@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
-  "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act \u2014 hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here \u2014 src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) \u2014 is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.37.3",
+  "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
+  "surface_version": "1.43.1",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -40,11 +40,14 @@
     "findings",
     "run-record",
     "run",
-    "demo"
+    "demo",
+    "login",
+    "logout",
+    "readback"
   ],
   "hashed": {
     "contracts/migration-sidecar-bundle.v0.json": {
-      "sha256": "f5097f6cccaf211d442c1ebc584d2c76d5a07a44e587df130de02117a9412db0"
+      "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
       "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
@@ -56,16 +59,16 @@
       "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
-      "sha256": "3fa085f2ad368567983cdc9c01e7c712682d02df9c28e69a2b7befb45d444468"
+      "sha256": "8a0d37be9a4bb34d0ed073c9d6bfa4406a7b499c801c34c5fbb26646e2665c0b"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "91853bbd1b14c080e2fe2ec32f1aa643f53e62df280b543093bf158ae924dd4b"
+      "sha256": "47c2899f409ed5927cf410bddd63e7bb8a9d154eabf7a07455777aed118212e9"
     },
     "schemas/campaign-spec.v4.schema.json": {
-      "sha256": "12b57573739357acb2b007d00a737cd86face441c47f2719fc51b041dc8ea4a5"
+      "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
@@ -77,10 +80,10 @@
       "sha256": "1405c32bb9698030e9a40d754191e413cdd505dde91ac7de2e41c8887700f8f2"
     },
     "schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json": {
-      "sha256": "1bc53b9a75a6c19c89aee6e9664574980b09d2e13eb8826b157f5ab6ba82d0b0"
+      "sha256": "3c40fd79f218d1b95f0424f9a2b67db140a306329e2ca02793e2740d3afded59"
     },
     "schemas/campaigns-os-qa-verdict.v0.schema.json": {
-      "sha256": "f7ce00e4f814d0ab7659b11fb2a14d3e4fafbf7c8e353449f25d7e87e1627acc"
+      "sha256": "ec4514e81a791a63bc0b358d7977aa823f3c5524e0f5caaba2712e66f262e18a"
     },
     "schemas/campaigns-os-doctor-output.v0.schema.json": {
       "sha256": "87866e619d2a18f01a208a1682cb14a2079f61df51c642f4e1902b6e6bce0ce5"
@@ -92,7 +95,7 @@
       "sha256": "08ca132134b9e4610370e88082a5e888d09ddec0d5ee4512d84cc57181da722e"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
-      "sha256": "2a073874ab6081dd6db48e90f1a9b2c3c7c3ae4af70779c604701d70bb12b46d"
+      "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
     },
     "schemas/campaigns-os-runtime-recipe.v1.schema.json": {
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"
@@ -107,10 +110,19 @@
       "sha256": "841c1f884260ce3eb3ddb518960a127bc915992a9539c818e5986ce156acff1f"
     },
     "schemas/campaigns-os-progress-snapshot.v0.schema.json": {
-      "sha256": "c572756be7df03351843ffc361fc657e3fd819702b4e6f0a78a3c8efd0b0f046"
+      "sha256": "ef31b4f20e39dfc1614dd4b45e4cf1692a51760b008cb51d133659307bd2a954"
     },
     "demo/apollo-v0/provenance.json": {
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
+    },
+    "schemas/campaigns-os-readback.v2.schema.json": {
+      "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
+    },
+    "contracts/effects.v1.json": {
+      "sha256": "121779835c14d8d48390c57268b50a60fe808f5d9ba91ea2dde5df22a64f8aaf"
+    },
+    "schemas/campaigns-os-effects.v1.schema.json": {
+      "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"
     }
   },
   "named": [
@@ -123,6 +135,7 @@
     "docs/supported-surface.md",
     "docs/campaigns-os-build-flow.md",
     "docs/build-packet.md",
+    "docs/gateway-login.md",
     "docs/migration-sidecar-bundle.md",
     "docs/design-source-package.md",
     "docs/campaign-build-brief.md",
@@ -192,6 +205,14 @@
     "docs/progress-snapshots.md",
     "contracts/fixtures/progress/observation.v0.json",
     "docs/demo-preview.md",
-    "demo/apollo-v0/NOTICE.txt"
+    "demo/apollo-v0/NOTICE.txt",
+    "docs/readback.md",
+    "docs/effects.md",
+    "agents/claude/CLAUDE.md",
+    "agents/codex/AGENTS.md",
+    "agents/copilot/copilot-instructions.md",
+    "agents/cursor/campaigns-os.mdc",
+    "docs/skills-revision.md",
+    "docs/local-setup.md"
   ]
 }

package/docs/build-packet.md

@@ -4,7 +4,7 @@ The Build Packet is the campaign assembly handoff. It wraps, but does not replac
 
 It answers:
 
-- Which CampaignSpec and Map ID are we building?
+- Which CampaignSpec and saved Map ID or local-spec ID are we building?
 - Which public route slug and campaign directory are expected?
 - Where are the prepared HTML/assets?
 - Which Campaign Build Brief is the merchandising/design presentation truth?
@@ -15,6 +15,56 @@ It answers:
 
 The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
+## Local-spec entry
+
+A saved Map is optional for a prepared-HTML build. The coding agent authors an
+ordinary CampaignSpec from the brief, source design and configured campaign's
+real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+operator supplies the selected store/campaign, public Campaigns API key, intended
+pages and commercial choices, plus store contact details and policy URLs. Verify
+the store/campaign binding and package/offer references; do not guess commerce
+values. No gateway or Map provisioning is required for this entry.
+
+Set `spec_identity.local_spec_id` to a new UUID once, commit it with the spec,
+and keep it unchanged through revisions and fresh checkouts. It accepts 1–64
+letters, digits, underscores or hyphens, with no surrounding whitespace. Local
+IDs are checked exactly; the legacy normalization of saved Map IDs does not
+apply. Malformed or conflicting local identities cannot be adopted into campaign
+evidence; blocked diagnostic reports may still be written. Doctor reports local
+identity failures as `spec.local_identity`, while
+saved-Map failures retain `spec.map_id`. Set `spec_identity.public_route_slug`
+to the intended route. Omit `map_id`, saved-Map URLs and saved-Map revision
+metadata; a local ID is never a Map ID. A spec declaring both kinds is refused.
+A separately authored campaign gets a new local ID even if its route matches.
+
+```sh
+npx --no-install campaigns-os start --spec campaign-spec.json --source source-html --target . --template-family <certified-family> --deploy-target local-serve
+npx --no-install campaigns-os next --packet campaign-runtime.build.json
+```
+
+The packet and report retain `map_id: null` and carry `local_spec_id`. Doctor,
+report writes, polish capture, progress, run closeout and QA compare that local
+identity. Material spec hashes still bind the current revision; a changed ID or
+content cannot reuse earlier proof. After a material revision, follow `next` to
+refresh preparation and affected evidence. Keep the spec, source, dependency
+pins and canonical sidecars in Git. Use `readback` and `next` after a fresh
+checkout; identity survives the move, but proof freshness is assessed again.
+
+Run QA through `--packet`. Local verdicts use the storage key
+`local-spec-<local_spec_id>` and carry the explicit ID in the full verdict and
+committed sidecar. A matching route alone cannot adopt a verdict. Local QA is
+never posted to the Map portal: `qa run` suppresses publication even with
+`--post-verdict`, while `qa publish` refuses with `local_spec`. Progress remains
+local with `map_id_missing`. Run Telemetry retains
+its existing consent controls. `spec derive --write-map` requires a real saved
+Map. Moving to a saved Map requires fresh preparation and evidence; this entry
+does not claim saved-Map revision alignment.
+
+Existing saved-Map specs and packets continue to work. The identity change does
+not relax template certification, source proof, store/SDK parity, polish,
+commerce checks, or typed-card checkout proof. Resolve their reported gates;
+localhost readiness is not production approval.
+
 ## Root-Served Campaigns (`campaign.route_root`)
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
@@ -78,7 +128,7 @@ campaigns-os page-kit sync --packet campaign-runtime.build.json [--dry-run] [--j
 ```
 
 The CampaignSpec is the authority for the Store Profile: those values are
-authored in the Map, never in the repo, so `page-kit sync` writes the nine
+authored in the saved Map or the repository-owned local spec, so `page-kit sync` writes the nine
 fields the spec carries (`campaign.store_*`) unconditionally. The SDK pin is
 different. On an existing campaign the repo pin moves first and the Map/spec
 is stale until someone re-saves it, so a spec → repo write would undo a bump
@@ -103,7 +153,7 @@ covers only the governed fields. `--dry-run` prints the same diff without
 writing. Exit 0 on success (including a no-op re-run); exit 2 with
 `page_kit.sync.*` error codes and nothing written when the packet cannot be
 read, the target entry or the spec is missing or not an object, the spec
-identifies another campaign (`spec_identity.public_route_slug` or `map_id`
+identifies another campaign (`spec_identity.public_route_slug`, `map_id` or `local_spec_id`
 disagreeing with the packet: `page_kit.sync.spec_identity_mismatch`), or the
 resolved `_data/campaigns.json` lies outside the target repo through a symlink
 (`page_kit.sync.target_escapes_repo`).
@@ -444,17 +494,25 @@ network, which the default run never touches, so it is opt-in:
 campaigns-os spec derive --packet campaign-runtime.build.json --from-store <subdomain> [--store-token-source env:<VAR>] [--dry-run] [--json]
 ```
 
-`<subdomain>` is the store's `<store>.29next.store` subdomain (the Admin API
-lives at `https://<subdomain>.29next.store/api/admin/`). The read token is
-taken from the environment, never from the command line: from
-`<SUBDOMAIN>_ADMIN_TOKEN` (upper-cased, dashes as underscores) by default,
-or from the variable `--store-token-source env:<VAR>` names. An Admin API
-access token with the `store:read` and `content:read` scopes (Settings >
-API Access) is enough; the token is sent as a bearer and appears nowhere in
-the output, which names the variable instead (a value that is not one line
-of printable ASCII is refused unsent, `spec.derive.store_credential_invalid`,
-and a transport error that quotes a header is redacted). The store is only
-read.
+`<subdomain>` is the store's `<store>.29next.store` subdomain. In the
+1.38.0 candidate, the default read uses gateway credentials saved by
+`campaigns-os login --store <subdomain>`, through
+`https://mcp.nextcommerce.com/admin/`. This is an admitted owned-store
+private pilot, not general merchant availability. Missing, expired or uncertain
+credentials require login; gateway failure never falls back to an environment
+token. See [gateway login and migration](gateway-login.md).
+
+**Migration for existing direct callers:** add
+`--store-token-source env:<VAR>` explicitly, naming your existing environment
+variable (for example `EXAMPLE_ADMIN_TOKEN`). The former implicit
+`<SUBDOMAIN>_ADMIN_TOKEN` lookup is removed. This break-glass path warns that it
+bypasses gateway custody and contacts
+`https://<subdomain>.29next.store/api/admin/` directly. A `store:read` and
+`content:read` Admin token is sufficient. Tokens are never CLI arguments or
+output; invalid bearer values are refused unsent. Both paths only read the store.
+Gateway page pagination is consolidated by custody into a bounded list; the CLI
+does not follow an upstream cursor on this path. The explicit direct path keeps
+its existing bounded cursor traversal.
 
 | Spec field | Store authority |
 |---|---|
@@ -489,14 +547,17 @@ return). A slug that is not one honest path segment (a separator, `.` or
 spec was stale and the diff is the correction, or `--from-store` names
 another merchant's store and the spec should be restored.
 
-The result carries a `store` block (`subdomain`, `admin_api`,
-`token_source`, `store_read`, `pages_read`, `primary_domain`), and the text
+The result carries a `store` block (gateway reads add `transport: "gateway"`
+and the actual gateway `endpoint`; `admin_api` remains the logical upstream
+source), with `subdomain`, `admin_api`,
+`token_source`, `store_read`, `pages_read`, `primary_domain`, and the text
 output a `Store:` line. After a write that moved a store field, `next` is
 `page-kit sync` first (doctor's `page_kit.store_profile` gate now sees the
 spec ahead of the repo and names sync as its repair), then doctor. A store
 that cannot be read is a refusal with nothing written, repo fields included,
-exit 2: `spec.derive.store_credential_missing` (the variable is unset or
-empty), `store_unauthorized` (401/403), `store_not_found` (404: no store at
+exit 2: `spec.derive.store_credential_missing` (no gateway login, or the explicitly
+selected variable is unset or empty), `store_credential_unavailable` (local
+storage is busy or unavailable), `store_unauthorized` (401/403), `store_not_found` (404: no store at
 that subdomain), `store_unreachable` (transport, timeout, 5xx) or
 `store_response_invalid`. Local preconditions (packet, spec, target entry, spec boundary, page tree)
 are checked before the store is contacted, and a packet that names another
@@ -1103,12 +1164,12 @@ and report proof policy fields above.
 
 | Flag | Source | When to use |
 | --- | --- | --- |
-| `--spec <path>` | Local JSON file | Offline work, CI runs against a fixture, or hand-edited spec drafts |
-| `--map-id <id>` | Map Builder proxy (KV-backed) | Default agentic flow — KV is the source of truth, no file shuttling |
+| `--spec <path>` | Local JSON file | Agent-authored local specs, saved-Map exports, offline work or CI fixtures |
+| `--map-id <id>` | Map Builder proxy (KV-backed) | Saved-Map intake from the current KV revision |
 
 When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode.
 
-Retrieval behavior:
+Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
 - **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
@@ -1290,7 +1351,7 @@ doctor read for the locked template family (`required`, `family`, `version`,
   running). This is what `prepare-build` records by default. The catalog
   travels with the toolkit, not with the campaign, so the packet does not
   record where one machine's checkout or package install kept it, and the
-  same packet resolves on any machine and under `npx campaigns-os`.
+  same packet resolves on any machine and under `npx --no-install campaigns-os`.
 - A string `path` is an operator-supplied `--commerce-catalog <path>`,
   recorded relative to the packet (keep it inside the campaign repo). Doctor
   resolves it against the packet's directory and blocks on

package/docs/campaigns-os-build-flow.md

@@ -2,7 +2,7 @@
 
 The happy path is intentionally tight:
 
-1. Export a saved local CampaignSpec JSON from Campaign Map Builder, including Map ID and public route slug.
+1. Use a saved Map export, or have the coding agent author a CampaignSpec from the brief and verified campaign values through the [local-spec entry](build-packet.md#local-spec-entry). Preserve its Map ID or stable `local_spec_id`, plus its public route slug.
 2. Run `campaigns-os start` with the CampaignSpec, prepared source files, target page-kit repo, and template family.
 3. Treat doctor as the first gate. If its `next` block says `doctor-blocked` or `prepare-build` (the same stage names `campaigns-os next` uses), stop and resolve the named blocker.
 4. Run setup when doctor asks for setup; otherwise continue to assembly.
@@ -11,7 +11,7 @@ The happy path is intentionally tight:
 7. Install the package-owned Playwright browser with `npm run qa:install-browser`.
 8. Run polish, serve the current built output, and run `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>`. Do not mark Polish terminal or begin deploy/QA until this package-owned page-load evidence passes or has an exact finding waiver.
 9. Deploy a preview.
-10. Run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` with the tested URL. QA runs publish to the QA portal by default (the QA tab records browser QA plus typed-card proof and the run prints its portal link); pass `--no-post-verdict` only for offline / dev / CI runs.
+10. Run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --browser --test-order common` with the tested URL. Saved-Map QA uses the existing consent and publication controls; pass `--no-post-verdict` to keep its verdict local. Local-spec QA always keeps verdicts and progress local, even with `--post-verdict`, and `qa publish` refuses local-spec packets. Run Telemetry retains its consent controls.
 11. Treat test-order depth as the control: global test cards bypass the gateway and create no transactions, so no approval is needed. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
 12. Promote, block, or iterate from the recorded build, polish, deploy, QA, and test-order evidence.
 

package/docs/demo-preview.md

@@ -6,7 +6,7 @@ release at least 1.37.0 (or a reviewed full-SHA source pin).
 From the folder containing your exact project-local toolkit installation:
 
 ```bash
-npx campaigns-os demo --target ./apollo-sample
+npx --no-install campaigns-os demo --target ./apollo-sample
 ```
 
 Open the printed `landing/index.html` file directly. No server or browser

package/docs/diagnostics.md

@@ -6,12 +6,15 @@ npm, install a reviewed full-SHA source pin as described in the quickstart.
 From the campaign folder:
 
 ```bash
-npx campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json
-npx campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json --json > diagnostic.json
+npx --no-install campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json
+npx --no-install campaigns-os tooling diagnose --platform codex --packet campaign-runtime.build.json --json > diagnostic.json
 ```
 
-Omit `--packet` for installation and skill diagnostics only. Use `--platform
-claude` for a Claude-only profile. `--context` and `--report` may select existing
+Omit `--packet` for installation and skill diagnostics only. Without
+`--platform`, only the platforms where Campaigns OS skills are installed are
+checked and the export reports `platform: installed` (or `all` when none are
+installed, so every platform was checked); use `--platform claude` to
+check one profile, or `--platform all` for every one. `--context` and `--report` may select existing
 local sidecars; `--target` selects a local skills directory. These inputs are
 never included in the export. The text and JSON forms are suitable for review
 and copying to a support request. The command itself sends nothing.