diff --git a/DOCKER_HUB.md b/DOCKER_HUB.md
index 04b5cf2..03855a9 100644
--- a/DOCKER_HUB.md
+++ b/DOCKER_HUB.md
@@ -353,6 +353,35 @@ 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`, `/ext`-disabled extensions, pi user state |
+| `/home/developer/.mempalace` | `devbox-palace` (uncomment to enable) | Shared palace — visible to both pi and opencode |
+
+The `pi` binary, pi-toolkit, and pi-extensions are baked into the image; `pi update` does **not** persist across `--rm` containers — image rebuild is the upgrade 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:
diff --git a/scripts/generate-dockerhub-md.py b/scripts/generate-dockerhub-md.py
index c903aba..594e265 100755
--- a/scripts/generate-dockerhub-md.py
+++ b/scripts/generate-dockerhub-md.py
@@ -63,7 +63,7 @@ SECTION_RULES: dict[str, str] = {
     "Usage": "keep",
     "Configuration": "trim",                    # drop dev-build sub-sections
     "oh-my-opencode-slim (Multi-Agent Orchestration)": "keep",
-    "pi (alternative/complementary harness)": "drop",   # full README only, would push past 25 kB
+    "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",
@@ -122,6 +122,35 @@ For docker-compose users, see the source repo for `docker-compose.yml` and `.env
     "License": """## Source
 
 MIT licensed. Source, issues, and `docker-compose.yml` templates: <https://gitea.jordbo.se/joakimp/opencode-devbox>
+""",
+    "pi (alternative/complementary harness)": """## 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`, `/ext`-disabled extensions, pi user state |
+| `/home/developer/.mempalace` | `devbox-palace` (uncomment to enable) | Shared palace — visible to both pi and opencode |
+
+The `pi` binary, pi-toolkit, and pi-extensions are baked into the image; `pi update` does **not** persist across `--rm` containers — image rebuild is the upgrade path.
+
+Full build args, extension list, and toolkit detail: <https://gitea.jordbo.se/joakimp/opencode-devbox#pi-alternativecomplementary-harness>
 """,
 }