Document the TUI as a usage surface

[SPIKESPIGEL404]

Adds usage/tui.mdx, and fixes a docs-contract trap found while writing it.

The TUI page

bitrouter tui shipped in v1.0.0-alpha.27 but has no page. Worse, it's half-promised: cli-overlays/harnesses.md already carries a ## @tui block and generate-cli.mjs lists tui in the group, but the generated page renders only launch and spawn — .cli-snapshot.json is still alpha.26, which predates the command. So the page titled "launch, spawn & tui" silently ships two of three.

This adds the concept page as a sibling of usage/mcp.mdx — the same split that page already has with the generated CLI reference. usage/ now reads as the three ways to drive BitRouter: CLI, MCP, TUI.

Structure follows the console's model, not a keybind dump. opencode's TUI page was the starting reference, but most of it doesn't transfer: its page is ordered input-first (@ file refs, ! bash, 17 slash commands) because its TUI is a text box. Ours has no composer anywhere — subagent panes are read-only by design. So the page leads with the ownership rule (sessions take your input, subagents never do), because no key makes sense before it. Its verb table carries a Reached from column rather than flattening three tiers — inline, leader, palette — into one list.

Facts come from apps/bitrouter/src/tui/, not TUI_SPEC_V3.md, which has drifted:

• the roster is a right-hand rail; the spec draws a single left rail
• Ctrl-C has three behaviours by pane kind and ownership, and never quits the console
• : reaches the palette only from a monitor pane — a session swallows it
• the fleet socket is #[cfg(unix)], so delegation degrades on Windows

The harness matrix is two independent columns: pi and openclaw are routed but get no fleet MCP tools; grok and agy get neither. A harness without those tools can host the orchestrator pane but can never spawn a subagent — the rail just stays empty, which is the failure that table predicts.

The lint fix

The authoring contract told writers to prefer > [!NOTE] blockquotes. That doesn't work here — source.config.ts registers only remarkGfm + rehypeSlug, so alerts render as a plain blockquote with a literal [!NOTE] visible. Nothing under content/ used the syntax, so nothing was broken in production; the contract just invited it, and lint:docs stayed green either way. The trap is that alerts do render in repo Markdown like CONTRIBUTING.md, because GitHub renders those itself.

Made <Callout> the only documented form and added a lint rule. Fenced examples still pass, so docs can document the form they forbid.

Two gaps closed while verifying:

• usage/ was excluded from linting outright. The exclusion exists for the generated usage/cli/ pages, but it was a level too coarse — hand-authored usage/mcp.mdx and usage/tui.mdx were never checked, so the new rule wouldn't have covered the page that surfaced this. Now lints usage/ and skips only the generated subtree.
• Line numbers were body-relative. splitFrontmatter drops the frontmatter and the blank run after it, so an alert on line 8 reported as :3. Pre-existing for the import/export check too; both now point at the real line.

Verification

• pnpm lint:docs — OK, 47 docs across 6 sections (was 45/5)
• pnpm test — 83/83
• Lint rule proven both directions: bare alert fails with exit 1 and a message naming the fix; fenced alert passes. Line numbers checked against known positions (:8, :7).
• Page rendered on the dev server: correct sidebar slot under Usage, full TOC, prev/next wires MCP Server → TUI → Model Fallbacks. ASCII diagram fits desktop and scrolls inside its own container at 375px with no page-level horizontal scroll. No console errors from the page.

Follow-up (not in this PR)

The bitrouter tui flag reference this page links to still doesn't exist. It appears with no further authoring once the snapshot is re-captured from an alpha.27+ binary — that needs a local upgrade and rewrites two committed generated files, so I left it out:

brew upgrade bitrouter && pnpm snapshot:cli && pnpm generate:cli

🤖 Generated with Claude Code