markdown docs are consistently out-of-date

[ktdreyer]

As humans and agents read through the docs, several READMEs or other markdown files are consistently wrong or out-of-date. This can steer the LLMs into amplifying bad patterns. (garbage in, garbage out).

Examples I remember:

#790
#835
#769

This is somewhat related to code churn: it's low value to write a README for areas of the codebase that are high-churn (example: listing directory contents). It's much higher value to document low-churn, higher-level principles that change slowly (if at all).

Two approaches here:

1. "stop the bleeding" one-time pass to fix all the issues (see this skill as inspiration)
2. Edit CLAUDE.md to stop Claude from writing brittle things into individual README Markdown files, and treat the code as authoritative in areas where it makes sense (ie, don't AI-generate a list of files in a directory into a Markdown file).