@salesforce/b2c-dx-mcp 3.2.0 → 3.3.0

package/content/guidance/mcp/{cip → b2c-mcp-cip}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: MCP CIP Analytics
-description: Discover and run CIP reports or analytics SQL for sales, merchandising, and technical operations. Resolve warehouse access, bound results, and interpret site/date scope.
+name: b2c-mcp-cip
+description: Required before cip_query. Discover and run CIP reports or analytics SQL for sales, merchandising, and technical operations; resolve warehouse access, bound results, and interpret site/date scope.
 ---
 
 # CIP analytics
@@ -8,7 +8,7 @@ description: Discover and run CIP reports or analytics SQL for sales, merchandis
 Use CIP for warehouse analytics: sales, products, promotions, search, payments,
 traffic, inventory, and API/controller trends. Use SCAPI for current records;
 logs/metrics for immediate diagnosis.
-Read this skill once through resources or `skills_read` (`mcp/cip`), then pass
+Read this skill once through resources or `skills_read` (`mcp/b2c-mcp-cip`), then pass
 `skillRead: true` to `cip_query`. Discovery needs no acknowledgment.
 
 ## Choose and discover
@@ -42,13 +42,13 @@ Reports & Dashboards data tracking enabled on supported 26.1+ environments.
 No data or rejected access does not establish zero sales or a healthy system.
 
 Missing values: `config_inspect` with masking; ask the user if the target cannot
-be determined. [MCP configuration](skill://mcp/b2c-config/SKILL.md) explains resolution.
+be determined. [MCP configuration](skill://mcp/b2c-mcp-config/SKILL.md) explains resolution.
 For CLI equivalents, configuration, host selection, and availability caveats:
 [existing CIP skill](skill://b2c-cli/b2c-cip/SKILL.md) (`skills_read` ID `b2c-cli/b2c-cip`)
-and [analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac),
-plus the [CLI reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cip).
-Read these conditionally, not as extra prerequisites. If that collection is
-excluded, use `docs_read` query `cli-cip` or the guide URL.
+and the analytics guide (`docs_read({query: "guide-analytics-reports-cip-ccac"})`,
+[online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac.md)), plus the CLI reference
+(`cli-cip`, [online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cip.md)).
+Read these conditionally, not as extra prerequisites.
 Official [JDBC setup and limits](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_access_guide.html).
 
 ## Query and interpret
@@ -84,3 +84,5 @@ Read further only for an unresolved question:
   [starter queries](skill://b2c-cli/b2c-cip/references/STARTER_QUERIES.md), not the whole file.
 Stop when the report and evidence answer the task; no follow-up skill read is required.
 For incidents, correlate trends with logs and the relevant `b2c-ops` runbook.
+
+Other MCP workflows and runbooks: [skill index](skill://mcp/b2c-mcp-server/SKILL.md#skill-index).

package/content/guidance/mcp/{b2c-config → b2c-mcp-config}/SKILL.md

@@ -1,11 +1,12 @@
 ---
-name: b2c-config
-description: MCP configuration, authentication setup, external access grants, and masked inspection. Use for setup or unresolved configuration issues; routine config_inspect needs no skill read.
+name: b2c-mcp-config
+description: Resolve B2C MCP configuration, authentication, and external access grants with masked inspection. Use for setup, credential, or wrong-target issues; routine config_inspect needs no skill read.
 ---
 
 # MCP Configuration
 
-For MCP installation or tool selection, see [server setup](skill://mcp/server/SKILL.md).
+For MCP installation, tool selection, or other MCP workflows, see the
+[server skill index](skill://mcp/b2c-mcp-server/SKILL.md#skill-index).
 
 ## Inspect resolved values
 
@@ -72,15 +73,15 @@ pages; follow returned `nextOffset` when the needed topic lies later in an artic
 From the same project, `b2c setup inspect --json` uses the same resolver and
 default masking. Match the environment, `--config`, and `--instance` selections
 when comparing results. For CLI setup or configuration commands, consult
-[b2c-cli/b2c-config](skill://b2c-cli/b2c-config/SKILL.md) when the broader skill
-collections are enabled, or the shared configuration documentation below.
+[b2c-cli/b2c-config](skill://b2c-cli/b2c-config/SKILL.md) or the shared
+configuration documentation below.
 For authentication specifically, `skills_read({id: "b2c-cli/b2c-config", section: "authentication"})`.
 CLI browser-login instructions do not enable SCAPI Admin code-mode user auth.
 
 ## Further reading
 
-Read only for the configuration issue at hand:
+Read with `docs_read({query: ID})`, only for the configuration issue at hand:
 
-- [MCP configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration)
-- [Shared configuration and precedence](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration)
-- [Authentication setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication)
+- MCP configuration: `mcp-configuration` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration.md))
+- Shared configuration and precedence: `guide-configuration` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.md))
+- Authentication setup: `guide-authentication` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.md))

package/content/guidance/mcp/{debugger → b2c-mcp-debugger}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: MCP Debugger Usage
-description: Bounded debugger capture, request triggering, state inspection, and reliable session cleanup.
+name: b2c-mcp-debugger
+description: Debug B2C Commerce server-side scripts with the MCP debugger tools, using bounded breakpoint capture, request triggering, state inspection, and reliable session cleanup.
 ---
 
 # MCP Debugger Usage
@@ -54,18 +54,19 @@ next breakpoint or request completion. End sessions explicitly.
   A timeout leaves the breakpoint armed. Check sessions for a late halt; end with
   `clear_breakpoints: true` when finished. Do not leave an unbounded capture waiting.
 - Configuration still unexplained after `config_inspect`: consult
-  [MCP configuration](skill://mcp/b2c-config/SKILL.md).
+  [MCP configuration](skill://mcp/b2c-mcp-config/SKILL.md).
 - Missing BM permission/access key: `docs_read({query: "mcp-security"})` for debugger
   requirements; `guide-authentication` for WebDAV key setup. For other setup issues,
   `docs_search` with the specific error. If docs tools are unavailable, use
-  [debugger access](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/security#debugger)
-  and [WebDAV key setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication#webdav-access).
+  [debugger access](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/security.md#debugger)
+  and [WebDAV key setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.md#webdav-access).
   General WebDAV OAuth instructions do not apply to the debugger.
 - Before repeating a failed request, check whether it already changed state.
 
 ## CLI or IDE, when requested
 
 For terminal debugging use `b2c debug cli`; for a DAP client use `b2c debug`.
-For those workflows, read [b2c-cli/b2c-debug](skill://b2c-cli/b2c-debug/SKILL.md)
-when the broader skill collections are enabled, or the
-[CLI debugger reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/debug).
+For those workflows, read [b2c-cli/b2c-debug](skill://b2c-cli/b2c-debug/SKILL.md) or the
+CLI debugger reference (`docs_read({query: "cli-debug"})`, [online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/debug.md)).
+
+Other MCP workflows and runbooks: [skill index](skill://mcp/b2c-mcp-server/SKILL.md#skill-index).

package/content/guidance/mcp/{scapi → b2c-mcp-scapi}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: MCP SCAPI Code Mode
-description: Discover standard and live custom SCAPI contracts, compose Admin requests, and verify changes using configured authentication and safety rules.
+name: b2c-mcp-scapi
+description: Required before scapi_search or scapi_execute. Discover standard and live custom SCAPI contracts, compose Admin and Shopper requests, and verify changes under configured authentication and Safety Mode.
 ---
 
 # SCAPI Code Mode
@@ -8,13 +8,80 @@ description: Discover standard and live custom SCAPI contracts, compose Admin re
 Prefer dedicated tools. Otherwise discover with `scapi_search`, compose with
 `scapi_execute`. Use JavaScript async arrow functions; no TypeScript or imports.
 Warehouse reports/SQL use `cip_discover` / `cip_query`, not code mode;
-see [CIP analytics](skill://mcp/cip/SKILL.md).
+see [CIP analytics](skill://mcp/b2c-mcp-cip/SKILL.md).
 Use code mode for API discovery, request composition, and result processing.
 Use terminal/file tools for local development, builds, and filesystem work.
 Filesystem APIs, subprocesses, worker threads, and native addons are restricted.
 Read this skill once via resources or `skills_read`,
 then pass `skillRead: true`. This does not authorize mutations.
 
+## Code objects
+
+Write JavaScript against these objects, not TypeScript.
+
+`scapi_search`:
+
+```ts
+interface Operation {
+  api: string;
+  operationId: string;
+  summary?: string;
+  parameters: Array<{name: string; in: string; required?: boolean; schema?: unknown}>;
+  requestBody?: {required?: boolean; content: Record<string, {schema: any}>};
+  responses?: Record<string, unknown>;
+  security: Array<Record<string, string[]>>;
+  auth: {types: string[]; schemes: string[]; executable: boolean}; // runtime support, not access
+}
+declare const spec: {
+  apis: Array<{id: string; apiFamily: string; apiName: string; apiVersion: string; authTypes: string[]}>;
+  paths: Record<string, Record<string, Operation>>; // full paths, lowercase HTTP methods
+};
+```
+
+`scapi_execute` (`async (input) => ...` receives the tool's `input`):
+
+```ts
+declare const organizationId: string | undefined; // resolved tenant
+declare const siteId: string | undefined; // configured site
+declare const scapi: {
+  request(options: {
+    method: string;
+    path: string;
+    query?: Record<string, unknown>;
+    body?: unknown;
+  }): Promise<{status: number; ok: boolean; data: any; diagnostic?: {code: string; message: string}}>;
+};
+```
+
+Both tools also expose `codemode.search`/`codemode.describe`; `codemode.run` and
+`auth.*` are execute-only. See [Reusable workflows](#reusable-workflows) and [Authentication](#authentication).
+
+Search examples:
+
+```js
+// Find product operations
+async () =>
+  Object.entries(spec.paths)
+    .filter(([path]) => path.startsWith('/product/products/'))
+    .flatMap(([path, methods]) =>
+      Object.entries(methods).map(([method, op]) => ({method, path, operationId: op.operationId})),
+    );
+
+// Inspect only fields needed for creation
+async () => {
+  const op = spec.paths['/product/products/v1/organizations/{organizationId}/products/{productId}'].put;
+  const body = op.requestBody.content['application/json'].schema;
+  const fields = [...new Set([...(body.required ?? []), 'name', 'owningCatalogId', 'onlineFlag'])];
+  return {
+    parameters: op.parameters,
+    required: body.required,
+    fields: Object.fromEntries(fields.map((k) => [k, body.properties[k]])),
+    auth: op.auth,
+    security: op.security,
+  };
+};
+```
+
 ## Discover
 
 Discovery defaults to the bundled standard contracts offline; no credentials needed.
@@ -22,7 +89,9 @@ Pass `schemas: "live"` to search the configured tenant's Schemas API contracts
 instead: tenant `c_*` properties, custom APIs, and APIs newer than the bundle.
 Live search needs `sfcc.scapi-schemas`, uses the same project context as
 `scapi_execute`, and caches per tenant for the server session (`refresh: true` refetches). Contracts that
-failed to load are listed in `schemaFailures`. Schemas and responses can be huge.
+failed to load are listed in `schemaFailures`. APIs with `origin: "local"` are
+developer-supplied beta contracts (`--scapi-schemas`). They replace the bundled and live versions in search and
+execution. Schemas and responses can be huge.
 Return only what the next decision needs:
 
 1. Find APIs/operations through `spec.apis`/`spec.paths`; return method/path/operationId.
@@ -106,16 +175,16 @@ and `ShopperToken` operations use their declared `c_*` scopes. [Custom API workf
 - Unsupported: registered-shopper-only operations (`RegisteredShopperToken`),
   trusted-system/agent on-behalf tokens, and SLAS itself (`shopper/auth/v1`).
   `auth.slas({flow: 'registered', ...})` exports a registered token for external clients.
-  SLAS admin roles differ: [CLI/SDK](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/slas).
+  SLAS admin roles differ: `docs_read({query: "cli-slas"})` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/slas.md)).
 - HTTP 401/403 retain `status`/`data` plus `diagnostic`; preserve these.
   A 403 alone does not prove missing scopes.
 
-For missing values or wrong targets, read [MCP configuration](skill://mcp/b2c-config/SKILL.md)
-(`skills_read` ID `mcp/b2c-config`). For external client/role/tenant-filter setup,
+For missing values or wrong targets, read [MCP configuration](skill://mcp/b2c-mcp-config/SKILL.md)
+(`skills_read` ID `mcp/b2c-mcp-config`). For external client/role/tenant-filter setup,
 use `docs_read({query: "guide-authentication"})`; official Admin authorization:
 `commerce-api/authorization-for-admin-apis`, scope definitions: `commerce-api/auth-z-scope-catalog`.
 For other access questions, search `docs_search` with the specific error and API.
-If docs are unavailable, use the [authentication guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication).
+If docs are unavailable, use the [authentication guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.md).
 These are conditional setup references, not additional prerequisite reads.
 
 ## Compose and verify
@@ -198,6 +267,8 @@ For explicit save requests, see [saving](references/saving.md).
 
 No CLI code-mode equivalent. For missing settings such as promotion discounts,
 consider [XML archives](skill://b2c-cli/b2c-site-import-export/SKILL.md)
-([CLI docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs)).
+(`docs_read({query: "cli-jobs"})`, [online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs.md)).
 [Platform reference](https://developer.salesforce.com/docs/commerce/commerce-api/references).
-[Configuration/access](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration).
+Configuration/access: `docs_read({query: "mcp-configuration"})` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration.md)).
+
+Other MCP workflows and runbooks: [skill index](skill://mcp/b2c-mcp-server/SKILL.md#skill-index).

package/content/guidance/mcp/{server → b2c-mcp-server}/SKILL.md

@@ -1,10 +1,32 @@
 ---
-name: server
-description: B2C MCP setup, toolset customization, available capabilities, tool choice, and skill discovery.
+name: b2c-mcp-server
+description: Index and setup for the B2C Commerce MCP server, covering toolset selection, tool choice by task, and the skill catalog. Use to enable tools, pick the right tool, or find the skill that covers a B2C task.
 ---
 
 # B2C MCP Server
 
+## Skill index
+
+Read only the skill that matches the task; each links its own references.
+
+| Task | Skill |
+| --- | --- |
+| Commerce API reads/writes (required before `scapi_search` / `scapi_execute`) | `skill://mcp/b2c-mcp-scapi/SKILL.md` |
+| Warehouse reports and SQL (required before `cip_query`) | `skill://mcp/b2c-mcp-cip/SKILL.md` |
+| Configuration, credentials, access grants, wrong target | `skill://mcp/b2c-mcp-config/SKILL.md` |
+| Server-side script debugging | `skill://mcp/b2c-mcp-debugger/SKILL.md` |
+| Instance files and selected cartridge uploads | [files](references/files.md) |
+| Production incident or unknown operational signal | `skill://b2c-ops/b2c-production-triage/SKILL.md` |
+| Failed or late jobs | `skill://b2c-ops/b2c-job-health/SKILL.md` |
+| Checkout or order failures | `skill://b2c-ops/b2c-checkout-triage/SKILL.md`, `skill://b2c-ops/b2c-order-failure-triage/SKILL.md` |
+| Anything else | `skill://index` |
+
+Every skill and reference file is readable as an MCP resource
+(`skill://<collection>/<skill>/<file>`) or with `skills_read({uri})`.
+Collections: `b2c` (platform/cartridges), `b2c-cli` (CLI), `b2c-ops`
+(operator/admin runbooks), `storefront-next` (storefronts), `mcp` (server/tool
+workflows). Search with `skills_read({query, collection})` or browse `skill://index`.
+
 ## Server configuration and tool availability
 
 Use the client's tool discovery before concluding a tool is unavailable.
@@ -40,7 +62,7 @@ Use launch arguments/environment for server settings, not project `.env` or `dw.
 ## Tool choice and project configuration
 
 - Call `config_inspect` directly with the task's `projectDirectory`; secrets are
-  masked. For resolution issues: [B2C config](skill://mcp/b2c-config/SKILL.md).
+  masked. For resolution issues: [B2C config](skill://mcp/b2c-mcp-config/SKILL.md).
   CLI equivalent, when requested: `b2c setup inspect`.
 - Deploy cartridges: `cartridge_deploy`; CLI scripts/extra flags: `b2c code deploy`.
   Confirm instance/version and preserve returned `resolution`. Use `files` for
@@ -50,37 +72,37 @@ Use launch arguments/environment for server settings, not project `.env` or `dw.
   exact text by HTTP byte range or downloads to `outputPath`; `webdav_put` uploads
   `content` or `sourcePath`. Prefer these over a terminal for supported transfers.
   [File choices and limits](references/files.md).
-- Debug: [MCP debugger](skill://mcp/debugger/SKILL.md). CLI/IDE only when requested.
+- Debug: [MCP debugger](skill://mcp/b2c-mcp-debugger/SKILL.md). CLI/IDE only when requested.
 - Prefer dedicated tools for their workflows. For other Commerce API tasks,
   use `scapi_search` / `scapi_execute`: products, campaigns, promotions, jobs,
-  code versions, site cartridge paths, and more. Read [the SCAPI skill](skill://mcp/scapi/SKILL.md)
+  code versions, site cartridge paths, and more. Read [the SCAPI skill](skill://mcp/b2c-mcp-scapi/SKILL.md)
   first; its task map and built-in snippets cover recurring operations.
 - Custom API scaffold: `b2c scaffold generate custom-api`; no MCP equivalent.
 - API/product documentation: `docs_search` / `docs_read`.
 - Warehouse analytics: `cip_discover` for reports/metadata, `cip_query` for report
-  or SQL execution. Read [CIP analytics](skill://mcp/cip/SKILL.md) before execution.
+  or SQL execution. Read [CIP analytics](skill://mcp/b2c-mcp-cip/SKILL.md) before execution.
   Prefer CIP for sales/merchandising/technical trends; SCAPI for current records.
-- Operations or incidents: look for `b2c-ops` runbooks in `skill://index` or
-  `skills_read` with `collection: "b2c-ops"` and the task query. Start with the
-  matching job-health, checkout-triage, order-failure-triage, or production-triage skill. Read only
-  relevant references. Runbooks guide evidence and handoff, not authorization
+- Operations or incidents: start with the matching `b2c-ops` runbook from the
+  [skill index](#skill-index), or `skills_read` with `collection: "b2c-ops"` and
+  the task query. Read only relevant references. Runbooks guide evidence and handoff, not authorization
   to rerun jobs or change data. CLI fallback is appropriate for an uncovered
   signal when terminal access is available; a skill does not supply that access.
 
 Do not infer tool names from CLI commands. Check a mutation's outcome before
 retrying after missing output.
 
-## Skills
+## Loading skills
 
-Browse `skill://index` or, when enabled, search `skills_read`: `b2c` (platform/cartridges),
-`b2c-cli` (CLI), `b2c-ops` (operator/admin runbooks), `storefront-next` (storefronts),
-`mcp` (server/tool workflows).
-Read `skill://` URIs through MCP resources, or use `skills_read({uri: "skill://mcp/debugger/SKILL.md"})`
-for a file when enabled. These URIs are not native skill commands; do not derive
-client skill names from the server name or URI. Use `id` for a discovered skill ID.
-Result `skillReferences` point to optional
-detail for observed conditions: read the URI, or pass its URI and `section` to
-`skills_read`. Skills are directory-agnostic.
+If the client lists this server's skills, load them through it. Otherwise read
+`skill://` URIs as MCP resources, or with `skills_read({uri})`.
+Use a skill's listed name or URI; do not derive names from the server name.
+Relative links resolve against the linking skill's directory.
+Skills cite documentation IDs as `b2c docs read <id>` or `docs_read({query: "<id>"})`;
+read them with `docs_read({query: "<id>"})` (no terminal needed). Online links
+point to the same pages as Markdown.
+Result `skillReferences` point to optional detail for observed conditions:
+read the URI, or pass its URI and `section` to `skills_read`. Skills are
+directory-agnostic.
 
 Tools needing a skill name it in their description; no universal read is
 required. Resource and tool reads are equivalent; do not read both.
@@ -91,9 +113,11 @@ When scripting tool calls, emit `structuredContent` when present, otherwise
 
 ## Setup references
 
-- Credentials, external grants, or access failures: [MCP configuration](skill://mcp/b2c-config/SKILL.md),
-  `skills_read({id: "mcp/b2c-config", section: "setup-and-access"})` when available.
+Documentation IDs below are read with `docs_read({query: ID})`.
+
+- Credentials, external grants, or access failures: [MCP configuration](skill://mcp/b2c-mcp-config/SKILL.md),
+  `skills_read({id: "mcp/b2c-mcp-config", section: "setup-and-access"})`.
   It maps setup issues to exact documentation IDs; no universal setup read is needed.
-- [Client installation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation)
-- [Launch configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration)
-- [Capabilities and toolsets](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets)
+- [Client installation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation.md)
+- Launch configuration: `mcp-configuration` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration.md))
+- Capabilities and toolsets: `mcp-toolsets` ([online](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets.md))

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