@nextcommerce/campaigns-os 1.34.1 → 1.37.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/AGENTS.md +42 -13
  2. package/CHANGELOG.md +117 -0
  3. package/README.md +48 -21
  4. package/contracts/agent-relevant-change-policy.v1.json +1 -0
  5. package/contracts/campaign-cart-sdk-support-policy.v0.json +2 -2
  6. package/contracts/commerce-surface-catalog.json +31 -29
  7. package/contracts/fixtures/progress/observation.v0.json +89 -0
  8. package/contracts/release-ledger.json +425 -0
  9. package/contracts/supported-surface.json +20 -5
  10. package/contracts/template-brand-contract.shared-commerce.v0.json +1 -1
  11. package/demo/apollo-v0/NOTICE.txt +51 -0
  12. package/demo/apollo-v0/assets/css/demo.css +2 -0
  13. package/demo/apollo-v0/assets/css/landing/tokens.css +35 -0
  14. package/demo/apollo-v0/assets/css/next-core.css +16124 -0
  15. package/demo/apollo-v0/assets/images/1x1_1.svg +19 -0
  16. package/demo/apollo-v0/assets/images/1x1_2.svg +19 -0
  17. package/demo/apollo-v0/assets/images/affirm-logo.svg +24 -0
  18. package/demo/apollo-v0/assets/images/apple-pay-logo.svg +4 -0
  19. package/demo/apollo-v0/assets/images/bancontact-logo.svg +1 -0
  20. package/demo/apollo-v0/assets/images/cc-visa.svg +28 -0
  21. package/demo/apollo-v0/assets/images/cc_amex.svg +20 -0
  22. package/demo/apollo-v0/assets/images/cc_discover.svg +21 -0
  23. package/demo/apollo-v0/assets/images/cc_master.svg +22 -0
  24. package/demo/apollo-v0/assets/images/credit-card-flags.svg +38 -0
  25. package/demo/apollo-v0/assets/images/demo-inline-40788e52a7c75b78.svg +1 -0
  26. package/demo/apollo-v0/assets/images/demo-inline-686e73c8840a0f0a.svg +1 -0
  27. package/demo/apollo-v0/assets/images/google-pay-logo.svg +7 -0
  28. package/demo/apollo-v0/assets/images/guarantee-badge.png +0 -0
  29. package/demo/apollo-v0/assets/images/icon-dollar.svg +5 -0
  30. package/demo/apollo-v0/assets/images/icon-guarantee.svg +5 -0
  31. package/demo/apollo-v0/assets/images/icon-shipping.svg +5 -0
  32. package/demo/apollo-v0/assets/images/icons8-lock-24_1icons8-lock-24.png +0 -0
  33. package/demo/apollo-v0/assets/images/ideal-logo.svg +30 -0
  34. package/demo/apollo-v0/assets/images/klarna-logo.svg +9 -0
  35. package/demo/apollo-v0/assets/images/landing/_shared/16x9.svg +19 -0
  36. package/demo/apollo-v0/assets/images/landing/_shared/1x1_1.svg +19 -0
  37. package/demo/apollo-v0/assets/images/landing/_shared/4x3.svg +19 -0
  38. package/demo/apollo-v0/assets/images/landing/_shared/arrow-right.svg +6 -0
  39. package/demo/apollo-v0/assets/images/landing/_shared/cta-guarantee-icon.png +0 -0
  40. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-icon-1.svg +8 -0
  41. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-icon-2.svg +10 -0
  42. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-icon-3.svg +13 -0
  43. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-icon-4.svg +11 -0
  44. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-quote.svg +6 -0
  45. package/demo/apollo-v0/assets/images/landing/benefits-2/benefits-2-verified.svg +10 -0
  46. package/demo/apollo-v0/assets/images/landing/bottomcta-1/check-bullet.svg +5 -0
  47. package/demo/apollo-v0/assets/images/landing/faq-1/faq-chevron.svg +6 -0
  48. package/demo/apollo-v0/assets/images/landing/footer-1/footer-logo.png +0 -0
  49. package/demo/apollo-v0/assets/images/landing/guarantee-1/guarantee-1-badge.svg +8 -0
  50. package/demo/apollo-v0/assets/images/landing/hero-1/icon-check.svg +5 -0
  51. package/demo/apollo-v0/assets/images/landing/hero-1/icon-star.svg +6 -0
  52. package/demo/apollo-v0/assets/images/landing/hero-1/icon-verified.svg +6 -0
  53. package/demo/apollo-v0/assets/images/landing/icons-5/icon-batteries.svg +7 -0
  54. package/demo/apollo-v0/assets/images/landing/icons-5/icon-cuff-checking.svg +6 -0
  55. package/demo/apollo-v0/assets/images/landing/icons-5/icon-dual-user.svg +5 -0
  56. package/demo/apollo-v0/assets/images/landing/icons-5/icon-fda-cleared.svg +5 -0
  57. package/demo/apollo-v0/assets/images/landing/icons-5/icon-heartbeat.svg +17 -0
  58. package/demo/apollo-v0/assets/images/landing/icons-5/icon-lcd-display.svg +10 -0
  59. package/demo/apollo-v0/assets/images/landing/icons-5/icon-movement-error.svg +7 -0
  60. package/demo/apollo-v0/assets/images/landing/icons-5/icon-portable.png +0 -0
  61. package/demo/apollo-v0/assets/images/landing/icons-5/icon-reading-memory.svg +6 -0
  62. package/demo/apollo-v0/assets/images/landing/icons-5/icon-wrist-comfort.svg +5 -0
  63. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-card-1.jpg +0 -0
  64. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-card-2.jpg +0 -0
  65. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-card-3.jpg +0 -0
  66. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-card-4.jpg +0 -0
  67. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-1.png +0 -0
  68. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-2.png +0 -0
  69. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-3.png +0 -0
  70. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-4.png +0 -0
  71. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-5.png +0 -0
  72. package/demo/apollo-v0/assets/images/landing/ingredients-3/ingredients-3-promise-6.png +0 -0
  73. package/demo/apollo-v0/assets/images/landing/nav-1/flag-us.png +0 -0
  74. package/demo/apollo-v0/assets/images/landing/reviews-3/star-card.svg +3 -0
  75. package/demo/apollo-v0/assets/images/landing/reviews-3/star-lg.svg +3 -0
  76. package/demo/apollo-v0/assets/images/landing/reviews-3/star-sm.svg +3 -0
  77. package/demo/apollo-v0/assets/images/landing/reviews-3/verified.svg +10 -0
  78. package/demo/apollo-v0/assets/images/landing/testimonials-2/testimonials-2-reactions.svg +9 -0
  79. package/demo/apollo-v0/assets/images/landing/testimonials-2/testimonials-2-stars.svg +6 -0
  80. package/demo/apollo-v0/assets/images/link-logo.svg +1 -0
  81. package/demo/apollo-v0/assets/images/next-dark.svg +8 -0
  82. package/demo/apollo-v0/assets/images/paypal-logo.svg +5 -0
  83. package/demo/apollo-v0/assets/images/paypal-txt.svg +8 -0
  84. package/demo/apollo-v0/assets/images/paypal.svg +22 -0
  85. package/demo/apollo-v0/assets/images/sepa-logo.svg +275 -0
  86. package/demo/apollo-v0/assets/images/twint-logo.svg +1 -0
  87. package/demo/apollo-v0/assets/images/united-states-flag-icon.webp +0 -0
  88. package/demo/apollo-v0/assets/images/upsell-payment-logos.svg +38 -0
  89. package/demo/apollo-v0/assets/images/usps.png +0 -0
  90. package/demo/apollo-v0/checkout/index.html +1370 -0
  91. package/demo/apollo-v0/landing/index.html +1836 -0
  92. package/demo/apollo-v0/provenance.json +342 -0
  93. package/demo/apollo-v0/receipt/index.html +292 -0
  94. package/demo/apollo-v0/upsell-bundle-stepper/index.html +401 -0
  95. package/docs/activation-and-evidence.md +37 -0
  96. package/docs/build-packet.md +107 -0
  97. package/docs/demo-preview.md +63 -0
  98. package/docs/diagnostics.md +55 -0
  99. package/docs/orientation-contract-reference.md +2 -1
  100. package/docs/progress-snapshots.md +142 -0
  101. package/docs/runtime-readiness.md +1 -1
  102. package/docs/supported-surface.md +13 -1
  103. package/package.json +13 -3
  104. package/schemas/campaign-runtime-build-context.v0.schema.json +42 -0
  105. package/schemas/campaigns-os-progress-snapshot.v0.schema.json +370 -0
  106. package/skills/next-campaigns-build/SKILL.md +17 -1
  107. package/skills/next-campaigns-os/SKILL.md +19 -3
  108. package/skills/next-campaigns-os-setup/SKILL.md +17 -1
  109. package/skills/next-campaigns-polish/SKILL.md +18 -2
  110. package/skills/next-campaigns-qa/SKILL.md +24 -8
  111. package/skills.json +5 -5
  112. package/src/cli.mjs +74 -4
  113. package/src/consent.mjs +2 -2
  114. package/src/demo-artifact.mjs +97 -0
  115. package/src/demo.mjs +85 -0
  116. package/src/diagnostic.mjs +101 -0
  117. package/src/install-mode.mjs +13 -1
  118. package/src/progress-node.mjs +177 -0
  119. package/src/progress.mjs +133 -0
package/AGENTS.md CHANGED
@@ -61,19 +61,48 @@ is a refusal, not a value to interpret. And a prepared runtime can build and
61
61
  type-check but **cannot run browser QA** — preparation suppresses lifecycle
62
62
  scripts, which is also what suppresses the browser download.
63
63
 
64
- The recipe describes preparing a runtime from a **checkout**. The supported
65
- way to *run* the toolkit without a checkout is as a **pinned devDependency of
66
- the campaign folder** (a page-kit project): `npm i -D
67
- "github:NextCommerceCo/campaigns-os#<sha>"` there, then `npx campaigns-os …`
68
- from that folder. The same pin discipline applies — the sha is the one you
69
- oriented on — and npm records the resolved commit in that folder's
70
- `package.json` and `package-lock.json`, so CI and the deploy host install the
71
- same commit and `tooling status` reads the pin back (`Install mode: package
72
- install …`). It runs the package's own lifecycle script at install time, so it
73
- is not a recipe execution and makes no claim under the recipe's output
74
- checks. Every command the toolkit prints for you to copy is spelled for the
75
- install it came from (`npx campaigns-os …` there). A recipe kind for package
76
- installs is not published yet.
64
+ The recipe describes preparing a runtime from a **checkout**. The primary
65
+ way to *run* the toolkit is an **exact project-local devDependency** in the
66
+ campaign's Page Kit folder: `npm install --save-dev --save-exact
67
+ @nextcommerce/campaigns-os@<reviewed-version>`, then `npx campaigns-os …` from
68
+ that folder. Review the release's source tag and provenance against the commit
69
+ you oriented on; installation cannot supply its own trust decision. Commit
70
+ `package.json` and `package-lock.json` so other hosts install the same bytes.
71
+ For an unreleased reviewed commit use `npm install --save-dev --save-exact
72
+ "github:NextCommerceCo/campaigns-os#<full-sha>"` instead. Both run package
73
+ lifecycle scripts and are separate from this checkout-only recipe.
74
+
75
+ An exact global registry install is also supported:
76
+ `npm install -g @nextcommerce/campaigns-os@<reviewed-version>`. `tooling status`
77
+ reports whether the installation is local, global, or a checkout, its version,
78
+ and a source commit when derivable. It does not check registry currency. Use
79
+ its printed invocation to avoid another installation on PATH; a project-local
80
+ installation prints `npx campaigns-os`, while a shadowed global copy prints an
81
+ explicit invocation of that copy. Use `--platform claude` or `--platform codex`
82
+ consistently for profile-only setup and preflight, and install bundled skills
83
+ before following the stage recommendations. Browser proof uses the package's
84
+ `qa install-browser`; optional Playwright absence does not block other commands.
85
+
86
+ [Activation, access, and evidence](docs/activation-and-evidence.md) describes
87
+ public milestones without introducing another lifecycle. For support,
88
+ `tooling diagnose [--packet <packet>] [--platform <profile>] [--json]` reads
89
+ status and the read-only doctor's existing `next` recommendation and exports a
90
+ strict allowlist summary. It neither establishes orientation trust nor changes
91
+ campaign evidence or run sessions. See [diagnostics](docs/diagnostics.md).
92
+
93
+ Candidate 1.36.0 also records minimal progress observations after canonical
94
+ `next` and committed QA. Run `next` after agent-owned stages to observe their
95
+ reports. `--no-write` disables capture and send; `--no-remit` keeps it local.
96
+ The portable `./progress` contract preserves separate saved Map, semantic spec
97
+ and output identities, and grants no orientation or deployment trust. See
98
+ [progress snapshots](docs/progress-snapshots.md).
99
+
100
+ Candidate 1.37.0 adds `demo --target <new-directory>`, an offline visual sample
101
+ that copies a pinned inert Apollo bundle and prints its landing/index.html path.
102
+ It bypasses session recovery and creates no campaign evidence or telemetry.
103
+ Unsupported flags, including no-write and dry-run, are rejected before writes.
104
+ Start real work in a separate new Page Kit folder and preserve sample edits.
105
+ See [offline demo preview](docs/demo-preview.md).
77
106
 
78
107
  ## Supported versus internal
79
108
 
package/CHANGELOG.md CHANGED
@@ -2,6 +2,123 @@
2
2
 
3
3
  Notable supported-surface changes are recorded here.
4
4
 
5
+ ## [1.37.2] - 2026-09-18
6
+
7
+ ### Fixed
8
+
9
+ - Refresh the public starter catalog, per-family SDK verification and CampaignSpec
10
+ examples from template commit `11352c30`. The vendored SDK policy now records
11
+ released SDK 0.4.38, so freshness compares older certification against that
12
+ release instead of reporting SDK 0.4.37 as current.
13
+ - Carry forward private families and local QA structure. Refresh Apollo Template
14
+ Reference provenance and upsell shipping-copy guidance from the same source.
15
+ Reconcile certified fixture and payment-chrome provenance with the catalog;
16
+ rendered pages, config files and payment asset hashes remain unchanged.
17
+ - Preserve the toolkit's established pre-checkout select role and authored
18
+ forward routes when refreshing the known public examples. Narrow adapters
19
+ retain unrelated source updates and leave distinct future contracts unchanged.
20
+
21
+ ## [1.37.1+agent.1] - 2026-09-18
22
+
23
+ ### Changed
24
+
25
+ - Document the page-kit change procedure after handoff: PM proposals are
26
+ reconciled against a known baseline and the current reviewed repository spec.
27
+ Conflicting authored edits require a recorded decision; generated and API-owned
28
+ fields retain their own authority. The worked example preserves a developer's
29
+ SDK upgrade and new page URL while accepting an authored upsell change.
30
+ - Keep Map pin write-back explicit and store refresh with the authorized operator.
31
+ The procedure names the review and evidence requirements for the next build,
32
+ including fresh fingerprints after authored-only changes. It adds no automatic
33
+ synchronization, portal writes or spec prerequisite for static SDK upgrades.
34
+
35
+ ## [1.37.1] - 2026-09-18
36
+
37
+ ### Fixed
38
+
39
+ - Demo copies that detect a changed destination explain how to preserve its
40
+ files and retry with a different new directory. Ownership checks and cleanup
41
+ remain unchanged; a replacement-directory regression proves copying stops
42
+ after the first write and preserves files authored in the replacement.
43
+ - Clarify that demo raw arguments are validated in the CLI entry point before
44
+ the private dispatcher rechecks the parsed shape and extracts the target.
45
+
46
+ ## [1.37.0] - 2026-09-18
47
+
48
+ ### Added
49
+
50
+ - `demo --target <new-directory>` copies four pinned inert Apollo sample pages
51
+ for direct local-file exploration, with active sample navigation, disabled
52
+ commerce controls, local assets and restrictive CSP. It downloads nothing,
53
+ bypasses session recovery, and emits no campaign evidence or telemetry.
54
+ - Exclusive target creation refuses existing files, directories and symlinks.
55
+ Failed copies clean only owned entries; unsupported flags fail before writes.
56
+ A hashed provenance manifest and retained notices document the static projection,
57
+ pinned published Page Kit toolchain, build-time CSS and system font fallback.
58
+ Real campaigns begin separately, preserving sample edits.
59
+
60
+ ## [1.36.0+agent.1] - 2026-09-18
61
+
62
+ ### Fixed
63
+
64
+ - Progress treats a missing Build Context packet pointer as unconfirmed binding
65
+ and refuses its source endpoint. Sequence allocation recovers dead owners while
66
+ preserving live writers; interrupted recovery has an explicit offline procedure.
67
+ - Integration coverage now observes the actual next picker and committed QA with
68
+ complete local spec/build identity, then independently changes each binding.
69
+
70
+ ## [1.36.0] - 2026-09-18
71
+
72
+ ### Added
73
+
74
+ - Minimal progress snapshots observe canonical next-stage recommendations and
75
+ committed QA without replacing lifecycle rules or altering closeout. Separate
76
+ saved Map, semantic spec and output identities prevent completion claims from
77
+ crossing builds. A strict portable progress export, v0 schema and example
78
+ fixture support receiver validation and grouped histories without readiness
79
+ inference.
80
+ - Immutable local capture precedes consent-scoped delivery to the planned
81
+ progress receiver. Bounded retry preserves exact bytes and requires a matching
82
+ digest acknowledgment; failures leave the lifecycle result unchanged.
83
+ No-write disables capture/send and no-remit keeps observations local.
84
+
85
+ ### Changed
86
+
87
+ - Telemetry disclosure includes minimal stage observations intended for Workspace.
88
+ Noncanonical progress sharing requires explicit scoped opt-in; unscoped
89
+ environment ON does not bypass that protection. Fetched Map provenance retains
90
+ its original saved hash and local baseline separately from raw spec bytes.
91
+
92
+ ## [1.35.0] - 2026-09-18
93
+
94
+ ### Added
95
+
96
+ - A public activation/access/evidence contract separates installed tooling,
97
+ demo previews, saved Maps, resolved campaigns, observed previews, and recorded
98
+ QA while preserving the existing lifecycle and independent trust/freshness
99
+ and revision checks.
100
+ - `tooling diagnose [--packet <packet>] [--platform <profile>] [--json]`
101
+ projects installation status and the read-only doctor's next recommendation
102
+ into a compact support export. A fixed allowlist excludes paths, URLs,
103
+ credentials, identities, order values, content, argv, and environment.
104
+ Unknown producer values receive fixed markers and no repair authority.
105
+ Diagnosis never sweeps sessions, writes evidence, runs orders, or publishes.
106
+
107
+ ### Changed
108
+
109
+ - Exact npm project-local devDependency installation is the primary public
110
+ path; exact global releases and reviewed full-SHA sources remain supported.
111
+ Installed skills use the package-owned browser command and explain invocation
112
+ translation for local, global, and contributor installations.
113
+
114
+ ### Fixed
115
+
116
+ - Global npm installations are distinguished from campaign-local dependencies.
117
+ Global recovery commands address the inspected copy even when another
118
+ installation shadows it; project-local commands continue to resolve via npx.
119
+ Publication recovery continues to use `qa publish` on retained evidence,
120
+ without repeating checkout or placing another order.
121
+
5
122
  ## [1.34.1+agent.1] - 2026-09-18
6
123
 
7
124
  ### Changed
package/README.md CHANGED
@@ -19,28 +19,31 @@ This toolkit gives campaign developers and AI coding tools a clear path for asse
19
19
 
20
20
  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.
21
21
 
22
+ See [activation, access, and evidence](docs/activation-and-evidence.md) for what
23
+ installation, a saved Map, preview observation, and recorded QA each establish.
24
+
22
25
  ## Quick Start
23
26
 
24
27
  You do not need to clone this repository to use it. The toolkit is pinned as a
25
28
  devDependency of the campaign folder (a page-kit project) and runs through
26
- `npx campaigns-os …` from that folder — the pin is committed in `package.json`,
27
- so CI and the deploy host install the same commit. Requirements: Node
29
+ `npx campaigns-os …` from that folder — the pin is committed in `package.json`
30
+ and the lockfile, so CI and the deploy host install the same package bytes. Requirements: Node
28
31
  `>=20.19.0` and npm 10 or 11 (Node 22 ships npm 10). Three steps, in this
29
32
  order:
30
33
 
31
34
  1. **Orient before you run anything.** Read
32
35
  [`AGENTS.md`](AGENTS.md), `contracts/supported-surface.json`,
33
36
  `contracts/release-ledger.json` and `CHANGELOG.md` on GitHub at one commit,
34
- and keep that commit's sha. Orientation is a read of declarative data; it
37
+ using the canonical reading order in `AGENTS.md`, and keep that commit's sha. Orientation is a read of declarative data; it
35
38
  never executes toolkit code.
36
- 2. **Pin the toolkit and install its agent skills** from that same commit.
37
- 3. **Start a build** from that same commit.
39
+ 2. **Pin the reviewed release and install its agent skills.** Check the release tag/provenance against the reviewed source commit.
40
+ 3. **Start a real campaign build** from that installation.
38
41
 
39
42
  ```bash
40
43
  mkdir "<route>" && cd "<route>"
41
44
  npm init -y && npm i next-campaign-page-kit
42
45
  npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"
43
- npm i -D "github:NextCommerceCo/campaigns-os#<sha>"
46
+ npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.34.1
44
47
  npx campaigns-os tooling status --platform claude
45
48
  npx campaigns-os install-skills --platform claude
46
49
  mkdir -p source
@@ -50,8 +53,9 @@ The toolkit is also published to npm as `@nextcommerce/campaigns-os`, so the
50
53
  CLI can be installed once, globally, instead of pinned per campaign:
51
54
 
52
55
  ```bash
53
- npm install -g @nextcommerce/campaigns-os
56
+ npm install -g @nextcommerce/campaigns-os@1.34.1
54
57
  campaigns-os tooling status --platform claude
58
+ campaigns-os install-skills --platform claude
55
59
  ```
56
60
 
57
61
  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
65
69
  with provenance from a second, environment-gated job.
66
70
 
67
71
  For an existing page-kit campaign, skip the first three lines and `cd` into it
68
- (its `package.json` already declares `next-campaign-page-kit`). `#<sha>` is
69
- the commit you oriented on, so the code that runs is the code whose contracts
70
- you read; npm records the resolved commit in the folder's `package.json` and
71
- `package-lock.json`, which is how `tooling status` can print `Install mode:
72
- package install (node_modules), pinned at <version> @ <sha>`. The install runs
73
- the package's own build step (about 7 s). On a fresh profile that first
74
- `tooling status --platform claude` exits 2 with `ATTENTION_REQUIRED` and one
75
- action, the `install-skills` line — it is telling you the skills are not
76
- installed yet, not that the install failed; run it again after
77
- `install-skills` for `READY`. Without `--platform`, status checks every agent
78
- profile (Claude, Codex, shared) and stays at exit 2 until each is installed.
72
+ (its `package.json` already declares `next-campaign-page-kit`). `1.34.1` is
73
+ an exact published example; choose the release you reviewed, never a floating
74
+ dist-tag for a reproducible build. Commit `package.json` and `package-lock.json`.
75
+ The new `tooling diagnose` command requires 1.35.0 or later. When that release
76
+ is not published yet, use the reviewed full-SHA source pin below; the 1.34.1
77
+ example does not include diagnostics or the global invocation rendering fix.
78
+ A Git source pin remains supported when using an unreleased reviewed commit:
79
+ `npm install --save-dev --save-exact "github:NextCommerceCo/campaigns-os#<full-sha>"`.
80
+
81
+ For a visual sample, candidate 1.37.0 adds
82
+ `npx campaigns-os demo --target ./apollo-sample`. Open the printed
83
+ `landing/index.html` directly to explore four inert Apollo pages. This command
84
+ requires a reviewed candidate or a published release at least 1.37.0; the 1.34.1
85
+ example above does not include it. It downloads nothing and creates no campaign
86
+ evidence. Keep sample edits and start a real campaign in a separate new Page Kit
87
+ folder. See [offline sample preview](docs/demo-preview.md).
88
+ The lockfile records the resolved source and integrity; `tooling status` reports
89
+ install mode, package version, and a source commit when derivable. It does not
90
+ check registry currency or establish trust. On a fresh profile, preflight exits
91
+ 2 with `ATTENTION_REQUIRED` until that profile's skills are installed. Run
92
+ `tooling status --platform claude` again after `install-skills` for `READY`;
93
+ use `--platform codex` for a Codex-only profile. Without `--platform`, status
94
+ checks every supported agent profile.
79
95
  `install-skills` writes `~/.claude/skills` (`--platform codex` writes
80
96
  `~/.codex/skills`), replacing same-name folders; restart the agent after.
97
+ Run commands from the campaign folder: `npx` selects its local installation
98
+ even when another global copy is on PATH. A global-only installation prints
99
+ bare commands when its binary matches PATH, or an explicit `node` invocation
100
+ when another install shadows it.
81
101
  Prepared page HTML goes in `./source`, which must exist even when every page is
82
- template stock. To move to a newer commit, re-orient on it and run `npm i -D
83
- "github:NextCommerceCo/campaigns-os#<new-sha>"` again.
102
+ template stock. To update, review the new release source and install its exact version again.
84
103
 
85
104
  > **Heads up — `start` turns on run telemetry, and remit is ON by default.**
86
105
  > The first `start` opens a run session in the target folder and, unless you
@@ -120,7 +139,15 @@ states (the SDK pin, page routes, analytics ids) into the local CampaignSpec,
120
139
  and with `--write-map` records the pin in the saved Map's Build hints too, so
121
140
  a bump in the repo is one edit followed by a derive rather than a hand edit
122
141
  in two tools; with `--from-store <subdomain>` and the store's Admin API read
123
- token in the environment it derives the store profile from the store as well. Everything after `start` is agent-driven: after `start`
142
+ token in the environment it derives the store profile from the store as well.
143
+ Map write-back stays explicit and pin-only.
144
+
145
+ For changes after handoff, follow the
146
+ [spec review procedure](docs/build-packet.md#changing-a-campaign-after-handoff):
147
+ apply the PM's authored changes to the current repository spec, preserve derived
148
+ fields, and resolve competing edits before the next build.
149
+
150
+ Everything after `start` is agent-driven: after `start`
124
151
  and after every stage, run `next` and do what it prints — it names the skill
125
152
  and the exact commands for the next stage, already spelled `npx campaigns-os
126
153
  …` for this install, which is why `install-skills` comes first. The browser
@@ -87,6 +87,7 @@
87
87
  { "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." },
88
88
  { "match": { "kind": "prefix", "value": "fixtures/" }, "reason": "Test fixtures." },
89
89
  { "match": { "kind": "prefix", "value": "scripts/" }, "reason": "Repository checkers. Explicitly unsupported implementation (docs/supported-surface.md)." },
90
+ { "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." },
90
91
  { "match": { "kind": "prefix", "value": "src/" }, "reason": "Implementation. Explicitly unsupported except through declared package exports, which package.json changes classify." },
91
92
  { "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." },
92
93
  { "match": { "kind": "prefix", "value": "examples/" }, "reason": "Illustrative, regenerated at will (docs/supported-surface.md)." },
@@ -2,8 +2,8 @@
2
2
  "schema_version": "campaign-cart-sdk-support-policy/v0",
3
3
  "provenance": {
4
4
  "source": "NextCommerceCo/campaign-cart release tags",
5
- "latest_known_release": "0.4.36",
6
- "captured_at": "2026-08-18"
5
+ "latest_known_release": "0.4.38",
6
+ "captured_at": "2026-09-18"
7
7
  },
8
8
  "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
9
9
  "minimum_supported": "0.4.20",
@@ -166,13 +166,15 @@
166
166
  "items_json",
167
167
  "vouchers_json",
168
168
  "accept_text",
169
- "decline_text"
169
+ "decline_text",
170
+ "retail_shipping",
171
+ "offer_shipping"
170
172
  ],
171
173
  "sourceOfTruth": [
172
174
  "CampaignSpec upsell/downsell pages",
173
175
  "Campaigns API package refs and vouchers/offers"
174
176
  ],
175
- "agentRule": "Post-purchase upsells do not use shipping_methods. Package refs and vouchers must come from the upsell page contract."
177
+ "agentRule": "Post-purchase upsells do not use shipping_methods. Package refs and vouchers must come from the upsell page contract. `retail_shipping` and `offer_shipping` are display copy for the offer price block (the struck retail shipping line and the offer shipping line), not shipping method refs. The starter defaults claim `+$4.95 SHIPPING` and `+ FREE SHIPPING`; set both from the target campaign's real shipping figures whenever they differ."
176
178
  },
177
179
  "upsell_bundle_tiers": {
178
180
  "purpose": "Tiered post-purchase bundle upsell rows.",
@@ -493,9 +495,9 @@
493
495
  }
494
496
  },
495
497
  "verification": {
496
- "sdk_version": "0.4.37",
497
- "verified_at": "2026-08-21T15:26:00Z",
498
- "evidence": "sdk-0.4.37-2026-08-21",
498
+ "sdk_version": "0.4.38",
499
+ "verified_at": "2026-09-15T16:51:10Z",
500
+ "evidence": "sdk-0.4.38-2026-09-15",
499
501
  "status": "certified",
500
502
  "source": "template-verification.json"
501
503
  }
@@ -505,8 +507,8 @@
505
507
  "templateReference": {
506
508
  "id": "template-reference-apollo",
507
509
  "family": "apollo",
508
- "version": "sdk-0.4.37-2026-08-21",
509
- "source_commit": "e9a2fc17beefe572b8ddc0c4f9b1b8e2f97f9a59",
510
+ "version": "sdk-0.4.38-revalidated-2026-09-03",
511
+ "source_commit": "84a63fe7af8cf49cd8cfdaaa66eb00ef6dd9bc4a",
510
512
  "provenance_url": "https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/main/docs/template-references/apollo/README.md",
511
513
  "contract_path": "contracts/commerce-surface-catalog.json",
512
514
  "standard_viewport_refs": [
@@ -832,9 +834,9 @@
832
834
  }
833
835
  },
834
836
  "verification": {
835
- "sdk_version": "0.4.37",
836
- "verified_at": "2026-08-21T15:26:00Z",
837
- "evidence": "sdk-0.4.37-2026-08-21",
837
+ "sdk_version": "0.4.38",
838
+ "verified_at": "2026-09-15T16:51:10Z",
839
+ "evidence": "sdk-0.4.38-2026-09-15",
838
840
  "status": "certified",
839
841
  "source": "template-verification.json"
840
842
  }
@@ -1038,9 +1040,9 @@
1038
1040
  }
1039
1041
  },
1040
1042
  "verification": {
1041
- "sdk_version": "0.4.37",
1042
- "verified_at": "2026-08-21T15:26:00Z",
1043
- "evidence": "sdk-0.4.37-2026-08-21",
1043
+ "sdk_version": "0.4.38",
1044
+ "verified_at": "2026-09-15T16:51:10Z",
1045
+ "evidence": "sdk-0.4.38-2026-09-15",
1044
1046
  "status": "certified",
1045
1047
  "source": "template-verification.json"
1046
1048
  }
@@ -1235,9 +1237,9 @@
1235
1237
  }
1236
1238
  },
1237
1239
  "verification": {
1238
- "sdk_version": "0.4.37",
1239
- "verified_at": "2026-08-21T15:26:00Z",
1240
- "evidence": "sdk-0.4.37-2026-08-21",
1240
+ "sdk_version": "0.4.38",
1241
+ "verified_at": "2026-09-15T16:51:10Z",
1242
+ "evidence": "sdk-0.4.38-2026-09-15",
1241
1243
  "status": "certified",
1242
1244
  "source": "template-verification.json"
1243
1245
  }
@@ -1469,9 +1471,9 @@
1469
1471
  }
1470
1472
  },
1471
1473
  "verification": {
1472
- "sdk_version": "0.4.37",
1473
- "verified_at": "2026-08-21T15:26:00Z",
1474
- "evidence": "sdk-0.4.37-2026-08-21",
1474
+ "sdk_version": "0.4.38",
1475
+ "verified_at": "2026-09-15T16:51:10Z",
1476
+ "evidence": "sdk-0.4.38-2026-09-15",
1475
1477
  "status": "certified",
1476
1478
  "source": "template-verification.json"
1477
1479
  }
@@ -1802,9 +1804,9 @@
1802
1804
  }
1803
1805
  },
1804
1806
  "verification": {
1805
- "sdk_version": "0.4.37",
1806
- "verified_at": "2026-08-21T15:26:00Z",
1807
- "evidence": "sdk-0.4.37-2026-08-21",
1807
+ "sdk_version": "0.4.38",
1808
+ "verified_at": "2026-09-15T16:51:10Z",
1809
+ "evidence": "sdk-0.4.38-2026-09-15",
1808
1810
  "status": "certified",
1809
1811
  "source": "template-verification.json"
1810
1812
  }
@@ -2052,9 +2054,9 @@
2052
2054
  }
2053
2055
  },
2054
2056
  "verification": {
2055
- "sdk_version": "0.4.37",
2056
- "verified_at": "2026-08-21T15:26:00Z",
2057
- "evidence": "sdk-0.4.37-2026-08-21",
2057
+ "sdk_version": "0.4.38",
2058
+ "verified_at": "2026-09-15T16:51:10Z",
2059
+ "evidence": "sdk-0.4.38-2026-09-15",
2058
2060
  "status": "certified",
2059
2061
  "source": "template-verification.json"
2060
2062
  }
@@ -2236,9 +2238,9 @@
2236
2238
  }
2237
2239
  },
2238
2240
  "verification": {
2239
- "sdk_version": "0.4.37",
2240
- "verified_at": "2026-08-21T15:26:00Z",
2241
- "evidence": "sdk-0.4.37-2026-08-21",
2241
+ "sdk_version": "0.4.38",
2242
+ "verified_at": "2026-09-15T16:51:10Z",
2243
+ "evidence": "sdk-0.4.38-2026-09-15",
2242
2244
  "status": "certified",
2243
2245
  "source": "template-verification.json"
2244
2246
  }
@@ -2448,5 +2450,5 @@
2448
2450
  },
2449
2451
  "_synced_from_repo": "NextCommerceCo/campaign-cart-starter-templates",
2450
2452
  "_synced_from_ref": "main",
2451
- "_synced_from_sha": "a7cc8beaf9d332c5d8e501d36fb9d4d7e3667468"
2453
+ "_synced_from_sha": "11352c30c596db258679fd3a552b906086b11bb9"
2452
2454
  }
@@ -0,0 +1,89 @@
1
+ {
2
+ "schema_version": "campaigns-os-progress-snapshot/v0",
3
+ "stream_id": "progress_11111111111111111111111111111111",
4
+ "sequence": 1,
5
+ "previous_snapshot_id": null,
6
+ "observed_at": "2026-09-18T00:00:00.000Z",
7
+ "package_version": "1.36.0",
8
+ "producer": "next",
9
+ "identity": {
10
+ "map_id": "example-map",
11
+ "map_revision_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12
+ "map_revision_algorithm": "map-store-v1",
13
+ "saved_revision_alignment": "aligned",
14
+ "local_spec_material_hash": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
15
+ "local_spec_material_algorithm": "campaign-spec-material-v1",
16
+ "build_fingerprint": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
17
+ "build_fingerprint_algorithm": "sha256-manifest/v1"
18
+ },
19
+ "stages": [
20
+ {
21
+ "stage": "prepare_build",
22
+ "status": "completed",
23
+ "build_binding": "unconfirmed",
24
+ "source_build_fingerprint": null
25
+ },
26
+ {
27
+ "stage": "setup",
28
+ "status": "completed",
29
+ "build_binding": "unconfirmed",
30
+ "source_build_fingerprint": null
31
+ },
32
+ {
33
+ "stage": "assembly",
34
+ "status": "completed",
35
+ "build_binding": "matching",
36
+ "source_build_fingerprint": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
37
+ },
38
+ {
39
+ "stage": "polish",
40
+ "status": "pending",
41
+ "build_binding": "unconfirmed",
42
+ "source_build_fingerprint": null
43
+ },
44
+ {
45
+ "stage": "deploy",
46
+ "status": "pending",
47
+ "build_binding": "unconfirmed",
48
+ "source_build_fingerprint": null
49
+ },
50
+ {
51
+ "stage": "qa",
52
+ "status": "pending",
53
+ "build_binding": "unconfirmed",
54
+ "source_build_fingerprint": null
55
+ }
56
+ ],
57
+ "preview": {
58
+ "present": false,
59
+ "url_hash": null
60
+ },
61
+ "continuation": {
62
+ "stage": "polish",
63
+ "blocked": false,
64
+ "divergent": false,
65
+ "action_ids": [
66
+ "polish_skill"
67
+ ],
68
+ "gates": [
69
+ {
70
+ "id": "doctor",
71
+ "state": "pass"
72
+ },
73
+ {
74
+ "id": "prepare_build",
75
+ "state": "pass"
76
+ },
77
+ {
78
+ "id": "theme_gate",
79
+ "state": "waived"
80
+ },
81
+ {
82
+ "id": "polish_gate",
83
+ "state": "not_applicable"
84
+ }
85
+ ]
86
+ },
87
+ "qa": null,
88
+ "snapshot_id": "sha256:f52f2418c30e6696471fbcc86dcc3fc28caa7e17df9151b58d150747dd3f48fb"
89
+ }