diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md
index 6cf306318..6aa1d8afc 100644
--- a/packages/coding-agent/docs/packages.md
+++ b/packages/coding-agent/docs/packages.md
@@ -28,6 +28,8 @@ Use `--extension` or `-e` to try a package for one invocation without adding it
 pi -e npm:@example/pi-tools
 ```
 
+Pi caches `-e` packages under `~/.pi/agent/tmp/extensions/` and checks them on every start and `/reload`. An npm package is reinstalled when the registry has a newer version that matches the specification. A version pinned to an exact number, such as `@1.2.3`, is not checked. A git package is fetched and reset to the remote branch or ref. A ref that is a commit hash already checked out is not fetched. If the check fails or offline mode is on, Pi loads the cached copy.
+
 ## Choose a source
 
 | Source | Example | Behavior |