Skip to content

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

docs: a project thesaurus in CLAUDE.md, with the words never to write

Jack Rudenko774eafc52565
diff --git a/.claude/output-styles/composed.md b/.claude/output-styles/composed.md
index ce9a37ee..e1d16a82 100644
--- a/.claude/output-styles/composed.md
+++ b/.claude/output-styles/composed.md
@@ -28,37 +28,9 @@ These insights should be included in the conversation, not in the codebase. You
### Terminology
-One concept, one name, everywhere: code, comments, commit messages, docs, and
-conversation. A concept with two names reads as two concepts.
-
-| Use | Not | Because |
-|---|---|---|
-| provider shortcut | prefix | prefix is already taken three ways in `provider-definitions.ts` — `legacyPrefixes` (`g/`), `modelPrefix`, and vendor prefixes like `qwen/` — so it never says which one you mean |
-| bare name | unprefixed model | bare name is what `route()` and every routing doc call a model with no `provider@`, and a second term reads as a second concept |
-| routing chain | fallback chain | fallback properly names only the last-resort `defaultProvider` hop, not the whole credential-filtered candidate list |
-| metered | pay-as-you-go | the pricing code and tests say metered; PAYG survives only in the `qwen-payg` provider name and its picker label |
-| subscription | plan | plan is the vendor's product name (Coding Plan, Token Plan) while `SUBSCRIPTION_PROVIDERS` is claudish's own billing category |
-| cloud models catalog | catalog, when the kind matters | the hosted models-index metadata, keyed by model id and read with no credential; static within one catalog generation |
-| dynamic models catalog | roster | the model list a provider's discovery endpoint returns for one credential; never persisted. "Roster" named this and a plan's members alike, so neither reader could tell which was meant |
-| membership | roster, plan roster | the models a subscription plan publishes in the cloud models catalog (`subscriptionPlanIds`); it is coverage, not proof that a given account may use them |
-| picker | selector | docs, tests, and constants (`PICKER_ORDER`, `isPickableProvider`) say picker even though the file is `model-selector.ts` |
-| foreign model | external model | the antonym of native is foreign (`forceForeignModel`), and a local Ollama model is external to nothing yet still foreign to the harness |
-| harness | host | harness means Claude Code driving the session, while host already names the MCP host that spawns the server |
-| hydrate | resolve | resolving fetches a secret from 1Password, hydrating writes it into `process.env`, and the prehydration fix depends on that difference |
-| stream format | wire format | wire format is a converter's whole request/response encoding, stream format only the SSE dialect a parser consumes |
-| model spec | model string | a spec (`provider@model`) is explicit and self-describing on argv while a bare name still has routing ahead of it |
-
-Rules that hold regardless of the table above:
-
-- Use the domain's word, not the implementation's. If the business calls it a
- "booking", the code and the conversation say booking, even where the table
- is named `reservations`.
-- Do not invent a synonym for a term the codebase already uses. Grep before
- naming anything new.
-- When the code and the domain disagree on a name, say which you are using and
- which the reader will see in the file.
-- Keep abbreviations out of names people say out loud. `usr`, `mgr`, and `cfg`
- save four characters and cost a re-read every time.
+The project thesaurus lives in `CLAUDE.md`, under "Thesaurus — one name per concept", with the
+words never to write beside each term. Use it. This style does not repeat it, so the two cannot
+drift apart — a stale copy here is how "roster" survived a rename.
## Imported: lej-output-fixer--walk-me-through-it
diff --git a/.claude/output-styles/terminology.md b/.claude/output-styles/terminology.md
index c8163e6c..d6cef5a3 100644
--- a/.claude/output-styles/terminology.md
+++ b/.claude/output-styles/terminology.md
@@ -7,34 +7,6 @@ generated-by: "claudeup Styles tab, filled from the codebase by Claude Code."
### Terminology
-One concept, one name, everywhere: code, comments, commit messages, docs, and
-conversation. A concept with two names reads as two concepts.
-
-| Use | Not | Because |
-|---|---|---|
-| provider shortcut | prefix | prefix is already taken three ways in `provider-definitions.ts` — `legacyPrefixes` (`g/`), `modelPrefix`, and vendor prefixes like `qwen/` — so it never says which one you mean |
-| bare name | unprefixed model | bare name is what `route()` and every routing doc call a model with no `provider@`, and a second term reads as a second concept |
-| routing chain | fallback chain | fallback properly names only the last-resort `defaultProvider` hop, not the whole credential-filtered candidate list |
-| metered | pay-as-you-go | the pricing code and tests say metered; PAYG survives only in the `qwen-payg` provider name and its picker label |
-| subscription | plan | plan is the vendor's product name (Coding Plan, Token Plan) while `SUBSCRIPTION_PROVIDERS` is claudish's own billing category |
-| cloud models catalog | catalog, when the kind matters | the hosted models-index metadata, keyed by model id and read with no credential; static within one catalog generation |
-| dynamic models catalog | roster | the model list a provider's discovery endpoint returns for one credential; never persisted. "Roster" named this and a plan's members alike, so neither reader could tell which was meant |
-| membership | roster, plan roster | the models a subscription plan publishes in the cloud models catalog (`subscriptionPlanIds`); it is coverage, not proof that a given account may use them |
-| picker | selector | docs, tests, and constants (`PICKER_ORDER`, `isPickableProvider`) say picker even though the file is `model-selector.ts` |
-| foreign model | external model | the antonym of native is foreign (`forceForeignModel`), and a local Ollama model is external to nothing yet still foreign to the harness |
-| harness | host | harness means Claude Code driving the session, while host already names the MCP host that spawns the server |
-| hydrate | resolve | resolving fetches a secret from 1Password, hydrating writes it into `process.env`, and the prehydration fix depends on that difference |
-| stream format | wire format | wire format is a converter's whole request/response encoding, stream format only the SSE dialect a parser consumes |
-| model spec | model string | a spec (`provider@model`) is explicit and self-describing on argv while a bare name still has routing ahead of it |
-
-Rules that hold regardless of the table above:
-
-- Use the domain's word, not the implementation's. If the business calls it a
- "booking", the code and the conversation say booking, even where the table
- is named `reservations`.
-- Do not invent a synonym for a term the codebase already uses. Grep before
- naming anything new.
-- When the code and the domain disagree on a name, say which you are using and
- which the reader will see in the file.
-- Keep abbreviations out of names people say out loud. `usr`, `mgr`, and `cfg`
- save four characters and cost a re-read every time.
+The project thesaurus lives in `CLAUDE.md`, under "Thesaurus — one name per concept", with the
+words never to write beside each term. Use it. This style does not repeat it, so the two cannot
+drift apart — a stale copy here is how "roster" survived a rename.
diff --git a/CLAUDE.md b/CLAUDE.md
index 031166e7..55d0af4e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,24 +29,68 @@ lives in `ROADMAP.md`.
Evidence behind them: `ai-docs/reports/`. Evals: `ai-docs/benches/`. User-facing site: `docs/`.
-## Vocabulary — one name per concept
-
-The full dictionary is `.claude/output-styles/terminology.md`. It binds code, comments, commit
-messages, docs and conversation alike. The terms most often confused:
-
-- **cloud models catalog** — hosted models-index metadata, keyed by model id; no credential.
-- **dynamic models catalog** — the models a provider's discovery endpoint returns for ONE
- credential; never persisted.
-- **membership** — the models a subscription plan publishes (`subscriptionPlanIds`). Coverage,
- not proof that an account may use them.
-- **Never write "roster".** It meant both of the last two, so no reader could tell which. The
- word survives only inside models-index wire names quoted verbatim (`rosterCoverage`), until the
- backend renames them.
-- Provider names, shortcuts, credential names and hosts are copied from the backend contract
- (models-index `ai-docs/alibaba-provider-changes.md`, and the binding fixture). A rename REMOVES
- the old name: no alias, no shim, no deprecation notice.
-
-`AGENTS.md` is a symlink to this file, so Codex reads the same instructions.
+## Thesaurus — one name per concept
+
+Every agent and the main thread use these words, in code, comments, commit messages, docs and
+conversation. A concept with two names reads as two concepts. The "Never write" column is the
+negative case: if you are about to type one of those words, stop and use the left column.
+`AGENTS.md` is a symlink to this file, so Codex reads the same list.
+
+**Catalog and data**
+
+| Use | Never write | Means |
+|---|---|---|
+| cloud models catalog | "catalog" alone when the kind matters; "Firebase catalog" | the hosted models-index metadata, keyed by canonical model id, read with no credential |
+| dynamic models catalog | roster, account roster, live roster, served set | the models a provider's discovery endpoint returns for ONE credential; never persisted |
+| membership | roster, plan roster, included models | the models a subscription plan publishes (`subscriptionPlanIds`); coverage, not access |
+| entitlement | membership, coverage (when you mean access) | what one account may actually call; only its dynamic models catalog or a live request proves it |
+| generation | revision, snapshot, catalog version | one immutable catalog publication (`generationId`); every read of one refresh is pinned to it |
+| canonical model id | model name, catalog name | the catalog record's `modelId` (`kimi-k3`) |
+| wire id | provider name for the model, external name | the exact string sent to a provider (`externalModelId`: `k3`, `MiniMax-M3`) |
+| moving pointer | alias, latest alias | an id that redirects over time (`~moonshotai/kimi-latest`); send it only when the user asked for "latest" |
+| route binding | provider id, route alone | the `(routeId, routeProfileId)` pair; it names one endpoint and one credential silo |
+| route variant | effort model, model preset | a preset entry of a base model (`routeVariant`, e.g. `kimi-k3-256k`, context=256k) |
+| connection | aggregator row, provider row | one mapped way to call a model: an `aggregators[]` entry with `routeStatus: "mapped"` |
+| input modality, output modality | capability (for what goes in or out) | what a model accepts and produces: text, image, audio, video, file |
+| chat model | text model, LLM | takes text in and gives only text out; video input alone never excludes one |
+
+**Providers and routing**
+
+| Use | Never write | Means |
+|---|---|---|
+| claudish provider | provider (when ambiguous), vendor | an entry in `BUILTIN_PROVIDERS` (`openai-codex`, `qwen-token-plan`) |
+| vendor | provider (for the model's maker) | the company that makes the model; the catalog's `provider` field |
+| provider shortcut | prefix | `cx` in `cx@gpt-6-astra`. "Prefix" already means three other things in `provider-definitions.ts` |
+| model spec | model string | `provider@model`, explicit on argv |
+| bare name | unprefixed model | a model with no `provider@`; routing chooses its provider |
+| routing chain | fallback chain | the ordered, credential-filtered candidates for one request |
+| fallback | (the whole chain) | only the last-resort `defaultProvider` hop |
+| subscription | plan (as a billing category) | claudish's flat-rate category (`SUBSCRIPTION_PROVIDERS`); "plan" is the vendor's product name |
+| dynamic subscription | client subscription | a subscription whose models the account's own discovery decides (Antigravity, SuperGrok, Devin) |
+| native API | direct API | the vendor's own metered endpoint (the `direct-api` profile) |
+| gateway | aggregator (as a tier) | a metered service reselling many vendors: OpenRouter, Together, Fireworks, Poe, Vertex |
+| metered | pay-as-you-go, PAYG | billed per token. PAYG survives only in the names `qwen-payg` and "Alibaba PAYG" |
+| probe pick | probe model, test model | the first model Test All tries on a provider |
+
+**Harness and runtime**
+
+| Use | Never write | Means |
+|---|---|---|
+| harness | host | Claude Code driving the session; "host" is the MCP host that spawns the server |
+| foreign model | external model | any model not native to the harness; a local Ollama model is foreign too |
+| picker | selector | the interactive model chooser (`PICKER_ORDER`), although the file is `model-selector.ts` |
+| hydrate | resolve (for writing a secret into the environment) | resolving fetches a secret from 1Password; hydrating writes it into `process.env` |
+| stream format | wire format | the SSE dialect one parser consumes; wire format is a converter's whole encoding |
+
+**Negative cases, in context**
+
+- Wrong: "the account's roster lacks the model." Right: "the account's dynamic models catalog lacks the model."
+- Wrong: "the plan's roster has 31 models." Right: "the plan's membership has 31 models."
+- Wrong: "fall back to the Kimi alias." Right: "send the exact wire id `moonshotai/kimi-k3`, not the moving pointer."
+- Wrong: "the provider `qwen`" when you mean the Alibaba Token Plan. Right: "the claudish provider `qwen-token-plan`" or "the vendor `qwen`".
+- Wrong: "the fallback chain." Right: "the routing chain", whose last hop is the fallback.
+
+**Static values** (provider names, shortcuts, credential names, hosts) are copied from the backend contract: models-index `ai-docs/alibaba-provider-changes.md` and the binding fixture. A rename REMOVES the old name: no alias, no shim, no deprecation notice. Wire names the backend has not renamed yet (`rosterCoverage`) are quoted verbatim, never adopted as prose.
## Invariants — each of these fails SILENTLY