documentation

# Documentation This skill covers documentation for the Agentic B2C Developer Toolkit. ## Audience and Framing - Public docs explain capabilities, installation, configuration, and security. Describe outcomes people can request from their assistant; keep agent tool choreography, runtime internals, and implementation rationale in agent skills or contributor docs. Include technical details when they affect a user's choice. - Write for junior developers and non-developer administrators. Lead with the task, benefit, and visible behavior; explain technical terms when needed for setup. Say "asks for approval" rather than "form elicitation" or "per-request confirmation." Keep protocol state, worker lifetimes, and execution budgets in contributor docs or agent skills. Shared features must cover CLI, IDE, and assistant use; reserve assistant-specific framing for the relevant sections. - Link to canonical Salesforce Developer Center or Help pages for platform setup, requirements, and behavior. Toolkit guides supplement those workflows with our CLI, MCP, IDE, and skills capabilities; avoid maintaining a competing setup sequence. For Storefront Next, lead with Business Manager storefront setup and reuse its resources; link to the template's push workflow for source deployments. Keep matching agent skills aligned with those recommendations. - Say "B2C Commerce" rather than "Commerce" alone. Use "IDE Extension" for the editor product. The TypeScript SDK is a supporting foundation, not a primary toolkit product alongside CLI, IDE, and AI tools. - MCP tool references use compact tool-name/capability tables, access requirements, meaningful limits, and example requests. Link shared configuration/authentication; MCP Configuration covers MCP-specific settings only. Put toolset availability in a consistent **Toolsets:** field directly below each tool-group heading, not in prose or repeated table columns. Use subgroups when tools have different availability. - Prefer plugin installation where supported; keep manual setup and toolset customization secondary. A brief linked mention of the Agent Plugins standard is useful; manifest/schema details are not installation guidance. - MCP exposes skill guidance through `skills_read`; it does not install those collections as native assistant skills. Separate skills installation is optional, supported alongside MCP or alone. Show collections before their install examples. - Keep optional project recommendations and copyable assistant instructions in `docs/guide/project-setup.md`. Link from product pages rather than duplicating the examples. Support standalone skills and MCP use; distinguish recommendations from installation requirements and generated project files. - Safety Mode guidance leads with supported B2C operations and practical CLI, MCP, and IDE examples. Distinguish blocked actions, supported confirmations, and assistant approvals. Describe first-match rule precedence precisely; put broader agent/tool boundaries in a short scope note, not the introduction. ## Shared Visual Patterns Use the globally registered `ExamplePrompt` component for requests a reader can give their assistant: ```markdown <ExamplePrompt> > Summarize this campaign's promotions and flag schedule conflicts. </ExamplePrompt> ``` Write example prompts as user outcomes, without MCP tool names, toolsets, or instructions to use code mode. Name and explain those capabilities in the surrounding documentation, not in the user's request. Prompts should sound like natural business or development requests. Do not make users ask for policy enforcement, explanations of tool failures, routine verification, or session cleanup; those belong to tools and skills. Include constraints only when they express a real user choice, such as keeping a product offline or reviewing a proposed fix before editing code. Keep blank lines around the Markdown quote so VitePress parses it. The component provides the upright "Example prompt" label, chat icon, tinted background, and italic prompt text. Preserve the quote in Markdown exports. Ordinary quotations, notes, terminal commands, and agent instructions do not use this treatment. - Reuse `AssistantInstall` for client tabs and the shared MCP setup partials for the MCP page and Install AI Tools dialog. Order: Claude, Codex, VS Code, Cursor, OpenCode, Gemini. Keep full instructions in rendered HTML for search and no-JS readers. Put supported install buttons inside their client tab, before instructions. - Use `DocCards` for capability links and `.workflow-feature` for an example prompt paired with an image. Add screenshots or diagrams where they explain a task, not to decorate every section. Use clearly labeled placeholders until real captures are available. Research screenshots in `design-references/` stay uncommitted. - Preserve the site's Salesforce colors and shared typography. Verify visual changes in the browser at desktop and mobile widths; source edits alone do not establish that icons, wrapping, or spacing render correctly. - For clickable screenshots outside `public/`, import the image in the page's `<script setup>` and bind the link's `:href` to that import. A plain Markdown link to the source image can work in dev but 404 after Vite hashes the asset. Check link targets in a production build with `DOCS_BASE_PATH=/pr-672/` (or another subpath), not only in the dev server. ### CLI Terminal Images Use Freeze for compact CLI output images beside the relevant command. Prefer read-only listings, searches, status checks, and local previews. Use real output; choose useful columns and supported result limits before capture. Local sample data is appropriate when labeled as a sample. Do not invent successful output or expose credentials, personal information, or customer data. Match the existing Custom API image: JetBrains Mono, 14px, `#171717` background, window controls, 12px corner radius, no outer background or shadow. Cyan prompts and restrained status colors are sufficient. Aim for a 700px logical frame and roughly 5-12 output lines. Freeze auto-sized PNGs render at 4x resolution; an explicit width disables that scaling, so use padding to keep shorter captures at a consistent width. Keep raw captures and render settings in the locally ignored `design-references/` directory. Keep capture scripts and instructions reusable across machines. Do not commit capture-session diaries, personal paths, or machine-specific activity notes. Publish reviewed PNGs under `docs/public/terminal/`. Link the image to its full size using `[](/terminal/name.png)`; describe the command's useful result and significant statuses in the alt text, not just "terminal screenshot." Identify sample data and consequential flags such as offline mode when needed to interpret the result. Avoid transcribing entire tables. The shared CSS limits display width to 680px. Keep copyable command examples in the page. Verify image readability and links on desktop, mobile, and a built site with a URL prefix. ## 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 ├── python/ # Python SDK guides (manually written) │ └── api/ # Python API reference (generated, committed) └── .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 ### 4. Python SDK (`docs/python/`) Purpose: Guides and API reference for the Python SDK (`python/b2c-tooling-sdk/`), served under `/python/`. It is a self-contained section with its own sidebar — don't mirror TypeScript examples into it or add Python tabs to the main guides. - **Guides** (`docs/python/*.md`) are hand-written. Link to the shared docs (`/guide/configuration`, `/cli/auth`, `/api/`) rather than re-explaining shared concepts. The guide sidebar is hand-maintained in `config.mts`. - **API reference** (`docs/python/api/`) is generated from the Python docstrings (sphinx style) by `python/b2c-tooling-sdk/scripts/generate_api_docs.py` (griffe; no import of the package) along with `docs/python/api/sidebar.json`. Unlike `docs/api/`, the output is **committed** so the docs build needs no Python; the Python SDK CI job runs the `--check` mode. Never edit `docs/python/api/` directly. Update the docstrings, then from `python/b2c-tooling-sdk/` run `make api-docs` (or `make api-docs-check`) and commit the result. New public subpackages must be added to `PAGES` in the script. Heading anchors are emitted in VitePress's slug form (lowercase, `_`/`.` → `-`) because VitePress rewrites cross-page `#hash` links that way. ## 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<DeployResult> {} ```` ### 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 ``` ## Hosted Builds `.github/workflows/docs-preview.yml` publishes unreleased docs from `main` at `/pr-next/` on the preview host after every push. PR previews use `/pr-<number>/` and are removed when the PR closes. Both build packages and the docs site; neither refreshes published release history from GitHub. To rebuild manually, dispatch the workflow with no inputs for `main`, or set `pr_number` for a PR (including drafts). The workflow always resolves the source commit explicitly. The preview URL is recorded in the workflow summary; PRs also receive a preview comment. Production docs remain tied to stable release tags through `deploy-docs.yml`. ## Agent Discovery on the Docs Site `docs/public/llms.txt` is a curated agent entrypoint: CLI installation via `npx`, MCP/plugin setup, installed docs and skills tools, then selected Markdown references. Keep installation first and details terse; do not expand it into an exhaustive index or `llms-full.txt` bundle. Update it when setup or core capabilities change. The footer and HTML `rel="describedby"` link expose `llms.txt`. Each page has a `rel="alternate"` Markdown link matching View as Markdown. Source Markdown is exported at its existing path, with shared includes expanded; directory pages use `index.md`. Links in `llms.txt` are relative to its location so stable, dev, and PR previews stay self-contained. Check those references against built files. ## Release Notes `/releases/` combines published product changes with optional authored Markdown. Documentation-only releases and Documentation sections do not appear. Shared changes appear once with product labels; dependency updates are expandable. Group changes with the same product labels into unordered lists. Authored highlights remain prose above the generated notes. Use one date heading per day for the right-side outline, followed by Older Releases. Keep the outline aligned with product filters. Do not show a total update count: this page covers a selected period, not the entire release history. Keep authored highlights human-facing: outcomes, relevant limits, and upgrade actions. Do not copy CI mechanics or package plumbing into public prose. - `docs/.vitepress/releases/seed.json` is the checked-in history since July 1, 2026, including related IDE and skills artifacts. Local and PR builds need no GitHub access. Change the starting point deliberately with `pnpm --filter @salesforce/b2c-dx-docs run releases:refresh --seed-since YYYY-MM-DD`. - `pnpm --filter @salesforce/b2c-dx-docs run releases:refresh` uses authenticated `gh` to fetch stable product releases since that date into ignored `live.json`. Production runs this on every deployment, including doc-only releases. A failed refresh stops deployment. Removing local `live.json` restores the seed view. - Add optional entries under `docs/releases/_entries/<slug>.md`: ```yaml --- title: Introducing SCAPI code mode date: 2026-09-15 products: [mcp] release: '@salesforce/b2c-dx-mcp@3.0.0' --- ``` Follow with ordinary Markdown (no Vue/HTML components). With `release`, the entry adds a highlight above that release's generated changes; it stays hidden until the exact tag is available. Omit `release` for a standalone announcement. Product IDs: `cli`, `ide`, `mcp`, `skills`, `mrt`, `sdk`. SDK is secondary. The VitePress dev server watches entry edits; restart it after an invalid entry. - Release rendering runs when VitePress loads its config, including direct `vitepress build`. Generated partials and Markdown exports are ignored; never hand-edit them. All notes are present in static HTML, local search, and the `/releases/index.md` export. Filters enhance the static content in the browser. - Run `pnpm --filter @salesforce/b2c-dx-docs run test:releases` for parser, merge, editorial, offline-generation, and strict TypeScript checks. The `.ts` scripts run via `tsx` and use the repository's shared ESLint rules in `lint:agent`. Run `pnpm --filter @salesforce/b2c-dx-docs run format:releases` after edits. Also check the page on desktop and mobile, product filters, Markdown export, and a build with a subpath base. ## Guides Search Corpus (`b2c docs`)