---
description: Bootstrap missing AI docs — create .claude/docs/*.md for code areas that have no doc coverage yet
argument-hint: "[optional: a path or area to scan]"
---

# Create docs

Bootstrap the project's AI documentation by finding code areas that have **no
doc coverage** and writing a fresh `.claude/docs/<area>.md` for each. This is the
inverse of `/update-docs`: that command fixes **stale** existing docs; this one
fills **absent** ones.

**Create only.** Write new files under `.claude/docs/*.md` — never edit or
overwrite an existing doc, and never touch source code.

## 1. Find code areas

From the repo root, enumerate the significant source directories — directories
that hold more than one non-`.md`, non-`.env*` source file:

- `git ls-files` to list tracked files, then group by directory.
- Ignore markdown, `.env*`/`.envrc*`, and obvious non-source dirs
  (`node_modules`, `dist`, `build`, `.git`, vendored/generated output).

Order areas by significance (more source files = more significant). If
`$ARGUMENTS` is provided, treat it as a scope hint and scan only that path/area.

## 2. Determine what's already documented

For each area, decide whether it is already **covered**. An area is covered if
either:

- a `.claude/docs/*.md` already describes it, **or**
- a `README.md` or `CLAUDE.md` exists in that directory or any directory **above**
  it up to the repo root.

(This mirrors the walk-up scope the Stop hook and `/update-docs` use, so all three
agree on what counts as documented.) Skip every covered area — no duplication, no
overwrites.

## 3. Propose, then create

List the undocumented areas and the doc each would get
(`.claude/docs/<area>.md`), then **wait for confirmation before writing anything**.
Note any area you judged too small to be worth a doc as skipped, so nothing is
silently dropped.

On confirm, write each new doc grounded in the **actual code** in that area:

- a short overview — what the area does and why it exists,
- the key files and their responsibilities,
- how it connects to the rest of the repo,
- any notable gotchas.

Keep each doc concise and accurate — no padding, no invented detail. Choose a
clear, kebab-case `<area>.md` name (e.g. the directory or feature name).

## 4. Report

List each scanned area as exactly one of:

- `created — .claude/docs/<area>.md`
- `skipped — already documented (<which doc>)`
- `skipped — too small`

Keep the report tight. If every scanned area is already covered, say
"All scanned areas already have docs — nothing to create." and stop.

---

**Constraints**

- Create **only** new `.claude/docs/*.md` files. Never edit or overwrite an
  existing doc, and never edit source code, tests, or config.
- Never read or write `.env*` secrets files.
- If `$ARGUMENTS` is provided, treat it as a scope hint (a path or area) and scan
  only there.