docs(anthropic): clarify OAuth uses Claude Pro/Max subscription usage (#17399)

Users have been asking what they're billed for when they authenticate
Anthropic via OAuth in Hermes. Clarify in the provider docs that OAuth
routes through Anthropic's Claude Code subscription path — consuming
the extra Claude Code usage included with their Pro or Max plan — and
that an ANTHROPIC_API_KEY is pay-per-token against that key's org
instead.

Touches:
- integrations/providers.md: new info admonition in Anthropic (Native)
  section, plus provider-table row.
- user-guide/features/credential-pools.md: OAuth comment line.
- reference/environment-variables.md: Provider Auth (OAuth) intro.
- getting-started/quickstart.md: provider-picker table row.

website/docs/getting-started/quickstart.md

@@ -70,7 +70,7 @@ Good defaults:
 |----------|-----------|---------------|
 | **Nous Portal** | Subscription-based, zero-config | OAuth login via `hermes model` |
 | **OpenAI Codex** | ChatGPT OAuth, uses Codex models | Device code auth via `hermes model` |
-| **Anthropic** | Claude models directly (Pro/Max or API key) | `hermes model` with Claude Code auth, or an Anthropic API key |
+| **Anthropic** | Claude models directly — Pro/Max subscription (uses your included Claude Code usage) or API key | `hermes model` → OAuth login, or an Anthropic API key |
 | **OpenRouter** | Multi-provider routing across many models | Enter your API key |
 | **Z.AI** | GLM / Zhipu-hosted models | Set `GLM_API_KEY` / `ZAI_API_KEY` |
 | **Kimi / Moonshot** | Moonshot-hosted coding and chat models | Set `KIMI_API_KEY` |

website/docs/integrations/providers.md

@@ -18,7 +18,7 @@ You need at least one way to connect to an LLM. Use `hermes model` to switch pro
 | **OpenAI Codex** | `hermes model` (ChatGPT OAuth, uses Codex models) |
 | **GitHub Copilot** | `hermes model` (OAuth device code flow, `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `gh auth token`) |
 | **GitHub Copilot ACP** | `hermes model` (spawns local `copilot --acp --stdio`) |
-| **Anthropic** | `hermes model` (Claude Pro/Max via Claude Code auth, Anthropic API key, or manual setup-token) |
+| **Anthropic** | `hermes model` (Claude Pro/Max subscription via OAuth — uses your included Claude Code usage; also supports Anthropic API key or manual setup-token) |
 | **OpenRouter** | `OPENROUTER_API_KEY` in `~/.hermes/.env` |
 | **AI Gateway** | `AI_GATEWAY_API_KEY` in `~/.hermes/.env` (provider: `ai-gateway`) |
 | **z.ai / GLM** | `GLM_API_KEY` in `~/.hermes/.env` (provider: `zai`) |
@@ -158,6 +158,12 @@ If you're trying to switch to a provider you haven't set up yet (e.g. you only h
 
 Use Claude models directly through the Anthropic API — no OpenRouter proxy needed. Supports three auth methods:
 
+:::info Claude Pro / Max subscription usage
+When you authenticate via `hermes model` → Anthropic OAuth (or via `hermes auth add anthropic --type oauth`), Hermes consumes the **extra usage included with your Claude Pro or Max subscription** — the same quota Claude Code uses. This is per Anthropic's policy: requests identified as Claude Code route against your subscription's included Claude Code usage before any overage billing. You do not need an Anthropic API key or pay-per-token credits for this path — your Pro/Max plan covers it.
+
+If you use an `ANTHROPIC_API_KEY` instead, requests are billed pay-per-token against that key's organization (standard API pricing, independent of your Pro/Max subscription).
+:::
+
 ```bash
 # With an API key (pay-per-token)
 export ANTHROPIC_API_KEY=***

website/docs/reference/environment-variables.md

@@ -89,7 +89,7 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
 
 ## Provider Auth (OAuth)
 
-For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. Environment variables such as `ANTHROPIC_TOKEN` remain useful as manual overrides, but they are no longer the preferred path for Claude Pro/Max login.
+For native Anthropic auth, Hermes prefers Claude Code's own credential files when they exist because those credentials can refresh automatically. OAuth-authenticated Anthropic requests draw from the **extra Claude Code usage included with your Claude Pro or Max subscription** — no separate API key or per-token billing. Environment variables such as `ANTHROPIC_TOKEN` remain useful as manual overrides, but they are no longer the preferred path for Claude Pro/Max login.
 
 | Variable | Description |
 |----------|-------------|

website/docs/user-guide/features/credential-pools.md

@@ -40,7 +40,7 @@ hermes auth add openrouter --api-key sk-or-v1-your-second-key
 # Add a second Anthropic key
 hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key
 
-# Add an Anthropic OAuth credential (Claude Code subscription)
+# Add an Anthropic OAuth credential (uses your Claude Pro/Max subscription's included Claude Code usage)
 hermes auth add anthropic --type oauth
 # Opens browser for OAuth login
 ```