# 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:

```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
- **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

## 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`.