mercury-agent 0.4.28 → 0.5.1

package/docs/ARCHITECTURE.md

@@ -28,3 +28,7 @@
 ## Extension Points
 
 > Where the system is designed to be extended — plugin interfaces, hook points, configuration surfaces.
+
+- **Applicative profiles** (`src/core/profiles.ts`) — a `mercury-profile.yaml` declares `capabilities`, an exhaustive `member_permissions` set, and a `system_prompt`. `applyProfile` validates capabilities and persists `.mercury/active-profile.json`; `main.ts` activates it at startup (project-wide). Member permission scoping is in `getRolePermissions` (`src/core/permissions.ts`). Authoring contract: `docs/authoring-profiles.md`.
+- **Host-side capability broker** — extensions register `mercury.capability(name, handler)` (`src/extensions/types.ts`, `api.ts`); the agent invokes them from the container via `mrctl capability <name> <action>` → `POST /api/capability/:name/:action` (`src/core/routes/capability.ts`). Handlers run on the host with credentials that never enter the container; identity is the token-derived caller.
+- **Caller-bound capability token** (`src/core/caller-token.ts`) — per-turn HMAC token minted at container spawn, made authoritative over spoofable identity headers in the control-plane API auth middleware (`src/core/api.ts`).

package/docs/ROADMAP.md

@@ -10,7 +10,7 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 
 | Item | Doc | Notes |
 |------|-----|-------|
-| **business-extensions** | [doc](ideas/business-extensions.md) | Dedicated business extensions wrapping raw capabilities with deterministic logic |
+| — | — | — |
 
 ## Now
 
@@ -25,9 +25,6 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 | # | Item | Doc | Depends on | Why now |
 |---|------|-----|-----------|---------|
 | 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
-| 2 | **dm-auto-space** | [doc](backlog/dm-auto-space.md) | — | Auto-create space per customer DM |
-| 3 | **applicative-profiles** | [doc](backlog/applicative-profiles.md) | caller-bound-capability-token | Generic profile layer; host-side broker keeps secrets off customer containers |
-| 4 | **caller-bound-capability-token** | [doc](backlog/caller-bound-capability-token.md) | — | Per-turn token so brokers can trust callerId; also hardens TradeStation |
 
 ## Later
 
@@ -41,4 +38,6 @@ Single source of truth for priority. Rule: ≤15 min/week to maintain.
 
 | Item | Shipped | What |
 |------|---------|------|
-| — | — | — |
+| **applicative-profiles** | 2026-07-01 | Generic profile layer: manifest schema, exhaustive member scoping, host-side capability broker |
+| **caller-bound-capability-token** | 2026-07-01 | Per-turn unspoofable caller token for host API auth; also hardens TradeStation |
+| **dm-auto-space** | 2026-07-01 | Auto-create space per customer DM with rate limits and dashboard controls |

package/docs/{backlog/applicative-profiles.md → archive/applicative-profiles/2026-07-01-applicative-profiles.md}

@@ -1,6 +1,6 @@
 # Applicative Profiles
 
-**Status**: Backlog
+**Status**: Done
 **Slug**: applicative-profiles
 **Created**: 2026-07-01
 **Last updated**: 2026-07-01
@@ -70,7 +70,7 @@ Therefore **any credential injected into a customer's container is readable by t
 | 1. Profile schema + permission scoping | `mercury-public` | New `mercury-profile.yaml` fields; profile-aware member permissions |
 | 2. Host-side capability broker | `mercury-public` | Profile capabilities run host-side via `mrctl`→API, à la TradeStation; secrets stay on host |
 | 3. Per-turn caller token | `mercury-public` | [[caller-bound-capability-token]] — trustworthy `callerId` on the host (dependency) |
-| 4. Barber business logic | **private profiles repo** | Availability, 2 barbers, per-number limits, ownership rules — the moat |
+| 4. Barber business logic | **private repo** `tagula-agents/tagula-agent-profiles` | Availability, 2 barbers, per-number limits, ownership rules — the moat |
 
 ### Part 1 — Schema + permission scoping
 
@@ -115,7 +115,7 @@ The broker's ownership checks require a `callerId` the customer cannot forge. To
 
 ### Part 4 — Barber business logic (private repo)
 
-Lives in `tagula-agent-profiles` (or similar). Contains the `mercury-profile.yaml`, the agent persona, and the host-side route implementations' business rules (availability windows, 2-barber scheduling, per-number booking limits, double-booking prevention). Consumes Parts 1-3 as the public contract; never touches `mercury-public`.
+Lives in the private monorepo `Avishai-tsabari/tagula-agents` (`c:/code/agentic/tagula-agents`), under `tagula-agent-profiles/` (the repo also holds the cloud console). Checked out as a sibling of `mercury-public`. Contains the `mercury-profile.yaml`, the agent persona, and the host-side route implementations' business rules (availability windows, 2-barber scheduling, per-number booking limits, double-booking prevention). Consumes Parts 1-3 as the public contract; never touches `mercury-public`.
 
 ### Example manifest (in the private repo)
 
@@ -217,14 +217,15 @@ defaults:
 - [x] Context for Claude pointers filled in
 
 ### Implementation
-- [ ] Step 1 — Extend profile schema
-- [ ] Step 2 — Capability validation
-- [ ] Step 3 — Activation + config
-- [ ] Step 4 — Profile-aware permissions
-- [ ] Step 5 — Caller token dependency ([[caller-bound-capability-token]])
-- [ ] Step 6 — Broker route pattern (mirror `tradestation.ts`)
-- [ ] Step 7 — Tests
-- [ ] Step 8 — Example config
+- [x] Step 1 — Extend profile schema (`capabilities`, `member_permissions`, `system_prompt`); swapped hand-rolled `parseSimpleYaml` for the `yaml` lib (multiline `system_prompt` support, less fragility)
+- [x] Step 2 — Capability validation (`validateProfileCapabilities`, called in `applyProfile`); tests in `tests/applicative-profiles.test.ts`
+- [x] Step 3 — Activation + config: `profile` config key; `applyProfile` persists `.mercury/active-profile.json`; `main.ts` reads it at startup (after extensions load) and calls `setActiveProfileMemberPermissions`
+- [x] Step 4 — Profile-aware permissions: `getRolePermissions` uses the active profile's member set as exhaustive; precedence = explicit per-space override > profile > defaults; admin/system unaffected
+- [x] Step 5 — Caller token dependency ([[caller-bound-capability-token]]) — implemented and committed
+- [x] Step 5b — Inject `system_prompt` at container spawn (appended to `MERCURY_EXT_SYSTEM_PROMPT` in `runtime.ts`, ahead of per-space prompt)
+- [x] Step 6 — Host-side capability broker: `mercury.capability(name, handler)` extension API; `POST /api/capability/:name/:action` route (auth = token-derived caller, authz = permission named after the capability); `registry.getCapability`; `mrctl capability <name> <action> [json]`
+- [x] Step 7 — Tests: `tests/api.test.ts` capability broker (dispatch with token-derived caller; permission-denied → 403) + schema/scoping tests in `tests/applicative-profiles.test.ts`
+- [x] Step 8 — Example config: profile + `mrctl capability` + `MERCURY_CALLER_TOKEN_KEY` notes in `mercury.example.yaml`
 - [ ] `bun run check` passes
 - [ ] No secrets or `.env` files committed
 - [ ] No unrelated files modified
@@ -243,17 +244,27 @@ defaults:
 ## Retrospective
 
 **Residual risks / follow-ups:**
-- Per-turn caller token is a hard dependency for safe ownership → backlog/caller-bound-capability-token.md
-- Barber business logic tracked in the private profiles repo (out of this repo's scope) — accepted
+- Barber business logic (availability, 2-barber, per-number limits) lives in the private `tagula-agents` repo — out of this repo's scope — accepted
+- Ephemeral caller-token key breaks `mrctl` if the API and container-runner ever run in separate processes without `MERCURY_CALLER_TOKEN_KEY` set; documented in config + `docs/authoring-profiles.md` — accepted
+- `mrctl capability <name>/<action>` are not URL-encoded (path traversal only reaches other RBAC-guarded routes, no escalation) — accepted
+- Duplicate capability-name registration across two extensions silently first-wins in `registry.getCapability` — accepted
+- Empty `member_permissions: []` in a manifest gives members zero permissions (author's explicit exhaustive choice) — accepted
 
 **What changed from the plan:**
-- ...
+- Signing key is NOT derived from `API_SECRET` (the plan's fallback) — `API_SECRET` is readable in the container, so an ephemeral host-only random key is used instead (config `callerTokenKey` for multi-process).
+- Caller token split into its own delivered dependency (`caller-bound-capability-token`) — also hardened TradeStation, which reads identity from the same auth context (no code change needed there).
+- Replaced the hand-rolled `parseSimpleYaml` in `profiles.ts` with the `yaml` lib (multiline `system_prompt` support + less fragility); built-in profiles still parse.
+- Profile activation is project-wide via a module-level registry + persisted `.mercury/active-profile.json`, not per-space `space_config` writes (simpler, works for later-created dm-auto-space spaces).
+- Broker registration model chosen with the user: generic `mercury.capability(name, handler)` + `POST /api/capability/:name/:action` + `mrctl capability`, authorized by the permission named after the capability.
+- Added `docs/authoring-profiles.md` as the contract for the external profiles repo.
 
 **Key decisions made during implementation:**
-- ...
+- Token = HMAC-SHA256 over `base64url(payload).base64url(sig)`, constant-time compare with length guard; TTL = container timeout + 60s.
+- `getRolePermissions` uses `Array.isArray` (not `!== null`) on the active-profile member set so a malformed `active-profile.json` falls back to defaults instead of throwing in the hot path (found in session review).
+- Profile schema uses plain `z.object` (no `.strict()`), so unknown manifest keys are stripped, honoring the `2026-07-01-strict-yaml-schema-crash` post-mortem (warn/ignore unknown keys, fail only on invalid values); startup `loadActiveProfile` is try/catch → null.
 
 **Architecture impact** (update `docs/ARCHITECTURE.md` if any of these apply):
-- [ ] New package/module added
-- [ ] New data model or schema change
-- [ ] New inter-package interaction
+- [x] New package/module added — `src/core/caller-token.ts`, `src/core/routes/capability.ts`
+- [ ] New data model or schema change (uses existing `space_config`; adds a local `.mercury/active-profile.json` file, no DB schema change)
+- [x] New inter-package interaction — extension host-side capability handlers invoked via the control-plane API
 - [ ] Deployment topology changed

package/docs/{backlog/caller-bound-capability-token.md → archive/applicative-profiles/2026-07-01-caller-bound-capability-token.md}

@@ -1,6 +1,6 @@
 # Caller-Bound Capability Token
 
-**Status**: Backlog
+**Status**: Done
 **Slug**: caller-bound-capability-token
 **Created**: 2026-07-01
 **Last updated**: 2026-07-01
@@ -144,14 +144,14 @@ The signing key never enters the container. The container holds only its **own**
 - [x] Context for Claude pointers filled in
 
 ### Implementation
-- [ ] Step 1 — Token helpers
-- [ ] Step 2 — Mint at spawn
-- [ ] Step 3 — Forward in mrctl
-- [ ] Step 4 — Verify host-side
-- [ ] Step 5 — Migrate TradeStation guard
-- [ ] Step 6 — Tests
-- [ ] `bun run check` passes
-- [ ] No secrets committed
+- [x] Step 1 — Token helpers (`src/core/caller-token.ts`)
+- [x] Step 2 — Mint at spawn (`container-runner.ts`; key added to `BLOCKED_ENV_VARS`)
+- [x] Step 3 — Forward in mrctl (`x-mercury-token` header)
+- [x] Step 4 — Verify host-side (`api.ts` middleware; token identity wins)
+- [x] Step 5 — TradeStation guard: **no change needed** — it reads `c.get("auth")`, which now derives from the token
+- [x] Step 6 — Tests (`tests/caller-token.test.ts` unit; `tests/api.test.ts` integration: token overrides spoofed header, invalid token → 401)
+- [x] `bun run check` passes (one unrelated discord-adapter timeout flake under full parallel run; passes in isolation)
+- [x] No secrets committed
 
 ---
 
@@ -168,10 +168,14 @@ The signing key never enters the container. The container holds only its **own**
 - none
 
 **What changed from the plan:**
-- ...
+- **Signing key is NOT derived from `API_SECRET`.** The plan suggested deriving it when unset, but `API_SECRET` is injected into containers — the agent could recompute the key and forge tokens. Instead: an optional host-only `callerTokenKey` (env `MERCURY_CALLER_TOKEN_KEY`, in `BLOCKED_ENV_VARS`), falling back to an **ephemeral random key** generated once per host process. Zero required config; nothing forgeable from inside the container.
+- **TradeStation guard needed no code change** — it already reads identity from `c.get("auth")`, which the middleware now sets from the token.
+- Token injected as container env `CALLER_TOKEN` (unprefixed, like `CALLER_ID`/`API_SECRET`), forwarded as `x-mercury-token`.
 
 **Key decisions made during implementation:**
-- ...
+- HMAC-SHA256 over `base64url(payload).base64url(sig)`, payload `{c,s,exp}`; constant-time compare; no new dependency (`node:crypto`).
+- TTL = container timeout + 60s buffer, so a token never expires mid-turn but stays short-lived vs the permanent shared secret.
+- Header path retained as fallback → fully backward compatible; existing header-based tests and old container images keep working.
 
 **Architecture impact:**
 - [ ] New package/module added

package/docs/archive/summarization/2026-07-02-recent-dev-summary.md

@@ -0,0 +1,71 @@
+# Recent Dev Summary
+
+**Date:** 2026-07-02
+**Covers:** 3 shipped features · 2026-06-30 → 2026-07-01
+
+Three tightly-related features shipped together to lay the groundwork for customer-facing (member) profiles: a per-DM auto-space so each customer gets isolated persistent context, a caller-bound capability token so the host can trust *who* is calling, and applicative profiles that scope member capabilities and route privileged work through a host-side broker. The unifying thread is a **security pivot**: moving from "trust whoever holds a tool" to "keep secrets on the host and bind identity cryptographically" — a prerequisite for exposing capabilities to untrusted members.
+
+## Shipped
+
+| Feature | Slug | Date shipped | Key takeaway |
+|---------|------|-------------|--------------|
+| Auto-Create Space per DM | dm-auto-space | 2026-07-01 | Config-driven per-customer spaces; default-off, idempotent seeding via read-before-write |
+| Caller-Bound Capability Token | caller-bound-capability-token | 2026-07-01 | Per-turn HMAC token binds `{callerId, spaceId}`; host trusts the token, not spoofable headers |
+| Applicative Profiles | applicative-profiles | 2026-07-01 | Profiles scope member permissions + run privileged work host-side; secrets never enter member containers |
+
+## Build patterns
+
+### 1. Security by architecture, not by guardrail
+
+Rather than hardening a bypassable boundary, these features removed the sensitive material from the untrusted zone entirely.
+
+| Feature | Observation |
+|---------|-------------|
+| applicative-profiles | Credentials stay in host storage; member containers get only a self-scoped per-turn token — so `printenv` leaks nothing. Explicitly does *not* rely on the bypassable permission guard (TODO-2). |
+| caller-bound-capability-token | Signing key never enters the container; the container holds only its own turn's token and cannot forge another caller. |
+
+**Rule:** When an untrusted actor shares an execution environment, don't guard the secret — remove it from that environment. Security should come from where the secret lives, not from blocking the paths to it.
+
+### 2. Reuse the proven pattern over inventing one
+
+New capabilities deliberately mirrored an existing production mechanism instead of designing fresh machinery.
+
+| Feature | Observation |
+|---------|-------------|
+| applicative-profiles | The host-side capability broker is the TradeStation pattern generalized (`mrctl`→control-plane API, creds host-side), not a new transport. |
+| caller-bound-capability-token | TradeStation's confirm guard needed *no code change* — it already read identity from `c.get("auth")`, which the new middleware now populates from the token. |
+
+**Rule:** Before building new infrastructure, find the closest production-proven pattern and generalize it. Consumers that read from the right abstraction inherit the upgrade for free.
+
+### 3. Backward-compatible, additive rollout
+
+Every feature shipped default-off or fallback-preserving so existing deployments were unaffected.
+
+| Feature | Observation |
+|---------|-------------|
+| dm-auto-space | `enabled` defaults to `false`; global daily rate limits default to `0` (unlimited). |
+| caller-bound-capability-token | Absent a token, the old shared-secret + header path is unchanged, so old container images keep working during rollout. |
+| applicative-profiles | All new profile schema fields optional; brokers additive; existing profiles still parse. |
+
+**Rule:** Ship member-facing and security-sensitive changes as additive with a safe default; make the new path authoritative only when explicitly present, so rollout never breaks in-flight deployments.
+
+### 4. Plan-vs-reality divergence on the crypto detail
+
+Each retrospective flagged where the plan's shortcut was unsafe and was corrected during implementation.
+
+| Feature | Observation |
+|---------|-------------|
+| caller-bound-capability-token | Plan proposed deriving the signing key from `API_SECRET`; rejected because `API_SECRET` is readable in the container — switched to an ephemeral host-only key. |
+| applicative-profiles | Profile activation moved from per-space `space_config` writes to a module-level registry + persisted `.mercury/active-profile.json`; schema dropped `.strict()` to honor the strict-yaml crash post-mortem. |
+
+**Rule:** Re-examine any "derive the key from the existing secret" shortcut against the threat model — if the base secret is reachable by the attacker, the derived key is too.
+
+## Comparison with previous dev summary
+
+None — this is the first dev summary. Future summaries should watch whether the "security by architecture" and "reuse the proven pattern" themes persist as more member-facing profiles land in the private repo.
+
+## Action items
+
+1. **Land the private barber-appointments profile** against the now-public contract (schema + broker + caller token) to validate the design end-to-end.
+2. **Audit remaining header-trusting routes** to migrate onto token-derived identity now that the mechanism exists.
+3. **Document the host-side broker contract** (`docs/authoring-profiles.md`) as the canonical reference for external profile authors, and keep it in sync as capabilities grow.

package/docs/auth/dashboard.md

@@ -1,28 +1,28 @@
-# Dashboard Authentication
-
-The Mercury dashboard (`/dashboard/*`) is protected by `MERCURY_API_SECRET`. All htmx partial requests and the SSE events stream require a valid `mercury_token` session cookie.
-
-## How it works
-
-### Login route
-
-`GET /dashboard/login?token=<secret>` — the entry point for browser sessions.
-
-- Validates `token` against `MERCURY_API_SECRET` using `timingSafeEqual`
-- On success: sets `mercury_token` HttpOnly cookie and redirects to `/dashboard`
-- On failure: returns `401 Invalid or missing token`
-- Not protected by the dashboard auth middleware (it's the login endpoint itself)
-
-## Auth flow
-
-```
-User navigates to https://<host>:<port>/dashboard/login?token=<MERCURY_API_SECRET>
-  → agent sets mercury_token HttpOnly cookie
-  → 302 /dashboard
-  → dashboard loads, htmx requests include cookie ✅
-```
-
-## Key constraints
-
-- `MERCURY_API_SECRET` should be set to a long random string. `mercury setup` auto-generates one.
-- The cookie is HttpOnly — not accessible from JavaScript.
+# Dashboard Authentication
+
+The Mercury dashboard (`/dashboard/*`) is protected by `MERCURY_API_SECRET`. All htmx partial requests and the SSE events stream require a valid `mercury_token` session cookie.
+
+## How it works
+
+### Login route
+
+`GET /dashboard/login?token=<secret>` — the entry point for browser sessions.
+
+- Validates `token` against `MERCURY_API_SECRET` using `timingSafeEqual`
+- On success: sets `mercury_token` HttpOnly cookie and redirects to `/dashboard`
+- On failure: returns `401 Invalid or missing token`
+- Not protected by the dashboard auth middleware (it's the login endpoint itself)
+
+## Auth flow
+
+```
+User navigates to https://<host>:<port>/dashboard/login?token=<MERCURY_API_SECRET>
+  → agent sets mercury_token HttpOnly cookie
+  → 302 /dashboard
+  → dashboard loads, htmx requests include cookie ✅
+```
+
+## Key constraints
+
+- `MERCURY_API_SECRET` should be set to a long random string. `mercury setup` auto-generates one.
+- The cookie is HttpOnly — not accessible from JavaScript.

package/docs/auth/overview.md

@@ -1,109 +1,109 @@
-# Authentication
-
-Mercury needs credentials for two things:
-
-1. **AI model provider** — to call the LLM (Anthropic, OpenAI, etc.)
-2. **Chat platforms** — to connect to WhatsApp, Discord, Slack, Teams
-
-## Model Provider Auth
-
-### OAuth Login (Recommended)
-
-Mercury reuses [pi](https://github.com/badlogic/pi)'s OAuth providers. No API key needed — just login:
-
-```bash
-mercury auth login              # Interactive provider picker
-mercury auth login anthropic    # Or specify directly
-```
-
-Supported providers:
-
-| Provider | ID | What it gives you |
-|----------|----|-------------------|
-| Anthropic (Claude Pro/Max) | `anthropic` | Claude access via your subscription |
-| GitHub Copilot | `github-copilot` | Models via Copilot subscription |
-| Google Gemini CLI | `google-gemini-cli` | Gemini via Google Cloud |
-| Antigravity | `antigravity` | Gemini 3, Claude, GPT-OSS via Google Cloud |
-| ChatGPT Plus/Pro | `openai-codex` | OpenAI models via ChatGPT subscription |
-
-Credentials are saved to `.mercury/global/auth.json` and auto-refreshed when expired.
-
-### API Key
-
-Alternatively, set an API key in `.env`:
-
-```bash
-MERCURY_ANTHROPIC_API_KEY=sk-ant-...
-# or
-MERCURY_ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-...
-```
-
-### Resolution Order
-
-Mercury resolves credentials in this order:
-
-1. OAuth credentials from `auth.json` (via `mercury auth login`)
-2. `MERCURY_ANTHROPIC_OAUTH_TOKEN` from `.env`
-3. `MERCURY_ANTHROPIC_API_KEY` from `.env`
-
-> **OAuth always takes precedence over API keys.** If a provider has both an OAuth connection (in `auth.json` or `MERCURY_*_OAUTH_TOKEN`) and an API key (`MERCURY_*_API_KEY`), the OAuth token is used and the API key is ignored. This applies both to the CLI and to agents provisioned via the cloud console.
-
-### Managing Credentials
-
-```bash
-mercury auth status             # Show what's configured
-mercury auth logout anthropic   # Remove saved credentials
-mercury auth logout             # List what's logged in
-```
-
-## Chat Platform Auth
-
-### WhatsApp
-
-```bash
-mercury auth whatsapp                              # QR code (recommended)
-mercury auth whatsapp --pairing-code --phone 1234   # Pairing code (headless)
-```
-
-See [whatsapp.md](whatsapp.md) for details.
-
-### Discord
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_DISCORD=true
-MERCURY_DISCORD_BOT_TOKEN=your-bot-token
-```
-
-### Slack
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_SLACK=true
-MERCURY_SLACK_BOT_TOKEN=xoxb-...
-MERCURY_SLACK_SIGNING_SECRET=...
-```
-
-### Teams
-
-Set in `.env`:
-
-```bash
-MERCURY_ENABLE_TEAMS=true
-MERCURY_TEAMS_APP_ID=...
-MERCURY_TEAMS_APP_PASSWORD=...
-MERCURY_TEAMS_APP_TENANT_ID=...
-```
-
-## Dashboard Auth
-
-The web dashboard is protected by `MERCURY_API_SECRET`. Browser sessions are established via a login handshake managed by the cloud console — see [dashboard.md](dashboard.md).
-
-## Security
-
-- `auth.json` has `0600` permissions (owner read/write only)
-- WhatsApp credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
-- All `MERCURY_*` env vars are passed into containers with the prefix stripped
-- Never commit `.env` or `auth.json` to version control
+# Authentication
+
+Mercury needs credentials for two things:
+
+1. **AI model provider** — to call the LLM (Anthropic, OpenAI, etc.)
+2. **Chat platforms** — to connect to WhatsApp, Discord, Slack, Teams
+
+## Model Provider Auth
+
+### OAuth Login (Recommended)
+
+Mercury reuses [pi](https://github.com/badlogic/pi)'s OAuth providers. No API key needed — just login:
+
+```bash
+mercury auth login              # Interactive provider picker
+mercury auth login anthropic    # Or specify directly
+```
+
+Supported providers:
+
+| Provider | ID | What it gives you |
+|----------|----|-------------------|
+| Anthropic (Claude Pro/Max) | `anthropic` | Claude access via your subscription |
+| GitHub Copilot | `github-copilot` | Models via Copilot subscription |
+| Google Gemini CLI | `google-gemini-cli` | Gemini via Google Cloud |
+| Antigravity | `antigravity` | Gemini 3, Claude, GPT-OSS via Google Cloud |
+| ChatGPT Plus/Pro | `openai-codex` | OpenAI models via ChatGPT subscription |
+
+Credentials are saved to `.mercury/global/auth.json` and auto-refreshed when expired.
+
+### API Key
+
+Alternatively, set an API key in `.env`:
+
+```bash
+MERCURY_ANTHROPIC_API_KEY=sk-ant-...
+# or
+MERCURY_ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-...
+```
+
+### Resolution Order
+
+Mercury resolves credentials in this order:
+
+1. OAuth credentials from `auth.json` (via `mercury auth login`)
+2. `MERCURY_ANTHROPIC_OAUTH_TOKEN` from `.env`
+3. `MERCURY_ANTHROPIC_API_KEY` from `.env`
+
+> **OAuth always takes precedence over API keys.** If a provider has both an OAuth connection (in `auth.json` or `MERCURY_*_OAUTH_TOKEN`) and an API key (`MERCURY_*_API_KEY`), the OAuth token is used and the API key is ignored. This applies both to the CLI and to agents provisioned via the cloud console.
+
+### Managing Credentials
+
+```bash
+mercury auth status             # Show what's configured
+mercury auth logout anthropic   # Remove saved credentials
+mercury auth logout             # List what's logged in
+```
+
+## Chat Platform Auth
+
+### WhatsApp
+
+```bash
+mercury auth whatsapp                              # QR code (recommended)
+mercury auth whatsapp --pairing-code --phone 1234   # Pairing code (headless)
+```
+
+See [whatsapp.md](whatsapp.md) for details.
+
+### Discord
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_DISCORD=true
+MERCURY_DISCORD_BOT_TOKEN=your-bot-token
+```
+
+### Slack
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_SLACK=true
+MERCURY_SLACK_BOT_TOKEN=xoxb-...
+MERCURY_SLACK_SIGNING_SECRET=...
+```
+
+### Teams
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_TEAMS=true
+MERCURY_TEAMS_APP_ID=...
+MERCURY_TEAMS_APP_PASSWORD=...
+MERCURY_TEAMS_APP_TENANT_ID=...
+```
+
+## Dashboard Auth
+
+The web dashboard is protected by `MERCURY_API_SECRET`. Browser sessions are established via a login handshake managed by the cloud console — see [dashboard.md](dashboard.md).
+
+## Security
+
+- `auth.json` has `0600` permissions (owner read/write only)
+- WhatsApp credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
+- All `MERCURY_*` env vars are passed into containers with the prefix stripped
+- Never commit `.env` or `auth.json` to version control