@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/docs/effects.md

@@ -0,0 +1,350 @@
+# 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.
+
+`tooling setup` composes the existing skill/context/browser installers after a
+project-pin and preservation preflight. It also appends a project `CLAUDE.md`
+import. It bypasses session recovery, gateway credential reads and lifecycle
+capture; `--dry-run` is read-only. Like `qa install-browser`, its browser download
+has preflight-only effects proof offline; setup's preservation and recovery
+behavior has focused tests.
+
+- 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 third-party browser download used by `qa install-browser` and `tooling setup`. |
+
+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.
+
+A refusal is decided by argv alone. When file content or state on disk decides
+the outcome, the command has reached a handler failure and journals it.
+
+For intake, run-record, built-site QA, and `next`, argv-only checks run before
+their handler reads the target; invalid values are refused without a journal
+entry. For `start`, `prepare-build`, and `build`, bare, empty, and whitespace-only
+values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
+`--proxy-base`, `--wrapper-policy`, `--design-manifest`, and
+`--order-path-depth` are refused before local spec reads, Map fetches, or cache
+writes on the `--spec`, `--map-id`, and `--map-id --cached-spec` paths.
+The operator-facing `run-record` and `run end` commands refuse bare, empty, or
+whitespace-only values for every value-taking inherited run-record flag before
+packet work. The five agent
+token and elapsed-time flags retain their non-negative-integer diagnostics;
+`--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
+inherited boolean flags (`--no-remit`, `--no-write`, `--dry-run`, and `--json`)
+retain their bare-flag behavior. `run end` also rejects `--new-run` and
+`--run-id` because the saved session fixes its run ID. `run-record` also
+rejects bare, empty, or whitespace-only `--run-id` and valued `--new-run`.
+Internal stale-session and QA closeouts retain the previous handling of values
+inherited from their invoking commands. A bare, empty, or whitespace-only
+`--proxy-base` on a sweeping command still writes the stale Run Record.
+Terminal QA auto-end tolerates whitespace-only inherited `--context`,
+`--report`, or `--proxy-base`. A whitespace-only `--context` resolves as a
+literal relative path, so the default context file is not read. Bare or empty
+`--context` or `--report` still makes QA auto-end fail and leaves the session
+open; bare or empty `--qa-verdict` fails a Run Record closeout when inherited,
+though QA auto-end supplies its own verdict path. The underlying run-record
+handler still rejects invalid agent
+integers, unknown `--surfaces`, and any valued `--dry-run` that reaches it. QA
+auto-end drops `--dry-run` from inherited flags; if another inherited value
+fails in the handler, auto-end is skipped and the session stays open. QA's own
+journal entry is unaffected because auto-end runs after QA persistence. A named
+`--design-manifest` that is missing or is not a file is checked
+against the filesystem after intake has begun, so that failure is journaled.
+An invalid manifest's contents are likewise a handler failure. A `next` stage
+must be one of the stages in the orchestration stage contract; an unknown name
+is refused before the `next` handler reads the packet, runs doctor, or writes
+doctor output. The ambient run-session lookup in `main()` may read a named
+`--packet` before the handler runs.
+
+`polish capture --packet` would report "polish capture requires
+packet.assembly.target_repo to resolve to a local target repo" as a journaled
+handler failure because packet content would decide it. Today the workspace
+resolver always yields a local path, so this check does not fire through the
+CLI. `run end` reports "run end needs a build packet" as a journaled handler failure
+when the saved session has no packet and argv names none. For `qa run` and `qa
+resolve`, "QA requires a Map ID" is a refusal when argv carries no non-empty
+`--packet`, `--site`, `--built`, positional Map ID, or `--map-id` value. A selector
+flag without a value is refused with "Missing value for --<flag>". If a named
+packet yields neither a Map ID nor a valid local-spec identity after checkpoint
+preflight reads the packet, spec, and report, the requirement is a journaled
+handler failure. A conflicting local/Map identity is also a handler failure.
+The nested run-record refusal scope in session closeout guards against future
+changes. No internal closeout can currently create a refusal before its
+invoking command journals.
+
+## 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.
+
+Local-spec QA retains its artifacts locally. It never sends a verdict or progress
+to the Map portal, even when `--post-verdict` is supplied; `qa publish` refuses
+local-spec packets. Commerce API reads, served-page probes and requested typed-card
+orders keep their existing effects. Run Telemetry still follows its consent controls.

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/local-setup.md

@@ -0,0 +1,51 @@
+# Local campaign setup
+
+For a new campaign, choose its working folder and run this from that folder:
+
+```sh
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.1 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+```
+
+Review the release source/provenance before installation as described in
+`AGENTS.md`. npm installs the dependencies first; `--no-install` then runs only
+the project's installed CLI. Keep `package.json` and `package-lock.json` in
+Git. For an existing project, preserve its reviewed pin: run `npm ci`, then
+`npx --no-install campaigns-os tooling setup --target . --platform claude`
+on a release that supports setup. Changing the pin is a separate update.
+
+Setup checks the exact toolkit pin, its lockfile version and the installed
+page-kit dependency before it changes files. It composes the existing
+installers to:
+
+1. Install the QA browser through this toolkit's own Playwright package.
+2. Install the bundled skills into `~/.claude/skills` (same-name skills are
+   refreshed just as with `install-skills`).
+3. Install the four context files under `.campaign-runtime/agent-context`
+   and the managed runtime ignore block.
+4. Append one import to the project's `CLAUDE.md`, preserving existing text.
+
+The import uses Claude Code's documented
+[`@path` syntax](https://code.claude.com/docs/en/memory#import-additional-files).
+Existing context that differs from the bundle and symlink destinations require
+reconciliation before setup; setup does not overwrite them. A repeated run
+preserves campaign pages, authored decisions and project instructions. If the
+browser download fails, fix that error and rerun setup; shared skills and
+project files have not been changed. If the runtime ignore block cannot be
+written, setup reports `context_install_failed`; fix `.gitignore` and rerun.
+`--dry-run --json` previews setup without any writes or browser download.
+
+Restart Claude Code in the campaign folder. Use the `next-campaigns-os` skill
+and provide the configured campaign details, HTML/assets and brief. The agent
+authors a local CampaignSpec if there is no saved Map export; follow the
+[local-spec entry](build-packet.md#local-spec-entry). The skill checks its
+loaded bundle revision against the project copy.
+`restart_required` means the files are installed; it does not prove that the
+running agent has loaded them. Check Claude's `/context` view if the project
+instructions are missing.
+
+Setup does not scaffold template pages, create a CampaignSpec, connect the
+gateway, change a saved Map, run a campaign session, remit telemetry, or prove
+checkout. The agent performs intake and chooses the template before assembly.
+A local spec uses `spec_identity.local_spec_id` and keeps its evidence in the
+repository. Existing doctor/QA gates still apply. This entry is Claude Code first; other agents retain their existing
+manual installation path.

package/docs/migration-sidecar-bundle.md

@@ -55,12 +55,17 @@ contract. A packet found only at
 remedy; conformance does not silently widen discovery.
 
 The checker validates canonical paths, declared schema versions, strict UTC
-timestamps, cross-artifact Map ID, public slug, campaign directory, live URL
+timestamps, cross-artifact Map ID or local-spec ID, public slug, campaign directory, live URL
 path, template family, and spec identity, doctor freshness, and the URL/order-
 free QA projection. Safe repository-relative spellings such as
 `campaign-runtime.build.json` and `./campaign-runtime.build.json` are
 equivalent; absolute paths, URIs, backslashes, and parent traversal are not.
 
+Local-spec bundles compare `local_spec_id` across the packet, report, doctor
+output and QA sidecar. Their Map IDs remain null; the QA verdict's
+`campaign_slug` is the storage key `local-spec-<local_spec_id>`. Mixing local
+and saved-Map identities fails conformance; a shared public route is not enough.
+
 Spec identity has two deliberately separate meanings. Build Context
 `spec.hash` and Assembly Report `identity.spec_hash` retain exact raw-byte
 integrity. Build Context `spec.material_hash`, Assembly Report

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.43.1`
 
 ## 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
@@ -140,3 +140,9 @@ The planned immutable receiver key is
 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.
+
+Local-spec packets add optional `identity.local_spec_id`. Report binding compares
+that ID and the local material hash, so local stages can be observed without a
+saved Map. `map_id` and `map_revision_hash` remain null and
+`saved_revision_alignment` remains `unconfirmed`; these observations stay on disk
+with `map_id_missing` and have no portal storage key.