@nebulacomponents/citable 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.3.0 — 2026-07-18
+
+### Added
+
+- `citable action-plan [run-id]` converts immutable audit findings into ordered remediation artifacts with owners, blockers, unsafe shortcuts, semantic review gates, and detector-specific verification commands.
+- ANS-009/010 and GEO-005/006 validate prompt-to-page coverage, page-level claim/evidence mapping, primary entity mapping, and complete prompt evaluation briefs.
+- Canonical finding-to-action and AEO/GEO acceptance workflows for installed agent skills.
+- Separate audit posture states for retrieval eligibility, source extraction/support suitability, and observed citation behavior; no aggregate AI visibility score.
+- Capability-boundary and gap-analysis references covering crawler identity, index presence, rendered extraction, passage integrity, canonical consensus, and controlled citation evidence.
+
+### Changed
+
+- Registry entry schemas now reject unknown properties so misspelled governance fields fail validation instead of being ignored. This is a stricter contract; existing registries with extension fields must migrate those fields into the documented schema before validation.
+- Remote audits now restrict redirects to the audited origin, reject private-network destinations, enforce per-attempt timeouts, and cap response bodies at 5 MiB.
+
+### Fixed
+
+- Invalid `--ref-date` values now fail closed before expiry or evidence evaluation.
+- `self-upgrade` reports a nonzero process exit status when registry checks or cache refreshes fail.
+- Release packaging supports both array-shaped and package-keyed `npm pack --json` metadata through a shared parser.
+
+## 1.2.0 — 2026-07-18
+
+### Added
+
+- **`self-upgrade` command** — checks npm registry for the latest version and upgrades the npx cache if a newer version is available:
+  - `npx @nebulacomponents/citable self-upgrade` — check and upgrade
+  - `npx @nebulacomponents/citable self-upgrade --check` — check only, no upgrade
+  - `npx @nebulacomponents/citable self-upgrade --json` — machine-readable output
+  - Uses Node's built-in `fetch` (no extra deps), 10s timeout, graceful offline error
+- **6 new tests** for self-upgrade (current, update-available, registry failure × 2 each for human/JSON output)
+
+### Changed
+
+- Test count: 84 → 90
+
 ## 1.1.0 — 2026-07-18
 
 ### Added
@@ -21,7 +57,7 @@
 
 ### Changed
 
-- Detector count: 109 → 119 across 18 namespaces
+- Detector count: 102/15 namespaces (0.1.0) → 109/17 (1.0.0) → **119/18 namespaces** (this release)
 - Test count: 46 → 84
 
 ## 1.0.0 — 2026-07-18
@@ -38,6 +74,9 @@
   - CWV-001: LCP potential blockers (render-blocking scripts, images without dimensions)
   - CWV-002: preconnect hints for fonts
   - CWV-003: image optimization checks (format, dimensions, lazy loading)
+
+  > **Limitation:** no field or lab data collection; the CWV detectors check
+  > infrastructure readiness, not performance.
 - **URL fetch resilience** — retry with exponential backoff + jitter, 5xx handling
 - **CI workflow** — GitHub Actions for Node 22 matrix testing
 

package/README.md

@@ -16,11 +16,14 @@ generator, not a Lighthouse wrapper, not an "AI visibility score".
 - **Persistent registries** (`.citable/`): queries, prompts, entities, claims,
   evidence, pages, crawler policies, competitors, experiments — all
   JSON-Schema validated with referential integrity and history-preserving saves.
-- **109 detectors** across 17 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
-  ENTITY, CLAIM, EVD, SCHEMA, LINK, EXT, GEO, RECO, LIFE, MEAS, HREFLANG, CWV), each with
+- **123 detectors** across 18 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
+  ENTITY, CLAIM, EVD, SCHEMA, LINK, EXT, GEO, RECO, LIFE, MEAS, HREFLANG, CWV, AGENT), each with
   remediation, verification, severity, and determinism declared.
 - **Evidence packages** for every run: manifest, findings, report, captured
   robots/sitemaps/headers/schema/link graph, checksums.
+- **Separate state reporting** for retrieval eligibility, source extraction and
+  support suitability, and observed citation behavior. These are never merged
+  into an "AI visibility score."
 - **Fail-closed governance**: claims can't become verified without evidence,
   expired evidence invalidates claims, schema is never fabricated, missing
   facts return `blocked` with `required_input`.
@@ -28,6 +31,12 @@ generator, not a Lighthouse wrapper, not an "AI visibility score".
   mandatory human-review conditions.
 - **Multi-agent distribution**: Claude Code, Codex-compatible, Cursor, Gemini,
   generic — generated from one canonical `skill/` source.
+- **Agent-readiness detectors** (AGENT namespace): agents are both readers
+  and writers of your site — `llms.txt` and Markdown content negotiation shape
+  what they consume; MCP Server Cards and A2A Agent Cards expose what they can
+  invoke; Content-Signals and Web Bot Auth govern the permissions they receive.
+  Citable checks all of these in one pass alongside the rest of your
+  SEO/AEO/GEO signal surface.
 
 ## Install
 
@@ -114,6 +123,7 @@ npx @nebulacomponents/citable help
 cd your-site/
 citable init                  # creates .citable/ (non-destructive)
 citable audit --target ./dist --base-url https://example.com
+citable action-plan <run-id> # ordered actions, blockers, review gates, verification
 citable substantiate          # claim/evidence assessment (dry run)
 citable validate              # registry schema + referential integrity
 ```
@@ -138,6 +148,8 @@ citable validate              # registry schema + referential integrity
   workflow and trusted publisher setup
 - [Known limitations](docs/known-limitations.md) — read this before relying on
   any coverage claim
+- [Capability gap analysis](docs/capability-gap-analysis.md) — implemented,
+  partial, operator-supplied, and missing evidence boundaries
 
 ## Requirements
 

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: 0.1.0
+version: 1.3.0
 ---
 
 # Citable — search & generative discoverability governance
@@ -57,6 +57,19 @@ recommendation would require invented facts.
 Report posture per dimension (e.g. `retrieval_eligibility: strong`,
 `answer_extractability: weak`) — never one opaque 0–100 "AI visibility score".
 
+Every report must keep these top-level states separate:
+
+1. **Retrieval eligibility** — policy and captured technical conditions.
+2. **Source extraction and support suitability** — passage, entity, claim,
+   evidence, freshness, and structured-data conditions.
+3. **Observed citation behavior** — only controlled, timestamped provider
+   observations; absent observations are `not_evidenced`, never inferred.
+
+Within retrieval, distinguish `allowed_by_policy`, `synthetic_fetch_succeeded`,
+`observed_in_production_logs`, `indexed`, and `returned_by_retrieval`. Within
+citation testing, distinguish mention, citation, material support, canonical
+source selection, and recommendation. These states are not interchangeable.
+
 ## Tooling
 
 The `citable` CLI in this repository performs the deterministic work. Always
@@ -71,6 +84,7 @@ citable substantiate [--write]
 citable schema --target <dir|url>
 citable validate [registries|claims|evidence|schema|links]
 citable compare-snapshots [runA runB]
+citable action-plan [run-id]          # ordered actions, blockers, semantic gates, verification
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -79,6 +93,40 @@ lifecycle corroboration`. Every audit writes an evidence package to
 sitemaps, schema, link graph, checksums). A report without its evidence package
 is not a deliverable.
 
+## Finding-to-action protocol
+
+Detection is the start of the workflow, not the deliverable. For every audit:
+
+1. Run `citable action-plan <run-id>`. Use the generated files under
+   `.citable/actions/<run-id>/`; never edit the immutable source run.
+2. Work phases in order: **unblock** retrieval/security failures,
+   **governance** for owners/entities/claims/evidence, **content** for page and
+   answer changes, then **optimization**. Within a phase, critical/high precede
+   lower-severity work. Severity never substitutes for confidence.
+3. Before editing, assign an accountable owner and satisfy every
+   `required_input`. A blocked action stays blocked; do not write around missing
+   facts, evidence, legal review, or source-to-render mapping.
+4. Apply the listed semantic gates. AEO changes require intent alignment and
+   answer-extractability review. GEO changes require entity clarity,
+   recommendation eligibility, and narrative-accuracy review. Claim/evidence
+   changes additionally require claim-boundedness and evidence-strength review.
+5. Make the smallest source or registry change that addresses the evidence.
+   Reject every listed unsafe shortcut and every matching anti-pattern.
+6. Run the repository build/test commands, then the action's verification
+   command. Re-audit the affected scope and run `compare-snapshots` against the
+   source run. A finding is resolved only when its detector no longer reports
+   the same subject and no new critical/high regression appears.
+7. Report resolved, persisting, blocked, accepted-risk, and newly introduced
+   findings separately. Preserve run IDs, diffs, owners, review evidence, and
+   residual risk. Never translate "detector absent" into an outcome guarantee.
+
+For the complete AEO/GEO acceptance profile, follow
+`references/aeo-geo-validation.md`. Skipped deterministic checks or incomplete
+mandatory semantic reviews make the relevant posture `not_established`.
+Consult `references/capability-boundaries.md` before claiming any observation;
+it identifies which states the current CLI can collect and which require
+operator data or future adapters.
+
 ## Command workflows
 
 Detailed per-command workflows live in `commands/`. Follow them; they define

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

@@ -1 +1 @@
-1.1.0
+1.3.0

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

@@ -20,6 +20,7 @@ intent, not executability, so statuses are strict:
 | /citable schema | implemented |
 | /citable validate, validate-claims, validate-evidence, validate-schema, validate-links | implemented |
 | /citable compare-snapshots / validate-regression | implemented |
+| /citable action-plan | implemented — writes ordered, source-run-bound action artifacts outside immutable evidence packages |
 | /citable 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/dist/universal/.agents/skills/citable/commands/action-findings.md

@@ -0,0 +1,37 @@
+---
+command: /citable action-plan [run-id]
+purpose: Convert observed findings into ordered remediation work without changing the immutable audit package or inventing implementation facts.
+preconditions: [completed audit run with findings.json and manifest.json]
+artifacts_created: [.citable/actions/<run-id>/action-plan.json, .citable/actions/<run-id>/action-plan.md]
+failure_behaviour: missing or invalid source run -> fail; review-required action without owner -> blocked with required_input
+---
+
+# Detection-to-action workflow
+
+1. Generate the plan with `citable action-plan <run-id>`. Confirm the stored
+   `source_findings_hash` still matches the source audit before acting.
+2. Triage in generated phase order: unblock, governance, content, optimization.
+   Do not skip an earlier phase when it invalidates later evidence or rendering.
+3. Assign owners. Resolve each blocked action's exact required input. Missing
+   facts, evidence, legal review, or semantic review are blockers, not drafting
+   opportunities.
+4. Capture a before state for each subject. Use the finding's evidence,
+   preferred remediation, unsafe shortcuts, and detector lineage as the change
+   boundary.
+5. Apply the semantic gates listed on the action using the named rubrics. Store
+   quoted passages and registry records supporting the posture decision.
+6. Implement the smallest defensible change in canonical source. Registry
+   writes use the loader/saver and retain history. Content claims remain equal
+   to or narrower than their registered scope.
+7. Build and test the target repository. Run the generated verification
+   command, then compare the new audit to the source run.
+8. Close only with evidence: resolved detector/subject pair, before/after run
+   IDs, diff, reviewer, and residual risk. Mark blocked, accepted risk, and
+   false positive explicitly; do not silently drop findings.
+
+# Execution boundary
+
+`action-plan` plans and records work; it does not automatically rewrite a site.
+Source mutation remains agent/operator work because arbitrary repositories need
+their own build architecture, review authority, and rollback path. Follow
+`optimize-page.md` or `page-work.md` when the action requires page changes.

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

@@ -1,21 +1,24 @@
 {
   "name": "citable",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "managedBy": "citable-cli",
   "provider": "codex",
   "providerName": "OpenAI Codex",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.1.0",
+  "sourcePackage": "@nebulacomponents/citable@1.3.0",
   "variantPath": ".agents/skills/citable",
   "files": {
+    "commands/action-findings.md": "sha256:510361461f24fcd4a550e0a8d960c383aefe23f9a65a54a3ffc44abd4c1293e7",
     "commands/ingest.md": "sha256:cf35659aecd9d0e160909003efdbe056864fc5d824c71b4ef0ee801ce07ff598",
     "commands/measurement.md": "sha256:3550b1e747c5a38cdb712016b9bc773d93596bc4d1b49a309f9cddd816c1b662",
     "commands/optimize-page.md": "sha256:35866f3d7cdeef0376ea7a7d7036085a9b9cf95bbb300ecf4bd77610ebd74d85",
     "commands/page-work.md": "sha256:965a66e59bdf7b0da482d26fade53b3d265885ece5d463fe83b0789ebefaef3e",
-    "commands/README.md": "sha256:13774e705356b9eafb42aa522cc10337d86dfb973d533976f041a21819fb6cb4",
+    "commands/README.md": "sha256:186ca808e0f303938ef9f8f98c8273c4b7cb76cc791e7d751c3639bf201e3bb1",
     "commands/validate-render.md": "sha256:a8e1d04d40b84d57c35039250d98c6a7302cd44a148a8c3b9d9cfb92678c4347",
     "policies/crawler-policy-template.md": "sha256:15c88a4eeb21f53f71e5250dd3eb2d2791a814b304eaefce8bb30e2bdf2e2e59",
+    "references/aeo-geo-validation.md": "sha256:e45828d3ccca54a08513cb4235578c8a8ecf1dc47d1cb98e4a497838103bef70",
     "references/anti-patterns.md": "sha256:de63f8e646af0fbf479b45eb1d050ae62a8637acc320d21b87e4a083fd4c47e7",
+    "references/capability-boundaries.md": "sha256:901840fe87080071d0b11aa329d6a7954ffa6c601c58fadc275b55a7a988376a",
     "rubrics/answer-extractability.md": "sha256:c8e741143c34e53afdb3dc7b6976ce7b4485dce13b12d14c193fccb17bacf1da",
     "rubrics/claim-boundedness.md": "sha256:0bab1b85248c252b966175912ebfae13bf18aa7e41573f7466831ac78b5d3e27",
     "rubrics/comparison-fairness.md": "sha256:7afc86903aa4a695060be7b6bca42ba505c106ea7cfa153344189afc5b78a5ba",
@@ -29,26 +32,27 @@
     "rubrics/recommendation-eligibility.md": "sha256:38d2055fc5f6ab5e40fd1b48de4e0518fc4382da0b7062ad09c5afebcc673fc3",
     "rubrics/semantic-clarity.md": "sha256:66d9f4843a4a620ea8c00625c5e17c02baeaa373f2b445ce13de6f81d78ec7ba",
     "rubrics/source-authority.md": "sha256:8dbfe46bdcd0b5351f038be503601268c7d0abb9bed83be9ca58bf54dec5a73b",
-    "schemas/claim.schema.json": "sha256:70c521e51a24031a1e1f73eca04c2a2650e760f3fdc82e9553eb26c0b5c428e9",
-    "schemas/common.defs.json": "sha256:1ae1ae4a9b0babadbcba3288dd3d1adb3e152f87f1e51c08a397a0f29878e95f",
-    "schemas/competitor.schema.json": "sha256:7d34c1f131eba23d94404921c4defbdabb402f83bc5a748a1de40fbe89d65cca",
+    "schemas/action-plan.schema.json": "sha256:4b6c4c877840a065c7c0c0c7b52f696502bf3d4ca6d31179622fc364ea868d5e",
+    "schemas/claim.schema.json": "sha256:ce79ccbfa34ece9b7a309a6962522ea06a1f44c468b4c472b5c376554a788537",
+    "schemas/common.defs.json": "sha256:effdd812910d1c275c50520bb70d8aec085e53fa8cb68054dc58c04a5d4a66b3",
+    "schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
     "schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
-    "schemas/crawler.schema.json": "sha256:0541de509d0b5de065e1dd3ff52212ba389eaf7f5a9c2309b5e5beb232b4b356",
+    "schemas/crawler.schema.json": "sha256:1a113dfb80bc6cde904c3ea648c82ea1d88fe50f2c1a0e7175d44abba28ac64e",
     "schemas/detector-quality.schema.json": "sha256:5e9e1ac80b1198a0ff8fa17b9f7a543d3ccf3ed3d60196152f6ff095cfdebccd",
-    "schemas/entity.schema.json": "sha256:12f9222122255c86059185bc66e528e2828b430f7abc5683e6759774eb555553",
-    "schemas/evidence.schema.json": "sha256:a78d39cd1d66c89198b0ecc9af48c8d3d8659c7b5cbb9f96c43d18fcf2b4aeb7",
-    "schemas/experiment.schema.json": "sha256:704ea5c14cd4409c3a1806b8b1c124bcd9f2fe9e313dfa93662889bed0cb6441",
+    "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/page.schema.json": "sha256:195d2f91d67550627c7047fd8e98d08dc386bc5858a02239d6c23b99193eaac2",
+    "schemas/page.schema.json": "sha256:627613c35f461177fa946df08edf66fbf6f6bbdfc57eef812572b3af796d5e07",
     "schemas/project.schema.json": "sha256:ea48fdb6480f7047ba4594bd5908bc1f79c1ad6b9a2c204df900959b5f203dc6",
     "schemas/prompt-result.schema.json": "sha256:b55be47d7d58d7b1dd8c3b1e849e24e55216212c592cde7eb836953379b85737",
-    "schemas/prompt.schema.json": "sha256:69782525f9de3a9f92649f2bc2fb4a0b2ed4288d6028663b18e39918c9f7fca1",
-    "schemas/query.schema.json": "sha256:59829f78461f115d73486e6350dcea5daf5a8e77576013b7a6d25913f240c55d",
+    "schemas/prompt.schema.json": "sha256:7f0f50c83a86ac91faa7b79895dbc1fed371e8c0342e18d8c2877cc81f4f0f4c",
+    "schemas/query.schema.json": "sha256:3c0793a8c0c48ab39320416790840b345ea987696f35b1cc364f23245a62aacb",
     "schemas/run.schema.json": "sha256:46c3178620f3a358d936d535aeadb83454b9b35b551e53e6615cc9862063dacb",
     "scripts/README.md": "sha256:1c3e952950ef353849621b07c5f615bf7cd20cc5654da4635492a7bd6384e747",
-    "SKILL.md": "sha256:637bb755bca6a2225c5b69edab0b8be7dff294e784d7ce25cec23546b847324c",
+    "SKILL.md": "sha256:b9864498dd1507003386ac82b4cb8aea9056af7435c313e1aa19faa5cb185bf1",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:1575e1af4a95f12f70b4ee6a6adce8160953d93ea17dc2611b90883ccc3ad3b8"
+    "VERSION": "sha256:64d23f858ef51b0f996e4966d4e27c0371b437e2d2787890b1f7ad22d4ec5663"
   },
-  "treeHash": "sha256:1984fdb279446bdc9e2c81673a1c521564d6ed9f0cc74e8eee62e7cacb7c2843"
+  "treeHash": "sha256:f9dab639bf6d9fa5b638eefa2cc9ee73c7a30cc37d7f85f625ae608976b195aa"
 }

package/dist/universal/.agents/skills/citable/references/aeo-geo-validation.md

@@ -0,0 +1,50 @@
+# AEO/GEO validation profile
+
+This profile is an acceptance gate for eligibility and governance conditions,
+not a prediction of citation or recommendation. Report every row as
+`pass | finding | skipped | not_established`; never collapse rows into one score.
+
+## Top-level state separation
+
+| State | Current evidence boundary |
+| --- | --- |
+| Retrieval eligibility | Static policy plus captured synthetic HTTP response; crawler identity remains simulated unless verified logs/IP evidence are supplied |
+| Source extraction and support suitability | Initial-HTML extraction plus registries/detectors/rubrics; rendered-DOM parity remains not established without a renderer |
+| Observed citation behavior | Operator-supplied prompt-result observations only; report cohort size and property citation presence, never infer from readiness |
+
+## AEO checks
+
+| Condition | Deterministic controls | Semantic gate |
+| --- | --- | --- |
+| Retrievable, indexable answer surface | TECH, CRAWL, LINK; no skipped critical transport checks | intent-alignment |
+| Governed question coverage | ANS-009; page target_prompts resolve to active prompts | intent-alignment |
+| Direct, self-contained answer | ANS-001…004, ANS-008 | answer-extractability |
+| Atomic, bounded factual claims | ANS-005, CLAIM-004/007/009 | claim-boundedness |
+| Evidence adjacent and supportable | ANS-010, EVD-001…007 | evidence-strength, source-authority |
+| Procedures and comparisons extract cleanly | ANS-006/007 | answer-extractability, comparison-fairness |
+| Entity attribution is stable | ENTITY-001…007, GEO-005 | entity-clarity |
+| Visible schema agrees with content | SCHEMA-001…008 | semantic-clarity |
+
+## GEO checks
+
+| Condition | Deterministic controls | Semantic gate |
+| --- | --- | --- |
+| Prompt portfolio is evaluable | GEO-006, MEAS-001…003 | narrative-accuracy |
+| Entity and category representation is explicit | GEO-002/003/005, ENTITY-001…007 | entity-clarity |
+| Claims preserve scope, evidence, and legal status | CLAIM-001…009, EVD-001…007, ANS-010 | claim-boundedness, evidence-strength |
+| Recommendation inputs are complete | RECO-001…006 | recommendation-eligibility |
+| Comparisons are fair and corroborated | ANS-007, EXT-001/002 | comparison-fairness, source-authority |
+| Model-directed manipulation is absent | GEO-001/004 | mandatory human review for ambiguous hidden content |
+| Temporal and narrative integrity is governed | LIFE, MEAS, SCHEMA-004/006 | narrative-accuracy |
+
+## Acceptance rules
+
+- A deterministic finding means the corresponding condition is not met.
+- A skipped detector means the condition is `not_established`, not pass.
+- A heuristic detector absence is not proof; complete the semantic rubric.
+- Any rubric ambiguity condition produces `not_established + review_required`.
+- AEO/GEO posture can improve only after a before/after audit resolves the
+  relevant detector/subject pair without introducing critical/high regression.
+- Effectiveness is measured only from repeated, segmented observations using
+  the measurement workflow. Eligibility checks alone do not establish engine
+  behavior or causal impact.

package/dist/universal/.agents/skills/citable/references/capability-boundaries.md

@@ -0,0 +1,34 @@
+# Capability and observation boundaries
+
+Use the narrowest supported state. Never promote evidence across rows.
+
+| State | Current capability | Required evidence |
+| --- | --- | --- |
+| Allowed by policy | Implemented | Effective robots rule plus crawler-purpose registry decision |
+| Synthetic fetch succeeded | Partial | Captured status, redirects, headers, body from the declared user agent; label identity simulated |
+| Verified crawler reached edge | Operator supplied | Request log plus provider-published IP verification where supported |
+| Observed in production logs | Operator supplied | Timestamped server/CDN log with URL, status, bytes, latency, cache result, UA, and verification result |
+| Indexed | Operator supplied | Search Console/Bing Webmaster/API or timestamped engine observation |
+| Returned by retrieval | Operator supplied | Provider observation containing retrieved source URL |
+| Cited | Operator supplied | Complete answer observation with citation URL |
+| Materially supports answer | Human review required | Answer claim mapped to a passage that entails it |
+| Recommended | Operator supplied + review | Explicit recommendation, constraints, provider/mode/locale/time |
+
+Current CLI URL mode does not prove crawler identity, WAF allowlisting,
+production-log access, index presence, selected canonical, rendered DOM parity,
+or provider citation behavior. Record those states as `not_evidenced` unless the
+specified evidence is supplied.
+
+Primary-source lineage for these boundaries:
+
+- Perplexity documents separate `PerplexityBot` and `Perplexity-User` purposes,
+  published IP lists, and UA-plus-IP verification:
+  https://docs.perplexity.ai/docs/resources/perplexity-crawlers
+- Google documents `noindex` as preventing inclusion in Google Search and
+  distinguishes crawl/content controls:
+  https://developers.google.com/search/docs/crawling-indexing/control-what-you-share
+- Bing documents citation counts as observations that do not indicate ranking,
+  authority, or placement:
+  https://blogs.bing.com/webmaster/February-2026/Introducing-AI-Performance-in-Bing-Webmaster-Tools-Public-Preview
+- Google requires structured data to describe visible page content:
+  https://developers.google.com/search/docs/appearance/structured-data/sd-policies

package/dist/universal/.agents/skills/citable/schemas/action-plan.schema.json

@@ -0,0 +1,55 @@
+{
+  "$id": "citable://schemas/action-plan.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Finding action plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["source_run_id", "source_findings_hash", "generated_at", "summary", "actions"],
+  "properties": {
+    "source_run_id": { "type": "string", "minLength": 1 },
+    "source_findings_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "generated_at": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total_actions", "ready", "blocked"],
+      "properties": {
+        "total_actions": { "type": "integer", "minimum": 0 },
+        "ready": { "type": "integer", "minimum": 0 },
+        "blocked": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action_id", "finding_ids", "phase", "priority", "subject", "action", "owner", "status", "required_input", "semantic_gates", "unsafe_shortcuts", "verification"],
+        "properties": {
+          "action_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
+          "finding_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "phase": { "type": "string", "enum": ["unblock", "governance", "content", "optimization"] },
+          "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
+          "subject": { "type": "string" },
+          "action": { "type": "string", "minLength": 1 },
+          "owner": { "type": ["string", "null"] },
+          "status": { "type": "string", "enum": ["ready", "blocked"] },
+          "required_input": { "type": "array", "items": { "type": "string" } },
+          "semantic_gates": { "type": "array", "items": { "type": "string" } },
+          "unsafe_shortcuts": { "type": "array", "items": { "type": "string" } },
+          "verification": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["method", "detector", "command", "expected_result"],
+            "properties": {
+              "method": { "type": "string" },
+              "detector": { "type": "string" },
+              "command": { "type": "string" },
+              "expected_result": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -10,6 +10,7 @@
   "definitions": {
     "claim": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["claim_id", "claim", "claim_type", "status"],
       "properties": {
         "claim_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
@@ -34,6 +35,7 @@
         "source_location": { "type": "string" },
         "support_assessment": {
           "type": "object",
+          "additionalProperties": false,
           "required": ["status"],
           "properties": {
             "status": { "type": "string", "enum": ["directly_supported", "partially_supported", "inferred", "contradicted", "not_assessed"] },

package/dist/universal/.agents/skills/citable/schemas/common.defs.json

@@ -12,6 +12,7 @@
     },
     "provenance": {
       "type": "object",
+      "additionalProperties": false,
       "properties": {
         "created": { "$ref": "#/definitions/isoDate" },
         "updated": { "$ref": "#/definitions/isoDate" },
@@ -21,6 +22,7 @@
     },
     "registryFile": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["version", "kind", "entries"],
       "properties": {
         "version": { "type": "integer", "minimum": 1 },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "competitor": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["competitor_id", "name", "status"],
       "properties": {
         "competitor_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "crawler": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["crawler_id", "user_agent", "purpose", "decision", "status"],
       "properties": {
         "crawler_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "entity": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["entity_id", "canonical_name", "entity_type", "status"],
       "properties": {
         "entity_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
@@ -26,7 +27,7 @@
         "secondary_categories": { "type": "array", "items": { "type": "string" } },
         "definition": { "type": "string" },
         "exclusions": { "type": "array", "items": { "type": "string" } },
-        "relationships": { "type": "array", "items": { "type": "object", "required": ["type", "entity"], "properties": { "type": { "type": "string" }, "entity": { "type": "string" } } } },
+        "relationships": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["type", "entity"], "properties": { "type": { "type": "string" }, "entity": { "type": "string" } } } },
         "evidence": { "type": "array", "items": { "type": "string" } },
         "schema_types": { "type": "array", "items": { "type": "string" } },
         "status": { "$ref": "citable://schemas/common.defs.json#/definitions/status" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "evidence": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["evidence_id", "title", "evidence_type", "verification_status"],
       "properties": {
         "evidence_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "experiment": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["experiment_id", "hypothesis", "primary_metric", "status"],
       "properties": {
         "experiment_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "page": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["page_id", "url", "page_type", "status"],
       "properties": {
         "page_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "prompt": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["prompt_id", "canonical_prompt", "prompt_class", "status"],
       "properties": {
         "prompt_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },

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

@@ -10,6 +10,7 @@
   "definitions": {
     "query": {
       "type": "object",
+      "additionalProperties": false,
       "required": ["query_id", "canonical_query", "intent", "status"],
       "properties": {
         "query_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },