@adia-ai/a2ui-compose 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -10,6 +10,102 @@ generator graph.
 
 ## [Unreleased]
 
+_Nothing yet._
+
+---
+
+## [0.2.1] - 2026-05-02
+
+**Lockstep cut + scope-drift gate at composer time + skeleton harvest + Tier-1 block filter + high-resolution session ticket trace.** All 8 published `@adia-ai/*` packages bump 0.2.0 → 0.2.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.0` → `0.2.1`.
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.2.0` (covers `0.2.1`).
+- `strategies/zettel/chunk-synthesizer.js` and `strategies/zettel/issue-reporter.js` are the surfaces that gained the new behavior below; no other directories under `strategies/` were touched.
+
+### Added — Scope-drift gate at composer time (2026-05-02)
+
+`composeFromIntent` now computes a scope-drift signal after every successful composition: composed-HTML component count vs. the sum of bound chunks' component counts. When `actual / expected > 1.5×` (with a 20-component floor to suppress small-UI noise), the synthesizer emits a warning with the ratio. The MCP layer auto-fires a `scope-drift` issue on detection, which writes both a JSON ticket and a high-resolution Markdown ticket showing the bound-chunk envelope, ratio, and a callout naming the canvas-drift regression class.
+
+- `chunk-synthesizer.js`: `computeScopeDrift(html, boundChunks)`, `SCOPE_DRIFT_RATIO = 1.5`, `SCOPE_DRIFT_MIN_ACTUAL = 20`. Tier-1 (single bound block) and Tier-2 (page chunk + every block resolved into a slot) both instrumented.
+- `issue-reporter.js`: new `'scope-drift'` reason in `AUTO_FIRE_POLICY` (type `bug`, severity `drift`, owner `synthesis`); `scopeDrift` flowed into the trace; ticket renderer extended with envelope + ratio + drift callout.
+
+Closes the loop on the canvas-drift regression class — the §37 fix patched the immediate symptom (84 components for a 4-stat retrieval), this trip-wire makes the class self-detecting.
+
+### Added — Skeleton harvest + Tier-1 block filter (2026-05-02)
+
+Two coordinated changes to the chunk-corpus pipeline that bound the synthesizer's output envelope.
+
+- **Skeleton harvest for nested chunks.** `harvest-chunks.mjs` now collapses each nested `data-chunk` element's inner content to `<!-- nested: <name> -->`, so page/panel chunks become compact skeletons. `dashboard-admin-page` shrank from 26,555c → 1,522c (-94%); `dashboard-overview-panel` from 12,493c → 898c (-93%); xl-bucket chunks (>10K chars) went from 2 → 0.
+- **Tier-1 retrieval `kind: 'block'` filter.** `composeFromIntent` restricts the fast-path retrieval to block-kind chunks; page/panel composition still works via Tier-2 LLM synthesis with slot-binding, where the skeleton is the right input.
+
+End-to-end: "trace documentation UI with stat cards" now produces 4 components (was 84). "kpi dashboard with stat cards" → 13 components. The retrieved chunk's component count is now an upper bound on the Tier-1 fast-path output.
+
+### Added — High-resolution session ticket trace (2026-05-02)
+
+The synthesizer now captures a `retrievalTrace` per attempt: Tier-1 hits with scores + kinds, Tier-2 catalog summary (page/panel/block counts, top-N block candidates), user-prompt char count, system-prompt hash, attempt-by-attempt LLM raw responses, validation results, plan, and HTML preview. The state cache stores it on every entry. `attachTrace('full')` (now the default when `state_id` is provided) returns the full session-replay payload.
+
+`issue-reporter.js` renders this as a sibling Markdown ticket alongside the JSON; sections cover header, description, reproduction, component count, retrieval log table, LLM attempts (raw responses), user prompt, composer plan, generated HTML preview, warnings, ops history, environment. A maintainer can replay any flagged session from the ticket alone.
+
+---
+
+## [0.2.0] - 2026-05-02
+
+**Lockstep cut + boundary cleanup.** All 8 published `@adia-ai/*`
+packages now share one version, governed by
+[`docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../docs/specs/package-architecture.md#15-versioning-policy).
+This release also lands the `engine/` ↔ `engines/` collision fix from
+T3 of the
+[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../.brain/archive/2026-Q2/PLAN-packages-architecture-fixes-2026-05-02.md)
+plan.
+
+### Changed
+
+- `version`: `0.1.0` → `0.2.0`.
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.0.2` → `^0.2.0`.
+- `dependencies["@adia-ai/a2ui-retrieval"]`: `^0.0.1` → `^0.2.0`.
+- `dependencies["@adia-ai/a2ui-validator"]`: `^0.0.1` → `^0.2.0`.
+
+- **Directory renames — `engine/` → `core/`, `engines/` → `strategies/`**
+  to remove the singular/plural collision that read as a typo. The
+  orchestrator (`generator.js`, `state.js`, `context-store.js`,
+  `artifacts.js`, `pattern-export.js`, `reference.js`, `pipeline/`) now
+  lives at `core/`; the pluggable strategies (`monolithic/`, `zettel/`,
+  `registry.js`) live at `strategies/`. The `transpiler/` directory's
+  internal imports were also rewritten by the same sweep (no behavior
+  change). All internal imports updated in one sweep.
+- **`constitution.md` moved out of the package source** to
+  [`docs/specs/compose-constitution.md`](../../../docs/specs/compose-constitution.md)
+  so it doesn't ship in the published tarball. Pointer added in
+  README.
+- **`package.json` `exports` map updated** with new keys (`./core`,
+  `./strategies/registry`, `./strategies/zettel`); old keys
+  (`./engine`, `./engines/registry`, `./engines/zettel`) retained as
+  aliases for one release cycle and removed in the next major.
+- Spec [`docs/specs/package-architecture.md`](../../../docs/specs/package-architecture.md)
+  bumped 0.5.0 → 0.6.0 with the directory tree updated to reflect the
+  new layout; new § 15 documents the lockstep versioning policy.
+
+### Migration
+
+Consumers importing from the old paths still work for one release
+cycle, but should update on next touch:
+
+```diff
+- import { generateUI } from '@adia-ai/a2ui-compose/engine';
++ import { generateUI } from '@adia-ai/a2ui-compose/core';
+
+- import { pick, registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
++ import { pick, registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
+
+- import { generateZettel } from '@adia-ai/a2ui-compose/engines/zettel';
++ import { generateZettel } from '@adia-ai/a2ui-compose/strategies/zettel';
+```
+
 ---
 
 ## [0.1.0] - 2026-04-28
@@ -85,7 +181,7 @@ thin until Phase B introduces typed component-tree refinements.
 
 ### Out of scope (Phase B / C)
 
-- Persistent state across server restarts (SQLite-backed cache).
+- Persistent state across server restarts (filesystem-JSON-backed cache at `.brain/state-cache/`; mirrors the existing audit-ledger convention; design in plan §2).
 - Branching / version trees.
 - LLM-streamed op emission.
 - Multi-user concurrent refinement (CRDT / OT).

package/README.md

@@ -1,6 +1,8 @@
 # @adia-ai/a2ui-compose
 
-Framework-agnostic UI generation engine. Takes a natural-language intent +
+Framework-agnostic UI generation engine. Constitution doc:
+[`docs/specs/compose-constitution.md`](../../../docs/specs/compose-constitution.md).
+Takes a natural-language intent +
 an A2UI component catalog and produces a tree of A2UI protocol messages
 ready for a renderer.
 
@@ -24,7 +26,7 @@ intent  ─▶  classify  ─▶  retrieve  ─▶  compose / adapt  ─▶  val
 One entry point, two generation strategies, pluggable LLM back-end.
 
 ```javascript
-import { generateUI } from '@adia-ai/a2ui-compose/engine';
+import { generateUI } from '@adia-ai/a2ui-compose/core';
 
 const result = await generateUI({
   intent: 'login form with email, password, and remember-me',
@@ -41,11 +43,13 @@ const result = await generateUI({
 ## Layout
 
 ```
-gen-ui/
-├── engine/
-│   └── generator.js        generateUI() — the one public entry point
+a2ui-compose/
+├── core/                   orchestrator — state, dispatch, pipeline (formerly engine/)
+│   ├── generator.js        generateUI() — the one public entry point
+│   ├── state.js            ArtifactStore + PipelineEngine singletons
+│   └── pipeline/           6-stage pipeline engine
 │
-├── engines/                pluggable strategies via registerEngine()
+├── strategies/             pluggable engines via registerEngine() (formerly engines/)
 │   ├── registry.js         engine selector + reserved-name guard
 │   ├── monolithic/         pattern-match + LLM-adapt (3 modes)
 │   │   ├── generate-instant.js   no LLM — pattern-match only
@@ -54,7 +58,7 @@ gen-ui/
 │   └── zettel/             fragment-graph composition
 │       ├── generator-adapter.js  entry point
 │       ├── composer.js           assembles fragments → compositions
-│       └── session.js            multi-turn state
+│       └── session-store.js      multi-turn state (Phase A)
 │
 ├── retrieval/
 │   ├── catalog.js          loads component schemas from sibling .a2ui.json
@@ -98,7 +102,7 @@ and assembles them into compositions. Verbatim retrieval above a threshold
 across multi-turn iterations.
 
 ```javascript
-import { registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
+import { registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
 
 registerEngine('my-engine', async (ctx) => {
   // ctx: intent, catalog, patterns, concepts, session, llm, …

package/{engine → core}/generator.js

@@ -14,21 +14,21 @@
 import { validateSchema } from '../../validator/validator.js';
 import { getContext, searchBlocks, searchBlocksSemantic, lookupDomain, listPatterns } from './reference.js';
 import { store, engine } from './state.js';
-import { checkIntentAlignment } from '../../retrieval/intent-alignment.js';
-import { decomposeIntent, composeSubtasks } from '../../retrieval/decomposer.js';
+import { checkIntentAlignment } from '../../retrieval/intent/intent-alignment.js';
+import { decomposeIntent, composeSubtasks } from '../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../retrieval/wiring-catalog.js';
 import { getComponentData } from '../../retrieval/pattern-library.js';
 
 import { StubLLMAdapter } from '../llm/llm-stub.js';
 import { createAdapter } from '../llm/llm-bridge.js';
-import { assessClarity } from '../../retrieval/clarity.js';
-import { isConversational } from '../../retrieval/intent-gate.js';
+import { assessClarity } from '../../retrieval/intent/clarity.js';
+import { isConversational } from '../../retrieval/intent/intent-gate.js';
 import { classifyIntent } from '../../retrieval/domain-router.js';
-import { researchIntent, detectReferences } from '../../retrieval/web-research.js';
-import { feedbackStore } from '../../retrieval/feedback-store.js';
-import { pick as pickEngine, registerMonolithicEngines } from '../engines/registry.js';
-import { analyzePrompt } from '../../retrieval/prompt-analyzer.js';
-import { recordTurn, isRecording } from '../../retrieval/dialog-recorder.js';
+import { researchIntent, detectReferences } from '../../retrieval/authoring/web-research.js';
+import { feedbackStore } from '../../retrieval/feedback/feedback-store.js';
+import { pick as pickEngine, registerMonolithicEngines } from '../strategies/registry.js';
+import { analyzePrompt } from '../../retrieval/intent/prompt-analyzer.js';
+import { recordTurn, isRecording } from '../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,
@@ -38,10 +38,10 @@ import {
   parseA2UIResponse,
   buildRepairPrompt,
   generateSuggestions,
-} from '../engines/monolithic/_shared.js';
-import { generateInstant }  from '../engines/monolithic/generate-instant.js';
-import { generatePro }      from '../engines/monolithic/generate-pro.js';
-import { generateThinking } from '../engines/monolithic/generate-thinking.js';
+} from '../strategies/monolithic/_shared.js';
+import { generateInstant }  from '../strategies/monolithic/generate-instant.js';
+import { generatePro }      from '../strategies/monolithic/generate-pro.js';
+import { generateThinking } from '../strategies/monolithic/generate-thinking.js';
 
 
 /**

package/{engine → core}/state.js

@@ -1,8 +1,8 @@
 /**
  * Shared module-level singletons for the monolithic engine.
  *
- * These were previously private to engine/generator.js. Extracted so that
- * engines/monolithic/generate-{instant,pro,thinking}.js can share the same
+ * These were previously private to core/generator.js. Extracted so that
+ * strategies/monolithic/generate-{instant,pro,thinking}.js can share the same
  * artifact store and pipeline engine without going through the dispatcher.
  *
  * Same instances, imported by reference — do NOT re-instantiate per-call.

package/index.js

@@ -5,12 +5,12 @@
  * via subpaths:
  *
  *   import { generateUI }      from '@adia-ai/a2ui-compose';
- *   import { pick, registerEngine } from '@adia-ai/a2ui-compose/engines/registry';
- *   import { generateZettel }  from '@adia-ai/a2ui-compose/engines/zettel';
+ *   import { pick, registerEngine } from '@adia-ai/a2ui-compose/strategies/registry';
+ *   import { generateZettel }  from '@adia-ai/a2ui-compose/strategies/zettel';
  *   import { llmBridge }       from '@adia-ai/a2ui-compose/llm';
  *
  * See README for the full public surface.
  */
 
-export { generateUI, generateUIStream } from './engine/generator.js';
-export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './engines/registry.js';
+export { generateUI, generateUIStream } from './core/generator.js';
+export { pick, listEngines, registerEngine, unregisterEngine, ENGINES } from './strategies/registry.js';

package/package.json

@@ -1,21 +1,24 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {
-    ".":                    "./index.js",
-    "./engine":             "./engine/generator.js",
-    "./engines/zettel":     "./engines/zettel/generator-adapter.js",
-    "./engines/registry":   "./engines/registry.js",
-    "./llm":                "./llm/llm-bridge.js",
-    "./llm/*":              "./llm/*.js",
-    "./transpiler":         "./transpiler/transpiler.js",
-    "./evals":              "./evals/harness.mjs"
+    ".":                       "./index.js",
+    "./core":                  "./core/generator.js",
+    "./strategies/zettel":     "./strategies/zettel/generator-adapter.js",
+    "./strategies/registry":   "./strategies/registry.js",
+    "./llm":                   "./llm/llm-bridge.js",
+    "./llm/*":                 "./llm/*.js",
+    "./transpiler":            "./transpiler/transpiler.js",
+    "./evals":                 "./evals/harness.mjs",
+    "./engine":                "./core/generator.js",
+    "./engines/zettel":        "./strategies/zettel/generator-adapter.js",
+    "./engines/registry":      "./strategies/registry.js"
   },
   "files": [
-    "engine/",
-    "engines/",
+    "core/",
+    "strategies/",
     "llm/",
     "evals/",
     "transpiler/",
@@ -34,8 +37,8 @@
     "directory": "packages/a2ui/compose"
   },
   "dependencies": {
-    "@adia-ai/a2ui-utils": "^0.0.2",
-    "@adia-ai/a2ui-retrieval": "^0.0.1",
-    "@adia-ai/a2ui-validator": "^0.0.1"
+    "@adia-ai/a2ui-utils": "^0.2.0",
+    "@adia-ai/a2ui-retrieval": "^0.2.0",
+    "@adia-ai/a2ui-validator": "^0.2.0"
   }
 }

package/{engines → strategies}/monolithic/_shared.js

@@ -1,16 +1,16 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, shared helpers.
  *
- * Pure helpers extracted from engine/generator.js per spec §11 Phase 2:
+ * Pure helpers extracted from core/generator.js per spec §11 Phase 2:
  * prompt builders, JSON parsers, canvas diff utilities, suggestion
  * generators. All stateless (the only module-level state is the lazy
  * component-catalog cache inside getComponentCatalog).
  */
 
-import { listPatterns } from '../../engine/reference.js';
-import { store } from '../../engine/state.js';
-import { checkIntentAlignment } from '../../../retrieval/intent-alignment.js';
-import { composeSubtasks } from '../../../retrieval/decomposer.js';
+import { listPatterns } from '../../core/reference.js';
+import { store } from '../../core/state.js';
+import { checkIntentAlignment } from '../../../retrieval/intent/intent-alignment.js';
+import { composeSubtasks } from '../../../retrieval/intent/decomposer.js';
 import { getWiringCatalog } from '../../../retrieval/wiring-catalog.js';
 import { getComponentData } from '../../../retrieval/pattern-library.js';
 
@@ -412,10 +412,10 @@ STATE LAYER:
   Controllers: ${wc.controllers.map(c => c.type).join(', ')} (extensible via registerController)
   "bind" maps controller state ↔ model paths for two-way sync.
 
-ACTIONS LAYER — AdiaEvent → handler chains:
-  Each action binds a AdiaEvent to a handler. The event is a typed object, not a string.
+ACTIONS LAYER — UIEvent → handler chains:
+  Each action binds a UIEvent to a handler. The event is a typed object, not a string.
 
-  AdiaEvent types: ${wc.adiaEvents.map(e => e.event).join(', ')}
+  UIEvent types: ${wc.adiaEvents.map(e => e.event).join(', ')}
   Each carries a typed payload:
 ${wc.adiaEvents.filter(e => e.payload).map(e => `    ${e.event} → ${e.payload}`).join('\n')}
 
@@ -434,7 +434,7 @@ ${wc.adiaEvents.filter(e => e.payload).map(e => `    ${e.event} → ${e.payload}
     }
   ]
 
-  AdiaEvent shape: { "event": "<type>", "target": "<componentId>", "debounce"?: ms, "throttle"?: ms, "condition"?: { "path", "equals"|"notEquals"|"exists" } }
+  UIEvent shape: { "event": "<type>", "target": "<componentId>", "debounce"?: ms, "throttle"?: ms, "condition"?: { "path", "equals"|"notEquals"|"exists" } }
   "target" scopes to a component id. Omit for surface-level events (mount, unmount).
   "onSuccess" / "onError" are follow-up action arrays — NOT separate entries.
   Handlers: ${wc.handlers.map(h => h.name).join(', ')} (extensible via registerHandler)

package/{engines → strategies}/monolithic/generate-instant.js

@@ -1,17 +1,17 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, instant mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
-import { getContext, searchBlocks, lookupDomain } from '../../engine/reference.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocks, lookupDomain } from '../../core/reference.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   generateSuggestions,
 } from './_shared.js';

package/{engines → strategies}/monolithic/generate-pro.js

@@ -1,19 +1,19 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, pro mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
-import { getContext, searchBlocks, lookupDomain } from '../../engine/reference.js';
-import { decomposeIntent } from '../../../retrieval/decomposer.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { isConversational } from '../../../retrieval/intent-gate.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocks, lookupDomain } from '../../core/reference.js';
+import { decomposeIntent } from '../../../retrieval/intent/decomposer.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { isConversational } from '../../../retrieval/intent/intent-gate.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,

package/{engines → strategies}/monolithic/generate-thinking.js

@@ -1,18 +1,18 @@
 /**
  * @adia-ai/a2ui-compose — monolithic engine, thinking mode.
  *
- * Extracted from engine/generator.js per spec §11 Phase 2. Shares state
- * (ArtifactStore, PipelineEngine) via engine/state.js. Pure helpers live
- * in engines/monolithic/_shared.js.
+ * Extracted from core/generator.js per spec §11 Phase 2. Shares state
+ * (ArtifactStore, PipelineEngine) via core/state.js. Pure helpers live
+ * in strategies/monolithic/_shared.js.
  */
 
 import { validateSchema } from '../../../validator/validator.js';
 import { validateMessages as validateCatalog } from '../../../validator/catalog-validator.js';
-import { getContext, searchBlocksSemantic, lookupDomain } from '../../engine/reference.js';
-import { assessClarity } from '../../../retrieval/clarity.js';
-import { feedbackStore } from '../../../retrieval/feedback-store.js';
-import { store, engine } from '../../engine/state.js';
-import { isRecording } from '../../../retrieval/dialog-recorder.js';
+import { getContext, searchBlocksSemantic, lookupDomain } from '../../core/reference.js';
+import { assessClarity } from '../../../retrieval/intent/clarity.js';
+import { feedbackStore } from '../../../retrieval/feedback/feedback-store.js';
+import { store, engine } from '../../core/state.js';
+import { isRecording } from '../../../retrieval/feedback/dialog-recorder.js';
 import {
   buildSystemPrompt,
   buildChatMessages,

package/{engines → strategies}/registry.js

@@ -7,7 +7,7 @@
  *   - zettel      → fragment-graph composition (single mode: instant)
  *
  * The registry deliberately does NOT own intent-gating, clarity assessment, or
- * execution lifecycle — the public `generateUI()` in engine/generator.js does
+ * execution lifecycle — the public `generateUI()` in core/generator.js does
  * that, then delegates the actual work through `pick()`.
  *
  * Shape invariant: every engine function returns
@@ -15,8 +15,8 @@
  */
 
 // Zettel is lazy-loaded — it transitively imports node:fs / node:path / node:url
-// (engines/zettel/fragment-library.js), which Vite externalizes in the browser.
-// Static-importing it here would break browser loads of engine/generator.js.
+// (strategies/zettel/fragment-library.js), which Vite externalizes in the browser.
+// Static-importing it here would break browser loads of core/generator.js.
 // In-browser callers reach zettel via POST /api/generate (server-side), never
 // through this registry, so lazy-loading is safe and incurs only a one-time
 // import on first server-side invocation.
@@ -33,15 +33,15 @@ async function getGenerateZettel() {
 let _isRecording = null;
 async function getIsRecording() {
   if (!_isRecording) {
-    const mod = await import('../../retrieval/dialog-recorder.js');
+    const mod = await import('../../retrieval/feedback/dialog-recorder.js');
     _isRecording = mod.isRecording;
   }
   return _isRecording;
 }
 
-// The three monolithic paths live inside engine/generator.js as internal
+// The three monolithic paths live inside core/generator.js as internal
 // functions. They're injected at boot via `registerMonolithicEngines()` to
-// avoid a circular import (engine/generator.js owns the registry caller).
+// avoid a circular import (core/generator.js owns the registry caller).
 let _monolithicInstant = null;
 let _monolithicPro = null;
 let _monolithicThinking = null;

package/{engines → strategies}/zettel/chunk-synthesizer.js

@@ -31,6 +31,12 @@ import { composeFromPlan, validatePlan } from './chunk-composer.js';
 const STRONG_RETRIEVAL_SCORE = 8;     // search-score threshold for fast path
 const PRE_SEARCH_LIMIT = 30;           // chunks shown to the LLM in the prompt
 const DEFAULT_MAX_ATTEMPTS = 2;
+// Scope-drift gate: composed HTML's component count vs. the sum of bound
+// chunks' component counts. A multiplier > SCOPE_DRIFT_RATIO trips a warning
+// + auto-fires a `scope-drift` issue. Floor prevents false positives on
+// small UIs where slot-wrapper noise dominates.
+const SCOPE_DRIFT_RATIO = 1.5;
+const SCOPE_DRIFT_MIN_ACTUAL = 20;
 
 const SYSTEM_PROMPT = `You compose web-app pages by binding training chunks into named slots.
 
@@ -141,17 +147,30 @@ function extractJSON(raw) {
 export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFAULT_MAX_ATTEMPTS }) {
   // Tier 1 — retrieval. Try semantic-blended hit first; fall back to keyword
   // when embeddings are unavailable (no chunk-embeddings.json or no API key).
-  const hits = await searchChunksAsync(intent, { limit: 5 });
+  //
+  // Restricted to kind=block: page/panel chunks are SKELETONS that need
+  // slot-binding composition (Tier 2 handles them). Returning a skeleton
+  // directly from Tier-1 would emit a near-empty page; we only want the
+  // fast-path for atomic block patterns.
+  const hits = await searchChunksAsync(intent, { kind: 'block', limit: 5 });
   if (hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE) {
     const top = getChunk(hits[0].name);
     const html = top.html || top.instances?.[0]?.html || '';
+    // Tier-1 fast path: sole bound chunk is the retrieved block. The gate
+    // is mostly a no-op here (ratio ≈ 1) but stays for symmetry — and to
+    // catch a corner case where retrieval returns a block that, post-render,
+    // expands far beyond its source (shouldn't happen, but worth detecting).
+    const scopeDrift = computeScopeDrift(html, [top]);
     return {
       html,
       plan: null,
       source: 'retrieval',
       score: hits[0].score,
       cosineScore: hits[0].cosineScore,
-      warnings: [],
+      warnings: scopeDrift.drift
+        ? [`scope drift: ${scopeDrift.actual} components in HTML vs ${scopeDrift.expected} in bound chunk (ratio ${scopeDrift.ratio.toFixed(2)}×)`]
+        : [],
+      scopeDrift,
     };
   }
 
@@ -189,6 +208,29 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
   let lastError = null;
   const attempts = [];
 
+  // Trace: snapshot of the retrieval log for the issue-reporter to surface
+  // verbatim on bug tickets. Recorded once before the retry loop so it
+  // describes what the LLM actually saw.
+  const retrievalTrace = {
+    tier1Hits: hits.slice(0, 5).map((h) => ({
+      name: h.name,
+      score: Number(h.score.toFixed(3)),
+      kind: h.kind,
+      cosineScore: h.cosineScore != null ? Number(h.cosineScore.toFixed(3)) : null,
+    })),
+    tier1Threshold: STRONG_RETRIEVAL_SCORE,
+    tier1Pass: hits.length > 0 && hits[0].score >= STRONG_RETRIEVAL_SCORE,
+    catalogSize: filtered.length,
+    catalogPageNames: pageChunks.map((c) => c.name),
+    catalogPanelNames: panelChunks.map((c) => c.name),
+    catalogBlockTopN: blockHits.slice(0, 10).map((h) => ({
+      name: h.name,
+      score: Number(h.score.toFixed(3)),
+    })),
+    userPromptChars: userPrompt.length,
+    systemPromptChars: SYSTEM_PROMPT.length,
+  };
+
   for (let i = 0; i < maxAttempts; i++) {
     const retryNudge = lastError
       ? `\n\nPREVIOUS ATTEMPT FAILED: ${lastError}. Return ONLY a JSON object shaped as { "page": "...", "slot_bindings": { ... } }. No prose, no questions.`
@@ -216,12 +258,33 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
       continue;
     }
 
+    // Compute scope-drift signal: composed envelope vs sum of bound chunks.
+    // Bound chunks = page chunk + every block/panel resolved into a slot.
+    const boundNames = new Set([plan.page]);
+    for (const v of Object.values(plan.slot_bindings || {})) {
+      const arr = Array.isArray(v) ? v : [v];
+      for (const n of arr) boundNames.add(n);
+    }
+    const boundChunks = [...boundNames].map((n) => getChunk(n)).filter(Boolean);
+    const scopeDrift = computeScopeDrift(composed.html, boundChunks);
+    const driftWarnings = scopeDrift.drift
+      ? [`scope drift: ${scopeDrift.actual} components in composed HTML vs ${scopeDrift.expected} in bound chunks (ratio ${scopeDrift.ratio.toFixed(2)}× exceeds gate ${SCOPE_DRIFT_RATIO}×)`]
+      : [];
+
     return {
       html: composed.html,
       plan,
       source: 'synthesis',
-      warnings: composed.warnings,
-      synthesis: { attempts: i + 1, attemptsLog: attempts, validation },
+      warnings: [...composed.warnings, ...driftWarnings],
+      scopeDrift,
+      synthesis: {
+        attempts: i + 1,
+        attemptsLog: attempts,
+        validation,
+        retrievalTrace,
+        userPrompt,
+        systemPromptHash: hashString(SYSTEM_PROMPT),
+      },
     };
   }
 
@@ -230,6 +293,59 @@ export async function composeFromIntent({ intent, llmAdapter, maxAttempts = DEFA
     plan: null,
     source: 'synthesis',
     warnings: [`synthesis failed after ${maxAttempts} attempts: ${lastError}`],
-    synthesis: { attempts: maxAttempts, attemptsLog: attempts },
+    synthesis: {
+      attempts: maxAttempts,
+      attemptsLog: attempts,
+      retrievalTrace,
+      userPrompt,
+      systemPromptHash: hashString(SYSTEM_PROMPT),
+    },
   };
 }
+
+// Cheap non-crypto hash for prompt-version fingerprinting in tickets.
+function hashString(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
+  return 'h' + h.toString(36);
+}
+
+/**
+ * Heuristic component count — number of opening tags in the HTML.
+ * Loose but stable proxy for A2UI envelope size; used by the scope-drift
+ * gate (above) and by issue-reporter's ticket-rendering counter.
+ */
+function countComponents(html) {
+  if (typeof html !== 'string') return 0;
+  return (html.match(/<[a-z][a-z0-9-]*/g) || []).length;
+}
+
+/**
+ * Compute the scope-drift signal for a composed result.
+ *
+ * Inputs: the final HTML string + the chunk records that fed into it
+ * (page chunk for Tier-2; the single block for Tier-1). Sums the bound
+ * chunks' component counts to get an "expected envelope," compares it to
+ * the actual composed count, and reports the ratio.
+ *
+ * Returns { actual, expected, ratio, drift } where `drift` is true when
+ * actual exceeds SCOPE_DRIFT_RATIO × expected AND actual ≥ SCOPE_DRIFT_MIN_ACTUAL.
+ */
+function computeScopeDrift(html, boundChunks) {
+  const actual = countComponents(html);
+  let expected = 0;
+  for (const c of boundChunks) {
+    if (!c) continue;
+    const chunkHtml = c.html || c.instances?.[0]?.html;
+    expected += countComponents(chunkHtml);
+  }
+  // Guard against zero-expected: when bound chunks have no HTML accounted for
+  // (rare; should only happen in malformed corpora), skip the gate rather
+  // than report infinite drift.
+  if (expected === 0) {
+    return { actual, expected, ratio: null, drift: false };
+  }
+  const ratio = actual / expected;
+  const drift = actual >= SCOPE_DRIFT_MIN_ACTUAL && ratio > SCOPE_DRIFT_RATIO;
+  return { actual, expected, ratio, drift };
+}

package/{engines → strategies}/zettel/generate.js

@@ -9,7 +9,7 @@
  *      existing canvas instead of regenerating
  *
  * The actual implementation is generator-adapter.js; this file is the
- * spec-compliant entry point at engines/zettel/generate.js per §11.
+ * spec-compliant entry point at strategies/zettel/generate.js per §11.
  */
 
 export { generateZettel as generate } from './generator-adapter.js';

package/{engines → strategies}/zettel/issue-reporter.js

@@ -75,6 +75,16 @@ export const AUTO_FIRE_POLICY = {
     suggested_owner: 'validator',
     titleFor: () => `refine_composition ops_failed list non-empty after apply`,
   },
+  'scope-drift': {
+    type: 'bug',
+    severity: 'drift',
+    suggested_owner: 'synthesis',
+    titleFor: (ctx) => {
+      const ratio = ctx?.scopeDrift?.ratio != null ? `${ctx.scopeDrift.ratio.toFixed(1)}×` : '';
+      const intent = ctx?.intent ? ` for "${truncate(ctx.intent, 40)}"` : '';
+      return `Scope drift${ratio ? ' ' + ratio : ''}: composed HTML exceeds bound-chunk envelope${intent}`;
+    },
+  },
 };
 
 function truncate(s, n = 60) {
@@ -167,9 +177,20 @@ export async function attachTrace(state_id, depth, cache) {
     };
   }
 
-  // 'full'
+  // 'full' — high-resolution session trace. Includes everything from
+  // summary plus the synthesis breadcrumbs (retrieval log, LLM prompts,
+  // raw responses per attempt, validation, plan, composed HTML preview)
+  // so a human reviewer or future agent can replay the full session.
   return {
     ...baseTrace,
+    intent: entry.intent ?? null,
+    source: entry.source ?? null,
+    score: entry.score ?? null,
+    plan: entry.plan ?? null,
+    synthesis: entry.synthesis ?? null, // retrievalTrace, attemptsLog, prompts
+    htmlPreview: entry.html ? truncateHtmlForTrace(entry.html) : null,
+    componentCount: entry.html ? countComponents(entry.html) : null,
+    scopeDrift: entry.scopeDrift ?? null,
     internal: entry.internal ?? null,
     output: entry.output ?? {
       ops: entry.ops_history || [],
@@ -177,9 +198,27 @@ export async function attachTrace(state_id, depth, cache) {
     },
     warnings: entry.warnings || [],
     duration_ms: entry.duration_ms ?? null,
+    parent_state_id: entry.parent_state_id ?? null,
+    created_at: entry.created_at ?? null,
   };
 }
 
+const HTML_PREVIEW_MAX_BYTES = 8 * 1024;
+
+function truncateHtmlForTrace(html) {
+  if (typeof html !== 'string') return null;
+  if (html.length <= HTML_PREVIEW_MAX_BYTES) return html;
+  return html.slice(0, HTML_PREVIEW_MAX_BYTES) + `\n<!-- ... ${html.length - HTML_PREVIEW_MAX_BYTES} bytes truncated -->`;
+}
+
+function countComponents(html) {
+  if (typeof html !== 'string') return 0;
+  // Count opening tags (excluding void/standalone HTML elements that
+  // don't contribute to A2UI component count). Loose heuristic; signals
+  // scope drift even if it's not a perfect protocol-level count.
+  return (html.match(/<[a-z][a-z0-9-]*/g) || []).length;
+}
+
 /**
  * Write an issue to disk.
  *
@@ -198,7 +237,11 @@ export async function reportIssue(input, ctx = {}) {
     ? ctx.reporter
     : 'user';
 
-  const traceDepth = input.trace ?? (input.state_id ? 'summary' : 'none');
+  // Default to 'full' when a state_id is provided — high-resolution session
+  // tickets are the design intent (the previous 'summary' default produced
+  // tickets too thin to debug from). Caller can opt down to 'summary' or
+  // 'none' explicitly.
+  const traceDepth = input.trace ?? (input.state_id ? 'full' : 'none');
   let trace = null;
   if (input.state_id && traceDepth !== 'none') {
     trace = await attachTrace(input.state_id, traceDepth, ctx.cache);
@@ -237,7 +280,181 @@ export async function reportIssue(input, ctx = {}) {
   const path = join(storageRoot, `${issue_id}.json`);
   await writeFile(path, JSON.stringify(issue, null, 2));
 
-  return { issue_id, path, ack: 'logged' };
+  // Write a sibling Markdown report for human review. The JSON ticket
+  // is the machine-readable source of truth; the .md is the readable
+  // surface a maintainer scans first to triage. Always written when
+  // we have a non-trivial trace (full or summary), so reviewers can
+  // see retrieval log, LLM prompts, attempts, plan, and composed HTML
+  // without reading the raw JSON.
+  let markdown_path = null;
+  if (trace) {
+    markdown_path = join(storageRoot, `${issue_id}.md`);
+    await writeFile(markdown_path, renderTicketMarkdown(issue, trace));
+  }
+
+  return {
+    issue_id,
+    path,                  // .json (machine-readable)
+    markdown_path,         // .md (human-readable; null when trace='none')
+    ack: 'logged',
+    severity: issue.severity,
+    suggested_owner: issue.suggested_owner,
+  };
+}
+
+/**
+ * Render the high-resolution session ticket as Markdown.
+ * Sections (each appears only if relevant data exists):
+ *   1. Header (id, severity, type, title, owner, tags)
+ *   2. Description (body)
+ *   3. Reproduction (intent, state_id, source, score)
+ *   4. Component-count drift (heuristic; flagged when > 50 components)
+ *   5. Retrieval log (Tier 1 hits + Tier 2 catalog summary)
+ *   6. LLM trace (each attempt's raw response)
+ *   7. Composer plan (slot bindings)
+ *   8. HTML preview (first 8KB of generated output)
+ *   9. Warnings + ops history
+ *  10. Environment (mcp/engine/model)
+ */
+function renderTicketMarkdown(issue, trace) {
+  const lines = [];
+  lines.push(`# ${issue.title}`);
+  lines.push('');
+  lines.push(`> **${issue.severity.toUpperCase()}** · ${issue.type} · owner: \`${issue.suggested_owner}\` · ${issue.created_at}`);
+  lines.push('> ');
+  lines.push(`> Issue ID: \`${issue.issue_id}\`${issue.tags?.length ? ' · tags: ' + issue.tags.map((t) => '`' + t + '`').join(' ') : ''}`);
+  lines.push('');
+
+  if (issue.body) {
+    lines.push('## Description');
+    lines.push('');
+    lines.push(issue.body);
+    lines.push('');
+  }
+
+  if (trace.intent || trace.state_id) {
+    lines.push('## Reproduction');
+    lines.push('');
+    if (trace.intent) lines.push(`- **Intent**: \`${trace.intent}\``);
+    if (trace.state_id) lines.push(`- **State ID**: \`${trace.state_id}\``);
+    if (trace.source) lines.push(`- **Source**: ${trace.source}${trace.score != null ? ` (score: ${trace.score.toFixed(3)})` : ''}`);
+    if (trace.parent_state_id) lines.push(`- **Parent state**: \`${trace.parent_state_id}\``);
+    if (trace.duration_ms != null) lines.push(`- **Duration**: ${trace.duration_ms}ms`);
+    lines.push('');
+  }
+
+  if (trace.componentCount != null) {
+    lines.push('## Component count');
+    lines.push('');
+    lines.push(`- **${trace.componentCount}** components in generated HTML`);
+    if (trace.scopeDrift) {
+      const sd = trace.scopeDrift;
+      const flag = sd.drift ? ' ⚠ **scope drift**' : '';
+      const ratio = sd.ratio != null ? `${sd.ratio.toFixed(2)}×` : 'n/a';
+      lines.push(`- Bound-chunk envelope: ${sd.expected} components`);
+      lines.push(`- Ratio (actual / expected): **${ratio}**${flag}`);
+      if (sd.drift) {
+        lines.push('');
+        lines.push(`> The composed HTML's component count exceeds the bound chunks' envelope by more than the drift gate. This is the canvas-drift regression class — the synthesizer materialized markup beyond what the retrieved chunks justify.`);
+      }
+    } else if (trace.componentCount > 50) {
+      lines.push('- ⚠ over-generation candidate (>50 components, no scope-drift signal available)');
+    }
+    lines.push('');
+  }
+
+  if (trace.synthesis?.retrievalTrace) {
+    const r = trace.synthesis.retrievalTrace;
+    lines.push('## Retrieval log');
+    lines.push('');
+    lines.push(`**Tier 1** (semantic-blended, threshold ${r.tier1Threshold}, ${r.tier1Pass ? '✓ pass' : '✗ fall through to Tier 2'})`);
+    lines.push('');
+    lines.push('| rank | score | kind | chunk |');
+    lines.push('|------|------:|------|-------|');
+    r.tier1Hits.forEach((h, i) => lines.push(`| ${i + 1} | ${h.score} | ${h.kind} | \`${h.name}\` |`));
+    lines.push('');
+    if (r.catalogSize) {
+      lines.push(`**Tier 2 catalog**: ${r.catalogSize} chunks (${r.catalogPageNames.length} page · ${r.catalogPanelNames.length} panel · ${r.catalogBlockTopN.length} top-block)`);
+      lines.push('');
+      if (r.catalogBlockTopN.length) {
+        lines.push('Top block candidates:');
+        for (const h of r.catalogBlockTopN) lines.push(`  - ${h.score} \`${h.name}\``);
+        lines.push('');
+      }
+    }
+  }
+
+  if (trace.synthesis?.attemptsLog?.length) {
+    lines.push('## LLM attempts');
+    lines.push('');
+    trace.synthesis.attemptsLog.forEach((att, i) => {
+      lines.push(`### Attempt ${att.attempt ?? i + 1}`);
+      lines.push('');
+      lines.push('```json');
+      lines.push(typeof att.raw === 'string' ? att.raw.slice(0, 2000) : JSON.stringify(att.raw, null, 2).slice(0, 2000));
+      lines.push('```');
+      lines.push('');
+    });
+    if (trace.synthesis.userPrompt) {
+      lines.push('### User prompt sent to LLM');
+      lines.push('');
+      lines.push('```');
+      lines.push(trace.synthesis.userPrompt.slice(0, 3000));
+      if (trace.synthesis.userPrompt.length > 3000) lines.push(`... (${trace.synthesis.userPrompt.length - 3000} more chars)`);
+      lines.push('```');
+      lines.push('');
+      if (trace.synthesis.systemPromptHash) lines.push(`System prompt hash: \`${trace.synthesis.systemPromptHash}\` (matches across attempts)`);
+      lines.push('');
+    }
+  }
+
+  if (trace.plan) {
+    lines.push('## Composer plan');
+    lines.push('');
+    lines.push('```json');
+    lines.push(JSON.stringify(trace.plan, null, 2));
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (trace.htmlPreview) {
+    lines.push('## Generated HTML (preview)');
+    lines.push('');
+    lines.push('```html');
+    lines.push(trace.htmlPreview);
+    lines.push('```');
+    lines.push('');
+  }
+
+  if (trace.warnings?.length) {
+    lines.push('## Warnings');
+    lines.push('');
+    for (const w of trace.warnings) lines.push(`- ${w}`);
+    lines.push('');
+  }
+
+  if (trace.output?.ops?.length) {
+    lines.push('## Ops history (refinement chain)');
+    lines.push('');
+    lines.push(`${trace.output.ops.length} ops applied. ${trace.output.delta_summary ? 'Last delta: ' + trace.output.delta_summary : ''}`);
+    lines.push('');
+  }
+
+  if (issue.environment) {
+    lines.push('## Environment');
+    lines.push('');
+    for (const [k, v] of Object.entries(issue.environment)) lines.push(`- **${k}**: ${v}`);
+    lines.push('');
+  }
+
+  if (issue.related_issue_ids?.length) {
+    lines.push('## Related issues');
+    lines.push('');
+    for (const id of issue.related_issue_ids) lines.push(`- \`${id}\``);
+    lines.push('');
+  }
+
+  return lines.join('\n');
 }
 
 /**

package/{engines → strategies}/zettel/session-store.js

@@ -17,7 +17,7 @@
  * restart. Good enough for a dev server; a persistent store is a later phase.
  */
 
-import { ArtifactStore } from '../../engine/artifacts.js';
+import { ArtifactStore } from '../../core/artifacts.js';
 
 const store = new ArtifactStore();
 

package/transpiler/transpiler.js

@@ -15,7 +15,7 @@ import {
   SKIP_TAGS, extractProps, inferGap,
 } from './transpiler-maps.js';
 import { validateSchema } from '../../validator/validator.js';
-import { getContext } from '../engine/reference.js';
+import { getContext } from '../core/reference.js';
 
 // ═══════════════════════════════════════════════════════════════
 // PUBLIC API

package/engine/constitution.md

@@ -1,78 +0,0 @@
-# AdiaUI Generation Constitution
-
-Rules the generator MUST satisfy. Used by the RLAIF critique-revise stage
-to evaluate and improve generated output. Each rule maps to a validator check.
-
----
-
-## Card Content Model
-
-- Every `Card` MUST have at least one of: `Header`, `Section`, `Footer`.
-- `Section` content MUST be wrapped in a `Column` component, not placed directly.
-- Headings (`h1`-`h6`) belong in `Header`, not `Section`.
-- Action buttons belong in `Footer`, not `Section` or `Header` (unless using `slot="action"`).
-- `Header` supports 4 slots: `slot="icon"` (leading), `slot="heading"` (title), `slot="description"` (subtitle), `slot="action"` (trailing badge/button).
-
-## Typography & Variant System
-
-- Use semantic HTML elements with `variant` attribute: `<h1 variant="title">`, `<h3 variant="section">`, `<p variant="body">`.
-- Never use `data-heading` — use `variant` instead.
-- Text hierarchy: display > title > heading > section > subsection > body > deck > caption > kicker > label.
-- Use `color="subtle"` or `color="muted"` for secondary text, not inline styles.
-
-## Layout Primitives
-
-- `Column` (col-ui): vertical stack. Use numeric `gap` values: `gap="2"`, `gap="4"`, `gap="6"`.
-- `Row` (row-ui): horizontal. Use `gap`, `justify`, `align` attributes.
-- `Grid` (grid-ui): CSS grid. Use `columns="2|3|4"`.
-- Never use named gaps (`gap="sm"`, `gap="md"`, `gap="lg"`) — always numeric.
-- Never use inline `style` attributes for layout.
-- Never use CSS class names.
-
-## Component Types
-
-- Use `Input` for text inputs (not `TextField` or `TextInput`).
-- Use `CheckBox` for checkboxes (not `Checkbox`).
-- Use `Select` for dropdowns (not `ChoicePicker`).
-- Use `Toggle` for switch controls.
-- Use `Button` with `variant="primary"` for main CTA, `variant="outline"` for secondary.
-- Button text via `text` prop, icon via `icon` prop (Phosphor icon name).
-
-## Flat Adjacency Protocol
-
-- Every component has a unique `id`.
-- Root component MUST have `id: "root"`.
-- Children referenced by ID array: `children: ["child-1", "child-2"]`.
-- IDs should be short and descriptive: `"hdr"`, `"email-field"`, `"submit-btn"`.
-- No circular references.
-- No orphaned components (every non-root must be referenced by a parent).
-
-## Anti-Patterns (DO NOT)
-
-1. **No bare divs** — never use `<div>` or HTML-only elements. Use AdiaUI components.
-2. **No flat adjacency violations** — every Text inside Section must be inside a Column wrapper.
-3. **No heading hierarchy skips** — don't jump from h1 to h3.
-4. **No duplicate IDs** — every component must have a unique ID.
-5. **No content directly in Tab** — Tab is a button strip item, not a content container.
-6. **No invented components** — only use types registered in the A2UI registry.
-7. **No slot on containers** — `slot="heading"` goes on the heading element, not on Header.
-8. **No inline styles** — use component props and tokens, not `style="..."`.
-
-## Prose & Content Context
-
-- For marketing/content pages, wrap in `<section prose>` to shift to content-optimized typography.
-- Centered page headers use: `<header align="center" size="lg">` → `<col-ui gap="4">` → kicker/display/deck.
-- Use `nomargin` on typography elements inside cards to prevent double-spacing.
-
-## Icon Names
-
-- Use Phosphor icon names: `arrow-right`, `check-circle`, `warning-circle`, etc.
-- Brand icons need `-logo` suffix: `google-logo`, `github-logo`, `twitter-logo`.
-- Common aliases are resolved automatically: `send`→`paper-plane-right`, `settings`→`gear`, `mail`→`envelope`.
-
-## Accessibility
-
-- Interactive elements must have `aria-label` if no visible text.
-- Icon-only buttons must have `aria-label`.
-- Images must have `alt` text.
-- Form inputs must have `label` prop.