@nextcommerce/campaigns-os 1.33.0

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

@@ -0,0 +1,145 @@
+---
+name: next-campaigns-polish
+version: 1.1.1
+description: Run the visual/runtime polish pass after build and before QA for a Campaigns OS campaign.
+---
+
+# Next Campaigns Polish
+
+Use this after build has produced a runnable page-kit campaign.
+
+Theme gate: `campaigns-os next polish` blocks when theme inspect found a
+generatable brand theme that is not yet applied to commerce pages. Do not work
+around the gate — apply the brand layer (`theme generate`, copy into campaign
+assets, load after `next-core.css`, record `report.theme`) or record an
+explicit waiver (`campaigns-os theme waive --packet <p> --reason "<why>" --waived-by "<named human>"`; placeholders are refused).
+
+Responsibilities:
+
+- Compare prepared source design against built campaign pages.
+- Scan the prepared source assets for brand marks such as `logo*.png`, `logo*.svg`, and obvious header/logo images before leaving starter-template logos in place.
+- Scan **visible** rendered text inside the family's content/commerce surfaces (the selectors enumerated in `contracts/template-brand-contract.<family>.v0.json`) for placeholder/residue copy the build should have replaced — the *literal starter defaults*: lorem-ipsum, the unmodified starter headings (`Product Name` / `Package Title` / `Your headline`), `[VERIFY …]` author notes, `TODO` markers. Match the literal starter strings, not any authored copy that merely contains those words, and skip `<script>` / `<style>` / JSON-LD / `data-*` attributes. Treat a surviving literal starter default on a content/commerce surface as a polish blocker — replace it from the prepared source / CampaignSpec; do not draft substitute copy (if the design's authored copy is genuinely missing, flag it rather than invent it). This is *copy* residue, complementary to the computed-style / asset residue gated by `next-campaigns-qa` + the brand contract — not a duplicate of it.
+- Flag template *defaults* left where they disagree with the prepared design — e.g. the same benefit icon repeated across a grid *when the design uses distinct icons*, or a guarantee badge/term that disagrees with the design — as polish defects, not just logos. Judge against the prepared source, not taste: copy or imagery the source/CampaignSpec does not supply (e.g. a placeholder testimonial name/quote/role) is residue; "looks generic" on its own is not.
+- **Brand-bleed (cloned-source de-brand) pass.** When a campaign is cloned from a proven sibling, the sibling's brand defaults ride along. Inspect the built pages and assets for residual cross-brand bleed and clear it before recording: (1) a residual promo/sale banner or coupon code/copy from the source campaign (including a baked-in *fake* code); (2) a prior-campaign / sibling favicon left in place; (3) scaffold or non-design fonts the design did not specify (e.g. starter `Plus Jakarta`); (4) hardcoded non-token colors — any brand color literal that should be a token, such as next-core's `#C670FE` "Most Popular" pill. Clear each from the prepared source / CampaignSpec and brand theme (tokens, not literals); flag — do not invent — anything the design genuinely doesn't supply. Treat surviving bleed as a polish blocker. This complements the favicon/logo and copy-residue checks above; it is the cross-brand contamination angle, not a duplicate.
+- Read the assembly report decisions before polishing. Do not reintroduce source-HTML elements that build intentionally dropped because CampaignSpec/API did not support them, such as unavailable payment methods.
+- **Remove or rename a contract-listed payment-chrome asset; never edit one in place.** The assets named in `contracts/template-brand-contract.<family>.v0.json` under `default_residue.payment_chrome.assets` are keyed by QA on the *referenced basename*, not on their contents. Stripping the unsupported marks from inside a shared file such as `upsell-payment-logos.svg` leaves the reference in place, so QA reports residue for an asset that no longer carries any — and on 2026-09-06 the repair loop's remedy for that report deleted a cards-only trust strip that was correct. Delete the asset, or write a new one under a new name and repoint the reference. QA downgrades an edited-in-place asset to `manual_review` rather than a blocker, but that is a safety net for a mistake, not the supported way to do this.
+- Preserve existing `report.theme` data. If polish changes generated theme CSS, load order, commerce-page coverage, theme warnings, or the first repair-loop defect, update the Assembly Report `theme` block rather than leaving stale evidence.
+- Patch only SDK-safe CSS, skin, layout, and content surfaces.
+- Preserve checkout/cart/upsell/receipt runtime wiring.
+- Capture desktop and mobile evidence for key commerce anchors.
+- For checkout payment, capture zoomed evidence of the express-wallet mount and card fields after SDK readiness. Verify that the visible hosted card and CVV input paths are vertically centered inside native-looking controls; do not accept full-height Spreedly iframes, oversized blank fields, or placeholder text pinned to the top edge.
+- 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.
+- Before recording a terminal Polish status, install the package-owned browser
+  once with `npm run qa:install-browser`, serve the current build, and run
+  `campaigns-os polish capture --packet <packet> --base-url <served-build-url>`.
+  The package captures every mapped route at fixed desktop/mobile viewports and
+  attaches `stages.polish.evidence.visual_review.page_load`. Never hand-author,
+  copy, or repair that object directly.
+- Record polish as `completed`, `skipped`, or `blocked` in the assembly report.
+  A nonzero capture result keeps Polish blocked until repair and recapture. The
+  producer persists bounded incomplete evidence for diagnosis and does not mark
+  the stage complete.
+- Use `npm run smoke:polish-capture` only as an optional local producer smoke
+  after browser installation. It opens a loopback fixture server and is not
+  part of `npm run check` or the CI browser lane.
+
+## Recording polish evidence
+
+The polish gate (`campaigns-os next polish` / QA handoff) reads structured
+evidence from `stages.polish.evidence`. The full accepted schema — stage-record
+requirements, every required field's accepted shape, the favicon certification
+shape and its escape semantics, the semantic text scans, and the blocker-code
+ladder — is documented in `docs/polish-evidence.md`. That document is the
+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.
+- `brand_review` — object; must include the `favicon` attestation and the
+  `brand_bleed` attestation (below).
+- `checkout_review` — object; must include `field_labels` (aliases
+  `initial_field_hints`, `visible_labels`) confirming legible initial field
+  hints, and `bump_compare_price_rule` (alias `bump_compare_price`)
+  confirming no equal/no-discount compare price renders.
+- `template_residue_review` — non-empty; its `starter_favicon` entry accepts
+  the same certification shape as `brand_review.favicon`.
+- `commerce_flow_review` — non-empty string/array/object.
+- `issues` — **must be an array**; `[]` is the canonical "no issues found".
+- `commands` — non-empty array of the commands polish actually ran; never
+  include build commands (that reads as self-certification).
+
+The stage record itself must carry `performed_by: "next-campaigns-polish"`,
+`source_build_fingerprint` equal to the current
+`stages.assembly.build_fingerprint`, `completed_at`, and — when the report
+fingerprints a Design Source Package — `source_package_material_fingerprint`.
+
+The `polish.hidden_eager_media` checkpoint blocks on nonwaivable missing,
+malformed, stale, integrity-invalid, route-mismatched, or incomplete package
+capture evidence. A complete finding means one computed-hidden `video` or
+`audio` element transferred strictly more than `1,048,576` bytes without an
+exact ASCII-case-insensitive `preload="none"` or `preload="metadata"` content
+attribute. Repair and recapture first. Only a complete real finding has an exact
+named-human waiver lane:
+
+```bash
+campaigns-os checkpoint waive \
+  --packet <packet> \
+  --gate polish.hidden_eager_media \
+  --reason "<why this exact finding is accepted>" \
+  --waived-by "<named human>" \
+  --review-condition "<specific re-evaluation trigger>"
+```
+
+The waiver remains visible and becomes inert when the build, slug, route plan,
+fixed viewports, or finding state changes.
+
+The favicon certification shape is authoritative (it skips the free-text leak
+scan): `{ "byte_match": true }` or `status`/`result` one of `matched_source`,
+`promoted_source`, `confirmed_non_template`, `no_source_candidate`. Free-text
+favicon evidence is scanned for starter-leak phrasing and the literal
+`images/favicon.png` path — certify structurally when you verified byte-level.
+
+Record, alongside the favicon (`brand_review.favicon`) and order-bump
+compare-price (`checkout_review.bump_compare_price_rule`) attestations the
+gate already checks, a `brand_review.brand_bleed` attestation for the de-brand
+pass above. Without it the gate blocks every completed polish run.
+
+Write the cleared result as an object — `cleared: true` is the canonical,
+unambiguous form (the gate accepts it directly and does not then scan the rest
+of the object for residue):
+
+```jsonc
+"brand_review": {
+  "favicon": { "byte_match": true, "status": "matched_source" },
+  "brand_bleed": {
+    "cleared": true,
+    "promo_codes": "none",
+    "favicon": "brand favicon",
+    "fonts": "design fonts only",
+    "colors": "tokenized"
+  }
+}
+```
+
+Field precedence is `brand_bleed`, then aliases `brand_bleed_review`, then
+`debrand`. A confirming free-form string is also accepted (e.g. `"promo banner
+stripped, design fonts only, colors tokenized, no prior favicon"`).
+
+Pitfall: if you record bleed as a string (or omit `cleared: true`), the gate
+runs a negative-text matcher over the value. Affirm clearance and do **not**
+echo the offending tokens — phrasings like `cleared: false`, `not cleared`,
+`bleed found`, `#C670FE`, `Plus Jakarta`, `prior-campaign`, or `promo code …
+still present` all block, even when describing what you *removed*. State the
+cleared outcome (`"de-brand pass complete, no residue"`), not the residue you
+deleted. If bleed genuinely remains, record `cleared: false` (or `bleed_found:
+true`) so the gate blocks until it is fixed — never paper over it.
+
+Polish is not QA and does not certify launch readiness.

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

@@ -0,0 +1,92 @@
+---
+name: next-campaigns-qa
+version: 1.3.1
+description: Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof.
+---
+
+# Next Campaigns QA
+
+Use this after the campaign has a preview or production URL and the assembly report records build and polish status. The public v0 runner is Node/npm-based, with an owned Playwright browser pass:
+
+```bash
+npm run qa:install-browser
+npm run campaigns-os -- qa resolve --packet campaign-runtime.build.json
+npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url>
+# Fixture-driven migration parity proof. Publishes to the QA portal by default.
+npm run campaigns-os -- qa parity --fixture <parity-fixture.json> --scenario <scenario-id> --base-url <preview-url>
+# Browser QA + typed-card proof. Publishes to the QA portal by default and prints the portal link.
+npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common
+# Offline / dev / CI only: keep the verdict local
+npm run campaigns-os -- qa run --packet campaign-runtime.build.json --base-url <preview-url> --browser --test-order common --no-post-verdict
+```
+
+`npm run qa:install-browser` is part of the standard QA sequence. Run it once
+after install/update before using `--browser` or `--test-order`; do not skip it
+unless the local Playwright browser binary is already installed.
+
+Inputs:
+
+- Campaign Map ID from the Build Packet
+- tested base URL (localhost dev URL, preview URL, or production URL)
+- assembly report
+- Test-order coverage choice (`common` default vs explicit paths vs topology-complete `full`) and SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation so the SDK loads)
+
+Rules:
+
+- Use the public Node/npm `campaigns-os qa` commands for campaign QA runs.
+- Canonical `qa run` automatically runs commercial parity for enabled pages with package rows when their source evidence is available. It reuses each page's read-only source fetch and the existing read-only `POST /api/price-preview`; neither creates carts, orders, or transactions. The lane is warn-first: proven price, recurring-cadence, and voucher mismatches become warn-severity `pricing` assertions, with compact coverage and findings at top-level `verdict.commercial`. Omitted or otherwise unprovable claims emit no mismatch assertion and do not change an otherwise-ready disposition; incomplete coverage remains visible in `verdict.commercial`.
+- Use `qa parity` for migration cells that carry a parity fixture; select the fixture scenario and drive that offer through the candidate funnel.
+- Parity capture blocking proof is the voucher-adjusted persisted line from typed-card order readback. Browser totals and client state do not replace the persisted-line voucher guard.
+- Read client purchase values per event. A whole-cart `dl_purchase` must not mask or supply an offer-level upsell purchase expectation.
+- Live `qa parity` runs publish to the QA portal by default like other QA runs. Pass `--no-post-verdict` for dev, replay, negative-control, and other local proof runs.
+- Theme gate: `qa run` refuses to run when a generatable brand theme is not applied to commerce pages and no waiver exists. Apply the brand layer or record a waiver (`campaigns-os theme waive` / `qa run --theme-waive "<reason>"`); do not bypass the gate another way. A waived run still reports template-residue findings at warn severity.
+- Template residue is a QA dimension, not advice: promoted starter families must have a brand/residue/pricing contract (`contracts/template-brand-contract.<family>.v0.json`). Browser QA inspects computed styles on commerce surfaces and fails pages that still render starter defaults (`#3c7dff`/`#0a265c`, starter `next-logo.png`, paypal/klarna chrome absent from the spec).
+- Pricing visibility is a blocker: an upsell/downsell offer with zero visible price rows fails QA. Pricing surfaces render via template pricing modes (`full_price`, `compare_at_current`, `unit_price_plus_total`, `savings_badge_amount`, `code_discounted_post_checkout`), never via campaign CSS `display:none` on price wrappers.
+- Exit-pop widgets are governed offer surfaces. If the selected family ships or copies a default exit-pop and CampaignSpec has no checkout `exit_intent` or `promo_code_input`, QA/doctor must report it as residue; strip it or wire the mapped offer/code through the SDK coupon path.
+- Typed-card runs emit a per-step ladder (`[qa:test-order] step=... status=...`) with bounded per-step and per-path timeouts, and always produce a verdict — a hung or crashed path is a blocked verdict with the step ladder as evidence, not a silent exit. Read the last completed step before re-running.
+- A typed-card path that fails is classified by **what it did to the store** before the runner decides what to do about it. A failure the runner can prove happened before submit (`not_created`) is **re-run once, if the creation budget has a slot no still-unrun planned path needs** — so a transient miss is not reported as a defect in the build, without an early path eating budget the last planned paths need. Under the default budget a path whose submit was *rejected* has already spent its own slot, so it is not re-run and records `evidence.order_creation.rerun_skipped` instead. When the re-run does happen, both attempts appear in `test_orders[]` and `evidence.retry` names the first attempt's error and ref id. A failure that happened **after** the order was created (`created` — most often a receipt that did not render) is **never resubmitted**: the runner reloads that order's receipt and re-runs only the read-only checks, and `evidence.recovery` carries the original failure, the checks re-run, and whether it cleared. Read `evidence.order_creation` for two separate counts: `submissions_reserved` (platform-side creation slots charged to this path — reserved before a submit click, or charged for a hosted-checkout redirect where no submit click happens — which stand even when the create then failed) and `orders_confirmed_created` (creates the platform was observed to accept) — a spent slot with no confirmed order is the ambiguous case, not an order to reconcile. Recovery clears only on persisted evidence it re-read on that pass: a failed or absent order read-back stops it honestly rather than re-deciding against the original attempt's numbers. An outcome it cannot prove either way (`ambiguous` — an unusable read-back, a lost create response, a network-failed create, a 4xx after an earlier 2xx) stops the path and names the operator check instead of buying again. A pass that only came back after recovery is never indistinguishable from a first-attempt pass, and a failure that survives recovery still blocks.
+- Analytics correctness is two-phase in the same run: the campaign-root visit inventories declared providers/tags only, then the one canonical typed-card run proves Purchase for each topology-recognized receipt from the signals emitted across every page the path loaded after checkout, read after the full `--analytics-settle` window. The receipt qualifies the order; the journey is measured, because the SDK fires `dl_purchase` (and the outbound Purchase) on the first `?ref_id=` page — the upsell page when the funnel has one — and dedupes it on the receipt. It never places a second analytics order. The receipt document's own reading stays in evidence (`receipt_signals`, `fired_on`) as the diagnostic of which document fired.
+- A missing or topology-unrecognized receipt is `MANUAL_REVIEW`/`WARN`; a recognized receipt with no dataLayer, outbound Meta, or outbound GA4 Purchase is `FAIL`/`BLOCKER`. Capture, unreadable-page, and settle-deadline errors on a recognized receipt are explicit non-waivable blockers. The `analytics-correctness:purchase-fires` waiver applies only to a genuine recognized-receipt/no-signal failure.
+- Keep QA in a tight sequence: install the Playwright browser, resolve topology, run browser QA plus typed-card proof with `--test-order common` by default. Test orders need no permission step. Pause only for missing inputs, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty.
+- Use `--browser` for rendered browser evidence. Browser QA must use the package-owned Playwright flow, not external agent/browser skills.
+- QA runs publish to the QA portal by default, so the QA tab/dashboard carries the full audit log and the run prints its portal link — report that link as the run reference. Pass `--no-post-verdict` (or `--local-only`) only for offline / dev / CI runs; those stay local-only under `qa-output/` and must not be reported as dashboard-visible.
+- Browser QA must include checkout commerce geometry evidence, not just mount counts: express-wallet buttons rendered in the current browser, card/CVV hosted iframe host dimensions, iframe text-path height, and center alignment. Apple Pay is browser/device eligible, so record mounted wallet kinds instead of requiring Apple Pay in Chrome-only QA.
+- `qa resolve` accepts either the deploy host or the campaign-root URL; when a Build Packet carries `campaign.public_route_slug`, the runner resolves page URLs under that slug.
+- Routing meta tags must be checked in runtime form. `next-success-url`, `next-upsell-accept-url`, and `next-upsell-decline-url` should point at campaign-root paths such as `/campaign-slug/upsell/`, not source filenames or unrooted spec literals.
+- Upsell accept/decline routes may be SDK-bound controls rather than static `<a href>` links. Treat rendered `data-next-upsell-action="add"` and `data-next-upsell-action="skip"` controls as valid route evidence, then prove the path in the browser walkthrough.
+- When CampaignSpec declares checkout `exit_intent.enabled`, browser QA should trigger/open the pop, accept the mapped offer, and verify the code is active, totals/order summary reprice through SDK/API state, and `cart.hasCoupon("CODE")` presentation appears only after apply.
+- When CampaignSpec declares checkout `promo_code_input.enabled`, browser QA should enter the mapped `offer_code` and verify active-code state, repricing, discount row rendering, and conditional presentation. Missing promo-code input is a blocker when CampaignSpec, source design, or user instructions declared it.
+- A declared offer surface that the build never shipped is a blocker, not a silent pass. Every `--browser` run emits `browser-exit-intent-surface:<page>` and `browser-promo-code-surface:<page>` for each checkout page whose CampaignSpec declares the surface with `enabled: true`. Absent markup is `FAIL`/`BLOCKER`; a surface that renders but cannot be tied to the declared `offer_code` (or sits behind an unopened disclosure) is `MANUAL_REVIEW`/`WARN`. Exit-intent markup is looked for inside `<template>` content as well as the live document, because a correctly built pop lives nowhere else before it fires. A browser collector that threw mid-read `SKIP`s with the cause instead of blocking — it did not find nothing, it could not look.
+- Typed-card runs reconcile the persisted order against what the checkout displayed at submit, and report both halves separately from whether the order was created: `browser-order-display-parity:<plan>` fails as a blocker naming any `is_upsell: false` line whose package the checkout never rendered as selected (and any displayed package that was never charged), and `browser-order-total-parity:<plan>` fails as a blocker when the order's pre-upsell total disagrees with the displayed summary total. Both `SKIP` with a stated reason when the page gives them nothing to compare — a summary whose rows carry no `data-package-id`, or a checkout with no `[data-next-display="cart.total"]` surface. Read a skip as missing coverage, never as a pass.
+- Test orders must exercise the tested campaign through the Campaign Cart SDK, not a hand-built backend API request.
+- Use the canonical Playwright typed-card path: fill customer/shipping fields, type sandbox card data into the active hosted payment iframes, and click the real checkout submit button.
+- Use a shared safe inbox for typed-card test-order customer email when the operator provides one. Reusing one safe inbox keeps customer/user lists clean while still allowing notification delivery.
+- The legacy SDK test-mode event and direct API order path are diagnostic fallbacks only; do not use them as launch proof unless the operator explicitly asks for a diagnostic fallback.
+- Do not use `next.getCartData().cartLines` as cart-populated proof. That field currently stays empty; use typed-card order read-back for committed cart truth, the `cart:updated` payload `items` / `summary.lines` for in-page cart state, and rendered bundle DOM evidence for pre-commit selection.
+- After the base checkout test order redirects to upsell, click the rendered SDK upsell accept/decline controls to prove the live upsell path. Do not fabricate upsell lines with a direct API call.
+- Valid test-order modes are `common`, `checkout`, `accept`, `decline`, `both`, `full`, `off`, and explicit accept/decline paths such as `accept-decline-accept`.
+- Browser test orders default to `--max-test-orders 6` (an accidental-flood guard, not a permission gate). Planning happens before browser launch; when `full` exceeds the cap, use explicit sample paths or rerun with the exact larger cap printed by the command (a linear three-offer graph plans nine orders, so use `--max-test-orders 9`). That cap bounds planned paths; `--max-order-creations` bounds real order creations, defaults to the planned path count, and is reserved before each submit click. A run that hits it stops that path with an explicit budget assertion — read it as a safety stop, not as a checkout defect, and account for the orders already created before raising it.
+- Resolve paths from the selected checkout's `expected_next_url`, then follow reachable offer `expected_accept_url` / `expected_decline_url` edges. Treat only declared receipt/thank-you pages and genuine cross-origin handoffs as terminals; an absent same-origin route is unresolved, not an external handoff.
+- `--test-order common` runs checkout plus first-offer accept/decline and adds the shortest real receipt path, deduplicated to at most four orders. It must not synthesize a receipt path from offer count.
+- Use `full` for every actual terminal path. The graph walk is deterministic and cycle-safe; cycles, missing routes, unresolved same-origin targets, and reachable nonterminals block `full` before browser launch instead of producing phantom coverage.
+- A path with remaining actions may stop cleanly only at a terminal recognized in that selected topology. Missing accept/decline controls on any other page are blockers. A cross-origin handoff is a valid terminal navigation but is not receipt-rendering or persisted-receipt proof.
+- Keep multi-funnel and `tiers:common` / `tiers:full` plans isolated to each selected checkout's own funnel graph, tiers, and recognized terminals; never borrow an unrelated funnel's receipt page.
+- Accepted-upsell proof is valid only when the browser observes the order upsell API mutation and the final order evidence contains the selected upsell package. A checkout bump line marked `is_upsell` is not accepted-upsell proof.
+- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific sandbox routing confirmation. Localhost on any port is globally available as a Campaigns App Development domain and suppresses Campaigns analytics; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
+- Launch readiness is separate from Campaigns OS proof. If QA passes on local/preview, still surface production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration as real-shopper readiness items before launch.
+- For multi-market campaigns, verify at least one non-default currency/country path: currency display, shipping method names/prices, available payment methods, and market-specific copy.
+- Treat missing deploy URL, missing polish status, or unresolved doctor blockers as launch blockers.
+- Report blockers, warnings, and residual risks.
+- QA follows build and polish; it does not edit campaign code.
+
+Canonical test-order flow:
+
+1. Open the deployed checkout URL in the package-owned Playwright browser session.
+2. Select the intended bundle/cart using the rendered campaign controls.
+3. Fill the checkout fields with QA customer/address data.
+4. Type the sandbox card into the active hosted payment iframes and click the real checkout submit button.
+5. Wait for the SDK to create the test order and redirect with `ref_id`.
+6. On upsell pages, click the actual accept or decline button for the target path.
+7. Verify receipt/order evidence and summarize order number, `ref_id`, selected cart, active vouchers/promo codes, discounts, upsell path, and line-item result.
+
+Do not use `campaigns-os qa --legacy-api-test-order` as the canonical proof path. It bypasses the deployed campaign page and the SDK checkout/upsell surfaces; keep it only as a diagnostic fallback when explicitly requested.

package/skills.json

@@ -0,0 +1,56 @@
+{
+  "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.",
+  "homepage": "https://github.com/NextCommerceCo/campaigns-os",
+  "retired_skills": [
+    {
+      "id": "next-campaigns-setup",
+      "replaced_by": "next-campaigns-os-setup",
+      "retired": "2026-08-06",
+      "detect_description_prefix": "Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet",
+      "reason": "Name released to the published page-kit scaffolder (NextCommerceCo/skills). install-skills removes OUR stale installed copy from shared skill directories when frontmatter name + description prefix match; anything else wearing the name is left alone."
+    }
+  ],
+  "skills": [
+    {
+      "id": "next-campaigns-os",
+      "name": "Campaigns OS Lifecycle",
+      "version": "1.0.16",
+      "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."
+    },
+    {
+      "id": "next-campaigns-os-setup",
+      "name": "Campaigns OS Setup",
+      "version": "2.0.0",
+      "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."
+    },
+    {
+      "id": "next-campaigns-build",
+      "name": "Campaign Build",
+      "version": "1.0.2",
+      "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."
+    },
+    {
+      "id": "next-campaigns-polish",
+      "name": "Campaign Polish",
+      "version": "1.1.1",
+      "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."
+    },
+    {
+      "id": "next-campaigns-qa",
+      "name": "Campaign QA",
+      "version": "1.3.1",
+      "path": "skills/next-campaigns-qa/SKILL.md",
+      "domain": "campaigns",
+      "description": "Run spec-aware QA from a Campaign Map ID and tested campaign URL after build, polish, and deploy/local evidence exist, including Playwright typed-card test-order proof."
+    }
+  ]
+}

package/skills.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLI=(node "$ROOT/bin/campaigns-os.mjs")
+
+usage() {
+  cat <<'EOF'
+Campaigns OS local skill helper
+
+Usage:
+  ./skills.sh status
+  ./skills.sh install [claude|codex|agents|all]
+  ./skills.sh dry-run [claude|codex|agents|all]
+  ./skills.sh context <target-campaign-repo>
+
+Examples:
+  ./skills.sh status
+  ./skills.sh install codex
+  ./skills.sh install all
+  ./skills.sh context ../my-campaign-repo
+
+Targets:
+  claude  -> ~/.claude/skills
+  codex   -> ~/.codex/skills
+  agents  -> ~/.agents/skills
+  all     -> all of the above
+EOF
+}
+
+action="${1:-status}"
+platform="${2:-all}"
+
+case "$action" in
+  status)
+    "${CLI[@]}" install-skills --platform all --dry-run
+    ;;
+  dry-run)
+    "${CLI[@]}" install-skills --platform "$platform" --dry-run
+    ;;
+  install)
+    "${CLI[@]}" install-skills --platform "$platform"
+    ;;
+  claude|codex|agents|all)
+    "${CLI[@]}" install-skills --platform "$action"
+    ;;
+  context)
+    target="${2:-}"
+    if [[ -z "$target" ]]; then
+      echo "Missing target campaign repo." >&2
+      usage >&2
+      exit 2
+    fi
+    "${CLI[@]}" install-agent-context --target "$target"
+    ;;
+  help|-h|--help)
+    usage
+    ;;
+  *)
+    echo "Unknown command: $action" >&2
+    usage >&2
+    exit 2
+    ;;
+esac