@nextcommerce/campaigns-os 1.33.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+@nextcommerce/campaigns-os
+Copyright 2026 Next Commerce Pte. Ltd.
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

package/README.md

@@ -0,0 +1,368 @@
+# Campaigns OS
+
+Campaigns OS is the developer toolkit for agent-assisted campaign builds on [Next Commerce](https://nextcommerce.com), a full-stack ecommerce platform for direct-response brands. A *campaign* is a short, conversion-focused funnel — landing page, checkout, optional upsells/downsells, receipt — wired to live products, price tiers, shipping, and payments.
+
+This toolkit gives campaign developers and AI coding tools a clear path for assembling one from prepared page files:
+
+1. Configure the campaign in the Next Commerce dashboard (Campaigns App).
+2. Create or review the Campaign Map in [Campaign Map Builder](https://campaign-map.nextcommerce.com).
+3. Export a local CampaignSpec JSON.
+4. Bring prepared HTML/CSS/assets for the campaign pages.
+5. Provide or generate a [Campaign Build Brief](./docs/campaign-build-brief.md) for merchandising/design presentation decisions.
+6. Create and doctor a Build Packet.
+7. Hand off to `next-campaigns-build`.
+8. Run build/lint, then install the Campaigns OS Playwright browser once with `campaigns-os qa install-browser`.
+9. Run `next-campaigns-polish`, serve the current build, and run the mandatory `campaigns-os polish capture` producer before marking Polish complete.
+10. Deploy a preview.
+11. Run `next-campaigns-qa` against the tested URL.
+12. Record launch blockers and follow-up work.
+
+The toolkit is contract-backed: starter templates describe which parts are reusable page structure, which parts are live commerce wiring, and which demo values must be replaced for a real campaign. That helps AI tools avoid common mistakes like carrying over sample package IDs, copying shipping options from the wrong template shape, or editing SDK-owned checkout surfaces as plain HTML.
+
+## Quick Start
+
+You do not need to clone this repository to use it. The toolkit is pinned as a
+devDependency of the campaign folder (a page-kit project) and runs through
+`npx campaigns-os …` from that folder — the pin is committed in `package.json`,
+so CI and the deploy host install the same commit. Requirements: Node
+`>=20.19.0` and npm 10 or 11 (Node 22 ships npm 10). Three steps, in this
+order:
+
+1. **Orient before you run anything.** Read
+   [`AGENTS.md`](AGENTS.md), `contracts/supported-surface.json`,
+   `contracts/release-ledger.json` and `CHANGELOG.md` on GitHub at one commit,
+   and keep that commit's sha. Orientation is a read of declarative data; it
+   never executes toolkit code.
+2. **Pin the toolkit and install its agent skills** from that same commit.
+3. **Start a build** from that same commit.
+
+```bash
+mkdir "<route>" && cd "<route>"
+npm init -y && npm i next-campaign-page-kit
+npx campaign-init --non-interactive --template <family> --slug "<route>" --name "<campaign name>"
+npm i -D "github:NextCommerceCo/campaigns-os#<sha>"
+npx campaigns-os tooling status --platform claude
+npx campaigns-os install-skills --platform claude
+mkdir -p source
+```
+
+The toolkit is also published to npm as `@nextcommerce/campaigns-os`, so the
+CLI can be installed once, globally, instead of pinned per campaign:
+
+```bash
+npm install -g @nextcommerce/campaigns-os
+campaigns-os tooling status --platform claude
+```
+
+A global install ships without a browser. Polish capture and QA need the
+Playwright Chromium: run `campaigns-os qa install-browser` once. Playwright
+itself is an optional dependency, installed by default; an install that
+omitted it (`--omit=optional`) is told exactly that by the commands that need
+it, and every other command runs without it.
+Releases are cut by pushing a `v<version>` tag that matches `package.json`
+and `surface_version` on a commit on `main`; `.github/workflows/publish.yml`
+runs the full check in an unprivileged job and publishes the verified tarball
+with provenance from a second, environment-gated job.
+
+For an existing page-kit campaign, skip the first three lines and `cd` into it
+(its `package.json` already declares `next-campaign-page-kit`). `#<sha>` is
+the commit you oriented on, so the code that runs is the code whose contracts
+you read; npm records the resolved commit in the folder's `package.json` and
+`package-lock.json`, which is how `tooling status` can print `Install mode:
+package install (node_modules), pinned at <version> @ <sha>`. The install runs
+the package's own build step (about 7 s). On a fresh profile that first
+`tooling status --platform claude` exits 2 with `ATTENTION_REQUIRED` and one
+action, the `install-skills` line — it is telling you the skills are not
+installed yet, not that the install failed; run it again after
+`install-skills` for `READY`. Without `--platform`, status checks every agent
+profile (Claude, Codex, shared) and stays at exit 2 until each is installed.
+`install-skills` writes `~/.claude/skills` (`--platform codex` writes
+`~/.codex/skills`), replacing same-name folders; restart the agent after.
+Prepared page HTML goes in `./source`, which must exist even when every page is
+template stock. To move to a newer commit, re-orient on it and run `npm i -D
+"github:NextCommerceCo/campaigns-os#<new-sha>"` again.
+
+> **Heads up — `start` turns on run telemetry, and remit is ON by default.**
+> The first `start` opens a run session in the target folder and, unless you
+> opt out, the session's Run Record is remitted to the Campaigns telemetry
+> endpoint with the packet's Campaigns API key. Opt out with
+> `npx campaigns-os telemetry off`, `CAMPAIGNS_OS_TELEMETRY=off`, or
+> `--no-remit` on the remitting command; capture stays local either way. The
+> full note — endpoint, payload, what `off` changes, and `--no-run-session` —
+> is in [docs/quickstart.md](docs/quickstart.md) above the first `start`; the
+> contract is [Run Telemetry](docs/workflow-findings-sidecar.md).
+
+```bash
+npx campaigns-os start --map-id <map-id> --target . --source ./source --template-family <family>
+npx campaigns-os next --packet ./campaign-runtime.build.json --json
+```
+
+`--map-id <id>` starts from a map saved in Campaign Map Builder (add
+`--proxy-base <origin>` when the map was saved on a non-production map store);
+`--spec <campaignspec.json>` starts from a local export instead. `--source` is
+always required: the folder of prepared HTML/CSS/assets for the pages you are
+building, with a source manifest that carries desktop and mobile screenshot
+proof for each designed page
+([Design Source Package](docs/design-source-package.md)). Pages that use the
+starter family's own design are declared, not omitted — see the template-stock
+note below.
+
+`start` ends by running doctor, and doctor's first verdict on a fresh target is
+normally `BLOCKED` with a list of what to supply — missing screenshot proof,
+demo values to replace, a scaffold to run. That list is the intake checklist,
+not a failed install. The demo values are the store profile and SDK pin
+`campaign-init` seeded into `_data/campaigns.json`; doctor prints the one
+command that replaces them from the CampaignSpec, `npx campaigns-os page-kit
+sync --packet campaign-runtime.build.json`, and after it both page-kit gates
+pass. The reverse write exists for a configured campaign: `npx campaigns-os
+spec derive --packet campaign-runtime.build.json` copies what the repo already
+states (the SDK pin, page routes, analytics ids) into the local CampaignSpec,
+and with `--write-map` records the pin in the saved Map's Build hints too, so
+a bump in the repo is one edit followed by a derive rather than a hand edit
+in two tools; with `--from-store <subdomain>` and the store's Admin API read
+token in the environment it derives the store profile from the store as well. Everything after `start` is agent-driven: after `start`
+and after every stage, run `next` and do what it prints — it names the skill
+and the exact commands for the next stage, already spelled `npx campaigns-os
+…` for this install, which is why `install-skills` comes first. The browser
+for polish capture and QA is a one-time `npx campaigns-os qa install-browser`,
+which installs the browser for the Playwright this toolkit bundles. A pin
+older than that command shows `npx playwright install chromium` instead; that
+is equivalent only when `npx playwright` resolves to the toolkit's Playwright
+(a campaign that depends on its own Playwright version gets that one's
+browser instead), so prefer `qa install-browser` on pins that have it.
+
+### Other ways to run it
+
+The pinned devDependency above is the primary path. To change the toolkit, use
+a checkout ([docs/quickstart.md](docs/quickstart.md)): every `npm run
+campaigns-os -- <command> …` example in this repository is that checkout form,
+and from a campaign folder the same command is `npx campaigns-os <command> …`
+with identical arguments (`npm run qa:install-browser` is the checkout's
+`qa install-browser`).
+
+From a checkout, the same first run uses the bundled example inputs:
+
+```bash
+npm install
+npm run campaigns-os -- tooling status
+npm run campaigns-os -- start \
+  --spec examples/campaignspec.v42.basic.json \
+  --source examples/source-html \
+  --target examples/target-page-kit \
+  --template-family olympus
+```
+
+If that first run stops at intake with `DESIGN_SOURCE_PACKAGE_NOT_READY`, the
+source material arrived without desktop/mobile screenshot proof. Supply it
+through `pages[].screenshots[]` in
+`<source-root>/.campaigns-os/source-html-manifest.json` — or in a manifest
+outside the source root named with `--design-manifest <path>`, when the source
+tree is not yours to write — and follow
+[Clearing `DESIGN_SOURCE_PACKAGE_NOT_READY`](docs/design-source-package.md#clearing-design_source_package_not_ready),
+which also gives the recovery sequence for the package a blocked run left behind.
+
+That path assumes the pages carry a standalone design of the merchant's. If they
+are template stock instead — no bespoke design, the starter family *is* the
+design — there is no screenshot to honestly supply. Declare those pages out of
+source scope (a manifest `skip_reason` entry, or CampaignSpec
+`build_scope.mode: "partial"`): intake records them as template stock, demands
+no design source for them, and the build stage materialises each from the
+locked family's own page. A family that publishes Template Reference proof
+(today `apollo`) covers them with `template_baseline`; every other family
+records an accepted Source Gap and intake lands at `ready_with_gaps`. See
+[Template-stock pages: the family decides](docs/design-source-package.md#template-stock-pages-the-family-decides).
+
+The command writes these target-repo artifacts:
+
+- `campaign-runtime.build.json`
+- `.campaign-runtime/build-context.json`
+- `.campaign-runtime/assembly-report.json`
+- `.campaign-runtime/doctor-output.json`
+- `.campaign-runtime/qa-verdict.json` (after QA)
+- `.campaign-runtime/agent-context/*`
+
+Validate the standardized CI/readback set with:
+
+```bash
+npm run campaigns-os -- bundle check --packet <page-kit-repo>/campaign-runtime.build.json --json
+```
+
+Use `--require-qa` when the campaign claims QA is complete. `status: conformant`
+means the sidecars agree with each other and the contract; it says nothing about
+whether doctor or QA passed. Read the warnings for that (a blocked doctor run
+emits `bundle.doctor_output.blocked`, a blocked QA verdict
+`bundle.qa_verdict.blocked`). See
+[Migration sidecar bundle v0](docs/migration-sidecar-bundle.md).
+
+Then ask your AI tool to continue from the emitted handoff. Fresh target repos usually start with `next-campaigns-os-setup`; existing campaign directories can move directly to `next-campaigns-build`.
+
+## Source Files
+
+The current source adapter is `html_funnel`: bring prepared HTML/CSS/assets for the campaign pages, plus a local exported CampaignSpec from Campaign Map Builder.
+
+For raw AI-generated or exported static HTML, "prepared" means page-kit-ready
+source, not a browser document dropped in unchanged and not a wholesale Liquid
+rewrite. Page Kit source is HTML with YAML frontmatter and optional Liquid
+helpers. Convert standalone HTML into the target page format first: remove outer
+`<html>`, `<head>`, and `<body>` wrappers, add page frontmatter, move shared
+CSS/assets into the campaign asset tree when useful, root links/assets with
+`campaign_link` and `campaign_asset` when needed, and keep landing/presell
+design markup separate from SDK-owned commerce controls.
+
+## Important Commands
+
+```bash
+npm run campaigns-os -- tooling status
+npm run campaigns-os -- install-skills --dry-run
+npm run campaigns-os -- install-skills --platform codex --dry-run
+npm run campaigns-os -- qa install-browser
+npm run skills -- status
+npm run campaigns-os -- prepare-build --spec <spec.json> --source <html-dir> --target <page-kit-repo> --template-family <family> --brief <campaign-build-brief.yaml>
+npm run campaigns-os -- doctor --packet <page-kit-repo>/campaign-runtime.build.json
+npm run campaigns-os -- standardize --target <page-kit-repo-or-cpk-repo> --json
+npm run campaigns-os -- theme inspect --packet <page-kit-repo>/campaign-runtime.build.json --json
+npm run campaigns-os -- theme generate --packet <page-kit-repo>/campaign-runtime.build.json --json
+npm run campaigns-os -- next setup --packet <page-kit-repo>/campaign-runtime.build.json
+npm run campaigns-os -- next build --packet <page-kit-repo>/campaign-runtime.build.json
+npm run qa:install-browser
+npm run campaigns-os -- next polish --packet <packet.json> --report <assembly-report.json>
+npm run campaigns-os -- polish capture --packet <packet.json> --base-url <served-current-build-url>
+npm run campaigns-os -- next qa --packet <packet.json> --report <assembly-report.json>
+npm run campaigns-os -- qa resolve --packet <packet.json>
+npm run campaigns-os -- qa run --packet <packet.json> --base-url <preview-url> --browser --test-order common
+npm run smoke:polish-capture
+npm run campaigns-os -- findings add --stage overall --kind positive_signal --summary "..."
+npm run campaigns-os -- findings harvest --packet <packet.json>
+npm run campaigns-os -- findings export --summary
+```
+
+Doctor inspects without changing the retained Assembly Report or doctor sidecar.
+A stale local `_site` still fails the current inspection; it does not rewrite
+the proof of an earlier delivered build. Use `doctor --packet <packet> --write`
+only when deliberately recording a new doctor stage. `--no-write` overrides
+`--write`. A custom `--doctor-out <path>` also requires `--write`; naming an
+output path alone does not create or refresh the file. Build/QA producer
+commands continue to record their own stages.
+Do not use `prepare-build --force` merely to refresh a catalog path: doctor
+already resolves the running toolkit's catalog, and force clears stage evidence.
+
+
+`qa run` automatically checks contract-governed authored price, recurring
+cadence, and voucher claims against fresh `/api/price-preview` results for
+commercial pages. It needs no private repo import or extra catalog flag; proven
+mismatches are warn-severity pricing assertions in the normal verdict.
+
+Run `tooling status` before a build session. It names the install mode — a
+pinned package (`npx`, or a consumer's `node_modules`) or a git checkout — and
+checks that the package metadata, CLI entrypoint, and installed Campaigns OS
+skills agree. For a checkout it also reports branch, upstream, and ahead/behind;
+for a package install the pinned commit is the freshness answer, and there is
+no npm dist-tag to compare against. Neither mode makes agent skills current on
+its own: when skills are stale, run `install-skills --platform all` through the
+same prefix you ran `tooling status` with (the status output prints the exact
+command) and restart local agent sessions.
+
+Run `campaigns-os qa install-browser` (`npm run qa:install-browser` from a
+checkout) once after install/update and before mandatory `polish capture` or
+any QA command that uses `--browser` or `--test-order`. It installs the Chromium
+binary used by the package-owned Playwright flow;
+Campaigns OS proof should not depend on external browser skills. `polish
+capture` must run against the served current build before Polish becomes
+terminal, deploy begins, or QA starts.
+
+`npm run smoke:polish-capture` is an optional real-Chromium package smoke. It
+requires the installed browser and permission to open a loopback HTTP listener;
+it is intentionally excluded from `npm run check` and CI.
+
+## Template Contracts
+
+The starter-template catalog snapshot lives in `contracts/commerce-surface-catalog.json`.
+
+For each selected family, the agent must read:
+
+- `families[family].agentContract`
+- `sharedFrontmatterVocabulary`
+- `frontmatter.demoOnlyValues`
+- `frontmatter.replaceFromSpecOrApi`
+- `frontmatter.removeWhenUnsupported`
+
+Shipping is family-specific. Families whose contracts include `shipping_methods`
+or `shipping_method` must source those refs from CampaignSpec/API. Families that
+do not own explicit shipping frontmatter, including `shop-single-step`, should
+not receive copied Olympus-style `shipping_methods` blocks. Special case:
+`shop-three-step` uses dynamic shipping through `window.next.getShippingMethods()`.
+
+When bootstrapping a family such as `demeter`, copy the family as an atomic
+page-kit slice. Checkout/receipt pages depend on matching `_includes/`,
+`_layouts/`, `assets/css/`, and `assets/js/`; copying only individual page files
+is not a valid minimum file set.
+
+## Spec Validation
+
+`campaign-spec/` is the single, public source of truth for CampaignSpec
+validation: a `normalize` phase, a composable rule registry, and a fixture
+corpus. The `doctor` runs these rules during spec validation (emitted under the
+`spec.validation` code, complementary to its packet/build-aware spec checks), and
+any campaign authoring UI (such as a Map Builder bundle) can import the same
+registry — so a spec rule is authored once and reaches internal teams and
+third-party agencies alike. The rules are authored in TypeScript with no heavy
+dependencies and compiled to plain ESM (`npm run build:spec`, on `prepare`) and a
+stable subpath export `@nextcommerce/campaigns-os/campaign-spec`, so consumers run
+them on `engines.node` (>=20) with no type-stripping or build step of their own.
+See [`campaign-spec/README.md`](campaign-spec/README.md).
+
+## Docs
+
+- [Quickstart](docs/quickstart.md)
+- [Access Model](docs/access-model.md)
+- [Build Packet](docs/build-packet.md)
+- [Supported Surface](docs/supported-surface.md) — what downstream consumers may depend on, and the gate that enforces it
+- [Brand Theme Bridge](docs/brand-theme-bridge.md)
+- [CampaignSpec Authoring Examples](docs/campaignspec-authoring-examples.md)
+- [Campaigns OS Build Flow](docs/campaigns-os-build-flow.md)
+- [Campaign Standardization Report](docs/campaign-standardization-report.md)
+- [Entry Points](docs/entry-points.md) — five intake shapes (template-stock, Figma-driven, AI-generated, hand-authored, mixed) and which producer / manifest each one ships with
+- [Source Adapters](docs/source-adapters.md)
+- [Setup Profile Parity](docs/setup-profile-parity.md)
+- [Developer Evaluation](docs/developer-evaluation.md)
+- [QA And Test Orders](docs/qa-and-test-orders.md)
+- [Legacy Migration Contract](docs/legacy-migration.md) — pure inventory, preview-plan, receipt, Offer request/readback, and token-free evidence helpers for bounded SDK 0.3.x shadow migrations
+- [Template Family vs Figma-extraction vs Hybrid](docs/template-vs-extraction-decision.md) — when to mint a template family, when to extract a bespoke design, and when to do both
+- [Small PR Review Path](docs/small-pr-review-path.md)
+- [Run Telemetry](docs/workflow-findings-sidecar.md) — per-run Run Record (system signal + workflow findings) tagged by improvement surface; captured locally always, remitted to Next Commerce only with up-front opt-out consent
+- [Versioning](docs/versioning.md)
+
+## Status
+
+Developer preview. Build output still needs the normal proof gates: build/lint evidence, polish plus package-owned page-load capture against the served current build, preview deploy or local dev URL, Playwright browser QA, and typed-card test-order proof via `--test-order common` (global test cards bypass the gateway and create no transactions; no approval needed — depth is the only control). Localhost on any port is a Campaigns App Development domain, so SDK calls are allowed and analytics are suppressed there; non-localhost preview/production origins still need SDK origin allowlist confirmation.
+
+Launch readiness is separate from Campaigns OS proof. Before real shoppers see a campaign, confirm the production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+
+## Review standards
+
+Two rules reviewers apply to every patch, beyond the gates in
+`npm run check`:
+
+- **A guard test includes the failing case.** A test that passes against the
+  unfixed code guards nothing, so assert the behaviour that was broken and check
+  that it fails without the fix. Prefer assertions against the parsed module or
+  its output — call the function, read the value — over matching substrings of
+  source text, which passes on a comment and breaks on a rename.
+- **A `catch` branches on the condition it claims to handle.** Test
+  `error.code` (or whatever specific condition the comment justifies), handle
+  that case, and journal or rethrow everything else. A bare `catch` that
+  swallows every error turns a typo, a permission failure, and an expected
+  absence into the same silent success.
+
+## Issue tracking
+
+Work in this repo is tracked with GitHub Issues and coordinated on the
+org-level **[Operations](https://github.com/orgs/NextCommerceCo/projects/10)**
+Kanban board (Todo / In Progress / Done). New issues are added to the board
+automatically by the `add-to-project` workflow.
+
+Before starting work on an issue: check it is not assigned to someone else,
+assign yourself (`gh issue edit <n> --add-assignee @me`), and move the card to
+In Progress. Open PRs with `Closes #<n>`; when the issue closes on merge, the board's built-in "Item closed" automation moves the card to Done.
+Contributors have a `/next-board` skill that wraps these board operations
+(status, claim, move, create).

package/agents/claude/CLAUDE.md

@@ -0,0 +1,32 @@
+# Campaigns OS Agent Context
+
+You are helping assemble a NEXT campaign through Campaigns OS. Start from the Build Packet, not from private runtime source.
+
+Core rules:
+
+- Treat CampaignSpec as campaign intent and the Campaigns API as live commerce truth.
+- Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.
+- Treat the Build Packet as the handoff envelope: source adapter, target repo, template family, deploy target, SDK origin state, and QA proof depth.
+- Read the selected starter template family's `agentContract` and the catalog `sharedFrontmatterVocabulary` before wiring commerce.
+- Replace demo package, shipping, voucher, payment, tracking, footer, and SEO values from CampaignSpec/API.
+- Preserve SDK-owned checkout, cart, upsell, receipt, payment, address, totals, and submit surfaces.
+- Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes.
+- Preserve prepared source HTML for landing/presell pages when it is a real standalone design.
+- For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references: preserve required `data-next-*` controls and runtime wiring, but let the campaign/source own visual chrome, copy hierarchy, imagery, and brand layer.
+- If `.campaign-runtime/build-context.json` has `theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence. A generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
+- Copy a starter template family atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages.
+- Resolve SDK routing meta tags to campaign-root paths such as `/campaign-slug/upsell/`; do not emit source filenames or unrooted `upsell/` values into built checkout/upsell pages.
+- Default one-time `packages.prepurchase_*` order bumps to fixed quantity rather than syncing with the main bundle unless the spec explicitly requires sync.
+- Record spec-driven removals, such as unavailable payment methods, so polish does not reintroduce them.
+- Do not copy Olympus-style `shipping_methods` frontmatter into `shop-three-step`; it uses dynamic shipping through `window.next.getShippingMethods()`.
+- Run build/lint checks and record evidence in the assembly report, then hand off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
+- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve --packet campaign-runtime.build.json`, then run `campaigns-os qa run --packet campaign-runtime.build.json --base-url <url> --browser --test-order common`.
+- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the deployed checkout and rendered upsell controls. `common` runs the checkout baseline, 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. Coverage is the only control — there is no permission/approval step.
+- Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
+- Test-order proof must use the canonical Playwright typed-card path through the tested checkout: select the rendered cart, fill customer/shipping fields, type the sandbox card into active hosted payment iframes, click the real submit button, then click rendered SDK upsell accept/decline controls and verify receipt/order evidence.
+- Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
+- Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof. Those are diagnostic fallbacks only when explicitly requested.
+- Test orders are safe to fire any time: global test cards bypass the gateway, create no transactions, and need no merchant-specific routing confirmation. Localhost on any port is a Campaigns App Development domain for SDK QA with analytics suppressed; non-localhost preview/production origins must be allowlisted for the campaign API key so the SDK loads — that is about SDK initialization, not test-order permission.
+- Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+
+Current source adapter: prepared HTML/assets (`html_funnel`).

package/agents/codex/AGENTS.md

@@ -0,0 +1,27 @@
+# Campaigns OS Agent Context
+
+Use this context when working in a target campaign repo with Campaigns OS artifacts.
+
+- Read `campaign-runtime.build.json` first.
+- If `.campaign-runtime/build-context.json` or `.campaign-runtime/assembly-report.json` exists, read them before editing campaign files.
+- Run `campaigns-os doctor --packet campaign-runtime.build.json` before build work.
+- Treat CampaignSpec validation as owned by the public `@nextcommerce/campaigns-os/campaign-spec` rules surfaced through doctor `spec.validation` findings; use structured rule/path detail when available.
+- Respect the selected template family's `agentContract`.
+- Replace demo refs from CampaignSpec/API; do not preserve starter sample IDs.
+- Preserve Campaign Cart SDK-owned checkout, cart, upsell, receipt, payment, address, totals, and submit surfaces.
+- Prepared AI/exported HTML must be converted into page-kit-ready source first: keep page-owned body markup, strip document wrappers, add YAML frontmatter, move shared CSS/assets into the campaign structure, and use Liquid helpers only for page-kit links/assets/includes.
+- Preserve prepared source HTML for landing/presell pages when it is a real standalone design.
+- For checkout/upsell/downsell/receipt, use starter-template commerce surfaces as SDK contract references: preserve required `data-next-*` controls and runtime wiring, but let the campaign/source own visual chrome, copy hierarchy, imagery, and brand layer.
+- If `.campaign-runtime/build-context.json` has `theme` or `.campaign-runtime/theme/theme-report.json` exists, use it as optional brand-theme evidence. A generated `brand-theme.css` must load after `next-core.css`; missing or low-confidence theme is a warning/skipped reason, not permission to edit SDK-owned runtime surfaces.
+- Copy a starter template family atomically with dependent pages, `_includes/`, `_layouts/`, `assets/css/`, and `assets/js/`; do not copy only checkout/receipt pages.
+- Emit SDK routing meta tags as campaign-root paths such as `/campaign-slug/upsell/`.
+- Default one-time `packages.prepurchase_*` bumps to fixed quantity unless the CampaignSpec explicitly requires package sync.
+- Record spec-driven drops so polish does not reintroduce unsupported source elements.
+- For `shop-three-step`, keep dynamic shipping via `window.next.getShippingMethods()` and do not add Olympus-style static `shipping_methods` frontmatter.
+- Build hands off to polish. Before Polish becomes terminal or hands off to deploy/QA, install the package-owned Playwright browser with `npm run qa:install-browser`, serve the current build, and run `campaigns-os polish capture --packet campaign-runtime.build.json --base-url <served-current-build-url>`.
+- After that checkpoint clears, QA uses the Campaigns OS Node/npm runner: run `campaigns-os qa resolve`, then `campaigns-os qa run --browser --test-order common` against the tested URL.
+- Typed-card test-order proof uses `campaigns-os qa run --test-order <common|checkout|decline|accept|both|full|explicit-path>` through the tested checkout and rendered upsell controls. Global test cards bypass the gateway and create no transactions, so no permission/approval is needed — coverage is the only control. `common` runs the checkout baseline, 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. Do not use external browser skills, the SDK test-mode event, or hand-built backend API orders as launch proof.
+- Analytics correctness is two-phase: the campaign-root visit inventories declared providers/tags only, and the same canonical typed-card run proves Purchase only from the topology-recognized final receipt document after `--analytics-settle`. Missing/unrecognized receipts are manual-review warnings; recognized receipt no-signal and capture/settle errors block. Only the genuine recognized-receipt/no-signal failure is waivable; capture/settle errors are not. Checkout/upsell signals remain whole-journey parity evidence and cannot satisfy a silent receipt.
+- Do not use `next.getCartData().cartLines` as cart-populated proof; use typed-card order read-back, `cart:updated` payload `items` / `summary.lines`, and rendered bundle DOM evidence.
+- Campaigns OS proof is not merchant launch readiness. Before launch, confirm production storefront URL, live payment methods, shipping markets, legal/support URLs, analytics expectations, and merchant-side configuration.
+- This is not full automated readiness. QA remains a separate gate.