@salesforce/b2c-cli 2.3.1 → 2.4.0

package/content/guidance/b2c-cli/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/b2c-mcp-debugger/SKILL.md` for the MCP workflow. Use the CLI for a requested terminal session or when MCP is unavailable.
+
+`b2c debug` provides a Debug Adapter Protocol (DAP) debug adapter for IDEs. For terminal or headless use without the MCP tools, `b2c debug cli` also offers an interactive REPL and a JSONL `--rpc` mode.
+
+> **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/content/guidance/b2c-cli/b2c-docs/SKILL.md

@@ -0,0 +1,301 @@
+---
+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, Commerce Solutions, OCAPI), Salesforce Help (Business Manager administration and merchandising), tooling documentation (CLI/MCP/SDK), standard job steps, and XSD schemas. Use this skill for ANY B2C Commerce developer or administrator question that is not already grounded in a loaded skill or the current project context — even if they just say "how do I implement passwordless login" or "what methods does Basket have" or "how do I deploy a PWA Kit bundle" or "how do I import a site archive" or "what SCAPI endpoints are available for checkout".
+---
+
+# B2C Docs Skill
+
+**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, OCAPI reference, 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`, `help-kb`)
+- **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 Salesforce Help Knowledge Articles — troubleshooting, known issues, how-to answers
+b2c docs search "code upload certificate hyperforce" --category help-kb
+
+# 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`, `commerce-solutions`, `ocapi`, `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
+b2c docs read help-kb/002772125
+
+# 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`            |
+| `commerce-solutions`      | B2C Commerce Solutions — bot management, caching strategies, flash-sale traffic, and industry solutions                          | `commerce-solutions/bot-management`                 |
+| `ocapi`                   | OCAPI reference — usage, hooks, settings, and best practices for the Open Commerce API                                           | `ocapi/ocapisettings`, `ocapi/bestpractices`        |
+| `tooling`                 | B2C CLI reference, guides, MCP docs, SDK guidance, and VS Code extension docs                                                    | `guide-authentication`, `cli-jobs`                  |
+| `job-step`                | Standard (system) job step catalog                                                                                               | `ImportCatalog`, `ExportCatalog`, `job-steps`       |
+| `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`            |
+| `help-kb`                 | Salesforce Help Knowledge Articles — troubleshooting, known issues, and how-to answers (keyed by article number)                 | `help-kb/002772125`                                 |
+
+> **URLs:** All categories except `job-step` carry both `url` (human .html page) and `sourceUrl` (machine-readable .md). For `help-admin`/`help-merchant`/`help-kb`, `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`/`help-kb`, `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          |
+
+## Finding CLI Commands
+
+`b2c docs search` searches documentation. To find **which `b2c` command performs a task**, search the CLI's own commands instead:
+
+```bash
+b2c commands search "deploy cartridges"
+b2c commands search "environment variables" --topic mrt --json
+```
+
+## Reading Agent Skills
+
+The CLI bundles its agent skills (workflow guides like this one). Read the skill for a command or topic, or search them, without installing a plugin:
+
+```bash
+b2c docs skill                          # list b2c-cli skills
+b2c docs skill code deploy              # skill covering a command or topic
+b2c docs skill --search "site import"   # search skills
+b2c docs skill --all --search "hooks"   # include b2c, b2c-ops, storefront-next
+```
+
+## More Commands
+
+See `b2c docs --help` for a full list of available commands and options.

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

@@ -0,0 +1,135 @@
+---
+name: b2c-ecdn
+description: Manage eCDN zones, security settings, and edge configuration for B2C Commerce storefronts. Use this skill whenever the user needs to purge CDN cache, provision SSL certificates, configure WAF or firewall rules, set up rate limiting, enable logpush or Page Shield, manage MRT routing, configure mTLS or cipher suites, or optimize edge performance. Also use when troubleshooting CDN-layer issues or managing zone settings -- even if they just say 'clear the cache' or 'block bot traffic on our storefront'.
+---
+
+# B2C eCDN Skill
+
+Use the `b2c` CLI plugin to manage eCDN (embedded Content Delivery Network) zones, certificates, security settings, and more.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli ecdn zones list`).
+
+## Configuration
+
+Values like `tenantId`, `clientId`, and `clientSecret` resolve from `dw.json` / `SFCC_*` env vars / the active instance / configuration plugins. Examples below show minimal usage; **add flags only to override configured values** — passing `--client-id`/`--client-secret`/`--tenant-id` is usually unnecessary. If a required value is missing, the CLI emits an actionable error pointing at the flag, env var, and config key.
+
+Run `b2c setup inspect` to see the resolved configuration and which source provided each value (`--json` for scripting; secrets stay masked by default). For precedence rules and troubleshooting, see the `b2c-cli:b2c-config` skill.
+
+## Prerequisites
+
+- OAuth credentials with `sfcc.cdn-zones` scope (read operations)
+- OAuth credentials with `sfcc.cdn-zones.rw` scope (write operations)
+- Tenant ID for your B2C Commerce organization (from config or `--tenant-id`)
+
+## Examples
+
+### List CDN Zones
+
+```bash
+# list all CDN zones for the configured tenant
+b2c ecdn zones list
+
+# JSON output
+b2c ecdn zones list --json
+
+# target a different tenant than the active config
+b2c ecdn zones list --tenant-id zzxy_prd
+```
+
+### Create a Storefront Zone
+
+```bash
+# create a new storefront zone
+b2c ecdn zones create --domain-name example.com
+```
+
+### Purge Cache
+
+```bash
+# purge cache for specific paths
+b2c ecdn cache purge --zone my-zone --path /products --path /categories
+
+# purge by cache tags
+b2c ecdn cache purge --zone my-zone --tag product-123 --tag category-456
+```
+
+### Manage Certificates
+
+```bash
+# list certificates for a zone
+b2c ecdn certificates list --zone my-zone
+
+# add a new certificate
+b2c ecdn certificates add --zone my-zone --hostname www.example.com --type custom --certificate-file ./cert.pem --private-key-file ./key.pem
+
+# validate a custom hostname
+b2c ecdn certificates validate --zone my-zone --custom-hostname-id abc123
+```
+
+### Manage Rate Limiting Rules
+
+```bash
+# list rate limiting rules
+b2c ecdn rate-limit list --zone my-zone
+
+# create a rate limiting rule
+b2c ecdn rate-limit create --zone my-zone --description "Rate limit /checkout" --expression '(http.request.uri.path matches "^/checkout")' --characteristics cf.unique_visitor_id --action block --period 60 --requests-per-period 50 --mitigation-timeout 600
+
+# get a rule
+b2c ecdn rate-limit get --zone my-zone --rule-id 2c0fc9fa937b11eaa1b71c4d701ab86e
+
+# update a rule
+b2c ecdn rate-limit update --zone my-zone --rule-id 2c0fc9fa937b11eaa1b71c4d701ab86e --requests-per-period 100
+
+# delete a rule
+b2c ecdn rate-limit delete --zone my-zone --rule-id 2c0fc9fa937b11eaa1b71c4d701ab86e --force
+```
+
+### Security Settings
+
+```bash
+# get security settings
+b2c ecdn security get --zone my-zone
+
+# update security settings
+b2c ecdn security update --zone my-zone --security-level medium --always-use-https --tls13
+```
+
+### Speed Settings
+
+```bash
+# get speed optimization settings
+b2c ecdn speed get --zone my-zone
+
+# update speed settings
+b2c ecdn speed update --zone my-zone --brotli on --http3 on --webp on
+```
+
+## Additional Topics
+
+For less commonly used eCDN features, see the reference files:
+
+- **[SECURITY.md](references/SECURITY.md)** — WAF (v1 and v2), custom firewall rules, rate limiting, and Page Shield (CSP policies, script detection, notification webhooks)
+- **[ADVANCED.md](references/ADVANCED.md)** — Logpush jobs, MRT routing rules, mTLS certificates, cipher suite configuration, and origin header modification
+
+## Configuration Overrides
+
+The tenant ID can be overridden via flag or environment variable:
+
+- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json
+
+The `--zone` flag accepts either:
+
+- Zone ID (32-character hex string)
+- Zone name (human-readable, case-insensitive lookup)
+
+### OAuth Scopes
+
+| Operation        | Required Scope      |
+| ---------------- | ------------------- |
+| Read operations  | `sfcc.cdn-zones`    |
+| Write operations | `sfcc.cdn-zones.rw` |
+
+### More Commands
+
+See `b2c ecdn --help` for a full list of available commands and options in the `ecdn` topic.

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

@@ -0,0 +1,97 @@
+# eCDN Advanced Reference
+
+Logpush, MRT rules, mTLS, cipher suites, and origin header commands for B2C eCDN.
+
+> `tenantId` resolves from `dw.json` / `SFCC_TENANT_ID`. Add `--tenant-id` only to override the active config.
+
+## Logpush
+
+```bash
+# create ownership challenge for S3 destination
+b2c ecdn logpush ownership --zone my-zone --destination-path 's3://my-bucket/logs?region=us-east-1'
+
+# list logpush jobs
+b2c ecdn logpush jobs list --zone my-zone
+
+# create a logpush job
+b2c ecdn logpush jobs create --zone my-zone --name "HTTP logs" --destination-path 's3://my-bucket/logs?region=us-east-1' --log-type http_requests
+
+# update a logpush job (enable/disable)
+b2c ecdn logpush jobs update --zone my-zone --job-id 123456 --enabled
+
+# delete a logpush job
+b2c ecdn logpush jobs delete --zone my-zone --job-id 123456
+```
+
+## MRT Rules
+
+```bash
+# get MRT ruleset for a zone
+b2c ecdn mrt-rules get --zone my-zone
+
+# create MRT rules to route to a Managed Runtime environment
+b2c ecdn mrt-rules create --zone my-zone --mrt-hostname customer-pwa.mobify-storefront.com --expressions '(http.host eq "example.com")'
+
+# update MRT ruleset hostname
+b2c ecdn mrt-rules update --zone my-zone --mrt-hostname new-customer-pwa.mobify-storefront.com
+
+# delete MRT ruleset
+b2c ecdn mrt-rules delete --zone my-zone
+```
+
+## mTLS Certificates
+
+Code upload certificates enable two-factor (mTLS) code upload to staging instances (`_stg` tenants only). There are two kinds: CAs registered with eCDN for the tenant (typically one, but several can be active, e.g. during renewal), which only sign certificates; and client certificates (`.p12`) signed by a CA (typically one per CI pipeline or developer, any number allowed), which the CLI sends on code upload. CI pipelines are the primary use case. Use `create --generate --name <ca-label> --client-name <pipeline>` once to create + register the CA and issue the first (CI) client cert, then `issue` for each additional pipeline/developer. `setup` is a guided, interactive version of `create --generate` with defaults and an optional dw.json update. `create` with `--certificate-file`/`--private-key-file` registers a bring-your-own CA. The code upload hostname is provisioned by Salesforce and linked automatically; users don't configure it. The CA private key must be kept secret (treat like a password); the CA certificate bundle must have a maximum validity of 1 year and be renewed before expiry. On Hyperforce, use the `staging-<realm>-<customer>.demandware.net` code upload hostname (not legacy `cert.staging.*`).
+
+For the complete workflow, security guidance, and renewal instructions, see [Deploying to Hyperforce: Set Up Two-Factor Code Upload](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/hyperforce.md#set-up-two-factor-code-upload) (`b2c docs read guide-hyperforce`).
+
+```bash
+# typically once per tenant: generate + register CA, issue first client cert (e.g. for CI)
+b2c ecdn mtls create --name code-upload --generate --client-name github-actions
+b2c ecdn mtls create --name code-upload --generate --out-dir ./certs --client-name github-actions
+
+# guided/interactive version of create --generate (prompts, defaults, optional dw.json update)
+b2c ecdn mtls setup
+
+# upload an existing CA
+b2c ecdn mtls create --name code-upload --certificate-file ./ca.pem --private-key-file ./ca.key
+
+# issue a client certificate per CI pipeline / developer (local-only, no API call)
+b2c ecdn mtls issue --ca-cert-file ./certs/ca.pem --ca-key-file ./certs/ca.key --name jane.doe
+b2c ecdn mtls issue --ca-cert-file ca.pem --ca-key-file ca.key --name ci --output ci.p12 --days 90
+
+# list uploaded CA certificates
+b2c ecdn mtls list
+
+# get certificate details
+b2c ecdn mtls get --certificate-id abc123
+
+# delete a CA certificate (uploaded CA stops accepting client certs)
+b2c ecdn mtls delete --certificate-id abc123
+```
+
+## Cipher Suites
+
+```bash
+# get cipher suites configuration
+b2c ecdn cipher-suites get --zone my-zone
+
+# update to Modern cipher suite
+b2c ecdn cipher-suites update --zone my-zone --suite-type Modern
+
+# update to Custom cipher suite with specific ciphers
+b2c ecdn cipher-suites update --zone my-zone --suite-type Custom --ciphers "ECDHE-ECDSA-AES128-GCM-SHA256,ECDHE-RSA-AES128-GCM-SHA256"
+```
+
+## Origin Headers
+
+```bash
+# get origin header modification
+b2c ecdn origin-headers get --zone my-zone
+
+# set origin header modification (for MRT)
+b2c ecdn origin-headers set --zone my-zone --header-value my-secret-value
+
+# delete origin header modification
+b2c ecdn origin-headers delete --zone my-zone
+```