v1.0.0: decouple from opencode-devbox

Self-contained build chain — own Dockerfile.base + Dockerfile.variant
+ entrypoint scripts + rootfs + CI pipeline. Previously v0.79.0 and
earlier were thin re-brands of opencode-devbox's pi-only variant
(joakimp/pi-devbox:base-pi-only built by opencode-devbox CI).

Architectural changes:
- Replace 5-line Dockerfile shim with full base+variant pair.
- Adapt CI workflow from opencode-devbox/docker-publish-split.yml,
  simplified to a single variant. Includes content-addressed base hash,
  PI_VERSION concrete-resolution to defeat registry-buildcache footgun,
  crane-based base-latest promotion, and the c6f9d11 smoke-test gate.
- pi-devbox releases no longer require rebuilding opencode-devbox first.

Base image additions:
- pandoc, graphviz, imagemagick, yq — broadly useful, ~260 MB total.
- tldr (tealdeer) — Rust port replaces Node tldr global, saves 135 MB.
- /etc/tmux.conf with base-index 0 + pane-base-index 0 — required for
  the planned :latest-studio variant; pi-studio hard-codes :0.0 target.

Smoke test:
- New checks for pandoc, graphviz, imagemagick, yq, tldr, tmux config,
  /tmp/sshcm directory.
- Image-size measurement now sums docker history layers (the prior
  inspect --format='{{.Size}}' returned only the variant-unique layer
  with the new base/variant split, understating by 2+ GB).
- Threshold 2850 → 3500 MB to absorb base additions + arch margin.

Image size:
- Local arm64 build: 3.20 GB. ~390 MB up from prior pi-only equivalent.
- Will tighten threshold once amd64 actuals settle in CI.

Pre-1.0 history preserved at tag pre-v1.0.0-decouple-backup.

Future work:
- v1.1.0: :latest-studio variant (adds pi-studio).
- v1.2.0: :latest-studio-tex variant (adds texlive-xetex for PDF).
- opencode-devbox v2.0.0 will retire INSTALL_PI / pi-only paths.

AGENTS.md

@@ -1,65 +1,130 @@
 # 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.
+Self-contained Docker image for the **pi coding-agent**. Decoupled from
+opencode-devbox at v1.0.0 (2026-06-09); previously pi-devbox was a thin
+re-brand of opencode-devbox's `pi-only` variant.
 
 ## 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
+- `Dockerfile.base` — multi-arch base layer with system packages,
+  GitHub-binary tools (fzf, eza, zoxide, neovim, bat, gosu, gitleaks,
+  git-lfs, uv, gitea-mcp, tealdeer), AWS CLI v2, mempalace + toolkit,
+  Node.js, Python toolchain, locales, ssh ControlMaster defaults, and
+  `/etc/tmux.conf` with 0-indexed sessions.
+- `Dockerfile.variant` — `FROM base-<hash>`, adds pi + companions
+  (`pi-toolkit`, `pi-extensions`, `pi-fork`, `pi-observational-memory`).
+- `entrypoint.sh` — UID/GID alignment as root, then drops to `developer`.
+- `entrypoint-user.sh` — per-container start: SSH ControlMaster socket
+  dir, LAN-access setup, MemPalace init, pi-toolkit + pi-extensions
+  deploy, mempalace-bridge symlink, fork/recall pi-install, skillset
+  deploy.
+- `rootfs/` — files baked into the image (bash aliases, inputrc,
+  setup-lan-access.sh).
+- `scripts/smoke-test.sh` — sanity checks run by CI before pushing to Hub.
+- `.gitea/workflows/docker-publish.yml` — two-phase CI (base-decide →
+  build-base → smoke → build-variant → promote-base-latest →
+  update-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`
+- Tags follow semver. **v1.0.0** is the first decoupled release; future
+  minor bumps add variants (`-studio`, `-studio-tex`); patch bumps follow
+  pi npm version updates and small fixes.
+- Docker Hub tags: `joakimp/pi-devbox:vX.Y.Z` + `joakimp/pi-devbox:latest`.
+  Internal tags: `joakimp/pi-devbox:base-<hash>` (content-addressed) +
+  `joakimp/pi-devbox:base-latest` (alias of most recent base).
 
 ## 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
+1. Confirm `pi --version` resolves from npm to the expected version
+   (`curl -sf 'https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest' | jq -r .version`).
+2. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
+3. Verify `docker compose up` works locally with the current `latest` image
+   if you're upgrading users from a previous version.
+4. Push tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
+5. Watch CI: smoke job builds amd64 only and asserts size + extensions +
+   pi version + new-base-tooling presence. Variant build is multi-arch
+   (amd64 + arm64) only after smoke passes.
+6. Verify the Hub tags appear (latest + vX.Y.Z, plus base-latest if the
+   base was rebuilt this run).
+7. **Revoke any short-lived Gitea PAT** used during the release at
+   `gitea.jordbo.se/user/settings/applications`.
 
-When drafting CHANGELOG entries, pull pi's release notes from the
-`CHANGELOG.md` shipped inside the npm tarball:
+## Cache-hit footgun (must-know)
 
-```bash
-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_VERSION` defaults to `latest` in `Dockerfile.variant` but **CI must
+resolve it to a concrete version string** before passing as a build-arg.
+Otherwise the build-arg string is byte-identical across releases →
+identical layer hash → registry buildcache silently reuses the old
+layer. `resolve-versions` job in the workflow handles this.
 
-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.
+Discovered in pi-devbox 2026-05-23 (every release v0.74.0..v0.75.5
+shipped the same image bytes); preventatively fixed for `PI_VERSION` +
+`PI_FORK_REF` + `PI_OBSMEM_REF`.
 
-## Key facts
+## Smoke-test gate
 
-- **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.
+`scripts/smoke-test.sh` runs amd64-only against a freshly-built variant
+image. Verifies binaries, repo clones, runtime deployment (waits for
+keybindings + mempalace bridge + ≥4 extensions before sampling — fixes
+the parallel-build-load race documented in opencode-devbox c6f9d11
+2026-06-08), and image size threshold (3500 MB; revisit after a few
+releases as actuals settle).
 
-## Conventions
+If smoke fails on size threshold but build is otherwise fine: bump
+`SIZE_THRESHOLD_MB` in scripts/smoke-test.sh in a follow-up commit and
+re-run. The threshold exists to catch *runaway* growth (an accidental
+texlive bake-in, a forgotten chrome dependency), not to block ordinary
+upstream bumps.
 
-- 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).
+## Build pipeline notes
 
-## Documentation drift sweep
+- **Two-phase**: base + variant. Base is rebuilt only when
+  `Dockerfile.base`, `rootfs/`, or `entrypoint*.sh` change (CI computes
+  a content hash and probes Hub for an existing `base-<hash>` tag).
+- **`base-latest` alias** is promoted from `base-<hash>` via `crane copy`
+  (manifest copy, no rebuild) only when the base actually changed.
+- **`docker buildx build --push` retry**: 3 attempts with backoff for
+  transient Hub blips. Deterministic failures fail all 3 and the job
+  fails as expected.
+- **Registry buildcache disabled**: buildkit's cache-export hits HTTP 400
+  on Hub CDN since ~2026-05-23. Image push works fine; we pay the full
+  base build on Dockerfile.base change, but base tags are content-
+  addressed so unchanged bases short-circuit at the probe step.
 
-Before committing any non-trivial change, check that prose still matches code. Drift hotspots in this repo:
+## Decoupling history (briefly)
 
-- `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.
+Pre-v1.0.0 pi-devbox was `FROM joakimp/pi-devbox:base-pi-only`, where
+`base-pi-only` was a tag built by **opencode-devbox CI** (with
+`INSTALL_OPENCODE=false` in their variant Dockerfile) and pushed under
+the pi-devbox repo as an internal building-block tag. This setup
+required rebuilding opencode-devbox before pi-devbox could be tagged
+and meant pi-devbox docs needed cross-referencing into opencode-devbox.
 
-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`.
+v1.0.0 brings pi install logic into this repo, drops the cross-repo
+dependency, and the `base-pi-only*` tags from opencode-devbox become
+deprecated artifacts (to be removed in opencode-devbox v2.0.0).
+
+## What we DON'T install (and why)
+
+- **No texlive** (~600 MB–1 GB). Users who need PDF export from pandoc
+  can install on demand: `sudo apt-get install texlive-xetex
+  texlive-latex-recommended`. The planned `:latest-studio-tex` variant
+  will bake this in.
+- **No pi-studio** (yet). Coming in v1.1.0 as the `:latest-studio`
+  variant. v1.0.0 is intentionally scope-limited to "decouple, don't
+  reshape."
+- **No Julia/R/GHCi/Clojure runtimes**. Use `uv run --with X` for
+  Python REPLs; `apt install` other-language runtimes ad-hoc per
+  container if needed.
+
+## Backward compatibility
+
+- The host `~/.mempalace` bind-mount path is unchanged.
+- Volume names (`devbox-pi-config`, `devbox-bash-history`,
+  `devbox-nvim-data`, `devbox-uv-tools`, `devbox-chroma-cache`) are
+  unchanged.
+- `~/.pi/agent/` layout inside the container is unchanged; existing
+  named volumes work without recreation.
+- The `:latest` and `vX.Y.Z` Hub tags continue to point at a "base + pi"
+  image. Same tag, same shape, just built differently.