diff --git a/AGENTS.md b/AGENTS.md
index b90d355..600e064 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -182,3 +182,11 @@ KDE integration is part of this repository under `kde/`. Build and install it th
 9. **The 9P namespace is the API.** Every capability is a file. Read, Write, or Rdwr. BlockOnce and Stream are special cases of Read. That's the entire interface.
 
 10. **`Rdwr` is an atomic operation** — not a variant of read or write. It's write-then-read as one unit. Sub-agents, session creation, tool execution, and generation all use this primitive.
+
+11. **Persisted state can contain garbage.** When debugging impossible errors, check if the data itself is corrupted. A failed command's stderr captured and stored as state will return that error on every subsequent read — the bug isn't in the code, it's in the data.
+
+12. **Environment variables don't always propagate.** Tools run through toolsrv, which sets specific env vars. If a tool calls another binary that expects `$USER` or `$OLLIE_UNAME`, verify those are actually set in the execution context. Provide explicit fallbacks.
+
+13. **Go build cache is aggressive.** When source changes don't appear in the binary, the cache may be stale. Use `go clean -cache` or verify with `go version -m <binary>` to check the embedded module version. Touch files if needed.
+
+14. **Separate index files for separate concerns.** Don't cram session and agent data into one line. `session/idx` lists sessions; `session/{s}/agent/idx` lists agents per session. Simpler parsing, fewer race conditions, cleaner code.