@nebulacomponents/citable 1.6.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebulacomponents/citable",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "Production-grade SEO, AEO, and GEO agent skill with auditable detection, claim governance, evidence validation, and multi-agent installation.",
   "keywords": [
     "seo",
@@ -71,7 +71,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.22.2"
+    "node": ">=24.0.0"
   },
   "license": "Apache-2.0",
   "repository": {

package/schemas/bing-webmaster.schema.json

@@ -0,0 +1,25 @@
+{
+  "$id": "citable://schemas/bing-webmaster.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Normalized Bing Webmaster observation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["dataset", "date", "url", "metrics", "dimensions", "interpretation_boundary"],
+  "properties": {
+    "dataset": { "type": "string", "enum": ["search_performance", "ai_performance"] },
+    "date": { "type": "string", "format": "date" },
+    "url": { "type": ["string", "null"], "format": "uri", "pattern": "^https?://" },
+    "metrics": { "type": "object", "additionalProperties": { "type": ["number", "null"] } },
+    "dimensions": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "query": { "type": ["string", "null"] },
+        "grounding_query": { "type": ["string", "null"] },
+        "source": { "type": ["string", "null"] },
+        "country": { "type": ["string", "null"] },
+        "device": { "type": ["string", "null"] }
+      }
+    },
+    "interpretation_boundary": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+  }
+}

package/schemas/crawler-identity.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "citable://schemas/crawler-identity.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Crawler identity evidence contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["provider", "declared_user_agent", "observed_source_ip", "range_source", "cidr_membership", "dns", "edge", "origin", "region", "collector", "stages", "verification_status"],
+  "properties": {
+    "provider": { "type": "string", "minLength": 1 },
+    "declared_user_agent": { "type": "string", "minLength": 1 },
+    "observed_source_ip": { "type": ["string", "null"] },
+    "range_source": {
+      "type": "object", "additionalProperties": false,
+      "required": ["url", "retrieved_at", "authority", "checksum", "checksum_scope", "checksum_valid"],
+      "properties": {
+        "url": { "type": ["string", "null"], "format": "uri" },
+        "retrieved_at": { "type": ["string", "null"], "format": "date-time" },
+        "authority": { "type": "string", "enum": ["provider_published", "owner_controlled", "third_party", "unknown"] },
+        "checksum": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
+        "checksum_scope": { "type": "string", "enum": ["source_snapshot", "not_captured"] },
+        "checksum_valid": { "type": "boolean" }
+      }
+    },
+    "cidr_membership": { "type": "string", "enum": ["matched", "not_matched", "not_tested", "invalid"] },
+    "dns": {
+      "type": "object", "additionalProperties": false, "required": ["status", "method"],
+      "properties": { "status": { "type": "string", "enum": ["verified", "failed", "not_tested"] }, "method": { "type": ["string", "null"] } }
+    },
+    "edge": {
+      "type": "object", "additionalProperties": false, "required": ["observed", "decision"],
+      "properties": { "observed": { "type": "boolean" }, "decision": { "type": ["string", "null"] } }
+    },
+    "origin": {
+      "type": "object", "additionalProperties": false, "required": ["observed", "status"],
+      "properties": { "observed": { "type": "boolean" }, "status": { "type": ["integer", "null"], "minimum": 100, "maximum": 599 } }
+    },
+    "region": { "type": ["string", "null"] },
+    "collector": { "type": "string", "minLength": 1 },
+    "stages": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] } },
+    "verification_status": { "type": "string", "enum": ["declared", "synthetically_observed", "range_matched", "dns_verified", "edge_observed", "origin_observed", "fully_verified", "contradictory", "insufficient_evidence"] }
+  }
+}

package/schemas/evidence-authority.schema.json

@@ -0,0 +1,15 @@
+{
+  "$id": "citable://schemas/evidence-authority.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Multidimensional evidence authority",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source_authority", "collection_authority", "authenticity_status", "representativeness"],
+  "properties": {
+    "source_authority": { "type": "string", "enum": ["provider_published", "standards_body", "owner_controlled", "independently_controlled", "third_party_commercial", "synthetic", "inferred", "unknown"] },
+    "collection_authority": { "type": "string", "enum": ["direct_api", "production_log", "browser_capture", "owner_export", "third_party_export", "manual_entry", "model_generated_inference", "static_analysis", "synthetic_probe"] },
+    "authenticity_status": { "type": "string", "enum": ["cryptographically_authenticated", "provider_range_verified", "owner_attested", "transport_authenticated", "checksum_protected_only", "unverified"] },
+    "representativeness": { "type": "string", "enum": ["production_population", "complete_export", "statistically_sampled", "controlled_experiment", "convenience_sample", "single_observation", "unknown"] },
+    "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+  }
+}

package/schemas/exception.schema.json

@@ -0,0 +1,70 @@
+{
+  "$id": "citable://schemas/exception.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Governed exception registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "exceptions" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["exception_id", "policy_id", "policy_hash", "status", "source_run_id", "finding_ids", "finding_hashes", "reason", "risk_statement", "residual_risk", "compensating_controls", "evidence_ids", "evidence_hashes", "owner_reviewer_id", "reviewer_assignments", "reviewer_independence", "created_at", "expires_at", "renewal_count", "renewal_limit", "invalidation_conditions", "audit_history"],
+        "properties": {
+          "exception_id": { "type": "string", "pattern": "^EXCEPTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "policy_id": { "type": "string", "pattern": "^POLICY-" },
+          "policy_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "status": { "type": "string", "enum": ["proposed", "approved", "revoked", "superseded"] },
+          "source_run_id": { "type": "string", "minLength": 1 },
+          "finding_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "finding_hashes": { "type": "object", "minProperties": 1, "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+          "reason": { "type": "string", "minLength": 1 },
+          "risk_statement": { "type": "string", "minLength": 1 },
+          "residual_risk": { "type": "string", "enum": ["documented", "not_documented"] },
+          "compensating_controls": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+          "evidence_ids": { "type": "array", "items": { "type": "string" } },
+          "evidence_hashes": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+          "owner_reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+          "reviewer_assignments": {
+            "type": "array", "minItems": 1,
+            "items": {
+              "type": "object", "additionalProperties": false, "required": ["reviewer_id", "role"],
+              "properties": {
+                "reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+                "role": { "type": "string", "enum": ["technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor", "remediation_implementer", "content_author"] }
+              }
+            }
+          },
+          "reviewer_independence": { "type": "string", "enum": ["established", "not_established", "conflicted"] },
+          "created_at": { "type": "string", "format": "date-time" },
+          "expires_at": { "type": "string", "format": "date-time" },
+          "renewal_count": { "type": "integer", "minimum": 0 },
+          "renewal_limit": { "type": "integer", "minimum": 0 },
+          "invalidation_conditions": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["finding_changed", "evidence_changed", "policy_changed", "resource_changed", "intervention_changed"] }
+          },
+          "related_intervention_id": { "type": ["string", "null"] },
+          "supersedes_exception_id": { "type": ["string", "null"] },
+          "superseded_by_exception_id": { "type": ["string", "null"] },
+          "audit_history": {
+            "type": "array", "minItems": 1,
+            "items": {
+              "type": "object", "additionalProperties": false, "required": ["timestamp", "actor_reviewer_id", "action", "note"],
+              "properties": {
+                "timestamp": { "type": "string", "format": "date-time" },
+                "actor_reviewer_id": { "type": "string", "pattern": "^REVIEWER-" },
+                "action": { "type": "string", "enum": ["proposed", "approved", "renewed", "revoked", "superseded"] },
+                "note": { "type": "string", "minLength": 1 }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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", "index", "citation", "citation_review", "crawler_log", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "bing_webmaster", "passage", "canonical_freshness", "performance", "corroboration", "metric"] },
     "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"] },
@@ -15,6 +15,7 @@
     "source": { "type": "string", "minLength": 1 },
     "evidence_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
     "data": { "type": "object" },
-    "limitations": { "type": "array", "items": { "type": "string" } }
+    "limitations": { "type": "array", "items": { "type": "string" } },
+    "authority": { "$ref": "citable://schemas/evidence-authority.schema.json" }
   }
 }

package/schemas/review-policy.schema.json

@@ -0,0 +1,35 @@
+{
+  "$id": "citable://schemas/review-policy.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Review policy registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "review_policies" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false,
+        "required": ["policy_id", "name", "status", "required_roles", "separation_rules", "max_exception_days", "max_renewals"],
+        "properties": {
+          "policy_id": { "type": "string", "pattern": "^POLICY-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["active", "deprecated"] },
+          "required_roles": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor"] }
+          },
+          "separation_rules": {
+            "type": "array", "uniqueItems": true,
+            "items": { "type": "string", "enum": ["author_cannot_verify_own_claim", "implementer_cannot_solely_verify", "commercial_owner_requires_independent_benefit_review", "risk_acceptor_must_be_authorized"] }
+          },
+          "max_exception_days": { "type": "integer", "minimum": 1, "maximum": 366 },
+          "max_renewals": { "type": "integer", "minimum": 0, "maximum": 20 }
+        }
+      }
+    }
+  }
+}

package/schemas/reviewer.schema.json

@@ -0,0 +1,32 @@
+{
+  "$id": "citable://schemas/reviewer.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Reviewer registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "reviewers" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["reviewer_id", "name", "status", "roles", "authorized_scopes", "conflicts"],
+        "properties": {
+          "reviewer_id": { "type": "string", "pattern": "^REVIEWER-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["active", "inactive"] },
+          "roles": {
+            "type": "array", "minItems": 1, "uniqueItems": true,
+            "items": { "type": "string", "enum": ["content_author", "evidence_owner", "technical_reviewer", "subject_matter_reviewer", "independent_reviewer", "approver", "risk_acceptor", "remediation_implementer"] }
+          },
+          "authorized_scopes": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+          "conflicts": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+        }
+      }
+    }
+  }
+}

package/skill/SKILL.md

@@ -7,12 +7,16 @@ 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.6.0
+version: 1.8.0
 ---
 
-# Citable — search & generative discoverability governance
+# Citable — evidence and change control for search and AI citation readiness
 
 Citable is an operational quality and governance layer, not a content generator.
+It records what a property makes technically available, what its content can
+support, and what external systems have actually been observed doing. It does
+not score visibility; it establishes what is eligible, supportable, observed,
+changed, and still unknown.
 It treats discoverability as an engineering system: registries as the source of
 truth, deterministic detectors for observable conditions, rubrics for semantic
 judgment, evidence packages for every run, and fail-closed behaviour wherever a
@@ -70,6 +74,11 @@ Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
 citation testing, distinguish mention, citation, material support, canonical
 source selection, and recommendation. These states are not interchangeable.
 
+Evidence preservation, authority, authenticity, collection method, and
+representativeness are also independent. Follow
+`references/evidence-authority.md`; a checksum or CIDR match alone never proves
+source authenticity, complete coverage, or verified crawler identity.
+
 ## Tooling
 
 The `citable` CLI in this repository performs the deterministic work. Always
@@ -86,6 +95,7 @@ citable validate [registries|claims|evidence|schema|links]
 citable compare-snapshots [runA runB]
 citable action-plan [run-id]          # ordered actions, blockers, semantic gates, verification
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
+citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
 citable apply --input <spec> [--write] # reviewed, hash-locked remediation; dry run by default
 citable monitor [runA runB]           # observation regression alerts
 citable metrics import --provider <name> --input <csv|json>
@@ -98,6 +108,8 @@ citable connect disconnect --connection-id <id> [--write]
 citable objectives init --input <json|yaml> [--write]
 citable objectives validate
 citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
+citable governance validate [--ref-date YYYY-MM-DD]
+citable governance evaluate <run-id> [--ref-date YYYY-MM-DD]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -155,8 +167,9 @@ mandatory.
 ## Registries are the source of truth
 
 `.citable/` holds YAML registries for queries, prompts, entities, claims,
-evidence, pages, crawlers, competitors, experiments, metrics, objectives,
-interventions, and optional connection state, all schema-validated
+  evidence, pages, crawlers, competitors, experiments, metrics, objectives,
+  interventions, optional connection state, reviewers, review policies, and
+  governed exceptions, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in
@@ -165,6 +178,9 @@ interventions, and optional connection state, all schema-validated
   competitors, pricing). Mark entities `incomplete` and list `required_input`.
 - Claim status transitions toward `verified` require existing verified evidence
   plus human semantic review; automation only downgrades (fail-closed).
+- Never encode an accepted exception as a passed or resolved finding. Validate
+  reviewer authority and separation of duties, bind approval to exact source
+  finding/policy/evidence hashes, and report enforcement disposition separately.
 
 ## Fail-closed behaviour
 

package/skill/commands/README.md

@@ -27,6 +27,7 @@ intent, not executability, so statuses are strict:
 | /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 |
+| /citable governance validate / evaluate | implemented — validates reviewer and exception authority and emits immutable dispositions without changing failed findings |
 | /citable ingest, map-site, map-queries, map-prompts, map-entities, map-evidence | specified (ingest.md) |
 | /citable optimize-page | specified (optimize-page.md) — requires source-to-render mapping, claim-preserving rewrites, build execution, rollback; none of that is proven yet |
 | /citable create-page, answer-block, architect, interlink, consolidate, metadata | specified (page-work.md) |

package/skill/commands/governance.md

@@ -0,0 +1,17 @@
+# Governance validation and exception evaluation
+
+Use `citable governance validate` before relying on any accepted exception. It
+validates reviewer roles and scopes, conflicts, policy requirements, separation
+of duties, source bindings, expiry, renewal, and referential integrity.
+
+Use `citable governance evaluate <run-id>` to create a new immutable evidence
+package. The command never edits the source run. Every source finding retains
+`technical_state: failed`; a valid exception is represented only as
+`enforcement_disposition: accepted_exception` with active validity and
+documented residual risk.
+
+Refuse authorization when policy, finding, or evidence hashes have changed;
+the exception is expired, revoked, superseded, conflicted, unauthorized, or
+over-renewed; required roles are absent; or more than one active exception
+matches a finding. Reviewer records are declarations and do not independently
+prove real-world identity, competence, independence, or legal authority.

package/skill/commands/measurement.md

@@ -70,6 +70,21 @@ agent × URL × status; flag 403/429/5xx concentrations against declared-allow
 crawlers; note that user-agent strings are spoofable and IP validation is the
 confirmation step (crawler registry ip_validation_method). Compare observed
 access against `crawlers.yaml` decisions (CRAWL-001 logic applied to logs).
+Normalize JSON or CSV edge/origin events into the crawler identity contract.
+Do not label CIDR membership alone verified: preserve range-source provenance,
+DNS, edge, origin, region, collector, stages, and contradiction state.
+Remove credentials, cookies, secrets, and unnecessary personal data before
+import. Citable rejects common sensitive field names but cannot establish that
+arbitrary URL or query values are lawful or appropriately minimized.
+
+# Bing owner observations
+
+Use `citable observe bing --dataset search_performance|ai_performance --input
+<csv|json>`. This release normalizes owner exports because no supported Bing AI
+Performance API contract has been captured. Citation counts do not indicate
+ranking, authority, placement, page importance, or material support. Grounding
+queries may be sampled. Preserve traffic-source dimensions and never infer
+causation from a temporal change.
 
 # monitor-contradictions
 Compare approved entity + claim records against: owned pages (automated, via

package/skill/references/capability-boundaries.md

@@ -13,12 +13,17 @@ Use the narrowest supported state. Never promote evidence across rows.
 | Cited | Import or disclosed adapter | Complete `observe citations` answer with citation URL and product/adapter mode |
 | Materially supports answer | Human review required | `citation_review` maps answer claim to source passage and names the reviewer |
 | Recommended | Operator supplied + review | Explicit recommendation, constraints, provider/mode/locale/time |
+| Accepted exception | Governed owner record | Active policy, authorized reviewers, separation-of-duty checks, exact finding/policy/evidence hashes, expiry, controls, and documented residual risk |
 
 URL audit mode alone does not prove crawler identity, WAF allowlisting,
 production-log access, index presence, selected canonical, rendered DOM parity,
 or provider citation behavior. Observation collectors can supply narrower
 evidence for these states; unavailable inputs remain `not_evidenced`.
 
+An accepted exception changes enforcement disposition only. It does not change
+the source finding, prove remediation, or establish that reviewer identity,
+competence, independence, or legal authority was externally authenticated.
+
 Primary-source lineage for these boundaries:
 
 - Perplexity documents separate `PerplexityBot` and `Perplexity-User` purposes,

package/skill/references/evidence-authority.md

@@ -0,0 +1,43 @@
+# Evidence authority and crawler identity
+
+An evidence checksum establishes preservation only. It does not establish that
+the source was authentic, the collection was complete, or the observation was
+representative. Report four axes independently on every new observation:
+
+1. `source_authority`: provider-published, standards-body, owner-controlled,
+   independently controlled, third-party commercial, synthetic, inferred, or
+   unknown.
+2. `collection_authority`: direct API, production log, browser capture, owner
+   export, third-party export, manual entry, model-generated inference, static
+   analysis, or synthetic probe.
+3. `authenticity_status`: cryptographically authenticated, provider-range
+   verified, owner-attested, transport-authenticated, checksum-protected only,
+   or unverified.
+4. `representativeness`: production population, complete export,
+   statistically sampled, controlled experiment, convenience sample, single
+   observation, or unknown.
+
+Never convert these axes into one authority score.
+
+## Crawler identity
+
+Contract support and verified observations are different outcomes. The
+`crawler-identity` schema can exist without any production event satisfying it.
+A user-agent match is `declared`. A synthetic request is
+`synthetically_observed`. An observed IP in an imported range is only
+`range_matched`.
+
+`fully_verified` requires all of:
+
+- a provider and declared user agent;
+- observed source IP matching the captured CIDR set;
+- provider-published range source URL, retrieval time, captured source snapshot,
+  and valid snapshot checksum;
+- documented forward/reverse DNS verification where applicable;
+- an explicit edge observation and decision;
+- a correlated origin observation and status;
+- region and collector identity.
+
+A failed range or DNS check, or a claimed verification without the required
+chain, is `contradictory`. Missing links are `insufficient_evidence`. Verification
+applies only to the captured event; it does not establish all crawler traffic.

package/src/cli/index.js

@@ -17,6 +17,7 @@ import { applyRemediation } from '../commands/applyRemediation.js';
 import { monitor } from '../commands/monitor.js';
 import { evaluateObjective, importMetrics, initializeObjective, validateObjectives } from '../commands/measurement.js';
 import { configureConnection, connectionStatus, discoverConnections, disconnectConnection, syncConnection, validateConnection } from '../commands/connect.js';
+import { evaluateDispositions, validateGovernance } from '../commands/governance.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -39,7 +40,7 @@ Commands
   validate [mode]           registries (default) | claims | evidence | schema | links
   compare-snapshots [a b]   Regression diff between two audit runs
   action-plan [run]         Turn audit findings into ordered remediation work
-  observe <mode>            Collect render, index, citation, log, passage,
+  observe <mode>            Collect render, index, citation, log, Bing, passage,
                             consensus, performance, or corroboration evidence
   apply                     Apply a reviewed, hash-locked remediation spec
   monitor [runA runB]       Compare observation runs and emit regression alerts
@@ -53,6 +54,8 @@ Commands
   objectives init           Validate/add one objective from --input (--write to save)
   objectives validate       Validate objective contracts and metric references
   evaluate [objective-id]   Compare objective baseline and evaluation windows
+  governance validate       Validate reviewer, policy, and exception controls
+  governance evaluate [run] Produce immutable enforcement dispositions without changing findings
   self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
@@ -61,6 +64,7 @@ Options
   --ref-date <YYYY-MM-DD>   Reference date for expiry/staleness checks (default: today)
   --input <file>            Import file or remediation specification
   --provider <name>         Provider label for imported observations
+  --dataset <name>          Provider export dataset (for example ai_performance)
   --connection-id <id>      Connection registry identifier
   --property-id <id>        Provider property or site identifier
   --credential-env <name>   Environment variable containing the access token
@@ -88,6 +92,7 @@ function parseArgs(argv) {
     else if (a === '--ref-date') args.refDate = argv[++i];
     else if (a === '--input') args.input = argv[++i];
     else if (a === '--provider') args.provider = argv[++i];
+    else if (a === '--dataset') args.dataset = argv[++i];
     else if (a === '--connection-id') args.connectionId = argv[++i];
     else if (a === '--property-id') args.propertyId = argv[++i];
     else if (a === '--credential-env') args.credentialEnv = argv[++i];
@@ -236,6 +241,20 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         out(args, `evaluate ${r.objective_id}: ${r.status}\n` + r.metrics.map((metric) => `  ${metric.metric_id}: ${metric.state}${metric.state === 'observed' ? ` (${metric.baseline} → ${metric.evaluation})` : ''}`).join('\n') + `\n${r.interpretation}`, r);
         break;
       }
+      case 'governance': {
+        const mode = args._[0];
+        if (mode === 'validate') {
+          const r = validateGovernance(root, { refDate: args.refDate });
+          out(args, `governance validate: ${r.ok ? 'OK' : 'PROBLEMS'} (${r.counts.reviewers} reviewer(s), ${r.counts.policies} policy/policies, ${r.counts.exceptions} exception(s))${r.problems.length ? `\n${r.problems.map((problem) => `  - ${problem}`).join('\n')}` : ''}`, r);
+          if (!r.ok) process.exitCode = 1;
+        } else if (mode === 'evaluate') {
+          const r = evaluateDispositions(root, { runId: args._[1], refDate: args.refDate });
+          const accepted = r.dispositions.filter((item) => item.enforcement_disposition === 'accepted_exception').length;
+          out(args, `governance evaluate ${r.source_run_id}: ${r.dispositions.length} failed finding(s), ${accepted} accepted exception(s)\nEvidence package: ${r.dir}`, r);
+          if (r.dispositions.some((item) => item.enforcement_disposition === 'blocked_ambiguous_exception')) process.exitCode = 1;
+        } else throw new Error('usage: citable governance <validate|evaluate [run-id]> [--ref-date YYYY-MM-DD]');
+        break;
+      }
       case 'self-upgrade': {
         const output = await selfUpgradeCommand(argv.slice(1));
         console.log(output);