@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/commands/auditBacklinks.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseCsv } from 'csv-parse/sync';
+import { auditBacklinkProfile } from '../analysis/offpage.js';
+
+/**
+ * `citable audit backlinks` — audit off-page authority and identify toxic domains.
+ */
+export async function auditBacklinks(root, { input, target, minSeverity } = {}) {
+  let backlinks = [];
+
+  if (input) {
+    const filePath = path.resolve(root, input);
+    if (!fs.existsSync(filePath)) throw new Error(`input file not found: ${input}`);
+    const raw = fs.readFileSync(filePath, 'utf8');
+
+    if (filePath.endsWith('.csv')) {
+      const records = parseCsv(raw, { columns: true, skip_empty_lines: true });
+      backlinks = records.map((r) => ({
+        source_url: r.source_url || r.Source || r.url || r.URL,
+        target_url: r.target_url || r.Target || r.target,
+        anchor_text: r.anchor_text || r.Anchor || r.anchor || '',
+        rel: r.rel || r.Rel || r.type || '',
+        source_ip: r.source_ip || r.IP || r.ip || null,
+      }));
+    } else {
+      const parsed = JSON.parse(raw);
+      backlinks = Array.isArray(parsed) ? parsed : (parsed.backlinks || []);
+    }
+  } else {
+    // Check if there is a competitor or backlink import in .citable/
+    const defaultFile = path.join(root, '.citable', 'backlinks.json');
+    if (fs.existsSync(defaultFile)) {
+      const parsed = JSON.parse(fs.readFileSync(defaultFile, 'utf8'));
+      backlinks = Array.isArray(parsed) ? parsed : (parsed.backlinks || []);
+    } else {
+      throw new Error('audit backlinks requires --input <backlinks.json|csv> or .citable/backlinks.json');
+    }
+  }
+
+  const result = auditBacklinkProfile(backlinks, { targetDomain: target });
+  return result;
+}
+
+/**
+ * Format terminal output for `citable audit backlinks`
+ */
+export function formatBacklinksOutput(r) {
+  const lines = [
+    `Off-Page Authority & Toxic Domain Audit`,
+    `=======================================`,
+    `Profile Health: ${r.profile_health.toUpperCase()}`,
+    `Total Backlinks: ${r.summary.total_backlinks} across ${r.summary.total_referring_domains} referring domain(s)`,
+    `Dofollow: ${r.summary.dofollow_count} | Nofollow: ${r.summary.nofollow_count} | UGC: ${r.summary.ugc_count} | Sponsored: ${r.summary.sponsored_count}`,
+    `Deep Link Ratio: ${r.summary.deep_link_ratio_pct}%`,
+    ``,
+    `ANCHOR TEXT PROFILE:`,
+    `  Branded Anchors: ${r.anchor_profile.branded_pct}%`,
+    `  Commercial Exact Match: ${r.anchor_profile.commercial_exact_match_pct}% (Risk: ${r.anchor_profile.over_optimization_risk.toUpperCase()})`,
+    ``,
+    `TOXIC DOMAIN IDENTIFICATION:`,
+    `  Flagged Toxic Domains: ${r.summary.toxic_domains_count} (Critical: ${r.summary.critical_risk_domains}, High: ${r.summary.high_risk_domains})`,
+  ];
+
+  if (r.toxic_domains.length) {
+    lines.push(``, `Flagged Risk Candidates:`);
+    for (const d of r.toxic_domains.slice(0, 15)) {
+      lines.push(`  [${d.risk_tier.toUpperCase()}] ${d.domain}`);
+      for (const reason of d.reasons) lines.push(`    - ${reason}`);
+      if (d.anchors.length) lines.push(`    - Sample anchors: "${d.anchors.join('", "')}"`);
+    }
+    lines.push(``, `Google Search Console Disavow Syntax Preview:`);
+    lines.push(r.disavow_export.split('\n').slice(0, 10).join('\n'));
+  } else {
+    lines.push(`  No toxic domain risk patterns detected in profile.`);
+  }
+
+  return lines.join('\n');
+}

package/src/commands/ciWorkflow.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function generateCiWorkflow() {
+  return `name: Citable CRO Funnel Sentinel
+on:
+  pull_request:
+    branches: [main, master]
+  push:
+    branches: [main, master]
+
+jobs:
+  cro-audit:
+    name: CRO Friction & Funnel Drift Sentinel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Run Component Static Linter
+        run: npx @nebulacomponents/citable lint components src/
+
+      - name: Run Strict Shift-Left CRO Audit Gate
+        run: npx @nebulacomponents/citable audit cro --strict
+`;
+}
+
+export function formatPrReviewComment(findings = []) {
+  if (findings.length === 0) {
+    return '### ✅ Citable CRO Sentinel: All conversion funnels and components verified clean with zero detected friction.';
+  }
+
+  const lines = [
+    '### ⚠️ Citable CRO Sentinel: Friction Detected in Pull Request',
+    '',
+    `Found **${findings.length}** conversion action defect(s) violating UX or funnel continuity criteria:`,
+    '',
+  ];
+
+  for (const f of findings) {
+    lines.push(`- **[${f.detector_id || 'CRO'}]** (${f.severity || 'medium'}): ${f.summary || f.observation?.summary}`);
+    if (f.remediation) {
+      lines.push(`  - *Remediation*: ${f.remediation}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('#### Recommended 1-Click Remediation');
+  lines.push('Run the following locally to patch components automatically with accessible Nebula Components:');
+  lines.push('```bash');
+  lines.push('npx @nebulacomponents/citable remediate --finding CRO-007 --write');
+  lines.push('```');
+
+  return lines.join('\n');
+}

package/src/commands/compatibility.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { readJson, nowIso } from '../shared/io.js';
+import { buildContext } from './context.js';
+import { runDetectors } from '../detectors/framework.js';
+import { selectDetectors, ALL_DETECTORS } from '../detectors/index.js';
+
+const PKG = readJson(new URL('../../package.json', import.meta.url));
+const SCHEMA_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'schemas');
+
+function checkModule(name) {
+  try {
+    execFileSync(process.execPath, ['--input-type=module', '-e', `await import('${name}')`], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 15000,
+      env: { ...process.env, NODE_OPTIONS: '' },
+    });
+    return { present: true, importable: true };
+  } catch (err) {
+    const notFound = /Cannot find (package|module)/.test(String(err.stderr || err.message));
+    return { present: !notFound, importable: false, note: notFound ? 'not installed (optional peer dependency)' : 'installed but failed to import — adapter mismatch' };
+  }
+}
+
+function engineSatisfied(range, actual) {
+  const m = range.match(/>=\s*(\d+)/);
+  if (!m) return { satisfied: true, note: `unrecognized range "${range}"` };
+  const major = Number.parseInt(actual.split('.')[0], 10);
+  return { satisfied: major >= Number(m[1]), note: `requires Node >= ${m[1]}, found ${actual}` };
+}
+
+/**
+ * `citable compatibility` — pre-flight diagnosis of environment, optional
+ * adapters, project framework, registry freshness, and generated-code
+ * constraints. Every check states its evidence; absence of an optional
+ * adapter is reported, never assumed.
+ */
+export async function compatibilityCommand(root, options = {}) {
+  const checks = [];
+
+  const engine = engineSatisfied(PKG.engines?.node || '>=0', process.versions.node);
+  checks.push({
+    check_id: 'NODE-ENGINE',
+    passed: engine.satisfied,
+    severity: engine.satisfied ? 'pass' : 'blocker',
+    detail: engine.note,
+  });
+
+  const peers = ['playwright', 'lighthouse', 'chrome-launcher', 'tesseract.js'];
+  const adapterResults = {};
+  for (const name of peers) {
+    const declared = Boolean(PKG.peerDependencies?.[name]);
+    const res = checkModule(name);
+    adapterResults[name] = { declared_optional_peer: declared, ...res };
+    checks.push({
+      check_id: `ADAPTER-${name.toUpperCase().replace('.', '-')}`,
+      passed: true, // absence of an optional adapter is a report, not a failure
+      severity: res.importable ? 'pass' : 'advisory',
+      detail: res.importable ? `${name} importable` : `${name}: ${res.note}`,
+    });
+  }
+
+  // Browser dependency: presence of a Chrome executable is only verified when
+  // chrome-launcher is importable; otherwise reported as unknown (fail open in
+  // reporting, fail closed in any feature that needs it).
+  if (adapterResults['chrome-launcher']?.importable) {
+    let browser = 'unknown';
+    try {
+      const mod = await import('chrome-launcher');
+      browser = mod.getChromePath?.() ? 'found' : 'not found';
+    } catch { browser = 'lookup failed'; }
+    checks.push({
+      check_id: 'BROWSER-CHROME',
+      passed: browser === 'found',
+      severity: browser === 'found' ? 'pass' : 'advisory',
+      detail: `Chrome executable: ${browser} (required for observe render / preview evidence; presence does not prove a successful launch)`,
+    });
+  }
+
+  // Project framework detection (for remediation format matching)
+  let frameworks = [];
+  const pkgFile = path.join(root, 'package.json');
+  if (fs.existsSync(pkgFile)) {
+    try {
+      const deps = { ...readJson(pkgFile).dependencies, ...readJson(pkgFile).devDependencies };
+      if (deps.next) frameworks.push('next');
+      if (deps.react) frameworks.push('react');
+      if (deps.vue || deps.nuxt) frameworks.push('vue');
+      if (deps.svelte || deps['@sveltejs/kit']) frameworks.push('svelte');
+    } catch { /* unreadable package.json reported below */ }
+  }
+  checks.push({
+    check_id: 'PROJECT-FRAMEWORK',
+    passed: true,
+    severity: 'pass',
+    detail: frameworks.length ? `detected: ${frameworks.join(', ')}; remediation templates available: react, vue, html` : 'no framework dependencies detected; component templates remain available as standalone HTML',
+  });
+
+  // Registry freshness
+  const citableDir = path.join(root, '.citable');
+  if (!fs.existsSync(citableDir)) {
+    checks.push({ check_id: 'REGISTRIES-PRESENT', passed: false, severity: 'advisory', detail: '.citable/ not found — run citable init' });
+  } else {
+    const yamlFiles = fs.readdirSync(citableDir).filter((f) => f.endsWith('.yaml'));
+    checks.push({ check_id: 'REGISTRIES-PRESENT', passed: true, severity: 'pass', detail: `${yamlFiles.length} registry/config YAML file(s) found; run citable validate registries for full referential validation` });
+    const registrySchemas = fs.readdirSync(SCHEMA_DIR).filter((f) => f.endsWith('.schema.json'));
+    checks.push({
+      check_id: 'SCHEMA-CONTRACTS',
+      passed: true,
+      severity: 'pass',
+      detail: `${registrySchemas.length} schema contracts shipped by citable ${PKG.version}; registries validated against them by citable validate registries`,
+    });
+  }
+
+  // Generated-code constraints (advisory, documented limits)
+  const edgeDir = path.join(root, '.citable', 'edge');
+  if (fs.existsSync(edgeDir)) {
+    for (const f of fs.readdirSync(edgeDir)) {
+      const size = fs.statSync(path.join(edgeDir, f)).size;
+      const limit = 1024 * 1024;
+      checks.push({
+        check_id: `EDGE-SIZE-${f}`,
+        passed: size <= limit,
+        severity: size <= limit ? 'pass' : 'blocker',
+        detail: `${f}: ${(size / 1024).toFixed(1)} KiB — Cloudflare Workers free plan limits the worker to ~1 MiB before compression (verify against your plan; this is a documented platform limit, not a measurement)`,
+      });
+    }
+  }
+
+  const blockers = checks.filter((c) => c.severity === 'blocker' && !c.passed);
+  return {
+    ok: blockers.length === 0,
+    timestamp: nowIso(),
+    tool_version: PKG.version,
+    node: process.versions.node,
+    engines: PKG.engines?.node || null,
+    framework: frameworks,
+    adapters: adapterResults,
+    checks,
+    blocker_count: blockers.length,
+    note: 'compatibility reports current environment facts; it cannot prove that a browser launch, API authorization, or collection will succeed',
+  };
+}
+
+/**
+ * `citable verify page <page>` — run the full deterministic detector set
+ * scoped to one page subject and return a posture verdict.
+ * pass = no detector currently reports this page; never an outcome guarantee.
+ */
+export async function verifyPage(root, pageRef, { target, baseUrl, refDate, viewport = null } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate, viewport });
+  if (!ctx.site) throw new Error('verify page requires a site target (built output directory or URL)');
+  const norm = (s) => String(s || '').replace(/\/+$/, '');
+  const candidates = [pageRef, pageRef.replace(/\/index\.html?$/i, '/'), pageRef.replace(/^\/+/, '')];
+  const wanted = pageRef.startsWith('/') ? `${norm(ctx.site.baseUrl)}${pageRef}` : pageRef;
+  const page = ctx.site.pages.find((p) => {
+    if (norm(p.url) === norm(wanted) || p.sourceFile === pageRef) return true;
+    if (candidates.some((c) => norm(p.url) === norm(pageRef.startsWith('/') ? `${norm(ctx.site.baseUrl)}${c}` : c))) return true;
+    if (norm(p.url).endsWith(norm(wanted))) return true;
+    return false;
+  });
+  if (!page) {
+    throw new Error(`page not found in audited output: ${pageRef}`);
+  }
+
+  const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(
+    selectDetectors({ namespaces: ALL_DETECTORS.map((d) => d.namespace).filter((v, i, a) => a.indexOf(v) === i) }),
+    { ...ctx, site: { ...ctx.site, pages: [page] } }
+  );
+  const pageFindings = findings.filter((f) => (f.subject?.url === page.url) || (f.subject?.identifier === page.url) || (f.subject?.source_file && f.subject.source_file === page.sourceFile));
+
+  const bySeverity = { critical: 0, high: 0, medium: 0, low: 0, informational: 0 };
+  for (const f of pageFindings) {
+    const s = f.classification?.severity;
+    if (s in bySeverity) bySeverity[s]++;
+  }
+  const status = errors.length ? 'blocked' : (bySeverity.critical > 0 || bySeverity.high > 0) ? 'attention' : pageFindings.length ? 'attention' : 'pass';
+
+  return {
+    page: page.url,
+    source_file: page.sourceFile,
+    status,
+    finding_count: pageFindings.length,
+    by_severity: bySeverity,
+    findings: pageFindings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      confidence: f.classification.confidence,
+      summary: f.observation.summary,
+      provenance: f.provenance,
+    })),
+    provenance: {
+      command: 'verify page',
+      timestamp: nowIso(),
+      tool_version: PKG.version,
+      viewport: ctx.viewport ?? null,
+      detectors_run: detectorsRun,
+      detectors_skipped: detectorsSkipped,
+      errors,
+      definition: 'pass means no detector currently reports this page; it is not a guarantee of crawling, indexing, ranking, citation, or conversion',
+    },
+  };
+}

package/src/commands/context.js

@@ -5,7 +5,7 @@ import { loadRegistries } from '../registries/index.js';
 import { buildSiteFromDir, buildSiteFromUrl } from '../extractor/site.js';
 
 /** Assemble the shared execution context used by audit-family commands. */
-export async function buildContext(root, { target, baseUrl, refDate } = {}) {
+export async function buildContext(root, { target, baseUrl, refDate, viewport = null } = {}) {
   const warnings = [];
   const configFile = path.join(root, '.citable', 'config.yaml');
   const config = fs.existsSync(configFile) ? readYaml(configFile) : { version: 1 };
@@ -71,6 +71,7 @@ export async function buildContext(root, { target, baseUrl, refDate } = {}) {
     observations: observations.length ? observations : null,
     snapshots,
     refDate: parseRefDate(refDate),
+    viewport,
     hashPage: (p) => sha256(p.text),
     warnings,
   };

package/src/commands/croBacklog.js

@@ -0,0 +1,182 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from '../shared/io.js';
+
+/**
+ * Generate a prioritized A/B experiment backlog from CRO audit findings.
+ */
+export function generateExperimentBacklog(findings = [], { dailyVisitors = 500, baselineRate = 0.02, defaultMde = 0.12 } = {}) {
+  const croFindings = findings.filter((f) => (f.detector_id || '').startsWith('CRO-') || f.discipline?.includes('cro'));
+
+  const backlog = [];
+
+  for (let i = 0; i < croFindings.length; i++) {
+    const f = croFindings[i];
+    const ns = f.detector_id;
+    const pageUrl = f.subject?.identifier || f.subject?.url || '/';
+
+    let title = '';
+    let change = '';
+    let rationale = f.observation?.summary || 'Friction detected on conversion pathway';
+    let expectedMde = defaultMde;
+    let primaryMetric = 'conversion_rate';
+    let secondaryMetrics = ['bounce_rate', 'form_completion_rate'];
+
+    switch (ns) {
+      case 'CRO-001':
+        title = 'Prominent Interactive Hero CTA Deployment';
+        change = 'Deploy prominent, high-contrast primary CTA button matching declared conversion intent';
+        expectedMde = 0.15;
+        break;
+      case 'CRO-002':
+        title = 'Form Friction Reduction & Progressive Profiling';
+        change = 'Condense lead capture form from >6 fields to 3 essential fields with progressive disclosure';
+        expectedMde = 0.20;
+        primaryMetric = 'lead_submission_rate';
+        break;
+      case 'CRO-005':
+        title = 'Ad-to-Landing Scent Match Alignment';
+        change = 'Align above-the-fold H1 headline and value proposition directly with title and ad intent';
+        expectedMde = 0.12;
+        break;
+      case 'CRO-006':
+        title = 'Proximate Trust Proof & Security Badges';
+        change = 'Position verified customer logo bar and security certification badges immediately below primary CTA';
+        expectedMde = 0.10;
+        break;
+      case 'CRO-007':
+        title = 'HTML5 Autocomplete Form Optimization';
+        change = 'Inject standard HTML5 autocomplete attributes on all identity, email, and telephone fields';
+        expectedMde = 0.08;
+        primaryMetric = 'form_completion_speed';
+        break;
+      case 'CRO-010':
+        title = 'Hero Choice Overload Elimination';
+        change = 'Consolidate competing hero buttons into exactly ONE dominant primary action and one text link';
+        expectedMde = 0.14;
+        break;
+      case 'CRO-012':
+        title = 'High-Intent Value CTA Microcopy';
+        change = 'Replace generic "Submit" or "Learn More" with action-oriented value copy ("Get My Free Analysis")';
+        expectedMde = 0.10;
+        break;
+      case 'CRO-013':
+        title = 'Enclosed Distraction-Free Checkout Funnel';
+        change = 'Remove global header navigation and external outbound links on checkout/pricing steps';
+        expectedMde = 0.15;
+        break;
+      case 'CRO-021':
+        title = 'Express Payment Wallet Integration';
+        change = 'Implement 1-click Apple Pay, Google Pay, and PayPal express wallet buttons';
+        expectedMde = 0.18;
+        primaryMetric = 'checkout_conversion_rate';
+        break;
+      default:
+        title = `Remediation for ${f.name || ns}`;
+        change = f.remediation?.preferred || 'Implement recommended conversion design system component';
+        expectedMde = defaultMde;
+    }
+
+    // Falsifiable hypothesis formulation
+    const hypothesis = `If we ${change} on ${pageUrl}, then ${primaryMetric} will increase by at least ${Math.round(expectedMde * 100)}%, because ${rationale.toLowerCase()}.`;
+
+    // Sample size calculation (two-tailed alpha=0.05, power=0.80)
+    const p1 = baselineRate;
+    const p2 = p1 * (1 + expectedMde);
+    const pBar = (p1 + p2) / 2;
+    const zAlpha = 1.96;
+    const zBeta = 0.8416;
+    const num = Math.pow(zAlpha * Math.sqrt(2 * pBar * (1 - pBar)) + zBeta * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2)), 2);
+    const den = Math.pow(p2 - p1, 2);
+    const nPerVariant = Math.ceil(num / den);
+    const totalSample = nPerVariant * 2;
+    const estDays = Math.max(7, Math.ceil(totalSample / dailyVisitors));
+
+    // Impact, Effort, Confidence (ICE)
+    const impact = Math.min(10, Math.max(4, Math.round(expectedMde * 50)));
+    const effort = ['CRO-007', 'CRO-012', 'CRO-005'].includes(ns) ? 2 : ['CRO-001', 'CRO-006', 'CRO-010'].includes(ns) ? 4 : 6;
+    const confidence = f.classification?.deterministic ? 9 : 7;
+    const iceScore = Math.round(((impact * confidence) / effort) * 10) / 10;
+
+    backlog.push({
+      experiment_id: `EXP-CRO-${String(i + 1).padStart(3, '0')}`,
+      title,
+      detector_id: ns,
+      target_page: pageUrl,
+      hypothesis,
+      discipline: ['cro'],
+      primary_metric: primaryMetric,
+      secondary_metrics: secondaryMetrics,
+      statistical_setup: {
+        baseline_rate_pct: Math.round(baselineRate * 1000) / 10,
+        expected_mde_pct: Math.round(expectedMde * 100),
+        confidence_level_pct: 95,
+        power_pct: 80,
+        sample_size_per_variant: nPerVariant,
+        total_sample_required: totalSample,
+        estimated_duration_days: estDays,
+        daily_visitors: dailyVisitors,
+      },
+      guardrails: [
+        'SEO Retention: Variant must preserve all canonical tags, JSON-LD structured data, and meta robots tags',
+        'Performance Guardrail: Mobile LCP must not degrade by > 250ms; CLS must remain <= 0.10',
+        'Secondary Safety Metric: Bounce rate must not increase by > 5% relative to control',
+      ],
+      stopping_criteria: [
+        'Minimum Duration Lock: Run for at least 7 full days to account for day-of-week seasonality, regardless of early p-values',
+        'Sample Ratio Mismatch (SRM): Terminate immediately if traffic allocation deviates significantly (chi-square p < 0.001)',
+        'Maximum Duration Cap: Stop and conclude as inconclusive if required sample size is not reached within 45 days',
+      ],
+      ice_prioritization: {
+        impact,
+        effort,
+        confidence,
+        ice_score: iceScore,
+        quadrant: impact >= 6 && effort <= 4 ? 'quick_wins' : impact >= 6 ? 'strategic_bets' : 'low_hanging_fruit',
+      },
+      status: 'draft',
+    });
+  }
+
+  // Sort by ICE score descending
+  backlog.sort((a, b) => b.ice_prioritization.ice_score - a.ice_prioritization.ice_score);
+
+  return {
+    fact_status: 'experiment_backlog_projection',
+    total_experiments: backlog.length,
+    summary: {
+      quick_wins: backlog.filter((e) => e.ice_prioritization.quadrant === 'quick_wins').length,
+      strategic_bets: backlog.filter((e) => e.ice_prioritization.quadrant === 'strategic_bets').length,
+      low_hanging_fruit: backlog.filter((e) => e.ice_prioritization.quadrant === 'low_hanging_fruit').length,
+    },
+    experiments: backlog,
+  };
+}
+
+/**
+ * Format Experiment Backlog as Markdown
+ */
+export function formatBacklogMarkdown(backlog) {
+  const lines = [
+    `# Conversion Experimentation Backlog & Hypothesis Register`,
+    `=========================================================`,
+    `Total Hypotheses: ${backlog.total_experiments} | Quick Wins: ${backlog.summary.quick_wins} | Strategic Bets: ${backlog.summary.strategic_bets}`,
+    ``,
+    `Methodology: Every experiment requires a falsifiable hypothesis, statistical power calculations, SEO guardrails, and stopping criteria.`,
+    ``,
+  ];
+
+  for (const exp of backlog.experiments) {
+    lines.push(`## [${exp.ice_prioritization.quadrant.toUpperCase()}] ${exp.experiment_id}: ${exp.title}`);
+    lines.push(`- **Target Surface**: \`${exp.target_page}\` (Trigger: \`${exp.detector_id}\`)`);
+    lines.push(`- **Falsifiable Hypothesis**: "${exp.hypothesis}"`);
+    lines.push(`- **Primary Metric**: \`${exp.primary_metric}\` | **Expected MDE**: +${exp.statistical_setup.expected_mde_pct}%`);
+    lines.push(`- **Statistical Blueprint**: ${exp.statistical_setup.sample_size_per_variant.toLocaleString()} visitors/variant (~${exp.statistical_setup.estimated_duration_days} days at ${exp.statistical_setup.daily_visitors} visitors/day, 80% power @ 95% conf)`);
+    lines.push(`- **ICE Score**: **${exp.ice_prioritization.ice_score}** (Impact: ${exp.ice_prioritization.impact}/10, Effort: ${exp.ice_prioritization.effort}/10, Conf: ${exp.ice_prioritization.confidence}/10)`);
+    lines.push(`- **Guardrails**: ${exp.guardrails.join('; ')}`);
+    lines.push(`- **Stopping Criteria**: ${exp.stopping_criteria.join('; ')}`);
+    lines.push(``);
+  }
+
+  return lines.join('\n');
+}