diff --git a/AGENTS.md b/AGENTS.md
index 4ab8fa6..8b23d1c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -400,3 +400,14 @@ pi --ssh user@host --ssh-ask-pass
   — same pattern for agent skills rather than extensions.
 - [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox)
   — Docker containers; composes toolkits via independent install.sh calls.
+
+## Documentation drift sweep
+
+Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
+
+- `README.md` — the per-extension feature/usage descriptions, the install instructions, the dependency list. When an extension's flags or behaviour change, the README block for that extension is the first thing to update.
+- `AGENTS.md` (this file) — the `Extension-specific notes` section is large and easy to leave stale. Each extension has its own subsection; if you change a flag, hook, or default, update the subsection here as well as the README.
+- Extension files themselves — the `// description:` comment header pi parses for the extension list view must stay accurate.
+- `install.sh` — `--only` / `--skip` defaults, the list of artifacts it knows about, and the symlink targets. If you add a new extension file, the installer's auto-discovery picks it up; if you add a new artifact type that needs special handling, the script must be updated and the README block describing what `install.sh does` along with it.
+
+Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md install.sh`. For an extension rename, also grep for the old name across the whole repo.