v2.1.1: bump opencode 1.17.5->1.17.6

Patch release. Upstream 1.17.6 is a single MCP-compatibility bugfix (no breaking/runtime/AVX changes). Also lands the unreleased mempalace-toolkit SHA-resolution CI fix and two doc corrections; the toolkit change advances the base hash so this carries a base rebuild + base-latest re-promote.

.env.example

@@ -98,5 +98,9 @@ SSH_KEY_PATH=~/.ssh
 # Requires image built with INSTALL_OMOS=true
 # ENABLE_OMOS=false
 # OMOS_TMUX=false              # Enable tmux multiplexer integration
-# OMOS_SKILLS=true             # Install recommended skills (simplify, agent-browser, cartography)
-# OMOS_RESET=false             # Force regenerate oh-my-opencode-slim config on next start
+# OMOS_SKILLS=true             # Symlink bundled OMOS skills (clonedeps, codemap,
+#                              # deepwork, oh-my-opencode-slim, simplify) from the
+#                              # image into ~/.agents/skills/ each start; updates
+#                              # on image pull. Independent of ENABLE_OMOS.
+#                              # See docs/omos-skills.md
+# OMOS_RESET=false             # Force regenerate oh-my-opencode-slim config on next start (does not affect skills)

.gitea/README.md

@@ -75,7 +75,13 @@ The split-base architecture is what the `docker-publish-split.yml` workflow exer
                   └──────────────────────────┘
 ```
 
-### Step 1: `base-decide` (and `resolve-versions` in parallel)
+### Step 1: `resolve-versions`, then `base-decide`
+
+**`resolve-versions`** resolves floating refs to concrete values: `omos_version`
+(npm `latest`) and `mempalace_toolkit_ref` (the `mempalace-toolkit` `main` HEAD
+resolved to a commit SHA via the gitea commits API). **`base-decide`** now
+**depends on `resolve-versions`** (they no longer run in parallel) because it
+folds `mempalace_toolkit_ref` into the base hash — see below.
 
 **`base-decide`** computes a SHA-256 hash over the inputs that determine
 the base image's content:
@@ -90,6 +96,9 @@ the base image's content:
     ! -name '._*' \
     -print0 | sort -z | xargs -0 cat
   cat entrypoint.sh entrypoint-user.sh
+  echo "$mempalace_toolkit_ref"   # CI-resolved SHA; mempalace-toolkit is
+                                  # cloned in Dockerfile.base, so a moved
+                                  # toolkit must force a base rebuild
 } | sha256sum | cut -c1-12
 ```
 

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

@@ -48,6 +48,7 @@ env:
 jobs:
   # ── Phase 1: decide whether base needs rebuilding ──────────────────
   base-decide:
+    needs: [resolve-versions]
     runs-on: ubuntu-latest
     container:
       image: catthehacker/ubuntu:act-latest
@@ -77,6 +78,10 @@ jobs:
                 ! -name '._*' \
                 -print0 2>/dev/null | sort -z | xargs -0 cat 2>/dev/null
               cat entrypoint.sh entrypoint-user.sh
+              # mempalace-toolkit is cloned in Dockerfile.base at a ref CI
+              # resolves to a SHA; fold it in so base_tag changes when the
+              # toolkit moves (otherwise a toolkit-only fix never lands).
+              echo "${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}"
             } | sha256sum | cut -c1-12
           )
           BASE_TAG="base-${HASH}"
@@ -121,6 +126,7 @@ jobs:
       image: catthehacker/ubuntu:act-latest
     outputs:
       omos_version: ${{ steps.resolve.outputs.omos_version }}
+      mempalace_toolkit_ref: ${{ steps.resolve.outputs.mempalace_toolkit_ref }}
     steps:
       - name: Resolve omos version from npm registry
         id: resolve
@@ -134,10 +140,24 @@ jobs:
           OMOS_VERSION=$(curl -sf "https://registry.npmjs.org/oh-my-opencode-slim/latest" | jq -r '.version')
           echo "omos_version=${OMOS_VERSION}" >> "$GITHUB_OUTPUT"
           echo "Resolved OMOS_VERSION=${OMOS_VERSION}"
+          # Resolve mempalace-toolkit main HEAD to a commit SHA. Unlike omos
+          # (an npm pkg baked into the VARIANT), mempalace-toolkit is cloned
+          # in Dockerfile.base, so this SHA is ALSO folded into the
+          # base-decide hash to force a base rebuild when the toolkit moves
+          # (without it, a toolkit-only fix silently fails to land unless
+          # Dockerfile.base itself changes). gitea allows unauthenticated
+          # public-repo commit listing; the token header is harmless if the
+          # env vars are unset (degrades to anon, still HTTP 200).
+          MEMPALACE_TOOLKIT_REF=$(curl -sf -H "Authorization: token ${GITEA_BUILD_TOKEN:-${GITHUB_TOKEN:-}}" \
+            "https://gitea.jordbo.se/api/v1/repos/joakimp/mempalace-toolkit/commits?limit=1&sha=main" \
+            | jq -r '.[0].sha // "main"' 2>/dev/null || echo "main")
+          [ -n "$MEMPALACE_TOOLKIT_REF" ] || MEMPALACE_TOOLKIT_REF=main
+          echo "mempalace_toolkit_ref=${MEMPALACE_TOOLKIT_REF}" >> "$GITHUB_OUTPUT"
+          echo "Resolved MEMPALACE_TOOLKIT_REF=${MEMPALACE_TOOLKIT_REF}"
 
   # ── Phase 2: build & push base (multi-arch), only when needed ──────
   build-base:
-    needs: [base-decide]
+    needs: [base-decide, resolve-versions]
     if: needs.base-decide.outputs.need_build == 'true'
     runs-on: ubuntu-latest
     container:
@@ -185,6 +205,7 @@ jobs:
         shell: bash
         env:
           BASE_TAG_FULL: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+          MEMPALACE_TOOLKIT_REF: ${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}
         run: |
           set -euo pipefail
           # 3-attempt retry around `docker buildx build --push` for transient
@@ -205,6 +226,7 @@ jobs:
             if docker buildx build \
                 --platform linux/amd64,linux/arm64 \
                 --file Dockerfile.base \
+                --build-arg MEMPALACE_TOOLKIT_REF="${MEMPALACE_TOOLKIT_REF}" \
                 --push \
                 --tag "${BASE_TAG_FULL}" \
                 .; then

AGENTS.md

@@ -18,7 +18,7 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 - `Dockerfile.base` — variant-independent layers (apt, locales, AWS CLI, Node.js, mempalace, gitea-mcp, user setup, chromadb prewarm, ENVs, entrypoints). Published as `joakimp/opencode-devbox:base-<sha12>`. Rebuilt only when its content hash changes.
 - `Dockerfile.variant` — `FROM`s the base and adds only opencode/omos installs gated by build args: `INSTALL_OPENCODE` (default true), `INSTALL_OMOS`, and `INSTALL_MEMPALACE`. All GitHub-sourced binaries are pinned with version ARGs. Two variants: `base` (`INSTALL_OPENCODE=true`) and `omos` (`+INSTALL_OMOS=true`).
 - `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.jsonc generation (delegated to `generate-config.py`), LAN-access setup (delegated to `setup-lan-access.sh`), a one-time npm-global prefix migration shim (legacy `~/.pi/npm-global` → `~/.config/opencode/npm-global`), skillset auto-deploy from mounted skillset repo, OMOS setup.
+- `entrypoint-user.sh` — runs as developer: git config, opencode.jsonc generation (delegated to `generate-config.py`), LAN-access setup (delegated to `setup-lan-access.sh`), a one-time npm-global prefix migration shim (legacy `~/.pi/npm-global` → `~/.config/opencode/npm-global`), skillset auto-deploy from mounted skillset repo, OMOS bundled-skills reconcile (symlinks the image's bundled skills into `~/.agents/skills/`), OMOS config setup.
 - `rootfs/usr/local/lib/opencode-devbox/setup-lan-access.sh` — host-OS-agnostic LAN reachability helper. Detects VM-backed hosts (macOS OrbStack / Docker Desktop, via `host.docker.internal` resolution) and generates a writable `~/.ssh-local/config` using the host as an SSH jump; no-op on native Linux. Controlled by `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` / `DEVBOX_HOST_ALIAS` / `DEVBOX_LAN_AUTOJUMP_PRIVATE`. Ships the mechanism only (generic `host` jump alias); user targets stay host-side — named-peer `ProxyJump host` overrides go in a bind-mounted `~/.config/devbox-shell/ssh-lan.conf` (Included before `~/.ssh/config`), never baked into the image. **Scoping invariant:** every `Include` in the generated config MUST be preceded by a bare `Host *` reset — an `Include` is scoped to the enclosing `Host`/`Match` block, so without the reset the included config only applies when targeting `host`/`mac` and named peers fall back to SSH defaults. The top `Host *` block also overrides `UserKnownHostsFile` and `ControlPath` into the writable `~/.ssh-local` sidecar (first-value-wins), because the bind-mounted `~/.ssh` is read-only — otherwise multiplexed hosts (`ControlPath ~/.ssh/cm/...`) fail to create their master socket. Non-fatal. Counted in the base hash, so editing it advances `base-latest`.
 - `rootfs/usr/local/lib/opencode-devbox/generate-config.py` — generates `~/.config/opencode/opencode.jsonc` from env vars. Never overwrites an existing config (checks both `.json` and `.jsonc`). Auto-registers MCP servers for detected tools (mempalace via `mempalace-mcp`, gitea-mcp, context7 remote endpoint).
 - `scripts/smoke-test.sh` — post-build image verification. Asserts binary presence, opencode startup, entrypoint correctness, config generation idempotency, and image size thresholds. Used by both CI workflows.
@@ -31,21 +31,36 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 
 ## Versioning scheme
 
-Tags follow `v{opencode_version}[letter]` — e.g. `v1.14.20` for the first build on a new opencode release, and `v1.14.20b`, `v1.14.20c`, … for subsequent rebuilds on the same opencode version.
+Image tags follow **independent semver** — they version *this image*, not the
+bundled opencode release. **`v2.0.0` is the decoupling point** (the pi-removal
+breaking release); from there the opencode npm version is tracked in
+`CHANGELOG.md` and the `OPENCODE_VERSION` ARG but no longer drives the tag. This
+mirrors the sibling [`joakimp/pi-devbox`](https://gitea.jordbo.se/joakimp/pi-devbox)
+repo, which decoupled from the pi tool version at its own `v1.0.0`.
 
-- The number tracks the opencode npm version (see `OPENCODE_VERSION` ARG in `Dockerfile.variant`).
-- **No letter suffix** on the first build of a new opencode version — the bare `v{opencode_version}` tag is the canonical release.
-- **Letter suffix is the build ordinal**, starting at `b` for the second build. The letter `a` is **never used** — think of the suffix as counting rebuilds: `b = 2nd, c = 3rd, d = 4th, …`. For opencode version `1.14.20`: first build `v1.14.20`, second `v1.14.20b`, third `v1.14.20c`, and so on.
-- A letter suffix is only used for container-level rebuilds — tooling changes, CVE fixes, doc-driven rebuilds, entrypoint bugfixes — that don't change the underlying opencode version.
-- **Pre-flight check before cutting any non-letter-suffixed tag** — verify the bump is real:
+- **MAJOR** — breaking changes to how users run/configure the container (volume
+  layout, removed variants/build-args, an entrypoint contract change that
+  requires user action). `v2.0.0` (pi removal + npm-prefix relocation) is the
+  reference example.
+- **MINOR** — backward-compatible features: new variants/tags, new opt-in
+  behavior, new env vars, or changed-but-compatible semantics. Example: `v2.1.0`
+  added the OMOS bundled-skills image-symlink mechanism.
+- **PATCH** — opencode/tool version bumps and small fixes that don't change the
+  contract. When a release pairs a tool bump with a feature, the feature wins
+  and it's a minor.
+- **Pre-flight check** — whenever an opencode bump is part of the release,
+  verify it is real before claiming it in the CHANGELOG:
   ```bash
-  npm view opencode-ai version           # must equal the X.Y.Z in your tag
+  npm view opencode-ai version           # must equal the X.Y.Z you pin in Dockerfile.variant
   ```
-  If the npm version equals the *previous* release's `X.Y.Z`, you're cutting a letter-suffix rebuild (`vX.Y.Zc`, `vX.Y.Zd`, …), not a new minor. **A bare `vX.Y.Z` tag is a claim that opencode upstream just released `X.Y.Z`** — if that claim is wrong, future opencode releases will collide with your tag namespace and the version-tracking story breaks.
-  
-  Cautionary example: 2026-05-28 morning, `v1.15.12` was cut while opencode-ai was still at `1.15.11`. The commit message itself acknowledged "OPENCODE_VERSION stays at 1.15.11" but tagged `v1.15.12` anyway. Re-cut as `v1.15.11c` the same afternoon (see CHANGELOG). The `v1.15.12` git tag and Hub images stayed as historical artifacts; the slip cost a CI cycle and a CHANGELOG-rewrite. **Run the npm view check at the top of every release-day cut.**
+  Historical note: under the *old* `v{opencode_version}[letter]` scheme a
+  mismatched tag was a namespace hazard — e.g. `v1.15.12` was cut while
+  opencode was still `1.15.11`, then re-cut as `v1.15.11c` (2026-05-28), costing
+  a CI cycle. Semver tags no longer encode the opencode version, so that
+  specific collision class is gone — but a CHANGELOG that names the wrong
+  upstream version is still wrong.
 
-CI produces four Docker Hub tags **under `opencode-devbox`** per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos` — one tag pair (versioned + floating alias) per variant (two variants: `base`, `omos`).
+CI produces four Docker Hub tags **under `opencode-devbox`** per release: `vX.Y.Z`, `latest`, `vX.Y.Z-omos`, `latest-omos` — one tag pair (versioned + floating alias) per variant (two variants: `base`, `omos`).
 
 When bumping the opencode version, bump `OPENCODE_VERSION` in `Dockerfile.variant` and update the comment in `.env.example` if it names a specific model/version for context.
 
@@ -86,12 +101,15 @@ curl -s https://api.github.com/repos/anomalyco/opencode/releases/tags/v1.15.10 |
 - **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, gitleaks, 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) — mind project-specific arch-name deviations (gitleaks uses `x64`, bat/eza/zoxide use `x86_64`/`aarch64`, gosu uses `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`.
 - **`OMOS_VERSION` MUST be passed by CI as a concrete version**, not left at the `latest` default. The npm install step in `Dockerfile.variant` (`oh-my-opencode-slim@${OMOS_VERSION}`) produces an identical layer-hash when the ARG value is byte-identical across builds; combined with the registry buildcache (`base-buildcache`) the layer gets reused even when `latest` would have resolved to a newer upstream. This is the same class of bug that bit pi-devbox v0.74.0 → v0.75.5 (silent same-bytes-across-releases regression discovered 2026-05-23, fixed in pi-devbox v0.75.5b). It is currently *masked* in opencode-devbox by `OPENCODE_VERSION` being a hard-coded ARG that bumps every release — that bump invalidates the parent-chain cache key for the downstream omos layer — but the masking would fail the moment a `vN.N.Nb` opencode-version-unchanged release ships that only bumps omos. Preventative fix: `.gitea/workflows/docker-publish-split.yml` has a `resolve-versions` job that runs `npm view oh-my-opencode-slim version`, exposing the concrete value as an output that the omos smoke + build jobs consume via build-args. Smoke tests assert via the `EXPECTED_OMOS_VERSION` env var — would catch the regression on the next release rather than several releases later. **If you change the variant build-args list, the resolve-versions job, or the smoke EXPECTED_*_VERSION wiring, audit all affected jobs in lockstep.**
+- **`resolve-versions` also pins `mempalace-toolkit` to a SHA** — `resolve-versions` resolves the `mempalace-toolkit` `main` HEAD to a commit SHA (`mempalace_toolkit_ref` output) via the gitea commits API (`/api/v1/repos/joakimp/mempalace-toolkit/commits?limit=1&sha=main`; gitea allows **unauthenticated** public-repo listing, so no secret is required). Unlike every other dependency, `mempalace-toolkit` is cloned in **`Dockerfile.base`**, not the variant — so the resolve→build-arg→variant plumbing bypasses it. To make a moved toolkit actually land, the resolved SHA is **folded into the `base-decide` hash** (so `base_tag` changes → base rebuilds) AND passed to `build-base` as `--build-arg MEMPALACE_TOOLKIT_REF`. Consequently **`base-decide` now depends on `resolve-versions`** (they no longer run in parallel), and the base clone uses a SHA-capable `git fetch <ref> + checkout FETCH_HEAD` (a `git clone --branch <40-char-SHA>` would fail). Trade-off: `base_tag` now reflects a live gitea lookup — on an API blip it falls back to `main`, triggering one *extra* base rebuild, never a *missed* one. If you touch `resolve-versions`, `base-decide`'s hash inputs, or the `build-base` build-args, audit `.gitea/README.md` Step 1 in lockstep.
 - **Registry buildkit cache-export is currently disabled** — do NOT re-add `cache-from`/`cache-to` to the `build-base` step in `.gitea/workflows/docker-publish-split.yml` without first verifying that buildkit's `mode=max` cache-export to `registry-1.docker.io` no longer returns HTTP 400 from the Hub CDN edge. The regression surfaced ~2026-05-23 and broke five consecutive opencode-devbox publish attempts (runs #332/333/334/336 + a rerun); root-caused on 2026-05-28 by a manual host-side publish that reproduced the same 400 only on `--cache-to` while image push worked fine. Failure shape is stable (`Offset:0` in the `_state` token, HTML response body = CDN-tier rejection, not registry backend), repo-specific (we're the only repo writing `:base-buildcache` mode=max), and explains why pinning `setup-buildx-action@v4.0.0` didn't help (action pin doesn't change the bundled buildkit version on the catthehacker runner image). Trade-off: dockerfile.base changes pay a full ~3 min rebuild instead of pulling cached layers; unchanged bases short-circuit at the Hub-probe step in `base-decide` and never re-build anyway. Variants don't use registry cache so they're unaffected. Re-enable condition: upstream moby/buildkit fix lands AND a low-risk test run succeeds without 400s. See CHANGELOG v1.15.12 `Unreleased` block for the full diagnostic chain. Manual escape-hatch publish procedure: `docs/manual-host-publish.md`.
 - **Push steps wrap `docker buildx build --push` in a 3-attempt retry loop** (15s, 30s backoff) for transient `registry-1.docker.io` blips — rate limits, brief 5xx, CDN flap. Implemented as inline `shell: bash` steps with `docker buildx build` raw rather than `docker/build-push-action@v7` so the loop is visible and tweakable. Affects the 1 base + 5 variant push steps in `.gitea/workflows/docker-publish-split.yml`; smoke-test builds (`load: true`, no push) are untouched. **This does NOT mask deterministic failures** — a true regression (like the cache-export 400 of 2026-05-23..28) fails all 3 attempts identically and the job still fails. Orthogonal to the cache-export disablement above: cache-export was about a deterministic protocol mismatch, retry is about absorbing genuine transients. Both are belt-and-braces with the `ci-release-watcher` skill's transient-rerun heuristic. If you change the matrix of push steps, keep the retry wrapper consistent across them — the pattern is duplicated rather than factored out because Gitea Actions doesn't support reusable composite shell steps cleanly.
 - **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.
+- **MemPalace `diary_write` anyOf workaround — upstream watch target** — `Dockerfile.base` carries a perl RUN block that strips a root-level `anyOf` from `mempalace_diary_write`'s advertised `inputSchema`. Mempalace 3.3.x/3.4.0 advertise `anyOf: [{required:[entry]},{required:[content]}]`, which Anthropic's tools API (and Codex) reject at session start (`input_schema does not support oneOf, allOf, or anyOf at the top level`), making the whole MCP server fail to load. The workaround is idempotent and self-deactivating: when upstream ships the real fix the regex stops matching and the build prints `WARN: ... upstream may have changed shape` — **that WARN is the signal to delete the RUN block.** Upstream status (last checked **2026-06-14**): issue **#1728 is still OPEN**; PR **#1735 is CLOSED UNMERGED (2026-06-11) — do NOT watch it, it is dead**; PR **#1717 is the current live fix candidate**; mempalace PyPI latest is **3.4.0 (== our pin)**, so **no release contains the fix yet** and the workaround must stay. **Removal trigger:** a mempalace release **> 3.4.0** that actually strips the root-level `anyOf` lands on PyPI — then bump `MEMPALACE_VERSION` (in lockstep with pi-devbox) and drop the RUN block. NOTE: `MEMPALACE_VERSION` (the pip pin) and `MEMPALACE_TOOLKIT_REF` (the git ref for the `mempalace-toolkit` clone) are unrelated despite the shared prefix; do not conflate them.
 - **MemPalace install path** — installed via `uv tool install` into `/opt/uv-tools/mempalace/`. Both the `mempalace` CLI and the `mempalace-mcp` MCP server binary are shipped as entry points by the mempalace package itself and placed on PATH by uv as shims whose shebangs point at the venv's Python. No hand-rolled wrapper is needed. Do not use `pip install --break-system-packages` — that was the previous approach and has been removed. Do not use `["python3", "-m", "mempalace.mcp_server"]` in `opencode.jsonc` — system Python can't import from the uv venv.
 - **generate-config.py idempotency** — the script MUST never overwrite an existing `opencode.jsonc` or legacy `opencode.json`. Config persists in the `devbox-opencode-config` named volume; accidentally clobbering that file would destroy hand-edits. The smoke test asserts this.
 - **Skillset auto-deploy** — on every container start, `entrypoint-user.sh` looks for a skillset repo (detection order: `$SKILLSET_CONTAINER_PATH` → `$HOME/skillset` → `/workspace/skillset`) and runs `deploy-skills.sh --bootstrap --prune-stale`. This creates relative symlinks in `~/.agents/skills/` and `~/.config/opencode/instructions/`. Do NOT bind-mount `~/.agents/skills/` from the host — the container manages its own skills with relative symlinks that differ from the host's. The named volume `devbox-opencode-config` persists the deployed config across restarts.
+- **OMOS bundled-skills reconcile** — on the omos variant, `entrypoint-user.sh` symlinks the five skills bundled with `oh-my-opencode-slim` (`clonedeps`, `codemap`, `deepwork`, `oh-my-opencode-slim`, `simplify`) from the image path `/usr/lib/node_modules/oh-my-opencode-slim/src/skills/<name>` into `~/.agents/skills/`, on **every** start, *after* the skillset deploy (so OMOS wins name collisions via `ln -sfn` — the only overlap is `simplify`, which was removed from the skillset repo). These are **absolute** symlinks (target is image-internal at a fixed `/usr` path) — do NOT "fix" them to relative like skillset's. Because the target lives in the image, pulling a newer image updates the skills with no installer run and no config reset. The block is non-fatal (`{ … } || true`), gated by `OMOS_SKILLS` (default true, **independent of `ENABLE_OMOS`**) and the presence of the source dir (no-op on the base variant). The two `oh-my-opencode-slim install` calls now pass `--skills=no` unconditionally — the installer manages only `oh-my-opencode-slim.json`, never skills; do not reintroduce installer-managed skills. A one-time migration (marker: `~/.config/opencode/.omos-skills-migrated`) backs up — never deletes — any frozen real copies the old installer left in `~/.config/opencode/skills/` to `<name>.bak.<epoch>`, because those would otherwise shadow the fresh image-sourced symlinks. The build-time smoke test asserts the bundled-skills source path exists (catches an upstream package restructure loudly). Full rationale: `docs/omos-skills.md`.
 - **Config persistence via named volume** — `devbox-opencode-config` is a Docker named volume mounted at `~/.config/opencode/`. It is NOT a host bind mount by default. This separation allows both native and containerized opencode to coexist on the same machine without symlink conflicts. Users who need to override can replace the named volume with a host bind mount in their compose file. Because `NPM_CONFIG_PREFIX` is set to `~/.config/opencode/npm-global` (relocated from the legacy `~/.pi/npm-global` in v2.0.0), anything installed via `npm install -g` as the developer user also lands on this volume and survives container recreate AND image rebuild.
 - **npm-global prefix relocation (v2.0.0 breaking change)** — the user-writable global npm prefix moved from `~/.pi/npm-global` to `~/.config/opencode/npm-global`. The old path lived on the `devbox-pi-config` volume (only mounted in `docker-compose.yml`); the new path is on `devbox-opencode-config`, which is a persistent named volume in BOTH `docker-compose.yml` and `docker-compose.shared.yml`. `entrypoint-user.sh` carries a one-time migration shim: if `~/.pi/npm-global` exists and the marker `~/.config/opencode/npm-global/.migrated-from-dot-pi` is absent, it `cp -an` the old `lib/`/`bin/`/`share/` into the new prefix (never overwriting fresh installs) and writes the marker. Baked binaries stay on `/usr` (the variant Dockerfile runs each `npm install -g` with `NPM_CONFIG_PREFIX=/usr`) so the volume mount doesn't shadow them. The `ENV NPM_CONFIG_PREFIX`/`PATH` lines in `Dockerfile.base` are declared *after* all build-time installs.
 - **Default CMD is `bash -l`** — not a harness. `docker compose run --rm devbox` drops the user into a login shell to choose: `aws sso login`, then `opencode` (or any tool). Pass the harness explicitly to launch directly: `docker compose run --rm devbox opencode`. `docker compose exec` bypasses entrypoint+CMD entirely (existing user workflow unchanged).

CHANGELOG.md

@@ -6,7 +6,99 @@ Tags follow `v{opencode_version}[letter]` — bare tag for the first build on a
 
 ---
 
-## Unreleased
+## v2.1.1 — 2026-06-14
+
+Image-semver **patch**: bumps opencode and lands the `mempalace-toolkit`
+SHA-resolution CI fix plus two doc corrections that accumulated on `main` since
+`v2.1.0`. The toolkit change folds a live SHA into the base-tag hash, so this
+release carries a full base rebuild and a `base-latest` re-promote.
+
+### Bumped: opencode-ai 1.17.5 → 1.17.6
+
+`OPENCODE_VERSION` ARG in `Dockerfile.variant`. Upstream `1.17.6` (published
+2026-06-13) is a single Core bugfix — *"Improved MCP server compatibility by
+declaring OpenCode's supported client capabilities"* — with no breaking,
+runtime-dependency, bundled-Bun, or CPU/AVX changes. Pure version bump on the
+devbox side. Full notes:
+<https://github.com/anomalyco/opencode/releases/tag/v1.17.6>.
+
+### Changed
+
+- **`mempalace-toolkit` is now CI-resolved to a commit SHA.** It is the only
+  dependency cloned in `Dockerfile.base` (everything else is in the variant),
+  so it bypassed the `resolve-versions` → build-arg plumbing and its ref stayed
+  a literal `main` — meaning a toolkit-only fix would silently fail to land
+  unless `Dockerfile.base` itself changed. Now `resolve-versions` resolves the
+  `mempalace-toolkit` `main` HEAD to a SHA (new `mempalace_toolkit_ref` output,
+  via the gitea commits API — unauthenticated, no secret needed), `base-decide`
+  folds that SHA into the base-tag hash (so a moved toolkit forces a base
+  rebuild) and now **depends on `resolve-versions`**, and `build-base` passes it
+  as `--build-arg MEMPALACE_TOOLKIT_REF`. The base clone switched from
+  `git clone --branch` to a SHA-capable `git fetch <ref> + checkout FETCH_HEAD`.
+  Trade-off: `base_tag` now reflects a live gitea lookup — an API blip falls
+  back to `main` and triggers one *extra* rebuild, never a *missed* one. Updated
+  `.gitea/README.md` Step 1 and `AGENTS.md` Critical conventions in lockstep.
+
+### Docs (no image change)
+
+- Correct the MemPalace `diary_write` anyOf workaround watch-target: upstream
+  PR #1735 was **closed unmerged** (2026-06-11), so the old “remove once #1735
+  ships” TODO pointed at a dead PR. Issue #1728 is still open; PR #1717 is the
+  current live candidate; mempalace PyPI latest is still 3.4.0 (== our pin), so
+  the workaround stays. Rewrote the `Dockerfile.base` tracking comment and added
+  a durable note under `AGENTS.md` Critical conventions.
+
+- Fix the quick-start description in `README.md` and the Hub `HUB_TEMPLATE`
+  (`scripts/generate-dockerhub-md.py`, regenerated `DOCKER_HUB.md`): bare
+  `docker compose run --rm devbox` lands in a **login shell** (default `CMD` is
+  `bash -l`), not opencode. The old copy claimed the opposite and had a garbled
+  "Use `bash` instead of (no command)" half-sentence. Pass `opencode` explicitly
+  to start the harness directly. Doc-only — does not trigger a new image build.
+
+## v2.1.0 — 2026-06-13
+
+Image-semver **minor**: adds the OMOS bundled-skills image-symlink mechanism and
+bumps opencode. `v2.0.0` decoupled image versioning from the opencode version
+(see [AGENTS.md](AGENTS.md#versioning-scheme)); this is the first feature release
+on the semver line, mirroring how the sibling `pi-devbox` repo moved to semver
+after its own `v1.0.0` decouple.
+
+### Bumped: opencode-ai 1.17.4 → 1.17.5
+
+`OPENCODE_VERSION` ARG in `Dockerfile.variant`.
+
+### Changed: OMOS bundled skills are now symlinked from the image, not copied
+
+The five skills bundled with `oh-my-opencode-slim` (`clonedeps`, `codemap`,
+`deepwork`, `oh-my-opencode-slim`, `simplify`) are now **symlinked from the
+image** into `~/.agents/skills/` on every container start, instead of being
+**copied** into `~/.config/opencode/skills/` once on first run by the OMOS
+installer.
+
+Why: the old copy landed in the persistent `devbox-opencode-config` volume and
+was gated by config-existence, so it **froze** at whatever the image shipped on
+first run — pulling a newer image never refreshed the skills, and the only
+update path (`OMOS_RESET=true`) also clobbered the user's hand-tuned
+`opencode.jsonc`. With the symlink approach the link target lives in the image,
+so **`docker compose pull` + recreate updates the skills for free** — no
+installer run, no config reset.
+
+- `entrypoint-user.sh`: new OMOS bundled-skills reconcile block (runs after the
+  skillset deploy so OMOS wins the `simplify` name collision; absolute symlinks;
+  non-fatal; gated by `OMOS_SKILLS`, now independent of `ENABLE_OMOS` and the
+  presence of the bundled-skills source on the omos variant).
+- `entrypoint-user.sh`: both `oh-my-opencode-slim install` calls now pass
+  `--skills=no` — the installer manages only `oh-my-opencode-slim.json`.
+- One-time migration backs up (never deletes) any frozen real copies in
+  `~/.config/opencode/skills/` to `<name>.bak.<epoch>` (marker:
+  `~/.config/opencode/.omos-skills-migrated`).
+- `scripts/smoke-test.sh`: asserts the bundled-skills source path exists on the
+  omos variant (catches an upstream package restructure).
+- Docs: new `docs/omos-skills.md`; updated `README.md`, `AGENTS.md`,
+  `.env.example` (`OMOS_SKILLS` semantics).
+
+**Editing `entrypoint-user.sh` advances the base hash** — this release carries a
+full base rebuild and a `base-latest` re-promote.
 
 ## v2.0.0 — 2026-06-13
 

DOCKER_HUB.md

@@ -34,7 +34,7 @@ curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.
 docker compose run --rm devbox
 ```
 
-This drops you straight into opencode with your project mounted at `/workspace`. Use `bash` as the command (e.g. `docker compose run --rm devbox bash`) to land in a shell first — useful for `aws sso login` or multi-agent workflows.
+This mounts your project at `/workspace`. With no command (as above) the image's default `CMD` (`bash -l`) drops you into a login shell — run `opencode` to start the harness, or `aws sso login` first, etc. To start opencode directly, pass it as the command: `docker compose run --rm devbox opencode`.
 
 **One-shot run, no persistence:**
 

Dockerfile.base

@@ -285,12 +285,19 @@ RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
 # kwarg alias so existing callers still work.
 #
 # Idempotent and self-deactivating: once upstream releases the fix the
-# regex no longer matches and this RUN is a silent no-op.
-# Upstream tracking:
+# regex no longer matches (and the WARN below fires) — that's the signal
+# to delete this RUN.
+# Upstream status (last checked 2026-06-14):
+#   issue #1728 — STILL OPEN (root-level anyOf rejected by Anthropic/Codex)
+#   PR #1735    — CLOSED UNMERGED 2026-06-11; do NOT watch it (dead)
+#   PR #1717    — open; the current live fix candidate to watch
+#   mempalace PyPI latest = 3.4.0 (== our pin) → no release contains the fix yet
 #   https://github.com/MemPalace/mempalace/issues/1728
-#   https://github.com/MemPalace/mempalace/pull/1735
-# TODO: remove this RUN once a mempalace release containing PR #1735 is on
-# PyPI and installed by the line above.
+#   https://github.com/MemPalace/mempalace/pull/1717
+# TODO: remove this RUN once a mempalace release > 3.4.0 that actually strips
+# the root-level anyOf ships on PyPI and is installed by the line above.
+# Keep MEMPALACE_VERSION in lockstep with pi-devbox when bumping.
+# See AGENTS.md “Critical conventions” for the full watch-target rationale.
 RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
       MP_FILE="$(find /opt/uv-tools/mempalace -path '*/mempalace/mcp_server.py' | head -n1)" && \
       if [ -z "$MP_FILE" ]; then echo "mempalace mcp_server.py not found" >&2; exit 1; fi && \
@@ -305,9 +312,22 @@ RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
 # ── mempalace-toolkit — bash wrappers for session/docs mining ────────
 ARG INSTALL_MEMPALACE_TOOLKIT=true
 ARG MEMPALACE_TOOLKIT_REF=main
+# MEMPALACE_TOOLKIT_REF accepts EITHER a branch name OR a commit SHA. CI
+# resolves it to a SHA (resolve-versions job) and folds that SHA into the
+# base-decide hash so the base rebuilds when the toolkit moves. `git clone
+# --branch <40-char-SHA>` fails ("Remote branch not found"), so use
+# `git fetch <ref> + checkout FETCH_HEAD`, which works for name and SHA.
 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 && \
+      rm -rf /opt/mempalace-toolkit && mkdir -p /opt/mempalace-toolkit && \
+      git -C /opt/mempalace-toolkit init -q && \
+      git -C /opt/mempalace-toolkit remote add origin https://gitea.jordbo.se/joakimp/mempalace-toolkit.git && \
+      ok=0; for i in 1 2 3 4 5; do \
+        if git -C /opt/mempalace-toolkit fetch --depth 1 origin "${MEMPALACE_TOOLKIT_REF}" && \
+           git -C /opt/mempalace-toolkit checkout -q FETCH_HEAD; then ok=1; break; fi; \
+        echo "git fetch mempalace-toolkit@${MEMPALACE_TOOLKIT_REF} failed (attempt $i/5), retrying in $((i*5))s..."; \
+        sleep $((i*5)); \
+      done; \
+      [ "$ok" = "1" ] && \
       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 && \

Dockerfile.variant

@@ -39,7 +39,7 @@ ARG USER_NAME=developer
 # edit, so the cache-hit class of bug that bit pi-devbox v0.74.0..
 # v0.75.5 cannot apply here.
 ARG INSTALL_OPENCODE=true
-ARG OPENCODE_VERSION=1.17.4
+ARG OPENCODE_VERSION=1.17.6
 RUN if [ "${INSTALL_OPENCODE}" = "true" ]; then \
       NPM_CONFIG_PREFIX=/usr npm install -g opencode-ai@${OPENCODE_VERSION} && \
       opencode --version ; \

README.md

@@ -27,7 +27,7 @@ $EDITOR .env
 docker compose run --rm devbox
 ```
 
-This pulls `joakimp/opencode-devbox:latest` from Docker Hub, mounts `WORKSPACE_PATH` at `/workspace`, and drops you straight into opencode. Use `bash` instead of (no command) to land in a shell first — useful for `aws sso login`, `omos`, etc.
+This pulls `joakimp/opencode-devbox:latest` from Docker Hub and mounts `WORKSPACE_PATH` at `/workspace`. With no command (as above) the image's default `CMD` (`bash -l`) drops you into a **login shell** — from there run `opencode` to start the harness, or do `aws sso login` first, launch `omos`, etc. To start opencode directly and skip the shell, pass it as the command: `docker compose run --rm devbox opencode`.
 
 **Want to hack on the image itself, follow upstream changes, or rebuild from source?** Clone the repo:
 
@@ -146,8 +146,8 @@ docker compose exec -u developer devbox aws --version
 | `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` |
+| `OMOS_SKILLS` | Symlink bundled OMOS skills from the image into `~/.agents/skills/` each start | `true` |
+| `OMOS_RESET` | Force regenerate OMOS config on next start (does not affect skills) | `false` |
 | `SKILLSET_CONTAINER_PATH` | Path to skillset repo inside container (for auto-deploy when not at /workspace/skillset) | Auto-detect |
 
 ### Reaching your LAN from the container
@@ -207,7 +207,7 @@ Host my-remote
 
 ### Custom opencode config
 
-Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. All changes to `opencode.jsonc`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation.
+Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. Changes to `opencode.jsonc` and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation. Auto-deployed skills are *not* stored here — skillset and OMOS skills are symlinked into `~/.agents/skills/` and rebuilt on every start (see [Custom skills](#custom-skills) and [docs/omos-skills.md](docs/omos-skills.md)).
 
 When an existing `opencode.jsonc` is found in the volume, the `OPENCODE_PROVIDER` auto-config is skipped.
 
@@ -232,6 +232,8 @@ When a skillset repo is detected, its skills are symlinked into `~/.agents/skill
 
 > **Warning:** Do not bind-mount a host `~/.agents/skills` directory directly into the container. This conflicts with the symlink-based auto-deploy mechanism and causes broken skill references.
 
+On the OMOS variant, the five skills bundled with oh-my-opencode-slim are also symlinked into `~/.agents/skills/` on each start — **from the image**, so pulling a newer image updates them with no installer run and no config reset. See [docs/omos-skills.md](docs/omos-skills.md).
+
 ### 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:
@@ -457,7 +459,7 @@ ENABLE_OMOS=true
 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.
+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. The installer no longer manages skills (`--skills=no`); the bundled skills are symlinked from the image on every start — see [docs/omos-skills.md](docs/omos-skills.md).
 
 ### OMOS Environment Variables
 
@@ -465,8 +467,8 @@ On first start, the entrypoint runs the oh-my-opencode-slim installer in non-int
 |---|---|---|
 | `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
 | `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) |
+| `OMOS_SKILLS` | `true` | Symlink the bundled OMOS skills (`clonedeps`, `codemap`, `deepwork`, `oh-my-opencode-slim`, `simplify`) from the image into `~/.agents/skills/` on each start. Independent of `ENABLE_OMOS`. See [docs/omos-skills.md](docs/omos-skills.md) |
+| `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config). Does **not** affect skills |
 
 ### Custom Configuration
 

docs/omos-skills.md

@@ -0,0 +1,110 @@
+# OMOS bundled skills
+
+How the five skills bundled with [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)
+(OMOS) are deployed in this image, why the mechanism changed, and how to keep
+them up to date.
+
+## TL;DR
+
+- OMOS bundles five skills: `clonedeps`, `codemap`, `deepwork`,
+  `oh-my-opencode-slim`, `simplify`.
+- They are **symlinked from the image** into `~/.agents/skills/` on every
+  container start by `entrypoint-user.sh` (gated by `OMOS_SKILLS`, default
+  `true`).
+- **To update them, pull a newer image and recreate the container** — no
+  installer run, no config reset:
+  ```bash
+  docker compose pull
+  docker compose up -d --force-recreate
+  ```
+
+## Why it works this way
+
+The skills ship inside the OMOS npm package, baked into the image at
+`/usr/lib/node_modules/oh-my-opencode-slim/src/skills/<name>/`. On start the
+entrypoint creates one absolute symlink per skill into `~/.agents/skills/` —
+the same flat directory the [skillset](#relationship-to-skillset) deploy uses
+and which opencode scans (directly and via the `~/.claude/skills` pointer).
+
+Because the symlink target lives in the **image**, not in a volume, the skill
+content tracks whatever image you run. Pull a newer `*-omos` image and the
+skills update on the next container start. `~/.agents/skills/` is itself an
+ephemeral container-layer directory rebuilt from scratch on every start, so the
+reconcile is idempotent and self-healing.
+
+The symlinks are **absolute** (unlike skillset's relative links): the target is
+always inside the container at a fixed `/usr` path, so there is no host/container
+path divergence to guard against.
+
+## The old mechanism (and the trap it created)
+
+Previously the OMOS *installer* (`oh-my-opencode-slim install --skills=yes`)
+**copied** the skills into `~/.config/opencode/skills/` — but only on the very
+first container start, gated by the absence of `oh-my-opencode-slim.json`. That
+directory is the persistent `devbox-opencode-config` named volume.
+
+The consequence: once the config existed, the installer was skipped forever, so
+the copied skills **froze** at whatever the image shipped on first run. Pulling
+a newer image did nothing (the copies lived in the volume, not the image). The
+only refresh path was `OMOS_RESET=true`, which runs `install --reset` and
+**also overwrites your hand-tuned `opencode.jsonc`** (model choices, agent
+config). Updating skills meant clobbering unrelated config — a bad trade.
+
+The installer has no skills-only refresh flag (`--skills=yes|no` is all-or-
+nothing within a full install; `--reset` overwrites everything), so the fix was
+to stop using the installer for skills entirely. The two `install` invocations
+in `entrypoint-user.sh` now pass `--skills=no`; the installer manages only the
+agent config (`oh-my-opencode-slim.json`).
+
+## One-time migration of frozen copies
+
+Existing volumes still contain the old frozen real directories under
+`~/.config/opencode/skills/`. Because opencode prefers a name found there over
+the same name in `~/.agents/skills/`, those stale copies would *shadow* the
+fresh image-sourced symlinks. On the first start after upgrading, the entrypoint
+**backs each of them up — never deletes** — to
+`~/.config/opencode/skills/<name>.bak.<epoch>` and writes a marker at
+`~/.config/opencode/.omos-skills-migrated` so the migration runs exactly once.
+Only real directories are touched; any symlink in that directory is left alone.
+
+If everything looks right after a few sessions, the backups are safe to remove:
+
+```bash
+rm -rf ~/.config/opencode/skills/*.bak.*
+```
+
+## Relationship to skillset
+
+The [skillset](https://gitea.jordbo.se/joakimp/skillset) repo deploys its own
+version-controlled skills into `~/.agents/skills/` via
+`deploy-skills.sh --bootstrap --prune-stale`, which the entrypoint runs on every
+start — *before* the OMOS reconcile. If a skill name exists in both, **OMOS
+wins**: the reconcile uses `ln -sfn`, which replaces any existing symlink. Today
+the only overlap is `simplify` (the OMOS copy is richer — it bundles
+`codemap.md` and a `README.md`), so `simplify` was removed from the skillset
+repo and the image copy owns the name.
+
+## Configuration
+
+| Variable | Default | Effect |
+|---|---|---|
+| `OMOS_SKILLS` | `true` | Symlink the bundled skills into `~/.agents/skills/` on each start. Set `false` to deploy no skills from the image. |
+
+`OMOS_SKILLS` is **independent of `ENABLE_OMOS`**: the skills are useful to plain
+opencode even when the multi-agent orchestration config is not enabled. The
+reconcile is additionally gated on the bundled-skills source being present, so
+it is automatically a no-op on the non-OMOS (`base`) image variant.
+
+## Troubleshooting
+
+- **A skill didn't update after `docker compose pull`.** Make sure you
+  recreated the container (`docker compose up -d --force-recreate`); a plain
+  restart reuses the old container layer. Confirm the link target —
+  `readlink ~/.agents/skills/deepwork` should point under
+  `/usr/lib/node_modules/oh-my-opencode-slim/src/skills/`.
+- **A skill disappeared.** If OMOS upstream restructured its package the symlink
+  target may no longer exist. The build-time smoke test asserts the source path,
+  so this should be caught in CI; if you hit it at runtime, look for a dangling
+  link in `ls -l ~/.agents/skills/`.
+- **I want a frozen copy back.** It's at
+  `~/.config/opencode/skills/<name>.bak.<epoch>` until you delete it.

entrypoint-user.sh

@@ -118,6 +118,66 @@ if [ -n "$SKILLSET_DEPLOY" ]; then
   "$SKILLSET_DEPLOY" --bootstrap --prune-stale >/dev/null 2>&1 || true
 fi
 
+# ── OMOS bundled skills: symlink from the image into the flat skills dir ──
+# The oh-my-opencode-slim package bundles its skills at a fixed, image-internal
+# path (npm global prefix /usr — see Dockerfile.variant). Historically the omos
+# *installer* COPIED them into ~/.config/opencode/skills/ on first run only,
+# freezing them in the persistent `devbox-opencode-config` named volume: pulling
+# a newer image never refreshed them, and the only update path was
+# `OMOS_RESET=true` (which also clobbers the user's hand-tuned opencode config).
+#
+# Instead we symlink them from the IMAGE into ~/.agents/skills/ — the same flat
+# dir skillset uses, which opencode scans (directly and via the ~/.claude/skills
+# pointer). Because the link targets live in the image, `docker compose pull` +
+# recreate updates the skills for free: no installer run, no config reset.
+#
+# ~/.agents/skills/ is authoritative. The legacy ~/.config/opencode/skills/ real
+# dir is intentionally bypassed; a one-time migration backs up (never destroys)
+# the frozen copies it holds so they stop shadowing the fresh image-sourced
+# skills. The migration marker lives in the parent config dir, not inside
+# skills/, so it never interferes with that directory's contents.
+#
+# Absolute symlink (not relative like skillset): the target is always inside the
+# container at a fixed /usr path, and ~/.agents/skills/ is an ephemeral
+# container-layer dir rebuilt each start — there is no host/container path
+# divergence to guard against. The whole block is non-fatal (`{ … } || true`):
+# a transient ln/mv failure must never brick container startup, mirroring the
+# skillset deploy above. Runs AFTER skillset deploy so OMOS wins any name
+# collision (e.g. `simplify`) via `ln -sfn`. Gated by OMOS_SKILLS (default true)
+# and the presence of the bundled skills (omos-variant images only).
+if [ "${OMOS_SKILLS:-true}" = "true" ]; then
+  OMOS_SKILLS_SRC=""
+  for cand in \
+    /usr/lib/node_modules/oh-my-opencode-slim/src/skills \
+    /usr/local/lib/node_modules/oh-my-opencode-slim/src/skills; do
+    if [ -d "$cand" ]; then OMOS_SKILLS_SRC="$cand"; break; fi
+  done
+  if [ -n "$OMOS_SKILLS_SRC" ]; then
+    {
+      AGENTS_SKILLS_DIR="$HOME/.agents/skills"
+      OPENCODE_SKILLS_DIR="$HOME/.config/opencode/skills"
+      OMOS_SKILLS_MARKER="$HOME/.config/opencode/.omos-skills-migrated"
+      mkdir -p "$AGENTS_SKILLS_DIR"
+      for skill_path in "$OMOS_SKILLS_SRC"/*/; do
+        [ -d "$skill_path" ] || continue
+        name="$(basename "$skill_path")"
+        # OMOS wins collisions: -f replaces an existing symlink (e.g. skillset's).
+        ln -sfn "${skill_path%/}" "$AGENTS_SKILLS_DIR/$name"
+        # One-time unshadow: back up — never destroy — the frozen real copy the
+        # old installer left in the persistent config volume. `! -L` ensures we
+        # only ever touch a real dir, never a symlink a user/skillset created.
+        if [ ! -f "$OMOS_SKILLS_MARKER" ] \
+          && [ -d "$OPENCODE_SKILLS_DIR/$name" ] \
+          && [ ! -L "$OPENCODE_SKILLS_DIR/$name" ]; then
+          mv "${OPENCODE_SKILLS_DIR:?}/$name" \
+            "${OPENCODE_SKILLS_DIR}/${name}.bak.$(date +%s)"
+        fi
+      done
+      touch "$OMOS_SKILLS_MARKER" 2>/dev/null || true
+    } || true
+  fi
+fi
+
 CONFIG_DIR="$HOME/.config/opencode"
 OMOS_CONFIG="$CONFIG_DIR/oh-my-opencode-slim.json"
 
@@ -139,15 +199,14 @@ if [ "${ENABLE_OMOS:-false}" = "true" ]; then
       OMOS_TMUX_FLAG="yes"
     fi
 
-    OMOS_SKILLS_FLAG="yes"
-    if [ "${OMOS_SKILLS:-true}" = "false" ]; then
-      OMOS_SKILLS_FLAG="no"
-    fi
-
+    # Skills are NOT installer-managed any more — they are symlinked from the
+    # image into ~/.agents/skills/ by the OMOS bundled-skills block above
+    # (gated by OMOS_SKILLS). Always pass --skills=no so the installer never
+    # writes frozen copies into the persistent config volume.
     bun x oh-my-opencode-slim@latest install \
       --no-tui \
       --tmux="${OMOS_TMUX_FLAG}" \
-      --skills="${OMOS_SKILLS_FLAG}"
+      --skills=no
 
     echo "oh-my-opencode-slim configured successfully."
   else
@@ -158,13 +217,11 @@ if [ "${ENABLE_OMOS:-false}" = "true" ]; then
       echo "OMOS_RESET=true — regenerating oh-my-opencode-slim config..."
       OMOS_TMUX_FLAG="no"
       [ "${OMOS_TMUX:-false}" = "true" ] && OMOS_TMUX_FLAG="yes"
-      OMOS_SKILLS_FLAG="yes"
-      [ "${OMOS_SKILLS:-true}" = "false" ] && OMOS_SKILLS_FLAG="no"
 
       bun x oh-my-opencode-slim@latest install \
         --no-tui \
         --tmux="${OMOS_TMUX_FLAG}" \
-        --skills="${OMOS_SKILLS_FLAG}" \
+        --skills=no \
         --reset
     fi
   fi

scripts/generate-dockerhub-md.py

@@ -88,7 +88,7 @@ curl -fsSL https://gitea.jordbo.se/joakimp/opencode-devbox/raw/branch/main/.env.
 docker compose run --rm devbox
 ```
 
-This drops you straight into opencode with your project mounted at `/workspace`. Use `bash` as the command (e.g. `docker compose run --rm devbox bash`) to land in a shell first — useful for `aws sso login` or multi-agent workflows.
+This mounts your project at `/workspace`. With no command (as above) the image's default `CMD` (`bash -l`) drops you into a login shell — run `opencode` to start the harness, or `aws sso login` first, etc. To start opencode directly, pass it as the command: `docker compose run --rm devbox opencode`.
 
 **One-shot run, no persistence:**
 

scripts/smoke-test.sh

@@ -180,6 +180,15 @@ if [ "$VARIANT" = "omos" ]; then
                "NPM_CONFIG_PREFIX=/usr npm ls -g --depth=0 2>/dev/null | grep oh-my-opencode-slim" \
                "$EXPECTED_OMOS_VERSION"
   fi
+  # OMOS bundled-skills SOURCE must be present at the fixed image path that
+  # entrypoint-user.sh symlinks into ~/.agents/skills/ on container start. If
+  # upstream restructures the package (moves src/skills), the runtime symlinks
+  # would dangle SILENTLY and the skills would just disappear — assert the
+  # source here so that breakage fails the build loudly instead. We check the
+  # source (not the runtime symlinks) because smoke tests run with
+  # --entrypoint="" and never execute entrypoint-user.sh.
+  run "omos bundled-skills source" \
+      "for n in clonedeps codemap deepwork oh-my-opencode-slim simplify; do test -d /usr/lib/node_modules/oh-my-opencode-slim/src/skills/\$n || exit 1; done && echo ok"
 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"