Repository navigation
docs: make the campaign agent guide the starting point - #72
next-devin wants to merge 2 commits into
Conversation
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
developer-docs | 3e1abeb | Commit Preview URL Branch Preview URL |
Nov 02 2026, 09:47 AM |
![kilo-code-bot[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Code Review SummaryStatus: 5 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (5 files)
Previous Findings Re-verifiedAll five findings from the prior review at
Verification NotesReviewed against Verified locally: the removed Not verified (no network access in this environment): reachability or current content of Not re-run: Fix these issues in Kilo Cloud Previous Review Summary (commit ac48618)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit ac48618)Status: 5 Issues Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
SUGGESTION
Files Reviewed (5 files)
Verification NotesReviewed against Verified locally: the Not verified (no network access in this environment): reachability of Fix these issues in Kilo Cloud Reviewed by minimax-m3 · Input: 79K · Output: 16.5K · Cached: 1.6M |
| <Callout type="info" title="Start or continue with your coding agent"> | ||
| Start with the [campaign agent guide](/docs/agent-setup). Give your agent a funnel URL, design, existing repository or saved Map. It can inspect, plan and prepare a local preview before store access is available, while preserving your builder and host. | ||
|
|
||
| For a new Page Kit campaign with commerce already configured, use the [Page Kit setup recipe](https://campaigns.nextcommerce.com/start/). The optional [Workspace](https://campaign-map.nextcommerce.com/) lets you plan visually and save a Map. The quick start below covers direct Page Kit scaffolding. |
There was a problem hiding this comment.
WARNING: "Page Kit setup recipe" mislabels campaigns.nextcommerce.com/start/, and contradicts the Workspace domain introduced in the same sentence
This URL was introduced as the Campaigns OS Start guide, and this repository documented what it does in that capacity:
- base commit
ce437eb: "The Campaigns OS Start guide also provides the Workspace/Map route." - PR docs: add Campaigns OS Start path #61 (
7504f93): "Start in the Campaigns OS Start guide: 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."
Both describe a plan-and-handoff flow centred on Workspace, not a Page Kit scaffolding recipe. Relabelling it "Page Kit setup recipe" — while pointing Workspace at a different domain (campaign-map.nextcommerce.com) in the very same sentence — leaves two mutually exclusive claims in one repo about where Workspace lives. If the page's function changed upstream, the older descriptions are now stale and should be corrected too; if it did not change, this label sends readers looking for a scaffolder where the page is a planner.
Note also that index.mdx:18, immediately below, describes the actual Page Kit CLI ("a CLI that scaffolds an SDK-ready starter template..."), so "Page Kit setup recipe" now names a third Page Kit entry point alongside the "Page Kit guide" and the "quick start" below it — with nothing stating how the three differ.
|
|
||
| Choose the continuation that fits your project: | ||
|
|
||
| - **New campaign:** inspect the source and prepare a local preview. Use the [Page Kit guide](/docs/campaigns/page-kit) for a new static project, or the [Page Kit setup recipe](https://campaigns.nextcommerce.com/start/) for a new static project with its campaign and offers already configured. |
There was a problem hiding this comment.
WARNING: The canonical agent prompt now routes agents to /start/ as a Page Kit scaffolding path, contradicting how this repo has documented that page
This bullet reaches /agent-setup/prompt.md, which scripts/check-agent-surfaces.mjs:130 asserts is served byte-for-byte from content/agent-setup.md. It is the surface an agent actually reads, and the one this PR exists to unify.
Per this repo's own history, https://campaigns.nextcommerce.com/start/ is a plan-and-handoff flow: "configure products and offers in the NEXT dashboard, use Workspace to map and save the plan and copy its Handoff, then give that Handoff to a developer or agent to build, preview, and run QA" (7504f93), and "also provides the Workspace/Map route" (ce437eb). Describing it as "the Page Kit setup recipe ... for a new static project with its campaign and offers already configured" tells an agent to look for a scaffolder and, more importantly, steers it away from the Workspace/Handoff route that the very next bullet ("Saved Map: open its Handoff in the Workspace") presents as the saved-Map entry point.
Please confirm what /start/ actually does now and name it accordingly — for example a Workspace/Map planning-and-handoff recipe — or drop the external link if the canonical prompt should not route agents there.
|
|
||
| These are the options you'll see at the `campaign-init` template picker. Each one installs a complete funnel into your project with SDK-ready checkout, cart, upsell, and receipt surfaces. Treat those commerce surfaces as runtime wiring: replace campaign-specific package IDs, offer codes, shipping methods, copy, assets, and routes, but avoid rebuilding the SDK-owned controls from scratch. | ||
|
|
||
| Compare families in the [template browser](https://campaigns.nextcommerce.com/templates/), which presents the [picker catalog](https://github.com/NextCommerceCo/campaign-cart-starter-templates/blob/main/templates.json) with previews and use cases. Keep the family an existing campaign already uses when it fits the change. |
There was a problem hiding this comment.
WARNING: The new "picker catalog" / "template browser" split is applied to only two of the four places that name these artifacts
This line and the canonical prompt (content/agent-setup.md:58) now distinguish the raw JSON ("picker catalog") from the browsable site ("template browser"). The two sibling pages that name the same file were not updated:
content/docs/campaigns/index.mdx:105— "Use the current catalog recommendations"content/docs/campaigns/index.mdx:296— "pick the family from the template catalog"content/docs/campaigns/page-kit.mdx:110— "pick the family from the template catalog"
So templates.json is now called "picker catalog", "current catalog" and "template catalog" depending on the page, and campaigns.nextcommerce.com/templates/ — the surface this line promotes — is never mentioned on either sibling page. A reader who lands on /docs/campaigns or /docs/campaigns/page-kit gets a third name and no pointer to the browser.
Since all three pages describe the same artifact, please settle on one label per artifact and apply it to all of them.
|
|
||
| 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. |
There was a problem hiding this comment.
SUGGESTION: The Workspace/Handoff continuation is not reconciled with the entry-point table directly above it
Adding "its Handoff provides the prompt for continuing with an agent" here creates a second, unranked way to resume a saved Map. The table row four lines up already routes that exact artifact elsewhere:
| Local CampaignSpec, saved Map or Build Packet | Identify the selected campaign and read existing intent/status | The Campaigns OS continuation command for that artifact |
and content/agent-setup.md:85 reinforces it: "use the installed Campaigns OS agent entry to choose local-spec or saved-Map intake; its --help lists start for intake and next for continuation."
An agent reading this file now has three mechanisms of unequal authority for the same artifact — the table's Campaigns OS continuation command, line 85's next command, and this new Handoff prompt — with no guidance on which applies when. Consider stating the precedence (for example, that the Handoff prompt is what a human pastes to begin a new session, while campaigns-os next continues an artifact in place).
Minor placement note: the paragraph currently sits after "These entries can join the same work at different points. Do not replay provisioning or scaffolding because a new session starts.", which closes the section. Moving it above that sentence, or into its own short subsection, would keep the definition with the entry points it describes.
| ### Offers | ||
|
|
||
| **Offers** are price mutation rules that apply when an order meets a condition. Two flavours: | ||
| Configure campaign discounts in [Campaigns App Offers & Discounts](https://docs.nextcommerce.com/docs/apps/campaigns-app/campaigns-offers-and-discounts). Use this setup when building with the SDK and campaign templates. Two flavours: |
There was a problem hiding this comment.
SUGGESTION: The Offers rewrite drops the only statement of how Offers relate to the SDK
The previous sentence told the reader what these rules are in platform terms: "These are the rules the SDK and campaign templates use for pricing and savings." The replacement — "Use this setup when building with the SDK and campaign templates" — only says where to configure them, and reads as a narrower condition on when the link matters.
The bullets below still define Offer and Code semantics, but nothing now says the SDK and the campaign templates read these same rules to price the cart and compute savings. If that relationship still holds, consider keeping it; if Offers & Discounts is really a separate merchant-side setup step, say so explicitly instead of leaving the reader to assume it is the SDK's pricing source.
Make the agent guide the first Campaigns navigation item and the general starting point for new builds, existing repositories and saved Maps. The guide links to the appropriate continuation, with the configured Page Kit recipe and optional Workspace clearly scoped.
Remove the conflicting Olympus default recommendation, show Apollo families first, and point template selection to the current catalog. Direct campaign pricing to Campaigns App Offers & Discounts.
Validation:
NEXT_TELEMETRY_DISABLED=1 npm run buildandnpm run checkpassed (agent surfaces, 71 authored-page frontmatter checks, markup and links; 0 link errors). Inspected the generated agent guide locally at mobile width.Related merchant documentation: NextCommerceCo/docs#80. This documentation work does not close or expand campaigns-os #716.