@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

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

@@ -0,0 +1,176 @@
+---
+name: b2c-content
+description: Export, list, and validate Page Designer content from B2C Commerce libraries. Use this skill whenever the user needs to export Page Designer pages, components, or content blocks, list pages in a content library, validate page JSON or metadefinitions, discover page IDs, migrate content between instances, or work with library XML offline. Also use when extracting content for review or building content deployment pipelines -- even if they just say 'export the homepage' or 'what pages are in the shared library'.
+---
+
+# B2C Content Skill
+
+Use the `b2c` CLI to export, list, and validate Page Designer content from Salesforce B2C Commerce content libraries.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli content export homepage`).
+
+## 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.
+
+Online export/list starts a system export job: SCAPI uses `sfcc.jobs.rw` plus the tenant scope; WebDAV downloads the archive and assets. `--api-backend ocapi` forces OCAPI; `auto` permits fallback. If an error only mentions OCAPI, retry with `--api-backend scapi` to expose the SCAPI failure before assuming OCAPI permissions are needed.
+
+## Examples
+
+### Export Pages
+
+```bash
+# export a single page from a shared library
+b2c content export homepage --library SharedLibrary
+
+# export multiple pages
+b2c content export homepage about-us contact --library SharedLibrary
+
+# export pages matching a regex pattern
+b2c content export "hero-.*" --library SharedLibrary --regex
+
+# export to a specific output directory
+b2c content export homepage --library SharedLibrary -o ./my-export
+
+# export a specific component by ID
+b2c content export hero-banner --library SharedLibrary
+
+# export a content block (reusable fragment) by ID
+b2c content export DiscoverContentBlock --library RefArch --site-library
+
+# export from a site-private library
+b2c content export homepage --library RefArch --site-library
+
+# preview without downloading (dry run)
+b2c content export homepage --library SharedLibrary --dry-run
+
+# export with JSON output
+b2c content export homepage --library SharedLibrary --json
+
+# export from a local XML file (offline, no instance needed)
+b2c content export homepage --library SharedLibrary --library-file ./library.xml --offline
+
+# filter pages by folder classification
+b2c content export homepage --library SharedLibrary --folder seasonal
+
+# custom asset extraction paths
+b2c content export homepage --library SharedLibrary -q "image.path" -q "video.url"
+
+# include orphan components in export
+b2c content export homepage --library SharedLibrary --keep-orphans
+```
+
+### Export Directly into an Import-Set Migration
+
+The focused content exporter writes standard archive-relative `libraries/` or site-library files directly into the directory passed to `--output`; unlike `b2c job export`, it does not add a generated `*_export` wrapper. Preview first, then use the final timestamped migration directory and review the exported XML and assets in place:
+
+```bash
+b2c content export homepage --library SharedLibrary --dry-run --show-tree
+b2c content export homepage \
+  --library SharedLibrary \
+  --output migrations/20260815T120000-update-homepage
+```
+
+For a site-private library, configure or pass `--site-library`. Do not require a temporary directory and copy step. Never write into an existing or applied migration. See `b2c-cli:b2c-import-set-migrations` for archive identity, trimming, and deployment rules.
+
+### List Content
+
+```bash
+# list all content in a library
+b2c content list --library SharedLibrary
+
+# list only pages
+b2c content list --library SharedLibrary --type page
+
+# list content blocks (reusable fragments; includes unlinked blocks)
+b2c content list --library SharedLibrary --type fragment
+
+# list including components
+b2c content list --library SharedLibrary --components
+
+# show tree structure
+b2c content list --library SharedLibrary --tree
+
+# list from a site-private library
+b2c content list --library RefArch --site-library
+
+# list from a local XML file
+b2c content list --library SharedLibrary --library-file ./library.xml
+
+# JSON output
+b2c content list --library SharedLibrary --json
+```
+
+### Content Blocks
+
+Content blocks are Page Designer "content blocks" — reusable `fragment.*`-typed content that is **shared** across pages (one definition, linked from many places). They are listed distinctly in the tree as `(CONTENT BLOCK)`, counted separately in export summaries, and can be exported by ID like a component (a Layout content block keeps its region children). `b2c content list --type fragment` shows the deduplicated catalog of every content block in a library, including blocks not currently linked to any page.
+
+### Configuration
+
+The `--library` flag can be configured in `dw.json` or `package.json` so you don't need to pass it every time:
+
+```json
+// dw.json
+{
+  "hostname": "my-sandbox.demandware.net",
+  "content-library": "SharedLibrary"
+}
+```
+
+```json
+// package.json
+{
+  "b2c": {
+    "contentLibrary": "SharedLibrary"
+  }
+}
+```
+
+With a configured library, commands become shorter:
+
+```bash
+b2c content export homepage
+b2c content list --type page
+```
+
+### Validate Metadefinitions
+
+```bash
+# validate a single metadefinition file
+b2c content validate cartridge/experience/pages/storePage.json
+
+# validate all metadefinitions in a directory recursively
+b2c content validate cartridge/experience/
+
+# validate with a glob pattern
+b2c content validate 'cartridge/experience/**/*.json'
+
+# explicitly specify the schema type
+b2c content validate --type componenttype mycomponent.json
+
+# JSON output for CI/scripting
+b2c content validate cartridge/experience/ --json
+```
+
+Schema types are auto-detected from file paths (`experience/pages/` → pagetype, `experience/components/` → componenttype) and from JSON content. Use `--type` to override.
+
+### More Commands
+
+See `b2c content --help` for a full list of available commands and options in the `content` topic.
+
+## 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.
+- **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.
+
+## Related Skills
+
+- `b2c-cli:b2c-import-set-migrations` - Ordered, idempotent migrations built from focused content exports
+- `b2c-cli:b2c-site-import-export` - Site archive import/export operations
+- `b2c-cli:b2c-webdav` - Low-level file operations on content libraries
+- `b2c-cli:b2c-config` - Configuration and credential management

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

@@ -0,0 +1,12 @@
+[
+  {"query": "I need to export the homepage Page Designer page from our shared content library so I can review its component structure.", "should_trigger": true},
+  {"query": "How do I list all Page Designer pages in a site-specific library? I want to see the full tree of pages and components.", "should_trigger": true},
+  {"query": "Can I export Page Designer content from a local library XML file without connecting to the instance? I downloaded the library earlier.", "should_trigger": true},
+  {"query": "I need to migrate Page Designer pages from staging to production. How do I export them and validate the content before importing?", "should_trigger": true},
+  {"query": "How do I find the page ID for a specific Page Designer page in my content library so I can export just that one?", "should_trigger": true},
+  {"query": "I want to validate our Page Designer metadefinitions against the actual page JSON to check for missing component types or broken references.", "should_trigger": true},
+  {"query": "I want to create a new Page Designer component type with custom regions and attribute groups. What should my JSON meta definition look like?", "should_trigger": false},
+  {"query": "How do I import a site archive zip file back into my sandbox? I have the export ready to upload.", "should_trigger": false},
+  {"query": "I need to edit content slot configurations in Business Manager for our category landing pages.", "should_trigger": false},
+  {"query": "How do I upload static assets like images and CSS to the library folder on my instance?", "should_trigger": false}
+]

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

@@ -0,0 +1,138 @@
+---
+name: b2c-debug
+description: Debug B2C Commerce server-side scripts using the b2c CLI. Use this skill whenever the user needs to set breakpoints, step through code, inspect variables, evaluate expressions, or investigate runtime behavior on a B2C Commerce instance. Also use when the user wants to understand what a script is doing at runtime, capture state at a specific line, or drive the debugger from a headless script — even if they just say "debug this controller" or "what's the value of basket at line 42".
+---
+
+# B2C Debug Skill
+
+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.
+
+`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.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli debug cli`).
+
+## Configuration & Authentication
+
+The CLI resolves the target instance and debugger credentials from environment variables (including project `.env`), the selected project-local or shared `dw.json`, and configuration plugins. It does not search parent directories. `package.json` supplies only non-sensitive defaults; `~/.mobify` supplies MRT credentials, not debugger credentials. **Flags like `--server`, `--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; keep secrets masked unless the user explicitly requests their values). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+For MCP debugging, pass `projectDirectory` to `debug_start_session` whenever the MCP server may have been launched outside the project. The tool uses that root to load the project's `.env` and default `dw.json`; pass `configPath` to select a different primary `dw.json`-format file and `instanceName` to select a named instance from the primary or shared default file. Cartridge discovery and local/server source mapping default to `projectDirectory`; pass `cartridgeDirectory` only when the cartridges live under a different root. The start call captures this information in `resolution`, which `debug_list_sessions` returns without requiring the caller to repeat it. The MCP server controls its SDAPI client identity internally, so callers do not pass a debugger client ID.
+
+## Prerequisites
+
+- Basic Auth credentials for a BM user with `WebDAV_Manage_Customization`: a username and either the account password or a `WebDAV File Access and UX Studio` access key
+
+## Interactive Debugging
+
+### Start a Debug Session
+
+```bash
+# Start interactive debugger
+b2c debug cli
+
+# Specify cartridge directory for source mapping
+b2c debug cli --cartridge-path ./cartridges
+
+# Use a custom client ID (for concurrent sessions)
+b2c debug cli --client-id my-session
+```
+
+### Set Breakpoints
+
+In the REPL:
+
+```
+break Cart.js:42
+break Checkout.js:100 if basket.totalGrossPrice > 100
+breakpoints
+delete 1
+```
+
+### Inspect State When Halted
+
+```
+stack
+vars
+members basket.productLineItems
+eval basket.productLineItems.length
+eval request.httpParameterMap.get("pid").stringValue
+```
+
+### Control Execution
+
+```
+continue
+step
+stepin
+stepout
+```
+
+### Thread Management
+
+```
+threads
+thread 5
+frame 2
+```
+
+## RPC Mode (Headless / Agent Use)
+
+For headless scripts, agents, and programmatic integration, use `--rpc` mode. Commands and responses are JSONL (one JSON object per line) on stdin/stdout.
+
+```bash
+b2c debug cli --rpc
+```
+
+### Send Commands
+
+```json
+{"id": 1, "command": "set_breakpoints", "args": {"breakpoints": [{"file": "Cart.js", "line": 42}]}}
+{"id": 2, "command": "get_stack"}
+{"id": 3, "command": "get_variables", "args": {"scope": "local"}}
+{"id": 4, "command": "evaluate", "args": {"expression": "basket.totalGrossPrice"}}
+{"id": 5, "command": "continue"}
+```
+
+### Receive Responses and Events
+
+```json
+{"event": "ready", "data": {}}
+{"id": 1, "result": {"breakpoints": [{"id": 1, "file": "Cart.js", "line": 42, "script_path": "/app_storefront/cartridge/controllers/Cart.js"}]}}
+{"event": "thread_stopped", "data": {"thread_id": 5, "location": {"file": "Cart.js", "line": 42, "function_name": "show"}}}
+```
+
+### Available RPC Commands
+
+| Command            | Key Args                                         | Description              |
+| ------------------ | ------------------------------------------------ | ------------------------ |
+| `set_breakpoints`  | `breakpoints: [{file, line, condition?}]`        | Replace all breakpoints  |
+| `list_breakpoints` |                                                  | List current breakpoints |
+| `continue`         | `thread_id?`                                     | Resume halted thread     |
+| `step_over`        | `thread_id?`                                     | Step to next line        |
+| `step_into`        | `thread_id?`                                     | Step into function       |
+| `step_out`         | `thread_id?`                                     | Step out of function     |
+| `get_stack`        | `thread_id?`                                     | Get call stack           |
+| `get_variables`    | `thread_id?, frame_index?, scope?, object_path?` | Get variables            |
+| `evaluate`         | `expression, thread_id?, frame_index?`           | Evaluate expression      |
+| `list_threads`     |                                                  | List threads             |
+| `select_thread`    | `thread_id`                                      | Switch thread            |
+| `select_frame`     | `index`                                          | Switch frame             |
+
+## DAP Mode (IDE Integration)
+
+For VS Code and other DAP-compatible IDEs:
+
+```bash
+b2c debug
+```
+
+This starts a DAP debug adapter over stdio, used by IDE launch configurations.
+
+## Related Skills
+
+- `b2c-cli:b2c-logs` - Retrieve server logs for investigating errors found during debugging
+- `b2c-cli:b2c-code` - Deploy code changes before debugging
+- `b2c-cli:b2c-config` - Verify instance configuration and credentials

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

@@ -0,0 +1,16 @@
+[
+  {"query": "debug this controller", "should_trigger": true},
+  {"query": "set a breakpoint on line 42 of Cart.js", "should_trigger": true},
+  {"query": "what's the value of basket at line 100", "should_trigger": true},
+  {"query": "step through the checkout code", "should_trigger": true},
+  {"query": "start a debug session on my sandbox", "should_trigger": true},
+  {"query": "inspect variables when the order is placed", "should_trigger": true},
+  {"query": "I need to debug why the payment hook fails", "should_trigger": true},
+  {"query": "how do I use the debugger from a script", "should_trigger": true},
+  {"query": "connect to the script debugger via RPC", "should_trigger": true},
+  {"query": "evaluate an expression in the halted thread", "should_trigger": true},
+  {"query": "deploy my cartridges to the sandbox", "should_trigger": false},
+  {"query": "check the error logs for failures", "should_trigger": false},
+  {"query": "create a new custom object type", "should_trigger": false},
+  {"query": "search for products using SCAPI", "should_trigger": false}
+]

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

@@ -0,0 +1,274 @@
+---
+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), 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
+
+**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.** The docs corpus covers Script API reference, Commerce API (SCAPI/OCAPI) integration patterns, storefront framework guides (SFRA, PWA Kit, Storefront Next), Business Manager administration and merchandising (Salesforce Help), job step parameters, authentication flows, and tooling configuration.
+
+Use the `b2c` CLI to search and read B2C Commerce documentation spanning multiple corpora: Script API reference (`dw.*` classes/modules), **Developer Center guides** (conceptual and how-to content across Commerce API, PWA Kit, SFRA, and more), **Salesforce Help** (Business Manager administration and merchandising content from help.salesforce.com), **tooling documentation** (this project's own guides), the **standard (system) job step catalog**, and XSD schemas.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli docs search ProductMgr`).
+
+> **MCP parity:** If the `b2c-dx-mcp` server is connected, its docs tools — `docs_search`, `docs_read`, `docs_list`, `docs_schema_search`, `docs_schema_read`, and `docs_schema_list` — cover the same corpus with the same search, workspace-awareness, and topic-scoping behavior described here.
+
+## Key Features
+
+- **Multi-corpus search** — Search across Script API, Developer Center guides, Salesforce Help (admin + merchandising), internal tooling docs (guides, CLI reference, MCP, and VS Code extension), job steps, and schemas in a unified index
+- **Workspace-aware search** — Auto-detects project type (cartridges, SFRA, PWA Kit, Storefront Next) and boosts relevant documentation while de-boosting competing storefront frameworks
+- **Category filtering** — Use `--category` to narrow results to a specific corpus (e.g., `commerce-api`, `pwa-kit-managed-runtime`, `sfra`, `script-api`, `help-admin`, `help-merchant`)
+- **Triage metadata** — Search results include `category`, `summary`, `keywords`, and `url` to help identify the right match without reading full content
+- **Online content with local cache** — Script API, Developer Center guides, and Salesforce Help are fetched online when you read them and cached locally (memory + on-disk, 7-day TTL) so repeat reads avoid the network; graceful offline fallback shows the summary + headings + both URLs
+- **Content-aware ranking** — BM25-style search indexes titles, section headings, summaries, and keywords for better recall on conceptual questions
+- **Dual URLs** — Every publicly-available doc entry carries both `url` (human-facing .html page) and `sourceUrl` (raw .md source). Script API entries link developer.salesforce.com; Salesforce Help entries link the live help.salesforce.com article while content is served from a raw markdown mirror. Content is fetched via sourceUrl with offline fallback
+- **Related content** — Developer Center guides include their immediate TOC parent and children as `relatedEntries`; Salesforce Help landing entries use the same field for linked child articles and include a matching **Related Content** section in their raw Markdown
+- **Topic allowlist** — Bound the entire corpus to chosen categories via `--topics` flag or `SFCC_DOCS_TOPICS` env var, or the `docsCategories` config field (dw.json `docs-categories`, `SFCC_DOCS_CATEGORIES`, package.json). The MCP server has a `--docs-topics` startup flag
+- **Payload-conscious defaults** — MCP tools limit result count (5) and return lean fields by default; CLI defaults to 20 results; verbose mode adds extended fields
+
+## Examples
+
+### Search Documentation
+
+```bash
+# Search across all documentation
+b2c docs search "passwordless login"
+
+# Filter by category for targeted results
+b2c docs search "passwordless login" --category commerce-api
+
+# Search Developer Center guides
+b2c docs search "storefront components" --category sfra
+b2c docs search "deploy bundle" --category pwa-kit-managed-runtime
+
+# Search Script API reference
+b2c docs search ProductMgr --category script-api
+b2c docs search "catalog product"
+
+# Find a standard job step by type ID
+b2c docs search ImportCatalog
+
+# Search Salesforce Help — administration (import/export, jobs, security, Account Manager)
+b2c docs search "site import export" --category help-admin
+
+# Search Salesforce Help — merchandising (catalogs, promotions, search, pricing)
+b2c docs search "price book assignment" --category help-merchant
+
+# Search tooling documentation
+b2c docs search "authentication setup" --category tooling
+b2c docs search "import set" --category tooling
+
+# Limit results (CLI default is 20, MCP default is 5)
+b2c docs search authentication --limit 5
+
+# Read the next page of ranked results
+b2c docs search authentication --limit 5 --offset 5
+
+# Show extended fields (url, sourceUrl, summary, keywords)
+b2c docs search authentication --columns id,title,category,url,summary
+# or use -x for extended output
+b2c docs search authentication -x
+
+# Workspace awareness is ON by default — search auto-detects the project type
+b2c docs search "components"
+
+# Opt out of workspace awareness
+b2c docs search "components" --workspace all
+
+# Force auto-detection explicitly
+b2c docs search "hooks" --workspace auto
+
+# Search with specific workspace types (boosts relevant docs)
+b2c docs search "page designer" --workspace sfra
+
+# Search with multiple workspace types (union of their boost categories)
+b2c docs search "checkout" --workspace cartridges,pwa-kit-v3
+
+# List all available documentation
+b2c docs search --list
+
+# List entries in a specific category
+b2c docs search --list --category commerce-api
+
+# List docs relevant to a specific workspace (list does not auto-detect)
+b2c docs search --list --workspace cartridges
+
+# Bound the entire corpus to specific topics (allowlist; env: SFCC_DOCS_TOPICS)
+b2c docs search "login" --topics sfnext,commerce-api
+```
+
+> **`--topics` vs `--category`:** `--category` filters a single query; `--topics` (CLI flag or `SFCC_DOCS_TOPICS` env var) is an allowlist that bounds the _entire_ available corpus — `--category`/`--workspace` narrow within it, and `docs read` won't resolve an id outside it. Pin it to expose only the docs relevant to your project. **The MCP server has an equivalent `--docs-topics` startup flag and `SFCC_DOCS_TOPICS` env var.**
+
+### Workspace-Aware Search
+
+The docs search understands which workspace framework your project uses and automatically favors relevant documentation. This helps surface the right guides for SFRA, PWA Kit, or Storefront Next projects, and is **on by default**.
+
+**How it works:**
+
+- **Auto-detection (default)**: `docs search` detects the project type from the workspace structure automatically; pass `--workspace auto` to force it explicitly
+- **Explicit targeting**: Specify one or more workspace types comma-separated: `cartridges`, `sfra`, `pwa-kit-v3`, or `storefront-next`. Multiple types union their boost categories
+- **Disable awareness**: Use `--workspace all` to search without any workspace preference
+
+**Category boost mapping:**
+
+- Always relevant (any workspace): `b2c-commerce`, `tooling`
+- `cartridges` → `script-api`, `job-step`
+- `sfra` → `sfra`
+- `pwa-kit-v3` → `pwa-kit-managed-runtime`, `commerce-api`
+- `storefront-next` → `sfnext`, `commerce-api`
+
+**De-boost competing frameworks:** When a workspace is detected or specified, the search engine de-boosts (x0.3) storefront framework guides that are NOT the current one. For example, if workspace is `sfra`, then `pwa-kit-managed-runtime` and `sfnext` categories are de-boosted; this reweights results without hiding them.
+
+**SFRA vs cartridges distinction:** A SFRA project is detected as both `cartridges` and `sfra` (SFRA is a refinement — it has the `app_storefront_base` cartridge). A cartridge project that is not SFRA (custom API cartridges, or a PWA Kit / Storefront Next repo that also ships cartridges) is `cartridges` only — so it will not boost `sfra` docs.
+
+A detected or specified workspace always **boosts** relevant docs (ranks them higher) but never hides categories. To hard-scope results to a category, use `--category` or `--topics`.
+
+**`--list` behavior:** When using `--list` to browse the catalog, workspace auto-detection is **disabled** — the list shows the full corpus unless you explicitly pass `--workspace <type>` to narrow it.
+
+**Examples:**
+
+```bash
+# Auto-detect and boost relevant docs (default behavior)
+b2c docs search "components"
+
+# Search with specific workspace type
+b2c docs search "checkout" --workspace sfra
+
+# Search with multiple workspace types
+b2c docs search "deploy" --workspace pwa-kit-v3,storefront-next
+```
+
+### Read Documentation
+
+```bash
+# Read Script API documentation
+b2c docs read ProductMgr
+b2c docs read dw.catalog.ProductMgr
+
+# Read Developer Center guides by namespaced ID
+b2c docs read sfnext/sfnext-get-started
+b2c docs read commerce-api/slas-passwordless-login-registration
+b2c docs read pwa-kit-managed-runtime/getting-started
+
+# Read Salesforce Help articles by namespaced ID
+b2c docs read help-admin/b2c_site_import_export
+b2c docs read help-merchant/b2c_creating_price_books
+
+# Read tooling guides
+b2c docs read guide-authentication
+b2c docs read guide-configuration
+
+# Output raw markdown (for piping)
+b2c docs read ProductMgr --raw
+
+# Output as JSON
+b2c docs read ProductMgr --json
+```
+
+> **Exact vs. fuzzy match:** `docs read` resolves an exact id deterministically (e.g. `dw.catalog.ProductMgr`). For a fuzzy query (e.g. `productmgr`) it applies the same workspace-aware ranking as `docs search` — so a fuzzy read resolves the same top hit search ranks first. Pass `--workspace all` to opt out.
+
+> **Content sources:** Script API, Developer Center guides, Salesforce Help, and tooling docs are fetched **online** from the .md source (sourceUrl) and cached locally, with a graceful offline fallback (summary + headings + both URLs). Only standard job steps are **bundled** in the CLI.
+
+To retrieve the human-facing .html page URL (for citing/opening in browser) or the raw .md source URL, use `--json` output or `--columns url,sourceUrl` in search results.
+
+### Standard Job Step Catalog
+
+The bundled corpus includes the catalog of **standard (system) job step type IDs** — the built-in steps (for example `ImportCatalog`, `ExportCatalog`, `ImportInventoryLists`) added to Business Manager job flows. Each step's page lists its purpose and configuration parameters (required, defaults, allowed values).
+
+```bash
+# Read the catalog overview (all standard step type IDs)
+b2c docs read job-steps
+
+# Read a specific step's purpose + configuration parameters
+b2c docs read ImportCatalog
+
+# Search for a step
+b2c docs search "import price"
+b2c docs search ExportInventoryLists --category job-step
+```
+
+For how standard steps fit into job flows — chaining with custom steps, IMPEX file hand-off, and when to use an in-flow step vs. the CLI equivalent — see the `b2c:b2c-custom-job-steps` and `b2c-cli:b2c-job` skills.
+
+### Download Documentation
+
+Download the latest Script API documentation from a B2C Commerce instance. The CLI auto-discovers the target server and credentials from `dw.json`, `SFCC_*` env vars, and configuration plugins — `--server` is only needed to override. Run `b2c setup inspect` to confirm what the CLI sees; see the `b2c-cli:b2c-config` skill for troubleshooting.
+
+```bash
+# Download to a directory (uses configured instance)
+b2c docs download ./my-docs
+
+# Override server explicitly
+b2c docs download ./docs --server sandbox.demandware.net
+
+# Keep the original archive
+b2c docs download ./docs --keep-archive
+```
+
+### Read XSD Schemas
+
+Read bundled XSD schema files for import/export data formats:
+
+```bash
+# Read a schema by name
+b2c docs schema catalog
+
+# Fuzzy match schema name
+b2c docs schema order
+
+# List all available schemas
+b2c docs schema --list
+
+# Print the filesystem path to the schema file
+b2c docs schema catalog --path
+
+# Validate an XML file against a schema using xmllint
+xmllint --schema "$(b2c docs schema catalog --path)" my-catalog.xml --noout
+```
+
+## Documentation Categories
+
+| Category                  | Description                                                                                                                      | Example IDs                                         |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `script-api`              | Server-side Script API reference (`dw.*` classes/modules)                                                                        | `dw.catalog.ProductMgr`, `dw.order.Basket`          |
+| `commerce-api`            | Commerce API (SCAPI/OCAPI) conceptual and how-to guides                                                                          | `commerce-api/slas-passwordless-login-registration` |
+| `pwa-kit-managed-runtime` | PWA Kit and Managed Runtime (MRT) guides                                                                                         | `pwa-kit-managed-runtime/getting-started`           |
+| `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`            |
+| `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`       |
+| `help-admin`              | Salesforce Help — administration/ops (import/export, jobs, replication, security, Account Manager, permissions, logs, inventory) | `help-admin/b2c_site_import_export`                 |
+| `help-merchant`           | Salesforce Help — merchandising (catalogs, products, promotions, search, content, analytics, SEO)                                | `help-merchant/b2c_creating_price_books`            |
+
+> **URLs:** All categories except `job-step` carry both `url` (human .html page) and `sourceUrl` (machine-readable .md). For `help-admin`/`help-merchant`, `url` is the live help.salesforce.com article and content is read from `sourceUrl`. `job-step` entries have neither (content is bundled inline).
+>
+> **Caching:** Content for the online corpora (`script-api`, the guide categories, `help-admin`/`help-merchant`, `tooling`) is fetched on `docs read` and cached locally. Use `b2c docs cache` to inspect it and `b2c docs cache --clear` to purge it (forces a re-fetch).
+
+## Common Script API Classes
+
+| Class                     | Description                    |
+| ------------------------- | ------------------------------ |
+| `dw.catalog.ProductMgr`   | Product management and queries |
+| `dw.catalog.Product`      | Product data and attributes    |
+| `dw.order.Basket`         | Shopping basket operations     |
+| `dw.order.Order`          | Order processing               |
+| `dw.customer.CustomerMgr` | Customer management            |
+| `dw.system.Site`          | Site configuration             |
+| `dw.web.URLUtils`         | URL generation utilities       |
+
+## Common Schemas
+
+| Schema      | Description                   |
+| ----------- | ----------------------------- |
+| `catalog`   | Product catalog import/export |
+| `order`     | Order data import/export      |
+| `customer`  | Customer data import/export   |
+| `inventory` | Inventory data import/export  |
+| `pricebook` | Price book import/export      |
+| `promotion` | Promotion definitions         |
+| `coupon`    | Coupon codes import/export    |
+| `jobs`      | Job step definitions          |
+
+## More Commands
+
+See `b2c docs --help` for a full list of available commands and options.

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

@@ -0,0 +1,12 @@
+[
+  {"query": "I'm writing a checkout controller and I need to know what methods are available on the Basket object. Can you look up the API docs for me? Specifically I need to know how to add a coupon and get the shipping cost.", "should_trigger": true},
+  {"query": "I need to understand the XML schema for product catalog imports. What fields are required vs optional, and what does a valid catalog.xml look like according to the schema?", "should_trigger": true},
+  {"query": "I'm trying to generate a URL to a specific product page in my controller but I'm not sure which URL generation class to use or what parameters it takes. Can you check the API reference?", "should_trigger": true},
+  {"query": "I'm building a custom payment processor and I need to look up the OrderPaymentInstrument properties — specifically how to get the payment method, amount, and transaction details. What does the interface look like?", "should_trigger": true},
+  {"query": "I need to validate incoming XML for a site import but I'm not sure what the schema allows for promotions. What elements and attributes are valid inside a <campaign> node according to the XSD?", "should_trigger": true},
+  {"query": "I'm extending a pipeline to send transactional emails and I need to know which class handles email sending on the server side — what are the constructor arguments and how do I set the template and recipient?", "should_trigger": true},
+  {"query": "How do I write JSDoc API documentation for the new SDK module I'm adding to the docs/ folder in this project?", "should_trigger": false},
+  {"query": "I want to find all the places in our cartridges where we call ProductMgr so I can refactor them to use a wrapper.", "should_trigger": false},
+  {"query": "What's the general process for setting up a new B2C Commerce sandbox and connecting it to Business Manager?", "should_trigger": false},
+  {"query": "I need to search our cartridge codebase for everywhere we import dw.web.Resource so I can audit our localization strings.", "should_trigger": false}
+]