@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

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

@@ -1,10 +1,33 @@
 ---
-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` |
+| Bots, scrapers or abusive traffic at the eCDN (WAF, firewall, rate limits) | `skill://b2c-ops/b2c-edge-traffic-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 +63,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 +73,39 @@ 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. Doc IDs are lookup keys: when citing
+sources to the user, link the doc's `url` from `docs_read`, unless they ask for
+IDs or Markdown links (`sourceUrl`).
+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 +116,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

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).