better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/context-files.md

@@ -0,0 +1,237 @@
+---
+sidebar_position: 8
+title: "Context Files"
+description: "Project context files — .hermes.md, AGENTS.md, CLAUDE.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
+---
+
+# Context Files
+
+Hermes Agent automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory. `SOUL.md` is now global to the Hermes instance and is loaded from `HERMES_HOME` only.
+
+## Supported Context Files
+
+| File | Purpose | Discovery |
+|------|---------|-----------| 
+| **.hermes.md** / **HERMES.md** | Project instructions (highest priority) | Walks to git root |
+| **AGENTS.override.md** | Personal, per-directory override of AGENTS.md (typically gitignored) | CWD at startup + subdirectories progressively |
+| **AGENTS.md** | Project instructions, conventions, architecture | CWD at startup + subdirectories progressively |
+| **CLAUDE.md** | Claude Code context files (also detected) | CWD at startup + subdirectories progressively |
+| **SOUL.md** | Global personality and tone customization for this Hermes instance | `HERMES_HOME/SOUL.md` only |
+| **.cursorrules** | Cursor IDE coding conventions | CWD only |
+| **.cursor/rules/*.mdc** | Cursor IDE rule modules | CWD only |
+
+:::info Priority system
+Only **one** project context type is loaded per session (first match wins): `.hermes.md` → `AGENTS.override.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`. **SOUL.md** is always loaded independently as the agent identity (slot #1).
+
+If an `AGENTS.override.md` exists next to an `AGENTS.md`, the override is loaded **instead of** the committed file — keep a personal (usually gitignored) `AGENTS.override.md` when you want different instructions than the ones checked into the repo, without editing the tracked `AGENTS.md`.
+:::
+
+## AGENTS.md
+
+`AGENTS.md` is the primary project context file. It tells the agent how your project is structured, what conventions to follow, and any special instructions.
+
+### Directory Chain (git root → working directory)
+
+When your working directory sits inside a git repository, Hermes loads a **merged chain** of `AGENTS.md` files at session start: the git-root `AGENTS.md` first, then the `AGENTS.md` in every intermediate directory down to your working directory. Deeper files appear later in the prompt, so more specific guidance takes precedence. Each file gets its own provenance header (e.g. `## ../../AGENTS.md`), and identical copies along the chain are deduplicated.
+
+```
+monorepo/                   (git root, cwd = packages/webapp/)
+├── AGENTS.md              ← Loaded first (repo-wide conventions)
+└── packages/
+    ├── AGENTS.md          ← Loaded second
+    └── webapp/
+        └── AGENTS.md      ← Loaded last (most specific, takes precedence)
+```
+
+Outside a git repository, only the working directory itself is checked — parents are never consulted, so an `AGENTS.md` planted in `/tmp` or `$HOME` can't leak into unrelated sessions.
+
+### Progressive Subdirectory Discovery
+
+At session start, Hermes loads the `AGENTS.md` from your working directory into the system prompt. As the agent navigates into subdirectories during the session (via `read_file`, `terminal`, `search_files`, etc.), it **progressively discovers** context files in those directories and injects them into the conversation at the moment they become relevant.
+
+```
+my-project/
+├── AGENTS.md              ← Loaded at startup (system prompt)
+├── frontend/
+│   └── AGENTS.md          ← Discovered when agent reads frontend/ files
+├── backend/
+│   └── AGENTS.md          ← Discovered when agent reads backend/ files
+└── shared/
+    └── AGENTS.md          ← Discovered when agent reads shared/ files
+```
+
+This approach has two advantages over loading everything at startup:
+- **No system prompt bloat** — subdirectory hints only appear when needed
+- **Prompt cache preservation** — the system prompt stays stable across turns
+
+Each subdirectory is checked at most once per session. The discovery also walks up parent directories, so reading `backend/src/main.py` will discover `backend/AGENTS.md` even if `backend/src/` has no context file of its own.
+
+:::info
+Subdirectory context files go through the same [security scan](#security-prompt-injection-protection) as startup context files. Malicious files are blocked.
+:::
+
+### Example AGENTS.md
+
+```markdown
+# Project Context
+
+This is a Next.js 14 web application with a Python FastAPI backend.
+
+## Architecture
+- Frontend: Next.js 14 with App Router in `/frontend`
+- Backend: FastAPI in `/backend`, uses SQLAlchemy ORM
+- Database: PostgreSQL 16
+- Deployment: Docker Compose on a Hetzner VPS
+
+## Conventions
+- Use TypeScript strict mode for all frontend code
+- Python code follows PEP 8, use type hints everywhere
+- All API endpoints return JSON with `{data, error, meta}` shape
+- Tests go in `__tests__/` directories (frontend) or `tests/` (backend)
+
+## Important Notes
+- Never modify migration files directly — use Alembic commands
+- The `.env.local` file has real API keys, don't commit it
+- Frontend port is 3000, backend is 8000, DB is 5432
+```
+
+## SOUL.md
+
+`SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](/user-guide/features/personality) page for full details.
+
+**Location:**
+
+- `~/.hermes/SOUL.md`
+- or `$HERMES_HOME/SOUL.md` if you run Hermes with a custom home directory
+
+Important details:
+
+- Hermes seeds a default `SOUL.md` automatically if one does not exist yet
+- Hermes loads `SOUL.md` only from `HERMES_HOME`
+- Hermes does not probe the working directory for `SOUL.md`
+- If the file is empty, nothing from `SOUL.md` is added to the prompt
+- If the file has content, the content is injected verbatim after scanning and truncation
+
+## .cursorrules
+
+Hermes is compatible with Cursor IDE's `.cursorrules` file and `.cursor/rules/*.mdc` rule modules. If these files exist in your project root and no higher-priority context file (`.hermes.md`, `AGENTS.md`, or `CLAUDE.md`) is found, they're loaded as the project context.
+
+This means your existing Cursor conventions automatically apply when using Hermes.
+
+## How Context Files Are Loaded
+
+### At startup (system prompt)
+
+Context files are loaded by `build_context_files_prompt()` in `agent/prompt_builder.py`:
+
+1. **Scan working directory** — checks for `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules` (first match wins)
+2. **Content is read** — each file is read as UTF-8 text
+3. **Security scan** — content is checked for prompt injection patterns
+4. **Truncation** — files exceeding the character cap are head/tail truncated (70% head, 20% tail, with a marker in the middle). The cap is an explicit `context_file_max_chars` from config.yaml when set; otherwise it scales dynamically with the model's context window (floor 20,000 chars, ceiling 500,000)
+5. **Assembly** — all sections are combined under a `# Project Context` header
+6. **Injection** — the assembled content is added to the system prompt
+
+### During the session (progressive discovery)
+
+`SubdirectoryHintTracker` in `agent/subdirectory_hints.py` watches tool call arguments for file paths:
+
+1. **Path extraction** — after each tool call, file paths are extracted from arguments (`path`, `workdir`, shell commands)
+2. **Ancestor walk** — the directory and up to 5 parent directories are checked (stopping at already-visited directories)
+3. **Hint loading** — if an `AGENTS.md`, `CLAUDE.md`, or `.cursorrules` is found, it's loaded (first match per directory)
+4. **Security scan** — same prompt injection scan as startup files
+5. **Truncation** — capped at 32,000 characters per file (a fixed preview cap; `context_file_max_chars` and the model's context window do not change it). An oversized hint keeps its head/tail marker pointing at the full file and is logged, but does not raise the chat truncation warning that startup context files do
+6. **Injection** — appended to the tool result, so the model sees it in context naturally
+
+The final prompt section looks roughly like:
+
+```text
+# Project Context
+
+The following project context files have been loaded and should be followed:
+
+## AGENTS.md
+
+[Your AGENTS.md content here]
+
+## .cursorrules
+
+[Your .cursorrules content here]
+
+[Your SOUL.md content here]
+```
+
+Notice that SOUL content is inserted directly, without extra wrapper text.
+
+## Security: Prompt Injection Protection
+
+All context files are scanned for potential prompt injection before being included. The scanner checks for:
+
+- **Instruction override attempts**: "ignore previous instructions", "disregard your rules"
+- **Deception patterns**: "do not tell the user"
+- **System prompt overrides**: "system prompt override"
+- **Hidden HTML comments**: `<!-- ignore instructions -->`
+- **Hidden div elements**: `<div style="display:none">`
+- **Credential exfiltration**: `curl ... $API_KEY`
+- **Secret file access**: `cat .env`, `cat credentials`
+- **Invisible characters**: zero-width spaces, bidirectional overrides, word joiners
+
+If any threat pattern is detected, the file is blocked:
+
+```
+[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]
+```
+
+:::warning
+This scanner protects against common injection patterns, but it's not a substitute for reviewing context files in shared repositories. Always validate AGENTS.md content in projects you didn't author.
+:::
+
+## Size Limits
+
+| Limit | Value |
+|-------|-------|
+| Max chars per file | `context_file_max_chars` when set; otherwise dynamic (scales with model context window, floor 20,000, ceiling 500,000) |
+| Read timeout per file | `context_file_read_timeout` (default 5 seconds); a file that takes longer to read — e.g. on iCloud Drive, OneDrive or NFS — is skipped with a warning |
+| Head truncation ratio | 70% |
+| Tail truncation ratio | 20% |
+| Truncation marker | 10% (shows char counts and suggests using file tools) |
+
+When a file exceeds the configured limit, the truncation message reads:
+
+```
+[...truncated AGENTS.md: kept 14000+4000 of 25000 chars. Use file tools to read the full file.]
+```
+
+## Tips for Effective Context Files
+
+:::tip Best practices for AGENTS.md
+1. **Keep it concise** — stay under your configured `context_file_max_chars`; the agent reads it every turn
+2. **Structure with headers** — use `##` sections for architecture, conventions, important notes
+3. **Include concrete examples** — show preferred code patterns, API shapes, naming conventions
+4. **Mention what NOT to do** — "never modify migration files directly"
+5. **List key paths and ports** — the agent uses these for terminal commands
+6. **Update as the project evolves** — stale context is worse than no context
+:::
+
+### Per-Subdirectory Context
+
+For monorepos, put subdirectory-specific instructions in nested AGENTS.md files:
+
+```markdown
+<!-- frontend/AGENTS.md -->
+# Frontend Context
+
+- Use `pnpm` not `npm` for package management
+- Components go in `src/components/`, pages in `src/app/`
+- Use Tailwind CSS, never inline styles
+- Run tests with `pnpm test`
+```
+
+```markdown
+<!-- backend/AGENTS.md -->
+# Backend Context
+
+- Use `poetry` for dependency management
+- Run the dev server with `poetry run uvicorn main:app --reload`
+- All endpoints need OpenAPI docstrings
+- Database models are in `models/`, schemas in `schemas/`
+```

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/context-references.md

@@ -0,0 +1,142 @@
+---
+sidebar_position: 9
+sidebar_label: "Context References"
+title: "Context References"
+description: "Inline @-syntax for attaching files, folders, git diffs, and URLs directly into your messages"
+---
+
+# Context References
+
+Type `@` followed by a reference to inject content directly into your message. Hermes expands the reference inline and appends the content under an `--- Attached Context ---` section.
+
+## Supported References
+
+| Syntax | Description |
+|--------|-------------|
+| `@file:path/to/file.py` | Inject file contents |
+| `@file:path/to/file.py:10-25` | Inject specific line range (1-indexed, inclusive) |
+| `@folder:path/to/dir` | Inject directory tree listing with file metadata |
+| `@diff` | Inject `git diff` (unstaged working tree changes) |
+| `@staged` | Inject `git diff --staged` (staged changes) |
+| `@git:5` | Inject last N commits with patches (max 10) |
+| `@url:https://example.com` | Fetch and inject web page content |
+
+## Usage Examples
+
+```text
+Review @file:src/main.py and suggest improvements
+
+What changed? @diff
+
+Compare @file:old_config.yaml and @file:new_config.yaml
+
+What's in @folder:src/components?
+
+Summarize this article @url:https://arxiv.org/abs/2301.00001
+```
+
+Multiple references work in a single message:
+
+```text
+Check @file:main.py, and also @file:test.py.
+```
+
+Trailing punctuation (`,`, `.`, `;`, `!`, `?`) is automatically stripped from reference values.
+
+## CLI Tab Completion
+
+In the interactive CLI, typing `@` triggers autocomplete:
+
+- `@` shows all reference types (`@diff`, `@staged`, `@file:`, `@folder:`, `@git:`, `@url:`)
+- `@file:` and `@folder:` trigger filesystem path completion with file size metadata
+- Bare `@` followed by partial text shows matching files and folders from the current directory
+
+## Line Ranges
+
+The `@file:` reference supports line ranges for precise content injection:
+
+```text
+@file:src/main.py:42        # Single line 42
+@file:src/main.py:10-25     # Lines 10 through 25 (inclusive)
+```
+
+Lines are 1-indexed. Invalid ranges are silently ignored (full file is returned).
+
+## Size Limits
+
+Context references are bounded to prevent overwhelming the model's context window:
+
+| Threshold | Value | Behavior |
+|-----------|-------|----------|
+| Soft limit | 25% of context length | Warning appended, expansion proceeds |
+| Hard limit | 50% of context length | Expansion refused, original message returned unchanged |
+| Folder entries | 200 files max | Excess entries replaced with `- ...` |
+| Git commits | 10 max | `@git:N` clamped to range [1, 10] |
+
+## Security
+
+### Sensitive Path Blocking
+
+These paths are always blocked from `@file:` references to prevent credential exposure:
+
+- SSH keys and config: `~/.ssh/id_rsa`, `~/.ssh/id_ed25519`, `~/.ssh/authorized_keys`, `~/.ssh/config`
+- Shell profiles: `~/.bashrc`, `~/.zshrc`, `~/.profile`, `~/.bash_profile`, `~/.zprofile`
+- Credential files: `~/.netrc`, `~/.pgpass`, `~/.npmrc`, `~/.pypirc`
+- Hermes env: `$HERMES_HOME/.env`
+
+These directories are fully blocked (any file inside):
+- `~/.ssh/`, `~/.aws/`, `~/.gnupg/`, `~/.kube/`, `$HERMES_HOME/skills/.hub/`
+
+### Path Traversal Protection
+
+All paths are resolved relative to the working directory. References that resolve outside the allowed workspace root are rejected.
+
+### Binary File Detection
+
+Binary files are detected via MIME type and null-byte scanning. Known text extensions (`.py`, `.md`, `.json`, `.yaml`, `.toml`, `.js`, `.ts`, etc.) bypass MIME-based detection. Binary files are rejected with a warning.
+
+## Platform Availability
+
+Context references are primarily a **CLI feature**. They work in the interactive CLI where `@` triggers tab completion and references are expanded before the message is sent to the agent.
+
+In **messaging platforms** (Telegram, Discord, etc.), the `@` syntax is not expanded by the gateway — messages are passed through as-is. The agent itself can still reference files via the `read_file`, `search_files`, and `web_extract` tools.
+
+## Interaction with Context Compression
+
+When conversation context is compressed, the expanded reference content is included in the compression summary. This means:
+
+- Large file contents injected via `@file:` contribute to context usage
+- If the conversation is later compressed, the file content is summarized (not preserved verbatim)
+- For very large files, consider using line ranges (`@file:main.py:100-200`) to inject only relevant sections
+
+## Common Patterns
+
+```text
+# Code review workflow
+Review @diff and check for security issues
+
+# Debug with context
+This test is failing. Here's the test @file:tests/test_auth.py
+and the implementation @file:src/auth.py:50-80
+
+# Project exploration
+What does this project do? @folder:src @file:README.md
+
+# Research
+Compare the approaches in @url:https://arxiv.org/abs/2301.00001
+and @url:https://arxiv.org/abs/2301.00002
+```
+
+## Error Handling
+
+Invalid references produce inline warnings rather than failures:
+
+| Condition | Behavior |
+|-----------|----------|
+| File not found | Warning: "file not found" |
+| Binary file | Warning: "binary files are not supported" |
+| Folder not found | Warning: "folder not found" |
+| Git command fails | Warning with git stderr |
+| URL returns no content | Warning: "no content extracted" |
+| Sensitive path | Warning: "path is a sensitive credential file" |
+| Path outside workspace | Warning: "path is outside the allowed workspace" |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/credential-pools.md

@@ -0,0 +1,308 @@
+---
+title: Credential Pools
+description: Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery.
+sidebar_label: Credential Pools
+sidebar_position: 9
+---
+
+# Credential Pools
+
+Credential pools let you register multiple API keys or OAuth tokens for the same provider. When one key hits a rate limit or billing quota, Hermes automatically rotates to the next healthy key — keeping your session alive without switching providers.
+
+This is different from [fallback providers](./fallback-providers.md), which switch to a *different* provider entirely. Credential pools are same-provider rotation; fallback providers are cross-provider failover. Pools are tried first — if all pool keys are exhausted, *then* the fallback provider activates.
+
+:::warning Key rotation resets the prompt cache
+Provider-side prompt caches (Anthropic, OpenAI, OpenRouter) are scoped to the account/API key that made the request. When the pool rotates to a different key mid-session, the new key has no cached prefix for your conversation — the next request re-reads the full history at undiscounted input price, and rotating back later is another full re-read unless the earlier key's cache TTL is still alive. Rotation keeps your session running, which is the point, but on long conversations each rotation costs one full-price pass over the context.
+:::
+
+:::tip
+Credential pools are mainly for API-key providers (OpenRouter, Anthropic). A single [Nous Portal](/integrations/nous-portal) OAuth covers 300+ models, so most users don't need a pool when on Portal.
+:::
+
+## How It Works
+
+```
+Your request
+  → Pick key from pool (round_robin / least_used / fill_first / random)
+  → Send to provider
+  → 429 rate limit?
+      → Plan/usage limit reached (e.g. ChatGPT/Codex "usage limit reached")?
+          → Rotate to next pool key immediately (no retry — the cap won't clear on retry)
+      → Generic / transient 429?
+          → Retry same key once (transient blip)
+          → Second 429 → rotate to next pool key
+      → All keys exhausted → fallback_model (different provider)
+  → 402 billing error?
+      → Immediately rotate to next pool key (1h cooldown)
+  → 401 auth expired?
+      → Try refreshing the token (OAuth)
+      → Refresh failed → rotate to next pool key
+  → Success → continue normally
+```
+
+## Quick Start
+
+If you already have an API key set in `.env`, Hermes auto-discovers it as a 1-key pool. To benefit from pooling, add more keys:
+
+```bash
+# Add a second OpenRouter key
+hermes auth add openrouter --api-key sk-or-v1-your-second-key
+
+# ...or let a browser login mint one (OpenRouter OAuth PKCE; stored as a plain API key)
+hermes auth add openrouter --type oauth
+
+# 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 (requires Claude Max plan + extra usage credits)
+hermes auth add anthropic --type oauth
+# Opens browser for OAuth login
+```
+
+Check your pools:
+
+```bash
+hermes auth list
+```
+
+Output:
+```
+openrouter (2 credentials):
+  #1  OPENROUTER_API_KEY   api_key id=ab12cd34 priority=0 env:OPENROUTER_API_KEY ←
+  #2  backup-key           api_key id=ef56gh78 priority=1 manual
+
+anthropic (3 credentials):
+  #1  hermes_pkce          oauth   id=ab12cd34 priority=0 hermes_pkce ←
+  #2  claude_code          oauth   id=cd34ef56 priority=1 claude_code
+  #3  ANTHROPIC_API_KEY    api_key id=ef56gh78 priority=2 env:ANTHROPIC_API_KEY
+```
+
+The `←` marks the currently selected credential. `id=` is the entry id accepted by
+`hermes auth remove <provider> <target>` when a label is ambiguous, and `priority=` is
+the order the pool tries credentials in under the `fill_first` strategy.
+
+## Interactive Management
+
+Run `hermes auth` with no subcommand for an interactive wizard:
+
+```bash
+hermes auth
+```
+
+This shows your full pool status and offers a menu:
+
+```
+What would you like to do?
+  1. Add a credential
+  2. Remove a credential
+  3. Reset cooldowns for a provider
+  4. Set rotation strategy for a provider
+  5. Exit
+```
+
+For providers that support both API keys and OAuth (Anthropic, Nous, Codex), the add flow asks which type:
+
+```
+anthropic supports both API keys and OAuth login.
+  1. API key (paste a key from the provider dashboard)
+  2. OAuth login (authenticate via browser)
+Type [1/2]:
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `hermes auth` | Interactive pool management wizard |
+| `hermes auth list` | Show all pools and credentials |
+| `hermes auth list <provider>` | Show a specific provider's pool |
+| `hermes auth add <provider>` | Add a credential (prompts for type and key) |
+| `hermes auth add <provider> --type api-key --api-key <key>` | Add an API key non-interactively |
+| `hermes auth add <provider> --type oauth` | Add an OAuth credential via browser login |
+| `hermes auth add <provider> --priority 0` | Add a credential and place it first in the `fill_first` order |
+| `hermes auth priority <provider> <target> <n>` | Move a credential to priority `n` (0 = tried first); the rest are renumbered |
+| `hermes auth remove <provider> <index>` | Remove credential by 1-based index |
+| `hermes auth reset <provider>` | Clear all cooldowns/exhaustion status |
+| `hermes auth reset <provider> <target>` | Clear the cooldown on one credential by index, id, or label |
+| `hermes auth refresh <provider> [target]` | Refresh one OAuth credential's tokens and return it to rotation (proves the grant is alive; the next request re-checks quota) |
+
+For Nous, `auth refresh` supports only the login's `device_code` singleton.
+Independent Nous pool accounts are rejected before refresh; their tokens and
+cooldowns are preserved. Reauthenticate with `hermes auth add nous --type oauth`
+to update the singleton; this does not refresh an independent account. Other
+providers retain their existing source-specific refresh support.
+
+## Rotation Strategies
+
+Priority positions are zero-based and clamp to the pool's ends; displayed targets
+are one-based indices, entry IDs, or unambiguous exact labels. `auth add --priority`
+also places an existing entry updated by reauthentication. Anthropic keeps manual
+credentials ahead of seeded credentials, so the command reports the effective
+position when that rule changes it. Other strategies may override priority, and
+reordering does not rebind credentials already held by a running session.
+
+Every successful pool selection increments `request_count`, regardless of strategy.
+Refresh-only lookups and peeks do not count. These are selection counters, not
+billing totals or a count of every inference request: a cached credential can serve
+multiple requests. Counts remain in memory until the next existing pool write
+(for example rotation, exhaustion, refresh, or an administrative change); this does
+not add a disk write per selection.
+
+Configure via `hermes auth` → "Set rotation strategy" or in `config.yaml`:
+
+```yaml
+credential_pool_strategies:
+  openrouter: round_robin
+  anthropic: least_used
+```
+
+| Strategy | Behavior |
+|----------|----------|
+| `fill_first` (default) | Use the first healthy key until it's exhausted, then move to the next; order is each credential's `priority` (`hermes auth priority` changes it) |
+| `round_robin` | Cycle through keys evenly, rotating after each selection |
+| `least_used` | Always pick the key with the lowest request count |
+| `random` | Random selection among healthy keys |
+
+## Error Recovery
+
+The pool handles different errors differently:
+
+| Error | Behavior | Cooldown |
+|-------|----------|----------|
+| **429 Rate Limit** | Retry same key once (transient). Second consecutive 429 rotates to next key | 1 hour |
+| **402 Billing/Quota** | Immediately rotate to next key | 1 hour |
+| **401 Auth Expired** | Try refreshing the OAuth token first. Rotate only if refresh fails | 5 minutes |
+| **All keys exhausted** | Fall through to `fallback_model` if configured | — |
+
+Provider-supplied `reset_at` timestamps override these default cooldowns.
+
+The `has_retried_429` flag resets on every successful API call, so a single transient 429 doesn't trigger rotation.
+
+## Custom Endpoint Pools
+
+Custom OpenAI-compatible endpoints (Together.ai, RunPod, local servers) get their own pools, keyed by the endpoint name from the `providers:` dict in config.yaml (or the legacy `custom_providers` list, which is auto-migrated).
+
+When you set up a custom endpoint via `hermes model`, it auto-generates a name like "Together.ai" or "Local (localhost:8080)". This name becomes the pool key.
+
+```bash
+# After setting up a custom endpoint via hermes model:
+hermes auth list
+# Shows:
+#   Together.ai (1 credential):
+#     #1  config key    api_key config:Together.ai ←
+
+# Add a second key for the same endpoint:
+hermes auth add Together.ai --api-key sk-together-second-key
+```
+
+Custom endpoint pools are stored in `auth.json` under `credential_pool` with a `custom:` prefix:
+
+```json
+{
+  "credential_pool": {
+    "openrouter": [...],
+    "custom:together.ai": [...]
+  }
+}
+```
+
+## Auto-Discovery
+
+Hermes automatically discovers credentials from multiple sources and seeds the pool on startup:
+
+| Source | Example | Auto-seeded? |
+|--------|---------|-------------|
+| Environment variables | `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` | Yes |
+| Numbered env siblings | `OPENROUTER_API_KEY_2`, `OPENROUTER_API_KEY_3`, … | Yes (see below) |
+| OAuth tokens (auth.json) | Codex device code, Nous device code | Yes |
+| Claude Code credentials | `~/.claude/.credentials.json` | Yes (Anthropic) |
+| Hermes PKCE OAuth | `~/.hermes/auth.json` | Yes (Anthropic) |
+| Custom endpoint config | `model.api_key` in config.yaml | Yes (custom endpoints) |
+| Manual entries | Added via `hermes auth add` | Persisted in auth.json |
+
+Auto-seeded entries are updated on each pool load — if you remove an env var, its pool entry is automatically pruned. Manual entries (added via `hermes auth add`) are never auto-pruned.
+
+### Several keys from the environment
+
+Want more than one key for a provider without storing any of them in `auth.json`? Number them. Next to `NVIDIA_API_KEY` set `NVIDIA_API_KEY_2`, `NVIDIA_API_KEY_3`, … in your shell, `.env`, or secret manager (Bitwarden Secrets, Vault, …) and each becomes its own pool entry on the next load — no command, no config. Discovery stops at the first missing number, so a stray `_5` with no `_4` is ignored. Combine with `credential_pool_strategies` to rotate them:
+
+```yaml
+credential_pool_strategies:
+  nvidia: round_robin
+```
+
+Borrowed runtime secrets (for example env vars, Bitwarden/Vault/keyring/systemd references, and custom config values) are reference-only at the `auth.json` boundary. Hermes can use the resolved value in memory for the current run, but it persists only metadata such as the source ref, label, status, request counters, and a non-reversible fingerprint. Manual entries and Hermes-owned OAuth/device-code state keep the durable tokens they need to refresh.
+
+## Delegation & Subagent Sharing
+
+When the agent spawns subagents via `delegate_task`, the parent's credential pool is automatically shared with children:
+
+- **Same provider** — the child receives the parent's full pool, enabling key rotation on rate limits
+- **Different provider** — the child loads that provider's own pool (if configured)
+- **No pool configured** — the child falls back to the inherited single API key
+
+This means subagents benefit from the same rate-limit resilience as the parent, with no extra configuration needed. Per-task credential leasing ensures children don't conflict with each other when rotating keys concurrently.
+
+## Thread Safety
+
+The credential pool uses a threading lock for all state mutations (`select()`, `mark_exhausted_and_rotate()`, `try_refresh_current()`, `mark_used()`). This ensures safe concurrent access when the gateway handles multiple chat sessions simultaneously.
+
+Across processes (many subagents, a gateway plus a CLI, cron jobs), OAuth refreshes are serialized through a file lock on `auth.json`. When one shared OAuth grant expires under many concurrent processes, exactly one process performs the refresh; the others detect that the on-disk token no longer matches the one that failed and adopt it instead of rotating the single-use refresh token again. A process that loses the lock race keeps its entry healthy and retries — lock contention is never recorded as a credential failure.
+
+## Architecture
+
+For the full data flow diagram, see [`docs/credential-pool-flow.excalidraw`](https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g) in the repository.
+
+The credential pool integrates at the provider resolution layer:
+
+1. **`agent/credential_pool.py`** — Pool manager: storage, selection, rotation, cooldowns; **`agent/credential_pool_admin.py`** owns locked target resolution, reset, add, removal, and priority mutations
+2. **`hermes_cli/auth_commands.py`** — CLI commands and interactive wizard
+3. **`hermes_cli/runtime_provider.py`** — Pool-aware credential resolution
+4. **`agent/turn_api_error.py`** — Error recovery: 429/402/401 → pool rotation → fallback
+
+## Storage
+
+Pool state is stored in `~/.hermes/auth.json` under the `credential_pool` key:
+
+```json
+{
+  "version": 1,
+  "credential_pool": {
+    "openrouter": [
+      {
+        "id": "abc123",
+        "label": "OPENROUTER_API_KEY",
+        "auth_type": "api_key",
+        "priority": 0,
+        "source": "env:OPENROUTER_API_KEY",
+        "secret_source": "bitwarden",
+        "secret_fingerprint": "sha256:12ab34cd56ef7890",
+        "last_status": "ok",
+        "request_count": 142
+      }
+    ],
+    "anthropic": [
+      {
+        "id": "manual1",
+        "label": "personal-api-key",
+        "auth_type": "api_key",
+        "priority": 0,
+        "source": "manual",
+        "access_token": "sk-ant-api03-..."
+      }
+    ]
+  }
+}
+```
+
+The OpenRouter entry above was borrowed from an external source, so the raw key is not stored in `auth.json`. The manual Anthropic entry was intentionally added to Hermes' credential store, so its token remains persistable.
+
+An `env:` row is re-hydrated from the environment on every load, and the variable name does not have to be one Hermes declares for the provider: numbered siblings (`OPENROUTER_API_KEY_2`, see [Auto-Discovery](#auto-discovery)) appear here automatically, and a hand-written row pointing at any other variable is filled the same way, without the secret ever being written to `auth.json`.
+
+Strategies are stored in `config.yaml` (not `auth.json`):
+
+```yaml
+credential_pool_strategies:
+  openrouter: round_robin
+  anthropic: least_used
+```