@nextcommerce/campaigns-os 1.48.0 → 1.52.0

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.48.0",
+  "surface_version": "1.52.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -66,7 +66,7 @@
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "47c2899f409ed5927cf410bddd63e7bb8a9d154eabf7a07455777aed118212e9"
+      "sha256": "5002529c5979c4d8fef7e298de82ebdf625ffbd11f5284ba684d96d173788d62"
     },
     "schemas/campaign-spec.v4.schema.json": {
       "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
@@ -84,7 +84,7 @@
       "sha256": "3c40fd79f218d1b95f0424f9a2b67db140a306329e2ca02793e2740d3afded59"
     },
     "schemas/campaigns-os-qa-verdict.v0.schema.json": {
-      "sha256": "ec4514e81a791a63bc0b358d7977aa823f3c5524e0f5caaba2712e66f262e18a"
+      "sha256": "8c689d29850b2b894c17438ee4411363033bae6f805820af53b7a04a5693d0e0"
     },
     "schemas/campaigns-os-doctor-output.v0.schema.json": {
       "sha256": "87866e619d2a18f01a208a1682cb14a2079f61df51c642f4e1902b6e6bce0ce5"
@@ -120,7 +120,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "5f8c6f2f88fc9e0c11c09e265640071d3c1d81fd96c6e05283ed5cfed21d1d59"
+      "sha256": "f49ac6dcbf441c90b12b51be9bc07805f6228f4143784045c5925e3c155a6181"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"

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

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "37a8d945db4c360739ded98348814cfd632da94f",
+        "sha": "2c618942391ae398fb4812f36fc93e6632054874",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },
@@ -75,7 +75,7 @@
     ],
     "placeholder_text_residue": {
       "page_types": ["checkout", "select", "upsell", "downsell", "receipt", "presell", "landing"],
-      "terms": ["Lorem", "lorem ipsum", "Placeholder", "TODO", "Product Name"],
+      "terms": ["Lorem", "lorem ipsum", "Placeholder", "TODO", "Product Name", "Benefit one", "Benefit two", "Benefit three", "Benefit four"],
       "rule": "Rendered campaign output must not contain literal template placeholder copy. Every term is replaced from the CampaignSpec/design before QA; QA fails (blocker) on any match in visible page text, regardless of any theme-gate waiver. Matched on word boundaries, case-insensitive. Scope is governed by page_types: the blocker applies only to the listed campaign funnel page types (generic, non-funnel pages whose type is not listed are not checked). Narrow page_types to exempt a page type where placeholder copy is acceptable."
     },
     "computed_style_checks": [

package/contracts/template-slot-manifest.shared-content-core.v0.json

@@ -1394,6 +1394,14 @@
               },
               "demo_value": "Our formula works with your body's own sleep systems \u2014 not against them. Our synergistic blend lower"
             },
+            {
+              "key": "benefits_2_section_id",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Section anchor id, the target of the header nav's in-page link. Template-owned, assembly never touches it: the nav href and this id must stay paired.",
+              "source_policy": "template_static"
+            },
             {
               "key": "benefits_2_section_heading",
               "kind": "copy",
@@ -1709,6 +1717,14 @@
               },
               "demo_value": "The compounding effect reaches its peak. Consistent deep sleep every night, sustained daytime energy"
             },
+            {
+              "key": "ingredients_3_section_id",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Section anchor id, the target of the header nav's in-page link. Template-owned, assembly never touches it: the nav href and this id must stay paired.",
+              "source_policy": "template_static"
+            },
             {
               "key": "ingredients_3_heading",
               "kind": "copy",
@@ -2531,6 +2547,14 @@
               "proof_modality": "review",
               "needs_merchant_input_able": true
             },
+            {
+              "key": "reviews_3_section_id",
+              "kind": "meta",
+              "role": "page_meta",
+              "owner": "template",
+              "description": "Section anchor id, the target of the header nav's in-page link. Template-owned, assembly never touches it: the nav href and this id must stay paired.",
+              "source_policy": "template_static"
+            },
             {
               "key": "reviews_3_badge_text",
               "kind": "copy",

package/docs/brand-theme-bridge.md

@@ -151,8 +151,9 @@ When `theme inspect` reports `can_generate: true` and the campaign ships
 commerce pages (checkout/upsell/downsell/receipt), the gate **blocks**
 `next polish`, `next deploy`, `next qa`, and `qa run` until one of:
 
-- the brand layer is generated and recorded as applied
-  (`report.theme.status: applied`, `load_order: after-next-core`), or
+- the brand layer is generated, linked and recorded as applied with
+  `campaigns-os record theme --packet <p>` (`report.theme.status: applied`,
+  `load_order: after-next-core`), or
 - an explicit waiver is recorded:
   `campaigns-os theme waive --packet <p> --reason "<why>" --waived-by "<named human>"`
   (optionally `--expires-at <ISO>`; placeholders such as "operator" are refused), or
@@ -197,8 +198,12 @@ If a fresh `brand-theme.css` exists:
 3. Preserve SDK-owned runtime surfaces: `data-next-*`, package selectors,
    payment fields, totals, submit controls, receipt templates, route meta tags,
    and SDK JavaScript.
-4. Record `report.theme.status`, `css_path`, `commerce_pages`, `load_order`,
-   and evidence.
+4. Rebuild, run `campaigns-os record build --packet <p>`, then
+   `campaigns-os record theme --packet <p>`. It reads each built commerce
+   page's stylesheet links and records `report.theme.status`, `css_path`,
+   `commerce_pages`, `load_order` and evidence. It refuses, writing nothing,
+   when a page that loads `next-core.css` does not load the brand layer after
+   it, or when no built commerce page loads `next-core.css`.
 
 ### Where next-core.css belongs
 
@@ -212,8 +217,9 @@ stylesheets off those pages and list them only in the frontmatter styles of
 the pages that render family components, often just checkout.
 
 `report.theme.commerce_pages` is the list of pages where the brand layer was
-applied, recorded by the build. Record the pages you actually scoped, for
-example `commerce_pages: ["checkout"]`. The theme gate does not compare this
+applied. `record theme` writes it from the built pages: every commerce page
+that loads `next-core.css`, for example `commerce_pages: ["checkout"]`. A page
+that loads neither stylesheet is left out and noted in the evidence. The theme gate does not compare this
 list with the funnel. It passes on `report.theme.status: applied` with
 `load_order: after-next-core`. The gate's own `commerce_pages` output is a
 different field: every checkout, upsell, downsell, receipt or thank-you page

package/docs/build-packet.md

@@ -22,8 +22,9 @@ ordinary CampaignSpec from the brief, source design and configured campaign's
 real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
 operator supplies the selected store/campaign, public Campaigns API key, intended
 pages and commercial choices, plus store contact details and policy URLs. Verify
-the store/campaign binding and package/offer references; do not guess commerce
-values. No gateway or Map provisioning is required for this entry.
+the store/campaign binding, and read the package, offer and shipping references
+from the campaign itself (below); do not guess commerce values. No gateway or
+Map provisioning is required for this entry.
 
 Set `spec_identity.local_spec_id` to a new UUID once, commit it with the spec,
 and keep it unchanged through revisions and fresh checkouts. It accepts 1–64
@@ -45,7 +46,9 @@ npx --no-install campaigns-os next --packet campaign-runtime.build.json
 The packet and report retain `map_id: null` and carry `local_spec_id`. Doctor,
 report writes, polish capture, progress, run closeout and QA compare that local
 identity. Material spec hashes still bind the current revision; a changed ID or
-content cannot reuse earlier proof. After a material revision, follow `next` to
+content cannot reuse earlier proof. After a material revision, doctor and
+`next` warn `spec.material_stale` (the spec no longer has the material hash
+prepare-build bound on the Assembly Report, which QA refuses); follow `next` to
 refresh preparation and affected evidence. Keep the spec, source, dependency
 pins and canonical sidecars in Git. Use `readback` and `next` after a fresh
 checkout; identity survives the move, but proof freshness is assessed again.
@@ -65,6 +68,56 @@ not relax template certification, source proof, store/SDK parity, polish,
 commerce checks, or typed-card checkout proof. Resolve their reported gates;
 localhost readiness is not production approval.
 
+### Reading package, offer and shipping refs
+
+No command writes commerce refs into a local spec, and `login` does not read
+them: a gateway login serves only the Store Profile fields that `spec derive
+--from-store` fills. Read them with the campaign's public Campaigns API key,
+through the request doctor and QA already make to check built pages against
+the live campaign: one GET of NEXT's proxy with the key in the
+`X-Campaign-Key` header. No store or Admin credential is involved.
+
+```sh
+CAMPAIGN_KEY='<public key>' node -e '
+fetch("https://campaign-map.nextcommerce.com/api/campaign", {
+  headers: { Accept: "application/json", "X-Campaign-Key": process.env.CAMPAIGN_KEY },
+}).then(async (res) => console.log(res.status, JSON.stringify(await res.json(), null, 2)));
+'
+```
+
+`curl -sS -H "Accept: application/json" -H "X-Campaign-Key: <public key>" https://campaign-map.nextcommerce.com/api/campaign`
+returns the same. Add `?ref_id=<campaign id>` when one key serves several
+campaigns. Other HTTP clients work with the same header, but the proxy refuses
+some default user agents, Python `urllib`'s and Perl `libwww-perl`'s among
+them, with a 403 whose body is `error code: 1010`; send another `User-Agent`
+or use one of the commands above.
+
+The answer is an envelope, `{ ok, status, endpoint, requested_ref_id,
+retrieved_at, data }`, with `requested_ref_id` present only when `?ref_id=`
+was sent; `ok: false` carries an `error` instead of a campaign. `data` is the
+campaign retrieve body the Campaign Cart SDK reads in the browser: one
+campaign, or an array of them, in which case use the entry whose `id` is the
+selected campaign. Copy from it as follows:
+
+| `data` field | CampaignSpec field |
+|---|---|
+| `id` | `campaign.ref_id` (doctor and QA send it as `?ref_id=`) |
+| `name`, `currency`, `language`, `payment_env_key` | the `campaign` fields of the same name |
+| `packages[]`: `ref_id`, `name`, `qty`, `price`, `price_retail`, `image`, the `product_*` fields and the recurring fields (`is_recurring`, `price_recurring`, `interval`, `interval_count`) | one `funnels[].pages[].packages[]` entry for each package the page sells |
+| `offers[]`: `ref_id`, `name`, `type`, `code`, `condition`, `benefit`, `packages[]` (by `package_id`), `shipping_methods[]` | root `offers[]`, copied whole; a page that presents an offer lists it in `funnels[].pages[].offers[]` by `ref_id` |
+| `shipping_methods[]`: `ref_id`, `code`, `price` | root `shipping_methods[]` |
+
+A package's ref is its `ref_id`, numbered within the campaign. `external_id`,
+`product_id` and `product_variant_id` are catalog ids, never package refs. The
+same `ref_id` values are what pages render in `data-next-package-id` and
+`data-next-shipping-id`. The read supplies refs and the values the campaign
+serves, not the selection: which packages and offers each page carries, and
+the role flags `is_upsell`, `is_order_bump` and `default_selected`, come from
+the brief and the operator. Copy prices and availability from the read rather
+than typing them from the brief. After the build, doctor and QA repeat this
+read and block a page ref the live campaign does not serve (see
+[the live campaign read](effects.md#the-live-campaign-read)).
+
 ## Root-Served Campaigns (`campaign.route_root`)
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
@@ -732,7 +785,14 @@ intended) when:
   (`…attribution_drift`).
 
 One error per finding; each names the two files and the two values, so the
-repair is a one-line edit. Pages whose route contains a `-backup-` or `-old-`
+repair is a one-line edit. Every built HTML file under `_site/<slug>/` is
+scanned, because every one is served. When doctor has the CampaignSpec, a
+finding that names a file no active spec page builds to says so and lists it
+under `stray_files`. Such a file is leftover output (page-kit does not prune
+`_site/`) or an HTML file copied into the source, such as a design export's
+`index.html` under `assets/`. The repair is to remove the source file if
+there is one, delete the built file, and rebuild and record the build again,
+not to retag it. Pages whose route contains a `-backup-` or `-old-`
 segment are parked copies: skipped and listed on the gate as `pages_skipped`,
 never scanned. Presence is not asserted: a campaign whose pages carry no key
 at all, or no `setAttribution` anywhere, passes on the funnel tag alone.
@@ -893,6 +953,24 @@ canonical rendered output of every certified starter family
 it reads for credential declarations (`script-parse:<page_id>`; see
 [QA and test orders](qa-and-test-orders.md)).
 
+### Built-output cart placeholder check (`built_output.cart_placeholders`)
+
+**Raw cart placeholders (`built_output.cart_placeholders`).** Doctor warns when a known SDK placeholder, such as `{item.name}`, `{subtotal}` or `{package.name}`, appears in live built HTML text or in a text attribute (`alt`, `title`, `placeholder`, `aria-label`, button `value`), where it prints as raw text. Placeholders inside `<template>`, inside `data-next-cart-items`/`data-next-order-items` rows and their declared row templates, and SDK-substituted quantity text are expected. Brace strings that are not known SDK placeholders, including `{tax}`, are review results. The placeholder list is vendored from the SDK version pinned in `src/sdk-attribute-index.mjs`. Pages whose SDK loader does not name an exact version, or names a version the list was not verified against, are reported as unexercised rather than passing. These are warnings, never blockers.
+
+### Built-output smoke checks (`built_output.smoke_qc`)
+
+**Smoke checks (`built_output.smoke_qc`).** Doctor warns on built pages that have:
+
+- an in-page `#link` with no matching `id` or `name` on the same page;
+- no favicon link;
+- no `og:title`, `og:description` or `og:image`;
+- an `og:image` that is relative or points to a missing file;
+- the Tailwind CDN script in a production build;
+- references to the `cdn.29next.store` asset host in any attribute or `<style>` block (use `cdn.cachebucket.com`);
+- `localhost` or loopback URLs in a production build.
+
+Targets inside `<template>` or named in page scripts are review results, and pages whose scripts could not all be read are unexercised. Remote `og:image` URLs are not fetched by doctor. The Tailwind and loopback checks need a recorded production build: development builds (including local proof) and `doctor --built`, which cannot tell the environment, report them as unexercised. All are warnings, never blockers.
+
 > **Where does the source HTML come from?** See [docs/entry-points.md](./entry-points.md) for the five recognized entry points (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and how each populates `source_html.pages[]` + `design_source`.
 
 ## Artifact Locations
@@ -970,8 +1048,9 @@ starter palette is acceptable>" --waived-by "<named human>"`, optionally
 (status and severity — never `fail`) and keeps the shipped palette visible in
 the verdict; or hand-author the brand
 layer — write `brand-theme.css`, list it after `next-core.css` in commerce-page
-frontmatter styles, rebuild, and record `report.theme.status: applied` with
-`load_order: after-next-core`. Nothing waives the gate on the operator's
+frontmatter styles, rebuild, `record build`, and `record theme`, which records
+`report.theme.status: applied` with `load_order: after-next-core` from the
+built pages. Nothing waives the gate on the operator's
 behalf. See [Brand Theme Bridge](./brand-theme-bridge.md) for both lanes in
 full.
 
@@ -1237,7 +1316,9 @@ loopback host (`127.0.0.1`, `[::1]`) with a ready line naming the
 `http://localhost:<port>/` fallback, and warns (`deploy.local_serve_url`) when
 the recorded URL is neither.
 `next` at the deploy stage then hands off a serve-locally prompt and action
-instead of a ship-to-host one. The directory to serve is `_site/`; for a
+instead of a ship-to-host one, and the served URL is recorded with
+`campaigns-os record deploy --packet <p> --base-url <url>` (the record command
+table below). The directory to serve is `_site/`; for a
 root-served campaign (`campaign.route_root: "/"`) the handoff adds that pages
 are served at site-root paths while assets keep the `/<public_route_slug>/`
 prefix, so `_site/` needs the same rewrite of root-level page routes onto
@@ -1248,9 +1329,10 @@ URL.
 `local-serve` also selects **local proof mode** for the build stage: page-kit
 is built in the development environment (`CPK_ENV=development npx
 campaign-build --json > .campaign-runtime/page-kit-build-summary.json`) into
-`_site/`, and the build records `stages.assembly.evidence.build_environment:
+`_site/`, and `campaigns-os record build --packet <packet> --build-environment
+development` records `stages.assembly.evidence.build_environment:
 "development"` on the Assembly Report (a free-form stage field; no schema
-change). The starter templates gate every vendor loader on the environment,
+change; never hand-edited). The starter templates gate every vendor loader on the environment,
 and a production build's protocol-relative loaders (`//host/...`) fail over a
 plain-HTTP local serve, voiding polish capture unwaivably; the SDK's `dl_*`
 events still fire in development. Before commit, `campaigns-os page-kit parity
@@ -1607,12 +1689,17 @@ hand-editing `.campaign-runtime/` JSON:
 | Command | Writes | Refused (nothing written) when |
 |---|---|---|
 | `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
-| `campaigns-os record build --packet <p>` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record build --packet <p> [--build-environment <development\|production>]` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, `evidence.build_environment` = the `--build-environment` value when given (kept from the last record otherwise), and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
 | `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
+| `campaigns-os record theme --packet <p>` | `report.theme`: status `applied`, `load_order` `after-next-core`, `css_path`, `commerce_pages` and per-page evidence read from each built commerce page's stylesheet links; any earlier theme waiver is cleared | build is not recorded for the current output, the campaign ships no commerce pages, a built commerce page that loads `next-core.css` does not load `brand-theme.css` (or `checkout-brand.css`) after it or links one missing from the built output, or no built commerce page loads `next-core.css` |
+| `campaigns-os record deploy --packet <p> --base-url <url>` | the packet's `deploy.preview_url` and `stages.deploy` completed with the URL in `outputs` and one evidence line per built page that answered (each page is requested under the URL first) | the packet is not `local-serve`, the URL is not a loopback origin naming the campaign's route root, a built page does not answer 2xx, polish is not recorded, the built output changed since build was recorded, or the theme gate is blocked |
 
 Each command also refuses a stage `next` has not reached: while doctor's
 prepare-build gate is set (`next` answers prepare-build) or while an earlier
-stage in the order below is not terminal.
+stage in the order below is not terminal. The exception is the one `next`
+makes: on the local preview, a polish doctor carries forward (never recorded
+for this build) does not hold `record deploy` back, as it does not hold `next`;
+polish stays owed and QA reports it.
 
 Each command reads the same packet, Build Context and Assembly Report `next`
 reads (`--context` / `--report` override them the same way), validates what it
@@ -1634,7 +1721,9 @@ whenever the report's campaign identity does not match the packet, including
 for packets with no Design Source Package. Every command also adds
 `recorded_by`, and `completed_at` unless it records a blocked Polish, to the
 stage it records. `--dry-run` runs every check, takes no lock and writes nothing. A failed
-check exits non-zero with the problems listed, one per line. Re-run `record
+check exits non-zero with the problems listed, one per line; a value outside a
+schema enum (for example an `adapter_decisions` policy) is listed with the
+values the schema allows and the value it got. Re-run `record
 build` after every page-kit build; a rebuild that changes the output needs
 `polish capture` and `record polish` again.
 

package/docs/campaign-build-brief.md

@@ -47,13 +47,37 @@ Guided questions are intentionally short and business-readable. They prioritize:
 2. Which palette/CTA style should commerce pages use?
 3. Which product variants/colors are actually sold?
 4. How should bundle pricing be presented?
-5. What promo/savings/urgency language is approved?
+5. Should the starter template's own promo placeholders (demo countdown timers, promo banners, placeholder voucher codes, exit-pop offers) be filled from the campaign's promo codes and offers, or removed?
 6. Which payment methods/trust badges may appear?
 7. Are runtime/catalog names allowed to override provided display names?
 8. Are there regulated claims or forbidden copy areas?
 
 The CLI avoids SDK/page-kit jargon in questions. The implementation can resolve SDK attributes, responsive CSS, asset paths, routing, template copying, and QA reruns. Business choices should come from the brief or be escalated.
 
+Question 5 is asked only when the CampaignSpec maps a surface that fills the template's promo placeholders: a `funnels[].promo_codes` roster, or a checkout page's enabled `exit_intent` or `promo_code_input`. It never asks for approval of the source design's own promo, proof or urgency copy, which is built as designed (see below). Without such a surface the guided draft sets `header_claim_source` and `timer_label` to `"none"`: the template's promo placeholders are removed.
+
+## Answering The Questions
+
+An answer counts only once it is in a brief file that `start` or `prepare-build` reads. The guided draft is regenerated on every run, so an answer given in conversation, or typed into the normalized draft, does not stick.
+
+1. Copy `.campaign-runtime/input/campaign-build-brief.normalized.json` to `campaign-build-brief.json` in the target repo. A brief file replaces the guided draft whole, so starting from the copy keeps the fields the draft already filled; any question the file leaves open blocks as a prepared brief.
+2. Set the fields that close each open question:
+
+   | Question | Fields |
+   |---|---|
+   | `page_design_authority` | `design_authority.<page_id>.source` for each page named in the question |
+   | `brand_palette_cta` | `brand.commerce_palette_source`, `brand.cta_style` |
+   | `variant_media_rules` | `media.sold_variants`, `media.allow_other_variant_colors` |
+   | `bundle_pricing_presentation` | `offer_presentation.bundle_cards.primary_price` |
+   | `promo_urgency_copy` | `promo_urgency.header_claim_source` (`campaign_offers` or `none`), `promo_urgency.timer_label` (the template timer's label, or `none`) |
+   | `payment_methods_trust` | `commerce_surfaces.payment_methods_allowed` |
+   | `canonical_display_names` | `canonical_display.product_name_source` |
+   | `regulated_claims` | one of `campaign_intent.compliance.approved_benefit_language`, `.forbidden_claims`, `.approved_claims`, `.copy_rules` |
+
+3. Re-run `start` or `prepare-build` with the same arguments. The file is found in the target repo automatically, or pass `--brief <file>`. Doctor's `build_brief.guided_questions` warning names the open questions and their fields.
+
+Re-running regenerates the Assembly Report. Before any stage has recorded evidence, that costs nothing. Once a stage has recorded evidence (setup, build, polish or later), the re-run is refused unless you pass `--force`, which resets those stages and clears their evidence. Answer the questions right after `start`.
+
 ## Risky Defaults
 
 Doctor blocks or asks when a prepared brief leaves high-impact questions unanswered, forbids alternate variant colors without naming sold variants, or contains direct contradictions such as the same payment method being both allowed and hidden.

package/docs/effects.md

@@ -123,6 +123,10 @@ and `build` (the intake alias for prepare-build + doctor), `theme waive`,
 sidecar refresh `qa run` makes after it records the QA stage (the verdict
 itself carries QA's own read).
 
+### `checkpoint accept`
+
+**Accepting a warning.** `campaigns-os checkpoint accept` records an operator's decision about a warning that a Campaigns OS check measured. It does not change readiness, does not remove the warning, does not change the status `next` reports, and cannot be used on review, unexercised, or excluded results. The warning must already be on record (in the doctor snapshot `next` writes, the Polish capture, or the full QA verdict) before it can be accepted. The accept is bound to the exact measured state and lapses when that state changes, or when its evidence is stale or cannot be reproduced. An optional expiry or review condition adds a second bound. Run it only with the operator's explicit decision, made after the warning was shown to them. A plausible name is not authorization. The command refuses placeholder and automation identities. Results are re-derived from the package's raw captures on every read, and a result whose capture is missing or does not match is listed as unexercised. These checks are tamper evidence, not proof of authorship: a hand-written record that copies every value and recomputes the checksum, or a hand-written result written together with a matching capture, is not detected.
+
 ## How to read a row
 
 ```jsonc
@@ -316,6 +320,8 @@ in for the destination — that the **declared destination is the one contacted*
 
 | Row | What the offline fixture cannot reach |
 | --- | --- |
+| `checkpoint accept` | An accept-eligible warning: no check this version ships produces one yet. Proved: the refused accept writes nothing — no report, no stale stamp, no journal entry — and contacts nothing. |
+| `checkpoint accept --dry-run` | An accept-eligible warning, as for `checkpoint accept`. Proved: the refused dry run writes nothing and contacts nothing. |
 | `login` | A reachable login gateway and a human at a browser. Proved: the failure path writes nothing at all — no credential, no journal entry. |
 | `logout` | A credential minted by a gateway login. Proved: the no-credential path writes nothing. |
 | `page-kit parity` | A `local-serve` deploy target and a page-kit renderer to build the two renders with. Proved: the refusal writes nothing but the journal entry. |

package/docs/local-setup.md

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

package/docs/orientation-contract-reference.md

@@ -26,7 +26,7 @@ Ledger schema id: `campaigns-os-release-ledger/v1`
 Change policy version: `1.0.0`  
 Reason-code vocabulary version: `1.0.0`  
 Limits version: `1.0.0`  
-Supported surface at generation time: `1.48.0`
+Supported surface at generation time: `1.52.0`
 
 ## Forward compatibility
 

package/docs/polish-evidence.md

@@ -109,6 +109,16 @@ Run it only after `npm run qa:install-browser` in an environment that permits a
 loopback HTTP listener and Chromium. It is deliberately opt-in and is not part
 of `npm run check` or CI.
 
+**Media weight and origin.** Polish capture records, for each captured route and viewport:
+
+- which resources came from the page's own origin after redirects, with the redirect chain;
+- their measured transfer bytes, which include response headers;
+- for each image, its natural size, rendered size, `object-fit`, and the pixel ratio of the capture.
+
+It warns when a video, or an image over 500,000 transfer bytes, comes from the page's own origin. It also warns when an image has at least twice the pixels needed at its rendered size and the captured pixel ratio (currently 1), for images of at least 250,000 natural pixels; `object-fit: cover` cropping is allowed for. Captures with cached or unmeasured transfers, partial transfers that cannot decide the result, image probes that were cut short, and never-loaded media are unexercised, never small. Another origin is reported as another origin: this check does not decide whether it is a CDN or what hosting costs. Pages Polish does not capture are listed as unexercised. The image probe runs after network observation ends and adds no requests. The record is checked against the page-load capture it came from on every read.
+
+The size check covers `<img>` elements in the page, including those inside open and closed shadow roots; images inside an iframe, `<input type=image>`, `<object>`, SVG `<image>` and CSS background images are not checked for size, and only their transfer bytes are weighed.
+
 ### Collector response records (the producer's wire form)
 
 Inside the producer, the browser adapter's CDP collector emits one

package/docs/qa-and-test-orders.md

@@ -39,8 +39,10 @@ the toolkit runs that loop in a fixed order:
 1. **Build in development.** The build stage runs page-kit in the development
    environment — `CPK_ENV=development npx campaign-build --json >
    .campaign-runtime/page-kit-build-summary.json` — into the target's normal
-   `_site/`, and records `stages.assembly.evidence.build_environment:
-   "development"` on the Assembly Report. `next build` names the command as
+   `_site/`, and `campaigns-os record build --packet <packet>
+   --build-environment development` records
+   `stages.assembly.evidence.build_environment: "development"` on the Assembly
+   Report. `next build` names the command as
    the `build_local_proof` action and in the build prompt; doctor warns
    (`local_proof.build_environment`) on a completed build that is not recorded
    as a development render. The starter templates gate every vendor loader on
@@ -55,9 +57,10 @@ the toolkit runs that loop in a fixed order:
    with it locally (the parity step renders it to a temp dir, and the deploy
    host renders it from the committed source).
 2. **Serve and prove.** Serve `_site/` on localhost (the `next deploy` handoff
-   names the directory and any root-route rewrite), record the URL on
-   `deploy.preview_url`, then run `polish capture`, `qa run --browser`, and the
-   typed-card order paths against it.
+   names the directory and any root-route rewrite) and run `polish capture`
+   against it. Once polish is recorded, `record deploy --packet <p> --base-url
+   <url>` records the URL on `deploy.preview_url` and the deploy stage; then run
+   `qa run --browser` and the typed-card order paths against it.
 3. **Prove the pin on the production output.** Before committing, run
 
    ```bash
@@ -367,7 +370,11 @@ Only contract-governed claims are compared, and only against `Exact` normalized
 truth. Proven differences emit warn-severity `pricing` assertions named
 `price-claim-mismatch`, `cadence-disclosure-mismatch`, or
 `voucher-not-applied`. Decorative, ambiguous, stale, unresolved, or malformed
-claims remain silent. The verdict's top-level `commercial` section records
+claims remain silent. A page showing a voucher the normalized plan cannot price
+(no calculated pair for its code, for example a live voucher on an upsell)
+leaves that page's price claims unresolved: the plan's only Exact truth for
+the page is then the list price, which a voucher-priced page is expected to
+differ from. The verdict's top-level `commercial` section records
 coverage, sanitized missing/unmatched/invalid capture evidence, proxy issues,
 and findings; the same findings are serialized deterministically into the flat
 `assertions` array consumed by existing QA tooling. A proven mismatch keeps the
@@ -1599,7 +1606,7 @@ the CampaignSpec instead:
   purchase multipliers (`ref` and `ref:2`). A uniquely referenced catalog
   package with its own `qty: 3` composition is still bought once (`ref`), not
   multiplied by three. **Order-bump rows — `packages[]` entries marked
-  `is_upsell: true` — are add-ons offered beside the selected tier, not tiers**:
+  `is_order_bump: true` or `is_upsell: true` — are add-ons offered beside the selected tier, not tiers**:
   they never become a plan (a three-tier checkout with one bump plans three
   tiers, so `tiers:common` on a two-upsell funnel is 12 orders, not 16), and
   the runner prints a `[qa:test-order]` line naming the bump ref(s) it left
@@ -1858,6 +1865,34 @@ table in [build-packet.md](./build-packet.md#deploy-target) and
 [Local proof mode](#local-proof-mode-deploytarget-local-serve) above for the
 development build, the parity check, and the order they run in.
 
+### Tracking parameters
+
+**Tracking parameters.** During a browser test order, QA adds synthetic tracking values (`utm_*`, `affid`, `sub1`, `subaffiliate2`, and up to eight names from `analytics.params.tracking.preserve`) to the pages it loads before the campaign's own navigation starts. It reports two results:
+
+- **URL preservation:** whether each value is still in the address after each page navigation it observed, through to the navigation after the order. A failing step is named only when QA observed both sides of it. A reload by QA itself, an unobserved step, or an attempt that ended early ends the measurement without a pass.
+- **Order attribution:** whether the matching attribution field reached the request of an order the store accepted.
+
+Values from `<meta name="os-tracking-tag">` tags are checked against order metadata. When page script sets attribution itself, differences are review results. Only synthetic values and equality results are stored, and order URLs in QA evidence are now stored without their query. Click ids and `funnel` are not seeded, even when listed in `tracking.preserve`, and are listed as not tested.
+
+Every string QA stores in its verdict is cut at its first query (a `?`, written literally or percent-encoded), every URL in it is also cut at its fragment, and a string longer than 16 KiB is truncated.
+
+## Content parameters
+
+**Content parameters.** For each `analytics.params.content` entry, QA loads each applicable page twice in separate fresh browser contexts: once without the parameter and once with `?<name>=n`. It waits for the SDK to finish its display pass, then checks that the same elements whose `data-next-hide` or `data-next-show` refers to `param.<name>` are visible without the parameter and hidden with it. A parameter whose only handlers cannot hide anything with `n` is a warning. Compound conditions, conditions the SDK parses unreliably, content already hidden without the parameter, elements that change between the two loads, pages that fail to load, and pages where the SDK did not finish produce review or unexercised results, never a pass. Runs without `--browser` list these checks as not requested. No orders are placed.
+
+## Policy links
+
+**Policy links.** For each configured `store_terms`, `store_privacy`, `store_returns`, `store_shipping`, and `store_contact` URL, QA checks two things:
+
+- **Presence:** whether any visited page links to that exact destination, with trailing slashes and default ports normalized and query parameters kept. Presence is decided only when QA read the links on every page it visits; otherwise it is unexercised.
+- **Availability:** whether the URL reaches an HTML page within 5 redirects, using bounded GET requests that read headers only.
+
+A redirect to the right page is fine. Missing links, links whose query differs, links whose declared footer label points elsewhere, 404s, server errors and redirects to the store's home page are warnings. Authentication, rate limiting, loops, non-HTML responses, unexpected statuses, configured values that are not absolute URLs, and redirects to other destinations are review results. Network failures are unexercised. A 200 response proves only that the page is reachable. `mailto:` contacts are checked for presence only. Runs without `--browser` list these checks as not requested. Link wording is used only as an English review hint.
+
+## Operator accepts (`checkpoint accept`)
+
+**Accepting a warning.** `campaigns-os checkpoint accept` records an operator's decision about a warning that a Campaigns OS check measured. It does not change readiness, does not remove the warning, does not change the status `next` reports, and cannot be used on review, unexercised, or excluded results. The warning must already be on record (in the doctor snapshot `next` writes, the Polish capture, or the full QA verdict) before it can be accepted. The accept is bound to the exact measured state and lapses when that state changes, or when its evidence is stale or cannot be reproduced. An optional expiry or review condition adds a second bound. Run it only with the operator's explicit decision, made after the warning was shown to them. A plausible name is not authorization. The command refuses placeholder and automation identities. Results are re-derived from the package's raw captures on every read, and a result whose capture is missing or does not match is listed as unexercised. These checks are tamper evidence, not proof of authorship: a hand-written record that copies every value and recomputes the checksum, or a hand-written result written together with a matching capture, is not detected.
+
 ## Launch Readiness Note
 
 Campaigns OS can prove the campaign build, SDK wiring, browser behavior, and
@@ -1885,6 +1920,13 @@ use the declared topology instead of a single happy path:
 5. Use `full` when you want every actual terminal path, raising the flood cap to
    the exact planned count when necessary.
 
+`next` names step 4 at the QA stage. When the checkout page the default run
+drives declares an order bump (`is_order_bump: true` or `is_upsell: true` rows), it lists a second QA
+command, `qa_run_bump`, beside `qa_run`: the same `--test-order common` run
+with `--cart <base>:1,<bump>:1`, where the base is the first selector tier the
+checkout declares. The QA stage prompt and the human `next` output carry the
+same command.
+
 Record order numbers, `ref_id` values, and expected line-item shapes in the
 handoff. If the browser console shows an SDK module-load error but the SDK
 fallback loads and checkout/order proof passes, keep it as platform warning
@@ -1927,19 +1969,32 @@ expectations, and commerce-ref validation. A doctor-clean non-packet run means
 matches a spec". Treat it as a residue/visual gate, not equivalent to a
 packet-driven QA pass.
 
-### Per-page credential declarations
+### Per-page credential binding
 
 Canonical `qa run` emits `page-binding:<page_id>` in the existing `api-metadata`
 family, with `campaigns-os-page-binding/v0` evidence (typed in the verdict schema).
-`match` means the statically declared credential equals the expected credential;
+`match` means the page's credential equals the expected credential;
 `mismatch` is a blocker. `unknown` requires manual review. All three carry
 `identity: not_verified`: credential equality never proves a unique Campaign App
 ID, and no App ID is inferred from `campaignId` or `next-campaign-id`.
 
 Expected data reuses the commercial QA resolver (packet, then spec, then an
 explicit supported environment source). Conflicting authored values are unknown.
-The SDK loads `window.nextConfig.apiKey` before `next-api-key` at boot, so meta
-wins at runtime; this check deliberately reports differing declarations as a
+
+With `--browser`, the row comes from the key the Campaign Cart SDK actually
+sent. The SDK sends it as `Authorization` on every Campaigns API request, and
+the browser pass reads that header on each page it loads. The values are
+compared in memory and dropped: the evidence records
+`observation: sdk_request`, `source_kinds: ["sdk_request"]`, and `match` when
+every request carried the expected credential or `mismatch` when any carried
+another. This works whatever the
+page's scripts look like. A page that sent no Campaigns API request, or a run
+with no single expected credential, keeps the static row described below.
+
+Without `--browser`, or for such a page, the row is a static read of what the
+page declares (`observation: static_declaration`). The SDK loads
+`window.nextConfig.apiKey` before `next-api-key` at boot, so meta wins at
+runtime; the static read deliberately reports differing declarations as a
 conflict rather than certifying one. It does not observe SDK execution.
 
 The bounded HTML loader is reused. HTML is parsed without execution; JavaScript

package/docs/runtime-readiness.md

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

package/docs/sdk-storage-compatibility.md

@@ -10,7 +10,7 @@ Omit `--json` for the concise human report. Exit 0 means source-compatible; exit
 
 The manifest is generated and owned by Campaign Cart, from its storage registry. The scanner has no independent SDK key list and fetches no remote code. Supply `docs/compatibility/storage-migrations.v1.json` from an unmodified checkout of a Campaign Cart release tag, v0.4.40 or later. The report records the full file SHA-256, SDK version, supported target range, registry/extractor/input digest, and Git provenance. When the supplied bytes equal their repository HEAD blob, provenance is `verified-git-blob` with commit and repository path. Proposed, modified, or copied manifests are labeled `unverified-local-file`; the label never certifies a release. Review/pin SDK provenance separately before acting on findings. A release manifest covers the target range it declares, which may end below its own SDK version: the v0.4.40 manifest, for example, covers 0.4.38 only. Targets outside the manifest's supported SDK range report unknown. A manifest whose SDK version is below its supported maximum is invalid.
 
-`--target` must name the Git root. `--scope` is mandatory: comma-separated literal repository-relative directory/file paths; use `.` only when the complete repository is intended. Add shared JavaScript directories explicitly. `--exclude` uses the same syntax and records explicit exclusions. Archives receive no implicit exemption. Only Git-tracked `.html`, `.htm`, `.js`, `.mjs`, and `.cjs` files in the selected scope are scanned, using current working-tree bytes and per-file digests; untracked files and built dependencies are outside this evidence. A selected HTML page's local script outside the selected files reports unknown. Relative scripts affected by an HTML `<base href>` also report unknown; review their actual dependency paths. Remote SDK and third-party scripts are not fetched or analyzed.
+`--target` must name the Git root. `--scope` is mandatory: comma-separated literal repository-relative directory/file paths; use `.` only when the complete repository is intended. Add shared JavaScript directories explicitly. `--exclude` uses the same syntax and records explicit exclusions. Archives receive no implicit exemption. Only Git-tracked `.html`, `.htm`, `.js`, `.mjs`, and `.cjs` files in the selected scope are scanned, using current working-tree bytes and per-file digests; untracked files and built dependencies are outside this evidence. A selected HTML page's local script outside the selected files reports unknown. In a Page Kit campaign (a page under `src/<slug>/`), a script src written `{{ 'js/x.js' | campaign_asset }}` resolves to `src/<slug>/assets/js/x.js`, as Page Kit serves it, and a page's frontmatter `scripts:` entries resolve the same way, since a layout's `{% for script in scripts %}` loop loads them through that filter. Any other `campaign_asset` value, a path that resolves outside the assets folder, and frontmatter that is not valid YAML or whose `scripts` is not a list of paths report unknown. Relative scripts affected by an HTML `<base href>` also report unknown; review their actual dependency paths. Remote SDK and third-party scripts are not fetched or analyzed.
 
 Acorn parses JavaScript ASTs; parse5 identifies executable inline HTML scripts and source offsets. Findings inventory storage area, operation, key, file/line/column, reason, and SDK-owned public replacement when supplied. The scanner recognizes direct `localStorage`/`sessionStorage`, `window`/`globalThis`/`self` properties, simple constant browser-global/storage aliases and storage destructuring, literal `getItem`/`setItem`/`removeItem` calls (including bracket method notation), property access/assignment/deletion, and lexical constant string indirection. Comments, ordinary strings, JSON script blocks and public store calls do not become storage reads. A literal legacy SDK key at or after its manifest migration boundary is incompatible. Guessed prefixes cannot establish compatibility.