@nextcommerce/campaigns-os 1.34.1 → 1.37.1

package/AGENTS.md

@@ -61,19 +61,48 @@ is a refusal, not a value to interpret. And a prepared runtime can build and
 type-check but **cannot run browser QA** — preparation suppresses lifecycle
 scripts, which is also what suppresses the browser download.
 
-The recipe describes preparing a runtime from a **checkout**. The supported
-way to *run* the toolkit without a checkout is as a **pinned devDependency of
-the campaign folder** (a page-kit project): `npm i -D
-"github:NextCommerceCo/campaigns-os#<sha>"` there, then `npx campaigns-os …`
-from that folder. The same pin discipline applies — the sha is the one you
-oriented on — and npm records the resolved commit in that folder's
-`package.json` and `package-lock.json`, so CI and the deploy host install the
-same commit and `tooling status` reads the pin back (`Install mode: package
-install …`). It runs the package's own lifecycle script at install time, so it
-is not a recipe execution and makes no claim under the recipe's output
-checks. Every command the toolkit prints for you to copy is spelled for the
-install it came from (`npx campaigns-os …` there). A recipe kind for package
-installs is not published yet.
+The recipe describes preparing a runtime from a **checkout**. The primary
+way to *run* the toolkit is an **exact project-local devDependency** in the
+campaign's Page Kit folder: `npm install --save-dev --save-exact
+@nextcommerce/campaigns-os@<reviewed-version>`, then `npx campaigns-os …` from
+that folder. Review the release's source tag and provenance against the commit
+you oriented on; installation cannot supply its own trust decision. Commit
+`package.json` and `package-lock.json` so other hosts install the same bytes.
+For an unreleased reviewed commit use `npm install --save-dev --save-exact
+"github:NextCommerceCo/campaigns-os#<full-sha>"` instead. Both run package
+lifecycle scripts and are separate from this checkout-only recipe.
+
+An exact global registry install is also supported:
+`npm install -g @nextcommerce/campaigns-os@<reviewed-version>`. `tooling status`
+reports whether the installation is local, global, or a checkout, its version,
+and a source commit when derivable. It does not check registry currency. Use
+its printed invocation to avoid another installation on PATH; a project-local
+installation prints `npx campaigns-os`, while a shadowed global copy prints an
+explicit invocation of that copy. Use `--platform claude` or `--platform codex`
+consistently for profile-only setup and preflight, and install bundled skills
+before following the stage recommendations. Browser proof uses the package's
+`qa install-browser`; optional Playwright absence does not block other commands.
+
+[Activation, access, and evidence](docs/activation-and-evidence.md) describes
+public milestones without introducing another lifecycle. For support,
+`tooling diagnose [--packet <packet>] [--platform <profile>] [--json]` reads
+status and the read-only doctor's existing `next` recommendation and exports a
+strict allowlist summary. It neither establishes orientation trust nor changes
+campaign evidence or run sessions. See [diagnostics](docs/diagnostics.md).
+
+Candidate 1.36.0 also records minimal progress observations after canonical
+`next` and committed QA. Run `next` after agent-owned stages to observe their
+reports. `--no-write` disables capture and send; `--no-remit` keeps it local.
+The portable `./progress` contract preserves separate saved Map, semantic spec
+and output identities, and grants no orientation or deployment trust. See
+[progress snapshots](docs/progress-snapshots.md).
+
+Candidate 1.37.0 adds `demo --target <new-directory>`, an offline visual sample
+that copies a pinned inert Apollo bundle and prints its landing/index.html path.
+It bypasses session recovery and creates no campaign evidence or telemetry.
+Unsupported flags, including no-write and dry-run, are rejected before writes.
+Start real work in a separate new Page Kit folder and preserve sample edits.
+See [offline demo preview](docs/demo-preview.md).
 
 ## Supported versus internal
 

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.37.1] - 2026-09-18
+
+### Fixed
+
+- Demo copies that detect a changed destination explain how to preserve its
+  files and retry with a different new directory. Ownership checks and cleanup
+  remain unchanged; a replacement-directory regression proves copying stops
+  after the first write and preserves files authored in the replacement.
+- Clarify that demo raw arguments are validated in the CLI entry point before
+  the private dispatcher rechecks the parsed shape and extracts the target.
+
+## [1.37.0] - 2026-09-18
+
+### Added
+
+- `demo --target <new-directory>` copies four pinned inert Apollo sample pages
+  for direct local-file exploration, with active sample navigation, disabled
+  commerce controls, local assets and restrictive CSP. It downloads nothing,
+  bypasses session recovery, and emits no campaign evidence or telemetry.
+- Exclusive target creation refuses existing files, directories and symlinks.
+  Failed copies clean only owned entries; unsupported flags fail before writes.
+  A hashed provenance manifest and retained notices document the static projection,
+  pinned published Page Kit toolchain, build-time CSS and system font fallback.
+  Real campaigns begin separately, preserving sample edits.
+
+## [1.36.0+agent.1] - 2026-09-18
+
+### Fixed
+
+- Progress treats a missing Build Context packet pointer as unconfirmed binding
+  and refuses its source endpoint. Sequence allocation recovers dead owners while
+  preserving live writers; interrupted recovery has an explicit offline procedure.
+- Integration coverage now observes the actual next picker and committed QA with
+  complete local spec/build identity, then independently changes each binding.
+
+## [1.36.0] - 2026-09-18
+
+### Added
+
+- Minimal progress snapshots observe canonical next-stage recommendations and
+  committed QA without replacing lifecycle rules or altering closeout. Separate
+  saved Map, semantic spec and output identities prevent completion claims from
+  crossing builds. A strict portable progress export, v0 schema and example
+  fixture support receiver validation and grouped histories without readiness
+  inference.
+- Immutable local capture precedes consent-scoped delivery to the planned
+  progress receiver. Bounded retry preserves exact bytes and requires a matching
+  digest acknowledgment; failures leave the lifecycle result unchanged.
+  No-write disables capture/send and no-remit keeps observations local.
+
+### Changed
+
+- Telemetry disclosure includes minimal stage observations intended for Workspace.
+  Noncanonical progress sharing requires explicit scoped opt-in; unscoped
+  environment ON does not bypass that protection. Fetched Map provenance retains
+  its original saved hash and local baseline separately from raw spec bytes.
+
+## [1.35.0] - 2026-09-18
+
+### Added
+
+- A public activation/access/evidence contract separates installed tooling,
+  demo previews, saved Maps, resolved campaigns, observed previews, and recorded
+  QA while preserving the existing lifecycle and independent trust/freshness
+  and revision checks.
+- `tooling diagnose [--packet <packet>] [--platform <profile>] [--json]`
+  projects installation status and the read-only doctor's next recommendation
+  into a compact support export. A fixed allowlist excludes paths, URLs,
+  credentials, identities, order values, content, argv, and environment.
+  Unknown producer values receive fixed markers and no repair authority.
+  Diagnosis never sweeps sessions, writes evidence, runs orders, or publishes.
+
+### Changed
+
+- Exact npm project-local devDependency installation is the primary public
+  path; exact global releases and reviewed full-SHA sources remain supported.
+  Installed skills use the package-owned browser command and explain invocation
+  translation for local, global, and contributor installations.
+
+### Fixed
+
+- Global npm installations are distinguished from campaign-local dependencies.
+  Global recovery commands address the inspected copy even when another
+  installation shadows it; project-local commands continue to resolve via npx.
+  Publication recovery continues to use `qa publish` on retained evidence,
+  without repeating checkout or placing another order.
+
 ## [1.34.1+agent.1] - 2026-09-18
 
 ### Changed

package/README.md

@@ -19,28 +19,31 @@ This toolkit gives campaign developers and AI coding tools a clear path for asse
 
 The toolkit is contract-backed: starter templates describe which parts are reusable page structure, which parts are live commerce wiring, and which demo values must be replaced for a real campaign. That helps AI tools avoid common mistakes like carrying over sample package IDs, copying shipping options from the wrong template shape, or editing SDK-owned checkout surfaces as plain HTML.
 
+See [activation, access, and evidence](docs/activation-and-evidence.md) for what
+installation, a saved Map, preview observation, and recorded QA each establish.
+
 ## Quick Start
 
 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`,
-so CI and the deploy host install the same commit. Requirements: Node
+`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:
 
 1. **Orient before you run anything.** Read
    [`AGENTS.md`](AGENTS.md), `contracts/supported-surface.json`,
    `contracts/release-ledger.json` and `CHANGELOG.md` on GitHub at one commit,
-   and keep that commit's sha. Orientation is a read of declarative data; it
+   using the canonical reading order in `AGENTS.md`, and keep that commit's sha. Orientation is a read of declarative data; it
    never executes toolkit code.
-2. **Pin the toolkit and install its agent skills** from that same commit.
-3. **Start a build** from that same commit.
+2. **Pin the reviewed release and install its agent skills.** Check the release tag/provenance against the reviewed source commit.
+3. **Start a real campaign build** from that installation.
 
 ```bash
 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 i -D "github:NextCommerceCo/campaigns-os#<sha>"
+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
 mkdir -p source
@@ -50,8 +53,9 @@ 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
+npm install -g @nextcommerce/campaigns-os@1.34.1
 campaigns-os tooling status --platform claude
+campaigns-os install-skills --platform claude
 ```
 
 A global install ships without a browser. Polish capture and QA need the
@@ -65,22 +69,37 @@ 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`). `#<sha>` is
-the commit you oriented on, so the code that runs is the code whose contracts
-you read; npm records the resolved commit in the folder's `package.json` and
-`package-lock.json`, which is how `tooling status` can print `Install mode:
-package install (node_modules), pinned at <version> @ <sha>`. The install runs
-the package's own build step (about 7 s). On a fresh profile that first
-`tooling status --platform claude` exits 2 with `ATTENTION_REQUIRED` and one
-action, the `install-skills` line — it is telling you the skills are not
-installed yet, not that the install failed; run it again after
-`install-skills` for `READY`. Without `--platform`, status checks every agent
-profile (Claude, Codex, shared) and stays at exit 2 until each is installed.
+(its `package.json` already declares `next-campaign-page-kit`). `1.34.1` 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.
+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
+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
+install mode, package version, and a source commit when derivable. It does not
+check registry currency or establish trust. On a fresh profile, preflight exits
+2 with `ATTENTION_REQUIRED` until that profile's skills are installed. Run
+`tooling status --platform claude` again after `install-skills` for `READY`;
+use `--platform codex` for a Codex-only profile. Without `--platform`, status
+checks every supported agent profile.
 `install-skills` writes `~/.claude/skills` (`--platform codex` writes
 `~/.codex/skills`), replacing same-name folders; restart the agent after.
+Run commands from the campaign folder: `npx` selects its local installation
+even when another global copy is on PATH. A global-only installation prints
+bare commands when its binary matches PATH, or an explicit `node` invocation
+when another install shadows it.
 Prepared page HTML goes in `./source`, which must exist even when every page is
-template stock. To move to a newer commit, re-orient on it and run `npm i -D
-"github:NextCommerceCo/campaigns-os#<new-sha>"` again.
+template stock. To update, review the new release source and install its exact version again.
 
 > **Heads up — `start` turns on run telemetry, and remit is ON by default.**
 > The first `start` opens a run session in the target folder and, unless you

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

@@ -87,6 +87,7 @@
     { "match": { "kind": "prefix", "value": "contracts/fixtures/" }, "reason": "Test fixtures. Consumer-facing fixtures reach the supported surface through contracts/supported-surface.json named[], which the derived pass classifies first." },
     { "match": { "kind": "prefix", "value": "fixtures/" }, "reason": "Test fixtures." },
     { "match": { "kind": "prefix", "value": "scripts/" }, "reason": "Repository checkers. Explicitly unsupported implementation (docs/supported-surface.md)." },
+    { "match": { "kind": "prefix", "value": "demo/" }, "reason": "Static projection implementation copied by the supported demo command; the declared provenance manifest pins all output digests. Named and hashed entries are classified by the derived supported-surface pass first." },
     { "match": { "kind": "prefix", "value": "src/" }, "reason": "Implementation. Explicitly unsupported except through declared package exports, which package.json changes classify." },
     { "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)." },

package/contracts/fixtures/progress/observation.v0.json

@@ -0,0 +1,89 @@
+{
+  "schema_version": "campaigns-os-progress-snapshot/v0",
+  "stream_id": "progress_11111111111111111111111111111111",
+  "sequence": 1,
+  "previous_snapshot_id": null,
+  "observed_at": "2026-09-18T00:00:00.000Z",
+  "package_version": "1.36.0",
+  "producer": "next",
+  "identity": {
+    "map_id": "example-map",
+    "map_revision_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "map_revision_algorithm": "map-store-v1",
+    "saved_revision_alignment": "aligned",
+    "local_spec_material_hash": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "local_spec_material_algorithm": "campaign-spec-material-v1",
+    "build_fingerprint": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+    "build_fingerprint_algorithm": "sha256-manifest/v1"
+  },
+  "stages": [
+    {
+      "stage": "prepare_build",
+      "status": "completed",
+      "build_binding": "unconfirmed",
+      "source_build_fingerprint": null
+    },
+    {
+      "stage": "setup",
+      "status": "completed",
+      "build_binding": "unconfirmed",
+      "source_build_fingerprint": null
+    },
+    {
+      "stage": "assembly",
+      "status": "completed",
+      "build_binding": "matching",
+      "source_build_fingerprint": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    {
+      "stage": "polish",
+      "status": "pending",
+      "build_binding": "unconfirmed",
+      "source_build_fingerprint": null
+    },
+    {
+      "stage": "deploy",
+      "status": "pending",
+      "build_binding": "unconfirmed",
+      "source_build_fingerprint": null
+    },
+    {
+      "stage": "qa",
+      "status": "pending",
+      "build_binding": "unconfirmed",
+      "source_build_fingerprint": null
+    }
+  ],
+  "preview": {
+    "present": false,
+    "url_hash": null
+  },
+  "continuation": {
+    "stage": "polish",
+    "blocked": false,
+    "divergent": false,
+    "action_ids": [
+      "polish_skill"
+    ],
+    "gates": [
+      {
+        "id": "doctor",
+        "state": "pass"
+      },
+      {
+        "id": "prepare_build",
+        "state": "pass"
+      },
+      {
+        "id": "theme_gate",
+        "state": "waived"
+      },
+      {
+        "id": "polish_gate",
+        "state": "not_applicable"
+      }
+    ]
+  },
+  "qa": null,
+  "snapshot_id": "sha256:f52f2418c30e6696471fbcc86dcc3fc28caa7e17df9151b58d150747dd3f48fb"
+}