documentation

This skill covers updating documentation for the B2C CLI project.

Documentation Structure

The project has three types of documentation:

docs/
├── guide/              # User guides (manually written)
│   ├── index.md
│   ├── installation.md
│   ├── authentication.md
│   └── configuration.md
├── cli/                # CLI reference (manually written)
│   ├── index.md
│   ├── code.md
│   ├── webdav.md
│   ├── jobs.md
│   └── ...
├── api/                # API reference (auto-generated)
│   └── *.md
└── .vitepress/         # Vitepress configuration
    └── config.mts

Documentation Types

1. User Guides (docs/guide/)

Purpose: Help users get started and understand concepts.

When to update:

• New features that need explanation
• Changes to installation or setup process
• New authentication methods
• Configuration changes

Example structure:

# Getting Started

Introduction to the topic.

## Prerequisites

- Node.js 22+
- pnpm

## Installation

\`\`\`bash
pnpm install -g @salesforce/b2c-cli
\`\`\`

## Next Steps

- [Authentication](./authentication.md)
- [Configuration](./configuration.md)

2. CLI Reference (docs/cli/)

Purpose: Document command syntax, flags, and usage examples.

When to update:

• New commands added
• Flags added, removed, or changed
• Command behavior changes
• New examples needed

Structure per command topic:

# Code Commands

Commands for managing code versions and cartridge deployment.

## b2c code deploy

Deploy cartridges to a B2C Commerce instance.

### Usage

\`\`\`bash
b2c code deploy [PATH] [FLAGS]
\`\`\`

### Arguments

| Argument | Description | Required | Default |
|----------|-------------|----------|---------|
| PATH | Path to cartridges directory | No | . |

### Flags

| Flag | Short | Description | Default |
|------|-------|-------------|---------|
| --server | -s | Instance hostname | - |
| --code-version | -v | Code version name | - |
| --cartridge | -c | Include specific cartridges | - |
| --exclude-cartridge | -x | Exclude cartridges | - |

### Examples

\`\`\`bash
# Deploy all cartridges in current directory
b2c code deploy --server dev01.example.com --code-version v1

# Deploy specific cartridges
b2c code deploy ./cartridges -c app_storefront -c app_custom

# Deploy excluding certain cartridges
b2c code deploy -x test_cartridge -x bm_extensions
\`\`\`

### Authentication

Requires WebDAV credentials (username/password) or OAuth.

3. API Reference (docs/api/)

Purpose: Document the SDK programmatic API.

This is auto-generated from TypeScript JSDoc comments using TypeDoc.

Never edit files in docs/api/ directly. Instead:

1. Update JSDoc comments in SDK source files
2. Run pnpm run docs:api to regenerate

Writing JSDoc for API Docs

Module-Level Documentation

Add to barrel files (index.ts):

/**
 * Authentication strategies for B2C Commerce APIs.
 *
 * This module provides various authentication mechanisms:
 * - OAuth 2.0 client credentials
 * - Basic authentication
 * - API key authentication
 *
 * @example
 * ```typescript
 * import { OAuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
 *
 * const auth = new OAuthStrategy({
 *   clientId: 'my-client',
 *   clientSecret: 'my-secret',
 * });
 * ```
 *
 * @module auth
 */

Class Documentation

/**
 * Client for WebDAV file operations on B2C Commerce instances.
 *
 * Supports uploading, downloading, and managing files in various
 * WebDAV roots (Cartridges, IMPEX, Logs, etc.).
 *
 * @example
 * ```typescript
 * const client = new WebDavClient(hostname, auth);
 * await client.put('Cartridges/v1/app_custom/file.js', content);
 * ```
 */
export class WebDavClient {
  /**
   * Creates a new WebDAV client.
   *
   * @param hostname - The B2C Commerce instance hostname
   * @param auth - Authentication strategy to use
   */
  constructor(hostname: string, auth: AuthStrategy) {}
}

Function Documentation

/**
 * Deploys cartridges to a B2C Commerce instance.
 *
 * Discovers cartridges in the specified path, creates a ZIP archive,
 * and uploads via WebDAV.
 *
 * @param instance - The B2C instance to deploy to
 * @param cartridgePath - Path containing cartridge directories
 * @param options - Deployment options
 * @returns Deployment result with uploaded cartridges
 *
 * @example
 * ```typescript
 * const result = await deployCartridges(instance, './cartridges', {
 *   include: ['app_storefront'],
 * });
 * console.log(result.cartridges);
 * ```
 *
 * @throws {DeploymentError} If deployment fails
 */
export async function deployCartridges(
  instance: B2CInstance,
  cartridgePath: string,
  options?: DeployOptions
): Promise<DeployResult> {}

Type Documentation

/**
 * Configuration for OAuth authentication.
 */
export interface OAuthConfig {
  /** OAuth client ID */
  clientId: string;

  /** OAuth client secret */
  clientSecret: string;

  /** OAuth scopes to request */
  scopes?: string[];
}

Building Documentation

# Generate API docs from JSDoc
pnpm run docs:api

# Start dev server (includes API generation)
pnpm run docs:dev

# Build static site
pnpm run docs:build

# Preview built site
pnpm run docs:preview

Guides Search Corpus (b2c docs)

Separate from the Vitepress site above, the SDK bundles a search index that powers b2c docs search / docs read and the MCP docs_* tools. For the Developer Center guides corpus, only lightweight metadata is bundled (packages/b2c-tooling-sdk/data/guides/index.json), including immediate parent and child relationships derived from the published TOCs; the page content itself is fetched live from developer.salesforce.com at read time.

Internal tooling corpus (tooling)

The internal tooling corpus is generated from every Markdown page under docs/guide/, docs/cli/, docs/mcp/, and docs/vscode-extension/. Do not maintain a per-page allowlist for these repository-owned docs. The generator discovers new pages automatically and skips only asset-folder README.md files and frontmatter redirects:

pnpm --filter @salesforce/b2c-tooling-sdk run generate:tooling-index

CI runs check:tooling-index and fails when the committed index is stale. The release workflow and SDK prepack regenerate the index as defense in depth. Because data/tooling/index.json ships in @salesforce/b2c-tooling-sdk, changes to the generated corpus require an SDK changeset.

Regenerate the index from a local clone of the commerce-cloud-docs content repo (defaults to ~/code/commerce-cloud-docs):

COMMERCE_DOCS_REPO=/path/to/commerce-cloud-docs \
  pnpm --filter @salesforce/b2c-tooling-sdk run generate:guides-index

Only TOC-referenced pages are indexed. The generator (scripts/generate-guides-index.ts) skips any .md file not linked from a guide table-of-contents YAML (e.g. b2c-commerce/guides/index.yml). Orphan files (old pages consolidated elsewhere, drafts) are not published by the docs site, so indexing them would yield dead 404 URLs.

Salesforce Help corpus (help-admin / help-merchant)

A second prose corpus covers help.salesforce.com Business Manager administration and merchandising content, sourced from a local clone of the content-commerce-cloud DITA repo (defaults to ~/code/content-commerce-cloud, override with CONTENT_COMMERCE_CLOUD_REPO). Unlike the guides, Help content is JS-rendered with no fetchable source, so the DITA is converted to Markdown and packed into the committed docs/help-content.tar.gz (extracted into the docs site at build time), with the lightweight index at packages/b2c-tooling-sdk/data/help/index.json:

CONTENT_COMMERCE_CLOUD_REPO=/path/to/content-commerce-cloud \
  pnpm --filter @salesforce/b2c-tooling-sdk run generate:help-corpus

Source provenance (delta tracking)

Both prose indexes record the upstream git commit they were generated from in a source block at the top of index.json:

"source": { "sha": "<full-sha>", "committedAt": "<ISO date>", "ref": "<branch>" }

Only these opaque values are stored — deliberately no repository URL — so no internal host name or maintainer credential lands in the published package (captured by scripts/source-provenance.ts).

Corpora sourced from the DWAPP archive (Script API, XSD schemas, job steps) are not git-backed, so instead of source they record the platform release: data/script-api/index.json and data/xsd/index.json carry a platformDocVersion (e.g. "DWAPP 26.8"), and data/job-steps/job-steps.json records the same under provenance.platformDocVersion. The version is parsed from the archive by refresh:docs-data and forwarded to generate:docs-index <version>; running that generator manually with no arg preserves whatever version is already committed (it never silently drops it).

Use the recorded SHA to see exactly what changed upstream before a refresh. In the relevant local clone:

# What guide content changed since the committed guides index was generated?
git -C ~/code/commerce-cloud-docs log --oneline <sha>..HEAD -- content/en-us

# What Help content changed since the committed help index was generated?
git -C ~/code/content-commerce-cloud log --oneline <sha>..HEAD -- content/ht/en-us

An empty log means the corpus is already current with that clone; otherwise the listed commits are the delta a regeneration will pick up. Always re-run enrich:docs (missing-only) after a guides refresh so new pages get summaries/keywords, then re-run generate:guides-index to merge them.

Verifying links (local only)

After regenerating, verify every URL in the index resolves:

pnpm --filter @salesforce/b2c-tooling-sdk run check:guides-links

Run this from a normal network / browser-capable connection. It is not a CI job: the docs CDN (Cloudflare) blanket-403s datacenter IPs, so it verifies nothing from GitHub-hosted runners (every URL comes back blocked). The script fails only on 404/410 (definitively gone); it treats 403/429/5xx/network errors as inconclusive and, if a run is dominated by them, warns and passes rather than reporting false failures. Always run it locally after touching the guides index.

TypeDoc Configuration

Located in typedoc.json:

{
  "entryPoints": [
    "packages/b2c-tooling-sdk/src/auth/index.ts",
    "packages/b2c-tooling-sdk/src/clients/index.ts",
    "packages/b2c-tooling-sdk/src/operations/code/index.ts"
  ],
  "out": "docs/api",
  "plugin": [
    "typedoc-plugin-markdown",
    "typedoc-vitepress-theme"
  ],
  "exclude": ["**/*.generated.ts"]
}

When adding new SDK modules, add their barrel file to entryPoints.

Vitepress Configuration

Located in docs/.vitepress/config.mts:

export default defineConfig({
  title: 'B2C CLI',
  base: '/b2c-developer-tooling/',

  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'CLI Reference', link: '/cli/' },
      { text: 'API Reference', link: '/api/' },
    ],

    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Installation', link: '/guide/installation' },
            { text: 'Authentication', link: '/guide/authentication' },
          ],
        },
      ],
      '/cli/': [
        {
          text: 'Commands',
          items: [
            { text: 'code', link: '/cli/code' },
            { text: 'webdav', link: '/cli/webdav' },
          ],
        },
      ],
    },
  },
});

When adding new CLI commands or guide pages, update the sidebar config.

Claude Code Skills (Plugin)

The skills/b2c-cli/skills/ directory contains skills that teach Claude about using the CLI commands. These are distributed via the plugin.

When to update:

• New CLI commands added
• Existing commands changed
• New usage patterns

Skill format:

---
name: b2c-<topic>
description: Brief description
---

# B2C <Topic> Skill

Overview of the command topic.

## Examples

### <Use Case>

\`\`\`bash
# Comment explaining the command
b2c <topic> <command> [args] [flags]
\`\`\`

### <Another Use Case>

\`\`\`bash
b2c <topic> <command> --flag value
\`\`\`

Documentation Update Checklist

When Adding a CLI Command

1. Update docs/cli/<topic>.md with command documentation
2. Update docs/.vitepress/config.mts sidebar if new topic
3. Update skills/b2c-cli/skills/b2c-<topic>/SKILL.md with examples

When Adding an SDK Module

1. Write module-level JSDoc in barrel file
2. Write JSDoc for all public classes, functions, types
3. Add entry point to typedoc.json if new module
4. Run pnpm run docs:api to regenerate

When Changing CLI Behavior

1. Update affected examples in docs/cli/*.md
2. Update affected examples in skills/b2c-cli/skills/*/SKILL.md
3. Update guide pages if conceptual changes

When Adding Configuration Options

1. Update docs/guide/configuration.md
2. Update relevant CLI command docs with new flags
3. Update skills with new flag examples

Navigation Structure

Top Navigation:

• Guide (/guide/)
• CLI Reference (/cli/)
• API Reference (/api/)

Sidebar:

• Contextual based on section
• API reference sidebar auto-generated from TypeDoc

Style Guidelines

• Use code blocks with language hints (bash, typescript)
• Include practical examples for every command/function
• Keep flag tables consistent across command docs
• Use relative links for internal references
• Avoid emojis unless specifically requested