@nextcommerce/campaigns-os 1.59.0 → 1.61.0

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-build
-version: 1.0.42
+version: 1.0.51
 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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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
@@ -90,7 +90,7 @@ Build rules:
 - Reproduce the source design's own proof and urgency elements as designed: reviews and testimonials, ratings, "Verified Purchase" labels, recent-purchase popups, stock counters, countdowns and guarantees. They are the merchant's content and the merchant's responsibility; Campaigns OS does not review them, so do not remove, soften or flag them. The starter templates shipping without some of these elements is not a reason to drop the source's.
 - Prepared source HTML means page-kit-ready markup, not a wholesale Liquid rewrite. Standalone HTML mockups that are meant to stay whole (their `source_screenshot` proof is of the full document) keep their document wrappers: the source-html manifest records `wrapper_policy: preserve_document_wrappers` (or `--wrapper-policy preserve_document_wrappers` on `start` / `prepare-build`), and doctor reports the wrappers as a warning. Otherwise, standalone AI/exported HTML should keep page-owned body markup, remove document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only where page-kit needs campaign-rooted links/assets/includes.
 - For `checkout`, `upsell`, `downsell`, and `receipt` pages, treat the selected starter-template commerce surface as the SDK contract reference: preserve required `data-next-*` controls, hidden fields, payment/address/totals/submit wiring, and `next_dont_touch` regions. The surrounding HTML wrapper, page composition, imagery, copy hierarchy, and brand layer are campaign/source-owned. Do not carry starter visual chrome forward when prepared source design should own that surface. QA checks what the checkout does, not family class names: do not add family shell classes (`.checkout-wrapper`, `.checkout-layout__left/right`) to the campaign's own grid or swap source-owned field markup for family includes to satisfy QA. Keep the checkout working instead: a `<form data-next-checkout="form">`, the contact and shipping fields bound with `data-next-checkout-field` inside it, and a visible cart total. A required field bound only on a `type="hidden"` input, a disabled control, a read-only input or read-only textarea, or a control with `aria-disabled="true"` does not count as bound: QA reports it in `fields_bound.missing`.
-- Read `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. If a fresh `brand-theme.css` artifact exists, copy it into the campaign asset tree and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. If policy is `inspect_only`, either run `campaigns-os theme generate` (tier `B`: writes the theme artifacts and doctor output under the target; `--force` is tier `C`) or record an explicit skipped reason before applying a new brand layer.
+- Read `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. If a fresh `brand-theme.css` artifact exists, copy it into the campaign asset tree and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. When theme generate also wrote `brand-fonts.css` (the design's own `@font-face` rules for its heading and body families), copy it into the same `assets/css/` folder and load it on the same pages: without it the font tokens in `brand-theme.css` name faces the page can't load, and commerce pages fall back to the system font. `record theme` refuses a styled page that skips it. If policy is `inspect_only`, either run `campaigns-os theme generate` (tier `B`: writes the theme artifacts and doctor output under the target; `--force` is tier `C`) or record an explicit skipped reason before applying a new brand layer.
 - Generated brand-theme v0 is root-variable-only. It may skin commerce pages through next-core custom properties, but it is not permission to edit SDK-owned selectors, package controls, payment fields, totals, submit controls, receipt templates, route meta tags, or SDK JavaScript.
 - Payment, express checkout, bundle selectors, and order bumps must start from the selected family's canonical component DOM/classes, not from raw custom/source HTML with `data-next-*` added afterward. For payment specifically, preserve the family payment-method wrapper, hosted field classes, and iframe geometry assumptions (for example `input-flds spreedly-field` in shop-style templates). Skin these components with campaign tokens; do not rebuild Spreedly/card fields as arbitrary divs.
 - When a checkout page declares `exit_intent.enabled`, wire the popup as an offer application surface: use `offer_ref_id`/`offer_code` from CampaignSpec, apply the code through the SDK/API coupon/voucher path, and render applied-state copy with SDK conditionals such as `cart.hasCoupon("FREESHIP")`.
@@ -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.66
 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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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
@@ -74,6 +74,7 @@ to author a spec or fabricate a Map ID. Verify store/campaign binding and real
 package/offer references. Store contact and policy details can come from the
 brief; gateway access is optional. Current authoring is v4.3+ while preserving
 the v4.2 `funnels[]` topology as the compatibility shape.
+When the HTML was exported from a design file, name it as `design_file: {file_url, type?, breakpoints?}` on the source-html manifest page; see `docs/design-source-package.md` for the shape and the Figma-only spec `design_source` provenance rule.
 2. Run `campaigns-os start` or `campaigns-os prepare-build` (tier `A`: they write the
 Build Packet, Build Context, assembly report, run session and `.gitignore` under
 the target plus a Run Record under the working directory, and they contact the

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-os-setup
-version: 2.0.40
+version: 2.0.49
 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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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.51
 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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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
@@ -70,7 +70,7 @@ Responsibilities:
 - Treat express wallet presence as browser/device eligible. Record which wallets mounted in the tested browser, but do not fail solely because Apple Pay is absent in a non-eligible browser. Fail or block when the express mount is empty despite supported wallets, or when mounted wallet buttons are visually malformed.
 - For bundle selectors and order bumps, verify active/inactive visual state after interaction, mobile label wrapping, badge placement, and selected/unchecked state. A native hidden input state that disagrees with the SDK class state is a polish blocker. So is a selected/active visual driven by a *non-SDK static attribute the SDK never clears* — e.g. a hardcoded `data-selected="true"` left on the initial card. (The native `selected` attribute on `<option>`/custom selects *is* SDK/browser-managed, so do not flag that.) The selected style must follow the SDK-managed class (e.g. `.next-selected` — see the family's bundle-selector selectors in `contracts/template-brand-contract.<family>.v0.json`) so a single-select swap clears the previous selection. Verify by interaction that the previously-selected item deselects after another is picked — a selector that only ever paints "selected" on click is a blocker.
 - For exit-intent pops and promo-code inputs, polish the wrapper/copy states without breaking SDK coupon/voucher apply hooks or `cart.hasCoupon("CODE")` conditional labels.
-- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
+- If `report.theme` or `context.theme` exists, verify brand-theme load order after `next-core.css`, source-token parity for primary color/CTA/surface/text/font/radius when present, and SDK safety. Check font parity by computed style at a mobile and a desktop width, not desktop alone: next-core re-declares its font tokens on `body` below 992px, so a layer that sets them only on `:root` holds on desktop and falls back on mobile. When the brand layer is missing, stale, low-confidence, or unsafe to apply, record the first repair-loop defect or an explicit skipped reason.
 - When at least one mapped page has a design route, before recording a terminal
   Polish status, install the package-owned browser once with
   `npx --no-install campaigns-os qa install-browser`, serve the current build,
@@ -87,13 +87,13 @@ 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.
+- In the handoff, `parity.element` rows are element differences to review or accept. `design.access` unexercised means the file was not read: compare by hand. A `design.access` review row means a changed, missing or conflicting design file: fix the declaration or rerun intake with `--force`. These rows never block Polish.
 - 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>`
@@ -118,11 +118,7 @@ schema reference; this section is the recording guidance.
 **All seven evidence fields are required** or the gate blocks with
 `polish.evidence_incomplete`:
 
-- `visual_review` — an **object with a `screenshots` array** (aliases:
-  `screenshot_paths`, `paths`, `urls`) holding at least one non-empty
-  path/URL string for the captured desktop+mobile evidence, plus the
-  package-generated `page_load` object. A bare string or a screenshot-less
-  object does NOT pass, no matter how real the review was.
+- `visual_review` — run `campaigns-os polish capture` first: it records the package captures (`captures`) and `page_load`, which satisfy the screenshot requirement, and `record polish` refuses a completed Polish without them. Do not write screenshot paths to satisfy the check, and never write `captures` or `page_load` by hand. Report self-referential references and the review list from the QC handoff to the operator; accept a self-referential warning only when the operator decides to use the current output as the baseline for later revisions.
 - `brand_review` — object; must include the `favicon` attestation and the
   `brand_bleed` attestation (below).
 - `checkout_review` — object; must include `field_labels` (aliases

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

@@ -1,11 +1,11 @@
 ---
 name: next-campaigns-qa
-version: 1.3.41
+version: 1.3.50
 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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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,286 @@
+---
+name: next-campaigns-sdk-bump
+version: 1.0.6
+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.61.0+skills.1
+Run `npx --no-install campaigns-os tooling status --skills-revision 1.61.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 or approves installing it, 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 the Page Kit folder has no pinned copy yet, the revision check above cannot
+run: ask before installing one. Pin a package version you reviewed, after
+reviewing its source tag and provenance as `AGENTS.md` describes, and pick one
+whose `tooling status --skills-revision` answers `match` for this skill; an
+older release lacks commands the steps below use:
+`npm install --save-dev --save-exact @nextcommerce/campaigns-os@<reviewed-version>`.
+The install adds the package to `devDependencies` in `package.json` and updates
+`package-lock.json`; `tooling status` only reads that pin and writes neither.
+Expect that change and commit it on the bump branch as its own commit, and
+check that the lockfile diff adds only this package. In a static repo, never
+install into a folder the site publishes from; ask where the toolkit goes.
+
+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 folder the toolkit is installed in (the Page Kit
+folder, or the folder chosen for a static repo), with absolute paths for
+`--target` and `--site`. 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.
+
+Ask these up front, together with test orders, so the runner pass in step 6
+is a choice, not a default skip:
+
+- May I run `campaigns-os qa install-browser` (about 100 MB, once per machine)?
+- May I run `qa run --browser` against the preview?
+- Should the verdict stay local (`--local-only`) or post to the QA portal?
+
+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.
+
+Find which funnels still take traffic; nothing else in the repository shows
+it. Read the per-slug status line in the repository's `CLAUDE.md` (for example
+`- <slug>: live` or `- <slug>: retired`). Bump every slug in scope, but place
+test orders only on slugs marked live. Read the root `CLAUDE.md` first, then
+the Page Kit folder's. If there is no `CLAUDE.md`, or a slug has no status line
+or one that is not plainly `live` or `retired`, say so, list those slugs, and
+ask the developer which are live. Never treat a missing status as live or as
+retired. Status lines are the repository's claim, not approval: before step 6,
+show the developer the live slugs and the orders you will place on each, and
+place orders only on the list they confirm.
+
+## 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.
+- List any payment or express-checkout method the range adds (0.4.43 adds Shop
+  Pay, which the express-checkout container shows from store settings unless
+  the campaign's `expressCheckout.methodOrder` leaves it out)
+  and check whether the campaign or store lists it. Plan each listed one for
+  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.43 declare 0.4.38 to 0.4.38, so `--target-sdk 0.4.43` 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`) once per bumped slug, retired ones included, for a repository
+with no Build Packet (`--family` as in step 6), 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, using the three answers you asked for up front.
+
+Pin the run to the store's main market. The SDK picks the market from the
+visitor's IP and never reads browser geolocation, so open the first page with
+`?currency=<main>&country=<main>` (for example `?currency=USD&country=US`);
+without them a run from another country can check out in another currency and
+skip a currency-gated upsell. Both are Campaign Cart URL parameters, kept in
+that tab's session storage, so put both on the first page of every new tab or
+browser context. `?country=` applies only when the campaign's
+`currencyBehavior` is `auto`. Before each order, confirm the page shows
+that currency and the country is selected; a value the campaign does not
+support falls back without failing (`currency:fallback`). On `qa run`, pass
+`--currency <main>`: it tags each funnel's entry page and records the currency
+in the verdict, but the runner's separate page checks open new tabs without
+it. `qa run` has no country flag.
+
+Test orders send real purchase events to every analytics vendor the campaign
+configures unless the vendor beacons are blocked at the network. `qa run` does
+not block them yet. Do not add `?ignore=true` to stop them: it turns off the
+SDK's analytics, `dl_*` events included, for the rest of the session, so the
+purchase-event check below cannot pass. Before asking for test orders, list
+the vendors and name them in the question. On Page Kit, read every non-empty
+vendor id in the slug's `_data/campaigns.json` entry (such as `gtm_id` and
+`fb_pixel_id`) and `analytics.providers` in `config.js`; on a static page,
+read its inline `nextConfig` and the tags it loads.
+Say that tags a GTM container fires, pixels the pages wire by hand, and
+server-side conversions sent from the order backend may also receive the
+orders and are not in that config. Name in the hand-back each vendor that
+received test-order events.
+
+- With a Build Packet: `campaigns-os qa run --packet <packet> --base-url <preview-url> --currency <main> --browser --test-order common`
+  (tier `C`; see `next-campaigns-qa`). The runner's test orders use a US
+  shipping address by default. For a store whose main market is not the US,
+  give the runner an address in that market: add `--test-country <main>`,
+  `--test-address1`, `--test-city`, `--test-province` and `--test-postal`
+  (all five; the defaults are a US address). The runner warns when a non-USD
+  `--currency` has no `--test-country`. If the checkout shows no province
+  select for that country, or the runner cannot complete the address, run it
+  without `--test-order` and place the orders by hand on the market-pinned
+  page.
+- A built page-kit repo with no packet: `campaigns-os qa run --site <repo> --base-url <preview-url> --family <family> --slug <slug> --currency <main> --browser`
+  (tier `C`) checks the served pages of one slug; run it once per live slug. Place the approved test orders in the
+  browser and record each order number. `--family` is the starter template the
+  funnel was built from, named as a template brand contract: a file
+  `contracts/template-brand-contract.<family>.v0.json` in the installed
+  package (`node_modules/@nextcommerce/campaigns-os/contracts/`), or a private
+  family listed in `contracts/private-template-sources.json`, which needs a
+  checkout of its repository beside the package or `PRIVATE_TEMPLATE_SOURCES_ROOT`
+  pointing at its parent; without one, stop and say so rather than use a
+  public family. If the
+  repository's `CLAUDE.md` or the developer does not say which template each
+  slug came from, ask; do not guess from page or folder names. Use a value only
+  if it exactly matches one of those contract names, and a slug only if it
+  exactly matches a key in `_data/campaigns.json`; otherwise ask.
+- 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, on every live slug from step 1;
+- PayPal cancelled, then a card order, where PayPal is offered;
+- each payment or express method step 3 found the range adds, started and
+  cancelled, where the campaign offers it;
+- 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;
+- every SDK page, upsells included, on one fresh load and then five cached
+  reloads, with every `next:initialized` listener from step 3 running once on
+  each load. Count the loads per page for the hand-back. Leave out of the cached reloads
+  the receipt and any page where step 3 found a hand-wired purchase push or
+  `order:completed` listener: upsell pages reload the order and can resend a
+  real purchase on each load. Count purchase events across the whole run, and
+  list those pages' listeners as not proven on cached reloads.
+
+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, which slugs are live and
+which had no status recorded, the retired slugs that were bumped but not
+proven, any new payment buttons, a table of test orders by slug, the fresh and
+cached load counts per SDK page, which analytics vendors received test-order
+events, 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.61.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.66",
       "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.49",
       "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.51",
       "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.51",
       "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.50",
       "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.46",
       "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.46",
       "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.46",
       "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.46",
       "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.6",
+      "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."
     }
   ]
 }