@nebulacomponents/citable 1.4.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## Unreleased
+
+## 1.5.1 — 2026-07-18
+
+### Fixed
+
+- `Ship release` now explicitly dispatches trusted npm publishing at the newly
+  created tag because GitHub suppresses workflow events generated by its own
+  repository token.
+
+## 1.5.0 — 2026-07-18
+
+### Added
+
+- Installer aliases compatible with the common `skills` CLI interface:
+  repeatable `--agent`/`-a`, `--skill`/`-s`, `--copy`, `-p`, `-g`, and `*`
+  provider selection.
+- Explicit copy-only integrity policy and actionable rejection of unsupported
+  symlink installs.
+- Structured pull request controls with code ownership, a required PR contract,
+  Conventional Commits title validation, and release-note enforcement.
+- Review-gated release preparation and shipping workflows with semantic-version
+  consistency checks, changelog-derived GitHub releases, protected tagging, and
+  npm trusted publishing handoff.
+- Optional provider-neutral metric, objective, intervention, and connection-state
+  contracts with strict schema and referential validation.
+- CSV/JSON metric imports, user-owned objective creation and validation, and
+  evidence-deduplicated baseline/evaluation reporting with explicit guardrails
+  and inconclusive outcomes.
+
+### Fixed
+
+- `citable install --all` now selects every supported provider in addition to
+  confirming non-interactively.
+- Release preparation now updates and validates the canonical skill version in
+  addition to package, lockfile, changelog, and roadmap versions.
+
 ## 1.4.0 — 2026-07-18
 
 ### Added

package/README.md

@@ -52,6 +52,20 @@ Install into specific agents:
 npx @nebulacomponents/citable install --providers=claude,codex,cursor
 ```
 
+The installer also accepts the common `skills` CLI conventions. `--agent` is
+repeatable, `--skill` accepts `citable` or `*`, and `--copy` explicitly selects
+Citable's default managed-copy mode:
+
+```bash
+npx @nebulacomponents/citable install --agent claude-code --agent codex --skill citable --copy -p -y
+```
+
+Install into every supported provider layout without prompting:
+
+```bash
+npx @nebulacomponents/citable install --all --project
+```
+
 Install globally:
 
 ```bash
@@ -91,10 +105,13 @@ provider-specific home paths, including `~/.claude/skills/citable/`,
 Target resolution is deterministic: explicit `--providers` wins, then project
 harness directories, then user-home harness hints. `--providers=detected`
 selects every detected supported provider; `--providers=all` selects every
-supported provider layout for the requested scope. Unknown provider names fail
-non-zero. In non-interactive mode, use `--yes`; project scope is the default
-unless `--global`/`--user`/`--scope=global` is supplied. The installer never
-reports success when no install target was selected.
+supported provider layout for the requested scope. `--providers=*` and `--all`
+are equivalent provider selections; `--all` also confirms non-interactively.
+Repeatable `--agent`/`-a`, `--skill`/`-s`, `--copy`, `-p`, and `-g` follow the
+familiar `skills` CLI interface. Unknown provider or skill names fail non-zero.
+Project scope is the default unless `--global`/`--user`/`--scope=global` is
+supplied. The installer never reports success when no install target was
+selected.
 
 Managed installs carry `manifest.json` with `managedBy: "citable-cli"` and
 SHA-256 hashes for the installed payload. Repeated installs validate the tree
@@ -102,7 +119,9 @@ and report `already current`. `update` compares the complete managed tree, not
 only `SKILL.md` or the version string. `uninstall` removes managed files only
 and preserves unrelated files in the skill directory. Locally modified managed
 installs and unmanaged `citable/` collisions are refused unless `--force` is
-used.
+used. Symlink mode is intentionally unsupported: provider-specific payloads and
+their manifests must remain an atomic managed unit so validation and uninstall
+do not cross ownership boundaries.
 
 The initial installer installs the skill payload only. It does not install
 provider hooks, sidecar configuration, telemetry, or unrelated agent settings.
@@ -133,6 +152,10 @@ citable observe performance --target https://example.com # CRUX_API_KEY
 citable apply --input remediation-spec.json          # dry run
 citable apply --input remediation-spec.json --write  # reviewed + hash-locked
 citable monitor [runA runB]
+citable metrics import --provider gsc --input metrics.csv
+citable objectives init --input objective.json --write
+citable objectives validate
+citable evaluate OBJECTIVE-PRODUCT_DISCOVERY --ref-date 2026-07-18
 citable substantiate          # claim/evidence assessment (dry run)
 citable validate              # registry schema + referential integrity
 ```
@@ -143,7 +166,7 @@ citable validate              # registry schema + referential integrity
 | --- | --- |
 | `skill/` | Canonical agent skill: SKILL.md, command contracts, rubrics, anti-patterns, policies, templates |
 | `src/` | CLI, commands, registries, detectors, crawler/extractor, evidence, reporting |
-| `schemas/` | JSON Schemas: 9 registries plus findings, runs, observations, remediation, config, and prompt results |
+| `schemas/` | JSON Schemas: 13 registries plus findings, runs, observations, remediation, config, and prompt results |
 | `tests/` | Unit + integration suites; positive/negative fixtures |
 | `docs/` | ADR, traceability matrix, known limitations |
 | `dist/` | Generated distribution packages (run `npm run build:dist`) |
@@ -159,6 +182,8 @@ citable validate              # registry schema + referential integrity
   any coverage claim
 - [Capability gap analysis](docs/capability-gap-analysis.md) — implemented,
   partial, operator-supplied, and missing evidence boundaries
+- [Measurement objectives](docs/measurement-objectives.md) — optional metric
+  imports, user-owned objectives, comparison windows, and guardrails
 
 ## Requirements
 
@@ -168,6 +193,9 @@ an installed Chromium browser. Google index inspection uses `GSC_ACCESS_TOKEN`
 and `--site-url`; CrUX uses `CRUX_API_KEY`. Missing dependencies or credentials
 produce incomplete evidence. Supported frameworks for auto-detection: Next.js,
 Astro, Nuxt, SvelteKit, Gatsby (other stacks: audit their built HTML output).
+Metrics and objectives are optional. No analytics or webmaster connection is
+required for core Citable workflows; owner CSV/JSON imports work without live
+provider authorization.
 
 ## License
 

package/dist/universal/.agents/skills/citable/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.4.0
+version: 1.5.1
 ---
 
 # Citable — search & generative discoverability governance
@@ -88,6 +88,10 @@ citable action-plan [run-id]          # ordered actions, blockers, semantic gate
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
 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>
+citable objectives init --input <json|yaml> [--write]
+citable objectives validate
+citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -144,8 +148,9 @@ mandatory.
 
 ## Registries are the source of truth
 
-`.citable/` holds nine YAML registries (queries, prompts, entities, claims,
-evidence, pages, crawlers, competitors, experiments), all schema-validated
+`.citable/` holds YAML registries for queries, prompts, entities, claims,
+evidence, pages, crawlers, competitors, experiments, metrics, objectives,
+interventions, and optional connection state, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in

package/dist/universal/.agents/skills/citable/VERSION

@@ -1 +1 @@
-1.4.0
+1.5.1

package/dist/universal/.agents/skills/citable/commands/README.md

@@ -24,11 +24,14 @@ intent, not executability, so statuses are strict:
 | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
 | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
 | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
+| /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 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) |
 | /citable validate-render | partially implemented by `observe render`; mobile/cross-browser and interaction exploration remain |
-| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by observation imports, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
+| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/dist/universal/.agents/skills/citable/commands/measurement.md

@@ -10,6 +10,23 @@ imports, and a disclosed custom citation-adapter protocol. It does not claim
 Bing AI Performance automation or equivalence between an API adapter and a
 consumer answer product. Preserve collector and product mode on every result.
 
+# implemented metric and objective workflow
+
+`citable metrics import --provider <name> --input <csv|json>` validates every
+row against a declared entry in `metrics.yaml` and writes immutable metric
+observations. `citable objectives init --input <json|yaml>` is dry-run by
+default; `--write` adds the validated objective with registry history.
+`citable objectives validate` checks contracts and metric references.
+`citable evaluate [objective-id]` compares independent baseline and evaluation
+windows, deduplicates repeated evidence, and reports each metric and guardrail
+separately. Insufficient data is `inconclusive`, never zero. Results describe
+temporal association and do not establish causation.
+
+Metrics, objectives, interventions, and connection state are optional. The
+absence of provider credentials is `not_configured`, not a finding and not
+evidence of zero activity. Credentials must never enter registries or evidence
+packages.
+
 # measure seo
 Inputs the operator exports (Search Console/Bing/analytics CSV or JSON).
 Workflow: validate segmentation (brand vs non-brand, intent, page type,

package/dist/universal/.agents/skills/citable/manifest.json

@@ -1,20 +1,20 @@
 {
   "name": "citable",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "managedBy": "citable-cli",
   "provider": "codex",
   "providerName": "OpenAI Codex",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.4.0",
+  "sourcePackage": "@nebulacomponents/citable@1.5.1",
   "variantPath": ".agents/skills/citable",
   "files": {
     "commands/action-findings.md": "sha256:510361461f24fcd4a550e0a8d960c383aefe23f9a65a54a3ffc44abd4c1293e7",
     "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
-    "commands/measurement.md": "sha256:c90352849a589b4cb66d1275a1888e9a2de5052a62399224c42b00f92bbdd814",
+    "commands/measurement.md": "sha256:5d7d94b496d2772ad433cf9fafa85af5c9638c8f326ec2017d2c8d6ef4dd1650",
     "commands/observe-and-act.md": "sha256:02a93bbbfddc3d8e11cb921ddccd19b0666133c4bdb4f4a280bcb131bed37e8c",
     "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
     "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
-    "commands/README.md": "sha256:71b7f2b7fc5e98cfa2b699ec48f58f3b4e32dfb0233315759fc98f7ae7eecac0",
+    "commands/README.md": "sha256:be1f55b439af94670d0711dcd7476eab09a2d7c86c4bcbf85b2ee0b454fb8684",
     "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
     "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
     "references/aeo-geo-validation.md": "sha256:e45828d3ccca54a08513cb4235578c8a8ecf1dc47d1cb98e4a497838103bef70",
@@ -38,13 +38,17 @@
     "schemas/common.defs.json": "sha256:effdd812910d1c275c50520bb70d8aec085e53fa8cb68054dc58c04a5d4a66b3",
     "schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
     "schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
+    "schemas/connection.schema.json": "sha256:cf0e9698dee697fb2c124989c3f478187297594c6ae76ecd04a43470e0a73616",
     "schemas/crawler.schema.json": "sha256:1a113dfb80bc6cde904c3ea648c82ea1d88fe50f2c1a0e7175d44abba28ac64e",
     "schemas/detector-quality.schema.json": "sha256:5e9e1ac80b1198a0ff8fa17b9f7a543d3ccf3ed3d60196152f6ff095cfdebccd",
     "schemas/entity.schema.json": "sha256:78a08c35c8f4eb7a804ab46b61a238502f59621ac5218991e783251fbde61c4f",
     "schemas/evidence.schema.json": "sha256:76baec7ad7e89c6952473c01dacb9e3b26953c088331e6314d531ce620df9ec1",
     "schemas/experiment.schema.json": "sha256:3cebebc5745a9eb359261408b0a0421b8370d2c94f8244ce939827cd9da41cb6",
     "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
-    "schemas/observation.schema.json": "sha256:81d8994591fff4bc23a10f813f1957719d5a2093171520f661ab8792e14748da",
+    "schemas/intervention.schema.json": "sha256:fcf28e117b207e64ffc96088aa70a95370841a2a9fa43ecb1c82b34c2058a818",
+    "schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
+    "schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
+    "schemas/observation.schema.json": "sha256:240ab0030e900dd8d779b63ef0558b1cca3b59a6de1a10cf9b2418b73ad92f02",
     "schemas/page.schema.json": "sha256:627613c35f461177fa946df08edf66fbf6f6bbdfc57eef812572b3af796d5e07",
     "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
     "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -53,9 +57,9 @@
     "schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
     "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
     "scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
-    "SKILL.md": "sha256:1e53637f88647dba7bdafc08545ad966f0f77b2814d956d3fbd57b38b3e34fa0",
+    "SKILL.md": "sha256:ef61c795af6e99099cd6247f4f6fec62ceb8c64f3eaa3e17eeb6b24057f7498c",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:78b591400c56b7b67b8cb3b2b8a8e65e9093897f02ce0878e6b5405c68620fa7"
+    "VERSION": "sha256:dfe7d71b3f428eb73ed853f8fded65e2986896e21d69f45ebf06bb623b450e14"
   },
-  "treeHash": "sha256:d5eb2a8baf1230bc82f28610cf0a875f58f5070cb3953838b8310bad07eca012"
+  "treeHash": "sha256:32f29a5d5aaab9b58e1ceae7ab894fe66fa2b55091248a20221f5f93b8e60915"
 }

package/dist/universal/.agents/skills/citable/schemas/connection.schema.json

@@ -0,0 +1,32 @@
+{
+  "$id": "citable://schemas/connection.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Optional connector state registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "connections" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["connection_id", "provider", "state", "authentication", "scopes", "limitations"],
+        "properties": {
+          "connection_id": { "type": "string", "pattern": "^CONNECTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "provider": { "type": "string", "minLength": 1 },
+          "property_id": { "type": ["string", "null"] },
+          "state": { "type": "string", "enum": ["not_configured", "configured", "synchronized", "partial", "authorization_expired", "permission_denied", "quota_limited", "temporarily_unavailable"] },
+          "authentication": { "type": "string", "enum": ["none", "environment", "os_keychain", "external_secret_manager", "owner_import"] },
+          "scopes": { "type": "array", "items": { "type": "string" } },
+          "last_synchronized_at": { "type": ["string", "null"], "format": "date-time" },
+          "cursor": { "type": ["string", "null"] },
+          "limitations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/dist/universal/.agents/skills/citable/schemas/intervention.schema.json

@@ -0,0 +1,33 @@
+{
+  "$id": "citable://schemas/intervention.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Intervention registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "interventions" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["intervention_id", "name", "status", "deployed_at", "affected_urls", "finding_ids", "objective_ids", "limitations"],
+        "properties": {
+          "intervention_id": { "type": "string", "pattern": "^INTERVENTION-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "status": { "type": "string", "enum": ["planned", "deployed", "rolled_back", "superseded"] },
+          "deployed_at": { "type": ["string", "null"], "format": "date-time" },
+          "commit": { "type": ["string", "null"] },
+          "pull_request": { "type": ["string", "null"] },
+          "affected_urls": { "type": "array", "items": { "type": "string" } },
+          "finding_ids": { "type": "array", "items": { "type": "string" } },
+          "objective_ids": { "type": "array", "items": { "type": "string", "pattern": "^OBJECTIVE-" } },
+          "limitations": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/dist/universal/.agents/skills/citable/schemas/metric.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "citable://schemas/metric.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Metric registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "metrics" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["metric_id", "name", "provider", "external_name", "unit", "value_type", "aggregation", "direction", "dimensions", "limitations"],
+        "properties": {
+          "metric_id": { "type": "string", "pattern": "^METRIC-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "provider": { "type": "string", "minLength": 1 },
+          "external_name": { "type": "string", "minLength": 1 },
+          "unit": { "type": "string", "enum": ["count", "ratio", "percent", "currency", "duration_ms", "position", "score", "custom"] },
+          "custom_unit": { "type": "string", "minLength": 1 },
+          "value_type": { "type": "string", "enum": ["integer", "number"] },
+          "aggregation": { "type": "string", "enum": ["sum", "average", "minimum", "maximum", "latest", "provider_defined"] },
+          "direction": { "type": "string", "enum": ["increase", "decrease", "maintain", "contextual"] },
+          "dimensions": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+          "limitations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "status": { "type": "string", "enum": ["active", "deprecated"] }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "unit": { "const": "custom" } } },
+            "then": { "required": ["custom_unit"] }
+          }
+        ]
+      }
+    }
+  }
+}

package/dist/universal/.agents/skills/citable/schemas/objective.schema.json

@@ -0,0 +1,65 @@
+{
+  "$id": "citable://schemas/objective.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Objective registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "kind", "updated", "entries"],
+  "properties": {
+    "version": { "const": 1 },
+    "kind": { "const": "objectives" },
+    "updated": { "type": "string", "format": "date-time" },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["objective_id", "name", "status", "primary_metrics", "supporting_metrics", "guardrails", "cohort", "comparison"],
+        "properties": {
+          "objective_id": { "type": "string", "pattern": "^OBJECTIVE-[A-Z0-9][A-Z0-9_-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "owner": { "type": ["string", "null"] },
+          "status": { "type": "string", "enum": ["draft", "active", "paused", "archived"] },
+          "primary_metrics": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/definitions/metricRef" } },
+          "supporting_metrics": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/definitions/metricRef" } },
+          "guardrails": { "type": "array", "items": { "$ref": "#/definitions/guardrail" } },
+          "cohort": { "$ref": "#/definitions/cohort" },
+          "comparison": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["baseline_days", "evaluation_days", "minimum_observations"],
+            "properties": {
+              "baseline_days": { "type": "integer", "minimum": 1 },
+              "evaluation_days": { "type": "integer", "minimum": 1 },
+              "minimum_observations": { "type": "integer", "minimum": 1 }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "metricRef": { "type": "string", "pattern": "^METRIC-[A-Z0-9][A-Z0-9_-]*$" },
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["metric_id", "operator", "threshold"],
+      "properties": {
+        "metric_id": { "$ref": "#/definitions/metricRef" },
+        "operator": { "type": "string", "enum": ["gte", "lte", "increase_by", "decrease_by", "no_regression"] },
+        "threshold": { "type": "number" }
+      }
+    },
+    "cohort": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["urls", "queries", "labels"],
+      "properties": {
+        "urls": { "type": "array", "items": { "type": "string" } },
+        "queries": { "type": "array", "items": { "type": "string" } },
+        "labels": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/dist/universal/.agents/skills/citable/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"] },
+    "kind": { "type": "string", "enum": ["render", "index", "citation", "citation_review", "crawler_log", "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"] },

package/dist/universal/.claude/skills/citable/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.4.0
+version: 1.5.1
 ---
 
 # Citable — search & generative discoverability governance
@@ -88,6 +88,10 @@ citable action-plan [run-id]          # ordered actions, blockers, semantic gate
 citable observe <mode> [options]      # render/index/citation/log/passage/consensus/performance evidence
 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>
+citable objectives init --input <json|yaml> [--write]
+citable objectives validate
+citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -144,8 +148,9 @@ mandatory.
 
 ## Registries are the source of truth
 
-`.citable/` holds nine YAML registries (queries, prompts, entities, claims,
-evidence, pages, crawlers, competitors, experiments), all schema-validated
+`.citable/` holds YAML registries for queries, prompts, entities, claims,
+evidence, pages, crawlers, competitors, experiments, metrics, objectives,
+interventions, and optional connection state, all schema-validated
 (`schemas/*.schema.json`) with referential integrity checks. Rules:
 
 - Never overwrite registry content without history — use the loader/saver in

package/dist/universal/.claude/skills/citable/VERSION

@@ -1 +1 @@
-1.4.0
+1.5.1

package/dist/universal/.claude/skills/citable/commands/README.md

@@ -24,11 +24,14 @@ intent, not executability, so statuses are strict:
 | /citable observe | implemented — render, index, citation, crawler-log, passage, consensus, performance, and corroboration evidence |
 | /citable apply | implemented — reviewed, hash-locked source replacements; dry run by default |
 | /citable monitor | implemented — compares immutable observation runs and emits evidence-linked alerts |
+| /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 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) |
 | /citable validate-render | partially implemented by `observe render`; mobile/cross-browser and interaction exploration remain |
-| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by observation imports, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
+| /citable measure seo/aeo/geo, test-prompts, monitor-crawlers, monitor-contradictions | partially implemented by metric/observation imports, objective evaluation, Google/CrUX live APIs, custom citation adapters, and monitor comparisons |
 
 Shared refusal conditions (all commands): any action that would fabricate
 facts, citations, evidence, authorship, reviews, corroboration, or hidden

package/dist/universal/.claude/skills/citable/commands/measurement.md

@@ -10,6 +10,23 @@ imports, and a disclosed custom citation-adapter protocol. It does not claim
 Bing AI Performance automation or equivalence between an API adapter and a
 consumer answer product. Preserve collector and product mode on every result.
 
+# implemented metric and objective workflow
+
+`citable metrics import --provider <name> --input <csv|json>` validates every
+row against a declared entry in `metrics.yaml` and writes immutable metric
+observations. `citable objectives init --input <json|yaml>` is dry-run by
+default; `--write` adds the validated objective with registry history.
+`citable objectives validate` checks contracts and metric references.
+`citable evaluate [objective-id]` compares independent baseline and evaluation
+windows, deduplicates repeated evidence, and reports each metric and guardrail
+separately. Insufficient data is `inconclusive`, never zero. Results describe
+temporal association and do not establish causation.
+
+Metrics, objectives, interventions, and connection state are optional. The
+absence of provider credentials is `not_configured`, not a finding and not
+evidence of zero activity. Credentials must never enter registries or evidence
+packages.
+
 # measure seo
 Inputs the operator exports (Search Console/Bing/analytics CSV or JSON).
 Workflow: validate segmentation (brand vs non-brand, intent, page type,

package/dist/universal/.claude/skills/citable/manifest.json

@@ -1,20 +1,20 @@
 {
   "name": "citable",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "managedBy": "citable-cli",
   "provider": "claude",
   "providerName": "Claude Code",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.4.0",
+  "sourcePackage": "@nebulacomponents/citable@1.5.1",
   "variantPath": ".claude/skills/citable",
   "files": {
     "commands/action-findings.md": "sha256:510361461f24fcd4a550e0a8d960c383aefe23f9a65a54a3ffc44abd4c1293e7",
     "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
-    "commands/measurement.md": "sha256:c90352849a589b4cb66d1275a1888e9a2de5052a62399224c42b00f92bbdd814",
+    "commands/measurement.md": "sha256:5d7d94b496d2772ad433cf9fafa85af5c9638c8f326ec2017d2c8d6ef4dd1650",
     "commands/observe-and-act.md": "sha256:02a93bbbfddc3d8e11cb921ddccd19b0666133c4bdb4f4a280bcb131bed37e8c",
     "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
     "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
-    "commands/README.md": "sha256:71b7f2b7fc5e98cfa2b699ec48f58f3b4e32dfb0233315759fc98f7ae7eecac0",
+    "commands/README.md": "sha256:be1f55b439af94670d0711dcd7476eab09a2d7c86c4bcbf85b2ee0b454fb8684",
     "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
     "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
     "references/aeo-geo-validation.md": "sha256:e45828d3ccca54a08513cb4235578c8a8ecf1dc47d1cb98e4a497838103bef70",
@@ -38,13 +38,17 @@
     "schemas/common.defs.json": "sha256:effdd812910d1c275c50520bb70d8aec085e53fa8cb68054dc58c04a5d4a66b3",
     "schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
     "schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
+    "schemas/connection.schema.json": "sha256:cf0e9698dee697fb2c124989c3f478187297594c6ae76ecd04a43470e0a73616",
     "schemas/crawler.schema.json": "sha256:1a113dfb80bc6cde904c3ea648c82ea1d88fe50f2c1a0e7175d44abba28ac64e",
     "schemas/detector-quality.schema.json": "sha256:5e9e1ac80b1198a0ff8fa17b9f7a543d3ccf3ed3d60196152f6ff095cfdebccd",
     "schemas/entity.schema.json": "sha256:78a08c35c8f4eb7a804ab46b61a238502f59621ac5218991e783251fbde61c4f",
     "schemas/evidence.schema.json": "sha256:76baec7ad7e89c6952473c01dacb9e3b26953c088331e6314d531ce620df9ec1",
     "schemas/experiment.schema.json": "sha256:3cebebc5745a9eb359261408b0a0421b8370d2c94f8244ce939827cd9da41cb6",
     "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
-    "schemas/observation.schema.json": "sha256:81d8994591fff4bc23a10f813f1957719d5a2093171520f661ab8792e14748da",
+    "schemas/intervention.schema.json": "sha256:fcf28e117b207e64ffc96088aa70a95370841a2a9fa43ecb1c82b34c2058a818",
+    "schemas/metric.schema.json": "sha256:2ada648e7274a8d78cc9d6e7ed616f91faa79cf9ed07613e2c1fc53b247aac8d",
+    "schemas/objective.schema.json": "sha256:94404dc95d04a6641ea7b9654317d0222793251ad44d3dfd2875738622a36025",
+    "schemas/observation.schema.json": "sha256:240ab0030e900dd8d779b63ef0558b1cca3b59a6de1a10cf9b2418b73ad92f02",
     "schemas/page.schema.json": "sha256:627613c35f461177fa946df08edf66fbf6f6bbdfc57eef812572b3af796d5e07",
     "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
     "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
@@ -53,9 +57,9 @@
     "schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
     "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
     "scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
-    "SKILL.md": "sha256:1e53637f88647dba7bdafc08545ad966f0f77b2814d956d3fbd57b38b3e34fa0",
+    "SKILL.md": "sha256:ef61c795af6e99099cd6247f4f6fec62ceb8c64f3eaa3e17eeb6b24057f7498c",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:78b591400c56b7b67b8cb3b2b8a8e65e9093897f02ce0878e6b5405c68620fa7"
+    "VERSION": "sha256:dfe7d71b3f428eb73ed853f8fded65e2986896e21d69f45ebf06bb623b450e14"
   },
-  "treeHash": "sha256:d5eb2a8baf1230bc82f28610cf0a875f58f5070cb3953838b8310bad07eca012"
+  "treeHash": "sha256:32f29a5d5aaab9b58e1ceae7ab894fe66fa2b55091248a20221f5f93b8e60915"
 }