docs: rewrite the quickstart around bitrouter/auto and the optimize loop

[SPIKESPIGEL404]

⚠️ Do not merge yet

This documents a UX that is partly shipped and partly still being designed. It is opened for review of structure and framing, not to land. See Blocked on below.

What this does

Refocuses the quickstart on the hosted endpoint and ends it on the optimization loop, instead of walking through a static proxy setup. 240 → 179 lines (~880 words, for reference OpenRouter's quickstart is ~1,500).

The page now has one continuous arc: send bitrouter/auto → measure it on your own workflow → publish → the same model id routes differently for you.

Changes

• Dropped the Cloud-vs-self-host framing, the capability parity table, and the self-host walkthrough. Self-hosting is a card in Next steps. "Cloud" now appears twice on the page, both unavoidable (bitrouter cloud login, the cloud.bitrouter.ai console link).
• Four-tab onboarding strip matching the landing hero — CLI, MCP, Agent Skills, Wizard — replacing the old "Option A / Option B" split.
• bitrouter skills add removed (deprecated upstream) from the quickstart, usage/skills.mdx, and cli-overlays/skills.md.
• Protocol coverage surfaced. Tabs are now OpenAI SDK / Anthropic SDK / curl rather than three renderings of the same OpenAI call, plus a table of all four natively supported request formats. Neither comparison page mentions protocol support at all today — this is undersold site-wide.
• "Start optimizing" replaces the old adaptive-routing deep dive: what makes it different from swapping in a cheaper model, what review reports, how publishing feeds back into bitrouter/auto, and how cycles compound.
• Seven dead inbound links removed — the #adaptive-routing and #self-host-or-cloud anchors no longer exist.
• optimize setup no longer opens with a flag. Guided discovery landed in feat: guide @auto workflow optimization bitrouter#779, so the section leads with bare bitrouter optimize setup and keeps exact argv for the undiscoverable case.

Blocked on

Updated after bitrouter/bitrouter#777, #779, and #788 merged. The naming question this PR was originally challenged on is resolved in this PR's favour — see below.

Resolved

1. bitrouter/auto does not exist yet. Zero occurrences in bitrouter/bitrouter. It exists as of feat: publish bitrouter/auto as the router slug bitrouter#788. bitrouter/ is now a namespace BitRouter resolves itself, reserved end to end: Stage 0 claims the prefix before any provider lookup, and dist-helper registry validate rejects any catalog or provider model id underneath.

   Note that #779 briefly settled this the other way — it shipped @auto and stated "bitrouter/auto is not introduced as an alias", explicitly correcting this PR. #788 reversed that on the adoption argument this PR was making all along: vendor/auto is the convention the ecosystem already uses, so a config pointing at some other .../auto model needs one segment changed rather than a new syntax learned. No page change is needed here — the spelling on this branch was right.

2. bitrouter optimize is unmerged — feat(optimize): add agentic workflow loop bitrouter#777. Merged, and its UX revision landed in #779.

Still open

3. bitrouter/auto is a local resolution, and this page is hosted. This is now the central blocker and it is a genuinely new one. #788 implements the slug in the local daemon's Stage-0 resolver, against a locally-bound presets.auto and a signed policy-lock.yaml. Every code sample on this page sends model: "bitrouter/auto" to https://api.bitrouter.ai/v1 with a brk_ key — a different service, which does not implement it. The reserved-namespace rule also means bitrouter/auto can never arrive via the registry catalog the way every other id on the supported-models page does; if Cloud serves it, it has to be a Cloud-side routing feature. Needs a decision from whoever owns the cloud registry.

4. bitrouter/auto does not work on a fresh install. #788 deliberately shipped the spelling without a default policy: with no bound policy the request returns a 400 naming bitrouter optimize setup, rather than falling back to a default route. This page's "change three strings" promise assumes paste-and-go. Tracked for team decision in feat: decide whether bitrouter/auto should work on a fresh install bitrouter#787 — that issue exists precisely because this page's arc depends on the answer.

5. npx @bitrouter/agent is not on npm. Confirmed still 404 as of this update. bitrouter-agent states it is in development.

6. Publishing must feed back into bitrouter/auto. True for the local daemon after #788. Not true for the hosted endpoint, which is the one this page tells readers to call — same dependency as (3).

Known gaps

• review output is described, not shown. Showing a real captured block would be the strongest three lines on the page; I did not invent a terminal format. #779's merge-readiness gates include capturing verified terminal output from a clean-host walkthrough — that capture is the thing to paste here.
• optimize setup still needs a workflow command. Closed by guided discovery in #779; the page now leads with bare bitrouter optimize setup.
• bitrouter skills add survives in the CLI reference at content/docs/(guide)/usage/cli.mdx. That page is generated from .cli-snapshot.json and the snapshot still contains the command — it only disappears after pnpm snapshot:cli against a binary that has dropped it.
• Two different things are now called "optimize" — bitrouter optimize (worktree baseline/candidate with an ACP judge) and npx @bitrouter/agent optimize (reads bitrouter.db, proposes a tighter policy). The quickstart references both. Worth renaming one.
• The landing hero ships a broken command. components/landing/zed/hero-quickstart.tsx says bitrouter run claude-code; run is not in the CLI snapshot — the command is bitrouter launch. The docs use bitrouter launch claude. Not fixed here.

Follow-ups not in this PR

• An adaptive routing page for the content removed from the quickstart. It needs rewriting regardless: policy.mode: frozen|adaptive replaced writeback, policy lock/unlock were removed upstream, and key_strategy: legacy_fingerprint is now rejected in favour of agent_trace/v2|<state>|<risk>. #788's skills/bitrouter/references/adaptive-routing.md is a usable source for the reserved-namespace and error semantics.
• content/docs/(guide)/usage/configuration.mdx still documents writeback: locked|evolve.
• Collapsing BYOK / BYOM / model-sources into one "bring your own upstreams" concept.

Verification

• pnpm lint:docs passes (49 docs, 7 sections)
• pnpm generate:cli re-run after editing cli-overlays/
• Full internal-link sweep across all pages: 0 broken page targets or anchors
• All touched pages render 200 on the dev server

🤖 Generated with Claude Code

[SPIKESPIGEL404]

Updated the description against what actually shipped. Two things worth pulling out, because one is good news and the other is a new blocker that did not exist when this was opened.

The naming challenge resolved in this PR's favour. bitrouter/bitrouter#779 shipped @auto and explicitly said "bitrouter/auto is not introduced as an alias", listing this PR's spelling as speculative. bitrouter/bitrouter#788 has now reversed that and made bitrouter/auto the documented public slug, on the same adoption argument this page was built around. This branch needs no spelling change — bitrouter/auto was right.

The new blocker is hosted vs local. #788 implements the slug in the local daemon's Stage-0 resolver, against a locally-bound presets.auto plus a signed policy-lock.yaml. Every code sample on this page sends model: "bitrouter/auto" to https://api.bitrouter.ai/v1 — a different service that does not implement it. Two consequences:

1. The reserved-namespace rule in #788 means bitrouter/auto can never reach users through the registry catalog that generates the supported-models tables. If Cloud serves it, it has to be a Cloud-side routing feature, deliberately built.
2. The page's payoff sentence — after optimize publish, the same model id routes differently for you — holds for the local daemon and not for the hosted endpoint this page tells readers to call.

Neither is a docs bug; the page is describing an intended product and the product is half-built. But it does mean the merge gate for this PR is now a Cloud decision rather than an OSS one.

Separately, #788 shipped the slug without a default policy: with nothing bound, the request returns a 400 naming bitrouter optimize setup instead of falling back. That was a deliberate choice — a built-in default routes real tokens without operator review, which cuts against the frozen/signed design — but it does contradict this page's "change three strings" framing. bitrouter/bitrouter#787 is open for that decision specifically because this page's arc depends on the answer.

One content change pushed: optimize setup no longer opens with --workflow-command, since #779 shipped guided discovery. That closes the "most concrete instruction is a flag a five-minute-old reader does not have" gap this PR raised itself. pnpm lint:docs passes.