Fix dash-incompatible slash substitution and bump omos size threshold

v1.14.31b made it through smoke-base and validate-base (reclaim worked), but two narrow bugs blocked the rest: 1. 'Derive platform slug' in the per-arch matrix jobs used bash ${PLATFORM_PAIR//\//-} which dash (/bin/sh in the runner) can't parse — 'Bad substitution'. Rewrote with 'tr / -'. 2. smoke-omos image size 3107 MB tripped the 3000 MB guardrail. All functional checks pass; the mempalace-toolkit bake-in from v1.14.30b added ~100 MB and the threshold was stale. Bumped to 3200 MB. No image-level changes.
Reclaim runner disk before load: true smoke builds
2026-05-01 10:43:04 +00:00 · 2026-05-01 09:34:52 +00:00 · 2026-05-01 08:43:08 +00:00 · 2026-04-30 20:56:58 +00:00 · 2026-04-30 15:11:49 +02:00 · 2026-04-29 15:27:30 +02:00
15 changed files with 2069 additions and 523 deletions
@@ -5,8 +5,29 @@ on:
    tags:
      - 'v*'

+# Serialize concurrent runs of the same workflow on the same ref so the
+# matrix 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
+
+# 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). Building both
+# architectures of both variants on a single runner exhausted disk around the
+# nodejs dpkg unpack / git-lfs layer export. To fix this:
+#   * smoke test (amd64 only, load into daemon) runs on its own runner
+#   * each push target (variant × arch) runs on its own runner, pushes by
+#     digest (no local image store), uploads digest as an artifact
+#   * a merge job composes the multi-arch manifest with `imagetools create`
+# Per-runner disk pressure is now one-quarter of the old single-job peak.
+
 jobs:
-  build-base:
+  # ── Smoke test (amd64 only, gates the push jobs) ────────────────────
+  smoke-base:
    runs-on: ubuntu-latest
    container:
      image: catthehacker/ubuntu:act-latest
@@ -15,11 +36,135 @@ jobs:
        uses: actions/checkout@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: |
-          # Prefer IPv4 to avoid intermittent IPv6 connectivity failures
-          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+          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
+
+  # ── Per-arch push (by digest, no local image) ───────────────────────
+  build-base:
+    runs-on: ubuntu-latest
+    needs: smoke-base
+    container:
+      image: catthehacker/ubuntu:act-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
+    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: Derive platform slug
+        id: platform
+        run: |
+          # POSIX-safe slash substitution — act's runner container ships
+          # /bin/sh as dash, which doesn't support bash's ${VAR//a/b}.
+          echo "pair=$(echo '${{ matrix.platform }}' | tr / -)" >> $GITHUB_OUTPUT

      - name: Set up QEMU
+        if: matrix.platform != 'linux/amd64'
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
@@ -33,36 +178,55 @@ jobs:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

-      - name: Extract version from tag
-        id: version
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/}
-          echo "version=${VERSION}" >> $GITHUB_OUTPUT
-
-      - name: Build and push (base)
+      - name: Build and push by digest
+        id: build
        uses: docker/build-push-action@v7
        with:
          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          tags: |
-            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}
-            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest
+          platforms: ${{ matrix.platform }}
+          outputs: type=image,name=${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox,push-by-digest=true,name-canonical=true,push=true
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-base-${{ steps.platform.outputs.pair }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1

  build-omos:
    runs-on: ubuntu-latest
+    needs: smoke-omos
    container:
      image: catthehacker/ubuntu:act-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
    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: Derive platform slug
+        id: platform
        run: |
-          # Prefer IPv4 to avoid intermittent IPv6 connectivity failures
-          echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+          # POSIX-safe slash substitution — act's runner container ships
+          # /bin/sh as dash, which doesn't support bash's ${VAR//a/b}.
+          echo "pair=$(echo '${{ matrix.platform }}' | tr / -)" >> $GITHUB_OUTPUT

      - name: Set up QEMU
+        if: matrix.platform != 'linux/amd64'
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
@@ -76,27 +240,122 @@ jobs:
          username: ${{ vars.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            INSTALL_OMOS=true
+          outputs: type=image,name=${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox,push-by-digest=true,name-canonical=true,push=true
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-omos-${{ steps.platform.outputs.pair }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ── Merge per-arch digests into multi-arch tags ─────────────────────
+  merge-base:
+    runs-on: ubuntu-latest
+    needs: build-base
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-base-*
+          merge-multiple: true
+
+      - 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: |
-          VERSION=${GITHUB_REF#refs/tags/}
-          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+        run: echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT

-      - name: Build and push (omos)
-        uses: docker/build-push-action@v7
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create \
+            -t ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }} \
+            -t ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest \
+            $(printf '${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox@sha256:%s ' *)
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect \
+            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}
+
+  merge-omos:
+    runs-on: ubuntu-latest
+    needs: build-omos
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - name: Force IPv4 for Docker Hub
+        run: echo 'precedence ::ffff:0:0/96  100' >> /etc/gai.conf
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
        with:
-          context: .
-          platforms: linux/amd64,linux/arm64
-          push: true
-          build-args: |
-            INSTALL_OMOS=true
-          tags: |
+          path: /tmp/digests
+          pattern: digests-omos-*
+          merge-multiple: true
+
+      - 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: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create \
+            -t ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-omos \
+            -t ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-omos \
+            $(printf '${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox@sha256:%s ' *)
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect \
            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:${{ steps.version.outputs.version }}-omos
-            ${{ vars.DOCKERHUB_USERNAME }}/opencode-devbox:latest-omos

  update-description:
    runs-on: ubuntu-latest
-    needs: [build-base, build-omos]
+    needs: [merge-base, merge-omos]
    container:
      image: catthehacker/ubuntu:act-latest
    steps:
@@ -0,0 +1,149 @@
+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
@@ -4,5 +4,16 @@
 *~
 .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
@@ -6,12 +6,16 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d

 ## File roles

- `Dockerfile` — single multi-stage build for both variants. OMOS variant is controlled by `INSTALL_OMOS=true` build arg. All GitHub-sourced binaries are pinned with version ARGs.
- `entrypoint.sh` — runs as root: UID/GID adjustment, SSH permissions, volume ownership fixes. Then drops to developer via gosu.
- `entrypoint-user.sh` — runs as developer: git config, opencode.json generation from env vars, OMOS setup.
- `DOCKER_HUB.md` — pushed to Docker Hub description via CI API call. Must stay under 25KB. Short description field must be ≤100 bytes.
- `README.md` — source repo documentation. Must stay in sync with DOCKER_HUB.md (both describe the same features but for different audiences).
- `.gitea/workflows/docker-publish.yml` — CI pipeline: three parallel jobs (build-base, build-omos, update-description). Triggered by tag push only.
+- `Dockerfile` — single multi-stage build for both variants. OMOS variant is controlled by `INSTALL_OMOS=true` build arg; mempalace is controlled by `INSTALL_MEMPALACE` (default `true`). All GitHub-sourced binaries are pinned with version ARGs.
+- `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.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.json generation (delegated to `generate-config.py`), OMOS setup.
+- `rootfs/usr/local/lib/opencode-devbox/generate-config.py` — generates `~/.config/opencode/opencode.json` from env vars. Never overwrites an existing config. Auto-registers MCP servers for detected tools (mempalace via the `mempalace-mcp` entry point, gitea-mcp).
+- `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 `README.md` using explicit section rules. `--check` fails if the committed file is out of sync (enforced by the `validate` workflow).
+- `DOCKER_HUB.md` — **auto-generated** from README. 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. Sections are selected/dropped/replaced for DOCKER_HUB.md per `SECTION_RULES` in `scripts/generate-dockerhub-md.py`.
+- `.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` — 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.

 ## Versioning scheme

@@ -28,25 +32,41 @@ When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile`

 ## 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.
- **Three docs to keep in sync** — Dockerfile changes that add tools or features must be reflected in `README.md`, `DOCKER_HUB.md`, and `.env.example`. The docker-compose examples in both docs must match the source `docker-compose.yml` pattern.
- **GitHub-sourced binaries** — fzf, gosu, git-lfs, neovim, bat, eza, zoxide, uv, rustup are installed from upstream releases (not apt) with pinned versions. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64).
+- **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.
+- **Two docs to keep in sync (automated)** — `README.md` is the source of truth. `DOCKER_HUB.md` is auto-generated by `scripts/generate-dockerhub-md.py`. When adding a new top-level section to README, either add it to `SECTION_RULES` in that script or the `--check` run will fail CI. `.env.example` must still be hand-updated to match Dockerfile/entrypoint behavior.
+- **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.json` — system Python can't import from the uv venv.
+- **generate-config.py idempotency** — the script MUST never overwrite an existing `opencode.json`. Users bind-mount their config directory or persist it across container recreations; accidentally clobbering that file would destroy hand-edits. The smoke test asserts this.
 - **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 CI. Pushing to `main` alone does not build images.
+- 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.

 ## Testing changes

-No test suite. Verify by:
-1. Building locally: `docker compose build`
-2. Running: `docker compose run --rm devbox bash`
-3. Checking tool availability inside container: `nvim --version`, `bat --version`, `uv --version`, etc.
-4. For entrypoint changes: test with a non-1000 UID workspace to verify UID adjustment and volume ownership fixes.
+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

@@ -6,6 +6,100 @@ Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a

 ---

+## 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.
@@ -13,6 +13,8 @@ Two image variants are published for each release:

 Both variants support `linux/amd64` and `linux/arm64`.

+> **NOTE:** This file is auto-generated from `README.md` by `scripts/generate-dockerhub-md.py`. Edit README.md and regenerate rather than editing this file directly.
+
 ## Quick Start

 ```bash
@@ -28,9 +30,7 @@ docker run -it --rm \

 This 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):

 ```bash
 docker run -it --rm \
@@ -43,237 +43,141 @@ docker run -it --rm \

 Then run `opencode` when ready.

-## Running Multiple Shells
+For docker-compose users, see the source repo for `docker-compose.yml` and `.env.example` templates.

-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:
+## Features
+
+- **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)
+- **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
-# 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
+# Required: workspace for your projects
+mkdir -p ~/projects

-# Shell 1: run opencode
-docker exec -it -u developer devbox opencode
-
-# Shell 2 (separate terminal): aws, git, etc.
-docker exec -it -u developer devbox bash
-
-# When done
-docker rm -f devbox
+# If mounting opencode config (recommended for persistent settings)
+mkdir -p ~/.config/opencode
 ```

-> **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.
+### Connecting to the container

-## Environment Variables
+From your laptop, SSH into the remote server where Docker is running, then start the container:

-All configuration is done via environment variables, typically stored in a `.env` file.
+```bash
+# 1. SSH into the remote server
+ssh user@remote-server

-### Provider Configuration
+# 2. Navigate to the project
+cd opencode-devbox
+
+# 3. Start the container with an interactive shell
+docker compose run --rm devbox bash
+
+# You're now inside the container — run commands here
+aws sso login --sso-session <your-sso-session> --use-device-code
+opencode
+```
+
+### Running modes
+
+**Interactive shell** — enter the container, run multiple commands:
+```bash
+docker compose run --rm devbox bash
+```
+
+**Direct to opencode** — skips the shell, launches opencode immediately:
+```bash
+docker compose run --rm devbox
+```
+
+**Background container** — keep it running, attach when needed:
+```bash
+# Start in background
+docker compose up -d
+
+# Attach a shell to the running container
+docker compose exec -u developer devbox bash
+
+# Or run a single command inside it
+docker compose exec -u developer devbox aws --version
+```
+
+> `run` creates a new container (cleaned up with `--rm`). `exec` attaches to an already running one.
+
+## Configuration
+
+### Environment Variables

 | Variable | Description | Default |
 |---|---|---|
 | `OPENCODE_PROVIDER` | LLM provider (`anthropic`, `openai`, `amazon-bedrock`) | `anthropic` |
 | `OPENCODE_MODEL` | Model override | Provider default |
-
-### API Keys
-
-Set the key matching your provider:
-
-| Variable | Provider |
-|---|---|
-| `ANTHROPIC_API_KEY` | Anthropic |
-| `OPENAI_API_KEY` | OpenAI |
-| `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` | AWS Bedrock (static creds) |
-
-### AWS Bedrock
-
-| Variable | Description | Default |
-|---|---|---|
-| `AWS_REGION` | AWS region | `us-east-1` |
+| `ANTHROPIC_API_KEY` | Anthropic API key | — |
+| `OPENAI_API_KEY` | OpenAI API key | — |
+| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
 | `AWS_PROFILE` | AWS SSO profile name | `default` |
-
-### Git
-
-| 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 |
-
-### Locale and Editor
-
-The container defaults to English (`en_US.UTF-8`) and neovim as the editor. Override via environment variables:
-
-| Variable | Description | Default |
-|---|---|---|
+| `GIT_USER_NAME` | Git commit author name | — |
+| `GIT_USER_EMAIL` | Git commit author email | — |
+| `WORKSPACE_PATH` | Host path to mount | `.` |
+| `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` |

-Pre-generated locales: `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` (all UTF-8).
-
-Example for Swedish:
-
-```bash
-LANG=sv_SE.UTF-8
-LANGUAGE=sv_SE:sv
-LC_ALL=sv_SE.UTF-8
-```
-
-To add a locale not in the list, run inside the container:
-
-```bash
-sudo sed -i '/xx_XX.UTF-8/s/^# //g' /etc/locale.gen
-sudo locale-gen
-```
-
-Replace `xx_XX` with the desired locale (e.g. `ru_RU`, `tr_TR`). This change does not persist across container restarts — for permanent additions, build from source and modify the Dockerfile.
-
-## Initial Setup
-
-### 1. Create host directories
-
-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
-mkdir -p ~/projects
-
-# If mounting opencode config (recommended for persistent settings)
-mkdir -p ~/.config/opencode
-
-# If using AWS Bedrock
-# mkdir -p ~/.aws
-
-# If mounting neovim config
-# mkdir -p ~/.config/nvim
-```
-
-### 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/eu.anthropic.claude-opus-4-6-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/.local/state/opencode` | Named volume (if configured) | ✅ Yes — Docker volume | TUI settings (theme, toggles) |
-| `/home/developer/.cache/bash` | Named volume `devbox-shell-history` | ✅ Yes — Docker volume | Bash history (`$HISTFILE`) — survives container recreate |
-| `/home/developer/.local/share/zoxide` | Named volume `devbox-zoxide` | ✅ Yes — Docker volume | Zoxide directory history (`z <fragment>` jump targets) |
-| `/home/developer/.local/share/nvim` | Named volume `devbox-nvim-data` | ✅ Yes — Docker volume | Neovim plugins, Mason LSP installs, Lazy plugin cache |
-| `/home/developer/.local/share/uv` | Named volume (if configured) | ✅ Yes — Docker volume | Python installs, uv tool installs |
-| `/home/developer/.rustup` | Named volume (if configured) | ✅ Yes — Docker volume | Rust toolchains |
-| `/home/developer/.cargo` | Named volume (if configured) | ✅ Yes — Docker volume | Cargo binaries, registry cache |
-| `/home/developer/.vscode-server` | Named volume (if configured) | ✅ Yes — Docker volume | VS Code server and extensions |
-| `/home/developer/.config/opencode` | Host bind mount (if configured) | ✅ Yes — lives on host | opencode.json, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
-
-### 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 if no existing config is found. To persist config changes, mount the config directory from the host (see Custom opencode Config below).
- **opencode data** (session history, memory) is lost on container recreation unless you add a named volume.
- **TUI settings** (theme, toggles) are lost on container recreation unless you add the `devbox-state` named volume.
- **Bash history** persists via the `devbox-shell-history` volume mounted at `~/.cache/bash`. `HISTFILE` is pre-configured; no setup required.
- **Python installs** via `uv python install` are lost on container recreation unless you add the `devbox-uv` named volume.
- **Rust toolchains** via `rustup-init` are lost on container recreation unless you add the `devbox-rustup` and `devbox-cargo` named volumes.
- **AWS SSO tokens** persist across restarts when `~/.aws` is mounted (recommended for Bedrock users).
-
-## Custom opencode Config
+### Custom opencode config

 For full control over opencode settings (MCP servers, custom models, and — on the OMOS variant — oh-my-opencode-slim agents), mount the entire config directory from the host:

-```bash
-docker run -it --rm \
-  -v ~/.config/opencode:/home/developer/.config/opencode \
-  ... \
-  joakimp/opencode-devbox:latest
+```yaml
+volumes:
+  - ~/.config/opencode:/home/developer/.config/opencode
 ```

-This persists all configuration changes across container restarts. When an existing `opencode.json` is found, the `OPENCODE_PROVIDER` auto-config is skipped.
+This persists all configuration changes across container restarts, including `opencode.json`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json`. When an existing `opencode.json` is found, the `OPENCODE_PROVIDER` auto-config is skipped.

 > **Portability note:** The mounted config runs inside a Linux container. Any absolute paths inside `opencode.json` (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.

-## Neovim Configuration
+### Custom skills
+
+Mount agent skills from the host:
+
+```yaml
+volumes:
+  - ~/.agents/skills:/home/developer/.agents/skills:ro
+```
+
+### 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:

-```bash
-docker run -it --rm \
-  -v ~/.config/nvim:/home/developer/.config/nvim:ro \
-  ... \
-  joakimp/opencode-devbox:latest
+```yaml
+volumes:
+  - ~/.config/nvim:/home/developer/.config/nvim:ro
 ```

-## Python Development with uv
+### 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:

@@ -298,18 +202,19 @@ uvx ruff check .
 uv python install 3.14
 ```

-To persist Python installs across container restarts, add a named volume:
+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`:

-```bash
-docker run -it --rm \
-  -v devbox-uv:/home/developer/.local/share/uv \
-  ... \
-  joakimp/opencode-devbox:latest
+```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
+### Rust development with rustup

 The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:

@@ -324,17 +229,19 @@ cargo build
 cargo run
 ```

-To persist Rust toolchains and cargo data across container restarts, add named volumes:
+To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:

-```bash
-docker run -it --rm \
-  -v devbox-rustup:/home/developer/.rustup \
-  -v devbox-cargo:/home/developer/.cargo \
-  ... \
-  joakimp/opencode-devbox:latest
+```yaml
+volumes:
+  - devbox-rustup:/home/developer/.rustup
+  - devbox-cargo:/home/developer/.cargo
+
+volumes:
+  devbox-rustup:
+  devbox-cargo:
 ```

-## JavaScript and TypeScript
+### JavaScript and TypeScript

 The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:

@@ -347,6 +254,9 @@ 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:
@@ -359,187 +269,76 @@ bun run src/index.ts

 Node modules are stored in your project directory under `/workspace` and persist automatically.

-## VS Code Integration
+### 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.

-**Requirements:** Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension. For remote Docker hosts, also install [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh).
+**Local Docker (Docker running on your workstation):**

-**Steps:**
+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`

-1. Start the container: `docker compose up -d`
-2. 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):**

-For remote Docker hosts (e.g. connecting to a server via SSH), first connect to the remote host with Remote-SSH, then attach to the container from there.
+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. For persistent extension storage across container recreations, add a named volume:
-
-```bash
-docker run -it --rm \
-  -v devbox-vscode:/home/developer/.vscode-server \
-  ... \
-  joakimp/opencode-devbox:latest
-```
-
-## 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/eu.anthropic.claude-opus-4-6-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`:
+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
-services:
-  devbox:
-    image: joakimp/opencode-devbox:latest
-    # For multi-agent orchestration, use the omos variant instead:
-    # image: joakimp/opencode-devbox:latest-omos
-    container_name: opencode-devbox
-    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
-      - devbox-state:/home/developer/.local/state/opencode
-      - devbox-uv:/home/developer/.local/share/uv
-      # Optional: persist Rust toolchains and cargo data
-      # - devbox-rustup:/home/developer/.rustup
-      # - devbox-cargo:/home/developer/.cargo
-      # Optional: persist VS Code server and extensions
-      # - devbox-vscode:/home/developer/.vscode-server
-      # Mount AWS config for Bedrock SSO (required for amazon-bedrock provider)
-      # - ~/.aws:/home/developer/.aws
-      # Optional: mount opencode config directory (persists config changes across restarts)
-      # - ~/.config/opencode:/home/developer/.config/opencode
-      # Optional: mount opencode agent skills from host
-      # - ~/.agents/skills:/home/developer/.agents/skills:ro
-      # Optional: mount neovim config from host (plugins auto-install on first start)
-      # - ~/.config/nvim:/home/developer/.config/nvim:ro
-
 volumes:
-  devbox-data:
-  devbox-state:
-  devbox-uv:
-  # devbox-rustup:
-  # devbox-cargo:
-  # devbox-vscode:
+  - devbox-vscode:/home/developer/.vscode-server
 ```

-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.
+## oh-my-opencode-slim (Multi-Agent Orchestration)

-Then:
+[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) adds a multi-agent layer on top of opencode — an Orchestrator delegates tasks to specialized agents (Explorer, Oracle, Librarian, Designer, Fixer), each configurable with different models and providers.
+
+### Setup
+
+A pre-built OMOS image is available on Docker Hub as `joakimp/opencode-devbox:latest-omos`. Alternatively, build from source:
+
+**1. Build the image with OMOS support:**

 ```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
+docker compose build --build-arg INSTALL_OMOS=true
 ```

-## Shell defaults
+This installs Bun and the oh-my-opencode-slim package into the image.

-The image ships baked `.bash_aliases` and `.inputrc` in `/etc/skel-devbox/`. On first container start the entrypoint copies them to `/home/developer/` **only if the target file does not already exist**, so your host bind-mounts or any in-container customization are preserved across upgrades.
-
- **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** via `$HISTFILE=~/.cache/bash/history`, backed by the `devbox-shell-history` named volume. Survives container recreate. 100 000 entries, time-stamped, dedup.
- **Case-insensitive tab completion** and coloured completion lists.
- **Aliases** — `ls`/`ll`/`la` → `eza`, `cat` → `bat`, `gs`/`gd`/`gl` for git, interactive `rm`/`mv`/`cp`.
- **Integrations** — `zoxide` (`z <fragment>`), `fzf` key bindings (`Ctrl-R`, `Ctrl-T`).
- **`[devbox]` prompt prefix** so you always know you're in the container.
-
-To override with your host's own files, uncomment the matching bind-mount lines in `docker-compose.yml`. To restore the baked defaults any time: `cp /etc/skel-devbox/.bash_aliases ~/` (or delete the file and recreate the container).
-
-## What's Included
-
-### Base image (`latest`)
-
- **Debian trixie-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, git-crypt, age, ssh, ripgrep, fd, fzf, bat, eza, zoxide, uv, rustup, jq, make, gcc, g++, curl, wget, neovim 0.12, tmux, htop, tree, rsync
- **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
- **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
+**2. Enable in `.env`:**

 ```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
+ENABLE_OMOS=true
 ```

-On first start, the entrypoint configures oh-my-opencode-slim automatically. The default preset uses OpenAI models.
+**3. Run as normal:**

-### OMOS environment variables
+```bash
+docker compose run --rm devbox
+```
+
+On first start, the entrypoint runs the oh-my-opencode-slim installer in non-interactive mode. It generates agent configuration at `~/.config/opencode/oh-my-opencode-slim.json` inside the container. The default preset uses OpenAI models — edit the generated config or mount your own to customize.
+
+### 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_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 OMOS configuration
+### Custom Configuration

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

 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
+### Verifying Agents

 After starting opencode with OMOS enabled, run inside the opencode session:

@@ -549,12 +348,260 @@ ping all agents

 All six agents should respond if your provider authentication is working.

-## Multi-User Setup
+## AWS Bedrock Authentication

-This guide covers single-user setup. For running multiple opencode-devbox instances in parallel — whether each user has their own OS account or everyone shares one login — see the [Multi-user setup section](https://gitea.jordbo.se/joakimp/opencode-devbox#multi-user-setup) in the source repository. It covers volume isolation, the `docker-compose.shared.yml` layout, and the `SIGNUM` / `$USER` auto-detection mechanism.
+When using AWS Bedrock as your LLM provider, you need:
+
+### 1. AWS config on the host
+
+The container needs access to your `~/.aws/config` with 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 on the host:
+
+```bash
+aws configure sso
+```
+
+### 2. Mount `~/.aws` into the container
+
+Uncomment the AWS volume mount in `docker-compose.yml`:
+
+```yaml
+- ~/.aws:/home/developer/.aws
+```
+
+Note: do **not** use `:ro` — SSO writes token cache files to this directory.
+
+### 3. Authenticate inside the container
+
+Since the container runs headless (no browser), use the device-code flow:
+
+```bash
+# Start the container
+docker compose up -d
+docker compose exec -u developer devbox bash
+
+# Authenticate — prints a URL and code you open in your local browser
+aws sso login --sso-session <your-sso-session> --use-device-code
+
+# Once approved in the browser, start opencode
+opencode
+```
+
+The `--use-device-code` flag outputs a URL and short code instead of trying to open a browser. Copy the URL into any browser (on your laptop, phone, etc.), enter the code, and complete the 2FA flow. The CLI in the container picks up the session automatically.
+
+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.json` (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.json`:
+   ```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.
+
+## 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
+```
+
+## Architecture
+
+```
+Host Machine
+├── ~/projects/my-app  ──bind mount──▶  /workspace (container)
+├── ~/.ssh             ──bind mount──▶  /home/developer/.ssh (ro)
+├── ~/.aws             ──bind mount──▶  /home/developer/.aws (Bedrock SSO)
+└── .env               ──env vars───▶  provider config + API keys
+
+Container (Debian trixie)
+├── opencode binary
+├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
+├── AWS CLI v2 (SSO + Bedrock auth)
+├── 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)
+├── entrypoint.sh (UID adjustment, git config, provider setup)
+└── /workspace ← your code lives here
+```
+
+### Data persistence
+
+| Path in container | Source | Survives `--rm`? | Contains |
+|---|---|---|---|
+| `/workspace` | Host bind mount | ✅ Yes | Your project files |
+| `/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/.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` | Host bind mount (if configured) | ✅ Yes | opencode.json, 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 persist config changes and use custom settings, mount the config directory from the host (see Custom opencode config above).

 ## Source

-Build from source or contribute: [opencode-devbox on Gitea](https://gitea.jordbo.se/joakimp/opencode-devbox)
-
-See the [Changelog](https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/CHANGELOG.md) for a full release history.
+MIT licensed. Source, issues, and `docker-compose.yml` templates: <https://gitea.jordbo.se/joakimp/opencode-devbox>
@@ -5,7 +5,7 @@ ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base

 ARG TARGETARCH
-ARG OPENCODE_VERSION=1.14.28
+ARG OPENCODE_VERSION=1.14.31

 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 \
@@ -45,76 +50,211 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
    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

-# neovim — modern text editor (pre-built release from GitHub)
-ARG NVIM_VERSION=0.12.1
+# neovim — modern text editor
+ARG NVIM_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;; *) echo "x86_64" ;; esac) && \
-    curl -fsSL "https://github.com/neovim/neovim/releases/download/v${NVIM_VERSION}/nvim-linux-${ARCH}.tar.gz" | tar -xz -C /opt && \
+    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=0.26.1
+ARG BAT_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
-    curl -fsSL "https://github.com/sharkdp/bat/releases/download/v${BAT_VERSION}/bat-v${BAT_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
-    install /tmp/bat-v${BAT_VERSION}-${ARCH}-unknown-linux-musl/bat /usr/local/bin/bat && \
-    rm -rf /tmp/bat-v${BAT_VERSION}-* && \
+    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=0.23.4
+ARG EZA_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
-    curl -fsSL "https://github.com/eza-community/eza/releases/download/v${EZA_VERSION}/eza_${ARCH}-unknown-linux-gnu.tar.gz" | tar -xz -C /usr/local/bin && \
+    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=0.9.9
+ARG ZOXIDE_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
-    curl -fsSL "https://github.com/ajeetdsouza/zoxide/releases/download/v${ZOXIDE_VERSION}/zoxide-${ZOXIDE_VERSION}-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /usr/local/bin zoxide && \
+    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)
-ARG UV_VERSION=0.11.7
+# 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) && \
-    curl -fsSL "https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/uv-${ARCH}-unknown-linux-musl.tar.gz" | tar -xz -C /tmp && \
+    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 "https://static.rust-lang.org/rustup/dist/${ARCH}-unknown-linux-gnu/rustup-init" -o /usr/local/bin/rustup-init && \
+    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
@@ -126,7 +266,7 @@ 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/*

@@ -141,26 +281,28 @@ 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.26.2
+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
@@ -179,12 +321,14 @@ RUN if [ "${INSTALL_OMOS}" = "true" ]; then \
      elif [ "$ARCH" = "aarch64" ]; then \
        BUN_ARCH="aarch64"; \
      fi && \
-      curl -fsSL "https://github.com/oven-sh/bun/releases/latest/download/bun-linux-${BUN_ARCH}.zip" -o /tmp/bun.zip && \
+      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

@@ -220,9 +364,11 @@ 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
@@ -327,19 +327,25 @@ 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_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) |
-| `OMOS_VERSION` | `latest` | Pin a specific oh-my-opencode-slim version |
+| `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)

@@ -444,6 +450,126 @@ 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.json` (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.json`:
+   ```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.
+
 ## 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.
@@ -36,6 +36,8 @@ services:
      - .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
@@ -61,6 +63,12 @@ services:
      # 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

@@ -70,3 +78,5 @@ volumes:
  devbox-zoxide:
  devbox-nvim-data:
  devbox-uv:
+  # devbox-palace:
+  # devbox-chroma-cache:
@@ -23,7 +23,6 @@ services:
    # build:
    #   context: .
    #   args:
-    #     INSTALL_PYTHON: "false"
    #     INSTALL_GO: "false"
    #     INSTALL_OMOS: "false"
    container_name: opencode-devbox
@@ -33,6 +32,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
@@ -75,7 +77,7 @@ services:
      # 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
+       # - ~/.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.
@@ -92,6 +94,16 @@ services:
      # 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

@@ -102,6 +114,8 @@ volumes:
  devbox-zoxide:
  devbox-nvim-data:
  devbox-uv:
+  # devbox-palace:
+  # devbox-chroma-cache:
  # devbox-rustup:
  # devbox-cargo:
  # devbox-vscode:
@@ -15,6 +15,20 @@ if [ -d "$SKEL_DIR" ]; then
  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)..."
+    mempalace init --yes /workspace >/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"
@@ -24,64 +38,14 @@ if [ -n "${GIT_USER_EMAIL:-}" ] && ! git config --global user.email &>/dev/null;
 fi

 # ── Generate opencode config from env vars if no config mounted ──────
+# 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
+
 CONFIG_DIR="$HOME/.config/opencode"
-CONFIG_FILE="$CONFIG_DIR/opencode.json"
-
-if [ ! -f "$CONFIG_FILE" ] && [ -n "${OPENCODE_PROVIDER:-}" ]; then
-  echo "Generating opencode config for provider: $OPENCODE_PROVIDER"
-  mkdir -p "$CONFIG_DIR"
-
-  case "$OPENCODE_PROVIDER" in
-    anthropic)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-6}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-    openai)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-openai/gpt-5.4}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-    amazon-bedrock)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-amazon-bedrock/global.anthropic.claude-sonnet-4-5-20250929-v1:0}",
-  "share": "disabled",
-  "autoupdate": false,
-  "provider": {
-    "amazon-bedrock": {
-      "options": {
-        "region": "${AWS_REGION:-us-east-1}",
-        "profile": "${AWS_PROFILE:-default}"
-      }
-    }
-  }
-}
-EOF
-      ;;
-    *)
-      cat > "$CONFIG_FILE" <<EOF
-{
-  "\$schema": "https://opencode.ai/config.json",
-  "model": "${OPENCODE_MODEL:-anthropic/claude-sonnet-4-6}",
-  "share": "disabled",
-  "autoupdate": false
-}
-EOF
-      ;;
-  esac
-fi
+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
@@ -89,7 +53,7 @@ fi
 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
@@ -106,7 +70,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}"
@@ -123,7 +87,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}" \
@@ -79,16 +79,41 @@ for dir in \
  /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"/.agents/skills; do
-  if [ -d "$dir" ] && [ "$(stat -c '%u' "$dir" 2>/dev/null)" != "$FINAL_UID" ]; then
+  [ -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 ──────────────────────
@@ -0,0 +1,157 @@
+#!/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,
+        }
+
+    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.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.
+    if config_file.exists():
+        print(
+            f"Existing opencode.json found at {config_file} — "
+            "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)
+    with config_file.open("w") as f:
+        json.dump(config, f, indent=2)
+        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())
@@ -0,0 +1,290 @@
+#!/usr/bin/env python3
+"""
+Generate DOCKER_HUB.md from README.md.
+
+Rationale
+---------
+README.md is the authoritative source. DOCKER_HUB.md is a subset
+intended for users pulling the pre-built image from Docker Hub — so
+build-from-source instructions, developer setup (git hooks, gitleaks),
+and CI/contribution content are dropped.
+
+Docker Hub enforces a 25 kB limit on the full description field.
+
+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
+
+Design
+------
+Sections are selected and in some cases rewritten via `SECTION_RULES`
+below. This keeps the transformation explicit and easy to audit — if
+a new section is added to README.md that should also appear on Docker
+Hub, extend SECTION_RULES rather than inventing implicit heuristics.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+README = REPO_ROOT / "README.md"
+DOCKER_HUB = REPO_ROOT / "DOCKER_HUB.md"
+
+# Max size for Docker Hub full_description (bytes, UTF-8).
+MAX_SIZE_BYTES = 25_000
+
+# Per-section transformation.
+#
+# Each key is a top-level section title as it appears in README.md
+# (without the leading "## ").
+#
+# The value is one of:
+#   "keep"      — include verbatim.
+#   "drop"      — exclude entirely.
+#   "replace"   — substitute a custom body (see REPLACEMENTS).
+#   "trim"      — keep but drop selected level-3 sub-sections listed
+#                 in TRIM_SUBSECTIONS[title].
+#
+# Unknown sections default to "drop" with a warning — forcing an
+# explicit decision whenever README gains a new section.
+SECTION_RULES: dict[str, str] = {
+    "Why?": "drop",                             # build-motivation, not user-facing
+    "Quick Start": "replace",                   # swap docker compose clone flow for docker run
+    "Features": "keep",
+    "Usage": "keep",
+    "Configuration": "trim",                    # drop dev-build sub-sections
+    "oh-my-opencode-slim (Multi-Agent Orchestration)": "keep",
+    "AWS Bedrock Authentication": "keep",
+    "MemPalace — persistent AI memory": "keep",
+    "Gitea MCP server": "keep",
+    "Shell defaults": "keep",
+    "Secret Scanning": "drop",                  # dev-only — gitleaks is for committers
+    "Architecture": "keep",
+    "License": "replace",                       # point at source repo instead
+}
+
+# Level-3 sub-section titles (without the leading "### ") to drop from
+# sections flagged as "trim". These are dev/build-oriented — Docker Hub
+# users already have the image and don't need rebuild or multi-user
+# compose instructions.
+TRIM_SUBSECTIONS: dict[str, set[str]] = {
+    "Configuration": {
+        "Multi-user setup",
+        "Rebuilding the Image",
+        "Build Args",
+    },
+}
+
+# Replacement bodies. Keys match SECTION_RULES entries marked "replace".
+# Each value is the full section including the "## Title" heading.
+REPLACEMENTS: dict[str, str] = {
+    "Quick Start": """## 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
+```
+
+This drops you straight into opencode with your project mounted at `/workspace`.
+
+For an interactive shell first (useful for AWS SSO login):
+
+```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` when ready.
+
+For docker-compose users, see the source repo for `docker-compose.yml` and `.env.example` templates.
+""",
+    "License": """## Source
+
+MIT licensed. Source, issues, and `docker-compose.yml` templates: <https://gitea.jordbo.se/joakimp/opencode-devbox>
+""",
+}
+
+
+# Prepended to the generated file.
+HEADER = """# opencode-devbox — Docker Hub
+
+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
+
+Two image variants are published for each release:
+
+| 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 |
+
+Both variants support `linux/amd64` and `linux/arm64`.
+
+> **NOTE:** This file is auto-generated from `README.md` by `scripts/generate-dockerhub-md.py`. Edit README.md and regenerate rather than editing this file directly.
+
+"""
+
+
+def split_sections(md: str) -> list[tuple[str, str]]:
+    """Split markdown on level-2 headings, returning (title, body) pairs.
+
+    The body includes the heading line and everything up to (but not
+    including) the next level-2 heading or EOF. Content before the first
+    ``## `` is returned with an empty title (the document preamble).
+    """
+    pattern = re.compile(r"^## ", re.MULTILINE)
+    parts = pattern.split(md)
+    preamble, *rest = parts
+
+    sections: list[tuple[str, str]] = []
+    if preamble.strip():
+        sections.append(("", preamble))
+    for part in rest:
+        line, _, body = part.partition("\n")
+        sections.append((line.strip(), f"## {line}\n{body}"))
+    return sections
+
+
+def trim_subsections(body: str, drop: set[str]) -> str:
+    """Remove level-3 sub-sections whose title is in `drop`.
+
+    A sub-section starts at a line beginning with "### " and ends at
+    the next "### " or "## " (or EOF).
+    """
+    if not drop:
+        return body
+
+    # Split on level-3 headings while preserving the level-2 header
+    # block. First piece is everything up to the first "### ".
+    parts = re.split(r"(^### .+\n)", body, flags=re.MULTILINE)
+    # parts alternates: [before_first_h3, "### Title\n", body, "### Title\n", body, ...]
+    kept: list[str] = [parts[0]] if parts else []
+    i = 1
+    while i < len(parts):
+        heading = parts[i]
+        content = parts[i + 1] if i + 1 < len(parts) else ""
+        title = heading[4:].strip()
+        if title not in drop:
+            kept.append(heading)
+            kept.append(content)
+        i += 2
+    return "".join(kept)
+
+
+def generate() -> str:
+    """Produce the DOCKER_HUB.md content string."""
+    readme = README.read_text(encoding="utf-8")
+    sections = split_sections(readme)
+
+    out: list[str] = [HEADER]
+    unknown: list[str] = []
+
+    for title, body in sections:
+        if title == "":
+            # README preamble is replaced by our HEADER; skip.
+            continue
+
+        rule = SECTION_RULES.get(title)
+        if rule is None:
+            unknown.append(title)
+            continue
+        if rule == "drop":
+            continue
+        if rule == "keep":
+            out.append(body.rstrip() + "\n\n")
+        elif rule == "trim":
+            trimmed = trim_subsections(body, TRIM_SUBSECTIONS.get(title, set()))
+            out.append(trimmed.rstrip() + "\n\n")
+        elif rule == "replace":
+            out.append(REPLACEMENTS[title].rstrip() + "\n\n")
+        else:  # pragma: no cover — programmer error
+            raise AssertionError(f"unknown rule {rule!r} for section {title!r}")
+
+    if unknown:
+        print(
+            "ERROR: README.md contains sections not classified in "
+            "SECTION_RULES:\n  - "
+            + "\n  - ".join(unknown)
+            + "\n\nAdd each to SECTION_RULES in "
+            "scripts/generate-dockerhub-md.py (choose keep/drop/replace).",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    return "".join(out).rstrip() + "\n"
+
+
+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 README.md.\n"
+                "Run: python3 scripts/generate-dockerhub-md.py",
+                file=sys.stderr,
+            )
+            # Show a small diff hint.
+            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 README.md "
+            f"({size} bytes, {MAX_SIZE_BYTES} limit).",
+        )
+        return 0
+
+    DOCKER_HUB.write_text(content, encoding="utf-8")
+    print(
+        f"Wrote {DOCKER_HUB} ({size} bytes, {MAX_SIZE_BYTES} limit).",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -0,0 +1,234 @@
+#!/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]
+#
+# 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]" >&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 '
+  printf "  %-15s %s\n" "opencode"      "$(opencode --version 2>&1 | head -1)"
+  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 --"
+run "opencode"          "opencode --version"
+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
+
+# bun: only in the omos variant
+if [ "$VARIANT" = "omos" ]; 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 JSON 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 JSON.
+label="generate-config produces valid opencode.json"
+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.json
+    ' > "$tmp/out.json" 2>/dev/null; then
+  if python3 -c "
+import json, sys
+c = json.load(open('$tmp/out.json'))
+assert c['model'].startswith('anthropic/'), c
+assert c['autoupdate'] is False
+assert c['share'] == 'disabled'
+" 2>&1; then
+    pass "$label"
+  else
+    fail "$label: output doesn't match expected shape: $(cat "$tmp/out.json")"
+  fi
+else
+  fail "$label: container failed: $(cat "$tmp/out.json")"
+fi
+
+# Config generation is idempotent — running twice must not overwrite.
+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. Adjust as image content evolves.
+# 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
+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 ==="