@salesforce/b2c-dx-mcp 3.2.1 → 3.4.0

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sfnext-theming
+description: >-
+  Re-brand and re-skin a Storefront Next storefront: change the color palette, corner radius and shadows (shape tokens), header and footer colors, typography and web fonts, logo, favicon, hero scrims, and brand copy, with WCAG contrast checks. Use when asked to rebrand or restyle the storefront, change the primary color, swap the font, make the header dark, make cards rounded or flat, replace the logo, edit src/theme, core.css, header.css, brand.css, tailwind.css, base.css, or src/lib/fonts.ts, or verify a theme change in the Design System Storybook stories. Do not use for building or styling an individual component (use `storefront-next:sfnext-components`), Figma kit sync (use `storefront-next-figma:sfnext-create-figma-kit`), or site configuration (use `storefront-next:sfnext-configuration`).
+---
+
+# Theming a Storefront Next Storefront
+
+Your storefront has exactly one theme, in `src/theme/`, and it is yours to edit. Rebranding is mostly value changes in a few CSS files; components pick the new look up through token classes. Choose a starting look with `sfnext create-storefront --vertical <id>` (a starter theme) and then customize it as below.
+
+## Where things live
+
+| Concern | File |
+|---|---|
+| Entry point and Tailwind `@source` scoping | `src/theme/index.css` (imports `shared.css`, which sets import order) |
+| Palette: background, foreground, primary, secondary, accent, muted, border, ring, destructive/success/warning/info | `src/theme/tokens/core.css` |
+| Shape: `--ui-radius`, `--ui-shadow`, `--ui-border-width` | `src/theme/tokens/core.css` |
+| Header, menu, footer, newsletter band, `--header-logo-filter` | `src/theme/tokens/header.css` |
+| Status and feedback colors | `src/theme/tokens/status.css` |
+| Swatches, sidebar, agentic UI, payment and cart extras, focus helpers | `tokens/swatch.css`, `sidebar.css`, `agentic.css`, `components.css`, `custom.css` |
+| `--brand-*` color primitives and hero scrims (`--hero-overlay-*`, `--hero-scrim`) | `src/theme/tokens/brand.css` |
+| Font stacks `--font-sans/-serif/-mono`; token-to-utility bridge | `src/theme/tailwind.css` (`@theme inline`) |
+| `@font-face`, base layer, `.section-container`, section-scoped shape rules | `src/theme/base.css` |
+| Component-level CSS (navigation, cart sheet, toasts, store locator) | `src/theme/overrides/*.css` |
+| Font binding and preload | `public/fonts/*.woff2`, `src/lib/fonts.ts` (used by `src/root.tsx`) |
+| Logo, favicon, hero and payment images | `public/images/`, `public/favicon.ico` |
+| Site name and brand strings | `src/locales/<locale>/translations.json` (`common.defaultSiteName`) |
+
+Palette values are not all derived from `brand.css`: `core.css` sets `--primary` and friends directly, so change them there. Token-to-class wiring and the full token file list are covered in `storefront-next:sfnext-components` (token system reference).
+
+## Workflow
+
+### 1. Read the current theme
+
+Open `src/theme/index.css`, `tokens/core.css`, `tokens/header.css`, and `tailwind.css` before editing. Keep variable names; change values.
+
+### 2. Palette
+
+Edit `:root` in `tokens/core.css`: `--primary`/`--primary-foreground`, `--background`/`--foreground`, `--secondary`, `--accent`, `--muted`, borders, `--ring`. Comments in the file record WCAG contrast ratios for the current values; recompute for yours. Minimums: 4.5:1 for text (`--primary` on `--primary-foreground`, `--foreground` on `--background`, each status color on its `-foreground`), 3:1 for borders and focus rings against the surface.
+
+Update `tokens/status.css` if semantic colors clash with the new palette, and `tokens/swatch.css`, `tokens/components.css` where defaults look off.
+
+### 3. Header, footer, and newsletter chrome
+
+`tokens/header.css` is deliberately decoupled from `--primary`, so changing the primary color does not recolor the header. Set `--header-background`/`--header-foreground`, menu hover/active colors, and `--footer-*` yourself. The logo is an image: for a dark header with a dark logo, set `--header-logo-filter` (for example `brightness(0) invert(1)` turns a black logo white; `none` leaves it alone). `--newsletter-background` defaults to `var(--primary)`.
+
+### 4. Shape
+
+Set `--ui-radius`, `--ui-shadow`, `--ui-border-width` in `core.css` to re-skin every shadcn primitive at once. Flat and square: `0`, `none`, `0`. Soft and raised: `var(--radius-xl)`, a light shadow, `0`. Do not edit primitives or add `rounded-*`/`shadow-*` classes, and never write `--radius-ui` / `--shadow-ui` (compile-time bridges, silent no-op). Scoped overrides, section rules, and the Card border exception are covered in `storefront-next:sfnext-components` (shape tokens reference). If your default border width is 0, the section rules at the bottom of `base.css` re-enable 1px Card borders on account, auth, and checkout pages; adjust those to taste.
+
+### 5. Typography
+
+Four touch points, all must agree:
+
+1. Put the variable `.woff2` in `public/fonts/`.
+2. `src/lib/fonts.ts`: `import font from '/fonts/<file>.woff2'; export const primaryFont = font;` (`root.tsx` preloads it).
+3. `@font-face` in `src/theme/base.css` (same URL, weight range, `font-display: swap`).
+4. `--font-sans` / `--font-serif` / `--font-mono` in `src/theme/tailwind.css`, with a fallback stack of similar metrics.
+
+Self-host fonts (WOFF2, preloaded, no third-party CDN). Remove the old font file if unused.
+
+### 6. Assets and copy
+
+- Logo: replace `public/images/logo.svg` (the `Logo` component in `src/components/logo` renders it; you can replace that component for an inline-SVG logo).
+- Favicon: `public/favicon.ico`.
+- Hero and promo images: `public/images/` (and the Page Designer content that references them).
+- Brand name: `common.defaultSiteName` in each `src/locales/<locale>/translations.json` you ship (used in page titles).
+- Hero text scrims: `--brand-black`/`--brand-white` in `brand.css` feed `--hero-overlay-dark/-light` and `--hero-scrim`; update them with the brand so hero text stays legible.
+
+### 7. Dark mode
+
+The shipped theme has one palette and no `.dark` token block. Do not promise dark mode; it would be new work (a `.dark` scope for every token file).
+
+### 8. Verify
+
+```bash
+pnpm dev                                   # look at home, PLP, PDP, cart, checkout, account
+pnpm storybook                             # Design System/Theme/Colors, Typography, Radius, Shadows
+pnpm lint                                  # color-linter flags hard-coded colors
+pnpm typecheck
+pnpm storybook:test --type=snapshot        # add --update only after reviewing intended changes
+pnpm storybook:test --type=a11y            # contrast and ARIA via axe-core
+```
+
+The `Design System/Theme/*` stories (`src/design-system/stories/`) render the live tokens and are the quickest visual check.
+
+## Guardrails
+
+- Change values in token files; do not sprinkle hex codes or `bg-[#...]` in components.
+- Need a new token? Define it in a `tokens/*.css` file and bridge it in `@theme inline` in `tailwind.css` (see TOKEN-SYSTEM).
+- Component-level CSS goes in `src/theme/overrides/*.css` (import it from `shared.css`) or `base.css`; prefer `[data-slot="..."]` selectors over utility-class selectors.
+
+## Design handoff
+
+If your designers work in Figma, keep the Figma variables and code tokens aligned with `storefront-next-figma:sfnext-create-figma-kit` (requires the Figma MCP server). Change the tokens in code first, then sync the kit.
+
+## Related Skills
+
+- `storefront-next:sfnext-components` - Build and style components with token classes and shape tokens
+- `storefront-next:sfnext-accessibility` - Contrast, focus, and accessibility scans
+- `storefront-next:sfnext-i18n` - Locale files that hold brand copy
+- `storefront-next:sfnext-performance` - Font and image loading guidance
+- `storefront-next:sfnext-page-designer` - Content and hero components authored in Page Designer
+- `storefront-next-figma:sfnext-create-figma-kit` - Sync the Figma design kit with your tokens

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/evals/trigger-evals.json

@@ -0,0 +1,5 @@
+[
+  {"query": "Re-skin my Storefront Next storefront: change the primary color to a deep green, swap the font to Inter, and make the header dark.", "should_trigger": true},
+  {"query": "Make the cards and buttons rounded with a soft shadow across the whole site. Where do I change that?", "should_trigger": true},
+  {"query": "Create a new ProductBadge component with CVA variants and a Storybook story that passes the snapshot tests.", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next/skills/sfnext-theming/references/REBRAND-CHECKLIST.md

@@ -0,0 +1,29 @@
+# Rebrand Checklist
+
+Work top to bottom; each item names the file to touch.
+
+- [ ] `src/theme/tokens/core.css`: `--primary`, `--primary-foreground`, `--background`, `--foreground`, `--secondary`, `--accent`, `--muted`, `--border`, `--input`, `--ring`
+- [ ] `src/theme/tokens/core.css`: contrast re-checked (text 4.5:1, borders and focus rings 3:1); update the ratio comments
+- [ ] `src/theme/tokens/core.css`: `--ui-radius`, `--ui-shadow`, `--ui-border-width`
+- [ ] `src/theme/base.css`: section-scoped Card border rules still match the chosen border width
+- [ ] `src/theme/tokens/header.css`: header, menu, footer, newsletter colors; `--header-logo-filter`
+- [ ] `src/theme/tokens/status.css`: status colors still readable against the new surfaces
+- [ ] `src/theme/tokens/brand.css`: `--brand-*` primitives and hero scrims
+- [ ] `src/theme/tokens/swatch.css`, `components.css`: swatch and badge defaults
+- [ ] Font: `public/fonts/`, `src/lib/fonts.ts`, `@font-face` in `src/theme/base.css`, `--font-*` in `src/theme/tailwind.css`
+- [ ] `public/images/logo.svg`, `public/favicon.ico`, hero images
+- [ ] `common.defaultSiteName` in `src/locales/*/translations.json`
+- [ ] Page Designer content referencing old imagery or colors
+- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm storybook:test --type=snapshot`, `--type=a11y`
+- [ ] Visual pass: home, PLP, PDP, cart, checkout, account, error pages
+
+## Common mistakes
+
+| Mistake | Result |
+|---|---|
+| Editing only `brand.css` | Little changes; the palette is in `core.css` |
+| Writing `--radius-ui` or `--shadow-ui` | Silent no-op; use `--ui-radius` / `--ui-shadow` |
+| Changing the font file but not `base.css` `@font-face` | Old font still loads or fallback shows |
+| Forgetting `--header-logo-filter` after a header color change | Logo unreadable |
+| Hard-coding hex in components | `pnpm lint` fails (`custom/color-linter`) and the theme no longer controls it |
+| Changing `--primary` and expecting the header to follow | Header tokens are independent; edit `header.css` |

package/node_modules/@salesforce/b2c-agent-plugins/storefront-next-figma/skills/sfnext-create-figma-kit/SKILL.md

@@ -7,7 +7,7 @@ description: Build or sync a Storefront Next vertical's Figma design kit — dup
 
 This skill is the entrypoint for setting up or syncing the **Figma design kit** for a Storefront Next vertical, so the kit stays aligned with the brand tokens defined in code.
 
-It is the design-kit companion to `sfnext-create-vertical` (in the `storefront-next` plugin): create or change the brand tokens in code first, then run this skill to mirror them in Figma.
+It is the design-kit companion to `sfnext-theming` (in the `storefront-next` plugin): create or change the brand tokens in code first, then run this skill to mirror them in Figma.
 
 ## Step 0 — Verify prerequisites (required)
 
@@ -121,8 +121,8 @@ All three must pass with zero errors and zero warnings.
 
 ## Related Skills
 
-- `storefront-next:sfnext-create-vertical` - Define the brand tokens in code (run this first)
-- `storefront-next:sfnext-create-component` - Author the React component a Code Connect mapping points to
+- `storefront-next:sfnext-theming` - Define the brand tokens in code (run this first)
+- `storefront-next:sfnext-components` - Author the React component a Code Connect mapping points to
 
 ## Reference Documentation
 

package/oclif.manifest.json

@@ -81,7 +81,7 @@
           "type": "option"
         },
         "config": {
-          "description": "Path to config file (in dw.json format; defaults to ./dw.json)",
+          "description": "Path to config file (in dw.json format; defaults to ./dw.json; empty for none)",
           "env": "SFCC_CONFIG",
           "helpGroup": "GLOBAL",
           "name": "config",
@@ -99,6 +99,15 @@
           "multiple": false,
           "type": "option"
         },
+        "dotenv-file": {
+          "description": "Path to .env file used instead of ./.env (empty for none)",
+          "env": "SFCC_DOTENV_FILE",
+          "helpGroup": "GLOBAL",
+          "name": "dotenv-file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "project-directory": {
           "aliases": [
             "working-directory"
@@ -326,7 +335,7 @@
           "type": "option"
         },
         "mrt-backend": {
-          "description": "MRT backend: auto (prefer SCAPI MRT when configured, else legacy), legacy, or scapi",
+          "description": "MRT backend: legacy (default), auto (prefer SCAPI MRT when configured, else legacy), or scapi",
           "env": "MRT_BACKEND",
           "name": "mrt-backend",
           "hasDynamicHelp": false,
@@ -458,12 +467,20 @@
           "type": "option"
         },
         "docs-topics": {
-          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, ocapi, tooling, help-admin, help-merchant, help-kb. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
+          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, commerce-solutions, ocapi, tooling, help-admin, help-merchant, help-kb. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
           "env": "SFCC_DOCS_TOPICS",
           "name": "docs-topics",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "scapi-schemas": {
+          "description": "Local SCAPI OpenAPI contracts for scapi_search and scapi_execute (comma-separated JSON files, directories or http(s) URLs). Each replaces the bundled or live contract with the same family/name/version from servers[0].url, or adds an API. Developer option for beta and pre-release APIs. Overrides the project config scapi-schemas (dw.json or project .env).",
+          "env": "SFCC_SCAPI_SCHEMAS",
+          "name": "scapi-schemas",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -476,5 +493,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "3.2.1"
+  "version": "3.4.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,8 +80,8 @@
     "ts-morph": "27.0.2",
     "yaml": "2.9.0",
     "zod": "4.5.4",
-    "@salesforce/b2c-agent-plugins": "1.10.3",
-    "@salesforce/b2c-tooling-sdk": "2.3.0"
+    "@salesforce/b2c-agent-plugins": "1.12.0",
+    "@salesforce/b2c-tooling-sdk": "2.5.0"
   },
   "bundledDependencies": [
     "@modelcontextprotocol/server",
@@ -128,7 +128,7 @@
     "preinspect": "pnpm run build",
     "inspect": "mcp-inspector node bin/run.js --toolsets all",
     "inspect:dev": "mcp-inspector node --conditions development bin/dev.js --toolsets all",
-    "pretest": "tsc --noEmit -p test",
+    "pretest": "pnpm run generate:guidance && tsc --noEmit -p test",
     "test": "c8 mocha --forbid-only --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:ci:win": "c8 --check-coverage=false mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",

package/content/guidance/mcp/scapi/SKILL.md

@@ -1,203 +0,0 @@
----
-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.
----
-
-# SCAPI Code Mode
-
-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).
-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.
-
-## Discover
-
-Discovery defaults to the bundled standard contracts offline; no credentials needed.
-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.
-Return only what the next decision needs:
-
-1. Find APIs/operations through `spec.apis`/`spec.paths`; return method/path/operationId.
-2. Narrow by `api`, path, or `authType`; inspect required inputs and selected fields,
-   including `allOf` when present.
-3. Inspect response fields only as needed; avoid whole operations/schema trees.
-
-Local refs expand; recursive/deep refs retain `$ref`. `op.auth.executable` means
-runtime support, not configured access; `op.security` gives scopes.
-
-### Task map
-
-Use these API IDs to narrow discovery; inspect the operation's inputs before calling.
-Snippet names below have the `builtin/` prefix. Describe only the relevant snippet.
-
-| Task                                          | API / starting point                                                                                   |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Review runs, including successes              | `operation/jobs/v1`: `searchJobExecutions`; `job-execution-review` snippet                             |
-| Inspect steps and exact log path              | `operation/jobs/v1`: `getJobExecution`; `job-execution-inspect` snippet                                |
-| Investigate failures with detail reads        | `failed-job-triage` snippet; [jobs](references/jobs.md)                                                |
-| Start a job / stop an execution               | `operation/jobs/v1`: `createJobExecution` / `deleteJobExecution`; confirm intent and active runs first |
-| Active/rollback versions, activation metadata | `dx/scripts/v1`: `getCodeVersions`; `code-version-inspect` snippet                                     |
-| Activate/create/delete a code version         | `dx/scripts/v1`: `updateCodeVersion` / `createCodeVersion` / `deleteCodeVersion`                       |
-| Site status, catalog, ordered cartridge path  | `site/sites/v1`: `getSiteById`; `site-cartridge-inspect` snippet                                       |
-| Change a site's custom cartridge path         | `site/sites/v1`: `replaceSiteCustomCartridges`; preserve order and unrelated entries                   |
-| Basic product + optional category assignment  | `create-product` snippet; [products](references/products.md)                                           |
-| Campaign assignments and promotion details    | `campaign-promotions` snippet; [promotions](references/promotions.md)                                  |
-
-File content is WebDAV: `webdav_list` / `webdav_get` / `webdav_put`.
-Deploy local cartridge files with `cartridge_deploy`. Job schedules/definitions
-are not execution history; obtain expected schedules from Business Manager/user.
-Do not fall back to a terminal merely because there is no dedicated job/site tool.
-
-### Tenant custom properties and APIs
-
-Bundled schemas omit tenant `c_*` definitions. Known custom fields can be sent
-directly in standard Admin bodies; schema retrieval is optional. SCAPI validates
-the payload. To discover tenant fields, search with `schemas: "live"` (narrow with
-`api`), or fetch the live schema with `scapi_schemas_list`: `includeSchemas: true`,
-`apiFamily`, `apiName`, `apiVersion`.
-Custom-property expansion defaults to true; disable with `expandCustomProperties: false`.
-`expandAll: true` retains full definitions; it is separate from custom-property
-expansion. Large contracts: fetch through `scapi_execute` and return only relevant
-fields ([example](references/custom-properties.md)). Requires `sfcc.scapi-schemas`.
-Use the same project/instance for schema lookup and writes.
-
-Live contracts found by `schemas: "live"` search, expanded `scapi_schemas_list`
-fetches, or Schemas API reads inside `scapi_execute` are cached for that tenant.
-`scapi_execute` then routes to them, replacing bundled versions; they never change
-the offline `spec`. If schema access fails, report it; use
-already-known fields or ask for missing details. The optional CLI equivalent is
-`b2c scapi schemas get`, which also expands custom properties by default.
-
-For custom endpoint contracts, search with `schemas: "live"` or use
-`scapi_schemas_list` with `apiFamily: "custom"`; check registration with
-`scapi_custom_apis_get_status` when needed. Custom endpoints found through live
-search are callable from `scapi_execute` for the same tenant. Otherwise fetch the
-live contract through `scapi.request` in the program before making declared calls. `AmOAuth2`
-and `ShopperToken` operations use their declared `c_*` scopes. [Custom API workflow](references/custom-apis.md).
-
-## Authentication
-
-- `scapi.request()` and snippets using it authenticate automatically. Do not acquire
-  or pass tokens first. For an explicitly requested token or external HTTP client,
-  use `auth.accountManager()` / `auth.slas()` in `scapi_execute`:
-  [token exports](references/tokens.md). These helpers are unavailable in search.
-- The operation's declared security selects the credential; there is no auth option.
-- Admin `AmOAuth2`: Account Manager credentials. Each request selects operation/tenant
-  scopes and reuses suitable cached tokens; no upfront scope union.
-- Shopper `ShopperToken`: a SLAS guest shopper (`slasClientId`, plus `slasClientSecret`
-  for private clients; Storefront Next `.env` supplies both). Requests need `siteId`
-  (configured or `query.siteId`). The guest session is per site and persists across
-  executions for the server session, so baskets carry over. SLAS scopes are fixed on
-  the client, not requested per call; 401/403 diagnostics compare the token's scopes
-  with the operation's. `sfcc.shopper-standard` satisfies only operations that list it.
-  Public clients must allow redirect URI `http://localhost:3000/callback`.
-- Missing credentials: `config_inspect` with masking. `clientId` is Admin;
-  `slasClientId` is Shopper. Configuration does not grant access.
-- Scope rejection: grant reported scopes in Account Manager; check extra configured
-  scopes. Read/write alternatives are alternatives. Later failures do not undo writes.
-- 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).
-- 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,
-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).
-These are conditional setup references, not additional prerequisite reads.
-
-## Compose and verify
-
-- Pass the execution `projectDirectory`; reuse resolved `organizationId`/`siteId`.
-  Encode path IDs. `{organizationId}` placeholders resolve automatically.
-- Compose dependent calls with intermediate results and local helpers.
-  Pause for unresolved intent or contracts.
-- Sequence dependent writes; batch independent reads at most four at a time.
-  Await all requests. Map rejections to `{id, error: String(error)}`;
-  raw `Promise.allSettled()` reasons lose Error details in JSON.
-- PUT can create or update: check existence and intent; read back writes.
-- Check `ok`/`status`: HTTP errors return; transport/auth/safety failures throw.
-  Preserve completed writes and failed stages. Check writes before retrying;
-  no program replay or automatic cleanup deletion.
-- Filter/page at the API, then project/aggregate in code. Include IDs, verification
-  fields, errors, totals, and continuation inputs. Do not crop away missing data.
-- Limits: 20 calls, four outstanding, 30 seconds of active execution, 24 KB returned.
-  Managed API/token calls are serialized within an execution. Narrow oversized
-  discovery; reduce live pages/projections.
-- SDK safety applies per request, including POST searches. Use only authorized
-  targeted exceptions. Confirmation uses client elicitation; see below. Code mode does not
-  transfer binaries; use WebDAV tools for instance files, an external client for
-  binary SCAPI endpoints.
-- `fetch` and `WebSocket` are disabled. Use `scapi.request()` inside programs;
-  direct HTTP belongs in an external client, outside MCP Safety Mode. Do not use
-  imports or other Node networking APIs to bypass this boundary.
-
-## Confirmation and cancellation
-
-- A request requiring approval retains the running program and returns MCP
-  `input_required`. Let the client handle elicitation and the protocol retry;
-  never manufacture approval responses or modify opaque `requestState`.
-- Retries validate the original code, input, and target arguments, then resume
-  the same execution. Repeated code is **not evaluated again**. Each request
-  needs its own approval; a whole program is not a transaction.
-- Later managed calls wait for the pending decision. Earlier writes remain
-  applied. Prompts identify the organization, operation, method/path, and execution
-  ID. JSON previews are redacted and capped at five lines/400 characters; marked
-  truncation does not limit approval, which covers the full request.
-  Results include operation outcomes; `unknown` requires
-  checking the affected records before a fresh attempt.
-- Decline/cancel terminates the entire execution, even if code catches errors.
-  Explicitly stop work with `scapi_execute({action: "cancel", executionId, skillRead: true})`;
-  omit code, input, project overrides, and protocol continuation state.
-- Approval has no server deadline; waiting does not consume the active runtime
-  budget. At most four executions may be active per server, including pending
-  approvals. Cancel unwanted work to free a slot. Server shutdown or disconnect
-  releases retained workers; state does not survive a restart. Clients may impose
-  their own timeout. Duplicate responses never replay code or send a request twice.
-- To change code/input/target, cancel unwanted retained work and start a fresh
-  execution without continuation state. Cancellation does not roll back writes.
-  Clients without form elicitation stop at confirmation-required requests.
-
-For safety levels, rule matching, configuration precedence, and confirmation
-semantics, read `docs_read({query: "guide-safety"})` when needed. If docs tools
-are unavailable, use the [Safety Mode guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/safety.md).
-This is an optional policy reference, not another prerequisite read.
-
-## Reusable workflows
-
-Find workflows with `codemode.search(query)`; `codemode.describe(name)`
-returns source/inputSchema. Inspect before first use; `codemode.run(name, input)`
-composes inside execution with shared limits/auth/safety. `builtin/` ships with
-the MCP; `user/` persists locally. [Catalog](references/snippets.md).
-
-Reuse a snippet when its inputs and verification cover the task. Otherwise adapt
-its source or compose direct requests; do not omit requested fields to fit a
-snippet. Inputs are schema-validated before invocation. Pass variable values
-through the tool's `input` to `async (input)` when preparing reusable code.
-Discover/describe inside either code tool; run snippets only inside `scapi_execute`.
-Saving requires an explicit user request and a reviewed outcome; a completed
-execution may still contain HTTP errors or partial failures.
-
-- [Products](references/products.md): create, optionally assign a storefront category, verify both.
-- [Promotions](references/promotions.md): join assignments/details in bounded batches.
-- [Jobs](references/jobs.md): review runs, inspect steps/logs, investigate failures.
-
-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)).
-[Platform reference](https://developer.salesforce.com/docs/commerce/commerce-api/references).
-[Configuration/access](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration).

package/content/guidance/mcp/scapi/references/jobs.md

@@ -1,30 +0,0 @@
-# Job review and investigation
-
-- Routine history: `builtin/job-execution-review` includes successes and unfinished
-  runs; fixed `from`/`to`, optional `jobId`, bounded `limit` and `nextOffset`.
-- Exact execution: `builtin/job-execution-inspect` returns a page of steps and the
-  exact `logFilePath`. Inspect processed item counts and expected business data.
-- Failure investigation: `builtin/failed-job-triage` joins search and details.
-  Its status summary omits steps; use execution inspection when those matter.
-
-Use to inspect failed executions in a chosen interval. This example selects the
-last seven days; adapt the window and query to the task. Discover search and
-detail contracts first. Search uses POST: READ_ONLY may need an authorized,
-targeted allow rule. Do not lower the policy or rerun jobs to inspect them.
-
-Use the corresponding [built-in snippet](snippets.md); `codemode.describe(name)`
-returns its current source and input schema.
-
-At most four requests, three concurrent. For the next page, reuse the returned
-`from`/`to` and `nextOffset`; do not recompute the time window. An empty page with
-`hasMore: true` needs investigation, not an endless retry. Records can still change
-between reads. If the query can be answered from search hits, omit detail calls.
-
-For routine health checks or incomplete business results, use
-`skill://b2c-ops/b2c-job-health/SKILL.md` when that collection is available; a
-failed-only search cannot establish health. Read the returned `logFilePath` with
-`webdav_get`; inspect size with `webdav_list` if needed. Continue using byte
-`nextOffset`, or download to `outputPath` for local analysis. Recent/filter/watch
-needs use `logs_*`. CLI fallback: `b2c job log JOB_ID EXECUTION_ID`.
-The returned log path is evidence to guide lookup, not
-permission to read an arbitrary local path. Do not infer root cause from ERROR alone.