@adia-ai/a2ui-compose 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -10,6 +10,63 @@ generator graph.
 
 ## [Unreleased]
 
+_No pending changes._
+
+---
+
+## [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`](../../../docs/plans/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 +142,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.0",
   "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/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/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.