diff --git a/AGENTS.md b/AGENTS.md
index 5f6c092..311932a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,19 @@ Container image that adds pi coding-agent on top of the opencode-devbox base ima
 3. Add fresh `## Unreleased` section
 4. Commit, tag `vX.Y.Z`, push tag → CI fires automatically
 
+When drafting CHANGELOG entries, pull pi's release notes from the
+`CHANGELOG.md` shipped inside the npm tarball:
+
+```bash
+cd /tmp && npm pack @earendil-works/pi-coding-agent@<version>
+tar -xzf earendil-works-pi-coding-agent-<version>.tgz package/CHANGELOG.md
+head -40 package/CHANGELOG.md
+```
+
+Pi's CHANGELOG has rich New Features / Added / Changed / Fixed sections
+per version. Don't try to derive notes from the npm registry metadata
+(`npm view`) — it doesn't include the changelog body.
+
 ## Key facts
 
 - **Base image**: `joakimp/opencode-devbox:base-latest` — rebuilt whenever opencode-devbox cuts a new base