Fix: developer-writable npm prefix for pi install

NPM_CONFIG_PREFIX is now /home/developer/.pi/npm-global, with that
prefix's bin/ prepended to PATH. Without this, 'pi install npm:<pkg>'
(and any 'npm install -g') by the developer user would EACCES against
the system prefix (/usr).

The new prefix lives on the devbox-pi-config named volume, so:
  - User-installed pi packages (themes, skills, extensions) survive
    container recreate AND image rebuild, complementing pi's auto-
    restore from settings.json with one less cold-start step.
  - A user-driven 'npm install -g @mariozechner/pi-coding-agent' lands
    on the volume and wins over the baked pi via PATH order.

Build-time 'npm install -g' calls (opencode, pi, oh-my-opencode-slim)
are unaffected: the new ENVs are declared after those steps in the
Dockerfile, so the baked binaries still install to /usr at build time
and are not shadowed by the volume mount at runtime.

Verified end-to-end with a Bun-driven smoke test: as developer,
'npm install -g cowsay' inside the container succeeds, the binary
lands on PATH, and survives a fresh container against the same volume.

DOCKER_HUB.md regenerated (24997/25000 bytes, 3-byte headroom — was
138 before; future README additions to the persistence section need
to trim something else first).

Docs updated: Dockerfile inline comments, README persistence section,
AGENTS install contract, DOCKER_HUB persistence table, .env.example
notes, CHANGELOG Unreleased entry.

Dockerfile

@@ -293,10 +293,14 @@ RUN if [ "${INSTALL_OPENCODE}" = "true" ]; then \
 # start so symlinks land under ~/.pi/agent/ on the named volume.
 #
 # Pi version is pinned by PI_VERSION (default: latest at build time).
-# `pi update` inside the container would write to the npm global
-# prefix, which is not on a volume — so updates do NOT persist across
-# `--rm` containers. Same contract as OPENCODE_VERSION: rebuild the
-# image to upgrade pi.
+# The baked pi binary lives at /usr/bin/pi (system npm prefix); the
+# user-writable NPM_CONFIG_PREFIX (~/.pi/npm-global, set further down)
+# is only consulted by `pi install npm:<pkg>` and `npm install -g` at
+# runtime — it does NOT shadow the baked pi unless the user does
+# `npm install -g @mariozechner/pi-coding-agent` themselves, in which
+# case the user-installed copy on the volume wins via PATH order. Same
+# contract as OPENCODE_VERSION otherwise: rebuild the image to upgrade
+# the baked pi.
 ARG INSTALL_PI=false
 ARG PI_VERSION=latest
 ARG PI_TOOLKIT_REF=main
@@ -418,6 +422,25 @@ print('chromadb embedding model warmed: all-MiniLM-L6-v2')" && \
       ls -lh /home/${USER_NAME}/.cache/chroma/onnx_models/all-MiniLM-L6-v2/ ; \
     fi
 
+# ── User-writable npm global prefix on the devbox-pi-config volume ──
+# By default npm's global prefix is /usr (writable only by root) so any
+# `pi install npm:<pkg>` or `npm install -g <pkg>` invoked by the
+# developer user would EACCES. Pointing the prefix into ~/.pi places
+# user-installed packages on the named volume, which means they survive
+# container recreation AND image rebuilds (complementing pi's auto-
+# restore from settings.json with one less cold-start step).
+#
+# These ENVs land AFTER all build-time `npm install -g` calls
+# (opencode, pi, oh-my-opencode-slim) so those still install to /usr at
+# build time. They take effect for every runtime invocation regardless
+# of shell init: docker compose run/exec, login shells, non-interactive
+# commands. npm auto-creates the prefix directory on first install.
+#
+# Harmless when INSTALL_PI=false (and no named volume mounted at ~/.pi):
+# the dir just lives on the container's writable layer.
+ENV NPM_CONFIG_PREFIX=/home/${USER_NAME}/.pi/npm-global
+ENV PATH="/home/${USER_NAME}/.pi/npm-global/bin:${PATH}"
+
 # ── Shell defaults (bash history, aliases, readline) ─────────────────
 # Shipped under /etc/skel-devbox/ rather than copied directly to the
 # user's home. The entrypoint copies them to /home/developer/ only if