docs: rewrite DEVELOPMENT.md (current state), add scripts/README.md

- Layout: tests/ per workspace, scripts/ tools, docs/ structure
- Test section: 4 types (unit/integration/characterization/scenario),
  counts (134 green + 1 validated skip), per-file run, scenario slow note
- Tools section: replay-combat (live demo), audit-rotation (rotation),
  audit-state (9 invariant classes)
- Storage: generic KV, path norm, STORAGE_MODE flow, test layers
- Status: M2/M3 done, M4 next
- scripts/README.md: tool usage + bug-finder not unit test

scripts/README.md

@@ -0,0 +1,52 @@
+# scripts/
+
+Manual tools. NOT unit tests. Math.random, non-deterministic.
+
+Used to FIND bugs. Unit tests (in `*/tests/`) LOCK them.
+
+## replay-combat.js
+
+Drives full combat through live backend via ws adapter (same contract as App).
+Player display live-updates. Use to watch UI react to state changes.
+
+```bash
+# start backend + frontend first (see docs/DEVELOPMENT.md)
+node scripts/replay-combat.js [rounds] [delayMs]
+# defaults: 100 rounds, 200ms/step
+```
+
+Coverage per round: damage, heal, all 22 conditions, toggleActive,
+removeParticipant, addParticipant (reinforcements), updateParticipant,
+pause/resume, reorderParticipants, endEncounter. Revives dead each round
+to sustain full round count.
+
+## audit-rotation.js
+
+Pure turn.js simulation of replay op sequence. Detects rotation violations
+(skip/dupe per round). Pinpointed BUG-1 (addParticipant + pause corrupts).
+
+```bash
+node scripts/audit-rotation.js
+```
+
+Bisect: comment/uncomment op blocks to isolate triggering combo.
+
+## audit-state.js
+
+Expanded invariant bug-finder. 9 check classes per round:
+
+1. rotation integrity
+2. HP bounds
+3. isActive consistency
+4. turnOrder no dup ids
+5. turnOrder ids all active
+6. currentTurn valid + active
+7. deathSave range + reset on revive
+8. removeParticipant orphans
+9. undo support
+
+```bash
+node scripts/audit-state.js [rounds]   # default 100
+```
+
+See TODO.md for bugs found.