fix: close deployment decoupling review

README.md

@@ -14,14 +14,22 @@ From a fresh clone, run these commands from the repository root:
 
 ```sh
 cp deploy/env/local.env.example deploy/env/local.env
-# Edit deploy/env/local.env, including PI_AUTH_FILE and the external endpoint URLs.
+# Edit deploy/env/local.env, including PI_AUTH_FILE, THT_SECRETS_FILE, and external endpoints.
 docker compose --env-file deploy/env/local.env \
   -f compose.yaml -f deploy/compose.local.yaml up --build -d
 ```
 
 `./scripts/run-stack.sh` runs this same base+local command in the foreground. The core image
-contains its Pi runtime; no host `pi` executable is used. For a server installation, copy and
-fill `deploy/env/server.env.example`, then use `-f compose.yaml -f deploy/compose.server.yaml`.
+contains its Pi runtime; no host `pi` executable is used. For a server installation:
+
+```sh
+cp deploy/env/server.env.example deploy/env/server.env
+# Edit all absolute storage, Pi/secret/session files, and endpoint paths.
+docker compose --env-file deploy/env/server.env \
+  -f compose.yaml -f deploy/compose.server.yaml \
+  -f deploy/compose.session-server.yaml.example up --build -d
+```
+
 Workspace descriptors come from the Git remote configured by `THT_WORKSPACE_GIT_REMOTE`; their
 runtime endpoint and secret bindings remain installation-local. Open
 <http://127.0.0.1:8080> (set `THOTH_HTTP_PORT` in `deploy/env/local.env` to choose another
@@ -164,15 +172,10 @@ with the organization's reviewed identity proxy. `AUTH_MODE=upstream` trusts thi
 rejects requests without the identity header. Setting `THOTH_PUBLIC_EXPOSURE=true` with any other
 auth mode fails during core startup.
 
-Production credentials use the one Compose secret bundle, not an environment example. Put the
-required keys in `deploy/secrets/thothii.secrets` for the selected base+server installation:
-
-```dotenv
-THT_MODEL_API_KEY=replace-me
-THT_DWH_API_KEY=replace-me
-THT_VEC_API_KEY=replace-me
-THT_VEC_WRITE_API_KEY=replace-me
-```
+Production credentials use the existing Compose secret-bundle contract, never environment values.
+Copy `deploy/secrets/thothii.secrets.example` to a protected host file, include only the required
+keys, and set its absolute path as `THT_SECRETS_FILE` in the operator env. Keep Pi's native
+provider auth in the separate protected file named by `PI_AUTH_FILE`.
 
 The bundle is mounted read-only as `/run/secrets/thothii.secrets` and must be mode `0600` or
 `0400` on the host. Docker's runtime `0444` mode is accepted only beneath `/run/secrets`; see
@@ -204,9 +207,9 @@ still scrubbed. Supporting them requires a future dedicated provider-specific co
 
 The server profile stores sessions and per-user preferences directly in PostgreSQL schema
 `thoth_sessions`; it does not use PostgREST, browser storage, a shared session directory, or a
-dual write. Start from [`deploy/compose.session-server.yaml.example`](deploy/compose.session-server.yaml.example)
-and copy [`deploy/workspaces/server-sessions.yaml.example`](deploy/workspaces/server-sessions.yaml.example)
-to the untracked `deploy/workspaces/server-sessions.yaml` mounted into the core container.
+dual write. Use [`deploy/compose.session-server.yaml.example`](deploy/compose.session-server.yaml.example)
+with the canonical base+server files and set `THT_SERVER_WORKSPACE_CONFIG` to an absolute,
+protected copy of [`deploy/workspaces/server-sessions.yaml.example`](deploy/workspaces/server-sessions.yaml.example).
 
 The runtime login needs membership in the no-login database role `thoth_sessions_runtime` only.
 The distinct, one-shot migrator login needs migration authority and uses
@@ -242,7 +245,8 @@ proxy clears the legacy identity header and the backend rejects it. Drain/stop a
 enable a maintenance response at the proxy, then run the migrator once and inspect its pristine JSON:
 
 ```sh
-docker compose -f compose.yaml -f deploy/compose.session-server.yaml \
+docker compose --env-file deploy/env/server.env \
+  -f compose.yaml -f deploy/compose.server.yaml -f deploy/compose.session-server.yaml.example \
   --profile session-migrate run --rm session-migrate
 ```