@nebulacomponents/citable 1.13.1 → 1.15.0

package/src/commands/actionPlan.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { readJson, writeJson, sha256, nowIso } from '../shared/io.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { checklistItem, toStringArray } from '../shared/checklist.js';
 
 const SEVERITY = { critical: 0, high: 1, medium: 2, low: 3, informational: 3, experimental: 3 };
 const PHASE = { unblock: 0, governance: 1, content: 2, optimization: 3 };
@@ -57,8 +58,13 @@ function renderPlan(plan) {
       lines.push(`### ${action.priority.toUpperCase()} · ${action.action_id} · ${action.status}`);
       lines.push('', `- Subject: \`${action.subject}\``, `- Action: ${action.action}`);
       lines.push(`- Owner: ${action.owner ?? 'unassigned'}`);
+      lines.push(`- Decision owner: ${action.decision_owner ?? 'unassigned'}`);
+      lines.push(`- Dependencies: ${action.depends_on_action_ids.length ? action.depends_on_action_ids.join(', ') : 'none established'}`);
       if (action.required_input.length) lines.push(`- Required input: ${action.required_input.join(', ')}`);
       if (action.semantic_gates.length) lines.push(`- Semantic gates: ${action.semantic_gates.join(', ')}`);
+      lines.push(`- Failure condition: ${action.failure_condition}`);
+      lines.push(`- Leading indicators: ${action.leading_indicators.length ? action.leading_indicators.join(', ') : 'none established'}`);
+      lines.push(`- Monitoring window: ${action.monitoring_window ?? 'not established'}`);
       lines.push(`- Verify: \`${action.verification.command}\``, '');
     }
   }
@@ -83,15 +89,20 @@ export function actionPlan(root, { runId } = {}) {
     return {
       action_id: `ACT-${finding.finding_id.replace(/^F-/, '')}`,
       finding_ids: [finding.finding_id],
+      depends_on_action_ids: [],
       phase: phaseFor(finding),
       priority: ['informational', 'experimental'].includes(finding.classification.severity) ? 'low' : finding.classification.severity,
       subject: finding.subject.identifier,
       action: finding.remediation.preferred,
       owner,
+      decision_owner: owner,
       status: blocked ? 'blocked' : 'ready',
-      required_input: blocked ? ['accountable owner'] : [],
+      required_input: blocked ? toStringArray([checklistItem('owner', 'accountable owner')]) : [],
       semantic_gates: semanticGates(finding),
       unsafe_shortcuts: finding.remediation.unsafe_shortcuts || [],
+      failure_condition: `${finding.verification.detector_to_rerun} still reports the exact subject, or verification cannot complete with sufficient evidence`,
+      leading_indicators: [],
+      monitoring_window: null,
       verification: {
         method: finding.verification.method,
         detector: finding.verification.detector_to_rerun,

package/src/commands/audit.js

@@ -8,6 +8,8 @@ import { summarize, renderMarkdownReport } from '../reporting/report.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
 import { writeJson, sha256 } from '../shared/io.js';
 import { extractModified } from '../detectors/lifeMeas.js';
+import { buildEntityGraph } from '../observations/entityGraph.js';
+import { buildSourceIdentityChain } from '../observations/sourceIdentity.js';
 
 /** `citable audit [scope]` — run detectors and produce an evidence package. */
 export async function audit(root, { target, scope, baseUrl, refDate } = {}) {
@@ -93,6 +95,8 @@ export async function audit(root, { target, scope, baseUrl, refDate } = {}) {
     const schemaBlocks = [];
     for (const p of ctx.site.pages) for (const j of p.jsonLd) schemaBlocks.push({ url: p.url, parseError: j.parseError, blocks: j.blocks });
     run.writeArtifact('schema/jsonld.json', schemaBlocks);
+    run.writeArtifact('schema/entity-graph.json', buildEntityGraph(ctx.site.pages));
+    run.writeArtifact('identity/source-chain.json', buildSourceIdentityChain(ctx.registries));
     for (const p of ctx.site.pages) {
       run.writeArtifact(`headers/${encodeURIComponent(p.url)}.json`, { status: p.status, headers: p.headers });
     }

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/demo.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { audit } from './audit.js';
+
+const FIXTURE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'fixtures', 'demo');
+// Pinned so output never drifts as real-world "today" passes the fixture's validity windows.
+const DEMO_REF_DATE = '2026-07-18';
+
+/**
+ * `citable demo` — run the full detector engine against a bundled, frozen,
+ * offline example site. Never fetches the network. Never scores the caller's
+ * own project or a real named company — the fixture is synthetic
+ * (`https://example.test`, RFC 2606 reserved, non-resolvable).
+ */
+export async function demo() {
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'citable-demo-'));
+  try {
+    fs.cpSync(FIXTURE_ROOT, workDir, { recursive: true });
+    const r = await audit(workDir, {
+      target: path.join(workDir, 'site'),
+      baseUrl: 'https://example.test',
+      refDate: DEMO_REF_DATE,
+    });
+    return {
+      runId: r.runId,
+      summary: r.summary,
+      manifest: r.manifest,
+      report: r.report,
+      fixture: 'bundled synthetic example site — offline, not fetched, not a real company',
+    };
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}

package/src/commands/fixtures/demo/.citable/claims.yaml

@@ -0,0 +1,27 @@
+version: 1
+kind: claims
+entries:
+  - claim_id: CLAIM-ENFORCE
+    claim: >
+      Gatekeeper validates whether an AI-initiated action remains admissible
+      before execution in configured enforcement deployments.
+    claim_type: capability
+    entity: ENT-GATEKEEPER
+    scope:
+      - configured deployments using enforcement mode
+    exclusions:
+      - advisory-only deployments
+    evidence: [EVD-ARCH-SPEC]
+    legal_status: approved
+    publication_surfaces: ["/products/gatekeeper/"]
+    owner: Claim Owner
+    status: verified
+    valid_from: "2026-05-10"
+    expires: "2027-05-10"
+    last_verified: "2026-06-01"
+    support_assessment:
+      status: directly_supported
+      assessor: SME Reviewer
+      assessment_method: architecture specification review against claim wording
+      assessment_date: "2026-06-01"
+      confidence: high

package/src/commands/fixtures/demo/.citable/competitors.yaml

@@ -0,0 +1,3 @@
+version: 1
+kind: competitors
+entries: []

package/src/commands/fixtures/demo/.citable/config.yaml

@@ -0,0 +1,18 @@
+version: 1
+site:
+  base_url: null
+  built_output_dir: null
+  source_dirs: []
+  default_locale: en
+  default_jurisdiction: null
+framework:
+  name: null
+  rendering_model: null
+  package_manager: null
+  build_command: null
+  test_command: null
+audit:
+  index_target_default: true
+  max_crawl_depth: 4
+  thin_content_words: 120
+  fetch_external: false

package/src/commands/fixtures/demo/.citable/crawlers.yaml

@@ -0,0 +1,30 @@
+version: 1
+kind: crawlers
+entries:
+  - crawler_id: CRAWLER-GOOGLEBOT
+    user_agent: Googlebot
+    vendor: Google
+    purpose: search_indexing
+    decision: allow
+    decision_owner: SEO Owner
+    business_rationale: search visibility
+    next_review_date: "2027-01-01"
+    status: active
+  - crawler_id: CRAWLER-GPTBOT
+    user_agent: GPTBot
+    vendor: OpenAI
+    purpose: model_training
+    decision: block
+    decision_owner: Legal Owner
+    legal_rationale: no training license granted
+    next_review_date: "2027-01-01"
+    status: active
+  - crawler_id: CRAWLER-OAI-SEARCHBOT
+    user_agent: OAI-SearchBot
+    vendor: OpenAI
+    purpose: ai_search_discovery
+    decision: allow
+    decision_owner: SEO Owner
+    business_rationale: ChatGPT search inclusion
+    next_review_date: "2027-01-01"
+    status: active

package/src/commands/fixtures/demo/.citable/entities.yaml

@@ -0,0 +1,28 @@
+version: 1
+kind: entities
+entries:
+  - entity_id: ENT-ORG
+    canonical_name: Example Governance
+    entity_type: organization
+    canonical_url: https://example.test/
+    aliases: []
+    authoritative_profiles:
+      - https://www.linkedin.com/company/example-governance
+    category: AI execution governance
+    definition: >
+      Example Governance is an AI execution governance platform vendor.
+    status: verified
+    last_verified: "2026-06-01"
+    owner: Entity Owner
+  - entity_id: ENT-GATEKEEPER
+    canonical_name: Gatekeeper
+    entity_type: product
+    owner_entity: ENT-ORG
+    canonical_url: https://example.test/products/gatekeeper/
+    category: AI execution governance
+    definition: >
+      A runtime enforcement component that validates whether an AI-initiated
+      action remains admissible before execution.
+    status: verified
+    last_verified: "2026-06-01"
+    owner: Entity Owner

package/src/commands/fixtures/demo/.citable/evidence.yaml

@@ -0,0 +1,19 @@
+version: 1
+kind: evidence
+entries:
+  - evidence_id: EVD-ARCH-SPEC
+    title: Gatekeeper architecture specification v2
+    evidence_type: architecture_specification
+    source: internal://specs/gatekeeper-v2.md
+    primary_or_secondary: primary
+    supports_claims: [CLAIM-ENFORCE]
+    methodology: design review
+    measurement_period: "2026-05"
+    publication_date: "2026-05-10"
+    retrieved_date: "2026-06-01"
+    valid_until: "2027-05-10"
+    integrity_hash: sha256:f685b01d139f89eacd9b8957b55f4986ad8dff1ba6848a61419dd505075d9dc
+    access_status: internal
+    reuse_status: licensed
+    reviewer: SME Reviewer
+    verification_status: verified

package/src/commands/fixtures/demo/.citable/experiments.yaml

@@ -0,0 +1,3 @@
+version: 1
+kind: experiments
+entries: []

package/src/commands/fixtures/demo/.citable/pages.yaml

@@ -0,0 +1,54 @@
+version: 1
+kind: pages
+entries:
+  - page_id: PAGE-HOME
+    url: /
+    page_type: home
+    primary_intent: brand navigation
+    primary_entities: [ENT-ORG]
+    content_owner: Content Owner
+    lifecycle_class: evergreen
+    review_cadence: quarterly
+    next_review_date: "2026-10-01"
+    indexing_intent: index
+    conversion_action: request demo
+    status: active
+  - page_id: PAGE-GATEKEEPER
+    url: /products/gatekeeper/
+    page_type: product
+    primary_intent: vendor evaluation of runtime authorization
+    primary_entities: [ENT-GATEKEEPER]
+    published_claims: [CLAIM-ENFORCE]
+    content_owner: Content Owner
+    factual_reviewer: SME Reviewer
+    lifecycle_class: product_capability
+    review_cadence: release-driven
+    next_review_date: "2026-12-01"
+    indexing_intent: index
+    conversion_action: request demo
+    status: active
+  - page_id: PAGE-DEFN
+    url: /learn/execution-governance/
+    page_type: definition
+    primary_intent: define AI execution governance
+    primary_entities: [ENT-ORG]
+    content_owner: Content Owner
+    factual_reviewer: SME Reviewer
+    lifecycle_class: foundational
+    review_cadence: semiannual
+    next_review_date: "2026-12-15"
+    indexing_intent: index
+    conversion_action: read product page
+    status: active
+  - page_id: PAGE-PRICING
+    url: /pricing/
+    page_type: pricing
+    primary_intent: pricing evaluation
+    primary_entities: [ENT-GATEKEEPER]
+    content_owner: Content Owner
+    lifecycle_class: pricing
+    review_cadence: on-change
+    next_review_date: "2026-08-01"
+    indexing_intent: index
+    conversion_action: contact sales
+    status: active

package/src/commands/fixtures/demo/.citable/prompts.yaml

@@ -0,0 +1,11 @@
+version: 1
+kind: prompts
+entries:
+  - prompt_id: P-RECO
+    canonical_prompt: What platforms provide runtime authorization for AI agents?
+    prompt_class: category
+    desired_outcome: mention
+    target_entities: [ENT-GATEKEEPER]
+    accuracy_status: not_observed
+    owner: GEO Owner
+    status: active

package/src/commands/fixtures/demo/.citable/queries.yaml

@@ -0,0 +1,10 @@
+version: 1
+kind: queries
+entries:
+  - query_id: Q-DEFN
+    canonical_query: what is ai execution governance
+    intent: category_discovery
+    funnel_stage: awareness
+    target_page: /learn/execution-governance/
+    business_value: high
+    status: active

package/src/commands/fixtures/demo/site/index.html

@@ -0,0 +1,12 @@
+<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Example Governance — AI execution governance platform</title>
+<meta name="description" content="Example Governance provides runtime authorization controls for AI agents, with documented scope, evidence, and limitations.">
+<link rel="canonical" href="https://example.test/">
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"Organization","@id":"https://example.test/#organization","name":"Example Governance","url":"https://example.test/"}</script>
+</head><body>
+<h1>AI execution governance for autonomous agents</h1>
+<p>Example Governance is an AI execution governance platform that validates whether an AI-initiated action remains admissible before execution. It does not replace observability tooling; it operates in the execution path.</p>
+<p>The platform is designed for engineering and risk teams at organizations that deploy tool-using AI agents. It is not intended for teams that only need model evaluation dashboards.</p>
+<nav><a href="/products/gatekeeper/">Gatekeeper runtime authorization</a> <a href="/learn/execution-governance/">What is AI execution governance</a> <a href="/pricing/">Pricing and deployment options</a></nav>
+</body></html>

package/src/commands/fixtures/demo/site/learn/execution-governance/index.html

@@ -0,0 +1,14 @@
+<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>What is AI execution governance? Definition and scope</title>
+<meta name="description" content="A precise definition of AI execution governance, what it excludes, and how it differs from observability and approval workflows.">
+<link rel="canonical" href="https://example.test/learn/execution-governance/">
+</head><body>
+<h1>What is AI execution governance?</h1>
+<p>AI execution governance is the set of enforceable controls that determines whether a specific AI-initiated action is authorized at the moment of execution. It does not include model training governance or after-the-fact observability.</p>
+<h2>How it differs from observability</h2>
+<p>Execution governance differs from observability in one decisive dimension: observability records actions after they occur, whereas execution governance can prevent an inadmissible action. The comparison basis here is enforcement capability, not data collection depth.</p>
+<h2>Limitations of this definition</h2>
+<p>This definition does not apply to fully air-gapped batch systems where no runtime decision point exists. That constraint is a boundary condition, not an implementation detail.</p>
+<p>See <a href="/products/gatekeeper/">Gatekeeper runtime authorization</a> for an implementation, or return to the <a href="/">Example Governance home page</a>.</p>
+</body></html>

package/src/commands/fixtures/demo/site/pricing/index.html

@@ -0,0 +1,10 @@
+<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Pricing — Gatekeeper plans and deployment options</title>
+<meta name="description" content="Published pricing for Gatekeeper: per-seat SaaS plans and self-hosted licensing, with what each plan does not include.">
+<link rel="canonical" href="https://example.test/pricing/">
+</head><body>
+<h1>Gatekeeper pricing</h1>
+<p>Gatekeeper SaaS starts at 40 USD per seat per month. Self-hosted licensing is quoted per deployment. The starter plan does not include enterprise audit exports; that limitation applies until the Team plan.</p>
+<p><a href="/products/gatekeeper/">Gatekeeper product details</a> · <a href="/">Example Governance home</a></p>
+</body></html>

package/src/commands/fixtures/demo/site/products/gatekeeper/index.html

@@ -0,0 +1,15 @@
+<!doctype html><html lang="en"><head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Gatekeeper — runtime authorization for AI agents</title>
+<meta name="description" content="Gatekeeper validates AI agent actions against current policy before execution. SaaS or self-hosted, available globally.">
+<link rel="canonical" href="https://example.test/products/gatekeeper/">
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"SoftwareApplication","@id":"https://example.test/products/gatekeeper/#product","name":"Gatekeeper","url":"https://example.test/products/gatekeeper/","publisher":{"@id":"https://example.test/#organization"}}</script>
+</head><body>
+<h1>Gatekeeper</h1>
+<p>Gatekeeper is a runtime enforcement component that validates whether an AI-initiated action remains admissible before execution. It is designed for platform engineering teams operating autonomous agents in production. It is not for teams seeking a model training framework.</p>
+<h2>Deployment and pricing</h2>
+<p>Gatekeeper is available as SaaS or self-hosted. Pricing is published per seat per month; contact sales for enterprise quotes. Gatekeeper is available in North America and Europe.</p>
+<h2>Limitations</h2>
+<p>Gatekeeper does not support advisory-only deployments for enforcement guarantees, and it does not cover workflows that bypass its integration points. Known limitation: latency budgets under 5 ms are out of scope.</p>
+<p><a href="/learn/execution-governance/">Read the execution governance definition</a> or <a href="/pricing/">compare pricing and deployment options</a>. <a href="/">Example Governance home</a></p>
+</body></html>

package/src/commands/fixtures/demo/site/robots.txt

@@ -0,0 +1,7 @@
+User-agent: GPTBot
+Disallow: /
+
+User-agent: *
+Allow: /
+
+Sitemap: https://example.test/sitemap.xml

package/src/commands/fixtures/demo/site/sitemap.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<url><loc>https://example.test/</loc><lastmod>2026-07-01</lastmod></url>
+<url><loc>https://example.test/products/gatekeeper/</loc><lastmod>2026-07-01</lastmod></url>
+<url><loc>https://example.test/learn/execution-governance/</loc><lastmod>2026-07-01</lastmod></url>
+<url><loc>https://example.test/pricing/</loc><lastmod>2026-07-01</lastmod></url>
+</urlset>

package/src/commands/init.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { writeYaml, readJson, nowIso, listFiles } from '../shared/io.js';
 import { REGISTRY_SPECS, emptyRegistry, contextDir } from '../registries/index.js';
 import { validateAgainst } from '../shared/schemaValidator.js';
+import { applySeed } from '../registries/seed.js';
 
 const DEFAULT_CRAWLERS = [
   ['CRAWLER-GOOGLEBOT', 'Googlebot', 'Google', 'search_indexing'],
@@ -68,7 +69,7 @@ function detectFramework(root) {
 }
 
 /** `citable init` — inspect the repo and create .citable/ without overwriting anything user-maintained. */
-export function init(root, { force = false } = {}) {
+export function init(root, { force = false, seed = null } = {}) {
   const dir = contextDir(root);
   const created = [];
   const skipped = [];
@@ -120,5 +121,7 @@ export function init(root, { force = false } = {}) {
     writeYaml(file, reg);
     created.push(spec.file);
   }
-  return { created, skipped, detected, unresolved };
+
+  const seedResult = seed ? applySeed(root, seed, { force }) : null;
+  return { created, skipped, detected, unresolved, seed: seedResult };
 }

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