@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-routing/SKILL.md

@@ -1,180 +1,123 @@
 ---
 name: sfnext-routing
-description: Implement file-based routing in Storefront Next with React Router 7. Use when adding new pages, creating layout routes, defining route parameters, or understanding route module exports (loader, action, component, meta). Covers flat-routes conventions, nested layouts, and the _app prefix.
+description: >-
+  Add and change pages in a Storefront Next project: flat-file routes in src/routes, layout routes (_app, _checkout, _empty), splat routes for product and category pages, action.* and resource.* routes, src/route-paths.ts (routes, resourceRoutes, routeHref), site-aware Link and useNavigate wrappers, SeoMeta and JsonLd head tags, multi-site /:siteId/:localeId URL prefixes, url.seoRoutes and excludeRoutes, extension routes, and the SLAS callback routes. Use for "add a page", "new route", "why is my link missing the site prefix", "route file naming", "redirect to login", or a 404 on a new URL. Do not use for loader/action/fetcher data code (use `storefront-next:sfnext-data-fetching`), shouldRevalidate (use `storefront-next:sfnext-revalidation`), SEO strategy such as sitemaps and canonical rules (use `storefront-next:sfnext-seo`), or Page Designer regions (use `storefront-next:sfnext-page-designer`).
 ---
 
-# Routing Skill
+# Storefront Next Routing
 
-This skill covers React Router 7 file-based routing in Storefront Next projects.
+Storefront Next uses React Router 7 framework mode with file-based routes. Every route module lives in `src/routes/`; the file name is the URL. Your project also ships `docs/README-MULTI-SITE.md` (URL prefix, locale and site detection) and `docs/README-SEO.md` (titles, meta tags, canonical URLs); read those for depth.
 
-## Overview
+## How routes are discovered
 
-Storefront Next uses React Router 7 in framework mode with flat-routes file conventions. Route files live in `src/routes/` and file names map directly to URL paths using dot (`.`) separators for nesting.
+`src/routes.ts` imports `flatRoutes` from `@salesforce/storefront-next-runtime/routing` (not `@react-router/fs-routes`). It is a drop-in wrapper that:
 
-## Route File Conventions
+1. scans `src/routes/` (test files are ignored),
+2. merges routes from `src/extensions/<name>/routes/` (see `storefront-next:sfnext-extensions`),
+3. wraps every route in the `app.url.prefix` pattern (default `/:siteId/:localeId`) through `src/app-wrapper.tsx`, and applies `app.url.seoRoutes` aliases to the product and category splats.
 
-### File Name to URL Mapping
+The two SLAS callback routes (`resource.slas-reset-password-callback.ts`, `resource.slas-passwordless-login-callback.ts`) are deliberately excluded from discovery in `src/routes.ts` and registered by hand at the bare paths `/reset-password-callback` and `/passwordless-login-callback`, outside the prefix, so a single callback URL works for all sites. If you add another server-to-server callback that cannot carry a site prefix, follow the same pattern in `src/routes.ts`.
 
-| File Name | URL Path | Notes |
-|-----------|----------|-------|
-| `_app.tsx` | — | Layout route (wraps child routes) |
-| `_app._index.tsx` | `/` | Home page (index of `_app` layout) |
-| `_app.product.$productId.tsx` | `/product/:productId` | Dynamic parameter |
-| `_app.category.$categoryId.tsx` | `/category/:categoryId` | Dynamic parameter |
-| `_app.cart.tsx` | `/cart` | Static route |
-| `_app.account.tsx` | `/account` | Layout for account pages |
-| `_app.account.orders.tsx` | `/account/orders` | Nested under account layout |
+## Route tree (what exists)
 
-### Naming Rules
+| Pattern | Files | Notes |
+|---|---|---|
+| `_app` layout | `_app.tsx` | header/footer shell; loads navigation; `shouldRevalidate` returns `false` |
+| Home, search, cart, wishlist | `_app._index.tsx`, `_app.search.tsx`, `_app.cart.tsx`, `_app.wishlist.tsx`, `_app.about-us.tsx` | |
+| Product detail | `_app.p.$.tsx` | splat; URL shape is build-time configurable (`url.seoRoutes`) |
+| Category / listing | `_app.c.$.tsx` | splat; URL shape is build-time configurable (`url.seoRoutes`) |
+| Account | `_app.account.tsx` (layout + auth guard), `_app.account.overview`, `.orders`, `.orders.$orderNo`, `.addresses`, `.payment-methods`, `.wishlist`, `.passkeys`, `.store-preferences` | |
+| Orders | `_app.order-confirmation.$orderNo.tsx`, `_app.order-lookup.*` (`results.$orderNo`, `verify.$orderNo`) | param is `$orderNo` |
+| `_checkout` layout | `_checkout.tsx`, `_checkout.checkout.tsx` | checkout chrome |
+| `_empty` layout | `_empty.tsx`, `_empty.login`, `.signup`, `.forgot-password`, `.reset-password`, `.logout`, `.maintenance`, `.oauth2.jwks`, `.preview.component`, `_empty.$.tsx` (catch-all) | no header/footer; there is no `_auth` layout |
+| Mutations | `action.*.ts(x)` (cart, wishlist, checkout, OTP, passkey, consent, site context...) | no UI; see `storefront-next:sfnext-data-fetching` |
+| Data endpoints | `resource.*.ts(x)` (recommendations, basket-products, category-products, analytics-proxy, `resource.api.client.$resource.ts`...) | no UI |
 
-- **Dots (`.`)** create path segments: `_app.product.tsx` maps to `/product`
-- **`$` prefix** marks dynamic parameters: `$productId` becomes `:productId`
-- **`_` prefix** marks layout routes (pathless): `_app.tsx` wraps children without adding a URL segment
-- **`_index`** matches the parent path exactly (index route)
+Naming rules (flat routes): `.` becomes `/`, `$name` is a param, `$` alone is a splat, a leading `_` segment is a pathless layout, `_index` is the index route. Pick the layout by prefix: `_app.` for standard pages, `_checkout.` for checkout, `_empty.` for header-less pages.
 
-See [Route Conventions Reference](references/ROUTE-CONVENTIONS.md) for the complete naming rules.
+## Add a page
 
-## Route Module Exports
-
-Each route file can export these values:
-
-### loader — Server-side data loading
+```tsx
+// src/routes/_app.shipping-policy.tsx  ->  /shipping-policy
+import type { Route } from './+types/_app.shipping-policy';
+import { SeoMeta } from '@/components/seo-meta';
+import { Link } from '@/components/link';
+import { routes } from '@/route-paths';
 
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-import type { LoaderFunctionArgs } from 'react-router';
+export async function loader({ request }: Route.LoaderArgs) {
+    return { pageUrl: new URL(request.url).href };
+}
 
-export function loader({ params, context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({
-            params: { path: { id: params.productId } }
-        }).then(({ data }) => data),
-    };
+export default function ShippingPolicy({ loaderData }: Route.ComponentProps) {
+    return (
+        <>
+            <SeoMeta title="Shipping policy" description="How we ship." openGraph={{ url: loaderData.pageUrl }} />
+            <h1>Shipping policy</h1>
+            <Link to={routes.cart}>Back to cart</Link>
+        </>
+    );
 }
 ```
 
-### action — Handle mutations (form submissions)
+Checklist for a new page:
 
-```typescript
-import { data, redirect } from 'react-router';
-import type { ActionFunctionArgs } from 'react-router';
+1. Create the file under `src/routes/` with the right layout prefix.
+2. Import types from `./+types/<file-name>` (`Route.LoaderArgs`, `Route.ComponentProps`, `Route.ActionArgs`). These are generated by `pnpm typecheck` (runs `react-router typegen`) and `pnpm dev`; run one if the import is unresolved.
+3. Add an entry to `routes` (page) or `resourceRoutes` (action/resource) in `src/route-paths.ts`. That file is the single source of truth for navigable paths. Keep it in sync when you rename or delete route files.
+4. Render `<SeoMeta>` (and `<JsonLd>` from `@/components/json-ld` for structured data) inside the component. React 19 hoists these tags to `<head>` and they work with streaming. Use `meta` exports only when a route already does.
+5. Add locale strings for user-facing text (`storefront-next:sfnext-i18n`) and a test next to the route (`storefront-next:sfnext-testing`).
 
-export async function action({ request, context }: ActionFunctionArgs) {
-    const formData = await request.formData();
-    // Handle mutation...
-    return data({ success: true });
-}
+## Links and navigation: always use the project wrappers
+
+```tsx
+import { Link, NavLink } from '@/components/link';
+import { useNavigate } from '@/hooks/use-navigate';
+import { href } from 'react-router';
+import { routes, routeHref, resourceRoutes } from '@/route-paths';
+
+<Link to={routes.cart}>Cart</Link>
+<Link to={routeHref(routes.accountOrderDetail, { orderNo })}>Order</Link>
 ```
 
-### default — Page component
+`Link`, `NavLink` and `useNavigate` from `@/components/link` and `@/hooks/use-navigate` apply the site/locale prefix (`buildUrl`). The React Router originals compile but silently produce unprefixed URLs that break multi-site routing. `AGENTS.md` makes this a hard rule.
 
-Components receive `loaderData` as props from the framework:
+For product and category URLs use the helpers in `@/route-paths` (`createProductUrl`, `createCategoryUrl`, `createCategoryNavigationUrl`) with the SEO URL context so links follow `url.seoRoutes`. In server code (redirects), use `buildUrlFromContext(routes.login, context)` from `@/lib/url.server`:
 
-```typescript
-import { Suspense } from 'react';
-import { Await } from 'react-router';
-import { SeoMeta } from '@/components/seo-meta';
+```ts
+import { redirect } from 'react-router';
+import { routes } from '@/route-paths';
+import { buildUrlFromContext } from '@/lib/url.server';
 
-export default function CategoryPage({ loaderData }: { loaderData: CategoryPageData }) {
-    // `category` is already resolved (awaited in loader)
-    // `products` is a Promise (streamed)
-    return (
-        <>
-            <SeoMeta
-                title={loaderData.category.name}
-                description={loaderData.category.pageDescription}
-            />
-            <h1>{loaderData.category.name}</h1>
-            <Suspense fallback={<ProductGridSkeleton />}>
-                <Await resolve={loaderData.products}>
-                    {(products) => <ProductGrid products={products} />}
-                </Await>
-            </Suspense>
-        </>
-    );
-}
+throw redirect(buildUrlFromContext(routes.login, context));
 ```
 
-For SEO metadata, use the `<SeoMeta />` component inside your page component (not a `meta` export).
+Form and fetcher `action` targets come from `resourceRoutes` (for example `resourceRoutes.cartItemAdd`), which are excluded from the site prefix via `app.url.excludeRoutes` in `config.server.ts` (`['/resource/**', '/action/**']` by default). A new `action.*` or `resource.*` route needs no prefix handling; a new page route gets it automatically.
 
-## Layout Routes
+## URL configuration
 
-Layout routes wrap child routes with shared UI (navigation, footer, etc.):
+`app.url` in `config.server.ts` (`prefix`, `excludeRoutes` and `seoRoutes` are protected config paths: set them in the file and rebuild, they cannot be overridden with `PUBLIC__` env vars; see `storefront-next:sfnext-configuration`) controls `prefix`, `excludeRoutes`, search-param mode, detection and `seoRoutes` (configurable product and category URL grammars). Changing the prefix or `seoRoutes` affects every link; follow `docs/README-MULTI-SITE.md` in your project rather than editing ad hoc.
 
-```typescript
-// src/routes/_app.tsx — Main app layout
-import { Outlet } from 'react-router';
+## Protecting routes
 
-export default function AppLayout() {
-    return (
-        <div>
-            <Header />
-            <main>
-                <Outlet />  {/* Child routes render here */}
-            </main>
-            <Footer />
-        </div>
-    );
-}
-```
+There is no `_auth` layout. Guard in the loader: read the session with `getAuth(context)` from `@/middlewares/auth.server` and `throw redirect(...)` to `routes.login` (see `_app.account.tsx` and `_app.wishlist.tsx`). Auth details: `storefront-next:sfnext-authentication`.
 
-### Adding a New Page
-
-1. Create a route file in `src/routes/`:
-   ```
-   src/routes/_app.wishlist.tsx    →  /wishlist
-   ```
-
-2. Export a `loader` for data and `default` for the component:
-   ```typescript
-   import { createApiClients } from '@/lib/api-clients';
-   import { SeoMeta } from '@/components/seo-meta';
-   import type { LoaderFunctionArgs } from 'react-router';
-
-   type WishlistPageData = {
-       wishlist: Promise<Wishlist>;
-   };
-
-   export function loader({ context }: LoaderFunctionArgs): WishlistPageData {
-       const clients = createApiClients(context);
-       return {
-           wishlist: clients.shopperCustomers.getWishlist({...}).then(({ data }) => data),
-       };
-   }
-
-   export default function WishlistPage({ loaderData }: { loaderData: WishlistPageData }) {
-       return (
-           <>
-               <SeoMeta title="My Wishlist" />
-               <Suspense fallback={<WishlistSkeleton />}>
-                   <Await resolve={loaderData.wishlist}>
-                       {(wishlist) => <div>{/* Render wishlist */}</div>}
-                   </Await>
-               </Suspense>
-           </>
-       );
-   }
-   ```
-
-## Resource Routes
-
-Routes that return data (no UI component):
-
-```typescript
-// src/routes/resource.api.client.$resource.tsx
-// Used by useScapiFetcher to execute SCAPI calls server-side
-export function loader({ params, context }: LoaderFunctionArgs) {
-    // Decode params, call SCAPI, return JSON
-}
-```
+## Rules to keep in mind
 
-## Related Skills
+- Only server `loader` and `action` exports are allowed; no `clientLoader`/`clientAction`.
+- Throw `new Response('...', { status: 404 })` for missing content so the right HTTP status reaches crawlers.
+- Resource routes called from the browser should reject cross-origin requests (see `resource.recommendations.ts` for the pattern).
+- Deeper references: [ROUTE-CONVENTIONS.md](references/ROUTE-CONVENTIONS.md) for exports and naming, [URLS-AND-SEO-ROUTES.md](references/URLS-AND-SEO-ROUTES.md) for prefixes and SEO aliases.
+
+## Finding more
 
-- `storefront-next:sfnext-data-fetching` - What happens inside loader and action functions
-- `storefront-next:sfnext-components` - Building page components with createPage
-- `storefront-next:sfnext-page-designer` - Page Designer routes with regions
+Read `AGENTS.md` in your project for the doc index. For other framework questions use `b2c docs search "storefront next routing"` (or the `docs_search` MCP tool).
 
-## Reference Documentation
+## Related Skills
 
-- [Route Conventions Reference](references/ROUTE-CONVENTIONS.md) - Complete naming rules and examples
+- `storefront-next:sfnext-data-fetching` - loaders, actions, fetchers
+- `storefront-next:sfnext-revalidation` - `shouldRevalidate` policy per route
+- `storefront-next:sfnext-seo` - canonical URLs, structured data, sitemaps
+- `storefront-next:sfnext-page-designer` - `@PageType` and regions on routes
+- `storefront-next:sfnext-extensions` - routes contributed by extensions
+- `storefront-next:sfnext-authentication` - sessions and login flows
+- `storefront-next:sfnext-overview` - architecture map

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-routing/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Add a new /shipping-policy page to my Storefront Next project with the standard header and footer", "should_trigger": true},
+  {"query": "My Link to the cart drops the /site/locale prefix in a multi-site storefront, how do I fix navigation?", "should_trigger": true},
+  {"query": "How do I stream non-critical data from a loader and avoid blocking the first byte?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-routing/references/ROUTE-CONVENTIONS.md

@@ -1,65 +1,65 @@
-# Route Conventions Reference
+# Route conventions
 
-## Flat Routes File Naming
+## File name to URL
 
-Storefront Next uses React Router 7's flat-routes convention where dots (`.`) in file names create URL path segments.
+| File | URL (before the site/locale prefix) |
+|---|---|
+| `_app._index.tsx` | `/` |
+| `_app.cart.tsx` | `/cart` |
+| `_app.account.orders.$orderNo.tsx` | `/account/orders/:orderNo` |
+| `_app.p.$.tsx` | product splat (shape set by `url.seoRoutes`; use `createProductUrl`) |
+| `_app.c.$.tsx` | category splat (shape set by `url.seoRoutes`; use `createCategoryUrl`) |
+| `_checkout.checkout.tsx` | `/checkout` |
+| `_empty.login.tsx` | `/login` |
+| `action.cart-item-add.tsx` | `/action/cart-item-add` |
+| `resource.recommendations.ts` | `/resource/recommendations` |
+| `resource.api.client.$resource.ts` | `/resource/api/client/:resource` |
 
-### Syntax Reference
+- A segment starting with `_` and no matching file content of its own is a pathless layout (`_app`, `_checkout`, `_empty`). The layout file (`_app.tsx`) renders `<Outlet />`.
+- A nested layout is a route file plus children, for example `_app.account.tsx` with `_app.account.overview.tsx` beneath it.
+- `.ts` is enough for routes without JSX (actions, resource routes, `_empty.logout.ts`).
+- Files named `*.test.ts(x)` beside routes are ignored by route discovery.
 
-| Syntax | Purpose | Example File | URL |
-|--------|---------|-------------|-----|
-| `.` | Path separator | `_app.product.tsx` | `/product` |
-| `$param` | Dynamic segment | `_app.product.$id.tsx` | `/product/:id` |
-| `_prefix` | Pathless layout | `_app.tsx` | (no URL segment) |
-| `_index` | Index route | `_app._index.tsx` | `/` (parent path) |
+## Route module exports
 
-### Common Route Patterns
+| Export | Purpose |
+|---|---|
+| `loader` | server data for the route (see `storefront-next:sfnext-data-fetching`) |
+| `action` | server mutation |
+| default component | receives `loaderData` via `Route.ComponentProps` |
+| `shouldRevalidate` | revalidation policy; most routes re-export from `@/lib/revalidation/routes/*` (see `storefront-next:sfnext-revalidation`) |
+| `middleware` | route-level server middleware (root chain lives in `src/root.tsx`) |
+| `ErrorBoundary` | route-scoped error UI (for example wishlist load failures) |
+| `links` / `meta` | mostly used in `src/root.tsx`; prefer `<SeoMeta>` in components |
+| Page Designer classes | `@PageType` and `@RegionDefinition` on an exported class, see `storefront-next:sfnext-page-designer` |
 
-```
-src/routes/
-├── _app.tsx                           # Layout: wraps all /app routes
-├── _app._index.tsx                    # /
-├── _app.product.$productId.tsx        # /product/:productId
-├── _app.category.$categoryId.tsx      # /category/:categoryId
-├── _app.cart.tsx                      # /cart
-├── _app.checkout.tsx                  # /checkout
-├── _app.account.tsx                   # Layout: wraps /account routes
-├── _app.account._index.tsx            # /account
-├── _app.account.orders.tsx            # /account/orders
-├── _app.account.orders.$orderId.tsx   # /account/orders/:orderId
-├── _app.search.tsx                    # /search
-├── _auth.tsx                          # Layout: auth pages
-├── _auth.login.tsx                    # /login
-├── _auth.register.tsx                 # /register
-└── resource.api.client.$resource.tsx  # Resource route (no UI)
-```
+`clientLoader` and `clientAction` are not permitted.
 
-### Layout Nesting
+## Typed route props
 
-```
-URL: /account/orders/12345
+```tsx
+import type { Route } from './+types/_app.cart';
 
-Route hierarchy:
-  _app.tsx                    (layout — renders Header, Footer, <Outlet />)
-    _app.account.tsx          (layout — renders account sidebar, <Outlet />)
-      _app.account.orders.$orderId.tsx  (page — renders order details)
+export async function loader({ request, context, params }: Route.LoaderArgs) { /* ... */ }
+export default function Cart({ loaderData }: Route.ComponentProps) { /* ... */ }
 ```
 
-## Route Module Exports
+The `+types` modules are generated. Run `pnpm typecheck` or `pnpm dev` to create them.
+
+## Layout notes
+
+- `_app.tsx` loads navigation categories once and exports `shouldRevalidate() { return false }`, so the header data is not re-fetched on later navigations. Change this only if you add navigation that must update.
+- `_empty.tsx` is a minimal `<main>` with a skip link, used by login, signup, callbacks, maintenance and the component preview.
+- `_checkout.tsx` provides the checkout layout.
+- `_app.account.tsx` is the account layout and redirects unauthenticated shoppers to login.
+
+## Head tags
 
-| Export | Type | When It Runs | Purpose |
-|--------|------|-------------|---------|
-| `loader` | Function | Server (SSR + SPA navigation) | Load data |
-| `action` | Function | Server (form submissions) | Handle mutations |
-| `default` | Component | Client + Server | Render UI |
-| `meta` | Function | Server | Set page title, description, OG tags |
-| `handle` | Object | Client + Server | Attach route metadata |
-| `ErrorBoundary` | Component | Client + Server | Error UI for this route |
-| `headers` | Function | Server | Set HTTP response headers |
+`SeoMeta` props: `title`, `rawTitle`, `description`, `noIndex`, `siteName`, `twitter`, `openGraph`. Use `noIndex` on account and transactional pages. `JsonLd` takes `data`, optional `id` and `nonce`. Both can be rendered anywhere in the tree, including inside a Suspense boundary.
 
-## Important Notes
+## Checklist when renaming or deleting a route
 
-- All loaders run on the server, both during SSR and client-side navigation
-- Route files must be `.tsx` (TypeScript with JSX) — JavaScript files are forbidden
-- The `_app` prefix is a pathless layout; it does not add `/app` to the URL
-- Resource routes (no default export) return data only, no rendered HTML
+1. Update `src/route-paths.ts`.
+2. Search for the old path in links, redirects, `resourceRoutes` users and tests.
+3. Re-run `pnpm typecheck` to regenerate `+types`.
+4. If the route is referenced by `shouldRevalidate` policies in `src/lib/revalidation/routes/`, update those.

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-routing/references/URLS-AND-SEO-ROUTES.md

@@ -0,0 +1,22 @@
+# Site prefixes, excluded routes and SEO aliases
+
+Configuration lives under `app.url` in `config.server.ts`. Full reference: `docs/README-CONFIG-OPTIONS.md` and `docs/README-MULTI-SITE.md` in your project.
+
+| Key | Effect |
+|---|---|
+| `url.prefix` | path pattern wrapped around every page route; default `/:siteId/:localeId` |
+| `url.excludeRoutes` | globs that skip the prefix; default `['/resource/**', '/action/**']` |
+| `url.seoRoutes` | per-site product and category URL grammars (slug segments, category modes, redirects) |
+
+## Rules
+
+- Define page paths without the prefix (as in `src/route-paths.ts`). The `Link` wrapper, `useNavigate` and `buildUrlFromContext` add it.
+- Never concatenate `/${siteId}/${locale}` by hand.
+- Keep `_app.p.$.tsx` and `_app.c.$.tsx` as splat routes; `seoRoutes` aliases resolve through them. Do not rename them.
+- Build product and category links with `createProductUrl`, `createCategoryUrl` and `createCategoryNavigationUrl` from `@/route-paths`, passing the SEO URL context (`useSeoUrlContext` in `@/hooks/use-seo-url-context`), so slugs and prefixes stay consistent.
+- A loader that resolves a product or category from the URL should use the resolvers under `@/lib/seo/` (see `_app.p.$.tsx`: `resolveProductRoute` from `@/lib/seo/url-resolution.server`) instead of parsing `params` directly.
+- For SEO URL strategy and Business Manager alignment see `storefront-next:sfnext-seo`.
+
+## Callbacks that cannot carry a prefix
+
+SLAS redirects back to a fixed URL. Register such routes by hand in `src/routes.ts`: add the file to `IGNORED_ROUTE_FILES` and append `route('/your-callback', 'routes/your-file.ts')` after `flatRoutes(...)`, exactly as the two existing SLAS callbacks do. Then register the full URL in SLAS (see `storefront-next:sfnext-authentication`).

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-scapi/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: sfnext-scapi
+description: >-
+  Use and extend SCAPI clients in a Storefront Next project: createApiClients, the `@/scapi` type barrel, typing `c_*` custom attributes by overriding a built-in client, and adding your own custom API end to end with `b2c sfnext scapi` (add, available, list, remove). Use for "clients.shopperProducts", "c_ attribute is not typed", "sfnext scapi add", "add custom API to the storefront", src/scapi/ generated files, custom-clients.ts, calling a loyalty/notify-style custom endpoint from a loader or action, useScapiFetcher, personalized=none for custom clients, or 404 from a custom endpoint. Do not use for writing the cartridge/schema.yaml itself (use `b2c:b2c-custom-api-development`), endpoint registration status (use `b2c-cli:b2c-scapi-custom`), loader/caching strategy (use `storefront-next:sfnext-data-fetching`), or login/session code (use `storefront-next:sfnext-authentication`).
+---
+
+# Storefront Next SCAPI Clients and Custom APIs
+
+The runtime (`@salesforce/storefront-next-runtime/scapi`) already ships typed clients for the standard shopper APIs (products, search, baskets, customers, orders, and so on). You do not "add" those. `sfnext scapi add` does one of two things on top:
+
+1. **Override** a built-in client (client key matches, for example `shopperProducts`) with a richer schema, typically your tenant's schema expanded with `c_*` custom attributes, so `product.c_myAttr` is typed.
+2. **Add a custom API** you deployed to B2C Commerce (a new property such as `clients.loyalty`).
+
+Which one you get is decided automatically from the client key. Deep dive: `docs/README-SCAPI.md` in your project.
+
+## The CLI surface
+
+Run as `b2c sfnext scapi ...`, or inside your project as `pnpm sfnext scapi ...` (the `sfnext` bin ships with the project). Add `-d <dir>` / `--project-directory` to target another directory.
+
+| Command | What it does |
+|---|---|
+| `scapi available` | Probes your tenant: for each of the built-in shopper APIs counts `c_*` attributes, lists tenant custom APIs, and prints the matching `scapi add` command. Needs OAuth. No filter flags. |
+| `scapi add <apiFamily> <apiName> <apiVersion>` | Pull mode: fetch the schema from the SCAPI Schemas API. Needs OAuth. |
+| `scapi add --schema <file> --name <clientKey>` | Local mode: use a YAML/JSON OpenAPI file. `--name` is required here. |
+| `scapi list` | Shows registered Overrides and Custom APIs (schema, base path, locale). |
+| `scapi remove <clientKey>` | Removes the registration and its generated files (one positional argument: the client key, for example `loyalty`). |
+
+`add` flags: `--name <key>` (defaults to camelCase of the API name in pull mode), `--base-path <path>` (derived from the schema `servers[].url` if omitted), `--supports-locale` / `--no-supports-locale` (overrides inherit the built-in default), `--expand-custom-properties` (default on, pull mode only; include `c_*`, use `--no-expand-custom-properties` to skip). Re-running `add` regenerates; there is no `--force` and no `--json`. There is no install step after `add`.
+
+**Pull mode prerequisites:** SCAPI short code (`SFCC_SHORTCODE` or `--short-code`), tenant id (`SFCC_TENANT_ID` or `--tenant-id`), and an Account Manager API client allowed the `sfcc.scapi-schemas` scope (`SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET`, or `--client-id`/`--client-secret`, or `dw.json`). The legacy names `SFCC_OAUTH_CLIENT_ID` / `SFCC_OAUTH_CLIENT_SECRET` are also accepted because the CLI resolves both. If the `@salesforce/storefront-next-dev` package is in the project, `b2c` uses that local version.
+
+```bash
+# Which built-in APIs have c_ attributes on my tenant? Which custom APIs exist?
+b2c sfnext scapi available
+
+# Type c_* attributes on products (override; pulls schema with custom properties)
+b2c sfnext scapi add product shopper-products v1
+
+# Register a custom API from the tenant, or from a local file
+b2c sfnext scapi add custom loyalty v1
+b2c sfnext scapi add --schema ./loyalty-api.yaml --name loyalty --base-path /custom/loyalty/v1
+
+b2c sfnext scapi list
+b2c sfnext scapi remove loyalty
+```
+
+For a schema-only look without touching the project use `b2c scapi schemas get/list` (see `b2c-cli:b2c-scapi-schemas`; both need `--tenant-id`).
+
+## What gets generated
+
+```
+src/scapi/
+  index.ts            barrel (generated), the only SCAPI import surface for app code
+  custom-clients.ts   registry of overrides and custom clients (generated)
+  schemas/            <name>-<ver>.yaml and .meta.json
+  generated/          <name>-<ver>.ts, .operations.ts, (.namespace.ts for overrides)
+```
+
+Never hand-edit these; rerun `sfnext scapi add`. Registry entries carry `key`, `basePath`, `ops`, `locale`, `orgPrefix`. Custom clients use `orgPrefix: true` (base `/custom/<name>/v1/organizations/{orgId}`); the shipped `sfnextNotify` entry is a working example.
+
+## Import rule
+
+Import types and clients from the barrel, not from the runtime package:
+
+```typescript
+import { ApiError, type ShopperProducts } from '@/scapi';          // picks up overrides
+// import { ShopperProducts } from '@salesforce/storefront-next-runtime/scapi'; // bypasses overrides, lint warns
+```
+
+Only `src/scapi/**` and `src/lib/api-clients.server.ts` may import the runtime path directly.
+
+## Use clients in loaders and actions
+
+```typescript
+import { createApiClients } from '@/lib/api-clients.server';
+
+export async function loader({ context }: LoaderFunctionArgs) {
+    const clients = createApiClients(context);
+    const { data: product } = await clients.shopperProducts.getProduct({
+        params: { path: { id: 'my-product-id' } },
+    });
+    const { data: rewards } = await clients.loyalty.getLoyaltyRewards(); // custom client
+    return { product, rewardTier: product?.c_loyaltyTier, rewards };
+}
+```
+
+- Calls return `{ data }` and **throw** `ApiError` on failure (wrap in `NormalizedApiError` from `@/lib/api/normalized-api-error` when you need a message/status).
+- `createApiClients` automatically injects `organizationId`, `siteId` and (when the client supports it) `locale`. Do not pass `siteId` yourself.
+- Auth comes from the shopper token in the auth middleware (`storefront-next:sfnext-authentication`); do not read tokens to call SCAPI manually. Get the shopper via `getAuth(context)` only when you need `customerId`.
+- Prefer the existing helpers in `src/lib/api/*.server.ts` (search, products, basket, wishlist, order) for standard APIs, and put your own custom-API calls in a new `src/lib/api/<thing>.server.ts`.
+- Calling from the browser: `useScapiFetcher(client, method, options)` goes through `/resource/api/client/...`, which only allows a short **allow-list** of operations (`src/lib/scapi/resource-policy.ts`), and `siteId`/`locale`/`organizationId` are server-owned. A new custom operation is not callable from the browser until you add it there; prefer a route loader/action. The `'helpers'` overload is deprecated. See `docs/README-PERFORMANCE.md` and `docs/README-REVALIDATION.md` for fetcher lifecycle rules.
+
+## End-to-end: a new custom API
+
+1. **Author the endpoint** (cartridge `rest-apis/<api-name>/` with `api.json`, `schema.yaml`, script) using `b2c:b2c-custom-api-development`. `api.json` maps `endpoint` to `schema` and `implementation`; auth is declared in `schema.yaml` (`ShopperToken` for storefront calls, with a `c_` scope under `security:`). The shipped `cartridges/app_storefrontnext_base/cartridge/rest-apis/sfnext-notify/` is a complete example.
+2. **Deploy and activate**: `b2c code deploy <cartridge> --reload` (reload toggles activation so endpoints re-register; see `b2c-cli:b2c-code`).
+3. **Confirm registration**: `b2c scapi custom status --tenant-id <id>` (filter with `--status not_registered`). Use `b2c-cli:b2c-scapi-custom` for 404s and `errorReason`.
+4. **Allow the scope**: add the custom scope to the SLAS client used by the storefront (`b2c-cli:b2c-slas`). The shopper token must carry it, otherwise calls get 401/403.
+5. **Register in the storefront**: `b2c sfnext scapi add custom <api-name> v1` (or `--schema` with a local copy).
+6. **Call it** from a server loader/action as above; `import type` request/response types from `@/scapi`.
+7. After schema changes repeat steps 2 and 5.
+
+## Non-personalized caching
+
+Storefront Next can add `personalized=none` to eligible GET requests through one central policy. Overrides and custom clients are **left unclassified** until you review and approve their exact transports in the policy module. Do not loosen it to `() => true`. See `docs/README-SCAPI-NON-PERSONALIZED-RESPONSES.md` before approving a client.
+
+## Pitfalls
+
+- Expecting `scapi add shopper-search ...` to be needed: standard clients already exist.
+- Importing from `@salesforce/storefront-next-runtime/scapi` and wondering why `c_*` is untyped.
+- Forgetting `--reload` after deploy, so the endpoint stays unregistered (404).
+- Passing `siteId` or `locale` in `params.query`: server-owned, stripped on the resource route and injected elsewhere.
+- Override key typos: the key must exactly match a built-in (`shopperProducts`, `shopperBasketsV2`, ...) or you create an unrelated custom client.
+- Custom client used from the browser fetcher without allow-listing it.
+
+Worked example of a shipped custom API: [references/WORKED-EXAMPLE.md](references/WORKED-EXAMPLE.md).
+
+## Related Skills
+
+- `b2c:b2c-custom-api-development` - author the cartridge, api.json, schema.yaml, scripts
+- `b2c-cli:b2c-scapi-custom` - registration status and debugging 404s
+- `b2c-cli:b2c-scapi-schemas` - browse SCAPI schemas
+- `b2c-cli:b2c-slas` - add custom scopes to the SLAS client
+- `storefront-next:sfnext-data-fetching` - loaders, actions, caching
+- `storefront-next:sfnext-authentication` - `getAuth`, sessions
+- `storefront-next:sfnext-revalidation` - fetcher revalidation rules

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-scapi/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "My product.c_brandStory custom attribute shows up as unknown in TypeScript on the PDP. How do I get it typed in Storefront Next?", "should_trigger": true},
+  {"query": "I deployed a loyalty custom API to my sandbox. How do I register it in the storefront with sfnext scapi and call it from a route loader?", "should_trigger": true},
+  {"query": "How do I write the schema.yaml and api.json for a new custom API endpoint in my cartridge?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-scapi/references/WORKED-EXAMPLE.md

@@ -0,0 +1,39 @@
+# Worked Example: the shipped `sfnext-notify` custom API
+
+Your project already contains one complete custom API, used to send login and password-reset emails. Copy its shape for your own.
+
+| Piece | Location in your project |
+|---|---|
+| Endpoint mapping | `cartridges/app_storefrontnext_base/cartridge/rest-apis/sfnext-notify/api.json` |
+| Contract and auth | `.../sfnext-notify/schema.yaml` (`ShopperToken` security scheme, scope `c_sfnext_notify`, `security:` on the operation) |
+| Implementation | `.../sfnext-notify/Notify.js` (exports `notify`, matching `"implementation": "Notify"` and the `operationId`) |
+| Storefront registration | `src/scapi/schemas/sfnext-notify-v1.yaml` + `.meta.json`, `src/scapi/generated/`, entry in `src/scapi/custom-clients.ts` |
+| Server call site | `src/lib/notify/notify.server.ts` |
+
+`api.json` maps each `operationId` to a schema file and script module:
+
+```json
+{ "endpoints": [ { "endpoint": "notify", "schema": "schema.yaml", "implementation": "Notify" } ] }
+```
+
+Registry entry generated by `sfnext scapi add`:
+
+```typescript
+{ key: 'sfnextNotify', basePath: '/custom/sfnext-notify/v1', ops: ops0, locale: true, orgPrefix: true }
+```
+
+Call site (server only):
+
+```typescript
+import { createApiClients } from '@/lib/api-clients.server';
+
+const clients = createApiClients(context);
+await clients.sfnextNotify.notify({ params: {}, body }); // siteId, organizationId injected
+```
+
+Notes:
+
+- Authentication is enforced by the SCAPI gateway (shopper token must carry `c_sfnext_notify`), not in the script. Register the scope on the SLAS client once with `sfnext setup-base-cartridge --slas-client-id <id>`.
+- `sfnextNotify` is intentionally **not** in the browser resource-route allow-list, so it cannot be invoked from `useScapiFetcher`; a test in the project asserts this.
+- Being a custom client, it is left unclassified by the non-personalized-response policy, which is correct for a POST.
+- To follow the pattern for your own API: write the cartridge (`b2c:b2c-custom-api-development`), `b2c code deploy <cartridge> --reload`, verify with `b2c scapi custom status --tenant-id <id>`, then `b2c sfnext scapi add custom <name> v1`.