diff --git a/compose.deploy.yaml b/compose.deploy.yaml
new file mode 100644
index 0000000..21d2df2
--- /dev/null
+++ b/compose.deploy.yaml
@@ -0,0 +1,11 @@
+# Deploy overlay: adds back the fixed host port mapping for a real running
+# deployment (e.g. the live instance behind Caddy/sh-caddy), which needs a
+# stable, known host port rather than the ephemeral one the gate resolves at
+# runtime via `docker compose port`.
+#
+# Usage:
+#   docker compose -f compose.yaml -f compose.deploy.yaml up -d --build
+services:
+  app:
+    ports:
+      - "4173:3000"
diff --git a/compose.yaml b/compose.yaml
index c3b91df..9b504ac 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -1,18 +1,27 @@
 # Software-house outcome-gate scaffold.
 #
-# No `container_name` and no anonymous/random host port: `app`'s host port is a
-# stable, project-specific mapping (4173) that will not collide with the gate
-# running this stack under a `-p <project>` prefix alongside a live deployment —
-# both instances share the same compose.yaml, isolated by project name, and the
-# gate/orchestrator polls this exact port for the health check (toolchain
-# health_url must match).
+# No `container_name`: the gate runs this stack under a `-p <project>` prefix,
+# isolated by project name from any live deployment sharing this same file.
+#
+# `app` publishes its port ephemerally (no fixed host port). The gate resolves
+# the actual host port at runtime via
+# `docker compose -p <proj> -f compose.yaml port app 3000`, builds
+# BASE_URL=http://127.0.0.1:<resolvedPort>, and polls BASE_URL + the toolchain
+# `health.path` (see toolchain_blob.health = {service, container_port, path}).
+# This is what lets the gate run concurrently with a live deployment without a
+# host port collision.
+#
+# For an actual running deployment (e.g. behind Caddy) that needs a stable,
+# known host port, use the `compose.deploy.yaml` override, which adds back the
+# fixed 4173:3000 mapping:
+#   docker compose -f compose.yaml -f compose.deploy.yaml up -d --build
 services:
   app:
     build:
       context: .
       dockerfile: Dockerfile
     ports:
-      - "4173:3000"
+      - "3000"
     # WHISPER_URL/WEBHOOK_BASE_URL/VAPID_*/OUTPUT_DIR/DATA_DIR all have safe
     # in-app defaults (see src/lib/server/*.ts) — override via a .env file or
     # `environment:` here for a real deployment; nothing is required to boot.