@nextcommerce/campaigns-os 1.46.0 → 1.48.0

package/CHANGELOG.md

@@ -2,6 +2,348 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.48.0] - 2026-10-02
+
+### Changed
+
+- The supported surface advances to 1.48.0 and ships the same-surface
+  changes recorded since 1.47.0, each described in its own section below:
+  the local setup command starts with `npm init -y` (`+agent.1`); the
+  `start`, `prepare-build` and `build` usage lines list
+  `--deploy-target`, `--preview-url` and `--production-url` (`+agent.6`);
+  doctor no longer scans built pages for proof and urgency copy
+  (`+agent.7`); QA stops failing the checkout price check on a checkout whose
+  cart is filled on an earlier page, and recognises the starter templates'
+  SDK loader (`+agent.8`); `readback` shows `warn` and `manual_review` rows as
+  themselves, and the agent context sends a resumed session to `readback`
+  and `next` first (`+agent.9`); a test order refused as a duplicate says so
+  (`+agent.10`); doctor's missing SDK pin message names the SDK the template
+  family was verified against (`+agent.11`); the local preview carries
+  missing polish and page-load evidence forward as warnings, so a campaign
+  built from a starter template can reach a test order (`+agent.12`); and the
+  vendored starter-template catalog is pinned to
+  campaign-cart-starter-templates `37a8d94` (`+agent.13`).
+- The bundled SDK support policy's `latest_known_release` returns to 0.4.38,
+  the value 1.47.0 shipped; `+agent.11` had moved it to 0.4.40. The policy
+  line only feeds template freshness, where the catalog's verification
+  records already name 0.4.40 as the current SDK, so freshness results and
+  doctor's missing SDK pin message are unchanged.
+- Bundled skills carry revision `1.48.0+skills.1`, with each skill version
+  advanced one patch, and the local setup install command pins the 1.48.0
+  package. The skill text is unchanged.
+
+## [1.47.0+agent.13] - 2026-10-02
+
+### Changed
+
+- The vendored starter-template catalog is re-synced to
+  campaign-cart-starter-templates `37a8d94` (was `3793b1d`). That brings in
+  the single-offer upsell copy priced outside the offer, order bumps that hide
+  their savings line and badge when the package has no discount, the
+  `is_upsell` wording for order reports, and refreshed template verification
+  evidence for Campaign Cart SDK 0.4.40. The verified SDK and the SDK support
+  policy are unchanged.
+- `fixtures/certified-families` is regenerated at the new pin, and the shared
+  commerce brand contract's payment-chrome `asset_pin` moves with it. The
+  shipped asset bytes are unchanged.
+
+## [1.47.0+agent.12] - 2026-10-01
+
+### Changed
+
+- On the local preview (a `local-serve` packet served from a loopback host),
+  missing polish and page-load evidence no longer stops the loop before a
+  typed-card order. One policy, `src/local-preview-policy.mjs`, carries
+  forward `polish.evidence_missing` / `polish.report_missing`, a page-load
+  checkpoint with no capture recorded, and the new
+  `polish.hidden_eager_media.no_capturable_routes` (every mapped page is
+  template stock). It also makes starter-template residue a warning when the
+  theme gate finds nothing generatable. Doctor reports these as warnings,
+  `next` moves past polish, and QA records `warn` rows, so the verdict is at
+  best `ready_with_exceptions`. A campaign built from a starter template with
+  no design can now reach a toolkit test order locally. Hosted preview and
+  production packets, other checks, `record polish` and the waiver commands
+  are unchanged. `docs/qa-and-test-orders.md` lists the carried-forward
+  checks.
+- An all-template-stock packet's page-load checkpoint now reports
+  `polish.hidden_eager_media.no_capturable_routes` instead of the
+  malformed-authority `capture_malformed`, and `polish capture` says why it
+  has nothing to capture. It still blocks off the local preview, with one
+  action: map a page to its design source, or prove on the local preview.
+
+## [1.47.0+agent.11] - 2026-10-01
+
+### Changed
+
+- `doctor`'s `page_kit.sdk_version.spec_missing` now names the SDK the
+  selected certified template family was last verified against (for
+  example `The "apollo" template family was last verified against
+  0.4.40.`), so the CampaignSpec pin is not chosen by searching docs. The
+  bundled SDK support policy's `latest_known_release` moves from 0.4.38 to
+  0.4.40, which the catalog's verification records already named.
+- `source_html.prep.document_wrapper` names the two ways to record a
+  standalone page as whole: `--wrapper-policy preserve_document_wrappers`
+  on `start` or `prepare-build`, or `wrapper_policy` in the source-html
+  manifest.
+- `source_html.pages.source_hash` now says the hash it compares is the one
+  intake recorded in the Build Packet, that re-running intake with
+  `--force` refreshes it (and clears recorded stage evidence), and that
+  editing the manifest alone does not. It no longer points at a producer
+  script. `docs/build-packet.md` says the same, and that a revision made
+  after build belongs under `src/<route>/`.
+
+## [1.47.0+agent.10] - 2026-10-01
+
+### Fixed
+
+- A test order the platform refuses as a duplicate now says so. The order
+  API puts the reason in `payment_details`, which QA's response capture
+  dropped, so the `browser-test-order` row read only
+  `order create rejected: HTTP 400`. The capture now keeps a string
+  `payment_details` on an error response, and a duplicate-order refusal adds `duplicate_order`
+  with the remedy: re-run with a different `--test-email-prefix` (or
+  `--test-email`), or wait up to 30 minutes. `docs/qa-and-test-orders.md`
+  explains what the platform matches on and why concurrent runs collide.
+
+## [1.47.0+agent.9] - 2026-10-01
+
+### Changed
+
+- The agent context `install-agent-context` writes (`agents/claude/CLAUDE.md`,
+  `agents/codex/AGENTS.md`, `agents/copilot/copilot-instructions.md`,
+  `agents/cursor/campaigns-os.mdc`) now tells a session picking up an
+  existing campaign to run `readback` and `next` before reading artifacts by
+  hand. It also says the committed `.campaign-runtime/qa-verdict.json` keeps
+  no order records or URLs, so its `browser-test-order:<path>` assertions are
+  the typed-card proof. A resumed session had read the sidecar's empty
+  `test_orders` as "no test orders" after five verified orders.
+- The `campaign-run-evidence` skill says the same: the sidecar always
+  empties `test_orders` and the URL fields, so an empty `test_orders` there
+  says nothing about ordering. Bundled skills carry revision
+  `1.47.0+skills.3`, with each skill version advanced two patches from
+  `1.47.0+skills.1`.
+
+### Fixed
+
+- `readback` shows `warn` and `manual_review` assertions as the verdict
+  statuses they are, with their severity, recorded `actual` and evidence
+  problems (as it does for `fail` rows), instead of counting them as
+  "unrecognized status".
+
+## [1.47.0+agent.8] - 2026-10-01
+
+### Fixed
+
+- `qa run` no longer fails `pricing.checkout_price_visible` on a checkout
+  whose cart is filled on an earlier page. When QA opens such a checkout
+  directly, the SDK cart is empty and the page has no package selection of its
+  own, so no price can show. The row is now `skipped` with that reason and
+  records `cart_count` and `checkout_selection_surface`. The test order
+  already enters that cart from the landing page. A checkout with its own
+  package selection, or a filled cart, still fails when no price shows.
+- The page-binding check recognises `campaign-cart@<tag>/dist/loader.js`, the
+  SDK loader the starter templates use, and no longer tries to fetch it as a
+  cross-origin config script. Starter-template pages now report
+  `dynamic_unresolved` instead of `script_unavailable_or_limit`; they still
+  need manual review, because the static reader cannot prove a binding on a
+  page that runs other scripts.
+
+## [1.47.0+agent.7] - 2026-10-01
+
+### Removed
+
+- `doctor` no longer scans built pages for proof and urgency copy. The
+  `content_residue.anti_pattern` warning (review counts, "Verified Purchase"
+  labels, stock and sell-out lines, expert and press mentions) is gone, and so
+  is `content_residue.urgency_unattested`, which asked a campaign without a
+  brief payload to confirm its countdown was real. That copy belongs to the
+  merchant, and agents read the warnings as a reason to strip it from the
+  merchant's own designs. Template demo residue, the needs-merchant-input
+  marker, the discount-claim warnings and the brief-backed urgency and proof
+  attestation gates are unchanged.
+
+### Changed
+
+- The `next-campaigns-build` and `next-campaigns-polish` skills now say to
+  reproduce the source design's own proof and urgency elements (reviews,
+  "Verified Purchase" labels, recent-purchase popups, stock counters,
+  countdowns, guarantees) as designed, and not to record them as polish
+  issues. `docs/campaign-build-brief.md` says the same. Bundled skills carry
+  revision `1.47.0+skills.2`, with each skill version advanced one patch.
+
+## [1.47.0+agent.6] - 2026-10-01
+
+### Changed
+
+- The usage lines for `start`, `prepare-build` and `build` now list
+  `--deploy-target <target>`, `--preview-url <url>` and
+  `--production-url <url>`. Intake has always written them to the Build
+  Packet's `deploy` block (`deploy.target` defaults to `unknown`), and
+  `docs/build-packet.md`, the README and the Start page already pass
+  `--deploy-target local-serve` to `start`, but the help text left them out,
+  so an agent checking that command against the help read it as
+  unsupported. Behaviour is unchanged.
+
+## [1.47.0+agent.1] - 2026-10-01
+
+### Fixed
+
+- The one-line setup command in `docs/local-setup.md` now starts with
+  `npm init -y`. Without a `package.json` in the campaign folder, npm installs
+  into the nearest parent folder that has a `package.json` or `node_modules`,
+  so a campaign folder created inside another project added page-kit and the
+  toolkit to that project instead of the campaign. The README and quickstart
+  installs already started with `npm init -y`; a test now holds all three to
+  it.
+
+## [1.47.0] - 2026-10-01
+
+### Changed
+
+- `contracts/effects.v1.json`: the `--force` notes on `start`,
+  `prepare-build` and `build` now say that `--force` also regenerates a stale
+  Design Source Package that the intake synthesized itself (#506). That holds
+  when the previous Assembly Report records origin `"synthesized"` and the
+  package bytes still match it. An adopted or hand-edited package is never
+  replaced. The declared writes already covered this path, so behaviour is
+  unchanged; only the notes were incomplete.
+- `compatibility.json` names the package version again. It still said 1.34.0
+  (#486). A unit test now fails when it differs from `package.json`.
+- Bundled skills carry revision `1.47.0+skills.1`, with each skill version
+  advanced one patch, and the local setup install command pins the 1.47.0
+  package. The skill text is unchanged.
+
+## [1.46.0+agent.11] - 2026-10-01
+
+### Changed
+
+- `doctor`'s `built_output.script_syntax` gate groups missing-script warnings
+  by the URL the browser resolves, not the raw src. Two spellings of one URL,
+  such as `check&#9;out.js` and `checkout.js`, now give one
+  `built_output.script_syntax.missing_script` warning instead of two. One src
+  that names different files on pages in different folders still gives one
+  warning per file.
+- A `<script>` the page ends inside, with no `</script>`, is no longer parsed
+  by doctor or QA: the browser never runs a script element whose end tag never
+  arrives, so it can no longer block either. Doctor warns about it under the
+  new `built_output.script_syntax.unclosed_script` code, one warning per page,
+  because the page output is probably truncated.
+- A script symlink under `_site` is read by following the link only while its
+  real path stays inside the site root. A link whose target is outside the
+  site root is not read. Doctor warns under the new
+  `built_output.script_syntax.symlink_outside_site` code, naming the link, and
+  does not block. The gate lists such links in `scripts_outside_site[]`. The
+  rule is recorded in `docs/build-packet.md`.
+
+## [1.46.0+agent.10] - 2026-10-01
+
+### Fixed
+
+- `qa run --test-order` now follows a redirected order upsell mutation. When
+  the accept's POST to the order-upsells URL answered 307 or 308, the step
+  took the redirect hop as the mutation's response and judged the upsell
+  without the order body. It now waits for the redirect chain's final
+  response and judges from that body. A late body is matched to the step by
+  the request that started its redirect chain, so every hop of one redirected
+  POST counts as the step's request and a body from another request still
+  never does. A redirect whose chain has no final response is reported as no
+  mutation response, not as answered.
+
+## [1.46.0+agent.9] - 2026-10-01
+
+### Fixed
+
+- `qa run` analytics parity no longer blocks on `purchase-present` when the
+  operator did not pass `--analytics-candidate`. The automatic candidate (the
+  campaign root, or the first built entry) is not a receipt page, so a Purchase
+  cannot fire there. When that candidate fires no Purchase, `purchase-present`
+  is now `MANUAL_REVIEW`/`WARN`, and `evidence.page_mismatch` gives the reason
+  (`receipt_baseline_non_receipt_candidate` or `candidate_not_receipt`), the
+  candidate's source and its page type. An explicit `--analytics-candidate`,
+  or a built entry whose topology page type is a receipt, still blocks on a
+  missing Purchase. To compare Purchase, pass the candidate receipt with
+  `--analytics-candidate`.
+
+## [1.46.0+agent.8] - 2026-10-01
+
+### Fixed
+
+- The local setup command in `docs/local-setup.md` installed both the toolkit
+  and `next-campaign-page-kit` with `--save-dev`. In an existing page-kit
+  project that moved page-kit from `dependencies` to `devDependencies`, so
+  builds that run `npm ci --omit=dev` or set `NODE_ENV=production` no longer
+  installed it. The command now installs page-kit with `--save-exact` only and
+  the toolkit with `--save-dev --save-exact`, so a project that declares
+  page-kit under `dependencies` keeps it there. The README and quickstart
+  page-kit installs also pin exactly.
+- `tooling setup` now warns when the project declares page-kit only in
+  `devDependencies`, and prints the command that moves it back. The warning
+  appears in the text output and in a new `warnings` array in the `--json`
+  result; setup still proceeds.
+
+## [1.46.0+agent.7] - 2026-10-01
+
+### Changed
+
+- The vendored starter-template catalog is re-synced to
+  campaign-cart-starter-templates `3793b1d` (was `11352c3`). That brings in the
+  runtime-gated payment logos, the composable upsell pages, the `is_upsell`
+  opt-out on every bump include, and template verification evidence for
+  Campaign Cart SDK 0.4.40. Family certification freshness now reads 0.4.40 as
+  the verified SDK. The SDK support policy (minimum and preferred versions) is
+  unchanged.
+- `fixtures/certified-families` is regenerated at the new pin, and the shared
+  commerce brand contract's payment-chrome `asset_pin` moves with it. The
+  shipped asset bytes are unchanged. The payment-chrome repair text now says
+  to set `payment_flags.show_<method>: false` in the page frontmatter when a
+  logo from the starter `payment-logos.html` row is flagged, instead of
+  deleting markup. `upsell-payment-logos.svg` stays listed because the
+  starter still renders it ungated under `payment_flags.style: flat` and on
+  one select page.
+
+## [1.46.0+agent.6] - 2026-10-01
+
+### Fixed
+
+- `sdk storage-check` accepts a Campaign Cart release manifest whose SDK
+  version is above its supported range. Released manifests stamp their own
+  release version but declare an earlier supported range (v0.4.40 declares
+  0.4.38 only), and the check refused every one of them with "Manifest
+  source SDK version must equal supported maximum". The target SDK is still
+  judged against the declared range, so a target outside it reports unknown
+  (`target-outside-manifest-range`). A manifest whose SDK version is below its
+  supported maximum is still refused, because it cannot vouch for later
+  releases. The report keeps recording the manifest's SDK version and range
+  separately.
+
+## [1.46.0+agent.5] - 2026-10-01
+
+### Removed
+
+- `doctor` no longer warns with `built_output.sdk_markup.checkout_bump_is_upsell`
+  (added in `1.45.0+agent.5`). When a shopper selects an order bump on a
+  checkout page, it is added as a line item on the checkout order. With
+  `data-next-is-upsell="true"` that line is tagged as an upsell, so platform
+  order reports show upsell items apart from the core items. That tagging is
+  the intended default. The warning fired on every canonical starter checkout
+  with a bump and told the user to remove the attribute, which would report
+  the bump as a core item. Leave the attribute in place. A campaign that
+  should not tag a bump as an upsell opts out by passing `is_upsell: false` to
+  the bump include. Doctor reports no finding for the attribute either way.
+
+## [1.46.0+agent.4] - 2026-10-01
+
+### Changed
+
+- The `next-campaigns-qa` and `next-campaigns-build` skills now say which
+  checkout controls count as bound for `browser-commerce-structure`: 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, and QA reports it in `fields_bound.missing`. This is the rule QA
+  has applied since #540; the skills had not stated it. Bundled skills carry
+  revision `1.46.0+skills.2`, with each skill version advanced one patch. No
+  change to the CLI.
+
 ## [1.46.0+agent.3] - 2026-09-30
 
 ### Changed
@@ -135,9 +477,11 @@ Notable supported-surface changes are recorded here.
   downsell and receipt pages, and bumps without the flag, get no warning. The
   flag comes from the bump include's markup, and several starter bump includes
   write it unconditionally, so a canonical starter checkout with a bump shows
-  this warning. To clear it, remove `data-next-is-upsell="true"` from the bump
-  include in the campaign, unless the line really should be billed as an
-  upsell. It is a warning, not a blocker.
+  this warning. It was a warning, not a blocker. Its advice to remove
+  `data-next-is-upsell="true"` was wrong: tagging a checkout bump line as an
+  upsell is the intended default, so order reports show upsell items apart
+  from core items, and removing the attribute would report the bump as a core
+  item. The warning is retired in `1.46.0+agent.5`.
 
 ### Fixed
 

package/README.md

@@ -11,8 +11,8 @@ This toolkit gives campaign developers and AI coding tools a clear path for asse
 5. Provide or generate a [Campaign Build Brief](./docs/campaign-build-brief.md) for merchandising/design presentation decisions.
 6. Create and doctor a Build Packet.
 7. Hand off to `next-campaigns-build`.
-8. Run build/lint, then install the Campaigns OS Playwright browser once with `campaigns-os qa install-browser`.
-9. Run `next-campaigns-polish`, serve the current build, and run the mandatory `campaigns-os polish capture` producer before marking Polish complete.
+8. Run build/lint and record the build with `campaigns-os record build`, then install the Campaigns OS Playwright browser once with `campaigns-os qa install-browser`.
+9. Run `next-campaigns-polish`, serve the current build, run the mandatory `campaigns-os polish capture` producer, then record Polish with `campaigns-os record polish --evidence <file>`.
 10. Deploy a preview.
 11. Run `next-campaigns-qa` against the tested URL.
 12. Record launch blockers and follow-up work.
@@ -45,7 +45,7 @@ steps, in this order:
 
 ```bash
 mkdir "<route>" && cd "<route>"
-npm init -y && npm i next-campaign-page-kit
+npm init -y && npm i --save-exact next-campaign-page-kit
 npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"
 npm install --save-dev --save-exact @nextcommerce/campaigns-os@<version>
 npx --no-install campaigns-os tooling status --platform claude
@@ -53,6 +53,15 @@ npx --no-install campaigns-os install-skills --platform claude
 mkdir -p source
 ```
 
+With Claude Code, [local setup](docs/local-setup.md) replaces the last two
+lines with one: `npx --no-install campaigns-os tooling setup --target .
+--platform claude` installs the QA browser, the skills and the project
+context, and keeps existing pages and instructions. It does not scaffold
+pages; the agent chooses the template at intake. Codex, Cursor and other
+agents keep the separate steps: `install-skills --platform codex` (or
+`--platform agents`), `install-agent-context --target .` and
+`qa install-browser`.
+
 The toolkit is also published to npm as `@nextcommerce/campaigns-os`, so the
 CLI can be installed once, globally, instead of pinned per campaign:
 
@@ -126,7 +135,10 @@ npx --no-install campaigns-os next --packet ./campaign-runtime.build.json --json
 `--proxy-base <origin>` when the map was saved on a non-production map store);
 `--spec <campaignspec.json>` starts from a local export or an agent-authored
 [local spec](docs/build-packet.md#local-spec-entry) instead. Local-spec identity
-requires a reviewed 1.43.0-or-later release. `--source` is
+requires a reviewed 1.43.0-or-later release. To prove the campaign on
+localhost before a preview deploy, add `--deploy-target local-serve` (and
+`--preview-url http://localhost:<port>/`); `qa policy set --deploy-target <target>`
+changes it later. `--source` is
 always required: the folder of prepared HTML/CSS/assets for the pages you are
 building, with a source manifest that carries desktop and mobile screenshot
 proof for each designed page
@@ -267,21 +279,28 @@ Before an SDK bump, scan explicitly scoped tracked merchant HTML/JS with [SDK st
 
 ```bash
 npm run campaigns-os -- tooling status
+npm run campaigns-os -- tooling setup --target <page-kit-repo> --platform claude --dry-run --json
 npm run campaigns-os -- install-skills --dry-run
 npm run campaigns-os -- install-skills --platform codex --dry-run
+npm run campaigns-os -- install-agent-context --target <page-kit-repo> --dry-run
 npm run campaigns-os -- qa install-browser
 npm run skills -- status
 npm run campaigns-os -- prepare-build --spec <spec.json> --source <html-dir> --target <page-kit-repo> --template-family <family> --brief <campaign-build-brief.yaml>
 npm run campaigns-os -- doctor --packet <page-kit-repo>/campaign-runtime.build.json
+npm run campaigns-os -- page-kit sync --packet <page-kit-repo>/campaign-runtime.build.json --dry-run
+npm run campaigns-os -- checkpoint waive --packet <packet.json> --gate source_html.producer_provenance --page <page_id> --reason "<why>" --waived-by "<named human>" --review-condition "<trigger>" --dry-run
 npm run campaigns-os -- sdk storage-check --target <campaign-git-root> --target-sdk 0.4.38 --manifest <sdk-storage-manifest.json> --scope <campaign,shared> --json
 npm run campaigns-os -- standardize --target <page-kit-repo-or-cpk-repo> --json
 npm run campaigns-os -- theme inspect --packet <page-kit-repo>/campaign-runtime.build.json --json
 npm run campaigns-os -- theme generate --packet <page-kit-repo>/campaign-runtime.build.json --json
 npm run campaigns-os -- next setup --packet <page-kit-repo>/campaign-runtime.build.json
 npm run campaigns-os -- next build --packet <page-kit-repo>/campaign-runtime.build.json
+npm run campaigns-os -- record setup --packet <page-kit-repo>/campaign-runtime.build.json
+npm run campaigns-os -- record build --packet <page-kit-repo>/campaign-runtime.build.json
 npm run qa:install-browser
 npm run campaigns-os -- next polish --packet <packet.json> --report <assembly-report.json>
 npm run campaigns-os -- polish capture --packet <packet.json> --base-url <served-current-build-url>
+npm run campaigns-os -- record polish --packet <packet.json> --evidence <polish-evidence.json>
 npm run campaigns-os -- next qa --packet <packet.json> --report <assembly-report.json>
 npm run campaigns-os -- qa resolve --packet <packet.json>
 npm run campaigns-os -- qa run --packet <packet.json> --base-url <preview-url> --browser --test-order common
@@ -298,6 +317,14 @@ only when deliberately recording a new doctor stage. `--no-write` overrides
 `--write`. A custom `--doctor-out <path>` also requires `--write`; naming an
 output path alone does not create or refresh the file. Build/QA producer
 commands continue to record their own stages.
+
+Record a stage's completion with `record setup`, `record build` (after every
+rebuild) and `record polish --evidence <file>` rather than hand-editing
+`.campaign-runtime/build-context.json` or `.campaign-runtime/assembly-report.json`.
+Each validates what it would write, refuses a stage `next` has not reached, and
+writes nothing on failure; `--dry-run` runs the checks without writing. See
+[Build Packet](docs/build-packet.md) and [Polish evidence](docs/polish-evidence.md).
+
 Do not use `prepare-build --force` merely to refresh a catalog path: doctor
 already resolves the running toolkit's catalog, and force clears stage evidence.
 

package/agents/claude/CLAUDE.md

@@ -6,6 +6,8 @@ Packet exists, read it and follow `next`. Check the loaded skill's bundle
 revision and restart the session if it differs from the
 project copy. Do not use private runtime source as the campaign's starting point.
 
+To pick up an existing campaign, run `campaigns-os readback .` and `campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
+
 Core rules:
 
 - Treat CampaignSpec as campaign intent and the Campaigns API as live commerce truth.

package/agents/codex/AGENTS.md

@@ -3,6 +3,7 @@
 Use this context when working in a target campaign repo with Campaigns OS artifacts.
 
 - Read `campaign-runtime.build.json` first.
+- To pick up an existing campaign, run `campaigns-os readback .` and `campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - If `.campaign-runtime/build-context.json` or `.campaign-runtime/assembly-report.json` exists, read them before editing campaign files.
 - Run `campaigns-os doctor --packet campaign-runtime.build.json` before build work.
 - Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.

package/agents/copilot/copilot-instructions.md

@@ -5,6 +5,7 @@ When this repository contains Campaigns OS artifacts, use them as the build hand
 - `campaign-runtime.build.json` defines the CampaignSpec, source adapter, target output, template family, deploy target, SDK origin state, and QA proof depth.
 - `.campaign-runtime/build-context.json` records page mappings and setup/build handoff details.
 - `.campaign-runtime/assembly-report.json` records stage evidence and blockers.
+- To pick up an existing campaign, run `campaigns-os readback .` and `campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`.
 - `.campaign-runtime/theme/theme-report.json`, when present, is optional brand-theme evidence. Generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
 
 CampaignSpec validation is owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.

package/agents/cursor/campaigns-os.mdc

@@ -6,7 +6,7 @@ globs:
 alwaysApply: false
 ---
 
-Read Campaigns OS artifacts before editing campaign pages. Treat CampaignSpec/API values as live commerce truth, starter-template contracts as SDK surface truth, and designed HTML/assets as visual/content intent. Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available. If `context.theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence; generated `brand-theme.css` must load after `next-core.css`, and missing/low-confidence theme is a warning or skipped reason, not permission to edit SDK-owned runtime surfaces.
+Read Campaigns OS artifacts before editing campaign pages. To pick up an existing campaign, run `campaigns-os readback .` and `campaigns-os next --packet campaign-runtime.build.json` before reading artifacts by hand; `next` blocks polish and QA again whenever the built output changes. The committed `.campaign-runtime/qa-verdict.json` keeps no order records or URLs: its `browser-test-order:<path>` assertions are the typed-card proof, and the full verdict is under `qa-output/`. Treat CampaignSpec/API values as live commerce truth, starter-template contracts as SDK surface truth, and designed HTML/assets as visual/content intent. Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available. If `context.theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence; generated `brand-theme.css` must load after `next-core.css`, and missing/low-confidence theme is a warning or skipped reason, not permission to edit SDK-owned runtime surfaces.
 
 Do not carry over demo package, shipping, voucher, payment, tracking, footer, or SEO values. Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes. Preserve prepared landing/presell source HTML when it is a real standalone design. For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references while campaign/source owns visual chrome. Copy starter template families atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages. Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`. Preserve SDK-owned checkout/cart/upsell/receipt surfaces. For `shop-three-step`, shipping is dynamic via `window.next.getShippingMethods()`.
 

package/compatibility.json

@@ -1,6 +1,6 @@
 {
   "package": "@nextcommerce/campaigns-os",
-  "version": "1.34.0",
+  "version": "1.48.0",
   "status": "developer-preview",
   "contracts": {
     "campaign_spec": "4.2-4.3",