From 494fa640babd8203d8d31187375747cdb85f962f Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Thu, 22 Oct 2026 18:12:41 +0700 Subject: [PATCH 01/13] Guide campaign intake and continuation across existing builds --- app/llms.txt/route.ts | 4 +- content/agent-setup.md | 118 +++++++++++++++++++++---------- content/capabilities.yaml | 8 ++- content/docs/campaigns/index.mdx | 22 +++--- content/docs/skills/index.mdx | 8 +-- package.json | 2 +- scripts/check-agent-surfaces.mjs | 14 +++- scripts/generate-agent-setup.mjs | 10 +-- 8 files changed, 121 insertions(+), 65 deletions(-) diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.ts index 7ff1c53..ce99012 100644 --- a/app/llms.txt/route.ts +++ b/app/llms.txt/route.ts @@ -73,8 +73,8 @@ function header(): string { `- [Campaigns API spec, v1](${SITE}/api/campaigns/v1.yaml): raw OpenAPI`, `- [Webhooks](${SITE}/docs/webhooks)`, `- [Skills](${SITE}/docs/skills): AI agent skills for the platform`, - `- [Campaign agent quickstart](${SITE}/docs/agent-setup): optional wrapper around the current Campaign Page Kit docs and CLI that preserves developer choices`, - `- [Campaign agent quickstart prompt](${SITE}/agent-setup/prompt.md): stable plain-Markdown instructions for starting a new campaign project when that is the developer's requested task`, + `- [Campaign agent quickstart](${SITE}/docs/agent-setup): start from a funnel URL, existing repo or Map; preview locally and leave a resumable handoff`, + `- [Campaign agent quickstart prompt](${SITE}/agent-setup/prompt.md): stable plain-Markdown instructions for campaign intake, existing builds and continuation`, `- [Prospect evaluation prompt](${SITE}/evaluate/prompt.md): source-grounded instructions for evaluating platform capabilities, fit, gaps, and a first pilot`, `- [Testing](${SITE}/docs/testing)`, `- [Agent guide (AGENTS.md)](https://github.com/NextCommerceCo/developer-docs/blob/main/AGENTS.md): navigation and evidence rules for agents reading this site`, diff --git a/content/agent-setup.md b/content/agent-setup.md index bc17240..8690dcc 100644 --- a/content/agent-setup.md +++ b/content/agent-setup.md @@ -1,23 +1,64 @@ - + -# Start a Campaign Page Kit project with an AI agent +# Start or continue a NEXT campaign with an AI agent -Use this quickstart only when the user wants a new Campaign Page Kit workspace. It is an optional agent-friendly wrapper around the current Campaigns documentation and `campaign-init`; it is not a general Next Commerce development environment, a production architecture decision, or a replacement for the developer's chosen workflow. +Use this procedure when the user supplies a funnel URL, design, existing campaign repository, or saved Map and wants to build, change, preview, or resume a campaign. Keep their build and hosting choices. Campaign Page Kit is the reference path for a new static campaign; an existing application does not need to become a Page Kit project. -If the user wants to understand the platform, work in an existing project, build a storefront theme or app, or use the Admin API, do not scaffold a campaign. Read the [developer index](https://developers.nextcommerce.com/llms.txt?ref=agent-setup) and [platform capability map](https://developers.nextcommerce.com/capabilities.json?ref=agent-setup), identify the relevant documentation, and respond to that task instead. +For storefront themes, apps, or other platform work, use the [developer index](https://developers.nextcommerce.com/llms.txt?ref=agent-setup) and [capability map](https://developers.nextcommerce.com/capabilities.json?ref=agent-setup) to find the relevant procedure instead. ## Before writing -- Confirm that the user's request calls for a new Campaign Page Kit project. If it is unclear, ask one concise question before installing packages or creating files. -- Inspect the current directory. If it contains an existing project, do not add a second project or replace its configuration. Ask whether to use that project or create a new subdirectory. -- Use the Node.js version required by the current [Campaigns quick start](https://developers.nextcommerce.com/docs/campaigns?ref=agent-setup). Do not impose a stricter version or relax the documented requirement. -- Preserve any template, source, project name, route slug, package manager, and agent-context choice the user has already made. The commands below use the docs' npm path for an empty project; do not replace an existing project's package-manager convention. -- Do not request, print, copy, or invent credentials. A workspace can be scaffolded and built without a Campaign API key. -- Do not call a live store or place an order unless the user has identified the store, authorized the action, and provided suitable test access. +Inspect the supplied files and current directory. Identify the intended change, source URL/design, existing repo, campaign identity if known, build command, output directory, hosting method, and any saved brief, spec, Map or evidence. Preserve existing work and user choices; do not scaffold over an existing project. -## Use the current Campaign Page Kit workflow +Ask together for missing business decisions that affect the result, such as target products, offer changes or which source design to follow. Continue source inspection and local planning while those answers or credentials are missing. Do not ask the user to choose internal tool names. -Read the [Campaign Page Kit guide](https://developers.nextcommerce.com/docs/campaigns/page-kit?ref=agent-setup), then inspect the installed CLI contract before constructing a command: +Record actual installed versions and the source commit of a reused template/repo. For work that includes Campaigns OS, use its [runtime preparation guidance](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/runtime-readiness.md); Node.js 22 is a common supported choice. The Page Kit-only minimum and the Campaigns OS supported runtime range are different. Read the installed CLI help and package documentation before using flags. If an installed documentation link is missing, use the corresponding public repository file at that package's release tag and record the mismatch. + +Store access, repository publishing, deployment, test orders, and analytics sends are separate effects. A source URL or API key does not authorize all of them. Use existing authority from the user's request; never print credentials or put them in the brief, handoff, committed files or command output. With no store-write authority, keep work local and leave provisioning and payment checks pending. + +## Choose the entry point + +| Supplied input | First action | Continue with | +| --- | --- | --- | +| Funnel/store URL or design | Read the source and distinguish observed facts from proposed behavior | A build brief, commerce dependency plan and local concept preview | +| Existing or cloned campaign repo | Read its instructions, build/configuration and retained evidence | Inspect current behavior and change only what the task requires | +| Existing external build | Inspect its own source, build and deployment conventions | The relevant Campaign Cart checks; retain its framework and host | +| Local CampaignSpec, saved Map or Build Packet | Identify the selected campaign and read existing intent/status | The supported Campaigns OS continuation command for that artifact | + +These entries can join the same work at different points. Do not replay provisioning or scaffolding merely because a new session starts. + +## From a source URL to a proposal + +Read public HTML or user-provided source without submitting forms or using cart/checkout endpoints. Record source URLs and capture dates. Describe observed products, variants, displayed prices/currency, offer wording, page structure and visible navigation. Mark checkout rules, shipping, subscriptions and post-purchase behavior unknown when the source does not establish them. A source site's displayed price is not proof of a NEXT package or offer configuration. + +Save presentation intent in the existing [Campaign Build Brief](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-build-brief.md) format, using its [v1 schema](https://github.com/NextCommerceCo/campaigns-os/blob/main/schemas/campaign-build-brief.v1.schema.json). Start with `schema_version: campaigns-os-build-brief/v1`, `brief_mode: guided`, and `status: needs_answers`. Keep source observations, proposed changes and unresolved questions distinct; use `_meta` for provenance. Do not label unapproved business choices complete. + +In the project's existing README or handoff note, record the proposed page journey and commerce dependencies: + +- Catalogue products, variants, base prices and currencies that must exist on the target store. +- Campaign packages, quantity selections, offers/codes and shipping that must reference that catalogue. +- Page behavior: selection, information/shipping steps, payment, offer acceptance/decline and receipt. +- Required domains, payment linking and analytics configuration, with their current evidence or unknown status. + +Do not invent package IDs, campaign keys or a saved Map to make validation pass. Without real commerce bindings, retain the brief and dependency plan; a complete operational CampaignSpec comes later. Importing visual source does not automatically migrate checkout behavior. + +## Inspect an existing or cloned build + +Read the repository's current brief, spec and generated records before deriving new intent from code. Code establishes implemented behavior; it does not establish what the merchant wanted. If Campaign Cart is present, use the existing [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md) after preparing the toolkit: + +```bash +campaigns-os standardize --target /path/to/existing-campaign --no-doctor --json +``` + +This inspects source without modifying the target. Retain its report and exact command outside generated stage records. A report does not migrate the project, prove checkout, or certify a launch. If the application is not recognized, record that limit and inspect its own integration; do not change frameworks to satisfy the detector. + +For a clone, record the source commit and list bindings that need replacement: campaign/store identity, packages, offers, domains, analytics IDs, URLs and custom business logic. Inspect names and locations without exposing secret values. Do not execute inherited scripts or open a connected clone before those effects are understood. Prior QA applies to the source campaign; the new bindings and changed behavior need their own proof. + +For a maintenance task, compare the requested business change with the existing brief/spec, authoritative commerce and implementation. Follow the [existing reconciliation and handoff procedure](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/build-packet.md) where it applies. Preserve the builder's deployment method and unchanged work. + +## Build a local preview before connecting commerce + +For a new Page Kit workspace, read the [Page Kit guide](https://developers.nextcommerce.com/docs/campaigns/page-kit?ref=agent-setup). In an empty task directory: ```bash npm init -y @@ -25,9 +66,9 @@ npm install next-campaign-page-kit npx campaign-init --help ``` -If the user has not supplied a template, route slug, campaign name, and agent-context preference, ask for the missing choices together. Do not silently select a starter template or context file. Use the current template picker or catalog described by the CLI and docs rather than copying a fixed list from this prompt. +Use the current [template catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json) and its selection guidance. Preserve a chosen template; otherwise recommend one for the product/variant and page requirements. Record the choice and why. Use the user's supplied name/slug, or propose them while continuing source work. -For a non-interactive agent run, replace every placeholder below with the developer-confirmed value: +For a non-interactive run, replace the placeholders with the selected values: ```bash npx campaign-init --non-interactive --json \ @@ -35,10 +76,9 @@ npx campaign-init --non-interactive --json \ --slug \ --name "" \ --ai-context +npm run build ``` -Choose the context value that matches the current tool, or `none` when the tool is unsupported or the developer does not want a generated context file: - | Tool | `--ai-context` value | | --- | --- | | Claude Code | `claude` | @@ -47,36 +87,38 @@ Choose the context value that matches the current tool, or `none` when the tool | GitHub Copilot | `copilot` | | Other agents | `none` | -`campaign-init` is the authority for scaffold behavior, supported flags, conflict handling, and exit codes. Do not reproduce the scaffold manually if it fails. Preserve its output and follow the troubleshooting guidance in the Campaign Page Kit guide. +The CLI owns scaffolding and conflict handling. Preserve failure output instead of recreating the scaffold by hand. A successful build writes `_site/`; it does not prove that opening those pages is safe or that commerce works. -The [Next Commerce AI skills guide](https://developers.nextcommerce.com/docs/skills?ref=agent-setup) describes optional reusable skills. Installing `next-campaigns-setup` is not required for this quickstart. Use it only when the developer asks for the fuller guided setup/configuration workflow or another official tool routes the task to it. +**Do not open an unconfigured scaffold just because init accepted no key.** Page Kit 0.3.0 can retain the template's demo key and enabled analytics. Inspect the installed version's behavior and generated output. Use a documented static-preview mode only when that installed version actually provides it, and verify it disables scripts, forms, frames and external requests before browser inspection. A pending PR is not a released capability. -## Verify only what was requested +If that protection is unavailable, leave the scaffold unopened. Make a separate local visual concept in a directory containing only authored static HTML, local CSS and local assets. Include no SDK/config scripts, forms, frames, event handlers, remote assets or payment navigation. Put this policy first in each page's ``, and label every page **Commerce unconfigured — visual concept only**: -Run the static build: - -```bash -npm run build +```html + ``` -Use the JSON emitted by `campaign-init` and the generated project files to confirm that: +Serve only that concept directory on loopback. Inspect its source before opening, then check rendered output and network activity at desktop and mobile widths. Record visual defects and limitations. This concept can communicate design and proposed navigation; it is not the connected campaign or payment QA. Do not remove runtime wiring from an existing campaign to make this separate preview. + +## Connect the approved implementation when ready + +The public [next-campaigns-create skill](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-create) owns campaign creation, edit, adopt/diff/update and campaign cloning through its existing plan/approval boundaries. It reads existing catalogue products and creates campaign configuration; it does not create catalogue products or CampaignSpec. Missing products/prices require the appropriate [Admin API product procedure](https://developers.nextcommerce.com/docs/admin-api) or dashboard work with its own access and authority. The Campaign Cart key and Admin API token are different credentials. + +Use [next-campaigns-setup](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) for Page Kit configuration. The [AI skills guide](https://developers.nextcommerce.com/docs/skills?ref=agent-setup) explains installation and version checks. Existing projects keep their own build procedure. Record Allowed Domains and payment-account linking as dependencies at their actual dashboard/API boundary. + +When real references and intended behavior are known, use the installed Campaigns OS [agent entry](https://github.com/NextCommerceCo/campaigns-os/blob/main/AGENTS.md) to choose local-spec or saved-Map intake. Current authoring uses CampaignSpec v5: `select` chooses before payment, `checkout_step` collects a form step, and `checkout` takes payment. v4.2/v4.3 read compatibility does not make those old versions the authoring target. The [public multi-step examples](https://github.com/NextCommerceCo/campaign-cart-starter-templates/tree/main/docs/fixtures/campaign-specs) illustrate the roles; use the installed toolkit's routing projection rather than treating every example hint as an implemented runtime guarantee. -- the selected campaign is registered in `_data/campaigns.json`; -- its source directory exists under `src/`; -- the requested agent context file was created, or no context file was requested; -- the build exits successfully and writes the campaign to `_site/`. +Keep any saved-Map requirement that applies to the user's delivery process. Do not save a Map, publish a repo, deploy, submit an order or send analytics as a side effect of this local-preview procedure. Record what is authorized, then invoke the appropriate existing capability. A doctor/static pass, intercepted analytics request and vendor receipt are different evidence. State which was actually obtained. -Inspect one generated entry page and briefly describe what the selected starter contains. Treat that as proof of a local scaffold only. Do not claim the project is connected to a store, production-ready, or tested end to end without the corresponding evidence. +## Leave work another session can continue -If the user explicitly wants to continue, follow the current Campaigns and testing documentation for configuration and test-store work. Otherwise stop after the verified local build; do not turn a quickstart into an unsolicited production setup. +Use the repository's existing README or handoff note. Link the existing artifacts rather than creating a second lifecycle record. Include: -## Report back +1. The user's requested outcome, chosen implementation/host, source URLs or clone commit, and unresolved business questions. +2. Brief/spec/Map/Build Packet paths or IDs that really exist; list absent artifacts as absent. Keep credentials out of the note. +3. Installed tool/skill versions, working directory, build command and output directory; identify the separate concept preview when used. +4. Which commerce bindings are verified, missing or inherited, and which actions remain unauthorized. +5. Exact checks and output paths, what those checks prove, outstanding defects, and the next executable local action or specific missing input. -Tell the user: +A returning session reads that note and the linked artifacts, checks the current revision and installed versions, and resumes the next action. It does not reset the project or replay completed writes. Let Campaigns OS commands create their own stage/evidence records; never hand-write a passing Assembly Report or reuse a source campaign's QA as acceptance for a clone. -1. Which directory and existing/new project path you used. -2. Which developer-provided template, slug, name, and agent-context value you used. -3. Which official docs and CLI contract you followed. -4. Whether `campaign-init` and the static build passed. -5. What you verified in the generated output. -6. What remains unconfigured or untested, and the next step relevant to the user's stated goal. +Report the result in plain language: what can be reviewed now, what is still unconfigured or unproved, and what is needed to continue. Stop at the user's requested boundary. diff --git a/content/capabilities.yaml b/content/capabilities.yaml index 8f4002f..de11439 100644 --- a/content/capabilities.yaml +++ b/content/capabilities.yaml @@ -266,8 +266,9 @@ capabilities: title: Campaigns summary: >- Campaigns are custom checkout funnels (landing, checkout, upsell, receipt pages) - backed by the CORS-enabled Campaigns API, built with the Campaign Page Kit and - starter templates. A campaign's checkout is separate from the storefront checkout, + backed by the CORS-enabled Campaigns API. Campaign Page Kit and starter templates + provide a reference build path; existing Campaign Cart applications retain their + tooling. A campaign's checkout is separate from the storefront checkout, but its orders are ordinary store orders that share the orders list, inventory, and subscriptions. audiences: [merchant, developer] @@ -279,6 +280,7 @@ capabilities: developer_docs: - /docs/campaigns - /docs/campaigns/page-kit + - /docs/agent-setup - /docs/campaigns/templates - /docs/campaigns/api - /docs/campaigns/admin-api @@ -286,7 +288,7 @@ capabilities: webhooks: [] skills: [next-campaigns-create, next-campaigns-setup] status: available - last_verified: 2026-09-14 + last_verified: 2026-10-22 - id: storefront-themes title: Storefront themes diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index c813717..df38826 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -1,6 +1,6 @@ --- title: Getting Started -description: Scaffold a campaign funnel with Campaign Page Kit, place a test order, and understand campaigns, packages, offers, domains, analytics, and hosting +description: Start or continue a campaign, preview locally, and connect products, offers, domains, analytics and hosting --- import { Callout } from 'fumadocs-ui/components/callout'; import { CampaignFunnelFlow, CampaignAnatomy } from '@/components/campaign-concepts-flow'; @@ -10,7 +10,7 @@ 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. -Start in the [Campaigns OS Start guide](https://campaigns.nextcommerce.com/start/): 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. The Page Kit quick start below remains the manual path for starting a project. +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. 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. @@ -19,9 +19,9 @@ For direct project scaffolding, use the **[Campaign Page Kit](https://github.com ### 1. Prerequisites -- **Node.js 18+** -- A **Next Commerce store** with a campaign created in the Campaigns App -- Your **Campaign API key**: select **Developer** in the campaign header to open the Developer workspace, then copy the key from the **Campaigns API** section +- **Node.js 18+** for Page Kit alone. If using Campaigns OS too, follow its [runtime guidance](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/runtime-readiness.md); Node.js 22 is a common supported choice. +- To connect commerce: a **Next Commerce store** with a campaign created in the Campaigns App +- To connect commerce: your **Campaign API key**: select **Developer** in the campaign header to open the Developer workspace, then copy the key from the **Campaigns API** section ### 2. Initialize a new project @@ -48,7 +48,7 @@ The `--ai-context` step writes the right context file to the right path for your -Skipping the API key during init is fine — run `npm run config` later to set it. +You can build without supplying a key, but Page Kit 0.3.0 may retain demo commerce credentials and enabled tracking. Before opening unconfigured output, follow the [local preview procedure](/docs/agent-setup#build-a-local-preview-before-connecting-commerce). Run `npm run config` when ready to bind the intended campaign. ### 3. Start the dev server @@ -57,15 +57,15 @@ Skipping the API key during init is fine — run `npm run config` later to set i npm run dev ``` -This opens your campaign's first page (e.g. `//presell/`) in the browser and hot-reloads as you edit. If you have multiple campaigns in the project, you'll get a picker. +For a configured campaign you are authorized to preview, this opens your campaign's first page (e.g. `//presell/`) in the browser and hot-reloads as you edit. If you have multiple campaigns in the project, you'll get a picker. -You now have a **complete campaign funnel** running on your local machine — presell, landing, checkout, upsells, and receipt — all wired up to your live store data through the SDK. Click through it and create a test order using the test card below. +The local server renders the starter pages. Store connection and checkout behavior still depend on the correct campaign binding, packages, offers and allowed domain. A local build alone does not verify those dependencies. ### 4. Place a test order -Run the full funnel end-to-end on your local dev server. At checkout, pay with the test card below — it processes without a real transaction so you can verify presell → checkout → upsell(s) → receipt all wire up correctly. +After the target store and test-order effects are authorized, run the configured funnel on your local dev server. The card below avoids a real payment, but submitting it creates a test order and may trigger downstream integrations. Follow [Testing](/docs/testing) for the applicable controls before checking checkout and post-purchase behavior. | Card number | Expiry | CVV | What it does | | --- | --- | --- | --- | @@ -100,9 +100,9 @@ my-campaigns/ ## Starter templates -Pick one at the `campaign-init` template prompt. Each template ships with SDK-ready checkout, upsell, and receipt surfaces, plus the supporting presell and landing pages for that family. Start from a maintained template, then replace campaign-specific copy, assets, package IDs, offer codes, shipping methods, tracking, and routes with values from Campaigns App and your build brief. The two Olympus templates are a good starting point for your first campaign. +Pick one at the `campaign-init` template prompt. Each template ships with SDK-ready checkout, upsell, and receipt surfaces, plus the supporting presell and landing pages for that family. Start from a maintained template, then replace campaign-specific copy, assets, package IDs, offer codes, shipping methods, tracking, and routes with values from Campaigns App and your build brief. Use the [current catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json) recommendations: Apollo for a standard tiered checkout, or Apollo MV for configurable variant slots. Preserve an existing family when it fits the project. - + [See all available templates →](/docs/campaigns/templates) diff --git a/content/docs/skills/index.mdx b/content/docs/skills/index.mdx index 207b89b..0091e44 100644 --- a/content/docs/skills/index.mdx +++ b/content/docs/skills/index.mdx @@ -8,7 +8,7 @@ import { Callout } from 'fumadocs-ui/components/callout'; Skills are structured markdown files. Any AI tool that accepts a context file or system prompt can use them — Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, and 50+ other LLM-powered agents. -For an optional quickstart that follows the current Campaign Page Kit CLI without choosing a template or project structure for you, use the [campaign agent quickstart](/docs/agent-setup). The quickstart does not require installing a skill. +Start with the [campaign agent guide](/docs/agent-setup) when you have a funnel URL, existing repo or Map. It covers local planning, preview and continuation while preserving your build and hosting choices. Reading the guide does not require installing a skill. ## Install @@ -69,8 +69,8 @@ An installed skill is a copy, so it doesn't change when the repository does. Che | [**next-theme-figma**](https://github.com/NextCommerceCo/skills/tree/main/next-theme-figma) | Turn a Figma storefront design into a validated, low-inference handoff package for `next-theme-dev`: sections, assets, geometry, copy, and design tokens | You have a Figma storefront design (PDP, homepage, and so on) to build as a Next Commerce theme | | [**next-theme-design**](https://github.com/NextCommerceCo/skills/tree/main/next-theme-design) | Turn a live website or its HTML into a validated handoff package for `next-theme-dev`: captures at three widths, sections, geometry, copy decisions, styles, behaviors, and commerce divergences | You want an existing page, such as a merchant's landing page, rebuilt as a Next Commerce storefront | | [**next-theme-dev**](https://github.com/NextCommerceCo/skills/tree/main/next-theme-dev) | Build, modify, and debug storefront themes: Spark, Intro Bootstrap, Theme Settings, the `ntk` CLI, DTL templates, storefront GraphQL, and builds from Figma or live-site handoff packages | You're editing theme files, setting up a new storefront, building from a handoff package, or debugging templates | -| [**next-campaigns-create**](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-create) | Create a launch-ready Campaigns App campaign over the Admin API: packages, shipping, quantity Buy 1/2/3, buy-X-get-Y as a labeled percentage, and gift-with-purchase, behind a plan-hash approval gate. Hands back the campaign `api_key` and package IDs | A new campaign needs to exist on a store before funnel work starts. It creates new campaigns only | -| [**next-campaigns-setup**](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) | Scaffold and configure a new Campaign Page Kit campaign end to end: project, starter template, config, and analytics | Starting a new CPK campaign after the campaign exists in the Campaigns App | +| [**next-campaigns-create**](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-create) | Create, edit, adopt/diff/update or clone campaign configuration through its reviewed plan and ownership boundaries. Reads existing catalogue products; manages campaign packages, shipping and offers | You need to create or change campaign configuration. It does not create catalogue products, pages or CampaignSpec | +| [**next-campaigns-setup**](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) | Guide Page Kit setup and configuration; use the public agent guide for URL intake, existing-build inspection and continuation | You need a Page Kit project or configuration. Check the installed skill version before relying on newer intake guidance | | [**next-bulk-fulfill**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-fulfill) | Mark orders **Fulfilled** with tracking numbers from a CSV when a fulfillment provider's sync-back fails | A provider shipped orders but tracking didn't sync back, leaving orders stuck in *Processing* | | [**next-bulk-move**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-move) | Move fulfillment orders between warehouse locations in bulk, from a file of order numbers or a product/SKU list | Switching fulfillment providers, or moving every fulfillment order containing a given SKU or product | | [**next-bulk-subscription**](https://github.com/NextCommerceCo/skills/tree/main/next-bulk-subscription) | Pause, cancel, or update subscriptions in bulk from a CSV or XLSX of subscription IDs, with a dry run and verification | Bulk-pausing, shifting renewal dates, changing intervals or gateways, or cancelling a list of subscriptions | @@ -84,7 +84,7 @@ Each skill lists its own requirements in its `SKILL.md` and `README.md`. In gene - **Operations and campaign provisioning skills** (`next-bulk-*`, `next-ops-scan`, `next-campaigns-create`) run Python 3 scripts that use only the standard library. They need an Admin API token with the scopes the skill names, in a local `.env` as `{SUBDOMAIN}_NEXT_ADMIN_API_TOKEN` or in the environment. Create the API access under **Settings → API Access**. - **Theme skills** need Python 3.10 or newer (`next-theme-figma` also uses Node.js), a browser tool that can take screenshots, and for `next-theme-dev` a Storefront OAuth app API key with `themes:read` and `themes:write`. -- **`next-campaigns-setup`** needs Node.js and npm, a Campaign Page Kit project, and the campaign's Campaign Cart API key. +- **Campaign local planning** needs source material, not a store key. Page Kit setup needs Node.js and a package manager; connecting commerce needs the intended campaign's Campaign Cart API key. Admin API provisioning uses a separate token. For work that includes Campaigns OS, follow its supported runtime guidance; Node.js 22 is a common choice. Skills that change store data (bulk actions, campaign creation, theme pushes) show a plan or dry run and wait for your approval before writing. diff --git a/package.json b/package.json index 31e9221..d4d48de 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "dev": "npm run generate && npm run build:preview && next dev --turbopack", "build": "npm run generate && npm run build:preview && next build", "start": "next start", - "generate": "node scripts/generate-api-docs.mjs && node scripts/generate-stats.mjs && node scripts/generate-graphql-docs.mjs && node scripts/generate-capability-map.mjs && node scripts/generate-agent-setup.mjs", + "generate": "node scripts/generate-api-docs.mjs && node scripts/generate-stats.mjs && node scripts/generate-graphql-docs.mjs && node scripts/generate-agent-setup.mjs && node scripts/generate-capability-map.mjs", "generate-api-docs": "node scripts/generate-api-docs.mjs", "generate-graphql-docs": "node scripts/generate-graphql-docs.mjs", "generate-stats": "node scripts/generate-stats.mjs", diff --git a/scripts/check-agent-surfaces.mjs b/scripts/check-agent-surfaces.mjs index 5debfaf..04e8661 100644 --- a/scripts/check-agent-surfaces.mjs +++ b/scripts/check-agent-surfaces.mjs @@ -125,11 +125,20 @@ if (capabilityMap) { const setupPrompt = read(join(OUT, 'agent-setup', 'prompt.md')); check(setupPrompt !== null, 'out/agent-setup/prompt.md does not exist'); if (setupPrompt !== null) { + check(setupPrompt === readFileSync(join(ROOT, 'content', 'agent-setup.md'), 'utf8').trimEnd() + '\n', 'agent setup prompt differs from its canonical source'); check(setupPrompt.startsWith('\n+/, ''); if (!promptHeading.test(humanSource)) { throw new Error('content/agent-setup.md must contain the expected setup heading'); } const humanInstructions = humanSource.replace(promptHeading, '## Instructions your agent receives'); const guide = `--- -title: Campaign agent quickstart -description: An optional agent-friendly wrapper around the current Campaign Page Kit docs and CLI that preserves the developer's workflow choices +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 --- Give your coding agent this instruction: \`\`\`text -Read https://developers.nextcommerce.com/agent-setup/prompt.md and use it to start a new Campaign Page Kit project for this task. Preserve my existing choices. If the template, route slug, campaign name, or agent-context preference is missing, ask me before creating files. +Read https://developers.nextcommerce.com/agent-setup/prompt.md and help me start or continue this campaign from the URL, repository or Map I provide. Preserve my build and hosting choices. Prepare a local preview and resumable handoff; keep live merchant state untouched. \`\`\` -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 is a campaign-specific quickstart, not general setup for every kind of Next Commerce development. +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. ${humanInstructions}`; From 240b1468d3532a327f0502478df3dee770a8aa8e Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Thu, 22 Oct 2026 18:17:04 +0700 Subject: [PATCH 02/13] Point source inspections to the published toolkit install --- content/agent-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/agent-setup.md b/content/agent-setup.md index 8690dcc..353e2cb 100644 --- a/content/agent-setup.md +++ b/content/agent-setup.md @@ -44,7 +44,7 @@ Do not invent package IDs, campaign keys or a saved Map to make validation pass. ## Inspect an existing or cloned build -Read the repository's current brief, spec and generated records before deriving new intent from code. Code establishes implemented behavior; it does not establish what the merchant wanted. If Campaign Cart is present, use the existing [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md) after preparing the toolkit: +Read the repository's current brief, spec and generated records before deriving new intent from code. Code establishes implemented behavior; it does not establish what the merchant wanted. If Campaign Cart is present, use the existing [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md). Reuse the project's pinned toolkit, or follow the [published-package installation instructions](https://github.com/NextCommerceCo/campaigns-os#quick-start) in a separate inspection directory; an inspection alone does not require adding Campaigns OS to the application: ```bash campaigns-os standardize --target /path/to/existing-campaign --no-doctor --json From 49a9cafa20a259ead655e1dc8edd94fc958c2322 Mon Sep 17 00:00:00 2001 From: Devin Michael Date: Thu, 22 Oct 2026 19:00:08 +0700 Subject: [PATCH 03/13] Clarify campaign tool invocation and preview boundaries --- content/agent-setup.md | 29 ++++++++++++++++++++++------- scripts/check-agent-surfaces.mjs | 8 +++++--- 2 files changed, 27 insertions(+), 10 deletions(-) diff --git a/content/agent-setup.md b/content/agent-setup.md index 353e2cb..1171273 100644 --- a/content/agent-setup.md +++ b/content/agent-setup.md @@ -44,12 +44,24 @@ Do not invent package IDs, campaign keys or a saved Map to make validation pass. ## Inspect an existing or cloned build -Read the repository's current brief, spec and generated records before deriving new intent from code. Code establishes implemented behavior; it does not establish what the merchant wanted. If Campaign Cart is present, use the existing [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md). Reuse the project's pinned toolkit, or follow the [published-package installation instructions](https://github.com/NextCommerceCo/campaigns-os#quick-start) in a separate inspection directory; an inspection alone does not require adding Campaigns OS to the application: +Read the repository's current brief, spec and generated records before deriving new intent from code. Code establishes implemented behavior; it does not establish what the merchant wanted. If Campaign Cart is present, use the existing [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md). Reuse the project's pinned toolkit and run from the directory that owns its installation. If none exists, follow the source review and release selection in the [published-package installation instructions](https://github.com/NextCommerceCo/campaigns-os#quick-start), then install that exact release in a separate empty inspection directory: ```bash -campaigns-os standardize --target /path/to/existing-campaign --no-doctor --json +npm init -y +npm install --save-dev --save-exact @nextcommerce/campaigns-os@ ``` +An inspection alone does not require adding Campaigns OS to the application. From the directory containing the chosen local installation, verify the installed package, record its version/status, read its help, and inspect the target: + +```bash +npm ls @nextcommerce/campaigns-os --depth=0 +npx --no-install campaigns-os tooling status --json +npx --no-install campaigns-os --help +npx --no-install campaigns-os standardize --target /path/to/existing-campaign --no-doctor --json +``` + +If the package is absent or the installed version differs from the reviewed pin, resolve that before running the CLI. Keep `--no-install`: `campaigns-os` is the executable name of the scoped package, not a package to download implicitly. `tooling status` can report attention needed for missing agent skills; retain its version and invocation report, and use that release's setup guidance for any required preparation. Do not assume a global binary is available or points at the same version. + This inspects source without modifying the target. Retain its report and exact command outside generated stage records. A report does not migrate the project, prove checkout, or certify a launch. If the application is not recognized, record that limit and inspect its own integration; do not change frameworks to satisfy the detector. For a clone, record the source commit and list bindings that need replacement: campaign/store identity, packages, offers, domains, analytics IDs, URLs and custom business logic. Inspect names and locations without exposing secret values. Do not execute inherited scripts or open a connected clone before those effects are understood. Prior QA applies to the source campaign; the new bindings and changed behavior need their own proof. @@ -63,7 +75,8 @@ For a new Page Kit workspace, read the [Page Kit guide](https://developers.nextc ```bash npm init -y npm install next-campaign-page-kit -npx campaign-init --help +npm ls next-campaign-page-kit --depth=0 +npx --no-install campaign-init --help ``` Use the current [template catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json) and its selection guidance. Preserve a chosen template; otherwise recommend one for the product/variant and page requirements. Record the choice and why. Use the user's supplied name/slug, or propose them while continuing source work. @@ -71,7 +84,7 @@ Use the current [template catalog](https://github.com/NextCommerceCo/campaign-ca For a non-interactive run, replace the placeholders with the selected values: ```bash -npx campaign-init --non-interactive --json \ +npx --no-install campaign-init --non-interactive --json \ --template \ --slug \ --name "" \ @@ -89,14 +102,16 @@ npm run build The CLI owns scaffolding and conflict handling. Preserve failure output instead of recreating the scaffold by hand. A successful build writes `_site/`; it does not prove that opening those pages is safe or that commerce works. -**Do not open an unconfigured scaffold just because init accepted no key.** Page Kit 0.3.0 can retain the template's demo key and enabled analytics. Inspect the installed version's behavior and generated output. Use a documented static-preview mode only when that installed version actually provides it, and verify it disables scripts, forms, frames and external requests before browser inspection. A pending PR is not a released capability. +**Do not open an unconfigured scaffold just because init accepted no key.** Page Kit 0.3.0 can retain the template's demo key and enabled analytics. Inspect the installed version reported above, its documented behavior and generated output. Use a documented static-preview mode only when that installed version actually provides it, and verify it disables scripts, form submissions, embedded child frames and external resource requests before browser inspection. Check navigation destinations separately. A pending PR is not a released capability. -If that protection is unavailable, leave the scaffold unopened. Make a separate local visual concept in a directory containing only authored static HTML, local CSS and local assets. Include no SDK/config scripts, forms, frames, event handlers, remote assets or payment navigation. Put this policy first in each page's ``, and label every page **Commerce unconfigured — visual concept only**: +If that protection is unavailable, leave the scaffold unopened. Make a separate local visual concept in a directory containing only authored static HTML, local CSS and local assets. Include no SDK/config scripts, forms, embedded frames, event handlers or remote assets. Remove external/payment links and redirect markup; navigation may only link to authored pages within the concept. Put this policy first in each page's ``, and label every page **Commerce unconfigured — visual concept only**: ```html ``` +The policy blocks resource requests and form submissions; it does not restrict ordinary link navigation, which must be removed or kept local in the authored markup. `frame-src` prevents this page from embedding frames. Preventing another site from embedding this page requires hosting response headers: `frame-ancestors` is [not supported in a meta policy](https://www.w3.org/TR/CSP3/#meta-element). Media and manifest requests fall back to `default-src 'none'`; worker requests fall back to `script-src 'none'`. Keep the concept self-contained: CDN styles/fonts and remote images will be blocked, so use local assets for visual review. + Serve only that concept directory on loopback. Inspect its source before opening, then check rendered output and network activity at desktop and mobile widths. Record visual defects and limitations. This concept can communicate design and proposed navigation; it is not the connected campaign or payment QA. Do not remove runtime wiring from an existing campaign to make this separate preview. ## Connect the approved implementation when ready @@ -105,7 +120,7 @@ The public [next-campaigns-create skill](https://github.com/NextCommerceCo/skill Use [next-campaigns-setup](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) for Page Kit configuration. The [AI skills guide](https://developers.nextcommerce.com/docs/skills?ref=agent-setup) explains installation and version checks. Existing projects keep their own build procedure. Record Allowed Domains and payment-account linking as dependencies at their actual dashboard/API boundary. -When real references and intended behavior are known, use the installed Campaigns OS [agent entry](https://github.com/NextCommerceCo/campaigns-os/blob/main/AGENTS.md) to choose local-spec or saved-Map intake. Current authoring uses CampaignSpec v5: `select` chooses before payment, `checkout_step` collects a form step, and `checkout` takes payment. v4.2/v4.3 read compatibility does not make those old versions the authoring target. The [public multi-step examples](https://github.com/NextCommerceCo/campaign-cart-starter-templates/tree/main/docs/fixtures/campaign-specs) illustrate the roles; use the installed toolkit's routing projection rather than treating every example hint as an implemented runtime guarantee. +When real references and intended behavior are known, use the installed Campaigns OS [agent entry](https://github.com/NextCommerceCo/campaigns-os/blob/main/AGENTS.md) and [quick start](https://github.com/NextCommerceCo/campaigns-os#quick-start) to choose local-spec or saved-Map intake. Keep the same `npx --no-install campaigns-os` invocation from its installation directory. Its installed `--help` lists `start` intake and `next` continuation; follow that release's documented arguments for the artifact you actually have. Current authoring uses CampaignSpec v5: `select` chooses before payment, `checkout_step` collects a form step, and `checkout` takes payment. v4.2/v4.3 read compatibility does not make those old versions the authoring target. The [public multi-step examples](https://github.com/NextCommerceCo/campaign-cart-starter-templates/tree/main/docs/fixtures/campaign-specs) illustrate the roles; use the installed toolkit's routing projection rather than treating every example hint as an implemented runtime guarantee. Keep any saved-Map requirement that applies to the user's delivery process. Do not save a Map, publish a repo, deploy, submit an order or send analytics as a side effect of this local-preview procedure. Record what is authorized, then invoke the appropriate existing capability. A doctor/static pass, intercepted analytics request and vendor receipt are different evidence. State which was actually obtained. diff --git a/scripts/check-agent-surfaces.mjs b/scripts/check-agent-surfaces.mjs index 04e8661..ea84869 100644 --- a/scripts/check-agent-surfaces.mjs +++ b/scripts/check-agent-surfaces.mjs @@ -122,10 +122,12 @@ if (capabilityMap) { } // Agent setup: raw Markdown and human guide are generated from one source. +const setupSource = read(join(ROOT, 'content', 'agent-setup.md')); +check(setupSource !== null, 'content/agent-setup.md does not exist'); const setupPrompt = read(join(OUT, 'agent-setup', 'prompt.md')); check(setupPrompt !== null, 'out/agent-setup/prompt.md does not exist'); if (setupPrompt !== null) { - check(setupPrompt === readFileSync(join(ROOT, 'content', 'agent-setup.md'), 'utf8').trimEnd() + '\n', 'agent setup prompt differs from its canonical source'); + if (setupSource !== null) check(setupPrompt === setupSource.trimEnd() + '\n', 'agent setup prompt differs from its canonical source'); check(setupPrompt.startsWith('