@nebulacomponents/citable 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -15,6 +15,31 @@ _No entries yet. See [`BOUNTY.md`](BOUNTY.md) to submit the first one._
 
 ## Unreleased
 
+## 1.17.0 — 2026-09-08
+
+### Added — Closed-Loop Remediation & Customer Fulfillment (Nebula Release Requests)
+
+- Added production-safe patch review in `src/commands/remediate.js`: framework detection (`detectFramework`), idempotent patchers (`applyPatchDetailed` — second application is a fixed point), unified diffs before any write (`unifiedDiff`), structural static validation that fails closed on unknown frameworks (`validatePatchedSource`), explicit confidence scoring with per-factor breakdown and a semantic-copy cap (`computeConfidence`), rollback snapshots with SHA-256 manifests under `.citable/remediation/snapshots/`, and refusal of `--write` when validation fails or confidence is below the 0.7 gate. Semantic microcopy replacements (CRO-012/COMP-003) always refuse automated write: copy decisions are human editorial judgments, not mechanical fixes.
+- Added closed-loop remediation verification `citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]` (`src/commands/verifyRemediation.js`): maps source-run finding → gated patch → detector re-run → before/after verdict (`verified`, `not_resolved`, `blocked`, `patch_refused`), detects new critical/high regressions against the full before-run, and emits a checksummed evidence bundle validated against the new contract `schemas/remediation-verification.schema.json`. Resolution means the detector no longer reports the same subject — never an outcome guarantee.
+- Added customer-ready implementation kit exporter `citable kit export --run <run-id> --finding <id> [--target <file>]` (`src/commands/implementationKit.js`): produces a structured directory with the verbatim finding, exact unified diff, Nebula Component template, rendering-evidence manifest (real evidence only — imagery is never fabricated), acceptance tests, deployment/rollback instructions, re-audit script, and explicit limitations/assumptions. Modeled revenue or lift estimates are excluded by policy.
+- Added per-finding provenance envelopes in `src/detectors/framework.js` (`runDetectors`): every finding now records `detector_version`, `tool_version`, source URL/file, evidence selector, evidence source class, viewport (or an explicit note that none was captured), methodology (deterministic vs heuristic), and a revalidation requirement. Contract extended in `schemas/finding.schema.json`. Detector definitions default to `version: 1` and must be bumped on semantic changes.
+- Added `citable compatibility` (`src/commands/compatibility.js`): pre-flight diagnosis of Node engine requirements, optional peer adapters (playwright, lighthouse, chrome-launcher, tesseract.js) distinguishing installed vs importable, browser executable presence (never claiming launch success), project framework detection for remediation format matching, registry/schema freshness, and generated-edge size against documented platform limits.
+- Added `citable verify page <page> --target <dir|url>`: full detector set scoped to a single page with severity breakdown and explicit posture definition (pass = no detector currently reports the page; not an outcome guarantee).
+- Added edge-code security audit `src/commands/edgeSecurity.js` with rules EDGSEC-001 through EDGSEC-007 (CSP unsafe-inline, HTMLRewriter `html:true` injection sinks, unescaped interpolation into HTML/script/Liquid contexts, untrusted referral fragments into parsing DOM sinks, potential PII collection, per-request response variance without cache guidance, worker size limits). Every `citable export edge` now ships with a security summary; `citable audit edge <file> --format <fmt>` audits arbitrary edge code. Also fixed a missing `fs` import that crashed `exportEdgeRules` with `--output`.
+- Added experiment safety guardrails `citable check experiment <id>` (`src/commands/experimentGuardrails.js`): sample-ratio mismatch (chi-square, standard 0.001 alpha), stopping-early, underpowered samples, experiment contamination and variant collisions, revenue attribution without a concluded SRM-clean experiment, and a mutually exclusive lifecycle of `planned | running | inconclusive | validated` with explicit definitions — "winner" language is never used.
+- Added deterministic visual layout-contract suite `citable test visual` (`src/commands/visualRegression.js`): contract checks (three viewport classes, keyboard focus visibility, reduced motion, narrow-mobile collapse, text-zoom wrapping, dark/light preference, aria-pressed toggles, 48px touch targets) plus a 22-cell screenshot matrix that records per-cell captures when playwright and a browser are available and otherwise records an explicit skipped state with required inputs. Preview HTML gained focus-visible outlines, prefers-reduced-motion handling, narrow-width collapse, long-string wrapping, color-scheme adaptation, and accessible viewport toggles.
+- Added structured machine-readable output contract: every `--json` payload is wrapped in the stable envelope `{ citable_output_schema, tool_version, command, generated_at, result }` with contract `schemas/cli-output-envelope.schema.json` (envelope version 1.0).
+- Added golden benchmark corpus `tests/fixtures/golden-corpus/` (version 1, anonymized synthetic fixtures across ecommerce, SaaS, lead generation, checkout, and agency verticals) with page-level detector labels and saliency bounds, plus `citable corpus benchmark` (`src/commands/goldenCorpus.js`) computing per-detector TP/FP/FN, precision, recall, and F1 with a fail-closed regression gate and mutation-tested failure proofs. Emphasis detectors include CRO-021 and the saliency indices.
+
+### Changed — Terminology and Claim-Accuracy Hardening
+
+- Split `CRO-021` (detector version 2) into distinct capabilities: payment-wallet readiness (Apple Pay, Google Pay, PayPal Express — payment methods) and authentication readiness (WebAuthn/passkeys — account authentication, reported informationally by `inspect cro` as `express_checkout_readiness`). The misleading "biometric readiness" framing is retired; a passkey-only checkout still fails wallet readiness. Fixtures prove both detection and the wallet/auth distinction.
+- Removed the unsupported "edge cache speeds (<2ms latency)" and "sub-500ms" performance claims from `docs/ROADMAP.md`: no speed or latency figure may be stated publicly without a documented measurement methodology.
+- Hardened `NebulaScentBeacon` referral handling in `src/components/index.js`: referrer and `:~:text=` fragments are documented and enforced as user-controlled untrusted input used only against a fixed allowlist to detect referral state; raw values are never rendered, persisted, or transmitted, and dynamic claim text must come from developer-controlled props.
+- Labeled all modeled outputs as heuristic indices: `calculateVisualSaliency` now returns `fact_status: modeled_index_not_observed_behavior` with interpretation notes; `inspect cro` labels Friction Surface Area and keystroke-effort values as modeled; gaze-path output is explicitly "order of modeled salience, not measured fixations".
+- Distinguished measured outcomes from modeled estimates in executive slide decks (`src/reporting/executiveExport.js`): a dedicated "Measured vs Modeled" slide separates deterministic findings from heuristic indices and states what is not claimed (revenue lift, conversion uplift); the fabricated "100% Mechanical Friction Eliminated" and "Zero Friction" claims were replaced with labeled modeled targets.
+
+
 ## 1.16.0 — 2026-09-08
 
 ### Added — Nebula Components Enterprise Platform Suite

package/README.md

@@ -21,7 +21,7 @@ generator, not a Lighthouse wrapper, not an "AI visibility score".
   objectives, interventions, optional connections, reviewers, review policies,
   governed exceptions, semantic review items, sampling plans, and audit schedules — all
   JSON-Schema validated with referential integrity and history-preserving saves.
-- **180 detectors** across 19 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
+- **181 detectors** across 19 namespaces (TECH, CRAWL, ARCH, PAGE, ANS,
   SCHEMA, CWV, GEO, AEO, CLAIM, EVD, LIFE, AGENT, MEAS, EXP, CONF, SEC, LINK,
   CRO), each with remediation, verification, severity, and determinism declared.
 - **Evidence packages** for every run: manifest, findings, report, captured
@@ -210,6 +210,19 @@ citable artifacts verify --input ./portable-run
 citable artifacts import --input ./portable-run
 citable substantiate          # claim/evidence assessment (dry run)
 citable validate              # registry schema + referential integrity
+
+# CRO remediation loop: audit → explain → remediate → verify → hand off
+citable inspect cro <page> --target ./dist
+citable remediate --finding CRO-007 --target src/Form.jsx        # dry run: diff + validation + confidence
+citable remediate --finding CRO-007 --target src/Form.jsx --write # gated; rollback snapshot created
+citable verify remediation --run <run-id> --finding CRO-007 --target src/Form.jsx --apply
+citable kit export --run <run-id> --finding CRO-007 --target src/Form.jsx
+citable check experiment <id> --observed-control 5000 --observed-variant 4980 --days-running 6
+citable verify page /pricing --target ./dist
+citable compatibility
+citable audit edge worker.js --format cloudflare-worker
+citable test visual
+citable corpus benchmark
 ```
 
 ## Repository map
@@ -218,8 +231,8 @@ 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: 27 registries plus findings, runs, observations, release governance, remediation, config, and prompt results |
-| `tests/` | Unit + integration suites; positive/negative fixtures |
+| `schemas/` | JSON Schemas: 29 registries plus findings, runs, observations, release governance, remediation verification, the CLI output envelope, config, and prompt results |
+| `tests/` | Unit + integration suites; positive/negative fixtures; labeled golden benchmark corpus |
 | `docs/` | ADR, traceability matrix, known limitations |
 | `dist/` | Generated distribution packages (run `npm run build:dist`) |
 

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.16.0
+version: 1.17.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -138,9 +138,18 @@ citable corpus evaluate --input <acceptance-corpus.json>
 citable corpus publish --input <acceptance-corpus.json> --output <public-corpus.json>
 citable corpus receipt --run <run-id> [--input <execution-context.json>]
 citable corpus compare-receipts <receipt-a.json> <receipt-b.json>
+citable corpus benchmark [--corpus <dir>] [--output <report.json>]  # labeled golden fixtures → per-detector precision/recall gate
 citable artifacts export <run-id> --output <directory>
 citable artifacts verify --input <directory>
 citable artifacts import --input <directory>
+citable inspect cro <page> --target <dir|url>   # CRO readiness: CTAs, forms, payment-wallet vs authentication readiness, modeled saliency indices
+citable preview cro <page> [--export <file.html>]  # split-screen before/remediated sandbox (layout-contract checked; accessibility-aware)
+citable remediate --finding <id> [--target <file>] [--write]  # production-safe patch: framework detection, unified diff, static validation, confidence gate, rollback snapshot; semantic copy changes always refuse automated write
+citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]  # closed loop: re-run the detector and emit a before/after evidence bundle (schema remediation-verification)
+citable verify page <page> --target <dir|url>   # all detectors scoped to one page; pass = no detector currently reports it, never an outcome guarantee
+citable check experiment <id> [--observed-control N --observed-variant N --days-running N]  # SRM, stopping, power, contamination; lifecycle: planned|running|inconclusive|validated
+citable compatibility   # Node engine, optional adapters, browser, framework, registries, edge size limits
+citable kit export --run <run-id> --finding <id> [--target <file>]  # customer-ready implementation kit (finding, diff, evidence, acceptance tests, deployment, limitations)
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -194,6 +203,43 @@ monitoring interpretation.
 Use `commands/field-validation.md` for acceptance-corpus authorization,
 sanitization, publication refusal, reproducibility, and evidence boundaries.
 
+## CRO remediation loop (audit → explain → remediate → verify → hand off)
+
+The CRO suite completes the loop. Rules that govern every step:
+
+1. **Safe patches only.** `remediate --write` is gated on framework detection,
+   static structural validation, idempotency, and an explicit confidence
+   threshold. Semantic microcopy replacements are refused for automated write
+   (fact ≠ inference): they require a human editorial decision. Every write
+   creates a rollback snapshot under `.citable/remediation/snapshots/`.
+2. **A written patch is not a verified repair.** Run
+   `verify remediation --run <run-id> --finding <id>`. Resolution means the
+   detector no longer reports the same subject — never a conversion guarantee.
+   The verification bundle is schema-validated
+   (`schemas/remediation-verification.schema.json`).
+3. **Payment wallets ≠ authentication.** Apple Pay/Google Pay/PayPal are
+   payment methods; WebAuthn/passkeys are account authentication. Report them
+   separately (`inspect cro` returns `payment_wallet_readiness` and
+   `authentication_readiness`). Never use "biometric readiness" as a claim.
+4. **Modeled indices are labeled.** Friction Surface Area, CTA Conspicuity
+   Index, and gaze-path ordering are heuristic indices over captured DOM
+   conditions — not observed user behavior and not revenue estimates. Slide
+   decks and kits must keep measured (deterministic findings) and modeled
+   (indices, projections) in separate, labeled categories. No latency,
+   speed, or "percentage eliminated" figure may be stated without a
+   documented measurement methodology.
+5. **Referral fragments are untrusted input.** ScentBeacon-style components
+   may match referrer/`:~:text=` against a fixed allowlist to detect the
+   referral state; raw values are never rendered, persisted, or transmitted.
+   Dynamic claim text must come from registry-bound developer props.
+6. **Experiments carry guardrails.** `check experiment` reports SRM, stopping
+   early, underpowered samples, contamination, and unsupported revenue
+   attribution, and derives one lifecycle of `planned`, `running`,
+   `inconclusive`, or `validated` — never "winner".
+7. **Machine-readable output is a contract.** `--json` wraps every command
+   payload in the `citable_output_schema` 1.0 envelope
+   (`schemas/cli-output-envelope.schema.json`).
+
 ## Command workflows
 
 Detailed per-command workflows live in `commands/`. Follow them; they define

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

@@ -1 +1 @@
-1.16.0
+1.17.0

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

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "managedBy": "citable-cli",
   "provider": "codex",
   "providerName": "OpenAI Codex",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.16.0",
+  "sourcePackage": "@nebulacomponents/citable@1.17.0",
   "variantPath": ".agents/skills/citable",
   "agentProfiles": {
     "status": "unsupported",
@@ -58,6 +58,7 @@
     "schemas/browser-evidence-plan.schema.json": "sha256:81ef14f665b4a00f01afb747576faeb06025722e5c15a36eff3d17e59e978851",
     "schemas/canonical-index-import.schema.json": "sha256:ef633662cb30873242ca356443bc4835afe56bb020208e8f42fa47ac8047b66e",
     "schemas/claim.schema.json": "sha256:ce79ccbfa34ece9b7a309a6962522ea06a1f44c468b4c472b5c376554a788537",
+    "schemas/cli-output-envelope.schema.json": "sha256:6964e8f2f43618bfd0d7a3f5344b37ebc26f04779796bb8ff4675b935b6208c3",
     "schemas/common.defs.json": "sha256:ac66081df6b86f652e066ea868edecfcd36cdd1b1c81e55a1e3af880f671b727",
     "schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
     "schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
@@ -77,7 +78,7 @@
     "schemas/exception.schema.json": "sha256:c88985494ec66554330fdc5b65d033527d0005acf41f10798b1e831d171f8944",
     "schemas/experiment.schema.json": "sha256:4b5d16481448597b152269296b67b5776be6f03d8f9afba1833bcee10bf3c05b",
     "schemas/field-validation-metrics.schema.json": "sha256:bd5daeafc1593f1c4707d75180e1feb1e81d9345a57c1f269eadf13c36cb7012",
-    "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
+    "schemas/finding.schema.json": "sha256:1775425b9b989dd4ffc0c607eb9d64e95cad2124f9058f83ef78b0b0030e209f",
     "schemas/fleet.schema.json": "sha256:3bf5772695ae4bb49a8c5fdbedee230ddb1d84aff6a3176eeb41527aca6ef2a5",
     "schemas/funnel.schema.json": "sha256:6c368f29296ac45f5d52bb3a2f95fa935a1f30f3d53aae846156e9aa4c8ec59c",
     "schemas/initiative.schema.json": "sha256:491f6cc022c7ac1f9ea9ac9ddfcd270cb49c390e2601fe1e73aa6192a9e7689a",
@@ -97,6 +98,7 @@
     "schemas/release-manifest.schema.json": "sha256:962be645e790b5f3dc6f6ea455e187492d727dcb91d00f91e4e25b40e2dbc360",
     "schemas/release-state.schema.json": "sha256:9920f68e538915d0d07044f313a9e410775a38ce9bb46a55d9ebe02970784803",
     "schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
+    "schemas/remediation-verification.schema.json": "sha256:b4e4f3ce8d72ef64cdb879a86b6afe9220e2d9e4d13ed3486348cc8ee38e1319",
     "schemas/review-item.schema.json": "sha256:df532a70385d5031bbc18654f3ccb436dc6e8d402ccf987e58f8f7e3ad2fb3f1",
     "schemas/review-policy.schema.json": "sha256:b2d176b1886f78c384b25532a0c3eb18548dfbd17f362a305e622bab562a1d04",
     "schemas/reviewer.schema.json": "sha256:3716697b752575a1277f2c2b318b1f2565de02bf9dce2a0c165567ab5330d18b",
@@ -108,9 +110,9 @@
     "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
     "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
     "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
-    "SKILL.md": "sha256:5a5dbae5d5af91f58dddf8fd2a1ed71c1740f81e5813b91e9329850ae6a46301",
+    "SKILL.md": "sha256:f39e0863bbcaf178c46afed4ae95834451d96e6b1d07af3883733de707e692ea",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:46081fd90571a274160408ebc81fc91b78ffca4049d477998e3b6909ac245e05"
+    "VERSION": "sha256:00afc49f1599e59129a59b64c2b019de3fe35300c05bb9d96cb25002576ff43b"
   },
-  "treeHash": "sha256:ac0e50b9957821d1e1e8efe33b0aa22314eca5d1fdcfc6ac90f017c2ec26d4b3"
+  "treeHash": "sha256:e4c2165da7ae3106c3bfa358445d2e51dd974f656d058bc03f22fd0604d2d4b3"
 }

package/dist/universal/.agents/skills/citable/schemas/cli-output-envelope.schema.json

@@ -0,0 +1,30 @@
+{
+  "$id": "citable://schemas/cli-output-envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLI JSON output envelope",
+  "description": "Stable envelope for every `citable <command> --json` output. Consumers read `citable_output_schema` for envelope compatibility and read command data from `result`. The envelope version changes only on breaking envelope changes; command payloads evolve backward-compatibly inside result.",
+  "type": "object",
+  "required": ["citable_output_schema", "tool_version", "generated_at", "result"],
+  "properties": {
+    "citable_output_schema": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Envelope contract version. 1.0 is the initial stable contract."
+    },
+    "tool_version": {
+      "type": "string",
+      "description": "Citable package version that produced the output."
+    },
+    "command": {
+      "type": ["string", "null"],
+      "description": "Top-level command that produced this output."
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of when the output was generated."
+    },
+    "result": {
+      "description": "Command-specific payload. Structure is defined per command and evolves backward-compatibly within an envelope major version."
+    }
+  }
+}

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

@@ -257,6 +257,75 @@
         }
       }
     },
+    "provenance": {
+      "type": "object",
+      "required": [
+        "detector_version",
+        "tool_version",
+        "evidence_source",
+        "methodology",
+        "revalidation_required"
+      ],
+      "properties": {
+        "detector_version": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "tool_version": {
+          "type": "string"
+        },
+        "source_url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "source_file": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_selector": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "evidence_source": {
+          "type": "string",
+          "enum": [
+            "dom_parse",
+            "registry",
+            "registry+dom_parse",
+            "controlled_observation",
+            "configuration"
+          ]
+        },
+        "viewport": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "viewport_note": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "methodology": {
+          "type": "string"
+        },
+        "revalidation_required": {
+          "type": "string",
+          "enum": [
+            "on_next_audit",
+            "human_review_before_action"
+          ]
+        }
+      }
+    },
     "status": {
       "type": "object",
       "required": [

package/dist/universal/.agents/skills/citable/schemas/remediation-verification.schema.json

@@ -0,0 +1,98 @@
+{
+  "$id": "citable://schemas/remediation-verification.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Remediation verification record",
+  "description": "Closed-loop evidence that a detector finding was addressed: before-run finding, applied patch, re-run detector result, and verdict. Proves only that the detector no longer reports the same subject; it never proves a conversion or outcome guarantee.",
+  "type": "object",
+  "required": [
+    "verification_id", "timestamp", "status", "tool_version",
+    "source_run_id", "detector_id", "subject", "verdict",
+    "provenance", "limitations"
+  ],
+  "properties": {
+    "verification_id": { "type": "string", "pattern": "^VR-[0-9]{14,20}-[a-z0-9]{2,8}$" },
+    "timestamp": { "type": "string" },
+    "status": { "type": "string", "enum": ["verified", "not_resolved", "blocked", "patch_refused"] },
+    "tool_version": { "type": "string" },
+    "repository_commit": { "type": ["string", "null"] },
+    "source_run_id": { "type": ["string", "null"], "minLength": 1 },
+    "recheck_run_id": { "type": ["string", "null"] },
+    "detector_id": { "type": ["string", "null"] },
+    "subject": {
+      "type": ["object", "null"],
+      "properties": {
+        "type": { "type": "string" },
+        "identifier": { "type": ["string", "null"] }
+      }
+    },
+    "verdict": {
+      "type": "object",
+      "required": ["resolved"],
+      "properties": {
+        "resolved": { "type": "boolean" },
+        "before_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "after_finding_ids": { "type": "array", "items": { "type": "string" } },
+        "new_regressions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["finding_id", "detector_id", "severity", "summary"],
+            "properties": {
+              "finding_id": { "type": "string" },
+              "detector_id": { "type": "string" },
+              "severity": { "type": "string" },
+              "summary": { "type": "string" }
+            }
+          }
+        },
+        "resolution_definition": {
+          "type": "string",
+          "description": "States the exact resolution criterion used; detector absence is not an outcome guarantee."
+        }
+      }
+    },
+    "patch": {
+      "type": ["object", "null"],
+      "properties": {
+        "target_file": { "type": "string" },
+        "framework": { "type": ["string", "null"] },
+        "patcher_class": { "type": ["string", "null"] },
+        "confidence": { "type": ["number", "null"] },
+        "validation_passed": { "type": "boolean" },
+        "applied": { "type": "boolean" },
+        "refusal_reason": { "type": ["string", "null"] },
+        "rollback_snapshot": { "type": ["string", "null"] },
+        "before_sha256": { "type": ["string", "null"] },
+        "after_sha256": { "type": ["string", "null"] }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["command", "recheck_target", "detectors_run"],
+      "properties": {
+        "command": { "type": "string" },
+        "recheck_target": { "type": ["string", "null"] },
+        "detectors_run": { "type": "array", "items": { "type": "string" } },
+        "detectors_skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "detector_id": { "type": "string" },
+              "reason": { "type": "string" }
+            }
+          }
+        },
+        "recheck_errors": { "type": "array", "items": { "type": "string" } },
+        "recheck_warnings": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "bundle_dir": { "type": ["string", "null"] },
+    "bundle_checksums": { "type": "object" }
+  }
+}

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

@@ -1,9 +1,9 @@
 {
   "name": "citable-agent-profiles",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "managedBy": "citable-cli",
   "provider": "claude",
-  "sourcePackage": "@nebulacomponents/citable@1.16.0",
+  "sourcePackage": "@nebulacomponents/citable@1.17.0",
   "files": {
     "citable-auditor.md": "sha256:06fe8d84834b2c09b7e7083aa6f57e94e837e0643dbe4ead4bbecf651fb41cad",
     "citable-semantic-reviewer.md": "sha256:77582263a048ea41ae3f7ee326dbd036222fab81ed83bda98034ec83ee21ef2e"

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.16.0
+version: 1.17.0
 ---
 
 # Citable — evidence and change control for search and AI citation readiness
@@ -138,9 +138,18 @@ citable corpus evaluate --input <acceptance-corpus.json>
 citable corpus publish --input <acceptance-corpus.json> --output <public-corpus.json>
 citable corpus receipt --run <run-id> [--input <execution-context.json>]
 citable corpus compare-receipts <receipt-a.json> <receipt-b.json>
+citable corpus benchmark [--corpus <dir>] [--output <report.json>]  # labeled golden fixtures → per-detector precision/recall gate
 citable artifacts export <run-id> --output <directory>
 citable artifacts verify --input <directory>
 citable artifacts import --input <directory>
+citable inspect cro <page> --target <dir|url>   # CRO readiness: CTAs, forms, payment-wallet vs authentication readiness, modeled saliency indices
+citable preview cro <page> [--export <file.html>]  # split-screen before/remediated sandbox (layout-contract checked; accessibility-aware)
+citable remediate --finding <id> [--target <file>] [--write]  # production-safe patch: framework detection, unified diff, static validation, confidence gate, rollback snapshot; semantic copy changes always refuse automated write
+citable verify remediation --run <run-id> --finding <id> [--target <file>] [--apply]  # closed loop: re-run the detector and emit a before/after evidence bundle (schema remediation-verification)
+citable verify page <page> --target <dir|url>   # all detectors scoped to one page; pass = no detector currently reports it, never an outcome guarantee
+citable check experiment <id> [--observed-control N --observed-variant N --days-running N]  # SRM, stopping, power, contamination; lifecycle: planned|running|inconclusive|validated
+citable compatibility   # Node engine, optional adapters, browser, framework, registries, edge size limits
+citable kit export --run <run-id> --finding <id> [--target <file>]  # customer-ready implementation kit (finding, diff, evidence, acceptance tests, deployment, limitations)
 ```
 
 Audit scopes: `technical seo aeo geo architecture entity claims evidence schema
@@ -194,6 +203,43 @@ monitoring interpretation.
 Use `commands/field-validation.md` for acceptance-corpus authorization,
 sanitization, publication refusal, reproducibility, and evidence boundaries.
 
+## CRO remediation loop (audit → explain → remediate → verify → hand off)
+
+The CRO suite completes the loop. Rules that govern every step:
+
+1. **Safe patches only.** `remediate --write` is gated on framework detection,
+   static structural validation, idempotency, and an explicit confidence
+   threshold. Semantic microcopy replacements are refused for automated write
+   (fact ≠ inference): they require a human editorial decision. Every write
+   creates a rollback snapshot under `.citable/remediation/snapshots/`.
+2. **A written patch is not a verified repair.** Run
+   `verify remediation --run <run-id> --finding <id>`. Resolution means the
+   detector no longer reports the same subject — never a conversion guarantee.
+   The verification bundle is schema-validated
+   (`schemas/remediation-verification.schema.json`).
+3. **Payment wallets ≠ authentication.** Apple Pay/Google Pay/PayPal are
+   payment methods; WebAuthn/passkeys are account authentication. Report them
+   separately (`inspect cro` returns `payment_wallet_readiness` and
+   `authentication_readiness`). Never use "biometric readiness" as a claim.
+4. **Modeled indices are labeled.** Friction Surface Area, CTA Conspicuity
+   Index, and gaze-path ordering are heuristic indices over captured DOM
+   conditions — not observed user behavior and not revenue estimates. Slide
+   decks and kits must keep measured (deterministic findings) and modeled
+   (indices, projections) in separate, labeled categories. No latency,
+   speed, or "percentage eliminated" figure may be stated without a
+   documented measurement methodology.
+5. **Referral fragments are untrusted input.** ScentBeacon-style components
+   may match referrer/`:~:text=` against a fixed allowlist to detect the
+   referral state; raw values are never rendered, persisted, or transmitted.
+   Dynamic claim text must come from registry-bound developer props.
+6. **Experiments carry guardrails.** `check experiment` reports SRM, stopping
+   early, underpowered samples, contamination, and unsupported revenue
+   attribution, and derives one lifecycle of `planned`, `running`,
+   `inconclusive`, or `validated` — never "winner".
+7. **Machine-readable output is a contract.** `--json` wraps every command
+   payload in the `citable_output_schema` 1.0 envelope
+   (`schemas/cli-output-envelope.schema.json`).
+
 ## Command workflows
 
 Detailed per-command workflows live in `commands/`. Follow them; they define

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

@@ -1 +1 @@
-1.16.0
+1.17.0

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

@@ -1,11 +1,11 @@
 {
   "name": "citable",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "managedBy": "citable-cli",
   "provider": "claude",
   "providerName": "Claude Code",
   "scope": "bundle",
-  "sourcePackage": "@nebulacomponents/citable@1.16.0",
+  "sourcePackage": "@nebulacomponents/citable@1.17.0",
   "variantPath": ".claude/skills/citable",
   "agentProfiles": {
     "status": "available",
@@ -63,6 +63,7 @@
     "schemas/browser-evidence-plan.schema.json": "sha256:81ef14f665b4a00f01afb747576faeb06025722e5c15a36eff3d17e59e978851",
     "schemas/canonical-index-import.schema.json": "sha256:ef633662cb30873242ca356443bc4835afe56bb020208e8f42fa47ac8047b66e",
     "schemas/claim.schema.json": "sha256:ce79ccbfa34ece9b7a309a6962522ea06a1f44c468b4c472b5c376554a788537",
+    "schemas/cli-output-envelope.schema.json": "sha256:6964e8f2f43618bfd0d7a3f5344b37ebc26f04779796bb8ff4675b935b6208c3",
     "schemas/common.defs.json": "sha256:ac66081df6b86f652e066ea868edecfcd36cdd1b1c81e55a1e3af880f671b727",
     "schemas/competitor.schema.json": "sha256:2f6fd7e4543846bde56ff4dc62bb41fa366889787b794a7cdb0bff1a3392e591",
     "schemas/config.schema.json": "sha256:a87f3bb0087de09035b9f2dafea66e32e4fcc2e3e329abcd0fd8a5ec33318f2a",
@@ -82,7 +83,7 @@
     "schemas/exception.schema.json": "sha256:c88985494ec66554330fdc5b65d033527d0005acf41f10798b1e831d171f8944",
     "schemas/experiment.schema.json": "sha256:4b5d16481448597b152269296b67b5776be6f03d8f9afba1833bcee10bf3c05b",
     "schemas/field-validation-metrics.schema.json": "sha256:bd5daeafc1593f1c4707d75180e1feb1e81d9345a57c1f269eadf13c36cb7012",
-    "schemas/finding.schema.json": "sha256:85907cd04cd8d2fe24a1e618e0df7160f6d56aa1818db501f345aebce5eb5edb",
+    "schemas/finding.schema.json": "sha256:1775425b9b989dd4ffc0c607eb9d64e95cad2124f9058f83ef78b0b0030e209f",
     "schemas/fleet.schema.json": "sha256:3bf5772695ae4bb49a8c5fdbedee230ddb1d84aff6a3176eeb41527aca6ef2a5",
     "schemas/funnel.schema.json": "sha256:6c368f29296ac45f5d52bb3a2f95fa935a1f30f3d53aae846156e9aa4c8ec59c",
     "schemas/initiative.schema.json": "sha256:491f6cc022c7ac1f9ea9ac9ddfcd270cb49c390e2601fe1e73aa6192a9e7689a",
@@ -102,6 +103,7 @@
     "schemas/release-manifest.schema.json": "sha256:962be645e790b5f3dc6f6ea455e187492d727dcb91d00f91e4e25b40e2dbc360",
     "schemas/release-state.schema.json": "sha256:9920f68e538915d0d07044f313a9e410775a38ce9bb46a55d9ebe02970784803",
     "schemas/remediation-spec.schema.json": "sha256:6fe8cb773702862ba6d261198bb5cc2dca3eca0a2310a60ebddd04377654df8d",
+    "schemas/remediation-verification.schema.json": "sha256:b4e4f3ce8d72ef64cdb879a86b6afe9220e2d9e4d13ed3486348cc8ee38e1319",
     "schemas/review-item.schema.json": "sha256:df532a70385d5031bbc18654f3ccb436dc6e8d402ccf987e58f8f7e3ad2fb3f1",
     "schemas/review-policy.schema.json": "sha256:b2d176b1886f78c384b25532a0c3eb18548dfbd17f362a305e622bab562a1d04",
     "schemas/reviewer.schema.json": "sha256:3716697b752575a1277f2c2b318b1f2565de02bf9dce2a0c165567ab5330d18b",
@@ -113,9 +115,9 @@
     "schemas/source-identity-chain.schema.json": "sha256:a65d9c12eaed1bd6b637c66a2f9362c17287fdfcb454d8676fb611d2d28aa019",
     "schemas/variance.schema.json": "sha256:68389f64f0a3be13ff8951e8eefba9a5c31d0738325cb47e37c1a8435bea48f0",
     "scripts/README.md": "sha256:9eee4e8beb4579a183bd714c9dd24b83abd020753eada5caeffae004739d60b5",
-    "SKILL.md": "sha256:5a5dbae5d5af91f58dddf8fd2a1ed71c1740f81e5813b91e9329850ae6a46301",
+    "SKILL.md": "sha256:f39e0863bbcaf178c46afed4ae95834451d96e6b1d07af3883733de707e692ea",
     "templates/finding-review.md": "sha256:b270a83d3f015150aac80249ae9314979c0befea39ff92ec455f9a5aaa73404c",
-    "VERSION": "sha256:46081fd90571a274160408ebc81fc91b78ffca4049d477998e3b6909ac245e05"
+    "VERSION": "sha256:00afc49f1599e59129a59b64c2b019de3fe35300c05bb9d96cb25002576ff43b"
   },
-  "treeHash": "sha256:ac0e50b9957821d1e1e8efe33b0aa22314eca5d1fdcfc6ac90f017c2ec26d4b3"
+  "treeHash": "sha256:e4c2165da7ae3106c3bfa358445d2e51dd974f656d058bc03f22fd0604d2d4b3"
 }

package/dist/universal/.claude/skills/citable/schemas/cli-output-envelope.schema.json

@@ -0,0 +1,30 @@
+{
+  "$id": "citable://schemas/cli-output-envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLI JSON output envelope",
+  "description": "Stable envelope for every `citable <command> --json` output. Consumers read `citable_output_schema` for envelope compatibility and read command data from `result`. The envelope version changes only on breaking envelope changes; command payloads evolve backward-compatibly inside result.",
+  "type": "object",
+  "required": ["citable_output_schema", "tool_version", "generated_at", "result"],
+  "properties": {
+    "citable_output_schema": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Envelope contract version. 1.0 is the initial stable contract."
+    },
+    "tool_version": {
+      "type": "string",
+      "description": "Citable package version that produced the output."
+    },
+    "command": {
+      "type": ["string", "null"],
+      "description": "Top-level command that produced this output."
+    },
+    "generated_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of when the output was generated."
+    },
+    "result": {
+      "description": "Command-specific payload. Structure is defined per command and evolves backward-compatibly within an envelope major version."
+    }
+  }
+}