@nebulacomponents/citable 1.13.1 → 1.15.0

package/src/observations/stance.js

@@ -0,0 +1,261 @@
+import { envelope, observationRun, readInput } from './common.js';
+import { loadRegistries } from '../registries/index.js';
+import { sha256 } from '../shared/io.js';
+
+const FAVORABLE_MARKERS = [
+  /\b(?:highly\s+)?recommended\b/i,
+  /\bindustry\s+standard\b/i,
+  /\bmarket\s+leader\b/i,
+  /\bbest(?:-in-class)?\b/i,
+  /\btop(?:\s+choice|\s+tier|\s+rated)?\b/i,
+  /\bpreferred\s+(?:solution|option|tool|platform)\b/i,
+  /\breliable\b/i,
+  /\brobust\b/i,
+  /\bsecure\b/i,
+  /\bperformant\b/i,
+  /\befficient\b/i,
+  /\bcomprehensive\b/i,
+  /\btrusted\b/i,
+  /\bintuitive\b/i,
+  /\bexcellent\b/i,
+];
+
+const UNFAVORABLE_MARKERS = [
+  /\bcriticized\s+for\b/i,
+  /\bexpensive\b/i,
+  /\boverpriced\b/i,
+  /\bunreliable\b/i,
+  /\boutdated\b/i,
+  /\blegacy\b/i,
+  /\bslow\b/i,
+  /\bbuggy\b/i,
+  /\bunstable\b/i,
+  /\bvulnerabilit(?:y|ies)\b/i,
+  /\bsecurity\s+flaw[s]?\b/i,
+  /\bsecurity\s+issue[s]?\b/i,
+  /\bbreach(?:es)?\b/i,
+  /\blacks?\s+(?:critical|essential|basic|key)\b/i,
+  /\bmissing\s+(?:critical|essential|key)\b/i,
+  /\bpoor\s+(?:performance|support|usability|documentation)\b/i,
+  /\bavoid\b/i,
+  /\bnot\s+recommended\b/i,
+  /\binferior\b/i,
+  /\bworst\b/i,
+  /\bsteep\s+learning\s+curve\b/i,
+  /\bfrustrating\b/i,
+  /\bfrequent\s+(?:downtime|crashes|errors|failures)\b/i,
+];
+
+function escapeRegex(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Extract sentences from text.
+ */
+function splitSentences(text) {
+  if (!text) return [];
+  return String(text)
+    .replace(/([.?!])\s+/g, '$1|§|')
+    .split('|§|')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Classify tone / stance towards a specific entity within an answer text.
+ * Stance categories: 'favorable', 'neutral', 'unfavorable', 'mixed', 'ambiguous'.
+ */
+export function classifyAnswerStance(answerText, entity, { reviewer = null, manualStance = null } = {}) {
+  const entityId = entity?.entity_id || 'unknown';
+  const canonicalName = entity?.canonical_name || entityId;
+  const names = [canonicalName, ...(entity?.aliases || [])].filter(Boolean);
+
+  if (!names.length || !answerText) {
+    return {
+      entity_id: entityId,
+      canonical_name: canonicalName,
+      mentioned: false,
+      stance: 'not_mentioned',
+      confidence: 'confirmed',
+      evidence_passages: [],
+      favorable_markers: [],
+      unfavorable_markers: [],
+      tone_summary: 'Entity not mentioned in text',
+      reviewer,
+      review_required: false,
+    };
+  }
+
+  // Check if any alias / canonical name is mentioned
+  const namePatterns = names.map((n) => new RegExp(`\\b${escapeRegex(n)}\\b`, 'i'));
+  const isMentioned = namePatterns.some((pattern) => pattern.test(answerText));
+
+  if (!isMentioned) {
+    return {
+      entity_id: entityId,
+      canonical_name: canonicalName,
+      mentioned: false,
+      stance: 'not_mentioned',
+      confidence: 'confirmed',
+      evidence_passages: [],
+      favorable_markers: [],
+      unfavorable_markers: [],
+      tone_summary: 'Entity not mentioned in text',
+      reviewer,
+      review_required: false,
+    };
+  }
+
+  // If a manual stance from a human reviewer is already recorded, honor it directly
+  if (manualStance && ['favorable', 'neutral', 'unfavorable', 'mixed', 'ambiguous'].includes(manualStance)) {
+    return {
+      entity_id: entityId,
+      canonical_name: canonicalName,
+      mentioned: true,
+      stance: manualStance,
+      confidence: reviewer ? 'confirmed' : 'high',
+      evidence_passages: [answerText.slice(0, 300)],
+      favorable_markers: [],
+      unfavorable_markers: [],
+      tone_summary: `Human-adjudicated stance: ${manualStance}`,
+      reviewer,
+      review_required: !reviewer,
+    };
+  }
+
+  // Find sentences mentioning the entity
+  const sentences = splitSentences(answerText);
+  const matchedIndices = new Set();
+  sentences.forEach((sentence, idx) => {
+    if (namePatterns.some((p) => p.test(sentence))) {
+      matchedIndices.add(idx);
+      // include adjacent sentence context if available
+      if (idx > 0) matchedIndices.add(idx - 1);
+      if (idx < sentences.length - 1) matchedIndices.add(idx + 1);
+    }
+  });
+
+  const contextSentences = [...matchedIndices].sort((a, b) => a - b).map((idx) => sentences[idx]);
+  const contextText = contextSentences.join(' ');
+
+  const favorableHits = [];
+  for (const rx of FAVORABLE_MARKERS) {
+    const m = contextText.match(rx);
+    if (m) favorableHits.push(m[0].toLowerCase());
+  }
+
+  const unfavorableHits = [];
+  for (const rx of UNFAVORABLE_MARKERS) {
+    const m = contextText.match(rx);
+    if (m) unfavorableHits.push(m[0].toLowerCase());
+  }
+
+  let stance = 'neutral';
+  if (unfavorableHits.length > 0 && favorableHits.length > 0) {
+    stance = 'mixed';
+  } else if (unfavorableHits.length > 0) {
+    stance = 'unfavorable';
+  } else if (favorableHits.length > 0) {
+    stance = 'favorable';
+  }
+
+  const toneSummary = stance === 'unfavorable'
+    ? `Unfavorable tone detected with markers: ${unfavorableHits.join(', ')}`
+    : stance === 'favorable'
+      ? `Favorable tone detected with markers: ${favorableHits.join(', ')}`
+      : stance === 'mixed'
+        ? `Mixed tone detected (favorable: ${favorableHits.join(', ')}; unfavorable: ${unfavorableHits.join(', ')})`
+        : 'Neutral / descriptive tone without evaluative polarity';
+
+  return {
+    entity_id: entityId,
+    canonical_name: canonicalName,
+    mentioned: true,
+    stance,
+    confidence: reviewer ? 'confirmed' : 'medium',
+    evidence_passages: contextSentences.slice(0, 3),
+    favorable_markers: [...new Set(favorableHits)],
+    unfavorable_markers: [...new Set(unfavorableHits)],
+    tone_summary: toneSummary,
+    reviewer,
+    review_required: !reviewer,
+  };
+}
+
+/**
+ * Execute `citable observe stance`.
+ */
+export async function observeStance(root, options = {}) {
+  const input = readInput(options.input);
+  const { registries, problems } = loadRegistries(root);
+  if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
+
+  const entities = (registries.entities?.entries || []).filter((e) => e.status !== 'retired');
+  if (!entities.length) throw new Error('no active entities found in entity registry');
+
+  const targetEntities = options.entity
+    ? entities.filter((e) => e.entity_id === options.entity || e.canonical_name.toLowerCase() === options.entity.toLowerCase())
+    : entities;
+
+  if (options.entity && !targetEntities.length) {
+    throw new Error(`entity not found: ${options.entity}`);
+  }
+
+  // Parse candidate items from input
+  const doc = input.value;
+  const items = Array.isArray(doc)
+    ? doc
+    : doc.observations || doc.items || doc.answers || doc.prompts || [doc];
+
+  const observations = [];
+  for (const item of items) {
+    const answerText = item.answer_text || item.answer || item.text || item.data?.answer_text || '';
+    if (!answerText) continue;
+
+    const promptId = item.prompt_id || item.data?.prompt_id || 'unknown';
+    const promptText = item.prompt_text || item.data?.prompt_text || null;
+    const engine = item.provider || item.engine || item.data?.provider || item.data?.engine || 'unknown';
+    const reviewer = options.reviewer || item.reviewer || item.evaluator || null;
+
+    for (const entity of targetEntities) {
+      const classification = classifyAnswerStance(answerText, entity, {
+        reviewer,
+        manualStance: item.stance || item.sentiment,
+      });
+
+      if (!classification.mentioned) continue;
+
+      const data = {
+        prompt_id: promptId,
+        prompt_text: promptText,
+        engine,
+        entity_id: entity.entity_id,
+        canonical_name: entity.canonical_name,
+        stance: classification.stance,
+        evidence_passages: classification.evidence_passages,
+        favorable_markers: classification.favorable_markers,
+        unfavorable_markers: classification.unfavorable_markers,
+        tone_summary: classification.tone_summary,
+        reviewer: classification.reviewer,
+        review_required: classification.review_required,
+      };
+
+      const raw = JSON.stringify({ item, classification });
+      observations.push(envelope('stance', data, {
+        method: reviewer ? 'human_review' : 'static_analysis',
+        source: input.file,
+        state: classification.review_required ? 'review_required' : 'observed',
+        confidence: classification.confidence,
+        raw,
+        limitations: classification.review_required
+          ? ['Automated stance classification is an evidence-backed semantic finding; authoritative determination requires a named human reviewer per the narrative-accuracy rubric.']
+          : [],
+      }));
+    }
+  }
+
+  return observationRun(root, 'observe stance', input.file, observations, {
+    rawInputs: { stance_input: input.raw },
+  });
+}

package/src/registries/seed.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readYaml, nowIso, sha256 } from '../shared/io.js';
+import { loadRegistries, saveRegistry, REGISTRY_SPECS } from './index.js';
+
+const SEEDS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'seeds');
+
+export function listSeeds(seedsDir = SEEDS_DIR) {
+  if (!fs.existsSync(seedsDir)) return [];
+  return fs.readdirSync(seedsDir).filter((name) => fs.existsSync(path.join(seedsDir, name, 'seed.json')));
+}
+
+function loadSeedManifest(name, seedsDir) {
+  const dir = path.join(seedsDir, name);
+  const manifestFile = path.join(dir, 'seed.json');
+  if (!fs.existsSync(manifestFile)) {
+    throw new Error(`unknown seed: ${name}; available seeds: ${listSeeds(seedsDir).join(', ') || 'none bundled'}`);
+  }
+  return { dir, manifest: JSON.parse(fs.readFileSync(manifestFile, 'utf8')) };
+}
+
+/** Deterministic, key-order-independent serialization for content fingerprinting. */
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** Fingerprint an entry's content, excluding provenance (which carries the fingerprint itself). */
+function contentFingerprint(entry) {
+  const { provenance, ...rest } = entry;
+  return sha256(stableStringify(rest));
+}
+
+/**
+ * Overlay a bundled starter registry seed onto the caller's `.citable/` registries.
+ *
+ * Fail-closed guarantees, enforced in code (never trusted from the seed file itself):
+ *   - every written entry is stamped `status: unverified` unconditionally, regardless of
+ *     what status the seed bundle declares (candidate, active, verified — all forced);
+ *   - an existing entry is only ever refreshed (even with `force`) if its current content
+ *     still matches the fingerprint recorded at seed time — `provenance.seededFrom` being
+ *     present is not by itself proof the entry is unedited, since a user can edit a field
+ *     while leaving provenance untouched; a fingerprint mismatch means the owner changed
+ *     it, and a seed can never clobber that edit.
+ */
+export function applySeed(root, name, { force = false, seedsDir = SEEDS_DIR } = {}) {
+  const { dir, manifest } = loadSeedManifest(name, seedsDir);
+  const { registries } = loadRegistries(root);
+  const appliedAt = nowIso();
+  const result = { seedName: name, seedVersion: manifest.version, appliedAt, registriesTouched: {}, warnings: [] };
+
+  for (const kind of manifest.registries) {
+    const spec = REGISTRY_SPECS.find((s) => s.kind === kind);
+    if (!spec) { result.warnings.push(`seed "${name}" references unknown registry kind "${kind}"; skipped`); continue; }
+    const seedFile = path.join(dir, spec.file);
+    if (!fs.existsSync(seedFile)) continue;
+    const seedRegistry = readYaml(seedFile);
+    const existing = registries[kind];
+    const existingById = new Map(existing.entries.map((e) => [e[spec.idField], e]));
+    let added = 0;
+    let skipped = 0;
+
+    for (const entry of seedRegistry.entries) {
+      const id = entry[spec.idField];
+      const already = existingById.get(id);
+      if (already) {
+        const seededFrom = already.provenance?.seededFrom;
+        const unedited = seededFrom && seededFrom.contentFingerprint === contentFingerprint(already);
+        if (!force || !unedited) { skipped++; continue; }
+      }
+
+      if (entry.status !== 'unverified') {
+        result.warnings.push(`${kind}/${id}: seed attempted status "${entry.status}"; forced to "unverified"`);
+        entry.status = 'unverified';
+      }
+      entry.provenance = {
+        ...(entry.provenance || {}),
+        seededFrom: { seedName: name, seedVersion: manifest.version, importedAt: appliedAt, contentFingerprint: contentFingerprint(entry) },
+      };
+
+      if (already) Object.assign(already, entry);
+      else existing.entries.push(entry);
+      added++;
+    }
+
+    saveRegistry(root, kind, existing);
+    result.registriesTouched[kind] = { added, skipped };
+  }
+
+  return result;
+}

package/src/registries/seeds/saas-pricing/claims.yaml

@@ -0,0 +1,18 @@
+version: 1
+kind: claims
+entries:
+  - claim_id: CLAIM-SEED-PRICING-TRANSPARENCY
+    claim: >
+      Placeholder: replace with a specific, evidenced pricing claim for your
+      product (e.g. published starting price, billing unit, plan boundaries).
+    claim_type: commercial
+    entity: ENT-SEED-PRODUCT
+    publication_surfaces: ["/pricing/"]
+    status: unverified
+  - claim_id: CLAIM-SEED-FEATURE-SCOPE
+    claim: >
+      Placeholder: replace with a specific, evidenced capability claim and its
+      scope/exclusions (what the product does and explicitly does not do).
+    claim_type: capability
+    entity: ENT-SEED-PRODUCT
+    status: unverified

package/src/registries/seeds/saas-pricing/entities.yaml

@@ -0,0 +1,20 @@
+version: 1
+kind: entities
+entries:
+  - entity_id: ENT-SEED-VENDOR
+    canonical_name: (your company name)
+    entity_type: organization
+    category: SaaS vendor
+    definition: >
+      Replace with your organization's own definition. Seeded as a starting
+      shape only — not a fact about your company.
+    status: unverified
+  - entity_id: ENT-SEED-PRODUCT
+    canonical_name: (your product name)
+    entity_type: product
+    owner_entity: ENT-SEED-VENDOR
+    category: SaaS product
+    definition: >
+      Replace with your product's own definition. Seeded as a starting shape
+      only — not a fact about your product.
+    status: unverified

package/src/registries/seeds/saas-pricing/seed.json

@@ -0,0 +1,6 @@
+{
+  "name": "saas-pricing",
+  "version": "1.0.0",
+  "description": "Starter claims/entities for a SaaS pricing page vertical.",
+  "registries": ["entities", "claims"]
+}

package/src/reporting/dashboard.js

@@ -0,0 +1,254 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from '../shared/io.js';
+
+const POSTURE_CLASS = {
+  pass: 'posture-pass',
+  partial: 'posture-partial',
+  fail: 'posture-fail',
+  not_established: 'posture-unknown',
+  observed: 'posture-pass',
+  not_evidenced: 'posture-unknown',
+};
+
+const NO_GUARANTEE = 'This dashboard renders values already recorded by each audit run. It derives no new findings, combines nothing into an AI visibility score, and guarantees no crawling, indexing, ranking, citation, recommendation, or conversion outcome.';
+
+function isAuditSummary(summary) {
+  return Boolean(summary) && typeof summary === 'object' && Boolean(summary.by_severity) && Boolean(summary.posture);
+}
+
+/**
+ * Load every audit run that recorded a summary.json, oldest first. Run IDs are
+ * `<ISO-timestamp>-<command>-<rand>`, so a lexicographic sort is chronological.
+ * A run whose evidence cannot be read is reported in `skipped`, never dropped
+ * silently and never thrown.
+ */
+export function loadRunHistory(root, { since, last } = {}) {
+  const runsDir = path.join(root, '.citable', 'runs');
+  const included = [];
+  const skipped = [];
+  if (!fs.existsSync(runsDir)) return { included, skipped };
+  let runIds = fs.readdirSync(runsDir)
+    .filter((runId) => fs.existsSync(path.join(runsDir, runId, 'summary.json')))
+    .sort();
+  if (since) runIds = runIds.filter((runId) => runId >= since);
+  for (const runId of runIds) {
+    const dir = path.join(runsDir, runId);
+    try {
+      const summary = readJson(path.join(dir, 'summary.json'));
+      if (!isAuditSummary(summary)) {
+        skipped.push({ run_id: runId, reason: 'summary.json records no by_severity or posture; observation runs are not part of the audit trend' });
+        continue;
+      }
+      included.push({ run_id: runId, manifest: readJson(path.join(dir, 'manifest.json')), summary });
+    } catch (err) {
+      skipped.push({ run_id: runId, reason: err.message });
+    }
+  }
+  // `last` counts audit runs that carry usable evidence, so an unreadable or
+  // observation-only run cannot silently consume the requested window. Skipped
+  // runs are reported unless `last` moved the window past them; `since` has
+  // already bounded them above.
+  const windowed = Number.isInteger(last) && last > 0 ? included.slice(-last) : included;
+  const truncated = windowed.length < included.length && windowed.length > 0;
+  return {
+    included: windowed,
+    skipped: truncated ? skipped.filter((item) => item.run_id >= windowed[0].run_id) : skipped,
+  };
+}
+
+/** Project the loaded runs into parallel, run-aligned series. */
+export function buildTimeSeries(included) {
+  return {
+    run_ids: included.map((run) => run.run_id),
+    timestamps: included.map((run) => run.manifest?.timestamp ?? null),
+    by_severity_series: included.map((run) => run.summary.by_severity ?? {}),
+    retrieval_eligibility_series: included.map((run) => run.summary.posture?.retrieval_eligibility?.result ?? null),
+    source_extraction_series: included.map((run) => run.summary.posture?.source_extraction_and_support?.result ?? null),
+    citation_presence_rate_series: included.map((run) => run.summary.posture?.observed_citation_behavior?.citation_presence_rate ?? null),
+  };
+}
+
+function severityCount(bySeverity, severity) {
+  return bySeverity?.[severity] ?? 0;
+}
+
+function formatRate(rate) {
+  return rate == null ? 'not evidenced' : `${(rate * 100).toFixed(1)}%`;
+}
+
+function formatPosture(result) {
+  return result ?? 'not recorded';
+}
+
+function formatTimestamp(timestamp) {
+  return timestamp ?? 'not recorded';
+}
+
+export function renderDashboardMarkdown(series, skipped = []) {
+  const lines = [];
+  const runCount = series.run_ids.length;
+  lines.push(`# Citable evidence dashboard`);
+  lines.push('');
+  lines.push(`- Audit runs included: ${runCount}`);
+  lines.push(`- Runs skipped: ${skipped.length}`);
+  if (runCount) lines.push(`- Window: \`${series.run_ids[0]}\` → \`${series.run_ids[runCount - 1]}\``);
+  lines.push('');
+  lines.push(`> ${NO_GUARANTEE}`);
+  lines.push('');
+  if (runCount < 2) {
+    lines.push('## Insufficient history');
+    lines.push('');
+    lines.push(runCount === 0
+      ? 'No audit run in `.citable/runs/` recorded a summary. No trend is established. Run `citable audit` to record comparable evidence.'
+      : 'Only one audit run is available. A single point establishes no trend, no direction, and no rate of change. Record at least two comparable runs before reading movement into these values.');
+    lines.push('');
+  }
+  if (runCount) {
+    lines.push('## Run history');
+    lines.push('');
+    lines.push('| Run | Timestamp | Critical | High | Medium | Retrieval eligibility | Source extraction | Citation presence rate |');
+    lines.push('| --- | --- | --- | --- | --- | --- | --- | --- |');
+    for (let i = 0; i < runCount; i++) {
+      const sev = series.by_severity_series[i];
+      lines.push(`| \`${series.run_ids[i]}\` | ${formatTimestamp(series.timestamps[i])} | ${severityCount(sev, 'critical')} | ${severityCount(sev, 'high')} | ${severityCount(sev, 'medium')} | ${formatPosture(series.retrieval_eligibility_series[i])} | ${formatPosture(series.source_extraction_series[i])} | ${formatRate(series.citation_presence_rate_series[i])} |`);
+    }
+    lines.push('');
+    lines.push('Counts come from each run\'s own recorded summary. A lower count is an observed difference between runs, not proof that a condition was fixed — see `citable compare-snapshots` for run comparability.');
+    lines.push('');
+  }
+  if (skipped.length) {
+    lines.push('## Skipped runs');
+    lines.push('');
+    for (const item of skipped) lines.push(`- \`${item.run_id}\`: ${item.reason}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Map run-aligned values to `<polyline points>` coordinates. Non-numeric entries
+ * (a run with no evidenced value) are omitted rather than interpolated, and
+ * fewer than two numeric points yields no line at all.
+ */
+function sparklinePath(values, { width = 480, height = 80 } = {}) {
+  const pad = 3;
+  const points = values.map((value, index) => ({ value, index })).filter((point) => Number.isFinite(point.value));
+  if (points.length < 2) return '';
+  const min = Math.min(...points.map((point) => point.value));
+  const max = Math.max(...points.map((point) => point.value));
+  const span = max - min;
+  const steps = Math.max(values.length - 1, 1);
+  return points.map((point) => {
+    const x = pad + (point.index / steps) * (width - pad * 2);
+    const y = span === 0 ? height / 2 : (height - pad) - ((point.value - min) / span) * (height - pad * 2);
+    return `${x.toFixed(1)},${y.toFixed(1)}`;
+  }).join(' ');
+}
+
+function renderSparkline(title, values, format) {
+  const points = sparklinePath(values);
+  const numeric = values.filter((value) => Number.isFinite(value));
+  const html = [];
+  html.push('<section class="chart">');
+  html.push(`<h3>${escapeHtml(title)}</h3>`);
+  if (!points) {
+    html.push(`<p class="note">Fewer than two runs recorded a numeric value for this series (${numeric.length} of ${values.length}). No trend line is drawn.</p>`);
+  } else {
+    html.push(`<svg viewBox="0 0 480 80" width="480" height="80" role="img" aria-label="${escapeHtml(title)}">`);
+    html.push(`<polyline points="${points}" fill="none" stroke="#2f6f4f" stroke-width="2" />`);
+    html.push('</svg>');
+    html.push(`<p class="note">Range across ${numeric.length} run(s) with a recorded value: ${escapeHtml(format(Math.min(...numeric)))} to ${escapeHtml(format(Math.max(...numeric)))}. The vertical axis is scaled to this range only; runs without a recorded value are omitted, not interpolated.</p>`);
+  }
+  html.push('</section>');
+  return html.join('\n');
+}
+
+function renderPostureRow(label, results, runIds) {
+  const cells = results.map((result, index) => `<span class="posture ${POSTURE_CLASS[result] ?? 'posture-unknown'}" title="${escapeHtml(runIds[index])}">${escapeHtml(formatPosture(result))}</span>`).join('');
+  return `<section class="chart"><h3>${escapeHtml(label)}</h3><div class="posture-row">${cells}</div><p class="note">Categorical states in run order. These are not plotted as numbers because they have no defined numeric distance.</p></section>`;
+}
+
+export function renderDashboardHtml(series, skipped = []) {
+  const runCount = series.run_ids.length;
+  const criticalHigh = series.by_severity_series.map((sev) => severityCount(sev, 'critical') + severityCount(sev, 'high'));
+  const html = [];
+  html.push('<!doctype html>');
+  html.push('<html lang="en">');
+  html.push('<head>');
+  html.push('<meta charset="utf-8" />');
+  html.push('<meta name="viewport" content="width=device-width, initial-scale=1" />');
+  html.push('<title>Citable evidence dashboard</title>');
+  html.push('<style>');
+  html.push('body { font: 16px/1.5 system-ui, sans-serif; margin: 2rem auto; max-width: 60rem; padding: 0 1rem; color: #1c1c1c; }');
+  html.push('table { border-collapse: collapse; width: 100%; font-size: 0.875rem; }');
+  html.push('th, td { border: 1px solid #d4d4d4; padding: 0.375rem 0.5rem; text-align: left; }');
+  html.push('th { background: #f3f3f3; }');
+  html.push('code { font-size: 0.8125rem; }');
+  html.push('blockquote { border-left: 4px solid #999; margin: 0 0 1.5rem; padding: 0.25rem 1rem; color: #333; }');
+  html.push('.note { color: #555; font-size: 0.8125rem; }');
+  html.push('.chart { margin: 1.5rem 0; }');
+  html.push('.chart svg { background: #fafafa; border: 1px solid #e4e4e4; }');
+  html.push('.posture-row { display: flex; flex-wrap: wrap; gap: 0.25rem; }');
+  html.push('.posture { border-radius: 3px; font-size: 0.75rem; padding: 0.125rem 0.375rem; }');
+  html.push('.posture-pass { background: #e2f2e6; color: #1d5c33; }');
+  html.push('.posture-partial { background: #fbf1d8; color: #7a5510; }');
+  html.push('.posture-fail { background: #fbe0e0; color: #8c1f1f; }');
+  html.push('.posture-unknown { background: #ececec; color: #4a4a4a; }');
+  html.push('.insufficient { background: #fbf1d8; border: 1px solid #e2c98a; padding: 0.75rem 1rem; }');
+  html.push('</style>');
+  html.push('</head>');
+  html.push('<body>');
+  html.push('<h1>Citable evidence dashboard</h1>');
+  html.push('<ul>');
+  html.push(`<li>Audit runs included: ${runCount}</li>`);
+  html.push(`<li>Runs skipped: ${skipped.length}</li>`);
+  if (runCount) html.push(`<li>Window: <code>${escapeHtml(series.run_ids[0])}</code> to <code>${escapeHtml(series.run_ids[runCount - 1])}</code></li>`);
+  html.push('</ul>');
+  html.push(`<blockquote>${escapeHtml(NO_GUARANTEE)}</blockquote>`);
+  if (runCount < 2) {
+    html.push('<section class="insufficient">');
+    html.push('<h2>Insufficient history</h2>');
+    html.push(`<p>${runCount === 0
+      ? 'No audit run in <code>.citable/runs/</code> recorded a summary. No trend is established. Run <code>citable audit</code> to record comparable evidence.'
+      : 'Only one audit run is available. A single point establishes no trend, no direction, and no rate of change. Record at least two comparable runs before reading movement into these values.'}</p>`);
+    html.push('</section>');
+  }
+  if (runCount) {
+    html.push('<h2>Trends</h2>');
+    html.push(renderSparkline('Critical and high findings per run', criticalHigh, (value) => String(value)));
+    html.push(renderSparkline('Observed citation presence rate per run', series.citation_presence_rate_series, formatRate));
+    html.push(renderPostureRow('Retrieval eligibility per run', series.retrieval_eligibility_series, series.run_ids));
+    html.push(renderPostureRow('Source extraction and support per run', series.source_extraction_series, series.run_ids));
+    html.push('<h2>Run history</h2>');
+    html.push('<table>');
+    html.push('<thead><tr><th>Run</th><th>Timestamp</th><th>Critical</th><th>High</th><th>Medium</th><th>Retrieval eligibility</th><th>Source extraction</th><th>Citation presence rate</th></tr></thead>');
+    html.push('<tbody>');
+    for (let i = 0; i < runCount; i++) {
+      const sev = series.by_severity_series[i];
+      html.push(`<tr><td><code>${escapeHtml(series.run_ids[i])}</code></td><td>${escapeHtml(formatTimestamp(series.timestamps[i]))}</td><td>${severityCount(sev, 'critical')}</td><td>${severityCount(sev, 'high')}</td><td>${severityCount(sev, 'medium')}</td><td>${escapeHtml(formatPosture(series.retrieval_eligibility_series[i]))}</td><td>${escapeHtml(formatPosture(series.source_extraction_series[i]))}</td><td>${escapeHtml(formatRate(series.citation_presence_rate_series[i]))}</td></tr>`);
+    }
+    html.push('</tbody>');
+    html.push('</table>');
+    html.push('<p class="note">Counts come from each run&#39;s own recorded summary. A lower count is an observed difference between runs, not proof that a condition was fixed.</p>');
+  }
+  if (skipped.length) {
+    html.push('<h2>Skipped runs</h2>');
+    html.push('<ul>');
+    for (const item of skipped) html.push(`<li><code>${escapeHtml(item.run_id)}</code>: ${escapeHtml(item.reason)}</li>`);
+    html.push('</ul>');
+  }
+  html.push('</body>');
+  html.push('</html>');
+  html.push('');
+  return html.join('\n');
+}