@nextcommerce/campaigns-os 1.37.2 → 1.41.2

package/README.md

@@ -26,10 +26,14 @@ installation, a saved Map, preview observation, and recorded QA each establish.
 
 You do not need to clone this repository to use it. The toolkit is pinned as a
 devDependency of the campaign folder (a page-kit project) and runs through
-`npx campaigns-os …` from that folder — the pin is committed in `package.json`
-and the lockfile, so CI and the deploy host install the same package bytes. Requirements: Node
-`>=20.19.0` and npm 10 or 11 (Node 22 ships npm 10). Three steps, in this
-order:
+`npx --no-install campaigns-os …` from that folder — the pin is committed in
+`package.json` and the lockfile, so CI and the deploy host install the same
+package bytes. Keep `--no-install`: `campaigns-os` is only the bin name of
+`@nextcommerce/campaigns-os`, so in a folder without the pinned copy a plain
+`npx campaigns-os` looks that name up on the registry and, with no terminal to
+ask, installs what it finds; with the flag, npx stops with an error instead.
+Requirements: Node `>=20.19.0` and npm 10 or 11 (Node 22 ships npm 10). Three
+steps, in this order:
 
 1. **Orient before you run anything.** Read
    [`AGENTS.md`](AGENTS.md), `contracts/supported-surface.json`,
@@ -43,9 +47,9 @@ order:
 mkdir "<route>" && cd "<route>"
 npm init -y && npm i next-campaign-page-kit
 npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"
-npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.34.1
-npx campaigns-os tooling status --platform claude
-npx campaigns-os install-skills --platform claude
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.37.3
+npx --no-install campaigns-os tooling status --platform claude
+npx --no-install campaigns-os install-skills --platform claude
 mkdir -p source
 ```
 
@@ -53,7 +57,7 @@ The toolkit is also published to npm as `@nextcommerce/campaigns-os`, so the
 CLI can be installed once, globally, instead of pinned per campaign:
 
 ```bash
-npm install -g @nextcommerce/campaigns-os@1.34.1
+npm install -g @nextcommerce/campaigns-os@1.37.3
 campaigns-os tooling status --platform claude
 campaigns-os install-skills --platform claude
 ```
@@ -69,20 +73,17 @@ runs the full check in an unprivileged job and publishes the verified tarball
 with provenance from a second, environment-gated job.
 
 For an existing page-kit campaign, skip the first three lines and `cd` into it
-(its `package.json` already declares `next-campaign-page-kit`). `1.34.1` is
+(its `package.json` already declares `next-campaign-page-kit`). `1.37.3` is
 an exact published example; choose the release you reviewed, never a floating
 dist-tag for a reproducible build. Commit `package.json` and `package-lock.json`.
-The new `tooling diagnose` command requires 1.35.0 or later. When that release
-is not published yet, use the reviewed full-SHA source pin below; the 1.34.1
-example does not include diagnostics or the global invocation rendering fix.
+`tooling diagnose` requires 1.35.0 or later and `demo` requires 1.37.0 or later.
 A Git source pin remains supported when using an unreleased reviewed commit:
 `npm install --save-dev --save-exact "github:NextCommerceCo/campaigns-os#<full-sha>"`.
 
-For a visual sample, candidate 1.37.0 adds
-`npx campaigns-os demo --target ./apollo-sample`. Open the printed
-`landing/index.html` directly to explore four inert Apollo pages. This command
-requires a reviewed candidate or a published release at least 1.37.0; the 1.34.1
-example above does not include it. It downloads nothing and creates no campaign
+For a visual sample, run
+`npx --no-install campaigns-os demo --target ./apollo-sample` (1.37.0 or later).
+It copies four inert Apollo pages; open the printed
+`landing/index.html` directly. It downloads nothing and creates no campaign
 evidence. Keep sample edits and start a real campaign in a separate new Page Kit
 folder. See [offline sample preview](docs/demo-preview.md).
 The lockfile records the resolved source and integrity; `tooling status` reports
@@ -105,15 +106,15 @@ template stock. To update, review the new release source and install its exact v
 > The first `start` opens a run session in the target folder and, unless you
 > opt out, the session's Run Record is remitted to the Campaigns telemetry
 > endpoint with the packet's Campaigns API key. Opt out with
-> `npx campaigns-os telemetry off`, `CAMPAIGNS_OS_TELEMETRY=off`, or
+> `npx --no-install campaigns-os telemetry off`, `CAMPAIGNS_OS_TELEMETRY=off`, or
 > `--no-remit` on the remitting command; capture stays local either way. The
 > full note — endpoint, payload, what `off` changes, and `--no-run-session` —
 > is in [docs/quickstart.md](docs/quickstart.md) above the first `start`; the
 > contract is [Run Telemetry](docs/workflow-findings-sidecar.md).
 
 ```bash
-npx campaigns-os start --map-id <map-id> --target . --source ./source --template-family <family>
-npx campaigns-os next --packet ./campaign-runtime.build.json --json
+npx --no-install campaigns-os start --map-id <map-id> --target . --source ./source --template-family <family>
+npx --no-install campaigns-os next --packet ./campaign-runtime.build.json --json
 ```
 
 `--map-id <id>` starts from a map saved in Campaign Map Builder (add
@@ -131,10 +132,11 @@ normally `BLOCKED` with a list of what to supply — missing screenshot proof,
 demo values to replace, a scaffold to run. That list is the intake checklist,
 not a failed install. The demo values are the store profile and SDK pin
 `campaign-init` seeded into `_data/campaigns.json`; doctor prints the one
-command that replaces them from the CampaignSpec, `npx campaigns-os page-kit
-sync --packet campaign-runtime.build.json`, and after it both page-kit gates
-pass. The reverse write exists for a configured campaign: `npx campaigns-os
-spec derive --packet campaign-runtime.build.json` copies what the repo already
+command that replaces them from the CampaignSpec, `npx --no-install
+campaigns-os page-kit sync --packet campaign-runtime.build.json`, and after it
+both page-kit gates pass. The reverse write exists for a configured campaign:
+`npx --no-install campaigns-os spec derive --packet
+campaign-runtime.build.json` copies what the repo already
 states (the SDK pin, page routes, analytics ids) into the local CampaignSpec,
 and with `--write-map` records the pin in the saved Map's Build hints too, so
 a bump in the repo is one edit followed by a derive rather than a hand edit
@@ -149,12 +151,13 @@ fields, and resolve competing edits before the next build.
 
 Everything after `start` is agent-driven: after `start`
 and after every stage, run `next` and do what it prints — it names the skill
-and the exact commands for the next stage, already spelled `npx campaigns-os
-…` for this install, which is why `install-skills` comes first. The browser
-for polish capture and QA is a one-time `npx campaigns-os qa install-browser`,
-which installs the browser for the Playwright this toolkit bundles. A pin
-older than that command shows `npx playwright install chromium` instead; that
-is equivalent only when `npx playwright` resolves to the toolkit's Playwright
+and the exact commands for the next stage, already spelled `npx --no-install
+campaigns-os …` for this install, which is why `install-skills` comes first.
+Releases before 1.41.2 print the same commands without `--no-install`; add it
+when you copy one. The browser for polish capture and QA is a one-time
+`npx --no-install campaigns-os qa install-browser`, which installs the browser
+for the Playwright this toolkit bundles. A pin older than that command shows
+`npx playwright install chromium` instead; that is equivalent only when `npx playwright` resolves to the toolkit's Playwright
 (a campaign that depends on its own Playwright version gets that one's
 browser instead), so prefer `qa install-browser` on pins that have it.
 
@@ -163,9 +166,9 @@ browser instead), so prefer `qa install-browser` on pins that have it.
 The pinned devDependency above is the primary path. To change the toolkit, use
 a checkout ([docs/quickstart.md](docs/quickstart.md)): every `npm run
 campaigns-os -- <command> …` example in this repository is that checkout form,
-and from a campaign folder the same command is `npx campaigns-os <command> …`
-with identical arguments (`npm run qa:install-browser` is the checkout's
-`qa install-browser`).
+and from a campaign folder the same command is
+`npx --no-install campaigns-os <command> …` with identical arguments (`npm run
+qa:install-browser` is the checkout's `qa install-browser`).
 
 From a checkout, the same first run uses the bundled example inputs:
 
@@ -288,9 +291,10 @@ checks that the package metadata, CLI entrypoint, and installed Campaigns OS
 skills agree. For a checkout it also reports branch, upstream, and ahead/behind;
 for a package install the pinned commit is the freshness answer, and there is
 no npm dist-tag to compare against. Neither mode makes agent skills current on
-its own: when skills are stale, run `install-skills --platform all` through the
-same prefix you ran `tooling status` with (the status output prints the exact
-command) and restart local agent sessions.
+its own: when skills are stale, run the refresh command the status output
+prints (it names each stale platform, through the same prefix you ran
+`tooling status` with) and restart local agent sessions. Without `--platform`,
+status checks only the platforms where Campaigns OS skills are installed.
 
 Run `campaigns-os qa install-browser` (`npm run qa:install-browser` from a
 checkout) once after install/update and before mandatory `polish capture` or
@@ -356,11 +360,14 @@ See [`campaign-spec/README.md`](campaign-spec/README.md).
 - [Setup Profile Parity](docs/setup-profile-parity.md)
 - [Developer Evaluation](docs/developer-evaluation.md)
 - [QA And Test Orders](docs/qa-and-test-orders.md)
+- [Run-Artifact Readback](docs/readback.md) — `campaigns-os readback`: a read-only projection of one run's emitted artifacts, with per-artifact freshness against the checkout and a versioned JSON contract to gate on
+- [Declared Command Effects](docs/effects.md) — what every supported invocation writes and sends, one row per command and effect-changing flag, each row proved by a test that runs the real CLI in a disposable target
 - [Legacy Migration Contract](docs/legacy-migration.md) — pure inventory, preview-plan, receipt, Offer request/readback, and token-free evidence helpers for bounded SDK 0.3.x shadow migrations
 - [Template Family vs Figma-extraction vs Hybrid](docs/template-vs-extraction-decision.md) — when to mint a template family, when to extract a bespoke design, and when to do both
 - [Small PR Review Path](docs/small-pr-review-path.md)
 - [Run Telemetry](docs/workflow-findings-sidecar.md) — per-run Run Record (system signal + workflow findings) tagged by improvement surface; captured locally always, remitted to Next Commerce only with up-front opt-out consent
 - [Versioning](docs/versioning.md)
+- [ADR 0002: One shipping path](docs/adr/0002-one-shipping-path-campaigns-agent-fold.md) — decides that the agent surface (skills, charter, declared effects, readback) lives in this repository; Campaigns Agent folds in
 
 ## Status
 

package/contracts/agent-relevant-change-policy.v1.json

@@ -59,8 +59,19 @@
     { "match": { "kind": "exact", "value": "contracts/agent-relevant-change-policy.v1.json" }, "class": "compatibility_policy" },
     { "match": { "kind": "exact", "value": "contracts/orientation-limits.v1.json" }, "class": "compatibility_policy" },
     { "match": { "kind": "exact", "value": "contracts/orientation-reason-codes.v1.json" }, "class": "compatibility_policy" },
+    { "match": { "kind": "exact", "value": "contracts/effects.v1.json" }, "class": "compatibility_policy" },
     { "match": { "kind": "exact", "value": "bin/campaigns-os.mjs" }, "class": "cli_surface" },
     { "match": { "kind": "exact", "value": "src/cli.mjs" }, "class": "cli_surface" },
+    {
+      "match": { "kind": "prefix", "value": "src/agent/" },
+      "class": "cli_surface",
+      "_note": "The agent-facing entry points (skill install, agent context, the tooling-status revision check) are reachable from the supported argv surface, so a change under src/agent/ is a CLI-surface change even though the rest of src/ is unsupported implementation. This rule sits ahead of the broad src/ ignore on purpose: the ignore's reason is 'implementation reachable only through declared package exports', which is exactly what this subtree is not."
+    },
+    {
+      "match": { "kind": "prefix", "value": "agents/" },
+      "class": "documentation",
+      "_note": "The per-platform agent instruction files an agent orients on (and that `install-agent-context` copies into a target repo). They were ignored as 'illustrative' while nothing consumed them; they are now named supported surface, so a change to one is a documentation change a consumer can see."
+    },
     { "match": { "kind": "exact", "value": "skills.json" }, "class": "skill" },
     { "match": { "kind": "exact", "value": "skills.sh" }, "class": "skill" },
     { "match": { "kind": "prefix", "value": "skills/" }, "class": "skill" },
@@ -92,7 +103,6 @@
     { "match": { "kind": "prefix", "value": "campaign-spec/" }, "reason": "Tests, fixtures, and packaging metadata for the generated runtime. The runtime sources a consumer must rebuild are classified by the generated_runtime rule first; only that rule's exclusions reach here." },
     { "match": { "kind": "prefix", "value": "examples/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
     { "match": { "kind": "prefix", "value": "prompts/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
-    { "match": { "kind": "prefix", "value": "agents/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
     { "match": { "kind": "prefix", "value": "docs/adr/" }, "reason": "Architecture decision records: rationale, not a consumed contract." },
     { "match": { "kind": "prefix", "value": "docs/" }, "reason": "Documentation that is not on the named supported surface and not an agent document of record. Named docs are classified by the derived pass first." },
     { "match": { "kind": "exact", "value": "README.md" }, "reason": "Repository front page; the agent entry point is AGENTS.md." },