@nextcommerce/campaigns-os 1.59.0 → 1.61.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.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.59.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.61.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.59.0`
+Supported surface at generation time: `1.61.0`
 
 ## Forward compatibility
 

package/docs/polish-evidence.md

@@ -37,7 +37,7 @@ The gate only applies once assembly is complete
 | `status` | `stages.polish.status` | Must start with `completed`. `blocked` → `polish.blocked`; anything else → `polish.evidence_missing`. |
 | `performed_by` | `stages.polish.performed_by`, `stages.polish.command_identity`, `evidence.performed_by` | Must be exactly `next-campaigns-polish`. Anything else (including missing) → `polish.self_certified`. |
 | `commands` | `stages.polish.commands` and/or `evidence.commands` | Must NOT mention a build command anywhere — a polish record that ran build is self-certification → `polish.self_certified`. The matcher is exactly the strings `next-campaigns-build` and `campaigns-os next build` (case-insensitive); other build tooling (e.g. page-kit's `campaign-build`) is not matched. |
-| `source_build_fingerprint` | `stages.polish.source_build_fingerprint` or `evidence.source_build_fingerprint` | Required, and must equal the current build fingerprint (`stages.assembly.build_fingerprint`, falling back to `stages.assembly.artifact_fingerprint`, `report.build_fingerprint`, `report.artifact_fingerprint`). Missing → `polish.source_build_fingerprint_missing`; different → `polish.stale`. Doctor, QA, and `polish capture` also recompute the fingerprint from the built output under `_site/<slug>/` (algorithm in `docs/build-packet.md`); when the output no longer matches the recorded value the gate is `polish.output_drift` with `current_output_fingerprint` and a `rerun_build` action, whatever the recorded string says. |
+| `source_build_fingerprint` | `stages.polish.source_build_fingerprint` or `evidence.source_build_fingerprint` | Required, and must equal the current build fingerprint (`stages.assembly.build_fingerprint`). Missing → `polish.source_build_fingerprint_missing`; different → `polish.stale`. Doctor, QA, and `polish capture` also recompute the fingerprint from the built output under `_site/<slug>/` (algorithm in `docs/build-packet.md`); when the output no longer matches the recorded value the gate is `polish.output_drift` with `current_output_fingerprint` and a `rerun_build` action, whatever the recorded string says. |
 | `source_package_material_fingerprint` | `stages.polish.source_package_material_fingerprint` or `evidence.source_package_material_fingerprint` | Only enforced when the report carries a current Design Source Package material fingerprint (`design_source_package.material_fingerprint` or equivalents). Missing → `polish.source_package_material_fingerprint_missing`; different → `polish.source_package_stale`. |
 | `completed_at` | `stages.polish.completed_at` or `evidence.completed_at` | Required non-empty timestamp string → else `polish.completed_at_missing`. |
 
@@ -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,40 @@ 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`.
 
+**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 +503,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 +556,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 +569,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/qa-and-test-orders.md

@@ -381,6 +381,14 @@ default currency. The persisted verdict redacts every URL query, so the
 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.
+`--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.
 
 ### Automatic commercial parity
 
@@ -1144,7 +1152,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)
 
@@ -1959,6 +1967,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 +2159,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