@nextcommerce/campaigns-os 1.33.0

package/schemas/source-html-manifest.v0.schema.json

@@ -0,0 +1,252 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nextcommerce.com/schemas/source-html-manifest.v0.schema.json",
+  "title": "Campaigns OS Source HTML Manifest v0",
+  "description": "Producer-authored manifest consumed by Campaigns OS prepare-build. Paths are relative to the source HTML root, not the .campaigns-os directory.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["schema_version", "pages"],
+  "properties": {
+    "schema_version": {
+      "const": "source-html-manifest/v0"
+    },
+    "generated_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generator": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Producer identity such as figma-sections-export@1.2.3 or reference-ai-producer@1.0.0."
+    },
+    "campaign_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "root": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional producer hint. Manifest page paths still resolve relative to the source root passed to prepare-build."
+    },
+    "wrapper_policy": {
+      "type": "string",
+      "enum": ["strip_document_wrappers", "preserve_document_wrappers", "not_required", "unknown"],
+      "description": "Optional operator selection of the document-wrapper policy for this source, in the same vocabulary the Build Packet records at source_html.adapter_contract.wrapper_policy. prepare-build seeds the adapter contract from it, so declaring \"preserve_document_wrappers\" here reports source_html.prep.document_wrapper without blocking instead of requiring the wrappers to be stripped. The prepare-build --wrapper-policy flag overrides this key; with neither, the default is \"strip_document_wrappers\". A value outside the enum does not invalidate the manifest: the key is ignored with a warning naming it, the value, and the accepted values, and the rest of the manifest is used as written. See docs/source-adapters.md, section \"Source preparation check\"."
+    },
+    "producer_provenance": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Optional producer evidence. Required by doctor for Figma exporter manifests.",
+      "properties": {
+        "source_type": {
+          "type": "string",
+          "minLength": 1,
+          "description": "For figma-sections-export output this must be semantic_figma_export."
+        },
+        "screenshot_fallback_used": {
+          "type": "boolean"
+        },
+        "generator_repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "generator_version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "export_log": {
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "figma_file_key": {
+          "type": ["string", "null"],
+          "minLength": 1
+        },
+        "figma_file_keys": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "semantic_section_count": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "breakpoint_image_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "material_fingerprint": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "section_exports": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["section", "type"],
+            "properties": {
+              "section": { "type": "string", "minLength": 1 },
+              "type": { "type": "string", "minLength": 1 },
+              "file_key": { "type": ["string", "null"], "minLength": 1 },
+              "node_ids": { "type": "object" },
+              "partial": { "type": ["string", "null"], "minLength": 1 },
+              "images": { "type": "array" },
+              "command": { "type": ["string", "null"], "minLength": 1 },
+              "warnings": { "type": "array" }
+            }
+          }
+        }
+      }
+    },
+    "files": {
+      "type": "array",
+      "description": "Optional material inventory for drift/provenance checks.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["path", "role", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "role": {
+            "type": "string",
+            "enum": ["page", "partial", "layout", "asset", "export_log", "support"]
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
+    },
+    "pages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["page_id"],
+        "description": "Exactly one of path (bind a source HTML file) or skip_reason (declare the page out of source scope) is required per entry; the oneOf below enforces the exclusion.",
+        "oneOf": [
+          { "required": ["path"], "not": { "required": ["skip_reason"] } },
+          { "required": ["skip_reason"], "not": { "required": ["path"] } }
+        ],
+        "properties": {
+          "page_id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Active CampaignSpec page id. This is the primary join key."
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Source-root-relative HTML file path."
+          },
+          "skip_reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Reason this active page carries no source HTML (e.g. template-derived)."
+          },
+          "page_type": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional producer page type used for fallback matching only."
+          },
+          "page_url": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional producer/spec route used for fallback matching after Page Kit route normalization."
+          },
+          "source_hash": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "Optional sha256 of the source HTML file at manifest generation time."
+          },
+          "screenshots": {
+            "$ref": "#/$defs/sourceScreenshotList",
+            "description": "Operator-authored source screenshot proof for this page, consumed by prepare-build when it synthesizes the Design Source Package. A renderable primary-design page clears DESIGN_SOURCE_PACKAGE_NOT_READY with one available desktop source_screenshot record and one available mobile source_screenshot record, unless an accepted screenshot-absence Source Gap or an approved waiver recorded in the package covers it. The runtime manifest validator does not read this key; the producer normalizes it and is more tolerant than this declaration (it lowercases viewport and drops or nulls malformed values rather than failing). See docs/design-source-package.md, section 'Clearing DESIGN_SOURCE_PACKAGE_NOT_READY'."
+          },
+          "screenshot_refs": {
+            "$ref": "#/$defs/sourceScreenshotList",
+            "description": "Alias for screenshots; read by the same producer channel."
+          },
+          "source_screenshot_refs": {
+            "$ref": "#/$defs/sourceScreenshotList",
+            "description": "Alias for screenshots; read by the same producer channel."
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "sourceScreenshotList": {
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "type": "string",
+            "minLength": 1,
+            "description": "Id of a visual record already registered for this package. An unresolved id contributes no proof."
+          },
+          { "$ref": "#/$defs/sourceScreenshot" }
+        ]
+      }
+    },
+    "sourceScreenshot": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "One source screenshot record. Only an available source_screenshot record with a recognized viewport counts toward readiness. A record without a recognized viewport, or with a kind outside the enum, is dropped by the producer and counts as nothing; an unavailable record is retained as evidence of an absence and satisfies no viewport. Field aliases the producer also accepts: viewport_key for viewport; artifact_path or file_path for path; canonical_url for url; artifact_hash or hash for sha256; a nested dimensions object for width/height; capture_timestamp for captured_at; reason for unavailable_reason.",
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional stable record id. When omitted the producer derives one from the page surface, viewport, and a content digest."
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["source_screenshot", "unavailable_render"],
+          "description": "Defaults to source_screenshot, the only kind that counts as proof. unavailable_render is accepted and retained but never satisfies a viewport. Any other kind is dropped for this channel rather than promoted to source proof."
+        },
+        "viewport": {
+          "type": "string",
+          "enum": ["desktop", "mobile", "tablet"],
+          "description": "Required for the record to count as proof; desktop and mobile are the readiness-required viewports and tablet is optional in v0."
+        },
+        "availability": {
+          "type": "string",
+          "enum": ["available", "unavailable"],
+          "description": "Defaults to available when path or url is present. An unavailable record requires unavailable_reason."
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Screenshot file path relative to the source HTML root, not to the .campaigns-os directory. The producer records this path; it does not open the file."
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Screenshot URL, when the capture is hosted rather than local."
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^(sha256:)?[0-9a-f]{64}$",
+          "description": "Optional sha256 of the screenshot bytes, bare or sha256:-prefixed. The producer records it; it does not recompute or verify it."
+        },
+        "width": { "type": "integer", "minimum": 1 },
+        "height": { "type": "integer", "minimum": 1 },
+        "device_profile": { "type": "string", "minLength": 1 },
+        "scale_factor": { "type": "number", "exclusiveMinimum": 0 },
+        "browser": { "type": "string", "minLength": 1 },
+        "captured_at": { "type": "string", "minLength": 1 },
+        "unavailable_reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Why no capture exists. Required when availability is unavailable."
+        },
+        "notes": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/skills/next-campaigns-build/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: next-campaigns-build
+version: 1.0.2
+description: Assemble a NEXT campaign from a doctor-cleared Build Packet, CampaignSpec/API values, prepared HTML/assets, page-kit, and starter-template contracts.
+---
+
+# Next Campaigns Build
+
+## Recommended Build Loop
+
+For campaign builds, follow **build → independent review → repair → verification**.
+The main session owns the plan, integration, and final acceptance. Choose subagent
+assignments and models for the task's required capabilities and the consequences
+of failure, especially for SDK-owned commerce, payments, offers, and theme wiring.
+Among suitable models, prefer cheaper ones for bounded implementation, inspection,
+and repair.
+
+Have a fresh reviewer inspect the result against the source material and actual
+rendered or runtime evidence, without the builder's rationale. Keep one writer at
+a time. Resolve concrete findings and rerun the relevant checks before declaring
+completion. After two repair-and-verification rounds that leave the targeted
+finding or failing required check unresolved, reassess the approach or surface
+the blocker. Scale review depth to the task and preserve the existing checks and
+approval boundaries. Carry review and verification through the existing Polish
+and QA stages; assembly review does not replace them.
+
+If delegation is unavailable or disallowed, perform a distinct self-review in the
+current session and disclose that no independent agent reviewed the result.
+
+## Inputs and Build Rules
+
+Inputs:
+
+- `campaign-runtime.build.json`
+- `.campaign-runtime/build-context.json`
+- `.campaign-runtime/assembly-report.json`
+- local CampaignSpec JSON
+- prepared HTML/assets source
+- target page-kit repo
+- starter-template commerce catalog
+
+Build rules:
+
+- Read `families[template_family].agentContract` before editing commerce surfaces.
+- Use `sharedFrontmatterVocabulary` to identify values that come from CampaignSpec/API.
+- Replace `frontmatter.demoOnlyValues`.
+- Replace values named by `frontmatter.replaceFromSpecOrApi`.
+- Remove unsupported surfaces named by `frontmatter.removeWhenUnsupported`.
+- Preserve SDK-owned checkout/cart/upsell/receipt/payment/address/totals/submit surfaces.
+- If `doctor` reports `derived.scope.mode = "partial"`, build the pages listed in `derived.scope.built_pages` from their prepared source. A page in `derived.scope.out_of_scope_pages` whose assembly-report decision `dec_page_scope_<page>` carries `template_stock: true` is template stock: materialise it from the locked family's own page for that role (`decision.template_family`; the `next build` prompt lists them), copied atomically with its dependent `_includes/`, `_layouts/`, and assets, and wired from CampaignSpec — a pre-checkout `select` step first, because it seeds the cart the runtime pages read. Do not look for prepared source HTML for it, and do not attest a screenshot of it as a design source. Once its built HTML exists at the page's route, doctor lists it among the previewable routes and lifts the runtime-QA block for it. An out-of-scope page without that marker stays unbuilt: carry its `skip_reason` into the assembly report and label the preview as route/visual-testable rather than full-funnel launch-ready.
+- For `landing` and `presell` pages, prefer the prepared source HTML when `source_html.pages[].path` points at a real standalone page. Preserve the design/content through a passthrough page-kit layout, inject the SDK loader/config as needed, and repoint CTAs into the CampaignSpec flow. Treat `source_html.pages[].path` and `context.page_map[].source_path` as source provenance. Treat `source_html.pages[].page_kit`, `context.page_map[].page_kit`, and `context.page_map[].output_path` as the Page Kit target file, route, CPK `page_type`, and frontmatter projection.
+- Prepared source HTML means page-kit-ready markup, not a wholesale Liquid rewrite. Standalone AI/exported HTML should keep page-owned body markup, remove document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only where page-kit needs campaign-rooted links/assets/includes.
+- For `checkout`, `upsell`, `downsell`, and `receipt` pages, treat the selected starter-template commerce surface as the SDK contract reference: preserve required `data-next-*` controls, hidden fields, payment/address/totals/submit wiring, and `next_dont_touch` regions. The surrounding HTML wrapper, page composition, imagery, copy hierarchy, and brand layer are campaign/source-owned. Do not carry starter visual chrome forward when prepared source design should own that surface.
+- Read `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. If a fresh `brand-theme.css` artifact exists, copy it into the campaign asset tree and load it after `next-core.css` on checkout, upsell, downsell, and receipt pages. If policy is `inspect_only`, either run `campaigns-os theme generate` or record an explicit skipped reason before applying a new brand layer.
+- Generated brand-theme v0 is root-variable-only. It may skin commerce pages through next-core custom properties, but it is not permission to edit SDK-owned selectors, package controls, payment fields, totals, submit controls, receipt templates, route meta tags, or SDK JavaScript.
+- Payment, express checkout, bundle selectors, and order bumps must start from the selected family's canonical component DOM/classes, not from raw custom/source HTML with `data-next-*` added afterward. For payment specifically, preserve the family payment-method wrapper, hosted field classes, and iframe geometry assumptions (for example `input-flds spreedly-field` in shop-style templates). Skin these components with campaign tokens; do not rebuild Spreedly/card fields as arbitrary divs.
+- When a checkout page declares `exit_intent.enabled`, wire the popup as an offer application surface: use `offer_ref_id`/`offer_code` from CampaignSpec, apply the code through the SDK/API coupon/voucher path, and render applied-state copy with SDK conditionals such as `cart.hasCoupon("FREESHIP")`.
+- When a checkout page declares `promo_code_input.enabled`, wire the template/source promo-code surface to accept the mapped CampaignSpec `offer_code`, submit it through SDK/API, and let SDK/API reprice selectors, totals, and discount rows.
+- When the selected family includes or copies a default exit-pop but CampaignSpec has no checkout `exit_intent` or `promo_code_input`, strip the widget during build; do not leave blank modals or default coupon-code controls in output.
+- Do not hardcode exit-pop or promo-code discount math, static post-discount prices, or campaign-specific JavaScript that mutates pricing display outside SDK-owned display regions.
+- If setup/build needs starter-template files, copy the template family atomically with its dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; copying only checkout/receipt pages is incomplete.
+- Resolve SDK routing meta tags to deployed campaign-root paths, not spec literals. For example, `next-success-url: upsell/` in the spec should become `/<public_route_slug>/upsell/` in built HTML.
+- If an order bump package comes from `packages.prepurchase_*` and is not one of the main `bundles[]`, default `package_sync=false` and `show_line_total_price=false` unless the CampaignSpec explicitly says the add-on quantity must sync with the main bundle.
+- For two-step package-selection-before-checkout flows, use the selector page as the pre-checkout step, encode the selected cart with `forcePackageId`, preserve attribution/tracking params, and strip `forcePackageId` from the visible checkout URL after SDK initialization.
+- Record intentional drops from source HTML in the assembly report, especially payment/provider changes such as "PayPal removed because CampaignSpec available_payment_methods excludes it." Polish must inherit these decisions.
+- Preserve any existing Build Context `theme` inspection state and Assembly Report `theme` application state. If build applies, skips, or invalidates generated theme CSS, update `report.theme` rather than leaving stale evidence.
+- After page-kit build, inspect rendered `_site` output: body exists, Campaign Cart runtime markers exist, `sdk_hints.meta_tags` rendered, route meta points at the campaign root, and copied funnel attribution/runtime baggage is gone.
+- For `shop-three-step`, shipping methods are dynamic through `window.next.getShippingMethods()`; do not add static Olympus-style `shipping_methods` frontmatter.
+- Run page-kit build and SDK/template lint available in the target repo.
+- Capture the machine-readable build summary as an artifact: `npx campaign-build --json > .campaign-runtime/page-kit-build-summary.json` (requires `next-campaign-page-kit` >= 0.1.4). Doctor's `built_output.build_summary` check verifies per-page build status and Page Kit shape warnings (`NESTED_NO_PERMALINK`, `DUPLICATE_OUTPUT`, `MISSING_FRONTMATTER`, `LAYOUT_NOT_FOUND`, `NO_CAMPAIGN`) from this artifact. If the installed page-kit predates `--json`, record that in the assembly report instead of skipping silently.
+- Update the assembly report with commands, evidence, warnings, blockers, and next owner. If a brand theme was applied, record `report.theme.status`, `css_path`, `commerce_pages`, `load_order=after-next-core`, evidence, and any first repair-loop defect.
+
+Build does not replace polish or QA. Hand off to `next-campaigns-polish` when the campaign is runnable.

package/skills/next-campaigns-os/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: next-campaigns-os
+version: 1.0.16
+description: Coordinate Campaigns OS lifecycle workflows from CampaignSpec, Build Packet, starter-template contracts, stage reports, deploy evidence, and QA proof depth.
+---
+
+# Campaigns OS
+
+Use this skill to orient a campaign build, run preflight, decide the next stage, and keep the lifecycle honest.
+
+## Public Lifecycle Boundary
+
+The public `campaigns-os` package owns portable workflow semantics: Build
+Packet generation, Build Context, Assembly Report validation, doctor/readiness
+decisions, public build/polish/QA guidance, and browser QA runner behavior.
+It also owns CampaignSpec validation through the public
+`@nextcommerce/campaigns-os/campaign-spec` subpath; Map Builder, the public
+doctor, and agency tooling should consume that same rule registry instead of
+vendoring or reimplementing spec rules.
+Internal orchestration may wrap this workflow for the Map Builder,
+issue-tracker projection, QA routing, dashboards, and promotion decisions,
+but those wrappers should not redefine the public contract.
+
+Workflow:
+
+1. Confirm the campaign was configured in Campaigns App and exported from Campaign Map Builder as current CampaignSpec JSON. Current authoring is v4.3+ while preserving the v4.2 `funnels[]` topology as the compatibility shape.
+2. Run `campaigns-os start` or `campaigns-os prepare-build` with a local CampaignSpec, prepared HTML/assets source, target page-kit repo, and explicit template family. The family must be certified (commerce catalog + brand contract; the CLI lists them on rejection) — an uncertified/custom family requires `--allow-uncertified-template "<reason>"` and forfeits deterministic assembly, residue QA, and pricing contracts. The entry point auto-opens the run session in the target repo; do not skip `campaigns-os run end` at the finish. If intake blocks with `DESIGN_SOURCE_PACKAGE_NOT_READY`, the source material carries no desktop/mobile screenshot proof: supply it through `pages[].screenshots[]` in `<source-root>/.campaigns-os/source-html-manifest.json` and follow "Clearing `DESIGN_SOURCE_PACKAGE_NOT_READY`" in `docs/design-source-package.md`, which also gives the recovery for the package a blocked run left behind.
+3. Brand-theme discovery runs in inspect-only mode by default and records `context.theme`. When it proves a brand theme is generatable and the campaign ships commerce pages, the theme gate BLOCKS polish/deploy/QA until the brand layer is applied after `next-core.css` or explicitly waived (`campaigns-os theme waive --packet <p> --reason "<why>" --waived-by "<named human>"`, the same named-human rule as `checkpoint waive`). Run `campaigns-os theme generate` and apply it during build; do not defer the decision.
+4. Run `campaigns-os doctor --packet <packet>`.
+5. Resolve the registered **Page Kit** checkpoints before runtime work. The CampaignSpec is the authority for the target's `_data/campaigns.json` entry, and the reconcile is a command, not a hand edit: `campaigns-os page-kit sync --packet <p>` (add `--dry-run` to see the field-by-field diff first) writes the spec's `campaign.store_*` fields into the entry for the packet's route and seeds the released SDK pin (`global_config.sdk_version` is canonical, `runtime.sdk_version` an accepted alias) while the entry is still in scaffold state or behind the spec; it never moves a configured campaign's pin backwards (on an existing campaign the repo pin moves first and the Map is stale: run `campaigns-os spec derive --packet <p>`, which writes the repo pin — and the page routes and analytics ids the repo carries — into the local CampaignSpec with a field-by-field diff, and add `--write-map` to record the pin in the saved Map's Build hints too (it reads the Map back and moves only the pin, forward or not at all; a Map pin ahead of the repo is refused as a warning), or re-save the Map by hand; a hand edit of the spec is never the answer for a derived field; the `campaign.store_*` fields are derived from the store itself with `spec derive --packet <p> --from-store <subdomain>`, the Admin API read token in `<SUBDOMAIN>_ADMIN_TOKEN`, and a field the store cannot state is reported and left as it is, never emptied), and touches nothing else; doctor and `next` print it as the gate's `repair_target` action, and after it `page_kit.store_profile` and `page_kit.sdk_version` pass without a waiver. Starter demo residue (a demo storefront URL or phone) in that entry is never waivable and must be replaced this way. A `PARTIAL` status means a field could not be made spec-authoritative (a spec value of the wrong type or shape, the demo value itself in the spec, demo residue in a field the spec does not carry, a conflicting or non-released pin, or a gate under an active waiver); the warnings name the spec field to fix, then sync again. Missing/malformed Store Profile or SDK evidence, invalid types or semantic versions, and conflicting dual SDK declarations are not waivable. An exact valid mismatch may be accepted with named-human attribution and a bound: `campaigns-os checkpoint waive --packet <p> --gate <page_kit.store_profile|page_kit.sdk_version> --reason "<why>" --waived-by "<named human>" --review-condition "<trigger>"` (or `--expires-at <future ISO timestamp>`). The package-owned hidden eager-media checkpoint is produced and resolved during Polish in step 9.
+6. On any doctor run that sees built output, resolve `built_output.upsell_selector_scope`. A `data-next-bundle-selector` on a page whose funnel role is `upsell` or `downsell` writes to the shopper's LIVE CART unless it carries `data-next-upsell-context`; loading the page then adds that package with no click, and it is charged at the next checkout without appearing in that checkout's rendered order summary. Being hidden does not help — the write happens at init. Fix it by adding `data-next-upsell-context` to the named selector, or by deleting a selector that exists only to display a price. This gate runs on EVERY doctor invocation, not only after assembly, because the defect it was written for was introduced by a later review round. If a cart-scoped selector on a post-purchase page is genuinely intended, record it: `campaigns-os checkpoint waive --packet <p> --gate built_output.upsell_selector_scope --reason "<why>" --waived-by "<named human>" --review-condition "<trigger>"`. On the same runs, resolve `built_output.campaign_identity`: every page must name the same campaign — one API key (`next-api-key` meta or the `config.js` / `window.nextConfig` `apiKey`), one `next-funnel`, and any `setAttribution({ funnel })` call agreeing with the tag of the page that makes it. A page copied from another funnel that still carries the other campaign's key, tag, or call binds and renders without complaint and puts the order on the wrong campaign. Each error names the two files and the two values; make the one-line edit it describes. Not waivable — there is no `checkpoint waive` lane for it. Parked `-backup-` / `-old-` copies are skipped and listed, not scanned. Also resolve `built_output.sdk_markup`: its blockers (`SWAP_WITH_ADD_TO_CART`, `CHECKOUT_NOT_FORM`, `WRONG_FIELD_NAME`, `MISSING_SELECTOR_ID_MATCH`) are markup the SDK binds and then silently no-ops or double-writes on — fix the markup the message names (it gives the SDK spelling for a wrong field name); its warnings (`DOUBLE_SELECTED`, `TEMPLATE_DOUBLE_BRACE`) are advisory. Neither is waivable. A `data-next-*` name the SDK does not read shows up as one advisory line naming the attribute index version, not a warning.
+7. If doctor's `next` block says `doctor-blocked` or `prepare-build` (it names the same stage `campaigns-os next` would), stop and resolve the named blockers.
+8. If doctor returns `build`, hand off with `campaigns-os next build --packet <packet>` and follow `next-campaigns-build`'s recommended **build → independent review → repair → verification** loop.
+9. After build, require polish and a preview deploy before QA. During Polish,
+   install the package-owned browser once with `npm run qa:install-browser`,
+   serve the current build, and run `campaigns-os polish capture --packet <p> --base-url <served-build-url>` before recording a terminal Polish status.
+   The package-owned producer attaches `visual_review.page_load`; never
+   hand-author it. Nonwaivable incomplete evidence blocks. A complete hidden
+   eager-media finding may receive an exact bound decision through
+   `campaigns-os checkpoint waive --packet <p> --gate polish.hidden_eager_media ...`.
+   Doctor/next report `ready_with_waivers`; QA
+   retains each attributed exception as `ready_with_exceptions`, and one
+   exception never suppresses another blocker.
+10. Run the package-owned proof path in sequence: ensure `npm run qa:install-browser` has completed, run `campaigns-os qa resolve --packet <packet>`, then `campaigns-os qa run --packet <packet> --base-url <url> --browser --test-order common`.
+11. Treat typed-card proof coverage as the control. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed. `common` runs checkout, first-offer accept and decline, and a deduplicated shortest real receipt path when that adds coverage (at most four orders). `full` walks every actual terminal path in the selected checkout topology; cycles, missing routes, and reachable nonterminals block exhaustive proof before browser launch. The accidental-flood cap remains `6`, and an overflow names the exact explicit `--max-test-orders` raise. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins still need SDK origin allowlist confirmation.
+12. Discuss launch only from recorded build, polish, deploy, browser QA, and test-order evidence, or from explicit blockers.
+
+## Session Intake
+
+When a Campaigns OS session starts, classify the starting path before handing
+off to setup, build, polish, QA, or promotion. The operator should separate:
+
+- Intent: build, partial page update, existing campaign update, QA only, repair from verdict, design/source assembly, or promotion.
+- Source truth: CampaignSpec/Map Builder export, Figma/design file, prepared HTML, existing campaign repo, deployed URL, or target deployment system.
+- Runtime truth: Build Packet, Build Context, Assembly Report, doctor JSON, tested URL, API key source, and SDK origin allowlist state (localhost is already a Development domain; non-localhost origins still need confirmation).
+- Change policy: what may change and what must be preserved, especially checkout, offer logic, routes, legal copy, and live campaign behavior.
+- Proof depth: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
+
+Return a compact brief before acting:
+
+```text
+Mode:
+Intent:
+Source truth:
+Runtime truth:
+Change policy:
+Proof depth:
+Next skill/command:
+Missing inputs:
+```
+
+Use `references/session-intake.md` when the mode, allowed changes, or proof
+depth is unclear. Ask only for fields needed by the selected starting path; a
+QA-only session should not require design files, and a partial landing update
+should not force full checkout/test-order depth unless commerce or routing can be
+affected.
+
+Rules:
+
+- This is contract-backed guidance and preflight, not full automated readiness.
+- Preserve CampaignSpec as the source of truth. Do not make CampaignSpec absorb source-export paths, target repo paths, template decisions, deploy status, or test-order depth; those belong in the Build Packet and stage reports.
+- Treat `spec.validation` doctor findings as public CampaignSpec rule findings. When JSON output carries `detail.ruleId`, `detail.path`, and `detail.data`, use those fields for UI/repair routing instead of parsing message text.
+- CampaignSpec/API own live commerce values.
+- Treat checkout `exit_intent` and `promo_code_input` as optional CampaignSpec launch contracts. If present, build must wire the mapped offer surface and QA must exercise the accept/apply path.
+- Keep offer application surfaces out of pricing logic: they validate/apply codes through SDK/API, while Campaigns API/SDK own repricing, totals, and discount rows.
+- Starter-template `agentContract` owns reusable commerce structure and protected SDK surfaces.
+- Promoted starter-template families must also have `contracts/template-brand-contract.<family>.v0.json` with family inventory, brand/residue, pricing, and exit-pop rules. Missing family contracts are gates, not advisory gaps.
+- Designed source owns visual composition and page-level content.
+- Brand-theme evidence is workflow-order neutral. Do not assume a Figma export came first; consume `context.theme` and `.campaign-runtime/theme/theme-report.json` when present. A truly missing/ungeneratable theme stays a warning, but a generatable-and-unapplied theme on a commerce-page campaign is a gate: apply it or waive it explicitly before polish/deploy/QA.
+- Follow `campaigns-os next` literally. Every `next` response carries its applicable Store Profile, SDK, hidden eager-media, theme, and broad Polish gates plus `next_actions` with exact commands — execute those instead of improvising. With an active run session, pipeline-advancing commands that don't match the last `next` recommendation are recorded to `.campaign-runtime/agent-deviations.jsonl`; declare an intentional detour with `--deviation-reason "<why>"`.
+- Close the loop: when `next` reports `done` (or QA has published its verdict and the PR is up), finish with `campaigns-os run end` so the Run Record is assembled and the run session clears. `campaigns-os run status` shows incomplete stages and the exact next command at any point.
+- Do not copy demo refs or unsupported optional surfaces into the target campaign.
+- Use SDK conditionals such as `cart.hasCoupon("CODE")` for code-specific presentation; do not mutate visible prices from campaign-specific JavaScript.
+- Build Packet, Build Context, and Assembly Report paths should be repo-relative when possible so handoff artifacts can be committed without machine-local absolute paths.
+- Preserve Build Context `theme` inspection state and Assembly Report `theme` application state when present; they are public v0 contract fields and should not be dropped by wrappers, setup reruns, or repair passes.
+- Store Profile fields are operator-entered storefront/legal metadata for page-kit `campaigns.json`; they do not come from the Campaigns API and should be collected in the CampaignSpec before build.
+- Treat `campaigns-os checkpoint waive` as a staged generic registry, not a universal waiver command. This release registers Store Profile, the Page Kit SDK pin, `polish.hidden_eager_media`, and `built_output.upsell_selector_scope`. The broad Polish Source Freshness gate remains on its existing artifact handling, and theme/QA keep their existing `theme waive` / `qa waive` lanes until those gates are explicitly registered. A checkpoint waiver needs a named human, non-empty reason, and at least one future expiry or non-empty review condition; a waiver remains visible, applies only to its exact checkpoint state, and never turns the checkpoint into a clean pass. Hidden eager-media measurement completeness is never waivable.
+- Keep the lifecycle in a tight sequence. Pause only for missing inputs, doctor blockers, deploy blockers, out-of-scope runtime pages, or merchant-specific uncertainty.
+- `campaigns-os standardize` audits the campaign ecosystem read-only: it recognizes Page Kit roots and non-Page-Kit Campaign Cart applications (Vite/React/Express apps, static HTML funnels) via portable evidence, classifies each root (`implementation.kind`), validates checkout field bindings against the Campaign Cart field contract, and evaluates loader versions against the SDK support policy contract. Findings carry `confidence` (`static_contract`, `static_inference`, `runtime_proof_required`); treat `runtime_proof_required` findings as missing proof, never as confirmed defects, and route them to browser QA rather than static repair.
+- Launch readiness is separate from Campaigns OS proof. Surface production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration as real-shopper readiness items, not Campaigns OS build blockers.
+- Browser QA and test-order proof are owned by Campaigns OS through Playwright. Do not route the core QA path through external browser skills or hand-built backend orders.

package/skills/next-campaigns-os/references/session-intake.md

@@ -0,0 +1,160 @@
+# Campaigns OS Session Intake
+
+Use this reference when a Campaigns OS session begins without an already-clear
+Build Packet, QA verdict, or promotion task. The goal is to make the operator
+separate intent, source truth, runtime truth, change policy, and proof policy.
+
+## Intake Envelope
+
+Return this compact brief before running a specialist skill or command:
+
+```text
+Mode:
+Intent:
+Source truth:
+Runtime truth:
+Change policy:
+Proof policy:
+Next skill/command:
+Missing inputs:
+```
+
+Definitions:
+
+- Intent: what the user wants done, such as build, update, QA, repair, or promote.
+- Source truth: CampaignSpec/Map Builder export, Figma/design file, prepared HTML, existing campaign, target repo, or deployed URL.
+- Runtime truth: Build Packet, Build Context, Assembly Report, optional `context.theme` / `.campaign-runtime/theme/theme-report.json`, doctor JSON, repo state, tested URL, Campaigns API key source, SDK origin state (localhost is a Development domain; non-localhost origins need allowlist confirmation), and test-order depth choice.
+- Change policy: what may change and what must be preserved, especially checkout, offer logic, live campaign routes, and legal/merchant copy.
+- Proof depth: visual preview, doctor, browser QA, QA portal/local verdict policy, typed-card test-order depth, market coverage, and repair routing.
+
+Ask only for the fields needed by the selected mode. Do not force a full-funnel
+build prompt when the user only needs QA, a partial page update, or repair from
+an existing verdict.
+
+## Starting Paths
+
+### Full Campaign Build
+
+Use when the user has CampaignSpec plus source/design material and wants an
+end-to-end campaign.
+
+Required before build:
+
+- Map ID or CampaignSpec path/URL.
+- Public route slug and target repo/output directory.
+- Source type and source files: Figma, exported HTML, prepared HTML, existing campaign, or other.
+- Pages in scope and any pages to preserve.
+- Template family if known; otherwise infer and ask before locking commerce surfaces.
+- Proof depth, including browser QA and the typed-card test-order depth to run.
+
+Route to Build Packet preparation, doctor, setup when scaffold is missing,
+build, polish, then QA.
+
+### Design Or Source Assembly
+
+Use when design/source material exists but repo/tooling context is incomplete.
+
+Collect:
+
+- Source authority: Figma link/file, exported HTML, AI-generated HTML, existing campaign, or assets folder.
+- Intended page map and any commerce surfaces represented in the source.
+- CampaignSpec or Map Builder status, if available.
+- Target implementation uncertainty: repo, template family, public route, deployment target.
+
+Output a Build Packet or source-adapter findings. Ask before changing checkout,
+offer, upsell, or receipt behavior when template family or runtime contracts are
+unknown.
+
+### Partial Page Build
+
+Use when only landing, presell, checkout skin, upsell, downsell, receipt, or a
+specific component is in scope.
+
+Collect:
+
+- Page(s) in scope and pages explicitly out of scope.
+- Whether commerce logic, SDK attributes, routing, checkout submit behavior, or offer logic may change.
+- Source authority for the selected page(s).
+- Proof needed for affected surfaces.
+
+Route to build or polish for scoped changes, then QA only the affected page
+paths plus downstream runtime paths that may have been affected.
+
+### Existing Campaign Update
+
+Use when a deployed or repo-backed campaign already exists.
+
+Collect:
+
+- Existing repo/branch and preview/production URL.
+- Current Build Packet, pass log, Assembly Report, or doctor output if present.
+- Exact allowed changes and preservation rules.
+- Whether live offer logic, checkout, routes, tracking, or legal copy may change.
+
+Run doctor when a packet exists. If no packet exists, reconstruct enough runtime
+truth before editing. Do not infer permission to alter commerce logic from a
+visual update request.
+
+### QA Only
+
+Use when the user wants evidence on a deployed campaign and no source edit.
+
+Collect:
+
+- Map ID and deployed base URL.
+- Build Packet path if local; otherwise enough info to resolve topology.
+- Whether browser QA should run.
+- Whether verdict should use the default QA portal publish path or stay local-only.
+- Typed-card test-order depth (`common`/explicit/`full`).
+
+Route to QA. Do not patch campaign code from the QA-only path.
+
+### Repair From QA Verdict
+
+Use when a posted/local verdict or QA dashboard run exists.
+
+Collect:
+
+- Verdict path or dashboard URL/run ID.
+- Build Packet and Assembly Report paths when local.
+- Whether repair may edit source, and which surfaces are protected.
+- The typed-card test-order depth to re-run for the retest.
+
+The public verdict is the source of repair truth. Route repairable items to
+specialist skills, ask only the needed clarification questions, and keep
+typed-card order failures as manual/specialist handoffs unless the owner and
+the test-order depth to re-run are clear.
+
+### Promotion Or Experiment
+
+Use when the user wants to interpret performance evidence or promote a funnel.
+
+Collect:
+
+- CampaignSpec path and funnel IDs.
+- Performance by Page evidence or date range.
+- Winner, confidence notes, and any exceptions.
+- Deployment/routing target and whether config changes should become a PR.
+
+Route through decision creation, promotion, and generated routing config. Do not
+hand-edit deployed routing config as the primary promotion path.
+
+## Test-Order Proof Policy
+
+Treat test orders as cheap, repeatable proof: global test cards bypass the
+gateway and create no transactions, so they need no permission or approval. The
+only real choice is coverage. Record:
+
+- Coverage: `common` (checkout, first-offer accept/decline, and a deduplicated shortest real receipt path when needed; at most four orders), `off`, `checkout`, `decline`, `accept`, `both`, `full`, or explicit paths such as `decline-decline-accept`.
+- Cart matrix: base cart, base plus bump, specific package refs/quantities.
+- SDK origin state (so the SDK loads): localhost Development domain, non-localhost allowlisted, or unknown — separate from test-order permission.
+- Max order cap: the accidental-flood guard; raise `--max-test-orders` for exhaustive proof.
+- Market coverage: default market only or at least one non-default country/currency path.
+- Customer email: reuse one inbox via `--test-email`/`CAMPAIGNS_OS_QA_TEST_EMAIL` (the customer record is not deletable).
+
+`--test-order common` covers checkout, the first-offer actions, and a shortest
+real receipt path when that adds coverage. Use `full` for every actual terminal
+path in the selected checkout topology. Cycles, missing routes, and reachable
+nonterminals block exhaustive proof before browser launch. The default
+`--max-test-orders 6` cap remains in place; an overflow names the exact explicit
+raise.

package/skills/next-campaigns-os-setup/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: next-campaigns-os-setup
+version: 2.0.0
+description: Bootstrap or prepare a target page-kit campaign repo from a doctor-cleared Campaigns OS Build Packet before full build wiring. Formerly installed as next-campaigns-setup; renamed 2026-08 to stop colliding with the published NextCommerceCo/skills scaffolder of that name.
+---
+
+# Next Campaigns OS Setup
+
+Use this skill when the Build Packet doctor says setup is required before assembly.
+
+Responsibilities:
+
+- Confirm the target repo exists and has or can install `next-campaign-page-kit`.
+- Create the campaign output directory only through page-kit-compatible structure.
+- When copying a selected starter template family, copy the family as an atomic page-kit slice: pages plus required `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`. Do not copy only `checkout.html` and `receipt.html`.
+- Public families resolve from the default `public` starter-templates source. A **private** family (one whose source lives in an access-controlled repo, e.g. a certified family not present in the public picker) is scaffolded via page-kit's template-source mechanism (`next-campaign-page-kit` >= 0.2.0): add a named source to the target repo's `_data/template-sources.json` (a `git` source with the SSH `url` + optional `ref`, or a `local` source `path`), then `campaign-init --source <name> --template <slug>`. The source repo must expose a root `templates.json` catalog + `src/<slug>/` tree. page-kit holds no family→repo mapping; the source config lives in the (private) consuming repo, and this skill (plus the family's certified contract) is where that source is known.
+- Install or reference `.campaign-runtime/agent-context` without overwriting existing root agent files.
+- Record setup status in both `.campaign-runtime/build-context.json` (`scaffold.required`, `scaffold.mode`, handoff fields) and `.campaign-runtime/assembly-report.json` (`stages.setup`).
+- Preserve existing Build Context `theme` inspection data and Assembly Report `theme` application data when setup is rerun against an existing campaign directory.
+- Hand off to `next-campaigns-build`.
+
+Do not wire checkout, upsell, receipt, payment, package, voucher, or shipping behavior in setup. Build owns that work after the template contract is locked.