docs: add API key setup guide for Groq, OpenRouter, OpenAI, Google, Anthropic

Covers signup flow, current free-tier limits, and where credentials land in
config.toml for every provider the harness redesign targets. Written earlier
but never committed, so it was invisible to the Phase 1/2 implementation
worktrees — landing it now before Phase 2 merges to avoid two divergent
versions of this file.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 129 insertions, 0 deletions

diff --git a/docs/api-keys-setup.md b/docs/api-keys-setup.md
new file mode 100644
index 0000000..bf58f1e
--- /dev/null
+++ b/docs/api-keys-setup.md
@@ -0,0 +1,129 @@
+# API Key Setup Guide
+
+This guide covers getting an API key for each cloud provider claudomator's multi-role harness can escalate to, and where the key goes once you have it. It does **not** cover local models (Ollama/vLLM/LM Studio etc. — those use `[local_model]` in `config.toml` and generally need no key).
+
+Providers, in escalation-ladder order (cheapest/free first):
+
+| Provider | Status | Cost | Wire format |
+|---|---|---|---|
+| Groq | to add | free tier (real, no card required historically) | OpenAI-compatible |
+| OpenRouter | to add | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible |
+| OpenAI | to add | prepaid credit, no ongoing free tier | OpenAI-compatible (native) |
+| Google (Gemini) | already have paid account | paid | native (Gemini API) |
+| Anthropic (Claude) | already have paid account | paid | native (Messages API) |
+
+> Note on freshness: signup flows and free-tier limits change without much notice. Treat the specific numbers below (rate limits, credit thresholds) as "true as of when this was written" and double-check the provider's own pricing/limits page before relying on them for capacity planning.
+
+---
+
+## Where keys go
+
+Once you have a key, it lands in `~/.claudomator/config.toml` under a `[providers.<name>]` table:
+
+```toml
+[providers.groq]
+endpoint = "https://api.groq.com/openai/v1"
+api_key = "gsk_..."
+default_model = "llama-3.3-70b-versatile"
+
+[providers.openrouter]
+endpoint = "https://openrouter.ai/api/v1"
+api_key = "sk-or-..."
+default_model = "meta-llama/llama-3.3-70b-instruct:free"
+
+[providers.openai]
+endpoint = "https://api.openai.com/v1"
+api_key = "sk-..."
+default_model = "gpt-4o-mini"
+
+[providers.anthropic]
+api_key = "sk-ant-..."
+default_model = "claude-sonnet-4-5"
+
+[providers.google]
+api_key = "AIza..."
+default_model = "gemini-2.5-flash"
+```
+
+`config.toml` is not committed to the repo (it lives in the claudomator data dir, `~/.claudomator/` by default) — this is the same place `local_model.api_key` already lives today, so no new secret-handling pattern, just more provider entries.
+
+**Do not** put these keys in `credentials/claude/` or `credentials/gemini/` — those directories hold CLI OAuth session state for the `claude`/`gemini` command-line tools (`ContainerRunner`'s path) and are a different kind of credential from a plain bearer API key.
+
+---
+
+## Groq
+
+Free tier, no credit card required to start. Good first escalation rung above local models — fast inference, real (if modest) daily limits.
+
+1. Go to `console.groq.com` and sign in (Google/GitHub/email).
+2. Left nav → **API Keys** → **Create API Key**. Name it something identifying claudomator (e.g. `claudomator-harness`).
+3. Copy the key immediately — Groq only shows it once (`gsk_...`).
+4. Rate limits (free tier, vary per model): roughly 30 requests/minute, 6K–70K tokens/minute, 1K–14.4K requests/day, 100K–500K tokens/day depending on the specific model. Check `console.groq.com/settings/limits` for your account's current numbers per model — this varies enough by model that it's worth checking directly rather than trusting a fixed table here.
+5. Put the key in `config.toml` under `[providers.groq]` as shown above. `endpoint` is Groq's OpenAI-compatible base: `https://api.groq.com/openai/v1`.
+
+---
+
+## OpenRouter
+
+Aggregates many providers/models behind one key, including models with a `:free` suffix. Useful as a second free-tier rung, or to reach models Groq doesn't host.
+
+1. Go to `openrouter.ai` and sign in.
+2. **Keys** (in account settings) → **Create Key**. Name it, copy it (`sk-or-...`) — shown once.
+3. Free-tier limits: **without any credit purchase**, 50 free-model requests/day total across all `:free`-suffixed models. **With $10+ in purchased credits**, that jumps to 1000 requests/day (a one-time credit purchase, not a subscription) — worth doing once your usage grows past the bare free tier, since it's a 20x limit increase for a fixed cost, not a recurring charge.
+4. Pick a free model when configuring the harness — model IDs ending in `:free` (e.g. `meta-llama/llama-3.3-70b-instruct:free`) don't draw down credits. Browse current free models at `openrouter.ai/models?max_price=0`.
+5. `endpoint` is `https://openrouter.ai/api/v1`.
+
+---
+
+## OpenAI
+
+No meaningful ongoing free tier at this point — expect to prepay. Included in the ladder mainly for model diversity/fallback, not as a cost-saving rung.
+
+1. Go to `platform.openai.com`, sign in, create an org if prompted.
+2. **Settings → Billing** — add a payment method and some prepaid credit before making real calls (some new accounts get a small trial credit, but it's not guaranteed or large).
+3. **Dashboard → API keys** (`platform.openai.com/api-keys`) → **Create new secret key**. Name it, copy it (`sk-...`) — shown once.
+4. Consider setting a spend limit under **Billing → Limits** so a runaway harness escalation can't produce a surprise bill — this matters more here than for Groq/OpenRouter's free tiers.
+5. `endpoint` is `https://api.openai.com/v1`.
+
+---
+
+## Google (Gemini) — you already have a paid account
+
+The existing `credentials/gemini/` directory holds an OAuth session for the `gemini` CLI (used by `ContainerRunner`). The native-API path this harness adds is separate: a plain API key from Google AI Studio, used directly against the Gemini API rather than through the CLI.
+
+1. Go to `aistudio.google.com/apikey` (Google AI Studio), signed in with the same Google account as your paid plan.
+2. **Create API key** — choose the Google Cloud project tied to your paid billing if prompted, so usage bills correctly rather than falling back to any free-tier project quota.
+3. Copy the key (`AIza...`).
+4. `[providers.google]` needs no `endpoint` override (the adapter defaults to the native Gemini API base) — just `api_key` and `default_model`.
+
+If you'd rather use Vertex AI (GCP's enterprise entry point to Gemini, with IAM-based auth instead of a bare API key) that's a heavier setup (service account, GCP project, `gcloud` auth) — not necessary for this harness unless you specifically want Vertex's quota/governance features. AI Studio's simple API key is sufficient for what's being built here.
+
+---
+
+## Anthropic (Claude) — you already have a paid account
+
+Same situation as Gemini: `credentials/claude/` holds the `claude` CLI's OAuth session (`ContainerRunner`'s path). The native-API path needs a separate Console API key.
+
+1. Go to `console.anthropic.com`, sign in with your paid account.
+2. **Settings → API Keys** → **Create Key**. Name it, select the workspace tied to your billing if you have more than one.
+3. Copy the key (`sk-ant-...`) — shown once.
+4. `[providers.anthropic]` needs no `endpoint` override — just `api_key` and `default_model` (e.g. `claude-sonnet-4-5` for the escalation ladder's cloud rung, or a Haiku-tier model for a cheaper intermediate rung before Sonnet).
+5. Since this is a separate credential from the CLI's OAuth session, keep an eye on Console usage/billing separately from whatever the `claude` CLI itself reports — they draw from the same account but are tracked as distinct API consumers.
+
+---
+
+## Sanity-checking a key works
+
+Once phase 1/2/4 of the harness redesign land (native `Provider` adapters), the quickest check is submitting a trivial role-typed task pinned to a single rung, e.g. via the CLI:
+
+```bash
+./claudomator run - <<'EOF'
+name: "provider smoke test"
+agent:
+  type: "groq"          # or anthropic / google / openai / openrouter
+  model: "llama-3.3-70b-versatile"
+  instructions: "Reply with the word OK and nothing else."
+EOF
+```
+
+and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. Until then, you can at minimum confirm the key itself is valid with a raw `curl` against the provider's chat-completions endpoint using the docs above.