# songwhip-docs

Keeps a repo's AI documentation in sync with its code. Installing the plugin
activates a `Stop` hook in **any** repo — no per-repo `settings.json` editing.

## How it works

1. **Detect (automatic, `Stop` hook).** When you finish a turn and enough code
   changed, the hook gathers the changed code files and the docs near them
   (`.claude/docs/*.md` plus every `README.md`/`CLAUDE.md` from each changed
   file up to the repo root) and asks Claude to flag any that look stale and
   **offer** to update them. It never edits docs on its own.
2. **Update (on demand, `/update-docs`).** When you accept the offer (or run the
   command anytime), Claude compares the docs against the diff and applies
   minimal edits, then reports what changed. Doc edits are git-tracked, so you
   review them in `git diff`.
3. **Create (on demand, `/create-docs`).** The inverse of update: instead of
   fixing stale docs, it bootstraps **missing** ones. It scans the repo for code
   areas with no doc coverage, proposes a `.claude/docs/<area>.md` for each, and
   writes them after you confirm. Create-only — it never edits or overwrites an
   existing doc, and never touches source.

## Noise gate

The hook only fires when at least **3** non-markdown code files changed, so
small edits don't nag. Tune it with an environment variable:

```sh
export SONGWHIP_DOCS_MIN_CHANGED_FILES=5   # nudge only on larger changes
```

The `/update-docs` and `/create-docs` commands are **not** gated — run them
whenever you like.

## Scope

- Touches docs only: `.claude/docs/*.md`, `README.md`, `CLAUDE.md`. Never code.
- Requires `git` and `jq` (or `python3`) on PATH.

## Install

```text
/plugin install songwhip-docs@songwhip-marketplace
```

See the marketplace [README](../../README.md) for adding the marketplace itself.