Document bitrouter.yaml and pivot to config-forward

[SPIKESPIGEL404]

Adds usage/configuration.mdx and moves the positioning from "no config to maintain" to config-forward.

Why

The declarative surface was undocumented. Coverage audit against content/docs/:

bitrouter.yaml block	Before
presets: (@name)	Concept covered, YAML key appears on zero pages
variants: (:name)	Same
routing: (sort / only / ignore / require_tags)	Same
policy_table:	Nothing. Zero pages.
policy: / policy-lock.yaml	Only quickstart + the CLI dump

Routing was documented API-first and console-first, so a reader who wanted routing in git had nowhere to land.

The page

usage/configuration.mdx — discovery order, the published JSON Schema, ${VAR} substitution, every top-level block, the policy table, the adaptive loop, and config validate in CI. Titled Configuration so it sits correctly beside CLI / MCP / Skills and doesn't overclaim (the file also holds server:, database:, mcp:), with Routing as code as the opening thesis and a named section anchor.

The differentiated claim is that the policy isn't inert. policy.writeback defaults to locked, so the router observes and proposes rather than writes; bitrouter policy evolve prints a dry-run and --apply publishes. You read the diff and commit it — the same review path as any other change. Adequacy escalation un-does downgrades that fail in production; exploration (off by default, and flagged as genuinely aggressive) finds safe downgrades instead of making you guess them. That's the part LiteLLM's config.yaml has no answer to, and it's exactly what had no docs.

The page owns the file; virtual-model.mdx and model-variants.mdx keep owning the behavior, so semantics aren't duplicated.

Positioning pivot

• migrate-from-tensorzero claimed "no schema to maintain" as an advantage. That was the old line and it was misleading regardless — there is a schema, it's published, and it validates in CI. Recast as a difference of degree: BitRouter is also configured as code, it just doesn't make you declare the shape of your application before you can route a request. The ClickHouse/no-database contrast is untouched, since that one is real.
• migrate-from-litellm mapped model_list onto "provider keys + routing presets" with no config file in sight. Both it and the fallback paragraph now point at the actual file.

A correction this surfaced

virtual-model.mdx said @name is a BitRouter Cloud namespace feature and that self-hosting gets models: instead. That's wrong. Verified against the binary:

$ bitrouter route "@fast" -c bitrouter.yaml
{"error":{"kind":"not_found","message":"no active provider declares model 'openai/gpt-4o-mini'",
          "context":["resolving model '@fast'"]}}

@fast resolved from the local presets: block and substituted the preset's model — it only failed because the test provider doesn't serve that model. presets: works self-hosted; Cloud adds the managed lifecycle (namespaces, enable/disable, the routing-presets endpoints), not the grammar. Separately, models: is a different feature — a named alias over an ordered endpoint chain, not invoked with @ — and the page conflated the two. Both fixed.

Verification

• Every YAML example on the page validates, assembled into one combined config and run against the real binary: valid: true, 2 presets, 1 variant.
• The documented validate contract is empirical, not inferred — exit 0 with counts; exit 1 with a line/column parse error; an unset ${VAR} reported under warnings and not fatal, which is what lets CI check shape without production keys.
• The schema at the URL the page gives contains every key documented, including all of policy_table and the explore_* block.
• pnpm lint:docs OK, 48 docs / 6 sections.
• All 13 outbound links return 200; all 5 anchors (#routing-as-code, #the-policy-table, #the-adaptive-loop, #validate-in-ci, and cli#policy) resolve.

One thing for a follow-up, in the other repo

The schema ships at dist/schema/bitrouter.config.schema.json and declares:

"$id": "https://bitrouter.dev/schema/v1.0.0-alpha.27/config.schema.json"

bitrouter.dev is NXDOMAIN — the domain doesn't resolve, and bitrouter.ai serves 404 there. This page therefore documents the raw GitHub URL, which is live and follows the pattern DEFAULT_REGISTRY_URL already uses for the registry. Worth either serving dist/schema/ from bitrouter.ai or changing the $id in helpers/dist-helper/src/schema.rs — a two-line fix that needs no infra.

🤖 Generated with Claude Code