docs: add usage examples to README (#24)

Author: jdalton

CLAUDE.md

@@ -37,6 +37,8 @@
 - Read files >500 LOC in chunks using offset/limit; never assume one read captured the whole file
 - Before every edit: re-read the file. After every edit: re-read to confirm the change applied correctly
 - When renaming anything, search separately for: direct calls, type references, string literals, dynamic imports, re-exports, test files — one grep is not enough
+- Tool results over 50K characters are silently truncated — if search returns suspiciously few results, narrow scope and re-run
+- For tasks touching >5 files: use sub-agents with worktree isolation to prevent context decay
 
 ## JUDGMENT PROTOCOL
 
@@ -50,6 +52,29 @@
 - Try the simplest approach first; if architecture is actually flawed, flag it and wait for approval before restructuring
 - When asked to "make a plan," output only the plan — no code until given the go-ahead
 
+## COMPLETION PROTOCOL
+
+- **NEVER claim done with something 80% complete** — finish 100% before reporting
+- When a multi-step change doesn't immediately show gains, commit and keep iterating — don't revert
+- If one approach fails, fix forward: analyze why, adjust, rebuild, re-measure — not `git checkout`
+- After EVERY code change: build, test, verify, commit. This is a single atomic unit
+- Reverting is a last resort after exhausting forward fixes — and requires explicit user approval
+
+## FILE SYSTEM AS STATE
+
+The file system is working memory. Use it actively:
+
+- Write intermediate results and analysis to files in `.claude/`
+- Use `.claude/` for plans, status tracking, and cross-session context
+- When debugging, save logs and outputs to files for reproducible verification
+- Don't hold large analysis in context — write it down, reference it later
+
+## SELF-IMPROVEMENT
+
+- After ANY correction from the user: log the pattern to memory so the same mistake is never repeated
+- Convert mistakes into strict rules — don't just note them, enforce them
+- After fixing a bug: explain why it happened and whether anything prevents that category of bug in the future
+
 ## SELF-EVALUATION
 
 - Before calling anything done: present two views — what a perfectionist would reject vs. what a pragmatist would ship