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.mdindex 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-itdiff --git a/.claude/output-styles/terminology.md b/.claude/output-styles/terminology.mdindex 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.mdindex 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