From c37b4c18e0c8864084cb9b435399118b0655c6b2 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 5 Jan 2026 01:03:01 +0100
Subject: [PATCH] docs: document env loading + shell fallback

---
 README.md             | 17 ++++++++++++++++-
 docs/configuration.md | 30 ++++++++++++++++++++++++++++++
 docs/faq.md           | 18 ++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 26ea0a582..49442a9b2 100644
--- a/README.md
+++ b/README.md
@@ -216,7 +216,22 @@ Minimal `~/.clawdbot/clawdbot.json`:
 
 Env vars: loaded from `.env` in the current working directory, plus a global fallback at `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`) without overriding existing values.
 
-Optional: import missing keys from your login shell env (sources your shell profile) via `env.shellEnv.enabled` (or `CLAWDBOT_LOAD_SHELL_ENV=1`). Timeout default: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`.
+Optional: import missing keys from your login shell env (sources your shell profile) via config or env var:
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
+    }
+  }
+}
+```
+
+- Env var: `CLAWDBOT_LOAD_SHELL_ENV=1`
+- Timeout override: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
+- Behavior: only imports known/expected keys, never overrides existing `process.env`.
 
 ### WhatsApp
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 99673c336..fd27ea821 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -60,6 +60,36 @@ To prevent the bot from responding to WhatsApp @-mentions in groups (only respon
 
 ## Common options
 
+### Env vars + `.env`
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.).
+
+Additionally, it loads:
+- `.env` from the current working directory (if present)
+- a global fallback `.env` from `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+### `env.shellEnv` (optional)
+
+Opt-in convenience: if enabled and none of the expected keys are set yet, CLAWDBOT runs your login shell and imports only the missing expected keys (never overrides).
+This effectively sources your shell profile.
+
+```json5
+{
+  env: {
+    shellEnv: {
+      enabled: true,
+      timeoutMs: 15000
+    }
+  }
+}
+```
+
+Env var equivalent:
+- `CLAWDBOT_LOAD_SHELL_ENV=1`
+- `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`
+
 ### `identity`
 
 Optional agent identity used for defaults and UX. This is written by the macOS onboarding assistant.
diff --git a/docs/faq.md b/docs/faq.md
index c47d44e94..57c28faca 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -118,6 +118,24 @@ pnpm clawdbot login
 
 **If OAuth fails** (headless/container): Do OAuth on a normal machine, then copy `~/.clawdbot/` to your server. The auth is just a JSON file.
 
+### How are env vars loaded?
+
+CLAWDBOT reads env vars from the parent process (shell, launchd/systemd, CI, etc.). It also loads `.env` files:
+- `.env` in the current working directory
+- global fallback: `~/.clawdbot/.env` (aka `$CLAWDBOT_STATE_DIR/.env`)
+
+Neither `.env` file overrides existing env vars.
+
+Optional convenience: import missing expected keys from your login shell env (sources your shell profile):
+
+```json5
+{
+  env: { shellEnv: { enabled: true, timeoutMs: 15000 } }
+}
+```
+
+Or set `CLAWDBOT_LOAD_SHELL_ENV=1` (timeout: `CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000`).
+
 ### Does enterprise OAuth work?
 
 **Not currently.** Enterprise accounts use SSO which requires a different auth flow that pi-coding-agent doesn't support yet.