@nextcommerce/campaigns-os 1.48.0 → 1.52.0

package/CHANGELOG.md

@@ -2,6 +2,545 @@
 
 Notable supported-surface changes are recorded here.
 
+## [1.52.0+agent.1] - 2026-10-05
+
+### Added
+
+- Doctor now reports built-page smoke warnings: missing in-page anchor targets, missing favicon and Open Graph tags, unresolved `og:image`, the Tailwind CDN script in production builds, `cdn.29next.store` asset references, and loopback URLs.
+
+## [1.52.0] - 2026-10-05
+
+### Added
+
+- QA now checks that configured store policy links are rendered and reachable, recording link presence and availability separately. QA now sends bounded header-only requests to the configured policy URLs; the effects contract declares them.
+
+### Changed
+
+- The effects contract now states that `qa run --browser` sends the header-only GET requests to the configured store policy URLs, rather than declaring them ahead of the check that sends them.
+
+## [1.51.0+agent.4] - 2026-10-05
+
+### Added
+
+- QA now checks at runtime that declared content parameters hide their content, comparing fresh contexts with and without `?<name>=n`.
+
+## [1.51.0+agent.3] - 2026-10-05
+
+### Added
+
+- QA browser test orders now report URL preservation and order attribution for synthetic tracking parameters as separate results. QA order evidence no longer stores query strings in `checkout_url`, `final_url` or request URLs.
+
+## [1.51.0+agent.2] - 2026-10-05
+
+### Added
+
+- Polish capture now records image geometry and redirect chains, and reports origin and weight warnings for video and large images served from the page's own origin, plus oversized images.
+
+### Changed
+
+- `polish capture` now records media weight beside page load evidence in the Assembly Report, so `next` reads the image weight and oversize results of a fresh capture.
+
+## [1.51.0+agent.1] - 2026-10-04
+
+### Added
+
+- Doctor now warns on SDK cart placeholders printed in live built HTML (`built_output.cart_placeholders`), ported from the public starter-template lint.
+
+## [1.51.0] - 2026-10-04
+
+### Added
+
+- Adds `checkpoint accept`, which records an operator's accept of a measured warning next to the unchanged measurement, and a QC handoff section in `next` that lists open, review, lapsed, unexercised and excluded results. Accepts never change readiness, and `checkpoint waive` still refuses gates that are not blocked.
+- The effects contract now declares bounded header-only GET requests to the store policy URLs a CampaignSpec configures, for `qa run --browser`, ahead of the check that sends them; QA does not send them yet.
+
+## [1.50.0+agent.20] - 2026-10-04
+
+### Changed
+
+- `scripts/refresh-certified-family-fixtures.mjs` now sets `og_image` to
+  `https://example.com/og-image.png` on each certified family's
+  `_data/campaigns.json` entry before it renders, and records that in the
+  fixture manifest as `render_inputs`. The starters leave `og:image` out until
+  a campaign sets one, so without it every certified page would report a
+  missing `og:image` to the coming built-output smoke checks. The value is on a
+  reserved domain, so it is plainly synthetic, and doctor `--built` neither
+  maps nor fetches it. The committed fixture tree is unchanged until the next
+  regeneration.
+
+## [1.50.0+agent.19] - 2026-10-03
+
+### Fixed
+
+- A campaign-identity finding (`funnel_drift`, `funnel_missing`,
+  `api_key_drift`, `attribution_drift`) that names a built file no active
+  CampaignSpec page builds to now says so, and lists the file on the finding as
+  `stray_files`. The message says to remove the source file if there is one,
+  delete the built file, and rebuild and record the build again. Before, a
+  design `index.html` copied under `assets/` built as its own page and blocked
+  as funnel drift, with the message telling the agent to retag a page it never
+  meant to ship. The gate still blocks, because the file is still served.
+
+## [1.50.0+agent.18] - 2026-10-03
+
+### Fixed
+
+- Commercial parity no longer warns `price-claim-mismatch` on a page that shows
+  a voucher the normalized plan cannot price. An upsell priced by a live
+  voucher showed the voucher price, and QA compared it with the list-price
+  total. Those price claims now count as unresolved, as the page's voucher
+  claims already did, so coverage reads incomplete instead.
+- `browser-order-bump-state` reads a `✓` glyph marker as checked only when its
+  text is painted. A tick that stays in the marker and is hidden with
+  `color: transparent` read checked before, so a declined bump failed as
+  misaligned.
+
+## [1.50.0+agent.17] - 2026-10-03
+
+### Fixed
+
+- Three CampaignSpec validation messages that doctor and `start` print now say
+  which field to change:
+  - The missing-`payment_env_key` warning keeps "No campaign loaded — campaign
+    key required for spec export." and adds that `campaign.payment_env_key` is
+    empty, where its value comes from, and that a Campaigns API key in the spec
+    does not fill it. Before, it printed next to doctor's "Campaigns API key
+    available via the packet-local CampaignSpec" line and read as if the key
+    were missing.
+  - The missing SDK version error keeps "SDK version is required for spec
+    export." and names `global_config.sdk_version` and the form it takes.
+  - The missing `design_source.file_url` warning, for a page whose
+    `design_source.type` is not `figma` or `ai-generated`, and doctor's
+    matching no-source-mapping error, say that hand-written or template HTML
+    leaves `design_source` off the page. Before, a plain HTML page with a
+    `design_source` block was told only to add a design-tool URL.
+
+## [1.50.0+agent.16] - 2026-10-03
+
+### Fixed
+
+- `prepare-build` (and `start`) no longer write an Assembly Report that fails
+  its own schema. When the brand-theme write failed, each error was copied
+  onto `theme.warnings[]` as `{ code, message, detail: error.detail || null }`.
+  The schema's `themeIssue.detail` is an object, so an error with no detail
+  (`theme.generate.not_ready`, `theme.generate.empty`) left `detail: null`.
+  `record setup` and `record build` then refused the report with
+  "Assembly Report theme.warnings.0.detail must be object". `detail` is now
+  written only when the error carries an object. The schema is unchanged.
+
+## [1.50.0+agent.15] - 2026-10-03
+
+### Fixed
+
+- `record setup|build|polish|theme|deploy` accept `--deviation-reason`, as
+  every other command does. The deviation notice tells an agent that departs
+  from `next` to "Declare intent with --deviation-reason". `record` checks its
+  flags against a strict allowlist, which held only its own flags and the global
+  `--run-id` and `--lifecycle-journal`, so it refused the flag as unknown on
+  every stage. It is now a global flag there too. A bare `--deviation-reason`
+  with no value is refused as before.
+
+## [1.50.0+agent.14] - 2026-10-03
+
+### Fixed
+
+- QA's placeholder text-residue gate (`template-residue:<page>:placeholder-text`,
+  and doctor's built-output warning) now also matches the starter templates'
+  own icon-grid placeholders, `Benefit one`, `Benefit two`, `Benefit three` and
+  `Benefit four`. The olympus checkouts ship them, and a campaign that kept
+  them passed QA with no failures, because the shared-commerce term list held
+  only `Lorem`, `lorem ipsum`, `Placeholder`, `TODO` and `Product Name`.
+  - The terms live in `contracts/template-brand-contract.shared-commerce.v0.json`,
+    so every family inherits them.
+  - Matching is word-bounded, so "Benefit once" does not fire.
+  - Doctor's next-step hint and `docs/template-family-contracts.md` list them.
+
+## [1.50.0+agent.13] - 2026-10-03
+
+### Fixed
+
+- The source preparation check `source_html.prep.document_wrapper` reads a
+  page's converted page-kit file once it exists at `page_kit.output_path`, not
+  the design it was converted from. Wrappers are stripped during conversion,
+  and the converted page is what page-kit builds. The check only ever read the
+  mapped design, so a correctly stripped build still failed. To clear it,
+  agents copied built pages over the design source (breaking the Design Source
+  Package hashes) or recorded `preserve_document_wrappers` for pages they had
+  stripped. A converted page that still carries wrappers is reported under its
+  own path. Before conversion the design is checked as before. The frontmatter
+  and source-link checks are unchanged. `docs/source-adapters.md` says so.
+
+## [1.50.0+agent.12] - 2026-10-03
+
+### Fixed
+
+- `record deploy` follows `next` past a polish carried forward on the local
+  preview. On a `local-serve` packet with a loopback preview, `next`'s stage
+  picker skips a polish that was never recorded for this build (the
+  local-preview policy carries it forward as a warning), so after
+  `record build` it answers deploy. `record deploy` checked every earlier
+  stage strictly and refused with "stages.polish.status is "required", so next
+  answers polish", which contradicted `next`. Sessions hand-wrote a polish skip
+  record to get past it. Both now read the same rule, from doctor's
+  `polish_gate`. Polish stays owed on the report and QA still reports it.
+  `record polish` and the waiver commands keep the strict gates.
+  `docs/build-packet.md` names the exception.
+
+## [1.50.0+agent.11] - 2026-10-03
+
+### Added
+
+- Doctor warns `spec.material_stale` when a local-spec campaign's CampaignSpec
+  no longer has the material hash prepare-build bound on the Assembly Report
+  (`identity.spec_material_hash`). `next` prints the warning with the rest of
+  doctor's. QA already refused such a run ("Re-run prepare-build after a
+  material revision"). Until now it was the only command that checked, so a
+  spec edited after `start` was accepted by doctor, `next` and every `record`
+  command, and the problem surfaced only after the build, polish and deploy
+  stages had been recorded against the old spec. The warning names both hashes
+  and says to re-run prepare-build from the edited spec.
+  `docs/build-packet.md` says so.
+
+## [1.50.0+agent.10] - 2026-10-03
+
+### Fixed
+
+- A checkout row marked `is_order_bump: true` is now read as an order bump.
+  The CampaignSpec schema and the authoring guide mark a checkout add-on with
+  that flag, and the certified fixtures use it alone, but the one bump
+  predicate the toolkit shares read only `is_upsell`. Such a row was treated
+  as a main package:
+  - the QA tier planner made it a selector tier of its own;
+  - `next` named no bump-cart QA command (`qa_run_bump`);
+  - commercial-journey priced the bump into the representative checkout and
+    planned no with/without-bump scenarios.
+
+  Either flag now marks a bump, and a row carrying `is_upsell: true` behaves as
+  before. On the certified fixtures, the five checkouts that declare a bump now
+  plan only their real tiers, and their bumps get the bump-cart command.
+- Messages that named a bump `(is_upsell)` now say
+  `(is_order_bump or is_upsell)`: the tier planner's warning and refusal, the
+  `next` bump-command description, the `qa run --help` text and the QA
+  test-order notes. `docs/qa-and-test-orders.md` says the same.
+
+## [1.50.0+agent.9] - 2026-10-03
+
+### Added
+
+- `record build --build-environment <development|production>` records the
+  page-kit environment the built output was rendered in, on
+  `stages.assembly.evidence.build_environment`. A later `record build` without
+  the flag keeps the recorded value. Before this, local proof mode
+  (`deploy.target: local-serve`) asked the agent to record the field, but no
+  command wrote it, so it was hand-edited into the Assembly Report.
+  - Under local-serve, `next` now names
+    `record build --packet <packet> --build-environment development` in the
+    build action and the build prompt.
+  - Doctor's `local_proof.build_environment` warning, the parity messages and
+    the local-proof rebuild hint name the same command.
+  - `docs/build-packet.md` and `docs/qa-and-test-orders.md` describe it.
+
+### Fixed
+
+- A `record` refused for a value outside a schema enum now lists the values the
+  schema allows and the value it got. For example,
+  `adapter_decisions.wrapper_policy must be equal to one of the allowed values:
+  "strip_document_wrappers", "preserve_document_wrappers", "not_required",
+  "unknown" (got "strip")`; before, it stopped at "allowed values".
+- Doctor's adapter-decision warning for an unknown value lists the allowed
+  values too.
+
+## [1.50.0+agent.8] - 2026-10-03
+
+### Changed
+
+- The vendored commerce-surface catalog is re-synced to
+  campaign-cart-starter-templates `02ffc61`, from `37a8d94`. That brings in
+  three starter changes:
+  - the single-offer upsell keeps a hidden in-offer skip, so its closing-card
+    decline works in every family (#205);
+  - `payment-methods.html` takes `method_order` and `default_method` (#202);
+  - fresh SDK 0.4.40 verification evidence (#203).
+
+  The upstream order-bump notes were consolidated, and the vendored copy
+  follows them.
+- `fixtures/certified-families/` is regenerated at the new pin. Every
+  `upsell-single` fixture now carries the in-offer skip, so QA's static
+  `route-link:<page>:decline` check, which fails a proxy decline with no
+  target, passes on all eight families instead of failing on each.
+- The shared commerce payment-chrome `asset_pin` moves to the new pin. The
+  asset bytes are unchanged.
+
+## [1.50.0+agent.7] - 2026-10-03
+
+### Fixed
+
+- `sdk storage-check` resolves Page Kit's `campaign_asset` script srcs. A
+  page under `src/<slug>/` that loads `{{ 'js/checkout.js' | campaign_asset }}`
+  is read as `src/<slug>/assets/js/checkout.js`, where Page Kit serves it from,
+  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.
+  Until now every such tag read as a relative path that was never in scope and
+  reported `shared-script-outside-scope`, so every Page Kit campaign came back
+  `unknown` even when nothing was incompatible (#582). A resolved script left
+  out of `--scope`, or excluded, is still reported, under its real path; a
+  `campaign_asset` value the scan cannot resolve stays unknown.
+  `docs/sdk-storage-compatibility.md` says so.
+
+## [1.50.0+agent.6] - 2026-10-03
+
+### Fixed
+
+- QA no longer passes an upsell decline or accept that does nothing. Some
+  upsell pages show a `data-upsell-proxy="skip"` (or `"add"`) button that
+  forwards its click to the SDK's `data-next-upsell-action` inside the offer.
+  When the offer has no such action, the static `route-link:<page>:decline`
+  (or `:accept`) check used to pass on the decline URL in the page's meta tag,
+  and only browser QA, after placing the order, found the control missing. The
+  static check now fails as a blocker and says the proxy has nothing to
+  forward to. The starter templates' single-offer upsell shipped this way in
+  every family until the templates kept a hidden in-offer skip.
+- Browser QA declines (and accepts) through the control a shopper sees. When
+  the page's `data-next-upsell-action` is hidden and a visible
+  `data-upsell-proxy` button forwards to it, QA clicks the proxy instead of
+  failing with `Element is not visible` on the hidden action. A proxy with no
+  in-offer action is still reported as a missing upsell control.
+
+## [1.50.0+agent.5] - 2026-10-03
+
+### Changed
+
+- The agent context the toolkit installs (`agents/claude/CLAUDE.md`,
+  `agents/codex/AGENTS.md`, `agents/cursor/campaigns-os.mdc`,
+  `agents/copilot/copilot-instructions.md`) and the `next-campaigns-os` and
+  `next-campaigns-qa` skills no longer say test orders need no permission or
+  approval, or are safe to fire any time. They say `qa run` has no permission
+  flag and coverage is its only control, and that test orders still land in
+  the store as real orders (global test cards: no charge, no transaction) that
+  someone may have to cancel. Unless the operator has already said test orders
+  are fine for the campaign, the agent asks once, up front in its first turn
+  with its other setup questions, so the answer covers the whole build and QA
+  and neither stops for it later. The skill's session-intake reference says
+  the same in its test-order proof policy.
+- The QA skill follows an answer the operator already gave and does not pause
+  QA to ask again. When nobody asked earlier, it asks once before the first
+  test order.
+- `qa run` is unchanged: it has no permission flag and none is added. Its
+  help text and the docs are unchanged.
+- Bundled skills carry revision `1.50.0+skills.2`, with each skill version
+  advanced one patch.
+
+## [1.50.0+agent.4] - 2026-10-02
+
+### Changed
+
+- At the QA stage, `next` lists a second QA command when the CampaignSpec's
+  checkout declares an order bump (`is_upsell: true` rows). `qa_run_bump`,
+  beside `qa_run`, is the same `qa run --browser --test-order common` with
+  `--cart <base>:1,<bump>:1`, so its test orders carry the add-on and prove
+  its charge. Until now `next` named only the default run. Its test orders
+  never toggle a bump, because the tier planner skips bump rows by design and
+  bump coverage comes from `--cart`, so a verdict could read ready with the
+  add-on never ordered. The base is the first selector tier the checkout
+  declares; a checkout that declares no tier gets the bump alone, and several
+  declared bumps share one cart. The QA stage prompt and the human `next`
+  output name the same command, and `docs/qa-and-test-orders.md` says so
+  under its launch-grade proof list. The bump is read from the one checkout
+  QA's test orders run on, the first enabled checkout across funnels, so a
+  bump declared only on a later funnel's checkout gets no command. When the
+  CampaignSpec does not parse, `next` warns
+  (`next.order_bump_spec_unreadable`) instead of silently naming no bump
+  command.
+- A progress snapshot records `qa_run_bump` as `qa_run`. The snapshot's
+  action vocabulary is unchanged, and a ready QA continuation does not read
+  as blocked.
+- The QA tier planner reads its bump and tier helpers from the
+  commercial-journey module, where `next` reads them too. Tier planning is
+  unchanged.
+
+## [1.50.0+agent.3] - 2026-10-02
+
+### Changed
+
+- The Campaign Build Brief question `promo_urgency_copy` now asks only about
+  the starter template's own promo placeholders: demo countdown timers, promo
+  banners, placeholder voucher codes and exit-pop offers. It asks whether to
+  fill them from the campaign's promo codes and offers or remove them. It no
+  longer asks which promo, savings and urgency language is approved, which
+  read as a request to approve the source design's own copy; that copy is the
+  merchant's content and is built as designed.
+- The question is asked only when the CampaignSpec maps a surface that fills
+  those placeholders: a `funnels[].promo_codes` roster, or a checkout page's
+  enabled `exit_intent` or `promo_code_input`. It used to be asked for any CampaignSpec
+  key naming an offer, discount, timer or urgency, so the offer catalog,
+  before-discount prices and design slot names all raised it. Without such a
+  surface the guided draft sets `promo_urgency.header_claim_source` and
+  `promo_urgency.timer_label` to `"none"` (the template's promo placeholders
+  are removed). The draft used to set `timer_label` to "Limited-time offer".
+- Doctor's `build_brief.guided_questions` warning names the brief fields that
+  close each open question and says how to record the answers: copy the
+  normalized draft to `campaign-build-brief.json` in the target repo, set the
+  fields, and re-run `start` or `prepare-build`. It also says the re-run needs
+  `--force`, which clears stage evidence, once a stage has recorded evidence.
+  `build_brief.questions_unanswered` names the fields too. An answer given
+  only in conversation was never recorded, so a later session asked again.
+- `next`'s QA prompt compares the template's own promo placeholders and trust
+  badges with the brief and says not to flag the source design's own proof,
+  urgency or guarantee elements. It used to ask for promo/urgency copy and
+  trust/guarantee claims to be compared. The build prompt names the template's
+  promo placeholders where it named promo/urgency language.
+- `docs/campaign-build-brief.md` rewords question 5 and adds "Answering The
+  Questions", with the fields that close each question.
+
+## [1.50.0+agent.2] - 2026-10-02
+
+### Changed
+
+- `docs/build-packet.md` says how to read a campaign's package, offer and
+  shipping refs for a local CampaignSpec. Its new "Reading package, offer and
+  shipping refs" section, under "Local-spec entry", gives the read doctor and
+  QA already make against the live campaign: one GET of NEXT's proxy,
+  `https://campaign-map.nextcommerce.com/api/campaign`, with the public
+  Campaigns API key in the `X-Campaign-Key` header. It shows a `node` and a
+  `curl` form, describes the envelope, and maps the campaign retrieve body's
+  `id`, `packages[]`, `offers[]` and `shipping_methods[]` to
+  `campaign.ref_id`, `funnels[].pages[].packages[]`, root `offers[]` and root
+  `shipping_methods[]`. It also notes that the proxy refuses some default user
+  agents, Python `urllib`'s and Perl `libwww-perl`'s among them. No command
+  writes these refs, as before.
+- With no saved gateway login, `tooling status` no longer only says to run
+  `login`. Its warning says login is optional and only lets `spec derive
+  --from-store` fill the Store Profile fields, and a second warning says
+  package, offer and shipping refs never come from the gateway login and
+  where the public-key read is documented. Both lines are under `warnings`,
+  and the exit code is unchanged.
+
+## [1.50.0+agent.1] - 2026-10-02
+
+### Changed
+
+- No command behaves differently. A comment in the QA browser module that
+  explains how repeated package declarations become purchase multipliers
+  named an internal store as its example; it now gives a neutral one (a 1x
+  and a 2x package). Two QA test files swap the same name in a fixture SKU
+  and a hosted-checkout URL for neutral placeholders, and the same fixture's
+  product title becomes "Demo Bag". Comment and test fixtures only; every
+  message and every exit code is unchanged.
+- The private-string check adds that store name to its hashed list, so it
+  cannot return.
+
+## [1.50.0] - 2026-10-02
+
+### Changed
+
+- With `qa run --browser`, each page's `page-binding:<page_id>` row comes
+  from the key the Campaign Cart SDK actually sent. The SDK sends the page's
+  key as `Authorization` on every Campaigns API request. The browser pass
+  reads that header on each page it loads, compares it with the expected key
+  in memory and keeps only the outcome: `match` (pass) when every request
+  carried the expected key, `mismatch` (blocker) when any carried another.
+  The key itself is never recorded. The static read of a page's declarations
+  could not resolve most real pages: the starter templates' `config.js` opens
+  with `window.dataLayer = window.dataLayer || []` and
+  `window.nextReady = window.nextReady || []`, which the static grammar treats
+  as dynamic, so every starter page was left for manual review, and inline
+  scripts, `async` scripts and scripts from other origins left other pages
+  the same way. A page that sends no Campaigns API request, a run with no
+  single expected key, and `qa run` without `--browser` keep the static read.
+- The QA verdict schema's page-binding evidence accepts
+  `observation: "sdk_request"` and the `sdk_request` source kind for that row.
+  Nothing is removed, so every verdict that validated before still does.
+  `docs/qa-and-test-orders.md` describes both observations.
+- Ships the same-surface changes recorded since 1.49.0, each described in
+  its own section below: the agent context spells every command
+  `npx --no-install campaigns-os …` and carries the build skill's proof rule
+  (`+agent.1`); and the install-mode module drops a stale comment, with no
+  behavior change (`+agent.2`).
+- Package and supported-surface version advance to 1.50.0 for the QA verdict
+  schema hash. The local setup install command pins 1.50.0. Bundled skills
+  carry revision `1.50.0+skills.1`, with each skill version advanced one
+  patch. The skill text is unchanged.
+
+## [1.49.0+agent.2] - 2026-10-02
+
+### Changed
+
+- No command behaves differently. The install-mode module drops a trailing
+  comment that described `applyInvocationPrefix`, a function removed when
+  commands began to be spelled with their prefix at the source (`cmd()` and
+  `asInvocation` in the install-invocation module). Comment-only; every
+  message and every exit code is unchanged.
+
+## [1.49.0+agent.1] - 2026-10-02
+
+### Changed
+
+- The agent context that `install-agent-context` and `tooling setup` write
+  (`agents/claude/CLAUDE.md`, `agents/codex/AGENTS.md`,
+  `agents/copilot/copilot-instructions.md`, `agents/cursor/campaigns-os.mdc`)
+  spells every command `npx --no-install campaigns-os …`, as the skills and
+  `AGENTS.md` do. It said `campaigns-os readback .`, `campaigns-os qa run …`
+  and so on, and fresh sessions ran them as written: "command not found"
+  where nothing is installed globally, and an older global copy instead of
+  the campaign's pinned one where something is. A test keeps bare commands
+  out of the agent context.
+- The agent context carries the build skill's proof rule: reproduce the
+  source design's own proof and urgency elements as designed, and do not
+  remove, soften or flag them. The rule was only in the build and polish
+  skills, and sessions were still questioning or removing the merchant's
+  proof.
+- An installed copy keeps the old text until `install-agent-context`
+  refreshes it.
+
+## [1.49.0] - 2026-10-02
+
+### Added
+
+- `campaigns-os record theme --packet <p>` records an applied brand layer on
+  the Assembly Report, where the theme gate previously sent the operator to
+  edit `report.theme` by hand. It reads each built commerce page's stylesheet
+  links in document order. A page that loads `next-core.css` must load
+  `brand-theme.css` (or `checkout-brand.css`) after it, and that file must be
+  in the built output. A page that loads neither renders the design's own
+  markup and is left out, noted in the evidence. When every page passes and at
+  least one loads the brand layer, it writes `report.theme`: status `applied`,
+  `load_order` `after-next-core`, `css_path`, `commerce_pages` and one evidence
+  line per page, and clears any earlier theme waiver. Otherwise it is refused,
+  naming each page, and writes nothing. Build must be recorded for the current
+  output first. `--dry-run` runs every check and writes nothing.
+- `campaigns-os record deploy --packet <p> --base-url <url>` records a local
+  preview (`deploy.target: local-serve`), where `next` previously sent the
+  operator to edit the packet and `stages.deploy` by hand. The URL must be a
+  loopback origin naming the campaign's route root. Every built page is
+  requested under it and must answer 2xx. It then writes the packet's
+  `deploy.preview_url` and `stages.deploy` completed, with the URL in
+  `outputs` and one evidence line per page. It is refused, writing nothing,
+  when any check fails, when polish is not recorded, when the built output
+  changed since build was recorded, or while the theme gate is blocked. The
+  requests stay on this machine. `--dry-run` runs every check, the requests
+  included, and writes nothing.
+
+### Changed
+
+- The theme gate's apply and load-order actions, the starter-palette notice,
+  the build prompt, the build and polish skills, `docs/brand-theme-bridge.md`
+  and `docs/build-packet.md` name `record theme` where they described a hand
+  edit of `report.theme`.
+- `next`'s local-serve deploy action and deploy prompt,
+  `docs/build-packet.md` and `docs/qa-and-test-orders.md` name `record deploy`
+  where they described a hand edit of `deploy.preview_url` and
+  `stages.deploy`.
+- `contracts/effects.v1.json` declares `record theme`, `record deploy` and
+  their `--dry-run` forms.
+- The Build Packet schema's `assembly.template_family` accepts every family
+  the commerce surface catalog and the private template sources name:
+  `apollo`, `apollo-mv-single-step`, `arjuna` and `karna` join the enum, which
+  had fallen behind both. Nothing is removed, so every packet that validated
+  before still does.
+- Package and supported-surface version advance to 1.49.0 for the effects
+  contract and Build Packet schema hashes. The local setup install command pins 1.49.0. Bundled skills
+  carry revision `1.49.0+skills.1`, with each skill version advanced one patch;
+  the build and polish skills also name `record theme`.
+
 ## [1.48.0] - 2026-10-02
 
 ### Changed

package/agents/claude/CLAUDE.md

@@ -6,7 +6,7 @@ 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/`.
+To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install 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:
 
@@ -19,20 +19,21 @@ Core rules:
 - 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 source HTML for landing/presell pages when it is a real standalone design.
 - For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references: preserve required `data-next-*` controls and runtime wiring, but let the campaign/source own visual chrome, copy hierarchy, imagery, and brand layer.
+- Reproduce the source design's own proof and urgency elements as designed (reviews, ratings, stock counters, countdowns, guarantees). They are the merchant's content; Campaigns OS does not review them, so do not remove, soften or flag them.
 - If `.campaign-runtime/build-context.json` has `theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence. A 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.
 - Copy a starter template family atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages.
 - Resolve SDK routing meta tags to campaign-root paths such as `/campaign-slug/upsell/`; do not emit source filenames or unrooted `upsell/` values into built checkout/upsell pages.
 - Default one-time `packages.prepurchase_*` order bumps to fixed quantity rather than syncing with the main bundle unless the spec explicitly requires sync.
 - Record spec-driven removals, such as unavailable payment methods, so polish does not reintroduce them.
 - Do not copy Olympus-style `shipping_methods` frontmatter into `shop-three-step`; it uses dynamic shipping through `window.next.getShippingMethods()`.
-- Run build/lint checks and record evidence in the assembly report, then hand off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
-- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve --packet campaign-runtime.build.json`, then run `campaigns-os qa run --packet campaign-runtime.build.json --base-url <url> --browser --test-order common`.
-- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Coverage is the only control — there is no permission/approval step.
+- Run build/lint checks and record evidence in the assembly report, then hand off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
+- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve --packet campaign-runtime.build.json`, then run `npx --no-install campaigns-os qa run --packet campaign-runtime.build.json --base-url <url> --browser --test-order common`.
+- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. `qa run` has no permission flag: coverage is its only control.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Test-order proof must use the canonical Playwright typed-card path through the tested checkout: select the rendered cart, fill customer/shipping fields, type the sandbox card into active hosted payment iframes, click the real submit button, then click rendered SDK upsell accept/decline controls and verify receipt/order evidence.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
 - Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof. Those are diagnostic fallbacks only when explicitly requested.
-- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific routing confirmation. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; 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.
+- Test orders still land in the store as real orders that someone may have to cancel (global test cards bypass the gateway: no charge, no transaction, no merchant-specific routing to confirm). Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; 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.
 - Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
 
 Current source adapter: prepared HTML/assets (`html_funnel`).

package/agents/codex/AGENTS.md

@@ -3,9 +3,9 @@
 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/`.
+- To pick up an existing campaign, run `npx --no-install campaigns-os readback .` and `npx --no-install 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.
+- Run `npx --no-install 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.
 - Respect the selected template family's `agentContract`.
 - Replace demo refs from CampaignSpec/API; do not preserve starter sample IDs.
@@ -13,15 +13,16 @@ Use this context when working in a target campaign repo with Campaigns OS artifa
 - 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 source HTML for landing/presell pages when it is a real standalone design.
 - For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references: preserve required `data-next-*` controls and runtime wiring, but let the campaign/source own visual chrome, copy hierarchy, imagery, and brand layer.
+- Reproduce the source design's own proof and urgency elements as designed (reviews, ratings, stock counters, countdowns, guarantees). They are the merchant's content; Campaigns OS does not review them, so do not remove, soften or flag them.
 - If `.campaign-runtime/build-context.json` has `theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence. A 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.
 - Copy a starter template family 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/`.
 - Default one-time `packages.prepurchase_*` bumps to fixed quantity unless the CampaignSpec explicitly requires package sync.
 - Record spec-driven drops so polish does not reintroduce unsupported source elements.
 - For `shop-three-step`, keep dynamic shipping via `window.next.getShippingMethods()` and do not add Olympus-style static `shipping_methods` frontmatter.
-- Build hands off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
-- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL.
-- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed — coverage is the only control. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
+- Build hands off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `npx --no-install campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
+- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `npx --no-install campaigns-os qa resolve`, then `npx --no-install campaigns-os qa run --browser --test-order common` against the tested URL.
+- Typed-card test-order proof uses `npx --no-install campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. `qa run` has no permission flag: coverage is its only control. Test orders still land in the store as real orders (global test cards: no charge, no transaction) that someone may have to cancel. Unless the operator has already said test orders are fine for this campaign, ask once, up front in your first turn with your other setup questions, so the answer covers the whole build and QA and neither stops for it later. `common` runs every actual terminal path when they fit under the flood cap (`--max-test-orders`, 6 by default); above the cap it runs the checkout baseline, first-offer accept and decline, and a deduplicated shortest real receipt path, then adds one decline path per offer or downsell page not yet declined, up to the cap, and names any page left out. A page counts as covered only when an order clicks its decline; the `browser-test-order:upsell-action-coverage` verdict row warns naming each page whose decline no order clicked. `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
 - Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
 - Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
 - Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.