pi-devbox/AGENTS.md

AGENTS.md — pi-devbox

Container image that adds pi coding-agent on top of the opencode-devbox base image.

Repository layout

• Dockerfile — single-stage build, FROM opencode-devbox:base-latest, installs pi + companion repos
• docker-compose.yml — compose file for local use
• .env.example — environment variable template
• scripts/smoke-test.sh — sanity checks run by CI before pushing to Docker Hub
• .gitea/workflows/docker-publish.yml — CI pipeline: smoke amd64 → multi-arch push → update Hub description

Versioning scheme

• Tags follow the pi npm version: v{pi_version}[letter]
• Bump PI_VERSION build-arg default in Dockerfile when cutting a new release
• Docker Hub: joakimp/pi-devbox:vX.Y.Z + joakimp/pi-devbox:latest

Release-day checklist

1. Bump PI_VERSION in Dockerfile (or leave as latest to pick up current)
2. Update CHANGELOG.md: promote Unreleased → vX.Y.Z — YYYY-MM-DD
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:

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
• pi binary: baked at /usr/bin/pi (system npm prefix); NPM_CONFIG_PREFIX=/home/developer/.pi/npm-global at runtime so user-installed pi/packages land on the named volume
• Companion repos: pi-toolkit and pi-extensions cloned to /opt/ at build time; entrypoint-user.sh (inherited from base) deploys symlinks to ~/.pi/agent/ on container start
• MemPalace: fully operational — inherited from base image; bridge extension deployed by entrypoint

Conventions

• 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
• PI_VERSION must be passed explicitly by CI as a concrete version (derived from the git tag), not left as the latest default. The Dockerfile's bare npm install -g @earendil-works/pi-coding-agent (without @${PI_VERSION}) produces an identical layer-hash across builds; combined with registry buildcache (cache-from/cache-to) the layer gets reused even when latest would have resolved to a newer pi version. All releases v0.74.0 → v0.75.5 silently shipped the same image bytes because of this (verified via docker manifest inspect — identical digests across both arches and all four tags). Fixed in v0.75.5b: workflow now derives PI_VERSION from ${{ github.ref_name }} and passes it as a build-arg; smoke-test asserts the resulting pi --version matches via EXPECTED_PI_VERSION env var. Same latent bug exists in opencode-devbox's with-pi variants but is masked there because OPENCODE_VERSION bumps invalidate downstream layers — will only manifest when cutting a vN.N.Nb-style opencode-version-unchanged release that only bumps pi.

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.