@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-code/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: b2c-code
+description: Deploy, download, and manage cartridge code versions on B2C Commerce instances. Use this skill whenever the user needs to upload or download cartridges to/from a sandbox, activate or delete code versions, watch for local file changes during development, or deploy a subset of cartridges. Also use when pushing code to an instance, pulling code from an instance, or setting up a dev workflow with live reload -- even if they just say 'push my code to the sandbox', 'download the code', or 'how do I activate the new version'.
+---
+
+# B2C Code Skill
+
+Use the `b2c` CLI to deploy, download, and manage code versions on Salesforce B2C Commerce instances.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli code deploy`).
+
+## MCP equivalent
+
+Prefer `cartridge_deploy` for cartridge upload. Set `codeVersion` explicitly when
+needed; `files` selects up to 100 local files (64 MiB total), relative to
+`projectDirectory`, within discovered cartridges. Omit `files` for whole cartridges.
+Matching remote files are overwritten; selected-file mode preserves other files.
+`reload` may activate the target; keep upload success/warnings if reload fails.
+Code mode `builtin/code-version-inspect` reads active/rollback and activation metadata;
+`builtin/site-cartridge-inspect` reads site cartridge order and checks expected names.
+SCAPI `dx/scripts/v1` provides version management; `site/sites/v1` manages site paths.
+Use the CLI for watches, recursive downloads, and extra deployment flags.
+
+## Configuration & Authentication
+
+The CLI auto-discovers the target instance and credentials from `SFCC_*` environment variables (including project `.env`), the selected project-local or shared `dw.json`, and configuration plugins. `package.json` supplies only non-sensitive defaults. **Flags like `--server`, `--client-id`, `--client-secret`, `--username`, and `--password` are usually unnecessary** — only pass them to override what's auto-detected.
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (use `--json` for scripting; secrets stay masked by default). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+## Examples
+
+### Deploy Cartridges
+
+```bash
+# deploy all cartridges from current directory
+b2c code deploy
+
+# deploy cartridges from a specific directory
+b2c code deploy ./my-cartridges
+
+# deploy to a specific server and code version
+b2c code deploy --server my-sandbox.demandware.net --code-version v1
+
+# deploy and reload (re-activate) the code version
+b2c code deploy --reload
+
+# delete existing cartridges before upload and reload
+b2c code deploy --delete --reload
+
+# deploy only specific cartridges
+b2c code deploy -c app_storefront_base -c plugin_applepay
+
+# exclude specific cartridges from deployment
+b2c code deploy -x test_cartridge
+```
+
+### Download Cartridges
+
+```bash
+# download all cartridges from the active code version
+b2c code download
+
+# download to a specific directory
+b2c code download -o ./downloaded
+
+# download from a specific server and code version
+b2c code download --server my-sandbox.demandware.net --code-version v1
+
+# download only specific cartridges
+b2c code download -c app_storefront_base -c plugin_applepay
+
+# exclude specific cartridges from download
+b2c code download -x test_cartridge
+
+# mirror: extract to local cartridge project locations
+b2c code download --mirror
+```
+
+### Watch for Changes
+
+```bash
+# watch cartridges and upload changes automatically
+b2c code watch
+
+# watch a specific directory
+b2c code watch ./my-cartridges
+
+# watch with specific server and code version
+b2c code watch --server my-sandbox.demandware.net --code-version v1
+
+# watch only specific cartridges
+b2c code watch -c app_storefront_base
+
+# watch excluding specific cartridges
+b2c code watch -x test_cartridge
+```
+
+### List Code Versions
+
+```bash
+# list code versions on the instance
+b2c code list
+
+# list with JSON output
+b2c code list --json
+```
+
+### Activate Code Version
+
+```bash
+# activate a code version
+b2c code activate <version-name>
+
+# reload (re-activate) the current code version
+b2c code activate --reload
+```
+
+**Note:** Activation is idempotent. If the version is already active, the command succeeds without making a change. If you've uploaded code or changed Custom APIs in the active version, use `--reload` with deploy or activate to force a refresh and register the endpoints. Check registration status with the `b2c-cli:b2c-scapi-custom` skill.
+
+### Delete Code Version
+
+```bash
+# delete a code version
+b2c code delete <version-name>
+```
+
+### API Backend
+
+`code list`, `code activate`, `code delete`, and the active-version discovery / activate / reload steps in `code deploy` run over SCAPI. Configure `shortCode`, `tenantId`, and the `sfcc.scripts` / `sfcc.scripts.rw` scopes and they work out of the box. Read scope (`sfcc.scripts`) covers `code list` / discovery; write scope (`sfcc.scripts.rw`) covers activate, delete, reload, and the `--activate` / `--reload` flags on deploy.
+
+`code deploy` (file upload itself), `code download`, and `code watch` always use WebDAV — only the surrounding code-version operations use SCAPI.
+
+OCAPI is deprecated and disabled on newer instances. `--api-backend auto` (the default) falls back to the OCAPI Data API on safe SCAPI capability/auth/request rejections; force a backend with `--api-backend scapi|ocapi` if needed. The `--reload` flag forces a code cache reload as activate(alternate) + activate(target), using whichever backend the command selected — so it works on OCAPI-disabled instances when SCAPI is configured.
+
+### More Commands
+
+See `b2c code --help` for a full list of available commands and options in the `code` topic.
+
+> **Note:** `b2c code deploy` uploads cartridge _code_ to an instance. To manage which cartridges are _active on a site_ (the cartridge path), see the `b2c-cli:b2c-sites` skill for the `b2c sites cartridges` commands.
+
+## Related Skills
+
+- `b2c-cli:b2c-sites` - Manage site cartridge paths (list, add, remove, set active cartridges)
+- `b2c-cli:b2c-scapi-custom` - Check Custom API registration status after deployment
+- `b2c-cli:b2c-webdav` - Low-level file operations (delete cartridges, list files)
+- `b2c:b2c-custom-api-development` - Creating Custom API endpoints

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-code/evals/trigger-evals.json

@@ -0,0 +1,14 @@
+[
+  {"query": "How do I deploy only app_storefront_base and plugin_applepay cartridges to my sandbox? I want to clean out the existing code version first.", "should_trigger": true},
+  {"query": "I want my local changes to auto-upload to the instance whenever I save a file. How do I set up file watching for development?", "should_trigger": true},
+  {"query": "How do I list all code versions on my instance and activate a specific one? I also need to delete an old version that's no longer used.", "should_trigger": true},
+  {"query": "I just finished building a new cartridge and need to push it to my sandbox for testing. What's the fastest way?", "should_trigger": true},
+  {"query": "Our release process requires deploying cartridges to staging, activating the new version, then verifying. Walk me through that workflow.", "should_trigger": true},
+  {"query": "I have a monorepo with multiple cartridges. How do I deploy a subset of them without uploading everything?", "should_trigger": true},
+  {"query": "I need to download the cartridge code from my sandbox to see what's currently deployed. How do I pull the code down?", "should_trigger": true},
+  {"query": "How do I sync the remote code version back to my local project? I want to mirror what's on the instance.", "should_trigger": true},
+  {"query": "I need to upload a site import archive to the IMPEX directory on my instance. What's the right approach?", "should_trigger": false},
+  {"query": "My ISML templates have a bug where isprint is double-encoding HTML entities. How do I fix the encoding attribute?", "should_trigger": false},
+  {"query": "How do I tail the error logs on my sandbox to debug a 500 error on the storefront?", "should_trigger": false},
+  {"query": "I need to run a site import job after uploading my data archive. How do I trigger the import?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-config/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: b2c-config
+description: Configure B2C CLI/MCP authentication, instances, and project defaults; troubleshoot missing credentials, wrong targets, or configuration precedence. Routine inspection can use config_inspect or b2c setup inspect directly.
+---
+
+# B2C Config Skill
+
+For routine inspection, call `config_inspect` or `b2c setup inspect` directly;
+no skill read is required. Keep secrets redacted; manually reading `dw.json` is usually unnecessary. Read the relevant section
+here when configuring sources or diagnosing unexpected/missing values.
+
+| Task                                 | CLI                     | MCP                                 | Preference / difference                                                                      | Fallback                                                  |
+| ------------------------------------ | ----------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Inspect resolved configuration       | `b2c setup inspect`     | `config_inspect`                    | Either; same resolver, redacted by default. MCP accepts per-call project/instance overrides. | Inspect source files only for edits or unresolved issues. |
+| Change configuration or authenticate | `b2c setup`, `b2c auth` | No configuration-writing equivalent | CLI; inspect command help for the requested operation.                                       | Edit the intended configuration source.                   |
+
+If `b2c` is unavailable, use `npx @salesforce/b2c-cli`.
+
+## How the CLI Discovers Configuration
+
+The CLI **automatically detects** instance hostname, credentials, tenant ID, MRT API key, and other settings from multiple sources. **You usually do not need to pass `--server`, `--client-id`, `--client-secret`, `--username`, `--password`, `--tenant-id`, `--short-code`, or `--api-key` as flags** — the CLI picks them up from the environment or config files.
+
+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).
+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.
+
+For unexpected values, inspect resolved configuration and sources with `config_inspect` or `b2c setup inspect`.
+
+### Shared Global Default
+
+Use a shared fallback when the same `dw.json`-format file should work across the CLI, MCP server, and B2C DX VS Code extension:
+
+```bash
+b2c setup default-config set /path/to/dw.json
+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 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`.
+
+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).
+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.
+
+Local MCP project tools accept `projectDirectory`. Tools that resolve B2C/MRT configuration accept the same flat `projectDirectory`, `configPath`, and `instanceName` arguments. This override is especially important for plugin installs, where the MCP process working directory may be the plugin directory rather than the open project. For each configuration-aware call, the MCP server:
+
+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.
+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`.
+7. Resolves specialized paths such as `cartridgeDirectory`, `buildDirectory`, and `outputDirectory` from the same root when relative.
+
+Project `.env` values are scoped to that MCP call so one project's environment does not leak into another.
+
+Each project/config-aware result includes an authoritative, compact `resolution` block. It reports the selected project, configuration file, instance, hostname, and specialized directories without relying on paths embedded in tool descriptions. Session and watch start calls retain it, and their list tools expose it for later follow-up calls. The MCP `config_inspect` tool additionally returns the full source graph and uses the same SDK resolver and registered CLI plugin configuration sources as `b2c setup inspect`. Use `projectDirectory`, `configPath`, and/or `instanceName` to compare the intended project, file, and instance.
+
+### `dw.json` Key Casing
+
+Field names in `dw.json` accept **both camelCase and kebab-case** — they're equivalent. For example:
+
+| Either form works                                                         |
+| ------------------------------------------------------------------------- |
+| `clientId` ≡ `client-id`                                                  |
+| `clientSecret` ≡ `client-secret`                                          |
+| `codeVersion` ≡ `code-version`                                            |
+| `tenantId` ≡ `tenant-id`                                                  |
+| `shortCode` ≡ `short-code` ≡ `scapi-shortcode`                            |
+| `webdavHostname` ≡ `webdav-hostname` ≡ `webdav-server` ≡ `secureHostname` |
+| `certificatePassphrase` ≡ `certificate-passphrase` ≡ `passphrase`         |
+
+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).
+
+## Authentication
+
+Most commands that interact with a B2C Commerce instance require authentication. The CLI supports several methods:
+
+- **Client credentials (API client):** Configure `clientId` and `clientSecret` in dw.json or environment variables. This is the default for automated/CI use.
+- **Browser-based (implicit OAuth):** Use `--user-auth` on any OAuth-enabled command to authenticate interactively via the browser. This opens Account Manager in your default browser for login.
+- **Basic auth:** Configure `username` and `password` for WebDAV operations.
+- **Stateful sessions:** Use `b2c auth login` for persistent browser-based login sessions or `b2c auth client` for persistent client authentication. Later commands reuse the valid saved session when no other client is configured.
+
+### `--user-auth` Flag
+
+Many commands support `--user-auth` to use browser-based OAuth instead of client credentials. As of B2C Commerce release 26.8, SCAPI Admin APIs do not support this flow; migrated commands use OCAPI in `auto` mode, while explicit SCAPI reports an actionable authentication error before making an API request. User auth remains useful when:
+
+- You don't have a `clientSecret` configured
+- You need user-level permissions (e.g., Account Manager admin roles)
+- You're working interactively
+
+```bash
+# Interactive browser-based auth for any OAuth command
+b2c sandbox list --user-auth
+b2c scapi schemas list --user-auth
+b2c auth token --user-auth
+```
+
+Coding agents can also use `--user-auth` — the browser flow works in any environment where a browser can be opened. The flag is exclusive with `--auth-methods`.
+
+**Running behind a proxy:** If `localhost:8080` isn't reachable by the browser (e.g., running in a container or behind a reverse proxy), set `SFCC_REDIRECT_URI` to the proxy URL. The local OAuth server still listens on the default port (or `SFCC_OAUTH_LOCAL_PORT`), but the redirect URI sent to Account Manager will use your proxy URL. Add the proxy URL to the API client's redirect URLs in Account Manager.
+
+## Tenant ID and Organization ID
+
+B2C Commerce uses two related identifiers:
+
+- **Tenant ID** — the short form (e.g., `zzxy_prd` or `zzxy-prd`)
+- **Organization ID** — the SCAPI form with `f_ecom_` prefix (e.g., `f_ecom_zzxy_prd`)
+
+The CLI automatically normalizes and translates between these formats. You can provide either form in configuration or flags — the CLI handles the conversion. It also extracts tenant IDs from hostnames (e.g., `zzxy-prd.dx.commercecloud.salesforce.com` resolves to `zzxy_prd`).
+
+In dw.json or environment variables, use the `tenantId` config key. The CLI will add the `f_ecom_` prefix when making SCAPI calls.
+
+## Inspecting Configuration
+
+Use `b2c setup inspect` to view the resolved configuration and understand where each value comes from. Use `b2c setup instance` commands to manage named instance configurations.
+
+> **Note:** `b2c setup config` works as an alias for `b2c setup inspect`.
+
+### When to Use
+
+Use `b2c setup inspect` when you need to:
+
+- Verify which configuration file is being used
+- Check if environment variables are being read correctly
+- Debug authentication failures by confirming credentials are loaded
+- Understand credential source priority (dw.json vs env vars vs plugins)
+- Identify hostname mismatch protection issues
+- Verify MRT API key is loaded from ~/.mobify
+
+### View Current Configuration
+
+```bash
+# Display resolved configuration (sensitive values masked by default)
+b2c setup inspect
+
+# View configuration for a specific instance from dw.json
+b2c setup inspect -i staging
+
+# View configuration with a specific config file
+b2c setup inspect --config /path/to/dw.json
+```
+
+### Debug Sensitive Values
+
+```bash
+# Reveal secrets only when the user explicitly requests their values
+b2c setup inspect --unmask
+```
+
+### JSON Output for Scripting
+
+```bash
+# Output as JSON for parsing in scripts
+b2c setup inspect --json
+
+# Pretty-print with jq
+b2c setup inspect --json | jq '.config'
+
+# Check which sources are loaded
+b2c setup inspect --json | jq '.sources'
+```
+
+## IDE Integration
+
+Use `b2c setup ide` to configure IDE tooling that consumes the resolved CLI configuration and to enable Script API IntelliSense.
+
+```bash
+# Vendor Script API TypeScript definitions + jsconfig.json (plain VS Code, WebStorm, etc.)
+b2c setup ide vscode-types
+
+# Print the TS Server plugin path for LSP-based editors (Neovim, Helix, Zed, ...)
+b2c setup ide tsserver-plugin --json
+```
+
+The B2C DX VS Code extension needs no setup — it injects the same TypeScript Server plugin at runtime.
+
+## Managing Instances
+
+### List Configured Instances
+
+```bash
+# Show all instances from dw.json
+b2c setup instance list
+
+# Output as JSON
+b2c setup instance list --json
+```
+
+### Create a New Instance
+
+```bash
+# Interactive mode - prompts for all values
+b2c setup instance create staging
+
+# With hostname
+b2c setup instance create staging --hostname staging.example.com
+
+# Create and set as active
+b2c setup instance create staging --hostname staging.example.com --active
+
+# Optionally save SCAPI coordinates and use SCAPI-first active-version detection
+b2c setup instance create staging --hostname staging.example.com \
+  --short-code kv7kzm78 --tenant-id zzxy_prd --api-backend auto
+
+# Non-interactive mode (for scripts)
+b2c setup instance create staging \
+  --hostname staging.example.com \
+  --username admin \
+  --password secret \
+  --force
+```
+
+`shortCode` and `tenantId` are optional. When present with stateless OAuth, setup tries SCAPI first to detect the active code version; otherwise `auto` uses OCAPI. If detection fails, interactive setup reports the reason and allows manual code-version entry.
+
+### Switch Active Instance
+
+```bash
+# Set staging as the default instance
+b2c setup instance set-active staging
+
+# Now commands use staging by default
+b2c code list  # Uses staging
+```
+
+### Remove an Instance
+
+```bash
+# Remove with confirmation prompt
+b2c setup instance remove staging
+
+# Remove without confirmation
+b2c setup instance remove staging --force
+```
+
+## Understanding the Output
+
+The `setup inspect` command displays configuration organized by category:
+
+- **Instance**: hostname, webdavHostname (if set), codeVersion
+- **Authentication (Basic)**: username, password (for WebDAV)
+- **Authentication (OAuth)**: clientId, clientSecret, scopes and authMethods (if set), accountManagerHost (if set)
+- **Authentication (JWT Bearer)**: jwtCertPath, jwtKeyPath, jwtPassphrase (only shown when configured)
+- **Authentication (SLAS)**: slasClientId, slasClientSecret (only shown when configured)
+- **TLS/mTLS**: certificate, certificatePassphrase, selfSigned (only shown when configured)
+- **SCAPI**: shortCode, tenantId
+- **Commerce Intelligence (CIP)**: cipHost (only shown when configured)
+- **On-Demand Sandbox (ODS)**: sandboxApiHost, realm (only shown when configured)
+- **Managed Runtime (MRT)**: mrtProject, mrtEnvironment, mrtApiKey, mrtOrigin (if set)
+- **Project**: configured deployment, content, and documentation defaults
+- **Metadata**: siteId, instanceName, and projectDirectory (only shown when configured)
+- **Safety**: safety configuration (only shown when configured)
+- **Sources**: List of all configuration sources that were loaded
+
+Each value shows its source in brackets:
+
+- `[DwJsonSource]` — Value from the primary `dw.json` file
+- `[default]` — Value from the shared default `dw.json` (shown as `DwJsonSource (default)` in the Sources table)
+- `[EnvSource]` — Value from an SFCC\_\* environment variable
+- `[MobifySource]` — Value from ~/.mobify file
+- `[PackageJsonSource]` — Value from package.json `b2c` key
+- Plugin-provided source names (e.g., a credential plugin)
+
+## Configuration Priority
+
+Values are resolved with this priority (highest to lowest):
+
+1. CLI flags and environment variables
+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
+
+When troubleshooting, check the source column to understand which configuration is taking precedence.
+
+## Project Defaults in package.json
+
+Put non-sensitive defaults shared by the project under the `b2c` key. `siteId` supplies the default site/channel for commands that accept configured site context. For content commands, set `contentLibrary` and list the same ID with `siteLibrary: true` when it is the site's private library:
+
+```json
+{
+  "b2c": {
+    "siteId": "RefArch",
+    "contentLibrary": "RefArch",
+    "libraries": [{"id": "RefArch", "siteLibrary": true}]
+  }
+}
+```
+
+With this configuration, `b2c content list` and `b2c content export homepage` default to the `RefArch` site-private library without `--library` or `--site-library`. CLI flags, environment variables, and `dw.json` remain higher-priority overrides. Keep credentials, passwords, secrets, hostnames, and other environment-specific connection data out of `package.json`.
+
+## Troubleshooting
+
+**Always start with `b2c setup inspect`** — it shows resolved values and their sources. Keep masking enabled; use `--json` for scripting. If a value isn't where you expect, the source column will tell you which file/env var/plugin won.
+
+### Command says "credentials required" or "client-id is required"
+
+- The CLI is not finding `clientId`/`clientSecret`. Run `b2c setup inspect` and check the OAuth section.
+- Check the selected configuration path and sources; defaults are project-local `dw.json` then the shared global default, without a parent-directory search.
+- Confirm `SFCC_CLIENT_ID`/`SFCC_CLIENT_SECRET` env vars are exported in _this_ shell, not just defined elsewhere.
+- Credential groups are **atomic**: if `clientId` comes from one source and `clientSecret` from a lower-priority one, the lower-priority secret is discarded. Provide both from the same source, or use a higher-priority override.
+
+### Command targets the wrong instance
+
+- `b2c setup inspect` will show the resolved hostname and its source.
+- For multi-instance `dw.json`, the `active: true` config is used by default. Override with `-i <name>` per-command, or change the default with `b2c setup instance set-active <name>`.
+- `SFCC_SERVER` (or any env var) overrides `dw.json`. Unset it if you want `dw.json` to win.
+- **Hostname mismatch protection:** if you pass `--server` (or `SFCC_SERVER`) that differs from the `dw.json` hostname, the CLI ignores **all** other values from `dw.json` to prevent mixing credentials across instances. Either match the hostname or pass full credentials explicitly.
+
+### `dw.json` is not being picked up
+
+- Check the `Sources` block from `b2c setup inspect` — if `DwJsonSource` isn't listed, the file wasn't found.
+- The CLI uses the selected project directory, not a parent-directory search. Run from your project root, set `SFCC_PROJECT_DIRECTORY`, or pass `--config /path/to/dw.json`.
+- Ensure the file is valid JSON (a parse error silently skips it).
+- Field name casing doesn't matter — both `clientId` and `client-id` work. See "dw.json Key Casing" above.
+
+### 401/403 errors on SCAPI/OCAPI calls
+
+- Confirm the resolved `clientId`/`clientSecret` belong to the _target_ instance (Account Manager scopes the API client per tenant).
+- Check OAuth scopes: required scopes vary by command (e.g., `sfcc.cdn-zones`, `sfcc.orders`). Pass `--auth-scope` or set `SFCC_OAUTH_SCOPES`.
+- For SCAPI commands, verify `tenantId` is correct — tenant IDs use underscores (`zzxy_001`), hostnames use hyphens (`zzxy-001`). The CLI normalizes between them, but a wrong tenant ID will produce 403s.
+
+### 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`.
+
+### MRT commands say "API key required"
+
+- `MRT_API_KEY` (or `SFCC_MRT_API_KEY`) env var, or `~/.mobify` file (`{ "api_key": "..." }`).
+- When using `--cloud-origin <host>`, the CLI looks for `~/.mobify--<host>` instead of plain `~/.mobify`.
+
+### Sensitive values masked in `setup inspect`
+
+- By default secrets show as `admi...REDACTED`. Keep masking enabled for routine troubleshooting. Use `--unmask` only when the user explicitly requests secret values.
+
+### Missing values
+
+- If a field shows `-`, no source provided it. Check spelling in `dw.json`, env var presence, and plugin output. Remember: `clientSecret`, `password`, and `mrtApiKey` cannot be set via `package.json` — use `dw.json` or env vars.
+
+### 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`.
+
+### Still stuck
+
+Compare two outputs:
+
+```bash
+b2c setup inspect --json > expected.json   # in a known-good shell
+# ... run the failing command in the broken shell, then:
+b2c setup inspect --json > actual.json
+diff expected.json actual.json
+```
+
+The diff usually points directly at the missing or overridden field.
+
+## Getting Admin OAuth Tokens
+
+Use `b2c auth token` to get an admin OAuth access token for Account Manager credentials (OCAPI and Admin APIs). This is useful for testing APIs, scripting, or CI/CD pipelines.
+
+```bash
+# Get access token (outputs raw token to stdout)
+b2c auth token
+
+# Get token with browser-based auth
+b2c auth token --user-auth
+
+# Get token with specific scopes (accepts multiple: repeat --auth-scope or comma-separate)
+b2c auth token --auth-scope sfcc.orders --auth-scope sfcc.products
+b2c auth token --auth-scope "sfcc.orders,sfcc.products"
+
+# Get token as JSON (includes expiration and scopes)
+b2c auth token --json
+
+# Use in curl for OCAPI calls
+curl -H "Authorization: Bearer $(b2c auth token)" \
+  "https://your-instance.dx.commercecloud.salesforce.com/s/-/dw/data/v24_1/sites"
+```
+
+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).
+
+> **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:
+>
+> ```bash
+> b2c auth token \
+>   --auth-scope "SALESFORCE_COMMERCE_API:zzpq_013" \
+>   --auth-scope sfcc.orders --auth-scope sfcc.products.rw
+> ```
+>
+> See the `b2c:b2c-scapi-admin` and `b2c:b2c-custom-api-development` skills for details.
+
+## More Commands
+
+See `b2c setup --help` for other setup commands including `b2c setup skills` for AI agent skill installation.

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-config/evals/trigger-evals.json

@@ -0,0 +1,12 @@
+[
+  {"query": "My CLI keeps connecting to the wrong sandbox. How do I check which config file and credentials are being used? I think my dw.json is getting overridden by environment variables.", "should_trigger": true},
+  {"query": "I need to set up multiple instances in my configuration and switch between staging and production environments easily.", "should_trigger": true},
+  {"query": "How do I get an OAuth access token from the CLI for use in curl commands against OCAPI? I need specific scopes included.", "should_trigger": true},
+  {"query": "Authentication keeps failing with a 401 error when I try to deploy. How do I debug what credentials the CLI is actually sending?", "should_trigger": true},
+  {"query": "I just cloned the project and need to set up my dw.json with the sandbox hostname and API client credentials. What fields are required?", "should_trigger": true},
+  {"query": "How do I configure my VS Code workspace to use the B2C CLI for deployments? I want to integrate it with my editor tasks.", "should_trigger": true},
+  {"query": "How do I deploy cartridges to my sandbox and activate the new code version?", "should_trigger": false},
+  {"query": "I need to run a Commerce Insights analytics report but I'm getting a 403 error. What API client role do I need?", "should_trigger": false},
+  {"query": "How do I upload a site import archive to the IMPEX folder on my instance?", "should_trigger": false},
+  {"query": "I want to purge the CDN cache for our production storefront after a content update.", "should_trigger": false}
+]