Documentation only — no code changes.
The README described AI_README as a style guide, which invited the obvious response: "then I'll just write a CLAUDE.md". Conventions are the least valuable thing these files hold.
Reframed around what a real deployment accumulates: silent-failure traps, deliberate-looking oddities, and post-mortem lessons that are invisible in source. The code shows the fix, never the failure that motivated it.
What changed
- The Problem now opens on session amnesia — the AI starts every session with no memory of the last, which is the root of the other symptoms
- New everyday-cases table before any domain-specific example, so the idea lands without needing the reader to know a particular stack
- Real production entries kept as evidence in a collapsed table, with a plain-language reading for each
- AI_README vs. CLAUDE.md section now contrasts where the knowledge comes from — written up front by a human vs. earned mid-session while debugging — rather than just how each file is maintained
- Documents the reviewed write path: validation, conflict detection, quality scoring, token budget. Conflict detection is what stops an AI "fixing" a workaround back into the bug it was avoiding
- Nesting claims corrected: both formats nest. The difference is when subdirectory rules reach the AI, verified with a small experiment
Full Changelog: v1.10.1...v1.10.2