Consume the platform capability map: capability_ids, developer resources panel, checks

.github/workflows/ci.yml

@@ -19,6 +19,7 @@ jobs:
 
       - run: npm ci
 
+      # prebuild runs audit-developer-links, validate-links, and check-capabilities.
       - run: npm run build
 
       - run: npm run check-search-budget

AGENTS.md

@@ -12,6 +12,7 @@ accurate product docs while building on the platform.
 | Published release history | `content/changelog/` |
 | Live site (canonical rendered output) | [docs.nextcommerce.com](https://docs.nextcommerce.com) |
 | Admin API, Campaigns SDK, webhooks, themes, GraphQL | [developers.nextcommerce.com](https://developers.nextcommerce.com) — separate repo |
+| Which merchant and developer pages cover one capability | [capabilities.json](https://developers.nextcommerce.com/capabilities.json) ([readable](https://developers.nextcommerce.com/docs/capabilities)) — pages here declare their ids in `capability_ids` frontmatter; domain bundles at `https://developers.nextcommerce.com/llms/<bundle>.txt` |
 
 Start with `content/docs/index.mdx` and `content/docs/about-next.mdx` for platform
 overview, then follow the section structure under `content/docs/`.

app/docs/[[...slug]]/page.tsx

@@ -9,6 +9,7 @@ import { notFound } from 'next/navigation';
 import { getMDXComponents } from '@/components/mdx';
 import { createRelativeLink } from 'fumadocs-ui/mdx';
 import type { Metadata } from 'next';
+import { DeveloperResources } from '@/components/developer-resources';
 
 export default async function Page(props: {
   params: Promise<{ slug?: string[] }>;
@@ -25,6 +26,7 @@ export default async function Page(props: {
       <DocsDescription>{page.data.description}</DocsDescription>
       <DocsBody>
         <MDX components={getMDXComponents({ a: createRelativeLink(source, page) })} />
+        <DeveloperResources ids={page.data.capability_ids} />
       </DocsBody>
     </DocsPage>
   );

app/llms.txt/route.ts

@@ -1,6 +1,7 @@
 import { source } from '@/lib/source';
 import { siteConfig } from '@/lib/config';
 import { llms } from 'fumadocs-core/source/llms';
+import capabilityMap from '@/lib/capabilities.snapshot.json';
 
 export const dynamic = 'force-static';
 
@@ -26,6 +27,12 @@ export function GET() {
     '',
     index,
     '',
+    '## Capability map and domain bundles',
+    '',
+    `[capabilities.json](${capabilityMap.sources.developer_docs}/capabilities.json) ([readable](${capabilityMap.sources.developer_docs}/docs/capabilities)) links each platform capability to its merchant guides here, its developer guides, Admin API operations, webhook events, and skills under a stable id; pages on this site declare their ids in a \`capability_ids\` frontmatter field. Domain bundles are plain Markdown, one per domain:`,
+    '',
+    ...capabilityMap.bundles.map((b) => `- [${b.title}](${b.url}): ${b.intro}`),
+    '',
   ].join('\n');
 
   return new Response(body, {

app/not-found.tsx

@@ -4,6 +4,7 @@ const recoveryLinks = [
   { label: 'Browse all docs', href: '/docs' },
   { label: 'Changelog', href: '/changelog' },
   { label: 'Developer docs', href: 'https://developers.nextcommerce.com' },
+  { label: 'Capability map', href: 'https://developers.nextcommerce.com/docs/capabilities' },
   { label: 'Agent index (llms.txt)', href: '/llms.txt' },
 ];
 

components/developer-resources.tsx

@@ -0,0 +1,65 @@
+import capabilityMap from '@/lib/capabilities.snapshot.json';
+
+interface Capability {
+  id: string;
+  title: string;
+  developer_docs: string[];
+  api_operations: { id: string; method: string; path: string; url: string | null }[];
+  webhooks: { event: string; url: string | null }[];
+}
+
+const DEVELOPER_SITE: string = capabilityMap.sources.developer_docs;
+const capabilities = capabilityMap.capabilities as Capability[];
+const byId = new Map(capabilities.map((c) => [c.id, c]));
+
+/**
+ * Developer resources for the capabilities a merchant page declares in
+ * `capability_ids`. Driven by the capability map snapshot the developer site
+ * publishes, so the links here are the same ones the map and the developer
+ * pages carry back to this site.
+ */
+export function DeveloperResources({ ids }: { ids?: string[] }) {
+  const matched = (ids ?? []).map((id) => byId.get(id)).filter((c): c is Capability => Boolean(c));
+  if (matched.length === 0) return null;
+  const withCounts = matched.filter((c) => c.api_operations.length > 0 || c.webhooks.length > 0);
+
+  return (
+    <aside aria-label="Developer resources" className="mt-10 rounded-lg border bg-fd-card p-4 text-sm text-fd-card-foreground">
+      <p className="font-medium">
+        Developer resources for{' '}
+        {matched.map((c, i) => (
+          <span key={c.id}>
+            {i > 0 && ', '}
+            <a href={`${DEVELOPER_SITE}/docs/capabilities#${c.id}`} className="underline underline-offset-4">
+              {c.title}
+            </a>
+          </span>
+        ))}
+      </p>
+      <ul className="mt-2 list-disc pl-5">
+        {matched.flatMap((c) =>
+          c.developer_docs.map((url) => (
+            <li key={url}>
+              <a href={url} className="underline underline-offset-4">
+                {url.replace(DEVELOPER_SITE, 'developers.nextcommerce.com')}
+              </a>
+            </li>
+          )),
+        )}
+      </ul>
+      {withCounts.length > 0 && (
+        <p className="mt-2 text-fd-muted-foreground">
+          {withCounts
+            .map((c) => {
+              const parts: string[] = [];
+              if (c.api_operations.length > 0) parts.push(`${c.api_operations.length} Admin API operations`);
+              if (c.webhooks.length > 0) parts.push(`${c.webhooks.length} webhook events`);
+              return `${c.title}: ${parts.join(', ')}`;
+            })
+            .join('. ')}
+          . See the capability map for the full lists.
+        </p>
+      )}
+    </aside>
+  );
+}

content/docs/analytics/disputes-reports.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Disputes Reports"
 description: "Evaluate your payment Disputes across a multitude of aggregated metrics"
+capability_ids: [disputes]
 ---
 Dispute reports allow you to view and analyze [**payment disputes**](/docs/features/payments/disputes-guide), aggregated by a variety of dimensions. Choose **Filters** to narrow down the results by various metrics, and export the results by choosing **Download CSV**.
 

content/docs/analytics/subscription-performance.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Subscription Reports"
 description: "Track subscriptions by lifecycle status, recurring and lifetime value, and MRR, with forecast, retention, and recovery reports."
+capability_ids: [subscriptions]
 ---
 Subscriptions reports display the total number of subscriptions by each lifecycle status, the average recurring billing value, and the average lifetime subscription value.  Choose **Filters** to narrow down the results by other metrics, and export the results by choosing **Download CSV**.
 

content/docs/apps/campaigns-app/build-campaign-packages.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Build Campaign Packages"
 description: "Set up the sellable items for your custom checkouts and upsell paths"
+capability_ids: [campaigns]
 ---
 Campaigns App maps configurable **Packages** to the items for sale on your external custom checkout flow. A **Package** is best understood as a Product or Product Variant + base Package Price + optional subscription schedule.
 

content/docs/apps/campaigns-app/campaign-analytics.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Campaign Analytics"
 description: "Track the traffic and performance of your campaigns in detail"
+capability_ids: [campaigns]
 ---
 To set up Campaign Analytics on a custom funnel, open the campaign, select **Developer**, and find the **Session Tracking** section.
 

content/docs/apps/campaigns-app/campaigns-offers-and-discounts.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Campaigns Offers & Discounts"
 description: "Create custom discounting codes and logic for Campaigns API"
+capability_ids: [campaigns]
 ---
 Campaigns App **Packages** represent the product or product variant identities for sale on your external custom checkout flow.
 

content/docs/apps/campaigns-app/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Campaigns App"
 description: "Connect custom checkouts to NEXT Campaigns API"
+capability_ids: [campaigns]
 ---
 Campaigns App simplifies and accelerates the deployment of custom marketing funnels and checkouts with Next Commerce's Campaigns API.
 

content/docs/build-a-store/storefront/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Storefront"
 description: "Your customer-facing web store - themes, content, reviews, and SEO"
+capability_ids: [storefront-themes]
 ---
 Your storefront is everything your customers see and interact with: the homepage, product pages, checkout, blog, support articles, and customer accounts.  Next Commerce storefronts are fully themed, localized, and managed directly from the dashboard.
 

content/docs/build-a-store/storefront/pages-and-assets.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Pages & Assets"
 description: "Create custom content pages and manage storefront media assets"
+capability_ids: [storefront-themes]
 ---
 ## Custom Pages
 

content/docs/build-a-store/storefront/themes.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Themes"
 description: "Install, customize, and manage your store's look and feel"
+capability_ids: [storefront-themes]
 ---
 Themes control the visual design and layout of your entire storefront, including the homepage, product pages, checkout, headers, footers, and customer account views.  Manage themes from the **Storefront > Themes** menu.
 

content/docs/build-a-store/technical-settings/configure-webhooks.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Configure Webhooks"
 description: "Integrate and extend to third party platforms with webhooks"
+capability_ids: [admin-api, webhooks]
 ---
 ## Webhooks
 

content/docs/features/fulfillment-guide/advanced-settings.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Advanced Settings"
 description: "Configure advanced fulfillment settings to customize your store"
+capability_ids: [fulfillment]
 ---
 ## Advanced **Fulfillment Settings**
 

content/docs/features/fulfillment-guide/fulfillment-statuses.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Fulfillment Statuses"
 description: "An overview fulfillment statuses for order line items"
+capability_ids: [fulfillment]
 ---
 ## Fulfillment Statuses
 

content/docs/features/fulfillment-guide/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Fulfillment Guide"
 description: "An overview of settings, locations, and concepts related to fulfillment"
+capability_ids: [fulfillment]
 ---
 Next Commerce offers a deep feature set related to order fulfillment.  This guide, and the pages that follow, offer an overview of fulfillment features.
 

content/docs/features/fulfillment-guide/location-based-routing.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Location-Based Routing"
 description: "Set up one or multiple fulfillment locations to orchestrate order fulfillment"
+capability_ids: [fulfillment]
 ---
 ## Multi-**Location Fulfillment**
 

content/docs/features/offers/shareable-coupon-links.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Shareable Coupon Links"
 description: "Share Storefront links with coupon codes pre-attached"
+capability_ids: [checkout-links]
 ---
 Make remarketing and discounting easy with Shareable Coupon Links.  Using these links with coupon codes pre-attached will automatically add the coupon code to a customer's cart during their shopping session.
 

content/docs/features/payments/3ds2-payments.mdx

@@ -1,6 +1,7 @@
 ---
 title: "3DS2 Payments"
 description: "Support 3D Secure 2 (3DS2) authentication for SCA-compliant card payments across NEXT's supported gateways, on storefront checkout and the Admin API."
+capability_ids: [payments-gateways]
 ---
 ## **3D Secure 2 Payments**
 

content/docs/features/payments/authorize-and-capture-payments.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Authorize & Capture Payments"
 description: "Pre-authorize a customer's payment card and capture funds later, automatically on shipment or manually, to reduce fees, fraud, and chargeback risk."
+capability_ids: [payments-gateways]
 ---
 By default, bankcard payment transactions charge the customer immediately.  In other words, the full amount of the payment is "captured" at the time of the transaction.  As an alternative payment flow, Next Commerce allows merchants to pre-authorize a customer's payment card,  then capture the funds later -  either automatically, at the time the order ships, or manually.
 

content/docs/features/payments/disputes-guide.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Disputes Guide"
 description: "Identify, manage, and resolve payment disputes"
+capability_ids: [disputes]
 ---
 ## Disputes
 

content/docs/features/payments/external-payment-methods.mdx

@@ -1,6 +1,7 @@
 ---
 title: "External Payment Methods"
 description: "Accept offline or custom payments and mark orders as paid via external methods"
+capability_ids: [payments-gateways]
 ---
 
 External Payment Methods allow store administrators to define custom payment options for scenarios where payment is collected outside of the standard online checkout flow. This is useful for accepting bank transfers, cash on delivery, invoiced payments, or any other offline or external payment arrangement.

content/docs/features/payments/gateways/next-payments.mdx

@@ -1,6 +1,7 @@
 ---
 title: "NEXT Payments"
 description: "Set up NEXT Payments, the built-in payment account for Next Commerce stores"
+capability_ids: [payments-gateways]
 ---
 NEXT Payments is the payment account built into Next Commerce. It is the only gateway offering the full range of alternative payment methods, and the only one where 3DS2 is configured for you.
 

content/docs/features/payments/gateways/test-gateway.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Test Gateway"
 description: "Place test orders without a live payment processor"
+capability_ids: [testing]
 ---
 The Test Gateway lets you place orders end to end without sending anything to a live processor. Use it to check checkout, offers, subscriptions, and fulfillment before going live.
 

content/docs/features/payments/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Payments Guide"
 description: "Set up and manage Gateways, Payment Apps, and more"
+capability_ids: [payments-gateways]
 ---
 ## Payment Gateways
 

content/docs/features/payments/payment-failure-cascading.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Payment Failure Cascading"
 description: "Re-attempt failed customer transactions to save checkouts"
+capability_ids: [payments-gateways]
 ---
 Merchants with more than one payment gateway may wish to support _cascading_ - ie. the immediate re-attempt of a failed bankcard transaction at checkout onto a secondary gateway.
 

content/docs/features/payments/risk-screening.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Risk Screening"
 description: "Set your risk tolerance and review blocked checkout attempts"
+capability_ids: [payments-gateways]
 ---
 ## Risk Screening
 

content/docs/features/payments/transaction-response-codes.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Transaction Response Codes"
 description: "Reference for all payment transaction response codes"
+capability_ids: [payments-gateways]
 ---
 Payment Transaction requests have many potential outcomes, with each gateway and processor having unique response codes.  Next Commerce codes and categorizes these into common response buckets, according to the following codes.
 

content/docs/manage/orders/collect-payments-on-orders.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Collect Payments on Orders"
 description: "Collect outstanding order balances by invoice, saved bankcard, new bankcard, or offline payment"
+capability_ids: [orders]
 ---
 When an order has an outstanding balance, merchants can collect the remaining amount from the Order Details view. This may happen after editing an order to add products or increase quantities, or when a previous payment attempt failed.
 

content/docs/manage/orders/test-orders.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Test Orders"
 description: "Create Test Orders with Test Order Cards"
+capability_ids: [orders, testing]
 ---
 Creating test orders is a very common exercise when testing new order confirmation designs, APIs, integrations, and other cases where you need to test your implementations.
 

content/docs/manage/subscriptions-guide/account-updater.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Account Updater"
 description: "Enroll to automatically update subscribers' expiring credit cards"
+capability_ids: [subscriptions]
 ---
 Recover revenue and avoid involuntary churn from your subscription customers by enrolling in Account Updater.
 

content/docs/manage/subscriptions-guide/cancellation-paths.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Cancellation Paths"
 description: "Standardized subscription cancellation reasons used across the platform"
+capability_ids: [subscriptions]
 ---
 
 ## Subscription Cancellation Reasons

content/docs/manage/subscriptions-guide/decline-salvage.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Decline Salvage"
 description: "Recover failed subscription renewal payments and retain customers with NEXT's automated retry capabilities."
+capability_ids: [subscriptions]
 ---
 ## Subscription Renewal Decline Salvage
 

content/docs/manage/subscriptions-guide/index.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Subscriptions Guide"
 description: "Learn about Subscription features and best practices for your store"
+capability_ids: [subscriptions]
 ---
 ## Subscriptions Overview
 

content/docs/manage/subscriptions-guide/managing-subscriptions.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Managing Subscriptions"
 description: "Manage individual subscriptions in your store"
+capability_ids: [subscriptions]
 ---
 ## Managing Subscriptions
 

content/docs/manage/subscriptions-guide/pause-subscriptions.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Pausing Subscriptions"
 description: "Pause and resume active subscriptions, including scheduled resume dates"
+capability_ids: [subscriptions]
 ---
 
 ## Subscription Pause

content/docs/manage/subscriptions-guide/subscription-phases.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Subscription Phases"
 description: "Schedule future changes to a subscription's items, pricing, shipping, and billing interval using phases"
+capability_ids: [subscriptions]
 ---
 
 ## Subscription Phases