use original fumadocs styling for docs

[dimaMachina]

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: f13764c9b6c577f84dc0e3e93c178c2b4d265f76

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:22am
agents-manage-api	Ready	Preview	Comment	Dec 8, 2025 8:22am
agents-manage-ui	Error			Dec 8, 2025 8:22am
agents-run-api	Ready	Preview	Comment	Dec 8, 2025 8:22am

[claude[bot]]

Claude finished @dimaMachina's task —— View job

---

PR Review: Use Original Fumadocs Styling for Docs

I'll provide a comprehensive architectural and engineering review of this substantial PR.

Review Progress

• [x] Understand the scope and purpose of fumadocs styling changes
• [x] Analyze documentation structure and meta.json changes
• [x] Review CLI and core package modifications
• [x] Evaluate system-level architectural impacts
• [x] Check for consistency and pattern adherence
• [x] Assess customer-facing API and breaking change impacts
• [x] Provide final recommendations

---

Summary

This PR's title "use original fumadocs styling for docs" significantly understates its scope. This is actually a major platform upgrade encompassing:

• 180 commits across 100+ files
• 91K additions, 7K deletions
• 9 packages affected with major version bumps
• New model support (Claude Opus 4.5, GPT-5.1, Gemini 3 Pro Preview)
• Documentation restructuring with comprehensive meta.json organization
• New template projects (facts-project with Rune/Bitcoin components)
• CLI improvements including schema introspection utilities

Major Architectural Concerns

1. Scope Mismatch & Communication

Severity: High

• The PR title "fumadocs styling" is misleading for a major platform upgrade
• Recommendation: Update PR title/description to reflect actual scope (e.g., "Major platform upgrade: New models, docs restructure, template improvements")
• This creates challenges for:
  • Release planning and change management
  • Stakeholder communication
  • Risk assessment

2. Schema Introspection Pattern

Severity: Medium The new schema-introspection.ts utility introduces validation-based schema analysis:

function getRequiredFieldsFromValidation(schema: z.ZodType): string[] {
  try {
    schema.parse({});
    return [];
  } catch (error) {
    // Extract field names from validation errors
  }
}

Concerns:

• Performance: Triggering validation errors for introspection could be expensive in hot paths
• Fragility: Relies on error message structure that could change with Zod updates
• Alternative approach: Consider using Zod's internal schema walking capabilities or maintaining explicit field metadata

Recommendation: Document performance characteristics and consider caching results for frequently introspected schemas.

3. Model Configuration Expansion

Severity: Medium Adding bleeding-edge models (Claude Opus 4.5, GPT-5.1) without explicit availability/beta status:

const anthropicModels = [
  { label: 'Claude Opus 4.5', value: ANTHROPIC_MODELS.CLAUDE_OPUS_4_5 },
  // ...

Concerns:

• Customer expectations: Users may encounter API errors if models aren't generally available
• Error handling: No indication of beta/preview status in the UI

Recommendations:

• Add metadata for model availability status (beta: true, preview: true)
• Implement graceful fallback when preferred models are unavailable
• Consider environment-based model filtering for production vs development

4. Documentation Navigation Complexity

Severity: Medium-Low The new meta.json structure introduces nested navigation with section separators:

{
  "pages": [
    "overview",
    "---TUTORIALS---",
    "...tutorials",
    "---TYPESCRIPT SDK---"
  ]
}

Concerns:

• Maintainability: Requires manual synchronization between folder structure and navigation metadata
• Scalability: Adding new sections requires updates in multiple places

Recommendation: Consider implementing auto-generation of navigation structure from folder hierarchy with manual overrides only when needed.

Code Quality & Engineering Patterns

5. Test Coverage Improvements

Positive: The test updates show good attention to mocking and isolation:

vi.mocked(findUp).mockResolvedValue('/test/path/src/projects');

Recommendation: Ensure the new template projects (facts-project) have corresponding test coverage.

6. Component Pattern Consistency

Positive: New data components follow established patterns:

export const runeHolderStats = dataComponent({
  id: 'rune-holder-stats',
  name: 'RuneHolderStats',
  description: '...',
  props: { /* JSON Schema */ }
});

7. Dependency Management

Concern: Adding @hono/zod-openapi dependency without clear usage documentation.

Recommendation: Document the integration pattern and ensure it's consistently used across API generation.

Customer Impact Assessment

8. Breaking Changes Risk

Severity: Medium Nine packages with major version bumps suggest potential breaking changes, but changesets only mention "new models" and styling changes.

Critical Questions:

• Are there actual breaking API changes beyond new models?
• Do existing agents continue to work without modification?
• Are database migrations required?

Recommendation:

• Clearly document any breaking changes in upgrade documentation
• Provide migration guides for affected patterns
• Consider if some changes should be patch/minor rather than major

9. New Template Project Quality

Positive: The facts-project template shows sophisticated patterns with proper typing:

export const runeHolderStats = dataComponent({
  props: {
    $schema: 'https://json-schema.org/draft/2020-12/schema',
    // Detailed property definitions
  }
});

Recommendation: Ensure this template includes comprehensive documentation and examples.

Final Recommendations

Immediate Actions (Before Merge)

1. Update PR title/description to reflect true scope
2. Document breaking changes explicitly in changeset files
3. Add model availability status metadata
4. Performance test schema introspection utilities

Follow-up Actions

1. Create upgrade guide for major version bump
2. Add automated tests for new template projects
3. Consider implementing navigation auto-generation
4. Document new dependency usage patterns

Monitoring

1. Track model API errors after deployment
2. Monitor performance of schema introspection in production
3. Gather feedback on new documentation structure

Verdict

This is a well-executed major upgrade that expands platform capabilities significantly. The main concerns are around communication/scope clarity and ensuring proper customer migration support. The code quality is high and follows established patterns well.

Recommend: Approve after addressing communication/documentation concerns and confirming breaking change strategy.

---