Rewrite docs, docstrings, and comments in a plain teaching voice

[Cuuper22]

Reworks the project prose so a newcomer can learn the system by reading it. No behavior and no facts change.

What changed

Documentation — README, DESIGN, PRODUCT, RESEARCH, ROADMAP, RELEASING, the CHANGELOG entries, and everything under docs/, process/, and observations/. Technical terms are now defined where they first appear, and each document leads with what the thing is and why it exists before how it works.

Code documentation — module, class, and function docstrings across all 189 scope modules, the core engine, the CLI layer, and research/ + presets/. Scope docstrings now explain the physical or systems question each module answers and how it connects to neighboring scopes. Comments that merely restated the code were deleted. Test modules gained docstrings describing what property each file verifies and why it matters.

For example, scopes/kernel_roofline.py previously opened with a noun-phrase list of its contents. It now explains the mechanism: what arithmetic intensity is, why a kernel's attainable rate is the minimum of its per-level ceilings, and where the memory-bound/compute-bound crossover sits.

What deliberately did not change

Nothing executable. Identifiers, expressions, numbers, and every string literal are untouched — including the var() / eq() / Reference() and preset description strings, and the CLI and error messages that tests assert on.

The archived files under archive/ keep their original wording. archive/README.md states that those files are kept byte-identical for provenance, and they are timestamped first-person records whose exact wording is the archived fact. Only the archive index itself was rewritten.

Verification

• Full test suite: 1029 passed, with the same 10 pre-existing errors that unmodified main produces on this machine (Windows temp-directory PermissionErrors, unrelated to this change). The baseline was captured from a clean main worktree specifically so the two runs could be compared.
• python -m compileall clean across the package.
• The docs-stats gate passes, independently confirming that every tracked statistic in the README, the HTML stat grid, and app.js survived the rewrite.

🤖 Generated with Claude Code