# Documentation > 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. - Skill: `salesforcecommercecloud/documentation` (Agent Skill) - Install (CLI): `npx skillmds@latest add salesforcecommercecloud/documentation` - Raw SKILL.md: https://api.skillmd.com/api/skills/salesforcecommercecloud/documentation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: salesforcecommercecloud (https://skillmd.com/u/salesforcecommercecloud) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/salesforcecommercecloud/documentation --- # 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: ```markdown # 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: ```markdown # 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`): ```typescript /** * 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 ```typescript /** * 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 ```typescript /** * 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 {} ``` ### Type Documentation ```typescript /** * 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 ```bash # 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: ```bash 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`): ```bash 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`: ```bash 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`: ```json "source": { "sha": "", "committedAt": "", "ref": "" } ``` 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 `; 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: ```bash # What guide content changed since the committed guides index was generated? git -C ~/code/commerce-cloud-docs log --oneline ..HEAD -- content/en-us # What Help content changed since the committed help index was generated? git -C ~/code/content-commerce-cloud log --oneline ..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: ```bash 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`: ```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`: ```typescript 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: ```markdown --- name: b2c- description: Brief description --- # B2C Skill Overview of the command topic. ## Examples ### \`\`\`bash # Comment explaining the command b2c [args] [flags] \`\`\` ### \`\`\`bash b2c --flag value \`\`\` ``` ## Documentation Update Checklist ### When Adding a CLI Command 1. Update `docs/cli/.md` with command documentation 2. Update `docs/.vitepress/config.mts` sidebar if new topic 3. Update `skills/b2c-cli/skills/b2c-/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