opencode-devbox/docs/CLEANUP-v2.0.0.md

PR-5: Retire pi from opencode-devbox

After pi-devbox has shipped v1.0.0 as a fully independent image (with its own base + variant Dockerfiles, CI, smoke tests, and docs), the pi-related paths in opencode-devbox become dead weight. This PR removes them.

Pre-conditions before merging

This PR should land only after all of the following are stable:

1. pi-devbox v1.0.0 published, smoke tests passing, in active use for at least one release cycle.
2. Anyone consuming joakimp/pi-devbox:base-pi-only directly (e.g. forks pinned to it) has been notified and migrated.
3. The deprecation warning (PR-1 of this work — see below) has been live for at least one release cycle so consumers have visible notice.

Files / sections to remove from opencode-devbox

Dockerfile.variant

Remove these blocks entirely:

• The INSTALL_PI / PI_VERSION / PI_TOOLKIT_REF / PI_EXTENSIONS_REF / PI_FORK_REPO / PI_FORK_REF / PI_OBSMEM_REPO / PI_OBSMEM_REF build-args.
• The RUN if [ "${INSTALL_PI}" = "true" ]; then ... block (entire block — git_clone_retry, git_fetch_ref, npm install pi-coding-agent, the four /opt/pi-* clones, the npm installs in /opt/pi-fork and /opt/pi-observational-memory, and the four rev-parse echoes).
• All comments referencing pi-only as "the single source of truth for the pi-devbox image" (the variant matrix table, the explanatory paragraph, and the "rationale" comments at the top of the file about pi-only existing for pi-devbox to FROM).

Update the variant matrix table at the top of Dockerfile.variant:

   variant            INSTALL_OPENCODE  INSTALL_OMOS
   ─────────────────  ────────────────  ────────────
   base               true              false
   omos               true              true

(only two variants now; pi-only and the with-pi/omos-with-pi axis are gone).

entrypoint-user.sh

Remove:

• The pi-toolkit and pi-extensions install hooks (the section that runs (cd /opt/pi-toolkit && ./install.sh --yes) etc.).
• The ~/.pi/agent/settings.json seeding from /opt/pi-toolkit/settings.example.json.
• Any other pi-conditional blocks (search for INSTALL_PI, pi-toolkit, pi-extensions, ~/.pi/).

Verify that the AWS Bedrock auth bootstrap (the pi-toolkit AWS env loader) is not relied on by opencode users. If it is, lift it out of the pi-toolkit dependency (it's small and self-contained).

Dockerfile.base

Remove:

• The mkdir -p /home/${USER_NAME}/.pi/agent/extensions line in the standard-directories block. Replace with the equivalent opencode- specific paths if any aren't already present (~/.config/opencode is already there).
• NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global — change to /home/${USER_NAME}/.config/opencode/npm-global or a more neutral path. Update the corresponding PATH env var.

Also update the long base-image header comment to remove the "variants for pi-devbox" rationale.

CI (.gitea/workflows/docker-publish-split.yml or equivalent)

Remove:

• The pi-only variant build job.
• The with-pi and omos-with-pi variant build jobs (they're redundant with the standalone pi-devbox now).
• The base-pi-only tag publish step (which pushes to joakimp/pi-devbox:base-pi-only from this repo).
• The resolve-pi-version job step (no longer needed).
• Smoke-test invocations with --variant pi-only, --variant with-pi, --variant omos-with-pi.

Remaining variants in CI: base, omos. The "with-pi" axis is fully retired.

scripts/smoke-test.sh

Remove:

• The --variant pi-only, --variant with-pi, --variant omos-with-pi branches.
• pi-related assertions: pi --version, the ~/.pi/agent/extensions/*.ts ≥ 4 check, the mempalace.ts bridge gate (mempalace itself stays, but its bridge into pi is no longer this image's concern).

Remaining variant axis in smoke tests: base, omos.

README.md (and AGENTS.md, DOCKER_HUB.md)

• Remove the pi-only variant from the "Image variants" table.
• Remove the with-pi / omos-with-pi variants if they were documented.
• Remove all sections about pi-toolkit, pi-extensions, pi-fork, pi-observational-memory, ~/.pi paths, and pi-related env vars.
• Remove the "this image also produces base-pi-only for pi-devbox" notes.
• Add a single-paragraph "Looking for pi?" section pointing to joakimp/pi-devbox.

Dockerfile references in pi-devbox repo (cleanup of cross-repo coupling)

This isn't a change to opencode-devbox, but it's part of the same deprecation:

• Once pi-devbox v1.0.0 is the single source of truth, remove pi-devbox/Dockerfile (the 5-line shim with the long joakimp/pi-devbox:base-pi-only rationale comment). It's replaced by Dockerfile.base + Dockerfile.variant produced by PR-1 of this work.

Two-step deprecation path (recommended)

Rather than a single big-bang removal, use a deprecation cycle:

Step 1 — pre-PR (lands at the same time as pi-devbox v1.0.0)

Add a deprecation warning to opencode-devbox:

1. Build-time message — when INSTALL_PI=true, INSTALL_PI_DEPRECATED=warn is the default; the variant build prints to stderr:

   ===========================================================
   DEPRECATION WARNING: INSTALL_PI is deprecated in opencode-devbox
   and will be removed in v2.0.0. Use joakimp/pi-devbox:latest
   instead. See https://gitea.jordbo.se/joakimp/pi-devbox
   ===========================================================
   

2. CHANGELOG entry on opencode-devbox: "INSTALL_PI build-arg path deprecated; will be removed in v2.0.0."
3. README and DOCKER_HUB updates: mark pi-only, with-pi, omos-with-pi variants as deprecated, point to pi-devbox.
4. The base-pi-only tag continues to be published but with a notice in the description: "Internal artifact for pi-devbox. Deprecated; pull joakimp/pi-devbox:latest directly."

Step 2 — removal PR (this document)

Lands one release cycle (or one calendar month, whichever is later) after step 1. Removes everything listed in the per-file sections above. Tagged as opencode-devbox v2.0.0 (the major bump signals the breaking change).

Risk assessment

What could go wrong

• Someone is consuming base-pi-only directly without going through pi-devbox. The deprecation warning + one-cycle delay should surface this.
• Mempalace bridge in pi-extensions — this stays in pi-devbox; no impact on opencode-devbox.
• Shared base assumptions — opencode-devbox's ~/.pi/npm-global NPM_CONFIG_PREFIX was a pi-specific design. In the cleanup we move it to a neutral path. Existing opencode-devbox users get a one-time migration: their npm install -g packages installed at the old path stop being on PATH. Document this in the v2.0.0 changelog and add a one-liner that copies the old prefix contents to the new one if the old one exists.

What's safe

• The base apt set, the Go-binary installs, MemPalace, the SSH ControlMaster setup, the entrypoint UID/GID dance — all of these stay. They're not pi-specific.
• The omos variant — fully unaffected.
• Existing opencode-only users — no change to their workflow.

Verification

After PR-5 lands, the following should be true:

• grep -ri "INSTALL_PI\|pi-toolkit\|pi-extensions\|pi-fork\|pi-observational-memory\|base-pi-only" . in opencode-devbox returns no matches.
• docker history joakimp/opencode-devbox:latest shows no pi-related layers.
• The opencode-devbox CI matrix builds only base and omos variants.
• pi-devbox CI is unaffected (it's a different repo).
• Both repos build cleanly in their own CI without referencing the other.

Estimated effort

• Step 1 (deprecation warnings): ~2 hours.
• Step 2 (removal): ~4 hours including local testing of opencode-only build paths.
• One release cycle of monitoring between them.

Total: ~1 working day of focused effort, spread over a calendar month.

Order in the broader plan

1. PR-1 on pi-devbox — copy base + variant Dockerfiles, strip opencode/omos paths, tag v1.0.0.
2. PR-2 on pi-devbox — add pandoc, graphviz, imagemagick, tldr, yq.
3. PR-3 on pi-devbox — add :latest-studio variant.
4. (Optional) PR-4 on pi-devbox — add :latest-studio-tex variant.
5. PR-pre on opencode-devbox — deprecation warnings (step 1 above).
6. PR-5 on opencode-devbox — actual removal (this document, step 2).

PRs 1–4 are independent and can land in any order on pi-devbox. PR-pre should land alongside or shortly after pi-devbox v1.0.0 (PR-1) so consumers know to migrate. PR-5 lands one release cycle after PR-pre.