@salesforce/b2c-dx-mcp 3.2.0 → 3.3.0

package/bin/run.js

@@ -4,24 +4,20 @@
  * SPDX-License-Identifier: Apache-2
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
-/* global process */
 
 /**
  * Production entry point for MCP server using oclif.
  *
  * This uses oclif's production mode which:
  * - Uses compiled JavaScript from dist/
- * - Loads .env file if present for local configuration
+ * - Loads the project .env (or --dotenv-file / SFCC_DOTENV_FILE) for local configuration
  *
  */
 
-// Load .env file if present (Node.js native support)
-try {
-  process.loadEnvFile();
-} catch {
-  // .env file not found or not readable, continue without it
-}
-
 import {execute} from '@oclif/core';
+import {preloadEnvFile} from '@salesforce/b2c-tooling-sdk/config';
+
+// Shell variables are never overridden.
+preloadEnvFile();
 
 await execute({dir: import.meta.url});

package/content/guidance/b2c/b2c-hooks/references/ORDER-HOOK-LIFECYCLE.md

@@ -165,5 +165,5 @@ alignment, or explicit recovery control matters more than atomic one-request orc
 ## Cross-References
 
 - [B2C Hooks](../SKILL.md#headless-order-payment-use-the-order-pi-authorization-seam) — primary implementation guidance
-- [b2c-ordering](../../b2c-ordering/SKILL.md) — order statuses and Shopper Orders failure handling
+- `b2c-ordering` skill — order statuses and Shopper Orders failure handling
 - [OCAPI/SCAPI Hooks reference](./OCAPI-SCAPI-HOOKS.md) — hook signature list

package/content/guidance/b2c/b2c-onboarding/SKILL.md

@@ -44,7 +44,7 @@ This onboarding skill is part of the `b2c` plugin. For a full B2C Commerce setup
 | `gemini-cli`  | `gemini extensions install https://github.com/SalesforceCommerceCloud/b2c-developer-tooling` (run in terminal, not inside the CLI) |
 | `other`       | Use the file-copy installer below |
 
-For clients without MCP-enabled plugin support, the `b2c-dx-mcp` server can be installed directly — see the [MCP installation docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation).
+For clients without MCP-enabled plugin support, the `b2c-dx-mcp` server can be installed directly — see the [MCP installation docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/installation.md).
 
 **Alternative — file-copy installer for any IDE** (also the right command to **update** already-installed skills or add a specific skill set):
 
@@ -149,6 +149,6 @@ Route by the answer:
 
 ## Reference
 
-- B2C CLI reference: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/
-- Install guide: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/install
-- Agent skills overview: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills
+- B2C CLI reference: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/index.md
+- Install guide: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/installation.md
+- Agent skills overview: https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills.md

package/content/guidance/b2c/b2c-ordering/SKILL.md

@@ -106,7 +106,7 @@ server-side phase that creates, authorizes, and performs the Commerce-side place
 or when the processor cannot participate in order-PI authorization. That hook runs inside order
 creation's transaction: do not add a nested `Transaction.wrap`, and understand that `Status.ERROR`
 rolls back the Commerce order but not an external gateway side effect. See
-[b2c-hooks](../b2c-hooks/SKILL.md#alternative-authorize-and-place-in-orderafterpost).
+"Alternative: Authorize and Place in `order.afterPOST`" in the `b2c-hooks` skill.
 
 ## OrderMgr API Reference
 
@@ -388,4 +388,4 @@ exports.createOrderNo = function() {
 
 ## Related Skills
 
-- [b2c-hooks](../b2c-hooks/SKILL.md) - Order hooks (calculate, payment, createOrderNo)
+- `b2c-hooks` skill - Order hooks (calculate, payment, createOrderNo)

package/content/guidance/b2c/b2c-querying-data/SKILL.md

@@ -252,8 +252,8 @@ These APIs hit the database directly and are expensive on high-traffic pages. Re
 
 ## Related Skills
 
-- [b2c-ordering](../b2c-ordering/SKILL.md) — Order lifecycle, status transitions, creation flows
-- [b2c-custom-objects](../b2c-custom-objects/SKILL.md) — Custom object CRUD, OCAPI search queries
+- `b2c-ordering` skill — Order lifecycle, status transitions, creation flows
+- `b2c-custom-objects` skill — Custom object CRUD, OCAPI search queries
 
 ## Best Practices
 

package/content/guidance/b2c/b2c-scapi-admin/SKILL.md

@@ -6,12 +6,12 @@ description: Build backend integrations that sync data between B2C Commerce and
 # SCAPI Admin APIs
 
 Build backend integrations or manage Commerce data through standard Admin APIs.
-Use [Shopper APIs](../b2c-scapi-shopper/SKILL.md) for storefront flows.
+Use the `b2c-scapi-shopper` skill for storefront flows.
 
 ## Tool choice
 
 When B2C MCP is available:
-- Prefer a dedicated task tool. Otherwise read `skill://mcp/scapi/SKILL.md` once
+- Prefer a dedicated task tool. Otherwise read `skill://mcp/b2c-mcp-scapi/SKILL.md` once
   through resources or `skills_read`, then use `skillRead: true`.
 - `scapi_search`: bundled standard contracts, offline. Find method/path/operationId,
   then inspect selected parameters, fields, and security scopes. Return compact projections.
@@ -47,7 +47,7 @@ an external client, token flow, or bulk import. There is no CLI code-mode equiva
 
 - [OAuth scopes](references/OAUTH-SCOPES.md): integration grants; compare with the operation's security.
 - [Integration patterns](references/INTEGRATION-PATTERNS.md): ETL, sync, bulk import.
-- [Configuration](../../../b2c-cli/skills/b2c-config/SKILL.md): CLI credentials and precedence.
+- `b2c-config` skill: CLI credentials and precedence.
 - Official docs: `commerce-api/authorization-for-admin-apis`, `commerce-api/auth-z-scope-catalog`,
   `commerce-api/timeouts-limits`, `commerce-api/throttle-rates`,
   `commerce-api/inventory-impex-best-practices`.

package/content/guidance/b2c/b2c-scapi-admin/references/CLIENT-EXAMPLES.md

@@ -49,7 +49,7 @@ b2c auth token --json
 
 > **Tenant scope is required.** For any SCAPI Admin call (system APIs *and* custom Admin APIs), the token must carry both the tenant scope `SALESFORCE_COMMERCE_API:<tenant_id>` and the API-specific scopes — see [Dual Scope Requirement](#dual-scope-requirement) below. The SCAPI subcommands (`b2c scapi custom status`, `b2c scapi schemas list`) add the tenant scope automatically; `b2c auth token` and raw curl do not.
 
-See [b2c-config skill](../../../../b2c-cli/skills/b2c-config/SKILL.md) for configuration details.
+See the `b2c-config` skill for configuration details.
 
 ### Get Token Programmatically
 
@@ -430,9 +430,9 @@ Admin APIs have lower rate limits than Shopper APIs. See `docs_read commerce-api
 
 ## Related Skills
 
-- [b2c-config](../../../../b2c-cli/skills/b2c-config/SKILL.md) - Get admin tokens via CLI
-- [b2c-scapi-shopper](../../b2c-scapi-shopper/SKILL.md) - Shopper-facing APIs
-- [b2c-scapi-schemas](../../../../b2c-cli/skills/b2c-scapi-schemas/SKILL.md) - Browse OpenAPI schemas
+- `b2c-config` skill - Get admin tokens via CLI
+- `b2c-scapi-shopper` skill - Shopper-facing APIs
+- `b2c-scapi-schemas` skill - Browse OpenAPI schemas
 
 ## Reference Documentation
 

package/content/guidance/b2c/b2c-scapi-shopper/SKILL.md

@@ -6,12 +6,12 @@ description: Call Shopper Commerce APIs (SCAPI) from headless storefronts and co
 # Shopper Commerce APIs
 
 Build storefront product, basket, checkout, customer, and context flows with SCAPI.
-For backend management use [Admin APIs](../b2c-scapi-admin/SKILL.md).
+For backend management use the `b2c-scapi-admin` skill.
 
 ## Tool choice
 
 When B2C MCP is available:
-- Read `skill://mcp/scapi/SKILL.md` once through resources or `skills_read` before
+- Read `skill://mcp/b2c-mcp-scapi/SKILL.md` once through resources or `skills_read` before
   code-mode tools; pass `skillRead: true`.
 - `scapi_search` with `authType: "shopper"` discovers bundled contracts offline.
   Find method/path/operationId first, then selected inputs, response fields, and
@@ -40,8 +40,8 @@ These schema commands use live Schemas API access; MCP discovery is offline.
 - Preserve basket/order state and handle errors explicitly. Page/filter responses
   and return only fields needed by the next operation.
 - For headless payment authorization, inspect
-  [order-PI hooks](../b2c-hooks/SKILL.md#headless-order-payment-use-the-order-pi-authorization-seam)
-  and [order lifecycle](../b2c-ordering/SKILL.md) before choosing a placement flow.
+  the order-PI hooks in the `b2c-hooks` skill ("Headless Order Payment") and the
+  order lifecycle in the `b2c-ordering` skill before choosing a placement flow.
 
 ## Conditional references
 
@@ -49,8 +49,8 @@ These schema commands use live Schemas API access; MCP discovery is offline.
 - [Checkout](references/CHECKOUT-FLOW.md): basket-to-order workflow.
 - [Common patterns](references/COMMON-PATTERNS.md): errors, pagination, field selection.
 - [Scopes](references/SCOPES.md): Shopper grants by family.
-- [SLAS](../../../b2c-cli/skills/b2c-slas/SKILL.md): CLI client management.
-- [Advanced auth](../b2c-slas-auth-patterns/SKILL.md): OTP, passkeys, session bridge.
+- `b2c-slas` skill: CLI client management.
+- `b2c-slas-auth-patterns` skill: OTP, passkeys, session bridge.
 - Official docs: `commerce-api/use-shopper-api`, `commerce-api/slas`,
   `commerce-api/work-with-baskets-orders`, `commerce-api/shopper-context-best-practices`,
   `commerce-api/auth-z-scope-catalog`, `commerce-api/performance`.

package/content/guidance/b2c/b2c-scapi-shopper/references/CLIENT-EXAMPLES.md

@@ -50,7 +50,7 @@ b2c slas client create \
   --redirect-uri http://localhost:3000/callback
 ```
 
-See [b2c-slas skill](../../../../b2c-cli/skills/b2c-slas/SKILL.md) for full client management.
+See the `b2c-slas` skill for full client management.
 
 ### Get Guest Token
 
@@ -197,8 +197,7 @@ const order = await fetch(
 > Treat the returned `NEW` order as success. On a deterministic payment failure, call
 > `POST /orders/{orderNo}/actions/fail?reopenBasket=true` with an appropriate reason code. Preserve a
 > `CREATED` order when provider state is indeterminate. See
-> [b2c-hooks](../../b2c-hooks/SKILL.md#headless-order-payment-use-the-order-pi-authorization-seam) and
-> [b2c-ordering](../../b2c-ordering/SKILL.md). Confirm version-specific request fields with the Shopper
+> "Headless Order Payment" in the `b2c-hooks` skill and the `b2c-ordering` skill. Confirm version-specific request fields with the Shopper
 > Orders schema and hook signatures with `b2c docs read commerce-api/hook-method-details`.
 
 ### Shopper Customers
@@ -338,12 +337,12 @@ Find logs in Log Center under `scapi.verbose` category.
 
 ## Related Skills
 
-- [b2c-slas](../../../../b2c-cli/skills/b2c-slas/SKILL.md) - Create and manage SLAS clients
-- [b2c-slas-auth-patterns](../../b2c-slas-auth-patterns/SKILL.md) - Advanced auth: OTP, passkeys, session bridge
-- [b2c-scapi-schemas](../../../../b2c-cli/skills/b2c-scapi-schemas/SKILL.md) - Browse OpenAPI schemas
-- [b2c-custom-api-development](../../b2c-custom-api-development/SKILL.md) - Create custom endpoints
-- [b2c-hooks](../../b2c-hooks/SKILL.md) - Order-PI authorization hooks, default placement, and the single-phase `order.afterPOST` alternative
-- [b2c-ordering](../../b2c-ordering/SKILL.md) - Order lifecycle, status transitions, and failure handling
+- `b2c-slas` skill - Create and manage SLAS clients
+- `b2c-slas-auth-patterns` skill - Advanced auth: OTP, passkeys, session bridge
+- `b2c-scapi-schemas` skill - Browse OpenAPI schemas
+- `b2c-custom-api-development` skill - Create custom endpoints
+- `b2c-hooks` skill - Order-PI authorization hooks, default placement, and the single-phase `order.afterPOST` alternative
+- `b2c-ordering` skill - Order lifecycle, status transitions, and failure handling
 
 ## Reference Documentation
 

package/content/guidance/b2c-cli/b2c-cip/SKILL.md

@@ -11,7 +11,7 @@ immediate diagnosis. If `b2c` is unavailable, use `npx @salesforce/b2c-cli`.
 ## Choose the surface
 
 - Prefer MCP `cip_discover` / `cip_query` when available. Read
-  `skill://mcp/cip/SKILL.md` before querying and pass `skillRead: true`.
+  `skill://mcp/b2c-mcp-cip/SKILL.md` before querying and pass `skillRead: true`.
   Discovery/config inspection is ungated. No terminal or token export needed.
 - Use CLI for explicit CLI requests, automation, or larger local CSV/JSON exports.
   MCP limits results to 500 rows / 24 KB; `truncated` means incomplete output,
@@ -46,7 +46,7 @@ instruction to change the target instance. Non-production data requires 26.1+
 can also need staging analytics. Dashboard: `https://ccac.stg.analytics.commercecloud.salesforce.com`.
 
 Missing configuration/availability:
-[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac).
+[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac.md) (`b2c docs read guide-analytics-reports-cip-ccac`).
 Resolution details: `b2c-cli/b2c-config`. Read only the relevant section.
 
 ## Discover and execute
@@ -111,6 +111,6 @@ Read a matching section only when the task needs it:
 - Sales comparisons, gaps, latest activity: [SALES_ANALYSIS.md](references/SALES_ANALYSIS.md).
 - Custom SQL patterns: [STARTER_QUERIES.md](references/STARTER_QUERIES.md).
 - Unknown table family: [KNOWN_TABLES.md](references/KNOWN_TABLES.md), then live metadata.
-- CLI options: [command reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cip).
+- CLI options: [command reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cip.md) (`b2c docs read cli-cip`).
 
 Stop once the requested result and material limitations are established.

package/content/guidance/b2c-cli/b2c-cip/references/SALES_ANALYSIS.md

@@ -47,4 +47,4 @@ For unresolved field meaning, consult the specific official table article:
 [sales summary](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_aggr_sales_summary.html)
 or [site dimension](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/jdbc_ccdw_dim_site.html).
 For access/availability, use the
-[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac).
+[analytics guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/analytics-reports-cip-ccac.md) (`b2c docs read guide-analytics-reports-cip-ccac`).

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

@@ -22,19 +22,26 @@ The CLI **automatically detects** instance hostname, credentials, tenant ID, MRT
 
 Sources, in resolution order (highest priority first):
 
-1. **CLI flags and environment variables** — explicit values always win. Includes `.env` files in the current project directory (auto-loaded).
+1. **CLI flags and environment variables** — explicit values always win. Shell variables win over the env file; toolkit variables (`SFCC_*`, `MRT_*`) in the project's `.env` (or the file selected with `--dotenv-file` / `SFCC_DOTENV_FILE`) come next.
 2. **Plugin sources (high priority)** — custom configuration plugins (e.g., secret managers).
-3. **`dw.json`** — selected by `--config` / `SFCC_CONFIG`, the project's `.env`, the project-local file, or the shared global `dw.json`. Supports a single instance or a `configs[]` array with `active: true` / `-i <name>` selection.
-4. **`~/.mobify`** — home-directory file (MRT API key only).
-5. **Plugin sources (low priority)**.
-6. **`package.json`** under the `b2c` key — non-sensitive project defaults (e.g., `shortCode`, `clientId`, `mrtProject`). Sensitive fields like `clientSecret`/`password` are intentionally **not** allowed here.
+3. **`dw.json`** — selected by `--config` / `SFCC_CONFIG`, the env file, the project-local file, or the shared global `dw.json`. Supports a single instance or a `configs[]` array with `active: true` / `-i <name>` selection.
+4. **Storefront Next variables** — fallbacks that only fill fields missing from the selected `dw.json` entry (see below).
+5. **`~/.mobify`** — home-directory file (MRT API key only).
+6. **Plugin sources (low priority)**.
+7. **`package.json`** under the `b2c` key — non-sensitive project defaults (e.g., `shortCode`, `clientId`, `mrtProject`). Sensitive fields like `clientSecret`/`password` are intentionally **not** allowed here.
+
+Hostname protection applies between sources: if an env file's `SFCC_SERVER` differs from the selected `dw.json` entry's hostname, that whole entry is skipped (`HOSTNAME_MISMATCH` warning). If no source sets a tenant ID and the hostname is a sandbox hostname (`abcd-001.dx.commercecloud.salesforce.com`), the tenant ID is derived (`abcd_001`); a conflicting configured tenant ID produces a `TENANT_MISMATCH` warning. Conversely, if no source sets a hostname and the tenant ID is a sandbox tenant (`abcd_001`, including a Storefront Next `f_ecom_abcd_001` organization ID), the hostname is derived (`abcd-001.dx.commercecloud.salesforce.com`).
+
+Use `--dotenv-file .env.staging` (or `SFCC_DOTENV_FILE`) to use another env file instead of `.env`; it replaces `.env` rather than layering on it. `--dotenv-file ""` uses no env file, and `--config ""` uses no `dw.json`.
 
 For unexpected values, inspect resolved configuration and sources with `config_inspect` or `b2c setup inspect`.
 
 ### Storefront Next Environment Compatibility
 
 The resolver accepts these Storefront Next variables as fallbacks, so a project
-can reuse its existing B2C Commerce and SLAS configuration:
+can reuse its existing B2C Commerce and SLAS configuration. The `PUBLIC__app__*`
+and `COMMERCE_API_SLAS_SECRET` variables rank below `dw.json`: with `-i stg`,
+stg's own tenant, short code, site, and SLAS client are kept and these only fill gaps.
 
 | Storefront Next variable                     | Resolved field     | Default toolkit variable  |
 | -------------------------------------------- | ------------------ | ------------------------- |
@@ -46,7 +53,7 @@ can reuse its existing B2C Commerce and SLAS configuration:
 | `MRT_PROJECT`                                | `mrtProject`       | `MRT_PROJECT`             |
 | `MRT_TARGET`                                 | `mrtEnvironment`   | `MRT_ENVIRONMENT`         |
 
-Explicit flags and default toolkit variables win over these fallbacks.
+Explicit flags, default toolkit variables, and the selected `dw.json` entry win over these fallbacks. `MRT_PROJECT` and `MRT_TARGET` are toolkit variables and keep toolkit priority.
 
 ### Shared Global Default
 
@@ -58,16 +65,16 @@ b2c setup default-config get
 b2c setup default-config unset
 ```
 
-The configuration-file selection order is: explicit `--config`; process `SFCC_CONFIG`; project `.env` `SFCC_CONFIG`; project-local `dw.json`; global default. The global file never replaces an explicit or project-local choice.
+The configuration-file selection order is: explicit `--config`; process `SFCC_CONFIG`; env file `SFCC_CONFIG`; project-local `dw.json`; global default. The global file never replaces an explicit or project-local choice. An explicit path (`--config` / `SFCC_CONFIG`) is used on its own, without the global file; `setup inspect` notes when the global default is skipped.
 
-The primary and global `dw.json` files form one instance catalog. `-i <name>` searches the primary file first and then the global file, with same-name primary entries shadowing global entries. Each selected instance is complete—its fields are not merged with a matching entry in the other file. Instance list/remove/set-active operate across both files; create writes to the primary file when present and otherwise to the global `dw.json`.
+A discovered project `dw.json` and the global `dw.json` form one instance catalog. `-i <name>` searches the primary file first and then the global file, with same-name primary entries shadowing global entries. Each selected instance is complete—its fields are not merged with a matching entry in the other file. Instance list/remove/set-active operate across both files; create writes to the primary file when present and otherwise to the global `dw.json`.
 
 Without `-i`, an active primary instance wins. A root-level primary configuration with no `active` field is its implicit default; set its root to `active: false` to opt it out and allow an active/default global instance to be selected. `b2c setup inspect` shows both files in its Sources section and marks the selected file.
 
 ### MCP Project Context
 
-For MCP installation or tool selection, use `mcp/server` when
-available or the [MCP configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration).
+For MCP installation or tool selection, use `mcp/b2c-mcp-server` when
+available or the [MCP configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration.md) (`b2c docs read mcp-configuration`).
 These are client launch settings; `config_inspect` reports B2C values and sources,
 not enabled toolsets or client filters. Project `.env` does not select MCP tools.
 
@@ -75,7 +82,7 @@ Local MCP project tools accept `projectDirectory`. Tools that resolve B2C/MRT co
 
 1. Parses `.env` from `projectDirectory`.
 2. Applies all supported B2C/MRT environment variables from that file.
-3. Selects a `dw.json`-format configuration file in this order: per-call `configPath`; startup `--config` / `SFCC_CONFIG`; project `.env` `SFCC_CONFIG`; `${projectDirectory}/dw.json`; shared global default.
+3. Selects a `dw.json`-format configuration file in this order: per-call `configPath`; startup `--config` / `SFCC_CONFIG`; project `.env` `SFCC_CONFIG`; `${projectDirectory}/dw.json`; shared global default. An explicit path is used without the shared global default. Storefront Next variables from the project `.env` only fill gaps below `dw.json`.
 4. Resolves relative per-call `configPath` and project `.env` `SFCC_CONFIG` values from `projectDirectory`.
 5. Selects `instanceName`, when supplied, from the primary file first and then the shared global `dw.json`, without changing either file.
 6. Continues through the normal tooling configuration sources, including registered plugin sources, MRT credentials, and `package.json`.
@@ -101,7 +108,9 @@ Field names in `dw.json` accept **both camelCase and kebab-case** — they're eq
 
 Legacy aliases like `server` (for `hostname`) are also still supported. If a value isn't being picked up, casing is rarely the cause — check spelling, then run `b2c setup inspect` to see what the CLI actually parsed.
 
-For the full field reference, see the [Configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration) (or `docs/guide/configuration.md` in the repo).
+A JSON Schema for `dw.json` is published at `https://salesforcecommercecloud.github.io/b2c-developer-tooling/schemas/dw.schema.json` (the B2C DX VS Code extension applies it automatically). Add it as `"$schema"` in a `dw.json` for editor validation and completion.
+
+For the full field reference, see the [Configuration guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.md) (`b2c docs read guide-configuration`).
 
 ## Authentication
 
@@ -227,7 +236,7 @@ b2c setup openshell --dry-run
 openshell sandbox exec -n b2c-<instance> -- b2c code list
 ```
 
-Edit `.openshell/<sandbox>/policy.yaml` and re-run to apply it; use `--recreate` after changing secrets or configuration. Add hosts with `--allow-host`. Only client credentials work in the sandbox (no browser login). See the [Agent Sandboxing guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-sandboxing#openshell).
+Edit `.openshell/<sandbox>/policy.yaml` and re-run to apply it; use `--recreate` after changing secrets or configuration. Add hosts with `--allow-host`. Only client credentials work in the sandbox (no browser login). See the [Agent Sandboxing guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-sandboxing.md#openshell) (`b2c docs read guide-agent-sandboxing`).
 
 ## Managing Instances
 
@@ -319,12 +328,13 @@ Each value shows its source in brackets:
 
 Values are resolved with this priority (highest to lowest):
 
-1. CLI flags and environment variables
+1. CLI flags and environment variables (shell, then env file `SFCC_*`/`MRT_*`)
 2. Plugin sources (high priority)
 3. dw.json file
-4. ~/.mobify file (MRT API key only)
-5. Plugin sources (low priority)
-6. package.json `b2c` key
+4. Storefront Next variables (fallbacks)
+5. ~/.mobify file (MRT API key only)
+6. Plugin sources (low priority)
+7. package.json `b2c` key
 
 When troubleshooting, check the source column to understand which configuration is taking precedence.
 
@@ -378,7 +388,7 @@ With this configuration, `b2c content list` and `b2c content export homepage` de
 ### Missing `tenantId` / `shortCode`
 
 - These resolve from `dw.json`, `SFCC_TENANT_ID`/`SFCC_SHORTCODE`, or `package.json`. Run `b2c setup inspect` to see which source provided them.
-- For sandboxes, `tenantId` is derived from the hostname (replace `-` with `_`): `zzxy-001.dx...` → `zzxy_001`.
+- For sandboxes, `tenantId` is derived from the hostname (replace `-` with `_`): `zzxy-001.dx...` → `zzxy_001`. The reverse also applies: with a sandbox tenant ID and no hostname, the hostname is derived.
 
 ### MRT commands say "API key required"
 
@@ -395,7 +405,7 @@ With this configuration, `b2c content list` and `b2c content export homepage` de
 
 ### Wrong source taking precedence
 
-- Review the priority list in "How the CLI Discovers Configuration" above. Common surprise: env vars (or a `.env` file) override `dw.json`.
+- Review the priority list in "How the CLI Discovers Configuration" above. Common surprise: env vars (or a `.env` file) override `dw.json`, and an env file `SFCC_SERVER` with a different hostname skips the `dw.json` entry entirely. Storefront Next variables never override `dw.json`.
 
 ### Still stuck
 
@@ -435,7 +445,7 @@ curl -H "Authorization: Bearer $(b2c auth token)" \
 
 The token is obtained using the `clientId` and `clientSecret` from your configuration (dw.json or environment variables). If only `clientId` is configured, or `--user-auth` is used, an implicit OAuth flow is used (browser-based).
 
-**Note:** This command returns **admin** tokens for OCAPI/Admin APIs. For **shopper** tokens (SLAS), see the [b2c-slas skill](../b2c-slas/SKILL.md).
+**Note:** This command returns **admin** tokens for OCAPI/Admin APIs. For **shopper** tokens (SLAS), see the `b2c-slas` skill.
 
 > **Calling SCAPI Admin APIs (system or custom)?** The token must carry the tenant scope `SALESFORCE_COMMERCE_API:<tenant_id>` **plus** the API-specific scopes. `b2c auth token` does not add the tenant scope for you (unlike the SCAPI subcommands such as `b2c scapi custom status`), so pass it explicitly:
 >

package/content/guidance/b2c-cli/b2c-content/SKILL.md

@@ -163,7 +163,7 @@ See `b2c content --help` for a full list of available commands and options in th
 ## Troubleshooting
 
 - **"Library is required"** -- Set `--library` flag or configure `content-library` in `dw.json`.
-- **Authentication errors** -- Inspect resolved configuration first. SCAPI needs client-credentials or JWT authentication with `sfcc.jobs.rw` and the tenant scope; browser login is OCAPI/WebDAV-only. Use `b2c-cli:b2c-auth` for setup. `--library-file` skips the remote export job; add `--offline` to skip asset downloads too.
+- **Authentication errors** -- Inspect resolved configuration first. SCAPI needs client-credentials or JWT authentication with `sfcc.jobs.rw` and the tenant scope; browser login is OCAPI/WebDAV-only. Use `b2c-cli:b2c-config` for setup. `--library-file` skips the remote export job; add `--offline` to skip asset downloads too.
 - **Library not found** -- Verify the library ID matches exactly. For site-private libraries, add `--site-library`.
 - **No content found** -- Check that the page/content IDs exist. Use `b2c content list` to discover available IDs.
 - **Timeout errors** -- Large libraries may exceed the default timeout. Use `--timeout <seconds>` to increase it.

package/content/guidance/b2c-cli/b2c-debug/SKILL.md

@@ -7,7 +7,7 @@ description: Debug B2C Commerce server-side scripts using the b2c CLI. Use this
 
 Debug server-side scripts on Salesforce B2C Commerce instances — set breakpoints, step through code, and inspect variables in SFRA controllers, hooks, jobs, and custom APIs.
 
-> Prefer MCP debugging when available: `debug_control` resumes/steps; `debug_inspect` reads stacks and variables; `debug_evaluate` evaluates expressions. See `skill://mcp/debugger/SKILL.md` for the MCP workflow. Use the CLI for a requested terminal session or when MCP is unavailable.
+> Prefer MCP debugging when available: `debug_control` resumes/steps; `debug_inspect` reads stacks and variables; `debug_evaluate` evaluates expressions. See `skill://mcp/b2c-mcp-debugger/SKILL.md` for the MCP workflow. Use the CLI for a requested terminal session or when MCP is unavailable.
 
 `b2c debug` provides a Debug Adapter Protocol (DAP) debug adapter for IDEs. For terminal or headless use without the MCP tools, `b2c debug cli` also offers an interactive REPL and a JSONL `--rpc` mode.
 

package/content/guidance/b2c-cli/b2c-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: b2c-docs
-description: Search and read B2C Commerce documentation using the b2c CLI. Covers Script API reference (dw.* classes/modules), Developer Center guides (Commerce API, PWA Kit, SFRA, Storefront Next, B2C Commerce, OCAPI), Salesforce Help (Business Manager administration and merchandising), tooling documentation (CLI/MCP/SDK), standard job steps, and XSD schemas. Use this skill for ANY B2C Commerce developer or administrator question that is not already grounded in a loaded skill or the current project context — even if they just say "how do I implement passwordless login" or "what methods does Basket have" or "how do I deploy a PWA Kit bundle" or "how do I import a site archive" or "what SCAPI endpoints are available for checkout".
+description: Search and read B2C Commerce documentation using the b2c CLI. Covers Script API reference (dw.* classes/modules), Developer Center guides (Commerce API, PWA Kit, SFRA, Storefront Next, B2C Commerce, Commerce Solutions, OCAPI), Salesforce Help (Business Manager administration and merchandising), tooling documentation (CLI/MCP/SDK), standard job steps, and XSD schemas. Use this skill for ANY B2C Commerce developer or administrator question that is not already grounded in a loaded skill or the current project context — even if they just say "how do I implement passwordless login" or "what methods does Basket have" or "how do I deploy a PWA Kit bundle" or "how do I import a site archive" or "what SCAPI endpoints are available for checkout".
 ---
 
 # B2C Docs Skill
@@ -114,7 +114,7 @@ The docs search understands which workspace framework your project uses and auto
 
 **Category boost mapping:**
 
-- Always relevant (any workspace): `b2c-commerce`, `ocapi`, `tooling`
+- Always relevant (any workspace): `b2c-commerce`, `commerce-solutions`, `ocapi`, `tooling`
 - `cartridges` → `script-api`, `job-step`
 - `sfra` → `sfra`
 - `pwa-kit-v3` → `pwa-kit-managed-runtime`, `commerce-api`
@@ -239,6 +239,7 @@ xmllint --schema "$(b2c docs schema catalog --path)" my-catalog.xml --noout
 | `sfra`                    | Storefront Reference Architecture (SFRA) guides                                                                                  | `sfra/controllers-and-routes`                       |
 | `sfnext`                  | Storefront Next guides                                                                                                           | `sfnext/sfnext-get-started`                         |
 | `b2c-commerce`            | General B2C Commerce platform guides                                                                                             | `b2c-commerce/business-manager-overview`            |
+| `commerce-solutions`      | B2C Commerce Solutions — bot management, caching strategies, flash-sale traffic, and industry solutions                          | `commerce-solutions/bot-management`                 |
 | `ocapi`                   | OCAPI reference — usage, hooks, settings, and best practices for the Open Commerce API                                           | `ocapi/ocapisettings`, `ocapi/bestpractices`        |
 | `tooling`                 | B2C CLI reference, guides, MCP docs, SDK guidance, and VS Code extension docs                                                    | `guide-authentication`, `cli-jobs`                  |
 | `job-step`                | Standard (system) job step catalog                                                                                               | `ImportCatalog`, `ExportCatalog`, `job-steps`       |
@@ -275,6 +276,26 @@ xmllint --schema "$(b2c docs schema catalog --path)" my-catalog.xml --noout
 | `coupon`    | Coupon codes import/export    |
 | `jobs`      | Job step definitions          |
 
+## Finding CLI Commands
+
+`b2c docs search` searches documentation. To find **which `b2c` command performs a task**, search the CLI's own commands instead:
+
+```bash
+b2c commands search "deploy cartridges"
+b2c commands search "environment variables" --topic mrt --json
+```
+
+## Reading Agent Skills
+
+The CLI bundles its agent skills (workflow guides like this one). Read the skill for a command or topic, or search them, without installing a plugin:
+
+```bash
+b2c docs skill                          # list b2c-cli skills
+b2c docs skill code deploy              # skill covering a command or topic
+b2c docs skill --search "site import"   # search skills
+b2c docs skill --all --search "hooks"   # include b2c, b2c-ops, storefront-next
+```
+
 ## More Commands
 
 See `b2c docs --help` for a full list of available commands and options.

package/content/guidance/b2c-cli/b2c-ecdn/references/ADVANCED.md

@@ -43,7 +43,7 @@ b2c ecdn mrt-rules delete --zone my-zone
 
 Code upload certificates enable two-factor (mTLS) code upload to staging instances (`_stg` tenants only). There are two kinds: CAs registered with eCDN for the tenant (typically one, but several can be active, e.g. during renewal), which only sign certificates; and client certificates (`.p12`) signed by a CA (typically one per CI pipeline or developer, any number allowed), which the CLI sends on code upload. CI pipelines are the primary use case. Use `create --generate --name <ca-label> --client-name <pipeline>` once to create + register the CA and issue the first (CI) client cert, then `issue` for each additional pipeline/developer. `setup` is a guided, interactive version of `create --generate` with defaults and an optional dw.json update. `create` with `--certificate-file`/`--private-key-file` registers a bring-your-own CA. The code upload hostname is provisioned by Salesforce and linked automatically; users don't configure it. The CA private key must be kept secret (treat like a password); the CA certificate bundle must have a maximum validity of 1 year and be renewed before expiry. On Hyperforce, use the `staging-<realm>-<customer>.demandware.net` code upload hostname (not legacy `cert.staging.*`).
 
-For the complete workflow, security guidance, and renewal instructions, see [Deploying to Hyperforce: Set Up Two-Factor Code Upload](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/hyperforce#set-up-two-factor-code-upload).
+For the complete workflow, security guidance, and renewal instructions, see [Deploying to Hyperforce: Set Up Two-Factor Code Upload](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/hyperforce.md#set-up-two-factor-code-upload) (`b2c docs read guide-hyperforce`).
 
 ```bash
 # typically once per tenant: generate + register CA, issue first client cert (e.g. for CI)

package/content/guidance/b2c-cli/b2c-job/references/IMPORT.md

@@ -2,7 +2,7 @@
 
 ### Import Site Archives
 
-The `job import` command waits for the import job to complete by default. The same command imports a **job definition** (`jobs.xml` at the archive root) that registers a new runnable job on the instance — for the `jobs.xml` structure (job/flow/step, step `type`, the required `<triggers>` element), see the [jobs.xml Reference](../../../../b2c/skills/b2c-custom-job-steps/references/JOBS-XML.md).
+The `job import` command waits for the import job to complete by default. The same command imports a **job definition** (`jobs.xml` at the archive root) that registers a new runnable job on the instance — for the `jobs.xml` structure (job/flow/step, step `type`, the required `<triggers>` element), see the jobs.xml reference in the `b2c-custom-job-steps` skill.
 
 ```bash
 # import a local directory as a site archive (waits for completion by default)

package/content/guidance/b2c-cli/b2c-metrics/SKILL.md

@@ -312,4 +312,4 @@ All operations accept `(client, tenantId, options?)` and return `Promise<Metrics
 - **404/category not enabled**: the category may not be enabled for your organization (closed beta)
 - **503/temporarily unavailable**: metrics service may be temporarily unavailable
 
-For full command reference, use `b2c metrics --help` and see [CLI docs](/cli/metrics) and [Metrics Guide](/guide/metrics).
+For full command reference, use `b2c metrics --help` and see [CLI docs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/metrics.md) (`b2c docs read cli-metrics`) and [Metrics Guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/metrics.md) (`b2c docs read guide-metrics`).

package/content/guidance/b2c-cli/b2c-mrt/SKILL.md

@@ -19,8 +19,8 @@ Run `b2c setup inspect` to see the resolved configuration and which source provi
 
 Most MRT commands run against the legacy MRT Cloud API (API key). Several commands can also run over the SCAPI MRT backend: `mrt bundle history`, `mrt bundle list`, `mrt bundle deploy` (both the local-build push and deploying an existing `<bundleId>`), and the `mrt env var` family (`list` / `set` / `push` / `delete`). Choose with `--mrt-backend` (`MRT_BACKEND` / `SFCC_MRT_BACKEND`, or `mrtBackend` in `dw.json`):
 
-- `auto` (default) — use SCAPI when it's configured (`--short-code` + `--tenant-id` + client-credentials or JWT Bearer auth), otherwise legacy. Falls back to legacy on safe pre-execution errors. Each command requests its own scopes: bundle commands use `sfcc.storefront.deployments[.rw]`; env var commands use `sfcc.storefront.environments[.rw]` (reads accept either tier, writes require `.rw`).
-- `legacy` — always the MRT Cloud API.
+- `legacy` (default) — always the MRT Cloud API.
+- `auto` — use SCAPI when it's configured (`--short-code` + `--tenant-id` + client-credentials or JWT Bearer auth), otherwise legacy. Falls back to legacy on safe pre-execution errors. Each command requests its own scopes: bundle commands use `sfcc.storefront.deployments[.rw]`; env var commands use `sfcc.storefront.environments[.rw]` (reads accept either tier, writes require `.rw`).
 - `scapi` — always SCAPI, with no fallback; errors if prerequisites are missing. Also errors on unsupported commands (every MRT command except the bundle and env var commands above).
 
 Notes:
@@ -183,7 +183,7 @@ Configure MRT settings in your project's `dw.json`:
 export MRT_API_KEY=your-api-key
 export MRT_PROJECT=my-storefront
 export MRT_ENVIRONMENT=staging
-export MRT_BACKEND=auto        # auto (default) | legacy | scapi
+export MRT_BACKEND=legacy      # legacy (default) | auto | scapi
 ```
 
 ### ~/.mobify Config

package/content/guidance/b2c-cli/b2c-scapi-custom/SKILL.md

@@ -9,7 +9,7 @@ Use the `b2c` CLI plugin to manage SCAPI Custom API endpoints and check their re
 
 When B2C MCP is available, prefer `scapi_custom_apis_get_status` for registration
 and `scapi_schemas_list` for live contracts. For Admin custom API execution, read
-`skill://mcp/scapi/SKILL.md`; fetch the contract through `scapi.request` in the
+`skill://mcp/b2c-mcp-scapi/SKILL.md`; fetch the contract through `scapi.request` in the
 program before calling its endpoints. Schema reads need `sfcc.scapi-schemas`;
 execution needs the declared `c_*` scope. Shopper execution is unsupported.
 

package/content/guidance/b2c-cli/b2c-scapi-schemas/SKILL.md

@@ -10,7 +10,7 @@ Browse standard or tenant-specific SCAPI OpenAPI contracts.
 ## Tool choice
 
 When B2C MCP is available, prefer `scapi_search` for Admin and Shopper contracts.
-Read `skill://mcp/scapi/SKILL.md` via resource or `skills_read` first; pass
+Read `skill://mcp/b2c-mcp-scapi/SKILL.md` via resource or `skills_read` first; pass
 `skillRead: true`. Discover method/path/operationId, then selected inputs and
 fields. The default searches bundled standard contracts offline; `schemas: "live"`
 searches the tenant's contracts (custom attributes, custom APIs, newer APIs) and

package/content/guidance/b2c-cli/b2c-site-import-export/SKILL.md

@@ -48,7 +48,7 @@ review and trim before committing, preserving XSD-required fields.
 - Archive layout and XML workflows: [archive workflows](references/WORKFLOWS.md).
 - Attribute/type XML patterns: [metadata XML](references/METADATA-XML.md).
 - Remote imports, size splitting, and import-set options: [import options](references/IMPORT-OPTIONS.md).
-- Export flags, data units, and compact JSON results: [export reference](../b2c-job/references/EXPORT.md).
+- Export flags, data units, and compact JSON results: the export reference in the `b2c-job` skill.
 - Ordered migrations, naming, history, and recovery: `b2c-cli:b2c-import-set-migrations`.
 - Service configuration XML: `b2c:b2c-webservices`.
 

package/content/guidance/b2c-cli/b2c-sites/SKILL.md

@@ -95,7 +95,7 @@ Site reads and cartridge-path writes run over SCAPI (the `site/sites` API) when
 ```bash
 b2c sites list
 # then use the ID in other commands
-b2c site-import upload --site RefArch ...
+b2c job export --site RefArch --site-data content,site_preferences
 ```
 
 **Checking site status:** The status column shows the storefront status (online/offline) for each site, useful for verifying deployment state.

package/content/guidance/b2c-cli/b2c-slas/SKILL.md

@@ -7,7 +7,7 @@ description: Create, update, and manage SLAS (Shopper Login and API Access Servi
 
 Use the `b2c` CLI plugin to manage SLAS (Shopper Login and API Access Service) API clients and credentials.
 
-> **Important:** SLAS is for **shopper** (customer) authentication used by storefronts and headless commerce. For **admin** tokens (OCAPI, Admin APIs), use `b2c auth token` - see [b2c-config skill](../b2c-config/SKILL.md).
+> **Important:** SLAS is for **shopper** (customer) authentication used by storefronts and headless commerce. For **admin** tokens (OCAPI, Admin APIs), use `b2c auth token` - see the `b2c-config` skill.
 
 > **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli slas client list`).
 

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

@@ -29,9 +29,9 @@ update process for live customer impact; do not wait for exact counts to escalat
 | Order records                | Discover Admin Orders contracts via code mode                    | A response enum does not establish supported status filters. See [failed-order triage](skill://b2c-ops/b2c-order-failure-triage/SKILL.md) for the demonstrated OCAPI fallback. |
 | Affected products/attributes | SCAPI Admin product reads; live schemas for tenant custom fields | Compare known IDs and selected fields. Shopper contracts are reference-only in this runtime.                                                                                   |
 | Suspected import/integration | [b2c-job-health](skill://b2c-ops/b2c-job-health/SKILL.md)        | Read the chosen job's log and check its actual data effects.                                                                                                                   |
-| Traffic/latency context      | Code mode Metrics where enabled; CLI `b2c metrics`               | Feature access and scopes vary. CIP/CCAC trends: `cip_discover` / `cip_query` after [CIP guidance](skill://mcp/cip/SKILL.md), with freshness/coverage limits. CLI fallback: `b2c cip`.                                                          |
+| Traffic/latency context      | Code mode Metrics where enabled; CLI `b2c metrics`               | Feature access and scopes vary. CIP/CCAC trends: `cip_discover` / `cip_query` after [CIP guidance](skill://mcp/b2c-mcp-cip/SKILL.md), with freshness/coverage limits. CLI fallback: `b2c cip`.                                                          |
 
-Read `skill://mcp/scapi/SKILL.md` before code mode; prefer dedicated tools when
+Read `skill://mcp/b2c-mcp-scapi/SKILL.md` before code mode; prefer dedicated tools when
 available. Discover operations/required fields before requests, compose bounded
 reads, and return selected evidence with errors and continuation. Read only the
 conditional reference needed; native assistants can use installed skill names.

package/content/guidance/b2c-ops/b2c-job-health/SKILL.md

@@ -27,7 +27,7 @@ an incident. Do not invent impact from a red status alone.
 | Expected product/data change | Discover the relevant Admin operation and select affected fields | Relevant CLI/data workflow if supported                      |
 | Code-version clues           | `builtin/code-version-inspect` in code mode                  | `b2c code list`; modification time is not activation history |
 
-Read `skill://mcp/scapi/SKILL.md` before code mode. Use its search/discovery
+Read `skill://mcp/b2c-mcp-scapi/SKILL.md` before code mode. Use its search/discovery
 contract; project/instance context belongs on tool calls. Authentication is
 managed. Do not export tokens or use ambient fetch inside code mode.
 
@@ -72,4 +72,4 @@ No source access is required; case submission needs authorization.
 
 CLI-specific detail when needed: native `b2c-job`, MCP
 `skill://b2c-cli/b2c-job/SKILL.md`, or the
-[Jobs reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs).
+[Jobs reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs.md) (`b2c docs read cli-jobs`).