Merge remote-tracking branch 'origin/main' into feat/honcho-async-memory

Made-with: Cursor # Conflicts: # cli.py # tests/test_run_agent.py
2026-03-11 12:22:56 -04:00
parent 047b118299 91101065bb
commit a0b0dbe6b2
138 changed files with 17829 additions and 1109 deletions
--- a/website/docs/getting-started/installation.md
+++ b/website/docs/getting-started/installation.md
@@ -22,7 +22,7 @@ Native Windows is **not supported**. Please install [WSL2](https://learn.microso

 ### What the Installer Does

-The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, and global `hermes` command setup. It finishes by running the interactive setup wizard to configure your LLM provider.
+The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat.

 ### After Installation

@@ -30,10 +30,19 @@ Reload your shell and start chatting:

 ```bash
 source ~/.bashrc   # or: source ~/.zshrc
-hermes setup       # Configure API keys (if you skipped during install)
 hermes             # Start chatting!
 ```

+To reconfigure individual settings later, use the dedicated commands:
+
+```bash
+hermes model          # Choose your LLM provider and model
+hermes tools          # Configure which tools are enabled
+hermes gateway setup  # Set up messaging platforms
+hermes config set     # Set individual config values
+hermes setup          # Or run the full setup wizard to configure everything at once
+```
+
 ---

 ## Prerequisites
@@ -192,10 +201,10 @@ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
 fish_add_path $HOME/.local/bin
 ```

-### Step 9: Run the Setup Wizard (Optional)
+### Step 9: Configure Your Provider

 ```bash
-hermes setup
+hermes model       # Select your LLM provider and model
 ```

 ### Step 10: Verify the Installation
@@ -253,7 +262,7 @@ hermes
 | Problem | Solution |
 |---------|----------|
 | `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
-| `API key not set` | Run `hermes setup` or `hermes config set OPENROUTER_API_KEY your_key` |
+| `API key not set` | Run `hermes model` to configure your provider, or `hermes config set OPENROUTER_API_KEY your_key` |
 | Missing config after update | Run `hermes config check` then `hermes config migrate` |

 For more diagnostics, run `hermes doctor` — it will tell you exactly what's missing and how to fix it.
--- a/website/docs/getting-started/quickstart.md
+++ b/website/docs/getting-started/quickstart.md
@@ -29,13 +29,15 @@ source ~/.bashrc   # or source ~/.zshrc

 ## 2. Set Up a Provider

-The installer runs the setup wizard automatically. If you skipped it, run:
+The installer configures your LLM provider automatically. To change it later, use one of these commands:

 ```bash
-hermes setup
+hermes model       # Choose your LLM provider and model
+hermes tools       # Configure which tools are enabled
+hermes setup       # Or configure everything at once
 ```

-This walks you through selecting an inference provider:
+`hermes model` walks you through selecting an inference provider:

 | Provider | What it is | How to set up |
 |----------|-----------|---------------|
@@ -160,9 +162,9 @@ mcp_servers:
 | Command | Description |
 |---------|-------------|
 | `hermes` | Start chatting |
-| `hermes setup` | Configure providers and settings |
-| `hermes model` | Switch provider or model |
+| `hermes model` | Choose your LLM provider and model |
 | `hermes tools` | Configure which tools are enabled per platform |
+| `hermes setup` | Full setup wizard (configures everything at once) |
 | `hermes doctor` | Diagnose issues |
 | `hermes update` | Update to latest version |
 | `hermes gateway` | Start the messaging gateway |
--- a/website/docs/reference/cli-commands.md
+++ b/website/docs/reference/cli-commands.md
@@ -38,7 +38,7 @@ These are commands you run from your shell.

 | Command | Description |
 |---------|-------------|
-| `hermes setup` | Full setup wizard (provider, terminal, messaging) |
+| `hermes setup` | Full setup wizard — configures provider, model, terminal, and messaging all at once |
 | `hermes config` | View current configuration |
 | `hermes config edit` | Open config.yaml in your editor |
 | `hermes config set KEY VAL` | Set a specific value |
@@ -147,6 +147,7 @@ Type `/` in the interactive CLI to see an autocomplete dropdown.
 | `/config` | Show current configuration |
 | `/prompt [text]` | View/set custom system prompt |
 | `/personality [name]` | Set a predefined personality |
+| `/reasoning [arg]` | Manage reasoning effort and display. Args: effort level (`none`, `low`, `medium`, `high`, `xhigh`) or display toggle (`show`, `hide`). No args shows current state. |

 ### Conversation

--- a/website/docs/reference/faq.md
+++ b/website/docs/reference/faq.md
@@ -26,7 +26,7 @@ Hermes Agent works with any OpenAI-compatible API. Supported providers include:
 - **MiniMax** — global and China endpoints
 - **Local models** — via [Ollama](https://ollama.com/), [vLLM](https://docs.vllm.ai/), [llama.cpp](https://github.com/ggerganov/llama.cpp), [SGLang](https://github.com/sgl-project/sglang), or any OpenAI-compatible server

-Set your provider with `hermes setup` or by editing `~/.hermes/.env`. See the [Environment Variables](./environment-variables.md) reference for all provider keys.
+Set your provider with `hermes model` or by editing `~/.hermes/.env`. See the [Environment Variables](./environment-variables.md) reference for all provider keys.

 ### Does it work on Windows?

@@ -160,8 +160,8 @@ curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scri
 # Check which keys are set
 hermes config get OPENROUTER_API_KEY

-# Re-run interactive setup
-hermes setup
+# Re-configure your provider
+hermes model

 # Or set directly
 hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
@@ -279,7 +279,7 @@ hermes gateway logs
 **Cause:** Network issues, bot token expired, or platform webhook misconfiguration.

 **Solution:**
- Verify your bot token is valid with `hermes setup`
+- Verify your bot token is valid with `hermes gateway setup`
 - Check gateway logs: `hermes gateway logs`
 - For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible

--- a/website/docs/user-guide/cli.md
+++ b/website/docs/user-guide/cli.md
@@ -104,6 +104,7 @@ Type `/` to see an autocomplete dropdown of all available commands.
 | `/config` | Show current configuration |
 | `/prompt [text]` | View/set/clear custom system prompt |
 | `/personality [name]` | Set a predefined personality |
+| `/reasoning [arg]` | Manage reasoning effort (`none`/`low`/`medium`/`high`/`xhigh`) and display (`show`/`hide`) |

 ### Conversation Management

@@ -131,6 +132,23 @@ Type `/` to see an autocomplete dropdown of all available commands.
 Commands are case-insensitive — `/HELP` works the same as `/help`. Most commands work mid-conversation.
 :::

+## Quick Commands
+
+You can define custom commands that run shell commands instantly without invoking the LLM. These work in both the CLI and messaging platforms (Telegram, Discord, etc.).
+
+```yaml
+# ~/.hermes/config.yaml
+quick_commands:
+  status:
+    type: exec
+    command: systemctl status hermes-agent
+  gpu:
+    type: exec
+    command: nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader
+```
+
+Then type `/status` or `/gpu` in any chat. See the [Configuration guide](/docs/user-guide/configuration#quick-commands) for more examples.
+
 ## Skill Slash Commands

 Every installed skill in `~/.hermes/skills/` is automatically registered as a slash command. The skill name becomes the command:
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -471,6 +471,24 @@ compression:

 The `summary_model` must support a context length at least as large as your main model's, since it receives the full middle section of the conversation for compression.

+## Iteration Budget Pressure
+
+When the agent is working on a complex task with many tool calls, it can burn through its iteration budget (default: 90 turns) without realizing it's running low. Budget pressure automatically warns the model as it approaches the limit:
+
+| Threshold | Level | What the model sees |
+|-----------|-------|---------------------|
+| **70%** | Caution | `[BUDGET: 63/90. 27 iterations left. Start consolidating.]` |
+| **90%** | Warning | `[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]` |
+
+Warnings are injected into the last tool result's JSON (as a `_budget_warning` field) rather than as separate messages — this preserves prompt caching and doesn't disrupt the conversation structure.
+
+```yaml
+agent:
+  max_turns: 90                # Max iterations per conversation turn (default: 90)
+```
+
+Budget pressure is enabled by default. The agent sees warnings naturally as part of tool results, encouraging it to consolidate its work and deliver a response before running out of iterations.
+
 ## Auxiliary Models

 Hermes uses lightweight "auxiliary" models for side tasks like image analysis, web page summarization, and browser screenshot analysis. By default, these use **Gemini Flash** via OpenRouter or Nous Portal — you don't need to configure anything.
@@ -590,6 +608,16 @@ agent:

 When unset (default), reasoning effort defaults to "medium" — a balanced level that works well for most tasks. Setting a value overrides it — higher reasoning effort gives better results on complex tasks at the cost of more tokens and latency.

+You can also change the reasoning effort at runtime with the `/reasoning` command:
+
+```
+/reasoning           # Show current effort level and display state
+/reasoning high      # Set reasoning effort to high
+/reasoning none      # Disable reasoning
+/reasoning show      # Show model thinking above each response
+/reasoning hide      # Hide model thinking
+```
+
 ## TTS Configuration

 ```yaml
@@ -614,6 +642,7 @@ display:
  compact: false         # Compact output mode (less whitespace)
  resume_display: full   # full (show previous messages on resume) | minimal (one-liner only)
  bell_on_complete: false  # Play terminal bell when agent finishes (great for long tasks)
+  show_reasoning: false    # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
 ```

 | Mode | What you see |
@@ -632,6 +661,33 @@ stt:

 Requires `VOICE_TOOLS_OPENAI_KEY` in `.env` for OpenAI STT.

+## Quick Commands
+
+Define custom commands that run shell commands without invoking the LLM — zero token usage, instant execution. Especially useful from messaging platforms (Telegram, Discord, etc.) for quick server checks or utility scripts.
+
+```yaml
+quick_commands:
+  status:
+    type: exec
+    command: systemctl status hermes-agent
+  disk:
+    type: exec
+    command: df -h /
+  update:
+    type: exec
+    command: cd ~/.hermes/hermes-agent && git pull && pip install -e .
+  gpu:
+    type: exec
+    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader
+```
+
+Usage: type `/status`, `/disk`, `/update`, or `/gpu` in the CLI or any messaging platform. The command runs locally on the host and returns the output directly — no LLM call, no tokens consumed.
+
+- **30-second timeout** — long-running commands are killed with an error message
+- **Priority** — quick commands are checked before skill commands, so you can override skill names
+- **Type** — only `exec` is supported (runs a shell command); other types show an error
+- **Works everywhere** — CLI, Telegram, Discord, Slack, WhatsApp, Signal
+
 ## Human Delay

 Simulate human-like response pacing in messaging platforms:
@@ -685,8 +741,16 @@ delegation:
    - terminal
    - file
    - web
+  # model: "google/gemini-3-flash-preview"  # Override model (empty = inherit parent)
+  # provider: "openrouter"                  # Override provider (empty = inherit parent)
 ```

+**Subagent provider:model override:** By default, subagents inherit the parent agent's provider and model. Set `delegation.provider` and `delegation.model` to route subagents to a different provider:model pair — e.g., use a cheap/fast model for narrowly-scoped subtasks while your primary agent runs an expensive reasoning model.
+
+The delegation provider uses the same credential resolution as CLI/gateway startup. All configured providers are supported: `openrouter`, `nous`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`. When a provider is set, the system automatically resolves the correct base URL, API key, and API mode — no manual credential wiring needed.
+
+**Precedence:** `delegation.provider` in config → parent provider (inherited). `delegation.model` in config → parent model (inherited). Setting just `model` without `provider` changes only the model name while keeping the parent's credentials (useful for switching models within the same provider like OpenRouter).
+
 ## Clarify

 Configure the clarification prompt behavior:
--- a/website/docs/user-guide/features/skills.md
+++ b/website/docs/user-guide/features/skills.md
@@ -55,6 +55,8 @@ metadata:
  hermes:
    tags: [python, automation]
    category: devops
+    fallback_for_toolsets: [web]    # Optional — conditional activation (see below)
+    requires_toolsets: [terminal]   # Optional — conditional activation (see below)
 ---

 # Skill Title
@@ -90,6 +92,30 @@ platforms: [macos, linux]     # macOS and Linux

 When set, the skill is automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms. If omitted, the skill loads on all platforms.

+### Conditional Activation (Fallback Skills)
+
+Skills can automatically show or hide themselves based on which tools are available in the current session. This is most useful for **fallback skills** — free or local alternatives that should only appear when a premium tool is unavailable.
+
+```yaml
+metadata:
+  hermes:
+    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
+    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
+    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
+    requires_tools: [terminal]        # Show ONLY when these specific tools are available
+```
+
+| Field | Behavior |
+|-------|----------|
+| `fallback_for_toolsets` | Skill is **hidden** when the listed toolsets are available. Shown when they're missing. |
+| `fallback_for_tools` | Same, but checks individual tools instead of toolsets. |
+| `requires_toolsets` | Skill is **hidden** when the listed toolsets are unavailable. Shown when they're present. |
+| `requires_tools` | Same, but checks individual tools. |
+
+**Example:** The built-in `duckduckgo-search` skill uses `fallback_for_toolsets: [web]`. When you have `FIRECRAWL_API_KEY` set, the web toolset is available and the agent uses `web_search` — the DuckDuckGo skill stays hidden. If the API key is missing, the web toolset is unavailable and the DuckDuckGo skill automatically appears as a fallback.
+
+Skills without any conditional fields behave exactly as before — they're always shown.
+
 ## Skill Directory Structure

 ```
--- a/website/docs/user-guide/messaging/email.md
+++ b/website/docs/user-guide/messaging/email.md
@@ -0,0 +1,176 @@
+---
+sidebar_position: 7
+title: "Email"
+description: "Set up Hermes Agent as an email assistant via IMAP/SMTP"
+---
+
+# Email Setup
+
+Hermes can receive and reply to emails using standard IMAP and SMTP protocols. Send an email to the agent's address and it replies in-thread — no special client or bot API needed. Works with Gmail, Outlook, Yahoo, Fastmail, or any provider that supports IMAP/SMTP.
+
+:::info No External Dependencies
+The Email adapter uses Python's built-in `imaplib`, `smtplib`, and `email` modules. No additional packages or external services are required.
+:::
+
+---
+
+## Prerequisites
+
+- **A dedicated email account** for your Hermes agent (don't use your personal email)
+- **IMAP enabled** on the email account
+- **An app password** if using Gmail or another provider with 2FA
+
+### Gmail Setup
+
+1. Enable 2-Factor Authentication on your Google Account
+2. Go to [App Passwords](https://myaccount.google.com/apppasswords)
+3. Create a new App Password (select "Mail" or "Other")
+4. Copy the 16-character password — you'll use this instead of your regular password
+
+### Outlook / Microsoft 365
+
+1. Go to [Security Settings](https://account.microsoft.com/security)
+2. Enable 2FA if not already active
+3. Create an App Password under "Additional security options"
+4. IMAP host: `outlook.office365.com`, SMTP host: `smtp.office365.com`
+
+### Other Providers
+
+Most email providers support IMAP/SMTP. Check your provider's documentation for:
+- IMAP host and port (usually port 993 with SSL)
+- SMTP host and port (usually port 587 with STARTTLS)
+- Whether app passwords are required
+
+---
+
+## Step 1: Configure Hermes
+
+The easiest way:
+
+```bash
+hermes gateway setup
+```
+
+Select **Email** from the platform menu. The wizard prompts for your email address, password, IMAP/SMTP hosts, and allowed senders.
+
+### Manual Configuration
+
+Add to `~/.hermes/.env`:
+
+```bash
+# Required
+EMAIL_ADDRESS=hermes@gmail.com
+EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
+EMAIL_IMAP_HOST=imap.gmail.com
+EMAIL_SMTP_HOST=smtp.gmail.com
+
+# Security (recommended)
+EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
+
+# Optional
+EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
+EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
+EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
+EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs
+```
+
+---
+
+## Step 2: Start the Gateway
+
+```bash
+hermes gateway              # Run in foreground
+hermes gateway install      # Install as a system service
+```
+
+On startup, the adapter:
+1. Tests IMAP and SMTP connections
+2. Marks all existing inbox messages as "seen" (only processes new emails)
+3. Starts polling for new messages
+
+---
+
+## How It Works
+
+### Receiving Messages
+
+The adapter polls the IMAP inbox for UNSEEN messages at a configurable interval (default: 15 seconds). For each new email:
+
+- **Subject line** is included as context (e.g., `[Subject: Deploy to production]`)
+- **Reply emails** (subject starting with `Re:`) skip the subject prefix — the thread context is already established
+- **Attachments** are cached locally:
+  - Images (JPEG, PNG, GIF, WebP) → available to the vision tool
+  - Documents (PDF, ZIP, etc.) → available for file access
+- **HTML-only emails** have tags stripped for plain text extraction
+- **Self-messages** are filtered out to prevent reply loops
+
+### Sending Replies
+
+Replies are sent via SMTP with proper email threading:
+
+- **In-Reply-To** and **References** headers maintain the thread
+- **Subject line** preserved with `Re:` prefix (no double `Re: Re:`)
+- **Message-ID** generated with the agent's domain
+- Responses are sent as plain text (UTF-8)
+
+### File Attachments
+
+The agent can send file attachments in replies. Include `MEDIA:/path/to/file` in the response and the file is attached to the outgoing email.
+
+---
+
+## Access Control
+
+Email access follows the same pattern as all other Hermes platforms:
+
+1. **`EMAIL_ALLOWED_USERS` set** → only emails from those addresses are processed
+2. **No allowlist set** → unknown senders get a pairing code
+3. **`EMAIL_ALLOW_ALL_USERS=true`** → any sender is accepted (use with caution)
+
+:::warning
+**Always configure `EMAIL_ALLOWED_USERS`.** Without it, anyone who knows the agent's email address could send commands. The agent has terminal access by default.
+:::
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"IMAP connection failed"** at startup | Verify `EMAIL_IMAP_HOST` and `EMAIL_IMAP_PORT`. Ensure IMAP is enabled on the account. For Gmail, enable it in Settings → Forwarding and POP/IMAP. |
+| **"SMTP connection failed"** at startup | Verify `EMAIL_SMTP_HOST` and `EMAIL_SMTP_PORT`. Check that your password is correct (use App Password for Gmail). |
+| **Messages not received** | Check `EMAIL_ALLOWED_USERS` includes the sender's email. Check spam folder — some providers flag automated replies. |
+| **"Authentication failed"** | For Gmail, you must use an App Password, not your regular password. Ensure 2FA is enabled first. |
+| **Duplicate replies** | Ensure only one gateway instance is running. Check `hermes gateway status`. |
+| **Slow response** | The default poll interval is 15 seconds. Reduce with `EMAIL_POLL_INTERVAL=5` for faster response (but more IMAP connections). |
+| **Replies not threading** | The adapter uses In-Reply-To headers. Some email clients (especially web-based) may not thread correctly with automated messages. |
+
+---
+
+## Security
+
+:::warning
+**Use a dedicated email account.** Don't use your personal email — the agent stores the password in `.env` and has full inbox access via IMAP.
+:::
+
+- Use **App Passwords** instead of your main password (required for Gmail with 2FA)
+- Set `EMAIL_ALLOWED_USERS` to restrict who can interact with the agent
+- The password is stored in `~/.hermes/.env` — protect this file (`chmod 600`)
+- IMAP uses SSL (port 993) and SMTP uses STARTTLS (port 587) by default — connections are encrypted
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `EMAIL_ADDRESS` | Yes | — | Agent's email address |
+| `EMAIL_PASSWORD` | Yes | — | Email password or app password |
+| `EMAIL_IMAP_HOST` | Yes | — | IMAP server host (e.g., `imap.gmail.com`) |
+| `EMAIL_SMTP_HOST` | Yes | — | SMTP server host (e.g., `smtp.gmail.com`) |
+| `EMAIL_IMAP_PORT` | No | `993` | IMAP server port |
+| `EMAIL_SMTP_PORT` | No | `587` | SMTP server port |
+| `EMAIL_POLL_INTERVAL` | No | `15` | Seconds between inbox checks |
+| `EMAIL_ALLOWED_USERS` | No | — | Comma-separated allowed sender addresses |
+| `EMAIL_HOME_ADDRESS` | No | — | Default delivery target for cron jobs |
+| `EMAIL_ALLOW_ALL_USERS` | No | `false` | Allow all senders (not recommended) |
--- a/website/docs/user-guide/messaging/index.md
+++ b/website/docs/user-guide/messaging/index.md
@@ -1,12 +1,12 @@
 ---
 sidebar_position: 1
 title: "Messaging Gateway"
-description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal — architecture and setup overview"
+description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, or Email — architecture and setup overview"
 ---

 # Messaging Gateway

-Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
+Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, or Email. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

 ## Architecture

@@ -15,12 +15,12 @@ Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal. The gateway
 │                      Hermes Gateway                             │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
-│  │ Telegram │ │ Discord  │ │ WhatsApp │ │  Slack   │ │ Signal │ │
-│  │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter│ │
-│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
-│       │             │            │             │           │      │
-│       └─────────────┼────────────┼─────────────┼───────────┘      │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌───────┐│
+│  │ Telegram │ │ Discord  │ │ WhatsApp │ │ Slack  │ │ Signal │ │ Email ││
+│  │ Adapter  │ │ Adapter  │ │ Adapter  │ │Adapter │ │Adapter │ │Adapter││
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ └───┬────┘ └──┬────┘│
+│       │             │            │            │          │         │     │
+│       └─────────────┼────────────┼────────────┼──────────┼─────────┘     │
 │                           │                                     │
 │                  ┌────────▼────────┐                            │
 │                  │  Session Store  │                            │
@@ -114,9 +114,10 @@ Configure per-platform overrides in `~/.hermes/gateway.json`:
 # Restrict to specific users (recommended):
 TELEGRAM_ALLOWED_USERS=123456789,987654321
 DISCORD_ALLOWED_USERS=123456789012345678
-SIGNAL_ALLOWED_USERS=+15551234567,+15559876543
+SIGNAL_ALLOWED_USERS=+155****4567,+155****6543
+EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com

-# Or allow specific users across all platforms (comma-separated user IDs):
+# Or allow
 GATEWAY_ALLOWED_USERS=123456789,987654321

 # Or explicitly allow all users (NOT recommended for bots with terminal access):
@@ -202,6 +203,7 @@ Each platform has its own toolset:
 | WhatsApp | `hermes-whatsapp` | Full tools including terminal |
 | Slack | `hermes-slack` | Full tools including terminal |
 | Signal | `hermes-signal` | Full tools including terminal |
+| Email | `hermes-email` | Full tools including terminal |

 ## Next Steps

@@ -210,3 +212,4 @@ Each platform has its own toolset:
 - [Slack Setup](slack.md)
 - [WhatsApp Setup](whatsapp.md)
 - [Signal Setup](signal.md)
+- [Email Setup](email.md)