diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index 8c4331a3..13a5081b 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -106,7 +106,20 @@ For most users, [Git for Windows](https://git-scm.com/download/win) is sufficien
 
 ### API Keys & OAuth
 
-Set the environment variable for your provider:
+**Option 1: Settings file** (recommended)
+
+Add API keys to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "apiKeys": {
+    "anthropic": "sk-ant-...",
+    "openai": "sk-..."
+  }
+}
+```
+
+**Option 2: Environment variables**
 
 | Provider | Environment Variable |
 |----------|---------------------|
@@ -120,6 +133,8 @@ Set the environment variable for your provider:
 | OpenRouter | `OPENROUTER_API_KEY` |
 | ZAI | `ZAI_API_KEY` |
 
+Settings file keys take priority over environment variables.
+
 **OAuth Providers:**
 
 Use `/login` to authenticate with subscription-based or free-tier providers: