diff --git a/docs/gotchas.md b/docs/gotchas.md
index a3b131c8..c50421be 100644
--- a/docs/gotchas.md
+++ b/docs/gotchas.md
@@ -145,9 +145,12 @@ across `destroy`/recreate (`--purge` wipes them).
 `/agents/<name>/state` (RW; uniform for all agents).
 The harness exposes the same path
 via `$HYPERHIVE_STATE_DIR`. System prompts tell agents to keep
-durable knowledge here (`notes.md`, anything else). The harness also
-writes its events log here (`hyperhive-events.sqlite`).
-Survives `destroy`/recreate alongside the claude dir.
+durable knowledge here (`notes.md`, anything else) — the harness's own
+internal files (`hyperhive-events.sqlite`, `hyperhive-turn-stats.sqlite`,
+`hyperhive-model`) live in the separate `harness` dir instead, so they
+don't clutter what claude sees as "my notes dir" (see
+[`docs/persistence.md`](persistence.md)). Survives `destroy`/recreate
+alongside the claude dir.
 
 ## Networking & ports