@nextcommerce/campaigns-os 1.33.0

package/docs/build-packet.md

@@ -0,0 +1,1300 @@
+# Build Packet
+
+The Build Packet is the campaign assembly handoff. It wraps, but does not replace, the CampaignSpec.
+
+It answers:
+
+- Which CampaignSpec and Map ID are we building?
+- Which public route slug and campaign directory are expected?
+- Where are the prepared HTML/assets?
+- Which Campaign Build Brief is the merchandising/design presentation truth?
+- Which target page-kit repo should be updated?
+- Which starter template family is locked?
+- Which commerce catalog/contract should the agent read?
+- Which deploy target, SDK origin state, and QA proof depth apply?
+
+The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
+
+## Root-Served Campaigns (`campaign.route_root`)
+
+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,
+the normal shape for a single-campaign site or an in-place static deploy —
+declares `campaign.route_root: "/"`. Rules:
+
+- `public_route_slug` stays **required** either way: it is the campaign
+  identity and the `_site/<public_route_slug>/` built-output directory name.
+  `route_root` describes the *served* path shape only.
+- When present, `route_root` must be `"/"` or `"/<public_route_slug>/"`; any
+  other prefix is a doctor blocker (`campaign.route_root`) because it would
+  contradict the slug identity the built-output checks root on. `qa run`
+  reads the packet by the same rule: a value doctor blocks never roots a QA
+  check either — QA audits the slug-prefixed default instead — so a
+  hand-edited packet cannot pass QA at a root doctor refuses.
+- 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.
+- 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 `/`.
+- Two `sdk_hints.meta_tags` keys older Map exports still carry, `next-currency`
+  and `next-predictive-address`, are not read by the Campaign Cart SDK (the
+  list is `src/sdk-meta-tags.mjs`; QA reads the same one). Doctor never
+  requires them from the built page: a spec that lists one gets a single
+  advisory warning per page, `sdk_hints.meta_tags.ignored_by_sdk`, naming the
+  key and the reason (`remove from the Map's page hints; the SDK does not read
+  it`), whether or not the tag rendered and before `_site/` exists. They are
+  never `sdk_hints.meta_tags.missing` and never appear in the pre-build
+  "CampaignSpec expects SDK meta tags (...)" list. The fix is an edit to the
+  Map's page hints, not to the build.
+
+Page-kit also needs `campaign.store_url` for `_data/campaigns.json`. Additional Store Profile fields live under `campaign.store_*` as optional storefront/legal metadata because they are not Campaigns API data: the operator enters them, or `spec derive --from-store` derives them from the store (see "Deriving the spec from the repo" below).
+
+### Page Kit Store Profile checkpoint
+
+Doctor compares the packet-local CampaignSpec to exactly nine governed fields
+in `_data/campaigns.json[public_route_slug]`, in this order:
+`store_name`, `store_url`, `store_terms`, `store_privacy`, `store_contact`,
+`store_returns`, `store_shipping`, `store_phone`, and `store_phone_tel`.
+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.
+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
+values are replaced.
+
+The repair is a command. A fresh page-kit scaffold (`campaign-init`) seeds the
+route's entry with the starter family's demo profile and pin, so this gate and
+the SDK-version gate below block on every first run; the values that clear
+them already exist in the CampaignSpec, and doctor and `next` print the
+reconcile as the gate's `repair_target` action:
+
+```bash
+campaigns-os page-kit sync --packet campaign-runtime.build.json [--dry-run] [--json]
+```
+
+The CampaignSpec is the authority for the Store Profile: those values are
+authored in the Map, never in the repo, so `page-kit sync` writes the nine
+fields the spec carries (`campaign.store_*`) unconditionally. The SDK pin is
+different. On an existing campaign the repo pin moves first and the Map/spec
+is stale until someone re-saves it, so a spec → repo write would undo a bump
+silently; sync therefore **seeds** `sdk_version` (`global_config.sdk_version`,
+or the `runtime.sdk_version` alias when the canonical key is absent): it
+writes the pin while the entry is still in scaffold state (the starter demo
+store profile is still in it) or when the target pin is older than the
+spec's, and refuses to move a configured campaign's pin backwards
+(`not_synced`, reason `target_newer`, naming both versions and pointing at
+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
+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
+`page_kit.sync.file_reformatted` warning says so, because the printed diff
+covers only the governed fields. `--dry-run` prints the same diff without
+writing. Exit 0 on success (including a no-op re-run); exit 2 with
+`page_kit.sync.*` error codes and nothing written when the packet cannot be
+read, the target entry or the spec is missing or not an object, the spec
+identifies another campaign (`spec_identity.public_route_slug` or `map_id`
+disagreeing with the packet: `page_kit.sync.spec_identity_mismatch`), or the
+resolved `_data/campaigns.json` lies outside the target repo through a symlink
+(`page_kit.sync.target_escapes_repo`).
+
+The spec is the authority, but the target is made authoritative only from a
+usable spec value. States the target cannot be made authoritative for are
+reported as `not_synced` with a reason, never written, and the run's status
+is `partial` (exit 0, since the writes that could happen did; doctor will
+still block): a conflicting or non-released spec pin; a spec field of the
+wrong type (`spec_invalid_type`, doctor's own blocker); a URL field that is
+not an http(s) URL or a `store_phone_tel` that is not a `tel:` URI of digits,
+spaces, dashes, parens and dots (templates put both into `href` attributes,
+where escaping does not neutralize another scheme); a value with control
+characters; the starter demo value itself in the spec; and starter demo
+residue in a governed field the spec does not carry (doctor blocks on that
+residue without a waiver, and sync has no spec value to write over it). For
+every one of those the gate's `repair_target` action is an edit naming the
+spec field, not the sync command, so `next` never loops on a repair that
+cannot make progress. Fix the spec, then sync again. (`store_contact` may
+also be a `mailto:` address, the one non-http value templates render as a
+contact link.) A gate under an active named-human waiver is a human decision
+sync does not reverse: its fields are reported `not_synced` with reason
+`waived` naming who waived, and the target stays as the waiver accepted it
+until the waiver is withdrawn from the Assembly Report. Sync reads the report
+doctor would (the one the Build Context binds, or `--report <path>`, which
+doctor appends to the printed command when it inspected a non-default
+report); unknown flags are rejected rather than ignored, so a mistyped
+`--dry-run` cannot become a write. After a write the retained doctor
+snapshot is marked stale; when the report records a terminal build, a
+`page_kit.sync.build_stale` warning says the rendered `_site/` was built
+from the old entry and points at the rebuild, because doctor's page-kit gates
+read `_data/campaigns.json`, not the built output. Re-run `doctor` and both
+gates report `pass` without a waiver.
+
+An intentional, evidence-backed mismatch or missing value may be accepted with
+the first gate in the staged checkpoint registry:
+
+```bash
+campaigns-os checkpoint waive \
+  --packet campaign-runtime.build.json \
+  --gate page_kit.store_profile \
+  --reason "<why correction is intentionally deferred>" \
+  --waived-by "<named human>" \
+  --review-condition "<specific re-evaluation trigger>"
+```
+
+Use `--expires-at <canonical-ISO-timestamp>` instead of, or alongside,
+`--review-condition`; at least one bound is required and an expiry must be later
+than `waived_at`. The decision is appended to the Assembly Report's top-level
+`waivers[]` and fingerprints the exact slug, relative target path, and governed
+discrepant field/value set. Stale, foreign, expired, or malformed records are
+inert. A current waiver produces checkpoint status `waived` and doctor/next
+readiness `ready_with_waivers`; it never becomes a clean pass. Raw arbitrary
+campaign entry fields are validation-private and never belong in doctor, next,
+sidecar, or QA evidence. The same boundary applies to waiver history: public
+gate/readback/QA output whitelists the active decision's scope, current safe
+subject, fingerprint, attribution, timestamps, and bound, while inert history
+is exposed only as stale/foreign/malformed/expired counts. Raw report records
+remain private to evaluation. Once correction removes all blocker fields,
+waiver history is not evaluated or surfaced as an inert warning.
+
+### Page Kit SDK version checkpoint
+
+The second registered checkpoint requires a canonical released semantic version
+in CampaignSpec and a released target pin in
+`_data/campaigns.json[public_route_slug].sdk_version`. CampaignSpec's
+`global_config.sdk_version` is canonical, with `runtime.sdk_version` as an
+accepted alias; declaring both is valid only when their released
+versions are equal. Missing, malformed, present-but-empty, non-string,
+prerelease, non-canonical, or conflicting dual declarations are non-waivable.
+Missing or invalid target evidence is also non-waivable.
+
+The two pins have a direction of authority. The repo pin is the version the
+funnel serves, so it is the only value a bump can be proven against; the spec
+field is a build hint whose job is to seed a fresh scaffold. The gate compares
+them accordingly:
+
+- **Equal** — pass.
+- **Target newer than the spec, both released, entry configured** (the
+  starter demo store profile is gone) — a completed bump the Map has not been
+  re-saved for. Doctor passes the gate with the `page_kit.sdk_version.repo_newer`
+  warning and a ready line naming what ships; QA projects it as a `warn`
+  assertion; `next` does not stop. The gate's `advisory_actions` carry one
+  `refresh_spec` command, `campaigns-os spec derive --packet <packet>`
+  (below), which writes the repo pin into the spec; with `--write-map` it
+  also records the pin in the Map's Build hints field (Campaign Cart SDK
+  version), which is otherwise re-saved by hand to make the exported spec
+  stop reading stale. Nothing in the repo needs to change, and there is
+  nothing to waive.
+- **Target behind the spec, or still the scaffold's seeded pin beside the demo
+  store profile** — blocked, repaired by `page-kit sync` (below) or waived.
+- **Target pin not a released version** — blocked, non-waivable, whatever the
+  spec says.
+
+Only the blocked mismatch between two valid released versions has a waiver
+lane, and the decision fingerprints that exact expected/observed pair:
+
+```bash
+campaigns-os checkpoint waive \
+  --packet campaign-runtime.build.json \
+  --gate page_kit.sdk_version \
+  --reason "<why this exact target pin is intentional>" \
+  --waived-by "<named human>" \
+  --review-condition "<specific re-evaluation trigger>"
+```
+
+Changing either version makes the decision stale. The same named-human,
+bounded-decision, visibility, and privacy rules described for Store Profile
+apply. A target pin that is missing, malformed, or behind a valid spec pin
+(or still the scaffold's seeded pin beside the demo store profile) is repaired
+by the same `campaigns-os page-kit sync --packet <campaign-runtime.build.json>`
+described above, which doctor and `next` print as the gate's `repair_target`
+action. A configured campaign whose pin is newer than the spec's is the
+advisory case above: no required action, and sync never moves that pin
+backwards; `spec derive` is the command that closes it from the spec side.
+
+### Deriving the spec from the repo (`spec derive`)
+
+Every CampaignSpec field has a class: **authored** (a human writes it: offers,
+funnel shape, copy intent), **mirrored** (pulled from the Campaigns API or the
+store: packages, prices, shipping) or **derived** (the repo or the store
+already states it: the SDK pin, page routes, the store profile, analytics
+ids). The table is on #432. Derived fields are generated, never typed, and
+this command generates the repo-derived ones so doctor compares generated
+against generated instead of refereeing a hand-typed value against the repo:
+
+```bash
+campaigns-os spec derive --packet campaign-runtime.build.json [--dry-run] [--json] [--report <json>] [--from-store <subdomain> [--store-token-source env:<VAR>]] [--write-map] [--proxy-base <url>]
+```
+
+By default it reads the target repo only (no network unless `--from-store` or
+`--write-map`, below) and writes into the packet's local spec (`spec.local_path`):
+
+| Spec field | Repo authority |
+|---|---|
+| `global_config.sdk_version`, and `runtime.sdk_version` when the spec declares the alias (so the two never conflict) | `_data/campaigns.json[public_route_slug].sdk_version` |
+| `funnels[].pages[].page_url` (the legacy `funnel_pages[].page_url` mirror, when present, is reconciled to the same route on every run) | the page tree under `assembly.output_dir` (default `src/<public_route_slug>/`), read by page-kit's own rule: the file's basename alone (`checkout.html` → `checkout/` wherever it sits; `index.html` → the entry route; a nested `index.html` collides with the root and is not read), or a frontmatter `permalink` in the `/<slug>/<route>/` form prepare-build writes (page-kit serves a permalink verbatim, so any other spelling is a repo defect, refused) |
+| `analytics.providers.gtm.containerId` | `_data/campaigns.json[public_route_slug].gtm_id` |
+| `analytics.providers.facebook.pixelId` | `_data/campaigns.json[public_route_slug].fb_pixel_id` |
+
+Nothing else is written: not the store profile (store-derived; see
+`--from-store` below), not any authored or mirrored field, not the packet,
+not the repo. A
+derived field the spec carries with a different, authored-looking value is
+overwritten, and the printed `before -> after` line shows it: that is the
+class doing its job. A block the spec lacks is created (`global_config`,
+`analytics.providers.gtm` as `{ "enabled": true, "containerId": … }`); an
+array element is never invented.
+
+Each page is bound to one file: the packet's own projection first
+(`source_html.pages[].page_kit.target_path`, the file the build stage wrote
+for that page id), else a file whose route equals the page's current route,
+whose terminal segment equals it, or whose filename is the page id. The
+derived route is compared the way prepare-build projects a route
+(normalized, slug prefix stripped), so a spelling that already resolves to
+the tree's route (`checkout`, `/<slug>/checkout/`) is not a change, and a
+value nested differently from the tree (`offers/upsell/` against
+`upsell.html`) is. A routing hint in `sdk_hints.meta_tags` (`next-success-url`,
+`next-upsell-accept-url`, `next-upsell-decline-url`) that no longer matches
+the derived route of the page it names is reported as
+`spec.derive.routing_hint_stale` on every run until the Map is re-saved;
+hints are a Map projection the editor regenerates and are not rewritten.
+
+What the repo cannot state is reported as `not_derived[]` with a reason and
+the status is `partial` (exit 0; the fields it could derive are written):
+
+| Reason | Meaning |
+|---|---|
+| `scaffold_seed` | the entry still carries the starter demo store profile, so its pin is the starter's seed, not a version anyone chose; `page-kit sync` seeds the pin from the spec in that state |
+| `target_missing`, `target_invalid` | the entry has no `sdk_version`, or it is not a released `MAJOR.MINOR.PATCH`; for an analytics id, the value is not a GTM container id / a digits-only pixel id; for a route, the file's permalink is not in the `/<slug>/<route>/` form (no slug prefix, another prefix, `.html`, `..`, a control character), reported with the URL page-kit would serve |
+| `waived` | an active named-human `page_kit.sdk_version` waiver covers the exact pair; derive leaves the spec as the waiver accepted it |
+| `spec_ahead` | a released pin the spec declares (canonical or alias) is ahead of the repo pin: the state doctor blocks on with `page-kit sync` as its repair (#413); one command owns it, so derive never moves a spec pin backwards |
+| `page_tree_missing`, `page_file_not_found`, `page_file_ambiguous` | no page tree, no file binds to the page, or more than one does |
+| `entry_route_undeclared` | the page binds to the top-level `index.html` (the entry route, `""`) but is not flagged `is_entry`; doctor honours an empty `page_url` only on the entry page, so the flag is asked for in the Map rather than the route written |
+| `waivers_unknown` | the Assembly Report could not be read, so a named-human `page_kit.sdk_version` waiver cannot be ruled out; the pin waits, routes and ids still derive |
+| `page_id_duplicate` | the page id appears more than once; no single route can be derived for it |
+| `spec_container_invalid` | `global_config`, `runtime`, `analytics`, `analytics.providers` or `analytics.providers.<provider>` exists in the spec but is not an object; reported by the plan so `--dry-run` and the write agree |
+| `target_empty` | the entry's `gtm_id` / `fb_pixel_id` is empty while the spec declares an id; an empty repo value never deletes a spec id |
+
+A placeholder id (`GTM-XXXXXXX`, a run of one digit) is `target_invalid`:
+writing it would declare an analytics contract QA then blocks on. A derived
+field the entry does not carry at all is listed under `not_in_target[]` and
+left as it is.
+
+After a write, the sidecars that carry the spec's identity are re-bound. The
+Build Context's `spec.hash` / `spec.material_hash` and the Assembly Report's
+`identity.spec_hash` / `identity.spec_material_hash` move to the new spec
+when they were bound to the one derive replaced and name that spec file
+(`rebound` on the result; two packets sharing a target repo never re-bind
+each other's sidecars);
+QA's verdict and `bundle check` correlate against the material hash, so this
+is what keeps a derive-then-QA run conformant. A sidecar already carrying
+another identity is left alone with a `spec.derive.identity_not_rebound`
+warning naming `prepare-build`. A derived route change also warns
+`spec.derive.projection_stale`: the packet's page-kit projection
+(`source_html.pages[].page_kit`) and the Build Context page map were prepared
+from the old routes, and `prepare-build` (or `start`) regenerates them. A
+provider block derive creates warns `spec.derive.analytics_block_created`:
+the spec then declares an analytics contract QA gates on. `--dry-run` carries
+the same `file_reformatted`, `projection_stale` and `build_stale` warnings,
+phrased as what a write would do.
+
+Write discipline is `page-kit sync`'s: one read serves the plan and the
+write; the file is edited in place and re-serialized with its own top-level
+indentation, line ending and trailing newline (`spec.derive.file_reformatted`
+when that round trip would not reproduce the file byte for byte); staged
+through a temp file created with the spec's own mode bits and renamed over it,
+after re-reading the spec and refusing (`spec.derive.spec_changed_underneath`,
+exit 2) when it changed since the single read; written only at the path
+the spec resolves to, which must lie inside the spec's own directory or the
+target repo (`spec.derive.spec_escapes_boundary` otherwise, so a symlinked
+`spec.local_path` cannot redirect the write); the retained doctor sidecar is
+marked stale after a write, and a terminal build gets a
+`spec.derive.build_stale` warning naming the rebuild (doctor does not
+fingerprint the spec itself; the re-bound sidecar identity is what QA reads). `--dry-run` prints the
+same diff and writes nothing; unknown flags and a valued `--dry-run` are
+rejected. Exit 2 with `spec.derive.*` error codes and nothing written when the
+packet cannot be read, `spec.local_path` is absent or not a file, the spec is
+not a JSON object, the spec identifies another campaign
+(`spec.derive.spec_identity_mismatch`), or the target entry is missing
+(`spec.derive.entry_missing`; scaffold first).
+
+#### Deriving the store profile from the store (`--from-store`)
+
+The nine `campaign.store_*` Store Profile fields are derived too, and their
+authority is the store: `page-kit sync` writes them spec → repo, and this is
+the generator for the store → spec half. It needs a credential and the
+network, which the default run never touches, so it is opt-in:
+
+```bash
+campaigns-os spec derive --packet campaign-runtime.build.json --from-store <subdomain> [--store-token-source env:<VAR>] [--dry-run] [--json]
+```
+
+`<subdomain>` is the store's `<store>.29next.store` subdomain (the Admin API
+lives at `https://<subdomain>.29next.store/api/admin/`). The read token is
+taken from the environment, never from the command line: from
+`<SUBDOMAIN>_ADMIN_TOKEN` (upper-cased, dashes as underscores) by default,
+or from the variable `--store-token-source env:<VAR>` names. An Admin API
+access token with the `store:read` and `content:read` scopes (Settings >
+API Access) is enough; the token is sent as a bearer and appears nowhere in
+the output, which names the variable instead (a value that is not one line
+of printable ASCII is refused unsent, `spec.derive.store_credential_invalid`,
+and a transport error that quotes a header is redacted). The store is only
+read.
+
+| Spec field | Store authority |
+|---|---|
+| `campaign.store_name` | `GET /store/` `name` (Admin API version `2024-04-01`) |
+| `campaign.store_url` | `GET /store/` `primary_domain`, as `https://<primary_domain>` |
+| `campaign.store_phone` | `GET /store/` `contact_address.phone_number`, verbatim |
+| `campaign.store_phone_tel` | the same phone as a `tel:` URI (digits, a leading `+` kept), only when the display phone is one plain number: an extension, a second number or a vanity word would fold into the digits and dial something else, so those leave the field not derived (`target_invalid`) |
+| `campaign.store_terms`, `store_privacy`, `store_contact`, `store_returns`, `store_shipping` | `GET /pages/` (Admin API version `unstable`, followed cursor by cursor under the store's own pages endpoint): the one storefront page that carries the policy, as `https://<primary_domain>/<slug>/`, which is where the storefront serves it. A page whose slug is one of the policy's conventional slugs (`terms`, `terms-of-service`, `privacy-policy`, `contact-us`, `return-policy`, `shipping-policy`, `shipping-returns`, …) binds first; only when no page has a conventional slug does the wider match by slug or title words apply (terms/tos/conditions; privacy; contact; return(s)/refund(s); shipping/delivery), so a "free shipping" promo page never outranks the policy. One page may carry two policies (`shipping-returns`) |
+
+Rows join the same `before -> after` diff in the Store Profile's field
+order, each with its store source, and are compared NFC-normalized and
+trimmed as `page-kit sync` compares them, plus one leniency of derive's own:
+URL fields compare without a trailing slash, so a spec that carries
+`https://x.example/` is left alone when the store says `https://x.example`
+rather than churned (sync then writes the spec's spelling into the repo as
+it is). Every value
+passes the Store Profile shape rule before it is planned: the starter demo
+store's URL or phone, a non-http(s) URL, a malformed `tel:` or a control
+character is `target_invalid`, never written. A field the store cannot state
+is `not_derived[]` and **the spec's value is left as it is** (a store never
+empties a spec field): `store_field_missing` (an empty name, domain or
+phone), `store_domain_missing` (no primary domain, so no page URL can be
+formed), `store_page_not_found`, `store_page_ambiguous` (several pages read
+as the policy; the slugs are named), `store_pages_unavailable` (the pages
+endpoint failed, with the reason: a token without `content:read`, a version
+that does not serve `/pages/`, a body that is not the page list, a cursor
+outside the store's pages endpoint that was not followed) and
+`store_pages_truncated` (more pages than ten requests or two thousand rows
+return). A slug that is not one honest path segment (a separator, `.` or
+`..`, malformed text) is `target_invalid`. When the store's primary domain is not the host the spec's
+`store_url` named, `spec.derive.store_domain_changed` says so: either the
+spec was stale and the diff is the correction, or `--from-store` names
+another merchant's store and the spec should be restored.
+
+The result carries a `store` block (`subdomain`, `admin_api`,
+`token_source`, `store_read`, `pages_read`, `primary_domain`), and the text
+output a `Store:` line. After a write that moved a store field, `next` is
+`page-kit sync` first (doctor's `page_kit.store_profile` gate now sees the
+spec ahead of the repo and names sync as its repair), then doctor. A store
+that cannot be read is a refusal with nothing written, repo fields included,
+exit 2: `spec.derive.store_credential_missing` (the variable is unset or
+empty), `store_unauthorized` (401/403), `store_not_found` (404: no store at
+that subdomain), `store_unreachable` (transport, timeout, 5xx) or
+`store_response_invalid`. Local preconditions (packet, spec, target entry, spec boundary, page tree)
+are checked before the store is contacted, and a packet that names another
+spec or route by the time the read returns is refused
+(`spec.derive.packet_changed_underneath`). `--store-token-source` without
+`--from-store`, a subdomain that is not one (a URL, a path), or a token
+source that is not `env:<VAR>` is rejected before anything is read.
+
+#### Recording the pin in the Map (`--write-map`)
+
+The local derive fixes the exported spec; the Map itself still shows the old
+pin until someone re-saves Build hints, so anyone opening the Map or a fresh
+export reads stale. `--write-map` closes that half (#415): after the local
+write, the pin the plan derived is recorded into the saved Map's Build hints
+field (Campaign Cart SDK version) through the proxy Worker, with the same
+direction of authority as everything else on this gate: the write goes
+forward or not at all.
+
+```bash
+campaigns-os spec derive --packet campaign-runtime.build.json --write-map [--dry-run] [--proxy-base <url>]
+```
+
+The Map named by the packet's `spec.map_id` is read back (`GET
+/api/spec/<map-id>`) and re-stated with exactly the pin fields moved
+(`global_config.sdk_version`, and `runtime.sdk_version` only when the Map
+already declares the alias): every other field is the Map's own read-back,
+never the local spec, so an authored field is not rewritten from a local copy
+and the routes or analytics ids derive wrote locally do not travel. The `PUT
+/api/maps/<map-id>` carries the packet's Campaigns API key as
+`X-Campaign-Key` (the receiver refuses a key that is not the Map's; the key
+is the public-by-design one the packet, its local spec or the declared env
+source already holds) and the Map's `spec_hash` as `X-Spec-Hash`, so a save
+that landed in between is a conflict, not an overwrite. The proxy base is the
+canonical `https://campaign-map.nextcommerce.com` unless `--proxy-base` names
+another; it must be https, or a loopback host over http (allowed for a local
+receiver, with a stderr warning that the key travels in clear).
+
+The decision, reported on the result's `map` object and as one text line:
+
+| `map.status` | Meaning |
+|---|---|
+| `written` | the Map declared no pin, or one behind the repo pin; it now records the repo pin (`map.spec_identity.before` / `.after` carry the Map's `spec_hash` and `saved_at` either side) |
+| `unchanged` | the Map already records the repo pin; nothing sent |
+| `would_write` | `--dry-run`: the Map was read and the write previewed; nothing sent |
+| `refused` | a warning, exit 0, the local derive stands: `ahead` (the Map pin is newer than the repo pin — a bump the repo never received, doctor's blocked state and `page-kit sync`'s repair; the Map is never moved backwards) or `pin_unreadable` (the Map's pin is not a released version, or two declarations disagree; a value the rule cannot order is not overwritten silently) |
+| `skipped` | the pin was not derived (`pin_<reason>`, the `not_derived` reason: a scaffold's seed, a waiver, `spec_ahead`, …) or the local derive was blocked; nothing was read or sent |
+| `failed` | an error, exit 2, the local derive stands: `key_missing` (no Campaigns API key anywhere), `key_mismatch` (403), `not_found` (404), `changed_underneath` (409: derive again against the current save), `rejected` (the proxy's spec validation refused the re-stated Map: re-save it in the builder first), `proxy_base_insecure`, `network_error`, `http_error`, `response_invalid` (an answer that says neither yes nor no: read the Map back before deriving again) |
+
+A write is traceable from the campaign's own record: one line is appended to
+the Assembly Report's `evidence[]` (`Map write-back: global_config.sdk_version
+<before> -> <after> on Map <id> at <time> via spec derive --write-map (Map
+spec_hash <before> -> <after>)`), the retained doctor sidecar is marked stale
+by `spec derive --write-map`, and the run's lifecycle journal carries the
+command with its argv shape, so the Run Record (which references the report by
+hash) shows both that the write ran and what it changed. A report that does
+not exist yet (a derive before `prepare-build`) leaves a
+`spec.derive.map_not_recorded` warning carrying the same line; a report that
+took the line while the doctor stamp failed leaves
+`spec.derive.map_doctor_sidecar_not_marked` instead, and one that could not be
+read back after the failure leaves `spec.derive.map_recorded_status_unknown`
+(`map.recorded: "unknown"`) rather than a claim either way. A 403 on the read
+is `key_mismatch`, as on the write. Without
+`--write-map` nothing is read from or sent to the Map; `--proxy-base` is
+refused on its own.
+
+### Polish hidden eager-media checkpoint
+
+The third registered checkpoint is package-owned page-load evidence recorded at
+`stages.polish.evidence.visual_review.page_load`. Install the package-owned
+browser, serve the current build, and run this producer before marking Polish
+complete, deploying, or starting QA:
+
+```bash
+npm run qa:install-browser
+campaigns-os polish capture \
+  --packet campaign-runtime.build.json \
+  --base-url <served-current-build-url>
+```
+
+The producer derives every mapped, non-skipped route from the packet and
+captures desktop `1440x1200` and mobile `390x844`. It blocks when a
+computed-hidden `video` or `audio` element transfers strictly more than
+`1,048,576` bytes, unless its content attribute is exactly
+ASCII-case-insensitive `none` or `metadata`. Evidence exactly at the byte
+threshold passes. The command owns the versioned capture format and its
+integrity binding; never hand-author or copy `page_load`.
+
+The operator supplies the URL of the current served output. The evidence binds
+to packet/report authority, but the URL itself is not cryptographic proof that
+the server is hosting those exact build bytes. The durable field map, bounded
+measurement semantics, and attachment race boundary are documented in
+[Polish evidence](./polish-evidence.md#durable-page_load-field-map).
+
+Missing, malformed, stale, incomplete, or contradictory measurement evidence
+is nonwaivable. A complete real finding may receive an exact named-human
+decision:
+
+```bash
+campaigns-os checkpoint waive \
+  --packet campaign-runtime.build.json \
+  --gate polish.hidden_eager_media \
+  --reason "<why this exact finding is accepted>" \
+  --waived-by "<named human>" \
+  --review-condition "<specific re-evaluation trigger>"
+```
+
+The decision binds the build fingerprint, campaign slug, route scope, routes,
+fixed viewports, and stable finding state. Any change makes it inert. Doctor and
+`next` report `ready_with_waivers`; QA reports `ready_with_exceptions` and keeps
+the warning visible.
+
+QA evaluates all three registered gates from one packet/spec/target/report
+snapshot; a waiver for one never hides a blocker in another. See
+[QA checkpoint preflight](./qa-and-test-orders.md#packet-local-checkpoint-preflight)
+for the downstream runtime boundary.
+
+Every gate that still owes work carries `required_actions[]` — the exact repair
+command or manual step, plus the waiver command. `campaigns-os doctor` prints
+the same actions in its text report, under a `Required actions:` block below the
+errors and warnings, so an operator reading stdout gets the remediation without
+re-running with `--json`.
+
+### Built-output campaign identity gate (`built_output.campaign_identity`)
+
+Every doctor run that sees built output (the packet path and `doctor --built`
+alike) checks that the pages agree about which campaign they belong to. The
+SDK reads three identity signals per page and reconciles nothing across
+pages: the API key (`<meta name="next-api-key">` beats `window.nextConfig.apiKey`,
+whether inline or in the `config.js` the page loads), the `next-funnel` meta,
+and any `setAttribution({ funnel })` call. A page copied from another funnel
+that still carries the other campaign's key, tag, or attribution call binds,
+builds, and renders without complaint, and creates or attributes the order
+against the wrong campaign. It has shipped twice.
+
+The gate blocks (not waivable — two identities on one funnel cannot both be
+intended) when:
+
+- any two observed API keys differ, from any source on any page, including a
+  page whose meta names one key while its `config.js` names another
+  (`built_output.campaign_identity.api_key_drift`);
+- `next-funnel` differs across pages (`…funnel_drift`), or, once any page
+  carries the tag, a page that declares `next-page-type` has no `next-funnel`
+  (`…funnel_missing`; a campaign that tags no page at all is consistent, and
+  the platform fills the campaign name when the tag is absent);
+- a `setAttribution({ funnel })` string disagrees with the `next-funnel` of the
+  page that calls it, or with the campaign's tag when that page has none
+  (`…attribution_drift`).
+
+One error per finding; each names the two files and the two values, so the
+repair is a one-line edit. Pages whose route contains a `-backup-` or `-old-`
+segment are parked copies: skipped and listed on the gate as `pages_skipped`,
+never scanned. Presence is not asserted: a campaign whose pages carry no key
+at all, or no `setAttribution` anywhere, passes on the funnel tag alone.
+`checkpoint waive` does not register this gate; the repair is the only route.
+
+The gate's evidence lands beside the other checkpoint gates at
+`derived.checkpoint_gates[]` (`id: built_output.campaign_identity`, status
+`pass` | `blocked` | `not_applicable`, `identity: { api_key, api_key_source,
+funnel }`, `findings[]`, `pages_scanned`, `pages_skipped`). It is proven to
+pass on the canonical rendered output of every certified starter family
+(`fixtures/certified-families/`), the reachability bar every static
+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
+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.
+
+Blockers (not waivable — the markup provably does not do what it says):
+
+- `SWAP_WITH_ADD_TO_CART` — a bundle selector in swap mode (explicit
+  `data-next-selection-mode="swap"`, or the SDK default when the attribute is
+  absent) with an `add-to-cart` button linked to it by `data-next-selector-id`.
+  Both write the cart. An upsell-context selector is exempt: it is select mode
+  by construction.
+- `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.38: `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
+  `billing-` prefixed name). The message names the SDK spelling for the usual
+  offenders (`firstName` → `fname`, `zip` → `postal`).
+- `MISSING_SELECTOR_ID_MATCH` — an `add-to-cart` button whose
+  `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.
+
+Warnings (advisory):
+
+- `DOUBLE_SELECTED` — more than one `data-next-selected="true"` card inside one
+  selector.
+- `TEMPLATE_DOUBLE_BRACE` — `{{` inside an SDK-owned `<template>`: the direct
+  child of a container the SDK clones from (`data-next-cart-summary`,
+  `data-summary-lines`, `data-next-discounts`, `data-next-bundle-selector`,
+  `data-next-bundle-slots`, `data-next-package-selector`,
+  `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.
+
+Information: `data-next-*` names the vendored attribute index does not list are
+collected on the gate (`unknown_attributes[]`) and printed as one advisory ready
+line, never as a warning. That is where an invented attribute such as
+`data-next-coupon-input` shows up; it is information rather than a warning
+because the certified templates carry a handful of their own `data-next-*`
+hooks the SDK never reads.
+
+Markup inside SDK templates is scanned too, since the SDK clones it into the
+live DOM. A gate reports one disposition: while blockers stand, advisories
+stay on the gate's `warned[]` and become doctor warnings only once the
+blockers clear; the gate `reason` names the first five findings and a count. The gate's evidence lands beside the other checkpoint gates at
+`derived.checkpoint_gates[]` (`id: built_output.sdk_markup`, status `pass` |
+`blocked` | `not_applicable`, `findings[]` for blockers, `warned[]` for
+advisories, `unknown_attributes[]`, `pages_scanned`,
+`sdk_attribute_index_version`). Fixtures: `fixtures/sdk-markup/<code>/{bad,good}`.
+It passes, with no advisory, on the canonical rendered output of every
+certified starter family (`fixtures/certified-families/`).
+
+> **Where does the source HTML come from?** See [docs/entry-points.md](./entry-points.md) for the five recognized entry points (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and how each populates `source_html.pages[]` + `design_source`.
+
+## Artifact Locations
+
+By default `campaigns-os start` writes into the target repo:
+
+```text
+campaign-runtime.build.json
+.campaign-runtime/build-context.json
+.campaign-runtime/assembly-report.json
+.campaign-runtime/doctor-output.json
+.campaign-runtime/theme/theme-report.json
+.campaign-runtime/input/campaign-build-brief.normalized.json
+.campaign-runtime/input/design-source-package.json
+```
+
+Those `.campaign-runtime/` paths are relative to the target repo
+(`packet.assembly.target_repo`, resolved against the packet's directory) even
+when `--out` keeps the packet somewhere else, and every stage — `doctor`
+included — reads and writes them there. When `prepare-build --report-out`
+puts the Assembly Report elsewhere, the Build Context records that path
+(`report_path`, relative to the target repo) and `doctor`, `next`, `qa run`,
+`qa waive` and the QA stage record follow it, so the report `next` reads is the
+one QA writes into — provided the context's `packet_path` names that packet;
+a context naming another packet binds nothing. `theme waive`, `checkpoint
+waive`, `polish capture`,
+`findings harvest`, `run-record` and `run status` act on the default location
+unless `--report` names another. `run-record` keys its record on a `run_id`
+resolved as `--run-id`, else the active run session, else the most recent Run
+Record already on disk for this packet's campaign (re-emitted in place), else
+a freshly minted id; `--new-run` mints on request and `--list` prints the ids
+on disk without writing (see docs/workflow-findings-sidecar.md).
+
+The packet's top-level `generated_at` (ISO-8601 UTC, `Z` suffix) is stamped by
+`prepare-build` on every new packet. Downstream freshness — campaigns-agent's
+readback staleness comparison and its multi-packet selection at the repository
+root — reads this field, never file mtime. Packets generated before the field
+existed remain schema-valid without it, but they cannot win freshness selection
+and never satisfy a fresh-artifact readback on their own; regenerate rather
+than hand-adding the field. Note that a committed artifact set always reads
+stale to the readback once HEAD moves past it — freshness proof is a
+regeneration at HEAD, not a property a commit can preserve.
+
+Commit durable packet/context/report artifacts when they represent a real build handoff. The rest of `.campaign-runtime/` is machine-local and is not for the campaign repository: `run-session.json`, `command-lifecycle.jsonl`, `agent-deviations.jsonl`, `workflow-findings.jsonl`, `run-records/`, `fetched-specs/`, `polish-evidence/`, `evidence/`, and `*.log`/`*.tmp` are per-machine, append-only, or carry live URLs and absolute paths, and so are the full QA verdicts `qa run` writes under the target's `qa-output/`. `start`, `prepare-build`, `install-agent-context`, and `run start` write a managed ignore block for exactly that set into the target's `.gitignore` once (keyed on its marker line; edit the list beneath it freely). The readback bundle (`build-context.json`, `assembly-report.json`, `doctor-output.json`, `qa-verdict.json`), `input/`, `theme/`, `agent-context/`, and `setup-handoff.json` are deliberately not ignored. The Campaigns API key is a public, browser-side, domain-allowlisted key and may already be present in the local CampaignSpec as `campaign.campaigns_api_key`; do not duplicate it into the packet unless the spec is unavailable. Do not commit raw private API responses, backend secrets, or temporary media exports.
+
+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.
+
+`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 packet, context, report, and generated doctor-output paths as relative paths by default, including sibling CampaignSpec/source directories such as `../campaign-source`. `campaigns-os doctor` continues to accept older absolute-path packets; use `campaigns-os doctor --packet <packet> --write --strip-paths` when regenerating a commit-ready doctor output from an older packet. Committed handoff artifacts should not contain machine-local absolute paths unless no relative form is possible.
+
+`start` / `prepare-build` also run the [Brand Theme Bridge](./brand-theme-bridge.md)
+in `inspect_only` mode. The optional theme evidence lives in `context.theme`,
+`report.theme`, and `.campaign-runtime/theme/theme-report.json`. The Build
+Packet itself does not gain required theme fields in v0.
+
+A campaign whose source carries no brand tokens has one more decision to make,
+and it is due before QA rather than after it. With nothing to generate, the
+theme gate passes (`theme_gate.nothing_generatable`) and no brand layer is
+applied, so the commerce pages ship the starter family's own palette — and
+browser QA, with the gate unwaived, runs the template-residue checks at blocker
+severity, so `qa run` blocks on `template-residue:<page>:style:*` rows for the
+starter call-to-action colour. That is deliberate on both sides: a passing gate
+means "nothing could be generated", not "this palette was reviewed". Two lanes
+clear it, and `campaigns-os next` names them from the build stage onward so the
+choice is made before a blocked verdict forces it — for the families this
+applies to. Palette residue is a certified-family check: it runs only where the
+selected `template_family` has a brand contract listing both the starter colours
+and the commerce selectors to inspect them on, so a `custom` or `undecided`
+family produces no `template-residue:*:style:*` rows and `next` stays quiet
+rather than asking for a waiver it does not need. Either record an explicit
+operator waiver (`campaigns-os theme waive --packet <packet> --reason "<why the
+starter palette is acceptable>" --waived-by "<named human>"`, optionally
+`--expires-at <canonical ISO timestamp>`), which downgrades those rows to `warn`
+(status and severity — never `fail`) and keeps the shipped palette visible in
+the verdict; or hand-author the brand
+layer — write `brand-theme.css`, list it after `next-core.css` in commerce-page
+frontmatter styles, rebuild, and record `report.theme.status: applied` with
+`load_order: after-next-core`. Nothing waives the gate on the operator's
+behalf. See [Brand Theme Bridge](./brand-theme-bridge.md) for both lanes in
+full.
+
+`start` / `prepare-build` also accept `--brief <campaign-build-brief.yaml|json>`
+and auto-discover `campaign-build-brief.yaml`, `.yml`, or `.json` from the
+source root or target repo. When none is present, Campaigns OS creates a guided
+draft at `.campaign-runtime/input/campaign-build-brief.normalized.json`.
+See [Campaign Build Brief](./campaign-build-brief.md) for the schema and
+prepared/guided behavior.
+
+`start` / `prepare-build` also prepares the normalized Design Source Package at
+`.campaign-runtime/input/design-source-package.json`. When that path is absent,
+the command synthesizes and writes the package; when it exists, the command
+validates it against the current campaign/page/source/template inputs and reuses
+its exact bytes. It refuses stale or contradictory packages instead of silently
+regenerating them. Its schema version is
+`campaign-design-source-package/v0` (schema file:
+`schemas/campaign-design-source-package.v0.schema.json`). The Build Packet,
+Build Context, and Assembly Report reference that artifact by path, full artifact
+hash, and material fingerprint instead of embedding it,
+matching the normalized Build Brief handoff pattern. The full hash supports audit
+and reproduction; the material fingerprint drives freshness gates. The package
+includes a generated top-level `readiness` summary with
+`status`, `blocking_reasons`, `gap_count`, `todo_count`, `waiver_count`, and
+`generated_at`; detailed gaps, TODOs, and waivers remain authoritative.
+See the dedicated [Design Source Package v0 guide](./design-source-package.md)
+for the exact reference shape, material projection, emit/reuse/refusal boundary,
+and lifecycle ownership contract. This section keeps the Build Packet handoff
+context and does not replace that consumer guide.
+
+`readiness.status` uses `pending`, `blocked`, `ready`, `ready_with_gaps`, or
+`ready_with_waivers`, not `ready_with_warnings`. The package may include
+free-form `notes`, but notes do not affect readiness; any concern that affects
+whether Build or Polish can proceed must be typed as a gap, TODO, proposed
+exception, or waiver. Source gaps and TODOs require `scope` and `applies_to`;
+attach them to Surface Identity when possible. The package reserves a top-level
+Surface Identity entry `campaign` with `kind: "campaign"`; use
+`applies_to: ["campaign"]` for legitimate campaign-level gaps/TODOs. Surface
+Identity IDs should be stable human-semantic strings such as `campaign`,
+`landing`, `landing.hero`, `checkout`, `checkout.payment`, or
+`upsell.offer-card`, with labels and aliases for source-specific, DOM, or Page
+Kit names. v0 requires `campaign` plus page-level Surface Identities for active
+or mapped CampaignSpec pages; section and runtime-surface IDs are optional until
+Build or Polish needs them. Do not derive the primary Surface Identity solely
+from CPK `page_type`, Map Builder custom labels, public routes, or producer page
+types. Preserve those as mapped attributes or aliases alongside the Surface
+Identity. For page-level IDs, prefer the CampaignSpec page ID when it is stable
+and human-readable; otherwise derive from normalized page role plus order
+(`landing`, `checkout`, `upsell-1`, `downsell-1`, `receipt`). Always preserve the
+CampaignSpec page ID, Map Builder label/custom name, public route, source aliases,
+and CPK `page_type` separately. `surface_identity[]` is a structured catalog,
+not a simple list of strings. Minimum fields are `id`, `kind`, `label`,
+`aliases`, and `mappings`; page-surface `mappings` preserve CampaignSpec page ID,
+Map Builder label/custom name, public route, producer page type, and Page Kit
+projection. Contribution mappings should reference `surface_identity[].id`
+values and carry relationship metadata such as `coverage_role`, `confidence`,
+`source_refs`, and `notes`. They should not define competing CampaignSpec route
+or Page Kit projection maps. `coverage_role` is a small enum:
+`primary_design`, `partial_design`, `brand_tokens`, `asset_source`,
+`copy_source`, `template_baseline`, `reference_only`, or `fallback_legacy`;
+use `notes` for unusual cases. Mapping `confidence` is also a coarse enum:
+`high`, `medium`, `low`, or `unknown`. It describes confidence in the
+surface/coverage mapping, not design quality or approval. Low confidence blocks
+source readiness only when it affects required page-level `primary_design`
+coverage; represent that as a Source TODO unless waived. Low confidence on
+brand-token, reference-only, or other non-primary coverage does not by itself
+block the v0 readiness evaluator; any gap or note is a separate explicit record.
+
+Screenshot references in the Design Source Package are source-side or
+reference-side proof only: canonical URLs, exports, captured source renders, or
+explicit records that a render is unavailable. Built-output screenshots for the
+current implementation belong in Polish Evidence or later QA evidence, tied to
+the current build fingerprint. Polish should compare against Design Source
+Package refs and Template Reference refs without mutating either source artifact.
+If Polish can capture a missing canonical source render, it should emit a
+proposed source-reference update or Source TODO rather than silently updating the
+Design Source Package. Source preparation owns any package mutation and must
+record it explicitly with attribution.
+Material source-reference refreshes create a new Design Source Package
+fingerprint. Any Build, Polish, or QA evidence tied to the previous source
+fingerprint is stale until refreshed or explicitly waived. v0 determines
+materiality through its explicit projection, not a marker in the package.
+Top-level `generated_at`, generated readiness/readback, notes, visual
+`captured_at` alone, formatting, key order, and normalized record/set order are
+non-material; the exact artifact-byte hash still changes when their serialized
+bytes change.
+Polish Evidence must record both the current build fingerprint and the current
+Design Source Package material fingerprint, conventionally as
+`source_build_fingerprint` for the assembly/build artifact and
+`source_package_material_fingerprint` for the design source context. Freshness
+gates consider Polish current only when both match the latest artifacts;
+if either changes materially, Polish is stale unless a structured waiver explains
+the exception. During the v0 transition, the polish gate enforces
+`source_package_material_fingerprint` only when the Assembly Report exposes a
+current Design Source Package material fingerprint, such as
+`design_source_package.material_fingerprint`. Legacy reports without a current
+source package keep the build-fingerprint gate and emit a readiness warning
+instead of blocking.
+
+Build must also record the Design Source Package material fingerprint it
+consumed on `stages.assembly.source_package_material_fingerprint`; Prepare does
+not populate that consumption field. If the current
+`design_source_package.material_fingerprint` is missing from Assembly or differs
+from the Assembly-recorded value, `campaigns-os next` routes back to Build before
+Polish. Polish must review a build made from the current material source context;
+it should not repair or certify a build made from stale design inputs.
+
+`stages.assembly.build_fingerprint` is the fingerprint of the built OUTPUT, not
+of its inputs: it changes exactly when the bytes under `_site/<public_route_slug>/`
+change, so a toolkit or template upgrade that renders different output from
+identical source reads as a different build, and identical output on any machine
+at any path yields the same value. The algorithm (`sha256-manifest/v1`): list every
+file under the built route root, path relative to that root with `/` separators,
+sorted by code point; for each file emit one `<path>\n<sha256-hex>\n` pair; the
+fingerprint is `sha256:` plus the SHA-256 of that manifest. Nothing is excluded by
+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
+(`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`
+(blocking once assembly is complete). The polish gate, QA, and `polish capture`
+compare evidence against that recomputed value, so evidence bound to a build whose
+output has since changed is `polish.output_drift` even when the recorded string
+still matches (`polish.stale` stays the code for evidence stamped against an older
+recorded build). `polish capture` refuses by name when the built route root is
+missing, unreadable, or drifted; symbolic links are never build output and are
+skipped by the walk.
+
+A stale or missing Assembly Source Package Fingerprint is waivable only as an
+exceptional Source Freshness Waiver. The waiver must be structured in
+`waivers[]`, with `scope: "assembly_source_package_freshness"` or an
+`applies_to` reference such as
+`stages.assembly.source_package_material_fingerprint`, plus reason, owner or
+waived_by, timestamp, and expiry/review condition. The waiver allows the
+orchestration loop to proceed to Polish, but Polish still must record current
+Polish Evidence, including `source_package_material_fingerprint` when a current
+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
+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
+existing artifact or waiver paths until each is explicitly registered.
+
+In v0, material source fingerprint fields include contribution identity/kind,
+provenance, presentation intent, Surface Identity catalog and mappings,
+contribution coverage roles, mapping confidence, source refs, source
+screenshot/reference refs, Template Reference linkage, Source Gaps, Source
+TODOs, accepted waivers, and any source divergence or proposed exception that
+has `readiness_affecting: true`. Generated readback prose, formatting/key order,
+and administrative notes are non-material when they do not alter readiness,
+coverage, provenance, or comparison basis. Capture timestamps alone may be
+non-material, but changing the viewport key, URL, dimensions, artifact path, or
+visual artifact hash is material.
+
+For renderable contributions that provide page-level `primary_design` coverage,
+source readiness requires at least desktop and mobile screenshot refs. Tablet is
+optional in v0. If a source is renderable but cannot be captured, record a
+Source TODO unless the absence is explicitly accepted as a Source Gap or covered
+by an approved Checkpoint Waiver. Template-baseline pages use the selected
+Template Reference standard viewport refs rather than source-specific captures.
+Use shared viewport keys across source refs, Polish Evidence, and QA evidence:
+`mobile`, `desktop`, and optional `tablet` in v0. Exact width, height, device
+profile, scale factor, browser, capture time, and URL are capture metadata, not
+new viewport names. Avoid stage-specific aliases such as `iphone`, `small`,
+`wide`, or `1440`; keep those details in metadata so cross-stage comparisons can
+join on the same keys.
+
+Required page-level coverage applies to every active or mapped page in the
+current build scope. A page is covered by a non-low-confidence `primary_design`
+contribution, an explicit `template_baseline` contribution for template-stock
+pages, or an attributed Source Gap / approved Checkpoint Waiver explaining why
+no primary design source exists. `template_baseline` must reference the selected
+template family/version and Template Reference artifact or contract. If the
+Template Reference proof is missing, record a Source TODO, Source Gap, or waiver
+according to whether the missing proof represents unfinished preparation, an
+accepted source absence, or an approved run exception. Missing page-level
+coverage blocks source readiness.
+
+## Adapter And Proof Fields
+
+Fresh packets now include `source_html.adapter_contract`. Build Context and
+Assembly Report carry the same values as `adapter_decisions`, and build agents
+should update the report as they complete work.
+
+Required adapter decisions:
+
+| Field | Purpose |
+| --- | --- |
+| `raw_html_conversion_status` | Whether prepared HTML has been converted into page-kit-ready source. |
+| `source_asset_strategy` | How images/fonts/CSS/JS are moved and referenced. Prefer `pagekit_campaign_asset_root`. |
+| `commerce_shell_adoption` | Whether checkout/upsell/downsell/receipt use a template-clone-first SDK surface. |
+| `route_rewrite_policy` | How page links, CTAs, and SDK routing values were rewritten from CampaignSpec routes. |
+| `template_files_copied` | Whether the selected template family was copied/verified as one atomic page-kit slice. |
+| `config_script_strategy` | How campaign config scripts are loaded. |
+| `wrapper_policy` | Whether document wrappers are stripped, preserved, or not required. |
+| `frontmatter_policy` | How Page Kit YAML frontmatter is created or preserved. |
+| `script_style_reference_policy` | How scripts/styles move into frontmatter, campaign assets, inline blocks, or passthrough. |
+| `cta_rewrite_policy` | How CTA destinations are rewritten from CampaignSpec routes. |
+| `layout_choice` | Which Page Kit layout strategy wraps the prepared source. |
+
+Fresh build context also includes `source.asset_crawl`
+(`source-asset-crawl/v0`). `prepare-build` scans the source HTML files and
+referenced local CSS, then records each local image/font/CSS/JS asset ref with:
+
+- `raw` and `normalized` source refs;
+- `source_path` / `source_exists` resolution under the source root;
+- `pagekit_asset_path` for the campaign asset-root ref to use during assembly;
+- summarized warnings for raw `/assets/...` refs, missing local files, and
+  refs that escape the source root.
+
+Use this inventory before moving assets into Page Kit. It is deliberately a
+context/report aid, not part of `source_html.pages[]` page binding.
+
+`template_files_copied` is intentionally group-based rather than prose-only:
+`pages`, `_includes`, `_layouts`, `assets/css`, `assets/js`, and
+`frontmatter_vocabulary`. Doctor warns when an assembly-complete report still
+shows `pending`/`partial` template copying or misses one of those groups. When
+the status is `complete` or `verified_existing_slice`, `paths` must name
+target-repo-relative proof paths and doctor verifies those paths exist.
+
+Fresh packets also include `qa.proof_policy`, mirrored into
+`report.proof_policy`. It records browser QA requirement, typed-card depth,
+localhost Development-domain behavior, non-localhost SDK allowlist requirement,
+order path depth, and operator approval state. Test cards still need no
+permission gate; the explicit field prevents agents from re-litigating proof
+depth in chat. Doctor checks the full field set in both packet and report
+artifacts when present. `order_path_depth` is seeded `common` and set with
+`--order-path-depth <off|common|full>` on `prepare-build`/`start` or later
+with `qa policy set --order-path-depth <depth>`, which also refreshes the
+report mirror; a packet whose depth disagrees with its report mirror draws the
+advisory `qa.proof_policy.order_path_depth_drift` warning naming that command
+(see `docs/qa-and-test-orders.md`, "Purchase-proof coverage"). The `qa` block carries no permission booleans:
+`qa.test_orders_allowed` and `qa.sandbox_test_card_confirmed`, which no command
+read, were removed in supported surface 1.28.0, and doctor warns
+(`qa.removed_policy_fields`) on a packet that still carries either.
+
+### Deploy target
+
+`deploy.target` names where the built `_site/` output is served for QA. The
+schema enum is `netlify`, `cloudflare-pages`, `vercel`, `shopify-proxy`,
+`agency-ci`, `local-serve` and `unknown`; doctor blocks (`deploy.target`) on
+any other value. `prepare-build`/`start` take `--deploy-target <target>` and
+default to `unknown`; `qa policy set --deploy-target <target>` changes it later.
+
+`local-serve` (added in 1.28.0) is the localhost QA path: nothing is deployed,
+the built output is served on localhost by any static server, and
+`deploy.preview_url` records that origin. Localhost on any port is a Campaigns
+App Development domain (SDK allowed, analytics suppressed), so under
+`local-serve` doctor does not raise `campaign.allowed_domains_confirmed`, reads
+a recorded localhost URL as the intended state (a `ready` line), accepts a
+loopback host (`127.0.0.1`, `[::1]`) with a ready line naming the
+`http://localhost:<port>/` fallback, and warns (`deploy.local_serve_url`) when
+the recorded URL is neither.
+`next` at the deploy stage then hands off a serve-locally prompt and action
+instead of a ship-to-host one. The directory to serve is `_site/`; for a
+root-served campaign (`campaign.route_root: "/"`) the handoff adds that pages
+are served at site-root paths while assets keep the `/<public_route_slug>/`
+prefix, so `_site/` needs the same rewrite of root-level page routes onto
+`/<public_route_slug>/<route>` the production host applies — no single
+directory serves both. The QA stage is unchanged and runs against the recorded
+URL.
+
+`local-serve` also selects **local proof mode** for the build stage: page-kit
+is built in the development environment (`CPK_ENV=development npx
+campaign-build --json > .campaign-runtime/page-kit-build-summary.json`) into
+`_site/`, and the build records `stages.assembly.evidence.build_environment:
+"development"` on the Assembly Report (a free-form stage field; no schema
+change). The starter templates gate every vendor loader on the environment,
+and a production build's protocol-relative loaders (`//host/...`) fail over a
+plain-HTTP local serve, voiding polish capture unwaivably; the SDK's `dl_*`
+events still fire in development. Before commit, `campaigns-os page-kit parity
+--packet <packet>` renders the current source in both environments to temp
+directories and proves the served output is the current development render
+and that production differs from it only in environment-gated output, with
+the same page set, route slugs, Campaign Cart pin and `next-api-key`; the
+result is recorded on `stages.assembly.evidence.local_proof.production_parity`
+and doctor reports it as `local_proof.production_parity` (with
+`local_proof.build_environment` for the build record). The PR preview is the
+second check. The toolkit never proposes editing a generated include to make a
+local capture pass. Details and the step order:
+[qa-and-test-orders.md](./qa-and-test-orders.md#local-proof-mode-deploytarget-local-serve).
+
+Campaign Build Brief `qa_policy` is deliberately scoped as
+`documented_expectation` metadata. Use it to preserve business QA intent, but
+do not treat it as the enforced gate; doctor/QA enforcement reads the packet
+and report proof policy fields above.
+
+## CampaignSpec Retrieval (`--map-id`)
+
+`campaigns-os start` / `campaigns-os prepare-build` accept the CampaignSpec via either of two routes:
+
+| Flag | Source | When to use |
+| --- | --- | --- |
+| `--spec <path>` | Local JSON file | Offline work, CI runs against a fixture, or hand-edited spec drafts |
+| `--map-id <id>` | Map Builder proxy (KV-backed) | Default agentic flow — KV is the source of truth, no file shuttling |
+
+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.
+
+Retrieval behavior:
+
+- **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.
+- **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
+- **`--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.
+
+The fetched spec is treated identically to a `--spec`-supplied local file from this point forward — same identity validation, same `prepareBuild` pipeline, same idempotency semantics. Re-running `start --map-id` on the same campaign re-fetches the spec, regenerates the packet, and re-runs doctor. If `design_source` was newly populated since the last run, the doctor's design_source-aware blocker logic surfaces it; if nothing changed, the run is a no-op as far as downstream stages are concerned.
+
+## Source HTML Manifest Auto-Population
+
+When the source HTML root carries a source-html manifest at `<source>/.campaigns-os/source-html-manifest.json` (schema `source-html-manifest/v0`, published at `schemas/source-html-manifest.v0.schema.json`) — or `--design-manifest <path>` names a manifest of that schema anywhere else, for a source root nobody can write to — `campaigns-os prepare-build` reads it and uses its `pages[]` block to populate `packet.source_html.pages[]` directly — bypassing the legacy filesystem-name slug matching. Wherever the manifest lives, its `pages[].path` entries stay relative to `--source`. A `pages[]` entry with `skip_reason` and no `path` declares a template-stock page: its assembly decision carries `template_stock: true` and the locked family, and intake demands no design source for it ([Template-stock pages](design-source-package.md#template-stock-pages-the-family-decides)).
+
+The source-html manifest remains a producer/source-HTML adapter input. It is not
+renamed into the Design Source Package. In the normalized source workflow,
+`prepare-build` uses source-html manifests, filesystem fallback, template-stock
+inputs, and other adapters to emit a separate public Design Source Package with
+contributions, coverage, gaps/TODOs, Surface Identity, references, and readback.
+When source-html data is the available input and the default package path is
+missing, current v0 `prepare-build` synthesizes the package. If a package already
+exists, it is validated against the current material inputs and reused byte for
+byte or refused; it is never silently regenerated. Downstream Build and Polish
+consume the package concept rather than branching back to
+`packet.source_html` as a second source model. The emitted package lives at
+`.campaign-runtime/input/design-source-package.json` by default and is referenced
+from packet/context/report by path, full artifact hash, and material fingerprint.
+
+Behavior:
+
+- The manifest is consumed only when it passes the `source-html-manifest/v0`
+  validator. Unknown schema versions, missing `page_id`, entries with neither
+  (or both) `path` and `skip_reason`, or malformed `source_hash` values log a
+  warning and fall back to filesystem matching so out-of-band tools cannot
+  silently corrupt the packet. Doctor also validates a present manifest at the
+  source root.
+- A partial-source build is declarable (#238). A page entry may carry
+  `skip_reason` instead of `path` to declare that active page out of source
+  scope (a template-derived page has no source HTML by design), and
+  CampaignSpec `build_scope.mode: "partial"` declares the same thing as a
+  blanket for active pages with no manifest entry and no `design_source`.
+  Declared pages are recorded on the packet as `skip_reason` mappings and on
+  the assembly report under `stages.prepare_build.declared_out_of_scope`;
+  prepare-build reaches `completed_partial` instead of blocking on
+  `MISSING_SOURCE_PAGE`, and the declaration regenerates identically on every
+  `start`/`prepare-build` run because it derives from the spec and manifest.
+  A page that declares `design_source` still blocks without a per-page skip
+  entry, and full/undeclared scope keeps the blocking behavior exactly.
+- The manifest's `page_id` must match an active CampaignSpec page id. Manifest entries with no matching spec page surface as a `MANIFEST_EXTRA_PAGE` prompt (analogous to the existing `MISSING_SOURCE_PAGE` prompt) so the operator reconciles either the spec or the manifest before build.
+- Optional manifest `page_url` values must be unique after Page Kit route normalization. Duplicate values surface as `MANIFEST_DUPLICATE_PAGE_URL`; prepare-build keeps the first value for route fallback matching and asks the operator to deduplicate before build.
+- Path values are relative to the source HTML root (`<source>`), not to the `.campaigns-os/` directory that contains the manifest. For example, use `checkout/index.html`, not `../checkout/index.html`.
+- An optional top-level `wrapper_policy` key declares the document-wrapper policy for the handed-over source, in the same vocabulary the packet records at `source_html.adapter_contract.wrapper_policy`. prepare-build seeds the adapter contract from it; the `--wrapper-policy` flag overrides it, and with neither the default stays `strip_document_wrappers`. Unlike the keys above, a value outside the vocabulary does not invalidate the manifest — the key is ignored with a warning and the rest of the manifest is used as written. See [docs/source-adapters.md](source-adapters.md#selecting-the-wrapper-policy-at-intake).
+- The build context records `source.manifest` with `schema_version`, `generator`, `generated_at`, and `page_count`, and the assembly decision log records evidence citing the manifest file.
+
+When the manifest is absent, prepare-build falls back to filesystem-name slug
+matching. If exactly one candidate matches an active page, the mapping is
+recorded as before. If multiple HTML files can satisfy the same page, or if all
+matching files were already assigned to sibling pages, prepare-build blocks with
+`AMBIGUOUS_SOURCE_PAGE`, records `context.source.ambiguous_candidates`, and
+drafts `context.source.manifest_draft` so the operator can write
+`.campaigns-os/source-html-manifest.json` and choose the intended paths before
+build.
+
+### Page Kit Target Projection
+
+`source_html.pages[].path` is source provenance. It names the producer/source-root-relative HTML file that should be consumed; it is not necessarily the file path to write under the Page Kit campaign directory.
+
+Fresh `prepare-build` output also writes `source_html.pages[].page_kit` for mapped pages. This block is the Page Kit target projection:
+
+- `target_path` is the page file relative to `assembly.output_dir` (`checkout.html`, `receipt.html`, etc.).
+- `output_path` is the same target file relative to `assembly.target_repo`.
+- `public_route` is the rendered campaign-rooted route Page Kit should produce.
+- `page_type` is the CPK runtime/analytics vocabulary (`product`, `checkout`, `upsell`, `receipt`), not the richer CampaignSpec or producer page type. CampaignSpec `select` pages project as CPK `checkout` because they are pre-checkout runtime selection surfaces.
+- `frontmatter` names the Page Kit frontmatter fields the build should write or preserve.
+- `permalink_required` is true when Page Kit's filename-derived route would not match `public_route`.
+
+The Design Source Package should reference this projection without confusing it
+with Surface Identity. Surface Identity is the campaign-facing join key; Page Kit
+`page_type`, public routes, output paths, CampaignSpec/Map Builder page IDs,
+custom labels, and producer page types stay as mapped attributes or aliases.
+
+`page_map[].output_path` in the Build Context is the same Page Kit target path,
+not `source_html.pages[].path` appended under `assembly.output_dir`. Build agents
+should read `source_path` for producer provenance and `page_kit.output_path` for
+the file to write.
+
+CampaignSpec `page_url` and legacy `url` values are interpreted as Page Kit
+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.
+
+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/`
+projects to `step-1.html`). If two routes collapse to the same target filename,
+prepare-build emits `PAGE_KIT_TARGET_CONFLICT`; change one CampaignSpec route
+before build instead of letting an agent choose a destination.
+
+### Per-page `source_hash` (Slice 6 drift detection)
+
+Each `manifest.pages[]` entry MAY carry a `source_hash` field — the sha256 hex digest of the source HTML file's contents at the moment the producer wrote the manifest. When present, prepare-build threads the hash onto the matching `packet.source_html.pages[]` mapping. Doctor reads the packet mapping at validate time, computes the current on-disk sha256 of the same file, and warns (`source_html.pages.source_hash`) when they diverge.
+
+Behavior:
+
+- Optional on the producer side. Producers that don't emit `source_hash` (pre-Slice-6 manifests, template-stock, hand-authored) keep working; doctor's drift check is silent without a hash to compare.
+- Warning severity only. A drift never blocks a build — the operator decides whether to re-run the producer to refresh the manifest or accept the local edits.
+- The warning names the file path and includes both hashes (truncated to 12 chars) so the operator can confirm which file diverged without re-running the producer.
+
+### Reference AI-generated producer
+
+`scripts/reference-ai-producer.mjs` ships in this repo as the smallest possible producer reference. It walks a folder of HTML files (auto-discovery) or accepts explicit `--page page_id=path` mappings, computes sha256 per file, and emits the `source-html-manifest/v0` at the canonical location. Auto-discovery maps `landing.html` to `landing` and nested `checkout/index.html` to `checkout`; duplicate inferred page ids fail fast, so use explicit `--page` mappings for ambiguous layouts.
+
+Usage:
+
+```bash
+node scripts/reference-ai-producer.mjs \
+  --source <source-root> \
+  --campaign-slug <slug> \
+  [--generator <name@version>] \
+  [--page landing=presell-a.html --page checkout=checkout/step.html]
+```
+
+Real AI agents (Claude, Codex, etc.) that produce campaign source HTML should adopt this manifest shape so doctor's design_source-aware error messages and Slice 6 drift detection work uniformly across producers. The script generates only the manifest; it does not write any HTML.
+
+## Authoring-Time Hints (Template Family + Upsell Pattern)
+
+The CampaignSpec carries two optional **hints** the build agent uses
+as defaults. Both are hints, not contracts: CLI / operator overrides
+always win.
+
+**Campaign-level:** `campaign.preferred_template_family` declares
+which starter family the campaign was authored against (one of
+`apollo`, `apollo-mv-single-step`, `olympus`, `limos`, `demeter`,
+`olympus-mv-single-step`, `olympus-mv-two-step`, `shop-single-step`,
+`shop-three-step`). The
+consumer (`preferredTemplateFamily()` in `src/cli.mjs`) reads this
+at three spec locations and uses it as the default template family
+when no `--template-family` CLI flag is given.
+
+Resolution order:
+
+1. `--template-family <family>` CLI flag (sets `template_lock.locked: true`).
+2. `spec.spec_identity.preferred_template_family`.
+3. `spec.campaign.preferred_template_family` (the canonical authoring location).
+4. `spec.preferred_template_family` (legacy fallback).
+5. `"undecided"`.
+
+When the flag and the hint disagree, the flag wins and `prepare-build` says
+so rather than resolving in silence: it prints one stderr line naming the
+winning flag value, the overridden `preferred_template_family` value, and
+which channel each came from, and records the same thing on the assembly
+report as a `prepare_build` warning with code
+`TEMPLATE_FAMILY_HINT_OVERRIDDEN`. An operator reading the report
+therefore sees that the packet's family was an override rather than agreement
+with the spec. A flag that merely repeats the hint is agreement, not an
+override, and stays quiet. To build on the spec hint instead, re-run without
+`--template-family`; to remove the disagreement, update the spec so the two
+match.
+
+When the hint wins, `template_lock.locked` stays `false` — the family is set as the default but not locked, so a downstream stage (or a follow-up operator pass) can override without contradiction. `template_decision_notes` records the hint source. `template.candidates` in the build context lists the hint with `source: "CampaignSpec preferred_template_family"` for provenance.
+
+**Per-page:** `Page.upsell_template_pattern` declares the UI variant
+for an upsell page (one of `mv`, `bundle_tier_pills`,
+`bundle_tier_cards`, `single`). Flows from the spec page onto
+`packet.source_html.pages[].upsell_template_pattern` so the build
+stage can pick the right partial without re-parsing the spec.
+
+The field is per-page; only upsell pages should carry it. Upstream
+spec validation warns when it's set on non-upsell pages, but the
+consumer surfaces it verbatim and lets the build stage decide what
+to do with it.
+
+## Commerce Catalog (`assembly.commerce_catalog`)
+
+`assembly.commerce_catalog` names the commerce-surface catalog the build and
+doctor read for the locked template family (`required`, `family`, `version`,
+`path`).
+
+- `path: null` means the toolkit's own catalog
+  (`contracts/commerce-surface-catalog.json` of the `campaigns-os` that is
+  running). This is what `prepare-build` records by default. The catalog
+  travels with the toolkit, not with the campaign, so the packet does not
+  record where one machine's checkout or package install kept it, and the
+  same packet resolves on any machine and under `npx campaigns-os`.
+- A string `path` is an operator-supplied `--commerce-catalog <path>`,
+  recorded relative to the packet (keep it inside the campaign repo). Doctor
+  resolves it against the packet's directory and blocks on
+  `assembly.commerce_catalog.path` when it does not exist.
+- Packets prepared before `null` was recorded carry the toolkit catalog as a
+  packet-relative path that climbs into the checkout that ran `prepare-build`
+  (`../../../campaigns-os/contracts/commerce-surface-catalog.json`). When such a
+  path does not exist but its file name is `commerce-surface-catalog.json`,
+  doctor and QA resolve it to the running toolkit's catalog and doctor prints
+  a `ready` line saying the packet still carries a machine-local path. That
+  is never a blocker; re-running `prepare-build` records `null`.
+
+## Orchestration Loop (`campaigns-os next`)
+
+`campaigns-os next` (no stage argument) is the agentic orchestration primitive. It reads the current packet, doctor, and assembly report state from disk and tells you which stage should run next. Each call re-reads state, so the loop is idempotent and recoverable across sessions / machines.
+
+Treat the loop as a sequence of Readiness Checkpoints, not as a required one-shot
+campaign build. A one-shot run is the best case where inputs are already complete
+and every checkpoint can advance in one session; the normal path may take several
+turns or sessions as source gaps, source TODOs, waivers, polish findings, deploy
+state, and QA blockers are discovered and resolved.
+
+For source preparation, the Design Source Package should carry a generated
+readback summary that names included sources, coverage, gaps/TODOs, mappings,
+reference availability, and readiness. The readback helps humans and agents pick
+up the work later; structured package fields remain authoritative. Later stages
+should write their own stage readbacks or evidence summaries rather than
+rewriting the Design Source Readback. Those stage readbacks should be surfaced
+through a consolidated or just-in-time Campaign Readiness Readback so the
+operator is not expected to discover a patchwork of separate artifacts. Generate
+that readiness readback from the latest artifacts as the primary behavior; Run
+Records may snapshot it for audit. `campaigns-os next` should show the concise
+current-stage readback, while run or campaign status should show the fuller
+campaign-level readback. The readback should include readable prose plus stable
+buckets: `current_checkpoint`, `readiness_status`, `handled`, `blocked_by`,
+`known_gaps`, `proposed_exceptions`, `waivers`, `evidence_refs`, and
+`next_actions`. `evidence_refs` should point to source package sections,
+screenshots, Polish Evidence, Assembly Report stages, deploy URLs, QA verdicts,
+or other owning artifacts; the readback summarizes evidence but does not embed
+the detailed proof. UI surfaces may render screenshot thumbnails from refs, but
+CLI/readback data should keep screenshots as references with a short statement of
+what each proves.
+
+Checkpoint status should stay boring and shared: `pending`, `blocked`, `ready`,
+`ready_with_gaps`, `ready_with_waivers`, `completed`,
+`completed_with_warnings`, or `skipped`. Put stage-specific detail in evidence,
+gaps, TODOs, waivers, findings, and next actions. `ready_with_waivers` requires
+structured waiver evidence: owner, reason, scope, applies-to references, created
+time, and either an expiry or review condition. Stages such as polish may draft
+or recommend waivers with evidence, but an operator/run decision approves them.
+Polish must classify every unresolved issue as `repair_needed`, `source_gap`,
+`source_divergence`, `waiver_recommended`, or `out_of_scope` so the next
+checkpoint knows whether to fix, carry, approve, or route it. Unresolved
+`repair_needed` issues block deploy and QA unless repaired, reclassified, or
+covered by an approved waiver. A `source_divergence` raised by polish is
+proposed until confirmed by an operator/run decision or the relevant Build or
+Design Source owner. A `source_gap` raised by polish is proposed too, unless it
+traces to an accepted Source Gap in the Design Source Package.
+
+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"
+```
+
+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 |
+|---|---|---|
+| setup | `stages.setup` | scaffold the page-kit campaign repo |
+| build | `stages.assembly` | assemble the campaign (next-campaigns-build) |
+| polish | `stages.polish` | source-design fidelity pass (next-campaigns-polish) |
+| deploy | `stages.deploy` | ship `_site/` to Netlify / CF Pages / Vercel / etc. (out-of-band), or serve it locally under `deploy.target: local-serve` |
+| qa | `stages.qa` | spec-aware QA (next-campaigns-qa) |
+
+The CLI stage name is `build` but the report keys the same stage as `assembly` — the picker handles the translation. Both names refer to the same lifecycle step.
+
+The Assembly Report's top-level `status`, `next` and `blockers` are derived from its `stages` on every write of the report (prepare-build's first write and every stage record after it), never carried forward from an earlier write. `status` is `blocked` while any recorded stage is blocked, `completed` only once every recorded stage (`prepare_build` and `doctor` included) is terminal, and `prepared` otherwise. `next.stage` is the first non-terminal stage in the order above, in the `next <stage>` vocabulary (`setup`, `build`, `polish`, `deploy`, `qa`, then `done`; a blocked prepare-build or doctor names `prepare-build` / `doctor-blocked`; a doctor that never recorded an outcome does not hold the ladder but is named `doctor` once the ladder is exhausted, so a `prepare-build --no-doctor` report never reads `completed`), `next.owner` is the skill that owns it, and `next.blocked` is present and true when that stage is the one holding the ladder. `blockers` is the union of the `blockers[]` of the stages currently blocked, so a blocker cleared by a re-run leaves the top level with its stage. The report's `next` is the ledger's own position; `campaigns-os next` additionally folds in live gates (doctor findings, purchase-proof coverage, the polish gate) and remains the authority for what runs next.
+
+Result shape (with `--json`):
+
+```jsonc
+{
+  "ok": true,
+  "status": "ready",
+  "stage": "build",
+  "picked_reason": "Stage \"assembly\" has status \"pending\"; run \"build\" next.",
+  "prompt": "Use next-campaigns-build for this Campaigns OS handoff. ...",
+  "errors": [],
+  "warnings": [],
+  "ready": [],
+  "stage_blocked": false  // present only when the recorded status is "blocked"
+}
+```
+
+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 in a terminal status. Pipeline is complete. To re-run a specific stage, set its status back to `"pending"` in the assembly report and 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.
+
+## Design Source-Aware Coverage Error
+
+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` 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.
+
+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.