@salesforce/b2c-cli 2.3.0 → 2.4.0

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

@@ -0,0 +1,103 @@
+---
+name: sfnext-accessibility
+description: >-
+  Build and fix accessible UI in a Storefront Next storefront (WCAG 2.1 AA): jsx-a11y lint findings, missing accessible names and labels, form error association, dialog focus management, aria-live status messages, keyboard behavior, color contrast, and verifying fixes with Storybook a11y/play() tests and the e2e axe scan with its baseline. Use for "accessibility", "a11y", "WCAG", "screen reader", "aria-label", "focus trap", "axe violation", pnpm lint:a11y, pnpm a11y, a11y-baseline.json, skip-a11y, STORYBOOK_A11Y_TEST_MODE, or an accessibility audit finding to fix. Do not use for general lint/typecheck gates (use `storefront-next:sfnext-quality-gates`), writing non-accessibility tests (use `storefront-next:sfnext-testing`), or color/token design (use `storefront-next:sfnext-theming`).
+---
+
+# Storefront Next Accessibility
+
+Target: WCAG 2.1 AA. Accessibility is checked at three levels, cheapest first:
+
+| Level | Tool | Catches |
+|-------|------|---------|
+| Lint | OxLint `jsx-a11y` (`pnpm lint`, `pnpm lint:a11y`) | Missing alt/labels, invalid ARIA, non-interactive handlers, ambiguous link text |
+| Component | Storybook a11y addon (axe) and `play()` assertions | Contrast and name/role issues in a rendered state; focus, live regions, dialog behavior |
+| Page | e2e axe scan (`pnpm a11y`) against `e2e/a11y-baseline.json` | Page composition, layout, mobile vs desktop |
+
+Some things no scanner finds: focus order, meaning carried by color alone, 200%/400% zoom reflow, and what a screen reader actually announces. Those need keyboard testing, a story `play()` assertion of the DOM facts behind them, or a human with assistive technology.
+
+## Author accessibly by default
+
+1. Use the project's building blocks; they are already accessible in the general case:
+   - Radix-based primitives in `src/components/ui/` (dialog, dropdown-menu, sheet, tooltip, ...).
+   - `FormLabel`/`FormControl`/`FormMessage` from `@/components/ui/form` and the wrappers in `src/components/form-fields/` (they wire `aria-describedby` and invalid state from form context).
+   - `src/components/product-image` and `src/components/dynamic-image` (alt text), `src/components/radio-card` (grouped options), `src/components/skip-link.tsx` (first focusable element, targets `#main-content`), `src/components/announcement-banner`.
+2. Icon-only controls need a translated accessible name: `<Button aria-label={t('close')}>`. Decorative icons get `aria-hidden="true"` and must not be focusable.
+3. Every input needs a real label; errors must be programmatically associated and announced (form-field wrappers do this).
+4. Use semantic elements first (`button`, `a`, `ul`, `h1..h6`); add ARIA only to fill gaps. Keep one `h1` per page and do not skip levels.
+5. Status changes that happen without navigation (cart updates, promo applied, errors) need an `aria-live` region (`role="status"` or `role="alert"`); the message must be rendered into an existing live region or the region must exist before content changes.
+6. Dialogs and drawers: focus moves in on open, is trapped, returns to the trigger on close, `Escape` closes. Use the Radix dialog primitives rather than hand-rolling.
+7. Respect `prefers-reduced-motion` (see `src/components/fade-through-image` and `product-zoom-modal` for the pattern).
+8. Keep visible focus styles; do not remove outlines without a replacement from the theme tokens.
+9. Do not "fix" `role="list"` on a `ul`: it is deliberate (Tailwind's `list-style: none` removes list semantics in Safari + VoiceOver), and the lint config allows it.
+
+## Fix the right layer
+
+Before editing a shared primitive, check the call site.
+
+- Call-site fix (most common): the primitive is correct but the caller passed no `aria-label`, a meaningless `alt`, or bypassed `FormLabel`. Fix the caller.
+- Primitive fix: the shared component itself emits inaccessible markup. One change cascades to every usage, so keep it small and re-run the component's stories and snapshots.
+- Many findings citing one primitive usually means one call-site pattern to correct, not a broken primitive.
+
+## Reproduce, fix, confirm
+
+Do not call something fixed from reading code. Capture a failing signal first, then the same check passing afterwards.
+
+1. Name the state: default, form-error, modal-open, out-of-stock, focus-after-action, zoomed. Many violations only exist after interaction, which is why default-page scans come back clean.
+2. Reproduce:
+   - Lint rule: `pnpm lint:a11y`.
+   - Rendered axe rule: run the story with `STORYBOOK_A11Y_TEST_MODE=error` via `pnpm storybook:test --type=a11y`, or add the scenario to the e2e a11y specs.
+   - Focus/label/live-region issues: write a `play()` assertion (next section) and watch it fail.
+3. Fix at the right layer.
+4. Re-run the same check; also run the component's snapshot (`pnpm storybook:test --type=snapshot`, `--update` only after reviewing the diff) and `pnpm lint`.
+5. Never add a suppression (disabled axe rule, `oxlint-disable`, `aria-hidden`) just to turn a check green. A suppression is acceptable only when it targets a node you do not control and the reason is written next to it.
+
+## Storybook: a11y addon and play() assertions
+
+- Default addon mode is `todo` (violations are shown, not failing). `pnpm storybook:test --type=a11y` runs in error mode, so violations fail. `STORYBOOK_DISABLE_A11Y=true` turns it off.
+- Opt one story file into strict mode: spread `{ a11y: { test: 'error' } }` into `parameters` (see `src/components/checkout/storybook/checkout-strict-a11y-parameters.ts`).
+- Tag `skip-a11y` excludes a story from a11y runs. Use it rarely and comment why.
+- Assert accessible outcomes, not CSS classes:
+
+```tsx
+play: async ({ canvasElement }) => {
+    await waitForStorybookReady(canvasElement);
+    const body = within(canvasElement.ownerDocument.body); // Radix portals render into <body>
+    const dialog = body.getByRole('dialog');
+    await expect(dialog).toBeInTheDocument();
+    await expect(body.getAllByRole('textbox')[0]).toHaveFocus();
+    await expect(body.getByRole('textbox', { name: /email/i })).toBeInTheDocument(); // label association
+    await expect(body.getByRole('status')).toHaveTextContent(/saved/i);               // live region populated
+},
+```
+
+A working reference is `src/components/login/stories/otp-modal.stories.tsx`. Imports: `expect, within, userEvent` from `storybook/test`; `waitForStorybookReady` from `@storybook/test-utils`. Tag the story `interaction` so it runs under `--type=interaction`.
+
+## e2e axe scan and baseline
+
+`pnpm a11y` runs axe (WCAG 2.1 A/AA tags) over key pages at desktop and mobile viewports and compares with `e2e/a11y-baseline.json`. CI fails when critical or serious violations increase or a new critical/serious rule appears; moderate and minor regressions are logged but do not block.
+
+```bash
+pnpm a11y                   # scan and compare with baseline
+pnpm --dir e2e a11y:report  # or from e2e/: markdown + HTML report of violations
+pnpm --dir e2e a11y:update-baseline   # after fixing: ratchet the baseline down, review the diff, commit
+pnpm a11y:scan-coverage     # checks that every page route is scanned or explicitly allowlisted
+```
+
+- Never hand-edit the baseline; regenerate it.
+- New pages: add a `Scenario` in `e2e/src/specs/core/a11y/` (public, account or orders spec), then run `a11y:update-baseline`. Details: `e2e/docs/a11y.md`.
+- The dev server must be running (`pnpm dev`) or use `--mode=local` as described in `storefront-next:sfnext-testing`.
+
+## Translated text
+
+`jsx-a11y/anchor-ambiguous-text` only sees literal JSX text. A link whose text comes from `t('...')` is never checked, so review link and label copy in `src/locales/*/translations.json` for "click here"/"read more" style text, in every locale you ship. See `storefront-next:sfnext-i18n`.
+
+More checklists (states, keyboard, pages to spot check): [references/checklist.md](references/checklist.md).
+
+## Related Skills
+
+- `storefront-next:sfnext-quality-gates` - lint config and pre-PR checklist
+- `storefront-next:sfnext-testing` - story, unit and e2e test mechanics
+- `storefront-next:sfnext-components` - component and form-field conventions
+- `storefront-next:sfnext-theming` - color tokens and contrast
+- `storefront-next:sfnext-i18n` - translated labels and link text

package/content/guidance/storefront-next/sfnext-accessibility/references/checklist.md

@@ -0,0 +1,64 @@
+# Accessibility checklists
+
+## Classify a finding
+
+| Question | If yes |
+|----------|--------|
+| Is there a DOM fact a scanner or assertion can check (missing name, unlabeled input, empty live region, `aria-hidden` on focusable, duplicate id, empty heading, contrast)? | Automatable. Reproduce with axe (story a11y run or e2e scan) and fix. |
+| Is it about focus landing in the right place, roving arrow keys, trap/return, live region populated? | Has a DOM correlate. Assert it in a story `play()`. |
+| Is it reading order, meaning conveyed by color alone, zoom/reflow at 200% to 400%, or exactly what VoiceOver/NVDA speaks? | Manual. Test with the keyboard, browser zoom and a screen reader; record the result. Do not close it as "cannot reproduce" because a scanner is clean. |
+
+For "status message is not announced": if a live region should exist in the DOM, it is assertable; if the claim is purely about speech output, test with assistive technology.
+
+## States to exercise
+
+Scan or assert in each relevant state, not only the settled default:
+
+- default
+- form-error (submit empty or invalid)
+- modal, drawer or menu open
+- out-of-stock / unavailable variant
+- after an action (focus after add-to-cart, after closing a dialog)
+- zoomed to 400% / narrow viewport
+- mobile and desktop viewports
+- reduced motion enabled
+
+Prefer states that do not depend on live catalog data for repeatable checks; data-dependent states (out-of-stock, specific content) can differ between local and CI backends.
+
+## Keyboard pass (per page or component)
+
+- Tab order follows the visual order; nothing focusable is hidden; a visible focus indicator is always present.
+- All controls operable with Enter/Space; menus, tabs, carousels and swatch groups support arrow keys as expected.
+- `Escape` closes dialogs and popovers; focus returns to the trigger.
+- No keyboard trap outside intentional modal containment.
+- The skip link is the first Tab stop and moves focus to `#main-content`.
+
+## Forms
+
+- Each field has a visible label associated through `FormLabel` or `htmlFor`.
+- Error text is associated (`aria-describedby`) and the field is `aria-invalid`; on a failed submit, move focus to the first invalid field or an error summary (verify the behavior of the form you are editing).
+- Required state is conveyed in text, not color alone.
+- Autocomplete attributes are set for address, email and payment fields.
+
+## Images and media
+
+- Product and content images use `ProductImage`/`DynamicImage` with meaningful alt text; decorative images use empty alt.
+- Icon-only buttons have translated accessible names.
+- Carousels: labelled region, pause/controls reachable by keyboard, reduced motion respected.
+
+## Content and structure
+
+- One `h1` per page; headings in order.
+- Landmarks (`header`, `nav`, `main`, `footer`) present once each with labels where repeated.
+- Link text makes sense out of context, in every locale.
+- Lists use list markup; keep `role="list"` on styled `ul` (Safari + VoiceOver).
+
+## Where to run what
+
+| Goal | Command |
+|------|---------|
+| Lint-level a11y only | `pnpm lint:a11y` |
+| Rendered component violations | `pnpm storybook:test --type=a11y` |
+| Focus/aria behavior | `pnpm storybook:test --type=interaction` |
+| Full-page scan vs baseline | `pnpm a11y` |
+| Report with HTML snippets for tickets | `pnpm --dir e2e a11y:report` |

package/content/guidance/storefront-next/sfnext-analytics-consent/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: sfnext-analytics-consent
+description: >-
+  Storefront Next analytics: engagement adapters (Einstein, Active Data, Data 360), adding a custom adapter, tracking consent gating, PageViewTracker, useAnalytics events, and first-touch attribution (dw_attribution). Use when configuring engagement.adapters in config.server.ts, writing an adapter with hasConsent, registering it in initializeEngagementAdapters, wiring the consent banner (trackingConsent, consentCategories, dw_dnt), firing trackViewProduct/trackCartItemAdd events, debugging why no analytics events are sent, or passing campaign attribution to orders. Do not use for general config loading or env vars (use `storefront-next:sfnext-configuration`), CSP/script allowlisting of third-party tags (use `storefront-next:sfnext-security`), or SEO meta/JSON-LD (use `storefront-next:sfnext-seo`).
+---
+
+# Storefront Next Analytics and Consent
+
+Events flow: component -> `useAnalytics()` -> event mediator (`@salesforce/storefront-next-runtime/events`) -> each registered engagement adapter. Every adapter checks shopper consent before sending. Read `docs/README-ADAPTER-PATTERN-GUIDE.md` and `docs/README-CONSENT-TRACKING.md` in your project for the full guides; where they disagree with the code, trust the code (paths below were verified).
+
+## Where things live
+
+| Concern | Location |
+|---|---|
+| Adapter config | `engagement.adapters.*` in `config.server.ts` |
+| Adapter types, store, `hasConsent`, `buildConsentPreferences` | `@/lib/adapters` (`src/lib/adapters/engagement/`) |
+| Registration of built-in adapters | `src/lib/adapters/engagement/register.ts` (`initializeEngagementAdapters`) |
+| Built-in adapters | `einstein.ts`, `active-data.ts`, `data360.ts` in the same folder |
+| Page view tracking | `src/analytics/page-view-tracker.tsx` (`PageViewTracker`, mounted in `src/root.tsx`) |
+| Event hooks | `@/hooks/use-analytics`, `@/hooks/use-tracking-consent` |
+| Attribution | `src/lib/attribution.ts`, `@/hooks/use-attribution`, `src/middlewares/attribution-forwarding.server.ts` |
+
+## Configure built-in adapters
+
+```ts
+// config.server.ts
+engagement: {
+  adapters: {
+    einstein: { enabled: true, consentCategory: 'analytics', host, einsteinId, realm, siteId, isProduction: false,
+                eventToggles: { view_page: true, view_product: true /* ... */ } },
+    data360:  { enabled: true, consentCategory: 'analytics', appSourceId, tenantId, siteId, webStoreId: 'sfnext', eventToggles: { /* ... */ } },
+    activeData: { enabled: true, /* see config.server.ts */ },
+  },
+  analytics: {
+    trackingConsent: { enabled: true, defaultTrackingConsent: TrackingConsent.Declined,
+                       consentCategories: ['necessary', 'analytics', 'marketing', 'personalization'] },
+    pageViewsBlocklist: [/* paths that must not emit view_page */],
+  },
+}
+```
+
+- The shipped IDs (einsteinId, realm, tenantId, ...) are sample values. Replace them with your own before go-live, or set `enabled: false`.
+- An adapter with `consentCategory: 'analytics'` sends nothing unless `'analytics'` is in `trackingConsent.consentCategories`.
+- `eventToggles` turns individual event types on or off per adapter. Data 360 ships only view/impression events enabled.
+- The `einstein` and `data360` adapter blocks, and `activeData.enabled` / `activeData.eventToggles`, are protected config paths and cannot be overridden with `PUBLIC__` env vars; edit `config.server.ts` and rebuild. Other keys follow the `PUBLIC__app__engagement__...` pattern (see `storefront-next:sfnext-configuration`).
+
+## Fire events
+
+```tsx
+import { useAnalytics } from '@/hooks/use-analytics';
+
+const { trackViewProduct, trackCartItemAdd } = useAnalytics();
+```
+
+`useAnalytics` returns `trackViewPage`, `trackViewProduct`, `trackCartItemAdd`, `trackCheckoutStart`, `trackCheckoutStep`, `trackViewSearch`, `trackViewCategory`, `trackClickProductIn{Category,Search,Recommender}`, `trackViewRecommender`, search-suggestion and wishlist trackers. On the server these are no-ops, so call them from effects or event handlers. Check the hook source for exact argument shapes before calling.
+
+## Consent
+
+Consent is read from the auth session (`dw_dnt` cookie) by `useTrackingConsent()`, converted to a `ConsentPreferences` array by `buildConsentPreferences(trackingConsent, consentCategories, isTrackingConsentEnabled)`, and passed to every adapter. While consent is undetermined or declined, no events are sent.
+
+```tsx
+import { useTrackingConsent } from '@/hooks/use-tracking-consent';
+import { TrackingConsent } from '@/types/tracking-consent';
+
+const { shouldShowBanner, setTrackingConsent } = useTrackingConsent();
+setTrackingConsent(TrackingConsent.Accepted);
+```
+
+Granular per-category consent (for example from a CMP) means replacing the binary banner logic that feeds `buildConsentPreferences`; adapters already gate per `consentCategory`.
+
+## Add a custom adapter
+
+See [references/CUSTOM-ADAPTER.md](references/CUSTOM-ADAPTER.md). In short: implement `createMyAdapter(config): EngagementAdapter` using `hasConsent`, register it with `addAdapter('my-adapter', ...)` inside `initializeEngagementAdapters`, and add `engagement.adapters.myAdapter` config (the config type allows extra keys).
+
+## Attribution
+
+A first-touch `dw_attribution` cookie captures allow-listed landing/referrer params (see `LANDING_PARAM_ALLOWLIST` in `src/lib/attribution.ts`). `attributionForwardingMiddleware` forwards it on order creation. Add a parameter by extending the allowlist; cookie size is capped (`MAX_ATTRIBUTION_COOKIE_VALUE_LENGTH`).
+
+## Troubleshooting
+
+- No events at all: consent not accepted, `'analytics'` missing from `consentCategories`, adapter `enabled: false`, or the path is in `pageViewsBlocklist`. Startup logs a warning when consent categories are empty.
+- Custom adapter never fires: it was not registered in `initializeEngagementAdapters`, or `eventToggles[eventType]` is falsy.
+- Third-party script or beacon blocked: CSP, see `storefront-next:sfnext-security`.
+
+## Related Skills
+
+- `storefront-next:sfnext-configuration` - config.server.ts, env overrides
+- `storefront-next:sfnext-security` - CSP for analytics endpoints
+- `storefront-next:sfnext-authentication` - session/cookies behind `dw_dnt`
+- `storefront-next:sfnext-testing` - testing adapters and hooks
+- `storefront-next:sfnext-seo` - page metadata and structured data

package/content/guidance/storefront-next/sfnext-analytics-consent/references/CUSTOM-ADAPTER.md

@@ -0,0 +1,49 @@
+# Writing a custom engagement adapter
+
+Verify the types in `src/lib/adapters/engagement/types.ts` in your project first.
+
+## 1. Implement
+
+```ts
+// src/lib/adapters/engagement/my-adapter.ts
+import { hasConsent, type EngagementAdapter, type EngagementAdapterConfig } from '@/lib/adapters';
+import type { AnalyticsEvent, ConsentPreferences, EventSiteInfo } from '@salesforce/storefront-next-runtime/events';
+
+export function createMyAdapter(config: EngagementAdapterConfig): EngagementAdapter {
+  return {
+    name: 'my-adapter',
+    sendEvent: async (event: AnalyticsEvent, siteInfo?: EventSiteInfo, consentPreferences?: ConsentPreferences) => {
+      if (!hasConsent(config.consentCategory, consentPreferences)) return;
+      if (!config.eventToggles[event.eventType]) return;
+      navigator.sendBeacon('https://example.com/collect', JSON.stringify({ event, siteInfo }));
+    },
+  };
+}
+```
+
+`hasConsent(category, prefs)` is in `src/lib/adapters/engagement/utils.ts`; read it for the behavior when `category` is undefined.
+
+## 2. Register
+
+In `src/lib/adapters/engagement/register.ts`, inside `initializeEngagementAdapters(appConfig)`:
+
+```ts
+const mine = appConfig?.engagement?.adapters?.myAdapter;
+if (mine?.enabled) {
+  addAdapter('my-adapter', createMyAdapter({ consentCategory: mine.consentCategory, eventToggles: mine.eventToggles || {}, ...mine }));
+}
+```
+
+Follow the try/catch and logger pattern used for the built-in adapters.
+
+## 3. Configure
+
+Add `engagement.adapters.myAdapter: { enabled: true, consentCategory: 'marketing', eventToggles: { view_page: true } }` in `config.server.ts`. Add `'marketing'` (or your category) to `trackingConsent.consentCategories`.
+
+## 4. Allow the endpoint in CSP
+
+Beacons to a new host need `connect-src` (and script hosts need `script-src`). See `storefront-next:sfnext-security`.
+
+## 5. Test
+
+Unit-test the adapter with and without consent (see the `*.test.ts` files beside the built-in adapters for the pattern).

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

@@ -0,0 +1,127 @@
+---
+name: sfnext-authentication
+description: >-
+  Work with Storefront Next's server-only authentication and session architecture (SLAS guest/registered tokens, httpOnly cookies, auth.server.ts middleware). Use for getAuth, useAuth, updateAuth, destroyAuth, protecting account routes, login/logout actions, guest-to-registered basket/wishlist merge, "session expired" redirects, 401 recovery loops, cc-at/cc-nx/usid/dwsid cookies, cookie names or expiry, passwordless login, social login, OTP email verification, passkeys, guest order lookup, or refresh-token lifetime settings. Do not use for Turnstile, CSP headers or cookie-domain config (use `storefront-next:sfnext-security`), calling SCAPI clients (use `storefront-next:sfnext-scapi`), or sharing sessions with SFRA (use `storefront-next:sfnext-hybrid-storefronts`).
+---
+
+# Storefront Next Authentication
+
+Authentication is **server-only**. One middleware (`src/middlewares/auth.server.ts`, registered in the `middleware` array of `src/root.tsx`) runs on every request: it reads cookies, validates or refreshes the SLAS access token, performs a guest login when nothing usable exists, and writes `Set-Cookie`. Tokens never reach the browser. Components only see a small non-sensitive slice through `useAuth()`.
+
+Read `docs/README-AUTH.md` in your project for the full reference; this skill is the task-oriented summary. Route modules use server `loader`/`action` only, never `clientLoader`/`clientAction`.
+
+## Request flow
+
+1. Valid access token (JWT `exp` in the future): use it.
+2. Expired access token with a refresh token: refresh, rewrite `cc-at`.
+3. No tokens: guest login.
+4. Registered shopper whose refresh fails: 307 to `/login?returnUrl=<path>&error=session_expired` (site/locale prefix included) and a fresh guest session is created in parallel. Guests are silently re-issued a guest session.
+5. A SCAPI call returning 401 throws `AuthTokenInvalidError`; the middleware clears state, re-runs login/refresh and 307-redirects to the same URL. The short-lived `cc-auth-recover` cookie (30 s) prevents loops.
+
+User type comes from the access-token JWT (registered tokens carry an `rcid` claim), not from which cookie exists. `customerId` is **not** a cookie; it is derived per request from the JWT.
+
+## Read auth on the server
+
+```typescript
+import { getAuth } from '@/middlewares/auth.server';
+import type { LoaderFunctionArgs } from 'react-router';
+
+export async function loader({ context }: LoaderFunctionArgs) {
+    const auth = getAuth(context); // full SessionData, server only
+    const isRegistered = auth.userType === 'registered';
+    return { isRegistered };       // never return auth.accessToken / refreshToken
+}
+```
+
+## Read auth in components
+
+```tsx
+import { useAuth } from '@/providers/auth';
+
+function AccountBadge() {
+    const auth = useAuth(); // PublicSessionData | undefined
+    return auth?.userType === 'registered' ? <span>Welcome back</span> : <SignInLink />;
+}
+```
+
+`PublicSessionData` is exactly `customerId`, `userType`, `usid`, `encUserId`, `trackingConsent`. The root loader derives it with `getPublicSessionData` (from `@/middlewares/auth.utils`) and passes it to `AuthProvider`; there is no client `getAuth`.
+
+## Protect a route
+
+Branch inside the server loader. Prefer the existing account layout (`src/routes/_app.account.tsx`) for anything under `/account` instead of adding per-route checks.
+
+```typescript
+import { redirect } from 'react-router';
+import { getAuth } from '@/middlewares/auth.server';
+import { buildUrlFromContext } from '@/lib/url.server';
+import { routes } from '@/route-paths';
+
+export async function loader({ context }: LoaderFunctionArgs) {
+    if (getAuth(context).userType !== 'registered') {
+        throw redirect(buildUrlFromContext(routes.login, context)); // keeps site/locale prefix
+    }
+    // ...
+}
+```
+
+## Log in and out
+
+Never write auth cookies yourself. Use the helpers exported from `@/middlewares/auth.server`:
+
+```typescript
+import { loginRegisteredUser, updateAuth } from '@/middlewares/auth.server';
+
+export async function action({ request, context }: ActionFunctionArgs) {
+    const form = await request.formData();
+    const tokens = await loginRegisteredUser(context, String(form.get('email')), String(form.get('password')));
+    updateAuth(context, tokens);            // re-derives userType/customerId/usid, swaps cc-nx-g for cc-nx
+    return redirect('/account');
+}
+```
+
+`updateAuth` accepts a SLAS token response or an updater function (`updateAuth(context, (cur) => ({ ...cur, codeVerifier }))`). Logout: `destroyAuth(context)` clears every auth cookie on the response; the shipped `src/routes/_empty.logout.ts` also calls `clients.auth.logout` and `destroyBasket`. Prefer `src/lib/api/auth/standard-login.server.ts` and `social-login.server.ts` over hand-rolled flows: they already handle the merge below.
+
+Other exported helpers: `loginGuestUser`, `refreshAccessToken`, `authorizePasswordless`, `getPasswordLessAccessToken`, `getPasswordResetToken`, `resetPasswordWithToken`, `requestOtp`, `verifyOtp`, `flashAuth(context, message)` (clear session plus an error message), `clearInvalidSessionAndRestoreGuest(context)` (deleted customer or corrupted session).
+
+## Guest to registered merge
+
+`customerId` changes from the guest `gcid` to the registered `rcid` at the token swap, and SCAPI rejects the guest id under the registered token. So: snapshot guest-owned data (wishlist) **before** the swap, then `mergeBasket` and `mergeWishlist` **after**. `src/lib/api/auth/social-login.server.ts` is the reference implementation. `dw_dnt` tracking consent is preserved across the swap.
+
+## Common SCAPI calls for account data
+
+These are real operations: `clients.shopperCustomers.getCustomerOrders`, `getCustomerProductLists` (wishlists), `getCustomer`. Use the existing helpers (`src/lib/api/order.server.ts`, `wishlist.server.ts`, `customer.server.ts`) rather than calling clients directly. Client setup and the `@/lib/api-clients.server` import are covered in `storefront-next:sfnext-scapi`.
+
+## Configuration
+
+| Setting | Where |
+|---|---|
+| Refresh-token lifetime | `PUBLIC_COMMERCE_API_GUEST_REFRESH_TOKEN_EXPIRY_SECONDS` (max 30 days), `PUBLIC_COMMERCE_API_REGISTERED_REFRESH_TOKEN_EXPIRY_SECONDS` (max 90 days) |
+| Feature flags | `features.passwordlessLogin`, `features.passkey`, `features.socialLogin`, `features.otpRequest`, `auth.otpLength` in `config.server.ts` |
+| Private SLAS client | `commerce.api.privateKeyEnabled` (required for passwordless / OTP) |
+| Cookie domain | `app.cookies.domain` (see `storefront-next:sfnext-security`) |
+
+`secure` on cookies is only set on deployed (HTTPS) environments; local `pnpm dev` over `http://localhost` writes non-secure cookies so Safari keeps them.
+
+## Pitfalls
+
+- Reading tokens with `document.cookie`: impossible by design (httpOnly). Use `useAuth()` or loader data.
+- Returning `getAuth(context)` from a loader leaks tokens into the page. Return only derived values.
+- Refreshing tokens manually in routes: the middleware already does it.
+- Logging `accessToken` or `refreshToken`: never.
+- Changing the cookie domain on a live site leaves old host-only cookies shadowing new ones; roll out in a quiet window.
+- A loop of redirects to `/login?error=session_expired` usually means refresh tokens are being rejected (SLAS client config, or cookie domain mismatch between hosts).
+
+## References
+
+- [COOKIES.md](references/COOKIES.md): full cookie inventory, namespacing, expiry, hints.
+- [LOGIN-FLOWS.md](references/LOGIN-FLOWS.md): passwordless, social, OTP, passkeys, password reset, guest order lookup, email cartridge prerequisites.
+- In your project: `docs/README-AUTH.md`, `docs/README-EMAIL-VERIFICATION.md`, `docs/README-GUEST-ORDER-LOOKUP.md`, `docs/README-EMAIL-CARTRIDGE.md`.
+
+## Related Skills
+
+- `storefront-next:sfnext-security` - Turnstile bot protection, CSP for social providers, cookie domain
+- `storefront-next:sfnext-scapi` - SCAPI clients and custom APIs
+- `storefront-next:sfnext-hybrid-storefronts` - shared `dwsid` session bridge with SFRA
+- `storefront-next:sfnext-analytics-consent` - `dw_dnt` tracking consent
+- `storefront-next:sfnext-configuration` - `config.server.ts` and `PUBLIC__` overrides
+- `b2c-cli:b2c-slas` - manage SLAS clients and scopes

package/content/guidance/storefront-next/sfnext-authentication/references/COOKIES.md

@@ -0,0 +1,39 @@
+# Storefront Next Auth Cookies
+
+Source of truth in your project: `docs/README-AUTH.md` (Cookie Architecture) and the constants in `src/middlewares/auth.utils.ts`. Cookie serialization lives in `src/lib/cookie-utils.server.ts` (`getCookieConfig`, `createCookie`).
+
+All auth cookies are `HttpOnly`, so client JavaScript cannot read them. The only exception is `dw_dnt` (the consent banner reads it). The browser still sends every cookie on each request, which is what lets the server middleware and a hybrid B2C Commerce (SFRA) storefront read them.
+
+| Cookie | Purpose | User type | Lifetime | Notes |
+|---|---|---|---|---|
+| `cc-nx-g` | Guest refresh token | Guest | Guest refresh expiry (max 30 days) | Mutually exclusive with `cc-nx` |
+| `cc-nx` | Registered refresh token | Registered | Registered refresh expiry (max 90 days) | Written on login; deletes `cc-nx-g` |
+| `cc-at` | Access token | Both | JWT `exp` | Refreshed by middleware |
+| `usid` | SLAS user session id (JWT `sub`) | Both | Refresh expiry, else access expiry | Keep httpOnly; never expose to JS |
+| `enc_user_id` | Encoded user id | Registered | Refresh expiry | Needed for some SLAS calls |
+| `idp_access_token` | Social-login IDP access token | Both | Access expiry | Social login only |
+| `id_token` | OIDC ID token | Both | Access expiry | |
+| `idp_refresh_token` | Social-login IDP refresh token | Both | Refresh expiry | |
+| `dw_dnt` | Tracking consent (value is the `TrackingConsent` enum) | Both | Session | Not httpOnly, not site-namespaced; cookie is the source of truth |
+| `dwsid` | B2C Commerce session id (hybrid bridge) | Both | Session | Not site-namespaced; taken from the SLAS `Set-Cookie` header |
+| `cc-cv` | PKCE code verifier | Both | 5 minutes | Social login flow |
+| `cc-auth-recover` | 401 / session-expiry redirect loop guard | Both | 30 seconds | Set by middleware, cleared on follow-up request |
+
+Related non-auth cookies you may see: `cc-tv_<siteId>` (Turnstile attestation, 30 min, see `storefront-next:sfnext-security`), `glo_order_*` / `glo_cd_*` (guest order lookup), site-context cookies for site, locale and currency, a JS-readable `__sfdc_usertype_<siteId>` hint that carries only guest/registered so cached app-shell HTML can restore header state, and a JS-readable basket snapshot cookie. The hint and basket cookies never carry tokens.
+
+## Rules
+
+- **Namespacing.** Cookies are suffixed with the site id (for example `cc-nx_RefArch`) so multi-site deployments do not collide. `dwsid` and `dw_dnt` are deliberately excluded (`COOKIE_NAMESPACE_EXCLUSIONS`) so B2C Commerce and external scripts can read them.
+- **No `userType` cookie.** It is derived from the access-token JWT (`rcid` claim means registered). The refresh-cookie name is only a cold-start fallback and a write-time decision about which refresh cookie to set or delete.
+- **No `customerId` cookie.** Derived from the JWT. A legacy `customer_id` cookie is only deleted on logout and error paths.
+- **Value source.** Token strings come from the SLAS token response body; `userType`, `customerId`, `usid`, expiry and consent are decoded from the JWT so they cannot drift from the token. `dwsid` is the exception (SLAS `Set-Cookie`).
+- **Expiry overrides.** `PUBLIC_COMMERCE_API_GUEST_REFRESH_TOKEN_EXPIRY_SECONDS` and `PUBLIC_COMMERCE_API_REGISTERED_REFRESH_TOKEN_EXPIRY_SECONDS` can shorten the refresh lifetime; values above 30 / 90 days are capped.
+- **Defaults.** `path: '/'`, `sameSite: 'lax'`, `secure` only on deployed HTTPS (gated on `isRemote()`); `SameSite=None` cookies used by Page Designer design mode always stay `Secure`. The resolved `app.cookies.domain` (or per-site `commerce.sites[].cookies.domain`) applies to every cookie the storefront writes.
+- **Never write auth cookies directly.** Use `updateAuth` / `destroyAuth`; the middleware owns serialization and deletes cookies with expired `Set-Cookie` headers.
+
+## Debugging checklist
+
+1. DevTools > Application > Cookies: do you see duplicates of the same name (host-only plus domain-scoped)? See cookie-domain rollout notes in `storefront-next:sfnext-security`.
+2. Login works but does not stick on Safari over `http://localhost`: `secure` cookies are refused; confirm you are on `pnpm dev`/`pnpm preview` (which write non-secure cookies) and not a tunnel or HTTPS proxy with mismatched host.
+3. Hybrid pages lose the session: confirm `dwsid` is present on both storefronts and the cookie-domain settings agree on both sides.
+4. Repeated `session_expired` redirects: check the SLAS client's refresh-token settings and that the cookie domain matches the serving host.

package/content/guidance/storefront-next/sfnext-authentication/references/LOGIN-FLOWS.md

@@ -0,0 +1,59 @@
+# Login Flows
+
+All flows end in `updateAuth(context, tokenResponse)` from `@/middlewares/auth.server`. Prefer the existing route and library code over new implementations:
+
+| Flow | Entry points in your project |
+|---|---|
+| Password login | `src/routes/_empty.login.tsx`, `src/lib/api/auth/standard-login.server.ts` |
+| Registration | `src/routes/_empty.signup.tsx`, `src/lib/api/auth/register.server.ts` |
+| Password reset | `src/routes/_empty.reset-password.tsx`, `action.request-password-reset.ts`, `resource.slas-reset-password-callback.ts`, `src/lib/api/auth/reset-password.server.ts` |
+| Passwordless / OTP | `action.authorize-passwordless-email.ts`, `action.verify-passwordless-otp.ts`, `action.otp-request.ts`, `action.otp-verify.ts`, `resource.slas-passwordless-login-callback.ts`, `src/lib/auth/passwordless-login.server.ts` |
+| Social login | `src/lib/api/auth/social-login.server.ts` |
+| Passkeys | `action.passkey-*.ts`, `resource.passkey-status.ts`, `_app.account.passkeys.tsx`, `src/components/passkeys/`, `src/lib/auth/passkey-support.ts`, `webauthn.ts` |
+| Guest order lookup | `_app.order-lookup.*`, `action.order-lookup-*.ts`, `src/lib/order/` |
+
+Auth helpers used by these flows (`authorizePasswordless`, `getPasswordLessAccessToken`, `requestOtp`, `verifyOtp`, `getPasswordResetToken`, `resetPasswordWithToken`, passkey start/finish functions) are exported from `@/middlewares/auth.server`.
+
+## Passwordless (magic link) and OTP
+
+- Enable in `config.server.ts` under `features.passwordlessLogin` (`enabled`, `mode: 'email' | 'callback'`, `callbackUri` default `/passwordless-login-callback`, `landingUri` default `/login`). The callback URL must be allowlisted in the SLAS client. The callback route takes no site/locale prefix so one SLAS entry covers all sites.
+- Requires a SLAS **private** client: set `commerce.api.privateKeyEnabled: true`. If it is `false`, passwordless is disabled at runtime regardless of other settings.
+- `features.otpRequest.mode`: `email` (SLAS sends the code; supports email verification) or `callback` (SLAS POSTs the code to your `callbackUri` and you deliver it; no email-verification UI). `auth.otpLength` must be 6 or 8 and match the SLAS client.
+- Email verification UI (verified badge, change email, passwordless registration) turns on with the Business Manager preference **Enable Email Verification** (Site Preferences > Storefront Login Preferences; up to 5 minutes to propagate). Changing login email also needs **Enable Loginid Updates for SCAPI** (request via Salesforce support) and B2C 24.7 or later.
+- Full detail and troubleshooting table: `docs/README-EMAIL-VERIFICATION.md`.
+
+## Email delivery (email cartridge)
+
+Magic links, password resets and OTPs are sent by the `app_storefrontnext_base` cartridge's `POST /notify` custom API, called server-side via `clients.sfnextNotify` (`src/lib/notify/notify.server.ts`). One-time setup:
+
+1. `sfnext setup-base-cartridge --slas-client-id <id>` registers the `c_sfnext_notify` scope on the SLAS client (idempotent; needs `SFCC_SHORTCODE`, `SFCC_TENANT_ID` and OAuth client credentials).
+2. Deploy the cartridge (`pnpm cartridge:deploy --reload`) and add `app_storefrontnext_base` to the site cartridge path.
+3. Complete the Business Manager steps in `docs/README-EMAIL-CARTRIDGE.md` (storefront host allowlist preference, etc.).
+
+To change how mail is sent, customize the cartridge's `sendNotification` helper rather than the storefront. Deploy and endpoint registration checks: `b2c-cli:b2c-code`, `b2c-cli:b2c-scapi-custom`.
+
+## Social login
+
+- Enable `features.socialLogin` (`enabled`, `providers`, `callbackUri` default `/social-callback`). Each provider also needs setup in Account Manager / SLAS.
+- Flow is authorization-code with PKCE: generate the challenge, store the verifier via `updateAuth(context, (cur) => ({ ...cur, codeVerifier }))` (lands in httpOnly `cc-cv`, 5 minutes), redirect to the IDP, exchange the code in the callback and call `updateAuth(context, tokenResponse)`.
+- Adding a provider beyond the defaults usually needs CSP changes (`connect-src`, redirect/popup origins): see `storefront-next:sfnext-security`.
+- Guest wishlist/basket must be captured before and merged after the token swap; copy the shape of `social-login.server.ts`.
+- In a hybrid setup add `^/social-callback.*` to `HYBRID_ROUTING_RULES` (see `storefront-next:sfnext-hybrid-storefronts`).
+
+## Passkeys
+
+Enable with `features.passkey.enabled`. Registration is authorized by an OTP whose delivery follows `features.passkey.mode` (`email` or `callback`, same allowlisting rules as above). Passkeys are managed on `/account/passkeys`.
+
+## Guest order lookup
+
+Lets a guest find an order by order number plus email, confirm a 6-digit access code (valid 15 minutes, fixed by SCAPI) and view a redacted read-only order.
+
+- Set `guestOrderLookup.enabled: true` (default `false`). When off, both pages 404 and the actions return `FEATURE_DISABLED`.
+- Set `GUEST_ORDER_LOOKUP_COOKIE_SECRET` (falls back to `CLIENT_SECRET`); without a secret the feature fails closed with `CONFIGURATION_ERROR`.
+- Implement the B2C Commerce hook `sfcc.app.order.sendOrderAccessCode(order, accessCode)` in a cartridge; the storefront never sends this email itself (the shipped email cartridge covers it).
+- `guestOrderLookup.allowedFields` is an allow-list applied to the order before it reaches the browser; `cooldownSeconds` and `orderNumberPattern` tune abuse controls. Turnstile is enforced on the request-code step only (`guestOrderLookup.turnstile`).
+- Full detail: `docs/README-GUEST-ORDER-LOOKUP.md`.
+
+## Bot protection on login
+
+The passwordless/OTP email step, checkout registration and order lookup can be gated with Cloudflare Turnstile. Configuration and rollout are in `storefront-next:sfnext-security`.

package/content/guidance/storefront-next/sfnext-commerce-features/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: sfnext-commerce-features
+description: >-
+  Catalogue and router for optional Storefront Next commerce features: Shopper Context (qualifiers, source codes), Order Management returns/cancel/tracking (SOM/OMS), delivery estimates, feature stubs (@feature-stub), guest order lookup, the app_storefrontnext_base email cartridge, and the shipped extensions (bnpl, bopis, multiship, store-locator, ratings-reviews, customer-preferences, product-content, shipping-delivery, theme-switcher). For each: which flag, SLAS scope, Business Manager setting, cartridge, or extension registry entry it needs, and which in-project doc to read. Use when asked how to enable a feature, why a feature does not render, what prerequisites a feature has, or which stubs are mock data. Do not use for building a new extension (use `storefront-next:sfnext-extensions`), config loading (use `storefront-next:sfnext-configuration`), or SLAS login flows (use `storefront-next:sfnext-authentication`).
+---
+
+# Storefront Next Commerce Features
+
+Start with the feature table, then read the named doc in your project's `docs/` folder. Do not assume a feature is live: several ship as UI scaffolds with mock data (see Feature stubs).
+
+## Feature table
+
+| Feature | Enable with | Also needs | Read |
+|---|---|---|---|
+| Shopper Context | `features.shopperContext.enabled` (env: `PUBLIC__app__features__shopperContext__enabled=true`), default off | Shopper Context API access for the SLAS client; qualifiers arrive as URL params or via the `useShopperContext` hook, stored in cookies | `docs/README-SHOPPER-CONTEXT.md` |
+| Returns, cancel, tracking (Order Management) | Nothing to toggle | Salesforce Order Management connected to the B2C instance; order loader expands `['oms','oms_shipments']`; without `omsData` only tracking shows | `docs/README-ORDER-MANAGEMENT.md` |
+| Delivery estimates | Keep extension `SFDC_EXT_SHIPPING_DELIVERY` installed | SLAS scopes `sfcc.shopper-delivery-estimates` and `sfcc.shopper-standard`, a delivery-estimate Commerce App bound to `sfcc.app.shipping.estimate`, online products on the site | `docs/README-DELIVERY-ESTIMATES.md` |
+| Guest order lookup | `guestOrderLookup.enabled: true` in `config.server.ts` | `GUEST_ORDER_LOOKUP_COOKIE_SECRET` (or `CLIENT_SECRET` fallback) and a cartridge implementing hook `sfcc.app.order.sendOrderAccessCode` to email the code | `docs/README-GUEST-ORDER-LOOKUP.md` |
+| Email cartridge (`app_storefrontnext_base`) | Deploy cartridge, add to site cartridge path | SLAS scope `c_sfnext_notify` (`sfnext setup-base-cartridge --slas-client-id <id>`), import preference metadata, set `Storefront Hosts` global custom preference, callback mode in storefront config | `docs/README-EMAIL-CARTRIDGE.md` |
+| Feature stubs | n/a | Mock UI scaffolds, not integrations | `docs/README-FEATURE-STUBS.md` |
+
+## Extensions shipped in src/extensions
+
+Registry: `src/extensions/config.json` (keys `SFDC_EXT_*`). Each extension contributes components to `UITarget` points through its `target-config.json`. To install or remove one, follow the install/uninstall instructions in `instructions/*.mdc` when the registry entry references them; building new extensions is `storefront-next:sfnext-extensions`.
+
+| Extension | Registry key | Notes |
+|---|---|---|
+| Store Locator | `SFDC_EXT_STORE_LOCATOR` | Find stores by location. Guided install/uninstall in `instructions/`. |
+| Multiship | `SFDC_EXT_MULTISHIP` | Ship items to several addresses in one order. Guided install/uninstall. |
+| Buy Online Pickup In Store | `SFDC_EXT_BOPIS` | Depends on Store Locator and Multiship. Guided install/uninstall. |
+| Shipping and Delivery | `SFDC_EXT_SHIPPING_DELIVERY` | Registers `sfcc.pdp.estimatedDelivery`; see delivery estimates row. |
+| Buy Now Pay Later (demo) | `SFDC_EXT_BNPL` | Mock fixtures; `sfcc.pdp.bnpl.message` target. Replace API function bodies to integrate a provider. |
+| Ratings and Reviews (demo) | `SFDC_EXT_RATINGS_REVIEWS` | Mock fixtures for PDP, cart modal, order detail CTA. Integrate Bazaarvoice, PowerReviews, etc. by replacing API bodies. |
+| Product Content (demo) | `SFDC_EXT_PRODUCT_CONTENT` | Returns/warranty card, FAQ, collapsibles (`sfcc.pdp.returnsWarranty`, `sfcc.pdp.faq`, `sfcc.pdp.collapsibles`). Fixtures in `lib/api/product-content.server.ts`. |
+| Customer Preferences (demo) | `SFDC_EXT_CUSTOMER_PREFERENCES` | Interests/preferences on the account page. Mock data. |
+| Theme switcher | none in registry | Folder `src/extensions/theme-switcher` has no registry entry in the shipped project; check your project before relying on it. |
+
+Demo extensions are "(Demo)" in `config.json`. Treat them as reference implementations: read the extension `README.md` and replace fixture functions before go-live.
+
+## Feature stubs
+
+Working UI with no backend (express checkout buttons, BNPL, returns and warranty, customer interests, and others). Find all of them:
+
+```bash
+grep -r "@feature-stub" src/
+```
+
+Each marker explains how to strip or wire it. Review the list before launch so mock content does not ship.
+
+## Decision flow when "the feature is not showing"
+
+1. Flag off? (`shopperContext`, `guestOrderLookup`) - check `config.server.ts` and env overrides.
+2. Extension missing from `src/extensions/config.json`, or dependencies not installed (BOPIS needs Store Locator and Multiship)?
+3. Missing SLAS scope on the shopper client (see `storefront-next:sfnext-authentication`)? Confirm in your SLAS client config, then re-login to get a fresh token.
+4. Backend not configured: OMS not connected, Commerce App not bound, cartridge not on the site cartridge path.
+5. Result is mock data: it is a stub.
+
+More detail per group: [references/FEATURE-PREREQUISITES.md](references/FEATURE-PREREQUISITES.md).
+
+## Related Skills
+
+- `storefront-next:sfnext-extensions` - UITarget, target-config.json, authoring extensions
+- `storefront-next:sfnext-configuration` - feature flags and env overrides
+- `storefront-next:sfnext-authentication` - SLAS scopes and clients
+- `storefront-next:sfnext-scapi` - calling the backing SCAPI endpoints
+- `storefront-next:sfnext-deployment` - deploying cartridges and bundles
+- `b2c-cli:b2c-mrt` - Managed Runtime environment variables