@salesforce/b2c-dx-mcp 2.1.1 → 3.0.0

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

@@ -0,0 +1,126 @@
+---
+name: b2c-scapi-custom
+description: Check custom SCAPI endpoint registration status using the b2c CLI. Use this skill whenever the user needs to verify that their custom API endpoints are registered and working, debug 404 or "endpoint not found" errors on custom APIs, or list custom API endpoints and their deployment status — even if they just say "my custom API returns 404" or "is my endpoint deployed".
+---
+
+# B2C SCAPI Custom APIs Skill
+
+Use the `b2c` CLI plugin to manage SCAPI Custom API endpoints and check their registration status.
+
+When B2C MCP is available, prefer `scapi_custom_apis_get_status` for registration
+and `scapi_schemas_list` for live contracts. For Admin custom API execution, read
+`skill://mcp/scapi/SKILL.md`; fetch the contract through `scapi.request` in the
+program before calling its endpoints. Schema reads need `sfcc.scapi-schemas`;
+execution needs the declared `c_*` scope. Shopper execution is unsupported.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli scapi custom status`).
+
+## Configuration
+
+Values like `tenantId`, `shortCode`, `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`/`--short-code` 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.
+
+## Tenant ID vs. Organization ID
+
+The tenant ID identifies your B2C Commerce instance. It is **not** the same as the organization ID:
+
+- **Tenant ID**: `zzxy_prd` (the `tenantId` value in dw.json, or `--tenant-id` override)
+- **Organization ID**: `f_ecom_zzxy_prd` (used in SCAPI URLs, has `f_ecom_` prefix)
+
+### Deriving Tenant ID from Hostname
+
+For sandbox instances, derive the tenant ID from the hostname by replacing hyphens with underscores:
+
+| Hostname                                   | Tenant ID  |
+| ------------------------------------------ | ---------- |
+| `zzpq-013.dx.commercecloud.salesforce.com` | `zzpq_013` |
+| `zzxy-001.dx.commercecloud.salesforce.com` | `zzxy_001` |
+| `abcd-dev.dx.commercecloud.salesforce.com` | `abcd_dev` |
+
+For production instances, use your realm and instance identifier (e.g., `zzxy_prd`).
+
+## Examples
+
+### Get Custom API Endpoint Status
+
+```bash
+# list all Custom API endpoints for the configured tenant
+b2c scapi custom status
+
+# list with JSON output
+b2c scapi custom status --json
+
+# target a different tenant than the active config
+b2c scapi custom status --tenant-id zzxy_prd
+```
+
+### Filter by Status
+
+```bash
+# list only active endpoints
+b2c scapi custom status --status active
+
+# list only endpoints that failed to register
+b2c scapi custom status --status not_registered
+```
+
+### Group by Type or Site
+
+```bash
+# group endpoints by API type (Admin vs Shopper)
+b2c scapi custom status --group-by type
+
+# group endpoints by site
+b2c scapi custom status --group-by site
+```
+
+### Customize Output Columns
+
+```bash
+# show extended columns (includes error reasons, sites, etc.)
+b2c scapi custom status --extended
+
+# select specific columns to display
+b2c scapi custom status --columns type,apiName,status,sites
+
+# available columns: type, apiName, apiVersion, cartridgeName, endpointPath, httpMethod, status, sites, securityScheme, operationId, schemaFile, implementationScript, errorReason, id
+```
+
+### Debug Failed Registrations
+
+```bash
+# quickly find and diagnose failed Custom API registrations
+b2c scapi custom status --status not_registered --columns type,apiName,endpointPath,errorReason
+```
+
+### Configuration Overrides
+
+The tenant ID and short code can be overridden via flags or environment variables:
+
+- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json
+- `--short-code` / `SFCC_SHORTCODE` / `shortCode` in dw.json
+
+### More Commands
+
+See `b2c scapi custom --help` for a full list of available commands and options.
+
+## OAuth Scopes (manual token minting)
+
+`b2c scapi custom status` injects the scopes it needs automatically — the domain scope `sfcc.custom-apis` plus the tenant scope `SALESFORCE_COMMERCE_API:<tenant_id>`. You don't pass these for the command itself.
+
+When you mint a token **by hand** (with `b2c auth token` or curl) to call a custom Admin API directly, that injection does **not** happen — you must list both the tenant scope and your scope(s) yourself. `b2c auth token` accepts multiple scopes (repeat `--auth-scope` or comma-separate):
+
+```bash
+# Token for calling a custom Admin API endpoint
+b2c auth token \
+  --auth-scope "SALESFORCE_COMMERCE_API:zzpq_013" \
+  --auth-scope c_my_admin_scope
+```
+
+A token missing the tenant scope returns 403. See `b2c:b2c-custom-api-development` (Testing Reference) for full request examples.
+
+## Related Skills
+
+- `b2c:b2c-custom-api-development` - Creating Custom API endpoints (schema, script, mapping)
+- `b2c-cli:b2c-code` - Deploying and activating code versions (triggers registration)

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

@@ -0,0 +1,12 @@
+[
+  {"query": "I deployed my custom API endpoint yesterday but it's returning 404 when I try to call it. How do I check if it actually got registered on the tenant?", "should_trigger": true},
+  {"query": "I have several custom API endpoints and I need to see which ones are successfully deployed vs which ones failed registration. Some of them aren't working and I need to understand why.", "should_trigger": true},
+  {"query": "After deploying my custom SCAPI endpoint, the status shows 'not_registered'. How do I figure out what went wrong with the registration process?", "should_trigger": true},
+  {"query": "We just pushed a new version of our loyalty points API to production and I need to verify the endpoint is live before the mobile team starts integrating. How do I confirm the registration went through?", "should_trigger": true},
+  {"query": "I'm getting intermittent 404s on one of our custom endpoints — sometimes it works, sometimes it doesn't. I want to check the current registration state across all our custom APIs to see if something is flaky or partially deployed.", "should_trigger": true},
+  {"query": "Our CI pipeline deploys custom endpoints and I want to add a post-deploy verification step that checks the registration status and fails the build if any endpoint isn't properly registered. What information can I get about the registration state?", "should_trigger": true},
+  {"query": "I want to create a new custom REST API endpoint that returns personalized product recommendations. What's the cartridge structure and how do I define the route?", "should_trigger": false},
+  {"query": "How do I call the standard Shopper Products API from my storefront JavaScript to get product details by ID?", "should_trigger": false},
+  {"query": "I need to configure OCAPI resource permissions to allow my external system to access order data via the Data API.", "should_trigger": false},
+  {"query": "I'm writing the server-side handler logic for a custom API endpoint. How do I access the request body and return a JSON response with proper error handling?", "should_trigger": false}
+]

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

@@ -0,0 +1,64 @@
+---
+name: b2c-scapi-schemas
+description: Browse and retrieve SCAPI OpenAPI schema specifications. Use this skill whenever the user needs to list available SCAPI APIs, inspect endpoint paths or request/response shapes, explore data models for products or orders, check which fields an API returns, or understand SCAPI versioning. Also use when looking up API details before building an integration -- even if they just say 'what fields does the product API return' or 'show me the SCAPI endpoints'.
+---
+
+# B2C SCAPI Schemas Skill
+
+Browse standard or tenant-specific SCAPI OpenAPI contracts.
+
+## Tool choice
+
+When B2C MCP is available, prefer offline `scapi_search` for standard Admin and
+Shopper contracts. Read `skill://mcp/scapi/SKILL.md` via resource or `skills_read`
+first; pass `skillRead: true`. Discover method/path/operationId, then selected
+inputs and fields. No credentials or live Schemas API access needed.
+
+Use `scapi_schemas_list` for live schemas, custom attributes, and custom APIs.
+For tenant fields, supply API family/name/version and `includeSchemas: true`.
+Custom-property expansion defaults to true; `expandAll: true` preserves full definitions.
+For large schemas, fetch/filter through code mode as described in the MCP SCAPI skill.
+Use `scapi_custom_apis_get_status` for registration status. Live schema access needs
+`sfcc.scapi-schemas`. Prefer a dedicated task tool for execution, otherwise
+`scapi_execute` supports Admin JSON calls with configured auth/scopes. For custom
+Admin endpoints, fetch the live contract through `scapi.request` in each program
+before calling it; follow the MCP SCAPI skill. Shopper and binary execution are
+unsupported. Use docs tools for semantics
+and limits rather than duplicating contract discovery.
+
+For CLI work, use `b2c scapi schemas list` and
+`b2c scapi schemas get <family> <name> <version>`; both use live access.
+CLI get expands custom properties by default; `--no-expand-custom-properties`
+requests the standard contract. MCP also defaults to expansion; disable it with
+`expandCustomProperties: false`. Known custom fields can be sent through standard
+Admin code-mode requests without a schema read or offline refresh.
+`config_inspect` is the masked MCP equivalent of `b2c setup inspect`.
+Read [CLI examples](references/CLI-EXAMPLES.md) for filters, selective expansion,
+custom properties, and file output. There is no CLI code-mode equivalent.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli scapi schemas list`).
+
+## Configuration
+
+Values like `tenantId`, `shortCode`, `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`/`--short-code` 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.
+
+## Tenant ID vs. Organization ID
+
+The tenant ID identifies your B2C Commerce instance for SCAPI calls. It is **not** the same as the organization ID:
+
+- **Tenant ID**: `zzxy_prd` (the `tenantId` value in dw.json, or `--tenant-id` override)
+- **Organization ID**: `f_ecom_zzxy_prd` (used in SCAPI URLs, has `f_ecom_` prefix)
+
+### Deriving Tenant ID from Hostname
+
+For sandbox instances, derive the tenant ID from the hostname by replacing hyphens with underscores:
+
+| Hostname                                   | Tenant ID  |
+| ------------------------------------------ | ---------- |
+| `zzpq-013.dx.commercecloud.salesforce.com` | `zzpq_013` |
+| `zzxy-001.dx.commercecloud.salesforce.com` | `zzxy_001` |
+| `abcd-dev.dx.commercecloud.salesforce.com` | `abcd_dev` |
+
+For production instances, use your realm and instance identifier (e.g., `zzxy_prd`).

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

@@ -0,0 +1,12 @@
+[
+  {"query": "I want to see all the available SCAPI APIs for my sandbox instance. How do I browse the full list of API families?", "should_trigger": true},
+  {"query": "I need to check what fields the product API returns before I build my integration. How do I inspect the full schema definition?", "should_trigger": true},
+  {"query": "What endpoints are available in the shopper-orders API? I want to see the paths and their request/response shapes.", "should_trigger": true},
+  {"query": "I'm trying to understand the SCAPI data model for baskets. How do I look up all the properties and nested objects?", "should_trigger": true},
+  {"query": "Before building a catalog sync, I need to check if there's a bulk product update endpoint available in the SCAPI admin APIs. How do I explore the schemas?", "should_trigger": true},
+  {"query": "I want to compare the schema versions between two SCAPI releases to see what changed in the product search response.", "should_trigger": true},
+  {"query": "I need to actually make a SCAPI call to search for products. What's the correct curl command to hit the shopper-search endpoint?", "should_trigger": false},
+  {"query": "How do I generate TypeScript interfaces from a local OpenAPI spec file I already have?", "should_trigger": false},
+  {"query": "I want to build a custom API client in the tooling SDK for a new SCAPI endpoint. How do I set up the OAuth middleware?", "should_trigger": false},
+  {"query": "How do I configure SLAS authentication for my headless storefront to get shopper tokens?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-scapi-schemas/references/CLI-EXAMPLES.md

@@ -0,0 +1,108 @@
+# SCAPI Schema CLI Examples
+
+
+### List Available Schemas
+
+```bash
+# list all available SCAPI schemas (uses configured tenant)
+b2c scapi schemas list
+
+# list with JSON output
+b2c scapi schemas list --json
+
+# target a different tenant than the active config
+b2c scapi schemas list --tenant-id zzxy_prd
+```
+
+### Filter Schemas
+
+```bash
+# filter by API family (e.g., product, checkout, search)
+b2c scapi schemas list --api-family product
+
+# filter by API name
+b2c scapi schemas list --api-name shopper-products
+
+# filter by status
+b2c scapi schemas list --status current
+```
+
+### Get Schema (Collapsed/Outline - Default)
+
+By default, schemas are output in a collapsed format optimized for context efficiency. This is ideal for agentic use cases and LLM consumption.
+
+```bash
+# get collapsed schema (paths show methods, schemas show names only)
+b2c scapi schemas get product shopper-products v1
+
+# save to file
+b2c scapi schemas get product shopper-products v1 > schema.json
+```
+
+### Get Schema with Selective Expansion
+
+Expand only the parts of the schema you need:
+
+```bash
+# expand specific paths
+b2c scapi schemas get product shopper-products v1 --expand-paths /products,/products/{productId}
+
+# expand specific schemas
+b2c scapi schemas get product shopper-products v1 --expand-schemas Product,ProductResult
+
+# combine expansions
+b2c scapi schemas get product shopper-products v1 --expand-paths /products --expand-schemas Product
+```
+
+### Get Full Schema
+
+```bash
+# get full schema without any collapsing
+b2c scapi schemas get product shopper-products v1 --expand-all
+```
+
+### List Available Paths/Schemas/Examples
+
+Discover what's available in a schema before expanding:
+
+```bash
+# list all paths in the schema
+b2c scapi schemas get product shopper-products v1 --list-paths
+
+# list all schema names
+b2c scapi schemas get product shopper-products v1 --list-schemas
+
+# list all examples
+b2c scapi schemas get product shopper-products v1 --list-examples
+```
+
+### Output Formats
+
+```bash
+# output as YAML
+b2c scapi schemas get product shopper-products v1 --yaml
+
+# output wrapped JSON with metadata (apiFamily, apiName, apiVersion, schema)
+b2c scapi schemas get product shopper-products v1 --json
+```
+
+### Custom Properties
+
+```bash
+# include custom properties (default behavior)
+b2c scapi schemas get product shopper-products v1
+
+# exclude custom properties
+b2c scapi schemas get product shopper-products v1 --no-expand-custom-properties
+```
+
+### Configuration Overrides
+
+The tenant ID and short code can be overridden via flags or environment variables:
+
+- `--tenant-id` / `SFCC_TENANT_ID` / `tenantId` in dw.json
+- `--short-code` / `SFCC_SHORTCODE` / `shortCode` in dw.json
+
+### More Commands
+
+See `b2c scapi schemas --help` for a full list of available commands and options.

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-site-import-export/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: b2c-site-import-export
+description: Author, validate, import, and verify B2C Commerce site archives and metadata XML; export selected data for inspection or migration.
+---
+
+# Site Archives
+
+Use `b2c job import` / `b2c job export` to transfer site archives. If `b2c` is
+unavailable, use `npx @salesforce/b2c-cli`.
+
+## Configuration and tool choice
+
+CLI and MCP share resolved configuration: `SFCC_*` variables (including project
+`.env`), project/shared `dw.json`, and plugins. `package.json` provides nonsecret
+defaults. Use `--project-directory` outside the target project. Inspect with
+`b2c setup inspect --json` or MCP `config_inspect`; keep secrets masked. Configured
+values normally make credential flags and manual `dw.json` reads unnecessary.
+For resolution issues, use `b2c-cli:b2c-config`.
+
+No dedicated MCP archive-transfer tool exists. Use the CLI for XML imports and
+exports, including settings absent from SCAPI contracts. MCP `scapi_execute` can
+manage supported Admin fields; a metadata record alone does not prove that
+promotion discounts or targeting rules are configured.
+
+## Import and verify
+
+1. Resolve the target site/catalog and intended change. Include only relevant
+   data in the archive; preserve unrelated settings and requested enabled state.
+2. Author XML in the platform archive layout. Check the relevant XSD with
+   `b2c docs schema <name>` (list names with `--list`), then validate locally.
+3. Import the directory or zip. The command waits by default; `--show-log` shows
+   job logs on failure. Check completion before retrying.
+4. Read back the affected fields. If the API omits them, export the matching data
+   unit and inspect the relevant XML records. A successful job alone is insufficient.
+
+```bash
+b2c job import ./archive --show-log
+b2c job export --site MySite --site-data campaigns_and_promotions --output ./verification
+```
+
+`--site` alone exports all site data; specify `--site-data` for focused work.
+Directory output retains the platform's generated `*_export` root. Do not overwrite
+an existing/applied migration. Exports may contain secrets or unrelated defaults;
+review and trim before committing, preserving XSD-required fields.
+
+## Focused references
+
+- Archive layout and XML workflows: [archive workflows](references/WORKFLOWS.md).
+- Attribute/type XML patterns: [metadata XML](references/METADATA-XML.md).
+- Remote imports, size splitting, and import-set options: [import options](references/IMPORT-OPTIONS.md).
+- Export flags, data units, and compact JSON results: [export reference](../b2c-job/references/EXPORT.md).
+- Ordered migrations, naming, history, and recovery: `b2c-cli:b2c-import-set-migrations`.
+- Service configuration XML: `b2c:b2c-webservices`.
+
+Jobs prefer SCAPI; `--api-backend auto` can fall back to OCAPI on supported
+rejections. Archive transfer uses WebDAV in either case. For job scopes, backend
+selection, and monitoring, use the relevant section of `b2c-cli:b2c-job`.

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-site-import-export/evals/trigger-evals.json

@@ -0,0 +1,14 @@
+[
+  {"query": "I need to add a 'loyaltyTier' attribute to the Customer profile on our sandbox. I've got some XML written but I'm not sure about the right directory structure or how to push it up to the instance.", "should_trigger": true},
+  {"query": "We have a folder with metadata XML and preferences files that define our feature flags. How do I get this imported onto our dev instance so the new attributes show up in Business Manager?", "should_trigger": true},
+  {"query": "I wrote a custom-objecttype-definitions.xml for a new object type and I need to import it to the sandbox. How do I structure the site archive folder and run the import with the CLI?", "should_trigger": true},
+  {"query": "I need to export the full site configuration from our staging instance so I can diff it against production before we go live. What's the best way to pull down all the metadata, preferences, and custom object definitions as XML files?", "should_trigger": true},
+  {"query": "We're setting up a new sandbox and I need to replicate the entire configuration from another instance — site preferences, custom attributes, payment methods, shipping configs, the works. How do I package all that into a site archive and import it?", "should_trigger": true},
+  {"query": "I have several numbered metadata archive folders and zip files that need to import in order, while later runs skip the ones already applied.", "should_trigger": true},
+  {"query": "Our data import completed and then the runner crashed before recording success. I want the next run to retry until a durable receipt exists.", "should_trigger": true},
+  {"query": "I have a sites/site_template/meta directory with a bunch of XML files but the import keeps failing with a schema validation error. The error message references system-objecttype-extensions.xml line 47. How do I debug what's wrong with my archive structure?", "should_trigger": true},
+  {"query": "I need to download the log files from my sandbox to debug a checkout error that happened this morning.", "should_trigger": false},
+  {"query": "How do I push my cartridge code changes up to the sandbox so I can test them? I've been editing files locally in my IDE.", "should_trigger": false},
+  {"query": "I want to import a product catalog from a CSV file with 10,000 SKUs. The CSV has columns for product ID, name, price, and image URL. What's the fastest way to get this data into the system?", "should_trigger": false},
+  {"query": "I need to deploy my updated SFRA cartridge code to the sandbox. I've made changes to controllers and templates in app_storefront_base. What's the upload command?", "should_trigger": false}
+]

package/node_modules/@salesforce/b2c-agent-plugins/b2c-cli/skills/b2c-site-import-export/references/IMPORT-OPTIONS.md

@@ -0,0 +1,118 @@
+# Import Options
+
+## Import Commands
+
+### Import Local Directory
+
+```bash
+# Import a local directory as a site archive (waits for completion by default)
+b2c job import ./my-site-data
+
+# Import and return immediately without waiting
+b2c job import ./my-site-data --no-wait
+
+# Import a local zip file
+b2c job import ./export.zip
+
+# Keep the archive on the instance after import
+b2c job import ./my-site-data --keep-archive
+
+# Show job log if the import fails
+b2c job import ./my-site-data --show-log
+```
+
+### Import Remote Archive
+
+```bash
+# Import an archive that already exists on the instance (in Impex/src/instance/)
+b2c job import existing-archive.zip --remote
+```
+
+### Apply an Ordered, Idempotent Import Set
+
+Use `job import-set` when site import/export archives must be applied in order and skipped after the instance records their successful import. By default, the command reads discovered cartridge metadata first and the migrations directory second. This section is a summary; for the full migration workflow — source exclusions, post-import README notes, import history, set IDs, CI/CD patterns, and recovery — use the dedicated `b2c-cli:b2c-import-set-migrations` skill.
+
+Cartridge metadata supports two project layouts:
+
+- A standard site import/export archive directly inside `metadata/`, applied as one archive.
+- An ordered collection of immediate child directories or `.zip` files inside `metadata/`, with each child applied as one archive.
+
+Use one layout consistently within a cartridge. Cartridges are ordered by name, their archives are ordered lexically, and every cartridge archive is considered before the explicit import-set directory. Every directory-based archive must contain at least one file; empty directory trees are rejected before upload. The explicit directory uses the ordered-child layout:
+
+```text
+migrations/
+├── 20260801T140000-add-preferences/
+│   ├── meta/
+│   └── sites/
+├── 20260802T091500-seed-content.zip
+└── README.md                       # ignored
+```
+
+Name every archive `YYYYMMDDTHHmmss-description`, using UTC for cross-time-zone teams. The timestamp supplies ordering and helps keep archive names unique across projects.
+
+```bash
+# Show pending and already-applied archives without writing anything
+b2c job import-set --dry-run
+
+# Apply the default ./migrations directory
+b2c job import-set
+
+# Ignore discovered cartridge metadata and apply only ./migrations
+b2c job import-set --no-cartridge-metadata
+
+# Ignore project directories recursively during source discovery
+b2c job import-set --import-set-exclude fixtures --import-set-exclude test/integration
+
+# Apply a different directory
+b2c job import-set ./data-migrations
+
+# Keep uploaded archives for inspection
+b2c job import-set --keep-archive
+```
+
+Important semantics:
+
+- After an archive succeeds, later runs against the same instance skip it, including runs from other machines.
+- The archive name determines whether it has run; changing its contents does not cause another import. Never edit an applied archive—add a new, later-sorting archive for each change.
+- An interrupted run can retry its current archive. Make every archive safe to apply more than once.
+- Only one runner applies a history at a time. Other runners wait and then skip work completed while they were waiting.
+- An inactive run becomes recoverable after 30 minutes by default. Adjust this with `--stale-lock-seconds`; use `--break-lock` only after confirming the previous runner has stopped.
+- `--timeout` applies to each archive import, `--poll-interval` controls job polling, and `--lock-poll-interval` controls waiting for another runner.
+- `--import-set-exclude` can be repeated or comma-separated. Paths are relative to the project directory and exclude the named source directory and all descendants. Configure the same project default with `b2c.importSetExclude` in `package.json`, `import-set-exclude` in `dw.json`, or `SFCC_IMPORT_SET_EXCLUDE`.
+
+The default directory is `./migrations`; it may be absent if discovered cartridges supply at least one metadata archive. The default history name is `migrations` and is shared across runs against the target instance, regardless of local path. Most users should omit `--set-id`; use it only when intentionally creating an independent history. Cartridge discovery is enabled by default; use `--no-cartridge-metadata` to opt out.
+
+To start over without deleting the previous history, use a new set ID and keep using it on subsequent runs:
+
+```bash
+b2c job import-set --set-id migrations-reset-20260818
+```
+
+To reset the default history in place, remove it and rerun the import set:
+
+```bash
+b2c webdav rm --root=impex b2c-cli/import-sets/migrations
+b2c job import-set
+```
+
+For a custom set ID, replace the final `migrations` path segment with that ID. Resetting in place permanently forgets which archives succeeded and makes every current archive pending again, so only use it when every archive is safe to reapply. `--break-lock` is for recovery and does not reset history.
+
+### Import Archives Larger Than the Instance Limit
+
+An instance rejects a single import archive above its size limit (typically 200 MB). Use `--split` on a directory import to import the data in multiple smaller parts:
+
+```bash
+# Split a large directory import into multiple archive parts
+b2c job import ./big-site-data --split
+
+# Tune the per-archive size limit (default 190mb; bare number is MiB)
+b2c job import ./big-site-data --split --max-size 150mb
+```
+
+How splitting works:
+
+- **Metadata/XML is imported first**, kept together in one archive when it fits (so internal references and dependency ordering resolve within a single import). If the XML alone is too large, it splits at top-level data-unit boundaries (`catalogs`, `libraries`, `sites`, `meta`, …) in dependency order — never splitting a single unit.
+- **Static assets** (files under a `static/` folder) are deferred into later archive parts, packed by compressed size. They attach to the catalogs/libraries created by the metadata import.
+- Parts import sequentially; the command stops on the first failure.
+
+If a single file, or a single data unit's XML, is larger than `--max-size` on its own, the command errors (a file is never split across archives). A normal directory import that exceeds the limit warns and recommends `--split`. `--split` cannot be combined with `--remote`, subset paths, or `--no-wait`.