@nebulacomponents/citable 0.1.0

package/skill/rubrics/semantic-clarity.md

@@ -0,0 +1,42 @@
+# Rubric: semantic clarity
+
+Judges whether a page's subject, terminology, and relationships are unambiguous
+to a system that has never seen the organization before.
+
+## Scoring dimensions
+
+1. **Single subject** — one primary entity/concept per page; competitors for
+   attention (multiple unrelated H2 topics) lower the score.
+2. **Controlled terminology** — one canonical term used consistently; variants
+   only if registered as aliases (ENTITY-006 flags drift deterministically;
+   this rubric judges whether the drift is meaningful or benign inflection).
+3. **Explicit relationships** — product→organization, capability→product,
+   evidence→capability, concept→adjacent-concept distinctions stated in prose.
+4. **Category anchoring** — the entity's category named in text, matching the
+   registry category.
+5. **Jargon load** — proprietary terms defined at first meaningful use.
+
+## Posture
+
+`strong` (1–4 hold), `partial` (subject clear, relationships implicit),
+`weak` (subject or category ambiguous), `not_established` (page has no
+registered primary entity — fix the registry first).
+
+## Evidence required
+
+Quoted passages showing the category statement and each relationship; the
+registry entity rows compared against.
+
+## Example / counterexample
+
+- Strong: "Gatekeeper is a runtime enforcement component *from Example
+  Governance* in the *AI execution governance* category. It differs from
+  observability tooling because…"
+- Weak: a page alternating between "platform", "framework", "suite", and
+  "solution" for the same product, with the category never named.
+
+## Ambiguity → human review
+
+- Term meaning is jurisdiction- or discipline-specific (e.g., "authorization"
+  in IAM vs healthcare).
+- Two registered entities legitimately share the page (partnership pages).

package/skill/rubrics/source-authority.md

@@ -0,0 +1,37 @@
+# Rubric: source authority
+
+Judges how much weight an external source can carry as corroboration. Used by
+`/citable audit corroboration` and evidence review.
+
+## Scoring dimensions
+
+1. **Editorial independence** — no ownership, payment, or reciprocal
+   arrangement with the claiming organization; disclosed relationships reduce
+   but do not zero the score, *undisclosed* ones zero it.
+2. **Topical retrieval presence** — is this a source engines already retrieve
+   for the topic? (Observed citations in prompt-results are the evidence.)
+3. **Substantive treatment** — the source describes the entity accurately and
+   substantively, not a directory one-liner.
+4. **Stability** — stable URL, accessible to retrieval systems, not paywalled
+   into invisibility.
+5. **Provenance** — publisher identity, publication date, and (for research)
+   methodology visible.
+
+## Posture
+
+`strong` (independent + retrieved + substantive), `partial` (independent but
+thin or unproven retrieval), `weak` (interest-conflicted or unstable),
+`not_established` (independence cannot be determined → treat as owned until
+verified).
+
+## Hard exclusions (never count as corroboration)
+
+Paid "best vendor" lists presented as editorial · fabricated comparison sites ·
+synthetic community mentions · fake reviews · undisclosed sponsorships ·
+programmatic pages ranking their own operator first · AI-generated third-party
+profiles. These are anti-patterns to report, not sources to weigh.
+
+## Ambiguity → human review
+
+- Source independence uncertain (affiliate links present, sponsor unclear).
+- Source is authoritative in one jurisdiction but not the claim's jurisdiction.

package/skill/templates/finding-review.md

@@ -0,0 +1,54 @@
+# Templates
+
+## Blocked-status response (fail closed)
+
+```yaml
+status: blocked
+reason: <what fact/evidence is missing>
+required_input:
+  - <exact missing input 1>
+  - <exact missing input 2>
+owner: <who can supply it>
+```
+
+## Incomplete external verification
+
+```yaml
+status: incomplete
+reason: external verification unavailable
+not_verified:
+  - <competitor capabilities>
+  - <current engine behaviour>
+consequence: findings below exclude these dimensions
+```
+
+## Posture block (per page or entity)
+
+```yaml
+posture:
+  retrieval_eligibility: strong | partial | weak | not_established
+  semantic_clarity: ...
+  answer_extractability: ...
+  entity_resolution: ...
+  evidence_strength: ...
+  recommendation_eligibility: ...
+confidence: confirmed | high | medium | low | unknown
+basis: [run_id, rubric files applied, observations count]
+```
+
+## Experiment record (required before causal claims)
+
+```yaml
+experiment_id: <DISC>-EXP-<n>
+hypothesis: >
+  <specific, falsifiable>
+primary_metric: <one>
+secondary_metrics: []
+control_group: <or baseline_window>
+baseline_window: <days>
+evaluation_window: <days>
+known_confounders: [algorithm updates, seasonality, competitor publications, retrieval refresh timing]
+decision_rule: >
+  <what result retains/reverts the change>
+owner: <name>
+```

package/src/cli/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { init } from '../commands/init.js';
+import { audit } from '../commands/audit.js';
+import { validate } from '../commands/validate.js';
+import { mapClaims } from '../commands/mapClaims.js';
+import { substantiate } from '../commands/substantiate.js';
+import { inspect } from '../commands/inspect.js';
+import { schemaCommand } from '../commands/schemaCmd.js';
+import { compareSnapshots } from '../commands/compareSnapshots.js';
+import { isInstallerCommand, runInstallerCommand } from '../installer/index.js';
+
+const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
+
+Usage: citable <command> [options]
+
+Commands
+  install                   Install the Citable skill into coding-agent harnesses
+  update                    Update managed Citable skill installations
+  check                     Report installed and available Citable versions
+  uninstall                 Remove managed Citable skill files
+  list                      List detected providers and installation state
+  doctor                    Diagnose installer, provider, and integrity problems
+  init                      Initialize .citable/ context and registries (non-destructive)
+  audit [scope]             Run detectors; scopes: technical seo aeo geo architecture entity
+                            claims evidence schema lifecycle corroboration
+  inspect <page>            Profile one page (URL path or source file)
+  map-claims                Extract material claim candidates from pages (--write to save)
+  substantiate              Assess claim/evidence status (--write to apply downgrades)
+  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
+
+Options
+  --target <dir|url>        Built output directory or deployed URL to audit
+  --base-url <url>          Base URL for path resolution of a built output dir
+  --ref-date <YYYY-MM-DD>   Reference date for expiry/staleness checks (default: today)
+  --write                   Persist registry changes (map-claims, substantiate)
+  --json                    Machine-readable output only
+
+No output of this tool guarantees crawling, indexing, ranking, citation,
+recommendation, inclusion, sentiment, or conversion outcomes.`;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--write') args.write = true;
+    else if (a === '--json') args.json = true;
+    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 === '--force') args.force = 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);
+}
+
+export async function main(argv = process.argv.slice(2), options = {}) {
+  const cmd = argv[0];
+  if (isInstallerCommand(cmd)) return runInstallerCommand(cmd, argv.slice(1), options);
+  const args = parseArgs(argv.slice(1));
+  const root = options.cwd ?? process.cwd();
+
+  try {
+    switch (cmd) {
+      case 'init': {
+        const r = init(root, { force: args.force });
+        out(args, `Initialized .citable/\n  created: ${r.created.join(', ') || 'nothing'}\n  skipped: ${r.skipped.join(', ') || 'nothing'}\n  detected framework: ${r.detected.framework ?? 'unknown'}\n  unresolved assumptions:\n${r.unresolved.map((u) => `    - ${u}`).join('\n') || '    none'}`, r);
+        break;
+      }
+      case 'audit': {
+        const scope = args._[0];
+        const r = await audit(root, { target: args.target, scope, baseUrl: args.baseUrl, refDate: args.refDate });
+        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;
+      }
+      case 'inspect': {
+        if (!args._[0]) throw new Error('usage: citable inspect <page> --target <dir|url>');
+        const r = await inspect(root, args._[0], { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+        out(args, `Inspect ${r.url}\n  title: ${r.title}\n  status: ${r.status}; canonical: ${r.canonicals.join(', ') || 'none'}; robots: ${r.robotsDirectives.join(',') || 'default'}\n  intent: ${r.primary_intent ?? 'undeclared'}; conversion: ${r.conversion_action ?? 'undeclared'}\n  entities: ${r.entities.map((e) => e.name).join(', ') || 'none'}\n  claims: ${r.claims.length}; findings: ${r.findings.length}\n  ambiguity:\n${r.unresolved_ambiguity.map((a) => `    - ${a}`).join('\n') || '    none'}`, r);
+        break;
+      }
+      case 'map-claims': {
+        const r = await mapClaims(root, { target: args.target, baseUrl: args.baseUrl, write: args.write, refDate: args.refDate });
+        out(args, `map-claims: ${r.candidates.length} candidate claim(s)${args.write ? `, ${r.written} written to registry as candidate/review_required` : ' (dry run — use --write to save)'}\n` + r.candidates.map((c) => `  [${c.claim_type}${c.review_required ? ', REVIEW REQUIRED' : ''}] ${c.claim.slice(0, 100)}\n    at ${c.source_location}`).join('\n'), r);
+        break;
+      }
+      case 'substantiate': {
+        const r = substantiate(root, { write: args.write, refDate: args.refDate });
+        out(args, `substantiate: ${r.assessments.length} claim(s) assessed${args.write ? ' (changes written)' : ' (dry run)'}\n` + r.assessments.map((a) => `  ${a.claim_id}: ${a.previous_status} → ${a.outcome}\n    ${a.reasons.join('; ')}${a.required_input.length ? `\n    required input: ${a.required_input.join(', ')}` : ''}`).join('\n'), r);
+        break;
+      }
+      case 'schema': {
+        const r = await schemaCommand(root, { target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+        out(args, `schema: ${r.findings.length} finding(s), ${r.proposals.length} proposal(s), ${r.blocked.length} blocked (incomplete entity data)\n` + r.blocked.map((b) => `  BLOCKED ${b.entity_id}: needs ${b.required_input.join(', ')}`).join('\n'), r);
+        break;
+      }
+      case 'validate': {
+        const mode = args._[0] ?? 'registries';
+        const r = await validate(root, { mode, target: args.target, baseUrl: args.baseUrl, refDate: args.refDate });
+        out(args, `validate ${mode}: ${r.ok ? 'OK' : 'PROBLEMS'}\n` + (r.problems.length ? r.problems.map((p) => `  - ${p}`).join('\n') : '  registries structurally valid') + (r.findings?.length ? `\n  detector findings: ${r.findings.length} (see run ${r.runId})` : ''), r);
+        if (!r.ok) process.exitCode = 1;
+        break;
+      }
+      case 'compare-snapshots': {
+        const r = compareSnapshots(root, { runA: args._[0], runB: args._[1] });
+        out(args, `compare ${r.runA} → ${r.runB}\n  new: ${r.summary.new_findings} (critical/high: ${r.summary.regression_critical_or_high})\n  resolved: ${r.summary.resolved_findings}\n  persisting: ${r.summary.persisting_findings}`, r);
+        if (r.summary.regression_critical_or_high > 0) process.exitCode = 1;
+        break;
+      }
+      case undefined:
+        console.log(HELP);
+        break;
+      default:
+        console.error(`unknown command: ${cmd}\n`);
+        console.log(HELP);
+        process.exitCode = 2;
+    }
+  } catch (err) {
+    console.error(`citable: ${err.message}`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const code = await main();
+  if (Number.isInteger(code)) process.exitCode = code;
+}

package/src/commands/audit.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildContext } from './context.js';
+import { selectDetectors } from '../detectors/index.js';
+import { runDetectors } from '../detectors/framework.js';
+import { createRun } from '../evidence/run.js';
+import { summarize, renderMarkdownReport } from '../reporting/report.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { writeJson, sha256 } from '../shared/io.js';
+import { extractModified } from '../detectors/lifeMeas.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 });
+  const detectors = selectDetectors({ scope });
+
+  const run = createRun(root, {
+    command: `audit${scope ? ' ' + scope : ''}`,
+    argv: process.argv.slice(2),
+    target: {
+      kind: ctx.site ? ctx.site.mode : 'registries',
+      location: ctx.site ? ctx.site.location : path.join(root, '.citable'),
+      environment: 'local',
+    },
+    configHash: sha256(JSON.stringify(ctx.config)),
+  });
+  ctx.runId = run.runId;
+  ctx.timestamp = run.manifest.timestamp;
+
+  run.manifest.warnings.push(...ctx.warnings);
+  if (!ctx.site) {
+    run.manifest.incomplete_checks.push('No site target supplied and no built_output_dir configured: page/site detectors were skipped; this run covers registries only.');
+  }
+  if (ctx.site?.fetchErrors?.length) {
+    run.manifest.errors.push(...ctx.site.fetchErrors);
+  }
+
+  const { findings, detectorsRun, detectorsSkipped, errors } = runDetectors(detectors, ctx);
+  run.manifest.detectors_run = detectorsRun;
+  run.manifest.detectors_skipped = detectorsSkipped;
+  run.manifest.errors.push(...errors);
+
+  // Validate every finding against the data contract; a contract breach fails the run.
+  const invalid = [];
+  for (const f of findings) {
+    const { valid, errors: e } = validateAgainst('finding.schema.json', f);
+    if (!valid) invalid.push(`${f.finding_id}: ${e.join('; ')}`);
+  }
+  if (invalid.length) {
+    run.manifest.errors.push(...invalid);
+    run.finalize('failed');
+    throw new Error(`findings violate the data contract:\n${invalid.join('\n')}`);
+  }
+
+  // Evidence package artifacts
+  run.writeArtifact('findings.json', findings);
+  const summary = summarize(findings);
+  run.writeArtifact('summary.json', summary);
+  run.writeArtifact('inputs.json', {
+    target: run.manifest.target, scope: scope ?? 'all',
+    registry_counts: Object.fromEntries(Object.entries(ctx.registries).map(([k, v]) => [k, v.entries.length])),
+    pages_audited: ctx.site?.pages.length ?? 0,
+  });
+  run.writeArtifact('environment.json', {
+    node: process.version, platform: process.platform, cwd: root,
+    ref_date: ctx.refDate.toISOString(),
+  });
+  if (ctx.site) {
+    run.writeArtifact('pages/index.json', ctx.site.pages.map((p) => ({
+      url: p.url, status: p.status, title: p.title, canonicals: p.canonicals,
+      noindex: p.noindex, wordCount: p.wordCount, sourceFile: p.sourceFile,
+      contentHash: ctx.hashPage(p),
+    })));
+    if (ctx.site.robotsText != null) run.writeArtifact('robots/robots.txt', ctx.site.robotsText);
+    for (const sm of ctx.site.sitemaps) {
+      run.writeArtifact(`sitemaps/${path.basename(String(sm.source))}.json`, sm.parsed);
+    }
+    run.writeArtifact('links/graph.json', {
+      inbound: Object.fromEntries([...ctx.site.inbound.entries()].map(([k, v]) => [k, v.length])),
+      outbound: Object.fromEntries([...ctx.site.outbound.entries()].map(([k, v]) => [k, v.map((e) => e.to)])),
+    });
+    const schemaBlocks = [];
+    for (const p of ctx.site.pages) for (const j of p.jsonLd) schemaBlocks.push({ url: p.url, parseError: j.parseError, blocks: j.blocks });
+    run.writeArtifact('schema/jsonld.json', schemaBlocks);
+    for (const p of ctx.site.pages) {
+      run.writeArtifact(`headers/${encodeURIComponent(p.url)}.json`, { status: p.status, headers: p.headers });
+    }
+  }
+
+  const report = renderMarkdownReport({ findings, manifest: run.manifest, summary, detectorsSkipped });
+  run.writeArtifact('report.md', report);
+
+  // Update the latest page snapshot for regression/freshness comparison
+  if (ctx.site) {
+    const snap = { taken_at: run.manifest.timestamp, run_id: run.runId, pages: {} };
+    for (const p of ctx.site.pages) {
+      snap.pages[p.url] = { contentHash: ctx.hashPage(p), dateModified: extractModified(p), status: p.status };
+    }
+    const snapDir = path.join(root, '.citable', 'snapshots');
+    fs.mkdirSync(snapDir, { recursive: true });
+    if (fs.existsSync(path.join(snapDir, 'pages-latest.json'))) {
+      fs.copyFileSync(path.join(snapDir, 'pages-latest.json'), path.join(snapDir, `pages-${run.runId}.prev.json`));
+    }
+    writeJson(path.join(snapDir, 'pages-latest.json'), snap);
+  }
+
+  const status = run.manifest.errors.length ? 'completed_with_warnings'
+    : run.manifest.incomplete_checks.length ? 'incomplete' : 'completed';
+  const dir = run.finalize(status);
+  return { runId: run.runId, dir, findings, summary, manifest: run.manifest, report };
+}

package/src/commands/compareSnapshots.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from '../shared/io.js';
+
+/**
+ * `citable compare-snapshots [runA runB]` — regression comparison between two audit runs.
+ * Defaults to the two most recent runs containing findings.json.
+ */
+export function compareSnapshots(root, { runA, runB } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runsDir)) throw new Error('no runs recorded yet');
+  const runs = fs.readdirSync(runsDir)
+    .filter((r) => fs.existsSync(path.join(runsDir, r, 'findings.json')))
+    .sort();
+  if (!runA || !runB) {
+    if (runs.length < 2) throw new Error(`need two runs with findings to compare; found ${runs.length}`);
+    runB = runB ?? runs[runs.length - 1];
+    runA = runA ?? runs[runs.length - 2];
+  }
+  const load = (r) => {
+    const dir = path.join(runsDir, r);
+    if (!fs.existsSync(path.join(dir, 'findings.json'))) throw new Error(`run ${r} has no findings.json`);
+    return {
+      findings: readJson(path.join(dir, 'findings.json')),
+      manifest: readJson(path.join(dir, 'manifest.json')),
+    };
+  };
+  const a = load(runA);
+  const b = load(runB);
+  const key = (f) => `${f.detector_id}|${f.subject.identifier}|${f.observation.summary}`;
+  const aKeys = new Map(a.findings.map((f) => [key(f), f]));
+  const bKeys = new Map(b.findings.map((f) => [key(f), f]));
+  const regressions = [...bKeys.entries()].filter(([k]) => !aKeys.has(k)).map(([, f]) => f);
+  const resolved = [...aKeys.entries()].filter(([k]) => !bKeys.has(k)).map(([, f]) => f);
+  const persisting = [...bKeys.entries()].filter(([k]) => aKeys.has(k)).map(([, f]) => f);
+  return {
+    runA, runB,
+    baseline_timestamp: a.manifest.timestamp,
+    comparison_timestamp: b.manifest.timestamp,
+    regressions, resolved, persisting,
+    summary: {
+      new_findings: regressions.length,
+      resolved_findings: resolved.length,
+      persisting_findings: persisting.length,
+      regression_critical_or_high: regressions.filter((f) => ['critical', 'high'].includes(f.classification.severity)).length,
+    },
+  };
+}

package/src/commands/context.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readYaml, readJson, sha256 } from '../shared/io.js';
+import { loadRegistries } from '../registries/index.js';
+import { buildSiteFromDir, buildSiteFromUrl } from '../extractor/site.js';
+
+/** Assemble the shared execution context used by audit-family commands. */
+export async function buildContext(root, { target, baseUrl, refDate } = {}) {
+  const warnings = [];
+  const configFile = path.join(root, '.citable', 'config.yaml');
+  const config = fs.existsSync(configFile) ? readYaml(configFile) : { version: 1 };
+  const { registries, problems } = loadRegistries(root);
+  warnings.push(...problems);
+
+  let site = null;
+  const resolvedBase = baseUrl ?? config.site?.base_url ?? 'https://example.test';
+  if (target) {
+    if (/^https?:\/\//.test(target)) {
+      site = await buildSiteFromUrl(target);
+    } else if (fs.existsSync(target)) {
+      site = buildSiteFromDir(target, { baseUrl: resolvedBase });
+    } else {
+      throw new Error(`audit target not found: ${target}`);
+    }
+  } else if (config.site?.built_output_dir && fs.existsSync(path.join(root, config.site.built_output_dir))) {
+    site = buildSiteFromDir(path.join(root, config.site.built_output_dir), { baseUrl: resolvedBase });
+  }
+
+  // Prompt observations recorded under .citable/runs/*/prompt-results/
+  const promptResults = [];
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (fs.existsSync(runsDir)) {
+    for (const run of fs.readdirSync(runsDir)) {
+      const prDir = path.join(runsDir, run, 'prompt-results');
+      if (!fs.existsSync(prDir)) continue;
+      for (const f of fs.readdirSync(prDir)) {
+        if (f.endsWith('.json')) {
+          try { promptResults.push(readJson(path.join(prDir, f))); } catch { warnings.push(`unreadable prompt result: ${run}/${f}`); }
+        }
+      }
+    }
+  }
+
+  // Latest page snapshot (for regression/freshness comparison)
+  let snapshots = null;
+  const snapFile = path.join(root, '.citable', 'snapshots', 'pages-latest.json');
+  if (fs.existsSync(snapFile)) {
+    try { snapshots = readJson(snapFile); } catch { warnings.push('unreadable pages snapshot'); }
+  }
+
+  return {
+    root,
+    config,
+    registries,
+    site,
+    promptResults: promptResults.length ? promptResults : null,
+    snapshots,
+    refDate: refDate ? new Date(refDate) : new Date(),
+    hashPage: (p) => sha256(p.text),
+    warnings,
+  };
+}

package/src/commands/init.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeYaml, readJson, nowIso, listFiles } from '../shared/io.js';
+import { REGISTRY_SPECS, emptyRegistry, contextDir } from '../registries/index.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+const DEFAULT_CRAWLERS = [
+  ['CRAWLER-GOOGLEBOT', 'Googlebot', 'Google', 'search_indexing'],
+  ['CRAWLER-BINGBOT', 'Bingbot', 'Microsoft', 'search_indexing'],
+  ['CRAWLER-OAI-SEARCHBOT', 'OAI-SearchBot', 'OpenAI', 'ai_search_discovery'],
+  ['CRAWLER-GPTBOT', 'GPTBot', 'OpenAI', 'model_training'],
+  ['CRAWLER-CHATGPT-USER', 'ChatGPT-User', 'OpenAI', 'user_initiated_retrieval'],
+  ['CRAWLER-PERPLEXITYBOT', 'PerplexityBot', 'Perplexity', 'ai_search_discovery'],
+  ['CRAWLER-PERPLEXITY-USER', 'Perplexity-User', 'Perplexity', 'user_initiated_retrieval'],
+  ['CRAWLER-CLAUDEBOT', 'ClaudeBot', 'Anthropic', 'model_training'],
+];
+
+function detectFramework(root) {
+  const detected = {
+    framework: null, rendering_model: null, package_manager: null,
+    build_commands: [], test_commands: [], robots_files: [], sitemap_sources: [],
+    schema_sources: [], metadata_systems: [], analytics: [], content_collections: [],
+  };
+  const unresolved = [];
+  const pkgFile = path.join(root, 'package.json');
+  if (fs.existsSync(pkgFile)) {
+    const pkg = readJson(pkgFile);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) { detected.framework = 'next.js'; detected.rendering_model = 'hybrid'; }
+    else if (deps.astro) { detected.framework = 'astro'; detected.rendering_model = 'static'; }
+    else if (deps.nuxt) { detected.framework = 'nuxt'; detected.rendering_model = 'hybrid'; }
+    else if (deps['@sveltejs/kit']) { detected.framework = 'sveltekit'; detected.rendering_model = 'hybrid'; }
+    else if (deps.gatsby) { detected.framework = 'gatsby'; detected.rendering_model = 'static'; }
+    else if (deps.react || deps.vue) { detected.framework = 'spa'; detected.rendering_model = 'csr'; }
+    if (pkg.scripts?.build) detected.build_commands.push(`npm run build`);
+    if (pkg.scripts?.test) detected.test_commands.push(`npm test`);
+    detected.package_manager = fs.existsSync(path.join(root, 'pnpm-lock.yaml')) ? 'pnpm'
+      : fs.existsSync(path.join(root, 'yarn.lock')) ? 'yarn'
+      : fs.existsSync(path.join(root, 'bun.lockb')) ? 'bun' : 'npm';
+  } else if (fs.existsSync(path.join(root, 'pyproject.toml'))) {
+    detected.framework = 'python';
+    unresolved.push('Python project detected; rendering model and build pipeline need manual confirmation.');
+  } else {
+    unresolved.push('No package manifest found; framework, build, and test commands unknown.');
+  }
+  for (const f of listFiles(root, (p) => /robots\.txt$/.test(p))) detected.robots_files.push(path.relative(root, f));
+  for (const f of listFiles(root, (p) => /sitemap.*\.(xml|ts|js|mjs)$/.test(p))) detected.sitemap_sources.push(path.relative(root, f));
+  for (const f of listFiles(root, (p) => /\.(html|jsx?|tsx?|astro|vue|svelte)$/.test(p)).slice(0, 400)) {
+    const text = fs.readFileSync(f, 'utf8');
+    if (text.includes('application/ld+json') || text.includes('schema.org')) detected.schema_sources.push(path.relative(root, f));
+    if (/gtag\(|googletagmanager|plausible|posthog|umami|matomo/i.test(text)) detected.analytics.push(path.relative(root, f));
+  }
+  if (detected.rendering_model === null) unresolved.push('Rendering model could not be determined from manifests.');
+  return { detected, unresolved };
+}
+
+/** `citable init` — inspect the repo and create .citable/ without overwriting anything user-maintained. */
+export function init(root, { force = false } = {}) {
+  const dir = contextDir(root);
+  const created = [];
+  const skipped = [];
+  fs.mkdirSync(dir, { recursive: true });
+  for (const sub of ['policies', 'findings', 'snapshots', 'reports', 'runs']) {
+    fs.mkdirSync(path.join(dir, sub), { recursive: true });
+  }
+  const { detected, unresolved } = detectFramework(root);
+
+  const configFile = path.join(dir, 'config.yaml');
+  if (!fs.existsSync(configFile) || force) {
+    const config = {
+      version: 1,
+      site: { base_url: null, built_output_dir: null, source_dirs: [], default_locale: 'en', default_jurisdiction: null },
+      framework: {
+        name: detected.framework, rendering_model: detected.rendering_model,
+        package_manager: detected.package_manager,
+        build_command: detected.build_commands[0] ?? null, test_command: detected.test_commands[0] ?? null,
+      },
+      audit: { index_target_default: true, max_crawl_depth: 4, thin_content_words: 120, fetch_external: false },
+    };
+    const { valid, errors } = validateAgainst('config.schema.json', config);
+    if (!valid) throw new Error(`generated config invalid: ${errors.join('; ')}`);
+    writeYaml(configFile, config);
+    created.push('config.yaml');
+  } else skipped.push('config.yaml (exists)');
+
+  const projectFile = path.join(dir, 'project.yaml');
+  if (!fs.existsSync(projectFile) || force) {
+    const project = { version: 1, initialized_at: nowIso(), repository_root: root, detected, unresolved_assumptions: unresolved };
+    const { valid, errors } = validateAgainst('project.schema.json', project);
+    if (!valid) throw new Error(`generated project profile invalid: ${errors.join('; ')}`);
+    writeYaml(projectFile, project);
+    created.push('project.yaml');
+  } else skipped.push('project.yaml (exists)');
+
+  for (const spec of REGISTRY_SPECS) {
+    const file = path.join(dir, spec.file);
+    if (fs.existsSync(file)) { skipped.push(`${spec.file} (exists)`); continue; }
+    const reg = emptyRegistry(spec.kind);
+    if (spec.kind === 'crawlers') {
+      reg.entries = DEFAULT_CRAWLERS.map(([id, ua, vendor, purpose]) => ({
+        crawler_id: id, user_agent: ua, vendor, purpose,
+        decision: 'undecided', status: 'active',
+      }));
+    }
+    const { valid, errors } = validateAgainst(spec.schema, reg);
+    if (!valid) throw new Error(`generated ${spec.file} invalid: ${errors.join('; ')}`);
+    writeYaml(file, reg);
+    created.push(spec.file);
+  }
+  return { created, skipped, detected, unresolved };
+}

package/src/commands/inspect.js

@@ -0,0 +1,61 @@
+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 <page>` — profile one page: intent, entities, claims, metadata, links, lifecycle, ambiguity. */
+export async function inspect(root, pageRef, { target, baseUrl, refDate } = {}) {
+  const ctx = await buildContext(root, { target, baseUrl, refDate });
+  if (!ctx.site) throw new Error('inspect 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);
+  const claims = (ctx.registries.claims?.entries || []).filter((c) => (reg?.published_claims || []).includes(c.claim_id) || (c.publication_surfaces || []).some((s) => page.url.includes(s)));
+  const entities = (ctx.registries.entities?.entries || []).filter((e) => (reg?.primary_entities || []).includes(e.entity_id) || page.text.toLowerCase().includes(e.canonical_name.toLowerCase()));
+
+  // Answer-bearing passages: first paragraph + paragraphs following question headings
+  const answerPassages = [];
+  if (page.paragraphs[0]) answerPassages.push({ role: 'opening', text: page.paragraphs[0].slice(0, 300) });
+  for (const h of page.headings.filter((h) => h.text.endsWith('?'))) {
+    answerPassages.push({ role: `after heading "${h.text}"`, text: '(verify prose follows; see ANS-002)' });
+  }
+
+  // Per-page detector pass
+  const single = { ...ctx, site: { ...ctx.site, pages: [page] } };
+  const { findings } = runDetectors(selectDetectors({}), single);
+  const pageFindings = findings.filter((f) => f.subject.identifier === page.url || f.subject.url === page.url);
+
+  const ambiguities = [];
+  if (!reg) ambiguities.push('Page has no registry entry: intent, target queries, owner, and lifecycle are undeclared.');
+  if (reg && !reg.primary_intent) ambiguities.push('Registry entry declares no primary intent.');
+  if (reg && !reg.conversion_action) ambiguities.push('No conversion action declared; commercial role unknown.');
+  if (entities.length === 0) ambiguities.push('No registered entity matched on this page.');
+
+  return {
+    url: page.url,
+    sourceFile: page.sourceFile,
+    status: page.status,
+    title: page.title,
+    metaDescription: page.metaDescription,
+    canonicals: page.canonicals,
+    robotsDirectives: page.robotsDirectives,
+    headings: page.headings,
+    wordCount: page.wordCount,
+    registry: reg,
+    primary_intent: reg?.primary_intent ?? null,
+    conversion_action: reg?.conversion_action ?? null,
+    lifecycle: reg ? { class: reg.lifecycle_class, owner: reg.content_owner, reviewer: reg.factual_reviewer, next_review: reg.next_review_date } : null,
+    entities: entities.map((e) => ({ entity_id: e.entity_id, name: e.canonical_name, type: e.entity_type })),
+    claims: claims.map((c) => ({ claim_id: c.claim_id, type: c.claim_type, status: c.status, claim: c.claim })),
+    schemaBlocks: page.jsonLd.map((j) => ({ parseError: j.parseError, types: j.blocks.map((b) => b['@type']) })),
+    internalLinks: {
+      inbound: (ctx.site.inbound.get(ctx.site.normalize(page.url)) || []).length,
+      outbound: (ctx.site.outbound.get(ctx.site.normalize(page.url)) || []).length,
+    },
+    answerPassages,
+    findings: pageFindings,
+    unresolved_ambiguity: ambiguities,
+  };
+}