better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,237 +0,0 @@
----
-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

@@ -1,142 +0,0 @@
----
-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

@@ -1,308 +0,0 @@
----
-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
-```