@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/content/guidance/storefront-next/sfnext-extensions/references/ACTION-HOOKS.md

@@ -0,0 +1,57 @@
+# Action Hooks
+
+Action hooks let an extension run server-side code at fixed points in the checkout actions (fraud checks, address verification, payment enrichment) without editing the action files. UI slots are separate; see the main skill.
+
+## Available hook ids
+
+The ids live in `ACTION_HOOK_IDS` in `src/targets/action-hook.server.ts`; `pnpm extensions:list` prints them too.
+
+| Constant | Hook id |
+|----------|---------|
+| `CHECKOUT_FRAUD_AFTER_SUBMIT_CONTACT_INFO` | `sfcc.checkout.fraud.afterSubmitContactInfo` |
+| `CHECKOUT_ADDRESS_VERIFICATION_AFTER_SUBMIT_SHIPPING_ADDRESS` | `sfcc.checkout.addressVerification.afterSubmitShippingAddress` |
+| `CHECKOUT_SHIPPING_AFTER_METHODS_FETCH` | `sfcc.checkout.shipping.afterMethodsFetch` |
+| `CHECKOUT_SHIPPING_AFTER_METHOD_SELECT` | `sfcc.checkout.shipping.afterMethodSelect` |
+| `CHECKOUT_PAYMENTS_AFTER_SUBMIT_PAYMENT` | `sfcc.checkout.payments.afterSubmitPayment` |
+| `CHECKOUT_FRAUD_BEFORE_PLACE` | `sfcc.checkout.fraud.beforePlace` (blocking) |
+| `CHECKOUT_PAYMENTS_BEFORE_PLACE_ORDER` | `sfcc.checkout.payments.beforePlaceOrder` (blocking) |
+| `CHECKOUT_PAYMENTS_AFTER_PLACE_ORDER` | `sfcc.checkout.payments.afterPlaceOrder` |
+
+## Register a handler
+
+```json
+{
+  "actionHooks": [
+    { "hookId": "sfcc.checkout.fraud.beforePlace", "handler": "extensions/my-extension/hooks/fraud-check.ts", "order": 0 }
+  ]
+}
+```
+
+`handler` is a path relative to `src/`; the module's default export is the handler. It receives the hook context (`{ data, actionContext }`) and returns the (optionally modified) context, or nothing to pass it through.
+
+```typescript
+import { ActionHookError } from '@/targets/action-hook.server';
+import type { ActionHookContext } from '@/targets/action-hook.server';
+
+export default async function fraudCheck(context: ActionHookContext) {
+    const risky = await scoreOrder(context.data);   // your own server-side call
+    if (risky) {
+        throw new ActionHookError('We could not process this order.', 'sfcc.checkout.fraud.beforePlace', 'placeOrder');
+    }
+    return context;
+}
+```
+
+The constructor is `ActionHookError(message, hookId, step)`; the step is echoed in the 400 response.
+
+## Semantics
+
+- Handlers for one hook run in series as a waterfall, ordered by `order`; each receives the previous handler's output. With no handlers the original context is returned unchanged.
+- Throwing `ActionHookError` aborts the action and returns an HTTP 400 JSON response with your message and the step.
+- Each handler has a timeout (a few seconds); a slow handler is treated as a failure, so do not make long calls inside hooks.
+- Non-blocking hooks (the default): an unexpected error is logged, the failing handler is skipped and the action continues. Blocking hooks (`fraud.beforePlace`, `payments.beforePlaceOrder` run with `blocking: true`): an unexpected error fails the action, so a broken fraud or payment check cannot silently let an order through.
+- Keep handlers server-safe: they run in the action, so use `*.server` modules freely and never put secrets in client-visible config (use `server-config.ts`).
+
+## Adding a new hook point
+
+Call `runHookSafe` from an action with a new id you add to `ACTION_HOOK_IDS`, as `src/routes/action.place-order.ts` does. Pass `blocking: true` only when a failure must stop the action. Then run `pnpm extensions:list` to confirm it is discovered.

package/content/guidance/storefront-next/sfnext-extensions/references/BASE-AUDIT.md

@@ -1,65 +1,68 @@
-# Base Audit Reference
+# Base Audit: Extend, Restyle, or Edit
 
-Use this before building an extension or adding a section to a page. The goal is to decide **whether to extend at all**, and if so, **at which layer** — so you never ship a component that duplicates something the base template already renders.
+Use this before building an extension or adding a section to a page. The goal is to decide whether to extend at all, and if so at which layer, so you never ship a component that duplicates something the storefront already renders. You own the whole project, so the choices are about keeping changes small and upgrade-friendly, not about who is allowed to edit what.
 
-## The gate, step by step
+## The gate
 
-1. **Find the base component.** Open the route in `src/routes/` and trace what it renders down to the section you care about.
-2. **Check every rendered section.** For each thing you want to add, ask: does the base already render equivalent content here?
+1. **Find what renders today.** Open the route in `src/routes/` and follow it down to the component for the area you care about.
+2. **Check every section you plan to add.** Does the base already render equivalent content there (a description, accordion, badge, banner, title)?
 3. **Branch:**
-   - **Already rendered** → restyle via token/brand layer or a CVA variant, or inject into a UITarget slot on the existing content. Do **not** create a parallel component.
-   - **Not rendered** → an extension (or a base slot) is justified.
-4. **Pick the layer for what's genuinely missing:**
+   - Already rendered: change its look or behavior in place, or fill an existing slot next to it. Do not add a parallel component.
+   - Not rendered: continue to step 4.
+4. **Choose the layer:**
 
-   ```
-   Purely visual (color, font, spacing)?
-     └─ YES → Token / CVA change. No extension.
-     └─ NO  → Needed by only one storefront/vertical?
-                 └─ YES → Extension at a UITarget slot.
-                 └─ NO  → Shared pattern → add a slot/render-prop to the BASE component.
-   ```
+```
+Purely visual (color, font, radius, spacing)?
+  YES -> Token or component-variant change (storefront-next:sfnext-theming). No extension.
+  NO  -> Does a UITarget slot exist where it belongs?
+           YES -> Extension filling that slot (this skill).
+           NO  -> Is it a one-off for this storefront?
+                    YES -> Edit the route or component directly.
+                    NO  -> Edit the base component to add a <UITarget> slot (or a render prop),
+                           then fill it from an extension.
+```
 
-## Worked examples
+Rule of thumb: extensions add what is missing; they do not recreate what exists. If you keep editing the same base file for the same feature, give it a slot.
 
-### Example 1 — duplicate section (wrong) vs additive section (right)
+## Worked examples (real slots)
 
-```
-❌ WRONG — base ProductView already renders a description accordion ("What's in it:").
-           The extension adds its own "What's in it" section → duplicate content on the PDP.
+Find them with `pnpm extensions:list`. The ids below are from a current project; confirm in yours.
 
-✅ CORRECT — base already renders description + adapter sections (Ingredients, How to Use…).
-             The extension adds ONLY the sections the base does not have
-             (e.g. "Shipping & Fresh Guarantee", a brand story block).
-```
+| You want | Already in base? | Layer |
+|----------|------------------|-------|
+| A "store finder" link beside the cart icon | No; `sfcc.header.before.cart` exists | Extension component on that slot (how the store locator does it) |
+| An installment-payment message under the PDP price | No; `sfcc.pdp.bnpl.message` exists | Extension component on that slot (the BNPL demo does this) |
+| A reviews section on the PDP | No; `sfcc.pdp.reviews.section` and `sfcc.pdp.reviews.rating` exist | Extension (the ratings and reviews demo) |
+| A returns and warranty card on the PDP | Yes: `sfcc.pdp.returnsWarranty` and `sfcc.pdp.collapsibles` already render content | Replace or extend what the product-content extension fills; do not add another card |
+| Make the primary button a new color | Button exists | Token change, no extension |
+| A denser product tile | Tile exists | New component variant, no extension |
+| A promo strip above the header, nothing fits | No slot | Edit the header component, and add a `<UITarget>` if you expect to reuse the seam |
+| Block an order when a fraud check fails | Server hook `sfcc.checkout.fraud.beforePlace` exists | Action hook (see [Action Hooks](ACTION-HOOKS.md)), not UI |
 
-### Example 2 — restyle, don't re-render
+### Duplicate section (wrong) vs additive section (right)
 
 ```
-❌ WRONG — base renders the product title in ProductInfo.
-           A brand "stamp" extension renders the product title again.
+WRONG: the PDP already renders collapsible product-detail sections. The extension adds its own
+       accordion with the same headings -> two copies of the same content.
 
-✅ CORRECT — the stamp adds ONLY the brand line ("ACME · Handmade")
-             above the existing ProductInfo. The title stays where the base renders it.
+RIGHT: fill or extend what the existing collapsibles slot renders, or add only sections
+       the base lacks.
 ```
 
-### Example 3 — pick the right layer
+### Restyle, do not re-render
 
-| Desired change | Already in base? | Correct layer |
-|----------------|------------------|---------------|
-| Make the primary button green | Button exists | Token change in `brand.css` (no extension) |
-| Add a "compact" tile density | Tile exists | New CVA variant on the tile |
-| Add a site-wide promo banner above nav | Not rendered, one storefront only | Extension at `header.before.nav` |
-| Add a "sustainability meta" line every storefront will want | Not rendered, shared pattern | Slot / render-prop on the BASE tile/product component |
+```
+WRONG: an extension renders the product title again so it can style it.
+RIGHT: adjust the title's token or variant; add only the new line (for example a badge) in a slot.
+```
 
-## Finding the slots and base render points
+## Finding slots and render points
 
 ```bash
-# from packages/template-retail-rsc-app — list every UITarget slot in use
-rg "UITarget" src/ -l
-
-# read a target file to find its targetId values, e.g.
-#   <UITarget targetId="header.before.nav" />
-#   <UITarget targetId="pdp.add-to-cart.below" />
+pnpm extensions:list              # every UITarget id and action hook id, with where it is used
+pnpm extensions:list -- --json    # machine-readable
+rg "UITarget" src/ -l             # files that render slots
+rg 'targetId="sfcc.pdp' src/      # slots for one area
 ```
 
-If no suitable slot exists where you need it and the page is one you own, a direct route edit is acceptable — but still run the audit first so you don't duplicate existing content. Prefer a UITarget slot when one fits.
+The build fails when `target-config.json` names a `targetId` that no `<UITarget>` renders, so a typo is caught immediately. If no slot suits and the page is yours to change, a direct edit is fine, after running the audit so you do not duplicate existing content.

package/content/guidance/storefront-next/sfnext-extensions/references/CLI-AND-INSTALL.md

@@ -0,0 +1,58 @@
+# CLI and Install
+
+The `sfnext` CLI (from `@salesforce/storefront-next-dev`, available in your project) manages extensions. Run commands from the project root, or pass `--project-directory`.
+
+```bash
+sfnext extensions list                                   # installed extensions
+sfnext extensions create -n "My Extension" -d "What it does"   # scaffold a new extension
+sfnext extensions install -e SFDC_EXT_STORE_LOCATOR      # install a registered extension
+sfnext extensions remove -e SFDC_EXT_BOPIS               # remove one (comma-separate several)
+sfnext extensions remove -e SFDC_EXT_STORE_LOCATOR --yes # also remove dependents without prompting
+pnpm extensions:list                                     # UITarget ids and action hook ids (not the same as `list`)
+```
+
+Run `sfnext extensions <command> --help` for the exact flags in your version.
+
+## create
+
+Scaffolds `src/extensions/<kebab-name>/` (components, locales, hooks, routes, README) and registers a `SFDC_EXT_*` entry in `src/extensions/config.json`. It does not create `target-config.json` content for you; add it when you have a component to plug in.
+
+## install and remove
+
+Registered extensions are listed in `src/extensions/config.json`, each with a marker key, `name`, `description`, `folder`, optional `dependencies`, and `installationInstructions` / `uninstallationInstructions` pointing at files in `instructions/`. Shipped registrations include Store Locator, BOPIS (depends on Store Locator and Multiship), Multiship, and the demo extensions BNPL, Customer Preferences, Ratings and Reviews, Product Content, and Shipping Delivery. The theme-switcher folder is present but not registered.
+
+- `install` copies the extension folder and merges the marked snippets (see markers below) into base files from a source template repository (`--source-git-url`/`-s` overrides the default).
+- `remove` reverses that and, when other installed extensions depend on the target, asks before removing them (`--yes` skips the prompt).
+- Always commit or stash first and review the diff: installs touch base files such as `root.tsx`, the header and the footer.
+
+## Agent-driven install instructions
+
+`instructions/*.mdc` are step-by-step prompts a coding agent can follow to install or uninstall an extension. Treat them as a starting point: they are generated from the source template repository and can lag behind your project (for example file paths or a temporary clone folder name). If a step mentions a file that does not exist in your project, prefer `sfnext extensions install`, or compare against the extension's own `README.md`.
+
+To author instructions for your own extension (an extension whose integration edits are marked with `SFDC_EXT_*` markers):
+
+```bash
+sfnext create-instructions -d . -c <extension-config.json> -e SFDC_EXT_MY_FEATURE
+```
+
+Options include `-f` for the specific files that contain markers, `-b` for the template branch, and `-o` for the output directory (default `./instructions`).
+
+## Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `@sfdc-extension-line SFDC_EXT_X` | The comment line and the single line that follows it belong to the extension |
+| `@sfdc-extension-block-start SFDC_EXT_X` / `@sfdc-extension-block-end SFDC_EXT_X` | Everything between belongs to the extension |
+| `@sfdc-extension-file SFDC_EXT_X` | The whole file belongs to the extension and is removed on uninstall |
+
+Rules: use the exact `SFDC_EXT_*` key from `config.json`; never nest different markers; only mark code the extension truly needs outside its folder.
+
+## After install or remove
+
+```bash
+pnpm locales:aggregate-extensions   # regenerate src/extensions/locales (also runs in dev/build)
+pnpm config:aggregate-extensions    # regenerate src/extensions/config (also runs in dev/build)
+pnpm typecheck && pnpm lint
+```
+
+Then read the extension's README for environment variables, SLAS scopes, or custom SCAPI endpoints it needs. Store Locator, for example, relies on the store data your instance exposes; check its README.

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

@@ -1,116 +1,79 @@
-# Extension Examples Reference
+# Extension Examples
 
-## Store Locator Extension
+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.
 
-A complete extension adding store locator functionality:
+## Simplest: BNPL (one slot, one API module)
 
 ```
-src/extensions/store-locator/
+src/extensions/bnpl/
 ├── target-config.json
-├── components/
-│   ├── store-locator-badge.tsx    # Badge in header
-│   └── store-locator-map.tsx      # Map component
-├── routes/
-│   └── store-locator.tsx          # /store-locator page
+├── 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/
-│   ├── en-US/translations.json
-│   └── de-DE/translations.json
-└── providers/
-    └── store-provider.tsx         # Store data context
+└── README.md
 ```
 
-### target-config.json
-
 ```json
 {
   "components": [
-    {
-      "targetId": "header.after.logo",
-      "path": "extensions/store-locator/components/store-locator-badge.tsx",
-      "order": 0
-    }
-  ],
-  "contextProviders": [
-    {
-      "path": "extensions/store-locator/providers/store-provider.tsx",
-      "order": 0
-    }
+    { "targetId": "sfcc.pdp.bnpl.message", "path": "extensions/bnpl/components/target/bnpl-target.tsx", "order": 0 }
   ]
 }
 ```
 
-### Route
+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.
 
-```typescript
-// src/extensions/store-locator/routes/store-locator.tsx
-import { createApiClients } from '@/lib/api-clients';
-import { useTranslation } from 'react-i18next';
+## Several slots: Ratings and Reviews
 
-export function loader({ context }: LoaderFunctionArgs) {
-    const clients = createApiClients(context);
-    return {
-        stores: clients.shopperStores.getStores({...}).then(({ data }) => data),
-    };
-}
+Three entries in one `target-config.json` fill three different places:
 
-export default function StoreLocatorPage({ loaderData }) {
-    const { t } = useTranslation('extStoreLocator');
+| 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` |
 
-    return (
-        <div>
-            <h1>{t('title')}</h1>
-            {/* Render store map and list */}
-        </div>
-    );
-}
-```
+It also has `context/`, `providers/`, `routes/`, `lib/` and `locales/`. Pattern: one target adapter per slot, shared logic in context and `lib`.
 
-### Translations
+## Routes, provider, middleware: Store Locator
 
-```json
-// src/extensions/store-locator/locales/en-US/translations.json
-{
-  "title": "Find a Store",
-  "searchPlaceholder": "Enter city or zip code",
-  "noResults": "No stores found nearby"
-}
+```
+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
 ```
 
-## Integration Marker Patterns
+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.
 
-### Single-Line Import
+## Wrapper slot
 
-```typescript
-/** @sfdc-extension-line SFDC_EXT_STORE_LOCATOR */
-import StoreLocatorBadge from '@extensions/store-locator/components/store-locator-badge';
-```
+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`:
 
-### Block Integration
+```tsx
+import type { ReactNode } from 'react';
 
-```typescript
-/* @sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR */
-<Link to="/store-locator" className="flex items-center gap-2">
-    <MapPinIcon className="h-4 w-4" />
-    <span>{t('storeLocator')}</span>
-</Link>
-/* @sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR */
+export default function ConsentWrapper({ children }: { children?: ReactNode }) {
+    return <div className="rounded border p-2">{children}</div>;
+}
 ```
 
-## BOPIS Extension (Buy Online, Pick Up In Store)
+Use `pnpm extensions:list` to see which slots are wrappers in your project.
 
-```json
-{
-  "components": [
-    {
-      "targetId": "product.detail.fulfillment",
-      "path": "extensions/bopis/components/pickup-selector.tsx",
-      "order": 0
-    },
-    {
-      "targetId": "cart.item.fulfillment",
-      "path": "extensions/bopis/components/pickup-info.tsx",
-      "order": 0
-    }
-  ]
-}
-```
+## 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

@@ -1,148 +1,93 @@
 ---
 name: sfnext-hybrid-storefronts
-description: Implement hybrid storefronts that run Storefront Next alongside SFRA or SiteGenesis. Use when planning gradual migration from SFRA, configuring hybrid proxy for local development, setting up session bridging between storefronts, or routing traffic between old and new implementations.
+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 Skill
+# Hybrid Storefronts
 
-This skill covers running Storefront Next alongside an existing SFRA or SiteGenesis storefront — enabling gradual migration without a full rewrite.
+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.
 
-## Overview
+- **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.
 
-A hybrid storefront splits traffic between Storefront Next (for new or migrated pages) and an existing SFRA/SiteGenesis storefront (for pages not yet migrated). Session bridging ensures users maintain authentication and cart state across both implementations.
+## Two sets of configuration
 
-## Architecture
-
-```
-Customer Request
-      ↓
-  CDN / eCDN (Cloudflare)        ← Production: routes based on URL patterns
-      ↓
-  ┌─────────────────────────────┐
-  │ Storefront Next │ SFRA/SiteGenesis │
-  │  (MRT)          │  (B2C Instance)  │
-  └────────┴────────────────────┘
-       ↕ Session Bridge (shared cookies) ↕
-```
-
-**Production:** Cloudflare eCDN handles routing between Storefront Next and SFRA based on origin rules.
-
-**Local Development:** A Vite dev server plugin (`hybridProxyPlugin` from `@salesforce/storefront-next-dev`) proxies non-matching requests to your SFCC sandbox, simulating the eCDN split at `localhost:5173`.
-
-## Configuration
-
-Hybrid mode is configured entirely through environment variables — there is no extension directory.
-
-### Application Config (All Environments)
-
-These `PUBLIC__` variables are bundled into the app and required in all environments:
+| 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
-# Enable hybrid mode — activates the client-side legacy-routes middleware
 PUBLIC__app__hybrid__enabled=true
+PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id", "/categoryLv1/*"]'
 
-# Routes that belong to SFRA — client-side <Link> clicks to these trigger full-page loads
-# Supports exact paths and React Router parameterized routes
-PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id"]'
-```
-
-### Proxy Plugin Config (Local Development Only)
-
-These configure the Vite dev server proxy and have no effect in production:
-
-```bash
-# Enable the proxy
 HYBRID_PROXY_ENABLED=true
-
-# Your SFCC sandbox origin
-SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com
-
-# Routing rules: Cloudflare eCDN expression format
-# 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 "^/resource.*" or http.request.uri.path matches "^/action/.*")'
-
-# Optional: locale for SFRA path transformation (falls back to PUBLIC__app__i18n__fallbackLng)
-HYBRID_PROXY_LOCALE=en-GB
+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/.*")'
 ```
 
-## Client-Side Navigation Middleware
-
-The `legacy-routes.client.ts` middleware intercepts client-side navigation to SFRA-owned routes:
-
-1. User clicks `<Link to="/checkout">`
-2. React Router begins client-side navigation
-3. Middleware checks if `/checkout` matches any pattern in `legacyRoutes`
-4. If yes → forces a full-page navigation so the CDN/proxy routes to SFRA
-5. If no → continues normal client-side rendering
-
-This prevents React Router from trying to render pages that belong to SFRA.
+`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.
 
-## Session Bridging
+## legacyRoutes patterns
 
-Both storefronts share the same session cookies (`dwsid`, `cc-*`) on a common domain:
+Each entry is a string or `{ pattern, suffix }`.
 
-### Cookie Handling (Local Dev)
+| 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 proxy handles cookies in three layers:
-1. **Set-Cookie header rewriting** — SFCC response `Domain=.salesforce.com` → `Domain=localhost`
-2. **Storefront Next server cookies** — Written directly to localhost, no rewriting needed
-3. **Client-side cookie interception** — Injected script patches `document.cookie` for SFRA's JS
+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.
 
-### SFRA to Storefront Next
+## Session bridge
 
-When navigating from SFRA to Storefront Next:
-1. SFRA provides session credentials (dwsgst/dwsrst tokens)
-2. Storefront Next exchanges the bridge token for SLAS tokens
-3. Normal SLAS cookie-based auth resumes
+There is no token exchange and no client-side sync. The bridge is the `dwsid` cookie (plus `dw_dnt` for tracking consent):
 
-### Storefront Next to SFRA
+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.
 
-When navigating from Storefront Next to SFRA:
-1. Shared `dwsid` cookie maintains session continuity
-2. Full-page navigation triggered by legacy-routes middleware
-3. CDN/proxy routes request to SFCC origin
+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`.
 
-## Traffic Routing Patterns
+## Edit the proxy where customers edit it
 
-### Gradual Migration Strategy
+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.
 
-1. **Phase 1** — Homepage, product, and category pages on Storefront Next
-2. **Phase 2** — Account and search pages
-3. **Phase 3** — Cart and checkout flow
-4. **Phase 4** — Full migration, remove SFRA
+- **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`.
 
-### Required Routing Rules
+## Automatic behaviors
 
-Some patterns must always route to Storefront Next:
-
-| Pattern        | Why                                            |
-| -------------- | ---------------------------------------------- |
-| `^/resource.*` | React Router resource routes (data endpoints)  |
-| `^/action/.*`  | React Router actions (form submissions)        |
-
-### Keep Rules in Sync
-
-`HYBRID_ROUTING_RULES` (what Storefront Next owns) and `PUBLIC__app__hybrid__legacyRoutes` (what SFRA owns) are complementary. Any path not in routing rules that could be a `<Link>` target should be in `legacyRoutes`.
-
-## Common Considerations
-
-- **Cookie domains** — Both storefronts must share a cookie domain for session bridging
-- **CDN configuration** — Update eCDN origin rules as pages migrate
-- **SEO continuity** — Maintain URL structure to preserve search rankings
-- **Cart synchronization** — Basket state is consistent via shared session cookies
+- 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
 
-| Issue                             | Cause                      | Solution                                          |
-| --------------------------------- | -------------------------- | ------------------------------------------------- |
-| Lost session crossing storefronts | Cookie domain mismatch     | Ensure shared parent domain                       |
-| Cart items disappear              | Basket not synced          | Verify session bridge cookies (`dwsid`, `cc-*`)   |
-| Redirect loops                    | Conflicting routing rules  | Check eCDN rules and `legacyRoutes` consistency   |
-| 404 on SFRA pages (local dev)     | Missing from routing rules | Add path to `HYBRID_ROUTING_RULES`                |
-| React Router 404 on legacy route  | Missing from legacyRoutes  | Add path to `PUBLIC__app__hybrid__legacyRoutes`   |
+| 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` - SLAS token management and session cookies
-- `storefront-next:sfnext-deployment` - MRT deployment for hybrid setup
-- `storefront-next:sfnext-configuration` - Environment configuration for hybrid mode
+- `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