@adia-ai/adia-ui-factory 0.2.2

package/references/authoring-components.md

@@ -0,0 +1,88 @@
+# Authoring a project component
+
+When no catalog primitive composes to the need, author a light-DOM custom element. The discipline below is what separates a component that themes, scales, and survives HMR from one that fights the system. It mirrors the framework's own audit gates — the `adia-lint` hook and the MCP's `check_anti_patterns` mechanize the catchable parts.
+
+## The skeleton
+
+A component is three files in one folder (`components/<tag>/`):
+
+```text
+components/my-thing/
+├── my-thing.js      # the class + side-effect registration
+├── my-thing.css     # the @scope block (token-only)
+└── my-thing.class.js  # (optional) the class alone, for tests/subclassing
+```
+
+```js
+// my-thing.js
+import { defineIfFree } from '@adia-ai/web-components/core/register.js';
+import { UIElement } from '@adia-ai/web-components/core/element.js';
+
+class UIMyThing extends UIElement {
+  static properties = { /* declared props become signals */ };
+  connected()    { /* set up; pair every addEventListener with a teardown */ }
+  disconnected() { /* remove every listener added in connected() */ }
+}
+defineIfFree('my-thing', UIMyThing);   // idempotent — safe on HMR / double import
+export { UIMyThing };
+```
+
+## The two-block `@scope` CSS (mandatory shape)
+
+Every component stylesheet is scoped to its tag and split into a zero-specificity token block and a base block:
+
+```css
+@scope (my-thing) {
+  :where(:scope) {                 /* specificity (0,0,0) — themes + consumers override cleanly */
+    --my-thing-bg:     var(--a-ui-bg);
+    --my-thing-fg:     var(--a-ui-text);
+    --my-thing-radius: var(--a-radius);
+    --my-thing-px:     var(--a-ui-px);
+  }
+  :scope {                         /* specificity (0,1,0) — base styles, consume component tokens only */
+    display: flex;
+    padding-inline: var(--my-thing-px);
+    background: var(--my-thing-bg);
+    color: var(--my-thing-fg);
+    border-radius: var(--my-thing-radius);
+  }
+  :scope[variant="outline"] {      /* variants = token overrides only, never layout */
+    --my-thing-bg: transparent;
+  }
+}
+```
+
+**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.
+
+## 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).
+- **Size-agnostic chrome.** Never set `width`/`height`/`inline-size` on the tag's `:scope`. The component owns _intrinsic_ sizing (`min-height`, `padding`, `gap`); the **consumer** (a layout primitive or explicit style) owns extent. Width-on-tag fights the placer and the resizable frame.
+- **Light DOM only.** Never `attachShadow`. No `::slotted()` (a shadow-DOM API) — style slotted content via `:scope > [slot="x"]`. To _read_ projected children, use `logicalChildren` / `logicalSlotted` from `@adia-ai/web-components/core/logical-children` — plain `this.children` misses children rendered through `${items.map(…)}` and the `display:contents` trap.
+- **Guard define and boot.** `defineIfFree` guards re-definition; also guard the boot (`#booted` flag in `connected()`) — the callback fires again whenever the element moves in the DOM, which otherwise double-renders.
+- **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).
+
+## Anti-patterns (the lint seeds)
+
+The mechanizable smells the framework audits — these seed the phase-(c) hook and overlap the MCP's `check_anti_patterns`. Grep hints in parens.
+
+| Smell | Fix |
+| --- | --- |
+| Shadow DOM (`attachShadow`) | light DOM only |
+| Raw color in component CSS (`#`, `rgb(`, `oklch(`) | `var(--a-*)` token |
+| Raw px ≥ 3 without carve-out comment | `var(--a-space-*)` |
+| `::slotted(` | `:scope > [slot="x"]` |
+| `width`/`height`/`inline-size` on the tag `:scope` | consumer owns extent |
+| Dead font token (`--a-font` ≠ `--a-font-family*`) | floor to `--a-font-family-ui` |
+| Single `:scope` block (no `:where(:scope)` token block) | two-block `@scope` |
+| Boolean prop `default: true` | flip the name (`closable`→`permanent`) so absent = false |
+| `attr:` in a property def | `attribute:` |
+| `title`/`error`/`active`/`disabled` as a prop name | `heading` / `danger` / `value`/`step` / `readonly` |
+| Bare `<div>` for layout; raw `<button>`/`<input>` | `<col-ui>`/`<row-ui>`/`<grid-ui>`; the `*-ui` control |
+| Card/drawer body not wrapped in `<section>` | `<card-ui><section>…</section></card-ui>` |
+| 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.

package/references/component-model.md

@@ -0,0 +1,71 @@
+# The adia-ui component model
+
+How to _think_ about the catalog. The **live** catalog is the a2ui MCP (`get_component_map`, `lookup_component`, `get_traits`) — query it for exact names, props, and counts; don't memorize them here (they drift per release). This file teaches the vocabulary so the MCP's answers make sense.
+
+## Three tiers
+
+| Tier | Package | What it is | Examples (shape, not a contract) |
+| --- | --- | --- | --- |
+| **Primitives** | `@adia-ai/web-components` | Atomic custom elements — controls, layout, display, overlays | `<button-ui>` `<input-ui>` `<select-ui>` `<table-ui>` `<card-ui>` `<modal-ui>` `<drawer-ui>` |
+| **Layout primitives** | (same) | The box model — never hand-roll a bare `<div>` for layout | `<col-ui>` `<row-ui>` `<grid-ui>` `<stack-ui>` `<page-ui>` `<section-ui>` |
+| **Traits** | (subpath) | Reusable _behaviors_ attached to any element — not data, not components | `pressable` `focusable` `draggable` `ripple` `scale-press` `roving-tabindex` `focus-trap` |
+| **Composites / shells** | `@adia-ai/web-modules` | Multi-component surfaces / page chrome | `<admin-shell>` `<admin-sidebar>` `<chat-shell>` `<editor-shell>` |
+
+**Naming:** kebab-case with a `-ui` **suffix** (`<button-ui>`, not `<a-button>`). Shells/composites carry a domain prefix (`<admin-*>`, `<chat-*>`).
+
+**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.
+
+## Registration is a side effect of import
+
+Importing a component module **registers its tag**. Two forms:
+
+```js
+import '@adia-ai/web-components';            // the barrel — registers every primitive (incl. router-ui)
+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).
+
+## Signals, not a virtual DOM
+
+Components extend `UIElement` (or `UIFormElement` for form-participating controls) and use fine-grained signals:
+
+```js
+import { UIElement, signal, computed, effect } from '@adia-ai/web-components/core/element.js';
+```
+
+- `signal(v)` — reactive value (`.value` get/set)
+- `computed(() => …)` — memoized derived value
+- `effect(() => …)` — runs on dependency change; auto-cleans on disconnect
+
+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.
+
+## Traits — behavior by declaration
+
+```html
+<button-ui traits="pressable scale-press ripple">Save</button-ui>
+```
+
+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`.
+
+## Tokens — the only styling currency
+
+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` |
+
+- **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">`).
+- **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`.
+
+## "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.
+
+## 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/data-and-hydration.md

@@ -0,0 +1,84 @@
+---
+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]
+---
+
+# 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.
+
+## The five patterns
+
+**1 · Signals** — fine-grained reactivity (no virtual DOM).
+
+```js
+import { signal, computed, effect } from '@adia-ai/web-components/core/signals.js';
+const view = signal('live');
+effect(() => render(view.value));   // re-runs on change; auto-cleans on disconnect
+```
+
+**2 · Service / Controller / Command** — CRUD with undo. The Service is **async from day one** (so an in-memory impl can later swap for a remote one behind the same interface); the Controller orchestrates signals + service; Commands record patches for undo.
+
+```js
+class InMemoryTaskService { async create(d){…} async update(id,d){…} async delete(id){…} }
+// swap for RemoteTaskService (same interface) → Controller + Commands unchanged
+```
+
+**3 · DataClient + mappers** — the UI reads typed **projections**, never a backend. The pure mapper is the fixtures⇄API swap seam.
+
+```js
+const labs = await client.read({ type: 'LabRecommendationSet', params });   // → projection
+// mapper lives in app/shared/corpus/mappers/, pure: (sources) => Projection
+await client.mutate({ type: 'order', payload }, { action_source: btn.dataset.action }); // attribution REQUIRED
+```
+
+**Attribution `[gate]`:** every `mutate` passes an `action_source`; the client throws without it.
+
+**4 · Property-API binding** — populate catalog components by property, not children.
+
+```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()
+```
+
+**5 · Declarative `data-*`** — static flows; state is CSS.
+
+```html
+<main data-auth> … </main>
+<style>[data-auth] form { display: block; }</style>
+```
+
+## The three hydration paths
+
+**SPA — self-boot.** The surface is a self-booting container; it fetches and renders itself.
+
+```js
+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`.
+
+**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.
+
+```html
+<!-- server-rendered page (SSR) -->
+<analytics-panel data-seed-id="abc"></analytics-panel>
+<script type="module">import('/islands/analytics-panel.js');</script>  <!-- client-only registration -->
+```
+
+Rule: exactly one route owner _per scope_ — the framework routes the page; a content-less `<router-ui>` may route tabs **inside** the island. Never let the island's router fight the framework's.
+
+## Section registration & connection
+
+- **Register by side-effect import** — the barrel (`@adia-ai/web-components`) or the component module; an unimported section never upgrades.
+- **Data down, events up** — props in (`.rec = …`), `CustomEvent`s out; no reaching into a parent's internals.
+- **Read projected children** via `logicalChildren` / `logicalSlotted` (from `@adia-ai/web-components/core/logical-children`) — `this.children` misses `${items.map(…)}` output and the `display:contents` trap.
+
+## Routing & state ownership
+
+- **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.

package/references/genui-a2ui.md

@@ -0,0 +1,62 @@
+---
+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]
+---
+
+# a2ui runtime & corpus — consumer surface
+
+The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs custom). Pipeline internals (compose strategies, zettel scoring, catalog) are maintainer territory — not here. Exact names below; treat as a snapshot (re-bake with the pinned MCP).
+
+## Render roots
+
+**`<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()`.
+
+**`<gen-root mode="chat|split|canvas">`** — a layout shell unifying chat + canvas (+ `inspector` to debug the generated tree). Switch layout via `mode`.
+
+```html
+<a2ui-root id="canvas"></a2ui-root>
+<script type="module">
+  import { registerResolver } from '@adia-ai/a2ui-runtime';
+  registerResolver('resource', async (uri) => fetchResource(uri));  // register BEFORE feeding
+  document.getElementById('canvas').doc = validatedMessages;        // A2UIMessage[]
+</script>
+```
+
+## A2UI message format
+
+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' }`.
+- `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).
+
+## registerResolver
+
+```js
+import { registerResolver } from '@adia-ai/a2ui-runtime';
+registerResolver('resource', async (uri, params) => { … });   // resolves resource:// → your data
+```
+
+Built-in schemes: `resource:` (→ a `/api/...` REST convention), `api:` (direct URL), `mock:` (returns a stub). Register **once per session, before** any generated UI references the scheme — an unresolved scheme renders empty.
+
+## 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.
+
+## 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.
+
+## Consumer vs maintainer
+
+Consumer (here): mount roots, register resolvers, call the MCP to generate/validate/refine, use or author a corpus. Maintainer (elsewhere): compose strategies, zettel scoring, the component catalog, embedding-model choice, evals. If you're editing `packages/a2ui/compose/**` or tuning retrieval scoring, you've crossed into maintainer territory.

package/references/llm.md

@@ -0,0 +1,79 @@
+# LLM features with `@adia-ai/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.
+
+> **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.
+
+## Import & the core API
+
+```js
+import { chat, streamChat, createClient } from '@adia-ai/llm';
+import { MODELS, DEFAULT_MODEL } from '@adia-ai/llm/models';
+```
+
+- `chat(opts) → Promise<{ text, usage, stopReason }>` — non-streaming.
+- `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?`.
+
+`StreamChunk` is a tagged union — branch on `chunk.type`:
+
+```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
+  else if (chunk.type === 'done')     finalize(chunk.usage, chunk.stopReason);
+  else if (chunk.type === 'error')    fail(chunk.error);
+}
+```
+
+## Providers
+
+Anthropic, OpenAI, and Gemini, **auto-detected from the model name** (`claude*` → anthropic, `gpt*`/`o1*` → openai, `gemini*` → google). Override with `provider`. Keys are read server-side from `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GOOGLE_API_KEY`.
+
+## 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`:
+
+- **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.
+
+  ```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`).
+
+- **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.**
+
+When authoring: default to the smart-proxy pattern; only use passthrough behind a Vite dev proxy, and say so explicitly.
+
+## The chat shell
+
+`<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.
+
+## 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.

package/references/migration.md

@@ -0,0 +1,57 @@
+---
+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, 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.
+
+## 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:
+
+   ```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.
+5. **Report** — per-axis counts, manual-review list, gate results, next actions.
+
+## Real breaking-change history (before → after)
+
+- **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).
+
+## 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)
+
+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:
+
+```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
+```
+
+## 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.

package/references/project-shapes.md

@@ -0,0 +1,96 @@
+---
+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.
+
+## The four-axis layout (all shapes)
+
+```text
+<app>/
+├── README.md · PATTERNS.md · CHANGELOG.md   # entry + non-obvious patterns + history
+├── spec/     design — BRIEF · ARCHITECTURE · SPEC (+ per-screen specs)
+├── plan/     execution — ROADMAP · MILESTONES · PLAN
+├── skills/   procedural knowledge — <app>-expert/ (optional)
+└── app/      runnable source (shape-specific below)
+```
+
+Keep the axes separate: `spec/` is the contract, `plan/` the sequence, `app/` the build, `skills/` the app's own expertise. The design/plan docs are not optional scaffolding noise — they're how a surface stays traceable to intent.
+
+## The three shapes
+
+### Single-surface — one entry, one surface
+
+One `app/<name>.html` + its contents + a controller; reactive state via signals, often Service/Controller/Command for mutations/undo.
+
+```text
+app/
+├── index.html · <name>.css
+├── components/<tag>/<tag>.{js,css}
+├── controller/ · service/ · state/   # if it has real domain logic
+└── seed-data.js
+```
+
+Use for: a focused tool/widget (a board, a canvas, an embedded panel).
+
+### Rollup — many sibling sub-pages under one app
+
+Each sub-page is a page-trio or page-DUO; a uniform (or per-subflow) shell template loads it. Three flavors:
+
+- **heterogeneous** — independent playgrounds, each its own chrome + logic; shared bits in `app/_shared/`.
+- **homogeneous** — uniform template, fixtures per page, property-API wiring (often `admin-shell`).
+- **declarative-DUO** — mostly static flows (auth/onboarding), per-subflow chrome, few controllers.
+
+```text
+app/
+├── _shared/                         # cross-page helpers (heterogeneous)
+└── <sub>/<sub>.{html,contents.html[,contents.js]}
+```
+
+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`**.
+
+```text
+app/
+├── shared/                          # DataClient · corpus/mappers · components · tokens
+└── <surface>/{spec,plan,src}/       # one per embedded surface
+```
+
+Use for: multiple embedded surfaces sharing data context, components, and an embed bridge.
+
+## Page-trio vs page-DUO
+
+| Form | Files | When |
+| --- | --- | --- |
+| **trio** | `<page>.html` + `<page>.contents.html` + `<page>.contents.js` (`export default setup(host)`) | the surface needs **behavior or property-API wiring** (events, `.columns=…`, streaming) |
+| **DUO** | `<page>.html` + `<page>.contents.html` | the surface is **purely declarative** (static markup, CSS-only state) |
+
+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`)
+
+`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.
+
+## Components
+
+One folder per tag, mirroring the framework: `components/<tag>/<tag>.{js,css}` (folder name = custom-element tag). Authoring discipline: `authoring-components.md`.
+
+## Structure rubric `[gate]`
+
+A project is well-structured when (gate = all `[gate]` hold):
+
+- **Four-axis present** `[gate]` — `spec/` + `plan/` + `app/` (skills/ optional).
+- **Shape declared & matched** `[gate]` — the layout matches one of the three shapes; no half-rollup.
+- **Page form correct** `[gate]` — every surface is trio or DUO per the rule; a DUO carries no `.contents.js`; a trio's `.contents.js` exports `setup`.
+- **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`.

package/references/shell-admin.md

@@ -0,0 +1,65 @@
+---
+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]
+---
+
+# admin-shell — the app frame
+
+Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barrel**: `import '@adia-ai/web-modules/shell'`.
+
+## Cluster roster
+
+`<admin-shell>` (host coordinator) · `<admin-sidebar>` (resizable/collapsible, `slot="leading"|"trailing"`) · `<admin-command>` (Cmd+K palette) · `<admin-content>` (center column) · `<admin-topbar>` / `<admin-statusbar>` (chrome bars, shared slots) · `<admin-scroll>` (vertical scroll container) · `<admin-page>` + `<admin-page-header>` / `<admin-page-body>` / `<admin-page-footer>` (the page; header/footer sticky, body scrolls) · `<admin-entity-item>` (icon+label+badge identity row). Three are JS-bearing (shell, sidebar, command); the rest are CSS-only structure.
+
+## Canonical skeleton
+
+```html
+<admin-shell mode="rounded borderless">
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header"><span slot="heading">Workspace</span></admin-topbar>
+    <nav-ui>…</nav-ui>
+    <admin-statusbar slot="footer"><admin-entity-item slot="heading">…</admin-entity-item></admin-statusbar>
+    <div data-resize></div>                          <!-- required when [resizable] -->
+  </admin-sidebar>
+  <admin-content>
+    <admin-topbar slot="header">
+      <button-ui data-sidebar-toggle="leading" icon="sidebar" variant="ghost"></button-ui>
+      <breadcrumb-ui slot="heading">…</breadcrumb-ui>
+    </admin-topbar>
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header slot="header"><header-ui><span slot="heading">Page</span></header-ui></admin-page-header>
+        <admin-page-body slot="body"><section-ui>…</section-ui></admin-page-body>
+      </admin-page>
+    </admin-scroll>
+    <admin-statusbar slot="footer"><span>Status</span></admin-statusbar>
+  </admin-content>
+  <admin-command><command-ui placeholder="Search…"></command-ui></admin-command>
+</admin-shell>
+```
+
+## Props · events · methods
+
+- `<admin-shell mode>` — space-separated (`rounded` `borderless`; default `"rounded borderless"`). Events (forwarded): `sidebar-toggle {name, expanded}`, `sidebar-resize {name, width}`, `command-select {value}`. Methods: `toggleLeading()` `toggleTrailing()` `openCommand()` `closeCommand()`.
+- `<admin-sidebar>` — `resizable` `collapsible` `name` `min-width`; reflects `[collapsed]` (snap ≤96px) / `[resizing]`. Methods `.toggle()/.collapse()/.expand()`. A `[data-sidebar-toggle="leading"]` button anywhere wires to it via delegation.
+- `<admin-command>` — `open` `shortcut` (`both`|`cmd+k`|`ctrl+k`) `no-shortcut`; `.show()/.hide()`. A `[data-command-trigger]` opens it.
+- Read cross-cutting state off the child: `shell.querySelector('admin-sidebar[slot="leading"]').hasAttribute('collapsed')`; style with `admin-shell:has(admin-sidebar[collapsed]) …`.
+
+## 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`).
+
+## Gotchas (mechanized where noted)
+
+- **Piecemeal import** → `AdminSidebar`/`AdminCommand` unregistered; `.toggle()/.show()` undefined. Import the barrel.
+- **Wrapping shell children in `<col-ui>`/`<row-ui>`** → breaks the grid (it reads tag selectors). Generics go _inside_ `admin-content`/`admin-page-body`.
+- **Raw `<header>` inside `<admin-page-header>`** → slot routing silently drops; wrap `<header-ui>`.
+- **`[resizable]` without a child `<div data-resize>`** → no drag handle.
+- **Hardcoded `[collapsed]`** → won't auto-clear on resize; use `.collapse()/.expand()`.
+- **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`).
+
+Real usage: `apps/saas/app/admin-dashboard/`.