@nextcommerce/campaigns-os 1.60.0 → 1.61.0

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.60.0",
+  "surface_version": "1.61.0",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -58,7 +58,7 @@
       "sha256": "d524003184131398dc15fdb84385af1be0de0c69d6c5ede7278689a5b6101b81"
     },
     "schemas/campaign-design-source-package.v0.schema.json": {
-      "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
+      "sha256": "ecb8fd534977826541aa7110dad3483b7b9215dd60ed30b6370083848b957f13"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
       "sha256": "625a6f2ed6bee726f9cddad750e64a54a7e03744c777f5a70afe4a39afdd9848"
@@ -112,7 +112,7 @@
       "sha256": "41ff370de4395149781d7e8c4ad6d7d4e2f896eb2030944399d36f1237726a20"
     },
     "schemas/source-html-manifest.v0.schema.json": {
-      "sha256": "841c1f884260ce3eb3ddb518960a127bc915992a9539c818e5986ce156acff1f"
+      "sha256": "58bc98b3fd07c87c6ba92d29b26941ca97200ea433d73f7418966f679841df49"
     },
     "schemas/campaigns-os-progress-snapshot.v0.schema.json": {
       "sha256": "ef31b4f20e39dfc1614dd4b45e4cf1692a51760b008cb51d133659307bd2a954"
@@ -121,7 +121,7 @@
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
     },
     "schemas/campaigns-os-readback.v2.schema.json": {
-      "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
+      "sha256": "443676656a7d0db4c8c45301dad5c925cd1b03d4d0e3dccdf0132d9a4e6005f2"
     },
     "contracts/effects.v1.json": {
       "sha256": "9c1d69e44eab7403ca3ff80f850214d89b0a02fdc51544beef37dbd0a653eeaa"

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

@@ -55,7 +55,7 @@
       },
       "asset_pin": {
         "repo": "NextCommerceCo/campaign-cart-starter-templates",
-        "sha": "3987b18a356cb961b06c94b2035622bafe938316",
+        "sha": "b38343e85a05ec2fe949e13e783057d4c717a8d6",
         "path": "src/<family>/assets/<asset>",
         "note": "asset_sha256 is the sha256 of each shipped starter asset at this commit (the commerce-surface-catalog _synced_from_sha pin; the bytes are identical across every family). A served asset whose bytes hash to the shipped value is the untouched starter asset and counts as residue even though its markup names no method; different bytes mean it was edited in place. check-template-doctrine verifies these hashes against the pinned checkout."
       },

package/docs/access-model.md

@@ -0,0 +1,20 @@
+# Access Model
+
+Campaign developers should not need access to the private Campaigns OS runtime development repo.
+
+This repo is the developer-facing surface:
+
+- docs
+- schemas
+- examples
+- starter-template contract snapshots
+- agent skills
+- Build Packet doctor
+- checkpoint wrappers
+- issue templates
+
+Private platform/runtime development remains outside this repo. Do not copy private repo paths, client-specific examples, secrets, dashboard internals, or unpublished platform mutation procedures here.
+
+## Distribution
+
+This repo should stay suitable for public or partner access. Private runtime details, private repo paths, secrets, and client-specific implementation notes belong outside this surface.

package/docs/brand-theme-bridge.md

@@ -37,12 +37,66 @@ the accent fallback and the warning asks the operator to confirm it.
 ```text
 .campaign-runtime/theme/theme-report.json
 .campaign-runtime/theme/brand-theme.css
+.campaign-runtime/theme/brand-fonts.css   (only when the source ships brand faces)
 ```
 
 The generated CSS is v0 root-variable-only. It can override next-core custom
 properties such as `--brand--color--primary` and
 `--brand--color--cta-primary`, but it must not emit selectors, `data-next`
 selectors, payment/package/cart selectors, JavaScript, or remote URL fetches.
+The one exception is a `:root, body` block for the font-family tokens (see
+Typography below).
+
+### Typography
+
+Commerce pages keep the design's type, not the template's system stack.
+Inspection reads every CSS file the source pages link:
+
+- the `@font-face` rules the source ships;
+- which family its headings use (`h1`–`h3`, then `heading`/`title` classes);
+- which family its body copy uses (`html`, `body`, `p`, or the class a
+  stylesheet scopes itself under, such as the importer's `.cc-import`);
+- which family its buttons use, and the button `border-radius`.
+
+`var()` references resolve through custom properties on `:root`, `html`, `body`
+and that scope class, where Shopify themes keep `--font-body-family` and
+`--buttons-radius`. A family is mapped only when the source ships a face for
+it: a family the page can't load would only change the fallback, so it is
+left out, reported as a `theme.typography.face_unavailable` warning, and
+listed in the theme report's `typography.unavailable`.
+
+| Source | next-core token |
+| --- | --- |
+| heading family, then the generic the source gave it | `--_text---font-family--heading` |
+| body family (else the button family), then its generic | `--_text---font-family--primary` |
+| button radius (`0`, or one to four lengths or percentages) | `--radius-size--buttons` |
+
+A button radius in another form (`10px / 20px`, an unresolved `var()`) is not
+mapped and is listed in `typography.radius_rejected`.
+
+The targets are in the `typography` block of
+`contracts/brand-theme-target-tokens.next-core.v0.json`. next-core re-declares
+both font-family tokens on `body` inside its 991px, 767px and 479px media
+queries, so a `:root` value alone holds only on desktop. The generator emits
+them in a `:root, body` block. `brand-theme.css` loads after next-core, so its
+`body` declaration wins at every width.
+
+`brand-fonts.css` holds only `@font-face` rules for the mapped families. It
+always ships `font-display: swap`, whatever the source declared. A face the
+source declares once per format keeps every file, in source order. Its URLs are relative to `assets/css/`, pointing at the
+source's own font files, which build copies into the campaign's `assets/`
+tree with the rest of the source assets. A face whose file is remote, a
+`data:` URL, root-relative, outside the source root or missing is left out with
+`theme.typography.face_src_dropped`; containment is checked on real paths, so
+a symlink out of the source root is dropped. Family names are stripped of
+characters that could not appear in a quoted family. Button radius is mapped only alongside a
+mapped family, so a source with no brand faces generates exactly what it did
+before.
+
+Typography covers family and button radius only, because those are the only
+type and shape tokens next-core exposes. Heading weight, letter-spacing and
+text-transform stay at next-core's values: next-core renders headings at 700,
+so a design that sets headings at 600 shows its bold face on commerce pages.
 
 ### Foreground tokens are derived from background luminance
 
@@ -205,8 +259,10 @@ downsell, or receipt pages.
 
 If a fresh `brand-theme.css` exists:
 
-1. Copy it into the campaign asset tree.
-2. Add it to commerce page frontmatter styles after `next-core.css`.
+1. Copy it into the campaign asset tree (`assets/css/`), with
+   `brand-fonts.css` beside it when theme generate wrote one.
+2. Add it to commerce page frontmatter styles after `next-core.css`. List
+   `brand-fonts.css` on the same pages; its position does not matter.
 3. Preserve SDK-owned runtime surfaces: `data-next-*`, package selectors,
    payment fields, totals, submit controls, receipt templates, route meta tags,
    and SDK JavaScript.
@@ -215,7 +271,10 @@ If a fresh `brand-theme.css` exists:
    page's stylesheet links and records `report.theme.status`, `css_path`,
    `commerce_pages`, `load_order` and evidence. It refuses, writing nothing,
    when a page that loads `next-core.css` does not load the brand layer after
-   it, or when no built commerce page loads `next-core.css`.
+   it, when theme generate wrote `brand-fonts.css` (at the Build Context's
+   `theme.generated.fonts_css_path`) and a styled page does not load an
+   identical copy from inside the built site, or when no built commerce page
+   loads `next-core.css`.
 
 ### Where next-core.css belongs
 

package/docs/build-packet.md

@@ -832,7 +832,7 @@ Blockers (not waivable — the markup provably does not do what it says):
 - `CHECKOUT_NOT_FORM` — `data-next-checkout` on an element that is not `<form>`.
 - `WRONG_FIELD_NAME` — `data-next-checkout-field` with a value the SDK does not
   map. The set is vendored from the SDK at a named tag
-  (`src/sdk-attribute-index.mjs`, currently v0.4.42: `email`, `fname`, `lname`,
+  (`src/sdk-attribute-index.mjs`, currently v0.4.43: `email`, `fname`, `lname`,
   `phone`, `address1`, `address2`, `city`, `province`, `postal`, `country`,
   `payment-method`, `accepts_marketing`, `cc-number`, `cc-month`, `cc-year`,
   `exp-month`, `exp-year`, `cvv`, the legacy `card-*` spellings, and any
@@ -867,6 +867,23 @@ Warnings (advisory):
   `data-next-package-toggle`), or one a `*-template-id` attribute points at.
   SDK tokens are single-brace; a template nothing in the SDK reads, including
   a vendor template nested deeper inside SDK chrome, may use any syntax.
+- `PAGE_TYPE_ATTRIBUTE` — `data-next-page-type` on a page with no
+  `<meta name="next-page-type">`. The SDK never reads the attribute, so the
+  page runs as the default `product` step; on an upsell page no upsell page
+  view is recorded. `window.nextConfig.pageType` does not silence it: it
+  reaches the SDK's config store but not the upsell page view. The message
+  names the meta value to add: `receipt` on a receipt, `upsell` on a page with
+  a `data-next-upsell` offer, otherwise the attribute's SDK page type
+  (`product`, `cart`, `checkout`, `upsell`, `receipt`; `downsell` reads as
+  `upsell`, `thank-you`, `thankyou` and `confirmation` as `receipt`, and
+  `presell`, `landing` and `advertorial` as `product`). Any other value is not
+  guessed at: the message lists the five SDK page types.
+- `UPSELL_PAGE_TYPE_MISSING` — a `data-next-upsell` offer on a page whose
+  `next-page-type` meta is missing or is not `upsell` (the SDK has no
+  `downsell` page type). The SDK records the upsell page view only from
+  `<meta name="next-page-type" content="upsell">`, so reports show the
+  purchase with no upsell view before it. Not raised on a receipt, or when
+  `PAGE_TYPE_ATTRIBUTE` already names the page.
 
 Information: `data-next-*` names the vendored attribute index does not list are
 collected on the gate (`unknown_attributes[]`) and printed as one advisory ready
@@ -1029,6 +1046,16 @@ Commit durable packet/context/report artifacts when they represent a real build
 
 Packet-mode `doctor` is inspection-only by default and preserves retained evidence and active run journals, even when lifecycle capture is configured. Use `--write` to intentionally record fresh evidence; `--no-write` takes precedence. Inspection still reports current blockers and keeps the same exit status.
 
+Add `--ci` for the [standing PR evidence check](campaigns-os-build-flow.md#live-campaign-changes):
+`campaigns-os doctor --packet <packet> --ci --no-live-refs`. CI mode assesses the
+same build-bound Polish/QA debt as readback, exits 0 for current evidence, 3 for
+owed evidence, 4 for unknown debt, and 2 for a missing/unreadable packet. Any owed
+stage returns 3; otherwise an unknown stage returns 4. Other doctor errors remain reported but do not
+change the CI exit. It prints Markdown for a PR comment, or adds `ci.status`,
+`ci.exit_code`, `ci.polish`, `ci.qa` and `ci.changes` under `--json`.
+`--ci` adds no writes or network reads; pass `--no-live-refs` in CI to disable
+doctor's existing live campaign read. Without `--ci`, inspection behavior is unchanged.
+
 `campaigns-os doctor --packet <packet> --write` restates its outcome on the Assembly Report's `stages.doctor` (status, command, outputs, blockers, warnings, `checked_at`). A re-run that reaches the same outcome leaves the report's bytes unchanged rather than refreshing the timestamp alone, so a digest taken of the report — a Run Record's `assembly_report` sha256 — keeps verifying across repeated doctor runs; a changed outcome still rewrites the file.
 
 `campaigns-os start` / `campaigns-os prepare-build` writes portable packet, context, report, and generated doctor-output paths. Resolve each path from its reader's base:

package/docs/campaign-build-brief.md

@@ -4,6 +4,22 @@ The Campaign Build Brief is the merchandising and design-presentation truth for
 
 CampaignSpec remains the operational truth: packages, offers, shipping, routing, SDK hints, payment/runtime values, and API identity. The Build Brief answers business-owned presentation questions that agents should not infer silently: page authority, palette and CTA treatment, product media rules, pricing display, promo language, payment/trust surfaces, canonical names, residue policy, and QA expectations.
 
+## Design Authority
+
+For a page built from an HTML export of a named design file, the drafted brief
+records `design_authority.<page>.source: design_file`, with `reference` set to
+the design file link, `frames` set to the declared frame links, and
+`derived_artifact` naming the export (`provided_design_export` and its HTML
+path). The summary reads "follow the design file, built from its HTML export".
+A Figma spec `design_source` supplies this lineage only with
+figma-sections-export provenance that passes doctor's
+`source_html.producer_provenance` check without a waiver; a manifest
+`design_file` is its own declaration.
+A value you state in the brief file is kept as you wrote it. This records
+authority; it does not read the design file or compare elements. Doctor's
+`design.access` reports that access as unexercised, with guidance to continue or
+compare the export and file by hand.
+
 ## Artifact Locations
 
 Campaigns OS accepts YAML or JSON:

package/docs/campaigns-os-build-flow.md

@@ -17,6 +17,65 @@ The happy path is intentionally tight:
 
 Pause only for missing inputs, doctor blockers, blocked deploys, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty. The default path should not branch into external browser skills or hand-built backend order creation.
 
+## Live-campaign changes
+
+Keep a standing pull-request check after launch: install locked dependencies
+with `npm ci`, build the campaign site with
+`CPK_ENV=development npx --no-install campaign-build` (the check does not read the build summary),
+then run `npx --no-install campaigns-os doctor --packet <packet> --ci --no-live-refs`.
+Run these from the Page Kit folder containing the pinned tools and committed
+packet, local CampaignSpec, Build Context and Assembly Report. The site build
+must produce `_site/<public_route_slug>/`; `campaigns-os build` prepares inputs
+and does not build the site. Do not record a new build merely to clear the check.
+Match the Assembly Report's build environment: the documented local-proof flow
+uses `development`; set `CPK_ENV=production` when the recorded evidence reviewed
+a production render instead. Environment differences also change fingerprints.
+
+| CI status | Exit code | Meaning |
+|---|---|---|
+| `current` | `0` | Polish and QA both bind to the build on disk and neither is lifecycle-required. |
+| `owed` | `3` | Polish or QA binds to another build or is lifecycle-required; evidence is owed. |
+| `unknown` | `4` | Output or assembly fingerprints are missing, a stage fingerprint is missing without a lifecycle requirement, output is unreadable, or inspection throws; debt cannot be determined. |
+| `usage` | `2` | The packet is missing, unreadable or invalid JSON. |
+
+Any owed stage returns 3; otherwise an unknown stage returns 4. Normal
+doctor errors remain visible but do not determine the CI exit code. Without
+`--ci`, doctor retains its usual inspection output and 0/2 result. `--json`
+adds a `ci` object containing `status`, `exit_code`, `polish`, `qa`, and
+`changes` when assessment completes. Without `--json`, every CI outcome prints
+an escaped Markdown report, including a "could not evaluate" report for packet
+usage errors (exit 2) or inspection failures (exit 4). Page changes are compared
+with the retained assembly manifest, so the page list may be empty if that
+manifest was already updated; old Polish/QA bindings still show debt.
+Without a usable manifest, page changes are unknown, but matching stage
+bindings remain current unless lifecycle-required, and differing bindings remain owed.
+The check reads recorded fingerprints, not machine-local capture files.
+Readback's `evidence_debt` uses the same assessment, showing an agent this debt
+before it edits; its separate time-based staleness assessment is not the CI signal.
+
+Copy the [workflow example](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/examples/campaign-repo-evidence-check.yml) into the
+campaign repository and adjust the packet path. It posts or updates one PR
+comment using the fixed `<!-- campaign-evidence-check -->` marker. Evidence
+reports use stdout only; stderr stays in the job log. If the command produces
+no stdout, the comment points to the job log with a fixed fallback message.
+If install or build fails before doctor runs, the comment is updated with
+"Campaign build failed; evidence not evaluated. See the job log."
+Evidence findings are **report-only by default**. Opt in to failing on a nonzero doctor
+exit by setting the repository Actions variable
+`CAMPAIGNS_OS_EVIDENCE_CHECK` to `fail`. Install/build failures still fail normally.
+Fork pull requests may lack comment-write permission; comment failures are
+nonfatal and the report remains in the job log. The example uses `pull_request`
+and does not run untrusted code with `pull_request_target` privileges.
+
+To repay fingerprint-drift debt, rebuild and record the output, re-run `polish capture` against
+that served build, record Polish with `record polish --evidence <evidence.json>`,
+then run `qa run` to record QA for the current build. For lifecycle-required
+stages with matching build bindings, re-run the required stages against the
+existing build: `polish capture` and `record polish` when Polish is owed, and
+`qa run` when QA is owed. The CI report names each owed stage's cause and
+selects the remedy accordingly. The workflow only inspects;
+it does not renew evidence or deploy.
+
 ## Partial Builds
 
 Partial builds are valid campaign work. A pass may build only new presell pages,
@@ -83,11 +142,11 @@ the assembly report.
 - Landing and presell pages should preserve prepared HTML when it is a real standalone design. Use page-kit passthrough structure, inject the SDK/config requirements, and repoint CTAs into the CampaignSpec flow.
 - **Pre-checkout pages must ship the same SDK bootstrap as the checkout layout.** Presell and landing pages are SDK `page_type: product`; they need `config.js` (before the loader), the `campaign-cart@v{sdk_version}/dist/loader.js` module script, and the `next-funnel` + `next-page-type` meta tags — not just inert `data-next-*` attributes. Without the loader the SDK silently no-ops: `data-next-hide` conditional visibility (`param.banner` / `param.seen`), `utmTransfer` UTM/query carry-through to checkout (top-of-funnel ad attribution), and SDK analytics never fire. Treat `param.banner` / `param.seen` visibility and `utmTransfer` as standard pre-checkout wiring, not per-campaign discoveries. Doctor enforces this with `built_output.pre_checkout_sdk_bootstrap`.
 - **Every page names the same campaign.** A page borrowed from another funnel (a copied upsell or receipt) must not keep the other campaign's `next-api-key` / `config.js` API key, `next-funnel` meta, or `setAttribution({ funnel })` call; the SDK reads these per page and reconciles nothing, so the order lands on or attributes to the wrong campaign with no visible error. Doctor blocks this, unwaivably, with `built_output.campaign_identity` (one error per drift, naming both files and both values).
-- **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); every `data-next-upsell-action` sits inside its `data-next-upsell` container, on any page type; one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first five as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `ORPHANED_UPSELL_ACTION`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); every `data-next-upsell-action` sits inside its `data-next-upsell` container, on any page type; one default-selected card per selector; single-brace tokens inside SDK templates; the page type in `<meta name="next-page-type">` (`upsell` on every upsell offer page), never only in a `data-next-page-type` attribute. Doctor enforces the first five as blockers and the last three as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `ORPHANED_UPSELL_ACTION`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`, `PAGE_TYPE_ATTRIBUTE`, `UPSELL_PAGE_TYPE_MISSING`).
 - **Campaign scripts must parse.** A hand-edited script with a stray or missing bracket throws a `SyntaxError` on every page that loads it, and nothing in it runs. Doctor parses every campaign-owned `.js` file a built page loads by a local `<script src>` and blocks, unwaivably, with `built_output.script_syntax.parse_failure`, naming the file, line and column.
 - Checkout, upsell, downsell, and receipt pages should preserve starter-template SDK contracts while keeping the campaign/source visual language. Treat starter templates as the reference for required `data-next-*` controls and wiring, not as a mandate to carry their visual chrome into the final campaign.
 - If source HTML declares SDK-owned zones such as `data-commerce-zone="checkout-form"` or `data-commerce-zone="order-summary"`, keep the selected starter-template family's SDK wiring for that zone (the checkout form, bound fields, payment submit and cart summary). The wrapper and page composition around it stay source-owned; do not add family class names to the campaign's own layout to satisfy QA.
-- If `context.theme` names a generated `brand-theme.css`, copy it into campaign assets and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. Generated brand-theme v0 is root-variable-only; do not use it as permission to edit SDK-owned selectors or runtime structure.
+- If `context.theme` names a generated `brand-theme.css`, copy it into campaign assets and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. When `context.theme.generated.fonts_css_path` names a `brand-fonts.css`, copy it beside the brand layer and load it on the same pages, so headings and body copy use the design's faces (`record theme` refuses a styled page that skips it). Generated brand-theme v0 is root-variable-only; do not use it as permission to edit SDK-owned selectors or runtime structure.
 - Buy-more-save-more selectors should use selected quantity plus Offer-aware price displays. Do not swap in stale package-per-tier IDs unless the CampaignSpec explicitly represents an older campaign that still owns separate packages for each option.
 - SDK routing meta tags should be emitted as campaign-root paths, for example `/campaign-slug/upsell/`, even when the CampaignSpec source value is slug-relative like `upsell/`.
 - One-time prepurchase/order-bump packages outside the main bundle should default to fixed quantity and fixed line total display unless the spec explicitly requires syncing quantity with the main bundle.

package/docs/campaignspec-authoring-examples.md

@@ -0,0 +1,116 @@
+# CampaignSpec Authoring Examples
+
+Use these examples when authoring or generating common Campaign Map shapes. They
+are public-package guidance: the goal is clearer exported CampaignSpec fields,
+not a private merchant workflow.
+
+## Hero Product + Order Bump + Upsell + Receipt
+
+Reference fixture: [single-step checkout, upsell and receipt](https://github.com/NextCommerceCo/campaigns-os/blob/main/contracts/fixtures/campaign-specs/shop-single-step-upsell-receipt.json).
+Fixtures are repository test data and are not included in the installed package.
+
+For CampaignSpec 5.0 multi-step shapes, compare the [three-step checkout](https://github.com/NextCommerceCo/campaigns-os/blob/main/contracts/fixtures/campaign-specs/shop-three-step-dynamic-shipping.json)
+and [select-to-checkout](https://github.com/NextCommerceCo/campaigns-os/blob/main/contracts/fixtures/campaign-specs/olympus-mv-two-step-configurable.json) examples.
+Author new specs against the shipped [v5 schema](../schemas/campaign-spec.v5.schema.json).
+
+Canonical page shape:
+
+```text
+checkout -> upsell -> receipt
+```
+
+Authoring guidance:
+
+- Checkout page:
+  - `type: "checkout"` with `sdk_hints.sdk_page_type: "checkout"`
+  - `page_url: "/checkout/"` — `page_url` is the route field.
+  - `packages[]` entries use `ref_id` + `qty` (the real export key is `qty`,
+    not `quantity`). A plain entry is the main package; add-ons carry the
+    boolean role flags `is_order_bump: true` / `is_upsell: true` — there is
+    no `role` field in exports.
+  - `sdk_hints.template_family` names the intended starter family only as a
+    hint; the Build Packet still locks the family.
+  - `sdk_hints.meta_tags.next-success-url` points to the next runtime route.
+  - `success_url` holds the next PAGE ID (never a URL, despite the name).
+  - A checkout may equally declare its forward step as `next_page`; twelve
+    pages across ten certified fixtures do. Forward links resolve from
+    whichever routing field a page declares — `on_accept`, then `success_url`,
+    then `next_page` — so an unconventional journey is wired rather than
+    dropped.
+  - `next_page` is the generic "wherever this page goes next" and is honoured on
+    every page type. The other two forward fields carry a page-shaped meaning
+    and are honoured only where that meaning exists:
+    - `success_url` means "after payment succeeds" — only on `type: "checkout"`.
+    - `on_accept` means "after accepting the offer on this page" — only on
+      `type: "upsell"` or `"downsell"`.
+
+    Declared anywhere else they are inert, `next_page` wins, and the
+    `RouteFieldIgnoredForPageType` warning says which field was skipped and
+    where the shopper actually goes. A `select` page is the first step of a
+    two-step checkout and a `checkout_step` is a non-final page of a split
+    checkout: neither takes payment nor presents an accept/decline offer, so a
+    copy-pasted `success_url` or `on_accept` there does not route.
+  - Multi-step checkout (CampaignSpec 5.0): `checkout` is the page that takes
+    payment, and it forwards to an upsell, downsell or thank-you page. A page
+    with a checkout form that collects details and moves on without placing an
+    order is `type: "checkout_step"` and routes with `next_page`; a bundle
+    picker before checkout is `type: "select"`. Every path from an entry page
+    to an upsell passes exactly one `checkout`; a campaign may hold several, one
+    per split-test path. A 4.2/4.3 spec that chained `checkout → checkout` is
+    read as `checkout_step` pages ahead of the last one.
+    See the [v5 schema](../schemas/campaign-spec.v5.schema.json) for the
+    authoring fields; runtime routing is projected by Campaigns OS.
+
+- Upsell page:
+  - `type: "upsell"` or `type: "downsell"`, with
+    `sdk_hints.sdk_page_type: "upsell"`
+  - `page_url` is a Page Kit route, not a source filename.
+  - `packages[]` (with `is_upsell: true`) or `offers[]` names the
+    post-purchase offer refs. Offers are identified by `ref_id` into the
+    root `offers[]` catalog (`package_ref_id` is not part of the contract).
+  - `on_accept` and `on_decline` hold the next PAGE IDs; route paths live
+    in `page_url` / derived `resolved_routing`.
+
+- Receipt page:
+  - `type: "thankyou"` — the canonical terminal page type. The SDK-layer
+    `receipt` projection is expressed as `sdk_hints.sdk_page_type: "receipt"`
+    (and `meta_tags["next-page-type"]`), never as `page.type`.
+  - `page_url: "/receipt/"`
+  - Receipt summary/frontmatter hints preserve SDK-owned order item templates.
+
+Generator checklist:
+
+- Always emit stable `page.id` values; page IDs are the join key for
+  `source_html.pages[]`.
+- Prefer Page Kit public routes (`checkout/`, `upsell/`, `receipt/`) over
+  filenames (`checkout.html`).
+- Keep package, shipping, voucher, and offer refs in CampaignSpec/API fields,
+  not in source HTML.
+- Put template-family preference in `campaign.preferred_template_family` when
+  useful, but require the Build Packet/template lock before commerce wiring.
+- Keep checkout/upsell/downsell/receipt runtime surfaces template-clone-first;
+  source HTML can own visual composition and copy, not payment/order mutation.
+
+## Order Bump Notes
+
+An order bump is still a checkout package/offer surface. It should be encoded as
+a checkout page package with `is_order_bump: true`, a `qty`, and its source
+`ref_id`.
+When the selected starter family does not support a bump, the build should
+remove the bump surface and record the decision in the Assembly Report instead
+of leaving demo bump refs in copied frontmatter.
+
+## Multi-Upsell Depth
+
+For more than one post-purchase page, keep each upsell/downsell page explicit in
+`funnels[].pages[]` and wire `on_accept` / `on_decline` to the next page. QA
+then derives typed-card proof coverage from topology. `common` runs every
+actual terminal path when they fit under the flood cap; above it, it runs
+checkout, first-offer accept and decline, and a deduplicated shortest real
+receipt path, then adds the shortest path that clicks the decline on each offer
+or downsell page not yet declined, up to the cap. Explicit paths support targeted
+repair, while `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`; when the
+planned count exceeds it, the command names the exact explicit
+`--max-test-orders` raise.

package/docs/design-source-package.md

@@ -32,6 +32,48 @@ Unknown top-level fields are rejected.
 
 ## Contributions and coverage
 
+**A design file behind an HTML export.** Name it on the page's source-html
+manifest entry as `design_file: {type, file_url, breakpoints}`. `breakpoints`
+holds optional desktop, tablet and mobile frame links. Intake records a separate,
+non-renderable contribution (`figma_frames` with native trust for Figma, otherwise
+`other` with opaque trust), with `reference_only` coverage. The page's
+`html_funnel` mapping links to it through `derived_from`. Pages sharing a file
+share one contribution. A CampaignSpec page's Figma `design_source` records lineage
+only with figma-sections-export provenance that passes doctor's
+`source_html.producer_provenance` check without a waiver; then it wins when both
+channels are present. Otherwise, a spec pointer alone adds no contribution or
+lineage at intake, and no `design.access` row unless the package already records
+a spec contribution. A Figma `design_source` that names a different file or
+frames from the manifest's `design_file` is reported as a conflict for review
+even when it records no lineage, as is a file key that differs from the
+exporter's. A file shared by several pages keeps the manifest's provenance if
+any page declared it in the manifest.
+
+Malformed `design_file` values remain non-fatal manifest warnings; the schema
+accepts them so validation agrees with intake. File URL schemes are
+case-insensitive. Explicit tool types are lowercased for identity. For a type
+other than `figma` or `other`, the design-file source ref's optional
+`design_file_type` string preserves the type doctor needs to reconstruct the
+recorded identity even after a declaration edit. This new field is material;
+source-reference `notes` remain nonmaterial, including on `design_file` refs.
+
+Recording a file adds no readiness requirement, Source TODO or blocker. A
+manifest edit, including `design_file`, follows the existing stale-package rule:
+rerun intake with `--force`. A later spec declaration leaves the package current;
+when eligible under the Figma provenance rule above, doctor reports the
+unrecorded file with the same recovery guidance.
+`design.access` reports `unexercised` / `design_access_missing` when the recorded
+file agrees with the declaration. For a recorded spec contribution, doctor
+compares the current spec declaration even if today's manifest or provenance is
+unavailable. This version cannot read design files. This
+records authority only; Polish element parity compares the built page with its
+source HTML, not the design file (see [Polish evidence](polish-evidence.md)).
+A changed design file is listed for review; changing only breakpoint frames on
+that file does not change its identity. If the package records a file but the
+current declaration is absent, `design.access` reports `review` /
+`design_reference_missing`: restore the declaration, or rerun intake with
+`--force` to drop the recorded file.
+
 Each `contributions[]` record identifies one source contribution and records:
 
 - `id`, `kind`, `trust`, and whether it is `renderable`;
@@ -275,10 +317,10 @@ The projected fields are explicit:
 | Contribution core | `id`, `kind`, `trust`, `renderable`. |
 | Provenance | `source_type`, `adapter`, `producer`, `generator`, `generator_version`, `source_root`, `manifest_schema_version`, `manifest_path`, `manifest_sha256`, `producer_material_fingerprint`, `asset_crawl_schema_version`. |
 | Presentation intent | `summary`, `composition`, `content_hierarchy`, `imagery`, `copy`, `brand`, `responsive_behavior`. |
-| Source reference | `id`, `kind`, `path`, `url`, `sha256`, `role`, `media_type`. |
+| Source reference | `id`, `kind`, `path`, `url`, `sha256`, `role`, `media_type`, optional `design_file_type` (only on `design_file` refs). |
 | Visual reference | `id`, `kind`, `viewport`, `availability`, `url`, `path`, `sha256`, `width`, `height`, `device_profile`, `scale_factor`, `browser`, `source_ref_id`, `unavailable_reason`. |
 | Template Reference | `id`, `family`, `version`, `contract_path`, `artifact_path`, `sha256`, `standard_viewport_refs` using the visual projection above. |
-| Coverage mapping | `id`, `surface_id`, `coverage_role`, `confidence`, `source_refs`, `screenshot_refs`, `reference_refs`, `template_reference_id`. |
+| Coverage mapping | `id`, `surface_id`, `coverage_role`, `confidence`, `source_refs`, `screenshot_refs`, `reference_refs`, `template_reference_id`, optional `derived_from`. |
 | Source Gap | `id`, `kind`, `scope`, `applies_to`, `reason`, `status`, `attributed_by`, `attributed_at`, `evidence_refs`. |
 | Source TODO | `id`, `kind`, `scope`, `applies_to`, `description`, `status`, `owner`, `required_viewports`, `source_ref_ids`. |
 | Approved waiver | `id`, `scope`, `applies_to`, `reason`, `status`, `waived_by`, `waived_at`, `expires_at`, `review_condition`, `evidence_refs`. |
@@ -458,6 +500,8 @@ only when filename matching was ambiguous, and is `null` otherwise.)
 
 ### The record shape
 
+Polish now reads these files. Record `scale_factor` (the device pixel ratio the screenshot was taken at) and keep `width`/`height` equal to the image's pixel size: a screenshot is compared with the built page only when its width divided by `scale_factor` equals the capture width, and a screenshot without `scale_factor` is not compared. Link it to its source page (`source_ref_id`, filled in for you) and record `captured_at`, or it is listed for review.
+
 One manifest page entry with its proof, inside the envelope the validator requires
 (the mobile record is elided):