@nextcommerce/campaigns-os 1.59.0 → 1.60.0

package/docs/campaigns-os-build-flow.md

@@ -41,7 +41,7 @@ URL.
 - Starter template contracts own the SDK attribute contract and protected runtime surfaces: checkout/cart/upsell/receipt/payment/address/totals/submit controls and their required data attributes.
 - Designed source owns visual composition, content hierarchy, imagery, and page-level copy.
 
-Packages identify sellable products or variants, and Offers own campaign price changes. Package Retail Price/Quantity fields may exist on older campaigns, but assembly should not introduce them for new tier pricing.
+Packages identify sellable products or variants, and Offers own campaign price changes. The Campaigns App dashboard calls packages **Products** and creates one per variant when an Offer that selects it is saved, so a campaign set up there has one package per variant and a separate Offer for each Buy 1/2/3 tier. Package Retail Price/Quantity fields and multi-unit packages exist on older campaigns that have the legacy **Enable Package Retail Price & Quantity** setting on (see the "Older Campaigns" section of [Campaign Products](https://docs.nextcommerce.com/docs/apps/campaigns-app/build-campaign-packages)), but assembly should not introduce them for new tier pricing.
 
 ## Offer Application Surfaces
 

package/docs/local-setup.md

@@ -3,7 +3,7 @@
 For a new campaign, create an empty working folder and run this from it:
 
 ```sh
-npm init -y && npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.59.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.60.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 `npm init -y` gives the folder its own `package.json`. Without one, npm

package/docs/orientation-contract-reference.md

@@ -26,7 +26,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.59.0`
+Supported surface at generation time: `1.60.0`
 
 ## Forward compatibility
 

package/docs/polish-evidence.md

@@ -37,7 +37,7 @@ The gate only applies once assembly is complete
 | `status` | `stages.polish.status` | Must start with `completed`. `blocked` → `polish.blocked`; anything else → `polish.evidence_missing`. |
 | `performed_by` | `stages.polish.performed_by`, `stages.polish.command_identity`, `evidence.performed_by` | Must be exactly `next-campaigns-polish`. Anything else (including missing) → `polish.self_certified`. |
 | `commands` | `stages.polish.commands` and/or `evidence.commands` | Must NOT mention a build command anywhere — a polish record that ran build is self-certification → `polish.self_certified`. The matcher is exactly the strings `next-campaigns-build` and `campaigns-os next build` (case-insensitive); other build tooling (e.g. page-kit's `campaign-build`) is not matched. |
-| `source_build_fingerprint` | `stages.polish.source_build_fingerprint` or `evidence.source_build_fingerprint` | Required, and must equal the current build fingerprint (`stages.assembly.build_fingerprint`, falling back to `stages.assembly.artifact_fingerprint`, `report.build_fingerprint`, `report.artifact_fingerprint`). Missing → `polish.source_build_fingerprint_missing`; different → `polish.stale`. Doctor, QA, and `polish capture` also recompute the fingerprint from the built output under `_site/<slug>/` (algorithm in `docs/build-packet.md`); when the output no longer matches the recorded value the gate is `polish.output_drift` with `current_output_fingerprint` and a `rerun_build` action, whatever the recorded string says. |
+| `source_build_fingerprint` | `stages.polish.source_build_fingerprint` or `evidence.source_build_fingerprint` | Required, and must equal the current build fingerprint (`stages.assembly.build_fingerprint`). Missing → `polish.source_build_fingerprint_missing`; different → `polish.stale`. Doctor, QA, and `polish capture` also recompute the fingerprint from the built output under `_site/<slug>/` (algorithm in `docs/build-packet.md`); when the output no longer matches the recorded value the gate is `polish.output_drift` with `current_output_fingerprint` and a `rerun_build` action, whatever the recorded string says. |
 | `source_package_material_fingerprint` | `stages.polish.source_package_material_fingerprint` or `evidence.source_package_material_fingerprint` | Only enforced when the report carries a current Design Source Package material fingerprint (`design_source_package.material_fingerprint` or equivalents). Missing → `polish.source_package_material_fingerprint_missing`; different → `polish.source_package_stale`. |
 | `completed_at` | `stages.polish.completed_at` or `evidence.completed_at` | Required non-empty timestamp string → else `polish.completed_at_missing`. |
 

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.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.59.0`.
+Recipe kind `campaigns-os-node-v1`, revision `1.0.3`, validated by `schemas/campaigns-os-runtime-recipe.v1.schema.json` (`Campaigns OS Runtime Recipe v1`). Supported surface at generation time: `1.60.0`.
 
 ## What this is
 

package/docs/skills-revision.md

@@ -16,7 +16,7 @@ that the copy on disk moved.
 `skills.json` carries one top-level field:
 
 ```json
-"bundle_revision": "1.59.0+skills.1"
+"bundle_revision": "1.60.0+skills.1"
 ```
 
 The spelling is `<package version>+skills.<n>`:
@@ -25,7 +25,7 @@ The spelling is `<package version>+skills.<n>`:
   skills ship with (`check-skill-versions.mjs` fails if the two disagree);
 - `<n>` is a plain counter, not a semver component. It says "this is the *n*th
   skill-text revision published against that package version" and it **resets
-  with the prefix**. `1.59.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
+  with the prefix**. `1.60.0+skills.1` is therefore ahead of `1.40.0+skills.7`.
 
 It is one identity for the bundle as a whole, on purpose. Per-skill versions
 still exist and still gate per-skill changes, but an agent that loaded one skill
@@ -37,7 +37,7 @@ The first body line of every bundled `SKILL.md`, immediately after the
 frontmatter, is exactly:
 
 ```
-Bundle revision: 1.59.0+skills.1
+Bundle revision: 1.60.0+skills.1
 ```
 
 followed by a short paragraph telling the agent to run the check below at the
@@ -48,7 +48,7 @@ text the agent is actually reading, not from a file it would have to go and open
 ## The check
 
 ```bash
-npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1
+npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1
 ```
 
 The value is compared against the bundle revision of the **CLI the command runs
@@ -90,20 +90,20 @@ reports the choice as `skills.scope` (`requested`, `installed_platforms`, or
 "revision_check": "match",
 "skills_revision": {
   "status": "match",
-  "requested": "1.59.0+skills.1",
+  "requested": "1.60.0+skills.1",
   "spelling": "bundle",
-  "on_disk": "1.59.0+skills.1",
+  "on_disk": "1.60.0+skills.1",
   "on_disk_skill": null,
-  "message": "match (1.59.0+skills.1)"
+  "message": "match (1.60.0+skills.1)"
 }
 ```
 
 The text view prints one named line, as a header above the rest of the status:
 
 ```
-Skills revision: match (1.59.0+skills.1)
-Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.59.0+skills.1 — start a fresh session
-Skills revision: unchecked (on disk 1.59.0+skills.1)
+Skills revision: match (1.60.0+skills.1)
+Skills revision: mismatch: loaded 1.39.0+skills.1, on disk 1.60.0+skills.1 — start a fresh session
+Skills revision: unchecked (on disk 1.60.0+skills.1)
 ```
 
 `unchecked` is the state when the flag is absent. It is not an error — an

package/package.json

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

package/skills/campaign-lifecycle-orientation/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-lifecycle-orientation
-version: 1.0.37
+version: 1.0.41
 description: Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing any stage or changing any state.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/campaign-readback-classification/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-readback-classification
-version: 1.0.37
+version: 1.0.41
 description: Classify a selected campaign from the readback projection's v2 fields and write a read-only handoff without turning diagnosis into permission.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/campaign-run-evidence/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: campaign-run-evidence
-version: 1.0.37
+version: 1.0.41
 description: Interpret existing Campaigns OS doctor, QA and proof-depth evidence without claiming more proof than the artifacts contain.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/contribution-intake/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: contribution-intake
-version: 1.0.37
+version: 1.0.41
 description: Turn a suggestion about the agent surface into a classified, evidence-checked proposal and, only with attended approval, one issue on this repository's tracker.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-build/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-build
-version: 1.0.42
+version: 1.0.46
 description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -110,7 +110,7 @@ Build rules:
 - Run page-kit build and SDK/template lint available in the target repo.
 - Record build with `campaigns-os record build --packet <packet>` after every page-kit build (tier `C`: it overwrites `stages.assembly` and, when the output changed, resets `stages.polish` to `required` in the assembly report, and stamps the doctor output stale; `--dry-run` is tier `none`). It stamps `stages.assembly.build_fingerprint` with the fingerprint doctor computes from `_site/<slug>/` and the Design Source Package material fingerprint when the report has one. Never type or copy these fields by hand.
 - If `next` reports that the build output is unchanged after a brief or CampaignSpec change, rebuild so the change reaches the pages. Pass `--deviation-reason` to `record build` only when the operator explicitly decides in this conversation that the change needs no change to the built pages, and quote their reason.
-- Capture the machine-readable build summary as an artifact: `npx campaign-build --json > .campaign-runtime/page-kit-build-summary.json` (requires `next-campaign-page-kit` >= 0.1.4). Doctor's `built_output.build_summary` check verifies per-page build status and Page Kit shape warnings (`NESTED_NO_PERMALINK`, `DUPLICATE_OUTPUT`, `MISSING_FRONTMATTER`, `LAYOUT_NOT_FOUND`, `NO_CAMPAIGN`) from this artifact. If the installed page-kit predates `--json`, record that in the assembly report instead of skipping silently.
+- Capture the machine-readable build summary as an artifact: `npx campaign-build --json > .campaign-runtime/page-kit-build-summary.json` (requires `next-campaign-page-kit` >= 0.1.4). Doctor's `built_output.build_summary` check verifies per-page build status and Page Kit shape warnings (`NESTED_NO_PERMALINK`, `DUPLICATE_OUTPUT`, `MISSING_FRONTMATTER`, `LAYOUT_NOT_FOUND`, `NO_CAMPAIGN`) from this artifact. On `next-campaign-page-kit` >= 0.3.0 it also reads the summary's top-level `assetWarnings`: each `ASSET_IGNORED` entry names an `.html` file under `assets/` that page-kit neither builds nor copies, so a link or iframe to it 404s. Move such a file out of `assets/` if it is a page, or remove it. If the installed page-kit predates `--json`, record that in the assembly report instead of skipping silently.
 - Update the assembly report with commands, evidence, warnings, blockers, and next owner. If a brand theme was applied, run `campaigns-os record theme --packet <p>` (tier `C`) after `record build`: it reads each built commerce page's stylesheet links and records `report.theme` (status applied, `load_order=after-next-core`, `css_path`, `commerce_pages`, evidence). It refuses, writing nothing, when a page that loads `next-core.css` does not load the brand layer after it. Don't hand-edit `report.theme`; a first repair-loop defect goes through `record polish`.
 
 Build does not replace polish or QA. Hand off to `next-campaigns-polish` when the campaign is runnable.

package/skills/next-campaigns-os/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os
-version: 1.0.57
+version: 1.0.61
 description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-os-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.40
+version: 2.0.44
 description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-polish/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-polish
-version: 1.1.42
+version: 1.1.46
 description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read
@@ -87,13 +87,12 @@ Responsibilities:
   evidence forward as a warning. Query or fragment text on the production
   page does not make it a distinct preview. If the hosted preview URL is not
   yet recorded, run
-  `campaigns-os qa policy set --packet <packet> --preview-url <url>` first,
-  then `campaigns-os next --packet <packet>`. Run
-  `campaigns-os next qa --packet <packet>`, then
-  `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser
-  --test-order common`. The hosted preview URL satisfies the deploy handoff;
-  after QA records its verdict, run `campaigns-os next --packet <packet>` for
-  closeout. QA against the packet's production URL keeps the checkpoint blocked.
+  `campaigns-os qa policy set --packet <packet> --preview-url <url>` first.
+  Then follow `campaigns-os next --packet <packet>`: it hands off
+  `campaigns-os record deploy --packet <packet> --base-url
+  <preview route root>`, then `campaigns-os qa run --packet <packet>
+  --base-url <preview-url> --browser --test-order common`, then closeout. QA
+  against the packet's production URL keeps the checkpoint blocked.
 - When a readability warning appears, report it with its colours, ratio, requirement and pages. Offer the operator options inside the brand palette (a darker or lighter shade of the same hue, the palette's text colour, or a larger, bold label where the design allows). Do not recolour the merchant's design until the operator chooses. Accept a warning only with the refs, reason and name the operator gives you at the QC handoff.
 - Record Polish as `completed`, `skipped`, or `blocked` with
   `campaigns-os record polish --packet <packet> --evidence <polish-evidence.json>`

package/skills/next-campaigns-qa/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.41
+version: 1.3.45
 description: Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
 ---
 
-Bundle revision: 1.59.0+skills.1
-Run `npx --no-install campaigns-os tooling status --skills-revision 1.59.0+skills.1`
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
 from the campaign's Page Kit folder, where it runs the project's pinned copy and
 never installs one, at the start of each task. Start a fresh session if it
 reports `mismatch`: this text is already in your context and is never re-read

package/skills/next-campaigns-sdk-bump/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: next-campaigns-sdk-bump
+version: 1.0.1
+description: Bump a live campaign's Campaign Cart SDK from one 0.4.x release to a later 0.4.x on a page-kit or static repo. Use for any request to bump, upgrade or move a campaign to SDK 0.4.x, including when the repository has its own BUMP.md. Find every pin, check the release diff and storage against the campaign's own code, prove on a preview with approved test orders, and report what is not proven.
+---
+
+Bundle revision: 1.60.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.60.0+skills.1`
+from the campaign's Page Kit folder, where it runs the project's pinned copy and
+never installs one, at the start of each task. Start a fresh session if it
+reports `mismatch`: this text is already in your context and is never re-read
+while the CLI on disk can move under it. If the output has no `Skills revision:`
+line (no `revision_check` under `--json`), a campaigns-os older than this check
+answered; follow none of its actions and run the pinned copy.
+
+# Next Campaigns SDK Bump
+
+Use this when someone says "bump this campaign to SDK 0.4.x". The developer
+installs the toolkit, asks for the bump, approves each push, the pull request
+and each test order, then reviews and merges. Everything here uses existing
+commands; there is no new write or order capability.
+
+If `tooling status` prints `Refresh installed skills` for `--platform codex` or
+`--platform agents` only, that refresh is for those harnesses; it is not
+required in a session that uses neither.
+
+In the instructions below, bare `campaigns-os …` means `npx --no-install
+campaigns-os …` from the campaign folder. The effect class in each
+parenthetical is the declared row of `contracts/effects.v1.json`.
+
+## Scope: a current-SDK bump only
+
+A bump moves a funnel from one Campaign Cart 0.4.x release to a later 0.4.x.
+Before anything else, confirm every page in scope loads a 0.4.x loader. Stop
+and say so if you find a 0.3.x pin or a legacy page: one whose own code calls
+the Campaigns JS or the Campaigns API directly for cart and checkout. Moving
+those changes bundle selection, cart calculation and more, and is migration
+work, not a bump.
+
+Judge a legacy page by what drives its cart and checkout, not by a script URL.
+The 0.4.x SDK loads the Campaigns analytics script (`/js/v1/campaign/`) itself
+for analytics, and some layouts also load it by hand; on a page the 0.4.x SDK
+drives, that script alone is not a reason to stop.
+
+A bump does not adopt new SDK components. Hand-written address or phone fields
+stay hand-written; adopting `data-next-address` or another new component is
+separate work.
+
+## Approval gates
+
+Ask before every push, before opening the pull request, and before test
+orders. Test orders are real orders in the store that someone may have to
+cancel; follow the `next-campaigns-qa` rule: ask once up front, then follow the
+answer. Never write evidence or notes into the served tree: many static repos
+publish from the repository root. The hand-back goes on the ticket or the pull
+request.
+
+`qa run` against a preview that is not a local address posts its verdict to the
+QA portal on campaign-map.nextcommerce.com and prints the link. Say so when you
+ask about test orders, and pass `--local-only` unless the developer wants the
+verdict there. `qa run` writes its local verdict under `qa-output/` in the
+current folder (or `--output-dir <path>`). Keep `qa-output/` out of commits:
+check `.gitignore`, and never stage it.
+
+## 1. Branch
+
+Branch from an up-to-date `main`. List open pull requests that touch the
+campaign folder and ask the developer about merge order before branching.
+
+## 2. Find every pin
+
+**Page-kit repo** (`_data/campaigns.json` exists):
+
+- `sdk_version` on each slug's entry in `_data/campaigns.json`.
+- Pages that type the version into their own loader. Search with
+  `grep -rn "campaign-cart@v" src`. Switch each one to
+  `campaign-cart@v{{ campaign.sdk_version }}` so the data file is the only pin.
+  A data-file-only bump leaves those pages on the old SDK. The starter
+  templates render with Liquid and expose the entry as `campaign`; on a page
+  that does not, keep a literal version instead and say so. Step 5 checks the
+  built pages for an unrendered `{{`.
+- With a Build Packet, `campaigns-os page-kit sync --packet <packet>` (tier `B`)
+  writes the CampaignSpec's pin into the entry; without one, edit the entry.
+
+**Static repo** (no `_data/campaigns.json` anywhere in the repository, root
+included):
+
+- Preview with `campaigns-os sdk repin --target <funnel folder> --target-sdk <x.y.z>`
+  (tier `none` without `--apply`). It lists every loader and CSS pin with path
+  and line.
+- Scope it to the funnel folder, not the repository root. Repin rewrites every
+  semver pin below `--target`, so in a repository where funnels sit side by
+  side, a root-level `--apply` moves pages outside the bump. Check every listed
+  file belongs to the funnel, then run the same command with `--apply` (tier
+  `B`). It writes `.campaign-runtime/sdk-repin.json` under the target; that file
+  is served if the publish root includes it, so say so or keep it out of the
+  deploy.
+- `sdk repin` refuses a target with `_data/campaigns.json` at or below it,
+  but it does not look above `--target`. A funnel folder inside a page-kit
+  repository is not refused, so never point `sdk repin` at one; use the
+  page-kit steps above.
+
+## 3. Read the release diff against the campaign
+
+Read the release notes and the source diff between the two Campaign Cart tags.
+For each change, search the campaign's own JavaScript, includes and markup, and
+report file and line where the campaign depends on the changed behaviour. In
+particular:
+
+- Trace where the funnel's purchase event comes from before the bump. Static
+  funnels often hand-wire `order:completed` listeners and their own `dataLayer`
+  pushes; check that event's page and timing against the release you are
+  moving to.
+- If a page shows a discount before the SDK confirms a coupon, check that the
+  coupon exists on every campaign the funnel uses.
+- Note whether the range changes the card fields or the 3-D Secure flow; if it
+  does, plan a 3-D Secure test order in step 6.
+- When the range removes a feature the campaign uses, say so, and do not just
+  delete the call: that silently drops the feature from a live funnel. Look for
+  a documented replacement in the repository's own docs (`CLAUDE.md`,
+  `BUMP.md`) and the release notes. If none is documented, stop and ask.
+- Classify every `next:initialized` listener. From 0.4.42 the SDK fires that
+  event once and does not replay it, so a deferred script that only listens for
+  it can miss it on a cached reload. Guard each one in the bump: run now if
+  `window.next` exists and `document.body.dataset.nextSdkLoading === "false"`,
+  otherwise wait for the event, and run once either way. Step 6 proves it.
+
+## 4. Storage check
+
+Run `campaigns-os sdk storage-check --target <git-root> --target-sdk <x.y.z> --manifest <storage-migrations.v1.json> --scope <funnel folder,shared js>`
+(tier `none`). Take the manifest from an unmodified checkout of the target
+Campaign Cart tag (`docs/compatibility/storage-migrations.v1.json`, v0.4.40 or
+later), at the highest version its supported range declares. Read each
+`incompatible` and `unknown` line and say whose key it is. See
+`docs/sdk-storage-compatibility.md`.
+
+The manifest's `supportedSdkVersions` can stop below the tag it ships in: tags
+v0.4.39 to v0.4.42 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.42` returns
+`target-outside-manifest-range`. Run the check at the manifest's highest
+version and report that it does not speak for the versions above it.
+
+## 5. Build and check
+
+**Page-kit:** run a development build, confirm every built page loads only the
+target version and that no built loader URL still holds an unrendered `{{`,
+then `campaigns-os doctor --built <repo> --family <family> --slug <slug>`
+(tier `none`) for a repository with no Build Packet, or `campaigns-os doctor --packet <packet>`
+with one. Errors that are already on `main` are recorded, not fixed. Report doctor's
+advisories with the rest; an attribute flagged as missing from the SDK's index
+that the page does set (for example `data-next-page-type` on `<body>`) goes in
+the hand-back as unchecked, not fixed by guesswork.
+
+**Static:** there is no build and no doctor. Re-run the repin preview (it
+should list nothing below the target) and search the served pages for any
+remaining old version.
+
+## 6. Preview proof
+
+Deploy a preview and prove the bump with browser test orders under the
+approval rule above. `qa run --browser` needs the browser once per machine:
+`campaigns-os qa install-browser` downloads about 100 MB, so ask before running
+it. Pin the browser to the store's main market: a run
+geolocated elsewhere can order in another currency and skip a currency-gated
+upsell.
+
+- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --browser --test-order common`
+  (tier `C`; see `next-campaigns-qa`).
+- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --browser`
+  (tier `C`) checks the served pages. Place the approved test orders in the
+  browser and record each order number.
+- A static repo: place the approved test orders in the browser on the preview
+  and record each order number.
+
+Cover:
+
+- one card order per live checkout;
+- PayPal cancelled, then a card order, where PayPal is offered;
+- an upsell at quantity 2 or more on a page that shows a quantity picker;
+- a 3-D Secure card when step 3 found card-field or 3-D Secure changes, and whether it challenged;
+- the coupon path, if the funnel has one;
+- the purchase event fires once, on the page the release says it should;
+- each SDK page on a fresh load and on a cached reload, with every
+  `next:initialized` listener from step 3 running once on both.
+
+Read each order back in the store admin (the packet run's verdict under
+`qa-output/` also lists the orders it created) and keep the order numbers for
+the hand-back.
+
+## 7. Hand back
+
+On the ticket or the pull request, not in the repository: what changed (pins,
+loader rewrites), the storage-check and doctor results, a table of test orders,
+what is not proven, and which orders to cancel.

package/skills.json

@@ -1,7 +1,7 @@
 {
   "name": "campaigns-os-skills",
   "description": "Skills bundled with Campaigns OS. `skills.sh` installs these into the shared agent skill directories (~/.claude/skills, ~/.codex/skills), so each one is a versioned package: bump the version whenever a package changes. `bundle_revision` identifies the bundle as a whole — `<package version>+skills.<n>`, where the prefix is this package's version and `<n>` counts the skill-text revisions published against it. It advances whenever ANY bundled skill changes, every SKILL.md states it on its first body line, and `campaigns-os tooling status --skills-revision <value>` compares the value an agent read from a skill against the bundle on disk. See docs/skills-revision.md.",
-  "bundle_revision": "1.59.0+skills.1",
+  "bundle_revision": "1.60.0+skills.1",
   "homepage": "https://github.com/NextCommerceCo/campaigns-os",
   "retired_skills": [
     {
@@ -16,7 +16,7 @@
     {
       "id": "next-campaigns-os",
       "name": "Campaigns OS Lifecycle",
-      "version": "1.0.57",
+      "version": "1.0.61",
       "path": "skills/next-campaigns-os/SKILL.md",
       "domain": "campaigns",
       "description": "Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth."
@@ -24,7 +24,7 @@
     {
       "id": "next-campaigns-os-setup",
       "name": "Campaigns OS Setup",
-      "version": "2.0.40",
+      "version": "2.0.44",
       "path": "skills/next-campaigns-os-setup/SKILL.md",
       "domain": "campaigns",
       "description": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly next-campaigns-setup; renamed to release that name to the published NextCommerceCo/skills scaffolder."
@@ -32,7 +32,7 @@
     {
       "id": "next-campaigns-build",
       "name": "Campaign Build",
-      "version": "1.0.42",
+      "version": "1.0.46",
       "path": "skills/next-campaigns-build/SKILL.md",
       "domain": "campaigns",
       "description": "Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts."
@@ -40,7 +40,7 @@
     {
       "id": "next-campaigns-polish",
       "name": "Campaign Polish",
-      "version": "1.1.42",
+      "version": "1.1.46",
       "path": "skills/next-campaigns-polish/SKILL.md",
       "domain": "campaigns",
       "description": "Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign."
@@ -48,7 +48,7 @@
     {
       "id": "next-campaigns-qa",
       "name": "Campaign QA",
-      "version": "1.3.41",
+      "version": "1.3.45",
       "path": "skills/next-campaigns-qa/SKILL.md",
       "domain": "campaigns",
       "description": "Run spec-aware QA from a saved Map or local-spec Build Packet and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
@@ -56,7 +56,7 @@
     {
       "id": "campaign-lifecycle-orientation",
       "name": "Campaign Lifecycle Orientation",
-      "version": "1.0.37",
+      "version": "1.0.41",
       "path": "skills/campaign-lifecycle-orientation/SKILL.md",
       "domain": "campaigns",
       "description": "Orient a reader to the Campaigns OS lifecycle artifacts a run has already emitted, without advancing their state: the shared vocabulary, doctor as a gate, the stage record, and the store-theme/Page Kit two-worlds trap."
@@ -64,7 +64,7 @@
     {
       "id": "campaign-run-evidence",
       "name": "Campaign Run Evidence",
-      "version": "1.0.37",
+      "version": "1.0.41",
       "path": "skills/campaign-run-evidence/SKILL.md",
       "domain": "campaigns",
       "description": "Interpret existing doctor, QA verdict and proof-depth evidence without claiming more proof than the artifacts contain, and keep funnel proof apart from merchant launch readiness."
@@ -72,7 +72,7 @@
     {
       "id": "campaign-readback-classification",
       "name": "Campaign Readback Classification",
-      "version": "1.0.37",
+      "version": "1.0.41",
       "path": "skills/campaign-readback-classification/SKILL.md",
       "domain": "campaigns",
       "description": "Classify a selected campaign from the campaigns-os-readback/v2 fields (artifacts, staleness.stale_keys, clean, doctor, divergences, skip_cascades) and write a read-only handoff without turning diagnosis into permission."
@@ -80,10 +80,18 @@
     {
       "id": "contribution-intake",
       "name": "Contribution Intake",
-      "version": "1.0.37",
+      "version": "1.0.41",
       "path": "skills/contribution-intake/SKILL.md",
       "domain": "campaigns",
       "description": "Turn a suggestion about the agent surface into a classified, evidence-checked and redacted proposal, filed on this repository tracker only with attended approval."
+    },
+    {
+      "id": "next-campaigns-sdk-bump",
+      "name": "Campaign SDK Bump",
+      "version": "1.0.1",
+      "path": "skills/next-campaigns-sdk-bump/SKILL.md",
+      "domain": "campaigns",
+      "description": "Bump a live campaign from one Campaign Cart 0.4.x release to a later 0.4.x on a page-kit or static repo: find every pin, check the release diff and storage against the campaign code, prove on a preview with approved test orders, and report what is not proven."
     }
   ]
 }