feat: split-base build pipeline (parallel, manual-trigger only)

Two-Dockerfile split-base build alongside the existing single-Dockerfile
pipeline. Goal: cut CI wall clock from ~165-180min to ~30-40min on
typical version-bump-only releases by reusing a base image across the
four variants.

Files added:
- Dockerfile.base       variant-independent layers (apt, locales, AWS
                        CLI, Node.js, mempalace, gitea-mcp, user setup,
                        chromadb prewarm, ENVs, entrypoints).
- Dockerfile.variant    FROMs ${BASE_IMAGE} and adds opencode / pi /
                        omos / Go installs gated by INSTALL_* args.
                        Each npm install -g uses NPM_CONFIG_PREFIX=/usr
                        per-RUN to keep baked binaries off the volume-
                        shadowed ~/.pi/npm-global path inherited from
                        base.
- .gitea/workflows/docker-publish-split.yml
                        workflow_dispatch-only pipeline:
                        base-decide -> build-base (conditional) ->
                        smoke-* (4 parallel) -> build-variant-*
                        (4 parallel) -> promote-base-latest ->
                        update-description. Hash-driven base reuse:
                        if base-<sha> already exists on Docker Hub,
                        the build is skipped entirely. Inputs:
                        release_tag (test tag suffix, default
                        v0.0.0-split-test) and promote_latest
                        (default false; gates latest-* aliases and
                        Hub description update).

Files unchanged:
- Dockerfile, docker-publish.yml, validate.yml all left in place so
  the production tag-push pipeline keeps working untouched.

Migration plan (in CHANGELOG Unreleased):
1. workflow_dispatch test run with promote_latest=false; verify the
   four variant images smoke-pass and have plausible sizes.
2. Compare manifest digests against the same-version output from the
   production pipeline (independent test run on the same commit).
3. Once verified across 1-2 release cycles, swap docker-publish-split.yml
   to on: push: tags: v* and retire docker-publish.yml.

AGENTS.md and CHANGELOG.md updated with file roles and the migration
plan. Production pipeline behavior is bit-for-bit unchanged on this
branch.

.env.example

@@ -7,7 +7,7 @@
 OPENCODE_PROVIDER=anthropic
 
 # Model override (optional, defaults per provider)
-# OPENCODE_MODEL=anthropic/claude-sonnet-4-5
+# OPENCODE_MODEL=anthropic/claude-sonnet-4-6
 
 # ── API Keys (set the one matching your provider) ────────────────────
 # ANTHROPIC_API_KEY=
@@ -31,9 +31,68 @@ WORKSPACE_PATH=~/projects
 # Path to SSH keys on host
 SSH_KEY_PATH=~/.ssh
 
+# ── Skillset (agent skills and instructions) ─────────────────────────
+# If you have a skillset repo, the entrypoint auto-deploys skills and
+# instructions on container start using relative symlinks (portable
+# across host/container).
+#
+# Detection is automatic if the skillset lives directly at the workspace
+# root (i.e. WORKSPACE_PATH/skillset → /workspace/skillset in container).
+#
+# If the skillset lives in a subdirectory of your workspace, set
+# SKILLSET_CONTAINER_PATH to its location *inside the container*. This
+# is determined by the workspace mount: whatever is at
+# WORKSPACE_PATH/<subpath> on the host becomes /workspace/<subpath>
+# in the container.
+#
+# Examples:
+#   Host skillset at ~/projects/skillset        → already at /workspace/skillset (auto-detected, no config needed)
+#   Host skillset at ~/projects/tools/skillset  → SKILLSET_CONTAINER_PATH=/workspace/tools/skillset
+#   Host skillset at ~/projects/local/skillset  → SKILLSET_CONTAINER_PATH=/workspace/local/skillset
+#
+# Alternatively, mount the skillset repo at a dedicated path using the
+# SKILLSET_PATH volume in docker-compose.yml (see comments there). In
+# that case the entrypoint finds it at ~/skillset automatically.
+#
+# SKILLSET_CONTAINER_PATH=
+
+# ── Locale (defaults to en_US.UTF-8) ─────────────────────────────────
+# LANG=sv_SE.UTF-8
+# LANGUAGE=sv_SE:sv
+# LC_ALL=sv_SE.UTF-8
+
 # ── oh-my-opencode-slim (multi-agent orchestration) ──────────────────
 # Requires image built with INSTALL_OMOS=true
 # ENABLE_OMOS=false
 # OMOS_TMUX=false              # Enable tmux multiplexer integration
 # OMOS_SKILLS=true             # Install recommended skills (simplify, agent-browser, cartography)
 # OMOS_RESET=false             # Force regenerate oh-my-opencode-slim config on next start
+
+# ── pi coding-agent (alternative/complementary harness) ─────────────────
+# Requires image built with INSTALL_PI=true.
+# When the image is built with both INSTALL_OPENCODE=true (default) and
+# INSTALL_PI=true, both harnesses share the same mempalace install and
+# palace path — wing data is mutually visible to either harness.
+#
+# Pi version is baked at build time via PI_VERSION (default: latest at
+# build). The baked `pi` binary is at /usr/bin/pi (system npm prefix);
+# rebuild the image to upgrade it. NPM_CONFIG_PREFIX is set to
+# /home/developer/.pi/npm-global, so anything installed via
+# `pi install npm:...` or `npm install -g` as the developer user
+# (themes, skills, extensions, including a user-installed pi itself)
+# lands on the named volume and survives container recreate AND image
+# rebuilds. A user-installed pi wins via PATH order over the baked one.
+#
+# Pi config (settings.json, extensions toggle state, sessions, auth) persists in the
+# devbox-pi-config named volume mounted at ~/.pi/.
+#
+# To launch pi from a `compose run` invocation:
+#   docker compose run --rm devbox pi
+# To attach to a running container:
+#   docker compose exec -u developer devbox pi
+# Default `compose run` (no args) drops to bash; pick the harness yourself.
+#
+# Build args (set in docker-compose.yml or via --build-arg on docker build):
+#   INSTALL_PI=true              # default false; opt-in
+#   PI_VERSION=latest            # pin a specific version, e.g. 0.73.0
+#   INSTALL_OPENCODE=false       # build a pi-only image (still has Bun in -omos)

.env.shared.example

@@ -0,0 +1,33 @@
+# ── Shared machine setup ─────────────────────────────────────────────
+# SIGNUM isolates your container name and named volumes from other users.
+#
+# Own-account mode (each user has their own OS login):
+#   Leave SIGNUM commented out — it defaults to your OS username ($USER).
+# SIGNUM=
+#
+# Shared-account mode (everyone logs in as the same OS user):
+#   Uncomment and set to your unique identifier.
+# SIGNUM=your-signum-here
+
+# ── Provider ─────────────────────────────────────────────────────────
+OPENCODE_PROVIDER=amazon-bedrock
+OPENCODE_MODEL=amazon-bedrock/eu.anthropic.claude-opus-4-6-v1
+AWS_REGION=eu-west-1
+AWS_PROFILE=default
+
+# ── Git ──────────────────────────────────────────────────────────────
+GIT_USER_NAME=Your Name
+GIT_USER_EMAIL=your.name@example.com
+
+# ── Paths (adjust to your layout) ───────────────────────────────────
+# Default: ~/src mounted as /workspace
+# WORKSPACE_PATH=~/src
+
+# SSH keys — defaults to shared ~/.ssh
+# If you have per-user keys: SSH_KEY_PATH=~/<signum>/.ssh
+# SSH_KEY_PATH=~/.ssh
+
+# ── Locale (defaults to en_US.UTF-8) ────────────────────────────────
+# LANG=sv_SE.UTF-8
+# LANGUAGE=sv_SE:sv
+# LC_ALL=sv_SE.UTF-8

.gitea/workflows/docker-publish-split.yml

@@ -0,0 +1,576 @@
+name: Publish Docker Image (split-base)
+
+# Two-phase split-base build pipeline. Lives ALONGSIDE the original
+# docker-publish.yml during the migration window. Triggers only on
+# workflow_dispatch (manual) so it doesn't conflict with the production
+# tag-trigger pipeline.
+#
+# Once we've validated 1-2 successful runs and verified output
+# byte-for-byte against the original, this workflow takes over `on:
+# push: tags: v*` and the original is retired.
+#
+# Pipeline shape:
+#   1. base-decide      compute base hash from Dockerfile.base + rootfs/
+#                       + entrypoints; probe Docker Hub for existing tag.
+#   2. build-base       only if probe missed; multi-arch push of base-<hash>.
+#   3. smoke-* (×4)     amd64-only build of each variant FROMing the base
+#                       tag; runs scripts/smoke-test.sh.
+#   4. build-variant-*  multi-arch push of each variant tag (the user-
+#       (×4)            facing release tags, unchanged in shape).
+#   5. promote-base-latest  re-tag base-<hash> → base-latest with `crane copy`
+#                       (manifest copy, no rebuild).
+#   6. update-description   patch Docker Hub description (unchanged).
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release tag to publish (e.g. v1.14.42-split). Pushed to Docker Hub as both the literal tag and `latest*`-aliases.'
+        required: true
+        default: 'v0.0.0-split-test'
+      promote_latest:
+        description: 'Update latest/latest-omos/latest-with-pi/latest-omos-with-pi aliases (set false for test runs)'
+        required: false
+        default: 'false'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  BUILDKIT_PROGRESS: plain
+  IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox
+
+# ───────────────────────────────────────────────────────────────────
+# Reusable disk-reclaim snippet — strips catthehacker toolchains and
+# stale docker state. Identical to the production workflow's pattern.
+# ───────────────────────────────────────────────────────────────────
+
+jobs:
+  # ── Phase 1: decide whether base needs rebuilding ──────────────────
+  base-decide:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    outputs:
+      base_tag: ${{ steps.compute.outputs.base_tag }}
+      need_build: ${{ steps.probe.outputs.need_build }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Compute base tag from Dockerfile.base + dependencies
+        id: compute
+        run: |
+          # Hash inputs that determine the base image's contents.
+          # Order is fixed via `find -print0 | sort -z` for reproducibility.
+          HASH=$(
+            {
+              cat Dockerfile.base
+              find rootfs -type f -print0 2>/dev/null | sort -z | xargs -0 cat 2>/dev/null
+              cat entrypoint.sh entrypoint-user.sh
+            } | sha256sum | cut -c1-12
+          )
+          BASE_TAG="base-${HASH}"
+          echo "base_tag=${BASE_TAG}" >> "$GITHUB_OUTPUT"
+          echo "Computed base tag: ${BASE_TAG}"
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Probe Docker Hub for existing base tag
+        id: probe
+        run: |
+          set +e
+          docker manifest inspect "${IMAGE}:${{ steps.compute.outputs.base_tag }}" \
+            > /dev/null 2>&1
+          PROBE_RC=$?
+          set -e
+          if [ "${PROBE_RC}" = "0" ]; then
+            echo "need_build=false" >> "$GITHUB_OUTPUT"
+            echo "Base tag ${IMAGE}:${{ steps.compute.outputs.base_tag }} exists — skipping rebuild."
+          else
+            echo "need_build=true" >> "$GITHUB_OUTPUT"
+            echo "Base tag ${IMAGE}:${{ steps.compute.outputs.base_tag }} missing — will build."
+          fi
+
+  # ── Phase 2: build & push base (multi-arch), only when needed ──────
+  build-base:
+    needs: [base-decide]
+    if: needs.base-decide.outputs.need_build == 'true'
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push base (multi-arch)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.base
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+          # Registry cache for faster repeat base rebuilds (e.g. Node bump).
+          cache-from: type=registry,ref=${{ env.IMAGE }}:base-buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:base-buildcache,mode=max
+
+  # ── Phase 3: amd64 smoke per variant (gates the multi-arch publish) ─
+  # Each smoke job builds amd64-only against the base tag and runs
+  # scripts/smoke-test.sh. base-decide.outputs.base_tag is always set;
+  # build-base may have been skipped (cache hit) but the tag exists either way.
+
+  smoke-base:
+    needs: [base-decide, build-base]
+    if: |
+      always() &&
+      needs.base-decide.result == 'success' &&
+      (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - name: Reclaim runner disk
+        run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Build amd64 variant for smoke
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-base
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=false
+            INSTALL_PI=false
+      - name: Smoke test (amd64)
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-base --variant base
+
+  smoke-omos:
+    needs: [base-decide, build-base]
+    if: |
+      always() &&
+      needs.base-decide.result == 'success' &&
+      (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-omos
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=true
+            INSTALL_PI=false
+      - run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos --variant omos
+
+  smoke-with-pi:
+    needs: [base-decide, build-base]
+    if: |
+      always() &&
+      needs.base-decide.result == 'success' &&
+      (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-with-pi
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=false
+            INSTALL_PI=true
+      - run: bash scripts/smoke-test.sh opencode-devbox:smoke-with-pi --variant with-pi
+
+  smoke-omos-with-pi:
+    needs: [base-decide, build-base]
+    if: |
+      always() &&
+      needs.base-decide.result == 'success' &&
+      (needs.build-base.result == 'success' || needs.build-base.result == 'skipped')
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-omos-with-pi
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=true
+            INSTALL_PI=true
+      - run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos-with-pi --variant omos-with-pi
+
+  # ── Phase 4: multi-arch publish per variant ────────────────────────
+
+  build-variant-base:
+    needs: [base-decide, smoke-base]
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-qemu-action@v3
+        with: {platforms: arm64}
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Compute version-specific tags
+        id: tags
+        run: |
+          VERSION="${{ inputs.release_tag }}"
+          TAGS="${IMAGE}:${VERSION}"
+          if [ "${{ inputs.promote_latest }}" = "true" ]; then
+            TAGS="${TAGS}\n${IMAGE}:latest"
+          fi
+          echo -e "tags<<EOF\n${TAGS}\nEOF" >> "$GITHUB_OUTPUT"
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=false
+            INSTALL_PI=false
+          tags: ${{ steps.tags.outputs.tags }}
+
+  build-variant-omos:
+    needs: [base-decide, smoke-omos]
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-qemu-action@v3
+        with: {platforms: arm64}
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Compute version-specific tags
+        id: tags
+        run: |
+          VERSION="${{ inputs.release_tag }}"
+          TAGS="${IMAGE}:${VERSION}-omos"
+          if [ "${{ inputs.promote_latest }}" = "true" ]; then
+            TAGS="${TAGS}\n${IMAGE}:latest-omos"
+          fi
+          echo -e "tags<<EOF\n${TAGS}\nEOF" >> "$GITHUB_OUTPUT"
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=true
+            INSTALL_PI=false
+          tags: ${{ steps.tags.outputs.tags }}
+
+  build-variant-with-pi:
+    needs: [base-decide, smoke-with-pi]
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-qemu-action@v3
+        with: {platforms: arm64}
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Compute version-specific tags
+        id: tags
+        run: |
+          VERSION="${{ inputs.release_tag }}"
+          TAGS="${IMAGE}:${VERSION}-with-pi"
+          if [ "${{ inputs.promote_latest }}" = "true" ]; then
+            TAGS="${TAGS}\n${IMAGE}:latest-with-pi"
+          fi
+          echo -e "tags<<EOF\n${TAGS}\nEOF" >> "$GITHUB_OUTPUT"
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=false
+            INSTALL_PI=true
+          tags: ${{ steps.tags.outputs.tags }}
+
+  build-variant-omos-with-pi:
+    needs: [base-decide, smoke-omos-with-pi]
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+      - run: |
+          rm -rf /opt/hostedtoolcache /opt/microsoft /opt/az /opt/ghc \
+            /usr/local/.ghcup /usr/share/dotnet /usr/share/swift \
+            /usr/local/lib/android /usr/local/share/powershell \
+            /usr/local/share/chromium /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+      - uses: docker/setup-qemu-action@v3
+        with: {platforms: arm64}
+      - uses: docker/setup-buildx-action@v4
+        with: {driver-opts: network=host}
+      - uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      - name: Compute version-specific tags
+        id: tags
+        run: |
+          VERSION="${{ inputs.release_tag }}"
+          TAGS="${IMAGE}:${VERSION}-omos-with-pi"
+          if [ "${{ inputs.promote_latest }}" = "true" ]; then
+            TAGS="${TAGS}\n${IMAGE}:latest-omos-with-pi"
+          fi
+          echo -e "tags<<EOF\n${TAGS}\nEOF" >> "$GITHUB_OUTPUT"
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: Dockerfile.variant
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            BASE_IMAGE=${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+            INSTALL_OPENCODE=true
+            INSTALL_OMOS=true
+            INSTALL_PI=true
+          tags: ${{ steps.tags.outputs.tags }}
+
+  # ── Phase 5: promote base-<hash> → base-latest (manifest copy only) ─
+  promote-base-latest:
+    needs:
+      - base-decide
+      - build-variant-base
+      - build-variant-omos
+      - build-variant-with-pi
+      - build-variant-omos-with-pi
+    if: inputs.promote_latest == 'true'
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: imjasonh/setup-crane@v0.4
+      - name: Login (crane)
+        run: |
+          crane auth login docker.io \
+            -u ${{ vars.DOCKERHUB_USERNAME }} \
+            -p "${{ secrets.DOCKERHUB_TOKEN }}"
+      - name: Re-tag base-<hash> as base-latest
+        run: |
+          crane copy \
+            ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }} \
+            ${{ env.IMAGE }}:base-latest
+
+  # ── Phase 6: update Hub description (only on real release runs) ────
+  update-description:
+    needs:
+      - build-variant-base
+      - build-variant-omos
+      - build-variant-with-pi
+      - build-variant-omos-with-pi
+    if: inputs.promote_latest == 'true'
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Update Docker Hub description
+        run: |
+          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
+            -H "Content-Type: application/json" \
+            -d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
+            | jq -r .access_token)
+          if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
+            echo "::error::Failed to authenticate with Docker Hub API"
+            exit 1
+          fi
+          HTTP_CODE=$(jq -n \
+            --rawfile full DOCKER_HUB.md \
+            --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support." \
+            '{"full_description": $full, "description": $short}' | \
+            curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
+              "https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
+              -H "Authorization: Bearer $TOKEN" \
+              -H "Content-Type: application/json" \
+              -d @-)
+          if [ "$HTTP_CODE" != "200" ]; then
+            echo "Response body:"
+            cat /tmp/hub-response.txt
+            echo "::error::Docker Hub description update failed with HTTP $HTTP_CODE"
+            exit 1
+          fi

.gitea/workflows/docker-publish.yml

@@ -5,8 +5,56 @@ on:
     tags:
       - 'v*'
 
+# Serialize concurrent runs of the same workflow on the same ref so the
+# build jobs can't race `docker system prune` in the smoke gates
+# (pruning from one job can nuke another job's in-flight buildx cache).
+# cancel-in-progress: false — tag pushes are release events, we never
+# want to silently drop one.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+# Plain progress output from BuildKit — critical for diagnosing stalls
+# inside arm64-under-QEMU builds where the default collapsed progress UI
+# hides which step is stuck.
+env:
+  BUILDKIT_PROGRESS: plain
+
+# Runner disk pressure notes:
+# Gitea Actions runners use `catthehacker/ubuntu:act-latest` on a shared host
+# with limited overlay space (~40 GB, often 70%+ used at start). Two jobs
+# per variant:
+#   * smoke gate (amd64 only, `load: true` into local dockerd for smoke
+#     testing) — peak disk = tarball + unpacked image + buildx cache. The
+#     `Reclaim runner disk` step below strips catthehacker-resident
+#     toolchains and prunes stale docker state before buildx starts.
+#   * build job (amd64 + arm64, `push-by-digest` streaming directly to
+#     Docker Hub, no local unpack). Peak disk on push-by-digest is
+#     BuildKit's content store only — much smaller than `load: true`.
+#     `docker/build-push-action@v7` with comma-separated platforms
+#     publishes a proper multi-arch manifest in one step.
+#
+# Why not matrix + digest artifacts?
+#   An earlier revision split each arch into its own matrix job and used
+#   `actions/upload-artifact` to pass digests to a merge job. On Gitea
+#   Actions, `actions/{upload,download}-artifact@v4+` fails with
+#   `GHESNotSupportedError` — v4 relies on a GitHub-specific Artifact
+#   API that Gitea doesn't implement. Rather than downgrade to @v3 (the
+#   last Gitea-compatible release) we collapsed back to single-job
+#   multi-arch push. The matrix only helps when the build literally
+#   cannot fit on one runner, which push-by-digest + reclaim no longer
+#   hits for this image.
+#
+# Gitea Actions gotchas baked into this file:
+#   * `actions/{upload,download}-artifact` must stay at @v3 on Gitea.
+#   * Step scripts run under /bin/sh (dash) — no bash-isms like
+#     ${VAR//a/b}. Use `tr` or explicit `shell: bash`.
+#   * `docker/build-push-action@v7` with `platforms: a,b` works for
+#     multi-arch push natively; no matrix/merge dance needed.
+
 jobs:
-  build-base:
+  # ── Smoke test (amd64 only, gates the push jobs) ────────────────────
+  smoke-base:
     runs-on: ubuntu-latest
     container:
       image: catthehacker/ubuntu:act-latest
@@ -14,11 +62,265 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      # See docker-publish.yml preamble. `load: true` peak disk = tarball
+      # + unpacked image + buildx cache; the image now crosses the 40 GB
+      # runner overlay's starting headroom. Strip catthehacker-resident
+      # toolchains and any stale docker state up front.
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build and load amd64 image for smoke test
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:smoke-base
+
+      - name: Smoke test (amd64)
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-base --variant base
+
+  smoke-omos:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build and load amd64 image for smoke test
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_OMOS=true
+          tags: opencode-devbox:smoke-omos
+
+      - name: Smoke test (amd64)
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos --variant omos
+
+  smoke-with-pi:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build and load amd64 image for smoke test
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_PI=true
+          tags: opencode-devbox:smoke-with-pi
+
+      - name: Smoke test (amd64)
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-with-pi --variant with-pi
+
+  smoke-omos-with-pi:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build and load amd64 image for smoke test
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_OMOS=true
+            INSTALL_PI=true
+          tags: opencode-devbox:smoke-omos-with-pi
+
+      - name: Smoke test (amd64)
+        run: bash scripts/smoke-test.sh opencode-devbox:smoke-omos-with-pi --variant omos-with-pi
+
+  # ── Multi-arch push (single job per variant, comma-separated platforms) ─
+  build-base:
+    runs-on: ubuntu-latest
+    needs: smoke-base
+    timeout-minutes: 90
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      # Lighter reclaim than the smoke-gate version: push-by-digest
+      # doesn't write to host dockerd, so `docker system prune` adds
+      # little. BuildKit cache from prior runs is the thing to clear.
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+        with:
+          platforms: arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
 
       - name: Login to Docker Hub
         uses: docker/login-action@v4
@@ -28,11 +330,9 @@ jobs:
 
       - name: Extract version from tag
         id: version
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/}
-          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
-      - name: Build and push (base)
+      - name: Build and push (multi-arch)
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -44,17 +344,48 @@ jobs:
 
   build-omos:
     runs-on: ubuntu-latest
+    needs: smoke-omos
+    timeout-minutes: 90
     container:
       image: catthehacker/ubuntu:act-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker builder prune -af || true
+          df -h / || true
+
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v4
+        with:
+          platforms: arm64
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
 
       - name: Login to Docker Hub
         uses: docker/login-action@v4
@@ -64,11 +395,9 @@ jobs:
 
       - name: Extract version from tag
         id: version
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/}
-          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
 
-      - name: Build and push (omos)
+      - name: Build and push (multi-arch)
         uses: docker/build-push-action@v7
         with:
           context: .
@@ -80,9 +409,144 @@ jobs:
             ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-omos
             ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-omos
 
+  build-with-pi:
+    runs-on: ubuntu-latest
+    needs: smoke-with-pi
+    timeout-minutes: 90
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+        with:
+          platforms: arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Build and push (multi-arch)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            INSTALL_PI=true
+          tags: |
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-with-pi
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-with-pi
+
+  build-omos-with-pi:
+    runs-on: ubuntu-latest
+    needs: smoke-omos-with-pi
+    timeout-minutes: 90
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+        with:
+          platforms: arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Build and push (multi-arch)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          build-args: |
+            INSTALL_OMOS=true
+            INSTALL_PI=true
+          tags: |
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-omos-with-pi
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-omos-with-pi
+
   update-description:
     runs-on: ubuntu-latest
-    needs: [build-base, build-omos]
+    needs: [build-base, build-omos, build-with-pi, build-omos-with-pi]
     container:
       image: catthehacker/ubuntu:act-latest
     steps:
@@ -91,25 +555,27 @@ jobs:
 
       - name: Update Docker Hub description
         run: |
-          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/users/login/ \
+          TOKEN=$(curl -s -X POST https://hub.docker.com/v2/auth/token \
             -H "Content-Type: application/json" \
-            -d '{"username":"${{ vars.DOCKERHUB_USERNAME }}","password":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
-            | jq -r .token)
+            -d '{"identifier":"${{ vars.DOCKERHUB_USERNAME }}","secret":"${{ secrets.DOCKERHUB_TOKEN }}"}' \
+            | jq -r .access_token)
           if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
             echo "::error::Failed to authenticate with Docker Hub API"
             exit 1
           fi
           HTTP_CODE=$(jq -n \
-            --arg full "$(cat DOCKER_HUB.md)" \
-            --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support. Available in base and omos (multi-agent) variants." \
+            --rawfile full DOCKER_HUB.md \
+            --arg short "Portable AI dev environment for opencode. Debian-based with git, Node.js, AWS CLI, and SSH support." \
             '{"full_description": $full, "description": $short}' | \
-            curl -s -o /dev/null -w "%{http_code}" -X PATCH \
+            curl -s -o /tmp/hub-response.txt -w "%{http_code}" -X PATCH \
               "https://hub.docker.com/v2/repositories/${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox/" \
-              -H "Authorization: JWT $TOKEN" \
+              -H "Authorization: Bearer $TOKEN" \
               -H "Content-Type: application/json" \
               -d @-)
           echo "Docker Hub API returned: $HTTP_CODE"
           if [ "$HTTP_CODE" != "200" ]; then
+            echo "Response body:"
+            cat /tmp/hub-response.txt
             echo "::error::Docker Hub description update failed with HTTP $HTTP_CODE"
             exit 1
           fi

.gitea/workflows/validate.yml

@@ -0,0 +1,262 @@
+name: Validate
+
+# Lightweight validation on pushes to main. Builds single-arch (amd64),
+# runs the smoke test, and checks image size — without pushing anything
+# to Docker Hub. Tag pushes are handled by docker-publish.yml which
+# does the full multi-arch build-and-push.
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - 'CHANGELOG.md'
+      - 'README.md'
+      - 'DOCKER_HUB.md'
+      - 'deploy/**'
+      - '.gitleaks.toml'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  docs-check:
+    # Fails if DOCKER_HUB.md is out of sync with what generate-dockerhub-md.py
+    # would produce from README.md. Keeps the two docs from drifting.
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check DOCKER_HUB.md is in sync with README.md
+        run: |
+          python3 scripts/generate-dockerhub-md.py --check
+
+  validate-base:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      # The runner's overlay disk starts ~70% full. `load: true` peak disk
+      # is tarball + unpacked image + buildx cache, which tips it over
+      # once the image crosses ~3 GB. Strip catthehacker-resident
+      # toolchains we never use and any stale docker state up front.
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build base image (amd64, load to local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          tags: opencode-devbox:ci-base
+
+      - name: Smoke test
+        run: |
+          bash scripts/smoke-test.sh opencode-devbox:ci-base --variant base
+
+  validate-omos:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build omos image (amd64, load to local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_OMOS=true
+          tags: opencode-devbox:ci-omos
+
+      - name: Smoke test
+        run: |
+          bash scripts/smoke-test.sh opencode-devbox:ci-omos --variant omos
+
+  validate-with-pi:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build with-pi image (amd64, load to local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_PI=true
+          tags: opencode-devbox:ci-with-pi
+
+      - name: Smoke test
+        run: |
+          bash scripts/smoke-test.sh opencode-devbox:ci-with-pi --variant with-pi
+
+  validate-omos-with-pi:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Force IPv4 for Docker Hub
+        run: |
+          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Reclaim runner disk
+        run: |
+          set -x
+          df -h / || true
+          rm -rf \
+            /opt/hostedtoolcache \
+            /opt/microsoft \
+            /opt/az \
+            /opt/ghc \
+            /usr/local/.ghcup \
+            /usr/share/dotnet \
+            /usr/share/swift \
+            /usr/local/lib/android \
+            /usr/local/share/powershell \
+            /usr/local/share/chromium \
+            /usr/local/share/boost \
+            /usr/lib/jvm 2>/dev/null || true
+          apt-get clean || true
+          rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* || true
+          docker system df || true
+          docker system prune -af --volumes || true
+          docker builder prune -af || true
+          df -h / || true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+        with:
+          driver-opts: network=host
+
+      - name: Build omos+with-pi image (amd64, load to local daemon)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          push: false
+          load: true
+          build-args: |
+            INSTALL_OMOS=true
+            INSTALL_PI=true
+          tags: opencode-devbox:ci-omos-with-pi
+
+      - name: Smoke test
+        run: |
+          bash scripts/smoke-test.sh opencode-devbox:ci-omos-with-pi --variant omos-with-pi

.gitignore

@@ -3,3 +3,17 @@
 *.swo
 *~
 .DS_Store
+
+# Docker buildx state (created by 'docker compose build')
+.docker/
+
+# Personal cloud-init overrides (not shared)
+deploy/my-cloud-init.yml
+
+# MemPalace per-project files (issue #185)
+mempalace.yaml
+entities.json
+
+# Python bytecode (from running scripts/ and rootfs/.../*.py locally)
+__pycache__/
+*.pyc

AGENTS.md

@@ -0,0 +1,95 @@
+# AGENTS.md
+
+## Project overview
+
+Docker image packaging [opencode](https://opencode.ai) into a production-ready dev container. Two image variants (base and omos) are published to Docker Hub via Gitea Actions CI. Not a library or application — this is infrastructure (Dockerfile, entrypoint scripts, docker-compose, documentation).
+
+## File roles
+
+- `Dockerfile` — production single-Dockerfile build. Variants are gated by build args: `INSTALL_OMOS` (Bun + multi-agent layer), `INSTALL_OPENCODE` (default true), `INSTALL_PI` (default false), `INSTALL_MEMPALACE` (default true). All GitHub-sourced binaries are pinned with version ARGs.
+- `Dockerfile.base` and `Dockerfile.variant` — **WIP, branch `feat/split-build` only.** Two-Dockerfile split-base build: base contains all variant-independent layers; variant `FROM`s the base and adds only opencode/omos/pi installs. Used by `docker-publish-split.yml` (workflow_dispatch only) for parallel testing alongside the production pipeline. See CHANGELOG `Unreleased` for the migration plan and trade-offs.
+- `entrypoint.sh` — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes (skipped via `.devbox-owner` sentinel when ownership is already correct). Then drops to developer via gosu. Volume ownership loop covers `~/.pi/` when `INSTALL_PI=true`.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.jsonc generation (delegated to `generate-config.py`), pi-toolkit + pi-extensions deploy (when pi installed), pi settings.json bootstrap, mempalace pi-bridge symlink, skillset auto-deploy from mounted skillset repo, OMOS setup.
+- `rootfs/usr/local/lib/opencode-devbox/generate-config.py` — generates `~/.config/opencode/opencode.jsonc` from env vars. Never overwrites an existing config (checks both `.json` and `.jsonc`). Auto-registers MCP servers for detected tools (mempalace via `mempalace-mcp`, gitea-mcp, context7 remote endpoint).
+- `scripts/smoke-test.sh` — post-build image verification. Asserts binary presence, opencode startup, entrypoint correctness, config generation idempotency, and image size thresholds. Used by both CI workflows.
+- `scripts/generate-dockerhub-md.py` — generates `DOCKER_HUB.md` from a hand-maintained `HUB_TEMPLATE` constant. `--check` fails if the committed file is out of sync (enforced by the `validate` workflow).
+- `DOCKER_HUB.md` — **auto-generated** from `HUB_TEMPLATE` in `scripts/generate-dockerhub-md.py`. Do not edit directly. Pushed to Docker Hub description via CI API call. Must stay under 25 kB. Short description field must be ≤100 bytes.
+- `README.md` — authoritative source documentation for everything in this repo. Independent of `DOCKER_HUB.md`: the Hub doc is hand-maintained in the generator's `HUB_TEMPLATE` and intentionally slim, linking back to the gitea README for depth.
+- `.gitea/workflows/validate.yml` — lightweight amd64 build + smoke test on push to main and PRs. Also runs the DOCKER_HUB.md sync check.
+- `.gitea/workflows/docker-publish.yml` — production CI pipeline on tag push: smoke-test each variant on amd64, then full multi-arch (amd64 + arm64) build-and-push, then update Docker Hub description.
+- `.gitea/workflows/docker-publish-split.yml` — **WIP, branch `feat/split-build` only.** Two-phase split-base pipeline. Triggers on `workflow_dispatch` only so it runs alongside the production pipeline without conflict. Pushes to user-supplied `release_tag` input (e.g. `v0.0.0-split-test`); `latest*` aliases only updated when `promote_latest: true`. Compute base hash, conditionally build base, then 4 variant deltas in parallel.
+
+## Versioning scheme
+
+Tags follow `v{opencode_version}[letter]` — e.g. `v1.14.20` for the first build on a new opencode release, and `v1.14.20b`, `v1.14.20c`, … for subsequent rebuilds on the same opencode version.
+
+- The number tracks the opencode npm version (see `OPENCODE_VERSION` ARG in `Dockerfile`).
+- **No letter suffix** on the first build of a new opencode version — the bare `v{opencode_version}` tag is the canonical release.
+- **Letter suffix is the build ordinal**, starting at `b` for the second build. The letter `a` is **never used** — think of the suffix as counting rebuilds: `b = 2nd, c = 3rd, d = 4th, …`. For opencode version `1.14.20`: first build `v1.14.20`, second `v1.14.20b`, third `v1.14.20c`, and so on.
+- A letter suffix is only used for container-level rebuilds — tooling changes, CVE fixes, doc-driven rebuilds, entrypoint bugfixes — that don't change the underlying opencode version.
+
+CI produces eight Docker Hub tags per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`, `vX.Y.Z[n]-with-pi`, `latest-with-pi`, `vX.Y.Z[n]-omos-with-pi`, `latest-omos-with-pi` — one tag pair (versioned + floating alias) per build variant.
+
+When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile` and update the comment in `.env.example` if it names a specific model/version for context.
+
+## Critical conventions
+
+- **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup. The loop writes a `.devbox-owner` sentinel after a successful chown so subsequent starts skip the recursive walk. Users should not touch these files.
+- **Documentation coupling on release** — four docs co-vary and drift in lockstep when not updated together:
+  - `README.md` is the source of truth for user-facing build/run/config detail.
+  - `DOCKER_HUB.md` is auto-generated from `HUB_TEMPLATE` in `scripts/generate-dockerhub-md.py`. CI's `--check` run fails if it's stale. Hub-facing copy is intentionally slim (~5.5 kB, ~78% headroom against the 25 kB Hub limit) — update the template here when image variants, quick-start flow, or the elevator pitch change. README.md no longer feeds into Hub, so README edits do NOT require regenerating DOCKER_HUB.md.
+  - `CHANGELOG.md` records every release. When cutting a tag, **promote `## Unreleased` to `## vX.Y.Z[n] — YYYY-MM-DD` BEFORE pushing the tag** so the tag points at a CHANGELOG that names itself. Keep entries reverse-chronological (newest at top, after the `Unreleased` block). Doc-only updates that happen post-tag (Hub description live-patches, README clarifications) get a fresh `## Unreleased` block with a note that they don't trigger a new image build.
+  - `AGENTS.md` (this file) carries domain facts that change on structural releases — tag-count statements, CI job lists, install contracts. After any change to `.gitea/workflows/*.yml` or the variant matrix, grep this file for stale numbers (`grep -nE "four|eight|all [0-9]"`).
+  - `.env.example` must be hand-updated to match Dockerfile/entrypoint behavior — it is not auto-generated.
+
+  Release-day checklist: README → (regenerate DOCKER_HUB.md only if HUB_TEMPLATE changed) → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag.
+- **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to `latest`. Each build-time install step reads the `/releases/latest` Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major pin), `DEBIAN_VERSION=trixie-slim` (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag.
+- **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`.
+- **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.
+- **MemPalace install path** — installed via `uv tool install` into `/opt/uv-tools/mempalace/`. Both the `mempalace` CLI and the `mempalace-mcp` MCP server binary are shipped as entry points by the mempalace package itself and placed on PATH by uv as shims whose shebangs point at the venv's Python. No hand-rolled wrapper is needed. Do not use `pip install --break-system-packages` — that was the previous approach and has been removed. Do not use `["python3", "-m", "mempalace.mcp_server"]` in `opencode.jsonc` — system Python can't import from the uv venv.
+- **generate-config.py idempotency** — the script MUST never overwrite an existing `opencode.jsonc` or legacy `opencode.json`. Config persists in the `devbox-opencode-config` named volume; accidentally clobbering that file would destroy hand-edits. The smoke test asserts this.
+- **Skillset auto-deploy** — on every container start, `entrypoint-user.sh` looks for a skillset repo (detection order: `$SKILLSET_CONTAINER_PATH` → `$HOME/skillset` → `/workspace/skillset`) and runs `deploy-skills.sh --bootstrap --prune-stale`. This creates relative symlinks in `~/.agents/skills/` and `~/.config/opencode/instructions/`. Do NOT bind-mount `~/.agents/skills/` from the host — the container manages its own skills with relative symlinks that differ from the host's. The named volume `devbox-opencode-config` persists the deployed config across restarts.
+- **Config persistence via named volume** — `devbox-opencode-config` is a Docker named volume mounted at `~/.config/opencode/`. It is NOT a host bind mount by default. This separation allows both native and containerized opencode to coexist on the same machine without symlink conflicts. Users who need to override can replace the named volume with a host bind mount in their compose file. **Same pattern for pi:** `devbox-pi-config` is mounted at `~/.pi/` and persists user toggles (`/ext`-disabled extensions), `~/.pi/agent/settings.json` edits, and — because `NPM_CONFIG_PREFIX` is set to `~/.pi/npm-global` — anything installed via `pi install npm:...` or `npm install -g` as the developer user, across container recreate AND image rebuild.
+- **pi install contract** — `INSTALL_PI=true` (default false) opt-in build arg. The baked `pi` binary is npm-installed globally to `/usr` at build time (system prefix). At runtime, `NPM_CONFIG_PREFIX=/home/developer/.pi/npm-global` is set in the image ENV with that prefix's `bin/` prepended to `PATH` — so any `pi install npm:...` or `npm install -g` invoked by the developer user lands on the named volume and survives everything except `docker compose down -v`. The new ENVs are declared *after* all build-time `npm install -g` calls in the Dockerfile so they don't redirect the baked installs into a path that the volume mount would later shadow. If the user runs `npm install -g @mariozechner/pi-coding-agent` themselves, the user-installed copy on the volume wins via `PATH` order; otherwise image rebuild is the upgrade path for the baked pi (same contract as `OPENCODE_VERSION`). The pi-toolkit and pi-extensions repos are git-cloned into `/opt/` at build time, then their `install.sh` runs from `entrypoint-user.sh` on each container start to symlink into `~/.pi/agent/` (which lives on the named volume). The mempalace pi-bridge is symlinked manually from `/opt/mempalace-toolkit/extensions/pi/mempalace.ts` — we do NOT call mempalace-toolkit's full `install.sh` because its `install_skill` step would race with skillset auto-deploy `--prune-stale`.
+- **Pi deploy ordering matters in entrypoint-user.sh** — `pi-toolkit` runs first (creates `keybindings.json` symlink and writes pi-env.zsh), then `pi-extensions`, then `settings.json` template bootstrap, then mempalace bridge symlink. mempalace-toolkit's `check_pi_toolkit` probe (when called from the host install path) expects keybindings to already be present — not currently called from container, but ordering matches host convention.
+- **Default CMD is `bash -l`** — not a harness. `docker compose run --rm devbox` drops the user into a login shell to choose: `aws sso login`, then `opencode` or `pi` (or any tool). Pass the harness explicitly to launch directly: `docker compose run --rm devbox opencode` / `docker compose run --rm devbox pi`. `docker compose exec` bypasses entrypoint+CMD entirely (existing user workflow unchanged).
+- **Docker Hub description update** — uses `/v2/auth/token` endpoint (not the deprecated `/v2/users/login`). Auth uses `identifier`/`secret` fields, returns `access_token`, sent as `Bearer`. Short description must be ≤100 bytes.
+
+## CI quirks
+
+- Both build jobs include an IPv4 preference step (`gai.conf` + `driver-opts: network=host` for buildx) to work around intermittent IPv6 failures on the Gitea runners.
+- `update-description` job runs only when both builds succeed (`needs: [build-base, build-omos]`).
+- Tags must be pushed to trigger the publish workflow. The validate workflow runs on push to main and PRs.
+- Smoke tests run on amd64 only (single-arch load into the local daemon). The multi-arch push happens after smoke passes.
+- **Gitea Actions runner has ~40 GB disk, often 70%+ used at job start.** All eight `load: true` jobs (`validate-base`, `validate-omos`, `validate-with-pi`, `validate-omos-with-pi`, `smoke-base`, `smoke-omos`, `smoke-with-pi`, `smoke-omos-with-pi`) include a `Reclaim runner disk` step that strips catthehacker-resident toolchains and prunes stale docker state before `setup-buildx-action`. Build jobs use a lighter version (push-by-digest doesn't need `docker system prune`). Don't remove these steps without testing on a fresh runner.
+- **`docker/build-push-action@v7` with `platforms: linux/amd64,linux/arm64` handles multi-arch push natively in a single job** — produces a proper manifest list, no matrix or merge step needed. An earlier revision split into per-arch matrix jobs with digest artifacts, but that pattern requires `actions/{upload,download}-artifact@v4+` which Gitea Actions doesn't support (see below).
+- **`actions/upload-artifact` and `actions/download-artifact` must stay at @v3 on Gitea.** v4+ uses a GitHub-Enterprise-specific Artifact API; runs fail with `GHESNotSupportedError`. If you need artifacts for a new reason (build logs, SBOMs, etc.), pin @v3 explicitly.
+- **Step scripts run under `/bin/sh` (dash), not bash.** Avoid bash-isms like `${VAR//a/b}` parameter-pattern substitution; use POSIX alternatives (`tr`, `sed`) or declare `shell: bash` on the step.
+- **`BUILDKIT_PROGRESS=plain`** is set at workflow level on `docker-publish.yml` so arm64-under-QEMU builds log each layer line-by-line. The default collapsed progress UI hides which step is stalled, which made diagnosing earlier hangs expensive.
+
+## Testing changes
+
+The smoke test (`scripts/smoke-test.sh`) is the canonical check and runs automatically in CI. To run locally:
+
+```bash
+# Base image
+docker compose build
+bash scripts/smoke-test.sh opencode-devbox --variant base
+
+# OMOS image
+docker build --build-arg INSTALL_OMOS=true -t opencode-devbox:omos .
+bash scripts/smoke-test.sh opencode-devbox:omos --variant omos
+```
+
+For manual/exploratory testing:
+1. `docker compose run --rm devbox bash`
+2. Check specific tools inside: `nvim --version`, `bat --version`, `uv --version`, `mempalace --help`, etc.
+3. For entrypoint changes: test with a non-1000 UID workspace to verify UID adjustment, volume ownership fixes, and the `.devbox-owner` sentinel behavior.
+4. For `generate-config.py` changes: run standalone with `HOME=/tmp/fake OPENCODE_PROVIDER=anthropic python3 rootfs/usr/local/lib/opencode-devbox/generate-config.py`.
+
+## Commit style
+
+Imperative mood, first line summarizes the change. Multi-line body explains "why" when non-obvious. Examples from history:
+- `Fix ownership of named volume mount points in entrypoint`
+- `Add uv package manager to base image for on-demand Python support`
+- `Upgrade base image from Debian bookworm to trixie (current stable)`

CHANGELOG.md

@@ -0,0 +1,344 @@
+# Changelog
+
+All notable changes to the opencode-devbox container image.
+
+Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a new opencode release, letter suffix (`b`, `c`, …) for container-level rebuilds on the same version. See [AGENTS.md](AGENTS.md#versioning-scheme) for details.
+
+---
+
+## Unreleased
+
+Docs-only updates that don't trigger a new image build (Docker Hub description was patched live via the API without re-tagging):
+
+- **Docs:** DOCKER_HUB.md `Image Variants` table now lists all four published variants (`latest`, `latest-omos`, `latest-with-pi`, `latest-omos-with-pi`) instead of only the first two. Generator (`scripts/generate-dockerhub-md.py`) HEADER updated to match.
+- **Docs:** DOCKER_HUB.md gains a tailored `pi (alternative/complementary harness)` section covering run, mempalace integration, and persistence — the full README pi section is too large to include verbatim under the 25 kB Hub limit, so a `replace` rule in the generator emits a Hub-tailored excerpt that links out to the gitea README anchor for full build args / extension list / toolkit detail. DOCKER_HUB.md size 24 862 bytes (138 byte headroom).
+- **Docs:** README pi section gains a `### Setup` paragraph mentioning the prebuilt `latest-with-pi` and `latest-omos-with-pi` Docker Hub tags, mirroring the OMOS section's `latest-omos` mention.
+- **Docs:** AGENTS.md tag-scheme paragraph corrected from "four Docker Hub tags per release" to eight (the v1.14.41b CI matrix expansion). Reclaim-disk job list updated from the four pre-pi jobs to all eight current `load: true` jobs.
+
+Image changes (will ship in the next tagged release):
+
+- **Fix:** `pi install npm:<pkg>` (and any `npm install -g`) by the `developer` user no longer EACCES against the system npm prefix. `NPM_CONFIG_PREFIX` is now `/home/developer/.pi/npm-global` and the prefix's `bin/` is prepended to `PATH`. The directory lives on the `devbox-pi-config` named volume, so user-installed pi packages (themes, skills, extensions) survive container recreation and image rebuilds. Build-time `npm install -g` calls (opencode, pi, oh-my-opencode-slim) are unaffected because the new ENVs are declared after those steps in the Dockerfile, so the baked binaries still install to `/usr` and are not shadowed by the volume mount.
+
+Build pipeline (branch `feat/split-build`, not yet merged):
+
+- **New: split-base build pipeline.** `Dockerfile.base` (variant-independent layers — apt, locales, AWS CLI, Node.js, mempalace, gitea-mcp, user setup, chromadb prewarm, ENVs, entrypoints) builds once and is published as `joakimp/opencode-devbox:base-<sha>`. `Dockerfile.variant` `FROM`s that base and adds only opencode/omos/pi installs (or skips them per build-args). Companion workflow `.gitea/workflows/docker-publish-split.yml` runs as a `workflow_dispatch`-only pipeline alongside the existing `docker-publish.yml` so they don't conflict. Hash-driven base reuse: a content hash of `Dockerfile.base + rootfs/ + entrypoint*.sh` becomes the base tag; if the tag already exists on Docker Hub, the base build is skipped entirely. Estimated wall clock: version-bump-only release ~30–40 min (vs ~165–180 min today); base-touching release ~60–70 min. Trade-off: two Dockerfiles to maintain, and `npm install -g` in the variant must override `NPM_CONFIG_PREFIX=/usr` per-RUN to keep baked binaries off the volume-shadowed path. Once 1–2 successful workflow_dispatch runs validate the output against the existing pipeline, the new workflow takes over `on: push: tags: v*` and the original is retired.
+
+Docs-only (the DOCKER_HUB.md change can be patched live to Hub without a CI rebuild; AGENTS.md change is repo-internal):
+
+- **Hub doc rewrite:** `DOCKER_HUB.md` is now generated from a hand-maintained `HUB_TEMPLATE` constant in `scripts/generate-dockerhub-md.py` instead of a section-by-section transformation of `README.md`. Drops from 24 997 bytes (3 byte headroom) to 5 551 bytes (~78% headroom). The old derive-from-README mechanism (`SECTION_RULES`, `TRIM_SUBSECTIONS`, `REPLACEMENTS`, `split_sections`, `trim_subsections`) is gone — README and Hub doc are now independent surfaces. Hub copy stays slim and links out to the gitea README for full depth (build args, multi-user setup, AWS Bedrock walkthrough, MemPalace deep-dive, language-specific dev sections). Trade-off: image-variants table and quick-start flow are now coupled to `HUB_TEMPLATE` and need a manual edit when they change — explicit and local rather than spread across rules.
+- **AGENTS.md:** "Documentation coupling on release" rule updated — README edits no longer require regenerating DOCKER_HUB.md. Release-day checklist tightened.
+- **README pi section:** "What gets installed" sub-section updated to reflect the actual shipped state. Was stale: claimed 6 pi-extensions (actually 7 — mcp-loader was added in pi-extensions commit 141bf64 / 7eec49b / 37cc49e but never propagated here). Each extension now has a one-line description; mcp-loader gets a paragraph covering its dual-transport (local stdio + remote streamable-HTTP per MCP spec 2025-03-26) capability and the `/mcp` slash command. Clarified that the mempalace bridge is a separate MCP entry point that coexists with mcp-loader rather than being replaced by it. Added an explicit note that no MCP servers are baked in beyond mempalace — the loader is opt-in via settings.json edits.
+
+## v1.14.41b — 2026-05-08
+
+**Optional pi as second harness.**
+
+- **Feature:** New `INSTALL_PI=true` build arg installs [pi](https://github.com/mariozechner/pi-coding-agent) as an alternative or complementary harness alongside opencode. Both harnesses share the same mempalace install and palace path — wing/diary entries are mutually visible. Adds ~150 MB to the image. Pi version pinned by `PI_VERSION` (default: latest at build time); `pi update` inside the container does not persist across `--rm` containers — image rebuild is the upgrade path, same contract as `OPENCODE_VERSION`.
+- **Feature:** New `INSTALL_OPENCODE=false` build arg builds an image without opencode (e.g. for pi-only use). Default remains `true`. Existing builds and tags are unaffected.
+- **Feature:** New `devbox-pi-config` named volume mounted at `~/.pi/` persists pi user state (settings.json, `/ext`-disabled extensions) across container recreate. Mirrors the `devbox-opencode-config` pattern from v1.14.33.
+- **Feature:** Container clones [pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit) (keybindings, env loader, settings template) and [pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions) (6 extensions including ext-toggle, todo, ssh-controlmaster, notify, git-checkpoint, confirm-destructive) into `/opt/` at build time. New `PI_TOOLKIT_REF` and `PI_EXTENSIONS_REF` build args (default `main`) pin git refs. The mempalace pi-bridge `mempalace.ts` is symlinked from the existing `/opt/mempalace-toolkit/` clone.
+- **Behavior change:** Default container CMD changed from `["opencode"]` to `["bash", "-l"]`. `docker compose run --rm devbox` (no command) now drops to a login shell so users can pick `opencode` or `pi` (or run `aws sso login` first). To preserve the old behavior, pass the harness explicitly: `docker compose run --rm devbox opencode`. `docker compose exec` workflows are unaffected (they bypass the entrypoint and CMD).
+- **Performance:** chromadb's all-MiniLM-L6-v2 ONNX embedding model (~80 MB) is now pre-warmed at image build time under `~/.cache/chroma/onnx_models/`. Without this, mempalace's `init` step in entrypoint-user.sh would download the model silently on first container start (suppressed via `>/dev/null 2>&1`), stalling startup by minutes on a fresh image. Pre-warming runs as `gosu developer` so the cache lands at the right path and is owned by the runtime user.
+- **Bugfix:** entrypoint-user.sh now redirects stdin from `/dev/null` for the `mempalace init --yes` call. Without this, the interactive `Mine this directory now? [Y/n]` prompt at the end of init would silently block forever when the container was started with `docker run -it` (TTY keeps stdin open). EOF on stdin makes the prompt fall through to its default.
+- **Smoke-test:** New `--variant with-pi` (threshold 2700 MB) and `--variant omos-with-pi` (3400 MB). Pi-specific assertions verify pi binary, pi-toolkit clone, pi-extensions clone, deployed keybindings symlink, extension count ≥ 4, mempalace bridge symlink, and settings.json bootstrap. Pi state assertions use `docker exec` from the host (not `run`-inside-container) since the container has no docker CLI.
+- **CI:** `.gitea/workflows/{validate,docker-publish}.yml` extended with `with-pi` and `omos-with-pi` matrix entries. Each release now produces eight Docker Hub tags: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`, `vX.Y.Z[n]-with-pi`, `latest-with-pi`, `vX.Y.Z[n]-omos-with-pi`, `latest-omos-with-pi`.
+- **Docs:** README adds a "pi (alternative/complementary harness)" section. AGENTS.md codifies pi install contract, deploy ordering in entrypoint-user.sh, and rationale for not calling mempalace-toolkit's full `install.sh` from container.
+
+## v1.14.41 — 2026-05-08
+
+Bump opencode to 1.14.41.
+
+- **v1.14.41 (upstream):** restored formatter output handling for stdout/stderr writes; warping a session to another workspace can now carry over uncommitted file changes; restored custom provider setup in `/connect`; macOS Settings menu entry added; desktop local server split into a separate utility process; ACP clients restore last model/mode/effort when loading sessions and can close sessions cleanly.
+
+No container-level changes in this release. Dockerfile bump only.
+
+## v1.14.40 — 2026-05-07
+
+Bump opencode to 1.14.40.
+
+Rolls up upstream releases v1.14.34 → v1.14.40 (no v1.14.36). Highlights:
+
+- **v1.14.40:** support `.well-known/opencode` configs that point to a separate remote config file; assistant text preserved in signed reasoning blocks; CORS, network options, web terminal, and Cloudflare AI Gateway provider fixes; Mistral Medium 3.5 variants restored.
+- **v1.14.39:** desktop app respects `HTTP_PROXY` and friends; storage reads return `null` instead of failing when keys are missing.
+- **v1.14.38:** embedded UI requests work with arbitrary `connect-src` origins under the default CSP; desktop trusts system CA certificates for HTTPS.
+- **v1.14.37:** cancelling a task now cancels child subtask sessions; v2 session rendering improvements (cleaner tool states, better compaction summaries); new "warp a session into another workspace or back to local project" feature; Windows titlebar stable across zoom changes.
+- **v1.14.35:** preserve diff patch boundaries so session diffs render correctly when file contents themselves contain `diff --git` text.
+- **v1.14.34:** PTY connection tickets for authenticated terminal websockets; v2 session failure events for clients to detect failed runs; improved shell command handling for Bash/PowerShell/cmd; new `debug info` command; `--username` option for basic-auth server connections.
+
+No container-level changes in this release. Dockerfile bump only.
+
+## v1.14.33 — 2026-05-03
+
+**Bump opencode to 1.14.33. Named volume for opencode config, skillset auto-deploy, Context7 MCP.**
+
+Rolls up the image-structure changes originally planned for v1.14.32b onto the current opencode release. v1.14.32 was built but never deployed (wrong deploy dir caught the tag mid-flight); skipped in favor of landing everything together on 1.14.33.
+
+- **Breaking:** `~/.config/opencode/` now uses a named volume (`devbox-opencode-config`) instead of a host bind mount. The container's config, skills, and instructions are independent from the host. Users who relied on the bind mount should either re-add it explicitly in their compose file (overriding the volume) or migrate hand-edits into the container.
+- **Breaking:** `~/.agents/skills/` is no longer bind-mounted from the host. The container manages its own skills directory — the entrypoint deploys skills from the skillset repo on each start.
+- **Feature:** Skillset auto-deploy on container start. The entrypoint runs `deploy-skills.sh --bootstrap --prune-stale` from the first skillset repo found at: `$SKILLSET_CONTAINER_PATH` → `~/skillset` → `/workspace/skillset`. Creates relative symlinks that resolve inside the container regardless of host path layout. Idempotent.
+- **Feature:** Context7 remote MCP server registered in auto-generated config. No local binary; provides up-to-date library documentation to LLMs. Config file is now `opencode.jsonc` (supports comments) with a note about the optional API key for higher rate limits. Existing-config check detects both `.json` and `.jsonc`.
+- **Env:** New `SKILLSET_CONTAINER_PATH` env var for specifying skillset repo location inside the container when it's not at `/workspace/skillset`.
+- **Docs:** README updated for named volume config, skillset auto-deploy, Context7 MCP server, `opencode.jsonc` references. AGENTS.md, DOCKER_HUB.md regenerated.
+
+Upstream opencode 1.14.32 notes (shipped in this build since v1.14.32 was skipped): shell-mode input in the prompt is editable again (backspace, cursor keys); HTTP API workspace adapters no longer lose instance context, restoring workspace create/sync/routing; experimental workspace creation requests that omit `extra` are fixed; OpenAPI parameter schemas now match the public API so generated clients stop drifting; unsupported image formats fall back to text reads instead of being sent as image attachments; agents can use the global temp directory without extra permission prompts; Bedrock sessions that include reasoning content no longer break when switching models; session archive timestamps reject non-finite values to avoid invalid JSON. TUI: reduced startup theme flashing under the system theme, animated logo avoids subpixel rendering on terminals without truecolor support.
+
+Upstream opencode 1.14.33 release notes: see https://github.com/sst/opencode/releases/tag/v1.14.33.
+
+## v1.14.31d — 2026-05-01
+
+**CI: collapse per-arch matrix back into single multi-arch push jobs.**
+
+- **Fix:** `v1.14.31c`'s per-arch matrix build jobs failed on `Upload digest` with `GHESNotSupportedError: @actions/artifact v2.0.0+, upload-artifact@v4+ and download-artifact@v4+ are not currently supported on GHES`. Gitea Actions only implements the v3-compatible artifact API; `@v4` uses a GitHub-Enterprise-specific backend. Separately, `build-omos linux/arm64` hung silently for 12 minutes in "Set-up job" and then failed with no log output — likely catthehacker image-pull contention between concurrent matrix children on the same runner host.
+  - Rather than downgrade to `actions/{upload,download}-artifact@v3`, collapsed the per-arch matrix entirely. `docker/build-push-action@v7` with `platforms: linux/amd64,linux/arm64` publishes a proper multi-arch manifest in a single job, so the whole artifact-passing and `imagetools create` merge dance existed only to support a matrix split we no longer need.
+  - The original matrix split was designed around `load: true` disk exhaustion (v1.14.30b). With `push-by-digest`/`push: true` streaming straight to the registry — no local unpack — the peak disk story is fundamentally different. Validated in v1.14.31b that the reclaim step gives sufficient headroom for a single-job amd64 build; oracle-reviewed call that this should extend to the combined amd64+arm64 push case.
+  - Workflow goes from 7 jobs to 5 (smoke-base, smoke-omos, build-base, build-omos, update-description). 263 → ~110 lines of YAML in `docker-publish.yml`.
+- **Add:** `timeout-minutes: 90` on both build jobs so a hung arm64 build produces an explicit failure with logs rather than runner-default silent truncation.
+- **Add:** `BUILDKIT_PROGRESS=plain` at workflow level so arm64-under-QEMU build output is line-by-line (the default collapsed progress UI was obscuring earlier stalls).
+- **Add:** `AGENTS.md §CI quirks` documents the Gitea-specific traps encountered this week: `upload-artifact@v3`-only on Gitea, `/bin/sh` is dash, `build-push-action@v7` does multi-arch natively with comma-separated platforms, reclaim step is mandatory on `load: true` jobs.
+- No image changes. Rebuild of v1.14.31 content only.
+
+## v1.14.31c — 2026-05-01
+
+**CI: fix bash-specific parameter expansion and bump omos size threshold.**
+
+- **Fix:** `Derive platform slug` step in the per-arch matrix build jobs (`build-base`, `build-omos`) used `${PLATFORM_PAIR//\//-}` which is a bash parameter-expansion. The runner container executes step scripts via `/bin/sh` (dash), which errored with `Bad substitution`. Rewrote using `tr / -` which is POSIX and behaves identically. Both `build-base` and `build-omos` matrix jobs were blocked on this on `v1.14.31b`.
+- **Fix:** smoke-test image-size threshold for the `omos` variant bumped from 3000 MB to 3200 MB. The mempalace-toolkit bake-in added ~100 MB to omos; measured 3107 MB on `v1.14.31b`. All functional smoke checks (opencode, node, mempalace CLIs, toolkit wrappers, oh-my-opencode-slim) pass — this is a guardrail recalibration, not a performance concession. The underlying image genuinely grew.
+- The runner-disk reclaim step from v1.14.31b did its job: `smoke-base` and `validate-base` now pass cleanly. Only `smoke-omos` was blocked this iteration, and only on the threshold.
+- No image changes beyond what shipped in v1.14.31. Rebuild of v1.14.31 content only.
+
+## v1.14.31b — 2026-05-01
+
+**CI: reclaim runner disk before `load: true` smoke builds.**
+
+- **Fix:** v1.14.31's publish workflow and the `validate` workflow both hit `No space left on device` on the single-arch amd64 smoke/validate builds (`/opt/uv-tools/mempalace/lib/python3.13/site-packages/hf_xet/hf_xet.abi3.so`, `/usr/local/bin/git-lfs`). Root cause is not the build itself but the `load: true` step: peak disk during export equals tarball + unpacked image + buildx cache, and the image has crossed the ~3 GB threshold where this no longer fits in the ~12 GB of free space the runner container starts with. The v1.14.30c refactor split multi-arch into per-arch push-by-digest jobs (which don't `load`), but the smoke gates still do and still hit the wall.
+  - Added a `Reclaim runner disk` step to all four `load: true` jobs (`validate-base`, `validate-omos`, `smoke-base`, `smoke-omos`). The step strips `catthehacker/ubuntu:act-latest`-resident toolchains we never use (hosted-tool-cache, dotnet, android, powershell, swift, ghc, jvm, microsoft, chromium, boost) and runs `docker system prune -af --volumes` + `docker builder prune -af` against the runner's dockerd before `setup-buildx-action`. Expected reclaim is 6–12 GB depending on what's resident.
+  - Added workflow-level `concurrency: { group: ..., cancel-in-progress: false }` on `docker-publish.yml` so concurrent tag pushes can't race `docker system prune` in one job against an in-flight buildx cache in another.
+  - Pruning is deliberately kept out of the per-arch matrix push-by-digest jobs (`build-base`/`build-omos`) — those don't need it (no `load: true`), and pruning in parallel jobs risks one job nuking another's cache.
+- **Follow-up** (not in this release): image-size reduction via a dedicated `uv tool install mempalace` build stage (strips uv's cache from the final image), pinning `mempalace-toolkit` to a commit SHA with `--depth=1 --filter=blob:none`, and auditing whether `hf_xet` is actually required by mempalace at runtime. These will ship in the next release that rebases on a new opencode version.
+- No image changes. Rebuild of v1.14.31 content only.
+
+## v1.14.31 — 2026-05-01
+
+Bump opencode to 1.14.31.
+
+**CI infrastructure: split multi-arch publish across separate runners.**
+
+- **Fix:** The `publish` workflow exhausted runner disk space on `v1.14.30b` and would have hit the same wall on any subsequent release. Both variants built both architectures on a single `catthehacker/ubuntu:act-latest` container with ~40 GB of shared overlay space, and the peak disk footprint during the nodejs dpkg unpack / git-lfs layer export pushed it over the edge (`No space left on device`). The mempalace-toolkit bake-in from v1.14.30b added the final straw; the underlying issue is that QEMU-emulated arm64 layers were stored alongside the amd64 build on the same runner.
+  - `docker-publish.yml` refactored to the canonical `push-by-digest` + manifest-merge pattern: smoke test (amd64) runs on its own runner, each `(variant × arch)` push target runs on its own fresh runner with `outputs: type=image,...,push-by-digest=true,push=true` (no local image store), then a tiny merge job assembles the multi-arch manifest with `docker buildx imagetools create` from digest artifacts.
+  - Per-runner disk peak is now roughly one-quarter of the old single-job peak. The four Docker Hub tags produced per release (`vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`) are unchanged.
+  - Also parallelizes the amd64 and arm64 builds, so wall-clock time for a release should drop noticeably despite the added merge hop.
+
+## v1.14.30b — 2026-04-30
+
+**Bake mempalace-toolkit wrappers into the image.**
+
+- **Fix:** The scheduler templates in [mempalace-toolkit's `contrib/`](https://gitea.jordbo.se/joakimp/mempalace-toolkit/src/branch/main/contrib) assume `mempalace-session` is available inside the container, but the image never actually installed it. Users following the `*-devbox` scheduler docs would silently lose the wrappers on every `docker compose up --force-recreate`, because the only way to get them was a post-hoc `./install.sh --yes` inside the container — which lives in the ephemeral layer. The host-side systemd timer would then fire, `docker exec` in, and hit `mempalace-session: command not found`. Caught during runtime validation on 2026-04-30.
+  - New Dockerfile block clones `mempalace-toolkit` at build time (depth-1) to `/opt/mempalace-toolkit/`, symlinks `bin/mempalace-session` and `bin/mempalace-docs` into `/usr/local/bin/`, and asserts both respond to `--help` before the layer succeeds.
+  - Gated by `ARG INSTALL_MEMPALACE_TOOLKIT=true` (defaults on, depends on `INSTALL_MEMPALACE=true`).
+  - Floated ref via `ARG MEMPALACE_TOOLKIT_REF=main` — override for reproducible builds once the toolkit starts tagging releases.
+- **Tests:** Smoke test gains three toolkit assertions (`mempalace-session --help`, `mempalace-docs --help`, symlink target check). The resolved-versions preamble now logs the toolkit git short-SHA alongside the other floated components.
+- **Docs:** README's MemPalace section gains a `Scheduled mining (mempalace-toolkit)` subsection covering the new wrappers and pointing at `contrib/` for scheduling. New build-args table entry for `INSTALL_MEMPALACE_TOOLKIT`.
+
+## v1.14.30 — 2026-04-30
+
+Bump opencode to 1.14.30.
+
+## v1.14.29c — 2026-04-29
+
+**Drop redundant mempalace-mcp-server wrapper, use the entry point mempalace ships.**
+
+- **Fix:** MCP integration with mempalace was still broken for users with custom `opencode.json` files because they typically had `["python3", "-m", "mempalace.mcp_server"]` from v1.14.28b and earlier. With the uv-tool install path, system python3 can't import mempalace and the MCP server subprocess exits immediately — opencode surfaced this as `MCP error -32000: connection closed`. Users should migrate to `["mempalace-mcp"]`. The auto-generated config in new containers already emits the new form.
+- **Cleanup:** Remove the hand-rolled `/usr/local/bin/mempalace-mcp-server` wrapper. The mempalace Python package ships a `mempalace-mcp` console entry point; `uv tool install` places it on PATH as a shim whose shebang points at the isolated venv's Python. The wrapper was duplicating what uv installs for free. Removed `rootfs/usr/local/bin/` and its COPY + chmod lines from the Dockerfile.
+- **Docs:** README's MemPalace section now shows `["mempalace-mcp"]` and explicitly warns against `["python3", "-m", "mempalace.mcp_server"]` with the observed failure mode.
+- **Tests:** Smoke test asserts `/usr/local/bin/mempalace-mcp` is executable and prints its symlink target, replacing the previous wrapper-present check.
+
+## v1.14.29b — 2026-04-29
+
+**Fix OMOS `bunx` detection + CI build reliability.**
+
+- **Fix:** `entrypoint-user.sh` checked `command -v bunx` to gate the OMOS auto-install, but the OMOS image only ships the `bun` binary — upstream's bun installer never creates a `bunx` symlink and neither did our Dockerfile. The check always failed on a fresh OMOS image, so `bun x oh-my-opencode-slim@latest install` never ran and first-start OMOS setup would have printed `ENABLE_OMOS=true but bun is not installed.` even though bun was right there. Latent until now because the only exercised path had a persisted `oh-my-opencode-slim.json` from a prior install.
+  - Changed the gate to `command -v bun`.
+  - Changed both install invocations from `bunx oh-my-opencode-slim@latest install ...` to `bun x oh-my-opencode-slim@latest install ...`.
+  - Added `ln -sf bun /usr/local/bin/bunx` to the Dockerfile's OMOS block so interactive users can still type `bunx` by habit, and verified the symlink at build time (`test -L /usr/local/bin/bunx`).
+  - Smoke test now asserts the `bunx` symlink is present on the OMOS variant.
+- **Fix:** CI build robustness against transient GitHub/Gitea CDN failures. The first attempt at building v1.14.29b tripped on a single HTTP 502 from GitHub's release CDN mid-download (`zoxide-0.9.9-x86_64-unknown-linux-musl.tar.gz`), failing the entire OMOS build with no retry. Fix applied to every tool-download curl in the Dockerfile:
+  - `curl --retry 5 --retry-delay 5 --retry-all-errors` on both the `-fsSL` GET requests and the `-sI` HEAD requests used for `/releases/latest` redirect resolution. 5 attempts with 5 s back-off eats most transient CDN hiccups without failing the build.
+  - Added `[ -n "$V" ]` assertion after each version-resolution step. If the HEAD redirect ever fails to produce a tag name, the build fails fast with an empty-version message rather than trying to download `.../v//...` and producing a confusing 404.
+  - Same hardening applied to the optional Go install block (go.dev JSON feed + tarball download) and the nodesource apt-repo setup script.
+- **Security:** Added `apt-get upgrade -y` to the core-packages RUN step. Picks up any security/CVE fixes published between `debian:trixie-slim` base-image rebuilds. Paired with the existing `update` and `install` in the same layer so image history isn't bloated. Today this produced `0 upgraded` (base image is current), but it future-proofs against the next CVE drop.
+
+## v1.14.29 — 2026-04-28
+
+**Opencode 1.14.29 + infrastructure and maintainability pass.**
+
+- Bump opencode to 1.14.29.
+- **Cleanup:** Remove dead `INSTALL_PYTHON` build arg. Python 3 + pip + venv have been unconditionally installed in the base layer since mempalace was added; the flag was a no-op. Users should use `uv` (pre-installed) or `uvx` for Python tooling.
+- **Fix:** `mempalace init` in `entrypoint-user.sh` now uses `--yes` for non-interactive operation. Previously the command prompted the user (`Your choice [enter/edit/add]:`) on first container start, which either hung or printed prompts into the user's terminal. The init is still gated by `[ ! -d "$PALACE_DIR/palace" ]` so existing palace data from prior versions is preserved untouched on upgrade.
+- **Feature:** MemPalace is now installed via `uv tool install` into an isolated venv at `/opt/uv-tools/mempalace/`, reached through a new `/usr/local/bin/mempalace-mcp-server` wrapper. Replaces the previous `pip install --break-system-packages` approach — removes the PEP 668 workaround and keeps mempalace deps out of system Python site-packages. The wrapper is what `generate-config.py` now references in the auto-generated `opencode.json`. Users with custom `opencode.json` files should update their mempalace MCP command from `["python3", "-m", "mempalace.mcp_server"]` to `["mempalace-mcp-server"]`.
+- **Feature:** New `INSTALL_MEMPALACE` build arg (default `true`). Rebuild with `--build-arg INSTALL_MEMPALACE=false` to shave ~300 MB off the image when local AI memory isn't needed.
+- **Refactor:** `opencode.json` generation extracted from `entrypoint-user.sh` into a standalone Python script at `/usr/local/lib/opencode-devbox/generate-config.py`. Easier to read, test, and extend with new providers. Default models are declared at the top of the script rather than hard-coded in bash heredocs. Reduces `entrypoint-user.sh` from 176 to 97 lines. Behavior is unchanged — the script preserves the critical guarantee of never overwriting an existing `opencode.json`.
+- **Perf:** Container startup avoids the recursive `chown -R` on named volumes that already have correct ownership. A `.devbox-owner` sentinel file written after a successful chown lets subsequent starts short-circuit via a single `cat`. On volumes with thousands of files (nvim plugins, palace data) this cuts multi-second startup costs to milliseconds. If `USER_UID` changes between runs, the sentinel mismatches and the full chown still runs.
+- **CI:** New `validate` workflow runs on every push to main and PR — single-arch amd64 build, smoke test, and DOCKER_HUB.md sync check. Catches broken Dockerfile changes without waiting for a tag push.
+- **CI:** `docker-publish.yml` now smoke-tests each variant on amd64 before the full multi-arch push. A failing smoke test blocks the release.
+- **CI:** Image size is tracked and fails the build if it exceeds thresholds (base: 2500 MB uncompressed, OMOS: 3000 MB). Makes bloat visible rather than silent.
+- **Docs:** `DOCKER_HUB.md` is now auto-generated from `README.md` via `scripts/generate-dockerhub-md.py`. Editing it directly is a mistake — the `--check` step in CI fails if the committed file is out of sync. Section inclusion is controlled by explicit rules (`SECTION_RULES`, `TRIM_SUBSECTIONS`); adding a new section to README forces an explicit keep/drop/replace decision. Keeps the 25 kB Docker Hub limit in sight and eliminates manual sync burden.
+- **Tests:** New `scripts/smoke-test.sh` asserts: (a) all core binaries are runnable and print a version, (b) opencode starts, (c) entrypoint correctly drops to the developer user, (d) `generate-config.py` produces valid JSON with the expected shape, (e) `generate-config.py` never overwrites an existing config, (f) bun is present only in the OMOS variant, (g) image size is under threshold. The smoke test also logs resolved versions of every component as its first step so CI output always records what got baked in.
+- **Versioning:** All GitHub/Gitea-hosted binaries (gosu, fzf, git-lfs, neovim, bat, eza, zoxide, uv, gitea-mcp) and the go.dev-hosted Go toolchain now default to `latest` at build time. Each `*_VERSION` ARG resolves the newest upstream release by reading the `/releases/latest` Location redirect (or the go.dev JSON feed). Previously these were hand-pinned to a specific version, which meant rebuilds didn't pick up upstream CVE fixes until someone remembered to bump the pin. Pinning is still supported — pass `--build-arg NVIM_VERSION=0.12.1` etc. to lock a specific version. Intentionally still pinned: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major only), `DEBIAN_VERSION=trixie-slim` (OS base).
+
+## v1.14.28b — 2026-04-27
+
+- **Feature:** Add MemPalace local-first AI memory system to base image. Provides 29 MCP tools for semantic search over conversation history, knowledge graph queries, and agent diaries. Palace data persists via optional `devbox-palace` named volume, ChromaDB embedding model cache via `devbox-chroma-cache`. No API keys required.
+- **Feature:** Auto-register mempalace MCP server in generated opencode.json (when mempalace is installed and config is auto-generated from OPENCODE_PROVIDER).
+- **Feature:** Add official Gitea MCP server (`gitea-mcp`) to base image. Provides 50+ MCP tools for Gitea API (repos, issues, PRs, releases, Actions). Disabled by default — requires `GITEA_ACCESS_TOKEN` and `GITEA_HOST` env vars.
+
+## v1.14.28 — 2026-04-26
+
+Bump opencode to 1.14.28.
+
+## v1.14.25 — 2026-04-25
+
+Bump opencode to 1.14.25. Also includes container-level changes since v1.14.22b:
+- Add `python3-pip` and `python3-venv` to base image (fixes Mason LSP installs).
+- Add `devbox-nvim-data` named volume for neovim plugin/Mason persistence.
+- Add `devbox-zoxide` named volume for zoxide directory history persistence.
+- Bake devbox-shell bridge line into `/etc/skel-devbox/.bash_aliases`.
+- Add CHANGELOG.md with full release history.
+
+## v1.14.22b — 2026-04-23
+
+**Fix Mason LSP installs, persist nvim data, devbox-shell bridge.**
+
+- **Fix:** Add `python3-pip` and `python3-venv` to base image. Mason creates a Python venv per LSP package and pip-installs into it; Debian trixie ships python3 without ensurepip, so venv creation failed and every Mason Python package (ruff, ansible-lint) errored on every nvim start.
+- **Feature:** Add `devbox-nvim-data` named volume at `~/.local/share/nvim` — Lazy plugin cache and Mason LSP installs now persist across `--force-recreate`.
+- **Feature:** Add `devbox-zoxide` named volume at `~/.local/share/zoxide` — zoxide directory history persists across recreates.
+- **Feature:** Bake the devbox-shell bridge line into `/etc/skel-devbox/.bash_aliases` — hosts using the `~/.config/devbox-shell/` directory-mount pattern get automatic sourcing without manual setup after recreate.
+
+## v1.14.22 — 2026-04-23
+
+Bump opencode to 1.14.22.
+
+## v1.14.21 — 2026-04-23
+
+**Opencode 1.14.21 + zoxide persistence + multi-user fixes.**
+
+- Bump opencode to 1.14.21.
+- Fix single-file bind-mount caveat: document the kernel-level inode issue (affects all platforms, not just Docker Desktop).
+- Pin project name in default `docker-compose.yml` — directory renames no longer orphan named volumes.
+- Fix volume collision in shared-machine compose: scope project name by `SIGNUM`.
+- Auto-detect OS username (`$USER`) for volume isolation in own-account mode.
+- Document the upgrade ritual for reconciling VM compose files.
+- Add multi-user setup pointer in DOCKER_HUB.md.
+
+## v1.14.20b — 2026-04-21
+
+**Fix `[devbox]` prompt marker lost on `exec bash`.**
+
+- The PS1 prefix guard used an exported env var that survived `exec bash`, but PS1 itself doesn't — so the new shell skipped adding the prefix. Replaced with a substring check on PS1 itself.
+- Clarify tag-letter convention in AGENTS.md: suffix is the build ordinal, `a` is never used.
+
+## v1.14.20 — 2026-04-21
+
+**Opencode 1.14.20 + PROMPT_COMMAND/zoxide fix.**
+
+- Bump opencode to 1.14.20.
+- Fix `PROMPT_COMMAND` collision with zoxide: `history -a;` followed by zoxide's `;__zoxide_hook` produced `;;` which bash rejected on every prompt. Moved history-flush after zoxide init, using newline separator.
+- Includes all v1.14.19c shell-defaults work (baked `.bash_aliases`/`.inputrc` via `/etc/skel-devbox/`, skel-copy on first run, `devbox-shell-history` named volume).
+
+## v1.14.19d — 2026-04-21
+
+*Superseded by v1.14.20 before building. Tagged but never built.*
+
+## v1.14.19c — 2026-04-21
+
+**Bash history persistence, shell defaults, GID auto-detect.**
+
+- **Feature:** Bash history persists across `--force-recreate` via `devbox-shell-history` named volume at `~/.cache/bash`.
+- **Feature:** Quality-of-life shell defaults shipped in `/etc/skel-devbox/` and copied to `~/` only if absent: prefix history search on Up/Down, 100k-entry timestamped dedup history, coloured case-insensitive tab completion, eza/bat aliases, zoxide/fzf integrations, `[devbox]` prompt marker.
+- **Feature:** Skel-copy pattern — host bind-mounts and in-container customizations are never overwritten on upgrade.
+- **Fix:** Entrypoint now detects workspace UID and GID independently. Hosts with UID 1000 but non-1000 GID (e.g. Debian's `useradd` default GID 1001) get correct group remapping.
+- **Docs:** SSH banner-timeout troubleshooting (CGNAT), shell defaults section, skel restore/diff commands.
+
+## v1.14.19b — 2026-04-20
+
+**Ownership fixes and config/docs refresh.**
+
+- **Fix:** Root-owned parent dirs left behind by nested named-volume mounts. Entrypoint now chowns `.local`, `.local/share`, `.local/state`, `.config` before leaf mount points.
+- **Fix:** `deploy/sync-to-vm.sh` no longer preserves host GIDs (`rsync -a` → `-rlptDz`).
+- Default model IDs refreshed (claude-sonnet-4-6, gpt-5.4, global Bedrock inference profile).
+- Documentation gates oh-my-opencode-slim references to the OMOS variant.
+
+## v1.14.19 — 2026-04-20
+
+Bump opencode to 1.14.19.
+
+## v1.14.18 — 2026-04-19
+
+Fix Bun download URL: remove non-existent LATEST file fetch.
+
+## v1.4.17 — 2026-04-19
+
+Bump opencode to v1.4.17, add `file` utility to base image.
+
+## v1.4.12 — 2026-04-18
+
+Bump opencode to v1.4.12.
+
+## v1.4.11 — 2026-04-18
+
+Bump opencode to v1.4.11.
+
+## v1.4.7 — 2026-04-17
+
+Bump opencode to v1.4.7.
+
+## v1.4.6 — 2026-04-15
+
+Bump opencode to v1.4.6.
+
+## v1.4.3k — 2026-04-13
+
+Fix Bedrock config: add `AWS_PROFILE` to generated config, add `.agents/skills` to volume ownership fix.
+
+## v1.4.3j — 2026-04-13
+
+Upgrade base image from Debian bookworm to trixie (current stable). Bookworm EOL June 2026; trixie supported until 2028/LTS 2030.
+
+## v1.4.3i — 2026-04-12
+
+Add rustup for on-demand Rust support, document JS/TS development.
+
+## v1.4.3h — 2026-04-12
+
+Add uv package manager to base image for on-demand Python support.
+
+## v1.4.3g — 2026-04-12
+
+Fix IPv6 connectivity failures: force IPv4 preference in CI builds.
+
+## v1.4.3f — 2026-04-11
+
+Add error handling to Docker Hub description update step.
+
+## v1.4.3e — 2026-04-10
+
+Fix CVEs: install git-lfs from GitHub (Go 1.25), document Go versions for gosu/fzf.
+
+## v1.4.3d — 2026-04-10
+
+Fix CVEs: install gosu 1.19 and fzf 0.71.0 from GitHub releases instead of Debian packages.
+
+## v1.4.3c — 2026-04-10
+
+Fix CVEs: install gosu from GitHub release instead of Debian package (Go 1.19.8 → current).
+
+## v1.4.3b — 2026-04-10
+
+Fix entrypoint crash on read-only SSH mount.
+
+## v1.4.3 — 2026-04-10
+
+Bump opencode to 1.4.3.
+
+## v1.4.2 — 2026-04-10
+
+Initial release. Fix CI: use vars for username, secrets for token.

DOCKER_HUB.md

@@ -1,17 +1,19 @@
-# opencode-devbox — Docker Hub
+# opencode-devbox
 
 Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.
 
-## Image Variants
+Designed for teams who want a reproducible coding-agent setup that runs the same on every laptop and CI runner — without forcing each developer to install Bun, Node, AWS CLI, mempalace, or maintain shell config drift across machines.
 
-Two image variants are published for each release:
+## Image Variants
 
 | Tag | Description |
 |---|---|
 | `latest` / `vX.Y.Z` | Base image — opencode, Node.js, AWS CLI, dev tools |
-| `latest-omos` / `vX.Y.Z-omos` | Base + [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration, Bun, and tmux |
+| `latest-omos` / `vX.Y.Z-omos` | Base + [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration and Bun |
+| `latest-with-pi` / `vX.Y.Z-with-pi` | Base + [pi](https://github.com/mariozechner/pi-coding-agent) as alternative/complementary harness (shares the mempalace install with opencode) |
+| `latest-omos-with-pi` / `vX.Y.Z-omos-with-pi` | OMOS + pi together |
 
-Both variants support `linux/amd64` and `linux/arm64`.
+All variants support `linux/amd64` and `linux/arm64`.
 
 ## Quick Start
 
@@ -26,11 +28,9 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest
 ```
 
-This drops you straight into opencode with your project mounted at `/workspace`.
+Drops you straight into opencode with your project mounted at `/workspace`.
 
-## Interactive Shell
-
-To get a shell first (useful for AWS SSO login or running other commands):
+For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
 
 ```bash
 docker run -it --rm \
@@ -41,322 +41,55 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest bash
 ```
 
-Then run `opencode` when ready.
+Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
 
-## Running Multiple Shells
+For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
 
-Once opencode is running it takes over the terminal. To have a separate shell for `aws`, `git`, or other commands, run the container in the background and attach multiple times:
+## What's Inside
 
-```bash
-# Start in background
-docker run -d --name devbox \
-  -e ANTHROPIC_API_KEY=your-key \
-  -e OPENCODE_PROVIDER=anthropic \
-  -v ~/projects:/workspace \
-  -v ~/.ssh:/home/developer/.ssh:ro \
-  joakimp/opencode-devbox:latest sleep infinity
+- **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
+- **[pi](https://github.com/mariozechner/pi-coding-agent)** *(in `*-with-pi` variants)* — lightweight TUI coding-agent that coexists with opencode and shares the same mempalace install. Includes the `mcp-loader` extension so any local-stdio or remote streamable-HTTP MCP server (searxng, gitea, context7, …) can be added by editing `~/.pi/agent/settings.json`.
+- **[mempalace](https://github.com/MemPalace/mempalace)** — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi.
+- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** *(in `*-omos` variants)* — multi-agent orchestration on top of opencode (council, fallback chains, named agents).
+- **AWS CLI v2** with SSO support, **Node.js LTS**, **Bun** (OMOS variants), **uv** (Python), **gosu** for clean UID/GID adjustment to match your host workspace.
+- **MCP wrappers** for mempalace pre-installed and pre-wired to both harnesses.
 
-# Shell 1: run opencode
-docker exec -it -u developer devbox opencode
+## Authentication
 
-# Shell 2 (separate terminal): aws, git, etc.
-docker exec -it -u developer devbox bash
+The container reads provider credentials from environment variables and host-mounted config:
 
-# When done
-docker rm -f devbox
-```
+- **Anthropic / OpenAI / Groq / others:** set `OPENCODE_PROVIDER` and the corresponding `*_API_KEY` via `-e` or `.env`.
+- **AWS Bedrock (SSO):** mount `~/.aws` from the host, `OPENCODE_PROVIDER=amazon-bedrock`, then `aws sso login` inside the container. Tokens persist across container restarts via the host bind-mount.
+- **OAuth / device-code providers:** auth state lives in opencode's config, which is persisted via the `devbox-opencode-config` named volume.
 
-> **Note:** Always use `-u developer` with `docker exec` — the container starts as root for UID adjustment, then drops to `developer`. Without `-u developer`, exec runs as root.
+Full Bedrock walkthrough (IAM roles, permissions, multi-account setups): see the [AWS Bedrock Authentication](
+https://gitea.jordbo.se/joakimp/opencode-devbox#aws-bedrock-authentication
+) section on gitea.
 
-## Environment Variables
+## Persistence
 
-All configuration is done via environment variables, typically stored in a `.env` file.
-
-### Provider Configuration
-
-| Variable | Description | Default |
+| Volume | Mount | Survives |
 |---|---|---|
-| `OPENCODE_PROVIDER` | LLM provider (`anthropic`, `openai`, `amazon-bedrock`) | `anthropic` |
-| `OPENCODE_MODEL` | Model override | Provider default |
+| `devbox-opencode-config` | `~/.config/opencode` | container recreate, image rebuild |
+| `devbox-pi-config` | `~/.pi` | container recreate, image rebuild — incl. user-installed pi packages via `pi install` (`NPM_CONFIG_PREFIX` points into the volume) |
+| `devbox-palace` (uncomment) | `~/.mempalace` | container recreate, image rebuild — palace data is precious, treat as primary storage |
+| `devbox-chroma-cache` | `~/.cache/chroma` | container recreate (model cache, disposable — re-downloads in seconds) |
 
-### API Keys
+Workspace bind-mount (`/workspace`) is your project directory on the host, so source code is never inside the container.
 
-Set the key matching your provider:
+Full persistence reference, including multi-user (`SIGNUM`) isolation and host bind-mount alternatives: see the [README on gitea](https://gitea.jordbo.se/joakimp/opencode-devbox#persistence).
 
-| Variable | Provider |
-|---|---|
-| `ANTHROPIC_API_KEY` | Anthropic |
-| `OPENAI_API_KEY` | OpenAI |
-| `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (static creds) |
+## Where to Go Next
 
-### AWS Bedrock
+- **Full README** with build args, every feature in detail, troubleshooting: <https://gitea.jordbo.se/joakimp/opencode-devbox>
+- **CHANGELOG** for version history: <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/CHANGELOG.md>
+- **Issues / source / docker-compose templates:** <https://gitea.jordbo.se/joakimp/opencode-devbox>
+- **Agent-facing internals** (for future maintainers / coding agents working in the repo): <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/AGENTS.md>
 
-| Variable | Description | Default |
-|---|---|---|
-| `AWS_REGION` | AWS region | `us-east-1` |
-| `AWS_PROFILE` | AWS SSO profile name | `default` |
+## License
 
-### Git
+MIT. See <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/LICENSE>.
 
-| Variable | Description |
-|---|---|
-| `GIT_USER_NAME` | Git commit author name |
-| `GIT_USER_EMAIL` | Git commit author email |
+---
 
-### User ID Mapping
-
-The container runs as user `developer` (UID 1000 by default). If your host user has a different UID, file permission mismatches can occur on mounted volumes.
-
-The entrypoint automatically detects the owner of `/workspace` and adjusts the container user's UID/GID to match. You can also set it explicitly:
-
-| Variable | Description | Default |
-|---|---|---|
-| `USER_UID` | Container user UID | Auto-detect from `/workspace` owner |
-| `USER_GID` | Container user GID | Auto-detect from `/workspace` owner |
-
-## Initial Setup
-
-### 1. Create a project directory
-
-```bash
-mkdir -p ~/projects
-```
-
-### 2. Create a `.env` file
-
-Create a `.env` file with your configuration. Examples for each provider:
-
-**Anthropic:**
-```bash
-OPENCODE_PROVIDER=anthropic
-ANTHROPIC_API_KEY=sk-ant-...
-GIT_USER_NAME=Your Name
-GIT_USER_EMAIL=you@example.com
-```
-
-**OpenAI:**
-```bash
-OPENCODE_PROVIDER=openai
-OPENAI_API_KEY=sk-...
-GIT_USER_NAME=Your Name
-GIT_USER_EMAIL=you@example.com
-```
-
-**AWS Bedrock (SSO):**
-```bash
-OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
-AWS_REGION=eu-west-1
-AWS_PROFILE=your-profile-name
-GIT_USER_NAME=Your Name
-GIT_USER_EMAIL=you@example.com
-```
-
-### 3. AWS SSO setup (Bedrock users only)
-
-AWS SSO requires a `~/.aws/config` file on the host with your SSO session configuration. If you already have this on another machine, copy it:
-
-```bash
-scp -r user@other-machine:~/.aws ~/.aws
-```
-
-Or configure from scratch:
-
-```bash
-aws configure sso
-```
-
-You'll be prompted for:
-- SSO session name
-- SSO start URL
-- SSO region
-- Registration scopes (typically `sso:account:access`)
-
-The `~/.aws` directory must be mounted into the container (see docker-compose example below).
-
-## Data Storage and Persistence
-
-Understanding what survives container restarts and what doesn't:
-
-| Path in container | Source | Survives restart? | Contains |
-|---|---|---|---|
-| `/workspace` | Host bind mount | ✅ Yes — lives on host | Your project files |
-| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes — lives on host | SSH keys |
-| `/home/developer/.aws` | Host bind mount | ✅ Yes — lives on host | AWS credentials/SSO cache |
-| `/home/developer/.local/share/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | Session history, memory, auth tokens |
-| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No — regenerated each start | Provider config, MCP server definitions |
-| `/home/developer/.config/opencode/oh-my-opencode-slim.json` | Generated by entrypoint (OMOS variant) | ❌ No — regenerated each start | Agent/model mappings |
-
-### Key points
-
-- **Project files** (`/workspace`) are always safe — they're your host filesystem.
-- **opencode config** is auto-generated from `OPENCODE_PROVIDER` env var on each start. It only sets provider and model — no MCP servers. To persist MCP server config, mount your own config file (see Custom opencode Config below).
-- **opencode data** (session history, memory) is lost with `--rm` unless you add a named volume.
-- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
-
-## Custom opencode Config
-
-For full control (MCP servers, custom models, keybindings), mount your own config:
-
-```bash
-docker run -it --rm \
-  -v ./my-opencode.json:/home/developer/.config/opencode/opencode.json:ro \
-  ... \
-  joakimp/opencode-devbox:latest
-```
-
-When a config file is mounted, the `OPENCODE_PROVIDER` auto-config is skipped.
-
-## Using docker-compose
-
-Create a directory with a `docker-compose.yml` and a `.env` file:
-
-```bash
-mkdir opencode-devbox && cd opencode-devbox
-```
-
-`.env` — your settings (never commit this):
-
-```bash
-OPENCODE_PROVIDER=amazon-bedrock
-OPENCODE_MODEL=amazon-bedrock/anthropic.claude-sonnet-4-5-v1
-AWS_REGION=eu-west-1
-AWS_PROFILE=your-profile-name
-GIT_USER_NAME=Your Name
-GIT_USER_EMAIL=you@example.com
-```
-
-`docker-compose.yml`:
-
-```yaml
-services:
-  devbox:
-    image: joakimp/opencode-devbox:latest
-    # For multi-agent orchestration, use the omos variant instead:
-    # image: joakimp/opencode-devbox:latest-omos
-    stdin_open: true
-    tty: true
-    env_file:
-      - .env
-    environment:
-      - TERM=xterm-256color
-    volumes:
-      - ~/projects:/workspace
-      - ~/.ssh:/home/developer/.ssh:ro
-      - devbox-data:/home/developer/.local/share/opencode
-      # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
-      # - ~/.aws:/home/developer/.aws
-      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
-      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
-      # Optional: mount opencode skills from host
-      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
-      # - ~/.agents/skills:/home/developer/.agents/skills:ro
-
-volumes:
-  devbox-data:
-```
-
-Docker Compose loads `.env` automatically from the same directory. All variables from `.env` are passed to the container via `env_file`. Do **not** hardcode provider settings in the `environment:` section — use `.env` instead.
-
-Then:
-
-```bash
-# Start in background
-docker compose up -d
-
-# Open a shell (always use -u developer with exec)
-docker compose exec -u developer devbox bash
-
-# For Bedrock: authenticate, then start opencode
-aws sso login --sso-session <your-session> --use-device-code
-opencode
-
-# Or run opencode directly (if no SSO needed)
-docker compose exec -u developer devbox opencode
-
-# One-shot mode (creates and removes container)
-docker compose run --rm devbox        # direct to opencode
-docker compose run --rm devbox bash   # interactive shell
-```
-
-## What's Included
-
-### Base image (`latest`)
-
-- **Debian bookworm-slim** — glibc, full terminal/PTY support
-- **opencode** — AI coding assistant
-- **Node.js 22** — for npx-based MCP servers
-- **AWS CLI v2** — SSO and Bedrock authentication
-- **Dev tools** — git, git-lfs, ssh, ripgrep, fd, fzf, jq, curl, wget, vim, tree
-- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
-
-### OMOS image (`latest-omos`)
-
-Everything in the base image, plus:
-
-- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** — multi-agent orchestration plugin
-- **Bun** — JavaScript runtime required by oh-my-opencode-slim
-- **tmux** — terminal multiplexer (used by OMOS for agent pane integration, but also useful on its own for managing multiple terminal sessions)
-- **6 specialized agents** — Orchestrator, Explorer, Oracle, Librarian, Designer, Fixer
-
-### Additional runtimes (build from source)
-
-When [building from source](https://gitea.jordbo.se/joakimp/opencode-devbox), additional runtimes are available via build args:
-
-- **Python 3** (`INSTALL_PYTHON=true`) — Python 3 + pip + venv
-- **Go** (`INSTALL_GO=true`) — Go toolchain
-
-## oh-my-opencode-slim (OMOS variant)
-
-The `-omos` image variant includes [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim), which adds a multi-agent layer on top of opencode. An Orchestrator delegates tasks to specialized agents, each configurable with different models and providers.
-
-### Quick start with OMOS
-
-```bash
-docker run -it --rm \
-  -e OPENAI_API_KEY=your-key \
-  -e OPENCODE_PROVIDER=openai \
-  -e ENABLE_OMOS=true \
-  -v ~/projects:/workspace \
-  -v ~/.ssh:/home/developer/.ssh:ro \
-  joakimp/opencode-devbox:latest-omos
-```
-
-On first start, the entrypoint configures oh-my-opencode-slim automatically. The default preset uses OpenAI models.
-
-### OMOS environment variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
-| `OMOS_TMUX` | `false` | Enable tmux pane integration (watch agents in split panes) |
-| `OMOS_SKILLS` | `true` | Install recommended skills (simplify, agent-browser, cartography) |
-| `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config) |
-
-### Custom OMOS configuration
-
-Mount your own config to control which models power each agent:
-
-```bash
-docker run -it --rm \
-  -e ENABLE_OMOS=true \
-  -v ./oh-my-opencode-slim.json:/home/developer/.config/opencode/oh-my-opencode-slim.json:ro \
-  ... \
-  joakimp/opencode-devbox:latest-omos
-```
-
-See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
-
-### Verifying agents
-
-After starting opencode with OMOS enabled, run inside the opencode session:
-
-```
-ping all agents
-```
-
-All six agents should respond if your provider authentication is working.
-
-## Source
-
-Build from source or contribute: [opencode-devbox on Gitea](https://gitea.jordbo.se/joakimp/opencode-devbox)
+> This description is generated by `scripts/generate-dockerhub-md.py` from a hand-maintained template. Edit the template (not this file) and regenerate.

Dockerfile

@@ -1,11 +1,11 @@
 # opencode-devbox — portable AI dev environment
 # Debian-based container with opencode and configurable dev tools
 
-ARG DEBIAN_VERSION=bookworm-slim
+ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base
 
 ARG TARGETARCH
-ARG OPENCODE_VERSION=1.4.3
+ARG OPENCODE_VERSION=1.14.41
 
 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -15,7 +15,12 @@ LABEL org.opencontainers.image.source="https://gitea.jordbo.se/joakimp/opencode-
 ENV DEBIAN_FRONTEND=noninteractive
 
 # ── Core system packages ─────────────────────────────────────────────
-RUN apt-get update && apt-get install -y --no-install-recommends \
+# apt-get upgrade picks up any security/CVE fixes published between
+# debian:trixie-slim base-image rebuilds. Paired with the index update
+# and the install in the same layer so we don't bloat image history.
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    apt-get install -y --no-install-recommends \
     ca-certificates \
     curl \
     wget \
@@ -27,54 +32,293 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     fd-find \
     tree \
     less \
-    vim-tiny \
+    htop \
+    tmux \
+    make \
+    patch \
+    diffutils \
+    git-crypt \
+    age \
+    file \
     sudo \
     locales \
     procps \
     unzip \
+    gcc \
+    g++ \
+    rsync \
+    python3-pip \
+    python3-venv \
     && ln -s /usr/bin/fdfind /usr/local/bin/fd \
+    && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
 # ── Go-compiled tools (install from GitHub to avoid CVEs in Debian's old Go builds)
+#
+# Version policy for the binaries below:
+#   • Default is `latest` — resolved at build time by following the
+#     /releases/latest redirect on GitHub and reading the tag from the
+#     Location header. This means every tagged image picks up the newest
+#     upstream release, with no risk of running months-old CVE-affected
+#     binaries.
+#   • Explicit pins still work: pass `--build-arg GOSU_VERSION=1.19` etc.
+#     Useful for reproducibility or rolling back a bad upstream release.
+#   • Resolved versions are printed during build and re-checked by the
+#     smoke test (scripts/smoke-test.sh), so drift is visible in CI logs.
+#
+# The helper `resolve_latest` reads the redirected tag (e.g. "v0.26.1")
+# and strips a leading "v" if present, yielding a plain version string.
 
-# gosu — privilege de-escalation (built with Go 1.24.6)
-ARG GOSU_VERSION=1.19
+# gosu — privilege de-escalation
+ARG GOSU_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
-    curl -fsSL "https://github.com/tianon/gosu/releases/download/${GOSU_VERSION}/gosu-${ARCH}" -o /usr/local/bin/gosu && \
+    V="${GOSU_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/tianon/gosu/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing gosu ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/tianon/gosu/releases/download/${V}/gosu-${ARCH}" -o /usr/local/bin/gosu && \
     chmod +x /usr/local/bin/gosu && \
     gosu --version
 
-# fzf — fuzzy finder (built with Go 1.23.12)
-ARG FZF_VERSION=0.71.0
+# fzf — fuzzy finder
+ARG FZF_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
-    curl -fsSL "https://github.com/junegunn/fzf/releases/download/v${FZF_VERSION}/fzf-${FZF_VERSION}-linux_${ARCH}.tar.gz" | tar -xz -C /usr/local/bin fzf && \
+    V="${FZF_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/junegunn/fzf/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing fzf ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/junegunn/fzf/releases/download/v${V}/fzf-${V}-linux_${ARCH}.tar.gz" | tar -xz -C /usr/local/bin fzf && \
     fzf --version
 
-# git-lfs — Git Large File Storage (built with Go 1.25)
-ARG GIT_LFS_VERSION=3.7.1
+# git-lfs — Git Large File Storage
+ARG GIT_LFS_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
-    curl -fsSL "https://github.com/git-lfs/git-lfs/releases/download/v${GIT_LFS_VERSION}/git-lfs-linux-${ARCH}-v${GIT_LFS_VERSION}.tar.gz" | tar -xz -C /tmp && \
-    install /tmp/git-lfs-${GIT_LFS_VERSION}/git-lfs /usr/local/bin/git-lfs && \
-    rm -rf /tmp/git-lfs-${GIT_LFS_VERSION} && \
+    V="${GIT_LFS_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/git-lfs/git-lfs/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing git-lfs ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/git-lfs/git-lfs/releases/download/v${V}/git-lfs-linux-${ARCH}-v${V}.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/git-lfs-${V}/git-lfs /usr/local/bin/git-lfs && \
+    rm -rf /tmp/git-lfs-${V} && \
     git lfs install --system && \
     git-lfs --version
 
-# Set locale
-RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+# neovim — modern text editor
+ARG NVIM_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
+    V="${NVIM_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/neovim/neovim/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing neovim ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/neovim/neovim/releases/download/v${V}/nvim-linux-${ARCH}.tar.gz" | tar -xz -C /opt && \
+    ln -s /opt/nvim-linux-${ARCH}/bin/nvim /usr/local/bin/nvim && \
+    nvim --version | head -1
+
+# bat — syntax-highlighted cat replacement
+ARG BAT_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${BAT_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/sharkdp/bat/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing bat ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/sharkdp/bat/releases/download/v${V}/bat-v${V}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/bat-v${V}-${ARCH}-unknown-linux-musl/bat /usr/local/bin/bat && \
+    rm -rf /tmp/bat-v${V}-* && \
+    bat --version
+
+# eza — modern ls replacement
+ARG EZA_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${EZA_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/eza-community/eza/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing eza ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/eza-community/eza/releases/download/v${V}/eza_${ARCH}-unknown-linux-gnu.tar.gz" | tar -xz -C /usr/local/bin && \
+    eza --version | head -1
+
+# zoxide — smarter cd command
+ARG ZOXIDE_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${ZOXIDE_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/ajeetdsouza/zoxide/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing zoxide ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/ajeetdsouza/zoxide/releases/download/v${V}/zoxide-${V}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
+    zoxide --version
+
+# uv — fast Python package manager (replaces pip, venv, pyenv)
+# Note: uv releases don't prefix tags with "v" (e.g. tag is "0.11.8").
+ARG UV_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${UV_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/astral-sh/uv/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing uv ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/astral-sh/uv/releases/download/${V}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uv /usr/local/bin/uv && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uvx /usr/local/bin/uvx && \
+    rm -rf /tmp/uv-* && \
+    uv --version
+
+# ── Optional: MemPalace — local-first AI memory system ───────────────
+# Provides semantic search over conversation history via 29 MCP tools.
+# Palace data persists via the devbox-palace named volume.
+# The embedding model (~300 MB) is downloaded on first use and cached
+# in the palace directory.
+#
+# Installed via `uv tool install` into an isolated venv at
+# /opt/uv-tools/mempalace/. The `mempalace` CLI goes directly on PATH;
+# the MCP server is reached via the /usr/local/bin/mempalace-mcp-server
+# wrapper (rootfs/usr/local/bin/mempalace-mcp-server), since system
+# python3 cannot import from the isolated venv.
+#
+# Disable with --build-arg INSTALL_MEMPALACE=false to shave ~300 MB off
+# the image (chromadb, torch-adjacent deps).
+ARG INSTALL_MEMPALACE=true
+ENV UV_TOOL_DIR=/opt/uv-tools
+ENV UV_TOOL_BIN_DIR=/usr/local/bin
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
+      mkdir -p /opt/uv-tools && \
+      uv tool install --no-cache mempalace && \
+      /opt/uv-tools/mempalace/bin/python -c "import mempalace; print('mempalace', mempalace.__version__ if hasattr(mempalace, '__version__') else 'installed')" ; \
+    fi
+
+# ── mempalace-toolkit — bash wrappers for session/docs mining ────────
+# Thin wrappers (`mempalace-session`, `mempalace-docs`) that delegate to
+# the mempalace Python CLI for two common scheduled tasks:
+#   - mempalace-session: mines opencode's SQLite session history into
+#     the palace (wing_conversations). Referenced by contrib/ scheduler
+#     templates (systemd user timer, cron) in the toolkit repo.
+#   - mempalace-docs: mines project docs into a per-project wing.
+# Repo source of truth: https://gitea.jordbo.se/joakimp/mempalace-toolkit
+#
+# Requires INSTALL_MEMPALACE=true (wrappers shell out to `mempalace`).
+# Disable with --build-arg INSTALL_MEMPALACE_TOOLKIT=false if you don't
+# use the scheduled-mining workflow.
+ARG INSTALL_MEMPALACE_TOOLKIT=true
+ARG MEMPALACE_TOOLKIT_REF=main
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ] && [ "${INSTALL_MEMPALACE_TOOLKIT}" = "true" ]; then \
+      git clone --depth 1 --branch "${MEMPALACE_TOOLKIT_REF}" \
+        https://gitea.jordbo.se/joakimp/mempalace-toolkit.git /opt/mempalace-toolkit && \
+      ln -sf /opt/mempalace-toolkit/bin/mempalace-session /usr/local/bin/mempalace-session && \
+      ln -sf /opt/mempalace-toolkit/bin/mempalace-docs    /usr/local/bin/mempalace-docs && \
+      chmod +x /opt/mempalace-toolkit/bin/mempalace-session /opt/mempalace-toolkit/bin/mempalace-docs && \
+      mempalace-session --help >/dev/null && \
+      mempalace-docs    --help >/dev/null && \
+      echo "mempalace-toolkit installed at $(cd /opt/mempalace-toolkit && git rev-parse --short HEAD)" ; \
+    fi
+
+# rustup — Rust toolchain manager
+# Installs the rustup-init binary only. Users bootstrap Rust with:
+#   rustup-init -y && source ~/.cargo/env
+# Toolchains persist via devbox-rustup and devbox-cargo volumes.
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
+    chmod +x /usr/local/bin/rustup-init
+
+# gitea-mcp — MCP server for Gitea API (official, Go binary, hosted on gitea.com)
+ARG GITEA_MCP_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
+    V="${GITEA_MCP_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://gitea.com/gitea/gitea-mcp/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing gitea-mcp ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://gitea.com/gitea/gitea-mcp/releases/download/v${V}/gitea-mcp_Linux_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin/ gitea-mcp && \
+    chmod +x /usr/local/bin/gitea-mcp && \
+    gitea-mcp --version
+
+# Set locale — generate common UTF-8 locales (override via LANG/LC_ALL env vars)
+# To add more locales, run: sudo sed -i '/<locale>.UTF-8/s/^# //g' /etc/locale.gen && sudo locale-gen
+RUN sed -i -E '/(en_US|en_GB|sv_SE|da_DK|nb_NO|fi_FI|de_DE|fr_FR|es_ES|it_IT|pt_BR|nl_NL|pl_PL|ja_JP|ko_KR|zh_CN)\.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
 ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 ENV LC_ALL=en_US.UTF-8
+ENV EDITOR=nvim
+ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
 
 # ── Node.js (required for opencode v1.x install + MCP servers) ──────
 ARG NODE_VERSION=22
-RUN curl -fsSL https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \
+RUN curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \
     apt-get install -y --no-install-recommends nodejs && \
     rm -rf /var/lib/apt/lists/*
 
 # ── Install opencode via npm ─────────────────────────────────────────
-# v1.x is distributed as an npm package with platform-specific binaries
-RUN npm install -g opencode-ai@${OPENCODE_VERSION} && \
-    opencode --version
+# v1.x is distributed as an npm package with platform-specific binaries.
+# Disable with --build-arg INSTALL_OPENCODE=false to build a slimmer
+# image without opencode (e.g. when only pi is needed). For a fully
+# pi-only stripped image (no Bun, no opencode), see the pi-devbox repo.
+ARG INSTALL_OPENCODE=true
+RUN if [ "${INSTALL_OPENCODE}" = "true" ]; then \
+      npm install -g opencode-ai@${OPENCODE_VERSION} && \
+      opencode --version ; \
+    fi
+
+# ── Optional: pi coding-agent ────────────────────────────────────────
+# Installs pi as an alternative/complementary harness. Coexists with
+# opencode in the same image — both share the mempalace install and
+# palace path, so wing data is mutually visible to either harness.
+#
+# pi-toolkit (keybindings.json + pi-env.zsh + settings.example.json)
+# and pi-extensions (confirm-destructive, ext-toggle, git-checkpoint,
+# notify, ssh-controlmaster, todo, …) are cloned into /opt/ at build
+# time. entrypoint-user.sh runs each repo's install.sh on container
+# start so symlinks land under ~/.pi/agent/ on the named volume.
+#
+# Pi version is pinned by PI_VERSION (default: latest at build time).
+# The baked pi binary lives at /usr/bin/pi (system npm prefix); the
+# user-writable NPM_CONFIG_PREFIX (~/.pi/npm-global, set further down)
+# is only consulted by `pi install npm:<pkg>` and `npm install -g` at
+# runtime — it does NOT shadow the baked pi unless the user does
+# `npm install -g @mariozechner/pi-coding-agent` themselves, in which
+# case the user-installed copy on the volume wins via PATH order. Same
+# contract as OPENCODE_VERSION otherwise: rebuild the image to upgrade
+# the baked pi.
+ARG INSTALL_PI=false
+ARG PI_VERSION=latest
+ARG PI_TOOLKIT_REF=main
+ARG PI_EXTENSIONS_REF=main
+RUN if [ "${INSTALL_PI}" = "true" ]; then \
+      if [ "${PI_VERSION}" = "latest" ]; then \
+        npm install -g @mariozechner/pi-coding-agent ; \
+      else \
+        npm install -g @mariozechner/pi-coding-agent@${PI_VERSION} ; \
+      fi && \
+      pi --version && \
+      git clone --depth 1 --branch "${PI_TOOLKIT_REF}" \
+        https://gitea.jordbo.se/joakimp/pi-toolkit.git /opt/pi-toolkit && \
+      git clone --depth 1 --branch "${PI_EXTENSIONS_REF}" \
+        https://gitea.jordbo.se/joakimp/pi-extensions.git /opt/pi-extensions && \
+      echo "pi-toolkit at $(cd /opt/pi-toolkit && git rev-parse --short HEAD)" && \
+      echo "pi-extensions at $(cd /opt/pi-extensions && git rev-parse --short HEAD)" ; \
+    fi
 
 # ── AWS CLI v2 (for SSO/Bedrock authentication) ─────────────────────
 RUN ARCH=$(case "${TARGETARCH}" in \
@@ -82,40 +326,54 @@ RUN ARCH=$(case "${TARGETARCH}" in \
       arm64) echo "aarch64" ;; \
       *) echo "x86_64" ;; \
     esac) && \
-    curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-${ARCH}.zip" -o /tmp/awscli.zip && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://awscli.amazonaws.com/awscli-exe-linux-${ARCH}.zip" -o /tmp/awscli.zip && \
     unzip -q /tmp/awscli.zip -d /tmp && \
     /tmp/aws/install && \
     rm -rf /tmp/aws /tmp/awscli.zip && \
-    aws --version
-
-# ── Optional: Python ─────────────────────────────────────────────────
-ARG INSTALL_PYTHON=false
-RUN if [ "${INSTALL_PYTHON}" = "true" ]; then \
-      apt-get update && apt-get install -y --no-install-recommends \
-        python3 python3-pip python3-venv && \
-      rm -rf /var/lib/apt/lists/*; \
-    fi
+     aws --version
 
 # ── Optional: Go ─────────────────────────────────────────────────────
+# Latest stable Go is resolved from https://go.dev/dl/?mode=json when
+# GO_VERSION=latest (default). Pass an explicit version like "1.26.2"
+# to pin.
 ARG INSTALL_GO=false
-ARG GO_VERSION=1.23.4
+ARG GO_VERSION=latest
 RUN if [ "${INSTALL_GO}" = "true" ]; then \
       GOARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
-      curl -fsSL "https://go.dev/dl/go${GO_VERSION}.linux-${GOARCH}.tar.gz" | tar -C /usr/local -xz && \
+      V="${GO_VERSION}" && \
+      if [ "$V" = "latest" ]; then \
+        V=$(curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://go.dev/dl/?mode=json" | \
+            awk -F'"' '/"version":/ { sub(/^go/,"",$4); print $4; exit }'); \
+      fi && \
+      [ -n "$V" ] && \
+      echo "Installing Go ${V}" && \
+      curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://go.dev/dl/go${V}.linux-${GOARCH}.tar.gz" | tar -C /usr/local -xz && \
       ln -s /usr/local/go/bin/go /usr/local/bin/go && \
       ln -s /usr/local/go/bin/gofmt /usr/local/bin/gofmt; \
     fi
 
 # ── Optional: oh-my-opencode-slim (multi-agent orchestration) ────────
-# Installs Bun runtime, tmux, and the oh-my-opencode-slim npm package.
+# Installs Bun runtime and the oh-my-opencode-slim npm package.
 # Runtime activation is controlled by ENABLE_OMOS env var in entrypoint.
+# Uses the baseline Bun build (SSE4.2 only) for compatibility with older
+# CPUs that lack AVX2 (e.g. Sandy Bridge on OpenStack).
 ARG INSTALL_OMOS=false
 ARG OMOS_VERSION=latest
 RUN if [ "${INSTALL_OMOS}" = "true" ]; then \
-      apt-get update && apt-get install -y --no-install-recommends tmux && \
-      rm -rf /var/lib/apt/lists/* && \
-      curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash && \
+      ARCH=$(uname -m) && \
+      if [ "$ARCH" = "x86_64" ]; then \
+        BUN_ARCH="x64-baseline"; \
+      elif [ "$ARCH" = "aarch64" ]; then \
+        BUN_ARCH="aarch64"; \
+      fi && \
+      curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/oven-sh/bun/releases/latest/download/bun-linux-${BUN_ARCH}.zip" -o /tmp/bun.zip && \
+      unzip -o /tmp/bun.zip -d /tmp/bun && \
+      mv /tmp/bun/bun-linux-${BUN_ARCH}/bun /usr/local/bin/bun && \
+      chmod +x /usr/local/bin/bun && \
+      ln -sf bun /usr/local/bin/bunx && \
+      rm -rf /tmp/bun /tmp/bun.zip && \
       bun --version && \
+      test -L /usr/local/bin/bunx && \
       npm install -g oh-my-opencode-slim@${OMOS_VERSION}; \
     fi
 
@@ -129,20 +387,89 @@ RUN groupadd --gid ${USER_GID} ${USER_NAME} && \
     echo "${USER_NAME} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/${USER_NAME}
 
 # Create standard directories
+#
+# ~/.pi/agent/extensions/ is created proactively so the named volume
+# mount has a real owner from the first start. The directory is also
+# what mempalace-toolkit's install_pi_extension probes to decide
+# whether to deploy the pi↔mempalace bridge — must exist before that
+# step runs in entrypoint-user.sh.
 RUN mkdir -p /workspace \
     /home/${USER_NAME}/.config/opencode/skills \
+    /home/${USER_NAME}/.pi/agent/extensions \
     /home/${USER_NAME}/.agents/skills \
     /home/${USER_NAME}/.local/share/opencode \
+    /home/${USER_NAME}/.cache/bash \
     /home/${USER_NAME}/.ssh && \
     chown -R ${USER_NAME}:${USER_NAME} /workspace /home/${USER_NAME}
 
+# ── Pre-warm chromadb embedding model ──────────────────────────────
+# Mempalace uses chromadb's ONNXMiniLM_L6_V2 embedding function, which
+# downloads ~80 MB of all-MiniLM-L6-v2 ONNX weights from chromadb's CDN
+# on first use. Without pre-warming this happens silently (output is
+# suppressed by the entrypoint init step) and stalls first container
+# start by minutes on a slow network. We bake the cache at build time
+# under the developer user's home so the runtime first-start is fast.
+#
+# Cache path comes from chromadb's hardcoded `Path.home() / .cache /
+# chroma / onnx_models / all-MiniLM-L6-v2`. Run as gosu developer so
+# Path.home() resolves correctly and ownership is right from the start.
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
+      gosu ${USER_NAME} /opt/uv-tools/mempalace/bin/python -c "\
+from chromadb.utils.embedding_functions import ONNXMiniLM_L6_V2; \
+ef = ONNXMiniLM_L6_V2(); \
+_ = ef(['warmup']); \
+print('chromadb embedding model warmed: all-MiniLM-L6-v2')" && \
+      ls -lh /home/${USER_NAME}/.cache/chroma/onnx_models/all-MiniLM-L6-v2/ ; \
+    fi
+
+# ── User-writable npm global prefix on the devbox-pi-config volume ──
+# By default npm's global prefix is /usr (writable only by root) so any
+# `pi install npm:<pkg>` or `npm install -g <pkg>` invoked by the
+# developer user would EACCES. Pointing the prefix into ~/.pi places
+# user-installed packages on the named volume, which means they survive
+# container recreation AND image rebuilds (complementing pi's auto-
+# restore from settings.json with one less cold-start step).
+#
+# These ENVs land AFTER all build-time `npm install -g` calls
+# (opencode, pi, oh-my-opencode-slim) so those still install to /usr at
+# build time. They take effect for every runtime invocation regardless
+# of shell init: docker compose run/exec, login shells, non-interactive
+# commands. npm auto-creates the prefix directory on first install.
+#
+# Harmless when INSTALL_PI=false (and no named volume mounted at ~/.pi):
+# the dir just lives on the container's writable layer.
+ENV NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global
+ENV PATH="/home/${USER_NAME}/.pi/npm-global/bin:${PATH}"
+
+# ── Shell defaults (bash history, aliases, readline) ─────────────────
+# Shipped under /etc/skel-devbox/ rather than copied directly to the
+# user's home. The entrypoint copies them to /home/developer/ only if
+# the target file does not already exist, so host bind-mounts and
+# previously-customized files are never overwritten. Users can restore
+# the baked defaults anytime via:
+#   cp /etc/skel-devbox/.bash_aliases ~/.bash_aliases
+# History itself persists via the devbox-shell-history named volume
+# mounted at ~/.cache/bash (HISTFILE points there).
+RUN mkdir -p /etc/skel-devbox
+COPY rootfs/home/developer/.bash_aliases /etc/skel-devbox/.bash_aliases
+COPY rootfs/home/developer/.inputrc      /etc/skel-devbox/.inputrc
+
 # ── Entrypoint ────────────────────────────────────────────────────────
+COPY rootfs/usr/local/lib/opencode-devbox/ /usr/local/lib/opencode-devbox/
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY entrypoint-user.sh /usr/local/bin/entrypoint-user.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint-user.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint-user.sh \
+    /usr/local/lib/opencode-devbox/*.py
 
 # Start as root — entrypoint adjusts UID/GID then drops to developer
 WORKDIR /workspace
 
 ENTRYPOINT ["entrypoint.sh"]
-CMD ["opencode"]
+# Default to a login shell. `docker compose run --rm devbox` drops
+# the user into bash to choose: `aws sso login`, then `opencode`
+# or `pi`. To launch a harness directly, pass it explicitly:
+#   docker compose run --rm devbox opencode
+#   docker compose run --rm devbox pi
+# `docker compose exec` bypasses the entrypoint and CMD entirely, so
+# this default has no effect on attach-style workflows.
+CMD ["bash", "-l"]

Dockerfile.base

@@ -0,0 +1,330 @@
+# opencode-devbox — base image (variant-independent layers)
+#
+# This Dockerfile produces an image tagged base-<hash>, used as the parent
+# for all four published variants (base, omos, with-pi, omos-with-pi).
+# It contains everything that does not depend on variant-specific
+# build-args (INSTALL_OPENCODE, INSTALL_OMOS, INSTALL_PI). The variant
+# Dockerfile (Dockerfile.variant) FROMs the base and adds only those
+# deltas.
+#
+# The base is rebuilt only when this file or anything it COPYs in
+# changes (rootfs/, entrypoint*.sh). Version bumps to OPENCODE_VERSION,
+# OMOS_VERSION, PI_VERSION, etc. do NOT trigger a base rebuild.
+#
+# See the project README's "Build pipeline" section for the rationale.
+
+ARG DEBIAN_VERSION=trixie-slim
+FROM debian:${DEBIAN_VERSION} AS base
+
+ARG TARGETARCH
+
+LABEL maintainer="joakimp"
+LABEL description="opencode-devbox — base image (variant-independent)"
+LABEL org.opencontainers.image.source="https://gitea.jordbo.se/joakimp/opencode-devbox"
+
+# Avoid interactive prompts during build
+ENV DEBIAN_FRONTEND=noninteractive
+
+# ── Core system packages ─────────────────────────────────────────────
+# apt-get upgrade picks up any security/CVE fixes published between
+# debian:trixie-slim base-image rebuilds. Paired with the index update
+# and the install in the same layer so we don't bloat image history.
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    apt-get install -y --no-install-recommends \
+    ca-certificates \
+    curl \
+    wget \
+    git \
+    openssh-client \
+    gnupg \
+    jq \
+    ripgrep \
+    fd-find \
+    tree \
+    less \
+    htop \
+    tmux \
+    make \
+    patch \
+    diffutils \
+    git-crypt \
+    age \
+    file \
+    sudo \
+    locales \
+    procps \
+    unzip \
+    gcc \
+    g++ \
+    rsync \
+    python3-pip \
+    python3-venv \
+    && ln -s /usr/bin/fdfind /usr/local/bin/fd \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Go-compiled tools (install from GitHub to avoid CVEs in Debian's old Go builds)
+#
+# Version policy for the binaries below:
+#   • Default is `latest` — resolved at build time by following the
+#     /releases/latest redirect on GitHub and reading the tag from the
+#     Location header. This means every base rebuild picks up the newest
+#     upstream release, with no risk of running months-old CVE-affected
+#     binaries.
+#   • Explicit pins still work: pass `--build-arg GOSU_VERSION=1.19` etc.
+#   • Resolved versions are printed during build and re-checked by the
+#     smoke test (scripts/smoke-test.sh), so drift is visible in CI logs.
+
+# gosu — privilege de-escalation
+ARG GOSU_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    V="${GOSU_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/tianon/gosu/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing gosu ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/tianon/gosu/releases/download/${V}/gosu-${ARCH}" -o /usr/local/bin/gosu && \
+    chmod +x /usr/local/bin/gosu && \
+    gosu --version
+
+# fzf — fuzzy finder
+ARG FZF_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    V="${FZF_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/junegunn/fzf/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing fzf ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/junegunn/fzf/releases/download/v${V}/fzf-${V}-linux_${ARCH}.tar.gz" | tar -xz -C /usr/local/bin fzf && \
+    fzf --version
+
+# git-lfs — Git Large File Storage
+ARG GIT_LFS_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    V="${GIT_LFS_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/git-lfs/git-lfs/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing git-lfs ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/git-lfs/git-lfs/releases/download/v${V}/git-lfs-linux-${ARCH}-v${V}.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/git-lfs-${V}/git-lfs /usr/local/bin/git-lfs && \
+    rm -rf /tmp/git-lfs-${V} && \
+    git lfs install --system && \
+    git-lfs --version
+
+# neovim — modern text editor
+ARG NVIM_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
+    V="${NVIM_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/neovim/neovim/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing neovim ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/neovim/neovim/releases/download/v${V}/nvim-linux-${ARCH}.tar.gz" | tar -xz -C /opt && \
+    ln -s /opt/nvim-linux-${ARCH}/bin/nvim /usr/local/bin/nvim && \
+    nvim --version | head -1
+
+# bat — syntax-highlighted cat replacement
+ARG BAT_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${BAT_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/sharkdp/bat/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing bat ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/sharkdp/bat/releases/download/v${V}/bat-v${V}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/bat-v${V}-${ARCH}-unknown-linux-musl/bat /usr/local/bin/bat && \
+    rm -rf /tmp/bat-v${V}-* && \
+    bat --version
+
+# eza — modern ls replacement
+ARG EZA_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${EZA_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/eza-community/eza/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing eza ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/eza-community/eza/releases/download/v${V}/eza_${ARCH}-unknown-linux-gnu.tar.gz" | tar -xz -C /usr/local/bin && \
+    eza --version | head -1
+
+# zoxide — smarter cd command
+ARG ZOXIDE_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${ZOXIDE_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/ajeetdsouza/zoxide/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing zoxide ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/ajeetdsouza/zoxide/releases/download/v${V}/zoxide-${V}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
+    zoxide --version
+
+# uv — fast Python package manager (replaces pip, venv, pyenv)
+# Note: uv releases don't prefix tags with "v" (e.g. tag is "0.11.8").
+ARG UV_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${UV_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/astral-sh/uv/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing uv ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/astral-sh/uv/releases/download/${V}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uv /usr/local/bin/uv && \
+    install /tmp/uv-${ARCH}-unknown-linux-musl/uvx /usr/local/bin/uvx && \
+    rm -rf /tmp/uv-* && \
+    uv --version
+
+# ── MemPalace — local-first AI memory system ─────────────────────────
+# Provides semantic search over conversation history via 29 MCP tools.
+# Always installed in the base (variant-independent). Set
+# INSTALL_MEMPALACE=false at base-build time to shave ~300 MB.
+ARG INSTALL_MEMPALACE=true
+ENV UV_TOOL_DIR=/opt/uv-tools
+ENV UV_TOOL_BIN_DIR=/usr/local/bin
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
+      mkdir -p /opt/uv-tools && \
+      uv tool install --no-cache mempalace && \
+      /opt/uv-tools/mempalace/bin/python -c "import mempalace; print('mempalace', mempalace.__version__ if hasattr(mempalace, '__version__') else 'installed')" ; \
+    fi
+
+# ── mempalace-toolkit — bash wrappers for session/docs mining ────────
+ARG INSTALL_MEMPALACE_TOOLKIT=true
+ARG MEMPALACE_TOOLKIT_REF=main
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ] && [ "${INSTALL_MEMPALACE_TOOLKIT}" = "true" ]; then \
+      git clone --depth 1 --branch "${MEMPALACE_TOOLKIT_REF}" \
+        https://gitea.jordbo.se/joakimp/mempalace-toolkit.git /opt/mempalace-toolkit && \
+      ln -sf /opt/mempalace-toolkit/bin/mempalace-session /usr/local/bin/mempalace-session && \
+      ln -sf /opt/mempalace-toolkit/bin/mempalace-docs    /usr/local/bin/mempalace-docs && \
+      chmod +x /opt/mempalace-toolkit/bin/mempalace-session /opt/mempalace-toolkit/bin/mempalace-docs && \
+      mempalace-session --help >/dev/null && \
+      mempalace-docs    --help >/dev/null && \
+      echo "mempalace-toolkit installed at $(cd /opt/mempalace-toolkit && git rev-parse --short HEAD)" ; \
+    fi
+
+# rustup — Rust toolchain manager (init binary only; toolchains installed at runtime)
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
+    chmod +x /usr/local/bin/rustup-init
+
+# gitea-mcp — MCP server for Gitea API
+ARG GITEA_MCP_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
+    V="${GITEA_MCP_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://gitea.com/gitea/gitea-mcp/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && \
+    [ -n "$V" ] && \
+    echo "Installing gitea-mcp ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://gitea.com/gitea/gitea-mcp/releases/download/v${V}/gitea-mcp_Linux_${ARCH}.tar.gz" \
+    | tar -xz -C /usr/local/bin/ gitea-mcp && \
+    chmod +x /usr/local/bin/gitea-mcp && \
+    gitea-mcp --version
+
+# Set locale — generate common UTF-8 locales (override via LANG/LC_ALL env vars)
+RUN sed -i -E '/(en_US|en_GB|sv_SE|da_DK|nb_NO|fi_FI|de_DE|fr_FR|es_ES|it_IT|pt_BR|nl_NL|pl_PL|ja_JP|ko_KR|zh_CN)\.UTF-8/s/^# //g' /etc/locale.gen && locale-gen
+ENV LANG=en_US.UTF-8
+ENV LANGUAGE=en_US:en
+ENV LC_ALL=en_US.UTF-8
+ENV EDITOR=nvim
+ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
+
+# ── Node.js (required for opencode/pi/omos at variant build + MCP servers) ──
+ARG NODE_VERSION=22
+RUN curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \
+    apt-get install -y --no-install-recommends nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
+# ── AWS CLI v2 (for SSO/Bedrock authentication) ─────────────────────
+RUN ARCH=$(case "${TARGETARCH}" in \
+      amd64) echo "x86_64" ;; \
+      arm64) echo "aarch64" ;; \
+      *) echo "x86_64" ;; \
+    esac) && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://awscli.amazonaws.com/awscli-exe-linux-${ARCH}.zip" -o /tmp/awscli.zip && \
+    unzip -q /tmp/awscli.zip -d /tmp && \
+    /tmp/aws/install && \
+    rm -rf /tmp/aws /tmp/awscli.zip && \
+     aws --version
+
+# ── Non-root user ────────────────────────────────────────────────────
+ARG USER_NAME=developer
+ARG USER_UID=1000
+ARG USER_GID=1000
+
+RUN groupadd --gid ${USER_GID} ${USER_NAME} && \
+    useradd --uid ${USER_UID} --gid ${USER_GID} -m -s /bin/bash ${USER_NAME} && \
+    echo "${USER_NAME} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/${USER_NAME}
+
+# Create standard directories
+RUN mkdir -p /workspace \
+    /home/${USER_NAME}/.config/opencode/skills \
+    /home/${USER_NAME}/.pi/agent/extensions \
+    /home/${USER_NAME}/.agents/skills \
+    /home/${USER_NAME}/.local/share/opencode \
+    /home/${USER_NAME}/.cache/bash \
+    /home/${USER_NAME}/.ssh && \
+    chown -R ${USER_NAME}:${USER_NAME} /workspace /home/${USER_NAME}
+
+# ── Pre-warm chromadb embedding model ──────────────────────────────
+# Runs as gosu developer so Path.home() resolves correctly. Uses
+# the mempalace venv's python, which is the only one that has
+# chromadb importable (system python3 cannot reach the isolated venv).
+RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
+      gosu ${USER_NAME} /opt/uv-tools/mempalace/bin/python -c "\
+from chromadb.utils.embedding_functions import ONNXMiniLM_L6_V2; \
+ef = ONNXMiniLM_L6_V2(); \
+_ = ef(['warmup']); \
+print('chromadb embedding model warmed: all-MiniLM-L6-v2')" && \
+      ls -lh /home/${USER_NAME}/.cache/chroma/onnx_models/all-MiniLM-L6-v2/ ; \
+    fi
+
+# ── User-writable npm global prefix on the devbox-pi-config volume ──
+# By default npm's global prefix is /usr (writable only by root) so any
+# `pi install npm:<pkg>` or `npm install -g <pkg>` invoked by the
+# developer user would EACCES. Pointing the prefix into ~/.pi places
+# user-installed packages on the named volume, which means they survive
+# container recreation AND image rebuilds.
+#
+# IMPORTANT: in this split-build layout the variant Dockerfile inherits
+# this prefix at build time. To keep the baked binaries on /usr (so the
+# ~/.pi volume mount doesn't shadow them), the variant Dockerfile MUST
+# run each `npm install -g` with NPM_CONFIG_PREFIX=/usr in the per-RUN
+# environment. See Dockerfile.variant.
+ENV NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global
+ENV PATH="/home/${USER_NAME}/.pi/npm-global/bin:${PATH}"
+
+# ── Shell defaults (bash history, aliases, readline) ─────────────────
+RUN mkdir -p /etc/skel-devbox
+COPY rootfs/home/developer/.bash_aliases /etc/skel-devbox/.bash_aliases
+COPY rootfs/home/developer/.inputrc      /etc/skel-devbox/.inputrc
+
+# ── Entrypoint ────────────────────────────────────────────────────────
+COPY rootfs/usr/local/lib/opencode-devbox/ /usr/local/lib/opencode-devbox/
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+COPY entrypoint-user.sh /usr/local/bin/entrypoint-user.sh
+RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint-user.sh \
+    /usr/local/lib/opencode-devbox/*.py
+
+# Start as root — entrypoint adjusts UID/GID then drops to developer
+WORKDIR /workspace
+
+ENTRYPOINT ["entrypoint.sh"]
+CMD ["bash", "-l"]

Dockerfile.variant

@@ -0,0 +1,103 @@
+# opencode-devbox — variant image
+#
+# FROMs a base-<hash> image produced by Dockerfile.base and adds only
+# the variant-specific tools (opencode, pi, oh-my-opencode-slim, Go).
+#
+# The four published variants are produced from THIS Dockerfile by
+# varying build args:
+#
+#   variant            INSTALL_OPENCODE  INSTALL_OMOS  INSTALL_PI
+#   ─────────────────  ────────────────  ────────────  ──────────
+#   base               true              false         false
+#   omos               true              true          false
+#   with-pi            true              false         true
+#   omos-with-pi       true              true          true
+#
+# Pass `--build-arg BASE_IMAGE=<repo>:base-<hash>` to select the base.
+# The CI workflow computes the base hash from Dockerfile.base + rootfs/
+# + entrypoint*.sh and feeds it in.
+#
+# IMPORTANT: the base image sets NPM_CONFIG_PREFIX to
+# /home/developer/.pi/npm-global so runtime `pi install npm:...` and
+# `npm install -g` by the developer user lands on the named volume.
+# At BUILD time we want the baked binaries on /usr so they survive the
+# volume mount. Each `npm install -g` below therefore prefixes the
+# command with `NPM_CONFIG_PREFIX=/usr`.
+
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+
+ARG TARGETARCH
+ARG USER_NAME=developer
+
+# ── Install opencode via npm ─────────────────────────────────────────
+ARG INSTALL_OPENCODE=true
+ARG OPENCODE_VERSION=1.14.41
+RUN if [ "${INSTALL_OPENCODE}" = "true" ]; then \
+      NPM_CONFIG_PREFIX=/usr npm install -g opencode-ai@${OPENCODE_VERSION} && \
+      opencode --version ; \
+    fi
+
+# ── Optional: pi coding-agent ────────────────────────────────────────
+# pi-toolkit and pi-extensions are cloned into /opt/. entrypoint-user.sh
+# runs each repo's install.sh on container start so symlinks land under
+# ~/.pi/agent/ on the named volume.
+ARG INSTALL_PI=false
+ARG PI_VERSION=latest
+ARG PI_TOOLKIT_REF=main
+ARG PI_EXTENSIONS_REF=main
+RUN if [ "${INSTALL_PI}" = "true" ]; then \
+      if [ "${PI_VERSION}" = "latest" ]; then \
+        NPM_CONFIG_PREFIX=/usr npm install -g @mariozechner/pi-coding-agent ; \
+      else \
+        NPM_CONFIG_PREFIX=/usr npm install -g @mariozechner/pi-coding-agent@${PI_VERSION} ; \
+      fi && \
+      pi --version && \
+      git clone --depth 1 --branch "${PI_TOOLKIT_REF}" \
+        https://gitea.jordbo.se/joakimp/pi-toolkit.git /opt/pi-toolkit && \
+      git clone --depth 1 --branch "${PI_EXTENSIONS_REF}" \
+        https://gitea.jordbo.se/joakimp/pi-extensions.git /opt/pi-extensions && \
+      echo "pi-toolkit at $(cd /opt/pi-toolkit && git rev-parse --short HEAD)" && \
+      echo "pi-extensions at $(cd /opt/pi-extensions && git rev-parse --short HEAD)" ; \
+    fi
+
+# ── Optional: Go ─────────────────────────────────────────────────────
+ARG INSTALL_GO=false
+ARG GO_VERSION=latest
+RUN if [ "${INSTALL_GO}" = "true" ]; then \
+      GOARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+      V="${GO_VERSION}" && \
+      if [ "$V" = "latest" ]; then \
+        V=$(curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://go.dev/dl/?mode=json" | \
+            awk -F'"' '/"version":/ { sub(/^go/,"",$4); print $4; exit }'); \
+      fi && \
+      [ -n "$V" ] && \
+      echo "Installing Go ${V}" && \
+      curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://go.dev/dl/go${V}.linux-${GOARCH}.tar.gz" | tar -C /usr/local -xz && \
+      ln -s /usr/local/go/bin/go /usr/local/bin/go && \
+      ln -s /usr/local/go/bin/gofmt /usr/local/bin/gofmt; \
+    fi
+
+# ── Optional: oh-my-opencode-slim (multi-agent orchestration) ────────
+# Installs Bun runtime and the oh-my-opencode-slim npm package.
+ARG INSTALL_OMOS=false
+ARG OMOS_VERSION=latest
+RUN if [ "${INSTALL_OMOS}" = "true" ]; then \
+      ARCH=$(uname -m) && \
+      if [ "$ARCH" = "x86_64" ]; then \
+        BUN_ARCH="x64-baseline"; \
+      elif [ "$ARCH" = "aarch64" ]; then \
+        BUN_ARCH="aarch64"; \
+      fi && \
+      curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/oven-sh/bun/releases/latest/download/bun-linux-${BUN_ARCH}.zip" -o /tmp/bun.zip && \
+      unzip -o /tmp/bun.zip -d /tmp/bun && \
+      mv /tmp/bun/bun-linux-${BUN_ARCH}/bun /usr/local/bin/bun && \
+      chmod +x /usr/local/bin/bun && \
+      ln -sf bun /usr/local/bin/bunx && \
+      rm -rf /tmp/bun /tmp/bun.zip && \
+      bun --version && \
+      test -L /usr/local/bin/bunx && \
+      NPM_CONFIG_PREFIX=/usr npm install -g oh-my-opencode-slim@${OMOS_VERSION}; \
+    fi
+
+# WORKDIR / ENTRYPOINT / CMD inherited from base.

README.md

@@ -27,19 +27,30 @@ docker compose run --rm devbox
 
 ## Features
 
-- **Debian bookworm** base — glibc, full PTY/terminal support
+- **Debian trixie** base — glibc, full PTY/terminal support
 - **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
 - **Host filesystem access** — bind mount any directory as `/workspace`
 - **SSH key forwarding** — git push/pull to private repos
 - **MCP server support** — Node.js included for `npx`-based MCP servers
 - **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
-- **Optional runtimes** — Python, Go via build args (Node.js always included — required for opencode v1.x)
+- **Python via uv** — `uv` package manager included; install Python on demand with `uv python install`
+- **Rust via rustup** — `rustup-init` included; bootstrap Rust on demand with `rustup-init -y`
+- **Optional runtimes** — Python (apt), Go via build args (Node.js always included — required for opencode v1.x)
 - **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
 - **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
 - **Multi-arch** — amd64 and arm64
 
 ## Usage
 
+### Prerequisites
+
+Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
+
+```bash
+# Required: workspace for your projects
+mkdir -p ~/projects
+```
+
 ### Connecting to the container
 
 From your laptop, SSH into the remote server where Docker is running, then start the container:
@@ -103,30 +114,204 @@ docker compose exec -u developer devbox aws --version
 | `SSH_KEY_PATH` | Host SSH key directory | `~/.ssh` |
 | `USER_UID` | Override container user UID | Auto-detect from `/workspace` |
 | `USER_GID` | Override container user GID | Auto-detect from `/workspace` |
+| `LANG` | System locale | `en_US.UTF-8` |
+| `LANGUAGE` | Language priority list | `en_US:en` |
+| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
+| `EDITOR` | Default text editor | `nvim` |
 | `ENABLE_OMOS` | Enable oh-my-opencode-slim multi-agent orchestration | `false` |
 | `OMOS_TMUX` | Enable tmux pane integration for OMOS | `false` |
 | `OMOS_SKILLS` | Install OMOS recommended skills on first run | `true` |
 | `OMOS_RESET` | Force regenerate OMOS config on next start | `false` |
+| `SKILLSET_CONTAINER_PATH` | Path to skillset repo inside container (for auto-deploy when not at /workspace/skillset) | Auto-detect |
 
 ### Custom opencode config
 
-Mount your own `opencode.json` for full control (MCP servers, custom models, etc.):
+Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. All changes to `opencode.jsonc`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation.
+
+When an existing `opencode.jsonc` is found in the volume, the `OPENCODE_PROVIDER` auto-config is skipped.
+
+**Alternative: host bind-mount** — if you specifically want to share config from the host (e.g. to version-control it or sync across machines), replace the named volume with a bind mount:
 
 ```yaml
 volumes:
-  - ./my-opencode.json:/home/developer/.config/opencode/opencode.json:ro
+  - ~/.config/opencode:/home/developer/.config/opencode
 ```
 
+> **Portability note:** The mounted config runs inside a Linux container. Any absolute paths inside `opencode.jsonc` (for example, host-specific `plugin` entries like `file:///usr/local/lib/node_modules/...` or `file:///opt/homebrew/...`) will not resolve inside the container. Prefer bare package specifiers (e.g. `"oh-my-opencode-slim"`) that resolve via `node_modules` lookup, which works on both macOS and Linux hosts.
+
 ### Custom skills
 
-Mount your host's opencode skills into the container:
+Skills are deployed automatically from a skillset repo on container start. The entrypoint detects the skillset location in this order:
+
+1. `SKILLSET_CONTAINER_PATH` env var (explicit path to skillset repo inside container)
+2. `~/skillset` mount (if present)
+3. `/workspace/skillset` fallback (if your workspace contains a `skillset/` directory)
+
+When a skillset repo is detected, its skills are symlinked into `~/.agents/skills/` automatically. No manual configuration needed.
+
+> **Warning:** Do not bind-mount a host `~/.agents/skills` directory directly into the container. This conflicts with the symlink-based auto-deploy mechanism and causes broken skill references.
+
+### Neovim configuration
+
+The image includes neovim 0.12 with `EDITOR=nvim` set by default. To use your own neovim config (and have plugins auto-install via lazy.nvim on first start), mount it from the host:
 
 ```yaml
 volumes:
-  - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
-  - ~/.agents/skills:/home/developer/.agents/skills:ro
+  - ~/.config/nvim:/home/developer/.config/nvim:ro
 ```
 
+### Python development with uv
+
+The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
+
+```bash
+# Python 3.13 is available out of the box
+python3 --version
+
+# Use uv for package management
+uv venv
+uv pip install -r requirements.txt
+
+# Or use uv's project workflow (reads pyproject.toml)
+uv sync
+
+# Run a Python script
+uv run python script.py
+
+# Install standalone Python tools
+uvx ruff check .
+
+# Install a newer Python version (persists with devbox-uv volume)
+uv python install 3.14
+```
+
+Python installations are stored in `~/.local/share/uv/`. To persist them across container restarts, add the `devbox-uv` named volume to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-uv:/home/developer/.local/share/uv
+
+volumes:
+  devbox-uv:
+```
+
+Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
+
+### Rust development with rustup
+
+The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
+
+```bash
+# One-time setup: install Rust toolchain (~300MB, persists with volumes)
+rustup-init -y
+source ~/.cargo/env
+
+# Now use Rust normally
+cargo new my-project
+cargo build
+cargo run
+```
+
+To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:
+
+```yaml
+volumes:
+  - devbox-rustup:/home/developer/.rustup
+  - devbox-cargo:/home/developer/.cargo
+
+volumes:
+  devbox-rustup:
+  devbox-cargo:
+```
+
+### JavaScript and TypeScript
+
+The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
+
+```bash
+# Initialize a new project
+npm init -y
+
+# Install dependencies
+npm install
+
+# Run TypeScript (via tsx, ts-node, etc.)
+npx tsx src/index.ts
+
+# Use npx for one-off tools
+npx tsc --init
+```
+
+The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
+
+```bash
+bun init
+bun install
+bun run src/index.ts
+```
+
+Node modules are stored in your project directory under `/workspace` and persist automatically.
+
+### VS Code integration
+
+VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
+
+**Local Docker (Docker running on your workstation):**
+
+1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
+2. Start the container: `docker compose up -d`
+3. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
+
+**Remote Docker (Docker running on a remote server, e.g. via SSH):**
+
+1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions
+2. Connect to the remote host: `Ctrl+Shift+P` → "Remote-SSH: Connect to Host"
+3. On the remote host, start the container: `docker compose up -d`
+4. In VS Code (now connected to the remote): `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container"
+
+VS Code extensions installed inside the container persist as long as the container exists (not removed with `docker compose down`). For persistent extension storage across container recreations, add a named volume:
+
+```yaml
+volumes:
+  - devbox-vscode:/home/developer/.vscode-server
+```
+
+### Multi-user setup
+
+The shared-machine compose file (`docker-compose.shared.yml`) supports two modes:
+
+**Own-account mode** (each user has their own OS login — the common case):
+Leave `SIGNUM` unset in `.env`. The project name defaults to `devbox-$USER`, so each OS user automatically gets isolated container names and named volumes with zero configuration.
+
+**Shared-account mode** (everyone logs in as the same OS user, e.g. `garage`):
+Each user sets `SIGNUM=<unique-id>` in `.env` to get isolation.
+
+Setup per user:
+
+```bash
+# Replace <signum> with your username/identifier
+mkdir -p ~/<signum>/opencode-devbox
+cd ~/<signum>/opencode-devbox
+
+# Copy the shared-machine compose and env files
+cp /path/to/opencode-devbox/docker-compose.shared.yml docker-compose.yml
+cp /path/to/opencode-devbox/.env.shared.example .env
+
+# Edit .env — set SIGNUM only if you're in shared-account mode
+vim .env
+
+# Start
+docker compose up -d
+docker compose exec -u developer devbox opencode
+```
+
+Each user's container, config, and named volumes are fully isolated:
+- Container name: `devbox-<signum>` (or `devbox-$USER` in own-account mode)
+- Named volumes: prefixed with the project name (`devbox-<signum>_devbox-data`, etc.) — the Docker daemon is system-wide, so directory-name prefixing alone is NOT sufficient for isolation
+- Opencode config: persisted via per-user named volume (`devbox-<signum>_devbox-opencode-config`)
+
+See `docker-compose.shared.yml` and `.env.shared.example` for the full configuration.
+
 ### Rebuilding the Image
 
 `docker compose run` and `docker compose up` use the existing image — they **do not rebuild** when you change the Dockerfile or build args (e.g. updating `OPENCODE_VERSION`). Rebuild explicitly:
@@ -142,19 +327,29 @@ docker compose run --rm --build devbox
 
 ### Build Args
 
-Enable optional language runtimes or pin a specific opencode version:
+Enable optional language runtimes, pin a specific opencode version, or lock any of the tooling components:
 
 ```bash
-docker compose build --build-arg INSTALL_PYTHON=true --build-arg INSTALL_GO=true
+docker compose build --build-arg INSTALL_GO=true
 docker compose build --build-arg OPENCODE_VERSION=1.5.0
+docker compose build --build-arg NVIM_VERSION=0.12.1   # pin to a specific version
 ```
 
 | Arg | Default | Description |
 |---|---|---|
-| `INSTALL_PYTHON` | `false` | Python 3 + pip + venv |
-| `INSTALL_GO` | `false` | Go toolchain |
-| `INSTALL_OMOS` | `false` | [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration (installs Bun, tmux, and plugin) |
-| `OMOS_VERSION` | `latest` | Pin a specific oh-my-opencode-slim version |
+| `INSTALL_GO` | `false` | Go toolchain (resolves latest stable from go.dev when `GO_VERSION=latest`) |
+| `INSTALL_MEMPALACE` | `true` | [MemPalace](https://github.com/MemPalace/mempalace) local AI memory system (~300 MB — disable to shrink image if you don't need MCP memory) |
+| `INSTALL_MEMPALACE_TOOLKIT` | `true` | [mempalace-toolkit](https://gitea.jordbo.se/joakimp/mempalace-toolkit) bash wrappers (`mempalace-session`, `mempalace-docs`). Cloned at build time from `MEMPALACE_TOOLKIT_REF` (default `main`). Requires `INSTALL_MEMPALACE=true`. |
+| `INSTALL_OMOS` | `false` | [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration (installs Bun and plugin) |
+| `INSTALL_OPENCODE` | `true` | Install opencode. Set `false` to build a pi-only image (still includes Bun if `INSTALL_OMOS=true`; for a fully stripped pi-only image see the `pi-devbox` repo). |
+| `INSTALL_PI` | `false` | Install [pi](https://github.com/mariozechner/pi-coding-agent) as alternative/complementary harness. Both clones [pi-toolkit](https://gitea.jordbo.se/joakimp/pi-toolkit) (~5 MB) and [pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions) (~1 MB) into `/opt/`; entrypoint deploys them on container start. ~150 MB total image growth. |
+| `PI_VERSION` | `latest` | npm version of `@mariozechner/pi-coding-agent`. Floats by default (image rebuild = pi update). |
+| `PI_TOOLKIT_REF`, `PI_EXTENSIONS_REF` | `main` | Git refs for the toolkit/extensions clones. Pin to a tag/commit for reproducibility. |
+| `OPENCODE_VERSION` | *(pinned per release)* | opencode npm version. Drives the image tag and is intentionally not floated. |
+| `NODE_VERSION` | `22` | Node.js major version. Pinned to protect against upstream breaking changes across majors. |
+| `GOSU_VERSION`, `FZF_VERSION`, `GIT_LFS_VERSION`, `NVIM_VERSION`, `BAT_VERSION`, `EZA_VERSION`, `ZOXIDE_VERSION`, `UV_VERSION`, `GITEA_MCP_VERSION`, `GO_VERSION`, `OMOS_VERSION` | `latest` | All GitHub/Gitea/go.dev-hosted binaries resolve to the newest upstream release at build time. Override with a specific version to pin. Resolved versions are logged in CI output. |
+
+> **Reproducibility note:** With `latest` defaults, two builds of the same `v{opencode}` tag may embed different tool versions if upstream releases have happened in between. This is intentional — it means every rebuild picks up upstream CVE fixes automatically. If you need a bit-for-bit reproducible build, pass explicit `*_VERSION` args. The CI smoke test logs the resolved versions for every release build.
 
 ## oh-my-opencode-slim (Multi-Agent Orchestration)
 
@@ -170,7 +365,7 @@ A pre-built OMOS image is available on Docker Hub as `joakimp/opencode-devbox:la
 docker compose build --build-arg INSTALL_OMOS=true
 ```
 
-This installs Bun, tmux, and the oh-my-opencode-slim package into the image.
+This installs Bun and the oh-my-opencode-slim package into the image.
 
 **2. Enable in `.env`:**
 
@@ -191,20 +386,15 @@ On first start, the entrypoint runs the oh-my-opencode-slim installer in non-int
 | Variable | Default | Description |
 |---|---|---|
 | `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
-| `OMOS_TMUX` | `false` | Enable tmux pane integration (tmux is included with `INSTALL_OMOS`) |
+| `OMOS_TMUX` | `false` | Enable tmux pane integration (tmux is included in the base image) |
 | `OMOS_SKILLS` | `true` | Install recommended skills (simplify, agent-browser, cartography) |
 | `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config) |
 
 ### Custom Configuration
 
-You can mount your own oh-my-opencode-slim config instead of using the auto-generated one:
+If you mount the opencode config directory (see Custom opencode config above), the `oh-my-opencode-slim.json` file is included and persists across restarts. Edit it directly to control which models power each agent, fallback chains, council setup, and more.
 
-```yaml
-volumes:
-  - ./oh-my-opencode-slim.json:/home/developer/.config/opencode/oh-my-opencode-slim.json:ro
-```
-
-The config file controls which models power each agent, fallback chains, council setup, and more. See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
+See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
 
 ### Verifying Agents
 
@@ -216,6 +406,79 @@ ping all agents
 
 All six agents should respond if your provider authentication is working.
 
+## pi (alternative/complementary harness)
+
+[pi](https://github.com/mariozechner/pi-coding-agent) is a lightweight TUI coding-agent that can run alongside opencode in the same container. Both harnesses share the mempalace install and palace data — wing/diary entries created by one are visible to the other.
+
+### Setup
+
+Pre-built pi-enabled images are available on Docker Hub as `joakimp/opencode-devbox:latest-with-pi` (base + pi) and `joakimp/opencode-devbox:latest-omos-with-pi` (OMOS + pi). Pulling one of those tags is the fastest path. Alternatively, build from source:
+
+### Build
+
+```bash
+docker compose build --build-arg INSTALL_PI=true
+# Or: pin a pi version
+docker compose build --build-arg INSTALL_PI=true --build-arg PI_VERSION=0.73.0
+# Or: pi-only image (no opencode, smaller)
+docker compose build --build-arg INSTALL_PI=true --build-arg INSTALL_OPENCODE=false
+```
+
+### Run
+
+The default `compose run --rm devbox` invocation drops to a login bash so you can choose:
+
+```bash
+docker compose run --rm devbox       # bash, then `pi` or `opencode` or `aws sso login`
+docker compose run --rm devbox pi     # launch pi directly
+docker compose run --rm devbox opencode
+```
+
+For an attached `compose up -d` container, both harnesses are reachable via `compose exec`:
+
+```bash
+docker compose exec -u developer devbox pi
+docker compose exec -u developer devbox opencode
+docker compose exec -u developer devbox bash
+```
+
+### What gets installed
+
+- **`pi` CLI** — npm-installed globally at build time. Version pinned by `PI_VERSION`.
+- **pi-toolkit** — keybindings.json (mosh/tmux newline fixes), pi-env.zsh (AWS env loader), settings.json template. Cloned to `/opt/pi-toolkit`; deployed to `~/.pi/agent/` on first container start.
+- **pi-extensions** — 7 extensions, cloned to `/opt/pi-extensions` and symlinked into `~/.pi/agent/extensions/`:
+  - `confirm-destructive` — confirm-prompt before dangerous bash commands and session actions.
+  - `ext-toggle` — `/ext` slash command to list and enable/disable extensions at runtime (rename-to-disable; survives `/reload`).
+  - `git-checkpoint` — per-turn `git stash` checkpoint, restorable on `/fork`.
+  - `mcp-loader` — generic MCP server loader. Reads an `mcp` block from `~/.pi/agent/settings.json` (same shape as opencode and Claude Desktop) and connects to each declared server, exposing the tools as native pi tools. Supports both **local stdio** subprocesses (`uvx mcp-searxng`, `gitea-mcp`, …) and **remote streamable-HTTP** servers per MCP spec 2025-03-26 (e.g. `https://mcp.context7.com/mcp`). Adds a `/mcp` slash command for runtime status / toggle (same UX as `/ext`). See [`pi-extensions/AGENTS.md`](https://gitea.jordbo.se/joakimp/pi-extensions/src/branch/main/AGENTS.md) for transport details and the `headers` config for auth tokens.
+  - `notify` — native terminal notification when the agent finishes.
+  - `ssh-controlmaster` — transparent SSH remote execution via persistent ControlMaster socket (when pi is launched with `--ssh user@host`).
+  - `todo` — `todo` tool for the agent + `/todos` for the user.
+- **mempalace bridge** — separate `mempalace.ts` extension symlinked from the cloned `mempalace-toolkit`. Provides pi's MCP tools for palace search/diary/knowledge-graph with bespoke agent-identity injection from `$MEMPALACE_AGENT_NAME`. Coexists with `mcp-loader` rather than replacing it — don't list `mempalace` in settings.json's `mcp` block too, or you'll get duplicate tool registrations.
+- **MCP servers (none baked in beyond mempalace)** — the loader registers nothing by default. Add servers by editing `~/.pi/agent/settings.json` and `/reload`. Examples (mcp-searxng for web search, context7 for live library docs) are in the `pi-extensions` README.
+
+### Persistence
+
+`~/.pi/` is mounted on the `devbox-pi-config` named volume. Everything below survives container recreate **and** image rebuilds:
+
+- `~/.pi/agent/settings.json` (provider/model, theme selection, the `mcp` block, and the `packages` array tracking installed pi packages).
+- `~/.pi/agent/extensions/` (hand-placed extensions and the symlinks deployed by `pi-extensions/install.sh`).
+- `~/.pi/agent/sessions/`, `~/.pi/agent/auth.json`.
+- `~/.pi/agent/git/<host>/<path>/` (pi packages installed via `pi install git:...`).
+- `~/.pi/npm-global/` (pi packages installed via `pi install npm:...`, plus any `npm install -g` invoked as the `developer` user). `NPM_CONFIG_PREFIX` is pre-set in the image, the prefix's `bin/` is on `PATH`, and the directory itself lives on the volume — so user-installed themes, skills, and extensions survive everything short of `docker compose down -v`.
+
+The **baked** pi binary (and pi-toolkit / pi-extensions repos under `/opt/`) live on the image filesystem, not the volume. Image rebuild is the upgrade path for those — same contract as `OPENCODE_VERSION`. If you `npm install -g @mariozechner/pi-coding-agent` yourself, the user-installed copy on the volume wins via `PATH` order and survives image rebuilds.
+
+### Configuration
+
+The entrypoint copies `pi-toolkit/settings.example.json` to `~/.pi/agent/settings.json` on first start. Edit it to set provider/model:
+
+```bash
+docker compose exec -u developer devbox $EDITOR ~/.pi/agent/settings.json
+```
+
+The AWS env loader (`pi-env.zsh`) reads `~/.config/pi/.env` if you bind-mount one; otherwise pi uses container env vars passed via `.env`.
+
 ## AWS Bedrock Authentication
 
 When using AWS Bedrock as your LLM provider, you need:
@@ -264,6 +527,179 @@ The `--use-device-code` flag outputs a URL and short code instead of trying to o
 
 SSO sessions typically last 8–12 hours before requiring re-authentication. Since `~/.aws` is mounted from the host, tokens persist across container restarts.
 
+## MemPalace — persistent AI memory
+
+The image includes [MemPalace](https://github.com/MemPalace/mempalace), a local-first AI memory system that stores conversation history verbatim and retrieves it via semantic search. Nothing leaves your machine.
+
+> MemPalace adds ~300 MB to the image (chromadb, embedding model deps). If you don't use it, rebuild with `--build-arg INSTALL_MEMPALACE=false` to shrink the image.
+
+### Enabling persistence
+
+Uncomment the palace volume in `docker-compose.yml`:
+
+```yaml
+- devbox-palace:/home/developer/.mempalace
+```
+
+Without the volume, palace data lives in the container's writable layer and is lost on `--force-recreate`.
+
+### MCP integration with opencode
+
+Add mempalace as an MCP server in your `opencode.jsonc` (inside `~/.config/opencode/`):
+
+```json
+{
+  "mcp": {
+    "mempalace": {
+      "type": "local",
+      "command": ["mempalace-mcp"]
+    }
+  }
+}
+```
+
+> The image installs mempalace into an isolated `uv tool` venv at `/opt/uv-tools/mempalace/`. `uv tool install` places `mempalace-mcp` on `PATH` as a shim whose shebang points at the venv's Python, so MCP clients can invoke it as a normal binary without worrying about the venv. Do **not** use `["python3", "-m", "mempalace.mcp_server"]` — the system Python cannot import from the uv-managed venv and you'll get `ModuleNotFoundError` / `MCP error -32000: connection closed`.
+
+This gives opencode access to 29 MCP tools for searching memory, querying the knowledge graph, managing wings/rooms/drawers, and agent diaries.
+
+### Basic usage
+
+```bash
+# Mine project files into the palace
+mempalace mine /workspace
+
+# Mine conversation transcripts
+mempalace mine ~/.local/share/opencode/ --mode convos
+
+# Search memory
+mempalace search "why did we switch to eno1"
+
+# Load context for a new session
+mempalace wake-up
+```
+
+Each workspace gets its own isolated "wing" — memories never leak between projects.
+
+### Scheduled mining (mempalace-toolkit)
+
+The image bakes in [mempalace-toolkit](https://gitea.jordbo.se/joakimp/mempalace-toolkit), a small set of bash wrappers that pair with mempalace for two common routines:
+
+```bash
+# Mine opencode session history (reads ~/.local/share/opencode/opencode.db, stages JSONL, mines into wing_conversations)
+mempalace-session
+
+# Mine a project's docs into a dedicated wing
+mempalace-docs /workspace/my-project
+```
+
+Both wrappers are idempotent and dedup-aware — re-running them on unchanged input is a cheap no-op.
+
+For weekly automated runs, the toolkit ships ready-to-use scheduler templates (systemd user timer, launchd user agent, cron) in its [`contrib/`](https://gitea.jordbo.se/joakimp/mempalace-toolkit/src/branch/main/contrib) directory. The `*-devbox` variants are designed for this container: host-side schedulers that `docker exec` into the running opencode-devbox.
+
+Disable the toolkit (keeps mempalace itself) with `--build-arg INSTALL_MEMPALACE_TOOLKIT=false`. Pin to a specific ref with `--build-arg MEMPALACE_TOOLKIT_REF=v0.3.0` once tagged releases exist.
+
+### Storage
+
+Two separate named volumes keep different data classes apart:
+
+- **Palace data** (`~/.mempalace/`): ChromaDB vectors, SQLite knowledge graph, drawers. This is your memory — back it up, treat it as precious. Persists via the `devbox-palace` named volume.
+- **Embedding model cache** (`~/.cache/chroma/`): ONNX model (~79 MB), downloaded automatically on first search. Disposable — blow it away and it re-downloads in ~4 seconds. Persists via the `devbox-chroma-cache` named volume so you don't re-download on every container recreation.
+- **No API keys required** for core functionality (local embeddings via ONNX).
+
+Both volumes are commented out by default in `docker-compose.yml` — uncomment to enable:
+
+```yaml
+- devbox-palace:/home/developer/.mempalace
+- devbox-chroma-cache:/home/developer/.cache/chroma
+```
+
+**Air-gapped environments:** pre-populate the `devbox-chroma-cache` volume with the `all-MiniLM-L6-v2/` model contents. The palace volume needs no pre-population.
+
+## Gitea MCP server
+
+The image includes the [official Gitea MCP server](https://gitea.com/gitea/gitea-mcp) (`gitea-mcp`), providing 50+ MCP tools for interacting with self-hosted Gitea instances — repositories, issues, pull requests, releases, branches, wiki, and Actions.
+
+### Setup
+
+1. Create a Personal Access Token on your Gitea instance (Settings → Applications → Generate Token, scopes: `repo`, `read:user`).
+
+2. Add to your `.env`:
+   ```env
+   GITEA_HOST=https://your-gitea-instance.example.com
+   GITEA_ACCESS_TOKEN=your_token_here
+   ```
+
+3. Enable the gitea MCP server in your `opencode.jsonc`:
+   ```json
+   {
+     "mcp": {
+       "gitea": {
+         "type": "local",
+         "command": ["gitea-mcp", "-t", "stdio", "--host", "{env:GITEA_HOST}"],
+         "environment": {
+           "GITEA_ACCESS_TOKEN": "{env:GITEA_ACCESS_TOKEN}"
+         },
+         "enabled": true
+       }
+     }
+   }
+   ```
+
+The server is installed but disabled by default — it requires authentication to be useful.
+
+## Context7 MCP server
+
+The image auto-registers a [Context7](https://context7.com) MCP server, which provides up-to-date library documentation and code examples to LLMs at query time. This is a remote MCP server at `mcp.context7.com/mcp` — no local binary is needed.
+
+- Auto-registered in the generated `opencode.jsonc` (no manual setup required)
+- Provides documentation for any programming library/framework on demand
+- Requires internet access — useless in air-gapped/offline environments
+
+## Shell defaults
+
+The image ships a baked `.bash_aliases` and `.inputrc` with quality-of-life defaults. On first container start they are copied from `/etc/skel-devbox/` into `/home/developer/` **only if the target file does not already exist** — so host bind-mounts and any version you've customized inside the container are never overwritten on upgrade.
+
+Defaults you get out of the box:
+
+- **Prefix history search** on Up/Down arrows (type `git `, press Up, walk back through prior `git ...` commands only). Ctrl-Up / Ctrl-Down still step through full history.
+- **Persistent history** — `$HISTFILE` points at `~/.cache/bash/history`, backed by the `devbox-shell-history` named volume so history survives container recreation. Timestamps, 100 000 entries, dedup.
+- **Case-insensitive tab completion**, coloured completion lists, `show-all-if-ambiguous`.
+- **Aliases** — `ls`/`ll`/`la` use `eza`, `cat` uses `bat`, `gs`/`gd`/`gl` for git, safe `rm`/`mv`/`cp`.
+- **Integrations** — `zoxide` (`z <fragment>` to jump), `fzf` Ctrl-R / Ctrl-T key bindings.
+- **Prompt marker** — `[devbox]` prefix so it's always obvious you're inside the container.
+
+### Overriding the defaults
+
+**Option A — bind-mount host files.** Uncomment the bind-mount lines in `docker-compose.yml`:
+
+```yaml
+- ~/.bash_aliases:/home/developer/.bash_aliases:ro
+- ~/.inputrc:/home/developer/.inputrc:ro
+```
+
+> **Single-file bind-mount caveat (all platforms):** Docker bind-mounts the file's **inode**, not its path. When editors like vim, nvim, VS Code, or `sed -i` save a file, they write to a temp file and `rename()` it over the original — creating a new inode. The container stays pinned to the old (now unlinked) inode and never sees the update. This is a kernel limitation ([Docker #15793](https://github.com/moby/moby/issues/15793)), not fixable by Docker. Append-only writes (`echo "alias foo=bar" >> file`) are safe because they modify the same inode. **Workaround:** mount the parent directory instead of the single file (e.g. `~/.config/devbox-shell:/home/developer/.config/devbox-shell:ro`) and source files from there.
+
+**Option B — customize inside the container.** Just edit `~/.bash_aliases` or `~/.inputrc` as normal. Pair this with a bind-mount or named volume on the home dir if you want the edits to survive container recreation.
+
+### Restoring or diffing defaults
+
+The skel files remain available inside every container at `/etc/skel-devbox/`. Useful commands:
+
+```bash
+# See what the image currently ships
+cat /etc/skel-devbox/.bash_aliases
+
+# Diff your current config against the upstream defaults
+diff ~/.bash_aliases /etc/skel-devbox/.bash_aliases
+
+# Reset to the baked defaults
+cp /etc/skel-devbox/.bash_aliases ~/.bash_aliases
+
+# …or delete the file and recreate the container — the entrypoint
+# copies from /etc/skel-devbox/ on next start if the target is absent
+rm ~/.bash_aliases
+```
+
 ## Secret Scanning
 
 A [gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook prevents accidentally committing API keys, passwords, or other secrets.
@@ -301,14 +737,14 @@ Host Machine
 ├── ~/.aws             ──bind mount──▶  /home/developer/.aws (Bedrock SSO)
 └── .env               ──env vars───▶  provider config + API keys
 
-Container (Debian bookworm)
+Container (Debian trixie)
 ├── opencode binary
-├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun + tmux)
+├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
 ├── AWS CLI v2 (SSO + Bedrock auth)
-├── git, ssh, ripgrep, fd, jq, curl, fzf
+├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, rustup, make, gcc, g++, rsync
+├── git, git-crypt, age, ssh, ripgrep, fd, fzf, jq, curl, tree
 ├── Node.js (for MCP servers)
 ├── Bun (optional — included with oh-my-opencode-slim)
-├── tmux (optional — included with oh-my-opencode-slim, also useful independently)
 ├── entrypoint.sh (UID adjustment, git config, provider setup)
 └── /workspace ← your code lives here
 ```
@@ -321,10 +757,17 @@ Container (Debian bookworm)
 | `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
 | `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
 | `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
-| `/home/developer/.config/opencode/opencode.json` | Generated by entrypoint | ❌ No | Provider/model config |
-| `/home/developer/.config/opencode/oh-my-opencode-slim.json` | Generated by entrypoint (if OMOS enabled) | ❌ No | Agent/model mappings |
+| `/home/developer/.local/state/opencode` | Named volume `devbox-state` | ✅ Yes | TUI settings (theme, toggles) |
+| `/home/developer/.cache/bash` | Named volume `devbox-shell-history` | ✅ Yes | Bash history (`$HISTFILE`), survives container recreate |
+| `/home/developer/.local/share/zoxide` | Named volume `devbox-zoxide` | ✅ Yes | Zoxide directory history (`z <fragment>` jump targets) |
+| `/home/developer/.local/share/nvim` | Named volume `devbox-nvim-data` | ✅ Yes | Neovim plugins, Mason LSP installs, Lazy plugin cache |
+| `/home/developer/.local/share/uv` | Named volume `devbox-uv` (if configured) | ✅ Yes | Python installs, uv tool installs |
+| `/home/developer/.rustup` | Named volume `devbox-rustup` (if configured) | ✅ Yes | Rust toolchains |
+| `/home/developer/.cargo` | Named volume `devbox-cargo` (if configured) | ✅ Yes | Cargo binaries, registry cache |
+| `/home/developer/.vscode-server` | Named volume `devbox-vscode` (if configured) | ✅ Yes | VS Code server and extensions |
+| `/home/developer/.config/opencode` | Named volume `devbox-opencode-config` | ✅ Yes | `opencode.jsonc`, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
 
-**opencode config** (`opencode.json`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To use MCP servers or custom settings, mount your own config file (see Custom opencode config above).
+**opencode config** (`opencode.jsonc`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, use the named volume (default) or bind-mount from host (see Custom opencode config above).
 
 ## License
 

check-versions.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# check-versions.sh — Compare pinned versions in Dockerfile against latest releases
+# Run before tagging a release to see what can be bumped.
+set -euo pipefail
+
+BOLD="\033[1m"; DIM="\033[2m"; GREEN="\033[32m"; YELLOW="\033[33m"; RESET="\033[0m"
+
+DOCKERFILE="${1:-Dockerfile}"
+
+if [[ ! -f "$DOCKERFILE" ]]; then
+  echo "Usage: $0 [Dockerfile]"
+  exit 1
+fi
+
+get_pinned() {
+  grep "^ARG $1=" "$DOCKERFILE" | head -1 | cut -d= -f2
+}
+
+get_latest_github() {
+  local repo="$1"
+  local tag
+  tag=$(curl -s "https://api.github.com/repos/${repo}/releases/latest" | jq -r '.tag_name // empty')
+  # Strip leading 'v' if present
+  echo "${tag#v}"
+}
+
+get_latest_go() {
+  curl -s "https://go.dev/dl/?mode=json" | jq -r '.[0].version' | sed 's/^go//'
+}
+
+get_latest_npm() {
+  npm view "$1" version 2>/dev/null
+}
+
+check() {
+  local name="$1" current="$2" latest="$3"
+  if [[ -z "$latest" ]]; then
+    printf "  ${DIM}%-20s %-12s  (could not check)${RESET}\n" "$name" "$current"
+  elif [[ "$current" == "$latest" ]]; then
+    printf "  ${GREEN}%-20s %-12s  ✓ up to date${RESET}\n" "$name" "$current"
+  else
+    printf "  ${YELLOW}${BOLD}%-20s %-12s  → %s available${RESET}\n" "$name" "$current" "$latest"
+  fi
+}
+
+echo ""
+echo -e "${BOLD}Version check for $DOCKERFILE${RESET}"
+echo ""
+
+# GitHub-sourced binaries
+check "opencode"  "$(get_pinned OPENCODE_VERSION)" "$(get_latest_npm opencode-ai)"
+check "gosu"      "$(get_pinned GOSU_VERSION)"      "$(get_latest_github tianon/gosu)"
+check "fzf"       "$(get_pinned FZF_VERSION)"        "$(get_latest_github junegunn/fzf)"
+check "git-lfs"   "$(get_pinned GIT_LFS_VERSION)"    "$(get_latest_github git-lfs/git-lfs)"
+check "neovim"    "$(get_pinned NVIM_VERSION)"        "$(get_latest_github neovim/neovim)"
+check "bat"       "$(get_pinned BAT_VERSION)"         "$(get_latest_github sharkdp/bat)"
+check "eza"       "$(get_pinned EZA_VERSION)"         "$(get_latest_github eza-community/eza)"
+check "zoxide"    "$(get_pinned ZOXIDE_VERSION)"      "$(get_latest_github ajeetdsouza/zoxide)"
+check "uv"        "$(get_pinned UV_VERSION)"          "$(get_latest_github astral-sh/uv)"
+check "Go (opt)"  "$(get_pinned GO_VERSION)"          "$(get_latest_go)"
+
+echo ""
+echo -e "${DIM}Node.js uses major version ($(get_pinned NODE_VERSION)) — auto-updates via nodesource.${RESET}"
+echo -e "${DIM}rustup-init uses latest from static.rust-lang.org — no pinned version.${RESET}"
+echo -e "${DIM}Debian apt packages update on each build via apt-get update.${RESET}"
+echo ""

deploy/README.md

@@ -0,0 +1,318 @@
+# Deploy — Host VM setup
+
+Scripts for setting up a fresh Linux VM to host opencode-devbox.
+
+## Files
+
+- **`cloud-init.yml`** — cloud-init user-data template for automated VM provisioning on OpenStack, Proxmox, or any cloud with cloud-init support
+- **`setup-host.sh`** — interactive post-install script for VMs that weren't provisioned with cloud-init
+- **`setup-openstack-secgroup.sh`** — creates an OpenStack security group with the right rules (SSH, mosh, ICMP)
+- **`sync-to-vm.sh`** — syncs local config directories (`~/.aws`, `~/.config/opencode`, etc.) to a remote VM based on which bind mounts are active in its `docker-compose.yml`
+
+## Supported distributions
+
+- **Debian 13 (Trixie)** — recommended (matches opencode-devbox base image)
+- **Ubuntu 24.04 LTS** — also works
+
+Other distributions will need manual adaptation.
+
+## Quick start
+
+### Option 1: Cloud-init (automated)
+
+Customize `cloud-init.yml` — replace the SSH public key and optionally the hostname/timezone. Then use it during VM creation:
+
+- **Proxmox**: attach as cloud-init user-data
+- **OpenStack**: pass via `--user-data` flag (see full example below)
+- **AWS/DigitalOcean/etc**: paste into the "user data" field
+
+#### Full OpenStack example
+
+Cloud-init only handles guest configuration — flavor, image, network, and security group must be specified explicitly at creation time.
+
+> **Note:** Do not use `--key-name` — the SSH key is configured in `cloud-init.yml` under `ssh_authorized_keys` for the `devbox` user. The `--key-name` flag injects into the image's default user (e.g. `debian`), not the `devbox` user created by cloud-init.
+
+```bash
+# List available flavors to choose appropriate sizing
+openstack flavor list
+
+# Create the security group first (one-time, see below)
+./setup-openstack-secgroup.sh
+
+# Basic — boot from default storage
+openstack server create \
+  --flavor c4m8 \
+  --image Debian-13-Trixie \
+  --network my-network \
+  --security-group opencode-devbox \
+  --user-data cloud-init.yml \
+  devbox-vm
+```
+
+If your cloud offers NVMe-backed (performance) volumes, boot from one for faster Docker and build I/O:
+
+```bash
+# Performance — boot from NVMe volume (40GB, preserved on instance deletion)
+openstack server create \
+  --flavor c4m8 \
+  --network my-network \
+  --security-group opencode-devbox \
+  --user-data cloud-init.yml \
+  --block-device source_type=image,uuid=$(openstack image show Debian-13-Trixie -f value -c id),destination_type=volume,volume_size=40,delete_on_termination=false,boot_index=0,volume_type=performance \
+  devbox-vm
+```
+
+> **Note:** The inline `volume_type` parameter requires API microversion 2.67+. If the server goes to ERROR state, check your volume quota (`openstack quota show`) and try creating the volume separately:
+> ```bash
+> openstack volume create --image Debian-13-Trixie --size 40 --type performance --bootable devbox-boot-volume
+> openstack server create --flavor c4m8 --volume devbox-boot-volume --network my-network --security-group opencode-devbox --user-data cloud-init.yml devbox-vm
+> ```
+
+#### Floating IP
+
+OpenStack doesn't support assigning a floating IP at instance creation time — it's a separate step after the VM is active:
+
+```bash
+# Allocate a new floating IP from the external network
+openstack floating ip create <external-network>
+
+# Assign it to the VM
+openstack server add floating ip devbox-vm <floating-ip>
+```
+
+To find your external network name: `openstack network list --external`. If you already have an unassigned floating IP, skip the create step.
+
+The VM boots with Docker installed, firewall configured (or skipped on OpenStack), and your SSH key authorized. Log in as the `devbox` user.
+
+### Console password (optional)
+
+The cloud-init template uses SSH key authentication only — no password is set by default. This is sufficient for normal use since the `devbox` user has passwordless `sudo`.
+
+A password is only needed for:
+
+- **Emergency console access** — logging in via OpenStack Horizon console (noVNC) or Proxmox VNC when SSH is unreachable
+- **`su - devbox`** — switching to the devbox user from another account
+
+To enable console access, uncomment the `chpasswd` block in `cloud-init.yml` before deploying:
+
+```yaml
+chpasswd:
+  expire: false
+  users:
+    - name: devbox
+      password: your-password-here
+      type: text
+```
+
+For an already-running VM, set a password via SSH:
+
+```bash
+sudo passwd devbox
+```
+
+### Option 2: Post-install script (manual)
+
+On a fresh Debian/Ubuntu VM:
+
+```bash
+curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/deploy/setup-host.sh | bash
+```
+
+Or clone and run:
+
+```bash
+git clone https://gitea.jordbo.se/joakimp/opencode-devbox
+cd opencode-devbox/deploy
+./setup-host.sh
+```
+
+## What gets installed
+
+- Docker Engine (from Docker's official apt repo, not distro's `docker.io`)
+- Docker Compose plugin (v2)
+- `tmux`, `mosh`, `git`
+- `ufw` firewall with SSH (22) and mosh (UDP 60000-61000) allowed — **skipped on OpenStack** (detected automatically; use security groups instead)
+- IPv4 DNS preference (works around Docker Hub IPv6 connectivity issues)
+
+## OpenStack security groups
+
+On OpenStack, firewalling is handled by security groups rather than ufw. The `setup-host.sh` script detects OpenStack automatically and skips ufw configuration.
+
+To create the required security group:
+
+```bash
+./setup-openstack-secgroup.sh
+```
+
+This creates a security group named `opencode-devbox` with rules for SSH (TCP 22), mosh (UDP 60000-61000), and ICMP. Apply it to your instance:
+
+```bash
+# New instance
+openstack server create --security-group opencode-devbox ...
+
+# Existing instance
+openstack server add security group <instance-name> opencode-devbox
+```
+
+## VM sizing recommendations
+
+| Use case | vCPU | RAM | Disk |
+|---|---|---|---|
+| Minimum | 2 | 4 GB | 20 GB |
+| Recommended | 4 | 8 GB | 40 GB |
+| Heavy use (Rust/Python builds, multi-project) | 8 | 16 GB | 80 GB |
+
+## After VM setup
+
+If you uncomment any bind mounts in `docker-compose.yml` (e.g. `~/.aws`, `~/.config/opencode`), create the directories first — Docker creates missing bind mount paths as root-owned, which causes permission issues:
+
+```bash
+# Only create directories for mounts you uncomment
+mkdir -p ~/.aws                  # AWS Bedrock SSO
+mkdir -p ~/.config/opencode      # persistent opencode config
+mkdir -p ~/.config/nvim          # custom neovim config
+mkdir -p ~/.agents/skills        # opencode agent skills
+```
+
+Named volumes (`devbox-data`, `devbox-uv`, etc.) are managed by Docker and need no pre-creation.
+
+```bash
+mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+vim .env                                           # configure provider and keys
+vim docker-compose.yml                             # uncomment optional volume mounts
+docker compose up -d
+docker compose exec -u developer devbox opencode
+```
+
+> **AWS Bedrock users:** Uncomment the `~/.aws` volume mount in `docker-compose.yml` before starting. You'll also need to copy your `~/.aws/config` from a machine where SSO is already configured, then authenticate inside the container with `aws sso login`.
+
+### Syncing local config to the VM
+
+After editing `docker-compose.yml` on the VM to uncomment the bind mounts you need, run `sync-to-vm.sh` from your local machine to copy the corresponding directories:
+
+```bash
+./deploy/sync-to-vm.sh devbox-affection
+```
+
+The script reads `docker-compose.yml` on the remote VM, detects which bind mounts are active, and syncs only those directories from your local machine. It also creates the remote directories if they don't exist.
+
+### Upgrading an existing VM to a new release
+
+Each tagged release may add new named volumes or bind-mount lines to `docker-compose.yml`. Pulling a new image via `docker compose pull` grabs the new container behaviour, but compose files on the VM are user-owned and never touched by the image — you have to reconcile them yourself when upgrading across versions.
+
+**Symptom of a missed reconcile:** a new feature quietly doesn't work even though the image is correct. Example from v1.14.19c → v1.14.20: bash history persistence requires the `devbox-shell-history` named volume mounted at `/home/developer/.cache/bash`. The v1.14.20 image writes history to that path either way, but without the volume mount on the VM, writes land in the container's writable layer and vanish on every `--force-recreate`.
+
+**Upgrade ritual:**
+
+```bash
+# On the VM, before recreating the container:
+cd ~/opencode-devbox
+cp docker-compose.yml docker-compose.yml.bak-$(date +%Y%m%d-%H%M%S)
+
+# Compare against the repo version to see what's new:
+#   (from your local checkout)
+scp devbox-affection:~/opencode-devbox/docker-compose.yml /tmp/vm-compose.yml
+diff -u /tmp/vm-compose.yml ~/src/src_local/opencode-devbox/docker-compose.yml
+```
+
+For each new `volumes:` entry or mount line in the repo version that isn't in your VM's file, add it manually — preserving any local customizations you've made (image variant, read/write flags on bind mounts, etc.). Then:
+
+```bash
+docker compose config >/dev/null   # verify YAML still parses
+docker compose up -d --force-recreate
+```
+
+If you maintain the VM's compose file with no local changes, `scp` the repo version over wholesale. If you have customizations (the common case), do the diff-and-merge by hand.
+
+### Shell defaults inside the container
+
+The image ships baked `.bash_aliases` and `.inputrc` in `/etc/skel-devbox/` — quality-of-life defaults (prefix history search on Up/Down arrows, persistent history across container recreates via the `devbox-shell-history` named volume, `[devbox]` prompt marker, sensible aliases). On first container start the entrypoint copies them to `/home/developer/` **only if the target file does not already exist**.
+
+This means:
+
+- Fresh containers get the defaults automatically.
+- If you bind-mount your host's `~/.bash_aliases` / `~/.inputrc` (see the commented lines in `docker-compose.yml`), your host versions win.
+- If you edit the files inside a running container and store them via a home-dir bind-mount or equivalent, subsequent upgrades never overwrite them.
+- To restore the baked defaults any time: `cp /etc/skel-devbox/.bash_aliases ~/` (or delete the file and recreate the container).
+- To diff your current config against what the image ships: `diff ~/.bash_aliases /etc/skel-devbox/.bash_aliases`.
+
+### CI runner maintenance: automatic Docker pruning
+
+Gitea Actions runners accumulate Docker build cache, stale buildkit containers, and unused images over time. Without periodic cleanup, the runner's disk fills up and builds stall during the image-push phase (symptom: `#61 exporting to image` / `pushing layers` hangs indefinitely while buildkit repeatedly re-authenticates with Docker Hub).
+
+Set up two layers of automatic cleanup on the runner host:
+
+**1. Daily cron job** — prunes images, containers, and build cache older than 72 hours:
+
+```bash
+sudo tee /etc/cron.daily/docker-prune <<'EOF'
+#!/bin/sh
+docker system prune -af --filter "until=72h" > /var/log/docker-prune.log 2>&1
+docker builder prune -af --filter "until=72h" >> /var/log/docker-prune.log 2>&1
+EOF
+sudo chmod +x /etc/cron.daily/docker-prune
+```
+
+**2. Docker daemon builder GC** — caps buildkit cache at 10 GB (Docker 23.0+):
+
+Add to `/etc/docker/daemon.json` (create if absent):
+
+```json
+{
+  "builder": {
+    "gc": {
+      "enabled": true,
+      "defaultKeepStorage": "10GB"
+    }
+  }
+}
+```
+
+Then `sudo systemctl restart docker`.
+
+Both are safe to run on a machine that also hosts long-running containers (like opencode-devbox) — `docker system prune` only removes *unused* images and *stopped* containers, never running ones.
+
+### Troubleshooting: SSH hangs or "banner exchange" timeouts
+
+If SSH to the VM intermittently fails with `Connection timed out during banner exchange` or pure TCP connect timeouts — especially after the first few successful connects in a short window — the cause is almost certainly your ISP's CGNAT (Carrier-Grade NAT), not the VM.
+
+**Symptoms**
+
+- First 3–4 SSH connects succeed, then subsequent ones fail hard for 20–30 minutes
+- `ping` to the VM works perfectly throughout (ICMP isn't tracked the same way)
+- `mosh` sessions stay stable once established (UDP, different flow table)
+- Happens on residential ISPs (Tele2, Comhem, Telia, most European consumer broadband)
+- VM-side logs show SSH is idle — the SYNs never reach it
+
+**Cause**
+
+Residential CGNAT boxes keep a per-subscriber TCP flow table with a small concurrent-flow cap (~4) per destination IP. Once exhausted, new SYNs to that destination are silently dropped until old flows age out (typically 20–30 min after TCP close).
+
+**Fix**
+
+Add SSH connection multiplexing on your client so all SSH sessions (interactive, `scp`, `rsync`, scripts) share a single TCP connection to the VM:
+
+```ssh-config
+# ~/.ssh/config
+Host <vm-alias>
+    HostName <vm-ip>
+    User devbox
+    IdentityFile ~/.ssh/id_ed25519
+    ControlMaster auto
+    ControlPath ~/.ssh/cm/%r@%h:%p
+    ControlPersist 4h
+    ServerAliveInterval 30
+    ServerAliveCountMax 6
+```
+
+Then create the socket directory:
+
+```bash
+mkdir -p ~/.ssh/cm && chmod 700 ~/.ssh/cm
+```
+
+All SSH to the VM now multiplexes over a single flow slot, regardless of how many parallel sessions you open. `sync-to-vm.sh` already does this internally for its own rsync/scp calls.
+
+For a more robust long-term fix (especially if you access the VM from multiple hosts), run a WireGuard tunnel on the VM and route SSH through that — UDP bypasses the TCP flow table entirely.

deploy/cloud-init.yml

@@ -0,0 +1,110 @@
+#cloud-config
+# cloud-init template for opencode-devbox host VM
+# Tested on Debian 13 (Trixie) and Ubuntu 24.04
+#
+# Usage:
+#   - Proxmox: attach this file as cloud-init user-data in VM config
+#   - OpenStack: pass as --user-data when creating the instance
+#   - Cloud providers: paste into "user data" field
+#
+# Customize the marked sections before use.
+
+# ── Hostname ─────────────────────────────────────────────────────────
+hostname: devbox
+manage_etc_hosts: true
+
+# ── User ─────────────────────────────────────────────────────────────
+users:
+  - name: devbox
+    groups: sudo, docker
+    shell: /bin/bash
+    sudo: ALL=(ALL) NOPASSWD:ALL
+    ssh_authorized_keys:
+      # CUSTOMIZE: replace with your public SSH key.
+      # This is the only SSH key config needed — do NOT use --key-name with
+      # openstack server create, as that injects into the image's default
+      # user (e.g. debian), not the devbox user defined here.
+      - ssh-ed25519 AAAA... your-key-here
+
+# ── Optional: console password ───────────────────────────────────────
+# Uncomment to set a password for the devbox user. Only needed for
+# emergency access via the OpenStack/Proxmox console (VNC/noVNC).
+# SSH key authentication is used for normal access.
+#
+# chpasswd:
+#   expire: false
+#   users:
+#     - name: devbox
+#       password: your-password-here
+#       type: text
+
+# ── Locale and timezone ──────────────────────────────────────────────
+# en_US.UTF-8 is pre-generated on Debian/Ubuntu and works out of the box.
+# To use a different locale (e.g. sv_SE.UTF-8), add it to the runcmd
+# section before the locale is applied:
+#   - locale-gen sv_SE.UTF-8
+# Then change the locale line below to match.
+locale: en_US.UTF-8
+timezone: Europe/Stockholm
+
+# ── Package installation ─────────────────────────────────────────────
+package_update: true
+package_upgrade: true
+packages:
+  - ca-certificates
+  - curl
+  - gnupg
+  - git
+  - tmux
+  - mosh
+  - rsync
+  - fzf
+  - ripgrep
+  - ufw
+
+# ── Commands to run at first boot ────────────────────────────────────
+runcmd:
+  # Install Docker from official repository
+  - install -m 0755 -d /etc/apt/keyrings
+  - curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
+  - chmod a+r /etc/apt/keyrings/docker.asc
+  - echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo \"$ID\") $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" > /etc/apt/sources.list.d/docker.list
+  - apt-get update
+  - apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+  - usermod -aG docker devbox
+
+  # Firewall — skip on OpenStack (use security groups instead)
+  - |
+    if curl -s --connect-timeout 2 http://169.254.169.254/openstack/ >/dev/null 2>&1; then
+      echo "OpenStack detected — skipping ufw (use security groups instead)"
+    else
+      ufw default deny incoming
+      ufw default allow outgoing
+      ufw allow ssh
+      ufw allow 60000:61000/udp
+      ufw --force enable
+    fi
+
+  # Disable IPv6 preference for Docker (avoids intermittent Docker Hub connectivity issues)
+  - echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+  # Create projects directory for the user
+  - mkdir -p /home/devbox/projects
+  - chown devbox:devbox /home/devbox/projects
+
+# ── Final message ───────────────────────────────────────────────────
+final_message: |
+  opencode-devbox host VM ready.
+
+  Next steps:
+    1. SSH in:      ssh devbox@<this-host>
+    2. Clone your opencode-devbox compose config, or:
+       mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+    3. Edit .env with your provider and keys
+    4. Edit docker-compose.yml to uncomment optional mounts (e.g. ~/.aws for Bedrock)
+    5. docker compose up -d
+    6. docker compose exec -u developer devbox opencode
+
+  Cloud-init run completed in $UPTIME seconds.

deploy/setup-host.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+# setup-host.sh — Post-install script for opencode-devbox host VM
+#
+# Run this on a fresh Debian 13 or Ubuntu 24.04 VM to set up everything
+# needed to run opencode-devbox containers.
+#
+# Usage:
+#   curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/deploy/setup-host.sh | bash
+#
+# Or clone and run:
+#   git clone https://gitea.jordbo.se/joakimp/opencode-devbox
+#   cd opencode-devbox/deploy
+#   ./setup-host.sh
+
+set -euo pipefail
+
+# ── Colors ──────────────────────────────────────────────────────────
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RED="\033[31m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+err()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ── Detect distro ──────────────────────────────────────────────────
+if [[ ! -f /etc/os-release ]]; then
+  err "Cannot detect Linux distribution — /etc/os-release missing"
+  exit 1
+fi
+
+. /etc/os-release
+
+case "$ID" in
+  debian|ubuntu)
+    info "Detected $PRETTY_NAME"
+    ;;
+  *)
+    err "Unsupported distribution: $ID — this script only supports Debian and Ubuntu"
+    exit 1
+    ;;
+esac
+
+# ── Require sudo ────────────────────────────────────────────────────
+if [[ $EUID -eq 0 ]]; then
+  err "Do not run as root — use a regular user with sudo"
+  exit 1
+fi
+
+if ! sudo -n true 2>/dev/null; then
+  warn "This script needs sudo access. You may be prompted for your password."
+fi
+
+# ── Update packages ─────────────────────────────────────────────────
+info "Updating package index..."
+sudo apt-get update -qq
+
+info "Installing base packages..."
+sudo apt-get install -y --no-install-recommends \
+  ca-certificates curl gnupg git tmux mosh rsync fzf ripgrep ufw
+
+# ── Docker ──────────────────────────────────────────────────────────
+if command -v docker &>/dev/null; then
+  ok "Docker already installed ($(docker --version))"
+else
+  info "Installing Docker from official repository..."
+  sudo install -m 0755 -d /etc/apt/keyrings
+  sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
+  sudo chmod a+r /etc/apt/keyrings/docker.asc
+
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | \
+    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+  sudo apt-get update -qq
+  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+
+  ok "Docker installed: $(docker --version)"
+fi
+
+# ── Add user to docker group ────────────────────────────────────────
+if groups | grep -q docker; then
+  ok "User already in docker group"
+else
+  info "Adding $USER to docker group..."
+  sudo usermod -aG docker "$USER"
+  warn "You must log out and back in for docker group to take effect"
+  warn "Or run: newgrp docker"
+fi
+
+# ── Firewall ────────────────────────────────────────────────────────
+# Detect OpenStack — if running on OpenStack, skip ufw (security groups handle firewalling)
+SKIP_UFW=false
+if curl -s --connect-timeout 2 http://169.254.169.254/openstack/ &>/dev/null; then
+  SKIP_UFW=true
+  warn "OpenStack detected — skipping ufw (use security groups instead)"
+  warn "Ensure your security group allows: SSH (22/tcp), mosh (60000-61000/udp)"
+fi
+
+if [[ "$SKIP_UFW" == "false" ]]; then
+  info "Configuring firewall (ufw)..."
+  sudo ufw default deny incoming >/dev/null
+  sudo ufw default allow outgoing >/dev/null
+  sudo ufw allow ssh >/dev/null
+  sudo ufw allow 60000:61000/udp comment 'mosh' >/dev/null
+  if ! sudo ufw status | grep -q "Status: active"; then
+    sudo ufw --force enable
+  fi
+  ok "Firewall active — SSH and mosh allowed"
+fi
+
+# ── IPv4 preference for Docker Hub ──────────────────────────────────
+if ! grep -q 'precedence ::ffff:0:0/96' /etc/gai.conf 2>/dev/null; then
+  info "Setting IPv4 preference in /etc/gai.conf..."
+  echo 'precedence ::ffff:0:0/96  100' | sudo tee -a /etc/gai.conf > /dev/null
+  ok "IPv4 preferred for DNS resolution"
+fi
+
+# ── Create projects directory ───────────────────────────────────────
+if [[ ! -d "$HOME/projects" ]]; then
+  mkdir -p "$HOME/projects"
+  ok "Created ~/projects"
+fi
+
+# ── Done ────────────────────────────────────────────────────────────
+echo ""
+ok "Host setup complete"
+echo ""
+cat <<EOF
+${BOLD}Next steps:${RESET}
+
+  1. If you weren't already in the docker group, log out and back in:
+       exit
+       ssh <your-user>@<this-host>
+
+  2. Set up opencode-devbox:
+       mkdir -p ~/opencode-devbox && cd ~/opencode-devbox
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/docker-compose.yml -o docker-compose.yml
+       curl -sL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.example -o .env
+
+  3. Edit .env with your provider and API keys:
+       vim .env
+
+  4. Start and connect:
+       docker compose up -d
+       docker compose exec -u developer devbox opencode
+
+EOF

deploy/setup-openstack-secgroup.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# setup-openstack-secgroup.sh — Create an OpenStack security group for opencode-devbox
+#
+# Prerequisites:
+#   - OpenStack CLI installed (pip install python-openstackclient)
+#   - Authenticated (source your openrc.sh or clouds.yaml configured)
+#
+# Usage:
+#   ./setup-openstack-secgroup.sh [group-name]
+#
+# Default group name: opencode-devbox
+
+set -euo pipefail
+
+GROUP_NAME="${1:-opencode-devbox}"
+
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+
+if ! command -v openstack &>/dev/null; then
+  echo "Error: openstack CLI not found. Install with: pip install python-openstackclient"
+  exit 1
+fi
+
+# Check if group already exists
+if openstack security group show "$GROUP_NAME" &>/dev/null; then
+  warn "Security group '$GROUP_NAME' already exists — updating rules"
+else
+  info "Creating security group '$GROUP_NAME'..."
+  openstack security group create "$GROUP_NAME" \
+    --description "opencode-devbox: SSH, mosh, HTTPS"
+  ok "Security group created"
+fi
+
+# Add rules (idempotent — OpenStack ignores duplicates)
+info "Adding rules..."
+
+# SSH (TCP 22)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol tcp --dst-port 22 --remote-ip 0.0.0.0/0 \
+  --description "SSH" 2>/dev/null && ok "SSH (TCP 22)" || warn "SSH rule already exists"
+
+# Mosh (UDP 60000-61000)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol udp --dst-port 60000:61000 --remote-ip 0.0.0.0/0 \
+  --description "mosh" 2>/dev/null && ok "mosh (UDP 60000-61000)" || warn "mosh rule already exists"
+
+# ICMP (ping — useful for diagnostics)
+openstack security group rule create "$GROUP_NAME" \
+  --protocol icmp --remote-ip 0.0.0.0/0 \
+  --description "ICMP ping" 2>/dev/null && ok "ICMP ping" || warn "ICMP rule already exists"
+
+echo ""
+ok "Security group '$GROUP_NAME' ready"
+echo ""
+echo -e "${BOLD}Apply to a new instance:${RESET}"
+echo "  openstack server create --security-group $GROUP_NAME ..."
+echo ""
+echo -e "${BOLD}Apply to an existing instance:${RESET}"
+echo "  openstack server add security group <instance-name> $GROUP_NAME"
+echo ""

deploy/sync-to-vm.sh

@@ -0,0 +1,146 @@
+#!/bin/bash
+# sync-to-vm.sh — Copy local config to an opencode-devbox VM
+#
+# Reads docker-compose.yml on the remote VM to detect which bind mounts
+# are active, then syncs the corresponding directories from this machine.
+#
+# Usage:
+#   ./sync-to-vm.sh <ssh-host>
+#
+# Examples:
+#   ./sync-to-vm.sh devbox-affection
+#   ./sync-to-vm.sh devbox@129.192.68.184
+
+set -euo pipefail
+
+# ── Colors ──────────────────────────────────────────────────────────
+BOLD="\033[1m"; GREEN="\033[32m"; YELLOW="\033[33m"; RED="\033[31m"; RESET="\033[0m"
+info()  { echo -e "${BOLD}==>${RESET} $*"; }
+ok()    { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()  { echo -e "${YELLOW}${BOLD}!${RESET} $*"; }
+err()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+# ── Args ────────────────────────────────────────────────────────────
+if [[ $# -lt 1 ]]; then
+  err "Usage: $0 <ssh-host>"
+  echo "  Example: $0 devbox-affection"
+  exit 1
+fi
+
+SSH_HOST="$1"
+REMOTE_COMPOSE="~/opencode-devbox/docker-compose.yml"
+
+# ── SSH multiplexing (reuse one connection for all operations) ──────
+CTRL_SOCKET=$(mktemp -u /tmp/sync-to-vm-XXXXXX)
+SSH_OPTS="-o ControlMaster=auto -o ControlPath=${CTRL_SOCKET} -o ControlPersist=120 -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3"
+
+cleanup() {
+  ssh ${SSH_OPTS} -O exit "$SSH_HOST" 2>/dev/null || true
+  rm -f "$CTRL_SOCKET"
+}
+trap cleanup EXIT
+
+ssh_cmd() {
+  ssh ${SSH_OPTS} "$SSH_HOST" "$@"
+}
+
+# ── Bind mount patterns to detect ──────────────────────────────────
+# Maps: grep pattern → local source → remote destination
+declare -a MOUNT_PATTERNS=(
+  "~/.aws:/home/developer/.aws|$HOME/.aws|~/.aws"
+  "~/.config/opencode:/home/developer/.config/opencode|$HOME/.config/opencode|~/.config/opencode"
+  "~/.config/nvim:/home/developer/.config/nvim|$HOME/.config/nvim|~/.config/nvim"
+  "~/.agents/skills:/home/developer/.agents/skills|$HOME/.agents/skills|~/.agents/skills"
+)
+
+# ── Establish persistent SSH connection ─────────────────────────────
+info "Connecting to ${SSH_HOST}..."
+if ! ssh_cmd true 2>/dev/null; then
+  err "Cannot connect to ${SSH_HOST}"
+  exit 1
+fi
+ok "Connected to ${SSH_HOST}"
+
+# ── Fetch remote docker-compose.yml ─────────────────────────────────
+info "Reading docker-compose.yml from ${SSH_HOST}..."
+REMOTE_COMPOSE_CONTENT=$(ssh_cmd "cat $REMOTE_COMPOSE 2>/dev/null") || {
+  err "Could not read ${REMOTE_COMPOSE} on ${SSH_HOST}"
+  err "Has the VM been set up? Run the post-setup steps first."
+  exit 1
+}
+
+# ── Ensure workspace directory exists on remote ─────────────────────
+REMOTE_ENV="~/opencode-devbox/.env"
+WORKSPACE_PATH=$(ssh_cmd "grep -E '^\s*WORKSPACE_PATH=' $REMOTE_ENV 2>/dev/null | cut -d= -f2- | tr -d '\"'" 2>/dev/null || true)
+if [[ -n "$WORKSPACE_PATH" ]]; then
+  info "Ensuring WORKSPACE_PATH (${WORKSPACE_PATH}) exists on ${SSH_HOST}..."
+  ssh_cmd "mkdir -p ${WORKSPACE_PATH}"
+  ok "Workspace directory ready"
+else
+  # Default from docker-compose.yml is ~/projects or current dir
+  WORKSPACE_PATH=$(echo "$REMOTE_COMPOSE_CONTENT" | grep -oP 'WORKSPACE_PATH:-[^}]+' | sed 's/WORKSPACE_PATH:-//' || true)
+  if [[ -n "$WORKSPACE_PATH" && "$WORKSPACE_PATH" != "." ]]; then
+    info "Ensuring default WORKSPACE_PATH (${WORKSPACE_PATH}) exists on ${SSH_HOST}..."
+    ssh_cmd "mkdir -p ${WORKSPACE_PATH}"
+    ok "Workspace directory ready"
+  fi
+fi
+
+# ── Detect active bind mounts ──────────────────────────────────────
+SYNCED=0
+
+for entry in "${MOUNT_PATTERNS[@]}"; do
+  IFS='|' read -r pattern local_path remote_path <<< "$entry"
+
+  # Check if the mount is uncommented (active) in docker-compose.yml
+  # Match lines that start with optional whitespace and a dash, NOT preceded by #
+  if echo "$REMOTE_COMPOSE_CONTENT" | grep -qE "^\s*-\s+['\"]?${pattern}" 2>/dev/null; then
+    # Mount is active — check if local source exists
+    if [[ ! -d "$local_path" ]]; then
+      warn "Mount active for ${pattern} but ${local_path} does not exist locally — skipping"
+      continue
+    fi
+
+    # Check if directory has content
+    if [[ -z "$(ls -A "$local_path" 2>/dev/null)" ]]; then
+      warn "${local_path} is empty — skipping"
+      continue
+    fi
+
+    info "Syncing ${local_path} → ${SSH_HOST}:${remote_path}"
+
+    # Ensure remote directory exists
+    ssh_cmd "mkdir -p ${remote_path}"
+
+    # Sync with rsync (fall back to scp if rsync unavailable)
+    # Exclude generated/cached content that gets recreated on the remote.
+    # Use -rlptD (archive minus -o -g) so ownership on the remote is set
+    # by the receiving user (devbox). Preserving host UID/GID with -a
+    # tagged files with the pusher's numeric GID, which leaked through
+    # whenever the VM happened to have a matching group (see #group-1001).
+    if command -v rsync &>/dev/null; then
+      rsync -rlptDz --progress \
+        --exclude='node_modules' \
+        --exclude='__pycache__' \
+        --exclude='.venv' \
+        --exclude='*.pyc' \
+        --exclude='cli/cache' \
+        --exclude='sso/cache' \
+        -e "ssh ${SSH_OPTS}" "${local_path}/" "${SSH_HOST}:${remote_path}/"
+    else
+      scp -o "ControlPath=${CTRL_SOCKET}" -r "${local_path}/." "${SSH_HOST}:${remote_path}/"
+    fi
+
+    ok "Synced ${local_path}"
+    SYNCED=$((SYNCED + 1))
+  fi
+done
+
+# ── Summary ─────────────────────────────────────────────────────────
+echo ""
+if [[ $SYNCED -eq 0 ]]; then
+  warn "No active bind mounts detected in remote docker-compose.yml"
+  warn "Uncomment the mounts you need in ${REMOTE_COMPOSE} on the VM, then re-run this script"
+else
+  ok "Synced ${SYNCED} director$([ $SYNCED -eq 1 ] && echo 'y' || echo 'ies') to ${SSH_HOST}"
+fi

docker-compose.shared.yml

@@ -0,0 +1,93 @@
+# opencode-devbox docker-compose for shared machines
+#
+# For machines where multiple users share one OS account (e.g. 'garage').
+# Each user gets isolated config, data, and named volumes by setting
+# SIGNUM in their .env file.
+#
+# Setup per user:
+#   1. mkdir -p ~/<signum>/opencode-devbox && cd ~/<signum>/opencode-devbox
+#   2. cp docker-compose.shared.yml docker-compose.yml
+#   3. cp .env.shared.example .env
+#   4. Edit .env with your signum, provider, keys, etc.
+#   5. mkdir -p ~/<signum>/.config/opencode
+#   6. docker compose up -d
+#
+# Volume isolation: the top-level 'name:' field derives a unique project
+# name per user, which Docker Compose uses as the prefix for all named
+# volumes. Without this, two users whose compose file lives in a directory
+# with the same basename would share volumes — the Docker daemon is
+# system-wide and doesn't scope by OS user.
+#
+# Two modes:
+#   Own-account mode (each user has their own OS login):
+#     Leave SIGNUM unset in .env — it defaults to $USER automatically.
+#   Shared-account mode (everyone logs in as the same OS user):
+#     Set SIGNUM=<unique-id> in .env so each person gets isolated volumes.
+
+name: devbox-${SIGNUM:-${USER}}
+
+services:
+  devbox:
+    image: joakimp/opencode-devbox:latest
+    container_name: devbox-${SIGNUM:-${USER}}
+    stdin_open: true
+    tty: true
+    env_file:
+      - .env
+    environment:
+      - TERM=xterm-256color
+      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
+      - GITEA_HOST=${GITEA_HOST:-}
+    volumes:
+      # Host workspace — user's project directory
+      - ${WORKSPACE_PATH:-~/src}:/workspace
+
+      # SSH keys — user-specific if available, else shared
+      - ${SSH_KEY_PATH:-~/.ssh}:/home/developer/.ssh:ro
+
+      # Optional: mount skillset repo for automatic skill/instruction deployment.
+      # The entrypoint runs deploy-skills.sh --bootstrap on start, creating
+      # relative symlinks that resolve inside the container regardless of
+      # where the repo lives on the host. Set SKILLSET_PATH in .env.
+      # - ${SKILLSET_PATH}:/home/developer/skillset
+
+      # Persist opencode config (opencode.jsonc, oh-my-opencode-slim.json,
+      # instructions, etc.) across container recreations. Auto-generated on
+      # first start from env vars by generate-config.py and the skillset
+      # deploy script. Using a named volume keeps the container's symlinks
+      # independent from the host.
+      - devbox-opencode-config:/home/developer/.config/opencode
+
+      # Persist opencode data (auth, memory, session history)
+      - devbox-data:/home/developer/.local/share/opencode
+
+      # Persist bash history across container recreations
+      - devbox-shell-history:/home/developer/.cache/bash
+
+      # Persist zoxide directory history ('z <fragment>' to jump)
+      - devbox-zoxide:/home/developer/.local/share/zoxide
+
+      # Persist neovim plugin/Mason data (avoids re-downloading on every recreate)
+      - devbox-nvim-data:/home/developer/.local/share/nvim
+
+      # Persist uv data (Python installs)
+      - devbox-uv:/home/developer/.local/share/uv
+
+      # Optional: persist MemPalace data (conversation memory, knowledge graph)
+      # - devbox-palace:/home/developer/.mempalace
+
+      # Optional: persist ChromaDB embedding model cache (~79 MB)
+      # - devbox-chroma-cache:/home/developer/.cache/chroma
+
+      # Optional: AWS credentials (per-user if available)
+      # - ${HOME}/${SIGNUM}/.aws:/home/developer/.aws
+
+volumes:
+  devbox-opencode-config:
+  devbox-data:
+  devbox-shell-history:
+  devbox-zoxide:
+  devbox-nvim-data:
+  devbox-uv:
+  # devbox-palace:
+  # devbox-chroma-cache:

docker-compose.yml

@@ -8,15 +8,26 @@
 # Or for interactive one-shot:
 #   docker compose run --rm devbox
 
+# Pin the project name so named volumes survive directory renames.
+# Without this, Docker Compose derives the project name from the
+# directory basename — renaming the dir orphans all existing volumes.
+name: opencode-devbox
+
 services:
   devbox:
-    build:
-      context: .
-      args:
-        INSTALL_PYTHON: "false"
-        INSTALL_GO: "false"
-        INSTALL_OMOS: "false"
-    image: opencode-devbox:latest
+    image: joakimp/opencode-devbox:latest
+    # For multi-agent orchestration, use the omos variant instead:
+    # image: joakimp/opencode-devbox:latest-omos
+    #
+    # To build from source instead of pulling from Docker Hub, uncomment:
+    # build:
+    #   context: .
+    #   args:
+    #     INSTALL_GO: "false"
+    #     INSTALL_OMOS: "false"
+    #     INSTALL_PI: "false"
+    #     # PI_VERSION: "latest"
+    #     # INSTALL_OPENCODE: "true"
     container_name: opencode-devbox
     stdin_open: true
     tty: true
@@ -24,6 +35,9 @@ services:
       - .env
     environment:
       - TERM=xterm-256color
+      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-}
+      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
+      - GITEA_HOST=${GITEA_HOST:-}
     volumes:
       # Host workspace — mount your project here
       - ${WORKSPACE_PATH:-.}:/workspace
@@ -31,21 +45,95 @@ services:
       # SSH keys (read-only) — for git push/pull
       - ${SSH_KEY_PATH:-~/.ssh}:/home/developer/.ssh:ro
 
-      # Optional: mount your own opencode config (MCP servers, custom models, etc.)
-      # - ./opencode.json:/home/developer/.config/opencode/opencode.json:ro
+      # Optional: mount skillset repo for automatic skill/instruction deployment.
+      # The entrypoint runs deploy-skills.sh --bootstrap on start, creating
+      # relative symlinks that resolve inside the container regardless of
+      # where the repo lives on the host. Set SKILLSET_PATH in .env.
+      # - ${SKILLSET_PATH}:/home/developer/skillset
 
-      # Optional: mount opencode skills from host
-      # - ~/.config/opencode/skills:/home/developer/.config/opencode/skills:ro
-      # - ~/.agents/skills:/home/developer/.agents/skills:ro
+      # Persist opencode config (opencode.jsonc, oh-my-opencode-slim.json,
+      # instructions, etc.) across container recreations. Auto-generated on
+      # first start from env vars by generate-config.py and the skillset
+      # deploy script. Using a named volume (not a host bind mount) keeps
+      # the container's skill/instruction symlinks independent from the host,
+      # allowing both native and containerized opencode on the same machine.
+      - devbox-opencode-config:/home/developer/.config/opencode
+      - devbox-pi-config:/home/developer/.pi
 
-      # Optional: mount your own oh-my-opencode-slim config
-      # - ./oh-my-opencode-slim.json:/home/developer/.config/opencode/oh-my-opencode-slim.json:ro
+      # NOTE: Do NOT bind-mount ~/.agents/skills/ from the host. The
+      # container manages its own skills directory independently — the
+      # entrypoint deploys skills from the skillset repo on each start.
+      # Sharing it with the host causes symlink conflicts (relative paths
+      # differ between host and container filesystem namespaces).
+
+      # Optional: mount neovim config from host (plugins auto-install on first start)
+      # - ~/.config/nvim:/home/developer/.config/nvim:ro
 
       # Optional: persist opencode data (auth, memory, etc.)
       - devbox-data:/home/developer/.local/share/opencode
 
+      # Optional: persist opencode TUI settings (theme, toggles, etc.)
+      - devbox-state:/home/developer/.local/state/opencode
+
+      # Persist bash history across container recreations.
+      # Without this, ~/.bash_history is lost on 'docker compose up --force-recreate'.
+      - devbox-shell-history:/home/developer/.cache/bash
+
+      # Persist zoxide directory history ('z <fragment>' to jump).
+      - devbox-zoxide:/home/developer/.local/share/zoxide
+
+      # Optional: override baked shell defaults with your host's rc files.
+      # The image ships sensible defaults (history tuning, prefix-search on
+      # Up/Down arrows, fzf/zoxide integration). Uncomment to use your own:
+      #
+      # NOTE: Single-file bind-mounts break when editors use atomic save
+      # (vim, VS Code, sed -i write a temp file then rename() over the
+      # original, creating a new inode the container never sees). This is a
+      # kernel limitation, not Docker-specific. If host edits stop appearing
+      # in the container, mount the parent directory instead — see the
+      # "Shell defaults" section in README.md.
+      # - ~/.bash_aliases:/home/developer/.bash_aliases:ro
+       # - ~/.inputrc:/home/developer/.inputrc:ro
+
+      # Optional: persist uv data (Python installs, tool installs)
+      # Without this, 'uv python install' must be re-run after container removal.
+      - devbox-uv:/home/developer/.local/share/uv
+
+      # Optional: persist Rust toolchains and cargo data
+      # Without this, 'rustup-init' must be re-run after container removal.
+      # - devbox-rustup:/home/developer/.rustup
+      # - devbox-cargo:/home/developer/.cargo
+
+      # Optional: persist VS Code server and extensions across container recreations
+      # - devbox-vscode:/home/developer/.vscode-server
+
+      # Persist neovim plugin/Mason data (avoids re-downloading on every recreate)
+      - devbox-nvim-data:/home/developer/.local/share/nvim
+
+      # Optional: persist MemPalace data (conversation memory, knowledge graph,
+      # embeddings). Without this, palace data is lost on container recreation.
+      # - devbox-palace:/home/developer/.mempalace
+
+      # Optional: persist ChromaDB embedding model cache (~79 MB, downloaded on
+      # first mempalace search). Without this, the model re-downloads on every
+      # container recreation. Separate from palace data — model cache is
+      # disposable, palace data is precious.
+      # - devbox-chroma-cache:/home/developer/.cache/chroma
+
       # Optional: AWS credentials/SSO config (not read-only — SSO writes token cache)
       # - ~/.aws:/home/developer/.aws
 
 volumes:
+  devbox-opencode-config:
+  devbox-pi-config:
   devbox-data:
+  devbox-state:
+  devbox-shell-history:
+  devbox-zoxide:
+  devbox-nvim-data:
+  devbox-uv:
+  # devbox-palace:
+  # devbox-chroma-cache:
+  # devbox-rustup:
+  # devbox-cargo:
+  # devbox-vscode:

entrypoint-user.sh

@@ -1,6 +1,39 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# ── Shell defaults: copy baked files from /etc/skel-devbox/ if absent
+# Respects host bind-mounts and user customizations — existing files
+# are never overwritten. To restore defaults: rm ~/.bash_aliases (or
+# .inputrc) and recreate the container, or cp from /etc/skel-devbox/
+# directly.
+SKEL_DIR="/etc/skel-devbox"
+if [ -d "$SKEL_DIR" ]; then
+  for f in .bash_aliases .inputrc; do
+    if [ -f "$SKEL_DIR/$f" ] && [ ! -e "$HOME/$f" ]; then
+      cp "$SKEL_DIR/$f" "$HOME/$f"
+    fi
+  done
+fi
+
+# ── MemPalace: initialize palace for the workspace if mempalace is installed
+# Creates the palace directory structure on first run. Idempotent — skips
+# if palace already exists, so upgrades from older versions preserve
+# existing data. `--yes` auto-accepts detected entities so the init is
+# non-interactive — the container entrypoint has no usable stdin for
+# prompts anyway.
+if command -v mempalace &>/dev/null && [ -d /workspace ]; then
+  PALACE_DIR="${HOME}/.mempalace"
+  if [ ! -d "$PALACE_DIR/palace" ]; then
+    echo "Initializing MemPalace for workspace (non-interactive)..."
+    # </dev/null: mempalace init has an interactive "Mine this directory
+    # now? [Y/n]" prompt that --yes does not auto-answer in all paths.
+    # Without redirected stdin, the process blocks here forever when run
+    # from `docker run -it` (the TTY keeps stdin open). EOF on stdin
+    # makes the prompt fall through to its default (skip).
+    mempalace init --yes /workspace </dev/null >/dev/null 2>&1 || true
+  fi
+fi
+
 # ── Git config defaults ──────────────────────────────────────────────
 if [ -n "${GIT_USER_NAME:-}" ] && ! git config --global user.name &>/dev/null; then
   git config --global user.name "$GIT_USER_NAME"
@@ -10,71 +43,82 @@ if [ -n "${GIT_USER_EMAIL:-}" ] && ! git config --global user.email &>/dev/null;
 fi
 
 # ── Generate opencode config from env vars if no config mounted ──────
-CONFIG_DIR="$HOME/.config/opencode"
-CONFIG_FILE="$CONFIG_DIR/opencode.json"
+# Delegated to a standalone Python script for clarity and testability.
+# The script is idempotent: it never overwrites an existing opencode.json
+# (bind-mounted from host, persisted in named volume, or previously
+# generated) and no-ops if OPENCODE_PROVIDER is unset.
+python3 /usr/local/lib/opencode-devbox/generate-config.py
 
-if [ ! -f "$CONFIG_FILE" ] && [ -n "${OPENCODE_PROVIDER:-}" ]; then
-  echo "Generating opencode config for provider: $OPENCODE_PROVIDER"
-  mkdir -p "$CONFIG_DIR"
+# ── pi: deploy toolkit + extensions + mempalace bridge ─────────────
+# Runs only when pi was baked into the image (INSTALL_PI=true at build).
+# Each install.sh is idempotent and backs up real files before linking,
+# so re-running across container restarts is safe.
+#
+# Order: pi-toolkit first (creates ~/.pi/agent/keybindings.json symlink
+# and writes the AWS env loader), then pi-extensions (symlinks our 6
+# extensions), then settings.json bootstrap from the toolkit template,
+# then the mempalace bridge symlink (one-liner; mempalace-toolkit's
+# install_skill is intentionally skipped to avoid racing with skillset
+# auto-deploy below).
+if command -v pi &>/dev/null; then
+  if [ -d /opt/pi-toolkit ]; then
+    (cd /opt/pi-toolkit && ./install.sh --yes) || \
+      echo "WARN: pi-toolkit install.sh failed (continuing)"
+  fi
 
-  case "$OPENCODE_PROVIDER" in
-    anthropic)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-5}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-    openai)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-openai/gpt-4o}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-    amazon-bedrock)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-amazon-bedrock/anthropic.claude-sonnet-4-5-v1}",
-  "share": "disabled",
-  "autoupdate": false,
-  "provider": {
-    "amazon-bedrock": {
-      "options": {
-        "region": "${AWS_REGION:-us-east-1}"
-      }
-    }
-  }
-}
-EOF
-      ;;
-    *)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-5}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-  esac
+  if [ -d /opt/pi-extensions ]; then
+    (cd /opt/pi-extensions && ./install.sh --yes) || \
+      echo "WARN: pi-extensions install.sh failed (continuing)"
+  fi
+
+  # Bootstrap settings.json from template if absent (pi rewrites this
+  # file at runtime — lastChangelogVersion, etc — so we can't symlink it).
+  if [ ! -f "$HOME/.pi/agent/settings.json" ] && \
+     [ -f /opt/pi-toolkit/settings.example.json ]; then
+    cp /opt/pi-toolkit/settings.example.json "$HOME/.pi/agent/settings.json"
+  fi
+
+  # pi↔mempalace MCP bridge — single extension symlink.
+  if [ -f /opt/mempalace-toolkit/extensions/pi/mempalace.ts ] && \
+     command -v mempalace &>/dev/null && \
+     [ ! -L "$HOME/.pi/agent/extensions/mempalace.ts" ]; then
+    ln -sf /opt/mempalace-toolkit/extensions/pi/mempalace.ts \
+           "$HOME/.pi/agent/extensions/mempalace.ts"
+  fi
 fi
 
+# ── Skillset: deploy skills/instructions from mounted skillset repo ──
+# When the skillset repo is mounted (at $HOME/skillset or /workspace/skillset),
+# run the deploy script to create relative symlinks for skills and instructions.
+# This ensures skills resolve correctly inside the container regardless of
+# where the repo lives on the host. Idempotent — second run is a no-op.
+#
+# Detection order:
+#   1. SKILLSET_CONTAINER_PATH env var (explicit, for non-standard layouts)
+#   2. $HOME/skillset (dedicated volume mount via SKILLSET_PATH in compose)
+#   3. /workspace/skillset (skillset is directly inside workspace root)
+SKILLSET_DEPLOY=""
+if [ -n "${SKILLSET_CONTAINER_PATH:-}" ] && [ -x "${SKILLSET_CONTAINER_PATH}/deploy-skills.sh" ]; then
+  SKILLSET_DEPLOY="${SKILLSET_CONTAINER_PATH}/deploy-skills.sh"
+elif [ -x "$HOME/skillset/deploy-skills.sh" ]; then
+  SKILLSET_DEPLOY="$HOME/skillset/deploy-skills.sh"
+elif [ -x /workspace/skillset/deploy-skills.sh ]; then
+  SKILLSET_DEPLOY="/workspace/skillset/deploy-skills.sh"
+fi
+if [ -n "$SKILLSET_DEPLOY" ]; then
+  "$SKILLSET_DEPLOY" --bootstrap --prune-stale >/dev/null 2>&1 || true
+fi
+
+CONFIG_DIR="$HOME/.config/opencode"
+OMOS_CONFIG="$CONFIG_DIR/oh-my-opencode-slim.json"
+
 # ── oh-my-opencode-slim setup (multi-agent orchestration) ────────────
 # Activated by ENABLE_OMOS=true. Requires the image to be built with
 # INSTALL_OMOS=true (which installs bun + the oh-my-opencode-slim package).
 OMOS_CONFIG="$CONFIG_DIR/oh-my-opencode-slim.json"
 
 if [ "${ENABLE_OMOS:-false}" = "true" ]; then
-  if ! command -v bunx &>/dev/null; then
+  if ! command -v bun &>/dev/null; then
     echo "WARNING: ENABLE_OMOS=true but bun is not installed."
     echo "Rebuild with: docker compose build --build-arg INSTALL_OMOS=true"
   elif [ ! -f "$OMOS_CONFIG" ]; then
@@ -91,7 +135,7 @@ if [ "${ENABLE_OMOS:-false}" = "true" ]; then
       OMOS_SKILLS_FLAG="no"
     fi
 
-    bunx oh-my-opencode-slim@latest install \
+    bun x oh-my-opencode-slim@latest install \
       --no-tui \
       --tmux="${OMOS_TMUX_FLAG}" \
       --skills="${OMOS_SKILLS_FLAG}"
@@ -108,7 +152,7 @@ if [ "${ENABLE_OMOS:-false}" = "true" ]; then
       OMOS_SKILLS_FLAG="yes"
       [ "${OMOS_SKILLS:-true}" = "false" ] && OMOS_SKILLS_FLAG="no"
 
-      bunx oh-my-opencode-slim@latest install \
+      bun x oh-my-opencode-slim@latest install \
         --no-tui \
         --tmux="${OMOS_TMUX_FLAG}" \
         --skills="${OMOS_SKILLS_FLAG}" \

entrypoint.sh

@@ -6,18 +6,22 @@ CURRENT_UID=$(id -u "$USER_NAME")
 CURRENT_GID=$(id -g "$USER_NAME")
 
 # ── UID/GID adjustment ───────────────────────────────────────────────
-# Priority: env vars > auto-detect from /workspace > default (1000)
+# Priority per dimension: env var > auto-detect from /workspace > no-op
+# UID and GID are detected independently so a GID-only mismatch (e.g. host
+# user has UID 1000 but primary group at GID 1001) is still corrected.
 TARGET_UID="${USER_UID:-}"
 TARGET_GID="${USER_GID:-}"
 
-# Auto-detect from /workspace owner if env vars not set
-if [ -z "$TARGET_UID" ] && [ -d /workspace ]; then
-  WORKSPACE_UID=$(stat -c '%u' /workspace 2>/dev/null || stat -f '%u' /workspace 2>/dev/null)
-  WORKSPACE_GID=$(stat -c '%g' /workspace 2>/dev/null || stat -f '%g' /workspace 2>/dev/null)
-  # Only adjust if workspace is owned by a non-root user
-  if [ "$WORKSPACE_UID" != "0" ] && [ "$WORKSPACE_UID" != "$CURRENT_UID" ]; then
+if [ -d /workspace ]; then
+  WORKSPACE_UID=$(stat -c '%u' /workspace 2>/dev/null || stat -f '%u' /workspace 2>/dev/null || echo "")
+  WORKSPACE_GID=$(stat -c '%g' /workspace 2>/dev/null || stat -f '%g' /workspace 2>/dev/null || echo "")
+  # Adopt workspace UID if env var not set and workspace is non-root-owned
+  if [ -z "$TARGET_UID" ] && [ -n "$WORKSPACE_UID" ] && [ "$WORKSPACE_UID" != "0" ] && [ "$WORKSPACE_UID" != "$CURRENT_UID" ]; then
     TARGET_UID="$WORKSPACE_UID"
-    TARGET_GID="${TARGET_GID:-$WORKSPACE_GID}"
+  fi
+  # Adopt workspace GID if env var not set and workspace group differs
+  if [ -z "$TARGET_GID" ] && [ -n "$WORKSPACE_GID" ] && [ "$WORKSPACE_GID" != "0" ] && [ "$WORKSPACE_GID" != "$CURRENT_GID" ]; then
+    TARGET_GID="$WORKSPACE_GID"
   fi
 fi
 
@@ -25,12 +29,13 @@ fi
 if [ -n "$TARGET_GID" ] && [ "$TARGET_GID" != "$CURRENT_GID" ]; then
   groupmod -g "$TARGET_GID" "$USER_NAME" 2>/dev/null || true
   find /home/"$USER_NAME" -not -path "/home/$USER_NAME/.ssh/*" -group "$CURRENT_GID" -exec chgrp "$TARGET_GID" {} + 2>/dev/null || true
+  echo "Adjusted developer GID to $TARGET_GID"
 fi
 
 if [ -n "$TARGET_UID" ] && [ "$TARGET_UID" != "$CURRENT_UID" ]; then
   usermod -u "$TARGET_UID" "$USER_NAME" 2>/dev/null || true
   find /home/"$USER_NAME" -not -path "/home/$USER_NAME/.ssh/*" -user "$CURRENT_UID" -exec chown "$TARGET_UID" {} + 2>/dev/null || true
-  echo "Adjusted developer UID:GID to $TARGET_UID:${TARGET_GID:-$CURRENT_GID}"
+  echo "Adjusted developer UID to $TARGET_UID"
 fi
 
 # ── SSH key permissions ──────────────────────────────────────────────
@@ -46,5 +51,71 @@ if [ -d "/home/$USER_NAME/.ssh" ] && [ "$(ls -A "/home/$USER_NAME/.ssh" 2>/dev/n
   fi
 fi
 
+# ── Fix ownership of named volume mount points ──────────────────────
+# Named volumes are created as root on first use. Fix ownership so the
+# developer user can write to them.
+FINAL_UID="${TARGET_UID:-$CURRENT_UID}"
+FINAL_GID="${TARGET_GID:-$CURRENT_GID}"
+
+# First, fix parent dirs that Docker auto-creates as root:root when it
+# materializes nested mount points (e.g. mounting a volume at
+# .local/state/opencode creates .local/state as root). Non-recursive —
+# we only need the dir node itself; children are handled below or were
+# created by the user.
+for parent in \
+  /home/"$USER_NAME"/.local \
+  /home/"$USER_NAME"/.local/share \
+  /home/"$USER_NAME"/.local/state \
+  /home/"$USER_NAME"/.cache \
+  /home/"$USER_NAME"/.config; do
+  if [ -d "$parent" ] && [ "$(stat -c '%u' "$parent" 2>/dev/null)" != "$FINAL_UID" ]; then
+    chown "$FINAL_UID":"$FINAL_GID" "$parent" 2>/dev/null || true
+  fi
+done
+
+for dir in \
+  /home/"$USER_NAME"/.local/share/opencode \
+  /home/"$USER_NAME"/.local/state/opencode \
+  /home/"$USER_NAME"/.local/share/uv \
+  /home/"$USER_NAME"/.local/share/zoxide \
+  /home/"$USER_NAME"/.local/share/nvim \
+  /home/"$USER_NAME"/.mempalace \
+  /home/"$USER_NAME"/.cache/bash \
+  /home/"$USER_NAME"/.cache/chroma \
+  /home/"$USER_NAME"/.rustup \
+  /home/"$USER_NAME"/.cargo \
+  /home/"$USER_NAME"/.vscode-server \
+  /home/"$USER_NAME"/.config/opencode \
+  /home/"$USER_NAME"/.config/nvim \
+  /home/"$USER_NAME"/.pi \
+  /home/"$USER_NAME"/.agents/skills; do
+  [ -d "$dir" ] || continue
+
+  # Sentinel-file fast path: on volumes with thousands of files (nvim
+  # plugins, palace data) the recursive chown used to cost multiple
+  # seconds on every container start even when ownership was already
+  # correct. Now we write a sentinel after a successful chown and skip
+  # the walk when the sentinel matches the target UID:GID.
+  #
+  # If USER_UID changes between runs (user switches hosts, different
+  # workspace owner), the sentinel won't match and the full chown runs.
+  sentinel="$dir/.devbox-owner"
+  expected="$FINAL_UID:$FINAL_GID"
+  if [ -f "$sentinel" ] && [ "$(cat "$sentinel" 2>/dev/null)" = "$expected" ]; then
+    continue
+  fi
+
+  # Recursive chown needed. Only do it when the top-level differs too
+  # (covers the common case of fresh root-owned named volumes).
+  if [ "$(stat -c '%u' "$dir" 2>/dev/null)" != "$FINAL_UID" ]; then
+    chown -R "$FINAL_UID":"$FINAL_GID" "$dir" 2>/dev/null || true
+  fi
+
+  # Write sentinel so subsequent starts skip the recursive walk.
+  # Suppress errors — a read-only mount would fail here, but that would
+  # already have failed above on the chown itself.
+  echo "$expected" > "$sentinel" 2>/dev/null || true
+done
+
 # ── Drop to developer user for remaining setup ──────────────────────
 exec gosu "$USER_NAME" /usr/local/bin/entrypoint-user.sh "$@"

rootfs/home/developer/.bash_aliases

@@ -0,0 +1,94 @@
+# opencode-devbox bash aliases and customizations
+# Sourced by the Debian-default ~/.bashrc on shell startup.
+# To override, bind-mount your host's ~/.bash_aliases over this file
+# via docker-compose.yml.
+
+# ── Host-shared shell customizations (devbox-shell bridge) ───────────
+# If the host bind-mounts a directory at ~/.config/devbox-shell/ (the
+# recommended pattern for sharing aliases/PATH/utilities between host
+# and container), source the bash_aliases file from it. This survives
+# --force-recreate because it's baked into the image's skel, not the
+# container's writable layer. Hosts that don't use this pattern are
+# unaffected — the test silently skips if the file doesn't exist.
+[ -r "$HOME/.config/devbox-shell/bash_aliases" ] && . "$HOME/.config/devbox-shell/bash_aliases"
+
+# ── History persistence and quality ──────────────────────────────────
+# The named volume devbox-shell-history is mounted at ~/.cache/bash
+# so history survives container recreation.
+export HISTFILE="${HOME}/.cache/bash/history"
+mkdir -p "$(dirname "$HISTFILE")" 2>/dev/null || true
+
+# Large, time-stamped, deduplicated history. Append rather than overwrite.
+export HISTSIZE=100000
+export HISTFILESIZE=200000
+export HISTCONTROL=ignoreboth:erasedups
+export HISTTIMEFORMAT='%F %T  '
+shopt -s histappend 2>/dev/null
+shopt -s cmdhist 2>/dev/null
+# Note: PROMPT_COMMAND="history -a" is installed LATER in this file,
+# after zoxide's init runs. Installing it here would create a
+# "history -a;;__zoxide_hook" chain because zoxide's init uses ';'
+# as its separator and prepends itself; two adjacent ';' breaks the
+# parser. See https://github.com/ajeetdsouza/zoxide/issues/722.
+
+# ── Common aliases ───────────────────────────────────────────────────
+# Prefer eza (modern ls) when available
+if command -v eza >/dev/null 2>&1; then
+  alias ls='eza --group-directories-first'
+  alias ll='eza -lh --group-directories-first --git'
+  alias la='eza -lha --group-directories-first --git'
+  alias tree='eza --tree'
+else
+  alias ll='ls -lh'
+  alias la='ls -lha'
+fi
+
+# Prefer bat (syntax-highlighted cat) when available
+if command -v bat >/dev/null 2>&1; then
+  alias cat='bat --style=plain --paging=never'
+  alias less='bat --paging=always'
+fi
+
+# Git shortcuts
+alias gs='git status'
+alias gd='git diff'
+alias gl='git log --oneline --graph --decorate -20'
+
+# Safety: confirm before destructive ops
+alias rm='rm -i'
+alias mv='mv -i'
+alias cp='cp -i'
+
+# ── Shell integrations ───────────────────────────────────────────────
+# zoxide — smarter cd. Use 'z <fragment>' to jump to previously-visited dirs.
+if command -v zoxide >/dev/null 2>&1; then
+  eval "$(zoxide init bash)"
+fi
+
+# fzf — fuzzy finder key bindings (Ctrl-R for history, Ctrl-T for files).
+# We install fzf from GitHub releases (not apt), so sourcing from the
+# apt-path /usr/share/doc/fzf/examples/* would find nothing. Use the
+# binary's own --bash flag (available since fzf 0.48) for setup.
+if command -v fzf >/dev/null 2>&1; then
+  eval "$(fzf --bash)" 2>/dev/null || true
+fi
+
+# ── PROMPT_COMMAND: flush history every prompt ───────────────────────
+# Installed AFTER zoxide init so zoxide's hook is already in place;
+# we append with a newline separator to avoid the ';;' parse error
+# described at the top of this file. Guarded so repeated sourcing
+# (e.g. `exec bash`) doesn't stack duplicates.
+if [ -z "${DEVBOX_HIST_SET:-}" ]; then
+  PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a"
+  export DEVBOX_HIST_SET=1
+fi
+
+# ── Prompt: show [opencode-devbox] tag so it's obvious you're in the container
+# Preserves the default Debian PS1 logic but prefixes with a container marker.
+# We check for the literal '[devbox]' substring in PS1 rather than relying on
+# an exported guard variable — otherwise `exec bash` inherits the guard but
+# gets a fresh (prefix-less) PS1 from .bashrc, and the prefix would never be
+# re-added in the new shell.
+if [ -n "${PS1:-}" ] && [[ "$PS1" != *"[devbox]"* ]]; then
+  PS1='\[\e[38;5;39m\][devbox]\[\e[0m\] '"${PS1}"
+fi

rootfs/home/developer/.inputrc

@@ -0,0 +1,27 @@
+# opencode-devbox readline defaults
+# To override, bind-mount your host's ~/.inputrc over this file
+# via docker-compose.yml.
+
+# Inherit system-wide defaults (colour, 8-bit input, …) if present
+$include /etc/inputrc
+
+# ── History search on Up/Down ────────────────────────────────────────
+# Type a prefix, press Up, and walk through previous commands starting
+# with that prefix. Ctrl-Up / Ctrl-Down keep the unconditional stepper.
+"\e[A": history-search-backward
+"\e[B": history-search-forward
+"\e[1;5A": previous-history
+"\e[1;5B": next-history
+
+# ── Completion quality ───────────────────────────────────────────────
+set show-all-if-ambiguous on      # single Tab shows matches on ambiguity
+set completion-ignore-case on     # case-insensitive file/dir completion
+set colored-stats on              # colour ls-style completion list entries
+set colored-completion-prefix on  # highlight the matched prefix
+set visible-stats on              # append /*@ type indicators in completion
+set mark-symlinked-directories on # add trailing / to symlinks to dirs
+set skip-completed-text on        # don't re-insert already-typed text
+
+# Treat hyphens and underscores as equivalent when completing (e.g.
+# typing `foo-` matches both `foo-bar` and `foo_bar`).
+set completion-map-case on

rootfs/usr/local/lib/opencode-devbox/generate-config.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+Generate opencode.json from environment variables on first container start.
+
+Safety guarantees:
+  - NEVER overwrites an existing opencode.json. If the file is present
+    (whether bind-mounted from the host, persisted in a named volume, or
+    previously generated), this script exits immediately without writing.
+  - Requires OPENCODE_PROVIDER to be set. Without it, no file is written.
+
+Environment variables:
+  OPENCODE_PROVIDER  Required. One of: anthropic, openai, amazon-bedrock.
+  OPENCODE_MODEL     Optional. Overrides the provider default model.
+  AWS_REGION         Bedrock only. Default: us-east-1.
+  AWS_PROFILE        Bedrock only. Default: default.
+
+MCP servers are auto-registered for tools detected on PATH:
+  - mempalace (if installed) — enabled
+  - gitea-mcp (if installed) — registered but disabled by default
+
+Output path: $HOME/.config/opencode/opencode.json
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+# Default model per provider. Update here when upstream changes.
+DEFAULT_MODELS: dict[str, str] = {
+    "anthropic": "anthropic/claude-sonnet-4-6",
+    "openai": "openai/gpt-5.4",
+    "amazon-bedrock": (
+        "amazon-bedrock/global.anthropic.claude-sonnet-4-5-20250929-v1:0"
+    ),
+}
+
+# Fallback when OPENCODE_PROVIDER is set but not recognized.
+FALLBACK_MODEL = DEFAULT_MODELS["anthropic"]
+
+SCHEMA_URL = "https://opencode.ai/config.json"
+
+
+def build_config(provider: str, model: str) -> dict:
+    """Build the base opencode.json structure for a provider."""
+    config: dict = {
+        "$schema": SCHEMA_URL,
+        "model": model,
+        "share": "disabled",
+        "autoupdate": False,
+    }
+
+    if provider == "amazon-bedrock":
+        config["provider"] = {
+            "amazon-bedrock": {
+                "options": {
+                    "region": os.environ.get("AWS_REGION", "us-east-1"),
+                    "profile": os.environ.get("AWS_PROFILE", "default"),
+                }
+            }
+        }
+
+    return config
+
+
+def register_mcp_servers(config: dict) -> list[str]:
+    """Auto-register MCP servers for tools detected on PATH.
+
+    Returns the list of server names that were added. The "mcp" key
+    is only added to the config when at least one server is registered.
+    """
+    servers: dict[str, dict] = {}
+
+    # MemPalace — local-first AI memory (if installed).
+    # `mempalace-mcp` is the entry-point binary shipped by the mempalace
+    # Python package. `uv tool install mempalace` places it on PATH as a
+    # shim whose shebang points at the isolated venv's Python, so system
+    # `python3 -m mempalace.mcp_server` (which would fail — system
+    # python3 can't import from the uv venv) is unnecessary here.
+    if shutil.which("mempalace-mcp"):
+        servers["mempalace"] = {
+            "type": "local",
+            "command": ["mempalace-mcp"],
+        }
+
+    # Gitea — self-hosted Git forge API (if installed).
+    # Disabled by default; user must set GITEA_ACCESS_TOKEN + GITEA_HOST
+    # and flip enabled=true in their config.
+    if shutil.which("gitea-mcp"):
+        servers["gitea"] = {
+            "type": "local",
+            "command": ["gitea-mcp", "-t", "stdio"],
+            "enabled": False,
+        }
+
+    # Context7 — up-to-date library documentation for LLMs (remote).
+    # Free tier works without an API key; set CONTEXT7_API_KEY for higher
+    # rate limits. No local binary needed — purely a remote MCP endpoint.
+    servers["context7"] = {
+        "type": "remote",
+        "url": "https://mcp.context7.com/mcp",
+    }
+
+    if servers:
+        config["mcp"] = servers
+
+    return list(servers.keys())
+
+
+def main() -> int:
+    provider = os.environ.get("OPENCODE_PROVIDER", "").strip()
+    if not provider:
+        # No provider set — nothing to do. Not an error.
+        return 0
+
+    home = Path(os.environ.get("HOME", "/home/developer"))
+    config_dir = home / ".config" / "opencode"
+    config_file = config_dir / "opencode.jsonc"
+    config_file_legacy = config_dir / "opencode.json"
+
+    # CRITICAL: never overwrite an existing config. Users may have
+    # bind-mounted their host config directory, or their config may be
+    # persisted in a named volume from a previous run.
+    # Check both .json and .jsonc variants.
+    if config_file.exists() or config_file_legacy.exists():
+        existing = config_file if config_file.exists() else config_file_legacy
+        print(
+            f"Existing config found at {existing} — "
+            "skipping generation.",
+            file=sys.stderr,
+        )
+        return 0
+
+    if provider not in DEFAULT_MODELS:
+        print(
+            f"WARNING: unknown OPENCODE_PROVIDER={provider!r}, "
+            f"falling back to default model {FALLBACK_MODEL!r}.",
+            file=sys.stderr,
+        )
+
+    model = os.environ.get("OPENCODE_MODEL", "").strip() or DEFAULT_MODELS.get(
+        provider, FALLBACK_MODEL
+    )
+
+    print(f"Generating opencode config for provider: {provider}", file=sys.stderr)
+
+    config = build_config(provider, model)
+    added = register_mcp_servers(config)
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write as JSONC so we can include helpful comments.
+    content = json.dumps(config, indent=2)
+
+    # Insert a comment about Context7 API key after the context7 url line.
+    context7_comment = (
+        '      "url": "https://mcp.context7.com/mcp"\n'
+        "      // For higher rate limits, sign up at https://context7.com/dashboard\n"
+        '      // and add: "headers": { "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}" }'
+    )
+    content = content.replace(
+        '      "url": "https://mcp.context7.com/mcp"',
+        context7_comment,
+    )
+
+    with config_file.open("w") as f:
+        f.write(content)
+        f.write("\n")
+
+    if added:
+        print(
+            f"MCP servers registered in opencode config: {', '.join(added)}.",
+            file=sys.stderr,
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/generate-dockerhub-md.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+Generate DOCKER_HUB.md.
+
+Rationale
+---------
+DOCKER_HUB.md is the public-facing description shown on Docker Hub. It
+has two hard constraints the README does not:
+
+  1. A 25 kB byte limit on the full_description field.
+  2. A different audience: Hub readers want a 30-second evaluation —
+     "what is this, how do I run it, does it have what I need" — and
+     reference material is better consulted in context on gitea.
+
+For a long time this script tried to derive DOCKER_HUB.md from README.md
+by section selection + targeted replacement. As the README grew that
+approach pushed against the 25 kB ceiling on every change, costing a
+trim-something-else exercise per edit (final state: 3 byte headroom).
+
+The new approach is much simpler: a hand-written HUB_TEMPLATE below.
+The template intentionally stays slim and links out to the gitea README
+for everything that benefits from depth. README.md grows freely.
+
+Trade-off: when image-variants table or quick-start flow changes,
+update HUB_TEMPLATE here too. That coupling is now explicit and
+local rather than spread across SECTION_RULES + REPLACEMENTS + TRIM
+machinery.
+
+Usage
+-----
+Regenerate in place:
+    python3 scripts/generate-dockerhub-md.py
+
+Fail if DOCKER_HUB.md is out of sync with what this script would emit
+(run this in CI):
+    python3 scripts/generate-dockerhub-md.py --check
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DOCKER_HUB = REPO_ROOT / "DOCKER_HUB.md"
+
+# Max size for Docker Hub full_description (bytes, UTF-8).
+MAX_SIZE_BYTES = 25_000
+
+# Where readers go for the full reference.
+GITEA = "https://gitea.jordbo.se/joakimp/opencode-devbox"
+
+
+HUB_TEMPLATE = f"""# opencode-devbox
+
+Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.
+
+Designed for teams who want a reproducible coding-agent setup that runs the same on every laptop and CI runner — without forcing each developer to install Bun, Node, AWS CLI, mempalace, or maintain shell config drift across machines.
+
+## Image Variants
+
+| Tag | Description |
+|---|---|
+| `latest` / `vX.Y.Z` | Base image — opencode, Node.js, AWS CLI, dev tools |
+| `latest-omos` / `vX.Y.Z-omos` | Base + [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration and Bun |
+| `latest-with-pi` / `vX.Y.Z-with-pi` | Base + [pi](https://github.com/mariozechner/pi-coding-agent) as alternative/complementary harness (shares the mempalace install with opencode) |
+| `latest-omos-with-pi` / `vX.Y.Z-omos-with-pi` | OMOS + pi together |
+
+All variants support `linux/amd64` and `linux/arm64`.
+
+## Quick Start
+
+```bash
+docker run -it --rm \\
+  -e ANTHROPIC_API_KEY=your-key \\
+  -e OPENCODE_PROVIDER=anthropic \\
+  -e GIT_USER_NAME="Your Name" \\
+  -e GIT_USER_EMAIL="you@example.com" \\
+  -v ~/projects:/workspace \\
+  -v ~/.ssh:/home/developer/.ssh:ro \\
+  joakimp/opencode-devbox:latest
+```
+
+Drops you straight into opencode with your project mounted at `/workspace`.
+
+For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
+
+```bash
+docker run -it --rm \\
+  -e ANTHROPIC_API_KEY=your-key \\
+  -e OPENCODE_PROVIDER=anthropic \\
+  -v ~/projects:/workspace \\
+  -v ~/.ssh:/home/developer/.ssh:ro \\
+  joakimp/opencode-devbox:latest bash
+```
+
+Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
+
+For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
+
+## What's Inside
+
+- **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
+- **[pi](https://github.com/mariozechner/pi-coding-agent)** *(in `*-with-pi` variants)* — lightweight TUI coding-agent that coexists with opencode and shares the same mempalace install. Includes the `mcp-loader` extension so any local-stdio or remote streamable-HTTP MCP server (searxng, gitea, context7, …) can be added by editing `~/.pi/agent/settings.json`.
+- **[mempalace](https://github.com/MemPalace/mempalace)** — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi.
+- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** *(in `*-omos` variants)* — multi-agent orchestration on top of opencode (council, fallback chains, named agents).
+- **AWS CLI v2** with SSO support, **Node.js LTS**, **Bun** (OMOS variants), **uv** (Python), **gosu** for clean UID/GID adjustment to match your host workspace.
+- **MCP wrappers** for mempalace pre-installed and pre-wired to both harnesses.
+
+## Authentication
+
+The container reads provider credentials from environment variables and host-mounted config:
+
+- **Anthropic / OpenAI / Groq / others:** set `OPENCODE_PROVIDER` and the corresponding `*_API_KEY` via `-e` or `.env`.
+- **AWS Bedrock (SSO):** mount `~/.aws` from the host, `OPENCODE_PROVIDER=amazon-bedrock`, then `aws sso login` inside the container. Tokens persist across container restarts via the host bind-mount.
+- **OAuth / device-code providers:** auth state lives in opencode's config, which is persisted via the `devbox-opencode-config` named volume.
+
+Full Bedrock walkthrough (IAM roles, permissions, multi-account setups): see the [AWS Bedrock Authentication](
+{GITEA}#aws-bedrock-authentication
+) section on gitea.
+
+## Persistence
+
+| Volume | Mount | Survives |
+|---|---|---|
+| `devbox-opencode-config` | `~/.config/opencode` | container recreate, image rebuild |
+| `devbox-pi-config` | `~/.pi` | container recreate, image rebuild — incl. user-installed pi packages via `pi install` (`NPM_CONFIG_PREFIX` points into the volume) |
+| `devbox-palace` (uncomment) | `~/.mempalace` | container recreate, image rebuild — palace data is precious, treat as primary storage |
+| `devbox-chroma-cache` | `~/.cache/chroma` | container recreate (model cache, disposable — re-downloads in seconds) |
+
+Workspace bind-mount (`/workspace`) is your project directory on the host, so source code is never inside the container.
+
+Full persistence reference, including multi-user (`SIGNUM`) isolation and host bind-mount alternatives: see the [README on gitea]({GITEA}#persistence).
+
+## Where to Go Next
+
+- **Full README** with build args, every feature in detail, troubleshooting: <{GITEA}>
+- **CHANGELOG** for version history: <{GITEA}/src/branch/main/CHANGELOG.md>
+- **Issues / source / docker-compose templates:** <{GITEA}>
+- **Agent-facing internals** (for future maintainers / coding agents working in the repo): <{GITEA}/src/branch/main/AGENTS.md>
+
+## License
+
+MIT. See <{GITEA}/src/branch/main/LICENSE>.
+
+---
+
+> This description is generated by `scripts/generate-dockerhub-md.py` from a hand-maintained template. Edit the template (not this file) and regenerate.
+"""
+
+
+def generate() -> str:
+    return HUB_TEMPLATE
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Fail if DOCKER_HUB.md differs from generated content.",
+    )
+    args = parser.parse_args()
+
+    content = generate()
+    size = len(content.encode("utf-8"))
+    if size > MAX_SIZE_BYTES:
+        print(
+            f"ERROR: generated DOCKER_HUB.md is {size} bytes, exceeding the "
+            f"Docker Hub limit of {MAX_SIZE_BYTES} bytes.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.check:
+        existing = DOCKER_HUB.read_text(encoding="utf-8") if DOCKER_HUB.exists() else ""
+        if existing != content:
+            print(
+                "ERROR: DOCKER_HUB.md is out of sync with the template.\n"
+                "Run: python3 scripts/generate-dockerhub-md.py",
+                file=sys.stderr,
+            )
+            import difflib
+
+            diff = difflib.unified_diff(
+                existing.splitlines(keepends=True),
+                content.splitlines(keepends=True),
+                fromfile="DOCKER_HUB.md (committed)",
+                tofile="DOCKER_HUB.md (generated)",
+                n=2,
+            )
+            sys.stderr.writelines(list(diff)[:80])
+            return 1
+        print(
+            f"OK: DOCKER_HUB.md is in sync with HUB_TEMPLATE "
+            f"({size} bytes, {MAX_SIZE_BYTES} limit, "
+            f"{MAX_SIZE_BYTES - size} bytes headroom).",
+        )
+        return 0
+
+    DOCKER_HUB.write_text(content, encoding="utf-8")
+    print(
+        f"Wrote {DOCKER_HUB} ({size} bytes, {MAX_SIZE_BYTES} limit, "
+        f"{MAX_SIZE_BYTES - size} bytes headroom).",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/smoke-test.sh

@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+# Smoke-test a freshly-built opencode-devbox image.
+#
+# Verifies:
+#   - Core binaries are on PATH and runnable
+#   - opencode itself starts and prints a version
+#   - Entrypoint runs cleanly as non-root after UID adjustment
+#   - Generated opencode.json has the expected shape
+#   - MCP wrapper works (when mempalace is installed)
+#
+# Usage: ./scripts/smoke-test.sh <image> [--variant base|omos|with-pi|omos-with-pi]
+#
+# Exit codes:
+#   0  all checks passed
+#   1  one or more checks failed
+
+set -euo pipefail
+
+IMAGE="${1:-}"
+VARIANT="base"
+if [ "${2:-}" = "--variant" ]; then
+  VARIANT="${3:-base}"
+fi
+
+if [ -z "$IMAGE" ]; then
+  echo "usage: $0 <image> [--variant base|omos|with-pi|omos-with-pi]" >&2
+  exit 2
+fi
+
+FAILED=0
+pass() { echo "  ✓ $1"; }
+fail() { echo "  ✗ $1" >&2; FAILED=$((FAILED + 1)); }
+
+run() {
+  # Run a command inside the image and capture its output.
+  # First arg is a label, rest is the shell command.
+  local label="$1"; shift
+  local out
+  if out=$(docker run --rm --entrypoint="" "$IMAGE" sh -c "$*" 2>&1); then
+    pass "$label ($(echo "$out" | head -1))"
+  else
+    fail "$label: $out"
+  fi
+}
+
+echo "=== Smoke test: $IMAGE (variant: $VARIANT) ==="
+echo
+echo "-- Resolved component versions --"
+# Prints the actual version of every floating component so CI logs
+# always record what got baked into this image, even when Dockerfile
+# ARGs default to "latest".
+docker run --rm --entrypoint="" "$IMAGE" sh -c '
+  if command -v opencode >/dev/null 2>&1; then
+    printf "  %-15s %s\n" "opencode"      "$(opencode --version 2>&1 | head -1)"
+  fi
+  if command -v pi >/dev/null 2>&1; then
+    printf "  %-15s %s\n" "pi"            "$(pi --version 2>&1 | head -1)"
+  fi
+  printf "  %-15s %s\n" "node"          "$(node --version)"
+  printf "  %-15s %s\n" "npm"           "$(npm --version)"
+  printf "  %-15s %s\n" "nvim"          "$(nvim --version | head -1)"
+  printf "  %-15s %s\n" "bat"           "$(bat --version)"
+  printf "  %-15s %s\n" "eza"           "$(eza --version | head -2 | tail -1)"
+  printf "  %-15s %s\n" "zoxide"        "$(zoxide --version)"
+  printf "  %-15s %s\n" "uv"            "$(uv --version)"
+  printf "  %-15s %s\n" "fzf"           "$(fzf --version)"
+  printf "  %-15s %s\n" "fd"            "$(fd --version)"
+  printf "  %-15s %s\n" "rg"            "$(rg --version | head -1)"
+  printf "  %-15s %s\n" "gosu"          "$(gosu --version)"
+  printf "  %-15s %s\n" "git-lfs"       "$(git-lfs --version)"
+  printf "  %-15s %s\n" "gitea-mcp"     "$(gitea-mcp --version 2>&1 | head -1)"
+  printf "  %-15s %s\n" "aws"           "$(aws --version 2>&1)"
+  if command -v bun >/dev/null 2>&1; then
+    printf "  %-15s %s\n" "bun"         "$(bun --version)"
+  fi
+  if command -v mempalace >/dev/null 2>&1; then
+    printf "  %-15s %s\n" "mempalace"   "$(mempalace --version 2>&1 | head -1 || echo installed)"
+  fi
+  if command -v mempalace-session >/dev/null 2>&1 && [ -d /opt/mempalace-toolkit ]; then
+    printf "  %-15s %s\n" "toolkit"     "$(git -C /opt/mempalace-toolkit rev-parse --short HEAD 2>/dev/null || echo installed)"
+  fi
+'
+echo
+echo "-- Core binaries --"
+# opencode is gated on INSTALL_OPENCODE=true (default). When absent, the
+# image is a pi-only build (or a pure base — no harness at all).
+if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v opencode" >/dev/null 2>&1; then
+  run "opencode"          "opencode --version"
+else
+  echo "  - opencode not installed (INSTALL_OPENCODE=false)"
+fi
+run "node"              "node --version"
+run "npm"               "npm --version"
+run "git"               "git --version"
+run "nvim"              "nvim --version | head -1"
+run "bat"               "bat --version"
+run "eza"               "eza --version | head -1"
+run "zoxide"            "zoxide --version"
+run "uv"                "uv --version"
+run "uvx"               "uvx --version"
+run "rustup-init"       "rustup-init --version"
+run "fzf"               "fzf --version"
+run "fd"                "fd --version"
+run "rg"                "rg --version | head -1"
+run "jq"                "jq --version"
+run "aws"               "aws --version"
+run "gitea-mcp"         "gitea-mcp --version"
+run "gosu"              "gosu --version"
+run "tmux"              "tmux -V"
+
+echo
+echo "-- Optional / variant-gated --"
+# mempalace: present unless built with INSTALL_MEMPALACE=false
+if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v mempalace" >/dev/null 2>&1; then
+  run "mempalace"             "mempalace --help | head -1"
+  run "mempalace-mcp"         "test -x /usr/local/bin/mempalace-mcp && readlink /usr/local/bin/mempalace-mcp"
+else
+  echo "  - mempalace not installed (INSTALL_MEMPALACE=false)"
+fi
+
+# mempalace-toolkit wrappers: present unless built with INSTALL_MEMPALACE_TOOLKIT=false
+# Gated on mempalace presence — wrappers are useless without the CLI.
+if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v mempalace && command -v mempalace-session" >/dev/null 2>&1; then
+  run "mempalace-session (toolkit)" "mempalace-session --help | head -1"
+  run "mempalace-docs (toolkit)"    "mempalace-docs --help | head -1"
+  run "toolkit symlink target"      "test -L /usr/local/bin/mempalace-session && readlink /usr/local/bin/mempalace-session"
+elif docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v mempalace" >/dev/null 2>&1; then
+  echo "  - mempalace-toolkit not installed (INSTALL_MEMPALACE_TOOLKIT=false)"
+fi
+
+# pi: present when built with INSTALL_PI=true. Verifies pi itself plus
+# the runtime-deployed pi-toolkit + pi-extensions + mempalace bridge
+# symlinks under ~/.pi/agent/. Note: extension symlinks are created by
+# entrypoint-user.sh on first start, so we test by running the entry
+# point chain (not just `docker run --entrypoint=""`).
+if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v pi" >/dev/null 2>&1; then
+  run "pi"                       "pi --version"
+  run "pi-toolkit clone"         "test -d /opt/pi-toolkit && git -C /opt/pi-toolkit rev-parse --short HEAD"
+  run "pi-extensions clone"      "test -d /opt/pi-extensions && git -C /opt/pi-extensions rev-parse --short HEAD"
+
+  # Run the full entrypoint as developer to verify install.sh deployment.
+  # Spin up a long-running container so we can `docker exec` into it from
+  # the host — the `run` helper above invokes commands INSIDE the image
+  # and has no docker CLI to nest with.
+  CID=$(docker run -d --rm "$IMAGE" tail -f /dev/null)
+  trap 'docker rm -f "$CID" >/dev/null 2>&1 || true' EXIT
+
+  # Wait for entrypoint-user.sh to finish deploying pi-toolkit + extensions.
+  # Marker: keybindings.json symlink lands once pi-toolkit/install.sh has run.
+  # Up to 30s — omos-with-pi has more setup work than base+pi.
+  for _ in $(seq 1 30); do
+    if docker exec "$CID" test -L /home/developer/.pi/agent/keybindings.json 2>/dev/null; then
+      break
+    fi
+    sleep 1
+  done
+
+  exec_test() {
+    local label="$1"; shift
+    local out
+    if out=$(docker exec -u developer "$CID" sh -c "$*" 2>&1); then
+      pass "$label ($(echo "$out" | head -1))"
+    else
+      fail "$label: $out"
+    fi
+  }
+
+  exec_test "~/.pi/agent/keybindings.json (pi-toolkit)" \
+            'test -L $HOME/.pi/agent/keybindings.json && echo ok'
+  exec_test "~/.pi/agent/extensions/*.ts ≥ 4 (pi-extensions)" \
+            'count=$(ls -1 $HOME/.pi/agent/extensions/*.ts 2>/dev/null | wc -l); [ $count -ge 4 ] && echo "$count extensions"'
+  exec_test "~/.pi/agent/extensions/mempalace.ts (bridge)" \
+            'test -L $HOME/.pi/agent/extensions/mempalace.ts && echo ok'
+  exec_test "~/.pi/agent/settings.json (template bootstrap)" \
+            'test -f $HOME/.pi/agent/settings.json && echo ok'
+
+  docker rm -f "$CID" >/dev/null 2>&1 || true
+  trap - EXIT
+else
+  echo "  - pi not installed (INSTALL_PI=false)"
+fi
+
+# bun: only in the omos and omos-with-pi variants
+if [ "$VARIANT" = "omos" ] || [ "$VARIANT" = "omos-with-pi" ]; then
+  run "bun (omos)"            "bun --version"
+  run "bunx symlink (omos)"   "test -L /usr/local/bin/bunx && readlink /usr/local/bin/bunx"
+  # oh-my-opencode-slim is npm-installed globally (not a bun install);
+  # verify it shows up in the global module list.
+  run "oh-my-opencode-slim"   "npm ls -g --depth=0 2>/dev/null | grep oh-my-opencode-slim"
+else
+  if docker run --rm --entrypoint="" "$IMAGE" sh -c "command -v bun" >/dev/null 2>&1; then
+    fail "bun should NOT be in base image but was found"
+  else
+    pass "bun correctly absent from base image"
+  fi
+fi
+
+echo
+echo "-- Entrypoint behaviour --"
+
+# Generate-config script exists and has valid syntax.
+run "generate-config.py exists" \
+    "test -x /usr/local/lib/opencode-devbox/generate-config.py && python3 -m py_compile /usr/local/lib/opencode-devbox/generate-config.py && echo ok"
+
+# Entrypoint drops to developer user and runs a trivial command.
+# Writes the result to a file inside the container so we don't have to
+# disentangle entrypoint log output from command stdout on the host.
+label="entrypoint drops to developer"
+tmpout=$(mktemp)
+if docker run --rm -e OPENCODE_PROVIDER= "$IMAGE" \
+    sh -c 'whoami > /tmp/who && cat /tmp/who' > "$tmpout" 2>/dev/null; then
+  # The last line of stdout is the whoami output. Entrypoint log lines
+  # (MemPalace init, "Adjusted developer UID", etc.) go to stderr or
+  # get printed before our sh command runs.
+  actual=$(tail -1 "$tmpout" | tr -d '[:space:]')
+  if [ "$actual" = "developer" ]; then
+    pass "$label"
+  else
+    fail "$label: expected 'developer', got '$actual' (full output: $(cat "$tmpout"))"
+  fi
+else
+  fail "$label: container failed"
+fi
+rm -f "$tmpout"
+
+# Config generation with anthropic provider writes valid JSONC with the
+# expected shape. The script's log message goes to stderr (line 1 of
+# generate-config.py uses file=sys.stderr) so capturing only stdout
+# gives us clean JSONC. We strip // comments before validating JSON.
+label="generate-config produces valid opencode.jsonc"
+tmp=$(mktemp -d)
+if docker run --rm \
+    -e OPENCODE_PROVIDER=anthropic \
+    -e HOME=/tmp/home \
+    --entrypoint="" \
+    "$IMAGE" sh -c '
+      mkdir -p /tmp/home
+      python3 /usr/local/lib/opencode-devbox/generate-config.py 2>/dev/null
+      cat /tmp/home/.config/opencode/opencode.jsonc
+    ' > "$tmp/out.jsonc" 2>/dev/null; then
+  # Strip single-line // comments for JSON validation (respecting strings)
+  if python3 -c "
+import re, json, sys
+text = open('$tmp/out.jsonc').read()
+# Match either a string literal or a // comment; keep strings, drop comments
+pattern = r'\"(?:\\\\.|[^\"\\\\])*\"|//[^\n]*'
+stripped = re.sub(pattern, lambda m: m.group(0) if m.group(0).startswith('\"') else '', text)
+c = json.loads(stripped)
+assert c['model'].startswith('anthropic/'), c
+assert c['autoupdate'] is False
+assert c['share'] == 'disabled'
+assert 'context7' in c.get('mcp', {}), 'context7 MCP not registered'
+" 2>&1; then
+    pass "$label"
+  else
+    fail "$label: output doesn't match expected shape: $(cat "$tmp/out.jsonc")"
+  fi
+else
+  fail "$label: container failed: $(cat "$tmp/out.jsonc")"
+fi
+
+# Config generation is idempotent — running twice must not overwrite.
+# Tests both legacy .json and new .jsonc detection.
+label="generate-config never overwrites existing config"
+if docker run --rm \
+    -e OPENCODE_PROVIDER=anthropic \
+    -e HOME=/tmp/home \
+    --entrypoint="" \
+    "$IMAGE" sh -c '
+      mkdir -p /tmp/home/.config/opencode
+      echo "{\"sentinel\": \"user-config\"}" > /tmp/home/.config/opencode/opencode.json
+      python3 /usr/local/lib/opencode-devbox/generate-config.py 2>/dev/null
+      cat /tmp/home/.config/opencode/opencode.json
+    ' 2>/dev/null | grep -q '"sentinel": "user-config"'; then
+  pass "$label"
+else
+  fail "$label: existing config was modified!"
+fi
+rm -rf "$tmp"
+
+echo
+echo "-- Image size --"
+SIZE_BYTES=$(docker image inspect --format='{{.Size}}' "$IMAGE")
+SIZE_MB=$((SIZE_BYTES / 1024 / 1024))
+echo "  Uncompressed size: ${SIZE_MB} MB"
+
+# Thresholds (uncompressed): base 2500 MB, omos 3200 MB, with-pi adds ~150 MB.
+# omos bumped 3000→3200 on v1.14.31c — mempalace-toolkit bake-in pushed the
+# omos variant to ~3.1 GB. Functional smoke checks all pass; this is a
+# guardrail, not a performance limit.
+THRESHOLD=2500
+[ "$VARIANT" = "omos" ] && THRESHOLD=3200
+[ "$VARIANT" = "with-pi" ] && THRESHOLD=2700
+[ "$VARIANT" = "omos-with-pi" ] && THRESHOLD=3400
+if [ "$SIZE_MB" -gt "$THRESHOLD" ]; then
+  fail "image size ${SIZE_MB} MB exceeds threshold ${THRESHOLD} MB for variant=$VARIANT"
+else
+  pass "image size ${SIZE_MB} MB within threshold ${THRESHOLD} MB"
+fi
+
+echo
+if [ "$FAILED" -gt 0 ]; then
+  echo "=== FAILED: $FAILED check(s) ===" >&2
+  exit 1
+fi
+echo "=== PASSED ==="