Generate and maintain architecture documentation for any codebase. Produces CLAUDE.md, docs/CODEBASE_MAP.md, README.md, and AGENTS.md with mermaid diagrams, annotated file trees, and navigation guides.

• Works with any language or project type (not limited to TypeScript/JavaScript)
• Scans codebase with token counting to plan parallel analysis
• Spawns parallel subagents for large codebases (stays within context limits)
• Detects existing docs and runs in update mode (only refreshes stale sections)
• Generates navigation guides — "To add a new X: touch these files" — the most actionable documentation for AI agents

# Clone to your skills directory
git clone https://github.com/jeremyknows/update-docs.git ~/.claude/skills/update-docs

Clone the repo and point your agent's skill loader at the SKILL.md file:

git clone https://github.com/jeremyknows/update-docs.git ~/update-docs

• Python 3.9+ (ships with macOS, most Linux distros)
• uv (recommended) — handles dependencies automatically

# Verify Python 3.9+
python3 --version

# Install uv (optional but recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

If uv is not installed, the scanner falls back to python3 (requires pip install tiktoken manually).

# Test the scanner
uv run ~/.claude/skills/update-docs/scripts/scan-codebase.py . --format tree

You should see a file tree with token counts.

Just tell Claude what you need:

• "Update the docs for this project"
• "Create a CLAUDE.md and codebase map"
• "Map this codebase"
• "My docs are stale, refresh them"
• "I need architecture documentation"
• "Generate a README"

# In any project directory
/update-docs

1. Scan — Runs scan-codebase.py to get file tree with token counts (respects .gitignore)
2. Plan — Groups files by module, balances token budgets across subagents
3. Analyze — Spawns parallel Sonnet subagents to read and analyze code (orchestrator never reads files directly)
4. Synthesize — Merges subagent reports into documentation using templates from references/doc-templates.md
5. Verify — Checks all file path references exist and mermaid syntax is valid
6. Report — Lists what was created/updated, leaves changes for user review (never commits)

No configuration needed. The skill auto-detects project type, language, and framework from the scan results.

# JSON output (used by the skill)
uv run scripts/scan-codebase.py . --format json

# Tree view with token counts
uv run scripts/scan-codebase.py . --format tree

# Compact view sorted by token count
uv run scripts/scan-codebase.py . --format compact

# Increase max tokens per file (default: 50,000)
uv run scripts/scan-codebase.py . --max-tokens 100000

# See all options
uv run scripts/scan-codebase.py --help

update-docs does NOT generate inline code comments. It generates standalone documentation files.

• Subagent-only architecture — The orchestrator never reads codebase files directly. For very small projects (< 10 files), this adds overhead but keeps the approach consistent.
• Token estimation — Uses tiktoken with cl100k_base encoding. Accurate for Claude models but may over/under-count for other model families.
• No inline comments — Generates standalone .md files only. Use generate-docs for JSDoc/TSDoc.
• Git dependency for update mode — Update mode requires a git repo to detect changes since last mapping. Falls back to full mode if not a git repo.
• Max file size — Scanner skips files over 1MB or 50,000 tokens (configurable with --max-tokens).
• Root .gitignore only — Only reads the root-level .gitignore. Nested .gitignore files in subdirectories are not parsed.
• No .gitignore negation — .gitignore negation patterns (!pattern) are not supported; negated files will still be excluded.

update-docs/
├── SKILL.md                  # Main skill — orchestration instructions
├── README.md                 # This file
├── LICENSE.txt               # MIT (skill + scanner attribution)
├── .gitignore
├── scripts/
│   └── scan-codebase.py      # Codebase scanner with token counting (from Cartographer, MIT)
└── references/
    └── doc-templates.md      # Output templates + mermaid conventions

• Cartographer by Bootoshi — scan-codebase.py is bundled from this project (MIT license). The "Opus orchestrates, Sonnet reads" pattern and navigation guide concept also originate from Cartographer.

MIT — see LICENSE.txt