@nextcommerce/campaigns-os 1.37.3 → 1.43.1

package/README.md

@@ -5,8 +5,8 @@ Campaigns OS is the developer toolkit for agent-assisted campaign builds on [Nex
 This toolkit gives campaign developers and AI coding tools a clear path for assembling one from prepared page files:
 
 1. Configure the campaign in the Next Commerce dashboard (Campaigns App).
-2. Create or review the Campaign Map in [Campaign Map Builder](https://campaign-map.nextcommerce.com).
-3. Export a local CampaignSpec JSON.
+2. Use the current saved Map in [Campaign Map Builder](https://campaign-map.nextcommerce.com), or have the coding agent author a [local CampaignSpec](docs/build-packet.md#local-spec-entry) from the brief and verified campaign values.
+3. Keep the CampaignSpec JSON with its saved Map ID or stable `local_spec_id`, plus its public route slug.
 4. Bring prepared HTML/CSS/assets for the campaign pages.
 5. Provide or generate a [Campaign Build Brief](./docs/campaign-build-brief.md) for merchandising/design presentation decisions.
 6. Create and doctor a Build Packet.
@@ -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`,
@@ -44,8 +48,8 @@ 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.37.3
-npx campaigns-os tooling status --platform claude
-npx campaigns-os install-skills --platform claude
+npx --no-install campaigns-os tooling status --platform claude
+npx --no-install campaigns-os install-skills --platform claude
 mkdir -p source
 ```
 
@@ -76,8 +80,9 @@ dist-tag for a reproducible build. Commit `package.json` and `package-lock.json`
 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, `npx campaigns-os demo --target ./apollo-sample`
-(1.37.0 or later) copies four inert Apollo pages; open the printed
+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).
@@ -101,20 +106,22 @@ 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
 `--proxy-base <origin>` when the map was saved on a non-production map store);
-`--spec <campaignspec.json>` starts from a local export instead. `--source` is
+`--spec <campaignspec.json>` starts from a local export or an agent-authored
+[local spec](docs/build-packet.md#local-spec-entry) instead. Local-spec identity
+requires a reviewed 1.43.0-or-later release. `--source` is
 always required: the folder of prepared HTML/CSS/assets for the pages you are
 building, with a source manifest that carries desktop and mobile screenshot
 proof for each designed page
@@ -127,10 +134,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
@@ -145,12 +153,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.
 
@@ -159,9 +168,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:
 
@@ -221,7 +230,7 @@ Then ask your AI tool to continue from the emitted handoff. Fresh target repos u
 
 ## Source Files
 
-The current source adapter is `html_funnel`: bring prepared HTML/CSS/assets for the campaign pages, plus a local exported CampaignSpec from Campaign Map Builder.
+The current source adapter is `html_funnel`: bring prepared HTML/CSS/assets for the campaign pages, plus a CampaignSpec exported from Campaign Map Builder or authored by the coding agent through the [local-spec entry](docs/build-packet.md#local-spec-entry).
 
 For raw AI-generated or exported static HTML, "prepared" means page-kit-ready
 source, not a browser document dropped in unchanged and not a wholesale Liquid
@@ -284,9 +293,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
@@ -352,11 +362,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/agents/claude/CLAUDE.md

@@ -1,6 +1,10 @@
 # Campaigns OS Agent Context
 
-You are helping assemble a NEXT campaign through Campaigns OS. Start from the Build Packet, not from private runtime source.
+You are helping assemble a NEXT campaign through Campaigns OS. Use the
+`next-campaigns-os` skill from this project's pinned toolkit. When a Build
+Packet exists, read it and follow `next`. Check the loaded skill's bundle
+revision and restart the session if it differs from the
+project copy. Do not use private runtime source as the campaign's starting point.
 
 Core rules:
 

package/campaign-spec/dist/types.d.ts

@@ -593,6 +593,8 @@ export interface AnalyticsContract {
  * local-experimental.
  */
 export interface SpecIdentity {
+    /** Stable agent-authored identity when there is no saved Map. */
+    local_spec_id?: string;
     map_id?: string;
     source?: string;
     id?: string;

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." },