refactor: re-brand the opencode-devbox with-pi variant (single source of truth)

pi-devbox no longer installs pi itself. The Dockerfile is now a thin
FROM joakimp/opencode-devbox:latest-with-pi (overridable via BASE_IMAGE),
inheriting pi + pi-toolkit + pi-extensions + pi-fork (fork) +
pi-observational-memory (recall) + the LAN-access helper + all base tooling
from the single source of truth. Eliminates the install-logic duplication
that drifted against opencode-devbox/Dockerfile.variant (decision #3).

Consequences (documented in CHANGELOG/AGENTS):
- The image now ALSO contains opencode (with-pi has INSTALL_OPENCODE=true).
  A leaner pi-only image would need a dedicated pi-only variant upstream.
- Publish ordering: release opencode-devbox first so latest-with-pi 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 — turning the version coupling into an enforced ordering guard.

CI: drop PI_VERSION build-arg (Dockerfile installs nothing); keep tag->version
resolution to feed the smoke base-freshness guard. Smoke adds fork/recall
clone + node_modules + settings.json registration checks; size threshold
2200 -> 2900 MB (now tracks with-pi). Docs updated across README, AGENTS,
DOCKER_HUB, .env.example, docker-compose.

AGENTS.md

@@ -1,10 +1,11 @@
 # AGENTS.md — pi-devbox
 
-Container image that adds pi coding-agent on top of the opencode-devbox base image.
+Container image that re-brands the opencode-devbox **with-pi** variant as a
+pi-focused image. As of 2026-06-03 it no longer installs pi itself.
 
 ## Repository layout
 
-- `Dockerfile` — single-stage build, `FROM opencode-devbox:base-latest`, installs pi + companion repos
+- `Dockerfile` — thin re-brand: `FROM opencode-devbox:latest-with-pi` (overridable via `BASE_IMAGE` arg). No install logic of its own — pi + companions are inherited from the with-pi variant. 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
@@ -13,12 +14,12 @@ Container image that adds pi coding-agent on top of the opencode-devbox base ima
 ## 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
+- The image inherits pi from `latest-with-pi`, so the **publish ordering matters**: rebuild opencode-devbox first so `latest-with-pi` 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. Bump `PI_VERSION` in `Dockerfile` (or leave as `latest` to pick up current)
+1. Ensure opencode-devbox has been released so `joakimp/opencode-devbox:latest-with-pi` 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
@@ -38,27 +39,27 @@ per version. Don't try to derive notes from the npm registry metadata
 
 ## 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
+- **Base image**: `joakimp/opencode-devbox:latest-with-pi` — the single source of truth for the pi install + companions. Rebuilt whenever opencode-devbox releases.
+- **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. Because it FROMs with-pi, the image **also contains opencode**.
+- **Companion repos**: cloned to `/opt/` by the with-pi build; `entrypoint-user.sh` (inherited) deploys/registers them on container start.
+- **MemPalace**: fully operational — inherited from base; 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.
+- 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 2900 MB (tracks the with-pi 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 `latest-with-pi`, override the `BASE_IMAGE` arg (a version 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`).
-- `AGENTS.md` (this file) — `Key facts` block (pi binary path, `NPM_CONFIG_PREFIX`, base-image tag), smoke-test threshold number.
+- `README.md` — quick-start examples, env-var table, base-image reference (must match `FROM` in `Dockerfile`), "what's inside" (now includes opencode + fork/recall).
+- `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.
-- `Dockerfile` `PI_VERSION` ARG default — if you intend to pin (rather than `latest`), bump it on release.
+- `.env.example` — hand-updated, must match Dockerfile/entrypoint env vars (including the inherited LAN-access knobs).
+- `Dockerfile` `BASE_IMAGE` ARG default — the with-pi 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`.