@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/content/guidance/storefront-next/sfnext-performance/references/PERFORMANCE-REVIEW-CHECKLIST.md

@@ -0,0 +1,85 @@
+# Performance self-review checklist
+
+Run this on your own diff before you call a change done, especially when it adds a loader, fetcher, Suspense boundary, modal, context or action. For each section, find the relevant lines in the diff, answer the questions, and fix what fails. Related docs in your project: `docs/README-DATA.md`, `docs/README-SUSPENSE.md`, `docs/README-REVALIDATION.md`, `docs/README-PERFORMANCE.md`.
+
+Impact of a problem is roughly: traffic of the page x instances of the component on it x cost of one occurrence. A fetch in a product tile on a listing page multiplies by every tile; a layout loader re-run multiplies by every action on every page.
+
+## 1. Fetch efficiency
+
+Map the fetch topology for each user gesture (load, navigation, add to cart, open modal): which loaders, fetchers and SCAPI calls run, and in what order.
+
+- [ ] Overlapping loaders: do two active loaders read the same resource? Move it to the lowest common layout and share via `useRouteLoaderData`.
+- [ ] Dependent data chained across round trips (fetch A, then B using A, then enrichment) belongs in one loader, with independent calls started in parallel first.
+- [ ] Write-in-read: does a GET path create or mutate server state (for example "get or create basket")? Reads called from many places then race or duplicate writes. Separate creation from reads.
+- [ ] Prefetch and consume: if one component prefetches and another consumes the same data, they must share one fetcher key, or the data is fetched twice.
+- [ ] Unstable references in effect dependencies (object or array literals, fresh callbacks) re-fire fetches on every render. Depend on primitives or stable refs.
+- [ ] Fetcher hooks inside list items: N items means N registered fetchers and, when they load on mount, N requests. A `useFetcher` used only on interaction is not amplification; one that loads on mount is. Lift the data into the parent loader or a single batched call (`fetchProductsByIds`).
+- [ ] Payload: only the `expand`/`select` values the UI renders.
+
+## 2. Fetcher misuse
+
+Is this a fetcher that should be a loader?
+
+- [ ] A fetch on mount or render whose inputs are known at request time (route params, search params, cookies, context) belongs in the loader. This includes indirect forms: `useEffect` calls an async function that calls `fetch` or `fetcher.load()`, and fetches inside error fallbacks.
+- [ ] Does the component ignore `loaderData` and re-fetch the same data? Use the loader data.
+- [ ] Legitimate uses: gesture-gated loads (click, hover, open), client-only inputs (geolocation, local selection), re-fetching after a mutation, intent-based prefetch.
+
+## 3. Suspense placement
+
+- [ ] Every `use(promise)` and `<Await>` has a `<Suspense>` ancestor.
+- [ ] The boundary is as low as possible: it wraps only the subtree that reads the promise, not the page or layout.
+- [ ] The fallback reserves the final size (no layout shift) and is not `null` above the fold without reserved space.
+
+## 4. Suspense granularity
+
+- [ ] Independent consumers have sibling boundaries, so a slow promise does not hold back a fast one.
+- [ ] One logical unit that must appear together shares one boundary and one promise composed in the loader.
+- [ ] No boundary wrapped around content that is already resolved.
+
+## 5. Promise stability
+
+A new promise object on each render restarts suspension and flashes the fallback.
+
+- [ ] Stable sources only: `loaderData`, `useRouteLoaderData`, `useOutletContext`, props derived from them, `useRef`, `useState` lazy-pinned, module constants.
+- [ ] No `Promise.all/race/allSettled`, `.then/.catch/.finally`, `new Promise`, or async IIFE in render. No `useMemo` around a promise.
+- [ ] Fixes: compose and transform in the loader (`.then` there); split into separate boundaries; pin with `useState(() => ...)` or re-pin with `useRef` keyed on inputs.
+
+## 6. Hydration and render stability
+
+Render scope should not exceed data-change scope.
+
+- [ ] Values read only inside event handlers or callbacks live in `useRef`, or are read at call time (for example `matchMedia` inside the handler), not in state or Context.
+- [ ] Hidden subscribers: components that subscribe to a store but render nothing visible still re-render; return `null` early or move the subscription to the component that renders.
+- [ ] Context values are memoized (`useMemo`/`useCallback`); check every field each consumer reads during render, and split state from updaters.
+- [ ] Subscriptions sit at the consumer, or in a render-nothing manager that writes to a ref/store.
+- [ ] `useSyncExternalStore`: `getServerSnapshot` matches the first client render; `getSnapshot` returns a stable reference when nothing changed.
+
+## 7. Revalidation scope
+
+After an action, every active loader re-runs by default.
+
+- [ ] For each new or changed action and each active loader (matched chain, mounted resource fetchers, open modals and drawers): is there overlap (does the result change what the loader reads) and is the value otherwise unavailable (provider not already updated)? If either is false, gate the loader with `shouldRevalidate`.
+- [ ] Confirm the trigger is a real submission (`Form`, `useSubmit`, `fetcher.submit`). Raw `fetch` or SCAPI client calls trigger nothing.
+- [ ] Modals and drawers count twice: as targets (fetchers they load when open) and as triggers (actions they submit). Unmount them when closed (`useDeferredUnmount`).
+- [ ] A gate must inspect the action path or `actionResult`; checking only that `formAction` is set still re-runs on everything.
+- [ ] Do not gate off a re-run that is the sync mechanism for a provider.
+
+See `storefront-next:sfnext-revalidation`.
+
+## 8. Client-side transforms
+
+- [ ] Shape data in the loader, not during render: lookup maps, chained filter/map passes, deep spreads, slug or URL normalization.
+- [ ] `useMemo` does not fix transforming loader data on every mount; move it to the loader.
+- [ ] Exceptions: values derived from UI state (selected variant, local filter), and work inside event handlers.
+
+## 9. Also check
+
+- [ ] Images: LCP image has `priority="high"` and is not lazy; `widths` match the layout.
+- [ ] New dependency: check bundle impact with `pnpm bundlesize`; lazy-load heavy, hidden UI.
+- [ ] Third-party scripts: `async` or `defer`, loaded after consent where required.
+- [ ] New preconnect only for origins used on every page.
+- [ ] Added routes export the right `shouldRevalidate`.
+
+## Reporting
+
+For each finding note where it is (file and line), the rule it breaks, who pays (every shopper, every tile, every action), and the smallest fix. Prefer fixing the highest-multiplier problems first.

package/content/guidance/storefront-next/sfnext-performance/references/SUSPENSE-AND-STREAMING.md

@@ -0,0 +1,58 @@
+# Suspense and streaming recipes
+
+Read `docs/README-SUSPENSE.md` in your project for the full guide.
+
+## Placement
+
+Every component that calls `use(promise)` or renders `<Await>` must sit under a `<Suspense>`. Place the boundary as low as possible, around only the subtree that reads the promise, so the rest of the page is not held back. A consumer with no boundary above it suspends the nearest ancestor (often the whole route) and blocks the shell.
+
+```tsx
+// Bad: boundary wraps the page; one slow promise hides everything
+<Suspense fallback={<PageSkeleton />}><Page /></Suspense>
+
+// Good: boundary wraps only the reader
+<Header />
+<Suspense fallback={<ReviewsSkeleton />}><Reviews promise={loaderData.reviews} /></Suspense>
+```
+
+## Granularity
+
+- Independent data: sibling boundaries, so each resolves on its own.
+- One logical unit that must appear together: one promise composed in the loader, one boundary.
+- Do not nest a boundary per field of one entity; do not share one boundary across unrelated promises.
+
+## Promise stability
+
+Stable sources: `loaderData`, `useRouteLoaderData`, `useOutletContext`, props passed from those, `useRef`, `useState` lazy pinned, module-level constants.
+
+Unstable (new identity each render): `Promise.all/race/allSettled` in render, `.then`/`.catch`/`.finally` chains in render, `new Promise`, async IIFEs, `useMemo(() => promise)`.
+
+Fixes:
+
+```ts
+// in the loader: compose there
+const summary = Promise.all([a(), b()]).then(([x, y]) => ({ x, y }));
+return { summary };
+```
+
+```tsx
+// component-local promise that depends on props: pin it
+const [promise] = useState(() => fetchSomething(id));          // lazy pin, fixed for mount
+// or re-pin only when the key changes
+const ref = useRef<{ key: string; p: Promise<Data> }>();
+if (ref.current?.key !== id) ref.current = { key: id, p: fetchSomething(id) };
+```
+
+Client-side `fetchSomething` here must be a fetcher-driven or already-started promise; prefer composing in the loader whenever the data is knowable there.
+
+## Skeletons
+
+Size the skeleton to the final content (same height and grid) to avoid layout shift. For listing grids reuse the product-grid skeleton and `DeferredProductGrid`.
+
+## Critical Page Designer regions
+
+Page-level LCP region: `await` the page in the loader and render `<Region critical>` (no region fallback element). Component-level data inside keeps its own boundaries.
+
+## Errors in streamed data
+
+A rejected promise reaches the nearest `errorElement` on `<Await>` or the route `ErrorBoundary`. For optional sections use `errorElement={null}` and log in the loader; for important ones show an inline retry.

package/content/guidance/storefront-next/sfnext-project-setup/SKILL.md

@@ -1,160 +1,147 @@
 ---
 name: sfnext-project-setup
-description: Create and configure Storefront Next projects. Use when creating a new storefront, understanding project structure, setting up environment variables, or running the sfnext CLI for the first time. Covers project creation, directory layout, .env configuration, and sfnext CLI basics.
+description: >-
+  Create and bootstrap a Storefront Next project, and learn its layout, npm scripts, and first-run workflow.
+  Use when creating a new storefront, running `sfnext create-storefront` (`--vertical` starter theme, `--defaults`,
+  `--template`, `--output-dir`), choosing between Business Manager Storefront Setup and the CLI, fixing
+  `pnpm install` / Node 24 problems, copying `.env.default` to `.env`, asking "what does this folder do" or
+  "which pnpm script do I run", or running `b2c sfnext` / `pnpm sfnext` commands for the first time.
+  Do not use for config.server.ts or PUBLIC__ env var rules (use `storefront-next:sfnext-configuration`),
+  building/pushing to Managed Runtime (use `storefront-next:sfnext-deployment`), or a conceptual tour of the
+  architecture (use `storefront-next:sfnext-overview`).
 ---
 
-# Project Setup Skill
+# Storefront Next Project Setup
 
-This skill guides you through creating and configuring a Storefront Next project — a server-rendered SPA built on React 19, React Router 7, Vite, and Tailwind CSS v4.
+A Storefront Next project is a server-rendered React 19 / React Router 7 / Vite / Tailwind v4 app that runs on Managed Runtime (MRT). All SCAPI calls run server-side. You own the project code after it is created.
 
-## Overview
+**Read the project's own `AGENTS.md` first.** It ships in every project (`CLAUDE.md` is a copy) and is the authority for data-loading, Suspense, state, image, and navigation rules. This skill never overrides it. Detailed guides live in the project's `docs/README-*.md`.
 
-Storefront Next storefronts run on Managed Runtime (MRT) with all SCAPI requests executing server-side. Use Business Manager storefront setup for an instance-connected storefront; use `create-storefront` for local exploration. Project application source uses TypeScript (`.ts`/`.tsx`); follow the project's configuration for build scripts.
+## Prerequisites
 
-## Creating a Project
+- Node.js >= 24 (`package.json` `engines`; MRT also runs Node 24)
+- pnpm >= 10.28
+- A B2C Commerce instance with a SLAS public client, your organization ID, and the SCAPI short code (unless you only want the bundled demo backend)
 
-### Via Business Manager (instance-connected storefront)
+## Choose how to start
 
-Prefer storefront setup: it creates API clients, MRT resources, initial configuration,
-and a deployment. Reuse those resources; do not create replacement SLAS clients or
-MRT projects as routine setup. Choose the [GitHub workflow](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm-github.html)
-or [local-code workflow](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm.html).
-Use the downloaded `env.txt` as the project's `.env`; do not invent tenant/site IDs
-or expose its secrets. Guide the user through Business Manager when setup is needed.
+| Path | Use when |
+| --- | --- |
+| Business Manager **Storefront Setup** (GitHub or local-code workflow) | You want an instance-connected storefront. It creates the SLAS client, the MRT project/environments, initial config, and a first deployment. Reuse those resources; do not create replacement SLAS clients or MRT projects as routine setup. Use the downloaded `env.txt` as `.env`. Guides: [GitHub workflow](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm-github.html), [local-code workflow](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-quick-start-create-bm.html) |
+| `sfnext create-storefront` | You want a fresh local project from a starter theme, with your own extension selection and credentials |
+| Clone / "Use this template" of a published starter repo | You prefer plain git; the project README lists the starter repositories |
 
-### Via CLI (local exploration)
+Never invent tenant/site IDs and never echo secrets from `env.txt`.
 
-Use for template exploration without provisioning instance resources. To connect
-to the user's instance, follow storefront setup above and use its configuration.
+## Create a project with the CLI
 
 ```bash
-# Create a new storefront project (interactive)
+# Interactive: pick a starter theme, name, extensions, and credentials
 pnpm dlx @salesforce/storefront-next-dev create-storefront
+# or, with the b2c CLI (auto-installs the sfnext plugin on first use)
+b2c sfnext create-storefront
 
-# Or create with a name flag
-pnpm dlx @salesforce/storefront-next-dev create-storefront --name my-storefront
-
-# Navigate into the project
-cd my-storefront
-
-# Install dependencies
-pnpm install
-
-# Start development server
-pnpm dev
-```
-
-## Project Structure
-
-```
-my-storefront/
-├── .env.default              # Default environment variables (template)
-├── .env                      # Local overrides (git-ignored)
-├── config.server.ts          # Centralized configuration with defaults
-├── vite.config.ts            # Vite build configuration
-├── package.json              # Dependencies and scripts
-├── src/
-│   ├── app.css               # Global styles and Tailwind theme
-│   ├── root.tsx              # Root layout component
-│   ├── routes/               # File-based routes (React Router 7)
-│   │   ├── _app.tsx          # App layout (authenticated shell)
-│   │   ├── _app._index.tsx   # Home page
-│   │   └── _app.product.$productId.tsx
-│   ├── components/           # Reusable UI components
-│   │   ├── ui/               # shadcn/ui base components (customizable)
-│   │   └── ...               # Custom components
-│   ├── config/               # Configuration schema and context
-│   │   └── schema.ts         # Config type definitions
-│   ├── lib/                  # Utilities and API client setup
-│   │   ├── api-clients.ts    # createApiClients() factory
-│   │   ├── utils.ts          # cn() utility and helpers
-│   │   └── registry.ts       # Page Designer component registry
-│   ├── locales/              # Translation files
-│   │   └── en-US/
-│   │       └── translations.json
-│   ├── middlewares/          # Server middleware
-│   │   ├── auth.server.ts    # Authentication middleware
-│   │   └── basket.server.ts  # Basket middleware
-│   ├── providers/            # React context providers
-│   ├── hooks/                # Custom React hooks
-│   ├── extensions/           # Extension modules
-│   └── test-utils/           # Shared test utilities
-├── public/                   # Static assets
-└── cartridges/               # Page Designer cartridge metadata
+# Non-interactive
+sfnext create-storefront -n my-storefront --vertical cosmetic -o ./projects
+sfnext create-storefront -n my-storefront --defaults
 ```
 
-See [Project Structure Reference](references/PROJECT-STRUCTURE.md) for detailed directory explanations.
+| Flag | Meaning |
+| --- | --- |
+| `-n, --name` | Project name |
+| `-V, --vertical` | Starter theme: `fashion` (default with `--defaults`), `cosmetic`, `foundations`, `footwear`, `furniture`, `luxury` |
+| `-t, --template` | Template repo URL or local path (overrides `--vertical`) |
+| `-b, --template-branch` | Branch or tag to clone |
+| `-d, --defaults` | Accept all defaults, no prompts (CI) |
+| `-o, --output-dir` | Where to create the project |
 
-## Environment Setup
+What it does: shallow-clones the chosen starter, removes `.git`, asks which **extensions** to keep (and trims the rest; manage them later with `sfnext extensions ...`, see `storefront-next:sfnext-extensions`), prompts for the values in `config-meta.json` (SLAS client ID, organization ID, short code), and writes `.env` from `.env.default`.
 
-For Business Manager-created storefronts, use the downloaded configuration.
-For local CLI exploration, copy `.env.default` to `.env`:
+Then:
 
 ```bash
-cp .env.default .env
+cd my-storefront
+pnpm install
+pnpm dev          # http://localhost:5173
 ```
 
-### Required Variables
+## First run
 
-Use values from the selected storefront. This is a configuration example, not a
-request to provision new credentials. See Salesforce's [Environment Variables](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-environment-vars.html)
-for public/server-only visibility and supported paths.
+`.env.default` ships with a public demo backend so `cp .env.default .env && pnpm dev` boots. **Only `.env` is read**; `.env.default` is never loaded. Replace the three required values with your own before pointing at real data:
 
 ```bash
-PUBLIC__app__commerce__api__clientId=your-client-id
-PUBLIC__app__commerce__api__organizationId=your-org-id
-PUBLIC__app__commerce__api__siteId=your-site-id
-PUBLIC__app__commerce__api__shortCode=your-short-code
-PUBLIC__app__defaultSiteId=your-site-id
-PUBLIC__app__commerce__sites='[{"id":"your-site-id","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]'
+PUBLIC__app__commerce__api__clientId=...
+PUBLIC__app__commerce__api__organizationId=...
+PUBLIC__app__commerce__api__shortCode=...
 ```
 
-See [Environment Variables Reference](references/ENV-VARIABLES.md) for the complete variable list and naming rules.
+Restart the dev server after editing `.env`. Dev fails fast if the short code is missing. Everything else has defaults in `config.server.ts`; see `storefront-next:sfnext-configuration`. If the project should target your own site, also set `PUBLIC__app__defaultSiteId` and `PUBLIC__app__commerce__sites` (JSON array) as described there.
 
-## Development Commands
+Before shipping, run through the pre-launch gate in `storefront-next:sfnext-deployment` (demo analytics IDs, staging image host, demo credentials).
 
-```bash
-# Start development server with hot reload
-pnpm dev
+## Project layout (short form)
 
-# Build for production
-pnpm build
+```
+my-storefront/
+├── AGENTS.md / CLAUDE.md        # Rules for coding agents -- read first
+├── config.server.ts             # All app config defaults (metadata / runtime / app)
+├── config-meta.json             # Values create-storefront prompts for
+├── .env.default, .env           # Required credentials; only .env is loaded
+├── package.json                 # Scripts + storefrontNext version stamp
+├── react-router.config.ts, vite.config.ts, vite-plugins/
+├── src/
+│   ├── routes/                  # Flat file routes (_app.*, _checkout.*, _empty.*, action.*, resource.*)
+│   ├── components/ (ui/ = primitives), hooks/, providers/, lib/, middlewares/
+│   ├── extensions/              # Optional feature modules + config.json registry
+│   ├── theme/                   # index.css entry, tokens/, overrides/
+│   ├── locales/                 # <lang-REGION>/translations.json
+│   ├── scapi/                   # Generated + custom SCAPI clients
+│   ├── targets/                 # UI target (extension point) system
+│   └── types/config.ts          # AppConfig type
+├── cartridges/app_storefrontnext_base   # Page Designer metadata cartridge
+├── docs/                        # README-*.md guides, COMPATIBILITY.md, migrations/
+├── instructions/                # Extension install/uninstall guides (.mdc)
+├── e2e/                         # Playwright suite (own package)
+└── public/
+```
 
-# Run tests
-pnpm test
+See [PROJECT-STRUCTURE.md](references/PROJECT-STRUCTURE.md) for route families, key files, and where to go for each concern.
 
-# Run Storybook
-pnpm storybook
+## Scripts and CLI
 
-# Check bundle size
-pnpm bundlesize:test
-```
+Run `pnpm <script>`. The most used: `dev`, `build`, `start` (preview the production build on :3000), `typecheck`, `lint`, `test`, `push`, `cartridge:generate|validate|deploy`, `config:inspect`, `config:push-env`, `bundlesize`, `storybook`. Full table in [SCRIPTS.md](references/SCRIPTS.md). The project's `package.json` `scripts` is the source of truth; grep it instead of guessing.
+
+The `sfnext` binary (from `@salesforce/storefront-next-dev`, already a project dependency) is also reachable as `pnpm sfnext <cmd>` or `b2c sfnext <cmd>` (the b2c CLI prefers the project-local copy when run inside the project). Command reference: [SFNEXT-CLI.md](references/SFNEXT-CLI.md). The template also exposes `pnpm b2c` for the b2c CLI.
 
-## Non-Negotiable Rules
+## Conventions worth knowing up front
 
-1. **TypeScript only** — `.ts` and `.tsx` files; JavaScript files are blocked by ESLint
-2. **Server-only data loading** — Use `loader` functions; never use client loaders
-3. **Synchronous loaders** — Return promises, do not use `async`/`await` (enables streaming)
-4. **Tailwind CSS 4 only** — No inline styles, CSS modules, or separate CSS files
-5. **Use `createPage()` HOC** — Standardizes page patterns with Suspense
+- Application code is TypeScript/TSX only (`node scripts/check-typescript-only.js` flags stray `.js`). Linting is OxLint (`pnpm lint`, zero warnings), formatting is Biome (`pnpm format`).
+- Imports use the `@/` alias to `src/`. Server-only modules are suffixed `.server.ts`.
+- Use the site-aware `Link`/`NavLink` from `@/components/link` and `useNavigate` from `@/hooks/use-navigate`, not the React Router originals.
+- Server `loader`/`action` only; no `clientLoader`/`clientAction`. Await only critical data; return non-critical data as promises (`storefront-next:sfnext-data-fetching`).
+- Version compatibility between your project and the SDK: `package.json#storefrontNext` and `docs/COMPATIBILITY.md`.
 
 ## Troubleshooting
 
-| Issue                   | Cause                               | Solution                                              |
-| ----------------------- | ----------------------------------- | ----------------------------------------------------- |
-| SCAPI 401 errors        | Missing or invalid credentials      | Verify `.env` variables match your Commerce Cloud org |
-| JavaScript file errors  | `.js`/`.jsx` files in source        | Rename to `.ts`/`.tsx`; ESLint blocks JS files        |
-| Dev server not starting | Missing dependencies                | Run `pnpm install`                                    |
-| Config not loading      | Missing `config.server.ts` defaults | Define defaults before using environment overrides    |
+| Symptom | Cause / fix |
+| --- | --- |
+| `pnpm install` fails or engine warning | Node < 24 or pnpm < 10.28; upgrade both |
+| Dev server exits immediately about short code | `PUBLIC__app__commerce__api__shortCode` missing in `.env` (not `.env.default`) |
+| SCAPI 401/403 | Client ID / organization ID / short code do not match the same org, or the SLAS client lacks scopes; run `sfnext setup-base-cartridge --slas-client-id <id>` only if the base cartridge scopes are the issue |
+| `.env` change ignored | Restart `pnpm dev`; check with `pnpm config:inspect` |
+| Unknown `sfnext` command via `b2c` | First use installs the plugin; run inside the project so the local copy is used |
 
-## Related Skills
+## Finding more
 
-- `storefront-next:sfnext-configuration` - Ongoing configuration management and multi-site setup
-- `storefront-next:sfnext-routing` - File-based routing conventions
-- `storefront-next:sfnext-data-fetching` - Server-side data loading patterns
-- `storefront-next:sfnext-deployment` - Building and deploying to MRT
+- Project `AGENTS.md` doc index and `docs/README-*.md`
+- `b2c docs search "<topic>" --category sfnext` (or MCP `docs_search`) for the published Storefront Next guides
 
-## Reference Documentation
+## Related Skills
 
-- [Project Structure Reference](references/PROJECT-STRUCTURE.md) - Detailed directory and file explanations
-- [Environment Variables Reference](references/ENV-VARIABLES.md) - Complete variable list and naming rules
+- `storefront-next:sfnext-overview` - Architecture and concept tour
+- `storefront-next:sfnext-configuration` - config.server.ts, PUBLIC__ env vars, multi-site URLs
+- `storefront-next:sfnext-deployment` - Build, push to MRT, cartridge deploy, pre-launch gate
+- `storefront-next:sfnext-routing` - File routes and site-aware links
+- `storefront-next:sfnext-extensions` - Install, remove, and create extensions
+- `storefront-next:sfnext-theming` - Rebranding `src/theme/`
+- `b2c-cli:b2c-mrt` - Generic MRT project/environment management

package/content/guidance/storefront-next/sfnext-project-setup/references/PROJECT-STRUCTURE.md

@@ -1,99 +1,61 @@
-# Project Structure Reference
-
-## Top-Level Files
-
-| File               | Purpose                                                                                    |
-| ------------------ | ------------------------------------------------------------------------------------------ |
-| `config.server.ts` | Centralized configuration with typed defaults; environment variables override these values |
-| `.env.default`     | Template of all supported environment variables; copy to `.env` for local development      |
-| `.env`             | Local environment overrides (git-ignored)                                                  |
-| `vite.config.ts`   | Vite build configuration including plugins (static registry, etc.)                         |
-| `package.json`     | Dependencies, scripts, and bundle size limits (`bundlesize` config)                        |
-| `tsconfig.json`    | TypeScript configuration with `@/` path alias mapping to `src/`                            |
-
-## Source Directory (`src/`)
-
-### `src/routes/`
-
-File-based routing using React Router 7 flat-routes convention. File names map to URL paths:
-
-| File                                | URL                                  |
-| ----------------------------------- | ------------------------------------ |
-| `_app.tsx`                          | Layout wrapper (no URL segment)      |
-| `_app._index.tsx`                   | `/` (home page)                      |
-| `_app.product.$productId.tsx`       | `/product/:productId`                |
-| `_app.category.$categoryId.tsx`     | `/category/:categoryId`              |
-| `_app.cart.tsx`                     | `/cart`                              |
-| `resource.api.client.$resource.tsx` | Resource route for `useScapiFetcher` |
-
-Each route module can export: `loader`, `action`, `default` (component), `meta`, `handle`, `ErrorBoundary`.
-
-### `src/components/`
-
-Reusable UI components organized in directories:
-
-```
-src/components/product-tile/
-├── index.tsx              # Component implementation
-├── index.test.tsx         # Vitest unit tests
-└── stories/
-    └── index.stories.tsx  # Storybook stories
-```
-
-**`src/components/ui/`** — shadcn/ui components added via `npx shadcn@latest add <name>`. These are copied into your codebase and can be customized directly.
-
-### `src/config/`
-
-Configuration system:
-
-- `schema.ts` — TypeScript type definitions for the config shape
-- `context.tsx` — React context provider (`ConfigProvider`) and `useConfig()` hook
-- `index.ts` — Exports `getConfig()` and `useConfig()`
-
-### `src/lib/`
-
-Utilities and shared logic:
-
-- `api-clients.ts` — `createApiClients(context)` factory for SCAPI clients
-- `utils.ts` — `cn()` class name utility (merges Tailwind classes)
-- `registry.ts` — Page Designer component registry
-- `static-registry.ts` — Auto-generated by Vite plugin (do not edit)
-
-### `src/locales/`
-
-Translation files organized by locale:
-
-```
-src/locales/
-├── en-US/translations.json
-├── de-DE/translations.json
-└── fr-FR/translations.json
-```
-
-### `src/middlewares/`
-
-Server middleware:
-
-- `auth.server.ts` — SLAS authentication, token management, `getAuth(context)`
-- `basket.server.ts` — Basket middleware and request-context basket resource helpers
-
-### `src/extensions/`
-
-Extension modules with their own routes, components, translations, and providers. Extensions typically include `target-config.json` (for `targetId` component/provider insertion) and are registered in `src/extensions/config.json`.
-
-### `src/test-utils/`
-
-Shared test utilities:
-
-- `config.ts` — Mock configuration for tests
-- `context-provider-utils.ts` — Context provider helpers
-- `context-provider.tsx` — Test wrapper providers
-
-## Build Output
-
-- `build/` — Production build output (server and client bundles)
-- `coverage/` — Test coverage reports
-
-## Cartridges
-
-- `cartridges/` — Page Designer cartridge with experience metadata (component/page JSON definitions generated by MCP tools)
+# Project Structure
+
+A short map of a Storefront Next project. The project's `AGENTS.md` ("Project Structure") is authoritative and kept current; use `ls` on the project rather than trusting any long listing, including this one.
+
+## Top level
+
+| Path | Purpose |
+| --- | --- |
+| `AGENTS.md`, `CLAUDE.md` | Rules and doc index for coding agents |
+| `config.server.ts` | Typed defaults for the whole app (`metadata`, `runtime`, `app`). Edited by you; overridden per environment with `PUBLIC__` env vars |
+| `config-meta.json`, `config-metadata/` | Values `sfnext create-storefront` prompts for; config metadata |
+| `.env.default` / `.env` | Required credentials and MRT target. Only `.env` is read |
+| `package.json` | Scripts, dependencies, and `storefrontNext` (`templateRelease`, `templateVersion`, `minSdkVersion`) |
+| `react-router.config.ts`, `vite.config.ts`, `vite-plugins/` | Framework and build config; plugins for bundle size, env validation, hybrid proxy, server-only-config guard |
+| `components.json` | shadcn config (CSS entry is `src/theme/index.css`) |
+| `cartridges/app_storefrontnext_base/` | Base cartridge; Page Designer metadata is generated into it |
+| `docs/` | `README-*.md` guides, `COMPATIBILITY.md`, `migrations/` upgrade guides |
+| `instructions/` | Install/uninstall instructions for extensions (`.mdc`) |
+| `e2e/` | Playwright end-to-end and accessibility suite (its own package) |
+| `scripts/` | Helper scripts behind `lint:a11y`, `lint:css`, `bundlesize:compare`, `storybook:test`, `extensions:list`, ... |
+| `.storybook/`, `.github/`, `.devcontainer/`, `.claude/skills/sync-shadcn` | Storybook, CI workflows, dev container, in-project skill for syncing shadcn primitives |
+| `public/` | Static assets (fonts, images, robots.txt, favicon) |
+
+## `src/`
+
+| Path | Notes |
+| --- | --- |
+| `routes/` | Flat file routes. Families: `_app.*` (storefront shell), `_checkout.*`, `_empty.*` (login, signup, maintenance; minimal chrome), `action.*` (server mutations), `resource.*` (resource routes). Products and categories are splats: `_app.p.$.tsx`, `_app.c.$.tsx`. Orders use `$orderNo`. See `storefront-next:sfnext-routing` |
+| `routes.ts`, `route-paths.ts` | Route registration and typed path helpers (`routeHref`) |
+| `root.tsx`, `entry.client.tsx`, `entry.server.tsx`, `app-wrapper.tsx` | App shell and entry points. `root.tsx` imports `src/theme/index.css` |
+| `components/` | Feature components; `components/ui/` holds UI primitives you own; `components/link` is the site-aware `Link`/`NavLink` |
+| `hooks/` | Includes `use-navigate` and `use-current-site-and-locale-ref` |
+| `providers/` | React context providers |
+| `lib/` | Domain folders (`auth/`, `cart/`, `checkout/`, `product/`, `order/`, ...), `api-clients.server.ts` (`createApiClients(context)`), `url.server.ts` (`buildUrlFromContext`), `page-designer/` (registry, loader), `decorators/`, `revalidation/` |
+| `middlewares/` | Server middlewares (`app-config`, `site-context`, `i18next`, `auth`, `basket`, `security-headers`, `logging`, ...). Ordering is in `src/server/middleware-registry.ts` |
+| `scapi/` | Generated and custom SCAPI clients (`@/scapi` barrel); see `storefront-next:sfnext-scapi` |
+| `extensions/` | Optional feature modules; `config.json` is the extension registry; per-extension `config.ts` / `server-config.ts` feed app config |
+| `targets/` | UI target (extension point) system |
+| `theme/` | `index.css` entry, `base.css`, `tailwind.css`, `tokens/`, `overrides/`, `animations.css`; see `storefront-next:sfnext-theming` |
+| `locales/` | One folder per language-region (`en-US`, `de-DE`, ...) with `translations.json`; see `storefront-next:sfnext-i18n` |
+| `types/config.ts` | `AppConfig` / `Config` types and the `getConfig` / `useConfig` type augmentation |
+| `analytics/`, `design-system/`, `test-utils/` | Tracking components, design-system docs stories, shared test helpers (`@/test-utils/config`, `context-provider`, `request-helpers`, ...) |
+
+## Where to look for each concern
+
+| Concern | Start here |
+| --- | --- |
+| Data loading, Suspense, state, images | `AGENTS.md` "Performance & Data Rules", `docs/README-DATA.md`, `README-SUSPENSE.md`, `README-STATE.md` |
+| All config options | `docs/README-CONFIG.md` (required/optional tables), `docs/README-CONFIG-OPTIONS.md` |
+| Multi-site, locale URLs, SEO routes | `docs/README-MULTI-SITE.md` |
+| Auth and cookies | `docs/README-AUTH.md` |
+| Page Designer | `docs/README-PAGE-DESIGNER.md` |
+| Upgrading | `docs/COMPATIBILITY.md`, `docs/migrations/` |
+
+## Page Designer metadata
+
+Component metadata is generated from decorators by `pnpm cartridge:generate` (also run by `pnpm build`) into `cartridges/app_storefrontnext_base/`, validated with `pnpm cartridge:validate`, and deployed to the B2C instance with `pnpm cartridge:deploy` (not part of `pnpm push`). See `storefront-next:sfnext-deployment` and `storefront-next:sfnext-page-designer`.
+
+## Adding UI primitives
+
+The project ships an in-project `sync-shadcn` skill (`.claude/skills/sync-shadcn`) and `scripts/upgrade-shadcn.js` for pulling updated shadcn primitives into `src/components/ui/` without losing local changes. Prefer that over a raw `npx shadcn add`.