fix(config): address review findings for Docker customization templates

- HIGH: Remove redundant -f flags in Dockerfile.user.example (contradicted override template)
- MEDIUM: Add image: remote-coding-agent to docker-compose.yml app service (fixes FROM lookup)
- MEDIUM: Add Customizing the Image section to docs/docker.md
- LOW: Clarify root docker-compose.override.example.yml comment to match deploy counterpart style

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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.
 

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:

docker-compose.yml

@@ -31,6 +31,7 @@ services:
   # -------------------------------------------------------------------------
   app:
     build: .
+    image: remote-coding-agent
     env_file: .env
     environment:
       ARCHON_DOCKER: "true"

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