diff --git a/AGENTS.md b/AGENTS.md
index 9c5919e..c465b82 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -47,7 +47,13 @@ re-brand of opencode-devbox's `pi-only` variant.
    (`curl -sf 'https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest' | jq -r .version`).
 2. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
 3. Verify `docker compose up` works locally with the current `latest` image
-   if you're upgrading users from a previous version.
+   if you're upgrading users from a previous version. Then run the
+   **post-recreate sanity check** inside the running container to confirm
+   persisted volumes survived and the pi runtime wiring re-deployed (not just
+   that the container booted):
+   `docker compose exec devbox bash scripts/recreate-sanity-check.sh --expected-version X.Y.Z`
+   (or just `pi-devbox-sanity --expected-version X.Y.Z` if `cli_utils/bin` is
+   on PATH). This is the runtime peer of the build-time `smoke-test.sh` gate.
 4. Push tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
 5. Watch CI: smoke job builds amd64 only and asserts size + extensions +
    pi version + new-base-tooling presence. Variant build is multi-arch