hard docs writer

a tool that automatically documents the confusing parts of a codebase, specifically optimized for making AI agents more effective. most codebases have sections that are genuinely hard to understand — complex state machines, subtle invariants, non-obvious initialization orders, implicit dependencies between modules. humans who built these parts hold the context in their heads; AI agents and new human engineers hit a wall.

the approach would be to identify these "hard" sections automatically (high coupling, low comment density, frequent bug origins, high churn), then generate detailed prose explanations that capture the intent and gotchas, not just what the code does mechanically. the target reader is an AI agent starting a new task — so the docs need to be dense, precise, and structured in a way that fits efficiently into a context window.