@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

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

@@ -0,0 +1,75 @@
+# eCDN Security Reference
+
+WAF, firewall rules, rate limiting, and Page Shield commands for B2C eCDN.
+
+> `tenantId` resolves from `dw.json` / `SFCC_TENANT_ID`. Add `--tenant-id` only to override the active config.
+
+## WAF (Web Application Firewall)
+
+```bash
+# list WAF v1 groups
+b2c ecdn waf groups list --zone my-zone
+
+# update WAF v1 group mode
+b2c ecdn waf groups update --zone my-zone --group-id abc123 --mode on
+
+# list WAF v1 rules in a group
+b2c ecdn waf rules list --zone my-zone --group-id abc123
+
+# list WAF v2 rulesets
+b2c ecdn waf rulesets list --zone my-zone
+
+# update WAF v2 ruleset
+b2c ecdn waf rulesets update --zone my-zone --ruleset-id abc123 --action block
+
+# migrate zone to WAF v2
+b2c ecdn waf migrate --zone my-zone
+```
+
+## Firewall Rules
+
+```bash
+# list custom firewall rules
+b2c ecdn firewall list --zone my-zone
+
+# create a firewall rule
+b2c ecdn firewall create --zone my-zone --description "Block bad bots" --action block --filter '(cf.client.bot)'
+
+# update a firewall rule
+b2c ecdn firewall update --zone my-zone --rule-id abc123 --action challenge
+
+# reorder firewall rules
+b2c ecdn firewall reorder --zone my-zone --rule-ids id1,id2,id3
+```
+
+## Rate Limiting
+
+```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 "API rate limit" --threshold 100 --period 60 --action block --match-url '/api/*'
+
+# delete a rate limiting rule
+b2c ecdn rate-limit delete --zone my-zone --rule-id abc123
+```
+
+## Page Shield
+
+```bash
+# list Page Shield notification webhooks (organization level)
+b2c ecdn page-shield notifications list
+
+# create a notification webhook
+b2c ecdn page-shield notifications create --url https://example.com/webhook --secret my-secret --zones zone1,zone2
+
+# list Page Shield policies (zone level)
+b2c ecdn page-shield policies list --zone my-zone
+
+# create a CSP policy
+b2c ecdn page-shield policies create --zone my-zone --action allow --value script-src
+
+# list detected scripts
+b2c ecdn page-shield scripts list --zone my-zone
+```

package/content/guidance/b2c-cli/b2c-import-set-migrations/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: b2c-import-set-migrations
+description: Create and apply ordered, idempotent B2C Commerce site import/export archives from discovered cartridge metadata and project migrations using `b2c job import-set`. Use this opt-in project workflow for migrations built from focused instance exports, repeatable setup, onboarding, and CI/CD imports that apply once per instance. Also covers source exclusions, post-import README notes, resetting history, and recovering an interrupted run.
+---
+
+# Import Set Migrations Skill
+
+Use `b2c job import-set` to apply site import/export archives from discovered cartridge `metadata/` directories followed by project migrations. Each archive is applied once per instance and skipped on later runs. Re-running the command is the intended workflow for local setup, developer onboarding, and CI/CD.
+
+> [!IMPORTANT]
+> **This is an optional, opt-in, project-level approach — not a default workflow.** A project adopts it deliberately by keeping import-set sources with its code and running `b2c job import-set` from setup scripts or CI. Follow an existing project's conventions. If a project only uses occasional one-off site imports, use the `b2c-cli:b2c-site-import-export` skill instead.
+
+> **Tip:** If `b2c` is not installed globally, use `npx @salesforce/b2c-cli` instead (e.g., `npx @salesforce/b2c-cli job import-set`).
+
+## 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.
+
+`job import-set` requires both OAuth and WebDAV credentials. Run `b2c setup inspect` to confirm the resolved configuration; see the `b2c-cli:b2c-config` skill for precedence rules and troubleshooting.
+
+## Import Sources and Order
+
+The command considers cartridge metadata first, followed by the project migrations directory (`./migrations` by default). Discovered cartridges are ordered by name, and archives within each source are ordered lexically.
+
+A cartridge `metadata/` directory can use either layout:
+
+- If it resembles a standard site import/export archive, the entire `metadata/` directory is one archive.
+- Otherwise, each immediate child directory or `.zip` file is one archive, matching the migrations-directory behavior.
+
+Keep each cartridge in one form rather than mixing an archive layout with ordered children. Directory-based archives must contain at least one file.
+
+The project migrations directory contains immediate child directories and `.zip` files as archives. Hidden entries and other loose files are ignored:
+
+```text
+migrations/
+├── 20260801T140000-add-preferences/
+│   ├── README.md                   # post-import note for THIS archive (see below)
+│   ├── meta/
+│   │   └── system-objecttype-extensions.xml
+│   └── sites/
+│       └── RefArch/
+│           └── preferences.xml
+├── 20260802T091500-seed-content.zip
+└── README.md                       # top-level README is not an archive
+```
+
+Each archive directory (or the contents of each zip) uses the standard site import/export archive layout that `b2c job import` accepts. For archive structure and metadata XML patterns, see the `b2c-cli:b2c-site-import-export` skill.
+
+### Naming convention
+
+Name every ordered child archive `YYYYMMDDTHHmmss-description`, e.g. `20260801T140000-add-preferences`. Use UTC so ordering is stable across time zones. Names identify applied archives, so never edit or reuse a name after it has been applied; add a new, later-sorting archive instead.
+
+## Commands
+
+```bash
+# Preview: show pending vs. already-applied archives; writes nothing to the instance
+b2c job import-set --dry-run
+
+# Apply the default ./migrations directory (safe to repeat)
+b2c job import-set
+
+# Apply a different directory
+b2c job import-set ./data-migrations
+
+# Import project migrations without discovered cartridge metadata
+b2c job import-set --no-cartridge-metadata
+
+# Exclude project-relative source trees recursively
+b2c job import-set --import-set-exclude fixtures --import-set-exclude test/integration
+
+# Keep each uploaded archive on the instance after import (for inspection)
+b2c job import-set --keep-archive
+```
+
+### Flags
+
+| Flag                        | Description                                                                        | Default      |
+| --------------------------- | ---------------------------------------------------------------------------------- | ------------ |
+| `--dry-run`                 | Show pending and applied archives without locking, importing, or writing state     | `false`      |
+| `--keep-archive`, `-k`      | Keep each uploaded archive on the instance after import                            | `false`      |
+| `--[no-]cartridge-metadata` | Include imports from discovered cartridge `metadata/` directories                  | `true`       |
+| `--import-set-exclude`      | Exclude a project-relative directory recursively from source discovery; repeatable |              |
+| `--set-id`                  | Name an independent import history                                                 | `migrations` |
+| `--break-lock`              | Recover an interrupted import-set run immediately                                  | `false`      |
+| `--stale-lock-seconds`      | Consider an inactive import-set run recoverable after this many seconds            | `1800`       |
+| `--lock-poll-interval`      | Seconds between checks while waiting for another run                               | `3`          |
+| `--timeout`, `-t`           | Timeout in seconds for each individual import job                                  | No timeout   |
+| `--poll-interval`           | Job polling interval in seconds                                                    | `3`          |
+| `--show-log`                | Show the job log when an import fails                                              | `true`       |
+| `--json`                    | Emit machine-readable archive statuses and counts; suppress human output           | `false`      |
+
+### Source exclusions
+
+`--import-set-exclude` accepts repeated flags or comma-separated paths. Paths are relative to `--project-directory` or the current project and exclude the directory and all descendants from source discovery. The setting is also available as:
+
+- `import-set-exclude` in `dw.json`
+- `b2c.importSetExclude` in `package.json`, which is suitable for committed project defaults
+- comma-separated `SFCC_IMPORT_SET_EXCLUDE`
+
+Exclusions select source directories; they do not remove files from inside a selected archive.
+
+## Post-Import Notes (per-archive README)
+
+Some migrations require **manual follow-up** that cannot be captured in an archive — for example enabling an instance-specific site preference, wiring a service credential in Business Manager, or flipping a feature toggle after the data lands.
+
+Document these in a `README.md` (or `README`) file at the top of a directory-based archive, whether it comes from cartridge metadata or project migrations. After a run, the CLI prints the notes for archives it applied in a consolidated **Post-import notes** summary.
+
+```text
+migrations/
+└── 20260801T140000-add-preferences/
+    ├── README.md
+    ├── meta/
+    └── sites/
+```
+
+**`20260801T140000-add-preferences/README.md`:**
+
+```markdown
+# Add feature-X preferences
+
+Manual follow-up (per instance):
+
+1. In Business Manager, go to Merchant Tools > Site Preferences > Feature X.
+2. Set the API endpoint to the instance-specific value (not imported — differs per environment).
+3. Save and verify the storefront picks it up.
+```
+
+Behavior:
+
+- Notes are surfaced only for archives **applied in this run** (freshly imported). Archives already applied on the instance (skipped) do not repeat their notes, so the summary reflects only what just changed.
+- `--dry-run` shows the notes for **pending** archives as a preview, so you can review manual steps before committing to the import.
+- Only directory-based archives are scanned for a README; `.zip` archives are not. `README.md` takes precedence over `README`. An empty README produces no note.
+- The top-level README of the set directory itself is not an archive and is not printed — use it for human-facing docs about the set as a whole.
+- With `--json`, notes are not printed; each archive's note text is available in the JSON result instead.
+
+This is the idiomatic place to record "what a human must still do" for a migration — keep archive contents safe to reapply and push environment-specific manual work into the note.
+
+## Repeat Runs
+
+After each successful import, the target instance records that archive's name. Later runs skip it without comparing contents.
+
+Key rules:
+
+- An interrupted run can retry its current archive, so every archive must be safe to apply more than once.
+- Applied state is shared across developers, checkouts, and CI runners targeting the same instance.
+- Never edit an applied archive. Add a new, later-sorting archive for every change.
+- Keep names distinct within an import history; UTC timestamps make collisions unlikely.
+
+## Set IDs (namespaces)
+
+The default import history is named `migrations` and is shared by runs against the same instance, regardless of local directory path.
+
+Most projects should **omit `--set-id`**. Use it only to intentionally maintain an independent migration history on the same instance, or to preserve a legacy namespace whose archive names cannot follow the timestamp convention.
+
+## Concurrent Runs and Recovery
+
+Only one runner applies a given history at a time. Other runners wait and then skip archives completed while they were waiting.
+
+An interrupted run becomes recoverable after 30 minutes by default; tune this with `--stale-lock-seconds`. Use `--break-lock` when it must be recovered immediately.
+
+## Idiomatic Workflows
+
+### Local setup / onboarding
+
+Commit the cartridge metadata and/or `./migrations` sources to the repo. New developers point the CLI at their sandbox and run:
+
+```bash
+b2c job import-set --dry-run   # see what will apply
+b2c job import-set             # apply; read the post-import notes for manual steps
+```
+
+Running it again later applies only the migrations added since.
+
+### CI/CD
+
+Run `b2c job import-set` as a deploy step against staging/production. It is safe to run on every pipeline invocation — only unapplied archives import. Prefer `--json` to capture the applied/skipped counts and per-archive note text for logs or downstream summaries:
+
+```bash
+b2c job import-set --json > import-set-result.json
+```
+
+Concurrent pipeline runs coordinate automatically.
+
+### Adding a new migration
+
+1. Reserve a new name with the current UTC timestamp: `20260815T120000-add-loyalty-attrs/`.
+2. For hand-authored data, create that directory and put the site archive contents inside (`meta/`, `sites/`, etc.). For instance-owned data, use the direct export workflow below.
+3. If manual follow-up is needed, add a `README.md` describing it.
+4. Run `b2c job import-set --dry-run`, review the pending archive, and commit. The next apply run imports only unapplied archives.
+
+### Building a migration from an instance export
+
+When the desired state already exists on an instance, export it instead of reconstructing XML from memory. Load these related skills before acting:
+
+- `b2c-cli:b2c-config` to confirm the source instance.
+- `b2c-cli:b2c-job` for export data units and `--output` behavior.
+- `b2c-cli:b2c-site-import-export` for archive layout, XML patterns, and schema-valid trimming.
+- `b2c-cli:b2c-content` for selected Page Designer pages, components, content blocks, and assets.
+- `b2c:b2c-metadata` when editing system attributes, custom object definitions, or site preferences.
+
+Export directly into the import-set source tree and edit the resulting archive in place. A temporary review directory followed by a copy is optional, not the default.
+
+`b2c job export --output migrations` extracts the platform archive under a newly generated `*_export` directory. Rename that one new directory immediately to the reserved permanent migration name, before previewing or applying the import set:
+
+```bash
+b2c setup inspect -i <SOURCE_INSTANCE>
+
+# Site descriptor, including a site's cartridge path
+b2c job export \
+  --site <SITE_ID> \
+  --site-data site_descriptor \
+  --output migrations \
+  -i <SOURCE_INSTANCE>
+
+# Other focused examples
+b2c job export --site <SITE_ID> --site-data site_preferences --output migrations -i <SOURCE_INSTANCE>
+b2c job export --global-data meta_data --output migrations -i <SOURCE_INSTANCE>
+b2c job export --library <LIBRARY_ID> --output migrations -i <SOURCE_INSTANCE>
+
+# Rename the one newly generated archive root once, then edit it in place.
+mv migrations/<GENERATED_EXPORT_DIR> migrations/<YYYYMMDDTHHmmss>-<description>
+```
+
+For selected Page Designer/content items, preview the match set and point the focused exporter directly at the final migration directory; it writes archive-relative `libraries/` or site-library content without a generated wrapper:
+
+```bash
+b2c content export <CONTENT_ID> --library <LIBRARY_ID> --dry-run --show-tree -i <SOURCE_INSTANCE>
+b2c content export <CONTENT_ID> \
+  --library <LIBRARY_ID> \
+  --output migrations/<YYYYMMDDTHHmmss>-<description> \
+  -i <SOURCE_INSTANCE>
+```
+
+Add `--site-library` for a site-private library. After any export, inspect every file and remove unrelated data, generated `version.txt`, environment-specific values, and secrets—including encrypted or hashed password values. Preserve the standard archive-relative layout and keep schema-required companion fields; validate trimmed XML against the matching B2C XSD rather than assuming a partial document is valid.
+
+Never export over an existing or applied archive. Use a temporary directory only intentionally, such as when comparing multiple exploratory exports or when a tool cannot isolate a new archive safely under the import-set directory.
+
+## Resetting Import History
+
+There is no dedicated reset command. Prefer starting a separate history so the old one remains intact:
+
+```bash
+b2c job import-set --set-id migrations-reset-20260818
+```
+
+Continue using that set ID on future runs. To clear the default history in place instead, remove it through WebDAV and rerun:
+
+```bash
+b2c webdav rm --root=impex b2c-cli/import-sets/migrations
+b2c job import-set
+```
+
+For a custom set ID, replace the final path segment. Clearing history makes every current archive pending again, so use it only when all archives are safe to reapply. `--break-lock` recovers an interrupted run; it does not reset history.
+
+## Import Failure Recovery
+
+Fix the archive or target-instance problem and rerun. Archives already applied are skipped, and the failed archive retries. `--show-log` is enabled by default and displays the platform job log for a failed import.
+
+## Related Skills
+
+- `b2c-cli:b2c-site-import-export` - Single archive import/export, site-archive folder structure, and metadata XML patterns
+- `b2c-cli:b2c-job` - Running and monitoring jobs, including individual archive imports and `job search`/`job wait`
+- `b2c:b2c-metadata` - System object extensions, custom object definitions, and site preferences
+- `b2c-cli:b2c-webdav` - Clearing an import history when an in-place reset is required
+- `b2c-cli:b2c-config` - Resolving instance and credential configuration

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

@@ -0,0 +1,62 @@
+---
+name: b2c-job
+description: Run existing B2C Commerce jobs, monitor executions, inspect failures, rebuild search indexes, and import or export site archives with the CLI.
+---
+
+# Run and Monitor Jobs
+
+Use `b2c job` for existing jobs. To create job steps or author `jobs.xml`, use
+`b2c:b2c-custom-job-steps`. If `b2c` is unavailable, use `npx @salesforce/b2c-cli`.
+
+## Configuration and tool choice
+
+CLI and MCP share configuration: `SFCC_*` variables (including project `.env`),
+project/shared `dw.json`, and plugins; `package.json` provides nonsecret defaults.
+Use `--project-directory` when running outside the target project. Inspect with
+`b2c setup inspect --json` or MCP `config_inspect`; both mask secrets by default.
+Override configured values only when needed. For resolution issues, use `b2c-cli:b2c-config`.
+
+No dedicated MCP job tool exists. Prefer these CLI workflows for running/waiting
+on jobs and transferring archives. MCP `scapi_search`/`scapi_execute` can compose
+supported Admin requests; they do not replace the CLI's archive transfer workflow.
+
+## Run and inspect
+
+```bash
+b2c job run my-job --wait --timeout 600
+b2c job run my-job --wait -P key=value
+b2c job search --job-id my-job --count 5
+b2c job wait my-job execution-id --timeout 600
+b2c job log my-job --failed
+```
+
+`job run` returns immediately unless `--wait` is supplied. For raw system-job
+bodies, search indexing, standard step choices, execution deletion, and backend
+configuration: [run and monitor](references/RUN-AND-MONITOR.md).
+Deletion removes completed execution records; it does not cancel jobs.
+
+## Site archives
+
+```bash
+b2c job import ./archive --show-log
+b2c job export --site MySite --site-data campaigns_and_promotions --output ./export
+```
+
+Import/export wait by default and transfer files over WebDAV. Jobs prefer SCAPI
+(`sfcc.jobs.rw` for writes, `sfcc.jobs` for reads); `--api-backend auto` falls back
+on supported SCAPI rejections. See the backend section in the run/monitor reference
+if access fails. Check job outcome before retrying a write.
+
+Read only the relevant reference:
+
+- Import remote archives or directory subsets: [import options](references/IMPORT.md).
+- Choose export data units or output paths: [export](references/EXPORT.md).
+- Author/validate XML and verify imported settings: `b2c-cli:b2c-site-import-export`.
+- Apply ordered, tracked migrations: `b2c-cli:b2c-import-set-migrations`.
+
+## Output
+
+Normal CLI output suffices for status. For scripting, save large `--json` results
+to a file and print selected fields; keep the exit code and inspect failures.
+See [export](references/EXPORT.md), section `compact-results`. Avoid dumping full
+execution records or reading both JSON and human output for the same result.

package/content/guidance/b2c-cli/b2c-job/references/EXPORT.md

@@ -0,0 +1,115 @@
+# Export Site Archives
+
+## Compact Results
+
+Normal CLI output reports completion and the saved path. When scripting, save
+the full JSON and stderr to files; print only verification fields. For example:
+
+```bash
+b2c job export --site MySite --site-data campaigns_and_promotions \
+  --output ./verification --json > export-result.json 2> export-stderr.log
+archive_status=$?
+if [ "$archive_status" -eq 0 ]; then
+  jq '{localPath, archiveFilename, execution: (.execution | {id, execution_status, exit_status})}' export-result.json
+else
+  jq '{name, message, code}' export-result.json
+  tail -n 40 export-stderr.log
+  exit "$archive_status"
+fi
+```
+
+Keep full artifacts for investigation; do not print them alongside the projection.
+After an import/export failure, inspect job status/logs before retrying. For an
+import, the same approach reports execution status without `localPath`.
+
+## Export Commands
+
+The `job export` command exports data from a B2C Commerce instance as a site archive. You must specify at least one data unit to export.
+
+```bash
+# export global metadata
+b2c job export --global-data meta_data
+
+# export multiple global data units
+b2c job export --global-data meta_data,custom_types,locales
+
+# export a site with all site data
+b2c job export --site RefArch
+
+# export a site with specific site data units
+b2c job export --site RefArch --site-data content,site_preferences
+
+# export multiple sites
+b2c job export --site RefArch --site SiteGenesis --site-data campaigns_and_promotions
+
+# export catalogs
+b2c job export --catalog storefront-catalog
+b2c job export --catalog storefront-catalog,electronics-catalog
+
+# export libraries
+b2c job export --library RefArchSharedLibrary
+
+# export inventory lists
+b2c job export --inventory-list my-inventory
+
+# export price books
+b2c job export --price-book usd-sale-prices
+
+# combine multiple top-level categories
+b2c job export --site RefArch --site-data content --catalog storefront-catalog --global-data meta_data
+
+# full control via raw JSON data units configuration
+b2c job export --data-units '{"global_data":{"meta_data":true},"sites":{"RefArch":{"content":true}}}'
+
+# save to a specific output directory
+b2c job export --global-data meta_data -o ./my-export
+
+# save as a zip file without extracting
+b2c job export --global-data meta_data --zip-only
+
+# leave the archive on the instance without downloading
+b2c job export --global-data meta_data --no-download
+
+# keep the archive on the instance after downloading
+b2c job export --global-data meta_data --keep-archive
+
+# set a timeout (seconds)
+b2c job export --global-data meta_data --timeout 600
+```
+
+#### Output Directory Semantics
+
+When `--output` names a directory, the CLI extracts the downloaded platform zip as-is. Platform exports contain a generated top-level directory such as `<timestamp>_export`, so `--output migrations` creates `migrations/<generated>_export/...`; it does not merge data units directly into `migrations/`. If `--output` ends in `.zip`, the CLI writes that exact zip path instead.
+
+For an ordered import-set migration, export to the import-set directory, rename the one newly generated archive root once to its permanent ordered name, and then review and trim it in place:
+
+```bash
+b2c job export --site RefArch --site-data site_descriptor --output migrations
+mv migrations/<GENERATED_EXPORT_DIR> migrations/20260815T120000-update-site-descriptor
+b2c job import-set --dry-run
+```
+
+Do not require a temporary directory and copy step for export-based migrations. Never export over an existing or applied archive. See `b2c-cli:b2c-import-set-migrations` for naming, trimming, retry, and deployment rules, and `b2c-cli:b2c-site-import-export` for valid archive structure.
+
+#### Available Data Units
+
+**Top-level categories** (each takes one or more IDs via flags):
+
+| Flag               | Description                                                                    |
+| ------------------ | ------------------------------------------------------------------------------ |
+| `--site`           | Site IDs to export (use `--site-data` to pick specific units, defaults to all) |
+| `--catalog`        | Catalog IDs                                                                    |
+| `--library`        | Library IDs                                                                    |
+| `--inventory-list` | Inventory list IDs                                                             |
+| `--price-book`     | Price book IDs                                                                 |
+| `--global-data`    | Global data units (comma-separated names from the list below)                  |
+
+**Site data units** (use with `--site-data`):
+
+`ab_tests`, `active_data_feeds`, `all`, `cache_settings`, `campaigns_and_promotions`, `content`, `coupons`, `custom_objects`, `customer_cdn_settings`, `customer_groups`, `distributed_commerce_extensions`, `dynamic_file_resources`, `gift_certificates`, `ocapi_settings`, `payment_methods`, `payment_processors`, `redirect_urls`, `search_settings`, `shipping`, `site_descriptor`, `site_preferences`, `sitemap_settings`, `slots`, `sorting_rules`, `source_codes`, `static_dynamic_alias_mappings`, `stores`, `tax`, `url_rules`
+
+**Global data units** (use with `--global-data`):
+
+`access_roles`, `all`, `csc_settings`, `csrf_whitelists`, `custom_preference_groups`, `custom_quota_settings`, `custom_types`, `geolocations`, `global_custom_objects`, `job_schedules`, `job_schedules_deprecated`, `locales`, `meta_data`, `oauth_providers`, `ocapi_settings`, `page_meta_tags`, `preferences`, `price_adjustment_limits`, `services`, `sorting_rules`, `static_resources`, `system_type_definitions`, `users`, `webdav_client_permissions`
+
+For full control over the export configuration (including `catalog_static_resources`, `library_static_resources`, and `customer_lists`), use `--data-units` with a JSON string matching the `ExportDataUnitsConfiguration` shape.

package/content/guidance/b2c-cli/b2c-job/references/IMPORT.md

@@ -0,0 +1,43 @@
+# Import Site Archives
+
+### Import Site Archives
+
+The `job import` command waits for the import job to complete by default. The same command imports a **job definition** (`jobs.xml` at the archive root) that registers a new runnable job on the instance — for the `jobs.xml` structure (job/flow/step, step `type`, the required `<triggers>` element), see the [jobs.xml Reference](../../../../b2c/skills/b2c-custom-job-steps/references/JOBS-XML.md).
+
+```bash
+# import a local directory as a site archive (waits for completion by default)
+b2c job import ./my-site-data
+
+# import a local zip file
+b2c job import ./export.zip
+
+# import and return immediately without waiting for completion
+b2c job import ./my-site-data --no-wait
+
+# keep the archive on the instance after import
+b2c job import ./my-site-data --keep-archive
+
+# import an archive that already exists on the instance (in Impex/src/instance/)
+b2c job import existing-archive.zip --remote
+
+# show job log on failure
+b2c job import ./my-site-data --show-log
+
+# import only a subset of a directory (extra positionals are paths/globs
+# resolved against the directory; preserves layout inside the archive)
+b2c job import ./my-site-data sites/RefArch libraries/mylib
+b2c job import ./my-site-data 'libraries/**'
+```
+
+### Import Sets
+
+`job import-set` first applies site import/export archives from discovered cartridge `metadata/` sources, then applies archives in `./migrations`, and skips archives already recorded on the target instance:
+
+```bash
+b2c job import-set --dry-run
+b2c job import-set
+b2c job import-set --no-cartridge-metadata # only use ./migrations
+b2c job import-set --import-set-exclude fixtures # ignore this project subtree
+```
+
+`--import-set-exclude` can be repeated or comma-separated and can also be configured as `b2c.importSetExclude` in `package.json`, `import-set-exclude` in `dw.json`, or `SFCC_IMPORT_SET_EXCLUDE`. For the full migration workflow — archive layouts, timestamp naming, post-import README notes, retry behavior, reset options, concurrency, and recovery — use the `b2c-cli:b2c-import-set-migrations` skill.