@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-hybrid-storefronts/references/HYBRID-PROXY-CONFIG.md

@@ -1,123 +1,86 @@
 # Hybrid Proxy Configuration Reference
 
-## Overview
+Authoritative guide in your project: `docs/README-HYBRID-PROXY.md`. Plugin wiring: `vite-plugins/hybrid-proxy.ts`.
 
-The hybrid proxy is a **Vite dev server plugin** (`hybridProxyPlugin` from `@salesforce/storefront-next-dev`) that routes requests between Storefront Next and SFRA based on URL patterns during local development. In production, Cloudflare eCDN handles routing.
+## Environment variables
 
-## 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>/...`. |
 
-### All Environments
+`hybrid` defaults to `{ enabled: false, legacyRoutes: [] }` in `config.server.ts`.
 
-```bash
-# Enable hybrid mode (activates client-side legacy-routes middleware)
-PUBLIC__app__hybrid__enabled=true
-
-# Routes owned by SFRA — Link clicks to these force full-page navigation
-# Supports exact paths and React Router parameterized routes (/product/:id)
-PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'
-```
-
-### Local Development Only
-
-```bash
-# Enable the Vite proxy
-HYBRID_PROXY_ENABLED=true
-
-# SFCC sandbox URL (the actual hostname, not the SCAPI base URL)
-SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com
-
-# Cloudflare-style routing expression
-# Paths matching → Storefront Next; paths not matching → proxied to SFCC
-HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" 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 "^/account.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*")'
-
-# Optional: locale for SFRA path transformation
-HYBRID_PROXY_LOCALE=en-GB
-
-# Commerce Cloud site ID (likely already set)
-PUBLIC__app__defaultSiteId=RefArchGlobal
-```
-
-## Routing Rules Format
-
-Each clause follows `http.request.uri.path matches "<regex>"`, joined with `or`:
+## Routing rule format
 
 ```
 (http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")
 ```
 
-This is the same format used by Cloudflare eCDN origin rules — keep local and production in sync.
-
-### Required Patterns
-
-| Pattern        | Why                                              |
-| -------------- | ------------------------------------------------ |
-| `^/resource.*` | React Router resource routes (server endpoints)  |
-| `^/action/.*`  | React Router actions (form submissions)          |
-
-### Automatically Excluded Paths (never proxied)
-
-- `/@*`, `/__*` — Vite internals
-- `/src/*`, `/node_modules/*` — Source files
-- `*.data` — React Router data requests
-- `/mobify/*` — SCAPI proxy paths
-- Static asset extensions (`.js`, `.css`, `.png`, `.woff2`, etc.)
+Only `http.request.uri.path matches "<regex>"` clauses joined by `or` are parsed. Always include `^/resource.*` and `^/action/.*`. `.data` requests are excluded automatically.
 
-SFRA static assets (`/on/demandware.static/*`, `/on/demandware.store/*`) are always proxied.
+| Pattern | Route |
+|---|---|
+| `^/$` | Home |
+| `^/login.*`, `^/logout.*`, `^/signup.*`, `^/reset-password.*` | Auth pages |
+| `^/account.*` | Account |
+| `^/product.*`, `^/category.*`, `^/search.*` | Catalog |
+| `^/social-callback.*` | Social login callback |
 
-## Path Transformation
+## Path transformation
 
-The proxy rewrites paths to SFRA format automatically:
+| Browser URL | Proxied to |
+|---|---|
+| `/` | `/s/<siteId>` |
+| `/cart` | `/s/<siteId>/<locale>/cart` |
+| `/on/demandware.static/...`, `/s/...` | unchanged |
 
-| Browser URL    | Proxied to SFCC as                    |
-| -------------- | ------------------------------------- |
-| `/cart`        | `/s/RefArchGlobal/en-GB/cart`         |
-| `/checkout`    | `/s/RefArchGlobal/en-GB/checkout`     |
+With `url.prefix` set in `config.server.ts`:
 
-The `siteId` comes from `PUBLIC__app__defaultSiteId`. The locale uses `HYBRID_PROXY_LOCALE` → `PUBLIC__app__i18n__fallbackLng` → `default`.
+| `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` |
 
-## Cookie Handling (Local Dev)
+Query strings are preserved.
 
-Three layers keep cookies working on localhost:
+## Cookie layers (local dev)
 
-1. **Set-Cookie header rewriting** — `Domain=.salesforce.com` → `Domain=localhost`
-2. **Storefront Next server cookies** — Written directly to localhost
-3. **Client-side cookie interception** — Injected script patches `document.cookie` for SFRA JS
+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 Route Matching
+## Custom matcher (last resort)
 
-Override the default `shouldRouteToNext` matcher in `vite.config.ts`:
+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
+        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
 });
 ```
 
-## CDN Routing (Production)
-
-In production, Cloudflare eCDN origin rules handle the split:
-
-```
-# Conceptual — configured in Cloudflare dashboard
-/                       → Storefront Next (MRT origin)
-/product/*              → Storefront Next (MRT origin)
-/category/*             → Storefront Next (MRT origin)
-/cart                   → SFRA (B2C Instance origin)
-/checkout/*             → SFRA (B2C Instance origin)
-/on/demandware.static/* → SFRA (B2C Instance origin)
-```
-
-## Shared Cookie Requirements
+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.
 
-Both storefronts must share a parent cookie domain:
+## Gotchas
 
-| Storefront      | Domain              | Cookie Domain   |
-| --------------- | ------------------- | --------------- |
-| Storefront Next | `www.example.com`   | `.example.com`  |
-| SFRA            | `legacy.example.com`| `.example.com`  |
+- 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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-i18n/SKILL.md

@@ -1,187 +1,152 @@
 ---
 name: sfnext-i18n
-description: Implement internationalization in Storefront Next using i18next with useTranslation for components and getTranslation for server-side code. Use when adding translations, configuring locales, handling pluralization, using the Zod schema factory pattern, or managing extension translations. Covers namespaces, interpolation, and language switching.
+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`).
 ---
 
-# Internationalization (i18n) Skill
+# Storefront Next Internationalization
 
-This skill covers internationalization in Storefront Next using i18next with a dual-instance architecture (server + client).
+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.
 
-## Overview
+## Which API to use
 
-- **Server instance** — Has access to all translations for all languages
-- **Client instance** — Dynamically imports translations as JavaScript chunks
-- **Dual API** — `useTranslation()` for components, `getTranslation()` for non-component code
+| Where | API |
+|-------|-----|
+| React components | `useTranslation` from `react-i18next` |
+| Loaders, actions, middleware, utilities, tests | `getTranslation` from `@salesforce/storefront-next-runtime/i18n` |
 
-## Translation File Structure
-
-Translations are organized as namespace files per locale, compiled into a TypeScript index:
+```tsx
+import { useTranslation } from 'react-i18next';
 
-```
-src/locales/en-US/
-├── index.ts              # Merges all namespace files + extensions
-├── translations.json     # Default namespace (top-level keys become namespaces)
-└── product.json          # "product" namespace (separate file)
-
-src/locales/en-GB/
-├── index.ts
-├── translations.json
-└── product.json
+export function AddToCart({ count }: { count: number }) {
+    const { t } = useTranslation('product'); // namespace = top-level key in translations.json
+    return <button>{t('addToCart', { count })}</button>;
+}
 ```
 
-The `index.ts` imports all namespace files and extension translations:
+```ts
+import type { LoaderFunctionArgs } from 'react-router';
+import { getTranslation } from '@salesforce/storefront-next-runtime/i18n';
 
-```typescript
-import translations from '@/locales/en-US/translations.json';
-import product from '@/locales/en-US/product.json';
-import extensionTranslations from '@/extensions/locales/en-US/';
-
-const allTranslations = { ...translations, product, ...extensionTranslations };
-export default allTranslations satisfies ResourceLanguage;
+export function loader({ context }: LoaderFunctionArgs) {
+    const { t } = getTranslation(context); // server: pass the router context
+    return { title: t('product:title') };
+}
 ```
 
-### Namespace structure in `translations.json`
+- 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`.
 
-Each top-level key is a namespace:
+## File layout
 
-```json
-{
-    "header": {
-        "search": "Search",
-        "account": "Account"
-    },
-    "footer": {
-        "copyright": "© {{year}} Company"
-    }
-}
+```
+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
 ```
 
-### Separate namespace file (`product.json`)
+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
 {
-    "title": "Product Details",
-    "addToCart": "Add to Cart",
-    "greeting": "Hello, {{name}}!",
-    "itemCount_one": "{{count}} item",
-    "itemCount_other": "{{count}} items"
+    "product": {
+        "addToCart": "Add to cart",
+        "greeting": "Hello, {{name}}!",
+        "itemCount_one": "{{count}} item",
+        "itemCount_other": "{{count}} items"
+    }
 }
 ```
 
-## Usage in Components
+- 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.
 
-```typescript
-import { useTranslation } from 'react-i18next';
+To customize copy, edit `translations.json` directly.
 
-export function ProductCard() {
-    const { t } = useTranslation('product');
-
-    return (
-        <div>
-            <h1>{t('title')}</h1>
-            <button>{t('addToCart')}</button>
-            <p>{t('greeting', { name: 'John' })}</p>
-            <p>{t('itemCount', { count: 5 })}</p>
-        </div>
-    );
-}
-```
+## Add a new locale (checklist)
 
-**Critical:** Always pass a namespace to `useTranslation()`:
+Keep these in sync or the locale silently never appears:
 
-```typescript
-// WRONG — missing namespace
-const { t } = useTranslation();
-t('title');  // Will not find the key
+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.
 
-// CORRECT — with namespace
-const { t } = useTranslation('product');
-t('title');  // Works
-```
+Details and currency rules: [references/locale-config.md](references/locale-config.md).
 
-## Usage in Server Code
+## How the active locale is chosen
 
-```typescript
-import { getTranslation } from '@/lib/i18next';
+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`.
 
-// In loaders/actions (pass context)
-export function loader(args: LoaderFunctionArgs) {
-    const { t } = getTranslation(args.context);
-    return { title: t('product:title') };
-}
+`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`.
 
-// Client-side utilities (no context)
-const { t } = getTranslation();
-const message = t('product:addToCart');
-```
+## Extension translations
 
-## Validation Schemas — Factory Pattern
+Each extension keeps its strings in `src/extensions/<name>/locales/<locale>/translations.json`. Its namespace is `ext` + PascalCase directory name:
 
-**Critical:** Use a factory function for Zod schemas with translated messages to avoid race conditions:
+```tsx
+const { t } = useTranslation('extStoreLocator'); // src/extensions/store-locator
+```
 
-```typescript
-// WRONG — Module-level schema (race condition: t() may not be initialized)
-export const schema = z.object({
-    email: z.string().email(t('validation:emailInvalid'))
-});
+`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.
 
-// CORRECT — Factory function
-import type { TFunction } from 'i18next';
+## Validation messages: Zod schema factories
 
-export const createSchema = (t: TFunction) => {
-    return z.object({
-        email: z.string().email(t('validation:emailInvalid'))
-    });
-};
+Module-level `t()` runs before i18next is initialized. Build the schema from a function:
 
-// Usage in component
+```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), [t]);
-
-    const form = useForm({ resolver: zodResolver(schema) });
+    const schema = useMemo(() => createSchema(t as unknown as TFunction), [t]);
+    // useForm({ resolver: zodResolver(schema) })
 }
 ```
 
-## Language Switching
-
-```typescript
-import LocaleSwitcher from '@/components/locale-switcher';
-
-export function Footer() {
-    return <footer><LocaleSwitcher /></footer>;
-}
-```
+`createCustomerProfileFormSchema` in `src/components/customer-profile-form/index.tsx` is a working example.
 
-## Extension Translations
+## Testing translations
 
-Extensions use `extPascalCase` namespace auto-derived from the extension directory name:
+`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`.
 
-```
-src/extensions/my-extension/locales/
-├── en-US/translations.json
-└── it-IT/translations.json
-```
+## Pitfalls
 
-```typescript
-const { t } = useTranslation('extMyExtension');
-t('welcome');
-```
+| 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`). |
 
-## Common Pitfalls
+## Finding more
 
-| Pitfall | Problem | Solution |
-|---------|---------|----------|
-| Missing namespace | Keys not found | Always pass namespace: `useTranslation('product')` |
-| Module-level `t()` in schemas | Race condition on initialization | Use factory pattern: `createSchema(t)` |
-| Forgetting context on server | Translations not found | Use `getTranslation(args.context)` in loaders |
-| Duplicate keys across namespaces | Wrong translation shown | Prefix with namespace: `t('product:title')` |
+- `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-components` - Using translations in UI components
-- `storefront-next:sfnext-extensions` - Extension translation namespacing
-- `storefront-next:sfnext-configuration` - Locale and site configuration
+- `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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-i18n/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Add Brazilian Portuguese (pt-BR) as a supported language for our Storefront Next site and translate the cart strings", "should_trigger": true},
+  {"query": "How do I translate a Zod validation message in my checkout form without it showing the raw key?", "should_trigger": true},
+  {"query": "Change the URL prefix so the storefront uses /:siteId/:localeId paths and add a new site to commerce.sites", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/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

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

@@ -0,0 +1,5 @@
+[
+  {"query": "I just opened a Storefront Next project for the first time - where do I start and which commands exist?", "should_trigger": true},
+  {"query": "Which Storefront Next skill or doc covers what I need to do? I'm not sure where to look", "should_trigger": true},
+  {"query": "Add a custom engagement adapter that respects the consent banner", "should_trigger": false}
+]