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