diff --git a/.gitignore b/.gitignore index ab61d9bf..6fc7b7e2 100644 --- a/.gitignore +++ b/.gitignore @@ -24,8 +24,8 @@ out/ /content/docs/storefront/graphql/mutations/ /content/docs/campaigns/api/*/ /lib/generated/ -# Generated capability page (regenerated by npm run generate; source is content/capabilities.yaml) -/content/docs/capabilities/index.mdx +# Generated agent setup guide (regenerated by npm run generate; source is content/agent-setup.md) +/content/docs/agent-setup/index.mdx # Misc .DS_Store diff --git a/AGENTS.md b/AGENTS.md index a1f9d1fb..f3acf275 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent guide for developers.nextcommerce.com -This file is the navigation and evidence contract for an agent reading the Next Commerce developer documentation. It is not a setup script. Agent setup instructions will live at /agent-setup/prompt.md (tracked in developer-docs#45). +This file is the navigation and evidence contract for an agent reading the Next Commerce developer documentation. It is not a setup script. For setup, fetch and follow [the stable agent setup prompt](https://developers.nextcommerce.com/agent-setup/prompt.md). ## What this site is @@ -11,7 +11,7 @@ The sibling site, https://docs.nextcommerce.com, is the merchant and operator do ## Where to start - https://developers.nextcommerce.com/llms.txt is the page index for this site, with a one-line description per page and absolute URLs. It also lists the domain bundles. -- https://developers.nextcommerce.com/capabilities.json is the platform capability map: one record per capability with a stable id, the merchant and developer pages that document it, its Admin API operations, webhook events, skills, status, and the date its links were last verified. The readable form is https://developers.nextcommerce.com/docs/capabilities. Pages on both sites declare their ids in a `capability_ids` frontmatter field. +- https://developers.nextcommerce.com/capabilities.json is the platform capability map: one record per capability with a stable id, the merchant and developer pages that document it, its Admin API operations, webhook events, skills, status, and the date its links were last verified. Page relationships are derived from the URLs in the map. - Domain bundles at https://developers.nextcommerce.com/llms/.txt (`platform`, `admin-api`, `payments`, `campaigns`, `storefront`, `apps-webhooks`) are plain Markdown: the capability records for one domain followed by the full text of the developer pages they cite. Fetch the bundle for your question before the full corpus. - https://developers.nextcommerce.com/llms-full.txt is the full corpus in one file. It is large (about 1.5 MB) and includes 500+ generated reference pages; fetch it only when a bundle or a page URL is not enough. - Raw OpenAPI specs, which are the authority for operations, parameters, and fields: diff --git a/app/agent-setup/prompt.md/route.ts b/app/agent-setup/prompt.md/route.ts new file mode 100644 index 00000000..529f9ebc --- /dev/null +++ b/app/agent-setup/prompt.md/route.ts @@ -0,0 +1,12 @@ +import setup from '@/lib/generated/agent-setup.json'; + +export const revalidate = false; + +export function GET() { + return new Response(setup.prompt, { + headers: { + 'Content-Type': 'text/markdown; charset=utf-8', + 'Cache-Control': 'public, max-age=3600, stale-while-revalidate=86400', + }, + }); +} diff --git a/app/docs/[[...slug]]/page.tsx b/app/docs/[[...slug]]/page.tsx index 00098a89..7b1b3587 100644 --- a/app/docs/[[...slug]]/page.tsx +++ b/app/docs/[[...slug]]/page.tsx @@ -11,7 +11,6 @@ import { getMDXComponents } from '@/components/mdx'; import { createRelativeLink } from 'fumadocs-ui/mdx'; import { VersionSelector } from '@/components/version-selector'; import { AutoExpandBody } from '@/components/auto-expand-body'; -import { CapabilityLinks } from '@/components/capability-links'; import type { Metadata } from 'next'; export default async function Page(props: { @@ -42,7 +41,6 @@ export default async function Page(props: { a: createRelativeLink(source, page), })} /> - ); diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx index ebba16b9..18f1e4c6 100644 --- a/app/docs/layout.tsx +++ b/app/docs/layout.tsx @@ -3,7 +3,7 @@ import { baseOptions } from '@/lib/layout.shared'; import { source } from '@/lib/source'; import { AlgoliaDocSearch, AlgoliaDocSearchMobile } from '@/components/search'; import type { ReactNode } from 'react'; -import { ChevronsLeftRightEllipsis, Megaphone, ShoppingBag, Puzzle, Webhook, Sparkles, FlaskConical, Map } from 'lucide-react'; +import { ChevronsLeftRightEllipsis, Megaphone, ShoppingBag, Puzzle, Webhook, Sparkles, FlaskConical } from 'lucide-react'; import type { SidebarTab } from 'fumadocs-ui/utils/get-sidebar-tabs'; const sectionMeta: Record = { @@ -42,11 +42,6 @@ const sectionMeta: Record, - description: 'Platform capability map', - color: 'bg-slate-500/15 text-slate-500', - }, }; export default function Layout({ children }: { children: ReactNode }) { diff --git a/app/evaluate/prompt.md/route.ts b/app/evaluate/prompt.md/route.ts new file mode 100644 index 00000000..3fd8650b --- /dev/null +++ b/app/evaluate/prompt.md/route.ts @@ -0,0 +1,12 @@ +import evaluation from '@/lib/generated/evaluation-prompt.json'; + +export const revalidate = false; + +export function GET() { + return new Response(evaluation.prompt, { + headers: { + 'Content-Type': 'text/markdown; charset=utf-8', + 'Cache-Control': 'public, max-age=3600, stale-while-revalidate=86400', + }, + }); +} diff --git a/app/llms.txt/route.ts b/app/llms.txt/route.ts index 870d8535..7ff1c534 100644 --- a/app/llms.txt/route.ts +++ b/app/llms.txt/route.ts @@ -67,13 +67,15 @@ function header(): string { `- [Merchant docs index](${MERCHANT_SITE}/llms.txt)`, `- [Platform and API changelog](${MERCHANT_SITE}/changelog): the developer portal has no changelog of its own`, `- [Capability map (JSON)](${SITE}/capabilities.json): one record per platform capability linking merchant guides, developer guides, Admin API operations, webhook events, and skills under a stable id`, - `- [Capability map (readable)](${SITE}/docs/capabilities)`, `- [Admin API spec, 2024-04-01](${SITE}/api/admin/2024-04-01.yaml): stable, raw OpenAPI`, `- [Admin API spec, unstable](${SITE}/api/admin/unstable.yaml): raw OpenAPI`, `- [Admin API spec, 2023-02-10](${SITE}/api/admin/2023-02-10.yaml): deprecated, raw OpenAPI`, `- [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`, + `- [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`, '', @@ -116,7 +118,7 @@ export function GET() { }); const body = keys - .map((key) => `## ${groupTitle(key)}\n\n${groups.get(key)!.join('\n')}\n`) + .map((key) => `## ${groupTitle(key)}\n\n${groups.get(key)!.sort((a, b) => a.localeCompare(b)).join('\n')}\n`) .join('\n'); return new Response(header() + '\n' + body, { diff --git a/app/not-found.tsx b/app/not-found.tsx index e9e0495d..6925faeb 100644 --- a/app/not-found.tsx +++ b/app/not-found.tsx @@ -15,7 +15,6 @@ export default function NotFound() {
  • Browse all docs
  • Admin API
  • Webhooks
    • -
  • Capability map
  • Merchant docs
  • Changelog
  • Agent index (llms.txt)
    • diff --git a/app/sitemap.ts b/app/sitemap.ts index 1487843c..43b1f3b0 100644 --- a/app/sitemap.ts +++ b/app/sitemap.ts @@ -8,6 +8,8 @@ const BASE_URL = 'https://developers.nextcommerce.com'; export default function sitemap(): MetadataRoute.Sitemap { return [ { url: BASE_URL, lastModified: new Date(), priority: 1.0 }, + { url: `${BASE_URL}/agent-setup/prompt.md`, priority: 0.8 }, + { url: `${BASE_URL}/evaluate/prompt.md`, priority: 0.8 }, ...source.getPages().map((page) => ({ url: `${BASE_URL}${page.url}`, lastModified: new Date(), diff --git a/components/capability-links.tsx b/components/capability-links.tsx deleted file mode 100644 index 6c03492e..00000000 --- a/components/capability-links.tsx +++ /dev/null @@ -1,55 +0,0 @@ -import { capabilitiesForPage, getCapability, MERCHANT_SITE, type Capability } from '@/lib/capabilities'; - -/** - * Reciprocal links from a developer page back to the merchant guides for the - * same capability. Driven entirely by the capability map: a page is linked when - * the map's developer_docs cite it or its frontmatter declares capability_ids. - */ -export function CapabilityLinks({ pageUrl, declaredIds }: { pageUrl: string; declaredIds?: string[] }) { - const byId = new Map(); - for (const c of capabilitiesForPage(pageUrl)) byId.set(c.id, c); - for (const id of declaredIds ?? []) { - const c = getCapability(id); - if (c) byId.set(c.id, c); - } - const capabilities = [...byId.values()]; - if (capabilities.length === 0) return null; - - // Several capabilities on one page can cite the same merchant guide; list it once. - const merchantLinks = [...new Set(capabilities.flatMap((c) => c.operator_docs))].map((url) => ({ url })); - - return ( - - ); -} diff --git a/content/agent-setup.md b/content/agent-setup.md new file mode 100644 index 00000000..bc172408 --- /dev/null +++ b/content/agent-setup.md @@ -0,0 +1,82 @@ + + +# Start a Campaign Page Kit project 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. + +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. + +## 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. + +## Use the current Campaign Page Kit workflow + +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: + +```bash +npm init -y +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: + +```bash +npx campaign-init --non-interactive --json \ + --template \ + --slug \ + --name "" \ + --ai-context +``` + +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` | +| OpenAI Codex | `codex` | +| Cursor | `cursor` | +| 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. + +## Verify only what was requested + +Run the static build: + +```bash +npm run build +``` + +Use the JSON emitted by `campaign-init` and the generated project files to confirm that: + +- 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/`. + +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. + +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. + +## Report back + +Tell the user: + +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. diff --git a/content/capabilities.yaml b/content/capabilities.yaml index 88e010df..cce00db2 100644 --- a/content/capabilities.yaml +++ b/content/capabilities.yaml @@ -14,12 +14,12 @@ # event, skill, bundle, or enum value. # # Record fields -# id stable, kebab-case; consumed by page frontmatter (capability_ids) on both sites +# id stable, kebab-case; used by the JSON map and domain bundles # title human name # summary one to three sentences of plain prose an agent can quote # audiences subset of [merchant, developer] # operator_docs merchant-site paths (absolute URLs are generated) -# developer_docs developer-site paths; must exist under content/docs after generation +# developer_docs developer-site paths, with the best entry page first; every path must exist # api_operations "tag:" selectors and/or operationIds from the stable Admin API spec # webhooks event names from the spec, or the single word "all" # skills skill names from the AI Skills page @@ -178,7 +178,16 @@ capabilities: - /docs/admin-api/guides/payment-methods/sepa-debit - /docs/admin-api/guides/payment-methods/swish - /docs/admin-api/guides/payment-methods/twint - api_operations: [tag:payments] + api_operations: + - gatewayGroupsList + - gatewayGroupsRetrieve + - gatewaysList + - gatewaysRetrieve + - transactionsList + - transactionsVerifyCreate + - transactionsRetrieve + - transactionsCaptureCreate + - transactionsRefundCreate webhooks: [gateway.created, gateway.updated, transaction.created, transaction.updated] skills: [] status: available @@ -197,7 +206,16 @@ capabilities: - /docs/analytics/disputes-reports developer_docs: - /docs/apps/guides/dispute-service - api_operations: [] + api_operations: + - disputesList + - disputesCreate + - disputesRetrieve + - disputesUpdate + - disputesPartialUpdate + - disputesDestroy + - disputesNotesList + - disputesNotesCreate + - disputesResolveCreate webhooks: [dispute.created, dispute.updated] skills: [] status: available @@ -383,9 +401,8 @@ capabilities: accounts.29next.com), the X-29next-API-Version and X-29Next-Signature headers, and the API key namespace. These are current, in use on every store, and not scheduled to change. Use them exactly as written. - audiences: [merchant, developer] - operator_docs: - - /docs/start-here/get-started + audiences: [developer] + operator_docs: [] developer_docs: - /docs/admin-api - /docs/webhooks diff --git a/content/docs/admin-api/guides/exports.mdx b/content/docs/admin-api/guides/exports.mdx index fcd884a9..5c66007b 100644 --- a/content/docs/admin-api/guides/exports.mdx +++ b/content/docs/admin-api/guides/exports.mdx @@ -1,7 +1,6 @@ --- title: API Exports description: Generate, poll, and download CSV data exports through the Admin API, with available export types and the export.created webhook -capability_ids: [admin-api] sidebar_label: Exports sidebar_position: 3 tags: diff --git a/content/docs/admin-api/guides/external-checkout.mdx b/content/docs/admin-api/guides/external-checkout.mdx index bd72bafa..657a8ba6 100644 --- a/content/docs/admin-api/guides/external-checkout.mdx +++ b/content/docs/admin-api/guides/external-checkout.mdx @@ -1,7 +1,6 @@ --- title: External Checkout Flow description: Create carts and orders from an external checkout through the Admin API, including upsells, line items, and payment details -capability_ids: [orders] sidebar_label: External Checkout Flow sidebar_position: 1 tags: diff --git a/content/docs/admin-api/guides/order-management.mdx b/content/docs/admin-api/guides/order-management.mdx index 185cad48..ab408740 100644 --- a/content/docs/admin-api/guides/order-management.mdx +++ b/content/docs/admin-api/guides/order-management.mdx @@ -1,7 +1,6 @@ --- title: API Order Management description: Edit order line items, refund, update shipping addresses, manage fulfillment orders, add tracking, and cancel orders through the Admin API -capability_ids: [orders] sidebar_label: Order Management sidebar_position: 1 tags: diff --git a/content/docs/admin-api/guides/payment-methods/affirm.mdx b/content/docs/admin-api/guides/payment-methods/affirm.mdx index da6d7872..6005a263 100644 --- a/content/docs/admin-api/guides/payment-methods/affirm.mdx +++ b/content/docs/admin-api/guides/payment-methods/affirm.mdx @@ -1,7 +1,6 @@ --- title: Affirm Admin API Guide description: Create Admin API orders paid with Affirm using the redirect payment flow, payment_return_url, and payment_complete_url -capability_ids: [payments-gateways] sidebar_label: Affirm sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/payment-methods/afterpay.mdx b/content/docs/admin-api/guides/payment-methods/afterpay.mdx index 79a7ae95..c238eecd 100644 --- a/content/docs/admin-api/guides/payment-methods/afterpay.mdx +++ b/content/docs/admin-api/guides/payment-methods/afterpay.mdx @@ -1,7 +1,6 @@ --- title: Afterpay Admin API Guide description: Create Admin API orders paid with Afterpay (Clearpay in the UK) using the redirect payment flow, with upsell and subscription limitations -capability_ids: [payments-gateways] sidebar_label: Afterpay tags: - Guide diff --git a/content/docs/admin-api/guides/payment-methods/apple-pay.mdx b/content/docs/admin-api/guides/payment-methods/apple-pay.mdx index 5f86abc1..fd0443c5 100644 --- a/content/docs/admin-api/guides/payment-methods/apple-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/apple-pay.mdx @@ -1,7 +1,6 @@ --- title: Apple Pay Admin API Guide description: Create Admin API orders paid with Apple Pay using the redirect payment flow, including standard and one-click checkout options -capability_ids: [payments-gateways] sidebar_label: Apple Pay sidebar_position: 3 tags: diff --git a/content/docs/admin-api/guides/payment-methods/bancontact.mdx b/content/docs/admin-api/guides/payment-methods/bancontact.mdx index f1cb3bd1..efe86b88 100644 --- a/content/docs/admin-api/guides/payment-methods/bancontact.mdx +++ b/content/docs/admin-api/guides/payment-methods/bancontact.mdx @@ -1,7 +1,6 @@ --- title: Bancontact Admin API Guide description: Create Admin API orders paid with Bancontact using the redirect payment flow, payment_return_url, and payment_complete_url -capability_ids: [payments-gateways] sidebar_label: Bancontact sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/payment-methods/bankcard.mdx b/content/docs/admin-api/guides/payment-methods/bankcard.mdx index ce920c08..a7f1e848 100644 --- a/content/docs/admin-api/guides/payment-methods/bankcard.mdx +++ b/content/docs/admin-api/guides/payment-methods/bankcard.mdx @@ -1,7 +1,6 @@ --- title: Bankcard description: Charge tokenized bankcards on the Admin API with card_token, including gateway routing, iFrame card tokenization, and 3D Secure (3DS2) -capability_ids: [payments-gateways] sidebar_label: Bankcard sidebar_position: 2 tags: diff --git a/content/docs/admin-api/guides/payment-methods/google-pay.mdx b/content/docs/admin-api/guides/payment-methods/google-pay.mdx index a0a42ebb..becc299c 100644 --- a/content/docs/admin-api/guides/payment-methods/google-pay.mdx +++ b/content/docs/admin-api/guides/payment-methods/google-pay.mdx @@ -1,7 +1,6 @@ --- title: Google Pay Admin API Guide description: Create Admin API orders paid with Google Pay using the redirect payment flow, including standard and one-click checkout options -capability_ids: [payments-gateways] sidebar_label: Google Pay sidebar_position: 3 tags: diff --git a/content/docs/admin-api/guides/payment-methods/ideal.mdx b/content/docs/admin-api/guides/payment-methods/ideal.mdx index 8b7e4384..dba17201 100644 --- a/content/docs/admin-api/guides/payment-methods/ideal.mdx +++ b/content/docs/admin-api/guides/payment-methods/ideal.mdx @@ -1,7 +1,6 @@ --- title: iDEAL Admin API Guide description: Create Admin API orders paid with iDEAL using the redirect payment flow, payment_return_url, and payment_complete_url -capability_ids: [payments-gateways] sidebar_label: iDEAL sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/payment-methods/index.mdx b/content/docs/admin-api/guides/payment-methods/index.mdx index e640da49..e3e531c8 100644 --- a/content/docs/admin-api/guides/payment-methods/index.mdx +++ b/content/docs/admin-api/guides/payment-methods/index.mdx @@ -1,7 +1,6 @@ --- title: Payment Methods description: Capability matrix of Admin API payment methods by flow type, express checkout, upsell, and subscription support, with links to each guide -capability_ids: [payments-gateways] sidebar_label: Payment Methods tags: - Guide diff --git a/content/docs/admin-api/guides/payment-methods/klarna.mdx b/content/docs/admin-api/guides/payment-methods/klarna.mdx index b04e079b..c6eed0d4 100644 --- a/content/docs/admin-api/guides/payment-methods/klarna.mdx +++ b/content/docs/admin-api/guides/payment-methods/klarna.mdx @@ -1,7 +1,6 @@ --- title: Klarna Admin API Guide description: Create Admin API orders paid with Klarna using the redirect payment flow, with support for one-click upsells and subscription items -capability_ids: [payments-gateways] sidebar_label: Klarna sidebar_position: 4 tags: diff --git a/content/docs/admin-api/guides/payment-methods/link.mdx b/content/docs/admin-api/guides/payment-methods/link.mdx index 21deff87..97d24ea2 100644 --- a/content/docs/admin-api/guides/payment-methods/link.mdx +++ b/content/docs/admin-api/guides/payment-methods/link.mdx @@ -1,7 +1,6 @@ --- title: Link Admin API Guide description: Create Admin API orders paid with Link via Stripe using the redirect payment flow, with support for one-click upsells and subscription items -capability_ids: [payments-gateways] sidebar_label: Link sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/payment-methods/paypal.mdx b/content/docs/admin-api/guides/payment-methods/paypal.mdx index aa73533a..aa458de9 100644 --- a/content/docs/admin-api/guides/payment-methods/paypal.mdx +++ b/content/docs/admin-api/guides/payment-methods/paypal.mdx @@ -1,7 +1,6 @@ --- title: PayPal Admin API Guide description: Create Admin API orders paid with PayPal using the redirect payment flow, with one-click upsells via Reference Transactions -capability_ids: [payments-gateways] sidebar_label: PayPal sidebar_position: 3 tags: diff --git a/content/docs/admin-api/guides/payment-methods/sepa-debit.mdx b/content/docs/admin-api/guides/payment-methods/sepa-debit.mdx index b69f3b6c..29588aa5 100644 --- a/content/docs/admin-api/guides/payment-methods/sepa-debit.mdx +++ b/content/docs/admin-api/guides/payment-methods/sepa-debit.mdx @@ -1,7 +1,6 @@ --- title: SEPA Direct Debit Admin API Guide description: Create Admin API orders paid with SEPA Direct Debit using the redirect payment flow, payment_return_url, and payment_complete_url -capability_ids: [payments-gateways] sidebar_label: SEPA Direct Debit sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/payment-methods/swish.mdx b/content/docs/admin-api/guides/payment-methods/swish.mdx index 659d8200..5f224f8a 100644 --- a/content/docs/admin-api/guides/payment-methods/swish.mdx +++ b/content/docs/admin-api/guides/payment-methods/swish.mdx @@ -1,7 +1,6 @@ --- title: Swish Admin API Guide description: Create Admin API orders paid with Swish through NEXT Payments for Swedish SEK checkouts using the redirect payment flow -capability_ids: [payments-gateways] sidebar_label: Swish tags: - Guide diff --git a/content/docs/admin-api/guides/payment-methods/twint.mdx b/content/docs/admin-api/guides/payment-methods/twint.mdx index d6d424ae..6fb42535 100644 --- a/content/docs/admin-api/guides/payment-methods/twint.mdx +++ b/content/docs/admin-api/guides/payment-methods/twint.mdx @@ -1,7 +1,6 @@ --- title: Twint Admin API Guide description: Create Admin API orders paid with Twint via NEXT Payments using the redirect payment flow, with support for one-click upsells and subscription items -capability_ids: [payments-gateways] sidebar_label: Twint sidebar_position: 5 tags: diff --git a/content/docs/admin-api/guides/subscription-management.mdx b/content/docs/admin-api/guides/subscription-management.mdx index c94bec2e..baa1aaee 100644 --- a/content/docs/admin-api/guides/subscription-management.mdx +++ b/content/docs/admin-api/guides/subscription-management.mdx @@ -1,7 +1,6 @@ --- title: API Subscription Management description: Create, update, pause, cancel, renew, and retry subscriptions through the Admin API, including line item, schedule, payment, and bulk operations -capability_ids: [subscriptions] sidebar_label: Subscription Management sidebar_position: 1 tags: diff --git a/content/docs/admin-api/guides/testing-guide.mdx b/content/docs/admin-api/guides/testing-guide.mdx index 5169401e..b5215fed 100644 --- a/content/docs/admin-api/guides/testing-guide.mdx +++ b/content/docs/admin-api/guides/testing-guide.mdx @@ -1,7 +1,6 @@ --- title: Test Order Flows description: Test cards, test card tokens, and the test gateway for creating test orders, transactions, and subscriptions on the Admin API -capability_ids: [testing] sidebar_label: Testing Guide sidebar_position: 1 tags: diff --git a/content/docs/admin-api/index.mdx b/content/docs/admin-api/index.mdx index 88eab585..7f28afc7 100644 --- a/content/docs/admin-api/index.mdx +++ b/content/docs/admin-api/index.mdx @@ -1,7 +1,6 @@ --- title: Admin API description: Admin API authentication with OAuth apps and access tokens, API versioning with the X-29next-API-Version header, and rate limits -capability_ids: [admin-api, legacy-identifiers] sidebar_label: Admin API sidebar_position: 5 --- diff --git a/content/docs/admin-api/permissions.md b/content/docs/admin-api/permissions.md index 9d786e8f..21dd4ff2 100644 --- a/content/docs/admin-api/permissions.md +++ b/content/docs/admin-api/permissions.md @@ -1,7 +1,6 @@ --- title: Permissions description: OAuth app scopes that control read and write access to Admin API resources such as orders, carts, subscriptions, and webhooks -capability_ids: [admin-api] sidebar_label: Permissions sidebar_position: 2 --- diff --git a/content/docs/agent-setup/meta.json b/content/docs/agent-setup/meta.json new file mode 100644 index 00000000..f4a4d1c4 --- /dev/null +++ b/content/docs/agent-setup/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Agent setup", + "pages": ["index"] +} diff --git a/content/docs/apps/app-development-flow.mdx b/content/docs/apps/app-development-flow.mdx index 2c8d01e6..498ae3b1 100644 --- a/content/docs/apps/app-development-flow.mdx +++ b/content/docs/apps/app-development-flow.mdx @@ -1,7 +1,6 @@ --- title: Development Flow description: How app changes reach development stores automatically and production stores through versioned releases created in your Partner account -capability_ids: [apps] sidebar_position: 3 --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/app-kit.mdx b/content/docs/apps/app-kit.mdx index 92978193..5b0d483f 100644 --- a/content/docs/apps/app-kit.mdx +++ b/content/docs/apps/app-kit.mdx @@ -1,7 +1,6 @@ --- title: App Kit description: Install the next-app-kit Python package and use nak setup, nak build, and nak push to bundle and push app files to Next Commerce -capability_ids: [apps] sidebar_label: App Kit sidebar_position: 7 tags: diff --git a/content/docs/apps/assets.mdx b/content/docs/apps/assets.mdx index 660b833d..3a12147b 100644 --- a/content/docs/apps/assets.mdx +++ b/content/docs/apps/assets.mdx @@ -3,7 +3,6 @@ title: Assets Reference sidebar_label: Assets sidebar_position: 4 description: The asset directory is meant to contain any static assets needed for your app, such as images, css, or javascript that is referenced in your app snippets. -capability_ids: [apps] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/event-tracking.mdx b/content/docs/apps/event-tracking.mdx index 6fa15e37..871222ff 100644 --- a/content/docs/apps/event-tracking.mdx +++ b/content/docs/apps/event-tracking.mdx @@ -1,7 +1,6 @@ --- title: Event Tracking description: Map a JavaScript file as storefront_event_tracker in manifest.json and read app settings from app.settings inside the tracker -capability_ids: [apps] sidebar_position: 5 --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/guides/dispute-service.mdx b/content/docs/apps/guides/dispute-service.mdx index f1e9c627..b8d3b745 100644 --- a/content/docs/apps/guides/dispute-service.mdx +++ b/content/docs/apps/guides/dispute-service.mdx @@ -1,7 +1,6 @@ --- title: Dispute Service Apps description: Build a server-to-server app that creates, matches, refunds, and resolves payment disputes with the Admin API and transaction.created webhooks -capability_ids: [disputes] sidebar_position: 1 tags: - Guide diff --git a/content/docs/apps/guides/fulfillment-service.mdx b/content/docs/apps/guides/fulfillment-service.mdx index f4dfbf56..086fda25 100644 --- a/content/docs/apps/guides/fulfillment-service.mdx +++ b/content/docs/apps/guides/fulfillment-service.mdx @@ -1,7 +1,6 @@ --- title: Fulfillment Service Apps description: Build a fulfillment service app that accepts fulfillment requests, creates full or partial fulfillments, handles cancellations, and syncs stock -capability_ids: [fulfillment] sidebar_position: 2 tags: - Guide diff --git a/content/docs/apps/guides/marketing-attribution.mdx b/content/docs/apps/guides/marketing-attribution.mdx index 19d94eac..bd309c0c 100644 --- a/content/docs/apps/guides/marketing-attribution.mdx +++ b/content/docs/apps/guides/marketing-attribution.mdx @@ -1,7 +1,6 @@ --- title: Marketing Attribution Apps description: Capture ad platform identifiers as cart attribution metadata with an event tracker and read them from order.created webhooks -capability_ids: [apps] sidebar_position: 3 tags: - Guide diff --git a/content/docs/apps/guides/server-to-server-apps.mdx b/content/docs/apps/guides/server-to-server-apps.mdx index 15883611..817f82ee 100644 --- a/content/docs/apps/guides/server-to-server-apps.mdx +++ b/content/docs/apps/guides/server-to-server-apps.mdx @@ -1,7 +1,6 @@ --- title: Server to Server Apps description: Create a Partner account app, configure its OAuth URLs, and test the install flow on a development store with OAuth Debugger -capability_ids: [apps] sidebar_position: 0 tags: - Guide diff --git a/content/docs/apps/guides/storefront-extension.mdx b/content/docs/apps/guides/storefront-extension.mdx index e1aa3461..048b50ef 100644 --- a/content/docs/apps/guides/storefront-extension.mdx +++ b/content/docs/apps/guides/storefront-extension.mdx @@ -1,7 +1,6 @@ --- title: Storefront Extension Apps description: App file layout, manifest.json, and using App Kit to set up, build, and push an app that extends storefront themes -capability_ids: [apps] sidebar_position: 0 tags: - Guide diff --git a/content/docs/apps/index.mdx b/content/docs/apps/index.mdx index a0c4b11c..07fc1051 100644 --- a/content/docs/apps/index.mdx +++ b/content/docs/apps/index.mdx @@ -1,7 +1,6 @@ --- title: Apps description: How apps extend Next Commerce with webhooks, the Admin API, event tracking, and snippets, with links to example apps and reference guides -capability_ids: [apps] sidebar_title: Apps --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/manifest.mdx b/content/docs/apps/manifest.mdx index db0e4b8e..9ec9d0e7 100644 --- a/content/docs/apps/manifest.mdx +++ b/content/docs/apps/manifest.mdx @@ -1,7 +1,6 @@ --- title: Manifest Reference description: "manifest.json properties for storefront apps: storefront_event_tracker, locations for app snippets, and settings_schema" -capability_ids: [apps] sidebar_label: Manifest sidebar_position: 3 --- diff --git a/content/docs/apps/oauth/getting-started.mdx b/content/docs/apps/oauth/getting-started.mdx index 6fddb198..346cc975 100644 --- a/content/docs/apps/oauth/getting-started.mdx +++ b/content/docs/apps/oauth/getting-started.mdx @@ -1,7 +1,6 @@ --- title: Getting Started with OAuth description: Authorize a server-side app with the OAuth 2.0 authorization code flow and exchange the code for an Admin API access token -capability_ids: [apps] sidebar_position: 1 --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/oauth/index.mdx b/content/docs/apps/oauth/index.mdx index 44c8caf0..e31fba6f 100644 --- a/content/docs/apps/oauth/index.mdx +++ b/content/docs/apps/oauth/index.mdx @@ -1,7 +1,6 @@ --- title: OAuth Overview description: How the OAuth 2.0 authorization code flow issues Admin API access tokens for server-side apps, with the install flow step by step -capability_ids: [apps] sidebar_position: 2 --- diff --git a/content/docs/apps/oauth/install-flows.md b/content/docs/apps/oauth/install-flows.md index 0f45bc85..37b57205 100644 --- a/content/docs/apps/oauth/install-flows.md +++ b/content/docs/apps/oauth/install-flows.md @@ -1,7 +1,6 @@ --- title: Install Flows description: Build install links for private apps with client_id and what changes when an app is published as a public app -capability_ids: [apps] sidebar_position: 6 --- diff --git a/content/docs/apps/oauth/session-auth.mdx b/content/docs/apps/oauth/session-auth.mdx index cd1ec097..c7f405e9 100644 --- a/content/docs/apps/oauth/session-auth.mdx +++ b/content/docs/apps/oauth/session-auth.mdx @@ -1,7 +1,6 @@ --- title: Session Token Overview description: Verify short-lived JWT session tokens sent from the store dashboard using your app client ID and client secret -capability_ids: [apps] sidebar_position: 2 --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/apps/review.mdx b/content/docs/apps/review.mdx index 0cc84062..221eb287 100644 --- a/content/docs/apps/review.mdx +++ b/content/docs/apps/review.mdx @@ -1,7 +1,6 @@ --- title: Submitting an App for Review description: Checklist for submitting an app for review and how the review process decides whether it is published to the App store -capability_ids: [apps] sidebar_label: Review & Publishing sidebar_position: 8 --- diff --git a/content/docs/apps/settings.mdx b/content/docs/apps/settings.mdx index 5e8a1411..e0cf273e 100644 --- a/content/docs/apps/settings.mdx +++ b/content/docs/apps/settings.mdx @@ -1,7 +1,6 @@ --- title: Settings Reference description: Define app settings in settings_schema, read them from app.settings in snippets, and reference for setting attributes and input types -capability_ids: [apps] sidebar_label: Settings sidebar_position: 6 --- diff --git a/content/docs/apps/snippets.mdx b/content/docs/apps/snippets.mdx index 4a55c04c..cca94f29 100644 --- a/content/docs/apps/snippets.mdx +++ b/content/docs/apps/snippets.mdx @@ -1,7 +1,6 @@ --- title: Snippets description: HTML template snippets that extend storefront themes through app_hook locations, using the same syntax as theme templates -capability_ids: [apps] sidebar_label: Snippets sidebar_position: 5 --- diff --git a/content/docs/campaigns/admin-api/index.mdx b/content/docs/campaigns/admin-api/index.mdx index 4cdac398..8fef8104 100644 --- a/content/docs/campaigns/admin-api/index.mdx +++ b/content/docs/campaigns/admin-api/index.mdx @@ -1,7 +1,6 @@ --- title: Campaigns Admin API description: Set up and manage campaigns programmatically instead of clicking through the dashboard. -capability_ids: [campaigns] tags: - Guide --- diff --git a/content/docs/campaigns/api/index.mdx b/content/docs/campaigns/api/index.mdx index 015600cf..f8d55f99 100644 --- a/content/docs/campaigns/api/index.mdx +++ b/content/docs/campaigns/api/index.mdx @@ -1,7 +1,6 @@ --- title: Campaign Cart API description: "Campaign Cart API for external checkout funnels: session tracking, calculate cart, create cart, create order, upsells, and order retrieval" -capability_ids: [campaigns] sidebar_label: Campaign Cart API sidebar_position: 1 --- diff --git a/content/docs/campaigns/index.mdx b/content/docs/campaigns/index.mdx index 2f261a5c..b59b4600 100644 --- a/content/docs/campaigns/index.mdx +++ b/content/docs/campaigns/index.mdx @@ -1,7 +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 -capability_ids: [campaigns] --- import { Callout } from 'fumadocs-ui/components/callout'; import { CampaignFunnelFlow, CampaignAnatomy } from '@/components/campaign-concepts-flow'; diff --git a/content/docs/campaigns/page-kit.mdx b/content/docs/campaigns/page-kit.mdx index af0ee8a8..39a52fb9 100644 --- a/content/docs/campaigns/page-kit.mdx +++ b/content/docs/campaigns/page-kit.mdx @@ -1,7 +1,6 @@ --- title: Page Kit description: Build, preview, and deploy multiple campaign funnels from a single repo. -capability_ids: [campaigns] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/campaigns/templates.mdx b/content/docs/campaigns/templates.mdx index 9fb0eb07..e03cf5dd 100644 --- a/content/docs/campaigns/templates.mdx +++ b/content/docs/campaigns/templates.mdx @@ -1,7 +1,6 @@ --- title: Templates description: The starter templates you can install with page kit, get your campaign up and running in minutes. -capability_ids: [campaigns] --- ## Introduction diff --git a/content/docs/capabilities/meta.json b/content/docs/capabilities/meta.json deleted file mode 100644 index a11b05ff..00000000 --- a/content/docs/capabilities/meta.json +++ /dev/null @@ -1 +0,0 @@ -{ "root": true, "title": "Capabilities", "icon": "Map", "description": "Platform capability map", "pages": ["index"] } diff --git a/content/docs/index.mdx b/content/docs/index.mdx index f7aabfdd..d4abee34 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -54,7 +54,7 @@ Campaigns and storefronts are the customer-facing layer — both produce orders -Install [**Next Commerce AI Skills**](/docs/skills) so your coding agent (Claude Code, Cursor, Codex, Copilot, …) knows the platform — APIs, CLI workflows, and architecture patterns — and can work autonomously on your store. One command: `npx skills add NextCommerceCo/skills`. +Already decided to start a new Campaign Page Kit project? The [**Campaign agent quickstart**](/docs/agent-setup) gives your coding agent a thin wrapper around the current CLI while preserving your template, route, and project choices. For reusable guidance across platform tasks, use [**Next Commerce AI Skills**](/docs/skills). @@ -158,4 +158,3 @@ Use apps to package an integration as an installable unit that works across mult - [Server-to-server guide](/docs/apps/guides/server-to-server-apps) - [Storefront extension guide](/docs/apps/guides/storefront-extension) - [Webhooks](/docs/webhooks) - diff --git a/content/docs/meta.json b/content/docs/meta.json index b227f45c..63e127ea 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -7,7 +7,7 @@ "apps", "webhooks", "skills", - "testing", - "capabilities" + "agent-setup", + "testing" ] } diff --git a/content/docs/skills/index.mdx b/content/docs/skills/index.mdx index 2c9af782..798a2184 100644 --- a/content/docs/skills/index.mdx +++ b/content/docs/skills/index.mdx @@ -1,7 +1,6 @@ --- title: AI Skills description: Pre-built skills that give AI coding agents deep knowledge of the Next Commerce platform. -capability_ids: [agent-skills] --- import { Callout } from 'fumadocs-ui/components/callout'; @@ -9,6 +8,8 @@ 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. + ## Install The simplest path is the [`skills` CLI](https://github.com/vercel-labs/skills) — it pulls `SKILL.md` files from a GitHub repo and drops them into the right config directory for whichever assistant you use. The target agent is auto-detected by default. diff --git a/content/docs/storefront/checkout-links.mdx b/content/docs/storefront/checkout-links.mdx index 930899c4..29f11f74 100644 --- a/content/docs/storefront/checkout-links.mdx +++ b/content/docs/storefront/checkout-links.mdx @@ -1,7 +1,6 @@ --- title: Checkout Links description: URL parameters for pre-loading a store's checkout with products, vouchers, currency, and marketing attribution -capability_ids: [checkout-links] --- Checkout Links allow you add links from any website, email or web marketing channel directly to your store's checkout flow with items pre-loaded in their cart. diff --git a/content/docs/storefront/event-tracking.mdx b/content/docs/storefront/event-tracking.mdx index 7921d15b..e45d8502 100644 --- a/content/docs/storefront/event-tracking.mdx +++ b/content/docs/storefront/event-tracking.mdx @@ -1,7 +1,6 @@ --- title: Event Tracking description: Subscribe to storefront customer events with JavaScript event trackers, the init context helper, and the available event payloads -capability_ids: [storefront-themes] sidebar_label: Event Tracking sidebar_position: 3 --- diff --git a/content/docs/storefront/graphql/index.mdx b/content/docs/storefront/graphql/index.mdx index 4aefdeb8..aafb264e 100644 --- a/content/docs/storefront/graphql/index.mdx +++ b/content/docs/storefront/graphql/index.mdx @@ -1,7 +1,6 @@ --- title: Storefront GraphQL API description: Storefront GraphQL API endpoint, session authentication, GraphiQL explorer, and the cart, product, voucher, and account operations -capability_ids: [storefront-themes] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/storefront/index.md b/content/docs/storefront/index.md index 4cf5cd60..ae90cf34 100644 --- a/content/docs/storefront/index.md +++ b/content/docs/storefront/index.md @@ -1,7 +1,6 @@ --- title: Storefront description: "Overview of the storefront developer tools: themes, event tracking, and the Storefront GraphQL API" -capability_ids: [storefront-themes] --- The Next Commerce storefront is a flexible, customizable front-end layer for your ecommerce business. Whether you're building a completely custom storefront or enhancing an existing theme, this section will guide you through the tools and features available to developers. diff --git a/content/docs/storefront/themes/cdn-and-caching.mdx b/content/docs/storefront/themes/cdn-and-caching.mdx index 9032b631..50328288 100644 --- a/content/docs/storefront/themes/cdn-and-caching.mdx +++ b/content/docs/storefront/themes/cdn-and-caching.mdx @@ -3,7 +3,6 @@ sidebar_label: CDN & Caching sidebar_position: 2 title: Storefront CDN & Caching description: How storefront asset CDN, full page caching, and template caching work, and why to verify theme changes on the network domain -capability_ids: [storefront-themes] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/storefront/themes/guides/custom-page-templates.mdx b/content/docs/storefront/themes/guides/custom-page-templates.mdx index 812c675d..ff6f92d5 100644 --- a/content/docs/storefront/themes/guides/custom-page-templates.mdx +++ b/content/docs/storefront/themes/guides/custom-page-templates.mdx @@ -1,7 +1,6 @@ --- title: Custom Page Templates description: Create page..html templates in templates/pages that extend the default page template and select them in the dashboard -capability_ids: [storefront-themes] sidebar_label: Custom Page Templates tags: - Guide diff --git a/content/docs/storefront/themes/guides/custom-product-templates.mdx b/content/docs/storefront/themes/guides/custom-product-templates.mdx index 977b6615..b49e3c54 100644 --- a/content/docs/storefront/themes/guides/custom-product-templates.mdx +++ b/content/docs/storefront/themes/guides/custom-product-templates.mdx @@ -1,7 +1,6 @@ --- title: Custom Product Templates description: Create product..html templates in templates/catalogue that extend the default product template and select them per product -capability_ids: [storefront-themes] sidebar_label: Custom Product Templates tags: - Guide diff --git a/content/docs/storefront/themes/guides/personalized-products.mdx b/content/docs/storefront/themes/guides/personalized-products.mdx index cb0aaaff..89bcd570 100644 --- a/content/docs/storefront/themes/guides/personalized-products.mdx +++ b/content/docs/storefront/themes/guides/personalized-products.mdx @@ -1,7 +1,6 @@ --- title: Personalized Products Guide description: "Capture customer input as line item properties with properties[] inputs, show them in the cart, and pass them via the Storefront GraphQL API" -capability_ids: [storefront-themes] sidebar_label: Personalized Products tags: - Guide diff --git a/content/docs/storefront/themes/guides/product-metadata.md b/content/docs/storefront/themes/guides/product-metadata.md index 65129163..3b9379aa 100644 --- a/content/docs/storefront/themes/guides/product-metadata.md +++ b/content/docs/storefront/themes/guides/product-metadata.md @@ -1,7 +1,6 @@ --- title: Product Metadata description: Render custom product metadata fields in theme templates with product.metadata. -capability_ids: [storefront-themes] sidebar_label: Product Metadata tags: - Guide diff --git a/content/docs/storefront/themes/guides/product-variants.mdx b/content/docs/storefront/themes/guides/product-variants.mdx index 4eea7206..00604bff 100644 --- a/content/docs/storefront/themes/guides/product-variants.mdx +++ b/content/docs/storefront/themes/guides/product-variants.mdx @@ -1,7 +1,6 @@ --- title: Product Variants Guide description: Render variant attribute selectors from variant_form and map choices to variant product IDs with the product.data JSON object -capability_ids: [storefront-themes] sidebar_label: Product Variants tags: - Guide diff --git a/content/docs/storefront/themes/index.mdx b/content/docs/storefront/themes/index.mdx index 90205254..940bfa70 100644 --- a/content/docs/storefront/themes/index.mdx +++ b/content/docs/storefront/themes/index.mdx @@ -1,7 +1,6 @@ --- title: Themes description: Theme directory structure for assets, configs, locales, layouts, partials, templates, and sass, plus an introduction to Theme Kit -capability_ids: [storefront-themes] sidebar_title: Themes sidebar_position: 0 --- diff --git a/content/docs/storefront/themes/settings.mdx b/content/docs/storefront/themes/settings.mdx index 68c08577..c193fa50 100644 --- a/content/docs/storefront/themes/settings.mdx +++ b/content/docs/storefront/themes/settings.mdx @@ -1,7 +1,6 @@ --- title: Theme Settings description: Define dashboard theme settings in settings_schema.json, read them in templates, and reference every schema input type -capability_ids: [storefront-themes] sidebar_label: Settings sidebar_position: 3 --- diff --git a/content/docs/storefront/themes/templates/filters.md b/content/docs/storefront/themes/templates/filters.md index 8170dd0a..f2c04fdf 100644 --- a/content/docs/storefront/themes/templates/filters.md +++ b/content/docs/storefront/themes/templates/filters.md @@ -1,7 +1,6 @@ --- title: 'Filter Reference' description: Built-in Django Template Language filters for lists, formatting, strings, currency, asset URLs, and math -capability_ids: [storefront-themes] --- ## Arrays & Lists diff --git a/content/docs/storefront/themes/templates/index.mdx b/content/docs/storefront/themes/templates/index.mdx index 98dc1c23..83918f81 100644 --- a/content/docs/storefront/themes/templates/index.mdx +++ b/content/docs/storefront/themes/templates/index.mdx @@ -1,7 +1,6 @@ --- title: Templates description: "Introduction to the Django Template Language used in storefront themes: variables, filters, and tags" -capability_ids: [storefront-themes] sidebar_position: 1 --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/storefront/themes/templates/objects.mdx b/content/docs/storefront/themes/templates/objects.mdx index 5f1762ca..2aae2480 100644 --- a/content/docs/storefront/themes/templates/objects.mdx +++ b/content/docs/storefront/themes/templates/objects.mdx @@ -1,7 +1,6 @@ --- title: Object Reference description: Global, page, and view-specific template objects available in storefront theme templates and their properties -capability_ids: [storefront-themes] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/storefront/themes/templates/tags.mdx b/content/docs/storefront/themes/templates/tags.mdx index 20d9a729..7354c35f 100644 --- a/content/docs/storefront/themes/templates/tags.mdx +++ b/content/docs/storefront/themes/templates/tags.mdx @@ -1,7 +1,6 @@ --- title: Tag Reference description: Built-in template tags for storefront themes, including extends, include, cart_form, app_hook, purchase_info_for_product, t, and url -capability_ids: [storefront-themes] sidebar_label: Tag Reference sidebar_position: 1 --- diff --git a/content/docs/storefront/themes/templates/urls-and-template-paths.mdx b/content/docs/storefront/themes/templates/urls-and-template-paths.mdx index e495688a..446fa83c 100644 --- a/content/docs/storefront/themes/templates/urls-and-template-paths.mdx +++ b/content/docs/storefront/themes/templates/urls-and-template-paths.mdx @@ -2,7 +2,6 @@ sidebar_label: URLs & Template Paths title: URLs & Template Paths description: Storefront URL names, URL paths, and the theme template path each built-in view renders -capability_ids: [storefront-themes] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/storefront/themes/theme-kit.mdx b/content/docs/storefront/themes/theme-kit.mdx index 53d8f13c..9f50489b 100644 --- a/content/docs/storefront/themes/theme-kit.mdx +++ b/content/docs/storefront/themes/theme-kit.mdx @@ -1,7 +1,6 @@ --- title: Theme Kit description: Install and configure ntk (Theme Kit), connect it to a store with an API key, and use its checkout, push, pull, watch, and sass commands -capability_ids: [storefront-themes] sidebar_label: Theme Kit sidebar_position: 4 tags: diff --git a/content/docs/storefront/themes/translations.mdx b/content/docs/storefront/themes/translations.mdx index a62b2eef..92332b3a 100644 --- a/content/docs/storefront/themes/translations.mdx +++ b/content/docs/storefront/themes/translations.mdx @@ -3,7 +3,6 @@ sidebar_label: Translations sidebar_position: 2 title: Translations description: Localize theme templates with the t tag, locale JSON files, variable arguments, and cardinal and ordinal pluralization -capability_ids: [storefront-themes] --- Theme templates can be fully localized with translations so that your store visitors are shown content in their local language. Use the t (translation) tag in your templates to access string translations in the locale files. Learn more about the [t tag](/docs/storefront/themes/templates/tags#t) and theme Locale files. diff --git a/content/docs/testing/index.mdx b/content/docs/testing/index.mdx index f8dd56e0..68ce36fc 100644 --- a/content/docs/testing/index.mdx +++ b/content/docs/testing/index.mdx @@ -1,7 +1,6 @@ --- title: Testing description: Test checkout, orders, subscriptions, and webhooks on a live store without moving real money -capability_ids: [testing] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/docs/webhooks/index.mdx b/content/docs/webhooks/index.mdx index b22b7ca3..598632d4 100644 --- a/content/docs/webhooks/index.mdx +++ b/content/docs/webhooks/index.mdx @@ -1,7 +1,6 @@ --- title: Webhooks description: Use webhooks to be notified about events that happen in your store. -capability_ids: [webhooks, legacy-identifiers] --- import { Callout } from 'fumadocs-ui/components/callout'; diff --git a/content/evaluate-next.md b/content/evaluate-next.md new file mode 100644 index 00000000..c54f7f76 --- /dev/null +++ b/content/evaluate-next.md @@ -0,0 +1,38 @@ + + +# Evaluate Next Commerce from its primary documentation + +You are helping a prospect decide whether Next Commerce fits their business and implementation. Ground the evaluation in the current public documentation. Do not rely on prior model knowledge or fill documentation gaps with assumptions. + +## Read in this order + +1. Fetch the [platform capability map](https://developers.nextcommerce.com/capabilities.json?ref=agent-evaluation). Use its stable capability IDs to plan the evaluation. +2. Fetch the [platform overview bundle](https://developers.nextcommerce.com/llms/platform.txt?ref=agent-evaluation). +3. Fetch only the domain bundles needed for the prospect's question: [Admin API](https://developers.nextcommerce.com/llms/admin-api.txt?ref=agent-evaluation), [payments](https://developers.nextcommerce.com/llms/payments.txt?ref=agent-evaluation), [campaigns](https://developers.nextcommerce.com/llms/campaigns.txt?ref=agent-evaluation), [storefront](https://developers.nextcommerce.com/llms/storefront.txt?ref=agent-evaluation), or [apps and webhooks](https://developers.nextcommerce.com/llms/apps-webhooks.txt?ref=agent-evaluation). +4. Use the [merchant docs index](https://docs.nextcommerce.com/llms.txt?ref=agent-evaluation) for operator workflows and the [changelog](https://docs.nextcommerce.com/changelog?ref=agent-evaluation) for release and version claims. +5. Follow the specific page and reference links those sources cite. Do not fetch the full corpus unless the focused sources cannot answer the question. + +## Evidence rules + +- Cite every material claim with the public page URL that supports it. +- Separate documented current behavior, beta or deprecated behavior, and your own inference. +- Preserve current legacy technical identifiers such as `29next.store` hostnames and `X-29next-*` headers exactly as documented. +- Do not invent NEXT Payments processing rates. Public docs do not publish them. +- Do not claim a feature is unavailable only because one page omits it. Check the capability map, the relevant developer bundle, the merchant index, and the changelog first. +- State conflicts or stale-looking pages instead of silently choosing one. + +## Ask for context + +If the prospect has not provided it, ask for their current platform, storefront model, checkout or funnel requirements, order volume, subscription mix, payment gateways, fulfillment model, integration team, and desired migration timeline. Ask only for details that would change the recommendation. + +## Deliverable + +Return a concise evaluation with these sections: + +1. **Platform picture**: how storefronts, Campaigns, checkout, payments, orders, subscriptions, fulfillment, apps, webhooks, and the Admin API fit together. +2. **Capability fit**: what directly fits the prospect's needs, with evidence. +3. **Gaps and open questions**: what is missing, ambiguous, sales-gated, or needs validation. Include a subsection titled **What is not documented**. +4. **First pilot**: the smallest useful integration or campaign, the systems involved, safe test method, success criteria, and likely decision points. +5. **Sources**: the pages used, grouped by capability. + +Do not turn the evaluation into sales copy. The useful outcome is a sourced picture of what the platform can do, where it fits, and what the prospect should verify next. diff --git a/package.json b/package.json index c97ea82e..2a0aec2c 100644 --- a/package.json +++ b/package.json @@ -6,11 +6,12 @@ "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", + "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-api-docs": "node scripts/generate-api-docs.mjs", "generate-graphql-docs": "node scripts/generate-graphql-docs.mjs", "generate-stats": "node scripts/generate-stats.mjs", "generate-capability-map": "node scripts/generate-capability-map.mjs", + "generate-agent-setup": "node scripts/generate-agent-setup.mjs", "build:preview": "node scripts/build-preview.mjs", "validate-links": "npm run generate && node scripts/validate-links.mjs", "check-agent-surfaces": "node scripts/check-agent-surfaces.mjs", diff --git a/scripts/check-agent-surfaces.mjs b/scripts/check-agent-surfaces.mjs index 44f55c87..81941081 100644 --- a/scripts/check-agent-surfaces.mjs +++ b/scripts/check-agent-surfaces.mjs @@ -6,10 +6,13 @@ import { readFileSync, existsSync } from 'fs'; import { join, resolve, dirname } from 'path'; import { fileURLToPath } from 'url'; +import { load as loadYaml } from 'js-yaml'; const __dirname = dirname(fileURLToPath(import.meta.url)); const ROOT = resolve(__dirname, '..'); const OUT = join(ROOT, 'out'); +const capabilitySource = loadYaml(readFileSync(join(ROOT, 'content', 'capabilities.yaml'), 'utf8')); +const authoredCapabilities = Array.isArray(capabilitySource?.capabilities) ? capabilitySource.capabilities : []; const failures = []; function check(condition, message) { @@ -38,6 +41,12 @@ if (llms !== null) { ]) { check(llms.includes(needle), `llms.txt is missing ${JSON.stringify(needle)}`); } + const pageSections = llms.slice(llms.indexOf('\n## Overview\n')).split(/^## /m).slice(1); + for (const section of pageSections) { + const lines = section.split('\n').filter((line) => line.startsWith('- [')); + const sorted = [...lines].sort((a, b) => a.localeCompare(b)); + check(lines.every((line, index) => line === sorted[index]), `llms.txt section ${JSON.stringify(section.split('\n')[0])} is not sorted`); + } } // 404 page @@ -69,8 +78,8 @@ if (statsRaw !== null) { } } -// Capability map: the JSON served at /capabilities.json, its schema, and the -// readable page must exist and agree on ids. +// Capability map: the JSON served at /capabilities.json and its schema remain +// machine-readable surfaces. The former human-readable projection stays absent. const capPath = join(OUT, 'capabilities.json'); const capRaw = read(capPath); check(capRaw !== null, 'out/capabilities.json does not exist'); @@ -87,27 +96,76 @@ if (capabilityMap) { check(capabilityMap.version === 1, `capabilities.json version is ${capabilityMap.version}`); check(Array.isArray(capabilityMap.capabilities) && capabilityMap.capabilities.length >= 8, 'capabilities.json has fewer than 8 capabilities'); check(Array.isArray(capabilityMap.bundles) && capabilityMap.bundles.length === 6, 'capabilities.json does not list 6 bundles'); - const capPage = read(join(OUT, 'docs', 'capabilities.html')) ?? read(join(OUT, 'docs', 'capabilities', 'index.html')); - check(capPage !== null, 'out/docs/capabilities.html does not exist'); - if (capPage !== null) { - for (const c of capabilityMap.capabilities) { - check(capPage.includes(`id="${c.id}"`), `capability page has no anchor for ${c.id}`); - for (const url of c.operator_docs) check(capPage.includes(url), `capability page is missing merchant link ${url}`); - } + const payments = capabilityMap.capabilities.find((c) => c.id === 'payments-gateways'); + const disputes = capabilityMap.capabilities.find((c) => c.id === 'disputes'); + const authoredOperationIds = (id) => authoredCapabilities.find((c) => c.id === id)?.api_operations ?? []; + const outputOperationIds = (capability) => capability?.api_operations.map((operation) => operation.id) ?? []; + for (const capability of [payments, disputes]) { + const expected = authoredOperationIds(capability?.id); + const actual = outputOperationIds(capability); + check( + actual.length === expected.length && expected.every((id) => actual.includes(id)), + `${capability?.id ?? 'missing capability'} operations differ between capabilities.yaml and capabilities.json`, + ); } + check(!payments?.api_operations.some((op) => op.id.startsWith('disputes')), 'payments-gateways still contains dispute operations'); + check(disputes?.api_operations.every((op) => op.id.startsWith('disputes')), 'disputes contains a non-dispute operation'); + const capPage = read(join(OUT, 'docs', 'capabilities.html')) ?? read(join(OUT, 'docs', 'capabilities', 'index.html')); + check(capPage === null, 'out/docs/capabilities should not be built'); for (const c of capabilityMap.capabilities) { for (const url of c.developer_docs) { const rel = url.replace('https://developers.nextcommerce.com', ''); const html = read(join(OUT, `${rel}.html`)) ?? read(join(OUT, rel, 'index.html')); check(html !== null, `developer page ${rel} cited by ${c.id} was not built`); - // The reciprocal panel must appear on every cited developer page. - if (html !== null && c.operator_docs.length > 0) { - check(html.includes('Related merchant guides'), `developer page ${rel} has no reciprocal merchant-guide panel`); - } } } } +// Agent setup: raw Markdown and human guide are generated from one source. +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.startsWith('\n/.test(source)) { + throw new Error('content/agent-setup.md must start with a versioned, dated setup comment'); +} +if (/\]\(\//.test(source)) { + throw new Error('content/agent-setup.md must use absolute links'); +} +if (!/^\n/.test(evaluationSource)) { + throw new Error('content/evaluate-next.md must start with a versioned, dated evaluation comment'); +} +if (/\]\(\//.test(evaluationSource)) { + throw new Error('content/evaluate-next.md must use absolute links'); +} + +mkdirSync(generatedDir, { recursive: true }); +writeFileSync(join(generatedDir, 'agent-setup.json'), JSON.stringify({ prompt: source }, null, 2) + '\n'); +writeFileSync(join(generatedDir, 'evaluation-prompt.json'), JSON.stringify({ prompt: evaluationSource }, null, 2) + '\n'); + +const promptHeading = /^# Start a Campaign Page Kit project with an AI agent$/m; +const humanSource = source.replace(/^\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 +--- + +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. +\`\`\` + +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. + +${humanInstructions}`; + +mkdirSync(docsDir, { recursive: true }); +writeFileSync(join(docsDir, 'index.mdx'), guide); +console.log('Generated campaign agent quickstart, human guide, and evaluation prompt from canonical Markdown sources'); diff --git a/scripts/generate-capability-map.mjs b/scripts/generate-capability-map.mjs index 249fb8a5..82e8f30b 100644 --- a/scripts/generate-capability-map.mjs +++ b/scripts/generate-capability-map.mjs @@ -1,7 +1,7 @@ /** * Generates lib/generated/capabilities.json, the platform capability map served at - * /capabilities.json and consumed by the /llms/.txt routes, the capability - * page, and the merchant docs site. + * /capabilities.json and consumed by the /llms/.txt routes and the merchant + * docs site. * * Source: content/capabilities.yaml (hand-authored index; see its header comment). * Run after generate-api-docs.mjs, because developer page existence is checked @@ -18,7 +18,7 @@ * live by scripts/check-live-surfaces.mjs and by the merchant repo's own CI */ -import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'fs'; +import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync } from 'fs'; import { join, resolve, dirname } from 'path'; import { fileURLToPath } from 'url'; import { load as loadYaml } from 'js-yaml'; @@ -301,87 +301,11 @@ console.log( `${capabilities.reduce((n, c) => n + c.webhooks.length, 0)} webhook links`, ); -// ---- readable page ---------------------------------------------------------- -// content/docs/capabilities/index.mdx is generated (git-ignored) so the page and -// the JSON can never list different ids or links. meta.json beside it is committed. - -function mdxEscape(text) { - return text.replace(/[{}<>]/g, (ch) => ({ '{': '{', '}': '}', '<': '<', '>': '>' })[ch]); -} - -// Links to /docs pages stay site-relative so validate-links checks them; links to -// non-docs routes (JSON, specs, bundles) stay absolute, which the link validator -// cannot see and which agents copy verbatim. -function relative(url) { - return url.startsWith(`${DEVELOPER_SITE}/docs/`) ? url.slice(DEVELOPER_SITE.length) : url; +// Remove the generated human-readable page from checkouts that built an older +// version of this script. capabilities.json and the domain bundles are the agent +// surfaces; the machine taxonomy should not occupy the public docs navigation. +const obsoleteReadablePage = join(ROOT, 'content', 'docs', 'capabilities', 'index.mdx'); +if (existsSync(obsoleteReadablePage)) { + rmSync(obsoleteReadablePage); + console.log(`Removed obsolete ${obsoleteReadablePage}`); } - -const page = []; -page.push('---'); -page.push('title: Platform Capabilities'); -page.push('description: One record per platform capability linking merchant guides, developer guides, Admin API operations, webhook events, and AI agent skills under a stable id'); -page.push('full: true'); -page.push('---'); -page.push(''); -page.push(`This page and [capabilities.json](${DEVELOPER_SITE}/capabilities.json) are the same generated projection (${output.generated_at}) over the two documentation sites and the Admin API specification. Each capability has a stable id that pages on both sites declare in their frontmatter. Links, operations, and events come from the owning sources; when they disagree with this page, the guide, the [spec](${DEVELOPER_SITE}/api/admin/${specVersion}.yaml), or the [changelog](${MERCHANT_SITE}/changelog) wins.`); -page.push(''); -page.push(`Agents: fetch a [domain bundle](${DEVELOPER_SITE}/llms.txt) rather than this page when you need the prose behind a capability. The JSON schema is at [capabilities.schema.json](${DEVELOPER_SITE}/capabilities.schema.json).`); -page.push(''); -page.push('## Bundles'); -page.push(''); -page.push('| Bundle | Capabilities | Plain-text URL |'); -page.push('| --- | --- | --- |'); -for (const b of bundles) { - page.push(`| ${b.title} | ${b.capabilities.map((id) => `[${id}](#${id})`).join(', ')} | [${b.url.replace(DEVELOPER_SITE, '')}](${b.url}) |`); -} -page.push(''); -page.push('## Capabilities'); -page.push(''); -for (const c of capabilities) { - page.push(`### ${mdxEscape(c.title)} [#${c.id}]`); - page.push(''); - page.push(`\`id: ${c.id}\` · status: ${c.status} · audiences: ${c.audiences.join(', ')} · links verified ${c.last_verified}`); - page.push(''); - page.push(mdxEscape(c.summary)); - page.push(''); - for (const n of c.notes) page.push(`> ${mdxEscape(n)}`); - if (c.notes.length > 0) page.push(''); - if (c.operator_docs.length > 0) { - page.push('**Merchant guides**'); - page.push(''); - for (const u of c.operator_docs) page.push(`- [${u.replace(MERCHANT_SITE, 'docs.nextcommerce.com')}](${u})`); - page.push(''); - } - if (c.developer_docs.length > 0) { - page.push('**Developer guides**'); - page.push(''); - for (const u of c.developer_docs) page.push(`- [${relative(u)}](${relative(u)})`); - page.push(''); - } - if (c.api_operations.length > 0) { - page.push(`**Admin API operations (${c.api_operations.length}, version ${specVersion})**`); - page.push(''); - for (const op of c.api_operations) { - const text = `\`${op.method} ${op.path}\`${op.summary ? ` ${mdxEscape(op.summary)}` : ''}`; - page.push(op.url ? `- [${text}](${relative(op.url)})` : `- ${text}`); - } - page.push(''); - } - if (c.webhooks.length > 0) { - page.push(`**Webhook events (${c.webhooks.length})**`); - page.push(''); - for (const w of c.webhooks) page.push(w.url ? `- [\`${w.event}\`](${relative(w.url)})` : `- \`${w.event}\``); - page.push(''); - } - if (c.skills.length > 0) { - page.push('**AI agent skills**'); - page.push(''); - for (const s of c.skills) page.push(`- [${s.name}](${s.url})`); - page.push(''); - } -} - -const pageDir = join(ROOT, 'content', 'docs', 'capabilities'); -mkdirSync(pageDir, { recursive: true }); -writeFileSync(join(pageDir, 'index.mdx'), page.join('\n') + '\n'); -console.log(`Generated ${join(pageDir, 'index.mdx')}`); diff --git a/source.config.ts b/source.config.ts index 3864a9ed..4816ef1f 100644 --- a/source.config.ts +++ b/source.config.ts @@ -71,9 +71,8 @@ export const docs = defineDocs({ full: z.boolean().optional(), // Agent-retrieval metadata. `description` (from frontmatterSchema) is required // on every authored page by scripts/check-frontmatter.mjs; the fields below are - // optional and validated against the capability map by the same script. + // optional. audience: z.array(z.enum(['merchant', 'developer'])).optional(), - capability_ids: z.array(z.string()).optional(), status: z.enum(['available', 'beta', 'deprecated']).optional(), last_verified: z .string()