Rewrite DOCKER_HUB.md as a hand-maintained slim template

The previous derive-from-README mechanism (split_sections, SECTION_RULES,
TRIM_SUBSECTIONS, REPLACEMENTS) generated a 24 997 byte Hub doc with
3 byte headroom against the 25 kB Hub limit. Every README addition
forced a 'trim something else first' exercise, and the resulting copy
was awkward (terse, repetitive linkbacks injected mid-section).

Replace with a single hand-maintained HUB_TEMPLATE constant. The Hub
doc is now intentionally slim (~5.5 kB, ~78 percent headroom) and
focuses on what Hub readers actually need: elevator pitch, image
variants, quick start, what's inside, auth, persistence, and link-outs
to the gitea README for depth.

Trade-off: when image-variants or quick-start change, update
HUB_TEMPLATE here too. That coupling is now explicit and local rather
than spread across SECTION_RULES + REPLACEMENTS + TRIM machinery,
and most README edits no longer require regenerating DOCKER_HUB.md
at all.

Generator simplified from 323 lines to 199 lines (270-line net
reduction across the script + DOCKER_HUB.md). README and Hub doc are
now independent surfaces.

CHANGELOG and AGENTS updated to reflect the new coupling. Release-day
checklist tightened: README -> regenerate DOCKER_HUB ONLY if
HUB_TEMPLATE changed -> promote CHANGELOG -> grep AGENTS -> commit
-> tag.

AGENTS.md

@@ -11,9 +11,9 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d
 - `entrypoint-user.sh` — runs as developer: git config, opencode.jsonc generation (delegated to `generate-config.py`), pi-toolkit + pi-extensions deploy (when pi installed), pi settings.json bootstrap, mempalace pi-bridge symlink, skillset auto-deploy from mounted skillset repo, OMOS setup.
 - `rootfs/usr/local/lib/opencode-devbox/generate-config.py` — generates `~/.config/opencode/opencode.jsonc` from env vars. Never overwrites an existing config (checks both `.json` and `.jsonc`). Auto-registers MCP servers for detected tools (mempalace via `mempalace-mcp`, gitea-mcp, context7 remote endpoint).
 - `scripts/smoke-test.sh` — post-build image verification. Asserts binary presence, opencode startup, entrypoint correctness, config generation idempotency, and image size thresholds. Used by both CI workflows.
-- `scripts/generate-dockerhub-md.py` — generates `DOCKER_HUB.md` from `README.md` using explicit section rules. `--check` fails if the committed file is out of sync (enforced by the `validate` workflow).
-- `DOCKER_HUB.md` — **auto-generated** from README. Do not edit directly. Pushed to Docker Hub description via CI API call. Must stay under 25 kB. Short description field must be ≤100 bytes.
-- `README.md` — authoritative source documentation. Sections are selected/dropped/replaced for DOCKER_HUB.md per `SECTION_RULES` in `scripts/generate-dockerhub-md.py`.
+- `scripts/generate-dockerhub-md.py` — generates `DOCKER_HUB.md` from a hand-maintained `HUB_TEMPLATE` constant. `--check` fails if the committed file is out of sync (enforced by the `validate` workflow).
+- `DOCKER_HUB.md` — **auto-generated** from `HUB_TEMPLATE` in `scripts/generate-dockerhub-md.py`. Do not edit directly. Pushed to Docker Hub description via CI API call. Must stay under 25 kB. Short description field must be ≤100 bytes.
+- `README.md` — authoritative source documentation for everything in this repo. Independent of `DOCKER_HUB.md`: the Hub doc is hand-maintained in the generator's `HUB_TEMPLATE` and intentionally slim, linking back to the gitea README for depth.
 - `.gitea/workflows/validate.yml` — lightweight amd64 build + smoke test on push to main and PRs. Also runs the DOCKER_HUB.md sync check.
 - `.gitea/workflows/docker-publish.yml` — CI pipeline on tag push: smoke-test each variant on amd64, then full multi-arch (amd64 + arm64) build-and-push, then update Docker Hub description.
 
@@ -35,12 +35,12 @@ When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile`
 - **entrypoint.sh volume ownership loop** — when adding a new named volume mount point, add it to the `for dir in ...` loop in `entrypoint.sh` so root-owned volumes get chowned on startup. The loop writes a `.devbox-owner` sentinel after a successful chown so subsequent starts skip the recursive walk. Users should not touch these files.
 - **Documentation coupling on release** — four docs co-vary and drift in lockstep when not updated together:
   - `README.md` is the source of truth for user-facing build/run/config detail.
-  - `DOCKER_HUB.md` is auto-generated by `scripts/generate-dockerhub-md.py` from README. CI's `--check` run fails if it's stale or any new top-level README section is missing from `SECTION_RULES`. Hard cap: 25 kB Hub limit (current: ~24.9 kB, very tight — trim before adding).
+  - `DOCKER_HUB.md` is auto-generated from `HUB_TEMPLATE` in `scripts/generate-dockerhub-md.py`. CI's `--check` run fails if it's stale. Hub-facing copy is intentionally slim (~5.5 kB, ~78% headroom against the 25 kB Hub limit) — update the template here when image variants, quick-start flow, or the elevator pitch change. README.md no longer feeds into Hub, so README edits do NOT require regenerating DOCKER_HUB.md.
   - `CHANGELOG.md` records every release. When cutting a tag, **promote `## Unreleased` to `## vX.Y.Z[n] — YYYY-MM-DD` BEFORE pushing the tag** so the tag points at a CHANGELOG that names itself. Keep entries reverse-chronological (newest at top, after the `Unreleased` block). Doc-only updates that happen post-tag (Hub description live-patches, README clarifications) get a fresh `## Unreleased` block with a note that they don't trigger a new image build.
   - `AGENTS.md` (this file) carries domain facts that change on structural releases — tag-count statements, CI job lists, install contracts. After any change to `.gitea/workflows/*.yml` or the variant matrix, grep this file for stale numbers (`grep -nE "four|eight|all [0-9]"`).
   - `.env.example` must be hand-updated to match Dockerfile/entrypoint behavior — it is not auto-generated.
 
-  Release-day checklist: README → regenerate DOCKER_HUB.md → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag.
+  Release-day checklist: README → (regenerate DOCKER_HUB.md only if HUB_TEMPLATE changed) → promote CHANGELOG Unreleased → grep AGENTS.md for stale counts → commit → tag → push tag.
 - **GitHub/Gitea-sourced binaries float by default** — gosu, fzf, git-lfs, nvim, bat, eza, zoxide, uv, gitea-mcp, Go, oh-my-opencode-slim all default to `latest`. Each build-time install step reads the `/releases/latest` Location redirect (or the go.dev JSON feed for Go) and derives the concrete version. Use the same `ARCH` case-switch pattern for multi-arch support (amd64/arm64). Intentional pins: `OPENCODE_VERSION` (drives the image tag), `NODE_VERSION=22` (major pin), `DEBIAN_VERSION=trixie-slim` (OS base). Adding a new upstream tool: follow the existing floated-version pattern, don't hardcode a specific tag.
 - **Resolved versions are logged by the smoke test** — `scripts/smoke-test.sh` prints a "Resolved component versions" table as its first step. CI logs always capture what got baked into a given image even when ARGs default to `latest`.
 - **Shell scripts use `set -euo pipefail`** — both entrypoints are strict. Errors in volume chown or SSH permission operations are intentionally suppressed with `|| true`.

CHANGELOG.md

@@ -19,6 +19,11 @@ Image changes (will ship in the next tagged release):
 
 - **Fix:** `pi install npm:<pkg>` (and any `npm install -g`) by the `developer` user no longer EACCES against the system npm prefix. `NPM_CONFIG_PREFIX` is now `/home/developer/.pi/npm-global` and the prefix's `bin/` is prepended to `PATH`. The directory lives on the `devbox-pi-config` named volume, so user-installed pi packages (themes, skills, extensions) survive container recreation and image rebuilds. Build-time `npm install -g` calls (opencode, pi, oh-my-opencode-slim) are unaffected because the new ENVs are declared after those steps in the Dockerfile, so the baked binaries still install to `/usr` and are not shadowed by the volume mount.
 
+Docs-only (the DOCKER_HUB.md change can be patched live to Hub without a CI rebuild; AGENTS.md change is repo-internal):
+
+- **Hub doc rewrite:** `DOCKER_HUB.md` is now generated from a hand-maintained `HUB_TEMPLATE` constant in `scripts/generate-dockerhub-md.py` instead of a section-by-section transformation of `README.md`. Drops from 24 997 bytes (3 byte headroom) to 5 551 bytes (~78% headroom). The old derive-from-README mechanism (`SECTION_RULES`, `TRIM_SUBSECTIONS`, `REPLACEMENTS`, `split_sections`, `trim_subsections`) is gone — README and Hub doc are now independent surfaces. Hub copy stays slim and links out to the gitea README for full depth (build args, multi-user setup, AWS Bedrock walkthrough, MemPalace deep-dive, language-specific dev sections). Trade-off: image-variants table and quick-start flow are now coupled to `HUB_TEMPLATE` and need a manual edit when they change — explicit and local rather than spread across rules.
+- **AGENTS.md:** "Documentation coupling on release" rule updated — README edits no longer require regenerating DOCKER_HUB.md. Release-day checklist tightened.
+
 ## v1.14.41b — 2026-05-08
 
 **Optional pi as second harness.**

DOCKER_HUB.md

@@ -1,10 +1,10 @@
-# opencode-devbox — Docker Hub
+# opencode-devbox
 
 Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.
 
-## Image Variants
+Designed for teams who want a reproducible coding-agent setup that runs the same on every laptop and CI runner — without forcing each developer to install Bun, Node, AWS CLI, mempalace, or maintain shell config drift across machines.
 
-Four image variants are published for each release:
+## Image Variants
 
 | Tag | Description |
 |---|---|
@@ -15,8 +15,6 @@ Four image variants are published for each release:
 
 All variants support `linux/amd64` and `linux/arm64`.
 
-> **NOTE:** This file is auto-generated from `README.md` by `scripts/generate-dockerhub-md.py`. Edit README.md and regenerate rather than editing this file directly.
-
 ## Quick Start
 
 ```bash
@@ -30,9 +28,9 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest
 ```
 
-This drops you straight into opencode with your project mounted at `/workspace`.
+Drops you straight into opencode with your project mounted at `/workspace`.
 
-For an interactive shell first (useful for AWS SSO login):
+For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
 
 ```bash
 docker run -it --rm \
@@ -43,554 +41,55 @@ docker run -it --rm \
   joakimp/opencode-devbox:latest bash
 ```
 
-Then run `opencode` when ready.
+Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
 
-For docker-compose users, see the source repo for `docker-compose.yml` and `.env.example` templates.
+For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
 
-## Features
+## What's Inside
 
-- **Debian trixie** base — glibc, full PTY/terminal support
-- **Configurable providers** — Anthropic, OpenAI, AWS Bedrock via env vars
-- **Host filesystem access** — bind mount any directory as `/workspace`
-- **SSH key forwarding** — git push/pull to private repos
-- **MCP server support** — Node.js included for `npx`-based MCP servers
-- **Non-root user** — runs as `developer` with UID auto-matched to workspace owner (sudo available)
-- **Python via uv** — `uv` package manager included; install Python on demand with `uv python install`
-- **Rust via rustup** — `rustup-init` included; bootstrap Rust on demand with `rustup-init -y`
-- **Optional runtimes** — Python (apt), Go via build args (Node.js always included — required for opencode v1.x)
-- **Multi-agent orchestration** — optional [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) integration via build arg
-- **AWS CLI v2** — built-in SSO/Bedrock authentication with headless device-code flow
-- **Multi-arch** — amd64 and arm64
+- **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
+- **[pi](https://github.com/mariozechner/pi-coding-agent)** *(in `*-with-pi` variants)* — lightweight TUI coding-agent that coexists with opencode and shares the same mempalace install. Includes the `mcp-loader` extension so any local-stdio or remote streamable-HTTP MCP server (searxng, gitea, context7, …) can be added by editing `~/.pi/agent/settings.json`.
+- **[mempalace](https://github.com/MemPalace/mempalace)** — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi.
+- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** *(in `*-omos` variants)* — multi-agent orchestration on top of opencode (council, fallback chains, named agents).
+- **AWS CLI v2** with SSO support, **Node.js LTS**, **Bun** (OMOS variants), **uv** (Python), **gosu** for clean UID/GID adjustment to match your host workspace.
+- **MCP wrappers** for mempalace pre-installed and pre-wired to both harnesses.
 
-## Usage
+## Authentication
 
-### Prerequisites
+The container reads provider credentials from environment variables and host-mounted config:
 
-Bind-mounted directories must exist on the host before starting the container. Docker creates missing directories as root-owned, which causes permission issues.
+- **Anthropic / OpenAI / Groq / others:** set `OPENCODE_PROVIDER` and the corresponding `*_API_KEY` via `-e` or `.env`.
+- **AWS Bedrock (SSO):** mount `~/.aws` from the host, `OPENCODE_PROVIDER=amazon-bedrock`, then `aws sso login` inside the container. Tokens persist across container restarts via the host bind-mount.
+- **OAuth / device-code providers:** auth state lives in opencode's config, which is persisted via the `devbox-opencode-config` named volume.
 
-```bash
-# Required: workspace for your projects
-mkdir -p ~/projects
-```
+Full Bedrock walkthrough (IAM roles, permissions, multi-account setups): see the [AWS Bedrock Authentication](
+https://gitea.jordbo.se/joakimp/opencode-devbox#aws-bedrock-authentication
+) section on gitea.
 
-### Connecting to the container
+## Persistence
 
-From your laptop, SSH into the remote server where Docker is running, then start the container:
-
-```bash
-# 1. SSH into the remote server
-ssh user@remote-server
-
-# 2. Navigate to the project
-cd opencode-devbox
-
-# 3. Start the container with an interactive shell
-docker compose run --rm devbox bash
-
-# You're now inside the container — run commands here
-aws sso login --sso-session <your-sso-session> --use-device-code
-opencode
-```
-
-### Running modes
-
-**Interactive shell** — enter the container, run multiple commands:
-```bash
-docker compose run --rm devbox bash
-```
-
-**Direct to opencode** — skips the shell, launches opencode immediately:
-```bash
-docker compose run --rm devbox
-```
-
-**Background container** — keep it running, attach when needed:
-```bash
-# Start in background
-docker compose up -d
-
-# Attach a shell to the running container
-docker compose exec -u developer devbox bash
-
-# Or run a single command inside it
-docker compose exec -u developer devbox aws --version
-```
-
-> `run` creates a new container (cleaned up with `--rm`). `exec` attaches to an already running one.
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Description | Default |
+| Volume | Mount | Survives |
 |---|---|---|
-| `OPENCODE_PROVIDER` | LLM provider (`anthropic`, `openai`, `amazon-bedrock`) | `anthropic` |
-| `OPENCODE_MODEL` | Model override | Provider default |
-| `ANTHROPIC_API_KEY` | Anthropic API key | — |
-| `OPENAI_API_KEY` | OpenAI API key | — |
-| `AWS_REGION` | AWS region for Bedrock | `us-east-1` |
-| `AWS_PROFILE` | AWS SSO profile name | `default` |
-| `GIT_USER_NAME` | Git commit author name | — |
-| `GIT_USER_EMAIL` | Git commit author email | — |
-| `WORKSPACE_PATH` | Host path to mount | `.` |
-| `SSH_KEY_PATH` | Host SSH key directory | `~/.ssh` |
-| `USER_UID` | Override container user UID | Auto-detect from `/workspace` |
-| `USER_GID` | Override container user GID | Auto-detect from `/workspace` |
-| `LANG` | System locale | `en_US.UTF-8` |
-| `LANGUAGE` | Language priority list | `en_US:en` |
-| `LC_ALL` | Override all locale settings | `en_US.UTF-8` |
-| `EDITOR` | Default text editor | `nvim` |
-| `ENABLE_OMOS` | Enable oh-my-opencode-slim multi-agent orchestration | `false` |
-| `OMOS_TMUX` | Enable tmux pane integration for OMOS | `false` |
-| `OMOS_SKILLS` | Install OMOS recommended skills on first run | `true` |
-| `OMOS_RESET` | Force regenerate OMOS config on next start | `false` |
-| `SKILLSET_CONTAINER_PATH` | Path to skillset repo inside container (for auto-deploy when not at /workspace/skillset) | Auto-detect |
+| `devbox-opencode-config` | `~/.config/opencode` | container recreate, image rebuild |
+| `devbox-pi-config` | `~/.pi` | container recreate, image rebuild — incl. user-installed pi packages via `pi install` (`NPM_CONFIG_PREFIX` points into the volume) |
+| `devbox-palace` (uncomment) | `~/.mempalace` | container recreate, image rebuild — palace data is precious, treat as primary storage |
+| `devbox-chroma-cache` | `~/.cache/chroma` | container recreate (model cache, disposable — re-downloads in seconds) |
 
-### Custom opencode config
+Workspace bind-mount (`/workspace`) is your project directory on the host, so source code is never inside the container.
 
-Opencode configuration is persisted automatically via the named volume `devbox-opencode-config`. This volume is mounted at `/home/developer/.config/opencode` by default — no host directory setup required. All changes to `opencode.jsonc`, skills, and (on the OMOS variant) `oh-my-opencode-slim.json` survive container recreation.
+Full persistence reference, including multi-user (`SIGNUM`) isolation and host bind-mount alternatives: see the [README on gitea](https://gitea.jordbo.se/joakimp/opencode-devbox#persistence).
 
-When an existing `opencode.jsonc` is found in the volume, the `OPENCODE_PROVIDER` auto-config is skipped.
+## Where to Go Next
 
-**Alternative: host bind-mount** — if you specifically want to share config from the host (e.g. to version-control it or sync across machines), replace the named volume with a bind mount:
+- **Full README** with build args, every feature in detail, troubleshooting: <https://gitea.jordbo.se/joakimp/opencode-devbox>
+- **CHANGELOG** for version history: <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/CHANGELOG.md>
+- **Issues / source / docker-compose templates:** <https://gitea.jordbo.se/joakimp/opencode-devbox>
+- **Agent-facing internals** (for future maintainers / coding agents working in the repo): <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/AGENTS.md>
 
-```yaml
-volumes:
-  - ~/.config/opencode:/home/developer/.config/opencode
-```
+## License
 
-> **Portability note:** The mounted config runs inside a Linux container. Any absolute paths inside `opencode.jsonc` (for example, host-specific `plugin` entries like `file:///usr/local/lib/node_modules/...` or `file:///opt/homebrew/...`) will not resolve inside the container. Prefer bare package specifiers (e.g. `"oh-my-opencode-slim"`) that resolve via `node_modules` lookup, which works on both macOS and Linux hosts.
+MIT. See <https://gitea.jordbo.se/joakimp/opencode-devbox/src/branch/main/LICENSE>.
 
-### Custom skills
+---
 
-Skills are deployed automatically from a skillset repo on container start. The entrypoint detects the skillset location in this order:
-
-1. `SKILLSET_CONTAINER_PATH` env var (explicit path to skillset repo inside container)
-2. `~/skillset` mount (if present)
-3. `/workspace/skillset` fallback (if your workspace contains a `skillset/` directory)
-
-When a skillset repo is detected, its skills are symlinked into `~/.agents/skills/` automatically. No manual configuration needed.
-
-> **Warning:** Do not bind-mount a host `~/.agents/skills` directory directly into the container. This conflicts with the symlink-based auto-deploy mechanism and causes broken skill references.
-
-### Neovim configuration
-
-The image includes neovim 0.12 with `EDITOR=nvim` set by default. To use your own neovim config (and have plugins auto-install via lazy.nvim on first start), mount it from the host:
-
-```yaml
-volumes:
-  - ~/.config/nvim:/home/developer/.config/nvim:ro
-```
-
-### Python development with uv
-
-The image includes Python 3.13 (from Debian Trixie) and [uv](https://docs.astral.sh/uv/), a fast Python package manager that replaces pip, venv, and pyenv:
-
-```bash
-# Python 3.13 is available out of the box
-python3 --version
-
-# Use uv for package management
-uv venv
-uv pip install -r requirements.txt
-
-# Or use uv's project workflow (reads pyproject.toml)
-uv sync
-
-# Run a Python script
-uv run python script.py
-
-# Install standalone Python tools
-uvx ruff check .
-
-# Install a newer Python version (persists with devbox-uv volume)
-uv python install 3.14
-```
-
-Python installations are stored in `~/.local/share/uv/`. To persist them across container restarts, add the `devbox-uv` named volume to your `docker-compose.yml`:
-
-```yaml
-volumes:
-  - devbox-uv:/home/developer/.local/share/uv
-
-volumes:
-  devbox-uv:
-```
-
-Project virtual environments (`.venv`) are stored in your workspace directory and persist automatically via the `/workspace` bind mount.
-
-### Rust development with rustup
-
-The image includes `rustup-init`, the Rust toolchain installer. Rust is not pre-installed but can be bootstrapped on demand:
-
-```bash
-# One-time setup: install Rust toolchain (~300MB, persists with volumes)
-rustup-init -y
-source ~/.cargo/env
-
-# Now use Rust normally
-cargo new my-project
-cargo build
-cargo run
-```
-
-To persist Rust toolchains and cargo data across container restarts, add named volumes to your `docker-compose.yml`:
-
-```yaml
-volumes:
-  - devbox-rustup:/home/developer/.rustup
-  - devbox-cargo:/home/developer/.cargo
-
-volumes:
-  devbox-rustup:
-  devbox-cargo:
-```
-
-### JavaScript and TypeScript
-
-The base image includes **Node.js 22** and **npm** — sufficient for most JavaScript and TypeScript development:
-
-```bash
-# Initialize a new project
-npm init -y
-
-# Install dependencies
-npm install
-
-# Run TypeScript (via tsx, ts-node, etc.)
-npx tsx src/index.ts
-
-# Use npx for one-off tools
-npx tsc --init
-```
-
-The OMOS image variant also includes **Bun**, a faster JavaScript runtime and package manager:
-
-```bash
-bun init
-bun install
-bun run src/index.ts
-```
-
-Node modules are stored in your project directory under `/workspace` and persist automatically.
-
-### VS Code integration
-
-VS Code can connect directly to a running opencode-devbox container for a full IDE experience with IntelliSense, debugging, and extensions running inside the container.
-
-**Local Docker (Docker running on your workstation):**
-
-1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
-2. Start the container: `docker compose up -d`
-3. In VS Code: `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container" → select `opencode-devbox`
-
-**Remote Docker (Docker running on a remote server, e.g. via SSH):**
-
-1. Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extensions
-2. Connect to the remote host: `Ctrl+Shift+P` → "Remote-SSH: Connect to Host"
-3. On the remote host, start the container: `docker compose up -d`
-4. In VS Code (now connected to the remote): `Ctrl+Shift+P` → "Dev Containers: Attach to Running Container"
-
-VS Code extensions installed inside the container persist as long as the container exists (not removed with `docker compose down`). For persistent extension storage across container recreations, add a named volume:
-
-```yaml
-volumes:
-  - devbox-vscode:/home/developer/.vscode-server
-```
-
-## oh-my-opencode-slim (Multi-Agent Orchestration)
-
-[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) adds a multi-agent layer on top of opencode — an Orchestrator delegates tasks to specialized agents (Explorer, Oracle, Librarian, Designer, Fixer), each configurable with different models and providers.
-
-### Setup
-
-A pre-built OMOS image is available on Docker Hub as `joakimp/opencode-devbox:latest-omos`. Alternatively, build from source:
-
-**1. Build the image with OMOS support:**
-
-```bash
-docker compose build --build-arg INSTALL_OMOS=true
-```
-
-This installs Bun and the oh-my-opencode-slim package into the image.
-
-**2. Enable in `.env`:**
-
-```bash
-ENABLE_OMOS=true
-```
-
-**3. Run as normal:**
-
-```bash
-docker compose run --rm devbox
-```
-
-On first start, the entrypoint runs the oh-my-opencode-slim installer in non-interactive mode. It generates agent configuration at `~/.config/opencode/oh-my-opencode-slim.json` inside the container. The default preset uses OpenAI models — edit the generated config or mount your own to customize.
-
-### OMOS Environment Variables
-
-| Variable | Default | Description |
-|---|---|---|
-| `ENABLE_OMOS` | `false` | Activate oh-my-opencode-slim on container start |
-| `OMOS_TMUX` | `false` | Enable tmux pane integration (tmux is included in the base image) |
-| `OMOS_SKILLS` | `true` | Install recommended skills (simplify, agent-browser, cartography) |
-| `OMOS_RESET` | `false` | Force regenerate config on next start (backs up existing config) |
-
-### Custom Configuration
-
-If you mount the opencode config directory (see Custom opencode config above), the `oh-my-opencode-slim.json` file is included and persists across restarts. Edit it directly to control which models power each agent, fallback chains, council setup, and more.
-
-See the [oh-my-opencode-slim configuration docs](https://github.com/alvinunreal/oh-my-opencode-slim/blob/master/docs/configuration.md) for the full reference.
-
-### Verifying Agents
-
-After starting opencode with OMOS enabled, run inside the opencode session:
-
-```
-ping all agents
-```
-
-All six agents should respond if your provider authentication is working.
-
-## pi (alternative/complementary harness)
-
-[pi](https://github.com/mariozechner/pi-coding-agent) is a lightweight TUI coding-agent that can run alongside opencode in the same container. Both harnesses share the same mempalace install and palace data — wing/diary entries created by one are visible to the other. Available on the `*-with-pi` and `*-omos-with-pi` image tags.
-
-### Run
-
-The default container CMD is `bash -l`, so `compose run --rm devbox` drops to a login shell. From there pick a harness:
-
-```bash
-docker compose run --rm devbox          # bash — then run `pi`, `opencode`, or `aws sso login`
-docker compose run --rm devbox pi       # launch pi directly
-docker compose exec -u developer devbox pi    # attach into a `compose up -d` container
-```
-
-### MemPalace integration
-
-pi ships pre-wired with the mempalace bridge — the `mempalace.ts` extension is symlinked into `~/.pi/agent/extensions/` at first start, exposing palace MCP tools (search, diary, knowledge graph) to pi natively. The same `~/.mempalace/` palace is shared with opencode, so memories are mutually visible across harnesses. To persist palace data across container recreate, uncomment the `devbox-palace` volume in `docker-compose.yml` (see *MemPalace* section below).
-
-### Persistence
-
-| Path in container | Volume | Contains |
-|---|---|---|
-| `/home/developer/.pi` | `devbox-pi-config` (default) | `settings.json`, `agent/extensions/`, `auth.json`, `sessions/`, plus `git/` and `npm-global/` (`NPM_CONFIG_PREFIX` points here) so `pi install npm:` / `git:` and `npm i -g` survive container recreate and image rebuild. |
-| `/home/developer/.mempalace` | `devbox-palace` (uncomment) | Shared palace — visible to pi and opencode |
-
-Baked pi (`/usr/bin/pi`, `/opt/pi-*`) ships in the image; rebuild to upgrade. `npm i -g @mariozechner/pi-coding-agent` lands on the volume and wins via `PATH`.
-
-Full build args, extension list, and toolkit detail: <https://gitea.jordbo.se/joakimp/opencode-devbox#pi-alternativecomplementary-harness>
-
-## AWS Bedrock Authentication
-
-When using AWS Bedrock as your LLM provider, you need:
-
-### 1. AWS config on the host
-
-The container needs access to your `~/.aws/config` with SSO session configuration. If you already have this on another machine, copy it:
-
-```bash
-scp -r user@other-machine:~/.aws ~/.aws
-```
-
-Or configure from scratch on the host:
-
-```bash
-aws configure sso
-```
-
-### 2. Mount `~/.aws` into the container
-
-Uncomment the AWS volume mount in `docker-compose.yml`:
-
-```yaml
-- ~/.aws:/home/developer/.aws
-```
-
-Note: do **not** use `:ro` — SSO writes token cache files to this directory.
-
-### 3. Authenticate inside the container
-
-Since the container runs headless (no browser), use the device-code flow:
-
-```bash
-# Start the container
-docker compose up -d
-docker compose exec -u developer devbox bash
-
-# Authenticate — prints a URL and code you open in your local browser
-aws sso login --sso-session <your-sso-session> --use-device-code
-
-# Once approved in the browser, start opencode
-opencode
-```
-
-The `--use-device-code` flag outputs a URL and short code instead of trying to open a browser. Copy the URL into any browser (on your laptop, phone, etc.), enter the code, and complete the 2FA flow. The CLI in the container picks up the session automatically.
-
-SSO sessions typically last 8–12 hours before requiring re-authentication. Since `~/.aws` is mounted from the host, tokens persist across container restarts.
-
-## MemPalace — persistent AI memory
-
-The image includes [MemPalace](https://github.com/MemPalace/mempalace), a local-first AI memory system that stores conversation history verbatim and retrieves it via semantic search. Nothing leaves your machine.
-
-> MemPalace adds ~300 MB to the image (chromadb, embedding model deps). If you don't use it, rebuild with `--build-arg INSTALL_MEMPALACE=false` to shrink the image.
-
-### Enabling persistence
-
-Uncomment the palace volume in `docker-compose.yml`:
-
-```yaml
-- devbox-palace:/home/developer/.mempalace
-```
-
-Without the volume, palace data lives in the container's writable layer and is lost on `--force-recreate`.
-
-### MCP integration with opencode
-
-Add mempalace as an MCP server in your `opencode.jsonc` (inside `~/.config/opencode/`):
-
-```json
-{
-  "mcp": {
-    "mempalace": {
-      "type": "local",
-      "command": ["mempalace-mcp"]
-    }
-  }
-}
-```
-
-> The image installs mempalace into an isolated `uv tool` venv at `/opt/uv-tools/mempalace/`. `uv tool install` places `mempalace-mcp` on `PATH` as a shim whose shebang points at the venv's Python, so MCP clients can invoke it as a normal binary without worrying about the venv. Do **not** use `["python3", "-m", "mempalace.mcp_server"]` — the system Python cannot import from the uv-managed venv and you'll get `ModuleNotFoundError` / `MCP error -32000: connection closed`.
-
-This gives opencode access to 29 MCP tools for searching memory, querying the knowledge graph, managing wings/rooms/drawers, and agent diaries.
-
-### Basic usage
-
-```bash
-# Mine project files into the palace
-mempalace mine /workspace
-
-# Mine conversation transcripts
-mempalace mine ~/.local/share/opencode/ --mode convos
-
-# Search memory
-mempalace search "why did we switch to eno1"
-
-# Load context for a new session
-mempalace wake-up
-```
-
-Each workspace gets its own isolated "wing" — memories never leak between projects.
-
-### Scheduled mining (mempalace-toolkit)
-
-The image bakes in [mempalace-toolkit](https://gitea.jordbo.se/joakimp/mempalace-toolkit), a small set of bash wrappers that pair with mempalace for two common routines:
-
-```bash
-# Mine opencode session history (reads ~/.local/share/opencode/opencode.db, stages JSONL, mines into wing_conversations)
-mempalace-session
-
-# Mine a project's docs into a dedicated wing
-mempalace-docs /workspace/my-project
-```
-
-Both wrappers are idempotent and dedup-aware — re-running them on unchanged input is a cheap no-op.
-
-For weekly automated runs, the toolkit ships ready-to-use scheduler templates (systemd user timer, launchd user agent, cron) in its [`contrib/`](https://gitea.jordbo.se/joakimp/mempalace-toolkit/src/branch/main/contrib) directory. The `*-devbox` variants are designed for this container: host-side schedulers that `docker exec` into the running opencode-devbox.
-
-Disable the toolkit (keeps mempalace itself) with `--build-arg INSTALL_MEMPALACE_TOOLKIT=false`. Pin to a specific ref with `--build-arg MEMPALACE_TOOLKIT_REF=v0.3.0` once tagged releases exist.
-
-### Storage
-
-Two separate named volumes keep different data classes apart:
-
-- **Palace data** (`~/.mempalace/`): ChromaDB vectors, SQLite knowledge graph, drawers. This is your memory — back it up, treat it as precious. Persists via the `devbox-palace` named volume.
-- **Embedding model cache** (`~/.cache/chroma/`): ONNX model (~79 MB), downloaded automatically on first search. Disposable — blow it away and it re-downloads in ~4 seconds. Persists via the `devbox-chroma-cache` named volume so you don't re-download on every container recreation.
-- **No API keys required** for core functionality (local embeddings via ONNX).
-
-Both volumes are commented out by default in `docker-compose.yml` — uncomment to enable:
-
-```yaml
-- devbox-palace:/home/developer/.mempalace
-- devbox-chroma-cache:/home/developer/.cache/chroma
-```
-
-**Air-gapped environments:** pre-populate the `devbox-chroma-cache` volume with the `all-MiniLM-L6-v2/` model contents. The palace volume needs no pre-population.
-
-## Gitea MCP server
-
-The image includes the [official Gitea MCP server](https://gitea.com/gitea/gitea-mcp) (`gitea-mcp`), providing 50+ MCP tools for interacting with self-hosted Gitea instances — repositories, issues, pull requests, releases, branches, wiki, and Actions.
-
-### Setup
-
-1. Create a Personal Access Token on your Gitea instance (Settings → Applications → Generate Token, scopes: `repo`, `read:user`).
-
-2. Add to your `.env`:
-   ```env
-   GITEA_HOST=https://your-gitea-instance.example.com
-   GITEA_ACCESS_TOKEN=your_token_here
-   ```
-
-3. Enable the gitea MCP server in your `opencode.jsonc`:
-   ```json
-   {
-     "mcp": {
-       "gitea": {
-         "type": "local",
-         "command": ["gitea-mcp", "-t", "stdio", "--host", "{env:GITEA_HOST}"],
-         "environment": {
-           "GITEA_ACCESS_TOKEN": "{env:GITEA_ACCESS_TOKEN}"
-         },
-         "enabled": true
-       }
-     }
-   }
-   ```
-
-The server is installed but disabled by default — it requires authentication to be useful.
-
-## Architecture
-
-```
-Host Machine
-├── ~/projects/my-app  ──bind mount──▶  /workspace (container)
-├── ~/.ssh             ──bind mount──▶  /home/developer/.ssh (ro)
-├── ~/.aws             ──bind mount──▶  /home/developer/.aws (Bedrock SSO)
-└── .env               ──env vars───▶  provider config + API keys
-
-Container (Debian trixie)
-├── opencode binary
-├── oh-my-opencode-slim (optional — multi-agent orchestration plugin, includes Bun)
-├── AWS CLI v2 (SSO + Bedrock auth)
-├── neovim 0.12, tmux, htop, bat, eza, zoxide, uv, rustup, make, gcc, g++, rsync
-├── git, git-crypt, age, ssh, ripgrep, fd, fzf, jq, curl, tree
-├── Node.js (for MCP servers)
-├── Bun (optional — included with oh-my-opencode-slim)
-├── entrypoint.sh (UID adjustment, git config, provider setup)
-└── /workspace ← your code lives here
-```
-
-### Data persistence
-
-| Path in container | Source | Survives `--rm`? | Contains |
-|---|---|---|---|
-| `/workspace` | Host bind mount | ✅ Yes | Your project files |
-| `/home/developer/.ssh` | Host bind mount (ro) | ✅ Yes | SSH keys |
-| `/home/developer/.aws` | Host bind mount (if configured) | ✅ Yes | AWS credentials/SSO cache |
-| `/home/developer/.local/share/opencode` | Named volume `devbox-data` | ✅ Yes | Session history, memory |
-| `/home/developer/.local/state/opencode` | Named volume `devbox-state` | ✅ Yes | TUI settings (theme, toggles) |
-| `/home/developer/.cache/bash` | Named volume `devbox-shell-history` | ✅ Yes | Bash history (`$HISTFILE`), survives container recreate |
-| `/home/developer/.local/share/zoxide` | Named volume `devbox-zoxide` | ✅ Yes | Zoxide directory history (`z <fragment>` jump targets) |
-| `/home/developer/.local/share/nvim` | Named volume `devbox-nvim-data` | ✅ Yes | Neovim plugins, Mason LSP installs, Lazy plugin cache |
-| `/home/developer/.local/share/uv` | Named volume `devbox-uv` (if configured) | ✅ Yes | Python installs, uv tool installs |
-| `/home/developer/.rustup` | Named volume `devbox-rustup` (if configured) | ✅ Yes | Rust toolchains |
-| `/home/developer/.cargo` | Named volume `devbox-cargo` (if configured) | ✅ Yes | Cargo binaries, registry cache |
-| `/home/developer/.vscode-server` | Named volume `devbox-vscode` (if configured) | ✅ Yes | VS Code server and extensions |
-| `/home/developer/.config/opencode` | Named volume `devbox-opencode-config` | ✅ Yes | `opencode.jsonc`, skills, plus `oh-my-opencode-slim.json` on the OMOS variant |
-
-**opencode config** (`opencode.jsonc`) is auto-generated from `OPENCODE_PROVIDER` on each start. It sets provider and model only — no MCP servers. To persist config changes and use custom settings, use the named volume (default) or bind-mount from host (see Custom opencode config above).
-
-## Source
-
-MIT licensed. Source, issues, and `docker-compose.yml` templates: <https://gitea.jordbo.se/joakimp/opencode-devbox>
+> This description is generated by `scripts/generate-dockerhub-md.py` from a hand-maintained template. Edit the template (not this file) and regenerate.

scripts/generate-dockerhub-md.py

@@ -1,15 +1,30 @@
 #!/usr/bin/env python3
 """
-Generate DOCKER_HUB.md from README.md.
+Generate DOCKER_HUB.md.
 
 Rationale
 ---------
-README.md is the authoritative source. DOCKER_HUB.md is a subset
-intended for users pulling the pre-built image from Docker Hub — so
-build-from-source instructions, developer setup (git hooks, gitleaks),
-and CI/contribution content are dropped.
+DOCKER_HUB.md is the public-facing description shown on Docker Hub. It
+has two hard constraints the README does not:
 
-Docker Hub enforces a 25 kB limit on the full description field.
+  1. A 25 kB byte limit on the full_description field.
+  2. A different audience: Hub readers want a 30-second evaluation —
+     "what is this, how do I run it, does it have what I need" — and
+     reference material is better consulted in context on gitea.
+
+For a long time this script tried to derive DOCKER_HUB.md from README.md
+by section selection + targeted replacement. As the README grew that
+approach pushed against the 25 kB ceiling on every change, costing a
+trim-something-else exercise per edit (final state: 3 byte headroom).
+
+The new approach is much simpler: a hand-written HUB_TEMPLATE below.
+The template intentionally stays slim and links out to the gitea README
+for everything that benefits from depth. README.md grows freely.
+
+Trade-off: when image-variants table or quick-start flow changes,
+update HUB_TEMPLATE here too. That coupling is now explicit and
+local rather than spread across SECTION_RULES + REPLACEMENTS + TRIM
+machinery.
 
 Usage
 -----
@@ -19,77 +34,42 @@ Regenerate in place:
 Fail if DOCKER_HUB.md is out of sync with what this script would emit
 (run this in CI):
     python3 scripts/generate-dockerhub-md.py --check
-
-Design
-------
-Sections are selected and in some cases rewritten via `SECTION_RULES`
-below. This keeps the transformation explicit and easy to audit — if
-a new section is added to README.md that should also appear on Docker
-Hub, extend SECTION_RULES rather than inventing implicit heuristics.
 """
 
 from __future__ import annotations
 
 import argparse
-import re
 import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-README = REPO_ROOT / "README.md"
 DOCKER_HUB = REPO_ROOT / "DOCKER_HUB.md"
 
 # Max size for Docker Hub full_description (bytes, UTF-8).
 MAX_SIZE_BYTES = 25_000
 
-# Per-section transformation.
-#
-# Each key is a top-level section title as it appears in README.md
-# (without the leading "## ").
-#
-# The value is one of:
-#   "keep"      — include verbatim.
-#   "drop"      — exclude entirely.
-#   "replace"   — substitute a custom body (see REPLACEMENTS).
-#   "trim"      — keep but drop selected level-3 sub-sections listed
-#                 in TRIM_SUBSECTIONS[title].
-#
-# Unknown sections default to "drop" with a warning — forcing an
-# explicit decision whenever README gains a new section.
-SECTION_RULES: dict[str, str] = {
-    "Why?": "drop",                             # build-motivation, not user-facing
-    "Quick Start": "replace",                   # swap docker compose clone flow for docker run
-    "Features": "keep",
-    "Usage": "keep",
-    "Configuration": "trim",                    # drop dev-build sub-sections
-    "oh-my-opencode-slim (Multi-Agent Orchestration)": "keep",
-    "pi (alternative/complementary harness)": "replace",   # tailored Hub version, full detail in README
-    "AWS Bedrock Authentication": "keep",
-    "MemPalace — persistent AI memory": "keep",
-    "Gitea MCP server": "keep",
-    "Context7 MCP server": "drop",
-    "Shell defaults": "drop",                   # detail, full README covers it
-    "Secret Scanning": "drop",                  # dev-only — gitleaks is for committers
-    "Architecture": "keep",
-    "License": "replace",                       # point at source repo instead
-}
+# Where readers go for the full reference.
+GITEA = "https://gitea.jordbo.se/joakimp/opencode-devbox"
 
-# Level-3 sub-section titles (without the leading "### ") to drop from
-# sections flagged as "trim". These are dev/build-oriented — Docker Hub
-# users already have the image and don't need rebuild or multi-user
-# compose instructions.
-TRIM_SUBSECTIONS: dict[str, set[str]] = {
-    "Configuration": {
-        "Multi-user setup",
-        "Rebuilding the Image",
-        "Build Args",
-    },
-}
 
-# Replacement bodies. Keys match SECTION_RULES entries marked "replace".
-# Each value is the full section including the "## Title" heading.
-REPLACEMENTS: dict[str, str] = {
-    "Quick Start": """## Quick Start
+HUB_TEMPLATE = f"""# opencode-devbox
+
+Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.
+
+Designed for teams who want a reproducible coding-agent setup that runs the same on every laptop and CI runner — without forcing each developer to install Bun, Node, AWS CLI, mempalace, or maintain shell config drift across machines.
+
+## Image Variants
+
+| Tag | Description |
+|---|---|
+| `latest` / `vX.Y.Z` | Base image — opencode, Node.js, AWS CLI, dev tools |
+| `latest-omos` / `vX.Y.Z-omos` | Base + [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration and Bun |
+| `latest-with-pi` / `vX.Y.Z-with-pi` | Base + [pi](https://github.com/mariozechner/pi-coding-agent) as alternative/complementary harness (shares the mempalace install with opencode) |
+| `latest-omos-with-pi` / `vX.Y.Z-omos-with-pi` | OMOS + pi together |
+
+All variants support `linux/amd64` and `linux/arm64`.
+
+## Quick Start
 
 ```bash
 docker run -it --rm \\
@@ -102,9 +82,9 @@ docker run -it --rm \\
   joakimp/opencode-devbox:latest
 ```
 
-This drops you straight into opencode with your project mounted at `/workspace`.
+Drops you straight into opencode with your project mounted at `/workspace`.
 
-For an interactive shell first (useful for AWS SSO login):
+For an interactive shell first (useful for AWS SSO login, multi-harness workflows, or just `bash`):
 
 ```bash
 docker run -it --rm \\
@@ -115,156 +95,63 @@ docker run -it --rm \\
   joakimp/opencode-devbox:latest bash
 ```
 
-Then run `opencode` when ready.
+Then run `opencode`, `pi` (on `*-with-pi` variants), or `aws sso login` from the shell.
 
-For docker-compose users, see the source repo for `docker-compose.yml` and `.env.example` templates.
-""",
-    "License": """## Source
+For docker-compose users, the source repo provides `docker-compose.yml`, `.env.example`, and a one-liner `docker compose up -d` workflow with named volumes pre-wired.
 
-MIT licensed. Source, issues, and `docker-compose.yml` templates: <https://gitea.jordbo.se/joakimp/opencode-devbox>
-""",
-    "pi (alternative/complementary harness)": """## pi (alternative/complementary harness)
+## What's Inside
 
-[pi](https://github.com/mariozechner/pi-coding-agent) is a lightweight TUI coding-agent that can run alongside opencode in the same container. Both harnesses share the same mempalace install and palace data — wing/diary entries created by one are visible to the other. Available on the `*-with-pi` and `*-omos-with-pi` image tags.
+- **[opencode](https://opencode.ai)** — primary coding-agent harness. Multi-provider (Anthropic, OpenAI, Bedrock, Google, Groq, etc.).
+- **[pi](https://github.com/mariozechner/pi-coding-agent)** *(in `*-with-pi` variants)* — lightweight TUI coding-agent that coexists with opencode and shares the same mempalace install. Includes the `mcp-loader` extension so any local-stdio or remote streamable-HTTP MCP server (searxng, gitea, context7, …) can be added by editing `~/.pi/agent/settings.json`.
+- **[mempalace](https://github.com/MemPalace/mempalace)** — persistent AI memory layer (ChromaDB + SQLite). Wing/diary/knowledge-graph entries are mutually visible to opencode and pi.
+- **[oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim)** *(in `*-omos` variants)* — multi-agent orchestration on top of opencode (council, fallback chains, named agents).
+- **AWS CLI v2** with SSO support, **Node.js LTS**, **Bun** (OMOS variants), **uv** (Python), **gosu** for clean UID/GID adjustment to match your host workspace.
+- **MCP wrappers** for mempalace pre-installed and pre-wired to both harnesses.
 
-### Run
+## Authentication
 
-The default container CMD is `bash -l`, so `compose run --rm devbox` drops to a login shell. From there pick a harness:
+The container reads provider credentials from environment variables and host-mounted config:
 
-```bash
-docker compose run --rm devbox          # bash — then run `pi`, `opencode`, or `aws sso login`
-docker compose run --rm devbox pi       # launch pi directly
-docker compose exec -u developer devbox pi    # attach into a `compose up -d` container
-```
+- **Anthropic / OpenAI / Groq / others:** set `OPENCODE_PROVIDER` and the corresponding `*_API_KEY` via `-e` or `.env`.
+- **AWS Bedrock (SSO):** mount `~/.aws` from the host, `OPENCODE_PROVIDER=amazon-bedrock`, then `aws sso login` inside the container. Tokens persist across container restarts via the host bind-mount.
+- **OAuth / device-code providers:** auth state lives in opencode's config, which is persisted via the `devbox-opencode-config` named volume.
 
-### MemPalace integration
+Full Bedrock walkthrough (IAM roles, permissions, multi-account setups): see the [AWS Bedrock Authentication](
+{GITEA}#aws-bedrock-authentication
+) section on gitea.
 
-pi ships pre-wired with the mempalace bridge — the `mempalace.ts` extension is symlinked into `~/.pi/agent/extensions/` at first start, exposing palace MCP tools (search, diary, knowledge graph) to pi natively. The same `~/.mempalace/` palace is shared with opencode, so memories are mutually visible across harnesses. To persist palace data across container recreate, uncomment the `devbox-palace` volume in `docker-compose.yml` (see *MemPalace* section below).
+## Persistence
 
-### Persistence
-
-| Path in container | Volume | Contains |
+| Volume | Mount | Survives |
 |---|---|---|
-| `/home/developer/.pi` | `devbox-pi-config` (default) | `settings.json`, `agent/extensions/`, `auth.json`, `sessions/`, plus `git/` and `npm-global/` (`NPM_CONFIG_PREFIX` points here) so `pi install npm:` / `git:` and `npm i -g` survive container recreate and image rebuild. |
-| `/home/developer/.mempalace` | `devbox-palace` (uncomment) | Shared palace — visible to pi and opencode |
+| `devbox-opencode-config` | `~/.config/opencode` | container recreate, image rebuild |
+| `devbox-pi-config` | `~/.pi` | container recreate, image rebuild — incl. user-installed pi packages via `pi install` (`NPM_CONFIG_PREFIX` points into the volume) |
+| `devbox-palace` (uncomment) | `~/.mempalace` | container recreate, image rebuild — palace data is precious, treat as primary storage |
+| `devbox-chroma-cache` | `~/.cache/chroma` | container recreate (model cache, disposable — re-downloads in seconds) |
 
-Baked pi (`/usr/bin/pi`, `/opt/pi-*`) ships in the image; rebuild to upgrade. `npm i -g @mariozechner/pi-coding-agent` lands on the volume and wins via `PATH`.
+Workspace bind-mount (`/workspace`) is your project directory on the host, so source code is never inside the container.
 
-Full build args, extension list, and toolkit detail: <https://gitea.jordbo.se/joakimp/opencode-devbox#pi-alternativecomplementary-harness>
-""",
-}
+Full persistence reference, including multi-user (`SIGNUM`) isolation and host bind-mount alternatives: see the [README on gitea]({GITEA}#persistence).
 
+## Where to Go Next
 
-# Prepended to the generated file.
-HEADER = """# opencode-devbox — Docker Hub
+- **Full README** with build args, every feature in detail, troubleshooting: <{GITEA}>
+- **CHANGELOG** for version history: <{GITEA}/src/branch/main/CHANGELOG.md>
+- **Issues / source / docker-compose templates:** <{GITEA}>
+- **Agent-facing internals** (for future maintainers / coding agents working in the repo): <{GITEA}/src/branch/main/AGENTS.md>
 
-Portable AI developer environment for [opencode](https://opencode.ai). Debian-based, with git, SSH, Node.js, AWS CLI v2, and common dev tools pre-installed.
+## License
 
-## Image Variants
+MIT. See <{GITEA}/src/branch/main/LICENSE>.
 
-Four image variants are published for each release:
-
-| Tag | Description |
-|---|---|
-| `latest` / `vX.Y.Z` | Base image — opencode, Node.js, AWS CLI, dev tools |
-| `latest-omos` / `vX.Y.Z-omos` | Base + [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) multi-agent orchestration and Bun |
-| `latest-with-pi` / `vX.Y.Z-with-pi` | Base + [pi](https://github.com/mariozechner/pi-coding-agent) as alternative/complementary harness (shares the mempalace install with opencode) |
-| `latest-omos-with-pi` / `vX.Y.Z-omos-with-pi` | OMOS + pi together |
-
-All variants support `linux/amd64` and `linux/arm64`.
-
-> **NOTE:** This file is auto-generated from `README.md` by `scripts/generate-dockerhub-md.py`. Edit README.md and regenerate rather than editing this file directly.
+---
 
+> This description is generated by `scripts/generate-dockerhub-md.py` from a hand-maintained template. Edit the template (not this file) and regenerate.
 """
 
 
-def split_sections(md: str) -> list[tuple[str, str]]:
-    """Split markdown on level-2 headings, returning (title, body) pairs.
-
-    The body includes the heading line and everything up to (but not
-    including) the next level-2 heading or EOF. Content before the first
-    ``## `` is returned with an empty title (the document preamble).
-    """
-    pattern = re.compile(r"^## ", re.MULTILINE)
-    parts = pattern.split(md)
-    preamble, *rest = parts
-
-    sections: list[tuple[str, str]] = []
-    if preamble.strip():
-        sections.append(("", preamble))
-    for part in rest:
-        line, _, body = part.partition("\n")
-        sections.append((line.strip(), f"## {line}\n{body}"))
-    return sections
-
-
-def trim_subsections(body: str, drop: set[str]) -> str:
-    """Remove level-3 sub-sections whose title is in `drop`.
-
-    A sub-section starts at a line beginning with "### " and ends at
-    the next "### " or "## " (or EOF).
-    """
-    if not drop:
-        return body
-
-    # Split on level-3 headings while preserving the level-2 header
-    # block. First piece is everything up to the first "### ".
-    parts = re.split(r"(^### .+\n)", body, flags=re.MULTILINE)
-    # parts alternates: [before_first_h3, "### Title\n", body, "### Title\n", body, ...]
-    kept: list[str] = [parts[0]] if parts else []
-    i = 1
-    while i < len(parts):
-        heading = parts[i]
-        content = parts[i + 1] if i + 1 < len(parts) else ""
-        title = heading[4:].strip()
-        if title not in drop:
-            kept.append(heading)
-            kept.append(content)
-        i += 2
-    return "".join(kept)
-
-
 def generate() -> str:
-    """Produce the DOCKER_HUB.md content string."""
-    readme = README.read_text(encoding="utf-8")
-    sections = split_sections(readme)
-
-    out: list[str] = [HEADER]
-    unknown: list[str] = []
-
-    for title, body in sections:
-        if title == "":
-            # README preamble is replaced by our HEADER; skip.
-            continue
-
-        rule = SECTION_RULES.get(title)
-        if rule is None:
-            unknown.append(title)
-            continue
-        if rule == "drop":
-            continue
-        if rule == "keep":
-            out.append(body.rstrip() + "\n\n")
-        elif rule == "trim":
-            trimmed = trim_subsections(body, TRIM_SUBSECTIONS.get(title, set()))
-            out.append(trimmed.rstrip() + "\n\n")
-        elif rule == "replace":
-            out.append(REPLACEMENTS[title].rstrip() + "\n\n")
-        else:  # pragma: no cover — programmer error
-            raise AssertionError(f"unknown rule {rule!r} for section {title!r}")
-
-    if unknown:
-        print(
-            "ERROR: README.md contains sections not classified in "
-            "SECTION_RULES:\n  - "
-            + "\n  - ".join(unknown)
-            + "\n\nAdd each to SECTION_RULES in "
-            "scripts/generate-dockerhub-md.py (choose keep/drop/replace).",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
-
-    return "".join(out).rstrip() + "\n"
+    return HUB_TEMPLATE
 
 
 def main() -> int:
@@ -290,11 +177,10 @@ def main() -> int:
         existing = DOCKER_HUB.read_text(encoding="utf-8") if DOCKER_HUB.exists() else ""
         if existing != content:
             print(
-                "ERROR: DOCKER_HUB.md is out of sync with README.md.\n"
+                "ERROR: DOCKER_HUB.md is out of sync with the template.\n"
                 "Run: python3 scripts/generate-dockerhub-md.py",
                 file=sys.stderr,
             )
-            # Show a small diff hint.
             import difflib
 
             diff = difflib.unified_diff(
@@ -307,14 +193,16 @@ def main() -> int:
             sys.stderr.writelines(list(diff)[:80])
             return 1
         print(
-            f"OK: DOCKER_HUB.md is in sync with README.md "
-            f"({size} bytes, {MAX_SIZE_BYTES} limit).",
+            f"OK: DOCKER_HUB.md is in sync with HUB_TEMPLATE "
+            f"({size} bytes, {MAX_SIZE_BYTES} limit, "
+            f"{MAX_SIZE_BYTES - size} bytes headroom).",
         )
         return 0
 
     DOCKER_HUB.write_text(content, encoding="utf-8")
     print(
-        f"Wrote {DOCKER_HUB} ({size} bytes, {MAX_SIZE_BYTES} limit).",
+        f"Wrote {DOCKER_HUB} ({size} bytes, {MAX_SIZE_BYTES} limit, "
+        f"{MAX_SIZE_BYTES - size} bytes headroom).",
     )
     return 0