Split docs into Documentation and API Reference tabs

[SPIKESPIGEL404]

Promotes the generated Cloud API reference out of the docs sidebar into its own top-level tab, so the docs nav reads Documentation | API Reference instead of seven sections in one flat list.

How the tabs work

Fumadocs derives layout tabs from page-tree folders marked "root": true. The tree root itself never qualifies — which is why the existing "root": true in content/docs/meta.json produced no tabs at all. Each tab therefore needs its own folder:

• content/docs/(guide)/ — Documentation
• content/docs/reference/ — API Reference

The parentheses make (guide) a folder group, which fumadocs strips from the URL. (guide)/overview/quickstart.md still publishes at /docs/overview/quickstart, so all six guide sections keep their paths and need no redirects.

Tab rendering needed no new code: the desktop strip in DocsHeader is already a port of fumadocs' LayoutHeaderTabs, and the sidebar renders the native tabs dropdown below lg. Both light up once the root folders exist.

CLI and MCP move to Documentation → Usage

They document how you drive BitRouter, not the Cloud REST surface. These URLs do change:

Old	New
/docs/reference/cli/*	/docs/usage/cli/*
/docs/reference/mcp	/docs/usage/mcp

Wildcard redirects added, placed above the broader /docs/reference rules that would otherwise swallow them. All verified returning 308.

Two generator fixes carry the most weight

Both would have reverted the refactor at build time, rather than failing loudly:

• generate-openapi.mjs rewrites reference/meta.json on every prebuild. It was emitting {title: "Reference", defaultOpen: false} and re-listing cli/mcp — dropping root: true deletes the tab. The section meta now comes from a REFERENCE_META constant, with a comment explaining why it must keep the flag.
• generate-cli.mjs still wrote to content/docs/reference/cli/, which would have resurrected the old pages as duplicates.

check-docs.mjs and generate-supported-tables.mjs also needed the new paths (the former was crashing on ENOENT).

Incidental fixes

• GitHub edit link and sitemap lastmod both rebuilt file paths from slugs. Neither survives a folder group, and both were already wrong for .md pages since they hardcoded .mdx. Now use page.path.
• Mobile header. The row overflowed at 375px, pushing the CTA over the search trigger — the wordmark now drops below sm. More significantly, DocsHeader replaces fumadocs' header wholesale and never rendered slots.sidebar.trigger. Below md the sidebar is a drawer, and that drawer is the only place the tabs dropdown lives, so the docs nav and the API Reference tab were unreachable on a phone. It now passes the native trigger through a new leadingSlot on WebHeaderBody.

Verification

• pnpm lint:docs passes (44 docs), pnpm test passes (83 tests)
• Full pnpm build prerenders 119 doc pages
• Re-running both generators reproduces reference/meta.json byte-identically, root: true intact, and does not recreate reference/cli/
• Browser-checked at 375 / 768 / 1440: tab strip on desktop, dropdown in the static sidebar at tablet, dropdown in the drawer on mobile
• Redirects return 308; all guide URLs unchanged

Note for review

The 67 file moves are recorded as pure renames (zero content change). Worth a look at whether (guide) is the name you want for the group — it shows up in file paths and the GitHub edit links, though never in a URL.

🤖 Generated with Claude Code