@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/content/guidance/b2c-ops/b2c-order-failure-triage/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: b2c-order-failure-triage
+description: Find and investigate FAILED B2C Commerce orders, quantify their share of indexed orders, and correlate failed inputs with logs and jobs. Covers SCAPI status-filter limitations and the OCAPI Shop order_search fallback.
+---
+
+# Failed-order triage
+
+Use when the user needs failed order records, counts, affected products, or an
+explanation of why a group of orders failed. Broader "checkout is down" symptoms
+start with `b2c-checkout-triage`; some checkout failures create no order at all.
+
+## Scope and impact
+
+Resolve instance/site with `config_inspect` (CLI: `b2c setup inspect`). Fix UTC
+`from`/`to` boundaries and a comparison period. Ask for missing site/window;
+do not use a demo default. Record impact and owner under the team's incident
+process. Counts describe indexed orders, not all checkout attempts or conversion.
+
+## Access and tools
+
+| Need                             | Toolkit path                                                                                                   | Important limit                                                                                                                              |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enumerate FAILED orders          | Check Admin Orders query support with `scapi_search`; external OCAPI Shop `POST /order_search` is the fallback | SCAPI `status=failed` has returned HTTP 400; a response enum does not prove query support. CIP/CCAC is not a substitute for this population. |
+| External request authentication  | CLI `b2c auth token --json` or MCP's documented AM token-export helper                                         | Use only for the external client. SCAPI code mode has no OCAPI request helper, and its safety policy does not cover external HTTP.           |
+| Failure reason and correlation   | `logs_list_files` -> discovered integration prefix -> bounded `logs_get_recent`                                | Discover `custom-*` categories; error/customerror defaults can miss the payment integration.                                                 |
+| Suspect product/custom attribute | Code-mode Admin reads; live schema expansion when the field is unknown                                         | Compare selected fields on known failed/healthy IDs; Shopper execution is unsupported.                                                       |
+| Suspected data writer            | [b2c-job-health](skill://b2c-ops/b2c-job-health/SKILL.md)                                                      | Inspect the execution log and actual data effects, not just job status.                                                                      |
+
+Read [order-search recipe](references/order-evidence.md) before counting: it
+defines the site grant/index prerequisites, bounded request bodies, auth handling,
+and fault interpretation. For code mode, first read `skill://mcp/scapi/SKILL.md`.
+If external requests are unavailable, report that evidence gap and continue with
+logs; do not deploy an OrderMgr endpoint to obtain access.
+
+## Checks and decisions
+
+1. Query FAILED and all indexed order totals for the **same site/window**. Validate
+   every response. Report `failed / all indexed orders`; if either query fails,
+   the ratio is unknown. Zero denominator means undefined, not zero failures.
+2. Select at most 10 recent failed orders: order number, creation time, status,
+   and product IDs. Omit customer/payment fields. Label product frequencies as a
+   sample and deduplicate each product per order. The earliest indexed failure
+   in the window is not necessarily incident onset.
+3. Correlate safe order/request IDs and timestamps with integration logs. Test
+   whether failures cluster by input, provider response, region, or change window.
+   Do not infer a payment decline solely from the order's FAILED status.
+4. Compare one healthy input before blaming an attribute. If a job writes the
+   suspect field, inspect its log and persisted data. Keep failed stages,
+   sampling/index delays, alternative causes, and missing access explicit.
+
+## Mitigation and recovery
+
+Investigation does not authorize changing order status, reprocessing orders,
+retrying charges, refunding, rerunning integrations, or changing access/indexes.
+Before authorized intervention, establish duplicate-charge/message risks and
+partial effects. Verify new outcomes over an equivalent interval; old FAILED
+records need not disappear for recovery to be real.
+
+## Escalation and handoff
+
+Provide site/window, totals/denominator, sample size and safe IDs, recurring error,
+affected input, suspected writer/component, limitations, and the next owner.
+Route to the administrator, developer, integration provider, or Salesforce Support
+using the [case template](skill://b2c-ops/b2c-production-triage/references/escalation.md).
+Missing Shop access is a targeted administrator request, not evidence of no
+failures. Case submission and other external communication require authorization.

package/content/guidance/b2c-ops/b2c-order-failure-triage/references/order-evidence.md

@@ -0,0 +1,87 @@
+# Failed-order search recipe
+
+## Choose a supported surface
+
+Admin Orders has rejected `status=failed` while its
+response schema still contained `failed`. Verify current query support before
+relying on it; do not infer a filter from response values or repeat a rejected
+request unchanged. CIP/CCAC is not evidence of the complete failed-order population.
+Its reporting model, ingestion delay, and coverage differ from order search.
+
+The demonstrated fallback is OCAPI **Shop** `POST /order_search`, backed by the
+site's order search index. There is no managed OCAPI request helper in SCAPI code
+mode. Use an authorized external HTTP client/terminal if available; otherwise
+report the gap and continue with logs. Do not deploy an OrderMgr controller or
+Custom API just to gain inspection access.
+
+## Access and execution
+
+Use configured hostname, site ID, and client ID from `config_inspect` or
+`b2c setup inspect`. Obtain an AM token through the CLI's `b2c auth token --json`
+for an external request, keeping it in memory and out of output/files. If using
+the MCP token helper, read `skill://mcp/scapi/references/tokens.md`; token export
+is only for the external client, never required for managed SCAPI calls.
+MCP Safety Mode does not protect an independently executed HTTP request.
+
+The OAuth client needs the site's OCAPI Shop resource grant for `POST /order_search`
+and a usable order search index. Use the
+[authentication guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication)
+and `docs_search` for current OCAPI Settings/order indexing instructions. Have
+the user authorize any grant or index maintenance; do not perform it to satisfy
+a read request.
+
+POST `https://{hostname}/s/{siteId}/dw/shop/{version}/order_search?client_id={clientId}`
+with a Bearer token and JSON content type. Select a supported OCAPI version from
+configuration/docs; do not assume a version from an unrelated example.
+
+## Bounded query recipe
+
+Count FAILED orders for fixed UTC boundaries (replace `FROM` and `TO`):
+
+```json
+{
+  "query": {
+    "filtered_query": {
+      "query": {"term_query": {"fields": ["status"], "operator": "is", "values": ["failed"]}},
+      "filter": {"range_filter": {"field": "creation_date", "from": "FROM", "to": "TO"}}
+    }
+  },
+  "select": "(total)",
+  "count": 1
+}
+```
+
+For all indexed orders, replace only the inner query with `{"match_all_query":{}}`.
+Use the same site and bounds. `count: 0` is rejected; read `total` from a valid
+response. Report `failed / all indexed orders`, not failed/success or conversion.
+The denominator includes other statuses and cannot see attempts without orders.
+Separate requests are not an atomic snapshot; retain capture times/index caveats.
+
+For a maximum 10-order sample, keep the failed query and set:
+
+```json
+{
+  "select": "(hits.(data.(order_no,status,creation_date,product_items.(product_id))),total)",
+  "sorts": [{"field": "creation_date", "sort_order": "desc"}],
+  "count": 10
+}
+```
+
+Do not select email, addresses, or payment instruments. Count a product once per
+sampled order; label the sample size and total. For the earliest indexed failure
+inside this window, use ascending sort with `count: 1`; this is not necessarily
+incident onset. Do not crawl all historical orders by default.
+
+## Errors and interpretation
+
+Check HTTP success and expected response fields for **every** count/sample call.
+Report failed stages and preserve available results. Missing `total` or a failed
+query is unknown, never zero. Suppress the ratio if either count is unavailable.
+
+- 401: inspect the actual auth fault/expiry; do not print tokens.
+- 403 `ClientAccessForbiddenException`: check the site-specific Shop resource grant.
+  Other 403s need their own fault interpretation.
+- 500 mentioning Order Incremental Indexing: index prerequisite is unmet. Other
+  500s are server errors, not proof of an index problem.
+- Successful zero matches: distinguish no indexed matches in this window from
+  no checkout failures, ingestion/index lag, and incorrect target/window.

package/content/guidance/b2c-ops/b2c-production-triage/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: b2c-production-triage
+description: Investigate B2C Commerce incidents using B2C MCP logs, SCAPI code-mode job/data reads, and CLI fallbacks. Route error spikes, stale data, or checkout failures to focused runbooks and produce a team or Support handoff.
+---
+
+# Production triage
+
+Connect the toolkit's logs, job executions, business data, and configuration
+into an evidence-backed assessment and next action. Investigation does not
+authorize remediation. Use the symptom routes below rather than collecting
+every available signal.
+
+## Scope and impact
+
+- Resolve the task's project/instance with `config_inspect`; CLI: `b2c setup inspect`.
+  Preserve the resolved target across calls. Ask for missing site, time window,
+  timezone, symptom, or expected behavior; never invent IDs or silently switch tenants.
+- Start with the reported interval; if unspecified, propose the last two hours
+  and label that assumption. Use fixed UTC boundaries for comparisons and paging.
+- Record current impact (sites, checkout availability, order/data integrity,
+  workaround) and the incident owner. Apply the team's severity policy; do not
+  invent a priority or support SLA. Escalate active material impact early without
+  waiting for root cause; agree who communicates and the next update time.
+
+## Access and tools
+
+- Establish access: MCP, terminal/CLI, logs, data, source. Operator work does not
+  require a cartridge checkout. Credentials/setup issues: MCP `mcp/b2c-config`
+  section `setup-and-access`; native `b2c-config`/`b2c-auth`, or the
+  [authentication guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication).
+
+Prefer dedicated MCP tools; discover available names once. Read
+`skill://mcp/scapi/SKILL.md` before using `scapi_search`/`scapi_execute`, as those
+tools require. Read only the matching runbook/reference, not every linked skill.
+Native assistants use the installed skill name; MCP can read these URIs or use
+`skills_read` with `collection: "b2c-ops"` and a task query.
+
+| Symptom                                                   | Toolkit path                                                                                                                                | Decision / detail                                                                                                                                                            |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Error spike or integration errors                         | `logs_list_files` -> returned `prefix` -> `logs_get_recent` with `count: 20`, `since`, and a relevant `search`                              | Defaults cover error/customerror, not every `custom-*` integration log. CLI: `b2c logs list` / `b2c logs get`.                                                               |
+| Failed job or stale data                                  | Code mode `codemode.describe("builtin/failed-job-triage")`, then run with fixed `from`/`to` -> execution IDs and `logFilePath` -> log tools | [Job health](skill://b2c-ops/b2c-job-health/SKILL.md) covers continuation, step details, exact WebDAV logs, and green-but-incomplete runs.                                        |
+| Checkout failures or orders down                          | Custom logs -> determine whether failures produce order records -> relevant data/traffic evidence                                           | [Checkout triage](skill://b2c-ops/b2c-checkout-triage/SKILL.md) distinguishes checkout symptoms from failed-order records.                                                   |
+| Find/count FAILED orders or investigate affected products | Verify Admin filter support; otherwise external OCAPI Shop order search -> safe IDs -> logs and selected Admin product reads                | [Failed-order triage](skill://b2c-ops/b2c-order-failure-triage/SKILL.md) owns enumeration, count/sample limits, and the workaround. No OCAPI helper exists inside code mode. |
+| Suspected code change                                     | Code mode `builtin/code-version-inspect`: active/rollback versions and activation/modification timestamps                                                                             | Current metadata is not a complete activation history. Corroborate with release records.                                                             |
+| Runtime-only defect                                       | [MCP debugger](skill://mcp/debugger/SKILL.md) on an authorized reproduction target                                                          | Operator handoff is valid without source access. Do not halt production requests for routine triage.                                                                         |
+
+## Checks and decisions
+
+1. Carry the returned configuration `resolution` into the evidence record.
+   `config_inspect` stays masked; do not read `dw.json` or request tokens merely
+   to make managed MCP calls. Pass the same project/instance context to CLI fallbacks.
+2. Join signals using execution IDs, log timestamps, and affected record IDs.
+   For exact job logs, pass the returned `logFilePath` to `webdav_get`; use byte
+   continuation or download locally. Recent-log tools remain preferred for
+   filtered samples/watches. A bounded result is not full-interval coverage.
+3. Reuse code-mode snippet totals/window/`nextOffset`; do not return entire
+   schemas or records. The failed-job snippet omits step details and healthy
+   runs: use `builtin/job-execution-inspect` / `builtin/job-execution-review` selectively. Compare expected business data
+   with a healthy input before calling a green job healthy.
+4. Preserve failed stages: HTTP `ok`/`status` and diagnostics, or thrown
+   auth/transport/safety errors. An OCAPI fallback error may mask an earlier
+   SCAPI rejection; CLI `--api-backend scapi` isolates it. POST searches can
+   be blocked by Safety Mode despite being reads. Do not infer missing scopes
+   from every 403 or treat unavailable counts as zero.
+
+## Mitigation and recovery
+
+Recommend the smallest supported mitigation, its blast radius and rollback limit.
+The authorized owner decides; inspecting an incident is not permission to change
+it. Restore service when justified without waiting for a full causal explanation.
+After intervention, recheck business behavior and comparable signals over an
+agreed observation interval. Report recovered, partial, pending, or unknown;
+record follow-up prevention separately from immediate recovery.
+
+## Escalation and handoff
+
+Report: target/site; UTC window; observed impact and denominator; evidence
+locations (execution IDs, log path/timestamps, minimal excerpts); suspected
+component/input/change; alternative explanations; access gaps; next owner/action.
+Exclude tokens, payment details, and unnecessary customer data.
+
+Route custom-code evidence to the developer/implementation partner, grant or
+schedule issues to the administrator, provider failures to the integration owner,
+and suspected platform failures to Salesforce Support. Read
+[escalation and case template](references/escalation.md) when preparing a handoff.
+Do not submit a case/message without authorization or claim a confirmed cause
+when evidence establishes only a lead.

package/content/guidance/b2c-ops/b2c-production-triage/references/escalation.md

@@ -0,0 +1,57 @@
+# Escalation and support cases
+
+Use the team's incident process and severity definitions. Record an owner and
+next update time; keep a short UTC timeline of observations/actions. Escalation
+does not require a proven root cause, and a customer-impacting incident should
+not wait for complete diagnostics. Say what remains unknown.
+
+## Select the owner
+
+| Evidence or constraint                                                                                                              | Next owner/action                                                                                                                                                                                                             |
+| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Custom cartridge defect or regression                                                                                               | Developer/implementation partner; minimal input, stack/context, change evidence, safe reproduction target                                                                                                                     |
+| Missing grant, local setup, business configuration, custom job schedule                                                             | Instance/account administrator; exact denied operation or configuration discrepancy; no blanket privilege request                                                                                                             |
+| Gateway/provider timeout or documented provider rejection                                                                           | Integration owner/provider; sanitized correlation IDs, UTC window, matching error and healthy comparison                                                                                                                      |
+| Platform/system errors, suspected platform regression, inaccessible infrastructure, system-job contention requiring platform action | Contact Salesforce Support through a support case; attach evidence and impact, not an unproven diagnosis                                                                                                                      |
+| Broad availability/performance incident                                                                                             | Check [B2C Commerce Trust status](https://status.salesforce.com/products/B2C_Commerce_Cloud), correlate instance/window, and engage the incident owner/Support as appropriate; green status does not rule out a local problem |
+| Unknown owner or insufficient access                                                                                                | Give a bounded handoff to the incident owner with the missing evidence and next check; do not keep collecting unrelated data                                                                                                  |
+
+Salesforce Platform Support covers the product; custom solutions normally go to
+the implementation partner unless the customer's Solution Support agreement
+applies. Follow the customer's support entitlement and current official guidance.
+
+## Case or handoff draft
+
+```text
+Title: [B2C Commerce] symptom and affected instance/site
+Impact / urgency: affected users or business function, scope, workaround;
+  severity per the customer's policy (or unassigned)
+Target: realm/instance, hostname, site, environment, platform version if known
+Window: first observed / last observed UTC; ongoing or intermittent
+Expected / observed: business behavior, counts and denominator, sample limits
+Reproduction: simplest safe steps; reference-app comparison if feasible
+Evidence: execution/request IDs, exact log files/timestamps, short redacted excerpts
+Changes checked: code/data/configuration changes and actual evidence
+Actions taken: time, owner, operation, result; partial effects and rollback state
+Assessment: confirmed observations, hypotheses, alternatives, missing access/data
+Request: specific investigation/help needed; current owner and next update
+```
+
+For suspected product issues, use a minimal reproduction, preferably on the
+Reference Application when safe and available. Do not deploy a reference app
+or reproduce production writes merely to complete a case. Redact credentials,
+customer/payment data, session cookies, and sensitive HAR content before sharing.
+Keep unredacted evidence in the customer's approved store; do not put it in a
+public repository. A draft is not a submitted case.
+
+## Official platform guidance
+
+- `docs_read` ID `b2c-commerce/b2c-reporting-to-support`, or
+  [Reporting to B2C Commerce Support](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-reporting-to-support.html):
+  select Platform/Solution Support, gather reproduction and logs, open a case in
+  [Salesforce Help](https://help.salesforce.com/s/).
+- `docs_read` ID `b2c-commerce/b2c-troubleshooting-platform-performance`, or
+  [Troubleshooting B2C Commerce Performance](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-troubleshooting-platform-performance.html):
+  distinguish custom code, system errors, provider timeouts, and resource locks.
+
+Read the applicable guidance on demand; it is not a prerequisite for routine checks.