docs: warn agents not to paste API keys in chat

INSTALL_FOR_AGENTS.md

@@ -19,13 +19,47 @@ restart the shell or add the PATH export to the shell profile.
 
 Ask the user for these:
 
+**SECURITY: Do NOT collect API keys inside the agent chat.** Any command the user runs
+in an agent session (Claude Code, OpenClaw, Hermes) is stored in conversation logs.
+If the agent tells the user to run `export OPENAI_API_KEY="sk-..."` in the chat, the
+key ends up in the logs. This is a conflict: gbrain needs the keys, but the agent
+session is not a safe place to enter them.
+
+**Instead, tell the user to set keys in a separate terminal:**
+
+```bash
+# Tell the user: "Open a separate terminal (not this chat) and run:"
+echo 'export OPENAI_API_KEY="sk-..."' >> ~/.zshenv
+echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshenv
+source ~/.zshenv
+```
+
+**Then verify keys are available without printing them:**
+
 ```bash
-export OPENAI_API_KEY=sk-...          # required for vector search
-export ANTHROPIC_API_KEY=sk-ant-...   # optional, improves search quality
+[ -n "$OPENAI_API_KEY" ] && echo "OpenAI key: set" || echo "OpenAI key: missing"
+[ -n "$ANTHROPIC_API_KEY" ] && echo "Anthropic key: set" || echo "Anthropic key: missing"
 ```
 
-Save to shell profile or `.env`. Without OpenAI, keyword search still works.
-Without Anthropic, search works but skips query expansion.
+If keys are missing, remind the user to set them in a separate terminal and restart
+the agent session (new sessions inherit shell environment variables).
+
+**If the user asks "should I just paste it here?"** — say NO. Explain:
+"This chat logs everything to the provider's servers. Set the key in a separate
+terminal instead so it never enters the conversation."
+
+**If the user asks why:** "Everything you type in an AI agent chat is stored in
+conversation logs on the provider's servers. An API key in the chat is like writing
+your password on a whiteboard in a shared office — it's probably fine, but you
+wouldn't do it on purpose."
+
+**If the user pastes an API key directly in the chat anyway**, immediately warn them:
+"That key is now in the conversation log. Please rotate it (delete and create a new one)
+at platform.openai.com → API Keys, then set the new key in a separate terminal."
+
+OpenAI is required for vector search. Anthropic is optional (improves search quality).
+Without OpenAI, keyword search still works. Without Anthropic, search works but skips
+query expansion.
 
 ## Step 3: Create the Brain
 

recipes/calendar-to-brain.md

@@ -157,7 +157,11 @@ Tell the user:
    - Application type: **Desktop app**
    - Name: anything (e.g., 'GBrain')
 5. Click **'Create'**. You'll see the Client ID and Client Secret.
-6. Copy both and paste them to me.
+6. In a **separate terminal** (not this chat), run:
+   `echo 'export GOOGLE_CLIENT_ID=\"your-id\"' >> ~/.zshenv`
+   `echo 'export GOOGLE_CLIENT_SECRET=\"your-secret\"' >> ~/.zshenv`
+   `source ~/.zshenv`
+   Then come back here — I'll verify they're set.
 
 Also enable the Calendar API:
 7. Go to https://console.cloud.google.com/apis/library/calendar-json.googleapis.com

recipes/credential-gateway.md

@@ -84,7 +84,11 @@ Tell the user:
 
    Bad purpose: 'email triage' — too narrow, blocks legitimate requests.
 
-5. Copy the **Gateway URL** and **Agent Token** and paste them to me"
+5. In a **separate terminal** (not this chat), run:
+   `echo 'export CLAWVISOR_GATEWAY_URL=\"your-url\"' >> ~/.zshenv`
+   `echo 'export CLAWVISOR_AGENT_TOKEN=\"your-token\"' >> ~/.zshenv`
+   `source ~/.zshenv`
+   Then come back here — I'll verify they're set."
 
 Validate:
 ```bash

recipes/email-to-brain.md

@@ -126,7 +126,11 @@ Tell the user:
    including inbox triage, searching by any criteria, reading emails, tracking threads'
    IMPORTANT: Be EXPANSIVE in the task purpose. Narrow purposes like 'email triage'
    will cause legitimate requests to fail verification.
-5. Copy the gateway URL and agent token"
+5. In a **separate terminal** (not this chat), run:
+   `echo 'export CLAWVISOR_GATEWAY_URL=\"your-url\"' >> ~/.zshenv`
+   `echo 'export CLAWVISOR_AGENT_TOKEN=\"your-token\"' >> ~/.zshenv`
+   `source ~/.zshenv`
+   Then come back here — I'll verify they're set."
 
 Validate:
 ```bash

recipes/ngrok-tunnel.md

@@ -66,7 +66,9 @@ Twilio webhooks and Claude Desktop connection.
 1. Go to https://dashboard.ngrok.com/signup (sign up)
 2. Go to https://dashboard.ngrok.com/billing and upgrade to **Hobby** ($8/mo)
 3. Go to https://dashboard.ngrok.com/get-started/your-authtoken
-4. Copy your **Authtoken** and paste it to me"
+4. In a **separate terminal** (not this chat), run:
+   `echo 'export NGROK_AUTHTOKEN=\"your-token\"' >> ~/.zshenv && source ~/.zshenv`
+   Then come back here — I'll verify it's set."
 
 Validate:
 ```bash

recipes/twilio-voice-brain.md

@@ -164,9 +164,13 @@ Tell the user:
 2. After logging in, you'll see your **Account SID** right on the main dashboard
    (it starts with 'AC' followed by 32 characters)
 3. Below it you'll see **Auth Token** — click **'Show'** to reveal it
-4. Copy both values and paste them to me"
+4. In a **separate terminal** (not this chat), run:
+   `echo 'export TWILIO_ACCOUNT_SID=\"your-sid\"' >> ~/.zshenv`
+   `echo 'export TWILIO_AUTH_TOKEN=\"your-token\"' >> ~/.zshenv`
+   `source ~/.zshenv`
+   Then come back here — I'll verify they're set."
 
-After the user provides them, validate immediately:
+After the user confirms they've set the keys, validate immediately:
 
 ```bash
 curl -s -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
@@ -224,7 +228,8 @@ your URL changes every time ngrok restarts, breaking Twilio and Claude Desktop.
 3. If you upgraded: go to https://dashboard.ngrok.com/domains and click
    **'+ New Domain'**. Choose a name (e.g., `your-brain-voice.ngrok.app`).
 4. Go to https://dashboard.ngrok.com/get-started/your-authtoken
-5. Copy your **Authtoken** and paste it to me
+5. In a **separate terminal** (not this chat), run:
+   `echo 'export NGROK_AUTHTOKEN=\"your-token\"' >> ~/.zshenv && source ~/.zshenv`
 6. Also tell me your fixed domain name (if you created one)"
 
 ```bash

recipes/x-to-brain.md

@@ -110,7 +110,9 @@ Tell the user:
 4. Inside the project, create a new App
 5. Go to the app's 'Keys and tokens' tab
 6. Under 'Bearer Token', click 'Generate' (or 'Regenerate')
-7. Copy the Bearer Token and paste it to me
+7. In a **separate terminal** (not this chat), run:
+   `echo 'export X_BEARER_TOKEN=\"your-token\"' >> ~/.zshenv && source ~/.zshenv`
+   Then come back here — I'll verify it's set.
 
 Note: Free tier gives read-only access with low limits. Basic tier ($200/mo)
 gives search/recent endpoint and higher limits. Pro tier gets full archive search."