From 41186ad9b02f523d663a98c2f2a6ae68c8df0976 Mon Sep 17 00:00:00 2001
From: Tom Boucher <trekkie@nomorestars.com>
Date: Wed, 18 Mar 2026 00:03:10 -0400
Subject: [PATCH] docs: document /gsd config for global API keys (#1079)

* docs: add Node LTS pinning guide for macOS Homebrew users

New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.

Added notice banner in README linking to the guide.

* docs: document /gsd config for global API keys

Added Global API Keys section to configuration.md explaining:
- /gsd config saves keys to ~/.gsd/agent/auth.json
- Keys apply to all projects automatically
- Three supported keys: Tavily, Brave, Context7
- How precedence works (env vars > saved keys)
- Anthropic models don't need search keys

Updated commands.md gsd config entry to link to the new section.
Added Set up API keys section to getting-started.md for first-run.
---
 docs/commands.md        |  2 +-
 docs/configuration.md   | 26 ++++++++++++++++++++++++++
 docs/getting-started.md | 11 +++++++++++
 3 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/commands.md b/docs/commands.md
index a34673c90..09d8f7c23 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -96,7 +96,7 @@ See [Parallel Orchestration](./parallel-orchestration.md) for full documentation
 | `gsd --list-models [search]` | List available models and exit |
 | `gsd sessions` | Interactive session picker — list all saved sessions for the current directory and choose one to resume |
 | `gsd --debug` | Enable structured JSONL diagnostic logging for troubleshooting dispatch and state issues |
-| `gsd config` | Re-run the setup wizard (LLM provider + tool keys) |
+| `gsd config` | Set up global API keys for search and docs tools (saved to `~/.gsd/agent/auth.json`, applies to all projects). See [Global API Keys](./configuration.md#global-api-keys-gsd-config). |
 | `gsd update` | Update GSD to the latest version |
 | `gsd headless new-milestone` | Create a new milestone from a context file (headless — no TUI required) |
 
diff --git a/docs/configuration.md b/docs/configuration.md
index b4db57641..d10c6f52f 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -50,6 +50,32 @@ token_profile: balanced
 - **Array fields** (`always_use_skills`, etc.): concatenated (global first, then project)
 - **Object fields** (`models`, `git`, `auto_supervisor`): shallow-merged, project overrides per-key
 
+## Global API Keys (`/gsd config`)
+
+Tool API keys are stored globally in `~/.gsd/agent/auth.json` and apply to all projects automatically. Set them once with `/gsd config` — no need to configure per-project `.env` files.
+
+```bash
+/gsd config
+```
+
+This opens an interactive wizard showing which keys are configured and which are missing. Select a tool to enter its key.
+
+### Supported keys
+
+| Tool | Environment Variable | Purpose | Get a key |
+|------|---------------------|---------|-----------|
+| Tavily Search | `TAVILY_API_KEY` | Web search for non-Anthropic models | [tavily.com/app/api-keys](https://tavily.com/app/api-keys) |
+| Brave Search | `BRAVE_API_KEY` | Web search for non-Anthropic models | [brave.com/search/api](https://brave.com/search/api) |
+| Context7 Docs | `CONTEXT7_API_KEY` | Library documentation lookup | [context7.com/dashboard](https://context7.com/dashboard) |
+
+### How it works
+
+1. `/gsd config` saves keys to `~/.gsd/agent/auth.json`
+2. On every session start, `loadToolApiKeys()` reads the file and sets environment variables
+3. Keys apply to all projects — no per-project setup required
+4. Environment variables (`export BRAVE_API_KEY=...`) take precedence over saved keys
+5. Anthropic models don't need Brave/Tavily — they have built-in web search
+
 ## All Settings
 
 ### `models`
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c2e991f58..56f00ac9f 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -10,6 +10,17 @@ Requires Node.js ≥ 20.6.0 (22+ recommended) and Git.
 
 GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`.
 
+### Set up API keys
+
+If you use a non-Anthropic model, you'll need a search API key for web search. Run `/gsd config` to set keys globally — they're saved to `~/.gsd/agent/auth.json` and apply to all projects:
+
+```bash
+# Inside any GSD session:
+/gsd config
+```
+
+See [Global API Keys](./configuration.md#global-api-keys-gsd-config) for details on supported keys.
+
 ### VS Code Extension
 
 GSD is also available as a VS Code extension. Install from the marketplace (publisher: FluxLabs) or search for "GSD" in VS Code extensions. The extension provides: