@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/storefront-next/sfnext-extensions/references/EXTENSION-EXAMPLES.md

@@ -0,0 +1,79 @@
+# Extension Examples
+
+Read the shipped extensions in `src/extensions/` before writing your own; these three cover the common shapes. Confirm paths in your project, since extensions evolve.
+
+## Simplest: BNPL (one slot, one API module)
+
+```
+src/extensions/bnpl/
+├── target-config.json
+├── components/            # includes components/target/bnpl-target.tsx
+├── context/               # bnpl-context
+├── lib/api/bnpl.server.ts # mock provider calls; replace bodies for a real provider
+├── locales/
+└── README.md
+```
+
+```json
+{
+  "components": [
+    { "targetId": "sfcc.pdp.bnpl.message", "path": "extensions/bnpl/components/target/bnpl-target.tsx", "order": 0 }
+  ]
+}
+```
+
+The target component is a thin default-exported adapter: it reads a context (`useBnpl()`), returns `null` when there is nothing to show, and wraps streamed promises in `Suspense`/`Await`. Keep slot components small and null-safe, because the slot renders wherever the base places it.
+
+## Several slots: Ratings and Reviews
+
+Three entries in one `target-config.json` fill three different places:
+
+| targetId | Component |
+|----------|-----------|
+| `sfcc.pdp.reviews.section` | `components/target/reviews-section-target.tsx` |
+| `sfcc.pdp.reviews.rating` | `components/target/reviews-summary-target.tsx` |
+| `sfcc.account.orderDetail.lineReview` | `components/target/order-line-review-target.tsx` |
+
+It also has `context/`, `providers/`, `routes/`, `lib/` and `locales/`. Pattern: one target adapter per slot, shared logic in context and `lib`.
+
+## Routes, provider, middleware: Store Locator
+
+```
+src/extensions/store-locator/
+├── target-config.json              # sfcc.header.before.cart -> components/header/store-locator-badge.tsx
+├── components/  context/  hooks/  stores/  locales/  tests/
+├── middlewares/                    # wired into base files via SFDC_EXT_ markers
+├── providers/store-locator.tsx     # mounted in root.tsx via @sfdc-extension-block markers
+└── routes/
+    ├── _app.store-locator.tsx          # page inside the app layout
+    ├── action.set-selected-store.ts    # action route
+    └── resource.stores.ts              # resource (JSON) route
+```
+
+This extension needs edits outside its folder (for example `root.tsx` and other base components), which is why it uses `SFDC_EXT_STORE_LOCATOR` markers; see [CLI and Install](CLI-AND-INSTALL.md). Route file names follow flat-route conventions: `_app.` prefix for routes in the app layout, `action.` and `resource.` for non-UI routes.
+
+## Wrapper slot
+
+A slot that has children keeps the base content and lets the extension decorate it (for example `sfcc.emailSignUp.consent.marketing`). The component receives `children`:
+
+```tsx
+import type { ReactNode } from 'react';
+
+export default function ConsentWrapper({ children }: { children?: ReactNode }) {
+    return <div className="rounded border p-2">{children}</div>;
+}
+```
+
+Use `pnpm extensions:list` to see which slots are wrappers in your project.
+
+## Server hook: fraud check
+
+See [Action Hooks](ACTION-HOOKS.md) for a `sfcc.checkout.fraud.beforePlace` handler and the blocking rules.
+
+## Checklist for a new extension
+
+1. Run the [Base Audit](BASE-AUDIT.md) gate.
+2. `sfnext extensions create -n "Name" -d "..."`.
+3. Add components, then `target-config.json` entries with `sfcc.` target ids from `pnpm extensions:list`.
+4. Add `locales/<lang>/translations.json` and use the `ext<PascalName>` namespace.
+5. Run `pnpm dev`, check the slot in the browser, then `pnpm typecheck && pnpm lint`.

package/content/guidance/storefront-next/sfnext-hybrid-storefronts/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sfnext-hybrid-storefronts
+description: >-
+  Run Storefront Next alongside an existing SFRA or SiteGenesis storefront for a gradual migration. Use for hybrid mode, PUBLIC__app__hybrid__enabled, legacyRoutes (exact, :param, * wildcard, { pattern, suffix }), HYBRID_PROXY_ENABLED, SFCC_ORIGIN, HYBRID_ROUTING_RULES, vite-plugins/hybrid-proxy.ts, the dwsid session bridge, sharing login/cart between SFRA and Storefront Next, eCDN routing rules, cookie domain for hybrid, "[Hybrid Proxy] SFCC returned a redirect to 404", blank proxied pages, or lost sessions when crossing storefronts. Do not use for the cookie-domain settings themselves beyond the hybrid checklist (use `storefront-next:sfnext-security`), auth code (use `storefront-next:sfnext-authentication`), or MRT deployment (use `storefront-next:sfnext-deployment`).
+---
+
+# Hybrid Storefronts
+
+A hybrid storefront serves some pages from Storefront Next (on Managed Runtime) and the rest from SFRA/SiteGenesis on the B2C instance, under one hostname.
+
+- **Production:** Cloudflare eCDN routes by URL pattern (see `b2c-cli:b2c-ecdn`). The dev proxy is never used.
+- **Local development:** a Vite dev-server plugin proxies non-Storefront-Next paths to your sandbox so both appear at `http://localhost:5173`. It only runs under `pnpm dev` and is a no-op in production builds. Full guide: `docs/README-HYBRID-PROXY.md` in your project.
+
+## Two sets of configuration
+
+| Set | Variables | Where it applies |
+|---|---|---|
+| App config | `PUBLIC__app__hybrid__enabled`, `PUBLIC__app__hybrid__legacyRoutes` | **Every** environment (local, staging, production) |
+| Dev proxy | `HYBRID_PROXY_ENABLED`, `SFCC_ORIGIN`, `HYBRID_ROUTING_RULES`, `HYBRID_PROXY_LOCALE`, `PUBLIC__app__defaultSiteId` | `pnpm dev` only |
+
+```bash
+PUBLIC__app__hybrid__enabled=true
+PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id", "/categoryLv1/*"]'
+
+HYBRID_PROXY_ENABLED=true
+SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com   # your sandbox hostname, not the SCAPI host
+HYBRID_PROXY_LOCALE=en-GB                                       # optional; falls back to i18n fallbackLng
+HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/login.*" or http.request.uri.path matches "^/logout.*" or http.request.uri.path matches "^/signup.*" or http.request.uri.path matches "^/reset-password.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/social-callback.*" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/search.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*")'
+```
+
+`HYBRID_ROUTING_RULES` lists what **Storefront Next owns** (same Cloudflare `http.request.uri.path matches "<regex>"` clauses, joined by `or`, as your eCDN rules). Anything not matching is proxied to SFRA. `^/resource.*` and `^/action/.*` are always required. Include every auth route you migrated (`/login`, `/logout`, `/signup`, `/reset-password`, `/social-callback`) or login breaks. `legacyRoutes` is the inverse: what SFRA owns, so a `<Link>` to it forces a full page load instead of a React Router 404. Keep both in sync with the production eCDN rules.
+
+## legacyRoutes patterns
+
+Each entry is a string or `{ pattern, suffix }`.
+
+| Form | Example | Matches |
+|---|---|---|
+| Exact | `/cart` | `/cart` only |
+| Named param | `/product/:id` | one segment |
+| Wildcard | `/categoryLv1/*` | anything under the prefix (`/categoryLv1/shoes/running`), **not** the bare `/categoryLv1` (list it separately); `*` may appear mid-pattern |
+| Catch-all | `*` | every path |
+| With suffix | `{ "pattern": "/product/:id", "suffix": ".html" }` | redirect appends `.html` (SFCC SEO URLs) |
+
+The matching middleware is `src/middlewares/legacy-routes.client.ts` (helpers in `legacy-routes.ts`). The eCDN regex `^/categoryLv1.*` matches the bare path while `/categoryLv1/*` does not; use `^/categoryLv1(/.*)?$` on the eCDN side to align them.
+
+## Session bridge
+
+There is no token exchange and no client-side sync. The bridge is the `dwsid` cookie (plus `dw_dnt` for tracking consent):
+
+1. Storefront Next's auth middleware extracts `dwsid` from the SLAS response and persists it.
+2. `dwsid` and `dw_dnt` are **not** site-namespaced, so SFRA reads and writes them directly. Other `cc-*` cookies are namespaced per site and are Storefront Next's own.
+3. The browser sends them on every request; the next full request to either side sees the shared session.
+
+For this to work across subdomains, cookie domain must be configured on **both** sides and agree: `app.cookies.domain` (or `commerce.sites[].cookies.domain`, or `PUBLIC__app__cookies__domain=.example.com`) in Storefront Next, and Business Manager > Merchant Tools > Site Preferences > **Hybrid Auth Settings** cookie-domain level `2` (level `0` is host-only; level `1` is rejected). Details and verification checklist: `storefront-next:sfnext-security` and `docs/README-COOKIE-DOMAIN.md`. Cookie inventory: `storefront-next:sfnext-authentication`.
+
+## Edit the proxy where customers edit it
+
+The plugin is wired in `vite-plugins/hybrid-proxy.ts` (called from `vite.config.ts`, development mode only). Edit there, not in `vite.config.ts`. It reads `url.prefix` and the site/locale alias catalog from `config.server.ts` automatically.
+
+- **Path rewriting:** `/cart` becomes `/s/<siteId>/<locale>/cart`, `/` becomes `/s/<siteId>`. With `url.prefix` of `/:localeId` or `/:siteId/:localeId` the proxy reuses the site/locale already in the path (`/uk/cart` becomes `/s/<siteId>/uk/cart`), and only treats a segment as site/locale if it is a known id or alias.
+- **Escape hatches (last resort):** `rewritePath(pathname)` returns an SFRA path or `null` to fall through; `routeMatcher(pathname, rules)` replaces the matcher. Keep `shouldRouteToNext` as the fallback so dev stays aligned with eCDN.
+- Target origin priority: `SFCC_ORIGIN`, then `SCAPI_PROXY_HOST`, then the SCAPI host from `shortCode`.
+
+## Automatic behaviors
+
+- Rewrites `Domain=.salesforce.com` cookies to `localhost`, rewrites SFCC URLs in HTML/JSON bodies, decompresses gzip/brotli/deflate before rewriting, and injects a `document.cookie` interceptor into proxied HTML (localhost workaround only, not used in production).
+- Never proxies Vite internals, `*.data`, `/mobify/*` and static asset extensions; always proxies `/on/demandware.static/*` and `/on/demandware.store/*`.
+- SFRA `plugin_redirect` answering `200` with a `Location` header is converted to a `302`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Logged out after visiting a Storefront Next page; log says `[Hybrid Proxy] SFCC returned a redirect to 404` | A migrated route is missing from `HYBRID_ROUTING_RULES`; SFCC 404s and clears cookies (proxy strips those `Set-Cookie`s) | Add the path pattern |
+| React Router 404 or error boundary when clicking a legacy link | Path missing from `legacyRoutes` | Add it (mind `*` vs bare parent) |
+| Session lost crossing storefronts | Cookie domain mismatch, or BM Hybrid Auth level differs | Align both sides; check for duplicate cookies |
+| Blank proxied page | Upstream `200` + `Location` (fixed in dev), or unsupported compression | Fix the SFRA cartridge or add an eCDN rule for production |
+| Works locally, wrong backend in production | `HYBRID_ROUTING_RULES` drifted from eCDN rules | Sync them |
+| Wrong locale in the SFRA path | `url.prefix` or `HYBRID_PROXY_LOCALE` mismatch | Check `url.prefix`; set `HYBRID_PROXY_LOCALE` to the site's default locale |
+| Proxy does nothing | `HYBRID_PROXY_ENABLED` not `true`, or not in dev mode | Check `.env` and `pnpm dev` |
+
+Env-var reference, path transformation and custom matcher: [references/HYBRID-PROXY-CONFIG.md](references/HYBRID-PROXY-CONFIG.md).
+
+## Related Skills
+
+- `storefront-next:sfnext-authentication` - cookies and SLAS sessions
+- `storefront-next:sfnext-security` - cookie domain, CSP
+- `storefront-next:sfnext-deployment` - MRT deployment
+- `storefront-next:sfnext-configuration` - `config.server.ts` and `PUBLIC__` overrides
+- `storefront-next:sfnext-routing` - site/locale URL prefixes
+- `b2c-cli:b2c-ecdn` - production routing rules
+- `b2c-cli:b2c-mrt` - Managed Runtime environments

package/content/guidance/storefront-next/sfnext-hybrid-storefronts/references/HYBRID-PROXY-CONFIG.md

@@ -0,0 +1,86 @@
+# Hybrid Proxy Configuration Reference
+
+Authoritative guide in your project: `docs/README-HYBRID-PROXY.md`. Plugin wiring: `vite-plugins/hybrid-proxy.ts`.
+
+## Environment variables
+
+| Variable | Scope | Purpose |
+|---|---|---|
+| `PUBLIC__app__hybrid__enabled` | all environments | Activates the client-side legacy-routes middleware. Default `false`. |
+| `PUBLIC__app__hybrid__legacyRoutes` | all environments | JSON array of SFRA-owned routes (strings or `{ pattern, suffix }`). |
+| `HYBRID_PROXY_ENABLED` | dev only | `true` turns the proxy on. |
+| `SFCC_ORIGIN` | dev only | Full HTTPS URL of the SFRA sandbox. Highest priority target. |
+| `SCAPI_PROXY_HOST` | dev only | Secondary target-origin override. |
+| `HYBRID_ROUTING_RULES` | dev only | Cloudflare-style expression of paths Storefront Next owns. |
+| `HYBRID_PROXY_LOCALE` | dev only, optional | Fallback locale for the SFRA path; else `PUBLIC__app__i18n__fallbackLng`, else `default`. |
+| `PUBLIC__app__defaultSiteId` | dev | Site id used in `/s/<siteId>/...`. |
+
+`hybrid` defaults to `{ enabled: false, legacyRoutes: [] }` in `config.server.ts`.
+
+## Routing rule format
+
+```
+(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")
+```
+
+Only `http.request.uri.path matches "<regex>"` clauses joined by `or` are parsed. Always include `^/resource.*` and `^/action/.*`. `.data` requests are excluded automatically.
+
+| Pattern | Route |
+|---|---|
+| `^/$` | Home |
+| `^/login.*`, `^/logout.*`, `^/signup.*`, `^/reset-password.*` | Auth pages |
+| `^/account.*` | Account |
+| `^/product.*`, `^/category.*`, `^/search.*` | Catalog |
+| `^/social-callback.*` | Social login callback |
+
+## Path transformation
+
+| Browser URL | Proxied to |
+|---|---|
+| `/` | `/s/<siteId>` |
+| `/cart` | `/s/<siteId>/<locale>/cart` |
+| `/on/demandware.static/...`, `/s/...` | unchanged |
+
+With `url.prefix` set in `config.server.ts`:
+
+| `url.prefix` | URL | Proxied to |
+|---|---|---|
+| `/:localeId` | `/uk/cart` | `/s/<siteId>/uk/cart` |
+| `/:localeId` | `/cart` | `/s/<siteId>/<fallback locale>/cart` (`cart` is not a known locale) |
+| `/:siteId/:localeId` | `/global/en-GB/cart` | `/s/global/en-GB/cart` |
+
+Query strings are preserved.
+
+## Cookie layers (local dev)
+
+1. Set-Cookie headers from SFCC: `Domain=.salesforce.com` rewritten to `localhost`.
+2. Storefront Next's own cookies are written to `localhost` directly.
+3. Injected `document.cookie` patch in proxied HTML so SFRA client-side cookie writes get the same treatment (SFRA omits `Secure` on `http://localhost`). Localhost-only; no production equivalent.
+
+## Custom matcher (last resort)
+
+Edit `vite-plugins/hybrid-proxy.ts`:
+
+```typescript
+import { hybridProxyPlugin, shouldRouteToNext } from '@salesforce/storefront-next-dev';
+
+hybridProxyPlugin({
+    // ...existing options...
+    routeMatcher: (pathname, rules) => {
+        if (pathname === '/my-custom-page') return true;   // Storefront Next
+        if (pathname === '/legacy-only') return false;     // SFRA
+        return shouldRouteToNext(pathname, rules);         // default eCDN-style matching
+    },
+    // rewritePath: (pathname) => myRewrite(pathname) ?? null, // non-standard URL models only
+});
+```
+
+If the matcher throws, the request falls through to React Router. Overriding the matcher means local routing no longer matches eCDN behavior; avoid unless necessary.
+
+## Gotchas
+
+- Rules out of sync with eCDN: local behavior differs from production.
+- A proxied path that does not exist on SFRA returns whatever SFCC returns.
+- `HYBRID_PROXY_LOCALE` must be a locale SFRA accepts in `/s/<site>/<locale>/`; match the site's `defaultLocale`.
+- Unsupported compression formats skip body rewriting and leak SFCC URLs.
+- Production: do not rely on the plugin; configure eCDN routing (`b2c-cli:b2c-ecdn`) and the same cookie domain on both sides.

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

@@ -0,0 +1,152 @@
+---
+name: sfnext-i18n
+description: >-
+  Translate and localize a Storefront Next storefront with i18next: useTranslation in components, getTranslation in loaders/actions/utilities, translations.json namespaces, pluralization and interpolation, Zod validation-message factories, adding a new language or locale, extension translations, and locale/currency switching. Use when adding or editing strings, "add a Brazilian Portuguese locale", supportedLngs / fallbackLng / supportedLocales, src/locales, locales:aggregate-extensions, LocaleSwitcher, mockI18nContext, hydration mismatch on translated text, or missing-key problems. Do not use for site/locale URL prefix routing (use `storefront-next:sfnext-routing`), site and currency configuration keys (use `storefront-next:sfnext-configuration`), or extension scaffolding (use `storefront-next:sfnext-extensions`).
+---
+
+# Storefront Next Internationalization
+
+Storefront Next uses `i18next` with a server instance (all languages loaded) and a browser instance (loads the active language as a static JS chunk). The infrastructure comes from `@salesforce/storefront-next-runtime/i18n`; your project owns the translations in `src/locales/`. The full guide ships in your project as `docs/README-I18N.md`. Caution: its locale-detection and `set-locale` passages are outdated; trust the code and this skill.
+
+## Which API to use
+
+| Where | API |
+|-------|-----|
+| React components | `useTranslation` from `react-i18next` |
+| Loaders, actions, middleware, utilities, tests | `getTranslation` from `@salesforce/storefront-next-runtime/i18n` |
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+export function AddToCart({ count }: { count: number }) {
+    const { t } = useTranslation('product'); // namespace = top-level key in translations.json
+    return <button>{t('addToCart', { count })}</button>;
+}
+```
+
+```ts
+import type { LoaderFunctionArgs } from 'react-router';
+import { getTranslation } from '@salesforce/storefront-next-runtime/i18n';
+
+export function loader({ context }: LoaderFunctionArgs) {
+    const { t } = getTranslation(context); // server: pass the router context
+    return { title: t('product:title') };
+}
+```
+
+- Without a namespace argument, prefix keys: `useTranslation()` then `t('product:title')` works. You lose key autocomplete, not correctness.
+- Client-only non-component code may call `getTranslation()` with no argument.
+- Other exports from the same module: `getLocale`, `mockI18nContext` (tests), `createI18nMiddleware`.
+
+## File layout
+
+```
+src/locales/
+├── index.ts               # barrel: explicit import of every locale
+├── types.ts               # DeepPartial<T>
+└── en-US/
+    ├── index.ts           # merges translations.json + aggregated extension strings
+    └── translations.json  # ONE file; each top-level key is a namespace
+```
+
+The project ships 17 locale directories (`ls src/locales`). Each `translations.json` is a single file whose top-level keys (`product`, `cart`, `checkout`, `routeError`, ...) are namespaces. There is no separate per-namespace file.
+
+```json
+{
+    "product": {
+        "addToCart": "Add to cart",
+        "greeting": "Hello, {{name}}!",
+        "itemCount_one": "{{count}} item",
+        "itemCount_other": "{{count}} items"
+    }
+}
+```
+
+- Interpolation uses `{{var}}`.
+- Plurals use i18next suffix keys (`_one`, `_other`, plus `_zero`, `_few`, ... where a language needs them), as in the shipped files. Call `t('itemCount', { count })` with the base key. Do not use nested `{ one, other }` objects.
+- `t()` key types come from the `en-GB` resources (`src/middlewares/i18next.server.ts`). Non-English locales are typed `satisfies DeepPartial<typeof enUS>`, so they may omit keys (i18next falls back to `fallbackLng`) but keys they include must match the English shape.
+
+To customize copy, edit `translations.json` directly.
+
+## Add a new locale (checklist)
+
+Keep these in sync or the locale silently never appears:
+
+1. Create `src/locales/pt-BR/index.ts` and `translations.json`. Copy an existing locale (for example `de-DE`, which carries the `DeepPartial` typing) and translate.
+2. Import and register it in the barrel `src/locales/index.ts` (both the import and the exported object).
+3. Add the id to `i18n.supportedLngs` in `config.server.ts` (and check `fallbackLng`).
+4. Add `{ id: 'pt-BR', preferredCurrency: 'BRL' }` to the site's `supportedLocales`, and make sure that currency is in the site's `supportedCurrencies`. The shape is `commerce.sites[]`; see `storefront-next:sfnext-configuration`.
+5. Add extension translations for the new locale (`src/extensions/<ext>/locales/pt-BR/translations.json`) if the extensions you use ship translations.
+6. Run `pnpm locales:aggregate-extensions` (also run automatically by `pnpm dev` and `pnpm build`).
+7. Verify: `pnpm dev`, then open the site under the new locale prefix and switch via the locale switcher.
+
+Details and currency rules: [references/locale-config.md](references/locale-config.md).
+
+## How the active locale is chosen
+
+The locale is resolved from the site context, driven by the URL prefix (default `/:siteId/:localeId`, from `config.url.prefix`). `siteContextMiddleware` runs before `i18nextMiddleware` (see the middleware array in `src/root.tsx`). It is not read from a `lng` cookie or `Accept-Language`.
+
+`src/components/locale-switcher` changes locale by navigating to the same page under the rebuilt prefix (`buildUrl`, `resolvePrefix`, `stripPathPrefix` from `@salesforce/storefront-next-runtime/site-context`) and posting the choice to persist it. There is no `action.set-locale` route. Render it with `import LocaleSwitcher from '@/components/locale-switcher'`. Currency is switched independently with `src/components/currency-switcher`.
+
+## Extension translations
+
+Each extension keeps its strings in `src/extensions/<name>/locales/<locale>/translations.json`. Its namespace is `ext` + PascalCase directory name:
+
+```tsx
+const { t } = useTranslation('extStoreLocator'); // src/extensions/store-locator
+```
+
+`src/extensions/locales/<locale>/index.ts` is generated by `pnpm locales:aggregate-extensions`. Never edit it, and leave its `// @sfdc-extension-line` marker comments alone.
+
+## Validation messages: Zod schema factories
+
+Module-level `t()` runs before i18next is initialized. Build the schema from a function:
+
+```tsx
+import { useMemo } from 'react';
+import { z } from 'zod';
+import type { TFunction } from 'i18next';
+import { useTranslation } from 'react-i18next';
+
+export const createSchema = (t: TFunction) =>
+    z.object({ email: z.string().email(t('validation:emailInvalid')) });
+
+function MyForm() {
+    const { t } = useTranslation();
+    const schema = useMemo(() => createSchema(t as unknown as TFunction), [t]);
+    // useForm({ resolver: zodResolver(schema) })
+}
+```
+
+`createCustomerProfileFormSchema` in `src/components/customer-profile-form/index.tsx` is a working example.
+
+## Testing translations
+
+`vitest.setup.ts` initializes i18next with all locales (language `en-GB`), so components using `useTranslation` render real English text. For loaders/actions, `createTestContext({ locale })` from `@/lib/test-utils` wires `mockI18nContext` for you; call it directly when building a context by hand. Assert on text with `getTranslation()` or literal English. Locale completeness tests (for example `src/locales/*.locale-completeness.test.ts`) are a good pattern for feature-specific keys. See `storefront-next:sfnext-testing`.
+
+## Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Importing `getTranslation` from `@/lib/i18next` | It lives in `@salesforce/storefront-next-runtime/i18n`. |
+| Importing `@salesforce/storefront-next-runtime/i18n/client` from a `*.server.ts` file | Browser-only; it fails to bundle and lint blocks it. |
+| Statically importing `@/locales` in `root.tsx` or the error boundary | Pulls every language into the client bundle; `src/locales/locale-imports.test.ts` guards this. The root loader passes `errorTranslations` (the `routeError` bundle) instead. |
+| New locale not showing up | Check all of: `src/locales/index.ts`, `supportedLngs`, site `supportedLocales`. |
+| `t()` at module scope | Use a factory or call inside the component/function. |
+| Hydration mismatch on translated text | `src/i18n-client-init.ts` gates hydration with `whenI18nReady()`; do not bypass it. |
+| Same key name in two namespaces | Use `t('ns:key')` to disambiguate. |
+| "Click here" style link text | `jsx-a11y/anchor-ambiguous-text` cannot see translated strings; review link copy in JSON (see `storefront-next:sfnext-accessibility`). |
+
+## Finding more
+
+- `docs/README-I18N.md` (architecture, currency flow, using a different i18n library) and the doc index in `AGENTS.md`.
+- `b2c docs search "i18n"` (or the MCP `docs_search` tool) for the Storefront Next docs corpus.
+
+## Related Skills
+
+- `storefront-next:sfnext-configuration` - `i18n`, `supportedLocales`, `supportedCurrencies` config
+- `storefront-next:sfnext-routing` - site/locale URL prefix and site-aware links
+- `storefront-next:sfnext-extensions` - extension structure and `ext*` namespaces
+- `storefront-next:sfnext-components` - using translations in UI components
+- `storefront-next:sfnext-testing` - unit and story tests
+- `storefront-next:sfnext-accessibility` - translated link and label text

package/content/guidance/storefront-next/sfnext-i18n/references/locale-config.md

@@ -0,0 +1,35 @@
+# Locale and currency configuration
+
+Locale support is declared in several places that must agree. All keys below live in `config.server.ts`; see `storefront-next:sfnext-configuration` and `docs/README-CONFIG-OPTIONS.md` for the full option reference.
+
+## Must stay in sync
+
+| Place | What |
+|-------|------|
+| `i18n.supportedLngs` / `i18n.fallbackLng` | Languages the app serves; `src/middlewares/i18next.server.ts` reads them |
+| `commerce.sites[].supportedLocales` | `{ id, preferredCurrency }` per locale, per site |
+| `commerce.sites[].supportedCurrencies` | Currencies a shopper may pick; each `preferredCurrency` must be listed |
+| `src/locales/<id>/` + `src/locales/index.ts` | Translation files and barrel registration |
+
+Rules of thumb:
+
+- Every id in `supportedLngs` needs a directory in `src/locales/` and an entry in the barrel.
+- Every id in `supportedLngs` should appear in at least one site's `supportedLocales`; the locale switcher only lists languages that are in both `supportedLngs` and the current site's `supportedLocales`.
+- Different sites can expose different subsets of locales.
+- Env overrides use the `PUBLIC__` double-underscore convention described in `docs/README-CONFIG.md`.
+
+## Currency
+
+Locale and currency switch independently. Priority: shopper's manual choice (cookie) over the locale's `preferredCurrency` over the site default currency. The UI is `src/components/currency-switcher`.
+
+## Typing
+
+`src/middlewares/i18next.server.ts` augments i18next `CustomTypeOptions` with the `en-GB` resources so `t('ns:key')` is type-checked. `src/locales/types.ts` exports `DeepPartial`; non-English locales use `satisfies ResourceLanguage satisfies DeepPartial<typeof enUS>`. Run `pnpm typecheck` after adding keys: a key present in a translated locale but missing in English, or with a different nested shape, fails the type check.
+
+## Client loading
+
+`src/i18n-client-init.ts` calls `initI18next` from `@salesforce/storefront-next-runtime/i18n/client` with a `loadLocale` that dynamically imports `@/locales/<language>/index.ts`, so each language becomes its own chunk. `whenI18nReady()` delays hydration until the active language chunk is loaded (with a timeout safety net). Keep the `import()` template there so Vite can split the chunks.
+
+## Using a different i18n library
+
+i18next is only the translation layer; locale resolution is independent (site context). `docs/README-I18N.md` ("Using a Different i18n Library") describes what to replace.

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

@@ -0,0 +1,101 @@
+---
+name: sfnext-overview
+description: >-
+  Start here for any Salesforce Commerce Storefront Next (sfnext) task: a router that maps what you want to do to the right storefront-next skill, says to read your project's AGENTS.md and docs/README-*.md first, and carries a cheat sheet for the sfnext CLI, the b2c CLI, the b2c-dx-mcp tools, and the docs search fallback. Use when starting work in a Storefront Next project, when unsure which skill applies, when asked "how do I do X in Storefront Next", "what commands exist", or "where is the documentation". Do not use once a specific area is clear; go straight to that skill (for example `storefront-next:sfnext-routing` or `storefront-next:sfnext-seo`).
+---
+
+# Storefront Next Overview and Router
+
+## Before anything else
+
+1. Read `AGENTS.md` at your project root. It is the source of truth for project structure, commands, and conventions; skills never override it.
+2. Check `docs/README-*.md` (one per topic) and `instructions/*.mdc` in the project. Prefer them over memory.
+3. Versions and compatibility: `docs/COMPATIBILITY.md` and `package.json#storefrontNext`.
+4. Requirements: Node >= 24, pnpm >= 10.28.
+
+## Which skill for which task
+
+| I want to... | Skill |
+|---|---|
+| Create a project, install, run locally, pick a starter theme | `storefront-next:sfnext-project-setup` |
+| Change `config.server.ts`, env overrides, feature flags, multi-site config | `storefront-next:sfnext-configuration` |
+| Build a bundle, push to Managed Runtime, deploy cartridges, env vars | `storefront-next:sfnext-deployment` |
+| Add or change a route, loader, action, URL pattern | `storefront-next:sfnext-routing` |
+| Fetch data, SCAPI calls in loaders, streaming, Suspense | `storefront-next:sfnext-data-fetching` |
+| Control loader revalidation and caching after actions | `storefront-next:sfnext-revalidation` |
+| Client state, contexts, stores | `storefront-next:sfnext-state-management` |
+| Speed, bundle size, Lighthouse, web vitals | `storefront-next:sfnext-performance` |
+| Login, SLAS, guest/registered sessions, passkeys, social login | `storefront-next:sfnext-authentication` |
+| Add or inspect SCAPI endpoints and clients (including custom APIs) | `storefront-next:sfnext-scapi` |
+| Serve some routes from another storefront (hybrid proxy) | `storefront-next:sfnext-hybrid-storefronts` |
+| Build or modify UI components | `storefront-next:sfnext-components` |
+| Design tokens, Tailwind, styling | `storefront-next:sfnext-theming` |
+| Page Designer components and regions | `storefront-next:sfnext-page-designer` |
+| Author or install extensions, UITargets | `storefront-next:sfnext-extensions` |
+| Translations, locales, language switching | `storefront-next:sfnext-i18n` |
+| Unit, component, Storybook and e2e tests | `storefront-next:sfnext-testing` |
+| CSP, security headers, bot protection | `storefront-next:sfnext-security` |
+| Analytics adapters, consent banner, attribution | `storefront-next:sfnext-analytics-consent` |
+| Meta tags, JSON-LD, canonical URLs, seoRoutes | `storefront-next:sfnext-seo` |
+| Shopper Context, order management, guest order lookup, email cartridge, shipped extensions | `storefront-next:sfnext-commerce-features` |
+| Lint, typecheck, pre-merge checks | `storefront-next:sfnext-quality-gates` |
+| Accessibility checks and fixes | `storefront-next:sfnext-accessibility` |
+
+Figma-to-Page-Designer work lives in the separate `figma-to-sfnext-pagedesigner` plugin.
+
+## sfnext CLI cheat sheet
+
+Installed with the project (`@salesforce/storefront-next-dev`). Prefer the `package.json` scripts, which wrap these.
+
+| Command | Purpose |
+|---|---|
+| `sfnext create-storefront` | Scaffold a project (`--vertical` picks the starter theme) |
+| `sfnext dev` / `sfnext preview` | Dev server / preview of the built app |
+| `sfnext create-bundle`, `sfnext push` | Build and push a bundle to Managed Runtime |
+| `sfnext prepare-local` | Prepare a local build |
+| `sfnext generate-cartridge`, `validate-cartridge`, `deploy-cartridge` | Cartridge build, check, upload |
+| `sfnext setup-base-cartridge` | Register the SLAS scope for the base cartridge |
+| `sfnext create-instructions` | Generate extension install instructions |
+| `sfnext config inspect`, `config aggregate-extensions` | Show resolved config; merge extension config |
+| `sfnext extensions create|install|list|remove` | Manage extensions |
+| `sfnext scapi add|available|list|remove` | Manage SCAPI client wiring |
+| `sfnext locales aggregate-extensions` | Merge extension locale files |
+
+Run `sfnext <command> --help` for flags; check your project's `package.json` scripts for the exact invocations.
+
+## b2c CLI cheat sheet
+
+Use `b2c` (`npx @salesforce/b2c-cli` if not installed) for platform work around the storefront:
+
+| Need | Command family |
+|---|---|
+| Managed Runtime projects, envs, env vars, bundles, logs | `b2c mrt ...` (skill `b2c-cli:b2c-mrt`) |
+| Deploy or watch cartridges on an instance | `b2c code deploy`, `b2c code watch` |
+| SCAPI schemas and custom APIs | `b2c scapi schemas ...`, `b2c scapi custom ...` |
+| SLAS clients | `b2c slas ...` (skill `b2c-cli:b2c-slas`) |
+| Instance and site data, WebDAV, jobs, logs | `b2c sites`, `b2c webdav`, `b2c job`, `b2c logs` |
+| Documentation | `b2c docs search`, `b2c docs read` |
+
+## MCP tools (b2c-dx-mcp, STOREFRONTNEXT toolset)
+
+`mrt_bundle_push`, `mrt_logs_watch`, `scapi_search`, `scapi_execute`, `scapi_snippet_save`, `scapi_schemas_list`, `scapi_custom_apis_get_status`, plus the docs tools `docs_search`, `docs_read`, `docs_list`, `docs_schema_search`, `docs_schema_read`, `docs_schema_list`. Availability depends on how the MCP server was started; list tools in your client.
+
+## Docs search fallback
+
+When the project docs and skills do not answer it, search the Storefront Next developer guides:
+
+```bash
+b2c docs search "storefront next getting started" --category sfnext
+b2c docs read <id-from-results>
+```
+
+MCP equivalent: `docs_search` with the storefront category, then `docs_read`. Workspace detection also boosts Storefront Next results automatically in a project. See `b2c-cli:b2c-docs`.
+
+## Related Skills
+
+- `storefront-next:sfnext-project-setup` - usual next step for new work
+- `storefront-next:sfnext-configuration` - config and env
+- `storefront-next:sfnext-routing` - routes and loaders
+- `storefront-next:sfnext-quality-gates` - checks before you finish
+- `b2c-cli:b2c-docs` - documentation search
+- `b2c-cli:b2c-mrt` - Managed Runtime