@salesforce/b2c-dx-mcp 2.1.1 → 3.0.0

package/content/guidance/mcp/b2c-config/SKILL.md

@@ -0,0 +1,86 @@
+---
+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.
+---
+
+# MCP Configuration
+
+For MCP installation or tool selection, see [server setup](skill://mcp/server/SKILL.md).
+
+## Inspect resolved values
+
+Call `config_inspect` directly with the task's absolute `projectDirectory`.
+No prior skill read is required. Secrets are masked by default (`unmask: false`).
+The result includes effective values, contributing sources, warnings, and
+`resolution` identifying the selected project, configuration file, and instance.
+
+Use the returned hostname, site, tenant, and other configured values. Report
+missing values rather than inventing them. Inspection does not verify remote
+credentials or connectivity.
+
+Reading `dw.json` manually is usually unnecessary: it may not be the selected
+file or contain the effective values. Avoid dumping configuration files or the
+environment to discover credentials. Inspect source files only for a requested
+edit or a specific issue the resolved output cannot explain. Set `unmask: true`
+only when the user explicitly requests secret values.
+
+## Where configuration comes from
+
+MCP tools use the same resolver as the CLI. Value precedence, highest first:
+launch overrides/environment (including project `.env`), high-priority config
+plugins, `dw.json`, `~/.mobify` (MRT key), low-priority config plugins, then
+`package.json` under `b2c` for non-sensitive defaults.
+
+- Project: per-call `projectDirectory`, then server `--project-directory` /
+  `SFCC_PROJECT_DIRECTORY`, then server working directory. The agent's project
+  may differ from the server's working directory; pass it explicitly.
+- Primary file: per-call `configPath`, startup `--config` / `SFCC_CONFIG`,
+  project `.env` `SFCC_CONFIG`, project `dw.json`, then shared global default.
+  Relative `configPath` resolves from `projectDirectory`.
+- Instance: `instanceName` selects a named instance from the primary/shared
+  catalog; otherwise configured active/default selection applies. Override only
+  to select another target; use `resolution` to confirm it.
+- Configuration files are reloaded for each configuration-dependent tool call.
+  Restart MCP after changing launch flags or its process environment. Existing
+  debugger sessions retain their selected target.
+
+## Setup and access
+
+Separate missing local values from missing external grants. `config_inspect`
+cannot create an API client, assign roles, or validate remote access. Explain the
+specific Account Manager, Business Manager, or Runtime Admin step when needed;
+changing a local scope list does not grant permission.
+
+When docs tools are available, use `docs_read({query: ID})` for these known IDs:
+
+| Need                                                 | Documentation ID / relevant topic                                 |
+| ---------------------------------------------------- | ----------------------------------------------------------------- |
+| MCP credentials or project selection                 | `mcp-configuration`                                               |
+| Configuration fields and precedence                  | `guide-configuration`                                             |
+| Account Manager client, roles, scopes, tenant filter | `guide-authentication` / Account Manager and SCAPI Authentication |
+| BM WebDAV access key or MRT API key                  | `guide-authentication` / WebDAV Access or Managed Runtime API Key |
+| Debugger permission or MCP safety restriction        | `mcp-security`                                                    |
+| SLAS client administration, when requested           | `cli-slas` / required roles and client setup                      |
+
+For another setup question, `docs_search({query: "<specific setup issue>", category: "tooling"})`,
+then read the returned ID. Use available categories; tool/topic selection can
+exclude these docs. Public links below remain alternatives. Read only relevant
+pages; follow returned `nextOffset` when the needed topic lies later in an article.
+
+## CLI, when requested
+
+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.
+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:
+
+- [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)

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

@@ -0,0 +1,86 @@
+---
+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.
+---
+
+# CIP analytics
+
+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
+`skillRead: true` to `cip_query`. Discovery needs no acknowledgment.
+
+## Choose and discover
+
+1. `cip_discover` defaults to report search; use `query` for task terms, then
+   `action: "report", name` for parameters, tables used, and available result notes. The catalog is offline.
+2. Prefer a curated report when its dimensions/filters answer the question.
+   Preview SQL with `params` only when adapting the report or checking a definition
+   absent from its notes; a standard report does not need a preview before running.
+3. For custom analysis, `action: "tables", query: "ccdw_aggr_%"` lists live metadata;
+   `action: "table", name` returns columns. Narrow names/schema and reuse findings.
+   These calls require CIP access. Columns default to 50 per page (lists: 20).
+   Follow `nextOffset` only for needed columns, not to exhaust unrelated metadata.
+4. `cip_query` accepts either `report` plus string-valued `params`, or `sql`.
+   Do not invent parameters or use a narrower report that omits requested evidence.
+
+## Configuration and access
+
+Reuse `projectDirectory` / `instanceName` and resolved configuration. Requires
+`tenantId`, Account Manager `clientId` and `clientSecret`; no instance hostname
+or SCAPI short code is needed. Authentication is managed; do not obtain tokens.
+CIP supports client credentials only, not user/SLAS/JWT flows. The client needs
+the **Salesforce Commerce API** role with the selected tenant in its tenant filter;
+the SDK requests `SALESFORCE_COMMERCE_API:<tenant>`.
+
+Tenants ending `_prd` use production analytics; other tenants use staging analytics.
+`staging: true` / `SFCC_CIP_STAGING=true` forces staging; configured `cipHost` /
+`SFCC_CIP_HOST` takes precedence. Staging analytics is a service destination,
+not permission to switch the user's target instance. Non-production data requires
+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.
+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.
+Official [JDBC setup and limits](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_access_guide.html).
+
+## Query and interpret
+
+- Fix the date window and site scope before querying. Report `from`/`to` are
+  inclusive dates. Supply required dates explicitly; do not silently use this month.
+- Warehouse numeric `site_id` differs from natural `nsite_id` (often
+  `Sites-Example-Site`) and SCAPI site IDs. Resolve through `ccdw_dim_site`;
+  do not synthesize a natural ID from a configured SCAPI site ID.
+- Prefer aggregate tables and explicit columns. Filter by date/site, group and
+  calculate in SQL, use stable ordering and LIMIT. Avoid wide `SELECT *`, large
+  fact-table joins, and repeated exploratory full-table queries.
+- `maxRows` defaults 50, maximum 500; output also caps at 24 KB. `rowCount` counts
+  returned rows, never all matches. If `truncated`, narrow/aggregate or query a
+  disjoint ordered window. No retained cursor; do not present a sample as a total.
+- Queries time out after 60 seconds by default (maximum 120). Cancellation closes
+  connections best-effort. Quota/rate/timeout errors: narrow the work; do not retry
+  in a loop. Preserve SQLState/HTTP errors and any incomplete evidence.
+- Warehouse freshness, reporting timezone, currency, and status definitions affect
+  comparisons. Query time is not data freshness. Explain unknown freshness rather
+  than treating warehouse values as live storefront truth.
+- For period AOV, divide summed revenue by summed orders; never average daily AOVs.
+  Zero orders means undefined AOV; missing dates mean no returned rows, not proven
+  zero sales. Fix complete calendar-week boundaries in the chosen timezone.
+- Safety Mode applies. CIP uses POST even for metadata and SELECT;
+  READ_ONLY can block these calls. Explain the specific restriction and use only
+  authorized, narrowly scoped exceptions. Skill acknowledgment is not authorization.
+
+Read further only for an unresolved question:
+- Sales gaps, period comparisons, or latest activity:
+  [sales interpretation](skill://b2c-cli/b2c-cip/references/SALES_ANALYSIS.md).
+- Adapting custom SQL beyond a report: read the matching section in
+  [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.

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

@@ -0,0 +1,71 @@
+---
+name: MCP Debugger Usage
+description: Bounded debugger capture, request triggering, state inspection, and reliable session cleanup.
+---
+
+# MCP Debugger Usage
+
+Use for B2C server-side script debugging. Confirm the sandbox, deployed script,
+breakpoint, and request before starting a session.
+
+## Prerequisites
+
+- Basic Auth for a BM user with `WebDAV_Manage_Customization`: username plus
+  password or WebDAV File Access and UX Studio access key. OAuth is unsupported.
+- Inspect unknown connection settings with `config_inspect` and the task's
+  `projectDirectory`; keep its default masking. Use resolved values.
+- Match local source and line numbers to deployed code and the site's cartridge
+  path. A breakpoint's `verified` flag indicates local source mapping, not that
+  matching code is deployed or active.
+
+## Capture and cleanup
+
+1. Call `debug_start_session` with `projectDirectory`. Use `configPath` or
+   `instanceName` only to override the configured selection. Cartridge discovery
+   defaults to that project; use `cartridgeDirectory` only for a different root.
+   Preserve the returned session ID and `resolution`.
+2. Call `debug_capture_at_breakpoint` with the file, line, a bounded timeout,
+   and `auto_continue: true` for a snapshot. It arms its own breakpoint; a prior
+   `debug_set_breakpoints` call is unnecessary. Use that tool for separate
+   breakpoint management; it replaces the existing set.
+3. Trigger the request. The capture tool's optional trigger supports GET without
+   custom headers; trigger authenticated or non-GET requests externally. An
+   external trigger must run while capture waits, not after awaiting its result.
+   A halted capture can return `trigger_pending: true`; resume with
+   `debug_control` with `action: continue` before expecting that request to finish. Do not retrigger it.
+4. Use captured stack, variables, and expressions. For further halted inspection,
+   use `debug_inspect` or `debug_evaluate`. Inspection returns stack and top-frame
+   variables (all scopes) by default; `include` selects stack, variables, or both.
+   Use `frame_index`, `scope`, or `object_path` for targeted inspection. Expressions
+   can have side effects; keep evaluation within the requested scope.
+5. Check halted threads with `debug_list_sessions`, resume with `debug_control` with `action: continue`,
+   and always call `debug_end_session` with `clear_breakpoints: true`, including
+   after errors or timeouts. Stop any log watches started for the investigation.
+
+## Stepping
+
+After a halt, call `debug_control` with `action: into`, `over`, or `out`, then
+`debug_wait_for_stop` before inspecting again. `action: continue` runs until the
+next breakpoint or request completion. End sessions explicitly.
+
+## Recovery
+
+- No breakpoint hit: verify deployed code, cartridge path, request, and breakpoint.
+  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).
+- 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).
+  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).

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

@@ -0,0 +1,153 @@
+---
+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 is offline; no credentials or Schemas API needed. 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, 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 reads do not change 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, use `scapi_schemas_list` with `apiFamily: "custom"`;
+check registration with `scapi_custom_apis_get_status` when needed. Execute Admin
+custom endpoints by fetching their live contract through `scapi.request` first
+in each program, then making declared calls. The read enables that contract for
+this execution only. Use `AmOAuth2` operations with their declared `c_*` scopes;
+Shopper operations remain unsupported. [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.
+- Admin `AmOAuth2`: Account Manager credentials. Each request selects operation/tenant
+  scopes and reuses suitable cached tokens; no upfront scope union.
+- 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.
+- Shopper requests through `scapi.request()` are unsupported; SLAS token export
+  is available 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 concurrent, 30 seconds, 24 KB returned. Narrow oversized
+  discovery; reduce live pages/projections.
+- SDK safety applies per request, including POST searches. Use only authorized
+  targeted exceptions. Confirmation-required requests stop. 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.
+
+## 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/custom-apis.md

@@ -0,0 +1,51 @@
+# Custom Admin APIs
+
+Custom contracts are live and tenant-specific; they are absent from offline `spec`.
+Discover with `scapi_schemas_list({apiFamily: 'custom'})`. Inspect the chosen API's
+paths, inputs, responses, and operation/root `security`. Use
+`scapi_custom_apis_get_status` for registration failures.
+
+In each execution, GET the selected contract through `scapi.request` before calling
+its endpoints. This registers the host's copy for the rest of that program only;
+reading via another tool or a previous program does not register it. Neither editing
+the returned object nor supplying a schema in a request changes the contract.
+For first use, return selected contract fields and resolve intent before writing.
+For known workflows, fetch and execute in one program; do not return the whole schema.
+
+```js
+async (input) => {
+  const api = `custom/${encodeURIComponent(input.apiName)}/${encodeURIComponent(input.apiVersion)}`;
+  const contract = await scapi.request({
+    method: 'GET',
+    path: `/dx/scapi-schemas/v1/organizations/{organizationId}/schemas/${api}`,
+  });
+  if (!contract.ok) return {stage: 'schema', ...contract};
+  // endpointPath is a previously inspected contract path with path IDs substituted.
+  const result = await scapi.request({
+    method: 'GET',
+    path: `/${api}/organizations/{organizationId}${input.endpointPath}`,
+    query: input.query,
+  });
+  if (!result.ok) return {stage: 'endpoint', ...result};
+  return {status: result.status, fields: Object.fromEntries(
+    input.fields.map(name => [name, result.data[name]])
+  )};
+}
+```
+
+- Schema lookup needs `sfcc.scapi-schemas`; execution needs the operation's declared
+  `c_*` scope and tenant scope. Managed auth requests each; `sfcc.custom-apis` is
+  for registration status, not custom business logic.
+- Only `AmOAuth2` execution is supported. A `ShopperToken` contract requires a
+  separate Shopper client; acquiring an Admin token does not enable it.
+- Paths in custom schemas are endpoint-relative (`/info`); requests use
+  `/custom/{apiName}/{apiVersion}/organizations/{organizationId}/info`.
+- Required parameters and JSON-body checks, SDK safety, cancellation, and execution
+  limits apply to schema reads and endpoint calls. Both count toward the call limit.
+- Schema fetch errors retain their HTTP status/body and access diagnostics. No
+  endpoint is enabled by a failed fetch. Unknown paths/methods are rejected.
+- For writes, verify the result before retrying and preserve completed stages.
+
+Use the same project/instance throughout. Optional CLI discovery:
+`b2c scapi schemas get custom <name> <version> --expand-all --json`.
+Authorization reference: `docs_read({query: 'commerce-api/custom-api-authentication'})`.

package/content/guidance/mcp/scapi/references/custom-properties.md

@@ -0,0 +1,43 @@
+# Live custom property definitions
+
+Use `scapi_schemas_list` for a focused schema read. When the contract is large,
+fetch and filter inside `scapi_execute` to keep it out of the conversation.
+The Schemas API requires `sfcc.scapi-schemas`; normal managed auth and safety apply.
+Known `c_*` fields work without a schema read. Discovery is optional and helps
+resolve tenant-specific names, types, and constraints.
+
+Example: find custom property definitions in the target instance's Products API.
+Pass the same `projectDirectory`/instance context as subsequent product requests.
+
+```js
+async () => {
+  const response = await scapi.request({
+    method: 'GET',
+    path: '/dx/scapi-schemas/v1/organizations/{organizationId}/schemas/product/products/v1',
+    query: {expand: ['custom_properties']},
+  });
+  if (!response.ok) return response;
+  const fields = [];
+  const pending = [{node: response.data, path: '$'}];
+  while (pending.length) {
+    const {node, path} = pending.pop();
+    if (!node || typeof node !== 'object') continue;
+    for (const [key, value] of Object.entries(node)) {
+      if (key.startsWith('c_')) {
+        fields.push({path, name: key, definition: value});
+      } else {
+        pending.push({node: value, path: `${path}/${key}`});
+      }
+    }
+  }
+  return {total: fields.length, fields: fields.slice(0, 20)};
+}
+```
+
+Narrow by field name for large customizations; follow relevant `$ref` targets and
+inspect constraints before writing. The count reports omitted matches. A field's
+presence in a response schema does not establish that it is writable: inspect the
+operation's request schema when discovering unfamiliar fields. Use fields directly in `scapi.request` bodies;
+no schema import or refresh is needed. Read back the requested fields to verify.
+
+For custom endpoint execution, see [custom APIs](custom-apis.md).

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

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

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

@@ -0,0 +1,37 @@
+# Basic product creation
+
+Use `builtin/create-product` for basic creation: required `productId` and
+`catalogId`, optional `name` (default locale), and `offline` (defaults to `true`).
+Set `offline: false` when the task calls for an online product. It sets the default
+online flag; site overrides and other availability requirements still apply.
+Use `scapi_execute` with the configured project and `skillRead: true`.
+
+The reusable sequence is inspect -> conditional write -> verify -> optional
+category assignment -> verify assignment. An existing
+product is not permission to update it. GET then PUT is not atomic: use a unique
+ID and do not assume this protects against concurrent writers.
+
+Use the corresponding [built-in snippet](snippets.md); `codemode.describe(name)`
+returns its current source and input schema.
+
+Pass `category: {catalogId, categoryId}` to also assign the new product to an
+existing category. The target catalog can differ from the product's owning
+`catalogId`; use the intended storefront catalog, not an inferred site ID.
+The workflow checks category access/existence before creating the product.
+Assignment uses the verified product ID and Catalogs API; it requires catalog
+read access and `sfcc.catalogs.rw` in addition to product permissions. Scopes are
+selected per request, so later authorization can still fail after creation.
+
+At most three requests without assignment, six with it. Read-back verifies ID, catalog, default online flag, and
+name when supplied. For additional fields or localization, adapt the source using
+the discovered API contract. This verifies saved fields, not every site's
+effective availability. For site-specific intent, inspect the selected site's
+effective state too. After an uncertain write or failed verification, inspect
+the product before retrying; do not replay creation or delete automatically.
+
+The result projects product fields and assignment IDs, verification, and write
+status; it omits expanded product data in the assignment response. `state: partial`
+retains completed product creation if assignment or its verification fails. The
+workflow is not transactional: inspect the failed stage and resume only that work.
+Rerunning creation on an existing product returns `exists` without assigning it.
+Category assignment alone does not establish storefront visibility or search indexing.

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

@@ -0,0 +1,19 @@
+# Join campaign assignments to promotions
+
+Use for inspecting a selected campaign. Replace `CAMPAIGN_ID` with an observed
+or user-selected ID; use the configured `siteId`. Discover both GET contracts
+first. This composes across API families without fetching tokens manually.
+
+Select a bounded assignment slice, deduplicate detail reads, then join the
+results locally. Keep assignment state separate from promotion state. Neither
+alone proves the effective discount; use XML archives when required settings
+are absent from the API contract.
+
+Use the corresponding [built-in snippet](snippets.md); `codemode.describe(name)`
+returns its current source and input schema.
+
+At most 13 requests, four concurrent. Detail failures remain attached to their
+promotion IDs. `nextOffset` indexes the assignment array; reuse the same campaign
+and site, adjusting the slice for another read. Concurrent assignment changes can
+shift positions. The assignment endpoint returns its full list: slicing limits
+detail requests and model output, not that first response's transfer size.

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

@@ -0,0 +1,12 @@
+# Save a reusable workflow
+
+Save only on user request with `scapi_snippet_save` and a completed `executionId`
+(last 50, current server). Verify the outcome first. Use `async (input)` and the
+tool's `input` for variable values; source must contain no credentials. Saving
+retains source/metadata only. No overwrite; choose a new name. Never replay writes
+to recover an expired execution. Saved code may reference other named snippets;
+those must still exist. Existing snippets remain runnable after restart.
+
+Declare an accurate read/write/destructive effect and JSON input schema.
+After saving, describe the named snippet to confirm its source. Discovery and
+execution remain available when scapi_snippet_save is excluded from the catalog.