@nebulacomponents/citable 1.17.0 → 1.18.1

package/src/commands/croBacklog.js

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

package/src/commands/croSuite.js

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildContext } from './context.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors, indexTargets, pageSubject, safePath } from '../detectors/framework.js';
+import { auditPageCro } from '../analysis/croAudit.js';
+import { analyzeConversionFunnel } from '../analysis/funnelAnalysis.js';
+import { analyzeBehavioralTelemetry } from '../analysis/behavioral.js';
+import { generateExperimentBacklog, formatBacklogMarkdown } from './croBacklog.js';
+import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
+import { buildCroRoadmap, formatCroRoadmapMarkdown } from '../analysis/croRoadmap.js';
+
+/**
+ * Full End-to-End CRO Intelligence Suite Audit
+ */
+export async function auditCroSuite(root, { target, baseUrl, refDate, input, funnelId, write = false } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('cro audit requires a site target (built output directory or URL)');
+
+  // 1. Run CRO detectors across all pages
+  const croDetectors = selectDetectors({ namespaces: ['CRO'] });
+  const { findings } = runDetectors(croDetectors, ctx);
+
+  const pages = indexTargets(ctx);
+
+  // 2. Above-the-fold clarity, trust, cognitive load, offer architecture per page
+  const auditedPages = pages.map((page) => auditPageCro(page, ctx));
+
+  // Average scores across commercial pages
+  const commercialPages = auditedPages.filter((p) => {
+    const u = (p.url || '').toLowerCase();
+    return u.includes('pricing') || u.includes('product') || u.includes('feature') || u.includes('checkout') || u.endsWith('/') || u.includes('landing');
+  });
+  const targetGroup = commercialPages.length > 0 ? commercialPages : auditedPages;
+
+  const avgAtfClarity = targetGroup.length > 0
+    ? Math.round(targetGroup.reduce((acc, p) => acc + p.atf_clarity.score, 0) / targetGroup.length)
+    : 0;
+
+  const avgTrustScore = targetGroup.length > 0
+    ? Math.round(targetGroup.reduce((acc, p) => acc + p.trust_and_credibility.score, 0) / targetGroup.length)
+    : 0;
+
+  const avgConversionReadiness = targetGroup.length > 0
+    ? Math.round(targetGroup.reduce((acc, p) => acc + p.conversion_readiness_score, 0) / targetGroup.length)
+    : 0;
+
+  // 3. End-to-end Funnel and Conversion-Path Analysis
+  const declaredFunnel = (ctx.registries?.funnels?.entries || []).find((f) => funnelId ? f.funnel_id === funnelId : true) || null;
+  const funnelAnalysis = analyzeConversionFunnel(ctx.site.pages, declaredFunnel);
+
+  // 4. Behavioral Evidence Analysis (if telemetry file provided)
+  let behavioralAnalysis = null;
+  if (input) {
+    const filePath = path.resolve(root, input);
+    if (fs.existsSync(filePath)) {
+      try {
+        const rawTelemetry = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        behavioralAnalysis = analyzeBehavioralTelemetry(rawTelemetry);
+      } catch (err) {
+        // Non-blocking parse error
+      }
+    }
+  }
+
+  // 5. Experiment Backlog with Falsifiable Hypotheses
+  const experimentBacklog = generateExperimentBacklog(findings);
+
+  // 6. Impact / Effort / Confidence (ICE) Prioritization Matrix
+  const iceMatrix = buildIceMatrix(findings, { type: 'findings' });
+
+  // 7. 30 / 90 / 180-Day CRO Strategic Roadmap tied to Measurable Conversion Outcomes
+  const targetDomain = ctx.site.baseUrl ? new URL(ctx.site.baseUrl).hostname : 'target-site';
+  const croRoadmap = buildCroRoadmap({
+    findings,
+    targetDomain,
+  });
+
+  const result = {
+    fact_status: 'modeled_cro_evaluation',
+    target: ctx.site.baseUrl || target,
+    total_pages_audited: pages.length,
+    summary: {
+      conversion_readiness_score: avgConversionReadiness,
+      atf_clarity_score: avgAtfClarity,
+      trust_credibility_score: avgTrustScore,
+      funnel_health_score: funnelAnalysis.funnel_health_score,
+      total_cro_findings: findings.length,
+      planned_experiments: experimentBacklog.total_experiments,
+      quick_wins_count: iceMatrix.summary.quick_wins_count,
+    },
+    funnel_analysis: funnelAnalysis,
+    pages: auditedPages,
+    behavioral_telemetry: behavioralAnalysis,
+    experiment_backlog: experimentBacklog,
+    ice_matrix: iceMatrix,
+    strategic_roadmap: croRoadmap,
+    findings: findings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      subject: f.subject.identifier || f.subject.url,
+      summary: f.observation.summary,
+      remediation: f.remediation?.preferred,
+    })),
+  };
+
+  return result;
+}
+
+/**
+ * Format Human-Readable CRO Suite Terminal Report
+ */
+export function formatCroSuiteOutput(r) {
+  const lines = [
+    `Conversion Rate Optimization (CRO) & Journey Intelligence Suite`,
+    `==============================================================`,
+    `Target: ${r.target}`,
+    `Audited Pages: ${r.total_pages_audited} | Conversion Readiness Score: ${r.summary.conversion_readiness_score}/100`,
+    ``,
+    `CORE PILLAR SCORES:`,
+    `  Above-The-Fold Clarity & Message Match:  ${r.summary.atf_clarity_score} / 100`,
+    `  Trust, Credibility & Risk-Reversal:      ${r.summary.trust_credibility_score} / 100`,
+    `  End-to-End Funnel Health:                ${r.summary.funnel_health_score} / 100 (${r.funnel_analysis.status.toUpperCase()})`,
+    `  Active CRO Findings:                     ${r.summary.total_cro_findings} defect(s)`,
+    ``,
+    `END-TO-END CONVERSION PATH ANALYSIS (${r.funnel_analysis.funnel_name}):`,
+  ];
+
+  for (const s of r.funnel_analysis.steps) {
+    const status = s.continuity_intact ? 'INTACT' : 'BROKEN';
+    lines.push(`  Step ${s.step}: [${s.role.toUpperCase()}] ${s.name} (${s.url}) → ${status} (Drop-off risk: ${s.drop_off_risk.toUpperCase()})`);
+  }
+
+  if (r.funnel_analysis.leaks.length) {
+    lines.push(``, `Identified Conversion Leaks:`);
+    for (const leak of r.funnel_analysis.leaks) {
+      lines.push(`  - [${leak.severity.toUpperCase()}] (${leak.type}) ${leak.description}`);
+    }
+  }
+
+  lines.push(``, `EXPERIMENTATION BACKLOG (${r.experiment_backlog.total_experiments} falsifiable hypotheses generated):`);
+  for (const exp of r.experiment_backlog.experiments.slice(0, 5)) {
+    lines.push(`  [${exp.ice_prioritization.quadrant.toUpperCase()}] ${exp.experiment_id}: ${exp.title} (Expected MDE: +${exp.statistical_setup.expected_mde_pct}%, ICE: ${exp.ice_prioritization.ice_score})`);
+    lines.push(`    Hypothesis: "${exp.hypothesis}"`);
+  }
+
+  lines.push(``, `30 / 90 / 180-DAY CRO STRATEGIC ROADMAP:`);
+  for (const h of r.strategic_roadmap.horizons) {
+    lines.push(`  ${h.label}:`);
+    lines.push(`    Goal: ${h.objective}`);
+    lines.push(`    Target KPI: ${h.measurable_conversion_kpi}`);
+    lines.push(`    Sequenced Experiments: ${h.experiments.length} experiment(s)`);
+  }
+
+  return lines.join('\n');
+}

package/src/commands/executive.js

@@ -45,6 +45,8 @@ const ROUTES = [
   { patterns: [/variance|miss|why.did.we/i],                 command: 'variance',             reason: 'Variance analysis' },
   { patterns: [/prioriti|roadmap|what.to.build|rank/i],      command: 'prioritize',           reason: 'Initiative prioritization' },
   { patterns: [/competitor|competitive|market.change/i],     command: 'competitive-intel',    reason: 'Competitive intelligence' },
+  { patterns: [/search|seo|aeo|geo|serp/i],                 command: 'executive-search',     reason: 'Enterprise Search & AEO/GEO Executive Report' },
+  { patterns: [/cro|conversion|funnel|journey/i],            command: 'executive-cro',        reason: 'Enterprise CRO & Journey Intelligence Executive Report' },
 ];
 
 const MAX_DEPTH = 1;
@@ -119,6 +121,8 @@ function commandToModule(cmd) {
     'variance':           'variance',
     'prioritize':         'prioritize',
     'competitive-intel':  'competitiveIntel',
+    'executive-search':   'executiveSearch',
+    'executive-cro':      'executiveCro',
   };
   return MAP[cmd] ?? cmd;
 }
@@ -136,6 +140,8 @@ function commandToExport(cmd) {
     'variance':           'varianceCommand',
     'prioritize':         'prioritizeCommand',
     'competitive-intel':  'competitiveIntelCommand',
+    'executive-search':   'executiveSearchCommand',
+    'executive-cro':      'executiveCroCommand',
   };
   return MAP[cmd] ?? cmd + 'Command';
 }

package/src/commands/executiveCro.js

@@ -0,0 +1,30 @@
+import { exportExecutiveCroReport } from '../reporting/executiveCroReport.js';
+
+export async function executiveCroCommand(args = [], root = process.cwd()) {
+  const target = argVal(args, '--target');
+  const baseUrl = argVal(args, '--base-url');
+  const runId = argVal(args, '--run');
+  const client = argVal(args, '--client');
+  const format = args.includes('--json') ? 'json' : argVal(args, '--format') || 'markdown';
+  const output = argVal(args, '--output');
+  const input = argVal(args, '--input');
+  const funnel = argVal(args, '--funnel');
+
+  const r = await exportExecutiveCroReport(root, {
+    target,
+    baseUrl,
+    runId,
+    clientName: client || 'Enterprise Client',
+    format,
+    output,
+    telemetryInput: input,
+    funnelId: funnel,
+  });
+
+  return format === 'json' ? r.data : r.content;
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/executiveSearch.js

@@ -0,0 +1,28 @@
+import { exportExecutiveSearchReport } from '../reporting/executiveSearchReport.js';
+
+export async function executiveSearchCommand(args = [], root = process.cwd()) {
+  const target = argVal(args, '--target');
+  const baseUrl = argVal(args, '--base-url');
+  const runId = argVal(args, '--run');
+  const client = argVal(args, '--client');
+  const format = args.includes('--json') ? 'json' : argVal(args, '--format') || 'markdown';
+  const output = argVal(args, '--output');
+  const input = argVal(args, '--input');
+
+  const r = await exportExecutiveSearchReport(root, {
+    target,
+    baseUrl,
+    runId,
+    clientName: client || 'Enterprise Client',
+    format,
+    output,
+    backlinksInput: input,
+  });
+
+  return format === 'json' ? r.data : r.content;
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/inspectCro.js

@@ -1,3 +1,4 @@
+import { auditPageCro } from "../analysis/croAudit.js";
 import { buildContext } from './context.js';
 import { registryPageFor, safePath } from '../detectors/framework.js';
 import { selectDetectors } from '../detectors/index.js';
@@ -74,8 +75,14 @@ export async function inspectCro(root, pageRef, { target, baseUrl, refDate } = {
     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,

package/src/commands/inspectEeat.js

@@ -0,0 +1,53 @@
+import { buildContext } from './context.js';
+import { safePath } from '../detectors/framework.js';
+import { evaluateEeat } from '../analysis/eeat.js';
+
+/**
+ * `citable inspect eeat <page>` — evaluate on-page content against the E-E-A-T rubric (0-5 scale).
+ */
+export async function inspectEeat(root, pageRef, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('inspect eeat 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 evaluateEeat(page, ctx);
+}
+
+/**
+ * Format terminal output for `citable inspect eeat <page>`
+ */
+export function formatEeatOutput(r) {
+  const lines = [
+    `Inspect E-E-A-T: ${r.url}`,
+    `========================================`,
+    `Composite Score: ${r.composite_score} / 5.0 [${r.overall_rating.toUpperCase()}]`,
+    `Status: ${r.fact_status} (Google Search Quality Rater Guidelines rubric)`,
+    ``,
+    `DIMENSIONS (0.0 - 5.0 scale):`,
+    `  Experience:        ${r.dimensions.experience.score} / 5.0`,
+    `  Expertise:         ${r.dimensions.expertise.score} / 5.0 (Author: ${r.dimensions.expertise.author || 'unattributed'})`,
+    `  Authoritativeness: ${r.dimensions.authoritativeness.score} / 5.0`,
+    `  Trustworthiness:   ${r.dimensions.trustworthiness.score} / 5.0 (Foundational Base)`,
+    ``,
+    `OBSERVED POSITIVE SIGNALS:`,
+  ];
+
+  for (const [dim, val] of Object.entries(r.dimensions)) {
+    if (val.signals.length) {
+      lines.push(`  ${dim.toUpperCase()}:`);
+      for (const s of val.signals) lines.push(`    ✓ ${s}`);
+    }
+  }
+
+  if (r.actionable_improvements.length) {
+    lines.push(``, `ACTIONABLE IMPROVEMENTS:`);
+    for (const item of r.actionable_improvements) {
+      lines.push(`  - [${item.dimension.toUpperCase()}] ${item.recommendation}`);
+    }
+  }
+
+  lines.push(``, `Note: ${r.disclaimer}`);
+  return lines.join('\n');
+}

package/src/commands/prioritize.js

@@ -1,19 +1,21 @@
 /**
- * prioritize command — Initiative Prioritization
+ * prioritize command — Initiative and Finding Prioritization (ICE Matrix)
  *
- * Ranks roadmap and investment choices. Weights must be visible when
- * weighted scoring is used — no opaque scores.
+ * Ranks roadmap, audit findings, and investment choices.
+ * Weights and factors must be visible when weighted scoring is used — no opaque scores.
  *
  * Usage:
  *   citable prioritize [--status proposed|approved]
  *   citable prioritize show <initiative_id>
  *   citable prioritize validate
- *   citable prioritize rank   — ranked list with explicit criteria
+ *   citable prioritize rank     — ranked list with explicit criteria
+ *   citable prioritize matrix   — Impact/Effort/Confidence (ICE) scoring matrix
  */
+import fs from 'node:fs';
+import path from 'node:path';
 import { contextDir, loadRegistryFile, registryLoadProblems } from '../registries/index.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
-import path from 'node:path';
-
+import { buildIceMatrix, formatIceMatrixOutput } from '../analysis/iceMatrix.js';
 
 const SCALE = { none: 0, low: 1, medium: 2, high: 3, critical: 4, validated: 4, transformative: 4, trivial: 0, very_high: 4, negligible: 0, 'n/a': 0 };
 
@@ -25,6 +27,7 @@ export async function prioritizeCommand(args, root = process.cwd()) {
     case 'show':     return initiativeShow(file, rest[0]);
     case 'validate': return initiativeValidate(file);
     case 'rank':     return initiativeRank(file);
+    case 'matrix':   return initiativeMatrix(file, root, rest);
     case 'list':
     default: {
       const statusFilter = rest[rest.indexOf('--status') + 1] ?? null;
@@ -86,6 +89,39 @@ function initiativeRank(file) {
   };
 }
 
+function initiativeMatrix(file, root, rest = []) {
+  const runIdx = rest.indexOf('--run');
+  const runId = runIdx !== -1 ? rest[runIdx + 1] : null;
+
+  if (runId) {
+    const findingsPath = path.join(root, '.citable', 'runs', runId, 'findings.json');
+    if (!fs.existsSync(findingsPath)) throw new Error(`run ${runId} findings.json not found`);
+    const findings = JSON.parse(fs.readFileSync(findingsPath, 'utf8'));
+    const matrix = buildIceMatrix(findings, { type: 'findings' });
+    return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
+  }
+
+  // Check if findings.json exists in latest run
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (fs.existsSync(runsDir)) {
+    const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort().reverse();
+    if (runs.length > 0 && rest.includes('--findings')) {
+      const findings = JSON.parse(fs.readFileSync(path.join(runsDir, runs[0], 'findings.json'), 'utf8'));
+      const matrix = buildIceMatrix(findings, { type: 'findings' });
+      return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
+    }
+  }
+
+  // Default: score initiatives from initiatives.yaml
+  if (fs.existsSync(file)) {
+    const data = load(file);
+    const matrix = buildIceMatrix(data.entries || [], { type: 'initiatives' });
+    return { ...matrix, formatted: formatIceMatrixOutput(matrix) };
+  }
+
+  throw new Error('prioritize matrix requires initiatives.yaml or an audit run (--run <run-id>)');
+}
+
 function initiativeValidate(file) {
   const data = load(file);
   const problems = [...registryLoadProblems(data)];

package/src/commands/roadmapCmd.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { contextDir, loadRegistryFile } from '../registries/index.js';
+import { readJson, writeJson } from '../shared/io.js';
+import { buildStrategicRoadmap, formatRoadmapMarkdown } from '../analysis/strategicRoadmap.js';
+
+/**
+ * `citable roadmap [generate|show]` — generate or view the 30/90/180-day strategic roadmap.
+ */
+export async function roadmapCommand(root, { runId, target, write = true } = {}) {
+  let findings = [];
+  let initiatives = [];
+
+  // 1. Load findings from specified or latest run
+  const runsDir = path.join(root, '.citable', 'runs');
+  let sourceRun = runId;
+  if (!sourceRun && fs.existsSync(runsDir)) {
+    const runs = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort();
+    if (runs.length) sourceRun = runs.at(-1);
+  }
+
+  if (sourceRun) {
+    const findingsFile = path.join(runsDir, sourceRun, 'findings.json');
+    if (fs.existsSync(findingsFile)) {
+      findings = JSON.parse(fs.readFileSync(findingsFile, 'utf8'));
+    }
+  }
+
+  // 2. Load initiatives if present
+  const initFile = path.join(contextDir(root), 'initiatives.yaml');
+  if (fs.existsSync(initFile)) {
+    try {
+      const data = loadRegistryFile(initFile, 'initiatives');
+      initiatives = data.entries || [];
+    } catch {
+      // Ignore non-fatal registry load problems
+    }
+  }
+
+  // Target domain resolution
+  let domain = target || 'nebulacomponents.com';
+  if (sourceRun) {
+    const manifestFile = path.join(runsDir, sourceRun, 'manifest.json');
+    if (fs.existsSync(manifestFile)) {
+      try {
+        const manifest = readJson(manifestFile);
+        if (manifest.target?.location) domain = manifest.target.location;
+      } catch {}
+    }
+  }
+
+  const roadmap = buildStrategicRoadmap({ findings, initiatives, targetDomain: domain });
+  const markdown = formatRoadmapMarkdown(roadmap);
+
+  let artifactPath = null;
+  if (write) {
+    const outDir = path.join(root, '.citable', 'roadmap');
+    fs.mkdirSync(outDir, { recursive: true });
+    artifactPath = path.join(outDir, 'strategic-roadmap.md');
+    fs.writeFileSync(artifactPath, markdown, 'utf8');
+    writeJson(path.join(outDir, 'strategic-roadmap.json'), roadmap);
+  }
+
+  return {
+    ...roadmap,
+    markdown,
+    artifact_path: artifactPath,
+  };
+}

package/src/commands/schemaCmd.js

@@ -2,9 +2,11 @@ import { buildContext } from './context.js';
 import { selectDetectors } from '../detectors/index.js';
 import { runDetectors, sitePageFor } from '../detectors/framework.js';
 import { checklistItem, toStringArray } from '../shared/checklist.js';
+import { recommendSchemaForPages } from '../analysis/schemaRecommendations.js';
 
 /**
- * `citable schema` — derive JSON-LD proposals from registry data and validate deployed schema.
+ * `citable schema` — derive JSON-LD proposals from registry data, recommend FAQPage, Speakable,
+ * and HowTo markup from visible page content, and validate deployed schema.
  *
  * Generation is registry-driven: schema is only proposed for entities that exist in the
  * entity registry with a canonical URL. Nothing is fabricated; missing fields are listed
@@ -71,5 +73,11 @@ export async function schemaCommand(root, { target, baseUrl, refDate } = {}) {
     }
   }
 
-  return { findings, proposals, blocked, missingDeployment };
+  // 4. Recommend structural schema markup (FAQPage, Speakable, HowTo) from visible content
+  let recommendations = { faq: [], speakable: [], howto: [] };
+  if (ctx.site?.pages) {
+    recommendations = recommendSchemaForPages(ctx.site.pages);
+  }
+
+  return { findings, proposals, blocked, missingDeployment, recommendations };
 }