Refactor docs nav: one CLI page, no AI Resources, four tabs

[SPIKESPIGEL404]

What

Three structural changes to the docs site, plus a build fix they surfaced.

1. The CLI reference is one page

content/docs/(guide)/usage/cli/ — ten generated pages plus a hand-authored hub — collapses into a single usage/cli.mdx, shaped like opencode's CLI reference: intro, global flags, then one ## section per command group with commands nested beneath as ###/####/#####.

scripts/generate-cli.mjs now emits the whole page. Overlays keep the same role, with one addition:

File	Supplies
cli-overlays/index.md (new)	page frontmatter + the intro (moved verbatim from the old hub page)
cli-overlays/<group>.md	title: → the ## section heading; prose → section intro; ## @<cmd> → per-command extras

The flag-hoisting is load-bearing, not just editorial. Flags every command accepts (-j/--json, --json, --human) now live in one ## Global flags table instead of repeating across 107 command tables. Without that, the page carries 733 table lines and OOMs the MDX compiler at a 12 GB heap — MDX compilation is superlinear in table rows, and a probe confirmed it's the rows specifically (3,205 lines of headings compile fine; 1,200 table rows do not). Hoisting drops it to 438 lines and the page builds.

2. AI Resources is dissolved

• skills.mdx → usage/skills.mdx, retitled Agent Skills
• the docs MCP server merges into usage/mcp.mdx as ## The docs MCP server, next to the origin server, with the "not the MCP gateway" section extended to distinguish all three roles
• the llms.txt page is retired

⚠️ Only the page is gone — /llms.txt and /api/docs/llms-full.txt still serve. Say the word if you want those retired too.

Usage now reads as the three ways to drive BitRouter: CLI, MCP Server, Agent Skills.

3. Integrations and Guides are top-level tabs

Both move out of the (guide) folder group to content/docs/, marked "root": true alongside Documentation and API Reference. URLs are unchanged — (guide) was already stripped from them.

Two fumadocs gotchas hit along the way:

• Integrations needed index in its pages list, or the tab resolved to /docs/integrations/models and /docs/integrations fell back to rendering under the Documentation tab.
• Guides has no index.mdx, so it needs a pagesIndex.

Icon polish

• usage/skills.mdx was the only page in the whole tree with a frontmatter icon: — a lone Box next to icon-less CLI and MCP Server siblings. Removed.
• Documentation was the only tab of four without an icon. Added BookOpen.
• integrations/index.mdx retitled Overview → Integrations, matching how reference/index.mdx is titled API Reference (it was the third "Overview" in that sidebar).

Redirects

Every retired URL has a 301 in next.config.ts. The ten CLI pages land on their section anchors:

From	To
/docs/usage/cli/daemon	/docs/usage/cli#daemon-lifecycle
/docs/usage/cli/misc	/docs/usage/cli#key-workflow-state-and-update
/docs/ai-resources/skills	/docs/usage/skills
/docs/ai-resources/mcp	/docs/usage/mcp#the-docs-mcp-server
/docs/guides	/docs/guides/cloud-api

(…and the rest — all twelve verified returning 308 to a live anchor.)

Section headings are now anchor targets that redirects depend on, so renaming one means updating next.config.ts. Noted in docs/CONTRIBUTING.md and AGENTS.md.

Verified

• pnpm build — clean, 107 docs pages prerendered
• pnpm test — 83 passing (footer-nav test updated for the new hrefs)
• pnpm lint:docs — 47 docs across 6 sections; check-docs.mjs updated for the moved sections, now covering hand-authored usage/ pages while exempting generated cli.mdx
• All four tabs render with their own sidebar; every redirect and anchor target checked in the browser

Not fixed here

A pre-existing React unique "key" prop warning in fumadocs' Sidebar — confirmed present on main before these changes.

🤖 Generated with Claude Code