pi-devbox/AGENTS.md

AGENTS.md — pi-devbox

Container image that re-brands the opencode-devbox pi-only variant as a pi-focused image. As of 2026-06-03 it no longer installs pi itself.

Repository layout

• Dockerfile — thin re-brand: FROM joakimp/pi-devbox:base-pi-only (overridable via BASE_IMAGE arg). No install logic of its own — pi + companions are inherited from the pi-only build (built INSTALL_OPENCODE=false, so no opencode — that's the distinction from opencode-devbox:latest-with-pi). The base-pi-only tag is produced by opencode-devbox CI (from opencode-devbox/Dockerfile.variant) but published into THIS repo as an internal building-block tag. This refactor removed the install-logic duplication that used to drift against opencode-devbox/Dockerfile.variant.
• 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]
• The image inherits pi from base-pi-only, so the publish ordering matters: rebuild opencode-devbox first so joakimp/pi-devbox:base-pi-only carries the target pi version, then tag this repo. The smoke test asserts pi --version matches the tag (EXPECTED_PI_VERSION) and fails loudly if the base is stale.
• Docker Hub: joakimp/pi-devbox:vX.Y.Z + joakimp/pi-devbox:latest

Release-day checklist

1. Ensure opencode-devbox has been released so joakimp/pi-devbox:base-pi-only carries the target pi version (and the fork/recall extensions). This is the hard prerequisite — the smoke guard enforces it.
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/pi-devbox:base-pi-only — an internal building-block tag (produced by opencode-devbox CI from Dockerfile.variant, the single source of truth for the pi install + companions; published into this repo, not under opencode-devbox). Rebuilt whenever opencode-devbox releases. Not for end users — they pull joakimp/pi-devbox:latest or a vX.Y.Z tag.
• Inherited content: pi (/usr/bin/pi), pi-toolkit, pi-extensions, pi-fork (fork), pi-observational-memory (recall), the mempalace bridge, the LAN-access helper, entrypoints, and all base dev tooling. The pi-only variant is built INSTALL_OPENCODE=false, so the image does not contain opencode.
• Companion repos: cloned to /opt/ by the pi-only build; entrypoint-user.sh (inherited) deploys/registers them on container start.
• MemPalace: fully operational — inherited from base; bridge extension deployed by entrypoint.

Conventions

• This repo no longer installs pi or clones companion repos — do not re-add that logic here. Change it in opencode-devbox/Dockerfile.variant (the single source of truth) instead.
• The smoke test threshold is 2750 MB (tracks the pi-only variant) — update if the image legitimately grows past it.
• The CI still resolves the tag's pi version, but only to feed EXPECTED_PI_VERSION to the smoke base-freshness guard — it is no longer passed as a build-arg (nothing in the Dockerfile consumes it).
• To pin a specific base build instead of tracking base-pi-only, override the BASE_IMAGE arg (a base-pi-only-vX.Y.Z tag or a digest).

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), "what's inside" (fork/recall; no opencode).
• AGENTS.md (this file) — Key facts block (base-image tag, inherited content), 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 (including the inherited LAN-access knobs).
• Dockerfile BASE_IMAGE ARG default — the pi-only tag this image tracks.

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.