docs(env): clarify env var ownership split for external compute worker mode

Expand documentation and example env files to explicitly distinguish which
environment variables belong in the app/root `.env` versus the `compute/worker/.env*`
files when deploying in external worker mode. This clarifies routing/auth
settings versus worker runtime configuration, reducing misconfiguration risk.

.env.example

@@ -80,6 +80,9 @@ IMPORT_LIBRARY_DIRS=
 # Compute
 # Embedded/local (default): leave COMPUTE_WORKER_URL empty.
 # External worker: set COMPUTE_WORKER_URL + COMPUTE_WORKER_TOKEN.
+# External worker split:
+# - App side (this root `.env`): set only routing/auth + shared timeout/stale overrides.
+# - Worker side (`compute/worker/.env*` or worker platform env): set NATS_*, S3_*, model base URLs, and worker tuning.
 # Details: docs/deploy/compute-worker
 # COMPUTE_WORKER_URL=http://localhost:8081
 # COMPUTE_WORKER_TOKEN=local-compute-token
@@ -88,6 +91,7 @@ IMPORT_LIBRARY_DIRS=
 # EMBEDDED_NATS_PORT=4222
 # EMBEDDED_NATS_MONITOR_PORT=8222
 # EMBEDDED_NATS_STORE_DIR=docstore/nats/jetstream
+# `NATS_URL` here is for embedded startup only. In external worker mode, set `NATS_URL` on the worker service env.
 # NATS_URL=nats://127.0.0.1:4222
 # Optional shared compute tuning:
 # COMPUTE_JOB_CONCURRENCY=1

compute/worker/.env.example

@@ -1,5 +1,11 @@
 # External compute-worker service env only.
 # Keep COMPUTE_WORKER_TOKEN and S3_* aligned with app env.
+# In external worker mode, worker runtime vars live here (or worker platform env),
+# not in the app/root `.env`.
+# App/root `.env` should only set:
+# - COMPUTE_WORKER_URL
+# - COMPUTE_WORKER_TOKEN
+# - optional shared timeout/stale overrides
 # Details: docs/deploy/compute-worker
 
 # Compute worker bind

docs-site/docs/deploy/compute-worker.md

@@ -33,6 +33,9 @@ Required:
 > [!IMPORTANT]
 > This file (`compute/worker/.env*`) is only for standalone worker deployments.
 > In embedded/local startup, app entrypoint spawns worker with the already-resolved root `.env` values.
+> In standalone external worker mode:
+> - App server env (root `.env` or platform env): `COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`, optional shared timeout/stale overrides.
+> - Worker service env (`compute/worker/.env*` or platform env): worker runtime values (`NATS_*`, `S3_*`, model base URLs, worker tuning).
 > For standalone worker deployments, keep shared app/worker values aligned:
 > - `COMPUTE_WORKER_TOKEN`
 > - shared object storage settings (`S3_*`)

docs-site/docs/deploy/local-development.md

@@ -188,6 +188,10 @@ COMPUTE_WORKER_URL=http://localhost:8081
 COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
 ```
 
+Ownership in external worker mode:
+- root `.env`: app routing/auth (`COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`) plus optional shared timeout/stale overrides
+- `compute/worker/.env*` (or worker platform env): worker runtime variables (`NATS_*`, `S3_*`, model base URLs, worker tuning)
+
 Worker mode requires worker-reachable shared object storage (S3-compatible endpoint).
 For external worker mode, object storage must be shared/reachable by both app and worker services.
 
@@ -232,6 +236,10 @@ COMPUTE_WORKER_URL=http://localhost:8081
 COMPUTE_WORKER_TOKEN=<same-token-used-by-worker>
 ```
 
+Use the same ownership split:
+- root `.env`: app routing/auth (`COMPUTE_WORKER_URL`, `COMPUTE_WORKER_TOKEN`) plus optional shared timeout/stale overrides
+- `compute/worker/.env*` (or worker platform env): worker runtime variables (`NATS_*`, `S3_*`, model base URLs, worker tuning)
+
 Use one of these `.env` mode templates:
 
 <Tabs groupId="local-env-modes">

docs-site/docs/reference/environment-variables.md

@@ -365,6 +365,7 @@ Base URL for standalone external compute worker mode.
 - Leave unset for embedded/local startup (`pnpm dev` / `pnpm start`) so entrypoint can start embedded worker+NATS.
 - Embedded startup requires `nats-server` available on host PATH.
 - Required only when using a standalone external worker service.
+- App-side only: set on app server/root `.env` (routing target), not worker-only env files.
 - Example: `http://localhost:8081`
 
 ### COMPUTE_WORKER_TOKEN
@@ -374,6 +375,7 @@ Bearer token for compute-worker auth.
 - Required for standalone external worker service mode.
 - Must match worker service `COMPUTE_WORKER_TOKEN`.
 - In embedded startup, entrypoint auto-generates one if unset.
+- In external worker mode, set this on both app server/root `.env` and worker service env (`compute/worker/.env*` or platform env).
 
 ### EMBEDDED_COMPUTE_WORKER_PORT
 
@@ -406,6 +408,7 @@ NATS connection URL used by compute worker runtime.
 - Embedded startup default: `nats://127.0.0.1:4222`
 - Standalone worker service: set in worker service env (`compute/worker/.env*` or platform env)
 - For embedded startup, this is optional; startup supplies the default value.
+- Worker-side only in external mode: set on worker service env, not app/root `.env`.
 
 ### COMPUTE_JOB_CONCURRENCY