@nebulacomponents/citable 1.17.0 → 1.18.1

package/src/analysis/schemaRecommendations.js

@@ -0,0 +1,173 @@
+import { parse as parseHtml } from 'node-html-parser';
+
+const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+const HOWTO_TITLE_RX = /^(?:how\s+to|how\s+do\s+i|step-by-step|guide\s+to)\b/i;
+
+/**
+ * Scan audited site pages for FAQPage, Speakable, and HowTo markup opportunities.
+ */
+export function recommendSchemaForPages(pages = []) {
+  const recommendations = {
+    faq: [],
+    speakable: [],
+    howto: [],
+  };
+
+  for (const page of pages) {
+    if (!page || page.status !== 200) continue;
+    const html = page.html || '';
+    const root = parseHtml(html);
+    const existingTypes = new Set(
+      (page.jsonLd || []).flatMap((j) => j.blocks || []).flatMap((b) => [].concat(b['@type'] || []))
+    );
+
+    // -------------------------------------------------------------
+    // 1. FAQPage Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('FAQPage')) {
+      const qas = [];
+
+      // Pattern A: <details><summary>Q</summary><p>A</p></details>
+      for (const details of root.querySelectorAll('details')) {
+        const summary = details.querySelector('summary');
+        if (summary) {
+          const questionText = summary.text.trim();
+          const clone = parseHtml(details.innerHTML);
+          const s = clone.querySelector('summary');
+          if (s) s.remove();
+          const answerText = clone.text.replace(/\s+/g, ' ').trim();
+          if (questionText && answerText) {
+            qas.push({ question: questionText, answer: answerText });
+          }
+        }
+      }
+
+      // Pattern B: Question headings followed by paragraphs
+      if (qas.length < 2) {
+        const headings = root.querySelectorAll('h2, h3');
+        for (const h of headings) {
+          const hText = h.text.trim();
+          if (QUESTION_RX.test(hText)) {
+            // Find next sibling paragraph
+            let next = h.nextElementSibling;
+            let answerText = '';
+            while (next && !['H1', 'H2', 'H3', 'H4'].includes(next.tagName)) {
+              if (['P', 'UL', 'OL', 'DIV'].includes(next.tagName)) {
+                answerText += (answerText ? ' ' : '') + next.text.replace(/\s+/g, ' ').trim();
+                if (answerText.length > 60) break;
+              }
+              next = next.nextElementSibling;
+            }
+            if (hText && answerText) {
+              qas.push({ question: hText, answer: answerText });
+            }
+          }
+        }
+      }
+
+      if (qas.length >= 2) {
+        recommendations.faq.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'FAQPage',
+          rationale: `Detected ${qas.length} visible question-and-answer pairs without FAQPage schema.`,
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'FAQPage',
+            mainEntity: qas.slice(0, 10).map((qa) => ({
+              '@type': 'Question',
+              name: qa.question,
+              acceptedAnswer: {
+                '@type': 'Answer',
+                text: qa.answer,
+              },
+            })),
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 2. Speakable Recommendation (SpeakableSpecification)
+    // -------------------------------------------------------------
+    const hasExistingSpeakable = (page.jsonLd || []).some((j) =>
+      (j.blocks || []).some((b) => b.speakable)
+    );
+
+    if (!hasExistingSpeakable) {
+      const speakableSelectors = [];
+      if (root.querySelector('h1')) speakableSelectors.push('h1');
+      if (root.querySelector('#summary, .executive-summary, .summary, .key-takeaways')) {
+        speakableSelectors.push(root.querySelector('#summary') ? '#summary' : '.executive-summary');
+      } else if (root.querySelector('article > p:first-of-type, main > p:first-of-type, p:first-of-type')) {
+        speakableSelectors.push('article > p:first-of-type');
+      }
+
+      if (speakableSelectors.length >= 2) {
+        recommendations.speakable.push({
+          target_url: page.url,
+          source_file: page.sourceFile || null,
+          schema_type: 'SpeakableSpecification',
+          rationale: 'Page has clear title and executive lead passage suitable for smart speaker / assistant audio playback.',
+          jsonld: {
+            '@context': 'https://schema.org',
+            '@type': 'WebPage',
+            '@id': `${page.url}#webpage`,
+            url: page.url,
+            name: page.title || 'Page',
+            speakable: {
+              '@type': 'SpeakableSpecification',
+              cssSelector: speakableSelectors,
+            },
+          },
+        });
+      }
+    }
+
+    // -------------------------------------------------------------
+    // 3. HowTo Recommendation
+    // -------------------------------------------------------------
+    if (!existingTypes.has('HowTo')) {
+      const pageTitle = page.title || '';
+      const h1s = (page.headings || []).filter((h) => h.level === 1).map((h) => h.text);
+      const isHowToPage = HOWTO_TITLE_RX.test(pageTitle) || h1s.some((h) => HOWTO_TITLE_RX.test(h));
+
+      if (isHowToPage) {
+        const steps = [];
+        // Look for ordered list items or step subheadings
+        const olItems = root.querySelectorAll('ol > li');
+        if (olItems.length >= 2) {
+          olItems.forEach((li, idx) => {
+            const stepText = li.text.replace(/\s+/g, ' ').trim();
+            if (stepText) {
+              steps.push({
+                '@type': 'HowToStep',
+                position: idx + 1,
+                name: `Step ${idx + 1}`,
+                text: stepText,
+              });
+            }
+          });
+        }
+
+        if (steps.length >= 2) {
+          recommendations.howto.push({
+            target_url: page.url,
+            source_file: page.sourceFile || null,
+            schema_type: 'HowTo',
+            rationale: `Procedural instructional guide detected with ${steps.length} ordered steps.`,
+            jsonld: {
+              '@context': 'https://schema.org',
+              '@type': 'HowTo',
+              name: h1s[0] || pageTitle,
+              description: page.paragraphs?.[0] || 'Procedural guide and instructions.',
+              step: steps,
+            },
+          });
+        }
+      }
+    }
+  }
+
+  return recommendations;
+}

package/src/analysis/strategicRoadmap.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson, nowIso } from '../shared/io.js';
+import { scoreFinding, scoreInitiative } from './iceMatrix.js';
+
+/**
+ * Generate a 30 / 90 / 180-day Strategic Roadmap from audit findings and initiatives.
+ */
+export function buildStrategicRoadmap({ findings = [], initiatives = [], targetDomain = 'example.com' } = {}) {
+  // Score all findings and initiatives with ICE
+  const scoredFindings = findings.map(scoreFinding);
+  const scoredInitiatives = initiatives.map(scoreInitiative);
+
+  // Group into horizons
+  const horizon30 = {
+    horizon: '30_days',
+    label: 'Days 1 - 30: Foundation & Unblock',
+    objective: 'Eliminate catastrophic crawl, index, and Core Web Vitals blockers; establish foundational crawler access and entity identity.',
+    focus_areas: [
+      'Technical SEO: Resolve HTTP non-200 responses, accidental noindex, and canonical contradictions',
+      'Core Web Vitals: Eliminate render-blocking scripts, specify image dimensions (CLS <= 0.1), preload LCP hero images',
+      'Answer Engine Access: Open robots.txt permissions for PerplexityBot, Bingbot, and OAI-SearchBot',
+      'Entity Identity: Deploy baseline Organization and primary Person JSON-LD schemas',
+    ],
+    exit_criteria: [
+      'Zero critical-severity technical findings in citable audit technical',
+      'Static CLS readiness: 100% of body images have explicit dimensions',
+      'All major answer engine bots verified allowed in robots directives',
+      'Baseline Organization schema live with verified @id',
+    ],
+    actions: [],
+  };
+
+  const horizon90 = {
+    horizon: '90_days',
+    label: 'Days 31 - 90: Governance, E-E-A-T & Extractability',
+    objective: 'Elevate on-page E-E-A-T, deploy rich structured data (FAQPage, Speakable, HowTo), audit backlinks, and automate fast indexing.',
+    focus_areas: [
+      'On-Page E-E-A-T: Attribute all content to verified authors, add credentials, visible update dates, and editorial transparency links',
+      'Schema Enrichment: Deploy FAQPage Q&A markup, SpeakableSpecification for audio extraction, and HowTo step schemas',
+      'Fast Indexing: Configure and verify IndexNow protocol connector for instant Bing / search engine notification',
+      'Off-Page Governance: Audit inbound backlink profile, flag toxic PBN/spam TLDs, and compile GSC disavow candidate file',
+      'Claim Substantiation: Map material business claims to evidence registry records',
+    ],
+    exit_criteria: [
+      'Composite E-E-A-T score >= 4.0 / 5.0 across money and content pages',
+      'FAQPage and Speakable schema deployed on all eligible guide/product pages',
+      'IndexNow connection tested and submitting on content updates',
+      'Google Disavow file reviewed and archived in evidence package',
+      'Zero unverified material claims in citable substantiate',
+    ],
+    actions: [],
+  };
+
+  const horizon180 = {
+    horizon: '180_days',
+    label: 'Days 91 - 180: GEO Dominance, Corroboration & Scale',
+    objective: 'Dominate generative search citations across Perplexity, Copilot, and ChatGPT; build digital PR authority; govern conversion experiments.',
+    focus_areas: [
+      'Generative Engine Optimization (GEO): Optimize RAG chunk boundaries (150-350 words) and direct copular definitions ("X is Y")',
+      'Competitive Share-of-Voice: Benchmark brand citation share and sentiment stance across AI engines vs key competitors',
+      'Authority & Corroboration: Earn high-authority primary citations (.edu, .gov, standards bodies, industry reports)',
+      'Conversion Rate Optimization (CRO): Implement accessible Nebula UI components and govern A/B experiment guardrails (SRM, stopping)',
+      'Continuous Governance: Schedule automated version-pinned audit runs with regression alerts',
+    ],
+    exit_criteria: [
+      'Answer-Engine readiness score >= 85/100 across Perplexity, Bing Copilot, and ChatGPT',
+      'Weekly automated continuous audit pipeline with regression monitoring active',
+      'Dominant citation share on primary category prompts in AI search engine probes',
+      'Zero statistically invalid experiment decisions (SRM < 0.001)',
+    ],
+    actions: [],
+  };
+
+  // Map findings into horizons based on urgency and discipline
+  for (const f of scoredFindings) {
+    const ns = (f.id || '').split('-')[0];
+    if (f.severity === 'critical' || ['TECH', 'CRAWL', 'STATUS'].includes(ns)) {
+      horizon30.actions.push(f);
+    } else if (f.severity === 'high' || ['CWV', 'SCHEMA', 'PAGE', 'LINK'].includes(ns)) {
+      if (['CWV-001', 'CWV-004'].includes(f.id)) horizon30.actions.push(f);
+      else horizon90.actions.push(f);
+    } else if (['ANS', 'ENTITY', 'CLAIM', 'EVD'].includes(ns)) {
+      horizon90.actions.push(f);
+    } else {
+      horizon180.actions.push(f);
+    }
+  }
+
+  // Map initiatives into horizons
+  for (const i of scoredInitiatives) {
+    if (i.impact >= 8 && i.effort <= 4) {
+      horizon30.actions.push(i);
+    } else if (i.impact >= 6) {
+      horizon90.actions.push(i);
+    } else {
+      horizon180.actions.push(i);
+    }
+  }
+
+  return {
+    fact_status: 'strategic_roadmap_projection',
+    target_domain: targetDomain,
+    generated_at: nowIso(),
+    methodology: 'Horizon Phasing: 30-Day (Critical Unblock & Core CWV) -> 90-Day (E-E-A-T, Schema & Off-Page) -> 180-Day (GEO Dominance & PR)',
+    horizons: [horizon30, horizon90, horizon180],
+  };
+}
+
+/**
+ * Format Strategic Roadmap as GitHub-flavored Markdown
+ */
+export function formatRoadmapMarkdown(roadmap) {
+  const lines = [
+    `# 30 / 90 / 180-Day Strategic Roadmap`,
+    ``,
+    `- Target Property: \`${roadmap.target_domain}\``,
+    `- Generated: ${roadmap.generated_at}`,
+    `- Governance Methodology: ${roadmap.methodology}`,
+    ``,
+    `> **Operating Premise Reminder**: This roadmap sequences verified remediation priorities and strategic enhancements. It establishes technical eligibility and extractability, but never guarantees ranking, traffic, or citation outcomes.`,
+    ``,
+  ];
+
+  for (const h of roadmap.horizons) {
+    lines.push(`## ${h.label}`);
+    lines.push(``);
+    lines.push(`**Objective**: ${h.objective}`);
+    lines.push(``);
+    lines.push(`### Strategic Focus Areas:`);
+    for (const f of h.focus_areas) lines.push(`- ${f}`);
+    lines.push(``);
+    lines.push(`### Exit Criteria & Success Milestones:`);
+    for (const c of h.exit_criteria) lines.push(`- [ ] ${c}`);
+    lines.push(``);
+    if (h.actions.length) {
+      lines.push(`### Prioritized Actions (${h.actions.length}):`);
+      lines.push(`| Action / Initiative | Impact | Effort | Conf | ICE Score | Quadrant |`);
+      lines.push(`| :--- | :--- | :--- | :--- | :--- | :--- |`);
+      for (const a of h.actions.slice(0, 10)) {
+        lines.push(`| **${a.id}**: ${a.title.slice(0, 45)} | ${a.impact}/10 | ${a.effort}/10 | ${a.confidence}/10 | **${a.ice_score}** | ${a.quadrant} |`);
+      }
+      lines.push(``);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/cli/index.js

@@ -1,4 +1,14 @@
 #!/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';
@@ -97,6 +107,15 @@ Commands
   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
@@ -109,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)
@@ -287,6 +308,12 @@ function parseArgs(argv) {
     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);
   }
@@ -360,6 +387,16 @@ 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>');
@@ -386,6 +423,18 @@ ${r.findings.map((f) => `  [${f.rule_id}] (${f.severity}) ${f.summary}\n    Fix:
       }
       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 });
@@ -409,7 +458,9 @@ ${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'}
@@ -746,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;
@@ -798,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;
       }
@@ -1178,6 +1274,56 @@ ${r.findings.map((f) => `  [${f.guardrail_id}] (${f.severity}) ${f.summary}`).jo
         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/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');
+}