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..239b230 100644 --- a/content/agent-setup.md +++ b/content/agent-setup.md @@ -1,23 +1,51 @@ - + -# 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) 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: the intended change, source URL or design, existing repo, campaign identity if known, build command, output directory, hosting method, and any saved brief, spec, Map or evidence. Preserve existing work; do not scaffold over an existing project. -## Use the current Campaign Page Kit workflow +Ask for missing business decisions together, such as target products, offer changes or which source design to follow, and keep inspecting and planning while answers or credentials are missing. Record installed versions and the source commit of any reused template or repo. For work that includes Campaigns OS, follow its [runtime guidance](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/runtime-readiness.md). -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: +Store access, repository publishing, deployment, test orders and analytics sends are separate effects; a source URL or API key authorizes none of them. Never print credentials or put them in the brief, handoff, committed files or command output. + +## 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 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 Campaigns OS continuation command for that artifact | + +These entries can join the same work at different points. Do not replay provisioning or scaffolding 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 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. + +Save presentation intent in the [Campaign Build Brief](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-build-brief.md) format (`schema_version: campaigns-os-build-brief/v1`, `brief_mode: guided`, `status: needs_answers`). In the project's README or handoff note, record the proposed page journey and the commerce dependencies: catalogue products and prices, packages, offers and shipping, page behavior, and the domains, payment linking and analytics still needed. 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 brief, spec and generated records before deriving intent from code; code shows what was implemented, not what the merchant wanted. If Campaign Cart is present, run the project's pinned Campaigns OS (or install it as the [quick start](https://github.com/NextCommerceCo/campaigns-os#quick-start) describes) and produce the [standardization report](https://github.com/NextCommerceCo/campaigns-os/blob/main/docs/campaign-standardization-report.md): + +```bash +npx campaigns-os standardize --target /path/to/existing-campaign --no-doctor --json +``` + +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. + +## 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 +53,7 @@ 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. - -For a non-interactive agent run, replace every placeholder below with the developer-confirmed value: +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: ```bash npx campaign-init --non-interactive --json \ @@ -35,10 +61,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 +72,28 @@ 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 [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. +The CLI owns scaffolding and conflict handling; preserve its failure output instead of recreating the scaffold by hand. A successful build writes `_site/`. -## Verify only what was requested +A scaffold made without a campaign key runs against the starter templates' demo campaign: the prices, cart and checkout it shows are the demo store's. Use it to review layout and flow, place no orders against it, and record in the handoff that the preview is demo-bound; it is not evidence about the merchant's campaign. Bind the real campaign with `npm run config` before any check that is meant to count, which needs the authorization steps below. The preview shows the stock template, not a rebuild of the source funnel. -Run the static build: +## Connect the approved implementation when ready -```bash -npm run build -``` +The [next-campaigns-create skill](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-create) creates, edits, adopts and clones Campaigns App configuration behind its plan-approval gate; it reads existing catalogue products, and missing products or prices need the [Admin API](https://developers.nextcommerce.com/docs/admin-api) or dashboard work. The Campaign Cart key and the Admin API token are different credentials. Use [next-campaigns-setup](https://github.com/NextCommerceCo/skills/tree/main/next-campaigns-setup) for Page Kit configuration; existing projects keep their own build procedure. -Use the JSON emitted by `campaign-init` and the generated project files to confirm that: +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; its `--help` lists `start` for intake and `next` for continuation. Current authoring is CampaignSpec v5: `select` chooses before payment, `checkout_step` collects a form step, and `checkout` takes payment, as the [public multi-step examples](https://github.com/NextCommerceCo/campaign-cart-starter-templates/tree/main/docs/fixtures/campaign-specs) show. -- 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/`. +Do not save a Map, publish a repo, deploy, submit an order or send analytics as a side effect of this procedure. Record what is authorized, then invoke the matching capability, and say which evidence was obtained: a doctor pass, an intercepted analytics request and a vendor receipt are different things. -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 README or existing handoff note and link the artifacts that exist rather than creating a second record. Include: -## Report back +1. The requested outcome, chosen implementation and host, source URLs or clone commit, and unresolved business questions. +2. Brief, spec, Map or Build Packet paths that exist; list absent artifacts as absent. Keep credentials out. +3. Installed tool and skill versions, working directory, build command and output directory. +4. Which commerce bindings are verified, missing or inherited, and which actions remain unauthorized. +5. The checks run, what they prove, outstanding defects, and the next local action or the specific missing input. -Tell the user: +A returning session reads that note, checks the current revision and installed versions, and resumes without resetting the project or replaying completed writes. Let Campaigns OS commands create their own stage records; never hand-write a passing Assembly Report or reuse a source campaign's QA 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 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..abe3db4 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. +Skipping the API key is fine for a look around: the scaffold runs against the starter templates' demo campaign, so the prices and checkout you see are the demo store's. Run `npm run config` to bind your campaign before testing anything that counts. ### 3. Start the dev server @@ -60,12 +60,12 @@ 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. -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) @@ -287,12 +287,14 @@ Two mechanisms skip tracking entirely — including the always-on internal `next `campaign-init` can run with no prompts — pass every value as a flag: +This example uses `apollo` for a single-step checkout; pick the family from the [template catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json). `CAMPAIGN_API_KEY` is the campaign's browser-visible Campaign Cart key, never an Admin API token. + ```bash npx campaign-init --non-interactive \ - --template olympus \ + --template apollo \ --slug my-campaign \ --name "My Campaign" \ - --api-key "$CAMPAIGN_API_KEY" \ + --api-key "${CAMPAIGN_API_KEY:?set CAMPAIGN_API_KEY first}" \ --ai-context claude ``` diff --git a/content/docs/campaigns/page-kit.mdx b/content/docs/campaigns/page-kit.mdx index 39a52fb..b68f7df 100644 --- a/content/docs/campaigns/page-kit.mdx +++ b/content/docs/campaigns/page-kit.mdx @@ -52,6 +52,8 @@ npm init -y npm install next-campaign-page-kit ``` +The `campaign-*` commands come from this installed dependency; run them from the project root, and in an existing project keep its pinned version. + ### 3. Run the setup script ```bash @@ -70,7 +72,7 @@ npx campaign-init 8. Optionally installs an **AI context doc** for your editor or agent -Get your Campaign API key from the Campaigns App in your store. You can skip this step during init and run `npm run config` later. +Get your Campaign API key from the Campaigns App in your store. You can skip it during init and run `npm run config` later. Until then the scaffold runs against the starter templates' demo campaign, so the prices and checkout you see are the demo store's. ### 4. Start the dev server @@ -105,12 +107,14 @@ npm run dev -c my-campaign -p 8080 # specific campaign and port `campaign-init` can run with no prompts. Pass every value as a flag and add `--non-interactive`: +These examples use `apollo` for a single-step checkout; pick the family from the [template catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json). `CAMPAIGN_API_KEY` is the campaign's browser-visible Campaign Cart key, never an Admin API token. + ```bash npx campaign-init --non-interactive \ - --template olympus \ + --template apollo \ --slug grounding-mat-v2 \ --name "Grounding Mat V2" \ - --api-key "$CAMPAIGN_API_KEY" \ + --api-key "${CAMPAIGN_API_KEY:?set CAMPAIGN_API_KEY first}" \ --ai-context claude ``` @@ -118,8 +122,8 @@ Add `--json` for agent-friendly automation — a single structured object on std ```bash npx campaign-init --json \ - --template olympus --slug grounding-mat-v2 --name "Grounding Mat V2" \ - --api-key "$CAMPAIGN_API_KEY" \ + --template apollo --slug grounding-mat-v2 --name "Grounding Mat V2" \ + --api-key "${CAMPAIGN_API_KEY:?set CAMPAIGN_API_KEY first}" \ --ai-context claude ``` 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..af2cfd3 100644 --- a/scripts/check-agent-surfaces.mjs +++ b/scripts/check-agent-surfaces.mjs @@ -122,14 +122,24 @@ 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) { + if (setupSource !== null) check(setupPrompt === setupSource.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}`;