feat(#493): api-key backend support (useApiKey + backendEnvironmentFile)

docs/turn-loop/config.md

@@ -239,3 +239,61 @@ left untouched.
 Set to `false` for agents that parse cargo's JSON output
 programmatically and do not pass `--message-format json` themselves.
 
+## API-key backend (`useApiKey` / `backendEnvironmentFile`)
+
+```nix
+hyperhive.useApiKey = true;               # default: false
+hyperhive.backendEnvironmentFile =
+  "/agents/myagent/state/openrouter.env"; # default: null
+hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string
+```
+
+Runs this agent's `claude` against an API-key backend (e.g. OpenRouter)
+instead of a Claude subscription via OAuth. Two options, paired — each
+is a no-op without the other:
+
+- **`useApiKey`** tells the harness itself not to wait for a Claude OAuth
+  session: at boot, `LoginState::from_dir` reports `Online` without
+  checking `~/.claude/` (`hive_agent::login::using_api_key`, reads
+  `HIVE_USE_API_KEY`), and the fact is stamped into the consolidated
+  harness state file so the operator dashboard also stops reading this
+  agent's empty `~/.claude/` as "needs login". An api-key agent that hits
+  a real 401 (the key itself is bad) still surfaces `needs_login` — only
+  the boot-time "have I ever logged in" check is bypassed, not the
+  auth-failure path.
+- **`backendEnvironmentFile`** points at an operator-managed file
+  (outside the nix store, one `KEY=value` per line, systemd
+  `EnvironmentFile` syntax) supplying the credentials `claude` itself
+  reads from the environment — typically `ANTHROPIC_API_KEY` and
+  `ANTHROPIC_BASE_URL`. Loaded as an *optional* `EnvironmentFile`
+  (leading `-`), so setting the option before the file exists doesn't
+  strand the harness at boot.
+
+Provision the file once, out of band (never through nix — an API key in
+the store is world-readable and travels with the flake closure):
+
+```sh
+# on the host, once per agent that should use an api-key backend
+sudo install -m 0600 -o root /dev/stdin \
+  /var/lib/hyperhive/agents/<name>/state/openrouter.env <<KEYS
+ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
+ANTHROPIC_API_KEY=sk-or-...
+KEYS
+```
+
+The file lives in the agent's bind-mounted state dir, so it survives
+container rebuilds (not `--purge`) without needing to be re-provisioned.
+
+⚠️ Verified end-to-end against OpenRouter has not happened as of this
+writing — `ANTHROPIC_BASE_URL` support in the shipped Claude CLI is
+documented behavior, not something this hive has run a live turn
+against yet. Tool use, streaming, and MCP all need to keep working
+through a non-Anthropic base URL; treat the first real agent on this
+path as the actual verification, not this doc.
+
+Switching an already-provisioned OAuth agent to `useApiKey` leaves
+`~/.claude/credentials.json` in place but unused — harmless, not
+cleaned up automatically. Cost shape also changes: subscription pricing
+→ per-request billing with no built-in monthly cap, worth knowing before
+pointing a busy agent at a metered backend.
+