Automatically update API reference for `manage-api` and API reference for `run-api`

[dimaMachina]

• [x] auto update API reference for manage-api

• [x] NEW API reference for run-api

• [x] updates all fumadocs dependencies

• [x] refactor all scripts from js to ts, thanks to --experimental-strip-types flag

• [x] polish README

• [x] refactor tailwind.config.mjs to ts

• [x] add "type": "module" in package.json to avoid specifying .mjs extension (like postcss.config.mjs)

• [x] pnpm generate-openapi and pnpm validate-link in prebuild script

• [ ] fix a lot of broken urls (should be done in another PR)

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 3092cf17ad10ea1860a2ef02a2841e02ffb54c6a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
agents-docs	Ready	Preview	Comment	Dec 8, 2025 8:35am
agents-manage-api	Ready	Preview	Comment	Dec 8, 2025 8:35am
agents-manage-ui	Ready	Preview	Comment	Dec 8, 2025 8:35am
agents-run-api	Ready	Preview	Comment	Dec 8, 2025 8:35am

[claude[bot]]

Claude finished @dimaMachina's task —— View job

---

Code Review Analysis

I'll provide a comprehensive review of this PR which appears to be a significant refactoring of the API documentation generation system.

Todo List:

• [x] Analyze overall PR scope and architectural changes
• [x] Review TypeScript migration (.mjs → .ts conversion)
• [x] Examine OpenAPI documentation generation changes
• [x] Evaluate package.json and dependency updates
• [x] Check navigation and content structure changes
• [x] Review deleted files and their impact
• [x] Assess potential breaking changes and missing functionality
• [x] Provide architectural feedback and recommendations

---

🏗️ Overall Assessment

This PR represents a well-executed modernization of the documentation infrastructure with significant architectural improvements. The changes demonstrate thoughtful engineering decisions that address scalability, maintainability, and developer experience.

✅ Strengths

1. Smart Migration Strategy

• Clean conversion from .mjs to .ts scripts with proper typing
• Removal of the massive index.json file (21,513 lines) in favor of dynamic generation
• Uses Node.js --experimental-strip-types for direct TypeScript execution

2. Improved OpenAPI Architecture

// agents-docs/src/lib/openapi.ts:6-8
input: () => ({
  index: 'https://agents-manage-api.preview.inkeep.com/openapi.json',
  'run-api': 'https://agents-run-api.preview.inkeep.com/openapi.json',
}),

• Generates docs from live endpoints rather than static files
• Supports multi-API documentation (manage-api + run-api)
• Leverages fumadocs-openapi for consistent generation

3. Enhanced Build Process

// agents-docs/package.json:17-20
"generate-openapi": "node scripts/generate-openapi-docs.ts --experimental-strip-types",
"generate-classnames": "node scripts/generate-classnames.ts --experimental-strip-types",
"prebuild": "pnpm generate-classnames",
"validate-link": "node scripts/validate-link.ts --experimental-strip-types"

• Automated documentation generation integrated into build pipeline
• Proper prebuild hooks ensure docs are current

4. Dependency Management

• Updated to modern React 19.2.0 and Next.js 16.0.3
• Consolidated fumadocs dependencies to compatible versions
• Added proper typing with schema-dts for structured data

---

⚠️ Areas for Consideration

Critical: Environment Dependency Risk

Issue: The OpenAPI generation depends on preview URLs being accessible:

'https://agents-manage-api.preview.inkeep.com/openapi.json'
'https://agents-run-api.preview.inkeep.com/openapi.json'

Concerns:

• Build failures if preview deployments are down/inaccessible
• Documentation staleness if preview schemas differ from production
• CI/CD brittleness in environments without preview access

Recommendations:

// Consider fallback strategy
input: () => ({
  index: process.env.MANAGE_API_OPENAPI_URL || 'https://agents-manage-api.preview.inkeep.com/openapi.json',
  'run-api': process.env.RUN_API_OPENAPI_URL || 'https://agents-run-api.preview.inkeep.com/openapi.json',
}),

Medium: Documentation Coverage Gaps

The generated run-api.mdx is notably sparse:

# agents-docs/content/docs/api-reference/run-api.mdx:5
toc: []

Questions:

• Is this expected for the run-api?
• Should there be more comprehensive endpoint documentation?
• Are authentication examples missing?

Medium: Error Handling & Recovery

generate-openapi-docs.ts lacks robust error handling:

// agents-docs/scripts/generate-openapi-docs.ts:21
main().catch(console.error);

Suggestions:

• Add network timeout handling
• Implement retry logic for API failures
• Provide clear error messages for debugging
• Consider graceful degradation when APIs are unavailable

Low: Type Safety Improvements

sidebar/transform.ts uses loose typing:

// agents-docs/src/components/sidebar/transform.ts:4
export const transformItems = (group: any) => {

Consider stronger typing:

interface NavigationGroup {
  group?: string;
  icon?: string;  
  pages: (string | NavigationItem)[];
}

export const transformItems = (group: NavigationGroup) => {

---

🎯 Architectural Strengths

1. Separation of Concerns: Clean separation between generation scripts and runtime code 2. Dynamic Content: Live API schema fetching ensures documentation accuracy 3. Modern Toolchain: Leverages latest fumadocs capabilities and TypeScript features 4. Build Integration: Proper integration with existing build processes

---

🚀 Recommendations

Immediate (Pre-merge)

1. Add environment variable support for OpenAPI URLs
2. Implement retry logic in generation scripts
3. Document the new build process in README

Short-term

1. Add comprehensive error handling to generation scripts
2. Strengthen TypeScript typing throughout the codebase
3. Consider offline fallbacks for critical build scenarios

Long-term

1. Monitor documentation build reliability in production
2. Consider API versioning strategy for backward compatibility
3. Evaluate caching strategies for frequently accessed schemas

---

📊 Impact Assessment

• ✅ No Breaking Changes: Navigation structure preserved
• ✅ Improved DX: Better typing and tooling
• ✅ Reduced Bundle Size: Eliminated massive static JSON file
• ⚠️ Build Dependencies: New external API dependencies
• ⚠️ Runtime Reliability: Dependent on preview environment stability

This is a well-architected refactoring that modernizes the documentation infrastructure. The primary risk is build-time dependency on external APIs, which should be mitigated with proper fallback strategies.

[github-actions[bot]]

:mag_right::speech_balloon: Inkeep AI search and chat service is syncing content for source 'Inkeep Agent Framework Docs'