docs: audit-driven repair of CLI reference, guides, and SDK JSDoc (#473)

Sweep across CLI/guide/API docs and SDK JSDoc to correct stale flags,
descriptions, and examples; fill in JSDoc on previously-undocumented
public exports so the typedoc-generated API reference covers the full
surface; add the missing operations/cap typedoc entry point.

Author: clavery

.changeset/doc-audit-and-jsdoc-pass.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-dx-docs': patch
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Documentation audit and repair pass: corrected stale CLI flag and command references across the CLI reference and guides, fixed broken examples (e.g. eCDN mTLS, sandbox `--no-*` flags, WebDAV `get` arguments), aligned SDK JSDoc with current signatures, and added the missing `operations/cap` typedoc entry point so the Commerce App SDK module appears in the API reference. Filled in JSDoc for previously undocumented public exports across the SDK (auth, clients, instance, logging, ods, mrt, cap, cip, debug, scaffold, schemas, skills, etc.) so the generated API docs cover the full public surface.

docs/api-readme.md

@@ -29,16 +29,22 @@ The SDK is organized into focused submodules that can be imported individually:
 ├── /operations/content  # Page Designer content export
 ├── /operations/cip      # Curated CIP analytics reports and SQL helpers
 ├── /operations/jobs     # Job execution, site archive import/export
+├── /operations/cap      # Custom API operations
 ├── /operations/logs     # Log tailing and retrieval
 ├── /operations/mrt      # Managed Runtime bundle operations
 ├── /operations/ods      # On-demand sandbox utilities
 ├── /operations/debug    # B2C Script Debugger (SDAPI + DAP adapter)
 ├── /operations/users    # Account Manager users
 ├── /operations/roles    # Account Manager roles
 ├── /operations/bm-roles # Business Manager roles
+├── /operations/bm-users # Business Manager users
 ├── /operations/orgs     # Account Manager organizations
 ├── /operations/sites    # Storefront site info and cartridge paths
 │
+├── /test-utils         # Testing utilities and helpers
+├── /telemetry          # Telemetry and analytics
+├── /ux                 # User experience utilities
+│
 ├── /slas                # SLAS helpers
 ├── /safety              # Safety-mode confirmation middleware
 ├── /discovery           # Instance discovery helpers
@@ -106,7 +112,8 @@ const {data} = await slasClient.GET('/tenants/{tenantId}/clients', {
 ### MRT Operations
 
 ```typescript
-import {pushBundle, ApiKeyStrategy} from '@salesforce/b2c-tooling-sdk';
+import {pushBundle} from '@salesforce/b2c-tooling-sdk/operations/mrt';
+import {ApiKeyStrategy} from '@salesforce/b2c-tooling-sdk/auth';
 
 const auth = new ApiKeyStrategy(process.env.MRT_API_KEY!);
 const result = await pushBundle(

docs/cli/account-manager.md

@@ -383,12 +383,11 @@ b2c am roles list [FLAGS]
 
 - ID
 - Description
-- Scope
-- Internal Role
+- Role Enum Name
 
 #### Extended Columns
 
-- Target Type
+- Permissions
 
 #### Examples
 
@@ -755,8 +754,7 @@ b2c am clients list [FLAGS]
 
 #### Extended Columns
 
-- Last Auth
-- Disabled
+None. All columns are available via the `--columns` flag.
 
 #### Examples
 

docs/cli/auth.md

@@ -39,6 +39,13 @@ export SFCC_CLIENT_ID=your-client-id
 b2c auth login
 ```
 
+### Flags
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (default: account.demandware.com) |
+| `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (comma-separated or repeated flag) |
+
 After a successful login, subsequent commands use the stored token until it expires or you run `b2c auth logout`.
 
 ## b2c auth logout
@@ -118,6 +125,12 @@ Uses `refresh_token` grant when a refresh token is stored, otherwise falls back
 b2c auth client renew
 ```
 
+### Flags
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname for OAuth (default: account.demandware.com) |
+
 ### Example
 
 ```bash
@@ -181,6 +194,13 @@ b2c auth token
 | `--client-secret` | `SFCC_CLIENT_SECRET` | Client Secret for OAuth |
 | `--auth-scope` | `SFCC_OAUTH_SCOPES` | OAuth scopes to request (can be repeated) |
 | `--account-manager-host` | `SFCC_ACCOUNT_MANAGER_HOST` | Account Manager hostname (default: account.demandware.com) |
+| `--short-code` | `SFCC_SHORTCODE` | SCAPI short code |
+| `--tenant-id` | `SFCC_TENANT_ID` | Organization/tenant ID |
+| `--auth-methods` | `SFCC_AUTH_METHODS` | Allowed auth methods in priority order (comma-separated): client-credentials, jwt, implicit, basic, api-key |
+| `--user-auth` | | Use browser-based user authentication (implicit OAuth flow) |
+| `--jwt-cert` | `SFCC_JWT_CERT` | Path to JWT certificate file (cert.pem) for JWT Bearer authentication |
+| `--jwt-key` | `SFCC_JWT_KEY` | Path to JWT private key file (key.pem) for JWT Bearer authentication |
+| `--jwt-passphrase` | `SFCC_JWT_PASSPHRASE` | Passphrase for encrypted JWT private key |
 
 ### Examples
 

docs/cli/bm.md

@@ -87,7 +87,7 @@ b2c bm roles list [--count <n>] [--start <n>] [--columns <cols>] [--extended]
 |------|-------------|
 | `--count`, `-n` | Number of roles to return (default 25) |
 | `--start` | Start index for pagination (default 0) |
-| `--columns`, `-c` | Comma-separated columns to display |
+| `--columns`, `-c` | Comma-separated columns to display. Available: `id`, `description`, `userCount`, `userManager` |
 | `--extended`, `-x` | Show all columns including extended fields |
 
 ```bash
@@ -275,7 +275,7 @@ b2c bm users list [--count <n>] [--start <n>] [--columns <cols>] [--extended]
 |------|-------------|
 | `--count`, `-n` | Number of users to return (default 25) |
 | `--start` | Start index for pagination (default 0) |
-| `--columns`, `-c` | Comma-separated columns to display |
+| `--columns`, `-c` | Comma-separated columns to display. Available: `login`, `email`, `name`, `disabled`, `locked`, `lastLogin`, `externalId` |
 | `--extended`, `-x` | Include extended columns (`lastLogin`, `externalId`) |
 
 ```bash
@@ -318,6 +318,10 @@ b2c bm users search [--search-phrase <text>] [--login <login>] [--email <email>]
 | `--sort-by` | Sort field (e.g. `last_login_date`) |
 | `--sort-order` | `asc` or `desc` |
 | `--query` | Raw OCAPI query JSON (overrides convenience flags) |
+| `--count`, `-n` | Number of users to return (default 25) |
+| `--start` | Start index for pagination (default 0) |
+| `--columns`, `-c` | Comma-separated columns to display. Available: `login`, `email`, `name`, `disabled`, `locked`, `lastLogin`, `externalId` |
+| `--extended`, `-x` | Include extended columns (`lastLogin`, `externalId`) |
 
 ```bash
 b2c bm users search --search-phrase smith

docs/cli/cap.md

@@ -230,6 +230,8 @@ b2c cap list [--site-id SITE_IDS]
 | `--site-id SITE_IDS` | `-s` | Site IDs to query (comma-separated). If omitted, queries all sites. |
 | `--timeout SECONDS` | `-t` | Timeout in seconds (default: no timeout) |
 | `--local` | `-l` | List locally detected Commerce App Packages (no instance required) |
+| `--columns COLS` | `-c` | Columns to display (comma-separated). Available columns: `path`, `id`, `name`, `version`, `domain`, `siteId`, `featureName`, `featureType`, `featureSource`, `installStatus`, `configStatus`, `installedAt` |
+| `--extended` | `-x` | Show all columns including extended fields |
 | `--json` | | Output result as JSON |
 
 ### Table Columns

docs/cli/cip.md

@@ -32,20 +32,21 @@ CIP commands use **OAuth client credentials only**.
 | --------------------- | ---------------------------------------------- |
 | Client ID             | `--client-id` or `SFCC_CLIENT_ID`              |
 | Client Secret         | `--client-secret` or `SFCC_CLIENT_SECRET`      |
-| Tenant (CIP instance) | `--tenant-id` / `--tenant` or `SFCC_TENANT_ID` |
+| Tenant (CIP instance) | `--tenant-id` or `SFCC_TENANT_ID`              |
 
 Your API client must include the **Salesforce Commerce API** role with a tenant filter that includes your target instance.
 
 ## Connection and Output Flags
 
-These flags are available on all CIP commands:
+These flags are available on `cip tables`, `cip describe`, `cip query`, and `cip report` subcommands:
 
 | Flag           | Description                           | Default                                       |
 | -------------- | ------------------------------------- | --------------------------------------------- |
 | `--format`     | Output format: `table`, `csv`, `json` | `table`                                       |
 | `--fetch-size` | Frame fetch size for paging           | `1000`                                        |
 | `--cip-host`   | CIP host override                     | `jdbc.analytics.commercecloud.salesforce.com` |
 | `--staging`    | Use staging analytics host            | `false`                                       |
+| `--json`       | Output result as JSON                 | `false`                                       |
 
 ## Query and Report Date Flags
 
@@ -243,4 +244,4 @@ Both `cip query` and report commands support:
 - `--format table` (default)
 - `--format csv` (writes CSV to stdout)
 - `--format json` (writes JSON to stdout)
-- `--json` (global JSON mode)
+- `--json` (global JSON mode; available on all CIP commands)

docs/cli/code.md

@@ -49,7 +49,12 @@ b2c code list
 
 ### Flags
 
-Uses [global instance and authentication flags](./index#global-flags).
+In addition to [global instance and authentication flags](./index#global-flags):
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--columns`, `-c` | Columns to display (comma-separated). Available: id, active, rollback, lastModified, cartridges | All columns |
+| `--extended`, `-x` | Show all columns including extended fields | `false` |
 
 ### Examples
 
@@ -116,8 +121,8 @@ In addition to [global flags](./index#global-flags):
 | `--activate`, `-a` | Activate code version after deploy | `false` |
 | `--reload`, `-r` | Reload (toggle activation to force reload) code version after deploy | `false` |
 | `--delete` | Delete existing cartridges before upload | `false` |
-| `--cartridge`, `-c` | Include specific cartridge(s) (can be repeated) | |
-| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (can be repeated) | |
+| `--cartridge`, `-c` | Include specific cartridge(s) (comma-separated or repeated) | |
+| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (comma-separated or repeated) | |
 
 ### Examples
 
@@ -183,8 +188,10 @@ In addition to [global flags](./index#global-flags):
 |------|-------------|---------|
 | `--output`, `-o` | Output directory for downloaded cartridges | `cartridges` |
 | `--mirror`, `-m` | Extract cartridges to their local project locations | `false` |
-| `--cartridge`, `-c` | Include specific cartridge(s) (can be repeated) | |
-| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (can be repeated) | |
+| `--cartridge`, `-c` | Include specific cartridge(s) (comma-separated or repeated) | |
+| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (comma-separated or repeated) | |
+
+**Note:** The `--mirror` and `--output` flags are mutually exclusive. You must use one or the other, not both. Use `--output` to extract all cartridges to a single directory, or use `--mirror` to extract each cartridge to its local project location.
 
 ### Examples
 
@@ -343,8 +350,8 @@ In addition to [global flags](./index#global-flags):
 
 | Flag | Description |
 |------|-------------|
-| `--cartridge`, `-c` | Include specific cartridge(s) (can be repeated) |
-| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (can be repeated) |
+| `--cartridge`, `-c` | Include specific cartridge(s) (comma-separated or repeated) |
+| `--exclude-cartridge`, `-x` | Exclude specific cartridge(s) (comma-separated or repeated) |
 
 ### Examples
 

docs/cli/content.md

@@ -179,6 +179,8 @@ In addition to [global flags](./index#global-flags):
 | `--components` | Include components in table output | `false` |
 | `--tree` | Show tree structure instead of table | `false` |
 | `--timeout` | Job timeout in seconds | |
+| `--columns`, `-c` | Columns to display (comma-separated). Available: id, type, typeId, children | All columns |
+| `--extended`, `-x` | Show all columns including extended fields | `false` |
 
 ### Examples
 
@@ -244,7 +246,7 @@ With `--json`, returns `{ data: [...] }` with each item containing `id`, `type`,
 
 ## b2c content validate
 
-Validate Page Designer metadefinition JSON files against bundled JSON schemas. This is a local-only command — no instance connection or authentication is required.
+Validate Page Designer metadefinition JSON files against schemas. This is a local-only command — no instance connection or authentication is required.
 
 The command auto-detects the schema type using file path conventions (`experience/pages/` → pagetype, `experience/components/` → componenttype) and falls back to inspecting the JSON properties. You can also specify the type explicitly with `--type`.
 

docs/cli/custom-apis.md

@@ -14,6 +14,10 @@ These flags are available on all Custom APIs commands:
 |------|---------------------|-------------|
 | `--tenant-id` | `SFCC_TENANT_ID` | (Required) Organization/tenant ID |
 | `--short-code` | `SFCC_SHORTCODE` | SCAPI short code |
+| `--client-id` | `SFCC_CLIENT_ID` | Account Manager API Client ID |
+| `--client-secret` | `SFCC_CLIENT_SECRET` | Account Manager API Client secret |
+
+Additional authentication flags (`--auth-methods`, `--user-auth`, `--account-manager-host`, `--jwt-cert`, `--jwt-key`, `--jwt-passphrase`) and logging flags (`--log-level`, `--debug`, `--jsonl`) are also available. See the [Authentication Guide](/guide/authentication#scapi-authentication) for credential configuration, or run any command with `--help` for the complete flag list.
 
 ## Authentication