From a710becd6c57a21a7be547b60c910b5dbd0847a9 Mon Sep 17 00:00:00 2001 From: kocaemre Date: Sun, 31 May 2026 22:44:17 +0300 Subject: [PATCH] docs: fix 25 documentation/code inconsistencies (audit round 3) Cross-checked website/docs against the source at main HEAD and corrected documented commands, env vars, config keys, headers, and default values that don't match the code. Docs-only; no behavioral changes. Refs #36048 Co-Authored-By: Claude Opus 4.8 (1M context) --- website/docs/developer-guide/programmatic-integration.md | 2 +- website/docs/developer-guide/session-storage.md | 2 +- website/docs/guides/cron-troubleshooting.md | 2 +- website/docs/guides/team-telegram-assistant.md | 2 +- website/docs/guides/tips.md | 4 ++-- website/docs/integrations/index.md | 2 +- website/docs/integrations/providers.md | 2 +- website/docs/reference/environment-variables.md | 2 -- website/docs/reference/tools-reference.md | 2 +- website/docs/user-guide/configuring-models.md | 2 +- website/docs/user-guide/features/codex-app-server-runtime.md | 4 ++-- website/docs/user-guide/features/overview.md | 2 +- website/docs/user-guide/features/tts.md | 2 +- website/docs/user-guide/features/web-dashboard.md | 2 +- website/docs/user-guide/features/web-search.md | 4 ++-- website/docs/user-guide/messaging/telegram.md | 2 +- 16 files changed, 18 insertions(+), 20 deletions(-) diff --git a/website/docs/developer-guide/programmatic-integration.md b/website/docs/developer-guide/programmatic-integration.md index 16963bdd08f9..39a3bae2ff48 100644 --- a/website/docs/developer-guide/programmatic-integration.md +++ b/website/docs/developer-guide/programmatic-integration.md @@ -118,7 +118,7 @@ Mid-session model switching works on every surface — it's the `/model` slash c - **CLI / TUI:** `/model claude-sonnet-4` or `/model openrouter:anthropic/claude-sonnet-4.6` - **TUI gateway RPC:** `command.dispatch` with `{"command": "/model claude-sonnet-4"}` - **ACP:** the IDE sends the slash command as a prompt; the agent dispatches it -- **API server:** include a `model` field in the request body or set `X-Hermes-Model` +- **API server:** include a `model` field in the request body Provider-aware resolution (the same model name picks the right format for whatever provider you're on) is built in. See `hermes_cli/model_switch.py`. diff --git a/website/docs/developer-guide/session-storage.md b/website/docs/developer-guide/session-storage.md index 55da265595cd..5bcb70c485cb 100644 --- a/website/docs/developer-guide/session-storage.md +++ b/website/docs/developer-guide/session-storage.md @@ -133,7 +133,7 @@ END; ## Schema Version and Migrations -Current schema version: **11** +Current schema version: **14** The `schema_version` table stores a single integer. Simple column additions are handled declaratively by `_reconcile_columns()` (which diffs live columns against `SCHEMA_SQL` and ADDs any missing ones). The version-gated chain is reserved for data migrations and index/FTS changes that can't be expressed declaratively: diff --git a/website/docs/guides/cron-troubleshooting.md b/website/docs/guides/cron-troubleshooting.md index f24e2dd3f6c6..2f2cb43b3465 100644 --- a/website/docs/guides/cron-troubleshooting.md +++ b/website/docs/guides/cron-troubleshooting.md @@ -111,7 +111,7 @@ Skills must be installed before they can be attached to cron jobs. If a skill is ### Check 2: Check skill name vs. skill folder name -Skill names are case-sensitive and must match the installed skill's folder name. If your job specifies `ai-funding-daily-report` but the skill folder is `ai-funding-daily-report`, confirm the exact name from `hermes skills list`. +Skill names are case-sensitive and must match the installed skill's folder name. If your job specifies `ai-funding-report` but the skill folder is `ai-funding-daily-report`, confirm the exact name from `hermes skills list`. ### Check 3: Skills that require interactive tools diff --git a/website/docs/guides/team-telegram-assistant.md b/website/docs/guides/team-telegram-assistant.md index 1341f9b4ed72..3b168eb4caf4 100644 --- a/website/docs/guides/team-telegram-assistant.md +++ b/website/docs/guides/team-telegram-assistant.md @@ -374,7 +374,7 @@ On a shared team bot, use Docker as the terminal backend so agent commands run i ```bash # In ~/.hermes/.env -TERMINAL_BACKEND=docker +TERMINAL_ENV=docker TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20 ``` diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md index fd4501080a0d..7e51f2b766e9 100644 --- a/website/docs/guides/tips.md +++ b/website/docs/guides/tips.md @@ -181,11 +181,11 @@ By default, messaging sessions never auto-reset — context lives until you `/re ### Use Docker for Untrusted Code -When working with untrusted repositories or running unfamiliar code, use Docker or Daytona as your terminal backend. Set `TERMINAL_BACKEND=docker` in your `.env`. Destructive commands inside a container can't harm your host system. +When working with untrusted repositories or running unfamiliar code, use Docker or Daytona as your terminal backend. Set `TERMINAL_ENV=docker` in your `.env`. Destructive commands inside a container can't harm your host system. ```bash # In your .env: -TERMINAL_BACKEND=docker +TERMINAL_ENV=docker TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest ``` diff --git a/website/docs/integrations/index.md b/website/docs/integrations/index.md index 90bd0a4042a6..7f4e1f17679e 100644 --- a/website/docs/integrations/index.md +++ b/website/docs/integrations/index.md @@ -16,7 +16,7 @@ If you only have time to set up one integration, set up [Nous Portal](/integrati Hermes supports multiple AI inference providers out of the box. Use `hermes model` to configure interactively, or set them in `config.yaml`. -- **[AI Providers](/user-guide/features/provider-routing)** — OpenRouter, Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Hermes auto-detects capabilities like vision, streaming, and tool use per provider. +- **[AI Providers](/integrations/providers)** — OpenRouter, Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Hermes auto-detects capabilities like vision, streaming, and tool use per provider. - **[Provider Routing](/user-guide/features/provider-routing)** — Fine-grained control over which underlying providers handle your OpenRouter requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and explicit priority ordering. - **[Fallback Providers](/user-guide/features/fallback-providers)** — Automatic failover to backup LLM providers when your primary model encounters errors. Includes primary model fallback and independent auxiliary task fallback for vision, compression, and web extraction. diff --git a/website/docs/integrations/providers.md b/website/docs/integrations/providers.md index e9e94d086305..343a056fe886 100644 --- a/website/docs/integrations/providers.md +++ b/website/docs/integrations/providers.md @@ -82,7 +82,7 @@ Don't have a subscription yet? Get one at [portal.nousresearch.com/manage-subscr :::info Codex Note The OpenAI Codex provider authenticates via device code (open a URL, enter a code). Hermes stores the resulting credentials in its own auth store under `~/.hermes/auth.json` and can import existing Codex CLI credentials from `~/.codex/auth.json` when present. No Codex CLI installation is required. -If a token refresh fails with a terminal error (HTTP 4xx, `invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and stops replaying it so you don't see a flood of identical auth failures. The next request surfaces a typed re-auth message instead. Run `hermes auth add codex-oauth` (or `hermes model` → OpenAI Codex) to start a fresh device-code login; the quarantine clears on the next successful exchange. +If a token refresh fails with a terminal error (HTTP 4xx, `invalid_grant`, revoked grant, etc.), Hermes marks the refresh token as dead and stops replaying it so you don't see a flood of identical auth failures. The next request surfaces a typed re-auth message instead. Run `hermes auth add openai-codex` (or `hermes model` → OpenAI Codex) to start a fresh device-code login; the quarantine clears on the next successful exchange. ::: :::warning diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/environment-variables.md index b41cbe7e24b5..873882958bbb 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/environment-variables.md @@ -720,7 +720,6 @@ Advanced per-platform knobs for throttling the outbound message batcher. Most us | `HERMES_IGNORE_USER_CONFIG` | Skip `~/.hermes/config.yaml` and use built-in defaults (credentials in `.env` still load). Equivalent to `--ignore-user-config`. | | `HERMES_IGNORE_RULES` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, memory, and preloaded skills. Equivalent to `--ignore-rules`. | | `HERMES_SAFE_MODE` | Troubleshooting mode: disable ALL customizations — skips plugin discovery, MCP server loading, and shell-hook registration. Set automatically by `--safe-mode` (which also sets the two flags above). | -| `HERMES_MD_NAMES` | Comma-separated list of rules-file names to auto-inject (default: `AGENTS.md,CLAUDE.md,.cursorrules,SOUL.md`). | | `HERMES_TOOL_PROGRESS` | Deprecated compatibility variable for tool progress display. Prefer `display.tool_progress` in `config.yaml`. | | `HERMES_TOOL_PROGRESS_MODE` | Deprecated compatibility variable for tool progress mode. Prefer `display.tool_progress` in `config.yaml`. | | `HERMES_HUMAN_DELAY_MODE` | Response pacing: `off`/`natural`/`custom` | @@ -750,7 +749,6 @@ Advanced per-platform knobs for throttling the outbound message batcher. Most us | `HERMES_WRITE_SAFE_ROOT` | Optional directory prefix that **hard-blocks** `write_file`/`patch` writes outside the listed roots (no approval prompt). Supports multiple directories separated by `os.pathsep` (`:` on Unix, `;` on Windows). See [HERMES_WRITE_SAFE_ROOT](#hermes_write_safe_root) below. | | `HERMES_DISABLE_LAZY_INSTALLS` | Internal bridge var set automatically in the official Docker image to prevent runtime dependency installs into the immutable `/opt/hermes` tree. The user-facing equivalent is `security.allow_lazy_installs: false` in `config.yaml`; do not set this in `.env`. | | `HERMES_DISABLE_FILE_STATE_GUARD` | Set to `1` to turn off the "file changed since you read it" guard on `patch`/`write_file`. | -| `HERMES_CORE_TOOLS` | Comma-separated override for the canonical core tool list (advanced; rarely needed). | | `HERMES_BUNDLED_SKILLS` | Comma-separated override for the list of bundled skills loaded at startup. | | `HERMES_OPTIONAL_SKILLS` | Comma-separated list of optional-skill names to auto-install on first run. | | `HERMES_DEBUG_INTERRUPT` | Set to `1` to log detailed interrupt/cancel tracing to `agent.log`. | diff --git a/website/docs/reference/tools-reference.md b/website/docs/reference/tools-reference.md index 006b731d2bc4..75866e97a2d4 100644 --- a/website/docs/reference/tools-reference.md +++ b/website/docs/reference/tools-reference.md @@ -242,7 +242,7 @@ Registered on the `hermes-discord` platform toolset. Moderation actions require ## `spotify` toolset -Registered by the bundled `spotify` plugin. Requires an OAuth token — run `hermes spotify setup` once to authorize. +Registered by the bundled `spotify` plugin. Requires an OAuth token — run `hermes auth spotify` once to authorize. | Tool | Description | Requires environment | |------|-------------|----------------------| diff --git a/website/docs/user-guide/configuring-models.md b/website/docs/user-guide/configuring-models.md index ec789c9c96e0..dfc0081db009 100644 --- a/website/docs/user-guide/configuring-models.md +++ b/website/docs/user-guide/configuring-models.md @@ -230,7 +230,7 @@ Then `/model fav` or `/model grok` in chat. User aliases shadow built-in short n hermes model # Interactive provider + model picker (the canonical way to switch defaults) ``` -`hermes model` walks you through picking a provider, authenticating (OAuth flows open a browser; API-key providers prompt for the key), and then choosing a specific model from that provider's curated catalog. The choice is written to `model.provider` and `model.model` in `~/.hermes/config.yaml`. +`hermes model` walks you through picking a provider, authenticating (OAuth flows open a browser; API-key providers prompt for the key), and then choosing a specific model from that provider's curated catalog. The choice is written to `model.provider` and `model.default` in `~/.hermes/config.yaml`. To list providers/models without launching the picker, use the dashboard or the REST endpoints below. To inspect what the CLI will actually use right now: `hermes config show | grep '^model\.'` and `hermes status`. diff --git a/website/docs/user-guide/features/codex-app-server-runtime.md b/website/docs/user-guide/features/codex-app-server-runtime.md index b4d317ae0cf9..776292711474 100644 --- a/website/docs/user-guide/features/codex-app-server-runtime.md +++ b/website/docs/user-guide/features/codex-app-server-runtime.md @@ -143,7 +143,7 @@ The kanban tools are gated by `HERMES_KANBAN_TASK` env var the dispatcher sets ```bash codex login # writes tokens to ~/.codex/auth.json ``` - Hermes' own `hermes auth login codex` writes to `~/.hermes/auth.json` — that's a separate session. **Run `codex login` separately** if you haven't. + Hermes' own `hermes auth add openai-codex` writes to `~/.hermes/auth.json` — that's a separate session. **Run `codex login` separately** if you haven't. 3. **(Optional) Install the Codex plugins you want.** When you enable the runtime, Hermes auto-migrates whichever curated plugins you've already installed via Codex CLI: ```bash @@ -390,7 +390,7 @@ This runtime is **opt-in beta**. Working as of Hermes Agent 2026.5 + Codex CLI 0 Known limitations: -- **Hermes auth and codex auth are separate sessions.** You need both `codex login` AND `hermes auth login codex` for the cleanest UX (the runtime uses codex's session for the LLM call). This is a deliberate design choice in Hermes' `_import_codex_cli_tokens` — Hermes won't share OAuth state with codex CLI to avoid clobbering each other on token refresh. +- **Hermes auth and codex auth are separate sessions.** You need both `codex login` AND `hermes auth add openai-codex` for the cleanest UX (the runtime uses codex's session for the LLM call). This is a deliberate design choice in Hermes' `_import_codex_cli_tokens` — Hermes won't share OAuth state with codex CLI to avoid clobbering each other on token refresh. - **`delegate_task`, `memory`, `session_search`, `todo` are unavailable on this runtime.** They need the running AIAgent context which a stateless MCP callback can't provide. Use `/codex-runtime auto` when you need these. - **No inline patch preview in approval prompts when codex doesn't track the changeset.** Codex's `fileChange` approval params don't always carry the changeset. Hermes caches the data from the corresponding `item/started` notification when possible, but if approval arrives before the item has streamed, the prompt falls back to whatever `reason` codex provides. - **Sub-second cancellation isn't guaranteed.** Mid-stream interrupts (Ctrl+C while codex is responding) are sent via `turn/interrupt`, but if codex has already flushed the final message, you get the response anyway. diff --git a/website/docs/user-guide/features/overview.md b/website/docs/user-guide/features/overview.md index 5f6c04f5ca8b..75f365b38924 100644 --- a/website/docs/user-guide/features/overview.md +++ b/website/docs/user-guide/features/overview.md @@ -34,7 +34,7 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch - **[Voice Mode](voice-mode.md)** — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels. - **[Browser Automation](browser.md)** — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome/Brave/Chromium/Edge via CDP, or local Chromium. Navigate websites, fill forms, and extract information. - **[Vision & Image Paste](vision.md)** — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model. -- **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Nine models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo); pick one via `hermes tools`. +- **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Eleven models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo, Krea V2 Medium/Large); pick one via `hermes tools`. - **[Voice & TTS](tts.md)** — Text-to-speech output and voice message transcription across all messaging platforms, with ten native provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, Mistral Voxtral, Google Gemini, xAI, NeuTTS, KittenTTS, and Piper — plus custom command providers for any local TTS CLI. ## Integrations diff --git a/website/docs/user-guide/features/tts.md b/website/docs/user-guide/features/tts.md index d62ad4a0c464..726a43c7724e 100644 --- a/website/docs/user-guide/features/tts.md +++ b/website/docs/user-guide/features/tts.md @@ -57,7 +57,7 @@ tts: base_url: "https://api.openai.com/v1" # Override for OpenAI-compatible TTS endpoints speed: 1.0 # 0.25 - 4.0 minimax: - model: "speech-2.8-hd" # speech-2.8-hd (default), speech-2.8-turbo + model: "speech-02-hd" # speech-02-hd (default), speech-02-turbo voice_id: "English_Graceful_Lady" # See https://platform.minimax.io/faq/system-voice-id speed: 1 # 0.5 - 2.0 vol: 1 # 0 - 10 diff --git a/website/docs/user-guide/features/web-dashboard.md b/website/docs/user-guide/features/web-dashboard.md index 2c8ed3a2ee63..990192ec1b71 100644 --- a/website/docs/user-guide/features/web-dashboard.md +++ b/website/docs/user-guide/features/web-dashboard.md @@ -1090,7 +1090,7 @@ When you run `hermes update`, the web frontend is automatically rebuilt if `npm` ## Themes & plugins -The dashboard ships with six built-in themes and can be extended with user-defined themes, plugin tabs, and backend API routes — all drop-in, no repo clone needed. +The dashboard ships with seven built-in themes and can be extended with user-defined themes, plugin tabs, and backend API routes — all drop-in, no repo clone needed. **Switch themes live** from the header bar — click the palette icon next to the language switcher. Selection persists to `config.yaml` under `dashboard.theme` and is restored on page load. diff --git a/website/docs/user-guide/features/web-search.md b/website/docs/user-guide/features/web-search.md index 57920fa8e96e..c02f78dd9582 100644 --- a/website/docs/user-guide/features/web-search.md +++ b/website/docs/user-guide/features/web-search.md @@ -25,7 +25,7 @@ Both are configured through a single backend selection. Providers are chosen via | **Tavily** | `TAVILY_API_KEY` | ✔ | ✔ | 1 000 searches/mo | | **Exa** | `EXA_API_KEY` | ✔ | ✔ | 1 000 searches/mo | | **Parallel** | `PARALLEL_API_KEY` | ✔ | ✔ | Paid | -| **xAI (Grok)** | `XAI_API_KEY` or `hermes auth login xai-oauth` | ✔ | — | Paid (SuperGrok or per-token) | +| **xAI (Grok)** | `XAI_API_KEY` or `hermes auth add xai-oauth` | ✔ | — | Paid (SuperGrok or per-token) | Brave Search, DDGS, and xAI are **search-only** — pair any of them with Firecrawl/Tavily/Exa/Parallel when you also need `web_extract`. DDGS uses the [`ddgs` Python package](https://pypi.org/project/ddgs/) under the hood; if it isn't already installed, run `pip install ddgs` (or let Hermes lazy-install it on first use). xAI runs Grok's server-side `web_search` tool on the Responses API — results are LLM-generated rather than index-backed, so titles, descriptions, and URL choice are all model output (see the [trust-model caveat](#xai-grok) below). @@ -304,7 +304,7 @@ XAI_API_KEY=sk-xai-your-key-here or for SuperGrok subscribers: ```bash -hermes auth login xai-oauth +hermes auth add xai-oauth ``` Then select xAI as the search backend: diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md index e458f28e0318..1ea240fabf9e 100644 --- a/website/docs/user-guide/messaging/telegram.md +++ b/website/docs/user-guide/messaging/telegram.md @@ -240,7 +240,7 @@ The gateway extracts `MEDIA:/path/to/file` tags from agent replies and ships the | **Archives** | `zip`, `rar`, `7z`, `tar`, `gz`, `bz2` | | **Books / packages** | `epub`, `apk`, `ipa` | -Anything on this list delivered as a native attachment on platforms that support it (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix, etc.); on platforms without native support it falls back to a link or plain-text indicator. The **bold** categories were added in the last few releases — if you were relying on the model saying `here is the file: /path/to/report.docx` instead, swap to `MEDIA:/path/to/report.docx` for native delivery. +Anything on this list is delivered as a native attachment on platforms that support it (Telegram, Discord, Signal, Slack, WhatsApp, Feishu, Matrix, etc.); on platforms without native support it falls back to a link or plain-text indicator. The **bold** categories were added in the last few releases — if you were relying on the model saying `here is the file: /path/to/report.docx` instead, swap to `MEDIA:/path/to/report.docx` for native delivery. ## Webhook Mode