@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/docs/entry-points.md

@@ -0,0 +1,188 @@
+# Entry Points
+
+A CampaignSpec is the destination contract. Source HTML is the input
+that gets composed against it. **Where source HTML comes from is the
+entry point.** Different campaigns enter the build pipeline from
+different shapes:
+
+| Entry point | `design_source` on spec | Source-HTML manifest | What it looks like |
+| --- | --- | --- | --- |
+| Template-stock | unset | absent | Spec + filesystem of starter-template pages. No design overlay. |
+| Figma-driven | `type: "figma"` | emitted by `figma-sections-export` | Spec + source HTML produced by the Figma exporter. |
+| AI-generated | `type: "ai-generated"` | emitted by the producing agent | Spec + source HTML written by an LLM/agent. |
+| Hand-authored | unset | absent | Spec + source HTML hand-written by a designer/dev. Same shape as template-stock from the consumer's view. |
+| Mixed | per-page | one manifest enumerating every page | Spec + source HTML composed from multiple producers (figma export for landing, template stock for checkout, etc.). |
+
+The build pipeline (`prepare-build` → doctor → setup → build → polish
+→ deploy → QA) is **identical across all five entry points**. The
+only thing that varies is how the source HTML arrives and how
+`design_source` / the manifest get populated. Doctor reads both, the
+rest of the pipeline reads the packet doctor produced.
+
+This doc explains how each entry point is recognized, what
+populates each input, and what the operator does for that path. The
+[Source HTML Manifest Auto-Population](./build-packet.md#source-html-manifest-auto-population)
+section in `build-packet.md` covers the manifest consumer
+mechanics; this doc names which entry point produces which input.
+
+## Template-stock
+
+The campaign is being scaffolded against a starter template
+(e.g. `olympus-mv-single-step`) with **no design overlay yet**. Spec
+values fill the template's placeholders. Source HTML is whatever the
+template family ships, possibly with light brand tweaks.
+
+- **CampaignSpec:** every page is present but `design_source` is
+  unset on every page.
+- **Source HTML:** the starter template's `src/` folder copied into
+  the target repo. Filenames match standard page-type conventions
+  (`landing.html`, `checkout.html`, `upsell.html`, `receipt.html`).
+- **Manifest:** absent.
+- **`prepare-build` behavior:** falls back to filesystem matching
+  (slug-based filename → CampaignSpec page mapping).
+- **Doctor behavior:** any page with no source mapping fires the
+  generic `source_html.pages.coverage` error (no Figma-specific hint
+  because `design_source` is unset).
+- **When to use:** initial scaffold, A/B variant testing on top of
+  an existing template, no-design-yet builds where the team will add
+  design later.
+- **Realistic example:** a single-product scaffold pass — clone
+  `olympus-mv-single-step`, fill spec, ship. Design overlay comes in
+  a separate later pass.
+
+## Figma-driven
+
+Design lives in Figma. `figma-sections-export` produces source HTML
+plus a manifest at handoff.
+
+- **CampaignSpec:** the pages that need design carry
+  `design_source.type === "figma"` with `file_url` plus
+  `breakpoints.{desktop, tablet, mobile}` per page.
+- **Source HTML:** `figma-sections-export` writes
+  `<campaign>/landing.html`, `<campaign>/_includes/landing/*.html`,
+  and/or `<campaign>/presell.html` into the source root.
+- **Manifest:** `<source>/.campaigns-os/source-html-manifest.json`
+  (or the file named by `--design-manifest <path>`) with
+  `generator: "figma-sections-export@<version>"`. Lists the
+  pages produced.
+- **`prepare-build` behavior:** reads the manifest, populates
+  `packet.source_html.pages[]` directly from it (bypasses filesystem
+  matching).
+- **Doctor behavior:** any spec page with `design_source` but no
+  source mapping fires a design_source-aware error naming the
+  Figma file and recommending
+  `npm run handoff -- <slug>` in figma-sections-export.
+- **When to use:** designer authors in Figma, ships the export at
+  handoff, build picks up automatically.
+
+## AI-generated
+
+An LLM or agent (Claude, Codex, etc.) writes the source HTML
+directly. The contract is the same as figma-driven from the
+consumer's view: a manifest at the agreed location with the agreed
+schema.
+
+- **CampaignSpec:** pages that were AI-produced carry
+  `design_source.type === "ai-generated"` so doctor can produce a
+  matching error message ("AI run hasn't completed" vs "designer
+  hasn't exported").
+- **Source HTML:** written by the AI agent into the source root,
+  with the same page-kit-ready conversion conventions documented in
+  [`source-adapters.md`](./source-adapters.md).
+- **Manifest:** same shape as the figma-driven case
+  (`source-html-manifest/v0`), with `generator: "<agent>@<version>"`.
+- **`prepare-build` behavior:** identical to figma-driven —
+  consumer doesn't care about provenance.
+- **Doctor behavior:** when an AI-marked page has no source
+  mapping, the design_source-aware error variant for `ai-generated`
+  fires (recommends re-running the AI agent rather than re-exporting
+  from Figma).
+- **When to use:** AI-generated landing/presell while
+  checkout/upsell stay on template stock. Pre-existing static HTML
+  pipelines that emit the manifest at handoff.
+
+## Hand-authored
+
+Designer or developer hand-writes the HTML directly. From the
+consumer's view this is shaped identically to template-stock: spec
+without `design_source`, no manifest, files on disk.
+
+- **CampaignSpec:** `design_source` unset on the hand-authored
+  pages.
+- **Source HTML:** the designer/dev places `.html` files in the
+  source root (any name; filesystem matching uses page-type slugs).
+- **Manifest:** absent.
+- **`prepare-build` behavior:** filesystem matching, same as
+  template-stock.
+- **Doctor behavior:** generic coverage error for missing pages.
+- **When to use:** one-off campaigns, presell article pages with
+  bespoke layouts, demos.
+
+## Mixed
+
+A single campaign with **per-page** entry points. Landing from
+Figma export, checkout from template stock, presell from an AI run.
+Per-page granularity is already in the schema (`design_source` is
+per-page; `source_html.pages[]` is per-page).
+
+- **CampaignSpec:** each page carries its own (or no)
+  `design_source`. There's no campaign-level "entry point" field —
+  per-page is the unit.
+- **Source HTML:** one source root, with files placed by whichever
+  producer owns that page. Recommend per-page subdirectories
+  (`landing/`, `checkout/`, `presell/`) when producers don't
+  coordinate filenames.
+- **Manifest:** one combined manifest at the source root listing
+  every page, with each entry's `path` pointing at its producer's
+  output location. Different producers write to different
+  subdirectories; the manifest unifies them. Manifest paths are
+  relative to the source root (`checkout/index.html`), and the
+  reference producer only auto-derives nested `index.html` files from
+  their parent directory. Use explicit `--page page_id=path` mappings
+  when multiple files would infer the same page id.
+- **`prepare-build` behavior:** when a manifest is present it
+  governs every mapping — including pages whose path points into a
+  template-stock subdirectory. Operators with mixed sources should
+  always write a manifest rather than relying on filesystem
+  fallback (which is all-or-nothing). The manifest path remains source
+  provenance; `source_html.pages[].page_kit` carries the target Page Kit
+  file, route, CPK `page_type`, and frontmatter projection.
+- **Doctor behavior:** per-page error variants fire based on each
+  page's `design_source.type`. A figma-marked landing page with no
+  manifest entry gets the Figma error; a template-stock checkout
+  page (no `design_source`) gets the generic error.
+- **When to use:** the realistic case for most live campaigns once
+  the design-Figma + template-stock-commerce-surfaces split is
+  routine.
+
+## Existing campaigns
+
+A campaign repository that already exists — built or not, with or
+without Campaigns OS artifacts — enters through
+`campaigns-os standardize --target <repo>`, not through the build
+pipeline. It is a read-only audit: it classifies each campaign root,
+inventories source and runtime contracts, judges SDK versions and
+checkout bindings against the bundled contracts, and, when a built
+`_site` and a known template family exist, runs the built-output
+doctor. The flags, exit codes and the slug-resolution rules are in
+[campaign-standardization-report.md](./campaign-standardization-report.md).
+Its findings name the entry point above the campaign should re-enter
+through when repair is needed.
+
+## Out of the consumer's hands
+
+The build pipeline doesn't care which agent wrote the source HTML;
+it only cares that the contract (filesystem location, manifest
+shape, `design_source` shape) is honored. New entry points (Penpot,
+Sketch, plain Markdown converters, etc.) slot in by:
+
+1. Adding a `design_source.type` value (open-string, accepted today).
+2. Emitting source HTML at the source root.
+3. Emitting a `source-html-manifest/v0` manifest if the entry point
+   wants doctor's manifest-aware code path; otherwise relying on
+   filesystem fallback like template-stock and hand-authored.
+
+No campaigns-os code change is required to add a new entry point if
+the producer honors the existing contracts. Doctor's error wording
+gets an additional `design_source.type` variant when a new entry
+point ships, but that's a polish step, not a gate.

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.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.60.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.62.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.60.0`
+Supported surface at generation time: `1.62.0`
 
 ## Forward compatibility
 

package/docs/polish-evidence.md

@@ -54,7 +54,7 @@ per-field problem line.
 
 | Field | Accepted shape (presence check) |
 |---|---|
-| `visual_review` | **Object** with a `screenshots` array (accepted aliases for the array key: `screenshot_paths`, `paths`, `urls`) containing at least one non-empty string, plus package-generated `page_load`. A bare string, an object without a screenshot array, or an empty array all fail. The gate's shape check accepts a single screenshot entry; the `next-campaigns-polish` responsibility bar is desktop **and** mobile captures of the key commerce anchors — record both. Never hand-author `page_load`. |
+| `visual_review` | **Object.** `record polish` needs the package capture record `captures`, which every `polish capture` run at this version writes. That record must be package-produced, bound to the current build and intact, and every image it claims must be a full-page capture at the capture's own viewport width at pixel ratio 1. Every planned route must have at least one rendered build cell with a captured actual shot; an all-skipped or all-failed build side does not qualify. Screenshot paths written by an agent are not read. After upgrading, run `polish capture` again before `record polish`. A Polish record written by an earlier version, without `captures`, is still read as before: a `screenshots` array (aliases `screenshot_paths`, `paths`, `urls`) with at least one non-empty string. Never hand-author `page_load` or `captures`. |
 | `brand_review` | Non-empty object (semantic checks in §3 apply: `favicon`, `brand_bleed`). |
 | `checkout_review` | Non-empty object (semantic checks in §3 apply: `field_labels`, `bump_compare_price_rule`). |
 | `template_residue_review` | Non-empty object/array/string (semantic check on `starter_favicon` in §3). |
@@ -121,6 +121,42 @@ The size check covers `<img>` elements in the page, including those inside open
 
 **Readability.** `polish capture` also measures text contrast on every page under `_site/<slug>/` (up to 128 pages per run), at desktop (1440×1200) and mobile (390×844) widths, device pixel ratio 1, including campaigns whose pages are all template stock: the Polish route plan now covers the mapped pages plus every built page, while the page-load capture keeps its own page set. On a campaign with no mapped pages, `polish capture` measures readability, prints the page-load message as a warning, and exits successfully. The text it reads: purchase, accept and decline controls; submit buttons and submit-type inputs; SDK action controls; bundle cards (names, prices, badges and the card selected at load); order bumps; prices; checkout labels and placeholder hints; and other body text. Ratios follow WCAG 2.x and are compared unrounded: 4.5:1 for normal text, 3:1 for large text (at least 24 CSS px, or at least 18.66 CSS px at weight 700 or more; semibold does not qualify). Colours in any CSS Color 4 form the browser reports are converted to sRGB; values outside sRGB are clipped and marked. Backgrounds are composited through transparent layers. SVG text is measured with its fill colour, and placeholder hints with their own colour, size and weight. Gradients, background images, pseudo-element backgrounds, a `::first-line` or `::first-letter` style that changes the text's colour, background or opacity, overlapping positioned layers or images (and the shapes of an SVG drawing under its text), text clipped to a background, colours that cannot be read (including a text fill colour, and an SVG fill that is not a plain colour or is combined with a stroke), and controls marked disabled only by the SDK's `next-disabled` class produce a review result with a reason and a crop; so do opacity, filters, blend modes and masks on the text or on any element around it. `clip-path` is ignored. Disabled controls (`disabled` or `aria-disabled="true"`) are listed as excluded (inactive control) and are never accepted; `readonly` is not disabled. Polish measures the states present when the page loads — default, selected, active, and open panels — without clicking, scrolling or typing. Text that has not rendered, controls still loading, controls hidden at load, text supplied by CSS `content`, selection states and collapsed panels not present at load, text inside closed shadow roots or cross-origin frames, pages measured before the SDK, stylesheets or fonts were ready, and pages not captured are listed as unexercised. Overlapping layers are detected by box intersection: a layer the page paints over text in another way is not detected. A ratio under the requirement is a warning. Warnings never block Polish or change readiness. The probe reads the page without changing it, and adds at most about five minutes of work per run; pages it could not reach in that time are listed as unexercised. The stored measurements are re-derived on every read, and the page set, widths and campaign are checked against the current build; but the colours the browser reported are tamper-evident only, like other Polish captures. Readability and media weight results read as stale when the built output differs from the recorded build, even before a new `record build`.
 
+**Layout conventions.** In the same pass as readability, at the mobile width, `polish capture` checks two layout conventions from the `layout_conventions` block of `contracts/template-brand-contract.shared-commerce.v0.json`. Each reports as a `layout.conventions` row, keyed by convention, on every built page. The first, `floating_cta`, covers floating CTA containers. A floating CTA container is the nearest box around a visible link or button whose computed position is `fixed` or `sticky`. Headers, navigation, dialogs, the announcement bar, boxes that hold a visible form field, and boxes taller than half the viewport do not count. Such a container should hold its control alone: one link or button and no other visible text. A container with a second control, or with text outside its control (rendered or CSS-generated), is a `floating_cta_extra_content` warning that names the container, its controls and up to ten of the other text elements. The record keeps the container's box and each control's box. The second, `cta_label_size`, reads the readability record's own measurements. Every rendered, enabled text element of a purchase or accept control or a submit button (readability roles `add_to_cart`, `upsell_accept` and `submit_control`) should be at least 16 CSS px. A smaller one is a `cta_label_too_small` warning with its measured size. A CTA that is a plain link with no SDK action reads as body text in the readability record and is not checked for label size. A page that meets both conventions reads pass. Both warnings can be accepted with `checkpoint accept`; neither blocks Polish, changes readiness, or reads the merchant's copy. A readability record captured before this check holds no layout, and the check reads `not_captured_by_this_version` until the next `polish capture`.
+
+**Element parity.** For each page built from provided source HTML, `polish capture` reads the source HTML render and the built page that the package capture already makes, with the same browser at the same width, height and pixel ratio (desktop 1440×1200 and mobile 390×844). On both it reads every visible element that holds text: its box, its text, its computed font family, size, weight, style, line height, letter spacing and text transform, and its text and background colour. Elements are matched by their text: exact matches that occur once on each side first, then the nearest exact match after removing the page's median offset, then text split across child elements, then close wording (at least 60% of words shared). A design text of four or more characters is reported missing only when it appears nowhere in the built page's visible text; where part of the built page could not be read (very long text, closed components, frames), it is listed for review instead. Differences become warnings when they exceed: 6 px for horizontal position, width and height, and for the vertical gap to the previous matched element (so one inserted band reports once, where the layout changed); 0.6 px font size; 2 px line height; 0.2 px letter spacing; 3 of 255 in any colour channel; any change of font family, weight, style or text transform. A web font that loaded for the source but not for the build is a warning even when the CSS names the same family. The font each glyph was actually drawn with is not read, and the handoff says so. Colour that cannot be measured on either side is listed for review. A source with no text, a source or build that could not be rendered or was not ready in time, a width or pixel-ratio mismatch (never resized), a source file that differs from the one recorded at intake, pages over the run's limits (1 500 elements per page, 32 pages, 200 font faces, about one minute of probing), and pages with unread parts are listed as unexercised or for review, never as a match. The probe's time counts against the package capture's own time budget. Both measurements are saved as local, git-ignored files, hashed and bound to the record. That makes an edit to part of the evidence detectable, but a process that rewrites the files and both records consistently is not detected. The source is measured again on every capture, so changed stylesheets or fonts are always seen; an unchanged source produces the same saved file. Warnings can be accepted with `checkpoint accept` and lapse when the measured values change; they never block Polish or change readiness. The comparison uses the HTML export as the design; a design file recorded for the page is not read by this version.
+
+### Package captures and design comparison
+
+After its existing page-load and readability work has finished and been recorded, `polish capture` takes full-page captures of every mapped page at desktop (1440×1200) and mobile (390×844), device pixel ratio 1, in a freshly loaded state with no scrolling or interaction. It also renders each page's source HTML from the source folder with the same browser at the same size. This visual pass uses its own browser instances, so its failures never change page-load or readability evidence.
+
+The source is served read-only from a local address, in a browser instance that can reach only that address. Requests and WebSocket connections to anything else are blocked and counted, other connections are refused by the local server, and no host name is looked up. Nothing from the source render leaves the machine.
+
+Each render waits for web fonts (up to 3 seconds) and for `[data-next-await]` elements to clear (up to 5 seconds) before either capture. The first capture is unchanged. The second differs only by its stabilization treatment: it stops animations and transitions, hides the caret, and masks SDK timers and prices. Timeouts are recorded, never hidden.
+
+Images are stored under `.campaign-runtime/polish/captures/` and `.campaign-runtime/polish/diff/`, named by their SHA-256. Each folder gets its own `.gitignore` the first time an image is written, so the images stay out of the repository even in a campaign set up by an earlier version. Old images are not deleted.
+
+Source screenshots recorded in the Design Source Package are opened and checked. The PNG structure is read without dependencies, and the image is fully decoded when the optional `pngjs` package is installed. An image whose declared size exceeds 17.28 million pixels (1440 × 12,000) is not decoded and is reported as not verifiable. Each screenshot is recorded as header-checked, decoded, or not verifiable, with its SHA-256 (computed when none was recorded) and identity.
+
+A reference or source page that is the build's own output is reported as self-referential. That means a file inside `_site/` or `.campaign-runtime/`, a file identical to a Polish capture or a built page, or the campaign's own Page Kit page. Accepting that warning records the output as a revision baseline, not as proof that the page matches the design. A self-referential file that also fails verification cannot be accepted. A reference whose origin cannot be established is listed for review.
+
+Compatible pairs are compared with the optional `pixelmatch` package:
+- images are padded, never resized;
+- width and height differences are reported;
+- a heatmap is written;
+- the most different areas are listed per section.
+
+Sections are elements marked with `data-section`, or, when a page has none, `section`, `header` and `footer` elements with an `id`. Each section is cut from each image at its own position, so a taller section above it does not shift the comparison. A section missing or repeated on one side is reported as not comparable. Areas masked on either side are excluded from both sides. When a page is taller than the 12,000-pixel capture limit, the whole-page figure is not computed, and only sections inside both captures are compared.
+
+Source screenshots are compared as whole images only, and only when their width and recorded `scale_factor` match the capture. Otherwise the comparison is reported as not supported. Their stabilization, state, crop and viewport height are not recorded, and each comparison says so.
+
+The comparison is a diagnostic for a reviewer: it is listed for review, it never passes or fails Polish, and it never changes readiness. When `pngjs` or `pixelmatch` is not installed, captures are still taken and the comparison is listed as unavailable. Animations driven by script and content below the fold that loads on scroll are limits of the comparison. The visual pass adds at most five minutes per run, and pages it could not reach in that time are listed as unexercised.
+
+The stored comparison figures are tamper-evident only, like other Polish captures. The images are re-checked on every read against their SHA-256 and against the pixel size recorded for them.
+
+Template-stock pages are outside the mapped capture plan and produce no visual rows.
+
+Hand-deleting `captures` reverts later reads to the legacy rule, but a new completed `record polish` still refuses. A fully reconstructed, internally consistent record can pass; the checksum is tamper evidence, not authorship proof. Pixel metrics and geometry are range-checked rather than recomputed on every read.
+
 ### Collector response records (the producer's wire form)
 
 Inside the producer, the browser adapter's CDP collector emits one
@@ -469,6 +505,8 @@ deliberately). Waived runs pass with status `waived`, never silently.
 
 ## 6. Complete passing example
 
+Run `polish capture` first to attach `page_load` and `captures`; the example omits these package-owned records. Screenshot paths below document review locations and cannot satisfy a new completed record.
+
 The hand-authored portion below is completed first. Run `campaigns-os polish
 capture` to attach the versioned `visual_review.page_load` object; that package
 artifact is intentionally not reproduced as editable JSON here.
@@ -520,6 +558,8 @@ stack).
 
 ## 7. Recording with `record polish`
 
+After upgrading, run `polish capture` again. A completed record requires its current `captures` record; leave it out of the evidence file so the captured value is carried forward. Existing records without `captures` retain the legacy read rule.
+
 ```bash
 campaigns-os record polish --packet <campaign-runtime.build.json> --evidence <polish-evidence.json> [--report <json>] [--dry-run] [--json]
 ```
@@ -531,7 +571,7 @@ any other key is refused:
 | Key | Required | Written to |
 |---|---|---|
 | `status` | no (default `completed`) | `stages.polish.status`; `completed`, `completed_with_warnings`, `blocked` or `skipped` |
-| `evidence` | for `completed*` | `stages.polish.evidence`, the seven categories of §2. Leave out `visual_review.page_load`: the value `polish capture` recorded is kept, and a file that carries one is refused. Without it, a `blocked` or `skipped` record keeps the evidence already on the report. |
+| `evidence` | for `completed*` | `stages.polish.evidence`, the seven categories of §2. Leave out `visual_review.page_load` and `visual_review.captures`: the value `polish capture` recorded is kept, and a file that carries one is refused. Without it, a `blocked` or `skipped` record keeps the evidence already on the report. |
 | `blockers` | for `blocked` only | `stages.polish.blockers`: a non-empty array of `{"code", "message"}` objects. |
 | `skip_reason` | for `skipped` only | `stages.polish.skip_reason`: a non-empty string. |
 | `repair_loop_defect` | no | `report.theme.repair_loop_defect`: `null`, or the first brand-layer repair-loop defect as an object (`code`, `message`, `path`, `detail`). A non-null defect needs a recorded `report.theme`. |

package/docs/progress-snapshots.md

@@ -65,10 +65,13 @@ rename; a live process is never evicted. A lock directory with no owner record
 a second. If one is found, or if recovery itself is interrupted, capture fails
 closed and the warning names the affected `.allocation-lock` directory: stop
 all Campaigns OS writers for that target, then remove that directory before
-retrying `next`. A file or other non-lock entry at the lock path is named in
-the warning and never removed: move it out of the way. Do not remove a lock
-while a writer is active. Do not run an
-older Campaigns OS release against the same target at the same time.
+retrying `next`. A file, an unreadable directory or other non-lock entry at
+the lock path is named in the warning and never removed: move it out of the
+way. Do not remove a lock while a writer is active. Run one Campaigns OS
+release against a target at a time: a lock held by a live process of another
+release (its owner record has no `lock_format`, or a different one) is refused
+at once and the warning names that process. Two releases that start at the
+same instant are not detected.
 
 An unchanged projection reuses its ID, timestamp and sequence. Identity
 changes start a new stream. Each local scope retains at most 32 snapshots and

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

@@ -134,6 +134,21 @@ waiver commands keep them strict. Progress
 snapshots record a carried-forward gate as `not_applicable`, because their
 schema has no carried-forward state.
 
+### Polish advisory for a page-only change
+
+After launch, a change that touches only some pages' HTML and leaves checkout,
+commerce markup, routes, scripts and the campaign's Page Kit config alone is a
+page-only change ([what a change owes](campaigns-os-build-flow.md#what-a-change-owes)).
+On any target, its stale Polish evidence (`polish.evidence_missing` after
+`record build`, `polish.stale`, `polish.output_drift`, and the
+`polish.hidden_eager_media.capture_stale` checkpoint) is carried forward with
+the `page_only_change` policy. Doctor reports it as a warning starting
+"Advisory for a page-only change"; `next` and `record deploy` move past Polish;
+QA records it as a `skipped` row, so it does not hold the verdict to
+`ready_with_exceptions`. A Polish recorded as blocked, incomplete or
+self-certified stays blocking, and so does a stage a brief or spec change
+requires.
+
 ## Resolve
 
 Use resolve before a full run:
@@ -382,6 +397,67 @@ currency is recorded as `evidence.currency` on the entry page's
 `http:<page_id>` assertion; an entry URL that does not parse gets no currency,
 and its row records `evidence.currency_not_applied` with the reason instead.
 
+The run also checks that the currency took. Campaign Cart falls back to the
+campaign's default currency when the requested one is not available, so a page
+can load with `?currency=GBP` and still take a USD order:
+
+- Each test order gets a `browser-order-currency:<path>` row comparing the
+  created order's `currency` (read from the order API response) with the run
+  currency. An order in any other currency fails as a blocker, and so does a
+  verified order whose currency was not recorded. The row's evidence is
+  `{ requested, order_currency }`.
+- Automatic commercial parity (below) asks the calculate endpoint for expected
+  totals in the run currency, in place of the Map's `campaign.currency`. When
+  the endpoint answers in another currency, the campaign does not price in the
+  run currency: a `commercial-currency:<RUN>:<ANSWERED>` row (family `pricing`)
+  fails as a blocker, and the commercial report lists the
+  `calculate_currency_mismatch` issue, so its status reads `incomplete`. The
+  row's id names the answered code upper-cased, one row per answered currency,
+  and it is written even when the verdict's assertion budget is used up.
+- Commercial parity reads prices from each page's source HTML, where a bound
+  price such as `data-next-display="bundle.main.price"` holds the authored
+  fallback text in the Map's `campaign.currency` (Campaign Cart replaces it at
+  runtime). When the run currency is not the Map's `campaign.currency`, those
+  price and recurring-price claims are not compared with the run-currency
+  totals: they count as unresolved, and the commercial report records
+  `unresolved_money_claims_reason: "static_source_not_in_run_currency"`. A
+  correctly built multi-currency page gets no `price-claim-mismatch` warning,
+  and the commercial status reads `incomplete` instead of `pass`. With
+  `--currency` set to the Map's own currency, the claims are compared as
+  before.
+
+Either blocker makes the verdict `blocked` and the command exit `4`. Without
+`--currency` neither row is written and expected totals use
+`campaign.currency`, as before.
+
+`--currency` sets the currency only. Test orders still ship to the address the
+`--test-*` flags give, a US address by default (see
+[Test customer and shipping address](#test-customer-and-shipping-address)). A
+non-USD `--currency` on a run that places orders, with no `--test-country`,
+prints a warning on stderr and the run goes ahead. Only the missing flag is
+checked: a currency such as EUR covers many countries, so an explicit
+`--test-country` is taken as meant. `qa run --site` takes `--currency` the same
+way and tags the slug's entry page.
+
+`--page <page_id>` (repeatable) checks only the named pages. It pays the QA a
+page-only change owes: `doctor --ci` and `next` name the changed pages by
+their route ids (`upsell1` for `upsell1/index.html`), and the CampaignSpec page
+id is accepted too. It needs `--packet`, places no test orders (it refuses
+`--test-order` and `--legacy-api-test-order` other than `off`, and
+`--vendor-beacons`), and refuses before checking anything when the
+output on disk is not the recorded build (run `record build` first), when the
+change since the build QA reviewed touches commerce, when a changed page is
+left out, when the QA it would extend did not complete (a blocked full run
+owes a full run), or when QA's inputs (the brief's `qa_policy` and the
+CampaignSpec) changed or cannot be confirmed current. Every other page gets a
+`page-scope:<page_id>` row, `skipped` with `outside_page_scope`. The QA stage
+it records carries `evidence.page_scope` (`pages`, `owed_pages`,
+`base_build_fingerprint`) and keeps the `purchase_proof` of the full run it
+extends. Its `evidence.qc_results` holds the rows for the scoped pages only,
+so until the next full run the QC handoff coverage reports the earlier full
+run's other QA checks (order paths and tracking among them) as not captured.
+QA already recorded in full for the current build is re-run without `--page`.
+
 ### Automatic commercial parity
 
 When the CampaignSpec has enabled pages with package rows, the same `qa run`
@@ -432,7 +508,11 @@ readback consumes. It is written for every finalized disposition, blocked
 included: the sidecar records what QA concluded, it is not a pass mark. A run
 that dies before verdict finalization or fails local validation never touches
 an existing sidecar. Packet-less runs (`--site`, raw map-id) have no packet
-home and write no sidecar.
+home and write no sidecar. For a project's second and later funnels the sidecar
+is `.campaign-runtime/funnels/<route>/qa-verdict.json` beside that funnel's
+packet, the runtime directory its `assembly.runtime_dir` names (see
+[Several funnels in one project](build-packet.md#several-funnels-in-one-project));
+`qa promote` and `qa publish` read and write the same file.
 
 The sidecar is an allowlist **projection** of the full verdict, same schema
 (`1.0`), stamped with its own `generated_at` at promotion time. Full verdicts
@@ -1144,7 +1224,7 @@ What the diff asserts (BLOCKER unless noted):
 For a real SDK 0.4 migration example that required typed-card post-purchase
 traversal, persisted-order price verification, receipt-context analytics, and
 independent order readback, see
-[SDK 0.4 Migration Proof Case Study](sdk04-migration-proof-case-study.md).
+[SDK 0.4 Migration Proof Case Study](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/sdk04-migration-proof-case-study.md).
 
 ## Parity capture (fixture-driven migration proof)
 
@@ -1329,6 +1409,80 @@ controls on an ordinary or unknown page remain blockers; they are not treated
 as evidence that a receipt was reached. Cross-origin handoffs count as terminal
 navigation, but not as Campaigns OS receipt rendering or persisted-receipt proof.
 
+### Analytics vendor beacons (`--vendor-beacons live`)
+
+A test order is a real purchase on the page, so the page reports it to every
+analytics vendor the campaign loads. To keep test orders out of vendor data, a
+`qa run --test-order` run answers the vendors' beacon requests locally. A
+beacon is the request a vendor script sends to report a page view or an event,
+as opposed to the loader, the request that downloads the vendor script. Every
+browser context the run opens (page checks, analytics capture and the orders)
+answers a request to a listed beacon endpoint with an empty `204` response, so
+nothing reaches the vendor. Those contexts also block service workers, because
+a request a page's service worker makes on the page's behalf would bypass the
+local answer. Loader scripts load normally: a blocked loader would leave the
+vendor script undefined, and the page would send nothing to observe.
+
+| Vendor | Beacon endpoints answered locally | Loaders that still load |
+|---|---|---|
+| GA4 (`ga4`) | `*.google-analytics.com/g/…`, `analytics.google.com/g/…`, `stats.g.doubleclick.net/g/…`, `www.google.com/g/collect` | `www.googletagmanager.com/gtag/js` |
+| Meta (`meta`) | `www.facebook.com/tr`, `www.facebook.com/privacy_sandbox/…` | `connect.facebook.net` |
+| TikTok (`tiktok`) | `analytics.tiktok.com/api/v2/…`, `analytics-ipv6.tiktokw.us` | `analytics.tiktok.com/i18n/pixel/…` |
+| Snap (`snap`) | `tr.snapchat.com`, `tr6.snapchat.com`, `tr-shadow.snapchat.com` | `sc-static.net` |
+| Pinterest (`pinterest`) | `ct.pinterest.com/v3/…`, `/user/…`, `/stats/…` | `s.pinimg.com`, `ct.pinterest.com/static/…` and `/ct.html` |
+| Taboola (`taboola`) | `trc.taboola.com` | `cdn.taboola.com` |
+| Triple Whale (`triplewhale`) | `api.config-security.com` (all but `/first`), `api.whaledb.io/keep-alive` | `api.config-security.com/first`, `conf.config-security.com` |
+| AppLovin Axon (`axon`) | `b.applovin.com/v1/pixel` | `s.axon.ai`, `c.albss.com`, `res4.applovin.com` |
+
+Each endpoint was read from the vendor's public loader script or public
+documentation; the source is recorded per vendor in
+`src/qa-vendor-endpoints.mjs`. Two vendor keys are not intercepted, and the
+verdict names them:
+
+- `northbeam`: its beacon host could not be confirmed (the loader is per client
+  and the public docs name no beacon host), so Northbeam still receives what
+  the page sends it, test purchases included.
+- `gtm`: Google Tag Manager sends nothing of its own. The tags it loads send to
+  their own vendors, held back only when that vendor is in the table. A GTM tag
+  for any other vendor (Google Ads, an affiliate pixel) still sends.
+
+`qa parity` orders are not intercepted.
+
+Every request to a listed endpoint is recorded, and the verdict carries one
+informational row, `browser-test-order:vendor-beacons` (status `pass`, severity
+`info`). Its `evidence` gives, per vendor seen, the request count, whether one
+of the requests named a purchase event (`purchase_seen`; `null` for Axon, whose
+event field could not be confirmed), and the ids, event names and endpoints
+(origin and path only, never a query string); `configured_not_seen` lists the
+vendors the CampaignSpec analytics block declares that sent nothing to a listed
+endpoint; `configured_not_observable` lists the declared vendors with no listed
+endpoint (GTM, Northbeam), which the row cannot see either way; and
+`not_intercepted` lists the two vendors above with the reason for each (with
+`live`, every vendor). The row is evidence only. A
+request the page sent proves the page sent it, not that the vendor received it,
+so it never counts as vendor purchase proof and never blocks the run. Purchase
+proof stays with `analytics-correctness:purchase-fires` (the dataLayer
+purchase, a Meta Purchase pixel request, or a GA4 purchase hit); with
+interception on, the Meta and GA4 requests behind it are still observed, just
+answered locally. The same requests feed the analytics inventory and parity
+legs as tag fires.
+
+To send the beacons to the vendors, pass `--vendor-beacons live`. `live` is
+the only value; any other value is refused before anything runs, and so is the
+flag on a run without `--test-order`, where it would change nothing. The row
+then records the requests as sent.
+
+```bash
+npm run campaigns-os -- qa run \
+  --packet campaign-runtime.build.json \
+  --test-order common \
+  --vendor-beacons live
+```
+
+Do not hold beacons back with `?ignore=true` on the campaign URL: from SDK
+0.4.42 it stops the SDK's `dl_*` events entirely, so the run would prove no
+purchase event at all.
+
 ### Purchase-proof coverage (`--test-order off` is a diagnostic)
 
 A QA run finalizes a verdict and records a terminal stage status whether or not
@@ -1959,6 +2113,41 @@ that died mid-submit. QA reports it on the path's `browser-test-order` row as
 (or `--test-email`), or wait. The shipping address is not part of the match, so
 changing `--test-address1` does not help.
 
+### Test customer and shipping address
+
+The runner fills the checkout as one test customer. Every field has a default,
+and each has a flag:
+
+| Flag | Default | Field |
+|---|---|---|
+| `--test-first-name` | `QA` | first name (shipping and billing) |
+| `--test-last-name` | `Playwright` | last name |
+| `--test-phone` | empty | phone, filled only when the checkout has the field |
+| `--test-email` | see above | email |
+| `--test-country` | `US` | country select (value or label, such as `GB`) |
+| `--test-address1` | `1600 Amphitheatre Pkwy` | street address |
+| `--test-city` | `Mountain View` | city |
+| `--test-province` | `CA` | state, province or region select (value or label) |
+| `--test-postal` | `94043` | postal code |
+
+The billing fields get the same values when the checkout shows them. To order
+in another market, pass `--test-country` and all four address flags for a real
+address in that country, since the address defaults are a US one, and pass
+`--currency` for that market's currency: the country flag does not change the
+currency. A UK run looks like this:
+
+```bash
+npm run campaigns-os -- qa run --packet campaign-runtime.build.json \
+  --currency GBP --browser --test-order common \
+  --test-country GB --test-address1 "<street>" --test-city "<city>" \
+  --test-province "<option from the province select>" --test-postal "<postcode>"
+```
+
+The province select is a required step. A checkout that shows no province
+select for the chosen country fails the path at that field
+(`Missing checkout select: province`); place those orders by hand on the
+market-pinned page (`?currency=<code>&country=<code>`).
+
 The browser driver intentionally behaves like a user:
 
 - package selection uses rendered `[data-next-package-id]` controls when
@@ -2116,10 +2305,15 @@ npm run campaigns-os -- doctor --built ../my-campaign-repo --family arjuna --emi
 
 # QA a built, served campaign with no packet/spec.
 npm run campaigns-os -- qa run --site ../my-campaign-repo --base-url http://localhost:8080 --family arjuna --browser
+
+# The same, entering the slug's first page in GBP.
+npm run campaigns-os -- qa run --site ../my-campaign-repo --base-url http://localhost:8080 --family arjuna --slug my-slug --currency GBP
 ```
 
 `--family` is required (the residue gates need the family's brand contract).
-`--slug` selects the campaign when `_site/` holds more than one. With no theme
+`--slug` selects the campaign when `_site/` holds more than one. `--base-url`
+can be the served site origin or the campaign root: QA adds the campaign's slug
+when the URL does not already end in it, so pages resolve under `/<slug>/`. With no theme
 artifacts the theme gate resolves to `not_applicable` (non-blocking), so the
 placeholder-text blocker and the other residue gates still run. The emitted
 minimal packet is marked `_synthesized` — it points doctor/QA at the built