@adia-ai/adia-ui-forge 0.8.62 → 0.8.64

package/skills/primitive-authoring/references/form-control-sizing.md

@@ -1,21 +1,21 @@
-# Form-control sizing posture — fill by default, `[inline]` hugs
+# Form-control sizing posture, fill by default, `[inline]` hugs
 
 Source of truth: [ADR-0077](../../../../../../docs/ops/adr/adr-0077-form-control-sizing-posture.md)
 (ratified 2026-08-19; amends [ADR-0037](../../../../../../docs/ops/adr/adr-0037-inline-display-mode-convention.md)
-partial — `[inline]` semantics widen to own the sizing axis, the display-default
+partial, `[inline]` semantics widen to own the sizing axis, the display-default
 convention itself is unchanged). Companion SPEC:
 `docs/ops/spec/spec-form-control-sizing-posture.md`. Read the ADR before
-touching a form-control host's width/min-width rules — this file is the
+touching a form-control host's width/min-width rules: this file is the
 routing pointer + the fix-now checklist, not a restatement of the ruling.
 
 ## The one-line rule
 
 A form-control host, absent `[inline]`, is block-level (ADR-0037, unchanged)
-**and fills its container's available inline space** — in block flow via
+**and fills its container's available inline space**, in block flow via
 `width: auto` (already true), in flex/grid parents via `width: 100%` on the
 host (the mechanism `field-ui`/`otp-input-ui` already shipped). `[inline]`
 flips BOTH axes at once: inline-level display **and** shrink-wrap/hug sizing.
-No separate `hug` attribute exists or should be minted — one token, one
+No separate `hug` attribute exists or should be minted, one token, one
 posture flip.
 
 ## Where legibility floors live
@@ -23,7 +23,7 @@ posture flip.
 **[retired 2026-08-28, ADR-0095]** The `--*-min-width: 20ch`-class floor
 described below is no longer permitted anywhere, including on
 `:scope[inline]`. A primitive never floors its own inline-size independent
-of its own geometry — the only permitted floor is
+of its own geometry: the only permitted floor is
 `min-inline-size: var(--<component>-height)` (a square minimum). ADR-0095
 Decision Class 1 removes the 20ch-class field-width floor for
 `input-ui`/`select-ui`/`combobox-ui` (plus `--input-label-min-width`,
@@ -32,21 +32,20 @@ floor, generalizing the `button-ui` keep-square pattern already named below
 to the field-width components.
 
 **[amended 2026-08-31, gh#2534, ADR-0095]** The square-minimum rule governs
-a primitive's own OUTER inline-size floor against its own block-size only —
-it does not reach a component's INTERNAL grid-column sizing. A token like
+a primitive's own OUTER inline-size floor against its own block-size only, it does not reach a component's INTERNAL grid-column sizing. A token like
 `field-ui[inline]`'s `--field-label-inline-min: 10ch` floors the label
 *column* inside the component's internal grid, to keep sibling rows
-aligned — not to prevent the host itself from collapsing — so it is not
+aligned, not to prevent the host itself from collapsing, so it is not
 "a `--*-min-width: 20ch`-class floor" in ADR-0095's sense and is not
 retired by the Decision above. Don't apply the square-minimum rule to an
 internal grid-column token by analogy to the field-width class.
 
-*(Historical, pre-ADR-0095 rule — superseded by the retirement above, kept
+*(Historical, pre-ADR-0095 rule, superseded by the retirement above, kept
 only for context on what the old convention was.)* A
 `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on
 `input-ui`/`select-ui`/`combobox-ui`) used to belong on `:scope[inline]`
 only, never on the plain `:scope`. In the fill state the container owns the
-width, all the way down — no exception, no re-added floor. Two floor
+width, all the way down, no exception, no re-added floor. Two floor
 classes are
 explicitly NOT sizing-posture floors and stay in both states: inner
 `min-width: 0` flex unclampers (the ellipsis-reset machinery) and
@@ -60,18 +59,17 @@ posture, and also stay in both states.
 - Plain `:scope` (no `[inline]`): block-level, `width: auto` in block flow,
   `width: 100%` in flex/grid parents. No `min-width` legibility floor here.
 - `:scope[inline]`: inline-level display, shrink-wrap sizing. Per ADR-0095,
-  no `--*-min-width: 20ch`-class floor moves here any more — a floor-carrier
+  no `--*-min-width: 20ch`-class floor moves here any more, a floor-carrier
   component uses the square minimum (`min-inline-size:
   var(--<component>-height)`) instead, in both states.
 - A component that wants to own its line but still hug has no attribute for
-  that state (ADR-0077 Decision item 6, accepted consequence) — tell the
+  that state (ADR-0077 Decision item 6, accepted consequence), tell the
   consumer to use explicit sizing (`width: fit-content` or an explicit
   width), don't invent a third posture token.
 - `field-ui`/`fields-ui`'s `[inline]` carve-out (single-row layout meaning,
   ADR-0037 §5) is retained and stays behaviorally convergent with this
-  decision — don't "fix" it to match the family's token meaning.
-- The trip-wire gate is `scripts/release/check-display-default-convention.mjs`
-  — it fails a 20ch-class host floor on the plain `:scope` and fails a
+  decision, don't "fix" it to match the family's token meaning.
+- The trip-wire gate is `scripts/release/check-display-default-convention.mjs`, it fails a 20ch-class host floor on the plain `:scope` and fails a
   missing fill mechanism in the default state, for roster components. One
   gate, no second check to satisfy.
 
@@ -79,6 +77,6 @@ posture, and also stay in both states.
 
 The exact component roster and the breaking-wave/golden-regeneration rollout
 (one coordinated wave, MIGRATION GUIDE entry same cycle, deliberately
-regenerated `evals/visual/` goldens — never additive-first, never shimmed)
+regenerated `evals/visual/` goldens, never additive-first, never shimmed)
 are the companion PLAN's job (`docs/ops/plan/plan-form-control-sizing.md`),
-not this reference — cite the ADR/PLAN rather than re-deriving scope here.
+not this reference, cite the ADR/PLAN rather than re-deriving scope here.

package/skills/primitive-authoring/references/lifecycle-patterns.md

@@ -1,10 +1,10 @@
-# Lifecycle Patterns — Listeners, Timers, Observers, Popovers
+# Lifecycle Patterns, Listeners, Timers, Observers, Popovers
 
 Deep dive on symmetric `connected()` / `disconnected()` in AdiaUI components. Read when adding any side effect (listener, timer, observer, popover) to a component, or when inheriting from `UIFormElement`.
 
 ## The symmetry rule
 
-Every side effect set up in `connected()` has a matching teardown in `disconnected()`. The teardown is authored at the same time as the setup, not later — if you leave `disconnected()` for tomorrow, tomorrow won't happen.
+Every side effect set up in `connected()` has a matching teardown in `disconnected()`. The teardown is authored at the same time as the setup, not later, if you leave `disconnected()` for tomorrow, tomorrow won't happen.
 
 ```javascript
 class UIWidget extends UIElement {
@@ -36,16 +36,16 @@ Four things happen in `disconnected()`:
 3. [Not shown] Clear any timers.
 4. [Not shown] Disconnect any observers.
 
-## Stable handlers — `#field` arrows, never inline arrows
+## Stable handlers, `#field` arrows, never inline arrows
 
 `removeEventListener(type, handler)` requires reference equality on `handler`. Inline arrows create a fresh function every time:
 
 ```javascript
-// WRONG — the inline arrow is a new function every render
+// WRONG: the inline arrow is a new function every render
 this.#buttonEl.addEventListener('click', (e) => this.doThing(e));
-// Later: removeEventListener can't match — no reference equality.
+// Later: removeEventListener can't match, no reference equality.
 
-// RIGHT — stable reference via private field
+// RIGHT, stable reference via private field
 #onButtonClick = (e) => this.doThing(e);
 // connected:
 this.#buttonEl.addEventListener('click', this.#onButtonClick);
@@ -57,10 +57,10 @@ The `#` prefix keeps the handler private to the class (can't be accidentally use
 
 **Historical bugs this pattern prevents:**
 
-- `cot.js:116` — summary click handler as inline arrow. Couldn't be removed; fixed by promoting to `#onSummaryClick`.
-- Generic pattern across ~35 components in the audit cycle — all promoted to stable fields.
+- `cot.js:116`, summary click handler as inline arrow. Couldn't be removed; fixed by promoting to `#onSummaryClick`.
+- Generic pattern across ~35 components in the audit cycle, all promoted to stable fields.
 
-## Ephemeral DOM with inline arrows — the tolerance rule
+## Ephemeral DOM with inline arrows, the tolerance rule
 
 There's ONE exception: inline arrows on DOM elements that are guaranteed to be fully detached + GC'd before the next re-render.
 
@@ -78,12 +78,12 @@ There's ONE exception: inline arrows on DOM elements that are guaranteed to be f
 }
 ```
 
-**This is tolerated but not preferred.** If anything about the lifetime changes — if someone adds a `row.remove()` that leaves a cached reference, or converts to incremental DOM updates — the listeners stop getting GC'd and become leaks.
+**This is tolerated but not preferred.** If anything about the lifetime changes, if someone adds a `row.remove()` that leaves a cached reference, or converts to incremental DOM updates, the listeners stop getting GC'd and become leaks.
 
 The safer pattern is event delegation on the stable parent:
 
 ```javascript
-// Preferred — one listener on the parent, reads data-attributes
+// Preferred, one listener on the parent, reads data-attributes
 connected() {
   this.#container.addEventListener('click', this.#onContainerClick);
 }
@@ -102,7 +102,7 @@ disconnected() {
 
 One listener, always removable, survives DOM churn.
 
-## Timers — `setInterval`, `setTimeout`
+## Timers, `setInterval`, `setTimeout`
 
 Store the handle, clear it in `disconnected()`:
 
@@ -128,7 +128,7 @@ disconnected() {
 
 The null-guard is defensive; `clearInterval(null)` is actually a no-op but the guard makes the "was it created?" intent explicit.
 
-## Observers — ResizeObserver, MutationObserver, IntersectionObserver
+## Observers, ResizeObserver, MutationObserver, IntersectionObserver
 
 Every observer has `.disconnect()`:
 
@@ -146,28 +146,28 @@ disconnected() {
 }
 ```
 
-**Historical bug:** `chart.js` had TWO `disconnected()` methods — the second one silently overrode the first. The first had the `ResizeObserver.disconnect()` call; the second didn't. Chart listeners leaked until a production repro surfaced it.
+**Historical bug:** `chart.js` had TWO `disconnected()` methods, the second one silently overrode the first. The first had the `ResizeObserver.disconnect()` call; the second didn't. Chart listeners leaked until a production repro surfaced it.
 
-**Lesson:** a class must declare `disconnected()` exactly once. If you need to add teardown, edit the existing method. Duplicate method names silently shadow — no error, no warning.
+**Lesson:** a class must declare `disconnected()` exactly once. If you need to add teardown, edit the existing method. Duplicate method names silently shadow, no error, no warning.
 
-## Reflection — non-finite Number-typed props don't stringify
+## Reflection, non-finite Number-typed props don't stringify
 
-`reflect()` in `core/element.js` writes a `Number`-typed reflected property's value back onto the DOM attribute by stringifying it. That's correct for finite numbers, but a non-numeric sentinel assigned to a `Number`-typed reflected prop (e.g. `range-total="?"` — table-ui's open/unproven-total marker for cursor/hasMore server paging) used to get silently coerced and re-stringified as the literal attribute `range-total="NaN"`, before any render ran (gh#1895, PR #1907, ADR-0082 amendment).
+`reflect()` in `core/element.js` writes a `Number`-typed reflected property's value back onto the DOM attribute by stringifying it. That's correct for finite numbers, but a non-numeric sentinel assigned to a `Number`-typed reflected prop (e.g. `range-total="?"`, table-ui's open/unproven-total marker for cursor/hasMore server paging) used to get silently coerced and re-stringified as the literal attribute `range-total="NaN"`, before any render ran (gh#1895, PR #1907, ADR-0082 amendment).
 
-**Fix, framework-wide:** a non-finite `Number`-typed value is left unreflected instead of stringified — gated narrowly on `Number` type + `Number.isFinite()` failing, so no other reflected prop's behavior changes.
+**Fix, framework-wide:** a non-finite `Number`-typed value is left unreflected instead of stringified, gated narrowly on `Number` type + `Number.isFinite()` failing, so no other reflected prop's behavior changes.
 
 ```javascript
-// core/element.js reflect() — the narrow gate
+// core/element.js reflect(), the narrow gate
 if (type === Number && !Number.isFinite(value)) {
-  // leave unreflected — do NOT write "NaN" to the attribute
+  // leave unreflected, do NOT write "NaN" to the attribute
 } else {
   this.setAttribute(attr, String(value));
 }
 ```
 
-**Recognition:** any future non-numeric sentinel authored onto a `Number`-typed reflected prop (a `'?'`, an `'auto'`, an open-ended marker) hits the same wart unless it too fails `Number.isFinite()` before the stringify step. If a prop's contract legitimately mixes numbers with a sentinel string, declare it non-reflecting or widen its declared type — don't rely on the reflect() gate alone as documentation of the contract.
+**Recognition:** any future non-numeric sentinel authored onto a `Number`-typed reflected prop (a `'?'`, an `'auto'`, an open-ended marker) hits the same wart unless it too fails `Number.isFinite()` before the stringify step. If a prop's contract legitimately mixes numbers with a sentinel string, declare it non-reflecting or widen its declared type, don't rely on the reflect() gate alone as documentation of the contract.
 
-## `UIFormElement` — `super` discipline
+## `UIFormElement`, `super` discipline
 
 Form-participating components inherit `ElementInternals` wiring from `UIFormElement`. That wiring only works if `super.connected()` and `super.disconnected()` are called:
 
@@ -185,20 +185,20 @@ class UIInput extends UIFormElement {
   #onInput = () => this.syncValue(this.#inputEl?.value ?? '');
 
   connected() {
-    super.connected(); // MUST — registers ElementInternals, form association
+    super.connected(); // MUST, registers ElementInternals, form association
     this.#inputEl = this.querySelector('input');
     this.#inputEl?.addEventListener('input', this.#onInput);
   }
 
   disconnected() {
-    super.disconnected(); // MUST — unregisters form participation
+    super.disconnected(); // MUST, unregisters form participation
     this.#inputEl?.removeEventListener('input', this.#onInput);
     this.#inputEl = null;
   }
 }
 ```
 
-Omit `super.connected()` and the component won't participate in form submission — the field value is never collected, no validation fires, no form-reset handler runs. It's a silent failure; you only find out when form submission misses the field.
+Omit `super.connected()` and the component won't participate in form submission: the field value is never collected, no validation fires, no form-reset handler runs. It's a silent failure; you only find out when form submission misses the field.
 
 ## Popovers, tooltips, document-level overlays
 
@@ -290,7 +290,7 @@ disconnected() {
 }
 ```
 
-## DOM-reference nulling — why it matters
+## DOM-reference nulling, why it matters
 
 A cached DOM reference (`this.#fooEl`) held by the component class keeps the referenced element alive for GC purposes, along with its own subtree. When the component is removed from the DOM, the old tree hangs around in memory until the component itself is garbage-collected.
 
@@ -306,36 +306,36 @@ disconnected() {
 }
 ```
 
-Especially important for components that are attached/detached frequently (modals, toasts, drawers) — each incarnation leaks its old subtree into memory if refs aren't released.
+Especially important for components that are attached/detached frequently (modals, toasts, drawers), each incarnation leaks its old subtree into memory if refs aren't released.
 
-## Adopt-or-stamp — slot content is the source of truth
+## Adopt-or-stamp, slot content is the source of truth
 
 Every slot-bearing primitive that exposes both an attribute and a slot for the same logical content (`text=` + `<span slot="text">`) follows the `#stampMark` / `#wasStamped` policy (working reference: `list-item-ui`, `packages/web-components/components/list/list.js`):
 
 1. `connected()` either **adopts** the consumer-authored slotted child or **stamps** a new one, tagging it `data-{component}-stamped`.
-2. `render()` may only mutate or remove elements carrying the stamp. An unstamped slotted child is consumer-owned — leave it alone, even when the matching attribute is empty.
+2. `render()` may only mutate or remove elements carrying the stamp. An unstamped slotted child is consumer-owned, leave it alone, even when the matching attribute is empty.
 3. The attribute stays a convenience shorthand that produces a stamped element; both forms render identically and are interchangeable.
 
-The failure this prevents: a `render()` that overwrites `textContent` from the attribute, or hides/removes the slot element when the attribute is empty, silently destroys consumer-authored rich content (links, `<strong>`, inline icons). A 13-page audit found 73 slot uses where the slotted form is the only way to author the intended content (the destructive render() confirmed in 3 primitives) before the policy landed — from the page author's seat it looks like "the docs are broken", from the component author's seat like "the consumer didn't pass the attribute"; both are wrong-blame. Source: ADR-0010.
+The failure this prevents: a `render()` that overwrites `textContent` from the attribute, or hides/removes the slot element when the attribute is empty, silently destroys consumer-authored rich content (links, `<strong>`, inline icons). A 13-page audit found 73 slot uses where the slotted form is the only way to author the intended content (the destructive render() confirmed in 3 primitives) before the policy landed, from the page author's seat it looks like "the docs are broken", from the component author's seat like "the consumer didn't pass the attribute"; both are wrong-blame. Source: ADR-0010.
 
-### `slot="caret"` — the one disclosure-indicator slot
+### `slot="caret"`, the one disclosure-indicator slot
 
-The expand/collapse (and dropdown) directional-indicator slot is named `caret` on every primitive that exposes composition slots (`tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`, `drilldown-ui`). `chevron` is retired — a hard rename with no compat alias, and `--*-chevron-*` tokens became `--*-caret-*` (Phosphor names the glyphs `caret-right` / `caret-down`; there is no `chevron-*` icon).
+The expand/collapse (and dropdown) directional-indicator slot is named `caret` on every primitive that exposes composition slots (`tree-item-ui`, `pane-ui`, `accordion-item-ui`, `nav-group-ui`, `select-ui`, `drilldown-ui`). `chevron` is retired, a hard rename with no compat alias, and `--*-chevron-*` tokens became `--*-caret-*` (Phosphor names the glyphs `caret-right` / `caret-down`; there is no `chevron-*` icon).
 
 - The mechanism is adopt-or-stamp (above): honor a declarative `<… slot="caret">` child if present, else stamp `<icon-ui slot="caret" name="caret-right">`. The same adopt-or-stamp rule applies to **every** composition slot the stamp builds (e.g. `slot="actions"`).
-- Rotation is driven by host open-state CSS (`:scope[open]` / `[collapsed]` / `[expanded]`) — never by swapping the icon name.
-- Internal-render components with no composition slots (`agent-trace`, `agent-reasoning`) keep `[data-*-caret]` styling hooks — the convention governs slots, not internal hooks.
+- Rotation is driven by host open-state CSS (`:scope[open]` / `[collapsed]` / `[expanded]`), never by swapping the icon name.
+- Internal-render components with no composition slots (`agent-trace`, `agent-reasoning`) keep `[data-*-caret]` styling hooks, the convention governs slots, not internal hooks.
 
 Source: ADR-0036, ADR-0092 (`drilldown-ui`'s row-level caret migrated from `slot="chevron"`,
 retained under ADR-0085, to `slot="caret"`, reversing that exemption).
 
 ## Anti-patterns to watch for
 
-- **Inline arrow + `removeEventListener`** — the listener isn't really being removed. Silent leak.
-- **Forgot to create `disconnected()`** — if `connected()` adds side effects, `disconnected()` must exist. No exceptions.
-- **Two `disconnected()` methods in the same class** — the second silently wins; the first's cleanup is lost.
-- **`super.connected()` missing in `UIFormElement` subclass** — form participation silently fails.
-- **Popover / tooltip never cleaned up** — stays in `document.body` forever.
-- **Observer recreated on every render** — re-observing without disconnecting first leaks observer refs.
-- **Timer fired after component removed** — not cleared in `disconnected()`, fires on a dead component. Can cause null-deref crashes or phantom re-renders.
-- **Multi-`await` method that can be re-invoked before the previous call finishes** (a route change, search-as-you-type, tab switch) — a guard checked only at ONE checkpoint doesn't protect the awaits after it; a slow-but-eventually-resuming call can pass every checkpoint it reaches and clobber a newer call's result. See [common-gotchas.md §6](common-gotchas.md#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough) (the sequence-token pattern: claim before the first `await`, re-check after every subsequent one).
+- **Inline arrow + `removeEventListener`**, the listener isn't really being removed. Silent leak.
+- **Forgot to create `disconnected()`**, if `connected()` adds side effects, `disconnected()` must exist. No exceptions.
+- **Two `disconnected()` methods in the same class**, the second silently wins; the first's cleanup is lost.
+- **`super.connected()` missing in `UIFormElement` subclass**, form participation silently fails.
+- **Popover / tooltip never cleaned up**, stays in `document.body` forever.
+- **Observer recreated on every render**, re-observing without disconnecting first leaks observer refs.
+- **Timer fired after component removed**, not cleared in `disconnected()`, fires on a dead component. Can cause null-deref crashes or phantom re-renders.
+- **Multi-`await` method that can be re-invoked before the previous call finishes** (a route change, search-as-you-type, tab switch), a guard checked only at ONE checkpoint doesn't protect the awaits after it; a slow-but-eventually-resuming call can pass every checkpoint it reaches and clobber a newer call's result. See [common-gotchas.md §6](common-gotchas.md#6-async-loadrender-function-completing-out-of-order--a-guard-at-the-checkpoint-isnt-enough) (the sequence-token pattern: claim before the first `await`, re-check after every subsequent one).

package/skills/primitive-authoring/references/llm-bridge.md

@@ -1,9 +1,9 @@
-# LLM Bridge extension — @adia-ai/llm
+# LLM Bridge extension, @adia-ai/llm
 
-**Superseded 2026-07-18 — `@adia-ai/llm` internals are `llm-client-maintenance`'s charter, not
+**Superseded 2026-07-18, `@adia-ai/llm` internals are `llm-client-maintenance`'s charter, not
 `primitive-authoring`'s.** That skill's references (`adapter-contract.md`, `streaming-sse.md`,
 `model-registry.md`, `bridge-facade.md`, `browser-proxy-boundary.md`, `add-a-provider.md`)
-are the current, maintained source — this file is kept only as a historical pointer and is
+are the current, maintained source: this file is kept only as a historical pointer and is
 no longer linked from `primitive-authoring`'s task-shape table or `code-style.md`. Route provider/
 streaming/bridge work to `llm-client-maintenance`.
 
@@ -47,13 +47,13 @@ This reference is about **modifying** the package. For day-to-day consumption (i
 └── server.js             ← Local proxy + static server (NOT shipped to npm)
 ```
 
-## Hard rules — defaults that bit us
+## Hard rules, defaults that bit us
 
 ### Rule 1: `maxTokens: 32768` is intentional
 
 The bridge hardcodes `maxTokens: 32768` in `complete()` and `stream()`. **Don't lower this.**
 
-A2UI JSON for moderately complex UIs (kanban, dashboard, pricing tier table) routinely exceeds 8k. An 8k truncation was discovered producing silent fallbacks the validator rubber-stamped at ~89/100 — the generator looked healthy but was emitting incomplete component trees.
+A2UI JSON for moderately complex UIs (kanban, dashboard, pricing tier table) routinely exceeds 8k. An 8k truncation was discovered producing silent fallbacks the validator rubber-stamped at ~89/100: the generator looked healthy but was emitting incomplete component trees.
 
 If you're adding a new provider that has a lower maxTokens ceiling (e.g., a model with 4k output limit), surface it as a model-level constraint in `MODELS`, **don't bypass the 32k bridge default**.
 
@@ -66,18 +66,18 @@ The bridge passes `cache: this.#provider === 'anthropic'`. This marks the ~23KB
 - Below provider's minimum cacheable size (1024 tok Sonnet/Opus, 2048 Haiku): no-op
 - Other providers silently ignore the unknown opt
 
-When adding a new provider, leave `cache` falsy unless that provider has its own caching mechanism — then add a parallel `case` in the adapter's `buildRequest`.
+When adding a new provider, leave `cache` falsy unless that provider has its own caching mechanism, then add a parallel `case` in the adapter's `buildRequest`.
 
 ### Rule 3: stopReason must propagate
 
 The bridge surfaces `stopReason` from the upstream response in both `complete()` and `stream()`'s terminal `done` chunk. Values:
 
-- `'end'` / `'stop'` / `'STOP'` — clean completion
-- `'max_tokens'` / `'length'` / `'MAX_TOKENS'` (Gemini) — **truncation**
-- `'tool_use'` / `'tool_calls'` — tool-call paused output
-- `'error'` — provider-side error
+- `'end'` / `'stop'` / `'STOP'`, clean completion
+- `'max_tokens'` / `'length'` / `'MAX_TOKENS'` (Gemini), **truncation**
+- `'tool_use'` / `'tool_calls'`, tool-call paused output
+- `'error'`, provider-side error
 
-**Downstream parser refuses silent fallback rendering when stopReason indicates truncation.** Don't normalize all values to `'end'` — the generator's truncation detector reads the raw value.
+**Downstream parser refuses silent fallback rendering when stopReason indicates truncation.** Don't normalize all values to `'end'`, the generator's truncation detector reads the raw value.
 
 ### Rule 4: lazy-load adapters in browser-facing modules
 
@@ -164,7 +164,7 @@ Edit `packages/llm/core/package.json`:
 }
 ```
 
-The `./adapters/*` glob already covers new files — no edit needed unless you want a named subpath.
+The `./adapters/*` glob already covers new files, no edit needed unless you want a named subpath.
 
 ### Step 4: Update `models.js` catalog
 
@@ -227,16 +227,16 @@ LLM_PROVIDER=myprovider node packages/gen-ui/mcp/gen-ui/scripts/eval-diff.mjs --
 
 ## Pitfalls
 
-- **Two proxy shapes — `proxyUrl` is overloaded.** The bridge supports two architecturally different proxies and the dispatcher in `packages/llm/core/adapters/index.js` chooses between them by URL shape. Get this wrong and you get silent 401s in the browser even though `node packages/llm/core/server.js` works fine.
+- **Two proxy shapes, `proxyUrl` is overloaded.** The bridge supports two architecturally different proxies and the dispatcher in `packages/llm/core/adapters/index.js` chooses between them by URL shape. Get this wrong and you get silent 401s in the browser even though `node packages/llm/core/server.js` works fine.
   - **Smart proxy** (`packages/llm/core/server.js`, route `POST /api/chat`): accepts a **provider-neutral body** `{ provider, model, messages, ... }`, holds the API key server-side, and dispatches internally to the right adapter. Headers are just `content-type: application/json`.
-  - **Passthrough proxy** (Vite dev `/api/llm/<provider>/<rest>` → real upstream URL `https://api.<provider>.com/<rest>`): expects the **real upstream body shape** (Anthropic-shaped for `/anthropic/`, OpenAI-shaped for `/openai/`, etc.) plus the **adapter's own auth headers** (`x-api-key` + `anthropic-version`, or `Authorization: Bearer …`). The proxy is dumb — it just rewrites the URL and forwards bytes.
+  - **Passthrough proxy** (Vite dev `/api/llm/<provider>/<rest>` → real upstream URL `https://api.<provider>.com/<rest>`): expects the **real upstream body shape** (Anthropic-shaped for `/anthropic/`, OpenAI-shaped for `/openai/`, etc.) plus the **adapter's own auth headers** (`x-api-key` + `anthropic-version`, or `Authorization: Bearer …`). The proxy is dumb, it just rewrites the URL and forwards bytes.
   - Dispatcher: `chat()` and `streamChat()` in `adapters/index.js` call `isPassthroughProxy(proxyUrl)` (regex `/\/api\/llm\/[a-z]+(\/|$)/`). If true, they call `passthroughRequest()` which builds the real upstream body via `adapter.buildRequest()` then swaps in `proxyUrl`. If false, they call `proxyRequest()` with the provider-neutral body.
-  - **When adding a new provider**, make sure: (1) `buildRequest()` omits the API key header when `proxyUrl` is the smart proxy (already handled), (2) `buildRequest()` _includes_ the API key header when called from `passthroughRequest()` (also already handled — passthroughRequest forwards adapter headers). The adapter's `buildRequest()` is the single source of truth for upstream-shape body + headers. Don't fork it for proxy mode.
+  - **When adding a new provider**, make sure: (1) `buildRequest()` omits the API key header when `proxyUrl` is the smart proxy (already handled), (2) `buildRequest()` _includes_ the API key header when called from `passthroughRequest()` (also already handled, passthroughRequest forwards adapter headers). The adapter's `buildRequest()` is the single source of truth for upstream-shape body + headers. Don't fork it for proxy mode.
 - **Don't add `apiKey` to the proxy body**. The proxy holds the key server-side. Adapter's `buildRequest` should set the API-key header only when `proxyUrl` is unset (i.e., direct mode).
 - **Don't normalize `stopReason`**. Each provider uses different terminal values (`max_tokens` vs `length` vs `MAX_TOKENS`); the truncation detector reads them raw.
 - **Don't import the package from itself.** `index.js` re-exports from `./adapters/index.js`; consumers inside the package reference relative paths to dodge the package-name resolution loop.
-- **`MODELS` is consumed by `<chat-input-ui>`** — its shape is `[{ label, options: [{ value, label }] }]` matching `<select-ui>` with `<optgroup>`s. Don't deviate from this shape or 3 apps break.
-- **`DEFAULT_MODEL` is the cheapest option** — resist the urge to default to a flagship model — most consumers want fast/cheap by default.
+- **`MODELS` is consumed by `<chat-input-ui>`**, its shape is `[{ label, options: [{ value, label }] }]` matching `<select-ui>` with `<optgroup>`s. Don't deviate from this shape or 3 apps break.
+- **`DEFAULT_MODEL` is the cheapest option**, resist the urge to default to a flagship model, most consumers want fast/cheap by default.
 
 ## Verification gates
 
@@ -253,7 +253,7 @@ If you added a new SSE chunk type to the streaming protocol, verify all 7 consum
 
 ## Cross-references
 
-- [code-style.md](code-style.md) — general AdiaUI conventions (this is a specialty path; start there if you need broader context)
-- **a2ui-maintenance** (sibling skill) — generator / MCP / zettel synthesis (consumes the bridge)
-- Spec: `.claude/docs/specs/package-architecture.md` § 11 (Phase 5 — engine registry)
-- README: `packages/llm/core/README.md` — consumer-facing docs
+- [code-style.md](code-style.md), general AdiaUI conventions (this is a specialty path; start there if you need broader context)
+- **a2ui-maintenance** (sibling skill), generator / MCP / zettel synthesis (consumes the bridge)
+- Spec: `.claude/docs/specs/package-architecture.md` § 11 (Phase 5, engine registry)
+- README: `packages/llm/core/README.md`, consumer-facing docs