@nextcommerce/campaigns-os 1.37.3 → 1.41.2

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.41.2",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -40,7 +40,10 @@
     "findings",
     "run-record",
     "run",
-    "demo"
+    "demo",
+    "login",
+    "logout",
+    "readback"
   ],
   "hashed": {
     "contracts/migration-sidecar-bundle.v0.json": {
@@ -62,7 +65,7 @@
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "91853bbd1b14c080e2fe2ec32f1aa643f53e62df280b543093bf158ae924dd4b"
+      "sha256": "886fb59b58787a3fd7a9c43ce4c676aeebbd52fd789269cfac700fcae42106d1"
     },
     "schemas/campaign-spec.v4.schema.json": {
       "sha256": "12b57573739357acb2b007d00a737cd86face441c47f2719fc51b041dc8ea4a5"
@@ -111,6 +114,15 @@
     },
     "demo/apollo-v0/provenance.json": {
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
+    },
+    "schemas/campaigns-os-readback.v2.schema.json": {
+      "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
+    },
+    "contracts/effects.v1.json": {
+      "sha256": "37c54f75731541f763aedac7b067506b3d0aa98e1083f285de87b9b32b027664"
+    },
+    "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,13 @@
     "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"
   ]
 }

package/docs/build-packet.md

@@ -444,17 +444,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 +497,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
@@ -1290,7 +1301,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/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.

package/docs/effects.md

@@ -0,0 +1,281 @@
+# Declared command effects
+
+`contracts/effects.v1.json` states, for every supported invocation of this
+toolkit, what it **writes** and what it **sends**. It is the file to read before
+you let an agent run a command it has not run before, and it is the file a tool
+face would read to decide whether an invocation needs a human in the loop.
+
+The point of the file is not the prose. It is that **every row is proved by a
+test** (`src/effects.test.mjs`), and a row without its test cannot be published:
+`npm run check:effects` refuses it.
+
+- The contract: [`contracts/effects.v1.json`](../contracts/effects.v1.json)
+- Its shape: [`schemas/campaigns-os-effects.v1.schema.json`](../schemas/campaigns-os-effects.v1.schema.json)
+- The proof: `src/effects.test.mjs`
+- The gate: `scripts/check-effects.mjs` (`npm run check:effects`)
+
+## The vocabulary
+
+### Annotations
+
+Four booleans per row, spelled the way an MCP tool face spells them, so a host
+that already understands those hints needs no translation layer.
+
+| Annotation | Meaning |
+| --- | --- |
+| `readOnlyHint` | The invocation changes **nothing**: no file under the target, the working directory or your machine, and no request off the machine. |
+| `destructiveHint` | The invocation can overwrite, clear or discard state that existed before it ran. Only meaningful when `readOnlyHint` is false. |
+| `openWorldHint` | The invocation can contact an endpoint off this machine. True exactly when the row declares at least one send. |
+| `idempotentHint` | Repeating the invocation with the same arguments adds no effect beyond the first run. |
+
+**`readOnlyHint` counts the command-lifecycle journal.** A journal append is a
+write like any other, so every `readOnlyHint: true` row is an invocation the
+CLI exempts from lifecycle capture (the converse does not hold: `demo` and the
+`--no-write` forms skip the journal but still write other declared files): `help`, `readback`,
+`run status`, `doctor` inspection, `doctor --no-write`, `sdk storage-check`,
+`tooling diagnose`, a refused invocation, `run-record --no-write`, and every
+`--dry-run` form on the commands that implement the flag. Everything else
+appends an entry when a journal is selected — an active run session,
+`--lifecycle-journal`, or `CAMPAIGNS_OS_LIFECYCLE_LOG` — and is therefore not
+read-only, even when the command writes no artifact of its own. `standardize`
+and `bundle check` are tier `B` for exactly that reason and nothing else; their
+rows say so.
+
+### Tiers
+
+| Tier | Meaning |
+| --- | --- |
+| `none` | No effect: nothing written anywhere, nothing sent. |
+| `B` | Writes files under the target, the working directory or your machine. Nothing leaves the machine. |
+| `A` | Can contact an endpoint off this machine (it may write locally too). |
+| `C` | Destructive: overwrites, clears or discards state that was already there (it may send too). |
+
+A row carries the **highest** tier it can reach, ranked `none < B < A < C`.
+
+### Location tokens
+
+A write path is a glob (`*` within one segment, `**` across segments) that opens
+with one of these:
+
+| Token | Resolves to |
+| --- | --- |
+| `{target}` | The target the invocation names: the directory given to `--target`, or the Page Kit target repository the Build Packet points at. |
+| `{cwd}` | The working directory the invocation runs in. |
+| `{spec}` | The CampaignSpec file the Build Packet names (`spec.local_path`), which need not live inside the target repository. |
+| `{home}` | Your machine: the home directory and the config root under it (`XDG_CONFIG_HOME` when set). |
+| `{packet}` | The Build Packet the invocation names (`--packet`), wherever it lives — it need not be the copy inside the target repository. |
+| `{lifecycle-journal}` | The command-lifecycle journal wherever it was selected for this invocation. |
+| `{proxy-base}` | The endpoint `--proxy-base` names, or the canonical NEXT endpoint when it does not. |
+| `{base-url}` | The campaign under test, as `--base-url` names it or as the packet derives it. |
+| `{playwright-download-host}` | Where Playwright fetches browser builds from: `PLAYWRIGHT_DOWNLOAD_HOST` when set, else the Playwright CDN. The one destination in the file that is not a Campaigns OS endpoint — `qa install-browser` is the one supported invocation that downloads from a third party. |
+
+The tokens matter because effects are not all under the target. `install-skills`
+writes your **home** directory, not the campaign. `telemetry on` writes your
+**machine** config. `run-record` writes beside the **working directory**, not the
+target repo. A row that said "writes the target" would be wrong about all three.
+
+## How to read a row
+
+```jsonc
+{
+  "command": "page-kit",
+  "subcommand": "sync",
+  "flags": [],                       // the base form; --dry-run is its own row
+  "annotations": { "readOnlyHint": false, "destructiveHint": false,
+                   "openWorldHint": false, "idempotentHint": true },
+  "tier": "B",
+  "writes": [
+    { "path": "{target}/_data/campaigns.json",
+      "when": "one of the ten Store Profile / SDK-pin fields is usable and differs from the entry",
+      "observed_in": ["no_session", "ambient_session", "stale_session", "lifecycle_log"] }
+    // …
+  ],
+  "sends": [],
+  "effect_test": "effects: page-kit sync",
+  "test_scope": "full",
+  "notes": "Writes only those ten fields of the packet's route entry…"
+}
+```
+
+There is **one row per command and per effect-changing flag combination**. The
+flags that change what the invocation does to the world are listed once, in
+`vocabulary.effect_changing_flags`: `--browser`, `--built`, `--dry-run`,
+`--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
+`--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
+`--no-write`, `--republish`, `--test-order`, `--write`, `--write-map`. Flags
+that only change the output shape (`--json`, `--report`) deliberately do not.
+
+**"The help text" is every help block the CLI prints**, not one file's.
+`campaigns-os qa` prints its own from `src/qa-node.mjs`, and while the coverage
+scan read only `src/cli.mjs` the three subcommands documented there alone — `qa
+parity`, `qa waive` and `qa install-browser` — owed no row, had none, and the
+gate stayed green. Every module that owns a usage block is listed in
+`HELP_SOURCE_PATHS` and scanned the same way; a test derives that list from the
+source, so a command that grows its own help cannot quietly leave the scan.
+
+**Every one of those flags that a help usage line carries owes a row**, and
+`scripts/check-effects.mjs` fails when one does not have it. Coverage by command
+alone was not enough: deleting the `page-kit sync --dry-run` row, or the
+`doctor --write` row, left the gate green while the file lost an effect —
+`doctor --write` writes the doctor sidecar, the assembly report and the packet
+that plain `doctor` does not. A flag that appears in a usage line for a command
+that has only a base row is now the loudest kind of failure this gate has.
+
+One row is not a command at all: `{"command": "*refused*"}` is any invocation
+refused before its handler runs — an unknown command, an unknown subcommand, or
+a flag the command rejects up front. It writes nothing, journals nothing, and is
+the row to read when you want to know what a typo costs. The one exception is
+declared on the rows it belongs to: `start`, `prepare-build`, `build`,
+`run start` and `run end` close out a **stale** run session at the root they are
+about to act on *before* argv is refused.
+
+## How a row is proved
+
+`src/effects.test.mjs` runs the real CLI in a disposable target seeded from
+`examples/`, under **five conditions**, and snapshots the whole tree (paths plus
+sha256) before and after while a loopback `node:http` receiver counts requests.
+
+| Condition | What it sets up |
+| --- | --- |
+| `no_session` | No run session at the target or the working directory. |
+| `ambient_session` | An active ambient run session opened by `run start` at the target. |
+| `stale_session` | A run session idle past the 12 h TTL, at the target and at the working directory. |
+| `lifecycle_log` | `CAMPAIGNS_OS_LIFECYCLE_LOG` names a journal outside the runtime directory. |
+| `persisted_consent` | Run Telemetry consent **persisted on the machine for the loopback receiver's scope**, a synthetic campaign key in the environment, no run session, and `--proxy-base <loopback>` wherever the command takes it. |
+
+Five conditions rather than one, because the CLI's effects are not a function of
+argv alone: an ambient session redirects the journal and is itself touched by
+session resolution, and a stale session is closed out — Run Record assembled —
+before some commands even read argv.
+
+### Why the fifth condition exists
+
+Under the first four, consent is `CAMPAIGNS_OS_TELEMETRY=off` unless the row
+declares a consent-gated send it expects to see in that condition; then the row
+runs with consent on and the loopback receiver as its endpoint, so "nothing was
+sent" is not an artefact of consent being off **for a send that is declared**.
+
+That took the row's word for which sends exist, and it hid real ones: `next` and
+its five stage forms, and all three `qa run` rows, declared `sends: []` while
+each of them POSTed — to `{proxy-base}/api/progress`, and for `qa run` to
+`{proxy-base}/api/qa/verdicts` as well, on blocked attempts included.
+
+`persisted_consent` does not read consent from the row. It persists consent the
+way an operator does — `campaigns-os telemetry on --proxy-base <loopback>`,
+which is a **scoped** record — and runs every row that way. An environment
+override is not equivalent and is the reason the earlier probe found nothing: an
+env grant carries no scope, so the remit refuses it for a non-canonical endpoint
+(`scope_bypassed`) and delivers nothing. Any request the receiver sees that no
+declared send covers fails the row.
+
+The same scoping is what keeps the suite off the network. The remit endpoint is
+a hard-coded constant with no environment override, so a command that falls back
+to the canonical endpoint resolves consent **off** (the persisted grant covers
+the loopback scope only) and sends nothing. That is asserted, not assumed: every
+invocation in this condition runs under `NODE_DEBUG=net` and its connection log
+must name no host but `127.0.0.1`, and one case states the claim directly for
+`next` with no `--proxy-base` at all.
+
+The assertion runs both ways, and that is what makes the file falsifiable:
+
+1. **Nothing undeclared may change**, in any condition. A `readOnlyHint: true`
+   row declares no writes, so any byte that moves fails it.
+2. **Every declared effect whose `observed_in` names a condition must be seen**
+   in it, so a row cannot be padded with effects that never happen.
+
+`observed_in` is per effect, not per row: `install-agent-context` writes
+`{target}/.gitignore` only when the target does not already ignore the runtime
+directory, so that entry is observed in three conditions and not under
+`ambient_session`, where `run start` has already added the line.
+
+### Rows proved at the preflight
+
+Some invocations cannot execute past their preflight with no network, no
+browser, no renderer and no credentials. Those rows carry
+`test_scope: "preflight"`. Their case proves the preflight refusal writes
+nothing beyond what the row declares and — where a loopback receiver can stand
+in for the destination — that the **declared destination is the one contacted**.
+
+| Row | What the offline fixture cannot reach |
+| --- | --- |
+| `login` | A reachable login gateway and a human at a browser. Proved: the failure path writes nothing at all — no credential, no journal entry. |
+| `logout` | A credential minted by a gateway login. Proved: the no-credential path writes nothing. |
+| `page-kit parity` | A `local-serve` deploy target and a page-kit renderer to build the two renders with. Proved: the refusal writes nothing but the journal entry. |
+| `polish capture` | An installed browser and a reachable `--base-url`. Proved: the refusal writes nothing but the journal entry and contacts nothing. |
+| `qa install-browser` | The Playwright CDN, and the ~150 MB Chromium archive it serves. Proved: the failed download writes exactly one path under your machine — the registry's link entry — and nothing else anywhere, and leaves the machine zero times. |
+| `qa parity` (and `--no-post-verdict`) | An installed Chromium and a reachable candidate funnel. Proved: the refusal writes nothing but the journal entry and contacts the stand-in for `--base-url` zero times. |
+| `qa resolve` | A resolution that is not blocked before the probe. Proved: the blocked resolution contacts the stand-in zero times. |
+| `qa run --browser` | An installed Chromium and a reachable campaign. Proved: the attempt is blocked at the same gate as the node run and writes exactly the blocked-attempt evidence. |
+| `spec derive --from-store` | A live gateway and a real store credential. Proved: the credential refusal writes nothing under the target or the spec. |
+| `spec derive --write-map` | A Map whose `spec_hash` precondition a loopback stand-in can satisfy, so the `PUT` is never reached. Proved: the declared destination **is** the one contacted (the receiver sees the Map read), and the refusal adds no report evidence. |
+| `telemetry list` | A real ops admin key and a real endpoint. Proved: the receiver sees the declared `GET /api/runs`, and the refusal writes nothing but the journal entry. |
+
+#### What a preflight row is allowed to touch
+
+A preflight row declares its allowances **separately from its effects**, and the
+test enforces them independently:
+
+```jsonc
+"preflight": {
+  "may_write":   ["{lifecycle-journal}"],   // the ONLY paths the refusal may write
+  "may_contact": ["/api/runs"]              // the exact request paths the receiver may see
+}
+```
+
+Both halves close a hole that a declared effect used to open. `logout` declared
+`{home}/**` for the credential a *completed* login writes — and that declaration
+also licensed its refusal to write anywhere under the home directory, so a
+home-directory write injected into the preflight passed. And a destination a
+loopback receiver only stands in for (`{base-url}`, the login gateway) matched
+**any** request path, so an injected endpoint passed too. Now:
+
+- `may_write` is the whole permission. It may not name a whole location
+  (`{target}`, `{target}/**`) and may not span segments under `{home}` — the
+  skills directories, the credential store and the consent file all live there,
+  under the temporary `HOME` the test sets, and a preflight that writes one of
+  them has to say which.
+- `may_contact` is matched literally against the request path, so an `/api/`
+  call nobody declared fails the row even when the row declares a stand-in
+  destination. (On a `full` row the same rule holds one step down: a stand-in
+  destination never covers an `/api/` path, because every API endpoint in this
+  contract is declared as `{proxy-base}/api/…`.)
+- A write the row declares as observed must also be in `may_write`; the gate
+  refuses the contradiction rather than letting the test find it.
+
+A `full` row may still carry an individual effect the offline fixture cannot
+reach — the Map Builder spec fetch behind `--map-id`, the `codex` and `agents`
+destinations of `install-skills`. Each such entry has an empty `observed_in`
+**and** a `not_observed_reason`, and `check-effects.mjs` refuses one without the
+reason. What it may not be is silent.
+
+## The rule
+
+**A row without its test is not published.** `scripts/check-effects.mjs` (in
+`npm run check` and `npm run check:contracts`) fails when:
+
+- a command on the supported CLI surface, a subcommand any help block teaches
+  (`src/cli.mjs` and `src/qa-node.mjs`), or an effect-changing flag a help usage
+  line carries, has no row;
+- a row names no `effect_test`, names one `src/effects.test.mjs` does not
+  declare, or names one the per-row generator would not produce (the cases are
+  generated from this file, so an unchecked name made the link vacuous);
+- a row has no entry in the test's `INVOCATIONS` table, or the table has an
+  entry no row claims — a generated case with no argv proves nothing;
+- an effect declares no `observed_in` and no `not_observed_reason`;
+- a `test_scope: "preflight"` row does not say in its own notes what it cannot
+  reach, declares no `preflight` allowances, licenses a whole location or a
+  home-directory subtree, names a `may_contact` entry that is not a request
+  path, or has an observed write its `may_write` does not allow; a
+  `test_scope: "full"` row carries allowances, or has no effect observed
+  anywhere;
+- the annotations disagree with the row (`readOnlyHint` with declared effects,
+  `openWorldHint` without a send, `destructiveHint` off tier `C`);
+- two rows claim the same invocation, or a write path opens with no known
+  location token;
+- `vocabulary.conditions` names a condition `src/effects.test.mjs` does not run.
+
+## When you change a command
+
+Change the effect, change the row, in the same PR. The effect test will tell you
+which row is wrong before review does: it names the path that moved and the row
+that failed to declare it.

package/docs/gateway-login.md

@@ -0,0 +1,113 @@
+# Gateway login and direct-token migration
+
+The 1.38.0 candidate supports the admitted owned-store private gateway pilot
+with the registered Campaigns OS CLI client. It is not general merchant
+availability. Publication, external trials and additional clients are separately
+gated. A successful owned-store drill does not prove automatic uninstall
+handling or authorize other stores.
+
+## Sign in
+
+```sh
+campaigns-os login --store example
+# The equivalent canonical host is example.29next.store.
+```
+
+`--store` is optional in an interactive terminal: one prompt asks for the store.
+There is no discovery or guess from the current project. Noninteractive calls
+must supply `--store`. URLs, paths and unrelated hosts are refused before any
+request. Login uses the fixed `https://mcp.nextcommerce.com` gateway.
+
+Open the displayed device page in one browser tab and enter the displayed code.
+Keep that tab: if installation is needed, follow its Install Campaigns link,
+sign in to the store dashboard and launch Campaigns. Match the code and explicitly
+allow reads. Return to the CLI. Pilot admission is operator controlled; knowing
+the store host or device-page URL is not an invitation. Never paste a dashboard
+or Admin token into the CLI. Login waits for browser consent within the device
+code's expiry; denial, timeout and failed persistence preserve the prior login.
+
+Gateway access and refresh credentials are stored outside the project. On macOS,
+the CLI prefers the user keychain; when unavailable it uses private user files
+under `~/.campaigns-os/credentials` (directory `0700`, files `0600`). Keychain
+selection metadata lives there too. The parent must be owned by the user and
+not group/other writable. Credential paths reject symlinks; a symlinked home is
+not supported in this pilot. Do not copy these files into a repository, support
+export or CI secret bundle. These are gateway credentials, not platform Admin
+tokens; platform OAuth custody stays server side.
+
+## Migrate store reads
+
+The default changed. A command that formerly read `EXAMPLE_ADMIN_TOKEN`
+automatically now requires a gateway login for the selected store:
+
+```sh
+campaigns-os login --store example
+campaigns-os spec derive --packet campaign-runtime.build.json --from-store example --dry-run
+```
+
+Existing direct callers, including callers outside the admitted pilot, can retain
+the direct path by explicitly naming their existing environment variable:
+
+```sh
+campaigns-os spec derive --packet campaign-runtime.build.json --from-store example --store-token-source env:EXAMPLE_ADMIN_TOKEN --dry-run
+```
+
+This break-glass path emits a warning and bypasses gateway custody. Its Admin
+token needs `store:read` and `content:read`. Do not put its value in argv.
+The default never checks that variable or falls back to it after a gateway error.
+An unavailable gateway fails closed. Gateway reads use `/admin/store/` and
+`/admin/pages/`; custody consolidates bounded upstream page results. Derivation
+still uses the same nine Store Profile fields and leaves missing or ambiguous
+values unchanged. The output distinguishes the actual gateway endpoint from
+the logical store Admin API source. See [Store Profile derivation](build-packet.md).
+
+Refresh is serialized per store binding. The CLI records a pending state before
+sending a refresh, then atomically saves the confirmed winning pair. A lost
+response, interrupted process or uncertain save requires a new login; the next
+invocation must not replay an old refresh. An expired absolute grant also requires
+login. A refresh may happen before access expires, or once after an unauthorized
+read; it is not an unlimited retry loop.
+
+## Inspect and recover
+
+`campaigns-os tooling status --json` includes `gateway_login` metadata for saved
+bindings, without `--store` or project inference. It shows store, local access
+expiry/remaining time and the gateway version reported when credentials were
+issued. It makes no gateway validity request and exports no credential values.
+`logged_in` means the saved access expiry is in the future, not that the remote
+grant is still valid. `access_expired` can still refresh on use; `login_required`
+means reauthorize. A reported version such as `a3-offline` is metadata, not proof
+of deployed source identity. `tooling diagnose` remains a separate redacted
+support export and omits gateway login/store metadata.
+
+Storage contention waits up to three seconds, then reports unavailable/busy.
+Retry after the other CLI finishes; check user-directory permissions and keychain
+access. One malformed or unreadable record makes the whole gateway status
+unavailable in this pilot; it does not prove that all stores are logged out.
+After a crash, confirm no Campaigns OS process is running before removing the
+stale binding's `.lock` directory under `~/.campaigns-os/credentials`. Never
+remove another live process's lock. If selection metadata is damaged, preserve
+it privately and repair or move aside only that binding's broken selection file
+before logging in again; this does not remotely revoke an old grant. Do not
+bypass ownership or symlink checks by making the directory world writable.
+
+## Sign out
+
+```sh
+campaigns-os logout --store example
+```
+
+Logout uses the same optional interactive store prompt. It attempts gateway
+revocation and clears the local selected login. Its message distinguishes
+confirmed remote revocation from an unrecognized grant, failed request or
+unreadable local record. Local cleanup alone is not proof of remote revocation;
+a failed keychain-item cleanup is reported separately. A pending/uncertain
+refresh is never replayed during logout. If remote revocation is unconfirmed,
+use the pilot operator's grant-revocation procedure; do not assume uninstall or
+local file deletion revoked it.
+
+Login, logout and the offline demo bypass lifecycle capture; login/logout do not
+accept general lifecycle flags. `tooling diagnose` also bypasses lifecycle
+capture. Gateway login does not grant telemetry administration:
+`CAMPAIGN_OPS_ADMIN_KEY` remains a separate cross-tenant `/api/runs` credential,
+with its existing trusted-origin safeguards and explicit warning.

package/docs/orientation-contract-reference.md

@@ -25,7 +25,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.37.3`
+Supported surface at generation time: `1.41.2`
 
 ## Forward compatibility
 
@@ -244,6 +244,9 @@ so a renamed command fails here as well as at the supported-surface gate.
 - `campaigns-os run-record`
 - `campaigns-os run`
 - `campaigns-os demo`
+- `campaigns-os login`
+- `campaigns-os logout`
+- `campaigns-os readback`
 
 ## Terminal outcome examples
 

package/docs/progress-snapshots.md

@@ -1,8 +1,8 @@
 # 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
+Release **1.36.0** adds the portable `@nextcommerce/campaigns-os/progress`
+export and `schemas/campaigns-os-progress-snapshot.v0.schema.json`; it first
+shipped in 1.37.1 and is in every later release. 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

package/docs/qa-and-test-orders.md

@@ -1692,9 +1692,9 @@ a trusted submission attests the runner, not execution or resource identity.
 
 ### Playwright updates and consumer installs
 
-After installing or updating Campaigns OS, run `npx campaigns-os qa install-browser`
-from the campaign project (or `campaigns-os qa install-browser` for a global
-installation). This resolves the same Playwright package as QA and polish capture.
+After installing or updating Campaigns OS, run
+`npx --no-install campaigns-os qa install-browser` from the campaign project
+(or `campaigns-os qa install-browser` for a global installation). This resolves the same Playwright package as QA and polish capture.
 A project's own `npx playwright install` can resolve a different version and install
 a different Chromium build. Campaigns OS is an optional-dependency owner, not a
 Playwright peer dependency: npm may share a compatible copy or install a nested one.