docs: document env loading + shell fallback

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
 

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.

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.