fix(docs): export compose tool paths

docs/install/local-workspace-registry.md

@@ -137,13 +137,18 @@ before creating sessions. Git pull/push over SSH remains fully supported and is
 Copy [the local Compose example](examples/local-compose.workspace-registry.yaml), exactly one
 selected [SSH Git override](examples/git-ssh.workspace-registry.yaml) or [HTTPS Git override](examples/git-https.workspace-registry.yaml),
 and [the bindings env example](examples/workspace-bindings.env.example) into an untracked operator
-directory. Set `THT_SOURCE_ROOT` and the absolute `THT_WORKSPACE_BINDINGS_ENV_FILE` in its `.env`;
+directory. Keep `THT_SOURCE_ROOT` and the absolute `THT_WORKSPACE_BINDINGS_ENV_FILE` in its `.env`
-this keeps the copied Compose file buildable and confines `THT_WS_*` values to `core`. Create the
+for Compose interpolation; this keeps the copied Compose file buildable and confines `THT_WS_*`
-host secret files named by the selected Git transport and every declared connector `*_SOURCE`, then
+values to `core`. A Compose `.env` file is not a shell environment, so do not import it into the
-generate the connector override and render through the preflight wrapper. The wrapper is required:
+maintenance shell. Instead, explicitly export the two non-secret paths before running the commands.
-it rejects unsafe source paths and a combined SSH+HTTPS Git selection before Compose runs.
+Create the host secret files named by the selected Git transport and every declared connector
+`*_SOURCE`, then generate the connector override and render through the preflight wrapper. The
+wrapper is required: it rejects unsafe source paths and a combined SSH+HTTPS Git selection before
+Compose runs.
 
 ```sh
+export THT_SOURCE_ROOT=/absolute/path/to/ThothII
+export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"
 "$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env --output connector-secrets.local.yaml
 "$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
   -f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml config --quiet

docs/install/server-workspace-registry.md

@@ -147,13 +147,17 @@ the absolute `THT_SERVER_WORKSPACE_CONFIG` path. Copy the bindings env example,
 `THT_SESSION_DB_HOST`, `THT_SESSION_DB_NAME`, `THT_SESSION_RUNTIME_USER`,
 `THT_SESSION_RUNTIME_PASSWORD_SOURCE`, and `THT_SESSION_CA_SOURCE`; the base Compose file wires
 `postgres`, `verify-full`, and the two Docker secret mount paths. This is the public server profile,
-not a filesystem-session fallback.
+not a filesystem-session fallback. A Compose `.env` file is not a shell environment, so do not
+import it into the maintenance shell. Explicitly export the non-secret source and bindings paths
+before running the commands below.
 
 Configure the portal proxy so the frontend and `/api` share one origin. It authenticates first and
 forwards the trusted identity expected by `AUTH_MODE=upstream`; it is the only public listener.
 From a trusted maintenance shell:
 
 ```sh
+export THT_SOURCE_ROOT=/absolute/path/to/ThothII
+export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"
 "$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env --output connector-secrets.local.yaml
 "$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
   -f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml -f connector-secrets.local.yaml up --build -d

scripts/test-verify-workspace-install-docs.sh

@@ -11,6 +11,8 @@ trap 'rm -f "$output"' EXIT HUP INT TERM
 for fixture in \
   "local manual requires generated connector override and Compose preflight" \
   "server manual requires generated connector override and Compose preflight" \
+  "local documented shell environment fixture" \
+  "server documented shell environment fixture" \
   "copied local base fixture" \
   "copied server PostgreSQL/TLS fixture" \
   "copied HTTPS Git override fixture" \
@@ -28,6 +30,23 @@ for fixture in \
   }
 done
 
+for manual in \
+  "$root/docs/install/local-workspace-registry.md" \
+  "$root/docs/install/server-workspace-registry.md"; do
+  grep -Fq 'export THT_SOURCE_ROOT=/absolute/path/to/ThothII' "$manual" || {
+    echo "installation manual does not publish a self-contained THT_SOURCE_ROOT export: $manual" >&2
+    exit 1
+  }
+  grep -Fq 'export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"' "$manual" || {
+    echo "installation manual does not publish a self-contained bindings export: $manual" >&2
+    exit 1
+  }
+  if rg -n 'source[[:space:]]+\.env' "$manual"; then
+    echo "installation manual unsafely imports operator .env: $manual" >&2
+    exit 1
+  fi
+done
+
 if rg -n 'connector-secrets\.workspace-registry|docker compose' \
   "$root/docs/install/local-workspace-registry.md" \
   "$root/docs/install/server-workspace-registry.md"; then

scripts/verify-workspace-install-docs.sh

@@ -62,9 +62,19 @@ verify_server_public_contract() {
 
 verify_manual_supported_path() {
   local profile="$1" manual="$2"
+  local source_root_export='export THT_SOURCE_ROOT=/absolute/path/to/ThothII'
+  local bindings_export='export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"'
   local generator='"$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env --output connector-secrets.local.yaml'
   local wrapper='"$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env'
 
+  grep -Fq "$source_root_export" "$manual" || {
+    echo "$profile manual does not export THT_SOURCE_ROOT for its shell commands" >&2
+    return 1
+  }
+  grep -Fq "$bindings_export" "$manual" || {
+    echo "$profile manual does not export THT_WORKSPACE_BINDINGS_ENV_FILE for its shell commands" >&2
+    return 1
+  }
   grep -Fq "$generator" "$manual" || {
     echo "$profile manual does not document the connector override generator" >&2
     return 1
@@ -151,18 +161,21 @@ verify_connector_fixture() {
 }
 
 verify_documented_operator_path() {
-  local profile="$1" directory="$2" connector_override
+  local profile="$1" directory="$2" documented_source_root="$3" connector_override
   connector_override="$directory/connector-secrets.local.yaml"
-  "$root/scripts/generate-connector-secrets-override.sh" \
-    --bindings-env "$directory/workspace-bindings.env" --operator-env "$directory/.env" \
-    --output "$connector_override" >/dev/null
   (
     cd "$directory"
-    "$root/scripts/compose-with-preflight.sh" --env-file .env \
+    unset THT_SOURCE_ROOT THT_WORKSPACE_BINDINGS_ENV_FILE
+    export THT_SOURCE_ROOT="$documented_source_root"
+    export THT_WORKSPACE_BINDINGS_ENV_FILE="$(pwd -P)/workspace-bindings.env"
+    "$THT_SOURCE_ROOT/scripts/generate-connector-secrets-override.sh" \
+      --bindings-env "$THT_WORKSPACE_BINDINGS_ENV_FILE" --operator-env .env \
+      --output connector-secrets.local.yaml >/dev/null
+    "$THT_SOURCE_ROOT/scripts/compose-with-preflight.sh" --env-file .env \
       -f compose.workspace-registry.yaml -f git-ssh.workspace-registry.yaml \
       -f connector-secrets.local.yaml config --quiet
   )
-  echo "$profile documented generator and preflight fixture passed"
+  echo "$profile documented shell environment fixture passed"
 }
 
 verify_copied_operator_fixtures() {
@@ -225,8 +238,8 @@ verify_copied_operator_fixtures() {
     "THT_WS_NORTH_STAR_RESEARCH_DWH_PASSWORD_SOURCE=$ssh_dir/dwh-password" \
     "THT_WS_NORTH_STAR_RESEARCH_VECTOR_API_KEY_SOURCE=$ssh_dir/vector-api-key" >>"$ssh_dir/.env"
   cp "$root/docs/install/examples/git-ssh.workspace-registry.yaml" "$ssh_dir/git-ssh.workspace-registry.yaml"
-  verify_documented_operator_path local "$ssh_dir"
+  verify_documented_operator_path local "$ssh_dir" "$root"
-  verify_documented_operator_path server "$server_dir"
+  verify_documented_operator_path server "$server_dir" "$root"
 
   cp "$root/docs/install/examples/local-compose.workspace-registry.yaml" "$connector_dir/compose.workspace-registry.yaml"
   : >"$connector_dir/dwh-password"; : >"$connector_dir/vector-password"