@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/storefront-next/sfnext-data-fetching/references/LOADERS.md

@@ -0,0 +1,73 @@
+# Loader patterns
+
+See also `docs/README-DATA.md`, `docs/README-SUSPENSE.md` and the "Performance & Data Rules" in `AGENTS.md` in your project.
+
+## Critical versus streamed
+
+| Data | Treatment |
+|---|---|
+| Entity that decides status (product, category, order) | `await`; map SCAPI 404 to `throw new Response(msg, { status: 404 })` |
+| Data visible in the first viewport, SEO tags, JSON-LD source | `await` |
+| Page Designer page for the LCP region | `await` the page and render `<Region critical>` (see `storefront-next:sfnext-page-designer`) |
+| Below the fold, recommendations, reviews, secondary panels | return the promise |
+| Short-TTL data (availability about 60 s) that is not the LCP | prefer streaming |
+| Needs a user gesture | fetcher, not loader |
+
+Start every independent request before the first `await` so they run in parallel:
+
+```ts
+const clients = createApiClients(context);
+const extrasPromise = loadExtras(context, id);          // started, not awaited
+const product = await fetchProductById(context, id);    // critical
+return { product, extras: extrasPromise };
+```
+
+## Stable promises
+
+Compose dependent work inside the loader (`extrasPromise.then(...)` there, never in render). A new promise object per render restarts Suspense and flashes the fallback. Do not wrap promises in `useMemo`. If a component must derive one, pin it with `useState(() => ...)` or re-pin via `useRef` keyed on the inputs. Full rules in `docs/README-SUSPENSE.md`.
+
+A streamed promise that can reject needs an error path: use `<Await errorElement={...}>` or make the loader promise resolve to a fallback value (`.catch(() => [])`) when degraded output is acceptable, and log inside the loader.
+
+## Consuming a promise
+
+```tsx
+<Suspense fallback={<RecommendationsSkeleton />}>
+    <Await resolve={loaderData.recommendations} errorElement={null}>
+        {(items) => <Recommendations items={items} />}
+    </Await>
+</Suspense>
+```
+
+- One `<Suspense>` per independent async operation; siblings may resolve independently.
+- The skeleton must reserve the final height (no `fallback={null}` above the fold).
+- A component that reads a promise with `use()` must have a `<Suspense>` ancestor, otherwise it blocks the first byte.
+- For product listings reuse `DeferredProductGrid` (`@/components/product-grid/deferred`).
+
+## Shared layout data
+
+Layout loaders (for example `_app.tsx` navigation) stream their data and child routes read it with `useRouteLoaderData('routes/_app')`. Put data that many routes need in the lowest common layout, not in each page.
+
+## Request context
+
+Loaders receive `context` (`Route.LoaderArgs`). Useful accessors:
+
+| Need | Import |
+|---|---|
+| Logger | `getLogger` from `@/lib/logger.server` |
+| Site, locale, currency | `siteContext` from `@salesforce/storefront-next-runtime/site-context` via `context.get(siteContext)` |
+| Config | `getConfig` from `@salesforce/storefront-next-runtime/config` |
+| Session | `getAuth` from `@/middlewares/auth.server` |
+| Basket | `getBasket`, `getBasketSnapshot`, `ensureBasketId` from `@/middlewares/basket.server` |
+
+Middleware order is defined in `src/root.tsx` (`export const middleware`); add new request-wide state there with `createContext`/middleware instead of re-deriving it in each loader.
+
+## Shopper context and personalization
+
+Shopper context (customer segments, source codes, custom qualifiers) is applied by `shopper-context` middleware and read in components with `useShopperContext`. Read `docs/README-SHOPPER-CONTEXT.md` before changing it. Personalized endpoints must not be cached as shared responses.
+
+## Pitfalls
+
+- `Promise.all([...])` over critical and non-critical together re-blocks the loader; await only the critical set.
+- Mutating `loaderData` on the client is unsupported; derive in the loader.
+- Do not add `clientLoader`.
+- Shaping or normalizing data in render (lookup maps, chained passes) belongs in the loader.

package/content/guidance/storefront-next/sfnext-data-fetching/references/SCAPI-FETCHER.md

@@ -0,0 +1,39 @@
+# `useScapiFetcher`
+
+`import { useScapiFetcher } from '@/hooks/use-scapi-fetcher'`
+
+A typed wrapper over React Router's `useFetcher` that calls a Shopper client method through a single resource route (`src/routes/resource.api.client.$resource.ts`). The request is encoded (base64url of `[client, method, options]`) into `/resource/api/client/:resource`, executed on the server, and the SCAPI `data` is returned unwrapped.
+
+```tsx
+const product = useScapiFetcher('shopperProducts', 'getProduct', {
+    params: { path: { id: variantId }, query: { expand: ['availability', 'prices'] } },
+});
+
+useEffect(() => {
+    if (variantId && product.state === 'idle' && !product.data && !product.errors) void product.load();
+}, [variantId, product]);  // keep deps stable; see checklist
+```
+
+Returned object: `.load()` (GET), `.submit(payload, opts)` (mutation), `.data`, `.errors`, `.success`, plus the fetcher fields such as `.state`.
+
+Real users: `src/providers/basket.tsx` (`shopperBasketsV2.getBasket`) and `src/components/cart-item-modal/*` (`shopperProducts.getProduct`).
+
+## Server allowlist (`src/lib/scapi/resource-policy.ts`)
+
+- Loaders: `shopperBasketsV2.getBasket`, `shopperProducts.getProduct`, `shopperProducts.getProducts`, `shopperSearch.getSearchSuggestions`.
+- Actions: `shopperCustomers.createCustomerAddress`, `updateCustomerAddress`, `removeCustomerAddress`, `updateCustomer`, `updateCustomerPassword`.
+
+Everything else is rejected. `organizationId`, `siteId` and `locale` are set by the server, and request bodies and headers are sanitized. The older "helpers" overload is unsupported.
+
+Need something else (recommendations, category products, your own custom API)? Create a `resource.*` route with a `loader`. Pattern: same-origin check, input validation, `Cache-Control: no-store` for personalized output (`resource.recommendations.ts`, `resource.category-products.ts`). To allow another client call, change `resource-policy.ts` deliberately and add a test; do not widen it casually.
+
+## Related hooks
+
+- `useScapiFetcherEffect(fetcher, { onSuccess, onError })` runs callbacks once per completed request.
+- `useScapiFetchClient` (`@/hooks/use-scapi-fetch`) is a lower-level, non-fetcher variant for one-off calls.
+
+## When not to use it
+
+If the data is knowable at request time, fetch it in the loader. Mounting a component that fires `useScapiFetcher().load()` in an effect for data the route could have streamed adds a waterfall; see the performance review checklist in `storefront-next:sfnext-performance`.
+
+Calls made through `useScapiFetcher().load()` are fetcher loads, not submissions, so they do not revalidate other loaders. `.submit()` is a submission and does.

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

@@ -0,0 +1,127 @@
+---
+name: sfnext-deployment
+description: >-
+  Build and deploy a Storefront Next storefront: `pnpm build`, `pnpm push` / `sfnext push` to Managed Runtime (MRT),
+  MRT credentials (MRT_API_KEY, MRT_PROJECT, MRT_TARGET), syncing env vars with `pnpm config:push-env`, deploying
+  the base cartridge and Page Designer metadata (`pnpm cartridge:generate|validate|deploy`), the shipped GitHub
+  Actions deploy workflow, bundle size checks, the pre-launch checklist, and upgrading a project (template vs SDK
+  compatibility, react-router pin). Use when a push fails or is rejected, a deployed site returns 500 or shows
+  stale Page Designer components, "deploy to staging/production", or before go-live.
+  Do not use for generic MRT project/environment/redirect/member management or log tailing (use `b2c-cli:b2c-mrt`),
+  for config.server.ts and PUBLIC__ variable rules (use `storefront-next:sfnext-configuration`), or for creating
+  the project (use `storefront-next:sfnext-project-setup`).
+---
+
+# Storefront Next Deployment
+
+A storefront ships as two independent deployments:
+
+| Deployment | Target | Command |
+| --- | --- | --- |
+| App bundle (SSR server + client assets) | Managed Runtime | `pnpm build` then `pnpm push` |
+| Base cartridge (Page Designer metadata, notification Custom API) | B2C Commerce instance (WebDAV code version) | `pnpm cartridge:deploy` |
+
+If Business Manager Storefront Setup created your project, reuse its MRT project, environments, and SLAS client. Guides: [deployment](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-push-mrt-auto.html), [launch](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-launch-storefront.html).
+
+## Build
+
+```bash
+pnpm build        # extension locales + config aggregation, cartridge:generate, react-router build -> build/
+pnpm start        # preview the production build at http://localhost:3000
+pnpm bundlesize   # build with bundle size limits enforced
+```
+
+Run `pnpm typecheck`, `pnpm lint`, and `pnpm test` before pushing. Node 24 is required locally and on MRT (`runtime.ssrParameters.ssrFunctionNodeVersion: '24.x'`).
+
+## Push to Managed Runtime
+
+`push` does **not** build; it fails if `build/` is missing.
+
+```bash
+pnpm build && pnpm push                              # upload only (not deployed to an env unless a target is set)
+pnpm push -- -m "Release 42" -e staging --wait       # deploy to an env and wait
+```
+
+| Need | Provide |
+| --- | --- |
+| Credentials | `MRT_API_KEY` (or `--api-key`, `--credentials-file`, `~/.mobify`); `MRT_CLOUD_ORIGIN` for a non-default MRT origin |
+| Project slug | `MRT_PROJECT` / `-p` / `SFCC_MRT_PROJECT` / dw.json `mrtProject` (set it explicitly; push errors without one) |
+| Target env | `MRT_TARGET` / `-e`. Required with `--wait`. Without it the bundle uploads but is not deployed |
+
+Put `MRT_PROJECT` and `MRT_TARGET` in `.env` for local pushes. Store `MRT_API_KEY` in your shell or CI secret store, not in committed files. Flags and other commands: `storefront-next:sfnext-project-setup` `references/SFNEXT-CLI.md`. Inspect without deploying: `pnpm sfnext create-bundle -d . -o .bundle`.
+
+Bundle history, rolling back to an earlier bundle, and environment management are generic MRT tasks: `b2c mrt bundle history|list|deploy`, see `b2c-cli:b2c-mrt`. Live logs: MCP `mrt_logs_watch` / `mrt_logs_watch_poll`, or `b2c mrt tail-logs`. MCP `mrt_bundle_push` can also push a bundle.
+
+## Environment variables on MRT
+
+`.env` is **not** uploaded by `push`. Set runtime config on the MRT environment:
+
+```bash
+pnpm config:push-env                                 # b2c mrt env var push: reads .env, shows a diff, asks to confirm
+b2c mrt env var push -f .env.staging -p my-project -e staging --yes   # explicit file, skips prompt
+b2c mrt env var set PUBLIC__app__defaultSiteId=MySite -p my-project -e staging
+pnpm sfnext config inspect --project my-project --environment staging  # see what is applied
+```
+
+`push` excludes `MRT_`-prefixed keys by default. Review the file first: `PUBLIC__` values are browser-visible, and local-only values should not be pushed. Variable naming and limits: Salesforce's [environment variables guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html). Rules for what to set: `storefront-next:sfnext-configuration`.
+
+## Cartridge deployment
+
+```bash
+pnpm cartridge:generate            # Page Designer metadata from decorators (also run by pnpm build)
+pnpm cartridge:validate            # validate generated JSON
+pnpm cartridge:deploy              # upload cartridges/ to the instance
+pnpm cartridge:deploy -- --delete --reload   # wipe old files first, then activate the code version
+```
+
+- Deployment is **not** part of `pnpm push` and is manual by default.
+- Needs an instance (`-s/--server` or `SFCC_SERVER`), WebDAV credentials, and either `--code-version` or OAuth credentials to discover the active version (`--reload` also needs OAuth with OCAPI `code_versions` access). Settings resolve from flags, env, or `dw.json`; see `b2c-cli:b2c-code` for the shared auth model.
+- Redeploy whenever Page Designer decorators or attribute definitions change; stale components in Business Manager mean the cartridge is behind.
+- The base cartridge also hosts the notification Custom API used by passwordless login, password reset, OTP, and guest order lookup emails. Once per client, register its SLAS scope with `sfnext setup-base-cartridge --slas-client-id <id>` (`docs/README-EMAIL-CARTRIDGE.md`).
+
+## CI/CD
+
+The project ships `.github/workflows/deploy.yml`: on push to the `latest` branch (or manual dispatch) it builds, runs `pnpm push --wait` (needs secret `MRT_API_KEY`, variables `MRT_PROJECT`, `MRT_TARGET`), and deploys cartridges with the b2c `code-deploy` action (needs `SFCC_SERVER`, `SFCC_CLIENT_ID`, secret `SFCC_CLIENT_SECRET`). Each job skips cleanly when its configuration is absent. Read the file before changing branch names or environments.
+
+## Pre-launch checklist
+
+1. `pnpm typecheck && pnpm lint && pnpm test` pass; `pnpm bundlesize` within limits.
+2. MRT variables set on the target env: your own client ID, organization ID, short code, site(s); `pnpm config:inspect` shows no unintended demo values.
+3. Demo analytics IDs/hosts in `app.engagement.adapters` replaced or disabled.
+4. `images.host` switched from the DIS staging host to production; `realmHostMappings` for custom domains.
+5. Cartridge deployed and code version activated; SLAS scopes registered; Page Designer pages publish and render.
+6. SLAS redirect URIs include every production domain; cookie domain and Business Manager Hybrid Auth level agree if used (`references/MRT-DEPLOYMENT.md`).
+7. `url.seoRoutes` has an entry per active site if enabled (protected: needs a rebuild).
+8. Security headers/CSP and Turnstile reviewed (`storefront-next:sfnext-security`); robots and sitemap handled (`storefront-next:sfnext-seo`).
+9. Smoke test after deploy: home, PLP, PDP, cart, login, checkout, and a Page Designer page.
+
+## Upgrading a project
+
+Your project records `storefrontNext.templateRelease`, `templateVersion`, and `minSdkVersion` in `package.json`; `docs/COMPATIBILITY.md` maps template releases to the SDK (`@salesforce/storefront-next-dev` / `-runtime`) versions they need. Follow the step-by-step guides in `docs/migrations/` (for example `react-router-7.18`: pin `react-router` and every `@react-router/*` package to exactly `7.18.2`, and `seo-url-rules`). Upgrade SDK packages, run `pnpm install`, `pnpm typecheck`, and tests, then redeploy.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| `Build directory ... does not exist` | Run `pnpm build` before `pnpm push` |
+| Push: project slug required | Set `MRT_PROJECT` (or `-p`) |
+| Push: credentials required / 401 | `MRT_API_KEY` missing or for a different MRT user; check `--credentials-file` |
+| `--wait` error about environment | Add `-e <env>` or `MRT_TARGET` |
+| 500 after deploy | Required `PUBLIC__` variables missing on that MRT environment; `pnpm sfnext config inspect --environment <env>`; tail logs (`b2c-cli:b2c-mrt`) |
+| Env var "not applied" on MRT | Key not in `config.server.ts` (ignored with a warning) or a protected path; see `storefront-next:sfnext-configuration` |
+| Stale Page Designer components | Cartridge not regenerated/deployed or code version not activated |
+| Build fails on client chunk importing server config | `server-config.ts` imported from client code |
+
+## Related Skills
+
+- `storefront-next:sfnext-project-setup` - Scripts, CLI reference, first run
+- `storefront-next:sfnext-configuration` - Config and env var rules, multi-site/base path/cookie domain
+- `storefront-next:sfnext-page-designer` - Decorators and cartridge metadata
+- `storefront-next:sfnext-performance` - Bundle size and Lighthouse
+- `storefront-next:sfnext-quality-gates` - Pre-push lint/type/test gates
+- `b2c-cli:b2c-mrt` - MRT projects, environments, bundles, env vars, redirects, logs
+- `b2c-cli:b2c-code` - Code version and cartridge deploy with the b2c CLI
+
+## Finding more
+
+Project `docs/README-BASE-PATH.md`, `README-MULTI-DOMAIN.md`, `README-COOKIE-DOMAIN.md`, `README-EMAIL-CARTRIDGE.md`, `docs/migrations/`; `b2c docs search "<topic>" --category sfnext`.

package/content/guidance/storefront-next/sfnext-deployment/references/MRT-DEPLOYMENT.md

@@ -0,0 +1,59 @@
+# Managed Runtime Deployment Reference
+
+## What MRT provides
+
+Server-side rendering on Node 24, a CDN in front of the SSR function and static bundle assets, separate environments (for example development, staging, production), and versioned bundles that can be re-deployed. Project, environment, member, redirect, and certificate management is done with `b2c mrt ...` (`b2c-cli:b2c-mrt`) or Runtime Admin.
+
+## Push flow
+
+```
+pnpm build  ->  build/
+pnpm push   ->  sfnext push: creates a bundle from build/, uploads it to the project
+            ->  with a target env (MRT_TARGET / -e): deploys it; with --wait: blocks until done
+```
+
+Precedence for project and environment: CLI flag, then `MRT_PROJECT` / `MRT_TARGET`, then `SFCC_MRT_PROJECT` / `SFCC_MRT_ENVIRONMENT`, then `dw.json` (`mrtProject`, `mrtEnvironment`). Credentials: `--api-key` / `MRT_API_KEY`, or `--credentials-file` / `MRT_CREDENTIALS_FILE`, or `~/.mobify`.
+
+Send extra flags through pnpm with `--`: `pnpm push -- --wait -e production`.
+
+## What push sends to MRT
+
+- The bundle (server build + client assets).
+- SSR parameters from `config.server.ts` `runtime.ssrParameters` (`ssrFunctionNodeVersion`, `envBasePath`) and `runtime.ssrOnly` / `ssrShared`.
+
+It does not send `.env` values or cartridges.
+
+## Environment variables
+
+Set per environment in Runtime Admin or with the b2c CLI (`pnpm config:push-env`, `b2c mrt env var set|push|list|delete`). Changes to variables apply to that environment; confirm the behavior in Runtime Admin for your project. Server-only secrets (`COMMERCE_API_SLAS_SECRET` for private clients, `GUEST_ORDER_LOOKUP_COOKIE_SECRET`, `MARKETING_CLOUD_*`) go in unprefixed. `PUBLIC__` variables are merged into config and visible in the browser. Limits: see Salesforce's [constraints](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html#constraints).
+
+Example of per-environment application variables (values are yours):
+
+```bash
+PUBLIC__app__commerce__api__clientId=<slas-client-id>
+PUBLIC__app__commerce__api__organizationId=f_ecom_<realm>_<instance>
+PUBLIC__app__commerce__api__shortCode=<short-code>
+PUBLIC__app__defaultSiteId=<site-id>
+PUBLIC__app__commerce__sites='[{"id":"<site-id>","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'
+```
+
+## Domains, base path, cookies
+
+- Many domains on one environment: register each as an external hostname in Runtime Admin, add SLAS redirect URIs per domain, configure `images.realmHostMappings`. The public origin is resolved per request from `X-Forwarded-Host`.
+- Several storefronts under one domain: give each environment a distinct `runtime.ssrParameters.envBasePath` (`/shop-a`); the CDN routes on the first path segment; the value reaches MRT via `pnpm push`.
+- Shared cookies across subdomains: `app.cookies.domain` plus Business Manager Hybrid Auth cookie-domain level `2`.
+
+Details: `storefront-next:sfnext-configuration` `references/MULTI-SITE-URLS.md`. If the domain is also fronted by eCDN, manage zones and rules with `b2c-cli:b2c-ecdn`.
+
+## Rollback
+
+Each push creates a bundle. To return to an earlier version, list bundles and deploy one to the environment: `b2c mrt bundle history -p <project> -e <env>` and `b2c mrt bundle deploy <bundleId> -p <project> -e <env>`. Cartridge changes roll back separately by activating a previous code version (`b2c-cli:b2c-code`).
+
+## Verifying a deployment
+
+1. Home, category, product, cart, and checkout pages render.
+2. Products and prices load (SCAPI connectivity, correct site).
+3. Login/logout, including social or passwordless if enabled.
+4. A Page Designer page renders and the cartridge/code version is current.
+5. Response headers (CSP) and cookies have the expected `Domain` (`curl -sI`).
+6. Logs show no repeated `[Config Warning]` lines about ignored variables.

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

@@ -0,0 +1,118 @@
+---
+name: sfnext-extensions
+description: >-
+  Add or remove modular features in a Storefront Next project with the extension system: src/extensions/<name>/ folders, target-config.json (UITarget components, contextProviders, actionHooks), sfcc.-prefixed UITarget ids, extension routes, per-extension config.ts and locales, SFDC_EXT_ integration markers, the `sfnext extensions create|install|remove|list` commands, and the agent-driven instructions/*.mdc install flow. Use when inserting a component into a UITarget slot (for example sfcc.header.before.cart or sfcc.pdp.bnpl.message), adding a checkout action hook, installing or removing store locator, BOPIS, multiship or a demo extension, listing extension points with pnpm extensions:list, or deciding whether to extend, restyle, or edit the base at all. Do not use for styling or brand changes (use `storefront-next:sfnext-theming`), for new merchant-editable Page Designer blocks (use `storefront-next:sfnext-page-designer`), or for analytics/engagement adapters (use `storefront-next:sfnext-analytics-consent`).
+---
+
+# Storefront Next Extensions
+
+An extension is a self-contained folder under `src/extensions/<name>/` that adds UI, routes, providers, translations, config and server hooks to the storefront without rewriting base files. The base declares named slots (`<UITarget targetId="..." />`); an extension's `target-config.json` says which of its components fill which slot.
+
+Your project ships with several extensions already (store locator, BOPIS, multiship, and demo extensions such as BNPL and ratings and reviews). Look at them before building: they are the reference implementations. See [Extension Examples](references/EXTENSION-EXAMPLES.md).
+
+## Decision gate: should this be an extension?
+
+Run this before writing code; the full walkthrough is in [Base Audit](references/BASE-AUDIT.md).
+
+1. Trace the route in `src/routes/` down to the place you want to change. Does the base already render equivalent content there?
+2. Already rendered: restyle it (tokens or a component variant, see `storefront-next:sfnext-theming`) or fill an existing slot; do not add a parallel copy.
+3. Not rendered and a slot exists: write an extension.
+4. Not rendered and no slot fits: edit the base route or component directly (you own the whole project) and, if it is a reusable seam, add a `<UITarget>` there so later extensions can plug in.
+
+Discover what already exists:
+
+```bash
+pnpm extensions:list          # all UITarget ids and server action hook ids (add --json for tooling)
+sfnext extensions list        # installed extensions
+rg "UITarget" src/            # where a slot is rendered
+```
+
+## Structure
+
+```
+src/extensions/my-extension/
+├── target-config.json     # which components/providers/hooks plug in where
+├── components/            # UI, including the components named in target-config.json
+├── routes/                # auto-registered routes (flat-route file naming)
+├── providers/             # context providers (listed in target-config.json)
+├── hooks/  context/  middlewares/  stores/   # as needed
+├── locales/<lang>/translations.json
+├── config.ts              # optional client-side defaults
+├── server-config.ts       # optional server-only defaults
+└── README.md
+```
+
+Create the scaffold with `sfnext extensions create -n "My Extension" -d "What it does"` (adds the folder, a README and an entry in `src/extensions/config.json`). Import across the project with the normal alias: `@/extensions/my-extension/...`. There is no `@extensions` alias.
+
+## target-config.json
+
+```json
+{
+  "components": [
+    { "targetId": "sfcc.header.before.cart", "path": "extensions/my-extension/components/header/badge.tsx", "order": 0 }
+  ],
+  "contextProviders": [
+    { "path": "extensions/my-extension/providers/my-provider.tsx", "order": 0 }
+  ],
+  "actionHooks": [
+    { "hookId": "sfcc.checkout.payments.afterSubmitPayment", "handler": "extensions/my-extension/hooks/after-payment.ts", "order": 0 }
+  ]
+}
+```
+
+- `path` is relative to `src/` and points at a module whose default export is the component (no required props; read context or hooks inside). Multiple components on one slot render in ascending `order`; duplicate orders warn because their order is not deterministic.
+- A slot without children is a replacement slot. A slot that wraps base content (`<UITarget targetId="..."><Base /></UITarget>`) is a wrapper slot: the extension component receives the base content as children.
+- Optional per component: `"enabled": false` to switch it off, and `"hint"` as a label for the dev-mode overlay. A top-level `"devOnly": true` skips the whole file in production builds.
+- Extension components only inject when a `target-config.json` exists in `src/extensions/<name>/`.
+- Every `targetId` must exist as a `<UITarget>` in the source; otherwise the build fails and names the orphan. Ids are namespaced: use the exact `sfcc.`-prefixed ids reported by `pnpm extensions:list` (for example `sfcc.header.before.cart`, `sfcc.pdp.bnpl.message`, `sfcc.pdp.reviews.section`, `sfcc.cart.orderSummary.before`).
+- In `pnpm dev`, UITarget dev mode shows markers so you can see which slots exist and what fills them.
+
+Server-side hooks (`actionHooks`, checkout steps) have their own semantics: [Action Hooks](references/ACTION-HOOKS.md).
+
+## Routes, translations, config
+
+- **Routes**: any file in `routes/` is merged into the route tree with React Router flat-route naming: `_app.store-locator.tsx` (inside the app layout), `action.set-selected-store.ts` (action), `resource.stores.ts` (resource route). See `src/extensions/store-locator/routes/`.
+- **Translations**: `locales/<lang>/translations.json` is namespaced `ext` + PascalCase folder name (`my-extension` -> `extMyExtension`): `useTranslation('extMyExtension')`. `pnpm dev` and `pnpm build` run `pnpm locales:aggregate-extensions` for you and write `src/extensions/locales/`; that folder is generated, do not edit it.
+- **Client config**: `config.ts` default-exports a plain, JSON-serializable object. It is merged into `config.app.extension.<camelName>` (read with `useConfig()` in components or `getConfig()` on the server) and can be overridden per environment with `PUBLIC__app__extension__<camelName>__<key>`. It is exposed to the browser: never put secrets there.
+- **Server-only config**: `server-config.ts` lands at `config.app.serverExtension.<camelName>`, has no `PUBLIC__` override, is unreachable from client code (the build fails if a client chunk imports it), and is read with `getConfig(context)` in loaders, actions and middleware.
+- `pnpm config:aggregate-extensions` (also run by dev and build) writes `src/extensions/config/`; generated, do not edit. Folder names must be letters, digits and hyphens starting with a letter. See `docs/README-CONFIG.md`.
+
+## Integration markers
+
+Extensions that modify base files mark their edits with comments so they can be installed and removed cleanly:
+
+```typescript
+selectedStoreMiddleware /** @sfdc-extension-line SFDC_EXT_STORE_LOCATOR */,
+
+// @sfdc-extension-block-start SFDC_EXT_STORE_LOCATOR
+import { StoreLocatorProvider } from '@/extensions/store-locator/providers/store-locator';
+// @sfdc-extension-block-end SFDC_EXT_STORE_LOCATOR
+
+/** @sfdc-extension-file SFDC_EXT_STORE_LOCATOR */   // marks an entire file as belonging to the extension
+```
+
+Use them when the extension needs edits outside its folder (middleware registration, a nav link, a loader) and you want `sfnext extensions remove` to be able to undo them. Each marker name (`SFDC_EXT_*`) is a key in `src/extensions/config.json`. Install, remove and marker details: [CLI and Install](references/CLI-AND-INSTALL.md).
+
+## Removing or replacing a demo extension
+
+BNPL, customer preferences, ratings and reviews, and product content ship with mock fixtures. To integrate a real provider, replace the bodies of their API functions (for example `src/extensions/bnpl/lib/api/bnpl.server.ts`). To drop one, use `sfnext extensions remove -e SFDC_EXT_BNPL`, then run `pnpm locales:aggregate-extensions`. `docs/README-FEATURE-STUBS.md` describes finding stubs with `grep -r "@feature-stub" src/`.
+
+## Best practices
+
+1. Keep the extension self-contained; reach into the base only through slots, hooks and markers.
+2. Prefer a slot over editing a base file; add a slot when you keep editing the same spot.
+3. Use `order` deliberately and give each slot entry a distinct value.
+4. Import via `@/extensions/...` and keep translations in the extension's own namespace.
+5. After adding a slot, extension or locale, run `pnpm dev` once so the aggregation and registries regenerate, and commit nothing from `src/extensions/locales/` or `src/extensions/config/` by hand.
+
+## Related Skills
+
+- `storefront-next:sfnext-overview` - project map and where things live
+- `storefront-next:sfnext-components` - component conventions used inside extensions
+- `storefront-next:sfnext-routing` - how extension routes join the route tree
+- `storefront-next:sfnext-i18n` - translation namespaces and locale files
+- `storefront-next:sfnext-configuration` - `config.ts` layering and `PUBLIC__` overrides
+- `storefront-next:sfnext-theming` - token and brand changes that do not need an extension
+- `storefront-next:sfnext-commerce-features` - checkout, multiship, BOPIS flows
+- `storefront-next:sfnext-page-designer` - merchant-editable blocks
+- `b2c:b2c-hooks` - B2C platform-side hooks (different from Storefront Next action hooks)

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

@@ -0,0 +1,68 @@
+# 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 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
+
+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: 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, 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.
+```
+
+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.
+
+## Worked examples (real slots)
+
+Find them with `pnpm extensions:list`. The ids below are from a current project; confirm in yours.
+
+| 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 |
+
+### Duplicate section (wrong) vs additive section (right)
+
+```
+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.
+
+RIGHT: fill or extend what the existing collapsibles slot renders, or add only sections
+       the base lacks.
+```
+
+### Restyle, do not re-render
+
+```
+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 slots and render points
+
+```bash
+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
+```
+
+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.