@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/storefront-next/sfnext-quality-gates/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sfnext-quality-gates
+description: >-
+  Run and fix the Storefront Next quality gates before a PR or deploy: OxLint (type-aware, --max-warnings 0) plus Biome formatting, lint:a11y, lint:css, typecheck, the TypeScript-only check, bundle-size budgets, Lighthouse CI, and the pre-PR checklist. Use when pnpm lint, pnpm format:check, pnpm typecheck, pnpm bundlesize or pnpm lighthouse:ci fails, for custom/color-linter or custom/header-format errors, "unused Tailwind class" findings, oxlint-disable comments, "what should I run before opening a PR", or CI red on lint. Do not use for writing tests (use `storefront-next:sfnext-testing`), accessibility fixes themselves (use `storefront-next:sfnext-accessibility`), or runtime performance tuning (use `storefront-next:sfnext-performance`).
+---
+
+# Storefront Next Quality Gates
+
+Your project enforces style, types, size and accessibility with a few commands. CI runs the same ones, and lint is strict: any warning fails.
+
+## Pre-PR checklist
+
+```bash
+pnpm lint            # OxLint (type-aware, --max-warnings 0) then Biome format check
+pnpm typecheck       # route typegen + tsc --noEmit
+pnpm test            # unit tests
+pnpm storybook:test --type=snapshot   # if you touched components or stories
+pnpm bundlesize      # if you added dependencies or large components
+```
+
+If you changed UI, also run `pnpm storybook:test --type=interaction` and `--type=a11y` (needs `pnpm exec playwright install chromium`). Fix formatting and auto-fixable lint in one go with `pnpm lint:fix`.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `pnpm lint` | `oxlint --type-aware --report-unused-disable-directives --max-warnings 0` (e2e excluded) then `biome format` check, then the e2e package's own lint |
+| `pnpm lint:fix` | `oxlint --fix` then `biome format --write` |
+| `pnpm format` / `pnpm format:check` | Biome formatting only (4-space indent, 120 columns, single quotes in JS, double in JSX) |
+| `pnpm lint:a11y` | Reports only `jsx-a11y/*` findings; exit 1 if any (see `storefront-next:sfnext-accessibility`) |
+| `pnpm lint:css` | After a build, checks the built app stylesheet for Tailwind candidates that only come from stories, tests or docs (dead or story-only classes). Run `pnpm build` first |
+| `pnpm typecheck` | `react-router typegen` then `tsc --noEmit` (uses extra heap) |
+| `node scripts/check-typescript-only.js` | Fails if `.js/.jsx/.mjs/.cjs` exist under `src/` |
+| `pnpm bundlesize` | Builds with `BUNDLES_SIZE_CHECK=true`; fails if chunks exceed limits in `package.json#bundlesize` (`client` and `server` lists) |
+| `pnpm bundlesize:compare` | Compares two bundle metadata files: `node scripts/compare-bundlesize.mjs --baseline <path> --candidate <path> [--tolerance <pct>]` |
+| `pnpm lighthouse:ci` | `lhci autorun` using `lighthouserc.cjs` (build first; it starts the preview server itself) |
+| `pnpm config:inspect` | Prints the resolved config to debug env overrides |
+
+ESLint and Prettier are not used. OxLint owns all linting (including type-aware rules and custom plugin rules); Biome owns only formatting.
+
+## Custom rules you will hit
+
+- `custom/color-linter`: use design tokens (`bg-primary`, `text-muted-foreground`), not hard-coded colors. See `storefront-next:sfnext-theming`.
+- `custom/header-format`: every TS/JS file needs the Apache 2.0 license header. Copy it from any existing source file.
+- `jsx-a11y/*` recommended set at error, plus `no-aria-hidden-on-focusable`, `anchor-ambiguous-text`, `no-redundant-roles` (allows `role="list"` on `ul`) and `alt-text` extended to `DynamicImage` and `ProductImage`.
+- `no-restricted-imports`: browser-only `@salesforce/storefront-next-runtime/i18n/client` is blocked from server modules.
+- TypeScript only in `src/`.
+
+Fix the code rather than disabling. If a suppression is truly needed, use a scoped `// oxlint-disable-next-line <rule> -- reason`. `--report-unused-disable-directives` fails stale ones. Generated and vendored trees (SCAPI generated clients, `src/components/ui/**`, build output) are skipped by lint and format.
+
+More: [references/lint-and-budgets.md](references/lint-and-budgets.md) and `docs/README-LINTING.md` (skip the sections about repository internals that do not apply to your project).
+
+## Typical failures
+
+| Symptom | Fix |
+|---------|-----|
+| `pnpm lint` fails only at the end on formatting | `pnpm format` |
+| Warning count > 0 | Warnings are errors here; fix or justify with a scoped disable |
+| `jsx-a11y/...` error | Fix markup; run `pnpm lint:a11y` while iterating |
+| Type errors about `+types/...` routes | Run `pnpm typecheck` (it regenerates route types) |
+| `pnpm lint:css` cannot find stylesheet | Run `pnpm build` first |
+| Lighthouse/bundle budget exceeded after adding a feature | See the budget notes in the reference; look for eager imports before raising a limit |
+
+## Related Skills
+
+- `storefront-next:sfnext-testing` - unit, story and e2e tests (the test half of the checklist)
+- `storefront-next:sfnext-accessibility` - fixing a11y lint and scan findings
+- `storefront-next:sfnext-performance` - reducing bundle and page weight
+- `storefront-next:sfnext-theming` - design tokens behind `color-linter`
+- `storefront-next:sfnext-deployment` - build and push after the gates pass

package/content/guidance/storefront-next/sfnext-quality-gates/references/lint-and-budgets.md

@@ -0,0 +1,39 @@
+# Lint configuration and performance budgets
+
+## Configuration files in your project
+
+| File | Role |
+|------|------|
+| `.oxlintrc.json` | All lint rules, custom JS-plugin rules (`custom/*`), overrides for tests/stories, `ignorePatterns` |
+| `biome.json` | Formatter only (linter and assists disabled) |
+| `lint-plugins/` | Source of the `custom/color-linter` and `custom/header-format` rules |
+| `e2e/biome.json` and e2e scripts | The e2e package lints and formats itself; it is not type-aware linted |
+
+OxLint's JS-plugin loader needs Node >= 22.6; the project requires Node 24.
+
+Test files relax some rules (fixtures use ad-hoc roles and handlers); story and test overrides are in `.oxlintrc.json`.
+
+## Editor integration
+
+Install the Oxc VS Code extension for inline diagnostics and the Biome extension (set as default formatter) for format on save.
+
+## Bundle size
+
+- Limits: `package.json#bundlesize` with `client` and `server` arrays of `{ name: <glob>, limit: '<size>' }`. Defaults are generous if absent.
+- `pnpm bundlesize` writes `build/<env>-bundlemeta.json` per environment.
+- Visualize: `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` opens `build/client-bundle-size.html` and `build/ssr-bundle-size.html` (`docs/README-PERFORMANCE.md`).
+- Before adding a large dependency, check its impact with the visualizer, lazy-load it (`React.lazy` or dynamic `import()`), and prefer server-only code for heavy logic.
+
+## Lighthouse CI
+
+- `lighthouserc.cjs` defines the URLs (home, a PDP, cart), number of runs, category score minimums (performance, accessibility, SEO, best-practices) and ceilings for `resource-summary:script:size` and `resource-summary:document:size` per route.
+- The shipped numbers are tuned to the starter theme. Your customizations (new scripts, bigger documents, different sites or product ids in the URL list) will move them. Update URLs to pages that exist in your catalog, then measure and set ceilings deliberately, with headroom, rather than deleting assertions.
+- Run `pnpm build` first; the config starts the preview server on port 3001 itself.
+- Also run `pnpm bundlesize` in CI or locally so regressions show up per chunk, not just in page totals.
+
+## When a budget fails
+
+1. Identify what grew: compare bundle metadata (`pnpm bundlesize:compare`) or the visualizer.
+2. Look for eager imports of heavy modules in root, layouts or shared components; convert to lazy loads.
+3. Check that new third-party scripts are deferred (see `storefront-next:sfnext-performance`).
+4. Only then raise a limit, in the smallest increment, and note why in the commit message.

package/content/guidance/storefront-next/sfnext-revalidation/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: sfnext-revalidation
+description: >-
+  Control which Storefront Next loaders re-run after an action or navigation: shouldRevalidate exports, the policy modules in src/lib/revalidation/routes (root, cart, product, category, checkout, home, wishlist, api-client, shared), getActionPath and isAmbientMutation, and the tag primitives in src/lib/revalidation/tags (withRevalidateTags, shouldRevalidateForTags, tagGroup, tagImplications). Use for "page re-fetches after add to cart", "loader runs too often", "stale data after a mutation", "flash of skeleton after changing a swatch", "add shouldRevalidate", or when a new action or route changes which loaders fire. Do not use for writing loaders or actions (use `storefront-next:sfnext-data-fetching`), Suspense and LCP tuning (use `storefront-next:sfnext-performance`), or client-side state (use `storefront-next:sfnext-state-management`).
+---
+
+# Storefront Next Revalidation
+
+React Router re-runs loaders after every action submission. A storefront has deep route trees, persistent fetchers (mini-cart) and lazy modals (quick view), so one add-to-cart can re-run many loaders that never read the basket, each with its own SCAPI fan-out. This skill is how to keep only the re-runs that are needed. The authoritative guide is `docs/README-REVALIDATION.md` in your project; read it before changing policy.
+
+## What revalidates
+
+An action submission (`<Form>`, `useSubmit`, `fetcher.submit`) re-runs the whole active set:
+
+1. the matched route chain (root, layouts, leaf),
+2. mounted resource fetchers (`fetcher.load()` of a resource route whose component is still mounted),
+3. fetchers inside open modals, drawers and sheets.
+
+A raw `fetch()`, a SCAPI client call, or `fetcher.load()` is not a submission and triggers nothing. A route that only exports an `action` fires revalidation but has no loader to re-run.
+
+## When a re-run is justified
+
+For each pair (action, active loader) it is justified only if both are true:
+
+- **Overlap**: the action result changes something the loader reads.
+- **Value not already available**: the new value does not already reach the UI another way (for example the basket provider is updated from the action result, so a cart action does not need the PDP loader to re-run).
+
+Two waste types: no overlap, or overlap with the value already available. Do not gate a re-run that is itself the sync mechanism (a provider that refills from loader output).
+
+## Where the policy lives
+
+Each route re-exports a shared policy rather than inlining logic:
+
+```ts
+// src/routes/_app.cart.tsx
+export { shouldRevalidate } from '@/lib/revalidation/routes/cart';
+```
+
+| Module (`src/lib/revalidation/routes/`) | Used by |
+|---|---|
+| `root.ts` | `src/root.tsx` (`export { shouldRevalidate } from ...`); denylist of irrelevant mutations, safe default is revalidate |
+| `cart.ts`, `checkout.ts`, `home.ts`, `wishlist.ts` | the matching route files |
+| `product.ts` | `_app.p.$.tsx`: relevant mutations force true; navigation re-runs only on different path or `pid` |
+| `category.ts` | `_app.c.$.tsx` and `_app.search.tsx`: skips client-only param changes and non-ambient mutations |
+| `api-client.ts` | `resource.api.client.$resource.ts` |
+| `shared.ts` | helpers: `getActionPath`, `isContextMutation`, `isIdentityMutation`, `isAmbientMutation` |
+
+`_app.tsx` exports `shouldRevalidate() { return false }` (navigation data that no shopper action changes). `resource.basket-products.ts` opts in only when `actionResult.basket.basketId` exists.
+
+"Ambient" mutations (site/currency, shopper context, login/signup/logout) change request-wide inputs and legitimately re-run most loaders.
+
+## Add a policy for a new route
+
+Prefer suppress-by-default allowlists for expensive loaders, and defer to the default for cheap ones:
+
+```ts
+// src/lib/revalidation/routes/store-events.ts
+import type { ShouldRevalidateFunctionArgs } from 'react-router';
+import { resourceRoutes } from '@/route-paths';
+import { getActionPath, isAmbientMutation } from './shared';
+
+const RELEVANT = [resourceRoutes.setSelectedStore] as readonly string[];
+
+export function shouldRevalidate({ currentUrl, nextUrl, formMethod, formAction, defaultShouldRevalidate }: ShouldRevalidateFunctionArgs) {
+    if (formMethod && formMethod !== 'GET') {
+        const path = getActionPath(formAction, currentUrl.origin);
+        return Boolean(path && (isAmbientMutation(path) || RELEVANT.includes(path)));
+    }
+    if (currentUrl.pathname !== nextUrl.pathname) return true;
+    return defaultShouldRevalidate; // explicit revalidate() still works; client-only params stay skipped
+}
+```
+
+Steps:
+
+1. List what the loader reads (fetched fields, URL params, cookies, context such as currency or selected store).
+2. List the actions reachable while this route is active (page, shell, open modals and drawers). Mark overlap and availability per action.
+3. Export the policy. Admit only mutations with overlap and no other delivery path. Document each admit in a comment.
+4. If a URL-filtered loader (search params) re-runs on navigation anyway, skip revalidating when only those params change.
+5. Add a test next to the policy (`*.test.ts`), covering an admitted mutation, a skipped mutation and a navigation.
+6. Verify manually: open DevTools Network, perform the gesture, and count loader (`.data`) requests.
+
+Gate adequacy matters: a policy that only checks `formAction` is set still re-runs on every action. Inspect the action path or `actionResult`.
+
+## Tags for cross-route contracts
+
+When several routes depend on the same data, use the tag primitives in `@/lib/revalidation/tags` (the framework ships primitives only; you own the catalogs):
+
+```ts
+// src/lib/revalidation/tags/cart.ts  (yours)
+export const cartTags = { all: 'cart.*', lineItem: (id: string) => `cart.lineItems:${id}` as const } as const;
+
+// action: emit
+import { withRevalidateTags } from '@/lib/revalidation/tags';
+return withRevalidateTags({ basket }, [cartTags.lineItem(itemId)]);
+
+// route: subscribe
+import { shouldRevalidateForTags } from '@/lib/revalidation/tags';
+export const shouldRevalidate = shouldRevalidateForTags([cartTags.all]);
+```
+
+Spell tags only through catalog builders (a typo silently matches nothing). Syntax: dot-separated segments, optional `:id`, `.*` wildcard is subscriber-only. Helpers: `tagGroup`, `tagImplications`, `matchesTag`, `normalizeTags`, `resolveTags`; `shouldRevalidateForTags(spec, { ambient, expand })`. An untagged action falls back to default behavior. See `src/lib/revalidation/tags/index.example.test.ts` and details in [POLICIES-AND-TAGS.md](references/POLICIES-AND-TAGS.md).
+
+## Related levers
+
+- Add-to-cart, promo and quantity changes update the basket through `updateBasketResource` and `BasketProvider` (`src/providers/basket.tsx`), so pages rarely need loader re-runs to show the new basket.
+- `useRevalidateOnReturn` (`@/hooks/use-revalidate-on-return`) refreshes stale data when the shopper returns to the tab or page.
+- Modals and drawers mount lazily; a quick-view that both loads product data and submits add-to-cart widens the active set and triggers it. Keep its fetcher unmounted until open and consider moving the submit elsewhere.
+- Leave `shouldRevalidate` gates on root-level session, site and config loaders conservative: the root policy defaults to revalidate.
+
+## Finding more
+
+`docs/README-REVALIDATION.md`, `docs/README-DATA.md`, `docs/README-STATE.md` and `AGENTS.md` in your project. `b2c docs search "revalidation"` or the `docs_search` MCP tool for product docs.
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - loaders, actions, fetchers
+- `storefront-next:sfnext-performance` - review checklist (revalidation scope section)
+- `storefront-next:sfnext-state-management` - providers that make a re-run unnecessary
+- `storefront-next:sfnext-routing` - route files that export policies
+- `storefront-next:sfnext-testing` - tests for policies

package/content/guidance/storefront-next/sfnext-revalidation/references/POLICIES-AND-TAGS.md

@@ -0,0 +1,55 @@
+# Policies and tags reference
+
+## Policy inputs
+
+`shouldRevalidate` receives `currentUrl`, `nextUrl`, `formMethod`, `formAction`, `actionStatus`, `actionResult` and `defaultShouldRevalidate`.
+
+- Action submissions have `formMethod` other than GET. Resolve the target with `getActionPath(formAction, currentUrl.origin)` from `@/lib/revalidation/routes/shared`, then compare to `resourceRoutes` values.
+- A navigation has no non-GET `formMethod`. Compare pathname and the search params the loader consumes.
+- `useRevalidator().revalidate()` arrives with `defaultShouldRevalidate` true and no `formMethod`; return `defaultShouldRevalidate` for that case so explicit refreshes work.
+- Treat any 2xx `actionStatus` as success, not only 200.
+
+## Decision table
+
+| Situation | Policy |
+|---|---|
+| Loader reads only data no action changes (navigation menu) | `return false` |
+| Loader reads URL filters | skip when only those params change; the navigation re-runs it with new params |
+| Expensive loader, few relevant writes | allowlist (suppress by default), as in `product.ts` |
+| Cheap loader, few irrelevant writes | denylist, as in `root.ts` |
+| Resource fetcher backing a provider | opt in when `actionResult` carries its payload (`basket.basketId`) |
+| Many routes depend on one data domain | tags |
+
+## Modals and drawers
+
+Lazy modals and drawers join the active set only after opening. List each modal as potential target (loads a resource fetcher on open) and trigger (submits an action). Fix by gating the fetcher-owning route, or by not mounting the loading component until needed.
+
+## Tags
+
+Primitives (`src/lib/revalidation/tags/index.ts`):
+
+| Export | Role |
+|---|---|
+| `withRevalidateTags(result, tags)` | action: attach `revalidateTags` to the result |
+| `shouldRevalidateForTags(spec, { ambient, expand })` | route: build a `shouldRevalidate`; `spec` is a tag array or `({ params }) => tags` |
+| `tagGroup(tag, deps)` | subscriber: a tag plus the tags it depends on |
+| `tagImplications(map)` | emitter side: expand an emitted tag into implied concrete tags |
+| `matchesTag(pattern, emitted)` | the matcher |
+| `normalizeTags`, `resolveTags` | utilities |
+
+Matching rules: the subscriber's pattern is compared to each emitted tag segment by segment. A trailing `.*` in the pattern matches any deeper tags. A pattern that omits `:id` matches all instances; if both pin an id they must equal. An emitted `*` is a literal segment.
+
+Ambient tags (cross-cutting dimensions such as currency) are appended to every subscription unless you pass `{ ambient: false }`. The default vocabulary is empty; define it per app with `tagImplications` if you need it.
+
+Compose with an extra guard when needed:
+
+```ts
+const byTags = shouldRevalidateForTags(['cart.*']);
+export const shouldRevalidate = (args) => byTags(args) && args.nextUrl.searchParams.get('drawer') === 'open';
+```
+
+Keep tag catalogs small and per domain in `src/lib/revalidation/tags/<domain>.ts`. Test them with the pattern in `index.example.test.ts`.
+
+## Root policy
+
+The root policy (`routes/root.ts`) defaults to revalidate, so avoid adding expensive work to the root loader; put it in a leaf route or stream it. Request-wide state is produced by the middleware chain in `src/root.tsx`.

package/content/guidance/storefront-next/sfnext-routing/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: sfnext-routing
+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`).
+---
+
+# Storefront Next Routing
+
+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.
+
+## How routes are discovered
+
+`src/routes.ts` imports `flatRoutes` from `@salesforce/storefront-next-runtime/routing` (not `@react-router/fs-routes`). It is a drop-in wrapper that:
+
+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.
+
+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`.
+
+## Route tree (what exists)
+
+| 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 |
+
+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.
+
+## Add a page
+
+```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';
+
+export async function loader({ request }: Route.LoaderArgs) {
+    return { pageUrl: new URL(request.url).href };
+}
+
+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>
+        </>
+    );
+}
+```
+
+Checklist for a new page:
+
+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`).
+
+## 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>
+```
+
+`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.
+
+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`:
+
+```ts
+import { redirect } from 'react-router';
+import { routes } from '@/route-paths';
+import { buildUrlFromContext } from '@/lib/url.server';
+
+throw redirect(buildUrlFromContext(routes.login, context));
+```
+
+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.
+
+## URL configuration
+
+`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.
+
+## Protecting routes
+
+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`.
+
+## Rules to keep in mind
+
+- 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
+
+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).
+
+## Related Skills
+
+- `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/content/guidance/storefront-next/sfnext-routing/references/ROUTE-CONVENTIONS.md

@@ -0,0 +1,65 @@
+# Route conventions
+
+## File name to URL
+
+| 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` |
+
+- 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.
+
+## Route module exports
+
+| 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` |
+
+`clientLoader` and `clientAction` are not permitted.
+
+## Typed route props
+
+```tsx
+import type { Route } from './+types/_app.cart';
+
+export async function loader({ request, context, params }: Route.LoaderArgs) { /* ... */ }
+export default function Cart({ loaderData }: Route.ComponentProps) { /* ... */ }
+```
+
+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
+
+`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.
+
+## Checklist when renaming or deleting a route
+
+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/content/guidance/storefront-next/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/content/guidance/storefront-next/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