@nextcommerce/campaigns-os 1.41.2 → 1.43.2

package/contracts/supported-surface.json

@@ -1,6 +1,6 @@
 {
   "_note": "The downstream contract manifest. Everything listed here is SUPPORTED SURFACE: consumers (campaigns-agent, campaign-builder, the private ops repo, page-kit campaign repos) may depend on it, and changing it is a deliberate act — hashed entries require a surface_version bump in the same change (check-supported-surface.mjs --base, mirroring the skills.json bump gate), named entries must keep existing at their path, cli_commands must keep resolving in the CLI dispatch, package_exports must stay exported, and every entry must ship in the npm pack (files[] coverage). Anything NOT listed here — src/** internals, scripts/** checkers, examples/**, prompts/**, contracts/** other than this file and the entries named[] below (the orientation contract, the release ledger, and the consumer-facing orientation fixtures) — is implementation: consumers may read it for context but must not build on it, and it can change without notice. Rationale and the compatibility promise: docs/supported-surface.md.",
-  "surface_version": "1.41.2",
+  "surface_version": "1.43.2",
   "package_exports": [
     "./commercial-journey",
     "./commercial-parity",
@@ -47,7 +47,7 @@
   ],
   "hashed": {
     "contracts/migration-sidecar-bundle.v0.json": {
-      "sha256": "f5097f6cccaf211d442c1ebc584d2c76d5a07a44e587df130de02117a9412db0"
+      "sha256": "53269453dfdaac4b286124d445b60b0c46205dfbaf8037ac61b30254a32df53a"
     },
     "contracts/runtime-recipe.campaigns-os-node-v1.json": {
       "sha256": "90aaaaade90cf2525ea1aa05be5cb2d02b57e6e59f9278a946efa8a087946fd3"
@@ -59,16 +59,16 @@
       "sha256": "65bcd8b5f41f1e9ecfc36f3b8838cd4ed531bd74c5a318ee5147131f6c9b4a1c"
     },
     "schemas/campaign-runtime-assembly-report.v0.schema.json": {
-      "sha256": "3fa085f2ad368567983cdc9c01e7c712682d02df9c28e69a2b7befb45d444468"
+      "sha256": "8a0d37be9a4bb34d0ed073c9d6bfa4406a7b499c801c34c5fbb26646e2665c0b"
     },
     "schemas/campaign-runtime-build-context.v0.schema.json": {
       "sha256": "f310c1b7844d9b1994864d15858ff0c6f17efc1e5285ba193d181bdb2dd4be2f"
     },
     "schemas/campaign-runtime-build-packet.v0.schema.json": {
-      "sha256": "886fb59b58787a3fd7a9c43ce4c676aeebbd52fd789269cfac700fcae42106d1"
+      "sha256": "47c2899f409ed5927cf410bddd63e7bb8a9d154eabf7a07455777aed118212e9"
     },
     "schemas/campaign-spec.v4.schema.json": {
-      "sha256": "12b57573739357acb2b007d00a737cd86face441c47f2719fc51b041dc8ea4a5"
+      "sha256": "af56c3de638d3c4e1fd5df8c2d733754d9ad16caa23b5bec92ce3a6f71bd0271"
     },
     "schemas/campaigns-os-legacy-migration-inventory.v0.schema.json": {
       "sha256": "d6edc4572900d15fdaf6b8c59916b0d885303c1d398bdadeb7c58285522c9049"
@@ -80,10 +80,10 @@
       "sha256": "1405c32bb9698030e9a40d754191e413cdd505dde91ac7de2e41c8887700f8f2"
     },
     "schemas/campaigns-os-qa-verdict-sidecar.v0.schema.json": {
-      "sha256": "1bc53b9a75a6c19c89aee6e9664574980b09d2e13eb8826b157f5ab6ba82d0b0"
+      "sha256": "3c40fd79f218d1b95f0424f9a2b67db140a306329e2ca02793e2740d3afded59"
     },
     "schemas/campaigns-os-qa-verdict.v0.schema.json": {
-      "sha256": "f7ce00e4f814d0ab7659b11fb2a14d3e4fafbf7c8e353449f25d7e87e1627acc"
+      "sha256": "ec4514e81a791a63bc0b358d7977aa823f3c5524e0f5caaba2712e66f262e18a"
     },
     "schemas/campaigns-os-doctor-output.v0.schema.json": {
       "sha256": "87866e619d2a18f01a208a1682cb14a2079f61df51c642f4e1902b6e6bce0ce5"
@@ -95,7 +95,7 @@
       "sha256": "08ca132134b9e4610370e88082a5e888d09ddec0d5ee4512d84cc57181da722e"
     },
     "schemas/campaigns-os-run-record.v0.schema.json": {
-      "sha256": "2a073874ab6081dd6db48e90f1a9b2c3c7c3ae4af70779c604701d70bb12b46d"
+      "sha256": "00dc9bcec79c12ea22a27f636188bcc33c6811df2d646ac7b49d4cc076e97355"
     },
     "schemas/campaigns-os-runtime-recipe.v1.schema.json": {
       "sha256": "f8a2ab5eadbb71fb6d5653b670ee71e4471c3df74dd04000d3dbd3d9ae9e71fc"
@@ -110,7 +110,7 @@
       "sha256": "841c1f884260ce3eb3ddb518960a127bc915992a9539c818e5986ce156acff1f"
     },
     "schemas/campaigns-os-progress-snapshot.v0.schema.json": {
-      "sha256": "c572756be7df03351843ffc361fc657e3fd819702b4e6f0a78a3c8efd0b0f046"
+      "sha256": "ef31b4f20e39dfc1614dd4b45e4cf1692a51760b008cb51d133659307bd2a954"
     },
     "demo/apollo-v0/provenance.json": {
       "sha256": "2e440be6513fe06b351c3a72c35424a04f807792621cb01e89803441fd925e06"
@@ -119,7 +119,7 @@
       "sha256": "dfc9abed38d456969e47a21f606d308a03bdf036f3466f7d6e47a602747dacf4"
     },
     "contracts/effects.v1.json": {
-      "sha256": "37c54f75731541f763aedac7b067506b3d0aa98e1083f285de87b9b32b027664"
+      "sha256": "1dae66e70bb5d167ca407d4ad03e70a1e2e761407b8ad7b85c8a7a51456df858"
     },
     "schemas/campaigns-os-effects.v1.schema.json": {
       "sha256": "3eadd22169ab98bc7c2f682af2751267605170581182158d96be035b0cfe44dc"
@@ -212,6 +212,7 @@
     "agents/codex/AGENTS.md",
     "agents/copilot/copilot-instructions.md",
     "agents/cursor/campaigns-os.mdc",
-    "docs/skills-revision.md"
+    "docs/skills-revision.md",
+    "docs/local-setup.md"
   ]
 }

package/docs/build-packet.md

@@ -4,7 +4,7 @@ The Build Packet is the campaign assembly handoff. It wraps, but does not replac
 
 It answers:
 
-- Which CampaignSpec and Map ID are we building?
+- Which CampaignSpec and saved Map ID or local-spec 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?
@@ -15,6 +15,56 @@ It answers:
 
 The current schema is `schemas/campaign-runtime-build-packet.v0.schema.json`.
 
+## Local-spec entry
+
+A saved Map is optional for a prepared-HTML build. The coding agent authors an
+ordinary CampaignSpec from the brief, source design and configured campaign's
+real commerce values, following `schemas/campaign-spec.v4.schema.json`. The
+operator supplies the selected store/campaign, public Campaigns API key, intended
+pages and commercial choices, plus store contact details and policy URLs. Verify
+the store/campaign binding and package/offer references; do not guess commerce
+values. No gateway or Map provisioning is required for this entry.
+
+Set `spec_identity.local_spec_id` to a new UUID once, commit it with the spec,
+and keep it unchanged through revisions and fresh checkouts. It accepts 1–64
+letters, digits, underscores or hyphens, with no surrounding whitespace. Local
+IDs are checked exactly; the legacy normalization of saved Map IDs does not
+apply. Malformed or conflicting local identities cannot be adopted into campaign
+evidence; blocked diagnostic reports may still be written. Doctor reports local
+identity failures as `spec.local_identity`, while
+saved-Map failures retain `spec.map_id`. Set `spec_identity.public_route_slug`
+to the intended route. Omit `map_id`, saved-Map URLs and saved-Map revision
+metadata; a local ID is never a Map ID. A spec declaring both kinds is refused.
+A separately authored campaign gets a new local ID even if its route matches.
+
+```sh
+npx --no-install campaigns-os start --spec campaign-spec.json --source source-html --target . --template-family <certified-family> --deploy-target local-serve
+npx --no-install campaigns-os next --packet campaign-runtime.build.json
+```
+
+The packet and report retain `map_id: null` and carry `local_spec_id`. Doctor,
+report writes, polish capture, progress, run closeout and QA compare that local
+identity. Material spec hashes still bind the current revision; a changed ID or
+content cannot reuse earlier proof. After a material revision, follow `next` to
+refresh preparation and affected evidence. Keep the spec, source, dependency
+pins and canonical sidecars in Git. Use `readback` and `next` after a fresh
+checkout; identity survives the move, but proof freshness is assessed again.
+
+Run QA through `--packet`. Local verdicts use the storage key
+`local-spec-<local_spec_id>` and carry the explicit ID in the full verdict and
+committed sidecar. A matching route alone cannot adopt a verdict. Local QA is
+never posted to the Map portal: `qa run` suppresses publication even with
+`--post-verdict`, while `qa publish` refuses with `local_spec`. Progress remains
+local with `map_id_missing`. Run Telemetry retains
+its existing consent controls. `spec derive --write-map` requires a real saved
+Map. Moving to a saved Map requires fresh preparation and evidence; this entry
+does not claim saved-Map revision alignment.
+
+Existing saved-Map specs and packets continue to work. The identity change does
+not relax template certification, source proof, store/SDK parity, polish,
+commerce checks, or typed-card checkout proof. Resolve their reported gates;
+localhost readiness is not production approval.
+
 ## Root-Served Campaigns (`campaign.route_root`)
 
 Most campaigns are served under a slug prefix (`/<public_route_slug>/...`), and
@@ -78,7 +128,7 @@ campaigns-os page-kit sync --packet campaign-runtime.build.json [--dry-run] [--j
 ```
 
 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
+authored in the saved Map or the repository-owned local spec, 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
@@ -103,7 +153,7 @@ 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`
+identifies another campaign (`spec_identity.public_route_slug`, `map_id` or `local_spec_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`).
@@ -733,6 +783,64 @@ advisories, `unknown_attributes[]`, `pages_scanned`,
 It passes, with no advisory, on the canonical rendered output of every
 certified starter family (`fixtures/certified-families/`).
 
+### Built-output script syntax gate (`built_output.script_syntax`)
+
+Every doctor run that sees built output (the packet path and `doctor --built`
+alike) parses each campaign-owned `.js` file a built page loads by a local
+`<script src>`. A script that does not parse throws a `SyntaxError` on every
+load of every page that references it, and nothing it defines runs; every
+HTML-reading gate passes over it. The shape that shipped was a template-family
+checkout script, copied and hand-edited, left with one closing `});` too many.
+
+Parsing uses Acorn at the latest `ecmaVersion`: `sourceType: 'script'` for
+classic scripts and `'module'` for `type="module"`, which is how the browser
+reads each. Remote scripts (an `http(s):` URL, a protocol-relative `//` URL,
+`data:`) are not campaign-owned and are not read, and neither are data blocks
+such as JSON-LD. The type is compared as the browser compares it, with
+surrounding ASCII whitespace stripped and case ignored. A classic `nomodule`
+script is skipped: a module-capable browser never fetches or runs it. A
+`type="module"` script ignores `nomodule` and is still parsed. Each src
+resolves the way the browser resolves it: against the base in effect when the
+parser prepares the script at its end tag, which is the first HTML `<base
+href>` in tree order among those already parsed, or else the page. A `<base>`
+parsed after a script does not move it, whether it is async, deferred or a
+module: its URL is fixed when it is prepared, not when it is fetched. Parse
+order decides, not final tree position, so a base that table foster parenting
+moves ahead of an earlier script still does not apply to it. A `base` inside
+SVG or MathML is not a base element, and only HTML-namespace `<script>`
+elements are read: an SVG `<script>` never loads a `src` attribute. The href is read as the URL parser reads
+it: only leading and trailing ASCII control characters and spaces are
+stripped. A base
+the browser refuses (one that does not parse, or a `data:` or `javascript:`
+URL) falls back to the page, as the HTML "set the frozen base URL" steps
+require. The percent-decoded path maps under the site root first, then the
+campaign directory, never outside either. A base on another origin makes
+relative srcs remote. Imports inside a module are not followed.
+
+A parse failure blocks (not waivable — a script that cannot be parsed cannot be
+intended to ship) under `built_output.script_syntax.parse_failure`, one error
+per file. The message leads with `<file>:<line>:<column>` and a fixed
+diagnostic category (for example `Unexpected token` or `Invalid regular
+expression`), never text from the script, and names the pages that load the
+file. A referenced local script that is not in the built output is a warning,
+not a blocker, under `built_output.script_syntax.missing_script`, one warning
+per src naming the pages that load it: the browser gets a 404 for it and
+nothing it would define runs, but whether the page needs it is not known here.
+The src is also listed in `scripts_unresolved[]`. While a parse failure blocks
+the gate, the missing scripts stay on the gate's `warned[]` rather than also
+surfacing as warnings.
+
+The gate's evidence lands beside the other checkpoint gates at
+`derived.checkpoint_gates[]` (`id: built_output.script_syntax`, status `pass` |
+`blocked` | `not_applicable`, `findings[]` with `file`, `line`, `column`,
+`source_type` and `pages`, `warned[]` with `src` and `pages`,
+`scripts_scanned`, `scripts_unresolved[]`, `pages_scanned`). Fixtures: `fixtures/script-syntax/{good,bad}`. It passes, parsing every
+local script the pages load and with no missing-script warning, on the
+canonical rendered output of every certified starter family
+(`fixtures/certified-families/`). QA applies the same rule to the page scripts
+it reads for credential declarations (`script-parse:<page_id>`; see
+[QA and test orders](qa-and-test-orders.md)).
+
 > **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
@@ -1114,14 +1222,15 @@ and report proof policy fields above.
 
 | 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 |
+| `--spec <path>` | Local JSON file | Agent-authored local specs, saved-Map exports, offline work or CI fixtures |
+| `--map-id <id>` | Map Builder proxy (KV-backed) | Saved-Map intake from the current KV revision |
 
 When `--map-id <id>` is set, the CLI fetches `GET <proxy>/api/spec/<id>` (default `<proxy>` is `https://campaign-map.nextcommerce.com`) and caches the response to `<target>/.campaign-runtime/fetched-specs/<id>.json`. The cached file is what downstream stages read, so the packet's `spec.local_path` always resolves to an on-disk artifact regardless of intake mode.
 
-Retrieval behavior:
+Saved-Map retrieval behavior (`--map-id`):
 
 - **Re-fetch by default.** Every `start` / `prepare-build` invocation re-fetches from KV. KV is the source of truth; the cache file is a debug/inspection artifact, not a performance optimization.
+- **One writer at a time.** The fetch happens first, but the fetched spec is written to the cache file only once the run holds the per-target prepare-build lock. A second run against the same target, fetching a newer Map revision, waits for the lock before replacing the cache, so the run holding it records the hash of the revision it actually parsed.
 - **`--cached-spec`** reuses the cache without a network call. Use for offline iteration or when the proxy is temporarily unreachable.
 - **`--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.
@@ -1130,7 +1239,7 @@ The fetched spec is treated identically to a `--spec`-supplied local file from t
 
 ## 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)).
+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`. Each `pages[]` entry carries exactly one of `path` or `skip_reason`: an entry with both is invalid, and an invalid entry makes prepare-build ignore the whole manifest and fall back to filesystem matching. 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,
@@ -1140,7 +1249,10 @@ 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
+byte or refused; it is never silently regenerated. The one exception is a stale
+package an earlier `prepare-build` synthesized and nobody has changed since:
+`--force` regenerates it from the current inputs
+([Design Source Package: stale packages](design-source-package.md#prepare-build-emit-validate-or-refuse)). 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

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

@@ -2,7 +2,7 @@
 
 The happy path is intentionally tight:
 
-1. Export a saved local CampaignSpec JSON from Campaign Map Builder, including Map ID and public route slug.
+1. Use a saved Map export, or have the coding agent author a CampaignSpec from the brief and verified campaign values through the [local-spec entry](build-packet.md#local-spec-entry). Preserve its Map ID or stable `local_spec_id`, plus its public route slug.
 2. Run `campaigns-os start` with the CampaignSpec, prepared source files, target page-kit repo, and template family.
 3. Treat doctor as the first gate. If its `next` block says `doctor-blocked` or `prepare-build` (the same stage names `campaigns-os next` uses), stop and resolve the named blocker.
 4. Run setup when doctor asks for setup; otherwise continue to assembly.
@@ -11,7 +11,7 @@ The happy path is intentionally tight:
 7. Install the package-owned Playwright browser with `npm run qa:install-browser`.
 8. Run polish, serve the current built output, and run `campaigns-os polish capture --packet <packet> --base-url <served-current-build-url>`. Do not mark Polish terminal or begin deploy/QA until this package-owned page-load evidence passes or has an exact finding waiver.
 9. Deploy a preview.
-10. Run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` with the tested URL. QA runs publish to the QA portal by default (the QA tab records browser QA plus typed-card proof and the run prints its portal link); pass `--no-post-verdict` only for offline / dev / CI runs.
+10. Run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --browser --test-order common` with the tested URL. Saved-Map QA uses the existing consent and publication controls; pass `--no-post-verdict` to keep its verdict local. Local-spec QA always keeps verdicts and progress local, even with `--post-verdict`, and `qa publish` refuses local-spec packets. Run Telemetry retains its consent controls.
 11. Treat test-order depth as the control: global test cards bypass the gateway and create no transactions, so no approval is needed. Localhost on any port is a Campaigns App Development domain (SDK allowed, analytics suppressed); non-localhost preview/production origins must still be allowlisted for the campaign API key so the SDK loads.
 12. Promote, block, or iterate from the recorded build, polish, deploy, QA, and test-order evidence.
 
@@ -84,6 +84,7 @@ the assembly report.
 - **Pre-checkout pages must ship the same SDK bootstrap as the checkout layout.** Presell and landing pages are SDK `page_type: product`; they need `config.js` (before the loader), the `campaign-cart@v{sdk_version}/dist/loader.js` module script, and the `next-funnel` + `next-page-type` meta tags — not just inert `data-next-*` attributes. Without the loader the SDK silently no-ops: `data-next-hide` conditional visibility (`param.banner` / `param.seen`), `utmTransfer` UTM/query carry-through to checkout (top-of-funnel ad attribution), and SDK analytics never fire. Treat `param.banner` / `param.seen` visibility and `utmTransfer` as standard pre-checkout wiring, not per-campaign discoveries. Doctor enforces this with `built_output.pre_checkout_sdk_bootstrap`.
 - **Every page names the same campaign.** A page borrowed from another funnel (a copied upsell or receipt) must not keep the other campaign's `next-api-key` / `config.js` API key, `next-funnel` meta, or `setAttribution({ funnel })` call; the SDK reads these per page and reconciles nothing, so the order lands on or attributes to the wrong campaign with no visible error. Doctor blocks this, unwaivably, with `built_output.campaign_identity` (one error per drift, naming both files and both values).
 - **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first four as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- **Campaign scripts must parse.** A hand-edited script with a stray or missing bracket throws a `SyntaxError` on every page that loads it, and nothing in it runs. Doctor parses every campaign-owned `.js` file a built page loads by a local `<script src>` and blocks, unwaivably, with `built_output.script_syntax.parse_failure`, naming the file, line and column.
 - Checkout, upsell, downsell, and receipt pages should preserve starter-template SDK contracts while keeping the campaign/source visual language. Treat starter templates as the reference for required `data-next-*` controls and wiring, not as a mandate to carry their visual chrome into the final campaign.
 - If source HTML declares SDK-owned zones such as `data-commerce-zone="checkout-form"` or `data-commerce-zone="order-summary"`, adopt the selected starter-template family shell for that runtime page. Do not build a custom checkout/upsell structure around a few borrowed includes; browser QA will check declared family structure where `agentContract.qaStructure` exists.
 - If `context.theme` names a generated `brand-theme.css`, copy it into campaign assets and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. Generated brand-theme v0 is root-variable-only; do not use it as permission to edit SDK-owned selectors or runtime structure.

package/docs/design-source-package.md

@@ -335,14 +335,80 @@ If any current campaign, active/mapped page, source material, manifest or crawl
 provenance, coverage, template family/reference, material fingerprint,
 readiness, or readback check fails, `prepare-build` refuses. It leaves the
 existing package and packet/context/report/brief sidecars byte-identical. It
-does not silently regenerate or overwrite the package; source preparation must
-reconcile the package and its references explicitly before retrying.
+does not silently regenerate or overwrite the package. The refusal names the
+package file and says which recovery applies:
+
+- **A package `prepare-build` synthesized itself.** The Assembly Report's
+  `design_source_package` reference records `origin`: `"synthesized"` when
+  `prepare-build` wrote the package bytes (or reused bytes it had written), and
+  `"adopted"` when it validated and reused a package it did not write. When the
+  previous report at this run's report path says `"synthesized"` and the
+  package bytes still hash to that report's `sha256`, the stale package is the
+  producer's own output: rerun with `--force` and `prepare-build` regenerates
+  it from the current inputs (mode `regenerated`), announcing the replacement
+  on stderr. `--force` also resets any stage evidence the Assembly Report
+  carries, exactly as it does for the report alone.
+- **Any other package** — placed by an operator, edited by hand after it was
+  written, adopted by an earlier run, or recorded by a report that predates
+  `origin` — is never overwritten, `--force` or not. Reconcile it with the
+  current inputs, or, if no downstream stage has consumed it, delete it and
+  rerun so `prepare-build` synthesizes a fresh one.
+
+Only the Assembly Report carries `origin`; the packet and context references
+keep their four strict fields.
+
+The package is published before the report that records it. So that a run
+which fails or dies between the two does not leave its own package unprovable,
+`prepare-build` first writes a pending provenance record beside the package
+(`.campaign-runtime/input/.design-source-package.json.pending-provenance.json`)
+naming the sha256 of the bytes it is about to publish, and removes it once the
+Assembly Report is written. A `--force` run that replaces a stale package it
+proved its own keeps that package's sha256 in the record too, so a
+regeneration that fails or dies part way leaves whichever package is on disk
+provable. A run that finds another writer's package at the path and adopts it
+instead of publishing drops its own candidate from the record. A retry that
+finds the record treats a package whose bytes still hash to one of its entries
+as `"synthesized"`, exactly as if the report had recorded it; bytes changed
+since are not vouched for, and a malformed record vouches for nothing. Just
+before the report is published the record is narrowed to what the report
+records (the package's hash when synthesized, nothing when adopted), so no
+unpublished candidate outlives the report. The record's path is
+reserved like the other outputs, so no configurable output may point at it.
+
+Runs against the same target take turns. From the stage-evidence check and
+the reading of its inputs (CampaignSpec, source manifest, page mappings, asset
+crawl) through the packet, context and report that record them,
+`prepare-build` holds a lock directory beside the package
+(`.campaign-runtime/input/.design-source-package.json.lock`), so each run judges
+provenance against the report and package the previous run left, and records
+the inputs it actually read. With `--map-id`, the fetched spec is written to the
+shared `fetched-specs/` cache file inside the same lock, so a run waiting for
+the lock cannot replace the spec the lock holder is reading. The source-html
+manifest is read once: the `manifest_sha256` the package records is the hash of
+the exact bytes source intake parsed. Every command that edits the Assembly Report
+(`doctor`, `qa run`, waivers, the polish merge and the other stage producers)
+takes the same lock for its read-modify-write, so no stage evidence lands
+between `prepare-build`'s final stage-evidence check and its publication; a
+producer that `prepare-build` reaches from inside its own run enters directly.
+Of several concurrent `--force` runs, the first regenerates the package and the
+rest reuse it as `"synthesized"`. A command that finds the lock held waits up to
+a minute. The lock directory and its owner record appear together, so a lock
+left by a process that died is recovered automatically, and a lock directory
+without an owner record (only an older release leaves one) is never taken
+over: the command refuses it after about a second and names it. Confirm no
+campaigns-os process is working on the target, then remove it. Do not run an
+older Campaigns OS release against the same target at the same time. A
+waiver's `--dry-run` preview takes no lock.
 
 Before writing any output, `prepare-build` also requires distinct paths for the
 Build Packet, Build Context, Assembly Report, Doctor output, normalized Build
 Brief, and fixed Design Source Package. Equal paths and filesystem aliases are
 rejected, including symlinks, hard links, dangling leaf symlinks, and symlinked
-parent directories.
+parent directories. No output may be placed inside the lock directory, or
+inside the staging and tomb directories the lock creates beside it
+(`.lock.staging-*`, `.lock.recovery-staging-*`, `.lock.released-*`,
+`.lock.abandoned-*`), directly or through a directory alias: they are removed
+with their contents when the run finishes.
 
 This behavior is the implemented v0 compatibility boundary. It does not promise
 that a separate future workflow command will generate, repair, approve, or
@@ -504,10 +570,12 @@ Either declaration records the page on the assembly report's
 `template_family` set to the family the packet locks, lists it under
 `stages.prepare_build.declared_out_of_scope`, and reaches
 `stages.prepare_build.status: "completed_partial"`. Intake demands no design
-source for the page: no `capture-*` TODO, no `link-*` TODO. The build stage
-materialises it from the locked family's own page of that role — the `next
-build` prompt names every template-stock page and the family to copy it from —
-and the family decides only *how* the package records its coverage:
+source for the page: no `capture-*` TODO, no `link-*` TODO. This source-scope
+classification does **not** authorize publishing a stock page. `next build`
+keeps these routes unbuilt by default and requires explicit operator opt-in
+per page before materializing a stand-in from the locked family. In particular,
+presell and landing pages staying on another host must not be replaced with
+placeholder copy. The family decides only *how* intake records coverage:
 
 - **A family that publishes complete Template Reference proof — today `apollo`
   alone** — covers the page with synthesized `template_baseline` coverage from
@@ -533,10 +601,10 @@ not built yet`, and keeps checkout launch and test-order proof blocked while a
 runtime page (`select`, `checkout`, `upsell`, `receipt`) is among them. You get
 a terminal, honest intake — not a fully proven campaign.
 
-The build stage lifts those limits page by page. `next-campaigns-build`
-materialises each template-stock page from the locked family's own page of
-that role (the pre-checkout `select` step first, because it seeds the cart the
-runtime pages read). Once the page's built HTML exists at its route under
+The build stage lifts those limits page by page for opted-in pages. It uses
+the locked family's own page of that role (an opted-in pre-checkout `select`
+stand-in first, because it seeds the cart the runtime pages read).
+Once the page's built HTML exists at its route under
 `_site/<slug>/`, doctor reads the `template_stock` marker on the scope decision
 and counts the page as built: it moves into `derived.scope.built_pages` (with
 `template_stock: true`, `template_family`, and no `source_path`), joins the
@@ -565,10 +633,10 @@ family the `template-baseline` contribution's `presentation_intent` names.
 
 ### Recovery after a blocked first run
 
-A blocked run still emits the package, and `prepare-build` never refreshes a
-package it did not just create. So a first run that blocked leaves a package
-whose provenance names the *old* manifest, and simply rerunning with a new
-manifest fails closed:
+A blocked run still emits the package, and a plain `prepare-build` never
+refreshes a package it did not just create. So a first run that blocked leaves a
+package whose provenance names the *old* manifest, and simply rerunning with a
+new manifest fails closed:
 
 ```
 campaigns-os: Design Source Package at <target>/.campaign-runtime/input/design-source-package.json
@@ -597,6 +665,12 @@ npm run campaigns-os -- start \
   --template-family <family>
 ```
 
+When the refusal says the package was synthesized by an earlier
+`prepare-build` and is unchanged since, skip step 2 and add `--force` to step 3
+instead: `prepare-build` (and `start` and `build`, which run the same intake)
+then regenerates the package itself. `--force` resets any stage evidence the
+Assembly Report carries, so the same caution applies.
+
 Step 2 is only ever correct for a package emitted by a blocked run that no
 downstream stage has consumed. Once Build or Polish has bound its evidence to a
 package fingerprint, deleting it invalidates that evidence; reconcile through

package/docs/effects.md

@@ -9,6 +9,13 @@ The point of the file is not the prose. It is that **every row is proved by a
 test** (`src/effects.test.mjs`), and a row without its test cannot be published:
 `npm run check:effects` refuses it.
 
+`tooling setup` composes the existing skill/context/browser installers after a
+project-pin and preservation preflight. It also appends a project `CLAUDE.md`
+import. It bypasses session recovery, gateway credential reads and lifecycle
+capture; `--dry-run` is read-only. Like `qa install-browser`, its browser download
+has preflight-only effects proof offline; setup's preservation and recovery
+behavior has focused tests.
+
 - The contract: [`contracts/effects.v1.json`](../contracts/effects.v1.json)
 - Its shape: [`schemas/campaigns-os-effects.v1.schema.json`](../schemas/campaigns-os-effects.v1.schema.json)
 - The proof: `src/effects.test.mjs`
@@ -67,7 +74,7 @@ with one of these:
 | `{lifecycle-journal}` | The command-lifecycle journal wherever it was selected for this invocation. |
 | `{proxy-base}` | The endpoint `--proxy-base` names, or the canonical NEXT endpoint when it does not. |
 | `{base-url}` | The campaign under test, as `--base-url` names it or as the packet derives it. |
-| `{playwright-download-host}` | Where Playwright fetches browser builds from: `PLAYWRIGHT_DOWNLOAD_HOST` when set, else the Playwright CDN. The one destination in the file that is not a Campaigns OS endpoint — `qa install-browser` is the one supported invocation that downloads from a third party. |
+| `{playwright-download-host}` | Where Playwright fetches browser builds from: `PLAYWRIGHT_DOWNLOAD_HOST` when set, else the Playwright CDN. The third-party browser download used by `qa install-browser` and `tooling setup`. |
 
 The tokens matter because effects are not all under the target. `install-skills`
 writes your **home** directory, not the campaign. `telemetry on` writes your
@@ -127,7 +134,76 @@ a flag the command rejects up front. It writes nothing, journals nothing, and is
 the row to read when you want to know what a typo costs. The one exception is
 declared on the rows it belongs to: `start`, `prepare-build`, `build`,
 `run start` and `run end` close out a **stale** run session at the root they are
-about to act on *before* argv is refused.
+about to act on *before* argv is refused. Commands that implement `--dry-run`
+skip this closeout whenever that flag is present, including a valued flag that
+will be refused: `run end --dry-run yes` writes, sends, and deletes nothing.
+
+A refusal is decided by argv alone. When file content or state on disk decides
+the outcome, the command has reached a handler failure and journals it.
+
+For intake, run-record, built-site QA, and `next`, argv-only checks run before
+their handler reads the target; invalid values are refused without a journal
+entry. For `start`, `prepare-build`, and `build`, bare, empty, and whitespace-only
+values of `--spec`, `--map-id`, `--source`, `--target`, `--source-kind`,
+`--proxy-base`, `--wrapper-policy`, `--design-manifest`, `--order-path-depth`,
+`--template-family`, `--allow-uncertified-template`, `--theme-policy`, and
+`--brief` are refused before local spec reads, Map fetches, or cache writes on
+the `--spec`, `--map-id`, and `--map-id --cached-spec` paths. So is a
+`--theme-policy` outside `inspect_only`, `auto`, and `off`. Whether a named
+template family is certified, and whether a named brief can be read, depend on
+file content: those checks still run in the handler and are journaled.
+The operator-facing `run-record` and `run end` commands refuse bare, empty, or
+whitespace-only values for every value-taking inherited run-record flag before
+packet work. The five agent
+token and elapsed-time flags retain their non-negative-integer diagnostics;
+`--surfaces` rejects unknown values, and `--dry-run` rejects a value. The
+inherited boolean flags (`--no-remit`, `--no-write`, `--dry-run`, and `--json`)
+retain their bare-flag behavior. `run end` also rejects `--new-run` and
+`--run-id` because the saved session fixes its run ID. `run-record` also
+rejects bare, empty, or whitespace-only `--run-id` and valued `--new-run`.
+Internal stale-session and QA closeouts retain the previous handling of values
+inherited from their invoking commands. A bare, empty, or whitespace-only
+`--proxy-base` on a sweeping command still writes the stale Run Record.
+Terminal QA auto-end tolerates whitespace-only inherited `--context`,
+`--report`, or `--proxy-base`. A whitespace-only `--context` resolves as a
+literal relative path, so the default context file is not read. Bare or empty
+`--context` or `--report` still makes QA auto-end fail and leaves the session
+open; bare or empty `--qa-verdict` fails a Run Record closeout when inherited,
+though QA auto-end supplies its own verdict path. The underlying run-record
+handler still rejects invalid agent
+integers, unknown `--surfaces`, and any valued `--dry-run` that reaches it. QA
+auto-end drops `--dry-run` from inherited flags; if another inherited value
+fails in the handler, auto-end is skipped and the session stays open. QA's own
+journal entry is unaffected because auto-end runs after QA persistence. A named
+`--design-manifest` that is missing or is not a file is checked
+against the filesystem after intake has begun, so that failure is journaled.
+An invalid manifest's contents are likewise a handler failure. A `next` stage
+must be one of the stages in the orchestration stage contract; an unknown name
+is refused before the `next` handler reads the packet, runs doctor, or writes
+doctor output. The ambient run-session lookup in `main()` may read a named
+`--packet` before the handler runs.
+
+`polish capture --packet` would report "polish capture requires
+packet.assembly.target_repo to resolve to a local target repo" as a journaled
+handler failure because packet content would decide it. Today the workspace
+resolver always yields a local path, so this check does not fire through the
+CLI. `run end` reports "run end needs a build packet" as a journaled handler failure
+when the saved session has no packet and argv names none. For `qa run` and `qa
+resolve`, "QA requires a Map ID" is a refusal when argv carries no non-empty
+`--packet`, `--site`, `--built`, positional Map ID, or `--map-id` value. A selector
+flag without a value is refused with "Missing value for --<flag>". If a named
+packet yields neither a Map ID nor a valid local-spec identity after checkpoint
+preflight reads the packet, spec, and report, the requirement is a journaled
+handler failure. A conflicting local/Map identity is also a handler failure.
+When `qa run` selects `--legacy-api-test-order`, a missing, bare, empty, or
+unusable `--cart` and an unknown legacy mode are argv-only refusals before QA
+input resolution. They append no lifecycle entry. Accepted modes remain
+`accept`, `decline`, and `both` (case-insensitive); browser `--test-order` still
+takes precedence and does not require the legacy cart. API credentials are
+still checked only inside the legacy handler and failures there are journaled.
+The nested run-record refusal scope in session closeout guards against future
+changes. No internal closeout can currently create a refusal before its
+invoking command journals.
 
 ## How a row is proved
 
@@ -279,3 +355,8 @@ reason. What it may not be is silent.
 Change the effect, change the row, in the same PR. The effect test will tell you
 which row is wrong before review does: it names the path that moved and the row
 that failed to declare it.
+
+Local-spec QA retains its artifacts locally. It never sends a verdict or progress
+to the Map portal, even when `--post-verdict` is supplied; `qa publish` refuses
+local-spec packets. Commerce API reads, served-page probes and requested typed-card
+orders keep their existing effects. Run Telemetry still follows its consent controls.

package/docs/local-setup.md

@@ -0,0 +1,51 @@
+# Local campaign setup
+
+For a new campaign, choose its working folder and run this from that folder:
+
+```sh
+npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.43.2 next-campaign-page-kit@0.2.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
+```
+
+Review the release source/provenance before installation as described in
+`AGENTS.md`. npm installs the dependencies first; `--no-install` then runs only
+the project's installed CLI. Keep `package.json` and `package-lock.json` in
+Git. For an existing project, preserve its reviewed pin: run `npm ci`, then
+`npx --no-install campaigns-os tooling setup --target . --platform claude`
+on a release that supports setup. Changing the pin is a separate update.
+
+Setup checks the exact toolkit pin, its lockfile version and the installed
+page-kit dependency before it changes files. It composes the existing
+installers to:
+
+1. Install the QA browser through this toolkit's own Playwright package.
+2. Install the bundled skills into `~/.claude/skills` (same-name skills are
+   refreshed just as with `install-skills`).
+3. Install the four context files under `.campaign-runtime/agent-context`
+   and the managed runtime ignore block.
+4. Append one import to the project's `CLAUDE.md`, preserving existing text.
+
+The import uses Claude Code's documented
+[`@path` syntax](https://code.claude.com/docs/en/memory#import-additional-files).
+Existing context that differs from the bundle and symlink destinations require
+reconciliation before setup; setup does not overwrite them. A repeated run
+preserves campaign pages, authored decisions and project instructions. If the
+browser download fails, fix that error and rerun setup; shared skills and
+project files have not been changed. If the runtime ignore block cannot be
+written, setup reports `context_install_failed`; fix `.gitignore` and rerun.
+`--dry-run --json` previews setup without any writes or browser download.
+
+Restart Claude Code in the campaign folder. Use the `next-campaigns-os` skill
+and provide the configured campaign details, HTML/assets and brief. The agent
+authors a local CampaignSpec if there is no saved Map export; follow the
+[local-spec entry](build-packet.md#local-spec-entry). The skill checks its
+loaded bundle revision against the project copy.
+`restart_required` means the files are installed; it does not prove that the
+running agent has loaded them. Check Claude's `/context` view if the project
+instructions are missing.
+
+Setup does not scaffold template pages, create a CampaignSpec, connect the
+gateway, change a saved Map, run a campaign session, remit telemetry, or prove
+checkout. The agent performs intake and chooses the template before assembly.
+A local spec uses `spec_identity.local_spec_id` and keeps its evidence in the
+repository. Existing doctor/QA gates still apply. This entry is Claude Code first; other agents retain their existing
+manual installation path.