docs: deep quality pass — expand 10 thin pages, fix specific issues (#4134)

Developer guide stubs expanded to full documentation: - trajectory-format.md: 56→233 lines (JSONL format, ShareGPT example, normalization rules, reasoning markup, replay code) - session-storage.md: 66→388 lines (SQLite schema, migration table, FTS5 search syntax, lineage queries, Python API examples) - context-compression-and-caching.md: 72→321 lines (dual compression system, config defaults, 4-phase algorithm, before/after example, prompt caching mechanics, cache-aware patterns) - tools-runtime.md: 65→246 lines (registry API, dispatch flow, availability checking, error wrapping, approval flow) - prompt-assembly.md: 89→246 lines (concrete assembled prompt example, SOUL.md injection, context file discovery table) User-facing pages expanded: - docker.md: 62→224 lines (volumes, env forwarding, docker-compose, resource limits, troubleshooting) - updating.md: 79→167 lines (update behavior, version checking, rollback instructions, Nix users) - skins.md: 80→206 lines (all color/spinner/branding keys, built-in skin descriptions, full custom skin YAML template) Hub pages improved: - integrations/index.md: 25→82 lines (web search backends table, TTS/browser providers, quick config example) - features/overview.md: added Integrations section with 6 missing links Specific fixes: - configuration.md: removed duplicate Gateway Streaming section - mcp.md: removed internal "PR work" language - plugins.md: added inline minimal plugin example (self-contained) 13 files changed, ~1700 lines added. Docusaurus build verified clean.
2026-04-25 00:51:20 +00:00 · 2026-03-30 20:30:11 -07:00 · 2026-03-30 20:30:11 -07:00 · 5b0243e6ad
commit 5b0243e6ad
parent 54b876a5c9
13 changed files with 1735 additions and 174 deletions
--- a/website/docs/user-guide/features/mcp.md
+++ b/website/docs/user-guide/features/mcp.md
@ -168,9 +168,7 @@ So a server that exposes callable tools but no resources/prompts will not get th

 ## Per-server filtering

-This is the main feature added by the PR work.
-
-You can now control which tools each MCP server contributes to Hermes.
+You can control which tools each MCP server contributes to Hermes, allowing fine-grained management of your tool namespace.

 ### Disable a server entirely

--- a/website/docs/user-guide/features/overview.md
+++ b/website/docs/user-guide/features/overview.md
@ -33,6 +33,15 @@ Hermes Agent includes a rich set of capabilities that extend far beyond basic ch
 - **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai's FLUX 2 Pro model with automatic 2x upscaling via the Clarity Upscaler.
 - **[Voice & TTS](tts.md)** — Text-to-speech output and voice message transcription across all messaging platforms, with four provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, and NeuTTS.

+## Integrations
+
+- **[Provider Routing](provider-routing.md)** — Fine-grained control over which AI providers handle your requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and priority ordering.
+- **[Fallback Providers](fallback-providers.md)** — Automatic failover to backup LLM providers when your primary model encounters errors, including independent fallback for auxiliary tasks like vision and compression.
+- **[API Server](api-server.md)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more.
+- **[IDE Integration (ACP)](acp.md)** — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor.
+- **[Honcho Memory](honcho.md)** — AI-native persistent memory for cross-session user modeling and personalization via dialectic reasoning.
+- **[RL Training](rl-training.md)** — Generate trajectory data from agent sessions for reinforcement learning and model fine-tuning.
+
 ## Customization

 - **[Personality & SOUL.md](personality.md)** — Fully customizable agent personality. `SOUL.md` is the primary identity file — the first thing in the system prompt — and you can swap in built-in or custom `/personality` presets per session.
--- a/website/docs/user-guide/features/plugins.md
+++ b/website/docs/user-guide/features/plugins.md
@ -25,6 +25,56 @@ Drop a directory into `~/.hermes/plugins/` with a `plugin.yaml` and Python code:

 Start Hermes — your tools appear alongside built-in tools. The model can call them immediately.

+### Minimal working example
+
+Here is a complete plugin that adds a `hello_world` tool and logs every tool call via a hook.
+
+**`~/.hermes/plugins/hello-world/plugin.yaml`**
+
+```yaml
+name: hello-world
+version: "1.0"
+description: A minimal example plugin
+```
+
+**`~/.hermes/plugins/hello-world/__init__.py`**
+
+```python
+"""Minimal Hermes plugin — registers a tool and a hook."""
+
+
+def register(ctx):
+    # --- Tool: hello_world ---
+    schema = {
+        "name": "hello_world",
+        "description": "Returns a friendly greeting for the given name.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Name to greet",
+                }
+            },
+            "required": ["name"],
+        },
+    }
+
+    def handle_hello(params):
+        name = params.get("name", "World")
+        return f"Hello, {name}! 👋  (from the hello-world plugin)"
+
+    ctx.register_tool("hello_world", schema, handle_hello)
+
+    # --- Hook: log every tool call ---
+    def on_tool_call(tool_name, params, result):
+        print(f"[hello-world] tool called: {tool_name}")
+
+    ctx.register_hook("post_tool_call", on_tool_call)
+```
+
+Drop both files into `~/.hermes/plugins/hello-world/`, restart Hermes, and the model can immediately call `hello_world`. The hook prints a log line after every tool invocation.
+
 Project-local plugins under `./.hermes/plugins/` are disabled by default. Enable them only for trusted repositories by setting `HERMES_ENABLE_PROJECT_PLUGINS=true` before starting Hermes.

 ## What plugins can do
--- a/website/docs/user-guide/features/skins.md
+++ b/website/docs/user-guide/features/skins.md
@ -30,28 +30,150 @@ display:

 ## Built-in skins

-| Skin | Description | Agent branding |
-|------|-------------|----------------|
-| `default` | Classic Hermes — gold and kawaii | `Hermes Agent` |
-| `ares` | War-god theme — crimson and bronze | `Ares Agent` |
-| `mono` | Monochrome — clean grayscale | `Hermes Agent` |
-| `slate` | Cool blue — developer-focused | `Hermes Agent` |
-| `poseidon` | Ocean-god theme — deep blue and seafoam | `Poseidon Agent` |
-| `sisyphus` | Sisyphean theme — austere grayscale with persistence | `Sisyphus Agent` |
-| `charizard` | Volcanic theme — burnt orange and ember | `Charizard Agent` |
+| Skin | Description | Agent branding | Visual character |
+|------|-------------|----------------|------------------|
+| `default` | Classic Hermes — gold and kawaii | `Hermes Agent` | Warm gold borders, cornsilk text, kawaii faces in spinners. The familiar caduceus banner. Clean and inviting. |
+| `ares` | War-god theme — crimson and bronze | `Ares Agent` | Deep crimson borders with bronze accents. Aggressive spinner verbs ("forging", "marching", "tempering steel"). Custom sword-and-shield ASCII art banner. |
+| `mono` | Monochrome — clean grayscale | `Hermes Agent` | All grays — no color. Borders are `#555555`, text is `#c9d1d9`. Ideal for minimal terminal setups or screen recordings. |
+| `slate` | Cool blue — developer-focused | `Hermes Agent` | Royal blue borders (`#4169e1`), soft blue text. Calm and professional. No custom spinner — uses default faces. |
+| `poseidon` | Ocean-god theme — deep blue and seafoam | `Poseidon Agent` | Deep blue to seafoam gradient. Ocean-themed spinners ("charting currents", "sounding the depth"). Trident ASCII art banner. |
+| `sisyphus` | Sisyphean theme — austere grayscale with persistence | `Sisyphus Agent` | Light grays with stark contrast. Boulder-themed spinners ("pushing uphill", "resetting the boulder", "enduring the loop"). Boulder-and-hill ASCII art banner. |
+| `charizard` | Volcanic theme — burnt orange and ember | `Charizard Agent` | Warm burnt orange to ember gradient. Fire-themed spinners ("banking into the draft", "measuring burn"). Dragon-silhouette ASCII art banner. |

-## What a skin can customize
+## Complete list of configurable keys

-| Area | Keys |
-|------|------|
-| Banner + response colors | `colors.banner_*`, `colors.response_border` |
-| Spinner animation | `spinner.waiting_faces`, `spinner.thinking_faces`, `spinner.thinking_verbs`, `spinner.wings` |
-| Branding text | `branding.agent_name`, `branding.welcome`, `branding.response_label`, `branding.prompt_symbol` |
-| Tool activity prefix | `tool_prefix` |
+### Colors (`colors:`)
+
+Controls all color values throughout the CLI. Values are hex color strings.
+
+| Key | Description | Default (`default` skin) |
+|-----|-------------|--------------------------|
+| `banner_border` | Panel border around the startup banner | `#CD7F32` (bronze) |
+| `banner_title` | Title text color in the banner | `#FFD700` (gold) |
+| `banner_accent` | Section headers in the banner (Available Tools, etc.) | `#FFBF00` (amber) |
+| `banner_dim` | Muted text in the banner (separators, secondary labels) | `#B8860B` (dark goldenrod) |
+| `banner_text` | Body text in the banner (tool names, skill names) | `#FFF8DC` (cornsilk) |
+| `ui_accent` | General UI accent color (highlights, active elements) | `#FFBF00` |
+| `ui_label` | UI labels and tags | `#4dd0e1` (teal) |
+| `ui_ok` | Success indicators (checkmarks, completion) | `#4caf50` (green) |
+| `ui_error` | Error indicators (failures, blocked) | `#ef5350` (red) |
+| `ui_warn` | Warning indicators (caution, approval prompts) | `#ffa726` (orange) |
+| `prompt` | Interactive prompt text color | `#FFF8DC` |
+| `input_rule` | Horizontal rule above the input area | `#CD7F32` |
+| `response_border` | Border around the agent's response box (ANSI escape) | `#FFD700` |
+| `session_label` | Session label color | `#DAA520` |
+| `session_border` | Session ID dim border color | `#8B8682` |
+
+### Spinner (`spinner:`)
+
+Controls the animated spinner shown while waiting for API responses.
+
+| Key | Type | Description | Example |
+|-----|------|-------------|---------|
+| `waiting_faces` | list of strings | Faces cycled while waiting for API response | `["(⚔)", "(⛨)", "(▲)"]` |
+| `thinking_faces` | list of strings | Faces cycled during model reasoning | `["(⚔)", "(⌁)", "(<>)"]` |
+| `thinking_verbs` | list of strings | Verbs shown in spinner messages | `["forging", "plotting", "hammering plans"]` |
+| `wings` | list of [left, right] pairs | Decorative brackets around the spinner | `[["⟪⚔", "⚔⟫"], ["⟪▲", "▲⟫"]]` |
+
+When spinner values are empty (like in `default` and `mono`), hardcoded defaults from `display.py` are used.
+
+### Branding (`branding:`)
+
+Text strings used throughout the CLI interface.
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `agent_name` | Name shown in banner title and status display | `Hermes Agent` |
+| `welcome` | Welcome message shown at CLI startup | `Welcome to Hermes Agent! Type your message or /help for commands.` |
+| `goodbye` | Message shown on exit | `Goodbye! ⚕` |
+| `response_label` | Label on the response box header | ` ⚕ Hermes ` |
+| `prompt_symbol` | Symbol before the user input prompt | `❯ ` |
+| `help_header` | Header text for the `/help` command output | `(^_^)? Available Commands` |
+
+### Other top-level keys
+
+| Key | Type | Description | Default |
+|-----|------|-------------|---------|
+| `tool_prefix` | string | Character prefixed to tool output lines in the CLI | `┊` |
+| `tool_emojis` | dict | Per-tool emoji overrides for spinners and progress (`{tool_name: emoji}`) | `{}` |
+| `banner_logo` | string | Rich-markup ASCII art logo (replaces the default HERMES_AGENT banner) | `""` |
+| `banner_hero` | string | Rich-markup hero art (replaces the default caduceus art) | `""` |

 ## Custom skins

-Create YAML files under `~/.hermes/skins/`. User skins inherit missing values from the built-in `default` skin.
+Create YAML files under `~/.hermes/skins/`. User skins inherit missing values from the built-in `default` skin, so you only need to specify the keys you want to change.
+
+### Full custom skin YAML template
+
+```yaml
+# ~/.hermes/skins/mytheme.yaml
+# Complete skin template — all keys shown. Delete any you don't need;
+# missing values automatically inherit from the 'default' skin.
+
+name: mytheme
+description: My custom theme
+
+colors:
+  banner_border: "#CD7F32"
+  banner_title: "#FFD700"
+  banner_accent: "#FFBF00"
+  banner_dim: "#B8860B"
+  banner_text: "#FFF8DC"
+  ui_accent: "#FFBF00"
+  ui_label: "#4dd0e1"
+  ui_ok: "#4caf50"
+  ui_error: "#ef5350"
+  ui_warn: "#ffa726"
+  prompt: "#FFF8DC"
+  input_rule: "#CD7F32"
+  response_border: "#FFD700"
+  session_label: "#DAA520"
+  session_border: "#8B8682"
+
+spinner:
+  waiting_faces:
+    - "(⚔)"
+    - "(⛨)"
+    - "(▲)"
+  thinking_faces:
+    - "(⚔)"
+    - "(⌁)"
+    - "(<>)"
+  thinking_verbs:
+    - "processing"
+    - "analyzing"
+    - "computing"
+    - "evaluating"
+  wings:
+    - ["⟪⚡", "⚡⟫"]
+    - ["⟪●", "●⟫"]
+
+branding:
+  agent_name: "My Agent"
+  welcome: "Welcome to My Agent! Type your message or /help for commands."
+  goodbye: "See you later! ⚡"
+  response_label: " ⚡ My Agent "
+  prompt_symbol: "⚡ ❯ "
+  help_header: "(⚡) Available Commands"
+
+tool_prefix: "┊"
+
+# Per-tool emoji overrides (optional)
+tool_emojis:
+  terminal: "⚔"
+  web_search: "🔮"
+  read_file: "📄"
+
+# Custom ASCII art banners (optional, Rich markup supported)
+# banner_logo: |
+#   [bold #FFD700] MY AGENT [/]
+# banner_hero: |
+#   [#FFD700]  Custom art here  [/]
+```
+
+### Minimal custom skin example
+
+Since everything inherits from `default`, a minimal skin only needs to change what's different:

 ```yaml
 name: cyberpunk
@ -78,4 +200,7 @@ tool_prefix: "▏"

 - Built-in skins load from `hermes_cli/skin_engine.py`.
 - Unknown skins automatically fall back to `default`.
- `/skin` updates the active CLI theme immediately for the current session.
+- `/skin` updates the active CLI theme immediately for the current session.
+- User skins in `~/.hermes/skins/` take precedence over built-in skins with the same name.
+- Skin changes via `/skin` are session-only. To make a skin your permanent default, set it in `config.yaml`.
+- The `banner_logo` and `banner_hero` fields support Rich console markup (e.g., `[bold #FF0000]text[/]`) for colored ASCII art.