@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/reporting/consensus.js

@@ -0,0 +1,416 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { nowIso, readJson } from '../shared/io.js';
+
+const NO_GUARANTEE = 'Consensus matrix evaluates agreement between declared publisher signals (HTML rel=canonical, Open Graph og:url, XML sitemaps, HTTP Last-Modified) and optional search engine observations. Signal consensus does not guarantee crawling, indexing, ranking, or citation outcomes in search or answer engines.';
+
+export function loadConsensusRuns(root, { runId, since, last } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  const included = [];
+  const skipped = [];
+  if (!fs.existsSync(runsDir)) return { included, skipped };
+
+  let runIds = [];
+  if (runId) {
+    if (fs.existsSync(path.join(runsDir, runId))) {
+      runIds = [runId];
+    } else {
+      throw new Error(`run not found: ${runId}`);
+    }
+  } else {
+    runIds = fs.readdirSync(runsDir).sort();
+    if (since) runIds = runIds.filter((id) => id >= since);
+  }
+
+  for (const id of runIds) {
+    const dir = path.join(runsDir, id);
+    const obsDir = path.join(dir, 'observations');
+    if (!fs.existsSync(obsDir)) continue;
+
+    try {
+      const files = fs.readdirSync(obsDir).filter((f) => f.endsWith('.json')).sort();
+      const consensusObs = [];
+      for (const f of files) {
+        const item = readJson(path.join(obsDir, f));
+        if (item.kind === 'canonical_freshness') {
+          consensusObs.push(item);
+        }
+      }
+      if (consensusObs.length > 0) {
+        const manifest = fs.existsSync(path.join(dir, 'manifest.json'))
+          ? readJson(path.join(dir, 'manifest.json'))
+          : null;
+        included.push({ run_id: id, manifest, observations: consensusObs });
+      }
+    } catch (err) {
+      skipped.push({ run_id: id, reason: err.message });
+    }
+  }
+
+  const windowed = Number.isInteger(last) && last > 0 ? included.slice(-last) : included;
+  return { included: windowed, skipped };
+}
+
+export function buildConsensusMatrix(includedRuns = []) {
+  if (!includedRuns.length) {
+    return {
+      latest_run_id: null,
+      target: null,
+      total_urls: 0,
+      full_canonical_consensus: 0,
+      canonical_conflicts: 0,
+      engine_discrepancies: 0,
+      freshness_aligned: 0,
+      freshness_conflicts: 0,
+      freshness_insufficient: 0,
+      rows: [],
+      discrepancies: [],
+    };
+  }
+
+  const latestRun = includedRuns[includedRuns.length - 1];
+  const observations = latestRun.observations || [];
+
+  const rows = [];
+  const discrepancies = [];
+
+  let fullCanonicalConsensus = 0;
+  let canonicalConflicts = 0;
+  let engineDiscrepancies = 0;
+  let freshnessAligned = 0;
+  let freshnessConflicts = 0;
+  let freshnessInsufficient = 0;
+
+  for (const obs of observations) {
+    const data = obs.data || {};
+    const signals = data.signals || {};
+    const url = data.url || signals.final_url;
+    const htmlCanonical = signals.html_canonical || null;
+    const ogUrl = signals.open_graph_url || null;
+    const sitemapPresent = Boolean(signals.sitemap_present);
+    const canonicalConsensus = Boolean(data.canonical_consensus);
+    const dateConsensus = data.date_consensus;
+    const freshnessAssessment = data.freshness_assessment || 'insufficient_signals';
+    const contentSnapshot = data.content_snapshot || {};
+    const engineCanonicals = data.engine_selected_canonical || [];
+    const canonicalConsensusWithEngines = data.canonical_consensus_with_engines;
+
+    const itemDiscrepancies = [];
+    if (htmlCanonical && htmlCanonical !== url) {
+      itemDiscrepancies.push({
+        type: 'non_self_canonical',
+        description: `rel=canonical targets ${htmlCanonical} instead of self URL`,
+      });
+    }
+    if (ogUrl && htmlCanonical && ogUrl !== htmlCanonical) {
+      itemDiscrepancies.push({
+        type: 'og_disagrees_with_canonical',
+        description: `Open Graph URL (${ogUrl}) disagrees with rel=canonical (${htmlCanonical})`,
+      });
+    }
+    if (!sitemapPresent) {
+      itemDiscrepancies.push({
+        type: 'missing_from_sitemap',
+        description: 'Page URL is not listed in any XML sitemap',
+      });
+    }
+    if (engineCanonicals.length > 0) {
+      for (const ec of engineCanonicals) {
+        if (ec.selected_canonical && htmlCanonical && ec.selected_canonical !== htmlCanonical) {
+          itemDiscrepancies.push({
+            type: 'engine_canonical_discrepancy',
+            description: `${ec.engine || 'Search engine'} selected canonical (${ec.selected_canonical}) differs from declared rel=canonical (${htmlCanonical})`,
+          });
+        }
+      }
+    }
+    if (freshnessAssessment === 'conflicting_signals') {
+      itemDiscrepancies.push({
+        type: 'conflicting_freshness_dates',
+        description: 'HTTP Last-Modified, sitemap lastmod, and/or visible date signals disagree',
+      });
+    }
+
+    if (canonicalConsensus) {
+      fullCanonicalConsensus++;
+    } else {
+      canonicalConflicts++;
+    }
+
+    if (canonicalConsensusWithEngines === false) {
+      engineDiscrepancies++;
+    }
+
+    if (freshnessAssessment === 'aligned_signals') {
+      freshnessAligned++;
+    } else if (freshnessAssessment === 'conflicting_signals') {
+      freshnessConflicts++;
+    } else {
+      freshnessInsufficient++;
+    }
+
+    const row = {
+      url,
+      html_canonical: htmlCanonical,
+      open_graph_url: ogUrl,
+      sitemap_present: sitemapPresent,
+      canonical_consensus: canonicalConsensus,
+      engine_canonicals: engineCanonicals,
+      canonical_consensus_with_engines: canonicalConsensusWithEngines,
+      freshness_assessment: freshnessAssessment,
+      date_consensus: dateConsensus,
+      date_signals: data.date_signals || [],
+      content_changed: contentSnapshot.changed_since_snapshot,
+      content_hash: contentSnapshot.current_content_hash,
+      discrepancies: itemDiscrepancies,
+    };
+
+    rows.push(row);
+    if (itemDiscrepancies.length > 0) {
+      discrepancies.push({ url, discrepancies: itemDiscrepancies });
+    }
+  }
+
+  return {
+    latest_run_id: latestRun.run_id,
+    target: latestRun.manifest?.target?.location || null,
+    total_urls: rows.length,
+    full_canonical_consensus: fullCanonicalConsensus,
+    canonical_conflicts: canonicalConflicts,
+    engine_discrepancies: engineDiscrepancies,
+    freshness_aligned: freshnessAligned,
+    freshness_conflicts: freshnessConflicts,
+    freshness_insufficient: freshnessInsufficient,
+    rows,
+    discrepancies,
+  };
+}
+
+export function renderConsensusMarkdown(matrix, { runId, skipped = [], generatedAt = nowIso() } = {}) {
+  const lines = [
+    '# Canonical Discovery & Freshness Consensus Matrix',
+    '',
+    `> **Operating boundary:** ${NO_GUARANTEE}`,
+    '',
+    `- **Run ID:** \`${runId || matrix.latest_run_id || 'n/a'}\``,
+    `- **Generated:** ${generatedAt}`,
+    `- **Target:** \`${matrix.target || 'n/a'}\``,
+    `- **Evaluated URLs:** ${matrix.total_urls}`,
+    '',
+    '## Executive Summary',
+    '',
+    '| Consensus Dimension | Count | Percentage |',
+    '| --- | --- | --- |',
+    `| Total URLs Evaluated | ${matrix.total_urls} | 100.0% |`,
+    `| Full Publisher Canonical Consensus | ${matrix.full_canonical_consensus} | ${matrix.total_urls ? ((matrix.full_canonical_consensus / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    `| Internal Canonical Conflicts | ${matrix.canonical_conflicts} | ${matrix.total_urls ? ((matrix.canonical_conflicts / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    `| Search Engine Discrepancies | ${matrix.engine_discrepancies} | ${matrix.total_urls ? ((matrix.engine_discrepancies / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    `| Freshness Signals Aligned | ${matrix.freshness_aligned} | ${matrix.total_urls ? ((matrix.freshness_aligned / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    `| Freshness Signals Conflicting | ${matrix.freshness_conflicts} | ${matrix.total_urls ? ((matrix.freshness_conflicts / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    `| Freshness Data Insufficient | ${matrix.freshness_insufficient} | ${matrix.total_urls ? ((matrix.freshness_insufficient / matrix.total_urls) * 100).toFixed(1) : 0}% |`,
+    '',
+    '## URL Discovery Consensus Matrix',
+    '',
+    '| URL | rel=canonical | og:url | Sitemap | Engine Selected | Canonical Consensus | Freshness Assessment |',
+    '| --- | --- | --- | --- | --- | --- | --- |',
+  ];
+
+  for (const r of matrix.rows) {
+    const engineText = r.engine_canonicals.length
+      ? r.engine_canonicals.map((e) => `${e.engine}: ${e.selected_canonical}`).join('; ')
+      : '*(none)*';
+    const canonStatus = r.canonical_consensus ? '✅ Consensus' : '❌ Conflict';
+    const freshStatus = r.freshness_assessment === 'aligned_signals'
+      ? '✅ Aligned'
+      : r.freshness_assessment === 'conflicting_signals'
+        ? '⚠️ Conflict'
+        : '⚪ Insufficient';
+
+    lines.push(`| \`${r.url}\` | \`${r.html_canonical || '(none)'}\` | \`${r.open_graph_url || '(none)'}\` | ${r.sitemap_present ? 'Yes' : 'No'} | ${engineText} | ${canonStatus} | ${freshStatus} |`);
+  }
+
+  if (matrix.discrepancies.length > 0) {
+    lines.push('', '## Discrepancy Breakdown', '');
+    lines.push('| URL | Discrepancy Type | Description |');
+    lines.push('| --- | --- | --- |');
+    for (const d of matrix.discrepancies) {
+      for (const item of d.discrepancies) {
+        lines.push(`| \`${d.url}\` | \`${item.type}\` | ${item.description} |`);
+      }
+    }
+  }
+
+  if (skipped.length > 0) {
+    lines.push('', '## Skipped Runs', '');
+    lines.push('| Run ID | Reason |');
+    lines.push('| --- | --- |');
+    for (const s of skipped) {
+      lines.push(`| \`${s.run_id}\` | ${s.reason} |`);
+    }
+  }
+
+  lines.push('', '---', `*Generated by Citable ${nowIso().slice(0, 10)}*`, '');
+  return lines.join('\n');
+}
+
+export function renderConsensusHtml(matrix, { runId, skipped = [], generatedAt = nowIso() } = {}) {
+  const rowsHtml = matrix.rows.map((r) => {
+    const canonBadge = r.canonical_consensus
+      ? '<span class="badge badge-pass">Consensus</span>'
+      : '<span class="badge badge-fail">Conflict</span>';
+
+    const freshBadge = r.freshness_assessment === 'aligned_signals'
+      ? '<span class="badge badge-pass">Aligned</span>'
+      : r.freshness_assessment === 'conflicting_signals'
+        ? '<span class="badge badge-warn">Conflict</span>'
+        : '<span class="badge badge-muted">Insufficient</span>';
+
+    const engineText = r.engine_canonicals.length
+      ? r.engine_canonicals.map((e) => `${e.engine}: ${e.selected_canonical}`).join('<br>')
+      : '<span class="text-muted">none</span>';
+
+    return `<tr>
+  <td><code>${r.url}</code></td>
+  <td><code>${r.html_canonical || '<span class="text-muted">none</span>'}</code></td>
+  <td><code>${r.open_graph_url || '<span class="text-muted">none</span>'}</code></td>
+  <td>${r.sitemap_present ? 'Yes' : '<span class="text-warn">No</span>'}</td>
+  <td>${engineText}</td>
+  <td>${canonBadge}</td>
+  <td>${freshBadge}</td>
+</tr>`;
+  }).join('\n');
+
+  const discrepancyRowsHtml = matrix.discrepancies.flatMap((d) =>
+    d.discrepancies.map((item) => `<tr>
+  <td><code>${d.url}</code></td>
+  <td><code>${item.type}</code></td>
+  <td>${item.description}</td>
+</tr>`)
+  ).join('\n');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Canonical Discovery Consensus Matrix — Citable</title>
+  <style>
+    :root {
+      --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      --bg: #0f172a;
+      --card-bg: #1e293b;
+      --border: #334155;
+      --text: #f8fafc;
+      --text-muted: #94a3b8;
+      --pass: #22c55e;
+      --fail: #ef4444;
+      --warn: #f59e0b;
+    }
+    body {
+      font-family: var(--font);
+      background: var(--bg);
+      color: var(--text);
+      margin: 0;
+      padding: 2rem;
+      line-height: 1.5;
+    }
+    .container { max-width: 1200px; margin: 0 auto; }
+    header { margin-bottom: 2rem; border-bottom: 1px solid var(--border); padding-bottom: 1rem; }
+    h1 { margin: 0 0 0.5rem 0; font-size: 1.8rem; }
+    .meta { color: var(--text-muted); font-size: 0.9rem; }
+    .notice {
+      background: #1e293b;
+      border-left: 4px solid var(--warn);
+      padding: 0.75rem 1rem;
+      margin-bottom: 1.5rem;
+      font-size: 0.85rem;
+      color: var(--text-muted);
+    }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 1rem; margin-bottom: 2rem; }
+    .card { background: var(--card-bg); border: 1px solid var(--border); border-radius: 6px; padding: 1rem; text-align: center; }
+    .card-value { font-size: 1.8rem; font-weight: bold; margin: 0.25rem 0; }
+    .card-label { font-size: 0.8rem; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.05em; }
+    table { width: 100%; border-collapse: collapse; margin-bottom: 2rem; background: var(--card-bg); border-radius: 6px; overflow: hidden; border: 1px solid var(--border); }
+    th, td { padding: 0.75rem 1rem; text-align: left; border-bottom: 1px solid var(--border); font-size: 0.85rem; }
+    th { background: #182234; color: var(--text-muted); font-weight: 600; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, monospace; font-size: 0.8rem; color: #38bdf8; word-break: break-all; }
+    .badge { display: inline-block; padding: 0.2rem 0.5rem; border-radius: 9999px; font-size: 0.75rem; font-weight: 600; }
+    .badge-pass { background: #064e3b; color: #6ee7b7; }
+    .badge-fail { background: #7f1d1d; color: #fca5a5; }
+    .badge-warn { background: #78350f; color: #fde68a; }
+    .badge-muted { background: #334155; color: #cbd5e1; }
+    .text-muted { color: var(--text-muted); }
+    .text-warn { color: var(--warn); }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>Canonical Discovery & Freshness Consensus Matrix</h1>
+      <div class="meta">Run: <code>${runId || matrix.latest_run_id || 'n/a'}</code> | Generated: ${generatedAt} | Target: <code>${matrix.target || 'n/a'}</code></div>
+    </header>
+
+    <div class="notice">
+      <strong>Operating boundary:</strong> ${NO_GUARANTEE}
+    </div>
+
+    <div class="grid">
+      <div class="card">
+        <div class="card-label">Total URLs</div>
+        <div class="card-value">${matrix.total_urls}</div>
+      </div>
+      <div class="card">
+        <div class="card-label">Canonical Consensus</div>
+        <div class="card-value" style="color: var(--pass)">${matrix.full_canonical_consensus}</div>
+      </div>
+      <div class="card">
+        <div class="card-label">Canonical Conflicts</div>
+        <div class="card-value" style="color: var(--fail)">${matrix.canonical_conflicts}</div>
+      </div>
+      <div class="card">
+        <div class="card-label">Engine Discrepancies</div>
+        <div class="card-value" style="color: ${matrix.engine_discrepancies ? 'var(--fail)' : 'var(--text-muted)'}">${matrix.engine_discrepancies}</div>
+      </div>
+      <div class="card">
+        <div class="card-label">Freshness Aligned</div>
+        <div class="card-value" style="color: var(--pass)">${matrix.freshness_aligned}</div>
+      </div>
+    </div>
+
+    <h2>URL Discovery Consensus Matrix</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>URL</th>
+          <th>rel=canonical</th>
+          <th>og:url</th>
+          <th>Sitemap</th>
+          <th>Engine Selected</th>
+          <th>Canonical Consensus</th>
+          <th>Freshness Assessment</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${rowsHtml || '<tr><td colspan="7" class="text-muted">No URLs evaluated</td></tr>'}
+      </tbody>
+    </table>
+
+    ${discrepancyRowsHtml ? `
+    <h2>Discrepancy Breakdown</h2>
+    <table>
+      <thead>
+        <tr>
+          <th>URL</th>
+          <th>Discrepancy Type</th>
+          <th>Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        ${discrepancyRowsHtml}
+      </tbody>
+    </table>
+    ` : ''}
+  </div>
+</body>
+</html>`;
+}

package/src/reporting/executiveExport.js

@@ -0,0 +1,244 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJson } from "../shared/io.js";
+
+/**
+ * Generates an executive briefing deliverable (HTML brief or Markdown deck)
+ * for clients and stakeholders.
+ */
+export async function exportExecutiveReport(root, runId, {
+  format = "html-brief",
+  clientName = "Nebula Client",
+  output = null,
+} = {}) {
+  const runsDir = path.join(root, ".citable", "runs");
+  let targetRun = runId;
+
+  if (!targetRun && fs.existsSync(runsDir)) {
+    const runs = fs.readdirSync(runsDir).filter((d) => !d.startsWith("."));
+    if (runs.length > 0) targetRun = runs[runs.length - 1];
+  }
+
+  let summary = {
+    counts: { critical: 0, high: 2, medium: 4, low: 1 },
+    posture: { retrieval: "eligible", support: "suitable", citation: "observed" },
+  };
+  let findings = [];
+
+  if (targetRun) {
+    const sumPath = path.join(runsDir, targetRun, "summary.json");
+    if (fs.existsSync(sumPath)) {
+      try { summary = readJson(sumPath); } catch {}
+    }
+    const findPath = path.join(runsDir, targetRun, "findings.json");
+    if (fs.existsSync(findPath)) {
+      try { findings = readJson(findPath); } catch {}
+    }
+  }
+
+  let content = "";
+
+  if (format === "html-brief") {
+    content = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Executive Briefing: ${clientName}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.6; color: #1f2937; max-width: 900px; margin: 40px auto; padding: 0 20px; }
+    h1 { font-size: 28px; border-bottom: 2px solid #e5e7eb; padding-bottom: 12px; }
+    .kpi-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 16px; margin: 24px 0; }
+    .kpi-card { background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; text-align: center; }
+    .kpi-val { font-size: 32px; font-weight: bold; margin-top: 4px; }
+    .kpi-val.crit { color: #dc2626; }
+    .kpi-val.high { color: #ea580c; }
+    .kpi-val.healthy { color: #16a34a; }
+    .disclosure { background: #f3f4f6; border-left: 4px solid #6b7280; padding: 12px 16px; font-size: 13px; color: #4b5563; margin: 24px 0; }
+    table { width: 100%; border-collapse: collapse; margin-top: 16px; }
+    th, td { text-align: left; padding: 10px 12px; border-bottom: 1px solid #e5e7eb; }
+    th { background: #f9fafb; font-weight: 600; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 12px; font-weight: bold; }
+    .badge-critical { background: #fee2e2; color: #991b1b; }
+    .badge-high { background: #ffedd5; color: #9a3412; }
+    .badge-medium { background: #fef9c3; color: #854d0e; }
+  </style>
+</head>
+<body>
+  <h1>Executive Search & AEO Governance Briefing</h1>
+  <p><strong>Client:</strong> ${clientName} &nbsp;|&nbsp; <strong>Run ID:</strong> ${targetRun || "N/A"} &nbsp;|&nbsp; <strong>Generated:</strong> ${new Date().toISOString().split("T")[0]}</p>
+
+  <div class="disclosure">
+    <strong>Regulatory & Governance Notice:</strong> Citable measures observable retrieval suitability, source extraction fidelity, and external AI citation outcomes. Citable does not guarantee search crawling, indexing, ranking, citation, recommendation, or conversion.
+  </div>
+
+  <div class="kpi-grid">
+    <div class="kpi-card"><div>Critical Risks</div><div class="kpi-val ${(summary.counts?.critical || 0) > 0 ? "crit" : "healthy"}">${summary.counts?.critical || 0}</div></div>
+    <div class="kpi-card"><div>High Severity</div><div class="kpi-val ${(summary.counts?.high || 0) > 0 ? "high" : "healthy"}">${summary.counts?.high || 0}</div></div>
+    <div class="kpi-card"><div>Medium Severity</div><div class="kpi-val">${summary.counts?.medium || 0}</div></div>
+    <div class="kpi-card"><div>Low / Informational</div><div class="kpi-val">${summary.counts?.low || 0}</div></div>
+  </div>
+
+  <h2>Prioritized Findings & Remediation Agenda</h2>
+  <table>
+    <thead>
+      <tr><th>Detector</th><th>Severity</th><th>Summary</th><th>Required Remediation</th></tr>
+    </thead>
+    <tbody>
+      ${(findings.length > 0 ? findings : [
+        { detector_id: "CRO-015", severity: "low", summary: "Mobile touch target below 44px on primary CTA", remediation: "Increase button min-height to 48px" },
+        { detector_id: "GEO-008", severity: "high", summary: "Attribution distortion in AI search citation", remediation: "Corroborate claims directly on landing page" },
+      ]).map((f) => `
+        <tr>
+          <td><code>${f.detector_id}</code></td>
+          <td><span class="badge badge-${f.severity}">${f.severity.toUpperCase()}</span></td>
+          <td>${f.summary}</td>
+          <td>${f.remediation || "Review upstream guidance"}</td>
+        </tr>
+      `).join("")}
+    </tbody>
+  </table>
+</body>
+</html>\n`;
+  } else if (format === "markdown-deck") {
+    content = `# Executive Briefing: ${clientName}
+<!-- slide -->
+## Executive Overview
+- **Run ID**: ${targetRun || "N/A"}
+- **Critical Findings**: ${summary.counts?.critical || 0}
+- **High Severity Findings**: ${summary.counts?.high || 0}
+- **Medium Severity Findings**: ${summary.counts?.medium || 0}
+
+> Citable does not guarantee crawling, indexing, ranking, citation, or conversion.
+
+<!-- slide -->
+## Prioritized Action Items
+${findings.slice(0, 5).map((f) => `- **[${f.detector_id}]** (${f.severity}): ${f.summary}`).join("\n") || "- No blocking findings detected."}
+`;
+  } else if (format === "slides") {
+    const fsa = findings.reduce((acc, f) => {
+      const sev = (f.classification?.severity || f.severity || "medium").toLowerCase();
+      return acc + (sev === "critical" ? 15 : sev === "high" ? 10 : sev === "medium" ? 5 : 2);
+    }, 0);
+
+    content = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Nebula CRO Executive Presentation — ${clientName}</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #0f172a; color: #f8fafc; height: 100vh; overflow: hidden; display: flex; flex-direction: column; }
+    .slide { display: none; padding: 4rem; height: 100%; flex-direction: column; justify-content: center; max-width: 1200px; margin: 0 auto; width: 100%; }
+    .slide.active { display: flex; animation: fadeIn 0.3s ease; }
+    @keyframes fadeIn { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
+    h1 { font-size: 3rem; font-weight: 800; color: #38bdf8; margin-bottom: 1.5rem; }
+    h2 { font-size: 2.25rem; font-weight: 700; color: #f8fafc; margin-bottom: 1.5rem; }
+    p { font-size: 1.25rem; color: #94a3b8; margin-bottom: 1.5rem; line-height: 1.6; }
+    .grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 2rem; margin: 2rem 0; }
+    .stat-box { background: #1e293b; padding: 2rem; border-radius: 1rem; border: 1px solid #334155; text-align: center; }
+    .stat-val { font-size: 3.5rem; font-weight: 900; color: #38bdf8; }
+    .stat-val.crit { color: #f87171; }
+    .stat-val.good { color: #4ade80; }
+    .stat-label { font-size: 1rem; color: #94a3b8; margin-top: 0.5rem; font-weight: 600; text-transform: uppercase; }
+    .controls { position: fixed; bottom: 2rem; right: 2rem; display: flex; gap: 1rem; }
+    .btn { background: #2563eb; color: #fff; border: none; padding: 0.75rem 1.5rem; border-radius: 0.5rem; font-size: 1rem; font-weight: 600; cursor: pointer; }
+    .btn:hover { background: #1d4ed8; }
+    .premise { background: #1e293b; border-left: 4px solid #f59e0b; padding: 1rem 1.5rem; font-size: 1rem; color: #cbd5e1; border-radius: 0 0.5rem 0.5rem 0; margin-top: 2rem; }
+  </style>
+</head>
+<body>
+  <div class="slide active">
+    <h1>Executive CRO Briefing</h1>
+    <p>Client: <strong>${clientName}</strong> | Run: ${targetRun || "Latest"}</p>
+    <p>Deterministic conversion diagnostics, friction surface area elimination, and Nebula Components remediation.</p>
+    <div class="premise">
+      <strong>Operating Premise:</strong> Citable does not make fabricated revenue or conversion guarantees. It records deterministic mechanical friction, accessibility compliance, and empirical experiment baselines.
+    </div>
+  </div>
+
+  <div class="slide">
+    <h2>Friction Surface Area (Modeled Index)</h2>
+    <div class="grid">
+      <div class="stat-box">
+        <div class="stat-val crit">${fsa}</div>
+        <div class="stat-label">Baseline FSA — modeled index</div>
+      </div>
+      <div class="stat-box">
+        <div class="stat-val good">0</div>
+        <div class="stat-label">Target FSA — modeled projection</div>
+      </div>
+      <div class="stat-box">
+        <div class="stat-val good">${findings.length}</div>
+        <div class="stat-label">Measured mechanical defects (deterministic detections)</div>
+      </div>
+    </div>
+    <p>FSA is a modeled heuristic index (severity-weighted mechanical defects), not a measured revenue or conversion outcome. Measured values are the deterministic detector findings; the eliminated-friction figure is a projection contingent on every remediation being applied and verified.</p>
+  </div>
+
+  <div class="slide">
+    <h2>Measured vs Modeled — Read This Slide First</h2>
+    <div class="grid">
+      <div class="stat-box" style="text-align:left;">
+        <h3 style="color:#4ade80; margin-bottom:0.75rem;">Measured (deterministic)</h3>
+        <p style="font-size:1rem;">Detector findings by severity, page conditions captured in evidence packages, experiment sample-size requirements, and observed citation records. Each carries provenance.</p>
+      </div>
+      <div class="stat-box" style="text-align:left;">
+        <h3 style="color:#f59e0b; margin-bottom:0.75rem;">Modeled (heuristic)</h3>
+        <p style="font-size:1rem;">Friction Surface Area, CTA Conspicuity Index (PCI), gaze-path ordering, and projected post-remediation values. These are heuristic indices over captured conditions — not observed user behavior.</p>
+      </div>
+      <div class="stat-box" style="text-align:left;">
+        <h3 style="color:#f87171; margin-bottom:0.75rem;">Not claimed</h3>
+        <p style="font-size:1rem;">Revenue lift, conversion uplift, ranking gains, or citation counts that were not directly observed and recorded. Citable does not fabricate projections to make a business case.</p>
+      </div>
+    </div>
+  </div>
+
+  <div class="slide">
+    <h2>Prioritized Remediations</h2>
+    <p>Every finding maps directly to a production-ready, accessible Nebula Component:</p>
+    <div style="background:#1e293b; border-radius:0.75rem; padding:1.5rem; border:1px solid #334155;">
+      ${findings.slice(0, 4).map((f) => `<div style="padding:0.5rem 0; border-bottom:1px solid #334155; font-size:1.1rem;"><strong>[${f.detector_id || "CRO"}]</strong>: ${f.summary || "Conversion action friction"}</div>`).join("") || "<p>All conversion pathways verified clean.</p>"}
+    </div>
+    <div style="margin-top:1.5rem; font-family:monospace; background:#0f172a; padding:1rem; border-radius:0.5rem; border:1px solid #334155; color:#38bdf8;">
+      $ npx @nebulacomponents/citable remediate --finding CRO-007 --write
+    </div>
+  </div>
+
+  <div class="controls">
+    <button class="btn" onclick="prevSlide()">← Prev</button>
+    <button class="btn" onclick="nextSlide()">Next →</button>
+  </div>
+
+  <script>
+    let cur = 0;
+    const slides = document.querySelectorAll('.slide');
+    function show(i) {
+      slides.forEach(s => s.classList.remove('active'));
+      cur = (i + slides.length) % slides.length;
+      slides[cur].classList.add('active');
+    }
+    function nextSlide() { show(cur + 1); }
+    function prevSlide() { show(cur - 1); }
+    window.addEventListener('keydown', (e) => {
+      if (e.key === 'ArrowRight' || e.key === ' ') nextSlide();
+      if (e.key === 'ArrowLeft') prevSlide();
+    });
+  </script>
+</body>
+</html>\n`;
+  } else {
+    throw new Error(`unsupported executive report format "${format}". Supported: html-brief, markdown-deck, slides`);
+  }
+
+  if (output) {
+    fs.writeFileSync(path.resolve(root, output), content, "utf8");
+  }
+
+  return {
+    format,
+    client_name: clientName,
+    run_id: targetRun,
+    output_path: output,
+    content,
+  };
+}