Compile public docs as locked Fumadocs workspaces

[davidkpiano]

Moves public Agent, Graph, and XState v6 alpha documentation from committed or central content to direct Fumadocs workspaces backed by immutable GitHub checkouts.

• reads Agent from statelyai/agent next
• reads Graph from statelyai/graph main
• reads XState v6 alpha docs from statelyai/xstate next
• publishes XState v6 under /docs/xstate/v6/..., separate from stable v5 /docs/*
• mounts core, React, Vue, Svelte, Solid, and Store docs into clean versioned routes
• records exact commits in docs-sources.lock.json
• reuses clean locked checkouts without requiring GitHub on repeat builds
• lets docs:watch opt into available sibling workspaces for immediate local edits
• preserves source paths, source-owned navigation, local doc links, locked GitHub links, and search indexing
• rewrites both dot-prefixed and bare relative workspace links
• shares README route and leading-title rules across compilation, navigation, and search
• derives matching non-blank titles after HTML preambles or from filenames
• supports source-wide notices and marks every XState v6 page as alpha
• gives source-owned sidebar section labels distinct typography from page links
• recursively includes mounted docs when source-owned meta.json navigation is absent
• retains snapshots for private statelyai/viz sources (SDK, CLI, MCP)
• removes obsolete Agent and Graph snapshots
• documents the lock, route, mount, and notice workflow and extends regression coverage

Companion Graph navigation metadata: statelyai/graph#30

Validation:

• node --test scripts/docs-sync.test.mjs (8/8, including offline cached sync, watcher paths, and mounted navigation fallback)
• syntax checks for sync, watcher, and search scripts
• Fumadocs MDX compilation
• Next.js production build (984 pages)
• local browser smoke tests for Agent, Graph, and XState v6 routes, root redirect, navigation, source/example links, cross-mounted framework links, search, alpha-notice scoping, light/dark rendering, and console errors

The local pnpm wrapper encounters this machine's ignored-build policy gate; running the same installed stage binaries directly passes.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 11, 2026 9:36pm

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 3 additional findings in Devin Review.

[devin-ai-integration]

🟡 Local edits to sibling documentation repos never show up in the watch workflow

The watch command points documentation compilation at the pinned downloaded copy of each external repository (getWorkspaceProjectCheckoutDir(...) at source.config.ts:33-36) even when it was told to use the developer's local copy, so edits made locally never appear.
Impact: Someone editing docs in a sibling checkout sees no change in the running site, and newly added local pages show up in the sidebar as links to missing pages.

Only the sync step honors DOCS_USE_LOCAL_WORKSPACES; the MDX compile step does not

scripts/docs-watch.mjs:55-59 runs scripts/docs-sync.mjs with DOCS_USE_LOCAL_WORKSPACES=1, which makes syncProject read from ../<repo> (scripts/docs-sync.mjs:1254-1258, scripts/docs-sync.mjs:1261-1309) and therefore generate lib/external-docs-nav.generated.ts from the local working tree. Immediately afterwards it runs pnpm exec fumadocs-mdx (scripts/docs-watch.mjs:60), which reads source.config.ts. There, workspace sources unconditionally resolve dir to .cache/docs-sources/<repo>/<locked commit>; no code path consults DOCS_USE_LOCAL_WORKSPACES (grep shows only scripts/docs-sync.mjs:1256 and scripts/docs-watch.mjs:57).

Result: navigation is derived from the local clone while page content is compiled from the locked commit. This contradicts README.md:177-178 ("pnpm docs:watch explicitly uses available sibling clones instead, so local workspace documentation edits appear immediately during development"), and any page that exists only locally yields a sidebar entry whose route has no compiled page.

---

Was this helpful? React with 👍 or 👎 to provide feedback.