@adia-ai/adia-ui-forge 0.1.2

package/skills/adia-ui-llm/references/model-registry.md

@@ -0,0 +1,75 @@
+# Model registry — mode 4
+
+The shared model catalog and provider detection. Source: `packages/llm/src/models.ts` (the `MODELS` catalog + `DEFAULT_MODEL`) and the `detectProvider()` function in `packages/llm/src/adapters/index.ts`.
+
+---
+
+## 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.
+
+## The `MODELS` shape — do not deviate
+
+`models.ts` exports:
+
+```text
+ModelOption = { value: string; label: string }
+ModelGroup  = { label: string; options: ModelOption[] }
+MODELS: ModelGroup[]
+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.
+
+## `DEFAULT_MODEL` — keep it cheap and present
+
+`DEFAULT_MODEL` is the value `<chat-input-ui>` selects on load. Two rules:
+
+- **It must be a `value` that exists somewhere in `MODELS`.** A `DEFAULT_MODEL` that no group lists leaves the select with nothing selected.
+- **Default to the cheapest/fastest option, not a flagship.** Most consumers want fast/cheap by default; a flagship default is a cost surprise. The current default in `models.ts` is the Haiku-tier Anthropic id.
+
+## Model ids must be resolvable by `detectProvider()`
+
+When a `chat()` / `streamChat()` call omits an explicit `provider`, the facade infers it from the model id via `detectProvider(model)` in `index.ts`. The current rules (case-insensitive on the id):
+
+| Returns | Matches when the id… |
+| --- | --- |
+| `anthropic` | includes `claude` OR starts with `anthropic/` |
+| `openai` | includes `gpt` / `o1` / `o3` / `o4` OR starts with `openai/` |
+| `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`).
+
+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
+
+`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-…`, `openai → gpt-4o`, `google → gemini-2.0-flash`). This is **distinct** from `models.ts`'s `DEFAULT_MODEL` (the chat-input default). They serve different surfaces:
+
+- `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
+
+Add a new Anthropic model to the chat-input dropdown.
+
+1. Plan: verify target is `npm run build` (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.
+3. Verify: `npm run 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
+
+- **A model id that `detectProvider` can't classify.** Adding `{ value: 'mystery-1' }` with no matching branch makes auto-detection throw for that model. Either name it to match a branch or add a branch.
+- **Reordering groups for "cleanliness".** The order is the dropdown order; reordering is a visible UI change, not a no-op.
+- **Treating `DEFAULT_MODEL` and the bridge `DEFAULT_MODELS` as the same thing.** They're two maps for two surfaces; a "default model" change usually means deciding which one you mean.
+
+## 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
+- Source: `packages/llm/src/models.ts`, `detectProvider()` in `packages/llm/src/adapters/index.ts`, `DEFAULT_MODELS` in `packages/llm/src/llm-bridge.ts`

package/skills/adia-ui-llm/references/streaming-sse.md

@@ -0,0 +1,95 @@
+# Streaming + SSE — mode 3
+
+The streaming protocol and the shared SSE parser. Source: `packages/llm/src/adapters/sse.ts` (the parser) and the `parseStream` method of each adapter in `packages/llm/src/adapters/anthropic.ts` / `openai.ts` / `gemini.ts`. The `StreamChunk` union is declared in `anthropic.ts`.
+
+---
+
+## The `StreamChunk` union — the streaming contract
+
+`streamChat()` and `client.stream()` yield this union (declared in `anthropic.ts`, re-exported from `index.ts`):
+
+```text
+StreamChunk =
+  | { type: 'text';     text: string; snapshot: string }
+  | { type: 'thinking'; text: string }
+  | { type: 'done';     text: string; usage: AdapterUsage; stopReason: string }
+  | { type: 'error';    error: Error }
+```
+
+Contract rules consumers depend on:
+
+- **`text` chunks carry both the delta and the running `snapshot`.** `text` is the new fragment; `snapshot` is the full text accumulated so far. A consumer can render incrementally (`text`) or replace wholesale (`snapshot`).
+- **Exactly one terminal.** A stream ends with a `done` chunk (carrying final `text`, `usage`, raw `stopReason`) OR an `error` chunk — never both, never neither on success.
+- **`thinking` is optional and may interleave.** Anthropic + OpenAI emit it; Gemini doesn't. Consumers ignore it safely but must not crash.
+- **`error` is a chunk, not a throw.** `streamChat()` catches a `fetch` failure and a non-`ok` response and yields `{ type: 'error', error }` rather than throwing (see `index.ts` `streamChat`). The consumer must handle the `error` chunk; a dropped `error` is a defect.
+
+Adding a new chunk type (e.g., a tool-call chunk) is additive but touches every consumer — see "Adding a chunk type" below.
+
+## Where the terminal `done` comes from — per provider
+
+The terminal differs by provider, which matters when you debug a missing `done`:
+
+| Provider | Terminal source (`parseStream`) |
+| --- | --- |
+| Anthropic | An explicit `message_stop` SSE event yields `done`; `message_delta` sets `stopReason` + `usage.output` first |
+| OpenAI | No terminal event — `parseStream` yields `done` after the SSE loop completes (the `[DONE]` sentinel ends the loop) |
+| Gemini | No terminal event — `done` yielded after the loop; `stopReason` is the constant `'end'` |
+
+So Anthropic's `done` is event-driven; OpenAI and Gemini synthesize it after the byte stream closes. A new adapter picks whichever matches its provider — but it MUST yield exactly one `done` on success.
+
+## The shared SSE parser — `readSSE`
+
+`sse.ts` exports `async function* readSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEEvent>` where:
+
+```text
+SSEEvent = { event: string | undefined; data: string; done: boolean }
+```
+
+What it handles — and why each matters:
+
+- **Partial-line buffering.** It decodes with `{ stream: true }` and keeps a `buffer`; an event split across two network chunks is reassembled. Don't re-implement line splitting in an adapter — consume `readSSE`.
+- **Double-newline framing.** Events are split on `\n\n` or `\r\n\r\n`; the trailing partial is carried as `remainder`.
+- **Field parsing.** Lines starting with `event:` set the event type; lines starting with `data:` append (one leading space stripped per the SSE spec); comment lines (`:`) are skipped.
+- **Multi-line data.** Multiple `data:` lines in one event are joined with `\n`.
+- **`[DONE]` detection.** An event whose joined data equals `[DONE]` gets `done: true`. Each adapter's `parseStream` does `if (event.done) break;` at the top of the loop.
+- **Flush.** After the reader closes, a non-empty trailing buffer is parsed once more (with an appended `\n\n`) so a final unterminated event isn't lost.
+
+`readSSE` releases the reader lock in a `finally`. An adapter must guard `if (!response.body) throw new Error('Response body is null')` before calling it (all three do).
+
+## How an adapter consumes events
+
+The shape every `parseStream` follows (grounded in `anthropic.ts`):
+
+1. Guard `response.body`; init `snapshot = ''`, `usage`, `stopReason`.
+2. `for await (const event of readSSE(response.body))` → `if (event.done) break;`.
+3. `JSON.parse(event.data)` in a `try`/`catch` — a malformed frame is skipped (`catch { continue; }`), never fatal.
+4. Branch on the event type. For Anthropic, `event.event ?? data.type` selects the SSE event (`message_start` / `content_block_delta` / `message_delta` / `message_stop` / `error`). OpenAI/Gemini branch on the JSON body shape (`choices[0].delta` / `candidates[0].content.parts`).
+5. On a text delta: `snapshot += delta; yield { type: 'text', text: delta, snapshot };`.
+6. On terminal: `yield { type: 'done', text: snapshot, usage, stopReason };`.
+
+`usage` accumulates across events — e.g. Anthropic sets `input` + cache fields at `message_start` and `output` at `message_delta`, so the `done` chunk carries the complete tally.
+
+## Worked example — "streamChat never emits `done`"
+
+1. Plan: verify target is a real `streamChat()` against the affected provider, asserting the last chunk is `{ type: 'done' }` with non-zero `usage`.
+2. Execute — bisect by layer:
+   - Is `readSSE` framing the events? Log raw `SSEEvent`s — if they arrive but the adapter yields no `done`, the bug is in the adapter's terminal branch.
+   - Anthropic: confirm a `message_stop` event actually arrives (event-driven terminal). OpenAI/Gemini: confirm the loop exits (a `[DONE]` or a closed body) so the post-loop `done` yields.
+   - If frames don't arrive at all, the proxy may be buffering SSE (see `browser-proxy-boundary.md`) — that's a transport bug, not a parser bug.
+3. Verify: a forced `streamChat()` shows ordered `text` deltas, a growing `snapshot`, and exactly one terminal `done`.
+
+## Adding a new chunk type
+
+A new `StreamChunk` variant (e.g. `{ type: 'tool_call'; ... }`):
+
+1. Add the variant to the union in `anthropic.ts` (the canonical type).
+2. Emit it from the adapters that support it; leave the others unchanged.
+3. **Audit every consumer.** The two named consumers are the adia-ui chat-shell and the A2UI generation pipeline (via `createAdapter()` — see `bridge-facade.md`). Confirm each either handles the new type or falls through gracefully (the bridge's `stream()` already ignores chunk types it doesn't consume).
+4. This is additive but consumer-visible — note it in CHANGELOG as a MINOR bump.
+
+## Cross-references
+
+- [adapter-contract.md](adapter-contract.md) — the adapter object, `parseResponse`, and the `usage` / `stopReason` mapping
+- [bridge-facade.md](bridge-facade.md) — how the bridge re-shapes `StreamChunk` for the adia-ui pipeline
+- [browser-proxy-boundary.md](browser-proxy-boundary.md) — SSE through a proxy (buffering pitfalls)
+- Source: `packages/llm/src/adapters/sse.ts`, and the `parseStream` of `anthropic.ts` / `openai.ts` / `gemini.ts`

package/skills/adia-ui-llm/references/teach-protocol.md

@@ -0,0 +1,78 @@
+# §Teach protocol — mode 8
+
+The extensibility binding for "make sure `adia-ui-llm` knows about X" / "train the skill on a new provider quirk" / "absorb this adapter pitfall into adia-ui-llm". This is the producer-side teach surface: it lands knowledge about MAINTAINING `@adia-ai/llm`, never about consuming it (consumer knowledge routes to the separate `adia-ui-factory` consumer skill).
+
+The decision tree below is mechanized in `scripts/teach-route.mjs` (the authoritative routing); this prose mirrors the branches for human readers and adds worked examples + anti-patterns.
+
+---
+
+## The first question — does it land in the skill at all?
+
+The skill is a CITATION layer, not a KNOWLEDGE layer. Much "new knowledge" about the LLM client is actually a **source edit**, not a skill edit:
+
+- A new field in a provider's response mapping → edit `packages/llm/src/adapters/<name>.ts` (`parseResponse` / `parseStream`). The skill changes only if a cross-adapter RULE changed.
+- A new model id → edit `packages/llm/src/models.ts`. The skill changes only if a registry rule changed (e.g. a new id-naming convention `detectProvider` must learn).
+- A new default → edit the source map (`models.ts:DEFAULT_MODEL` or `llm-bridge.ts:DEFAULT_MODELS`). The skill cites the maps; it doesn't store the values.
+
+If the payload is a fact the source already encodes (or should), the landing is the source — and the skill may not change at all. Land a skill patch only when the knowledge is a durable RULE, pitfall, or procedure a maintainer needs surfaced.
+
+## The decision tree (branches)
+
+First match wins. The landing is a reference file in this skill's `references/` directory (named bare below), or a non-reference landing (`(source)` / `(journal)` / `SKILL.md`). The mechanized router in `scripts/teach-route.mjs` emits the same target as a skill-root-relative path.
+
+| Branch | Fires when the payload is about… | Landing |
+| --- | --- | --- |
+| `source-edit` | a per-adapter field/value the source encodes (response field, a model id, a default value) | `(source) packages/llm/src/...` — not a skill landing |
+| `add-provider` | a new step or gotcha in adding a 4th provider | `add-a-provider.md` |
+| `streaming` | the SSE parser, the `StreamChunk` protocol, a chunk-type, `[DONE]` / framing | `streaming-sse.md` |
+| `model-registry` | the `MODELS` shape, `DEFAULT_MODEL`, `detectProvider` rules | `model-registry.md` |
+| `bridge-facade` | `chat`/`streamChat`/`createClient`, `createAdapter`, the bridge, the stub, `maxTokens`, lazy-load | `bridge-facade.md` |
+| `proxy-boundary` | smart vs passthrough proxy, the production-host path, key-in-browser safety | `browser-proxy-boundary.md` |
+| `adapter-contract` | a cross-adapter shape rule, `usage` mapping, raw `stopReason`, `buildRequest` discipline (DEFAULT) | `adapter-contract.md` |
+| `methodology` | a posture / mission shift or a new §SelfAudit axis | `SKILL.md` (inline) |
+| `journal` | a one-off debugging arc story (NEGATIVE — not the skill) | `(journal)` |
+
+`adapter-contract` is the default branch: an unclassified maintenance fact most often belongs with the adapter contract, and re-classifies from there.
+
+## The five-step landing procedure
+
+1. **Audit before patching.** Run `node scripts/audit-llm-roster.mjs` to confirm the skill is drift-free first; you don't want to land a patch on top of existing drift.
+2. **Author the patch** in the branch's target file. Keep it a citation — name the `packages/llm/src/...` path + type, don't paste the code.
+3. **Wire the activation surface.** If the patch adds a capability, add/adjust the §ColdStartTriage row or a §Posture line so the knowledge is reachable. An orphaned reference nobody routes to is dead weight.
+4. **Version + CHANGELOG.** Bump `skill.json` + the SKILL.md frontmatter `version` together (one MINOR for a new rule/capability; one PATCH for a clarification — never bundle both into one bump), and prepend a CHANGELOG entry.
+5. **Verify.** Run `node scripts/audit-llm-roster.mjs --strict` (0 drift) AND close the PEV loop — the underlying knowledge should be verifiable against the real package (`npm run build` + a `chat()` / stub round-trip). See `## §Plan-Execute-Verify` in SKILL.md.
+
+## Anti-patterns
+
+- **Append-only landing.** Tacking a paragraph onto the nearest file without checking whether it duplicates an existing rule or belongs in the source. Audit first.
+- **Source duplication.** Restating what an adapter's `parseResponse` already encodes. If the source is the truth, cite it; don't copy it into prose that will drift.
+- **Orphan triggers.** A new reference with no §ColdStartTriage row or posture line pointing at it.
+- **Capability-menu lies.** A menu row promising a mode whose reference doesn't cover it.
+- **MINOR + PATCH bundling.** Two unrelated changes in one version bump muddies the CHANGELOG.
+- **One-way thinking.** The most common producer-side miss: the payload is actually CONSUMER knowledge ("how do I wire `<chat-shell-ui>`", "what proxy do I deploy"). That does not land here — it belongs to the `adia-ui-factory` consumer `adia-ui-llm` skill. Route it there instead of forcing it into this producer skill.
+
+## Worked examples
+
+### Example A — "the openai adapter should map `length` finish_reason to a truncation signal"
+
+- Route: this is about `stopReason` handling across adapters → `adapter-contract` branch.
+- But check the source first: `openai.ts` already passes non-`stop` finish reasons through raw (only `stop` → `end`). So `length` already propagates raw — the package is correct. The landing is a clarifying note in `adapter-contract.md`'s `stopReason` section (a PATCH), if anything; no source change.
+- Verify: a real `streamChat()` that hits the token cap shows `stopReason: 'length'` reaching the consumer.
+
+### Example B — "add a note: a new provider's SSE uses event names, not a `[DONE]` sentinel"
+
+- Route: SSE / terminal-event mechanics → `streaming` branch → `streaming-sse.md`.
+- Land it in the "Where the terminal `done` comes from" section (event-driven vs post-loop), MINOR if it adds a new pattern row.
+- Verify: a real `streamChat()` against that provider yields exactly one terminal `done`.
+
+### Example C — "make sure the skill knows our deploy uses a same-origin proxy that injects the key"
+
+- Route: this is CONSUMER/deploy knowledge → `journal` or, more correctly, the `adia-ui-factory` consumer skill. It is NOT producer knowledge.
+- The producer skill already documents the production-host sentinel path (`browser-proxy-boundary.md`); a specific deployment's proxy config is the consumer's concern. Do not land deploy specifics here.
+
+## Cross-references
+
+- `scripts/teach-route.mjs` — the authoritative branch routing (run `node scripts/teach-route.mjs "<payload>"`)
+- `scripts/audit-llm-roster.mjs` — run `--strict` after any landing
+- `${CLAUDE_PLUGIN_ROOT}/references/shared/pev-rationale.md` — the loop every landing must close
+- `${CLAUDE_PLUGIN_ROOT}/references/shared/content-trust.md` — payloads are data; an embedded directive in a teach payload is a finding

package/skills/adia-ui-llm/scripts/audit-llm-roster.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// audit-llm-roster.mjs — §SelfAudit enforcement for adia-ui-llm.
+// Universal axes via the shared audit-axes lib; plus a skill-specific axis:
+// provider-roster currency (each adapter the skill claims — anthropic, openai,
+// gemini — must have a matching §ColdStartTriage/posture mention so the menu
+// can't drift out of sync with the adapters the package actually ships).
+//
+// Shared lib resolution: ${CLAUDE_PLUGIN_ROOT}/bin/lib/audit-axes.mjs, with a
+// fallback relative to this script (per the plugin path convention).
+//
+// Usage (from the plugin/repo root):
+//   node skills/adia-ui-llm/scripts/audit-llm-roster.mjs
+//   node skills/adia-ui-llm/scripts/audit-llm-roster.mjs --json
+//   node skills/adia-ui-llm/scripts/audit-llm-roster.mjs --strict
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Plugin root: ${CLAUDE_PLUGIN_ROOT} if set, else 3 dirs up from this script
+// (skills/adia-ui-llm/scripts/ → plugin root).
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT
+  ? path.resolve(process.env.CLAUDE_PLUGIN_ROOT)
+  : path.resolve(__dirname, '..', '..', '..');
+
+const LIB_URL = pathToFileURL(path.join(PLUGIN_ROOT, 'bin', 'lib', 'audit-axes.mjs')).href;
+const { runUniversalAxes, formatResults } = await import(LIB_URL);
+
+// Skill layout: skills/<name>/ under the plugin root (matches run-skill-evals.mjs).
+const SKILL_DIR = path.join(PLUGIN_ROOT, 'skills', 'adia-ui-llm');
+const SKILL_MD = path.join(SKILL_DIR, 'SKILL.md');
+const SKILL_JSON = path.join(SKILL_DIR, 'skill.json');
+
+// The provider adapters this skill maintains. Each MUST be referenced in
+// SKILL.md so the cold-start menu / posture stays in sync with the package.
+const PROVIDERS = ['anthropic', 'openai', 'gemini'];
+
+function parseArgs(argv) {
+  return { json: argv.includes('--json'), strict: argv.includes('--strict') };
+}
+
+function readSafe(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+function axisProviderRosterCurrency() {
+  const md = readSafe(SKILL_MD);
+  const findings = [];
+  for (const name of PROVIDERS) {
+    if (md.includes(name)) {
+      findings.push({ type: 'provider-present', message: `${name}: referenced in SKILL.md — correct`, name });
+    } else {
+      findings.push({
+        type: 'provider-missing',
+        message: `${name}: adapter is shipped by the package but not referenced in SKILL.md`,
+        name,
+      });
+    }
+  }
+  const driftCount = findings.filter(f => f.type !== 'provider-present').length;
+  return {
+    axis: 'providerRosterCurrency',
+    axis_num: 9,
+    status: driftCount > 0 ? 'drift' : 'ok',
+    findings,
+    summary: driftCount > 0 ? `${driftCount} provider(s) unreferenced` : 'all adapters referenced in SKILL.md',
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const ctx = { skillDir: SKILL_DIR, skillMd: SKILL_MD, skillJson: SKILL_JSON, repoRoot: PLUGIN_ROOT };
+  const { results: universal } = runUniversalAxes(ctx);
+  const axis9 = axisProviderRosterCurrency();
+  const allResults = [...universal, axis9];
+  const driftCount = allResults.filter(r => r.status === 'drift').length;
+
+  if (args.json) {
+    console.log(JSON.stringify({ results: allResults, driftCount }, null, 2));
+    if (args.strict && driftCount > 0) process.exit(1);
+    return;
+  }
+
+  console.log(`[audit-llm-roster] adia-ui-llm §SelfAudit — ${driftCount} drifting axis/axes`);
+  console.log(formatResults(allResults));
+  if (driftCount === 0) console.log('\n✓ All clean.');
+  if (args.strict && driftCount > 0) process.exit(1);
+}
+
+main();

package/skills/adia-ui-llm/scripts/teach-route.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// teach-route.mjs — Mechanized §Teach decision tree for adia-ui-llm.
+// Maps a "make sure the skill knows about X" payload to its landing target.
+// Composes from the shared teach-router lib; the prose tree in
+// references/teach-protocol.md mirrors these branches for human readers.
+//
+// Shared lib resolution: ${CLAUDE_PLUGIN_ROOT}/bin/lib/teach-router.mjs, with a
+// fallback relative to this script.
+//
+// Usage (from the plugin/repo root):
+//   node skills/adia-ui-llm/scripts/teach-route.mjs "add a new provider adapter"
+//   node skills/adia-ui-llm/scripts/teach-route.mjs --list
+//   node skills/adia-ui-llm/scripts/teach-route.mjs --payload="<payload>" [--json]
+
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT
+  ? path.resolve(process.env.CLAUDE_PLUGIN_ROOT)
+  : path.resolve(__dirname, '..', '..', '..');
+
+const LIB_URL = pathToFileURL(path.join(PLUGIN_ROOT, 'bin', 'lib', 'teach-router.mjs')).href;
+const { buildRouter, describeRouter } = await import(LIB_URL);
+
+// Branches: first match wins. `target` is the landing file (relative to skill
+// root) — or "(source)" / "(journal)" / "SKILL.md" for non-reference landings.
+// Mirrors the table in references/teach-protocol.md.
+export const branches = [
+  {
+    id: 'source-edit',
+    label: 'Per-adapter field/value the source encodes (NOT a skill landing)',
+    match: [/response field/i, /model id/i, 'default value', /new field/i, 'source edit', 'parseresponse field'],
+    target: '(source) packages/llm/src/',
+    confidence: 'high',
+  },
+  {
+    id: 'add-provider',
+    label: 'New step / gotcha in adding a 4th provider',
+    match: ['add a provider', 'add a new provider', '4th provider', 'fourth provider', 'new adapter step'],
+    target: 'references/add-a-provider.md',
+    confidence: 'high',
+  },
+  {
+    id: 'streaming',
+    label: 'SSE parser / StreamChunk protocol / chunk type',
+    match: ['sse', 'stream chunk', 'streamchunk', 'chunk type', '[done]', 'snapshot', 'streaming protocol', /stream(ing)? parser/i],
+    target: 'references/streaming-sse.md',
+    confidence: 'high',
+  },
+  {
+    id: 'model-registry',
+    label: 'MODELS shape / DEFAULT_MODEL / detectProvider rule',
+    match: ['models catalog', 'model registry', 'default_model', 'detectprovider', 'detect provider', 'grouped options', 'chat-input'],
+    target: 'references/model-registry.md',
+    confidence: 'high',
+  },
+  {
+    id: 'bridge-facade',
+    label: 'Facade / bridge / stub / maxTokens / lazy-load',
+    match: ['createadapter', 'create adapter', 'createclient', 'create client', 'bridge', 'stub', 'maxtokens', 'max tokens', 'lazy-load', 'lazy load', 'chatresult', 'chatopts'],
+    target: 'references/bridge-facade.md',
+    confidence: 'high',
+  },
+  {
+    id: 'proxy-boundary',
+    label: 'Proxy flavors / production-host path / key-in-browser safety',
+    match: ['proxy', 'passthrough', 'smart proxy', 'proxyurl', 'production host', 'browser key', 'key in browser', 'cors'],
+    target: 'references/browser-proxy-boundary.md',
+    confidence: 'high',
+  },
+  {
+    id: 'adapter-contract',
+    label: 'Cross-adapter shape rule / usage mapping / raw stopReason / buildRequest (DEFAULT)',
+    match: ['adapter contract', 'buildrequest', 'build request', 'usage mapping', 'stopreason', 'stop reason', 'parseresponse', 'adapter shape'],
+    target: 'references/adapter-contract.md',
+    confidence: 'medium',
+  },
+  {
+    id: 'methodology',
+    label: 'Posture / mission shift or new §SelfAudit axis (inline SKILL.md)',
+    match: ['posture', 'methodology', 'principle', 'mission', 'new selfaudit axis', 'self-audit axis'],
+    target: 'SKILL.md',
+    confidence: 'medium',
+  },
+  {
+    id: 'journal',
+    label: 'One-off arc story (NEGATIVE — journal, not the skill)',
+    match: ['arc story', 'debugging story', 'one-off', 'how i debugged', 'journal'],
+    target: '(journal)',
+    confidence: 'high',
+  },
+];
+
+export const router = buildRouter({ branches, defaultBranch: 'adapter-contract' });
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.includes('--list')) {
+    console.log(describeRouter(router, branches));
+    process.exit(0);
+  }
+  const payloadFlag = args.find(a => a.startsWith('--payload='));
+  const payload = payloadFlag
+    ? payloadFlag.slice('--payload='.length)
+    : args.filter(a => !a.startsWith('--')).join(' ');
+  if (!payload) {
+    console.error('Usage: node teach-route.mjs "<payload describing the new knowledge>"');
+    console.error('       node teach-route.mjs --payload="<payload>" [--json]');
+    console.error('       node teach-route.mjs --list');
+    process.exit(1);
+  }
+  const { branch, target, confidence, label } = router(payload);
+  console.log(JSON.stringify({ payload, branch, label, target, confidence }, null, 2));
+}

package/skills/adia-ui-llm/skill.json

@@ -0,0 +1,33 @@
+{
+  "name": "adia-ui-llm",
+  "version": "0.1.0",
+  "description": "Maintainer (PRODUCER) skill for @adia-ai/llm — the provider-agnostic LLM client at packages/llm/ that the adia-ui chat-shell and the A2UI generation pipeline depend on. Owns the provider adapters (anthropic / openai / gemini), the shared SSE parser, the model registry (models.ts), the unified chat() / streamChat() / createClient() facade, the createAdapter() bridge, the browser(proxyUrl)+Node duality, and StubLLMAdapter. Every mode names a real verify target (the built package, a real chat() round-trip, or the deterministic stub). Use whenever the user wants to ADD A PROVIDER ADAPTER / MODIFY AN ADAPTER / EVOLVE THE MODEL REGISTRY / WORK ON SSE STREAMING / CHANGE THE BRIDGE-FACADE CONTRACT / TOUCH THE BROWSER-PROXY BOUNDARY / FIX THE STUB. Triggers on \"add a new LLM provider\", \"fix the @adia-ai/llm SSE adapter\", \"the anthropic adapter drops cache tokens\", \"add a model to the registry\", \"streamChat yields a wrong chunk\", \"change chat()/streamChat()\", \"passthrough vs smart proxy\", \"stopReason normalization\", \"stub returns wrong A2UI\", \"teach adia-ui-llm\". Does NOT trigger for: WIRING the client into an app or chat box (CONSUMER side — the adia-ui-factory plugin's adia-ui-llm skill), generation-pipeline / corpus internals (adia-ui-a2ui), authoring web-components or the in-monorepo bridge surface against an unchanged client (adia-ui-authoring), cutting a release (adia-ui-release), or general LLM-streaming tutorials.",
+  "status": "stable",
+  "authors": ["kim.granlund"],
+  "codeowners": [],
+  "tags": ["adia-ui", "llm", "anthropic", "openai", "gemini", "sse", "streaming", "model-registry", "provider-adapter", "chat", "streamchat", "createadapter", "proxy", "stub", "provider-agnostic"],
+  "depends_on": [],
+  "peer_skills": ["adia-ui-authoring", "adia-ui-a2ui", "adia-ui-release", "adia-ui-gen-review", "adia-ui-dogfood"],
+  "environment": {
+    "portable": false,
+    "requires": ["the @adia-ai monorepo with packages/llm/ (src/adapters/{anthropic,openai,gemini,sse,index}.ts, src/models.ts, src/llm-bridge.ts, src/llm-stub.ts)"],
+    "rationale": "The @adia-ai/llm client source exists only in the @adia-ai monorepo; every verify command (npm run build for the package, a real chat()/streamChat() round-trip, the stub) and every audited source path (packages/llm/**) is substrate-side."
+  },
+  "files": [
+    "SKILL.md",
+    "CHANGELOG.md",
+    "skill.json",
+    "references/adapter-contract.md",
+    "references/streaming-sse.md",
+    "references/model-registry.md",
+    "references/bridge-facade.md",
+    "references/browser-proxy-boundary.md",
+    "references/add-a-provider.md",
+    "references/teach-protocol.md",
+    "scripts/audit-llm-roster.mjs",
+    "scripts/teach-route.mjs",
+    "evals/routing-corpus.json",
+    "evals/adversarial-corpus.json",
+    "evals/teach-routing-cases.json"
+  ]
+}

package/skills/adia-ui-release/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog — `adia-ui-release` skill
+
+## [0.1.0] stable — 2026-06-03
+
+**Initial cut in the `adia-ui-forge` plugin.** Faithful, de-repo'd, self-contained port of the @adia-ai monorepo's maintainer `adia-ui-release` skill, with the former `adia-ui-migration` skill folded in as the producer-side migration-guide-authoring section. Preserves the release-engineering depth (the gate roster, recovery paths, peer-in-flight discipline, ledger schema, notes craft) — this is a port, not a rewrite.
+
+### Ported
+
+- **SKILL.md** — the mode menu (now 11 modes), §Mission, §Posture (load-on- demand + content-trust citing `${CLAUDE_PLUGIN_ROOT}/references/shared/`), §Plan-Execute-Verify (per-mode real-product verify table), §ReleaseInvariants, §LoadingProtocol, §Recon, §Teach (stub → `teach-protocol.md`), §SelfAudit, §FileMap, §Status.
+- **11 references** — `cycle-happy-path.md`, `multi-agent-baseline.md`, `gates-catalog.md`, `recovery-paths.md`, `changelog-discipline.md`, `notes-authoring.md`, `rollup-notes.md`, `exe-deploy.md`, `ledger-discipline.md`, `teach-protocol.md`, plus the new `migration-guide-authoring.md` (the fold-in).
+- **8 scripts** (pure Node, stdlib only, `node --check` clean) — `bump.mjs`, `promote-unreleased.mjs`, `insert-stub.mjs`, `tag-lockstep.mjs`, `dispatch-publish.mjs`, `make-ledger.mjs`, `release-pack.mjs`, `audit-gate-roster.mjs`.
+- **9 case studies** (worked-example cycles) + the lockstep stub template + `evals/evals.json`.
+
+### Folded in — `adia-ui-migration` (producer side)
+
+The release skill now owns **producer-side** migration: mode 11 + §MigrationGuideAuthoring + `references/migration-guide-authoring.md` — authoring the `MIGRATION GUIDE.md` section when a cut breaks an API (before→after + audit grep + sweep recipe per item, manual-review classes for semantic flips, the version-coverage table, the in-repo sweep-verification audit) and sweeping the framework's own demo / playground / catalog surfaces. The **consumer** side (sweeping a downstream app against a published guide) deliberately stays in the separate consumer/app-author plugin; mode 11 declines + redirects for "migrate our app" requests.
+
+### Scope discipline (de-repo)
+
+- The portable release DISCIPLINE is the core. The @adia-ai monorepo's concrete **9-package lockstep**, **`check:*` gate roster**, and **`ui-kit.exe.xyz` demo-site deploy** are kept as the clearly-labeled **worked example** (header notes in `cycle-happy-path.md`, `gates-catalog.md`, `exe-deploy.md`; package/tag counts marked as the example in §ReleaseInvariants), NOT presented as universal gates.
+- Absolute paths (`/Users/...`) stripped; `$REPO` / `${CLAUDE_PLUGIN_ROOT}` used instead. Shared-infra references point at `${CLAUDE_PLUGIN_ROOT}/references/shared/` (content-trust, pev-rationale, skill-conventions). Skill-owned script invocations point at `${CLAUDE_PLUGIN_ROOT}/skills/adia-ui-release/scripts/`.
+- Instance data dropped: hardcoded repo slug → `--repo-slug <org>/<repo>` flag in `make-ledger.mjs` + `<org>/<repo>` placeholder in `ledger-discipline.md`; dated version-by-version skill history from the source's 1.x CHANGELOG dropped (durable knowledge + templates kept; the 9 case studies are retained as worked examples with absolute paths stripped).
+- Excluded-skill cross-references rewritten: `adia-ui-kit` → "the consumer/app-author plugin"; `adia-ui-ops` / `exe-dev-ops` → "a long-running-ops concern (separate; not in this plugin)"; `dogfood-sweep` → the present sibling `adia-ui-dogfood`; `a2ui-pipeline` → the present sibling `adia-ui-a2ui`; monorepo-only docs (`VISION-extensibility.md`, `trainable-skill-ecosystem-design`) → the shared `skill-conventions.md` / `pev-rationale.md`.