@nextcommerce/campaigns-os 1.43.2 → 1.47.0

package/docs/build-packet.md

@@ -69,7 +69,7 @@ localhost readiness is not production approval.
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
 that stays the default. A campaign whose whole funnel is served from the **site
-root** — pages at `/checkout-v2`, `/oto-ruggie`, `/receipt` with no slug prefix,
+root** — pages at `/checkout-v2`, `/oto-rootfunnel`, `/receipt` with no slug prefix,
 the normal shape for a single-campaign site or an in-place static deploy —
 declares `campaign.route_root: "/"`. Rules:
 
@@ -85,7 +85,10 @@ declares `campaign.route_root: "/"`. Rules:
 - Doctor's routing-meta checks (`routing_meta.runtime_root`,
   `sdk_hints.meta_tags.route_mismatch`) and route displays validate against the
   declared route root instead of assuming slug-as-prefix, so a root-served
-  funnel's correct `/receipt`-style metas pass without waivers.
+  funnel's correct `/receipt`-style metas pass without waivers. A routing
+  meta value with a bare or `//` host in front of its path is not a
+  `runtime_root` warning; it is the `routing_meta.host_prefixed` blocker (see "Page Kit
+  Target Projection" below).
 - The CampaignSpec may carry the same declaration at `campaign.route_root` (or
   `spec_identity.route_root`); `prepare-build` copies it onto the packet and
   defaults `live_url_path` to `/`.
@@ -112,6 +115,22 @@ Before scaffold, a missing target entry is `not_applicable`; once setup or
 assembly is terminal, or the target output already exists, missing or malformed
 target evidence is a non-waivable blocker. Target-only values remain warnings.
 Mismatches, missing required target values, and known demo residue block.
+An absent or null spec field means "not provided". An explicit empty (or
+whitespace-only) string in one of the eight optional fields (`store_name`,
+`store_terms`, `store_privacy`, `store_contact`, `store_returns`,
+`store_shipping`, `store_phone`, `store_phone_tel`) means the merchant has no
+such value: `page-kit sync` blanks a recognised starter demo value with it
+(the placeholder storefront URLs and phone number; the starter's demo store
+name is not recognised and stays a `target_only` warning), and a blank or
+absent target field then reads as `intentionally_empty` (clean, and named in
+the gate reason and the doctor line). `campaign.store_url` stays required: a
+`""` there still raises doctor's `spec.store_profile` error, and the gate
+reason says so. A real, non-demo target value against a spec `""` is left as
+it is and stays a `target_only` warning, because Maps saved `""` for every
+cleared store field before it meant empty; the warning and the sync output
+(`spec_empty_not_applied[]`) say the `""` was not applied, so remove that value
+by hand if the merchant has none. An empty string outside these fields
+carries no such meaning.
 Demo residue (a `demo.29next.com` URL or the demo phone number still in the
 target) is never waivable: the gate names the residue fields, offers no waive
 command for them, and `checkpoint waive` refuses with those fields until the
@@ -142,9 +161,15 @@ re-saving the Map). The repo pin is the authority for what ships and the Map
 field is a build hint, so that state is a doctor warning, not a blocker (see
 the SDK version checkpoint below). Both go into `_data/campaigns.json[public_route_slug]`,
 prints a field-by-field before/after diff, and touches nothing else: a
-governed field the spec does not carry is left as it is (doctor's
-`target_only` warning still applies), non-governed keys keep their values and
-order, other routes and other files are not written. The file is edited in
+governed field the spec does not carry (absent or null) is left as it is
+(doctor's `target_only` warning still applies), a field the spec sets to `""`
+(or whitespace only) blanks a recognised starter demo value (the placeholder
+storefront URLs and phone number; the starter's demo store name is not
+recognised and stays a `target_only` warning) and otherwise leaves the target
+value as it is (listed in `not_in_spec[]` as before and also in
+`spec_empty_not_applied[]`, printed as `Spec "" not applied`), non-governed
+keys keep their values and order, other routes and other files are not
+written. The file is edited in
 place and re-serialized with its own top-level indentation, line ending and
 trailing newline; when that round trip would not have reproduced the file
 byte for byte (a minified file, mixed indentation), a
@@ -724,13 +749,14 @@ built-output gate now carries.
 ### Built-output SDK markup gate (`built_output.sdk_markup`)
 
 Every doctor run that sees built output also runs the static SDK markup
-family: six shapes of `data-next-*` markup that the Campaign Cart SDK binds
+family: seven shapes of `data-next-*` markup that the Campaign Cart SDK binds
 without complaint and that then either do nothing (a field that never reaches
 the order, a button that never enables) or write the cart twice. They sit
 beside `built_output.upsell_selector_scope`, which is the same kind of check
-for one shape. The codes are the ones a partner Campaign Cart kit used, kept so
-the two vocabularies line up; each doctor issue is `built_output.sdk_markup.`
-plus the code lower-cased, and its message leads with the code.
+for one shape. The first six codes are the ones a partner Campaign Cart kit
+used, kept so the two vocabularies line up; each doctor issue is
+`built_output.sdk_markup.` plus the code lower-cased, and its message leads
+with the code.
 
 Blockers (not waivable — the markup provably does not do what it says):
 
@@ -752,6 +778,12 @@ Blockers (not waivable — the markup provably does not do what it says):
   `data-next-selector-id` names no selector on the page (an element that is a
   bundle, package, cart or upsell selector; another element echoing the id
   does not count). One finding per dead id, however many buttons link to it.
+- `ORPHANED_UPSELL_ACTION` — an element carrying `data-next-upsell-action` with
+  no ancestor carrying `data-next-upsell`. The SDK binds upsell actions only
+  inside that container, so a "No thanks" link placed beside the offer
+  container, not inside it, goes nowhere and the shopper cannot decline.
+  Checked on every page type, not only upsell and downsell pages. Move the
+  element inside its `data-next-upsell` container.
 
 Warnings (advisory):
 
@@ -826,15 +858,35 @@ file. A referenced local script that is not in the built output is a warning,
 not a blocker, under `built_output.script_syntax.missing_script`, one warning
 per src naming the pages that load it: the browser gets a 404 for it and
 nothing it would define runs, but whether the page needs it is not known here.
+Missing scripts are grouped by the URL the browser resolves, not the raw src,
+so `check&#9;out.js` and `checkout.js` (the URL parser removes the tab) are one
+warning; the src shown is the first spelling met.
 The src is also listed in `scripts_unresolved[]`. While a parse failure blocks
 the gate, the missing scripts stay on the gate's `warned[]` rather than also
 surfacing as warnings.
 
+A `<script>` the page ends inside, with no `</script>` before end of file, is
+not parsed: the browser never runs a script element whose end tag never
+arrives. Doctor warns about it under `built_output.script_syntax.unclosed_script`,
+one warning per page, because a page that ends mid-script is usually truncated
+output. QA neither fetches nor parses such a script.
+
+**Symlinks under `_site`.** A script that is a symlink, or sits under a
+symlinked directory, is read the way a static server serves it, by following
+the link, as long as its real path stays inside the site root (`_site/`). A
+parse failure in it is reported under the path the page loads. A script whose
+real path resolves outside the site root is not read. Doctor warns, and does
+not block, under `built_output.script_syntax.symlink_outside_site`, naming the
+link (never its target) and saying the target is outside the site root. The
+link is listed in `scripts_outside_site[]` with `file`, `src` and `pages`, not
+in `scripts_unresolved[]`.
+
 The gate's evidence lands beside the other checkpoint gates at
 `derived.checkpoint_gates[]` (`id: built_output.script_syntax`, status `pass` |
 `blocked` | `not_applicable`, `findings[]` with `file`, `line`, `column`,
-`source_type` and `pages`, `warned[]` with `src` and `pages`,
-`scripts_scanned`, `scripts_unresolved[]`, `pages_scanned`). Fixtures: `fixtures/script-syntax/{good,bad}`. It passes, parsing every
+`source_type` and `pages`, `warned[]` with `code`, `src` and `pages` (and
+`file` for a symlink outside the site root), `scripts_scanned`,
+`scripts_unresolved[]`, `scripts_outside_site[]`, `pages_scanned`). Fixtures: `fixtures/script-syntax/{good,bad}`. It passes, parsing every
 local script the pages load and with no missing-script warning, on the
 canonical rendered output of every certified starter family
 (`fixtures/certified-families/`). QA applies the same rule to the page scripts
@@ -1038,9 +1090,9 @@ fingerprint is `sha256:` plus the SHA-256 of that manifest. Nothing is excluded
 default (Page Kit writes only rendered HTML and copied assets into `_site/`, nothing
 it timestamps); `.campaign-runtime/page-kit-build-summary.json` lives outside the
 root and is not hashed. Build does not type the value: after page-kit build it runs
-`campaigns-os doctor --packet <packet> --json` and copies
-`derived.build_output_fingerprint.value` (with `.file_count` and `.status`) onto
-`stages.assembly.build_fingerprint`. Doctor recomputes the value on every run
+`campaigns-os record build --packet <packet>`, which stamps doctor's
+`derived.build_output_fingerprint.value` onto `stages.assembly.build_fingerprint`
+(see "Recording stage completion" below). Doctor recomputes the value on every run
 (`built_output.fingerprint`): a match is a ready line, a missing record is the
 warning `built_output.fingerprint_missing` carrying the value to record, and a
 recorded value the output no longer matches is `built_output.fingerprint_stale`
@@ -1064,9 +1116,11 @@ Design Source Package exists. The waiver must remain visible in Campaign
 Readiness Readback and downstream QA evidence; it is not a silent pass.
 In v0, write accepted Source Freshness Waivers directly into `waivers[]`.
 `campaigns-os checkpoint waive` is a staged generic registry and currently
-accepts four gates: `page_kit.store_profile`, `page_kit.sdk_version`,
-`polish.hidden_eager_media`, and `built_output.upsell_selector_scope`; an
-unregistered gate id is refused with that list. `theme waive` applies the same
+accepts five gates: `page_kit.store_profile`, `page_kit.sdk_version`,
+`polish.hidden_eager_media`, `built_output.upsell_selector_scope`, and
+`source_html.producer_provenance`, which is waived per page with
+`--page <page_id>` (see the [Design Source Package](./design-source-package.md)
+hand-written HTML route); an unregistered gate id is refused with that list. `theme waive` applies the same
 attribution rule (a named human, no placeholder, an optional future
 `--expires-at`) on its own lane. Within Polish, only the broader Source Freshness
 waiver retains its existing report path; theme and QA decisions retain their
@@ -1225,13 +1279,13 @@ and report proof policy fields above.
 | `--spec <path>` | Local JSON file | Agent-authored local specs, saved-Map exports, offline work or CI fixtures |
 | `--map-id <id>` | Map Builder proxy (KV-backed) | Saved-Map intake from the current KV revision |
 
-When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode.
+When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode. When the Map holds routes with a host in front of the path, the cached file holds the rooted routes and that run's Assembly Report `evidence[]` holds the values as fetched (see "Page Kit Target Projection" below). The cache is written only inside a real `fetched-specs/` directory: if `.campaign-runtime/`, `fetched-specs/` or the cache file is a symlink, the command stops with an error before fetching and writes nothing. Each write goes to a new file renamed over the cache file, so a hard link to the old file keeps its bytes.
 
 Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
 - **One writer at a time.** The fetch happens first, but the fetched spec is written to the cache file only once the run holds the per-target prepare-build lock. A second run against the same target, fetching a newer Map revision, waits for the lock before replacing the cache, so the run holding it records the hash of the revision it actually parsed.
-- **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
+- **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable. The cached copy is read as it is and never rewritten.
 - **`--proxy-base <url>`** overrides the default origin. Use for staging environments or local Worker dev (`wrangler dev`). Spec retrieval carries no credential, so any reachable origin works here — but the same flag also aims the credential-bearing rails (Run Telemetry remit, QA verdict publish, `telemetry list`), and those require `https:` unless the host is loopback (`localhost`, `127.0.0.1`, `[::1]`), which is allowed over plain http with a stderr warning. A plain-http remote proxy is refused before the request. See docs/workflow-findings-sidecar.md (Remit Channel).
 - Failure modes (HTTP error, `{ok: false}` response, network timeout) surface as clean CLI errors before any packet is written.
 
@@ -1321,6 +1375,70 @@ routes during projection. That normalization strips `.html`/`index.html`,
 removes query/fragment values, converts absolute preview URLs to their path, and
 normalizes trailing slashes before deriving target files and frontmatter routes.
 
+A route value with a host in front of its path (an older saved Map stored
+`shop.example.com/route/upsell/` where the route is `/route/upsell/`) is
+reduced to its rooted path before anything reads a spec that `prepare-build`,
+`start` or `build` fetched with `--map-id` in the same run. This covers every
+`page_url` and every `next-success-url`, `next-upsell-accept-url` and
+`next-upsell-decline-url` meta tag value in `funnels[].pages[]` and
+`funnel_pages[]`:
+
+- The host is removed and the path is kept with its query and fragment
+  (`shop.example.com/route/x/?v=b#top` becomes `/route/x/?v=b#top`). An
+  absolute `http(s)` `page_url` is rooted the same way; an absolute `http(s)`
+  routing meta value is a valid SDK target and is kept.
+- The fetched copy at `<target>/.campaign-runtime/fetched-specs/<map-id>.json`
+  then holds the rooted values, not the bytes as fetched. It is replaced only
+  after the Assembly Report recording the changes has been published, so if
+  publishing fails the copy is left exactly as fetched. The rooted spec is
+  written to a new file in `fetched-specs/` and renamed over the copy, so
+  another name for the old file (a hard link) is never changed. A spec with
+  no host-prefixed value is written exactly as fetched, as before.
+- Each changed value is recorded on that run's Assembly Report `evidence[]` as
+  `{ "code": "routing_meta.host_stripped", "page_id", "field", "from", "to" }`;
+  `from` is the value exactly as the Map returned it. The raw values are kept
+  only there and in the Map itself: a later run with `--cached-spec` reads the
+  rooted copy, finds nothing to strip, and records no evidence. One line on
+  stderr lists the changes.
+- `intake.saved_map_revision.local_spec_material_hash` in the Build Context is
+  the material hash of the rooted copy, while `hash` stays the fetched Map
+  revision. A progress snapshot's `saved_revision_alignment: "aligned"`
+  therefore means the local spec matches that Map revision after host
+  stripping, not byte for byte.
+
+A local `--spec` file and a copy reused with `--cached-spec` are never
+rewritten. When either holds a value doctor blocks on (below), intake reads it
+as it is and prints one line on stderr naming each value and its rooted form:
+for a local file, that the file must be edited; for `--cached-spec`, to re-run
+without `--cached-spec` so the Map is fetched and normalised.
+
+A value reads as host-prefixed when it is one of:
+
+- an `http://` or `https://` URL, with any host (stripped from a fresh fetch;
+  never blocked);
+- `//<host>/...`, where `<host>` is one of the bare host forms below;
+- `<host>/...`, where `<host>` is `localhost`, a valid IPv4 address (four
+  dot-separated numbers, each 0-255), any name with a `:port`
+  (`localhost:8080`, `shop.example.com:8443`), or a dotted name whose last
+  label is 2-63 letters and is not a page or script extension: `html`, `htm`,
+  `shtml`, `php`, `asp`, `aspx`, `jsp` or `cgi` (`shop.example.com`,
+  any case).
+
+Everything else stays a route for the existing checks: a rooted `/...` value,
+a first segment with no dot (`route/x/`), a dotted segment whose last label is
+not all letters (`v1.2/offer/`), a dotted quad with a number over 255
+(`300.1.2.3/offer/`), a page or script filename (`checkout.html`,
+`index.php/checkout/`, `upsell.aspx/`), `//` followed by something that is not
+a host (`//route/x/`), a bare host with no path, and an empty or missing value.
+
+If a bare or `//` host-prefixed value still reaches doctor (a local spec that
+holds one, a copy reused with `--cached-spec`, or a spec edited after intake),
+doctor blocks with `routing_meta.host_prefixed`, naming each value and its
+rooted form. An absolute `http(s)` value never raises it: projection converts
+an absolute `page_url` to its path, as above. `page_url` is checked whether or
+not the site is built; routing meta values follow the same built-output
+deferral as `routing_meta.runtime_root`.
+
 This prevents mixed-source manifests such as `checkout/index.html` from leaking producer folder structure into `src/<slug>/checkout/index.html`. Campaigns OS owns the Adapter from source/manifest/CampaignSpec into Page Kit shape; Page Kit remains the target.
 
 `target_path` intentionally uses the terminal route segment (`checkout/step-1/`
@@ -1477,10 +1595,49 @@ The motion:
 
 ```text
 agent calls `next` → gets { stage, prompt, picked_reason } → does the work →
-updates assembly report's stages.<name>.status → calls `next` again →
-repeat until stage="done"
+records it (`campaigns-os record setup|build|polish`; deploy and QA record their
+own stages) → calls `next` again → repeat until stage="done"
 ```
 
+### Recording stage completion
+
+Setup, build and polish completion is recorded with one command each, never by
+hand-editing `.campaign-runtime/` JSON:
+
+| Command | Writes | Refused (nothing written) when |
+|---|---|---|
+| `campaigns-os record setup --packet <p>` | Build Context `scaffold.required=false` (`handoff_skill` next-campaigns-build) and `stages.setup` completed | the campaign output directory (`assembly.output_dir`) does not exist, or there is no Build Context or Assembly Report |
+| `campaigns-os record build --packet <p>` | `stages.assembly` completed with `build_fingerprint` = doctor's `derived.build_output_fingerprint.value`, `source_package_material_fingerprint` = the report's Design Source Package material fingerprint when present, and `stages.polish` reset to `required` (`required_by` build, `required_for` qa) unless its evidence is bound to this exact output | doctor cannot compute the fingerprint (no `_site/<public_route_slug>/`), setup is still required, or `stages.setup` is not terminal |
+| `campaigns-os record polish --packet <p> --evidence <file>` | `stages.polish` from the file (`docs/polish-evidence.md` §7: completed, blocked or skipped), bound to doctor's current fingerprint; `report.theme.repair_loop_defect` when the file sets it | build is not recorded for the current output, the file has a shape error (named by field), or, for a completed status, the polish gate doctor evaluates would not pass on the result |
+
+Each command also refuses a stage `next` has not reached: while doctor's
+prepare-build gate is set (`next` answers prepare-build) or while an earlier
+stage in the order below is not terminal.
+
+Each command reads the same packet, Build Context and Assembly Report `next`
+reads (`--context` / `--report` override them the same way), validates what it
+would write against `schemas/campaign-runtime-build-context.v0.schema.json` and
+`schemas/campaign-runtime-assembly-report.v0.schema.json` plus doctor's report
+checks, and then writes under the target lock, stamping any retained doctor
+output stale. The packet is read once first, only to name the target lock, and
+re-read and re-checked under it: which report the Build Context binds, the
+report itself, the Build Context and doctor's reading (the fingerprint and the
+binding) are all read inside the same target lock as the write, and the
+fingerprint is computed once more just before the write; output
+that changed in between is refused, never recorded with the old value. Every
+command refuses a report that is not bound to the packet: whenever doctor's
+prepare-build binding gate fails (`next.prepare_build.context_missing`,
+`context_packet_mismatch`, `context_dsp_mismatch`, `context_report_missing`,
+`report_packet_mismatch`, `report_context_mismatch`, `report_campaign_mismatch`
+or `report_dsp_mismatch`, the refusals `next` answers with prepare-build), and
+whenever the report's campaign identity does not match the packet, including
+for packets with no Design Source Package. Every command also adds
+`recorded_by`, and `completed_at` unless it records a blocked Polish, to the
+stage it records. `--dry-run` runs every check, takes no lock and writes nothing. A failed
+check exits non-zero with the problems listed, one per line. Re-run `record
+build` after every page-kit build; a rebuild that changes the output needs
+`polish capture` and `record polish` again.
+
 Stage order: `setup → build → polish → deploy → qa`. The picker walks this list and returns the first stage whose recorded status isn't terminal (`completed`, `completed_with_warnings`, `skipped`). During Polish, install the package-owned browser first, then run `campaigns-os polish capture` against the served current build before recording a terminal `stages.polish.status` or proceeding to deploy/QA; the producer attaches package-owned `visual_review.page_load` evidence and never marks the stage complete itself.
 
 | Stage | Report key | Owner |
@@ -1523,8 +1680,8 @@ The legacy form `campaigns-os next <stage>` (e.g. `next build`) still works and
 
 CampaignSpec pages may carry an optional `design_source` block on `Page` — a pointer to the design artifact (Figma file + per-breakpoint selection URLs) that supplies prepared HTML for that page. When doctor detects an active spec page with no source mapping, the `source_html.pages.coverage` error now carries a hint that points the operator at the design source:
 
-- `design_source.type === "figma"` with `file_url`: doctor calls out the Figma file and the figma-sections-export handoff command (`npm run handoff -- <slug>`).
+- `design_source.type === "figma"` with `file_url`: doctor calls out the Figma file and says the Figma provenance gate (`source_html.producer_provenance`) needs the figma-sections-export handoff manifest (`npm run handoff -- <slug>`); a hand-written manifest cannot pass that gate.
 - `design_source` set without `file_url`: doctor flags the missing `file_url` so the spec can be corrected.
-- `design_source` unset: doctor keeps the original generic coverage error.
+- `design_source` unset, `ai-generated`, or another producer type: the message names the manifest path (`<source-root>/.campaigns-os/source-html-manifest.json`), the schema, and a minimal page entry to write by hand (no exporter is needed), plus `"wrapper_policy": "preserve_document_wrappers"` for standalone documents kept whole. When any active page's `design_source` is Figma, it instead says the manifest must pass the Figma provenance gate.
 
 The error code (`source_html.pages.coverage`) is unchanged so existing doctor consumers do not need to be updated; only the human-readable `message` and an optional `detail.design_source` payload are added.

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

@@ -83,10 +83,10 @@ 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); one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first four 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`, `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. 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`).
 - **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"`, adopt the selected starter-template family shell for that runtime page. Do not build a custom checkout/upsell structure around a few borrowed includes; browser QA will check declared family structure where `agentContract.qaStructure` exists.
+- 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.
 - 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/`.
@@ -95,7 +95,7 @@ the assembly report.
 - Any source element dropped because the spec does not support it, such as PayPal when `available_payment_methods` excludes PayPal, should be recorded in the assembly report for polish.
 - After page-kit build, doctor checks rendered local script references plus rendered package and shipping refs against the CampaignSpec. Missing built scripts, stale package IDs, stale shipping IDs, and unavailable package refs must be fixed or intentionally blocked before QA.
 - Browser QA opens SDK-owned runtime pages once as a shopper and once with `?debugger=true`. The debugger pass should prove the Campaign Cart debugger overlay and selector controls mount without changing the normal checkout/test-order flow.
-- Browser QA also checks template-family commerce structure when the family contract declares machine-checkable selectors. Missing required Limos checkout shell markers, for example, are treated as a warning-severity failure: the checkout may load, but it is not proven as a conformant Limos checkout.
+- Browser QA also checks template-family commerce structure when the family contract declares machine-checkable selectors. It checks what the checkout does, not family class names: a missing family shell selector (a wrapper or column class, or the shipping field row marker) is a warning when the checkout form, its bound fields and a visible total all pass, and a failure when any of them does not. A missing SDK selector is always a warning-severity failure. See [QA and test orders](qa-and-test-orders.md).
 
 ## Synthetic Campaigns
 

package/docs/design-source-package.md

@@ -728,6 +728,79 @@ the packet file, so a packet resolves its source from the location it was
 written at: replay a run from the same place, or expect doctor to report
 `source_html.root` as missing.
 
+### Hand-written HTML behind a Figma design source
+
+A saved Map page with `design_source.type: figma` (or a `figma.com` file URL)
+makes doctor demand figma-sections-export provenance from the source-html
+manifest: a semantic `producer_provenance` block, section exports, a
+material fingerprint, and the export's section partials and assets in
+`files[]`. When the approved source for that page is hand-written HTML and the
+Figma file only renders it, no export exists, and doctor reports the
+`source_html.producer_provenance*`, `source_html.files.partial` and
+`source_html.files.asset` errors. Leave `design_source` on the Map and take
+this route instead:
+
+1. Write the source-html manifest by hand (the record shape and the
+   `screenshots[]` proof are above). Give each page its `page_id` and `path`
+   and its desktop and mobile screenshot records, and list the page files in
+   `files[]` with `role: "page"`. Do not add `partial` or `asset` entries the
+   HTML does not have: the waiver covers their absence. Set `generator` to
+   the tool or person that wrote the HTML, never to `figma-sections-export`.
+2. If the HTML files are full documents (`<!doctype>`, `<html>`, `<head>`,
+   `<body>`), set `"wrapper_policy": "preserve_document_wrappers"` in the
+   manifest so the wrapper finding is a recorded decision, not a blocker (see
+   [docs/source-adapters.md](./source-adapters.md#selecting-the-wrapper-policy-at-intake)).
+3. Record a named-human waiver for each such page:
+
+   ```bash
+   campaigns-os checkpoint waive \
+     --packet campaign-runtime.build.json \
+     --gate source_html.producer_provenance \
+     --page <page_id> \
+     --reason "<why the approved source is hand-written HTML>" \
+     --waived-by "<named human>" \
+     --expires-at <ISO timestamp>
+   ```
+
+   `--page` is required, and it must name an active CampaignSpec page with a
+   Figma design source; any other id is refused and the refusal lists the pages
+   that qualify. The `<gate>:<page_id>` spelling is refused too. As with every
+   `checkpoint waive` gate, a placeholder name is refused, one bound
+   (`--expires-at` or `--review-condition`) is required, and `--dry-run`
+   validates the waiver and writes nothing. A value-taking flag given without
+   a value is refused, never read as the text `true`.
+
+Doctor reports the Figma-export findings (the `source_html.producer_provenance*`
+codes, `source_html.files.partial` and `source_html.files.asset`) once for each
+Figma-typed page, with the page in `detail.page_id`. While a page's waiver is
+active, its findings are reported as warnings carrying `waived: true`, its
+checkpoint gate reports `waived`, and doctor and `next` report
+`ready_with_waivers`, never clean. A waiver covers only its own page: another
+Figma-typed page without one still gets the findings as errors, and doctor
+stays blocked.
+
+When the manifest's `generator` names `figma-sections-export` in any form
+(with or without an `@<version>`, in any case), the manifest claims to be a
+real export, so the missing provenance is the export's own defect: doctor
+reports the findings once, manifest-wide, as errors, and each page's
+checkpoint gate reports `blocked` with the code
+`source_html.producer_provenance.exporter_claim` and the repair action.
+`checkpoint waive` refuses the gate in that state, and a waiver recorded
+before the generator changed is reported as inert.
+
+The waiver covers the Figma-export findings only. Manifest validation, the
+wrapper policy, source-preparation findings, page mappings and the screenshot
+proof at `prepare-build` keep their own severity.
+
+The waiver is recorded against the page's exact state: its design source and
+the provenance findings doctor reported when it was recorded. A change to either
+makes it stale, an expired waiver no longer applies, and doctor blocks again. A
+waiver for a page that no longer has a Figma design source (its `design_source`
+changed, or it left the spec), or one under a manifest whose generator claims
+figma-sections-export, is reported as
+`source_html.producer_provenance.waiver_inert`, a warning, like the other
+checkpoint gates' inert waiver history.
+
 ## Lifecycle ownership and freshness
 
 Prepare owns source normalization and the three package references. It records

package/docs/effects.md

@@ -38,8 +38,10 @@ that already understands those hints needs no translation layer.
 **`readOnlyHint` counts the command-lifecycle journal.** A journal append is a
 write like any other, so every `readOnlyHint: true` row is an invocation the
 CLI exempts from lifecycle capture (the converse does not hold: `demo` and the
-`--no-write` forms skip the journal but still write other declared files): `help`, `readback`,
-`run status`, `doctor` inspection, `doctor --no-write`, `sdk storage-check`,
+`--no-write` forms skip the journal but still write other declared files, and
+`doctor` inspection and `doctor --no-write` skip it and write nothing but may
+send the one live campaign read): `help`, `readback`,
+`run status`, `doctor --no-live-refs` inspection, `sdk storage-check`,
 `tooling diagnose`, a refused invocation, `run-record --no-write`, and every
 `--dry-run` form on the commands that implement the flag. Everything else
 appends an entry when a journal is selected — an active run session,
@@ -81,6 +83,46 @@ 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.
 
+### The Map Builder fetch
+
+`start`, `prepare-build` and `build` take their CampaignSpec from `--spec` or
+from `--map-id`. With `--map-id` (and no `--cached-spec`) the invocation sends
+`{proxy-base}/api/spec/{map-id}` and writes what comes back to
+`{target}/.campaign-runtime/fetched-specs/<map-id>.json`, replacing any earlier
+copy of that Map; the intake then reads the spec from that file. Both effects
+are on every row for those three commands. The effect test runs each row with
+`--spec` under four conditions and with `--map-id` under `persisted_consent`,
+the one condition whose `--proxy-base` is the loopback receiver, so the fetch
+and the write are observed rather than taken on trust.
+
+### The live campaign read
+
+`doctor --packet` (with or without `--write` / `--no-write`) and every `qa run`
+form check each page's shipping and package refs against the live campaign.
+Doctor reads when the packet's built `_site/<route>/` exists; QA reads when it
+has read at least one served page. Both need a public Campaigns API key from
+the packet, its local CampaignSpec or the declared campaign-key env var. The
+read is one `GET {proxy-base}/api/campaign` with the key in `X-Campaign-Key`,
+plus `?ref_id=<id>` when the CampaignSpec's `campaign.ref_id` names the
+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
+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
+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`,
+`checkpoint`, `findings harvest`, `run-record`, `next`, and the doctor
+sidecar refresh `qa run` makes after it records the QA stage (the verdict
+itself carries QA's own read).
+
 ## How to read a row
 
 ```jsonc
@@ -108,7 +150,7 @@ There is **one row per command and per effect-changing flag combination**. The
 flags that change what the invocation does to the world are listed once, in
 `vocabulary.effect_changing_flags`: `--browser`, `--built`, `--dry-run`,
 `--emit-packet`, `--example`, `--force`, `--from-store`, `--list`,
-`--no-post-verdict`, `--no-probe`, `--no-remit`, `--no-run-session`,
+`--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.
 
@@ -217,7 +259,7 @@ sha256) before and after while a loopback `node:http` receiver counts requests.
 | `ambient_session` | An active ambient run session opened by `run start` at the target. |
 | `stale_session` | A run session idle past the 12 h TTL, at the target and at the working directory. |
 | `lifecycle_log` | `CAMPAIGNS_OS_LIFECYCLE_LOG` names a journal outside the runtime directory. |
-| `persisted_consent` | Run Telemetry consent **persisted on the machine for the loopback receiver's scope**, a synthetic campaign key in the environment, no run session, and `--proxy-base <loopback>` wherever the command takes it. |
+| `persisted_consent` | Run Telemetry consent **persisted on the machine for the loopback receiver's scope**, a synthetic campaign key in the environment, no run session, and `--proxy-base <loopback>` wherever the command takes it. `start`, `prepare-build` and `build` name their spec by `--map-id` here, and the receiver serves it. |
 
 Five conditions rather than one, because the CLI's effects are not a function of
 argv alone: an ambient session redirects the journal and is itself touched by
@@ -319,10 +361,10 @@ loopback receiver only stands in for (`{base-url}`, the login gateway) matched
   refuses the contradiction rather than letting the test find it.
 
 A `full` row may still carry an individual effect the offline fixture cannot
-reach — the Map Builder spec fetch behind `--map-id`, the `codex` and `agents`
-destinations of `install-skills`. Each such entry has an empty `observed_in`
-**and** a `not_observed_reason`, and `check-effects.mjs` refuses one without the
-reason. What it may not be is silent.
+reach — the `codex` and `agents` destinations of `install-skills`. Each such
+entry has an empty `observed_in` **and** a `not_observed_reason`, and
+`check-effects.mjs` refuses one without the reason. What it may not be is
+silent.
 
 ## The rule
 

package/docs/gateway-login.md

@@ -17,6 +17,9 @@ campaigns-os login --store example
 There is no discovery or guess from the current project. Noninteractive calls
 must supply `--store`. URLs, paths and unrelated hosts are refused before any
 request. Login uses the fixed `https://mcp.nextcommerce.com` gateway.
+It asks for the `https://mcp.nextcommerce.com/mcp` resource and the
+`campaigns.read` capability. A login saved before 1.43.2+agent.3, which named
+the earlier `/campaigns` resource, is refused; sign in again.
 
 Open the displayed device page in one browser tab and enter the displayed code.
 Keep that tab: if installation is needed, follow its Install Campaigns link,

package/docs/local-setup.md

@@ -3,18 +3,21 @@
 For a new campaign, choose its working folder and run this from that folder:
 
 ```sh
-npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.2 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+npm install --save-exact next-campaign-page-kit@0.2.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.47.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
 ```
 
 Review the release source/provenance before installation as described in
 `AGENTS.md`. npm installs the dependencies first; `--no-install` then runs only
-the project's installed CLI. Keep `package.json` and `package-lock.json` in
-Git. For an existing project, preserve its reviewed pin: run `npm ci`, then
+the project's installed CLI. Page-kit stays a runtime dependency and the
+toolkit a dev dependency: installing page-kit with `--save-dev` would move it
+out of `dependencies` and break builds that run `npm ci --omit=dev`. Keep
+`package.json` and `package-lock.json` in Git. For an existing project, preserve its reviewed pin: run `npm ci`, then
 `npx --no-install campaigns-os tooling setup --target . --platform claude`
 on a release that supports setup. Changing the pin is a separate update.
 
 Setup checks the exact toolkit pin, its lockfile version and the installed
-page-kit dependency before it changes files. It composes the existing
+page-kit dependency before it changes files, and warns when page-kit is
+declared only in `devDependencies`. It composes the existing
 installers to:
 
 1. Install the QA browser through this toolkit's own Playwright package.