chore: dev/prod Docker compose separation with safety docs

- Add docker-compose.override.yml exposing db/redis ports for local dev
- Remove override from .gitignore so all devs get port mappings
- Use explicit -f in deploy.sh to skip override in production
- Document production safety rule: always use -f on the server

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitignore

@@ -156,9 +156,7 @@ uploads/
 __pypackages__/
 
 # Docker
-docker-compose.override.yml
 .dockerignore.local
-*.override.yml
 
 # Deployment & Security
 .build-info

docker-compose.override.yml

@@ -0,0 +1,9 @@
+# docker-compose.override.yml — auto-loaded in dev, skipped in prod via explicit -f
+# Exposes database and cache ports to localhost for local development.
+services:
+  db:
+    ports:
+      - "127.0.0.1:5432:5432"
+  redis:
+    ports:
+      - "127.0.0.1:6379:6379"

docs/deployment/docker.md

@@ -34,6 +34,33 @@ docker compose logs -f
 make docker-down
 ```
 
+### Dev vs Prod Compose Architecture
+
+The project uses a **compose override** pattern to separate dev and prod concerns:
+
+- **`docker-compose.yml`** — Base config. Services like `db` and `redis` do **not** expose ports to the host (they communicate over internal Docker networks only).
+- **`docker-compose.override.yml`** — Automatically loaded by `docker compose up` in dev. Exposes `db` (5432) and `redis` (6379) to `localhost` so the app can connect from outside Docker.
+- **`scripts/deploy.sh`** — Uses `docker compose -f docker-compose.yml --profile full` which **explicitly skips** the override file.
+
+> **CRITICAL — Production Safety Rule**
+>
+> The `-f docker-compose.yml` flag in `scripts/deploy.sh` is a deliberate security measure that prevents
+> `docker-compose.override.yml` from being loaded in production. This flag **must never be removed**.
+>
+> When running **any** `docker compose` command directly on the production server, you **must** always
+> pass `-f docker-compose.yml` explicitly to avoid accidentally loading the override file:
+>
+> ```bash
+> # CORRECT — on production server
+> docker compose -f docker-compose.yml --profile full up -d
+> docker compose -f docker-compose.yml --profile full logs -f api
+> docker compose -f docker-compose.yml --profile full exec db psql -U orion_user -d orion_db
+>
+> # WRONG — never run bare "docker compose" on production
+> docker compose up -d          # ← loads override, exposes ports!
+> docker compose --profile full up -d   # ← also loads override!
+> ```
+
 ### Current Services
 
 | Service | Port | Profile | Purpose |

scripts/deploy.sh

@@ -16,7 +16,7 @@
 
 set -euo pipefail
 
-COMPOSE="docker compose --profile full"
+COMPOSE="docker compose -f docker-compose.yml --profile full"
 HEALTH_URL="http://localhost:8001/health"
 HEALTH_RETRIES=12
 HEALTH_INTERVAL=5