@nextcommerce/campaigns-os 1.34.1 → 1.37.1

package/docs/progress-snapshots.md

@@ -0,0 +1,142 @@
+# Minimal progress observations
+
+Candidate release **1.36.0** adds the portable `@nextcommerce/campaigns-os/progress`
+export and `schemas/campaigns-os-progress-snapshot.v0.schema.json`. The currently
+published install example does not include this feature. Progress is a compact
+observation of the existing lifecycle, not a second workflow or proof of readiness.
+
+`next --packet <packet>` records the canonical picker result after the same doctor
+checks that supply its continuation and gates. Agents run `next` after setup,
+assembly, polish and preview deployment so those committed stage reports become
+visible. The CLI `build` command prepares inputs and runs doctor; it does not build
+or deploy the campaign. Preview's existing stage is `deploy`. Arbitrary edits are
+not tracked. `qa run --packet <packet>` observes its successfully committed or
+unchanged QA report before the existing closeout: ready QA closes its run once,
+blocked QA keeps it open. A progress delivery cannot close a run.
+
+## What is shared
+
+The strict v0 object carries its schema, package version, observation timestamp,
+producer (`next` or `qa`), opaque progress stream and sequence, prior snapshot ID,
+content digest, Map ID and separate revision/spec/build hashes. Six independent
+stage records retain observed status and explicit build binding. Continuation
+retains the canonical stage, blocked/divergent flags, fixed action IDs and gate
+states. Preview carries only presence and a hash of the URL. An optional QA block
+retains the exact verdict ID, disposition (including `ready_with_exceptions`),
+binding and publication state. Publication failure does not invalidate a locally
+retained verdict; recovery uses `qa publish`, without repeating an order.
+
+No commands, prompts, free text, content, local paths, URLs, query strings,
+credentials, order values or customer payloads enter the wire. Unknown vocabulary
+becomes a fixed `unknown` marker and cannot imply a passing continuation. A
+stage's observed `completed` status is a ledger claim, not independent verification.
+Only matching fingerprints carry `matching`; absent or unverifiable binding is
+`unconfirmed`. A current local output hash never proves a deployment is current.
+
+The identity algorithms are deliberately different:
+
+- `map-store-v1` retains the original saved Map hash. A fresh Map fetch records
+  that hash and the fetched local semantic baseline in Build Context intake.
+  Saved revision alignment is `aligned` only while the local spec still matches
+  that baseline and the context names this packet and Map. Existing contexts,
+  offline caches and local exports without that provenance remain `unconfirmed`.
+  The saved hash may still be retained as identity; it alone proves no alignment.
+- `campaign-spec-material-v1` hashes recursively key-sorted JSON after removing
+  top-level `spec_identity`, `slug`, `map_id` and `saved_at`, as existing
+  `specMaterialHash` does. It includes lifecycle and parent Map fields that the
+  saved Map producer excludes. It must never be compared as a Map-store hash.
+  Assembly Report `identity.spec_hash` is a raw-byte hash and is not this value.
+- `sha256-manifest/v1` is the existing doctor's output fingerprint: SHA-256 of
+  the sorted relative-path and file-SHA-256 manifest under the built route.
+  Reported assembly/QA binding uses the doctor's actual observed output and its
+  recorded-fingerprint comparison. Missing output remains nullable/unconfirmed.
+
+Different Map revisions, local specs, builds, packet/context/report bindings and
+endpoint scopes have independent streams. Completed stages cannot be combined
+across them. A progress stream is independent of a run-session ID.
+
+## Capture and delivery
+
+Sanitized immutable snapshots are written under the target repository's
+`.campaign-runtime/progress/` before any request. Allocation uses an exclusive
+local lock with a process owner. Dead owners are recovered through an exclusive
+recovery claim and an atomic rename; a live process is never evicted. An ownerless
+crash gap is recoverable after ten seconds. If recovery itself is interrupted,
+capture fails closed: stop all Campaigns OS writers for that target, then remove
+the abandoned `.allocation-lock` directory in the affected progress scope before
+retrying `next`. Do not remove a lock while a writer is active.
+
+An unchanged projection reuses its ID, timestamp and sequence. Identity
+changes start a new stream. Each local scope retains at most 32 snapshots and
+separate remit metadata; retention can leave an incomplete history. There is no
+daemon. A later observation retries its current pending delivery; old pending
+snapshots remain in the bounded local history, without background sends.
+
+`--no-write` disables both capture and delivery. `--no-remit` keeps capture local.
+`--no-run-session` does not start a session. A missing/invalid Map ID keeps the
+observation local with `map_id_missing`; a missing campaign key similarly yields
+`campaign_key_missing`. Capture or delivery failures never alter the lifecycle
+result or exit status.
+Capture may wait up to 1.5 seconds for allocation. Delivery is awaited within
+its separate two-second network budget. Unchanged lifecycle results mean the
+command's output and status remain unchanged; these bounded waits can add latency.
+
+The planned ops receiver is `POST /api/progress`. Destination precedence is an
+explicit `--proxy-base`, then the bound Build Context's `intake.proxy_base`, then
+the canonical NEXT endpoint only when there is no source binding. An invalid or
+foreign source binding fails closed, including a context without a nonempty
+matching packet pointer. An explicit endpoint override remains independent of
+that context, and cannot confirm its saved revision.
+
+HTTPS and plain HTTP loopback are accepted;
+userinfo, query, fragment and other protocols are refused. Redirects are refused.
+The existing campaign-key resolver supplies `X-Campaign-Key`; keys never enter
+snapshots or metadata.
+
+The same telemetry on/off choice governs sharing. Canonical delivery defaults on;
+explicit off, malformed environment/configuration and scope mismatch keep delivery
+off. Consent off still permits the sanitized local capture and sends no request.
+Noncanonical progress delivery requires an explicit matching scoped file
+opt-in (`telemetry on --proxy-base <endpoint>`). Unlike existing Run Record remit,
+unscoped environment ON cannot bypass scope for progress; it yields
+`scoped_consent_required`. Minimal stage observations are intended to be visible
+in Workspace. This producer does not implement the receiver or Workspace UI.
+
+Delivery uses a total two-second budget, at most one initial request and one retry
+for transport errors, 429 or 5xx. Both requests use identical canonical JSON bytes,
+ID and timestamp. A response body is bounded to 4 KiB. A 2xx or 409 succeeds only
+with `{ "ok": true, "snapshot_id": "<id>", "digest": "<same-id>" }`. Other
+400/401/403/409 answers and nonmatching acknowledgments remain failed; a conflict
+never silently counts as stored. Response error text is never copied to metadata.
+
+## Portable consumption
+
+```js
+import {
+  verifyProgressSnapshot, groupProgressHistories, progressStorageKey,
+} from '@nextcommerce/campaigns-os/progress';
+
+const checked = await verifyProgressSnapshot(snapshot);
+const histories = await groupProgressHistories(snapshots);
+const key = progressStorageKey(snapshot, scopeHash);
+```
+
+The export uses standard Web Crypto and TextEncoder; it has no Node, filesystem
+or network dependency. `validateProgressSnapshot` checks bounded strict shape and
+binding invariants; `verifyProgressSnapshot` also verifies the content digest.
+`snapshot_id` hashes recursively key-sorted JSON of every field except itself.
+Canonical transport JSON includes the ID, with no whitespace or newline.
+The exported schema and supported example fixture agree byte-for-byte in tests.
+
+`groupProgressHistories` accepts at most 256 snapshots, groups whole observations
+by complete identity plus stream, removes exact duplicate IDs and sorts sequences.
+Groups are `conflicted`, `incomplete`, `unconfirmed` or `observed`. It neither
+chooses a lifecycle stage nor merges completion claims. `observed` confers no
+receiver trust or readiness. Invalid members are rejected with fixed reason codes.
+
+The planned immutable receiver key is
+`progress:v0:<scope-hex>:<map-id>:<revision-hex>:<stream>:<sequence>:<digest-hex>`.
+`progressStorageKey` returns null without a valid shape, scope hash, Map or saved
+revision. A key match identifies scope; it is not authentication or trust. The
+receiver must verify the digest and authorized Map scope and stamp its own trust.
+Unknown, incomplete or conflicted histories must never yield a ready workspace.

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.34.1`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.1`.
 
 ## What this is
 

package/docs/supported-surface.md

@@ -14,7 +14,7 @@ implementation detail, however stable it looks.
 | Surface | Contract | Change discipline |
 |---|---|---|
 | `schemas/*.schema.json` (all of them) | The portable contract catalog: CampaignSpec, Design Source Package, Build Packet, Build Context, Assembly Report, Doctor Output, sidecar-bundle conformance, Run Record, Workflow Finding, Build Brief, Source-HTML Manifest, Tooling Orientation, Release Ledger, QA Verdict, the QA Verdict sidecar projection, Runtime Recipe, and the legacy-migration inventory/plan/receipt trio. | Hashed. Any content change requires updating the recorded hash **and** bumping `surface_version` in the same PR. A shape change that alters meaning gets a new schema-version const — one version identifier must never cover two shapes (the 2026-08 assembly-report drift is the incident this rule encodes). Additions to an open `v0` schema are expected and consumers must tolerate unknown fields; the security-sensitive legacy-migration schemas are closed, so additions there require a new lineage. 1.28.0 (RL entry `surface_version: 1.28.0`, breaking) removed the two required Build Packet booleans `qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed` (nothing read them; test orders run from `--test-order <mode>` alone), added `local-serve` to the `deploy.target` enum, and added the optional `remit_result` / `remit_base_kind` fields to the Run Record. 1.30.0 (additive) added the optional `data_layer` record to the QA Verdict's `test_orders[]` entries — the order's `dl_purchase` reading (#325). 1.33.0 (additive) added the optional `qa_verdict_publish` block to the Run Record — which verdict was posted to the QA portal, by `qa run` or `qa publish`, and what the portal answered, in the `remit_result` vocabulary (#328). |
-| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts four registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, and `built_output.upsell_selector_scope`. `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
+| CLI commands: `start`, `prepare-build`, `build`, `polish`, `checkpoint`, `page-kit`, `spec`, `doctor`, `bundle`, `next`, `theme`, `tooling`, `install-skills`, `install-agent-context`, `validate-assembly-report`, `telemetry`, `standardize`, `qa`, `findings`, `run-record`, `run`, `sdk`, `demo` | Scriptable entry points. The founding list (1.0.0) was the argv surface Campaigns Agent's remit fixture pins; 1.25.0 adds the partner entry path the public guides instruct — `install-skills` (skill install), `tooling status` (preflight), `next --packet` (the runtime cursor) — plus `theme`, `install-agent-context`, `validate-assembly-report`, and `telemetry`, since consent is part of the partner contract. `validate-build-packet`, formerly an undocumented and unsupported alias of `doctor`, was removed in 1.25.0+agent.7 (RL-0036) and now gets the unknown-command error; use `doctor`. `standardization-report`, a supported but redundant second spelling of `standardize` — same flags, same output, same exit codes — was removed in 1.27.0 and now gets the same unknown-command error; use `standardize`. Removing a supported command is a breaking change and is why that release moved the minor. `bundle check` validates the canonical JSON readback set and makes QA required only under `--require-qa`. `polish capture` owns page-load evidence production. `checkpoint waive` currently accepts four registered gates: `page_kit.store_profile`, `page_kit.sdk_version`, `polish.hidden_eager_media`, and `built_output.upsell_selector_scope`. `page-kit sync` (added in 1.29.0) writes the CampaignSpec's Store Profile fields and SDK pin into the target's `_data/campaigns.json` entry — the repair the first two gates name — and is the only `page-kit` subcommand. `spec derive` (added in 1.31.0) is the reverse write for the repo-derived field class (#432): the target's SDK pin, page routes and analytics ids into the packet's local CampaignSpec; it is the only `spec` subcommand, and the `page_kit.sdk_version.repo_newer` advisory names it; its `--write-map` flag (1.33.0+agent.2) also records the derived pin in the saved Map's Build hints field through the proxy Worker, never moving a Map pin backwards. `qa publish` (added in 1.33.0) posts an already-stored verdict to the QA portal without a re-run or an order, refusing a stale `spec_hash` or a verdict its Run Record already records as published (#328). Within Polish, only the broader Source Freshness waiver remains on its existing report lane; theme and QA decisions also retain their existing lanes. | Any change to this list — adding, renaming, or removing a command — bumps `surface_version` in the same PR, and since 1.25.0 `check-supported-surface.mjs --base` enforces that (before, only hashed and named entries owed a bump, so `checkpoint` landed unbumped). Subcommands, registered gates, and flags may grow freely beneath a listed command. Removing a listed command from dispatch fails the gate outright. Do not infer support for an unregistered checkpoint from the top-level command. |
 | `sdk storage-check` and `docs/sdk-storage-compatibility.md` | Read-only AST compatibility report for explicitly scoped tracked campaign HTML/JS before an SDK bump; consumes the supplied SDK-owned manifest and records its SHA-256 and verified or unverified local Git provenance. Incompatible and unknown findings exit 2; a clean scan is static source evidence only. | Additive supported CLI and named documentation; no automatic merchant integration repair. |
 | `bin/campaigns-os.mjs` (`campaigns-os`) | The CLI entry itself. | Declared in `package.json` `bin`; the gate fails if it disappears. |
 | Package export `./campaign-spec` | The versioned campaign-spec rule registry, consumed as `@nextcommerce/campaigns-os` (pinned by consumers' lockfiles; lockstep policy — ADR-003 in the ops repo). | Behavior-guarded from the consumer side by their contract tests; the export path itself is gated here. |
@@ -82,3 +82,15 @@ the package a consumer installs."
    the PR body — downstream pins (Campaigns Agent context spine, ops-repo
    `public-contracts.manifest.json`) update on their own cadence against a
    version they can see move.
+
+Candidate 1.36.0 adds the portable `./progress` export, its strict v0 JSON schema,
+[progress observation reference](progress-snapshots.md), and supported example
+fixture. Observations preserve canonical continuation and separate Map/spec/build
+identities; consumers must not treat history presence or scope-key matching as
+readiness or trust.
+
+Candidate 1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
+a hashed `demo/apollo-v0/provenance.json` and named attribution notice. The command
+exclusively creates a new target with validated inert pages. Its internal static
+files are covered by the provenance output hashes; they are not independent
+consumer interfaces. No campaign proof or session authority is granted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.34.1",
+  "version": "1.37.1",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,12 @@
     "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": "./schemas/campaigns-os-legacy-migration-inventory.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-plan.v0.schema.json",
     "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json": "./schemas/campaigns-os-legacy-provisioning-receipt.v0.schema.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./progress": {
+      "import": "./src/progress.mjs",
+      "default": "./src/progress.mjs"
+    },
+    "./schemas/campaigns-os-progress-snapshot.v0.schema.json": "./schemas/campaigns-os-progress-snapshot.v0.schema.json"
   },
   "scripts": {
     "campaigns-os": "node ./bin/campaigns-os.mjs",
@@ -134,6 +139,11 @@
     "compatibility.json",
     "AGENTS.md",
     "CHANGELOG.md",
-    "docs/sdk-storage-compatibility.md"
+    "docs/sdk-storage-compatibility.md",
+    "docs/activation-and-evidence.md",
+    "docs/diagnostics.md",
+    "docs/progress-snapshots.md",
+    "demo",
+    "docs/demo-preview.md"
   ]
 }

package/schemas/campaign-runtime-build-context.v0.schema.json

@@ -24,6 +24,48 @@
       },
       "description": "Context-relative reference to the normalized Design Source Package. sha256 hashes the exact artifact bytes; material_fingerprint drives freshness gates."
     },
+    "intake": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "saved_map_revision": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "map_id",
+                "hash",
+                "algorithm",
+                "local_spec_material_hash"
+              ],
+              "properties": {
+                "map_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "hash": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "algorithm": {
+                  "const": "map-store-v1"
+                },
+                "local_spec_material_hash": {
+                  "type": "string",
+                  "pattern": "^sha256:[0-9a-f]{64}$"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
     "spec": {
       "type": "object",
       "required": ["path", "hash", "active_pages"],

package/schemas/campaigns-os-progress-snapshot.v0.schema.json

@@ -0,0 +1,370 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/campaigns-os-progress-snapshot.v0.schema.json",
+  "title": "Campaigns OS minimal progress observation v0",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "snapshot_id",
+    "stream_id",
+    "sequence",
+    "previous_snapshot_id",
+    "observed_at",
+    "package_version",
+    "producer",
+    "identity",
+    "stages",
+    "preview",
+    "continuation",
+    "qa"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "campaigns-os-progress-snapshot/v0"
+    },
+    "snapshot_id": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "stream_id": {
+      "type": "string",
+      "pattern": "^progress_[0-9a-f]{32}$"
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647
+    },
+    "previous_snapshot_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "observed_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "package_version": {
+      "type": "string",
+      "pattern": "^\\d{1,6}\\.\\d{1,6}\\.\\d{1,6}$"
+    },
+    "producer": {
+      "enum": [
+        "next",
+        "qa"
+      ]
+    },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "map_id",
+        "map_revision_hash",
+        "map_revision_algorithm",
+        "saved_revision_alignment",
+        "local_spec_material_hash",
+        "local_spec_material_algorithm",
+        "build_fingerprint",
+        "build_fingerprint_algorithm"
+      ],
+      "properties": {
+        "map_id": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[A-Za-z0-9_-]{1,64}$"
+        },
+        "map_revision_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "map_revision_algorithm": {
+          "const": "map-store-v1"
+        },
+        "saved_revision_alignment": {
+          "enum": [
+            "aligned",
+            "unconfirmed"
+          ]
+        },
+        "local_spec_material_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "local_spec_material_algorithm": {
+          "const": "campaign-spec-material-v1"
+        },
+        "build_fingerprint": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "build_fingerprint_algorithm": {
+          "const": "sha256-manifest/v1"
+        }
+      }
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 6,
+      "maxItems": 6,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "stage",
+          "status",
+          "build_binding",
+          "source_build_fingerprint"
+        ],
+        "properties": {
+          "stage": {
+            "enum": [
+              "prepare_build",
+              "setup",
+              "assembly",
+              "polish",
+              "deploy",
+              "qa"
+            ]
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "required",
+              "blocked",
+              "completed",
+              "completed_with_warnings",
+              "skipped",
+              "unknown"
+            ]
+          },
+          "build_binding": {
+            "enum": [
+              "matching",
+              "unconfirmed"
+            ]
+          },
+          "source_build_fingerprint": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "pattern": "^sha256:[0-9a-f]{64}$"
+          }
+        }
+      }
+    },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "present",
+        "url_hash"
+      ],
+      "properties": {
+        "present": {
+          "type": "boolean"
+        },
+        "url_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        }
+      }
+    },
+    "continuation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "stage",
+        "blocked",
+        "divergent",
+        "action_ids",
+        "gates"
+      ],
+      "properties": {
+        "stage": {
+          "enum": [
+            "prepare-build",
+            "doctor-blocked",
+            "setup",
+            "build",
+            "polish",
+            "deploy",
+            "qa",
+            "done",
+            "unknown"
+          ]
+        },
+        "blocked": {
+          "type": "boolean"
+        },
+        "divergent": {
+          "type": "boolean"
+        },
+        "action_ids": {
+          "type": "array",
+          "maxItems": 64,
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "doctor_recheck",
+              "restore_prepare_build_binding",
+              "recheck",
+              "rerun_prepare_build",
+              "divergence_inspect",
+              "setup_skill",
+              "build_skill",
+              "build_local_proof",
+              "build_production_parity",
+              "polish_skill",
+              "deploy",
+              "advance",
+              "install_browser",
+              "qa_run",
+              "run_end",
+              "run_record_present",
+              "run_record_remit_recovery",
+              "run_record_closeout",
+              "purchase_proof_unknown",
+              "theme_gate.starter_palette_blocks_qa",
+              "theme_gate.brand_contract_unreadable",
+              "theme_gate.theme_generate",
+              "theme_gate.apply_brand_layer",
+              "theme_gate.waive_theme",
+              "theme_gate.fix_load_order",
+              "polish_gate.rerun_build",
+              "polish_gate.run_polish",
+              "polish_gate.repair_waiver",
+              "checkpoint.page_kit.sdk_version.repair_spec",
+              "checkpoint.page_kit.sdk_version.refresh_spec",
+              "checkpoint.page_kit.store_profile.repair_spec",
+              "checkpoint.built_output.upsell_selector_scope.repair_selectors",
+              "checkpoint.page_kit.sdk_version.repair_target",
+              "checkpoint.page_kit.sdk_version.align_store_profile",
+              "checkpoint.page_kit.sdk_version.align_sdk_version",
+              "checkpoint.page_kit.sdk_version.repair_waiver",
+              "checkpoint.page_kit.sdk_version.waive",
+              "checkpoint.page_kit.store_profile.repair_target",
+              "checkpoint.page_kit.store_profile.align_store_profile",
+              "checkpoint.page_kit.store_profile.align_sdk_version",
+              "checkpoint.page_kit.store_profile.repair_waiver",
+              "checkpoint.page_kit.store_profile.waive",
+              "checkpoint.built_output.upsell_selector_scope.repair_target",
+              "checkpoint.built_output.upsell_selector_scope.align_store_profile",
+              "checkpoint.built_output.upsell_selector_scope.align_sdk_version",
+              "checkpoint.built_output.upsell_selector_scope.repair_waiver",
+              "checkpoint.built_output.upsell_selector_scope.waive",
+              "checkpoint.polish.hidden_eager_media.capture",
+              "checkpoint.polish.hidden_eager_media.install_browser",
+              "checkpoint.polish.hidden_eager_media.repair",
+              "checkpoint.polish.hidden_eager_media.repair_authority",
+              "checkpoint.polish.hidden_eager_media.local_proof_rebuild",
+              "checkpoint.polish.hidden_eager_media.waive",
+              "unknown"
+            ]
+          }
+        },
+        "gates": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "state"
+            ],
+            "properties": {
+              "id": {
+                "enum": [
+                  "doctor",
+                  "prepare_build",
+                  "theme_gate",
+                  "polish_gate",
+                  "page_kit.sdk_version",
+                  "page_kit.store_profile",
+                  "built_output.upsell_selector_scope",
+                  "polish.hidden_eager_media",
+                  "unknown"
+                ]
+              },
+              "state": {
+                "enum": [
+                  "pass",
+                  "blocked",
+                  "waived",
+                  "not_applicable",
+                  "unknown"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "qa": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "verdict_id",
+            "disposition",
+            "binding",
+            "publish_state"
+          ],
+          "properties": {
+            "verdict_id": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[A-Za-z0-9_-]{1,64}$"
+            },
+            "disposition": {
+              "enum": [
+                "ready",
+                "ready_with_exceptions",
+                "blocked",
+                "unknown"
+              ]
+            },
+            "binding": {
+              "enum": [
+                "matching",
+                "unconfirmed"
+              ]
+            },
+            "publish_state": {
+              "enum": [
+                "skipped",
+                "ok",
+                "failed",
+                "unknown"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/next-campaigns-build/SKILL.md

@@ -1,11 +1,27 @@
 ---
 name: next-campaigns-build
-version: 1.0.2
+version: 1.0.3
 description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
 ---
 
 # Next Campaigns Build
 
+## Installed toolkit commands
+
+Run from the campaign folder with an exact project-local devDependency and
+committed lockfile. Orient on reviewed source before installation; check release
+provenance or pin the full reviewed Git SHA. Preflight with `npx campaigns-os
+tooling status --platform <claude|codex>` and refresh bundled skills for the same
+profile. Use the invocation printed by status and `next` to avoid PATH shadowing.
+
+In the instructions below, bare `campaigns-os …` means `npx campaigns-os …`
+from that campaign folder. Global-only users substitute the global copy's printed invocation for
+each `npx campaigns-os` example; toolkit contributors translate to `npm run campaigns-os -- …` in
+the toolkit checkout. Browser installation is `npx campaigns-os qa
+install-browser`, not a campaign npm script. `tooling diagnose --packet <p>
+--json` provides a redacted support export without changing retained evidence.
+
+
 ## Recommended Build Loop
 
 For campaign builds, follow **build → independent review → repair → verification**.