@adia-ai/adia-ui-factory 0.2.4 → 0.8.0

package/commands/adia-scaffold.md

@@ -1,17 +1,11 @@
 ---
-description: Scaffold a new adia-ui app — pick the rendering mode (SPA / SSR-framework), lay out the structure, wire the host.
-argument-hint: "[spa|ssr] [app name]"
+description: Scaffold a new adia-ui app, page, or component skeleton (bin/adia-scaffold emits the mechanical skeleton; the skill owns the shape decisions).
+argument-hint: "[app|page|component] [name]"
 ---
 
-Scaffold a new adia-ui app. **$ARGUMENTS**
+Scaffold an adia-ui surface. **$ARGUMENTS**
 
-**Name the design intent first [soft-gate]:** the design intent (the `BRIEF` — what this UI is reaching for) must be **at least lightly named**, one sentence is enough and it will evolve; absent, set a provisional, revisable pull and proceed. This is a **soft gate**, cleared by _naming_ a direction, not by stopping.
-
-1. **Pick mode + shape** via the `adia-ui-factory` classifiers (or the first argument) — or ask when it's greenfield. The shapes + four-axis layout are owned by **`adia-ui-project`** (load it for the decision).
-2. **Lay the skeleton deterministically** with the bundled scaffolder:
-   - SPA → `python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" spa <name>`
-   - SSR → `python3 "${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold" ssr <name> --framework <next|nuxt|sveltekit|astro>`
-   - add surfaces with the `page` (`--duo` for declarative) / `component` sub-commands.
-3. **Hand off:** `adia-ui-project` for the shape/layout decisions the bin doesn't make, `adia-ui-spa` / `adia-ui-ssr` for host wiring, then `adia-ui-compose` for the first real screen.
-
-The bin owns the byte-stable layout; the skills own the methodology. Don't restate either here.
+Invoke **`adia-project`** to classify the project shape and target, then use
+`${CLAUDE_PLUGIN_ROOT}/bin/adia-scaffold` for the mechanical skeleton. Shapes
+the bin doesn't one-shot (rollup, shared-foundation) are composed per the
+project-shapes reference.

package/commands/adia-verify.md

@@ -1,10 +1,9 @@
 ---
-description: Verify an adia-ui surface in the browser (QA + a11y gate).
-argument-hint: "[path]"
+description: Run the consumer-side exit gate on a composed surface — browser render, console, a11y, and composition audits.
+argument-hint: "[page or surface]"
 ---
 
-Verify an adia-ui surface before shipping. **$ARGUMENTS**
+Verify a composed surface. **$ARGUMENTS**
 
-Hand off to **`adia-ui-verify`** for the exit gate: render in a real browser (zero console errors on load, non-zero bounding boxes, and _read_ the screenshot), check accessibility (region roles + labels, keyboard paths, AA contrast), and confirm git hygiene (re-baseline, explicit allowlists, right branch).
-
-The skill owns the depth (`${CLAUDE_PLUGIN_ROOT}/references/verification.md`); don't restate it here.
+Invoke **`adia-verify`** and run its gate against the real rendered surface;
+findings come back file:line with severity.

package/package.json

@@ -1,16 +1,14 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.2.4",
-  "description": "Author and verify apps built on the adia-ui (@adia-ai) light-DOM web-component framework — scaffold, compose, wire, and verify across both SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
+  "version": "0.8.0",
+  "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",
     "a2ui",
+    "gen-ui",
     "web-components",
     "app-authoring",
-    "ssr",
-    "spa",
-    "scaffolding",
-    "llm-ui"
+    "consumer"
   ],
   "license": "MIT",
   "author": {
@@ -20,6 +18,7 @@
   "files": [
     ".claude-plugin",
     "skills",
+    "agents",
     "commands",
     "references",
     "bin",

package/references/a2ui-mcp-tools.md

@@ -20,8 +20,8 @@ This plugin wires `@adia-ai/a2ui-mcp` (declared in `.mcp.json`, run via `npx`).
 
 **Retrieve patterns & knowledge:**
 
-- `search_chunks` — semantic/keyword search over the 280+ corpus chunks.
-- `search_patterns` / `get_fragment` / `get_composition` — reusable composition patterns and fragments.
+- `search_chunks` — semantic/keyword search over the corpus's 394 chunks.
+- `search_patterns` / `list_patterns` / `get_composition` — reusable composition patterns.
 - `get_chunk` / `get_graph` / `resolve_composition` / `zettel_stats` — chunk graph navigation.
 
 **Classify & assemble (the generation pre-step):**
@@ -32,8 +32,9 @@ This plugin wires `@adia-ai/a2ui-mcp` (declared in `.mcp.json`, run via `npx`).
 **Generate** (host LLM in stdio):
 
 - `generate_ui` — produce A2UI/markup for a described surface.
-- `refine_ui` — iterate on a generated surface (multi-turn refinement; carry a `sessionId`).
-- `plan_app_state` — plan an app's state shape.
+- `refine_ui` — correct a `generate_ui` result whose validation failed (params: `intent`, `previousMessages`, `validationErrors`; monolithic only — zettel refines via `refine_composition`).
+- `plan_app_state` — extract the intent/domain/tasks ontology from a prompt *before* generating.
+- `compose_from_chunks` / `refine_composition` / `get_state` — the zettel two-call chunk workflow (compose, then refine against the kept `state_id`).
 
 **Validate** (offline):
 
@@ -43,7 +44,9 @@ This plugin wires `@adia-ai/a2ui-mcp` (declared in `.mcp.json`, run via `npx`).
 
 **Feedback & authoring loop:**
 
-- `submit_feedback` · `get_quality_metrics` · `get_training_gaps` · `import_pattern`.
+- `submit_feedback` · `get_quality_metrics` · `get_training_gaps` · `run_eval` · `report_issue` (files a session ticket under `qa/findings/issues/`).
+
+**Probe:** `server_status` — connectivity/version check (the `adia-verify` wiring probe).
 
 ## When to reach for it vs. hand-author
 
@@ -55,9 +58,9 @@ This plugin wires `@adia-ai/a2ui-mcp` (declared in `.mcp.json`, run via `npx`).
 
 Wiring the MCP is the right leverage, but be honest about what it costs:
 
-- **Always-on context (P6).** ~24 tool definitions load into context whenever the plugin is enabled, and the server starts on enable — whether or not you call a tool. This plugin's prose drives ~5 tools as the spine (`get_component_map`, `search_chunks`, `generate_ui`, `validate_schema`, `check_anti_patterns`) and ~13 across the authoring tier; the feedback/training (`submit_feedback`, `get_training_gaps`, `import_pattern`) and zettel-graph (`get_graph`, `resolve_composition`, `zettel_stats`) tools are corpus-maintainer surface an authoring agent rarely touches. **The tool set can't be scoped from `.mcp.json`** — the only lever is enabling/disabling the whole server (the README gives the disable path). A methodology-only user pays the full tax.
-- **Supply chain.** `.mcp.json` pins `@adia-ai/a2ui-mcp@0.7.8` (an exact version, so an upgrade is a reviewable diff — never `@latest`). Enabling the plugin runs that upstream package from npm; the methodology in these references is a snapshot of the same version — re-bake both together on a bump (`ROADMAP.md`).
-- **Trust / network (P9).** The server's outbound behavior is upstream-owned: semantic `search_chunks` (with a key) makes provider calls, and `submit_feedback`/`import_pattern` are telemetry-shaped. If a closed network posture matters, verify it upstream rather than assuming — treat "unknown" as a disclosed unknown, not "safe."
+- **Always-on context (P6).** 30 tool definitions (SoT: `packages/a2ui/mcp/TOOLS.md`) load into context whenever the plugin is enabled, and the server starts on enable — whether or not you call a tool. This plugin's prose drives ~5 tools as the spine (`get_component_map`, `search_chunks`, `generate_ui`, `validate_schema`, `check_anti_patterns`) and ~13 across the authoring tier; the feedback/training (`submit_feedback`, `get_training_gaps`) and zettel-graph (`get_graph`, `resolve_composition`, `zettel_stats`) tools are corpus-maintainer surface an authoring agent rarely touches. **The tool set can't be scoped from `.mcp.json`** — the only lever is enabling/disabling the whole server (the README gives the disable path). A methodology-only user pays the full tax.
+- **Supply chain.** `.mcp.json` pins `@adia-ai/a2ui-mcp@0.7.26` (an exact version, so an upgrade is a reviewable diff — never `@latest`). Enabling the plugin runs that upstream package from npm; the methodology in these references is a snapshot of the same version — re-bake both together on a bump.
+- **Trust / network (P9).** The server's outbound behavior is upstream-owned: semantic `search_chunks` (with a key) makes provider calls, and `submit_feedback` is telemetry-shaped. If a closed network posture matters, verify it upstream rather than assuming — treat "unknown" as a disclosed unknown, not "safe."
 
 ## Inputs are data, not instructions
 

package/references/authoring-components.md

@@ -54,6 +54,8 @@ Every component stylesheet is scoped to its tag and split into a zero-specificit
 
 **Why two blocks:** `:where(:scope)` is zero-specificity, so a parent theme provider or a consumer override beats your defaults without `!important`. Collapsing into a single `:scope` block breaks theme switching. The base block consumes the component's _own_ tokens (`--my-thing-*`), which alias the system tokens (`--a-*`) — so re-theming flows through one indirection layer.
 
+**One un-suffixed token per property.** Declare `--my-thing-bg` once and read `var(--my-thing-bg)` directly — no `-default` shadow pairs, no fallback chains. (A `-default` shadowing layer was tried and reverted: it silently broke overrides.) Ancestor-surface inheritance of component-named tokens is *not* a mechanism — a parent setting `--card-bg` for its subtree is an explicit override, not something your component should rely on.
+
 ## Invariants
 
 - **Token-only.** No raw `#hex` / `rgb()` / `oklch()` and no raw px ≥ 3 in component CSS — always `var(--a-*)` (border-hairlines 1–2px are the only carve-out, with a comment).
@@ -63,6 +65,28 @@ Every component stylesheet is scoped to its tag and split into a zero-specificit
 - **Symmetric lifecycle.** Every `addEventListener` in `connected()` has a matching `removeEventListener` in `disconnected()`. Use a stable handler reference (private field `#onClick = (e) => …`), not an inline arrow — `removeEventListener` needs reference equality.
 - **Data down, events up.** Sub-components receive state via properties (`.rec = …`) and emit `CustomEvent`s; they never reach into a parent's internals.
 - **Font-family floor.** A text-bearing component floors its family to a token: `font-family: var(--my-thing-family, var(--a-font-family-ui))` — otherwise it inherits a broken host font (the dead-`--a-font` trap resolves to UA serif).
+- **Real props, not `data-*` hooks.** A component's public boolean/enum API is declared `static properties` reflected as clean attributes — never `data-*` styling hooks.
+- **Container queries are opt-in** — `[provide-container-inline-size]` is the attribute utility that makes an element a size-query provider; it's not a per-component default.
+
+## CSS mechanics that bite
+
+- **`background: <color>` shorthand silently resets `background-clip`/`origin`/`position`/`size`** — a hover/active state that only recolors must use the `background-color` longhand, or a base `background-clip: content-box` flips to `border-box` and the fill balloons.
+- **`translate`/`scale`/`rotate` are independent properties, not `transform` aliases** — writing `style.translate` and reading the computed `transform` matrix (or vice versa) silently no-ops; animation loops that mix them read 0 and never move.
+- **An offsetting ancestor transform (`translate(-50%,-50%)`) breaks CSS anchor positioning** for top-layer popovers; an identity transform (`translateX(0)`) doesn't.
+- **An equal-specificity `@media` override must follow its base rule in source order** — placed earlier it silently loses.
+- **Never author `<thead>/<tbody>/<tr>/<td>` inside a custom element** — the HTML parser foster-parents them out of any non-`<table>` ancestor before your JS ever runs.
+
+## Lifecycle & reactivity traps (UIElement)
+
+- **Never declare a native DOM prop** (`textContent`, `innerHTML`, `className`, `id`) **in `static properties`** — the prop installer replaces the native accessor with a signal, so `el.textContent = ''` becomes a signal write instead of a child wipe.
+- **Wrap custom-setter bodies in `untracked()`** when they read reactive props — otherwise the read leaks a subscription into whichever effect called the setter.
+- **A MutationObserver that watches its own host and mutates it in the callback loops forever** — drain with `this.#observer.takeRecords()` after every absorb pass.
+- **A document-listening trait must not re-emit the same-named event on its host with `bubbles: true`** — the bubble re-reaches `document` and recurses; use distinct names for the incoming signal and the outgoing host event.
+- **A parent `render()` that filters children by an attr the child sets in its own `connected()` races the child upgrade** — match by tag name as well.
+- **Sync icon-registry checks (`isIconName`/`hasIcon`) at connect race the async manifest** on static (non-Vite) hosts — pair them with `whenIconRegistryReady` deferred re-stamping.
+- **FLIP/layout-animation preserves node identity, not content** — it fires on `appendChild` moves but not `replaceChildren` rebuilds, so diff children in place; and any post-drop effect must target the *final* DOM node by stable id (cross-container moves rebuild the source in a new parent).
+- **Drag affordances: one strong layer.** Keep the drop indicator (most precise) strong; ghost border, column outline, and bg tint stay subtle — everything at full strength reads as competing chrome.
+- **Drop targets: walk descendants, index post-removal.** `[droppable]` matches items via descendants + a closest-droppable filter (not direct children), so nested containers (cards inside a `.col-list`) still register; and a drop-indicator index is column-relative *after* the lifted item leaves — filter out the `[data-draggable-list-item-lifting]` node before counting, or the indicator lands one slot off.
 
 ## Anti-patterns (the lint seeds)
 
@@ -85,4 +109,4 @@ The mechanizable smells the framework audits — these seed the phase-(c) hook a
 | Hardcoded `open` on `<modal-ui>`/`<drawer-ui>` | drive via `.open = true` |
 | `new URL('…', import.meta.url)` literal for a corpus path | hold the path in a variable first |
 
-Run the framework's own gates when you have the repo (`npm run check:anti-patterns`, `audit:*`), and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.
+Run the plugin's `bin/adia-lint` on changed files, the framework's `audit:*` gates when you have the repo, and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.

package/references/component-model.md

@@ -13,8 +13,12 @@ How to _think_ about the catalog. The **live** catalog is the a2ui MCP (`get_com
 
 **Naming:** kebab-case with a `-ui` **suffix** (`<button-ui>`, not `<a-button>`). Shells/composites carry a domain prefix (`<admin-*>`, `<chat-*>`).
 
+**Light DOM is the substrate.** Components render in the light DOM — a `slot="X"` attribute is *inert* metadata unless CSS targets `[slot="X"]`; positioning is CSS by tag + ancestor + DOM order, never slot routing. Grep before believing any "the slot routes content" claim.
+
 **Rule of first resort:** reach for a catalog primitive before authoring anything. Never use a raw `<button>`/`<input>`/`<div>` where a `*-ui` primitive exists — raw elements skip focus rings, theming, density, and form association. Author a project component (see [authoring-components.md](authoring-components.md)) only when no primitive composes to the need.
 
+**Browser baseline:** Chromium 125+ · Safari 18.0+ · Firefox 129+ — the floor that makes `light-dark()`, `@scope`, popovers, and OKLCH usable without fallbacks.
+
 ## Registration is a side effect of import
 
 Importing a component module **registers its tag**. Two forms:
@@ -26,6 +30,13 @@ import '@adia-ai/web-components/components/button/button.js';  // one component
 
 Registration uses `defineIfFree('button-ui', UIButton)` internally — idempotent, so double-import is safe. The non-registering class import (`.../button/class`) exists for tests/subclassing. **In SSR this import must be client-only** — see [ssr-integration.md](ssr-integration.md).
 
+Registration corollaries that bite:
+
+- **Composites stamp primitives your HTML never mentions** — `chat-input-ui` internally renders `textarea-ui` + `select-ui`; unless those primitives are registered too, they stay undefined and collapse to 0×0.
+- **Shells register via the cluster barrel** (`@adia-ai/web-modules/shell|chat|editor`) — importing one shell's `.js` registers only the host; its bespoke children (`admin-sidebar`, `chat-thread`, …) only register when their sibling JS loads.
+- **Some tags are defined in a parent component's `.js`**, and some components are deliberately CSS-only (stylesheet + metadata, no `.js`) — when auditing whether a tag is real, grep for its `customElements.define`, don't `ls` folders.
+- **JS registers, CSS loads separately** — component CSS arrives via `<link>`/the CSS barrel, not the module graph; a JS-only side-effect import yields a registered but unstyled element.
+
 ## Signals, not a virtual DOM
 
 Components extend `UIElement` (or `UIFormElement` for form-participating controls) and use fine-grained signals:
@@ -40,6 +51,28 @@ import { UIElement, signal, computed, effect } from '@adia-ai/web-components/cor
 
 Declared `static properties` are wrapped as signals automatically, so setting `el.disabled = true` re-renders. Don't run a parallel `CustomEvent`-only state path that competes with signals.
 
+## Choosing components — the recurring calls
+
+Selection mistakes that keep recurring (verify props with `lookup_component` when unsure):
+
+- **`<stack-ui>` is a z-axis overlay** — all children share one grid cell. Vertical stacking is `<col-ui>`.
+- **High-frequency, low-cardinality view pickers** (Day/Week/Month, Kanban/List) are `<segmented-ui>`, not `<select-ui>` — all options visible, active one highlighted; reserve `select-ui` for lower-frequency, many-option knobs.
+- **Sidebar navigation is `<nav-ui>` + `<nav-item-ui>`**; `<menu-ui>`/`<menu-item-ui>` are for Popover-API dropdowns, never persistent nav.
+- **A list of rows** (leading control + title + subtext + trailing badge) is `<list-ui> > <list-item-ui>`, not bespoke flex divs.
+- **A standalone checkbox is `<check-ui name label="…">`** — never one `check-ui` wrapped in `<field-ui inline>`. `<field-ui>` is for form contexts only; toolbar knobs use the bare control + `aria-label` (the trigger already shows the value).
+- **Multiple radio/check siblings inside one `<field-ui label>`** need a `<col-ui gap="1">` wrapper — field-ui stacks a single input; without it they overlap.
+- **Card/drawer body content wraps in `<section>`** (canonical order: void media → `<header>` → `<section>`+ → `<footer>`) — direct flow children bypass the body slot and lose the `--card-inset` margin; `<section bleed>` zeros the inset but keeps inline padding.
+- **Clickable grid cards:** wrap the card in `<a href style="display:contents">` — link semantics + keyboard focus without a layout box, so the grid still sees the card as the cell; hover rides `a:hover card-ui`.
+- **No `stretch` on a `<button-ui>` inside a `<col-ui>` action stack** (col-ui already stretches children); `size="lg"` on an action stack applies only when it contains a `variant="primary"` button.
+- **`<toast-ui>` is a facade over `<feed-ui>`** — `AdiaToast.show()` routes to `AdiaFeed.post()`; the top-layer/queue/focus logic lives in the feed component.
+
+## Attribute honesty — silent-failure class
+
+- **Components silently accept any made-up attribute** — `text-ui muted`, `card-ui hover-elevate` are no-ops with zero warnings. Check the real prop list (`lookup_component`) before authoring; a rendered-but-unstyled state usually means an invented attr.
+- **`empty-state-ui` takes `[heading]`, not `[title]`** — `title=` becomes the native tooltip and the message silently doesn't render.
+- **Primary content often rides the default slot, not `text=`/`label=`** — `kbd-ui` and `card-ui` are the canonical traps. `button-ui` accepts both `text=` and child text; prefer `text=` for generated UI.
+- **Shell-tier bespoke children reflect state as attributes** (`admin-sidebar[collapsed]`) — read and style via attribute selectors; coordinate via `querySelector`, not a central store.
+
 ## Traits — behavior by declaration
 
 ```html
@@ -48,6 +81,9 @@ Declared `static properties` are wrapped as signals automatically, so setting `e
 
 or programmatically: `static traits = [pressable, scalePress]`. A trait is a factory (`defineTrait({ name, setup({host}) { …; return cleanup } })`) that manages attributes/events and tears itself down on disconnect. Query the live set with the MCP's `get_traits`.
 
+- **Traits require `UIElement`** — `traits="…"` on an HTMLElement-based or native element is silently ignored.
+- **`data-stream-*` attributes** are a universal ingestion trait: any element with a settable `.data` can subscribe to a shared, refcounted transport.
+
 ## Tokens — the only styling currency
 
 Three levels, all `--a-*`:
@@ -55,17 +91,29 @@ Three levels, all `--a-*`:
 | Level | Role | Examples |
 | --- | --- | --- |
 | **L1 primitive scales** | dimensionless base values | `--a-space-2` `--a-size-md` `--a-radius-sm` `--a-duration-fast` `--a-font-family-ui` |
-| **L2 semantic families** | role vocabulary | `--a-primary` `--a-danger` `--a-accent-bg` |
-| **L3 state × role** | what components consume | `--a-accent-bg-hover` `--a-danger-fg-active` `--a-ui-bg-disabled` |
+| **L2 semantic families** | role vocabulary | `--a-primary` `--a-danger` `--a-primary-bg` |
+| **L3 state × role** | what components consume | `--a-primary-bg-hover` `--a-danger-fg-active` `--a-ui-bg-disabled` |
 
-- **Color scheme** uses `light-dark()` at the token layer — never swap tokens by hand. Toggle with `<toggle-scheme-ui scheme="auto" target=":root" persist>`.
-- **Density** scales spacing via `--a-density` set at a provider boundary (`<div style="--a-density: 0.8">`).
+- **Color scheme** uses `light-dark()` at the token layer — never swap tokens by hand. Toggle with `<toggle-scheme-ui scheme="auto" target=":root" persist>`. Theming is **two independent axes**: `data-scheme` (light/dark) vs `data-theme` (named palette) — and `themes.css` loads separately from the styles barrel.
+- **Density / spacing / radius are `@property` multipliers** — three knobs rescale the whole system (the parametric spatial system); e.g. `--a-density: 0.8` at a provider boundary.
 - **Zero raw colors, zero raw px ≥ 3** in component CSS — always a token. This is mechanized by the `adia-lint` hook and by the MCP's `check_anti_patterns`.
+- **Use a token for its named role, never by coincidence** — `--a-bg` is never a foreground, `--a-fg` never a background; a primary fill is `--a-primary` + `--a-chrome-light` text.
+- **Text/icons on a filled primary disc** (radio dots, step circles, badge counters) use `--a-chrome-light` — theme-stable against any fill. (`--a-primary-fg` also resolves light post-Material-adoption; `--a-chrome-light` stays correct on arbitrary fills.)
+- **Series/group identity colors are `--a-data-0..9`**; semantic tones (info/success/danger/accent) mark *state*, never identity.
+- **Never re-ladder a foundation surface token** — don't override `--card-bg` with a bespoke elevation ladder; divergent ladders reintroduce the light/dark contrast inconsistency the symmetric canvas ramp prevents. (Per-element status tints are the legitimate exception.)
+- **Global `[color]`/`[weight]` utilities override component colors by `@layer` order** — a filled control that repurposes `color=` must opt out explicitly; conversely `[weight]` does *not* beat component-scoped `font-weight` (use a variant).
+- **Square/1:1 cells inheriting `--a-radius-md` render as circles** — small square cells take `--a-radius-sm`.
+- **Subtle structure chrome** (gridlines, weekend tints, today-column) shares one "barely-there" contrast budget — calibrate against the canvas surfaces in both schemes; too low is invisible, too high is chrome riot.
 
 ## "Registers" — typographic treatments, opt-in
 
 A _register_ (e.g. `verse`, `prose`) is a typographic treatment applied two ways together: **link the register stylesheet** (`styles/verse.css`) **and** put the **attribute** on the surface (`<my-surface verse>`). One without the other is a no-op — a common smell. Body/UI text defaults to `--a-font-family-ui`; registers opt a subtree into a different family/rhythm.
 
+## Layout realities
+
+- **A grid `auto`/`max-content` track collapses to ~1px around a flex wrapper** whose explicit width lives on an inner child — intrinsic max-content doesn't propagate through the wrapper; set the width on the wrapper itself (CSS, or JS-mirrored via ResizeObserver).
+- **Full-height shells need an unbroken flex chain** — see the mount gotcha in [shell-admin.md](shell-admin.md); it applies to every shell.
+
 ## Where this is incomplete
 
 The deep internals — the `html` template engine's escaping contract, `BaseController` delegation, the icon loader (`installIconLoadersForRegistered` + Vite `import.meta.glob`), `@bp` responsive notation, and the A2UI runtime/`<a2ui-root>` resolver — are framework-owned and version-specific. Treat the MCP (`lookup_component`, `search_chunks`) as the source of truth for them rather than encoding them here.

package/references/contracts/a2ui-mcp-surface.md

@@ -0,0 +1,35 @@
+# Contract: a2ui MCP tool surface (consumer side)
+
+<!-- VENDORED TWIN: adia-forge ships references/contracts/a2ui-mcp-surface.md
+     (producer side). Changes here must be reconciled in BOTH copies. -->
+
+The forge SHIPS `@adia-ai/a2ui-mcp` (source: `packages/a2ui/mcp/`); the factory
+PINS it in `.mcp.json` and consumer skills drive it. Source of truth for the
+full tool surface: `packages/a2ui/mcp/TOOLS.md` (30 tools, generated from
+`server.js` — update both together).
+
+## Stability rule (the load-bearing clause)
+
+- **Changing an existing tool's input/output contract is a breaking change for
+  every external MCP client** (Claude Desktop, Cursor, the factory plugin).
+  It requires: a dry-run diff of the schema, an explicit operator proceed, a
+  version bump of `@adia-ai/a2ui-mcp`, and a factory-side pin update.
+- **Adding tools is additive and safe.** Removing or renaming is breaking.
+- The factory pins an exact version (`npx -y @adia-ai/a2ui-mcp@<exact>`);
+  producers must not assume consumers float.
+
+## The consumer-load-bearing subset
+
+Tools the factory's skills depend on by name — treat their contracts as
+frozen-unless-versioned:
+
+| Tool | Consumer use |
+|---|---|
+| `generate_ui`, `refine_ui` | gen-UI generation loop (adia-genui) |
+| `validate_schema`, `check_anti_patterns` | the trust gate on LLM-emitted A2UI (screen-composer) |
+| `search_chunks`, `lookup_component`, `get_component_map`, `get_traits` | catalog literacy (adia-compose — "the MCP is the live catalog, don't memorize names") |
+| `convert_html` | migration aid (adia-migrate) |
+| `server_status` | connectivity probe (adia-verify) |
+
+`refine_ui` note: present in the pinned server; keep TOOLS.md's entry in sync
+with `server.js` when either changes (the 2026-06 red-team caught it missing).

package/references/contracts/migration-guide-format.md

@@ -0,0 +1,34 @@
+# Contract: MIGRATION GUIDE format (consumer side)
+
+<!-- VENDORED TWIN: adia-forge ships references/contracts/migration-guide-format.md
+     (producer side). Cross-plugin imports are forbidden, so changes here must be
+     reconciled in BOTH copies. -->
+
+`{repo}/.claude/docs/MIGRATION GUIDE.md` is the artifact the forge PRODUCES
+(via `adia-release`, on every breaking cut) and the factory CONSUMES (via
+`adia-migrate`, to drive consumer sweeps). This is the shared shape.
+
+## Producer obligations (adia-release, per breaking cut)
+
+1. **Version-scope bullet** in the top index: `**\`X.Y.Z\`** — <MINOR/PATCH>
+   lockstep cut. <BREAKING: one-line summary | No breaking changes.> See
+   [§ vX.Y.Z section below](#anchor).` Every cut gets a bullet, breaking or not —
+   the consumer sweep walks this index to find its version span.
+2. **Per-cut section** for breaking cuts, containing, in order:
+   - the breaking-change list, each item with: the old form, the new form, and
+     a **greppable pattern** (`git grep -n '<old>'`) a consumer can sweep;
+   - mechanical vs **judgment items** separated — judgment items (semantic
+     flips, behavioral defaults) are explicitly marked *never auto-sweep*;
+   - the verify command(s) that prove the sweep landed.
+3. **Anchors are stable** — section headings are linked from release notes and
+   consumer tooling; never retitle an existing section.
+4. Soft-API graduations (`_debug.*` → top-level) are documented even though
+   non-breaking — consumers key on them.
+
+## Consumer expectations (adia-migrate)
+
+The sweep discipline reads: index bullet(s) for the span → per-cut sections →
+grep audit with the given patterns → mechanical sweeps → judgment items
+surfaced to the operator → verify gates. A guide entry missing a greppable
+pattern or a verify command is a producer defect — report it upstream, do not
+improvise a sweep.

package/references/data-and-hydration.md

@@ -2,12 +2,12 @@
 name: data-and-hydration
 load-when: wiring an adia-ui app's data-flow, state ownership, content hydration, or section registration
 load-size: ~2.5k tokens
-required-for: [adia-ui-data — all modes]
+required-for: [adia-data — all modes]
 ---
 
 # Data, state & hydration — patterns
 
-Code shapes for the five data-flow patterns, the three hydration paths, and section wiring. The ownership rules (single-owner · projections-only · attribution) are the `adia-ui-data` rubric gates.
+Code shapes for the five data-flow patterns, the three hydration paths, and section wiring. The ownership rules (single-owner · projections-only · attribution) are the `adia-data` rubric gates.
 
 ## The five patterns
 
@@ -41,7 +41,9 @@ await client.mutate({ type: 'order', payload }, { action_source: btn.dataset.act
 ```js
 table.columns = [{ key:'name', label:'Name', sortable:true }];
 table.data    = rows;          // NOT: append <option>/<tr> children post-connect —
-select.options = opts;         // the element auto-stamps its slots at connected()
+select.options = opts;         // the element auto-stamps its slots at connected(); later-
+                               // appended children land OUTSIDE the stamped popover/listbox
+                               // as visible flow content and break the parent's layout
 ```
 
 **5 · Declarative `data-*`** — static flows; state is CSS.
@@ -59,7 +61,7 @@ select.options = opts;         // the element auto-stamps its slots at connected
 connected() { if (this.#booted) return; this.#booted = true; this.#load(); }
 ```
 
-**SSR — server → props → client.** The framework fetches on the server, seeds components as initial props, and the client refreshes via property binding (React `ref`+`useEffect`, Vue `:prop`, Svelte `bind:`). See `adia-ui-ssr`.
+**SSR — server → props → client.** The framework fetches on the server, seeds components as initial props, and the client refreshes via property binding (React `ref`+`useEffect`, Vue `:prop`, Svelte `bind:`). See `adia-host` / [ssr-integration.md](ssr-integration.md).
 
 **Hybrid — SPA island in an SSR page.** The server renders the page and emits the island's seed as a prop/attribute; the island **registers + boots on the client** and owns its own state and in-island routing. The framework owns the page and top-level routing; the island is a self-contained SPA surface inside it.
 
@@ -81,4 +83,5 @@ Rule: exactly one route owner _per scope_ — the framework routes the page; a c
 
 - **Content-less `<router-ui>`** for in-DOM/in-island tabs: routes _without_ `content`; CSS shows the active view. A content-mode route fetches + `innerHTML`-replaces — wrong for stamped views.
 - **Own the URL** when you need query params: `history.replaceState(...)` and reflect `data-route-path` yourself; don't set `router.routes` (it path-routes and clobbers query params).
-- **Single owner** per piece of state — the route owns the active view, the component owns selection/toggles, the DataClient owns fetched data. A control mutates the route; an observer/CSS reflects it back — never a second source of truth.
+- **Single owner** per piece of state — the ownership assignments are the `adia-data` rubric gates; the mechanic: a control mutates the route, an observer/CSS reflects it back — never a second source of truth.
+- **Never reset user-set state from a sibling control** — changing one selector (engine, tab) must not auto-reset an unrelated user-controlled one (mode, theme), even if the new selection ignores that setting.

package/references/genui-a2ui.md

@@ -2,7 +2,7 @@
 name: genui-a2ui
 load-when: authoring a generative-UI experience — mounting the a2ui runtime, feeding generated A2UI, wiring resolvers, or using the corpus
 load-size: ~2.5k tokens
-required-for: [adia-ui-genui — all modes]
+required-for: [adia-genui — all modes]
 ---
 
 # a2ui runtime & corpus — consumer surface
@@ -14,8 +14,8 @@ The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs cu
 **`<a2ui-root>`** — renders an A2UI surface.
 
 - **Author mode:** set `.doc = A2UIMessage[]` (a JS property; setting it re-renders). Use for editors/previews/tests.
-- **Stream mode:** set `src` + `transport` (`sse` | `ws` | `jsonl` | `mcp`); the root opens the stream and reconciles messages as they arrive. (`doc` wins if both are set.)
-- **Events:** `a2ui-message` (per message) · `a2ui-connected` / `a2ui-error` / `a2ui-closed` (stream) · `a2ui-action` (a child `[data-action]` fired). History: `back()` / `forward()`.
+- **Stream mode:** set `src` + `transport` (`sse` | `ws` | `jsonl` | `mcp`); the root opens the stream and reconciles messages as they arrive. (Don't set both — a `doc` reset does not abort an open stream; call `disconnect()` before switching to author mode.)
+- **Events:** `a2ui-message` (per message) · `a2ui-connected` / `a2ui-error` / `a2ui-closed` (stream) · `a2ui-action` (a child `[data-action]` fired).
 
 **`<gen-root mode="chat|split|canvas">`** — a layout shell unifying chat + canvas (+ `inspector` to debug the generated tree). Switch layout via `mode`.
 
@@ -30,10 +30,14 @@ The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs cu
 
 ## A2UI message format
 
+A2UI describes **layout, not behavior**: component trees + props + data/slot
+bindings + primitive refs — never JS behavior or per-canvas CSS. Behavior comes from the
+substrate's traits or pre-built apps; "make the generator emit JS/CSS" is a won't-fix.
+
 A discriminated union the runtime reconciles (set `.doc` to an array of these):
 
 - `createSurface` — `{ type, surfaceId, root? }` — start a surface.
-- `updateComponents` — `{ type, surfaceId, components: [{ id, component, children?, ...props }] }` — upsert the tree; `component` is an A2UI type name (`Card`, `Text`, `Stat`, …); other keys are props. A prop can be a **data binding** `{ path: 'kpi/value' }`.
+- `updateComponents` — `{ type, surfaceId, components: [{ id, component, children?, ...props }] }` — upsert the tree; `component` is an A2UI type name (`Card`, `Text`, `Stat`, …); other keys are props. A prop can be a **data binding** `{ path: 'kpi/value' }`. A `textContent` prop only hard-sets text on pure-text leaves (the runtime whitelists them) — on container components it routes through the `text=` attribute instead, because `el.textContent = …` would wipe the slotted children.
 - `updateDataModel` — `{ type, surfaceId, path, value }` — set data (JSON-Pointer path) that bindings read.
 - `wireComponents` — `{ type, surfaceId, controllers?, dataSources?, … }` — declare controllers/handlers/data sources/actions.
 - `meta` — `{ type, feedback? }` — pipeline metadata/reasoning (traces, feedback).
@@ -49,13 +53,15 @@ Built-in schemes: `resource:` (→ a `/api/...` REST convention), `api:` (direct
 
 ## The loop, end to end
 
-`classify_intent` → `assemble_context` (or `search_chunks` to ground) → `generate_ui` → **`validate_schema` + `check_anti_patterns`** → set `root.doc` → `refine_ui` (carry a `sessionId` for multi-turn; the server keeps the session's fragment state) or `root.back()/forward()`. **Validate before every render** — the runtime renders what you give it; garbage in, garbage rendered.
+`classify_intent` → `assemble_context` (or `search_chunks` to ground) → `generate_ui` → **`validate_schema` + `check_anti_patterns`** → set `root.doc` → on failed validation, `refine_ui(intent, previousMessages, validationErrors)` (monolithic; zettel multi-turn refinement uses `refine_composition` with the `state_id` from the prior `compose_from_chunks`). **Validate before every render** — the runtime renders what you give it; garbage in, garbage rendered.
 
 ## Corpus — core vs roll-your-own
 
 - **Shape:** chunks are JSON (`{ name, kind: block|panel|page, component tree, metadata }`), with an `_index`, a `catalog`, and pre-computed `chunk-embeddings`. Harvested from real pages' `data-chunk` markers.
 - **Core:** the MCP ships and retrieves over it — `search_chunks` (keyword always; semantic when `VOYAGE_API_KEY`/OpenAI is set) / `lookup_chunk`. Offline-capable (embeddings are committed).
-- **Roll your own** _(pattern, lightly documented):_ author demo pages → mark regions with `data-chunk` + `data-chunk-kind`/`-domain`/`-description`/`-keywords` → harvest to chunks → point retrieval at your set → (optional) build embeddings (needs a key). **Grounding rule:** every chunk must trace to a real page — no synthetic chunks.
+- **Roll your own** _(pattern, lightly documented):_ author demo pages → mark regions with `data-chunk` + `data-chunk-kind`/`-slot`/`-domain`/`-description`/`-keywords` (the harvester also reads `-related`/`-tags`) → `npm run harvest:chunks` → point retrieval at your set → (optional) build embeddings (needs a key). **Grounding rule:** every chunk must trace to a real page — no synthetic chunks.
+- **Keep chunks fresh:** after any layout/`@bp` change to `data-chunk`-annotated HTML, re-run `npm run harvest:chunks` in the same session — harvested chunks silently hold the stale values otherwise.
+- **Dev-overlay caveat:** the `?chunks` overlay (`site/dev-chunks.js`) prepends a `<span data-chunk-marker>` into every `[data-chunk]` element — `:first-child`/`:nth-child` rules on those children break during dev only.
 
 ## Consumer vs maintainer
 

package/references/llm.md

@@ -1,10 +1,15 @@
-# LLM features with `@adia-ai/llm`
+---
+name: llm
+load-when: wiring @adia-ai/llm — chat/streamChat signatures, StreamChunk handling, the proxy security model
+load-size: ~1.2k tokens
+required-for: [adia-llm]
+---
 
-Wiring chat / streaming / AI features into an app. This is **app-level LLM use** — distinct from _generating UI markup_, which is the a2ui MCP's `generate_ui` (see the boundary at the end). All of the below is from the framework's own `@adia-ai/llm` package.
+# `@adia-ai/llm` — the app-side LLM client
 
-> **Snapshot, not a spec.** The exact signatures, `StreamChunk` field names, and `<chat-shell-ui>` API below are verified against `@adia-ai/llm` **v0.7.8** (the pinned MCP's sibling). LLM client APIs drift fast — treat precise names as a starting point, confirm against the installed version, and lean on the **smart-proxy contract** (stable) rather than memorizing fields.
+Chat / streaming / AI features for a consumer app. Snapshot verified against **@adia-ai/llm v0.7.26**. LLM client surfaces drift — confirm precise field names against the installed version and lean on the **smart-proxy contract** (stable) rather than memorized fields.
 
-## Import & the core API
+## Import & core API
 
 ```js
 import { chat, streamChat, createClient } from '@adia-ai/llm';
@@ -15,16 +20,16 @@ import { MODELS, DEFAULT_MODEL } from '@adia-ai/llm/models';
 - `streamChat(opts) → AsyncGenerator<StreamChunk>` — streaming; `for await` the chunks.
 - `createClient(defaults) → { chat, stream }` — a client with baked-in defaults.
 
-`ChatOpts` (the fields you'll actually use): `model`, `messages: [{role, content}]`, `provider?` (auto-detected from the model name), `system?`, `maxTokens?`, `temperature?`, `stream?`, `signal?` (AbortSignal), `proxyUrl?`, plus Anthropic extras `thinking?` / `cache?`.
+`ChatOpts` (the fields that matter): `model`, `messages: [{role, content}]`, `provider?` (auto-detected from the model name), `system?`, `maxTokens?`, `temperature?`, `signal?` (AbortSignal), `proxyUrl?`, plus Anthropic extras `thinking?` / `cache?`.
 
-`StreamChunk` is a tagged union — branch on `chunk.type`:
+`StreamChunk` is a tagged union — branch on `chunk.type`, handle every branch:
 
 ```js
 for await (const chunk of streamChat(opts)) {
-  if (chunk.type === 'text')     append(chunk.text);            // also has .snapshot (full text so far)
-  else if (chunk.type === 'thinking') showThinking(chunk.text); // Anthropic extended thinking
+  if      (chunk.type === 'text')     append(chunk.text);        // also .snapshot (full text so far)
+  else if (chunk.type === 'thinking') showThinking(chunk.text);  // Anthropic extended thinking
   else if (chunk.type === 'done')     finalize(chunk.usage, chunk.stopReason);
-  else if (chunk.type === 'error')    fail(chunk.error);
+  else if (chunk.type === 'error')    fail(chunk.error);         // render it — never drop
 }
 ```
 
@@ -34,46 +39,24 @@ Anthropic, OpenAI, and Gemini, **auto-detected from the model name** (`claude*`
 
 ## The proxy / security model — read this first
 
-**Never ship a provider API key to the browser in production.** `@adia-ai/llm` supports two proxy shapes, auto-selected by the `proxyUrl`:
+**Never ship a provider API key to the browser in production.** Two proxy shapes, auto-selected from the `proxyUrl` (a URL matching `/api/llm/<provider>/…` ⇒ passthrough; anything else ⇒ smart):
 
-- **Smart proxy (production):** point `proxyUrl` at your own same-origin endpoint (e.g. `/api/chat`). The browser sends a provider-neutral body (`{provider, model, messages, …}`); **your server** holds the real key, reformats per provider, and pipes the SSE bytes back. The browser never sees a key.
+- **Smart proxy (production):** point `proxyUrl` at your own same-origin endpoint (e.g. `/api/chat`). The browser sends a provider-neutral body (`{provider, model, messages, system?, maxTokens?, temperature?}`); **your server** holds the real key, reformats per provider, and pipes the SSE bytes back. The browser never sees a key.
 
   ```js
   for await (const c of streamChat({ proxyUrl: '/api/chat', model, messages })) { … }
   ```
 
-  A reference server lives at `@adia-ai/llm`'s `server.js` (`POST /api/chat`).
+  Reference implementation (monorepo only — `server.js` is not in the npm-published files): `packages/llm/server.js` (`POST /api/chat`).
 
-- **Passthrough proxy (LOCAL DEV ONLY):** a `proxyUrl` matching `/api/llm/<provider>/…` (e.g. a Vite dev proxy). The browser sends the real upstream body **and the real key in headers** — anyone with DevTools can read it. The package logs a loud one-time warning. **Never deploy this shape.**
+- **Passthrough proxy (Vite dev ONLY):** a `proxyUrl` matching `/api/llm/<provider>/…` (e.g. a Vite dev proxy). The browser sends the real upstream body **and the real key in headers** — anyone with DevTools can read it. **Never deploy this shape.**
 
-When authoring: default to the smart-proxy pattern; only use passthrough behind a Vite dev proxy, and say so explicitly.
+When authoring: default to the smart-proxy pattern; use passthrough only behind a Vite dev proxy, and say so explicitly.
 
-## The chat shell
+## Chat surface wiring
 
-`<chat-shell-ui>` is a behavior-only web-module that renders a chat surface and wires it to `streamChat` for you:
-
-```html
-<chat-shell-ui proxy-url="/api/chat" model="claude-sonnet-4-6">
-  <chat-header><span slot="name">Assistant</span><chat-status slot="status"></chat-status></chat-header>
-  <chat-thread><chat-empty><empty-state-ui heading="Hello!"></empty-state-ui></chat-empty></chat-thread>
-  <chat-composer><chat-input-ui placeholder="Message…"></chat-input-ui></chat-composer>
-</chat-shell-ui>
-```
-
-- **Properties:** `model`, `provider`, `proxyUrl`, `system`, `thinking`, `streaming`.
-- **Events:** `submit`, `chunk`, `thinking`, `done`, `error`, `abort`, `message`, `clear`.
-- **Methods:** `send(text, {model})`, `appendMessage(...)`, `clear()`, `abort()`; accessors `messages` / `conversation` / `export` / `import(...)`.
-
-Set `proxy-url` (or, dev-only, an `apiKey`) and it auto-sends on submit; otherwise it just emits `submit` for you to handle. For SSR, register it client-side like any other component (see `ssr-integration.md`).
-
-## Boundary: app LLM vs. UI generation
-
-Two separate paths — don't conflate them:
-
-- **`@adia-ai/llm`** — a generic chat/streaming client for _your app's_ AI features (a chat box, a summarize button). Knows nothing about A2UI.
-- **a2ui MCP `generate_ui`** — turns an intent into A2UI component markup (retrieval-first, LLM fallback). Use it to _build UI_, then `validate_schema` / `check_anti_patterns` (see `a2ui-mcp-tools.md`).
-- The bridge (`createAdapter` from `@adia-ai/llm/bridge`) is what the A2UI generation pipeline uses internally to call an LLM for that fallback — you rarely call it directly.
+`<chat-shell proxy-url="/api/chat" model="…">` auto-sends on submit via `streamChat` and renders the stream for you; without `proxy-url` (or a dev-only `apiKey` property) it only emits `submit` for you to handle. The full surface — cluster roster, props/events/methods, registration gotchas — lives in [`shell-chat.md`](shell-chat.md); this file owns only the client/proxy contract.
 
 ## Not in the package (don't assume)
 
-Tool/function-calling chunks, structured-output/JSON-schema modes, built-in retry/backoff, and client-side token estimation are **not** surfaced by `@adia-ai/llm` as of this snapshot. If you need them, handle them in your own server layer — and check `mcp__a2ui__search_chunks` for anything added since.
+Tool/function-calling chunks, structured-output/JSON-schema modes, built-in retry/backoff, and client-side token estimation are **not** surfaced by `@adia-ai/llm` v0.7.26 — handle them in your own server layer. `createAdapter` from `@adia-ai/llm/bridge` is the A2UI generation pipeline's internal LLM adapter; an app rarely calls it directly.