diff --git a/.env.example b/.env.example
index ef70ac855..94c742401 100644
--- a/.env.example
+++ b/.env.example
@@ -182,3 +182,43 @@ WORKER_MEDSPACY_ASSERTION=false
 PYTHON_BIN=python
 # Optional when Tesseract is installed outside PATH on Windows.
 TESSERACT_CMD=C:\Program Files\Tesseract-OCR\tesseract.exe
+
+# Railway deployment credentials (CI / remote agents only)
+# NOT read by the Next.js app or the worker. src/lib/env.ts never references
+# these; they exist purely so the Railway CLI can authenticate without an
+# interactive browser login. Leaving them unset locally is correct and expected.
+#
+# Locally, `railway login` writes a short-lived OAuth session to
+# ~/.railway/config.json (access token expires after ~1 hour, refreshed from the
+# browser session). That file is machine-local and NOT portable: it also stores
+# absolute Windows worktree paths. Never copy it to a remote machine or commit
+# it — mint a real token below instead.
+#
+# Railway has three token types. They are created in DIFFERENT places:
+#   RAILWAY_TOKEN      Project token. Scoped to ONE environment in ONE project.
+#                      Created in Project Settings -> Tokens (NOT account settings).
+#                      Use for deploys/redeploys/logs. Preferred for CI —
+#                      narrowest blast radius. Example: RAILWAY_TOKEN=xxx railway up
+#   RAILWAY_API_TOKEN  Account OR workspace token. Created at
+#                      https://railway.com/account/tokens — pick a workspace to
+#                      scope it to that workspace, or "No workspace" for a
+#                      full-account token (broadest scope; do not share).
+#                      Required for account-level actions (railway list,
+#                      railway link). Prefer a workspace token over an account
+#                      token, and only use either when a project token cannot
+#                      do the job.
+# Set only ONE of these at a time — they select different auth paths.
+# Direct GraphQL Public API calls (not the CLI) differ too: project tokens use
+# the `Project-Access-Token` header, account/workspace tokens use
+# `Authorization: Bearer`.
+#
+# Store the value in a secret store, never in this repo:
+#   GitHub Actions   gh secret set RAILWAY_TOKEN   (read as ${{ secrets.RAILWAY_TOKEN }})
+#   Cursor Cloud     add as a Cloud Agent Secret (injected into process.env)
+#   Remote shell     export RAILWAY_TOKEN=...      (CLI prefers it over config.json)
+#
+# Rotate immediately if a token is ever pasted into a chat, log, PR, or commit.
+# Deploys remain an operator-confirmed action in this repo — see AGENTS.md
+# "API and provider confirmation boundary" and docs/worker-deploy-runbook.md.
+#RAILWAY_TOKEN=
+#RAILWAY_API_TOKEN=