docs-reviewlisted

# docs-review A documentation-quality sweep: every Markdown file under `README.md` and `docs/**` is audited across five axes, then fixed in place. The goal is to finish with zero broken links, no stray plan files, and every doc reflecting the current state of the codebase. ## Scope **Full audit:** `README.md` (repo root), every `*.md` under `docs/`. **Partial audit:** If `$ARGUMENTS` is a path or glob, restrict to that subset. ## Step 0 — Build file manifest (ALWAYS FIRST) ```bash { find . -maxdepth 1 -name 'README.md'; find docs -name '*.md' -type f 2>/dev/null; } \ | sort > /tmp/docs-manifest.txt echo "=== $(wc -l < /tmp/docs-manifest.txt | tr -d ' ') files queued ===" cat /tmp/docs-manifest.txt ``` Print the list so the user can see scope before work begins. ## The five audit axes Walk each file once and apply all checks. Fix in-place. Print `[✓] path — N fixes applied` or `[·] path — clean` for each file. ### Axis 1 — Visual cleanliness Fix: - Trailing whitespace on lines - Code fences without language hints (` ``` ` → ` ```bash `, ` ```json `, ` ```yaml `, etc.) - Tables with misaligned or inconsistent column counts - Inconsistent bullet styles (mix of `-`, `*`, `+` in one file) — normalize to `-` - Heading level skips (e.g. `####` directly after `#` with no `##` or `###` in between) - Long lines inside prose paragraphs (soft 120 char limit — flag, don't hard-wrap) Leave alone: ASCII diagrams, code blocks with legitimately long single-line commands. ### Axi