Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs: retire roster, and rebuild a safety argument on its new premise

Jack Rudenkoe95b8a51a552
diff --git a/ai-docs/architecture/README.md b/ai-docs/architecture/README.md
index 8c5f1435..98c37e1f 100644
--- a/ai-docs/architecture/README.md
+++ b/ai-docs/architecture/README.md
@@ -17,7 +17,7 @@ three earlier write-ups this material cites were lost.
| Document | What it covers | Read it before you… |
|---|---|---|
-| [`routing.md`](routing.md) | The `provider@model` syntax, the full provider-prefix table, local models, where a bare name's chain comes from now that there is NO built-in rules table, the fallback hop and its three empty states, `ModelCatalogResolver` vendor-prefix resolution, the DERIVED picker roster, and why subscription pricing is decided by billing rather than by `modelDiscovery` | change `routeBare`, `route-candidates.ts`, a `nativeModelPatterns` claim, `defaultProvider`, the picker, a catalog resolver, or `SUBSCRIPTION_PROVIDERS` |
+| [`routing.md`](routing.md) | The `provider@model` syntax, the full provider-prefix table, local models, where a bare name's chain comes from now that there is NO built-in rules table, the fallback hop and its three empty states, `ModelCatalogResolver` vendor-prefix resolution, the DERIVED picker provider list, and why subscription pricing is decided by billing rather than by `modelDiscovery` | change `routeBare`, `route-candidates.ts`, a `nativeModelPatterns` claim, `defaultProvider`, the picker, a catalog resolver, or `SUBSCRIPTION_PROVIDERS` |
| [`providers/devin.md`](providers/devin.md) | The only binary wire in the pipeline — Connect envelopes carrying protobuf, live uid resolution, errors that ride an HTTP 200, and the three wire facts that cost real money to get wrong | touch `providers/devin/`, the codec, or `dv@` model resolution |
| [`providers/grok-subscription.md`](providers/grok-subscription.md) | `gk@` on a SuperGrok / X Premium+ plan: RFC 8628 device flow, exact-scope matching, 6-hour token refresh with write-back, three mandatory client headers | touch `gk@`, `claudish login grok`, or its OAuth refresh |
| [`providers/antigravity.md`](providers/antigravity.md) | Gemini on an Antigravity subscription: the shared `agy` keychain token, runtime client-secret extraction, live served-set discovery | touch `ag@`, `auth/antigravity-*`, or the keychain token |
diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.md
index 1cc50cc6..bf7e01eb 100644
--- a/ai-docs/architecture/adapters.md
+++ b/ai-docs/architecture/adapters.md
@@ -60,7 +60,7 @@ inefficiency, so a shared value is not expected to fail, but it is less precise.
`OpenCodeZenTransport` sends `User-Agent: claudish/<version>` beside the session
id. OpenCode's docs ask a client to identify itself "rather than a generic SDK or
HTTP-library name", and this relay enforces it: `providers/model-discovery.ts`
-records that a UA-less roster request to Zen Go answers `403 error code: 1010`,
+records that a UA-less discovery request to Zen Go answers `403 error code: 1010`,
Cloudflare's browser-integrity block, while the identical request carrying one
returns 200 with 26 models (measured 2026-08-18). The chat path sits behind the
same edge and went without a UA until 2026-09-15.
@@ -203,7 +203,7 @@ that to 3/3.
`openai-sse.ts` calls `extractToolCallsFromText` (`handlers/shared/tool-call-recovery.ts`)
at finalization. That function scrapes tool calls out of assistant PROSE, for local models
that cannot emit structured `tool_calls` at all. It is the only production caller, so this
-path is exactly the `openai-sse` roster: GLM, Kimi, Grok, DeepSeek, Qwen, OpenRouter, LiteLLM.
+path is exactly the `openai-sse` provider list: GLM, Kimi, Grok, DeepSeek, Qwen, OpenRouter, LiteLLM.
Three properties are not obvious from the source and each one shipped as a defect
(v7.68.0, `ai-docs/reports/grok-tool-name-mangling-20260827.md`):
diff --git a/ai-docs/architecture/advisor.md b/ai-docs/architecture/advisor.md
index 92c76dbd..f53469b4 100644
--- a/ai-docs/architecture/advisor.md
+++ b/ai-docs/architecture/advisor.md
@@ -279,7 +279,7 @@ The startup notice says which, and warns when an inherited value reads as false.
catalog. The published catalog path (`CLAUDE_CODE_MODEL_CATALOG_URL`) feeds a different accessor
and does not supply it. No foreign model can earn a rank, and the table changes on every Claude
Code release. Never copy it into claudish: conditioning the variable on rank would mean
-duplicating that roster, which CLAUDE.md forbids. claudish sets the variable unconditionally
+duplicating that table, which CLAUDE.md forbids. claudish sets the variable unconditionally
under `--advisor` instead.
The advisor model itself must still be configured on the Claude Code side (`advisorModel` in
diff --git a/ai-docs/architecture/behavior-layer.md b/ai-docs/architecture/behavior-layer.md
index 0c5ac690..22327395 100644
--- a/ai-docs/architecture/behavior-layer.md
+++ b/ai-docs/architecture/behavior-layer.md
@@ -32,7 +32,7 @@ Rules **return** actions; the engine applies them. Nothing else in the layer mut
| `anthropic-sse` | MiniMax, Kimi direct, Z.AI | Byte-level passthrough, so interception is strictly opt-in: only a named tool has its `input_json_delta` frames withheld and rewritten. Verified byte-identical output for untargeted tools. |
| `gemini-sse` | Gemini | No buffering needed — Gemini delivers each `functionCall` with complete `args` in one part. Uses `repairToolArgs`, deliberately separate from the pre-existing `onToolCall` thought-signature hook. |
| `ollama-jsonl` | Ollama local | Not wired — this parser has no tool-call handling at all. |
-- **Off for native Claude** (`claude-*` or provider `anthropic`) — a naming rule, not a pinned roster.
+- **Off for native Claude** (`claude-*` or provider `anthropic`) — a naming rule, not a pinned model list.
- **Anchors live in `harness.ts` only.** `PLAN_MODE_HINT` is a cheap pre-test and **must stay a superset of the anchors** — an earlier version omitted "create your plan at" and short-circuited a valid anchor away. Never assume `~/.claude/plans`: CC has a `planDir` setting, so the path is always taken from the reminder.
## Why the layer is a SUPERVISOR, not a hint system
diff --git a/ai-docs/architecture/headless-vs-interactive.md b/ai-docs/architecture/headless-vs-interactive.md
index 4cb1546f..0eec12ef 100644
--- a/ai-docs/architecture/headless-vs-interactive.md
+++ b/ai-docs/architecture/headless-vs-interactive.md
@@ -208,9 +208,9 @@ to be asked: claudish's team children already spawn with `-y`.
lesson `team-capture.md` records for output: exit 0 proves nothing, which is why
`require_pattern` exists. Argument handling has the same hole.
- **Validate at the claudish boundary when the child will not.** `agent-availability.ts` does
- this for `--agent`: it discovers the roster live (`claude --agent <sentinel> -p`, ~0.5s, no API
- call, no tokens), caches it PER CWD because the roster is cwd-dependent (24 names in this repo,
- 5 in `/tmp`), and fails OPEN when the roster cannot be determined — blocking every session
+ this for `--agent`: it discovers the agent names live (`claude --agent <sentinel> -p`, ~0.5s, no
+ API call, no tokens), caches them PER CWD because that list is cwd-dependent (24 names in this
+ repo, 5 in `/tmp`), and fails OPEN when the list cannot be determined — blocking every session
because a probe broke would be a worse failure than the one it guards.
- **Prefer magmux over `-p`** for anything where a silent behavioural difference would corrupt
the result rather than merely degrade it.
diff --git a/ai-docs/architecture/keychain.md b/ai-docs/architecture/keychain.md
index 428cfedb..50ab1969 100644
--- a/ai-docs/architecture/keychain.md
+++ b/ai-docs/architecture/keychain.md
@@ -132,7 +132,7 @@ child already owned the *file descriptor*, and the write happened in another pro
`execFileSync` ever threw.
Shipped in `auth/antigravity-token.ts`'s `defaultReadStore` up to v9.0.7. The config TUI rebuilds
-its provider roster on every render and each rebuild calls `hasSharedAntigravityToken()`, so the
+its provider list on every render and each rebuild calls `hasSharedAntigravityToken()`, so the
two memos only collapse a burst — one spawn, and one leaked line, still got through every
`HAS_TOKEN_TTL_MS` (5 s) for as long as the view was open. claudish shares a terminal with the
Claude Code TUI, so the result was a display corrupted every five seconds for any user not signed
diff --git a/ai-docs/architecture/mcp-channel.md b/ai-docs/architecture/mcp-channel.md
index 67ef541e..57972d73 100644
--- a/ai-docs/architecture/mcp-channel.md
+++ b/ai-docs/architecture/mcp-channel.md
@@ -190,7 +190,7 @@ and `get_diagnostics` hands these records to an agent.
`list_sessions`, `get_diagnostics`
`preflight` exists because `--probe` is CLI-ONLY. An MCP consumer had no way to
-check a roster before committing to it, so it either shelled out to the CLI or
+check its models before committing to them, so it either shelled out to the CLI or
discovered provisioning failures minutes in with the slots already spent — a real
`team` run lost 3 of 10 slots that way. It reports, per model, WHICH provider
would serve it (via `route()`, the same rules and credential filter a real run
@@ -200,7 +200,7 @@ of the PROVIDER, not the model, so the same bare name can be free through a plan
or billed per token depending on which credential is present — which is precisely
what a caller cannot see from the model id.
-The roster is pinned by an EXACT frozen array in `channel/e2e-channel.test.ts`, so
+The tool list is pinned by an EXACT frozen array in `channel/e2e-channel.test.ts`, so
adding or removing a tool without updating that test fails CI. That is deliberate:
it is a wire contract, and an accidental change to the tool surface should be loud.
@@ -309,7 +309,7 @@ Five files: scrollback-buffer, session-manager, stream-json-reducer, e2e-channel
`session-manager.test.ts` carries seven mutation-proven regression guards, G1–G7: the timeout's status, the module-load signal exit codes (143/130), the reserved-flag rejection, the `--verbose`-before-`--quiet` argv order with a valueless `-p`, the delta firehose never reaching scrollback, and a promptless session reaching a usable state. Its fixtures replay real captured Claude Code 2.1.239 frames (`test-helpers/captured-stream-json.ts`), and its child (`test-helpers/fake-channel-stream-json.ts`) speaks bidirectional stream-json.
-**The tool roster is pinned twice, and adding a tool must break both.** `e2e-channel.test.ts` freezes the full 13-name list and the channel-only 6, deliberately: the roster is a wire contract and an accidental change to it should be loud. `get_diagnostics` broke both pins on the way in, which is the guard working.
+**The tool list is pinned twice, and adding a tool must break both.** `e2e-channel.test.ts` freezes the full 13-name list and the channel-only 6, deliberately: that list is a wire contract and an accidental change to it should be loud. `get_diagnostics` broke both pins on the way in, which is the guard working.
E2E tests use `--strict-mcp-config --bare --dangerously-skip-permissions` for isolation. SessionManager tests point child spawns at the tree under test via `CLAUDISH_BIN` (`spawn-claudish.ts`), never at the installed binary.
diff --git a/ai-docs/architecture/predefined-endpoints.md b/ai-docs/architecture/predefined-endpoints.md
index 3b1d2c78..ed412322 100644
--- a/ai-docs/architecture/predefined-endpoints.md
+++ b/ai-docs/architecture/predefined-endpoints.md
@@ -10,7 +10,7 @@ A **predefined endpoint** is a `customEndpoints` entry that ships inside the pac
## Activation is gated on a LOCALLY-PRESENT credential
-A row registers only when its key is already in `process.env`, one of its aliases, or `config.apiKeys`. Not because 25 dead providers would be untidy — because registration is what makes a provider visible at all. `buildProviderDefinition` sets `shortcuts: [name]`, and both the picker roster and the `@prefix` alias table are DERIVED from that, so registering unconditionally would pollute the `@prefix` namespace and its partial-match resolver with vendors that cannot serve a request, and would cost one async credential resolution per row per picker open — each able to open a 1Password handshake on a machine where concurrent handshakes are arbitrated globally and a burst of denials trips a 15-second machine-wide suppression.
+A row registers only when its key is already in `process.env`, one of its aliases, or `config.apiKeys`. Not because 25 dead providers would be untidy — because registration is what makes a provider visible at all. `buildProviderDefinition` sets `shortcuts: [name]`, and both the picker's provider list and the `@prefix` alias table are DERIVED from that, so registering unconditionally would pollute the `@prefix` namespace and its partial-match resolver with vendors that cannot serve a request, and would cost one async credential resolution per row per picker open — each able to open a 1Password handshake on a machine where concurrent handshakes are arbitrated globally and a burst of denials trips a 15-second machine-wide suppression.
Which is why the question is asked with `hasLocalApiKey()` — env → aliases → `config.apiKeys`, **sync**, structurally unable to reach the SDK. Not `credentials.isAvailable()`: a bundled row is not in the authority's map until `registerEndpoint` puts it there, so that call answers `false` for every row and the catalog would never activate at all.
@@ -135,7 +135,7 @@ Every row carries `evidence` and it is never read at run time; it exists for the
- It is **strong evidence about ROUTING** — that `baseUrl + apiPath` reaches a live endpoint which authenticates, and that the configured path is the vendor's real one rather than a catch-all. The sibling-path comparison is what buys that: a bogus sibling answering differently proves the route resolved. It exists because pass 1 ("401/403 with a JSON `error` object?") produced four false negatives, and because a status alone proves nothing about a route.
- It is **weak evidence about the vendor's STREAMING DIALECT.** A 401 says nothing about SSE chunking, tool-call encoding, `finish_reason` vocabulary or error-body shape on a successful turn. Those remain untested per vendor until someone holding each key runs a turn.
-`GET /v1/models` is **never** evidence here: Alibaba's `coding-intl` roster endpoint returns its full list to a bogus key and to no key at all.
+`GET /v1/models` is **never** evidence here: Alibaba's `coding-intl` discovery endpoint returns its full list to a bogus key and to no key at all.
**The LAYER itself is verified end to end, live.** A shipped catalog row (`tuningengines`, whose `apiPath` is byte-identical to OpenAI's) was pointed at `https://api.openai.com` via its own `TUNING_ENGINES_BASE_URL` override with a real key, and produced correct model output through the whole path — catalog → credential gate → compile → collision check → runtime registration → explicit `provider@model` routing → `OpenAIProviderTransport` → SSE parse → stdout — with no source change. The invisible-without-a-key gate, the malformed-override refusal and the placeholder-is-unset rule were confirmed on real traffic at the same time. Transcript, debug-log line numbers and the exact wire URL: `ai-docs/reports/predefined-endpoints/live-run.md`. That run proves the mechanism for every row; it proves the DIALECT of none of them, including Tuning Engines' own (the row was deliberately pointed away from its vendor).
@@ -145,12 +145,14 @@ Two rows (`parasail`, `writer`) return non-OpenAI error shapes and say so in `ev
## No model data, ever (R7)
-The schema is `.strict()` and has no `models`, `contextWindow`, `maxOutputTokens`, `pricing`, `capabilities` or `modelDiscovery` field, so a future contributor cannot add one by accident — an unknown key is a parse error, not a silently ignored field. A shipped roster is exactly the hardcoded model data this project forbids: it rots the moment a vendor adds a model, and the failure shape is claudish refusing a model that actually works. So a catalog vendor gets a **free-text model prompt** in the picker rather than a list. Model metadata comes from models-index or is absent.
+The schema is `.strict()` and has no `models`, `contextWindow`, `maxOutputTokens`, `pricing`, `capabilities` or `modelDiscovery` field, so a future contributor cannot add one by accident — an unknown key is a parse error, not a silently ignored field. A shipped model list is exactly the hardcoded model data this project forbids: it rots the moment a vendor adds a model, and the failure shape is claudish refusing a model that actually works. So a catalog vendor gets a **free-text model prompt** in the picker rather than a list. Model metadata comes from models-index or is absent.
## The caveat: activation infers intent from an ambient env var
A user who exported `PERPLEXITY_API_KEY` for some unrelated tool silently gains a claudish provider they never asked for. That is real, and it is stated rather than argued away.
-It is acceptable for one specific reason: **nothing claudish ships puts a catalog row in a bare-name routing chain.** No row declares `nativeModelPatterns` (the schema has no such field), none owns a legacy prefix, and none appears anywhere in `DEFAULT_ROUTING_RULES` — all three are pinned by `predefined-containment.test.ts`, the third because it is the one a future contributor can open with a single well-meaning edit ("`llama-*` should try Groq first"). So a row is reachable only by typing `perplexity@model` — the same explicit-access rule Devin and Alibaba Token Plan already follow, for the same reason. The cost of the wrong inference is therefore one extra row in a picker, never a request billed to a provider the user did not choose.
+It is acceptable for one specific reason: **nothing claudish ships puts a catalog row in a bare-name routing chain.** No row declares `nativeModelPatterns` (the schema has no such field), none owns a legacy prefix, and none is bound to a catalog route in `CATALOG_ROUTE_BINDINGS` — all three are pinned by `predefined-containment.test.ts`.
+
+The third clause carries the weight now, and it changed shape when the hand-written routing table was deleted (2026-09-22). The old argument was that no row appeared in `DEFAULT_ROUTING_RULES`; routing no longer reads a table at all, so the property rests on the BINDING instead. Gathering only proposes a provider that some catalog connection resolves to, which means an unbound row cannot be proposed for any model, by any name, ever. `together` and `fireworks` are the deliberate counter-examples: both ship as bundled rows AND are bound, because they are real gateways the catalog maps — activating one is the user naming it, the same explicit act as typing the prefix. So an unbound row is reachable only by typing `perplexity@model` — the same explicit-access rule Devin and Alibaba Token Plan already follow, for the same reason. The cost of the wrong inference is therefore one extra row in a picker, never a request billed to a provider the user did not choose.
The one qualification, stated because the absolute version is false: `route()` appends `defaultProvider` to EVERY bare chain, so a user who sets `"defaultProvider": "groq"` really does put a catalog row in bare chains. That is explicit user action naming the vendor, not a silent path, so the safety argument survives — but "can never" does not. If a catalog row ever becomes bare-name reachable WITHOUT the user naming it, this gate has to be revisited, because the inference would then be able to move money.
diff --git a/ai-docs/architecture/providers/antigravity.md b/ai-docs/architecture/providers/antigravity.md
index 4c66e81f..d28f109d 100644
--- a/ai-docs/architecture/providers/antigravity.md
+++ b/ai-docs/architecture/providers/antigravity.md
@@ -41,7 +41,7 @@ daily-cloudcode-pa.googleapis.com generate gemini-3.6-flash-high -> 200
```
On `cloudcode-pa` that account reads `currentTier: free-tier` (while `paidTier`
-says `g1-ultra-tier`), is served a roster of `gemini-2.5-*` plus editor-internal
+says `g1-ultra-tier`), is served a dynamic models catalog of `gemini-2.5-*` plus editor-internal
`chat_*`/`tab_*` ids, reports every quota bucket at 100% **forever** because
nothing is ever consumed, and can generate with EXACTLY the two `tab_*`
inline-completion models — free Code Assist's remaining entitlement — while all
@@ -88,7 +88,7 @@ nothing above it.
vocabulary. Doing so produced a bug report asking a backend to add five ids that
404 and delete the one that works.
-## The roster: what the backend declares unselectable
+## The dynamic models catalog: what the backend declares unselectable
`fetchAvailableModels` returns the whole editor surface, and states three ways
which of it is not a chat model — all of them read by
@@ -111,7 +111,7 @@ dropped a real model from the picker.
Only `tab_*` needs a prefix rule; it appears in no list and carries no flag.
-## Ordering: catalog dates are poison for this roster
+## Ordering: cloud models catalog dates are poison for Antigravity's models
Antigravity rows set `ignoreCatalogReleaseDate`. `compareByReleaseDateDesc` sorts
undated rows last, and measured 2026-08-24 only 6 of 19 served ids had a catalog
@@ -124,7 +124,7 @@ UNDATED gemini-3.7-flash-tiered — <- sorted to the BOTTOM
The catalog dates *base* models; Antigravity serves *variants* it does not list.
Six dated of nineteen was worse than zero: a partial signal ranked confidently on
-incomplete evidence. Suppressed, the whole roster falls through to version-parts
+incomplete evidence. Suppressed, the whole dynamic models catalog falls through to version-parts
and orders 3.7 > 3.6 > 3.5 > 3.1 > 3 > 2.5.
@@ -133,6 +133,6 @@ and orders 3.7 > 3.6 > 3.5 > 3.1 > 3 > 2.5.
- **Self-refresh**: when the token is expired, POST `oauth2/token` with `grant_type=refresh_token`. The Antigravity client_id/secret are **never shipped** — they're extracted at runtime from the user's own local `agy` binary (`strings` for the `…apps.googleusercontent.com` id + `GOCSPX-` secret; the working combo is discovered by first-200 and cached). The refreshed (and possibly rotated) token is written back to the shared store.
- **Degradation**: no store (agy not installed / not signed in) or non-macOS → actionable error pointing at `g@` + `GEMINI_API_KEY`.
-**Model ids — LIVE discovery, no hardcoded map**: the Antigravity backend requires a reasoning-tier suffix (bare `gemini-3.6-flash` → 404), but which variants a subscription serves is **per-account and drifts**, so claudish never hardcodes a roster. `getServedAntigravityModels()` fetches the live set from the backend's own `v1internal:fetchAvailableModels` (body `{project}`) — the served ids are the response `models` keys, plus a backend `defaultAgentModelId` — cached with a TTL. `resolveAntigravityModelId(requested, servedIds, defaultId)` then resolves against that LIVE set: exact match passes through; a bare family (e.g. `gemini-3.6-flash`) resolves to the backend's `defaultAgentModelId` when it's a variant of that family, else to the strongest reasoning tier by a *rank rule* (`high>medium>low>extra-low>tiered` — a rule, like `rankCodeAssistModel`, not pinned ids); anything else passes through to the F1–F7 404 rewrite. The only literals are the tier-rank ordering and endpoint strings — no concrete model ids in source.
+**Model ids — LIVE discovery, no hardcoded map**: the Antigravity backend requires a reasoning-tier suffix (bare `gemini-3.6-flash` → 404), but which variants a subscription serves is **per-account and drifts**, so claudish never hardcodes a model list. `getServedAntigravityModels()` fetches the live set from the backend's own `v1internal:fetchAvailableModels` (body `{project}`) — the served ids are the response `models` keys, plus a backend `defaultAgentModelId` — cached with a TTL. `resolveAntigravityModelId(requested, servedIds, defaultId)` then resolves against that LIVE set: exact match passes through; a bare family (e.g. `gemini-3.6-flash`) resolves to the backend's `defaultAgentModelId` when it's a variant of that family, else to the strongest reasoning tier by a *rank rule* (`high>medium>low>extra-low>tiered` — a rule, like `rankCodeAssistModel`, not pinned ids); anything else passes through to the F1–F7 404 rewrite. The only literals are the tier-rank ordering and endpoint strings — no concrete model ids in source.
**Identity strings**: `User-Agent: antigravity/cli/<ver> (aidev_client; os_type=<platform>; arch=<arch>; auth_method=consumer)` + `metadata: { ideType: "ANTIGRAVITY" }`. The transport keeps all the F1–F7 improvements from the old codeassist path (terminal-error → 400 surfaced inline, served-set-aware 404 rewrite, `rankCodeAssistModel`). Full reverse-engineering write-up: `ai-docs/sessions/antigravity-refactor-20260803-125333-d0791562/architecture.md` (write-up lost — predates the ai-docs tracking fix).
diff --git a/ai-docs/architecture/providers/devin.md b/ai-docs/architecture/providers/devin.md
index 411263fc..c5968534 100644
--- a/ai-docs/architecture/providers/devin.md
+++ b/ai-docs/architecture/providers/devin.md
@@ -7,7 +7,7 @@
The only **binary** wire in the pipeline: Connect-protocol envelopes carrying protobuf, on
`POST <server>/exa.api_server_pb.ApiServerService/GetChatMessage` with `authorization: Basic <k>-<k>`
(the key literally doubled), `content-type: application/connect+proto`, `connect-protocol-version: 1`.
-Codec, request builder, credentials, live roster, and uid resolution live in `providers/devin/`;
+Codec, request builder, credentials, live model discovery, and uid resolution live in `providers/devin/`;
Layer 1 is `adapters/devin-api-format.ts`, Layer 3 `providers/transport/devin.ts`, the parser
`handlers/shared/stream-parsers/devin-connect.ts`. Full reverse-engineering write-up:
`ai-docs/sessions/dev-arch-devin-subscription-20260806-120000-a1b2c3d4/protocol-spec.md` (write-up lost — predates the ai-docs tracking fix).
@@ -38,9 +38,10 @@ reasoning as Alibaba Token Plan, which also re-serves other vendors' models.
**The reasoning tier is IN the model id — there is no effort parameter.** `dv@claude-opus-5` at
effort `high` resolves to the uid `claude-opus-5-high` via `resolveDevinModelUid` against the LIVE
-roster (`getServedDevinModels` = `GetCliModelConfigs` ∩ `GetCliTeamSettings.allowed_model_uids`,
-minus `contextWindow === 0`, which is what drops the `adaptive` router pseudo-model). No roster,
-window, family, or tier is ever hardcoded — 167 models on the developer's own account. Note the two
+dynamic models catalog (`getServedDevinModels` = `GetCliModelConfigs` ∩
+`GetCliTeamSettings.allowed_model_uids`, minus `contextWindow === 0`, which is what drops the
+`adaptive` router pseudo-model). No model list, window, family, or tier is ever hardcoded —
+167 models on the developer's own account. Note the two
metadata rpcs are **unary and BARE** (`application/proto`, no envelope), field 1 is `"chisel"` there
versus `"devin-cli"` on `GetChatMessage`, `GetCliTeamSettings` lives on `SeatManagementService` not
`ApiServerService`, and metadata field 7 is required (dropping it → HTTP 400).
diff --git a/ai-docs/architecture/providers/grok-subscription.md b/ai-docs/architecture/providers/grok-subscription.md
index e41f81ed..a42a5b81 100644
--- a/ai-docs/architecture/providers/grok-subscription.md
+++ b/ai-docs/architecture/providers/grok-subscription.md
@@ -114,13 +114,14 @@ array order, so `parseModelSpec("grok-4.6").provider` is still `x-ai`. Two claim
namespace is fine now — the function that picked a single winner, `getProviderForModel`, no
longer exists.
-**The roster is discovered, never pinned.** `/v1/models` is genuinely authenticated (401 without a
-token — unlike Alibaba's `coding-intl` roster, where a 200 proves nothing) and the served set is
-account-scoped. Note the per-model effort ladders differ — `grok-4.6` offers `xhigh`, `grok-4.5`
+**The dynamic models catalog is discovered, never pinned.** `/v1/models` is genuinely
+authenticated (401 without a token — unlike Alibaba's `coding-intl` discovery endpoint, where a
+200 proves nothing) and the served set is account-scoped.
+Note the per-model effort ladders differ — `grok-4.6` offers `xhigh`, `grok-4.5`
does not — which is exactly the drifting per-account data that must not be hardcoded.
Models Index represents this as the `xai-supergrok` commercial plan, routed through provider UID
`grok-subscription` with `modelDiscovery: "client"`. Its public `includedModels` value is therefore
-only an account-roster limitation note, not a static allow-list. Claudish keeps the subscription
+only the plan's published membership, not a static allow-list. Claudish keeps the subscription
candidate when a Grok model is absent from the public slim catalog and lets the authenticated
-provider discovery decide the actual roster.
+provider discovery decide the account's actual dynamic models catalog.
diff --git a/ai-docs/architecture/routing.md b/ai-docs/architecture/routing.md
index 1cbdfb75..88140201 100644
--- a/ai-docs/architecture/routing.md
+++ b/ai-docs/architecture/routing.md
@@ -1,6 +1,6 @@
# Model routing
-> How a bare model name becomes a provider chain: defaultProvider, catalog resolvers, the derived picker roster, subscription pricing.
+> How a bare model name becomes a provider chain: defaultProvider, catalog resolvers, the derived picker provider list, subscription pricing.
>
> Extracted from `CLAUDE.md` (v7.64.0). Indexed in [`README.md`](./README.md).
@@ -185,7 +185,7 @@ model connection's `externalModelId` to that transport.
Plan absence has two different meanings:
-- `modelDiscovery: "catalog"`: the published roster is authoritative, so an absent model is
+- `modelDiscovery: "catalog"`: the published membership is authoritative, so an absent model is
dropped from that subscription provider's candidate chain.
- `modelDiscovery: "client"` or `"hybrid"`: the authenticated account may reveal models the
public backend cannot know, so absence remains unknown and the candidate is retained. Devin,
@@ -250,23 +250,23 @@ complete list.
([`providers/qwen-alibaba.md`](providers/qwen-alibaba.md)), so for that provider the list
records what the plan covers, not what the key may call, and it can still deny.
-## The interactive picker roster is DERIVED — never add a membership table
+## The interactive picker's provider list is DERIVED — never hand-write one
Bare `claudish` shows "Select provider:" from `model-selector.ts`. That list used to be a
hand-written `ALL_PROVIDER_CHOICES` array, so **membership was opt-in and a new provider
defaulted to invisible**. `devin` and `antigravity` were both fully working — routing,
`--probe`, and the config TUI (which has always derived its list from `getAllProviders()`) —
-while absent from the picker. `3a293b9` even built Antigravity's correct 20-model roster for
-a provider the picker could not offer.
+while absent from the picker. `3a293b9` even built Antigravity's correct 20-model dynamic
+models catalog for a provider the picker could not offer.
The v7389502 credential refactor is the trap here: it unified availability **checking** (it
-deleted the three duplicate readiness oracles) and left the **roster** alone. Unifying how a
+deleted the three duplicate readiness oracles) and left the **list itself** alone. Unifying how a
list is filtered is not the same as unifying what is in it.
- `isPickableProvider(def)` = `def.shortcuts.length > 0`. A definition with no shortcuts has
no user-typeable `@` prefix and exists only so `nativeModelPatterns` can steer a BARE name;
`qwen` and `native-anthropic` are the two, and both carry an empty `baseUrl`/`apiPath`.
- A rule, not a roster — there is no exclusion list to keep current.
+ A rule, not a table — there is no exclusion list to keep current.
- `PICKER_COPY` and `PICKER_ORDER` are **editorial only**: labels and ordering. Anything
unlisted still appears, at the end. Never use either as a membership gate.
- The `@prefix` filter aliases (`getProviderFilterAliases`) are derived the same way, from
@@ -294,7 +294,7 @@ hand-written provider table.** `configCommand` was exported and imported nowhere
What makes it worth recording rather than just deleting: it was **actively maintained while
dead**. The light-theme sweep (`c9cb626`) restyled it and a MiniMax endpoint fix (`b7173d2`)
corrected its hostname — two people paid to keep a table current that no code could read. A
-dead hand-written roster is worse than a live one, because nothing can ever prove it wrong.
+dead hand-written table is worse than a live one, because nothing can ever prove it wrong.
Check for importers before restyling a file.
## Subscription pricing is decided by BILLING, not by `modelDiscovery`
diff --git a/docs/settings-reference.md b/docs/settings-reference.md
index 4cef214d..bedc7aa1 100644
--- a/docs/settings-reference.md
+++ b/docs/settings-reference.md
@@ -779,8 +779,8 @@ Other behaviours worth knowing:
- **A row's base URL can be overridden**, when it declares one (e.g. `TUNING_ENGINES_BASE_URL` on `tuningengines`), from `config.endpoints["TUNING_ENGINES_BASE_URL"]` — what `claudish config` and the Providers tab's URL editor write — or from the environment variable of the same name. Config wins over environment, matching the `apiKeys` rule.
- **A malformed base-URL override skips the row rather than falling back** to the bundled public URL, whichever source it came from. Silently redirecting a typo to a vendor's public host would leak the traffic a self-hosted gateway exists to contain. An unexpanded `${VAR}` placeholder is treated as *unset*, not as malformed.
- **Turning a row off takes effect on the next start.** Runtime registration cannot be undone within a live process, so a row disabled mid-session keeps answering until claudish restarts. Claudish prints a warning naming the row and the reason rather than leaving that silent.
-- **No model roster ships with a row.** Catalog vendors get a free-text model prompt in the picker; model metadata comes from models-index or is absent.
-- **Nothing claudish ships puts a bundled row in a bare-name routing chain.** No row declares native model patterns or a legacy prefix, and none appears in the default routing rules, so a row is reachable only as `vendor@model` — an ambient key can add a picker row but cannot silently receive a request. (The one exception is your own doing: `defaultProvider` is appended to every bare chain, so setting `"defaultProvider": "groq"` does route bare names there.)
+- **No model list ships with a row.** Catalog vendors get a free-text model prompt in the picker; model metadata comes from models-index or is absent.
+- **Nothing claudish ships puts a bundled row in a bare-name routing chain.** No row declares native model patterns or a legacy prefix, and none is bound to a route in the cloud models catalog, so a row is reachable only as `vendor@model` — an ambient key can add a picker row but cannot silently receive a request. Routing proposes a provider only when a catalog connection resolves to it, so an unbound row cannot be proposed for any model. (`together` and `fireworks` are bound on purpose: they are gateways the catalog maps, and activating one is you naming it.) The other exception is also your own doing: the fallback is appended to every bare chain, so setting `"defaultProvider": "groq"` does route bare names there.
- An invalid `predefinedEndpoints` block warns once and is treated as absent, never as "off".
- **Evidence:** every shipped row is *probe*-verified — its configured path was confirmed to reach the vendor's own auth layer, and a deliberately bogus sibling path was confirmed to answer differently. **No row is live-verified**; that establishes the route, not the vendor's streaming dialect on a successful turn.