release: v1.6.2 — lift smoke size threshold (3500→3800)

Completes v1.6.1's studio publish. Run 512 shipped v1.6.1 non-studio
(3411 MB) cleanly, but smoke-studio failed the size gate at 3574 MB vs
the 3500 MB threshold. Threshold was set in v1.0.0 pre-agent-browser
(baseline was 3.20 GB local arm64 + 300 MB margin); v1.6.0 baked in
agent-browser + Chromium (+~291 MB net) but the threshold was never
lifted. v1.6.0 never got to smoke because of the network fault, so
nothing surfaced this until v1.6.1's smoke-studio.

Bump SIZE_THRESHOLD_MB to 3800 (~225 MB margin above observed studio
number, tight enough to still catch a genuine +GB regression). Refresh
the comment above the constant with the current baseline + run 512
actuals so future readers know where the number came from.

CI-only change; image bytes identical to v1.6.1 except for the manifest's
release_tag/source_revision. Not base-affecting.

.dockerignore

@@ -0,0 +1,35 @@
+# Keep the Docker build context minimal and prevent stray files (notably
+# `.git`) from ever being pulled in by a future broad COPY. Both Dockerfiles
+# only COPY `rootfs/` and `entrypoint*.sh`, so everything below is safe to
+# exclude from the context.
+#
+# DO NOT add `rootfs/`, `entrypoint.sh`, `entrypoint-user.sh`, or the
+# Dockerfiles here — they are required to build the image.
+
+# VCS / CI metadata
+.git
+.gitea
+.gitignore
+.dockerignore
+
+# Lint / editor config
+.hadolint.yaml
+.editorconfig
+
+# Docs & project meta
+README.md
+DOCKER_HUB.md
+CHANGELOG.md
+AGENTS.md
+IDEAS.md
+LICENSE
+THIRD_PARTY.md
+docs
+
+# Local orchestration & examples (compose runs the image; not a build input)
+docker-compose.yml
+docker-compose.mempalace.yml
+.env.example
+
+# Repo tooling / tests (run from a checkout, not baked into the image)
+scripts

.env.example

@@ -9,6 +9,19 @@ WORKSPACE_PATH=~/projects
 # Path to SSH keys on host
 SSH_KEY_PATH=~/.ssh
 
+# ── MemPalace memory (local by default) ───────────────────────────
+# By default the mempalace.ts extension spawns a LOCAL mempalace-mcp stdio
+# server (palace at ~/.mempalace). Uncomment the devbox-palace volume in
+# docker-compose.yml to persist it across container recreation.
+#
+# To instead share ONE MemPalace across containers/harnesses (pi + opencode
+# + native), set the URL below. When set, the extension connects over HTTP
+# and NO local mempalace-mcp is spawned; the devbox-palace volume is then
+# irrelevant. MEMPALACE_REMOTE_TOKEN, if set, is sent as a bearer token.
+#   Serve it with:  mempalace-mcp --transport http --host 0.0.0.0 --port 8765
+# MEMPALACE_REMOTE_URL=http://mempalace.lan:8765/mcp
+# MEMPALACE_REMOTE_TOKEN=
+
 # ── LAN access from the container (host-OS-agnostic) ─────────────────
 # On VM-backed hosts (macOS OrbStack / Docker Desktop) the container can't
 # reach the host's directly-attached LAN peers by default. The entrypoint

.gitea/workflows/docker-publish.yml

@@ -38,6 +38,16 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: false
 
+# Gitea Actions' default step shell is `sh -e {0}` (dash), which rejects
+# bash-only syntax like `set -o pipefail`, `[[ ]]`, and arrays. Setting the
+# default to bash workflow-wide eliminates the whole class of "forgot
+# `shell: bash` on this step" bugs (hit twice: ed49b8d resolve-versions,
+# b7197e8/b33e9dc promote-base-latest). All existing dash steps use only
+# POSIX syntax, so bash (a superset) runs them unchanged.
+defaults:
+  run:
+    shell: bash
+
 env:
   BUILDKIT_PROGRESS: plain
   IMAGE: ${{ vars.DOCKERHUB_USERNAME }}/pi-devbox
@@ -58,6 +68,9 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Guard — base *_REF args must be folded into the base hash
+        run: bash scripts/check-base-hash.sh
+
       - name: Compute base tag from Dockerfile.base + dependencies
         id: compute
         run: |
@@ -122,61 +135,105 @@ jobs:
       toolkit_ref: ${{ steps.resolve.outputs.toolkit_ref }}
       extensions_ref: ${{ steps.resolve.outputs.extensions_ref }}
       studio_ref: ${{ steps.resolve.outputs.studio_ref }}
+      studio_tag: ${{ steps.resolve.outputs.studio_tag }}
       mempalace_toolkit_ref: ${{ steps.resolve.outputs.mempalace_toolkit_ref }}
     steps:
       - name: Resolve pi version + companion refs
         id: resolve
+        shell: bash
         run: |
-          set -eu
-          # Query npm registry directly; catthehacker/ubuntu:act-latest's npm
-          # is not reliably on PATH in act_runner job containers.
-          PI_VERSION=$(curl -sf "https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest" | jq -r '.version')
+          set -euo pipefail
+          AUTH_HEADER="Authorization: token ${GITEA_BUILD_TOKEN:-${GITHUB_TOKEN:-}}"
+
+          # Fail loud rather than silently shipping a floating branch. A
+          # transient network/API failure must ABORT the release, not bake
+          # an unpinned ref that defeats both cache-busting AND after-the-
+          # fact reproducibility. (Previously each lookup fell back to
+          # `main`/`master` via `|| echo`.)
+          require_sha() { # $1=label $2=value
+            if ! printf '%s' "${2:-}" | grep -qiE '^[0-9a-f]{40}$'; then
+              echo "::error::Could not resolve $1 to a commit SHA (got '${2:-<empty>}'). Refusing to fall back to a floating ref — published images must stay reproducible. Check connectivity and GITEA_BUILD_TOKEN/GITHUB_TOKEN."
+              exit 1
+            fi
+          }
+
+          # pi version from npm (catthehacker/ubuntu:act-latest's npm is not
+          # reliably on PATH in act_runner job containers, so query directly).
+          PI_VERSION=$(curl -sf "https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest" | jq -r '.version' 2>/dev/null || true)
+          if ! printf '%s' "${PI_VERSION:-}" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Could not resolve pi version from npm (got '${PI_VERSION:-<empty>}')."
+            exit 1
+          fi
           echo "pi_version=${PI_VERSION}" >> "$GITHUB_OUTPUT"
-          # Resolve pi-fork / pi-observational-memory git refs to commit
-          # SHAs so the build-arg string changes whenever upstream moves.
+
+          # pi-fork / pi-observational-memory (GitHub) → commit SHAs.
           FORK_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
-            "https://api.github.com/repos/elpapi42/pi-fork/commits/master" || echo "master")
+            "https://api.github.com/repos/elpapi42/pi-fork/commits/master" || true)
+          require_sha PI_FORK_REF "$FORK_REF"
           OBSMEM_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
-            "https://api.github.com/repos/elpapi42/pi-observational-memory/commits/master" || echo "master")
-          [ -n "$FORK_REF" ]   || FORK_REF=master
-          [ -n "$OBSMEM_REF" ] || OBSMEM_REF=master
+            "https://api.github.com/repos/elpapi42/pi-observational-memory/commits/master" || true)
+          require_sha PI_OBSMEM_REF "$OBSMEM_REF"
           echo "fork_ref=${FORK_REF}"     >> "$GITHUB_OUTPUT"
           echo "obsmem_ref=${OBSMEM_REF}" >> "$GITHUB_OUTPUT"
-          # Also resolve pi-toolkit / pi-extensions main HEADs to SHAs so a
-          # workflow_dispatch re-run produces byte-identical images when
-          # those repos haven't moved (and a clean diff in build-arg strings
-          # when they have, defeating the registry buildcache footgun).
-          # Gitea API requires auth even for public-repo commit listing.
-          TOOLKIT_REF=$(curl -sf -H "Authorization: token ${GITEA_BUILD_TOKEN:-${GITHUB_TOKEN:-}}" \
+
+          # pi-toolkit / pi-extensions (Gitea) → commit SHAs. Gitea API
+          # requires auth even for public-repo commit listing.
+          TOOLKIT_REF=$(curl -sf -H "$AUTH_HEADER" \
             "https://gitea.jordbo.se/api/v1/repos/joakimp/pi-toolkit/commits?limit=1&sha=main" \
-            | jq -r '.[0].sha // "main"' 2>/dev/null || echo "main")
-          EXTENSIONS_REF=$(curl -sf -H "Authorization: token ${GITEA_BUILD_TOKEN:-${GITHUB_TOKEN:-}}" \
+            | jq -r '.[0].sha // empty' 2>/dev/null || true)
+          require_sha PI_TOOLKIT_REF "$TOOLKIT_REF"
+          EXTENSIONS_REF=$(curl -sf -H "$AUTH_HEADER" \
             "https://gitea.jordbo.se/api/v1/repos/joakimp/pi-extensions/commits?limit=1&sha=main" \
-            | jq -r '.[0].sha // "main"' 2>/dev/null || echo "main")
-          [ -n "$TOOLKIT_REF" ]    || TOOLKIT_REF=main
-          [ -n "$EXTENSIONS_REF" ] || EXTENSIONS_REF=main
+            | jq -r '.[0].sha // empty' 2>/dev/null || true)
+          require_sha PI_EXTENSIONS_REF "$EXTENSIONS_REF"
           echo "toolkit_ref=${TOOLKIT_REF}"        >> "$GITHUB_OUTPUT"
           echo "extensions_ref=${EXTENSIONS_REF}"  >> "$GITHUB_OUTPUT"
-          # Resolve mempalace-toolkit main HEAD to a SHA. UNLIKE the others,
-          # 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).
-          MEMPALACE_TOOLKIT_REF=$(curl -sf -H "Authorization: token ${GITEA_BUILD_TOKEN:-${GITHUB_TOKEN:-}}" \
+
+          # mempalace-toolkit (Gitea) → commit SHA. UNLIKE the others this
+          # is cloned in Dockerfile.base, so the SAME SHA is ALSO folded
+          # into the base-decide hash (see that job) to force a base rebuild
+          # when the toolkit moves — otherwise a toolkit-only fix silently
+          # fails to land unless Dockerfile.base itself changes.
+          MEMPALACE_TOOLKIT_REF=$(curl -sf -H "$AUTH_HEADER" \
             "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
+            | jq -r '.[0].sha // empty' 2>/dev/null || true)
+          require_sha MEMPALACE_TOOLKIT_REF "$MEMPALACE_TOOLKIT_REF"
           echo "mempalace_toolkit_ref=${MEMPALACE_TOOLKIT_REF}" >> "$GITHUB_OUTPUT"
-          # Resolve pi-studio (omaclaren/pi-studio) main HEAD to a SHA for
-          # the :latest-studio variant — same cache-busting rationale.
-          STUDIO_REF=$(curl -sf -H "Accept: application/vnd.github.sha" \
-            "https://api.github.com/repos/omaclaren/pi-studio/commits/main" || echo "main")
-          [ -n "$STUDIO_REF" ] || STUDIO_REF=main
+
+          # pi-studio (omaclaren/pi-studio) → newest SEMVER TAG's commit SHA
+          # for the :*-studio images. Upstream stopped publishing GitHub
+          # *Releases* at v0.5.55 but keeps tagging every version (vX.Y.Z) and
+          # pushing to main, so pinning main HEAD risked baking half-finished
+          # commits that land after a tag. Take the newest stable tag instead.
+          # List ALL tags in one `git ls-remote` call — the REST tags API
+          # paginates at 100 and this repo already has >140 tags, so page 1 is
+          # NOT guaranteed to hold the newest — pick the highest X.Y.Z with
+          # `sort -V` (pre-releases like -rc1 excluded by the strict filter),
+          # then resolve its commit SHA (a SHA, not a moving tag, preserves
+          # cache-busting + reproducibility and is what require_sha demands).
+          STUDIO_TAGS=$(git ls-remote --tags "https://github.com/omaclaren/pi-studio.git" || true)
+          STUDIO_TAG=$(printf '%s\n' "$STUDIO_TAGS" | awk '{print $2}' \
+            | sed -n 's#^refs/tags/##p' \
+            | grep -E '^v?[0-9]+\.[0-9]+\.[0-9]+$' \
+            | sort -V | tail -n1 || true)
+          if [ -z "${STUDIO_TAG:-}" ]; then
+            echo "::error::Could not resolve a pi-studio semver tag (git ls-remote empty/unreachable). Refusing to fall back to a floating ref."
+            exit 1
+          fi
+          # Prefer the peeled ^{} line (annotated tags); fall back to the
+          # direct ref (lightweight tags, which pi-studio currently uses).
+          STUDIO_REF=$(printf '%s\n' "$STUDIO_TAGS" | awk -v t="refs/tags/${STUDIO_TAG}^{}" '$2==t{print $1}')
+          if [ -z "$STUDIO_REF" ]; then
+            STUDIO_REF=$(printf '%s\n' "$STUDIO_TAGS" | awk -v t="refs/tags/${STUDIO_TAG}" '$2==t{print $1}')
+          fi
+          require_sha PI_STUDIO_REF "$STUDIO_REF"
           echo "studio_ref=${STUDIO_REF}" >> "$GITHUB_OUTPUT"
+          echo "studio_tag=${STUDIO_TAG}" >> "$GITHUB_OUTPUT"
+
           echo "Resolved PI_VERSION=${PI_VERSION}"
           echo "Resolved PI_FORK_REF=${FORK_REF}, PI_OBSMEM_REF=${OBSMEM_REF}"
           echo "Resolved PI_TOOLKIT_REF=${TOOLKIT_REF}, PI_EXTENSIONS_REF=${EXTENSIONS_REF}"
-          echo "Resolved PI_STUDIO_REF=${STUDIO_REF}"
+          echo "Resolved PI_STUDIO_REF=${STUDIO_REF} (pi-studio ${STUDIO_TAG})"
           echo "Resolved MEMPALACE_TOOLKIT_REF=${MEMPALACE_TOOLKIT_REF}"
 
   # ── Phase 2: build & push base (multi-arch), only when needed ──────
@@ -299,6 +356,9 @@ jobs:
             PI_OBSMEM_REF=${{ needs.resolve-versions.outputs.obsmem_ref }}
             PI_TOOLKIT_REF=${{ needs.resolve-versions.outputs.toolkit_ref }}
             PI_EXTENSIONS_REF=${{ needs.resolve-versions.outputs.extensions_ref }}
+            MEMPALACE_TOOLKIT_REF=${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}
+            RELEASE_TAG=smoke
+            SOURCE_REVISION=${{ github.sha }}
       - name: Smoke test (amd64)
         env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
@@ -355,6 +415,10 @@ jobs:
             PI_EXTENSIONS_REF=${{ needs.resolve-versions.outputs.extensions_ref }}
             INSTALL_STUDIO=true
             PI_STUDIO_REF=${{ needs.resolve-versions.outputs.studio_ref }}
+            PI_STUDIO_VERSION=${{ needs.resolve-versions.outputs.studio_tag }}
+            MEMPALACE_TOOLKIT_REF=${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}
+            RELEASE_TAG=smoke-studio
+            SOURCE_REVISION=${{ github.sha }}
       - name: Smoke test studio (amd64)
         env:
           EXPECTED_PI_VERSION: ${{ needs.resolve-versions.outputs.pi_version }}
@@ -406,10 +470,12 @@ jobs:
           OBSMEM_REF: ${{ needs.resolve-versions.outputs.obsmem_ref }}
           TOOLKIT_REF: ${{ needs.resolve-versions.outputs.toolkit_ref }}
           EXTENSIONS_REF: ${{ needs.resolve-versions.outputs.extensions_ref }}
+          MEMPALACE_TOOLKIT_REF: ${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}
         run: |
           set -euo pipefail
           TAG_FLAGS=()
           while IFS= read -r t; do [[ -n "$t" ]] && TAG_FLAGS+=( -t "$t" ); done <<< "${TAGS}"
+          BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
           # 3-attempt retry (see build-base step for rationale).
           for attempt in 1 2 3; do
             echo "==> Build+push attempt ${attempt}/3"
@@ -423,6 +489,10 @@ jobs:
                 --build-arg "PI_OBSMEM_REF=${OBSMEM_REF}" \
                 --build-arg "PI_TOOLKIT_REF=${TOOLKIT_REF}" \
                 --build-arg "PI_EXTENSIONS_REF=${EXTENSIONS_REF}" \
+                --build-arg "MEMPALACE_TOOLKIT_REF=${MEMPALACE_TOOLKIT_REF}" \
+                --build-arg "RELEASE_TAG=${RELEASE_TAG}" \
+                --build-arg "BUILD_DATE=${BUILD_DATE}" \
+                --build-arg "SOURCE_REVISION=${GITHUB_SHA:-}" \
                 "${TAG_FLAGS[@]}" \
                 .; then
               echo "==> Attempt ${attempt} succeeded"
@@ -487,10 +557,13 @@ jobs:
           TOOLKIT_REF: ${{ needs.resolve-versions.outputs.toolkit_ref }}
           EXTENSIONS_REF: ${{ needs.resolve-versions.outputs.extensions_ref }}
           STUDIO_REF: ${{ needs.resolve-versions.outputs.studio_ref }}
+          STUDIO_TAG: ${{ needs.resolve-versions.outputs.studio_tag }}
+          MEMPALACE_TOOLKIT_REF: ${{ needs.resolve-versions.outputs.mempalace_toolkit_ref }}
         run: |
           set -euo pipefail
           TAG_FLAGS=()
           while IFS= read -r t; do [[ -n "$t" ]] && TAG_FLAGS+=( -t "$t" ); done <<< "${TAGS}"
+          BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
           # 3-attempt retry (see build-base step for rationale).
           for attempt in 1 2 3; do
             echo "==> Build+push attempt ${attempt}/3"
@@ -504,8 +577,13 @@ jobs:
                 --build-arg "PI_OBSMEM_REF=${OBSMEM_REF}" \
                 --build-arg "PI_TOOLKIT_REF=${TOOLKIT_REF}" \
                 --build-arg "PI_EXTENSIONS_REF=${EXTENSIONS_REF}" \
+                --build-arg "MEMPALACE_TOOLKIT_REF=${MEMPALACE_TOOLKIT_REF}" \
                 --build-arg "INSTALL_STUDIO=true" \
                 --build-arg "PI_STUDIO_REF=${STUDIO_REF}" \
+                --build-arg "PI_STUDIO_VERSION=${STUDIO_TAG}" \
+                --build-arg "RELEASE_TAG=${RELEASE_TAG}" \
+                --build-arg "BUILD_DATE=${BUILD_DATE}" \
+                --build-arg "SOURCE_REVISION=${GITHUB_SHA:-}" \
                 "${TAG_FLAGS[@]}" \
                 .; then
               echo "==> Attempt ${attempt} succeeded"
@@ -525,16 +603,19 @@ jobs:
     needs:
       - base-decide
       - build-variant
-    # Skip on cache-hit base builds: when need_build=false, base-latest
-    # already points at the same digest as base-<hash>, so the retag is
-    # a tautology and any transient failure of it is purely cosmetic.
-    # Manual workflow_dispatch with promote_latest=true overrides this
-    # gate as an escape hatch (e.g., if base-latest got hand-deleted).
+    # Run on every tag release (and on promote_latest=true dispatches).
+    # The job-level gate deliberately does NOT key off need_build anymore:
+    # the actual no-op optimization moved INTO the step as a digest compare
+    # (see below). Keying the gate on need_build was wrong because a prior
+    # dry-run dispatch (promote_latest=false) can pre-build+push base-<hash>,
+    # making need_build=false on the subsequent tag run even though
+    # base-latest is still stale — the old gate then skipped promotion and
+    # left base-latest pointing at the PREVIOUS base. (Observed 2026-06-27,
+    # v1.2.3: dry-run-first release left base-latest one base behind.)
     if: |
       always() &&
       needs.build-variant.result == 'success' &&
-      (inputs.promote_latest == 'true' ||
-       (github.ref_type == 'tag' && needs.base-decide.outputs.need_build == 'true'))
+      (inputs.promote_latest == 'true' || github.ref_type == 'tag')
     runs-on: ubuntu-latest
     container:
       image: catthehacker/ubuntu:act-latest
@@ -556,11 +637,38 @@ jobs:
           crane auth login docker.io \
             -u ${{ vars.DOCKERHUB_USERNAME }} \
             -p "${{ secrets.DOCKERHUB_TOKEN }}"
-      - name: Re-tag base-<hash> as base-latest
+      - name: Re-tag base-<hash> as base-latest (only if stale)
+        # shell: bash is REQUIRED — Gitea Actions' default step shell is
+        # `sh -e {0}` (dash), which rejects `set -o pipefail` with
+        # "Illegal option -o pipefail" and aborts the step before the
+        # crane digest-compare runs, leaving base-latest un-promoted.
+        # Same footgun as ed49b8d (resolve-versions). Regression shipped
+        # in b7197e8, caught on the v1.2.4 release (run 418).
+        shell: bash
+        env:
+          BASE_HASH_REF: ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }}
+          BASE_LATEST_REF: ${{ env.IMAGE }}:base-latest
         run: |
-          crane copy \
-            ${{ env.IMAGE }}:${{ needs.base-decide.outputs.base_tag }} \
-            ${{ env.IMAGE }}:base-latest
+          set -euo pipefail
+          # Correctness invariant: after a release, base-latest must resolve to
+          # the SAME digest as the base-<hash> the just-built variants were
+          # FROM. Compare digests rather than trusting need_build — a prior
+          # dry-run dispatch can pre-build base-<hash>, so need_build=false on
+          # the tag run does NOT imply base-latest is already current. When the
+          # digests already match (genuine cache-hit release) this is a no-op,
+          # so we skip the crane copy entirely — preserving the original
+          # "don't do a tautological retag" intent and avoiding any cosmetic
+          # transient-failure exposure on releases that change nothing.
+          want=$(crane digest "${BASE_HASH_REF}")
+          have=$(crane digest "${BASE_LATEST_REF}" 2>/dev/null || echo "")
+          echo "base-<hash> digest: ${want}"
+          echo "base-latest digest: ${have:-<absent>}"
+          if [ "${want}" = "${have}" ]; then
+            echo "base-latest already current; nothing to promote."
+          else
+            echo "Promoting base-latest -> ${BASE_HASH_REF}"
+            crane copy "${BASE_HASH_REF}" "${BASE_LATEST_REF}"
+          fi
 
   # ── Phase 6: update Hub description (only on real release runs) ────
   update-description:

.gitea/workflows/lint.yml

@@ -0,0 +1,93 @@
+name: Lint
+
+# Durable guard against CI-workflow bugs — most importantly the recurring
+# "bash-only syntax under the default `sh`/dash shell" footgun that broke
+# resolve-versions (ed49b8d) and promote-base-latest (b7197e8 → run 418).
+# actionlint runs shellcheck against each `run:` step using its *effective*
+# shell, so `set -o pipefail` under dash is flagged as SC3040 before any
+# expensive build runs. This is cheap (~10s) and independent of the build
+# pipeline, so it fires on every push/PR — not just on release tags, which
+# is where the build workflow (docker-publish.yml) is otherwise only
+# triggered.
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  actionlint:
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install shellcheck
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends shellcheck python3-yaml
+
+      - name: Gitea shell guard (catches the actionlint blind spot)
+        # actionlint models GitHub Actions, where the default run shell is
+        # bash, so it does NOT flag bash syntax in a step that merely OMITS
+        # `shell:` — which is exactly how ed49b8d and b7197e8 manifested on
+        # Gitea (default sh/dash). This guard enforces that every run: step
+        # resolves to bash under Gitea's real defaults. Run it BEFORE
+        # actionlint so the more precise diagnostic surfaces first.
+        run: bash scripts/check-workflow-shell.sh .gitea/workflows
+
+      - name: Install actionlint (pinned)
+        env:
+          ACTIONLINT_VERSION: 1.7.7
+        run: |
+          curl -fsSL \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" \
+            | tar -xz -C /usr/local/bin actionlint
+          actionlint --version
+
+      - name: Run actionlint
+        # SHELLCHECK_OPTS excludes pure-style codes (quoting/style opinions)
+        # so the guard stays focused on correctness bugs — crucially the
+        # SC3xxx "not POSIX / wrong shell" family that catches the pipefail
+        # footgun. Do NOT exclude SC3040 (set -o pipefail under sh) or any
+        # other SC3xxx code.
+        env:
+          SHELLCHECK_OPTS: "-e SC2086 -e SC2016 -e SC2129 -e SC2001 -e SC2312"
+        # Pass explicit paths: actionlint's no-arg mode auto-detects a
+        # project by looking for `.github/workflows`, which doesn't exist in
+        # this `.gitea/workflows` repo and hard-fails with exit 3
+        # ("no project was found"). Globbing the workflow files is the
+        # supported way to lint a non-GitHub layout.
+        run: actionlint -color .gitea/workflows/*.yml
+
+  hadolint:
+    # Lint the two Dockerfiles that ARE the project (the shell/actions linting
+    # above never looked at them). Config — ignored rules + failure threshold
+    # — lives in .hadolint.yaml, which hadolint reads automatically, so a local
+    # `hadolint Dockerfile.base` reproduces CI exactly.
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install hadolint (pinned)
+        env:
+          HADOLINT_VERSION: 2.14.0
+        run: |
+          curl -fsSL \
+            "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-Linux-x86_64" \
+            -o /usr/local/bin/hadolint
+          chmod +x /usr/local/bin/hadolint
+          hadolint --version
+
+      - name: Run hadolint
+        run: hadolint Dockerfile.base Dockerfile.variant

.hadolint.yaml

@@ -0,0 +1,27 @@
+# hadolint configuration for pi-devbox.
+#
+# Both Dockerfiles are linted in CI (.gitea/workflows/lint.yml → `hadolint`
+# job). hadolint reads this file automatically, so a local
+# `hadolint Dockerfile.base` reproduces CI exactly.
+#
+# The ignores below are DELIBERATE project choices — they mirror the
+# philosophy of the shellcheck excludes already applied to `run:` steps
+# (SHELLCHECK_OPTS in lint.yml). Anything NOT listed here still fails the
+# build at `warning` and above, so new Dockerfile smells are caught going
+# forward.
+ignored:
+  - DL3008  # "pin apt versions" — intentionally unpinned: the base tracks
+            #   Debian stable and runs `apt-get upgrade`, so pinning point
+            #   versions would rot and fight security updates.
+  - DL3016  # "pin npm versions" — pi's version IS pinned, but via the
+            #   PI_VERSION build-arg (CI-resolved from npm), not the npm CLI.
+  - DL4006  # "set -o pipefail before a pipe" — the piped RUNs are
+            #   download|extract steps with their own retries / `set -e`.
+            #   Switching the global SHELL to bash is a larger, base-affecting
+            #   change — tracked in IDEAS.md.
+  - DL3003  # "use WORKDIR, not cd" — cosmetic in the few `cd` RUNs here.
+  - SC2086  # "double-quote to prevent word-splitting" — the same code is
+            #   excluded for shell `run:` steps in lint.yml; splitting is
+            #   intentional in these contexts.
+
+failure-threshold: warning

AGENTS.md

@@ -14,15 +14,31 @@ re-brand of opencode-devbox's `pi-only` variant.
 - `Dockerfile.variant` — `FROM base-<hash>`, adds pi + companions
   (`pi-toolkit`, `pi-extensions`, `pi-fork`, `pi-observational-memory`)
   and, when `INSTALL_STUDIO=true`, vendors `pi-studio` to `/opt/pi-studio`
-  (`-studio` variant).
+  (`-studio` variant). Also appends the pi-devbox managed block from
+  `pi-global-AGENTS.append.md` onto pi-toolkit's `pi-global-AGENTS.md` (the
+  single global instruction slot pi loads) so containers proactively load the
+  baked `pi-devbox-environment` skill. Idempotent via a marker grep. After the
+  pinned clones it also refreshes the vendored `pi-extensions` fallback skill
+  by copying `/opt/pi-extensions/skill/` over the committed `rootfs/` snapshot
+  (Option 1 over Option 2 — see `skills/VENDORED.md`).
 - `entrypoint.sh` — UID/GID alignment as root, then drops to `developer`.
-- `entrypoint-user.sh` — per-container start: SSH ControlMaster socket
-  dir, LAN-access setup, MemPalace init, pi-toolkit + pi-extensions
-  deploy, mempalace-bridge symlink, fork/recall + pi-studio pi-install,
-  optional `studio-expose` bridge (when `STUDIO_EXPOSE=1`), skillset
-  deploy.
+- `entrypoint-user.sh` — per-container start: prints the `pi-devbox-version`
+  banner first (which build/commit is running, from the manifest below),
+  then SSH ControlMaster socket dir, LAN-access setup, MemPalace init,
+  pi-toolkit + pi-extensions deploy, mempalace-bridge symlink, fork/recall +
+  pi-studio pi-install, optional `studio-expose` bridge (when
+  `STUDIO_EXPOSE=1`), image-baked skills symlink-in, skillset deploy.
 - `rootfs/` — files baked into the image (bash aliases, inputrc,
-  setup-lan-access.sh, `studio-expose` helper).
+  setup-lan-access.sh, `studio-expose` helper, `pi-devbox-version` — wraps
+  `/etc/pi-devbox/build-manifest.json` into a human-readable summary + live
+  drift check, see README “Build provenance”). Also
+  `usr/local/share/pi-devbox/skills/<name>/SKILL.md` — image-baked agent
+  skills (the repo-authored `pi-devbox-environment`, plus vendored fallback
+  copies of `pi-extensions` and `mempalace` — see `skills/VENDORED.md`)
+  symlinked into `~/.agents/skills/` by the entrypoint, available with or
+  without a mounted skillset — plus
+  `usr/local/share/pi-devbox/pi-global-AGENTS.append.md` (the global-AGENTS
+  pointer concatenated in `Dockerfile.variant`).
 - `scripts/smoke-test.sh` — sanity checks run by CI before pushing to Hub.
 - `.gitea/workflows/docker-publish.yml` — two-phase CI (base-decide →
   build-base → smoke → build-variant → promote-base-latest →
@@ -33,7 +49,8 @@ re-brand of opencode-devbox's `pi-only` variant.
 ## Versioning scheme
 
 - Tags follow semver. **v1.0.0** is the first decoupled release; future
-  minor bumps add variants (`-studio`, `-studio-tex`); patch bumps follow
+  minor bumps add variants (`-studio`, `-studio-tex`) or significant base
+  additions (e.g. v1.2.0 image-baked agent skills); patch bumps follow
   pi npm version updates and small fixes.
 - Docker Hub tags: `joakimp/pi-devbox:vX.Y.Z` + `joakimp/pi-devbox:latest`
   + (since v1.1.0) `joakimp/pi-devbox:vX.Y.Z-studio` +
@@ -45,6 +62,8 @@ re-brand of opencode-devbox's `pi-only` variant.
 
 1. Confirm `pi --version` resolves from npm to the expected version
    (`curl -sf 'https://registry.npmjs.org/@earendil-works%2Fpi-coding-agent/latest' | jq -r .version`).
+   Check release notes at https://github.com/earendil-works/pi/releases for
+   the upstream changelog to include in `CHANGELOG.md`.
 2. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
 3. Verify `docker compose up` works locally with the current `latest` image
    if you're upgrading users from a previous version. Then run the
@@ -61,7 +80,24 @@ re-brand of opencode-devbox's `pi-only` variant.
 6. Verify the Hub tags appear (latest + vX.Y.Z, the `-studio` pair, plus
    base-latest if the base was rebuilt this run).
 7. **Revoke any short-lived Gitea PAT** used during the release at
-   `gitea.jordbo.se/user/settings/applications`.
+   `gitea.jordbo.se/user/settings/applications`. N/A if you used the
+   `GITEA_ACCESS_TOKEN` env var instead (see *Gitea API access* below) —
+   its lifecycle is managed host-side, nothing to revoke.
+
+## Gitea API access (env token)
+
+`GITEA_ACCESS_TOKEN` + `GITEA_HOST` are passed into the container from the
+host `.env` via `docker-compose.yml` (`${GITEA_ACCESS_TOKEN:-}` /
+`${GITEA_HOST:-}`), primarily to enable the `gitea-mcp` server. They are
+**not** baked into the image. When configured, they are also available for
+**any** direct Gitea API interaction from inside the container — inspecting
+CI runs, checking published tags, listing commits — e.g.
+`curl -H "Authorization: token $GITEA_ACCESS_TOKEN" "$GITEA_HOST/api/v1/repos/joakimp/pi-devbox/actions/runs?limit=5"`.
+Prefer this over a short-lived PAT file when the env token is present (the
+`ci-release-watcher` skill auto-detects it). Public-repo GET listings work
+unauthenticated too, so the token matters mainly for private repos or
+rate-limit headroom; its lifecycle is host-managed, so there is nothing to
+revoke after use. Never echo the token value (including into logs).
 
 ## Cache-hit footgun (must-know)
 
@@ -120,10 +156,14 @@ deprecated artifacts (to be removed in opencode-devbox v2.0.0).
 
 ## What we DON'T install (and why)
 
-- **No texlive** (~600 MB–1 GB). Users who need PDF export from pandoc
-  or pi-studio can install on demand: `sudo apt-get install texlive-xetex
-  texlive-latex-recommended`. The planned `:latest-studio-tex` variant
-  will bake this in.
+- **No texlive** (~600 MB–1 GB). PDF export from pandoc / pi-studio works
+  out of the box via **`typst`** (~30 MB static binary), which the base ships
+  as the pandoc PDF engine (`pandoc --pdf-engine=typst`) — small enough to live
+  in base rather than a dedicated `:latest-studio-tex` variant. We don't bake in
+  a full TeX Live: it's heavy and typst covers the common Markdown→PDF case.
+  Users needing LaTeX-exact output can install the higher-fidelity fallback on
+  demand: `sudo apt-get install texlive-xetex texlive-latex-recommended` (then
+  `pandoc --pdf-engine=xelatex`).
 - **pi-studio** ships in the `:latest-studio` variant (since v1.1.0),
   vendored to `/opt/pi-studio` and registered at container start via
   `pi install /opt/pi-studio` (see Dockerfile.variant `INSTALL_STUDIO`).

CHANGELOG.md

@@ -13,6 +13,829 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ## Unreleased
 
+_Nothing yet — next release's changes will accrue here._
+
+## v1.6.2 — 2026-07-23
+
+Patch release. **Completes the v1.6.1 studio publish.** CI-only change; the
+shipped image content is identical to v1.6.1 apart from the bumped `pi`
+version resolution at build time (still `0.81.1`).
+
+> **Note on v1.6.1.** Ran on 2026-07-23; the non-studio variant (`v1.6.1`,
+> `latest`, `base-latest`) shipped cleanly, but the studio variant was blocked
+> in the smoke-studio job by a size assertion that was still calibrated for
+> the pre-`agent-browser` baseline. `v1.6.1-studio` and `latest-studio` were
+> never pushed; `latest-studio` on Hub still points at v1.5.0-studio until
+> v1.6.2 lands. Users who pull `joakimp/pi-devbox:v1.6.1` today get a valid
+> non-studio image with `pi 0.81.1` baked; there is no `v1.6.1-studio` image.
+
+### Fixed (CI)
+
+- **`scripts/smoke-test.sh`: raise `SIZE_THRESHOLD_MB` from `3500` to `3800`.**
+  The 3500 threshold was set in v1.0.0 based on a local arm64 build measured
+  at 3.20 GB plus a `+300 MB` margin. v1.6.0 baked in `agent-browser` +
+  Playwright Chromium (~291 MB net, documented in v1.6.0's entry) but the
+  threshold was never updated — v1.6.0 never ran to smoke because of the
+  site-network fault, so nothing surfaced the miscalibration until
+  run 512 (v1.6.1) reached smoke-studio and reported
+  `3574 MB exceeds threshold 3500 MB`. Actual CI amd64 sizes observed on
+  run 512: **3411 MB non-studio**, **3574 MB studio**. The new 3800 MB
+  ceiling carries ~225 MB margin above the studio number — enough to absorb
+  minor arch/build-cache variance and small future growth, still tight
+  enough to catch a genuine +GB regression. The comment above the constant
+  is refreshed to reflect the new baseline (agent-browser included, run 512
+  actuals). Not base-affecting; base hash unchanged.
+
+- **`scripts/smoke-test.sh`: don't hard-code a `v` prefix on `release_tag`
+  in the `pi-devbox-version` human-output assertion.** (Landed on the
+  retagged `v1.6.1` and carried forward in `v1.6.2`.) The smoke workflow
+  deliberately passes `RELEASE_TAG=smoke` / `RELEASE_TAG=smoke-studio` to
+  the variant build so smoke images don't collide with real `vX.Y.Z` tags,
+  and `pi-devbox-version` correctly prints `pi-devbox smoke`. The prior
+  assertion required the literal substring `pi-devbox v` — only true for
+  real releases — so it fired on every smoke run once it existed. The two
+  neighbouring assertions on `--json` and `--quiet` already cover the value
+  of `release_tag`; the human-output assertion now only verifies that the
+  line renders (substring `pi-devbox ` — note the trailing space). Never
+  fired before because `pi-devbox-version` was added post-v1.5.0 and every
+  CI attempt since was blocked before smoke ran.
+
+## v1.6.1 — 2026-07-22
+
+Patch release. Headline: **pi `0.80.6` → `0.81.1`** (npm `latest`) — the first
+pi bump since v1.5.0.
+
+> **Note on v1.6.0.** The `v1.6.0` git tag was cut on 2026-07-17 (agent-browser +
+> `pi-devbox-version`, see below) but never reached Docker Hub: the variant
+> publish was blocked by an intermittent SYN-drop fault on the on-prem CI
+> network (`ci-network-diagnosis.md`, since resolved). v1.6.1 lands v1.6.0's
+> content **plus** the pi bump in one release; there is no `v1.6.0` image on
+> Docker Hub. The `v1.6.0` git tag is left in place as an accurate record of
+> what was intended on that day.
+
+### Changed
+
+- **pi `0.80.6` → `0.81.1`.** The CI resolves `pi@latest` at build time; latest
+  is now `0.81.1`. The intermediate `0.81.0` is deliberately skipped: 0.81.0
+  removed the default stream fallback for extensions using the pre-0.81
+  `@earendil-works/pi-agent-core` API, which `pi-observational-memory` relies
+  on (`agentLoop` + `stream.result()` in the observer/reflector/dropper
+  agents). 0.81.1 restored the fallback ([earendil-works/pi#6915][pi-6915]),
+  making 0.81.1 — but not 0.81.0 — a safe drop-in. `pi-fork` only imports
+  types from `pi-agent-core` and is unaffected. Everything since v1.5.0's
+  baked `0.80.6` (i.e. `0.80.7`–`0.80.10`, `0.81.0`, `0.81.1`) was audited for
+  breaking changes against the two baked extensions — none affect this image.
+  The Node engine requirement rose to `>=22.19.0` in `0.81.0`; the base still
+  ships `22.23.1` (nodesource 22.x), so no engine bump is needed. Highlights
+  users inherit from the upstream jump: **local llama.cpp router support**
+  (search + download Hugging Face models, explicit load/unload, live
+  progress); **full pi-ai provider extensions** (extensions can now register
+  complete providers with native auth, model refresh, filtering, and
+  streaming); **Qwen Token Plan** subscription providers; **resilient
+  compaction / branch-summary retries** on transient provider failures with
+  lifecycle events exposed to interactive, JSON, RPC, and SDK consumers;
+  expanded usage accounting for tools, compaction, and branch summaries.
+  Base-affecting (npm install line rebuilds), so `base-<hash>` rebuilds. See
+  the [pi changelog][pi-changelog] for the full list.
+
+[pi-6915]: https://github.com/earendil-works/pi/issues/6915
+[pi-changelog]: https://github.com/earendil-works/pi/blob/main/CHANGELOG.md
+
+## v1.6.0 — 2026-07-13
+
+> ⚠️ **Never published to Docker Hub.** Tagged in git on 2026-07-17 but the
+> variant publish was blocked by a site-network fault before the image reached
+> the registry. Superseded by v1.6.1, which carries this release's content
+> forward alongside the `pi 0.81.1` bump.
+
+### Added
+
+- **`agent-browser` — headless browser automation, baked into every variant.**
+  The base now ships the [`agent-browser`](https://www.npmjs.com/package/agent-browser)
+  CLI plus a Playwright-fetched Chromium, so the agent can drive a real browser
+  (open/click/fill/`eval`/screenshot/snapshot) and *verify* front-end work
+  involving live DOM or WebGL instead of guessing. The `agent-browser` skill
+  (from the skillset repo) was previously a no-op because the binary was
+  absent; it now works out of the box. Two pieces: the standalone Rust CLI
+  (npm, `NPM_CONFIG_PREFIX=/usr` so it survives the `~/.pi/npm-global` volume),
+  and a Chromium fetched via `playwright install --with-deps chromium` into
+  `PLAYWRIGHT_BROWSERS_PATH=/usr/local/share/ms-playwright` (a system path,
+  never shadowed by the `/home/developer` volume — unlike agent-browser's own
+  `~/.agent-browser/browsers` default). A stable `/usr/local/bin/agent-chrome`
+  symlink, exported as `AGENT_BROWSER_EXECUTABLE_PATH`, insulates the config
+  from Playwright's per-version `chromium-<rev>` directory name. Debian trixie
+  `--with-deps` dependency resolution verified (the t64 renames are handled).
+  The global AGENTS.md managed block
+  (`rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md`) gains a short
+  pointer so agents discover the capability. Adds ~625 MB (Chromium; Playwright's
+  unused headless-shell build is dropped and the apt/npm caches cleaned in-layer
+  to stay lean). Base-affecting, rebuilds `base-<hash>`.
+
+- **`pi-devbox-version` command.** Wraps `/etc/pi-devbox/build-manifest.json`
+  into a human-readable summary (release tag, build date, source revision,
+  baked `pi_version`, and short SHAs for every `/opt` component) instead of
+  requiring users to know the manifest path and pipe it through `jq`
+  themselves. Also flags **live drift** — if `pi --version` no longer matches
+  what was baked at build time, the `pi:` line calls that out rather than
+  silently trusting the manifest. `--json` dumps the raw manifest for
+  scripting; `--quiet` gives a one-line `release_tag (source_revision)` form.
+  Printed automatically once at container start (`entrypoint-user.sh`, before
+  the rest of the setup output), and stays available on demand for the rest
+  of the session. Exits 1 with a short notice — rather than failing silently
+  — on images built before this file existed. Base-affecting (new
+  `rootfs/usr/local/bin/pi-devbox-version`), rebuilds `base-<hash>`.
+
+### Changed
+
+- **Bundled `pi-toolkit` settings template: `pi-fork` balanced tier bumped to
+  `eu.anthropic.claude-sonnet-5`** (was `claude-sonnet-4-6`), matching the model
+  now in use. The image clones `pi-toolkit@main` into `/opt/pi-toolkit` at build
+  time, so the next build bundles it automatically (pi-toolkit `0010417`); the
+  same commit also refreshes the template's `enabledModels` and the README
+  examples. Seed-only: existing containers keep their live `~/.pi/agent/settings.json`
+  (the entrypoint merge is live-wins), so only fresh `~/.pi` volumes are affected.
+
+## v1.5.0 — 2026-07-13
+
+### Added
+
+- **Seeded global gitignore now ignores `**/.claude/settings.local.json`.** Claude
+  Code's per-machine local settings file holds machine-specific permissions and
+  can carry credentials, so it should never be committed. The seed
+  (`rootfs/home/developer/.gitignore_global`, baked to `/etc/skel-devbox/`) gains
+  the pattern so fresh containers match a host global that already ignores it.
+  Existing containers are unaffected (the seed is copied only when
+  `~/.gitignore_global` is absent); their file can be updated by hand. Base-
+  affecting (`Dockerfile.base` COPY of the seed), rebuilds `base-<hash>`.
+
+- **Readable Neovim colours out of the box.** The base now ships a system-wide
+  Neovim config (`/etc/xdg/nvim/sysinit.vim`) that enables `termguicolors`,
+  plus the `kitty-terminfo` package. Vanilla Neovim otherwise fell back to a
+  256-colour palette over ssh/kitty and rendered strings and comments in a
+  muddy, low-contrast dark colour. `sysinit.vim` is Neovim's system vimrc: it
+  loads for every user before any personal `~/.config/nvim` and can still be
+  overridden per-user (`:set notermguicolors`, or your own init). Base-affecting
+  (`Dockerfile.base` apt package + COPY), rebuilds `base-<hash>`.
+
+- **Terminal support beyond kitty: `ncurses-term` + a compiled `xterm-ghostty`
+  alias.** The base previously shipped only `ncurses-base` (xterm-256color,
+  tmux), so SSHing in from a modern emulator degraded to a dumb fallback. The
+  base now installs `ncurses-term` (terminfo for WezTerm, Alacritty, foot, st,
+  and the base `ghostty` entry, among many others) and compiles an
+  `xterm-ghostty` alias with `tic -x` (`use=ghostty`) — Ghostty connects as
+  `TERM=xterm-ghostty` and no distro packages that name. Combined with
+  `kitty-terminfo` (xterm-kitty) and xterm-256color (iTerm2's default, already
+  in ncurses-base), the common modern terminals now resolve their TERM. The
+  approach mirrors the maintainer's ansible `common` role. Base-affecting
+  (`Dockerfile.base` apt + COPY + `tic` RUN, plus a new
+  `rootfs/usr/local/share/terminfo-src/ghostty.terminfo`), rebuilds `base-<hash>`.
+
+- **Repository hygiene: `LICENSE`, `THIRD_PARTY.md`, and `.dockerignore`.** The
+  repo declared MIT only in prose; it now ships an actual `LICENSE` file (MIT,
+  © Joakim Persson) plus `THIRD_PARTY.md` recording that the published images
+  bundle third-party software under its own terms (pi, pi-fork,
+  pi-observational-memory, pi-studio — all MIT; gosu Apache-2.0; Debian packages
+  under their respective licenses). A new `.dockerignore` trims the build
+  context to what the Dockerfiles actually `COPY` (`rootfs/` + `entrypoint*.sh`),
+  keeping `.git`, docs, `scripts/`, and compose files out — cheaper context and
+  no risk of a future broad `COPY` pulling in `.git`. Not base-affecting (the
+  base hash covers only `Dockerfile.base` + `rootfs/` + `entrypoint*.sh`);
+  image contents are byte-identical.
+
+- **Dockerfile linting (`hadolint`) in CI, plus an `IDEAS.md` backlog.** The
+  lint workflow already ran actionlint + shellcheck on `run:` steps but never
+  looked at the two Dockerfiles that are the heart of the project. A new
+  `hadolint` job (pinned v2.14.0, same download-pin pattern as actionlint) lints
+  `Dockerfile.base` and `Dockerfile.variant`; `.hadolint.yaml` grandfathers the
+  deliberate choices (unpinned apt/npm, `cd`-in-`RUN`, `SC2086` — mirroring the
+  existing shellcheck excludes) and fails on anything new at `warning`+.
+  `IDEAS.md` parks the vetted-but-unscheduled follow-ups (SHA-pin CI actions,
+  trivy scanning, buildx SBOM/provenance attestations, a local `Makefile`,
+  renovate). Repo/CI only — not baked into the image.
+
+### Changed
+
+- **`-studio` images now pin pi-studio to its newest *semver tag* instead of
+  `main` HEAD.** Upstream `omaclaren/pi-studio` abandoned GitHub *Releases* at
+  v0.5.55 but keeps tagging every version (currently `v0.9.36`) and pushing to
+  `main`; tracking `main` HEAD risked baking half-finished commits that land
+  after a tag. CI (`resolve-versions`) now lists every tag via a single
+  `git ls-remote` (the REST tags API paginates at 100 and the repo already has
+  >140 tags), selects the highest `X.Y.Z` with `sort -V` (pre-releases
+  excluded by a strict filter), and pins that tag's commit SHA into
+  `PI_STUDIO_REF`. Pinning the SHA (not the moving tag) preserves cache-busting
+  and reproducibility, is what `require_sha` demands, and is recorded in the
+  `se.jordbo.pi-devbox.pi-studio-ref` image label. The human-readable tag (e.g.
+  `v0.9.36`) is now also recorded in a new `se.jordbo.pi-devbox.pi-studio-version`
+  label for at-a-glance identification (`docker inspect`). Studio-variant only —
+  not base-affecting; takes effect on the next `-studio` build. No change to the
+  resolved commit today (`v0.9.36` == current `main` HEAD).
+
+### Fixed
+
+- **`pandoc --pdf-engine=typst` now works without `-V mainfont`.** pandoc's
+  bundled typst template (`/usr/share/pandoc/data/templates/template.typst`)
+  defaults the document font to an empty tuple (`font: ()`), so a naked
+  `pandoc --pdf-engine=typst` (and `studio_export_pdf` in some cases) failed
+  with `error: font fallback list must not be empty` unless the caller passed
+  `-V mainfont="..."`. The base now patches that template default to
+  `Libertinus Serif` (typst's own bundled default font) at build time, so PDF
+  export works out of the box. Base-affecting (`Dockerfile.base` RUN), rebuilds
+  `base-<hash>`. README gains a "Generating a PDF with pandoc + typst" section
+  with the working command and how to override the font via `-V mainfont`.
+
+---
+
+## v1.4.0 — 2026-07-11
+
+Minor release. Headline: **PDF export works out of the box** — the base now
+ships **`typst`** as the pandoc PDF engine (`pandoc --pdf-engine=typst`), so
+`studio_export_pdf` / `pandoc -o out.pdf` no longer fail with "xelatex not
+found". Also adds a **host SSH reachability check at shell startup**. Both are
+base-affecting (`Dockerfile.base` apt+RUN for typst/xz-utils; `.bash_aliases`
+for the SSH check is COPYd into the base), so the base rebuilds and both land in
+`base-<hash>`. pi auto-resolves `latest` at build time (0.80.3 → 0.80.6);
+mempalace stays pinned at 3.5.0 (current PyPI latest).
+
+### Added
+
+- **Host SSH reachability check at shell startup.** `~/.bash_aliases` (baked
+  into the image) now runs a one-time SSH probe on the first bash session of
+  each container. If the Mac host is not reachable (Remote Login disabled or
+  the `devbox_jump` key not yet authorized) it prints a clear warning with the
+  exact two steps to fix it, including the container's public key inline.
+  Subsequent shells in the same container skip the check (flag in `/tmp`,
+  cleared on recreate). Silent when SSH is working. Complements the existing
+  key-generation message in `setup-lan-access.sh` which only fires once at key
+  creation time and can easily be missed. Commit `4563b4d`.
+
+- **`typst` — lightweight PDF engine for pandoc (Markdown→PDF).** `pandoc` has
+  shipped in the base since v1.0.0 but as a front-end only — with no PDF
+  back-end installed, `studio_export_pdf` / `pandoc -o out.pdf` failed with
+  "xelatex not found". The base now installs `typst`, a single ~30 MB static
+  Rust binary (no LaTeX), used via `pandoc --pdf-engine=typst`. Chosen over a
+  ~600 MB TeX Live install; a fuller TeX Live remains the higher-fidelity
+  fallback for anyone needing LaTeX-exact output (install on demand). Also adds
+  `xz-utils` to the apt layer (typst ships a `.tar.xz` asset that `tar` needs
+  `xz` to extract). Installed with the standard `latest` GitHub-release idiom;
+  pin with `--build-arg TYPST_VERSION=vX.Y.Z`. This lands in `base-<hash>`
+  (Dockerfile.base changed). Supersedes the previously-planned
+  `:latest-studio-tex` variant — typst is small enough to ship in BASE, so no
+  separate TeX variant is needed. See `pi-devbox-roadmap`.
+
+---
+
+## v1.3.0 — 2026-07-02
+
+Minor release. Headline: **shared/external MemPalace** — the `mempalace.ts`
+bridge can now point at one MemPalace HTTP server (`MEMPALACE_REMOTE_URL`,
+optional `MEMPALACE_REMOTE_TOKEN`) shared across containers/harnesses instead of
+a per-container local palace; ships `docker-compose.mempalace.yml` for the
+server. Also ships the **`nano` + `micro`** non-modal editors and a **CI
+workflow-lint layer** (Gitea-accurate sh-vs-bash guard + actionlint/shellcheck),
+with the `docker-publish.yml` bash-defaults and `promote-base-latest` shell
+fixes. pi stays `0.80.3`; the base image rebuilds (the mempalace-toolkit ref
+advanced and `Dockerfile.base` gained nano/micro), so the new bridge and editors
+land in `base-<hash>`.
+
+### Added
+
+- **Share one MemPalace across containers via `MEMPALACE_REMOTE_URL`.** The
+  `mempalace.ts` bridge (from `mempalace-toolkit`) can now connect to a shared
+  MemPalace over HTTP instead of spawning a per-container local server: set
+  `MEMPALACE_REMOTE_URL=http://<host>:8765/mcp` (optionally
+  `MEMPALACE_REMOTE_TOKEN`) in `.env` and no local `mempalace-mcp` is spawned.
+  A new `docker-compose.mempalace.yml` stands up such a shared server
+  (`mempalace-mcp --transport http`). Leaving the URL unset keeps the default
+  local-per-container palace. See `.env.example`. (The HTTP transport is
+  unauthenticated — keep it on a trusted network or behind a reverse proxy.)
+
+- **Two non-modal terminal editors alongside `nvim`: `nano` and `micro`.**
+  The image previously shipped only `nvim` (with `EDITOR=nvim`), a modal
+  vi-style editor. Not everyone is comfortable with vi keybindings, so both
+  a classic and a modern non-modal option now ship:
+  - **`nano`** (apt) — ~2.8 MB installed. Its dependencies (`libc6`,
+    `libncursesw6`, `libtinfo6`) are already present via `nvim`/`less`/`htop`/
+    `tmux`, so it pulls in **no extra packages**. On-screen shortcut hints
+    (`^O` write, `^X` exit) make it the lowest-friction fallback.
+  - **`micro`** — ~12 MB, a single static Go binary installed from GitHub
+    releases (same pattern as `bat`/`eza`/`zoxide`). Desktop-style keybindings
+    (`Ctrl+S` save, `Ctrl+Q` quit, `Ctrl+C/V/X`, `Ctrl+Z` undo), mouse
+    support, and syntax highlighting out of the box. Pin with
+    `--build-arg MICRO_VERSION=vX.Y.Z`; defaults to `latest`.
+
+  Combined footprint is ~15 MB (<0.5% of the ~3.2 GB image). **`EDITOR`
+  stays `nvim`** — the new editors are opt-in via `export EDITOR=micro`
+  (or `nano`) and/or `git config --global core.editor micro`.
+
+  Note: micro's upstream repo moved `zyedidia/micro` → `micro-editor/micro`;
+  the Dockerfile uses the canonical URL because the old org's
+  `/releases/latest` redirect lands on another `/latest` URL (the org
+  rename), which would defeat the tag-parsing `latest`-resolution idiom.
+  These are base-image additions, so they only land once the `base-<hash>`
+  rebuilds (this file changed, so the next build picks them up).
+
+### Added (CI)
+
+- **Workflow lint (`.gitea/workflows/lint.yml`) running on every push and PR.**
+  Two complementary checks, so CI-workflow bugs are caught before an expensive
+  build runs:
+  - **`scripts/check-workflow-shell.sh`** — a Gitea-accurate guard that fails
+    if any `run:` step doesn't resolve to `bash` under Gitea's real defaults.
+    This catches the exact recurrence class (omit `shell:`, use bash syntax),
+    which **actionlint alone does not** — actionlint models GitHub Actions
+    (default shell = bash) and so assumes a shell-less step is bash, whereas
+    Gitea's default is `sh`/dash.
+  - **`actionlint` + `shellcheck`** — catches explicit `shell: sh` + bash
+    syntax (SC3040 etc.), expression errors, and general workflow mistakes.
+    Style-only shellcheck codes are excluded; the SC3xxx "wrong shell" family
+    is kept.
+
+### Changed (CI)
+
+- **Workflow-level `defaults: run: shell: bash` in `docker-publish.yml`.**
+  Gitea Actions defaults each `run:` step to `sh` (dash), so every bash-syntax
+  step had to individually remember `shell: bash` — a discipline requirement
+  that failed twice (ed49b8d, b7197e8). Setting the default workflow-wide
+  eliminates the whole class. All pre-existing dash steps use only POSIX
+  syntax, so bash (a superset) runs them unchanged.
+
+### Fixed (CI)
+
+- **`promote-base-latest` now sets `shell: bash` on the base-latest re-tag
+  step.** The `b7197e8` fix (v1.2.4) moved the digest-compare into that step
+  with `set -euo pipefail`, but Gitea Actions' default step shell is `sh`
+  (dash), which rejects `-o pipefail` (`Illegal option -o pipefail`) and aborts
+  the step before the `crane copy` runs. On the v1.2.4 release (run 418) this
+  left `base-latest` un-promoted, still pointing at the v1.2.3 base — the four
+  consumer tags (`v1.2.4`, `latest`, `v1.2.4-studio`, `latest-studio`) were
+  unaffected because they `FROM` the exact `base-<hash>`, not `base-latest`.
+  Same footgun as `ed49b8d` (`resolve-versions needs shell: bash`).
+
+---
+
+## v1.2.4 — 2026-06-29
+
+Patch release. Headline: **pi `0.80.2` → `0.80.3`** (npm `latest`). Also ships a
+global gitignore baked into the image, secrets-via-`env_file`-only compose
+hardening, and a CI fix so `promote-base-latest` re-points `base-latest`
+reliably after a dry-run-first release. The mempalace pin stays `3.5.0`. The
+base image rebuilds because `Dockerfile.base` changed (the gitignore seed +
+`entrypoint-user.sh` wiring).
+
+### Added
+
+- **Global gitignore baked into the image.** A `~/.gitignore_global`
+  (`*.bak`, `*.bak.*`, `*~`, `*.orig`, `*.swp`, `*.tmp`) is seeded into the home
+  dir from `/etc/skel-devbox/` on first boot (seed-if-absent, like
+  `.bash_aliases`/`.inputrc`, so user edits survive recreate) and wired via
+  `git config --global core.excludesFile`. Personal/tooling backup artifacts are
+  now ignored across all repos in the container without per-repo `.gitignore`
+  entries. The `core.excludesFile` wiring is skipped if the user already set one.
+
+### Changed
+
+- **Secrets are now delivered to the container via `env_file: .env` only; the
+  `environment:` block no longer re-declares `GITEA_ACCESS_TOKEN`,
+  `GITEA_HOST`, or `GITHUB_PERSONAL_ACCESS_TOKEN`.** An `environment:` entry
+  both overrides `env_file:` and is interpolated from the host shell, so a
+  stale shell export (e.g. one auto-loaded by an opencode/dotenv hook) would
+  silently shadow the value in your `.env` — an updated token in `.env` never
+  reached the container. Delivering secrets via `env_file` only decouples the
+  container from whatever the host shell happens to export. No action needed:
+  `.env.example` already documents every supported variable. Affects
+  `docker-compose.yml` and the README “basic shape” snippet.
+
+### Fixed (CI)
+
+- **`promote-base-latest` now re-points `base-latest` reliably after a
+  dry-run-first release.** The job's gate previously required
+  `need_build == 'true'`, on the assumption that `need_build == false`
+  implied `base-latest` was already current. That assumption breaks when a
+  `workflow_dispatch` dry-run (`promote_latest=false`) pre-builds and pushes
+  `base-<hash>` first: the subsequent tag run then sees `need_build == false`
+  (probe hit) and **skipped** promotion, leaving `base-latest` pointing at the
+  *previous* base. (Observed 2026-06-27 releasing v1.2.3 via dry-run-then-tag
+  — `base-latest` ended up one base behind, lacking the mempalace self-heal.)
+  Now the gate runs on every tag release (or `promote_latest=true` dispatch),
+  and the no-op optimization moved **into** the step as a `crane digest`
+  compare: it re-tags only when `base-latest` actually differs from the
+  released `base-<hash>`, so genuine cache-hit releases stay a no-op while
+  stale aliases get corrected. No image-content change; base hash unaffected.
+
+---
+
+## v1.2.3 — 2026-06-27
+
+Patch release. Headline: **mempalace-mcp now self-heals** instead of latching
+`available=false` permanently after a slow cold-open. Also folds in the `yq`
+and mempalace-skill changes that were sitting unreleased. **No pi/mempalace
+version change** — pi npm `latest` is still `0.80.2` (= v1.2.2) and the
+mempalace pin stays `3.5.0`; the base image rebuilds purely because the
+`mempalace-toolkit` ref advances to pick up the self-heal extension.
+
+### Fixed
+
+- **mempalace-mcp self-heal — no more permanent `available=false` latch.**
+  The `mempalace.ts` pi extension (from `mempalace-toolkit`, bumped to
+  [`e12b624`](https://gitea.jordbo.se/joakimp/mempalace-toolkit/commit/e12b624))
+  previously tripped its per-request timeout on a slow virtiofs cold-open of
+  the palace, killed the child, and set `available=false` **forever** (no
+  respawn) — a pi restart was the only recovery.
+  - **Bounded respawn with capped exponential backoff** via `ensureAlive()`
+    (`MEMPALACE_MCP_MAX_RESPAWNS=2`, `MEMPALACE_MCP_RESPAWN_BACKOFF_MS=1000`;
+    set max to `0` to disable). Both `execute()` and initial startup route
+    through it. The respawn budget **resets on any successful JSON-RPC
+    response** (`onStdout`), so a healthy session can't slowly exhaust it.
+  - **Scoped init timeout** raised `120000 → 300000` ms (`MEMPALACE_MCP_INIT_TIMEOUT_MS`),
+    affecting **init only** — the per-call timeout stays `60000`
+    (`MEMPALACE_MCP_TIMEOUT_MS`) — so a genuine cold HNSW deserialize isn't
+    killed mid-open.
+  - **Concurrency hardening:** a generation counter prevents a late-exiting
+    killed process from clobbering a fresh respawn, and an explicit `healthy`
+    flag replaces the racy `proc != null` check.
+  - Note: the build-time `smoke-test.sh` verifies the extension is present and
+    deployed but does **not** exercise respawn behaviour — first live
+    validation is on a running container.
+- **`yq` is now mikefarah's Go yq, not Debian's Python `yq`.** The base image
+  previously apt-installed `yq`, which on Debian/Ubuntu is the unrelated
+  kislyuk/`yq` (a jq wrapper, v3.x) — incompatible with the mikefarah v4 syntax
+  the `cloud-init` repo's `provision.sh`/`deploy.sh` expect. Dropped the apt
+  package and install the mikefarah binary instead (multi-arch amd64/arm64,
+  following the repo's `latest` convention like `tealdeer`/`uv`; pin a tag
+  with `--build-arg YQ_VERSION=vX.Y.Z`). The build-time `smoke-test.sh` gate
+  asserts `yq --version` reports `mikefarah` **and** major **v4**, so both a
+  regression to the Python package and a surprise future yq v5 fail CI.
+
+### Changed
+
+- **Baked `mempalace` skill now teaches temporal grounding.** Added a
+  *Temporal grounding* rule to the image-baked
+  `skills/mempalace/SKILL.md` (Phase 1 wake-up + a matching anti-pattern):
+  before using relative time terms ("yesterday", "last week"), establish the
+  current date/time and compute the delta against the actual diary/drawer
+  timestamp. Explicitly calls out that a **container recreate or fresh session
+  is not a day boundary** — pi-devbox restarts several times a day, so two
+  entries minutes apart can straddle a recreate. Fixes agents mislabelling
+  same-day sessions as "yesterday".
+
+---
+
+## v1.2.2 — 2026-06-24
+
+Patch release: pick up **pi `0.80.2`** (npm `latest`) and **mempalace `3.5.0`**,
+and drop the now-obsolete `diary_write` schema workaround — the upstream fix
+shipped.
+
+### Changed
+
+- **mempalace pin `3.4.0` → `3.5.0`.** mempalace 3.5.0 carries the upstream
+  fix for the top-level-`anyOf` `diary_write` schema
+  ([issue #1728](https://github.com/MemPalace/mempalace/issues/1728) /
+  [PR #1717](https://github.com/MemPalace/mempalace/pull/1717), merged
+  2026-06-14). The advertised schema is now `"required": ["agent_name"]` with
+  `entry`/`content` enforced at dispatch instead of via a root-level `anyOf`,
+  which Anthropic's tools API accepts. Verified against the published 3.5.0
+  wheel's `mcp_server.py` before removing the workaround.
+- **pi `0.79.10` → `0.80.2`**, auto-resolved from npm `latest` at build time
+  (no pin in the repo; CI's `resolve-versions` job fetches it).
+
+### Removed
+
+- **The `diary_write` top-level-`anyOf` workaround in `Dockerfile.base`.** The
+  `perl` patch that rewrote the installed `mcp_server.py` (needed while
+  mempalace 3.3.x/3.4.0 advertised a top-level `anyOf` that Anthropic rejects,
+  failing tool registration at session start) is gone, since 3.5.0 fixes it at
+  the source. Keep `MEMPALACE_VERSION` in lockstep with opencode-devbox.
+
+### Notes
+
+- Unrelated to this release: a *stalled* `mempalace-mcp` (e.g. a slow virtiofs
+  cold-open of `chroma.sqlite3`) surfaces as `mempalace-mcp not available`
+  because the `mempalace.ts` extension's per-request timeout kills the child
+  and flips `available=false` until pi is restarted — this is the 2026-06-13
+  stall-protection behaving as designed, not the `anyOf` bug.
+
+---
+
+## v1.2.1 — 2026-06-22
+
+Patch release: close the fork/recall + mempalace **under-utilisation gap** in
+containers started without the private `skillset` repo — bake the
+`pi-extensions` and `mempalace` skills into the image and add the missing
+mempalace session-start directive. pi version is re-resolved from npm `latest`
+at build.
+
+### Added
+
+- **Vendored fallback skills: `pi-extensions` + `mempalace`.** The pi-toolkit
+  global `AGENTS.md` directs every pi session to read
+  `~/.agents/skills/pi-extensions/SKILL.md` at start (the fix for fork/recall
+  under-utilisation). That pointer dangled in a container started **without**
+  the private `skillset` repo mounted. The image now bakes fallback copies of
+  both skills under `/usr/local/share/pi-devbox/skills/`, symlinked in by
+  `entrypoint-user.sh` (only when absent, so a mounted skillset still wins).
+- **Proactive-load directive for `mempalace`.** Baking the skill only fixes
+  *availability*; nothing in pi-toolkit's global `AGENTS.md` told sessions to
+  load it, so it would still surface only via description-matching. The
+  pi-devbox managed block (`pi-global-AGENTS.append.md`) now adds a
+  session-start pointer (gated to pi-devbox containers, conditional on the
+  MemPalace MCP tools being present) so a new container actually picks the
+  skill up — memory continuity matters most in a frequently-recreated
+  container. (`pi-extensions`'s directive already ships in pi-toolkit, so only
+  its skill file needed baking.)
+- **Layered freshness for the `pi-extensions` skill (Option 1 + Option 2).**
+  The canonical skill was promoted into the **public `pi-extensions` package
+  repo** under `skill/` (co-located with the extensions it documents). A
+  committed snapshot in `rootfs/` is the *floor*; `Dockerfile.variant` copies
+  `/opt/pi-extensions/skill/` (the pinned, manifest-recorded clone) over it at
+  build, so a normal build ships the fresh package copy and an old-ref/mirror
+  build still ships the snapshot. `mempalace` is snapshot-only (its consumer
+  skill has no public package home — the `mempalace-toolkit` repo ships a
+  *different* skill, `opencode-mempalace-bridge`). Provenance + refresh steps:
+  `rootfs/usr/local/share/pi-devbox/skills/VENDORED.md`.
+- **Smoke-test coverage** for the fallback skills: build-time presence of both
+  `SKILL.md`s and the `pi-extensions` helper, a check that the baked
+  `pi-extensions` skill matches the package copy when the clone carries it, and
+  runtime assertions that both are symlinked into `~/.agents/skills/`.
+
+---
+
+## v1.2.0 — 2026-06-22
+
+Minor release: **image-baked agent skills** — a new base mechanism that ships
+skills inside the image (independent of any mounted skillset repo) — plus the
+first such skill, `pi-devbox-environment`, and pi `0.79.9` → `0.79.10`
+(auto-resolved from npm `latest` at build).
+
+### Added
+
+- **Image-baked agent skills.** Skills under
+  `/usr/local/share/pi-devbox/skills/<name>/` are now symlinked into
+  `~/.agents/skills/` by `entrypoint-user.sh` on every start, making them
+  available **with or without** a mounted `skillset` repo. The symlink points
+  at the image path (so it survives volume recreate, unlike anything baked
+  under a home dir a named volume would shadow) and is created only when
+  absent, so a same-named skillset skill or user override is never clobbered.
+  The skillset deploy classifies these as foreign-links and its `--prune-stale`
+  pass leaves them untouched.
+- **`pi-devbox-environment` skill** (the first image-baked skill). Teaches
+  agents the container-shaped facts that are easy to get wrong: the
+  persistence/ephemerality tier model (what survives `down -v` / image
+  update), host + LAN SSH reachability and ControlMaster, split-horizon DNS
+  *mechanisms*, the interactive-vs-tool-shell alias gotcha (`dssh`/`dscp`/
+  `cat`→`bat` don't exist in the non-interactive bash tool), the tmux 0-index
+  constraint, uv-first Python, and pi-studio reachability. Deliberately
+  environment-agnostic — host OS, hostnames, internal domains, and nameservers
+  are discovered at runtime, never hardcoded.
+- **Proactive skill awareness via the global `AGENTS.md`.** `Dockerfile.variant`
+  appends a short, gated pointer (`pi-global-AGENTS.append.md`) onto
+  pi-toolkit's `pi-global-AGENTS.md` — the single global instruction slot pi
+  loads at startup — so containers load the `pi-devbox-environment` skill
+  proactively rather than only on description match. The pointer fires only
+  inside a pi-devbox container (checks for `/usr/local/lib/pi-devbox/`).
+  Build-time append is idempotent via a marker grep; runtime is unaffected
+  (the file is root-owned and re-symlinked by pi-toolkit each boot).
+- **Smoke-test coverage** for the new mechanism: build-time presence of the
+  baked skill + append snippet + the merged marker in `pi-global-AGENTS.md`,
+  and a runtime assertion that `~/.agents/skills/pi-devbox-environment` is
+  linked after the entrypoint runs.
+
+### Bumped: pi 0.79.9 → 0.79.10
+
+Resolved from npm `latest` at build (v1.1.7 shipped `0.79.9`). See the
+[pi changelog](https://github.com/earendil-works/pi/blob/main/CHANGELOG.md)
+for the upstream `0.79.10` notes.
+
+## v1.1.7 — 2026-06-21
+
+Patch release: pi `0.79.8` → `0.79.9` (auto-resolved at build), plus the
+`ssh-lan.conf` LAN-peer documentation that landed on `main` after v1.1.6.
+Companion refs are auto-resolved to SHAs at build as before.
+
+### Bumped: pi 0.79.8 → 0.79.9
+
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.9)):
+
+- **Chat-template thinking compatibility** — OpenAI-compatible custom
+  providers can map pi thinking levels into `chat_template_kwargs`, enabling
+  vLLM/Hugging Face chat-template models (e.g. DeepSeek) to use
+  provider-native thinking controls.
+- **GLM-5.2 provider improvements** — corrected Fireworks OpenAI-compatible
+  routing and OpenRouter `xhigh` thinking support, improving `/model`
+  behaviour and high-effort reasoning for GLM-5.2.
+- **Fixes** — same-directory session switches now reuse imported extension
+  modules (fresh instances + lifecycle events preserved); deep session
+  branches no longer take quadratic time to build context; Markdown
+  streaming code-fence rendering no longer flickers on partial closing
+  fences; fuzzy `edit` matches preserve untouched line blocks instead of
+  rewriting the whole file; `/model` hides Copilot models unavailable to the
+  account and ranks exact provider-prefixed matches first.
+
+### Docs: document `~/.config/devbox-shell/ssh-lan.conf` for naming LAN peers
+
+The host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf` is the
+intended place to add `ProxyJump host` overrides for **named** LAN peers (so
+`pi --ssh <peer>` / `dssh <peer>` route through the host), but it was only
+mentioned in `.env.example` and the `setup-lan-access.sh` header — never in the
+README. Added a "Naming LAN peers" subsection to the README troubleshooting
+block (plus a pointer from the SSH/ControlMaster section), and corrected the
+stale `setup-lan-access.sh` comment that suggested editing the read-only
+`~/.ssh/config` instead of `ssh-lan.conf`.
+
+## v1.1.6 — 2026-06-19
+
+Build provenance + reproducibility hardening, plus pi `0.79.7` → `0.79.8`
+(auto-resolved at build). Companion refs are auto-resolved to SHAs at build
+as before.
+
+### Bumped: pi 0.79.7 → 0.79.8
+
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.8)):
+
+- **Selective provider base entry points** — SDK users can pair
+  `@earendil-works/pi-ai/base` and `@earendil-works/pi-agent-core/base` with
+  explicit provider registration to keep bundled apps from including unused
+  provider transports.
+- **Mistral prompt caching** — Mistral sessions use provider-side prompt
+  caching keyed on the pi session ID, with cached-token usage/cost
+  accounting.
+- **Post-compaction token estimates** — compact results and compaction
+  events now include estimated post-compaction token counts.
+- **OpenRouter Fusion alias** — `openrouter/fusion` available as a built-in
+  OpenRouter model alias.
+
+### Added
+
+- **Self-describing images: OCI labels + on-disk build manifest.** The
+  variant build now records exactly which pi version and companion-repo
+  commits were baked into each image. Previously the SHAs resolved by CI
+  only ever reached the build log (which rotates), so a published tag was
+  not reconstructable after the fact — confirming what shipped meant
+  triangulating from `git`, `pi --version`, and extension source.
+  - OCI labels: `org.opencontainers.image.{version,revision,created}` plus
+    `se.jordbo.pi-devbox.{pi,pi-toolkit,pi-extensions,pi-fork,pi-obsmem,mempalace-toolkit,pi-studio}-*ref` —
+    inspect with `docker inspect`.
+  - `/etc/pi-devbox/build-manifest.json` written from **ground truth** (the
+    actual checked-out `HEAD` of each `/opt` clone + live `pi --version`),
+    not just the intended build-args, so it also exposes a clone that
+    silently resolved to the wrong ref. The provenance ARGs are declared
+    last so a changing `BUILD_DATE` never invalidates the expensive
+    install/clone layers.
+- **`scripts/check-base-hash.sh` — base-rebuild invariant guard.** Every
+  floating `ARG *_REF` consumed by `Dockerfile.base` must be folded into the
+  `base_tag` hash, or a ref-only change won't trigger a base rebuild (the
+  v1.1.2 mempalace-toolkit staleness footgun). The guard fails CI the moment
+  someone adds an `ARG *_REF` to `Dockerfile.base` without folding it in; it
+  runs in the `base-decide` job and locally. Smoke-test gained assertions for
+  the manifest (present, no `"unknown"` components) and the OCI labels.
+- **Overridable companion repo URLs.** The three gitea-hosted companions
+  (`pi-toolkit`, `pi-extensions`, `mempalace-toolkit`) gained `*_REPO`
+  build-args defaulting to their canonical `gitea.jordbo.se` origin —
+  matching the existing `PI_FORK_REPO` / `PI_OBSMEM_REPO` / `PI_STUDIO_REPO`
+  pattern. A relocated or forked build can now repoint a companion at a
+  mirror, another host, or a local path (`--build-arg PI_EXTENSIONS_REPO=...`)
+  without editing the Dockerfiles. Defaults are unchanged, so the canonical
+  CI build is byte-identical.
+
+### Changed
+
+- **`resolve-versions` now fails loud instead of falling back to a floating
+  branch.** Each pi-version / companion-ref lookup previously degraded to
+  `main`/`master` on a transient API/network failure (`|| echo "main"`),
+  silently shipping an unpinned ref that defeats both cache-busting and
+  reproducibility. Resolution now validates each result is a 40-hex commit
+  SHA (and pi a real semver) and aborts the release otherwise.
+
+## v1.1.5 — 2026-06-18
+
+Patch release: SSH ControlMaster read-only-socket fix + pi `0.79.6` → `0.79.7`
+(auto-resolved at build). The `pi-extensions` ref is auto-resolved to `main`
+HEAD at build, so the `ssh-controlmaster` fix below lands automatically.
+
+### Fixed
+
+- **`pi --ssh <host>` no longer fails with "Read-only file system" when the
+  user's `~/.ssh/config` sets a per-host `ControlPath` under the read-only
+  `~/.ssh` mount** (e.g. the common CGNAT idiom `ControlPath ~/.ssh/cm/%r@%h:%p`).
+  Root cause: SSH precedence means a user's per-host `ControlPath` always wins
+  over the baked `/etc/ssh/ssh_config.d` default, so the master socket tried to
+  bind under the RO `~/.ssh` and `ssh … pwd` exited 255 ("Could not resolve
+  remote pwd"). The `ssh-controlmaster` extension (pulled from `pi-extensions`
+  `main` via `PI_EXTENSIONS_REF`) now (a) resolves the remote pwd with a direct
+  connection (`-o ControlPath=none -o ControlMaster=no`), and (b) tests whether
+  the system `ControlPath` dir is actually writable — falling back to its own
+  `/tmp` master (whose command-line `-o ControlPath` overrides the user's path)
+  when it is not. OS-agnostic and independent of whether the user uses
+  ControlMaster, so the majority of configs (no ControlMaster at all) are
+  unaffected.
+
+### Changed
+
+- **`setup-lan-access.sh` now renders the writable SSH sidecar
+  (`~/.ssh-local/config`) on every host OS, not just VM-backed ones.**
+  Previously the whole script no-oped on native Linux, so a Linux host that
+  also bind-mounts `~/.ssh` read-only got no `ControlPath` redirect. The
+  `ControlPath` redirect + `Include ~/.ssh/config` (and `dssh`/`dscp` usability)
+  now work on Linux too; only the host-jump block (`Host host mac`), its key
+  generation, and the authorize hints remain gated on VM-backed detection
+  (`DEVBOX_LAN_ACCESS=auto`) or `=jump`.
+
+### Bumped: pi 0.79.6 → 0.79.7
+
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.7)):
+
+- **Automatic theme mode** — `/settings` can choose separate light and dark
+  themes and follow terminal color-scheme changes (`/` is now reserved in
+  theme names for this).
+- **Self-only `pi update` by default** — bare `pi update` updates pi only;
+  `pi update --all` updates pi and packages together.
+- **Extension API helpers** — `CONFIG_DIR_NAME` exported so extensions resolve
+  project config paths without hardcoding `.pi`; edit-diff helpers
+  (`generateDiffString`, `generateUnifiedPatch`, `EditDiffResult`) exported.
+- **Warp inline images** via Kitty graphics capability detection.
+- Fixes: RPC unknown-command errors now include the request id (clients no
+  longer hang); `/model` autocomplete matches provider/model regardless of
+  token order; tree navigator horizontally pans deep entries.
+
+## v1.1.4 — 2026-06-17
+
+Patch release: config and shell-quality fixes on a preserved volume. No pi
+version bump (still `0.79.6`, latest). The `pi-toolkit` ref is auto-resolved
+to `main` HEAD at build, so the AGENTS.md change below lands automatically.
+
+### Added
+
+- **Global `AGENTS.md` auto-loads the pi-extensions skill.** `pi-toolkit` now
+  ships `pi-global-AGENTS.md` and symlinks it to `~/.pi/agent/AGENTS.md` (pi's
+  global-instructions file, loaded at every start). It directs the agent to
+  read the `pi-extensions` skill at session start and carries a core
+  fork/recall cheat-sheet, since on-demand skill description-matching was
+  leaving `pi-fork` / `pi-observational-memory` under-utilised. **Heads-up:**
+  on a preserved volume any pre-existing real `~/.pi/agent/AGENTS.md` is backed
+  up to `*.bak.<timestamp>` and replaced by the symlink (same behavior as
+  `keybindings.json`).
+- **`settings.json` merge-on-recreate.** The bootstrap only ever copied the
+  template when `settings.json` was *absent*, so a file on a preserved volume
+  never picked up config added in a later image (e.g. the
+  `observational-memory` / `pi-fork` blocks, a newly-enabled model). The
+  entrypoint now deep-merges the template into an existing `settings.json` on
+  start with `jq -s '.[0] * .[1]'` (template first, live second): the user's
+  values always win and only *missing* keys are filled in. Arrays are treated
+  as leaves (a model the user removed is not re-added); the file is only
+  rewritten when the merge changes something, the original is backed up first,
+  and invalid JSON on either side is skipped rather than clobbered. Opt out
+  with `PI_SETTINGS_MERGE=0`.
+
+### Fixed
+
+- **bash history loss in nested / tmux shells.** The `DEVBOX_HIST_SET` guard
+  that installs the per-prompt `history -a` flush was `export`ed, so it leaked
+  into child processes. Any nested shell — crucially each tmux pane, which
+  inherits the tmux server's env — saw the guard already set and skipped
+  installing `history -a`, persisting history only on a clean exit. Abrupt
+  termination (`docker stop`, `tmux kill-server`, SIGKILL) then silently lost
+  that shell's in-memory history. The guard is now shell-local (no `export`),
+  so every new interactive shell re-installs its own flush. `zoxide` was less
+  affected (its hook is unguarded and writes immediately). History and zoxide
+  storage were never the issue — `~/.cache/bash` (`devbox-shell-history`) and
+  `~/.local/share/zoxide` (`devbox-zoxide`) are persistent named volumes.
+  **Note:** existing shells/panes keep the old behavior until restarted
+  (`tmux kill-server` or open fresh shells).
+
+### Maintainer
+
+- `scripts/recreate-sanity-check.sh` gained assertions for the new wiring: the
+  `~/.pi/agent/AGENTS.md` symlink, a nested login shell installing
+  `history -a`, and `settings.json` carrying the `observational-memory` +
+  `pi-fork` blocks after recreate.
+
+---
+
+## v1.1.3 — 2026-06-16
+
+Patch release: pi `0.79.4` → `0.79.5` (auto-resolved at build).
+
+### Bumped: pi 0.79.4 → 0.79.5
+
+Notable upstream changes (from [pi releases](https://github.com/earendil-works/pi/releases/tag/v0.79.5)):
+
+- **Provider-scoped API key environments** — `auth.json` API key entries can
+  now include `env` overrides for provider-specific Cloudflare, Azure OpenAI,
+  Google Vertex, Amazon Bedrock, cache retention, and proxy settings without
+  changing the project shell.
+- **Global HTTP proxy setting** — configure `httpProxy` once in global settings
+  to apply `HTTP_PROXY` / `HTTPS_PROXY` to Pi-managed HTTP clients.
+- **Vercel AI Gateway attribution** — requests now include Pi attribution
+  headers by default.
+- **Fixes:** inherited OpenAI Responses streaming tolerates null message content
+  before tool calls; DeepSeek V4 thinking no longer sends both `thinking` and
+  `reasoning_effort`; device-code login no longer auto-opens the browser;
+  various Google/Vertex Gemini model metadata corrections; session selector
+  empty-state fix; Cursor Up history navigation fix.
+
+---
+
 ## v1.1.2 — 2026-06-15
 
 Patch release: pi `0.79.3` → `0.79.4` (auto-resolved at build), plus the
@@ -278,7 +1101,7 @@ dependencies.
 ### Future work
 
 - v1.1.0: `:latest-studio` variant (adds [pi-studio](https://github.com/omaclaren/pi-studio)).
-- v1.2.0: `:latest-studio-tex` variant (adds texlive-xetex for PDF export).
+- v1.3.0: `:latest-studio-tex` variant (adds texlive-xetex for PDF export).
 
 ## v0.79.0 — 2026-06-08
 

DOCKER_HUB.md

@@ -51,6 +51,7 @@ Full setup guide — authentication for each provider (Anthropic, OpenAI, Gemini
 - **[pi-extensions](https://gitea.jordbo.se/joakimp/pi-extensions)** — 7 user-facing extensions: `ext-toggle`, `mcp-loader`, `todo`, `ssh-controlmaster`, `notify`, `git-checkpoint`, `confirm-destructive`
 - **`fork`** ([pi-fork](https://github.com/elpapi42/pi-fork)) and **`recall`** ([pi-observational-memory](https://github.com/elpapi42/pi-observational-memory)) tools
 - **mempalace bridge** — MCP extension auto-symlinked so pi reads/writes the host-mounted palace
+- **image-baked agent skills** — skills under `/usr/local/share/pi-devbox/skills/` (e.g. `pi-devbox-environment`, which teaches agents the container's persistence/networking/DNS/tmux/REPL specifics) are symlinked into `~/.agents/skills/` on start, available with or without a mounted skillset repo
 
 The entrypoint deploys/registers all of these on first container start. Re-running is idempotent and preserves user edits.
 
@@ -97,7 +98,7 @@ The entrypoint deploys/registers all of these on first container start. Re-runni
 
 ### SSH and networking
 
-- OpenSSH client with **ControlMaster auto** preconfigured on a writable socket path (`/tmp/sshcm/`). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps).
+- OpenSSH client with **ControlMaster auto** preconfigured on a writable socket path (`/tmp/sshcm/`). Mitigates ssh banner-exchange failures behind CGNAT-restricted residential ISPs (~4-flow caps). A read-only `~/.ssh` carrying a per-host `ControlPath` (common CGNAT configs) is handled too — redirected to a writable socket dir for both `pi --ssh` and `dssh`/`dscp`.
 - A **LAN-access helper** that auto-configures ssh jump-via-host on VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container can reach the host's directly-attached LAN peers (`dssh <peer>` alias; `DEVBOX_LAN_ACCESS` / `HOST_SSH_USER`).
 
 ## Versioning
@@ -155,4 +156,5 @@ Optional volumes for MemPalace (commented out by default — uncomment in `docke
 
 ## License
 
-MIT (the image; pi and the bundled tools each carry their own licenses).
+MIT (the image; pi and the bundled tools each carry their own licenses). See
+`LICENSE` and `THIRD_PARTY.md` in the [source repo](https://gitea.jordbo.se/joakimp/pi-devbox).

Dockerfile.base

@@ -14,7 +14,7 @@
 # content-addressed over this file, so any byte change invalidates the
 # cache. Recommended cadence: once per release for security updates.
 #
-# BASE_REBUILD_DATE: 2026-06-09 (v1.0.0 — decoupled from opencode-devbox)
+# BASE_REBUILD_DATE: 2026-07-13 (Unreleased — agent-browser CLI + Playwright Chromium for headless browser automation; prior: typst PDF engine + xz-utils + pandoc typst-template default-font patch)
 #
 # ── Lineage note ─────────────────────────────────────────────────────
 # Adapted from opencode-devbox/Dockerfile.base (commit before v1.16.2).
@@ -46,16 +46,43 @@ ENV DEBIAN_FRONTEND=noninteractive
 # Additions vs the upstream opencode-devbox base (2026-06-09):
 #   pandoc       — Markdown↔HTML/PDF/etc. conversion. Required by pi-studio
 #                  preview/export pipelines and broadly useful for any
-#                  agent-driven document workflow. ~200 MB.
+#                  agent-driven document workflow. ~200 MB. NOTE: pandoc is
+#                  only the front-end — PDF output needs a back-end engine.
+#                  We ship `typst` (installed further down) as the
+#                  lightweight default engine (`pandoc --pdf-engine=typst`)
+#                  instead of a ~600 MB TeX Live install.
+#   xz-utils     — `xz` decompressor. tar shells out to it for `.tar.xz`
+#                  assets (typst ships .tar.xz). ~0.5 MB. Also generally
+#                  useful for extracting xz-compressed archives.
 #   graphviz     — `dot` rendering for many diagram tools. ~10 MB.
 #                  See the bundled `dot-watch` helper for live .dot -> PNG
 #                  re-render (handy with pi-studio's image preview).
 #   imagemagick  — image conversion / resizing for thumbnails, etc. ~50 MB.
-#   yq           — YAML-aware companion to jq.
+#   (yq is NOT apt-installed: Debian's `yq` is the unrelated Python tool;
+#    mikefarah's Go yq is installed as a pinned binary further down.)
 #   socat        — TCP relay. Powers `studio-expose`, which bridges
 #                  pi-studio's container-loopback server to the container's
 #                  external interface so a published port can reach it.
 #                  ~1 MB; generally useful for any port-forwarding need.
+#   nano         — small, non-modal terminal editor for users who don't want
+#                  a vi-based editor. ~2.8 MB installed; its deps (libc6,
+#                  libncursesw6, libtinfo6) are already pulled in by nvim/less/
+#                  htop/tmux, so it adds no extra packages. Companion to nvim
+#                  and the `micro` binary installed further down. EDITOR stays
+#                  nvim; users opt in via `export EDITOR=nano`.
+#   kitty-terminfo — terminfo entry for the kitty terminal (TERM=xterm-kitty).
+#                  ~77 KB, terminfo file only (no kitty binary). Without it,
+#                  ncurses apps fall back and Neovim can't reliably detect
+#                  true-colour from kitty over ssh; installing it makes
+#                  TERM=xterm-kitty understood. Pairs with the system-wide
+#                  Neovim termguicolors default (etc/xdg/nvim/sysinit.vim).
+#   ncurses-term   — broad terminfo bundle (wezterm, alacritty, foot, st, the
+#                  base `ghostty` entry, and many more) so SSHing in from a
+#                  modern emulator resolves its TERM instead of degrading to a
+#                  dumb fallback. xterm-kitty is NOT in it (hence kitty-terminfo
+#                  above); TERM=xterm-ghostty is compiled from an alias further
+#                  down (ncurses ships `ghostty`, not `xterm-ghostty`). iTerm2
+#                  defaults to xterm-256color (ncurses-base), so needs nothing.
 RUN apt-get update && \
     apt-get upgrade -y --no-install-recommends && \
     apt-get install -y --no-install-recommends \
@@ -66,7 +93,6 @@ RUN apt-get update && \
     openssh-client \
     gnupg \
     jq \
-    yq \
     ripgrep \
     fd-find \
     tree \
@@ -89,9 +115,13 @@ RUN apt-get update && \
     python3-pip \
     python3-venv \
     pandoc \
+    xz-utils \
     graphviz \
     imagemagick \
     socat \
+    nano \
+    kitty-terminfo \
+    ncurses-term \
     && ln -s /usr/bin/fdfind /usr/local/bin/fd \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
@@ -130,6 +160,15 @@ RUN printf '%s\n' \
 # `Include /etc/ssh/ssh_config.d/*.conf` *before* the `Host *` block,
 # so user config can override these defaults if desired.
 #
+# CAVEAT (and why it is handled elsewhere): a user per-host override that
+# points ControlPath BACK under the read-only ~/.ssh (e.g. the common CGNAT
+# idiom `ControlPath ~/.ssh/cm/%r@%h:%p`) re-introduces the unwritable-socket
+# failure — a system drop-in here can never override a user's per-host value.
+# For `pi --ssh`, the ssh-controlmaster extension handles this by detecting an
+# unwritable system ControlPath and falling back to its own /tmp master; for
+# `ssh -F ~/.ssh-local/config` (dssh/dscp), setup-lan-access.sh redirects
+# ControlPath into the writable ~/.ssh-local. See CHANGELOG "Unreleased".
+#
 # ControlPersist=10m means the master socket sticks around 10 min after
 # the last session closes, so consecutive ssh calls in a workflow reuse
 # the same TCP flow. Companion entrypoint-user.sh creates /tmp/sshcm
@@ -222,6 +261,33 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "arm64" ;
     ln -s /opt/nvim-linux-${ARCH}/bin/nvim /usr/local/bin/nvim && \
     nvim --version | head -1
 
+# micro — modern, non-modal terminal editor. Ships alongside nvim so users
+# who aren't comfortable with vi-style modal editing have a friendly option:
+# desktop-style keybindings (Ctrl+S save, Ctrl+Q quit, Ctrl+C/V/X, Ctrl+Z
+# undo), mouse support, and syntax highlighting out of the box. A single
+# static Go binary (~12 MB) installed from GitHub releases, exactly like
+# bat/eza/zoxide below. EDITOR stays nvim (see below); users opt in with
+# `export EDITOR=micro` or `git config --global core.editor micro`.
+#
+# NOTE: upstream moved zyedidia/micro -> micro-editor/micro. The old org URL
+# still 302s, but its /releases/latest redirect lands on ANOTHER /latest URL
+# (the org rename), so the tag-parsing idiom below would resolve "latest"
+# instead of a version. Use the canonical micro-editor/micro URL.
+# Arch asset naming differs from the others: amd64 -> linux64, arm64 ->
+# linux-arm64. The tarball extracts to micro-<version>/micro.
+ARG MICRO_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "linux64" ;; arm64) echo "linux-arm64" ;; *) echo "linux64" ;; esac) && \
+    V="${MICRO_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/micro-editor/micro/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && [ -n "$V" ] && \
+    echo "Installing micro ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/micro-editor/micro/releases/download/v${V}/micro-${V}-${ARCH}.tar.gz" | tar -xz -C /tmp && \
+    install /tmp/micro-${V}/micro /usr/local/bin/micro && \
+    rm -rf /tmp/micro-${V} && \
+    micro --version
+
 # bat
 ARG BAT_VERSION=latest
 RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
@@ -280,21 +346,34 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
 # Always installed in the base. Set INSTALL_MEMPALACE=false at base-build
 # time to shave ~300 MB.
 #
-# Stall protection (fixed 2026-06-13): mempalace-mcp is launched by the
-# `mempalace.ts` pi extension from mempalace-toolkit (cloned below). That
-# extension now applies a per-REQUEST timeout in its JSON-RPC client and
-# kills the child on stall, so a virtiofs cold-open of chroma.sqlite3 /
-# HNSW load can no longer hang the pi TUI uninterruptibly. Tunables:
+# Stall protection (fixed 2026-06-13; self-heal added 2026-06-25):
+# mempalace-mcp is launched by the `mempalace.ts` pi extension from
+# mempalace-toolkit (cloned below). That extension applies a per-REQUEST
+# timeout in its JSON-RPC client and kills the child on stall, so a virtiofs
+# cold-open of chroma.sqlite3 / HNSW load can no longer hang the pi TUI
+# uninterruptibly. A stall-kill is no longer a permanent latch either: the
+# next tool call respawns the server with capped exponential backoff (the
+# budget resets on any successful response). Tunables:
 # MEMPALACE_MCP_TIMEOUT_MS (default 60000), MEMPALACE_MCP_INIT_TIMEOUT_MS
-# (default 120000); 0 disables. A standalone stdio-watchdog shim is NOT
-# needed — the extension already owns request/response correlation. See
-# CHANGELOG.md "Unreleased > Fixed".
+# (default 300000 — generous so a genuine first cold-open isn't killed),
+# MEMPALACE_MCP_MAX_RESPAWNS (default 2; 0 disables self-heal),
+# MEMPALACE_MCP_RESPAWN_BACKOFF_MS (default 1000); timeouts of 0 disable.
+# Defaults live in the extension, so no ENV is needed here. A standalone
+# stdio-watchdog shim is NOT needed — the extension already owns
+# request/response correlation. See CHANGELOG.md "Unreleased > Fixed".
 ARG INSTALL_MEMPALACE=true
 # Pin to a known-good version. Bump deliberately, not implicitly: an
 # unpinned install silently swept in mempalace 3.3.x/3.4.0 with a broken
-# diary_write schema (see workaround RUN below + issue #1728). Pinning
-# makes mempalace upgrades a reviewable diff rather than a surprise.
-ARG MEMPALACE_VERSION=3.4.0
+# diary_write schema. Pinning makes mempalace upgrades a reviewable diff
+# rather than a surprise.
+#
+# 3.5.0 (2026-06) ships the upstream fix for the top-level-anyOf diary_write
+# schema (issue #1728 / PR #1717, merged 2026-06-14): the advertised schema
+# is now `"required": ["agent_name"]` with entry/content enforced at dispatch,
+# which Anthropic's tools API accepts — so the old mcp_server.py perl
+# workaround that used to live below is gone. Keep in lockstep with
+# opencode-devbox when bumping.
+ARG MEMPALACE_VERSION=3.5.0
 ENV UV_TOOL_DIR=/opt/uv-tools
 ENV UV_TOOL_BIN_DIR=/usr/local/bin
 RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
@@ -303,45 +382,18 @@ RUN if [ "${INSTALL_MEMPALACE}" = "true" ]; then \
       /opt/uv-tools/mempalace/bin/python -c "import mempalace; print('mempalace', mempalace.__version__ if hasattr(mempalace, '__version__') else 'installed')" ; \
     fi
 
-# ── workaround: strip top-level anyOf from mempalace_diary_write schema ──
-# Mempalace 3.3.x/3.4.0 advertise diary_write's input_schema with a
-# top-level `anyOf: [{required:[entry]}, {required:[content]}]` to express
-# "either entry or content must be supplied". Anthropic's tools API rejects
-# top-level anyOf/oneOf/allOf, so pi/Claude fail at session start with
-# `tools.<n>.custom.input_schema: input_schema does not support oneOf,
-# allOf, or anyOf at the top level`.
-#
-# Patch the advertised schema to require ["agent_name", "entry"] and remove
-# the anyOf block. The handler keeps accepting `content` server-side as a
-# kwarg alias so existing callers still work.
-#
-# Idempotent and self-deactivating: once upstream releases the fix the
-# 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/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 opencode-devbox when bumping.
-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 && \
-      perl -0777 -i -pe 's/(?:[ \t]*\#[^\n]*\n)*[ \t]*"required":\s*\[\s*"agent_name"\s*\]\s*,\s*\n[ \t]*"anyOf":\s*\[\s*\n[ \t]*\{\s*"required":\s*\[\s*"entry"\s*\]\s*\}\s*,\s*\n[ \t]*\{\s*"required":\s*\[\s*"content"\s*\]\s*\}\s*,?\s*\n[ \t]*\]\s*,\s*\n/            "required": ["agent_name", "entry"],\n/s' "$MP_FILE" && \
-      if grep -q '"required": \["agent_name", "entry"\]' "$MP_FILE"; then \
-        echo "mempalace diary_write anyOf workaround: applied (or already clean)"; \
-      else \
-        echo "WARN: mempalace diary_write anyOf workaround did not match expected schema — upstream may have changed shape" >&2; \
-      fi ; \
-    fi
+# (The mempalace diary_write top-level-anyOf workaround that patched
+# mcp_server.py here was removed in v1.2.2 — fixed upstream in mempalace
+# 3.5.0 via issue #1728 / PR #1717 (merged 2026-06-14). See CHANGELOG.md.)
 
 # ── mempalace-toolkit — bash wrappers for session/docs mining ────────
 ARG INSTALL_MEMPALACE_TOOLKIT=true
 ARG MEMPALACE_TOOLKIT_REF=main
+# MEMPALACE_TOOLKIT_REPO defaults to the canonical gitea origin but is
+# overridable so a relocated/forked build can clone from a mirror or a
+# different host without editing this Dockerfile (mirrors the
+# PI_FORK_REPO / PI_OBSMEM_REPO / PI_STUDIO_REPO pattern in the variant).
+ARG MEMPALACE_TOOLKIT_REPO=https://gitea.jordbo.se/joakimp/mempalace-toolkit.git
 # 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
@@ -351,7 +403,7 @@ ARG MEMPALACE_TOOLKIT_REF=main
 RUN if [ "${INSTALL_MEMPALACE}" = "true" ] && [ "${INSTALL_MEMPALACE_TOOLKIT}" = "true" ]; then \
       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 && \
+      git -C /opt/mempalace-toolkit remote add origin "${MEMPALACE_TOOLKIT_REPO}" && \
       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; \
@@ -392,6 +444,11 @@ ENV LANG=en_US.UTF-8
 ENV LANGUAGE=en_US:en
 ENV LC_ALL=en_US.UTF-8
 ENV EDITOR=nvim
+# Advertise 24-bit colour so colour-aware tools (Neovim's own auto-detect, bat,
+# delta, ...) use true colour instead of a 256-colour fallback. Safe for the
+# modern terminals this devbox targets; override by exporting `COLORTERM=`
+# (empty) from a terminal that lacks true-colour support.
+ENV COLORTERM=truecolor
 ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"
 
 # ── Node.js (required for pi + MCP servers + tldr) ──
@@ -400,6 +457,58 @@ RUN curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors https://deb.nodesour
     apt-get install -y --no-install-recommends nodejs && \
     rm -rf /var/lib/apt/lists/*
 
+# ── agent-browser — headless browser automation for the agent ────────
+# Gives the agent a real browser it can drive (open/click/fill/eval/
+# screenshot) so front-end work involving live DOM or WebGL can be VERIFIED
+# rather than guessed at. The `agent-browser` skill (shipped from the
+# skillset repo, not this image) documents the CLI; without this block that
+# skill is a no-op because the binary isn't present. Verified end-to-end
+# 2026-07-13: drives the baked Chromium headless (open + screenshot + eval
+# into a WebGL SPA) — doctor's launch test passes in ~0.5s.
+#
+# TWO pieces, because agent-browser is a standalone Rust CLI that ships NO
+# browser of its own — it only drives one you provide:
+#   1. the CLI itself (npm; ~70 MB of prebuilt native binaries), and
+#   2. a Chromium, which we fetch via Playwright.
+#
+# Why Playwright fetches the browser (and NOT `agent-browser install`):
+# agent-browser's own installer drops Chrome under ~/.agent-browser/browsers
+# — inside /home/${USER_NAME}, which is a NAMED VOLUME at runtime, so a
+# build-time download would be SHADOWED (invisible) once the volume mounts.
+# Playwright honours PLAYWRIGHT_BROWSERS_PATH, so we place the browser under
+# /usr/local/share (never shadowed) and hand agent-browser a STABLE symlink
+# via AGENT_BROWSER_EXECUTABLE_PATH — the symlink insulates the ENV from
+# Playwright's per-version, per-ARCH browser directory (`chrome-linux` on arm64,
+# `chrome-linux64` on amd64 — Chrome-for-Testing), so we `find` the `chrome`
+# binary rather than hardcode the path; the headless-shell binary is named
+# `chrome-headless-shell`, so `-name chrome` skips it.
+#
+# `playwright install --with-deps chromium` also apt-installs Chromium's
+# runtime libs; verified to resolve correctly on Debian trixie (exit 0 — the
+# t64 library renames are handled by Playwright's dep list). Build runs as
+# root, so the apt step works. NPM_CONFIG_PREFIX=/usr keeps both CLIs on /usr
+# so they survive the ~/.pi/npm-global volume mount (same trick the variant
+# uses for pi). After fetching, we DROP Playwright's `chromium_headless_shell-*`
+# build — agent-browser drives the full chrome (verified, incl. headless), so the
+# headless shell is dead weight — and clean the apt/npm caches, trimming the
+# layer to ~625 MB (Chromium) from ~960 MB. Still the bulk of the base's size,
+# and the one real tradeoff of shipping this to every variant.
+ARG AGENT_BROWSER_VERSION=latest
+ARG PLAYWRIGHT_VERSION=latest
+ENV PLAYWRIGHT_BROWSERS_PATH=/usr/local/share/ms-playwright
+RUN NPM_CONFIG_PREFIX=/usr npm install -g \
+      "agent-browser@${AGENT_BROWSER_VERSION}" \
+      "playwright@${PLAYWRIGHT_VERSION}" && \
+    playwright install --with-deps chromium && \
+    CHROME="$(find "${PLAYWRIGHT_BROWSERS_PATH}" -type f -name chrome -path '*/chromium-*/*' | head -n1)" && \
+    [ -n "$CHROME" ] && ln -sf "$CHROME" /usr/local/bin/agent-chrome && \
+    agent-browser --version && \
+    test -x "$(readlink -f /usr/local/bin/agent-chrome)" && \
+    rm -rf "${PLAYWRIGHT_BROWSERS_PATH}"/chromium_headless_shell-* && \
+    npm cache clean --force && \
+    rm -rf /var/lib/apt/lists/* /root/.npm /tmp/*
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/local/bin/agent-chrome
+
 # ── tldr (tealdeer) — community-maintained command examples ──────────
 # Tealdeer is a Rust port of the tldr-pages client; ~5 MB static binary,
 # ~135 MB smaller than the Node tldr global. Same `tldr` command, same UX.
@@ -415,6 +524,61 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
     chmod +x /usr/local/bin/tldr && \
     tldr --version
 
+# ── typst — lightweight PDF engine for pandoc (Markdown→PDF) ─────────
+# pandoc (apt-installed above) is only a front-end; rendering PDF needs a
+# back-end engine. Rather than a ~600 MB TeX Live install, we ship typst:
+# a single ~30 MB static Rust binary with no LaTeX dependency. pi-studio's
+# PDF export (studio_export_pdf) and pandoc invocations use it via
+# `pandoc --pdf-engine=typst`. A fuller TeX Live remains the higher-
+# fidelity fallback for anyone who needs LaTeX-exact output (not shipped
+# here — install on demand or in a future variant).
+#
+# Follows the `latest` GitHub-release convention (like tealdeer/uv/bat).
+# typst ships a `.tar.xz` asset (hence xz-utils in the apt layer above)
+# that extracts to typst-<arch>-unknown-linux-musl/typst. Pin a specific
+# tag with --build-arg TYPST_VERSION=vX.Y.Z.
+#
+# We also patch pandoc's bundled typst template
+# (/usr/share/pandoc/data/templates/template.typst): its conf() defaults the
+# document font to an empty tuple (`font: ()`), so a naked
+# `pandoc --pdf-engine=typst` fails with "font fallback list must not be empty"
+# unless the caller passes `-V mainfont=...`. We default it to Libertinus Serif
+# (typst's own bundled default font) so PDF export works out-of-the-box.
+ARG TYPST_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64" ;; *) echo "x86_64" ;; esac) && \
+    V="${TYPST_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/typst/typst/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    V="${V#v}" && [ -n "$V" ] && \
+    echo "Installing typst ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/typst/typst/releases/download/v${V}/typst-${ARCH}-unknown-linux-musl.tar.xz" | tar -xJ -C /tmp && \
+    install /tmp/typst-${ARCH}-unknown-linux-musl/typst /usr/local/bin/typst && \
+    rm -rf /tmp/typst-${ARCH}-unknown-linux-musl && \
+    typst --version && \
+    sed -i 's/^  font: (),$/  font: ("Libertinus Serif",),/' /usr/share/pandoc/data/templates/template.typst && \
+    grep -q 'font: ("Libertinus Serif",),' /usr/share/pandoc/data/templates/template.typst
+
+# ── yq (mikefarah) — YAML processor, jq's companion for YAML ─────────
+# Installed as the mikefarah Go binary — NOT Debian's `yq` apt package, which
+# is the unrelated Python kislyuk/yq (a jq wrapper with different syntax and
+# version line, e.g. 3.x). The cloud-init repo's deploy.sh/provision.sh
+# require mikefarah yq v4 (the unrelated Debian python yq is v3.x). Follows
+# the repo's `latest` convention (like tealdeer/uv/etc.); the smoke test pins
+# the contract to major v4, so a future yq v5 fails CI instead of silently
+# breaking provision.sh. Pin a specific tag with --build-arg YQ_VERSION=vX.Y.Z.
+ARG YQ_VERSION=latest
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    V="${YQ_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/mikefarah/yq/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    [ -n "$V" ] && \
+    echo "Installing mikefarah yq ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/mikefarah/yq/releases/download/${V}/yq_linux_${ARCH}" -o /usr/local/bin/yq && \
+    chmod +x /usr/local/bin/yq && \
+    yq --version
+
 # ── AWS CLI v2 (for SSO/Bedrock authentication) ─────────────────────
 RUN ARCH=$(case "${TARGETARCH}" in \
       amd64) echo "x86_64" ;; \
@@ -464,16 +628,41 @@ ENV PATH="/home/${USER_NAME}/.pi/npm-global/bin:${PATH}"
 RUN mkdir -p /etc/skel-devbox
 COPY rootfs/home/developer/.bash_aliases     /etc/skel-devbox/.bash_aliases
 COPY rootfs/home/developer/.inputrc          /etc/skel-devbox/.inputrc
+COPY rootfs/home/developer/.gitignore_global /etc/skel-devbox/.gitignore_global
+
+# ── Editor defaults: system-wide Neovim true-colour ──────────────────
+# /etc/xdg/nvim/sysinit.vim is Neovim's system vimrc: it loads for every user
+# (before any personal ~/.config/nvim) and can still be overridden per-user.
+# Enables termguicolors so the default theme renders in 24-bit colour instead
+# of a muddy 256-colour fallback. Pairs with kitty-terminfo (installed above).
+COPY rootfs/etc/xdg/nvim/sysinit.vim /etc/xdg/nvim/sysinit.vim
+
+# ── Terminal support: xterm-ghostty terminfo alias ──────────────────
+# ncurses-term (installed above) covers wezterm/alacritty/foot/st and the base
+# `ghostty` entry, but Ghostty connects with TERM=xterm-ghostty, for which no
+# distro packages an entry. Ship a thin alias (use=ghostty) and compile it into
+# the system terminfo db with `tic -x`, so it inherits the maintained ghostty
+# capability set. The `infocmp` check fails the build if the entry didn't land.
+COPY rootfs/usr/local/share/terminfo-src/ghostty.terminfo /usr/local/share/terminfo-src/ghostty.terminfo
+RUN tic -x -o /usr/share/terminfo /usr/local/share/terminfo-src/ghostty.terminfo && \
+    infocmp -x xterm-ghostty >/dev/null
 
 # ── Entrypoint ────────────────────────────────────────────────────────
 COPY rootfs/usr/local/lib/pi-devbox/ /usr/local/lib/pi-devbox/
+# Image-baked skills + the global-AGENTS append snippet. Under /usr/local so a
+# named volume over a home dir can't shadow them; linked into ~/.agents/skills
+# by entrypoint-user.sh, and the snippet is concatenated onto the global
+# AGENTS.md in Dockerfile.variant (after pi-toolkit, which owns that file).
+COPY rootfs/usr/local/share/pi-devbox/ /usr/local/share/pi-devbox/
 COPY rootfs/usr/local/bin/studio-expose /usr/local/bin/studio-expose
 COPY rootfs/usr/local/bin/dot-watch /usr/local/bin/dot-watch
+COPY rootfs/usr/local/bin/pi-devbox-version /usr/local/bin/pi-devbox-version
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 COPY entrypoint-user.sh /usr/local/bin/entrypoint-user.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh /usr/local/bin/entrypoint-user.sh \
     /usr/local/bin/studio-expose \
     /usr/local/bin/dot-watch \
+    /usr/local/bin/pi-devbox-version \
     /usr/local/lib/pi-devbox/*.sh 2>/dev/null || true
 
 # Start as root — entrypoint adjusts UID/GID then drops to developer

Dockerfile.variant

@@ -41,6 +41,12 @@ ARG USER_NAME=developer
 ARG PI_VERSION=latest
 ARG PI_TOOLKIT_REF=main
 ARG PI_EXTENSIONS_REF=main
+# Repo URLs default to the canonical gitea origin but are overridable so a
+# relocated/forked build can clone from a mirror or a different host
+# without editing this Dockerfile — same pattern as PI_FORK_REPO /
+# PI_OBSMEM_REPO / PI_STUDIO_REPO below.
+ARG PI_TOOLKIT_REPO=https://gitea.jordbo.se/joakimp/pi-toolkit.git
+ARG PI_EXTENSIONS_REPO=https://gitea.jordbo.se/joakimp/pi-extensions.git
 # pi-fork (fork tool) + pi-observational-memory (recall tool) live on GitHub
 # under elpapi42. CI resolves these to commit SHAs to defeat the same
 # cache-hit footgun that affects PI_VERSION.
@@ -77,8 +83,8 @@ RUN set -e && \
       NPM_CONFIG_PREFIX=/usr npm install -g @earendil-works/pi-coding-agent@${PI_VERSION} ; \
     fi && \
     pi --version && \
-    git_fetch_ref   "https://gitea.jordbo.se/joakimp/pi-toolkit.git"    "${PI_TOOLKIT_REF}"    /opt/pi-toolkit && \
-    git_fetch_ref   "https://gitea.jordbo.se/joakimp/pi-extensions.git" "${PI_EXTENSIONS_REF}" /opt/pi-extensions && \
+    git_fetch_ref   "${PI_TOOLKIT_REPO}"    "${PI_TOOLKIT_REF}"    /opt/pi-toolkit && \
+    git_fetch_ref   "${PI_EXTENSIONS_REPO}" "${PI_EXTENSIONS_REF}" /opt/pi-extensions && \
     git_fetch_ref   "${PI_FORK_REPO}"   "${PI_FORK_REF}"   /opt/pi-fork && \
     git_fetch_ref   "${PI_OBSMEM_REPO}" "${PI_OBSMEM_REF}" /opt/pi-observational-memory && \
     (cd /opt/pi-fork && npm install --omit=dev --no-audit --no-fund) && \
@@ -88,6 +94,46 @@ RUN set -e && \
     echo "pi-fork at $(cd /opt/pi-fork && git rev-parse --short HEAD)" && \
     echo "pi-observational-memory at $(cd /opt/pi-observational-memory && git rev-parse --short HEAD)"
 
+# ── Image-baked skill refresh: pi-extensions (Option 1 over Option 2) ──
+# rootfs ships a VENDORED snapshot of the pi-extensions skill at
+# /usr/local/share/pi-devbox/skills/pi-extensions/ (the "floor" — guarantees the
+# skill is always in the image). The pi-extensions PACKAGE repo now co-locates
+# the canonical skill under skill/, so here — after the pinned clone — we copy
+# that over the snapshot. Result: a normal build ships the fresh, package-owned
+# copy (pinned + recorded in the manifest via PI_EXTENSIONS_REF); a build whose
+# ref predates the skill, or a fork pointing at a mirror without it, still ships
+# the committed snapshot. The skill calls ./evaluate-extension-usage.py, so it
+# is copied alongside. Idempotent and cache-safe (depends only on the clone).
+RUN if [ -f /opt/pi-extensions/skill/SKILL.md ]; then \
+      cp /opt/pi-extensions/skill/SKILL.md \
+         /usr/local/share/pi-devbox/skills/pi-extensions/SKILL.md && \
+      if [ -f /opt/pi-extensions/skill/evaluate-extension-usage.py ]; then \
+        cp /opt/pi-extensions/skill/evaluate-extension-usage.py \
+           /usr/local/share/pi-devbox/skills/pi-extensions/evaluate-extension-usage.py ; \
+      fi && \
+      echo "refreshed pi-extensions skill from package @ $(cd /opt/pi-extensions && git rev-parse --short HEAD)" ; \
+    else \
+      echo "pi-extensions package has no skill/ at this ref — keeping vendored snapshot" ; \
+    fi
+
+# ── pi-devbox awareness: append our pointer to the global AGENTS.md ──
+# pi loads a SINGLE global instruction file (~/.pi/agent/AGENTS.md), which
+# pi-toolkit's install.sh re-symlinks to /opt/pi-toolkit/pi-global-AGENTS.md on
+# every container start. There is no second global slot, and that file is
+# root-owned (not writable by the runtime user), so we compose at BUILD time:
+# append the pi-devbox managed block to pi-toolkit's file here, after the clone.
+# Idempotent via a marker grep so a rebuilt layer never double-appends. This
+# makes every container proactively aware of the pi-devbox-environment skill;
+# the snippet itself is gated (only fires when /usr/local/lib/pi-devbox exists).
+RUN if [ -f /opt/pi-toolkit/pi-global-AGENTS.md ] && \
+       ! grep -q 'pi-devbox:managed-block' /opt/pi-toolkit/pi-global-AGENTS.md; then \
+      printf '\n' >> /opt/pi-toolkit/pi-global-AGENTS.md && \
+      cat /usr/local/share/pi-devbox/pi-global-AGENTS.append.md >> /opt/pi-toolkit/pi-global-AGENTS.md && \
+      echo "appended pi-devbox block to pi-global-AGENTS.md" ; \
+    else \
+      echo "pi-devbox block already present or pi-global-AGENTS.md missing (skipped)" ; \
+    fi
+
 # ── Optional: pi-studio (:latest-studio variant) ─────────────────────
 # pi-studio (omaclaren/pi-studio) is a pi-package + theme providing a
 # two-pane browser workspace: prompt/response editor, KaTeX/Mermaid live
@@ -112,6 +158,10 @@ RUN set -e && \
 ARG INSTALL_STUDIO=false
 ARG PI_STUDIO_REPO=https://github.com/omaclaren/pi-studio.git
 ARG PI_STUDIO_REF=main
+# PI_STUDIO_VERSION is the human-readable tag (e.g. v0.9.36) that PI_STUDIO_REF
+# was resolved from; recorded as a label below for at-a-glance identification.
+# Only meaningful for the studio variant (default `none` otherwise).
+ARG PI_STUDIO_VERSION=none
 RUN if [ "${INSTALL_STUDIO}" = "true" ]; then \
       set -e; \
       rm -rf /opt/pi-studio && mkdir -p /opt/pi-studio && \
@@ -154,4 +204,61 @@ RUN if [ "${INSTALL_GO}" = "true" ]; then \
       ln -s /usr/local/go/bin/gofmt /usr/local/bin/gofmt; \
     fi
 
+# ── Build provenance: OCI labels + on-disk build manifest ────────────
+# Records exactly which pi version and companion-repo commits were baked
+# into THIS image, so a published tag is self-describing and reproducible
+# after the fact (CI logs rotate; a released image must not depend on
+# them). Previously the resolved SHAs only ever reached the CI build log.
+#
+# These ARGs are declared LAST, immediately before the layer that uses
+# them, so a changing BUILD_DATE / RELEASE_TAG / SOURCE_REVISION never
+# invalidates the expensive pi-install / clone layers above.
+ARG RELEASE_TAG=dev
+ARG BUILD_DATE=
+ARG SOURCE_REVISION=
+# MEMPALACE_TOOLKIT_REF is consumed in Dockerfile.base; re-declared here
+# only so its intended ref lands in the label set alongside the others.
+ARG MEMPALACE_TOOLKIT_REF=main
+
+LABEL org.opencontainers.image.version="${RELEASE_TAG}" \
+      org.opencontainers.image.revision="${SOURCE_REVISION}" \
+      org.opencontainers.image.created="${BUILD_DATE}" \
+      se.jordbo.pi-devbox.pi-version="${PI_VERSION}" \
+      se.jordbo.pi-devbox.pi-toolkit-ref="${PI_TOOLKIT_REF}" \
+      se.jordbo.pi-devbox.pi-extensions-ref="${PI_EXTENSIONS_REF}" \
+      se.jordbo.pi-devbox.pi-fork-ref="${PI_FORK_REF}" \
+      se.jordbo.pi-devbox.pi-obsmem-ref="${PI_OBSMEM_REF}" \
+      se.jordbo.pi-devbox.mempalace-toolkit-ref="${MEMPALACE_TOOLKIT_REF}" \
+      se.jordbo.pi-devbox.pi-studio-ref="${PI_STUDIO_REF}" \
+      se.jordbo.pi-devbox.pi-studio-version="${PI_STUDIO_VERSION}"
+
+# The manifest is written from GROUND TRUTH — the actual checked-out HEAD
+# of each /opt clone and the live `pi --version` — not merely the intended
+# build-args. That way it also exposes a clone that silently resolved to
+# something other than the requested ref. pi-studio is present only in the
+# studio variant (JSON null otherwise).
+RUN set -e; \
+    mkdir -p /etc/pi-devbox; \
+    rev() { git -C "$1" rev-parse HEAD 2>/dev/null || echo "unknown"; }; \
+    PI_V="$(pi --version 2>/dev/null | head -n1 | tr -d '\r\n')"; \
+    STUDIO_REV='null'; \
+    if [ -d /opt/pi-studio/.git ]; then STUDIO_REV="\"$(rev /opt/pi-studio)\""; fi; \
+    { \
+      echo '{'; \
+      echo "  \"release_tag\": \"${RELEASE_TAG}\","; \
+      echo "  \"build_date\": \"${BUILD_DATE}\","; \
+      echo "  \"source_revision\": \"${SOURCE_REVISION}\","; \
+      echo "  \"pi_version\": \"${PI_V}\","; \
+      echo "  \"components\": {"; \
+      echo "    \"pi-toolkit\": \"$(rev /opt/pi-toolkit)\","; \
+      echo "    \"pi-extensions\": \"$(rev /opt/pi-extensions)\","; \
+      echo "    \"pi-fork\": \"$(rev /opt/pi-fork)\","; \
+      echo "    \"pi-observational-memory\": \"$(rev /opt/pi-observational-memory)\","; \
+      echo "    \"mempalace-toolkit\": \"$(rev /opt/mempalace-toolkit)\","; \
+      echo "    \"pi-studio\": ${STUDIO_REV}"; \
+      echo "  }"; \
+      echo '}'; \
+    } > /etc/pi-devbox/build-manifest.json; \
+    echo "── build manifest ──"; cat /etc/pi-devbox/build-manifest.json
+
 # WORKDIR / ENTRYPOINT / CMD inherited from base.

IDEAS.md

@@ -0,0 +1,60 @@
+# Ideas & backlog
+
+A living list of potential improvements for pi-devbox that are **not yet
+scheduled**. This is intentionally lightweight — a place to park ideas so they
+aren't lost between sessions. When an item ships, describe it in
+[`CHANGELOG.md`](CHANGELOG.md) and remove it from here.
+
+Rough effort tags: 🟢 small · 🟡 medium · 🔴 large. Status: `idea` (unvetted) ·
+`planned` (agreed, not started).
+
+---
+
+## Supply-chain hardening
+
+- 🟡 `planned` — **Pin CI actions to commit SHAs.** The workflows use floating
+  major tags (`actions/checkout@v4`, `docker/build-push-action@v7`,
+  `docker/setup-buildx-action@v4`, `docker/login-action@v3`,
+  `docker/setup-qemu-action@v3`). This is inconsistent with the project's own
+  philosophy of SHA-pinning *content* refs (pi, pi-studio, pi-fork, …) to defeat
+  floating refs. Pin each action to a SHA with a trailing `# vX.Y.Z` comment.
+  Pairs naturally with the renovate item below to keep the pins fresh.
+
+- 🟡 `planned` — **Vulnerability scanning in CI.** No CVE scan runs on the
+  published images today. Add a `trivy image` (or grype) job to
+  `docker-publish.yml` after `smoke`. Start non-blocking (report only), then
+  tighten to fail on `HIGH`/`CRITICAL` with an available fix.
+
+- 🟢🟡 `planned` — **Standardize build provenance → buildx SBOM + attestations.**
+  The image already carries hand-rolled provenance (OCI labels +
+  `build-manifest`). `docker/build-push-action` can emit a standard SBOM and
+  SLSA provenance attestation nearly for free (`provenance: mode=max`,
+  `sbom: true`). Makes provenance machine-consumable and pairs well with the
+  trivy item (scan the SBOM).
+
+## Dockerfile hardening
+
+- 🟡 `idea` — **Address hadolint DL4006 properly.** Currently ignored in
+  `.hadolint.yaml`. The clean fix is `SHELL ["/bin/bash", "-o", "pipefail",
+  "-c"]` so piped `RUN`s fail on the first non-zero stage. This changes the
+  default `RUN` shell from `sh` to `bash` for all subsequent layers, so it is
+  base-affecting and needs a careful pass over existing `RUN`s before removing
+  the ignore.
+
+## Developer experience
+
+- 🟢 `idea` — **`Makefile`/`justfile` for local iteration.** Reproducing a CI
+  build locally means hand-assembling many `--build-arg`s. Thin targets
+  (`make build-base`, `make build-variant`, `make smoke`, `make lint`) would
+  make local testing painless and document the canonical invocations.
+
+- 🟡 `idea` — **Dependency-update automation (renovate).** With CI actions
+  SHA-pinned (above), a `renovate.json` keeps those pins — plus the pinned tool
+  versions (`ACTIONLINT_VERSION`, `HADOLINT_VERSION`, gosu, etc.) — current via
+  automated PRs. Requires a renovate runner against the Gitea instance.
+
+## Housekeeping
+
+- 🟢 `idea` — **Registry retention for `base-<hash>` tags.** The base-hash
+  caching scheme accumulates `base-<hash>` tags over time. Confirm whether the
+  registry prunes old ones, and add a retention/cleanup step if not.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joakim Persson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -29,13 +29,18 @@ on the host.
 - ChromaDB embedding model pre-warmed at build time (`all-MiniLM-L6-v2`)
 
 The host-mounted palace at `~/.mempalace` is shared across the host and
-this container so all your agents share one brain.
+this container so all your agents share one brain. To instead share a palace
+across *several* containers/harnesses, set `MEMPALACE_REMOTE_URL` to a shared
+MemPalace HTTP endpoint (see `.env.example` and `docker-compose.mempalace.yml`);
+the bridge then connects over HTTP and spawns no local server.
 
 ### Modern CLI tooling
 
 | Tool | Purpose |
 |---|---|
-| `nvim` | Neovim text editor |
+| `nvim` | Neovim text editor (modal / vi-style) |
+| `nano` | Small non-modal editor (on-screen shortcut hints) |
+| `micro` | Modern non-modal editor (Ctrl+S/Ctrl+Q keys, mouse, syntax highlighting) |
 | `tmux` | Terminal multiplexer (configured for 0-indexed sessions) |
 | `ripgrep`, `fd` | Fast file content / filename search |
 | `fzf` | Fuzzy finder |
@@ -49,6 +54,17 @@ this container so all your agents share one brain.
 | `gosu` | Privilege de-escalation in entrypoint |
 | `htop`, `tree`, `less` | Inspection utilities |
 
+The default `$EDITOR` is `nvim`. Three editors ship so you can pick your
+comfort level — if you'd rather not use a vi-style editor, `nano` and `micro`
+are both non-modal. Set your preference with `export EDITOR=micro` (or `nano`)
+in your shell profile, and/or `git config --global core.editor micro`.
+
+Neovim ships with a system-wide default (`/etc/xdg/nvim/sysinit.vim`) that turns
+on `termguicolors`, so its colours render in 24-bit instead of a muddy
+256-colour fallback over ssh/kitty. The `kitty-terminfo` entry is also bundled
+so `TERM=xterm-kitty` is understood. Override either in your own
+`~/.config/nvim`.
+
 ### Document and image tooling
 
 - `pandoc` — universal Markdown↔HTML/Org/RST/etc. converter
@@ -82,6 +98,9 @@ For Python REPLs and notebooks beyond the system interpreter, see the
 - A LAN-access helper that auto-configures ssh jump-via-host on
   VM-backed hosts (OrbStack / Docker Desktop on macOS) so the container
   can reach the host's directly-attached LAN peers.
+- Read-only `~/.ssh` is handled transparently: a per-host `ControlPath`
+  under it (common CGNAT configs like `~/.ssh/cm/...`) is redirected to a
+  writable socket dir for both `pi --ssh` and `dssh`/`dscp`.
 
 ## Quickstart
 
@@ -136,8 +155,10 @@ Currently published:
 
 Planned for an upcoming minor release:
 
-- `joakimp/pi-devbox:latest-studio-tex` — `-studio` plus `texlive-xetex`
-  for PDF export from Studio. Adds ~600 MB on top of `-studio`.
+- *(shipped in Unreleased/base)* **PDF export from Studio/pandoc** now works:
+  the base image ships **`typst`** as the PDF engine (`pandoc --pdf-engine=typst`),
+  a single ~30 MB static binary — no separate `-tex` variant needed.
+  `texlive-xetex` stays the higher-fidelity fallback (install on demand).
 
 ## Using pi-studio (`-studio` variant)
 
@@ -272,9 +293,30 @@ Assuming the compose file publishes `127.0.0.1:8765:8765` (see method B):
 > until step 2 runs. If the browser can't connect, verify Studio is up
 > (`/studio --status`) and the bridge is running (`ps aux | grep socat`).
 
-> PDF export (`/studio-pdf`, `studio_export_pdf`) needs a LaTeX engine,
-> which is **not** in `-studio` (only the planned `-studio-tex`). HTML
-> export, KaTeX, Mermaid, and all REPL features work without it.
+> PDF export (`/studio-pdf`, `studio_export_pdf`) uses **`typst`**, shipped in
+> the base image as the pandoc PDF engine (`pandoc --pdf-engine=typst`). For
+> LaTeX-exact output you can install `texlive-xetex` on demand as a heavier
+> fallback. HTML export, KaTeX, Mermaid, and all REPL features work regardless.
+
+### Generating a PDF with pandoc + typst
+
+The base ships `pandoc` (front-end) and `typst` (PDF engine), so Markdown → PDF
+works out of the box:
+
+```bash
+pandoc doc.md --pdf-engine=typst -o doc.pdf
+```
+
+The base patches pandoc's bundled typst template so it defaults to the
+**Libertinus Serif** font. Without that patch a naked `--pdf-engine=typst`
+fails with `error: font fallback list must not be empty`, because the upstream
+template leaves the font unset. To pick a different face, pass one of the fonts
+typst can see (`typst fonts` lists them — DejaVu Serif/Sans/Mono, Libertinus
+Serif, New Computer Modern):
+
+```bash
+pandoc doc.md --pdf-engine=typst -V mainfont="New Computer Modern" -o doc.pdf
+```
 
 ### Graphviz diagrams in Studio: `dot-watch`
 
@@ -316,9 +358,10 @@ services:
     environment:
       - TERM=xterm-256color
       # - STUDIO_EXPOSE=1          # -studio only: auto-start the socat bridge on boot
-      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
-      - GITEA_HOST=${GITEA_HOST:-}
-      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-}
+      # Secrets (GITEA_*, GITHUB_*, …) come from env_file: .env above — not
+      # duplicated here. An environment: entry overrides env_file and is
+      # interpolated from the host shell, so a stale shell export would
+      # silently shadow your .env. See .env.example for the full list.
     volumes:
       # Workspace: your host source tree
       - ${WORKSPACE_PATH:-.}:/workspace
@@ -439,6 +482,56 @@ session/docs mining; the 29 MCP tools (search, kg-query, drawer-add,
 diary-write, etc.) are wired into pi automatically by the pi-extensions
 mempalace bridge.
 
+## Agent skills
+
+pi discovers skills under `~/.agents/skills/`. Two delivery paths feed that
+directory, and they compose:
+
+- **Image-baked skills (always present).** Skills shipped *inside* the image
+  live under `/usr/local/share/pi-devbox/skills/` and are symlinked into
+  `~/.agents/skills/` by `entrypoint-user.sh` on every start. They need no
+  external mount, survive volume recreate (the source is an image path, not a
+  home dir a named volume would shadow), and are created only when absent so a
+  same-named skillset skill or user override is never clobbered. The bundled
+  **`pi-devbox-environment`** skill is delivered this way — it teaches agents
+  the container's persistence model, host/LAN SSH reachability, split-DNS
+  mechanisms, the interactive-vs-tool-shell alias gotcha (`dssh`/`dscp`),
+  tmux 0-indexing, uv-first Python, and pi-studio reachability, all as
+  *mechanisms* (deployment-specific hostnames/domains/nameservers are
+  discovered at runtime, never hardcoded).
+- **Vendored fallback skills.** The pi-toolkit global `AGENTS.md` tells every
+  pi session to read `~/.agents/skills/pi-extensions/SKILL.md` at start (to fix
+  fork/recall under-utilisation). That pointer would dangle in a container
+  started *without* the private `skillset` repo, so the image also bakes
+  fallback copies of **`pi-extensions`** and **`mempalace`**. They are
+  symlinked only when absent, so a mounted skillset always overrides them. The
+  `pi-extensions` skill is *layered*: a committed snapshot in `rootfs/` is the
+  floor, and `Dockerfile.variant` copies the canonical, package-owned copy from
+  the pinned `pi-extensions` clone (`/opt/pi-extensions/skill/`) over it at
+  build, so a normal build ships the fresh copy and an old-ref/mirror build
+  still ships the snapshot. `mempalace` is snapshot-only (its consumer skill
+  has no public package home), and because pi-toolkit's `AGENTS.md` has no
+  directive for it, the pi-devbox managed block adds a session-start
+  *proactive-load* pointer for it (gated to pi-devbox containers, conditional
+  on the MemPalace MCP tools) so a new container actually loads it. See
+  `rootfs/usr/local/share/pi-devbox/skills/VENDORED.md`.
+- **Skillset repo (optional).** If a `skillset` repo is mounted (at
+  `$HOME/skillset` or `/workspace/skillset`, or via `SKILLSET_CONTAINER_PATH`),
+  `deploy-skills.sh` symlinks its skills in too. Image-baked skills are
+  classified as foreign-links by its `--prune-stale` pass and left untouched.
+
+To make agents *proactively* load a baked skill at session start (rather than
+only on description match), the image appends a short, gated pointer to the
+global `AGENTS.md` at build time (see `pi-global-AGENTS.append.md`). The
+pointer fires only inside a pi-devbox container (it checks for
+`/usr/local/lib/pi-devbox/`).
+
+To add another image-baked skill: drop a `SKILL.md` under
+`rootfs/usr/local/share/pi-devbox/skills/<name>/`; the `COPY` in
+`Dockerfile.base` and the entrypoint symlink loop pick it up automatically. To
+refresh a vendored fallback, see
+`rootfs/usr/local/share/pi-devbox/skills/VENDORED.md`.
+
 ## SSH and ControlMaster
 
 The base image preconfigures `Host *` ssh defaults:
@@ -461,6 +554,27 @@ User-level overrides in `~/.ssh/config` win because Debian's
 `/etc/ssh/ssh_config` includes `/etc/ssh/ssh_config.d/*.conf` before
 the `Host *` block.
 
+### Per-host `ControlPath` on a read-only `~/.ssh`
+
+`~/.ssh` is usually bind-mounted read-only, so a user `~/.ssh/config` that
+points `ControlPath` back under it (e.g. the CGNAT idiom
+`ControlPath ~/.ssh/cm/%r@%h:%p`) can't bind its master socket here — and a
+system default can never override a user's per-host value. Two layers handle
+this without editing the read-only config:
+
+- **`pi --ssh <host>`** — the `ssh-controlmaster` extension detects an
+  unwritable system `ControlPath` and falls back to its own writable
+  `/tmp/pi-cm-<pid>.sock` master (its command-line `-o ControlPath` overrides
+  the user's path); the remote-`pwd` probe uses `-o ControlPath=none` so it
+  cannot fail on the read-only socket dir.
+- **`ssh -F ~/.ssh-local/config` / `dssh` / `dscp`** — `setup-lan-access.sh`
+  redirects `ControlPath` into the writable `~/.ssh-local/cm` for every host
+  (the sidecar is rendered on all host OSes). To name LAN peers that should
+  jump via the host, add `ProxyJump host` overrides in the host-owned
+  `~/.config/devbox-shell/ssh-lan.conf` (see
+  [Naming LAN peers](#naming-lan-peers)) rather than the read-only
+  `~/.ssh/config`.
+
 ## tmux and 0-indexed sessions
 
 The image installs `/etc/tmux.conf` with:
@@ -517,6 +631,96 @@ pi-coding-agent@latest` (the build-arg string would otherwise be
 byte-identical across releases and the layer would silently reuse the
 previous version's bytes).
 
+### Building a fork / relocated build
+
+The canonical build clones its companions from `gitea.jordbo.se`. Every
+companion repo URL is an overridable build-arg (defaulting to the canonical
+origin), so a fork or a build on a host that can't reach that gitea can
+repoint each one at a mirror, another host, or a local `file://` path
+**without editing the Dockerfiles**:
+
+| Build-arg | Default | Dockerfile |
+|---|---|---|
+| `PI_TOOLKIT_REPO` | `https://gitea.jordbo.se/joakimp/pi-toolkit.git` | variant |
+| `PI_EXTENSIONS_REPO` | `https://gitea.jordbo.se/joakimp/pi-extensions.git` | variant |
+| `MEMPALACE_TOOLKIT_REPO` | `https://gitea.jordbo.se/joakimp/mempalace-toolkit.git` | base |
+| `PI_FORK_REPO` | `https://github.com/elpapi42/pi-fork.git` | variant |
+| `PI_OBSMEM_REPO` | `https://github.com/elpapi42/pi-observational-memory.git` | variant |
+| `PI_STUDIO_REPO` | `https://github.com/omaclaren/pi-studio.git` | variant |
+
+Each has a matching `*_REF` arg (branch name or commit SHA). Example — build
+the variant against forked toolkit/extensions and a pinned pi:
+
+```bash
+# base first (mempalace-toolkit lives here)
+docker build -f Dockerfile.base -t myorg/pi-devbox:base-dev \
+  --build-arg MEMPALACE_TOOLKIT_REPO=https://github.com/myorg/mempalace-toolkit.git .
+
+# then the variant FROM that base
+docker build -f Dockerfile.variant -t myorg/pi-devbox:dev \
+  --build-arg BASE_IMAGE=myorg/pi-devbox:base-dev \
+  --build-arg PI_VERSION=0.79.7 \
+  --build-arg PI_TOOLKIT_REPO=https://github.com/myorg/pi-toolkit.git \
+  --build-arg PI_EXTENSIONS_REPO=https://github.com/myorg/pi-extensions.git .
+```
+
+Note: the gitea companions clone anonymously (no token needed); only the
+`resolve-versions` CI job calls the gitea *API* (which needs a token even
+for public repos). A plain `docker build` like the above skips that job
+entirely, so no credentials are required for a local/forked build.
+
+Provenance build-args (all optional; populate the OCI labels and
+`/etc/pi-devbox/build-manifest.json` — see below): `RELEASE_TAG`,
+`BUILD_DATE`, `SOURCE_REVISION`. CI sets these automatically; a manual build
+leaves them at harmless defaults.
+
+### Build provenance (labels + manifest)
+
+Every published image is self-describing. Inspect the OCI labels without
+pulling the filesystem:
+
+```bash
+docker inspect --format '{{json .Config.Labels}}' joakimp/pi-devbox:latest | jq .
+```
+
+`org.opencontainers.image.{version,revision,created}` plus
+`se.jordbo.pi-devbox.*-ref` record the intended pi version and companion
+refs. The on-disk `/etc/pi-devbox/build-manifest.json` records **ground
+truth** — the actual checked-out commit of each `/opt` clone and the live
+`pi --version` — so a tag is reconstructable after CI logs rotate:
+
+```bash
+docker run --rm --entrypoint= joakimp/pi-devbox:latest cat /etc/pi-devbox/build-manifest.json
+```
+
+Inside a running container, `pi-devbox-version` wraps that manifest into a
+human-readable summary — no need to remember the file path or pipe it
+through `jq` yourself:
+
+```console
+$ pi-devbox-version
+pi-devbox v1.5.0
+  built:  2026-07-13T17:53:16Z  (source d68674d11e06)
+  pi:     0.80.6
+  components:
+    pi-toolkit: 9a8f6faeaa08
+    pi-extensions: 61c98e004e3d
+    pi-fork: 4a09af4ef527
+    pi-observational-memory: 27a5195eaf90
+    mempalace-toolkit: 96699f2a1781
+    pi-studio: 2ef38ef31cea
+```
+
+It also flags **live drift** — if `pi --version` no longer matches what was
+baked at build time (e.g. something on a persisted volume shadowed the
+image's binary), the `pi:` line calls that out instead of silently trusting
+the manifest. `--json` dumps the raw manifest for scripting; `--quiet` gives
+a one-line `release_tag (source_revision)` form. It also prints once,
+automatically, at container start (from `entrypoint-user.sh`, before the
+rest of the setup output) — so you see which build you're in without
+asking. Exits 1 with a short notice on images built before this file
+existed, rather than failing silently.
+
 ## Troubleshooting
 
 ### Image grew unexpectedly
@@ -533,6 +737,28 @@ auto-runs on container start and writes `~/.ssh-local/config` with a
 ssh-jump-via-host configuration. Set `DEVBOX_LAN_ACCESS=jump` and
 `HOST_SSH_USER=<your-mac-user>` in `.env` if auto-detection fails.
 
+#### Naming LAN peers
+
+`DEVBOX_LAN_ACCESS` / `HOST_SSH_USER` only set up the *jump* to the host. To
+make a **named** peer route through it — so `pi --ssh alpserv-2`,
+`dssh alpserv-2`, etc. resolve the ProxyJump — add a `ProxyJump host` override
+for it in the host-owned, bind-mounted `~/.config/devbox-shell/ssh-lan.conf`
+(**not** `~/.ssh/config`, which is mounted read-only):
+
+```
+Host pve pve-2 alpserv-2 lagret
+    ProxyJump host
+```
+
+`HostName` / `User` / `IdentityFile` are inherited from the matching block in
+your real `~/.ssh/config` (first-value-wins, so only `ProxyJump` is taken from
+here). This file is `Include`d *before* `~/.ssh/config` and read fresh on every
+connection — newly added peers work immediately, no container or session
+restart needed — and the peer names stay out of the published image (they're a
+fact about your specific LAN, not the image). Alternatively, set
+`DEVBOX_LAN_AUTOJUMP_PRIVATE=1` to ProxyJump *any* RFC1918 address through the
+host without naming peers (see `.env.example`).
+
 ### Smoke-testing a local build
 
 ```bash
@@ -585,4 +811,7 @@ The pi coding-agent itself is [@earendil-works/pi-coding-agent](https://www.npmj
 
 ## License
 
-MIT
+MIT — see [`LICENSE`](LICENSE). This covers the repository's own contents
+(Dockerfiles, entrypoint scripts, `rootfs/` seeds, CI, docs). The published
+images bundle third-party software under their own licenses; see
+[`THIRD_PARTY.md`](THIRD_PARTY.md).

THIRD_PARTY.md

@@ -0,0 +1,46 @@
+# Third-party notices
+
+pi-devbox is distributed under the MIT License (see [`LICENSE`](LICENSE)), which
+covers **this repository's own contents** — the Dockerfiles, entrypoint scripts,
+`rootfs/` seeds, CI workflows, and docs.
+
+The **published container images** (`joakimp/pi-devbox:*`) additionally *bundle*
+third-party software, each of which remains under its own license. This file is
+a good-faith summary; the authoritative sources are the upstream projects and,
+for OS packages, the per-package copyright files inside the image at
+`/usr/share/doc/<package>/copyright`.
+
+## pi and its extensions (installed in the variant layer)
+
+| Component | Upstream | License |
+| --- | --- | --- |
+| pi (`@earendil-works/pi-coding-agent`) | npm | MIT |
+| pi-fork | github.com/elpapi42/pi-fork | MIT |
+| pi-observational-memory | github.com/elpapi42/pi-observational-memory | MIT |
+| pi-studio *(`-studio` variant only)* | github.com/omaclaren/pi-studio | MIT |
+| pi-toolkit, pi-extensions, mempalace-toolkit | authored by the maintainer (Joakim Persson) | MIT |
+
+## Tooling baked into the base image
+
+| Component | Upstream | License (best effort) |
+| --- | --- | --- |
+| gosu | github.com/tianon/gosu | Apache-2.0 |
+| Node.js | nodejs.org | MIT (bundles components under their own licenses) |
+| uv | github.com/astral-sh/uv | Apache-2.0 OR MIT |
+| Neovim | neovim.io | Apache-2.0 + Vim license |
+| Pandoc | pandoc.org | GPL-2.0-or-later |
+| Typst | github.com/typst/typst | Apache-2.0 |
+| ripgrep / fd / micro / tealdeer / yq (mikefarah) | respective repos | MIT / Apache-2.0 / Unlicense (varies) |
+
+## Base OS
+
+The image is built `FROM` a Debian base and installs packages via `apt`. Debian
+and its packages are distributed under their respective licenses (GPL, LGPL,
+MIT, BSD, and others). See each package's copyright file in the image under
+`/usr/share/doc/<package>/copyright`.
+
+---
+
+*Licenses marked "best effort" are widely known but were not each verified at
+the exact bundled version; consult the upstream project for authoritative
+terms. Corrections welcome.*

docker-compose.mempalace.yml

@@ -0,0 +1,84 @@
+# Shared MemPalace server (optional) — one palace for many clients.
+#
+# Runs `mempalace-mcp` over HTTP so several containers/harnesses (pi +
+# opencode + native) can share ONE palace instead of each keeping its own.
+# Point every client at it by setting, in that client's .env:
+#
+#   MEMPALACE_REMOTE_URL=http://<reachable-host>:8765/mcp
+#
+# (see .env.example). When set, the client connects over HTTP and does NOT
+# spawn its own local mempalace-mcp.
+#
+# Start:   docker compose -f docker-compose.mempalace.yml up -d
+# Stop:    docker compose -f docker-compose.mempalace.yml down
+# Logs:    docker compose -f docker-compose.mempalace.yml logs -f
+#
+# Why reuse the devbox image? mempalace-mcp is already installed in it, and
+# reusing it GUARANTEES the server's mempalace version matches the clients'
+# (both are pinned by the same image build). Override with a slimmer image via
+# MEMPALACE_SERVER_IMAGE if you prefer (it must provide `mempalace-mcp`).
+#
+# ⚠ SECURITY: mempalace-mcp's HTTP transport has NO authentication of its own.
+# Do NOT expose port 8765 to an untrusted network. The default below binds to
+# 127.0.0.1 (host loopback) only. To let sibling containers reach it, either
+# attach them to the shared `mempalace-net` network (container-to-container, no
+# host port needed — use http://mempalace-server:8765/mcp), or front it with a
+# reverse proxy that enforces MEMPALACE_REMOTE_TOKEN as `Authorization: Bearer`.
+
+name: mempalace-server
+
+services:
+  mempalace:
+    image: ${MEMPALACE_SERVER_IMAGE:-joakimp/pi-devbox:latest}
+    container_name: mempalace-server
+    # Bypass the devbox entrypoint (dev-shell/LAN/config setup) and run the
+    # HTTP MCP server directly. HOME + explicit --palace pin the data path so
+    # it does not depend on the image's default user/HOME. Runs as root so it
+    # can initialise the fresh named volume; the volume is dedicated to this
+    # server (clients reach it over HTTP, never by mounting it).
+    entrypoint: []
+    user: "0:0"
+    environment:
+      - HOME=/data
+    command:
+      - mempalace-mcp
+      - --transport
+      - http
+      - --host
+      - "0.0.0.0"
+      - --port
+      - "8765"
+      - --palace
+      - /data/.mempalace
+    restart: unless-stopped
+    # Loopback-only by default (see SECURITY note). Use "8765:8765" to expose on
+    # all host interfaces, or drop `ports:` entirely and rely on mempalace-net.
+    ports:
+      - "127.0.0.1:8765:8765"
+    volumes:
+      # The shared palace data — precious; back this up.
+      - mempalace-shared:/data/.mempalace
+      # Embedding-model cache (~79 MB, disposable) so search does not re-download.
+      - mempalace-shared-chroma:/data/.cache/chroma
+    networks:
+      - mempalace-net
+    healthcheck:
+      # A tools/list round-trip proves the server is answering MCP (python3 is
+      # always present — mempalace itself is a python tool in the image).
+      test:
+        - CMD
+        - python3
+        - -c
+        - "import urllib.request,json; d=json.dumps({'jsonrpc':'2.0','id':1,'method':'tools/list','params':{}}).encode(); r=urllib.request.Request('http://127.0.0.1:8765/mcp',data=d,headers={'Content-Type':'application/json','Accept':'application/json'}); urllib.request.urlopen(r,timeout=5).read()"
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s
+
+volumes:
+  mempalace-shared:
+  mempalace-shared-chroma:
+
+networks:
+  mempalace-net:
+    name: mempalace-net

docker-compose.yml

@@ -31,9 +31,13 @@ services:
       - .env
     environment:
       - TERM=xterm-256color
-      - GITEA_ACCESS_TOKEN=${GITEA_ACCESS_TOKEN:-}
-      - GITEA_HOST=${GITEA_HOST:-}
-      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN:-}
+      # Secrets (GITEA_*, GITHUB_*, and any others) are delivered to the
+      # container via `env_file: .env` above — do NOT duplicate them here.
+      # An `environment:` entry overrides env_file AND is interpolated from
+      # the host shell, so a stale shell export (e.g. one auto-loaded by a
+      # dotenv hook) would silently shadow the value in your .env. Keeping
+      # secrets env_file-only decouples the container from the host shell.
+      # See .env.example for the full list of supported variables.
     volumes:
       # Host workspace — mount your project here
       - ${WORKSPACE_PATH:-.}:/workspace
@@ -72,7 +76,10 @@ services:
       # Persist uv data (Python installs, tool installs)
       - devbox-uv:/home/developer/.local/share/uv
 
-      # Optional: persist MemPalace data (conversation memory, knowledge graph)
+      # Optional: persist MemPalace data (conversation memory, knowledge graph).
+      # Applies to the LOCAL palace only (the default). In EXTERNAL mode
+      # (MEMPALACE_REMOTE_URL set in .env) the shared server owns the data, so
+      # this volume is irrelevant.
       # - devbox-palace:/home/developer/.mempalace
 
       # Optional: persist ChromaDB embedding model cache (~79 MB)

entrypoint-user.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# ── Startup banner: which pi-devbox build is this? ─────────────────
+# Printed FIRST, before the setup noise below, so it's the first thing
+# visible when the container starts (CMD is `bash -l`, tty:true in compose,
+# so this reaches the same stream as the interactive shell the user lands
+# in). Reads the ground-truth manifest baked in Dockerfile.variant; a no-op
+# with a short stderr notice on images built before it existed.
+command -v pi-devbox-version >/dev/null 2>&1 && pi-devbox-version || true
+
 # ── SSH ControlMaster socket dir ────────────────────────────────
 # Companion to /etc/ssh/ssh_config.d/00-devbox-controlmaster.conf in the
 # base image — that file declares ControlPath=/tmp/sshcm/%r@%h:%p; this
@@ -12,12 +20,16 @@ set -euo pipefail
 mkdir -p /tmp/sshcm
 chmod 700 /tmp/sshcm
 
-# ── LAN access: generic host-OS-agnostic reachability helper ────────
-# On VM-backed hosts (macOS OrbStack / Docker Desktop) the container can't
-# reach the host's directly-attached LAN peers by default; this generates a
-# writable ~/.ssh-local/config that uses the host as an SSH jump. On native
-# Linux (LAN reachable directly) it is a no-op. Controlled by DEVBOX_LAN_ACCESS
-# (auto|jump|off) + HOST_SSH_USER. Always non-fatal. See the script header.
+# ── LAN access + writable SSH sidecar: host-OS-agnostic helper ──────
+# Generates the writable ~/.ssh-local/config on EVERY host OS: a `Host *`
+# ControlPath redirect into ~/.ssh-local/cm (so `ssh -F` / dssh / dscp work
+# even when ~/.ssh is bind-mounted read-only) plus `Include ~/.ssh/config`. On
+# VM-backed hosts (macOS OrbStack / Docker Desktop) it ALSO adds an
+# SSH-jump-via-host block so the container can reach the host's
+# directly-attached LAN peers; on native Linux (LAN reachable directly) the
+# jump block is omitted but the sidecar is still rendered. Controlled by
+# DEVBOX_LAN_ACCESS (auto|jump|off) + HOST_SSH_USER. Always non-fatal. See the
+# script header.
 if [ -r /usr/local/lib/pi-devbox/setup-lan-access.sh ]; then
   bash /usr/local/lib/pi-devbox/setup-lan-access.sh || true
 fi
@@ -29,13 +41,39 @@ fi
 # directly.
 SKEL_DIR="/etc/skel-devbox"
 if [ -d "$SKEL_DIR" ]; then
-  for f in .bash_aliases .inputrc; do
+  for f in .bash_aliases .inputrc .gitignore_global; do
     if [ -f "$SKEL_DIR/$f" ] && [ ! -e "$HOME/$f" ]; then
       cp "$SKEL_DIR/$f" "$HOME/$f"
     fi
   done
 fi
 
+# ── Image-baked skills: link into ~/.agents/skills ───────────────────
+# Skills shipped IN the image (under /usr/local/share/pi-devbox/skills/) are
+# made available regardless of whether a skillset repo is mounted. Done EARLY
+# — before the pi-toolkit/extensions deploy below — so the symlinks exist by
+# the time anything gates on "container ready": the smoke-test readiness probe
+# waits on pi-deploy markers (keybindings.json, mempalace.ts) that only land
+# AFTER this point, so linking here closes a sample-too-early race that failed
+# the runtime skill-link assertion. Pointing at the image path (/usr/local/...)
+# keeps the skill fresh from the image and surviving volume recreate (unlike
+# anything baked under a home dir, which a named volume would shadow). Created
+# only when absent, so a same-named skillset skill (deployed later, at the end
+# of this script) or a user override is never clobbered; the skillset deploy
+# classifies these as foreign-links and its --prune-stale pass leaves them
+# alone (only dangling symlinks are pruned).
+DEVBOX_SKILLS_SRC=/usr/local/share/pi-devbox/skills
+if [ -d "$DEVBOX_SKILLS_SRC" ]; then
+  mkdir -p "$HOME/.agents/skills"
+  for _sk in "$DEVBOX_SKILLS_SRC"/*/; do
+    [ -d "$_sk" ] || continue
+    _skname=$(basename "$_sk")
+    if [ ! -e "$HOME/.agents/skills/$_skname" ]; then
+      ln -s "${_sk%/}" "$HOME/.agents/skills/$_skname"
+    fi
+  done
+fi
+
 # ── MemPalace: initialize palace for the workspace if mempalace is installed
 # Creates the palace directory structure on first run. Idempotent — skips
 # if palace already exists, so upgrades from older versions preserve
@@ -61,6 +99,12 @@ fi
 if [ -n "${GIT_USER_EMAIL:-}" ] && ! git config --global user.email &>/dev/null; then
   git config --global user.email "$GIT_USER_EMAIL"
 fi
+# Global gitignore for personal/tooling artifacts (*.bak, *~, *.orig, ...).
+# Seeded above into $HOME/.gitignore_global from /etc/skel-devbox. Point git at
+# it only if the user has not already set their own core.excludesFile.
+if [ -f "$HOME/.gitignore_global" ] && ! git config --global core.excludesFile &>/dev/null; then
+  git config --global core.excludesFile "$HOME/.gitignore_global"
+fi
 
 # ── pi: deploy toolkit + extensions + mempalace bridge ─────────────
 # pi is always installed in pi-devbox; no INSTALL_PI guard needed.
@@ -86,9 +130,35 @@ if command -v pi &>/dev/null; then
 
   # Bootstrap settings.json from template if absent (pi rewrites this
   # file at runtime — lastChangelogVersion, etc — so we can't symlink it).
-  if [ ! -f "$HOME/.pi/agent/settings.json" ] && \
-     [ -f /opt/pi-toolkit/settings.example.json ]; then
-    cp /opt/pi-toolkit/settings.example.json "$HOME/.pi/agent/settings.json"
+  _pi_settings="$HOME/.pi/agent/settings.json"
+  _pi_template=/opt/pi-toolkit/settings.example.json
+  if [ ! -f "$_pi_settings" ] && [ -f "$_pi_template" ]; then
+    cp "$_pi_template" "$_pi_settings"
+    echo "pi settings.json bootstrapped from template"
+  elif [ -f "$_pi_settings" ] && [ -f "$_pi_template" ] && \
+       [ "${PI_SETTINGS_MERGE:-1}" != "0" ] && command -v jq >/dev/null 2>&1; then
+    # Non-destructive merge: a settings.json on a PRESERVED volume never
+    # otherwise sees new template keys (the bootstrap above only fires when
+    # the file is absent), so config added in an image upgrade — e.g. the
+    # observational-memory / pi-fork blocks or a newly-enabled model — never
+    # reaches existing users. Deep-merge with the template FIRST and the
+    # live file SECOND ('.[0] * .[1]') so the user's values always win and
+    # only keys MISSING from the live file are filled in from the template.
+    # Arrays are treated as leaves (the user's array is kept verbatim, so a
+    # model they deliberately removed is not re-added). Only rewrite when the
+    # merge actually changes something, and back up the original first.
+    # Set PI_SETTINGS_MERGE=0 to disable. Invalid JSON on either side → skip,
+    # never clobber.
+    if _pi_merged=$(jq -s '.[0] * .[1]' "$_pi_template" "$_pi_settings" 2>/dev/null); then
+      if [ -n "$_pi_merged" ] && \
+         ! printf '%s' "$_pi_merged" | jq -e --slurpfile cur "$_pi_settings" '. == $cur[0]' >/dev/null 2>&1; then
+        cp "$_pi_settings" "${_pi_settings}.bak.$(date +%Y%m%d-%H%M%S)"
+        printf '%s\n' "$_pi_merged" > "$_pi_settings"
+        echo "pi settings.json: merged new template keys from settings.example.json (backup saved)"
+      fi
+    else
+      echo "WARN: pi settings.json merge skipped (jq could not parse template or live file; left untouched)"
+    fi
   fi
 
   # pi↔mempalace MCP bridge — single extension symlink.

rootfs/etc/xdg/nvim/sysinit.vim

@@ -0,0 +1,18 @@
+" pi-devbox — system-wide Neovim defaults.
+"
+" This is Neovim's *system vimrc*: it loads for every user before any personal
+" ~/.config/nvim, and personal configs can still override it.
+"
+" Enable 24-bit ("true") colour. Without it, Neovim's default theme is squeezed
+" into a 256-colour palette where strings/comments become a muddy, low-contrast
+" dark colour — a common complaint over ssh/kitty where COLORTERM often isn't
+" propagated into the container. Modern terminals (kitty, WezTerm, iTerm2,
+" Alacritty, ...) all support true colour; the bundled kitty-terminfo also lets
+" Neovim auto-detect it, but forcing it here guarantees readable colour
+" regardless of how the terminal type / COLORTERM reach the container.
+"
+"   Opt out for a session:  :set notermguicolors
+"   Override permanently:   set your own value in ~/.config/nvim/init.lua
+if has('termguicolors')
+  set termguicolors
+endif

rootfs/home/developer/.bash_aliases

@@ -54,6 +54,38 @@ alias gs='git status'
 alias gd='git diff'
 alias gl='git log --oneline --graph --decorate -20'
 
+# ── Host SSH reachability check (once per container lifetime) ───────────────
+# Warns at first shell startup if the Mac host is not reachable via SSH.
+# Only runs inside a container, only if the jump key exists, and only once
+# per container lifetime (/tmp flag is cleared on recreate).
+_devbox_check_host_ssh() {
+  [ -f "/.dockerenv" ] || return 0
+  local ssh_cfg="$HOME/.ssh-local/config"
+  [ -f "$ssh_cfg" ] || return 0
+  local key_pub="$HOME/.ssh-local/devbox_jump_ed25519.pub"
+  [ -f "$key_pub" ] || return 0
+  local flag="/tmp/.devbox_host_ssh_ok"
+  [ -f "$flag" ] && return 0
+  if ssh -F "$ssh_cfg" \
+        -o BatchMode=yes \
+        -o ConnectTimeout=2 \
+        -o StrictHostKeyChecking=accept-new \
+        mac true 2>/dev/null; then
+    touch "$flag"
+    return 0
+  fi
+  local pub_key
+  pub_key=$(cat "$key_pub")
+  printf '\n\033[1;33m⚠  devbox: Mac host not reachable via SSH\033[0m\n'
+  printf '   Some tools use SSH to run commands on the Mac host.\n'
+  printf '   Fix (run both on the Mac):\n\n'
+  printf '   \033[1mStep 1\033[0m  System Settings → General → Sharing → Remote Login → ON\n\n'
+  printf '   \033[1mStep 2\033[0m  echo '"'"'%s'"'"' >> ~/.ssh/authorized_keys\n' "$pub_key"
+  printf '\n   Then open a new shell in the container to verify.\n\n'
+}
+_devbox_check_host_ssh
+unset -f _devbox_check_host_ssh
+
 # ── LAN access via the host (dssh) ───────────────────────────────────
 # When running on a VM-backed host (macOS OrbStack / Docker Desktop), the
 # entrypoint's setup-lan-access.sh generates ~/.ssh-local/config so the host
@@ -89,9 +121,16 @@ fi
 # we append with a newline separator to avoid the ';;' parse error
 # described at the top of this file. Guarded so repeated sourcing
 # (e.g. `exec bash`) doesn't stack duplicates.
+#
+# The guard MUST stay shell-local (NOT exported): if it leaks into child
+# processes, every nested shell -- crucially each tmux pane, which inherits
+# the tmux server's env -- skips installing `history -a` and only persists
+# history on a clean exit. Abrupt termination (docker stop, tmux kill-server,
+# SIGKILL) then loses that shell's in-memory history. Keeping it unexported
+# means each new interactive shell re-installs its own per-prompt flush.
 if [ -z "${DEVBOX_HIST_SET:-}" ]; then
   PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a"
-  export DEVBOX_HIST_SET=1
+  DEVBOX_HIST_SET=1
 fi
 
 # ── Prompt: show [opencode-devbox] tag so it's obvious you're in the container

rootfs/home/developer/.gitignore_global

@@ -0,0 +1,14 @@
+# Global gitignore — personal/tooling artifacts (applies to all repos in the container)
+# Seeded into $HOME/.gitignore_global by entrypoint-user.sh and wired via
+# `git config --global core.excludesFile`. Edit freely; it is yours after first boot.
+
+# backup / editor / merge artifacts
+*.bak
+*.bak.*
+*~
+*.orig
+*.swp
+*.tmp
+
+# AI/LLM tool local settings — machine-specific perms + credentials, never commit
+**/.claude/settings.local.json

rootfs/usr/local/bin/pi-devbox-version

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# pi-devbox-version — show which pi-devbox image build is running.
+#
+# WHY THIS EXISTS
+#   The image bakes ground-truth build info into /etc/pi-devbox/build-manifest.json
+#   at `docker build` time (see Dockerfile.variant): the release tag, build date,
+#   source commit, live `pi --version` at build time, and the actual checked-out
+#   commit of every /opt component clone. That answers "what image am I running?"
+#   — but only if you know to go look for the file. This wraps it into one
+#   command, prints it human-first at container start (see entrypoint-user.sh),
+#   and stays available on demand for the rest of the session.
+#
+# USAGE
+#   pi-devbox-version           human-readable summary (default)
+#   pi-devbox-version --json    raw manifest JSON (for scripting)
+#   pi-devbox-version --quiet   one-line "release_tag (source_revision)" form
+#
+# EXIT STATUS
+#   0 on success. 1 if the manifest is missing (e.g. an image built before
+#   this file existed, or a non-pi-devbox base) — prints a short notice
+#   to stderr rather than failing silently.
+
+set -euo pipefail
+
+MANIFEST=/etc/pi-devbox/build-manifest.json
+MODE="human"
+
+case "${1:-}" in
+  --json)  MODE="json" ;;
+  --quiet|-q) MODE="quiet" ;;
+  --help|-h)
+    sed -n '2,20p' "$0" | sed 's/^# \?//'
+    exit 0
+    ;;
+esac
+
+if [ ! -f "$MANIFEST" ]; then
+  echo "pi-devbox-version: no build manifest at $MANIFEST" >&2
+  echo "  (image predates the manifest, or this isn't a pi-devbox image)" >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "pi-devbox-version: jq not found; dumping raw manifest instead" >&2
+  cat "$MANIFEST"
+  exit 0
+fi
+
+if [ "$MODE" = "json" ]; then
+  cat "$MANIFEST"
+  exit 0
+fi
+
+release_tag=$(jq -r '.release_tag' "$MANIFEST")
+build_date=$(jq -r '.build_date' "$MANIFEST")
+source_rev=$(jq -r '.source_revision' "$MANIFEST")
+pi_version_baked=$(jq -r '.pi_version' "$MANIFEST")
+
+if [ "$MODE" = "quiet" ]; then
+  printf '%s (%s)\n' "$release_tag" "${source_rev:0:7}"
+  exit 0
+fi
+
+# Live drift check: has `pi` been upgraded since this container was built?
+# (image is immutable, but a volume-persisted ~/.pi could in theory shadow
+# the baked binary — this stays honest rather than trusting the manifest
+# blindly, same "ground truth over intent" spirit as how the manifest
+# itself is generated in Dockerfile.variant.)
+pi_version_live=""
+if command -v pi >/dev/null 2>&1; then
+  pi_version_live=$(pi --version 2>/dev/null | head -n1 | tr -d '\r\n')
+fi
+
+printf 'pi-devbox %s\n' "$release_tag"
+printf '  built:  %s  (source %s)\n' "$build_date" "${source_rev:0:12}"
+if [ -n "$pi_version_live" ] && [ "$pi_version_live" != "$pi_version_baked" ]; then
+  printf '  pi:     %s  \033[33m(baked as %s — drift detected)\033[0m\n' "$pi_version_live" "$pi_version_baked"
+else
+  printf '  pi:     %s\n' "${pi_version_live:-$pi_version_baked}"
+fi
+
+printf '  components:\n'
+jq -r '.components | to_entries[] | select(.value != null) | "    \(.key): \(.value[0:12])"' "$MANIFEST"

rootfs/usr/local/lib/pi-devbox/setup-lan-access.sh

@@ -14,7 +14,9 @@
 #   The one thing reachable from a container on every OS is the host itself
 #   (host.docker.internal). So on VM-backed hosts we generate a writable SSH
 #   config that reaches the host and lets the user ProxyJump onward to LAN
-#   peers the host can reach. On native Linux we do nothing.
+#   peers the host can reach. On native Linux we render the same writable
+#   config (for the ControlPath redirect + Include ~/.ssh/config) but emit no
+#   jump block, since LAN peers are reachable directly there.
 #
 #   We ship the MECHANISM (a generic `host` jump alias + writable config),
 #   never the POLICY: the user's specific target hosts live in their own
@@ -30,7 +32,9 @@
 #
 # CONTROLS (env)
 #   DEVBOX_LAN_ACCESS = auto (default) | jump | off
-#       auto  → set up the jump config only on VM-backed hosts; no-op on Linux.
+#       auto  → set up the host jump only on VM-backed hosts. The writable
+#               sidecar config (ControlPath redirect + Include) is always
+#               rendered, on every OS.
 #       jump  → always set up (e.g. native Linux with extra_hosts host-gateway).
 #       off   → do nothing.
 #   HOST_SSH_USER  — the username to SSH into the host as. REQUIRED for the
@@ -84,41 +88,71 @@ is_vm_backed() {
   getent hosts "$HOST_ALIAS_HOSTNAME" >/dev/null 2>&1
 }
 
-if [ "$MODE" = "auto" ] && ! is_vm_backed; then
-  # Native Linux host: LAN peers are reachable directly. Nothing to do.
-  exit 0
-fi
-
-# From here: MODE=jump, or MODE=auto on a VM-backed host.
-
-command -v ssh-keygen >/dev/null 2>&1 || exit 0
-
+# ── Writable socket dir + sidecar (ALWAYS, every host OS) ─────────────
+# The ControlPath redirect in the generated config needs a writable directory
+# regardless of host OS or jump mode. ~/.ssh is typically read-only, so the
+# master socket lives under the writable ~/.ssh-local. We create it and render
+# the config UNCONDITIONALLY so the redirect (and `Include ~/.ssh/config`) works
+# even on native Linux — where we set up no host jump but a read-only ~/.ssh
+# would otherwise still break ControlMaster sockets.
 mkdir -p "${SSH_LOCAL}/cm" 2>/dev/null || true
 chmod 700 "${SSH_LOCAL}" "${SSH_LOCAL}/cm" 2>/dev/null || true
 
-# ── Jump key (generated once; preserved across restarts) ──────────────
+# ── Decide whether to set up the host jump ────────────────────────────
+# Jump = reach the container host (host.docker.internal) as an SSH ProxyJump
+# onward to the host's LAN peers. Needed on VM-backed hosts (macOS / Docker
+# Desktop) or when forced with DEVBOX_LAN_ACCESS=jump. On native Linux LAN
+# peers are reachable directly, so NEED_JUMP=0 and we emit no jump block — but
+# we still render the config for the ControlPath redirect + Include.
+NEED_JUMP=0
+if [ "$MODE" = "jump" ] || { [ "$MODE" = "auto" ] && is_vm_backed; }; then
+  NEED_JUMP=1
+fi
+
+# ── Jump key (only when a jump is needed; generated once, preserved) ──
 # Persisted via a named volume on ~/.ssh-local (see compose), so a fresh key
 # is generated only on the very first start (or if the volume is wiped). When
 # we DO generate one it must be (re-)authorized on the host, so we flag it and
 # print a copy-paste authorize line below.
 KEY_JUST_GENERATED=0
-if [ ! -f "$KEY" ]; then
-  ssh-keygen -t ed25519 -N '' -C "devbox-jump@${HOSTNAME:-container}" -f "$KEY" >/dev/null 2>&1 || exit 0
+if [ "$NEED_JUMP" = "1" ] && command -v ssh-keygen >/dev/null 2>&1 && [ ! -f "$KEY" ]; then
+  if ssh-keygen -t ed25519 -N '' -C "devbox-jump@${HOSTNAME:-container}" -f "$KEY" >/dev/null 2>&1; then
     chmod 600 "$KEY" 2>/dev/null || true
     KEY_JUST_GENERATED=1
+  fi
 fi
 
 # ── Render the writable config ────────────────────────────────────────
-USER_LINE=""
-if [ -n "${HOST_SSH_USER:-}" ]; then
-  USER_LINE="    User ${HOST_SSH_USER}"
-fi
-
-# Optional host-owned named-peer jump overrides (portable: lives on the host,
-# not in the image). Included BEFORE ~/.ssh/config so its ProxyJump wins.
-SSH_LAN_CONF="${HOME}/.config/devbox-shell/ssh-lan.conf"
+# Jump-specific blocks (the host alias, host-owned peer overrides, and the
+# optional RFC1918 catch-all) only make sense when a jump is set up; on native
+# Linux they are all empty and only the ControlPath redirect + Include remain.
+JUMP_BLOCK=""
 LAN_CONF_BLOCK=""
-if [ -r "$SSH_LAN_CONF" ]; then
+AUTOJUMP_BLOCK=""
+if [ "$NEED_JUMP" = "1" ]; then
+  USER_LINE=""
+  if [ -n "${HOST_SSH_USER:-}" ]; then
+    USER_LINE="    User ${HOST_SSH_USER}"
+  fi
+  JUMP_BLOCK=$(cat <<EOF
+
+# The container host (OrbStack / Docker Desktop). 'host' and 'mac' are aliases.
+Host host mac
+    HostName ${HOST_ALIAS_HOSTNAME}
+${USER_LINE}
+    IdentityFile ~/.ssh-local/devbox_jump_ed25519
+    IdentitiesOnly yes
+    ControlMaster auto
+    ControlPath ~/.ssh-local/cm/%r@%h:%p
+    ControlPersist 4h
+    ServerAliveInterval 30
+EOF
+)
+
+  # Optional host-owned named-peer jump overrides (portable: lives on the host,
+  # not in the image). Included BEFORE ~/.ssh/config so its ProxyJump wins.
+  SSH_LAN_CONF="${HOME}/.config/devbox-shell/ssh-lan.conf"
+  if [ -r "$SSH_LAN_CONF" ]; then
     LAN_CONF_BLOCK=$(cat <<'EOF'
 
 # Host-owned named-peer jump overrides (bind-mounted; edit on the host).
@@ -127,13 +161,12 @@ Host *
 Include ~/.config/devbox-shell/ssh-lan.conf
 EOF
 )
-fi
+  fi
 
-# Optional opt-in RFC1918 catch-all: ProxyJump every private IP through the
-# host. Matches the typed address, never the resolved HostName, so named hosts
-# with their own ProxyJump are unaffected. Network-agnostic → roaming-safe.
-AUTOJUMP_BLOCK=""
-if [ "${DEVBOX_LAN_AUTOJUMP_PRIVATE:-0}" = "1" ]; then
+  # Optional opt-in RFC1918 catch-all: ProxyJump every private IP through the
+  # host. Matches the typed address, never the resolved HostName, so named hosts
+  # with their own ProxyJump are unaffected. Network-agnostic → roaming-safe.
+  if [ "${DEVBOX_LAN_AUTOJUMP_PRIVATE:-0}" = "1" ]; then
     AUTOJUMP_BLOCK=$(cat <<'EOF'
 
 # RFC1918 auto-jump (DEVBOX_LAN_AUTOJUMP_PRIVATE=1): reach any private IP on
@@ -146,6 +179,7 @@ Host 10.* 192.168.* 172.16.* 172.17.* 172.18.* 172.19.* 172.20.* 172.21.* 172.22
     ProxyJump host
 EOF
 )
+  fi
 fi
 
 INCLUDE_BLOCK=""
@@ -154,7 +188,9 @@ if [ -r "${HOME}/.ssh/config" ]; then
 
 # Your own target hosts. Scope reset to match-all so this Include applies to
 # every target (an Include is otherwise scoped to the enclosing Host block).
-# Add 'ProxyJump host' to LAN entries here (or in ssh-lan.conf above).
+# To make a LAN peer jump via the host, add 'ProxyJump host' to its entry in
+# the host-owned ~/.config/devbox-shell/ssh-lan.conf (Included above) — NOT
+# here in ~/.ssh/config, which is typically bind-mounted read-only.
 Host *
 Include ~/.ssh/config
 EOF
@@ -176,17 +212,7 @@ Host *
     UserKnownHostsFile ~/.ssh-local/known_hosts
     StrictHostKeyChecking accept-new
     ControlPath ~/.ssh-local/cm/%r@%h:%p
-
-# The container host (OrbStack / Docker Desktop). 'host' and 'mac' are aliases.
-Host host mac
-    HostName ${HOST_ALIAS_HOSTNAME}
-${USER_LINE}
-    IdentityFile ~/.ssh-local/devbox_jump_ed25519
-    IdentitiesOnly yes
-    ControlMaster auto
-    ControlPath ~/.ssh-local/cm/%r@%h:%p
-    ControlPersist 4h
-    ServerAliveInterval 30
+${JUMP_BLOCK}
 ${LAN_CONF_BLOCK}
 ${AUTOJUMP_BLOCK}
 ${INCLUDE_BLOCK}
@@ -199,6 +225,7 @@ chmod 600 "$CONFIG" 2>/dev/null || true
 # host won't recognize. With ~/.ssh-local persisted via a named volume, case
 # (b) fires only on first-ever start (or after the volume is reset) — so this
 # is normally a one-time, one-line step per machine, with no file to locate.
+if [ "$NEED_JUMP" = "1" ]; then
 PUBKEY_TEXT="$(cat "${KEY}.pub" 2>/dev/null)"
 if [ -z "${HOST_SSH_USER:-}" ]; then
   cat <<EOF
@@ -221,5 +248,6 @@ elif [ "$KEY_JUST_GENERATED" = "1" ]; then
          repeat this on container updates — only if that volume is reset.
 EOF
 fi
+fi
 
 exit 0

rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md

@@ -0,0 +1,43 @@
+<!-- pi-devbox:managed-block — appended to the global AGENTS.md at image build
+     time (Dockerfile.variant), after pi-toolkit is cloned. Keep this short:
+     it is a pointer, the depth lives in the skill. -->
+
+## Running inside pi-devbox
+
+If the directory `/usr/local/lib/pi-devbox/` exists (or your shell prompt is
+prefixed `[devbox]`, or `~/.ssh-local/config` is present), you are in a
+**pi-devbox container** — a Docker environment whose persistence, networking,
+DNS, host/LAN reachability, tmux, and Python/REPL behaviour differ from a normal
+workstation. Before any task that touches **reaching the host or its LAN, SSH,
+DNS/name resolution, what survives container recreate, running Python/REPLs,
+tmux, or pi-studio**, read `~/.agents/skills/pi-devbox-environment/SKILL.md`.
+
+Key reflex from that skill: **the deployment specifics are not universal** — the
+host OS, hostnames, internal domains, and nameservers vary per instance and must
+be discovered at runtime, never assumed. And interactive shell aliases
+(`dssh`, `dscp`, `cat`→`bat`) do **not** exist in your non-interactive bash
+tool, so spell out the underlying command (e.g.
+`ssh -F "$HOME/.ssh-local/config" mac …`).
+
+## Browser automation is available (agent-browser)
+
+This image bakes the **`agent-browser`** CLI plus a headless Chromium, so you can
+drive a real browser — open pages, click/fill/`eval`, snapshot the DOM, take
+screenshots — to **verify** front-end work (live DOM, WebGL, layout, popup
+positioning) instead of guessing. Reach for it whenever a task involves a web UI
+or checking how a page actually renders. `AGENT_BROWSER_EXECUTABLE_PATH` is
+preset to the baked browser, so `agent-browser open <url>` works out of the box
+(headless). Run `agent-browser skills get core --full` for the command set and
+workflow patterns (always version-matched to the CLI); the `agent-browser` skill
+under `~/.agents/skills/` mirrors it when the skillset is mounted.
+
+## Session start: load the mempalace skill
+
+If MemPalace MCP tools (e.g. `mempalace_search`, `mempalace_diary_write`) are in
+your tool list, **read `~/.agents/skills/mempalace/SKILL.md` before doing
+non-trivial work** and follow its protocol: search the palace before answering
+about past work, and write a diary entry before the session ends. This is
+especially load-bearing here — a pi-devbox container is frequently recreated, so
+the palace is your only memory across recreates. Without the habit it is just
+storage, not memory. (The skill is the consumer side; feeding the palace is the
+separate `opencode-mempalace-bridge` skill, if present.)

rootfs/usr/local/share/pi-devbox/skills/VENDORED.md

@@ -0,0 +1,47 @@
+# Vendored fallback skills
+
+Most directories here are **image-baked skills** that `entrypoint-user.sh`
+symlinks into `~/.agents/skills/` on container start (only when a skill of the
+same name is not already present, so a mounted `skillset` repo or a user
+override always wins).
+
+| skill | owner | how it gets here |
+|-------|-------|------------------|
+| `pi-devbox-environment` | pi-devbox (this repo) | authored here; the canonical copy |
+| `pi-extensions` | the `pi-extensions` package repo (`skill/`) | **vendored fallback** + refreshed at build |
+| `mempalace` | the `skillset` repo | **vendored fallback** (snapshot only) |
+
+## Why fallbacks exist
+
+The pi-toolkit global `AGENTS.md` tells every pi session to read
+`~/.agents/skills/pi-extensions/SKILL.md` at start (to fix fork/recall
+under-utilisation). That pointer dangles in a container started **without** the
+private `skillset` repo mounted. Baking the skill closes that *availability*
+gap. `mempalace` is baked for the same reason (memory continuity); since
+nothing in pi-toolkit's `AGENTS.md` points to it, the pi-devbox managed block
+(`pi-global-AGENTS.append.md`) also adds the matching *proactive-load*
+directive ("load the mempalace skill at session start") so a new container
+actually picks it up rather than relying on description-matching.
+`pi-extensions`'s directive already ships in pi-toolkit's `AGENTS.md`, so only
+its skill file needed baking.
+
+## Freshness model (layered — see Dockerfile.variant)
+
+- **`pi-extensions`** — Option 1 + Option 2. The committed copy here is the
+  *floor*; at build time `Dockerfile.variant` copies `/opt/pi-extensions/skill/`
+  (the pinned, package-owned source) over it, so a normal build ships the fresh
+  package copy and a stale-ref / mirror build still ships the snapshot. Keep
+  `evaluate-extension-usage.py` alongside `SKILL.md` — the skill calls it via
+  `./`.
+- **`mempalace`** — Option 2 only. The `mempalace` *consumer* skill lives only
+  in the private `skillset` repo (the `mempalace-toolkit` repo ships a
+  *different* skill, `opencode-mempalace-bridge`), so there is no public
+  package source to copy from. This snapshot is refreshed manually per release.
+
+## Refreshing the snapshots
+
+    cp <skillset>/skills/pi-extensions/SKILL.md   pi-extensions/SKILL.md
+    cp <skillset>/skills/pi-extensions/evaluate-extension-usage.py pi-extensions/
+    cp <skillset>/skills/mempalace/SKILL.md       mempalace/SKILL.md
+
+Snapshot provenance at last refresh: skillset `8e8db64`, pi-extensions pkg `a7f3044`.

rootfs/usr/local/share/pi-devbox/skills/mempalace/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: mempalace
+description: MemPalace agent memory protocol. Use on every session to maintain continuity across conversations — search before answering about past work, write diary entries before session ends, and mine new projects into the palace. Load this skill at session start.
+---
+
+# MemPalace Agent Memory Protocol
+
+## Overview
+
+MemPalace gives you persistent memory across sessions via an MCP server. It stores project knowledge (mined from files), conversation summaries (diary entries), and entity relationships (knowledge graph). Without this protocol, you have tools but no habits — and memory without habits is just storage.
+
+**Core principle:** Storage is not memory. Storage + protocol = memory.
+
+## When to Load This Skill
+
+- At the **start of every session** (proactively, before the user asks)
+- When the user mentions **past conversations, decisions, or work**
+- When working on a **new project or repository** for the first time
+- When the user asks about **people, projects, or relationships**
+
+## Session Lifecycle
+
+### Phase 1: Wake Up (session start)
+
+Run these immediately when a session begins, before responding to the user:
+
+1. **Load palace overview:**
+   ```
+   mempalace_status
+   ```
+   This returns wing/room counts, the AAAK spec, and the memory protocol reminder.
+
+2. **Read your recent diary:**
+   ```
+   mempalace_diary_read(agent_name="<your_agent_name>", last_n=5)
+   ```
+   Scan for context about recent sessions — what was worked on, what matters, what's pending.
+
+3. **Check the knowledge graph** for the user or active project if relevant:
+   ```
+   mempalace_kg_query(entity="<project_or_person>")
+   ```
+
+Do NOT announce this to the user. Just do it silently to orient yourself.
+
+### Temporal grounding — compute time deltas, don't guess
+
+Diary entries and drawers carry real timestamps (`timestamp`, `created_at`).
+Before describing *when* something happened — "yesterday", "earlier today",
+"last week", "a while back" — **establish the current date/time first and
+compute the delta against the actual timestamp.** Get "now" from the injected
+session date or by running `date` in a shell; never infer it.
+
+**A container recreate or a fresh session is NOT a day boundary.** A pi-devbox
+container is frequently restarted — often several times within the *same* day —
+and each restart begins a new session with a fresh wake-up. Do not reason "new
+session ⇒ last session was yesterday": two diary entries 90 minutes apart can
+straddle a container recreate. The only authoritative clock is the timestamp on
+the memory, not the session/container boundary.
+
+**Practical rule:** prefer explicit, checkable phrasing — e.g. "earlier today,
+~8h ago (both 2026-06-25)" — over a vague relative term. If you catch yourself
+about to write "yesterday" / "last week", subtract `now − entry.timestamp` and
+state the computed result. (Remember timestamps may be UTC while the wall clock
+is local — reconcile the offset before computing the delta.) Note too that
+session feeders can lag up to a week (see *Multi-harness palace*), so a recent
+absence in `wing_conversations` is not proof nothing happened.
+
+### Phase 2: Active Session (during work)
+
+#### Search Before You Speak
+
+Before answering questions about past work, decisions, people, or projects:
+
+```
+mempalace_search(query="<keywords>", wing="<project>")
+```
+
+**Never guess about facts that might be in the palace.** Wrong is worse than slow. Say "let me check" and query.
+
+#### Mine New Projects
+
+When working on a new codebase for the first time:
+
+1. Check if it's already mined:
+   ```
+   mempalace_list_wings
+   ```
+
+2. **Decide what to mine — docs first, code never (by default).**
+
+   The palace is for *context and intent*, not code recall. Code is better read from the working tree via `Read`/`Grep`/`glob` — always authoritative, never stale. Embedding source code produces thousands of low-signal drawers (e.g. `def __init__(self, ...)` across every class) that pollute search for years.
+
+   **Mine by default:**
+   - `*.md`, `*.rst`, `*.txt` — docs, READMEs, CHANGELOGs, architecture notes
+   - `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, design/decision docs — highest signal per byte
+   - `*.sh`, `Dockerfile`, `Makefile`, entrypoints — small, intent-bearing
+   - `*.yml`, `*.yaml`, `*.toml`, selective `*.json` (`docker-compose`, `pyproject`, `mkdocs.yml`, CI workflows) — skip lockfiles
+
+   **Do NOT mine by default:**
+   - `*.py`, `*.ts`, `*.tsx`, `*.js`, `*.go`, `*.rs`, `*.java`, `*.cpp`, `*.c`, `*.rb` — raw source code
+   - Test files, fixtures, generated code
+   - `node_modules/`, `.venv/`, `__pycache__/`, `.mypy_cache/`, `.pytest_cache/`, `.ruff_cache/` (the miner respects `.gitignore` but double-check)
+
+   Exception: if a code file *is* the documentation (e.g. a heavily-commented reference script, or a protocol definition), file it manually via `mempalace_add_drawer`.
+
+3. **Before mining**, inspect the repo to estimate drawer count:
+   ```bash
+   # Quick audit — what will actually get mined?
+   find <dir> -type f \
+     -not -path '*/.git/*' -not -path '*/node_modules/*' \
+     -not -path '*/.venv/*' -not -path '*/__pycache__/*' \
+     \( -name '*.md' -o -name '*.sh' -o -name '*.yml' -o -name '*.yaml' \
+        -o -name '*.toml' -o -name 'Dockerfile*' -o -name 'Makefile' \) | wc -l
+   ```
+   A docs-heavy repo should produce ~5–10 drawers per file. If a mine produces >15 drawers/file on average, code leaked in — investigate.
+
+4. Run the mine:
+   ```bash
+   mempalace init --yes <directory>
+   mempalace mine <directory> --agent <your_agent_name>
+   ```
+
+   The miner currently lacks a `--docs-only` or `--exclude-ext` flag (as of v3.3.3). Until it does, either:
+   - (a) Add a `mempalace.yaml` at the repo root with explicit include globs, OR
+   - (b) Mine everything, then surgically remove code-sourced drawers via SQL on `~/.mempalace/palace/chroma.sqlite3` (delete by `embedding_metadata.source_file LIKE '%.py'`), followed by `mempalace repair --yes`.
+
+5. If the CLI miner misses a file you *do* want (e.g., `.zsh`, an undocumented extension), file it manually:
+   ```
+   mempalace_add_drawer(wing="<project>", room="<aspect>", content="<verbatim content>", source_file="<path>")
+   ```
+
+6. After mining, reconnect to pick up the new embeddings:
+   ```
+   mempalace_reconnect
+   ```
+   If search errors occur after mining ("Error finding id"), repair the index:
+   ```bash
+   mempalace repair --yes
+   ```
+
+#### Track Facts in the Knowledge Graph
+
+When you learn new facts about people, projects, or relationships:
+
+```
+mempalace_kg_add(subject="ProjectX", predicate="uses", object="PostgreSQL")
+mempalace_kg_add(subject="Alice", predicate="owns", object="ProjectX", valid_from="2026-01-15")
+```
+
+When facts change (ended, no longer true):
+
+```
+mempalace_kg_invalidate(subject="Alice", predicate="works_at", object="OldCorp", ended="2026-03-01")
+```
+
+#### Cross-Reference with Tunnels
+
+When content in one project relates to another, create a tunnel:
+
+```
+mempalace_create_tunnel(
+  source_wing="project_api", source_room="endpoints",
+  target_wing="project_db", target_room="schema",
+  label="API endpoints map to these DB tables"
+)
+```
+
+#### Feeding opencode session history (opencode + mempalace-toolkit only)
+
+MemPalace has no upstream integration with [opencode](https://github.com/anomalyco/opencode) as of v3.3.3 — `hooks_cli.py` only supports `claude-code` and `codex` harnesses. Opencode persists every turn in a local SQLite DB at `~/.local/share/opencode/opencode.db`, but nothing moves that data into the palace automatically.
+
+On a machine with opencode + the [`mempalace-toolkit`](https://gitea.jordbo.se/joakimp/mempalace-toolkit) installed, session history is fed into `wing_conversations` via `mempalace-session` — either manually, or on a weekly systemd user timer / cron schedule shipped in `mempalace-toolkit/contrib/`. If this is missing, opencode conversations exist only in the local SQLite DB and are invisible to `mempalace_search`.
+
+**How to tell if it's set up:**
+
+```
+mempalace_list_wings
+```
+
+If `wing_conversations` exists and has a drawer count comparable to the user's opencode session count, session feeding is working. If it's empty or suspiciously small, suggest:
+
+1. Check if the toolkit is installed: `which mempalace-session`.
+2. If installed, suggest running `mempalace-session --dry-run` to preview and `mempalace-session` to file.
+3. If not installed, point the user at `gitea.jordbo.se/joakimp/mempalace-toolkit` for setup.
+
+**Don't try to paper over the gap by dumping turn-level content into the palace manually via `mempalace_add_drawer`** — that reinvents what `mempalace-session` does with normalization and dedup. Use the tool.
+
+Full routine (triggers, cadence, automation) is in the [`opencode-mempalace-bridge`](https://gitea.jordbo.se/joakimp/mempalace-toolkit) skill and the toolkit's `ARCHITECTURE.md` §5. The two skills pair: this one (`mempalace`) covers using the palace; that one (`opencode-mempalace-bridge`) covers feeding it from opencode.
+
+### Phase 3: Wind Down (session end)
+
+**Always write a diary entry before the session ends.** This is the most important habit.
+
+```
+mempalace_diary_write(
+  agent_name="<your_agent_name>",
+  entry="<AAAK compressed summary>",
+  topic="session-summary"
+)
+```
+
+#### Why still write diaries when sessions may be mined automatically?
+
+On machines running opencode + `mempalace-toolkit`, every session is mined into `wing_conversations` on a weekly (or user-defined) schedule. A common and incorrect conclusion: *"since every turn is captured automatically, writing a diary entry is redundant."* It isn't.
+
+Session mining captures **what was said** (every turn, verbatim). A diary captures **what the session meant** — editorial judgment by the agent who lived it:
+
+- Lessons learned, patterns noticed, pending items rolled forward
+- Meta-observations that were never said aloud during the session
+- Aggregate counts (commits shipped, bugs fixed, hours spent)
+- A compressed, recency-scannable summary for the *next* agent's wake-up
+
+Mining raw turns cannot surface these because the words don't exist verbatim — they're the agent's reflection at wind-down. Think of the split as *release notes* (diary) vs. *git log with diffs* (session mine): a repo keeps both because they answer different questions. So does the palace.
+
+**Practical rule:** automated mining does not replace Phase 3. Both systems cover each other's failure modes — a skipped diary is recovered from the raw turns; a missed mine is recovered from the diary summary. For the full treatment (comparison table, retrieval patterns, token economics), see [`mempalace-toolkit/ARCHITECTURE.md` §5 → "Diary vs session mine: why keep both?"](https://gitea.jordbo.se/joakimp/mempalace-toolkit/src/branch/main/ARCHITECTURE.md#diary-vs-session-mine-why-keep-both).
+
+#### AAAK Diary Format
+
+Write diary entries in compressed AAAK format for efficiency. Structure:
+
+```
+SESSION:<date>|<what.you.worked.on>|
+TASKS:
+1.<task.description>→<outcome>|
+2.<task.description>→<outcome>|
+DISCOVERED:<unexpected.findings>|
+ENTITIES:<people.or.projects.encountered>|
+<importance: one to five stars>
+```
+
+Example:
+
+```
+SESSION:2026-04-28|api.refactor+db.migration|
+TASKS:
+1.refactored.auth.endpoints→split.into.3.modules|
+2.added.user.roles.migration→postgres.enum.type|
+DISCOVERED:legacy.session.table.unused.since.v2|
+ENTITIES:ProjectX;Alice(reviewer)|
+***
+```
+
+Rules:
+- Use dots instead of spaces within phrases
+- Use pipes as field separators
+- Use arrows for cause/effect or transitions
+- Stars indicate session importance (one to five)
+- Keep it tight — a future agent should get the gist in seconds
+
+#### What to Capture
+
+Prioritize recording:
+- **Decisions made** and their rationale
+- **Discoveries** — things that surprised you or that a future session needs to know
+- **Unfinished work** — what's pending, what was deferred
+- **User preferences** observed during the session
+- **Entities encountered** — people, projects, tools, services
+
+### Phase 4: Fact Updates
+
+If facts changed during the session, update the knowledge graph before writing the diary:
+
+```
+mempalace_kg_invalidate(subject="...", predicate="...", object="...", ended="<today>")
+mempalace_kg_add(subject="...", predicate="...", object="...", valid_from="<today>")
+```
+
+## Palace Structure
+
+### Wings
+
+Wings are top-level categories, typically one per project or domain:
+- Named after the project directory (e.g., `cli_utils`, `opencode_devbox`)
+- Agent diaries live in `wing_<agent_name>` (e.g., `wing_orchestrator`, `wing_pi`)
+
+#### Multi-harness palace
+
+A single palace can be fed by multiple coding-agent harnesses. On this machine the palace is shared between **opencode** and **pi** (Mario Zechner's pi-coding-agent). Implications:
+
+- **`wing_conversations` mixes sources.** Both harnesses' session feeders write into the same wing. To tell them apart, look at the `source_file` metadata on each drawer:
+  - `pi_<uuid>.jsonl` → pi session
+  - `<slug>_ses_<id>.jsonl` → opencode session
+  - The first chunk of each session also carries a `| source: opencode` or `| source: pi` marker in the synthetic header line.
+- **Other wings may belong to other harnesses.** For example `wing_pi` is pi's diary, not opencode's. Don't assume every diary entry was written by you — check `agent_name` on the entry.
+- **Session feeders run on different schedules.** Pi sessions are fed Tue 03:00, opencode sessions Mon 03:00. Recent sessions from either harness can lag the palace by up to a week, so absence-of-evidence in `wing_conversations` is not evidence-of-absence for recent work.
+- **Reading another harness's diary is useful.** When orienting after a gap, `mempalace_diary_read agent_name=pi` (or whichever sibling agent has been active) often gives a fresher picture than waiting for the conversations feeder to catch up.
+
+### Rooms
+
+Rooms are aspects within a wing:
+- `fzf`, `scripts`, `configuration`, `general` — whatever the miner detects
+- Diary entries go into rooms by topic tag
+
+### Drawers
+
+Drawers hold verbatim content — never summarized, always searchable.
+
+### Tunnels
+
+Cross-wing connections linking related content across projects.
+
+### Knowledge Graph
+
+Entity-relationship triples with temporal validity. Query with `mempalace_kg_query`, browse with `mempalace_kg_timeline`.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| "No palace found" | Run `mempalace init <dir>` then `mempalace mine <dir>` |
+| "Error finding id" after mining | Run `mempalace repair --yes` then `mempalace_reconnect` |
+| Search returns irrelevant results | Use `max_distance=1.0` for stricter matching; add `wing` filter |
+| Miner skips file types | File manually with `mempalace_add_drawer` or use `--no-gitignore` |
+| Stale results after external changes | Call `mempalace_reconnect` |
+
+## Anti-Patterns
+
+- **Don't guess when you can search.** If a question touches past work, search first.
+- **Don't infer elapsed time from session or container boundaries.** A restart isn't a new day. Compare the actual timestamp (`timestamp` / `created_at`) against the current date/time before saying "yesterday", "last week", etc.
+- **Don't skip the diary.** A session without a diary entry is a session forgotten.
+- **Don't summarize drawer content.** File verbatim — the embedding model needs the original words.
+- **Don't mine .git directories or node_modules.** The CLI miner respects .gitignore by default.
+- **Don't create duplicate drawers.** Use `mempalace_check_duplicate` before adding manually.
+- **Don't treat the palace as a task list.** It's for knowledge and context, not todos.

rootfs/usr/local/share/pi-devbox/skills/pi-devbox-environment/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: pi-devbox-environment
+description: >-
+  Operate correctly inside a pi-devbox container. Load when running inside
+  pi-devbox (detection: the directory `/usr/local/lib/pi-devbox/` exists, the
+  shell prompt is prefixed `[devbox]`, or `~/.ssh-local/config` is present) and
+  the task touches any of: reaching the Docker host or its LAN, SSH, DNS name
+  resolution, what survives container recreate (persistence vs ephemerality),
+  running Python or other REPLs, tmux, or the pi-studio browser UI. Covers the
+  persistence model, the interactive-vs-tool-shell alias gotcha
+  (dssh/dscp/cat=bat exist only in interactive bash), host + LAN SSH
+  reachability and ControlMaster, split-horizon DNS mechanisms, the tmux
+  0-index constraint, uv-first Python, and pi-studio reachability. This skill
+  teaches MECHANISMS only — concrete hostnames, usernames, internal domains,
+  nameservers, and even the host OS vary per deployment and MUST be discovered
+  at runtime, never assumed or hardcoded.
+---
+
+# pi-devbox environment
+
+You are (or may be) running inside **pi-devbox**: a Docker container that ships
+pi, MemPalace, and a curated tool stack, with the host source tree mounted at
+`/workspace`. This skill is about the *container-shaped* facts that change how
+you should act — things that are easy to get wrong because they differ from a
+normal workstation shell.
+
+> **Golden rule: this environment is a template, not a fixed deployment.**
+> The host could be macOS, Windows, or Linux. There may or may not be LAN
+> peers, a VPN, split-DNS, a skillset mount, or the `-studio` variant. Detect
+> and verify the specifics live (commands below) — do **not** assume any
+> particular hostname, domain, nameserver, or OS. Where this skill shows
+> example values they are illustrative placeholders.
+
+## 0. Am I in pi-devbox, and what's true *here*?
+
+Cheap detection signals (any one is sufficient):
+
+```sh
+[ -d /usr/local/lib/pi-devbox ] && echo "pi-devbox image"
+[ -r "$HOME/.ssh-local/config" ] && echo "LAN/host SSH sidecar present"
+case "$PS1" in *'[devbox]'*) echo "interactive devbox shell";; esac
+```
+
+Then orient before acting:
+
+```sh
+cat /etc/os-release | head -2          # container distro (usually Debian)
+ls -la /usr/local/lib/pi-devbox/       # which devbox helpers exist
+sed -n '/^Host /,$p' ~/.ssh-local/config 2>/dev/null   # host/LAN reachability, if any
+mount | grep -E ' /workspace | /home/\S+/\.ssh '       # what's bind-mounted
+```
+
+## 1. Persistence vs ephemerality — know before you write
+
+The container has **three storage tiers with very different lifetimes**. Pick
+the right one or work is silently lost on the next recreate/update.
+
+| Tier | Examples | Survives `down`? | Survives `down -v`? | Survives image update / `--force-recreate`? |
+|---|---|---|---|---|
+| **Host bind-mount** | `/workspace`, usually `~/.ssh` (ro), often `~/.mempalace` | yes | yes (lives on host) | yes |
+| **Named volume** | `~/.pi`, `~/.ssh-local`, `~/.cache/bash`, `~/.local/share/{uv,nvim,zoxide}` | yes | **no** | yes |
+| **Writable container layer** | anything else: `sudo apt install …`, `rustup`/`ghc`/`R` toolchains, files in `/tmp`, `/opt` edits | yes | **no** | **no** |
+
+Practical consequences:
+
+- **Durable work goes in `/workspace`** (it's the host filesystem, UID-aligned —
+  what you write appears with the user's normal ownership on the host).
+- **Runtime-installed system packages and language toolchains are ephemeral.**
+  If a task needs them reproducibly, it belongs in the image (Dockerfile) or a
+  project manifest, not an ad-hoc `apt install`. Tell the user when you install
+  something that won't survive.
+- **`~/.pi` is a named volume**, so things baked into the *image* under
+  `/home/<user>/...` are **shadowed** by the volume on existing containers and
+  only seen on a fresh volume. Image-owned content that must always be live
+  belongs under an image path like `/usr/local/...` or `/opt/...` and is linked
+  in by the entrypoint — not dropped into a home directory that a volume covers.
+
+## 2. Interactive shell vs. your tool shell (a real footgun)
+
+The conveniences below are defined in `~/.bash_aliases` and **only exist in an
+interactive login shell.** Your `bash` *tool* runs non-interactively, so these
+are "command not found" there — you must spell out the underlying command.
+
+| Interactive alias | Non-interactive equivalent to actually run |
+|---|---|
+| `dssh <host>` | `ssh -F "$HOME/.ssh-local/config" <host>` |
+| `dscp …` | `scp -F "$HOME/.ssh-local/config" …` |
+| `cat file` (→ `bat`) | `cat file` works, but output differs; use `command cat` for raw |
+| `ll`, `la` (→ `eza`/`ls`) | `ls -lh`, `ls -lha` |
+
+If a command "works in my terminal but not when the agent runs it," this alias
+gap is the first thing to suspect.
+
+**`dscp`/`scp` with accented filenames on a macOS host.** macOS stores filenames
+in Unicode **NFD** (decomposed — e.g. `ä` is `a` + combining U+0308), while the
+string you type or paste is usually **NFC** (precomposed `ä`, U+00E4). The bytes
+differ, so a precomposed remote path *silently* fails to match on the host —
+`scp … "mac:'~/Desktop/Skärmavbild ….png'"` returns *No such file or directory*
+even though the file plainly exists. Sidestep the encoding entirely: let the
+**remote shell expand a wildcard**, or list the directory first and copy the
+exact name it prints.
+
+```sh
+# glob dodges the NFC/NFD mismatch (the remote shell matches the real bytes):
+scp -F "$HOME/.ssh-local/config" "mac:~/Desktop/Sk*rmavbild*.png" ./
+# or read the exact filename first, then copy that:
+ssh -F "$HOME/.ssh-local/config" mac 'ls -1 ~/Desktop/*.png'
+```
+
+## 3. Reaching the Docker host and its LAN over SSH
+
+When the host is VM-backed (e.g. OrbStack / Docker Desktop on macOS) the
+entrypoint's `setup-lan-access.sh` writes a **writable SSH sidecar** at
+`~/.ssh-local/config`. It always provides:
+
+- A `Host *` block redirecting `ControlPath` into the writable `~/.ssh-local/cm`
+  (because `~/.ssh` is typically bind-mounted **read-only**, so a master socket
+  can't be created under it), plus `Include ~/.ssh/config`.
+- Aliases **`host` / `mac`** → `host.docker.internal` (user comes from
+  `HOST_SSH_USER`) — i.e. SSH back into the Docker host.
+- On VM-backed hosts only: an **SSH-jump-via-host** block so the container can
+  reach the host's directly-attached LAN peers (`ProxyJump host`). On a native
+  Linux host the LAN is usually reachable directly and this jump block is
+  omitted — **so don't assume a jump path exists; read the sidecar.**
+
+Use it (remember §2 — spell it out in tool bash):
+
+```sh
+ssh -F "$HOME/.ssh-local/config" mac 'hostname; whoami'      # reach the host
+ssh -F "$HOME/.ssh-local/config" <lan-peer> '…'             # reach a LAN peer (if configured)
+```
+
+Two related mechanisms (don't reinvent them):
+
+- **ControlMaster multiplexing** is preconfigured (`/tmp/sshcm/`) to survive
+  CGNAT per-destination flow caps on residential ISPs. If `~/.ssh/config` pins
+  a `ControlPath` under the read-only `~/.ssh`, override with
+  `-o ControlPath=none` (or use the sidecar, which already redirects it).
+- **`pi --ssh <host>`** rewires pi's own read/write/edit/bash tools to run on a
+  remote host; it has its own writable-socket fallback. See the `pi-extensions`
+  skill for that path.
+
+## 4. DNS / name resolution — environment-specific, verify live
+
+How a name resolves here is **not universal** and depends on the host's
+networking. The container's own resolver is just `/etc/resolv.conf`, but the
+*host* (which you reach via §3, and whose DNS the container may inherit) can use
+**split-horizon DNS** to send certain internal domains to specific nameservers
+while everything else goes to a default resolver/VPN gateway. The mechanism is
+OS-specific and **may not be present at all**:
+
+- **macOS host:** per-domain files in `/etc/resolver/<domain>`, each listing
+  `nameserver` lines. Reading them (over `ssh … mac`) is a fine way to learn the
+  real split-DNS map — *for that one machine.*
+- **Linux host:** typically `systemd-resolved` split DNS (per-link `Domains=`
+  routing) or `/etc/resolv.conf` `search`/`nameserver`.
+- **Windows host:** the NRPT (Name Resolution Policy Table) plays the per-suffix
+  role; WSL2 inherits host resolution via mirrored networking + DNS tunneling.
+
+Operating rules:
+
+1. **Never hardcode a domain→nameserver mapping or a specific nameserver IP** —
+   it is per-deployment and changes between users and even VPN states.
+2. **Verify by reading the live config**, e.g. `cat /etc/resolv.conf` in the
+   container, or `ssh … mac 'cat /etc/resolver/* 2>/dev/null'` on a macOS host.
+3. **Reachability needs both DNS *and* a route.** A name resolving to an
+   internal address is useless if packets to that subnet don't have a path
+   (e.g. via the VPN or the §3 jump). Check both when something "resolves but
+   won't connect."
+4. If you discover deployment-specific facts (a domain, a nameserver, a
+   reachable peer), prefer recording them in MemPalace over baking them into
+   code or this skill.
+
+## 5. tmux is 0-indexed — don't change it
+
+The image ships `/etc/tmux.conf` with `base-index 0` / `pane-base-index 0`
+because **pi-studio hard-codes its tmux send target to `<session>:0.0`.** If you
+(or a user `~/.tmux.conf`) set `base-index 1`, pi-studio fails with "can't find
+window: 0". Leave the indexing alone in this environment.
+
+## 6. Python and other languages: uv-first, toolchains are ephemeral
+
+- A system `python3` exists, but **prefer `uv`** for REPLs and project envs —
+  it's installed and its store (`~/.local/share/uv`) is a persisted volume.
+  - Throwaway REPL: `uv run --with ipython ipython`
+  - Project env: `cd /workspace/proj && uv init && uv add <pkgs> && uv run …`
+    (the `pyproject.toml` + `uv.lock` travel with the repo — the durable choice).
+- Other language toolchains (Rust via rustup, R, GHC, Clojure, Go) are
+  **runtime opt-ins on the ephemeral layer** unless baked into the image — they
+  do not survive `down -v` or an image update. Flag this when installing.
+
+## 7. pi-studio reachability (only in the `-studio` variant)
+
+Present only if `/opt/pi-studio` exists / the `studio_*` tools are in your tool
+list. pi-studio **binds to `127.0.0.1` inside the container** with no host-bind
+flag, so a plain `docker -p` publish can't reach it. Two supported paths:
+
+- **Host networking** (`network_mode: host`): container loopback == host
+  loopback; open the tokenized URL on the host. (Changes
+  `host.docker.internal` semantics — weigh against §3 LAN jump.)
+- **`studio-expose` bridge** (`STUDIO_EXPOSE=1` or run `studio-expose &`): a
+  `socat` relay from the container's external interface to its loopback, so a
+  published `127.0.0.1:PORT` + `ssh -L PORT:127.0.0.1:PORT host` reaches it.
+
+The real auth token comes from the `/studio` slash command (`/studio --status`
+to reprint), **not** from `studio-expose`. For Graphviz, use `dot-watch` →
+PNG (Studio renders Mermaid natively and previews PNG, but not SVG/DOT).
+
+## 8. MemPalace is the shared brain
+
+MemPalace data is usually a **host bind-mount**, so a pi on the host and a pi in
+this container share one palace (SQLite WAL: many readers, one writer). Use it
+to persist the deployment-specific facts this skill deliberately refuses to
+hardcode. Details are in the `mempalace` skill.
+
+## Checklist before acting in this environment
+
+- [ ] Writing durable output? → `/workspace`, not the ephemeral layer.
+- [ ] Using `dssh`/`dscp`/`ll` in the bash tool? → spell out the real command.
+- [ ] Assuming a hostname / domain / nameserver / host OS? → stop, detect it.
+- [ ] "Resolves but won't connect"? → check route *and* DNS (§3 + §4).
+- [ ] `apt`/toolchain install? → tell the user it's ephemeral unless imaged.
+- [ ] Touching tmux indexing? → don't (§5).

rootfs/usr/local/share/pi-devbox/skills/pi-extensions/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: pi-extensions
+description: >-
+  Use the pi extensions (pi-fork, pi-observational-memory, ssh-controlmaster) effectively in the pi coding agent harness. Load this skill only when running inside pi (detection - `fork` and `recall` are present in your tool list, or `pi --ssh` was used to start the session). pi-fork dispatches focused subtasks to forked agents at fast/balanced/deep effort tiers; pi-observational-memory compacts long sessions into recallable observations + reflections; ssh-controlmaster rewires pi's read/write/edit/bash tools to execute on a remote host over a multiplexed SSH connection. This skill covers tier selection, task design, boundary discipline, when to use recall, and remote-pi mechanics.
+---
+
+# Pi Extensions: pi-fork, pi-observational-memory, ssh-controlmaster
+
+## When to Load This Skill
+
+Load only when **both** of these are true:
+
+1. You are running inside the **pi coding agent harness** (not Claude Code, not opencode, not any other harness).
+2. The `fork` and/or `recall` tools appear in your available tool list, **or** the session was started with `pi --ssh ...`.
+
+If you do not see those tools, this skill does not apply — skip it. Other harnesses do not have these extensions and the patterns below will not work there.
+
+This skill is most useful at the start of any non-trivial session where you may need to dispatch parallel subtasks, where the conversation is likely to compact (sessions running > ~80k tokens), or where pi is operating against a remote host.
+
+## Pi extension landscape (where the wiring lives)
+
+Pi has **two distinct extension locations** and it's easy to look in the wrong one:
+
+| Location | Mechanism | Examples |
+|---|---|---|
+| `~/.pi/agent/extensions/*.ts` (or `.ts.off`) | **Local extensions** — TypeScript files, usually symlinks into `/opt/pi-extensions/extensions/` or similar. Toggled via `/ext` slash command. | `ssh-controlmaster`, `git-checkpoint`, `notify`, `todo`, `mempalace`, `mcp-loader`, `ext-toggle`, `confirm-destructive` |
+| `~/.pi/agent/git/<host>/<owner>/<repo>/` | **Package extensions** — git-cloned npm packages registered via the `packages` array in `~/.pi/agent/settings.json`. | `pi-fork` (`github.com/elpapi42/pi-fork`), `pi-observational-memory` (`github.com/elpapi42/pi-observational-memory`, **default branch `master`** — a `main` branch does not exist, so `pi install git:...` resolves against `master`) |
+
+When the user asks how to use "the X extension", **check both locations** — `find ~/.pi/agent -maxdepth 4 -name "*X*"` covers both. The `/ext` slash command shows the local-extensions list with enable/disable state. There is also a distinct skill-bundled-script category (e.g. `ci-release-watcher`'s `ssh-control-master-setup.sh`) which is **not** a pi extension at all — it's a helper script inside a skill. Don't conflate the three.
+
+## Why These Extensions Belong Together
+
+pi-fork and pi-observational-memory are symbiotic. **pi-fork burns context** (each fork dispatches a focused subtask whose detailed exploration would otherwise pollute your main thread). **pi-observational-memory preserves context** (when the main thread eventually compacts, observations + reflections survive the fold and can be recalled by ID). Aggressive forking only works long-term if the surviving summary is high-fidelity, and OM only earns its keep when it's preserving genuinely valuable distilled work.
+
+ssh-controlmaster is orthogonal but composes cleanly: when pi is operating remotely, fork still spawns local sub-agents (each fork *itself* doesn't ssh), but their `bash`/`read`/`write`/`edit` calls do — see Part 3 caveats.
+
+---
+
+## Part 1: pi-fork
+
+### Effort tier mapping
+
+Configured in `~/.pi/agent/settings.json` under `pi-fork.effortProfiles`. The conventional mapping is:
+
+| Tier | Model | Use for |
+|---|---|---|
+| `fast` | haiku | mechanical edits, narrow lookups, file-listing, single-fact verification, simple syntactic checks |
+| `balanced` | sonnet (default) | normal exploration, implementation, testing, code review, option analysis |
+| `deep` | opus | architecture decisions, security analysis, concurrency reasoning, ambiguous debugging, high-risk reviews, runbook drafting where subtle mistakes are costly |
+
+**Rule of thumb:** start at `balanced` unless you have a specific reason to go up or down. Going too cheap on a deep task wastes a fork; going too expensive on a mechanical task is just slow.
+
+### When to fork vs. do it yourself
+
+Fork when **any** of:
+- The task requires reading many files whose contents you don't need to keep in your main context afterwards (the fork returns a dense summary; raw file contents stay in the fork's context and are discarded).
+- You want to run multiple analyses in **parallel** (especially: comparing N options, where independent reasoning is itself a signal — see "parallel forks" below).
+- The task is well-scoped enough to specify completely up front and well-bounded enough that returning a dense report is more useful than continuing the dialogue.
+- You are about to do something that would burn a lot of tokens on tool calls (long file reads, many bash invocations) whose output you will mostly discard.
+
+Don't fork when:
+- The work fits in your current context budget without crowding out what comes next.
+- The task is exploratory and you'll need to iterate based on what you find (forking turns iteration into round-trips with full task-spec rewrites).
+- You need to make decisions during the work that depend on context only the main thread has.
+
+### Task design: the four things a fork brief must contain
+
+1. **Verified context up front.** Do not say "go look at the codebase and figure out X". Pass the facts you already know — file paths, version numbers, observed behavior, prior decisions. The fork should be reasoning *from* context, not *finding* context. Discovery work costs the fork tokens that don't come back to you.
+2. **A specific deliverable.** "Analyze X" is too vague. "Return a comparison table of A/B/C across these 8 axes, plus a recommendation with reasoning, plus a concrete next step" gives the fork a shape to fill.
+3. **Decision authority.** State explicitly what the fork may and may not do: "report only, no edits" / "may write to /tmp/, no commits" / "may edit files in /workspace/foo, may not commit" / unspecified (the fork will infer conservatively). **State this even when it seems obvious.** See "Boundary discipline" below.
+4. **What "unsure" looks like.** Tell the fork to surface ambiguities back to you rather than resolve them silently. "Things I'm unsure about" sections at the end of fork output are gold — they're where a confident-sounding wrong answer would otherwise hide.
+
+### Parallel forks for option-comparison
+
+When facing a "which approach should we take" question with 2–4 candidate approaches, dispatching the candidates as parallel forks is high-leverage:
+
+- They reason **independently**. No fork sees the others' work.
+- **Convergence is signal.** If three forks at different effort tiers reach the same recommendation citing different evidence, that's a strong validation that doesn't depend on any one model's bias.
+- **Divergence is also signal.** If one disagrees, read its reasoning carefully — it may have spotted something the others missed, or it may have a tier-specific weakness worth knowing.
+
+Sample shape for an option-comparison call:
+- Fork 1 (deep) — detailed runbook for option A, with timing/risk/rollback
+- Fork 2 (balanced) — comparison table A vs B vs C across N axes, with a recommendation
+- Fork 3 (fast) — focused sub-question (e.g., "which container image / library version / CLI flag")
+
+This costs more than a single fork but the cross-validation is often worth it for decisions you'll execute on prod systems.
+
+### Boundary discipline (observed behavior)
+
+Forks **mostly** honor explicit decision-authority instructions, but not infallibly. Observed pattern from real sessions:
+
+- **Pure analysis tasks** (no write authority, "report only") — high compliance. Forks reliably return analysis without editing files or committing.
+- **Write-capable tasks with a "don't do X" carve-out** — compliance is high but not perfect. Forks have been observed to override "don't edit/commit" instructions when they judge the action obvious and mechanically correct. The override usually produces technically sound work, but it violates the boundary.
+
+**Practical rules:**
+- State decision authority explicitly, every time, even when "report only" feels redundant.
+- For high-stakes write authority, verify the fork's actions afterwards (`git status`, `git log -1`, file diffs) rather than assuming compliance.
+- If a boundary violation is unacceptable (e.g., compliance review, sandboxed exploration, "don't touch prod"), do not give the fork write tools at all — keep it strictly in analysis mode.
+- The fact that the fork was "right anyway" is not the same as the fork having followed instructions.
+
+### Anti-patterns
+
+- **Forking trivial work.** A fork has overhead. If the task takes < 30 seconds in your main thread, just do it.
+- **Vague briefs.** "Look into the database thing" returns vague output. The fork is not telepathic.
+- **Forking iterative work.** Forks are one-shot. If you need to iterate, you'll re-spec the task each time — usually worse than doing it yourself.
+- **Recursive forking** (forks spawning forks). Disabled by default and should stay disabled unless you have a specific batch-fanout use case.
+- **Treating fork output as ground truth without verification.** Especially for cited code/commit hashes/URLs — forks can hallucinate these like any LLM. Spot-check decisive evidence.
+
+---
+
+## Part 2: pi-observational-memory
+
+### How it actually works
+
+Observational memory (OM v3, "session-ledger" architecture) runs an **observer agent** in the background as your conversation grows. When token thresholds are crossed (defaults: observe at 10k, reflect at 20k, compact at 81k), the observer distills the recent transcript into:
+
+- **Observations** — timestamped events, each with a 12-character hex ID like `[3682ebfad7af]`. Compact one-liners describing what happened in the conversation.
+- **Reflections** — durable, long-lived facts about the user, project, decisions, and constraints. Some reflections include observation IDs as evidence pointers.
+
+When compaction fires, the raw transcript is folded away and replaced with a structured summary block containing the observations + reflections. **You — the next turn of the same agent — receive that summary block as your starting context.** That's the recovery mechanism.
+
+**Storage is in-transcript, not on disk.** Do not grep for `observations.jsonl` or similar files; you will not find them. The artifact lives in the model's input context window.
+
+Configuration lives in `~/.pi/agent/settings.json` under `observational-memory`. Tune `observeAfterTokens`, `reflectAfterTokens`, `compactAfterTokens`, and `observationsPoolMaxTokens` if observations feel sparse or noisy. The default 81k compaction threshold is well-calibrated for typical multi-task sessions.
+
+### The `recall` tool
+
+`recall(<12-char-hex-id>)` resolves a specific observation or reflection ID back to the original source context — the exact bash output, file contents, tool call results, commit message, or transcript fragment that the observation was distilled from.
+
+**Use recall when:**
+- You are about to make a decision that depends materially on a compacted observation or reflection whose details are unclear.
+- You need exact wording, paths, commands, errors, commits, or user constraints behind a remembered claim.
+- A broad reflection is relevant but you need its supporting observations to act safely.
+- The user asks "why do you believe X" or "what supports that memory".
+
+**Do not use recall for:**
+- Semantic search (it's keyed by ID, not topic — you must already have a specific 12-char hex ID).
+- Browsing the transcript out of curiosity.
+- Preemptive lookup of every ID in your context "just in case".
+
+Recall costs tokens. Use it when exact source context will materially change your next action.
+
+> **Calibration note (from a real ~1-month trial, 2026-05/06):** across 20 logged container sessions, `recall` was invoked **0 times** while obsmem passively carried 529 observations across 6 compactions. Zero recall is a *warning sign*, not a badge of efficiency — it means decisions after a compaction were made on the distilled one-liner alone, without ever re-checking the source. The injected summary is **lossy by design**. Default habit to adopt: when you are about to **edit code, ship a change, or assert a fact** that rests on a `[high]`/`[critical]` observation or a reflection you did not produce *this* turn, `recall` its ID **first**. One recall before a load-bearing action is cheap; redoing finished work or contradicting a prior correction is not.
+
+### Reading the compaction summary
+
+When you see a block like `The conversation history before this point was compacted into the following summary:` at the start of a session or turn, that's OM output. Standard structure:
+
+- **Reflections** at the top: stable facts. Some have IDs in brackets.
+- **Observations** below, chronological: timestamped events with IDs in brackets and importance markers (`[high]`, `[critical]`, etc.).
+
+When entries conflict, **the most recent observation reflects the latest known state.** Work that prior observations describe as completed should not be redone unless the user explicitly asks to revisit it.
+
+### Anti-patterns
+
+- **Treating compacted memory as definitive without recall** when stakes are high. Compaction is lossy; the observation may have lost a constraint that was on the line above it in the original transcript.
+- **Recalling every ID preemptively.** Wasteful. Recall on demand.
+- **Assuming the disk holds OM artifacts.** It doesn't. Don't waste time looking.
+- **Ignoring the summary block** when starting a session. It's there because the prior session was real work — read it before answering questions about past work.
+
+---
+
+## Quick Reference
+
+```
+fork(task=..., effort=fast|balanced|deep)
+  - state decision authority explicitly
+  - pass verified context up front
+  - specify deliverable shape
+  - ask for "unsure about" section
+
+recall(id=<12-char-hex>)
+  - only when stakes justify the cost
+  - id must already be visible in your context
+  - not a search tool
+```
+
+```
+~/.pi/agent/settings.json
+  pi-fork.effortProfiles    — model + thinking-depth per tier
+  pi-fork.defaultEffort     — usually "balanced"
+  observational-memory.*    — token thresholds, model, agentMaxTurns
+  observational-memory.debugLog: true  — opt-in NDJSON telemetry at
+    ~/.pi/agent/observational-memory/debug/<session>.ndjson (off by default)
+```
+
+### Installing on a fresh machine (host)
+
+These are git-sourced pi packages (pi-fork is **not** on npm). Add to the
+`packages` array in `~/.pi/agent/settings.json`, or:
+
+```
+pi install git:github.com/elpapi42/pi-fork
+pi install git:github.com/elpapi42/pi-observational-memory   # default branch: master (no main)
+# obsmem is also published: pi install npm:pi-observational-memory
+```
+
+Restart pi after install. Enable `observational-memory.debugLog` if you want
+the next window instrumented.
+
+### Evaluating usage
+
+`evaluate-extension-usage.py` (bundled next to this skill) mines pi session
+transcripts for fork/recall counts and obsmem compaction stats. Run it per
+machine (transcripts live at `~/.pi/agent/sessions/`) for a combined
+host+container picture:
+
+```
+./evaluate-extension-usage.py                  # ~/.pi/agent/sessions
+./evaluate-extension-usage.py /path/a /path/b  # multiple roots
+```
+
+---
+
+## Part 3: ssh-controlmaster
+
+### What it does
+
+When pi is launched with `--ssh`, this extension **rewires pi's `read`, `write`, `edit`, and `bash` tools to execute on the remote machine**, multiplexed over a single SSH ControlMaster socket. Pi is still running locally — the LLM, the UI, the MCP servers, the fork dispatcher all live on your local box — but anything those tools touch on the filesystem is the *remote's* filesystem.
+
+This is fundamentally different from running pi locally and using `bash` to ssh inside it: with `--ssh`, the tool layer itself is remoted, so the LLM thinks it's working in the remote's `cwd` (the system prompt is rewritten to say so).
+
+### Usage
+
+```bash
+# Key-based auth (preferred), remote cwd defaults to remote $HOME
+pi --ssh lagret
+
+# Pin to a specific remote directory
+pi --ssh lagret:/volume1/docker/portainer/compose/119
+
+# Password auth (input is NOT masked when typing)
+pi --ssh user@host --ssh-ask-pass
+```
+
+The `lagret` form requires a `Host lagret` block in `~/.ssh/config` or a resolvable hostname. The status bar shows `SSH ⚡ own master <host>:<cwd>` or `SSH ⚡ system master <host>:<cwd>` once connected.
+
+### How it cooperates with system SSH config
+
+It reads `ssh -G <host>` to learn the effective config, then:
+
+| `~/.ssh/config` for the host | Behavior |
+|---|---|
+| `ControlMaster auto` or `yes` with a `ControlPath` | Reuses the system master socket. Does **not** tear it down on pi exit ("it was the system's to manage before pi arrived"). |
+| No ControlMaster configured (or explicitly `no`) | Creates its own master at `/tmp/pi-cm-<pid>.sock` with `ControlPersist=yes`. Tears it down on pi `session_shutdown`. |
+
+This means it composes cleanly with the system-wide `ssh-control-master-setup.sh` helper from the `ci-release-watcher` skill: if that script has already configured `~/.ssh/config` for the host, `pi --ssh` rides on the existing master rather than opening a parallel connection.
+
+### Caveats and edge cases
+
+- **Local vs remote tool boundary.** Only `read`/`write`/`edit`/`bash` are remoted. **MCP servers are still local** — `mempalace` files drawers and diary entries against the local palace even when your shell work happens remotely. Same for `fork`, `recall`, `todo`, and any other custom tool. This is usually what you want (palace memory survives across remote sessions) but worth knowing.
+- **fork over ssh.** Forks spawn locally and inherit the same `--ssh` mode by virtue of the parent's tool wiring; the fork's bash calls hit the same ControlMaster. Forks burn the same SSH socket, not a parallel one — multiplexing wins again.
+- **macOS Unix socket path limit.** The own-master socket lives at `/tmp/pi-cm-<pid>.sock` to stay under macOS's ~104-char limit. If you have a non-default `TMPDIR` long enough to blow this, ssh will fail to start the master.
+- **Password auth password visibility.** From the source: *"input is NOT masked — the password is visible while typing."* The password is written to a chmod-700 SSH_ASKPASS script in `/tmp` and deleted after the master establishes; not persisted, but on-screen during entry.
+- **Remote bash environment.** The remote shell is whatever `ssh user@host '<cmd>'` invokes — typically a non-login non-interactive bash. Don't expect `~/.bashrc` aliases or PATH manipulations from `~/.profile`. Pin tool paths or invoke via `bash -lc '...'` if you need login-shell behavior.
+- **Path translation is naive.** The extension does `path.replace(localCwd, remoteCwd)` to translate paths in tool calls. If the LLM emits an absolute remote path that doesn't share the local-cwd prefix, the path is passed through unchanged — usually fine but pathological for paths that happen to contain the local-cwd substring.
+
+### When to use it
+
+- Editing configs on a NAS / homelab host without scp ping-pong (`pi --ssh lagret:/volume1/...`)
+- Operating against a host whose tools/data you need but whose disk is too slow to mount via SSHFS
+- Investigating runner state, container configs, etc., on a remote host as if local
+- Multi-step remote work where opening a fresh ssh connection per step would burn your CGNAT flow budget
+
+### Anti-patterns
+
+- **Using `pi --ssh` for one-off shell work.** Just `ssh` directly. The extension shines when there are dozens of tool calls per session.
+- **Filing palace drawers expecting them on the remote.** They go to the local palace. If you want palace artifacts on the remote host, ssh into the remote and run pi *there* against its local palace.
+- **Forgetting `--ssh` in followup sessions.** Status bar is the canary — if you don't see `SSH ⚡` you're operating locally despite intending remote. Easy mistake on a fresh terminal.
+
+### Reaching the devbox host from inside the container (`dssh` / `dscp`)
+
+Distinct from `pi --ssh` above. When the **pi-devbox container** runs under OrbStack / Docker Desktop on macOS, it can SSH back to its own host. The entrypoint's `setup-lan-access.sh` regenerates `~/.ssh-local/config` on **every container start** (the in-container `~/.ssh` is mounted read-only, so a sidecar config + `known_hosts` + `ControlPath` under `~/.ssh-local/` is used instead).
+
+```bash
+# Interactive shells get aliases (from ~/.bash_aliases):
+dssh host 'cmd'        # = ssh -F ~/.ssh-local/config host
+dscp file host:/path   # = scp -F ~/.ssh-local/config ...
+```
+
+**The agent's `bash` tool is non-interactive — those aliases are NOT loaded.** Use the explicit form:
+
+```bash
+ssh  -F ~/.ssh-local/config host 'cmd'
+scp  -F ~/.ssh-local/config <src> host:<dst>
+```
+
+- Host aliases `host` and `mac` both resolve to `host.docker.internal` (user varies per host machine — check `~/.ssh-local/config` for the active `User` value, key `~/.ssh-local/devbox_jump_ed25519`, `ControlMaster auto` / `ControlPersist 4h`).
+- The config chains `Include ~/.config/devbox-shell/ssh-lan.conf` then `Include ~/.ssh/config`, so LAN targets are reachable too (add `ProxyJump host` to those entries).
+- **Use it for:** enabling/inspecting the host's pi config (`~/.pi/agent/settings.json`), running `evaluate-extension-usage.py` against the host's `~/.pi/agent/sessions/` for a combined host+container metric, or copying host transcripts into the container. The host's pi runs natively there; its palace, sessions, and extensions are separate from the container's.
+
+---
+
+## Cross-Skill Notes
+
+- **mempalace** is for cross-session persistent memory (diary, knowledge graph, drawer storage). OM is for **within-session** context survival across compaction. They complement each other: write a diary entry at session end *and* let OM compact your work-in-progress mid-session.
+- **systematic-debugging** and **test-driven-development** skills pair well with deep-tier forks: a deep fork can carry out a focused debugging investigation or write a failing test suite without polluting your main context.
+- **ci-release-watcher** ships a `scripts/ssh-control-master-setup.sh` helper that configures system-wide SSH ControlMaster in `~/.ssh/config`. That's a separate mechanism from the `ssh-controlmaster` pi extension — they compose, they don't overlap. Use the script for persistent host-wide multiplexing, the extension for per-pi-session remote operation.

rootfs/usr/local/share/pi-devbox/skills/pi-extensions/evaluate-extension-usage.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""Evaluate pi-fork / pi-observational-memory usage from pi session transcripts.
+
+Mines pi's session .jsonl transcripts and reports:
+  - per-tool call counts (highlighting `fork` and `recall`)
+  - per-session fork/recall breakdown
+  - obsmem passive activity: compaction events, observations carried,
+    relevance-tier distribution, tokensBefore
+
+Works on any machine. Point it at one or more session roots; by default it
+scans ~/.pi/agent/sessions (the standard pi location, host or container).
+
+Usage:
+  ./evaluate-extension-usage.py                       # ~/.pi/agent/sessions
+  ./evaluate-extension-usage.py /path/to/sessions ... # explicit roots
+  ./evaluate-extension-usage.py --host HOST /path ... # label a root (for combined host+container runs)
+
+For a true host+container picture, run once per machine (or copy each
+machine's ~/.pi/agent/sessions here) and pass all roots together.
+"""
+import json, sys, os, glob, re, collections, argparse
+
+TIER_RE = re.compile(r'\[(low|medium|high|critical)\]')
+OBS_LINE_RE = re.compile(r'^\[[0-9a-f]{12}\] ', re.M)
+
+
+def walk_tools(x, counter):
+    if isinstance(x, dict):
+        tn = x.get("toolName")
+        if tn:
+            counter[tn] += 1
+        for v in x.values():
+            walk_tools(v, counter)
+    elif isinstance(x, list):
+        for v in x:
+            walk_tools(v, counter)
+
+
+def analyze(roots):
+    files = []
+    for r in roots:
+        if os.path.isfile(r) and r.endswith(".jsonl"):
+            files.append(r)
+        else:
+            files += glob.glob(os.path.join(r, "**", "*.jsonl"), recursive=True)
+    files = sorted(set(files))
+
+    tool_total = collections.Counter()
+    per_session = []
+    compactions = []
+    for f in files:
+        tc = collections.Counter()
+        with open(f, errors="ignore") as fh:
+            for ln in fh:
+                ln = ln.strip()
+                if not ln:
+                    continue
+                try:
+                    o = json.loads(ln)
+                except Exception:
+                    continue
+                walk_tools(o, tc)
+                if o.get("type") == "compaction":
+                    s = o.get("summary", "") or ""
+                    compactions.append({
+                        "file": os.path.basename(f),
+                        "tokensBefore": o.get("tokensBefore"),
+                        "observations": len(OBS_LINE_RE.findall(s)),
+                        "tiers": dict(collections.Counter(TIER_RE.findall(s))),
+                    })
+        tool_total.update(tc)
+        per_session.append((os.path.basename(f)[:10], tc.get("fork", 0),
+                            tc.get("recall", 0), sum(tc.values())))
+    return files, tool_total, per_session, compactions
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("roots", nargs="*",
+                    default=[os.path.expanduser("~/.pi/agent/sessions")])
+    args = ap.parse_args()
+
+    files, tool_total, per_session, comp = analyze(args.roots)
+    if not files:
+        print("No .jsonl transcripts found under:", args.roots, file=sys.stderr)
+        sys.exit(1)
+
+    print(f"=== {len(files)} transcripts under {args.roots} ===\n")
+    print("Tool call totals:")
+    for t, c in tool_total.most_common():
+        mark = "  <== pi-fork" if t == "fork" else ("  <== obsmem recall" if t == "recall" else "")
+        print(f"  {c:6d}  {t}{mark}")
+
+    fk = tool_total["fork"]; rc = tool_total["recall"]
+    fk_sess = sum(1 for p in per_session if p[1])
+    rc_sess = sum(1 for p in per_session if p[2])
+    print(f"\npi-fork:   {fk} calls across {fk_sess} sessions")
+    print(f"recall:    {rc} calls across {rc_sess} sessions"
+          + ("   (!) zero recall over the window — see SKILL.md calibration note" if rc == 0 else ""))
+
+    if comp:
+        tot_obs = sum(c["observations"] for c in comp)
+        tb = [c["tokensBefore"] for c in comp if c["tokensBefore"]]
+        print(f"\nobsmem passive: {len(comp)} compactions, {tot_obs} observations carried"
+              + (f", avg tokensBefore {sum(tb)//len(tb):,}" if tb else ""))
+        agg = collections.Counter()
+        for c in comp:
+            agg.update(c["tiers"])
+        if agg:
+            print("  relevance tiers:", dict(agg))
+    else:
+        print("\nobsmem passive: no compaction events found "
+              "(short sessions, or obsmem not active on these transcripts)")
+
+
+if __name__ == "__main__":
+    main()

rootfs/usr/local/share/terminfo-src/ghostty.terminfo

@@ -0,0 +1,14 @@
+# xterm-ghostty — alias of the maintained ncurses `ghostty` terminfo entry.
+#
+# Ghostty sets TERM=xterm-ghostty by default, but the ncurses terminfo
+# database (Debian: ncurses-term) ships the entry under the name `ghostty`
+# only — there is no `xterm-ghostty` alias, and no distro packages one. This
+# thin alias makes xterm-ghostty resolve to the same upstream-maintained
+# capability set, so SSH sessions from a Ghostty terminal work without
+# vendoring Ghostty's full (Zig-generated) terminfo here.
+#
+# `use=ghostty` is resolved by `tic` at compile time against the base
+# `ghostty` entry from ncurses-term (installed in Dockerfile.base before the
+# compile step). Compiled with `tic -x`.
+xterm-ghostty|Ghostty terminal emulator (xterm-ghostty alias),
+	use=ghostty,

scripts/check-base-hash.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# check-base-hash.sh — guard the base-rebuild invariant.
+#
+# Every floating `ARG *_REF` consumed by Dockerfile.base MUST be folded
+# into the base_tag hash in the docker-publish workflow. Otherwise a
+# ref-only change to that dependency does not change the base hash, the
+# Docker Hub probe finds the old base tag, and the base is NOT rebuilt —
+# the dependency fix silently fails to land. This is the v1.1.2-class
+# staleness footgun (then it was mempalace-toolkit; this guard stops the
+# next one before it ships).
+#
+# Runs in CI (base-decide job) and locally:  bash scripts/check-base-hash.sh
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+WF=".gitea/workflows/docker-publish.yml"
+DF="Dockerfile.base"
+
+# Extract the hash-compute block: the `HASH=$( … ) | sha256sum | cut`
+# brace-group in the "Compute base tag" step. This lives in a separate
+# file from the workflow, so scanning $WF here is free of the self-match
+# hazard an inline workflow step would have.
+block=$(awk '/HASH=\$\(/{f=1} f{print} f && /cut -c1-12/{exit}' "$WF")
+if [ -z "$block" ]; then
+  echo "::error::could not locate the HASH=\$( … ) | sha256sum block in $WF"
+  exit 1
+fi
+
+refs=$(grep -oE '^ARG [A-Z0-9_]+_REF' "$DF" | awk '{print $2}' | sort -u)
+fail=0
+for r in $refs; do
+  lc=$(printf '%s' "$r" | tr '[:upper:]' '[:lower:]')
+  if ! printf '%s' "$block" | grep -q "outputs.$lc"; then
+    echo "::error::Dockerfile.base declares '$r' but it is NOT folded into the base_tag hash in $WF."
+    echo "::error::Add  echo \"\${{ needs.resolve-versions.outputs.$lc }}\"  inside the HASH=\$( … ) | sha256sum block, or a $r-only change will silently fail to rebuild the base."
+    fail=1
+  fi
+done
+
+if [ "$fail" = 0 ]; then
+  echo "OK: all Dockerfile.base *_REF args are folded into base_tag (${refs:-none})."
+fi
+exit $fail

scripts/check-workflow-shell.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Gitea-accurate guard against the recurring "bash syntax under the default
+# sh/dash shell" footgun (ed49b8d resolve-versions; b7197e8 promote-base-latest,
+# run 418).
+#
+# WHY A CUSTOM CHECK AND NOT JUST actionlint:
+#   actionlint models *GitHub* Actions, whose default `run` shell is bash. It
+#   therefore assumes a step that omits `shell:` runs under bash, and does NOT
+#   flag `set -o pipefail` there. Gitea Actions' default is `sh` (dash), so the
+#   exact bug we hit (omit `shell:`, use bash syntax) is invisible to actionlint.
+#   actionlint only fires when a step *explicitly* declares `shell: sh`.
+#
+# THE INVARIANT THIS ENFORCES:
+#   Every `run:` step in every .gitea/workflows/*.yml must resolve to an
+#   effective shell of `bash` — via the step's own `shell:`, a job-level
+#   `defaults.run.shell`, or a workflow-level `defaults.run.shell`. Any step
+#   that would fall through to Gitea's `sh` default is a FAILURE, because a
+#   future author adding bash syntax to it fails silently in CI.
+#
+# Pair this with actionlint (which catches explicit `shell: sh` + bash syntax,
+# expression errors, and much else). Together they cover the class on Gitea.
+set -euo pipefail
+
+WF_DIR="${1:-.gitea/workflows}"
+
+python3 - "$WF_DIR" <<'PY'
+import sys, glob, os
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("ERROR: python3 yaml module missing (apt install python3-yaml)\n")
+    sys.exit(2)
+
+wf_dir = sys.argv[1]
+files = sorted(glob.glob(os.path.join(wf_dir, "*.yml")) + glob.glob(os.path.join(wf_dir, "*.yaml")))
+if not files:
+    sys.stderr.write(f"ERROR: no workflow files under {wf_dir}\n")
+    sys.exit(2)
+
+problems = []
+for f in files:
+    with open(f) as fh:
+        doc = yaml.safe_load(fh) or {}
+    wf_shell = (((doc.get("defaults") or {}).get("run") or {}).get("shell"))
+    jobs = doc.get("jobs") or {}
+    for jname, job in jobs.items():
+        job = job or {}
+        job_shell = (((job.get("defaults") or {}).get("run") or {}).get("shell"))
+        steps = job.get("steps") or []
+        for i, step in enumerate(steps):
+            step = step or {}
+            if "run" not in step:
+                continue  # `uses:` steps have no shell
+            eff = step.get("shell") or job_shell or wf_shell or "sh"  # Gitea default = sh
+            if eff != "bash":
+                name = step.get("name") or f"step[{i}]"
+                problems.append(f"{f}: job '{jname}' / '{name}': effective shell = '{eff}' (Gitea default is sh; declare shell: bash or a bash default)")
+
+if problems:
+    sys.stderr.write("Workflow shell guard FAILED — bash default not guaranteed:\n")
+    for p in problems:
+        sys.stderr.write(f"  - {p}\n")
+    sys.exit(1)
+print(f"Workflow shell guard OK — all run: steps in {len(files)} workflow file(s) resolve to bash.")
+PY

scripts/recreate-sanity-check.sh

@@ -6,8 +6,8 @@
 #     version is supplied — see the version note below)
 #   - Persisted named volumes survived (~/.pi config, shell history, zoxide,
 #     nvim data, uv cache, ssh-local)
-#   - pi runtime wiring is intact: keybindings symlink, ≥4 extensions, the
-#     mempalace.ts bridge, settings.json, and the pi-fork /
+#   - pi runtime wiring is intact: keybindings symlink, AGENTS.md symlink,
+#     ≥4 extensions, the mempalace.ts bridge, settings.json, and the pi-fork /
 #     pi-observational-memory / (studio variant) pi-studio package registrations
 #   - Shell defaults re-seeded from /etc/skel-devbox
 #   - /tmp/sshcm exists with mode 700 (ssh ControlMaster dir)
@@ -157,6 +157,14 @@ else
   fail "~/.pi/agent/keybindings.json missing or not a symlink"
 fi
 
+# global AGENTS.md symlink (pi-toolkit) — global instructions loaded by pi at
+# every start (directs the agent to read the pi-extensions skill at session start)
+if [ -L "$HOME/.pi/agent/AGENTS.md" ]; then
+  pass "~/.pi/agent/AGENTS.md symlink (pi-toolkit)"
+else
+  fail "~/.pi/agent/AGENTS.md missing or not a symlink"
+fi
+
 # extensions deployed (pi-extensions) — expect ≥4 *.ts
 EXT_COUNT=$(ls -1 "$HOME"/.pi/agent/extensions/*.ts 2>/dev/null | wc -l | tr -d ' ')
 if [ "$EXT_COUNT" -ge 4 ]; then
@@ -179,6 +187,18 @@ else
   fail "~/.pi/agent/settings.json missing"
 fi
 
+# settings.json merge: the entrypoint deep-merges new template keys into a
+# preserved settings.json on every start, so config added in an image upgrade
+# (e.g. the observational-memory / pi-fork blocks) reaches existing volumes.
+# Assert those blocks are present and that the file is still valid JSON.
+if command -v jq >/dev/null 2>&1 && [ -f "$HOME/.pi/agent/settings.json" ]; then
+  if jq -e 'has("observational-memory") and has("pi-fork")' "$HOME/.pi/agent/settings.json" >/dev/null 2>&1; then
+    pass "settings.json has observational-memory + pi-fork blocks (template merge)"
+  else
+    fail "settings.json missing observational-memory and/or pi-fork blocks (template merge did not land)"
+  fi
+fi
+
 # pi package registrations (pi install <local-path> → recorded in settings.json)
 if [ -f "$HOME/.pi/agent/settings.json" ]; then
   for pkg in pi-fork pi-observational-memory; do
@@ -214,6 +234,16 @@ else
   fail "~/.bash_aliases missing"
 fi
 
+# History flush must survive shell nesting. The DEVBOX_HIST_SET guard must NOT
+# be exported: if it leaks into child processes, nested shells (esp. tmux
+# panes) skip installing `history -a` and lose in-memory history on abrupt
+# termination. Assert a child login shell still wires up the per-prompt flush.
+if bash -lic 'bash -lic "case \"\$PROMPT_COMMAND\" in *\"history -a\"*) exit 0;; *) exit 1;; esac"' </dev/null >/dev/null 2>&1; then
+  pass "nested shell installs 'history -a' (DEVBOX_HIST_SET not exported)"
+else
+  fail "nested shell missing 'history -a' — DEVBOX_HIST_SET leaking to children?"
+fi
+
 if [ -f "$HOME/.inputrc" ]; then
   pass "~/.inputrc exists"
 else

scripts/smoke-test.sh

@@ -6,6 +6,10 @@
 # Verifies:
 #   - pi binary present and (if EXPECTED_PI_VERSION set) matches CI's resolved version
 #   - new v1.0.0 base additions (pandoc, graphviz, imagemagick, yq, tealdeer)
+#   - typst PDF engine for pandoc (Unreleased) — `pandoc --pdf-engine=typst`
+#   - non-modal editors nano + micro (alongside nvim)
+#   - terminfo for modern emulators: xterm-kitty, xterm-ghostty, wezterm,
+#     alacritty, foot (kitty-terminfo + ncurses-term + compiled ghostty alias)
 #   - tmux 0-indexing baked in /etc/tmux.conf (required for pi-studio variants)
 #   - pi-toolkit cloned at /opt/pi-toolkit
 #   - pi-extensions cloned at /opt/pi-extensions
@@ -15,6 +19,8 @@
 #   - mempalace bridge symlink present
 #   - settings.json bootstrapped
 #   - pi-fork + pi-observational-memory registered via `pi install`
+#   - pi-devbox-version command present + wraps the build manifest correctly
+#     (human, --json, --quiet)
 #   - (studio variant only, auto-detected) pi-studio cloned + prebuilt
 #     client bundle present + registered via `pi install`
 #   - image size within threshold
@@ -24,11 +30,15 @@ set -euo pipefail
 IMAGE="${1:?usage: $0 <image>}"
 PASS=0; FAIL=0
 # pi-devbox v1.0.0 (decoupled from opencode-devbox) added pandoc, graphviz,
-# imagemagick, yq, tealdeer, and a baked /etc/tmux.conf. Local arm64 build
-# observed 3.20 GB. CI amd64 builds may differ slightly; threshold below
-# carries +300 MB margin to absorb arch differences without false reds.
-# Tighten in a follow-up release once amd64 actuals are observed in CI logs.
-SIZE_THRESHOLD_MB=3500
+# imagemagick, yq, tealdeer, a baked /etc/tmux.conf, and the non-modal
+# editors nano + micro (~15 MB combined). v1.6.0 baked in agent-browser +
+# Playwright Chromium (~291 MB net after dropping the unused headless-shell
+# build), which lifted the baseline. CI amd64 actuals observed on run 512
+# (v1.6.1): 3411 MB non-studio, 3574 MB studio. Threshold below carries
+# ~225 MB margin above the studio number to absorb minor arch/build-cache
+# differences and small future growth without false reds, while still
+# catching an unexpected +GB regression.
+SIZE_THRESHOLD_MB=3800
 
 run() {
   local label="$1"; local cmd="$2"
@@ -71,15 +81,43 @@ run "git"             "git --version"
 run "aws"             "aws --version"
 run "uv"              "uv --version"
 run "nvim"            "nvim --version"
+run "nano"            "nano --version"
+run "micro"           "micro --version"
+run "kitty-terminfo"  "infocmp -x xterm-kitty >/dev/null 2>&1"
+run "terminfo: modern emulators (ncurses-term)" 'for t in wezterm alacritty foot ghostty st-256color; do infocmp -x "$t" >/dev/null 2>&1 || exit 1; done'
+run "terminfo: xterm-ghostty alias (tic)" "infocmp -x xterm-ghostty >/dev/null 2>&1"
+run "nvim true-colour default (sysinit.vim)" "nvim --headless -c 'lua os.exit(vim.o.termguicolors and 0 or 1)'"
 run "mempalace-mcp"   "mempalace-mcp --help"
 # v1.0.0 base additions — verify presence and basic functionality.
 run "pandoc"          "pandoc --version"
+run "typst"           "typst --version"
+run "pandoc+typst PDF engine" "printf '# hi\n' | pandoc --pdf-engine=typst -o /tmp/_smoke.pdf - && test -s /tmp/_smoke.pdf; rm -f /tmp/_smoke.pdf"
 run "graphviz (dot)"  "dot -V"
 run "imagemagick"     "magick --version"
-run "yq"              "yq --version"
+run "yq (mikefarah v4)" "yq --version | grep -qE 'mikefarah.*version v4'"
 run "tldr (tealdeer)" "tldr --version"
 run "socat"           "socat -V"
 run "studio-expose helper" "test -x /usr/local/bin/studio-expose"
+run "image-baked pi-devbox-environment skill" \
+    "test -f /usr/local/share/pi-devbox/skills/pi-devbox-environment/SKILL.md"
+run "global-AGENTS append snippet present" \
+    "test -f /usr/local/share/pi-devbox/pi-global-AGENTS.append.md"
+run "pi-devbox block merged into pi-global-AGENTS.md" \
+    "grep -q 'pi-devbox:managed-block' /opt/pi-toolkit/pi-global-AGENTS.md"
+run "mempalace session-start pointer merged into global AGENTS.md" \
+    "grep -q 'load the mempalace skill' /opt/pi-toolkit/pi-global-AGENTS.md"
+# Vendored fallback skills (so a no-skillset container still resolves the
+# AGENTS.md 'read the pi-extensions skill' pointer).
+run "image-baked pi-extensions fallback skill" \
+    "test -f /usr/local/share/pi-devbox/skills/pi-extensions/SKILL.md"
+run "pi-extensions skill ships its helper" \
+    "test -f /usr/local/share/pi-devbox/skills/pi-extensions/evaluate-extension-usage.py"
+run "image-baked mempalace fallback skill" \
+    "test -f /usr/local/share/pi-devbox/skills/mempalace/SKILL.md"
+# Layered freshness: when the pinned pi-extensions clone carries the skill, the
+# baked copy must be the fresh package copy (Option 1), not the stale snapshot.
+run "pi-extensions skill refreshed from package when present" \
+    "if [ -f /opt/pi-extensions/skill/SKILL.md ]; then cmp -s /opt/pi-extensions/skill/SKILL.md /usr/local/share/pi-devbox/skills/pi-extensions/SKILL.md; else true; fi"
 
 # ── tmux 0-indexing (required for pi-studio variants) ─────────────────
 echo ""
@@ -113,6 +151,38 @@ else
   echo "  ℹ️   pi-studio not present (non-studio variant) — skipping studio clone checks"
 fi
 
+# ── Build provenance (manifest + OCI labels) ─────────────────────────
+echo ""
+echo "── Build provenance ──"
+run "/etc/pi-devbox/build-manifest.json present" \
+    "test -f /etc/pi-devbox/build-manifest.json"
+run_expect "manifest records pi-extensions component" \
+    "cat /etc/pi-devbox/build-manifest.json" '"pi-extensions"'
+run_expect "manifest records pi_version" \
+    "cat /etc/pi-devbox/build-manifest.json" '"pi_version"'
+# Every component must be a resolved commit (or null for pi-studio in the
+# non-studio variant) — 'unknown' means a clone silently failed to resolve.
+run "manifest has no unresolved ('unknown') components" \
+    "! grep -q '\"unknown\"' /etc/pi-devbox/build-manifest.json"
+# pi-devbox-version wraps the manifest into a human-first command (this
+# PR); verify the binary is present, executable, and both output modes work.
+run "pi-devbox-version binary present + executable" \
+    "test -x /usr/local/bin/pi-devbox-version"
+run_expect "pi-devbox-version human output shows release tag" \
+    "pi-devbox-version" "pi-devbox "
+run_expect "pi-devbox-version --json round-trips the manifest" \
+    "pi-devbox-version --json" '"release_tag"'
+run_expect "pi-devbox-version --quiet is a compact one-liner" \
+    "pi-devbox-version --quiet | wc -l" "1"
+# OCI labels live in the image config, not the container fs — inspect them
+# from the host docker rather than via `docker run`.
+LBL=$(docker inspect --format '{{ index .Config.Labels "se.jordbo.pi-devbox.pi-extensions-ref" }}' "$IMAGE" 2>/dev/null || true)
+if [ -n "$LBL" ] && [ "$LBL" != "<no value>" ]; then
+  printf "  ✅  OCI label se.jordbo.pi-devbox.pi-extensions-ref=%s\n" "$LBL"; PASS=$((PASS+1))
+else
+  printf "  ❌  OCI label se.jordbo.pi-devbox.pi-extensions-ref missing or empty\n"; FAIL=$((FAIL+1))
+fi
+
 # ── Runtime deployment (needs entrypoint to run) ──────────────────────
 echo ""
 echo "── Runtime deployment ──"
@@ -134,6 +204,9 @@ for i in $(seq 1 45); do
   if docker exec "$CID" sh -c '
        test -L /home/developer/.pi/agent/keybindings.json && \
        test -L /home/developer/.pi/agent/extensions/mempalace.ts && \
+       test -L /home/developer/.agents/skills/pi-devbox-environment && \
+       test -L /home/developer/.agents/skills/pi-extensions && \
+       test -L /home/developer/.agents/skills/mempalace && \
        count=$(ls -1 /home/developer/.pi/agent/extensions/*.ts 2>/dev/null | wc -l) && \
        [ "$count" -ge 4 ]
      ' >/dev/null 2>&1; then
@@ -155,6 +228,9 @@ exec_test "keybindings.json (pi-toolkit)"         'test -L $HOME/.pi/agent/keybi
 exec_test "extensions ≥ 4 (pi-extensions)"        'count=$(ls -1 $HOME/.pi/agent/extensions/*.ts 2>/dev/null | wc -l); [ $count -ge 4 ] && echo "$count extensions"'
 exec_test "mempalace.ts bridge"                    'test -L $HOME/.pi/agent/extensions/mempalace.ts && echo ok'
 exec_test "settings.json bootstrapped"             'test -f $HOME/.pi/agent/settings.json && echo ok'
+exec_test "pi-devbox-environment skill linked"     'test -L $HOME/.agents/skills/pi-devbox-environment && test -f $HOME/.agents/skills/pi-devbox-environment/SKILL.md && echo ok'
+exec_test "pi-extensions skill linked (fallback)"  'test -L $HOME/.agents/skills/pi-extensions && test -f $HOME/.agents/skills/pi-extensions/SKILL.md && echo ok'
+exec_test "mempalace skill linked (fallback)"      'test -L $HOME/.agents/skills/mempalace && test -f $HOME/.agents/skills/mempalace/SKILL.md && echo ok'
 
 # pi-fork + pi-observational-memory are registered by entrypoint-user.sh via
 # `pi install /opt/<pkg>`, which runs slightly after the keybindings marker.