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

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.

package/references/migration.md

@@ -1,57 +1,131 @@
----
-name: migration
-load-when: migrating an adia-ui app — version upgrade, port-to-adia, or mode change
-load-size: ~2.5k tokens
-required-for: [adia-ui-migrate — all types]
----
+# Migration — types, history, sweep depth
 
-# Migration — types, history, discipline
-
-Consumer migrations. The framework MIGRATION GUIDE (in the framework repo) is the source of truth per version; this is the durable method + the shape of past breaks. Treat versions/examples as a snapshot.
+Consumer migrations: the durable method + the shape of past breaks. The framework MIGRATION
+GUIDE (`.claude/docs/MIGRATION GUIDE.md` in the framework repo — the space in the filename is
+intentional) is the per-version source of truth; its required shape is
+[`contracts/migration-guide-format.md`](contracts/migration-guide-format.md). Loaded by
+`adia-migrate` (all migration types). Versions and examples below are a snapshot, not a registry.
 
 ## Types
 
-- **version-upgrade** — bump `@adia-ai/*` X→Y (lockstep; all packages move together). PATCH cuts are drop-in; MINOR/MAJOR carry breaking items.
-- **port-to-adia** — an existing app (raw HTML, or legacy `@agent-ui-kit`) → adia-ui: a tag rename map (`aui-button`→`button-ui`, `<button>`→`<button-ui>`) + token namespace swap (`--n-*`→`--a-*`).
-- **mode-change** — SPA↔SSR: re-own routing (framework router vs `<router-ui>`), registration (top-level vs client-hook), and state (signals vs cookies). See `adia-ui-spa` / `adia-ui-ssr`.
-
-## The 5-step discipline
-
-1. **Read the guide** for the target version. Missing section → pause, ask, offer to draft it.
-2. **Audit** — `git grep -nlE '<pattern>'` each breaking item; cluster by component; count files/occurrences. Surface before sweeping.
-3. **Sweep** — mechanical per cluster:
+- **version-upgrade** — bump `@adia-ai/*` X→Y (lockstep; all packages move together). PATCH
+  cuts are drop-in; MINOR/MAJOR carry breaking items.
+- **port-to-adia** — an existing app (raw HTML, or legacy `@agent-ui-kit`) → adia-ui: a tag
+  rename map (`aui-button`→`button-ui`, `<button>`→`<button-ui>`) + token namespace swap
+  (`--n-*`→`--a-*`).
+- **mode-change** — SPA↔SSR: re-own routing (framework router vs `<router-ui>`), registration
+  (top-level vs client-hook), and state (signals vs cookies). `adia-host` carries both paths.
+
+## The 5-step sweep — depth
+
+1. **Read the guide** for the version span: index bullets → per-cut sections. Each breaking
+   item ships an old form, a new form, and a greppable pattern (the contract above). A missing
+   section, or an item without a pattern/verify command, is a producer defect — pause, report
+   upstream; don't improvise a breaking surface.
+2. **Audit** — `git grep -nE '<pattern>'` per item; cluster by component; report file +
+   occurrence counts and show the list before changing anything. Consumer code has edge cases
+   the canonical regexes don't anticipate (a `variant="danger"` on a non-button custom element
+   that shares the prefix).
+3. **Sweep** — mechanical per approved cluster:
 
    ```bash
    git grep -lE 'button-ui[^>]*variant="danger"' \
      | xargs perl -i -pe 's/(<button-ui[^>]*?)variant="danger"/$1color="danger"/g'
    ```
 
-   …or a shipped codemod. **Flag, don't auto-apply, judgment items** (below).
-
-4. **Verify** — `adia-lint` clean of `LEGACY-SHELL`/`NATIVE-PRIMITIVE`; build/render; then the **leftover-drift grep** across `.css`/`.js`/`.md`/`.json`; browser probe.
+   Judgment items (below) are flagged, never swept.
+4. **Verify** — `adia-lint` clean of `LEGACY-SHELL`/`NATIVE-PRIMITIVE`; the app's own build +
+   the browser gate ([`verification.md`](verification.md)); then the leftover-drift pass below.
 5. **Report** — per-axis counts, manual-review list, gate results, next actions.
 
-## Real breaking-change history (before → after)
+### Sweep anti-patterns (each shipped a real regression)
 
-- **v0.0.20 (10 items):** `<button-ui variant="danger">` → `variant="solid" color="danger"`; stage Booleans (`completed`/`active`) → `status="completed|active"` enum (timeline/stepper/pipeline); `<table-toolbar-ui>` opt-out Booleans **inverted** (`searchable="false"` → `no-search`; default flipped); `<chat-input-ui busy>` → `loading`; `variant="error"` alias removed → `danger`; event prefixes dropped (`chat-submit`→`submit`); `<field-ui error>` moved to the child input; `<agent-trace-ui open>` → `collapsed` (**semantic flip — default-visible now**); kebab prop keys → camelCase (JS only). Safari floor → 18.
-- **v0.0.29 — three-tier extraction:** `patterns/` moved `@adia-ai/web-components/patterns/*` → `@adia-ai/web-modules/{shell,chat,editor,runtime}/*`. Import-path rewrite + add the `web-modules` dep.
-- **v0.4.0 — legacy shell shapes retired (ADR-0024):** `<aside data-sidebar>`→`<admin-sidebar slot>`; `<dialog data-command>`→`<admin-command>`; `[data-chat-messages/input/empty]`→`<chat-thread>/<chat-composer>/<chat-empty>`; `[data-editor-body]/[data-canvas]`→`<editor-canvas>` + `<editor-sidebar>`. JS selectors move with them. (`adia-lint` `LEGACY-SHELL` flags the remnants.)
-- **v0.6.0/0.6.1:** `stat-ui.{js,css}`→`stat.{js,css}` (deep-import only); `<link-ui>` token rename `--link-color-*`→`--link-fg-*` (only if you override).
+- **One component per sweep.** `<(toast|alert|tag)-ui[^>]*variant="error"` looks efficient, but
+  perl/sed alternation captures don't substitute the matched alternative cleanly — loop
+  `for tag in toast alert tag` instead.
+- **HTML-attribute regexes don't cover JS property sites.** `<chat-input-ui busy>` and
+  `el.busy = true` are two audits — sweep `\.busy\s*=` separately, scoped to app code.
+- **`git grep -lE | xargs perl -i`, never `find … -exec perl`.** git grep excludes
+  `node_modules/`, `dist/`, `.git/`; a raw find doesn't.
 
-## Judgment items (flag for review — never auto-sweep)
-
-Semantic flips (`[open]`→`[collapsed]` inverts default visibility), Boolean opt-out inversions (default changes), attribution transfers (`field-ui error` → child input may not exist yet). Surface these with their call sites; let the author decide.
-
-## What the path-only sweep misses (leftover-drift categories)
+## Real breaking-change history (before → after)
 
-Bare-name mentions in prose docs (README/AGENTS/ROADMAP); skill-directory names; JSON metadata fields (highest impact — silent harvest miss on rebuild); inventory tables in cross-cutting docs. Use a pre/post grep diff:
+- **v0.0.20 (10 items):** `<button-ui variant="danger">` → `variant="solid" color="danger"`
+  (canonical form; the guide's mechanical sweep emits just `color="danger"`, leaning on `solid`
+  being the default variant); stage Booleans (`completed`/`active`) → `status="completed|active"`
+  enum (timeline/stepper/pipeline); `<table-toolbar-ui>` opt-out Booleans **inverted**
+  (`searchable="false"` → `no-search`; default flipped); `<chat-input-ui busy>` → `loading`;
+  `variant="error"` alias removed → `danger`; event prefixes dropped (`chat-submit`→`submit`,
+  `legend-toggle`→`toggle`, `slide-change`→`change`); `<field-ui error>` moved to the child
+  input; `<agent-trace-ui open>` → `collapsed` (**semantic flip — default-visible now**); kebab
+  prop keys → camelCase (JS only). Safari floor → 18.
+- **v0.0.29 — three-tier extraction:** `patterns/` moved `@adia-ai/web-components/patterns/*` →
+  `@adia-ai/web-modules/{shell,chat,editor,runtime}/*`. Import-path rewrite + add the
+  `web-modules` dep.
+- **v0.4.0 — legacy shell shapes retired (ADR-0024):** `<aside data-sidebar>`→`<admin-sidebar
+  slot>`; `<dialog data-command>`→`<admin-command>`; `[data-chat-messages/input/empty]`→
+  `<chat-thread>/<chat-composer>/<chat-empty>`; `[data-editor-body]/[data-canvas]`→
+  `<editor-canvas>` + `<editor-sidebar>`. JS selectors move with the markup. (`adia-lint`
+  `LEGACY-SHELL` flags the remnants.)
+- **v0.6.0/0.6.1:** `stat-ui.{js,css}`→`stat.{js,css}` (deep-import only); `<link-ui>` token
+  rename `--link-color-*`→`--link-fg-*` (only if you override).
+
+## Judgment items (flag with call sites — the author decides, never a sweep)
+
+- **Semantic flips** — `<agent-trace-ui open>`→`[collapsed]` is an inversion, not a rename:
+  `[open]` was default-hidden/opt-in, `[collapsed]` is default-visible/opt-out. Trace meant to
+  show? drop the attribute. Meant hidden? write `collapsed`.
+- **Boolean opt-out inversions** — `<table-toolbar-ui>`: the legacy Booleans defaulted to
+  `true`, so a bare `filterable` was a no-op; only an explicit `searchable="false"` carried
+  intent (→ `no-search`). A regex can't tell the two apart.
+- **Attribution transfers** — `<field-ui error="…">` moves the message to the child input,
+  which may not exist yet in the markup.
+- **JS-only key renames** — kebab property keys (`el['submit-label']`→`el.submitLabel`): the
+  HTML attribute form is unchanged, so attribute-only consumers need no change. Audit
+  programmatic access only.
+
+## Leftover drift — what the path-only sweep misses
+
+A vocabulary migration touches the markup but not the CSS selectors that style it, the JS
+comments that mention it, or the metadata that indexes it — different files, so a markup-only
+commit looks complete. Close with a pre/post grep diff:
 
 ```bash
 grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/pre.txt
 # … sweep …
-grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/post.txt && diff /tmp/pre.txt /tmp/post.txt
+grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/post.txt
+diff /tmp/pre.txt /tmp/post.txt   # anything left post-sweep is a stale ref to investigate
 ```
 
-## MCP aids
-
-`search_chunks` (the updated example for a changed component) · `check_anti_patterns` (a swept file is clean) · `convert_html` (map legacy/foreign markup → current components, for ports). There's no "list breaking changes" tool — the MIGRATION GUIDE is read by hand.
+Categories that have survived full-path sweeps:
+
+- **Bare-name prose mentions** in narrative docs and inventory tables (README, roadmap-style
+  indexes) — grep `\b<old-name>\b` over `*.md` / `*.yaml`, not just paths.
+- **Directories named after the renamed thing** (skill dirs, config dirs) — dir vs frontmatter
+  mismatch check:
+
+  ```bash
+  for skill in $(find . -name 'SKILL.md' -not -path '*/node_modules/*'); do
+    dir=$(basename $(dirname "$skill")); name=$(grep -m1 '^name:' "$skill" | sed 's/name: *//')
+    [ "$dir" != "$name" ] && echo "MISMATCH: $skill (dir=$dir, name=$name)"
+  done
+  ```
+
+- **JSON metadata at filename granularity** (highest impact — a stale `source`/`page` field is
+  a *silent* harvest miss on the next rebuild; no error is raised):
+
+  ```bash
+  for f in 'old-name.html' 'old-name.contents.html' 'old-name.contents.js'; do
+    grep -rn "$f" --include='*.json' | grep -v '/dist/' | grep -v '/node_modules/'
+  done
+  ```
+
+- **Refs to the directory itself, not the tag** — barrel JS exports, CSS `@import`s, HTML link
+  rels, sitemap/content paths name the old *dir*; a tag-rename sweep never touches them. Grep
+  the old directory name separately.
+- **Relative-import depth after `git mv`** — grep each moved file for `../` imports and fix the
+  depth; builds don't load them, so the breakage surfaces only in the browser. A doc move needs
+  a *different* rewrite per linking file's own depth — precompute per file.
+- **Hard-coded source lists in build scripts** — `SOURCES = […]` / include-dir arrays silently
+  drop renamed or new siblings while the build runs clean; diff output counts against the
+  pre-rename baseline after any rename.

package/references/project-shapes.md

@@ -1,13 +1,6 @@
----
-name: project-shapes
-load-when: classifying or laying out an adia-ui app's structure — picking the project shape, the four-axis layout, or page-trio vs page-DUO
-load-size: ~2.5k tokens
-required-for: [adia-ui-factory shape classifier, adia-ui-project (scaffold / add-surface / add-page)]
----
-
 # Project shapes & structure
 
-How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `bin/adia-scaffold` mechanizes the layout.
+How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `bin/adia-scaffold` mechanizes the layout. Loaded by `adia-orient` (shape classifier) and `adia-project` (layout / scaffold / inventory).
 
 ## The four-axis layout (all shapes)
 
@@ -56,7 +49,7 @@ Use for: a suite of related surfaces (a SaaS admin, a flow set, a demo gallery).
 
 ### Shared-foundation — sibling apps over a shared core
 
-Root-level `spec/plan/` for cross-app concerns; each app under `app/<name>/` with its own `spec/plan/src/`; a shared `app/shared/` (DataClient, loaders, mappers, tokens). The embed pattern lives here → becomes **`adia-embed-shell`**.
+Root-level `spec/plan/` for cross-app concerns; each app under `app/<name>/` with its own `spec/plan/src/`; a shared `app/shared/` (DataClient, loaders, mappers, tokens). The embed pattern lives here — the shell is **`<embed-shell>`** (ships in `@adia-ai/web-modules`, shell cluster); depth: [shell-embed.md](shell-embed.md).
 
 ```text
 app/
@@ -75,13 +68,18 @@ Use for: multiple embedded surfaces sharing data context, components, and an emb
 
 The `.html` shell fetches `.contents.html`, injects it, then dynamically imports `.contents.js` if present. **Rule:** add `.contents.js` only when there's behavior to wire — a DUO with a dead `.contents.js` and a trio missing its setup are both smells.
 
-## State & data — which pattern (depth: `adia-ui-data`)
+Two adjacent contracts:
+
+- `setup` must be `async function setup(host)` when its body contains top-level `await` — extracting inline page script into a non-async `.contents.js` controller turns that `await` into a parse-time SyntaxError.
+- CSS never takes the `.contents.` infix. HTML/JS get it because they're the dynamically-injected fragment + controller; CSS loads statically via `<link>` in the `.html` shell head and styles chrome + contents together, so its name follows scope (per-app / shared / per-component), not the page-form convention.
+
+## State & data — which pattern
 
-`signal()`/`effect()` (single-surface reactivity) · Service/Controller/Command (mutations + undo) · `DataClient.read(projection)` + pure mappers, with **`action_source` required on every `mutate`** (shared-foundation) · property-API (`el.columns = […]`, never post-connect `<option>` children) · declarative `data-*` (static flows). The data skill owns the choice; this is the map.
+The state/data pattern follows the shape, not taste — but the choice is owned by `adia-data`: see [data-and-hydration.md](data-and-hydration.md) for the shape → pattern map.
 
 ## Components
 
-One folder per tag, mirroring the framework: `components/<tag>/<tag>.{js,css}` (folder name = custom-element tag). Authoring discipline: `authoring-components.md`.
+One folder per tag, mirroring the framework: `components/<tag>/<tag>.{js,css}` (folder name = custom-element tag). Authoring discipline: [authoring-components.md](authoring-components.md).
 
 ## Structure rubric `[gate]`
 
@@ -93,4 +91,4 @@ A project is well-structured when (gate = all `[gate]` hold):
 - **Components foldered** `[gate]` — every custom element is `components/<tag>/<tag>.{js,css}`.
 - **No duplicated cross-surface code** `[review]` — shared logic lives in `app/shared/` (or `_shared/`), not copied per page.
 
-Verify target for a scaffold/edit: this rubric passes, and any new surface renders through `adia-ui-verify`.
+Verify target for a scaffold/edit: this rubric passes, and any new surface renders through `adia-verify`.

package/references/shell-admin.md

@@ -2,7 +2,7 @@
 name: shell-admin
 load-when: authoring or debugging an admin-shell app frame (sidebar + topbar + command palette + pages)
 load-size: ~2.5k tokens
-required-for: [adia-ui-shells — admin path]
+required-for: [adia-shells — admin path]
 ---
 
 # admin-shell — the app frame
@@ -49,7 +49,7 @@ Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barre
 
 ## SPA vs SSR
 
-SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only the **page body** via the framework outlet — replace the inner page content with `{children}` / `<slot/>`; never mount `<router-ui>` (see `adia-ui-ssr`).
+SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only the **page body** via the framework outlet — replace the inner page content with `{children}` / `<slot/>`; never mount `<router-ui>` (see `adia-host`).
 
 ## Gotchas (mechanized where noted)
 
@@ -61,5 +61,8 @@ SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only th
 - **Multiple `<admin-page>` in one `<admin-scroll>`** → single-axis scroll breaks; one page per scroll.
 - **`@container (…)` instead of `@container page-content (…)`** → won't react to sidebar collapse.
 - **Legacy shapes** (`<aside data-sidebar>`, `<dialog data-command>`) — retired v0.4.0 (`adia-lint` `LEGACY-SHELL`).
+- **Sidebar nav is `<nav-ui>` + `<nav-item-ui>`**, never `<menu-ui>`/`<menu-item-ui>` — menu-ui is for Popover-API dropdowns, not persistent navigation.
+- **Full-height mount:** an intermediate wrapper (`<main id="app">`) between `body { height: 100dvh; display: flex }` and the shell needs `flex: 1; display: flex; min-height: 0` — without it the flex chain breaks and the shell collapses to content height.
+- **`header-ui` has no CSS of its own** — its icon/heading/description/action grid comes from the parent's `@scope` (`admin-page-header` provides it); bespoke chrome reusing the header-ui vocabulary must supply the grid + text ellipsis locally.
 
 Real usage: `apps/saas/app/admin-dashboard/`.

package/references/shell-chat.md

@@ -2,12 +2,12 @@
 name: shell-chat
 load-when: authoring a chat-shell LLM conversation surface
 load-size: ~1.5k tokens
-required-for: [adia-ui-shells — chat path]
+required-for: [adia-shells — chat path]
 ---
 
 # chat-shell — the conversation surface
 
-LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `adia-ui-llm` — this is the _surface_; that is the _wiring_.
+LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `adia-llm` — this is the _surface_; that is the _wiring_.
 
 ## Cluster roster
 
@@ -33,12 +33,14 @@ LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-mod
 
 ## Wiring to the LLM
 
-Set `proxy-url` (or, dev-only, `apiKey`) and the shell **auto-sends on submit** via `streamChat` and renders the stream for you. Otherwise it just emits `submit` — you call your endpoint and drive the UI with `appendChunk`/`done`/`error`. **Security:** the production pattern is a same-origin smart proxy that holds the key server-side — never ship a provider key to the browser. Full client/proxy contract: `adia-ui-llm`.
+Set `proxy-url` (or, dev-only, `apiKey`) and the shell **auto-sends on submit** via `streamChat` and renders the stream for you. Otherwise it just emits `submit` — you call your endpoint and drive the UI with `appendChunk`/`done`/`error`. **Security:** the production pattern is a same-origin smart proxy that holds the key server-side — never ship a provider key to the browser. Full client/proxy contract: `adia-llm`.
 
 ## Gotchas
 
 - Import the **chat barrel**; piecemeal imports leave children unregistered.
+- `chat-input-ui` internally renders `textarea-ui` + `select-ui` (web-components primitives, invisible in your authored HTML) — the app must register those primitives too, or they stay undefined and collapse to 0px.
 - Legacy shapes (`[data-chat-messages]`, `[data-chat-input]`, `[data-chat-empty]`, `[data-chat-name]`) were retired v0.4.0 — use the bespoke tags (`adia-lint` `LEGACY-SHELL`).
 - SSR: register `<chat-shell>` client-side like any component; keep the key server-side.
+- **Reasoning/trace panels must surface their own reliability** — a bare status label (`Domain: data`) reads identically at 3% and 95% confidence; a label that hides the data needed to judge it is pragmatically deceptive. Show the confidence with the claim.
 
 Real usage: `apps/genui/app/factory-chat/`.

package/references/shell-editor.md

@@ -2,7 +2,7 @@
 name: shell-editor
 load-when: authoring an editor-shell — a design tool / canvas with resizable side panes
 load-size: ~1.2k tokens
-required-for: [adia-ui-shells — editor path]
+required-for: [adia-shells — editor path]
 ---
 
 # editor-shell — the canvas + panes