hermes - 💡(How to fix) Fix [Docs]: 27 documentation/code inconsistencies — wrong commands, env vars, config keys & defaults (audit round 3)

Summary

Cross-checked the documentation under website/docs/ against the source code at the current main HEAD: every documented CLI command/flag, slash command, config key, environment variable, header, provider/model name, and default value was verified against the actual code (hermes_cli/, gateway/, tools/, agent/, toolsets.py, hermes_state.py, etc.).

Same method as the merged docs-audit rounds (#22784 round 1, #22858 round 2) — effectively round 3. Most findings are in sections those rounds did not cover (reference/, user-guide/features/, user-guide/configuration.md, several developer-guide/ pages); a few remain in previously-audited sections. Translations under website/i18n/ are excluded.

27 findings. Each lists the doc location, what's wrong, the fix, and source evidence.

Nonexistent or wrong CLI commands / flags

1. reference/tools-reference.md:246 — There is no hermes spotify setup command (and no top-level hermes spotify command at all).

   • Fix: Change hermes spotify setup to hermes auth spotify.
   • Evidence: hermes_cli/main.py:12205 auth_spotify = auth_subparsers.add_parser("spotify", help="Authenticate Hermes with Spotify via PKCE") — spotify is a subcommand of auth, not top-level. No top-level spotify parser exists. The code itself instructs users to run hermes auth spotify (e.g …

2. integrations/providers.md:84 — codex-oauth is not a valid provider id.

   • Fix: Change hermes auth add codex-oauth to hermes auth add openai-codex (or hermes auth add openai-codex --type oauth).
   • Evidence: hermes_cli/auth.py:177 PROVIDER_REGISTRY key is "openai-codex" (no "codex-oauth" entry; grep '"codex-oauth"' --include=*.py returns nothing). hermes_cli/auth_commands.py:76-86 _normalize_provider only aliases openrouter and xai-oauth variants, not codex. hermes_cli/auth_commands.py:165-166: `if …

3. user-guide/messaging/simplex.md:69 — There is no hermes gateway pair command.

   • Fix: Replace with the real command, e.g. Enter that code via hermes pairing approve simplex <code>.
   • Evidence: hermes_cli/main.py: gateway subparsers (lines 11713-11870) define only run/start/stop/restart/status/install/uninstall/list/setup/migrate-legacy — no pair. The pairing command is top-level: main.py:12815 pairing_approve_parser = pairing_sub.add_parser("approve", help="Approve a pairing code") …

4. user-guide/features/web-search.md:28, 291 — hermes auth login <provider> is not a valid command — hermes auth has no login subcommand.

   • Fix: Replace both occurrences of hermes auth login xai-oauth with hermes auth add xai-oauth.
   • Evidence: hermes_cli/main.py:12139-12213 registers the auth subparsers — only add/list/remove/reset/status/logout/spotify; there is no login. hermes_cli/auth_commands.py:769-793 auth_command() dispatch handles only those actions (no login). xai-oauth IS a valid auth add provider …

5. user-guide/features/codex-app-server-runtime.md:146, 393 — hermes auth login codex is not a valid command: hermes auth has no login subcommand, and the Codex provider id is openai-codex (not codex).

   • Fix: Replace hermes auth login codex with hermes auth add openai-codex (both occurrences).
   • Evidence: hermes_cli/main.py:12139-12213 — auth subparsers are add/list/remove/reset/status/logout/spotify only (no login). hermes_cli/auth_commands.py:36 _OAUTH_CAPABLE_PROVIDERS lists the codex provider as openai-codex, not codex. (The top-level hermes login is separately deprecated: …

6. user-guide/multi-profile-gateways.md:173-175 — The hermes logs command has no --tail flag.

   • Fix: Change hermes logs --tail to hermes logs -f (or hermes logs --follow) in both lines.
   • Evidence: hermes_cli/main.py:14436-14441 registers only -f/--follow for the logs command (help: 'Follow the log in real time (like tail -f)'); the full argument list for the logs parser (main.py:14423-14461) is log_name, -n/--lines, -f/--follow, --level, --session, --since, --component — there is no …

7. guides/minimax-oauth.md:218 — The auth remove subcommand requires TWO positional arguments (provider AND a credential target index/id/label).

   • Fix: Change to hermes auth logout minimax-oauth.
   • Evidence: hermes_cli/main.py:12186-12192 declares auth_remove = auth_subparsers.add_parser("remove", ...) with required positionals auth_remove.add_argument("provider", ...) and auth_remove.add_argument("target", help="Credential index, entry id, or exact label") (no nargs='?') …

8. guides/run-hermes-with-nous-portal.md:252 — Same issue: hermes auth remove nous is missing the required target positional and will fail to parse.

   • Fix: Change to hermes auth logout nous # wipes the local refresh token.
   • Evidence: hermes_cli/main.py:12186-12192: auth_remove.add_argument("target", ...) is a required positional; hermes_cli/auth_commands.py:455-466 requires it to resolve a pool entry. The provider-only logout is hermes_cli/main.py:12201-12204 (auth logout <provider>) -> auth_commands.py:520.

9. guides/tips.md:184, 188 — There is no TERMINAL_BACKEND environment variable in Hermes.

   • Fix: Replace TERMINAL_BACKEND=docker with TERMINAL_ENV=docker in both the prose (line 184) and the code block (line 188).
   • Evidence: tools/terminal_tool.py:570 terminal_env = os.getenv("TERMINAL_ENV", "local") and :1021 env_type = os.getenv("TERMINAL_ENV", "local") are the only env reads for backend selection. cli.py:565 maps config field env_type -> env var TERMINAL_ENV; cli.py:547-548 maps config key backend -> …

10. guides/team-telegram-assistant.md:377 — TERMINAL_BACKEND is not read by any Hermes code; the env-var name for selecting the terminal backend is TERMINAL_ENV.

• Fix: Replace TERMINAL_BACKEND=docker with TERMINAL_ENV=docker.
• Evidence: tools/terminal_tool.py:570 and :1021 read os.getenv("TERMINAL_ENV", "local"); cli.py:565 bridges config field env_type to env var TERMINAL_ENV. No occurrence of TERMINAL_BACKEND is read anywhere in the .py tree. .env.example:175 shows the override as # TERMINAL_ENV=local.

Documented env vars / config keys / headers the code never reads

1. reference/environment-variables.md:537 — The documented environment variable HERMES_MD_NAMES is never read by the code.

• Fix: Remove the HERMES_MD_NAMES row from the env-var reference (the file-name list is hardcoded and not configurable via this env var), or implement an env override that the prompt builder actually reads.
• Evidence: grep across repo: no os.getenv("HERMES_MD_NAMES")/os.environ read exists. agent/prompt_builder.py:75 defines _HERMES_MD_NAMES = (".hermes.md", "HERMES.md") (an internal constant, different filenames). The context-file loaders hardcode the names: agent/prompt_builder.py:1408 `for name in …

1. reference/environment-variables.md:565 — The documented environment variable HERMES_CORE_TOOLS is never read by the code.

• Fix: Remove the HERMES_CORE_TOOLS row from the env-var reference, or wire up an actual os.getenv("HERMES_CORE_TOOLS") override of toolsets._HERMES_CORE_TOOLS.
• Evidence: grep -rniE 'getenv(["']HERMES_CORE_TOOLS|environ.*HERMES_CORE_TOOLS' returns nothing. toolsets.py:31 defines _HERMES_CORE_TOOLS = [ ... ] as a static list consumed at toolsets.py:401/412/418/etc.; no env read. Compare hermes_constants.py:205 override = os.getenv("HERMES_BUNDLED_SKILLS", "") …

1. developer-guide/model-provider-plugin.md:253 — The documented pip entry-point group is hermes.plugins, but the plugin loader only scans the group hermes_agent.plugins.

• Fix: Change [project.entry-points."hermes.plugins"] to [project.entry-points."hermes_agent.plugins"].
• Evidence: hermes_cli/plugins.py:169 ENTRY_POINTS_GROUP = "hermes_agent.plugins"; used as the only scanned group at plugins.py:1382-1386. No occurrence of group hermes.plugins exists anywhere in the code.

1. developer-guide/adding-platform-adapters.md:38, 41 — The plugin manifest filename is documented as PLUGIN.yaml (uppercase) in the directory structure and the section heading.

• Fix: Rename PLUGIN.yaml to plugin.yaml in the directory structure block (line 38) and the section heading (line 41).
• Evidence: hermes_cli/plugins.py:1248 manifest_file = child / "plugin.yaml" and plugins.py:1250 fallback child / "plugin.yml". find . -name "PLUGIN.yaml" returns nothing; reference plugins plugins/platforms/{irc,teams,line}/ all contain plugin.yaml.

1. developer-guide/programmatic-integration.md:121 — The X-Hermes-Model request header does not exist.

• Fix: Remove 'or set X-Hermes-Model' (keep only the request-body model field), since no model header is read.
• Evidence: gateway/platforms/api_server.py:1356 model = body.get("model") or self._model_name and :1786 model_name = body.get("model", self._model_name). Repo-wide grep for X-Hermes-Model returns zero matches; only X-Hermes-Session-Id/X-Hermes-Session-Key (plus response-only …

1. developer-guide/trajectory-format.md:218-226 — Neither the agent.save_trajectories config key nor a hermes --save-trajectories CLI flag exists.

• Fix: Remove the config.yaml agent.save_trajectories block and the --save-trajectories CLI flag claim, or correct them to reflect reality: it is set programmatically, and the standalone run_agent.py script accepts --save_trajectories.
• Evidence: grep -c save_trajectories hermes_cli/config.py = 0 (no config key; the agent block at config.py:678 contains max_turns, gateway_timeout, etc. but not save_trajectories). No --save-trajectories argparse flag in hermes_cli/_parser.py or main.py. The only standalone flag is run_agent.py:4662 …

Wrong defaults / values / counts

1. user-guide/messaging/sms.md:129 — The documented default for SMS_WEBHOOK_HOST is 0.0.0.0, but the code defaults it to 127.0.0.1.

• Fix: Change the documented default to 127.0.0.1: | SMS_WEBHOOK_HOST| No | Webhook bind address (default:127.0.0.1) |
• Evidence: gateway/platforms/sms.py:43 DEFAULT_WEBHOOK_HOST = "127.0.0.1" and sms.py:74 self._webhook_host: str = os.getenv("SMS_WEBHOOK_HOST", DEFAULT_WEBHOOK_HOST); also sms.py:13 docstring comment SMS_WEBHOOK_HOST (default 127.0.0.1).

1. user-guide/features/overview.md:37 — The image-generation registry actually ships ELEVEN text-to-image models, not nine.

• Fix: Change 'Nine models supported (...Z-Image Turbo)' to 'Eleven models supported' and add Krea V2 Medium/Large, or keep the count generic ('eleven models, selectable via hermes tools').
• Evidence: tools/image_generation_tool.py defines 11 t2i model keys in the registry: fal-ai/flux-2/klein/9b (l.98), fal-ai/z-image/turbo (l.147), fal-ai/nano-banana-pro (l.172), fal-ai/gpt-image-1.5 (l.198), fal-ai/gpt-image-2 (l.222), fal-ai/ideogram/v3 (l.254), fal-ai/recraft/v4/pro/text-to-image (l.276) …

1. user-guide/features/web-dashboard.md:513 — There are SEVEN built-in dashboard themes, not six.

• Fix: Change 'six built-in themes' to 'seven built-in themes'.
• Evidence: web/src/themes/presets.ts exports BUILTIN_THEMES with 7 entries (l.207-215): default, default-large, midnight, ember, mono, cyberpunk, rose.

1. user-guide/features/tts.md:60 — The documented default MiniMax TTS model speech-2.8-hd does not match the code default, which is speech-02-hd.

• Fix: Change the example/default to model: "speech-02-hd" (matching the code default), and update the comment to list the actually-supported MiniMax model names.
• Evidence: tools/tts_tool.py:179 DEFAULT_MINIMAX_MODEL = "speech-02-hd", used as the fallback at tools/tts_tool.py:1203 model = mm_config.get("model", DEFAULT_MINIMAX_MODEL). A repo-wide grep for speech-2.8 / speech-2 in tools/ and hermes_cli/ returns no matches.

1. user-guide/configuration.md:1238 — This prose lists only 8 supported display.language values, but the code supports 16, and the YAML comment 22 lines earlier in the SAME file (line 1216) correctly lists all 16: `en | zh | zh-hant | ….

• Fix: Update line 1238 to include all 16 supported languages (add zh-hant Traditional Chinese, af, ko, it, ga, pt, ru, hu), matching the YAML comment at line 1216 and SUPPORTED_LANGUAGES in code.
• Evidence: agent/i18n.py:42-45 defines SUPPORTED_LANGUAGES = ("en", "zh", "zh-hant", "ja", "de", "es", "fr", "tr", "uk", "af", "ko", "it", "ga", "pt", "ru", "hu") — 16 values, matching the doc's own line-1216 comment but not the line-1238 prose.

1. user-guide/configuring-models.md:207 — hermes model writes the chosen model name to model.default, not model.model.

• Fix: Change model.model to model.default: 'The choice is written to model.provider and model.default in ~/.hermes/config.yaml.'
• Evidence: hermes_cli/auth.py:6235 writes config["model"]["default"] = model_id (and :6237 config["model"] = {"default": model_id}). hermes_cli/runtime_provider.py:188-190 treats model.model only as a fallback alias ('Accept "model" as alias for "default" (users intuitively write model.model)') …

1. developer-guide/session-storage.md:136 — The documented current schema version is 11, but the code's SCHEMA_VERSION constant is 14.

• Fix: Update to 'Current schema version: 14' and document migrations 12-14 (or note that 12-14 are declarative column adds handled by _reconcile_columns()).
• Evidence: hermes_state.py:36 SCHEMA_VERSION = 14. The version-gated migration chain in _migrate_schema only has explicit < 10 and < 11 blocks (hermes_state.py:773, 796), then bumps to SCHEMA_VERSION (=14) at :846-849.

Broken link / markup / grammar / contradiction

1. integrations/index.md:19 — The 'AI Providers' link points to /user-guide/features/provider-routing — the identical target as the very next bullet, 'Provider Routing' (line 20).

• Fix: Point the 'AI Providers' link to /integrations/providers instead of /user-guide/features/provider-routing.
• Evidence: website/docs/integrations/providers.md frontmatter: title "AI Providers", located at integrations/providers.md (route /integrations/providers). website/docs/integrations/index.md:20 'Provider Routing' already links to the same /user-guide/features/provider-routing target, making line 19's link …

1. integrations/providers.md:912 — Orphaned Docusaurus admonition close marker.

• Fix: Remove the stray ::: on line 912 (the LM Studio context-length steps above it are plain prose, not an admonition). If a callout was intended, add a matching opener such as :::tip before line 898.
• Evidence: N/A (markup error within the doc; admonition-marker audit of providers.md shows all ::: pairs balanced except an unmatched close at line 912).

1. user-guide/messaging/telegram.md:187 — Missing verb — "Anything on this list delivered" is not a grammatical sentence; the auxiliary "is" is missing..

• Fix: "Anything on this list is delivered as a native attachment on platforms that support it ..."

1. guides/cron-troubleshooting.md:114 — The example is supposed to illustrate a name MISMATCH between the job's skill reference and the installed folder, but both names are written identically (ai-funding-daily-report vs ….

• Fix: Make the two names actually differ to show the mismatch, e.g. "If your job specifies ai-funding-report but the skill folder is ai-funding-daily-report, confirm the exact name from hermes skills list."

---

Happy to send a docs-fix PR (round 3) for these if useful.