feat(docs): migrate component documentation to Fumadocs MDX (#20)

* refactor(repo): scaffold Turborepo monorepo structure

Phase 1 of Fumadocs migration:
- Move entire app into apps/docs/
- Add Turborepo config with dev/build/lint tasks
- Add packages/config with shared tsconfig.base.json
- Add pnpm workspace config
- Create root package.json with workspace scripts
- Rename docs package to @jalco/docs
- Update husky for monorepo paths
- Verify build passes from new location

* feat(docs): add Fumadocs MDX infrastructure

Phase 2 of migration:
- Install fumadocs-core 16.6, fumadocs-mdx 14.2, fumadocs-ui (base-ui 16.6)
- Upgrade to Next.js 16.2, React 19.2, Zod 4
- Add source.config.ts for MDX collection definition
- Add lib/source.ts with Fumadocs page source loader
- Add mdx-components.tsx with Fumadocs defaults
- Wire createMDX into next.config.ts
- Create content/docs/ with meta.json sidebar ordering for all 28 components
- Create initial MDX pages: index.mdx, components/index.mdx
- Add fumadocs-mdx:collections path mapping to tsconfig
- Exclude .source/ from ESLint, suppress ignored-file warnings in lint-staged
- All 42 existing pages still build alongside Fumadocs

* feat(registry): add registry index generation for ComponentPreview

Phase 3: registry index for Fumadocs ComponentPreview, getRegistryComponent
helper, build pipeline wiring. Registry stays at registry/ — zero breakage.

* feat(docs): add Fumadocs catch-all route for MDX pages

Add app/docs/[...slug]/page.tsx that renders MDX content from
content/docs/ via Fumadocs. Explicit TSX pages take priority —
the catch-all only serves pages without a TSX counterpart. This
enables gradual migration: delete a TSX page, create the MDX,
and it works automatically.

* fix(docs): update sitemap to include Fumadocs MDX pages

Sitemap now merges routes from both the existing nav structure
and Fumadocs page source, deduplicating. As TSX pages are
migrated to MDX, the sitemap stays complete automatically.

* fix(docs): fix CodeBlockCommand hydration mismatch on React 19.2

Initialize package manager state with server-safe default, then
sync from localStorage in useEffect. The previous useState
initializer read localStorage during SSR which caused hydration
mismatches with React 19.2 / Next 16.

* feat(docs): first MDX component page — status-indicator

Prove the Fumadocs MDX pipeline end-to-end:
- ComponentPreview + ComponentPreviewClient for rendering in MDX
- InstallBlock wrapping existing InstallCommand
- Example components in registry/status-indicator/examples/
- Auto-discover examples in build-registry-index script
- status-indicator.mdx replaces the TSX page
- All 42 pages build successfully

* feat(docs): register all components as MDX components, full-fidelity status-indicator MDX

- Register all 28 registry components + docs infrastructure as MDX components
- Rewrite status-indicator.mdx to use ComponentDocsPage, VariantGrid,
  CodeLine, ApiRefTable — identical quality to the old TSX page
- Fix export names: StepperItem, LogViewerTerminal/Minimal/Filterable,
  TipJar variants
- Pattern proven: MDX pages can use the full docs component system
  with zero quality loss

* feat(docs): convert commit-graph and color-palette to proper MDX

Establish the correct MDX pattern:
- Example files in registry/<name>/examples/ for each preview
- Clean MDX with ComponentPreview, markdown code blocks, ApiRefTable
- No template literals or TypeScript in MDX body
- status-indicator, commit-graph, color-palette all working as MDX
- 25 TSX pages remaining to convert

* feat(docs): convert testimonial, logo-cloud, commit-graph, color-palette to MDX

4 components fully converted with example files + clean MDX.
24 TSX pages remaining.

* feat(docs): convert all 28 component pages to MDX

All TSX component docs pages are now MDX files in content/docs/components/.
Each uses ComponentPreview with the existing preview files — no new example
files needed for most components. Detailed examples exist for status-indicator,
commit-graph, color-palette, testimonial, and logo-cloud.

- 28 MDX files in content/docs/components/
- 0 TSX component pages remaining
- Registry index auto-discovers preview files as ComponentPreview targets
- All 41 pages build successfully
- Playground files restored to components/docs/playgrounds/

* feat(docs): switch sidebar to Fumadocs page tree

Replace the static lib/docs.ts sidebar with a Fumadocs-powered sidebar
that reads from the auto-generated page tree (MDX files + meta.json).
Keeps the existing visual design — spring animation, scroll indicator,
New badges from latest release. The sidebar now auto-discovers pages
from content/docs/ without manual nav configuration.

* feat(docs): proper MDX pages for all batch 1 components

Create example files and full MDX docs for:
- color-palette (grid + scale demos)
- license-badge (layouts + categories demos)
- repo-card (single + grid demos)
- contributor-grid (grid + list demo)

All 8 batch 1 components now have proper MDX pages with
ComponentPreview demos, API reference tables, and notes.
42 pages building successfully.

* fix(docs): restore tabbed Preview/Code view in MDX ComponentPreview

The MDX ComponentPreview now wraps the real ComponentPreview server
component which renders the tabbed Preview + Code panels with
syntax-highlighted source files. Previously it was a stripped-down
version showing only the live component with no code tab.

* feat(docs): restore AI copy + prompt buttons on component pages

The catch-all page now detects component pages and renders:
- CopyPromptButton with the full AI-friendly component prompt
- AiCopyButton with page summary for copying to AI destinations
- DependencyBadges showing npm and registry dependencies

These match the original ComponentDocsPage header behavior.

* fix(docs): correct component names in usage examples, tighten spacing

- Fix 13 auto-generated MDX pages that showed ApiRefTable instead of
  the actual component name in import/usage examples
- Reduce MDX content gap from gap-12 to gap-8 for tighter layout

* fix(docs): add static pages to sidebar, fix code blocks, correct component names

Sidebar:
- Add Getting Started section with Components, Installation, Color
  Themes, Releases as static links above the Fumadocs page tree
- All pages now accessible from the sidebar

Code blocks:
- Replace all markdown triple-backtick blocks with CodeLine components
  across 27 MDX files so they use the registry's syntax highlighting

Component names:
- Fix 13 auto-generated pages that showed wrong component names
  (ApiRefTable instead of the actual component) in usage examples

Cleanup:
- Rename changelog route to releases
- Tighten MDX content spacing (gap-12 → gap-8)

* feat(docs): enrich all 28 MDX pages with API Reference and Notes

Extract ApiRefTable blocks and Notes sections from old TSX pages
(recovered from git history) and append to all stub MDX pages.
Every component page now has:
- ComponentPreview with tabbed Preview/Code view
- InstallBlock with package manager tabs
- CodeLine usage examples
- API Reference table(s) with all props
- Notes section with component-specific details

19 pages enriched automatically + 1 manually (api-ref-table).
8 batch-1 pages were already rich.

* fix(docs): fix sidebar layout — remove Introduction, add category separators, tighten spacing

- Remove index.mdx from root meta so 'Introduction' doesn't show
  as a separate sidebar item
- Remove components/index from components meta (covered by static link)
- Flatten the Components folder into the sidebar so category
  separators (Code, Docs, Open Source, etc.) render directly
- Tighten sidebar gap from gap-6 to gap-1 with pt-5 on separators
  for clear visual grouping without excess whitespace
- Add pb-2 to Getting Started section for separation

* feat(docs): restore variant sections for kbd + stepper, update AGENTS.md

Kbd:
- Add Variants, Sizes, Examples, Color Schemes sections
- Import VariantGrid and registry components

Stepper:
- Add Examples section with status indicators, rich content,
  horizontal orientation, and custom icons

AGENTS.md:
- Document Fumadocs MDX docs workflow
- Require restoring showcase depth, not just structure
- Require Fumadocs page tree for sidebar changes

* feat(docs): restore variant sections for file-tree, json-viewer, log-viewer, request-viewer

File Tree:
- Add Examples section with icon styles, highlighted files, expand state
- Import FileTree and define sample tree data

JSON Viewer:
- Add Examples section with expanded depth and package manifest configs
- Import JsonViewer and define sample JSON data

Log Viewer:
- Add Variants section with Terminal, Filterable, and Minimal variants
- Import LogViewer components and define sample logs

Request Viewer:
- Add Examples section with GET and POST request samples
- Import RequestViewer and define network request data

* fix(docs): fix MDX syntax in file-tree, restore build

* feat(docs): restore variant sections for activity-graph, fix build

* feat(docs): restore variant sections for github-buttons, npm-badge, producthunt, tip-jar

* feat(docs): restore variant sections for cron-schedule, diff-viewer, ai-copy-button

* feat(docs): restore variant sections for code-block, code-block-command

* feat(docs): restore variant sections for code-line, producthunt, tip-jar, cron, diff, ai-copy, json, log, request, activity

* feat(docs): restore variant sections for api-ref-table, finish parity pass

* refactor(docs): revert complex TOC experiment, keep clean build

* feat(docs): add inline table of contents to docs pages

* feat(docs): widen page layout and move TOC to right sidebar

* feat(docs): increase page max-width and content width

* feat(docs): maximize content width and refine layout

* feat(docs): make content layout edge-to-edge

* feat(docs): expand global layout width and remove main content constraints

* fix(docs): correct nav link for releases

* fix(docs): resolve duplicate catch-all routes and cleanup

* fix(docs): resolve route conflicts and clean up duplicate folders

* fix(docs): restore optional catch-all for /docs home

* fix(docs): fix React 19 script console error

* feat(docs): migrate status-indicator to pure MDX

* chore(vercel): add configuration for monorepo structure

* chore(vercel): remove invalid vercel.json

* fix(docs): resolve remaining lint errors

* chore(repo): expose previews:generate at root

* chore(repo): register previews:generate task in turbo.json

* fix(ci): use pnpm check-types for type checking

* fix(ci): align root scripts with docs workspace tasks

* fix(ci): generate registry index before type checking

---------

Co-authored-by: Justin Levine <20596508+justinlevinedotme@users.noreply.github.com>

Author: jal-co

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
         run: pnpm previews:generate
 
       - name: Type check
-        run: pnpm exec tsc --noEmit
+        run: pnpm check-types
 
       - name: Registry build
         run: pnpm registry:build

.gitignore

@@ -1,24 +1,16 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-
 # dependencies
-/node_modules
-/.pnp
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/versions
-
-# testing
-/coverage
+node_modules
 
 # next.js
-/.next/
-/out/
+.next/
+out/
 
 # production
-/build
+build
+dist
+
+# turbo
+.turbo
 
 # misc
 .DS_Store
@@ -30,11 +22,11 @@ yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
 
-# env files (can opt-in for committing if needed)
+# env files
 .env*
 
-# registry build output (generated by `shadcn build`)
-/public/r/
+# registry build output
+**/public/r/
 
 # vercel
 .vercel
@@ -45,10 +37,13 @@ next-env.d.ts
 
 # local agent/tooling artifacts
 .agents/
-
 skills-lock.json
 bun.lock
-.env.local
 
-# Generated preview imports
-components/docs/__generated__/
+# Generated files
+**/components/docs/__generated__/
+**/registry/__index__.tsx
+**/.source/
+
+# lockfiles (regenerated)
+pnpm-lock.yaml

.husky/pre-commit

@@ -1 +1 @@
-pnpm exec lint-staged && pnpm exec tsc --noEmit
+cd apps/docs && pnpm exec lint-staged

AGENTS.md

@@ -243,6 +243,11 @@ A dev-only page at `/dev/screenshots` renders every component preview at full si
 ### Writing component docs
 
 - `.pi/references/docs-component-format-spec.md` MUST be followed as the canonical docs format guide for public component and block pages.
+- Public docs pages now live in the Fumadocs MDX source under `apps/docs/content/docs/**`. Agents MUST treat MDX as the default docs surface and MUST NOT reintroduce per-component TSX route pages unless explicitly requested.
+- For registry-backed component pages, agents MUST preserve the current docs shell behavior: tabbed Preview/Code rendering, AI copy actions, copy prompt actions, dependency badges, and install blocks.
+- When migrating or revising component docs, agents MUST restore showcase depth — not just structure. That means meaningful `Variants`, `Sizes`, `Examples`, `Configurations`, or other labeled sections whenever the old page or shipped component warrants them.
+- If a pre-migration docs page had multiple demos or variant sections, the migrated MDX page MUST keep equivalent coverage before the work is considered done.
+- Examples and demos for MDX pages SHOULD live in reusable files under `apps/docs/registry/<name>/examples/` when that materially improves readability, reuse, or MDX ergonomics.
 - Component doc descriptions MUST start with a concise one-sentence summary of what the component does.
 - Descriptions MUST NOT start with "A", "An", or "A React component for...".
 - Descriptions MUST NOT contain implementation details, subjective adjectives, or unnecessary jargon.
@@ -259,6 +264,7 @@ A dev-only page at `/dev/screenshots` renders every component preview at full si
 - When changing a public component's API, variants, states, or installation surface, all affected docs MUST be updated in the same change.
 - For public component changes, agents MUST check related docs pages, preview/demo files, homepage or showcase examples, usage snippets, and registry metadata.
 - Public variants MUST NOT be added or removed without verifying that labels, examples, and preview coverage still match the shipped component.
+- Sidebar/navigation changes in the docs app MUST use the Fumadocs page tree and `meta.json` conventions first. Agents MUST prefer fixing Fumadocs metadata/configuration over replacing the navigation system with custom hardcoded data.
 
 ## Releases