@nextcommerce/campaigns-os 1.59.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.59.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": "d5ff501ab57aef160a7108341de8a952006a28a4",
+        "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

@@ -788,9 +788,13 @@ One error per finding; each names the two files and the two values, so the
 repair is a one-line edit. Every built HTML file under `_site/<slug>/` is
 scanned, because every one is served. When doctor has the CampaignSpec, a
 finding that names a file no active spec page builds to says so and lists it
-under `stray_files`. Such a file is leftover output (page-kit does not prune
-`_site/`) or an HTML file copied into the source, such as a design export's
-`index.html` under `assets/`. The repair is to remove the source file if
+under `stray_files`. Such a file is leftover output or an HTML file copied
+into the source. On page-kit 0.2.x both happen: it does not prune `_site/`,
+and it builds and copies a design export's `index.html` under `assets/`. From
+0.3.0 page-kit removes `_site/<slug>/` before each build and neither builds
+nor copies `.html` under `assets/` (the build summary lists each one as
+`ASSET_IGNORED`), so a stray there is a source page no spec page claims or
+output written outside a build. The repair is to remove the source file if
 there is one, delete the built file, and rebuild and record the build again,
 not to retag it. Pages whose route contains a `-backup-` or `-old-`
 segment are parked copies: skipped and listed on the gate as `pages_skipped`,
@@ -828,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
@@ -863,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
@@ -1025,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:
@@ -1754,7 +1785,7 @@ own stages) → calls `next` again → repeat until stage="done"
 
 ### Refreshing after a CampaignSpec change
 
-When the CampaignSpec's material content changes, every build, Polish and QA record made against the earlier content stops counting as current, in local-spec, saved-Map and gateway packets alike. For a saved Map or gateway packet, Campaigns OS compares the copy intake fetched; it does not check whether that copy is the latest remote revision, and reports the remote as unconfirmed. Doctor warns `spec.material_stale`, and `next`, progress, readback, the Assembly Report's own status and the QA gate show the stages that are owed again; `next` routes to the first one. Run `campaigns-os record spec --packet <packet>` to bind the new content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`, which is never used as current proof. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the set, order or routes of active pages still needs intake. Re-recording an unchanged build after a spec change keeps the build owed, because the change has not reached the pages, unless the operator records a reason with `--deviation-reason`; this holds even when `record spec` was not run, and that `record build` also marks Polish and QA owed again. Polish stays owed until a new `polish capture`, and QA must produce a new verdict against the current content. Polish measurements of byte-identical output keep their values, but the Polish stage is owed again. These checks are tamper evidence, not proof: a hand-written record that copies the current values, or a packet pointed at an older copy of the spec, is not detected.
+When the CampaignSpec's material content changes, every build, Polish and QA record made against the earlier content stops counting as current, in local-spec, saved-Map and gateway packets alike. For a saved Map or gateway packet, Campaigns OS compares the copy intake fetched; it does not check whether that copy is the latest remote revision, and reports the remote as unconfirmed. Doctor warns `spec.material_stale`, and `next`, progress, readback, the Assembly Report's own status and the QA gate show the stages that are owed again; `next` routes to the first one. Run `campaigns-os record spec --packet <packet>` to bind the new content: it updates the build context and report identity, re-reads the brief file last saved (by intake or `record brief`), keeps waivers, warning accepts, the applied theme and deploy settings, and moves each superseded stage record into that stage's `history`, which is never used as current proof. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the set, order or routes of active pages still needs intake. Re-recording an unchanged build after a spec change keeps the build owed, because the change has not reached the pages, unless the operator records a reason with `--deviation-reason`; this holds even when `record spec` was not run, and that `record build` also marks Polish and QA owed again. Polish stays owed until a new `polish capture`, with one exception: when `record build --deviation-reason` records the very output a completed Polish reviewed (same build fingerprint and source package) and only the CampaignSpec changed, not the brief's presentation, that `record build` restores the Polish record the change moved to history, stamped with the current inputs. It is the same review of the same pages. QA must produce a new verdict against the current content. Polish measurements of byte-identical output keep their values, but the Polish stage is owed again. These checks are tamper evidence, not proof: a hand-written record that copies the current values, or a packet pointed at an older copy of the spec, is not detected.
 
 The CampaignSpec's material content is the whole spec except `spec_identity`,
 `slug`, `map_id` and `saved_at`; a page `label` edit is material. A spec
@@ -1813,13 +1844,11 @@ On a hosted target, record an unset hosted preview URL with
 `campaigns-os qa policy set --packet <p> --preview-url <url>`, then record the
 deploy with `campaigns-os record deploy --packet <p> --base-url <preview url>`. The hosted preview must be a non-loopback
 HTTP(S) URL whose origin or QA-resolved campaign route path differs from `deploy.production_url`;
-query and fragment text does not make the production page a preview. With
-`deploy.preview_url` recorded, run `campaigns-os next qa --packet <p>` and
-`campaigns-os qa run --packet <p> --base-url <preview-url> --browser
---test-order common`. The recorded hosted preview satisfies the deploy step
-for this all-template shape. After QA records a verdict for the current build,
-`campaigns-os next --packet <p>` reaches closeout without a hosted deploy
-record. QA against the packet's production URL retains the strict gate.
+query and fragment text does not make the production page a preview. With the
+deploy recorded, run `campaigns-os qa run --packet <p> --base-url <preview-url>
+--browser --test-order common`; after QA records a verdict for the current
+build, `campaigns-os next --packet <p>` reaches closeout. QA against the
+packet's production URL retains the strict gate.
 
 Each command reads the same packet, Build Context and Assembly Report `next`
 reads (`--context` / `--report` override them the same way), validates what it
@@ -1882,7 +1911,7 @@ Result shape (with `--json`):
 Terminal states:
 
 - **`stage: "doctor-blocked"`** — doctor returned errors. Resolve the blockers and re-run `campaigns-os doctor` to confirm before calling `next` again.
-- **`stage: "done"`** — every stage is terminal. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages, and `qa run` for QA. `record deploy` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Then call `next` again.
+- **`stage: "done"`** — every stage is terminal. Pipeline is complete. To repeat build work, do the work and use `record build`; it makes downstream stages owed as needed. Use `record setup` or `record polish` after repeating those stages. `record deploy` records the served deploy, a loopback URL for a local-serve target or an https URL for a hosted one. Use `qa run` for QA. Then call `next` again.
 - **`stage_blocked: true`** — the picker returned a stage whose recorded status is `blocked`. Don't run the prompt as-is; clear the blocker first.
 
 The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and is the way to force a specific stage when you want to override the picker.

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:
@@ -64,7 +80,7 @@ A brief is prepared, where every open question blocks, only when the file sets `
 
 Saving a brief whose content is unchanged keeps all stage evidence and statuses. Reformatting, reordering keys, writing a default value explicitly, or changing only `_meta` also keeps all stage evidence and statuses; the save may rewrite the brief files. When the presentation sections change (`campaign_intent`, `design_authority`, `brand`, `media`, `offer_presentation`, `promo_urgency`, `commerce_surfaces`, `canonical_display`, `template_residue_policy`, or any section you add), build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each affected stage records when its inputs changed. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and older ones are dropped. History is display only and is never used as current proof.
 
-Recording build again over output that has not changed since the brief or CampaignSpec changed does not make the build current: `next` keeps asking for a build, because the change has not reached the pages. If the operator decides the change needs no change to the built pages, record build with `--deviation-reason "<the operator's reason>"`; the build is then recorded with a warning, and the reason is shown in `next` and the QC handoff. `--deviation-reason` is a general flag any caller can pass: Campaigns OS records the reason, but cannot tell whether the operator chose it. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. The same applies after `prepare-build --force`, which now keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed. Recording Polish again does not make it current until a new `polish capture` runs after the change. Recording Polish as skipped, with a skip reason, while it is owed is the operator's decision to skip it: the input change no longer makes Polish owed. The Polish gate still passes only a completed Polish, so `next` stays at Polish until one is recorded (see `docs/polish-evidence.md`).
+Recording build again over output that has not changed since the brief or CampaignSpec changed does not make the build current: `next` keeps asking for a build, because the change has not reached the pages. If the operator decides the change needs no change to the built pages, record build with `--deviation-reason "<the operator's reason>"`; the build is then recorded with a warning, and the reason is shown in `next` and the QC handoff. `--deviation-reason` is a general flag any caller can pass: Campaigns OS records the reason, but cannot tell whether the operator chose it. A CampaignSpec change that was never saved with `record spec` is recorded by the next `record build`, `record polish` or QA run, with the same effect; `record build` then also marks Polish and QA owed again. An edit to the brief file is not read until it is saved with `record brief`: until then the build reads the saved brief, and doctor warns `build_brief.input_unsaved`. The same applies after `prepare-build --force`, which now keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed. Recording Polish again does not make it current until a new `polish capture` runs after the change. The exception is a CampaignSpec-only change recorded with `record build --deviation-reason` over the exact output a completed Polish reviewed: that `record build` restores the Polish record, since it reviewed the same pages. A brief presentation change still owes a new Polish. Recording Polish as skipped, with a skip reason, while it is owed is the operator's decision to skip it: the input change no longer makes Polish owed. The Polish gate still passes only a completed Polish, so `next` stays at Polish until one is recorded (see `docs/polish-evidence.md`).
 
 A build, Polish or QA record that does not say which brief and CampaignSpec content it was made against counts as unconfirmed, not current. Records made by earlier releases are unconfirmed, so after upgrading, `next` routes back to build once; record build and Polish again and run QA again. These checks are tamper evidence, not proof: a record written by hand that copies the current values or removes the record of an input change, or a packet pointed at an older copy of the spec or brief, is not detected.
 

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,
@@ -41,7 +100,7 @@ URL.
 - Starter template contracts own the SDK attribute contract and protected runtime surfaces: checkout/cart/upsell/receipt/payment/address/totals/submit controls and their required data attributes.
 - Designed source owns visual composition, content hierarchy, imagery, and page-level copy.
 
-Packages identify sellable products or variants, and Offers own campaign price changes. Package Retail Price/Quantity fields may exist on older campaigns, but assembly should not introduce them for new tier pricing.
+Packages identify sellable products or variants, and Offers own campaign price changes. The Campaigns App dashboard calls packages **Products** and creates one per variant when an Offer that selects it is saved, so a campaign set up there has one package per variant and a separate Offer for each Buy 1/2/3 tier. Package Retail Price/Quantity fields and multi-unit packages exist on older campaigns that have the legacy **Enable Package Retail Price & Quantity** setting on (see the "Older Campaigns" section of [Campaign Products](https://docs.nextcommerce.com/docs/apps/campaigns-app/build-campaign-packages)), but assembly should not introduce them for new tier pricing.
 
 ## Offer Application Surfaces
 
@@ -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):