@adia-ai/adia-ui-forge 0.1.2 → 0.8.0

package/skills/adia-a2ui/references/anti-patterns.md

@@ -0,0 +1,27 @@
+# Anti-pattern catalogue — the 8 checks + tuning discipline
+
+`check_anti_patterns` (rule source: `packages/a2ui/retrieval/anti-patterns.js`)
+runs eight checks against rendered HTML:
+
+- `noBareDivs` — use a layout component (`col-ui`, `row-ui`, `grid-ui`, `stack-ui`).
+- `noBareInputs` — use `input-ui` / `select-ui` / `check-ui`.
+- `cardStructure` — flags incorrect card nesting (section > header, etc.).
+- `columnWrap` — section content must be wrapped in `col-ui`.
+- `noHardcodedColors` — no hex/rgb in inline `style` attributes.
+- `noInlineLayout` — no `display: flex` / `grid` in inline styles.
+- `noInventedComponents` — every `*-ui` tag must exist in the catalog.
+- `slotOnContainer` — `slot` attributes belong on content elements, not containers.
+
+## Tuning discipline
+
+- **Don't bypass `validate_schema`.** A low structural score usually explains
+  anti-pattern findings; fix the A2UI JSON before chasing HTML-level issues.
+- **Don't act on stub outputs.** Without the API key loaded, `thinking` mode
+  silently falls back to `StubLLMAdapter`'s canned 6-component card — any
+  finding or feedback against it is noise. Check the output shape first.
+- **Don't commit intermediate JSON.** Scratch files go under the session
+  scratchpad or `.gitignore`d paths; the corpus is harvester-generated into
+  `packages/a2ui/corpus/chunks/` via `npm run harvest:chunks`.
+- **One rule at a time**, and after any rule/threshold change re-run
+  `npm run mcp:smoke` plus a spot-check over known-clean corpus HTML to
+  measure the false-positive delta before landing.

package/skills/adia-a2ui/references/chunk-authoring.md

@@ -0,0 +1,71 @@
+# Chunk authoring — HTML-first synthesis + harvest
+
+The corpus is **one-format and harvester-driven**. Hand-authored pattern /
+composition JSON dirs (`compose/patterns/`, `compose/{fragments,compositions}/`,
+`corpus/patterns/`) were retired; the only retrieval substrate is
+`packages/a2ui/corpus/chunks/` (394 chunks + `_index.json`), produced by
+`npm run harvest:chunks`. In-tree SoT for this workflow:
+`packages/a2ui/corpus/data-flow.md`.
+
+## The authoring loop
+
+1. **Author a live demo** in a harvest root: `apps/<name>/app/<demo>/`,
+   `playgrounds/<name>/`, `catalog/<lib>/app/<demo>/`, or `site/pages/<route>/`.
+   Demo pages are live-rendering and human-verified — they are the canonical
+   source; chunk JSON is derived output.
+2. **Tag retrievable regions** on the bounding element:
+   `data-chunk="<slug>"` + `data-chunk-kind="block|page|panel|field"` +
+   `data-chunk-domain` + `data-chunk-description` + `data-chunk-keywords`.
+   Spec: `.claude/docs/specs/genui-chunk-marker.md`; dev tooling:
+   `site/dev-chunks.{js,css}` (the `?chunks` overlay).
+3. **Harvest** — `npm run harvest:chunks` (dry-run: `harvest:chunks:dry`)
+   walks the source roots, writes `chunks/<slug>.json` + `_index.json`, and
+   runs the transpile pass (`compose/transpiler/`) to produce the A2UI
+   `template` for annotated chunks.
+4. **Embed** (optional but expected for retrieval parity) —
+   `npm run build:embeddings:chunks` regenerates `chunk-embeddings.json`.
+   Freshness gates: `npm run check:chunks-fresh` + `check:embeddings-fresh`.
+5. **Verify** — `npm run smoke:chunks` (stub-LLM, offline) and a rendered
+   check of the demo page; then the eval floor:
+   `npm run eval:diff -- --engine zettel`.
+
+Never hand-author or hand-edit `corpus/chunks/*.json` — they're build outputs;
+the harvester wins on the next run.
+
+## Metadata is the search index
+
+`data-chunk-description` + `data-chunk-keywords` + the slug are what
+`keywordScore()` and `searchAll()` match (name-token hits dominate — see
+[zettel-calibration](zettel-calibration.md)). A chunk whose name lacks its
+entity words is invisible to short queries. Write keyword-rich descriptions
+derived from what's IN the chunk (headings, labels, button text), not
+generic ("content card") prose.
+
+## Component-catalog examples (the other training signal)
+
+Per-component variant coverage lives in the component **yaml** (SoT) at
+`packages/web-components/components/<name>/<name>.yaml`; `<name>.a2ui.json`
+sidecars are **generated** by `node scripts/build/components.mjs` and
+hook-guarded — edit the yaml and rebuild, never the sidecar. Templates use
+PascalCase component names (`Chat`, not `chat-ui`); the registry maps class →
+tag. Demo variants in `<name>.examples.html` are the canonical variant list;
+yaml examples mirror them 1:1. Primitive/demo authoring itself belongs to the
+authoring sibling skill.
+
+## Pitfalls specific to authoring time
+
+- **`?chunks` dev overlay prepends a `<span data-chunk-marker>`** into every
+  `[data-chunk]` element — `:first-child` / `:nth-child` rules on those
+  children break during dev only; don't chase it as a corpus bug.
+- **Page-kind chunks declare slot regions via `data-chunk-slot="X"`** — slot
+  regions are NOT themselves chunks. A new page-kind chunk needs a matching
+  entry in the slot-validation map (`chunk-composer.js`) or compose-time
+  validation rejects its plans.
+- **Chunk-kind matters for retrieval budget** — pages and panels ride
+  unconditionally into the LLM prompt; blocks compete for the remaining
+  `PRE_SEARCH_LIMIT` budget. Mis-kinding a block as a panel inflates every
+  prompt.
+
+After harvest, continue with [corpus-discipline](corpus-discipline.md) for the
+cross-cutting corpus pitfalls, and [leverage-rules](leverage-rules.md) before
+splitting a repeated subtree into its own chunk.

package/skills/adia-a2ui/references/corpus-discipline.md

@@ -0,0 +1,68 @@
+# Corpus discipline — retrieval quality, harvest hygiene, drift traps
+
+## Pipeline-side pitfalls (each one has burned a session)
+
+- **"Thinking mode returns garbage"** → API keys must be in `.env` AND
+  `scripts/load-env.mjs` imported; otherwise the stub adapter answers with a
+  canned 6-component card.
+- **"Search misses obvious patterns"** → inspect chunk metadata first
+  (`npm run audit:corpus-stats`); bad descriptions/keywords = invisible chunks.
+- **"Gate rejects valid intents"** → intent words are filtered by the
+  `GATE_STOPS` set + 3-char minimum
+  (`compose/strategies/monolithic/generate-instant.js`). Check whether the key
+  word is a stop word before touching thresholds.
+- **`npm run smoke:chunks` re-harvests chunks as a side effect**, touching
+  `corpus/chunks/*.json` mtimes. After smokes, stage only files you actually
+  changed — never a blanket `git add -A`.
+- **The chunk-synthesizer fast-path threshold is 8** on the blended
+  keyword+cosine score. Below it, synthesis fires. Tune in
+  `chunk-synthesizer.js` (`STRONG_RETRIEVAL_SCORE`), not by inflating
+  `keywordScore()` weights in `chunk-library.js`.
+- **`state_id` is opaque to callers** — engine-generated on compose. Never
+  construct or parse it; refinements pass back the prior `state_id` so the
+  cache chains via `parent_state_id`.
+- **After any `@bp` / layout-attribute change to `data-chunk`-annotated HTML,
+  run `npm run harvest:chunks` in the same session** — otherwise training
+  chunks silently hold stale values.
+- **The corpus's inline `style=` is almost entirely structural page-frame
+  layout** (no primitive exists for it) — don't propose a mass
+  "convert to primitives" campaign; it's a known, accepted shape.
+- **Harvest roots are a hard-coded list** in `scripts/build/harvest-chunks.mjs`.
+  A directory rename that adds new siblings silently drops chunks while the
+  harvest "runs clean" (a rename once dropped 26 chunks for ~24h). After any
+  root-level rename: check the roots list AND diff chunk counts against the
+  previous `_index.json` tally.
+- **Subagent-authored demo pages misuse component APIs** (nested content
+  instead of label/description attrs, native `<table>` inside `table-ui`
+  causing a "No data" overlay). Visual QA every subagent-authored page before
+  harvesting it into the corpus.
+
+## Transpile-pass parser lessons (HTML → A2UI)
+
+The transpile pass (`compose/transpiler/`) inherited these hard-won rules —
+preserve them in any rewrite:
+
+1. **Regex `([\s\S]*?)` can't handle nested same-name tags** — depth-tracking
+   tag counting is required (`<card-ui><card-ui>…` matches the inner close).
+2. **Only DIRECT children belong in `comp.children`** — not the flattened
+   subtree; identify direct children as components not claimed by any other
+   component.
+3. **Re-ID by array index, not original ID** — multiple components can share
+   an original ID; index-mapping guarantees uniqueness.
+4. **Subtree walks need a visited set** — shared children reached via multiple
+   parents otherwise duplicate.
+5. **Boolean-attribute trap**: `text=""` parses as boolean `true`; any code
+   doing `c.text.toLowerCase()` needs a `typeof c.text === 'string'` guard.
+
+## Improving search quality without new infrastructure
+
+Three interventions compose multiplicatively; apply in order:
+
+1. **Enrich metadata** — derive descriptions from structural signals
+   (Input("Email") + Input("Password") + Button("Sign In") → "Login form with
+   email, password fields"). Historically 40% → 95% meaningful descriptions.
+2. **Trace which search path each mode actually invokes** — semantic search
+   has been built-but-unwired before; one-line wiring changes beat new infra.
+3. **Expand synonym/keyword surfaces** — bridge user vocabulary to chunk
+   vocabulary ("inbox" → notification) via `data-chunk-keywords`, remembering
+   name-token hits outrank keyword hits.

package/skills/adia-a2ui/references/eval-diagnostics.md

@@ -0,0 +1,86 @@
+# Eval diagnostics — gap diagnosis + regression triage
+
+**Diagnostics run before code changes — always.** The #1 anti-pattern is
+"tweak and hope": changing a prompt or adding a chunk without knowing why the
+score is low burns real-LLM eval runs and teaches nothing.
+
+## Phase 0 — author a stub-mode diagnostic (zero LLM cost)
+
+For each failing intent, capture four signals:
+
+1. **Search ranking** — what `searchChunks()` returns for the intent query.
+2. **Composition output** — what the pipeline emitted (HTML or plan).
+3. **Tag inventory** — every custom-element-like tag in the emitted HTML.
+4. **Coverage delta** — expected_components vs found_components.
+
+Template (runnable with `llmAdapter: null`):
+
+```js
+async function diagnose(intent) {
+  const search = searchChunks(intent.intent, { limit: 10 });
+  const comp = await composeFromIntent({ intent: intent.intent, llmAdapter: null });
+  const tags = [...comp.html.matchAll(/<([a-z]+-[a-z-]+)[\s>]/gi)]
+    .map(m => m[1]).filter((v, i, a) => a.indexOf(v) === i);
+  const found = intent.expected_components.filter(tag =>
+    new RegExp(`<${kebab(tag)}-ui[\\s>]`).test(comp.html));
+  return { search, tags, found,
+    missing: intent.expected_components.filter(t => !found.includes(t)) };
+}
+```
+
+## Phase 1 — classify failures
+
+| Bucket | Symptom | Root cause | Cost |
+| --- | --- | --- | --- |
+| A. Holdout misalignment | Top-1 retrieved ≠ expected_chunk | Holdout drifted from corpus | minutes |
+| B. Coverage gap | Chunk retrieved but HTML lacks expected tags | Chunk HTML doesn't contain those components | hours (new chunks) |
+| C. Wrong shell | Retrieval OK, LLM picks wrong page shell | Prompt ambiguity / missing domain→shell mapping | hours (prompt tuning) |
+| D. Broken render | HTML emitted but console errors / blank | Missing registrations or bad markup | hours (harvester bug) |
+| E. Measurement bug | Output looks right, score low | Scorer regex/casing/substring bug | minutes |
+| F. Embedding drift | Async top-1 ≠ sync top-1 | Cosine boosts flip rankings non-deterministically | minutes |
+
+**Fix order: A → E → F → C → B → D.** Fix measurement before content (else
+scores can't be trusted); fix determinism before adding content (else evals
+fluctuate).
+
+## Phase 2 — fixes per bucket
+
+- **A. Holdout alignment** — map each intent's `expected_chunk` to the actual
+  top-1; update `packages/a2ui/corpus/evals/holdout-compose-from-chunks.jsonl`.
+- **E. Measurement traps** — PascalCase→kebab (`AgentTrace` → `agent-trace`,
+  not `agenttrace`); substring false positives (`pane` vs `panel`,
+  `textarea-ui` contains `text-ui` — word boundaries); case sensitivity (`/i`).
+- **F. Embedding drift** — prefer sync keyword search for deterministic
+  fast-path tiers; keep async cosine for the synthesis tier only (embeddings
+  are a tie-breaker by design — see zettel-calibration).
+- **C. Wrong shell** — check the `SYSTEM_PROMPT` domain→shell mapping in
+  `chunk-synthesizer.js`; add explicit examples for the failing domain and a
+  negative constraint ("NEVER default to dashboard-admin-page for
+  non-dashboard intents").
+- **B. Coverage gap** — author a block chunk the HTML-first way
+  ([chunk-authoring](chunk-authoring.md)): demo page in a harvest root (e.g.
+  `catalog/ui-patterns/app/<name>/`), `data-chunk` + `data-chunk-kind="block"`
+  markers, real component tags so coverage scoring matches, then
+  `npm run harvest:chunks`.
+- **D. Broken render** — `packages/a2ui/mcp/scripts/render-fidelity.mjs`
+  output (console errors, blank viewport, undefined elements); verify
+  registrations in `packages/web-components/index.js`; check the harvester
+  didn't strip `data-chunk-slot` from page shells.
+
+## Verification
+
+```bash
+npm run eval:compose-from-chunks                       # stub first: fast, free
+npm run eval:compose-from-chunks -- --real-llm --report-file   # then real LLM
+```
+
+Stop only when all intents pass and the average is stable across 3 runs, and
+the SKILL.md floors hold.
+
+## The eval suite's dimensions
+
+`packages/a2ui/mcp/scripts/test-evals.mjs` scores 5 weighted dimensions:
+structural_validity 30% · intent_alignment 25% · component_coverage 20% ·
+card_model_compliance 15% · anti_pattern_count 10%. `--save-baseline`
+(`npm run test:evals:baseline`) stores scores; later runs flag any dimension
+dropping >5 points or aggregate >3 (exit code 2 = regression).

package/skills/adia-a2ui/references/format-extension-decisions.md

@@ -0,0 +1,66 @@
+# Format-extension decisions — when a component's contract can't express something
+
+A component's A2UI JSON contract sometimes can't carry a content shape the
+authored HTML has — a table cell with mixed prose and inline `<code>`, a
+label needing an icon, a slot needing arbitrary nested markup. Read this
+before extending any component's declarative contract to close a gap like
+that; it doesn't cover corpus/chunk decisions (see
+[leverage-rules](leverage-rules.md)) — it's about the component's own
+prop/construct surface.
+
+## The three-tier ladder, in order of preference
+
+1. **Extend an existing declarative registry the component already has** —
+   e.g. `table-ui`'s `components/table/cell-types.js` (`badge`, `progress`,
+   `link`, …). Add a new named type; the component dispatches rendering
+   through the registry it already owns. **Smallest blast radius**: no new
+   A2UI construct, no runtime/validator changes, no registry entry in
+   `packages/a2ui/runtime/registry.js`. **Ceiling**: only covers formats the
+   registry's render contract can express (inline-safe content, not
+   arbitrary nested block markup). Building the new registry entry is a
+   web-components primitive edit — hand off to `adia-author` for the
+   implementation half; this reference only decides the tier.
+2. **New A2UI primitive(s)**, each slot/cell a normal construct subtree (any
+   registered component nestable inside it) — matches how `Column`/`Row`
+   already compose. **Most expressive** — no ceiling on what can nest.
+   **Largest blast radius**: new constructs need transpiler synthesis,
+   runtime rendering support, and validator rules; changes what the
+   containing component MEANS in the A2UI graph model. Reserve for cases
+   tier 1 genuinely can't reach.
+3. **Raw-HTML/markup passthrough**, wired through an existing visual-only
+   escape hatch (e.g. `table-ui[raw]`) registered as an A2UI construct
+   carrying sanitized markup as a string prop. **Fastest to ship** — reuses
+   infrastructure verbatim. **Weakest fit for a generative pipeline**: an
+   LLM composing pages would need to emit raw HTML strings instead of
+   constructs, undermining the JSON-graph value the A2UI format exists for.
+   Acceptable ONLY as a narrowly-scoped escape hatch (e.g. a docs-migration
+   pipeline), never as a pattern taught to the generation engines.
+
+**Default to tier 1.** Climb to tier 2 or 3 only when a concrete case proves
+tier 1's ceiling — don't pre-emptively build the more expressive, more
+invasive tier for a gap tier 1 can still close.
+
+## Worked precedent — TKT-0008 (table-ui rich cells, 2026-07-13)
+
+`table-ui`'s `{columns, data}` contract only carried plain-string cells;
+docs reference tables with inline `<code>` in cells (e.g. `` `variant` `` in
+a props table) fell back to a preserved-HTML `Code` block instead of a
+`Table` component — the table never reached the A2UI graph. All three tiers
+were scoped (rich-cell vocabulary / new `TableRow`/`TableCell` primitives /
+raw-HTML passthrough via the existing `table-ui[raw]` prop); tier 1 was
+ratified and built: a new `markdown` cell type in `cell-types.js`, rendered
+via `core/markdown.js`'s `inline()` (exported for this reuse — the exact
+client-side counterpart to the docs-transpiler's own `convertInline()`).
+Measured result: the targeted failure class (`structural:tables` in the
+strict re-verification sweep) dropped 39→7 pages out of 98 measured; the
+residual 7 carry cells genuinely outside tier 1's reach (block content,
+component tags) and are an open tier-2/3 follow-up
+(`docs/tickets/TKT-0008-table-ui-cannot-express-rich-cells.md`).
+
+## Why this generalizes
+
+The same ladder applies to any AdiaUI primitive with a per-item/per-cell
+render dispatch (table columns, list-item variants, chart series formats,
+…): check for an existing registry FIRST, size the ceiling honestly against
+the concrete case at hand, and only pay the blast-radius cost of a new
+construct or a raw-passthrough when the registry provably can't reach it.

package/skills/adia-a2ui/references/leverage-rules.md

@@ -0,0 +1,52 @@
+# Leverage rules — when a repeated subtree earns its own corpus entry
+
+Historical note first: the zettel **fragment mechanism is retired**
+(`$fragment` refs now render as visible drift placeholders — see
+`compose/strategies/zettel/composer.js`). The leverage discipline below
+outlived the mechanism: it now governs whether a repeated subtree gets split
+into its own `data-chunk` block vs staying inline in its parent chunk, and it
+is the calibration for any future extraction tier.
+
+## The leverage rule
+
+**Do not extract a reusable unit unless it has leverage ≥ 3** — at least 3
+consumers would use it. Two exceptions:
+
+1. **Singleton closing a semantic gap** — a distinct domain primitive (e.g. a
+   keyboard-shortcut row) justifies extraction at leverage 1 because the
+   concept itself needs to be retrievable.
+2. **Intra-composition multi-use** — one composition instantiating the same
+   subtree N ≥ ~10 times justifies extraction; reuse is measured per instance,
+   not per referencing composition. Historical evidence: `calendar-day-cell`
+   used 35× inside one calendar composition lifted corpus reuse 26.4% → 33.5%
+   on its own.
+
+Sub-leverage extraction bloats the corpus, slows retrieval, and adds
+maintenance without improving reuse. Common candidates that DO clear the bar:
+card headers, key-value rows, icon+text rows, labeled progress bars, stat
+tiles, notification rows.
+
+## Keyword preservation (the extraction-drift lesson)
+
+Extraction SHRINKS the parent's keyword surface: before, the parent contained
+the subtree's text; after, it only references the child. Historically,
+extracting a card-header from the login-form pattern dropped its retrieval
+score 28 → 24 because "login / sign in / email password" tokens left with the
+extract; explicitly re-adding those keywords to the parent restored 28.
+
+**Rule: every parent that loses a subtree must be re-enriched with the
+semantic tokens that left.** In today's corpus this means the parent chunk's
+`data-chunk-keywords` (and re-harvest). Without it, retrieval degrades
+silently.
+
+## Threshold discipline after extraction
+
+If a known-good intent starts scoring below a retrieval threshold after a
+corpus split, DO NOT lower the threshold. In order:
+
+1. Verify the parent's keywords were preserved (above).
+2. Check the new entry's name/description doesn't cannibalize the parent's
+   semantic space (retrieval collision — see
+   [semantic-fail-lifting](semantic-fail-lifting.md) Strategy B).
+3. Only then consider threshold work, with
+   [zettel-calibration](zettel-calibration.md) history read first.

package/skills/adia-a2ui/references/mcp-pipeline-ops.md

@@ -0,0 +1,83 @@
+# MCP pipeline operations — generate → validate → render → feedback
+
+Operator workflows against the a2ui MCP server. Tool schemas + wrappers:
+[mcp-tool-reference](mcp-tool-reference.md).
+
+## Full pipeline — one command
+
+```bash
+node scripts/mcp-pipeline.cjs "dashboard with 4 stat cards and a revenue chart"
+```
+
+Pipes `intent → generate_ui → validate_schema → a2ui-to-html →
+check_anti_patterns` and prints the scores. Fastest whole-stack confirmation
+after a change.
+
+## Step-by-step (inspect intermediates)
+
+```bash
+node scripts/mcp-call.cjs generate_ui '{"intent":"dashboard with 4 stat cards","mode":"instant"}'
+node scripts/mcp-call.cjs validate_schema '{"messages":"<paste-messages-json>"}'
+echo '<paste-messages-json>' | node scripts/a2ui-to-html.cjs
+node scripts/mcp-call.cjs check_anti_patterns '{"html":"<paste-rendered-html>"}'
+```
+
+`validate_schema` is fast and deterministic — batch it over
+`packages/a2ui/corpus/chunks/*.json` templates to surface corpus drift without
+re-running the generator.
+
+## Compose from the chunk corpus
+
+When the intent matches a known page-shape (auth flow, dashboard layout, error
+shell), prefer `compose_from_chunks` over `generate_ui`:
+
+```bash
+node scripts/mcp-call.cjs compose_from_chunks '{"intent":"sign-in card with email + password + OAuth"}'
+```
+
+Tier 1 returns a matched chunk's HTML when the retrieval score ≥ 8; otherwise
+the LLM picks a `{page, slot_bindings}` plan from a pre-filtered ~30-entry
+catalog and the chunk composer materializes it, validating slot-name +
+chunk-kind contracts. Returns `{state_id, html, plan, candidates}`.
+
+## Multi-turn refinement (state_id chain)
+
+```bash
+# Turn 1 → returns state_id "abc123"
+node scripts/mcp-call.cjs compose_from_chunks '{"intent":"sign-in card with email + password"}'
+# Turn 2 → updateComponents messages + new state_id
+node scripts/mcp-call.cjs refine_composition '{"state_id":"abc123","intent":"add OAuth row with Google + GitHub"}'
+```
+
+Two-pass synthesis (locator → modifier), validator-driven retry
+(`maxAttempts=2`). Each refinement chains through `parent_state_id`; walk
+history with `get_state`. The state cache is in-memory and bounded — after an
+MCP server restart, re-run `compose_from_chunks` for a fresh `state_id`.
+
+## Reporting issues
+
+When the engine breaks expectations, fire `report_issue` with the most recent
+`state_id` (reporter: `llm` for agent self-fire, `user` for a human request).
+The record lands in the engine-internal telemetry store — scratch data for
+diagnosis. Anything worth durable tracking (a recurring pattern, a fix
+proposal) belongs in a GitHub issue or the PR description of the fixing
+change.
+
+## Validation checks
+
+`validate_schema` runs a weighted checklist (target aggregate ≥ 80). Common
+failures when the corpus drifts: `hasRootComponent` (missing `id: "root"`),
+`cardContentModel` (section without Column wrapper, or heading inside section
+instead of header), `headingHierarchy` (skipped levels), `flatAdjacency`
+(nested components instead of sibling id references). Full list + weights:
+`packages/a2ui/mcp/TOOLS.md`.
+
+## Feedback loop
+
+Score runs with `submit_feedback` keyed on the `executionId` from
+`generate_ui`. The analyzer
+(`packages/a2ui/retrieval/feedback/feedback-analyzer.js`) aggregates
+`corpus/feedback/*.jsonl` into per-intent trends, promotion candidates
+(≥95 score + ≥4 rating across 3+ runs → `npm run feedback:promote`), and the
+gap registry (`packages/a2ui/corpus/gaps/registry.json`).
+`npm run feedback:report` surfaces the current state.

package/skills/adia-a2ui/references/mcp-tool-reference.md

@@ -0,0 +1,59 @@
+# MCP tool reference — the a2ui server's tool surface
+
+**Schema SoT is `packages/a2ui/mcp/TOOLS.md` (30 tools), generated alongside
+`server.js` — read it for input/output shapes; never restate schemas here
+(they drift).** Tools register in `packages/a2ui/mcp/server.js` +
+`packages/a2ui/mcp/tools/{corpus,discovery,feedback,refine,synthesis,
+validation,zettel}.js`. Any tool change updates TOOLS.md in the same commit.
+
+## Stability rule (load-bearing)
+
+Changing an existing tool's input/output contract is a breaking change for
+every external MCP client. The full producer-side rule — dry-run schema diff,
+explicit operator proceed, `@adia-ai/a2ui-mcp` version bump, factory pin
+update, and the consumer-load-bearing subset whose contracts are
+frozen-unless-versioned — lives in
+[../../../references/contracts/a2ui-mcp-surface.md](../../../references/contracts/a2ui-mcp-surface.md).
+Adding tools is additive and safe; removing or renaming is breaking.
+
+## Tool map by job
+
+| Group | Tools | Registered in |
+| --- | --- | --- |
+| Generation | `generate_ui`, `refine_ui` (monolithic repair) | `synthesis.js`, `refine.js` |
+| Chunk synthesis + multi-turn | `compose_from_chunks`, `refine_composition`, `get_state`, `report_issue` | `synthesis.js` |
+| Chunk retrieval | `search_chunks`, `get_chunk`, `lookup_chunk` | `corpus.js` |
+| Catalog inspection | `lookup_component`, `get_component_map`, `get_traits`, `get_wiring_catalog`, `server_status` | `discovery.js` |
+| Composition/zettel inspection | `search_patterns`, `get_fragment`, `get_composition`, `get_graph`, `resolve_composition`, `zettel_stats` | `zettel.js` |
+| Intent + context | `classify_intent`, `assemble_context` | `discovery.js` |
+| Validation + conversion | `validate_schema`, `check_anti_patterns`, `convert_html` | `validation.js` |
+| Feedback + evaluation | `submit_feedback`, `get_quality_metrics`, `get_training_gaps`, `run_eval` | `feedback.js` |
+| Authoring (write path) | `import_pattern` | `zettel.js` |
+
+Selection heuristics:
+
+- **Fresh creation from a known page-shape** → `compose_from_chunks`
+  (retrieval-first); generic/novel intent → `generate_ui`.
+- **Modifying an existing surface** ("change", "add to", "remove") →
+  `refine_composition` with the prior `state_id` — never re-generate.
+- **Catalog literacy** → `lookup_component` / `get_component_map`; the MCP is
+  the live catalog — don't memorize component names.
+- **Trust gate on any LLM-emitted A2UI** → `validate_schema` then
+  `check_anti_patterns` on the rendered HTML.
+
+## Local wrappers (all verified in `scripts/`)
+
+- `scripts/mcp-pipeline.cjs "<intent>"` — full pipeline one-shot with a
+  combined report.
+- `scripts/mcp-call.cjs <tool> '<json-args>'` — single-tool call for stepping
+  through / inspecting intermediates.
+- `scripts/a2ui-to-html.cjs [file|stdin]` — renders A2UI message arrays to
+  HTML between `validate_schema` and `check_anti_patterns`.
+
+## When adding a tool
+
+1. Register in the matching `mcp/tools/<group>.js` file (zod input schema +
+   description that names its trigger phrases and its non-goals).
+2. Update `TOOLS.md` in the same commit (generated with the server build —
+   `npm run build:mcp-server`).
+3. Verify: `npm run mcp:smoke`, then a real-client round-trip.

package/skills/adia-a2ui/references/pipeline-overview.md

@@ -0,0 +1,115 @@
+# Pipeline overview — generator + retrieval + engines (mode: modify pipeline internals)
+
+All paths repo-relative. Specs worth reading before structural changes:
+`.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
+`.claude/docs/specs/genui-multiturn-architecture.md` (state cache, refiner,
+op format), `.claude/docs/specs/genui-chunk-marker.md` (chunk attributes),
+`.claude/docs/conventions/gen-ui-pipeline.md` (harvester wiring + embedding
+lifecycle), `.claude/docs/specs/package-architecture.md` (package relations).
+
+## Key files (verified 2026-07)
+
+### Engine orchestration
+
+| File | Role |
+| --- | --- |
+| `packages/a2ui/compose/core/generator.js` | `generate_ui` orchestrator — instant / pro / thinking / stream modes; multi-turn via `executionId` |
+| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `zettel`, `mcp`, `monolithic-*` |
+| `packages/a2ui/compose/strategies/zettel/` | Zettel + chunk-zettel engines — see [strategy-engines](strategy-engines.md) for the per-file map |
+| `packages/a2ui/compose/strategies/free-form-composer/` | Free-form engine (`index.js`, `system-prompt.js`, `transpile.js`) |
+| `packages/a2ui/compose/strategies/_shared/chunk-loader.js` | Shared chunk loading for engines |
+| `packages/a2ui/compose/shared/validate-and-repair.js` | Shared closed-loop validate→repair, adopted by every LLM-calling engine (thinking/pro fully; free-form validate-only) — see [strategy-engines](strategy-engines.md) §Closed-loop validation |
+| `packages/a2ui/compose/transpiler/transpiler.js` | HTML → A2UI transpile pass (used by harvester + convert_html) |
+
+### Corpus + retrieval
+
+| File | Role |
+| --- | --- |
+| `packages/a2ui/corpus/scripts/chunk-library.js` | Chunk catalog API — `getChunk()`, `searchChunks()` (keyword), `searchChunksAsync()` (keyword + cosine), `listChunksByKind()`, `lookupChunksByPrimary()`. Reads `corpus/chunks/` + `_index.json` |
+| `packages/a2ui/compose/strategies/zettel/composition-library.js` | Composition loader + `searchAll()` scoring (normalizes harvested chunks to composition shape) |
+| `scripts/build/harvest-chunks.mjs` | `[data-chunk]` boundary walker over `site/pages/`, `apps/`, `playgrounds/`, `catalog/` — writes `corpus/chunks/<name>.json` + `_index.json`. Run via `npm run harvest:chunks` |
+| `packages/a2ui/retrieval/intent/intent-categorizer.js` | Free-text intent → UI-category taxonomy |
+| `packages/a2ui/retrieval/feedback/feedback-analyzer.js` | Aggregates JSONL feedback (`corpus/feedback/*.jsonl`); promotion + gap candidates |
+| `packages/a2ui/retrieval/feedback/gap-registry.js` | Persistent gap tracking → `packages/a2ui/corpus/gaps/registry.json` |
+| `packages/a2ui/retrieval/anti-patterns.js` | The `check_anti_patterns` rule source |
+| `packages/a2ui/compose/core/reference.js` | Thin wrappers over retrieval exports (`searchBlocks`, `searchBlocksSemantic`, …) |
+
+### LLM bridge + MCP
+
+| File | Role |
+| --- | --- |
+| `packages/llm/llm-bridge.js` | `createAdapter()` — real LLM or stub fallback |
+| `scripts/load-env.mjs` | Shared .env loader for Node scripts |
+| `packages/a2ui/mcp/server.js` + `mcp/tools/*.js` | MCP stdio server + tool registrations — see [mcp-tool-reference](mcp-tool-reference.md) |
+
+## Critical rules
+
+1. **Relative imports in `packages/llm/*.js`** — never `@llm/` Vite aliases;
+   they don't resolve in Node and break published consumers.
+2. **`load-env.mjs` before any a2ui import in Node** — without it,
+   `createAdapter()` silently returns `StubLLMAdapter` (canned 6-component
+   card). Feedback or diagnosis on stub output is noise.
+3. **Metadata IS the search index.** Descriptions + keywords are what retrieval
+   matches. Enriching descriptions from structure (headings, labels, button
+   text) took meaningful-description rate 40% → 95%. When search degrades,
+   inspect chunk metadata before touching thresholds.
+4. **Instant-mode gate lives in `monolithic/generate-instant.js`** — words ≥3
+   chars pass; `GATE_STOPS` filters boilerplate. Grep the set before concluding
+   "the gate rejects valid intents".
+5. **A2UI describes LAYOUT, not behavior.** Generation emits component trees +
+   props + slot bindings; never JS or per-canvas CSS. Behavior delegates to
+   traits or pre-built apps. "Make the generator emit JS/CSS" is a won't-fix.
+6. **Renderer guards `textContent` against container wipe** —
+   `packages/a2ui/runtime/renderer.js` whitelists pure-text leaves
+   (`TEXT_TAG_OK`); everything else routes through the `text=` attribute so
+   slotted children survive. Preserve this when touching the renderer.
+7. **Registry ↔ catalog parity.** A component in the runtime registry but
+   missing from catalog schemas silently drops from generated compositions —
+   `npm run check:registry-catalog-coherence` guards it; run it after catalog
+   changes.
+8. **Multi-turn emits A2UI `updateComponents` messages, not new compositions.**
+   The chunk-refiner mutates the binding plan via four ops (`rebindSlot` /
+   `appendToSlot` / `removeFromSlot` / `replacePage`); state chains via
+   `parent_state_id`. Spec: `genui-multiturn-architecture.md`.
+9. **Issue telemetry goes through `ctx.issueAccumulator`** (suppressed when
+   `ctx.evalMode` is true so evals stay clean). New engine failure paths plumb
+   the accumulator; never write records to disk directly. Durable issue
+   tracking belongs in GitHub issues / PR descriptions, not the engine store.
+10. **A new LLM-calling engine adopts `validate-and-repair.js` as its final
+    stage** — full schema/catalog/anti-pattern conformance, orthogonal to
+    whatever narrower plan/grounding validation the engine already runs
+    (chunk-zettel's slot bindings, free-form's ingredient grounding). It
+    is NOT automatic: a raw-HTML-wrapper engine (chunk-zettel today, see
+    TKT-0009) gets zero value from it — check the engine's actual output
+    shape is a real component graph before wiring it in.
+11. **Escalation across engine tiers is the dispatcher's call, never the
+    engine's own** — `registry.js`'s adapter wrappers (not
+    `generate-instant.js`/`generate-pro.js` themselves) decide whether a
+    hard-fail escalates to a stronger tier, capped at one hop. See
+    `generateInstantAdapter`'s comment for the worked example.
+12. **`harvest-chunks.mjs` validates every templated chunk at admission
+    time** (validate-only, via the same shared module) — report-only by
+    default; `--strict` refuses to write on any invalid chunk but is NOT
+    the default for `npm run harvest:chunks` (TKT-0010: 27% of the corpus
+    currently fails, mostly a schema-generation gap around `data-*`/`span`
+    attributes, not corpus-content defects — see the ticket before
+    assuming a chunk is actually broken).
+
+## Test + run commands (all verified in root package.json)
+
+```bash
+npm run test:a2ui              # smoke checks, no LLM (22/22, +1 skipped OK)
+npm run test:a2ui:full         # + thinking mode (calls API)
+npm run test:evals             # 5-dimension quality evals (mcp/evals/evals.json); --save-baseline via test:evals:baseline
+npm run generate "login form"  # instant-mode CLI (mcp/scripts/generate.mjs)
+npm run smoke:engines          # all registered engines
+npm run smoke:register-engine  # in-process registration (11/11)
+npm run eval:diff -- --engine zettel        # floors in SKILL.md
+npm run harvest:chunks         # re-harvest corpus (dry: harvest:chunks:dry)
+npm run smoke:chunks           # stub-LLM chunk smoke (re-harvests as side effect!)
+npm run eval:chunk-synthesis   # hold-out intents against real LLM
+npm run build:embeddings:chunks
+npm run smoke:refine && npm run smoke:state-cache && npm run smoke:issues
+npm run eval:refine-synthesis  # multi-turn refinement quality
+npm run feedback:report && npm run feedback:promote
+```