@nextcommerce/campaigns-os 1.60.0 → 1.62.0

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/campaign-standardization-report.md

@@ -81,10 +81,10 @@ field before attributing the file.
 `--template-family`), `--slug`, `--sdk-support-policy`, `--field-contract`,
 `--no-doctor`, `--json`, and the two flags every command accepts,
 `--run-id` and `--lifecycle-journal`. Any other flag is refused before the
-scan starts, with the known list in the message — including the
-`--flag=value` spelling, which the parser would otherwise store as an unknown
-key (`--no-doctor=maybe` used to run the doctor anyway). Values follow the
-flag as the next argument.
+scan starts, with the known list in the message. Values follow the flag as
+the next argument: like every Campaigns OS command, standardize refuses the
+`--flag=value` spelling before the scan starts (`--no-doctor=maybe` used to
+run the doctor anyway).
 
 ### Exit codes
 

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

@@ -17,6 +17,116 @@ 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, or the only owed stage is advisory Polish for a page-only change. |
+| `owed` | `3` | Polish or QA binds to another build or is lifecycle-required; evidence is owed. For a page-only change only QA on the changed pages counts. |
+| `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.
+
+### What a change owes
+
+Each owed stage carries `change`: what changed since the build that stage
+last reviewed. It is read from the rebuilds `record build` keeps
+(`stages.assembly.build_changes`) plus the drift on disk, so the changed pages
+stay listed after `record build`. A change is one of two kinds:
+
+- **Page-only.** Only the HTML of some pages changed (copy, image references,
+  inline styling), and none of them is a checkout page or changed its commerce markup:
+  `data-next-*`, `os-checkout-*` and other package, offer, shipping or upsell
+  attributes, inline event handlers (`onclick` and the like), `next-*` meta
+  tags (the upsell accept and decline routes among them), scripts, link
+  targets or form actions. A checkout page is one whose type is checkout,
+  checkout step or select, or one that carries checkout or payment markup
+  (`data-next-checkout*`, `data-next-payment*`, `data-next-express-checkout*`,
+  `os-checkout*`). The campaign's own entry in
+  `_data/campaigns.json` (SDK pin, analytics ids, store fields) is unchanged.
+  It owes QA on the changed pages only: `qa.scope` is `pages` and
+  `qa.owed_pages` lists them. Polish is advisory (`polish.advisory: true`): it
+  is reported, and `next`, the CI check and the QA gate do not require it.
+- **Commerce-affecting.** Anything else: a checkout page, commerce markup or
+  the config entry changed, a page was added or removed (a route change), or a
+  built file other than a page's HTML changed (a script, stylesheet or image
+  file cannot be mapped to one page). It owes the full Polish and QA, as
+  does a change that cannot be read (a record made before `record build`
+  kept a commerce signature, or a rebuild history that no longer reaches the
+  reviewed build). A Polish or QA requirement a brief or spec change made is
+  always full.
+
+A page-only change extends only a review that completed. Polish is advisory
+only when the last Polish completed or was skipped; a blocked Polish owes the
+full stage. QA is owed on the changed pages only when the last QA completed,
+or when it was a page-scoped run that did not complete, in which case the
+pages are counted from the full QA that run extended, so its unpaid pages stay
+owed. A blocked or pending full QA owes a full run.
+
+The PR comment opens with the kind it found and what that owes, for example
+"Change found: page-only. It owes QA on `upsell1`; Polish is advisory." A
+commerce-affecting change names its reasons.
+
+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 a page-only change, rebuild, run `record build`, then run
+`qa run --packet <packet> --page <page_id>` against that build, repeating
+`--page` for each changed page the report names. A page-scoped run checks only
+those pages and places no test orders; the QA stage it records keeps the
+purchase proof of the full run it extends. It refuses, before checking
+anything, when the output on disk is not the recorded build, when the change
+is commerce-affecting, when a changed page is left out, when the QA it would
+extend did not complete, or when QA's inputs (the brief's `qa_policy` and the
+CampaignSpec) changed or cannot be confirmed current. Running Polish for a
+page-only change is optional.
+
+To repay fingerprint-drift debt for any other change, 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 +193,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,141 @@
+# 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. The flags mean "add-on" on `checkout`,
+    `checkout_step` and `select` pages only. On an upsell or downsell page
+    they mark nothing (see the upsell page below).
+  - `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[]` or `offers[]` names the post-purchase offer refs. Write each
+    package as a plain `{ ref_id, qty }` entry. On an upsell or downsell page
+    every package row is the page's offer and never an order bump, so
+    `is_upsell: true` on that row is accepted and changes nothing about
+    its role. 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.
+
+## Campaign Currencies
+
+- `campaign.currency` is the default currency: a three-letter upper-case
+  ISO 4217 code such as `"USD"`. A lower-case code (`"usd"`) or a symbol
+  (`"US$"`) is an error, because Campaign Cart can fall back to a cached USD
+  campaign and price the page in the wrong currency.
+- `campaign.available_currencies` lists every currency the campaign sells in,
+  the default included, as code strings: `["USD", "EUR", "GBP"]`. The
+  Campaigns API returns this list as `{ code, label }` objects; Map Builder
+  writes the codes, and a hand-written spec should too.
+- The Campaigns App API also has `additional_currencies`, which is the same
+  list without the default. It is not a CampaignSpec field: put every
+  currency in `available_currencies`.
+- When `available_currencies` is non-empty and does not contain
+  `campaign.currency`, the validator warns. An empty list states nothing and
+  is not checked.
+
+These checks are the `CampaignCurrencies` validator rule, which
+`campaigns-os doctor` runs with the rest of the spec rules.
+
+## 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`. |
@@ -397,12 +439,24 @@ left by a process that died is recovered automatically, and a lock directory
 without an owner record (only an older release leaves one) is never taken
 over: the command refuses it after about a second and names it. Confirm no
 campaigns-os process is working on the target, then remove it. Anything else
-at the lock path (a file, a symbolic link, or a directory with no owner record
-that holds other entries) is not a lock: once the wait ends the command names
-what is there and never removes it. The holder of the lock removes staging and
-released directories beside it whose recorded owner process no longer exists.
-Do not run an older Campaigns OS release against the same target at the same
-time. A waiver's `--dry-run` preview takes no lock.
+at the lock path (a file, a symbolic link, a directory the command cannot read,
+or a directory with no owner record that holds other entries) is not a lock:
+once the wait ends the command names what is there and never removes it. The
+holder of the lock removes staging, recovery, released and abandoned
+directories beside it whose recorded owner process no longer exists.
+
+Run one Campaigns OS release against a target at a time. Each owner record
+carries a `lock_format` number (the lock layout the writing release uses).
+Releases before 1.43.2 took the lock in two steps, creating the directory and
+then writing its owner, and a later release can replace that directory in the
+gap between them, so both runs enter. A command that finds the lock held by a
+live process whose owner record has no `lock_format`, or a different one,
+refuses at once and names that process instead of waiting for it. Every
+release before `lock_format` existed writes no number, so a holder from one of
+those is refused too, even though only releases before 1.43.2 can race. The
+check only sees a release that already holds the lock: two releases that start
+at the same instant can still meet in that gap. A dead holder from any release
+is recovered as usual. A waiver's `--dry-run` preview takes no lock.
 
 Before writing any output, `prepare-build` also requires distinct paths for the
 Build Packet, Build Context, Assembly Report, Doctor output, normalized Build
@@ -458,6 +512,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):
 

package/docs/effects.md

@@ -70,10 +70,12 @@ with one of these:
 | Token | Resolves to |
 | --- | --- |
 | `{target}` | The target the invocation names: the directory given to `--target`, or the Page Kit target repository the Build Packet points at. |
+| `{runtime}` | The funnel's runtime directory under `{target}`: `{target}/.campaign-runtime` for a Build Packet that records no `assembly.runtime_dir` (every packet before per-funnel records, and the first funnel of a project), else `{target}/<assembly.runtime_dir>`, which is `.campaign-runtime/funnels/<public_route_slug>` for each later funnel of the same project. The funnel's Build Context, Assembly Report, doctor output, theme output and intake inputs live here. |
 | `{cwd}` | The working directory the invocation runs in. |
 | `{spec}` | The CampaignSpec file the Build Packet names (`spec.local_path`), which need not live inside the target repository. |
 | `{home}` | Your machine: the home directory and the config root under it (`XDG_CONFIG_HOME` when set). |
 | `{packet}` | The Build Packet the invocation names (`--packet`), wherever it lives — it need not be the copy inside the target repository. |
+| `{packet-runtime}` | The same funnel runtime directory beside the Build Packet: `<packet directory>/.campaign-runtime`, or `<packet directory>/<assembly.runtime_dir>` when the packet records one. The committed QA verdict sidecar and the Run Records live here. |
 | `{lifecycle-journal}` | The command-lifecycle journal wherever it was selected for this invocation. |
 | `{proxy-base}` | The endpoint `--proxy-base` names, or the canonical NEXT endpoint when it does not. |
 | `{base-url}` | The campaign under test, as `--base-url` names it or as the packet derives it. |
@@ -81,8 +83,8 @@ with one of these:
 
 The tokens matter because effects are not all under the target. `install-skills`
 writes your **home** directory, not the campaign. `telemetry on` writes your
-**machine** config. `run-record` writes beside the **working directory**, not the
-target repo. A row that said "writes the target" would be wrong about all three.
+**machine** config. `run-record` writes beside the **Build Packet**
+(`{packet-runtime}`), not the target repo. A row that said "writes the target" would be wrong about all three.
 
 ### The Map Builder fetch
 
@@ -109,14 +111,14 @@ campaign. No store or Admin credential is used. The proxy's answer is an
 envelope whose `data` field holds the campaign. A failed read, an `ok: false`
 envelope, one with an `error` and no campaign, or several campaigns with no
 `campaign.ref_id` to pick one is recorded as `not_run` with its reason, never
-as a pass. `--no-live-refs` on `doctor` or `qa run` skips only this read and
+as a pass. `--no-live-refs` on `doctor`, `qa run` or `spec derive` skips only this read and
 records `not_run` with reason `disabled`; every other declared write and send
 is unchanged. Each form has its own row, including `doctor --write
 --no-live-refs` and `qa run --no-live-refs` with each `qa run` modifier.
 `doctor --no-write --no-live-refs` has the effects of the `doctor
 --no-live-refs` row.
 
-Only `doctor` and `qa run` make this read. The other commands that run doctor
+Only `doctor`, `qa run` and `spec derive` (see `spec derive` and the live campaign, below) make this read. The other commands that run doctor
 internally make no request and record `derived.live_campaign_refs` as
 `not_run` with reason `not_read`, with no warning: `start`, `prepare-build`
 and `build` (the intake alias for prepare-build + doctor), `theme waive`,
@@ -130,11 +132,13 @@ itself carries QA's own read).
 
 ### `record brief` and `record spec`
 
-**Saving brief answers.** `campaigns-os record brief --packet <packet>` saves Campaign Build Brief answers without re-running `start` or `prepare-build`. It writes the normalized brief under `{target}/.campaign-runtime/input/`, the Build Packet, the build context, the Assembly Report and the doctor-sidecar stale stamp, and sends nothing. It refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief. 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, build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and history is never used as current proof.
+**Saving brief answers.** `campaigns-os record brief --packet <packet>` saves Campaign Build Brief answers without re-running `start` or `prepare-build`. It writes the normalized brief under the funnel's runtime directory (`{runtime}/input/`), the Build Packet, the build context, the Assembly Report and the doctor-sidecar stale stamp, and sends nothing. It refuses a path that points at one of the files Campaigns OS writes itself, such as the normalized brief. 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, build, Polish and QA are owed again. When only `qa_policy` changes, QA alone is owed again. Setup and deploy records are kept. Each replaced record is kept under the stage's `history`; the last five superseded records per stage are kept, and history is never used as current proof.
 
-**Binding a CampaignSpec change.** `campaigns-os record spec --packet <packet>` binds the new CampaignSpec 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`. It writes the build context, the Assembly Report, the normalized brief and the doctor-sidecar stale stamp; it does not write the Build Packet, and it sends nothing. `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.
+**Binding a CampaignSpec change.** `campaigns-os record spec --packet <packet>` binds the new CampaignSpec 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`. It writes the build context, the Assembly Report, the normalized brief and the doctor-sidecar stale stamp, and it sends nothing. It writes the Build Packet and the Design Source Package only when it binds a page change: a move of routes alone, or on a handed-off campaign (deploy or QA completed) a page added or removed; then a deploy recorded without a build fingerprint is owed again too when the set of built pages changes (a fingerprint-bound deploy is made owed by the next `record build`). A rerun after a run that stopped part way moves the Design Source Package references that run left behind. `spec derive` no longer rebinds identity; run `record spec` after it. A change to the order of active pages, or a page added or removed before handoff, still needs intake.
 
-Both rows are tier C, because a change makes recorded stages owed again, and each `--dry-run` form is tier none: it writes nothing and appends no lifecycle entry. 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`. Intake now also refuses, without `--force`, to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation; with `--force`, it keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed.
+Both `record` rows are tier C, because a change makes recorded stages owed again, and each `--dry-run` form is tier none: it writes nothing and appends no lifecycle entry. 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`. Intake now also refuses, without `--force`, to discard recorded waivers, warning accepts, stage history, an applied theme, or a recorded deploy target, preview URL, production URL, order-path depth or allowed-domains confirmation; with `--force`, it keeps stage history, archives the build, Polish and QA records it clears, and keeps the record that the inputs changed.
+
+**`spec derive` and the live campaign.** Once the campaign is built (its `_site/<route>/` exists) and a public Campaigns API key resolves, `spec derive` makes the same read-only `GET {proxy-base}/api/campaign` doctor makes and refreshes the offer and package fields the spec mirrors from the Campaigns App; `--dry-run` makes it too, so the diff shows those fields. `--no-live-refs` sends nothing (its own row, tier B). `spec derive` and its `--dry-run` are tier A.
 
 ## How to read a row
 
@@ -164,8 +168,9 @@ flags that change what the invocation does to the world are listed once, in
 `vocabulary.effect_changing_flags`: `--apply`, `--browser`, `--built`, `--dry-run`,
 `--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
 `--no-live-refs`, `--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
-`--no-write`, `--republish`, `--test-order`, `--write`, `--write-map`. Flags
-that only change the output shape (`--json`, `--report`) deliberately do not.
+`--no-write`, `--republish`, `--test-order`, `--vendor-beacons`, `--write`,
+`--write-map`. Flags that only change the output shape (`--json`, `--report`)
+deliberately do not.
 
 **"The help text" is every help block the CLI prints**, not one file's.
 `campaigns-os qa` prints its own from `src/qa-node.mjs`, and while the coverage
@@ -253,6 +258,9 @@ input resolution. They append no lifecycle entry. Accepted modes remain
 `accept`, `decline`, and `both` (case-insensitive); browser `--test-order` still
 takes precedence and does not require the legacy cart. API credentials are
 still checked only inside the legacy handler and failures there are journaled.
+A `qa run --vendor-beacons` value other than `live`, or `--vendor-beacons` on
+a run without browser `--test-order`, is likewise an argv-only refusal before
+QA input resolution.
 The nested run-record refusal scope in session closeout guards against future
 changes. No internal closeout can currently create a refusal before its
 invoking command journals.