feat(transport): loopback-only default port binding + reverse-proxy docs (onboarding M3)

README.md

@@ -1,3 +1,52 @@
 # Maestro
 
-Dcntrlized project coordinator service
+Dcntrlized project coordinator service
+
+## Access & transport
+
+The dashboard ships session cookies (instance-owner gate), so the deployment
+default is **loopback-only**: `docker-compose.yaml` binds
+`127.0.0.1:8080:8080`, making the listener unreachable from the LAN unless you
+deliberately opt out. Maestro itself stays plaintext HTTP; TLS terminates in a
+reverse proxy (D6 — no TLS machinery inside the process).
+
+### Single host
+
+Reach the UI over SSH from your workstation:
+
+```sh
+ssh -L 8080:127.0.0.1:8080 <host>
+# then open http://localhost:8080
+```
+
+### Reverse proxy (LAN / public)
+
+Put Caddy, Traefik or nginx in front of `http://127.0.0.1:8080` and terminate
+TLS there:
+
+```text
+maestro.example.org {
+    reverse_proxy 127.0.0.1:8080
+}
+```
+
+- **WebSocket:** the UI uses `/api/ws`. Caddy and Traefik proxy upgrades
+  automatically; nginx needs explicit headers:
+  ```nginx
+  location / {
+      proxy_pass http://127.0.0.1:8080;
+      proxy_http_version 1.1;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection "upgrade";
+      proxy_set_header Host $host;
+      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+      proxy_set_header X-Forwarded-Proto $scheme;
+  }
+  ```
+- **Cookies behind the proxy:** set `COOKIE_SECURE=true` in Maestro's
+  environment so both session cookies (`maestro_access` / `maestro_refresh`)
+  are marked `Secure`.
+- **Host header:** mutating requests carry an Origin/Referer CSRF check that
+  compares hosts. A proxy that preserves `Host` works unchanged; if you rewrite
+  the host, keep forwarding `X-Forwarded-*` and serve the UI on the same host
+  you proxy to.

docker-compose.debug.yaml

@@ -3,7 +3,8 @@ services:
     image: maestro
     container_name: maestro
     ports:
-      - "8080:8080"
+      # Loopback-only default (dev is localhost anyway); see docker-compose.yaml
+      - "127.0.0.1:8080:8080"
     volumes:
       - "/var/run/docker.sock:/var/run/docker.sock"
       - "${XDG_DATA_HOME:-${HOME}}/.dcntrlized:/data/.dcntrlized"

docker-compose.yaml

@@ -3,7 +3,10 @@ services:
     image: maestro
     container_name: maestro
     ports:
-      - "8080:8080"
+      # Loopback-only by default (owner gate ships session cookies). Reach it
+      # via `ssh -L 8080:127.0.0.1:8080 <host>` or put a TLS reverse proxy in
+      # front — see README "Access & transport".
+      - "127.0.0.1:8080:8080"
     volumes:
       - "/var/run/docker.sock:/var/run/docker.sock"
       - "${XDG_DATA_HOME:-${HOME}}/.dcntrlized:/data/.dcntrlized"