@adia-ai/a2ui-mcp 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -9,6 +9,81 @@ zettel strategies.
 
 ## [Unreleased]
 
+_No pending changes._
+
+## [0.2.0] - 2026-05-02
+
+**Lockstep cut + corpus caret-lock fix.** 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 **fixes a live shipping bug** in 0.1.3: the `dependencies`
+range `"@adia-ai/a2ui-corpus": "^0.0.6"` locked to *exactly* `0.0.6`
+under npm pre-1.0 semver, so every fresh `npm i @adia-ai/a2ui-mcp`
+since the corpus 0.0.7 cut was installing a stale corpus — missing the
+§§22-25 nav consolidation, the new chunks, and the catalog regen. The
+new range `^0.2.0` works correctly. Same class fixed for the other 4
+internal deps in this package.
+
+### Fixed
+
+- **`a2ui-mcp@0.1.3 → corpus@0.0.6` install bug.** The new `^0.2.0`
+  ranges resolve to the actually-current versions instead of the
+  caret-locked old ones. Consumers running `npx adiaui-mcp` from npm
+  now see the post-§§22-25 corpus + the post-rename component catalog.
+
+### Changed
+
+- `version`: `0.1.3` → `0.2.0`.
+- `dependencies["@adia-ai/a2ui-compose"]`: `^0.1.0` → `^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`.
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.0.6` → `^0.2.0`.
+
+### No source changes
+
+`server.js`, tools, scripts, evals, personas — all byte-identical to
+0.1.3. The cut bumps version + the 4 internal dep ranges only.
+Consumers who want the substantive 0.1.3 work (`compose_from_chunks`
+eval runner + 20-intent hold-out set) get it via either 0.1.3 or
+0.2.0 — and 0.2.0 additionally installs the correct corpus version.
+
+## [0.1.3] - 2026-05-02
+
+Additive — `compose_from_chunks` eval runner + hold-out set. No
+BREAKING changes.
+
+### Added
+
+- **`compose_from_chunks` eval runner + hold-out set**. Closes the
+  spec at
+  [`docs/specs/compose-from-chunks-eval.md`](../../../docs/specs/compose-from-chunks-eval.md):
+  - `evals/compose-from-chunks-holdout.jsonl` — 20 intents (10
+    single-turn compose + 10 multi-turn refine) across 9
+    categories (data-display, forms, layout, data, data-viz,
+    agent, overlay, chat, settings, display).
+  - `scripts/eval-compose-from-chunks.mjs` — runner with `--stub`
+    (default; retrieval-only, no API calls) and `--real-llm`
+    (wires Anthropic SDK) modes. Composite scoring (structural
+    30 + coverage 20 + retrieval 20 + render 30, with null-
+    pro-rata redistribution when render is deferred). `--json`
+    + `--report-file` outputs. Threshold 80; exits 1 if avg < 80.
+  - `npm run eval:compose-from-chunks` exposes the runner.
+  - Stub baseline: 9 of 20 intents retrievable directly (avg
+    ~50-70 each); 11 need synthesis (correctly warn without
+    `--real-llm`). Aggregate ~26 / 100 stub. Real-LLM mode is
+    the gating signal for the `chunk-zettel` engine promotion.
+
+  Render-fidelity component is DEFERRED — needs Playwright
+  headless render + console-error capture wiring; current
+  composite drops the render weight pro-rata across
+  structural/coverage/retrieval until that lands.
+
+### Changed
+
+- `package.json` `files:` array now includes `evals/` so the hold-out
+  set ships in the published tarball.
+
 ---
 
 ## [0.1.2] - 2026-05-01

package/evals/compose-from-chunks-holdout.jsonl

@@ -0,0 +1,20 @@
+{"id":"intent-001","kind":"compose","category":"data-display","intent":"kpi grid with 4 stat cards: users, revenue, sessions, churn","expected_components":["Card","Stat","Grid"],"expected_chunk":"kpi-grid-4-card"}
+{"id":"intent-002","kind":"compose","category":"forms","intent":"sign-in form with email + password + 'forgot password' link","expected_components":["Card","Input","Button","Field"],"expected_chunk":"auth-sign-in"}
+{"id":"intent-003","kind":"compose","category":"layout","intent":"settings page with three tabs (general, integrations, billing)","expected_components":["Tabs","Tab","Card","Section"],"expected_chunk":"settings-tabs-3"}
+{"id":"intent-004","kind":"compose","category":"data","intent":"data table of users with role badge + last-active timestamp","expected_components":["Table","Badge"],"expected_chunk":"users-table"}
+{"id":"intent-005","kind":"compose","category":"data-viz","intent":"conversion funnel chart over 6 stages, with drop-off labels","expected_components":["Chart","Card","ChartLegend"],"expected_chunk":"conversion-funnel"}
+{"id":"intent-006","kind":"compose","category":"agent","intent":"agent activity feed with reasoning steps + final artifact","expected_components":["AgentTrace","AgentReasoning","AgentArtifact"],"expected_chunk":"agent-activity-feed"}
+{"id":"intent-007","kind":"compose","category":"layout","intent":"split-pane editor: code on the left, preview on the right","expected_components":["EditorShell","Pane","Code"],"expected_chunk":"editor-split"}
+{"id":"intent-008","kind":"compose","category":"overlay","intent":"command palette modal with grouped results (recent, suggestions)","expected_components":["Command","Modal"],"expected_chunk":"command-grouped"}
+{"id":"intent-009","kind":"compose","category":"forms","intent":"registration step 2 of 5 — profile setup with 4 fields","expected_components":["Card","StepProgress","Field","Input"],"expected_chunk":"reg-step-shell"}
+{"id":"intent-010","kind":"compose","category":"layout","intent":"404 error page with breadcrumb + back-to-home link","expected_components":["Card","Breadcrumb","Button"],"expected_chunk":"error-404"}
+{"id":"intent-011","kind":"refine","category":"data-display","intent":"dashboard for project metrics","refine":"add a date-range filter at the top","expected_components":["Card","Stat","Select"],"expected_chunk":"project-dashboard"}
+{"id":"intent-012","kind":"refine","category":"display","intent":"user profile card","refine":"make the email editable inline","expected_components":["Card","Avatar","Input"],"expected_chunk":"user-profile-card"}
+{"id":"intent-013","kind":"refine","category":"data","intent":"kanban board with 3 columns","refine":"add a count badge to each column header","expected_components":["Card","Badge","Header"],"expected_chunk":"kanban-3col"}
+{"id":"intent-014","kind":"refine","category":"chat","intent":"chat surface with streaming reply","refine":"add a stop button while streaming","expected_components":["ChatShell","Button","ChatInput"],"expected_chunk":"chat-streaming"}
+{"id":"intent-015","kind":"refine","category":"forms","intent":"sign-up form with email + password","refine":"add password strength meter","expected_components":["Card","Input","Progress"],"expected_chunk":"auth-sign-up"}
+{"id":"intent-016","kind":"refine","category":"settings","intent":"settings tab for notifications","refine":"split email + push into separate sections","expected_components":["Card","Section","Switch"],"expected_chunk":"settings-notifications"}
+{"id":"intent-017","kind":"refine","category":"data","intent":"table of orders","refine":"add a bulk-action toolbar above the table","expected_components":["Table","TableToolbar","Button"],"expected_chunk":"orders-table"}
+{"id":"intent-018","kind":"refine","category":"agent","intent":"agent reasoning panel","refine":"collapse intermediate steps by default, expandable","expected_components":["AgentReasoning","Accordion"],"expected_chunk":"agent-reasoning-collapsed"}
+{"id":"intent-019","kind":"refine","category":"overlay","intent":"modal confirming destructive action","refine":"require typing the resource name to confirm","expected_components":["Modal","Input","Button"],"expected_chunk":"destructive-confirm"}
+{"id":"intent-020","kind":"refine","category":"display","intent":"marketing landing hero","refine":"add a secondary 'see demo' CTA","expected_components":["Card","Heading","Button"],"expected_chunk":"marketing-hero"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -10,6 +10,7 @@
     "server.js",
     "tools/",
     "scripts/",
+    "evals/",
     "personas/",
     "README.md",
     "CHANGELOG.md"
@@ -26,10 +27,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@adia-ai/a2ui-compose": "^0.1.0",
-    "@adia-ai/a2ui-retrieval": "^0.0.1",
-    "@adia-ai/a2ui-validator": "^0.0.1",
-    "@adia-ai/a2ui-corpus": "^0.0.6",
+    "@adia-ai/a2ui-compose": "^0.2.0",
+    "@adia-ai/a2ui-retrieval": "^0.2.0",
+    "@adia-ai/a2ui-validator": "^0.2.0",
+    "@adia-ai/a2ui-corpus": "^0.2.0",
     "zod": "^3.24.0"
   }
 }

package/scripts/dogfood-test.mjs

@@ -1,7 +1,7 @@
 /**
  * Dogfood test: Run 20 diverse intents through A2UI instant mode.
  */
-const { generateUI } = await import('../../compose/engine/generator.js');
+const { generateUI } = await import('../../compose/core/generator.js');
 
 const intents = [
   'user registration form with name, email, password',

package/scripts/eval-chunk-synthesis.mjs

@@ -19,7 +19,7 @@
  */
 
 import '../../../../scripts/load-env.mjs';
-import { composeFromIntent } from '../../compose/engines/zettel/chunk-synthesizer.js';
+import { composeFromIntent } from '../../compose/strategies/zettel/chunk-synthesizer.js';
 import { createAdapter } from '../../compose/llm/llm-bridge.js';
 
 // Hold-out intents — chosen to NOT have a 1:1 chunk match (so synthesis path

package/scripts/eval-compose-from-chunks.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * eval-compose-from-chunks.mjs — Hold-out eval for the chunk-aware
+ * synthesizer. Per `docs/specs/compose-from-chunks-eval.md`.
+ *
+ * Reads `packages/a2ui/mcp/evals/compose-from-chunks-holdout.jsonl`,
+ * runs each intent through `composeFromIntent`, and emits a per-intent
+ * + aggregate report.
+ *
+ * Two modes:
+ *   --stub      (default) — retrieval-only path, no LLM calls. Fast;
+ *                produces a baseline that exercises the chunk-corpus +
+ *                retrieval scoring without spending API budget. Use to
+ *                verify the runner shape + the corpus surface.
+ *   --real-llm  — wires the LLM bridge for synthesis-tier composition.
+ *                Costs ~$2 per full eval at Claude Sonnet 4.6 pricing.
+ *                Requires `ANTHROPIC_API_KEY` in env.
+ *
+ * Scoring (composite, 0-100):
+ *   - Structural (30%) — composition emitted (html non-null OR plan
+ *     non-null).
+ *   - Coverage   (20%) — at least one of the intent's
+ *     `expected_components` appears in the emitted markup.
+ *   - Retrieval  (20%) — top-k retrieved chunks include the intent's
+ *     `expected_chunk` (when set). Soft-asserted; absence flags but
+ *     doesn't fail.
+ *   - Render fidelity (30%) — DEFERRED. Real implementation needs
+ *     Playwright headless render + console-error capture; this runner
+ *     emits a placeholder pending the render-fidelity smoke wiring.
+ *     The composite re-distributes its weight pro-rata across the
+ *     three remaining components when render is null.
+ *
+ * Exit:
+ *   0 if avg ≥ 80 (passes the chunk-zettel promotion gate threshold)
+ *   1 if avg < 80
+ *
+ * Usage:
+ *   npm run eval:compose-from-chunks                  # stub mode
+ *   npm run eval:compose-from-chunks -- --real-llm    # real-LLM
+ *   npm run eval:compose-from-chunks -- --limit 5     # first 5 intents
+ *   npm run eval:compose-from-chunks -- --json        # JSON report
+ *   npm run eval:compose-from-chunks -- --report-file # write to docs/reports/
+ */
+
+import '../../../../scripts/load-env.mjs';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { composeFromIntent } from '../../compose/strategies/zettel/chunk-synthesizer.js';
+import { searchChunksAsync } from '../../corpus/scripts/chunk-library.js';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const HOLDOUT = path.join(REPO_ROOT, 'packages/a2ui/mcp/evals/compose-from-chunks-holdout.jsonl');
+const PASS_THRESHOLD = 80;
+
+const args = process.argv.slice(2);
+const FLAG_REAL_LLM = args.includes('--real-llm');
+const FLAG_JSON     = args.includes('--json');
+const FLAG_REPORT   = args.includes('--report-file');
+const limitIdx = args.indexOf('--limit');
+const LIMIT    = limitIdx >= 0 ? parseInt(args[limitIdx + 1], 10) : null;
+
+// ─────────────────────────────────────────────────────────────────
+// Hold-out loader
+// ─────────────────────────────────────────────────────────────────
+
+function loadHoldOut() {
+  const raw = fs.readFileSync(HOLDOUT, 'utf8');
+  const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+  const intents = lines.map((l) => JSON.parse(l));
+  return LIMIT ? intents.slice(0, LIMIT) : intents;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// LLM adapter
+// ─────────────────────────────────────────────────────────────────
+
+async function buildLLMAdapter() {
+  if (!FLAG_REAL_LLM) return null;
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error('--real-llm requires ANTHROPIC_API_KEY in env.');
+    process.exit(2);
+  }
+  const { default: Anthropic } = await import('@anthropic-ai/sdk');
+  const client = new Anthropic({ apiKey });
+  return {
+    async complete({ system, user, model = 'claude-sonnet-4-6', maxTokens = 2048 }) {
+      const resp = await client.messages.create({
+        model,
+        max_tokens: maxTokens,
+        system,
+        messages: [{ role: 'user', content: user }],
+      });
+      const text = resp.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
+      return { text };
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Scoring
+// ─────────────────────────────────────────────────────────────────
+
+function scoreStructural(result) {
+  if (result.html || result.plan) return 100;
+  return 0;
+}
+
+function scoreCoverage(result, expected) {
+  if (!expected || expected.length === 0) return 100;
+  const html = String(result.html || '');
+  let hits = 0;
+  for (const tag of expected) {
+    const lowered = tag.toLowerCase().replace(/^ui/, '');
+    const re = new RegExp(`<${lowered}-ui[\\s>]`, 'i');
+    if (re.test(html)) hits++;
+  }
+  return Math.round((hits / expected.length) * 100);
+}
+
+async function scoreRetrieval(intent, expectedChunk) {
+  if (!expectedChunk) return null;
+  const hits = await searchChunksAsync(intent, { limit: 5 });
+  const found = hits.some((h) => h.name === expectedChunk);
+  return found ? 100 : 0;
+}
+
+function scoreRenderFidelity(_result) {
+  // DEFERRED — Playwright headless render + console-error capture.
+  // See spec § Out-of-band for the follow-up.
+  return null;
+}
+
+function compositeScore({ structural, coverage, retrieval, render }) {
+  const components = [
+    { name: 'structural', value: structural, weight: 30 },
+    { name: 'coverage',   value: coverage,   weight: 20 },
+    { name: 'retrieval',  value: retrieval,  weight: 20 },
+    { name: 'render',     value: render,     weight: 30 },
+  ].filter((c) => c.value !== null);
+
+  const totalWeight = components.reduce((s, c) => s + c.weight, 0);
+  const weighted = components.reduce((s, c) => s + c.value * c.weight, 0);
+  return totalWeight > 0 ? Math.round(weighted / totalWeight) : 0;
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Eval loop
+// ─────────────────────────────────────────────────────────────────
+
+async function evalIntent(intent, llmAdapter) {
+  const t0 = performance.now();
+  const result = await composeFromIntent({
+    intent: intent.intent,
+    llmAdapter,
+    maxAttempts: 2,
+  });
+  const elapsedMs = Math.round(performance.now() - t0);
+
+  const structural = scoreStructural(result);
+  const coverage = scoreCoverage(result, intent.expected_components);
+  const retrieval = await scoreRetrieval(intent.intent, intent.expected_chunk);
+  const render = scoreRenderFidelity(result);
+
+  const score = compositeScore({ structural, coverage, retrieval, render });
+  return {
+    id: intent.id,
+    kind: intent.kind,
+    intent: intent.intent,
+    source: result.source,
+    elapsedMs,
+    structural,
+    coverage,
+    retrieval,
+    render,
+    score,
+    warnings: result.warnings ?? [],
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Reporter
+// ─────────────────────────────────────────────────────────────────
+
+function reportText(results, mode) {
+  const avg = Math.round(results.reduce((s, r) => s + r.score, 0) / results.length);
+  const passing = results.filter((r) => r.score >= PASS_THRESHOLD).length;
+  const out = [];
+  out.push(`# compose_from_chunks eval — ${mode === 'real-llm' ? 'real LLM' : 'stub (retrieval only)'}`);
+  out.push('');
+  out.push(`Aggregate: avg **${avg}**, passing **${passing} / ${results.length}** (threshold ${PASS_THRESHOLD}).`);
+  out.push('');
+  out.push('| ID | Kind | Source | Struct | Cov | Retr | Render | Score | ms |');
+  out.push('|---|---|---|---:|---:|---:|---:|---:|---:|');
+  for (const r of results) {
+    out.push(`| ${r.id} | ${r.kind} | ${r.source ?? '—'} | ${r.structural} | ${r.coverage} | ${r.retrieval ?? '—'} | ${r.render ?? '—'} | **${r.score}** | ${r.elapsedMs} |`);
+  }
+  if (results.some((r) => r.warnings.length > 0)) {
+    out.push('');
+    out.push('## Warnings');
+    for (const r of results) {
+      if (r.warnings.length === 0) continue;
+      out.push(`- **${r.id}**: ${r.warnings.join('; ')}`);
+    }
+  }
+  return out.join('\n');
+}
+
+function reportJSON(results, mode) {
+  const avg = Math.round(results.reduce((s, r) => s + r.score, 0) / results.length);
+  const passing = results.filter((r) => r.score >= PASS_THRESHOLD).length;
+  return JSON.stringify({
+    mode,
+    threshold: PASS_THRESHOLD,
+    avg,
+    passing,
+    total: results.length,
+    results,
+  }, null, 2);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────────
+
+async function main() {
+  const intents = loadHoldOut();
+  const llmAdapter = await buildLLMAdapter();
+  const mode = FLAG_REAL_LLM ? 'real-llm' : 'stub';
+
+  const results = [];
+  for (const intent of intents) {
+    process.stderr.write(`▶ ${intent.id} ${intent.kind.padEnd(7)} ${intent.intent.slice(0, 50)}...\n`);
+    const result = await evalIntent(intent, llmAdapter);
+    results.push(result);
+  }
+
+  const output = FLAG_JSON ? reportJSON(results, mode) : reportText(results, mode);
+
+  if (FLAG_REPORT) {
+    const date = new Date().toISOString().slice(0, 10);
+    const dir = path.join(REPO_ROOT, 'docs/reports');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, `eval-compose-from-chunks-${date}.md`);
+    fs.writeFileSync(file, output + '\n');
+    console.error(`\nReport written to ${path.relative(REPO_ROOT, file)}`);
+  } else {
+    console.log(output);
+  }
+
+  const avg = results.reduce((s, r) => s + r.score, 0) / results.length;
+  process.exit(avg >= PASS_THRESHOLD ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error('eval-compose-from-chunks failed:', err.message);
+  process.exit(2);
+});

package/scripts/eval-diff.mjs

@@ -28,8 +28,8 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { generateUI } from '../../compose/engine/generator.js';
-import { generateZettel } from '../../compose/engines/zettel/generator-adapter.js';
+import { generateUI } from '../../compose/core/generator.js';
+import { generateZettel } from '../../compose/strategies/zettel/generator-adapter.js';
 import { runHarnessV2 } from '../../compose/evals/harness.mjs';
 import { validateSemantics } from '../../validator/semantic/index.js';
 

package/scripts/eval-fix.mjs

@@ -50,7 +50,7 @@ const MAX_ITER = parseInt([...args].find(a => a.startsWith('--max-iter='))?.spli
 
 // ── Load modules ──
 
-const { generateUI } = await import('../../compose/engine/generator.js');
+const { generateUI } = await import('../../compose/core/generator.js');
 const { validateSchema } = await import('../../validator/validator.js');
 const { getPattern, searchPatterns } = await import('../../retrieval/pattern-library.js');
 const { createTicket, formatTicket, formatTicketList } = await import('../../../../.tickets/tickets.js');

package/scripts/eval-refine-synthesis.mjs

@@ -23,10 +23,10 @@ import '../../../../scripts/load-env.mjs';
 import {
   refineFromIntent,
   applyOps,
-} from '../../compose/engines/zettel/chunk-refiner.js';
-import { mintStateId } from '../../compose/engines/zettel/state-cache.js';
-import { createIssueAccumulator } from '../../compose/engines/zettel/issue-reporter.js';
-import { composeFromPlan } from '../../compose/engines/zettel/chunk-composer.js';
+} from '../../compose/strategies/zettel/chunk-refiner.js';
+import { mintStateId } from '../../compose/strategies/zettel/state-cache.js';
+import { createIssueAccumulator } from '../../compose/strategies/zettel/issue-reporter.js';
+import { composeFromPlan } from '../../compose/strategies/zettel/chunk-composer.js';
 import { listChunksByKind, getChunk } from '../../corpus/scripts/chunk-library.js';
 import { createAdapter } from '../../compose/llm/llm-bridge.js';
 

package/scripts/generate.mjs

@@ -34,7 +34,7 @@ const mode = flags.has('--thinking') ? 'thinking' : flags.has('--pro') ? 'pro' :
 const JSON_OUT = flags.has('--json');
 const HTML_OUT = flags.has('--html');
 
-const { generateUI, generateUIStream } = await import('../../compose/engine/generator.js');
+const { generateUI, generateUIStream } = await import('../../compose/core/generator.js');
 
 console.error(`Mode: ${mode} | Intent: "${intent}"`);
 console.error('─'.repeat(50));
@@ -138,7 +138,7 @@ function componentsToHTML(comps) {
     Stat: 'stat-ui', Table: 'table-ui', Chart: 'chart-ui',
     List: 'list-ui', Pagination: 'pagination-ui',
     // Navigation
-    Tabs: 'tabs-ui', Tab: 'tab-ui', Nav: 'nav-n',
+    Tabs: 'tabs-ui', Tab: 'tab-ui', Nav: 'nav-ui',
     Breadcrumb: 'breadcrumb-ui', SegmentedControl: 'segmented-ui', Segment: 'segment-ui',
     // Overlay
     Modal: 'modal-ui', Drawer: 'drawer-ui', Popover: 'popover-ui',
@@ -170,7 +170,7 @@ function componentsToHTML(comps) {
       return `${indent}<${tag}${attrStr} nomargin>${c.textContent || ''}</${tag}>`;
     }
 
-    const tag = TAG_MAP[c.component] || c.component.toLowerCase() + '-n';
+    const tag = TAG_MAP[c.component] || c.component.toLowerCase() + '-ui';
     const skip = new Set(['id', 'component', 'children', 'textContent']);
     const attrs = Object.entries(c)
       .filter(([k]) => !skip.has(k))

package/scripts/multi-turn-test.mjs

@@ -13,7 +13,7 @@
  */
 
 import '../../../../scripts/load-env.mjs';
-import { generateUI } from '../../compose/engine/generator.js';
+import { generateUI } from '../../compose/core/generator.js';
 import { validateSchema } from '../../validator/validator.js';
 
 // ── Test scenarios ──────────────────────────────────────────────────

package/scripts/smoke-engine-registry.mjs

@@ -8,8 +8,8 @@
  *   - shape invariants hold on both paths
  */
 import '../../../../scripts/load-env.mjs';
-import { pick, listEngines, ENGINES } from '../../compose/engines/registry.js';
-import { generateUI } from '../../compose/engine/generator.js';
+import { pick, listEngines, ENGINES } from '../../compose/strategies/registry.js';
+import { generateUI } from '../../compose/core/generator.js';
 
 console.log('[smoke] engines registered:', listEngines().join(', '));
 

package/scripts/smoke-issues.mjs

@@ -8,8 +8,8 @@ import {
   attachTrace,
   createIssueAccumulator,
   AUTO_FIRE_POLICY,
-} from '../../compose/engines/zettel/issue-reporter.js';
-import { StateCache } from '../../compose/engines/zettel/state-cache.js';
+} from '../../compose/strategies/zettel/issue-reporter.js';
+import { StateCache } from '../../compose/strategies/zettel/state-cache.js';
 import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';

package/scripts/smoke-refine.mjs

@@ -7,13 +7,13 @@ import {
   applyOps,
   validateOps,
   opsToA2UI,
-} from '../../compose/engines/zettel/chunk-refiner.js';
+} from '../../compose/strategies/zettel/chunk-refiner.js';
 import {
   StateCache,
   mintStateId,
   mintNextStateId,
-} from '../../compose/engines/zettel/state-cache.js';
-import { createIssueAccumulator } from '../../compose/engines/zettel/issue-reporter.js';
+} from '../../compose/strategies/zettel/state-cache.js';
+import { createIssueAccumulator } from '../../compose/strategies/zettel/issue-reporter.js';
 import {
   getChunk,
   listChunksByKind,

package/scripts/smoke-register-engine.mjs

@@ -1,5 +1,5 @@
 // Smoke test for OD-5 plugin engine registry.
-import { registerEngine, unregisterEngine, pick, listEngines, ENGINES } from '../../compose/engines/registry.js';
+import { registerEngine, unregisterEngine, pick, listEngines, ENGINES } from '../../compose/strategies/registry.js';
 
 let pass = 0, fail = 0;
 const t = (label, ok, detail = '') => {

package/scripts/smoke-state-cache.mjs

@@ -7,7 +7,7 @@ import {
   mintNextStateId,
   getStateCache,
   resetStateCache,
-} from '../../compose/engines/zettel/state-cache.js';
+} from '../../compose/strategies/zettel/state-cache.js';
 
 let pass = 0, fail = 0;
 const t = (label, ok, detail = '') => {

package/scripts/smoke-synthesis.mjs

@@ -1,6 +1,6 @@
 // Direct test of zettel generator with LLM adapter — no HTTP server needed.
 import '../../../../scripts/load-env.mjs';
-import { generateZettel, clearSession, getTurns } from '../../compose/engines/zettel/generator-adapter.js';
+import { generateZettel, clearSession, getTurns } from '../../compose/strategies/zettel/generator-adapter.js';
 
 // Minimal Anthropic adapter inline (mirrors what server.js makes).
 function makeAdapter() {

package/scripts/test-a2ui.mjs

@@ -76,7 +76,7 @@ try {
 
 console.log('\n2. Pattern library');
 
-const { searchBlocks, listPatterns, lookupDomain } = await import('../../compose/engine/reference.js');
+const { searchBlocks, listPatterns, lookupDomain } = await import('../../compose/core/reference.js');
 
 const allPatterns = listPatterns();
 const withTemplates = allPatterns.filter(p => p.template && Array.isArray(p.template));
@@ -176,7 +176,7 @@ for (const intent of passTests) {
 
 console.log('\n4. Instant mode generation');
 
-const { generateUI } = await import('../../compose/engine/generator.js');
+const { generateUI } = await import('../../compose/core/generator.js');
 
 const instantTests = [
   { intent: 'login form', minComponents: 3 },
@@ -270,9 +270,9 @@ try {
 console.log('\n7. Multi-turn refinement (Phase A)');
 
 try {
-  const { StateCache, mintStateId, mintNextStateId } = await import('../../compose/engines/zettel/state-cache.js');
-  const { createIssueAccumulator } = await import('../../compose/engines/zettel/issue-reporter.js');
-  const { refineFromIntent, applyOps, opsToA2UI, validateOps } = await import('../../compose/engines/zettel/chunk-refiner.js');
+  const { StateCache, mintStateId, mintNextStateId } = await import('../../compose/strategies/zettel/state-cache.js');
+  const { createIssueAccumulator } = await import('../../compose/strategies/zettel/issue-reporter.js');
+  const { refineFromIntent, applyOps, opsToA2UI, validateOps } = await import('../../compose/strategies/zettel/chunk-refiner.js');
   const { listChunksByKind } = await import('../../corpus/scripts/chunk-library.js');
 
   // 7a. State cache + state-id chain

package/scripts/test-chunks.mjs

@@ -94,8 +94,8 @@ assert('lookup_chunk(article) finds dashboard-admin-page',
   articleChunks.some((c) => c.name === 'dashboard-admin-page'));
 
 // ── chunk-composer + chunk-synthesizer ──
-import { composeFromPlan, validatePlan } from '../../compose/engines/zettel/chunk-composer.js';
-import { composeFromIntent } from '../../compose/engines/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../../compose/strategies/zettel/chunk-composer.js';
+import { composeFromIntent } from '../../compose/strategies/zettel/chunk-synthesizer.js';
 
 console.log('\n── validatePlan ──');
 

package/scripts/test-evals.mjs

@@ -42,7 +42,7 @@ if (ONLY) evalCases = evalCases.filter(e => String(e.id) === ONLY);
 
 // ── Load generator ──
 
-const { generateUI } = await import('../../compose/engine/generator.js');
+const { generateUI } = await import('../../compose/core/generator.js');
 const { validateSchema } = await import('../../validator/validator.js');
 
 // ── Scoring functions ──

package/scripts/visual-validate.mjs

@@ -22,7 +22,7 @@ const PRO = args.has('--pro');
 const OPEN = args.has('--open');
 const OUTPUT = join(__dirname, '..', 'visual-validation.html');
 
-const { generateUI } = await import('../../compose/engine/generator.js');
+const { generateUI } = await import('../../compose/core/generator.js');
 const { validateSchema } = await import('../../validator/validator.js');
 
 const TEST_INTENTS = [

package/server.js

@@ -26,7 +26,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 
 // ── Import from a2ui ──
-import { generateUI } from '../compose/engine/generator.js';
+import { generateUI } from '../compose/core/generator.js';
 import { validateSchema } from '../validator/validator.js';
 import { validateMessages as validateCatalogMessages } from '../validator/catalog-validator.js';
 import {
@@ -52,11 +52,11 @@ import {
   getAllCompositions as getAllZettelCompositions,
   searchAll as searchZettelAll,
   getGraph as getZettelGraph,
-} from '../compose/engines/zettel/fragment-library.js';
+} from '../compose/strategies/zettel/fragment-library.js';
 import {
   resolveComposition as resolveZettelComposition,
   templateToMessages as zettelTemplateToMessages,
-} from '../compose/engines/zettel/composer.js';
+} from '../compose/strategies/zettel/composer.js';
 // Zettel bootstrap is still needed for get_fragment/resolve_composition tools;
 // the generate_ui tool now dispatches through the unified registry in gen-ui.
 
@@ -312,7 +312,7 @@ server.tool(
 // ── Pattern & Feedback Tools ──
 
 import { registerPattern } from '../retrieval/pattern-library.js';
-import { FeedbackCollector } from '../retrieval/feedback.js';
+import { FeedbackCollector } from '../retrieval/feedback/feedback.js';
 
 const feedbackCollector = new FeedbackCollector();
 
@@ -378,7 +378,7 @@ server.tool(
 
 // ── Quality metrics tool ──
 
-import { feedbackStore } from '../retrieval/feedback-store.js';
+import { feedbackStore } from '../retrieval/feedback/feedback-store.js';
 
 server.tool(
   'get_quality_metrics',
@@ -664,8 +664,8 @@ Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
 // Spec: docs/specs/genui-chunk-marker.md (§ "Harvester contract", future:
 // composition reasoning). Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
 
-import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/zettel/chunk-synthesizer.js';
-import { composeFromPlan, validatePlan } from '../compose/engines/zettel/chunk-composer.js';
+import { composeFromIntent as composeFromChunksImpl } from '../compose/strategies/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../compose/strategies/zettel/chunk-composer.js';
 import { createAdapter as createLLMAdapter } from '../compose/llm/llm-bridge.js';
 
 // ── Multi-turn architecture (Phase A) ────────────────────────────────
@@ -676,18 +676,18 @@ import {
   getStateCache,
   mintStateId,
   mintNextStateId,
-} from '../compose/engines/zettel/state-cache.js';
+} from '../compose/strategies/zettel/state-cache.js';
 import {
   reportIssue as reportIssueImpl,
   autoReport,
   createIssueAccumulator,
-} from '../compose/engines/zettel/issue-reporter.js';
+} from '../compose/strategies/zettel/issue-reporter.js';
 import {
   refineFromIntent,
   applyOps,
   opsToA2UI,
   validateOps,
-} from '../compose/engines/zettel/chunk-refiner.js';
+} from '../compose/strategies/zettel/chunk-refiner.js';
 
 const stateCache = getStateCache();