feat(cli,docs): add documentation links to CLI help and improve docs (#76)

* feat(cli): add documentation links to CLI help output

Add links to online documentation in CLI help output for both topics
and individual commands.

- Add withDocs() helper function to i18n module
- Update all topic descriptions in package.json with docs URLs
- Update all command descriptions to use withDocs() with anchored links

Example topic help output:
  $ b2c code --help
  Deploy and manage code versions on instances

  Docs: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/code.html

Example command help output:
  $ b2c code activate --help
  DESCRIPTION
    Activate or reload a code version

    Docs: https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/code.html#b2c-code-activate

* docs: improve CLI reference and authentication documentation

- Streamline auth.md with clearer credential requirements
- Update code.md with improved examples
- Add setup instructions to various CLI reference pages
- Expand authentication guide with detailed OAuth and WebDAV setup
- Minor fixes to configuration and other docs

Author: clavery

docs/cli/auth.md

@@ -88,85 +88,20 @@ b2c auth token | pbcopy  # macOS: copy to clipboard
 
 ## Authentication Overview
 
-The CLI supports multiple authentication methods depending on the operation.
+For complete authentication setup instructions, see the [Authentication Setup Guide](/guide/authentication).
 
-### Account Manager API Client (OAuth)
+### Quick Reference
 
-Most instance operations require an Account Manager API Client. The CLI supports two authentication methods:
+| Operation | Auth Required |
+|-----------|--------------|
+| [Code](/cli/code) deploy/watch | WebDAV credentials |
+| [Code](/cli/code) list/activate/delete, [Jobs](/cli/jobs), [Sites](/cli/sites) | OAuth + OCAPI configuration |
+| SCAPI commands ([eCDN](/cli/ecdn), [schemas](/cli/scapi-schemas), [custom-apis](/cli/custom-apis)) | OAuth + SCAPI scopes |
+| [ODS](/cli/ods), [SLAS](/cli/slas) | OAuth + appropriate roles |
+| [MRT](/cli/mrt) | API Key |
 
-| Auth Method | When Used | Role Configuration |
-|-------------|-----------|-------------------|
-| User Authentication | Only `--client-id` provided | Roles on your **user account** |
-| Client Credentials | Both `--client-id` and `--client-secret` provided | Roles on the **API client** |
+See [Configuration](/guide/configuration) for setting up credentials via environment variables or config files.
 
-```bash
-# User Authentication (opens browser for login)
-b2c ods list --client-id xxx
-
-# Client Credentials
-export SFCC_CLIENT_ID=my-client
-export SFCC_CLIENT_SECRET=my-secret
-b2c ods list
-```
-
-Used by:
-- Code management (`code list`, `code activate`, `code delete`)
-- Job operations (`job run`, `job search`, `job import`, `job export`)
-- Site operations (`sites list`)
-- ODS operations (requires `Sandbox API User` role)
-- SLAS operations (requires `SLAS Organization Administrator` or `Sandbox API User` role depending on auth method)
-
-### Basic Auth (WebDAV)
-
-WebDAV operations support Basic Auth using your Business Manager username and WebDAV access key:
-
-```bash
-export SFCC_USERNAME=my-user
-export SFCC_PASSWORD=my-webdav-access-key
-```
-
-Used by:
-- `code deploy` (file upload)
-- `code watch` (file upload)
-- `webdav` commands
-
-### MRT API Key
-
-Managed Runtime commands use a separate API key obtained from the MRT dashboard:
-
-```bash
-export SFCC_MRT_API_KEY=your-mrt-api-key
-```
-
-See [MRT Commands](./mrt#authentication) for details.
-
-### Mixed Authentication
-
-Some commands (like `code deploy` with `--reload`) require both OAuth and WebDAV access:
-
-```bash
-export SFCC_CLIENT_ID=my-client
-export SFCC_CLIENT_SECRET=my-secret
-export SFCC_USERNAME=my-user
-export SFCC_PASSWORD=my-access-key
-b2c code deploy --reload
-```
-
-### Configuration File
-
-Credentials can be stored in a `dw.json` file:
-
-```json
-{
-  "client-id": "my-client",
-  "client-secret": "my-secret",
-  "username": "my-user",
-  "password": "my-access-key"
-}
-```
-
-Use `--config` to specify a custom config file path, or `--instance` to select a named instance configuration.
-
-### Tenant Scope
-
-For ODS and SLAS operations, your API client must have tenant scope configured for the realm/organization you wish to manage. This is set up in Account Manager when creating or editing the API client.
+::: tip
+Each command page below documents its specific authentication requirements including required scopes.
+:::

docs/cli/code.md

@@ -6,6 +6,37 @@ description: Commands for deploying cartridges, activating code versions, and wa
 
 Commands for managing cartridge code on B2C Commerce instances.
 
+## Authentication
+
+Code commands use different authentication depending on the operation:
+
+| Operation | Auth Required |
+|-----------|--------------|
+| `code deploy`, `code watch` | WebDAV (Basic Auth or OAuth) |
+| `code list`, `code activate`, `code delete` | OAuth + OCAPI |
+
+### WebDAV Operations (deploy, watch)
+
+File upload operations require WebDAV access. Basic authentication is recommended:
+
+```bash
+export SFCC_USERNAME=your-bm-username
+export SFCC_PASSWORD=your-webdav-access-key
+```
+
+### OCAPI Operations (list, activate, delete)
+
+These commands require OAuth authentication with OCAPI permissions for the `/code_versions` resource configured in Business Manager.
+
+```bash
+export SFCC_CLIENT_ID=your-client-id
+export SFCC_CLIENT_SECRET=your-client-secret
+```
+
+For complete setup instructions including OCAPI configuration, see the [Authentication Guide](/guide/authentication).
+
+---
+
 ## b2c code list
 
 List all code versions on a B2C Commerce instance.
@@ -56,10 +87,6 @@ version2                  No        Yes       11/28/2024, 10:15:00 AM   15
 staging                   No        No        11/25/2024, 9:00:00 AM    12
 ```
 
-### Authentication
-
-This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding `SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET` environment variables.
-
 ---
 
 ## b2c code deploy
@@ -127,15 +154,6 @@ b2c code deploy
 
 Cartridges are discovered by searching for `.project` files (Eclipse project markers commonly used in SFCC development). The directory containing the `.project` file is considered a cartridge.
 
-### Authentication
-
-This command requires both WebDAV and OAuth authentication:
-
-- **WebDAV** (for file upload): Basic Auth (`--username`/`--password`) or OAuth
-- **OAuth** (for code version reload): `--client-id` and `--client-secret`
-
-Basic authentication is recommended for WebDAV operations due to better performance.
-
 ---
 
 ## b2c code activate
@@ -185,10 +203,6 @@ b2c code activate --code-version v2
 
 Use `--reload` when you've made changes via WebDAV and need the instance to pick up the changes without deploying again.
 
-### Authentication
-
-This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding environment variables.
-
 ---
 
 ## b2c code delete
@@ -230,10 +244,6 @@ b2c code delete old-version --force
 - You cannot delete the currently active code version
 - The command will prompt for confirmation unless `--force` is used
 
-### Authentication
-
-This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding environment variables.
-
 ---
 
 ## b2c code watch
@@ -301,11 +311,3 @@ Press `Ctrl+C` to stop watching.
 |----------|-------------|
 | `SFCC_UPLOAD_DEBOUNCE_TIME` | Debounce time in milliseconds (default: 100) |
 
-### Authentication
-
-This command requires both WebDAV and OAuth authentication:
-
-- **WebDAV** (for file upload): Basic Auth (`--username`/`--password`) or OAuth
-- **OAuth** (for determining active code version): `--client-id` and `--client-secret`
-
-Basic authentication is recommended for WebDAV operations due to better performance.

docs/cli/custom-apis.md

@@ -41,6 +41,8 @@ export SFCC_SHORTCODE=kv7kzm78
 b2c scapi custom status --client-id xxx --client-secret xxx --tenant-id zzxy_prd
 ```
 
+For complete setup instructions, see the [Authentication Guide](/guide/authentication#scapi-authentication).
+
 ---
 
 ## b2c scapi custom status

docs/cli/ecdn.md

@@ -35,6 +35,8 @@ eCDN commands require OAuth authentication with these scopes:
 | Read operations | `sfcc.cdn-zones` |
 | Write operations | `sfcc.cdn-zones.rw` |
 
+For complete setup instructions, see the [Authentication Guide](/guide/authentication#scapi-authentication).
+
 ---
 
 ## Zone Management

docs/cli/jobs.md

@@ -6,6 +6,40 @@ description: Commands for executing jobs, importing and exporting site archives,
 
 Commands for executing and monitoring jobs on B2C Commerce instances.
 
+## Authentication
+
+Job commands require OAuth authentication with OCAPI permissions.
+
+### Required OCAPI Permissions
+
+Configure these resources in Business Manager under **Administration** > **Site Development** > **Open Commerce API Settings**:
+
+| Resource | Methods | Commands |
+|----------|---------|----------|
+| `/jobs/*/executions` | POST | `job run` |
+| `/jobs/*/executions/*` | GET | `job run --wait`, `job wait` |
+| `/job_execution_search` | POST | `job search` |
+
+### WebDAV Access
+
+The `job import` and `job export` commands also require WebDAV access for file transfer.
+
+### Configuration
+
+```bash
+# OAuth credentials
+export SFCC_CLIENT_ID=your-client-id
+export SFCC_CLIENT_SECRET=your-client-secret
+
+# WebDAV (for import/export)
+export SFCC_USERNAME=your-bm-username
+export SFCC_PASSWORD=your-webdav-access-key
+```
+
+For complete setup instructions, see the [Authentication Guide](/guide/authentication).
+
+---
+
 ## b2c job run
 
 Execute a job on a B2C Commerce instance.
@@ -68,10 +102,6 @@ b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":[
 b2c job run sfcc-search-index-product-full-update --wait --body '{"site_scope":["RefArch"]}'
 ```
 
-### Authentication
-
-This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource.
-
 ---
 
 ## b2c job wait
@@ -114,10 +144,6 @@ b2c job wait my-job abc123-def456 --timeout 600
 b2c job wait my-job abc123-def456 --poll-interval 5
 ```
 
-### Authentication
-
-This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource.
-
 ---
 
 ## b2c job search
@@ -171,10 +197,6 @@ The command displays a table of job executions with:
 - Status
 - Start Time
 
-### Authentication
-
-This command requires OAuth authentication with OCAPI permissions for the `/job_execution_search` resource.
-
 ---
 
 ## b2c job import
@@ -229,10 +251,6 @@ b2c job import ./my-site-data --timeout 300
 - The archive is uploaded to `Impex/src/instance/` on the instance
 - By default, the archive is deleted after successful import (use `--keep-archive` to retain)
 
-### Authentication
-
-This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource and WebDAV access for file upload.
-
 ---
 
 ## b2c job export
@@ -317,6 +335,3 @@ When using `--global-data`, available types include:
 - `services` - Service configurations
 - And more (see OCAPI documentation)
 
-### Authentication
-
-This command requires OAuth authentication with OCAPI permissions for the `/jobs` resource and WebDAV access for file download.

docs/cli/mrt.md

@@ -48,7 +48,7 @@ MRT commands use API key authentication. The API key is configured in the Manage
 
 1. Log in to the [Managed Runtime dashboard](https://runtime.commercecloud.com/)
 2. Navigate to **Account Settings** > **API Keys**
-3. Create a new API key or use an existing one
+3. Copy your API key (or generate one if you haven't already)
 
 ### Configuration
 
@@ -64,6 +64,8 @@ Provide the API key via one of these methods:
 }
 ```
 
+For complete setup instructions, see the [Authentication Guide](/guide/authentication#managed-runtime-api-key).
+
 ---
 
 ## Organization Commands

docs/cli/ods.md

@@ -29,9 +29,9 @@ ODS commands require an Account Manager API Client.
 
 **Client Credentials**: Used when both `--client-id` and `--client-secret` are provided. The `Sandbox API User` role must be assigned to the API client.
 
-### Tenant Scope
+### Tenant Filter
 
-The API client must have tenant scope configured for the realm(s) you wish to manage. This is configured in Account Manager under the API client's **Organizations** section.
+The API client's roles must have a tenant filter configured for the realm(s) you wish to manage. In Account Manager, under each role (e.g., `Sandbox API User`), add the realm IDs you need to access to the **Tenant Filter**.
 
 ### Configuration
 
@@ -45,6 +45,8 @@ export SFCC_CLIENT_SECRET=my-secret
 b2c ods list
 ```
 
+For complete setup instructions, see the [Authentication Guide](/guide/authentication#account-manager-api-client).
+
 ---
 
 ## b2c ods list

docs/cli/scapi-schemas.md

@@ -37,6 +37,8 @@ export SFCC_SHORTCODE=kv7kzm78
 b2c scapi schemas list --client-id xxx --client-secret xxx --tenant-id zzxy_prd
 ```
 
+For complete setup instructions, see the [Authentication Guide](/guide/authentication#scapi-authentication).
+
 ---
 
 ## b2c scapi schemas list

docs/cli/sites.md

@@ -6,6 +6,28 @@ description: Commands for listing and managing storefront sites on B2C Commerce
 
 Commands for managing sites on B2C Commerce instances.
 
+## Authentication
+
+Sites commands require OAuth authentication with OCAPI permissions for the `/sites` resource.
+
+### Required OCAPI Permissions
+
+| Resource | Methods |
+|----------|---------|
+| `/sites` | GET |
+| `/sites/*` | GET |
+
+### Configuration
+
+```bash
+export SFCC_CLIENT_ID=your-client-id
+export SFCC_CLIENT_SECRET=your-client-secret
+```
+
+For complete setup instructions, see the [Authentication Guide](/guide/authentication).
+
+---
+
 ## b2c sites list
 
 List sites on a B2C Commerce instance.
@@ -55,6 +77,3 @@ Found 2 site(s):
     Status: online
 ```
 
-### Authentication
-
-This command requires OAuth authentication. Provide `--client-id` and `--client-secret` or set the corresponding `SFCC_CLIENT_ID` and `SFCC_CLIENT_SECRET` environment variables.