From ac4861899b2f3b41a1e04f07f5b0a30e5817d2d4 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Mon, 2 Nov 2026 14:53:48 +0700 Subject: [PATCH 1/2] docs: make the campaign agent guide the starting point --- components/campaign-templates-grid.tsx | 2 +- content/docs/campaigns/index.mdx | 8 +++++--- content/docs/campaigns/meta.json | 1 + content/docs/campaigns/templates.mdx | 6 +++++- scripts/generate-agent-setup.mjs | 8 ++++++++ 5 files changed, 20 insertions(+), 5 deletions(-) diff --git a/components/campaign-templates-grid.tsx b/components/campaign-templates-grid.tsx index 6526a47..f504911 100644 --- a/components/campaign-templates-grid.tsx +++ b/components/campaign-templates-grid.tsx @@ -20,7 +20,7 @@ const TEMPLATES: CampaignTemplate[] = [ name: 'olympus', slug: 'olympus', description: - 'Default pick. Single-step single-product checkout — lowest-friction conversion, used in most campaigns.', + '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/` }, diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index ab1a113..5544baf 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -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. - -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. + +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 [Campaigns OS setup recipe](https://campaigns.nextcommerce.com/start/). Workspace is optional. The quick start below covers direct Page Kit scaffolding. 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. @@ -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). These are the rules the SDK and campaign templates use for pricing and savings. Two flavours: - **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). diff --git a/content/docs/campaigns/meta.json b/content/docs/campaigns/meta.json index 53dfe64..b446553 100644 --- a/content/docs/campaigns/meta.json +++ b/content/docs/campaigns/meta.json @@ -5,6 +5,7 @@ "description": "Campaign funnels & checkout", "pages": [ "---Guides---", + "[Start with your agent](/docs/agent-setup)", "index", "templates", "page-kit", diff --git a/content/docs/campaigns/templates.mdx b/content/docs/campaigns/templates.mdx index e03cf5d..fec5c61 100644 --- a/content/docs/campaigns/templates.mdx +++ b/content/docs/campaigns/templates.mdx @@ -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. - +Use the [current template catalog](https://campaigns.nextcommerce.com/templates/) to choose a family. Its recommendations cover standard checkout, variant selection, and existing designs. Keep the family an existing campaign already uses when it fits the change. + + + +Continue with the [campaign agent guide](/docs/agent-setup) and give your agent the selected family. You can build locally without a saved Workspace Map. diff --git a/scripts/generate-agent-setup.mjs b/scripts/generate-agent-setup.mjs index 24c8bbc..c8b5e8c 100644 --- a/scripts/generate-agent-setup.mjs +++ b/scripts/generate-agent-setup.mjs @@ -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 @@ -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 [configured-campaign setup recipe](https://campaigns.nextcommerce.com/start/) when your campaign and offers are ready. +- **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. +- **Saved Map:** open its Handoff in the optional [Workspace](https://campaign-map.nextcommerce.com/) and give the saved plan to your agent. + ${humanInstructions}`; mkdirSync(docsDir, { recursive: true }); From 3e1abebc49cedddb397275fd7a27d790eaeedcfb Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Mon, 2 Nov 2026 16:40:56 +0700 Subject: [PATCH 2/2] Align campaign guide terminology and template ordering --- components/campaign-templates-grid.tsx | 64 +++++++++++++------------- content/agent-setup.md | 8 ++-- content/docs/campaigns/index.mdx | 4 +- content/docs/campaigns/templates.mdx | 6 +-- scripts/generate-agent-setup.mjs | 4 +- 5 files changed, 44 insertions(+), 42 deletions(-) diff --git a/components/campaign-templates-grid.tsx b/components/campaign-templates-grid.tsx index f504911..6a852ed 100644 --- a/components/campaign-templates-grid.tsx +++ b/components/campaign-templates-grid.tsx @@ -16,22 +16,6 @@ type CampaignTemplate = { const BASE = 'https://nextcommerce-campaign-templates.netlify.app'; const TEMPLATES: CampaignTemplate[] = [ - { - 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: 'apollo', slug: 'apollo', @@ -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', @@ -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', diff --git a/content/agent-setup.md b/content/agent-setup.md index 239b230..f9e761c 100644 --- a/content/agent-setup.md +++ b/content/agent-setup.md @@ -1,4 +1,4 @@ - + # Start or continue a NEXT campaign with an AI agent @@ -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. + ## 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. @@ -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 @@ -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 \ diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index 5544baf..2873cbb 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -12,7 +12,7 @@ Orders created through a campaign are regular store orders. They appear in the s 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 [Campaigns OS setup recipe](https://campaigns.nextcommerce.com/start/). Workspace is optional. The quick start below covers direct Page Kit scaffolding. +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. 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. @@ -180,7 +180,7 @@ Packages can also be **recurring** for subscription products. When you reference ### Offers -Configure campaign discounts in [Campaigns App Offers & Discounts](https://docs.nextcommerce.com/docs/apps/campaigns-app/campaigns-offers-and-discounts). These are the rules the SDK and campaign templates use for pricing and savings. 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: - **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). diff --git a/content/docs/campaigns/templates.mdx b/content/docs/campaigns/templates.mdx index fec5c61..9a8e07d 100644 --- a/content/docs/campaigns/templates.mdx +++ b/content/docs/campaigns/templates.mdx @@ -9,8 +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. -Use the [current template catalog](https://campaigns.nextcommerce.com/templates/) to choose a family. Its recommendations cover standard checkout, variant selection, and existing designs. Keep the family an existing campaign already uses when it fits the change. +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. - + -Continue with the [campaign agent guide](/docs/agent-setup) and give your agent the selected family. You can build locally without a saved Workspace Map. +Continue with the [campaign agent guide](/docs/agent-setup) and give your agent the selected family. You can build locally without a saved Map. diff --git a/scripts/generate-agent-setup.mjs b/scripts/generate-agent-setup.mjs index c8b5e8c..a30c022 100644 --- a/scripts/generate-agent-setup.mjs +++ b/scripts/generate-agent-setup.mjs @@ -56,9 +56,9 @@ The fetched file is plain Markdown at a stable URL. It uses the same source as t 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 [configured-campaign setup recipe](https://campaigns.nextcommerce.com/start/) when your campaign and offers are ready. +- **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. - **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. -- **Saved Map:** open its Handoff in the optional [Workspace](https://campaign-map.nextcommerce.com/) and give the saved plan to your agent. +- **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}`;