@adia-ai/a2ui-mcp 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog — @adia-ai/a2ui-mcp
+
+Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+Scope: MCP transport wrapping `@adia-ai/a2ui-compose`. Exposes
+generation tools over JSON-RPC for Claude Code, Claude Desktop,
+and other MCP hosts. Engine selector supports both monolithic and
+zettel strategies.
+
+## [Unreleased]
+
+### Changed
+- Registry / transpilation scripts at `packages/web-components/scripts/a2ui-to-html.cjs` and `packages/web-components/scripts/mcp-pipeline.cjs` now mirror the canonical `packages/web-components/a2ui/registry.js` for all A2UI component → custom-element mappings. Previously these scripts had several stale mappings that diverged from the runtime registry.
+
+---
+
+## [0.0.1] - 2026-04-24
+
+First public release. MCP server that wraps the compose engine and
+exposes A2UI generation tools over JSON-RPC.
+
+### Included
+
+- **Server** (`server.js`) — MCP stdio server. Registers tools,
+  handles JSON-RPC, routes requests to the compose engine selector.
+- **Tools** (`tools/`) — MCP tool definitions for
+  `generate_ui`, `validate_schema`, `check_anti_patterns`,
+  `search_patterns`, `lookup_component`, `get_composition`,
+  `get_fragment`, `get_graph`, `get_traits`, `get_wiring_catalog`,
+  `zettel_stats`, `run_eval`, `submit_feedback`, plus several more.
+  See `tools/` for the full surface.
+- **Personas** (`personas/`) — per-MCP-host prompts + behavior
+  tweaks.
+- **Scripts** (`scripts/`) — `eval-diff.mjs` (cross-engine regression
+  runner), `generate.mjs` (CLI wrapper), `test-a2ui.mjs` (integration
+  suite), smoke tests, and dogfood/multi-turn harnesses.
+- **Binary** — `adiaui-mcp` CLI registered via `package.json` `bin`
+  so `npx @adia-ai/a2ui-mcp` runs the stdio server directly.
+
+### Dependencies
+
+- `@modelcontextprotocol/sdk` ^1.29 — MCP transport + tool registration.
+- `zod` ^3.24 — tool-parameter schema validation.
+- `@adia-ai/a2ui-compose` ^0.0.1 — generation engine.
+- `@adia-ai/a2ui-retrieval` ^0.0.1 — retrieval layer.
+- `@adia-ai/a2ui-validator` ^0.0.1 — validation layer.
+- `@adia-ai/a2ui-corpus` ^0.0.1 — training corpus (patterns, fragments,
+  compositions, exemplars).
+
+### Verification
+- `npm run smoke:register-engine` — 11/11 passing (engine registration + reserved-name protection + custom-engine hooks).
+- `npm run test:a2ui` — 19 passed, 0 failed, 1 skipped (thinking-mode test is `--thinking` opt-in).
+
+---
+
+## [0.1.0] — internal baseline (unreleased)
+
+Initial version at the time the monorepo was established. Contains:
+
+- MCP server (`server.js`) exposing `generate_ui`, `search_patterns`, `lookup_component`, `resolve_composition`, `validate_schema`, and related tools.
+- Engine plugin API via in-process `registerEngine()` (see `packages/a2ui/compose/engines/registry.js`).
+- Smoke tests (`scripts/smoke-*.mjs`) for engine registration, merged generation, and end-to-end A2UI tests.
+- Eval harnesses (`scripts/test-evals.mjs`, `scripts/test-a2ui.mjs`, `scripts/eval-fix.mjs`) for corpus regression measurement.
+
+Package name still uses the legacy `@adia-ai/a2ui-mcp` scope pending rename (see root CHANGELOG for context).

package/README.md

@@ -0,0 +1,154 @@
+# @adia-ai/a2ui-mcp
+
+MCP server wrapping [`@adia-ai/a2ui-compose`](../compose). Exposes the generation
+engine, component catalog, pattern library, validator, and training
+feedback loop as stdio tools for Claude Desktop, Claude Code, and any
+other MCP-speaking host.
+
+> Runtime only. Generation logic lives in `@adia-ai/a2ui-compose`; UI atoms in
+> [`@adia-ai/web-components`](../web-components); the A2UI protocol runtime
+> (renderer, registry, streams, wiring) in
+> [`@adia-ai/a2ui-utils`](../a2ui/utils); corpus in
+> [`@adia-ai/a2ui-corpus`](../corpus).
+
+## Quick start
+
+```bash
+node packages/a2ui/mcp/server.js
+# or, if linked:
+adiaui-mcp
+```
+
+Register with Claude Code (`.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "adia-ui": {
+      "command": "node",
+      "args": ["packages/a2ui/mcp/server.js"]
+    }
+  }
+}
+```
+
+API keys (at least one required for `generate_ui`):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-…
+export OPENAI_API_KEY=sk-…
+export GEMINI_API_KEY=AIza…
+```
+
+## Tools
+
+The server registers 21 tools. Shape is stable; argument schemas via Zod.
+
+| Tool                   | What it does                                              |
+|------------------------|-----------------------------------------------------------|
+| `generate_ui`          | Intent → A2UI tree. Engine (`monolithic`/`zettel`) + mode. |
+| `validate_schema`      | Run the 15-check validator on an A2UI tree; returns 0-100. |
+| `classify_intent`      | Extract concepts, entities, implied components, steelman.  |
+| `lookup_component`     | Resolve a component name (alias-aware) to its schema.      |
+| `get_component_map`    | Full tag→class map including alias normalizations.         |
+| `search_patterns`      | Keyword-rank the monolithic pattern corpus.                |
+| `assemble_context`     | Build the system prompt context for a given intent.        |
+| `check_anti_patterns`  | Scan a tree for canonical anti-patterns (chart-legend, …). |
+| `get_traits`           | List trait catalog + their host-binding rules.             |
+| `convert_html`         | Raw HTML → best-effort A2UI tree (import path).            |
+| `get_wiring_catalog`   | Declarative wiring-engine recipes.                         |
+| `import_pattern`       | Commit a generated result into the pattern library.        |
+| `submit_feedback`      | Append a user-feedback event to the feedback store.        |
+| `get_quality_metrics`  | Aggregate pass/fail scores over a window.                  |
+| `get_training_gaps`    | Intents that currently miss coverage.                      |
+| `run_eval`             | Run the held-out benchmark; return pass/fail per intent.   |
+| `get_fragment`         | Fetch a single zettel fragment by id.                      |
+| `get_composition`      | Fetch a named multi-fragment composition.                  |
+| `resolve_composition`  | Expand a composition reference into its fragments.         |
+| `get_graph`            | Dump the zettel fragment-dependency graph.                 |
+| `zettel_stats`         | Corpus counts (fragments, compositions, reuse ratio, …).   |
+
+## Layout
+
+```
+gen-ui-mcp/
+├── server.js      MCP bootstrap — registers all 21 tools inline
+├── scripts/       Standalone runners (smoke tests, eval diffs, visual validate)
+│   ├── generate.mjs             CLI: `node scripts/generate.mjs "pricing page"`
+│   ├── eval-diff.mjs            diff held-out run vs baseline
+│   ├── eval-fix.mjs             re-run failing eval intents
+│   ├── dogfood-test.mjs         20-intent dogfood + avg-score gate
+│   ├── multi-turn-test.mjs      session iteration smoke
+│   ├── smoke-engine-registry.mjs   registry + reserved-name checks
+│   ├── smoke-register-engine.mjs   plugin engine registration
+│   ├── smoke-zettel.mjs         zettel-specific smoke (corpus + composer)
+│   ├── smoke-synthesis.mjs      fragment-synthesis path
+│   ├── smoke-merged.mjs         cross-engine merge check
+│   ├── smoke-searchable-select.mjs  known-good composition regression
+│   ├── test-a2ui.mjs            A2UI message validator unit tests
+│   ├── test-evals.mjs           evals harness wrapper
+│   └── visual-validate.mjs      Playwright render + Vision-LLM critique
+├── tools/         (reserved; tool code currently inlined in server.js)
+└── personas/      persona presets (vocabulary + style hints for adapters)
+```
+
+## CLI usage
+
+```bash
+# One-shot generation from a prompt
+node packages/a2ui/mcp/scripts/generate.mjs "pricing page with 3 tiers"
+
+# Run the held-out eval
+node packages/a2ui/mcp/scripts/test-evals.mjs
+
+# Full verification sweep (invoked by /verification-sweep slash command)
+npm run smoke:engines && \
+npm run smoke:register-engine && \
+npm run test:a2ui && \
+npm run eval:diff -- --engine zettel
+```
+
+## How it fits together
+
+```
+  ┌─────────────┐      MCP stdio
+  │ Claude Code │◀─────────────────▶ server.js
+  └─────────────┘                      │
+                                       ├── @adia-ai/a2ui-compose          (engines, validator, LLM bridge)
+                                       ├── @adia-ai/a2ui-corpus (catalog, fragments, feedback)
+                                       └── @adiahealth/web-components  (component schemas via .a2ui.json)
+```
+
+On start, the server:
+
+1. Loads the component catalog (`gen-ui-training/catalog-a2ui_0_9.json`)
+2. Lazy-initializes the zettel corpus on first `generate_ui`/`zettel_*` call
+3. Resolves LLM adapter from env vars
+4. Registers tools + opens stdio transport
+
+## Gotchas
+
+- **Corpus load is noisy.** The zettel composer prints stats to stderr on
+  first invocation. Callers expecting silent MCP should swallow stderr.
+- **API keys must be set before the server starts.** Changing env vars
+  mid-session doesn't hot-reload adapters.
+- **Engine selector is internal.** Don't pass `engine: 'mcp'` — the
+  generator picks `monolithic` vs `zettel` from intent + mode. Reserved
+  names in the registry guard against accidental shadowing.
+- **Validator score < 70 is still returned.** Consumers should gate on
+  the `passed` boolean or raw `score` — the tool doesn't auto-retry.
+
+## Evals + regression floors
+
+The server enforces the same thresholds as the rest of the pipeline:
+
+- `test:a2ui` — 19/19 green (+1 skipped OK)
+- `smoke:register-engine` — 11/11 green
+- `eval:diff -- --engine zettel` — coverage 100%, avgScore ≥ 88
+- Dogfood — 20/20 intents at avg ≥ 95
+
+See repo-root `AGENTS.md` for the full verification sweep.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@adia-ai/a2ui-mcp",
+  "version": "0.0.1",
+  "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
+  "type": "module",
+  "bin": {
+    "adiaui-mcp": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "tools/",
+    "scripts/",
+    "personas/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
+    "directory": "packages/a2ui/mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@adia-ai/a2ui-compose": "^0.0.1",
+    "@adia-ai/a2ui-retrieval": "^0.0.1",
+    "@adia-ai/a2ui-validator": "^0.0.1",
+    "@adia-ai/a2ui-corpus": "^0.0.1",
+    "zod": "^3.24.0"
+  }
+}

package/scripts/dogfood-test.mjs

@@ -0,0 +1,107 @@
+/**
+ * Dogfood test: Run 20 diverse intents through A2UI instant mode.
+ */
+const { generateUI } = await import('../../compose/engine/generator.js');
+
+const intents = [
+  'user registration form with name, email, password',
+  'product listing page with filters and grid',
+  'email inbox with folders and message preview',
+  'restaurant menu with categories and prices',
+  'weather app with forecast and current conditions',
+  'music player with playlist and controls',
+  'image carousel with thumbnails',
+  'file manager with folder tree and preview',
+  'social media profile with posts and followers',
+  'kanban board with tasks and columns',
+  'calendar with events and day view',
+  'shopping cart with items and checkout',
+  'chat application with contacts and messages',
+  'admin dashboard with users table and charts',
+  'blog post editor with preview',
+  'notification center with filters',
+  'project settings with team members',
+  'API documentation with endpoints list',
+  'color theme builder with preview',
+  'onboarding wizard with progress steps',
+];
+
+const results = [];
+
+for (const intent of intents) {
+  try {
+    const r = await generateUI({ intent, mode: 'instant' });
+    const components = r.messages?.[0]?.components || [];
+    const score = r.validation?.score ?? 0;
+    const errors = r.validation?.errors || [];
+    const warnings = r.validation?.warnings || [];
+
+    // Detect pattern match from suggestions and pipeline
+    const adaptedSuggestion = (r.suggestions || []).find(s => s.includes('Adapted from'));
+    const thinkingModeSuggestion = (r.suggestions || []).find(s => s.includes('Use "thinking" mode for LLM-powered'));
+    
+    let matchType = 'direct'; // assume direct pattern match
+    let patternName = null;
+    
+    if (adaptedSuggestion) {
+      matchType = 'partial';
+      const m = adaptedSuggestion.match(/Adapted from "([^"]+)"/);
+      patternName = m ? m[1] : 'unknown';
+    } else if (thinkingModeSuggestion) {
+      matchType = 'fallback';
+      patternName = null;
+    } else {
+      // Direct match - infer from pipeline confidence
+      const planReport = r.pipeline?.reports?.find(s => s.stage === 'plan');
+      const genReport = r.pipeline?.reports?.find(s => s.stage === 'generate');
+      if (planReport?.confidence >= 0.95) {
+        matchType = 'direct';
+      } else if (planReport?.confidence >= 0.5) {
+        matchType = 'partial';
+      }
+    }
+
+    // Component types
+    const compTypes = [...new Set(components.map(c => c.component))];
+
+    // Quality heuristics
+    const hasLayout = compTypes.some(t => ['Card', 'Section', 'Column', 'Row', 'Grid'].includes(t));
+    const hasInteractive = compTypes.some(t => ['Button', 'Input', 'Select', 'CheckBox', 'Toggle', 'Slider', 'TextArea'].includes(t));
+    const hasContent = compTypes.some(t => ['Text', 'Image', 'Avatar', 'Icon', 'Badge'].includes(t));
+    
+    results.push({
+      intent,
+      componentCount: components.length,
+      score,
+      matchType,
+      patternName,
+      compTypes,
+      hasLayout,
+      hasInteractive,
+      hasContent,
+      errors,
+      warnings,
+      suggestions: r.suggestions || [],
+      success: components.length > 0 && score >= 70,
+    });
+  } catch (err) {
+    results.push({
+      intent,
+      componentCount: 0,
+      score: 0,
+      matchType: 'error',
+      patternName: null,
+      compTypes: [],
+      hasLayout: false,
+      hasInteractive: false,
+      hasContent: false,
+      errors: [err.message],
+      warnings: [],
+      suggestions: [],
+      success: false,
+    });
+  }
+}
+
+// Print results as JSON
+console.log(JSON.stringify(results, null, 2));

package/scripts/eval-diff.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * Run one or both engines through the V2 harness and emit side-by-side artifacts.
+ *
+ * Replaces the older `scripts/zettel-eval-diff.mjs`. Lives under a2ui-mcp because
+ * cross-engine evaluation is an MCP-consumer concern (the MCP surface is what
+ * exposes multiple engines; this script is the CLI form of that comparison).
+ *
+ * Output: evals/mcp/runs/<ISO-timestamp>/
+ *   mcp.json      — V2 results for monolithic-pattern engine    (if engine ∈ {mcp, all})
+ *   zettel.json   — V2 results for fragment-graph engine          (if engine ∈ {zettel, all})
+ *   diff.md       — per-intent table + aggregate summary         (always)
+ *
+ * Usage:
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs                  # both engines
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs --engine all     # both engines (explicit)
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs --engine mcp     # monolithic only
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs --engine zettel  # fragment-graph only
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs --limit 20
+ *   node packages/a2ui/mcp/scripts/eval-diff.mjs --domain forms
+ */
+import '../../../../scripts/load-env.mjs';
+
+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 { runHarnessV2 } from '../../compose/evals/harness.mjs';
+import { validateSemantics } from '../../validator/semantic/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..', '..', '..', '..');
+
+// ── Args ──
+const args = process.argv.slice(2);
+const opt = (k) => {
+  const i = args.indexOf(`--${k}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const engine = opt('engine') || 'all';
+const limit = opt('limit') ? Number(opt('limit')) : undefined;
+const domain = opt('domain');
+// Shadow-mode semantic validator (Phase 1). Opt-in; zero effect on gating.
+const semanticEnabled = args.includes('--semantic');
+
+if (!['mcp', 'zettel', 'all'].includes(engine)) {
+  console.error(`[eval-diff] --engine must be one of: mcp | zettel | all  (got: ${engine})`);
+  process.exit(2);
+}
+
+const runMcp = engine === 'mcp' || engine === 'all';
+const runZettel = engine === 'zettel' || engine === 'all';
+
+// ── MCP adapter: use the top-level patternName exposed by generateInstant ──
+// Shadow-mode capture: when --semantic is set, remember the emitted messages
+// per intent so we can judge them after the structural harness finishes.
+const capturedMessages = new Map(); // key: `${label}:${intent}` → messages
+
+async function generateMcp({ intent, mode }) {
+  const result = await generateUI({ intent, mode: mode || 'instant' });
+  const patternName = result.patternName ?? null;
+  const strategy = result.strategy || (patternName ? 'pattern-match' : 'fallback');
+  if (semanticEnabled && Array.isArray(result.messages) && result.messages.length > 0) {
+    capturedMessages.set(`mcp:${intent}`, result.messages);
+  }
+  return {
+    ...result,
+    strategy,
+    retrieval: {
+      hit: !!patternName,
+      rank: patternName ? 1 : null, // mcp picks top-1 only; no candidate list surfaced
+      candidate: patternName,
+    },
+  };
+}
+
+async function generateZettelCapture({ intent, mode }) {
+  const result = await generateZettel({ intent, mode });
+  if (semanticEnabled && Array.isArray(result.messages) && result.messages.length > 0) {
+    capturedMessages.set(`zettel:${intent}`, result.messages);
+  }
+  return result;
+}
+
+// ── Run ──
+let mcp = null;
+let zettel = null;
+
+if (runMcp) {
+  console.error(`[eval-diff] running mcp (monolithic) harness…`);
+  mcp = await runHarnessV2({
+    generate: generateMcp,
+    domain,
+    limit,
+    mode: 'instant',
+    label: 'mcp',
+  });
+  console.error(`  coverage=${mcp.coverage}% emitted=${mcp.emitted}/${mcp.total} avgScore=${mcp.avgScoreWhenEmitted}`);
+}
+
+if (runZettel) {
+  console.error(`[eval-diff] running zettel (fragment-graph) harness…`);
+  zettel = await runHarnessV2({
+    generate: generateZettelCapture,
+    domain,
+    limit,
+    mode: 'instant',
+    label: 'zettel',
+  });
+  console.error(`  coverage=${zettel.coverage}% emitted=${zettel.emitted}/${zettel.total} avgScore=${zettel.avgScoreWhenEmitted}`);
+}
+
+// ── Shadow-mode semantic validation (Phase 1) ──
+// Opt-in via --semantic. Annotates per-intent rows + aggregates with
+// semanticScore/verdict/combinedScore. DOES NOT affect row.pass, passRate,
+// or avgScoreWhenEmitted — those remain structural-only.
+async function annotateSemantic(runObj, label) {
+  if (!runObj || !semanticEnabled) return;
+  let semSum = 0;
+  let semN = 0;
+  let combSum = 0;
+  let combN = 0;
+  let tokensIn = 0;
+  let tokensOut = 0;
+  let cached = 0;
+  let errors = 0;
+  const verdictBreakdown = {};
+  for (const row of runObj.results) {
+    if (!row.messagesEmitted) continue;
+    const msgs = capturedMessages.get(`${label}:${row.intent}`);
+    if (!msgs) continue;
+    try {
+      const v = await validateSemantics(
+        { intent: row.intent, messages: msgs },
+        { cache: true, timeoutMs: 15000 },
+      );
+      row.semanticScore = v.score;
+      row.semanticVerdict = v.verdict;
+      row.semanticRationale = v.rationale;
+      row.semanticAxes = v.axes;
+      row.semanticCost = v.cost;
+      row.rubricVersion = v.rubricVersion;
+      const structural = row.validationScore ?? 0;
+      row.combinedScore = Math.round(0.6 * structural + 0.4 * v.score);
+      // NOTE: row.pass intentionally NOT updated — shadow mode only.
+      if (!v.error) {
+        semSum += v.score;
+        semN += 1;
+        combSum += row.combinedScore;
+        combN += 1;
+        verdictBreakdown[v.verdict] = (verdictBreakdown[v.verdict] || 0) + 1;
+        tokensIn += v.cost?.inputTokens || 0;
+        tokensOut += v.cost?.outputTokens || 0;
+        if (v.cost?.cached) cached += 1;
+      } else {
+        errors += 1;
+      }
+    } catch (e) {
+      errors += 1;
+      row.semanticError = e.message;
+    }
+  }
+  runObj.semantic = {
+    enabled: true,
+    mode: 'shadow',
+    judged: semN,
+    errors,
+    cached,
+    avgSemanticScore: semN ? Math.round(semSum / semN) : null,
+    avgCombinedScore: combN ? Math.round(combSum / combN) : null,
+    verdictBreakdown,
+    tokens: { input: tokensIn, output: tokensOut },
+    rubricVersion: 'v1',
+  };
+  console.error(`[semantic:${label}] judged=${semN} avgSem=${runObj.semantic.avgSemanticScore} avgCombined=${runObj.semantic.avgCombinedScore} cached=${cached} errors=${errors} tokens=${tokensIn}+${tokensOut}`);
+}
+
+if (semanticEnabled) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.error('[eval-diff] --semantic requested but ANTHROPIC_API_KEY missing; skipping.');
+  } else {
+    console.error(`[eval-diff] running semantic validator (shadow mode)…`);
+    if (mcp) await annotateSemantic(mcp, 'mcp');
+    if (zettel) await annotateSemantic(zettel, 'zettel');
+  }
+}
+
+// ── Write artifacts ──
+const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+const outDir = join(repoRoot, 'evals', 'mcp', 'runs', stamp);
+await mkdir(outDir, { recursive: true });
+if (mcp) await writeFile(join(outDir, 'mcp.json'), JSON.stringify(mcp, null, 2));
+if (zettel) await writeFile(join(outDir, 'zettel.json'), JSON.stringify(zettel, null, 2));
+
+// ── Build diff.md ──
+function fmt(v) { return v == null ? '—' : String(v); }
+function winner(a, b) {
+  const sa = a.messagesEmitted ? (a.validationScore ?? 0) : -1;
+  const sb = b.messagesEmitted ? (b.validationScore ?? 0) : -1;
+  if (sa === -1 && sb === -1) return 'both-miss';
+  if (sa === sb) return 'tie';
+  return sa > sb ? 'mcp' : 'zettel';
+}
+
+let md = '';
+md += `# Engine Eval ${mcp && zettel ? 'Diff' : 'Report'}\n\n`;
+md += `- Run: \`${stamp}\`\n`;
+md += `- Engine(s): ${engine}\n`;
+md += `- Intents: ${(mcp || zettel).total}${domain ? ` (domain: ${domain})` : ''}${limit ? ` (limit: ${limit})` : ''}\n`;
+md += `- Mode: instant\n\n`;
+
+md += `## Aggregates\n\n`;
+if (mcp && zettel) {
+  md += `| metric | mcp | zettel |\n|---|---:|---:|\n`;
+  md += `| coverage % | ${mcp.coverage} | ${zettel.coverage} |\n`;
+  md += `| emitted | ${mcp.emitted}/${mcp.total} | ${zettel.emitted}/${zettel.total} |\n`;
+  md += `| avgScore (emitted only) | ${mcp.avgScoreWhenEmitted} | ${zettel.avgScoreWhenEmitted} |\n`;
+  md += `| avgF1 (emitted only) | ${mcp.avgF1WhenEmitted} | ${zettel.avgF1WhenEmitted} |\n`;
+  md += `| pass rate % | ${mcp.passRate} | ${zettel.passRate} |\n`;
+  md += `| retrieval MRR | ${fmt(mcp.retrievalMRR)} | ${fmt(zettel.retrievalMRR)} |\n\n`;
+} else {
+  const e = mcp || zettel;
+  const label = mcp ? 'mcp' : 'zettel';
+  md += `| metric | ${label} |\n|---|---:|\n`;
+  md += `| coverage % | ${e.coverage} |\n`;
+  md += `| emitted | ${e.emitted}/${e.total} |\n`;
+  md += `| avgScore (emitted only) | ${e.avgScoreWhenEmitted} |\n`;
+  md += `| avgF1 (emitted only) | ${e.avgF1WhenEmitted} |\n`;
+  md += `| pass rate % | ${e.passRate} |\n`;
+  md += `| retrieval MRR | ${fmt(e.retrievalMRR)} |\n\n`;
+}
+
+if (mcp && zettel) {
+  const zByIntent = new Map(zettel.results.map((r) => [r.id, r]));
+  const rows = mcp.results.map((m) => {
+    const z = zByIntent.get(m.id);
+    return { m, z, winner: winner(m, z) };
+  });
+  const counts = rows.reduce((a, r) => { a[r.winner] = (a[r.winner] || 0) + 1; return a; }, {});
+
+  md += `## Winner breakdown\n\n`;
+  md += `- mcp wins: ${counts.mcp || 0}\n`;
+  md += `- zettel wins: ${counts.zettel || 0}\n`;
+  md += `- ties: ${counts.tie || 0}\n`;
+  md += `- both missed: ${counts['both-miss'] || 0}\n\n`;
+
+  md += `## Strategy breakdown\n\n`;
+  md += `**mcp**: ` + Object.entries(mcp.strategyBreakdown).map(([k, v]) => `${k}=${v}`).join(', ') + `\n\n`;
+  md += `**zettel**: ` + Object.entries(zettel.strategyBreakdown).map(([k, v]) => `${k}=${v}`).join(', ') + `\n\n`;
+
+  md += `## Per-intent\n\n`;
+  md += `| id | domain | intent | mcp score | mcp F1 | zettel score | zettel F1 | winner | zettel strategy |\n`;
+  md += `|---|---|---|---:|---:|---:|---:|---|---|\n`;
+  for (const { m, z, winner: w } of rows) {
+    const intent = (m.intent || '').slice(0, 48).replace(/\|/g, '\\|');
+    md += `| ${m.id} | ${fmt(m.domain)} | ${intent} | ${fmt(m.validationScore)} | ${fmt(m.componentF1)} | ${fmt(z.validationScore)} | ${fmt(z.componentF1)} | ${w} | ${fmt(z.strategy)} |\n`;
+  }
+
+  await writeFile(join(outDir, 'diff.md'), md);
+  console.error(`\n[eval-diff] wrote ${outDir}`);
+  console.error(`  mcp wins:    ${counts.mcp || 0}`);
+  console.error(`  zettel wins: ${counts.zettel || 0}`);
+  console.error(`  ties:        ${counts.tie || 0}`);
+  console.error(`  both missed: ${counts['both-miss'] || 0}`);
+} else {
+  const e = mcp || zettel;
+  const label = mcp ? 'mcp' : 'zettel';
+  md += `## Strategy breakdown\n\n`;
+  md += `**${label}**: ` + Object.entries(e.strategyBreakdown).map(([k, v]) => `${k}=${v}`).join(', ') + `\n\n`;
+  md += `## Per-intent\n\n`;
+  md += `| id | domain | intent | score | F1 | strategy |\n|---|---|---|---:|---:|---|\n`;
+  for (const r of e.results) {
+    const intent = (r.intent || '').slice(0, 48).replace(/\|/g, '\\|');
+    md += `| ${r.id} | ${fmt(r.domain)} | ${intent} | ${fmt(r.validationScore)} | ${fmt(r.componentF1)} | ${fmt(r.strategy)} |\n`;
+  }
+  await writeFile(join(outDir, 'diff.md'), md);
+  console.error(`\n[eval-diff] wrote ${outDir}`);
+}
+
+console.log(outDir);