docs: lessons learned for rate-measurement hardening + the test harness

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -375,6 +375,21 @@ Non-obvious things that cost time and constrain the design:
   captures post-mix at the device format (always correct). The Audio panel shows each
   stream's provenance (known / measuring / measured rate (ch/bits assumed)) so what the
   mirror is using is always visible — see Limitations.
+- **A short measurement window *rejects* a bad reading, it can't *average* it away.**
+  Measuring the rate over ~200 ms made one extra ~10 ms WASAPI buffer at a window edge a
+  ~5% error, which lands *between* standard rates (they're >8% apart) — so 44100 read as
+  ~46205 and got published verbatim. The robust fix isn't just a longer window: it's to
+  **refuse any window that doesn't snap to a standard rate** and require **consensus**
+  across windows, since a quantization/burst error big enough to miss the right rate
+  lands in no-man's-land rather than on a wrong neighbour. Only commit a non-standard
+  estimate as explicitly *low-confidence* (shown red). The operator can also re-measure
+  or override the format via a per-stream `AudioRingHeader` op channel; the host rebuilds
+  its render client when `format_generation` bumps, so it takes effect live.
+- **Drive the ImGui overlay for tests through an IPC harness, not synthetic input.**
+  `PostMessage`-d mouse clicks don't reliably reach ImGui widgets, and key/coordinate
+  simulation is brittle. A tiny debug-only command channel (`-DCOOP_TEST_HARNESS`, file-
+  based) that calls the *same* code the buttons do — and replies with state — makes UI
+  validation deterministic and scriptable, and is compiled out of the shipped product.
 - **Capturing at `Present` decouples the mirror from DWM composition.** The hook copies
   the backbuffer inside the game's `Present`, which the game issues at its true render
   rate regardless of how DWM composites that *window*. So an unfocused game window can