diff --git a/Dockerfile.user.example b/Dockerfile.user.example
index 61a5186c..843bdc42 100644
--- a/Dockerfile.user.example
+++ b/Dockerfile.user.example
@@ -2,9 +2,9 @@
 # Copy this file to Dockerfile.user — do NOT modify Dockerfile.user.example.
 # Dockerfile.user is gitignored so your customizations stay local.
 #
-# Build the base image first, then build your custom image:
+# Build the base image first, then start the stack:
 #   docker compose build           # builds the base remote-coding-agent image
-#   docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
+#   docker compose up -d           # auto-merges docker-compose.override.yml
 #
 # This file extends the locally-built dev image. Add any tools you need below.
 
diff --git a/docker-compose.override.example.yml b/docker-compose.override.example.yml
index 0235ae25..545b1216 100644
--- a/docker-compose.override.example.yml
+++ b/docker-compose.override.example.yml
@@ -6,7 +6,8 @@
 # when both files are present — no extra flags needed:
 #   docker compose up -d
 #
-# This override tells Compose to build from Dockerfile.user instead of the default Dockerfile.
+# NOTE: The base docker-compose.yml uses `build: .` (Dockerfile by default). This override
+# switches it to Dockerfile.user so Compose builds your custom image instead.
 
 services:
   app:
diff --git a/docker-compose.yml b/docker-compose.yml
index 25df5fe0..3ddf5f19 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -31,6 +31,7 @@ services:
   # -------------------------------------------------------------------------
   app:
     build: .
+    image: remote-coding-agent
     env_file: .env
     environment:
       ARCHON_DOCKER: "true"
diff --git a/packages/docs-web/src/content/docs/deployment/docker.md b/packages/docs-web/src/content/docs/deployment/docker.md
index 86741280..d311b88b 100644
--- a/packages/docs-web/src/content/docs/deployment/docker.md
+++ b/packages/docs-web/src/content/docs/deployment/docker.md
@@ -496,6 +496,8 @@ docker compose up -d
 
 Uses `ghcr.io/coleam00/archon:latest`. To add PostgreSQL, uncomment the `postgres` service in the compose file and set `DATABASE_URL` in `.env`.
 
+To layer custom tools on top of the pre-built image, see [Customizing the Image](#customizing-the-image).
+
 ---
 
 ## Building the Image
@@ -522,6 +524,21 @@ docker run --env-file .env -p 3000:3000 archon
 
 The multi-stage build keeps the image lean — no devDependencies, test files, docs, or `.git/`.
 
+### Customizing the Image
+
+To add extra tools without modifying the tracked Dockerfile:
+
+1. Copy the example:
+   - **Local/dev**: `cp Dockerfile.user.example Dockerfile.user`
+   - **Server/deploy**: `cp deploy/Dockerfile.user.example Dockerfile.user`
+2. Edit `Dockerfile.user` — uncomment and extend the examples as needed.
+3. Copy the override file:
+   - **Local/dev**: `cp docker-compose.override.example.yml docker-compose.override.yml`
+   - **Server/deploy**: `cp deploy/docker-compose.override.example.yml docker-compose.override.yml`
+4. Run `docker compose up -d` — Compose merges the override automatically.
+
+`Dockerfile.user` and `docker-compose.override.yml` are gitignored so your customizations stay local.
+
 ---
 
 ## Maintenance