@nebulacomponents/citable 1.3.1 → 1.5.0

package/src/commands/measurement.js

@@ -0,0 +1,205 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseCsv } from 'csv-parse/sync';
+import { loadRegistries, saveRegistry } from '../registries/index.js';
+import { envelope, observationRun } from '../observations/common.js';
+import { parseRefDate, readJson, readYaml } from '../shared/io.js';
+import { validateAgainst } from '../shared/schemaValidator.js';
+
+function inputDocument(file) {
+  if (!file) throw new Error('--input <file> is required');
+  if (!fs.existsSync(file)) throw new Error(`input not found: ${file}`);
+  const raw = fs.readFileSync(file, 'utf8');
+  const ext = path.extname(file).toLowerCase();
+  if (ext === '.csv') return { raw, rows: parseCsv(raw, { columns: true, skip_empty_lines: true, trim: true }), file: path.resolve(file) };
+  const value = ext === '.yaml' || ext === '.yml' ? readYaml(file) : readJson(file);
+  return { raw, rows: Array.isArray(value) ? value : value.rows || value.entries || [value], file: path.resolve(file) };
+}
+
+function numericValue(raw, type, rowNumber) {
+  if (raw === '' || raw == null) throw new Error(`row ${rowNumber}: value is required`);
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new Error(`row ${rowNumber}: value must be numeric`);
+  if (type === 'integer' && !Number.isInteger(value)) throw new Error(`row ${rowNumber}: value must be an integer`);
+  return value;
+}
+
+function isoTime(raw, field, rowNumber) {
+  if (!raw || Number.isNaN(new Date(raw).getTime())) throw new Error(`row ${rowNumber}: ${field} must be a valid date-time`);
+  return new Date(raw).toISOString();
+}
+
+export function importMetrics(root, { input, provider }) {
+  if (!provider) throw new Error('metrics import requires --provider <name>');
+  const source = inputDocument(input);
+  if (!source.rows.length) throw new Error('metric import contains no rows');
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const definitions = new Map(registries.metrics.entries.map((metric) => [metric.metric_id, metric]));
+  const observations = source.rows.map((row, index) => {
+    const rowNumber = index + 1;
+    const metric = definitions.get(row.metric_id);
+    if (!metric) throw new Error(`row ${rowNumber}: unknown metric_id ${row.metric_id || '(missing)'}`);
+    if (metric.status === 'deprecated') throw new Error(`row ${rowNumber}: metric ${metric.metric_id} is deprecated`);
+    if (metric.provider.toLowerCase() !== String(provider).toLowerCase()) {
+      throw new Error(`row ${rowNumber}: metric ${metric.metric_id} belongs to ${metric.provider}, not ${provider}`);
+    }
+    const observedAt = isoTime(row.observed_at || row.date, 'observed_at', rowNumber);
+    const dimensions = {};
+    for (const dimension of metric.dimensions) {
+      if (row[dimension] != null && row[dimension] !== '') dimensions[dimension] = String(row[dimension]);
+    }
+    const data = {
+      metric_id: metric.metric_id,
+      provider: metric.provider,
+      external_name: metric.external_name,
+      value: numericValue(row.value, metric.value_type, rowNumber),
+      unit: metric.unit === 'custom' ? metric.custom_unit : metric.unit,
+      aggregation: metric.aggregation,
+      observed_at: observedAt,
+      period_start: row.period_start ? isoTime(row.period_start, 'period_start', rowNumber) : observedAt,
+      period_end: row.period_end ? isoTime(row.period_end, 'period_end', rowNumber) : observedAt,
+      dimensions,
+      source_row: rowNumber,
+    };
+    if (new Date(data.period_start) > new Date(data.period_end)) throw new Error(`row ${rowNumber}: period_start is after period_end`);
+    return envelope('metric', data, {
+      method: 'owner_import',
+      source: source.file,
+      raw: JSON.stringify(row),
+      limitations: metric.limitations,
+    });
+  });
+  return observationRun(root, 'metrics import', source.file, observations, { rawInputs: { metric_import: source.raw } });
+}
+
+function readObjectiveInput(input) {
+  const document = inputDocument(input);
+  if (document.rows.length !== 1) throw new Error('objectives init requires exactly one objective');
+  return document.rows[0];
+}
+
+export function initializeObjective(root, { input, write = false }) {
+  const objective = readObjectiveInput(input);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const candidate = { ...registries.objectives, entries: [...registries.objectives.entries, objective] };
+  const check = validateAgainst('objective.schema.json', candidate);
+  if (!check.valid) throw new Error(`objective violates contract: ${check.errors.join('; ')}`);
+  if (registries.objectives.entries.some((item) => item.objective_id === objective.objective_id)) throw new Error(`objective ${objective.objective_id} already exists`);
+  const metricIds = new Set(registries.metrics.entries.map((item) => item.metric_id));
+  const refs = [...objective.primary_metrics, ...objective.supporting_metrics, ...objective.guardrails.map((item) => item.metric_id)];
+  const unknown = [...new Set(refs.filter((ref) => !metricIds.has(ref)))];
+  if (unknown.length) throw new Error(`objective references unknown metrics: ${unknown.join(', ')}`);
+  if (write) saveRegistry(root, 'objectives', candidate);
+  return { objective, written: write, file: path.join(root, '.citable', 'objectives.yaml') };
+}
+
+export function validateObjectives(root) {
+  const { registries, problems } = loadRegistries(root);
+  const objectiveProblems = problems.filter((problem) => problem.startsWith('objectives/') || problem.startsWith('objectives.yaml'));
+  return { ok: objectiveProblems.length === 0, problems: objectiveProblems, count: registries.objectives.entries.length };
+}
+
+function metricObservations(root) {
+  const runs = path.join(root, '.citable', 'runs');
+  if (!fs.existsSync(runs)) return [];
+  const items = [];
+  for (const run of fs.readdirSync(runs)) {
+    const dir = path.join(runs, run, 'observations');
+    if (!fs.existsSync(dir)) continue;
+    for (const file of fs.readdirSync(dir).filter((name) => name.endsWith('-metric.json'))) {
+      const item = readJson(path.join(dir, file));
+      if (item.kind === 'metric') items.push(item);
+    }
+  }
+  return [...new Map(items.map((item) => [item.evidence_hash, item])).values()];
+}
+
+function inCohort(data, cohort) {
+  const url = data.dimensions.url || data.dimensions.page || null;
+  const query = data.dimensions.query || null;
+  const labels = String(data.dimensions.labels || data.dimensions.label || '').split(',').map((label) => label.trim()).filter(Boolean);
+  const urlMatch = !cohort.urls.length || (url && cohort.urls.some((pattern) => pattern.endsWith('*') ? url.startsWith(pattern.slice(0, -1)) : url === pattern));
+  const queryMatch = !cohort.queries.length || (query && cohort.queries.includes(query));
+  const labelMatch = !cohort.labels.length || cohort.labels.some((label) => labels.includes(label));
+  return urlMatch && queryMatch && labelMatch;
+}
+
+function aggregate(values, method) {
+  if (!values.length) return null;
+  if (method === 'sum') return values.reduce((sum, value) => sum + value, 0);
+  if (method === 'minimum') return Math.min(...values);
+  if (method === 'maximum') return Math.max(...values);
+  if (method === 'latest') return values.at(-1);
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function evaluateGuardrail(guardrail, metric, definition) {
+  if (metric.state !== 'observed') return { ...guardrail, state: 'inconclusive', passed: null, reason: 'metric comparison is inconclusive' };
+  let passed;
+  if (guardrail.operator === 'gte') passed = metric.evaluation >= guardrail.threshold;
+  else if (guardrail.operator === 'lte') passed = metric.evaluation <= guardrail.threshold;
+  else if (guardrail.operator === 'increase_by') passed = metric.relative_change != null && metric.relative_change >= guardrail.threshold;
+  else if (guardrail.operator === 'decrease_by') passed = metric.relative_change != null && metric.relative_change <= -guardrail.threshold;
+  else if (definition.direction === 'increase') passed = metric.evaluation >= metric.baseline;
+  else if (definition.direction === 'decrease') passed = metric.evaluation <= metric.baseline;
+  else if (definition.direction === 'maintain') passed = metric.relative_change != null && Math.abs(metric.relative_change) <= guardrail.threshold;
+  else return { ...guardrail, state: 'inconclusive', passed: null, reason: 'contextual metric requires a user-defined directional guardrail' };
+  return { ...guardrail, state: 'observed', passed, reason: passed ? 'observed condition met' : 'observed condition not met' };
+}
+
+export function evaluateObjective(root, { objectiveId, refDate }) {
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+  const objective = objectiveId ? registries.objectives.entries.find((item) => item.objective_id === objectiveId) : registries.objectives.entries[0];
+  if (!objective) throw new Error(objectiveId ? `objective not found: ${objectiveId}` : 'no objective configured');
+  const definitions = new Map(registries.metrics.entries.map((item) => [item.metric_id, item]));
+  const end = parseRefDate(refDate);
+  end.setUTCHours(23, 59, 59, 999);
+  const evaluationStart = new Date(end); evaluationStart.setUTCDate(evaluationStart.getUTCDate() - objective.comparison.evaluation_days + 1); evaluationStart.setUTCHours(0, 0, 0, 0);
+  const baselineEnd = new Date(evaluationStart.getTime() - 1);
+  const baselineStart = new Date(baselineEnd); baselineStart.setUTCDate(baselineStart.getUTCDate() - objective.comparison.baseline_days + 1); baselineStart.setUTCHours(0, 0, 0, 0);
+  const all = metricObservations(root).filter((item) => inCohort(item.data, objective.cohort));
+  const metricIds = [...new Set([...objective.primary_metrics, ...objective.supporting_metrics, ...objective.guardrails.map((item) => item.metric_id)])];
+  const metrics = metricIds.map((metricId) => {
+    const definition = definitions.get(metricId);
+    const observations = all.filter((item) => item.data.metric_id === metricId).sort((a, b) => a.data.observed_at.localeCompare(b.data.observed_at));
+    const baselineRows = observations.filter((item) => new Date(item.data.observed_at) >= baselineStart && new Date(item.data.observed_at) <= baselineEnd);
+    const evaluationRows = observations.filter((item) => new Date(item.data.observed_at) >= evaluationStart && new Date(item.data.observed_at) <= end);
+    const aggregatable = definition.aggregation !== 'provider_defined';
+    const enough = aggregatable && baselineRows.length >= objective.comparison.minimum_observations && evaluationRows.length >= objective.comparison.minimum_observations;
+    const baseline = enough ? aggregate(baselineRows.map((item) => item.data.value), definition.aggregation) : null;
+    const evaluation = enough ? aggregate(evaluationRows.map((item) => item.data.value), definition.aggregation) : null;
+    return {
+      metric_id: metricId,
+      provider: definition.provider,
+      state: enough ? 'observed' : 'inconclusive',
+      baseline,
+      evaluation,
+      absolute_change: enough ? evaluation - baseline : null,
+      relative_change: enough && baseline !== 0 ? (evaluation - baseline) / Math.abs(baseline) : null,
+      baseline_observations: baselineRows.length,
+      evaluation_observations: evaluationRows.length,
+      limitations: [
+        ...definition.limitations,
+        ...(!aggregatable ? ['provider_defined aggregation requires an explicit normalized aggregation before evaluation'] : []),
+        ...(aggregatable && !enough ? [`requires at least ${objective.comparison.minimum_observations} observations in each window`] : []),
+      ],
+    };
+  });
+  const guardrails = objective.guardrails.map((guardrail) => {
+    const metric = metrics.find((item) => item.metric_id === guardrail.metric_id);
+    return evaluateGuardrail(guardrail, metric, definitions.get(guardrail.metric_id));
+  });
+  return {
+    objective_id: objective.objective_id,
+    objective_name: objective.name,
+    windows: { baseline_start: baselineStart.toISOString(), baseline_end: baselineEnd.toISOString(), evaluation_start: evaluationStart.toISOString(), evaluation_end: end.toISOString() },
+    metrics,
+    guardrails,
+    guardrail_status: guardrails.some((item) => item.state === 'inconclusive') ? 'inconclusive' : guardrails.some((item) => !item.passed) ? 'not_met' : 'met',
+    status: metrics.every((metric) => metric.state === 'observed') ? 'observed' : 'inconclusive',
+    interpretation: 'Changes are temporal associations. This evaluation does not establish that an intervention caused an observed outcome.',
+  };
+}

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');
+  }
+}

package/src/evidence/run.js

@@ -61,7 +61,7 @@ export function createRun(root, { command, argv = [], target, locale = process.e
     writeArtifact(relPath, data) {
       const file = path.join(dir, relPath);
       fs.mkdirSync(path.dirname(file), { recursive: true });
-      if (typeof data === 'string') fs.writeFileSync(file, data);
+      if (typeof data === 'string' || Buffer.isBuffer(data)) fs.writeFileSync(file, data);
       else writeJson(file, data);
       manifest.output_hashes[relPath] = sha256File(file);
       return file;

package/src/installer/index.js

@@ -105,6 +105,8 @@ export function parseInstallerArgs(argv) {
     help: false,
     version: false,
     failOnUpdate: false,
+    installMode: 'copy',
+    skillSelection: null,
     _: [],
   };
 
@@ -118,17 +120,29 @@ export function parseInstallerArgs(argv) {
     else if (arg === '--dry-run') args.dryRun = true;
     else if (arg === '--force') args.force = true;
     else if (arg === '--json') args.json = true;
-    else if (arg === '--all') args.all = true;
+    else if (arg === '--all') { args.all = true; args.yes = true; }
     else if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--version' || arg === '-v') args.version = true;
-    else if (arg === '--project' || arg === '--local') args.scope = mergeScope(args.scope, 'project');
-    else if (arg === '--global' || arg === '--user') args.scope = mergeScope(args.scope, 'global');
+    else if (arg === '--project' || arg === '--local' || arg === '-p') args.scope = mergeScope(args.scope, 'project');
+    else if (arg === '--global' || arg === '--user' || arg === '-g') args.scope = mergeScope(args.scope, 'global');
+    else if (arg === '--copy') args.installMode = 'copy';
+    else if (arg === '--symlink') throw new CitableInstallerError('--symlink is not supported: Citable uses hashed managed copies for atomic validation and safe uninstall', EXIT_CODES.invalidArguments);
     else if (arg === '--fail-on-update') args.failOnUpdate = true;
     else if (arg === '--providers') {
       if (i + 1 >= argv.length) throw new CitableInstallerError('--providers requires a value', EXIT_CODES.invalidArguments);
       args.providersRaw = argv[++i];
     } else if (arg.startsWith('--providers=')) {
       args.providersRaw = arg.slice('--providers='.length);
+    } else if (arg === '--agent' || arg === '-a') {
+      if (i + 1 >= argv.length) throw new CitableInstallerError(`${arg} requires a value`, EXIT_CODES.invalidArguments);
+      args.providersRaw = [args.providersRaw, argv[++i]].filter(Boolean).join(',');
+    } else if (arg.startsWith('--agent=')) {
+      args.providersRaw = [args.providersRaw, arg.slice('--agent='.length)].filter(Boolean).join(',');
+    } else if (arg === '--skill' || arg === '-s') {
+      if (i + 1 >= argv.length) throw new CitableInstallerError(`${arg} requires a value`, EXIT_CODES.invalidArguments);
+      args.skillSelection = argv[++i];
+    } else if (arg.startsWith('--skill=')) {
+      args.skillSelection = arg.slice('--skill='.length);
     } else if (arg === '--scope') {
       if (i + 1 >= argv.length) throw new CitableInstallerError('--scope requires a value', EXIT_CODES.invalidArguments);
       args.scope = mergeScope(args.scope, normalizeScopeValue(argv[++i]));
@@ -141,7 +155,16 @@ export function parseInstallerArgs(argv) {
     }
   }
 
-  if (args.providersRaw !== null) {
+  if (args.skillSelection !== null && !['citable', '*'].includes(String(args.skillSelection).trim().toLowerCase())) {
+    throw new CitableInstallerError(`this package contains only the citable skill; unsupported --skill value: ${args.skillSelection}`, EXIT_CODES.invalidArguments);
+  }
+
+  if (args.all) {
+    if (args.providersRaw !== null) throw new CitableInstallerError('--all cannot be combined with --providers or --agent', EXIT_CODES.invalidArguments);
+    args.providerSelection = { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
+  }
+
+  if (args.providersRaw !== null && !args.providerSelection) {
     const parsed = parseProviderList(args.providersRaw);
     if (parsed.unknown.length) {
       const supported = PROVIDER_IDS.join(', ');
@@ -1102,12 +1125,17 @@ Install examples
   npx @nebulacomponents/citable install
   npx @nebulacomponents/citable install --yes
   npx @nebulacomponents/citable install --providers=claude,codex,cursor --project --yes
+  npx @nebulacomponents/citable install --agent claude-code --agent codex --skill citable --copy -p -y
   npx @nebulacomponents/citable install --providers=all --global --dry-run
 
 Options
-  --providers=<list>        Provider ids, detected, or all
-  --project, --local        Install/check project-local skill locations
-  --global, --user          Install/check user-global skill locations
+  --providers=<list>        Provider ids, detected, all, or *
+  --agent=<id>, -a <id>     Repeatable provider alias compatible with skills CLI
+  --skill=<name>, -s <name> Select citable or * (this package contains one skill)
+  --all                     Select every provider and confirm non-interactively
+  --copy                    Use managed copies (default and only install mode)
+  --project, --local, -p    Install/check project-local skill locations
+  --global, --user, -g      Install/check user-global skill locations
   --scope=<project|global>  Scope equivalent
   --yes, -y                 Confirm non-interactively
   --dry-run                 Preview filesystem changes without mutation

package/src/installer/providers.js

@@ -130,7 +130,7 @@ export function parseProviderList(value) {
   if (!raw) return { kind: 'explicit', providers: [], unknown: [] };
   const lowered = raw.toLowerCase();
   if (lowered === 'detected') return { kind: 'detected', providers: [], unknown: [] };
-  if (lowered === 'all') return { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
+  if (lowered === 'all' || lowered === '*') return { kind: 'all', providers: PROVIDER_IDS, unknown: [] };
 
   const providers = [];
   const unknown = [];