diff --git a/AGENTS.md b/AGENTS.md
index a2f1206..63e839b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,6 +17,9 @@ Frontend UI for self-hosted Honcho instances — browse memories, peers, session
 | `make test` | Vitest (unit + integration), excludes `e2e/` |
 | `make test-e2e` | Playwright e2e (uncached) |
 | `make smoke-docker` | Local: build image + hermetic smoke test of the `/api` proxy (Docker required) |
+| `make compose-up` | Run the web container from source (dev-forward, builds) at :8080 |
+| `make compose-up-prod` | Run the web container from the published image (pulls `ghcr…:latest`) |
+| `make compose-down` | Stop + remove the web container |
 | `make check` | lint + typecheck + test |
 | `pnpm --filter @openconcho/desktop cargo-check` | Local Rust/Tauri compile check before pushing desktop changes |
 | `pnpm --filter @openconcho/web generate:api` | Regen `src/api/schema.d.ts` from `openapi.json` |
diff --git a/README.md b/README.md
index 4492305..baaef8d 100644
--- a/README.md
+++ b/README.md
@@ -89,23 +89,29 @@ pnpm --filter @openconcho/desktop dev
 
 ### Docker (web app)
 
-Run the web UI in a container — handy for adding it to a self-hosted Honcho
-Compose stack. The image serves the SPA and reverse-proxies the Honcho API under
-its own origin: the browser calls `/api` same-origin and names the upstream in an
+The container serves the SPA and reverse-proxies the Honcho API under its own
+origin: the browser calls `/api` same-origin and names the upstream in an
 `X-Honcho-Upstream` header, so there's no browser CORS to configure.
 
+Two Compose modes (the published image is `ghcr.io/offendingcommit/openconcho-web`):
+
 ```bash
-docker run --rm -p 8080:8080 \
-  -e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 \
-  ghcr.io/offendingcommit/openconcho-web:latest
+# Dev-forward — build from this repo and run your local changes:
+OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up
+
+# Production — pull the latest published image instead of building:
+OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up-prod
+
+make compose-down   # stop + remove
 # → http://localhost:8080
 ```
 
-`OPENCONCHO_DEFAULT_HONCHO_URL` seeds the first instance (absolute URL).
-`OPENCONCHO_UPSTREAM_ALLOWLIST` is an optional SSRF guard (comma-separated host
-globs) for when you expose the proxy. To drop it into a Honcho Compose stack, use
-the `openconcho` service in [`docker-compose.yml`](docker-compose.yml). Full
-details and env vars are in [`docs/docker.md`](docs/docker.md).
+`make compose-up` uses [`docker-compose.yml`](docker-compose.yml) (`build: .`);
+`make compose-up-prod` layers [`docker-compose.prod.yml`](docker-compose.prod.yml)
+to pull `ghcr…:latest`. `OPENCONCHO_DEFAULT_HONCHO_URL` seeds the first instance
+(absolute URL); `OPENCONCHO_UPSTREAM_ALLOWLIST` is an optional SSRF guard
+(comma-separated host globs) for when you expose the proxy. Full details and env
+vars are in [`docs/docker.md`](docs/docker.md).
 
 ### Connecting to your instance
 
diff --git a/docs/docker.md b/docs/docker.md
index e293747..4cca817 100644
--- a/docs/docker.md
+++ b/docs/docker.md
@@ -15,18 +15,41 @@ applies**; the nginx→Honcho hop is server-side, where CORS is irrelevant. The
 frontend stays the source of truth for which instance to talk to, so the
 multi-instance switcher and the Fleet view keep working.
 
-## Add it to a Honcho Compose stack (recommended)
+## Compose: dev-forward vs prod
 
-Honcho's self-hosting path is Docker Compose. Drop the `openconcho` service from
-[`docker-compose.yml`](../docker-compose.yml) into the project that runs your
-Honcho `api`:
+Two Compose files, env/ports defined once in the base:
+
+- **`docker-compose.yml`** — dev-forward: `build: .`, so it runs **your local source**.
+- **`docker-compose.prod.yml`** — override that swaps the build for the **published
+  image** (`ghcr.io/offendingcommit/openconcho-web:latest`, `pull_policy: always`).
+
+```bash
+make compose-up        # build from source + run        → http://localhost:8080
+make compose-up-prod   # pull ghcr…:latest instead of building
+make compose-down      # stop + remove
+```
+
+`make compose-up-prod` expands to
+`docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d`. Set env
+inline or via a `.env` file:
+
+```bash
+OPENCONCHO_DEFAULT_HONCHO_URL=https://honcho.example.net make compose-up-prod
+```
+
+The published image is multi-arch (amd64 + arm64); the first publish creates a
+private GHCR package — make it public for unauthenticated pulls.
+
+## Add it to an existing Honcho Compose stack
+
+Drop the `openconcho` service into the project that runs your Honcho `api`,
+pointing the seed at the api service (nginx resolves it on the compose network):
 
 ```yaml
 services:
   openconcho:
     image: ghcr.io/offendingcommit/openconcho-web:latest
     environment:
-      # Seeds the first instance; nginx resolves this on the compose network.
       OPENCONCHO_DEFAULT_HONCHO_URL: http://api:8000
     ports:
       - "127.0.0.1:8080:8080"
@@ -39,14 +62,13 @@ services:
 `OPENCONCHO_DEFAULT_HONCHO_URL` seeds the UI's first instance with an absolute
 URL. The browser sends that URL in the `X-Honcho-Upstream` header; nginx (on the
 compose network) forwards to it — **no browser CORS, and the API token never
-leaves the origin.** The published image is multi-arch (amd64 + arm64); the first
-publish creates a private GHCR package — make it public for unauthenticated pulls.
+leaves the origin.**
 
-## Standalone
+## Standalone (no compose)
 
 ```bash
-docker build -t openconcho-web .
-docker run --rm -p 8080:8080 -e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 openconcho-web
+docker run --rm -p 8080:8080 -e OPENCONCHO_DEFAULT_HONCHO_URL=http://host.docker.internal:8000 \
+  ghcr.io/offendingcommit/openconcho-web:latest
 # → http://localhost:8080  ·  GET /healthz returns "ok"
 ```