Files

T

joakimp ae6253ab23 AGENTS.md: documentation-drift sweep as explicit pre-commit step

Companion to the same addition in the cloud-init and ansible repos.
Caught real drift in those repos in a recent session only because
the user explicitly asked. Codify the sweep with concrete, repo-
specific drift hotspots rather than a vague 'watch for drift' rule
that gets ignored.

Each AGENTS.md addition lists the doc files most likely to fall
behind code changes here, plus a quick-triage one-liner using
'git diff --name-only HEAD | xargs grep -l ...' so the rule is
actionable not aspirational.

2026-05-20 23:11:59 +02:00

2.9 KiB

Raw Blame History

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

Bump PI_VERSION in Dockerfile (or leave as latest to pick up current)
Update CHANGELOG.md: promote Unreleased → vX.Y.Z — YYYY-MM-DD
Add fresh ## Unreleased section
Commit, tag vX.Y.Z, push tag → CI fires automatically

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.

2.9 KiB Raw Blame History