@nebulacomponents/citable 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -88,5 +88,13 @@
     "ajv-formats": "^3.0.1",
     "js-yaml": "^5.2.1",
     "node-html-parser": "^9.0.0"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.50.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
   }
 }

package/schemas/observation.schema.json

@@ -0,0 +1,20 @@
+{
+  "$id": "citable://schemas/observation.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Collected observation envelope",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["observation_id", "kind", "state", "collected_at", "collection_method", "confidence", "source", "evidence_hash", "data"],
+  "properties": {
+    "observation_id": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration"] },
+    "state": { "type": "string", "enum": ["observed", "not_observed", "not_evidenced", "incomplete", "review_required", "failed"] },
+    "collected_at": { "type": "string", "format": "date-time" },
+    "collection_method": { "type": "string", "enum": ["live_api", "browser", "owner_import", "synthetic_fetch", "static_analysis", "human_review"] },
+    "confidence": { "type": "string", "enum": ["confirmed", "high", "medium", "low", "unknown"] },
+    "source": { "type": "string", "minLength": 1 },
+    "evidence_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "data": { "type": "object" },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/remediation-spec.schema.json

@@ -0,0 +1,28 @@
+{
+  "$id": "citable://schemas/remediation-spec.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Guarded remediation specification",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source_run_id", "operations"],
+  "properties": {
+    "source_run_id": { "type": "string" },
+    "operations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["operation_id", "file", "find", "replace", "expected_file_hash", "finding_ids"],
+        "properties": {
+          "operation_id": { "type": "string" },
+          "file": { "type": "string", "minLength": 1 },
+          "find": { "type": "string", "minLength": 1 },
+          "replace": { "type": "string" },
+          "expected_file_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "finding_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "reviewer": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,7 +7,7 @@ description: >
   generative engine optimization, structured data governance, claim substantiation,
   crawler policy, entity consistency, content discoverability, or wants a site audited
   for how search and AI systems will retrieve, understand, cite, or recommend it.
-version: 1.3.1
+version: 1.4.0
 ---
 
 # Citable — search & generative discoverability governance
@@ -85,6 +85,9 @@ citable schema --target <dir|url>
 citable validate [registries|claims|evidence|schema|links]
 citable compare-snapshots [runA runB]
 citable action-plan [run-id]          # ordered actions, blockers, semantic gates, verification
+citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
+citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
+citable monitor [runA runB]           # observation regression alerts
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -126,6 +129,9 @@ mandatory semantic reviews make the relevant posture `not_established`.
 Consult `references/capability-boundaries.md` before claiming any observation;
 it identifies which states the current CLI can collect and which require
 operator data or future adapters.
+Use `commands/observe-and-act.md` for collector prerequisites, evidence labels,
+the controlled citation adapter protocol, remediation refusal conditions, and
+monitoring interpretation.
 
 ## Command workflows
 

package/skill/commands/README.md

@@ -21,11 +21,14 @@ intent, not executability, so statuses are strict:
 | /citable validate, validate-claims, validate-evidence, validate-schema, validate-links | implemented |
 | /citable compare-snapshots / validate-regression | implemented |
 | /citable action-plan | implemented — writes ordered, source-run-bound action artifacts outside immutable evidence packages |
+| /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
+| /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
+| /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |
-| /citable validate-render | specified (validate-render.md) — blocked on the rendered-truth phase (docs/detectors/render-phase-plan.md) |
-| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | specified (measurement.md) — no external engine adapters exist or are claimed |
+| /citable validate-render | partially implemented by `observe render`; mobile/cross-browser and interaction exploration remain |
+| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by observation imports, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/skill/commands/measurement.md

@@ -1,14 +1,14 @@
 ---
 command: /citable measure seo|aeo|geo, test-prompts, monitor-crawlers, monitor-contradictions
-purpose: Observation and measurement workflows. Citable records and validates observations; it does not claim live engine adapters it does not have.
+purpose: Observation and measurement workflows with exact collector and product-mode boundaries.
 ---
 
 # Honest capability statement
 
-This MVP ships **no external engine adapters** (no Search Console API client,
-no ChatGPT/Perplexity automation). Measurement commands therefore operate on
-*operator-supplied observations*, validated against the data contracts, plus
-registry-side integrity checks (MEAS-001/002/003). Do not imply otherwise.
+Citable ships Google URL Inspection, CrUX field collection, normalized owner
+imports, and a disclosed custom citation-adapter protocol. It does not claim
+Bing AI Performance automation or equivalence between an API adapter and a
+consumer answer product. Preserve collector and product mode on every result.
 
 # measure seo
 Inputs the operator exports (Search Console/Bing/analytics CSV or JSON).

package/skill/commands/observe-and-act.md

@@ -0,0 +1,40 @@
+---
+command: /citable observe|apply|monitor
+purpose: Collect external and rendered evidence, apply reviewed source changes, and detect regressions without collapsing unlike evidence states.
+failure_behaviour: unavailable dependency, credential, source run, reviewer, exact hash, or unique replacement -> incomplete or fail; never infer success
+---
+
+# Observe, apply, and monitor
+
+## Collection modes
+
+- `observe render --target <URL>` uses optional Playwright. Browser evidence is
+  not search-index evidence.
+- `observe index --input <JSON>` imports owner exports. With `--target`,
+  `--site-url`, and `GSC_ACCESS_TOKEN`, it calls Google URL Inspection, which
+  reports the indexed version rather than performing a live indexability test.
+- `observe citations --input <JSON>` imports complete controlled observations.
+  With `--endpoint`, the input is a versioned prompt corpus and each prompt runs
+  1-20 times (default 3) through the disclosed adapter protocol. An API is not
+  presumed equivalent to a provider's consumer search experience.
+- `observe logs --input <JSON>` imports server/CDN records. User-agent matches
+  without IP verification remain low confidence.
+- `observe passages|consensus --target <dir|URL>` performs static extraction.
+- `observe performance` imports evidence or calls CrUX with `CRUX_API_KEY`.
+- `observe corroboration --input <JSON>` records observable external mentions;
+  controlled or unverified sources do not become authority claims.
+
+## Guarded remediation
+
+`apply --input remediation-spec.json` is a dry run. Every operation binds to an
+existing audit run and finding IDs, stays inside repository source, names a
+reviewer, matches the exact file hash, and identifies exactly one source string.
+`--write` applies only after all operations validate. Build, tests, semantic
+review, re-audit, and snapshot comparison remain mandatory afterward.
+
+## Monitoring
+
+`monitor [runA runB]` reports state changes, missing observations, index loss,
+canonical disagreement, and citation-presence changes. Alerts are evidence
+changes, not causal explanations or ranking conclusions. Schedule it in CI at
+the cadence defined by lifecycle and experiment records.

package/skill/references/capability-boundaries.md

@@ -6,18 +6,18 @@ Use the narrowest supported state. Never promote evidence across rows.
 | --- | --- | --- |
 | Allowed by policy | Implemented | Effective robots rule plus crawler-purpose registry decision |
 | Synthetic fetch succeeded | Partial | Captured status, redirects, headers, body from the declared user agent; label identity simulated |
-| Verified crawler reached edge | Operator supplied | Request log plus provider-published IP verification where supported |
-| Observed in production logs | Operator supplied | Timestamped server/CDN log with URL, status, bytes, latency, cache result, UA, and verification result |
-| Indexed | Operator supplied | Search Console/Bing Webmaster/API or timestamped engine observation |
+| Verified crawler reached edge | Imported evidence | `observe logs` record plus provider-published IP verification where supported |
+| Observed in production logs | Imported evidence | Timestamped `observe logs` artifact with URL, status, bytes, latency, cache result, UA, and verification result |
+| Indexed | Google API or imported evidence | `observe index`; Google inspection covers the indexed version, other engines require owner exports |
 | Returned by retrieval | Operator supplied | Provider observation containing retrieved source URL |
-| Cited | Operator supplied | Complete answer observation with citation URL |
-| Materially supports answer | Human review required | Answer claim mapped to a passage that entails it |
+| Cited | Import or disclosed adapter | Complete `observe citations` answer with citation URL and product/adapter mode |
+| Materially supports answer | Human review required | `citation_review` maps answer claim to source passage and names the reviewer |
 | Recommended | Operator supplied + review | Explicit recommendation, constraints, provider/mode/locale/time |
 
-Current CLI URL mode does not prove crawler identity, WAF allowlisting,
+URL audit mode alone does not prove crawler identity, WAF allowlisting,
 production-log access, index presence, selected canonical, rendered DOM parity,
-or provider citation behavior. Record those states as `not_evidenced` unless the
-specified evidence is supplied.
+or provider citation behavior. Observation collectors can supply narrower
+evidence for these states; unavailable inputs remain `not_evidenced`.
 
 Primary-source lineage for these boundaries:
 

package/src/cli/index.js

@@ -12,6 +12,9 @@ import { compareSnapshots } from '../commands/compareSnapshots.js';
 import { isInstallerCommand, runInstallerCommand } from '../installer/index.js';
 import { selfUpgradeCommand, selfUpgradeExitCode } from '../commands/selfUpgrade.js';
 import { actionPlan } from '../commands/actionPlan.js';
+import { observe } from '../commands/observe.js';
+import { applyRemediation } from '../commands/applyRemediation.js';
+import { monitor } from '../commands/monitor.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -34,12 +37,23 @@ Commands
   validate [mode]           registries (default) | claims | evidence | schema | links
   compare-snapshots [a b]   Regression diff between two audit runs
   action-plan [run]         Turn audit findings into ordered remediation work
+  observe <mode>            Collect render, index, citation, log, passage,
+                            consensus, performance, or corroboration evidence
+  apply                     Apply a reviewed, hash-locked remediation spec
+  monitor [runA runB]       Compare observation runs and emit regression alerts
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 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)
+  --input <file>            Import file or remediation specification
+  --provider <name>         Provider label for imported observations
+  --api-key <key>           API key (prefer provider environment variables)
+  --site-url <property>     Search Console property for live URL inspection
+  --access-token <token>    OAuth token (prefer provider environment variables)
+  --endpoint <url>          Controlled citation adapter endpoint
+  --repeat <count>          Repetitions per prompt for citation experiments
   --write                   Persist registry changes (map-claims, substantiate)
   --json                    Machine-readable output only
 
@@ -55,6 +69,14 @@ function parseArgs(argv) {
     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 === '--input') args.input = argv[++i];
+    else if (a === '--provider') args.provider = argv[++i];
+    else if (a === '--api-key') args.apiKey = argv[++i];
+    else if (a === '--site-url') args.siteUrl = argv[++i];
+    else if (a === '--access-token') args.accessToken = argv[++i];
+    else if (a === '--endpoint') args.endpoint = argv[++i];
+    else if (a === '--repeat') args.repeat = Number(argv[++i]);
+    else if (a === '--timeout') args.timeout = Number(argv[++i]);
     else if (a === '--force') args.force = true;
     else args._.push(a);
   }
@@ -128,6 +150,23 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args, `action-plan: ${r.summary.total_actions} action(s) [ready:${r.summary.ready} blocked:${r.summary.blocked}]\nPlan: ${path.join(r.dir, 'action-plan.md')}\nSource audit: ${r.source_run_id}`, r);
         break;
       }
+      case 'observe': {
+        const mode = args._[0];
+        const r = await observe(root, mode, args);
+        out(args, `observe ${mode}: ${r.summary.total} observation(s) [${Object.entries(r.summary.by_state).map(([k, v]) => `${k}:${v}`).join(' ')}]\nEvidence package: ${r.dir}\nStatus: ${r.manifest.status}`, r);
+        break;
+      }
+      case 'apply': {
+        const r = applyRemediation(root, args);
+        out(args, `apply: ${r.operations.length} operation(s) ${r.write ? 'applied' : 'proposed (dry run)'}\nEvidence package: ${r.dir}\nSource audit: ${r.source_run_id}`, r);
+        break;
+      }
+      case 'monitor': {
+        const r = monitor(root, { runA: args._[0], runB: args._[1] });
+        out(args, `monitor ${r.run_a} → ${r.run_b}: ${r.summary.alerts} alert(s), ${r.summary.critical_or_high} critical/high\nReport: ${path.join(r.dir, 'latest.json')}`, r);
+        if (r.summary.critical_or_high > 0) process.exitCode = 1;
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);

package/src/commands/applyRemediation.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRun } from '../evidence/run.js';
+import { readJson, sha256 } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function inside(root, candidate) {
+  const base = path.resolve(root) + path.sep;
+  const resolved = path.resolve(root, candidate);
+  if (!resolved.startsWith(base) || resolved.includes(`${path.sep}.git${path.sep}`) || resolved.includes(`${path.sep}.citable${path.sep}`)) {
+    throw new Error(`remediation file escapes editable source boundary: ${candidate}`);
+  }
+  return resolved;
+}
+
+export function applyRemediation(root, { input, write = false } = {}) {
+  if (!input || !fs.existsSync(input)) throw new Error('apply requires --input <remediation-spec.json>');
+  const raw = fs.readFileSync(input, 'utf8');
+  const spec = readJson(input);
+  const valid = validateAgainst('remediation-spec.schema.json', spec);
+  if (!valid.valid) throw new Error(`remediation spec invalid: ${valid.errors.join('; ')}`);
+  const manifestFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'manifest.json');
+  if (!fs.existsSync(manifestFile)) throw new Error(`source run not found: ${spec.source_run_id}`);
+  const findingsFile = path.join(root, '.citable', 'runs', spec.source_run_id, 'findings.json');
+  if (!fs.existsSync(findingsFile)) throw new Error(`source run has no findings: ${spec.source_run_id}`);
+  const sourceFindingIds = new Set(readJson(findingsFile).map((finding) => finding.finding_id));
+  const results = [];
+  const pending = [];
+  for (const operation of spec.operations) {
+    const unknownFindings = operation.finding_ids.filter((id) => !sourceFindingIds.has(id));
+    if (unknownFindings.length) throw new Error(`operation ${operation.operation_id} references findings outside source run: ${unknownFindings.join(', ')}`);
+    const file = inside(root, operation.file);
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`remediation target is not a file: ${operation.file}`);
+    const before = fs.readFileSync(file, 'utf8');
+    if (sha256(before) !== operation.expected_file_hash) throw new Error(`stale remediation refused for ${operation.file}: file hash changed`);
+    if (!operation.reviewer) throw new Error(`reviewer required for operation ${operation.operation_id}`);
+    const matches = before.split(operation.find).length - 1;
+    if (matches !== 1) throw new Error(`operation ${operation.operation_id} expected exactly one match, observed ${matches}`);
+    const after = before.replace(operation.find, operation.replace);
+    pending.push({ file, before, after });
+    results.push({ operation_id: operation.operation_id, file: operation.file, finding_ids: operation.finding_ids, reviewer: operation.reviewer, before_hash: sha256(before), after_hash: sha256(after), status: write ? 'applied' : 'proposed' });
+  }
+  if (write) {
+    const written = [];
+    try {
+      for (const change of pending) { fs.writeFileSync(change.file, change.after); written.push(change); }
+    } catch (error) {
+      for (const change of written.reverse()) fs.writeFileSync(change.file, change.before);
+      throw new Error(`remediation write failed and prior writes were rolled back: ${error.message}`);
+    }
+  }
+  const run = createRun(root, { command: 'apply', argv: process.argv.slice(2), target: { kind: 'source', location: root, environment: 'local' } });
+  run.addInput('remediation_spec', raw);
+  run.writeArtifact('remediation/results.json', { source_run_id: spec.source_run_id, write, operations: results });
+  run.manifest.warnings.push(write ? 'Source changes applied; build, test, re-audit, and snapshot comparison remain required.' : 'Dry run only; no source files were changed.');
+  return { runId: run.runId, dir: run.finalize('completed_with_warnings'), source_run_id: spec.source_run_id, write, operations: results };
+}

package/src/commands/monitor.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson, nowIso } from '../shared/io.js';
+
+function observations(dir) {
+  const folder = path.join(dir, 'observations');
+  if (!fs.existsSync(folder)) return [];
+  return fs.readdirSync(folder).filter((f) => f.endsWith('.json')).sort().map((f) => readJson(path.join(folder, f)));
+}
+
+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(':');
+  return [item.kind, d.url || d.citation_url || d.prompt_id || d.timestamp || item.observation_id].join(':');
+}
+
+export function monitor(root, { runA, runB } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runsDir)) throw new Error('no runs available to monitor');
+  const candidates = fs.readdirSync(runsDir).filter((r) => fs.existsSync(path.join(runsDir, r, 'observations'))).sort();
+  const b = runB || candidates.at(-1), a = runA || candidates.at(-2);
+  if (!a || !b) throw new Error('monitor requires two observation runs');
+  const before = new Map(observations(path.join(runsDir, a)).map((o) => [key(o), o]));
+  const after = new Map(observations(path.join(runsDir, b)).map((o) => [key(o), o]));
+  const alerts = [];
+  for (const [k, current] of after) {
+    const previous = before.get(k);
+    if (!previous) alerts.push({ severity: 'informational', type: 'new_observation', key: k, current_state: current.state });
+    else if (previous.state !== current.state) alerts.push({ severity: ['failed', 'not_observed'].includes(current.state) ? 'high' : 'medium', type: 'state_change', key: k, previous_state: previous.state, current_state: current.state });
+    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 });
+  }
+  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 };
+  const dir = path.join(root, '.citable', 'monitoring');
+  writeJson(path.join(dir, `${a}--${b}.json`), result);
+  writeJson(path.join(dir, 'latest.json'), result);
+  return { ...result, dir };
+}

package/src/commands/observe.js

@@ -0,0 +1,235 @@
+import { buildContext } from './context.js';
+import { envelope, observationRun, readInput } from '../observations/common.js';
+import { sha256 } from '../shared/io.js';
+import { fetchUrl } from '../crawler/fetch.js';
+import net from 'node:net';
+
+const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
+const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
+
+function canonicalReview(raw, targetOrigin) {
+  const citations = raw.citations || [];
+  return citations.map((citation, index) => {
+    const url = typeof citation === 'string' ? citation : citation.url;
+    const canonical = typeof citation === 'object' ? citation.canonical_url || url : url;
+    const supports = typeof citation === 'object' ? citation.support_status || 'review_required' : 'review_required';
+    return {
+      citation_url: url, canonical_url: canonical, citation_order: index + 1,
+      first_party: Boolean(targetOrigin && originOf(canonical) === targetOrigin),
+      support_status: supports,
+      answer_claim: typeof citation === 'object' ? citation.answer_claim || null : null,
+      source_passage: typeof citation === 'object' ? citation.source_passage || null : null,
+      reviewer: typeof citation === 'object' ? citation.reviewer || null : null,
+    };
+  });
+}
+
+async function observeRender(root, options) {
+  if (!options.target || !/^https?:\/\//.test(options.target)) throw new Error('render requires --target <http(s) URL>');
+  let playwright;
+  try { playwright = await import('playwright'); } catch {
+    const item = envelope('render', { url: options.target }, { method: 'browser', source: 'playwright', state: 'not_evidenced', confidence: 'unknown', limitations: ['Optional Playwright dependency is not installed.'] });
+    return observationRun(root, 'observe render', options.target, [item], { incomplete: ['Rendered DOM capture unavailable: install Playwright and a Chromium browser.'] });
+  }
+  const initial = await fetchUrl(options.target, { timeoutMs: options.timeout || 30000, maxRetries: 1 });
+  const browser = await playwright.chromium.launch({ headless: true });
+  try {
+    const capture = async (name, viewport, isMobile = false) => {
+      const context = await browser.newContext({ viewport, isMobile });
+      const page = await context.newPage();
+      const failures = [];
+      page.on('requestfailed', (request) => failures.push({ url: request.url(), error: request.failure()?.errorText || 'unknown' }));
+      const response = await page.goto(options.target, { waitUntil: 'networkidle', timeout: options.timeout || 30000 });
+      const html = await page.content(), text = await page.locator('body').innerText(), screenshot = await page.screenshot({ fullPage: true });
+      const result = { name, final_url: page.url(), status: response?.status() ?? null, viewport, html, text, screenshot, failed_requests: failures };
+      await context.close();
+      return result;
+    };
+    const desktop = await capture('desktop', { width: 1280, height: 900 });
+    const mobile = await capture('mobile', { width: 390, height: 844 }, true);
+    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 data = {
+      url: options.target, initial: { final_url: initial.url, status: initial.status, html_hash: sha256(initial.body), text_hash: sha256(initialText), word_count: words(initialText).length, redirect_chain: initial.redirectChain },
+      desktop: { final_url: desktop.final_url, status: desktop.status, html_hash: sha256(desktop.html), text_hash: sha256(desktop.text), word_count: words(desktop.text).length, failed_requests: desktop.failed_requests },
+      mobile: { final_url: mobile.final_url, status: mobile.status, html_hash: sha256(mobile.html), text_hash: sha256(mobile.text), word_count: words(mobile.text).length, failed_requests: mobile.failed_requests },
+      parity: { initial_to_desktop_word_ratio: words(desktop.text).length ? Number((words(initialText).length / words(desktop.text).length).toFixed(3)) : null, mobile_to_desktop_word_ratio: words(desktop.text).length ? Number((words(mobile.text).length / words(desktop.text).length).toFixed(3)) : null },
+    };
+    const item = envelope('render', data, { method: 'browser', source: 'playwright/chromium', raw: `${initial.body}\n${desktop.html}\n${mobile.html}` });
+    return observationRun(root, 'observe render', options.target, [item], { artifacts: { 'initial/response.html': initial.body, 'rendered/desktop-dom.html': desktop.html, 'rendered/desktop-text.txt': desktop.text, 'rendered/mobile-dom.html': mobile.html, 'rendered/mobile-text.txt': mobile.text, 'screenshots/desktop.png': desktop.screenshot, 'screenshots/mobile.png': mobile.screenshot } });
+  } finally { await browser.close(); }
+}
+
+async function observeIndex(root, options) {
+  if (!options.input) {
+    if (!options.target || !options.siteUrl) throw new Error('live index observation requires --target <URL> and --site-url <Search Console property>');
+    const token = options.accessToken || process.env.GSC_ACCESS_TOKEN;
+    if (!token) {
+      const item = envelope('index', { engine: 'google', url: options.target }, { method: 'live_api', source: 'Google Search Console URL Inspection API', state: 'not_evidenced', confidence: 'unknown', limitations: ['GSC_ACCESS_TOKEN is not configured.'] });
+      return observationRun(root, 'observe index', options.target, [item], { incomplete: ['Google index inspection unavailable: GSC_ACCESS_TOKEN is not configured.'] });
+    }
+    const response = await fetch('https://searchconsole.googleapis.com/v1/urlInspection/index:inspect', { method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify({ inspectionUrl: options.target, siteUrl: options.siteUrl, languageCode: options.locale || 'en-US' }) });
+    const raw = await response.text();
+    if (!response.ok) throw new Error(`Search Console returned ${response.status}: ${raw.slice(0, 300)}`);
+    const value = JSON.parse(raw).inspectionResult?.indexStatusResult || {};
+    const data = { engine: 'google', url: options.target, indexed: value.verdict === 'PASS', selected_canonical: value.googleCanonical || null, declared_canonical: value.userCanonical || null, last_crawl: value.lastCrawlTime || null, fetch_state: value.pageFetchState || null, raw_provider_result: value };
+    return observationRun(root, 'observe index', options.target, [envelope('index', data, { method: 'live_api', source: 'Google Search Console URL Inspection API', raw })], { rawInputs: { gsc_response: raw } });
+  }
+  const input = readInput(options.input);
+  const rows = Array.isArray(input.value) ? input.value : input.value.items || [input.value];
+  const observations = rows.map((row) => envelope('index', {
+    engine: row.engine || options.provider || 'unknown', url: row.url || row.inspectionUrl,
+    indexed: row.indexed ?? row.verdict === 'PASS', selected_canonical: row.selected_canonical || row.googleCanonical || null,
+    declared_canonical: row.declared_canonical || row.userCanonical || null, last_crawl: row.last_crawl || row.lastCrawlTime || null,
+    fetch_state: row.fetch_state || row.pageFetchState || null, raw_provider_result: row,
+  }, { method: 'owner_import', source: input.file, raw: JSON.stringify(row), confidence: 'confirmed' }));
+  return observationRun(root, 'observe index', input.file, observations, { rawInputs: { index_export: input.raw } });
+}
+
+async function observeCitations(root, options) {
+  const input = readInput(options.input);
+  let rows = Array.isArray(input.value) ? input.value : input.value.observations || [input.value];
+  let method = 'owner_import';
+  if (options.endpoint) {
+    const prompts = input.value.prompts || (Array.isArray(input.value) ? input.value : []);
+    if (!prompts.length) throw new Error('citation runner input must contain a prompts array');
+    if (!/^https:\/\//.test(options.endpoint) && !/^http:\/\/(127\.0\.0\.1|localhost)(:\d+)?\//.test(options.endpoint)) throw new Error('citation adapter endpoint must use HTTPS (loopback HTTP is allowed for testing)');
+    const repeat = Number.isInteger(options.repeat) && options.repeat > 0 && options.repeat <= 20 ? options.repeat : 3;
+    rows = [];
+    for (const prompt of prompts) for (let runIndex = 1; runIndex <= repeat; runIndex++) {
+      const response = await fetch(options.endpoint, { method: 'POST', headers: { 'content-type': 'application/json', ...(options.accessToken ? { authorization: `Bearer ${options.accessToken}` } : {}) }, body: JSON.stringify({ prompt_id: prompt.prompt_id, prompt_text: prompt.prompt_text, locale: prompt.locale || input.value.locale || 'en-US', run_index: runIndex, runs_in_series: repeat }) });
+      const rawResponse = await response.text();
+      if (!response.ok) throw new Error(`citation adapter returned ${response.status}: ${rawResponse.slice(0, 300)}`);
+      const result = JSON.parse(rawResponse);
+      rows.push({ ...result, prompt_id: prompt.prompt_id, prompt_text: prompt.prompt_text, locale: prompt.locale || input.value.locale || 'en-US', provider: result.provider || options.provider || 'custom-adapter', product_mode: result.product_mode || 'api-adapter', run_index: runIndex, runs_in_series: repeat });
+    }
+    method = 'live_api';
+  }
+  const targetOrigin = options.target ? originOf(options.target) : input.value.target_origin || null;
+  const observations = [];
+  for (const row of rows) {
+    const reviews = canonicalReview(row, targetOrigin);
+    observations.push(envelope('citation', {
+      prompt_id: row.prompt_id, prompt_text: row.prompt_text, provider: row.provider || row.engine,
+      product_mode: row.product_mode || row.interface || 'unknown', locale: row.locale || 'unknown',
+      answer_text: row.answer_text || '', citations: reviews, run_index: row.run_index || 1,
+      property_cited: reviews.some((r) => r.first_party),
+    }, { method, source: options.endpoint || input.file, raw: JSON.stringify(row) }));
+    for (const review of reviews) observations.push(envelope('citation_review', review, {
+      method: review.reviewer ? 'human_review' : 'static_analysis', source: options.endpoint || input.file,
+      state: review.support_status === 'review_required' ? 'review_required' : 'observed',
+      confidence: review.reviewer ? 'confirmed' : 'low', raw: JSON.stringify(review),
+      limitations: review.reviewer ? [] : ['Material support requires a named human reviewer.'],
+    }));
+  }
+  return observationRun(root, 'observe citations', input.file, observations, { rawInputs: { citation_results: input.raw } });
+}
+
+function observeLogs(root, options) {
+  const input = readInput(options.input);
+  const rows = Array.isArray(input.value) ? input.value : input.value.requests || [];
+  const ranges = input.value.provider_ranges || {};
+  const verify = (row) => {
+    const cidrs = ranges[row.user_agent] || [];
+    if (!row.source_ip || !cidrs.length) return { verified: false, method: null };
+    const family = net.isIP(row.source_ip);
+    if (!family) return { verified: false, method: 'invalid source IP' };
+    const block = new net.BlockList();
+    for (const cidr of cidrs) {
+      const [network, prefix] = cidr.split('/');
+      const rangeFamily = net.isIP(network);
+      if (rangeFamily === family && Number.isInteger(Number(prefix))) block.addSubnet(network, Number(prefix), family === 4 ? 'ipv4' : 'ipv6');
+    }
+    return { verified: block.check(row.source_ip, family === 4 ? 'ipv4' : 'ipv6'), method: `matched imported ${row.user_agent} CIDR set` };
+  };
+  const observations = rows.map((row) => {
+    const identity = verify(row);
+    return envelope('crawler_log', {
+    timestamp: row.timestamp, url: row.url, user_agent: row.user_agent, source_ip: row.source_ip,
+    status: row.status, bytes: row.bytes ?? null, latency_ms: row.latency_ms ?? null,
+    cache_status: row.cache_status ?? null, region: row.region ?? null,
+    identity_verified: identity.verified, verification_method: identity.method,
+  }, { method: 'owner_import', source: input.file, raw: JSON.stringify(row), confidence: identity.verified ? 'high' : 'low', limitations: identity.verified ? ['CIDR ranges were imported with the log evidence; their provider currency must be established by source metadata.'] : ['User-agent strings alone do not verify crawler identity.'] });
+  });
+  return observationRun(root, 'observe logs', input.file, observations, { rawInputs: { server_logs: input.raw }, incomplete: observations.some((o) => !o.data.identity_verified) ? ['Some crawler identities are not IP-verified.'] : [] });
+}
+
+async function observePassages(root, options) {
+  const ctx = await buildContext(root, options);
+  if (!ctx.site) throw new Error('passages requires --target <dir|url>');
+  const observations = [];
+  for (const page of ctx.site.pages) {
+    const rawWords = words(page.text).length;
+    for (let i = 0; i < page.paragraphs.length; i++) {
+      const passage = page.paragraphs.slice(i, i + 3).join(' ');
+      const count = words(passage).length;
+      if (count < 30) continue;
+      const dependencies = [];
+      if (/\b(this|that|these|those|it|they|above|below|here)\b/i.test(passage.slice(0, 100))) dependencies.push('possible external referent');
+      observations.push(envelope('passage', { url: page.url, passage_index: i, text: passage, word_count: count, independently_extractable: count >= 100 && count <= 300 && dependencies.length === 0, dependencies, content_to_noise_ratio: page.rawHtml.length ? Number((page.text.length / page.rawHtml.length).toFixed(3)) : null }, { method: 'static_analysis', source: page.sourceFile || page.url, raw: passage, confidence: 'medium' }));
+    }
+    if (!page.paragraphs.length) observations.push(envelope('passage', { url: page.url, word_count: rawWords, independently_extractable: false, dependencies: ['no paragraph passages extracted'] }, { method: 'static_analysis', source: page.sourceFile || page.url, state: 'not_observed', confidence: 'confirmed' }));
+  }
+  return observationRun(root, 'observe passages', options.target, observations);
+}
+
+async function observeConsensus(root, options) {
+  const ctx = await buildContext(root, options);
+  if (!ctx.site) throw new Error('consensus requires --target <dir|url>');
+  const sitemapRows = ctx.site.sitemaps.flatMap((s) => s.parsed?.urls || []);
+  const sitemapUrls = new Set(sitemapRows.map((u) => u.loc));
+  const observations = ctx.site.pages.map((page) => {
+    const declared = page.canonicals[0] || null;
+    const sitemapDate = sitemapRows.find((row) => row.loc === page.url)?.lastmod || null;
+    const visibleDate = page.metas['article:modified_time']?.[0] || page.metas['date.modified']?.[0] || page.metas['last-modified']?.[0] || null;
+    const signals = { final_url: page.url, html_canonical: declared, open_graph_url: page.ogUrl, sitemap_present: sitemapUrls.has(page.url), last_modified_header: page.headers['last-modified'] || null, sitemap_lastmod: sitemapDate, visible_or_meta_modified: visibleDate };
+    const urls = [page.url, declared, page.ogUrl].filter(Boolean);
+    const dates = [signals.last_modified_header, sitemapDate, visibleDate].filter(Boolean).map((value) => String(value).slice(0, 10));
+    return envelope('canonical_freshness', { url: page.url, signals, canonical_consensus: new Set(urls).size <= 1, date_consensus: dates.length >= 2 ? new Set(dates).size === 1 : null, engine_selected_canonical: null }, { method: 'static_analysis', source: page.sourceFile || page.url, raw: JSON.stringify(signals), confidence: 'high', limitations: ['Engine-selected canonical and content-difference date require external observations.'] });
+  });
+  return observationRun(root, 'observe consensus', options.target, observations);
+}
+
+async function observePerformance(root, options) {
+  if (options.input) {
+    const input = readInput(options.input);
+    const rows = Array.isArray(input.value) ? input.value : [input.value];
+    const observations = rows.map((row) => {
+      const provider = row.provider || (row.lighthouseVersion || row.categories ? 'Lighthouse' : row.record ? 'CrUX' : 'unknown');
+      const evidenceType = /lighthouse/i.test(provider) ? 'lab' : /crux|chrome ux/i.test(provider) ? 'field' : 'imported_unknown';
+      return envelope('performance', { ...row, provider, evidence_type: evidenceType }, { method: 'owner_import', source: input.file, raw: JSON.stringify(row), limitations: evidenceType === 'imported_unknown' ? ['Performance evidence was not identified as field or lab data.'] : [] });
+    });
+    return observationRun(root, 'observe performance', input.file, observations, { rawInputs: { performance_export: input.raw } });
+  }
+  if (!options.target) throw new Error('performance requires --target <URL> or --input <json>');
+  const key = options.apiKey || process.env.CRUX_API_KEY;
+  if (!key) {
+    const item = envelope('performance', { url: options.target, provider: 'CrUX' }, { method: 'live_api', source: 'CrUX API', state: 'not_evidenced', confidence: 'unknown', limitations: ['CRUX_API_KEY is not configured.'] });
+    return observationRun(root, 'observe performance', options.target, [item], { incomplete: ['CrUX collection unavailable: CRUX_API_KEY is not configured.'] });
+  }
+  const response = await fetch(`https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${encodeURIComponent(key)}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ url: options.target }) });
+  const raw = await response.text();
+  if (!response.ok) throw new Error(`CrUX API returned ${response.status}: ${raw.slice(0, 300)}`);
+  const data = JSON.parse(raw);
+  return observationRun(root, 'observe performance', options.target, [envelope('performance', { ...data, provider: 'CrUX', evidence_type: 'field' }, { method: 'live_api', source: 'CrUX API', raw })], { rawInputs: { crux_response: raw } });
+}
+
+function observeCorroboration(root, options) {
+  const input = readInput(options.input);
+  const rows = Array.isArray(input.value) ? input.value : input.value.mentions || [];
+  const observations = rows.map((row) => envelope('corroboration', row, { method: 'owner_import', source: input.file, raw: JSON.stringify(row), confidence: row.independent === true ? 'high' : 'low', limitations: row.independent === true ? [] : ['Source independence is not established.'] }));
+  return observationRun(root, 'observe corroboration', input.file, observations, { rawInputs: { corroboration_export: input.raw } });
+}
+
+export async function observe(root, mode, options = {}) {
+  switch (mode) {
+    case 'render': return observeRender(root, options);
+    case 'index': return observeIndex(root, options);
+    case 'citations': return observeCitations(root, options);
+    case 'logs': return observeLogs(root, options);
+    case 'passages': return observePassages(root, options);
+    case 'consensus': return observeConsensus(root, options);
+    case 'performance': return observePerformance(root, options);
+    case 'corroboration': return observeCorroboration(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, passages, consensus, performance, or corroboration');
+  }
+}