@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

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

@@ -1,141 +1,127 @@
 ---
 name: sfnext-deployment
-description: Build and deploy Storefront Next storefronts to Managed Runtime (MRT) using the sfnext CLI. Use when running production builds, pushing bundles to MRT with sfnext push, configuring deployment environments, or deploying Page Designer cartridges. This is for Storefront Next deployment — for general MRT management via b2c CLI, see b2c-cli:b2c-mrt.
+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`).
 ---
 
-# Deployment Skill
+# Storefront Next Deployment
 
-This skill covers building and deploying Storefront Next storefronts to Managed Runtime (MRT).
+A storefront ships as two independent deployments:
 
-## Overview
+| 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` |
 
-Storefront Next storefronts are deployed to MRT as bundles. The `sfnext` CLI handles building and pushing bundles, while environment configuration is managed through MRT environment variables.
+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).
 
-Reuse the MRT project, environment, and credentials created by Business Manager
-storefront setup. Follow the [deployment guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-push-mrt-auto.html)
-for source deployments and the [launch guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-launch-storefront.html)
-for staging/production rollout. Creating new SLAS clients or MRT resources is not
-a prerequisite to each deployment.
-
-## Production Build
+## Build
 
 ```bash
-# Build for production
-pnpm build
-
-# The build output goes to build/ directory
+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
 ```
 
-The production build:
-
-- Compiles TypeScript to JavaScript
-- Bundles client and server code separately
-- Optimizes and minifies assets
-- Generates the static Page Designer registry
+Run `pnpm typecheck`, `pnpm lint`, and `pnpm test` before pushing. Node 24 is required locally and on MRT (`runtime.ssrParameters.ssrFunctionNodeVersion: '24.x'`).
 
-## Deploying to MRT
+## Push to Managed Runtime
 
-### Using the Template's Push Script
-
-Use the project's `push` script (`sfnext push --project-directory .`). Build first;
-the push command requires existing build output. With the template's pnpm setup:
+`push` does **not** build; it fails if `build/` is missing.
 
 ```bash
-# Push the current build to MRT
-pnpm run push
-
-# Push with a specific message
-pnpm run push --message "Release v1.2.0"
-
-# Push to a specific environment
-pnpm run push --environment staging --wait
+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
 ```
 
-### Deployment Flow
-
-```
-pnpm run build → pnpm run push → MRT receives bundle → Deployed to environment
-```
+| 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 |
 
-See [MRT Deployment Reference](references/MRT-DEPLOYMENT.md) for detailed deployment options.
+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`.
 
-## Environment Configuration
+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 for MRT are configured through:
+## Environment variables on MRT
 
-1. **Runtime Admin or `b2c mrt env var set/push`** — Set application variables per environment; `PUBLIC__` values merge into runtime configuration and are browser-visible. Changes redeploy the environment.
-2. **CLI flags or `MRT_*` environment variables** — Control push/deploy targets
-3. **`.env` files** — Local development only (not deployed)
-
-Use `b2c mrt env var push --file .env.staging --project <project> --environment <environment>`
-to explicitly apply a reviewed file. It shows a diff and prompts; omit local-only
-values and use credentials for the target instance. See [Environment Variables](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html)
-for visibility, naming, and limits. MRT variable management uses the B2C CLI. For live logs, prefer MCP
-`mrt_logs_watch` / `mrt_logs_watch_poll`; CLI alternative: `b2c mrt tail-logs`.
-
-### MRT Deployment Variables
+`.env` is **not** uploaded by `push`. Set runtime config on the MRT environment:
 
 ```bash
-# Project slug (required for push)
-MRT_PROJECT=my-project-slug
-
-# Target environment (optional — if omitted, bundle is uploaded but not deployed)
-MRT_TARGET=development
+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
 ```
 
-### Application Variables (set in MRT Dashboard)
+`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
-PUBLIC__app__commerce__api__clientId=prod-client-id
-PUBLIC__app__commerce__api__organizationId=prod-org-id
-PUBLIC__app__commerce__api__shortCode=prod-short-code
+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
 ```
 
-## Page Designer Cartridge Deployment
+- 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`).
 
-Page Designer metadata must be deployed separately to Commerce Cloud (not MRT):
+## CI/CD
 
-```bash
-# Generate cartridge metadata
-pnpm generate:cartridge
-
-# Deploy cartridge to B2C instance
-pnpm deploy:cartridge
+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.
 
-# Deploy with clean (removes old cartridge first)
-pnpm deploy:cartridge:clean
-
-# Validate cartridge structure
-pnpm validate:cartridge
-```
+## Pre-launch checklist
 
-Cartridge metadata is also auto-generated as part of `pnpm build`.
+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.
 
-## Pre-Deployment Checklist
+## Upgrading a project
 
-1. **Run tests** — `pnpm test`
-2. **Check bundle size** — `pnpm bundlesize:test`
-3. **Verify environment variables** — All required vars set in target environment
-4. **Build successfully** — `pnpm build` completes without errors
-5. **Verify SCAPI credentials** — Client ID and org ID match the target environment
+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
 
-| Issue                          | Cause                         | Solution                                    |
-| ------------------------------ | ----------------------------- | ------------------------------------------- |
-| Build fails                    | TypeScript errors             | Fix type errors; run `pnpm typecheck`       |
-| Push rejected                  | Authentication issue          | Verify sfnext CLI credentials               |
-| 500 errors after deploy        | Missing environment variables | Check all required vars in MRT dashboard    |
-| Stale Page Designer components | Cartridge not deployed        | Re-deploy cartridge via MCP tool or b2c CLI |
+| 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` - Project structure and build configuration
-- `storefront-next:sfnext-configuration` - Environment variable configuration
-- `storefront-next:sfnext-page-designer` - Page Designer cartridge deployment
-- `storefront-next:sfnext-performance` - Bundle size optimization before deployment
-- `b2c-cli:b2c-mrt` - General MRT management via b2c CLI (NOT Storefront Next specific)
+- `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
 
-## Reference Documentation
+## Finding more
 
-- [MRT Deployment Reference](references/MRT-DEPLOYMENT.md) - Detailed deployment options and configuration
+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

@@ -1,90 +1,59 @@
-# MRT Deployment Reference
+# Managed Runtime Deployment Reference
 
-## Managed Runtime (MRT)
+## What MRT provides
 
-MRT is the hosting platform for Storefront Next storefronts. It 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.
 
-- **Server-side rendering** — Node.js runtime for SSR and loader execution
-- **CDN** — Global content delivery for static assets
-- **Environment management** — Separate environments for development, staging, production
-- **Bundle management** — Versioned deployments with rollback capability
+## Push flow
 
-## Deployment Commands
-
-```bash
-# Build, then run the template's push script
-pnpm run build && pnpm run push
-
-# Push with deployment message
-pnpm run push --message "Fix checkout flow"
-
-# Push to specific environment
-pnpm run push --environment production --wait
-
-# Create a bundle without deploying (inspection/custom pipelines)
-pnpm sfnext create-bundle -d . -o .bundle
+```
+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
 ```
 
-## Environment Variables on MRT
-
-### Setting Variables
-
-Environment variables are set per-environment through:
+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`.
 
-1. **Runtime Admin or `b2c mrt env var set/push`** — Application variables on the selected environment; changes redeploy it.
-2. **`MRT_PROJECT`, `MRT_TARGET`, `MRT_API_KEY`** — Deployment target and credentials for `pnpm sfnext push`; these do not upload application variables from `.env`.
+Send extra flags through pnpm with `--`: `pnpm push -- --wait -e production`.
 
-### Variable Limits
+## What push sends to MRT
 
-See Salesforce's [Environment Variables constraints](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html#constraints)
-for current limits. The 32 KB value-size limit covers all environment variables,
-not only `PUBLIC__` values. Public configuration paths must exist in `config.server.ts`.
+- The bundle (server build + client assets).
+- SSR parameters from `config.server.ts` `runtime.ssrParameters` (`ssrFunctionNodeVersion`, `envBasePath`) and `runtime.ssrOnly` / `ssrShared`.
 
-### Production Configuration Example
+It does not send `.env` values or cartridges.
 
-```bash
-# Commerce API credentials
-PUBLIC__app__commerce__api__clientId=prod-client-id
-PUBLIC__app__commerce__api__organizationId=f_ecom_abcd_001
-PUBLIC__app__commerce__api__siteId=RefArchGlobal
-PUBLIC__app__commerce__api__shortCode=kv7kzm78
-
-# Site configuration
-PUBLIC__app__defaultSiteId=RefArchGlobal
-PUBLIC__app__commerce__sites='[{"id":"RefArchGlobal","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"},{"id":"de-DE","preferredCurrency":"EUR"}],"supportedCurrencies":["USD","EUR"]}]'
-
-# Server-only secrets (not exposed to client)
-COMMERCE_API_SLAS_SECRET=production-slas-secret
-```
+## Environment variables
 
-## Bundle Management
+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).
 
-Each `sfnext push` creates a versioned bundle on MRT:
+Example of per-environment application variables (values are yours):
 
-```
-Bundle v1 (active) ← current production
-Bundle v2          ← previous deployment
-Bundle v3          ← two deployments ago
+```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"]}]'
 ```
 
-### Rollback
+## Domains, base path, cookies
 
-If a deployment causes issues, roll back to a previous bundle via the MRT Dashboard or CLI.
+- 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`.
 
-## Multi-Environment Setup
+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`.
 
-| Environment | Purpose                   | Auto-deploy           |
-| ----------- | ------------------------- | --------------------- |
-| Development | Feature testing           | From feature branches |
-| Staging     | Pre-production validation | From main branch      |
-| Production  | Live storefront           | Manual promotion      |
+## Rollback
 
-## Deployment Verification
+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`).
 
-After deploying, verify:
+## Verifying a deployment
 
-1. **Health check** — Site loads without errors
-2. **SCAPI connectivity** — Products and categories display correctly
-3. **Authentication** — Login/logout flow works
-4. **Page Designer** — Merchant-editable pages render correctly
-5. **Performance** — No regression in page load times
+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

@@ -1,142 +1,118 @@
 ---
 name: sfnext-extensions
-description: Build extensions for Storefront Next using target-config.json, target points, extension routes, and translation namespaces. Use when creating modular features, inserting components into UI targets, adding extension routes, adding a section to an existing page, or using SFDC_EXT_ integration markers. Covers the base-audit decision gate (deciding whether to extend at all vs token/variant override), extension structure, targetId configuration, and extension registration in src/extensions/config.json.
+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`).
 ---
 
-# Extensions Skill
+# Storefront Next Extensions
 
-This skill covers the Storefront Next extension system — modular features that plug into the storefront via target points.
+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.
 
-## Overview
+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).
 
-Extensions are self-contained feature modules that add components, routes, translations, and providers to a Storefront Next storefront without modifying core code.
+## Decision gate: should this be an extension?
 
-## Before You Build — Audit the Base First (Decision Gate)
+Run this before writing code; the full walkthrough is in [Base Audit](references/BASE-AUDIT.md).
 
-An extension is the right tool for adding something the storefront does **not already render**. Before scaffolding one, confirm you actually need it — a duplicated section costs you on every page load, every test, and every design sync.
+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.
 
-Run this gate **before writing any extension code**:
+Discover what already exists:
 
-1. **Find the base.** Open the relevant route in `src/routes/` and trace every component it renders.
-2. **Check each section you intend to add.** Does the base already render equivalent content at that location (a description, accordion, badge, banner, title…)?
-   - **YES** → do not create a parallel component. Restyle it through the token/brand layer (a CVA variant or `brand.css` value), or inject into a UITarget slot on the existing content. Adding a duplicate section is a bug, not a feature.
-   - **NO** → an extension is justified. Continue to the structure below and register it at the correct `targetId`.
-3. **Decide the layer for what's missing:**
-
-   ```
-   Is the change purely visual (color, font, spacing)?
-     └─ YES → Token / CVA change (brand.css or a component variant). No extension needed.
-     └─ NO  → Is the new structure needed by only one storefront/vertical?
-                 └─ YES → Extension at a UITarget slot (this skill). Never edit core.
-                 └─ NO  → It's a shared pattern — add a slot/render-prop to the BASE
-                          component instead, and let each consumer fill it.
-   ```
-
-**Rule of thumb:** extensions *add what is missing*; they never recreate what already exists. When in doubt, prefer a UITarget slot or a token override over a new component.
-
-See [Base Audit Reference](references/BASE-AUDIT.md) for worked examples of the gate.
+```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
+```
 
-## Extension Structure
+## Structure
 
 ```
 src/extensions/my-extension/
-├── target-config.json    # Target configuration (components/providers)
-├── components/           # Extension components
-├── routes/              # Extension routes (auto-registered)
-├── locales/             # Extension translations (auto-namespaced)
-└── providers/           # Extension context providers
+├── 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
 ```
 
-## Target Configuration
+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.
 
-The `target-config.json` file declares how the extension integrates:
+## target-config.json
 
 ```json
 {
   "components": [
-    {
-      "targetId": "header.before.cart",
-      "path": "extensions/my-extension/components/badge.tsx",
-      "order": 0
-    }
+    { "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
-    }
+    { "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 }
   ]
 }
 ```
 
-### Target Points
+- `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.
 
-Target points are named insertion slots in the storefront layout (for example, `header.before.cart`). Extensions insert components at these points via `targetId`.
-
-Extension availability is managed in `src/extensions/config.json`, where each extension is keyed by an `SFDC_EXT_*` marker.
-
-## Extension Routes
-
-Files in the `routes/` directory auto-register as routes:
-
-```typescript
-// src/extensions/my-extension/routes/my-route.tsx
-export function loader() {
-    return { message: 'Hello' };
-}
+Server-side hooks (`actionHooks`, checkout steps) have their own semantics: [Action Hooks](references/ACTION-HOOKS.md).
 
-export default function MyRoute() {
-    const { message } = useLoaderData();
-    return <div>{message}</div>;
-}
-```
+## Routes, translations, config
 
-## Extension Translations
+- **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`.
 
-Translations are auto-namespaced as `extPascalCase` based on the directory name:
+## Integration markers
 
-```
-src/extensions/my-extension/locales/
-├── en-US/translations.json
-└── it-IT/translations.json
-```
+Extensions that modify base files mark their edits with comments so they can be installed and removed cleanly:
 
 ```typescript
-const {t} = useTranslation('extMyExtension');
-t('welcome');
-```
-
-## Integration Markers
+selectedStoreMiddleware /** @sfdc-extension-line SFDC_EXT_STORE_LOCATOR */,
 
-Mark extension integration points in core code:
+// @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
 
-```typescript
-// Single line marker
-/** @sfdc-extension-line SFDC_EXT_MY_FEATURE */
-import myFeature from '@extensions/my-feature';
-
-// Block marker
-{/* @sfdc-extension-block-start SFDC_EXT_MY_FEATURE */}
-<Link to="/my-feature">My Feature</Link>
-{/* @sfdc-extension-block-end SFDC_EXT_MY_FEATURE */}
+/** @sfdc-extension-file SFDC_EXT_STORE_LOCATOR */   // marks an entire file as belonging to the extension
 ```
 
-See [Extension Examples Reference](references/EXTENSION-EXAMPLES.md) for complete examples.
+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).
 
-## Best Practices
+## Removing or replacing a demo extension
 
-1. **Self-contained** — Each extension should be independent
-2. **Use target points** — Insert UI via `target-config.json` rather than editing core files
-3. **Namespace translations** — Auto-namespacing prevents collisions
-4. **Order matters** — Use `order` in `target-config.json` to control rendering order
+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/`.
 
-## Related Skills
+## Best practices
 
-- `storefront-next:sfnext-i18n` - Translation patterns and namespace usage
-- `storefront-next:sfnext-routing` - How extension routes integrate with the router
-- `storefront-next:sfnext-components` - Component patterns used in extensions
+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.
 
-## Reference Documentation
+## Related Skills
 
-- [Base Audit Reference](references/BASE-AUDIT.md) - Worked examples of the decision gate (extend vs token/variant vs base slot)
-- [Extension Examples Reference](references/EXTENSION-EXAMPLES.md) - Complete extension examples
+- `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)