@salesforce/b2c-dx-mcp 3.2.1 → 3.3.0

package/dist/tools/scapi/scapi-code.d.ts

@@ -1,5 +1,5 @@
-import { ScapiLiveSchemaCache, ScapiShopperSessions } from '@salesforce/b2c-tooling-sdk/scapi';
+import { ScapiLiveSchemaCache, ScapiShopperSessions, type ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
 import type { McpTool } from '../../utils/types.js';
 import type { ServicesLoader } from '../adapter.js';
 import { ScapiExecutionRegistry } from './execution-registry.js';
-export declare function createScapiCodeTools(loadServices: ServicesLoader, snippetDirectory?: string, registry?: ScapiExecutionRegistry, schemaCache?: ScapiLiveSchemaCache, shopperSessions?: ScapiShopperSessions): McpTool[];
+export declare function createScapiCodeTools(loadServices: ServicesLoader, snippetDirectory?: string, registry?: ScapiExecutionRegistry, schemaCache?: ScapiLiveSchemaCache, shopperSessions?: ScapiShopperSessions, localSchemas?: readonly ScapiSchemaDocument[]): McpTool[];

package/dist/tools/scapi/scapi-code.js

@@ -17,64 +17,16 @@ const code = z
     .min(1)
     .max(32_768)
     .describe('JavaScript async arrow function. Return concise JSON. No filesystem or shell access.');
-const skillRead = z.boolean().optional().describe('True after reading the linked SCAPI skill.');
-const snippetDescription = `\nSnippets: await codemode.search(query) returns up to 10 names/descriptions/effects; await codemode.describe(name) returns source/inputSchema. Prefixes: builtin/, user/.`;
+const SCAPI_SKILL_REQUIRED = 'SCAPI_SKILL_REQUIRED: Read skill://mcp/b2c-mcp-scapi/SKILL.md through resources or skills_read, then retry with skillRead: true.';
+const skillRead = z
+    .literal(true, { error: SCAPI_SKILL_REQUIRED })
+    .describe('Required. Set true only after reading skill://mcp/b2c-mcp-scapi/SKILL.md (MCP resource, or skills_read({uri})).');
 function requireScapiSkill(read) {
     if (read !== true)
-        throw new Error('SCAPI_SKILL_REQUIRED: Read skill://mcp/scapi/SKILL.md through resources or skills_read, then retry with skillRead: true.');
+        throw new Error(SCAPI_SKILL_REQUIRED);
 }
-const searchDescription = `Discover Admin/Shopper SCAPI contracts; prefer dedicated tools. Read skill://mcp/scapi/SKILL.md first.
-Default: bundled, offline. schemas:"live": tenant c_*, custom, newer APIs, reused by execute.
-
-Schemas can be huge. Find operation IDs/paths first; then select required and task fields, not whole trees. Local refs expand; recursive/deep refs remain $ref.
-
-Code objects (write JavaScript, not these types):
-interface Operation {
-  api: string; operationId: string; summary?: string;
-  parameters: Array<{name: string; in: string; required?: boolean; schema?: unknown}>;
-  requestBody?: {required?: boolean; content: Record<string, {schema: any}>};
-  responses?: Record<string, unknown>;
-  security: Array<Record<string, string[]>>;
-  auth: {types: string[]; schemes: string[]; executable: boolean}; // runtime support, not access
-}
-declare const spec: {
-  apis: Array<{id: string; apiFamily: string; apiName: string; apiVersion: string; authTypes: string[]}>;
-  paths: Record<string, Record<string, Operation>>; // full paths, lowercase HTTP methods
-};
-
-Examples:
-// Find product operations
-async () => Object.entries(spec.paths)
-  .filter(([path]) => path.startsWith('/product/products/'))
-  .flatMap(([path, methods]) => Object.entries(methods)
-    .map(([method, op]) => ({method, path, operationId: op.operationId})))
-
-// Inspect only fields needed for creation
-async () => {
-  const op = spec.paths['/product/products/v1/organizations/{organizationId}/products/{productId}'].put;
-  const body = op.requestBody.content['application/json'].schema;
-  const fields = [...new Set([...(body.required ?? []), 'name', 'owningCatalogId', 'onlineFlag'])];
-  return {parameters: op.parameters, required: body.required,
-    fields: Object.fromEntries(fields.map(k => [k, body.properties[k]])), auth: op.auth, security: op.security};
-}`;
-const executeDescription = `Read, create, update, or delete Commerce records through SCAPI Admin or Shopper APIs when no dedicated tool fits. Discover endpoints with scapi_search; operations found with schemas:"live" (including custom APIs) are callable here for the same tenant. Otherwise fetch a custom API's live contract through scapi.request() in the same program first. Auth is automatic; Shopper APIs run as a guest whose session (basket) persists per site. JSON only; no binary transfers.
-Read skill://mcp/scapi/SKILL.md first.
-
-Reuse workflows with await codemode.run(name, input); describe first. async (input) receives input. Completed executionId enables scapi_snippet_save.
-Safety confirmation uses MCP elicitation. Protocol retries resume retained code; never replay it. Approval has no server deadline. Decline or cancel terminates execution without rollback. action:cancel needs executionId only (plus skillRead).
-
-Available in your code:
-declare const organizationId: string | undefined; // resolved tenant
-declare const siteId: string | undefined; // configured site
-declare const scapi: {
-  request(options: {method: string; path: string; query?: Record<string, unknown>; body?: unknown}):
-    Promise<{status: number; ok: boolean; data: any; diagnostic?: {code: string; message: string}}>;
-};
-
-Compose dependent requests; await each. Responses can be huge: filter/map/slice; return counts, selected rows and verification. Preserve failures. HTTP failures return ok:false; transport/auth/safety failures throw. SDK safety governs scapi.request. fetch/WebSocket are disabled. Optional auth.accountManager()/auth.slas() export tokens for external clients; see skill. Check writes before retrying.
-
-Example: inspect a campaign's promotions
-async () => codemode.run('builtin/campaign-promotions', {campaignId: 'selected-campaign', limit: 4})`;
+const searchDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Search SCAPI Admin/Shopper OpenAPI contracts by running JavaScript over \`spec\`, to find the operationId, path, inputs and scopes for a Commerce API task when no dedicated tool fits. Use cip_* for analytics and webdav_* for files. Searches the bundled contracts by default (offline, no credentials); schemas:"live" fetches the current contracts from the configured instance instead, including tenant c_* fields, custom APIs and APIs newer than the bundle.`;
+const executeDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Run any SCAPI Admin or Shopper API operation (reads, writes, searches and actions) through scapi.request() in JavaScript. Covers most developer, merchant and administrator tasks: catalogs, products, pricing, promotions, orders, customers, inventory, sites, jobs, code versions, observability, and storefront flows such as baskets. Use it whenever no more specific tool fits. Find operations with scapi_search first. Auth is automatic; Shopper calls run as a per-site guest whose basket persists. Operations are governed by Safety Mode and may ask the user for confirmation.`;
 function codeResult(data, resolution) {
     const result = resolution ? attachResolution(jsonResult(data, 0), resolution, 0) : jsonResult(data, 0);
     // Code-mode payloads are arbitrary JSON: retain provenance without duplicating the result.
@@ -93,7 +45,9 @@ function failure(error, resolution) {
         isError: true,
     };
 }
-export function createScapiCodeTools(loadServices, snippetDirectory, registry = new ScapiExecutionRegistry(), schemaCache = new ScapiLiveSchemaCache(), shopperSessions = new ScapiShopperSessions()) {
+export function createScapiCodeTools(loadServices, snippetDirectory, registry = new ScapiExecutionRegistry(), schemaCache = new ScapiLiveSchemaCache(), shopperSessions = new ScapiShopperSessions(), localSchemas = []) {
+    // Developer-supplied contracts (--scapi-schemas) replace bundled and live ones with the same id.
+    const local = (api) => localSchemas.filter((document) => !api || document.entry.id === api);
     // Retain only source for the last 50 completed executions, until this server ends.
     const executions = new Map();
     const searchInput = {
@@ -137,7 +91,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
         {
             name: 'scapi_search',
             title: 'SCAPI Spec Search',
-            description: searchDescription + snippetDescription,
+            description: searchDescription,
             inputSchema: searchInput,
             toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
             effect: 'read',
@@ -164,11 +118,12 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                             refresh: input.refresh,
                             signal: context?.signal,
                         }));
+                        documents = mergeScapiSchemas([], documents, local(input.api));
                         if (documents.length === 0 && failures.length === 0)
                             throw new Error('Unknown schema ID for this tenant. Omit api to discover available APIs.');
                     }
                     else {
-                        documents = loadScapiSchemas().filter((document) => !input.api || document.entry.id === input.api);
+                        documents = mergeScapiSchemas(loadScapiSchemas(), [], local()).filter((document) => !input.api || document.entry.id === input.api);
                         if (documents.length === 0)
                             throw new Error('Unknown schema ID. Omit api to discover available APIs, or use schemas:"live" for tenant and custom APIs.');
                     }
@@ -190,7 +145,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
         {
             name: 'scapi_execute',
             title: 'SCAPI Code Executor',
-            description: executeDescription + snippetDescription,
+            description: executeDescription,
             inputSchema: executeInput,
             toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
             effect: 'destructive',
@@ -241,8 +196,9 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                                     slasClientId: config.values.slasClientId,
                                     slasClientSecret: config.values.slasClientSecret,
                                 }),
-                                // Live contracts discovered for this tenant replace bundled ones; the user owns their accuracy.
-                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : []),
+                                // Live contracts discovered for this tenant replace bundled ones, and local ones replace both;
+                                // the user owns their accuracy.
+                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : [], localSchemas),
                                 onSchema(document, customProperties) {
                                     // Keep expanded tenant contracts from being replaced by unexpanded fetches.
                                     if (tenant && (customProperties || document.entry.apiFamily === 'custom'))

package/dist/utils/types.d.ts

@@ -1,4 +1,5 @@
 import type { CallToolResult } from '@modelcontextprotocol/server';
+import type { ScapiSchemaDocument } from '@salesforce/b2c-tooling-sdk/scapi';
 import type { z, ZodRawShape } from 'zod';
 import type { Toolset } from './constants.js';
 /**
@@ -64,4 +65,9 @@ export interface StartupFlags {
      * corpus at startup; unset means all categories.
      */
     docsTopics?: string;
+    /**
+     * Developer-supplied SCAPI contracts loaded from `--scapi-schemas` / `SFCC_SCAPI_SCHEMAS`.
+     * They replace bundled and live contracts with the same id in scapi_search and scapi_execute.
+     */
+    scapiSchemas?: readonly ScapiSchemaDocument[];
 }

package/node_modules/@salesforce/b2c-agent-plugins/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @salesforce/b2c-agent-plugins
 
+## 1.11.0
+
+### Minor Changes
+
+- [#738](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/738) [`1c73738`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/1c73738ce3c395738307653755692ffc357463c4) - The `storefront-next` and `figma-to-sfnext-pagedesigner` skills are updated for the October 2026 Storefront Next template. Code examples, commands, and project paths are corrected, and new skills cover security, SEO, analytics and consent, accessibility, quality gates, revalidation, and commerce features (24 skills). Skills were renamed or merged: `sfnext-create-vertical` → `sfnext-theming`, `sfnext-create-component` → `sfnext-components`, and `sfnext-scapi-management` + `sfnext-custom-apis` → `sfnext-scapi`. (Thanks [@clavery](https://github.com/clavery)!)
+
+### Patch Changes
+
+- [#737](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/737) [`78df45a`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/78df45adae187b3ce3149b22c88456ba0583c835) - Updated the `b2c-config` skill for env file selection and Storefront Next fallback precedence. (Thanks [@clavery](https://github.com/clavery)!)
+
+- [#739](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/739) [`86d42bc`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/86d42bc53c58020ca301df3e38d3cfa7ab0d4b04) - The `b2c-content` skill now points to `b2c-cli:b2c-config` for authentication setup instead of a skill that doesn't exist. (Thanks [@clavery](https://github.com/clavery)!)
+
+- [#731](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/731) [`f692182`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/f69218247ce92a7af0dbbb49ca9d696f4ca4a3a4) - Documentation search now includes the B2C Commerce Solutions guides (bot management, caching strategies, flash-sale traffic, and industry solutions) in a new `commerce-solutions` category. (Thanks [@clavery](https://github.com/clavery)!)
+
+- [#715](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/715) [`285bd55`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/285bd55bcbad048d343b3778eac4e1ef9b94cf97) - Add `b2c docs skill` to list, search, and read the agent skills bundled with the CLI, no plugin install required. Pass a skill, topic, or command (e.g. `b2c docs skill code deploy`); topic and command help now point to the covering skill. (Thanks [@clavery](https://github.com/clavery)!)
+
+- [#734](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/734) [`bea5bdc`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/bea5bdc81ae9353848b38258de4e5a32a76da9ae) - The default `--mrt-backend` is now `legacy` (the MRT Cloud API) instead of `auto`. MRT commands no longer auto-detect and prefer the SCAPI backend unless you opt in. To restore the previous behavior — prefer SCAPI when short code, tenant ID, and client-credentials/JWT Bearer auth are configured, otherwise fall back to legacy — pass `--mrt-backend auto` (or set `MRT_BACKEND=auto` / `mrtBackend` in `dw.json`). Use `--mrt-backend scapi` to require SCAPI with no fallback. (Thanks [@kieran-sf](https://github.com/kieran-sf)!)
+
+- [#731](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/pull/731) [`f692182`](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling/commit/f69218247ce92a7af0dbbb49ca9d696f4ca4a3a4) - Skills now refer to each other by name instead of relative paths, so links work wherever a skill is installed. Documentation links point to Markdown pages and include the `b2c docs read` ID for offline reading. (Thanks [@clavery](https://github.com/clavery)!)
+
 ## 1.10.3
 
 ### Patch Changes

package/node_modules/@salesforce/b2c-agent-plugins/README.md

@@ -76,6 +76,11 @@ Plugins listed in [`plugins.json`](./plugins.json) are zipped to `<name>-skills.
   for MCP bundling and in both marketplaces for native installation.
 - To make a new plugin installable via the B2C CLI, add it to [`plugins.json`](./plugins.json) and register a source in `packages/b2c-tooling-sdk/src/skills/sources.ts` (plus the `SkillSet` type in `types.ts`).
 - Add a changeset targeting `@salesforce/b2c-agent-plugins` for any skill content changes.
+- Skill references (enforced by `pnpm --filter @salesforce/b2c-dx-mcp run generate:guidance`):
+  - Relative links stay inside the skill directory (`references/X.md`, `../SKILL.md#section`).
+  - Refer to other skills by name ("see the `b2c-config` skill"), or by `skill://<collection>/<skill>/SKILL.md` in MCP skills. Never link another skill by relative path; skills install and serve independently.
+  - Link tooling docs to the Markdown page (`https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.md`) and add the docs ID: `` (`b2c docs read guide-configuration`) `` in plugin skills, `docs_read({query: "guide-configuration"})` in MCP skills.
+  - The frontmatter `name` must equal the directory name and follow the [Agent Skills naming rules](https://agentskills.io/specification#name-field).
 
 See the repository [CLAUDE.md](../CLAUDE.md) and the [documentation skill](../.claude/skills/documentation/SKILL.md) for full contributor guidance.
 

package/node_modules/@salesforce/b2c-agent-plugins/b2c/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "b2c",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "B2C Commerce development skills including Custom API development guides.",
   "author": {
     "name": "Salesforce"

package/node_modules/@salesforce/b2c-agent-plugins/b2c/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "b2c",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "B2C Commerce development skills including Custom API development guides.",
   "author": {
     "name": "Salesforce"

package/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "b2c-cli",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "B2C CLI Skills for Salesforce Commerce Cloud development.",
   "author": {
     "name": "Salesforce"

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "b2c-cli",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "B2C CLI Skills for Salesforce Commerce Cloud development.",
   "author": {
     "name": "Salesforce"

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/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/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/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.