Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs: record the availability spelling rule and the route-table gate's blind spots
Jack Rudenko8dfcfb79646e
diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.mdindex 88140201..ff330179 100644--- a/ai-docs/architecture/routing.md+++ b/ai-docs/architecture/routing.md@@ -75,7 +75,8 @@ project rules and nothing else.window, then provider name.3. **Append the fallback hop** (below).4. Credential filter (unchanged).-5. Availability filter (unchanged) — only a POSITIVE "not-served" removes anything.+5. Availability filter — only a POSITIVE "not-served" removes anything, and it asks each+ provider in that provider's own spelling (see below).6. Primary + fallbacks.**No catalog means local only.** With no readable catalog a bare name returns a no-route naming@@ -93,6 +94,41 @@ Each claim's namespace is ALSO owned by a metered sibling defined EARLIER inauto-detection unchanged — two claimants on one namespace is now fine, because the functionthat picked a single winner (`getProviderForModel`) no longer exists.+**The availability filter must ask in the provider's OWN spelling.** A provider that encodes+knobs into its model ids never lists a bare canonical id: Devin's dynamic models catalog holds+`swe-1-7`, `swe-1-7-medium` and `swe-1-7-lightning`, never `swe-1.7`. Its transport maps the+requested name onto one of those through `expandSelection` (`providers/model-resolvers/`) when+it sends. `providerServesModel` therefore resolves through the same resolver BEFORE comparing,+so the filter and the transport answer the same question. Until 2026-09-23 it compared the raw+string, answered "not-served" for every canonical id Devin carries, and "not-served" is the one+verdict allowed to remove a candidate: a bare `swe-1.7` lost its Devin hop and went to the+OpenRouter fallback ("swe-1.7 is not a valid model ID"), and the explicit `[email protected]` was+refused outright, since `routeExplicit` runs the same check. A provider with no registered+resolver gets its id back unchanged, so this costs every other provider nothing. A new+knob-encoding provider needs a resolver entry, or the filter will deny it by spelling.++## Changing anything that decides a chain: the route-table gate++A passing suite does not show a routing change is safe. It asserts the routes someone thought to+write down, and a silent removal hides in the ones nobody did.+`scripts/route-table-snapshot.ts capture|diff` pins the resolved chain of EVERY catalog model+through the real `route()`, before and after, and classifies each difference. Capture before the+change; after is too late. Both snapshots must be on the same catalog generation.++The gate has two measured blind spots, and a clean diff means "nothing changed for the models+this machine can see", never "nothing changed":++- **Credentials.** It runs on this machine's keys. Filtering virtual providers out of the gatherer+ removed `native-anthropic` from every `claude-*` chain, and the diff reported nothing, because+ this machine sets no `ANTHROPIC_API_KEY` and the hop was already being dropped. Two routing tests+ that set the key caught it.+- **Scope.** It walks catalog models only. The Devin spelling fix above changed routing for names+ a dynamic subscription serves and the catalog does not publish, and the catalog held no `swe-*`+ model at all, so the diff showed no change. The reproduction was the evidence.++Run the suite as the complement: the gate covers breadth the suite cannot, and the suite covers+credential states and non-catalog names the gate cannot.+## Default Provider Configuration (v7.0.0+)`defaultProvider` names the **fallback hop** — the last position in a gathered chain. It is adiff --git a/ai-docs/release.md b/ai-docs/release.mdindex 3ce98383..cd7b2670 100644--- a/ai-docs/release.md+++ b/ai-docs/release.md@@ -125,9 +125,12 @@ Two constraints hold regardless of who authorises:shared with the main checkout and every sibling worktree. Never `git stash`during a release; use a WIP commit.-TODO — not settled by detection, and worth answering on the next release:-- whether a failed magmux download from `MadAppGang/magmux` should block a release- or pin to a known-good magmux tag instead of `latest`.+SETTLED 2026-09-23 — the magmux source. The build keeps downloading the LATEST+release of `MadAppGang/magmux`; it is not pinned to a known-good tag. A failed+download, or a latest release missing a platform asset, BLOCKS the release: the+build job fails before anything publishes, which is the intended behaviour and+needs no workflow change. Decided by the repository owner when asked during the+v10.0.2 release. Preflight checks it by listing the latest release's assets.SETTLED 2026-09-15 — the two `displayWidth` tests in`packages/cli/src/tui/viz/color.test.ts`. They were NOT flaky and must NOT be