AGENTS: note pi changelog source is npm-tarball CHANGELOG.md

Companion to opencode-devbox's 'Upstream sources' section. Pi's npm
package ships a rich CHANGELOG.md with New Features / Added / Changed
/ Fixed sections — but the npm registry metadata ('npm view') doesn't
include the changelog body. Surface the 'npm pack + tar' recipe in
the release-day checklist so future-pi (and human-pi) doesn't try to
derive notes from npm view alone.

Doc-only, no CI implications.

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
@@ -35,3 +48,16 @@ Container image that adds pi coding-agent on top of the opencode-devbox base ima
 - Do NOT call `mempalace-toolkit/install.sh` in the Dockerfile — the base entrypoint handles it
 - `NPM_CONFIG_PREFIX=/usr` must be set per-RUN for any build-time `npm install -g` to keep baked binaries off the volume-shadowed path
 - The smoke test threshold is 2200 MB — update if the image legitimately grows past it
+
+## Documentation drift sweep
+
+Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
+
+- `README.md` — quick-start examples, env-var table, base-image reference (must match `FROM` in `Dockerfile`).
+- `AGENTS.md` (this file) — `Key facts` block (pi binary path, `NPM_CONFIG_PREFIX`, base-image tag), smoke-test threshold number.
+- `CHANGELOG.md` — promote `Unreleased` only on tag, but record post-release fixes in a fresh `Unreleased` block.
+- `DOCKER_HUB.md` — hand-maintained slim Hub description; sync anything user-facing that changes (env vars, run command, base image).
+- `.env.example` — hand-updated, must match Dockerfile/entrypoint env vars.
+- `Dockerfile` `PI_VERSION` ARG default — if you intend to pin (rather than `latest`), bump it on release.
+
+Quick triage: `git diff --name-only HEAD | xargs -I{} grep -l 'thing-you-changed' README.md AGENTS.md DOCKER_HUB.md CHANGELOG.md .env.example`.

CHANGELOG.md

@@ -8,6 +8,31 @@ Tags follow the pi npm version: `v{pi_version}[letter]` — bare tag for the fir
 
 ## Unreleased
 
+## v0.75.5 — 2026-05-23
+
+pi `0.75.4` → `0.75.5` bump (one upstream patch release, two days after v0.75.4).
+
+Notable upstream changes (from pi's CHANGELOG):
+
+- Cleaner read tool output (collapsed cards show only the read line; Ctrl+O expands).
+- Faster file tools on Windows (async fs ops during streaming, image resize off the main TUI thread).
+- More reliable package updates (`pi update` reconciles git-pinned refs without losing settings).
+- Custom Anthropic-compatible adaptive thinking via `compat.forceAdaptiveThinking`.
+- Several bash/read tool card display fixes; macOS Bun clipboard sidecar resolution; per-session OpenCode-Zen routing headers; Amazon Bedrock token cap fix.
+
+Plus a new pi 0.74.2 rescue release advising Node 20 users to upgrade Node before going to newer Pi versions — the devbox base image runs newer Node so this doesn't affect us, but worth noting for users running pi outside the devbox.
+
+- **Bump:** pi `@earendil-works/pi-coding-agent@0.75.5` baked at `/usr/bin/pi` (via `PI_VERSION=latest` resolving to 0.75.5 at build time — no Dockerfile change needed).
+- No image-side changes from v0.75.4 beyond the pi npm version. Built on `joakimp/opencode-devbox:base-latest` which itself is unchanged (cache-hit on `base-35ee5fe7861a` since v1.14.50b).
+
+## v0.75.4 — 2026-05-21
+
+pi `0.75.3` → `0.75.4` bump (one upstream patch release). Plus the AGENTS.md documentation-drift sweep clause that landed on `main` between v0.75.3 and now.
+
+- **Bump:** pi `@earendil-works/pi-coding-agent@0.75.4` baked at `/usr/bin/pi` (via `PI_VERSION=latest` resolving to 0.75.4 at build time — no Dockerfile change needed).
+- **AGENTS.md:** documentation drift sweep as explicit pre-commit workflow step (commit `ae6253a`). Companion clause added across the wider repo set the same day.
+- No image-side changes beyond the pi npm version. Built on `joakimp/opencode-devbox:base-latest` which itself is unchanged (cache-hit on `base-35ee5fe7861a` since v1.14.50b).
+
 ## v0.75.3 — 2026-05-18
 
 pi `0.74.0` → `0.75.3` bump (one upstream minor + three patch releases since the initial pi-devbox release on 2026-05-14).