Skip to content

docs: make the campaign agent guide the starting point #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
next-devin wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: make the campaign agent guide the starting point #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ac48618
docs: make the campaign agent guide the starting point
next-devin Nov 2, 2026
3e1abeb
Align campaign guide terminology and template ordering
next-devin Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 32 additions & 32 deletions components/campaign-templates-grid.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,22 +16,6 @@ type CampaignTemplate = {
const BASE = 'https://nextcommerce-campaign-templates.netlify.app';

const TEMPLATES: CampaignTemplate[] = [
{
name: 'olympus',
slug: 'olympus',
description:
'Default pick. Single-step single-product checkout — lowest-friction conversion, used in most campaigns.',
link: `${BASE}/olympus/checkout/`,
page_links: [
{ label: 'Presell', url: `${BASE}/olympus/presell/` },
{ label: 'Landing', url: `${BASE}/olympus/landing/` },
{ label: 'Checkout', url: `${BASE}/olympus/checkout/` },
{ label: 'Upsell — stepper', url: `${BASE}/olympus/upsell-bundle-stepper/` },
{ label: 'pills', url: `${BASE}/olympus/upsell-bundle-tier-pills/` },
{ label: 'cards', url: `${BASE}/olympus/upsell-bundle-tier-cards/` },
{ label: 'Receipt', url: `${BASE}/olympus/receipt/` },
],
},
{
name: 'apollo',
slug: 'apollo',
Expand All @@ -48,22 +32,6 @@ const TEMPLATES: CampaignTemplate[] = [
{ label: 'Receipt', url: `${BASE}/apollo/receipt/` },
],
},
{
name: 'olympus-mv-single-step',
slug: 'olympus-mv-single-step',
description: 'Products with variants (size, flavor, color) on a single-step checkout.',
link: `${BASE}/olympus-mv-single-step/checkout/`,
page_links: [
{ label: 'Presell', url: `${BASE}/olympus-mv-single-step/presell/` },
{ label: 'Landing', url: `${BASE}/olympus-mv-single-step/landing/` },
{ label: 'Checkout', url: `${BASE}/olympus-mv-single-step/checkout/` },
{ label: 'Upsell — MV', url: `${BASE}/olympus-mv-single-step/upsell-mv/` },
{ label: 'Upsell — stepper', url: `${BASE}/olympus-mv-single-step/upsell-bundle-stepper/` },
{ label: 'pills', url: `${BASE}/olympus-mv-single-step/upsell-bundle-tier-pills/` },
{ label: 'cards', url: `${BASE}/olympus-mv-single-step/upsell-bundle-tier-cards/` },
{ label: 'Receipt', url: `${BASE}/olympus-mv-single-step/receipt/` },
],
},
{
name: 'apollo-mv-single-step',
slug: 'apollo-mv-single-step',
Expand All @@ -81,6 +49,38 @@ const TEMPLATES: CampaignTemplate[] = [
{ label: 'Receipt', url: `${BASE}/apollo-mv-single-step/receipt/` },
],
},
{
name: 'olympus',
slug: 'olympus',
description:
'Single-step checkout with the original Olympus tiered card layout. Use when it matches your existing design.',
link: `${BASE}/olympus/checkout/`,
page_links: [
{ label: 'Presell', url: `${BASE}/olympus/presell/` },
{ label: 'Landing', url: `${BASE}/olympus/landing/` },
{ label: 'Checkout', url: `${BASE}/olympus/checkout/` },
{ label: 'Upsell — stepper', url: `${BASE}/olympus/upsell-bundle-stepper/` },
{ label: 'pills', url: `${BASE}/olympus/upsell-bundle-tier-pills/` },
{ label: 'cards', url: `${BASE}/olympus/upsell-bundle-tier-cards/` },
{ label: 'Receipt', url: `${BASE}/olympus/receipt/` },
],
},
{
name: 'olympus-mv-single-step',
slug: 'olympus-mv-single-step',
description: 'Products with variants (size, flavor, color) on a single-step checkout.',
link: `${BASE}/olympus-mv-single-step/checkout/`,
page_links: [
{ label: 'Presell', url: `${BASE}/olympus-mv-single-step/presell/` },
{ label: 'Landing', url: `${BASE}/olympus-mv-single-step/landing/` },
{ label: 'Checkout', url: `${BASE}/olympus-mv-single-step/checkout/` },
{ label: 'Upsell — MV', url: `${BASE}/olympus-mv-single-step/upsell-mv/` },
{ label: 'Upsell — stepper', url: `${BASE}/olympus-mv-single-step/upsell-bundle-stepper/` },
{ label: 'pills', url: `${BASE}/olympus-mv-single-step/upsell-bundle-tier-pills/` },
{ label: 'cards', url: `${BASE}/olympus-mv-single-step/upsell-bundle-tier-cards/` },
{ label: 'Receipt', url: `${BASE}/olympus-mv-single-step/receipt/` },
],
},
{
name: 'olympus-mv-two-step',
slug: 'olympus-mv-two-step',
Expand Down
8 changes: 5 additions & 3 deletions content/agent-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!-- next-commerce-agent-setup version=3 date=2026-10-22 -->
<!-- next-commerce-agent-setup version=4 date=2026-11-02 -->

# Start or continue a NEXT campaign with an AI agent

Expand All @@ -25,6 +25,8 @@ Store access, repository publishing, deployment, test orders and analytics sends

These entries can join the same work at different points. Do not replay provisioning or scaffolding because a new session starts.

The optional [Workspace](https://campaign-map.nextcommerce.com/) is a visual planning tool. A Map is the campaign plan saved there; its Handoff provides the prompt for continuing with an agent.

@kilo-code-bot kilo-code-bot Bot Nov 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: The Workspace/Handoff continuation is not reconciled with the entry-point table directly above it

Adding "its Handoff provides the prompt for continuing with an agent" here creates a second, unranked way to resume a saved Map. The table row four lines up already routes that exact artifact elsewhere:

| Local CampaignSpec, saved Map or Build Packet | Identify the selected campaign and read existing intent/status | The Campaigns OS continuation command for that artifact |

and content/agent-setup.md:85 reinforces it: "use the installed Campaigns OS agent entry to choose local-spec or saved-Map intake; its --help lists start for intake and next for continuation."

An agent reading this file now has three mechanisms of unequal authority for the same artifact — the table's Campaigns OS continuation command, line 85's next command, and this new Handoff prompt — with no guidance on which applies when. Consider stating the precedence (for example, that the Handoff prompt is what a human pastes to begin a new session, while campaigns-os next continues an artifact in place).

Minor placement note: the paragraph currently sits after "These entries can join the same work at different points. Do not replay provisioning or scaffolding because a new session starts.", which closes the section. Moving it above that sentence, or into its own short subsection, would keep the definition with the entry points it describes.


## From a source URL to a proposal

Read public HTML or user-provided source without submitting forms or using cart or checkout endpoints. Record source URLs and capture dates. Describe the observed products, variants, prices and currency, offer wording, page structure and navigation; mark checkout rules, shipping, subscriptions and post-purchase behavior unknown when the source does not establish them. A displayed price is not proof of a NEXT package or offer.
Expand All @@ -41,7 +43,7 @@ npx campaigns-os standardize --target /path/to/existing-campaign --no-doctor --j

The report inspects source without modifying the target and does not migrate the project, prove checkout or certify a launch. If the application is not recognized, record that and inspect its own integration rather than changing frameworks to satisfy the detector.

For a clone, record the source commit and list the bindings to replace: campaign and store identity, packages, offers, domains, analytics IDs, URLs and custom business logic. Prior QA applies to the source campaign; new bindings need their own proof. For a maintenance task, compare the requested change with the existing brief, spec and commerce configuration, following the [reconciliation and handoff procedure](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/build-packet.md) where it applies.
For a clone, record the source commit and list the bindings to replace: campaign and store identity, packages, offers, domains, analytics IDs, URLs and custom business logic. Prior QA applies to the source campaign; new bindings need their own proof. For a maintenance task, compare the requested change with the existing brief, spec and commerce configuration, following the [reconciliation and handoff procedure](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/build-packet.md#changing-a-campaign-after-handoff) where it applies.

## Build a local preview before connecting commerce

Expand All @@ -53,7 +55,7 @@ npm install next-campaign-page-kit
npx campaign-init --help
```

Choose a family from the [template catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json): preserve a template the user already chose, otherwise recommend one for the product, variant and page requirements and record why. For a non-interactive run, replace the placeholders with the selected values:
Choose a family from the [picker catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json), presented with previews and use cases in the [template browser](https://campaigns.nextcommerce.com/templates/): preserve a template the user already chose, otherwise recommend one for the product, variant and page requirements and record why. For a non-interactive run, replace the placeholders with the selected values:

```bash
npx campaign-init --non-interactive --json \
Expand Down
8 changes: 5 additions & 3 deletions content/docs/campaigns/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ Campaigns are fully custom checkout funnels — landing, checkout, upsell, and r

Orders created through a campaign are regular store orders. They appear in the store's Orders list alongside storefront orders and are available through the Admin API and webhooks like any other order.

<Callout type="info" title="Campaigns OS Start">
Give an agent a funnel URL, existing repo or saved Map using the [campaign agent guide](/docs/agent-setup). It can inspect, plan and prepare a local concept before store access is available. The [Campaigns OS Start guide](https://campaigns.nextcommerce.com/start/) also provides the Workspace/Map route. Keep your existing builder and host; the Page Kit quick start below is the reference path for a new static project.
<Callout type="info" title="Start or continue with your coding agent">
Start with the [campaign agent guide](/docs/agent-setup). Give your agent a funnel URL, design, existing repository or saved Map. It can inspect, plan and prepare a local preview before store access is available, while preserving your builder and host.

For a new Page Kit campaign with commerce already configured, use the [Page Kit setup recipe](https://campaigns.nextcommerce.com/start/). The optional [Workspace](https://campaign-map.nextcommerce.com/) lets you plan visually and save a Map. The quick start below covers direct Page Kit scaffolding.

@kilo-code-bot kilo-code-bot Bot Nov 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: "Page Kit setup recipe" mislabels campaigns.nextcommerce.com/start/, and contradicts the Workspace domain introduced in the same sentence

This URL was introduced as the Campaigns OS Start guide, and this repository documented what it does in that capacity:

Both describe a plan-and-handoff flow centred on Workspace, not a Page Kit scaffolding recipe. Relabelling it "Page Kit setup recipe" — while pointing Workspace at a different domain (campaign-map.nextcommerce.com) in the very same sentence — leaves two mutually exclusive claims in one repo about where Workspace lives. If the page's function changed upstream, the older descriptions are now stale and should be corrected too; if it did not change, this label sends readers looking for a scaffolder where the page is a planner.

Note also that index.mdx:18, immediately below, describes the actual Page Kit CLI ("a CLI that scaffolds an SDK-ready starter template..."), so "Page Kit setup recipe" now names a third Page Kit entry point alongside the "Page Kit guide" and the "quick start" below it — with nothing stating how the three differ.

</Callout>

For direct project scaffolding, use the **[Campaign Page Kit](https://github.com/NextCommerceCo/campaign-page-kit)**: a CLI that scaffolds an SDK-ready starter template, runs a hot-reload dev server, and outputs a static site you can deploy to Netlify, Cloudflare Pages, Vercel, or any static host.
Expand Down Expand Up @@ -178,7 +180,7 @@ Packages can also be **recurring** for subscription products. When you reference

### Offers

**Offers** are price mutation rules that apply when an order meets a condition. Two flavours:
Configure campaign discounts in [Campaigns App Offers & Discounts](https://docs.nextcommerce.com/docs/apps/campaigns-app/campaigns-offers-and-discounts). Use this setup when building with the SDK and campaign templates. Two flavours:

@kilo-code-bot kilo-code-bot Bot Nov 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: The Offers rewrite drops the only statement of how Offers relate to the SDK

The previous sentence told the reader what these rules are in platform terms: "These are the rules the SDK and campaign templates use for pricing and savings." The replacement — "Use this setup when building with the SDK and campaign templates" — only says where to configure them, and reads as a narrower condition on when the link matters.

The bullets below still define Offer and Code semantics, but nothing now says the SDK and the campaign templates read these same rules to price the cart and compute savings. If that relationship still holds, consider keeping it; if Offers & Discounts is really a separate merchant-side setup step, say so explicitly instead of leaving the reader to assume it is the SDK's pricing source.


- **Offer** — automatic, applies when the cart matches the rule (checkout page only)
- **Code** — voucher-based, applies when the customer enters a code. Codes stack **on top of** automatic offers, and codes are also the mechanism for applying discounts on **upsell pages** (where automatic offers don't run).
Expand Down
1 change: 1 addition & 0 deletions content/docs/campaigns/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"description": "Campaign funnels & checkout",
"pages": [
"---Guides---",
"[Start with your agent](/docs/agent-setup)",
"index",
"templates",
"page-kit",
Expand Down
4 changes: 4 additions & 0 deletions content/docs/campaigns/templates.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,8 @@ All templates are available for download on GitHub at [NextCommerceCo/campaign-c

These are the options you'll see at the `campaign-init` template picker. Each one installs a complete funnel into your project with SDK-ready checkout, cart, upsell, and receipt surfaces. Treat those commerce surfaces as runtime wiring: replace campaign-specific package IDs, offer codes, shipping methods, copy, assets, and routes, but avoid rebuilding the SDK-owned controls from scratch.

Compare families in the [template browser](https://campaigns.nextcommerce.com/templates/), which presents the [picker catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json) with previews and use cases. Keep the family an existing campaign already uses when it fits the change.

@kilo-code-bot kilo-code-bot Bot Nov 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: The new "picker catalog" / "template browser" split is applied to only two of the four places that name these artifacts

This line and the canonical prompt (content/agent-setup.md:58) now distinguish the raw JSON ("picker catalog") from the browsable site ("template browser"). The two sibling pages that name the same file were not updated:

  • content/docs/campaigns/index.mdx:105 — "Use the current catalog recommendations"
  • content/docs/campaigns/index.mdx:296 — "pick the family from the template catalog"
  • content/docs/campaigns/page-kit.mdx:110 — "pick the family from the template catalog"

So templates.json is now called "picker catalog", "current catalog" and "template catalog" depending on the page, and campaigns.nextcommerce.com/templates/ — the surface this line promotes — is never mentioned on either sibling page. A reader who lands on /docs/campaigns or /docs/campaigns/page-kit gets a third name and no pointer to the browser.

Since all three pages describe the same artifact, please settle on one label per artifact and apply it to all of them.


<CampaignTemplatesGrid />

Continue with the [campaign agent guide](/docs/agent-setup) and give your agent the selected family. You can build locally without a saved Map.
8 changes: 8 additions & 0 deletions scripts/generate-agent-setup.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ title: Start or continue a campaign with an agent
description: Start from a funnel URL, existing repository or Map, prepare a local preview, and leave a handoff another agent can continue
---

Start here to build or change a campaign with your own coding agent. Bring a URL, design, existing repository or saved Map; store access can follow when you are ready to connect commerce.

Give your coding agent this instruction:

\`\`\`text
Expand All @@ -52,6 +54,12 @@ Read https://developers.nextcommerce.com/agent-setup/prompt.md and help me start

The fetched file is plain Markdown at a stable URL. It uses the same source as the instructions below, contains no credentials, and keeps the current CLI and Campaigns docs authoritative. It covers campaign intake, existing builds and continuation. It does not require a new project or store credentials before source inspection and local planning.

Choose the continuation that fits your project:

- **New campaign:** inspect the source and prepare a local preview. Use the [Page Kit guide](/docs/campaigns/page-kit) for a new static project, or the [Page Kit setup recipe](https://campaigns.nextcommerce.com/start/) for a new static project with its campaign and offers already configured.

@kilo-code-bot kilo-code-bot Bot Nov 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WARNING: The canonical agent prompt now routes agents to /start/ as a Page Kit scaffolding path, contradicting how this repo has documented that page

This bullet reaches /agent-setup/prompt.md, which scripts/check-agent-surfaces.mjs:130 asserts is served byte-for-byte from content/agent-setup.md. It is the surface an agent actually reads, and the one this PR exists to unify.

Per this repo's own history, https://campaigns.nextcommerce.com/start/ is a plan-and-handoff flow: "configure products and offers in the NEXT dashboard, use Workspace to map and save the plan and copy its Handoff, then give that Handoff to a developer or agent to build, preview, and run QA" (7504f93), and "also provides the Workspace/Map route" (ce437eb). Describing it as "the Page Kit setup recipe ... for a new static project with its campaign and offers already configured" tells an agent to look for a scaffolder and, more importantly, steers it away from the Workspace/Handoff route that the very next bullet ("Saved Map: open its Handoff in the Workspace") presents as the saved-Map entry point.

Please confirm what /start/ actually does now and name it accordingly — for example a Workspace/Map planning-and-handoff recipe — or drop the external link if the canonical prompt should not route agents there.

- **Existing campaign:** keep its build and host, inspect the current revision, and follow the [maintenance procedure](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/build-packet.md#changing-a-campaign-after-handoff) when it uses Campaigns OS.
Comment thread
next-devin marked this conversation as resolved.
Resolved
- **Saved Map:** open its Handoff in the [Workspace](https://campaign-map.nextcommerce.com/), the optional visual planning tool, and give the saved plan to your agent.

${humanInstructions}`;

mkdirSync(docsDir, { recursive: true });
Expand Down
Loading