Bootstrap Documentation

Bootstrap Documentation onto an Existing Project

/doc-bootstrap takes a project from no (or partial) docs to a complete, code-grounded set in one command — scaled to a tier you pick. It reads your code to ground every claim, never overwrites docs you already have, and writes nothing until you apply.

Two ways to run every step

Each step below shows both:

• Slash command — type it in a Claude Code session. It acts on the current project and the agent runs the steps for you.
• Terminal — run the script directly from a shell (no Claude session needed). Use --path to point at any project.

Pick whichever you’re in; they do the same thing.

What it actually does (the mental model)

Bootstrap measures your docs against a target (a per-tier checklist), then authors only what’s missing to hit it. Three things make it safe to point at a real project:

• It’s scaled. You don’t document a 50-line script like a platform. You pick a tier (below) and bootstrap only aims for that bar.
• It’s grounded. Every fact it writes — an env var, a command, a route — is pulled from your real source and tagged with the file:line it came from. It can’t invent config that doesn’t exist.
• It augments, never clobbers. Accurate docs you already have are left alone; only gaps get filled, and you see a draft before anything lands.

Step 0 — Pick a tier (the one real decision)

A tier is how much documentation the project warrants. Over-documenting a throwaway script is waste; under-documenting a multi-team system is the gap this tool closes. Bootstrap proposes a tier, but you choose with --tier N. Tiers are cumulative — each includes everything below it:

Tier	Pick it when the project is…	You get	Why that set
0 — Minimal	a script, utility, or prototype; one dev; little surface	README.md	one person needs what it is, how to run it, the licence
1 — Standard	a real app or library with an ops surface	Tier 0 + CLAUDE.md, docs/reference/, docs/how-to/, a runbook	a team needs surfaces to look up, tasks to follow, ops to run
2 — Full	a complex, multi-audience system (devs + ops + editors / API users)	Tier 1 + docs/tutorials/, docs/explanation/, a published docs site	distinct audiences need learning paths, rationale, a real portal

Step 1 — Dry-run (writes nothing)

Stages drafts outside your tree and prints the proposed tier, the gaps it would fill, the create/augment/preserve plan, and any code-vs-doc conflicts (a doc claiming an env var your code doesn’t have). This is your review gate — read it before applying.

Slash command:

/doc-bootstrap

Terminal:

node ~/.claude/scripts/doc-bootstrap/bootstrap.js --path /path/to/project

Heads-up: triage under-calls doc-light projects. A project with docs but no obvious entry point can be proposed as Tier 0. If the table above says it deserves more, override with --tier 1 (or 2). Trust the table, not the guess.

Step 2 — Apply your chosen tier

Writes the accepted drafts to their real locations. You’re guaranteed: aligned docs are preserved (classified via doc-keeper, never overwritten), only gaps are filled (your hand-tuned docs don’t churn), and every claim is code-grounded (traces to a real file:line). --apply is required to write at every automation level — without it, Step 1’s dry-run is all you get. Once you pass --apply, L3 accepts all drafts and logs the plan, while L2 has you accept per-file first. Automation level never writes for you on its own.

Slash command:

/doc-bootstrap --tier 1 --apply

Terminal:

node ~/.claude/scripts/doc-bootstrap/bootstrap.js --path /path/to/project --tier 1 --apply

Step 3 — Confirm it’s complete

Reports zero gaps against the tier you chose. Not luck: bootstrap and the audit measure against the same checklist, so “bootstrap finished” means “audit is clean” by construction.

Slash command:

/doc-audit

Terminal:

make docs-check          # on a BoB repo

Step 4 — (Tier 2 only) Publish the docs site

Bootstrap hands off to the docs-site tooling but never deploys — going live is a separate, explicit step you take when ready.

Slash command:

/docs-site init
/docs-site dev

Terminal:

node ~/.claude/scripts/docs-site/init.sh --root /path/to/project
node ~/.claude/scripts/docs-site/dev.sh   --root /path/to/project

Re-running is safe (and why)

Re-run at the same tier on already-complete docs and nothing changes — no files added or removed, no gaps opened or closed. Bootstrap only acts on what’s missing, and on a complete tree nothing is. So it’s safe as the last step of any docs cleanup, and never a step you’re forced to run. Raising the tier is the one exception — a higher bar has new gaps, so it authors the new artifacts.

External (non-BoB) projects

Pointing bootstrap at a project that doesn’t use BoB writes no .claude/ config into it, and makes CLAUDE.md opt-in — documenting a project shouldn’t force it to adopt BoB. You get the docs without the framework.

---

Going deeper: the explanation covers the design and the convergence/fixpoint invariants; the reference lists every script, flag, and JSON contract. You don’t need either to run the steps above.