@nextcommerce/campaigns-os 1.37.1 → 1.37.3

package/AGENTS.md

@@ -97,7 +97,7 @@ 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
+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.

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.37.3] - 2026-09-19
+
+### Changed
+
+- Publish the corrected install documentation. The README and quick start in
+  the 1.37.2 tarball still pinned `@nextcommerce/campaigns-os@1.34.1` and called
+  `demo` a candidate feature; this release carries the 1.37.2+agent.1 wording
+  (install examples at the current release, `demo` documented as shipped in
+  1.37.0 and later) so the npm package page matches the portal. No command,
+  schema, skill or export changes.
+
+## [1.37.2+agent.1] - 2026-09-19
+
+### Changed
+
+- Point the install examples at the published 1.37.2 release. `README.md` and
+  `docs/quickstart.md` still pinned `@nextcommerce/campaigns-os@1.34.1`, three
+  releases behind the tag they ship in, so a reader following the GitHub or npm
+  README installed a toolkit without `demo` or `tooling diagnose`. The
+  minimum-version notes for those commands stay; the
+  "not published yet" caveats and their full-SHA workarounds are gone.
+- Stop calling 1.37.0 a candidate. `AGENTS.md`, `docs/supported-surface.md`,
+  `docs/activation-and-evidence.md`, `docs/demo-preview.md` and the quick starts
+  described `demo` as a "candidate 1.37.0" feature; 1.37.0 through 1.37.2 are
+  published releases and the wording now says so.
+
+## [1.37.2] - 2026-09-18
+
+### Fixed
+
+- Refresh the public starter catalog, per-family SDK verification and CampaignSpec
+  examples from template commit `11352c30`. The vendored SDK policy now records
+  released SDK 0.4.38, so freshness compares older certification against that
+  release instead of reporting SDK 0.4.37 as current.
+- Carry forward private families and local QA structure. Refresh Apollo Template
+  Reference provenance and upsell shipping-copy guidance from the same source.
+  Reconcile certified fixture and payment-chrome provenance with the catalog;
+  rendered pages, config files and payment asset hashes remain unchanged.
+- Preserve the toolkit's established pre-checkout select role and authored
+  forward routes when refreshing the known public examples. Narrow adapters
+  retain unrelated source updates and leave distinct future contracts unchanged.
+
+## [1.37.1+agent.1] - 2026-09-18
+
+### Changed
+
+- Document the page-kit change procedure after handoff: PM proposals are
+  reconciled against a known baseline and the current reviewed repository spec.
+  Conflicting authored edits require a recorded decision; generated and API-owned
+  fields retain their own authority. The worked example preserves a developer's
+  SDK upgrade and new page URL while accepting an authored upsell change.
+- Keep Map pin write-back explicit and store refresh with the authorized operator.
+  The procedure names the review and evidence requirements for the next build,
+  including fresh fingerprints after authored-only changes. It adds no automatic
+  synchronization, portal writes or spec prerequisite for static SDK upgrades.
+
 ## [1.37.1] - 2026-09-18
 
 ### Fixed

package/README.md

@@ -43,7 +43,7 @@ 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
+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
 mkdir -p source
@@ -53,7 +53,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 +69,16 @@ 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, `npx campaigns-os demo --target ./apollo-sample`
+(1.37.0 or later) 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
@@ -139,7 +135,15 @@ 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
 in two tools; with `--from-store <subdomain>` and the store's Admin API read
-token in the environment it derives the store profile from the store as well. Everything after `start` is agent-driven: after `start`
+token in the environment it derives the store profile from the store as well.
+Map write-back stays explicit and pin-only.
+
+For changes after handoff, follow the
+[spec review procedure](docs/build-packet.md#changing-a-campaign-after-handoff):
+apply the PM's authored changes to the current repository spec, preserve derived
+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

package/contracts/campaign-cart-sdk-support-policy.v0.json

@@ -2,8 +2,8 @@
   "schema_version": "campaign-cart-sdk-support-policy/v0",
   "provenance": {
     "source": "NextCommerceCo/campaign-cart release tags",
-    "latest_known_release": "0.4.36",
-    "captured_at": "2026-08-18"
+    "latest_known_release": "0.4.38",
+    "captured_at": "2026-09-18"
   },
   "source": "contracts/campaign-cart-sdk-support-policy.v0.json",
   "minimum_supported": "0.4.20",

package/contracts/commerce-surface-catalog.json

@@ -166,13 +166,15 @@
         "items_json",
         "vouchers_json",
         "accept_text",
-        "decline_text"
+        "decline_text",
+        "retail_shipping",
+        "offer_shipping"
       ],
       "sourceOfTruth": [
         "CampaignSpec upsell/downsell pages",
         "Campaigns API package refs and vouchers/offers"
       ],
-      "agentRule": "Post-purchase upsells do not use shipping_methods. Package refs and vouchers must come from the upsell page contract."
+      "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."
     },
     "upsell_bundle_tiers": {
       "purpose": "Tiered post-purchase bundle upsell rows.",
@@ -493,9 +495,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -505,8 +507,8 @@
       "templateReference": {
         "id": "template-reference-apollo",
         "family": "apollo",
-        "version": "sdk-0.4.37-2026-08-21",
-        "source_commit": "e9a2fc17beefe572b8ddc0c4f9b1b8e2f97f9a59",
+        "version": "sdk-0.4.38-revalidated-2026-09-03",
+        "source_commit": "84a63fe7af8cf49cd8cfdaaa66eb00ef6dd9bc4a",
         "provenance_url": "https://raw.githubusercontent.com/NextCommerceCo/campaign-cart-starter-templates/main/docs/template-references/apollo/README.md",
         "contract_path": "contracts/commerce-surface-catalog.json",
         "standard_viewport_refs": [
@@ -832,9 +834,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1038,9 +1040,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1235,9 +1237,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1469,9 +1471,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -1802,9 +1804,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2052,9 +2054,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2236,9 +2238,9 @@
         }
       },
       "verification": {
-        "sdk_version": "0.4.37",
-        "verified_at": "2026-08-21T15:26:00Z",
-        "evidence": "sdk-0.4.37-2026-08-21",
+        "sdk_version": "0.4.38",
+        "verified_at": "2026-09-15T16:51:10Z",
+        "evidence": "sdk-0.4.38-2026-09-15",
         "status": "certified",
         "source": "template-verification.json"
       }
@@ -2448,5 +2450,5 @@
   },
   "_synced_from_repo": "NextCommerceCo/campaign-cart-starter-templates",
   "_synced_from_ref": "main",
-  "_synced_from_sha": "a7cc8beaf9d332c5d8e501d36fb9d4d7e3667468"
+  "_synced_from_sha": "11352c30c596db258679fd3a552b906086b11bb9"
 }

package/contracts/release-ledger.json

@@ -5207,6 +5207,156 @@
         }
       ],
       "entry_sha256": "76423be9a8624b8a3b398f4a4bfd47ff17b48f45d6a3bc44a22e122172684c6a"
+    },
+    {
+      "id": "RL-0127",
+      "sequence": 127,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.37.1+agent.1",
+      "changelog_sha256": "4eef81fac283eb699daff04ea5de96a4ad768099f8b9e0556f57e671435479ca",
+      "agent_impact": "For page-kit campaigns after handoff, reconcile PM proposals against their baseline and the current reviewed repository spec. Record authored conflicts and regenerate build evidence for the accepted revision. Map pin write-back remains explicit; static SDK upgrades do not gain a spec requirement.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "named_surface",
+          "path": "docs/build-packet.md",
+          "surface_entry": "docs/build-packet.md",
+          "summary": "Document PM/developer ownership, authored reconciliation, reviewed build evidence and the boundary for future Git-backed portal saves."
+        }
+      ],
+      "entry_sha256": "7a643454252eff345d8015246440a037f69dab2041aee2f8fbafe1367caef087"
+    },
+    {
+      "id": "RL-0128",
+      "sequence": 128,
+      "date": "2026-09-18",
+      "kind": "release",
+      "surface_version": "1.37.2",
+      "changelog_section": "1.37.2",
+      "changelog_sha256": "96345150e314126c0b639cedebd4359085cb841af80cbf6e4ba0fb4554ce6d4c",
+      "agent_impact": "Use released SDK 0.4.38 for freshness comparisons. Public family verification, Apollo reference and upsell shipping-copy guidance now follow the pinned September 15 template source; older SDK evidence remains stale. Private overlays and rendered fixture bytes are preserved. Catalog refresh preserves the established select role and authored forward routes in exact known examples without overriding distinct future source contracts.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance the compatible package patch to 1.37.2."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Ship refreshed template evidence, SDK release policy and controlled refresh adapters that preserve established example roles and routes as package 1.37.2."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Keep the exact lockfile package identity at 1.37.2."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate the orientation reference for surface version 1.37.2."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate the runtime reference for package version 1.37.2."
+        }
+      ],
+      "entry_sha256": "174e0bac2ba34b94fbb7b30257d0baf4e417440cdbcfdc5685b9f48fa565ce26"
+    },
+    {
+      "id": "RL-0129",
+      "sequence": 129,
+      "date": "2026-09-19",
+      "kind": "release",
+      "surface_version": null,
+      "changelog_section": "1.37.2+agent.1",
+      "changelog_sha256": "602403245b293dc362ed28275ecfc1bc7d08e49f83be43cabdc5a91559ccd1f5",
+      "agent_impact": "Install examples in README.md and docs/quickstart.md now name the published 1.37.2 release instead of 1.34.1; demo is documented as shipped in 1.37.0 and later rather than as a candidate. No command, schema, skill or export changed.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "documentation",
+          "path": "AGENTS.md",
+          "surface_entry": "AGENTS.md",
+          "summary": "Describe demo as shipped in 1.37.0, not a candidate."
+        },
+        {
+          "class": "compatibility_policy",
+          "path": "docs/supported-surface.md",
+          "surface_entry": "docs/supported-surface.md",
+          "summary": "Describe the demo CLI command as shipped in 1.37.0, not a candidate."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/activation-and-evidence.md",
+          "surface_entry": "docs/activation-and-evidence.md",
+          "summary": "Describe demo --target as available in 1.37.0 and later."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/demo-preview.md",
+          "surface_entry": "docs/demo-preview.md",
+          "summary": "Drop the 1.34.1 caveat; demo ships in 1.37.0 and later."
+        }
+      ],
+      "entry_sha256": "7d7c4900e75bcb51f771416ce8c87e2e88111e184a5485fc6b7ac6634152241c"
+    },
+    {
+      "id": "RL-0130",
+      "sequence": 130,
+      "date": "2026-09-19",
+      "kind": "release",
+      "surface_version": "1.37.3",
+      "changelog_section": "1.37.3",
+      "changelog_sha256": "4fa53214f29b66d2dfff6011aaa373455e0d44d3cb1c5021cd867b473737fd08",
+      "agent_impact": "Install from 1.37.3 to get README and quick-start install examples that name the current release; demo is documented as shipped in 1.37.0 and later. Commands, schemas, skills and exports are unchanged from 1.37.2.",
+      "compatibility": "compatible",
+      "migration": "none",
+      "changes": [
+        {
+          "class": "compatibility_policy",
+          "path": "contracts/supported-surface.json",
+          "surface_entry": "contracts/supported-surface.json",
+          "summary": "Advance the compatible package patch to 1.37.3."
+        },
+        {
+          "class": "package_export",
+          "path": "package.json",
+          "surface_entry": null,
+          "summary": "Ship the corrected install documentation as package 1.37.3."
+        },
+        {
+          "class": "generated_runtime",
+          "path": "package-lock.json",
+          "surface_entry": null,
+          "summary": "Keep the exact lockfile package identity at 1.37.3."
+        },
+        {
+          "class": "documentation",
+          "path": "docs/orientation-contract-reference.md",
+          "surface_entry": "docs/orientation-contract-reference.md",
+          "summary": "Regenerate the orientation reference for surface version 1.37.3."
+        },
+        {
+          "class": "named_surface",
+          "path": "docs/runtime-readiness.md",
+          "surface_entry": "docs/runtime-readiness.md",
+          "summary": "Regenerate the runtime reference for package version 1.37.3."
+        }
+      ],
+      "entry_sha256": "fb317fe901bbab34f0c909b523a9e4e07040285a5f6883ee572c6f927681c0b1"
     }
   ]
 }

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act \u2014 hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here \u2014 src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) \u2014 is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.37.1",
+  "surface_version": "1.37.3",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",

package/contracts/template-brand-contract.shared-commerce.v0.json

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "a7cc8beaf9d332c5d8e501d36fb9d4d7e3667468",
+        "sha": "11352c30c596db258679fd3a552b906086b11bb9",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },

package/docs/activation-and-evidence.md

@@ -9,7 +9,7 @@ milestones below describe evidence, not a second state machine.
 | Milestone | What it establishes | What is still needed |
 |---|---|---|
 | Toolkit installed | The selected package can run and its agent skills can be checked with `tooling status`. | Campaign inputs and workflow evidence. Installation needs npm access; it does not grant store, Map, deploy, or QA access. |
-| Demo preview | Pinned sample pages can be opened locally for a visual walkthrough; candidate 1.37.0 provides `demo --target <new-directory>`. | A separate real campaign folder, configuration, replaced demo values, and the ordinary build and proof gates. Demo behavior is not live commerce proof. |
+| Demo preview | Pinned sample pages can be opened locally for a visual walkthrough; 1.37.0 and later provide `demo --target <new-directory>`. | A separate real campaign folder, configuration, replaced demo values, and the ordinary build and proof gates. Demo behavior is not live commerce proof. |
 | Map saved | Campaign Map Builder has retained the authored campaign plan. A local export is an alternative build input. | Export/revision agreement and resolution of live campaign data. Saving a Map does not establish Campaigns App or store access. |
 | Campaign resolved | The package-owned resolver has read the campaign's live configuration and produced resolution evidence. | Build, preview, and runtime proof. Confirm Campaigns App keys and allowed domains; store Admin API reads need their own read token. |
 | Preview observed | A browser has inspected the served current build at the tested URL. | Retained package-owned Polish capture and QA evidence tied to that build. A deployed URL alone is not an observation. |

package/docs/build-packet.md

@@ -220,6 +220,113 @@ action. A configured campaign whose pin is newer than the spec's is the
 advisory case above: no required action, and sync never moves that pin
 backwards; `spec derive` is the command that closes it from the spec side.
 
+### Changing a campaign after handoff
+
+For page-kit campaigns, the reviewed repository spec determines the next build.
+New handoffs use `.campaigns-os/campaign.spec.json`; existing packets keep their
+`spec.local_path` until a separate, reviewed migration. Static campaigns do not
+need a spec or packet for an SDK upgrade. This procedure implements the operating
+agreement in [#432](https://github.com/NextCommerceCo/campaigns-os/issues/432)
+and [#447](https://github.com/NextCommerceCo/campaigns-os/issues/447). It is a
+review procedure, not an automatic Map import or a portal editing lock.
+
+A PM can keep using Map Builder to propose a change. Saving the Map does not
+change the campaign repository or approve that change for the next build.
+
+| Responsibility | Owner |
+|---|---|
+| Propose offers, copy, page sequence and other authored intent; confirm the intended result | Campaign PM or named campaign owner |
+| Compare the proposal with the current repository, prepare the spec/code change and run checks | Developer, assisted by an agent where useful |
+| Resolve competing edits to the same authored field | PM confirms intent; developer checks the resulting implementation |
+| Review and merge the repository change | The campaign's existing authorized reviewer, under its normal PR rules |
+| Refresh store-derived data requiring an Admin token | Authorized operator or PM; never a routine developer SDK-bump prerequisite |
+
+Record the actual PM and developer/reviewer in the campaign change request. An
+agent can prepare a diff and evidence, but cannot supply a missing human decision.
+This procedure does not grant new merge, store-write or deployment authority.
+
+#### Propose and reconcile a change
+
+1. **Identify the starting revision.** Record the campaign repo, Git commit and
+   packet's spec path that the PM reviewed. Keep that spec as the baseline. A Map
+   ID identifies lineage, not the revision: also retain the proposed Map export
+   and its save/hash evidence. Do not overwrite the repository spec with it.
+2. **Compare three versions.** Compare the baseline with the PM's proposal, then
+   with the current repository spec. Match pages and packages by their stable
+   identifiers, not array position. Explain additions, removals and routing
+   changes as well as changed values. The
+   [field-class contract](https://github.com/NextCommerceCo/campaigns-os/issues/432#issuecomment-5707550439)
+   identifies what a PM can author and what the repo, API or editor owns.
+3. **Apply the intended change to the current spec on a branch.** Transfer only
+   the PM's authored changes. Keep current repo-derived SDK pins, page URLs and
+   analytics IDs; preserve API/store records and editor metadata under their own
+   authority. An offer selection may change, but a proposed price does not
+   rewrite an API-owned price: route that commercial setup change to its owner
+   and obtain refreshed readback before building it.
+4. **Resolve conflicts before accepting the change.** If PM and developer changed
+   the same authored field differently, neither value wins automatically. Record
+   the chosen value and PM confirmation in the PR. If the baseline is missing,
+   pause the import: ask the PM to restate the change against the current spec.
+   Do not infer intent from every difference in a stale export. If the repository
+   advances during review, repeat the comparison against the new revision.
+5. **Refresh and validate the result.** Preview `spec derive --dry-run`, inspect
+   every refused or unresolved field, then apply the accepted derivation. Plain
+   derive is local; it does not merge authored intent. Follow the packet's normal
+   `page-kit sync`, build, doctor and relevant QA steps. Resolve stale routing
+   hints and rebuild affected pages. A successful derive exit alone is not build
+   or QA approval. After an authored-only edit, derive may return `unchanged`
+   and leave the Assembly Report's spec hash at the previous build. Record fresh
+   build evidence and verify its spec fingerprint before accepting it. A changed
+   spec must not reuse evidence for the older build.
+6. **Review the intended result and record the revision.** The PM confirms the
+   commercial change and the developer supplies the checked diff and preview
+   evidence. Record the reviewed spec's exact-byte SHA-256, the tested repository
+   revision, and the doctor/QA evidence in the PR. Build or deploy from that
+   reviewed revision under the campaign's existing rules; rerun affected checks
+   if the spec or code changes afterwards. Tell the PM which proposal was accepted
+   and identify any remaining Map differences, so the saved Map is not mistaken
+   for a synchronized copy.
+
+A change request needs only: baseline commit/spec path, the proposal or requested
+field changes, current repository revision, conflict decisions, named reviewers,
+and the final spec hash with build/QA evidence. Use existing PRs and campaign
+records for this; there is no additional sidecar schema or new CLI command.
+
+#### Example: the PM changes an upsell while the developer upgrades the SDK
+
+The PM starts from reviewed revision A and replaces the first upsell's selected
+package with package B, already present in the campaign API. Meanwhile the
+repository reaches revision R with a newer SDK pin and a changed page permalink.
+The PM's export still contains A's SDK pin and generated page URL.
+
+| Value | PM proposal | Current repo R | Reviewed result |
+|---|---|---|---|
+| Selected upsell package (authored) | B | Original package | B, after PM confirmation |
+| SDK pin (repo-derived) | Old pin from A | Newer pin | Newer pin |
+| Page URL (repo-derived) | Old URL from A | New permalink | URL derived from the new permalink |
+| Package price (API-owned) | Copied API value | Current API value | Current API value; selection does not change the price |
+
+Start from R, change the selected package, and derive the repo-owned fields. Review
+routing references and rebuild the affected upsell page. If the developer also
+changed the selected package to C, record a conflict and obtain a choice before
+merging. Do not apply B merely because the Map was saved later.
+
+#### Map write-back and future portal saves
+
+`spec derive --write-map` remains an explicit, pin-only action. A developer or
+operator may request it when updating the Map's SDK hint is part of their task;
+it is not a default SDK-bump or reconciliation step. It retains the existing
+hash precondition and refusal to overwrite a newer Map pin. It does not mark a
+PM proposal accepted or synchronize offers, routes or other authored content.
+Store refresh through `--from-store` remains a separate authorized operator step.
+
+A future Git-backed portal save can replace the manual transfer only when it
+identifies the repository/spec and base revision, shows the authored diff,
+preserves each field's authority, detects concurrent changes, and submits the
+change through the same review process. It must show whether a change is merely
+proposed, reviewed or used by a build. That is separate portal work; this
+agreement does not enable portal writes.
+
 ### Deriving the spec from the repo (`spec derive`)
 
 Every CampaignSpec field has a class: **authored** (a human writes it: offers,

package/docs/demo-preview.md

@@ -1,8 +1,7 @@
 # Offline sample preview
 
-Candidate 1.37.0 adds `campaigns-os demo`. The published 1.34.1 installation
-example does not contain this command; install a reviewed full-SHA candidate
-or an exact release at least 1.37.0 after publication.
+`campaigns-os demo` ships in 1.37.0 and later; install an exact published
+release at least 1.37.0 (or a reviewed full-SHA source pin).
 
 From the folder containing your exact project-local toolkit installation:
 

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.1`
+Supported surface at generation time: `1.37.3`
 
 ## Forward compatibility
 

package/docs/runtime-readiness.md

@@ -8,7 +8,7 @@
 
 How a checkout of this repository at one commit becomes a usable installed runtime, and how a consumer decides whether a prepared one is still trustworthy. Everything below is generated from `contracts/runtime-recipe.campaigns-os-node-v1.json`, which is the only authority for these values.
 
-Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.1`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.2`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.37.3`.
 
 ## What this is
 

package/docs/supported-surface.md

@@ -89,7 +89,7 @@ fixture. Observations preserve canonical continuation and separate Map/spec/buil
 identities; consumers must not treat history presence or scope-key matching as
 readiness or trust.
 
-Candidate 1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
+1.37.0 adds the `demo` CLI command, [offline sample reference](demo-preview.md),
 a hashed `demo/apollo-v0/provenance.json` and named attribution notice. The command
 exclusively creates a new target with validated inert pages. Its internal static
 files are covered by the provenance output hashes; they are not independent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextcommerce/campaigns-os",
-  "version": "1.37.1",
+  "version": "1.37.3",
   "description": "Toolkit for agent-assisted NEXT campaign builds.",
   "license": "Apache-2.0",
   "repository": {