prism-design 2.13.0

package/scripts/clone.ts

@@ -0,0 +1,198 @@
+/**
+ * Prism — Orchestrateur principal
+ *
+ * Pipeline complet : URL → Extract → Analyze → Tokenize
+ * Usage: npm run clone -- <URL>
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { shouldSkipExtraction, writeFingerprint } from './shared/cache.js';
+
+// Phase 2.3 — Parse CLI flags: clone <url> [--force] [--enrich]
+const args = process.argv.slice(2);
+const forceFlag = args.includes('--force');
+const enrichFlag = args.includes('--enrich');
+const fidelityFlag = args.includes('--fidelity');
+const url = args.find(a => !a.startsWith('--'));
+
+if (!url) {
+  console.error('Usage: npm run clone -- <URL> [--force]');
+  console.error('Example: npm run clone -- https://linear.app');
+  console.error('         npm run clone -- https://linear.app --force  (bypass cache)');
+  process.exit(1);
+}
+
+try {
+  new URL(url);
+} catch {
+  console.error(`Invalid URL: ${url}`);
+  process.exit(1);
+}
+
+const domain = new URL(url).hostname.replace('www.', '');
+const baseDir = join(process.cwd(), 'extractions', domain);
+
+const startTime = Date.now();
+
+console.log('╔══════════════════════════════════════════════════╗');
+console.log('║         CLONE ARCHITECT — Full Pipeline         ║');
+console.log('╚══════════════════════════════════════════════════╝');
+console.log(`\n🎯 Target: ${url}\n`);
+
+// Phase 2.3 — Cache check before expensive Playwright extraction
+const cacheResult = await shouldSkipExtraction(url, domain, { force: forceFlag });
+if (cacheResult.skip) {
+  console.log(`✨ Cache hit: ${cacheResult.reason} — skipping extraction (saved ~140s)`);
+  console.log(`   Use --force to bypass cache and re-extract`);
+  console.log(`\n📁 Existing extraction at: ${baseDir}\n`);
+  process.exit(0);
+}
+console.log(`🔍 Cache: ${cacheResult.reason}`);
+
+// Step 1 — Extract
+console.log('━━━ STEP 1/4 — EXTRACTION ━━━');
+try {
+  execSync(`npx tsx scripts/extract.ts "${url}"`, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    timeout: 120000,
+  });
+} catch (err) {
+  console.error('❌ Extraction failed');
+  process.exit(1);
+}
+
+// Phase 5.4.1 — Write fingerprint ONLY after extraction validation
+// Previously (bug G4): fingerprint was written even if raw-css.json was empty/cassée.
+// Result: future runs hit cache and skip a broken extraction forever.
+// Now: validate raw-css.json has at least 5 CSS vars AND a body element before writing fingerprint.
+if (cacheResult.fingerprint) {
+  try {
+    const rawCssPath = join(baseDir, 'raw-css.json');
+    if (existsSync(rawCssPath)) {
+      const rawData = JSON.parse(require('fs').readFileSync(rawCssPath, 'utf-8'));
+      const cssVarCount = Object.keys(rawData?.desktop?.cssCustomProperties || {}).length;
+      const hasBody = !!rawData?.desktop?.elements?.body;
+      const hasColors = (rawData?.desktop?.allColors || []).length >= 3;
+      // Threshold: at least 3 colors + a body element. Extractions that fail anti-bot have ~0 vars + no body.
+      if (hasBody && hasColors) {
+        await writeFingerprint(domain, cacheResult.fingerprint);
+      } else {
+        console.warn(`  ⚠️  Skipping cache fingerprint (cssVars=${cssVarCount}, hasBody=${hasBody}, colors=${(rawData?.desktop?.allColors || []).length}) — looks like an aborted extraction`);
+      }
+    }
+  } catch (e) {
+    console.warn(`  ⚠️  Failed to validate raw-css.json before fingerprint: ${(e as Error).message}`);
+  }
+}
+
+// Check extraction output
+if (!existsSync(join(baseDir, 'raw-css.json'))) {
+  console.error('❌ raw-css.json not found after extraction');
+  process.exit(1);
+}
+
+// Step 1b (v2.10-C) — download key assets locally so the extraction is self-contained (best-effort)
+try {
+  const { downloadKeyAssets } = await import('./asset-downloader.js');
+  const a = await downloadKeyAssets(baseDir, domain);
+  console.log(`  📥 Assets: ${a.downloaded} downloaded, ${a.failed} failed → extractions/${domain}/assets/`);
+} catch (err) {
+  console.warn(`  ⚠️  Asset download skipped (non-blocking): ${(err as Error).message}`);
+}
+
+// Step 2 — Analyze
+console.log('\n━━━ STEP 2/4 — LAYOUT ANALYSIS ━━━');
+try {
+  execSync(`npx tsx scripts/analyze.ts "${domain}"`, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+} catch (err) {
+  console.error('❌ Analysis failed');
+  process.exit(1);
+}
+
+// Step 3 — Tokenize
+console.log('\n━━━ STEP 3/4 — TOKENIZATION ━━━');
+try {
+  execSync(`npx tsx scripts/tokenize.ts "${domain}"`, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+} catch (err) {
+  console.error('❌ Tokenization failed');
+  process.exit(1);
+}
+
+// Step 4 — Generate DESIGN.md
+console.log('\n━━━ STEP 4/5 — DESIGN.MD GENERATION ━━━\n');
+try {
+  execSync(`npx tsx scripts/generate-design-md.ts "${domain}"`, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+} catch (err) {
+  console.error('⚠️  DESIGN.md generation failed (non-blocking)');
+}
+
+// Step 5 — Generate showcase HTML
+console.log('\n━━━ STEP 5/5 — SHOWCASE ━━━\n');
+try {
+  execSync(`npx tsx scripts/generate-showcase.ts "${domain}"`, {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+    timeout: 30000,
+  });
+} catch (err) {
+  console.error('⚠️  Showcase generation failed (non-blocking)');
+}
+
+// Step 5b (optional) — Fidelity loop: rebuild a token-faithful page + pixelmatch vs original.
+// Writes extractions/<domain>/comparison/score.json (above-fold, 2×-matched). HONEST: token-level
+// reconstruction, not a pixel clone — the score is a floor. Run with --fidelity.
+if (fidelityFlag) {
+  console.log('\n━━━ FIDELITY — token rebuild + pixelmatch (above-fold) ━━━\n');
+  try {
+    execSync(`npx tsx scripts/rebuild.ts "${domain}"`, { stdio: 'inherit', cwd: process.cwd(), timeout: 30000 });
+    execSync(`npx tsx scripts/compare.ts "${domain}"`, { stdio: 'inherit', cwd: process.cwd(), timeout: 120000 });
+  } catch (err) {
+    console.warn(`⚠️  Fidelity step failed (non-blocking): ${(err as Error).message}`);
+  }
+}
+
+// Step 6 (optional) — Narrative enrichment via Claude API
+if (enrichFlag) {
+  console.log('\n━━━ STEP 6/6 — NARRATIVE ENRICHMENT (LLM pass) ━━━\n');
+  try {
+    const { enrichDesignMd } = await import('./narrative-enricher.js');
+    await enrichDesignMd(domain, { apiKey: process.env.ANTHROPIC_API_KEY });
+    console.log('   DESIGN.enriched.md written ✅');
+  } catch (err) {
+    console.warn(`⚠️  Narrative enrichment failed (non-blocking): ${(err as Error).message}`);
+  }
+}
+
+const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+console.log('\n╔══════════════════════════════════════════════════╗');
+console.log('║              PIPELINE COMPLETE                   ║');
+console.log('╚══════════════════════════════════════════════════╝');
+console.log(`\n⏱️  Duration: ${duration}s`);
+console.log(`📁 Output: extractions/${domain}/`);
+console.log('   ├── screenshots/          — Playwright captures');
+console.log('   ├── raw-css.json          — Computed styles brut');
+console.log('   ├── extraction-summary.json');
+console.log('   ├── layout-analysis.md    — Structure analysée');
+console.log('   ├── tokens.json           — Design tokens normalisés');
+console.log('   ├── DESIGN.md             — Narratif LLM-optimisé (format Google DESIGN.md, 24 sections)');
+console.log('   └── showcase/index.html   — Page de présentation visuelle');
+console.log('\n📋 Next steps:');
+console.log('   1. Review tokens.json and layout-analysis.md');
+console.log('   2. Use tokens to generate faithful code (R16 pipeline)');
+console.log('   3. Run: npm run compare -- ' + domain);

package/scripts/compare-vs-gd-final.ts

@@ -0,0 +1,273 @@
+/**
+ * Prism vs getdesign.md — HONEST Comparison Framework
+ *
+ * v2.12 REWRITE — the previous scorer measured VOLUME, not quality:
+ *   - it rewarded raw line count (`normalizeLog(designMdLines)`),
+ *   - it gave Prism a free +20 "verifiability" that getdesign could NEVER earn
+ *     (screenshots+tokens are CA-only), then declared CA the winner.
+ *   A ground-truthed audit (docs/comparison/auditmax-vs-gd) showed the opposite:
+ *   getdesign wins on editorial/rebuild fidelity. So the old composite was self-deception.
+ *
+ * This version:
+ *   - Scores COVERAGE + CONCRETENESS with an IDENTICAL formula for CA and GD (symmetric, fair).
+ *   - Caps every sub-score at 100 so breadth beyond the canonical 9 sections can't inflate.
+ *   - Removes line-count/volume entirely.
+ *   - Reports Prism's structural advantages (screenshots, raw CSS, re-extractability) SEPARATELY,
+ *     never folded into the head-to-head number.
+ *   - States explicitly what it does NOT measure (editorial quality, rebuild fidelity).
+ *
+ * Output: docs/comparison/ca-vs-gd-final.{json,md}
+ */
+
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+const ROOT = process.cwd();
+
+// ── GD slug → CA domain mapping ──────────────────────────────────────────
+const GD_SLUG_MAP: Record<string, string> = {
+  'bmw-m': 'bmwm.com', 'hp': 'hp.com', 'airbnb': 'airbnb.com', 'airtable': 'airtable.com',
+  'apple': 'apple.com', 'binance': 'binance.com', 'bmw': 'bmw.com', 'bugatti': 'bugatti.com',
+  'cal': 'cal.com', 'claude': 'claude.com', 'clay': 'clay.com', 'clickhouse': 'clickhouse.com',
+  'cohere': 'cohere.com', 'coinbase': 'coinbase.com', 'composio': 'composio.dev',
+  'cursor': 'cursor.com', 'elevenlabs': 'elevenlabs.io', 'expo': 'expo.dev',
+  'ferrari': 'ferrari.com', 'figma': 'figma.com', 'framer': 'framer.com',
+  'hashicorp': 'hashicorp.com', 'ibm': 'ibm.com', 'intercom': 'intercom.com',
+  'kraken': 'kraken.com', 'lamborghini': 'lamborghini.com', 'linear': 'linear.app',
+  'lovable': 'lovable.dev', 'mastercard': 'mastercard.com', 'meta': 'meta.com',
+  'minimax': 'minimax.io', 'mintlify': 'mintlify.com', 'miro': 'miro.com',
+  'mistral.ai': 'mistral.ai', 'mongodb': 'mongodb.com', 'nike': 'nike.com',
+  'notion': 'notion.so', 'nvidia': 'nvidia.com', 'ollama': 'ollama.com',
+  'opencode.ai': 'opencode.ai', 'pinterest': 'pinterest.com', 'playstation': 'playstation.com',
+  'posthog': 'posthog.com', 'raycast': 'raycast.com', 'renault': 'renault.com',
+  'replicate': 'replicate.com', 'resend': 'resend.com', 'revolut': 'revolut.com',
+  'runwayml': 'runwayml.com', 'sanity': 'sanity.io', 'sentry': 'sentry.io',
+  'shopify': 'shopify.com', 'spacex': 'spacex.com', 'spotify': 'spotify.com',
+  'starbucks': 'starbucks.com', 'stripe': 'stripe.com', 'supabase': 'supabase.com',
+  'superhuman': 'superhuman.com', 'tesla': 'tesla.com', 'theverge': 'theverge.com',
+  'together.ai': 'together.ai', 'uber': 'uber.com', 'vercel': 'vercel.com',
+  'vodafone': 'vodafone.com', 'voltagent': 'voltagent.dev', 'warp': 'warp.dev',
+  'webflow': 'webflow.com', 'wired': 'wired.com', 'wise': 'wise.com',
+  'x.ai': 'x.ai', 'zapier': 'zapier.com'
+};
+const DOMAIN_TO_SLUG: Record<string, string> = Object.fromEntries(
+  Object.entries(GD_SLUG_MAP).map(([s, d]) => [d, s])
+);
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+function countSections(content: string): number {
+  // count distinct top-level numbered/titled sections (## 1. X, ## Foo)
+  return content.split('\n').filter(l => /^##\s+\d?\.?\s*[A-Z]/.test(l)).length;
+}
+function extractHexColors(content: string): string[] {
+  const hexes = content.match(/#[0-9a-fA-F]{6}\b/g) || [];
+  return [...new Set(hexes.map(h => h.toLowerCase()))];
+}
+function extractFontFamilies(content: string): string[] {
+  // Format-agnostic: getdesign writes typography in PROSE ("Primary typeface: Inter"),
+  // Prism in CSS-ish form ("font-family: Inter"). Penalizing GD for prose = dishonest.
+  // Count typography presence across both conventions.
+  const matches = content.match(/font[-_ ]?family\s*:|typeface|font stack|primary font|monospace font/gi) || [];
+  return matches;
+}
+function hasFrontmatter(content: string): boolean {
+  return content.startsWith('---\n') || content.startsWith('---\r\n');
+}
+function rgbDistance(hex1: string, hex2: string): number {
+  const h1 = hex1.replace('#', ''), h2 = hex2.replace('#', '');
+  if (h1.length !== 6 || h2.length !== 6) return 999;
+  const r1 = parseInt(h1.slice(0, 2), 16), g1 = parseInt(h1.slice(2, 4), 16), b1 = parseInt(h1.slice(4, 6), 16);
+  const r2 = parseInt(h2.slice(0, 2), 16), g2 = parseInt(h2.slice(2, 4), 16), b2 = parseInt(h2.slice(4, 6), 16);
+  return Math.sqrt((r1 - r2) ** 2 + (g1 - g2) ** 2 + (b1 - b2) ** 2);
+}
+function avgPaletteDelta(paletteA: string[], paletteB: string[], k = 5): number {
+  const topA = paletteA.slice(0, k), topB = paletteB.slice(0, k);
+  if (topA.length === 0 || topB.length === 0) return 999;
+  let sum = 0, count = 0;
+  for (const ca of topA) { sum += Math.min(...topB.map(cb => rgbDistance(ca, cb))); count++; }
+  return count > 0 ? sum / count : 999;
+}
+
+// ── Brand metrics ────────────────────────────────────────────────────────
+interface DocMetrics {
+  designMdLines: number; sectionsCount: number; colorsCount: number;
+  palette: string[]; fontFamiliesCount: number; sizeKb: number; hasFrontmatter: boolean;
+}
+interface CABrand extends DocMetrics {
+  hasScreenshots: boolean; hasTokensJson: boolean; hasRawCss: boolean;
+  completenessScore: number; dark: boolean; fidelityScore: number | null;
+}
+
+function baseMetrics(content: string): DocMetrics {
+  return {
+    designMdLines: content.split('\n').length,
+    sectionsCount: countSections(content),
+    colorsCount: extractHexColors(content).length,
+    palette: extractHexColors(content).slice(0, 10),
+    fontFamiliesCount: extractFontFamilies(content).length,
+    sizeKb: Math.round(Buffer.byteLength(content, 'utf-8') / 1024),
+    hasFrontmatter: hasFrontmatter(content),
+  };
+}
+
+function analyzeCA(domain: string, catalog: any): CABrand | null {
+  const dir = join(ROOT, 'extractions', domain);
+  const md = join(dir, 'DESIGN.md');
+  if (!existsSync(md)) return null;
+  const content = readFileSync(md, 'utf-8');
+  const entry = catalog.brands?.find((b: any) => b.domain === domain);
+  // optional fidelity score from compare.ts output (honest, may be absent)
+  let fidelityScore: number | null = null;
+  const cmpPath = join(dir, 'comparison', 'score.json');
+  if (existsSync(cmpPath)) {
+    try { fidelityScore = JSON.parse(readFileSync(cmpPath, 'utf-8')).score ?? null; } catch { /* noop */ }
+  }
+  return {
+    ...baseMetrics(content),
+    hasScreenshots: existsSync(join(dir, 'screenshots')),
+    hasTokensJson: existsSync(join(dir, 'tokens.json')),
+    hasRawCss: existsSync(join(dir, 'raw-css.json')),
+    completenessScore: entry?.completeness || 0,
+    dark: entry?.dark || false,
+    fidelityScore,
+  };
+}
+
+function analyzeGD(slug: string): DocMetrics | null {
+  // GD reference DESIGN.md files live under compare-gd/<slug>/GD-DESIGN.md
+  const candidates = [
+    join(ROOT, 'compare-gd', slug, 'GD-DESIGN.md'),
+    join(ROOT, 'audit-getdesign', `${slug}-DESIGN.md`),
+  ];
+  const path = candidates.find(p => existsSync(p));
+  if (!path) return null;
+  return baseMetrics(readFileSync(path, 'utf-8'));
+}
+
+// ── HONEST scoring — identical formula for CA and GD ───────────────────────
+const CANONICAL_SECTIONS = 9; // the dimensions getdesign.md's own format covers
+
+function coverageScore(sectionsCount: number): number {
+  return Math.round(Math.min(100, (sectionsCount / CANONICAL_SECTIONS) * 100));
+}
+function concretenessScore(colorsCount: number, fontFamiliesCount: number): number {
+  // Does the doc specify ENOUGH concrete values to act on? Saturates FAST — a curated 8-color doc
+  // is as "concrete" as a 50-color dump. This deliberately does NOT reward listing more colors
+  // (that was the old volume game in disguise, and it rewarded palette pollution). Both a tight
+  // hand-curated catalog and a broad auto-extraction reach 100 if they specify the essentials.
+  const colorPart = colorsCount >= 6 ? 55 : Math.round(colorsCount * 9);
+  const fontPart = fontFamiliesCount >= 1 ? 45 : 0;
+  return Math.min(100, colorPart + fontPart);
+}
+/** Documentation score: coverage + concreteness, identical for both sides. No volume, no verif bonus. */
+function docScore(d: DocMetrics | null): number {
+  if (!d) return 0;
+  return Math.round(0.5 * coverageScore(d.sectionsCount) + 0.5 * concretenessScore(d.colorsCount, d.fontFamiliesCount));
+}
+/** Prism-only structural advantages — reported SEPARATELY, never added to the doc score (R26). */
+function structuralAdvantages(ca: CABrand | null): string[] {
+  if (!ca) return [];
+  const a: string[] = [];
+  if (ca.hasScreenshots) a.push('desktop+mobile screenshots');
+  if (ca.hasRawCss) a.push('raw-css.json audit trail');
+  if (ca.hasTokensJson) a.push('tokens.json');
+  a.push('re-extractable / dated');
+  return a;
+}
+
+function verdict(ca: CABrand | null, gd: DocMetrics | null): { doc: 'CA' | 'GD' | 'tie'; reason: string } {
+  if (!ca && !gd) return { doc: 'tie', reason: 'no data' };
+  if (!gd) return { doc: 'CA', reason: 'no GD reference for this brand' };
+  if (!ca) return { doc: 'GD', reason: 'no Prism extraction for this brand' };
+  const c = docScore(ca), g = docScore(gd);
+  const doc = c > g + 8 ? 'CA' : g > c + 8 ? 'GD' : 'tie';
+  return { doc, reason: `coverage+concreteness ${c} vs ${g}` };
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────
+async function main() {
+  console.log('🔬 Prism vs getdesign.md — HONEST comparison (coverage + concreteness, symmetric)\n');
+
+  const catalog = JSON.parse(readFileSync(join(ROOT, 'catalog', 'index.json'), 'utf-8'));
+  const gdDomains = Object.values(GD_SLUG_MAP);
+
+  const results: any[] = [];
+  const docWins = { ca: 0, gd: 0, tie: 0 };
+  let sumCA = 0, sumGD = 0, compared = 0, caStructuralCount = 0;
+
+  for (const domain of gdDomains) {
+    const slug = DOMAIN_TO_SLUG[domain];
+    const ca = analyzeCA(domain, catalog);
+    const gd = analyzeGD(slug);
+    if (!ca || !gd) continue; // only score brands where BOTH docs exist (honest head-to-head)
+
+    const sCA = docScore(ca), sGD = docScore(gd);
+    const v = verdict(ca, gd);
+    const adv = structuralAdvantages(ca);
+    const paletteDelta = Math.round(avgPaletteDelta(ca.palette, gd.palette, 5));
+
+    compared++; sumCA += sCA; sumGD += sGD;
+    docWins[v.doc === 'CA' ? 'ca' : v.doc === 'GD' ? 'gd' : 'tie']++;
+    if (adv.length >= 3) caStructuralCount++;
+
+    results.push({
+      domain, slug,
+      caDoc: sCA, gdDoc: sGD,
+      caCoverage: coverageScore(ca.sectionsCount), gdCoverage: coverageScore(gd.sectionsCount),
+      caConcreteness: concretenessScore(ca.colorsCount, ca.fontFamiliesCount),
+      gdConcreteness: concretenessScore(gd.colorsCount, gd.fontFamiliesCount),
+      caFidelity: ca.fidelityScore, caStructural: adv, paletteDelta, verdict: v,
+    });
+    console.log(`  ${domain.padEnd(22)} doc CA ${String(sCA).padStart(3)} vs GD ${String(sGD).padStart(3)}  → ${v.doc.toUpperCase()}  ${ca.fidelityScore != null ? `(fidelity ${ca.fidelityScore}%)` : ''}`);
+  }
+
+  const avgCA = compared ? Math.round(sumCA / compared) : 0;
+  const avgGD = compared ? Math.round(sumGD / compared) : 0;
+
+  console.log('\n══════════════════════════════════════════════════');
+  console.log('📊 HONEST DOC SCORE (coverage + concreteness, same formula both sides)');
+  console.log('══════════════════════════════════════════════════');
+  console.log(`Brands with BOTH docs : ${compared}`);
+  console.log(`Avg doc score         : CA ${avgCA} vs GD ${avgGD} (Δ ${avgCA - avgGD})`);
+  console.log(`Doc-coverage wins     : CA ${docWins.ca} | GD ${docWins.gd} | tie ${docWins.tie}`);
+  console.log(`CA structural extras  : ${caStructuralCount}/${compared} brands ship screenshots+rawCSS+tokens`);
+  console.log('\n⚠️  NOT measured here: editorial-narrative quality (human-judged; a ground-truth audit favored getdesign)');
+  console.log('⚠️  NOT measured here: rebuild fidelity (run scripts/compare.ts per brand — pixelmatch vs original)');
+
+  // ── Save outputs ────────────────────────────────────────────────────
+  const outDir = join(ROOT, 'docs', 'comparison');
+  mkdirSync(outDir, { recursive: true });
+
+  const jsonOut = {
+    generatedAt: new Date().toISOString(),
+    method: 'symmetric coverage+concreteness; volume removed; verifiability reported separately',
+    comparedCount: compared,
+    avg: { caDoc: avgCA, gdDoc: avgGD, delta: avgCA - avgGD },
+    docWins,
+    caStructuralCount,
+    notMeasured: ['editorial narrative quality (human-judged, audit favored GD)', 'rebuild fidelity (see compare.ts)'],
+    brands: results,
+  };
+  writeFileSync(join(outDir, 'ca-vs-gd-final.json'), JSON.stringify(jsonOut, null, 2));
+
+  let md = `# Prism vs getdesign.md — Honest Comparison\n\n`;
+  md += `Generated: ${jsonOut.generatedAt}\n\n`;
+  md += `**Method (v2.12, honest):** documentation score = 50% coverage (vs the 9 canonical sections) + 50% concreteness (concrete hex/font values, capped). **Identical formula for both sides.** Volume (line count) removed — it rewarded bloat. Prism's structural artifacts (screenshots, raw CSS, tokens) are listed **separately**, never added to the score.\n\n`;
+  md += `> **What this does NOT measure:** editorial-narrative quality (human-judged — a ground-truth audit favored getdesign) and rebuild fidelity (pixelmatch, see \`compare.ts\`). This tool measures documentation **coverage + concreteness only.**\n\n`;
+  md += `## Aggregate\n\n`;
+  md += `| Metric | Prism | getdesign.md | Δ |\n|---|---|---|---|\n`;
+  md += `| Brands compared (both docs present) | ${compared} | ${compared} | — |\n`;
+  md += `| Avg doc score /100 | ${avgCA} | ${avgGD} | ${avgCA - avgGD >= 0 ? '+' : ''}${avgCA - avgGD} |\n`;
+  md += `| Doc-coverage wins | ${docWins.ca} | ${docWins.gd} | (tie ${docWins.tie}) |\n`;
+  md += `| Ships screenshots + rawCSS + tokens | ${caStructuralCount}/${compared} | 0/${compared} | structural |\n\n`;
+  md += `## Per-brand\n\n`;
+  md += `| Brand | CA doc | GD doc | CA cover | GD cover | CA concr | GD concr | ΔE palette | Verdict |\n|---|---|---|---|---|---|---|---|---|\n`;
+  for (const r of [...results].sort((a, b) => b.caDoc - a.caDoc)) {
+    md += `| ${r.domain} | ${r.caDoc} | ${r.gdDoc} | ${r.caCoverage} | ${r.gdCoverage} | ${r.caConcreteness} | ${r.gdConcreteness} | ${r.paletteDelta} | ${r.verdict.doc.toUpperCase()} |\n`;
+  }
+  md += `\n*Prism's edge is automation + verifiable artifacts + re-extractability + breadth — not a claim of better editorial fidelity. Where the doc scores tie, Prism's separately-listed structural artifacts are the real differentiator.*\n`;
+  writeFileSync(join(outDir, 'ca-vs-gd-final.md'), md);
+  console.log(`\n💾 docs/comparison/ca-vs-gd-final.{json,md}`);
+}
+
+main().catch(err => { console.error(err); process.exit(1); });