@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/storefront-next/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`.

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

@@ -0,0 +1,129 @@
+---
+name: sfnext-security
+description: >-
+  Configure Storefront Next security response headers, Content Security Policy (CSP), CSP contributors, Cloudflare Turnstile bot protection, and the shared cookie domain. Use for "Refused to load the script/connect/image" CSP violations, adding a third-party origin, app.security.headers, defaultCspDirectives, csp reportOnly rollout, writing a CSP contributor under src/middlewares/csp-contributors, HSTS or Permissions-Policy, Turnstile widget or enforceTurnstile, TURNSTILE_SECRET_KEYS, log-only rollout, or app.cookies.domain across subdomains. Do not use for auth tokens, cookie names or login flows (use `storefront-next:sfnext-authentication`), SFRA proxy routing (use `storefront-next:sfnext-hybrid-storefronts`), or consent banners and tracking (use `storefront-next:sfnext-analytics-consent`).
+---
+
+# Storefront Next Security
+
+Security is configured under `app.security` in `config.server.ts`: `security.headers` for response headers and CSP, `security.turnstile` for bot protection. Cookie sharing is `app.cookies.domain`. Your project ships deeper docs: `docs/README-SECURITY-HEADERS.md`, `docs/README-TURNSTILE.md`, `docs/README-COOKIE-DOMAIN.md`. Read them for details; this skill is the task guide.
+
+## Default headers
+
+Every storefront gets these with no opt-in, from `@salesforce/storefront-next-runtime/security` via the `securityHeadersMiddleware` in `src/middlewares/security-headers.server.ts`:
+
+| Header | Default |
+|---|---|
+| `Content-Security-Policy` | Strict, nonce-based (no `'unsafe-inline'` scripts, no `'unsafe-eval'`) |
+| `Strict-Transport-Security` | Sent on Managed Runtime only, suppressed locally |
+| `X-Frame-Options` | `SAMEORIGIN` |
+| `X-Content-Type-Options` | `nosniff` |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` |
+| `Permissions-Policy` | `camera=(), microphone=(), geolocation=()` |
+
+The CSP directive table (which origins `script-src`, `connect-src`, `img-src`, and `frame-src` allow by default) is in `docs/README-SECURITY-HEADERS.md`. The per-request nonce is read in `root.tsx` and must be forwarded to any inline `<script>` you render (for example the JSON-LD component takes a `nonce` prop).
+
+## Allow a new third-party origin
+
+The violation message names the directive to extend ("Refused to connect to ..." means `connect-src`). Spread the defaults, because **each directive you set fully replaces the default**:
+
+```ts
+// config.server.ts
+import { defaultCspDirectives } from '@salesforce/storefront-next-runtime/security';
+
+security: {
+    headers: {
+        csp: {
+            directives: {
+                ...defaultCspDirectives,
+                'script-src': [...defaultCspDirectives['script-src']!, 'https://cdn.example.com'],
+                'connect-src': [...defaultCspDirectives['connect-src']!, 'https://api.example.com'],
+            },
+        },
+    },
+},
+```
+
+Use exact origins, not wildcards. Do not load third-party scripts synchronously in the document head; load them after interaction or idle (see `storefront-next:sfnext-performance`).
+
+Env-var override is awkward for directives (names contain hyphens, and a JSON override replaces the whole map). Use `config.server.ts` for directives and env vars for toggles:
+
+```bash
+PUBLIC__app__security__headers__csp__reportOnly=true
+PUBLIC__app__security__headers__hsts=false
+```
+
+## Roll out or relax safely
+
+- Migrating or adding many origins: set `csp: { reportOnly: true }`, watch DevTools violations, extend the directives, then remove `reportOnly`. A startup warning is logged while it is on.
+- Disable one header with `hsts: false` or `permissionsPolicy: false`. `headers: { enabled: false }` disables everything; use it for debugging only. A startup warning is logged whenever any header is disabled.
+
+## CSP contributors
+
+A contributor lets a feature add its own exact origins to the CSP at boot instead of hand-editing directives. Shipped examples in `src/middlewares/csp-contributors/`: `cimulate.ts` (Shopper Agent widget, active when enabled in config), `data360.ts` (`connect-src` for the tenant ingestion host), and `openstreetmap.ts` (a deliberate no-op; replace it to permit map tiles).
+
+Shape (see `data360.ts` for the smallest real one):
+
+```ts
+import type { CspContributor, CspContribution } from '@salesforce/storefront-next-runtime/security';
+import { toCspOrigin } from './to-csp-origin.js';
+
+export function createMyFeatureCspContributor(cfg: { enabled?: boolean; apiUrl?: string } | undefined): CspContributor {
+    const origin = cfg?.apiUrl ? toCspOrigin(cfg.apiUrl) : null;
+    return {
+        id: 'my-feature',
+        isActive: () => cfg?.enabled === true && origin !== null,
+        contribute: (): CspContribution => (origin ? { 'connect-src': [origin] } : {}),
+    };
+}
+```
+
+Then add it to the `contributors` array in `src/middlewares/security-headers.server.ts`. Rules:
+
+- Derive origins from config you already have; `toCspOrigin` returns `null` for unsafe values.
+- The runtime validates contributors at boot: https only, no wildcards, no credentials, no whitespace.
+- Contribute only while the feature is active, so disabled features never widen the policy.
+- Add a colocated `*.test.ts` like the shipped ones.
+
+Use a contributor for a feature toggled by config; use the `defaultCspDirectives` spread for one-off origins.
+
+## Turnstile bot protection
+
+Cloudflare Turnstile guards passwordless email, checkout registration, and order lookup. It is **fail-open** on Cloudflare outages (so a Turnstile incident never blocks checkout) and fail-closed on real bot signals (forged, replayed, or missing tokens).
+
+Config (`config.server.ts`, overridable with `PUBLIC__` env vars): `security.turnstile.enabled`, `mode` (`managed`, `non-interactive`, `invisible`), `sites` (per-site site keys), and `verification.mode` (`enforce`, `log-only`, `disabled`).
+
+| Variable | Purpose |
+|---|---|
+| `TURNSTILE_SECRET_KEYS` | JSON map of site key to secret key. Server-only. Required for `enforce` and `log-only` |
+| `PUBLIC__app__security__turnstile__enabled` | Master switch; when false the widget never renders |
+| `PUBLIC__app__security__turnstile__sites` | JSON per-site keys |
+| `PUBLIC__app__security__turnstile__verification__mode` | `enforce`, `log-only`, `disabled` |
+
+Rollout: deploy with `verification.mode` set to `log-only`, read the logs for `would_block`, then switch to `enforce`. Shoppers start without a `cc-tv_<siteId>` attestation cookie after the switch, which is expected.
+
+Add protection to a new server action by rendering `TurnstileWidget` (`src/components/security/turnstile-widget.tsx`) in the form and calling `enforceTurnstile` (`src/lib/turnstile/enforce.server.ts`) in the action before doing work. Pass `request`, `config`, `turnstileToken`, `logger`, `actionName`, `email`, and `turnstileCookieName`; set the `cc-tv` cookie from the returned `cookieValue` when it is non-null. Copy an existing caller such as `src/routes/action.authorize-passwordless-email.ts`. Cloudflare test keys and a manual test matrix: [references/TURNSTILE.md](references/TURNSTILE.md).
+
+## Cookie domain
+
+Cookies are host-only by default. To share them across subdomains or with SFRA, set `app.cookies.domain` (or `commerce.sites[].cookies.domain` per site; env `PUBLIC__app__cookies__domain=.example.com`) **and** match Business Manager: Site Preferences, Hybrid Auth Settings, cookie-domain level `0` for host-only, `2` for the first-level parent domain. Level `1` is rejected. A mismatch silently breaks sessions. Full checklist: [references/COOKIE-DOMAIN.md](references/COOKIE-DOMAIN.md).
+
+## Pitfalls
+
+| Symptom | Cause / fix |
+|---|---|
+| Added origin to `script-src` and other scripts broke | You replaced the directive. Spread `defaultCspDirectives['script-src']` first |
+| Inline script blocked | Missing `nonce`. Read it from root loader data and pass it on |
+| CSS/JS fail on local Safari after enabling your own `upgrade-insecure-requests` | The default suppresses it locally for a reason; keep the default |
+| Login does not stick after setting `cookies.domain` | Domain is not a parent of the serving host, or Business Manager level mismatches |
+| Turnstile widget never appears | Expected when Cloudflare says no challenge is needed (`interaction-only`); check network tab and `cc-tv_<siteId>` |
+| Everything blocked in Turnstile tests | Secret keys missing in `TURNSTILE_SECRET_KEYS` for the configured site key |
+
+## Related Skills
+
+- `storefront-next:sfnext-authentication` - cookies, sessions, login flows that Turnstile protects
+- `storefront-next:sfnext-hybrid-storefronts` - SFRA proxy and `dwsid` session bridge
+- `storefront-next:sfnext-configuration` - `config.server.ts` and `PUBLIC__` overrides
+- `storefront-next:sfnext-performance` - loading third-party scripts safely
+- `storefront-next:sfnext-analytics-consent` - tracking consent and analytics adapters
+- `storefront-next:sfnext-deployment` - Managed Runtime environment variables

package/content/guidance/storefront-next/sfnext-security/references/COOKIE-DOMAIN.md

@@ -0,0 +1,39 @@
+# Cookie domain reference
+
+Full guide: `docs/README-COOKIE-DOMAIN.md` in your project.
+
+## Resolution order
+
+1. `commerce.sites[].cookies.domain` (per site)
+2. `app.cookies.domain` (global; env `PUBLIC__app__cookies__domain`)
+3. Unset: host-only cookies
+
+The domain is applied to every cookie the storefront writes (auth, session, site, locale, currency). It must be a parent of the serving host or the browser silently drops the cookies. A leading dot is optional.
+
+## Business Manager match
+
+Business Manager, Merchant Tools, Site Preferences, Hybrid Auth Settings:
+
+| Storefront `cookies.domain` | BM level | Result |
+|---|---|---|
+| unset | 0 | OK, host-only everywhere |
+| `.example.com` | 2 | OK, shared across subdomains |
+| `.example.com` | 0 | Broken cross-subdomain session |
+| unset | 2 | Duplicate host-only vs domain-scoped cookies |
+
+Level 1 is rejected. Salesforce-managed sites need a request to the team managing Business Manager.
+
+## Verify
+
+```bash
+curl -sI https://www.example.com/ | grep -i '^set-cookie:'
+```
+
+- Every cookie carries the same `Domain=`.
+- No same-name duplicates (one host-only, one domain-scoped).
+- A session persists between `www.` and `account.` hosts; in hybrid mode `dwsid` is shared with SFRA pages.
+- Logout clears the domain-scoped cookies.
+
+## Rollout
+
+Changing the domain on a live site leaves old cookies next to new ones until they expire, and a host-only cookie shadows a domain-scoped one of the same name. Expect transient session glitches; roll out in a low-traffic window. A per-site empty string inherits the global domain; it cannot force host-only.

package/content/guidance/storefront-next/sfnext-security/references/TURNSTILE.md

@@ -0,0 +1,43 @@
+# Turnstile reference
+
+Deep design lives in `docs/README-TURNSTILE.md` in your project. Quick facts:
+
+## Modules
+
+- `src/components/security/turnstile-widget.tsx` - client widget (`siteKey`, `onSuccess`, `onError`, `onExpire`, `onTimeout`, `onBypass`). Mounts with `appearance: 'interaction-only'`, so it is hidden unless Cloudflare needs shopper input.
+- `src/lib/turnstile/enforce.server.ts` - `enforceTurnstile` and `resolveVerificationMode`.
+- `src/lib/turnstile/constants.ts` - cookie base name `cc-tv` (written as `cc-tv_<siteId>`, 30 minute TTL).
+
+## Enforcement points
+
+`action.authorize-passwordless-email`, `action.initiate-checkout-registration`, the order-lookup request-code action, and the passwordless submit and OTP resend on the login route. The OTP verification actions rely on the earlier challenge plus the code itself.
+
+## Fail-open vs fail-closed
+
+Open (request allowed, logged at warn): siteverify network failure or 5xx, `internal-error`, sustained elevated failure rate, CDN probe failure, client script timeout. Closed: `invalid-input-response`, `timeout-or-duplicate`, missing token while Cloudflare looks healthy, origin mismatch, misconfigured site key.
+
+## Verification mode
+
+| Value | Behavior |
+|---|---|
+| `enforce` | Blocks failures |
+| `log-only` | Runs full verification, only logs `would_block`; no shopper blocked, no `cc-tv` cookie issued |
+| `disabled` | Skips verification |
+
+`TURNSTILE_VERIFICATION_ENABLED` is deprecated; use `PUBLIC__app__security__turnstile__verification__mode`. `TURNSTILE_CDN_PROBE_URL` overrides the health probe URL for tests.
+
+## Cloudflare test keys (local development)
+
+| Site key | Secret key | Behavior |
+|---|---|---|
+| `1x00000000000000000000AA` | `1x0000000000000000000000000000000AA` | Always passes, silent |
+| `2x00000000000000000000AB` | `2x0000000000000000000000000000000AA` | Always blocks, silent |
+| `3x00000000000000000000FF` | `1x0000000000000000000000000000000AA` | Forces an interactive challenge (only visible widget) |
+
+Set the site key in `security.turnstile.sites` and `TURNSTILE_SECRET_KEYS` to a JSON map of site key to secret key. The passwordless login form only renders when the `emailVerificationEnabled` site preference is on (Business Manager, Storefront Login Preferences); see `docs/README-TURNSTILE.md` for seeding it locally.
+
+## Manual checks
+
+- Interactive key `3x...FF` with a passing secret: widget appears, then the OTP modal opens.
+- Always-block key: no widget, a generic "We couldn't verify your information" alert, no OTP modal.
+- Block `challenges.cloudflare.com` locally: no widget, flow continues (graceful degradation).

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

@@ -0,0 +1,95 @@
+---
+name: sfnext-seo
+description: >-
+  Storefront Next SEO and AEO/GEO: the SeoMeta component (title, description, noIndex, Open Graph, X cards), JsonLd structured data, canonical URLs and the query-parameter allowlist, hreflang, configurable product/category URLs via url.seoRoutes, semantic URL builders (createProductUrl, createCategoryUrl, useSeoUrlContext), redirectToCanonicalPath, crawler rendering and pagination, and how multi-domain and base path affect generated URLs. Use when adding meta tags or JSON-LD to a route, enabling or changing seoRoutes, fixing duplicate or wrong canonical or og:url URLs, or when a build fails for a missing site in seoRoutes. Do not use for route file naming (use `storefront-next:sfnext-routing`), site/locale config in general (use `storefront-next:sfnext-configuration`), or translations (use `storefront-next:sfnext-i18n`).
+---
+
+# Storefront Next SEO
+
+In-project references: `docs/README-SEO.md`, `docs/README-AEO-GEO.md`, `docs/README-MULTI-SITE.md` (URL Config), `docs/README-MULTI-DOMAIN.md`, `docs/README-BASE-PATH.md`, `docs/migrations/seo-url-rules/README.md`. Read them for depth; this skill is the task map.
+
+## Page metadata: SeoMeta
+
+```tsx
+import { SeoMeta } from '@/components/seo-meta';
+
+<SeoMeta title={t('meta.title', { defaultValue: 'My Page' })} description={t('meta.description', { defaultValue: '...' })} />
+<SeoMeta title="Checkout" noIndex />            {/* private/transactional pages */}
+<SeoMeta rawTitle title="Store Name" />         {/* no " | Site Name" suffix */}
+<SeoMeta title={name} openGraph={{ type: 'product', url: pageUrl, image }} />
+```
+
+Props (verified in `src/components/seo-meta/index.tsx`): `title`, `rawTitle`, `description`, `noIndex`, `siteName`, `twitter`, `openGraph`. Open Graph input auto-derives X card tags unless `twitter` is set. Use `noIndex` for cart, checkout, account, and other non-public pages. Root-level canonical and hreflang descriptors come from `src/utils/seo.ts` and `src/utils/canonical-url.ts`; routes do not add them.
+
+## Structured data: JsonLd
+
+```tsx
+import { JsonLd } from '@/components/json-ld';
+
+<JsonLd data={productSchema} id="product-schema" nonce={nonce} />
+```
+
+Pass the CSP nonce so the inline script is allowed. Builders live in `src/utils/product-schema.ts`, `category-schema.ts`, `schema-url.ts`. PDP emits `Product`; PLP emits `CollectionPage` + `ItemList` (see `docs/README-AEO-GEO.md`).
+
+## One URL everywhere
+
+Canonical `<link>`, `og:url` and JSON-LD `url` must agree. In loaders:
+
+```ts
+import { buildSeoPageUrl } from '@/lib/seo/page-url.server';
+import { redirectToCanonicalPath } from '@/lib/seo/canonical-redirect.server';
+
+redirectToCanonicalPath(requestUrl);                 // 301 for trailing slash
+const pageUrl = buildSeoPageUrl(context, requestUrl); // origin + canonical path/query
+```
+
+Only allowlisted query params survive in canonicals (`CONTENT_PARAMS` in `src/utils/canonical-url.ts`: `q`, `offset`, `sort`, `refine`, `pid` by default). Add a param only if it changes main page content, and add a test next to `canonical-url.test.ts`.
+
+## Configurable URLs: url.seoRoutes
+
+```ts
+// config.server.ts
+url: {
+  prefix: '/:siteId/:localeId',
+  seoRoutes: {
+    RefArchGlobal: { product: { prefix: 'p' }, category: { prefix: 'c', mode: 'id-suffix' } },
+  },
+}
+```
+
+Key rules (full playbook in [references/SEO-ROUTES.md](references/SEO-ROUTES.md)):
+
+- Build-time: changing `seoRoutes` requires a rebuild and redeploy (restart the dev server locally).
+- Every active site needs an entry, or URL generation throws / the build fails.
+- Business Manager URL settings are the source of truth; `seoRoutes` is a manual copy that must be kept in sync.
+- Do not rename route files. Routes are already generic; the config maps prefixes.
+- Build links with the semantic builders, never hardcoded `/product/...` strings:
+
+```tsx
+import { createProductUrl, createCategoryUrl } from '@/route-paths';
+import { useSeoUrlContext } from '@/hooks/use-seo-url-context';
+
+const ctx = useSeoUrlContext();
+<Link to={createProductUrl({ productId, slug }, ctx)} />
+```
+
+`seoFallback.sites` in config supplies per-site fallback behavior when a SEO URL cannot be resolved; see `docs/README-MULTI-SITE.md`.
+
+## Multi-domain and base path
+
+- Origin for canonicals comes from `getAppOrigin` (honors forwarded host, falls back to `EXTERNAL_DOMAIN_NAME`). Each custom domain must be attached to the Managed Runtime environment. See [references/MULTI-DOMAIN-BASE-PATH.md](references/MULTI-DOMAIN-BASE-PATH.md).
+- Mapping domains to sites uses an `X-Site-Id` header set by your CDN.
+- A base path (`MRT_ENV_BASE_PATH`, set from the push config) prefixes asset and route URLs; use `getBasePath()` rather than hardcoding.
+
+## Crawlers
+
+Crawlers receive full HTML rendering; category pages stay crawlable through a `?page=N` parameter with rel prev/next links, while the canonical stays the base category URL. Verify with `curl` and a crawler user agent. Check `docs/README-SEO.md` "Crawler Rendering and Pagination" before changing streaming behavior.
+
+## Related Skills
+
+- `storefront-next:sfnext-routing` - route modules and URL patterns
+- `storefront-next:sfnext-configuration` - config.server.ts and env overrides
+- `storefront-next:sfnext-i18n` - locales, hreflang inputs
+- `storefront-next:sfnext-hybrid-storefronts` - URLs owned by another storefront
+- `storefront-next:sfnext-security` - CSP nonce for JSON-LD
+- `storefront-next:sfnext-performance` - streaming vs crawler rendering

package/content/guidance/storefront-next/sfnext-seo/references/MULTI-DOMAIN-BASE-PATH.md

@@ -0,0 +1,17 @@
+# Multi-domain and base path effects on URLs
+
+In-project docs: `docs/README-MULTI-DOMAIN.md`, `docs/README-BASE-PATH.md`, `docs/README-MULTI-SITE.md`.
+
+## Multiple domains, one environment
+
+- Attach every domain to the Managed Runtime environment (custom domains in the MRT project; see `b2c-cli:b2c-mrt`).
+- The request host is read from the forwarded host header; `getAppOrigin` uses it for canonical, hreflang, and og URLs. `EXTERNAL_DOMAIN_NAME` is a fallback only.
+- To choose the Commerce site per domain, have the CDN send an `X-Site-Id` header (for example `site-a.shop.com` -> `RefArch`).
+- Only trust forwarded host behind your CDN; the doc has a section on trusting the forwarded host.
+- Images on custom domains need `realmHostMappings`; cookies are host-only by default (see `docs/README-COOKIE-DOMAIN.md`).
+
+## Base path
+
+- `MRT_ENV_BASE_PATH` is set by Managed Runtime from the push configuration (`ssrParameters.envBasePath`).
+- Server code reads `process.env.MRT_ENV_BASE_PATH`; client code derives it from the bundle path. Use `getBasePath()` (defined in your project's `src/lib/utils.ts`) when building URLs by hand.
+- Canonical URLs must include the base path; use `buildSeoPageUrl` instead of concatenating strings.

package/content/guidance/storefront-next/sfnext-seo/references/SEO-ROUTES.md

@@ -0,0 +1,31 @@
+# Adopting url.seoRoutes
+
+Source: `docs/migrations/seo-url-rules/README.md` and `docs/README-MULTI-SITE.md` (URL Config) in your project. Trust the code if they differ; verify `apply-seo-url-config` behavior in `@salesforce/storefront-next-dev`.
+
+## What it changes
+
+Without `seoRoutes` the storefront serves the built-in `/product/{id}` and `/category/{id}` grammar. With it, each site gets its own product and category prefix (for example `/p/{slug}/{id}`), matching Business Manager URL settings.
+
+## Checklist before enabling
+
+1. Runtime and dev packages are on a release that supports `seoRoutes` (see `docs/COMPATIBILITY.md`).
+2. Every active site has an entry in `url.seoRoutes`; a missing site fails.
+3. Decide the category mode per site: `id-suffix` (slug plus trailing category id) or slug-path (pure slug hierarchy).
+4. Protect routes that must not be captured by a product/category prefix with `protectedPaths` (build-time option described in the URL Config section).
+5. Leaf routes vs segments: check how the build validates overlapping prefixes.
+6. Keep Business Manager URL settings identical; there is no automatic sync.
+
+## Avoid breaking indexed URLs
+
+- Keep old URL shapes redirecting to the new canonical ones; `redirectToCanonicalPath` only normalizes trailing slashes, so test old `/product/{id}` URLs explicitly.
+- Audit hardcoded links; replace them with `createProductUrl` / `createCategoryUrl` and `useSeoUrlContext()`.
+- Legacy category paths can be converted with `createCategoryUrlFromLegacyPath` in `@/route-paths`.
+- Deploy, then crawl canonical, hreflang, and JSON-LD URLs for consistency.
+
+## Hybrid deployments
+
+If part of the catalog is served by another storefront, the storefront only owns the URLs routed to it; see `storefront-next:sfnext-hybrid-storefronts` and `docs/README-HYBRID-PROXY.md`.
+
+## Verifying
+
+Run `pnpm typecheck && pnpm test`, then request a product and category URL for each site and check the canonical `<link>`.

package/content/guidance/storefront-next/sfnext-state-management/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: sfnext-state-management
+description: >-
+  Choose the right state mechanism in a Storefront Next project: loader and action data, useRouteLoaderData, URL state with useSearchParams, cookies and sessions, optimistic UI (fetcher.formData, useNavigation, useOptimistic), React context providers (BasketProvider, AuthProvider, wishlist, product-context), and small useSyncExternalStore stores such as the mini-cart store. Use for "where should this state live", "useBasket", "useAuth", "share state between components", "optimistic add to cart", "global client state", "hydration mismatch from a store", or "do I need Zustand". Do not use for fetching or mutating data (use `storefront-next:sfnext-data-fetching`), controlling loader re-runs (use `storefront-next:sfnext-revalidation`), or login flows and sessions (use `storefront-next:sfnext-authentication`).
+---
+
+# Storefront Next State Management
+
+Server state lives in loaders and actions. Client state is small and local. There is no global client store library in the template (Zustand was removed): use the tools below in this order. `docs/README-STATE.md` and `docs/README-DATA.md` in your project cover each in depth.
+
+## Decision table
+
+| State | Use |
+|---|---|
+| Data from SCAPI | `loader` + `loaderData`; `action` for writes |
+| Another route's loader data | `useRouteLoaderData('routes/_app')` (route id = file path without extension) |
+| Filters, sort, pagination, tab | URL: `useSearchParams` / `useParams` (shareable, SSR-friendly) |
+| Must survive requests, read by server | cookies (`createCookie` from `@/lib/cookie-utils.server`) or session helpers |
+| Pending or optimistic result | `fetcher.formData`, `useNavigation`, `useOptimistic` |
+| Form fields, toggles, open/close in one component | `useState` / `useReducer` |
+| Shared by a subtree | React context with a provider at the owning layout |
+| Shared app-wide and read outside React, or high-frequency | module-level `useSyncExternalStore` store |
+| Request-scoped server values (site, auth, basket) | router `context` (middleware), read with `context.get(...)` |
+
+Prefer the earliest row that works. Never copy loader data into `useState` to "cache" it.
+
+## Existing providers and stores
+
+| Need | API |
+|---|---|
+| Basket | `BasketProvider` in `src/providers/basket.tsx`: `useBasket({ autoLoad })`, `useBasketSnapshot`, `useBasketHydrated`, `useBasketError`, `useBasketUpdater`, `useBasketReset`, `useBasketLoader`, `useBasketReconcile`; `BasketCookieReconciler` syncs the cookie |
+| Session info | `useAuth()` from `@/providers/auth` |
+| Product / variant selection | `@/providers/product-context`, `@/providers/product-view` |
+| Image widths | `DynamicImageProvider` (`@/providers/dynamic-image`) |
+| Wishlist | `src/providers/wishlist.ts` (module-level store) |
+| Mini-cart open state | `useMiniCartStore`, `setMiniCartOpen` in `src/hooks/mini-cart-store.ts` |
+| Cart toast | `src/hooks/cart-mutation-toast-store.ts` |
+| Shopper context | `useShopperContext` (`@/hooks/use-shopper-context`) |
+
+The basket is loaded through `useScapiFetcher('shopperBasketsV2', 'getBasket')` and is updated from action results via `updateBasketResource` (server side, `@/middlewares/basket.server`), so after a basket action components simply re-render from `useBasket()`. The `__sfdc_basket` cookie carries the basket id; `__sfdc_usertype` is the user-type hint. Do not read these directly in components; use the hooks. Server reads: `getBasket`, `getBasketSnapshot`, `ensureBasketId`, `destroyBasket`, and `getAuth`, `updateAuth`, `destroyAuth` from `@/middlewares/auth.server`.
+
+## Optimistic UI
+
+```tsx
+const fetcher = useFetcher<typeof action>();
+const removing = fetcher.formData?.get('itemId') === item.itemId;
+return <li hidden={removing}>...</li>;
+```
+
+Use `useOptimistic` for values the server will confirm, and `useNavigation` for URL-driven pending states. Roll back by reading the confirmed `loaderData`/basket value; never hand-maintain a parallel copy.
+
+## A small external store
+
+Use when state is global, changes often, or must be set outside React. Follow `src/hooks/mini-cart-store.ts`:
+
+```ts
+import { useSyncExternalStore } from 'react';
+
+interface State { open: boolean }
+let state: State = { open: false };
+const SERVER_STATE: State = Object.freeze({ open: false });
+const listeners = new Set<() => void>();
+
+const subscribe = (l: () => void) => { listeners.add(l); return () => void listeners.delete(l); };
+export const setOpen = (open: boolean) => {
+    if (open === state.open) return;         // skip no-op writes
+    state = { ...state, open };
+    listeners.forEach((l) => l());
+};
+export function useDrawerStore<T>(select: (s: State) => T): T {
+    return useSyncExternalStore(subscribe, () => select(state), () => select(SERVER_STATE));
+}
+```
+
+Rules:
+
+- `getSnapshot` must return a referentially stable value when nothing changed. Select primitives; a selector that allocates per call loops forever.
+- Provide a server snapshot and mutate only from events or effects so SSR and the first client render match (no hydration warnings).
+- Split stores by independent writers so each consumer subscribes to a slice.
+- For an instance-based store (one per widget), create it in a factory and provide it by context, as `createStoreLocatorStore` does in the store-locator extension.
+
+## Context providers
+
+- Put the provider at the lowest layout that contains all consumers.
+- Memoize the `value` (`useMemo`, `useCallback`) and split read-only state from updaters into separate contexts so updater-only consumers do not re-render.
+- Use a selector pattern for large contexts (see README-STATE "Context Selector Pattern").
+- Values used only inside callbacks belong in `useRef`, not context state.
+- Compose providers with `src/providers/compose-providers.tsx`.
+
+More patterns and anti-patterns in [PATTERNS.md](references/PATTERNS.md).
+
+## Common mistakes
+
+| Mistake | Instead |
+|---|---|
+| `useEffect` that fetches on mount and stores in state | loader (or streamed promise) |
+| Copying `loaderData` or basket into `useState` | read directly; derive with plain expressions |
+| Filters in `useState` | `useSearchParams` |
+| Reading cookies in components | loader returns the value, or use the provider hook |
+| New context for one component's state | `useState` in that component |
+| Adding Zustand or Redux | the mechanisms above; check `storefront-next:sfnext-overview` for conventions |
+
+## Finding more
+
+`AGENTS.md` ("Key Documentation"), `docs/README-STATE.md`, `docs/README-DATA.md`. `b2c docs search "storefront next state"` or the `docs_search` MCP tool.
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - loaders, actions, fetchers
+- `storefront-next:sfnext-revalidation` - when providers make a re-run unnecessary
+- `storefront-next:sfnext-performance` - hydration stability and render scope
+- `storefront-next:sfnext-authentication` - `useAuth` and session lifecycle
+- `storefront-next:sfnext-commerce-features` - cart, wishlist, checkout features
+- `storefront-next:sfnext-components` - component conventions

package/content/guidance/storefront-next/sfnext-state-management/references/PATTERNS.md

@@ -0,0 +1,45 @@
+# State patterns and anti-patterns
+
+## Render scope should not exceed data-change scope
+
+If a value changes often but only event handlers read it, do not store it in state or Context. Keep it in a `useRef` or read it at call time (for example `window.matchMedia(...).matches` inside the handler). Every state change re-renders the component and all consumers of a Context value.
+
+Hidden subscribers: a component that subscribes to a store but renders nothing visible (an invisible drawer) still re-renders. Return `null` early or move the subscription to the component that renders the content.
+
+## Provider value stability
+
+```tsx
+const value = useMemo(() => ({ items, isOpen }), [items, isOpen]);
+const actions = useMemo(() => ({ open, close }), [open, close]); // useCallback inside
+return (
+    <StateContext.Provider value={value}>
+        <ActionsContext.Provider value={actions}>{children}</ActionsContext.Provider>
+    </StateContext.Provider>
+);
+```
+
+Check each field read during render: if a consumer uses only `isOpen`, it still re-renders when `items` changes with one combined context. Split or use a selector.
+
+## Manager components
+
+A component that only subscribes to data to perform a side effect (for example syncing the basket cookie, like `BasketCookieReconciler`) should render `null` and live as a leaf so the parent is not re-rendered.
+
+## Server versus client snapshots
+
+For `useSyncExternalStore`, `getServerSnapshot` must equal what the first client render will read, or React warns and re-renders. Read browser-only data (storage, matchMedia) after mount in an effect and then write it into the store.
+
+## URL state
+
+Prefer URL state for anything a shopper might share or reload. Changing search params triggers navigation and loader re-run; see `storefront-next:sfnext-revalidation` to skip re-runs for client-only params. Use `setSearchParams(next, { replace: true, preventScrollReset: true })` for high-frequency updates such as typing.
+
+## Cookies
+
+Cookies written by the server are set from `action` or middleware responses. Use the helpers in `src/lib/cookie-utils.server.ts` (site-scoped names, domain resolution, `createCookie`). Do not store personal data or tokens in cookies readable by scripts. Consent state is covered by `storefront-next:sfnext-analytics-consent`.
+
+## Derived state
+
+Compute derived values during render. `useMemo` is for expensive pure computations of UI-derived values; it does not fix transforming loader data in render (do that in the loader) and must not wrap promises.
+
+## Testing state
+
+Render with the real provider in tests, or mock the hook module (`vi.mock('@/providers/basket')`). For stores, call the exported setters inside `act` and reset module state between tests. See `storefront-next:sfnext-testing`.