@nextcommerce/campaigns-os 1.33.0

package/docs/campaign-build-brief.md

@@ -0,0 +1,145 @@
+# Campaign Build Brief
+
+The Campaign Build Brief is the merchandising and design-presentation truth for a Campaigns OS build.
+
+CampaignSpec remains the operational truth: packages, offers, shipping, routing, SDK hints, payment/runtime values, and API identity. The Build Brief answers business-owned presentation questions that agents should not infer silently: page authority, palette and CTA treatment, product media rules, pricing display, promo language, payment/trust surfaces, canonical names, residue policy, and QA expectations.
+
+## Artifact Locations
+
+Campaigns OS accepts YAML or JSON:
+
+```bash
+campaigns-os prepare-build \
+  --source ./design-export \
+  --spec ./campaign-spec.json \
+  --target ./merchant-campaign \
+  --template-family olympus \
+  --brief ./campaign-build-brief.yaml
+```
+
+`campaigns-os build` is an intake alias for the same flow plus doctor.
+
+If `--brief` is omitted, `prepare-build` looks for:
+
+- `campaign-build-brief.yaml`
+- `campaign-build-brief.yml`
+- `campaign-build-brief.json`
+
+It checks the source root first, then the target repo. If none exists, Campaigns OS writes a guided draft to:
+
+```text
+.campaign-runtime/input/campaign-build-brief.normalized.json
+```
+
+The Build Packet, Build Context, and Assembly Report all reference that normalized artifact so it survives handoff, compaction, rebuilds, polish, and QA.
+
+## Modes
+
+Prepared mode is for veteran users. A complete brief should let the build proceed without business questions. If a supplied brief is incomplete or contradictory, doctor blocks with `build_brief.*` errors.
+
+Guided mode is for new or partial inputs. Campaigns OS drafts a brief from CampaignSpec, page mappings, template family, source assets, and available runtime hints. It records only high-impact unresolved questions as warnings so existing builds still run while the business uncertainty is visible.
+
+## High-Impact Questions
+
+Guided questions are intentionally short and business-readable. They prioritize:
+
+1. Which source controls each page?
+2. Which palette/CTA style should commerce pages use?
+3. Which product variants/colors are actually sold?
+4. How should bundle pricing be presented?
+5. What promo/savings/urgency language is approved?
+6. Which payment methods/trust badges may appear?
+7. Are runtime/catalog names allowed to override provided display names?
+8. Are there regulated claims or forbidden copy areas?
+
+The CLI avoids SDK/page-kit jargon in questions. The implementation can resolve SDK attributes, responsive CSS, asset paths, routing, template copying, and QA reruns. Business choices should come from the brief or be escalated.
+
+## Risky Defaults
+
+Doctor blocks or asks when a prepared brief leaves high-impact questions unanswered, forbids alternate variant colors without naming sold variants, or contains direct contradictions such as the same payment method being both allowed and hidden.
+
+Doctor warns when generated guided drafts still need answers, a brief allows payment methods not observed in CampaignSpec, or a brief does not explicitly block promo/template placeholders.
+
+Existing template residue, theme, pricing, and built-output checks continue to run. The brief gives those checks business intent instead of replacing them.
+
+## Content Claims Are Reviewed, Not Enforced
+
+The doctor scans built output for content residue and raises some of it as
+warnings: every content anti-pattern under the warning code
+`content_residue.anti_pattern` (the finding ids include `invented_counts`
+for invented counts and ratings, `verified_buyer_chrome` for "Verified
+Buyer" and similar review chrome, `byline_persona`, `borrowed_authority`,
+`press_marquee`, and `science_theater`; all of them are warning-only), and
+promo copy claiming a discount above the CampaignSpec maximum (`template_contract.discount_claim_residue`, or
+`template_contract.discount_claim_unverified` when the spec sets no maximum).
+
+These stay warnings on purpose, and nothing downstream reads them. There is no
+blocker, no `blocked_stages` entry, no QA assertion, and no test-order gate
+keyed on any of them. A build carrying all of them can pass doctor, pass QA,
+and deploy.
+
+The toolkit flags the copy; it does not adjudicate it. **Responsibility for
+every claim on the page — proof counts, review chrome, discount percentages,
+and the rest — sits with the operator and the client, not with Campaigns OS.**
+Use the brief to record which claims are approved and which language is
+forbidden (see the high-impact questions above), and treat a content warning as
+a prompt to check the brief, not as a gate that will stop the build if you
+ignore it.
+
+The hard content checks are separate and do block: the needs-merchant-input
+marker (`content_residue.needs_merchant_input`) and countdown chrome rendered
+without verified offer urgency on a brief-backed build
+(`content_residue.unverified_urgency`).
+
+## QA Policy Scope
+
+`qa_policy` records business expectations for the proof pass, such as desktop/mobile screenshots, checkout flow coverage, post-purchase coverage, visible-placeholder handling, and runtime-data comparison. It is not the doctor/QA enforcement contract by itself.
+
+Normalized briefs include `qa_policy.enforcement.status: documented_expectation` so consumers do not mistake these fields for direct gates. Doctor and QA enforce the Build Packet `qa.proof_policy` and Assembly Report `report.proof_policy` contract, which names browser QA, typed-card depth, SDK origin allowlist state, order path depth, and operator approval state.
+
+## Generic Scenarios
+
+Single-variant gadget:
+
+- One physical product, one sold color.
+- Landing page owns the palette.
+- Checkout inherits landing CTA style.
+- Carousel avoids alternate colors.
+- Bundle cards emphasize unit price and simple savings badges.
+
+Multi-variant apparel:
+
+- Product has several colors/sizes.
+- Variant selector is allowed.
+- Media may show multiple colors only when the selected-variant workflow supports it.
+- Product imagery must not imply unavailable sizes/colors.
+
+Consumable subscription:
+
+- One-time and subscribe-and-save offers may coexist.
+- Pricing separates first-order savings from subscription terms.
+- Promo timers avoid false urgency when the offer is evergreen.
+
+Home goods bundle:
+
+- Main product plus accessories.
+- Bundle cards emphasize included items, not only percentage savings.
+- Lifestyle images can show room scenes, but the product must remain inspectable.
+
+Digital or service add-on:
+
+- Physical variant imagery is not required.
+- OTO copy emphasizes scope, duration, and support terms.
+- Shipping copy is hidden.
+
+Health/wellness product:
+
+- Claims require stricter copy boundaries.
+- The brief should list forbidden claims and approved benefit language.
+- QA should flag unapproved medical or guaranteed-outcome wording.
+
+High-compliance financial or regulated offer:
+
+- Promo and urgency copy defaults conservative.
+- Trust badges and claims must be source-backed.
+- Savings, guarantees, or scarcity language requires explicit approval.

package/docs/campaign-standardization-report.md

@@ -0,0 +1,329 @@
+# Campaign Standardization Report
+
+The Campaign Standardization Report is a read-only audit for campaign
+repositories across the campaign ecosystem. It discovers campaign roots,
+classifies each root's implementation, inventories source structure and
+runtime contracts, validates checkout field bindings and SDK loader versions
+against contracts, and names the next safe remediation category without
+editing the target repo.
+
+Two implementation kinds are recognized:
+
+- `page_kit` — modern CPK roots (`_data/campaigns.json` or a
+  `next-campaign-page-kit` dependency). Existing sections and finding codes
+  are unchanged.
+- `campaign_cart_app` — non-Page-Kit applications (Vite/React/Express apps,
+  static HTML funnels) detected through portable Campaign Cart evidence: the
+  loader script URL, `meta[name="next-campaign-id"]`, `window.nextConfig`, or
+  a sufficient density of `data-next-*` anchors. Evidence is rolled up to the
+  nearest `package.json` boundary; one strong signal (or ≥5 weak anchors)
+  classifies the root. Directories already claimed as Page Kit roots are never
+  double-claimed, nested application roots are scanned independently (a parent
+  root never re-reports a nested root's files), and a parent repo may contain
+  both kinds side by side. HTML comments are masked throughout, so
+  commented-out loaders, bindings, or radios never produce evidence or
+  findings.
+
+Every root carries `implementation` (`kind`, `evidence`, `frameworks`) and
+`capabilities` — the inspections that actually ran for that root, never a
+standing list per kind. A `page_kit` root always lists
+`page_kit_source_contract`, `sdk_version_policy` and
+`campaign_cart_runtime_inventory`; it adds `checkout_field_contract` only
+when its source inlines checkout bindings (the attributes the field
+contract's `binding_attributes` names; bundled: `data-next-checkout-field` /
+`os-checkout-field`), and `built_output_doctor` only once a built-output doctor result is
+attached (so never under `--no-doctor`, never without a `_site`, never while
+the built slug is unresolved). A `campaign_cart_app` root lists
+`campaign_cart_runtime_inventory`, `sdk_loader_discovery`,
+`sdk_version_policy`, `checkout_field_contract` and
+`payment_interaction_risk`. Composition is capability-based rather than a
+repository-type switch (see `campaign-ecosystem-standardization-design.md`).
+
+Run it against a Page Kit root, a parent `*-cpk` repo, or any campaign
+application checkout:
+
+```bash
+campaigns-os standardize --target /path/to/example-cpk --json
+campaigns-os standardize --target /path/to/example-cpk --family olympus-mv-single-step --slug example --json
+```
+
+The command is spelled `standardize`. It had a second spelling,
+`standardization-report`, which dispatched to the same code with the same
+flags and the same output; that spelling was removed at supported surface
+1.27.0 and now returns the unknown-command error, so a script still using it
+must be retargeted at `standardize`. The report's own
+`schema_version` is unaffected.
+
+By default, the command prints markdown for operators. Use `--json` for agents
+or dashboards. When a built `_site` exists, the built slug is resolved, and a
+template family is explicit or can be found in `.campaign-runtime`, the
+command also runs the existing `doctor --built` checks and folds those
+findings into the report. Use `--no-doctor` to keep the run to source/runtime
+inventory only.
+
+The command is read-only: it never writes into the target repository, and
+tests hold it to that (every file's size, mtime and content hash are identical
+before and after a run that includes the built-output doctor, and again with
+`--no-doctor`, and again when the target already carries a
+`.campaign-runtime/doctor-output.json`). `--no-doctor` only skips the
+built-output doctor pass inside the report; there is no write for it to
+skip. That last case is the one #312 reported as a write: the repro copied
+an example target with `cp -R`, which copies gitignored files, and the
+checkout's example carried a doctor sidecar from an earlier `doctor` run. A
+`.campaign-runtime/doctor-output.json` under a target you just ran
+`standardize` against was written by one of the four producers named in its
+`generated_by` field (`doctor`, `next`, `start`/`build`, `qa run`) — read that
+field before attributing the file.
+
+### Flags
+
+`standardize` accepts exactly `--target`, `--family` (alias
+`--template-family`), `--slug`, `--sdk-support-policy`, `--field-contract`,
+`--no-doctor`, `--json`, and the two flags every command accepts,
+`--run-id` and `--lifecycle-journal`. Any other flag is refused before the
+scan starts, with the known list in the message — including the
+`--flag=value` spelling, which the parser would otherwise store as an unknown
+key (`--no-doctor=maybe` used to run the doctor anyway). Values follow the
+flag as the next argument.
+
+### Exit codes
+
+- `0` — the report was produced and `ok` is `true` (`status` is `ready` or
+  `ready_with_warnings`).
+- `1` — the command did not run: an unknown flag, a missing `--target`, or a
+  missing or unparseable `--sdk-support-policy` / `--field-contract` file.
+  Nothing is printed on stdout; stderr carries one named error.
+- `2` — the report was produced and `ok` is `false` (`status` is
+  `blocked`, including `campaign.root_not_found`).
+
+### When `--slug` matters
+
+The built-output scope is the directory under `_site/` whose pages the
+built-output doctor inspects. It is resolved from, in order: `--slug`; the
+single slug `_data/campaigns.json` declares; the `campaign.public_route_slug`
+the `.campaign-runtime` packets name, when every packet that names one
+agrees; and, only when none of those exists, the
+`_site/` layout itself (one html-bearing directory, or root-level html). The
+report records the choice as `built_output.slug` and `built_output.slug_source`
+(`operator_flag`, `campaigns_json`, the packet's relative path, or
+`site_layout`), and `identity.campaign_slug` / `identity.campaign_slug_source`
+carry the same answer. Two outcomes replace a silent guess:
+
+- `built_output.scope_unresolved` (operator readiness) — `_site/` holds more
+  than one html-bearing directory and no slug source names one. This is the
+  case that needs `--slug`; the finding lists `slug_candidates` and the
+  doctor proof command carries a `--slug <slug>` placeholder.
+- `built_output.slug_mismatch` (operator readiness) — the slug came from
+  `campaigns.json` or a packet, but `_site/` has no directory for it. The
+  built output belongs to some other campaign (a stale build, typically), so
+  the doctor is skipped and the finding names the expected slug, its source,
+  and the directories that are there. When `_site/<slug>/` exists but holds
+  no HTML pages the same finding says so (`exists but holds no HTML pages`,
+  evidence `slug_directory_present: true`) rather than calling the directory
+  missing. Rebuild, or pass `--slug` to inspect a different directory on
+  purpose.
+
+Whenever a slug was needed, the doctor proof command under `remediation`
+carries it (`--slug <resolved>`), so the command the report hands back is the
+one that reproduces its own result.
+
+## Schema
+
+Top-level shape:
+
+```json
+{
+  "schema_version": "campaign-standardization-report/v0",
+  "generated_at": "2026-07-06T00:00:00.000Z",
+  "target_repo": "/path/to/example-cpk",
+  "status": "ready_with_warnings",
+  "ok": true,
+  "summary": {
+    "root_count": 1,
+    "blockers": 0,
+    "warnings": 2,
+    "operator_readiness": 1,
+    "blocked_roots": 0,
+    "warning_roots": 1,
+    "ready_roots": 0
+  },
+  "roots": [],
+  "errors": [],
+  "recommendation": {
+    "home": "staged_split",
+    "summary": "Keep the read-only source/runtime scanner in public campaigns-os first; layer private repo discovery, issue creation, and merchant ops context in an internal campaign-ops wrapper."
+  }
+}
+```
+
+### Campaign Cart application roots
+
+`campaign_cart_app` roots contain: `implementation`, `capabilities`,
+`identity` (campaign IDs, loader-discovered SDK versions, runtime artifact
+presence), `sdk_loader` (each loader reference with path/line/URL/version),
+`version_policy` (policy source + per-version evaluations, separate from
+version discovery), `checkout_fields` (every
+`data-next-checkout-field`/`os-checkout-field` binding classified as
+`supported`, `stale_alias`, or `unknown` against
+`contracts/campaign-cart-checkout-field-contract.v0.json`), `payment`
+(SDK `payment_method` radios, hidden radios, custom triggers, synchronization
+script evidence, and `proof_state`), `runtime_contract`, `findings`, and
+`remediation`.
+
+`sdk_loader.references` records pinned and unpinned loader refs alike
+(`version` is null for `@latest`/branch/commit pins, which raise
+`version.sdk_loader_unpinned` instead of a policy evaluation). Only URLs that
+point at a loader/dist artifact count; incidental `campaign-cart@x.y.z`
+strings elsewhere in source are ignored.
+
+`payment.proof_state` is one of `runtime_proof_required` (custom-control
+evidence found), `undetermined` (radios exist; static scanning cannot exclude
+externally-styled custom controls), or `not_applicable` (no `payment_method`
+radios). The scanner never affirms that behavioral proof is unnecessary when
+payment radios exist.
+
+Ecosystem findings carry a `confidence` field:
+
+- `static_contract` — provable from source against a named contract (stale
+  field aliases, SDK version below policy). Safe repair targets.
+- `static_inference` — heuristic source evidence. Informs risk only.
+- `runtime_proof_required` — behavior only a DOM/browser test can confirm
+  (custom payment controls driving the real radios). Reported as *missing
+  proof*, explicitly not a confirmed failure.
+
+The SDK support policy lives in
+`contracts/campaign-cart-sdk-support-policy.v0.json` and is injectable per run
+via `createStandardizationReport({ sdkSupportPolicy })`; the field contract is
+similarly injectable via `fieldContract`. "Latest" is never frozen into
+scanner code.
+
+Both contracts apply to both root kinds. The SDK support policy judges every
+discovered SDK version — a `campaign_cart_app` root's loader pins and bundled
+dependency, and a `page_kit` root's `_data/campaigns.json` `sdk_version`
+values — with one rule: below `minimum_supported` is the blocker
+`version.sdk_below_minimum_supported`, below `preferred_minimum` is the
+warning `version.sdk_below_preferred_policy`, and each message names the
+policy source. Every root records the policy it was judged by under
+`version_policy` (`source`, `minimum_supported`, `preferred_minimum`,
+`evaluations[]` with a `source` of `loader`, `bundled_dependency` or
+`campaigns_json` per version), and the markdown prints it as
+`Version policy: min X, preferred Y (source)`. The bundled policy is
+`0.4.20` minimum / `0.4.30` preferred. The Page Kit dependency cutoff is
+separate: `version.page_kit_below_preferred_cutoff` fires below `0.1.1`, a
+constant in the scanner, because the policy contract has no Page Kit field.
+The checkout field contract runs wherever inline checkout bindings exist; a
+Page Kit root that inlines them gets the same `checkout_fields` block and the
+same `checkout.unsupported_field_binding` / `checkout.unknown_field_binding`
+findings as an application root.
+
+Both are also injectable from the CLI: pass
+`--sdk-support-policy <path-to-json>` and/or `--field-contract <path-to-json>`
+to `standardize`. Each file is read and JSON-parsed
+(a missing or unparseable file is a clear, named error) and overrides the
+bundled contract for that run, for every root the run discovers:
+
+```bash
+campaigns-os standardize --target /path/to/example-cpk \
+  --sdk-support-policy ./my-sdk-policy.json \
+  --field-contract ./my-field-contract.json --json
+```
+
+When no root of either kind is detected, the report carries a single
+`campaign.root_not_found` error (this replaced the earlier
+`page_kit.root_not_found` code when ecosystem detection landed).
+
+### Page Kit root sections
+
+Each Page Kit root contains these sections:
+
+- `identity`: repo name, Page Kit root, slug inventory, SDK versions, Page Kit
+  dependency, template family evidence, certification freshness for that
+  family, Campaigns OS artifact presence, and built-site presence.
+  `template_certification_freshness` states the SDK version the family was
+  last verified against and the current SDK recorded by the vendored
+  contracts (the commerce surface catalog snapshot's per-family
+  `verification` blocks plus the SDK support policy) — an older evidence
+  record is not current certification. Families with no verification record
+  on the snapshot report freshness as unknown rather than inventing one.
+- `source_structure`: HTML/page/include/layout counts, Liquid helper counts,
+  raw blocks, document wrappers, hardcoded root asset refs, unreadable files,
+  and payment-method include detection.
+- `runtime_contract`: `data-next-*` anchor summary, checkout/upsell/receipt
+  surface signals, package/shipping refs, source manifest presence, and
+  `.campaign-runtime` inventory.
+- `version_policy`: the SDK support policy the root was judged by and its
+  per-version evaluations (see above).
+- `checkout_fields`: present only when the root inlines checkout bindings;
+  the same shape as on application roots.
+- `built_output`: built page inventory, the resolved slug and its source,
+  slug-scope resolution state (`slug_candidates` when unresolved), and
+  optional built-output doctor result.
+- `findings`: normalized blocker, warning, and operator-readiness items with
+  evidence and next action.
+- `remediation`: safe agent repairs, clarification needed, product or merchant
+  risks, and proof commands.
+
+## Finding Taxonomy
+
+`standardization_blocker` means an agent should not assume the repo is portable
+or standard without repair. Current blockers include missing or invalid
+`_data/campaigns.json`, an SDK below the policy's minimum supported version,
+stale checkout field aliases, Liquid raw blocks, and built-output doctor
+errors.
+
+`standardization_warning` means the repo can be inspected but may drift from the
+modern CPK contract. Current warnings include an SDK below the policy's
+preferred minimum, a Page Kit dependency below `0.1.1`, missing Campaigns OS
+artifacts, hardcoded `/assets/...` refs, page-level
+document wrappers, unreadable source files, missing `campaign_asset`, missing
+`data-next-*` anchors, and tentative payment-method include gaps.
+
+`operator_readiness` means the repo may be technically inspectable but lacks
+proof or business context. Current readiness items include missing built output,
+unknown or tentative template family, missing source-html manifest, unresolved
+built slug, a built slug with no matching built directory, and unknown
+production proof.
+
+## Home Recommendation
+
+Use a staged split:
+
+- Put the read-only scanner, schema, markdown formatter, and built-output doctor
+  integration in public `campaigns-os`.
+- Put private repo discovery, sample-set selection, merchant launch context,
+  issue creation, and workbench UI surfacing in an internal campaign-ops wrapper.
+
+This keeps the portable contract close to the existing Campaigns OS doctor while
+leaving private operational workflow outside the public package.
+
+## First Follow-Up Backlog
+
+- Add schema validation once the artifact shape settles across more repos.
+- Add explicit template-family evidence from CampaignSpec and Build Packet when
+  those artifacts are present.
+- Replace crude payment-method include detection with family contract checks.
+- Add optional `--output <path>` for durable JSON/markdown output.
+- Add repo-set orchestration in an internal campaign-ops wrapper for private
+  sample sets and follow-up generation.
+- Add waiver support for intentional one-off template deviations.
+
+## Ecosystem Follow-Up Backlog
+
+- Packetless `qa resolve/run` for existing funnels, keyed off the
+  standardization report, to convert `runtime_proof_required` payment findings
+  into behavioral proof (deterministic DOM test of custom controls driving
+  `input[name="payment_method"]`).
+- Deployed-URL-only assessment (no source checkout).
+- Origin/environment diagnosis as operator readiness: SDK origin allowlist
+  rejection (CORS) must be classified as merchant/environment configuration,
+  never conflated with an application integration defect.
+- Additional adapters: source-only exports, legacy CampaignsJS funnels,
+  CampaignSpec/Build Packet cross-checking for campaigns that carry full
+  Campaigns OS evidence.
+- Provenance refresh script for the field/policy contracts, mirroring the
+  starter-template catalog refresh.
+- Symlinked source directories are currently skipped (silent false negative)
+  and large vendored files are read whole; add link-following policy and a
+  file-size cap.
+- CSS-aware hidden-control detection (external stylesheets are not scanned;
+  `undetermined` proof state covers the gap honestly for now).

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

@@ -0,0 +1,117 @@
+# Campaigns OS Build Flow
+
+The happy path is intentionally tight:
+
+1. Export a saved local CampaignSpec JSON from Campaign Map Builder, including Map ID and 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.
+5. Assemble the page-kit campaign from starter-template contracts, not from copied demo commerce values.
+6. Run page-kit build plus SDK/template lint and record results in the assembly report.
+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.
+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.
+
+Pause only for missing inputs, doctor blockers, blocked deploys, out-of-scope runtime pages that block checkout proof, or merchant-specific uncertainty. The default path should not branch into external browser skills or hand-built backend order creation.
+
+## Partial Builds
+
+Partial builds are valid campaign work. A pass may build only new presell pages,
+landing pages, upsells, downsells, or another bounded slice that sends traffic
+to an existing downstream route. In the Build Packet, map pages being built with
+`source_html.pages[].path` and mark intentionally untouched pages with
+`source_html.pages[].skip_reason`.
+
+For mapped pages, `source_html.pages[].path` is source provenance. Use
+`source_html.pages[].page_kit` for the Page Kit target file, public route, CPK
+`page_type`, and frontmatter projection.
+
+`doctor` classifies that as `derived.scope.mode = "partial"`. Mapped pages are
+route/visual-testable after deploy. Skipped checkout, upsell, downsell, or
+receipt pages keep checkout launch readiness and test-order proof blocked until
+those runtime pages are built or explicitly delegated to an existing downstream
+URL.
+
+## Commerce Ownership
+
+- CampaignSpec/API own live campaign identity, routes, package refs, offer refs, shipping refs, payment support, tracking intent, footer links, and SEO values.
+- Starter template contracts own the SDK attribute contract and protected runtime surfaces: checkout/cart/upsell/receipt/payment/address/totals/submit controls and their required data attributes.
+- Designed source owns visual composition, content hierarchy, imagery, and page-level copy.
+
+Packages identify sellable products or variants, and Offers own campaign price changes. Package Retail Price/Quantity fields may exist on older campaigns, but assembly should not introduce them for new tier pricing.
+
+## Offer Application Surfaces
+
+CampaignSpec may declare checkout-level offer application behavior through
+`funnels[].pages[].exit_intent` and `funnels[].pages[].promo_code_input`.
+Treat these fields as intent for runtime checkout surfaces, not as separate
+pricing models:
+
+- `exit_intent.offer_ref_id` points at the configured campaign Offer.
+- `exit_intent.offer_code` is the voucher/promo code the runtime should apply
+  when the shopper accepts the pop.
+- `promo_code_input.offer_ref_id` points at the configured campaign Offer.
+- `promo_code_input.offer_code` is the voucher/promo code the runtime should
+  accept through the manual entry surface.
+- optional `notes` fields are build/QA implementation notes. Durable popup
+  copy, CTA labels, placeholders, success labels, and active labels belong to
+  the source design or selected template, not the Spec.
+
+Build should wire the selected starter-template checkout so the accepted offer
+is applied through the Campaign Cart SDK/Campaigns API path. Do not hardcode
+discount math, mutate static price literals, or treat the pop as an alternate
+bundle model. After the code is active, bundle selectors, totals, order summary,
+and discount rows should render from SDK/API state.
+
+Code-specific presentation belongs in SDK conditionals, for example:
+
+```html
+<span data-next-show='cart.hasCoupon("FREESHIP")'>Free shipping applied</span>
+```
+
+A promo-code box accepts a shopper-entered code and asks SDK/API to validate and
+apply it; it does not own pricing truth. When `promo_code_input.enabled` is
+declared, build should preserve or create the template/source promo-code surface,
+wire it to the mapped `offer_code`, and record the implementation decision in
+the assembly report.
+
+## Assembly Rules
+
+- Landing and presell pages should preserve prepared HTML when it is a real standalone design. Use page-kit passthrough structure, inject the SDK/config requirements, and repoint CTAs into the CampaignSpec flow.
+- **Pre-checkout pages must ship the same SDK bootstrap as the checkout layout.** Presell and landing pages are SDK `page_type: product`; they need `config.js` (before the loader), the `campaign-cart@v{sdk_version}/dist/loader.js` module script, and the `next-funnel` + `next-page-type` meta tags — not just inert `data-next-*` attributes. Without the loader the SDK silently no-ops: `data-next-hide` conditional visibility (`param.banner` / `param.seen`), `utmTransfer` UTM/query carry-through to checkout (top-of-funnel ad attribution), and SDK analytics never fire. Treat `param.banner` / `param.seen` visibility and `utmTransfer` as standard pre-checkout wiring, not per-campaign discoveries. Doctor enforces this with `built_output.pre_checkout_sdk_bootstrap`.
+- **Every page names the same campaign.** A page borrowed from another funnel (a copied upsell or receipt) must not keep the other campaign's `next-api-key` / `config.js` API key, `next-funnel` meta, or `setAttribution({ funnel })` call; the SDK reads these per page and reconciles nothing, so the order lands on or attributes to the wrong campaign with no visible error. Doctor blocks this, unwaivably, with `built_output.campaign_identity` (one error per drift, naming both files and both values).
+- **SDK markup must do what it says.** `data-next-checkout` goes on the `<form>`; `data-next-checkout-field` values are the SDK's fixed names (`fname`, `lname`, `postal` — never `firstName`, `lastName`, `zip`); an `add-to-cart` button linked by `data-next-selector-id` needs a selector with that id and that selector in `select` mode (swap mode plus the button writes the cart twice); one default-selected card per selector; single-brace tokens inside SDK templates. Doctor enforces the first four as blockers and the last two as warnings under `built_output.sdk_markup` (codes `SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`, `DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`).
+- 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.
+- Buy-more-save-more selectors should use selected quantity plus Offer-aware price displays. Do not swap in stale package-per-tier IDs unless the CampaignSpec explicitly represents an older campaign that still owns separate packages for each option.
+- SDK routing meta tags should be emitted as campaign-root paths, for example `/campaign-slug/upsell/`, even when the CampaignSpec source value is slug-relative like `upsell/`.
+- One-time prepurchase/order-bump packages outside the main bundle should default to fixed quantity and fixed line total display unless the spec explicitly requires syncing quantity with the main bundle.
+- Checkout exit-intent pops and promo-code inputs are protected offer application surfaces. Preserve/apply the selected family's SDK coupon/voucher hooks; skin the shell and copy around them.
+- Any source element dropped because the spec does not support it, such as PayPal when `available_payment_methods` excludes PayPal, should be recorded in the assembly report for polish.
+- After page-kit build, doctor checks rendered local script references plus rendered package and shipping refs against the CampaignSpec. Missing built scripts, stale package IDs, stale shipping IDs, and unavailable package refs must be fixed or intentionally blocked before QA.
+- Browser QA opens SDK-owned runtime pages once as a shopper and once with `?debugger=true`. The debugger pass should prove the Campaign Cart debugger overlay and selector controls mount without changing the normal checkout/test-order flow.
+- Browser QA also checks template-family commerce structure when the family contract declares machine-checkable selectors. Missing required Limos checkout shell markers, for example, are treated as a warning-severity failure: the checkout may load, but it is not proven as a conformant Limos checkout.
+
+## Synthetic Campaigns
+
+For AI-generated or synthetic campaigns, the static source page can be used to
+exercise the design-to-page-kit path, but SDK checkout still needs a Campaigns
+App campaign, store URL, packages, shipping/payment configuration, and an SDK
+origin that can load the campaign API key. Localhost on any port is available for
+Development-domain SDK checks, but a non-localhost preview/production origin must
+be allowlisted. If the evaluator has no natural merchant/store,
+reuse a designated test store and record that choice. Otherwise mark checkout,
+receipt, and test-order QA as blocked instead of debugging an SDK loading state
+as if it were a page-kit build failure.
+
+## Not Full Automation
+
+This repo improves first-run success. It does not yet prove a campaign is live-ready.
+
+Campaigns OS proof is not merchant launch readiness. Before launch, confirm the
+production storefront URL, live payment methods, shipping markets, legal/support
+URLs, analytics expectations, and merchant-side configuration.