Default STACKS_HOST_DIR to /opt/stacks so host and container paths match

The shipped default (./data/stacks) guarantees the mismatch that hid stack data
from the file browser, the editor and (before 0.40.0) from backups: compose
resolves ./config against the container path, so the daemon creates the data
directories at /opt/stacks/<stack>/... on the host regardless of where
STACKS_HOST_DIR points. Same change for the agent, plus the reasoning in
.env.example and the README config table. Images unchanged (0.40.1).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -3,8 +3,13 @@
 SECRET_KEY=change-me-to-a-long-random-string
 
 # Host directory where stack folders (compose.yaml + .env) are stored.
-# This MUST be the same path on the host and is bind-mounted into the backend.
-STACKS_HOST_DIR=./data/stacks
+# It MUST be the same path as STACKS_DIR inside the container (/opt/stacks):
+# compose runs in the backend container and resolves a stack's relative bind
+# mounts (./config) against the *container* path, so the daemon creates those
+# data directories at that path on the host. With a different host path here,
+# every stack's data lands outside StackPilot's view — the file browser and the
+# editor won't see it (backups capture it either way, via a helper container).
+STACKS_HOST_DIR=/opt/stacks
 
 # Allowed CORS origin(s) for the API (comma separated). The bundled frontend
 # proxies /api, so this only matters if you call the API from another origin.

README.md

@@ -415,7 +415,15 @@ most important ones:
 | `DATA_DIR`      | `/data`            | SQLite DB + app data                      |
 | `CORS_ORIGINS`  | localhost          | Allowed API origins (comma separated)     |
 
-The host path for stacks is set via `STACKS_HOST_DIR` in `.env`.
+The host path for stacks is set via `STACKS_HOST_DIR` in `.env`, and it should
+be **the same path as `STACKS_DIR`** (`/opt/stacks` by default). Compose runs
+inside the backend container, so a stack's relative bind mounts (`./config`) are
+resolved against the container path and the daemon creates those directories at
+that path *on the host*. Point `STACKS_HOST_DIR` somewhere else and every stack's
+data lives at `/opt/stacks/<stack>/…` on the host while StackPilot looks at a
+different folder — the file browser and editor then show only the compose file.
+Backups cover the data either way (they read bind sources by host path through a
+helper container) and the Backup dialog warns when the two paths diverge.
 
 ## Local development
 

agent/docker-compose.yml

@@ -15,7 +15,10 @@ services:
       - HOST_PROC_PATH=/host_proc
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
-      - ${STACKS_HOST_DIR:-./data/stacks}:/opt/stacks
+      # Same rule as the central app: this must resolve to the same path as
+      # STACKS_DIR, or the stacks' relative bind mounts (./config) end up at the
+      # container path on the host, where the agent cannot see them.
+      - ${STACKS_HOST_DIR:-/opt/stacks}:/opt/stacks
       - /proc:/host_proc:ro
       # Read-only host devices for status/detection parity with the main host.
       - /dev:/dev:ro

docker-compose.yml

@@ -22,7 +22,12 @@ services:
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - ./data:/data
-      - ${STACKS_HOST_DIR:-./data/stacks}:/opt/stacks
+      # MUST resolve to the same path as STACKS_DIR above: compose runs inside
+      # this container and resolves a stack's relative bind mounts (./config)
+      # against the container path, which the daemon then creates at that same
+      # path on the host. A different host path means the stacks' data lands
+      # somewhere StackPilot cannot see (file browser, editor).
+      - ${STACKS_HOST_DIR:-/opt/stacks}:/opt/stacks
       - /proc:/host_proc:ro
       # Host devices for GPU/device detection + passthrough (USB/TTY/DRI).
       # Read-only; remove if you don't need GPU/device features.