docs(security): refine local secret management guidance

Supersedes: #406

Co-authored-by: Gabriel Nahum <gnahum12345@users.noreply.github.com>

.env.example

@@ -1,26 +1,65 @@
 # ZeroClaw Environment Variables
-# Copy this file to .env and fill in your values.
-# NEVER commit .env — it is listed in .gitignore.
+# Copy this file to `.env` and fill in your local values.
+# Never commit `.env` or any real secrets.
 
-# ── Required ──────────────────────────────────────────────────
-# Your LLM provider API key
-# ZEROCLAW_API_KEY=sk-your-key-here
+# ── Core Runtime ──────────────────────────────────────────────
+# Provider key resolution at runtime:
+# 1) explicit key passed from config/CLI
+# 2) provider-specific env var (OPENROUTER_API_KEY, OPENAI_API_KEY, ...)
+# 3) generic fallback env vars below
+
+# Generic fallback API key (used when provider-specific key is absent)
 API_KEY=your-api-key-here
+# ZEROCLAW_API_KEY=your-api-key-here
 
-# ── Provider & Model ─────────────────────────────────────────
-# LLM provider: openrouter, openai, anthropic, ollama, glm
+# Default provider/model (can be overridden by CLI flags)
 PROVIDER=openrouter
+# ZEROCLAW_PROVIDER=openrouter
 # ZEROCLAW_MODEL=anthropic/claude-sonnet-4-20250514
 # ZEROCLAW_TEMPERATURE=0.7
 
+# Workspace directory override
+# ZEROCLAW_WORKSPACE=/path/to/workspace
+
+# ── Provider-Specific API Keys ────────────────────────────────
+# OpenRouter
+# OPENROUTER_API_KEY=sk-or-v1-...
+
+# Anthropic
+# ANTHROPIC_OAUTH_TOKEN=...
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# OpenAI / Gemini
+# OPENAI_API_KEY=sk-...
+# GEMINI_API_KEY=...
+# GOOGLE_API_KEY=...
+
+# Other supported providers
+# VENICE_API_KEY=...
+# GROQ_API_KEY=...
+# MISTRAL_API_KEY=...
+# DEEPSEEK_API_KEY=...
+# XAI_API_KEY=...
+# TOGETHER_API_KEY=...
+# FIREWORKS_API_KEY=...
+# PERPLEXITY_API_KEY=...
+# COHERE_API_KEY=...
+# MOONSHOT_API_KEY=...
+# GLM_API_KEY=...
+# MINIMAX_API_KEY=...
+# QIANFAN_API_KEY=...
+# DASHSCOPE_API_KEY=...
+# ZAI_API_KEY=...
+# SYNTHETIC_API_KEY=...
+# OPENCODE_API_KEY=...
+# VERCEL_API_KEY=...
+# CLOUDFLARE_API_KEY=...
+
 # ── Gateway ──────────────────────────────────────────────────
 # ZEROCLAW_GATEWAY_PORT=3000
 # ZEROCLAW_GATEWAY_HOST=127.0.0.1
 # ZEROCLAW_ALLOW_PUBLIC_BIND=false
 
-# ── Workspace ────────────────────────────────────────────────
-# ZEROCLAW_WORKSPACE=/path/to/workspace
-
 # ── Docker Compose ───────────────────────────────────────────
 # Host port mapping (used by docker-compose.yml)
 # HOST_PORT=3000