@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/commands/experimentGuardrails.js

@@ -0,0 +1,213 @@
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * Experiment safety guardrails.
+ *
+ * Lifecycle statuses are mutually exclusive and explicitly defined:
+ *   planned     — declared, not yet receiving traffic decisions
+ *   running     — receiving traffic, sample below the computed requirement and
+ *                 window not elapsed; no reading may be taken
+ *   inconclusive— window and sample satisfied, effect not statistically
+ *                 significant; absence of evidence is not evidence of absence
+ *   validated   — full window, full sample, no SRM, effect significant at the
+ *                 declared alpha for the primary metric ONLY
+ *
+ * Guardrails fail closed: missing observations, missing windows, or missing
+ * registry context produce `blocked` findings, never a silent pass.
+ */
+
+const MIN_WINDOW_DAYS = 7;
+const SRM_ALPHA = 0.001; // standard SRM alert threshold
+
+/** Abramowitz–Stegun normal CDF. */
+function normalCdf(z) {
+  const t = 1 / (1 + 0.2316419 * Math.abs(z));
+  const d = 0.3989423 * Math.exp((-z * z) / 2);
+  const p = d * t * (0.3193815 + t * (-0.3565638 + t * (1.781478 + t * (-1.821256 + t * 1.330274))));
+  return z >= 0 ? 1 - p : p;
+}
+
+function chiSquare1dfP(chi2) {
+  return 2 * (1 - normalCdf(Math.sqrt(chi2)));
+}
+
+export function requiredSamplePerVariant(baselineRate, mde, alpha = 0.05, power = 0.8) {
+  const p1 = baselineRate;
+  const p2 = p1 * (1 + mde);
+  const pBar = (p1 + p2) / 2;
+  const zAlpha = alpha === 0.01 ? 2.576 : alpha === 0.10 ? 1.645 : 1.96;
+  const zBeta = power === 0.9 ? 1.282 : power === 0.95 ? 1.645 : 0.8416;
+  const numerator = Math.pow(zAlpha * Math.sqrt(2 * pBar * (1 - pBar)) + zBeta * Math.sqrt(p1 * (1 - p1) + p2 * (1 - p2)), 2);
+  const denominator = Math.pow(p2 - p1, 2);
+  return Math.ceil(numerator / denominator);
+}
+
+function windowDays(str) {
+  const m = String(str || '').match(/(\d+)\s*d/i);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Core guardrail evaluation for one experiment record plus optional observed
+ * data: { control, variant, baseline_rate, mde, days_running, revenue_claimed,
+ * other_active_experiments: [{experiment_id, target_page}] }.
+ */
+export function evaluateExperiment(experiment, observed = {}) {
+  const findings = [];
+  const add = (guardrail_id, severity, summary, required_input = null) =>
+    findings.push({ guardrail_id, severity, summary, ...(required_input ? { required_input } : {}) });
+
+  const status = experiment.status || 'draft';
+  const declaredSplit = (experiment.variants || []).length
+    ? (experiment.variants.find((v) => v.traffic_pct) || {}).traffic_pct || 50
+    : 50;
+  const window = windowDays(experiment.evaluation_window || experiment.minimum_observation_window);
+  const baseline = observed.baseline_rate ?? experiment.baseline_rate ?? null;
+  const mde = observed.mde ?? experiment.mde ?? null;
+
+  // Underpowered / required sample
+  let requiredN = null;
+  if (baseline > 0 && baseline < 1 && mde > 0) {
+    requiredN = requiredSamplePerVariant(baseline, mde);
+    if (window && window < MIN_WINDOW_DAYS) {
+      add('EXP-WINDOW-TOO-SHORT', 'high',
+        `Evaluation window ${window}d is shorter than the ${MIN_WINDOW_DAYS}d minimum; day-of-week seasonality produces high false-positive risk.`);
+    }
+  } else {
+    add('EXP-BASELINE-MISSING', 'blocked',
+      'No usable baseline_rate/mde declared; sample-size and power requirements cannot be established (fail closed).',
+      'required_input: baseline_rate (0-1) and mde (relative)');
+  }
+
+  // Stopping early
+  if (status === 'active' || status === 'observing') {
+    const daysRunning = observed.days_running ?? null;
+    if (window && daysRunning !== null && daysRunning < window) {
+      add('EXP-STOPPING-EARLY', 'high',
+        `Experiment has run ${daysRunning}d of the declared ${window}d window; stopping now invalidates the design. No interim reading is decision-grade.`);
+    }
+  }
+
+  // Sample-ratio mismatch
+  if (observed.control !== undefined && observed.variant !== undefined) {
+    const c = Number(observed.control);
+    const v = Number(observed.variant);
+    if (!Number.isFinite(c) || !Number.isFinite(v) || c < 0 || v < 0) {
+      add('EXP-OBSERVATIONS-INVALID', 'blocked', 'Observed counts must be non-negative numbers (fail closed).');
+    } else if (c + v >= 100) {
+      const total = c + v;
+      const share = declaredSplit / 100;
+      const expectedC = total * share;
+      const expectedV = total * (1 - share);
+      const chi2 = ((c - expectedC) ** 2) / expectedC + ((v - expectedV) ** 2) / expectedV;
+      const p = chiSquare1dfP(chi2);
+      if (p < SRM_ALPHA) {
+        add('EXP-SRM-DETECTED', 'critical',
+          `Sample-ratio mismatch: observed ${c}/${v} vs declared ${declaredSplit}/${100 - declaredSplit} split (chi-square p=${p.toExponential(2)}). Instrumentation or routing is broken; all readings from this experiment are untrustworthy until fixed.`);
+      }
+    } else {
+      add('EXP-SAMPLE-TOO-SMALL-FOR-SRM', 'blocked',
+        'Fewer than 100 total observations; SRM cannot be assessed yet (fail closed).');
+    }
+  } else if (status === 'active' || status === 'observing') {
+    add('EXP-OBSERVATIONS-MISSING', 'blocked',
+      'Active experiment without observed variant counts; sample ratio, power, and stopping state cannot be verified (fail closed).',
+      'required_input: observed control and variant assignment counts');
+  }
+
+  // Power status against observed sample
+  if (requiredN !== null && observed.control !== undefined && observed.variant !== undefined) {
+    const perVariant = Math.min(Number(observed.control), Number(observed.variant));
+    if (perVariant < requiredN) {
+      add('EXP-UNDERPOWERED', 'medium',
+        `Current sample (${perVariant}/variant) is below the ${requiredN}/variant requirement for ${Math.round((mde ?? 0) * 100)}% MDE at 80% power; any observed difference is not decision-grade.`);
+    }
+  }
+
+  // Revenue attribution without sufficient evidence
+  if (observed.revenue_claimed || /revenue|aov|arp/i.test(experiment.primary_metric || '')) {
+    const hasConcluded = status === 'concluded';
+    const hasSrm = findings.some((f) => f.guardrail_id === 'EXP-SRM-DETECTED');
+    if (hasSrm || !hasConcluded) {
+      add('EXP-REVENUE-UNSUPPORTED', 'high',
+        'Revenue attribution asserted without a concluded, SRM-clean experiment and verified conversion instrumentation; this remains a modeled estimate, not a measured outcome.');
+    }
+  }
+
+  // Contamination across pages / incompatible variants
+  const others = observed.other_active_experiments || [];
+  for (const other of others) {
+    if (other.target_page && experiment.target_page && other.target_page === experiment.target_page) {
+      add('EXP-CONTAMINATION', 'high',
+        `Experiment ${other.experiment_id} is also active on ${other.target_page}; overlapping experiments contaminate each other's readings.`);
+    }
+    const sharedVariants = (other.variant_ids || []).filter((id) => (experiment.variant_ids || []).includes(id));
+    if (sharedVariants.length) {
+      add('EXP-VARIANT-COLLISION', 'high',
+        `Variant id(s) ${sharedVariants.join(', ')} collide with active experiment ${other.experiment_id}; assignment is ambiguous.`);
+    }
+  }
+
+  // Lifecycle status (mutually exclusive, explicitly derived)
+  let lifecycle;
+  const blocking = findings.some((f) => f.severity === 'blocked' || f.severity === 'critical');
+  if (status === 'draft' || status === 'observing' || (!observed.control && !observed.variant && status !== 'active')) {
+    lifecycle = 'planned';
+  } else if (blocking) {
+    lifecycle = 'inconclusive';
+  } else {
+    const perVariant = Math.min(Number(observed.control ?? 0), Number(observed.variant ?? 0));
+    const withinWindow = window ? (observed.days_running ?? Infinity) >= window : false;
+    const sampleMet = requiredN !== null ? perVariant >= requiredN : false;
+    const significant = typeof observed.p_value === 'number' ? observed.p_value < (observed.alpha ?? 0.05) : false;
+    if (withinWindow && sampleMet && significant) lifecycle = 'validated';
+    else if (withinWindow && sampleMet) lifecycle = 'inconclusive';
+    else lifecycle = 'running';
+  }
+
+  const definitions = {
+    planned: 'declared, not yet receiving traffic; no reading exists',
+    running: 'receiving traffic; sample/window incomplete; interim readings are not decision-grade',
+    inconclusive: 'window and sample satisfied but the effect is not statistically significant, or a blocking guardrail fired; absence of evidence is not evidence of absence',
+    validated: 'full window, sufficient sample, no SRM, primary metric significant at declared alpha — statistically validated for the primary metric only, never a conversion or revenue guarantee',
+  };
+
+  return {
+    experiment_id: experiment.experiment_id,
+    registry_status: status,
+    lifecycle,
+    lifecycle_definition: definitions[lifecycle],
+    required_sample_per_variant: requiredN,
+    declared_traffic_split: `${declaredSplit}/${100 - declaredSplit}`,
+    guardrail_count: findings.length,
+    findings,
+    lifecycle_definitions: definitions,
+    note: 'lifecycle labels describe statistical state only; Citable does not guarantee conversion, ranking, or citation outcomes',
+  };
+}
+
+/**
+ * `citable check experiment <id> [--observed-control N --observed-variant N]`
+ */
+export async function checkExperiment(root, options = {}) {
+  const { registries, problems } = loadRegistries(root);
+  const entries = registries?.experiments?.entries || [];
+  const id = options.experimentId || options.experiment_id;
+  if (!id) throw new Error('usage: citable check experiment <experiment-id> [--observed-control N --observed-variant N --days-running N]');
+  const experiment = entries.find((e) => e.experiment_id === id);
+  if (!experiment) {
+    throw new Error(`experiment "${id}" not found in experiments.yaml. Available: ${entries.map((e) => e.experiment_id).join(', ') || 'none'}`);
+  }
+  const observed = {
+    control: options.observedControl ?? options.observed_control,
+    variant: options.observedVariant ?? options.observed_variant,
+    days_running: options.daysRunning ?? options.days_running,
+    baseline_rate: options.baselineRate ? Number(options.baselineRate) : undefined,
+    mde: options.mde ? Number(options.mde) : undefined,
+    p_value: options.pValue ? Number(options.pValue) : undefined,
+    revenue_claimed: options.revenueClaimed ?? options.revenue_claimed ?? false,
+    other_active_experiments: entries.filter((e) => e.status === 'active' && e.experiment_id !== id),
+  };
+  const result = evaluateExperiment(experiment, observed);
+  return { ...result, registry_problems: problems };
+}

package/src/commands/goldenCorpus.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readYaml, nowIso } from '../shared/io.js';
+import { buildSiteFromDir } from '../extractor/site.js';
+import { runDetectors } from '../detectors/framework.js';
+import { selectDetectors } from '../detectors/index.js';
+import { calculateVisualSaliency } from '../analysis/saliency.js';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * `citable corpus benchmark` — golden-benchmark evaluation of deterministic
+ * CRO detectors over a versioned, anonymized, labeled page corpus.
+ *
+ * Labels are page-level: expect_findings (must fire), expect_clean (must not
+ * fire), saliency bounds for the modeled conspicuity index. Output carries
+ * per-detector true/false positive/negative counts, precision, recall, and
+ * F1, plus an explicit pass/fail gate against the manifest thresholds.
+ *
+ * The benchmark evaluates detectors against synthetic fixtures; it is not
+ * evidence about real-world accuracy, and it never becomes a visibility or
+ * conversion claim.
+ */
+export async function runGoldenBenchmark(root, { corpusDir = null, writeReport = null } = {}) {
+  const resolvedCorpus = corpusDir
+    ? path.resolve(root, corpusDir)
+    : path.join(MODULE_DIR, '..', '..', 'tests', 'fixtures', 'golden-corpus');
+  const manifestPath = path.join(resolvedCorpus, 'MANIFEST.yaml');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`golden corpus manifest not found: ${manifestPath}`);
+  }
+  const manifest = readYaml(manifestPath);
+  const namespaces = manifest.namespaces || ['CRO'];
+  const detectors = selectDetectors({ namespaces });
+  const thresholds = manifest.thresholds || { recall_min: 1.0, precision_min: 1.0 };
+
+  // per-detector confusion counters
+  const tally = new Map();
+  for (const d of detectors) {
+    tally.set(d.id, { detector_id: d.id, deterministic: d.deterministic, true_positives: 0, false_positives: 0, false_negatives: 0, true_negatives: 0 });
+  }
+  const pageResults = [];
+  const saliencyResults = [];
+
+  for (const [siteName, site] of Object.entries(manifest.sites || {})) {
+    const siteDir = path.join(resolvedCorpus, siteName);
+    if (!fs.existsSync(siteDir)) throw new Error(`corpus site directory missing: ${siteDir}`);
+    const built = buildSiteFromDir(siteDir, { baseUrl: `https://${siteName}.corpus.test` });
+    for (const page of built.pages) {
+      const relPage = path.relative(siteDir, page.sourceFile).split(path.sep).join('/');
+      const labels = (site.pages || {})[relPage] || {};
+      const expected = new Set(labels.expect_findings || []);
+      const expectClean = new Set(labels.expect_clean || []);
+
+      const scoped = { site: { ...built, pages: [page] }, registries: null, observations: null };
+      const { findings } = runDetectors(detectors, scoped);
+      const fired = new Set(findings.map((f) => f.detector_id));
+
+      for (const d of detectors) {
+        const t = tally.get(d.id);
+        const isExpected = expected.has(d.id);
+        const didFire = fired.has(d.id);
+        if (isExpected && didFire) t.true_positives++;
+        else if (isExpected && !didFire) t.false_negatives++;
+        else if (!isExpected && didFire) t.false_positives++;
+        else t.true_negatives++;
+      }
+
+      const violations = [];
+      for (const id of expected) {
+        if (!fired.has(id)) violations.push({ kind: 'false_negative', detector_id: id });
+      }
+      for (const id of fired) {
+        if (!expected.has(id)) {
+          violations.push({ kind: expectClean.has(id) ? 'labeled_clean_violation' : 'unexpected_finding', detector_id: id, summary: findings.find((f) => f.detector_id === id)?.observation?.summary });
+        }
+      }
+
+      pageResults.push({
+        site: siteName,
+        kind: site.kind,
+        page: relPage,
+        url: page.url,
+        expected: [...expected],
+        fired: [...fired],
+        violations,
+      });
+
+      if (labels.saliency) {
+        const sal = calculateVisualSaliency({
+          ctas: page.ctas.map((c) => ({ ...c })),
+          headings: (page.h1s || []).map((h) => ({ level: 1, text: h.text })),
+          forms: page.forms.map((f) => ({ fieldCount: f.fieldCount })),
+        });
+        const pciMin = labels.saliency.pci_min;
+        const pass = pciMin === undefined ? true : sal.primary_cta_conspicuity_index >= pciMin;
+        saliencyResults.push({
+          site: siteName,
+          page: relPage,
+          primary_cta_conspicuity_index: sal.primary_cta_conspicuity_index,
+          pci_min_label: pciMin ?? null,
+          passed: pass,
+          methodology: 'PCI is a modeled heuristic index over DOM geometry labels, not observed user attention',
+        });
+      }
+    }
+  }
+
+  const perDetector = [...tally.values()].map((t) => {
+    const precision = (t.true_positives + t.false_positives) > 0 ? t.true_positives / (t.true_positives + t.false_positives) : null;
+    const recall = (t.true_positives + t.false_negatives) > 0 ? t.true_positives / (t.true_positives + t.false_negatives) : null;
+    const f1 = precision !== null && recall !== null && (precision + recall) > 0 ? (2 * precision * recall) / (precision + recall) : null;
+    return { ...t, precision, recall, f1 };
+  });
+
+  const exercised = perDetector.filter((d) => d.true_positives + d.false_negatives > 0);
+  const violations = pageResults.flatMap((p) => p.violations.map((v) => ({ site: p.site, page: p.page, ...v })));
+  const recallFailures = exercised.filter((d) => d.recall < thresholds.recall_min);
+  const precisionFailures = perDetector.filter((d) => d.precision !== null && d.precision < thresholds.precision_min);
+
+  const result = {
+    benchmark: 'golden-corpus',
+    corpus_version: manifest.corpus_version,
+    corpus_dir: path.relative(root, resolvedCorpus) || resolvedCorpus,
+    anonymized: Boolean(manifest.anonymized),
+    timestamp: nowIso(),
+    tool_version: JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version,
+    thresholds,
+    sites_evaluated: Object.keys(manifest.sites || {}).length,
+    pages_evaluated: pageResults.length,
+    per_detector: perDetector,
+    saliency: saliencyResults,
+    violations,
+    gate: {
+      ok: recallFailures.length === 0 && precisionFailures.length === 0 && violations.length === 0,
+      recall_failures: recallFailures.map((d) => d.detector_id),
+      precision_failures: precisionFailures.map((d) => d.detector_id),
+      violation_count: violations.length,
+    },
+    limitations: [
+      'Synthetic fixture benchmark: measures consistency with labels, not real-world accuracy.',
+      'Registry-dependent detectors (funnels, experiments) are not exercised by this corpus.',
+      'Saliency bounds evaluate a modeled heuristic index, not observed user attention.',
+    ],
+  };
+
+  if (writeReport) {
+    const outFull = path.resolve(root, writeReport);
+    fs.mkdirSync(path.dirname(outFull), { recursive: true });
+    fs.writeFileSync(outFull, JSON.stringify(result, null, 2) + '\n', 'utf8');
+    result.report_path = outFull;
+  }
+  return result;
+}

package/src/commands/implementationKit.js

@@ -0,0 +1,202 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, nowIso } from '../shared/io.js';
+import { remediateCommand } from './remediate.js';
+
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.svg']);
+
+function findRenderEvidence(runDir) {
+  const shots = [];
+  const walk = (d) => {
+    for (const name of fs.readdirSync(d)) {
+      const p = path.join(d, name);
+      if (fs.statSync(p).isDirectory()) walk(p);
+      else if (IMAGE_EXTS.has(path.extname(name).toLowerCase())) shots.push(path.relative(runDir, p));
+    }
+  };
+  if (fs.existsSync(runDir)) walk(runDir);
+  return shots;
+}
+
+function acceptanceTestsFor(finding, rem) {
+  const lines = [
+    '## Acceptance tests',
+    '',
+    '### 1. Deterministic detector re-check (authoritative)',
+    '```',
+    `citable verify remediation --run <source-run-id> --finding ${finding.detector_id} --target <file> --apply`,
+    '```',
+    'Pass criterion: status `verified` — the detector no longer reports this finding for the same subject. Detector absence is not an outcome guarantee.',
+    '',
+  ];
+  if (rem?.scaffold_command) {
+    lines.push(`### 2. Component integration`, '```', rem.scaffold_command, '```', 'After scaffolding, confirm the component renders without console errors in the consuming page.');
+    lines.push('');
+  }
+  lines.push(
+    '### 3. Manual review gates',
+    '- Confirm the change preserves factual accuracy, human comprehension, accessibility, and conversion function.',
+    '- Run the repository build/test suite. A failed build makes "validated" an unavailable conclusion.',
+    '- Capture after-change rendering evidence (screenshot) for the customer record.'
+  );
+  return lines.join('\n');
+}
+
+function deploymentFor(rem) {
+  const fw = rem?.framework?.framework || 'unknown';
+  const lines = [
+    '## Deployment instructions',
+    '',
+    `Detected framework: **${fw}**${rem?.framework ? ` (detection confidence ${rem.framework.confidence}; signals: ${rem.framework.signals.join(', ') || 'none'})` : ''}`,
+    '',
+    '1. Review `patch.diff`. Apply with `citable remediate --finding <id> --target <file> --write` or by hand from the diff.',
+    '2. Run your project build and test commands. The Citable static check does not replace your compiler.',
+    '3. Deploy through your normal pipeline; commit the rollback snapshot path noted in the verification record.',
+    '4. Frozen-CMS alternative: regenerate the edge adapter with `citable export edge --format cloudflare-cro` (Cloudflare Workers) and verify with `citable test edge`. Edge changes ship without a code deploy but remain subject to the same detector verification.',
+    '',
+    'Rollback: restore the snapshot recorded in `.citable/remediation/snapshots/` (see verification record `rollback_snapshot`).',
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * `citable kit export` — customer-ready implementation kit connecting audit
+ * findings to Nebula's fulfillment artifact: explanation, exact changes,
+ * rendering evidence, acceptance tests, deployment steps, re-audit command,
+ * and explicit limitations. Screenshots are included only when real rendering
+ * evidence exists in the source run; Citable never fabricates imagery.
+ */
+export async function exportImplementationKit(root, options = {}) {
+  const { run: runId, finding, subject = null, target = null, output = null } = options;
+  const runDir = path.join(root, '.citable', 'runs', runId || '');
+  if (!runId || !fs.existsSync(path.join(runDir, 'findings.json'))) {
+    throw new Error(`source run not found: .citable/runs/${runId || '(none)'}`);
+  }
+  const findings = readJson(path.join(runDir, 'findings.json'));
+  const matches = findings.filter((f) =>
+    (f.detector_id || '').toUpperCase() === String(finding || '').toUpperCase()
+    && (!subject || (f.subject?.identifier || f.subject?.url) === subject));
+  if (matches.length === 0) {
+    throw new Error(`finding ${finding} not present in run ${runId}`);
+  }
+
+  const f = matches[0];
+  const patch = target
+    ? await remediateCommand(root, { finding: f.detector_id, target, format: options.format || 'react' })
+    : await remediateCommand(root, { finding: f.detector_id, format: options.format || 'react' });
+
+  const slug = `${f.detector_id}-${String(subject || (f.subject?.identifier || f.subject?.url || 'subject'))
+    .replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 48)}`;
+  const kitDir = output ? path.resolve(root, output) : path.join(root, '.citable', 'kits', `${nowIso().replace(/\D/g, '').slice(0, 14)}-${slug}`);
+  fs.mkdirSync(path.join(kitDir, 'evidence'), { recursive: true });
+
+  // finding explanation (verbatim from the immutable run)
+  fs.writeFileSync(path.join(kitDir, 'finding.json'), JSON.stringify(matches, null, 2) + '\n');
+
+  // exact change: unified diff when a target file is known, else component code
+  if (target && patch.diff) {
+    fs.writeFileSync(path.join(kitDir, 'patch.diff'), patch.diff);
+    fs.writeFileSync(path.join(kitDir, 'patch-metadata.json'), JSON.stringify({
+      target_file: target,
+      framework: patch.framework,
+      patcher_class: patch.patcher_class,
+      confidence: patch.confidence?.score ?? null,
+      validation: patch.validation,
+      write_policy: patch.write_policy,
+      refusal: patch.write_refused ? patch.refusal_reason : null,
+    }, null, 2) + '\n');
+  }
+  if (patch.code) {
+    fs.writeFileSync(path.join(kitDir, `component-${patch.format || 'react'}.${patch.format === 'vue' ? 'vue' : patch.format === 'html' ? 'html' : 'jsx'}`), patch.code + '\n');
+  }
+
+  // before/after screenshots: only real rendering evidence from the run
+  const shots = findRenderEvidence(runDir);
+  for (const rel of shots) {
+    fs.copyFileSync(path.join(runDir, rel), path.join(kitDir, 'evidence', path.basename(rel)));
+  }
+  fs.writeFileSync(path.join(kitDir, 'evidence', 'MANIFEST.md'), shots.length
+    ? `Rendering evidence files copied from run ${runId}:\n${shots.map((s) => `- ${s}`).join('\n')}\nThese are before-state observations unless a paired post-remediation run is referenced. Citable does not fabricate imagery.\n`
+    : `No rendering evidence (screenshots) was present in run ${runId}. Collect after-state evidence with \`citable observe render --target <url>\` before and after the change. No placeholder imagery is provided because Citable does not fabricate evidence.\n`);
+
+  fs.writeFileSync(path.join(kitDir, 'acceptance-tests.md'), acceptanceTestsFor(f, patch) + '\n');
+  fs.writeFileSync(path.join(kitDir, 'deployment.md'), deploymentFor(patch) + '\n');
+
+  const ns = f.detector_id.split('-')[0].toLowerCase();
+  fs.writeFileSync(path.join(kitDir, 're-audit.sh'), `#!/bin/sh
+# Re-audit the affected scope after deployment and compare against the source run.
+set -eu
+citable audit --scope ${ns} --target <deployed-target> --base-url <base-url>
+citable verify remediation --run ${runId} --finding ${f.detector_id} --target <file> --apply
+citable compare-snapshots ${runId} <new-run-id>
+` + '\n');
+  fs.chmodSync(path.join(kitDir, 're-audit.sh'), 0o755);
+
+  const limitations = [
+    ...(f.reasoning?.limitations || []),
+    'This kit contains no modeled revenue or conversion-lift estimates; impact projections are excluded by policy.',
+    'Detection was performed against a snapshot; the deployed property may differ by the time this kit is applied.',
+    'A verified patch resolves the detector condition only; it is not a guarantee of conversion, ranking, or citation outcomes.',
+  ];
+  const assumptions = f.reasoning?.assumptions || [];
+  fs.writeFileSync(path.join(kitDir, 'limitations.md'), [
+    '## Limitations', '', ...limitations.map((l) => `- ${l}`), '',
+    '## Assumptions', '',
+    ...(assumptions.length ? assumptions.map((a) => `- ${a}`) : ['- No additional assumptions recorded by the detector.']),
+  ].join('\n') + '\n');
+
+  fs.writeFileSync(path.join(kitDir, 'README.md'), [
+    `# Implementation Kit — ${f.detector_id}`,
+    '',
+    `**Finding:** ${f.observation?.summary}`,
+    `**Subject:** ${f.subject?.identifier || f.subject?.url || 'unknown'}`,
+    `**Severity:** ${f.classification?.severity} | **Confidence:** ${f.classification?.confidence}`,
+    `**Source run:** ${runId} | **Kit generated:** ${nowIso()} by Citable ${PKG_VERSION}`,
+    '',
+    '## Contents',
+    '',
+    '- `finding.json` — verbatim finding record from the immutable source run',
+    target && patch.diff ? '- `patch.diff` — unified diff of the exact proposed change (dry-run; nothing was written)' : '- (no patch.diff: no target file supplied; component template below)',
+    patch.code ? '- `component-*.jsx|vue|html` — recommended Nebula Component template' : null,
+    '- `patch-metadata.json` — framework detection, confidence, validation checks (when target supplied)',
+    '- `evidence/` — rendering evidence from the source run (see evidence/MANIFEST.md)',
+    '- `acceptance-tests.md` — detector re-check plus manual review gates',
+    '- `deployment.md` — deployment and rollback instructions',
+    '- `re-audit.sh` — re-audit and verification commands',
+    '- `limitations.md` — limitations and assumptions (fact vs inference separation)',
+    '',
+    '## Order of operations',
+    '',
+    '1. Review finding and diff; assign an accountable owner.',
+    '2. Apply the smallest change (patch or component).',
+    '3. Run acceptance tests, then deployment.',
+    '4. Run `re-audit.sh`; keep the verification bundle with the customer record.',
+    '',
+    'Citable does not guarantee crawling, indexing, ranking, citation, recommendation, or conversion.',
+  ].filter(Boolean).join('\n') + '\n');
+
+  const files = [];
+  const walk = (d) => {
+    for (const name of fs.readdirSync(d)) {
+      const p = path.join(d, name);
+      if (fs.statSync(p).isDirectory()) walk(p);
+      else files.push(path.relative(kitDir, p));
+    }
+  };
+  walk(kitDir);
+
+  return {
+    ok: true,
+    finding_id: f.finding_id,
+    detector_id: f.detector_id,
+    source_run_id: runId,
+    kit_dir: path.relative(root, kitDir),
+    files: files.sort(),
+    rendering_evidence_count: shots.length,
+    has_patch_diff: Boolean(target && patch.diff),
+  };
+}

package/src/commands/inspectCro.js

@@ -1,7 +1,9 @@
+import { auditPageCro } from "../analysis/croAudit.js";
 import { buildContext } from './context.js';
 import { registryPageFor, safePath } from '../detectors/framework.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors } from '../detectors/framework.js';
+import { calculateVisualSaliency } from '../analysis/saliency.js';
 
 /**
  * `citable inspect cro <page>` — evaluate page conversion readiness, CTA visibility, form friction, and trust badges.
@@ -37,14 +39,58 @@ export async function inspectCro(root, pageRef, { target, baseUrl, refDate } = {
   const titleStem = page.title ? page.title.split(/[|—–-]/)[0].trim() : '';
   const h1Text = page.h1s?.[0]?.text || '';
 
+  // Visual attention saliency modeling
+  const saliency = calculateVisualSaliency({
+    ctas: ctas.map((c) => ({ ...c, isPrimary: c.isPrimary })),
+    headings: (page.h1s || []).map((h) => ({ level: 1, text: h.text })),
+    forms: forms.map((f) => ({ fieldCount: f.fieldCount })),
+  });
+
+  // Keystroke Effort Index (KEI) across all forms
+  const totalInputs = forms.reduce((sum, f) => sum + (f.fieldCount || 0), 0);
+  const inputsWithAutocomplete = forms.reduce((sum, f) => sum + f.inputs.filter((inp) => Boolean(inp.autocomplete)).length, 0);
+  const manualKeystrokes = totalInputs * 14; // Average 14 keystrokes + focus taps per field
+  const autofillKeystrokes = totalInputs > 0 && inputsWithAutocomplete > 0
+    ? (totalInputs - inputsWithAutocomplete) * 14 + 1
+    : manualKeystrokes;
+  const keystrokeReductionPct = manualKeystrokes > 0
+    ? Math.round(((manualKeystrokes - autofillKeystrokes) / manualKeystrokes) * 100)
+    : 0;
+
+  // Express checkout readiness: payment wallets and authentication tracked separately.
+  // Apple Pay / Google Pay / PayPal are payment methods; WebAuthn/passkeys are account
+  // authentication. Conflating them produces misleading "biometric readiness" claims.
+  const walletRx = /apple\s*pay|google\s*pay|paypal|one-click/i;
+  const authRx = /passkey|webauthn/i;
+  const walletCtas = ctas.filter((c) => walletRx.test(c.text || ''));
+  const authCtas = ctas.filter((c) => authRx.test(c.text || ''));
+  const walletViaBadgeOrHtml = trustBadges.some((t) => walletRx.test(t.signal || '')) ||
+    Boolean(page.rawHtml && /data-express-payment|apple-pay|google-pay|paypal-button/i.test(page.rawHtml));
+  const authViaHtml = Boolean(page.rawHtml && /passkey|webauthn|publickey-credentials/i.test(page.rawHtml));
+
+  // Friction Surface Area (FSA) — a modeled heuristic index, not a measured
+  // revenue or conversion outcome.
+  const fsaScore = croFindings.reduce((acc, f) => {
+    const w = f.classification.severity === 'critical' ? 15 : f.classification.severity === 'high' ? 10 : f.classification.severity === 'medium' ? 5 : 2;
+    return acc + w;
+  }, 0);
+
+  const pageCroAudit = auditPageCro(page, ctx);
+
   return {
     url: page.url,
+    conversion_readiness_score: pageCroAudit.conversion_readiness_score,
+    atf_clarity: pageCroAudit.atf_clarity,
+    trust_and_credibility: pageCroAudit.trust_and_credibility,
+    offer_architecture: pageCroAudit.offer_architecture,
     sourceFile: page.sourceFile,
     status: page.status,
     declared_conversion_action: declaredAction,
     primary_intent: reg?.primary_intent ?? null,
     page_type: reg?.page_type ?? null,
     conversion_status: status,
+    friction_surface_area: fsaScore,
+    friction_surface_area_note: 'modeled heuristic index (severity-weighted mechanical defect count); not a measured conversion or revenue outcome',
     title_to_h1_alignment: {
       titleStem,
       h1Text,
@@ -55,6 +101,27 @@ export async function inspectCro(root, pageRef, { target, baseUrl, refDate } = {
     analytics_installed: (page.analyticsTags || []).length > 0,
     analytics_tags: page.analyticsTags || [],
     nav_links_count: page.navLinksCount || 0,
+    saliency,
+    keystroke_effort: {
+      total_inputs: totalInputs,
+      inputs_with_autocomplete: inputsWithAutocomplete,
+      autofill_coverage_pct: totalInputs > 0 ? Math.round((inputsWithAutocomplete / totalInputs) * 100) : 100,
+      manual_keystrokes_required: manualKeystrokes,
+      autofill_keystrokes_required: autofillKeystrokes,
+      keystroke_reduction_pct: keystrokeReductionPct,
+    },
+    express_checkout_readiness: {
+      payment_wallet_readiness: {
+        supported: walletCtas.length > 0 || walletViaBadgeOrHtml,
+        detected_triggers: walletCtas.map((c) => c.text),
+        note: 'payment wallets are payment methods (Apple Pay, Google Pay, PayPal)',
+      },
+      authentication_readiness: {
+        supported: authCtas.length > 0 || authViaHtml,
+        detected_triggers: authCtas.map((c) => c.text),
+        note: 'WebAuthn/passkeys are account authentication, not a payment method; this is an informational readiness index, not observed usage',
+      },
+    },
     ctas: ctas.map((c) => ({
       text: c.text,
       tag: c.tag,