# Campaigns OS

Set up the campaign and its offers in the Campaigns App, then paste the start
prompt from campaigns.nextcommerce.com/start into your coding agent.

Campaigns OS is NEXT's system for building checkout campaigns from
proven patterns: the agent starts from a starter template, wires it to the
campaign's products and offers through a CampaignSpec, previews the runtime,
and runs QA (a test order on every planned path) before launch.

## Pages

- / — portal home: the start sentence, starter templates, pattern demos, tracking path
- /start/ — the one starting point. For people: set up the campaign and its offers in the Campaigns App, then open a coding agent in an empty folder and paste the start prompt, which points here. For agents: the steps under "For agents" below, also shown as the command checklist at /start/#for-agents
- /templates/ — catalog of the eight starter template families
- /templates/<family>/ — detail pages for all eight families (pages, quick start, SDK contract): apollo, apollo-mv-single-step, olympus, olympus-mv-single-step, olympus-mv-two-step, demeter, shop-single-step, shop-three-step
- /patterns/ — interactive pattern library (bundle selectors, order bumps, upsells, display attributes)
- /tracking/ — plain-language campaign tracking setup guide: choose one connection per tool, configure it in the workspace, and verify it with a test order

## Key resources

- Starter templates (source): https://github.com/NextCommerceCo/campaign-cart-starter-templates
- Live template previews: linked from each family page under https://campaigns.nextcommerce.com/templates/
- Public toolkit (CLI, schemas, CampaignSpec rules): https://github.com/NextCommerceCo/campaigns-os
- Workspace (optional: open a saved Map and copy its start prompt): https://campaign-map.nextcommerce.com
- Developer docs: https://developers.nextcommerce.com/docs/campaigns
- Campaign Cart SDK reference: https://cart-sdk.nextcommerce.com/latest/
- Campaign Cart SDK releases (versions and release notes): https://github.com/NextCommerceCo/campaign-cart/releases
- Template-adapter vendor keys: https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/_shared/analytics/README.md

## For agents

If a person pasted the /start/ prompt ("Set up a NEXT campaign build in this folder"),
these steps are your task. Work in the folder you were opened in.

1. Orient. Before installing or running anything, read the toolkit's
   `AGENTS.md` at the release:
   https://github.com/NextCommerceCo/campaigns-os/blob/v1.62.0/AGENTS.md — it is
   the orientation contract: what to read, in what order, and which paths you
   may depend on. Orientation is a declarative read of contracts, schemas, and
   the release ledger; do not run toolkit code to decide whether to trust the
   toolkit.
2. Ask the person for what you need: the store and the configured campaign
   (with its public Campaigns API key), the page HTML and images (or "use the
   starter template as-is"), and a brief naming the pages in order, each
   offer, the store name and support contact, and the policy page URLs. Never
   invent prices, offers, or policy text. Test orders land in the store as
   real orders (test card, no charge) that someone may have to cancel. Unless
   the person has already said test orders are fine, ask once now, with your
   other questions, so build and QA run through without stopping for it.
3. Set up the folder. No clone is needed: the toolkit is published to npm as
   `@nextcommerce/campaigns-os`, installed as an exact devDependency of the
   campaign folder (a page-kit project), and run with
   `npx --no-install campaigns-os …`. Commit package.json and
   package-lock.json so CI and the host install the same release.

   Claude Code (one step; it reports `restart_required`, so ask the person to
   restart Claude Code in this folder):

   ```
   npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.62.0 && npx --no-install campaigns-os tooling setup --target . --platform claude
   ```

   An existing campaign keeps its reviewed versions: `npm ci`, then only the
   `tooling setup` part. Details:
   https://github.com/NextCommerceCo/campaigns-os/blob/v1.62.0/docs/local-setup.md

   Codex, Cursor, and other agents (`tooling setup` is Claude-only; use
   `--platform agents` for Cursor and other agents that read shared skills).
   The context files land in `.campaign-runtime/agent-context/`; point the
   project's AGENTS.md or Cursor rules at the matching file. `install-skills`
   lists each SKILL.md it wrote under `Read now`: read those files in this
   session, because a running agent does not load skills installed after it
   started. Restart only if you cannot read them.

   ```
   npm init -y && npm install --save-exact next-campaign-page-kit@0.3.0 && npm install --save-dev --save-exact @nextcommerce/campaigns-os@1.62.0
   npx --no-install campaigns-os install-skills --platform codex
   npx --no-install campaigns-os install-agent-context --target .
   npx --no-install campaigns-os qa install-browser
   ```

4. Write `campaign-spec.json` from the brief, the HTML, and the campaign's
   real commerce data, following the local-spec entry:
   https://github.com/NextCommerceCo/campaigns-os/blob/v1.62.0/docs/build-packet.md
   Set `spec_identity.local_spec_id` once and keep it. Put the HTML and images
   in `source-html/`.
5. Start, then run `next` after every stage and do what it names, through a
   localhost build to a test order with a test card. `<family>` is a starter
   template family from /templates/. `start` sends its run record to NEXT's
   telemetry endpoint by default; `npx --no-install campaigns-os telemetry off`
   first keeps it local. Until a stage is recorded, re-run the full start line
   to redo intake. After that, `start` refuses to overwrite the recorded work:
   save a changed brief with `record brief` and a changed CampaignSpec with
   `record spec`, and `next` names the stage that is owed again.

   ```
   npx --no-install campaigns-os start --spec campaign-spec.json --source source-html --target . --template-family <family> --deploy-target local-serve
   npx --no-install campaigns-os next --packet ./campaign-runtime.build.json --json
   ```

From a saved Workspace plan instead (its Handoff prompt names the Map ID;
create `./source` even when every page uses the template as-is; QA for a
saved plan posts its verdict to the Map unless you pass `--no-post-verdict`,
except a run against a local address such as localhost, which keeps it local
unless you pass `--post-verdict` or run `qa publish` afterwards):

```
npx --no-install campaigns-os start --map-id <map-id> --target . --source ./source --template-family <family>
```

Every artifact (CampaignSpec, Build Packet, QA verdict) is machine-readable
JSON with versioned schemas. A local test order is not launch approval:
hosted preview and production release are separate steps the person approves.

## Conventions

- CampaignSpec: versioned JSON describing a campaign's packages, funnels,
  routes, and offers. Validated by the campaigns-os rule registry.
- Build Packet: the validated handoff artifact a campaign build produces.
- Starter template families are cloned atomically; the SDK owns data-next-*
  attributes on commerce surfaces.
- Each starter family's current Campaign Cart SDK and its last recorded
  verification are listed at /templates/; SDK versions and release notes are
  at https://github.com/NextCommerceCo/campaign-cart/releases. Campaign Cart's analytics
  runtime emits complete cart/checkout payloads and stamps campaign plus
  `ncsid` session identity on every provider event. RudderStack is a supported
  SDK provider when its JavaScript SDK snippet is present on campaign pages.
- Tracking intent lives in the CampaignSpec (`spec.analytics`); a saved Map
  sets it in the Workspace under Campaign settings > Tracking. Public
  guidance describes Google Tag Manager, built-in connections, and supported
  platform connections in plain language. Template-adapter vendors compile to
  `campaigns.json` keys; use one delivery path per vendor.