@nebulacomponents/citable 1.12.0 → 1.13.1

package/src/commands/executive.js

@@ -0,0 +1,167 @@
+/**
+ * executive command — Chief-of-Staff Router
+ *
+ * Routes reporting and decision requests to the correct specialized skill.
+ * Built last deliberately — orchestration without strong underlying skills
+ * only coordinates weak outputs.
+ *
+ * Routing table:
+ *   quarterly reporting      → board-report
+ *   monthly reporting        → executive-review
+ *   bounded decision         → decision-memo
+ *   material uncertainty     → scenario
+ *   risk request             → risk
+ *   metric dispute           → kpi
+ *   commercial premise       → assumption-audit
+ *   customer value question  → outcomes
+ *   roadmap priority         → prioritize
+ *   competitor change        → competitive-intel
+ *
+ * Controls:
+ *   - Max orchestration depth: 1 (no recursive routing)
+ *   - Circular-call prevention: command registry checked before dispatch
+ *   - Explicit conflict surfacing — conflicts not smoothed over
+ *   - Decision logging to .citable/executive-log.yaml
+ *
+ * Usage:
+ *   citable executive <request>
+ *   citable executive --route <command>   Force a specific route
+ *   citable executive --log              Show recent routing decisions
+ */
+import { contextDir } from '../registries/index.js';
+import { readYaml, writeYaml, nowIso } from '../shared/io.js';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const ROUTES = [
+  { patterns: [/quarterly|board.pack|board.report/i],        command: 'board-report',         reason: 'Quarterly board pack' },
+  { patterns: [/monthly|operating.review|exec.review/i],     command: 'executive-review',     reason: 'Monthly executive operating review' },
+  { patterns: [/decision|decide|approve|memo/i],             command: 'decision-memo',        reason: 'Bounded decision record' },
+  { patterns: [/scenario|war.room|compound.risk|cascade/i],  command: 'scenario',             reason: 'Compound risk scenario' },
+  { patterns: [/risk.register|residual.risk|risk.list/i],    command: 'risk',                 reason: 'Risk register' },
+  { patterns: [/kpi|metric.definition|metric.dispute/i],     command: 'kpi',                  reason: 'KPI architecture' },
+  { patterns: [/assumption|premise|still.valid/i],            command: 'assumption-audit',     reason: 'Assumption validity' },
+  { patterns: [/customer.outcome|customer.value|impact/i],   command: 'outcomes',             reason: 'Customer outcomes' },
+  { 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' },
+];
+
+const MAX_DEPTH = 1;
+let _callDepth = 0;
+
+export async function executiveCommand(args, root = process.cwd()) {
+  const forceRoute = argVal(args, '--route');
+  const showLog = args.includes('--log');
+
+  if (showLog) return executiveLog(root);
+
+  if (_callDepth >= MAX_DEPTH) {
+    return { error: 'Maximum orchestration depth reached — circular routing prevented' };
+  }
+
+  const request = args.filter(a => !a.startsWith('--')).join(' ');
+
+  const route = forceRoute
+    ? ROUTES.find(r => r.command === forceRoute)
+    : resolveRoute(request);
+
+  if (!route) {
+    return {
+      unresolved: true,
+      request,
+      available_commands: ROUTES.map(r => ({ command: r.command, reason: r.reason })),
+      message: 'Could not determine the appropriate skill. Use --route <command> to force a route, or run the specific command directly.',
+    };
+  }
+
+  // Log the routing decision
+  logDecision(root, { request, routed_to: route.command, reason: route.reason, at: nowIso() });
+
+  _callDepth++;
+  try {
+    // Lazy-import to avoid circular deps — commands are imported at call time
+    const mod = await import(`./${commandToModule(route.command)}.js`);
+    const fn = mod[commandToExport(route.command)];
+    if (!fn) {
+      return { error: `No handler for command: ${route.command}` };
+    }
+    const downstreamArgs = args.filter((arg, index) => arg !== '--route' && args[index - 1] !== '--route');
+    const result = await fn(downstreamArgs, root);
+    return {
+      routed_to: route.command,
+      reason: route.reason,
+      result,
+    };
+  } finally {
+    _callDepth--;
+  }
+}
+
+function resolveRoute(request) {
+  if (!request) return null;
+  for (const route of ROUTES) {
+    if (route.patterns.some(p => p.test(request))) return route;
+  }
+  return null;
+}
+
+function commandToModule(cmd) {
+  const MAP = {
+    'board-report':       'boardReport',
+    'executive-review':   'executiveReview',
+    'decision-memo':      'decisionMemo',
+    'scenario':           'scenario',
+    'risk':               'risk',
+    'kpi':                'kpi',
+    'assumption-audit':   'assumptionAudit',
+    'outcomes':           'outcomes',
+    'variance':           'variance',
+    'prioritize':         'prioritize',
+    'competitive-intel':  'competitiveIntel',
+  };
+  return MAP[cmd] ?? cmd;
+}
+
+function commandToExport(cmd) {
+  const MAP = {
+    'board-report':       'boardReportCommand',
+    'executive-review':   'executiveReviewCommand',
+    'decision-memo':      'decisionMemoCommand',
+    'scenario':           'scenarioCommand',
+    'risk':               'riskCommand',
+    'kpi':                'kpiCommand',
+    'assumption-audit':   'assumptionAuditCommand',
+    'outcomes':           'outcomesCommand',
+    'variance':           'varianceCommand',
+    'prioritize':         'prioritizeCommand',
+    'competitive-intel':  'competitiveIntelCommand',
+  };
+  return MAP[cmd] ?? cmd + 'Command';
+}
+
+function logDecision(root, entry) {
+  const dir = contextDir(root);
+  const logFile = path.join(dir, 'executive-log.yaml');
+  let log = { version: 1, kind: 'executive-log', entries: [] };
+  if (fs.existsSync(logFile)) {
+    try { log = readYaml(logFile) ?? log; } catch {}
+  }
+  log.entries.push(entry);
+  // Keep last 100 entries
+  if (log.entries.length > 100) log.entries = log.entries.slice(-100);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  writeYaml(logFile, { ...log, updated: nowIso() });
+}
+
+function executiveLog(root) {
+  const logFile = path.join(contextDir(root), 'executive-log.yaml');
+  if (!fs.existsSync(logFile)) return { log: [], message: 'No routing decisions logged yet.' };
+  const log = readYaml(logFile) ?? { entries: [] };
+  return { log: (log.entries ?? []).slice(-20) };
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/executiveReview.js

@@ -0,0 +1,206 @@
+/**
+ * executive-review command — Monthly Executive Operating Review
+ *
+ * Generates an evidence-first operating review. Produces an evidence
+ * ledger first, then derives the narrative. Never generates a polished
+ * positive summary when data is absent or ungoverned.
+ *
+ * Four-act invariant (mandatory):
+ *   1. Where management said the company would be
+ *   2. Where it actually is
+ *   3. Why the variance exists
+ *   4. What management is doing about it
+ *
+ * Usage:
+ *   citable executive-review [--period <YYYY-MM>] [--json]
+ */
+import { checkReferentialIntegrity, loadRegistries } from '../registries/index.js';
+import { nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import { dateOnly, parseAsOf } from '../shared/asOf.js';
+
+
+/** Filter registry entries to only those that pass schema validation. */
+function validEntries(entries, schemaName) {
+  if (!entries?.length) return [];
+  return entries.filter(e => {
+    const { valid } = validateAgainst(schemaName, { version: 1, kind: schemaName.replace('.schema.json','s'), entries: [e] });
+    return valid;
+  });
+}
+
+function validReferences(entries, kind, idField, problems) {
+  return entries.filter(entry => !problems.some(problem => problem.startsWith(`${kind}/${entry[idField]}:`)));
+}
+
+export async function executiveReviewCommand(args, root = process.cwd()) {
+  const asOf  = parseAsOf(args);
+  const period = argVal(args, '--period') ?? currentPeriod(asOf);
+  const asJson = args.includes('--json');
+
+  const { registries, problems: regProblems } = loadRegistries(root);
+  const refProblems = checkReferentialIntegrity(registries);
+
+  const report = buildReview(registries, period, [...regProblems, ...refProblems], refProblems);
+  report.generated_at = nowIso();
+  report.as_of = dateOnly(asOf);
+
+  return asJson ? report : formatReview(report);
+}
+
+function buildReview(registries, period, regProblems, refProblems) {
+  // Filter to schema-valid and referentially valid governed evidence.
+  const kpis = validReferences(validEntries(registries.kpis?.entries, 'kpi.schema.json'), 'kpis', 'metric_id', refProblems);
+  const validVariances = validReferences(validEntries(registries.variances?.entries, 'variance.schema.json'), 'variances', 'variance_id', refProblems);
+  const variances = validVariances.filter(v => v.period === period);
+  const outcomes = validReferences(validEntries(registries['customer-outcomes']?.entries, 'customer-outcome.schema.json'), 'customer-outcomes', 'outcome_id', refProblems);
+  const risks = validReferences(validEntries(registries.risks?.entries, 'risk.schema.json'), 'risks', 'risk_id', refProblems);
+  const decisions = validReferences(validEntries(registries.decisions?.entries, 'decision.schema.json'), 'decisions', 'decision_id', refProblems);
+
+  const invalidTotal =
+    ((registries.kpis?.entries?.length ?? 0) - kpis.length) +
+    ((registries.variances?.entries?.length ?? 0) - validVariances.length) +
+    ((registries['customer-outcomes']?.entries?.length ?? 0) - outcomes.length) +
+    ((registries.risks?.entries?.length ?? 0) - risks.length) +
+    ((registries.decisions?.entries?.length ?? 0) - decisions.length);
+
+
+  // Evidence ledger — raw facts before narrative
+  const ledger = {
+    period,
+    governed_metrics: kpis.length,
+    variances_this_period: variances.length,
+    material_variances: variances.filter(v => ['material','critical'].includes(v.materiality)).length,
+    customer_outcomes_total: outcomes.length,
+    outcomes_customer_confirmed: outcomes.filter(o => o.customer_confirmed).length,
+    outcomes_causal_established: outcomes.filter(o => o.outcome_stage === 'causal_relationship_established').length,
+    board_visible_risks: risks.filter(r => r.board_visibility).length,
+    critical_risks: risks.filter(r => r.residual_exposure === 'critical').length,
+    deteriorating_risks: risks.filter(r => r.trend === 'deteriorating').length,
+  };
+
+  // Commercial section
+  const commercial = buildSection('commercial', kpis, variances, [
+    'ARR','MRR','bookings','pipeline_coverage','win_rate','sales_cycle','customer_concentration',
+  ]);
+
+  // Customer section
+  const customer = buildSection('customer', kpis, variances, [
+    'active_customers','onboarding_time','renewal_risk','findings_acted_upon','unresolved_escalations',
+  ]);
+
+  // Product section
+  const product = buildSection('product', kpis, variances, [
+    'active_properties','audits_run','completed_valid_audits','installation_success','feature_adoption',
+  ]);
+
+  // Quality section — Citable-specific
+  const quality = buildSection('quality', kpis, variances, [
+    'detector_precision','confirmed_false_positives','known_false_negatives','expired_evidence','stale_registries',
+  ]);
+
+  // Operations section
+  const operations = buildSection('operations', kpis, variances, [
+    'failed_runs','incomplete_evidence_packages','crawler_access_failures','release_regressions',
+  ]);
+
+  // Management section
+  const openDecisions = decisions.filter(d => d.status === 'open');
+  const management = {
+    open_decisions: openDecisions.length,
+    decisions_requiring_action: openDecisions.map(d => ({
+      id: d.decision_id, title: d.title, owner: d.owner, deadline: d.deadline,
+    })),
+  };
+
+  return {
+    report_type: 'executive-operating-review',
+    period,
+    registry_problems: regProblems,
+    invalid_entries_excluded: invalidTotal > 0 ? invalidTotal : undefined,
+    ledger,
+    four_act_required: buildFourActPrompt(variances),
+    sections: { commercial, customer, product, quality, operations, management },
+    ungoverned_warning: ledger.governed_metrics === 0
+      ? 'BLOCKED: No governed KPIs. Register metrics with `citable kpi add` before generating narrative.'
+      : null,
+  };
+}
+
+function buildSection(name, kpis, variances, relevantNames) {
+  const sectionKpis = kpis.filter(k =>
+    relevantNames.some(n => k.metric_id?.toLowerCase().includes(n.toLowerCase()) || k.name?.toLowerCase().includes(n.toLowerCase()))
+  );
+  const sectionVariances = variances.filter(v =>
+    sectionKpis.some(k => k.metric_id === v.metric_id)
+  );
+  return {
+    section: name,
+    governed_metrics: sectionKpis.length,
+    variances: sectionVariances.length,
+    material_variances: sectionVariances.filter(v => ['material','critical'].includes(v.materiality)).length,
+    ungoverned_warning: sectionKpis.length === 0
+      ? `No governed KPIs for ${name} — narrative cannot be generated from ungoverned data`
+      : null,
+  };
+}
+
+function buildFourActPrompt(variances) {
+  if (variances.length === 0) return { status: 'no_variances_this_period' };
+  const material = variances.filter(v => ['material','critical'].includes(v.materiality));
+  return {
+    status: 'required',
+    material_variances: material.length,
+    template: {
+      act_1: 'Where management said the company would be: [state targets and forecasts from KPI registry]',
+      act_2: 'Where it actually is: [state actuals from variance records]',
+      act_3: 'Why the variance exists: [state primary_driver from each material variance — vague causes rejected]',
+      act_4: 'What management is doing about it: [state management_response from each material variance]',
+    },
+  };
+}
+
+function formatReview(report) {
+  const lines = [
+    `# Executive Operating Review — ${report.period}`,
+    `Generated: ${report.generated_at}`,
+    '',
+  ];
+  if (report.ungoverned_warning) {
+    lines.push(`⛔ ${report.ungoverned_warning}`, '');
+  }
+  if (report.registry_problems?.length) {
+    lines.push(`⚠️  Registry problems (${report.registry_problems.length}):`);
+    for (const p of report.registry_problems.slice(0, 5)) lines.push(`   ${p}`);
+    lines.push('');
+  }
+  const l = report.ledger;
+  lines.push(
+    '## Evidence Ledger',
+    `- Governed metrics: ${l.governed_metrics}`,
+    `- Variances this period: ${l.variances_this_period} (${l.material_variances} material)`,
+    `- Customer outcomes: ${l.customer_outcomes_total} (${l.outcomes_customer_confirmed} confirmed, ${l.outcomes_causal_established} causal)`,
+    `- Board-visible risks: ${l.board_visible_risks} (${l.critical_risks} critical, ${l.deteriorating_risks} deteriorating)`,
+    '',
+    '## Four-Act Reporting Requirement',
+  );
+  const fa = report.four_act_required;
+  if (fa.status === 'required') {
+    for (const [act, text] of Object.entries(fa.template)) {
+      lines.push(`**${act.replace('_',' ').toUpperCase()}:** ${text}`);
+    }
+  } else {
+    lines.push('No variances registered for this period.');
+  }
+  return lines.join('\n');
+}
+
+function currentPeriod(asOf) {
+  const d = asOf ?? new Date();
+  return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`;
+}
+
+function argVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}

package/src/commands/init.js

@@ -15,6 +15,19 @@ const DEFAULT_CRAWLERS = [
   ['CRAWLER-CLAUDEBOT', 'ClaudeBot', 'Anthropic', 'model_training'],
 ];
 
+function hasSchemaSignal(text) {
+  if (/application\/ld\+json/i.test(text)) return true;
+  for (const match of text.matchAll(/https?:\/\/[^\s"'<>]+/gi)) {
+    try {
+      const hostname = new URL(match[0]).hostname.toLowerCase();
+      if (hostname === 'schema.org' || hostname === 'www.schema.org') return true;
+    } catch {
+      // Ignore malformed URL-like source text during best-effort project discovery.
+    }
+  }
+  return false;
+}
+
 function detectFramework(root) {
   const detected = {
     framework: null, rendering_model: null, package_manager: null,
@@ -47,7 +60,7 @@ function detectFramework(root) {
   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 (hasSchemaSignal(text)) 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.');

package/src/commands/kpi.js

@@ -0,0 +1,86 @@
+/**
+ * kpi command — KPI Architecture registry management
+ *
+ * Usage:
+ *   citable kpi list     List all governed metrics
+ *   citable kpi show <id> Show a single KPI
+ *   citable kpi validate  Validate all KPI records
+ */
+import { loadRegistries, contextDir } from '../registries/index.js';
+import { readYaml, writeYaml, nowIso } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+import path from 'node:path';
+import fs from 'node:fs';
+
+const REQUIRED_COMPARISON = true; // every KPI must have a comparison basis
+
+export async function kpiCommand(args, root = process.cwd()) {
+  const [subcommand, ...rest] = args;
+  const dir = contextDir(root);
+  const file = path.join(dir, 'kpis.yaml');
+
+  switch (subcommand) {
+    case 'list': return kpiList(file);
+    case 'show': return kpiShow(file, rest[0]);
+    case 'validate': return kpiValidate(file);
+    case 'add': return { error: '`citable kpi add` is not yet implemented; edit kpis.yaml directly and run `citable kpi validate`' };
+    default:
+      return kpiList(file);
+  }
+}
+
+function loadKpis(file) {
+  if (!fs.existsSync(file)) return { version: 1, kind: 'kpis', entries: [] };
+  return readYaml(file) ?? { version: 1, kind: 'kpis', entries: [] };
+}
+
+function kpiList(file) {
+  const data = loadKpis(file);
+  if (!data.entries.length) return { kpis: [], message: 'No KPIs registered. Edit .citable/kpis.yaml, then run `citable kpi validate`.' };
+  return {
+    kpis: data.entries.map(k => ({
+      metric_id: k.metric_id,
+      name: k.name,
+      owner: k.owner,
+      cadence: k.reporting_cadence,
+      target: k.target ?? 'NOT SET',
+      comparison_required: k.comparison_required ?? REQUIRED_COMPARISON,
+      limitations: (k.known_limitations ?? []).length,
+    })),
+    total: data.entries.length,
+  };
+}
+
+function kpiShow(file, id) {
+  if (!id) return { error: 'metric_id required' };
+  const data = loadKpis(file);
+  const kpi = data.entries.find(k => k.metric_id === id);
+  if (!kpi) return { error: `KPI not found: ${id}` };
+  return { kpi };
+}
+
+function kpiValidate(file) {
+  const data = loadKpis(file);
+  const problems = [];
+  const { valid, errors } = validateAgainst('kpi.schema.json', data);
+  if (!valid) problems.push(...errors);
+  // Citable-specific checks
+  for (const k of data.entries) {
+    if (!k.known_limitations || k.known_limitations.length === 0)
+      problems.push(`${k.metric_id}: known_limitations is empty — every metric must document its measurement constraints`);
+    if (k.comparison_required !== false && !k.comparison_basis)
+      problems.push(`${k.metric_id}: comparison_basis required when comparison_required is true`);
+    if (!k.restatement_policy)
+      problems.push(`${k.metric_id}: restatement_policy missing — how will historical data be corrected?`);
+    // Citable metric distinction checks
+    if (/installs?/i.test(k.name) && !/active/i.test(k.name))
+      problems.push(`${k.metric_id}: "installs" vs "active_installations" must be distinct metrics`);
+    if (/audit/i.test(k.name) && !/valid|complete/i.test(k.executive_definition ?? ''))
+      problems.push(`${k.metric_id}: audits_run vs completed_valid_audits must be distinguished in executive_definition`);
+  }
+  return {
+    valid: problems.length === 0,
+    problems,
+    checked: data.entries.length,
+  };
+}

package/src/commands/monitor.js

@@ -11,6 +11,7 @@ function observations(dir) {
 function key(item) {
   const d = item.data || {};
   if (item.kind === 'citation') return [item.kind, d.provider, d.product_mode, d.prompt_id, d.run_index].join(':');
+  if (item.kind === 'representation_drift') return [item.kind, d.manifest_hash, d.surface_id, d.retrieval_path, d.region, d.request_identity].join(':');
   return [item.kind, d.url || d.citation_url || d.prompt_id || d.timestamp || item.observation_id].join(':');
 }
 
@@ -30,6 +31,14 @@ export function monitor(root, { runA, runB } = {}) {
     if (current.kind === 'index' && previous?.data?.indexed === true && current.data.indexed === false) alerts.push({ severity: 'high', type: 'index_loss', key: k });
     if (current.kind === 'canonical_freshness' && previous?.data?.canonical_consensus === true && current.data.canonical_consensus === false) alerts.push({ severity: 'high', type: 'canonical_regression', key: k });
     if (current.kind === 'citation' && previous?.data?.property_cited === true && current.data.property_cited === false) alerts.push({ severity: 'medium', type: 'citation_presence_change', key: k });
+    if (current.kind === 'representation_drift' && previous) {
+      const from = previous.data.representation_state, to = current.data.representation_state;
+      if (from !== 'divergent' && to === 'divergent') alerts.push({ severity: 'high', type: 'representation_divergence_observed', key: k, previous_state: from, current_state: to, authority: 'external_unverified', gates_release_finalization: false });
+      if (from === 'divergent' && to === 'consistent') {
+        const duration = new Date(current.collected_at) - new Date(previous.collected_at);
+        alerts.push({ severity: 'informational', type: 'representation_convergence_observed', key: k, previous_state: from, current_state: to, observed_interval_ms: Number.isFinite(duration) && duration >= 0 ? duration : null, authority: 'external_unverified', gates_release_finalization: false });
+      }
+    }
   }
   for (const k of before.keys()) if (!after.has(k)) alerts.push({ severity: 'medium', type: 'observation_missing', key: k });
   const result = { generated_at: nowIso(), run_a: a, run_b: b, summary: { alerts: alerts.length, critical_or_high: alerts.filter((x) => ['critical', 'high'].includes(x.severity)).length }, alerts };

package/src/commands/observe.js

@@ -8,11 +8,20 @@ import { parse as parseCsv } from 'csv-parse/sync';
 import { crawlerIdentity } from '../observations/crawlerIdentity.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { observeMedia } from '../observations/media.js';
+import { parse as parseHtml } from 'node-html-parser';
+import { verifyManifestIntegrity } from '../release/governance.js';
+import { observeBrowserPlan } from '../observations/browserJourney.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
 const strictDate = (value) => /^\d{4}-\d{2}-\d{2}$/.test(value || '') && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
 
+function visibleHtmlText(html) {
+  const document = parseHtml(String(html || ''));
+  for (const node of document.querySelectorAll('script,style')) node.remove();
+  return document.textContent.replace(/\s+/g, ' ').trim();
+}
+
 function canonicalReview(raw, targetOrigin) {
   const citations = raw.citations || [];
   return citations.map((citation, index) => {
@@ -31,6 +40,7 @@ function canonicalReview(raw, targetOrigin) {
 }
 
 async function observeRender(root, options) {
+  if (options.input) return observeBrowserPlan(root, options);
   if (!options.target || !/^https?:\/\//.test(options.target)) throw new Error('render requires --target <http(s) URL>');
   const profileNames = ['desktop', 'mobile', 'javascript_disabled'];
   let reused = [], previousRaw = null;
@@ -74,7 +84,7 @@ async function observeRender(root, options) {
       };
     }
     const initial = await (options.fetchUrl || fetchUrl)(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
-    const initialText = initial.body.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ').replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    const initialText = visibleHtmlText(initial.body);
     const observations = [...reused], artifacts = { 'initial/response.html': initial.body }, incomplete = [];
     const profiles = [{ name: 'desktop', viewport: { width: 1280, height: 900 } }, { name: 'mobile', viewport: { width: 390, height: 844 }, settings: { isMobile: true } }, { name: 'javascript_disabled', viewport: { width: 1280, height: 900 }, settings: { javaScriptEnabled: false } }];
     for (const profile of profiles.filter((item) => !reused.some((old) => old.data.profile === item.name))) {
@@ -369,6 +379,77 @@ function observeCorroboration(root, options) {
   return observationRun(root, 'observe corroboration', input.file, observations, { rawInputs: { corroboration_export: input.raw } });
 }
 
+async function observeRepresentation(root, options) {
+  const input = readInput(options.input);
+  const manifest = input.value;
+  const integrity = verifyManifestIntegrity(manifest);
+  if (!integrity.ok) throw new Error(`release manifest is invalid: ${integrity.failures.join('; ')}`);
+  if (!options.target) throw new Error('representation observation requires --target <controlled surface URL>');
+  const surface = manifest.controlled_surfaces.find((item) => item.url === options.target || item.surface_id === options.surfaceId);
+  if (!surface) throw new Error('target is not a controlled surface in the release manifest');
+  const expected = manifest.projections.find((item) => item.projection_id === surface.projection_id);
+  if (!expected) throw new Error(`expected projection ${surface.projection_id} is missing`);
+  const collector = options.fetchUrl || fetchUrl;
+  const paths = [
+    { path: 'direct', url: surface.url },
+    { path: 'cache_busted', url: `${surface.url}${surface.url.includes('?') ? '&' : '?'}citable_manifest=${manifest.manifest_hash.slice(0, 16)}` },
+  ];
+  const observations = [];
+  const artifacts = {};
+  const incomplete = [];
+  for (const item of paths) {
+    try {
+      const response = await collector(item.url, { userAgent: options.userAgent || 'CitableRepresentationProbe/1.0', maxRetries: 1 });
+      const responseHash = sha256(response.body);
+      const observedProjectionHash = surface.verification_method === 'exact_response_body'
+        ? responseHash
+        : response.headers?.[surface.verification_header] || null;
+      const representationState = response.status >= 200 && response.status < 300
+        ? !observedProjectionHash ? 'insufficient_evidence' : observedProjectionHash === expected.sha256 ? 'consistent' : 'divergent'
+        : response.status === 403 || response.status === 429 ? 'challenged' : 'failed';
+      const data = {
+        release_id: manifest.release_id,
+        manifest_hash: manifest.manifest_hash,
+        surface_id: surface.surface_id,
+        projection_id: expected.projection_id,
+        retrieval_path: item.path,
+        requested_url: item.url,
+        final_url: response.url,
+        status: response.status,
+        redirect_chain: response.redirectChain || [],
+        headers: response.headers || {},
+        verification_method: surface.verification_method,
+        verification_header: surface.verification_header,
+        expected_projection_hash: expected.sha256,
+        observed_projection_hash: observedProjectionHash,
+        observed_response_hash: responseHash,
+        representation_state: representationState,
+        authority_label: 'external_unverified',
+        gates_release_finalization: false,
+        request_identity: options.userAgent || 'CitableRepresentationProbe/1.0',
+        region: options.region || 'local_unspecified',
+      };
+      observations.push(envelope('representation_drift', data, {
+        method: 'synthetic_fetch', source: item.url, raw: response.body,
+        confidence: 'confirmed',
+        limitations: ['One synthetic retrieval does not represent all caches, indexes, products, accounts, geographies, or users.'],
+        authority: { source_authority: 'unknown', collection_authority: 'synthetic_probe', authenticity_status: 'unverified', representativeness: 'single_observation' },
+      }));
+      artifacts[`representation/${item.path}-response.txt`] = response.body;
+      artifacts[`representation/${item.path}-headers.json`] = response.headers || {};
+    } catch (error) {
+      incomplete.push(`${item.path} representation retrieval failed: ${error.message}`);
+      observations.push(envelope('representation_drift', {
+        release_id: manifest.release_id, manifest_hash: manifest.manifest_hash, surface_id: surface.surface_id,
+        projection_id: expected.projection_id, retrieval_path: item.path, requested_url: item.url,
+        representation_state: 'failed', authority_label: 'external_unverified', gates_release_finalization: false,
+        request_identity: options.userAgent || 'CitableRepresentationProbe/1.0', region: options.region || 'local_unspecified',
+      }, { method: 'synthetic_fetch', source: item.url, state: 'failed', confidence: 'confirmed', raw: error.message, limitations: [error.message], authority: { source_authority: 'unknown', collection_authority: 'synthetic_probe', authenticity_status: 'unverified', representativeness: 'single_observation' } }));
+    }
+  }
+  return observationRun(root, 'observe representation', surface.url, observations, { rawInputs: { release_manifest: input.raw }, incomplete, artifacts });
+}
+
 export async function observe(root, mode, options = {}) {
   switch (mode) {
     case 'render': return observeRender(root, options);
@@ -381,6 +462,7 @@ export async function observe(root, mode, options = {}) {
     case 'performance': return observePerformance(root, options);
     case 'corroboration': return observeCorroboration(root, options);
     case 'media': return observeMedia(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, or media');
+    case 'representation': return observeRepresentation(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, media, or representation');
   }
 }