documentation

name	documentation
description	Updating user guides, CLI reference, and API documentation for the B2C CLI project. Use when adding or changing CLI command docs, writing JSDoc for TypeDoc generation, updating Vitepress sidebar config, or creating new guide pages.
metadata	{"internal":true}

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.

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