# Docsmith V2 > Build documentation from filled markdown intake forms. AI fetches knowledge from Notion/GitHub/GDrive/URL/files, drafts content, captures screenshots via browser walkthrough, translates to multiple locales, and deploys to Docusaurus. Layered intake (project + module). Re-run safe; source change detection via lock file. Commands: init, module, fetch, run, continue, audience, plan, voice, draft, edit, walkthrough, record, translate, verify, update, categorize, deploy, publish, intake-help, help. - Skill: `dangtran1003/docsmith-v2` (Agent Skill, multi-file: 28 files) - Install (CLI): `npx skillmds@latest add dangtran1003/docsmith-v2` - Raw SKILL.md: https://api.skillmd.com/api/skills/dangtran1003/docsmith-v2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: dangtran1003 (https://skillmd.com/u/dangtran1003) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/dangtran1003/docsmith-v2 --- # docsmith Documentation skill following the PRC-010 process. Standalone-first workspace; deploys to Docusaurus or other targets via preset. v1.5.0 introduces a **layered intake system** so BAs can configure docs by filling markdown forms (no YAML) — and an `update` command that detects when external knowledge sources change. Reading order: - This file (catalog of commands and high-level rules) - [intake-reference.md](intake-reference.md) — intake forms, layered config, `run`/`continue`/`update`/`fetch`/`module` commands, source fetching - [process-reference.md](process-reference.md) — PRC-010 process detail - [deploy-reference.md](deploy-reference.md) — deploy and categorize logic - [translate-reference.md](translate-reference.md) — translation block-level rules and review modes - [tools-reference.md](tools-reference.md) — browser automation reference ## Commands 20 commands. Most users typically run only `init`, `module`, `run`, and `deploy` for the happy path. | Command | Alias | Owner | Purpose | | --------------- | ----- | ------ | ------------------------------------------------------------------------------------------------------ | | `help` | `h` | — | Show this command reference | | `init` | `i` | **AI** | Initialize workspace: scaffold `documentation/intake/project.md`, folders, gitignore | | `module` | `m` | **AI** | Create / list / archive a module intake at `documentation/intake/modules/.md` | | `intake-help` | `ih` | — | Print intake field reference (what each section/field means, defaults) | | `fetch` | `f` | **AI** | Fetch external sources (Notion/GitHub/GDrive/URL/file). Updates cache + `sources.lock.yaml`. | | `run` | `r` | **AI** | Orchestrated pipeline: validate intake → fetch → audience → plan → voice → draft → edit → wt → record → translate. Pauses at the configured gate. | | `continue` | `c` | **AI** | Resume `run` after a gate (read `.run-state.yaml`) | | `audience` | — | **AI** | Generate audience profile from intake (use intake `Audience` section) | | `plan` | `pl` | **AI** | Generate documentation plan + sitemap from intake `Scope` | | `voice` | `vc` | **AI** | Generate voice chart from intake `Voice`. Quick mode by default; `--full` adds UX patterns + scorecard.| | `draft` | `dr` | **AI** | Draft docs in `documentation/drafts//`. Uses fetched sources as KB. | | `edit` | `ed` | **AI** | Self-review (5 passes). With `--from-review`, applies feedback file. | | `walkthrough` | `wt` | **AI** | Verify against live product + capture screenshots. Phases: VERIFY → gate → APPLY → CAPTURE. | | `record` | `rec` | **AI** | Record short tutorial videos from `` markers (browser screen recording) | | `translate` | `tr` | **AI** | Translate from source locale to each `locales.targets`. Batch review by default; `--per-block` opt-in. | | `verify` | `vf` | **AI** | 10-check audit (placeholders, voice score, links, glossary consistency, etc.) | | `update` | `up` | **AI** | Detect changed external sources; propose draft updates | | `categorize` | `cat` | **AI** | Generate `_category_.json` from sitemap (Docusaurus preset) | | `deploy` | `dep` | **AI** | Sync workspace to host project. `--dry-run`, `--target`, `--force`, `--locale`, `--sync-deletes`. | | `publish` | `pub` | Human | Final checklist: review deploy, `git commit && push` on target | ### Examples ``` /docsmith help /docsmith init # one-time setup /docsmith module instances # add a module /docsmith intake-help # browse intake field reference # Edit documentation/intake/project.md and modules/instances.md, then: /docsmith run # full pipeline, pauses at after-draft /docsmith continue # resume after review /docsmith deploy --dry-run /docsmith deploy # Update flow when sources change: /docsmith update # check all modules /docsmith update instances # one module ``` ## Process flow ``` init (once) → module (per module) → fill intakes → run → [pause: review] → continue → deploy → publish │ └─ Underlying stages (auto-chained by run): audience → plan → voice → draft → edit → walkthrough → [record] → translate → categorize ``` For multi-locale projects, `translate` runs as part of the pipeline and is required before `deploy`. Deploy with empty target locale drafts emits a warning. For maintenance: `/docsmith update` detects external source changes and proposes targeted re-drafts. ## Configuration v1.5.0 splits config into 3 layers: 1. **Defaults** — from preset (`standalone` or `docusaurus`) 2. **Project intake** — `documentation/intake/project.md` ([template](templates/PROJECT_INTAKE_TEMPLATE.md)) 3. **Module intake** — `documentation/intake/modules/.md` ([template](templates/MODULE_INTAKE_TEMPLATE.md)) Higher layers override lower for the same field. Sources are cumulative. Intake forms are markdown with checkboxes and backtick fields — no YAML to write. AI parses them deterministically. See [intake-reference.md](intake-reference.md) for parsing rules. A legacy `.docsmithrc.yaml` is still read for backward compat with v1.4.x but deprecated; new projects use intake forms only. ## Path scoping (safety) Every command validates that absolute write paths fall inside one of: - `documentation/` (workspace — includes `documentation/deployments/` audit trail and `documentation/.run-state/` orchestration state) - `deploy.target_path` from project intake (or `--target` override) — for `deploy` command only Writes outside these roots are rejected. This is the core safety guarantee. **Why deployments lives inside `documentation/`** (changed in v1.5.1): in in-place mode where `deploy.target_path = .`, having a top-level `deployments/` folder would clutter the host project root and risk colliding with user-named folders. Keeping it nested ensures docsmith's footprint at the project root is exactly one folder: `documentation/`. ## Re-run protocol (safety) Every command that produces output checks for existence first. If output exists: 1. **Update** (recommended for content) — read existing as KB, propose deltas, apply per item. Untouched content preserved verbatim. 2. **Overwrite** — discard existing (archived to `archive//`), generate fresh. Requires explicit "OVERWRITE" confirmation. 3. **Side-by-side** — keep both, new file gets suffix `-v2` / `-v3`. 4. **Cancel** — abort. Default: `prompt` (always ask). Configurable via intake `Auto-run behavior` or legacy `behavior.on_existing`. **Critical rule for Update mode**: read existing as canonical KB and propose deltas only (NEW / UPDATE / REMOVE / KEEP). Do NOT regenerate untouched sections — that loses team's manual edits. ## Command details ### `help` Print the command table above. No other action. ### `init` (AI) **Purpose**: scaffold a docsmith workspace at the current directory. One-time setup. **Pre-checks** (1.5.1+): 1. If a `documentation/` folder already exists at the current directory: - Inspect its contents. If it has files NOT matching docsmith's structure (e.g., user-authored docs), STOP and report. Suggest `--force` only after the user moves or backs up content. - If contents match docsmith structure (intake/, plan/, etc.) → re-run protocol gate. 2. If running in a directory with a `docusaurus.config.{js,ts,mjs}` AND user did NOT specify `--target`: - Suggest in-place mode and confirm with user - If confirmed: set `deploy.target_path = .` in pre-fill - If declined: ask for sibling target path 3. If running in a directory with a `package.json` AND no `docusaurus.config`: - This is an unrelated Node project. Confirm intent before scaffolding. 4. If running in a non-empty directory with no recognizable config: - List existing folders/files. Ask user to confirm or move first. Refuse to scaffold next to user content silently. **Behavior**: 1. Detect host project context (per pre-checks): `docusaurus.config.{js,ts,mjs}` present → suggest `docusaurus` preset; otherwise `standalone` 2. Inspect target if Docusaurus: read `/CLAUDE.md`, parse `docusaurus.config` for paths 3. Create directory structure (see § File organization below). All paths are inside `documentation/`. 4. Create or update `.gitignore` (1.5.1+): - If `.gitignore` exists at project root: APPEND a docsmith block (between `# BEGIN docsmith` and `# END docsmith` markers). Don't duplicate entries on re-run. - If no `.gitignore`: create one with the docsmith block. - Entries added: ``` # BEGIN docsmith documentation/.cache/ documentation/videos/raw/ documentation/.run-state/ # END docsmith ``` 5. Pre-fill `project.md` with detected values (product slug from package.json or directory name; deploy target from inspected Docusaurus path; etc.) 6. Print: "Workspace scaffolded. Edit documentation/intake/project.md, then run `/docsmith module ` for each feature area." **Flags**: - `--upgrade-from-1.4` — read existing `.docsmithrc.yaml` and pre-fill `project.md` from it; keep yaml for compat (deprecated) - `--force` — overwrite existing intake files (requires confirm) - `--in-place` — explicitly request in-place mode (skip prompt when in Docusaurus repo) - `--reformat-intake` — re-render existing intake files with current template (preserves filled values; backup at `.backup-pre-/`) - `--from-source ` (v1.5.9+) — AI auto-fills intake from source document(s). Multiple sources comma-separated. See "From-source mode" below. - `--resume` (v1.5.10+) — retry previously failed parallel sub-agents from last `init --from-source` run with >5 modules. Only applicable when last run reported partial completion. #### From-source mode (v1.5.9+) Use `--from-source` to skip manual intake authoring. AI reads BA doc / PRD / existing docs, infers fields, and writes `project.md`. Workflow: 1. **Fetch source(s)** using existing fetch logic (Notion / GitHub / GDrive / URL / file) 2. **Infer fields** by category: - **Facts** (high confidence): direct quotes from source — product name, audience role, module names, feature lists - **Guesses** (medium confidence): inferred from context — primary goal, voice tone, scope details. Marked `← AI guess` in intake - **Defaults** (no source data): conservative fallback per template default. Marked `← default applied` 3. **Interactive Q&A** for fields that source doesn't cover: - Source language (from BA doc language, but always asks to confirm) - Target locales (translation strategy) - Deploy preset and target path - Walkthrough credentials (env var names) - Voiceover strategy (if videos planned) - Pause gate preference for first run 4. **Write `project.md`** with inline `> Auto-filled from : ""` annotations and `← AI guess` markers on uncertain fields 5. **Detect modules** from source structure (sections, headings) and prompt user: "Create module intake for each? Y/N/select" 6. **Generate inference report** at `documentation/intake/.inference/-project.md` (see [templates/INTAKE_INFERENCE_REPORT_TEMPLATE.md](templates/INTAKE_INFERENCE_REPORT_TEMPLATE.md)) 7. **Print summary**: ``` ✓ Created project.md (8 facts, 4 guesses, 7 defaults, 3 asked) ✓ Detected 2 modules: instances, storage ⚠ 4 fields marked "← AI guess" — please verify before /docsmith run 📋 Inference report: documentation/intake/.inference/-project.md ``` **Re-run with `--from-source`** (when source updates): - Existing intake values that match AI's last inference → safe to re-infer - Existing intake values BA edited manually → preserved (hash check) - Show diff before applying. Re-run protocol gate (Update / Overwrite / Skip). ### `module` (AI) **Purpose**: manage module intake files. **Sub-commands**: ``` /docsmith module # create new module /docsmith module --from # clone from another module /docsmith module --from-source # AI auto-fill from source (v1.5.9+) /docsmith module list # list modules with status /docsmith module archive # mark as archived (skip in run) /docsmith module unarchive # un-archive ``` **Create behavior**: 1. Re-run protocol check on `documentation/intake/modules/.md` 2. Copy `templates/MODULE_INTAKE_TEMPLATE.md` to that path 3. Pre-fill module slug, display name from argument 4. If `--from `: copy non-identity fields from `` (sources, voice override, etc.) 5. If `--from-source `: AI auto-fills features and content types from source (same logic as `init --from-source` but scoped to one module). Generates inference report at `.inference/-.md`. Asks user about scope when ambiguous: "Source mentions 'snapshot' under Storage — include in this module's scope? Y/N" 6. Update project.md `Module intake files` section (between BEGIN/END MODULES LIST markers) 7. Print: "Module '' created. Edit and run `/docsmith run ` when ready." ### `intake-help` (—) Print intake field reference. No file changes. ``` /docsmith intake-help # all fields /docsmith intake-help product # one section /docsmith intake-help sources # source types and auth ``` For each field: name, what it controls, validation rules, default value. ### `fetch` (AI) **Purpose**: pull content from external knowledge sources declared in intakes. Manual; usually called automatically by `run` and `update`. **Prerequisites**: env vars set for any auth-required sources (Notion, private GitHub, GDrive). See [SETUP.md](../../SETUP.md) — section "Environment variables for sources and credentials". **Flags**: - (no args) — fetch all sources for project + all active modules - `--module ` — only this module - `--source ` — only this source **Per-type behavior**: see [intake-reference.md](intake-reference.md) § "External source fetching". After fetch: writes content to `documentation/.cache/sources/.{md,dir}`, updates `sources.lock.yaml`. ### `run` (AI) — orchestrated pipeline **Requires**: filled project + module intake; env vars set for sources/credentials in scope. **Workflow**: 1. Validate intakes (see [intake-reference.md](intake-reference.md) § Validation). Stop on critical errors. 2. Resolve layered config; snapshot to `documentation/deployments//resolved-config.yaml`. 3. Call `fetch` internally (uses lock file if recent). 4. Run pipeline stages in sequence: `audience` → `plan` → `voice` → `draft` → `edit` → `walkthrough` → `record` → `translate`. 5. Pause at the configured gate (default: `after-draft`). 6. Save state to `documentation/.run-state/.yaml` (per-module, not global — allows multiple modules to be in different stages simultaneously). For multi-module runs, each module gets its own state file. 7. Print resume instructions. **Flags**: - `[]` — single module instead of all - `--pause-at ` — override the configured pause point - `--from ` — start from a specific stage (e.g. `--from walkthrough` to skip planning) **Pause gates**: `after-plan`, `after-draft` (default), `before-walkthrough`, `after-walkthrough`, `before-deploy`, `never`. ### `continue` (AI) Resume from `documentation/.run-state/.yaml`. - `/docsmith continue` (no args): if exactly one module has paused state, resume it. If multiple, list them and ask which to resume. If none, error. - `/docsmith continue `: resume specific module's state. If state stale (>7 days) or workspace modified outside docsmith since last `run`, warn before resuming. ### `audience` / `plan` / `voice` / `draft` / `edit` Individual pipeline stages. Each: - Reads resolved config from intake - **Interactive fill** (v1.5.13+): if a stage requires an empty intake field, AI prompts user inline and writes the answer back to intake. Avoids upfront full-form fill. See [intake-reference.md § 10](intake-reference.md) for per-stage required fields and prompt format. - Re-run protocol applies (if output exists, gate) - Writes to its conventional output path - Returns control (does NOT chain to next stage; that's `run`'s job) **Skip prompts with `--no-prompt`**: any stage command accepts `--no-prompt` flag. Behavior: fail immediately if a required field is empty (old behavior). Useful for CI scripts that shouldn't pause for user input. Specific behaviors: **`audience`** — output: `documentation/plan/audience-profile.md` from [templates/AUDIENCE_PROFILE_TEMPLATE.md](templates/AUDIENCE_PROFILE_TEMPLATE.md). Uses intake `Audience` section. **`plan`** — outputs: `documentation/plan/documentation-plan.md` (from [templates/DOCUMENTATION_PLAN_TEMPLATE.md](templates/DOCUMENTATION_PLAN_TEMPLATE.md)) AND `documentation/plan/sitemap.md`. Uses intake `Scope` (from each module). Sitemap follows the project pattern (Pattern A/B/C from project intake § Sitemap pattern) and the per-module section selection. AI warns when a module is missing a section the project pattern includes, but doesn't auto-fix. See [templates/SITEMAP_PATTERNS_TEMPLATE.md](templates/SITEMAP_PATTERNS_TEMPLATE.md) for canonical section types and patterns. Flags: - `--migrate-sitemap` — for v1.5.3-or-earlier workspaces: AI proposes a pattern, asks to confirm, and updates project + module intakes to use the new sitemap system. **`voice`** — outputs: `documentation/standards/voice-chart.md` from [templates/VOICE_CHART_TEMPLATE.md](templates/VOICE_CHART_TEMPLATE.md). With `--full`, also generates UX text patterns and content scorecard (these were standard in v1.4.x; now opt-in for lean default). **`draft`** — outputs: `documentation/drafts///.md`. Reads cached sources from `.cache/sources/`. Uses [templates/CONTENT_TYPE_TEMPLATES.md](templates/CONTENT_TYPE_TEMPLATES.md). Image refs: workspace-absolute paths `/images//.png`. Caption rules per [templates/MEDIA_POLICY_TEMPLATE.md § 3.5](templates/MEDIA_POLICY_TEMPLATE.md). Video markers per [templates/VIDEO_SCRIPT_TEMPLATE.md § VIDEO marker](templates/VIDEO_SCRIPT_TEMPLATE.md). **`edit`** — five passes: voice match, UX patterns, clarity, accuracy markers, link/cross-ref. With `--from-review `, applies a reviewer's feedback file (Markdown with `// FEEDBACK:` annotations or block comments). ### `walkthrough` (AI) **Prerequisites**: browser automation tool (Claude in Chrome extension OR Playwright MCP) AND test account credentials set as env vars. See [SETUP.md](../../SETUP.md) — section "Path 1: Claude in Chrome" or "Path 2: Playwright MCP". **Interactive fill (v1.5.13+)**: if product URL or credentials env vars are empty in intake, AI prompts user inline and writes back. Verifies env vars are actually set in shell before proceeding. See [intake-reference.md § 10](intake-reference.md) — section "walkthrough" required fields. **Media policy**: respects screenshot density rules and per-locale strategy from project intake § 11 (and module intake § 8 overrides). Default behavior is "source-only" capture (one screenshot reused across all locales). See [templates/MEDIA_POLICY_TEMPLATE.md](templates/MEDIA_POLICY_TEMPLATE.md) for density rules per content type, style options, and aspect ratio. Three-phase pipeline: ``` A: VERIFY /docsmith wt --check → drift report (read-only) ↓ GATE Edit decisions.yaml (auto-fix / manual-fix / product-bug / skip) ↓ B: APPLY /docsmith wt --apply → update drafts per decisions ↓ C: CAPTURE → screenshots, replace placeholders ``` **Default mode** (no flag): runs A → interactive gate → B → C. **Flags**: - `--check` — Phase A only; fast (~30s); for drift monitoring - `--apply` — B + C with existing decisions - `--skip-drift` — C only; for first runs or known-clean drafts - `--auto-apply-high-confidence` — skip gate, auto-apply HIGH-confidence fixes - `--locale ` — verify against a translated locale (requires product UI in that locale) Drift report format: [templates/DRIFT_REPORT_TEMPLATE.md](templates/DRIFT_REPORT_TEMPLATE.md). Test cases: [templates/WALKTHROUGH_TEST_CASE_TEMPLATE.md](templates/WALKTHROUGH_TEST_CASE_TEMPLATE.md). Items marked `product-bug` tracked in `walkthrough/active-product-bugs.yaml` across runs; auto-resolved when UI matches doc. ### `record` (AI) **Prerequisites**: same as `walkthrough` PLUS ffmpeg installed for video encoding. If voiceover strategy is "AI synthetic voice", also need TTS provider configured (project intake § 11). For local TTS (default): Piper or Coqui binaries installed. For remote TTS: API auth env var set. See [SETUP.md](../../SETUP.md) — section "Path 3: For `record` (tutorial videos)". **Interactive fill (v1.5.13+)**: if voiceover strategy = "AI synthetic voice" and TTS provider/voice ID not set, AI prompts inline and writes back. Silent strategy (default) requires no prompts. See [intake-reference.md § 10](intake-reference.md) — section "record" required fields. **Media policy**: respects video density rules, length caps, voiceover strategy, and TTS provider from project intake § 11 (and module intake § 8 overrides). Default behavior is "Silent + on-screen captions" (no audio, no TTS needed). See [templates/MEDIA_POLICY_TEMPLATE.md](templates/MEDIA_POLICY_TEMPLATE.md) § 4-7 for full options. **Script files (v1.5.7+)**: each video has its own script file at `documentation/scripts//.md`. Script contains source-language narration plus per-locale translations. Voiceover (TTS or human) reads from this file. See [templates/VIDEO_SCRIPT_TEMPLATE.md](templates/VIDEO_SCRIPT_TEMPLATE.md) for format. **Workflow**: 1. Scan drafts for `` markers 2. For each marker, look up `documentation/scripts//.md`: - If missing → AI generates initial script from surrounding draft prose, saves to file, pauses for user review - If exists but stale (draft section changed >20%) → warn user 3. User reviews/edits script file 4. On confirm: TTS generates audio per locale (skipped if silent), capture screen, encode video 5. Replace VIDEO marker with `