@salesforce/b2c-cli 2.3.0 → 2.4.0

package/content/guidance/storefront-next/sfnext-page-designer/references/TROUBLESHOOTING.md

@@ -0,0 +1,35 @@
+# Troubleshooting Page Designer
+
+Start with the command loop: `pnpm cartridge:generate`, `pnpm cartridge:validate`, `pnpm cartridge:deploy`, then hard-refresh Business Manager. Most "it does not show up" problems are one of these not having run against the right instance and code version.
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Component absent from the Business Manager palette | Cartridge not regenerated or not deployed; deployed to a code version the site does not use; cartridge not on the site's path; metadata class not `export`ed | Export the class, run generate, validate and deploy, confirm the active code version, hard-refresh |
+| `cartridge:generate` or `validate` fails | Invalid `searching` combination; unknown attribute `type`; non-literal decorator argument; `enum` without `values` | Fix the decorator; generation parses decorators statically, so use literals |
+| Component is in the palette but renders nothing | `typeId` or `group` differs from the registry entry (`Content.hero` vs `Layout.hero`); registry stale; missing default export | Compare the decorator with `src/lib/page-designer/static-registry.ts`; restart `pnpm dev` or `pnpm build` |
+| Component not in `static-registry.ts` | File outside `src/components`, or `@Component` typeId is not a string literal | Move it or make it a literal; restart the dev server |
+| Page is empty on the storefront | No published page for that `pageId` or aspect assignment; wrong `pageId` in the loader; loader fetched a different aspect than the template | Check the page in Business Manager; `fetchPageWithComponentData` returns `null` on 404/API error |
+| Wrong template offered for products or categories | `supportedAspectTypes` disagrees with the loader's `aspectType` | Make them agree (`['pdp']`/`'pdp'`, `['plp']`/`'plp'`) |
+| Region shows nothing though merchants filled it | `<Region regionId>` not matching the `@RegionDefinition` id; region declared but never rendered | Cross-check ids in both directions |
+| `data` prop is `undefined` | Exported `loader` is an object (`{ server }`) not a function; registry lacks `{ loader: 'loader' }`; loader reads attributes from the wrong place | `export const loader = loaders.server`; read `componentData.data.<attr>`; regenerate the registry |
+| Loader data for an attribute is `undefined` | Attribute `id` differs from the field name; attribute not declared on the metadata class | Align `id` and field name |
+| Image attribute crashes or shows nothing | Treated as a string | It is an object: use `image.url` and `image.focalPoint` |
+| `markup` attribute shows literal tags | Rendered as text | Render as HTML only if the content is trusted |
+| Blank space then content pops in (layout shift) | `fallback` missing or height-less | Export a `fallback` that reserves the final height |
+| Suspense never resolves / whole region blank | `fallback` suspends (hooks, fetching); `critical` region given an unresolved page | Keep `fallback` synchronous; `await` the page for critical regions |
+| React warns about `designMetadata`/`component` props on a DOM element | Spreading `...rest` onto a DOM element | Destructure the injected props (`component`, `data`, `designMetadata`, `regionId`) out before spreading |
+| TypeScript error on `<Region>` | Mixed `page` and `component` props, or `fallbackElement` on a component-mode region | Use page mode at route level and component mode for nested regions, never both |
+| Nested region empty | Page mode used inside a component, or `component` prop missing | `<Region component={component} regionId="..." />` |
+| Design mode links navigate away | `PageDesignerInit` removed from `root.tsx` | Restore it |
+| Edits in Business Manager not reflected on the storefront | Editing a different instance than the storefront reads; cached page | Check the environment and site; see `storefront-next:sfnext-revalidation` for caching |
+
+## Debugging tips
+
+```bash
+pnpm cartridge:generate          # regenerate metadata; errors name the offending decorator
+pnpm cartridge:validate          # schema-check the generated JSON
+grep -n "Content.hero" src/lib/page-designer/static-registry.ts   # is the component registered?
+ls cartridges/app_storefrontnext_base/cartridge/experience/components   # is the metadata there?
+```
+
+Deploy problems (auth, WebDAV, code version) are not Page Designer problems; use `b2c-cli:b2c-code` and `b2c-cli:b2c-webdav`, and rerun with `--log-level trace`.

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

@@ -0,0 +1,102 @@
+---
+name: sfnext-performance
+description: >-
+  Keep a Storefront Next storefront fast and self-review changes for performance: LCP, CLS and TBT, Suspense placement and granularity, stable promise identity, lazy-loaded modals and drawers with useDeferredUnmount, useDeferredRender, Region critical, DynamicImage and image priority, font loading, resource hints (links.preconnect), bundle size checks (pnpm bundlesize, BUNDLES_SIZE_ANALYZE), Lighthouse CI, and the performance.metrics / Server-Timing flags. Use for "page is slow", "LCP regression", "skeleton flashes", "bundle too big", "review my diff for performance", "hydration mismatch or extra re-renders", "waterfall of fetches", or before merging feature work that adds loaders, fetchers, modals and drawers or images. Do not use for loader/action mechanics (use `storefront-next:sfnext-data-fetching`), revalidation policy (use `storefront-next:sfnext-revalidation`), or accessibility (use `storefront-next:sfnext-accessibility`).
+---
+
+# Storefront Next Performance
+
+Performance rules are part of `AGENTS.md` ("Performance & Data Rules") and detailed in `docs/README-PERFORMANCE.md`, `docs/README-SUSPENSE.md`, `docs/README-IMAGES.md` and `docs/README-PERFORMANCE-METRICS.md` in your project. This skill is the working summary plus a checklist to run on your own diff: [PERFORMANCE-REVIEW-CHECKLIST.md](references/PERFORMANCE-REVIEW-CHECKLIST.md).
+
+## Core rules
+
+1. Server-load data. Await only what SEO, LCP, layout or the HTTP status needs; return promises for the rest (see `storefront-next:sfnext-data-fetching`).
+2. One `<Suspense>` per async operation, with a skeleton that reserves the final size. No `fallback={null}` above the fold unless space is reserved.
+3. Promise identity must be stable across renders: compose in the loader, read from `loaderData`/props, never `Promise.all`/`.then`/`new Promise` in render, never `useMemo` around a promise. Escape hatches: `useState(() => ...)` pinning or `useRef` re-pinning.
+4. Every `use()`/`<Await>` consumer needs a `<Suspense>` ancestor; otherwise it blocks the first byte of the streamed shell.
+5. Heavy or hidden UI (modals, drawers, dialogs, rich editors) is `React.lazy` and mounted only while needed.
+6. Shape data in the loader, not in render.
+7. Hints and third-party scripts cost: preconnect only to origins used on every page; load scripts `async`/`defer`.
+
+## Lazy modals and drawers
+
+```tsx
+import { lazy, Suspense, useState } from 'react';
+import { useDeferredUnmount } from '@/hooks/use-deferred-unmount';
+
+const SizeGuide = lazy(() => import('@/components/size-guide').then((m) => ({ default: m.SizeGuide })));
+
+export function SizeGuideButton() {
+    const [open, setOpen] = useState(false);
+    const mounted = useDeferredUnmount(open); // stays mounted briefly after close for the exit animation
+    return (
+        <>
+            <button onClick={() => setOpen(true)}>Size guide</button>
+            {mounted && (
+                <Suspense fallback={null}>
+                    <SizeGuide open={open} onOpenChange={setOpen} />
+                </Suspense>
+            )}
+        </>
+    );
+}
+```
+
+Avoid a sticky "loaded" latch (a state that flips true on first open and never resets): fetchers inside the modal stay registered and re-run on every later revalidation. See `src/components/product-tile/quick-add-button.tsx`.
+
+## Deferred rendering
+
+`useDeferredRender(enabled, options)` (`@/hooks/use-deferred-render`) delays mounting a Suspense boundary until an idle frame; use it for large below-the-fold grids. `DeferredProductGrid` (`@/components/product-grid/deferred`) is the reference. `useDeferredRenderSequence(n)` fans out work one step per idle frame.
+
+## Page Designer
+
+Mark a region `<Region critical>` only when it is required for the initial HTML or is an LCP candidate, and `await` that page in the loader (omit a region fallback). Below-the-fold regions stay streamed. See `storefront-next:sfnext-page-designer`.
+
+## Images, fonts, hints
+
+- Images: use `DynamicImage` (`@/components/dynamic-image`). Props: `src`, `alt`, `widths`, `heights`, `imageProps`, `as`, `className`, `loading`, `priority`, `objectFit`. Give the LCP image `priority="high"` (React 19 preload) and never lazy-load it. Provide `widths` matching the layout, or wrap a group in `DynamicImageProvider` (`@/providers/dynamic-image`, `value={{ widths }}`). URL helpers are in `docs/README-IMAGES.md`.
+- Fonts: the template self-hosts `public/fonts/sen-variable.woff2`, preloads it in `src/root.tsx` `links`, and declares `@font-face` with `font-display: swap` in `src/theme/base.css`. Keep fonts same-origin, preload only the one above-the-fold face, and consider system fonts for secondary text.
+- Resource hints: configure `app.links.preconnect`, `prefetchDns`, `prefetch` in `config.server.ts` or via `PUBLIC__app__links__preconnect='["https://cdn.example.com"]'`. Default preconnects to the image host only.
+
+## Measure
+
+| Task | Command |
+|---|---|
+| Check bundle size limits (block CI) | `pnpm bundlesize` |
+| Interactive treemaps (`build/client-bundle-size.html`, `build/ssr-bundle-size.html`) | `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` |
+| Compare size runs | `pnpm bundlesize:compare` |
+| Lighthouse | `pnpm lighthouse:ci` |
+| Request timings | `performance.metrics` flags in `config.server.ts` |
+
+The limits live in the `bundlesize` block of `package.json`. If a legitimate change exceeds a limit, state the reason and raise it deliberately; do not use `manualChunks` to bucket components.
+
+`performance.metrics` (`serverPerformanceMetricsEnabled`, `serverTimingHeaderEnabled`, `clientPerformanceMetricsEnabled`) are all `false` in the shipped `config.server.ts`; `docs/README-PERFORMANCE-METRICS.md` lists two of them as defaulting to `true`, but the shipped config wins. Enable them only while debugging, because `serverTimingHeaderEnabled` adds a `Server-Timing` header and costs response time. Override via `PUBLIC__app__...` environment variables (`storefront-next:sfnext-configuration`).
+
+## Review workflow
+
+1. Run the checklist on your diff (fetch topology, Suspense, promise stability, hydration, revalidation scope, client transforms).
+2. `pnpm typecheck`, `pnpm lint`, `pnpm test`.
+3. `pnpm bundlesize` when you add dependencies or routes.
+4. Load the page with network throttling and CPU slowdown; confirm no layout shift when streamed sections resolve and that server HTML contains the LCP element.
+
+Impact rule of thumb: traffic of the page x number of instances on it x cost per instance. A fetch in a product tile is multiplied by every tile.
+
+## References
+
+- [PERFORMANCE-REVIEW-CHECKLIST.md](references/PERFORMANCE-REVIEW-CHECKLIST.md) - self-review checklist with rules, bad/good forms and exceptions
+- [SUSPENSE-AND-STREAMING.md](references/SUSPENSE-AND-STREAMING.md) - placement, granularity, promise stability recipes
+
+## Finding more
+
+`AGENTS.md` "Key Documentation" and `docs/README-PERFORMANCE.md`. `b2c docs search "storefront next performance"` or `docs_search` MCP tool.
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - loaders, streaming
+- `storefront-next:sfnext-revalidation` - cutting wasted loader re-runs
+- `storefront-next:sfnext-state-management` - render scope and stores
+- `storefront-next:sfnext-components` - component conventions
+- `storefront-next:sfnext-page-designer` - critical regions
+- `storefront-next:sfnext-quality-gates` - lint, typecheck, tests before merge
+- `storefront-next:sfnext-deployment` - bundle and MRT limits
+- `b2c-cli:b2c-mrt` - Managed Runtime logs and deploys

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

@@ -0,0 +1,147 @@
+---
+name: sfnext-project-setup
+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`).
+---
+
+# Storefront Next Project Setup
+
+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.
+
+**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`.
+
+## Prerequisites
+
+- 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)
+
+## Choose how to start
+
+| 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 |
+
+Never invent tenant/site IDs and never echo secrets from `env.txt`.
+
+## Create a project with the CLI
+
+```bash
+# 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
+
+# Non-interactive
+sfnext create-storefront -n my-storefront --vertical cosmetic -o ./projects
+sfnext create-storefront -n my-storefront --defaults
+```
+
+| 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 |
+
+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`.
+
+Then:
+
+```bash
+cd my-storefront
+pnpm install
+pnpm dev          # http://localhost:5173
+```
+
+## First run
+
+`.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=...
+PUBLIC__app__commerce__api__organizationId=...
+PUBLIC__app__commerce__api__shortCode=...
+```
+
+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.
+
+Before shipping, run through the pre-launch gate in `storefront-next:sfnext-deployment` (demo analytics IDs, staging image host, demo credentials).
+
+## Project layout (short form)
+
+```
+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/
+```
+
+See [PROJECT-STRUCTURE.md](references/PROJECT-STRUCTURE.md) for route families, key files, and where to go for each concern.
+
+## Scripts and CLI
+
+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.
+
+## Conventions worth knowing up front
+
+- 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
+
+| 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 |
+
+## Finding more
+
+- 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
+
+## Related Skills
+
+- `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

@@ -0,0 +1,61 @@
+# 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`.

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

@@ -0,0 +1,47 @@
+# Project Scripts
+
+Scripts in a Storefront Next project's `package.json`. Run with `pnpm <name>`; extra flags after the name are forwarded (`pnpm test --coverage`). If a script here is missing in your project, `grep -A60 '"scripts"' package.json` -- your project is the source of truth.
+
+## Develop and run
+
+| Script | Does |
+| --- | --- |
+| `dev` | Aggregates extension locales and config, then starts `sfnext dev` (Vite SSR, HMR) on http://localhost:5173. Runs with the `dev-data-store` Node condition |
+| `dev:debug` | Same with `--inspect` for a Node debugger |
+| `dev:log` | Dev with `SFCC_LOG_LEVEL=debug` |
+| `build` | `locales:aggregate-extensions`, `config:aggregate-extensions`, `cartridge:generate`, then `react-router build` -> `build/` |
+| `start` / `preview` | `sfnext preview`: serves the production build on http://localhost:3000 (builds if needed; `SFNEXT_DATA_STORE_UNAVAILABLE_MODE=fallback`) |
+
+## Deploy and operate
+
+| Script | Does |
+| --- | --- |
+| `push` | `sfnext push --project-directory .` -- uploads `build/` to Managed Runtime. Build first. Pass flags after it: `pnpm push -- --wait -e staging` |
+| `cartridge:generate` | `sfnext generate-cartridge` -- Page Designer metadata from decorators |
+| `cartridge:validate` | `sfnext validate-cartridge` -- validate metadata JSON against schemas |
+| `cartridge:deploy` | `sfnext deploy-cartridge` -- upload cartridges to the B2C instance (`-- --delete` wipes old files first) |
+| `config:inspect` | `sfnext config inspect` -- show which `config.server.ts` values are overridden by `.env` or MRT |
+| `config:push-env` | `b2c mrt env var push` -- sync `.env` variables to an MRT environment |
+| `config:aggregate-extensions`, `locales:aggregate-extensions` | Merge per-extension config / translations; run automatically by `dev`, `build`, `typecheck` |
+| `b2c` | Run the b2c CLI from the project (`pnpm b2c --help`) |
+
+## Quality
+
+| Script | Does |
+| --- | --- |
+| `typecheck` | Aggregate extension config, `react-router typegen`, then `tsc --noEmit` |
+| `lint` / `lint:fix` | OxLint (type-aware, zero warnings) plus Biome format check / fix |
+| `format` / `format:check` | Biome |
+| `lint:a11y`, `lint:css`, `a11y:scan-coverage` | Static accessibility lint, CSS/token lint, a11y scan coverage report |
+| `test` / `test:watch` | Vitest (`pnpm test src/components/foo` for one path) |
+| `storybook` | Storybook on http://localhost:6006 |
+| `storybook:build` | Static Storybook build |
+| `storybook:test` | Story tests: `--type=snapshot \| interaction \| a11y`, `--static`, `--update` |
+| `bundlesize` | Build with `BUNDLES_SIZE_CHECK=true` to enforce bundle limits |
+| `bundlesize:compare` | Compare bundle sizes between builds |
+| `lighthouse:ci` | Lighthouse CI run |
+| `extensions:list` | List extension points |
+| `e2e`, `e2e:turnstile`, `a11y` | Playwright suites in `e2e/` |
+| `chromatic:core` | Chromatic visual-test helper |
+
+Bundle treemap: `cross-env BUNDLES_SIZE_ANALYZE=true pnpm build` (writes `build/client-bundle-size.html`).

package/content/guidance/storefront-next/sfnext-project-setup/references/SFNEXT-CLI.md

@@ -0,0 +1,63 @@
+# `sfnext` CLI
+
+The `sfnext` binary comes from `@salesforce/storefront-next-dev`. Ways to run it:
+
+- `pnpm sfnext <command>` or a project script (`pnpm dev`, `pnpm push`, ...) inside the project
+- `b2c sfnext <command>` -- the b2c CLI installs the plugin on first use and, when run inside a project, prefers the project's local copy
+- `pnpm dlx @salesforce/storefront-next-dev <command>` for commands that run before a project exists (`create-storefront`)
+
+Most commands take `-d, --project-directory` (default: current directory). `.env` in the project directory is loaded automatically (not `.env.default`).
+
+## Project lifecycle
+
+| Command | Purpose |
+| --- | --- |
+| `create-storefront` | Create a project from a starter theme. Flags: `-n` name, `-V` starter theme (`fashion`, `cosmetic`, `foundations`, `footwear`, `furniture`, `luxury`), `-t` template URL/path, `-b` branch/tag, `-d` defaults, `-o` output dir |
+| `dev` | Vite dev server with SSR. `-p, --port` (default 5173) |
+| `preview` | Serve the production build, building if needed. `-p, --port` (default 3000) |
+| `create-bundle` | Create an MRT bundle in `.bundle/` without pushing. `-b` build dir, `-o` output dir, `-m` message, `-s` project slug |
+| `push` | Upload the build to Managed Runtime. See below |
+
+## Managed Runtime push
+
+```bash
+pnpm build && pnpm push -- -m "Release notes" -e staging --wait
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `-m, --message` | Bundle message (default: git branch:commit) |
+| `-w, --wait` | Wait for the deployment to finish; requires a target environment |
+| `-b, --build-directory` | Build dir (default: auto-detected `build/`) |
+| `-p, --project` | MRT project slug (env `MRT_PROJECT`, then `SFCC_MRT_PROJECT`, then dw.json `mrtProject`) |
+| `-e, --environment` | Target environment (env `MRT_TARGET`). Without one the bundle is uploaded but not deployed |
+| `--api-key`, `--credentials-file`, `--cloud-origin` | MRT credentials (env `MRT_API_KEY`, `MRT_CREDENTIALS_FILE`, `MRT_CLOUD_ORIGIN`; or `~/.mobify`) |
+
+`push` does not build; it fails if the build directory is missing.
+
+## Cartridges (Page Designer metadata)
+
+| Command | Purpose |
+| --- | --- |
+| `generate-cartridge` | Generate component metadata from decorators into `cartridges/app_storefrontnext_base` |
+| `validate-cartridge` | Validate the generated JSON |
+| `deploy-cartridge` | Upload cartridges to a B2C instance. Instance settings come from flags, env, or `dw.json`. Flags: `-s, --server`, `-v, --code-version`, `-r, --reload` (re-activate), `--delete` (remove old files first), `-c` include / `-x` exclude cartridges |
+| `setup-base-cartridge` | Register the SLAS scopes the base cartridge needs: `--slas-client-id <id>` (needs short code and tenant ID from flags/env/dw.json) |
+
+Deploying cartridges needs WebDAV credentials; without `--code-version` it also needs OAuth credentials to discover the active code version.
+
+## Configuration and extensions
+
+| Command | Purpose |
+| --- | --- |
+| `config inspect` | Show which `config.server.ts` values are overridden by `.env` or MRT (`--project`, `--environment` to include MRT values) |
+| `config aggregate-extensions`, `locales aggregate-extensions` | Merge extension config / translations (run by `dev`, `build`, `typecheck`) |
+| `extensions list` | List installed extensions |
+| `extensions install -e <SFDC_EXT_...>` | Install an extension |
+| `extensions remove -e <A,B>` | Remove extensions (`--yes` to also remove dependents) |
+| `extensions create -n "<Name>" -d "<desc>"` | Scaffold a new extension (`-p` target project dir) |
+| `create-instructions` | Generate install/uninstall instruction files for an extension you author |
+
+## SCAPI clients
+
+`sfnext scapi available | add | list | remove` manage typed SCAPI clients, including custom APIs. See `storefront-next:sfnext-scapi`.