@nebulacomponents/citable 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",

package/schemas/observation.schema.json

@@ -7,7 +7,7 @@
   "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", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift"] },
+    "kind": { "type": "string", "enum": ["render", "browser_journey", "index", "citation", "citation_review", "crawler_log", "crawler_probe", "regional_network", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric", "media_pdf", "media_transcript", "media_image", "representation_drift", "stance"] },
     "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"] },

package/schemas/schedule.schema.json

@@ -1,4 +1,4 @@
 {
   "$id":"citable://schemas/schedule.schema.json","$schema":"http://json-schema.org/draft-07/schema#","title":"Audit schedule registry","type":"object","additionalProperties":false,"required":["version","kind","updated","entries"],
-  "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"type":"string"}}}}}}
+  "properties":{"version":{"const":1},"kind":{"const":"schedules"},"updated":{"type":"string","format":"date-time"},"entries":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["schedule_id","name","status","cron","owner","expected_tool_version","audit","retention_days","limitations"],"properties":{"schedule_id":{"type":"string","pattern":"^SCHEDULE-[A-Z0-9][A-Z0-9_-]*$"},"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["active","paused","retired"]},"cron":{"type":"string","minLength":5},"owner":{"type":"string","minLength":1},"expected_tool_version":{"type":"string","pattern":"^\\d+\\.\\d+\\.\\d+$"},"audit":{"type":"object","additionalProperties":false,"required":["target","scope"],"properties":{"target":{"type":"string","minLength":1},"scope":{"type":["string","null"]},"base_url":{"type":["string","null"]}}},"monitor":{"type":"object","additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"webhook_url":{"type":"string"},"min_severity":{"type":"string","enum":["informational","medium","high","critical"]}}},"retention_days":{"type":"integer","minimum":1},"limitations":{"type":"array","minItems":1,"items":{"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.14.0
+version: 1.15.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -95,7 +95,8 @@ 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/probe/passage/consensus/performance evidence
+citable observe <mode> [options]      # render/index/citation/log/probe/passage/consensus/performance/stance evidence
+citable observe stance --input <citations|prompts.json> [--entity <id>]
 citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
 citable observe probes --target <url> [--region <label>]
 citable observe network --input <regional-network-import.json>
@@ -103,13 +104,17 @@ citable observe render --target <url> [--interactions] [--resume-run <run-id>]
 citable observe render --input <browser-evidence-plan.json>
 citable observe performance --target <url> --lighthouse [--repeat 1..5]
 citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
-citable monitor [runA runB]           # observation regression alerts
+citable monitor [runA runB] [--webhook <url>] [--min-severity <sev>]  # observation regression alerts
+citable report dashboard [--last N] [--since <run-id>]  # cross-run evidence trend (Markdown + HTML)
+citable report share-of-voice [--last N] [--since <run-id>]  # competitor citation share (Markdown + HTML)
 citable metrics import --provider <name> --input <csv|json>
 citable connect status
-citable connect configure --provider <gsc|ga4> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
-citable connect discover --provider <gsc|ga4>
+citable connect configure --provider <gsc|ga4|wordpress|webflow> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
+citable connect discover --provider <gsc|ga4|wordpress|webflow>
 citable connect validate --connection-id <id>
 citable connect sync --connection-id <id> --start-date YYYY-MM-DD --end-date YYYY-MM-DD
+citable connect read --connection-id <id> --target-id <id>
+citable connect apply --connection-id <id> --input <cms-spec.json> [--write]
 citable connect disconnect --connection-id <id> [--write]
 citable objectives init --input <json|yaml> [--write]
 citable objectives validate
@@ -121,7 +126,7 @@ citable reviews prioritize [--write]
 citable reviews plan --input <json|yaml> [--write]
 citable reviews sample <sampling-plan-id> [--write]
 citable reviews evaluate
-citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
+citable schedules run <schedule-id> [--ref-date YYYY-MM-DD] [--monitor] [--webhook <url>]
 citable project github <run-id>
 citable observe media --input <manifest.json> [--ocr]
 citable observe representation --input <release-manifest.json> --target <controlled-url>

package/skill/commands/README.md

@@ -21,9 +21,12 @@ 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 observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, corroboration, and stance evidence |
 | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
+| /citable connect status / configure / discover / validate / sync / read / apply / disconnect | implemented — GA4, GSC, WordPress, and Webflow adapters with hash-locked CMS remediation |
 | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
+| /citable report dashboard | implemented — folds each run's recorded summary into a cross-run Markdown/HTML trend; derives no new findings and no combined score |
+| /citable report share-of-voice | implemented — joins competitor registry against recorded citation observations to compute verified share-of-citation |
 | /citable metrics import | implemented — validates declared CSV/JSON metrics and writes immutable observations |
 | /citable objectives init / validate | implemented — user-owned metric selection, cohorts, windows, and guardrails |
 | /citable evaluate | implemented — independent baseline/evaluation comparisons with inconclusive handling |

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

@@ -91,9 +91,16 @@ 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
+## Monitoring and alert delivery
 
-`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.
+`monitor [runA runB] [--webhook <url>] [--min-severity <level>]` reports state
+changes, missing observations, index loss, canonical disagreement, and
+citation-presence changes. With `--webhook`, detected regressions matching or
+exceeding `--min-severity` (default `medium`) are dispatched as sealed JSON
+alert payloads and logged under `.citable/monitoring/deliveries/`. Destination
+URLs must be public network destinations (private/loopback addresses are blocked).
+Alerts are evidence changes, not causal explanations or ranking conclusions.
+
+Scheduled monitoring (`schedules run <id> --monitor [--webhook <url>]`) automatically
+compares the scheduled audit against the preceding baseline run and dispatches
+regression alerts when configured in `schedules.yaml`.

package/skill/commands/reporting.md

@@ -0,0 +1,57 @@
+---
+command: /citable report dashboard [--last N] [--since <run-id>]
+purpose: Fold the summary each audit run already recorded into a cross-run Markdown table and self-contained HTML page without deriving new findings, scores, or causal explanations.
+preconditions: [at least one finalized audit run under .citable/runs/ with a summary.json]
+failure_behaviour: fewer than two audit runs -> explicit insufficient-history state, not a trend; unreadable summary or manifest -> run reported under skipped runs; non-integer --last -> fail
+artifacts_created: [.citable/reports/dashboard.md, .citable/reports/dashboard.html]
+---
+
+# Cross-run evidence reporting
+
+1. Run `citable report dashboard` to read severity counts, retrieval
+   eligibility, source extraction and support, and observed citation presence
+   rate across run history. Every value is copied from a run's own
+   `summary.json`. The command runs no detector, opens no network connection,
+   and never edits an immutable run package.
+2. Treat the output as derived, not canonical. It is written to
+   `.citable/reports/`, alongside `monitor` and `action-plan` derived
+   artifacts. The evidence of record remains `.citable/runs/<run-id>/`.
+3. Window the history with `--since <run-id>` (keeps that run and everything
+   after it) and `--last N` (keeps the final N runs). Run IDs sort
+   chronologically, so both filters are deterministic.
+4. Read fewer than two runs as no trend. With zero or one run the dashboard
+   states insufficient history explicitly instead of drawing a line through a
+   single point. Direction, rate of change, and improvement are not established
+   by one observation.
+5. Read skipped runs as a gap in the series, not as absence of a problem. A run
+   whose `summary.json` or `manifest.json` cannot be parsed, and an observation
+   run whose summary records no severity or posture, is listed with its reason
+   rather than counted as zero findings.
+6. Read a falling count as an observed difference between runs, not as proof
+   that a condition was fixed. Use `citable compare-snapshots` to establish
+   whether two runs are comparable at all — detector set, configuration,
+   observation method, and tool version all change what a count means.
+
+# Refusal boundary
+
+Do not present the dashboard as an AI visibility score, a ranking forecast, or
+a measure of citation likelihood. The three posture dimensions are reported
+separately and are never combined into a single number. Do not interpolate,
+estimate, or carry forward a missing value: a run with no evidenced citation
+presence rate is omitted from that trend line, not filled in. Do not attribute
+any observed change to a specific intervention.
+
+# Share of voice and competitor reporting
+
+1. Run `citable report share-of-voice [--last N] [--since <run-id>]` to evaluate
+   first-party and competitor citation presence and share across recorded
+   `observe citation` runs.
+2. Contested competitor domains are loaded from `.citable/competitors.yaml`.
+   Citations whose canonical URL matches declared competitor domains are joined
+   into per-prompt and aggregate shares.
+3. Competitor share is calculated strictly from evidenced observations; missing
+   observations or unevaluated prompts are never filled with fabricated zeros or
+   interpolated estimates.
+4. Outputs are written to `.citable/reports/share-of-voice.md` and
+   `.citable/reports/share-of-voice.html`.
+

package/src/cli/index.js

@@ -16,9 +16,11 @@ import { projectGithub, runSchedule } from '../commands/delivery.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';
+import { monitor, monitorAndAlert } from '../commands/monitor.js';
+import { reportDashboard } from '../commands/reportDashboard.js';
+import { reportShareOfVoice } from '../commands/reportShareOfVoice.js';
 import { evaluateObjective, importMetrics, initializeObjective, validateObjectives } from '../commands/measurement.js';
-import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
+import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection, readCmsContent, applyCmsRemediation } from '../commands/connect.js';
 import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 import { evaluateReviews, initializeSamplingPlan, prioritizeReviews, queueReviews, selectSample } from '../commands/reviews.js';
 import { selfUpgradeCommand, selfUpgradeExitCode } from '../commands/selfUpgrade.js';
@@ -67,13 +69,17 @@ Commands
                             consensus, performance, corroboration, crawler or regional probes,
                             media evidence, or representation evidence
   apply                     Apply a reviewed, hash-locked remediation spec
-  monitor [runA runB]       Compare observation runs and emit regression alerts
+  monitor [runA runB]       Compare observation runs and emit regression alerts [--webhook <url>]
+  report dashboard [--last N] [--since <run-id>]   Render a cross-run evidence trend as Markdown + HTML
+  report share-of-voice [--last N]                 Compute first-party and competitor citation share
   metrics import            Import declared metric observations from CSV/JSON
   connect status            List optional connectors and configured connections
   connect configure         Configure non-secret connection state (--write to save)
   connect discover          Discover provider properties using environment auth
   connect validate          Verify configured property access
   connect sync              Collect declared metrics into immutable observations
+  connect read              Read CMS content and hash for remediation targeting
+  connect apply             Apply reviewed, hash-locked CMS remediation (--write to apply)
   connect disconnect        Remove optional connection state (--write to confirm)
   objectives init           Validate/add one objective from --input (--write to save)
   objectives validate       Validate objective contracts and metric references
@@ -85,7 +91,7 @@ Commands
   reviews plan              Validate/add a sampling plan from --input
   reviews sample [plan]     Select a reproducible census or seeded random sample
   reviews evaluate          Detect stale decisions and require disagreement adjudication
-  schedules run [id]        Execute an active version-pinned audit schedule
+  schedules run [id]        Execute an active version-pinned schedule [--monitor] [--webhook <url>]
   project github [run]      Render non-authoritative GitHub annotations from a run
   corpus evaluate           Evaluate a disclosed real-property acceptance corpus
   corpus publish            Validate and project an owner-authorized public corpus
@@ -156,6 +162,8 @@ function parseArgs(argv) {
     else if (a === '--input') args.input = argv[++i];
     else if (a === '--output') args.output = argv[++i];
     else if (a === '--run') args.runId = argv[++i];
+    else if (a === '--since') args.since = argv[++i];
+    else if (a === '--last') args.last = argv[++i];
     else if (a === '--provider') args.provider = argv[++i];
     else if (a === '--dataset') args.dataset = argv[++i];
     else if (a === '--connection-id') args.connectionId = argv[++i];
@@ -175,6 +183,12 @@ function parseArgs(argv) {
     else if (a === '--timeout') args.timeout = Number(argv[++i]);
     else if (a === '--force') args.force = true;
     else if (a === '--seed') args.seed = argv[++i];
+     else if (a === '--webhook') args.webhook = argv[++i];
+    else if (a === '--min-severity') args.minSeverity = argv[++i];
+    else if (a === '--monitor') args.monitor = true;
+    else if (a === '--target-id') args.targetId = argv[++i];
+    else if (a === '--reviewer') args.reviewer = argv[++i];
+    else if (a === '--entity') args.entity = argv[++i];
     else args._.push(a);
   }
   return args;
@@ -276,7 +290,9 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         const r = await observe(root, mode, args);
         const claimDiffLine = r.summary.citation_metrics?.claim_diff
           ? `\nClaim diff: ${Object.entries(r.summary.citation_metrics.claim_diff).map(([k, v]) => `${k}:${v}`).join(' ')}` : '';
-        out(args, `observe ${mode}: ${r.summary.total} observation(s) [${Object.entries(r.summary.by_state).map(([k, v]) => `${k}:${v}`).join(' ')}]${claimDiffLine}\nEvidence package: ${r.dir}\nStatus: ${r.manifest.status}`, r);
+        const stanceLine = r.summary.stance_metrics
+          ? `\nStance summary: favorable:${r.summary.stance_metrics.favorable} neutral:${r.summary.stance_metrics.neutral} unfavorable:${r.summary.stance_metrics.unfavorable} mixed:${r.summary.stance_metrics.mixed} review_required:${r.summary.stance_metrics.review_required}` : '';
+        out(args, `observe ${mode}: ${r.summary.total} observation(s) [${Object.entries(r.summary.by_state).map(([k, v]) => `${k}:${v}`).join(' ')}]${claimDiffLine}${stanceLine}\nEvidence package: ${r.dir}\nStatus: ${r.manifest.status}`, r);
         break;
       }
       case 'apply': {
@@ -285,11 +301,35 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         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);
+        const r = await monitorAndAlert(root, {
+          runA: args._[0],
+          runB: args._[1],
+          webhookUrl: args.webhook,
+          minSeverity: args.minSeverity,
+        });
+        let msg = `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')}`;
+        if (r.delivery) {
+          if (r.delivery.skipped) msg += `\nDelivery: skipped (${r.delivery.reason})`;
+          else if (r.delivery.success) msg += `\nDelivery: webhook dispatched to ${r.delivery.target_url} (HTTP ${r.delivery.status_code})`;
+          else msg += `\nDelivery: webhook FAILED (${r.delivery.error})`;
+        }
+        out(args, msg, r);
         if (r.summary.critical_or_high > 0) process.exitCode = 1;
         break;
       }
+      case 'report': {
+        const sub = args._[0];
+        if (sub === 'dashboard') {
+          const r = reportDashboard(root, { since: args.since, last: args.last ? Number(args.last) : undefined });
+          out(args, `report dashboard: ${r.included} audit run(s) included, ${r.skipped} skipped\nMarkdown: ${r.path_md}\nHTML: ${r.path_html}`, r);
+        } else if (sub === 'share-of-voice' || sub === 'citations' || sub === 'share') {
+          const r = reportShareOfVoice(root, { since: args.since, last: args.last ? Number(args.last) : undefined });
+          out(args, `report share-of-voice: ${r.included} citation run(s) included, ${r.competitors_evaluated} competitor(s) evaluated\nMarkdown: ${r.path_md}\nHTML: ${r.path_html}`, r);
+        } else {
+          throw new Error('usage: citable report <dashboard|share-of-voice> [--last <n>] [--since <run-id>]');
+        }
+        break;
+      }
       case 'metrics': {
         if (args._[0] !== 'import') throw new Error('usage: citable metrics import --provider <name> --input <csv|json>');
         const r = importMetrics(root, { input: args.input, provider: args.provider });
@@ -314,10 +354,16 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         } else if (mode === 'sync') {
           const r = await syncConnection(root, args);
           out(args, `connect sync ${r.connection_id}: ${r.summary.total} metric observation(s)\nEvidence package: ${r.dir}`, r);
+        } else if (mode === 'read') {
+          const r = await readCmsContent(root, args);
+          out(args, `connect read ${r.connection_id} [${r.target_id}]: title="${r.content.title}" hash=${r.content.content_hash.slice(0, 12)}…\nURL: ${r.content.url || 'n/a'}`, r);
+        } else if (mode === 'apply') {
+          const r = await applyCmsRemediation(root, args);
+          out(args, `connect apply ${r.connection_id} [${r.target_id}]: ${r.status} ${r.dry_run ? '(dry run; use --write to apply)' : 'applied'}\nBefore: ${r.before_hash?.slice(0, 12)}… After: ${r.after_hash?.slice(0, 12)}…\nReviewer: ${r.reviewer}`, r);
         } else if (mode === 'disconnect') {
           const r = disconnectConnection(root, args);
           out(args, `connect disconnect ${r.connection_id}: ${r.disconnected ? 'removed' : 'dry run; use --write to remove'}`, r);
-        } else throw new Error('usage: citable connect <status|configure|discover|validate|sync> [options]');
+        } else throw new Error('usage: citable connect <status|configure|discover|validate|sync|read|apply|disconnect> [options]');
         break;
       }
       case 'objectives': {
@@ -363,9 +409,30 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         break;
       }
       case 'schedules': {
-        if(args._[0]!=='run') throw new Error('usage: citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]');
-        const r=await runSchedule(root,{scheduleId:args._[1],refDate:args.refDate});
-        out(args,`schedule ${r.schedule_execution.schedule_id}: audit ${r.runId}\nEvidence package: ${r.dir}\nExecution record: ${r.execution_file}`,r);
+        if (args._[0] !== 'run') throw new Error('usage: citable schedules run <schedule-id> [--ref-date YYYY-MM-DD] [--webhook <url>] [--monitor]');
+        const r = await runSchedule(root, {
+          scheduleId: args._[1],
+          refDate: args.refDate,
+          webhook: args.webhook,
+          monitor: args.monitor,
+          minSeverity: args.minSeverity,
+        });
+        let msg = `schedule ${r.schedule_execution.schedule_id}: audit ${r.runId}\nEvidence package: ${r.dir}\nExecution record: ${r.execution_file}`;
+        if (r.schedule_execution.monitor) {
+          const m = r.schedule_execution.monitor;
+          if (m.status === 'insufficient_history') {
+            msg += `\nMonitor: insufficient history (${m.message})`;
+          } else {
+            msg += `\nMonitor: compared to ${m.baseline_run} (${m.regressions_count} regression(s), ${m.summary.regression_critical_or_high} critical/high)`;
+          }
+        }
+        if (r.schedule_execution.alert_delivery) {
+          const d = r.schedule_execution.alert_delivery;
+          if (d.skipped) msg += `\nAlert delivery: skipped (${d.reason})`;
+          else if (d.success) msg += `\nAlert delivery: dispatched to ${d.target_url} (HTTP ${d.status_code})`;
+          else msg += `\nAlert delivery: FAILED (${d.error})`;
+        }
+        out(args, msg, r);
         break;
       }
       case 'project': {

package/src/commands/connect.js

@@ -1,7 +1,9 @@
+import fs from 'node:fs';
 import { loadRegistries, saveRegistry } from '../registries/index.js';
 import { envelope, observationRun } from '../observations/common.js';
 import { getConnector, listConnectors } from '../connectors/index.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { readJson } from '../shared/io.js';
 
 function findConnection(root, connectionId) {
   const loaded = loadRegistries(root);
@@ -88,3 +90,30 @@ export async function syncConnection(root, { connectionId, startDate, endDate, a
   saveRegistry(root, 'connections', updated);
   return { ...run, connection_id: connectionId, provider: connector.provider };
 }
+
+export async function readCmsContent(root, { connectionId, targetId, accessToken, env, fetchImpl } = {}) {
+  if (!connectionId || !targetId) throw new Error('connect read requires --connection-id <id> and --target-id <id>');
+  const loaded = findConnection(root, connectionId);
+  const connector = getConnector(loaded.connection.provider);
+  if (!connector.readContent) {
+    throw new Error(`connector ${connector.provider} does not support CMS content reading`);
+  }
+  const context = contextFor(loaded.connection, connector, { accessToken, env, fetchImpl });
+  const content = await connector.readContent(loaded.connection, targetId, context);
+  return { connection_id: connectionId, provider: connector.provider, target_id: targetId, content };
+}
+
+export async function applyCmsRemediation(root, { connectionId, input, write = false, reviewer, accessToken, env, fetchImpl } = {}) {
+  if (!connectionId || !input) throw new Error('connect apply requires --connection-id <id> and --input <spec.json>');
+  const loaded = findConnection(root, connectionId);
+  const connector = getConnector(loaded.connection.provider);
+  if (!connector.applyRemediation) {
+    throw new Error(`connector ${connector.provider} does not support CMS remediation updates`);
+  }
+  const spec = typeof input === 'string' && fs.existsSync(input) ? readJson(input) : typeof input === 'object' ? input : JSON.parse(input);
+  const context = { ...contextFor(loaded.connection, connector, { accessToken, env, fetchImpl }), write: Boolean(write) };
+  if (reviewer && !spec.reviewer) spec.reviewer = reviewer;
+  const result = await connector.applyRemediation(loaded.connection, spec, context);
+  return { connection_id: connectionId, provider: connector.provider, ...result };
+}
+

package/src/commands/context.js

@@ -41,6 +41,20 @@ export async function buildContext(root, { target, baseUrl, refDate } = {}) {
     }
   }
 
+  // Observations recorded under .citable/runs/*/observations/
+  const observations = [];
+  if (fs.existsSync(runsDir)) {
+    for (const run of fs.readdirSync(runsDir)) {
+      const obsDir = path.join(runsDir, run, 'observations');
+      if (!fs.existsSync(obsDir)) continue;
+      for (const f of fs.readdirSync(obsDir)) {
+        if (f.endsWith('.json')) {
+          try { observations.push(readJson(path.join(obsDir, f))); } catch { warnings.push(`unreadable observation: ${run}/${f}`); }
+        }
+      }
+    }
+  }
+
   // Latest page snapshot (for regression/freshness comparison)
   let snapshots = null;
   const snapFile = path.join(root, '.citable', 'snapshots', 'pages-latest.json');
@@ -54,6 +68,7 @@ export async function buildContext(root, { target, baseUrl, refDate } = {}) {
     registries,
     site,
     promptResults: promptResults.length ? promptResults : null,
+    observations: observations.length ? observations : null,
     snapshots,
     refDate: parseRefDate(refDate),
     hashPage: (p) => sha256(p.text),

package/src/commands/delivery.js

@@ -2,12 +2,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { audit } from './audit.js';
+import { compareSnapshots } from './compareSnapshots.js';
+import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
 import { loadRegistries } from '../registries/index.js';
 import { readJson, sha256, writeJson, nowIso } from '../shared/io.js';
 
 const PKG = readJson(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../package.json'));
 
-export async function runSchedule(root, { scheduleId, refDate } = {}) {
+export async function runSchedule(root, {
+  scheduleId,
+  refDate,
+  webhook,
+  monitor: flagMonitor,
+  minSeverity,
+  fetchImpl,
+  lookup,
+  allowPrivateForTest = false,
+} = {}) {
   const { registries, problems } = loadRegistries(root);
   if (problems.length) throw new Error(`registry validation failed: ${problems.join('; ')}`);
   const schedule = registries.schedules.entries.find((item) => item.schedule_id === scheduleId);
@@ -15,7 +26,80 @@ export async function runSchedule(root, { scheduleId, refDate } = {}) {
   if (schedule.status !== 'active') throw new Error(`schedule ${scheduleId} is ${schedule.status}`);
   if (schedule.expected_tool_version !== PKG.version) throw new Error(`schedule ${scheduleId} expects Citable ${schedule.expected_tool_version}, current version is ${PKG.version}`);
   const result = await audit(root, { target: schedule.audit.target, scope: schedule.audit.scope, baseUrl: schedule.audit.base_url, refDate });
-  const execution = { schedule_id: scheduleId, cron: schedule.cron, owner: schedule.owner, executed_at: nowIso(), run_id: result.runId, manifest_hash: sha256(fs.readFileSync(path.join(result.dir, 'manifest.json'))), limitations: schedule.limitations };
+
+  const shouldMonitor = flagMonitor || Boolean(schedule.monitor?.enabled);
+  let monitorResult = null;
+  let alertDelivery = null;
+
+  if (shouldMonitor) {
+    const runsDir = path.join(root, '.citable', 'runs');
+    const runs = fs.existsSync(runsDir)
+      ? fs.readdirSync(runsDir).filter((r) => r !== result.runId && fs.existsSync(path.join(runsDir, r, 'findings.json'))).sort()
+      : [];
+    const prevRunId = runs.at(-1);
+
+    if (prevRunId) {
+      const comparison = compareSnapshots(root, { runA: prevRunId, runB: result.runId });
+      monitorResult = {
+        baseline_run: prevRunId,
+        comparable: comparison.comparability.comparable,
+        summary: comparison.summary,
+        regressions_count: comparison.regressions.length,
+      };
+
+      const targetWebhook = webhook || schedule.monitor?.webhook_url;
+      const targetMinSev = minSeverity || schedule.monitor?.min_severity || 'medium';
+
+      if (targetWebhook) {
+        const alerts = comparison.regressions.map((f) => ({
+          severity: f.classification?.severity || 'medium',
+          type: 'finding_regression',
+          detector_id: f.detector_id,
+          key: `${f.detector_id}|${f.subject?.identifier || f.subject?.source_file || 'unknown'}`,
+          message: f.observation?.summary || '',
+        }));
+
+        const qualifyingAlerts = filterAlerts(alerts, targetMinSev);
+        if (qualifyingAlerts.length > 0) {
+          const payload = buildAlertPayload({
+            runA: prevRunId,
+            runB: result.runId,
+            source: 'schedule',
+            summary: {
+              schedule_id: scheduleId,
+              ...comparison.summary,
+            },
+            alerts: qualifyingAlerts,
+          });
+          alertDelivery = await dispatchAlertWebhook(root, payload, {
+            webhookUrl: targetWebhook,
+            fetchImpl,
+            lookup,
+            allowPrivateForTest,
+          });
+        } else {
+          alertDelivery = { skipped: true, reason: `no regressions meet min_severity: ${targetMinSev}` };
+        }
+      }
+    } else {
+      monitorResult = {
+        status: 'insufficient_history',
+        message: 'No prior audit run available for regression comparison',
+      };
+    }
+  }
+
+  const execution = {
+    schedule_id: scheduleId,
+    cron: schedule.cron,
+    owner: schedule.owner,
+    executed_at: nowIso(),
+    run_id: result.runId,
+    manifest_hash: sha256(fs.readFileSync(path.join(result.dir, 'manifest.json'))),
+    limitations: schedule.limitations,
+    ...(monitorResult ? { monitor: monitorResult } : {}),
+    ...(alertDelivery ? { alert_delivery: alertDelivery } : {}),
+  };
   const executionFile = path.join(root, '.citable', 'schedule-executions', `${result.runId}.json`);
   writeJson(executionFile, execution);
   return { ...result, schedule_execution: execution, execution_file: executionFile };

package/src/commands/monitor.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, nowIso } from '../shared/io.js';
+import { buildAlertPayload, dispatchAlertWebhook, filterAlerts } from '../monitoring/alertDelivery.js';
 
 function observations(dir) {
   const folder = path.join(dir, 'observations');
@@ -47,3 +48,37 @@ export function monitor(root, { runA, runB } = {}) {
   writeJson(path.join(dir, 'latest.json'), result);
   return { ...result, dir };
 }
+
+export async function monitorAndAlert(root, {
+  runA,
+  runB,
+  webhookUrl,
+  minSeverity = 'medium',
+  fetchImpl,
+  lookup,
+  allowPrivateForTest = false,
+} = {}) {
+  const result = monitor(root, { runA, runB });
+  if (webhookUrl) {
+    const qualifying = filterAlerts(result.alerts, minSeverity);
+    if (qualifying.length > 0) {
+      const payload = buildAlertPayload({
+        runA: result.run_a,
+        runB: result.run_b,
+        source: 'monitor',
+        summary: result.summary,
+        alerts: qualifying,
+      });
+      const delivery = await dispatchAlertWebhook(root, payload, {
+        webhookUrl,
+        fetchImpl,
+        lookup,
+        allowPrivateForTest,
+      });
+      return { ...result, delivery };
+    }
+    return { ...result, delivery: { skipped: true, reason: `no alerts meet min_severity: ${minSeverity}` } };
+  }
+  return result;
+}
+

package/src/commands/observe.js

@@ -12,6 +12,7 @@ import { observeMedia } from '../observations/media.js';
 import { parse as parseHtml } from 'node-html-parser';
 import { verifyManifestIntegrity } from '../release/governance.js';
 import { observeBrowserPlan } from '../observations/browserJourney.js';
+import { observeStance } from '../observations/stance.js';
 
 const originOf = (value) => { try { return new URL(value).origin; } catch { return null; } };
 const words = (text) => String(text || '').trim().split(/\s+/).filter(Boolean);
@@ -761,6 +762,7 @@ export async function observe(root, mode, options = {}) {
     case 'network': return observeRegionalNetwork(root, options);
     case 'media': return observeMedia(root, options);
     case 'representation': return observeRepresentation(root, options);
-    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, or representation');
+    case 'stance': return observeStance(root, options);
+    default: throw new Error('observe mode must be render, index, citations, logs, bing, passages, consensus, performance, corroboration, probes, network, media, representation, or stance');
   }
 }

package/src/commands/reportDashboard.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildTimeSeries, loadRunHistory, renderDashboardHtml, renderDashboardMarkdown } from '../reporting/dashboard.js';
+
+/**
+ * `citable report dashboard` — fold the summary already recorded by each audit
+ * run into a cross-run Markdown table and a self-contained HTML page. Derived
+ * output only: it never reads, edits, or re-derives an immutable run package.
+ */
+export function reportDashboard(root, { since, last } = {}) {
+  if (last != null && (!Number.isInteger(last) || last < 1)) throw new Error('--last must be a positive integer');
+  const { included, skipped } = loadRunHistory(root, { since, last });
+  const series = buildTimeSeries(included);
+  const dir = path.join(root, '.citable', 'reports');
+  const pathMd = path.join(dir, 'dashboard.md');
+  const pathHtml = path.join(dir, 'dashboard.html');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(pathMd, renderDashboardMarkdown(series, skipped));
+  fs.writeFileSync(pathHtml, renderDashboardHtml(series, skipped));
+  return { dir, included: included.length, skipped: skipped.length, path_md: pathMd, path_html: pathHtml };
+}