@nebulacomponents/citable 1.16.0 → 1.18.0

package/src/cli/index.js

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
+import { auditCroSuite, formatCroSuiteOutput } from "../commands/croSuite.js";
+import { formatBacklogMarkdown } from "../commands/croBacklog.js";
+import { formatCroRoadmapMarkdown } from "../analysis/croRoadmap.js";
+import { sweepTechnical, formatSweepOutput } from "../commands/sweep.js";
+import { inspectEeat, formatEeatOutput } from "../commands/inspectEeat.js";
+import { inspectReadiness, formatReadinessOutput } from "../commands/answerEngineReadiness.js";
+import { auditBacklinks, formatBacklinksOutput } from "../commands/auditBacklinks.js";
+import { roadmapCommand } from "../commands/roadmapCmd.js";
+import { sowCommand } from "../commands/sowCmd.js";
+import { buildIceMatrix, formatIceMatrixOutput } from "../analysis/iceMatrix.js";
+import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { init } from '../commands/init.js';
 import { audit } from '../commands/audit.js';
+import { auditEdgeCode } from '../commands/edgeSecurity.js';
 import { planAudit } from '../commands/planAudit.js';
 import { demo } from '../commands/demo.js';
 import { validate } from '../commands/validate.js';
@@ -21,6 +33,14 @@ import { probeEngine } from '../commands/probe.js';
 import { lintComponents } from '../commands/lintComponents.js';
 import { exportExecutiveReport } from '../reporting/executiveExport.js';
 import { attributeImpact } from '../commands/attributeImpact.js';
+import { remediateCommand } from '../commands/remediate.js';
+import { verifyRemediation } from '../commands/verifyRemediation.js';
+import { exportImplementationKit } from '../commands/implementationKit.js';
+import { compatibilityCommand, verifyPage } from '../commands/compatibility.js';
+import { runVisualRegression } from '../commands/visualRegression.js';
+import { checkExperiment } from '../commands/experimentGuardrails.js';
+import { runGoldenBenchmark } from '../commands/goldenCorpus.js';
+import { previewCroCommand } from '../commands/previewCro.js';
 import { schemaCommand } from '../commands/schemaCmd.js';
 import { compareSnapshots } from '../commands/compareSnapshots.js';
 import { isInstallerCommand, runInstallerCommand } from '../installer/index.js';
@@ -76,12 +96,26 @@ Commands
   inspect <page>            Profile one page (URL path or source file)
   inspect serp <page>       Simulate Google SERP title/snippet truncation and rich results
   inspect cro <page>        Evaluate page conversion readiness, CTA visibility, and friction
+  inspect saliency <page>   Evaluate privacy-first algorithmic visual attention and CTA conspicuity
   inspect aeo <page>        Evaluate answer extractability, question density, and structure
   inspect geo <page>        Evaluate RAG chunkability, section density, and retrieval posture
+  preview cro <page>        Interactive split-screen visual preview of original vs remediated page
+  remediate [finding]       Synthesize accessible Nebula Components; safe patches with diff, validation, confidence, rollback (--write gated, fail closed)
   test funnel [id]          Test multi-step conversion funnel continuity and parameter persistence
+  test visual               Deterministic layout-contract checks + viewport/variant screenshot matrix (screenshots need playwright)
   plan experiment           Calculate statistical sample size and duration for A/B testing
+  check experiment          Experiment guardrails: SRM, stopping, power, contamination, lifecycle status
   map-claims                Extract material claim candidates from pages (--write to save)
   substantiate              Assess claim/evidence status (--write to apply downgrades)
+  cro [audit]               Full CRO intelligence suite: funnel, ATF clarity, trust, cognitive load, ICE matrix, roadmap
+  cro backlog               Generate A/B experimentation backlog with falsifiable hypotheses & guardrails
+  cro roadmap               30/90/180-day CRO roadmap tied to measurable conversion outcomes
+  sweep [technical]         Run technical SEO sweep with Core Web Vitals metrics
+  inspect eeat <page>       Evaluate on-page content against Google E-E-A-T rubric (0-5 scale)
+  inspect readiness <page>  Evaluate answer-engine readiness across Perplexity, Bing Copilot, and ChatGPT
+  audit backlinks           Audit off-page authority and identify toxic domains (--input <file>)
+  prioritize matrix         Impact/Effort/Confidence (ICE) scoring matrix for roadmap & findings
+  roadmap [generate|show]   30/90/180-day strategic roadmap with milestone horizons
   schema                    Validate deployed JSON-LD and propose registry-derived schema
   validate [mode]           registries (default) | claims | evidence | schema | links
   compare-snapshots [a b]   Regression diff between two audit runs
@@ -94,6 +128,8 @@ Commands
   report dashboard [--last N] [--since <run-id>]   Render a cross-run evidence trend as Markdown + HTML
   report share-of-voice [--last N]                 Compute first-party and competitor citation share
   report consensus [--last N] [--since <run-id>]   Render Canonical Discovery Consensus Matrix (Markdown + HTML)
+  report search [--target <dir|url>] [--run <id>]  Enterprise Search Intelligence & AEO/GEO Executive Briefing (19 pillars)
+  report cro [--target <dir|url>] [--input <file>] Enterprise CRO & Customer Journey Executive Briefing (25 pillars)
   metrics import            Import declared metric observations from CSV/JSON
   connect status            List optional connectors and configured connections
   connect configure         Configure non-secret connection state (--write to save)
@@ -123,9 +159,14 @@ Commands
   corpus evaluate           Evaluate a disclosed real-property acceptance corpus
   corpus publish            Validate and project an owner-authorized public corpus
   corpus receipt            Create a reproducibility receipt for a sealed run
+  corpus benchmark          Run the labeled golden fixture corpus and report per-detector precision/recall
   corpus compare-receipts   Compare two acceptance-run receipt envelopes
   artifacts export         Export one sealed run as a portable verified directory
   artifacts verify         Verify an exported artifact interchange directory
+  verify remediation       Closed loop: re-run the detector after a patch and emit a before/after evidence bundle
+  verify page <page>       Run all detectors scoped to one page and report posture (pass/attention/blocked)
+  compatibility            Pre-flight: Node engine, optional adapters, browser, framework, registries, edge limits
+  kit export               Customer-ready implementation kit: finding, diff, evidence, acceptance tests, deployment
   artifacts import         Import a verified run without changing its canonical bytes
   self-upgrade              Check for a newer version and upgrade the npx cache
   kpi [list|show|validate]  KPI architecture — govern metric definitions, sources, targets
@@ -203,6 +244,7 @@ function parseArgs(argv) {
     else if (a === '--target') args.target = argv[++i];
     else if (a === '--base-url') args.baseUrl = argv[++i];
     else if (a === '--ref-date') args.refDate = argv[++i];
+    else if (a === '--viewport') args.viewport = argv[++i];
     else if (a === '--input') args.input = argv[++i];
     else if (a === '--output') args.output = argv[++i];
     else if (a === '--run') args.runId = argv[++i];
@@ -254,14 +296,59 @@ function parseArgs(argv) {
     else if (a === '--note') args.note = argv[++i];
     else if (a === '--expired') args.expiredOnly = true;
     else if (a === '--expiring-soon') args.expiringSoonDays = Number(argv[++i]);
+    else if (a === '--finding') args.finding = argv[++i];
+    else if (a === '--component') args.component = argv[++i];
+    else if (a === '--format') args.format = argv[++i];
+    else if (a === '--strict') args.strict = true;
+    else if (a === '--export') args.export = argv[++i];
+    else if (a === '--apply') args.apply = true;
+    else if (a === '--preview-file') args['preview-file'] = argv[++i];
+    else if (a === '--observed-control') args['observed-control'] = argv[++i];
+    else if (a === '--observed-variant') args['observed-variant'] = argv[++i];
+    else if (a === '--days-running') args['days-running'] = argv[++i];
+    else if (a === '--baseline-rate') args['baseline-rate'] = argv[++i];
+    else if (a === '--p-value') args['p-value'] = argv[++i];
+    else if (a === '--matrix') args.matrix = true;
+    else if (a === '--roadmap') args.roadmap = true;
+    else if (a === '--engines') args.engines = true;
+    else if (a === '--funnel') args.funnel = argv[++i];
+    else if (a === '--client') args.client = argv[++i];
+    else if (a === '--type') args.type = argv[++i];
+    else if (a === '--revenue-claimed') args['revenue-claimed'] = true;
     else args._.push(a);
   }
   return args;
 }
 
-function out(args, human, data) {
-  if (args.json) console.log(JSON.stringify(data, null, 2));
-  else console.log(human);
+const TOOL_VERSION_CLI = JSON.parse(
+  fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+
+// Set by main(); read by out() for the JSON envelope. Kept off `args` because
+// several commands spread parsed args directly into option objects.
+let CURRENT_COMMAND = null;
+
+/**
+ * Stable machine-readable output contract (citable_output_schema 1.0):
+ * every command's --json payload is wrapped in this envelope so CI systems
+ * and agencies can consume results without parsing terminal text. The
+ * envelope version changes only on breaking envelope changes; command
+ * payloads evolve backward-compatibly inside `result`.
+ */
+const OUTPUT_SCHEMA_VERSION = '1.0';
+
+function out(args, human, data, command = null) {
+  if (args.json) {
+    console.log(JSON.stringify({
+      citable_output_schema: OUTPUT_SCHEMA_VERSION,
+      tool_version: TOOL_VERSION_CLI,
+      command: command ?? CURRENT_COMMAND,
+      generated_at: new Date().toISOString(),
+      result: data,
+    }, null, 2));
+  } else {
+    console.log(human);
+  }
 }
 
 export async function main(argv = process.argv.slice(2), options = {}) {
@@ -272,6 +359,7 @@ export async function main(argv = process.argv.slice(2), options = {}) {
   }
   if (isInstallerCommand(cmd)) return runInstallerCommand(cmd, argv.slice(1), options);
   const args = parseArgs(argv.slice(1));
+  CURRENT_COMMAND = cmd;
   const root = options.cwd ?? process.cwd();
 
   try {
@@ -299,8 +387,30 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         break;
       }
       case 'audit': {
+        if (args._[0] === 'cro') {
+          const r = await auditCroSuite(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, input: args.input, funnelId: args.funnel });
+          out(args, formatCroSuiteOutput(r), r);
+          break;
+        }
+        if (args._[0] === 'backlinks') {
+          const r = await auditBacklinks(root, { input: args.input, target: args.target, minSeverity: args.minSeverity });
+          out(args, formatBacklinksOutput(r), r);
+          break;
+        }
+        if (args._[0] === 'edge') {
+          const file = args._[1];
+          if (!file || !args.format) throw new Error('usage: citable audit edge <file> --format <cloudflare-worker|cloudflare-cro|vercel-middleware|shopify-snippet|html>');
+          const content = fs.readFileSync(path.resolve(root, file), 'utf8');
+          const r = auditEdgeCode(content, { format: args.format, name: file });
+          const txt = `audit edge ${file} (${r.format}, ${r.byte_size} bytes)
+  Findings: ${r.finding_count} (high:${r.high} medium:${r.medium} advisory:${r.advisory})
+${r.findings.map((f) => `  [${f.rule_id}] (${f.severity}) ${f.summary}\n    Fix: ${f.remediation}`).join('\n') || '  no risk patterns found'}
+  Methodology: ${r.methodology}`;
+          out(args, txt, r);
+          break;
+        }
         const scope = args._[0];
-        const r = await audit(root, { target: args.target, scope, baseUrl: args.baseUrl, refDate: args.refDate });
+        const r = await audit(root, { target: args.target, scope, baseUrl: args.baseUrl, refDate: args.refDate, viewport: args.viewport });
         out(args, `Audit ${r.runId}: ${r.summary.total} finding(s) [${Object.entries(r.summary.by_severity).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nReport: ${path.join(r.dir, 'report.md')}\nStatus: ${r.manifest.status}${r.manifest.incomplete_checks.length ? `\nIncomplete: ${r.manifest.incomplete_checks.join('; ')}` : ''}`, { runId: r.runId, dir: r.dir, summary: r.summary, status: r.manifest.status });
         break;
       }
@@ -313,6 +423,18 @@ export async function main(argv = process.argv.slice(2), options = {}) {
       }
       case 'inspect': {
         if (!args._[0]) throw new Error('usage: citable inspect <page> --target <dir|url> OR citable inspect serp <page> OR citable inspect cro <page> OR citable inspect aeo <page> OR citable inspect geo <page>');
+        if (args._[0] === 'eeat' || args._[0] === 'content') {
+          if (!args._[1]) throw new Error('usage: citable inspect eeat <page> --target <dir|url>');
+          const r = await inspectEeat(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+          out(args, formatEeatOutput(r), r);
+          break;
+        }
+        if (args._[0] === 'readiness' || args._[0] === 'engines') {
+          if (!args._[1]) throw new Error('usage: citable inspect readiness <page> --target <dir|url>');
+          const r = await inspectReadiness(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+          out(args, formatReadinessOutput(r), r);
+          break;
+        }
         if (args._[0] === 'serp') {
           if (!args._[1]) throw new Error('usage: citable inspect serp <page> --target <dir|url>');
           const r = await inspectSerp(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
@@ -336,11 +458,18 @@ ${richList}
           if (!args._[1]) throw new Error('usage: citable inspect cro <page> --target <dir|url>');
           const r = await inspectCro(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
           const txt = `Inspect CRO ${r.url}
-  Status: ${r.conversion_status}
+  Status: ${r.conversion_status} (Conversion Readiness: ${r.conversion_readiness_score ?? 'N/A'}/100)
+  Above-the-Fold Clarity: ${r.atf_clarity?.score ?? 'N/A'}/100 (Scent: ${r.atf_clarity?.scent_match ? 'CONGRUENT' : 'GAP'})
+  Trust & Credibility: ${r.trust_and_credibility?.score ?? 'N/A'}/100
+  Friction Surface Area: ${r.friction_surface_area}
   Declared Conversion Action: ${r.declared_conversion_action || 'none'}
   Page Type: ${r.page_type || 'unregistered'}; Intent: ${r.primary_intent || 'unregistered'}
   Analytics Instrumentation: ${r.analytics_installed ? `INSTALLED (${r.analytics_tags.length} tag${r.analytics_tags.length === 1 ? '' : 's'})` : 'NOT DETECTED'}
   Hero CTAs: ${r.hero_cta_count}; Choice Overload: ${r.has_choice_overload ? 'YES (paralysis risk)' : 'no'}
+  Primary CTA Conspicuity: ${r.saliency?.primary_cta_conspicuity_index ?? 'N/A'} (${r.saliency?.pci_assessment ?? 'unassessed'}) — modeled heuristic index, not observed attention
+  Keystroke Effort: ${r.keystroke_effort?.autofill_coverage_pct}% autofill coverage (${r.keystroke_effort?.keystroke_reduction_pct}% modeled mobile friction reduction)
+  Payment Wallet Readiness: ${r.express_checkout_readiness?.payment_wallet_readiness?.supported ? 'SUPPORTED' : 'NOT DETECTED (CRO-021)'}
+  Authentication Readiness (passkeys/WebAuthn): ${r.express_checkout_readiness?.authentication_readiness?.supported ? 'DETECTED' : 'NOT DETECTED'} (informational index; authentication, not payment)
   CTAs (${r.ctas.length}):
 ${r.ctas.map((c) => `    [${c.isPrimary ? 'PRIMARY' : 'SECONDARY'}${c.inHero ? ' - HERO' : ''}] "${c.text}" (${c.tag}) → ${c.target || 'no target'}`).join('\n') || '    none'}
   Forms (${r.forms.length}):
@@ -350,6 +479,20 @@ ${r.forms.map((f, i) => `    Form ${i + 1}: ${f.fieldCount} fields (autocomplete
           out(args, txt, r);
           break;
         }
+        if (args._[0] === 'saliency') {
+          if (!args._[1]) throw new Error('usage: citable inspect saliency <page> --target <dir|url>');
+          const r = await inspectCro(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+          const sal = r.saliency;
+          const gazeLines = (sal?.predicted_gaze_path || []).map((g) => `    ${g.order}. [${g.type.toUpperCase()}] "${g.label}" (salience: ${Math.round(g.salience_score * 100)}%)`).join('\n');
+          const txt = `Inspect Saliency ${r.url}
+  Primary CTA Conspicuity Index: ${sal?.primary_cta_conspicuity_index ?? 'N/A'} [${sal?.pci_assessment ?? 'unassessed'}]
+  Visual Clutter Risk: ${sal?.visual_clutter ?? 'clean'} (${sal?.competing_hero_elements_count ?? 0} high-salience hero elements)
+  Predicted Gaze Path (First 3 Fixations):
+${gazeLines || '    none predicted'}
+  SVG Attention Heatmap: generated (${sal?.elements_evaluated ?? 0} elements mapped)`;
+          out(args, txt, { url: r.url, saliency: sal });
+          break;
+        }
         if (args._[0] === 'aeo') {
           if (!args._[1]) throw new Error('usage: citable inspect aeo <page> --target <dir|url>');
           const r = await inspectAeo(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
@@ -451,8 +594,84 @@ ${r.headings.questions.map((q) => `    [H${q.level}] "${q.text}"`).join('\n') ||
         out(args, txt, r);
         break;
       }
+      case 'preview': {
+        const sub = args._[0];
+        if (sub !== 'cro') throw new Error('usage: citable preview cro <page> [--target <dir|url>] [--export <path>]');
+        const page = args._[1] || 'home';
+        const r = await previewCroCommand(root, page, { target: args.target, export: args.export });
+        const txt = `Preview CRO ${r.url}
+  Friction Surface Area (Before): ${r.fsa_before}
+  Friction Surface Area (Modeled Target): ${r.fsa_after} (modeled index, not a measured outcome)
+  Resolved Findings: ${r.findings_count}
+  HTML Preview: ${r.saved_file || 'rendered in memory (use --export <file.html> to save)'}`;
+        out(args, txt, r);
+        break;
+      }
+      case 'remediate': {
+        const r = await remediateCommand(root, {
+          finding: args.finding || args._[0],
+          component: args.component,
+          target: args.target,
+          format: args.format || 'react',
+          write: args.write,
+        });
+        if (r.target) {
+          const parts = [`Remediate ${r.finding_id} → ${r.recommended_component}`, `  Rationale: ${r.rationale}`, `  Scaffold Command: ${r.scaffold_command}`];
+          parts.push(`  Target File: ${r.target}`);
+          parts.push(`  Framework: ${r.framework?.framework || 'unknown'} (detection confidence ${r.framework?.confidence ?? 0})`);
+          parts.push(`  Patch: ${r.changed ? `${r.match_count} match(es)` : 'no match (already remediated or not applicable)'}, idempotent: ${r.idempotent}, class: ${r.patcher_class}`);
+          if (r.validation) {
+            for (const c of r.validation.checks) parts.push(`  Check ${c.check_id}: ${c.passed ? 'PASS' : 'FAIL'} — ${c.detail}`);
+            if (r.validation.methodology) parts.push(`  Methodology: ${r.validation.methodology}`);
+          }
+          if (r.confidence) {
+            parts.push(`  Confidence: ${r.confidence.score} (write threshold ${r.write_policy?.min_confidence ?? 0.7})`);
+            for (const f of r.confidence.factors) parts.push(`    - ${f.factor}: ${f.weight} (${f.detail})`);
+          }
+          parts.push(r.written
+            ? `  Written. Rollback snapshot: ${r.rollback?.snapshot_file}`
+            : r.write_refused
+              ? `  Write REFUSED (fail closed): ${r.refusal_reason}`
+              : `  Dry run — unified diff below. Use --write to apply.`);
+          if (r.diff) parts.push('Unified Diff:', r.diff.trimEnd());
+          parts.push('', 'Code Snippet (recommended component):', '--------------------------------------------------', r.code, '--------------------------------------------------');
+          out(args, parts.join('\n'), r);
+          break;
+        }
+        const txt = r.recommended_component
+          ? `Remediate ${r.finding_id} → ${r.recommended_component}
+  Rationale: ${r.rationale}
+  Scaffold Command: ${r.scaffold_command}
+Code Snippet (${r.format}):
+--------------------------------------------------
+${r.code}
+--------------------------------------------------`
+          : r.component
+            ? `Remediate Component: ${r.component}
+  Scaffold Command: ${r.scaffold_command}
+Code Snippet:
+--------------------------------------------------
+${r.code}
+--------------------------------------------------`
+            : `Available Components:
+${(r.available_components || []).map((c) => `  - ${c.name} (${c.id}): ${c.description}`).join('\n')}
+Supported Findings: ${(r.supported_findings || []).join(', ')}`;
+        out(args, txt, r);
+        break;
+      }
       case 'test-funnel':
       case 'test': {
+        if (cmd === 'test' && args._[0] === 'visual') {
+          const preview = args['preview-file'] ? fs.readFileSync(path.resolve(root, args['preview-file']), 'utf8') : null;
+          const r = await runVisualRegression(root, { previewHtml: preview, output: args.output });
+          const txt = `test visual
+  Contract checks: ${r.contract.ok ? 'ALL PASS' : 'FAIL'} (${r.contract.checks.filter((c) => c.passed).length}/${r.contract.checks.length})
+${r.contract.checks.map((c) => `  ${c.passed ? '✔' : '✖'} ${c.check_id}: ${c.detail}`).join('\n')}
+  Matrix cells: ${r.matrix_cells.length}
+  Screenshots: ${r.screenshots.status}${r.screenshots.required_input ? ` (required_input: ${r.screenshots.required_input})` : ` (${r.screenshots.captured.length} captured)`}`;
+          out(args, txt, r);
+          break;
+        }
         if (cmd === 'test-funnel' || args._[0] === 'funnel') {
           const funnelId = cmd === 'test-funnel' ? args._[0] : args._[1];
           const r = await testFunnel(root, funnelId, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
@@ -510,7 +729,8 @@ ${r.issues.map((iss) => `    - ${iss}`).join('\n') || '    none'}
         if (sub === 'edge') {
           const format = args.format || 'cloudflare-redirects';
           const r = await exportEdgeRules(root, { format, output: args.output });
-          out(args, `Exported ${r.rules_count} edge rule(s) in format "${r.format}"${r.output_path ? ` to ${r.output_path}` : ''}\n${r.content}`, r);
+          const sec = r.security;
+          out(args, `Exported ${r.rules_count} edge rule(s) in format "${r.format}"${r.output_path ? ` to ${r.output_path}` : ''}\nSecurity audit: ${sec.high} high, ${sec.medium} medium, ${sec.advisory} advisory finding(s)\n${sec.findings.map((f) => `  [${f.rule_id}] (${f.severity}) ${f.summary}`).join('\n') || '  no risk patterns found'}\n${r.content}`, r);
           break;
         }
         throw new Error('usage: citable export edge [--format <cloudflare-redirects|cloudflare-waf|cloudflare-worker>]');
@@ -577,6 +797,16 @@ ${r.recommendations.map((rec) => `    - ${rec}`).join('\n')}`;
         break;
       }
       case 'action-plan': {
+        if (args.matrix) {
+          const r = await prioritizeCommand(['matrix', ...(args._[0] ? ['--run', args._[0]] : ['--findings'])], root);
+          out(args, r.formatted || JSON.stringify(r, null, 2), r);
+          break;
+        }
+        if (args.roadmap) {
+          const r = await roadmapCommand(root, { runId: args._[0], target: args.target, write: args.write !== false });
+          out(args, r.markdown, r);
+          break;
+        }
         const r = actionPlan(root, { runId: args._[0] });
         out(args, `action-plan: ${r.summary.total_actions} action(s) [ready:${r.summary.ready} blocked:${r.summary.blocked}]\nPlan: ${path.join(r.dir, 'action-plan.md')}\nSource audit: ${r.source_run_id}`, r);
         break;
@@ -629,11 +859,46 @@ ${r.recommendations.map((rec) => `    - ${rec}`).join('\n')}`;
         } else if (sub === 'consensus') {
           const r = reportConsensus(root, { runId: args.runId, since: args.since, last: args.last ? Number(args.last) : undefined });
           out(args, `report consensus: ${r.urls_evaluated} URL(s) evaluated (${r.canonical_consensus_count} consensus, ${r.conflicts_count} conflict(s))\nMarkdown: ${r.path_md}\nHTML: ${r.path_html}`, r);
+        } else if (sub === 'search' || sub === 'seo') {
+          const r = await exportExecutiveReport(root, args.runId, {
+            type: 'search',
+            format: args.format || 'markdown',
+            clientName: args.client,
+            output: args.output,
+            target: args.target,
+            baseUrl: args.baseUrl,
+            refDate: args.refDate,
+            input: args.input,
+          });
+          out(args, r.content, r.data);
+        } else if (sub === 'cro') {
+          const r = await exportExecutiveReport(root, args.runId, {
+            type: 'cro',
+            format: args.format || 'markdown',
+            clientName: args.client,
+            output: args.output,
+            target: args.target,
+            baseUrl: args.baseUrl,
+            refDate: args.refDate,
+            input: args.input,
+            funnelId: args.funnel,
+          });
+          out(args, r.content, r.data);
         } else if (sub === 'export') {
-          const r = await exportExecutiveReport(root, args.runId, { format: args.format, clientName: args.client, output: args.output });
+          const r = await exportExecutiveReport(root, args.runId, {
+            format: args.format,
+            clientName: args.client,
+            output: args.output,
+            type: args.type,
+            target: args.target,
+            baseUrl: args.baseUrl,
+            refDate: args.refDate,
+            input: args.input,
+            funnelId: args.funnel,
+          });
           out(args, `Executive Report Exported (${r.format}) for "${r.client_name}"${r.output_path ? ` to ${r.output_path}` : ''}\n\n${r.content}`, r);
         } else {
-          throw new Error('usage: citable report <dashboard|share-of-voice|consensus|export> [--last <n>] [--since <run-id>] [--run <run-id>] [--format <html-brief|markdown-deck>]');
+          throw new Error('usage: citable report <dashboard|share-of-voice|consensus|search|cro|export> [--last <n>] [--since <run-id>] [--run <run-id>] [--format <md|html|json>]');
         }
         break;
       }
@@ -831,7 +1096,14 @@ ${r.recommendations.map((rec) => `    - ${rec}`).join('\n')}`;
         } else if (mode === 'compare-receipts') {
           const r = readAndCompareAcceptanceReceipts(args._[1], args._[2]);
           out(args, `corpus compare-receipts ${r.receipt_a} → ${r.receipt_b}\nComparable envelope: ${r.comparable}\nFingerprint equal: ${r.fingerprint_equal}\nPartial runs: ${r.partial_runs.length}`, r);
-        } else throw new Error('usage: citable corpus <evaluate|publish|receipt|compare-receipts> [options]');
+        } else if (mode === 'benchmark') {
+          const r = await runGoldenBenchmark(root, { corpusDir: args.input, writeReport: args.output });
+          const txt = `corpus benchmark v${r.corpus_version}: ${r.pages_evaluated} page(s) across ${r.sites_evaluated} site(s)
+  Gate: ${r.gate.ok ? 'PASS' : 'FAIL'} (violations: ${r.gate.violation_count}, recall failures: ${r.gate.recall_failures.join(', ') || 'none'}, precision failures: ${r.gate.precision_failures.join(', ') || 'none'})
+${r.per_detector.filter((d) => d.true_positives + d.false_negatives + d.false_positives > 0).map((d) => `  ${d.detector_id}: TP ${d.true_positives}, FP ${d.false_positives}, FN ${d.false_negatives}, P ${d.precision ?? 'n/a'}, R ${d.recall ?? 'n/a'}`).join('\n')}
+  Limitations: ${r.limitations[0]}`;
+          out(args, txt, r);
+        } else throw new Error('usage: citable corpus <evaluate|publish|receipt|compare-receipts|benchmark> [options]');
         break;
       }
       case 'artifacts': {
@@ -848,6 +1120,93 @@ ${r.recommendations.map((rec) => `    - ${rec}`).join('\n')}`;
         } else throw new Error('usage: citable artifacts <export <run-id> --output <directory>|verify --input <directory>|import --input <directory>>');
         break;
       }
+      case 'verify': {
+        const mode = args._[0];
+        if (mode === 'page') {
+          const r = await verifyPage(root, args._[1], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, viewport: args.viewport });
+          const sev = Object.entries(r.by_severity).filter(([, n]) => n > 0).map(([k, n]) => `${k}:${n}`).join(' ') || 'none';
+          const txt = `verify page ${r.page}
+  Status: ${r.status}
+  Findings: ${r.finding_count} (${sev})
+  Detectors run: ${r.provenance.detectors_run.length}
+  Definition: ${r.provenance.definition}`;
+          out(args, txt, r);
+          break;
+        }
+        if (mode !== 'remediation') throw new Error('usage: citable verify <remediation --run <run-id> --finding <detector-id> [|page <page>] [--target <dir|file>] [--apply]');
+        const r = await verifyRemediation(root, {
+          run: args.runId || args._[1],
+          finding: args.finding,
+          target: args.target,
+          apply: args.apply,
+          subject: args.subject,
+          baseUrl: args['base-url'],
+          refDate: args['ref-date'],
+        });
+        const subject = r.subject?.identifier || 'unknown subject';
+        const patchLine = r.patch
+          ? `\n  Patch: applied=${r.patch.applied}${r.patch.refusal_reason ? ` (refused: ${r.patch.refusal_reason})` : ''}${r.patch.rollback_snapshot ? `\n  Rollback snapshot: ${r.patch.rollback_snapshot}` : ''}`
+          : '';
+        const txt = `verify remediation ${r.detector_id} on ${subject}
+  Verdict: ${r.status}${r.verdict.resolved ? ' (finding no longer reported)' : ''}
+  Before finding(s): ${r.verdict.before_finding_ids.join(', ') || 'none'}
+  After finding(s): ${r.verdict.after_finding_ids.join(', ') || 'none'}
+  New critical/high regressions: ${r.verdict.new_regressions.length}${patchLine}
+  Re-check target: ${r.provenance.recheck_target || 'n/a'}
+  Resolution criterion: detector absence for the same subject; not an outcome guarantee
+  Bundle: ${r.bundle_dir || 'not written'}`;
+        out(args, txt, r);
+        break;
+      }
+      case 'kit': {
+        if (args._[0] !== 'export') throw new Error('usage: citable kit export --run <run-id> --finding <detector-id> [--target <file>] [--subject <id|url>] [--output <dir>]');
+        const r = await exportImplementationKit(root, {
+          run: args.runId,
+          finding: args.finding,
+          target: args.target,
+          subject: args.subject,
+          output: args.output,
+          format: args.format,
+        });
+        const txt = `kit export ${r.detector_id}
+  Kit directory: ${r.kit_dir}
+  Files: ${r.files.length}
+  Rendering evidence files: ${r.rendering_evidence_count}
+  Patch diff included: ${r.has_patch_diff}`;
+        out(args, txt, r);
+        break;
+      }
+      case 'compatibility': {
+        const r = await compatibilityCommand(root, args);
+        const txt = `compatibility (citable ${r.tool_version}, Node ${r.node})
+${r.checks.map((c) => `  [${c.severity.toUpperCase()}] ${c.check_id}: ${c.detail}`).join('\n')}
+  Blockers: ${r.blocker_count}
+  Note: ${r.note}`;
+        out(args, txt, r);
+        break;
+      }
+      case 'check': {
+        if (args._[0] === 'experiment') {
+          const r = await checkExperiment(root, {
+            experimentId: args._[1],
+            observedControl: args['observed-control'] !== undefined ? Number(args['observed-control']) : undefined,
+            observedVariant: args['observed-variant'] !== undefined ? Number(args['observed-variant']) : undefined,
+            daysRunning: args['days-running'] !== undefined ? Number(args['days-running']) : undefined,
+            baselineRate: args['baseline-rate'],
+            mde: args.mde,
+            pValue: args['p-value'],
+            revenueClaimed: args['revenue-claimed'],
+          });
+          const txt = `check experiment ${r.experiment_id}
+  Lifecycle: ${r.lifecycle} — ${r.lifecycle_definition}
+  Guardrails: ${r.guardrail_count} finding(s)
+${r.findings.map((f) => `  [${f.guardrail_id}] (${f.severity}) ${f.summary}`).join('\n') || '  no guardrail findings'}
+  Note: ${r.note}`;
+          out(args, txt, r);
+          break;
+        }
+        throw new Error('usage: citable check experiment <id> [--observed-control N --observed-variant N --days-running N --p-value X --revenue-claimed]');
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);
@@ -915,6 +1274,56 @@ ${r.recommendations.map((rec) => `    - ${rec}`).join('\n')}`;
         out(args, JSON.stringify(r, null, 2), r);
         break;
       }
+      case 'cro': {
+        const sub = args._[0];
+        if (sub === 'backlog') {
+          const r = await auditCroSuite(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, input: args.input });
+          out(args, formatBacklogMarkdown(r.experiment_backlog), r.experiment_backlog);
+          break;
+        }
+        if (sub === 'roadmap') {
+          const r = await auditCroSuite(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, input: args.input });
+          out(args, formatCroRoadmapMarkdown(r.strategic_roadmap), r.strategic_roadmap);
+          break;
+        }
+        const r = await auditCroSuite(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, input: args.input, funnelId: args.funnel });
+        out(args, formatCroSuiteOutput(r), r);
+        break;
+      }
+      case 'sweep': {
+        const sub = args._[0];
+        if (sub && sub !== 'technical') throw new Error('usage: citable sweep technical [--target <dir|url>]');
+        const r = await sweepTechnical(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate, page: args._[1] });
+        out(args, formatSweepOutput(r), r);
+        break;
+      }
+      case 'matrix': {
+        const r = await prioritizeCommand(['matrix', ...argv.slice(1)], root);
+        out(args, r.formatted || JSON.stringify(r, null, 2), r);
+        break;
+      }
+      case 'roadmap': {
+        const r = await roadmapCommand(root, { runId: args.runId, target: args.target, write: args.write !== false });
+        out(args, r.markdown, r);
+        break;
+      }
+      case 'sow': {
+        const r = await sowCommand(argv.slice(1), root);
+        out(args, r.content || r.message || JSON.stringify(r, null, 2), r.data || r);
+        break;
+      }
+      case 'inspect-eeat': {
+        if (!args._[0]) throw new Error('usage: citable inspect-eeat <page> --target <dir|url>');
+        const r = await inspectEeat(root, args._[0], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+        out(args, formatEeatOutput(r), r);
+        break;
+      }
+      case 'inspect-readiness': {
+        if (!args._[0]) throw new Error('usage: citable inspect-readiness <page> --target <dir|url>');
+        const r = await inspectReadiness(root, args._[0], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+        out(args, formatReadinessOutput(r), r);
+        break;
+      }
       case undefined:
         console.log(HELP);
         break;

package/src/commands/answerEngineReadiness.js

@@ -0,0 +1,48 @@
+import { buildContext } from './context.js';
+import { safePath } from '../detectors/framework.js';
+import { evaluateAnswerEngineReadiness } from '../analysis/readiness.js';
+
+/**
+ * `citable inspect readiness <page>` — evaluate page extraction and readiness across
+ * Perplexity, Bing Copilot, and ChatGPT / SearchGPT.
+ */
+export async function inspectReadiness(root, pageRef, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('inspect readiness requires a site target (built output directory or URL)');
+  const wanted = safePath(pageRef, ctx.site.baseUrl);
+  const page = ctx.site.pages.find((p) => safePath(p.url) === wanted || p.sourceFile === pageRef);
+  if (!page) throw new Error(`page not found in audited output: ${pageRef}`);
+
+  return evaluateAnswerEngineReadiness(page, ctx);
+}
+
+/**
+ * Format terminal output for `citable inspect readiness <page>`
+ */
+export function formatReadinessOutput(r) {
+  const lines = [
+    `Answer-Engine Readiness: ${r.url}`,
+    `==============================================`,
+    `Composite Readiness Score: ${r.composite_readiness_score} / 100`,
+    ``,
+    `ENGINE EVALUATIONS:`,
+    `  Perplexity:   ${r.engines.perplexity.score}/100 [${r.engines.perplexity.status.toUpperCase()}] (Bot: ${r.engines.perplexity.primary_bot})`,
+    `  Bing Copilot: ${r.engines.bing_copilot.score}/100 [${r.engines.bing_copilot.status.toUpperCase()}] (Bot: ${r.engines.bing_copilot.primary_bot})`,
+    `  ChatGPT:      ${r.engines.chatgpt.score}/100 [${r.engines.chatgpt.status.toUpperCase()}] (Bot: ${r.engines.chatgpt.primary_bot})`,
+    ``,
+    `CROSS-ENGINE CAPABILITY MATRIX:`,
+  ];
+
+  for (const row of r.comparison_matrix) {
+    lines.push(`  - ${row.capability.padEnd(28)} | Perplexity: ${row.perplexity.padEnd(10)} | Copilot: ${row.bing_copilot.padEnd(14)} | ChatGPT: ${row.chatgpt}`);
+  }
+
+  if (r.recommendations.length) {
+    lines.push(``, `PRIORITIZED ACTIONS:`);
+    for (const rec of r.recommendations) {
+      lines.push(`  [${rec.priority.toUpperCase()}] (${rec.engine.toUpperCase()}) ${rec.action}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/commands/audit.js

@@ -12,8 +12,8 @@ import { buildEntityGraph } from '../observations/entityGraph.js';
 import { buildSourceIdentityChain } from '../observations/sourceIdentity.js';
 
 /** `citable audit [scope]` — run detectors and produce an evidence package. */
-export async function audit(root, { target, scope, baseUrl, refDate } = {}) {
-  const ctx = await buildContext(root, { target, baseUrl, refDate });
+export async function audit(root, { target, scope, baseUrl, refDate, viewport = null } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate, viewport });
   const detectors = selectDetectors({ scope });
 
   const run = createRun(root, {