@nebulacomponents/citable 1.15.1 → 1.17.0

package/src/commands/fleet.js

@@ -0,0 +1,104 @@
+import path from "node:path";
+import fs from "node:fs";
+import { loadRegistries, contextDir } from "../registries/index.js";
+import { audit } from "./audit.js";
+
+/**
+ * Returns summary of all properties defined in the fleet registry.
+ */
+export async function fleetSummary(root) {
+  const { registries } = loadRegistries(root);
+  const fleet = registries?.fleet?.entries || [];
+
+  const byEnv = {};
+  const byOwner = {};
+  for (const p of fleet) {
+    byEnv[p.environment] = (byEnv[p.environment] || 0) + 1;
+    if (p.owner) byOwner[p.owner] = (byOwner[p.owner] || 0) + 1;
+  }
+
+  return {
+    total_properties: fleet.length,
+    active_properties: fleet.filter((p) => p.status === "active").length,
+    by_environment: byEnv,
+    by_owner: byOwner,
+    properties: fleet.map((p) => ({
+      property_id: p.property_id,
+      name: p.name,
+      environment: p.environment,
+      primary_domain: p.primary_domain,
+      status: p.status,
+      owner: p.owner,
+    })),
+  };
+}
+
+/**
+ * Runs fleet-wide audit across registered fleet properties.
+ */
+export async function fleetAudit(root, { propertyId = null, environment = null, scope = null } = {}) {
+  const { registries } = loadRegistries(root);
+  const fleet = registries?.fleet?.entries || [];
+
+  if (fleet.length === 0) {
+    throw new Error("no fleet properties declared in registries (expected .citable/fleet.yaml)");
+  }
+
+  let targets = fleet.filter((p) => p.status === "active");
+  if (propertyId) {
+    targets = targets.filter((p) => p.property_id === propertyId || p.primary_domain === propertyId);
+    if (targets.length === 0) throw new Error(`property "${propertyId}" not found in active fleet`);
+  }
+  if (environment) {
+    targets = targets.filter((p) => p.environment === environment);
+  }
+
+  const results = [];
+  for (const prop of targets) {
+    const propTarget = prop.built_output_dir && fs.existsSync(path.resolve(root, prop.built_output_dir))
+      ? path.resolve(root, prop.built_output_dir)
+      : null;
+
+    let auditRes = null;
+    let error = null;
+
+    try {
+      if (propTarget || prop.base_url) {
+        auditRes = await audit(root, {
+          target: propTarget || prop.base_url,
+          baseUrl: prop.base_url,
+          scope,
+        });
+      }
+    } catch (err) {
+      error = err.message;
+    }
+
+    results.push({
+      property_id: prop.property_id,
+      name: prop.name,
+      primary_domain: prop.primary_domain,
+      environment: prop.environment,
+      status: auditRes ? "audited" : (error ? "error" : "skipped"),
+      findings_count: auditRes?.findings?.length ?? 0,
+      critical_count: auditRes?.findings?.filter((f) => f.severity === "critical").length ?? 0,
+      high_count: auditRes?.findings?.filter((f) => f.severity === "high").length ?? 0,
+      medium_count: auditRes?.findings?.filter((f) => f.severity === "medium").length ?? 0,
+      low_count: auditRes?.findings?.filter((f) => f.severity === "low").length ?? 0,
+      error,
+    });
+  }
+
+  const totalFindings = results.reduce((acc, r) => acc + r.findings_count, 0);
+  const totalCritical = results.reduce((acc, r) => acc + r.critical_count, 0);
+  const totalHigh = results.reduce((acc, r) => acc + r.high_count, 0);
+
+  return {
+    fleet_size: targets.length,
+    total_findings: totalFindings,
+    total_critical: totalCritical,
+    total_high: totalHigh,
+    fleet_health: totalCritical === 0 && totalHigh === 0 ? "healthy" : (totalCritical > 0 ? "critical" : "needs_attention"),
+    properties: results,
+  };
+}

package/src/commands/generateLlmsTxt.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadRegistries } from '../registries/index.js';
+
+/**
+ * Build spec-compliant /llms.txt and /llms-full.txt from Citable registries.
+ * Adheres to https://llmstxt.org/ standard:
+ * - H1 title with brand/project name
+ * - Blockquote summary
+ * - Markdown links with descriptions
+ * - Optional links section pointing to /llms-full.txt
+ */
+export function buildLlmsTxt(root, options = {}) {
+  const { registries } = loadRegistries(root);
+  const siteConfig = registries.config?.site || {};
+  const siteName = siteConfig.name || registries.entities?.entries?.[0]?.canonical_name || 'Project Documentation';
+  const siteUrl = options.siteUrl || siteConfig.base_url || 'https://example.test';
+  const description = siteConfig.description || registries.entities?.entries?.[0]?.description || 'Evidence-backed documentation and verified specifications.';
+
+  const pages = (registries.pages?.entries || []).filter((p) => !p.noindex);
+  const claims = (registries.claims?.entries || []).filter((c) => ['verified', 'verified_narrowed', 'stated'].includes(c.status));
+
+  // Build llms.txt
+  const lines = [];
+  lines.push(`# ${siteName}`);
+  lines.push('');
+  lines.push(`> ${description}`);
+  lines.push('');
+
+  if (pages.length > 0) {
+    lines.push('## Documentation & Key Pages');
+    lines.push('');
+    for (const p of pages) {
+      const url = p.url ? p.url : new URL(p.path || '/', siteUrl).href;
+      const title = p.title || p.page_id || 'Untitled page';
+      const desc = p.description ? `: ${p.description}` : '';
+      lines.push(`- [${title}](${url})${desc}`);
+    }
+    lines.push('');
+  }
+
+  if (claims.length > 0) {
+    lines.push('## Verified Capabilities & Claims');
+    lines.push('');
+    for (const c of claims) {
+      const target = c.publication_surfaces?.[0] || siteUrl;
+      const fullUrl = target.startsWith('http') ? target : new URL(target, siteUrl).href;
+      lines.push(`- [${c.claim}](${fullUrl}): Verified claim (${c.claim_type})`);
+    }
+    lines.push('');
+  }
+
+  lines.push('## Optional');
+  lines.push('');
+  const fullUrl = new URL('/llms-full.txt', siteUrl).href;
+  lines.push(`- [Full Content Directory](${fullUrl}): Complete uncompressed documentation representation`);
+  lines.push('');
+
+  const llmsTxt = lines.join('\n');
+
+  // Build llms-full.txt
+  const fullLines = [];
+  fullLines.push(`# ${siteName} (Full Text Specification)`);
+  fullLines.push('');
+  fullLines.push(`> Complete textual representation of ${siteName} for generative engines and autonomous agents.`);
+  fullLines.push('');
+  for (const p of pages) {
+    const url = p.url ? p.url : new URL(p.path || '/', siteUrl).href;
+    fullLines.push(`### ${p.title || p.page_id}`);
+    fullLines.push(`- URL: ${url}`);
+    if (p.description) fullLines.push(`- Description: ${p.description}`);
+    if (p.published_claims?.length) fullLines.push(`- Published Claims: ${p.published_claims.join(', ')}`);
+    fullLines.push('');
+  }
+  const llmsFullTxt = fullLines.join('\n');
+
+  return {
+    siteName,
+    siteUrl,
+    llmsTxt,
+    llmsFullTxt,
+    pageCount: pages.length,
+    claimCount: claims.length,
+  };
+}
+
+export function generateLlmsTxt(root, options = {}) {
+  const built = buildLlmsTxt(root, options);
+  const outDir = options.output || root;
+
+  let written = false;
+  let llmsTxtPath = null;
+  let llmsFullTxtPath = null;
+
+  if (options.write) {
+    fs.mkdirSync(outDir, { recursive: true });
+    llmsTxtPath = path.join(outDir, 'llms.txt');
+    llmsFullTxtPath = path.join(outDir, 'llms-full.txt');
+    fs.writeFileSync(llmsTxtPath, built.llmsTxt, 'utf8');
+    fs.writeFileSync(llmsFullTxtPath, built.llmsFullTxt, 'utf8');
+    written = true;
+  }
+
+  return {
+    ...built,
+    written,
+    outputDir: outDir,
+    llmsTxtPath,
+    llmsFullTxtPath,
+  };
+}

package/src/commands/goldenCorpus.js

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

package/src/commands/implementationKit.js

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

package/src/commands/inspectAeo.js

@@ -0,0 +1,74 @@
+import { buildContext } from './context.js';
+import { registryPageFor, safePath } from '../detectors/framework.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors } from '../detectors/framework.js';
+
+/**
+ * `citable inspect aeo <page>` — evaluate page answer extractability, question density,
+ * direct lead conciseness, grounded quantitative metrics, and synthesis readiness.
+ */
+export async function inspectAeo(root, pageRef, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('inspect aeo 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}`);
+
+  const reg = registryPageFor(ctx, page);
+
+  // Evaluate findings for this single page across ANS namespace
+  const single = { ...ctx, site: { ...ctx.site, pages: [page] } };
+  const { findings } = runDetectors(selectDetectors({ namespaces: ['ANS'] }), single);
+  const aeoFindings = findings.filter((f) => f.subject.identifier === page.url || f.subject.url === page.url);
+
+  // Analyze question headings and answer leads
+  const QUESTION_RX = /^(?:how|what|why|when|where|who|can|is|does|which|should)\b|\?$/i;
+  const questionHeadings = (page.headings || []).filter((h) => QUESTION_RX.test(h.text.trim()));
+
+  // Definitional copula check
+  const COPULA_RX = /\b(?:is|are|refers\s+to|denotes|represents|means)\b/i;
+  const firstParagraph = (page.paragraphs && page.paragraphs[0]) || '';
+  const hasCopularDefinition = COPULA_RX.test(firstParagraph.slice(0, 140));
+
+  // Structured elements
+  const tablesCount = (page.tables || []).length;
+  const listsCount = (page.orderedLists || []).length;
+
+  // Executive summary
+  const SUMMARY_RX = /\b(?:executive\s+summary|key\s+takeaways?|summary|overview|at\s+a\s+glance|tl;?dr|quick\s+summary|highlights?)\b/i;
+  const hasExecutiveSummary = (page.headings || []).some((h) => SUMMARY_RX.test(h.text));
+
+  // Determine synthesis posture
+  let extractabilityStatus = 'optimal';
+  if (aeoFindings.some((f) => f.classification.severity === 'high')) {
+    extractabilityStatus = 'obstructed';
+  } else if (aeoFindings.length >= 2) {
+    extractabilityStatus = 'suboptimal';
+  } else if (aeoFindings.length === 1) {
+    extractabilityStatus = 'minor_improvements';
+  }
+
+  return {
+    url: page.url,
+    sourceFile: page.sourceFile,
+    status: page.status,
+    page_type: reg?.page_type ?? null,
+    word_count: page.rawVisibleWordCount || page.wordCount || 0,
+    extractability_status: extractabilityStatus,
+    headings: {
+      total: (page.headings || []).length,
+      questions: questionHeadings.map((h) => ({ level: h.level, text: h.text })),
+    },
+    answer_structure: {
+      has_copular_definition: hasCopularDefinition,
+      has_executive_summary: hasExecutiveSummary,
+      tables_count: tablesCount,
+      ordered_lists_count: listsCount,
+    },
+    findings: aeoFindings.map((f) => ({
+      detector_id: f.detector_id,
+      severity: f.classification.severity,
+      summary: f.observation.summary,
+    })),
+  };
+}