@adia-ai/adia-ui-forge 0.8.61 → 0.8.63

package/skills/llm-client-maintenance/references/adapter-contract.md

@@ -1,27 +1,27 @@
 # Adapter contract
 
-The single shape every provider adapter implements. Source: `packages/llm/core/src/adapters/anthropic.ts` (the canonical adapter — `openai.ts` and `gemini.ts` import their shared types from it), the facade `packages/llm/core/src/adapters/index.ts`, and the shared parser `packages/llm/core/src/adapters/sse.ts`.
+The single shape every provider adapter implements. Source: `packages/llm/core/src/adapters/anthropic.ts` (the canonical adapter, `openai.ts` and `gemini.ts` import their shared types from it), the facade `packages/llm/core/src/adapters/index.ts`, and the shared parser `packages/llm/core/src/adapters/sse.ts`.
 
-This reference is about the adapter object — its three methods, the request it builds, and the response/usage/`stopReason` it parses. The SSE-byte mechanics live in `streaming-sse.md`; the facade that dispatches to an adapter lives in `bridge-facade.md`.
+This reference is about the adapter object, its three methods, the request it builds, and the response/usage/`stopReason` it parses. The SSE-byte mechanics live in `streaming-sse.md`; the facade that dispatches to an adapter lives in `bridge-facade.md`.
 
-Field tables below are a snapshot verified against `packages/llm/core/src/` on 2026-07-10 — on any conflict, the source wins; re-grep before relying on an exact field name.
+Field tables below are a snapshot verified against `packages/llm/core/src/` on 2026-07-10, on any conflict, the source wins; re-grep before relying on an exact field name.
 
 ---
 
-## The adapter object — three methods
+## The adapter object, three methods
 
 Each provider exports a single `const` (lowercase provider name) with a `name` literal plus three methods. The facade calls them; consumers never touch an adapter directly.
 
 | Member | Signature (see `anthropic.ts`) | Job |
 | --- | --- | --- |
 | `name` | `'anthropic' as const` (or `'openai'` / `'gemini'`) | Registry key + error messages |
-| `buildRequest(opts)` | `(BuildRequestOpts) => AdapterRequest` | Build the upstream `{ url, headers, body }` — the single source of truth for upstream shape |
+| `buildRequest(opts)` | `(BuildRequestOpts) => AdapterRequest` | Build the upstream `{ url, headers, body }`, the single source of truth for upstream shape |
 | `parseResponse(json)` | `(ProviderResponseBody) => AdapterResponse` | Map a non-streaming JSON body to `{ text, usage, stopReason }` |
 | `parseStream(response)` | `(Response) => AsyncGenerator<StreamChunk>` | Map an SSE `Response` to the `StreamChunk` union |
 
-The shared types (`AdapterRequest`, `AdapterUsage`, `AdapterResponse`, `StreamChunk`, `BuildRequestOpts`) are declared in `anthropic.ts` and re-exported from `index.ts`. `openai.ts` and `gemini.ts` `import type` them from `./anthropic.js`. **When you change a shared type, change it in `anthropic.ts`** — the other two adapters and the facade inherit it.
+The shared types (`AdapterRequest`, `AdapterUsage`, `AdapterResponse`, `StreamChunk`, `BuildRequestOpts`) are declared in `anthropic.ts` and re-exported from `index.ts`. `openai.ts` and `gemini.ts` `import type` them from `./anthropic.js`. **When you change a shared type, change it in `anthropic.ts`**, the other two adapters and the facade inherit it.
 
-## `AdapterResponse` — the normalized result
+## `AdapterResponse`, the normalized result
 
 `parseResponse` (and the terminal `done` chunk of `parseStream`) always returns:
 
@@ -37,25 +37,25 @@ The facade wraps this as `ChatResult` (same fields) for `chat()`. Each adapter i
 | `text` | first `content[]` block of `type === 'text'` | `choices[0].message.content` | join of `candidates[0].content.parts[].text` |
 | `usage.input` | `usage.input_tokens` | `usage.prompt_tokens` | `usageMetadata.promptTokenCount` |
 | `usage.output` | `usage.output_tokens` | `usage.completion_tokens` | `usageMetadata.candidatesTokenCount` |
-| `usage.cacheCreation` | `usage.cache_creation_input_tokens` | — (absent) | — (absent) |
-| `usage.cacheRead` | `usage.cache_read_input_tokens` | — (absent) | — (absent) |
-| `stopReason` | `stop_reason` (raw) | `finish_reason` (`stop` → `end`, else raw) | `finishReason` (raw — `STOP`/`MAX_TOKENS`/`SAFETY`; `'end'` only when absent; fixed 2026-07-16, was hardcoded `'end'` hiding truncation) |
+| `usage.cacheCreation` | `usage.cache_creation_input_tokens` |, (absent) |, (absent) |
+| `usage.cacheRead` | `usage.cache_read_input_tokens` |, (absent) |, (absent) |
+| `stopReason` | `stop_reason` (raw) | `finish_reason` (`stop` → `end`, else raw) | `finishReason` (raw, `STOP`/`MAX_TOKENS`/`SAFETY`; `'end'` only when absent; fixed 2026-07-16, was hardcoded `'end'` hiding truncation) |
 
 Every numeric field defaults to `0` via `?? 0`; missing cache fields stay absent for non-Anthropic providers. **A new adapter must fill `input` + `output`; cache fields are optional.**
 
-## `stopReason` — propagate raw, never normalize
+## `stopReason`, propagate raw, never normalize
 
 The `stopReason` string is part of the public contract because the downstream truncation detector reads it. Known values across providers:
 
-- `end` / `stop` / `STOP` — clean completion.
-- `max_tokens` (Anthropic) / `length` (OpenAI) / `MAX_TOKENS` (Gemini) — **truncation**; the consumer refuses silent fallback rendering.
-- `tool_use` (Anthropic) / `tool_calls` (OpenAI) — tool-call paused output.
+- `end` / `stop` / `STOP`, clean completion.
+- `max_tokens` (Anthropic) / `length` (OpenAI) / `MAX_TOKENS` (Gemini), **truncation**; the consumer refuses silent fallback rendering.
+- `tool_use` (Anthropic) / `tool_calls` (OpenAI), tool-call paused output.
 
-OpenAI's adapter maps only its own `finish_reason === 'stop'` to `end` and passes everything else through raw (see `openai.ts` `parseResponse`). Anthropic passes `stop_reason` through untouched. **Do not collapse the truncation values to `end`** — that hides truncation from the consumer and is a defect, not a cleanup.
+OpenAI's adapter maps only its own `finish_reason === 'stop'` to `end` and passes everything else through raw (see `openai.ts` `parseResponse`). Anthropic passes `stop_reason` through untouched. **Do not collapse the truncation values to `end`**: that hides truncation from the consumer and is a defect, not a cleanup.
 
-## `buildRequest()` — one source of truth for upstream shape
+## `buildRequest()`, one source of truth for upstream shape
 
-`buildRequest(opts: BuildRequestOpts)` returns `{ url, headers, body }`. It is called from two places — direct mode and passthrough-proxy mode — and **must produce the same upstream body + auth headers in both**. Don't fork it for proxy mode; the dispatcher swaps only the URL (see `browser-proxy-boundary.md`).
+`buildRequest(opts: BuildRequestOpts)` returns `{ url, headers, body }`. It is called from two places, direct mode and passthrough-proxy mode, and **must produce the same upstream body + auth headers in both**. Don't fork it for proxy mode; the dispatcher swaps only the URL (see `browser-proxy-boundary.md`).
 
 Per-provider request facts grounded in the source:
 
@@ -68,9 +68,9 @@ Per-provider request facts grounded in the source:
 | Stream flag | `stream` in body | `stream` + `stream_options.include_usage` | encoded in the URL action |
 | Roles | `messages[]` verbatim | `messages[]` verbatim | `assistant` → `model`, else `user` |
 
-Gemini's URL is action-dependent: `generateContent` for non-streaming, `streamGenerateContent?alt=sse` for streaming (see `gemini.ts` — the `action` ternary). The other two use one URL and a `stream` body flag.
+Gemini's URL is action-dependent: `generateContent` for non-streaming, `streamGenerateContent?alt=sse` for streaming (see `gemini.ts`, the `action` ternary). The other two use one URL and a `stream` body flag.
 
-## Anthropic prompt caching — the `cache` opt
+## Anthropic prompt caching, the `cache` opt
 
 `BuildRequestOpts.cache` is Anthropic-specific. When `cache` is truthy, `anthropic.ts` wraps the system prompt as a cache-control block:
 
@@ -78,24 +78,24 @@ Gemini's URL is action-dependent: `generateContent` for non-streaming, `streamGe
 body.system = [{ type: 'text', text: opts.system, cache_control: { type: 'ephemeral' } }]
 ```
 
-`openai.ts` and `gemini.ts` ignore `cache` (they read only the fields they understand). The bridge sets `cache: this.#provider === 'anthropic'` so the adia-ui system prompt becomes a cache breakpoint. **A new adapter should ignore `cache` unless its provider has its own caching mechanism** — then add a parallel branch in that adapter's `buildRequest` and surface the cache fields in `parseResponse`.
+`openai.ts` and `gemini.ts` ignore `cache` (they read only the fields they understand). The bridge sets `cache: this.#provider === 'anthropic'` so the adia-ui system prompt becomes a cache breakpoint. **A new adapter should ignore `cache` unless its provider has its own caching mechanism**, then add a parallel branch in that adapter's `buildRequest` and surface the cache fields in `parseResponse`.
 
-## `thinking` — Anthropic-only request, two adapters surface a chunk
+## `thinking`, Anthropic-only request, two adapters surface a chunk
 
 `BuildRequestOpts.thinking` / `thinkingBudget` are read only by `anthropic.ts` (`body.thinking = { type: 'enabled', budget_tokens: opts.thinkingBudget ?? 10000 }`). On the streaming side, both Anthropic (`thinking_delta`) and OpenAI (`delta.reasoning_content`) emit a `{ type: 'thinking', text }` chunk; Gemini does not. Consumers may ignore `thinking` chunks, but they must not crash on them.
 
-## Worked example — auditing an adapter's `usage` mapping
+## Worked example, auditing an adapter's `usage` mapping
 
 Symptom: cache hit-rate telemetry reads `0` for Anthropic even though the API returned cache reads.
 
 1. Plan: verify target is a real `chat()` against Anthropic with a system prompt large enough to cache (≥1024 tok Sonnet/Opus, ≥2048 Haiku) and `cache: true`, run twice in the cache window.
-2. Execute: inspect `anthropic.ts` `parseResponse` — confirm `cacheRead` reads `usage.cache_read_input_tokens` (not a camelCase guess). For streaming, confirm `message_start` sets `usage.cacheCreation` / `usage.cacheRead` and `message_delta` sets `usage.output` (see `parseStream` in `anthropic.ts`).
+2. Execute: inspect `anthropic.ts` `parseResponse`, confirm `cacheRead` reads `usage.cache_read_input_tokens` (not a camelCase guess). For streaming, confirm `message_start` sets `usage.cacheCreation` / `usage.cacheRead` and `message_delta` sets `usage.output` (see `parseStream` in `anthropic.ts`).
 3. Verify: the second `chat()` returns `usage.cacheRead > 0`; the bridge's `cacheReadTokens` is non-zero. If it's still `0`, the bug is the field name, not the bridge.
 
 ## Cross-references
 
-- [streaming-sse.md](streaming-sse.md) — the `StreamChunk` union, the shared SSE parser, and the per-provider event mapping
-- [bridge-facade.md](bridge-facade.md) — how `chat()` / `streamChat()` resolve and call an adapter; the `ChatResult` wrapper
-- [browser-proxy-boundary.md](browser-proxy-boundary.md) — why `buildRequest()` must stay proxy-agnostic
-- [add-a-provider.md](add-a-provider.md) — the end-to-end recipe that uses this contract
+- [streaming-sse.md](streaming-sse.md), the `StreamChunk` union, the shared SSE parser, and the per-provider event mapping
+- [bridge-facade.md](bridge-facade.md), how `chat()` / `streamChat()` resolve and call an adapter; the `ChatResult` wrapper
+- [browser-proxy-boundary.md](browser-proxy-boundary.md), why `buildRequest()` must stay proxy-agnostic
+- [add-a-provider.md](add-a-provider.md), the end-to-end recipe that uses this contract
 - Source: `packages/llm/core/src/adapters/anthropic.ts` (canonical types + adapter), `openai.ts`, `gemini.ts`

package/skills/llm-client-maintenance/references/add-a-provider.md

@@ -1,6 +1,6 @@
 # Add a provider
 
-The end-to-end recipe for a 4th provider adapter (DeepSeek, Mistral, Cohere, an OpenAI-compatible gateway, …). Grounded in the existing three adapters under `packages/llm/core/src/adapters/` and the facade `packages/llm/core/src/adapters/index.ts`. Read `adapter-contract.md` first — this recipe wires the contract it defines.
+The end-to-end recipe for a 4th provider adapter (DeepSeek, Mistral, Cohere, an OpenAI-compatible gateway, …). Grounded in the existing three adapters under `packages/llm/core/src/adapters/` and the facade `packages/llm/core/src/adapters/index.ts`. Read `adapter-contract.md` first, this recipe wires the contract it defines.
 
 Adding a provider is **additive** to the public surface (a new adapter, a new `MODELS` group, a new `detectProvider` branch). It does not break existing consumers if you follow the contract.
 
@@ -8,20 +8,20 @@ Adding a provider is **additive** to the public surface (a new adapter, a new `M
 
 ## Decide first: is this OpenAI-compatible?
 
-Many providers (Groq, Together, Mistral, any OpenAI-compatible gateway) speak the OpenAI Chat Completions wire format. `openai.ts` already notes this. If the new provider is OpenAI-compatible, you may not need a new adapter at all — you may only need a `detectProvider` branch and a base-URL override. A genuinely new wire format (different request body, different SSE event shape) needs a new adapter. Confirm against the provider's API docs before writing code.
+Many providers (Groq, Together, Mistral, any OpenAI-compatible gateway) speak the OpenAI Chat Completions wire format. `openai.ts` already notes this. If the new provider is OpenAI-compatible, you may not need a new adapter at all, you may only need a `detectProvider` branch and a base-URL override. A genuinely new wire format (different request body, different SSE event shape) needs a new adapter. Confirm against the provider's API docs before writing code.
 
-## Step 1 — write the adapter
+## Step 1, write the adapter
 
 Create `packages/llm/core/src/adapters/<name>.ts` exporting one `const` matching the contract (model on `anthropic.ts`):
 
 - `name: '<name>' as const`.
-- `buildRequest(opts: BuildRequestOpts): AdapterRequest` — return `{ url, headers, body }`. Set the auth header the provider expects. Map `opts.system`, `opts.messages`, `opts.maxTokens` (default to the package's `32768` unless the provider's ceiling is lower), `opts.temperature`, and the `stream` flag into the provider's body shape.
-- `parseResponse(json): AdapterResponse` — map to `{ text, usage: { input, output }, stopReason }`. Pass `stopReason` through RAW (don't normalize).
-- `parseStream(response): AsyncGenerator<StreamChunk>` — guard `response.body`, consume `readSSE` from `./sse.js`, accumulate `snapshot` + `usage`, yield `text` deltas with the running `snapshot`, and yield exactly one terminal `done`.
+- `buildRequest(opts: BuildRequestOpts): AdapterRequest`, return `{ url, headers, body }`. Set the auth header the provider expects. Map `opts.system`, `opts.messages`, `opts.maxTokens` (default to the package's `32768` unless the provider's ceiling is lower), `opts.temperature`, and the `stream` flag into the provider's body shape.
+- `parseResponse(json): AdapterResponse`, map to `{ text, usage: { input, output }, stopReason }`. Pass `stopReason` through RAW (don't normalize).
+- `parseStream(response): AsyncGenerator<StreamChunk>`, guard `response.body`, consume `readSSE` from `./sse.js`, accumulate `snapshot` + `usage`, yield `text` deltas with the running `snapshot`, and yield exactly one terminal `done`.
 
-`import type { AdapterRequest, AdapterResponse, AdapterUsage, StreamChunk, BuildRequestOpts } from './anthropic.js';` — reuse the canonical types; don't redeclare them.
+`import type { AdapterRequest, AdapterResponse, AdapterUsage, StreamChunk, BuildRequestOpts } from './anthropic.js';`, reuse the canonical types; don't redeclare them.
 
-## Step 2 — register in the facade
+## Step 2, register in the facade
 
 Edit `packages/llm/core/src/adapters/index.ts`:
 
@@ -36,15 +36,15 @@ Then add a `detectProvider` branch so model ids route without an explicit `provi
 if (m.includes('<id-substring>') || m.startsWith('<name>/')) return 'myprovider';
 ```
 
-Support both conventions — a substring (`m.includes(...)`) and a `provider/model` prefix (`m.startsWith('<name>/')`) — to match how the existing branches behave (see `model-registry.md`).
+Support both conventions, a substring (`m.includes(...)`) and a `provider/model` prefix (`m.startsWith('<name>/')`), to match how the existing branches behave (see `model-registry.md`).
 
-## Step 3 — subpath export (usually automatic)
+## Step 3, subpath export (usually automatic)
 
 `package.json` already has `"./adapters/*"` as a glob export, so `@adia-ai/llm/adapters/<name>` resolves without an edit. Only add a named subpath (like `./bridge` / `./models`) if you want a stable short import.
 
-## Step 4 — add to the model registry
+## Step 4, add to the model registry
 
-Edit `packages/llm/core/src/models.ts` — add a `ModelGroup`:
+Edit `packages/llm/core/src/models.ts`, add a `ModelGroup`:
 
 ```text
 { label: 'MyProvider', options: [ { value: '<model-id>', label: '<display name>' } ] }
@@ -52,28 +52,28 @@ Edit `packages/llm/core/src/models.ts` — add a `ModelGroup`:
 
 Keep the `[{ label, options: [{ value, label }] }]` shape exactly (the `<chat-input-ui>` setter depends on it). The `value` must be a model id your Step 2 `detectProvider` branch classifies. Don't change `DEFAULT_MODEL` to the new provider unless you intend a default switch (keep it cheap/fast).
 
-## Step 5 — wire the bridge default + browser route (if browser-routable)
+## Step 5, wire the bridge default + browser route (if browser-routable)
 
 Edit `packages/llm/core/src/llm-bridge.ts`:
 
-- Add `myprovider: '<default-model-id>'` to `DEFAULT_MODELS` (the per-provider fallback `createAdapter()` uses when no model is supplied — distinct from `models.ts`'s `DEFAULT_MODEL`; see `model-registry.md`).
-- **INVARIANT: every keyed map in the bridge (`DEFAULT_MODELS`, `resolveBaseUrl`'s proxyMap, `detectProvider`'s return) uses the SAME key as the adapters registry** (`providers` in `adapters/index.ts`). A mismatched key compiles fine and throws at runtime (`Unknown provider`) — the gh#268 L-1 bug class. If a marketing name differs from the registry key (Google/Gemini), normalize the alias at the top of `createAdapter()` and use the registry key everywhere below.
+- Add `myprovider: '<default-model-id>'` to `DEFAULT_MODELS` (the per-provider fallback `createAdapter()` uses when no model is supplied, distinct from `models.ts`'s `DEFAULT_MODEL`; see `model-registry.md`).
+- **INVARIANT: every keyed map in the bridge (`DEFAULT_MODELS`, `resolveBaseUrl`'s proxyMap, `detectProvider`'s return) uses the SAME key as the adapters registry** (`providers` in `adapters/index.ts`). A mismatched key compiles fine and throws at runtime (`Unknown provider`), the gh#268 L-1 bug class. If a marketing name differs from the registry key (Google/Gemini), normalize the alias at the top of `createAdapter()` and use the registry key everywhere below.
 - If the provider should work in the browser, add a `resolveBaseUrl` entry whose path is `/api/llm/<name>/...` so it matches the passthrough regex (see `browser-proxy-boundary.md`). The deployed app's same-origin proxy must have a matching route that injects the server-side key.
 
-## Step 6 — caching + thinking (only if the provider supports them)
+## Step 6, caching + thinking (only if the provider supports them)
 
-`BuildRequestOpts.cache` and `thinking` are currently Anthropic-shaped. Leave `cache` ignored unless the provider has its own prompt-cache mechanism — then add a parallel branch in your `buildRequest` and surface the cache fields in `parseResponse`/`parseStream`. Same for `thinking`: only emit a `{ type: 'thinking', text }` chunk if the provider streams reasoning deltas (OpenAI does, via `delta.reasoning_content`; Gemini does not).
+`BuildRequestOpts.cache` and `thinking` are currently Anthropic-shaped. Leave `cache` ignored unless the provider has its own prompt-cache mechanism, then add a parallel branch in your `buildRequest` and surface the cache fields in `parseResponse`/`parseStream`. Same for `thinking`: only emit a `{ type: 'thinking', text }` chunk if the provider streams reasoning deltas (OpenAI does, via `delta.reasoning_content`; Gemini does not).
 
-## Step 7 — verify against the real provider
+## Step 7, verify against the real provider
 
 This is the verify target. Do not declare done on a clean compile alone:
 
-1. `npm run build -w @adia-ai/llm` (repo root; `tsc --build`) — the new adapter compiles with no type error against the shared types.
+1. `npm run build -w @adia-ai/llm` (repo root; `tsc --build`), the new adapter compiles with no type error against the shared types.
 2. A real `chat({ provider: 'myprovider', apiKey: '<key>', model: '<model-id>', messages: [...] })` returns non-empty `text` and a sane `usage` (`input`/`output` > 0) and a raw `stopReason`.
 3. A real `streamChat(...)` shows ordered `text` deltas with a growing `snapshot`, a terminal `done` carrying final `usage`, and an `error` chunk on a forced failure (bad key).
 4. `detectProvider('<model-id>')` returns `'myprovider'` (auto-detection works with no explicit provider).
 
-## Worked example — adding an OpenAI-compatible gateway
+## Worked example, adding an OpenAI-compatible gateway
 
 A gateway that speaks the OpenAI wire format with a different base URL and a `gw-` model prefix.
 
@@ -83,8 +83,8 @@ A gateway that speaks the OpenAI wire format with a different base URL and a `gw
 
 ## Cross-references
 
-- [adapter-contract.md](adapter-contract.md) — the three-method object + the `usage` / `stopReason` mapping this recipe implements
-- [streaming-sse.md](streaming-sse.md) — the `StreamChunk` protocol the new `parseStream` must satisfy
-- [model-registry.md](model-registry.md) — the `MODELS` group + `detectProvider` branch
-- [browser-proxy-boundary.md](browser-proxy-boundary.md) — the `resolveBaseUrl` entry + passthrough regex
-- [bridge-facade.md](bridge-facade.md) — `DEFAULT_MODELS` and the lazy-load gate
+- [adapter-contract.md](adapter-contract.md), the three-method object + the `usage` / `stopReason` mapping this recipe implements
+- [streaming-sse.md](streaming-sse.md), the `StreamChunk` protocol the new `parseStream` must satisfy
+- [model-registry.md](model-registry.md), the `MODELS` group + `detectProvider` branch
+- [browser-proxy-boundary.md](browser-proxy-boundary.md), the `resolveBaseUrl` entry + passthrough regex
+- [bridge-facade.md](bridge-facade.md), `DEFAULT_MODELS` and the lazy-load gate

package/skills/llm-client-maintenance/references/bridge-facade.md

@@ -6,7 +6,7 @@ This reference covers the facade/bridge contract and the stub. The proxy-flavor
 
 ---
 
-## The public barrel — what `@adia-ai/llm` exports
+## The public barrel, what `@adia-ai/llm` exports
 
 `index.ts` re-exports exactly four things; this is the package's public API surface:
 
@@ -17,21 +17,21 @@ export { StubLLMAdapter }                 from './llm-stub.js';
 export { createAdapter }                  from './llm-bridge.js';
 ```
 
-Subpath exports (`package.json` `exports`): `.` (the barrel), `./adapters/*` (each adapter, glob), `./bridge`, `./models`, `./stub`. The `./adapters/*` glob means **a new adapter file is exported automatically** — no `package.json` edit needed unless you want a named subpath.
+Subpath exports (`package.json` `exports`): `.` (the barrel), `./adapters/*` (each adapter, glob), `./bridge`, `./models`, `./stub`. The `./adapters/*` glob means **a new adapter file is exported automatically**, no `package.json` edit needed unless you want a named subpath.
 
-## Build order — the package's `index.js` is a tsc artifact
+## Build order: the package's `index.js` is a tsc artifact
 
 `npm run build -w @adia-ai/llm` (repo root) compiles the package; the emitted `index.js` is gitignored. Two downstream consequences:
 
-- **A fresh git worktree can't build the repo's JS bundles until `@adia-ai/llm` is built** — the tsc artifact doesn't exist in a fresh checkout.
+- **A fresh git worktree can't build the repo's JS bundles until `@adia-ai/llm` is built**, the tsc artifact doesn't exist in a fresh checkout.
 - **After any source change here that component bundles consume, rebuild in order:** `npm run build -w @adia-ai/llm` FIRST (`build:bundle-js` resolves the package's `index.js`), then `npm run build:bundle-css` / `npm run build:bundle-js`. The `check:css-bundles-fresh` / `check:js-bundles-fresh` gates are blocking in CI, and `build:site` does NOT rebuild these package bundles.
 
-## Layer 1 — the standalone facade (`chat` / `streamChat`)
+## Layer 1, the standalone facade (`chat` / `streamChat`)
 
 `chat(opts: ChatOpts): Promise<ChatResult>` and `streamChat(opts): AsyncGenerator<StreamChunk>` are the provider-agnostic functions. Both follow the same arc in `index.ts`:
 
-1. `resolveAdapter(opts)` — uses `opts.provider` or `detectProvider(opts.model)`; throws if neither resolves (see `model-registry.md`).
-2. Build the request: if `opts.proxyUrl` is set, branch on `isPassthroughProxy(proxyUrl)` (passthrough vs smart proxy — see `browser-proxy-boundary.md`); otherwise call `adapter.buildRequest({ ...opts, stream })` directly.
+1. `resolveAdapter(opts)`, uses `opts.provider` or `detectProvider(opts.model)`; throws if neither resolves (see `model-registry.md`).
+2. Build the request: if `opts.proxyUrl` is set, branch on `isPassthroughProxy(proxyUrl)` (passthrough vs smart proxy, see `browser-proxy-boundary.md`); otherwise call `adapter.buildRequest({ ...opts, stream })` directly.
 3. `fetch(url, { method: 'POST', headers, body: JSON.stringify(body), signal })`.
 4. On `!res.ok`: `chat` throws `Error(err.error.message || '<adapter> API error <status>')`; `streamChat` yields an `error` chunk instead of throwing.
 5. `chat` returns `adapter.parseResponse(json)`; `streamChat` delegates to `adapter.parseStream(res)`.
@@ -44,58 +44,58 @@ ChatOpts   = { model; messages; apiKey; provider?; system?; maxTokens?; temperat
 ChatResult = { text: string; usage: AdapterUsage; stopReason: string }
 ```
 
-`ChatResult` is structurally identical to `AdapterResponse` — the facade returns the adapter's parsed response unchanged. **Changing `ChatOpts` / `ChatResult` is a breaking change for every consumer**; adding an optional `ChatOpts` field is additive.
+`ChatResult` is structurally identical to `AdapterResponse`, the facade returns the adapter's parsed response unchanged. **Changing `ChatOpts` / `ChatResult` is a breaking change for every consumer**; adding an optional `ChatOpts` field is additive.
 
-## Layer 1b — `createClient` (reusable instance with defaults)
+## Layer 1b, `createClient` (reusable instance with defaults)
 
 `createClient(defaults: Partial<ChatOpts> = {}): LLMClient` returns `{ chat, stream }` that merge `defaults` under each call's opts (`{ ...defaults, ...opts }`). The merge is shallow and call-opts-win. Use it to bake in `provider` + `apiKey` + `proxyUrl` once. `LLMClient` is the interface the bridge wraps.
 
-## Layer 2 — the bridge (`createAdapter` → `AdiaUILLMBridge`)
+## Layer 2, the bridge (`createAdapter` → `AdiaUILLMBridge`)
 
 `llm-bridge.ts` adapts the facade to the adia-ui pipeline's simpler interface. The pipeline calls `adapter.complete({ messages, systemPrompt })` and `adapter.stream({ messages, systemPrompt })`; the bridge translates to the facade's `chat({ model, messages, system, … })`.
 
 `createAdapter(opts): Promise<StubLLMAdapter | AdiaUILLMBridge>` (async):
 
-- Resolves `provider` in precedence order: `opts.provider` → the model id via `detectProviderFromModel(model)` (exported from `adapters/index.ts`) → `LLM_PROVIDER` env → env-key `detectProvider()`. The model id outranking env detection is load-bearing — a model-picker selection ("gemini-2.5-flash") must decide the provider, or every non-default model routes to the env-detected provider's API and 404s (live bug fixed 2026-07-16). Resolves the model from `opts.model` / `LLM_MODEL` env / per-provider `DEFAULT_MODELS`.
-- Reads the API key from `opts.apiKey` or the provider's own `KEY_ENVS` entry — **per-provider isolated**, never a cross-provider fallback chain (`anthropic: [ANTHROPIC_API_KEY]`, `openai: [OPENAI_API_KEY]`, `gemini: [GEMINI_API_KEY, GOOGLE_API_KEY]` — Gemini's only exception is its own legacy alias, not another provider's key). PR #274 removed an earlier cross-provider fallback as a key-leak risk; don't reintroduce it.
-- **No key on a production browser host → routes through the same-origin smart proxy for the SELECTED provider** (`createBrowserProxyBridge`), not the stub — the proxy holds the real key server-side. **No key anywhere else (Node, local dev, non-production host) → returns `StubLLMAdapter`** (with a console warning). Key present → builds a real bridge.
-- Lazy-loads the adapters via `getCreateClient()` — see "Lazy-load gate" below.
+- Resolves `provider` in precedence order: `opts.provider` → the model id via `detectProviderFromModel(model)` (exported from `adapters/index.ts`) → `LLM_PROVIDER` env → env-key `detectProvider()`. The model id outranking env detection is load-bearing, a model-picker selection ("gemini-2.5-flash") must decide the provider, or every non-default model routes to the env-detected provider's API and 404s (live bug fixed 2026-07-16). Resolves the model from `opts.model` / `LLM_MODEL` env / per-provider `DEFAULT_MODELS`.
+- Reads the API key from `opts.apiKey` or the provider's own `KEY_ENVS` entry, **per-provider isolated**, never a cross-provider fallback chain (`anthropic: [ANTHROPIC_API_KEY]`, `openai: [OPENAI_API_KEY]`, `gemini: [GEMINI_API_KEY, GOOGLE_API_KEY]`, Gemini's only exception is its own legacy alias, not another provider's key). PR #274 removed an earlier cross-provider fallback as a key-leak risk; don't reintroduce it.
+- **No key on a production browser host → routes through the same-origin smart proxy for the SELECTED provider** (`createBrowserProxyBridge`), not the stub, the proxy holds the real key server-side. **No key anywhere else (Node, local dev, non-production host) → returns `StubLLMAdapter`** (with a console warning). Key present → builds a real bridge.
+- Lazy-loads the adapters via `getCreateClient()`, see "Lazy-load gate" below.
 
 The `AdiaUILLMBridge` class re-shapes both directions:
 
-- **`complete()`** calls `chat()` with `maxTokens: 32768` and `cache: provider === 'anthropic'`, then returns `{ content, stopReason, usage: { inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } }` — note the field rename from the facade's `usage.input` to the pipeline's `usage.inputTokens`.
-- **`stream()`** iterates `client.stream()`, re-emits `text` chunks as `{ type: 'text', content }`, and re-emits `done` as `{ type: 'done', stopReason, usage: {…Tokens} }`. Chunk types it doesn't consume (`thinking`, `error`) fall through silently — when you add a chunk type, decide whether the bridge should surface it.
+- **`complete()`** calls `chat()` with `maxTokens: 32768` and `cache: provider === 'anthropic'`, then returns `{ content, stopReason, usage: { inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens } }`, note the field rename from the facade's `usage.input` to the pipeline's `usage.inputTokens`.
+- **`stream()`** iterates `client.stream()`, re-emits `text` chunks as `{ type: 'text', content }`, and re-emits `done` as `{ type: 'done', stopReason, usage: {…Tokens} }`. Chunk types it doesn't consume (`thinking`, `error`) fall through silently, when you add a chunk type, decide whether the bridge should surface it.
 
-### The `maxTokens: 32768` default is intentional — don't lower it
+### The `maxTokens: 32768` default is intentional, don't lower it
 
-Both `complete()` and `stream()` hardcode `maxTokens: 32768`. A2UI JSON for moderately complex UIs (kanban, dashboard, pricing table) routinely exceeds 8k; an 8k cap produced silent truncation that the validator rubber-stamped at ~89/100. The adapters' own `DEFAULT_MAX_TOKENS` (Anthropic + Gemini) is also `32768`. If a new provider has a lower output ceiling, surface it as a model-level constraint in `MODELS` — **do not lower the 32k bridge default**.
+Both `complete()` and `stream()` hardcode `maxTokens: 32768`. A2UI JSON for moderately complex UIs (kanban, dashboard, pricing table) routinely exceeds 8k; an 8k cap produced silent truncation that the validator rubber-stamped at ~89/100. The adapters' own `DEFAULT_MAX_TOKENS` (Anthropic + Gemini) is also `32768`. If a new provider has a lower output ceiling, surface it as a model-level constraint in `MODELS`, **do not lower the 32k bridge default**.
 
-### Lazy-load gate — don't break Node/SSR consumers
+### Lazy-load gate, don't break Node/SSR consumers
 
-`createAdapter` reaches the adapters through `getCreateClient()`, which `await import('./adapters/index.js')` inside a `try`/`catch` (falling back to the stub on failure) and memoizes the result. This is load-bearing: `llm-bridge.ts` is browser/SSR-facing, and a top-level static import of the adapters can throw at module-load time in pure-Node contexts (Vite-alias / `node:` resolution). **If you add a module under `adapters/` that imports `node:` builtins, keep the lazy gate intact** — top-level imports break SSR.
+`createAdapter` reaches the adapters through `getCreateClient()`, which `await import('./adapters/index.js')` inside a `try`/`catch` (falling back to the stub on failure) and memoizes the result. This is load-bearing: `llm-bridge.ts` is browser/SSR-facing, and a top-level static import of the adapters can throw at module-load time in pure-Node contexts (Vite-alias / `node:` resolution). **If you add a module under `adapters/` that imports `node:` builtins, keep the lazy gate intact**, top-level imports break SSR.
 
-## The stub — `StubLLMAdapter`
+## The stub, `StubLLMAdapter`
 
-`llm-stub.ts` is the deterministic, no-API-key adapter pipeline code develops against. It mirrors the bridge's interface — `complete({ messages, systemPrompt })` and `async *stream(request)` — so consumers swap it in transparently.
+`llm-stub.ts` is the deterministic, no-API-key adapter pipeline code develops against. It mirrors the bridge's interface, `complete({ messages, systemPrompt })` and `async *stream(request)`, so consumers swap it in transparently.
 
 Contract the stub must keep:
 
 - **`complete()` returns parseable A2UI.** It builds a canned component tree and returns `{ content: JSON.stringify([{ type: 'updateComponents', surfaceId: 'default', components }]), usage: { inputTokens, outputTokens } }`. The `content` must stay valid A2UI JSON or pipeline parsing breaks.
-- **`stream()` yields the same content as one `text` chunk.** It calls `complete()` and yields `{ type: 'text', content: result.content }` — a single chunk that simulates streaming.
-- **`usage` is a rough estimate.** `estimateTokens` is `~chars/4`; it's deterministic, not exact, and that's fine — the stub exists for offline development, not telemetry fidelity.
+- **`stream()` yields the same content as one `text` chunk.** It calls `complete()` and yields `{ type: 'text', content: result.content }`, a single chunk that simulates streaming.
+- **`usage` is a rough estimate.** `estimateTokens` is `~chars/4`; it's deterministic, not exact, and that's fine, the stub exists for offline development, not telemetry fidelity.
 
-The stub's `complete()` result shape (`{ content, usage: { inputTokens, outputTokens } }`) matches the bridge's `complete()` minus the cache fields — keep them aligned when the bridge's shape changes so the stub stays a drop-in.
+The stub's `complete()` result shape (`{ content, usage: { inputTokens, outputTokens } }`) matches the bridge's `complete()` minus the cache fields, keep them aligned when the bridge's shape changes so the stub stays a drop-in.
 
-## Worked example — `createAdapter()` returns the stub when a key IS set
+## Worked example, `createAdapter()` returns the stub when a key IS set
 
 1. Plan: verify target is a `createAdapter({ provider: 'anthropic', apiKey: '<real>' })` returning an `AdiaUILLMBridge` whose `.provider === 'anthropic'`, and `complete()` returning real `content`.
-2. Execute: trace `createAdapter` — `provider !== 'stub'` so it resolves the key; if the key is falsy it warns and returns the stub. Check the env-var path (`<PROVIDER>_API_KEY` then the Anthropic/OpenAI/Google fallbacks) and confirm `getCreateClient()` didn't fall back to `null` (lazy import failed → stub).
+2. Execute: trace `createAdapter`, `provider !== 'stub'` so it resolves the key; if the key is falsy it warns and returns the stub. Check the env-var path (`<PROVIDER>_API_KEY` then the Anthropic/OpenAI/Google fallbacks) and confirm `getCreateClient()` didn't fall back to `null` (lazy import failed → stub).
 3. Verify: with a real key, `createAdapter` returns a bridge (not a stub), `complete()` returns provider text, and `usage.cacheCreationTokens` / `cacheReadTokens` are populated for Anthropic.
 
 ## Cross-references
 
-- [adapter-contract.md](adapter-contract.md) — what `resolveAdapter` / `buildRequest` / `parseResponse` do
-- [browser-proxy-boundary.md](browser-proxy-boundary.md) — the `proxyUrl` dispatch and the production-host stub path
-- [model-registry.md](model-registry.md) — `DEFAULT_MODEL` vs the bridge's `DEFAULT_MODELS`
-- [streaming-sse.md](streaming-sse.md) — the `StreamChunk` union the bridge re-shapes
+- [adapter-contract.md](adapter-contract.md), what `resolveAdapter` / `buildRequest` / `parseResponse` do
+- [browser-proxy-boundary.md](browser-proxy-boundary.md), the `proxyUrl` dispatch and the production-host stub path
+- [model-registry.md](model-registry.md), `DEFAULT_MODEL` vs the bridge's `DEFAULT_MODELS`
+- [streaming-sse.md](streaming-sse.md), the `StreamChunk` union the bridge re-shapes
 - Source: `packages/llm/core/src/adapters/index.ts`, `packages/llm/core/src/llm-bridge.ts`, `packages/llm/core/src/llm-stub.ts`, `packages/llm/core/src/index.ts`

package/skills/llm-client-maintenance/references/browser-proxy-boundary.md

@@ -13,28 +13,28 @@ This is the single most error-prone area of the package: `proxyUrl` is overloade
 | Mode | When | Body shape | Auth |
 | --- | --- | --- | --- |
 | **Direct** | `proxyUrl` unset | `adapter.buildRequest()` upstream body | Adapter's own auth header (the real key) |
-| **Smart proxy** | `proxyUrl` set, NOT matching the passthrough regex | Provider-neutral `{ provider, model, messages, system?, maxTokens?, temperature?, thinking?, stream }` | `content-type` only — the proxy holds the key server-side |
+| **Smart proxy** | `proxyUrl` set, NOT matching the passthrough regex | Provider-neutral `{ provider, model, messages, system?, maxTokens?, temperature?, thinking?, stream }` | `content-type` only, the proxy holds the key server-side |
 | **Passthrough proxy** | `proxyUrl` matches `/api/llm/<provider>(/...)` | Real upstream body (`adapter.buildRequest()`), URL swapped to the proxy | Adapter's own auth header, forwarded verbatim by the dumb proxy |
 
 The dispatcher (in `index.ts`): `opts.proxyUrl ? (isPassthroughProxy(opts.proxyUrl) ? passthroughRequest(...) : proxyRequest(...)) : adapter.buildRequest(...)`.
 
-## `isPassthroughProxy` — the URL-shape classifier
+## `isPassthroughProxy`, the URL-shape classifier
 
 ```text
 PASSTHROUGH_PROXY_RE = /\/api\/llm\/[a-z]+(\/|$)/
 isPassthroughProxy(url) = typeof url === 'string' && PASSTHROUGH_PROXY_RE.test(url)
 ```
 
-Anything matching `/api/llm/<provider>/` is a **passthrough** proxy (a dumb URL rewriter — e.g. the Vite dev server forwarding to `https://api.<provider>.com/...`). Everything else is treated as a **smart** proxy (a server that speaks the provider-neutral protocol and holds the key). **This regex is the entire contract** between the two flavors — if you change the dev-server proxy path, update the regex, and vice versa.
+Anything matching `/api/llm/<provider>/` is a **passthrough** proxy (a dumb URL rewriter, e.g. the Vite dev server forwarding to `https://api.<provider>.com/...`). Everything else is treated as a **smart** proxy (a server that speaks the provider-neutral protocol and holds the key). **This regex is the entire contract** between the two flavors, if you change the dev-server proxy path, update the regex, and vice versa.
 
-## `proxyRequest` vs `passthroughRequest` — the two builders
+## `proxyRequest` vs `passthroughRequest`, the two builders
 
-- **`proxyRequest(opts, stream)`** builds the provider-neutral body `{ provider, model, messages, stream }` plus the optional `system` / `maxTokens` / `temperature` / `thinking`, with headers `content-type: application/json` only. **No `apiKey` in the body** — the smart proxy holds the key. URL is `opts.proxyUrl`.
-- **`passthroughRequest(opts, stream)`** calls `adapter.buildRequest({ ...opts, stream })` (the real upstream body + the adapter's auth headers) and then swaps ONLY the upstream **origin**: the proxy prefix (everything in `proxyUrl` up to the `/api/llm/<provider>` segment) is joined with `buildRequest()`'s own path + query. This preserves URL-encoded routing — gemini carries `models/<model>:<action>?alt=sse` in the path; overwriting the whole URL with a static `proxyUrl` (the pre-2026-07-16 behavior) dropped it and every gemini passthrough call hit the proxy root.
+- **`proxyRequest(opts, stream)`** builds the provider-neutral body `{ provider, model, messages, stream }` plus the optional `system` / `maxTokens` / `temperature` / `thinking`, with headers `content-type: application/json` only. **No `apiKey` in the body**: the smart proxy holds the key. URL is `opts.proxyUrl`.
+- **`passthroughRequest(opts, stream)`** calls `adapter.buildRequest({ ...opts, stream })` (the real upstream body + the adapter's auth headers) and then swaps ONLY the upstream **origin**: the proxy prefix (everything in `proxyUrl` up to the `/api/llm/<provider>` segment) is joined with `buildRequest()`'s own path + query. This preserves URL-encoded routing, gemini carries `models/<model>:<action>?alt=sse` in the path; overwriting the whole URL with a static `proxyUrl` (the pre-2026-07-16 behavior) dropped it and every gemini passthrough call hit the proxy root.
 
 So `buildRequest()` is the single source of upstream shape for BOTH direct mode and passthrough mode (see `adapter-contract.md`). The only thing passthrough changes is the URL origin. **Don't fork `buildRequest` for proxy mode.**
 
-## The browser bridge — `resolveBaseUrl` + the proxy map
+## The browser bridge, `resolveBaseUrl` + the proxy map
 
 In the browser, `llm-bridge.ts` routes through a same-origin passthrough proxy. `resolveBaseUrl(provider)` returns `undefined` outside the browser (let the adapter use its default upstream URL) and, in the browser, maps provider → prefix (the upstream API path comes from `buildRequest()`, never from this map):
 
@@ -44,21 +44,21 @@ openai    → /api/llm/openai
 gemini    → /api/llm/gemini
 ```
 
-A `proxyUrl` that already includes the API path (the legacy `/api/llm/anthropic/v1/messages` shape) still works — the prefix extraction stops at the provider segment and re-appends the identical upstream path.
+A `proxyUrl` that already includes the API path (the legacy `/api/llm/anthropic/v1/messages` shape) still works, the prefix extraction stops at the provider segment and re-appends the identical upstream path.
 
 These paths match `PASSTHROUGH_PROXY_RE`, so the facade routes them through `passthroughRequest`. **A new browser-routable provider needs a `resolveBaseUrl` entry whose path matches the passthrough regex.**
 
-## Production-host path — real calls with no client key
+## Production-host path, real calls with no client key
 
 `isProductionHost()` returns `true` when the browser is on a non-local host (not `localhost` / `127.0.0.1` / `0.0.0.0` / `*.local` / private `10.` / `192.168.` / `172.16–31.` ranges). When `createAdapter()` detects `provider === 'stub'` (no env vars in the browser) BUT `IS_BROWSER && isProductionHost()`, it calls `createBrowserProxyBridge('anthropic', …)` instead of returning the stub:
 
 - It builds a real client with a **sentinel** `apiKey: 'browser-uses-server-side-proxy-key'` so the non-empty-key check passes.
-- The sentinel **never reaches the upstream provider** — the same-origin proxy strips the incoming auth header and injects its own server-side key.
+- The sentinel **never reaches the upstream provider**, the same-origin proxy strips the incoming auth header and injects its own server-side key.
 - This is how a deployed app makes real LLM calls without ever exposing a key to the browser.
 
 **Preserve this path.** Removing it makes production browsers fall back to the stub (canned UI) instead of real generation.
 
-## Key-in-browser safety — the one-shot warning
+## Key-in-browser safety, the one-shot warning
 
 In direct/passthrough browser mode with a real `apiKey`, the key is sent verbatim in `x-api-key` / `Authorization` headers and is readable in DevTools. `createAdapter()` logs a styled, deduplicated (window-flag `__adia_llm_key_warning_shown`) warning naming the provider and a masked key, stating this is local-dev only. This is intentional friction:
 
@@ -67,13 +67,13 @@ In direct/passthrough browser mode with a real `apiKey`, the key is sent verbati
 
 Keep the warning and the dedup flag when touching `createAdapter()`.
 
-## Worked example — "401 in the browser, but `node` works fine"
+## Worked example, "401 in the browser, but `node` works fine"
 
 1. Plan: verify target is a real browser `streamChat()` through the proxy returning `text` deltas, and the same call in Node (direct) succeeding.
-2. Execute — the usual cause is a proxy-flavor mismatch:
+2. Execute: the usual cause is a proxy-flavor mismatch:
    - Is `proxyUrl` matching `PASSTHROUGH_PROXY_RE`? If the dev server is a passthrough but the URL doesn't match the regex, the facade builds a provider-neutral body and sends it to a dumb proxy that expects the raw upstream shape → upstream 401/400.
    - For passthrough, confirm the adapter's auth header is present (`passthroughRequest` forwards `buildRequest` headers). For smart proxy, confirm NO key is in the body and the server injects it.
-   - SSE buffering: a proxy that buffers responses breaks streaming — confirm the proxy flushes SSE (this is a transport bug, surfaced as a "never emits `done`" in `streaming-sse.md`).
+   - SSE buffering: a proxy that buffers responses breaks streaming, confirm the proxy flushes SSE (this is a transport bug, surfaced as a "never emits `done`" in `streaming-sse.md`).
 3. Verify: browser `streamChat()` streams; Node direct works; no real key is visible in the browser Network panel on a production host.
 
 ## Pitfalls
@@ -85,7 +85,7 @@ Keep the warning and the dedup flag when touching `createAdapter()`.
 
 ## Cross-references
 
-- [adapter-contract.md](adapter-contract.md) — `buildRequest()` as the single upstream-shape source
-- [bridge-facade.md](bridge-facade.md) — `createAdapter()` and the stub fallback
-- [streaming-sse.md](streaming-sse.md) — SSE-through-a-proxy buffering symptoms
+- [adapter-contract.md](adapter-contract.md), `buildRequest()` as the single upstream-shape source
+- [bridge-facade.md](bridge-facade.md), `createAdapter()` and the stub fallback
+- [streaming-sse.md](streaming-sse.md), SSE-through-a-proxy buffering symptoms
 - Source: `isPassthroughProxy` / `proxyRequest` / `passthroughRequest` in `packages/llm/core/src/adapters/index.ts`; `resolveBaseUrl` / `isProductionHost` / `createBrowserProxyBridge` in `packages/llm/core/src/llm-bridge.ts`

package/skills/llm-client-maintenance/references/model-registry.md

@@ -2,15 +2,15 @@
 
 The shared model catalog and provider detection. Source: `packages/llm/core/src/models.ts` (the `MODELS` catalog + `DEFAULT_MODEL`) and the `detectProvider()` function in `packages/llm/core/src/adapters/index.ts`.
 
-Concrete ids/groups below are a snapshot verified against the source on 2026-07-10 — on any conflict, the source wins.
+Concrete ids/groups below are a snapshot verified against the source on 2026-07-10, on any conflict, the source wins.
 
 ---
 
 ## What the registry is for
 
-`models.ts` is the one source for the model list three surfaces previously duplicated. It is exported as a subpath (`@adia-ai/llm/models`) and as a top-level re-export from `index.ts`. Its consumer is the `<chat-input-ui>` web-module's `models` setter — a grouped-options structure rendered by an internal `<select-ui>` with `<optgroup>`s.
+`models.ts` is the one source for the model list three surfaces previously duplicated. It is exported as a subpath (`@adia-ai/llm/models`) and as a top-level re-export from `index.ts`. Its consumer is the `<chat-input-ui>` web-module's `models` setter, a grouped-options structure rendered by an internal `<select-ui>` with `<optgroup>`s.
 
-## The `MODELS` shape — do not deviate
+## The `MODELS` shape, do not deviate
 
 `models.ts` exports:
 
@@ -23,9 +23,9 @@ DEFAULT_MODEL: string
 
 `MODELS` is a 2-D grouped array: an outer list of provider groups, each with a `label` (the provider name shown as the `<optgroup>` label) and an `options[]` of `{ value, label }` pairs (the `value` is the model id sent to the API; the `label` is the human display name).
 
-**This exact shape is a contract.** The `<chat-input-ui>.models` setter expects `[{ label, options: [{ value, label }] }]`. Flattening it, renaming the keys, or nesting differently breaks the chat input. The current groups (as authored in `models.ts`) are `Anthropic`, `OpenAI`, `Google` — adding a group is additive; restructuring is breaking.
+**This exact shape is a contract.** The `<chat-input-ui>.models` setter expects `[{ label, options: [{ value, label }] }]`. Flattening it, renaming the keys, or nesting differently breaks the chat input. The current groups (as authored in `models.ts`) are `Anthropic`, `OpenAI`, `Google`, adding a group is additive; restructuring is breaking.
 
-## `DEFAULT_MODEL` — keep it cheap and present
+## `DEFAULT_MODEL`, keep it cheap and present
 
 `DEFAULT_MODEL` is the value `<chat-input-ui>` selects on load. Two rules:
 
@@ -43,25 +43,25 @@ When a `chat()` / `streamChat()` call omits an explicit `provider`, the facade i
 | `gemini` | includes `gemini` OR starts with `google/` |
 | `null` | none of the above → the facade throws "Cannot detect provider…; set provider explicitly" |
 
-**So a new model id in `MODELS` must either match an existing `detectProvider` branch or ship with a new branch** — otherwise every consumer that relies on auto-detection breaks for that model. When you add a provider, add both the `MODELS` group AND the `detectProvider` branch (see `add-a-provider.md`).
+**So a new model id in `MODELS` must either match an existing `detectProvider` branch or ship with a new branch**, otherwise every consumer that relies on auto-detection breaks for that model. When you add a provider, add both the `MODELS` group AND the `detectProvider` branch (see `add-a-provider.md`).
 
 Note the two id-naming conventions both flow through detection: a substring convention (`claude…`, `gpt…`, `gemini…`) and a `provider/model` prefix convention (`anthropic/…`, `openai/…`, `google/…`). A new provider should support both for forward-compatibility.
 
-## The bridge's `DEFAULT_MODELS` is a separate map — keep it in sync
+## The bridge's `DEFAULT_MODELS` is a separate map, keep it in sync
 
-`llm-bridge.ts` carries its own `DEFAULT_MODELS` (per-provider fallback used by `createAdapter()` when no model is supplied — e.g. `anthropic → claude-sonnet-4-6`, `openai → gpt-4o`, `gemini → gemini-2.5-flash`). This is **distinct** from `models.ts`'s `DEFAULT_MODEL` (the chat-input default). They serve different surfaces. **The bridge's map MUST be keyed by the adapters-registry keys** (`anthropic`/`openai`/`gemini`) — a 2026-07-16 live bug (gh#268 L-1) came from the bridge keying `google` while the registry keyed `gemini`: `createAdapter({provider:'google'})` always threw, and auto-detection returned an always-throwing bridge. `'google'` survives only as a normalized-away input alias in `createAdapter()`:
+`llm-bridge.ts` carries its own `DEFAULT_MODELS` (per-provider fallback used by `createAdapter()` when no model is supplied, e.g. `anthropic → claude-sonnet-4-6`, `openai → gpt-4o`, `gemini → gemini-2.5-flash`). This is **distinct** from `models.ts`'s `DEFAULT_MODEL` (the chat-input default). They serve different surfaces. **The bridge's map MUST be keyed by the adapters-registry keys** (`anthropic`/`openai`/`gemini`), a 2026-07-16 live bug (gh#268 L-1) came from the bridge keying `google` while the registry keyed `gemini`: `createAdapter({provider:'google'})` always threw, and auto-detection returned an always-throwing bridge. `'google'` survives only as a normalized-away input alias in `createAdapter()`:
 
-- `models.ts:DEFAULT_MODEL` — what the chat-input UI pre-selects (cheap/fast).
-- `llm-bridge.ts:DEFAULT_MODELS[provider]` — what `createAdapter()` falls back to per provider when the caller passes none.
+- `models.ts:DEFAULT_MODEL`, what the chat-input UI pre-selects (cheap/fast).
+- `llm-bridge.ts:DEFAULT_MODELS[provider]`, what `createAdapter()` falls back to per provider when the caller passes none.
 
 When you add a provider, add an entry to the bridge's `DEFAULT_MODELS` too (see `bridge-facade.md`). When you retire a model id, check both maps.
 
-## Worked example — adding a model to an existing provider
+## Worked example, adding a model to an existing provider
 
 Add a new Anthropic model to the chat-input dropdown.
 
 1. Plan: verify target is `npm run build -w @adia-ai/llm` (the package compiles) plus a `chat()` with the new id resolving to the `anthropic` provider and returning text.
-2. Execute: add `{ value: '<new-claude-id>', label: '<display name>' }` to the `Anthropic` group's `options[]` in `models.ts`. No `detectProvider` change needed — the id includes `claude`, so the existing branch matches.
+2. Execute: add `{ value: '<new-claude-id>', label: '<display name>' }` to the `Anthropic` group's `options[]` in `models.ts`. No `detectProvider` change needed, the id includes `claude`, so the existing branch matches.
 3. Verify: the build passes; the `MODELS` shape is unchanged structurally; a `chat({ model: '<new-claude-id>', … })` with no explicit provider resolves Anthropic and returns non-empty `text`. If `DEFAULT_MODEL` should point at the new id, confirm it's a value that now exists.
 
 ## Pitfalls
@@ -72,6 +72,6 @@ Add a new Anthropic model to the chat-input dropdown.
 
 ## Cross-references
 
-- [bridge-facade.md](bridge-facade.md) — `createAdapter()` and its per-provider `DEFAULT_MODELS`
-- [add-a-provider.md](add-a-provider.md) — the recipe that adds a `MODELS` group + a `detectProvider` branch together
+- [bridge-facade.md](bridge-facade.md), `createAdapter()` and its per-provider `DEFAULT_MODELS`
+- [add-a-provider.md](add-a-provider.md), the recipe that adds a `MODELS` group + a `detectProvider` branch together
 - Source: `packages/llm/core/src/models.ts`, `detectProvider()` in `packages/llm/core/src/adapters/index.ts`, `DEFAULT_MODELS` in `packages/llm/core/src/llm-bridge.ts`