diff --git a/.env.test.example b/.env.test.example
index 43bb0d1bb..7dd657524 100644
--- a/.env.test.example
+++ b/.env.test.example
@@ -1,27 +1,81 @@
-# Test Environment Configuration (automation stack)
+# ==========================================
+# GridPilot Test Environment Example
+# ==========================================
 # Copy this file to `.env.test` and adjust values as needed.
 #
-# Scope:
-# - This file is for the hosted-session automation stack (companion/automation).
-# - It is NOT used by the Website ↔ API Docker smoke stack (that stack is driven by env vars in
-#   [`docker-compose.test.yml`](docker-compose.test.yml:1) and scripts in [`package.json`](package.json:92)).
+# Scope / mental model:
+# - This file is for the hosted-session automation stack (companion/automation + adapters).
+# - It is NOT used by the Website ↔ API Docker smoke stack:
+#   - that stack is configured in [`docker-compose.test.yml`](docker-compose.test.yml:1)
+#   - and executed via scripts in [`package.json`](package.json:92)
+# - It also does NOT “configure the API” (e.g. `GRIDPILOT_API_PERSISTENCE`): API/Website runtime env lives in
+#   `.env.development` / `.env.production` and docker-compose env.
 #
-# Note on legacy config:
-# - `AUTOMATION_MODE` is deprecated in favor of `NODE_ENV` mapping in [`getAutomationMode()`](adapters/automation/config/AutomationConfig.ts:104).
-# - Keep `AUTOMATION_MODE` only if you need to force legacy behavior.
+# These env vars are read by:
+# - [`loadAutomationConfig()`](adapters/automation/config/AutomationConfig.ts:136)
+#
+# Legacy note:
+# - `AUTOMATION_MODE` is deprecated in favor of `NODE_ENV` mapping via [`getAutomationMode()`](adapters/automation/config/AutomationConfig.ts:104).
+# - Keep `AUTOMATION_MODE` only if you need to force legacy behavior for older tooling.
 
-# Prefer this:
+# ------------------------------------------
+# Runtime
+# ------------------------------------------
 NODE_ENV=test
 
+# ------------------------------------------
+# Automation Mode (legacy override)
+# ------------------------------------------
 # Optional legacy override (deprecated): `dev` | `mock` | `production`
+# - `mock` keeps tests deterministic (no real browser/iRacing).
+# - `production` enables real automation (only for manual runs / dedicated rigs).
 AUTOMATION_MODE=mock
 
+# ------------------------------------------
 # Shared automation settings
+# ------------------------------------------
+# Default timeout for automation operations (ms)
 AUTOMATION_TIMEOUT=5000
+
+# Number of retry attempts for failed operations
 RETRY_ATTEMPTS=1
+
+# Capture screenshots on error (string parsing: any value except "false" enables it)
 SCREENSHOT_ON_ERROR=false
 
+# ------------------------------------------
+# Chrome / DevTools (optional)
+# ------------------------------------------
+# Used by some adapters/tests to attach to a running Chrome instance.
+# CHROME_DEBUG_PORT=9222
+# CHROME_WS_ENDPOINT=ws://127.0.0.1:9222/devtools/browser/<id>
+
+# ------------------------------------------
+# Native automation tuning (optional)
+# ------------------------------------------
+# These are only relevant when running real automation (iRacing window + templates).
+# IRACING_WINDOW_TITLE=iRacing
+# TEMPLATE_PATH=./resources/templates/iracing
+# OCR_CONFIDENCE=0.9
+# NUTJS_MOUSE_SPEED=1000
+# NUTJS_KEYBOARD_DELAY=50
+
+# Retry tuning (optional)
+# AUTOMATION_MAX_RETRIES=3
+# AUTOMATION_BASE_DELAY_MS=500
+# AUTOMATION_MAX_DELAY_MS=5000
+# AUTOMATION_BACKOFF_MULTIPLIER=2
+
+# Timing tuning (optional)
+# AUTOMATION_PAGE_LOAD_WAIT_MS=5000
+# AUTOMATION_INTER_ACTION_DELAY_MS=200
+# AUTOMATION_POST_CLICK_DELAY_MS=300
+# AUTOMATION_PRE_STEP_DELAY_MS=100
+
+# ------------------------------------------
 # Logging (automation/adapters)
+# ------------------------------------------
+# Loaded by [`loadLoggingConfig()`](adapters/automation/config/LoggingConfig.ts:32)
 # LOG_LEVEL=warn
 # LOG_FILE_PATH=./logs/gridpilot
 # LOG_MAX_FILES=7