fix: head+tail truncation for execute_code stdout (inspired by openclaw context-pruning)

Previously, _drain() only captured the first MAX_STDOUT_BYTES (50KB) of
stdout, silently dropping all tail output. Scripts that print() their
final results at the end would have those results lost.

Now uses a two-buffer approach: 40% head + 60% tail (rolling window).
This matches the pattern already used in terminal_tool.py (line 1042-1051)
but gives the tail more space since execute_code scripts typically
print() their final results at the end.

Inspired by openclaw's softTrim context-pruning (headChars/tailChars).

.env.example

@@ -53,10 +53,6 @@ MINIMAX_CN_API_KEY=
 # Get at: https://firecrawl.dev/
 FIRECRAWL_API_KEY=
 
-# Nous Research API Key - Vision analysis and multi-model reasoning
-# Get at: https://inference-api.nousresearch.com/
-NOUS_API_KEY=
-
 # FAL.ai API Key - Image generation
 # Get at: https://fal.ai/
 FAL_KEY=

AGENTS.md

@@ -1,80 +1,60 @@
 # Hermes Agent - Development Guide
 
-Instructions for AI coding assistants (GitHub Copilot, Cursor, etc.) and human developers.
-
-Hermes Agent is an AI agent harness with tool-calling capabilities, interactive CLI, messaging integrations, and scheduled tasks.
+Instructions for AI coding assistants and developers working on the hermes-agent codebase.
 
 ## Development Environment
 
-**IMPORTANT**: Always use the virtual environment if it exists:
 ```bash
-source venv/bin/activate  # Before running any Python commands
+source .venv/bin/activate  # ALWAYS activate before running Python
 ```
 
 ## Project Structure
 
 ```
 hermes-agent/
-├── agent/                # Agent internals (extracted from run_agent.py)
-│   ├── auxiliary_client.py   # Shared auxiliary OpenAI client (vision, compression, web extract)
-│   ├── model_metadata.py     # Model context lengths, token estimation
+├── run_agent.py          # AIAgent class — core conversation loop
+├── model_tools.py        # Tool orchestration, _discover_tools(), handle_function_call()
+├── toolsets.py           # Toolset definitions, _HERMES_CORE_TOOLS list
+├── cli.py                # HermesCLI class — interactive CLI orchestrator
+├── hermes_state.py       # SessionDB — SQLite session store (FTS5 search)
+├── agent/                # Agent internals
+│   ├── prompt_builder.py     # System prompt assembly
 │   ├── context_compressor.py # Auto context compression
 │   ├── prompt_caching.py     # Anthropic prompt caching
-│   ├── prompt_builder.py     # System prompt assembly (identity, skills index, context files)
+│   ├── auxiliary_client.py   # Auxiliary LLM client (vision, summarization)
+│   ├── model_metadata.py     # Model context lengths, token estimation
 │   ├── display.py            # KawaiiSpinner, tool preview formatting
+│   ├── skill_commands.py     # Skill slash commands (shared CLI/gateway)
 │   └── trajectory.py         # Trajectory saving helpers
-├── hermes_cli/           # CLI implementation
-│   ├── main.py           # Entry point, command dispatcher
-│   ├── banner.py         # Welcome banner, ASCII art, skills summary
-│   ├── commands.py       # Slash command definitions + autocomplete
-│   ├── callbacks.py      # Interactive prompt callbacks (clarify, sudo, approval)
-│   ├── setup.py          # Interactive setup wizard
-│   ├── config.py         # Config management & migration
-│   ├── status.py         # Status display
-│   ├── doctor.py         # Diagnostics
-│   ├── gateway.py        # Gateway management
-│   ├── uninstall.py      # Uninstaller
-│   ├── cron.py           # Cron job management
-│   └── skills_hub.py     # Skills Hub CLI + /skills slash command
-├── tools/                # Tool implementations
-│   ├── registry.py            # Central tool registry (schemas, handlers, dispatch)
-│   ├── approval.py            # Dangerous command detection + per-session approval
-│   ├── environments/          # Terminal execution backends
-│   │   ├── base.py            # BaseEnvironment ABC
-│   │   ├── local.py           # Local execution with interrupt support
-│   │   ├── docker.py          # Docker container execution
-│   │   ├── ssh.py             # SSH remote execution
-│   │   ├── singularity.py     # Singularity/Apptainer + SIF management
-│   │   ├── modal.py           # Modal cloud execution
-│   │   └── daytona.py         # Daytona cloud sandboxes
-│   ├── terminal_tool.py       # Terminal orchestration (sudo, lifecycle, factory)
-│   ├── todo_tool.py           # Planning & task management
-│   ├── process_registry.py    # Background process management
-│   └── ...                    # Other tool files
-├── gateway/              # Messaging platform adapters
-│   ├── platforms/        # Platform-specific adapters (telegram, discord, slack, whatsapp)
-│   └── ...
-├── cron/                 # Scheduler implementation
-├── environments/         # RL training environments (Atropos integration)
-├── skills/               # Bundled skill sources
-├── optional-skills/      # Official optional skills (not activated by default)
-├── cli.py                # Interactive CLI orchestrator (HermesCLI class)
-├── hermes_state.py       # SessionDB — SQLite session store (schema, titles, FTS5 search)
-├── run_agent.py          # AIAgent class (core conversation loop)
-├── model_tools.py        # Tool orchestration (thin layer over tools/registry.py)
-├── toolsets.py           # Tool groupings
-├── toolset_distributions.py  # Probability-based tool selection
+├── hermes_cli/           # CLI subcommands and setup
+│   ├── main.py           # Entry point — all `hermes` subcommands
+│   ├── config.py         # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
+│   ├── commands.py       # Slash command definitions + SlashCommandCompleter
+│   ├── callbacks.py      # Terminal callbacks (clarify, sudo, approval)
+│   └── setup.py          # Interactive setup wizard
+├── tools/                # Tool implementations (one file per tool)
+│   ├── registry.py       # Central tool registry (schemas, handlers, dispatch)
+│   ├── approval.py       # Dangerous command detection
+│   ├── terminal_tool.py  # Terminal orchestration
+│   ├── process_registry.py # Background process management
+│   ├── file_tools.py     # File read/write/search/patch
+│   ├── web_tools.py      # Firecrawl search/extract
+│   ├── browser_tool.py   # Browserbase browser automation
+│   ├── code_execution_tool.py # execute_code sandbox
+│   ├── delegate_tool.py  # Subagent delegation
+│   ├── mcp_tool.py       # MCP client (~1050 lines)
+│   └── environments/     # Terminal backends (local, docker, ssh, modal, daytona, singularity)
+├── gateway/              # Messaging platform gateway
+│   ├── run.py            # Main loop, slash commands, message dispatch
+│   ├── session.py        # SessionStore — conversation persistence
+│   └── platforms/        # Adapters: telegram, discord, slack, whatsapp, homeassistant, signal
+├── cron/                 # Scheduler (jobs.py, scheduler.py)
+├── environments/         # RL training environments (Atropos)
+├── tests/                # Pytest suite (~2500+ tests)
 └── batch_runner.py       # Parallel batch processing
 ```
 
-**User Configuration** (stored in `~/.hermes/`):
-- `~/.hermes/config.yaml` - Settings (model, terminal, toolsets, etc.)
-- `~/.hermes/.env` - API keys and secrets
-- `~/.hermes/pairing/` - DM pairing data
-- `~/.hermes/hooks/` - Custom event hooks
-- `~/.hermes/image_cache/` - Cached user images
-- `~/.hermes/audio_cache/` - Cached user voice messages
-- `~/.hermes/sticker_cache.json` - Telegram sticker descriptions
+**User config:** `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys)
 
 ## File Dependency Chain
 
@@ -88,698 +68,175 @@ model_tools.py  (imports tools/registry + triggers tool discovery)
 run_agent.py, cli.py, batch_runner.py, environments/
 ```
 
-Each tool file co-locates its schema, handler, and registration. `model_tools.py` is a thin orchestration layer.
-
 ---
 
-## AIAgent Class
-
-The main agent is implemented in `run_agent.py`:
+## AIAgent Class (run_agent.py)
 
 ```python
 class AIAgent:
-    def __init__(
-        self,
-        model: str = "anthropic/claude-sonnet-4.6",
-        api_key: str = None,
-        base_url: str = "https://openrouter.ai/api/v1",
-        max_iterations: int = 60,        # Max tool-calling loops
+    def __init__(self,
+        model: str = "anthropic/claude-opus-4.6",
+        max_iterations: int = 90,
         enabled_toolsets: list = None,
         disabled_toolsets: list = None,
-        verbose_logging: bool = False,
-        quiet_mode: bool = False,         # Suppress progress output
-        tool_progress_callback: callable = None,  # Called on each tool use
-    ):
-        # Initialize OpenAI client, load tools based on toolsets
-        ...
-    
-    def chat(self, user_message: str, task_id: str = None) -> str:
-        # Main entry point - runs the agent loop
-        ...
+        quiet_mode: bool = False,
+        save_trajectories: bool = False,
+        platform: str = None,           # "cli", "telegram", etc.
+        session_id: str = None,
+        skip_context_files: bool = False,
+        skip_memory: bool = False,
+        # ... plus provider, api_mode, callbacks, routing params
+    ): ...
+
+    def chat(self, message: str) -> str:
+        """Simple interface — returns final response string."""
+
+    def run_conversation(self, user_message: str, system_message: str = None,
+                         conversation_history: list = None, task_id: str = None) -> dict:
+        """Full interface — returns dict with final_response + messages."""
 ```
 
 ### Agent Loop
 
-The core loop in `_run_agent_loop()`:
-
-```
-1. Add user message to conversation
-2. Call LLM with tools
-3. If LLM returns tool calls:
-   - Execute each tool
-   - Add tool results to conversation
-   - Go to step 2
-4. If LLM returns text response:
-   - Return response to user
-```
+The core loop is inside `run_conversation()` — entirely synchronous:
 
 ```python
-while turns < max_turns:
-    response = client.chat.completions.create(
-        model=model,
-        messages=messages,
-        tools=tool_schemas,
-    )
-    
+while api_call_count < self.max_iterations and self.iteration_budget.remaining > 0:
+    response = client.chat.completions.create(model=model, messages=messages, tools=tool_schemas)
     if response.tool_calls:
         for tool_call in response.tool_calls:
-            result = await execute_tool(tool_call)
+            result = handle_function_call(tool_call.name, tool_call.args, task_id)
             messages.append(tool_result_message(result))
-        turns += 1
+        api_call_count += 1
     else:
         return response.content
 ```
 
-### Conversation Management
-
-Messages are stored as a list of dicts following OpenAI format:
-
-```python
-messages = [
-    {"role": "system", "content": "You are a helpful assistant..."},
-    {"role": "user", "content": "Search for Python tutorials"},
-    {"role": "assistant", "content": None, "tool_calls": [...]},
-    {"role": "tool", "tool_call_id": "...", "content": "..."},
-    {"role": "assistant", "content": "Here's what I found..."},
-]
-```
-
-### Reasoning Model Support
-
-For models that support chain-of-thought reasoning:
-- Extract `reasoning_content` from API responses
-- Store in `assistant_msg["reasoning"]` for trajectory export
-- Pass back via `reasoning_content` field on subsequent turns
+Messages follow OpenAI format: `{"role": "system/user/assistant/tool", ...}`. Reasoning content is stored in `assistant_msg["reasoning"]`.
 
 ---
 
 ## CLI Architecture (cli.py)
 
-The interactive CLI uses:
-- **Rich** - For the welcome banner and styled panels
-- **prompt_toolkit** - For fixed input area with history, `patch_stdout`, slash command autocomplete, and floating completion menus
-- **KawaiiSpinner** (in run_agent.py) - Animated kawaii faces during API calls; clean `┊` activity feed for tool execution results
-
-Key components:
-- `HermesCLI` class - Main CLI controller with commands and conversation loop
-- `SlashCommandCompleter` - Autocomplete dropdown for `/commands` (type `/` to see all)
-- `agent/skill_commands.py` - Scans skills and builds invocation messages (shared with gateway)
-- `load_cli_config()` - Loads config, sets environment variables for terminal
-- `build_welcome_banner()` - Displays ASCII art logo, tools, and skills summary
-- `_preload_resumed_session()` - Loads session history early (before banner) for immediate display on resume
-- `_display_resumed_history()` - Renders a compact conversation recap in a Rich Panel on session resume
-
-CLI UX notes:
-- Thinking spinner (during LLM API call) shows animated kawaii face + verb (`(⌐■_■) deliberating...`)
-- When LLM returns tool calls, the spinner clears silently (no "got it!" noise)
-- Tool execution results appear as a clean activity feed: `┊ {emoji} {verb} {detail} {duration}`
-- "got it!" only appears when the LLM returns a final text response (`⚕ ready`)
-- The prompt shows `⚕ ❯` when the agent is working, `❯` when idle
-- Pasting 5+ lines auto-saves to `~/.hermes/pastes/` and collapses to a reference
-- Multi-line input via Alt+Enter or Ctrl+J
-- When resuming a session (`--continue`/`--resume`), a "Previous Conversation" panel shows previous messages before the input prompt (configurable via `display.resume_display`)
-- `/commands` - Process user commands like `/help`, `/clear`, `/personality`, etc.
-- `/skill-name` - Invoke installed skills directly (e.g., `/axolotl`, `/gif-search`)
-
-CLI uses `quiet_mode=True` when creating AIAgent to suppress verbose logging.
-
-### Skill Slash Commands
-
-Every installed skill in `~/.hermes/skills/` is automatically registered as a slash command.
-The skill name (from frontmatter or folder name) becomes the command: `axolotl` → `/axolotl`.
-
-Implementation (`agent/skill_commands.py`, shared between CLI and gateway):
-1. `scan_skill_commands()` scans all SKILL.md files at startup, filtering out skills incompatible with the current OS platform (via the `platforms` frontmatter field)
-2. `build_skill_invocation_message()` loads the SKILL.md content and builds a user-turn message
-3. The message includes the full skill content, a list of supporting files (not loaded), and the user's instruction
-4. Supporting files can be loaded on demand via the `skill_view` tool
-5. Injected as a **user message** (not system prompt) to preserve prompt caching
+- **Rich** for banner/panels, **prompt_toolkit** for input with autocomplete
+- **KawaiiSpinner** (`agent/display.py`) — animated faces during API calls, `┊` activity feed for tool results
+- `load_cli_config()` in cli.py merges hardcoded defaults + user config YAML
+- `process_command()` is a method on `HermesCLI` (not in commands.py)
+- Skill slash commands: `agent/skill_commands.py` scans `~/.hermes/skills/`, injects as **user message** (not system prompt) to preserve prompt caching
 
 ### Adding CLI Commands
 
-1. Add to `COMMANDS` dict with description
-2. Add handler in `process_command()` method
-3. For persistent settings, use `save_config_value()` to update config
-
----
-
-## Hermes CLI Commands
-
-The unified `hermes` command provides all functionality:
-
-| Command | Description |
-|---------|-------------|
-| `hermes` | Interactive chat (default) |
-| `hermes chat -q "..."` | Single query mode |
-| `hermes -c` / `hermes --continue` | Resume the most recent session |
-| `hermes -c "my project"` | Resume a session by name (latest in lineage) |
-| `hermes --resume <session_id>` | Resume a specific session by ID or title |
-| `hermes -w` / `hermes --worktree` | Start in isolated git worktree (for parallel agents) |
-| `hermes setup` | Configure API keys and settings |
-| `hermes config` | View current configuration |
-| `hermes config edit` | Open config in editor |
-| `hermes config set KEY VAL` | Set a specific value |
-| `hermes config check` | Check for missing config |
-| `hermes config migrate` | Prompt for missing config interactively |
-| `hermes status` | Show configuration status |
-| `hermes doctor` | Diagnose issues |
-| `hermes update` | Update to latest (checks for new config) |
-| `hermes uninstall` | Uninstall (can keep configs for reinstall) |
-| `hermes gateway` | Start gateway (messaging + cron scheduler) |
-| `hermes gateway setup` | Configure messaging platforms interactively |
-| `hermes gateway install` | Install gateway as system service |
-| `hermes sessions list` | List past sessions (title, preview, last active) |
-| `hermes sessions rename <id> <title>` | Rename/title a session |
-| `hermes cron list` | View scheduled jobs |
-| `hermes cron status` | Check if cron scheduler is running |
-| `hermes version` | Show version info |
-| `hermes pairing list/approve/revoke` | Manage DM pairing codes |
-
----
-
-## Messaging Gateway
-
-The gateway connects Hermes to Telegram, Discord, Slack, and WhatsApp.
-
-### Setup
-
-The interactive setup wizard handles platform configuration:
-
-```bash
-hermes gateway setup      # Arrow-key menu of all platforms, configure tokens/allowlists/home channels
-```
-
-This is the recommended way to configure messaging. It shows which platforms are already set up, walks through each one interactively, and offers to start/restart the gateway service at the end.
-
-Platforms can also be configured manually in `~/.hermes/.env`:
-
-### Configuration (in `~/.hermes/.env`):
-
-```bash
-# Telegram
-TELEGRAM_BOT_TOKEN=123456:ABC-DEF...      # From @BotFather
-TELEGRAM_ALLOWED_USERS=123456789,987654   # Comma-separated user IDs (from @userinfobot)
-
-# Discord  
-DISCORD_BOT_TOKEN=MTIz...                 # From Developer Portal
-DISCORD_ALLOWED_USERS=123456789012345678  # Comma-separated user IDs
-
-# Agent Behavior
-HERMES_MAX_ITERATIONS=60                  # Max tool-calling iterations
-MESSAGING_CWD=/home/myuser                # Terminal working directory for messaging
-
-# Tool progress is configured in config.yaml (display.tool_progress: off|new|all|verbose)
-```
-
-### Working Directory Behavior
-
-- **CLI (`hermes` command)**: Uses current directory (`.` → `os.getcwd()`)
-- **Messaging (Telegram/Discord)**: Uses `MESSAGING_CWD` (default: home directory)
-
-This is intentional: CLI users are in a terminal and expect the agent to work in their current directory, while messaging users need a consistent starting location.
-
-### Security (User Allowlists):
-
-**IMPORTANT**: By default, the gateway denies all users who are not in an allowlist or paired via DM.
-
-The gateway checks `{PLATFORM}_ALLOWED_USERS` environment variables:
-- If set: Only listed user IDs can interact with the bot
-- If unset: All users are denied unless `GATEWAY_ALLOW_ALL_USERS=true` is set
-
-Users can find their IDs:
-- **Telegram**: Message [@userinfobot](https://t.me/userinfobot)
-- **Discord**: Enable Developer Mode, right-click name → Copy ID
-
-### DM Pairing System
-
-Instead of static allowlists, users can pair via one-time codes:
-1. Unknown user DMs the bot → receives pairing code
-2. Owner runs `hermes pairing approve <platform> <code>`
-3. User is permanently authorized
-
-Security: 8-char codes, 1-hour expiry, rate-limited (1/10min/user), max 3 pending per platform, lockout after 5 failed attempts, `chmod 0600` on data files.
-
-Files: `gateway/pairing.py`, `hermes_cli/pairing.py`
-
-### Event Hooks
-
-Hooks fire at lifecycle points. Place hook directories in `~/.hermes/hooks/`:
-
-```
-~/.hermes/hooks/my-hook/
-├── HOOK.yaml    # name, description, events list
-└── handler.py   # async def handle(event_type, context): ...
-```
-
-Events: `gateway:startup`, `session:start`, `session:reset`, `agent:start`, `agent:step`, `agent:end`, `command:*`
-
-The `agent:step` event fires each iteration of the tool-calling loop with tool names and results.
-
-Files: `gateway/hooks.py`
-
-### Tool Progress Notifications
-
-When `tool_progress` is enabled in `config.yaml`, the bot sends status messages as it works:
-- `💻 \`ls -la\`...` (terminal commands show the actual command)
-- `🔍 web_search...`
-- `📄 web_extract...`
-- `🐍 execute_code...` (programmatic tool calling sandbox)
-- `🔀 delegate_task...` (subagent delegation)
-- `❓ clarify...` (user question, CLI-only)
-
-Modes:
-- `new`: Only when switching to a different tool (less spam)
-- `all`: Every single tool call
-
-### Typing Indicator
-
-The gateway keeps the "typing..." indicator active throughout processing, refreshing every 4 seconds. This lets users know the bot is working even during long tool-calling sequences.
-
-### Platform Toolsets:
-
-Each platform has a dedicated toolset in `toolsets.py`:
-- `hermes-telegram`: Full tools including terminal (with safety checks)
-- `hermes-discord`: Full tools including terminal
-- `hermes-whatsapp`: Full tools including terminal
-
----
-
-## Configuration System
-
-Configuration files are stored in `~/.hermes/` for easy user access:
-- `~/.hermes/config.yaml` - All settings (model, terminal, compression, etc.)
-- `~/.hermes/.env` - API keys and secrets
-
-### Adding New Configuration Options
-
-When adding new configuration variables, you MUST follow this process:
-
-#### For config.yaml options:
-
-1. Add to `DEFAULT_CONFIG` in `hermes_cli/config.py`
-2. **CRITICAL**: Bump `_config_version` in `DEFAULT_CONFIG` when adding required fields
-3. This triggers migration prompts for existing users on next `hermes update` or `hermes setup`
-
-Example:
-```python
-DEFAULT_CONFIG = {
-    # ... existing config ...
-    
-    "new_feature": {
-        "enabled": True,
-        "option": "default_value",
-    },
-    
-    # BUMP THIS when adding required fields
-    "_config_version": 2,  # Was 1, now 2
-}
-```
-
-#### For .env variables (API keys/secrets):
-
-1. Add to `REQUIRED_ENV_VARS` or `OPTIONAL_ENV_VARS` in `hermes_cli/config.py`
-2. Include metadata for the migration system:
-
-```python
-OPTIONAL_ENV_VARS = {
-    # ... existing vars ...
-    "NEW_API_KEY": {
-        "description": "What this key is for",
-        "prompt": "Display name in prompts",
-        "url": "https://where-to-get-it.com/",
-        "tools": ["tools_it_enables"],  # What tools need this
-        "password": True,  # Mask input
-    },
-}
-```
-
-#### Update related files:
-
-- `hermes_cli/setup.py` - Add prompts in the setup wizard
-- `cli-config.yaml.example` - Add example with comments
-- Update README.md if user-facing
-
-### Config Version Migration
-
-The system uses `_config_version` to detect outdated configs:
-
-1. `check_for_missing_config()` compares user config to `DEFAULT_CONFIG`
-2. `migrate_config()` interactively prompts for missing values
-3. Called automatically by `hermes update` and optionally by `hermes setup`
-
----
-
-## Environment Variables
-
-API keys are loaded from `~/.hermes/.env`:
-- `OPENROUTER_API_KEY` - Main LLM API access (primary provider)
-- `FIRECRAWL_API_KEY` - Web search/extract tools
-- `FIRECRAWL_API_URL` - Self-hosted Firecrawl endpoint (optional)
-- `BROWSERBASE_API_KEY` / `BROWSERBASE_PROJECT_ID` - Browser automation
-- `FAL_KEY` - Image generation (FLUX model)
-- `NOUS_API_KEY` - Vision and Mixture-of-Agents tools
-
-Terminal tool configuration (in `~/.hermes/config.yaml`):
-- `terminal.backend` - Backend: local, docker, singularity, modal, daytona, or ssh
-- `terminal.cwd` - Working directory ("." = host CWD for local only; for remote backends set an absolute path inside the target, or omit to use the backend's default)
-- `terminal.docker_image` - Image for Docker backend
-- `terminal.singularity_image` - Image for Singularity backend
-- `terminal.modal_image` - Image for Modal backend
-- `terminal.daytona_image` - Image for Daytona backend
-- `DAYTONA_API_KEY` - API key for Daytona backend (in .env)
-- SSH: `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, `TERMINAL_SSH_KEY` in .env
-
-Agent behavior (in `~/.hermes/.env`):
-- `HERMES_MAX_ITERATIONS` - Max tool-calling iterations (default: 60)
-- `MESSAGING_CWD` - Working directory for messaging platforms (default: ~)
-- `display.tool_progress` in config.yaml - Tool progress: `off`, `new`, `all`, `verbose`
-- `OPENAI_API_KEY` - Voice transcription (Whisper STT)
-- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` - Slack integration (Socket Mode)
-- `SLACK_ALLOWED_USERS` - Comma-separated Slack user IDs
-- `HERMES_HUMAN_DELAY_MODE` - Response pacing: off/natural/custom
-- `HERMES_HUMAN_DELAY_MIN_MS` / `HERMES_HUMAN_DELAY_MAX_MS` - Custom delay range
-
-### Dangerous Command Approval
-
-The terminal tool includes safety checks for potentially destructive commands (e.g., `rm -rf`, `DROP TABLE`, `chmod 777`, etc.):
-
-**Behavior by Backend:**
-- **Docker/Singularity/Modal**: Commands run unrestricted (isolated containers)
-- **Local/SSH**: Dangerous commands trigger approval flow
-
-**Approval Flow (CLI):**
-```
-⚠️  Potentially dangerous command detected: recursive delete
-    rm -rf /tmp/test
-
-    [o]nce  |  [s]ession  |  [a]lways  |  [d]eny
-    Choice [o/s/a/D]: 
-```
-
-**Approval Flow (Messaging):**
-- Command is blocked with explanation
-- Agent explains the command was blocked for safety
-- User must add the pattern to their allowlist via `hermes config edit` or run the command directly on their machine
-
-**Configuration:**
-- `command_allowlist` in `~/.hermes/config.yaml` stores permanently allowed patterns
-- Add patterns via "always" approval or edit directly
-
-**Sudo Handling (Messaging):**
-- If sudo fails over messaging, output includes tip to add `SUDO_PASSWORD` to `~/.hermes/.env`
-
----
-
-## Background Process Management
-
-The `process` tool works alongside `terminal` for managing long-running background processes:
-
-**Starting a background process:**
-```python
-terminal(command="pytest -v tests/", background=true)
-# Returns: {"session_id": "proc_abc123", "pid": 12345, ...}
-```
-
-**Managing it with the process tool:**
-- `process(action="list")` -- show all running/recent processes
-- `process(action="poll", session_id="proc_abc123")` -- check status + new output
-- `process(action="log", session_id="proc_abc123")` -- full output with pagination
-- `process(action="wait", session_id="proc_abc123", timeout=600)` -- block until done
-- `process(action="kill", session_id="proc_abc123")` -- terminate
-- `process(action="write", session_id="proc_abc123", data="y")` -- send stdin
-- `process(action="submit", session_id="proc_abc123", data="yes")` -- send + Enter
-
-**Key behaviors:**
-- Background processes execute through the configured terminal backend (local/Docker/Modal/Daytona/SSH/Singularity) -- never directly on the host unless `TERMINAL_ENV=local`
-- The `wait` action blocks the tool call until the process finishes, times out, or is interrupted by a new user message
-- PTY mode (`pty=true` on terminal) enables interactive CLI tools (Codex, Claude Code)
-- In RL training, background processes are auto-killed when the episode ends (`tool_context.cleanup()`)
-- In the gateway, sessions with active background processes are exempt from idle reset
-- The process registry checkpoints to `~/.hermes/processes.json` for crash recovery
-
-Files: `tools/process_registry.py` (registry + handler), `tools/terminal_tool.py` (spawn integration)
+1. Add to `COMMANDS` dict in `hermes_cli/commands.py`
+2. Add handler in `HermesCLI.process_command()` in `cli.py`
+3. For persistent settings, use `save_config_value()` in `cli.py`
 
 ---
 
 ## Adding New Tools
 
-Adding a tool requires changes in **2 files** (the tool file and `toolsets.py`):
-
-1. **Create `tools/your_tool.py`** with handler, schema, check function, and registry call:
+Requires changes in **3 files**:
 
+**1. Create `tools/your_tool.py`:**
 ```python
-# tools/example_tool.py
-import json
-import os
+import json, os
 from tools.registry import registry
 
-def check_example_requirements() -> bool:
-    """Check if required API keys/dependencies are available."""
+def check_requirements() -> bool:
     return bool(os.getenv("EXAMPLE_API_KEY"))
 
 def example_tool(param: str, task_id: str = None) -> str:
-    """Execute the tool and return JSON string result."""
-    try:
-        result = {"success": True, "data": "..."}
-        return json.dumps(result, ensure_ascii=False)
-    except Exception as e:
-        return json.dumps({"error": str(e)}, ensure_ascii=False)
-
-EXAMPLE_SCHEMA = {
-    "name": "example_tool",
-    "description": "Does something useful.",
-    "parameters": {
-        "type": "object",
-        "properties": {
-            "param": {"type": "string", "description": "The parameter"}
-        },
-        "required": ["param"]
-    }
-}
+    return json.dumps({"success": True, "data": "..."})
 
 registry.register(
     name="example_tool",
     toolset="example",
-    schema=EXAMPLE_SCHEMA,
-    handler=lambda args, **kw: example_tool(
-        param=args.get("param", ""), task_id=kw.get("task_id")),
-    check_fn=check_example_requirements,
+    schema={"name": "example_tool", "description": "...", "parameters": {...}},
+    handler=lambda args, **kw: example_tool(param=args.get("param", ""), task_id=kw.get("task_id")),
+    check_fn=check_requirements,
     requires_env=["EXAMPLE_API_KEY"],
 )
 ```
 
-2. **Add to `toolsets.py`**: Add `"example_tool"` to `_HERMES_CORE_TOOLS` if it should be in all platform toolsets, or create a new toolset entry.
+**2. Add import** in `model_tools.py` `_discover_tools()` list.
 
-3. **Add discovery import** in `model_tools.py`'s `_discover_tools()` list: `"tools.example_tool"`.
+**3. Add to `toolsets.py`** — either `_HERMES_CORE_TOOLS` (all platforms) or a new toolset.
 
-That's it. The registry handles schema collection, dispatch, availability checking, and error wrapping automatically. No edits to `TOOLSET_REQUIREMENTS`, `handle_function_call()`, `get_all_tool_names()`, or any other data structure.
+The registry handles schema collection, dispatch, availability checking, and error wrapping. All handlers MUST return a JSON string.
 
-**Optional:** Add to `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` for the setup wizard, and to `toolset_distributions.py` for batch processing.
-
-**Special case: tools that need agent-level state** (like `todo`, `memory`):
-These are intercepted by `run_agent.py`'s tool dispatch loop *before* `handle_function_call()`. The registry still holds their schemas, but dispatch returns a stub error as a safety fallback. See `todo_tool.py` for the pattern.
-
-All tool handlers MUST return a JSON string. The registry's `dispatch()` wraps all exceptions in `{"error": "..."}` automatically.
-
-### Dynamic Tool Availability
-
-Tools declare their requirements at registration time via `check_fn` and `requires_env`. The registry checks `check_fn()` when building tool definitions -- tools whose check fails are silently excluded.
-
-### Stateful Tools
-
-Tools that maintain state (terminal, browser) require:
-- `task_id` parameter for session isolation between concurrent tasks
-- `cleanup_*()` function to release resources
-- Cleanup is called automatically in run_agent.py after conversation completes
+**Agent-level tools** (todo, memory): intercepted by `run_agent.py` before `handle_function_call()`. See `todo_tool.py` for the pattern.
 
 ---
 
-## Trajectory Format
+## Adding Configuration
 
-Conversations are saved in ShareGPT format for training:
-```json
-{"from": "system", "value": "System prompt with <tools>...</tools>"}
-{"from": "human", "value": "User message"}
-{"from": "gpt", "value": "<think>reasoning</think>\n<tool_call>{...}</tool_call>"}
-{"from": "tool", "value": "<tool_response>{...}</tool_response>"}
-{"from": "gpt", "value": "Final response"}
-```
-
-Tool calls use `<tool_call>` XML tags, responses use `<tool_response>` tags, reasoning uses `<think>` tags.
-
-### Trajectory Export
+### config.yaml options:
+1. Add to `DEFAULT_CONFIG` in `hermes_cli/config.py`
+2. Bump `_config_version` (currently 5) to trigger migration for existing users
 
+### .env variables:
+1. Add to `OPTIONAL_ENV_VARS` in `hermes_cli/config.py` with metadata:
 ```python
-agent = AIAgent(save_trajectories=True)
-agent.chat("Do something")
-# Saves to trajectories/*.jsonl in ShareGPT format
+"NEW_API_KEY": {
+    "description": "What it's for",
+    "prompt": "Display name",
+    "url": "https://...",
+    "password": True,
+    "category": "tool",  # provider, tool, messaging, setting
+},
 ```
 
+### Config loaders (two separate systems):
+
+| Loader | Used by | Location |
+|--------|---------|----------|
+| `load_cli_config()` | CLI mode | `cli.py` |
+| `load_config()` | `hermes tools`, `hermes setup` | `hermes_cli/config.py` |
+| Direct YAML load | Gateway | `gateway/run.py` |
+
 ---
 
-## Batch Processing (batch_runner.py)
+## Important Policies
 
-For processing multiple prompts:
-- Parallel execution with multiprocessing
-- Content-based resume for fault tolerance (matches on prompt text, not indices)
-- Toolset distributions control probabilistic tool availability per prompt
-- Output: `data/<run_name>/trajectories.jsonl` (combined) + individual batch files
+### Prompt Caching Must Not Break
 
-```bash
-python batch_runner.py \
-    --dataset_file=prompts.jsonl \
-    --batch_size=20 \
-    --num_workers=4 \
-    --run_name=my_run
-```
+Hermes-Agent ensures caching remains valid throughout a conversation. **Do NOT implement changes that would:**
+- Alter past context mid-conversation
+- Change toolsets mid-conversation
+- Reload memories or rebuild system prompts mid-conversation
 
----
+Cache-breaking forces dramatically higher costs. The ONLY time we alter context is during context compression.
 
-## Skills System
-
-Skills are on-demand knowledge documents the agent can load. Compatible with the [agentskills.io](https://agentskills.io/specification) open standard.
-
-```
-skills/
-├── mlops/                    # Category folder
-│   ├── axolotl/             # Skill folder
-│   │   ├── SKILL.md         # Main instructions (required)
-│   │   ├── references/      # Additional docs, API specs
-│   │   ├── templates/       # Output formats, configs
-│   │   └── assets/          # Supplementary files (agentskills.io)
-│   └── vllm/
-│       └── SKILL.md
-├── .hub/                    # Skills Hub state (gitignored)
-│   ├── lock.json            # Installed skill provenance
-│   ├── quarantine/          # Pending security review
-│   ├── audit.log            # Security scan history
-│   ├── taps.json            # Custom source repos
-│   └── index-cache/         # Cached remote indexes
-```
-
-**Progressive disclosure** (token-efficient):
-1. `skills_categories()` - List category names (~50 tokens)
-2. `skills_list(category)` - Name + description per skill (~3k tokens)
-3. `skill_view(name)` - Full content + tags + linked files
-
-SKILL.md files use YAML frontmatter (agentskills.io format):
-```yaml
----
-name: skill-name
-description: Brief description for listing
-version: 1.0.0
-platforms: [macos]              # Optional — restrict to specific OS (macos/linux/windows)
-metadata:
-  hermes:
-    tags: [tag1, tag2]
-    related_skills: [other-skill]
----
-# Skill Content...
-```
-
-**Platform filtering** — Skills with a `platforms` field are automatically excluded from the system prompt index, `skills_list()`, and slash commands on incompatible platforms. Skills without the field load everywhere (backward compatible). See `skills/apple/` for macOS-only examples (iMessage, Reminders, Notes, FindMy).
-
-**Skills Hub** — user-driven skill search/install from online registries and official optional skills. Sources: official optional skills (shipped with repo, labeled "official"), GitHub (openai/skills, anthropics/skills, custom taps), ClawHub, Claude marketplace, LobeHub. Not exposed as an agent tool — the model cannot search for or install skills. Users manage skills via `hermes skills browse/search/install` CLI commands or the `/skills` slash command in chat.
-
-Key files:
-- `tools/skills_tool.py` — Agent-facing skill list/view (progressive disclosure)
-- `tools/skills_guard.py` — Security scanner (regex + LLM audit, trust-aware install policy)
-- `tools/skills_hub.py` — Source adapters (OptionalSkillSource, GitHub, ClawHub, Claude marketplace, LobeHub), lock file, auth
-- `hermes_cli/skills_hub.py` — CLI subcommands + `/skills` slash command handler
-
----
-
-## Auxiliary Model Configuration
-
-Hermes uses lightweight "auxiliary" models for side tasks that run alongside the main conversation model:
-
-| Task | Tool(s) | Default Model |
-|------|---------|---------------|
-| **Vision analysis** | `vision_analyze`, `browser_vision` | `google/gemini-3-flash-preview` (via OpenRouter) |
-| **Web extraction** | `web_extract`, browser snapshot summarization | `google/gemini-3-flash-preview` (via OpenRouter) |
-| **Context compression** | Auto-compression when approaching context limit | `google/gemini-3-flash-preview` (via OpenRouter) |
-
-By default, these auto-detect the best available provider: OpenRouter → Nous Portal → (text tasks only) custom endpoint → Codex → API-key providers.
-
-### Changing the Vision Model
-
-To use a different model for image analysis (e.g., GPT-4o instead of Gemini Flash), add to `~/.hermes/config.yaml`:
-
-```yaml
-auxiliary:
-  vision:
-    provider: "openrouter"        # or "nous", "main", "auto"
-    model: "openai/gpt-4o"        # any model slug your provider supports
-```
-
-Or set environment variables (in `~/.hermes/.env` or shell):
-
-```bash
-AUXILIARY_VISION_MODEL=openai/gpt-4o
-# Optionally force a specific provider:
-AUXILIARY_VISION_PROVIDER=openrouter
-```
-
-### Changing the Web Extraction Model
-
-```yaml
-auxiliary:
-  web_extract:
-    provider: "auto"
-    model: "google/gemini-2.5-flash"
-```
-
-### Changing the Compression Model
-
-```yaml
-compression:
-  summary_model: "google/gemini-2.5-flash"
-  summary_provider: "auto"          # "auto", "openrouter", "nous", "main"
-```
-
-### Provider Options
-
-| Provider | Description |
-|----------|-------------|
-| `"auto"` | Best available (default). For vision, only tries OpenRouter + Nous. |
-| `"openrouter"` | Force OpenRouter (requires `OPENROUTER_API_KEY`) |
-| `"nous"` | Force Nous Portal (requires `hermes login`) |
-| `"codex"` | Force Codex OAuth (ChatGPT account). Supports vision via gpt-5.3-codex. |
-| `"main"` | Use your custom endpoint (`OPENAI_BASE_URL` + `OPENAI_API_KEY`). Works with OpenAI API, local models, etc. |
-
-**Important:** Vision tasks require a multimodal-capable model. In `auto` mode, OpenRouter, Nous Portal, and Codex OAuth are tried (they all support vision). Setting `provider: "main"` for vision will work only if your endpoint supports multimodal input (e.g. OpenAI with GPT-4o, or a local model with vision).
-
-**Key files:** `agent/auxiliary_client.py` (resolution chain), `tools/vision_tools.py`, `tools/browser_tool.py`, `tools/web_tools.py`
+### Working Directory Behavior
+- **CLI**: Uses current directory (`.` → `os.getcwd()`)
+- **Messaging**: Uses `MESSAGING_CWD` env var (default: home directory)
 
 ---
 
 ## Known Pitfalls
 
 ### DO NOT use `simple_term_menu` for interactive menus
-
-`simple_term_menu` has rendering bugs in tmux, iTerm2, and other non-standard terminals. When the user scrolls with arrow keys, previously highlighted items "ghost" — duplicating upward and corrupting the display. This happens because the library uses ANSI cursor-up codes to redraw in place, and tmux/iTerm miscalculate positions when the menu is near the bottom of the viewport.
-
-**Rule:** All interactive menus in `hermes_cli/` must use `curses` (Python stdlib) instead. See `tools_config.py` for the pattern — both `_prompt_choice()` (single-select) and `_prompt_toolset_checklist()` (multi-select with space toggle) use `curses.wrapper()`. The numbered-input fallback handles Windows where curses isn't available.
+Rendering bugs in tmux/iTerm2 — ghosting on scroll. Use `curses` (stdlib) instead. See `hermes_cli/tools_config.py` for the pattern.
 
 ### DO NOT use `\033[K` (ANSI erase-to-EOL) in spinner/display code
-
-The ANSI escape `\033[K` leaks as literal `?[K` text when `prompt_toolkit`'s `patch_stdout` is active. Use space-padding instead to clear lines: `f"\r{line}{' ' * pad}"`. See `agent/display.py` `KawaiiSpinner`.
+Leaks as literal `?[K` text under `prompt_toolkit`'s `patch_stdout`. Use space-padding: `f"\r{line}{' ' * pad}"`.
 
 ### `_last_resolved_tool_names` is a process-global in `model_tools.py`
-
-The `execute_code` sandbox uses `_last_resolved_tool_names` (set by `get_tool_definitions()`) to decide which tool stubs to generate. When subagents run with restricted toolsets, they overwrite this global. After delegation returns to the parent, `execute_code` may see the child's restricted list instead of the parent's full list. This is a known bug — `execute_code` calls after delegation may fail with `ImportError: cannot import name 'patch' from 'hermes_tools'`.
+When subagents overwrite this global, `execute_code` calls after delegation may fail with missing tool imports. Known bug.
 
 ### Tests must not write to `~/.hermes/`
-
-The `autouse` fixture `_isolate_hermes_home` in `tests/conftest.py` redirects `HERMES_HOME` to a temp dir. Every test runs in isolation. If you add a test that creates `AIAgent` instances or writes session logs, the fixture handles cleanup automatically. Never hardcode `~/.hermes/` paths in tests.
+The `_isolate_hermes_home` autouse fixture in `tests/conftest.py` redirects `HERMES_HOME` to a temp dir. Never hardcode `~/.hermes/` paths in tests.
 
 ---
 
-## Testing Changes
+## Testing
 
-After making changes:
+```bash
+source .venv/bin/activate
+python -m pytest tests/ -q          # Full suite (~2500 tests, ~2 min)
+python -m pytest tests/test_model_tools.py -q   # Toolset resolution
+python -m pytest tests/test_cli_init.py -q       # CLI config loading
+python -m pytest tests/gateway/ -q               # Gateway tests
+python -m pytest tests/tools/ -q                 # Tool-level tests
+```
 
-1. Run `hermes doctor` to check setup
-2. Run `hermes config check` to verify config
-3. Test with `hermes chat -q "test message"`
-4. For new config options, test fresh install: `rm -rf ~/.hermes && hermes setup`
+Always run the full suite before pushing changes.

README.md

@@ -17,7 +17,7 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), [Open
 
 <table>
 <tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
-<tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
+<tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
 <tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
 <tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
 <tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
@@ -71,7 +71,7 @@ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes
 | [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes |
 | [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions |
 | [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options |
-| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Home Assistant |
+| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
 | [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Command approval, DM pairing, container isolation |
 | [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ tools, toolset system, terminal backends |
 | [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Procedural memory, Skills Hub, creating skills |

agent/context_compressor.py

@@ -342,7 +342,9 @@ Write only the summary, starting with "[CONTEXT SUMMARY]:" prefix."""
             compressed.append(msg)
 
         if summary:
-            compressed.append({"role": "user", "content": summary})
+            last_head_role = messages[compress_start - 1].get("role", "user") if compress_start > 0 else "user"
+            summary_role = "user" if last_head_role in ("assistant", "tool") else "assistant"
+            compressed.append({"role": summary_role, "content": summary})
         else:
             if not self.quiet_mode:
                 print("   ⚠️  No summary model available — middle turns dropped without summary")

agent/prompt_builder.py

@@ -122,6 +122,15 @@ PLATFORM_HINTS = {
         "attachments, audio as file attachments. You can also include image URLs "
         "in markdown format ![alt](url) and they will be uploaded as attachments."
     ),
+    "signal": (
+        "You are on a text messaging communication platform, Signal. "
+        "Please do not use markdown as it does not render. "
+        "You can send media files natively: to deliver a file to the user, "
+        "include MEDIA:/absolute/path/to/file in your response. Images "
+        "(.png, .jpg, .webp) appear as photos, audio as attachments, and other "
+        "files arrive as downloadable documents. You can also include image "
+        "URLs in markdown format ![alt](url) and they will be sent as photos."
+    ),
     "cli": (
         "You are a CLI AI Agent. Try not to use markdown but simple text "
         "renderable inside a terminal."

agent/redact.py

@@ -8,6 +8,7 @@ the first 6 and last 4 characters for debuggability.
 """
 
 import logging
+import os
 import re
 from typing import Optional
 
@@ -15,7 +16,7 @@ logger = logging.getLogger(__name__)
 
 # Known API key prefixes -- match the prefix + contiguous token chars
 _PREFIX_PATTERNS = [
-    r"sk-[A-Za-z0-9_-]{10,}",           # OpenAI / OpenRouter
+    r"sk-[A-Za-z0-9_-]{10,}",           # OpenAI / OpenRouter / Anthropic (sk-ant-*)
     r"ghp_[A-Za-z0-9]{10,}",            # GitHub PAT (classic)
     r"github_pat_[A-Za-z0-9_]{10,}",    # GitHub PAT (fine-grained)
     r"xox[baprs]-[A-Za-z0-9-]{10,}",    # Slack tokens
@@ -25,6 +26,18 @@ _PREFIX_PATTERNS = [
     r"fc-[A-Za-z0-9]{10,}",             # Firecrawl
     r"bb_live_[A-Za-z0-9_-]{10,}",      # BrowserBase
     r"gAAAA[A-Za-z0-9_=-]{20,}",        # Codex encrypted tokens
+    r"AKIA[A-Z0-9]{16}",                # AWS Access Key ID
+    r"sk_live_[A-Za-z0-9]{10,}",        # Stripe secret key (live)
+    r"sk_test_[A-Za-z0-9]{10,}",        # Stripe secret key (test)
+    r"rk_live_[A-Za-z0-9]{10,}",        # Stripe restricted key
+    r"SG\.[A-Za-z0-9_-]{10,}",          # SendGrid API key
+    r"hf_[A-Za-z0-9]{10,}",             # HuggingFace token
+    r"r8_[A-Za-z0-9]{10,}",             # Replicate API token
+    r"npm_[A-Za-z0-9]{10,}",            # npm access token
+    r"pypi-[A-Za-z0-9_-]{10,}",         # PyPI API token
+    r"dop_v1_[A-Za-z0-9]{10,}",         # DigitalOcean PAT
+    r"doo_v1_[A-Za-z0-9]{10,}",         # DigitalOcean OAuth
+    r"am_[A-Za-z0-9_-]{10,}",           # AgentMail API key
 ]
 
 # ENV assignment patterns: KEY=value where KEY contains a secret-like name
@@ -52,6 +65,22 @@ _TELEGRAM_RE = re.compile(
     r"(bot)?(\d{8,}):([-A-Za-z0-9_]{30,})",
 )
 
+# Private key blocks: -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----
+_PRIVATE_KEY_RE = re.compile(
+    r"-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----"
+)
+
+# Database connection strings: protocol://user:PASSWORD@host
+# Catches postgres, mysql, mongodb, redis, amqp URLs and redacts the password
+_DB_CONNSTR_RE = re.compile(
+    r"((?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|amqp)://[^:]+:)([^@]+)(@)",
+    re.IGNORECASE,
+)
+
+# E.164 phone numbers: +<country><number>, 7-15 digits
+# Negative lookahead prevents matching hex strings or identifiers
+_SIGNAL_PHONE_RE = re.compile(r"(\+[1-9]\d{6,14})(?![A-Za-z0-9])")
+
 # Compile known prefix patterns into one alternation
 _PREFIX_RE = re.compile(
     r"(?<![A-Za-z0-9_-])(" + "|".join(_PREFIX_PATTERNS) + r")(?![A-Za-z0-9_-])"
@@ -69,9 +98,12 @@ def redact_sensitive_text(text: str) -> str:
     """Apply all redaction patterns to a block of text.
 
     Safe to call on any string -- non-matching text passes through unchanged.
+    Disabled when security.redact_secrets is false in config.yaml.
     """
     if not text:
         return text
+    if os.getenv("HERMES_REDACT_SECRETS", "").lower() in ("0", "false", "no", "off"):
+        return text
 
     # Known prefixes (sk-, ghp_, etc.)
     text = _PREFIX_RE.sub(lambda m: _mask_token(m.group(1)), text)
@@ -101,6 +133,20 @@ def redact_sensitive_text(text: str) -> str:
         return f"{prefix}{digits}:***"
     text = _TELEGRAM_RE.sub(_redact_telegram, text)
 
+    # Private key blocks
+    text = _PRIVATE_KEY_RE.sub("[REDACTED PRIVATE KEY]", text)
+
+    # Database connection string passwords
+    text = _DB_CONNSTR_RE.sub(lambda m: f"{m.group(1)}***{m.group(3)}", text)
+
+    # E.164 phone numbers (Signal, WhatsApp)
+    def _redact_phone(m):
+        phone = m.group(1)
+        if len(phone) <= 8:
+            return phone[:2] + "****" + phone[-2:]
+        return phone[:4] + "****" + phone[-4:]
+    text = _SIGNAL_PHONE_RE.sub(_redact_phone, text)
+
     return text
 
 

cli-config.yaml.example

@@ -635,3 +635,8 @@ display:
   #   verbose: Full args, results, and debug logs (same as /verbose)
   # Toggle at runtime with /verbose in the CLI
   tool_progress: all
+
+  # Play terminal bell when agent finishes a response.
+  # Useful for long-running tasks — your terminal will ding when the agent is done.
+  # Works over SSH. Most terminals can be configured to flash the taskbar or play a sound.
+  bell_on_complete: false

cli.py

@@ -161,6 +161,7 @@ def load_cli_config() -> Dict[str, Any]:
         },
         "browser": {
             "inactivity_timeout": 120,  # Auto-cleanup inactive browser sessions after 2 min
+            "record_sessions": False,  # Auto-record browser sessions as WebM videos
         },
         "compression": {
             "enabled": True,      # Auto-compress when approaching context limit
@@ -363,6 +364,13 @@ def load_cli_config() -> Dict[str, Any]:
         if model:
             os.environ[model_env] = model
     
+    # Security settings
+    security_config = defaults.get("security", {})
+    if isinstance(security_config, dict):
+        redact = security_config.get("redact_secrets")
+        if redact is not None:
+            os.environ["HERMES_REDACT_SECRETS"] = str(redact).lower()
+
     return defaults
 
 # Load configuration at module startup
@@ -1035,6 +1043,8 @@ class HermesCLI:
         self.tool_progress_mode = CLI_CONFIG["display"].get("tool_progress", "all")
         # resume_display: "full" (show history) | "minimal" (one-liner only)
         self.resume_display = CLI_CONFIG["display"].get("resume_display", "full")
+        # bell_on_complete: play terminal bell (\a) when agent finishes a response
+        self.bell_on_complete = CLI_CONFIG["display"].get("bell_on_complete", False)
         self.verbose = verbose if verbose is not None else (self.tool_progress_mode == "verbose")
         
         # Configuration - priority: CLI args > env vars > config file
@@ -1118,6 +1128,10 @@ class HermesCLI:
         self._provider_require_params = pr.get("require_parameters", False)
         self._provider_data_collection = pr.get("data_collection")
         
+        # Fallback model config — tried when primary provider fails after retries
+        fb = CLI_CONFIG.get("fallback_model") or {}
+        self._fallback_model = fb if fb.get("provider") and fb.get("model") else None
+
         # Agent will be initialized on first use
         self.agent: Optional[AIAgent] = None
         self._app = None  # prompt_toolkit Application (set in run())
@@ -1349,6 +1363,7 @@ class HermesCLI:
                 session_db=self._session_db,
                 clarify_callback=self._clarify_callback,
                 honcho_session_key=self.session_id,
+                fallback_model=self._fallback_model,
             )
             # Apply any pending title now that the session exists in the DB
             if self._pending_title and self._session_db:
@@ -3120,6 +3135,12 @@ class HermesCLI:
                 # nothing can interleave between the box borders.
                 _cprint(f"\n{top}\n{response}\n\n{bot}")
             
+            # Play terminal bell when agent finishes (if enabled).
+            # Works over SSH — the bell propagates to the user's terminal.
+            if self.bell_on_complete:
+                sys.stdout.write("\a")
+                sys.stdout.flush()
+            
             # Combine all interrupt messages (user may have typed multiple while waiting)
             # and re-queue as one prompt for process_loop
             if pending_message and hasattr(self, '_pending_input'):

cron/scheduler.py

@@ -98,6 +98,7 @@ def _deliver_result(job: dict, content: str) -> None:
         "discord": Platform.DISCORD,
         "slack": Platform.SLACK,
         "whatsapp": Platform.WHATSAPP,
+        "signal": Platform.SIGNAL,
     }
     platform = platform_map.get(platform_name.lower())
     if not platform:

docs/README.md

@@ -1,7 +0,0 @@
-# Documentation
-
-All documentation has moved to the website:
-
-**📖 [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**
-
-The documentation source files live in [`website/docs/`](../website/docs/).

docs/send_file_integration_map.md

@@ -1,345 +0,0 @@
-# send_file Integration Map — Hermes Agent Codebase Deep Dive
-
-## 1. environments/tool_context.py — Base64 File Transfer Implementation
-
-### upload_file() (lines 153-205)
-- Reads local file as raw bytes, base64-encodes to ASCII string
-- Creates parent dirs in sandbox via `self.terminal(f"mkdir -p {parent}")`
-- **Chunk size:** 60,000 chars (~60KB per shell command)
-- **Small files (<=60KB b64):** Single `printf '%s' '{b64}' | base64 -d > {remote_path}`
-- **Large files:** Writes chunks to `/tmp/_hermes_upload.b64` via `printf >> append`, then `base64 -d` to target
-- **Error handling:** Checks local file exists; returns `{exit_code, output}`
-- **Size limits:** No explicit limit, but shell arg limit ~2MB means chunking is necessary for files >~45KB raw
-- **No theoretical max** — but very large files would be slow (many terminal round trips)
-
-### download_file() (lines 234-278)
-- Runs `base64 {remote_path}` inside sandbox, captures stdout
-- Strips output, base64-decodes to raw bytes
-- Writes to host filesystem with parent dir creation
-- **Error handling:** Checks exit code, empty output, decode errors
-- Returns `{success: bool, bytes: int}` or `{success: false, error: str}`
-- **Size limit:** Bounded by terminal output buffer (practical limit ~few MB via base64 terminal output)
-
-### Promotion potential:
-- These methods work via `self.terminal()` — they're environment-agnostic
-- Could be directly lifted into a new tool that operates on the agent's current sandbox
-- For send_file, this `download_file()` pattern is the key: it extracts files from sandbox → host
-
-## 2. tools/environments/base.py — BaseEnvironment Interface
-
-### Current methods:
-- `execute(command, cwd, timeout, stdin_data)` → `{output, returncode}`
-- `cleanup()` — release resources
-- `stop()` — alias for cleanup
-- `_prepare_command()` — sudo transformation
-- `_build_run_kwargs()` — subprocess kwargs
-- `_timeout_result()` — standard timeout dict
-
-### What would need to be added for file transfer:
-- **Nothing required at this level.** File transfer can be implemented via `execute()` (base64 over terminal, like ToolContext does) or via environment-specific methods.
-- Optional: `upload_file(local_path, remote_path)` and `download_file(remote_path, local_path)` methods could be added to BaseEnvironment for optimized per-backend transfers, but the base64-over-terminal approach already works universally.
-
-## 3. tools/environments/docker.py — Docker Container Details
-
-### Container ID tracking:
-- `self._container_id` stored at init from `self._inner.container_id`
-- Inner is `minisweagent.environments.docker.DockerEnvironment`
-- Container ID is a standard Docker container hash
-
-### docker cp feasibility:
-- **YES**, `docker cp` could be used for optimized file transfer:
-  - `docker cp {container_id}:{remote_path} {local_path}` (download)
-  - `docker cp {local_path} {container_id}:{remote_path}` (upload)
-- Much faster than base64-over-terminal for large files
-- Container ID is directly accessible via `env._container_id` or `env._inner.container_id`
-
-### Volumes mounted:
-- **Persistent mode:** Bind mounts at `~/.hermes/sandboxes/docker/{task_id}/workspace` → `/workspace` and `.../home` → `/root`
-- **Ephemeral mode:** tmpfs at `/workspace` (10GB), `/home` (1GB), `/root` (1GB)
-- **User volumes:** From `config.yaml docker_volumes` (arbitrary `-v` mounts)
-- **Security tmpfs:** `/tmp` (512MB), `/var/tmp` (256MB), `/run` (64MB)
-
-### Direct host access for persistent mode:
-- If persistent, files at `/workspace/foo.txt` are just `~/.hermes/sandboxes/docker/{task_id}/workspace/foo.txt` on host — no transfer needed!
-
-## 4. tools/environments/ssh.py — SSH Connection Management
-
-### Connection management:
-- Uses SSH ControlMaster for persistent connection
-- Control socket at `/tmp/hermes-ssh/{user}@{host}:{port}.sock`
-- ControlPersist=300 (5 min keepalive)
-- BatchMode=yes (non-interactive)
-- Stores: `self.host`, `self.user`, `self.port`, `self.key_path`
-
-### SCP/SFTP feasibility:
-- **YES**, SCP can piggyback on the ControlMaster socket:
-  - `scp -o ControlPath={socket} {user}@{host}:{remote} {local}` (download)
-  - `scp -o ControlPath={socket} {local} {user}@{host}:{remote}` (upload)
-- Same SSH key and connection reuse — zero additional auth
-- Would be much faster than base64-over-terminal for large files
-
-## 5. tools/environments/modal.py — Modal Sandbox Filesystem
-
-### Filesystem API exposure:
-- **Not directly.** The inner `SwerexModalEnvironment` wraps Modal's sandbox
-- The sandbox object is accessible at: `env._inner.deployment._sandbox`
-- Modal's Python SDK exposes `sandbox.open()` for file I/O — but only via async API
-- Currently only used for `snapshot_filesystem()` during cleanup
-- **Could use:** `sandbox.open(path, "rb")` to read files or `sandbox.open(path, "wb")` to write
-- **Alternative:** Base64-over-terminal already works via `execute()` — simpler, no SDK dependency
-
-## 6. gateway/platforms/base.py — MEDIA: Tag Flow (Complete)
-
-### extract_media() (lines 587-620):
-- **Pattern:** `MEDIA:\S+` — extracts file paths after MEDIA: prefix
-- **Voice flag:** `[[audio_as_voice]]` global directive sets `is_voice=True` for all media in message
-- Returns `List[Tuple[str, bool]]` (path, is_voice) and cleaned content
-
-### _process_message_background() media routing (lines 752-786):
-- After extracting MEDIA tags, routes by file extension:
-  - `.ogg .opus .mp3 .wav .m4a` → `send_voice()`
-  - `.mp4 .mov .avi .mkv .3gp` → `send_video()`
-  - `.jpg .jpeg .png .webp .gif` → `send_image_file()`
-  - **Everything else** → `send_document()`
-- This routing already supports arbitrary files!
-
-### send_* method inventory (base class):
-- `send(chat_id, content, reply_to, metadata)` — ABSTRACT, text
-- `send_image(chat_id, image_url, caption, reply_to)` — URL-based images
-- `send_animation(chat_id, animation_url, caption, reply_to)` — GIF animations
-- `send_voice(chat_id, audio_path, caption, reply_to)` — voice messages
-- `send_video(chat_id, video_path, caption, reply_to)` — video files
-- `send_document(chat_id, file_path, caption, file_name, reply_to)` — generic files
-- `send_image_file(chat_id, image_path, caption, reply_to)` — local image files
-- `send_typing(chat_id)` — typing indicator
-- `edit_message(chat_id, message_id, content)` — edit sent messages
-
-### What's missing:
-- **Telegram:** No override for `send_document` — falls back to text! (`send_image_file` ✅ added)
-- **Discord:** No override for `send_document` — falls back to text! (`send_image_file` ✅ added)
-- **Slack:** No override for `send_document` — falls back to text! (`send_image_file` ✅ added)
-- **WhatsApp:** Has `send_document` and `send_image_file` via bridge — COMPLETE.
-- The base class defaults just send "📎 File: /path" as text — useless for actual file delivery.
-
-## 7. gateway/platforms/telegram.py — Send Method Analysis
-
-### Implemented send methods:
-- `send()` — MarkdownV2 text with fallback to plain
-- `send_voice()` — `.ogg`/`.opus` as `send_voice()`, others as `send_audio()`
-- `send_image()` — URL-based via `send_photo()`
-- `send_image_file()` — local file via `send_photo(photo=open(path, 'rb'))` ✅
-- `send_animation()` — GIF via `send_animation()`
-- `send_typing()` — "typing" chat action
-- `edit_message()` — edit text messages
-
-### MISSING:
-- **`send_document()` NOT overridden** — Need to add `self._bot.send_document(chat_id, document=open(file_path, 'rb'), ...)`
-- **`send_video()` NOT overridden** — Need to add `self._bot.send_video(...)`
-
-## 8. gateway/platforms/discord.py — Send Method Analysis
-
-### Implemented send methods:
-- `send()` — text messages with chunking
-- `send_voice()` — discord.File attachment
-- `send_image()` — downloads URL, creates discord.File attachment
-- `send_image_file()` — local file via discord.File attachment ✅
-- `send_typing()` — channel.typing()
-- `edit_message()` — edit text messages
-
-### MISSING:
-- **`send_document()` NOT overridden** — Need to add discord.File attachment
-- **`send_video()` NOT overridden** — Need to add discord.File attachment
-
-## 9. gateway/run.py — User File Attachment Handling
-
-### Current attachment flow:
-1. **Telegram photos** (line 509-529): Download via `photo.get_file()` → `cache_image_from_bytes()` → vision auto-analysis
-2. **Telegram voice** (line 532-541): Download → `cache_audio_from_bytes()` → STT transcription
-3. **Telegram audio** (line 542-551): Same pattern
-4. **Telegram documents** (line 553-617): Extension validation against `SUPPORTED_DOCUMENT_TYPES`, 20MB limit, content injection for text files
-5. **Discord attachments** (line 717-751): Content-type detection, image/audio caching, URL fallback for other types
-6. **Gateway run.py** (lines 818-883): Auto-analyzes images with vision, transcribes audio, enriches document messages with context notes
-
-### Key insight: Files are always cached to host filesystem first, then processed. The agent sees local file paths.
-
-## 10. tools/terminal_tool.py — Terminal Tool & Environment Interaction
-
-### How it manages environments:
-- Global dict `_active_environments: Dict[str, Any]` keyed by task_id
-- Per-task creation locks prevent duplicate sandbox creation
-- Auto-cleanup thread kills idle environments after `TERMINAL_LIFETIME_SECONDS`
-- `_get_env_config()` reads all TERMINAL_* env vars for backend selection
-- `_create_environment()` factory creates the right backend type
-
-### Could send_file piggyback?
-- **YES.** send_file needs access to the same environment to extract files from sandboxes.
-- It can reuse `_active_environments[task_id]` to get the environment, then:
-  - Docker: Use `docker cp` via `env._container_id`
-  - SSH: Use `scp` via `env.control_socket`
-  - Local: Just read the file directly
-  - Modal: Use base64-over-terminal via `env.execute()`
-- The file_tools.py module already does this with `ShellFileOperations` — read_file/write_file/search/patch all share the same env instance.
-
-## 11. tools/tts_tool.py — Working Example of File Delivery
-
-### Flow:
-1. Generate audio file to `~/.hermes/audio_cache/tts_TIMESTAMP.{ogg,mp3}`
-2. Return JSON with `media_tag: "MEDIA:/path/to/file"`
-3. For Telegram voice: prepend `[[audio_as_voice]]` directive
-4. The LLM includes the MEDIA tag in its response text
-5. `BasePlatformAdapter._process_message_background()` calls `extract_media()` to find the tag
-6. Routes by extension → `send_voice()` for audio files
-7. Platform adapter sends the file natively
-
-### Key pattern: Tool saves file to host → returns MEDIA: path → LLM echoes it → gateway extracts → platform delivers
-
-## 12. tools/image_generation_tool.py — Working Example of Image Delivery
-
-### Flow:
-1. Call FAL.ai API → get image URL
-2. Return JSON with `image: "https://fal.media/..."` URL
-3. The LLM includes the URL in markdown: `![description](URL)`
-4. `BasePlatformAdapter.extract_images()` finds `![alt](url)` patterns
-5. Routes through `send_image()` (URL) or `send_animation()` (GIF)
-6. Platform downloads and sends natively
-
-### Key difference from TTS: Images are URL-based, not local files. The gateway downloads at send time.
-
----
-
-# INTEGRATION MAP: Where send_file Hooks In
-
-## Architecture Decision: MEDIA: Tag Protocol vs. New Tool
-
-The MEDIA: tag protocol is already the established pattern for file delivery. Two options:
-
-### Option A: Pure MEDIA: Tag (Minimal Change)
-- No new tool needed
-- Agent downloads file from sandbox to host using terminal (base64)
-- Saves to known location (e.g., `~/.hermes/file_cache/`)
-- Includes `MEDIA:/path` in response text
-- Existing routing in `_process_message_background()` handles delivery
-- **Problem:** Agent has to manually do base64 dance + know about MEDIA: convention
-
-### Option B: Dedicated send_file Tool (Recommended)
-- New tool that the agent calls with `(file_path, caption?)`
-- Tool handles the sandbox → host extraction automatically
-- Returns MEDIA: tag that gets routed through existing pipeline
-- Much cleaner agent experience
-
-## Implementation Plan for Option B
-
-### Files to CREATE:
-
-1. **`tools/send_file_tool.py`** — The new tool
-   - Accepts: `file_path` (path in sandbox), `caption` (optional)
-   - Detects environment backend from `_active_environments`
-   - Extracts file from sandbox:
-     - **local:** `shutil.copy()` or direct path
-     - **docker:** `docker cp {container_id}:{path} {local_cache}/` 
-     - **ssh:** `scp -o ControlPath=... {user}@{host}:{path} {local_cache}/`
-     - **modal:** base64-over-terminal via `env.execute("base64 {path}")`
-   - Saves to `~/.hermes/file_cache/{uuid}_{filename}`
-   - Returns: `MEDIA:/cached/path` in response for gateway to pick up
-   - Register with `registry.register(name="send_file", toolset="file", ...)`
-
-### Files to MODIFY:
-
-2. **`gateway/platforms/telegram.py`** — Add missing send methods:
-   ```python
-   async def send_document(self, chat_id, file_path, caption=None, file_name=None, reply_to=None):
-       with open(file_path, "rb") as f:
-           msg = await self._bot.send_document(
-               chat_id=int(chat_id), document=f,
-               caption=caption, filename=file_name or os.path.basename(file_path))
-       return SendResult(success=True, message_id=str(msg.message_id))
-   
-   async def send_image_file(self, chat_id, image_path, caption=None, reply_to=None):
-       with open(image_path, "rb") as f:
-           msg = await self._bot.send_photo(chat_id=int(chat_id), photo=f, caption=caption)
-       return SendResult(success=True, message_id=str(msg.message_id))
-   
-   async def send_video(self, chat_id, video_path, caption=None, reply_to=None):
-       with open(video_path, "rb") as f:
-           msg = await self._bot.send_video(chat_id=int(chat_id), video=f, caption=caption)
-       return SendResult(success=True, message_id=str(msg.message_id))
-   ```
-
-3. **`gateway/platforms/discord.py`** — Add missing send methods:
-   ```python
-   async def send_document(self, chat_id, file_path, caption=None, file_name=None, reply_to=None):
-       channel = self._client.get_channel(int(chat_id)) or await self._client.fetch_channel(int(chat_id))
-       with open(file_path, "rb") as f:
-           file = discord.File(io.BytesIO(f.read()), filename=file_name or os.path.basename(file_path))
-           msg = await channel.send(content=caption, file=file)
-       return SendResult(success=True, message_id=str(msg.id))
-   
-   async def send_image_file(self, chat_id, image_path, caption=None, reply_to=None):
-       # Same pattern as send_document with image filename
-   
-   async def send_video(self, chat_id, video_path, caption=None, reply_to=None):
-       # Same pattern, discord renders video attachments inline
-   ```
-
-4. **`toolsets.py`** — Add `"send_file"` to `_HERMES_CORE_TOOLS` list
-
-5. **`agent/prompt_builder.py`** — Update platform hints to mention send_file tool
-
-### Code that can be REUSED (zero rewrite):
-
-- `BasePlatformAdapter.extract_media()` — Already extracts MEDIA: tags
-- `BasePlatformAdapter._process_message_background()` — Already routes by extension
-- `ToolContext.download_file()` — Base64-over-terminal extraction pattern
-- `tools/terminal_tool.py` _active_environments dict — Environment access
-- `tools/registry.py` — Tool registration infrastructure
-- `gateway/platforms/base.py` send_document/send_image_file/send_video signatures — Already defined
-
-### Code that needs to be WRITTEN from scratch:
-
-1. `tools/send_file_tool.py` (~150 lines):
-   - File extraction from each environment backend type
-   - Local file cache management
-   - Registry registration
-   
-2. Telegram `send_document` + `send_image_file` + `send_video` overrides (~40 lines)
-3. Discord `send_document` + `send_image_file` + `send_video` overrides (~50 lines)
-
-### Total effort: ~240 lines of new code, ~5 lines of config changes
-
-## Key Environment-Specific Extract Strategies
-
-| Backend    | Extract Method                 | Speed    | Complexity |
-|------------|-------------------------------|----------|------------|
-| local      | shutil.copy / direct path     | Instant  | None       |
-| docker     | `docker cp container:path .`  | Fast     | Low        |
-| docker+vol | Direct host path access       | Instant  | None       |
-| ssh        | `scp -o ControlPath=...`      | Fast     | Low        |
-| modal      | base64-over-terminal          | Moderate | Medium     |
-| singularity| Direct path (overlay mount)   | Fast     | Low        |
-
-## Data Flow Summary
-
-```
-Agent calls send_file(file_path="/workspace/output.pdf", caption="Here's the report")
-    │
-    ▼
-send_file_tool.py:
-    1. Get environment from _active_environments[task_id]
-    2. Detect backend type (docker/ssh/modal/local)
-    3. Extract file to ~/.hermes/file_cache/{uuid}_{filename}
-    4. Return: '{"success": true, "media_tag": "MEDIA:/home/user/.hermes/file_cache/abc123_output.pdf"}'
-    │
-    ▼
-LLM includes MEDIA: tag in its response text
-    │
-    ▼
-BasePlatformAdapter._process_message_background():
-    1. extract_media(response) → finds MEDIA:/path
-    2. Checks extension: .pdf → send_document()
-    3. Calls platform-specific send_document(chat_id, file_path, caption)
-    │
-    ▼
-TelegramAdapter.send_document() / DiscordAdapter.send_document():
-    Opens file, sends via platform API as native document attachment
-    User receives downloadable file in chat
-```

gateway/channel_directory.py

@@ -40,8 +40,8 @@ def build_channel_directory(adapters: Dict[Any, Any]) -> Dict[str, Any]:
         except Exception as e:
             logger.warning("Channel directory: failed to build %s: %s", platform.value, e)
 
-    # Telegram & WhatsApp can't enumerate chats -- pull from session history
-    for plat_name in ("telegram", "whatsapp"):
+    # Telegram, WhatsApp & Signal can't enumerate chats -- pull from session history
+    for plat_name in ("telegram", "whatsapp", "signal"):
         if plat_name not in platforms:
             platforms[plat_name] = _build_from_sessions(plat_name)
 
@@ -52,7 +52,7 @@ def build_channel_directory(adapters: Dict[Any, Any]) -> Dict[str, Any]:
 
     try:
         DIRECTORY_PATH.parent.mkdir(parents=True, exist_ok=True)
-        with open(DIRECTORY_PATH, "w") as f:
+        with open(DIRECTORY_PATH, "w", encoding="utf-8") as f:
             json.dump(directory, f, indent=2, ensure_ascii=False)
     except Exception as e:
         logger.warning("Channel directory: failed to write: %s", e)
@@ -115,7 +115,7 @@ def _build_from_sessions(platform_name: str) -> List[Dict[str, str]]:
 
     entries = []
     try:
-        with open(sessions_path) as f:
+        with open(sessions_path, encoding="utf-8") as f:
             data = json.load(f)
 
         seen_ids = set()
@@ -147,7 +147,7 @@ def load_directory() -> Dict[str, Any]:
     if not DIRECTORY_PATH.exists():
         return {"updated_at": None, "platforms": {}}
     try:
-        with open(DIRECTORY_PATH) as f:
+        with open(DIRECTORY_PATH, encoding="utf-8") as f:
             return json.load(f)
     except Exception:
         return {"updated_at": None, "platforms": {}}

gateway/config.py

@@ -26,6 +26,7 @@ class Platform(Enum):
     DISCORD = "discord"
     WHATSAPP = "whatsapp"
     SLACK = "slack"
+    SIGNAL = "signal"
     HOMEASSISTANT = "homeassistant"
 
 
@@ -155,7 +156,16 @@ class GatewayConfig:
         """Return list of platforms that are enabled and configured."""
         connected = []
         for platform, config in self.platforms.items():
-            if config.enabled and (config.token or config.api_key):
+            if not config.enabled:
+                continue
+            # Platforms that use token/api_key auth
+            if config.token or config.api_key:
+                connected.append(platform)
+            # WhatsApp uses enabled flag only (bridge handles auth)
+            elif platform == Platform.WHATSAPP:
+                connected.append(platform)
+            # Signal uses extra dict for config (http_url + account)
+            elif platform == Platform.SIGNAL and config.extra.get("http_url"):
                 connected.append(platform)
         return connected
     
@@ -379,6 +389,26 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
             )
     
+    # Signal
+    signal_url = os.getenv("SIGNAL_HTTP_URL")
+    signal_account = os.getenv("SIGNAL_ACCOUNT")
+    if signal_url and signal_account:
+        if Platform.SIGNAL not in config.platforms:
+            config.platforms[Platform.SIGNAL] = PlatformConfig()
+        config.platforms[Platform.SIGNAL].enabled = True
+        config.platforms[Platform.SIGNAL].extra.update({
+            "http_url": signal_url,
+            "account": signal_account,
+            "ignore_stories": os.getenv("SIGNAL_IGNORE_STORIES", "true").lower() in ("true", "1", "yes"),
+        })
+        signal_home = os.getenv("SIGNAL_HOME_CHANNEL")
+        if signal_home:
+            config.platforms[Platform.SIGNAL].home_channel = HomeChannel(
+                platform=Platform.SIGNAL,
+                chat_id=signal_home,
+                name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
+            )
+
     # Home Assistant
     hass_token = os.getenv("HASS_TOKEN")
     if hass_token:

gateway/mirror.py

@@ -73,7 +73,7 @@ def _find_session_id(platform: str, chat_id: str) -> Optional[str]:
         return None
 
     try:
-        with open(_SESSIONS_INDEX) as f:
+        with open(_SESSIONS_INDEX, encoding="utf-8") as f:
             data = json.load(f)
     except Exception:
         return None
@@ -103,7 +103,7 @@ def _append_to_jsonl(session_id: str, message: dict) -> None:
     """Append a message to the JSONL transcript file."""
     transcript_path = _SESSIONS_DIR / f"{session_id}.jsonl"
     try:
-        with open(transcript_path, "a") as f:
+        with open(transcript_path, "a", encoding="utf-8") as f:
             f.write(json.dumps(message, ensure_ascii=False) + "\n")
     except Exception as e:
         logger.debug("Mirror JSONL write failed: %s", e)

gateway/platforms/ADDING_A_PLATFORM.md

@@ -0,0 +1,313 @@
+# Adding a New Messaging Platform
+
+Checklist for integrating a new messaging platform into the Hermes gateway.
+Use this as a reference when building a new adapter — every item here is a
+real integration point that exists in the codebase. Missing any of them will
+cause broken functionality, missing features, or inconsistent behavior.
+
+---
+
+## 1. Core Adapter (`gateway/platforms/<platform>.py`)
+
+The adapter is a subclass of `BasePlatformAdapter` from `gateway/platforms/base.py`.
+
+### Required methods
+
+| Method | Purpose |
+|--------|---------|
+| `__init__(self, config)` | Parse config, init state. Call `super().__init__(config, Platform.YOUR_PLATFORM)` |
+| `connect() -> bool` | Connect to the platform, start listeners. Return True on success |
+| `disconnect()` | Stop listeners, close connections, cancel tasks |
+| `send(chat_id, text, ...) -> SendResult` | Send a text message |
+| `send_typing(chat_id)` | Send typing indicator |
+| `send_image(chat_id, image_url, caption) -> SendResult` | Send an image |
+| `get_chat_info(chat_id) -> dict` | Return `{name, type, chat_id}` for a chat |
+
+### Optional methods (have default stubs in base)
+
+| Method | Purpose |
+|--------|---------|
+| `send_document(chat_id, path, caption)` | Send a file attachment |
+| `send_voice(chat_id, path)` | Send a voice message |
+| `send_video(chat_id, path, caption)` | Send a video |
+| `send_animation(chat_id, path, caption)` | Send a GIF/animation |
+| `send_image_file(chat_id, path, caption)` | Send image from local file |
+
+### Required function
+
+```python
+def check_<platform>_requirements() -> bool:
+    """Check if this platform's dependencies are available."""
+```
+
+### Key patterns to follow
+
+- Use `self.build_source(...)` to construct `SessionSource` objects
+- Call `self.handle_message(event)` to dispatch inbound messages to the gateway
+- Use `MessageEvent`, `MessageType`, `SendResult` from base
+- Use `cache_image_from_bytes`, `cache_audio_from_bytes`, `cache_document_from_bytes` for attachments
+- Filter self-messages (prevent reply loops)
+- Filter sync/echo messages if the platform has them
+- Redact sensitive identifiers (phone numbers, tokens) in all log output
+- Implement reconnection with exponential backoff + jitter for streaming connections
+- Set `MAX_MESSAGE_LENGTH` if the platform has message size limits
+
+---
+
+## 2. Platform Enum (`gateway/config.py`)
+
+Add the platform to the `Platform` enum:
+
+```python
+class Platform(Enum):
+    ...
+    YOUR_PLATFORM = "your_platform"
+```
+
+Add env var loading in `_apply_env_overrides()`:
+
+```python
+# Your Platform
+your_token = os.getenv("YOUR_PLATFORM_TOKEN")
+if your_token:
+    if Platform.YOUR_PLATFORM not in config.platforms:
+        config.platforms[Platform.YOUR_PLATFORM] = PlatformConfig()
+    config.platforms[Platform.YOUR_PLATFORM].enabled = True
+    config.platforms[Platform.YOUR_PLATFORM].token = your_token
+```
+
+Update `get_connected_platforms()` if your platform doesn't use token/api_key
+(e.g., WhatsApp uses `enabled` flag, Signal uses `extra` dict).
+
+---
+
+## 3. Adapter Factory (`gateway/run.py`)
+
+Add to `_create_adapter()`:
+
+```python
+elif platform == Platform.YOUR_PLATFORM:
+    from gateway.platforms.your_platform import YourAdapter, check_your_requirements
+    if not check_your_requirements():
+        logger.warning("Your Platform: dependencies not met")
+        return None
+    return YourAdapter(config)
+```
+
+---
+
+## 4. Authorization Maps (`gateway/run.py`)
+
+Add to BOTH dicts in `_is_user_authorized()`:
+
+```python
+platform_env_map = {
+    ...
+    Platform.YOUR_PLATFORM: "YOUR_PLATFORM_ALLOWED_USERS",
+}
+platform_allow_all_map = {
+    ...
+    Platform.YOUR_PLATFORM: "YOUR_PLATFORM_ALLOW_ALL_USERS",
+}
+```
+
+---
+
+## 5. Session Source (`gateway/session.py`)
+
+If your platform needs extra identity fields (e.g., Signal's UUID alongside
+phone number), add them to the `SessionSource` dataclass with `Optional` defaults,
+and update `to_dict()`, `from_dict()`, and `build_source()` in base.py.
+
+---
+
+## 6. System Prompt Hints (`agent/prompt_builder.py`)
+
+Add a `PLATFORM_HINTS` entry so the agent knows what platform it's on:
+
+```python
+PLATFORM_HINTS = {
+    ...
+    "your_platform": (
+        "You are on Your Platform. "
+        "Describe formatting capabilities, media support, etc."
+    ),
+}
+```
+
+Without this, the agent won't know it's on your platform and may use
+inappropriate formatting (e.g., markdown on platforms that don't render it).
+
+---
+
+## 7. Toolset (`toolsets.py`)
+
+Add a named toolset for your platform:
+
+```python
+"hermes-your-platform": {
+    "description": "Your Platform bot toolset",
+    "tools": _HERMES_CORE_TOOLS,
+    "includes": []
+},
+```
+
+And add it to the `hermes-gateway` composite:
+
+```python
+"hermes-gateway": {
+    "includes": [..., "hermes-your-platform"]
+}
+```
+
+---
+
+## 8. Cron Delivery (`cron/scheduler.py`)
+
+Add to `platform_map` in `_deliver_result()`:
+
+```python
+platform_map = {
+    ...
+    "your_platform": Platform.YOUR_PLATFORM,
+}
+```
+
+Without this, `schedule_cronjob(deliver="your_platform")` silently fails.
+
+---
+
+## 9. Send Message Tool (`tools/send_message_tool.py`)
+
+Add to `platform_map` in `send_message_tool()`:
+
+```python
+platform_map = {
+    ...
+    "your_platform": Platform.YOUR_PLATFORM,
+}
+```
+
+Add routing in `_send_to_platform()`:
+
+```python
+elif platform == Platform.YOUR_PLATFORM:
+    return await _send_your_platform(pconfig, chat_id, message)
+```
+
+Implement `_send_your_platform()` — a standalone async function that sends
+a single message without requiring the full adapter (for use by cron jobs
+and the send_message tool outside the gateway process).
+
+Update the tool schema `target` description to include your platform example.
+
+---
+
+## 10. Cronjob Tool Schema (`tools/cronjob_tools.py`)
+
+Update the `deliver` parameter description and docstring to mention your
+platform as a delivery option.
+
+---
+
+## 11. Channel Directory (`gateway/channel_directory.py`)
+
+If your platform can't enumerate chats (most can't), add it to the
+session-based discovery list:
+
+```python
+for plat_name in ("telegram", "whatsapp", "signal", "your_platform"):
+```
+
+---
+
+## 12. Status Display (`hermes_cli/status.py`)
+
+Add to the `platforms` dict in the Messaging Platforms section:
+
+```python
+platforms = {
+    ...
+    "Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
+}
+```
+
+---
+
+## 13. Gateway Setup Wizard (`hermes_cli/gateway.py`)
+
+Add to the `_PLATFORMS` list:
+
+```python
+{
+    "key": "your_platform",
+    "label": "Your Platform",
+    "emoji": "📱",
+    "token_var": "YOUR_PLATFORM_TOKEN",
+    "setup_instructions": [...],
+    "vars": [...],
+}
+```
+
+If your platform needs custom setup logic (connectivity testing, QR codes,
+policy choices), add a `_setup_your_platform()` function and route to it
+in the platform selection switch.
+
+Update `_platform_status()` if your platform's "configured" check differs
+from the standard `bool(get_env_value(token_var))`.
+
+---
+
+## 14. Phone/ID Redaction (`agent/redact.py`)
+
+If your platform uses sensitive identifiers (phone numbers, etc.), add a
+regex pattern and redaction function to `agent/redact.py`. This ensures
+identifiers are masked in ALL log output, not just your adapter's logs.
+
+---
+
+## 15. Documentation
+
+| File | What to update |
+|------|---------------|
+| `README.md` | Platform list in feature table + documentation table |
+| `AGENTS.md` | Gateway description + env var config section |
+| `website/docs/user-guide/messaging/<platform>.md` | **NEW** — Full setup guide (see existing platform docs for template) |
+| `website/docs/user-guide/messaging/index.md` | Architecture diagram, toolset table, security examples, Next Steps links |
+| `website/docs/reference/environment-variables.md` | All env vars for the platform |
+
+---
+
+## 16. Tests (`tests/gateway/test_<platform>.py`)
+
+Recommended test coverage:
+
+- Platform enum exists with correct value
+- Config loading from env vars via `_apply_env_overrides`
+- Adapter init (config parsing, allowlist handling, default values)
+- Helper functions (redaction, parsing, file type detection)
+- Session source round-trip (to_dict → from_dict)
+- Authorization integration (platform in allowlist maps)
+- Send message tool routing (platform in platform_map)
+
+Optional but valuable:
+- Async tests for message handling flow (mock the platform API)
+- SSE/WebSocket reconnection logic
+- Attachment processing
+- Group message filtering
+
+---
+
+## Quick Verification
+
+After implementing everything, verify with:
+
+```bash
+# All tests pass
+python -m pytest tests/ -q
+
+# Grep for your platform name to find any missed integration points
+grep -r "telegram\|discord\|whatsapp\|slack" gateway/ tools/ agent/ cron/ hermes_cli/ toolsets.py \
+  --include="*.py" -l | sort -u
+# Check each file in the output — if it mentions other platforms but not yours, you missed it
+```

gateway/platforms/base.py

@@ -838,6 +838,8 @@ class BasePlatformAdapter(ABC):
         user_name: Optional[str] = None,
         thread_id: Optional[str] = None,
         chat_topic: Optional[str] = None,
+        user_id_alt: Optional[str] = None,
+        chat_id_alt: Optional[str] = None,
     ) -> SessionSource:
         """Helper to build a SessionSource for this platform."""
         # Normalize empty topic to None
@@ -852,6 +854,8 @@ class BasePlatformAdapter(ABC):
             user_name=user_name,
             thread_id=str(thread_id) if thread_id else None,
             chat_topic=chat_topic.strip() if chat_topic else None,
+            user_id_alt=user_id_alt,
+            chat_id_alt=chat_id_alt,
         )
     
     @abstractmethod

gateway/platforms/signal.py

@@ -0,0 +1,716 @@
+"""Signal messenger platform adapter.
+
+Connects to a signal-cli daemon running in HTTP mode.
+Inbound messages arrive via SSE (Server-Sent Events) streaming.
+Outbound messages and actions use JSON-RPC 2.0 over HTTP.
+
+Based on PR #268 by ibhagwan, rebuilt with bug fixes.
+
+Requires:
+  - signal-cli installed and running: signal-cli daemon --http 127.0.0.1:8080
+  - SIGNAL_HTTP_URL and SIGNAL_ACCOUNT environment variables set
+"""
+
+import asyncio
+import base64
+import json
+import logging
+import os
+import random
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional, Any
+from urllib.parse import unquote
+
+import httpx
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import (
+    BasePlatformAdapter,
+    MessageEvent,
+    MessageType,
+    SendResult,
+    cache_image_from_bytes,
+    cache_audio_from_bytes,
+    cache_document_from_bytes,
+    cache_image_from_url,
+)
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+SIGNAL_MAX_ATTACHMENT_SIZE = 100 * 1024 * 1024  # 100 MB
+MAX_MESSAGE_LENGTH = 8000  # Signal message size limit
+TYPING_INTERVAL = 8.0  # seconds between typing indicator refreshes
+SSE_RETRY_DELAY_INITIAL = 2.0
+SSE_RETRY_DELAY_MAX = 60.0
+HEALTH_CHECK_INTERVAL = 30.0  # seconds between health checks
+HEALTH_CHECK_STALE_THRESHOLD = 120.0  # seconds without SSE activity before concern
+
+# E.164 phone number pattern for redaction
+_PHONE_RE = re.compile(r"\+[1-9]\d{6,14}")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _redact_phone(phone: str) -> str:
+    """Redact a phone number for logging: +15551234567 -> +155****4567."""
+    if not phone:
+        return "<none>"
+    if len(phone) <= 8:
+        return phone[:2] + "****" + phone[-2:] if len(phone) > 4 else "****"
+    return phone[:4] + "****" + phone[-4:]
+
+
+def _parse_comma_list(value: str) -> List[str]:
+    """Split a comma-separated string into a list, stripping whitespace."""
+    return [v.strip() for v in value.split(",") if v.strip()]
+
+
+def _guess_extension(data: bytes) -> str:
+    """Guess file extension from magic bytes."""
+    if data[:4] == b"\x89PNG":
+        return ".png"
+    if data[:2] == b"\xff\xd8":
+        return ".jpg"
+    if data[:4] == b"GIF8":
+        return ".gif"
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return ".webp"
+    if data[:4] == b"%PDF":
+        return ".pdf"
+    if len(data) >= 8 and data[4:8] == b"ftyp":
+        return ".mp4"
+    if data[:4] == b"OggS":
+        return ".ogg"
+    if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+        return ".mp3"
+    if data[:2] == b"PK":
+        return ".zip"
+    return ".bin"
+
+
+def _is_image_ext(ext: str) -> bool:
+    return ext.lower() in (".jpg", ".jpeg", ".png", ".gif", ".webp")
+
+
+def _is_audio_ext(ext: str) -> bool:
+    return ext.lower() in (".mp3", ".wav", ".ogg", ".m4a", ".aac")
+
+
+def _render_mentions(text: str, mentions: list) -> str:
+    """Replace Signal mention placeholders (\\uFFFC) with readable @identifiers.
+
+    Signal encodes @mentions as the Unicode object replacement character
+    with out-of-band metadata containing the mentioned user's UUID/number.
+    """
+    if not mentions or "\uFFFC" not in text:
+        return text
+    # Sort mentions by start position (reverse) to replace from end to start
+    # so indices don't shift as we replace
+    sorted_mentions = sorted(mentions, key=lambda m: m.get("start", 0), reverse=True)
+    for mention in sorted_mentions:
+        start = mention.get("start", 0)
+        length = mention.get("length", 1)
+        # Use the mention's number or UUID as the replacement
+        identifier = mention.get("number") or mention.get("uuid") or "user"
+        replacement = f"@{identifier}"
+        text = text[:start] + replacement + text[start + length:]
+    return text
+
+
+def check_signal_requirements() -> bool:
+    """Check if Signal is configured (has URL and account)."""
+    return bool(os.getenv("SIGNAL_HTTP_URL") and os.getenv("SIGNAL_ACCOUNT"))
+
+
+# ---------------------------------------------------------------------------
+# Signal Adapter
+# ---------------------------------------------------------------------------
+
+class SignalAdapter(BasePlatformAdapter):
+    """Signal messenger adapter using signal-cli HTTP daemon."""
+
+    platform = Platform.SIGNAL
+
+    def __init__(self, config: PlatformConfig):
+        super().__init__(config, Platform.SIGNAL)
+
+        extra = config.extra or {}
+        self.http_url = extra.get("http_url", "http://127.0.0.1:8080").rstrip("/")
+        self.account = extra.get("account", "")
+        self.ignore_stories = extra.get("ignore_stories", True)
+
+        # Parse allowlists — group policy is derived from presence of group allowlist
+        group_allowed_str = os.getenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+        self.group_allow_from = set(_parse_comma_list(group_allowed_str))
+
+        # HTTP client
+        self.client: Optional[httpx.AsyncClient] = None
+
+        # Background tasks
+        self._sse_task: Optional[asyncio.Task] = None
+        self._health_monitor_task: Optional[asyncio.Task] = None
+        self._typing_tasks: Dict[str, asyncio.Task] = {}
+        self._running = False
+        self._last_sse_activity = 0.0
+        self._sse_response: Optional[httpx.Response] = None
+
+        # Normalize account for self-message filtering
+        self._account_normalized = self.account.strip()
+
+        logger.info("Signal adapter initialized: url=%s account=%s groups=%s",
+                     self.http_url, _redact_phone(self.account),
+                     "enabled" if self.group_allow_from else "disabled")
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Connect to signal-cli daemon and start SSE listener."""
+        if not self.http_url or not self.account:
+            logger.error("Signal: SIGNAL_HTTP_URL and SIGNAL_ACCOUNT are required")
+            return False
+
+        self.client = httpx.AsyncClient(timeout=30.0)
+
+        # Health check — verify signal-cli daemon is reachable
+        try:
+            resp = await self.client.get(f"{self.http_url}/api/v1/check", timeout=10.0)
+            if resp.status_code != 200:
+                logger.error("Signal: health check failed (status %d)", resp.status_code)
+                return False
+        except Exception as e:
+            logger.error("Signal: cannot reach signal-cli at %s: %s", self.http_url, e)
+            return False
+
+        self._running = True
+        self._last_sse_activity = time.time()
+        self._sse_task = asyncio.create_task(self._sse_listener())
+        self._health_monitor_task = asyncio.create_task(self._health_monitor())
+
+        logger.info("Signal: connected to %s", self.http_url)
+        return True
+
+    async def disconnect(self) -> None:
+        """Stop SSE listener and clean up."""
+        self._running = False
+
+        if self._sse_task:
+            self._sse_task.cancel()
+            try:
+                await self._sse_task
+            except asyncio.CancelledError:
+                pass
+
+        if self._health_monitor_task:
+            self._health_monitor_task.cancel()
+            try:
+                await self._health_monitor_task
+            except asyncio.CancelledError:
+                pass
+
+        # Cancel all typing tasks
+        for task in self._typing_tasks.values():
+            task.cancel()
+        self._typing_tasks.clear()
+
+        if self.client:
+            await self.client.aclose()
+            self.client = None
+
+        logger.info("Signal: disconnected")
+
+    # ------------------------------------------------------------------
+    # SSE Streaming (inbound messages)
+    # ------------------------------------------------------------------
+
+    async def _sse_listener(self) -> None:
+        """Listen for SSE events from signal-cli daemon."""
+        url = f"{self.http_url}/api/v1/events?account={self.account}"
+        backoff = SSE_RETRY_DELAY_INITIAL
+
+        while self._running:
+            try:
+                logger.debug("Signal SSE: connecting to %s", url)
+                async with self.client.stream(
+                    "GET", url,
+                    headers={"Accept": "text/event-stream"},
+                    timeout=None,
+                ) as response:
+                    self._sse_response = response
+                    backoff = SSE_RETRY_DELAY_INITIAL  # Reset on successful connection
+                    self._last_sse_activity = time.time()
+                    logger.info("Signal SSE: connected")
+
+                    buffer = ""
+                    async for chunk in response.aiter_text():
+                        if not self._running:
+                            break
+                        buffer += chunk
+                        while "\n" in buffer:
+                            line, buffer = buffer.split("\n", 1)
+                            line = line.strip()
+                            if not line:
+                                continue
+                            # Parse SSE data lines
+                            if line.startswith("data:"):
+                                data_str = line[5:].strip()
+                                if not data_str:
+                                    continue
+                                self._last_sse_activity = time.time()
+                                try:
+                                    data = json.loads(data_str)
+                                    await self._handle_envelope(data)
+                                except json.JSONDecodeError:
+                                    logger.debug("Signal SSE: invalid JSON: %s", data_str[:100])
+                                except Exception:
+                                    logger.exception("Signal SSE: error handling event")
+
+            except asyncio.CancelledError:
+                break
+            except httpx.HTTPError as e:
+                if self._running:
+                    logger.warning("Signal SSE: HTTP error: %s (reconnecting in %.0fs)", e, backoff)
+            except Exception as e:
+                if self._running:
+                    logger.warning("Signal SSE: error: %s (reconnecting in %.0fs)", e, backoff)
+
+            if self._running:
+                # Add 20% jitter to prevent thundering herd on reconnection
+                jitter = backoff * 0.2 * random.random()
+                await asyncio.sleep(backoff + jitter)
+                backoff = min(backoff * 2, SSE_RETRY_DELAY_MAX)
+
+        self._sse_response = None
+
+    # ------------------------------------------------------------------
+    # Health Monitor
+    # ------------------------------------------------------------------
+
+    async def _health_monitor(self) -> None:
+        """Monitor SSE connection health and force reconnect if stale."""
+        while self._running:
+            await asyncio.sleep(HEALTH_CHECK_INTERVAL)
+            if not self._running:
+                break
+
+            elapsed = time.time() - self._last_sse_activity
+            if elapsed > HEALTH_CHECK_STALE_THRESHOLD:
+                logger.warning("Signal: SSE idle for %.0fs, checking daemon health", elapsed)
+                try:
+                    resp = await self.client.get(
+                        f"{self.http_url}/api/v1/check", timeout=10.0
+                    )
+                    if resp.status_code == 200:
+                        # Daemon is alive but SSE is idle — update activity to
+                        # avoid repeated warnings (connection may just be quiet)
+                        self._last_sse_activity = time.time()
+                        logger.debug("Signal: daemon healthy, SSE idle")
+                    else:
+                        logger.warning("Signal: health check failed (%d), forcing reconnect", resp.status_code)
+                        self._force_reconnect()
+                except Exception as e:
+                    logger.warning("Signal: health check error: %s, forcing reconnect", e)
+                    self._force_reconnect()
+
+    def _force_reconnect(self) -> None:
+        """Force SSE reconnection by closing the current response."""
+        if self._sse_response and not self._sse_response.is_stream_consumed:
+            try:
+                asyncio.create_task(self._sse_response.aclose())
+            except Exception:
+                pass
+            self._sse_response = None
+
+    # ------------------------------------------------------------------
+    # Message Handling
+    # ------------------------------------------------------------------
+
+    async def _handle_envelope(self, envelope: dict) -> None:
+        """Process an incoming signal-cli envelope."""
+        # Unwrap nested envelope if present
+        envelope_data = envelope.get("envelope", envelope)
+
+        # Filter syncMessage envelopes (sent transcripts, read receipts, etc.)
+        # signal-cli may set syncMessage to null vs omitting it, so check key existence
+        if "syncMessage" in envelope_data:
+            return
+
+        # Extract sender info
+        sender = (
+            envelope_data.get("sourceNumber")
+            or envelope_data.get("sourceUuid")
+            or envelope_data.get("source")
+        )
+        sender_name = envelope_data.get("sourceName", "")
+        sender_uuid = envelope_data.get("sourceUuid", "")
+
+        if not sender:
+            logger.debug("Signal: ignoring envelope with no sender")
+            return
+
+        # Self-message filtering — prevent reply loops
+        if self._account_normalized and sender == self._account_normalized:
+            return
+
+        # Filter stories
+        if self.ignore_stories and envelope_data.get("storyMessage"):
+            return
+
+        # Get data message — also check editMessage (edited messages contain
+        # their updated dataMessage inside editMessage.dataMessage)
+        data_message = (
+            envelope_data.get("dataMessage")
+            or (envelope_data.get("editMessage") or {}).get("dataMessage")
+        )
+        if not data_message:
+            return
+
+        # Check for group message
+        group_info = data_message.get("groupInfo")
+        group_id = group_info.get("groupId") if group_info else None
+        is_group = bool(group_id)
+
+        # Group message filtering — derived from SIGNAL_GROUP_ALLOWED_USERS:
+        # - No env var set → groups disabled (default safe behavior)
+        # - Env var set with group IDs → only those groups allowed
+        # - Env var set with "*" → all groups allowed
+        # DM auth is fully handled by run.py (_is_user_authorized)
+        if is_group:
+            if not self.group_allow_from:
+                logger.debug("Signal: ignoring group message (no SIGNAL_GROUP_ALLOWED_USERS)")
+                return
+            if "*" not in self.group_allow_from and group_id not in self.group_allow_from:
+                logger.debug("Signal: group %s not in allowlist", group_id[:8] if group_id else "?")
+                return
+
+        # Build chat info
+        chat_id = sender if not is_group else f"group:{group_id}"
+        chat_type = "group" if is_group else "dm"
+
+        # Extract text and render mentions
+        text = data_message.get("message", "")
+        mentions = data_message.get("mentions", [])
+        if text and mentions:
+            text = _render_mentions(text, mentions)
+
+        # Process attachments
+        attachments_data = data_message.get("attachments", [])
+        image_paths = []
+        audio_path = None
+        document_paths = []
+
+        if attachments_data and not getattr(self, "ignore_attachments", False):
+            for att in attachments_data:
+                att_id = att.get("id")
+                att_size = att.get("size", 0)
+                if not att_id:
+                    continue
+                if att_size > SIGNAL_MAX_ATTACHMENT_SIZE:
+                    logger.warning("Signal: attachment too large (%d bytes), skipping", att_size)
+                    continue
+                try:
+                    cached_path, ext = await self._fetch_attachment(att_id)
+                    if cached_path:
+                        if _is_image_ext(ext):
+                            image_paths.append(cached_path)
+                        elif _is_audio_ext(ext):
+                            audio_path = cached_path
+                        else:
+                            document_paths.append(cached_path)
+                except Exception:
+                    logger.exception("Signal: failed to fetch attachment %s", att_id)
+
+        # Build session source
+        source = self.build_source(
+            chat_id=chat_id,
+            chat_name=group_info.get("groupName") if group_info else sender_name,
+            chat_type=chat_type,
+            user_id=sender,
+            user_name=sender_name or sender,
+            user_id_alt=sender_uuid if sender_uuid else None,
+            chat_id_alt=group_id if is_group else None,
+        )
+
+        # Determine message type
+        msg_type = MessageType.TEXT
+        if audio_path:
+            msg_type = MessageType.VOICE
+        elif image_paths:
+            msg_type = MessageType.IMAGE
+
+        # Parse timestamp from envelope data (milliseconds since epoch)
+        ts_ms = envelope_data.get("timestamp", 0)
+        if ts_ms:
+            try:
+                timestamp = datetime.fromtimestamp(ts_ms / 1000, tz=timezone.utc)
+            except (ValueError, OSError):
+                timestamp = datetime.now(tz=timezone.utc)
+        else:
+            timestamp = datetime.now(tz=timezone.utc)
+
+        # Build and dispatch event
+        event = MessageEvent(
+            source=source,
+            text=text or "",
+            message_type=msg_type,
+            image_paths=image_paths,
+            audio_path=audio_path,
+            document_paths=document_paths,
+            timestamp=timestamp,
+        )
+
+        logger.debug("Signal: message from %s in %s: %s",
+                      _redact_phone(sender), chat_id[:20], (text or "")[:50])
+
+        await self.handle_message(event)
+
+    # ------------------------------------------------------------------
+    # Attachment Handling
+    # ------------------------------------------------------------------
+
+    async def _fetch_attachment(self, attachment_id: str) -> tuple:
+        """Fetch an attachment via JSON-RPC and cache it. Returns (path, ext)."""
+        result = await self._rpc("getAttachment", {
+            "account": self.account,
+            "attachmentId": attachment_id,
+        })
+
+        if not result:
+            return None, ""
+
+        # Result is base64-encoded file content
+        raw_data = base64.b64decode(result)
+        ext = _guess_extension(raw_data)
+
+        if _is_image_ext(ext):
+            path = cache_image_from_bytes(raw_data, ext)
+        elif _is_audio_ext(ext):
+            path = cache_audio_from_bytes(raw_data, ext)
+        else:
+            path = cache_document_from_bytes(raw_data, ext)
+
+        return path, ext
+
+    # ------------------------------------------------------------------
+    # JSON-RPC Communication
+    # ------------------------------------------------------------------
+
+    async def _rpc(self, method: str, params: dict, rpc_id: str = None) -> Any:
+        """Send a JSON-RPC 2.0 request to signal-cli daemon."""
+        if not self.client:
+            logger.warning("Signal: RPC called but client not connected")
+            return None
+
+        if rpc_id is None:
+            rpc_id = f"{method}_{int(time.time() * 1000)}"
+
+        payload = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "params": params,
+            "id": rpc_id,
+        }
+
+        try:
+            resp = await self.client.post(
+                f"{self.http_url}/api/v1/rpc",
+                json=payload,
+                timeout=30.0,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+
+            if "error" in data:
+                logger.warning("Signal RPC error (%s): %s", method, data["error"])
+                return None
+
+            return data.get("result")
+
+        except Exception as e:
+            logger.warning("Signal RPC %s failed: %s", method, e)
+            return None
+
+    # ------------------------------------------------------------------
+    # Sending
+    # ------------------------------------------------------------------
+
+    async def send(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to_message_id: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a text message."""
+        await self._stop_typing_indicator(chat_id)
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": text,
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+
+        if result is not None:
+            return SendResult(success=True)
+        return SendResult(success=False, error="RPC send failed")
+
+    async def send_typing(self, chat_id: str) -> None:
+        """Send a typing indicator."""
+        params: Dict[str, Any] = {
+            "account": self.account,
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        await self._rpc("sendTyping", params, rpc_id="typing")
+
+    async def send_image(
+        self,
+        chat_id: str,
+        image_url: str,
+        caption: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send an image. Supports http(s):// and file:// URLs."""
+        await self._stop_typing_indicator(chat_id)
+
+        # Resolve image to local path
+        if image_url.startswith("file://"):
+            file_path = unquote(image_url[7:])
+        else:
+            # Download remote image to cache
+            try:
+                file_path = await cache_image_from_url(image_url)
+            except Exception as e:
+                logger.warning("Signal: failed to download image: %s", e)
+                return SendResult(success=False, error=str(e))
+
+        if not file_path or not Path(file_path).exists():
+            return SendResult(success=False, error="Image file not found")
+
+        # Validate size
+        file_size = Path(file_path).stat().st_size
+        if file_size > SIGNAL_MAX_ATTACHMENT_SIZE:
+            return SendResult(success=False, error=f"Image too large ({file_size} bytes)")
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": caption or "",
+            "attachments": [file_path],
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+        if result is not None:
+            return SendResult(success=True)
+        return SendResult(success=False, error="RPC send with attachment failed")
+
+    async def send_document(
+        self,
+        chat_id: str,
+        file_path: str,
+        caption: Optional[str] = None,
+        filename: Optional[str] = None,
+        **kwargs,
+    ) -> SendResult:
+        """Send a document/file attachment."""
+        await self._stop_typing_indicator(chat_id)
+
+        if not Path(file_path).exists():
+            return SendResult(success=False, error="File not found")
+
+        params: Dict[str, Any] = {
+            "account": self.account,
+            "message": caption or "",
+            "attachments": [file_path],
+        }
+
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        result = await self._rpc("send", params)
+        if result is not None:
+            return SendResult(success=True)
+        return SendResult(success=False, error="RPC send document failed")
+
+    # ------------------------------------------------------------------
+    # Typing Indicators
+    # ------------------------------------------------------------------
+
+    async def _start_typing_indicator(self, chat_id: str) -> None:
+        """Start a typing indicator loop for a chat."""
+        if chat_id in self._typing_tasks:
+            return  # Already running
+
+        async def _typing_loop():
+            try:
+                while True:
+                    await self.send_typing(chat_id)
+                    await asyncio.sleep(TYPING_INTERVAL)
+            except asyncio.CancelledError:
+                pass
+
+        self._typing_tasks[chat_id] = asyncio.create_task(_typing_loop())
+
+    async def _stop_typing_indicator(self, chat_id: str) -> None:
+        """Stop a typing indicator loop for a chat."""
+        task = self._typing_tasks.pop(chat_id, None)
+        if task:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    # ------------------------------------------------------------------
+    # Chat Info
+    # ------------------------------------------------------------------
+
+    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
+        """Get information about a chat/contact."""
+        if chat_id.startswith("group:"):
+            return {
+                "name": chat_id,
+                "type": "group",
+                "chat_id": chat_id,
+            }
+
+        # Try to resolve contact name
+        result = await self._rpc("getContact", {
+            "account": self.account,
+            "contactAddress": chat_id,
+        })
+
+        name = chat_id
+        if result and isinstance(result, dict):
+            name = result.get("name") or result.get("profileName") or chat_id
+
+        return {
+            "name": name,
+            "type": "dm",
+            "chat_id": chat_id,
+        }

gateway/run.py

@@ -118,6 +118,12 @@ if _config_path.exists():
         _tz_cfg = _cfg.get("timezone", "")
         if _tz_cfg and isinstance(_tz_cfg, str) and "HERMES_TIMEZONE" not in os.environ:
             os.environ["HERMES_TIMEZONE"] = _tz_cfg.strip()
+        # Security settings
+        _security_cfg = _cfg.get("security", {})
+        if isinstance(_security_cfg, dict):
+            _redact = _security_cfg.get("redact_secrets")
+            if _redact is not None:
+                os.environ["HERMES_REDACT_SECRETS"] = str(_redact).lower()
     except Exception:
         pass  # Non-fatal; gateway can still run with .env values
 
@@ -194,6 +200,7 @@ class GatewayRunner:
         self._ephemeral_system_prompt = self._load_ephemeral_system_prompt()
         self._reasoning_config = self._load_reasoning_config()
         self._provider_routing = self._load_provider_routing()
+        self._fallback_model = self._load_fallback_model()
 
         # Wire process registry into session store for reset protection
         from tools.process_registry import process_registry
@@ -393,6 +400,26 @@ class GatewayRunner:
             pass
         return {}
 
+    @staticmethod
+    def _load_fallback_model() -> dict | None:
+        """Load fallback model config from config.yaml.
+
+        Returns a dict with 'provider' and 'model' keys, or None if
+        not configured / both fields empty.
+        """
+        try:
+            import yaml as _y
+            cfg_path = _hermes_home / "config.yaml"
+            if cfg_path.exists():
+                with open(cfg_path) as _f:
+                    cfg = _y.safe_load(_f) or {}
+                fb = cfg.get("fallback_model", {}) or {}
+                if fb.get("provider") and fb.get("model"):
+                    return fb
+        except Exception:
+            pass
+        return None
+
     async def start(self) -> bool:
         """
         Start the gateway and all configured platform adapters.
@@ -591,6 +618,13 @@ class GatewayRunner:
                 return None
             return SlackAdapter(config)
 
+        elif platform == Platform.SIGNAL:
+            from gateway.platforms.signal import SignalAdapter, check_signal_requirements
+            if not check_signal_requirements():
+                logger.warning("Signal: SIGNAL_HTTP_URL or SIGNAL_ACCOUNT not configured")
+                return None
+            return SignalAdapter(config)
+
         elif platform == Platform.HOMEASSISTANT:
             from gateway.platforms.homeassistant import HomeAssistantAdapter, check_ha_requirements
             if not check_ha_requirements():
@@ -626,12 +660,14 @@ class GatewayRunner:
             Platform.DISCORD: "DISCORD_ALLOWED_USERS",
             Platform.WHATSAPP: "WHATSAPP_ALLOWED_USERS",
             Platform.SLACK: "SLACK_ALLOWED_USERS",
+            Platform.SIGNAL: "SIGNAL_ALLOWED_USERS",
         }
         platform_allow_all_map = {
             Platform.TELEGRAM: "TELEGRAM_ALLOW_ALL_USERS",
             Platform.DISCORD: "DISCORD_ALLOW_ALL_USERS",
             Platform.WHATSAPP: "WHATSAPP_ALLOW_ALL_USERS",
             Platform.SLACK: "SLACK_ALLOW_ALL_USERS",
+            Platform.SIGNAL: "SIGNAL_ALLOW_ALL_USERS",
         }
 
         # Per-platform allow-all flag (e.g., DISCORD_ALLOW_ALL_USERS=true)
@@ -870,159 +906,187 @@ class GatewayRunner:
         # every new message rehydrates an oversized transcript, causing
         # repeated truncation/context failures.  Detect this early and
         # compress proactively — before the agent even starts.  (#628)
+        #
+        # Thresholds are derived from the SAME compression config the
+        # agent uses (compression.threshold × model context length) so
+        # CLI and messaging platforms behave identically.
         # -----------------------------------------------------------------
         if history and len(history) >= 4:
-            from agent.model_metadata import estimate_messages_tokens_rough
+            from agent.model_metadata import (
+                estimate_messages_tokens_rough,
+                get_model_context_length,
+            )
 
-            # Read thresholds from config.yaml → session_hygiene section
-            _hygiene_cfg = {}
+            # Read model + compression config from config.yaml — same
+            # source of truth the agent itself uses.
+            _hyg_model = "anthropic/claude-sonnet-4.6"
+            _hyg_threshold_pct = 0.85
+            _hyg_compression_enabled = True
             try:
                 _hyg_cfg_path = _hermes_home / "config.yaml"
                 if _hyg_cfg_path.exists():
                     import yaml as _hyg_yaml
                     with open(_hyg_cfg_path) as _hyg_f:
                         _hyg_data = _hyg_yaml.safe_load(_hyg_f) or {}
-                    _hygiene_cfg = _hyg_data.get("session_hygiene", {})
-                    if not isinstance(_hygiene_cfg, dict):
-                        _hygiene_cfg = {}
+
+                    # Resolve model name (same logic as run_sync)
+                    _model_cfg = _hyg_data.get("model", {})
+                    if isinstance(_model_cfg, str):
+                        _hyg_model = _model_cfg
+                    elif isinstance(_model_cfg, dict):
+                        _hyg_model = _model_cfg.get("default", _hyg_model)
+
+                    # Read compression settings
+                    _comp_cfg = _hyg_data.get("compression", {})
+                    if isinstance(_comp_cfg, dict):
+                        _hyg_threshold_pct = float(
+                            _comp_cfg.get("threshold", _hyg_threshold_pct)
+                        )
+                        _hyg_compression_enabled = str(
+                            _comp_cfg.get("enabled", True)
+                        ).lower() in ("true", "1", "yes")
             except Exception:
                 pass
 
-            _compress_token_threshold = int(
-                _hygiene_cfg.get("auto_compress_tokens", 100_000)
-            )
-            _compress_msg_threshold = int(
-                _hygiene_cfg.get("auto_compress_messages", 200)
-            )
-            _warn_token_threshold = int(
-                _hygiene_cfg.get("warn_tokens", 200_000)
+            # Also check env overrides (same as run_agent.py)
+            _hyg_threshold_pct = float(
+                os.getenv("CONTEXT_COMPRESSION_THRESHOLD", str(_hyg_threshold_pct))
             )
+            if os.getenv("CONTEXT_COMPRESSION_ENABLED", "").lower() in ("false", "0", "no"):
+                _hyg_compression_enabled = False
 
-            _msg_count = len(history)
-            _approx_tokens = estimate_messages_tokens_rough(history)
-
-            _needs_compress = (
-                _approx_tokens >= _compress_token_threshold
-                or _msg_count >= _compress_msg_threshold
-            )
-
-            if _needs_compress:
-                logger.info(
-                    "Session hygiene: %s messages, ~%s tokens — auto-compressing "
-                    "(thresholds: %s msgs / %s tokens)",
-                    _msg_count, f"{_approx_tokens:,}",
-                    _compress_msg_threshold, f"{_compress_token_threshold:,}",
+            if _hyg_compression_enabled:
+                _hyg_context_length = get_model_context_length(_hyg_model)
+                _compress_token_threshold = int(
+                    _hyg_context_length * _hyg_threshold_pct
                 )
+                # Warn if still huge after compression (95% of context)
+                _warn_token_threshold = int(_hyg_context_length * 0.95)
+
+                _msg_count = len(history)
+                _approx_tokens = estimate_messages_tokens_rough(history)
+
+                _needs_compress = _approx_tokens >= _compress_token_threshold
+
+                if _needs_compress:
+                    logger.info(
+                        "Session hygiene: %s messages, ~%s tokens — auto-compressing "
+                        "(threshold: %s%% of %s = %s tokens)",
+                        _msg_count, f"{_approx_tokens:,}",
+                        int(_hyg_threshold_pct * 100),
+                        f"{_hyg_context_length:,}",
+                        f"{_compress_token_threshold:,}",
+                    )
+
+                    _hyg_adapter = self.adapters.get(source.platform)
+                    if _hyg_adapter:
+                        try:
+                            await _hyg_adapter.send(
+                                source.chat_id,
+                                f"🗜️ Session is large ({_msg_count} messages, "
+                                f"~{_approx_tokens:,} tokens). Auto-compressing..."
+                            )
+                        except Exception:
+                            pass
 
-                _hyg_adapter = self.adapters.get(source.platform)
-                if _hyg_adapter:
                     try:
-                        await _hyg_adapter.send(
-                            source.chat_id,
-                            f"🗜️ Session is large ({_msg_count} messages, "
-                            f"~{_approx_tokens:,} tokens). Auto-compressing..."
-                        )
-                    except Exception:
-                        pass
+                        from run_agent import AIAgent
 
-                try:
-                    from run_agent import AIAgent
+                        _hyg_runtime = _resolve_runtime_agent_kwargs()
+                        if _hyg_runtime.get("api_key"):
+                            _hyg_msgs = [
+                                {"role": m.get("role"), "content": m.get("content")}
+                                for m in history
+                                if m.get("role") in ("user", "assistant")
+                                and m.get("content")
+                            ]
 
-                    _hyg_runtime = _resolve_runtime_agent_kwargs()
-                    if _hyg_runtime.get("api_key"):
-                        _hyg_msgs = [
-                            {"role": m.get("role"), "content": m.get("content")}
-                            for m in history
-                            if m.get("role") in ("user", "assistant")
-                            and m.get("content")
-                        ]
-
-                        if len(_hyg_msgs) >= 4:
-                            _hyg_agent = AIAgent(
-                                **_hyg_runtime,
-                                max_iterations=4,
-                                quiet_mode=True,
-                                enabled_toolsets=["memory"],
-                                session_id=session_entry.session_id,
-                            )
-
-                            loop = asyncio.get_event_loop()
-                            _compressed, _ = await loop.run_in_executor(
-                                None,
-                                lambda: _hyg_agent._compress_context(
-                                    _hyg_msgs, "",
-                                    approx_tokens=_approx_tokens,
-                                ),
-                            )
-
-                            self.session_store.rewrite_transcript(
-                                session_entry.session_id, _compressed
-                            )
-                            history = _compressed
-                            _new_count = len(_compressed)
-                            _new_tokens = estimate_messages_tokens_rough(
-                                _compressed
-                            )
-
-                            logger.info(
-                                "Session hygiene: compressed %s → %s msgs, "
-                                "~%s → ~%s tokens",
-                                _msg_count, _new_count,
-                                f"{_approx_tokens:,}", f"{_new_tokens:,}",
-                            )
-
-                            if _hyg_adapter:
-                                try:
-                                    await _hyg_adapter.send(
-                                        source.chat_id,
-                                        f"🗜️ Compressed: {_msg_count} → "
-                                        f"{_new_count} messages, "
-                                        f"~{_approx_tokens:,} → "
-                                        f"~{_new_tokens:,} tokens"
-                                    )
-                                except Exception:
-                                    pass
-
-                            # Still too large after compression — warn user
-                            if _new_tokens >= _warn_token_threshold:
-                                logger.warning(
-                                    "Session hygiene: still ~%s tokens after "
-                                    "compression — suggesting /reset",
-                                    f"{_new_tokens:,}",
+                            if len(_hyg_msgs) >= 4:
+                                _hyg_agent = AIAgent(
+                                    **_hyg_runtime,
+                                    max_iterations=4,
+                                    quiet_mode=True,
+                                    enabled_toolsets=["memory"],
+                                    session_id=session_entry.session_id,
                                 )
+
+                                loop = asyncio.get_event_loop()
+                                _compressed, _ = await loop.run_in_executor(
+                                    None,
+                                    lambda: _hyg_agent._compress_context(
+                                        _hyg_msgs, "",
+                                        approx_tokens=_approx_tokens,
+                                    ),
+                                )
+
+                                self.session_store.rewrite_transcript(
+                                    session_entry.session_id, _compressed
+                                )
+                                history = _compressed
+                                _new_count = len(_compressed)
+                                _new_tokens = estimate_messages_tokens_rough(
+                                    _compressed
+                                )
+
+                                logger.info(
+                                    "Session hygiene: compressed %s → %s msgs, "
+                                    "~%s → ~%s tokens",
+                                    _msg_count, _new_count,
+                                    f"{_approx_tokens:,}", f"{_new_tokens:,}",
+                                )
+
                                 if _hyg_adapter:
                                     try:
                                         await _hyg_adapter.send(
                                             source.chat_id,
-                                            "⚠️ Session is still very large "
-                                            "after compression "
-                                            f"(~{_new_tokens:,} tokens). "
-                                            "Consider using /reset to start "
-                                            "fresh if you experience issues."
+                                            f"🗜️ Compressed: {_msg_count} → "
+                                            f"{_new_count} messages, "
+                                            f"~{_approx_tokens:,} → "
+                                            f"~{_new_tokens:,} tokens"
                                         )
                                     except Exception:
                                         pass
 
-                except Exception as e:
-                    logger.warning(
-                        "Session hygiene auto-compress failed: %s", e
-                    )
-                    # Compression failed and session is dangerously large
-                    if _approx_tokens >= _warn_token_threshold:
-                        _hyg_adapter = self.adapters.get(source.platform)
-                        if _hyg_adapter:
-                            try:
-                                await _hyg_adapter.send(
-                                    source.chat_id,
-                                    f"⚠️ Session is very large "
-                                    f"({_msg_count} messages, "
-                                    f"~{_approx_tokens:,} tokens) and "
-                                    "auto-compression failed. Consider "
-                                    "using /compress or /reset to avoid "
-                                    "issues."
-                                )
-                            except Exception:
-                                pass
+                                # Still too large after compression — warn user
+                                if _new_tokens >= _warn_token_threshold:
+                                    logger.warning(
+                                        "Session hygiene: still ~%s tokens after "
+                                        "compression — suggesting /reset",
+                                        f"{_new_tokens:,}",
+                                    )
+                                    if _hyg_adapter:
+                                        try:
+                                            await _hyg_adapter.send(
+                                                source.chat_id,
+                                                "⚠️ Session is still very large "
+                                                "after compression "
+                                                f"(~{_new_tokens:,} tokens). "
+                                                "Consider using /reset to start "
+                                                "fresh if you experience issues."
+                                            )
+                                        except Exception:
+                                            pass
+
+                    except Exception as e:
+                        logger.warning(
+                            "Session hygiene auto-compress failed: %s", e
+                        )
+                        # Compression failed and session is dangerously large
+                        if _approx_tokens >= _warn_token_threshold:
+                            _hyg_adapter = self.adapters.get(source.platform)
+                            if _hyg_adapter:
+                                try:
+                                    await _hyg_adapter.send(
+                                        source.chat_id,
+                                        f"⚠️ Session is very large "
+                                        f"({_msg_count} messages, "
+                                        f"~{_approx_tokens:,} tokens) and "
+                                        "auto-compression failed. Consider "
+                                        "using /compress or /reset to avoid "
+                                        "issues."
+                                    )
+                                except Exception:
+                                    pass
 
         # First-message onboarding -- only on the very first interaction ever
         if not history and not self.session_store.has_any_sessions():
@@ -2623,6 +2687,7 @@ class GatewayRunner:
                 platform=platform_key,
                 honcho_session_key=session_key,
                 session_db=self._session_db,
+                fallback_model=self._fallback_model,
             )
             
             # Store agent reference for interrupt support

gateway/session.py

@@ -45,6 +45,8 @@ class SessionSource:
     user_name: Optional[str] = None
     thread_id: Optional[str] = None  # For forum topics, Discord threads, etc.
     chat_topic: Optional[str] = None  # Channel topic/description (Discord, Slack)
+    user_id_alt: Optional[str] = None  # Signal UUID (alternative to phone number)
+    chat_id_alt: Optional[str] = None  # Signal group internal ID
     
     @property
     def description(self) -> str:
@@ -68,7 +70,7 @@ class SessionSource:
         return ", ".join(parts)
     
     def to_dict(self) -> Dict[str, Any]:
-        return {
+        d = {
             "platform": self.platform.value,
             "chat_id": self.chat_id,
             "chat_name": self.chat_name,
@@ -78,6 +80,11 @@ class SessionSource:
             "thread_id": self.thread_id,
             "chat_topic": self.chat_topic,
         }
+        if self.user_id_alt:
+            d["user_id_alt"] = self.user_id_alt
+        if self.chat_id_alt:
+            d["chat_id_alt"] = self.chat_id_alt
+        return d
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "SessionSource":
@@ -90,6 +97,8 @@ class SessionSource:
             user_name=data.get("user_name"),
             thread_id=data.get("thread_id"),
             chat_topic=data.get("chat_topic"),
+            user_id_alt=data.get("user_id_alt"),
+            chat_id_alt=data.get("chat_id_alt"),
         )
     
     @classmethod
@@ -333,7 +342,7 @@ class SessionStore:
         
         if sessions_file.exists():
             try:
-                with open(sessions_file, "r") as f:
+                with open(sessions_file, "r", encoding="utf-8") as f:
                     data = json.load(f)
                     for key, entry_data in data.items():
                         self._entries[key] = SessionEntry.from_dict(entry_data)
@@ -348,7 +357,7 @@ class SessionStore:
         sessions_file = self.sessions_dir / "sessions.json"
         
         data = {key: entry.to_dict() for key, entry in self._entries.items()}
-        with open(sessions_file, "w") as f:
+        with open(sessions_file, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
     
     def _generate_session_key(self, source: SessionSource) -> str:
@@ -672,7 +681,7 @@ class SessionStore:
         
         # Also write legacy JSONL (keeps existing tooling working during transition)
         transcript_path = self.get_transcript_path(session_id)
-        with open(transcript_path, "a") as f:
+        with open(transcript_path, "a", encoding="utf-8") as f:
             f.write(json.dumps(message, ensure_ascii=False) + "\n")
     
     def rewrite_transcript(self, session_id: str, messages: List[Dict[str, Any]]) -> None:
@@ -699,7 +708,7 @@ class SessionStore:
         
         # JSONL: overwrite the file
         transcript_path = self.get_transcript_path(session_id)
-        with open(transcript_path, "w") as f:
+        with open(transcript_path, "w", encoding="utf-8") as f:
             for msg in messages:
                 f.write(json.dumps(msg, ensure_ascii=False) + "\n")
 
@@ -721,7 +730,7 @@ class SessionStore:
             return []
         
         messages = []
-        with open(transcript_path, "r") as f:
+        with open(transcript_path, "r", encoding="utf-8") as f:
             for line in f:
                 line = line.strip()
                 if line:

hermes_cli/config.py

@@ -81,6 +81,7 @@ DEFAULT_CONFIG = {
     
     "browser": {
         "inactivity_timeout": 120,
+        "record_sessions": False,  # Auto-record browser sessions as WebM videos
     },
     
     "compression": {
@@ -107,6 +108,7 @@ DEFAULT_CONFIG = {
         "compact": False,
         "personality": "kawaii",
         "resume_display": "full",  # "full" (show previous messages) | "minimal" (one-liner only)
+        "bell_on_complete": False,  # Play terminal bell (\a) when agent finishes a response
     },
     
     # Text-to-speech configuration
@@ -437,7 +439,7 @@ OPTIONAL_ENV_VARS = {
         "category": "setting",
     },
     "HERMES_MAX_ITERATIONS": {
-        "description": "Maximum tool-calling iterations per conversation (default: 60)",
+        "description": "Maximum tool-calling iterations per conversation (default: 90)",
         "prompt": "Max iterations",
         "url": None,
         "password": False,
@@ -757,6 +759,36 @@ def load_config() -> Dict[str, Any]:
     return config
 
 
+_COMMENTED_SECTIONS = """
+# ── Security ──────────────────────────────────────────────────────────
+# API keys, tokens, and passwords are redacted from tool output by default.
+# Set to false to see full values (useful for debugging auth issues).
+#
+# security:
+#   redact_secrets: false
+
+# ── Fallback Model ────────────────────────────────────────────────────
+# Automatic provider failover when primary is unavailable.
+# Uncomment and configure to enable. Triggers on rate limits (429),
+# overload (529), service errors (503), or connection failures.
+#
+# Supported providers:
+#   openrouter   (OPENROUTER_API_KEY)  — routes to any model
+#   openai-codex (OAuth — hermes login) — OpenAI Codex
+#   nous         (OAuth — hermes login) — Nous Portal
+#   zai          (ZAI_API_KEY)         — Z.AI / GLM
+#   kimi-coding  (KIMI_API_KEY)        — Kimi / Moonshot
+#   minimax      (MINIMAX_API_KEY)     — MiniMax
+#   minimax-cn   (MINIMAX_CN_API_KEY)  — MiniMax (China)
+#
+# For custom OpenAI-compatible endpoints, add base_url and api_key_env.
+#
+# fallback_model:
+#   provider: openrouter
+#   model: anthropic/claude-sonnet-4
+"""
+
+
 def save_config(config: Dict[str, Any]):
     """Save configuration to ~/.hermes/config.yaml."""
     ensure_hermes_home()
@@ -764,6 +796,18 @@ def save_config(config: Dict[str, Any]):
     
     with open(config_path, 'w') as f:
         yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+        # Append commented-out sections for features that are off by default
+        # or only relevant when explicitly configured. Skip sections the
+        # user has already uncommented and configured.
+        sections = []
+        sec = config.get("security", {})
+        if not sec or sec.get("redact_secrets") is None:
+            sections.append("security")
+        fb = config.get("fallback_model", {})
+        if not fb or not (fb.get("provider") and fb.get("model")):
+            sections.append("fallback")
+        if sections:
+            f.write(_COMMENTED_SECTIONS)
 
 
 def load_env() -> Dict[str, str]:
@@ -1009,7 +1053,7 @@ def set_config_value(key: str, value: str):
         'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN',
         'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY',
         'SUDO_PASSWORD', 'SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN',
-        'GITHUB_TOKEN', 'HONCHO_API_KEY', 'NOUS_API_KEY', 'WANDB_API_KEY',
+        'GITHUB_TOKEN', 'HONCHO_API_KEY', 'WANDB_API_KEY',
         'TINKER_API_KEY',
     ]
     

hermes_cli/gateway.py

@@ -507,6 +507,12 @@ _PLATFORMS = [
         "emoji": "📲",
         "token_var": "WHATSAPP_ENABLED",
     },
+    {
+        "key": "signal",
+        "label": "Signal",
+        "emoji": "📡",
+        "token_var": "SIGNAL_HTTP_URL",
+    },
 ]
 
 
@@ -525,6 +531,13 @@ def _platform_status(platform: dict) -> str:
                 return "configured + paired"
             return "enabled, not paired"
         return "not configured"
+    if platform.get("key") == "signal":
+        account = get_env_value("SIGNAL_ACCOUNT")
+        if val and account:
+            return "configured"
+        if val or account:
+            return "partially configured"
+        return "not configured"
     if val:
         return "configured"
     return "not configured"
@@ -650,6 +663,121 @@ def _is_service_running() -> bool:
     return len(find_gateway_pids()) > 0
 
 
+def _setup_signal():
+    """Interactive setup for Signal messenger."""
+    import shutil
+
+    print()
+    print(color("  ─── 📡 Signal Setup ───", Colors.CYAN))
+
+    existing_url = get_env_value("SIGNAL_HTTP_URL")
+    existing_account = get_env_value("SIGNAL_ACCOUNT")
+    if existing_url and existing_account:
+        print()
+        print_success("Signal is already configured.")
+        if not prompt_yes_no("  Reconfigure Signal?", False):
+            return
+
+    # Check if signal-cli is available
+    print()
+    if shutil.which("signal-cli"):
+        print_success("signal-cli found on PATH.")
+    else:
+        print_warning("signal-cli not found on PATH.")
+        print_info("  Signal requires signal-cli running as an HTTP daemon.")
+        print_info("  Install options:")
+        print_info("    Linux:  sudo apt install signal-cli")
+        print_info("            or download from https://github.com/AsamK/signal-cli")
+        print_info("    macOS:  brew install signal-cli")
+        print_info("    Docker: bbernhard/signal-cli-rest-api")
+        print()
+        print_info("  After installing, link your account and start the daemon:")
+        print_info("    signal-cli link -n \"HermesAgent\"")
+        print_info("    signal-cli --account +YOURNUMBER daemon --http 127.0.0.1:8080")
+        print()
+
+    # HTTP URL
+    print()
+    print_info("  Enter the URL where signal-cli HTTP daemon is running.")
+    default_url = existing_url or "http://127.0.0.1:8080"
+    try:
+        url = input(f"  HTTP URL [{default_url}]: ").strip() or default_url
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Setup cancelled.")
+        return
+
+    # Test connectivity
+    print_info("  Testing connection...")
+    try:
+        import httpx
+        resp = httpx.get(f"{url.rstrip('/')}/api/v1/check", timeout=10.0)
+        if resp.status_code == 200:
+            print_success("  signal-cli daemon is reachable!")
+        else:
+            print_warning(f"  signal-cli responded with status {resp.status_code}.")
+            if not prompt_yes_no("  Continue anyway?", False):
+                return
+    except Exception as e:
+        print_warning(f"  Could not reach signal-cli at {url}: {e}")
+        if not prompt_yes_no("  Save this URL anyway? (you can start signal-cli later)", True):
+            return
+
+    save_env_value("SIGNAL_HTTP_URL", url)
+
+    # Account phone number
+    print()
+    print_info("  Enter your Signal account phone number in E.164 format.")
+    print_info("  Example: +15551234567")
+    default_account = existing_account or ""
+    try:
+        account = input(f"  Account number{f' [{default_account}]' if default_account else ''}: ").strip()
+        if not account:
+            account = default_account
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Setup cancelled.")
+        return
+
+    if not account:
+        print_error("  Account number is required.")
+        return
+
+    save_env_value("SIGNAL_ACCOUNT", account)
+
+    # Allowed users
+    print()
+    print_info("  The gateway DENIES all users by default for security.")
+    print_info("  Enter phone numbers or UUIDs of allowed users (comma-separated).")
+    existing_allowed = get_env_value("SIGNAL_ALLOWED_USERS") or ""
+    default_allowed = existing_allowed or account
+    try:
+        allowed = input(f"  Allowed users [{default_allowed}]: ").strip() or default_allowed
+    except (EOFError, KeyboardInterrupt):
+        print("\n  Setup cancelled.")
+        return
+
+    save_env_value("SIGNAL_ALLOWED_USERS", allowed)
+
+    # Group messaging
+    print()
+    if prompt_yes_no("  Enable group messaging? (disabled by default for security)", False):
+        print()
+        print_info("  Enter group IDs to allow, or * for all groups.")
+        existing_groups = get_env_value("SIGNAL_GROUP_ALLOWED_USERS") or ""
+        try:
+            groups = input(f"  Group IDs [{existing_groups or '*'}]: ").strip() or existing_groups or "*"
+        except (EOFError, KeyboardInterrupt):
+            print("\n  Setup cancelled.")
+            return
+        save_env_value("SIGNAL_GROUP_ALLOWED_USERS", groups)
+
+    print()
+    print_success("Signal configured!")
+    print_info(f"  URL: {url}")
+    print_info(f"  Account: {account}")
+    print_info(f"  DM auth: via SIGNAL_ALLOWED_USERS + DM pairing")
+    print_info(f"  Groups: {'enabled' if get_env_value('SIGNAL_GROUP_ALLOWED_USERS') else 'disabled'}")
+
+
 def gateway_setup():
     """Interactive setup for messaging platforms + gateway service."""
 
@@ -702,6 +830,8 @@ def gateway_setup():
 
         if platform["key"] == "whatsapp":
             _setup_whatsapp()
+        elif platform["key"] == "signal":
+            _setup_signal()
         else:
             _setup_standard_platform(platform)
 

hermes_cli/setup.py

@@ -1264,7 +1264,7 @@ def setup_agent_settings(config: dict):
     # ── Max Iterations ──
     print_header("Agent Settings")
 
-    current_max = get_env_value('HERMES_MAX_ITERATIONS') or '60'
+    current_max = get_env_value('HERMES_MAX_ITERATIONS') or '90'
     print_info("Maximum tool-calling iterations per conversation.")
     print_info("Higher = more complex tasks, but costs more tokens.")
     print_info("Recommended: 30-60 for most tasks, 100+ for open exploration.")
@@ -1660,14 +1660,18 @@ def setup_gateway(config: dict):
 # Section 5: Tool Configuration (delegates to unified tools_config.py)
 # =============================================================================
 
-def setup_tools(config: dict):
+def setup_tools(config: dict, first_install: bool = False):
     """Configure tools — delegates to the unified tools_command() in tools_config.py.
     
     Both `hermes setup tools` and `hermes tools` use the same flow:
     platform selection → toolset toggles → provider/API key configuration.
+    
+    Args:
+        first_install: When True, uses the simplified first-install flow
+            (no platform menu, prompts for all unconfigured API keys).
     """
     from hermes_cli.tools_config import tools_command
-    tools_command()
+    tools_command(first_install=first_install, config=config)
 
 
 # =============================================================================
@@ -1820,7 +1824,7 @@ def run_setup_wizard(args):
     setup_gateway(config)
 
     # Section 5: Tools
-    setup_tools(config)
+    setup_tools(config, first_install=not is_existing)
 
     # Save and show summary
     save_config(config)

hermes_cli/status.py

@@ -206,6 +206,8 @@ def show_status(args):
         "Telegram": ("TELEGRAM_BOT_TOKEN", "TELEGRAM_HOME_CHANNEL"),
         "Discord": ("DISCORD_BOT_TOKEN", "DISCORD_HOME_CHANNEL"),
         "WhatsApp": ("WHATSAPP_ENABLED", None),
+        "Signal": ("SIGNAL_HTTP_URL", "SIGNAL_HOME_CHANNEL"),
+        "Slack": ("SLACK_BOT_TOKEN", None),
     }
     
     for name, (token_var, home_var) in platforms.items():

hermes_cli/tools_config.py

@@ -96,6 +96,11 @@ CONFIGURABLE_TOOLSETS = [
     ("homeassistant",    "🏠 Home Assistant",           "smart home device control"),
 ]
 
+# Toolsets that are OFF by default for new installs.
+# They're still in _HERMES_CORE_TOOLS (available at runtime if enabled),
+# but the setup checklist won't pre-select them for first-time users.
+_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl"}
+
 # Platform display config
 PLATFORMS = {
     "cli":      {"label": "🖥️  CLI",       "default_toolset": "hermes-cli"},
@@ -142,6 +147,8 @@ TOOL_CATEGORIES = {
     },
     "web": {
         "name": "Web Search & Extract",
+        "setup_title": "Select Search Provider",
+        "setup_note": "A free DuckDuckGo search skill is also included — skip this if you don't need Firecrawl.",
         "icon": "🔍",
         "providers": [
             {
@@ -595,11 +602,18 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
         print(color(f"  --- {icon} {name} ({provider['name']}) ---", Colors.CYAN))
         if provider.get("tag"):
             _print_info(f"  {provider['tag']}")
+        # For single-provider tools, show a note if available
+        if cat.get("setup_note"):
+            _print_info(f"  {cat['setup_note']}")
         _configure_provider(provider, config)
     else:
         # Multiple providers - let user choose
         print()
-        print(color(f"  --- {icon} {name} - Choose a provider ---", Colors.CYAN))
+        # Use custom title if provided (e.g. "Select Search Provider")
+        title = cat.get("setup_title", f"Choose a provider")
+        print(color(f"  --- {icon} {name} - {title} ---", Colors.CYAN))
+        if cat.get("setup_note"):
+            _print_info(f"  {cat['setup_note']}")
         print()
 
         # Plain text labels only (no ANSI codes in menu items)
@@ -617,6 +631,9 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
                     configured = " [configured]"
             provider_choices.append(f"{p['name']}{tag}{configured}")
 
+        # Add skip option
+        provider_choices.append("Skip — keep defaults / configure later")
+
         # Detect current provider as default
         default_idx = 0
         for i, p in enumerate(providers):
@@ -628,7 +645,13 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
                 default_idx = i
                 break
 
-        provider_idx = _prompt_choice("  Select provider:", provider_choices, default_idx)
+        provider_idx = _prompt_choice(f"  {title}:", provider_choices, default_idx)
+
+        # Skip selected
+        if provider_idx >= len(providers):
+            _print_info(f"  Skipped {name}")
+            return
+
         _configure_provider(providers[provider_idx], config)
 
 
@@ -835,9 +858,19 @@ def _reconfigure_simple_requirements(ts_key: str):
 
 # ─── Main Entry Point ─────────────────────────────────────────────────────────
 
-def tools_command(args=None):
-    """Entry point for `hermes tools` and `hermes setup tools`."""
-    config = load_config()
+def tools_command(args=None, first_install: bool = False, config: dict = None):
+    """Entry point for `hermes tools` and `hermes setup tools`.
+
+    Args:
+        first_install: When True (set by the setup wizard on fresh installs),
+            skip the platform menu, go straight to the CLI checklist, and
+            prompt for API keys on all enabled tools that need them.
+        config: Optional config dict to use.  When called from the setup
+            wizard, the wizard passes its own dict so that platform_toolsets
+            are written into it and survive the wizard's final save_config().
+    """
+    if config is None:
+        config = load_config()
     enabled_platforms = _get_enabled_platforms()
 
     print()
@@ -846,6 +879,57 @@ def tools_command(args=None):
     print(color("  Tools that need API keys will be configured when enabled.", Colors.DIM))
     print()
 
+    # ── First-time install: linear flow, no platform menu ──
+    if first_install:
+        for pkey in enabled_platforms:
+            pinfo = PLATFORMS[pkey]
+            current_enabled = _get_platform_tools(config, pkey)
+
+            # Uncheck toolsets that should be off by default
+            checklist_preselected = current_enabled - _DEFAULT_OFF_TOOLSETS
+
+            # Show checklist
+            new_enabled = _prompt_toolset_checklist(pinfo["label"], checklist_preselected)
+
+            added = new_enabled - current_enabled
+            removed = current_enabled - new_enabled
+            if added:
+                for ts in sorted(added):
+                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
+                    print(color(f"  + {label}", Colors.GREEN))
+            if removed:
+                for ts in sorted(removed):
+                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
+                    print(color(f"  - {label}", Colors.RED))
+
+            # Walk through ALL selected tools that have provider options or
+            # need API keys.  This ensures browser (Local vs Browserbase),
+            # TTS (Edge vs OpenAI vs ElevenLabs), etc. are shown even when
+            # a free provider exists.
+            to_configure = [
+                ts_key for ts_key in sorted(new_enabled)
+                if TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)
+            ]
+
+            if to_configure:
+                print()
+                print(color(f"  Configuring {len(to_configure)} tool(s):", Colors.YELLOW))
+                for ts_key in to_configure:
+                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts_key), ts_key)
+                    print(color(f"    • {label}", Colors.DIM))
+                print(color("  You can skip any tool you don't need right now.", Colors.DIM))
+                print()
+                for ts_key in to_configure:
+                    _configure_toolset(ts_key, config)
+
+            _save_platform_tools(config, pkey, new_enabled)
+            save_config(config)
+            print(color(f"  ✓ Saved {pinfo['label']} tool configuration", Colors.GREEN))
+            print()
+
+        return
+
+    # ── Returning user: platform menu loop ──
     # Build platform choices
     platform_choices = []
     platform_keys = []
@@ -896,11 +980,10 @@ def tools_command(args=None):
                     print(color(f"  - {label}", Colors.RED))
 
             # Configure newly enabled toolsets that need API keys
-            if added:
-                for ts_key in sorted(added):
-                    if TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key):
-                        if not _toolset_has_keys(ts_key):
-                            _configure_toolset(ts_key, config)
+            for ts_key in sorted(added):
+                if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)):
+                    if not _toolset_has_keys(ts_key):
+                        _configure_toolset(ts_key, config)
 
             _save_platform_tools(config, pkey, new_enabled)
             save_config(config)

optional-skills/email/agentmail/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: agentmail
+description: Give the agent its own dedicated email inbox via AgentMail. Send, receive, and manage email autonomously using agent-owned email addresses (e.g. hermes-agent@agentmail.to).
+version: 1.0.0
+metadata:
+  hermes:
+    tags: [email, communication, agentmail, mcp]
+    category: email
+---
+
+# AgentMail — Agent-Owned Email Inboxes
+
+## Requirements
+
+- **AgentMail API key** (required) — sign up at https://console.agentmail.to (free tier: 3 inboxes, 3,000 emails/month; paid plans from $20/mo)
+- Node.js 18+ (for the MCP server)
+
+## When to Use
+Use this skill when you need to:
+- Give the agent its own dedicated email address
+- Send emails autonomously on behalf of the agent
+- Receive and read incoming emails
+- Manage email threads and conversations
+- Sign up for services or authenticate via email
+- Communicate with other agents or humans via email
+
+This is NOT for reading the user's personal email (use himalaya or Gmail for that).
+AgentMail gives the agent its own identity and inbox.
+
+## Setup
+
+### 1. Get an API Key
+- Go to https://console.agentmail.to
+- Create an account and generate an API key (starts with `am_`)
+
+### 2. Configure MCP Server
+Add to `~/.hermes/config.yaml` (paste your actual key — MCP env vars are not expanded from .env):
+```yaml
+mcp_servers:
+  agentmail:
+    command: "npx"
+    args: ["-y", "agentmail-mcp"]
+    env:
+      AGENTMAIL_API_KEY: "am_your_key_here"
+```
+
+### 3. Restart Hermes
+```bash
+hermes
+```
+All 11 AgentMail tools are now available automatically.
+
+## Available Tools (via MCP)
+
+| Tool | Description |
+|------|-------------|
+| `list_inboxes` | List all agent inboxes |
+| `get_inbox` | Get details of a specific inbox |
+| `create_inbox` | Create a new inbox (gets a real email address) |
+| `delete_inbox` | Delete an inbox |
+| `list_threads` | List email threads in an inbox |
+| `get_thread` | Get a specific email thread |
+| `send_message` | Send a new email |
+| `reply_to_message` | Reply to an existing email |
+| `forward_message` | Forward an email |
+| `update_message` | Update message labels/status |
+| `get_attachment` | Download an email attachment |
+
+## Procedure
+
+### Create an inbox and send an email
+1. Create a dedicated inbox:
+   - Use `create_inbox` with a username (e.g. `hermes-agent`)
+   - The agent gets address: `hermes-agent@agentmail.to`
+2. Send an email:
+   - Use `send_message` with `inbox_id`, `to`, `subject`, `text`
+3. Check for replies:
+   - Use `list_threads` to see incoming conversations
+   - Use `get_thread` to read a specific thread
+
+### Check incoming email
+1. Use `list_inboxes` to find your inbox ID
+2. Use `list_threads` with the inbox ID to see conversations
+3. Use `get_thread` to read a thread and its messages
+
+### Reply to an email
+1. Get the thread with `get_thread`
+2. Use `reply_to_message` with the message ID and your reply text
+
+## Example Workflows
+
+**Sign up for a service:**
+```
+1. create_inbox (username: "signup-bot")
+2. Use the inbox address to register on the service
+3. list_threads to check for verification email
+4. get_thread to read the verification code
+```
+
+**Agent-to-human outreach:**
+```
+1. create_inbox (username: "hermes-outreach")
+2. send_message (to: user@example.com, subject: "Hello", text: "...")
+3. list_threads to check for replies
+```
+
+## Pitfalls
+- Free tier limited to 3 inboxes and 3,000 emails/month
+- Emails come from `@agentmail.to` domain on free tier (custom domains on paid plans)
+- Node.js (18+) is required for the MCP server (`npx -y agentmail-mcp`)
+- The `mcp` Python package must be installed: `pip install mcp`
+- Real-time inbound email (webhooks) requires a public server — use `list_threads` polling via cronjob instead for personal use
+
+## Verification
+After setup, test with:
+```
+hermes --toolsets mcp -q "Create an AgentMail inbox called test-agent and tell me its email address"
+```
+You should see the new inbox address returned.
+
+## References
+- AgentMail docs: https://docs.agentmail.to/
+- AgentMail console: https://console.agentmail.to
+- AgentMail MCP repo: https://github.com/agentmail-to/agentmail-mcp
+- Pricing: https://www.agentmail.to/pricing

run_agent.py

@@ -183,6 +183,7 @@ class AIAgent:
         session_db=None,
         honcho_session_key: str = None,
         iteration_budget: "IterationBudget" = None,
+        fallback_model: Dict[str, Any] = None,
     ):
         """
         Initialize the AI Agent.
@@ -406,6 +407,17 @@ class AIAgent:
         except Exception as e:
             raise RuntimeError(f"Failed to initialize OpenAI client: {e}")
         
+        # Provider fallback — a single backup model/provider tried when the
+        # primary is exhausted (rate-limit, overload, connection failure).
+        # Config shape: {"provider": "openrouter", "model": "anthropic/claude-sonnet-4"}
+        self._fallback_model = fallback_model if isinstance(fallback_model, dict) else None
+        self._fallback_activated = False
+        if self._fallback_model:
+            fb_p = self._fallback_model.get("provider", "")
+            fb_m = self._fallback_model.get("model", "")
+            if fb_p and fb_m and not self.quiet_mode:
+                print(f"🔄 Fallback model: {fb_m} ({fb_p})")
+
         # Get available tools with filtering
         self.tools = get_tool_definitions(
             enabled_toolsets=enabled_toolsets,
@@ -2146,6 +2158,141 @@ class AIAgent:
             raise result["error"]
         return result["response"]
 
+    # ── Provider fallback ──────────────────────────────────────────────────
+
+    # API-key providers: provider → (base_url, [env_var_names])
+    _FALLBACK_API_KEY_PROVIDERS = {
+        "openrouter": (OPENROUTER_BASE_URL, ["OPENROUTER_API_KEY"]),
+        "zai": ("https://api.z.ai/api/paas/v4", ["ZAI_API_KEY", "Z_AI_API_KEY"]),
+        "kimi-coding": ("https://api.moonshot.ai/v1", ["KIMI_API_KEY"]),
+        "minimax": ("https://api.minimax.io/v1", ["MINIMAX_API_KEY"]),
+        "minimax-cn": ("https://api.minimaxi.com/v1", ["MINIMAX_CN_API_KEY"]),
+    }
+
+    # OAuth providers: provider → (resolver_import_path, api_mode)
+    # Each resolver returns {"api_key": ..., "base_url": ...}.
+    _FALLBACK_OAUTH_PROVIDERS = {
+        "openai-codex": ("resolve_codex_runtime_credentials", "codex_responses"),
+        "nous": ("resolve_nous_runtime_credentials", "chat_completions"),
+    }
+
+    def _resolve_fallback_credentials(
+        self, fb_provider: str, fb_config: dict
+    ) -> Optional[tuple]:
+        """Resolve credentials for a fallback provider.
+
+        Returns (api_key, base_url, api_mode) on success, or None on failure.
+        Handles three cases:
+          1. OAuth providers (openai-codex, nous) — call credential resolver
+          2. API-key providers (openrouter, zai, etc.) — read env var
+          3. Custom endpoints — use base_url + api_key_env from config
+        """
+        # ── 1. OAuth providers ────────────────────────────────────────
+        if fb_provider in self._FALLBACK_OAUTH_PROVIDERS:
+            resolver_name, api_mode = self._FALLBACK_OAUTH_PROVIDERS[fb_provider]
+            try:
+                import hermes_cli.auth as _auth
+                resolver = getattr(_auth, resolver_name)
+                creds = resolver()
+                return creds["api_key"], creds["base_url"], api_mode
+            except Exception as e:
+                logging.warning(
+                    "Fallback to %s failed (credential resolution): %s",
+                    fb_provider, e,
+                )
+                return None
+
+        # ── 2. API-key providers ──────────────────────────────────────
+        fb_key = (fb_config.get("api_key") or "").strip()
+        if not fb_key:
+            key_env = (fb_config.get("api_key_env") or "").strip()
+            if key_env:
+                fb_key = os.getenv(key_env, "")
+            elif fb_provider in self._FALLBACK_API_KEY_PROVIDERS:
+                for env_var in self._FALLBACK_API_KEY_PROVIDERS[fb_provider][1]:
+                    fb_key = os.getenv(env_var, "")
+                    if fb_key:
+                        break
+        if not fb_key:
+            logging.warning(
+                "Fallback model configured but no API key found for provider '%s'",
+                fb_provider,
+            )
+            return None
+
+        # ── 3. Resolve base URL ───────────────────────────────────────
+        fb_base_url = (fb_config.get("base_url") or "").strip()
+        if not fb_base_url and fb_provider in self._FALLBACK_API_KEY_PROVIDERS:
+            fb_base_url = self._FALLBACK_API_KEY_PROVIDERS[fb_provider][0]
+        if not fb_base_url:
+            fb_base_url = OPENROUTER_BASE_URL
+
+        return fb_key, fb_base_url, "chat_completions"
+
+    def _try_activate_fallback(self) -> bool:
+        """Switch to the configured fallback model/provider.
+
+        Called when the primary model is failing after retries.  Swaps the
+        OpenAI client, model slug, and provider in-place so the retry loop
+        can continue with the new backend.  One-shot: returns False if
+        already activated or not configured.
+        """
+        if self._fallback_activated or not self._fallback_model:
+            return False
+
+        fb = self._fallback_model
+        fb_provider = (fb.get("provider") or "").strip().lower()
+        fb_model = (fb.get("model") or "").strip()
+        if not fb_provider or not fb_model:
+            return False
+
+        resolved = self._resolve_fallback_credentials(fb_provider, fb)
+        if resolved is None:
+            return False
+        fb_key, fb_base_url, fb_api_mode = resolved
+
+        # Build new client
+        try:
+            client_kwargs = {"api_key": fb_key, "base_url": fb_base_url}
+            if "openrouter" in fb_base_url.lower():
+                client_kwargs["default_headers"] = {
+                    "HTTP-Referer": "https://github.com/NousResearch/hermes-agent",
+                    "X-OpenRouter-Title": "Hermes Agent",
+                    "X-OpenRouter-Categories": "productivity,cli-agent",
+                }
+            elif "api.kimi.com" in fb_base_url.lower():
+                client_kwargs["default_headers"] = {"User-Agent": "KimiCLI/1.0"}
+
+            self.client = OpenAI(**client_kwargs)
+            self._client_kwargs = client_kwargs
+            old_model = self.model
+            self.model = fb_model
+            self.provider = fb_provider
+            self.base_url = fb_base_url
+            self.api_mode = fb_api_mode
+            self._fallback_activated = True
+
+            # Re-evaluate prompt caching for the new provider/model
+            self._use_prompt_caching = (
+                "openrouter" in fb_base_url.lower()
+                and "claude" in fb_model.lower()
+            )
+
+            print(
+                f"{self.log_prefix}🔄 Primary model failed — switching to fallback: "
+                f"{fb_model} via {fb_provider}"
+            )
+            logging.info(
+                "Fallback activated: %s → %s (%s)",
+                old_model, fb_model, fb_provider,
+            )
+            return True
+        except Exception as e:
+            logging.error("Failed to activate fallback model: %s", e)
+            return False
+
+    # ── End provider fallback ──────────────────────────────────────────────
+
     def _build_api_kwargs(self, api_messages: list) -> dict:
         """Build the keyword arguments dict for the active API mode."""
         if self.api_mode == "codex_responses":
@@ -2945,9 +3092,14 @@ class AIAgent:
             )
             self._iters_since_skill = 0
 
-        # Honcho prefetch: retrieve user context for system prompt injection
+        # Honcho prefetch: retrieve user context for system prompt injection.
+        # Only on the FIRST turn of a session (empty history).  On subsequent
+        # turns the model already has all prior context in its conversation
+        # history, and the Honcho context is baked into the stored system
+        # prompt — re-fetching it would change the system message and break
+        # Anthropic prompt caching.
         self._honcho_context = ""
-        if self._honcho and self._honcho_session_key:
+        if self._honcho and self._honcho_session_key and not conversation_history:
             try:
                 self._honcho_context = self._honcho_prefetch(user_message)
             except Exception as e:
@@ -2965,14 +3117,42 @@ class AIAgent:
         # Built once on first call, reused for all subsequent calls.
         # Only rebuilt after context compression events (which invalidate
         # the cache and reload memory from disk).
+        #
+        # For continuing sessions (gateway creates a fresh AIAgent per
+        # message), we load the stored system prompt from the session DB
+        # instead of rebuilding.  Rebuilding would pick up memory changes
+        # from disk that the model already knows about (it wrote them!),
+        # producing a different system prompt and breaking the Anthropic
+        # prefix cache.
         if self._cached_system_prompt is None:
-            self._cached_system_prompt = self._build_system_prompt(system_message)
-            # Store the system prompt snapshot in SQLite
-            if self._session_db:
+            stored_prompt = None
+            if conversation_history and self._session_db:
                 try:
-                    self._session_db.update_system_prompt(self.session_id, self._cached_system_prompt)
-                except Exception as e:
-                    logger.debug("Session DB update_system_prompt failed: %s", e)
+                    session_row = self._session_db.get_session(self.session_id)
+                    if session_row:
+                        stored_prompt = session_row.get("system_prompt") or None
+                except Exception:
+                    pass  # Fall through to build fresh
+
+            if stored_prompt:
+                # Continuing session — reuse the exact system prompt from
+                # the previous turn so the Anthropic cache prefix matches.
+                self._cached_system_prompt = stored_prompt
+            else:
+                # First turn of a new session — build from scratch.
+                self._cached_system_prompt = self._build_system_prompt(system_message)
+                # Bake Honcho context into the prompt so it's stable for
+                # the entire session (not re-fetched per turn).
+                if self._honcho_context:
+                    self._cached_system_prompt = (
+                        self._cached_system_prompt + "\n\n" + self._honcho_context
+                    ).strip()
+                # Store the system prompt snapshot in SQLite
+                if self._session_db:
+                    try:
+                        self._session_db.update_system_prompt(self.session_id, self._cached_system_prompt)
+                    except Exception as e:
+                        logger.debug("Session DB update_system_prompt failed: %s", e)
 
         active_system_prompt = self._cached_system_prompt
 
@@ -3097,11 +3277,13 @@ class AIAgent:
             # Build the final system message: cached prompt + ephemeral system prompt.
             # The ephemeral part is appended here (not baked into the cached prompt)
             # so it stays out of the session DB and logs.
+            # Note: Honcho context is baked into _cached_system_prompt on the first
+            # turn and stored in the session DB, so it does NOT need to be injected
+            # here.  This keeps the system message identical across all turns in a
+            # session, maximizing Anthropic prompt cache hits.
             effective_system = active_system_prompt or ""
             if self.ephemeral_system_prompt:
                 effective_system = (effective_system + "\n\n" + self.ephemeral_system_prompt).strip()
-            if self._honcho_context:
-                effective_system = (effective_system + "\n\n" + self._honcho_context).strip()
             if effective_system:
                 api_messages = [{"role": "system", "content": effective_system}] + api_messages
             
@@ -3252,6 +3434,10 @@ class AIAgent:
                         print(f"{self.log_prefix}   ⏱️  Response time: {api_duration:.2f}s (fast response often indicates rate limiting)")
                         
                         if retry_count >= max_retries:
+                            # Try fallback before giving up
+                            if self._try_activate_fallback():
+                                retry_count = 0
+                                continue
                             print(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded for invalid responses. Giving up.")
                             logging.error(f"{self.log_prefix}Invalid API response after {max_retries} retries.")
                             self._persist_session(messages, conversation_history)
@@ -3576,6 +3762,11 @@ class AIAgent:
                     ])) and not is_context_length_error
 
                     if is_client_error:
+                        # Try fallback before aborting — a different provider
+                        # may not have the same issue (rate limit, auth, etc.)
+                        if self._try_activate_fallback():
+                            retry_count = 0
+                            continue
                         self._dump_api_request_debug(
                             api_kwargs, reason="non_retryable_client_error", error=api_error,
                         )
@@ -3593,6 +3784,10 @@ class AIAgent:
                         }
 
                     if retry_count >= max_retries:
+                        # Try fallback before giving up entirely
+                        if self._try_activate_fallback():
+                            retry_count = 0
+                            continue
                         print(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded. Giving up.")
                         logging.error(f"{self.log_prefix}API call failed after {max_retries} retries. Last error: {api_error}")
                         logging.error(f"{self.log_prefix}Request details - Messages: {len(api_messages)}, Approx tokens: {approx_tokens:,}")

scripts/install.sh

@@ -492,9 +492,23 @@ install_system_packages() {
                         return 0
                     fi
                 fi
+            elif [ -e /dev/tty ]; then
+                # Non-interactive (e.g. curl | bash) but a terminal is available.
+                # Read the prompt from /dev/tty (same approach the setup wizard uses).
+                echo ""
+                log_info "Installing ${description} requires sudo."
+                read -p "Install? [Y/n] " -n 1 -r < /dev/tty
+                echo
+                if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
+                    if sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a $install_cmd < /dev/tty; then
+                        [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
+                        [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
+                        return 0
+                    fi
+                fi
             else
-                log_warn "Non-interactive mode: cannot prompt for sudo password"
-                log_info "Install missing packages manually: sudo $install_cmd"
+                log_warn "Non-interactive mode and no terminal available — cannot install system packages"
+                log_info "Install manually after setup completes: sudo $install_cmd"
             fi
         fi
     fi

skills/dogfood/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: dogfood
+description: Systematic exploratory QA testing of web applications — find bugs, capture evidence, and generate structured reports
+version: 1.0.0
+metadata:
+  hermes:
+    tags: [qa, testing, browser, web, dogfood]
+    related_skills: []
+---
+
+# Dogfood: Systematic Web Application QA Testing
+
+## Overview
+
+This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.
+
+## Prerequisites
+
+- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`, `browser_close`)
+- A target URL and testing scope from the user
+
+## Inputs
+
+The user provides:
+1. **Target URL** — the entry point for testing
+2. **Scope** — what areas/features to focus on (or "full site" for comprehensive testing)
+3. **Output directory** (optional) — where to save screenshots and the report (default: `./dogfood-output`)
+
+## Workflow
+
+Follow this 5-phase systematic workflow:
+
+### Phase 1: Plan
+
+1. Create the output directory structure:
+   ```
+   {output_dir}/
+   ├── screenshots/       # Evidence screenshots
+   └── report.md          # Final report (generated in Phase 5)
+   ```
+2. Identify the testing scope based on user input.
+3. Build a rough sitemap by planning which pages and features to test:
+   - Landing/home page
+   - Navigation links (header, footer, sidebar)
+   - Key user flows (sign up, login, search, checkout, etc.)
+   - Forms and interactive elements
+   - Edge cases (empty states, error pages, 404s)
+
+### Phase 2: Explore
+
+For each page or feature in your plan:
+
+1. **Navigate** to the page:
+   ```
+   browser_navigate(url="https://example.com/page")
+   ```
+
+2. **Take a snapshot** to understand the DOM structure:
+   ```
+   browser_snapshot()
+   ```
+
+3. **Check the console** for JavaScript errors:
+   ```
+   browser_console(clear=true)
+   ```
+   Do this after every navigation and after every significant interaction. Silent JS errors are high-value findings.
+
+4. **Take an annotated screenshot** to visually assess the page and identify interactive elements:
+   ```
+   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
+   ```
+   The `annotate=true` flag overlays numbered `[N]` labels on interactive elements. Each `[N]` maps to ref `@eN` for subsequent browser commands.
+
+5. **Test interactive elements** systematically:
+   - Click buttons and links: `browser_click(ref="@eN")`
+   - Fill forms: `browser_type(ref="@eN", text="test input")`
+   - Test keyboard navigation: `browser_press(key="Tab")`, `browser_press(key="Enter")`
+   - Scroll through content: `browser_scroll(direction="down")`
+   - Test form validation with invalid inputs
+   - Test empty submissions
+
+6. **After each interaction**, check for:
+   - Console errors: `browser_console()`
+   - Visual changes: `browser_vision(question="What changed after the interaction?")`
+   - Expected vs actual behavior
+
+### Phase 3: Collect Evidence
+
+For every issue found:
+
+1. **Take a screenshot** showing the issue:
+   ```
+   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
+   ```
+   Save the `screenshot_path` from the response — you will reference it in the report.
+
+2. **Record the details**:
+   - URL where the issue occurs
+   - Steps to reproduce
+   - Expected behavior
+   - Actual behavior
+   - Console errors (if any)
+   - Screenshot path
+
+3. **Classify the issue** using the issue taxonomy (see `references/issue-taxonomy.md`):
+   - Severity: Critical / High / Medium / Low
+   - Category: Functional / Visual / Accessibility / Console / UX / Content
+
+### Phase 4: Categorize
+
+1. Review all collected issues.
+2. De-duplicate — merge issues that are the same bug manifesting in different places.
+3. Assign final severity and category to each issue.
+4. Sort by severity (Critical first, then High, Medium, Low).
+5. Count issues by severity and category for the executive summary.
+
+### Phase 5: Report
+
+Generate the final report using the template at `templates/dogfood-report-template.md`.
+
+The report must include:
+1. **Executive summary** with total issue count, breakdown by severity, and testing scope
+2. **Per-issue sections** with:
+   - Issue number and title
+   - Severity and category badges
+   - URL where observed
+   - Description of the issue
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Screenshot references (use `MEDIA:<screenshot_path>` for inline images)
+   - Console errors if relevant
+3. **Summary table** of all issues
+4. **Testing notes** — what was tested, what was not, any blockers
+
+Save the report to `{output_dir}/report.md`.
+
+## Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `browser_navigate` | Go to a URL |
+| `browser_snapshot` | Get DOM text snapshot (accessibility tree) |
+| `browser_click` | Click an element by ref (`@eN`) or text |
+| `browser_type` | Type into an input field |
+| `browser_scroll` | Scroll up/down on the page |
+| `browser_back` | Go back in browser history |
+| `browser_press` | Press a keyboard key |
+| `browser_vision` | Screenshot + AI analysis; use `annotate=true` for element labels |
+| `browser_console` | Get JS console output and errors |
+| `browser_close` | Close the browser session |
+
+## Tips
+
+- **Always check `browser_console()` after navigating and after significant interactions.** Silent JS errors are among the most valuable findings.
+- **Use `annotate=true` with `browser_vision`** when you need to reason about interactive element positions or when the snapshot refs are unclear.
+- **Test with both valid and invalid inputs** — form validation bugs are common.
+- **Scroll through long pages** — content below the fold may have rendering issues.
+- **Test navigation flows** — click through multi-step processes end-to-end.
+- **Check responsive behavior** by noting any layout issues visible in screenshots.
+- **Don't forget edge cases**: empty states, very long text, special characters, rapid clicking.
+- When reporting screenshots to the user, include `MEDIA:<screenshot_path>` so they can see the evidence inline.

skills/dogfood/references/issue-taxonomy.md

@@ -0,0 +1,109 @@
+# Issue Taxonomy
+
+Use this taxonomy to classify issues found during dogfood QA testing.
+
+## Severity Levels
+
+### Critical
+The issue makes a core feature completely unusable or causes data loss.
+
+**Examples:**
+- Application crashes or shows a blank white page
+- Form submission silently loses user data
+- Authentication is completely broken (can't log in at all)
+- Payment flow fails and charges the user without completing the order
+- Security vulnerability (e.g., XSS, exposed credentials in console)
+
+### High
+The issue significantly impairs functionality but a workaround may exist.
+
+**Examples:**
+- A key button does nothing when clicked (but refreshing fixes it)
+- Search returns no results for valid queries
+- Form validation rejects valid input
+- Page loads but critical content is missing or garbled
+- Navigation link leads to a 404 or wrong page
+- Uncaught JavaScript exceptions in the console on core pages
+
+### Medium
+The issue is noticeable and affects user experience but doesn't block core functionality.
+
+**Examples:**
+- Layout is misaligned or overlapping on certain screen sections
+- Images fail to load (broken image icons)
+- Slow performance (visible loading delays > 3 seconds)
+- Form field lacks proper validation feedback (no error message on bad input)
+- Console warnings that suggest deprecated or misconfigured features
+- Inconsistent styling between similar pages
+
+### Low
+Minor polish issues that don't affect functionality.
+
+**Examples:**
+- Typos or grammatical errors in text content
+- Minor spacing or alignment inconsistencies
+- Placeholder text left in production ("Lorem ipsum")
+- Favicon missing
+- Console info/debug messages that shouldn't be in production
+- Subtle color contrast issues that don't fail WCAG requirements
+
+## Categories
+
+### Functional
+Issues where features don't work as expected.
+
+- Buttons/links that don't respond
+- Forms that don't submit or submit incorrectly
+- Broken user flows (can't complete a multi-step process)
+- Incorrect data displayed
+- Features that work partially
+
+### Visual
+Issues with the visual presentation of the page.
+
+- Layout problems (overlapping elements, broken grids)
+- Broken images or missing media
+- Styling inconsistencies
+- Responsive design failures
+- Z-index issues (elements hidden behind others)
+- Text overflow or truncation
+
+### Accessibility
+Issues that prevent or hinder access for users with disabilities.
+
+- Missing alt text on meaningful images
+- Poor color contrast (fails WCAG AA)
+- Elements not reachable via keyboard navigation
+- Missing form labels or ARIA attributes
+- Focus indicators missing or unclear
+- Screen reader incompatible content
+
+### Console
+Issues detected through JavaScript console output.
+
+- Uncaught exceptions and unhandled promise rejections
+- Failed network requests (4xx, 5xx errors in console)
+- Deprecation warnings
+- CORS errors
+- Mixed content warnings (HTTP resources on HTTPS page)
+- Excessive console.log output left from development
+
+### UX (User Experience)
+Issues where functionality works but the experience is poor.
+
+- Confusing navigation or information architecture
+- Missing loading indicators (user doesn't know something is happening)
+- No feedback after user actions (e.g., button click with no visible result)
+- Inconsistent interaction patterns
+- Missing confirmation dialogs for destructive actions
+- Poor error messages that don't help the user recover
+
+### Content
+Issues with the text, media, or information on the page.
+
+- Typos and grammatical errors
+- Placeholder/dummy content in production
+- Outdated information
+- Missing content (empty sections)
+- Broken or dead links to external resources
+- Incorrect or misleading labels

skills/dogfood/templates/dogfood-report-template.md

@@ -0,0 +1,86 @@
+# Dogfood QA Report
+
+**Target:** {target_url}
+**Date:** {date}
+**Scope:** {scope_description}
+**Tester:** Hermes Agent (automated exploratory QA)
+
+---
+
+## Executive Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 Critical | {critical_count} |
+| 🟠 High | {high_count} |
+| 🟡 Medium | {medium_count} |
+| 🔵 Low | {low_count} |
+| **Total** | **{total_count}** |
+
+**Overall Assessment:** {one_sentence_assessment}
+
+---
+
+## Issues
+
+<!-- Repeat this section for each issue found, sorted by severity (Critical first) -->
+
+### Issue #{issue_number}: {issue_title}
+
+| Field | Value |
+|-------|-------|
+| **Severity** | {severity} |
+| **Category** | {category} |
+| **URL** | {url_where_found} |
+
+**Description:**
+{detailed_description_of_the_issue}
+
+**Steps to Reproduce:**
+1. {step_1}
+2. {step_2}
+3. {step_3}
+
+**Expected Behavior:**
+{what_should_happen}
+
+**Actual Behavior:**
+{what_actually_happens}
+
+**Screenshot:**
+MEDIA:{screenshot_path}
+
+**Console Errors** (if applicable):
+```
+{console_error_output}
+```
+
+---
+
+<!-- End of per-issue section -->
+
+## Issues Summary Table
+
+| # | Title | Severity | Category | URL |
+|---|-------|----------|----------|-----|
+| {n} | {title} | {severity} | {category} | {url} |
+
+## Testing Coverage
+
+### Pages Tested
+- {list_of_pages_visited}
+
+### Features Tested
+- {list_of_features_exercised}
+
+### Not Tested / Out of Scope
+- {areas_not_covered_and_why}
+
+### Blockers
+- {any_issues_that_prevented_testing_certain_areas}
+
+---
+
+## Notes
+
+{any_additional_observations_or_recommendations}

tests/agent/test_context_compressor.py

@@ -224,6 +224,60 @@ class TestCompressWithClient:
                 for tc in msg["tool_calls"]:
                     assert tc["id"] in answered_ids
 
+    def test_summary_role_avoids_consecutive_user_messages(self):
+        """Summary role should alternate with the last head message to avoid consecutive same-role messages."""
+        mock_client = MagicMock()
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "[CONTEXT SUMMARY]: stuff happened"
+        mock_client.chat.completions.create.return_value = mock_response
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000), \
+             patch("agent.context_compressor.get_text_auxiliary_client", return_value=(mock_client, "test-model")):
+            c = ContextCompressor(model="test", quiet_mode=True, protect_first_n=2, protect_last_n=2)
+
+        # Last head message (index 1) is "assistant" → summary should be "user"
+        msgs = [
+            {"role": "user", "content": "msg 0"},
+            {"role": "assistant", "content": "msg 1"},
+            {"role": "user", "content": "msg 2"},
+            {"role": "assistant", "content": "msg 3"},
+            {"role": "user", "content": "msg 4"},
+            {"role": "assistant", "content": "msg 5"},
+        ]
+        result = c.compress(msgs)
+        summary_msg = [m for m in result if "CONTEXT SUMMARY" in (m.get("content") or "")]
+        assert len(summary_msg) == 1
+        assert summary_msg[0]["role"] == "user"
+
+    def test_summary_role_avoids_consecutive_user_when_head_ends_with_user(self):
+        """When last head message is 'user', summary must be 'assistant' to avoid two consecutive user messages."""
+        mock_client = MagicMock()
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "[CONTEXT SUMMARY]: stuff happened"
+        mock_client.chat.completions.create.return_value = mock_response
+
+        with patch("agent.context_compressor.get_model_context_length", return_value=100000), \
+             patch("agent.context_compressor.get_text_auxiliary_client", return_value=(mock_client, "test-model")):
+            c = ContextCompressor(model="test", quiet_mode=True, protect_first_n=3, protect_last_n=2)
+
+        # Last head message (index 2) is "user" → summary should be "assistant"
+        msgs = [
+            {"role": "system", "content": "system prompt"},
+            {"role": "user", "content": "msg 1"},
+            {"role": "user", "content": "msg 2"},  # last head — user
+            {"role": "assistant", "content": "msg 3"},
+            {"role": "user", "content": "msg 4"},
+            {"role": "assistant", "content": "msg 5"},
+            {"role": "user", "content": "msg 6"},
+            {"role": "assistant", "content": "msg 7"},
+        ]
+        result = c.compress(msgs)
+        summary_msg = [m for m in result if "CONTEXT SUMMARY" in (m.get("content") or "")]
+        assert len(summary_msg) == 1
+        assert summary_msg[0]["role"] == "assistant"
+
     def test_summarization_does_not_start_tail_with_tool_outputs(self):
         mock_client = MagicMock()
         mock_response = MagicMock()

tests/gateway/test_session_hygiene.py

@@ -2,6 +2,10 @@
 
 Verifies that the gateway detects pathologically large transcripts and
 triggers auto-compression before running the agent.  (#628)
+
+The hygiene system uses the SAME compression config as the agent:
+  compression.threshold × model context length
+so CLI and messaging platforms behave identically.
 """
 
 import pytest
@@ -38,75 +42,113 @@ def _make_large_history_tokens(target_tokens: int) -> list:
 
 
 # ---------------------------------------------------------------------------
-# Detection threshold tests
+# Detection threshold tests (model-aware, unified with compression config)
 # ---------------------------------------------------------------------------
 
 class TestSessionHygieneThresholds:
-    """Test that the threshold logic correctly identifies large sessions."""
+    """Test that the threshold logic correctly identifies large sessions.
+
+    Thresholds are derived from model context length × compression threshold,
+    matching what the agent's ContextCompressor uses.
+    """
 
     def test_small_session_below_thresholds(self):
         """A 10-message session should not trigger compression."""
         history = _make_history(10)
-        msg_count = len(history)
         approx_tokens = estimate_messages_tokens_rough(history)
 
-        compress_token_threshold = 100_000
-        compress_msg_threshold = 200
+        # For a 200k-context model at 85% threshold = 170k
+        context_length = 200_000
+        threshold_pct = 0.85
+        compress_token_threshold = int(context_length * threshold_pct)
 
-        needs_compress = (
-            approx_tokens >= compress_token_threshold
-            or msg_count >= compress_msg_threshold
-        )
+        needs_compress = approx_tokens >= compress_token_threshold
         assert not needs_compress
 
-    def test_large_message_count_triggers(self):
-        """200+ messages should trigger compression even if tokens are low."""
-        history = _make_history(250, content_size=10)
-        msg_count = len(history)
-
-        compress_msg_threshold = 200
-        needs_compress = msg_count >= compress_msg_threshold
-        assert needs_compress
-
     def test_large_token_count_triggers(self):
-        """High token count should trigger compression even if message count is low."""
-        # 50 messages with huge content to exceed 100K tokens
-        history = _make_history(50, content_size=10_000)
+        """High token count should trigger compression when exceeding model threshold."""
+        # Build a history that exceeds 85% of a 200k model (170k tokens)
+        history = _make_large_history_tokens(180_000)
         approx_tokens = estimate_messages_tokens_rough(history)
 
-        compress_token_threshold = 100_000
+        context_length = 200_000
+        threshold_pct = 0.85
+        compress_token_threshold = int(context_length * threshold_pct)
+
         needs_compress = approx_tokens >= compress_token_threshold
         assert needs_compress
 
-    def test_under_both_thresholds_no_trigger(self):
-        """Session under both thresholds should not trigger."""
-        history = _make_history(100, content_size=100)
-        msg_count = len(history)
+    def test_under_threshold_no_trigger(self):
+        """Session under threshold should not trigger, even with many messages."""
+        # 250 short messages — lots of messages but well under token threshold
+        history = _make_history(250, content_size=10)
         approx_tokens = estimate_messages_tokens_rough(history)
 
-        compress_token_threshold = 100_000
-        compress_msg_threshold = 200
+        # 200k model at 85% = 170k token threshold
+        context_length = 200_000
+        threshold_pct = 0.85
+        compress_token_threshold = int(context_length * threshold_pct)
 
-        needs_compress = (
-            approx_tokens >= compress_token_threshold
-            or msg_count >= compress_msg_threshold
+        needs_compress = approx_tokens >= compress_token_threshold
+        assert not needs_compress, (
+            f"250 short messages (~{approx_tokens} tokens) should NOT trigger "
+            f"compression at {compress_token_threshold} token threshold"
         )
+
+    def test_message_count_alone_does_not_trigger(self):
+        """Message count alone should NOT trigger — only token count matters.
+
+        The old system used an OR of token-count and message-count thresholds,
+        which caused premature compression in tool-heavy sessions with 200+
+        messages but low total tokens.
+        """
+        # 300 very short messages — old system would compress, new should not
+        history = _make_history(300, content_size=10)
+        approx_tokens = estimate_messages_tokens_rough(history)
+
+        context_length = 200_000
+        threshold_pct = 0.85
+        compress_token_threshold = int(context_length * threshold_pct)
+
+        # Token-based check only
+        needs_compress = approx_tokens >= compress_token_threshold
         assert not needs_compress
 
-    def test_custom_thresholds(self):
-        """Custom thresholds from config should be respected."""
-        history = _make_history(60, content_size=100)
-        msg_count = len(history)
+    def test_threshold_scales_with_model(self):
+        """Different models should have different compression thresholds."""
+        # 128k model at 85% = 108,800 tokens
+        small_model_threshold = int(128_000 * 0.85)
+        # 200k model at 85% = 170,000 tokens
+        large_model_threshold = int(200_000 * 0.85)
+        # 1M model at 85% = 850,000 tokens
+        huge_model_threshold = int(1_000_000 * 0.85)
 
-        # Custom lower threshold
-        compress_msg_threshold = 50
-        needs_compress = msg_count >= compress_msg_threshold
-        assert needs_compress
+        # A session at ~120k tokens:
+        history = _make_large_history_tokens(120_000)
+        approx_tokens = estimate_messages_tokens_rough(history)
 
-        # Custom higher threshold
-        compress_msg_threshold = 100
-        needs_compress = msg_count >= compress_msg_threshold
-        assert not needs_compress
+        # Should trigger for 128k model
+        assert approx_tokens >= small_model_threshold
+        # Should NOT trigger for 200k model
+        assert approx_tokens < large_model_threshold
+        # Should NOT trigger for 1M model
+        assert approx_tokens < huge_model_threshold
+
+    def test_custom_threshold_percentage(self):
+        """Custom threshold percentage from config should be respected."""
+        context_length = 200_000
+
+        # At 50% threshold = 100k
+        low_threshold = int(context_length * 0.50)
+        # At 90% threshold = 180k
+        high_threshold = int(context_length * 0.90)
+
+        history = _make_large_history_tokens(150_000)
+        approx_tokens = estimate_messages_tokens_rough(history)
+
+        # Should trigger at 50% but not at 90%
+        assert approx_tokens >= low_threshold
+        assert approx_tokens < high_threshold
 
     def test_minimum_message_guard(self):
         """Sessions with fewer than 4 messages should never trigger."""
@@ -117,18 +159,19 @@ class TestSessionHygieneThresholds:
 
 
 class TestSessionHygieneWarnThreshold:
-    """Test the post-compression warning threshold."""
+    """Test the post-compression warning threshold (95% of context)."""
 
     def test_warn_when_still_large(self):
-        """If compressed result is still above warn_tokens, should warn."""
-        # Simulate post-compression tokens
-        warn_threshold = 200_000
-        post_compress_tokens = 250_000
+        """If compressed result is still above 95% of context, should warn."""
+        context_length = 200_000
+        warn_threshold = int(context_length * 0.95)  # 190k
+        post_compress_tokens = 195_000
         assert post_compress_tokens >= warn_threshold
 
     def test_no_warn_when_under(self):
-        """If compressed result is under warn_tokens, no warning."""
-        warn_threshold = 200_000
+        """If compressed result is under 95% of context, no warning."""
+        context_length = 200_000
+        warn_threshold = int(context_length * 0.95)  # 190k
         post_compress_tokens = 150_000
         assert post_compress_tokens < warn_threshold
 
@@ -150,10 +193,12 @@ class TestTokenEstimation:
         assert estimate_messages_tokens_rough(many) > estimate_messages_tokens_rough(few)
 
     def test_pathological_session_detected(self):
-        """The reported pathological case: 648 messages, ~299K tokens."""
-        # Simulate a 648-message session averaging ~460 tokens per message
+        """The reported pathological case: 648 messages, ~299K tokens.
+
+        With a 200k model at 85% threshold (170k), this should trigger.
+        """
         history = _make_history(648, content_size=1800)
         tokens = estimate_messages_tokens_rough(history)
-        # Should be well above the 100K default threshold
-        assert tokens > 100_000
-        assert len(history) > 200
+        # Should be well above the 170K threshold for a 200k model
+        threshold = int(200_000 * 0.85)
+        assert tokens > threshold

tests/gateway/test_signal.py

@@ -0,0 +1,294 @@
+"""Tests for Signal messenger platform adapter."""
+import json
+import pytest
+from unittest.mock import MagicMock, patch, AsyncMock
+
+from gateway.config import Platform, PlatformConfig
+
+
+# ---------------------------------------------------------------------------
+# Platform & Config
+# ---------------------------------------------------------------------------
+
+class TestSignalPlatformEnum:
+    def test_signal_enum_exists(self):
+        assert Platform.SIGNAL.value == "signal"
+
+    def test_signal_in_platform_list(self):
+        platforms = [p.value for p in Platform]
+        assert "signal" in platforms
+
+
+class TestSignalConfigLoading:
+    def test_apply_env_overrides_signal(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_HTTP_URL", "http://localhost:9090")
+        monkeypatch.setenv("SIGNAL_ACCOUNT", "+15551234567")
+
+        from gateway.config import GatewayConfig, _apply_env_overrides
+        config = GatewayConfig()
+        _apply_env_overrides(config)
+
+        assert Platform.SIGNAL in config.platforms
+        sc = config.platforms[Platform.SIGNAL]
+        assert sc.enabled is True
+        assert sc.extra["http_url"] == "http://localhost:9090"
+        assert sc.extra["account"] == "+15551234567"
+
+    def test_signal_not_loaded_without_both_vars(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_HTTP_URL", "http://localhost:9090")
+        # No SIGNAL_ACCOUNT
+
+        from gateway.config import GatewayConfig, _apply_env_overrides
+        config = GatewayConfig()
+        _apply_env_overrides(config)
+
+        assert Platform.SIGNAL not in config.platforms
+
+    def test_connected_platforms_includes_signal(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_HTTP_URL", "http://localhost:8080")
+        monkeypatch.setenv("SIGNAL_ACCOUNT", "+15551234567")
+
+        from gateway.config import GatewayConfig, _apply_env_overrides
+        config = GatewayConfig()
+        _apply_env_overrides(config)
+
+        connected = config.get_connected_platforms()
+        assert Platform.SIGNAL in connected
+
+
+# ---------------------------------------------------------------------------
+# Adapter Init & Helpers
+# ---------------------------------------------------------------------------
+
+class TestSignalAdapterInit:
+    def _make_config(self, **extra):
+        config = PlatformConfig()
+        config.enabled = True
+        config.extra = {
+            "http_url": "http://localhost:8080",
+            "account": "+15551234567",
+            **extra,
+        }
+        return config
+
+    def test_init_parses_config(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "group123,group456")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
+        assert adapter.http_url == "http://localhost:8080"
+        assert adapter.account == "+15551234567"
+        assert "group123" in adapter.group_allow_from
+
+    def test_init_empty_allowlist(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
+        assert len(adapter.group_allow_from) == 0
+
+    def test_init_strips_trailing_slash(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config(http_url="http://localhost:8080/"))
+
+        assert adapter.http_url == "http://localhost:8080"
+
+    def test_self_message_filtering(self, monkeypatch):
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
+        assert adapter._account_normalized == "+15551234567"
+
+
+class TestSignalHelpers:
+    def test_redact_phone_long(self):
+        from gateway.platforms.signal import _redact_phone
+        assert _redact_phone("+15551234567") == "+155****4567"
+
+    def test_redact_phone_short(self):
+        from gateway.platforms.signal import _redact_phone
+        assert _redact_phone("+12345") == "+1****45"
+
+    def test_redact_phone_empty(self):
+        from gateway.platforms.signal import _redact_phone
+        assert _redact_phone("") == "<none>"
+
+    def test_parse_comma_list(self):
+        from gateway.platforms.signal import _parse_comma_list
+        assert _parse_comma_list("+1234, +5678 , +9012") == ["+1234", "+5678", "+9012"]
+        assert _parse_comma_list("") == []
+        assert _parse_comma_list("  ,  ,  ") == []
+
+    def test_guess_extension_png(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100) == ".png"
+
+    def test_guess_extension_jpeg(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"\xff\xd8\xff\xe0" + b"\x00" * 100) == ".jpg"
+
+    def test_guess_extension_pdf(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"%PDF-1.4" + b"\x00" * 100) == ".pdf"
+
+    def test_guess_extension_zip(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"PK\x03\x04" + b"\x00" * 100) == ".zip"
+
+    def test_guess_extension_mp4(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"\x00\x00\x00\x18ftypisom" + b"\x00" * 100) == ".mp4"
+
+    def test_guess_extension_unknown(self):
+        from gateway.platforms.signal import _guess_extension
+        assert _guess_extension(b"\x00\x01\x02\x03" * 10) == ".bin"
+
+    def test_is_image_ext(self):
+        from gateway.platforms.signal import _is_image_ext
+        assert _is_image_ext(".png") is True
+        assert _is_image_ext(".jpg") is True
+        assert _is_image_ext(".gif") is True
+        assert _is_image_ext(".pdf") is False
+
+    def test_is_audio_ext(self):
+        from gateway.platforms.signal import _is_audio_ext
+        assert _is_audio_ext(".mp3") is True
+        assert _is_audio_ext(".ogg") is True
+        assert _is_audio_ext(".png") is False
+
+    def test_check_requirements(self, monkeypatch):
+        from gateway.platforms.signal import check_signal_requirements
+        monkeypatch.setenv("SIGNAL_HTTP_URL", "http://localhost:8080")
+        monkeypatch.setenv("SIGNAL_ACCOUNT", "+15551234567")
+        assert check_signal_requirements() is True
+
+    def test_render_mentions(self):
+        from gateway.platforms.signal import _render_mentions
+        text = "Hello \uFFFC, how are you?"
+        mentions = [{"start": 6, "length": 1, "number": "+15559999999"}]
+        result = _render_mentions(text, mentions)
+        assert "@+15559999999" in result
+        assert "\uFFFC" not in result
+
+    def test_render_mentions_no_mentions(self):
+        from gateway.platforms.signal import _render_mentions
+        text = "Hello world"
+        result = _render_mentions(text, [])
+        assert result == "Hello world"
+
+    def test_check_requirements_missing(self, monkeypatch):
+        from gateway.platforms.signal import check_signal_requirements
+        monkeypatch.delenv("SIGNAL_HTTP_URL", raising=False)
+        monkeypatch.delenv("SIGNAL_ACCOUNT", raising=False)
+        assert check_signal_requirements() is False
+
+
+# ---------------------------------------------------------------------------
+# Session Source
+# ---------------------------------------------------------------------------
+
+class TestSignalSessionSource:
+    def test_session_source_alt_fields(self):
+        from gateway.session import SessionSource
+        source = SessionSource(
+            platform=Platform.SIGNAL,
+            chat_id="+15551234567",
+            user_id="+15551234567",
+            user_id_alt="uuid:abc-123",
+            chat_id_alt=None,
+        )
+        d = source.to_dict()
+        assert d["user_id_alt"] == "uuid:abc-123"
+        assert "chat_id_alt" not in d  # None fields excluded
+
+    def test_session_source_roundtrip(self):
+        from gateway.session import SessionSource
+        source = SessionSource(
+            platform=Platform.SIGNAL,
+            chat_id="group:xyz",
+            chat_type="group",
+            user_id="+15551234567",
+            user_id_alt="uuid:abc",
+            chat_id_alt="xyz",
+        )
+        d = source.to_dict()
+        restored = SessionSource.from_dict(d)
+        assert restored.user_id_alt == "uuid:abc"
+        assert restored.chat_id_alt == "xyz"
+        assert restored.platform == Platform.SIGNAL
+
+
+# ---------------------------------------------------------------------------
+# Phone Redaction in agent/redact.py
+# ---------------------------------------------------------------------------
+
+class TestSignalPhoneRedaction:
+    def test_us_number(self):
+        from agent.redact import redact_sensitive_text
+        result = redact_sensitive_text("Call +15551234567 now")
+        assert "+15551234567" not in result
+        assert "+155" in result  # Prefix preserved
+        assert "4567" in result  # Suffix preserved
+
+    def test_uk_number(self):
+        from agent.redact import redact_sensitive_text
+        result = redact_sensitive_text("UK: +442071838750")
+        assert "+442071838750" not in result
+        assert "****" in result
+
+    def test_multiple_numbers(self):
+        from agent.redact import redact_sensitive_text
+        text = "From +15551234567 to +442071838750"
+        result = redact_sensitive_text(text)
+        assert "+15551234567" not in result
+        assert "+442071838750" not in result
+
+    def test_short_number_not_matched(self):
+        from agent.redact import redact_sensitive_text
+        result = redact_sensitive_text("Code: +12345")
+        # 5 digits after + is below the 7-digit minimum
+        assert "+12345" in result  # Too short to redact
+
+
+# ---------------------------------------------------------------------------
+# Authorization in run.py
+# ---------------------------------------------------------------------------
+
+class TestSignalAuthorization:
+    def test_signal_in_allowlist_maps(self):
+        """Signal should be in the platform auth maps."""
+        from gateway.run import GatewayRunner
+        from gateway.config import GatewayConfig
+
+        gw = GatewayRunner.__new__(GatewayRunner)
+        gw.config = GatewayConfig()
+        gw.pairing_store = MagicMock()
+        gw.pairing_store.is_approved.return_value = False
+
+        source = MagicMock()
+        source.platform = Platform.SIGNAL
+        source.user_id = "+15559999999"
+
+        # No allowlists set — should check GATEWAY_ALLOW_ALL_USERS
+        with patch.dict("os.environ", {}, clear=True):
+            result = gw._is_user_authorized(source)
+            assert result is False
+
+
+# ---------------------------------------------------------------------------
+# Send Message Tool
+# ---------------------------------------------------------------------------
+
+class TestSignalSendMessage:
+    def test_signal_in_platform_map(self):
+        """Signal should be in the send_message tool's platform map."""
+        from tools.send_message_tool import send_message_tool
+        # Just verify the import works and Signal is a valid platform
+        from gateway.config import Platform
+        assert Platform.SIGNAL.value == "signal"

tests/hermes_cli/test_set_config_value.py

@@ -38,7 +38,6 @@ class TestExplicitAllowlist:
         "OPENROUTER_API_KEY",
         "OPENAI_API_KEY",
         "ANTHROPIC_API_KEY",
-        "NOUS_API_KEY",
         "WANDB_API_KEY",
         "TINKER_API_KEY",
         "HONCHO_API_KEY",

tests/integration/test_web_tools.py

@@ -12,7 +12,7 @@ Usage:
 
 Requirements:
     - FIRECRAWL_API_KEY environment variable must be set
-    - NOUS_API_KEY environment variable (optional, for LLM tests)
+    - An auxiliary LLM provider (OPENROUTER_API_KEY or Nous Portal auth) (optional, for LLM tests)
 """
 
 import pytest
@@ -128,12 +128,12 @@ class WebToolsTester:
         else:
             self.log_result("Firecrawl API Key", "passed", "Found")
         
-        # Check Nous API key (optional)
+        # Check auxiliary LLM provider (optional)
         if not check_auxiliary_model():
-            self.log_result("Nous API Key", "skipped", "NOUS_API_KEY not set (LLM tests will be skipped)")
+            self.log_result("Auxiliary LLM", "skipped", "No auxiliary LLM provider available (LLM tests will be skipped)")
             self.test_llm = False
         else:
-            self.log_result("Nous API Key", "passed", "Found")
+            self.log_result("Auxiliary LLM", "passed", "Found")
         
         # Check debug mode
         debug_info = get_debug_session_info()

tests/test_codex_execution_paths.py

@@ -149,6 +149,7 @@ def test_gateway_run_agent_codex_path_handles_internal_401_refresh(monkeypatch):
     runner._prefill_messages = []
     runner._reasoning_config = None
     runner._provider_routing = {}
+    runner._fallback_model = None
     runner._running_agents = {}
     from unittest.mock import MagicMock, AsyncMock
     runner.hooks = MagicMock()

tests/test_fallback_model.py

@@ -0,0 +1,339 @@
+"""Tests for the provider fallback model feature.
+
+Verifies that AIAgent can switch to a configured fallback model/provider
+when the primary fails after retries.
+"""
+
+import os
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from run_agent import AIAgent
+
+
+def _make_tool_defs(*names: str) -> list:
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": n,
+                "description": f"{n} tool",
+                "parameters": {"type": "object", "properties": {}},
+            },
+        }
+        for n in names
+    ]
+
+
+def _make_agent(fallback_model=None):
+    """Create a minimal AIAgent with optional fallback config."""
+    with (
+        patch("run_agent.get_tool_definitions", return_value=_make_tool_defs("web_search")),
+        patch("run_agent.check_toolset_requirements", return_value={}),
+        patch("run_agent.OpenAI"),
+    ):
+        agent = AIAgent(
+            api_key="test-key-primary",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            fallback_model=fallback_model,
+        )
+        agent.client = MagicMock()
+        return agent
+
+
+# =============================================================================
+# _try_activate_fallback()
+# =============================================================================
+
+class TestTryActivateFallback:
+    def test_returns_false_when_not_configured(self):
+        agent = _make_agent(fallback_model=None)
+        assert agent._try_activate_fallback() is False
+        assert agent._fallback_activated is False
+
+    def test_returns_false_for_empty_config(self):
+        agent = _make_agent(fallback_model={"provider": "", "model": ""})
+        assert agent._try_activate_fallback() is False
+
+    def test_returns_false_for_missing_provider(self):
+        agent = _make_agent(fallback_model={"model": "gpt-4.1"})
+        assert agent._try_activate_fallback() is False
+
+    def test_returns_false_for_missing_model(self):
+        agent = _make_agent(fallback_model={"provider": "openrouter"})
+        assert agent._try_activate_fallback() is False
+
+    def test_activates_openrouter_fallback(self):
+        agent = _make_agent(
+            fallback_model={"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
+        )
+        with (
+            patch.dict("os.environ", {"OPENROUTER_API_KEY": "sk-or-fallback-key"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            result = agent._try_activate_fallback()
+            assert result is True
+            assert agent._fallback_activated is True
+            assert agent.model == "anthropic/claude-sonnet-4"
+            assert agent.provider == "openrouter"
+            assert agent.api_mode == "chat_completions"
+            mock_openai.assert_called_once()
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "sk-or-fallback-key"
+            assert "openrouter" in call_kwargs["base_url"].lower()
+            # OpenRouter should get attribution headers
+            assert "default_headers" in call_kwargs
+
+    def test_activates_zai_fallback(self):
+        agent = _make_agent(
+            fallback_model={"provider": "zai", "model": "glm-5"},
+        )
+        with (
+            patch.dict("os.environ", {"ZAI_API_KEY": "sk-zai-key"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            result = agent._try_activate_fallback()
+            assert result is True
+            assert agent.model == "glm-5"
+            assert agent.provider == "zai"
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "sk-zai-key"
+            assert "z.ai" in call_kwargs["base_url"].lower()
+
+    def test_activates_kimi_fallback(self):
+        agent = _make_agent(
+            fallback_model={"provider": "kimi-coding", "model": "kimi-k2.5"},
+        )
+        with (
+            patch.dict("os.environ", {"KIMI_API_KEY": "sk-kimi-key"}),
+            patch("run_agent.OpenAI"),
+        ):
+            assert agent._try_activate_fallback() is True
+            assert agent.model == "kimi-k2.5"
+            assert agent.provider == "kimi-coding"
+
+    def test_activates_minimax_fallback(self):
+        agent = _make_agent(
+            fallback_model={"provider": "minimax", "model": "MiniMax-M2.5"},
+        )
+        with (
+            patch.dict("os.environ", {"MINIMAX_API_KEY": "sk-mm-key"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            assert agent._try_activate_fallback() is True
+            assert agent.model == "MiniMax-M2.5"
+            assert agent.provider == "minimax"
+            call_kwargs = mock_openai.call_args[1]
+            assert "minimax.io" in call_kwargs["base_url"]
+
+    def test_only_fires_once(self):
+        agent = _make_agent(
+            fallback_model={"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
+        )
+        with (
+            patch.dict("os.environ", {"OPENROUTER_API_KEY": "sk-or-key"}),
+            patch("run_agent.OpenAI"),
+        ):
+            assert agent._try_activate_fallback() is True
+            # Second attempt should return False
+            assert agent._try_activate_fallback() is False
+
+    def test_returns_false_when_no_api_key(self):
+        """Fallback should fail gracefully when the API key env var is unset."""
+        agent = _make_agent(
+            fallback_model={"provider": "minimax", "model": "MiniMax-M2.5"},
+        )
+        # Ensure MINIMAX_API_KEY is not in the environment
+        env = {k: v for k, v in os.environ.items() if k != "MINIMAX_API_KEY"}
+        with patch.dict("os.environ", env, clear=True):
+            assert agent._try_activate_fallback() is False
+            assert agent._fallback_activated is False
+
+    def test_custom_base_url(self):
+        """Custom base_url in config should override the provider default."""
+        agent = _make_agent(
+            fallback_model={
+                "provider": "custom",
+                "model": "my-model",
+                "base_url": "http://localhost:8080/v1",
+                "api_key_env": "MY_CUSTOM_KEY",
+            },
+        )
+        with (
+            patch.dict("os.environ", {"MY_CUSTOM_KEY": "custom-secret"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            assert agent._try_activate_fallback() is True
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["base_url"] == "http://localhost:8080/v1"
+            assert call_kwargs["api_key"] == "custom-secret"
+
+    def test_prompt_caching_enabled_for_claude_on_openrouter(self):
+        agent = _make_agent(
+            fallback_model={"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
+        )
+        with (
+            patch.dict("os.environ", {"OPENROUTER_API_KEY": "sk-or-key"}),
+            patch("run_agent.OpenAI"),
+        ):
+            agent._try_activate_fallback()
+            assert agent._use_prompt_caching is True
+
+    def test_prompt_caching_disabled_for_non_claude(self):
+        agent = _make_agent(
+            fallback_model={"provider": "openrouter", "model": "google/gemini-2.5-flash"},
+        )
+        with (
+            patch.dict("os.environ", {"OPENROUTER_API_KEY": "sk-or-key"}),
+            patch("run_agent.OpenAI"),
+        ):
+            agent._try_activate_fallback()
+            assert agent._use_prompt_caching is False
+
+    def test_prompt_caching_disabled_for_non_openrouter(self):
+        agent = _make_agent(
+            fallback_model={"provider": "zai", "model": "glm-5"},
+        )
+        with (
+            patch.dict("os.environ", {"ZAI_API_KEY": "sk-zai-key"}),
+            patch("run_agent.OpenAI"),
+        ):
+            agent._try_activate_fallback()
+            assert agent._use_prompt_caching is False
+
+    def test_zai_alt_env_var(self):
+        """Z.AI should also check Z_AI_API_KEY as fallback env var."""
+        agent = _make_agent(
+            fallback_model={"provider": "zai", "model": "glm-5"},
+        )
+        with (
+            patch.dict("os.environ", {"Z_AI_API_KEY": "sk-alt-key"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            assert agent._try_activate_fallback() is True
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "sk-alt-key"
+
+    def test_activates_codex_fallback(self):
+        """OpenAI Codex fallback should use OAuth credentials and codex_responses mode."""
+        agent = _make_agent(
+            fallback_model={"provider": "openai-codex", "model": "gpt-5.3-codex"},
+        )
+        mock_creds = {
+            "api_key": "codex-oauth-token",
+            "base_url": "https://chatgpt.com/backend-api/codex",
+        }
+        with (
+            patch("hermes_cli.auth.resolve_codex_runtime_credentials", return_value=mock_creds),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            result = agent._try_activate_fallback()
+            assert result is True
+            assert agent.model == "gpt-5.3-codex"
+            assert agent.provider == "openai-codex"
+            assert agent.api_mode == "codex_responses"
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "codex-oauth-token"
+            assert "chatgpt.com" in call_kwargs["base_url"]
+
+    def test_codex_fallback_fails_gracefully_without_credentials(self):
+        """Codex fallback should return False if no OAuth credentials available."""
+        agent = _make_agent(
+            fallback_model={"provider": "openai-codex", "model": "gpt-5.3-codex"},
+        )
+        with patch(
+            "hermes_cli.auth.resolve_codex_runtime_credentials",
+            side_effect=Exception("No Codex credentials"),
+        ):
+            assert agent._try_activate_fallback() is False
+            assert agent._fallback_activated is False
+
+    def test_activates_nous_fallback(self):
+        """Nous Portal fallback should use OAuth credentials and chat_completions mode."""
+        agent = _make_agent(
+            fallback_model={"provider": "nous", "model": "nous-hermes-3"},
+        )
+        mock_creds = {
+            "api_key": "nous-agent-key-abc",
+            "base_url": "https://inference-api.nousresearch.com/v1",
+        }
+        with (
+            patch("hermes_cli.auth.resolve_nous_runtime_credentials", return_value=mock_creds),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            result = agent._try_activate_fallback()
+            assert result is True
+            assert agent.model == "nous-hermes-3"
+            assert agent.provider == "nous"
+            assert agent.api_mode == "chat_completions"
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "nous-agent-key-abc"
+            assert "nousresearch.com" in call_kwargs["base_url"]
+
+    def test_nous_fallback_fails_gracefully_without_login(self):
+        """Nous fallback should return False if not logged in."""
+        agent = _make_agent(
+            fallback_model={"provider": "nous", "model": "nous-hermes-3"},
+        )
+        with patch(
+            "hermes_cli.auth.resolve_nous_runtime_credentials",
+            side_effect=Exception("Not logged in to Nous Portal"),
+        ):
+            assert agent._try_activate_fallback() is False
+            assert agent._fallback_activated is False
+
+
+# =============================================================================
+# Fallback config init
+# =============================================================================
+
+class TestFallbackInit:
+    def test_fallback_stored_when_configured(self):
+        agent = _make_agent(
+            fallback_model={"provider": "openrouter", "model": "anthropic/claude-sonnet-4"},
+        )
+        assert agent._fallback_model is not None
+        assert agent._fallback_model["provider"] == "openrouter"
+        assert agent._fallback_activated is False
+
+    def test_fallback_none_when_not_configured(self):
+        agent = _make_agent(fallback_model=None)
+        assert agent._fallback_model is None
+        assert agent._fallback_activated is False
+
+    def test_fallback_none_for_non_dict(self):
+        agent = _make_agent(fallback_model="not-a-dict")
+        assert agent._fallback_model is None
+
+
+# =============================================================================
+# Provider credential resolution
+# =============================================================================
+
+class TestProviderCredentials:
+    """Verify that each supported provider resolves its API key correctly."""
+
+    @pytest.mark.parametrize("provider,env_var,base_url_fragment", [
+        ("openrouter", "OPENROUTER_API_KEY", "openrouter"),
+        ("zai", "ZAI_API_KEY", "z.ai"),
+        ("kimi-coding", "KIMI_API_KEY", "moonshot.ai"),
+        ("minimax", "MINIMAX_API_KEY", "minimax.io"),
+        ("minimax-cn", "MINIMAX_CN_API_KEY", "minimaxi.com"),
+    ])
+    def test_provider_resolves(self, provider, env_var, base_url_fragment):
+        agent = _make_agent(
+            fallback_model={"provider": provider, "model": "test-model"},
+        )
+        with (
+            patch.dict("os.environ", {env_var: "test-key-123"}),
+            patch("run_agent.OpenAI") as mock_openai,
+        ):
+            result = agent._try_activate_fallback()
+            assert result is True, f"Failed to activate fallback for {provider}"
+            call_kwargs = mock_openai.call_args[1]
+            assert call_kwargs["api_key"] == "test-key-123"
+            assert base_url_fragment in call_kwargs["base_url"].lower()

tests/test_run_agent.py

@@ -1040,3 +1040,136 @@ class TestMaxTokensParam:
         agent.base_url = "https://openrouter.ai/api/v1/api.openai.com"
         result = agent._max_tokens_param(4096)
         assert result == {"max_tokens": 4096}
+
+
+# ---------------------------------------------------------------------------
+# System prompt stability for prompt caching
+# ---------------------------------------------------------------------------
+
+class TestSystemPromptStability:
+    """Verify that the system prompt stays stable across turns for cache hits."""
+
+    def test_stored_prompt_reused_for_continuing_session(self, agent):
+        """When conversation_history is non-empty and session DB has a stored
+        prompt, it should be reused instead of rebuilding from disk."""
+        stored = "You are helpful. [stored from turn 1]"
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"system_prompt": stored}
+        agent._session_db = mock_db
+
+        # Simulate a continuing session with history
+        history = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi"},
+        ]
+
+        # First call — _cached_system_prompt is None, history is non-empty
+        agent._cached_system_prompt = None
+
+        # Patch run_conversation internals to just test the system prompt logic.
+        # We'll call the prompt caching block directly by simulating what
+        # run_conversation does.
+        conversation_history = history
+
+        # The block under test (from run_conversation):
+        if agent._cached_system_prompt is None:
+            stored_prompt = None
+            if conversation_history and agent._session_db:
+                try:
+                    session_row = agent._session_db.get_session(agent.session_id)
+                    if session_row:
+                        stored_prompt = session_row.get("system_prompt") or None
+                except Exception:
+                    pass
+
+            if stored_prompt:
+                agent._cached_system_prompt = stored_prompt
+
+        assert agent._cached_system_prompt == stored
+        mock_db.get_session.assert_called_once_with(agent.session_id)
+
+    def test_fresh_build_when_no_history(self, agent):
+        """On the first turn (no history), system prompt should be built fresh."""
+        mock_db = MagicMock()
+        agent._session_db = mock_db
+
+        agent._cached_system_prompt = None
+        conversation_history = []
+
+        # The block under test:
+        if agent._cached_system_prompt is None:
+            stored_prompt = None
+            if conversation_history and agent._session_db:
+                session_row = agent._session_db.get_session(agent.session_id)
+                if session_row:
+                    stored_prompt = session_row.get("system_prompt") or None
+
+            if stored_prompt:
+                agent._cached_system_prompt = stored_prompt
+            else:
+                agent._cached_system_prompt = agent._build_system_prompt()
+
+        # Should have built fresh, not queried the DB
+        mock_db.get_session.assert_not_called()
+        assert agent._cached_system_prompt is not None
+        assert "Hermes Agent" in agent._cached_system_prompt
+
+    def test_fresh_build_when_db_has_no_prompt(self, agent):
+        """If the session DB has no stored prompt, build fresh even with history."""
+        mock_db = MagicMock()
+        mock_db.get_session.return_value = {"system_prompt": ""}
+        agent._session_db = mock_db
+
+        agent._cached_system_prompt = None
+        conversation_history = [{"role": "user", "content": "hi"}]
+
+        if agent._cached_system_prompt is None:
+            stored_prompt = None
+            if conversation_history and agent._session_db:
+                try:
+                    session_row = agent._session_db.get_session(agent.session_id)
+                    if session_row:
+                        stored_prompt = session_row.get("system_prompt") or None
+                except Exception:
+                    pass
+
+            if stored_prompt:
+                agent._cached_system_prompt = stored_prompt
+            else:
+                agent._cached_system_prompt = agent._build_system_prompt()
+
+        # Empty string is falsy, so should fall through to fresh build
+        assert "Hermes Agent" in agent._cached_system_prompt
+
+    def test_honcho_context_baked_into_prompt_on_first_turn(self, agent):
+        """Honcho context should be baked into _cached_system_prompt on
+        the first turn, not injected separately per API call."""
+        agent._honcho_context = "User prefers Python over JavaScript."
+        agent._cached_system_prompt = None
+
+        # Simulate first turn: build fresh and bake in Honcho
+        agent._cached_system_prompt = agent._build_system_prompt()
+        if agent._honcho_context:
+            agent._cached_system_prompt = (
+                agent._cached_system_prompt + "\n\n" + agent._honcho_context
+            ).strip()
+
+        assert "User prefers Python over JavaScript" in agent._cached_system_prompt
+
+    def test_honcho_prefetch_skipped_on_continuing_session(self):
+        """Honcho prefetch should not be called when conversation_history
+        is non-empty (continuing session)."""
+        conversation_history = [
+            {"role": "user", "content": "hello"},
+            {"role": "assistant", "content": "hi there"},
+        ]
+
+        # The guard: `not conversation_history` is False when history exists
+        should_prefetch = not conversation_history
+        assert should_prefetch is False
+
+    def test_honcho_prefetch_runs_on_first_turn(self):
+        """Honcho prefetch should run when conversation_history is empty."""
+        conversation_history = []
+        should_prefetch = not conversation_history
+        assert should_prefetch is True

tests/tools/test_browser_console.py

@@ -0,0 +1,276 @@
+"""Tests for browser_console tool and browser_vision annotate param."""
+
+import json
+import os
+import sys
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", ".."))
+
+
+# ── browser_console ──────────────────────────────────────────────────
+
+
+class TestBrowserConsole:
+    """browser_console() returns console messages + JS errors in one call."""
+
+    def test_returns_console_messages_and_errors(self):
+        from tools.browser_tool import browser_console
+
+        console_response = {
+            "success": True,
+            "data": {
+                "messages": [
+                    {"text": "hello", "type": "log", "timestamp": 1},
+                    {"text": "oops", "type": "error", "timestamp": 2},
+                ]
+            },
+        }
+        errors_response = {
+            "success": True,
+            "data": {
+                "errors": [
+                    {"message": "Uncaught TypeError", "timestamp": 3},
+                ]
+            },
+        }
+
+        with patch("tools.browser_tool._run_browser_command") as mock_cmd:
+            mock_cmd.side_effect = [console_response, errors_response]
+            result = json.loads(browser_console(task_id="test"))
+
+        assert result["success"] is True
+        assert result["total_messages"] == 2
+        assert result["total_errors"] == 1
+        assert result["console_messages"][0]["text"] == "hello"
+        assert result["console_messages"][1]["text"] == "oops"
+        assert result["js_errors"][0]["message"] == "Uncaught TypeError"
+
+    def test_passes_clear_flag(self):
+        from tools.browser_tool import browser_console
+
+        empty = {"success": True, "data": {"messages": [], "errors": []}}
+        with patch("tools.browser_tool._run_browser_command", return_value=empty) as mock_cmd:
+            browser_console(clear=True, task_id="test")
+
+        calls = mock_cmd.call_args_list
+        # Both console and errors should get --clear
+        assert calls[0][0] == ("test", "console", ["--clear"])
+        assert calls[1][0] == ("test", "errors", ["--clear"])
+
+    def test_no_clear_by_default(self):
+        from tools.browser_tool import browser_console
+
+        empty = {"success": True, "data": {"messages": [], "errors": []}}
+        with patch("tools.browser_tool._run_browser_command", return_value=empty) as mock_cmd:
+            browser_console(task_id="test")
+
+        calls = mock_cmd.call_args_list
+        assert calls[0][0] == ("test", "console", [])
+        assert calls[1][0] == ("test", "errors", [])
+
+    def test_empty_console_and_errors(self):
+        from tools.browser_tool import browser_console
+
+        empty = {"success": True, "data": {"messages": [], "errors": []}}
+        with patch("tools.browser_tool._run_browser_command", return_value=empty):
+            result = json.loads(browser_console(task_id="test"))
+
+        assert result["total_messages"] == 0
+        assert result["total_errors"] == 0
+        assert result["console_messages"] == []
+        assert result["js_errors"] == []
+
+    def test_handles_failed_commands(self):
+        from tools.browser_tool import browser_console
+
+        failed = {"success": False, "error": "No session"}
+        with patch("tools.browser_tool._run_browser_command", return_value=failed):
+            result = json.loads(browser_console(task_id="test"))
+
+        # Should still return success with empty data
+        assert result["success"] is True
+        assert result["total_messages"] == 0
+        assert result["total_errors"] == 0
+
+
+# ── browser_console schema ───────────────────────────────────────────
+
+
+class TestBrowserConsoleSchema:
+    """browser_console is properly registered in the tool registry."""
+
+    def test_schema_in_browser_schemas(self):
+        from tools.browser_tool import BROWSER_TOOL_SCHEMAS
+
+        names = [s["name"] for s in BROWSER_TOOL_SCHEMAS]
+        assert "browser_console" in names
+
+    def test_schema_has_clear_param(self):
+        from tools.browser_tool import BROWSER_TOOL_SCHEMAS
+
+        schema = next(s for s in BROWSER_TOOL_SCHEMAS if s["name"] == "browser_console")
+        props = schema["parameters"]["properties"]
+        assert "clear" in props
+        assert props["clear"]["type"] == "boolean"
+
+
+# ── browser_vision annotate ──────────────────────────────────────────
+
+
+class TestBrowserVisionAnnotate:
+    """browser_vision supports annotate parameter."""
+
+    def test_schema_has_annotate_param(self):
+        from tools.browser_tool import BROWSER_TOOL_SCHEMAS
+
+        schema = next(s for s in BROWSER_TOOL_SCHEMAS if s["name"] == "browser_vision")
+        props = schema["parameters"]["properties"]
+        assert "annotate" in props
+        assert props["annotate"]["type"] == "boolean"
+
+    def test_annotate_false_no_flag(self):
+        """Without annotate, screenshot command has no --annotate flag."""
+        from tools.browser_tool import browser_vision
+
+        with (
+            patch("tools.browser_tool._run_browser_command") as mock_cmd,
+            patch("tools.browser_tool._aux_vision_client") as mock_client,
+            patch("tools.browser_tool._DEFAULT_VISION_MODEL", "test-model"),
+            patch("tools.browser_tool._get_vision_model", return_value="test-model"),
+        ):
+            mock_cmd.return_value = {"success": True, "data": {}}
+            # Will fail at screenshot file read, but we can check the command
+            try:
+                browser_vision("test", annotate=False, task_id="test")
+            except Exception:
+                pass
+
+            if mock_cmd.called:
+                args = mock_cmd.call_args[0]
+                cmd_args = args[2] if len(args) > 2 else []
+                assert "--annotate" not in cmd_args
+
+    def test_annotate_true_adds_flag(self):
+        """With annotate=True, screenshot command includes --annotate."""
+        from tools.browser_tool import browser_vision
+
+        with (
+            patch("tools.browser_tool._run_browser_command") as mock_cmd,
+            patch("tools.browser_tool._aux_vision_client") as mock_client,
+            patch("tools.browser_tool._DEFAULT_VISION_MODEL", "test-model"),
+            patch("tools.browser_tool._get_vision_model", return_value="test-model"),
+        ):
+            mock_cmd.return_value = {"success": True, "data": {}}
+            try:
+                browser_vision("test", annotate=True, task_id="test")
+            except Exception:
+                pass
+
+            if mock_cmd.called:
+                args = mock_cmd.call_args[0]
+                cmd_args = args[2] if len(args) > 2 else []
+                assert "--annotate" in cmd_args
+
+
+# ── auto-recording config ────────────────────────────────────────────
+
+
+class TestRecordSessionsConfig:
+    """browser.record_sessions config option."""
+
+    def test_default_config_has_record_sessions(self):
+        from hermes_cli.config import DEFAULT_CONFIG
+
+        browser_cfg = DEFAULT_CONFIG.get("browser", {})
+        assert "record_sessions" in browser_cfg
+        assert browser_cfg["record_sessions"] is False
+
+    def test_maybe_start_recording_disabled(self):
+        """Recording doesn't start when config says record_sessions: false."""
+        from tools.browser_tool import _maybe_start_recording, _recording_sessions
+
+        with (
+            patch("tools.browser_tool._run_browser_command") as mock_cmd,
+            patch("builtins.open", side_effect=FileNotFoundError),
+        ):
+            _maybe_start_recording("test-task")
+
+        mock_cmd.assert_not_called()
+        assert "test-task" not in _recording_sessions
+
+    def test_maybe_stop_recording_noop_when_not_recording(self):
+        """Stopping when not recording is a no-op."""
+        from tools.browser_tool import _maybe_stop_recording, _recording_sessions
+
+        _recording_sessions.discard("test-task")  # ensure not in set
+        with patch("tools.browser_tool._run_browser_command") as mock_cmd:
+            _maybe_stop_recording("test-task")
+
+        mock_cmd.assert_not_called()
+
+
+# ── dogfood skill files ──────────────────────────────────────────────
+
+
+class TestDogfoodSkill:
+    """Dogfood skill files exist and have correct structure."""
+
+    @pytest.fixture(autouse=True)
+    def _skill_dir(self):
+        # Use the actual repo skills dir (not temp)
+        self.skill_dir = os.path.join(
+            os.path.dirname(__file__), "..", "..", "skills", "dogfood"
+        )
+
+    def test_skill_md_exists(self):
+        assert os.path.exists(os.path.join(self.skill_dir, "SKILL.md"))
+
+    def test_taxonomy_exists(self):
+        assert os.path.exists(
+            os.path.join(self.skill_dir, "references", "issue-taxonomy.md")
+        )
+
+    def test_report_template_exists(self):
+        assert os.path.exists(
+            os.path.join(self.skill_dir, "templates", "dogfood-report-template.md")
+        )
+
+    def test_skill_md_has_frontmatter(self):
+        with open(os.path.join(self.skill_dir, "SKILL.md")) as f:
+            content = f.read()
+        assert content.startswith("---")
+        assert "name: dogfood" in content
+        assert "description:" in content
+
+    def test_skill_references_browser_console(self):
+        with open(os.path.join(self.skill_dir, "SKILL.md")) as f:
+            content = f.read()
+        assert "browser_console" in content
+
+    def test_skill_references_annotate(self):
+        with open(os.path.join(self.skill_dir, "SKILL.md")) as f:
+            content = f.read()
+        assert "annotate" in content
+
+    def test_taxonomy_has_severity_levels(self):
+        with open(
+            os.path.join(self.skill_dir, "references", "issue-taxonomy.md")
+        ) as f:
+            content = f.read()
+        assert "Critical" in content
+        assert "High" in content
+        assert "Medium" in content
+        assert "Low" in content
+
+    def test_taxonomy_has_categories(self):
+        with open(
+            os.path.join(self.skill_dir, "references", "issue-taxonomy.md")
+        ) as f:
+            content = f.read()
+        assert "Functional" in content
+        assert "Visual" in content
+        assert "Accessibility" in content
+        assert "Console" in content

tests/tools/test_code_execution.py

@@ -393,5 +393,56 @@ class TestStubSchemaDrift(unittest.TestCase):
         self.assertIn("mode", src)
 
 
+class TestHeadTailTruncation(unittest.TestCase):
+    """Tests for head+tail truncation of large stdout in execute_code."""
+
+    def _run(self, code):
+        with patch("model_tools.handle_function_call", side_effect=_mock_handle_function_call):
+            result = execute_code(
+                code=code,
+                task_id="test-task",
+                enabled_tools=list(SANDBOX_ALLOWED_TOOLS),
+            )
+        return json.loads(result)
+
+    def test_short_output_not_truncated(self):
+        """Output under MAX_STDOUT_BYTES should not be truncated."""
+        result = self._run('print("small output")')
+        self.assertEqual(result["status"], "success")
+        self.assertIn("small output", result["output"])
+        self.assertNotIn("TRUNCATED", result["output"])
+
+    def test_large_output_preserves_head_and_tail(self):
+        """Output exceeding MAX_STDOUT_BYTES keeps both head and tail."""
+        code = '''
+# Print HEAD marker, then filler, then TAIL marker
+print("HEAD_MARKER_START")
+for i in range(15000):
+    print(f"filler_line_{i:06d}_padding_to_fill_buffer")
+print("TAIL_MARKER_END")
+'''
+        result = self._run(code)
+        self.assertEqual(result["status"], "success")
+        output = result["output"]
+        # Head should be preserved
+        self.assertIn("HEAD_MARKER_START", output)
+        # Tail should be preserved (this is the key improvement)
+        self.assertIn("TAIL_MARKER_END", output)
+        # Truncation notice should be present
+        self.assertIn("TRUNCATED", output)
+
+    def test_truncation_notice_format(self):
+        """Truncation notice includes character counts."""
+        code = '''
+for i in range(15000):
+    print(f"padding_line_{i:06d}_xxxxxxxxxxxxxxxxxxxxxxxxxx")
+'''
+        result = self._run(code)
+        output = result["output"]
+        if "TRUNCATED" in output:
+            self.assertIn("chars omitted", output)
+            self.assertIn("total", output)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/tools/test_file_tools.py

@@ -38,6 +38,7 @@ class TestReadFileHandler:
     def test_returns_file_content(self, mock_get):
         mock_ops = MagicMock()
         result_obj = MagicMock()
+        result_obj.content = "line1\nline2"
         result_obj.to_dict.return_value = {"content": "line1\nline2", "total_lines": 2}
         mock_ops.read_file.return_value = result_obj
         mock_get.return_value = mock_ops
@@ -52,6 +53,7 @@ class TestReadFileHandler:
     def test_custom_offset_and_limit(self, mock_get):
         mock_ops = MagicMock()
         result_obj = MagicMock()
+        result_obj.content = "line10"
         result_obj.to_dict.return_value = {"content": "line10", "total_lines": 50}
         mock_ops.read_file.return_value = result_obj
         mock_get.return_value = mock_ops

tools/browser_tool.py

@@ -144,6 +144,7 @@ def _socket_safe_tmpdir() -> str:
 # Track active sessions per task
 # Stores: session_name (always), bb_session_id + cdp_url (cloud mode only)
 _active_sessions: Dict[str, Dict[str, str]] = {}  # task_id -> {session_name, ...}
+_recording_sessions: set = set()  # task_ids with active recordings
 
 # Flag to track if cleanup has been done
 _cleanup_done = False
@@ -478,11 +479,31 @@ BROWSER_TOOL_SCHEMAS = [
                 "question": {
                     "type": "string",
                     "description": "What you want to know about the page visually. Be specific about what you're looking for."
+                },
+                "annotate": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "If true, overlay numbered [N] labels on interactive elements. Each [N] maps to ref @eN for subsequent browser commands. Useful for QA and spatial reasoning about page layout."
                 }
             },
             "required": ["question"]
         }
     },
+    {
+        "name": "browser_console",
+        "description": "Get browser console output and JavaScript errors from the current page. Returns console.log/warn/error/info messages and uncaught JS exceptions. Use this to detect silent JavaScript errors, failed API calls, and application warnings. Requires browser_navigate to be called first.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "clear": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "If true, clear the message buffers after reading"
+                }
+            },
+            "required": []
+        }
+    },
 ]
 
 
@@ -802,6 +823,7 @@ def _run_browser_command(
     try:
         browser_cmd = _find_agent_browser()
     except FileNotFoundError as e:
+        logger.warning("agent-browser CLI not found: %s", e)
         return {"success": False, "error": str(e)}
     
     from tools.interrupt import is_interrupted
@@ -812,6 +834,7 @@ def _run_browser_command(
     try:
         session_info = _get_session_info(task_id)
     except Exception as e:
+        logger.warning("Failed to create browser session for task=%s: %s", task_id, e)
         return {"success": False, "error": f"Failed to create browser session: {str(e)}"}
     
     # Build the command with the appropriate backend flag.
@@ -841,6 +864,8 @@ def _run_browser_command(
             f"agent-browser-{session_info['session_name']}"
         )
         os.makedirs(task_socket_dir, mode=0o700, exist_ok=True)
+        logger.debug("browser cmd=%s task=%s socket_dir=%s (%d chars)",
+                     command, task_id, task_socket_dir, len(task_socket_dir))
         
         browser_env = {**os.environ}
         # Ensure PATH includes standard dirs (systemd services may have minimal PATH)
@@ -882,22 +907,29 @@ def _run_browser_command(
                                        "returncode=%s", result.returncode)
                 return parsed
             except json.JSONDecodeError:
-                # If not valid JSON, return as raw output
+                # Non-JSON output indicates agent-browser crash or version mismatch
+                raw = result.stdout.strip()[:500]
+                logger.warning("browser '%s' returned non-JSON output (rc=%s): %s",
+                               command, result.returncode, raw[:200])
                 return {
                     "success": True,
-                    "data": {"raw": result.stdout.strip()}
+                    "data": {"raw": raw}
                 }
         
         # Check for errors
         if result.returncode != 0:
             error_msg = result.stderr.strip() if result.stderr else f"Command failed with code {result.returncode}"
+            logger.warning("browser '%s' failed (rc=%s): %s", command, result.returncode, error_msg[:300])
             return {"success": False, "error": error_msg}
         
         return {"success": True, "data": {}}
         
     except subprocess.TimeoutExpired:
+        logger.warning("browser '%s' timed out after %ds (task=%s, socket_dir=%s)",
+                       command, timeout, task_id, task_socket_dir)
         return {"success": False, "error": f"Command timed out after {timeout} seconds"}
     except Exception as e:
+        logger.warning("browser '%s' exception: %s", command, e, exc_info=True)
         return {"success": False, "error": str(e)}
 
 
@@ -987,9 +1019,10 @@ def browser_navigate(url: str, task_id: Optional[str] = None) -> str:
     session_info = _get_session_info(effective_task_id)
     is_first_nav = session_info.get("_first_nav", True)
     
-    # Mark that we've done at least one navigation
+    # Auto-start recording if configured and this is first navigation
     if is_first_nav:
         session_info["_first_nav"] = False
+        _maybe_start_recording(effective_task_id)
     
     result = _run_browser_command(effective_task_id, "open", [url], timeout=60)
     
@@ -1253,6 +1286,10 @@ def browser_close(task_id: Optional[str] = None) -> str:
         JSON string with close result
     """
     effective_task_id = task_id or "default"
+    
+    # Stop auto-recording before closing
+    _maybe_stop_recording(effective_task_id)
+    
     result = _run_browser_command(effective_task_id, "close", [])
     
     # Close the backend session (Browserbase API in cloud mode, nothing extra in local mode)
@@ -1283,6 +1320,103 @@ def browser_close(task_id: Optional[str] = None) -> str:
         }, ensure_ascii=False)
 
 
+def browser_console(clear: bool = False, task_id: Optional[str] = None) -> str:
+    """Get browser console messages and JavaScript errors.
+    
+    Returns both console output (log/warn/error/info from the page's JS)
+    and uncaught exceptions (crashes, unhandled promise rejections).
+    
+    Args:
+        clear: If True, clear the message/error buffers after reading
+        task_id: Task identifier for session isolation
+        
+    Returns:
+        JSON string with console messages and JS errors
+    """
+    effective_task_id = task_id or "default"
+    
+    console_args = ["--clear"] if clear else []
+    error_args = ["--clear"] if clear else []
+    
+    console_result = _run_browser_command(effective_task_id, "console", console_args)
+    errors_result = _run_browser_command(effective_task_id, "errors", error_args)
+    
+    messages = []
+    if console_result.get("success"):
+        for msg in console_result.get("data", {}).get("messages", []):
+            messages.append({
+                "type": msg.get("type", "log"),
+                "text": msg.get("text", ""),
+                "source": "console",
+            })
+    
+    errors = []
+    if errors_result.get("success"):
+        for err in errors_result.get("data", {}).get("errors", []):
+            errors.append({
+                "message": err.get("message", ""),
+                "source": "exception",
+            })
+    
+    return json.dumps({
+        "success": True,
+        "console_messages": messages,
+        "js_errors": errors,
+        "total_messages": len(messages),
+        "total_errors": len(errors),
+    }, ensure_ascii=False)
+
+
+def _maybe_start_recording(task_id: str):
+    """Start recording if browser.record_sessions is enabled in config."""
+    if task_id in _recording_sessions:
+        return
+    try:
+        hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+        config_path = hermes_home / "config.yaml"
+        record_enabled = False
+        if config_path.exists():
+            import yaml
+            with open(config_path) as f:
+                cfg = yaml.safe_load(f) or {}
+            record_enabled = cfg.get("browser", {}).get("record_sessions", False)
+        
+        if not record_enabled:
+            return
+        
+        recordings_dir = hermes_home / "browser_recordings"
+        recordings_dir.mkdir(parents=True, exist_ok=True)
+        _cleanup_old_recordings(max_age_hours=72)
+        
+        import time
+        timestamp = time.strftime("%Y%m%d_%H%M%S")
+        recording_path = recordings_dir / f"session_{timestamp}_{task_id[:16]}.webm"
+        
+        result = _run_browser_command(task_id, "record", ["start", str(recording_path)])
+        if result.get("success"):
+            _recording_sessions.add(task_id)
+            logger.info("Auto-recording browser session %s to %s", task_id, recording_path)
+        else:
+            logger.debug("Could not start auto-recording: %s", result.get("error"))
+    except Exception as e:
+        logger.debug("Auto-recording setup failed: %s", e)
+
+
+def _maybe_stop_recording(task_id: str):
+    """Stop recording if one is active for this session."""
+    if task_id not in _recording_sessions:
+        return
+    try:
+        result = _run_browser_command(task_id, "record", ["stop"])
+        if result.get("success"):
+            path = result.get("data", {}).get("path", "")
+            logger.info("Saved browser recording for session %s: %s", task_id, path)
+    except Exception as e:
+        logger.debug("Could not stop recording for %s: %s", task_id, e)
+    finally:
+        _recording_sessions.discard(task_id)
+
+
 def browser_get_images(task_id: Optional[str] = None) -> str:
     """
     Get all images on the current page.
@@ -1337,7 +1471,7 @@ def browser_get_images(task_id: Optional[str] = None) -> str:
         }, ensure_ascii=False)
 
 
-def browser_vision(question: str, task_id: Optional[str] = None) -> str:
+def browser_vision(question: str, annotate: bool = False, task_id: Optional[str] = None) -> str:
     """
     Take a screenshot of the current page and analyze it with vision AI.
     
@@ -1351,6 +1485,7 @@ def browser_vision(question: str, task_id: Optional[str] = None) -> str:
     
     Args:
         question: What you want to know about the page visually
+        annotate: If True, overlay numbered [N] labels on interactive elements
         task_id: Task identifier for session isolation
         
     Returns:
@@ -1382,10 +1517,13 @@ def browser_vision(question: str, task_id: Optional[str] = None) -> str:
         _cleanup_old_screenshots(screenshots_dir, max_age_hours=24)
         
         # Take screenshot using agent-browser
+        screenshot_args = [str(screenshot_path)]
+        if annotate:
+            screenshot_args.insert(0, "--annotate")
         result = _run_browser_command(
             effective_task_id, 
             "screenshot", 
-            [str(screenshot_path)],
+            screenshot_args,
             timeout=30
         )
         
@@ -1426,8 +1564,11 @@ def browser_vision(question: str, task_id: Optional[str] = None) -> str:
 
         # Use the sync auxiliary vision client directly
         from agent.auxiliary_client import auxiliary_max_tokens_param
+        vision_model = _get_vision_model()
+        logger.debug("browser_vision: analysing screenshot (%d bytes) with model=%s",
+                     len(image_data), vision_model)
         response = _aux_vision_client.chat.completions.create(
-            model=_get_vision_model(),
+            model=vision_model,
             messages=[
                 {
                     "role": "user",
@@ -1442,17 +1583,22 @@ def browser_vision(question: str, task_id: Optional[str] = None) -> str:
         )
         
         analysis = response.choices[0].message.content
-        return json.dumps({
+        response_data = {
             "success": True,
             "analysis": analysis,
             "screenshot_path": str(screenshot_path),
-        }, ensure_ascii=False)
+        }
+        # Include annotation data if annotated screenshot was taken
+        if annotate and result.get("data", {}).get("annotations"):
+            response_data["annotations"] = result["data"]["annotations"]
+        return json.dumps(response_data, ensure_ascii=False)
     
     except Exception as e:
         # Keep the screenshot if it was captured successfully — the failure is
         # in the LLM vision analysis, not the capture.  Deleting a valid
         # screenshot loses evidence the user might need.  The 24-hour cleanup
         # in _cleanup_old_screenshots prevents unbounded disk growth.
+        logger.warning("browser_vision failed: %s", e, exc_info=True)
         error_info = {"success": False, "error": f"Error during vision analysis: {str(e)}"}
         if screenshot_path.exists():
             error_info["screenshot_path"] = str(screenshot_path)
@@ -1475,6 +1621,25 @@ def _cleanup_old_screenshots(screenshots_dir, max_age_hours=24):
         pass  # Non-critical — don't fail the screenshot operation
 
 
+def _cleanup_old_recordings(max_age_hours=72):
+    """Remove browser recordings older than max_age_hours to prevent disk bloat."""
+    import time
+    try:
+        hermes_home = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+        recordings_dir = hermes_home / "browser_recordings"
+        if not recordings_dir.exists():
+            return
+        cutoff = time.time() - (max_age_hours * 3600)
+        for f in recordings_dir.glob("session_*.webm"):
+            try:
+                if f.stat().st_mtime < cutoff:
+                    f.unlink()
+            except Exception:
+                pass
+    except Exception:
+        pass
+
+
 # ============================================================================
 # Cleanup and Management Functions
 # ============================================================================
@@ -1546,6 +1711,9 @@ def cleanup_browser(task_id: Optional[str] = None) -> None:
         bb_session_id = session_info.get("bb_session_id", "unknown")
         logger.debug("Found session for task %s: bb_session_id=%s", task_id, bb_session_id)
         
+        # Stop auto-recording before closing (saves the file)
+        _maybe_stop_recording(task_id)
+        
         # Try to close via agent-browser first (needs session in _active_sessions)
         try:
             _run_browser_command(task_id, "close", [], timeout=10)
@@ -1761,6 +1929,13 @@ registry.register(
     name="browser_vision",
     toolset="browser",
     schema=_BROWSER_SCHEMA_MAP["browser_vision"],
-    handler=lambda args, **kw: browser_vision(question=args.get("question", ""), task_id=kw.get("task_id")),
+    handler=lambda args, **kw: browser_vision(question=args.get("question", ""), annotate=args.get("annotate", False), task_id=kw.get("task_id")),
+    check_fn=check_browser_requirements,
+)
+registry.register(
+    name="browser_console",
+    toolset="browser",
+    schema=_BROWSER_SCHEMA_MAP["browser_console"],
+    handler=lambda args, **kw: browser_console(clear=args.get("clear", False), task_id=kw.get("task_id")),
     check_fn=check_browser_requirements,
 )

tools/code_execution_tool.py

@@ -457,11 +457,17 @@ def execute_code(
 
         # --- Poll loop: watch for exit, timeout, and interrupt ---
         deadline = time.monotonic() + timeout
-        stdout_chunks: list = []
         stderr_chunks: list = []
 
-        # Background readers to avoid pipe buffer deadlocks
+        # Background readers to avoid pipe buffer deadlocks.
+        # For stdout we use a head+tail strategy: keep the first HEAD_BYTES
+        # and a rolling window of the last TAIL_BYTES so the final print()
+        # output is never lost.  Stderr keeps head-only (errors appear early).
+        _STDOUT_HEAD_BYTES = int(MAX_STDOUT_BYTES * 0.4)   # 40% head
+        _STDOUT_TAIL_BYTES = MAX_STDOUT_BYTES - _STDOUT_HEAD_BYTES  # 60% tail
+
         def _drain(pipe, chunks, max_bytes):
+            """Simple head-only drain (used for stderr)."""
             total = 0
             try:
                 while True:
@@ -475,8 +481,48 @@ def execute_code(
             except (ValueError, OSError):
                 pass
 
+        stdout_total_bytes = [0]  # mutable ref for total bytes seen
+
+        def _drain_head_tail(pipe, head_chunks, tail_chunks, head_bytes, tail_bytes, total_ref):
+            """Drain stdout keeping both head and tail data."""
+            head_collected = 0
+            from collections import deque
+            tail_buf = deque()
+            tail_collected = 0
+            try:
+                while True:
+                    data = pipe.read(4096)
+                    if not data:
+                        break
+                    total_ref[0] += len(data)
+                    # Fill head buffer first
+                    if head_collected < head_bytes:
+                        keep = min(len(data), head_bytes - head_collected)
+                        head_chunks.append(data[:keep])
+                        head_collected += keep
+                        data = data[keep:]  # remaining goes to tail
+                        if not data:
+                            continue
+                    # Everything past head goes into rolling tail buffer
+                    tail_buf.append(data)
+                    tail_collected += len(data)
+                    # Evict old tail data to stay within tail_bytes budget
+                    while tail_collected > tail_bytes and tail_buf:
+                        oldest = tail_buf.popleft()
+                        tail_collected -= len(oldest)
+            except (ValueError, OSError):
+                pass
+            # Transfer final tail to output list
+            tail_chunks.extend(tail_buf)
+
+        stdout_head_chunks: list = []
+        stdout_tail_chunks: list = []
+
         stdout_reader = threading.Thread(
-            target=_drain, args=(proc.stdout, stdout_chunks, MAX_STDOUT_BYTES), daemon=True
+            target=_drain_head_tail,
+            args=(proc.stdout, stdout_head_chunks, stdout_tail_chunks,
+                  _STDOUT_HEAD_BYTES, _STDOUT_TAIL_BYTES, stdout_total_bytes),
+            daemon=True
         )
         stderr_reader = threading.Thread(
             target=_drain, args=(proc.stderr, stderr_chunks, MAX_STDERR_BYTES), daemon=True
@@ -500,12 +546,21 @@ def execute_code(
         stdout_reader.join(timeout=3)
         stderr_reader.join(timeout=3)
 
-        stdout_text = b"".join(stdout_chunks).decode("utf-8", errors="replace")
+        stdout_head = b"".join(stdout_head_chunks).decode("utf-8", errors="replace")
+        stdout_tail = b"".join(stdout_tail_chunks).decode("utf-8", errors="replace")
         stderr_text = b"".join(stderr_chunks).decode("utf-8", errors="replace")
 
-        # Truncation notice
-        if len(stdout_text) >= MAX_STDOUT_BYTES:
-            stdout_text = stdout_text[:MAX_STDOUT_BYTES] + "\n[output truncated at 50KB]"
+        # Assemble stdout with head+tail truncation
+        total_stdout = stdout_total_bytes[0]
+        if total_stdout > MAX_STDOUT_BYTES and stdout_tail:
+            omitted = total_stdout - len(stdout_head) - len(stdout_tail)
+            truncated_notice = (
+                f"\n\n... [OUTPUT TRUNCATED - {omitted:,} chars omitted "
+                f"out of {total_stdout:,} total] ...\n\n"
+            )
+            stdout_text = stdout_head + truncated_notice + stdout_tail
+        else:
+            stdout_text = stdout_head + stdout_tail
 
         exit_code = proc.returncode if proc.returncode is not None else -1
         duration = round(time.monotonic() - exec_start, 2)

tools/cronjob_tools.py

@@ -102,7 +102,9 @@ def schedule_cronjob(
                  - "local": Save to local files only (~/.hermes/cron/output/)
                  - "telegram": Send to Telegram home channel
                  - "discord": Send to Discord home channel
+                 - "signal": Send to Signal home channel
                  - "telegram:123456": Send to specific chat ID
+                 - "signal:+15551234567": Send to specific Signal number
     
     Returns:
         JSON with job_id, next_run time, and confirmation
@@ -216,7 +218,7 @@ Use for: reminders, periodic checks, scheduled reports, automated maintenance.""
             },
             "deliver": {
                 "type": "string",
-                "description": "Where to send output: 'origin' (back to this chat), 'local' (files only), 'telegram', 'discord', or 'platform:chat_id'"
+                "description": "Where to send output: 'origin' (back to this chat), 'local' (files only), 'telegram', 'discord', 'signal', or 'platform:chat_id'"
             }
         },
         "required": ["prompt", "schedule"]

tools/file_tools.py

@@ -7,6 +7,7 @@ import os
 import threading
 from typing import Optional
 from tools.file_operations import ShellFileOperations
+from agent.redact import redact_sensitive_text
 
 logger = logging.getLogger(__name__)
 
@@ -128,6 +129,8 @@ def read_file_tool(path: str, offset: int = 1, limit: int = 500, task_id: str =
     try:
         file_ops = _get_file_ops(task_id)
         result = file_ops.read_file(path, offset, limit)
+        if result.content:
+            result.content = redact_sensitive_text(result.content)
         return json.dumps(result.to_dict(), ensure_ascii=False)
     except Exception as e:
         return json.dumps({"error": str(e)}, ensure_ascii=False)
@@ -186,6 +189,10 @@ def search_tool(pattern: str, target: str = "content", path: str = ".",
             pattern=pattern, path=path, target=target, file_glob=file_glob,
             limit=limit, offset=offset, output_mode=output_mode, context=context
         )
+        if hasattr(result, 'matches'):
+            for m in result.matches:
+                if hasattr(m, 'content') and m.content:
+                    m.content = redact_sensitive_text(m.content)
         result_dict = result.to_dict()
         result_json = json.dumps(result_dict, ensure_ascii=False)
         # Hint when results were truncated — explicit next offset is clearer

tools/send_message_tool.py

@@ -8,6 +8,7 @@ human-friendly channel names to IDs. Works in both CLI and gateway contexts.
 import json
 import logging
 import os
+import time
 
 logger = logging.getLogger(__name__)
 
@@ -32,7 +33,7 @@ SEND_MESSAGE_SCHEMA = {
             },
             "target": {
                 "type": "string",
-                "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', or 'platform:chat_id'. Examples: 'telegram', 'discord:#bot-home', 'slack:#engineering'"
+                "description": "Delivery target. Format: 'platform' (uses home channel), 'platform:#channel-name', or 'platform:chat_id'. Examples: 'telegram', 'discord:#bot-home', 'slack:#engineering', 'signal:+15551234567'"
             },
             "message": {
                 "type": "string",
@@ -107,6 +108,7 @@ def _handle_send(args):
         "discord": Platform.DISCORD,
         "slack": Platform.SLACK,
         "whatsapp": Platform.WHATSAPP,
+        "signal": Platform.SIGNAL,
     }
     platform = platform_map.get(platform_name)
     if not platform:
@@ -160,6 +162,8 @@ async def _send_to_platform(platform, pconfig, chat_id, message):
         return await _send_discord(pconfig.token, chat_id, message)
     elif platform == Platform.SLACK:
         return await _send_slack(pconfig.token, chat_id, message)
+    elif platform == Platform.SIGNAL:
+        return await _send_signal(pconfig.extra, chat_id, message)
     return {"error": f"Direct sending not yet implemented for {platform.value}"}
 
 
@@ -219,6 +223,42 @@ async def _send_slack(token, chat_id, message):
         return {"error": f"Slack send failed: {e}"}
 
 
+async def _send_signal(extra, chat_id, message):
+    """Send via signal-cli JSON-RPC API."""
+    try:
+        import httpx
+    except ImportError:
+        return {"error": "httpx not installed"}
+    try:
+        http_url = extra.get("http_url", "http://127.0.0.1:8080").rstrip("/")
+        account = extra.get("account", "")
+        if not account:
+            return {"error": "Signal account not configured"}
+
+        params = {"account": account, "message": message}
+        if chat_id.startswith("group:"):
+            params["groupId"] = chat_id[6:]
+        else:
+            params["recipient"] = [chat_id]
+
+        payload = {
+            "jsonrpc": "2.0",
+            "method": "send",
+            "params": params,
+            "id": f"send_{int(time.time() * 1000)}",
+        }
+
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            resp = await client.post(f"{http_url}/api/v1/rpc", json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+            if "error" in data:
+                return {"error": f"Signal RPC error: {data['error']}"}
+            return {"success": True, "platform": "signal", "chat_id": chat_id}
+    except Exception as e:
+        return {"error": f"Signal send failed: {e}"}
+
+
 def _check_send_message():
     """Gate send_message on gateway running (always available on messaging platforms)."""
     platform = os.getenv("HERMES_SESSION_PLATFORM", "")

tools/skills_sync.py

@@ -69,10 +69,36 @@ def _read_manifest() -> Dict[str, str]:
 
 
 def _write_manifest(entries: Dict[str, str]):
-    """Write the manifest file in v2 format (name:hash)."""
+    """Write the manifest file atomically in v2 format (name:hash).
+
+    Uses a temp file + os.replace() to avoid corruption if the process
+    crashes or is interrupted mid-write.
+    """
+    import tempfile
+
     MANIFEST_FILE.parent.mkdir(parents=True, exist_ok=True)
-    lines = [f"{name}:{hash_val}" for name, hash_val in sorted(entries.items())]
-    MANIFEST_FILE.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    data = "\n".join(f"{name}:{hash_val}" for name, hash_val in sorted(entries.items())) + "\n"
+
+    try:
+        fd, tmp_path = tempfile.mkstemp(
+            dir=str(MANIFEST_FILE.parent),
+            prefix=".bundled_manifest_",
+            suffix=".tmp",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                f.write(data)
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp_path, MANIFEST_FILE)
+        except BaseException:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+    except Exception as e:
+        logger.debug("Failed to write skills manifest %s: %s", MANIFEST_FILE, e, exc_info=True)
 
 
 def _discover_bundled_skills(bundled_dir: Path) -> List[Tuple[str, Path]]:

website/docs/getting-started/learning-path.md

@@ -0,0 +1,150 @@
+---
+sidebar_position: 3
+title: 'Learning Path'
+description: 'Choose your learning path through the Hermes Agent documentation based on your experience level and goals.'
+---
+
+# Learning Path
+
+Hermes Agent can do a lot — CLI assistant, Telegram/Discord bot, task automation, RL training, and more. This page helps you figure out where to start and what to read based on your experience level and what you're trying to accomplish.
+
+:::tip Start Here
+If you haven't installed Hermes Agent yet, begin with the [Installation guide](/docs/getting-started/installation) and then run through the [Quickstart](/docs/getting-started/quickstart). Everything below assumes you have a working installation.
+:::
+
+## How to Use This Page
+
+- **Know your level?** Jump to the [experience-level table](#by-experience-level) and follow the reading order for your tier.
+- **Have a specific goal?** Skip to [By Use Case](#by-use-case) and find the scenario that matches.
+- **Just browsing?** Check the [Key Features](#key-features-at-a-glance) table for a quick overview of everything Hermes Agent can do.
+
+## By Experience Level
+
+| Level | Goal | Recommended Reading | Time Estimate |
+|---|---|---|---|
+| **Beginner** | Get up and running, have basic conversations, use built-in tools | [Installation](/docs/getting-started/installation) → [Quickstart](/docs/getting-started/quickstart) → [CLI Usage](/docs/user-guide/cli) → [Configuration](/docs/user-guide/configuration) | ~1 hour |
+| **Intermediate** | Set up messaging bots, use advanced features like memory, cron jobs, and skills | [Sessions](/docs/user-guide/sessions) → [Messaging](/docs/user-guide/messaging) → [Tools](/docs/user-guide/features/tools) → [Skills](/docs/user-guide/features/skills) → [Memory](/docs/user-guide/features/memory) → [Cron](/docs/user-guide/features/cron) | ~2–3 hours |
+| **Advanced** | Build custom tools, create skills, train models with RL, contribute to the project | [Architecture](/docs/developer-guide/architecture) → [Adding Tools](/docs/developer-guide/adding-tools) → [Creating Skills](/docs/developer-guide/creating-skills) → [RL Training](/docs/user-guide/features/rl-training) → [Contributing](/docs/developer-guide/contributing) | ~4–6 hours |
+
+## By Use Case
+
+Pick the scenario that matches what you want to do. Each one links you to the relevant docs in the order you should read them.
+
+### "I want a CLI coding assistant"
+
+Use Hermes Agent as an interactive terminal assistant for writing, reviewing, and running code.
+
+1. [Installation](/docs/getting-started/installation)
+2. [Quickstart](/docs/getting-started/quickstart)
+3. [CLI Usage](/docs/user-guide/cli)
+4. [Code Execution](/docs/user-guide/features/code-execution)
+5. [Context Files](/docs/user-guide/features/context-files)
+6. [Tips & Tricks](/docs/guides/tips)
+
+:::tip
+Pass files directly into your conversation with context files. Hermes Agent can read, edit, and run code in your projects.
+:::
+
+### "I want a Telegram/Discord bot"
+
+Deploy Hermes Agent as a bot on your favorite messaging platform.
+
+1. [Installation](/docs/getting-started/installation)
+2. [Configuration](/docs/user-guide/configuration)
+3. [Messaging Overview](/docs/user-guide/messaging)
+4. [Telegram Setup](/docs/user-guide/messaging/telegram)
+5. [Discord Setup](/docs/user-guide/messaging/discord)
+6. [Security](/docs/user-guide/security)
+
+For full project examples, see:
+- [Daily Briefing Bot](/docs/guides/daily-briefing-bot)
+- [Team Telegram Assistant](/docs/guides/team-telegram-assistant)
+
+### "I want to automate tasks"
+
+Schedule recurring tasks, run batch jobs, or chain agent actions together.
+
+1. [Quickstart](/docs/getting-started/quickstart)
+2. [Cron Scheduling](/docs/user-guide/features/cron)
+3. [Batch Processing](/docs/user-guide/features/batch-processing)
+4. [Delegation](/docs/user-guide/features/delegation)
+5. [Hooks](/docs/user-guide/features/hooks)
+
+:::tip
+Cron jobs let Hermes Agent run tasks on a schedule — daily summaries, periodic checks, automated reports — without you being present.
+:::
+
+### "I want to build custom tools/skills"
+
+Extend Hermes Agent with your own tools and reusable skill packages.
+
+1. [Tools Overview](/docs/user-guide/features/tools)
+2. [Skills Overview](/docs/user-guide/features/skills)
+3. [MCP (Model Context Protocol)](/docs/user-guide/features/mcp)
+4. [Architecture](/docs/developer-guide/architecture)
+5. [Adding Tools](/docs/developer-guide/adding-tools)
+6. [Creating Skills](/docs/developer-guide/creating-skills)
+
+:::tip
+Tools are individual functions the agent can call. Skills are bundles of tools, prompts, and configuration packaged together. Start with tools, graduate to skills.
+:::
+
+### "I want to train models"
+
+Use reinforcement learning to fine-tune model behavior with Hermes Agent's built-in RL training pipeline.
+
+1. [Quickstart](/docs/getting-started/quickstart)
+2. [Configuration](/docs/user-guide/configuration)
+3. [RL Training](/docs/user-guide/features/rl-training)
+4. [Provider Routing](/docs/user-guide/features/provider-routing)
+5. [Architecture](/docs/developer-guide/architecture)
+
+:::tip
+RL training works best when you already understand the basics of how Hermes Agent handles conversations and tool calls. Run through the Beginner path first if you're new.
+:::
+
+### "I want to use it as a Python library"
+
+Integrate Hermes Agent into your own Python applications programmatically.
+
+1. [Installation](/docs/getting-started/installation)
+2. [Quickstart](/docs/getting-started/quickstart)
+3. [Python Library Guide](/docs/guides/python-library)
+4. [Architecture](/docs/developer-guide/architecture)
+5. [Tools](/docs/user-guide/features/tools)
+6. [Sessions](/docs/user-guide/sessions)
+
+## Key Features at a Glance
+
+Not sure what's available? Here's a quick directory of major features:
+
+| Feature | What It Does | Link |
+|---|---|---|
+| **Tools** | Built-in tools the agent can call (file I/O, search, shell, etc.) | [Tools](/docs/user-guide/features/tools) |
+| **Skills** | Installable plugin packages that add new capabilities | [Skills](/docs/user-guide/features/skills) |
+| **Memory** | Persistent memory across sessions | [Memory](/docs/user-guide/features/memory) |
+| **Context Files** | Feed files and directories into conversations | [Context Files](/docs/user-guide/features/context-files) |
+| **MCP** | Connect to external tool servers via Model Context Protocol | [MCP](/docs/user-guide/features/mcp) |
+| **Cron** | Schedule recurring agent tasks | [Cron](/docs/user-guide/features/cron) |
+| **Delegation** | Spawn sub-agents for parallel work | [Delegation](/docs/user-guide/features/delegation) |
+| **Code Execution** | Run code in sandboxed environments | [Code Execution](/docs/user-guide/features/code-execution) |
+| **Browser** | Web browsing and scraping | [Browser](/docs/user-guide/features/browser) |
+| **Hooks** | Event-driven callbacks and middleware | [Hooks](/docs/user-guide/features/hooks) |
+| **Batch Processing** | Process multiple inputs in bulk | [Batch Processing](/docs/user-guide/features/batch-processing) |
+| **RL Training** | Fine-tune models with reinforcement learning | [RL Training](/docs/user-guide/features/rl-training) |
+| **Provider Routing** | Route requests across multiple LLM providers | [Provider Routing](/docs/user-guide/features/provider-routing) |
+
+## What to Read Next
+
+Based on where you are right now:
+
+- **Just finished installing?** → Head to the [Quickstart](/docs/getting-started/quickstart) to run your first conversation.
+- **Completed the Quickstart?** → Read [CLI Usage](/docs/user-guide/cli) and [Configuration](/docs/user-guide/configuration) to customize your setup.
+- **Comfortable with the basics?** → Explore [Tools](/docs/user-guide/features/tools), [Skills](/docs/user-guide/features/skills), and [Memory](/docs/user-guide/features/memory) to unlock the full power of the agent.
+- **Setting up for a team?** → Read [Security](/docs/user-guide/security) and [Sessions](/docs/user-guide/sessions) to understand access control and conversation management.
+- **Ready to build?** → Jump into the [Developer Guide](/docs/developer-guide/architecture) to understand the internals and start contributing.
+- **Want practical examples?** → Check out the [Guides](/docs/guides/tips) section for real-world projects and tips.
+
+:::tip
+You don't need to read everything. Pick the path that matches your goal, follow the links in order, and you'll be productive quickly. You can always come back to this page to find your next step.
+:::

website/docs/guides/_category_.json

@@ -0,0 +1,6 @@
+{
+  "label": "Guides & Tutorials",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false
+}

website/docs/guides/daily-briefing-bot.md

@@ -0,0 +1,263 @@
+---
+sidebar_position: 2
+title: "Tutorial: Daily Briefing Bot"
+description: "Build an automated daily briefing bot that researches topics, summarizes findings, and delivers them to Telegram or Discord every morning"
+---
+
+# Tutorial: Build a Daily Briefing Bot
+
+In this tutorial, you'll build a personal briefing bot that wakes up every morning, researches topics you care about, summarizes the findings, and delivers a concise briefing straight to your Telegram or Discord.
+
+By the end, you'll have a fully automated workflow combining **web search**, **cron scheduling**, **delegation**, and **messaging delivery** — no code required.
+
+## What We're Building
+
+Here's the flow:
+
+1. **8:00 AM** — The cron scheduler triggers your job
+2. **Hermes spins up** a fresh agent session with your prompt
+3. **Web search** pulls the latest news on your topics
+4. **Summarization** distills it into a clean briefing format
+5. **Delivery** sends the briefing to your Telegram or Discord
+
+The whole thing runs hands-free. You just read your briefing with your morning coffee.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **Hermes Agent installed** — see the [Installation guide](/docs/getting-started/installation)
+- **Gateway running** — the gateway daemon handles cron execution:
+  ```bash
+  hermes gateway install   # Install as system service (recommended)
+  # or
+  hermes gateway           # Run in foreground
+  ```
+- **Firecrawl API key** — set `FIRECRAWL_API_KEY` in your environment for web search
+- **Messaging configured** (optional but recommended) — [Telegram](/docs/user-guide/messaging/telegram) or Discord set up with a home channel
+
+:::tip No messaging? No problem
+You can still follow this tutorial using `deliver: "local"`. Briefings will be saved to `~/.hermes/cron/output/` and you can read them anytime.
+:::
+
+## Step 1: Test the Workflow Manually
+
+Before automating anything, let's make sure the briefing works. Start a chat session:
+
+```bash
+hermes
+```
+
+Then enter this prompt:
+
+```
+Search for the latest news about AI agents and open source LLMs.
+Summarize the top 3 stories in a concise briefing format with links.
+```
+
+Hermes will search the web, read through results, and produce something like:
+
+```
+☀️ Your AI Briefing — March 8, 2026
+
+1. Qwen 3 Released with 235B Parameters
+   Alibaba's latest open-weight model matches GPT-4.5 on several
+   benchmarks while remaining fully open source.
+   → https://qwenlm.github.io/blog/qwen3/
+
+2. LangChain Launches Agent Protocol Standard
+   A new open standard for agent-to-agent communication gains
+   adoption from 15 major frameworks in its first week.
+   → https://blog.langchain.dev/agent-protocol/
+
+3. EU AI Act Enforcement Begins for General-Purpose Models
+   The first compliance deadlines hit, with open source models
+   receiving exemptions under the 10M parameter threshold.
+   → https://artificialintelligenceact.eu/updates/
+
+---
+3 stories • Sources searched: 8 • Generated by Hermes Agent
+```
+
+If this works, you're ready to automate it.
+
+:::tip Iterate on the format
+Try different prompts until you get output you love. Add instructions like "use emoji headers" or "keep each summary under 2 sentences." Whatever you settle on goes into the cron job.
+:::
+
+## Step 2: Create the Cron Job
+
+Now let's schedule this to run automatically every morning. You can do this in two ways.
+
+### Option A: Natural Language (in chat)
+
+Just tell Hermes what you want:
+
+```
+Every morning at 8am, search the web for the latest news about AI agents
+and open source LLMs. Summarize the top 3 stories in a concise briefing
+with links. Use a friendly, professional tone. Deliver to telegram.
+```
+
+Hermes will create the cron job for you using the `schedule_cronjob` tool.
+
+### Option B: CLI Slash Command
+
+Use the `/cron` command for more control:
+
+```
+/cron add "0 8 * * *" "Search the web for the latest news about AI agents and open source LLMs. Find at least 5 recent articles from the past 24 hours. Summarize the top 3 most important stories in a concise daily briefing format. For each story include: a clear headline, a 2-sentence summary, and the source URL. Use a friendly, professional tone. Format with emoji bullet points and end with a total story count."
+```
+
+### The Golden Rule: Self-Contained Prompts
+
+:::warning Critical concept
+Cron jobs run in a **completely fresh session** — no memory of your previous conversations, no context about what you "set up earlier." Your prompt must contain **everything** the agent needs to do the job.
+:::
+
+**Bad prompt:**
+```
+Do my usual morning briefing.
+```
+
+**Good prompt:**
+```
+Search the web for the latest news about AI agents and open source LLMs.
+Find at least 5 recent articles from the past 24 hours. Summarize the
+top 3 most important stories in a concise daily briefing format. For each
+story include: a clear headline, a 2-sentence summary, and the source URL.
+Use a friendly, professional tone. Format with emoji bullet points.
+```
+
+The good prompt is specific about **what to search**, **how many articles**, **what format**, and **what tone**. It's everything the agent needs in one shot.
+
+## Step 3: Customize the Briefing
+
+Once the basic briefing works, you can get creative.
+
+### Multi-Topic Briefings
+
+Cover several areas in one briefing:
+
+```
+/cron add "0 8 * * *" "Create a morning briefing covering three topics. For each topic, search the web for recent news from the past 24 hours and summarize the top 2 stories with links.
+
+Topics:
+1. AI and machine learning — focus on open source models and agent frameworks
+2. Cryptocurrency — focus on Bitcoin, Ethereum, and regulatory news
+3. Space exploration — focus on SpaceX, NASA, and commercial space
+
+Format as a clean briefing with section headers and emoji. End with today's date and a motivational quote."
+```
+
+### Using Delegation for Parallel Research
+
+For faster briefings, tell Hermes to delegate each topic to a sub-agent:
+
+```
+/cron add "0 8 * * *" "Create a morning briefing by delegating research to sub-agents. Delegate three parallel tasks:
+
+1. Delegate: Search for the top 2 AI/ML news stories from the past 24 hours with links
+2. Delegate: Search for the top 2 cryptocurrency news stories from the past 24 hours with links
+3. Delegate: Search for the top 2 space exploration news stories from the past 24 hours with links
+
+Collect all results and combine them into a single clean briefing with section headers, emoji formatting, and source links. Add today's date as a header."
+```
+
+Each sub-agent searches independently and in parallel, then the main agent combines everything into one polished briefing. See the [Delegation docs](/docs/user-guide/features/delegation) for more on how this works.
+
+### Weekday-Only Schedule
+
+Don't need briefings on weekends? Use a cron expression that targets Monday–Friday:
+
+```
+/cron add "0 8 * * 1-5" "Search for the latest AI and tech news..."
+```
+
+### Twice-Daily Briefings
+
+Get a morning overview and an evening recap:
+
+```
+/cron add "0 8 * * *" "Morning briefing: search for AI news from the past 12 hours..."
+/cron add "0 18 * * *" "Evening recap: search for AI news from the past 12 hours..."
+```
+
+### Adding Personal Context with Memory
+
+If you have [memory](/docs/user-guide/features/memory) enabled, you can store preferences that persist across sessions. But remember — cron jobs run in fresh sessions without conversational memory. To add personal context, bake it directly into the prompt:
+
+```
+/cron add "0 8 * * *" "You are creating a briefing for a senior ML engineer who cares about: PyTorch ecosystem, transformer architectures, open-weight models, and AI regulation in the EU. Skip stories about product launches or funding rounds unless they involve open source.
+
+Search for the latest news on these topics. Summarize the top 3 stories with links. Be concise and technical — this reader doesn't need basic explanations."
+```
+
+:::tip Tailor the persona
+Including details about who the briefing is *for* dramatically improves relevance. Tell the agent your role, interests, and what to skip.
+:::
+
+## Step 4: Manage Your Jobs
+
+### List All Scheduled Jobs
+
+In chat:
+```
+/cron list
+```
+
+Or from the terminal:
+```bash
+hermes cron list
+```
+
+You'll see output like:
+
+```
+ID          | Name              | Schedule    | Next Run           | Deliver
+------------|-------------------|-------------|--------------------|--------
+a1b2c3d4    | Morning Briefing  | 0 8 * * *   | 2026-03-09 08:00   | telegram
+e5f6g7h8    | Evening Recap     | 0 18 * * *  | 2026-03-08 18:00   | telegram
+```
+
+### Remove a Job
+
+In chat:
+```
+/cron remove a1b2c3d4
+```
+
+Or ask conversationally:
+```
+Remove my morning briefing cron job.
+```
+
+Hermes will use `list_cronjobs` to find it and `remove_cronjob` to delete it.
+
+### Check Gateway Status
+
+Make sure the scheduler is actually running:
+
+```bash
+hermes cron status
+```
+
+If the gateway isn't running, your jobs won't execute. Install it as a system service for reliability:
+
+```bash
+hermes gateway install
+```
+
+## Going Further
+
+You've built a working daily briefing bot. Here are some directions to explore next:
+
+- **[Scheduled Tasks (Cron)](/docs/user-guide/features/cron)** — Full reference for schedule formats, repeat limits, and delivery options
+- **[Delegation](/docs/user-guide/features/delegation)** — Deep dive into parallel sub-agent workflows
+- **[Messaging Platforms](/docs/user-guide/messaging)** — Set up Telegram, Discord, or other delivery targets
+- **[Memory](/docs/user-guide/features/memory)** — Persistent context across sessions
+- **[Tips & Best Practices](/docs/guides/tips)** — More prompt engineering advice
+
+:::tip What else can you schedule?
+The briefing bot pattern works for anything: competitor monitoring, GitHub repo summaries, weather forecasts, portfolio tracking, server health checks, or even a daily joke. If you can describe it in a prompt, you can schedule it.
+:::

website/docs/guides/python-library.md

@@ -0,0 +1,340 @@
+---
+sidebar_position: 4
+title: "Using Hermes as a Python Library"
+description: "Embed AIAgent in your own Python scripts, web apps, or automation pipelines — no CLI required"
+---
+
+# Using Hermes as a Python Library
+
+Hermes isn't just a CLI tool. You can import `AIAgent` directly and use it programmatically in your own Python scripts, web applications, or automation pipelines. This guide shows you how.
+
+---
+
+## Installation
+
+Install Hermes directly from the repository:
+
+```bash
+pip install git+https://github.com/NousResearch/hermes-agent.git
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install git+https://github.com/NousResearch/hermes-agent.git
+```
+
+You can also pin it in your `requirements.txt`:
+
+```text
+hermes-agent @ git+https://github.com/NousResearch/hermes-agent.git
+```
+
+:::tip
+The same environment variables used by the CLI are required when using Hermes as a library. At minimum, set `OPENROUTER_API_KEY` (or `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` if using direct provider access).
+:::
+
+---
+
+## Basic Usage
+
+The simplest way to use Hermes is the `chat()` method — pass a message, get a string back:
+
+```python
+from run_agent import AIAgent
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+response = agent.chat("What is the capital of France?")
+print(response)
+```
+
+`chat()` handles the full conversation loop internally — tool calls, retries, everything — and returns just the final text response.
+
+:::warning
+Always set `quiet_mode=True` when embedding Hermes in your own code. Without it, the agent prints CLI spinners, progress indicators, and other terminal output that will clutter your application's output.
+:::
+
+---
+
+## Full Conversation Control
+
+For more control over the conversation, use `run_conversation()` directly. It returns a dictionary with the full response, message history, and metadata:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+
+result = agent.run_conversation(
+    user_message="Search for recent Python 3.13 features",
+    task_id="my-task-1",
+)
+
+print(result["final_response"])
+print(f"Messages exchanged: {len(result['messages'])}")
+```
+
+The returned dictionary contains:
+- **`final_response`** — The agent's final text reply
+- **`messages`** — The complete message history (system, user, assistant, tool calls)
+- **`task_id`** — The task identifier used for VM isolation
+
+You can also pass a custom system message that overrides the ephemeral system prompt for that call:
+
+```python
+result = agent.run_conversation(
+    user_message="Explain quicksort",
+    system_message="You are a computer science tutor. Use simple analogies.",
+)
+```
+
+---
+
+## Configuring Tools
+
+Control which toolsets the agent has access to using `enabled_toolsets` or `disabled_toolsets`:
+
+```python
+# Only enable web tools (browsing, search)
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    enabled_toolsets=["web"],
+    quiet_mode=True,
+)
+
+# Enable everything except terminal access
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    disabled_toolsets=["terminal"],
+    quiet_mode=True,
+)
+```
+
+:::tip
+Use `enabled_toolsets` when you want a minimal, locked-down agent (e.g., only web search for a research bot). Use `disabled_toolsets` when you want most capabilities but need to restrict specific ones (e.g., no terminal access in a shared environment).
+:::
+
+---
+
+## Multi-turn Conversations
+
+Maintain conversation state across multiple turns by passing the message history back in:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+)
+
+# First turn
+result1 = agent.run_conversation("My name is Alice")
+history = result1["messages"]
+
+# Second turn — agent remembers the context
+result2 = agent.run_conversation(
+    "What's my name?",
+    conversation_history=history,
+)
+print(result2["final_response"])  # "Your name is Alice."
+```
+
+The `conversation_history` parameter accepts the `messages` list from a previous result. The agent copies it internally, so your original list is never mutated.
+
+---
+
+## Saving Trajectories
+
+Enable trajectory saving to capture conversations in ShareGPT format — useful for generating training data or debugging:
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    save_trajectories=True,
+    quiet_mode=True,
+)
+
+agent.chat("Write a Python function to sort a list")
+# Saves to trajectory_samples.jsonl in ShareGPT format
+```
+
+Each conversation is appended as a single JSONL line, making it easy to collect datasets from automated runs.
+
+---
+
+## Custom System Prompts
+
+Use `ephemeral_system_prompt` to set a custom system prompt that guides the agent's behavior but is **not** saved to trajectory files (keeping your training data clean):
+
+```python
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    ephemeral_system_prompt="You are a SQL expert. Only answer database questions.",
+    quiet_mode=True,
+)
+
+response = agent.chat("How do I write a JOIN query?")
+print(response)
+```
+
+This is ideal for building specialized agents — a code reviewer, a documentation writer, a SQL assistant — all using the same underlying tooling.
+
+---
+
+## Batch Processing
+
+For running many prompts in parallel, Hermes includes `batch_runner.py`. It manages concurrent `AIAgent` instances with proper resource isolation:
+
+```bash
+python batch_runner.py --input prompts.jsonl --output results.jsonl
+```
+
+Each prompt gets its own `task_id` and isolated environment. If you need custom batch logic, you can build your own using `AIAgent` directly:
+
+```python
+import concurrent.futures
+from run_agent import AIAgent
+
+prompts = [
+    "Explain recursion",
+    "What is a hash table?",
+    "How does garbage collection work?",
+]
+
+def process_prompt(prompt):
+    # Create a fresh agent per task for thread safety
+    agent = AIAgent(
+        model="anthropic/claude-sonnet-4",
+        quiet_mode=True,
+        skip_memory=True,
+    )
+    return agent.chat(prompt)
+
+with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+    results = list(executor.map(process_prompt, prompts))
+
+for prompt, result in zip(prompts, results):
+    print(f"Q: {prompt}\nA: {result}\n")
+```
+
+:::warning
+Always create a **new `AIAgent` instance per thread or task**. The agent maintains internal state (conversation history, tool sessions, iteration counters) that is not thread-safe to share.
+:::
+
+---
+
+## Integration Examples
+
+### FastAPI Endpoint
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+from run_agent import AIAgent
+
+app = FastAPI()
+
+class ChatRequest(BaseModel):
+    message: str
+    model: str = "anthropic/claude-sonnet-4"
+
+@app.post("/chat")
+async def chat(request: ChatRequest):
+    agent = AIAgent(
+        model=request.model,
+        quiet_mode=True,
+        skip_context_files=True,
+        skip_memory=True,
+    )
+    response = agent.chat(request.message)
+    return {"response": response}
+```
+
+### Discord Bot
+
+```python
+import discord
+from run_agent import AIAgent
+
+client = discord.Client(intents=discord.Intents.default())
+
+@client.event
+async def on_message(message):
+    if message.author == client.user:
+        return
+    if message.content.startswith("!hermes "):
+        query = message.content[8:]
+        agent = AIAgent(
+            model="anthropic/claude-sonnet-4",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            platform="discord",
+        )
+        response = agent.chat(query)
+        await message.channel.send(response[:2000])
+
+client.run("YOUR_DISCORD_TOKEN")
+```
+
+### CI/CD Pipeline Step
+
+```python
+#!/usr/bin/env python3
+"""CI step: auto-review a PR diff."""
+import subprocess
+from run_agent import AIAgent
+
+diff = subprocess.check_output(["git", "diff", "main...HEAD"]).decode()
+
+agent = AIAgent(
+    model="anthropic/claude-sonnet-4",
+    quiet_mode=True,
+    skip_context_files=True,
+    skip_memory=True,
+    disabled_toolsets=["terminal", "browser"],
+)
+
+review = agent.chat(
+    f"Review this PR diff for bugs, security issues, and style problems:\n\n{diff}"
+)
+print(review)
+```
+
+---
+
+## Key Constructor Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model` | `str` | `"anthropic/claude-opus-4.6"` | Model in OpenRouter format |
+| `quiet_mode` | `bool` | `False` | Suppress CLI output |
+| `enabled_toolsets` | `List[str]` | `None` | Whitelist specific toolsets |
+| `disabled_toolsets` | `List[str]` | `None` | Blacklist specific toolsets |
+| `save_trajectories` | `bool` | `False` | Save conversations to JSONL |
+| `ephemeral_system_prompt` | `str` | `None` | Custom system prompt (not saved to trajectories) |
+| `max_iterations` | `int` | `90` | Max tool-calling iterations per conversation |
+| `skip_context_files` | `bool` | `False` | Skip loading AGENTS.md files |
+| `skip_memory` | `bool` | `False` | Disable persistent memory read/write |
+| `api_key` | `str` | `None` | API key (falls back to env vars) |
+| `base_url` | `str` | `None` | Custom API endpoint URL |
+| `platform` | `str` | `None` | Platform hint (`"discord"`, `"telegram"`, etc.) |
+
+---
+
+## Important Notes
+
+:::tip
+- Set **`skip_context_files=True`** if you don't want `AGENTS.md` files from the working directory loaded into the system prompt.
+- Set **`skip_memory=True`** to prevent the agent from reading or writing persistent memory — recommended for stateless API endpoints.
+- The `platform` parameter (e.g., `"discord"`, `"telegram"`) injects platform-specific formatting hints so the agent adapts its output style.
+:::
+
+:::warning
+- **Thread safety**: Create one `AIAgent` per thread or task. Never share an instance across concurrent calls.
+- **Resource cleanup**: The agent automatically cleans up resources (terminal sessions, browser instances) when a conversation ends. If you're running in a long-lived process, ensure each conversation completes normally.
+- **Iteration limits**: The default `max_iterations=90` is generous. For simple Q&A use cases, consider lowering it (e.g., `max_iterations=10`) to prevent runaway tool-calling loops and control costs.
+:::

website/docs/guides/team-telegram-assistant.md

@@ -0,0 +1,429 @@
+---
+sidebar_position: 3
+title: "Tutorial: Team Telegram Assistant"
+description: "Step-by-step guide to setting up a Telegram bot that your whole team can use for code help, research, system admin, and more"
+---
+
+# Set Up a Team Telegram Assistant
+
+This tutorial walks you through setting up a Telegram bot powered by Hermes Agent that multiple team members can use. By the end, your team will have a shared AI assistant they can message for help with code, research, system administration, and anything else — secured with per-user authorization.
+
+## What We're Building
+
+A Telegram bot that:
+
+- **Any authorized team member** can DM for help — code reviews, research, shell commands, debugging
+- **Runs on your server** with full tool access — terminal, file editing, web search, code execution
+- **Per-user sessions** — each person gets their own conversation context
+- **Secure by default** — only approved users can interact, with two authorization methods
+- **Scheduled tasks** — daily standups, health checks, and reminders delivered to a team channel
+
+---
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](/getting-started/learning-path) if you haven't yet.
+- **A Telegram account** for yourself (the bot owner)
+- **An LLM provider configured** — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env`
+
+:::tip
+A $5/month VPS is plenty for running the gateway. Hermes itself is lightweight — the LLM API calls are what cost money, and those happen remotely.
+:::
+
+---
+
+## Step 1: Create a Telegram Bot
+
+Every Telegram bot starts with **@BotFather** — Telegram's official bot for creating bots.
+
+1. **Open Telegram** and search for `@BotFather`, or go to [t.me/BotFather](https://t.me/BotFather)
+
+2. **Send `/newbot`** — BotFather will ask you two things:
+   - **Display name** — what users see (e.g., `Team Hermes Assistant`)
+   - **Username** — must end in `bot` (e.g., `myteam_hermes_bot`)
+
+3. **Copy the bot token** — BotFather replies with something like:
+   ```
+   Use this token to access the HTTP API:
+   7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+   ```
+   Save this token — you'll need it in the next step.
+
+4. **Set a description** (optional but recommended):
+   ```
+   /setdescription
+   ```
+   Choose your bot, then enter something like:
+   ```
+   Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
+   ```
+
+5. **Set bot commands** (optional — gives users a command menu):
+   ```
+   /setcommands
+   ```
+   Choose your bot, then paste:
+   ```
+   new - Start a fresh conversation
+   model - Show or change the AI model
+   status - Show session info
+   help - Show available commands
+   stop - Stop the current task
+   ```
+
+:::warning
+Keep your bot token secret. Anyone with the token can control the bot. If it leaks, use `/revoke` in BotFather to generate a new one.
+:::
+
+---
+
+## Step 2: Configure the Gateway
+
+You have two options: the interactive setup wizard (recommended) or manual configuration.
+
+### Option A: Interactive Setup (Recommended)
+
+```bash
+hermes gateway setup
+```
+
+This walks you through everything with arrow-key selection. Pick **Telegram**, paste your bot token, and enter your user ID when prompted.
+
+### Option B: Manual Configuration
+
+Add these lines to `~/.hermes/.env`:
+
+```bash
+# Telegram bot token from BotFather
+TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+
+# Your Telegram user ID (numeric)
+TELEGRAM_ALLOWED_USERS=123456789
+```
+
+### Finding Your User ID
+
+Your Telegram user ID is a numeric value (not your username). To find it:
+
+1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+2. It instantly replies with your numeric user ID
+3. Copy that number into `TELEGRAM_ALLOWED_USERS`
+
+:::info
+Telegram user IDs are permanent numbers like `123456789`. They're different from your `@username`, which can change. Always use the numeric ID for allowlists.
+:::
+
+---
+
+## Step 3: Start the Gateway
+
+### Quick Test
+
+Run the gateway in the foreground first to make sure everything works:
+
+```bash
+hermes gateway
+```
+
+You should see output like:
+
+```
+[Gateway] Starting Hermes Gateway...
+[Gateway] Telegram adapter connected
+[Gateway] Cron scheduler started (tick every 60s)
+```
+
+Open Telegram, find your bot, and send it a message. If it replies, you're in business. Press `Ctrl+C` to stop.
+
+### Production: Install as a Service
+
+For a persistent deployment that survives reboots:
+
+```bash
+hermes gateway install
+```
+
+This creates a **systemd** service (Linux) or **launchd** service (macOS) that runs automatically.
+
+```bash
+# Linux — manage the service
+hermes gateway start
+hermes gateway stop
+hermes gateway status
+
+# View live logs
+journalctl --user -u hermes-gateway -f
+
+# Keep running after SSH logout
+sudo loginctl enable-linger $USER
+```
+
+```bash
+# macOS — manage the service
+launchctl start ai.hermes.gateway
+launchctl stop ai.hermes.gateway
+tail -f ~/.hermes/logs/gateway.log
+```
+
+### Verify It's Running
+
+```bash
+hermes gateway status
+```
+
+Then send a test message to your bot on Telegram. You should get a response within a few seconds.
+
+---
+
+## Step 4: Set Up Team Access
+
+Now let's give your teammates access. There are two approaches.
+
+### Approach A: Static Allowlist
+
+Collect each team member's Telegram user ID (have them message [@userinfobot](https://t.me/userinfobot)) and add them as a comma-separated list:
+
+```bash
+# In ~/.hermes/.env
+TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
+```
+
+Restart the gateway after changes:
+
+```bash
+hermes gateway stop && hermes gateway start
+```
+
+### Approach B: DM Pairing (Recommended for Teams)
+
+DM pairing is more flexible — you don't need to collect user IDs upfront. Here's how it works:
+
+1. **Teammate DMs the bot** — since they're not on the allowlist, the bot replies with a one-time pairing code:
+   ```
+   🔐 Pairing code: XKGH5N7P
+   Send this code to the bot owner for approval.
+   ```
+
+2. **Teammate sends you the code** (via any channel — Slack, email, in person)
+
+3. **You approve it** on the server:
+   ```bash
+   hermes pairing approve telegram XKGH5N7P
+   ```
+
+4. **They're in** — the bot immediately starts responding to their messages
+
+**Managing paired users:**
+
+```bash
+# See all pending and approved users
+hermes pairing list
+
+# Revoke someone's access
+hermes pairing revoke telegram 987654321
+
+# Clear expired pending codes
+hermes pairing clear-pending
+```
+
+:::tip
+DM pairing is ideal for teams because you don't need to restart the gateway when adding new users. Approvals take effect immediately.
+:::
+
+### Security Considerations
+
+- **Never set `GATEWAY_ALLOW_ALL_USERS=true`** on a bot with terminal access — anyone who finds your bot could run commands on your server
+- Pairing codes expire after **1 hour** and use cryptographic randomness
+- Rate limiting prevents brute-force attacks: 1 request per user per 10 minutes, max 3 pending codes per platform
+- After 5 failed approval attempts, the platform enters a 1-hour lockout
+- All pairing data is stored with `chmod 0600` permissions
+
+---
+
+## Step 5: Configure the Bot
+
+### Set a Home Channel
+
+A **home channel** is where the bot delivers cron job results and proactive messages. Without one, scheduled tasks have nowhere to send output.
+
+**Option 1:** Use the `/sethome` command in any Telegram group or chat where the bot is a member.
+
+**Option 2:** Set it manually in `~/.hermes/.env`:
+
+```bash
+TELEGRAM_HOME_CHANNEL=-1001234567890
+TELEGRAM_HOME_CHANNEL_NAME="Team Updates"
+```
+
+To find a channel ID, add [@userinfobot](https://t.me/userinfobot) to the group — it will report the group's chat ID.
+
+### Configure Tool Progress Display
+
+Control how much detail the bot shows when using tools. In `~/.hermes/config.yaml`:
+
+```yaml
+display:
+  tool_progress: new    # off | new | all | verbose
+```
+
+| Mode | What You See |
+|------|-------------|
+| `off` | Clean responses only — no tool activity |
+| `new` | Brief status for each new tool call (recommended for messaging) |
+| `all` | Every tool call with details |
+| `verbose` | Full tool output including command results |
+
+Users can also change this per-session with the `/verbose` command in chat.
+
+### Set Up a Personality with SOUL.md
+
+Customize how the bot communicates by creating `~/.hermes/SOUL.md`:
+
+```markdown
+# Soul
+You are a helpful team assistant. Be concise and technical.
+Use code blocks for any code. Skip pleasantries — the team
+values directness. When debugging, always ask for error logs
+before guessing at solutions.
+```
+
+### Add Project Context
+
+If your team works on specific projects, create context files so the bot knows your stack:
+
+```markdown
+<!-- ~/.hermes/AGENTS.md -->
+# Team Context
+- We use Python 3.12 with FastAPI and SQLAlchemy
+- Frontend is React with TypeScript
+- CI/CD runs on GitHub Actions
+- Production deploys to AWS ECS
+- Always suggest writing tests for new code
+```
+
+:::info
+Context files are injected into every session's system prompt. Keep them concise — every character counts against your token budget.
+:::
+
+---
+
+## Step 6: Set Up Scheduled Tasks
+
+With the gateway running, you can schedule recurring tasks that deliver results to your team channel.
+
+### Daily Standup Summary
+
+Message the bot on Telegram:
+
+```
+Every weekday at 9am, check the GitHub repository at
+github.com/myorg/myproject for:
+1. Pull requests opened/merged in the last 24 hours
+2. Issues created or closed
+3. Any CI/CD failures on the main branch
+Format as a brief standup-style summary.
+```
+
+The agent creates a cron job automatically and delivers results to the chat where you asked (or the home channel).
+
+### Server Health Check
+
+```
+Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
+and Docker container status with 'docker ps'. Report anything unusual —
+partitions above 80%, containers that have restarted, or high memory usage.
+```
+
+### Managing Scheduled Tasks
+
+```bash
+# From the CLI
+hermes cron list          # View all scheduled jobs
+hermes cron status        # Check if scheduler is running
+
+# From Telegram chat
+/cron list                # View jobs
+/cron remove <job_id>     # Remove a job
+```
+
+:::warning
+Cron job prompts run in completely fresh sessions with no memory of prior conversations. Make sure each prompt contains **all** the context the agent needs — file paths, URLs, server addresses, and clear instructions.
+:::
+
+---
+
+## Production Tips
+
+### Use Docker for Safety
+
+On a shared team bot, use Docker as the terminal backend so agent commands run in a container instead of on your host:
+
+```bash
+# In ~/.hermes/.env
+TERMINAL_BACKEND=docker
+TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+```
+
+Or in `~/.hermes/config.yaml`:
+
+```yaml
+terminal:
+  backend: docker
+  container_cpu: 1
+  container_memory: 5120
+  container_persistent: true
+```
+
+This way, even if someone asks the bot to run something destructive, your host system is protected.
+
+### Monitor the Gateway
+
+```bash
+# Check if the gateway is running
+hermes gateway status
+
+# Watch live logs (Linux)
+journalctl --user -u hermes-gateway -f
+
+# Watch live logs (macOS)
+tail -f ~/.hermes/logs/gateway.log
+```
+
+### Keep Hermes Updated
+
+From Telegram, send `/update` to the bot — it will pull the latest version and restart. Or from the server:
+
+```bash
+hermes update
+hermes gateway stop && hermes gateway start
+```
+
+### Log Locations
+
+| What | Location |
+|------|----------|
+| Gateway logs | `journalctl --user -u hermes-gateway` (Linux) or `~/.hermes/logs/gateway.log` (macOS) |
+| Cron job output | `~/.hermes/cron/output/{job_id}/{timestamp}.md` |
+| Cron job definitions | `~/.hermes/cron/jobs.json` |
+| Pairing data | `~/.hermes/pairing/` |
+| Session history | `~/.hermes/sessions/` |
+
+---
+
+## Going Further
+
+You've got a working team Telegram assistant. Here are some next steps:
+
+- **[Security Guide](/user-guide/security)** — deep dive into authorization, container isolation, and command approval
+- **[Messaging Gateway](/user-guide/messaging)** — full reference for gateway architecture, session management, and chat commands
+- **[Telegram Setup](/user-guide/messaging/telegram)** — platform-specific details including voice messages and TTS
+- **[Scheduled Tasks](/user-guide/features/cron)** — advanced cron scheduling with delivery options and cron expressions
+- **[Context Files](/user-guide/features/context-files)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
+- **[Personality](/user-guide/features/personality)** — built-in personality presets and custom persona definitions
+- **Add more platforms** — the same gateway can simultaneously run [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), and [WhatsApp](/user-guide/messaging/whatsapp)
+
+---
+
+*Questions or issues? Open an issue on GitHub — contributions are welcome.*

website/docs/guides/tips.md

@@ -0,0 +1,211 @@
+---
+sidebar_position: 1
+title: "Tips & Best Practices"
+description: "Practical advice to get the most out of Hermes Agent — prompt tips, CLI shortcuts, context files, memory, cost optimization, and security"
+---
+
+# Tips & Best Practices
+
+A quick-wins collection of practical tips that make you immediately more effective with Hermes Agent. Each section targets a different aspect — scan the headers and jump to what's relevant.
+
+---
+
+## Getting the Best Results
+
+### Be Specific About What You Want
+
+Vague prompts produce vague results. Instead of "fix the code," say "fix the TypeError in `api/handlers.py` on line 47 — the `process_request()` function receives `None` from `parse_body()`." The more context you give, the fewer iterations you need.
+
+### Provide Context Up Front
+
+Front-load your request with the relevant details: file paths, error messages, expected behavior. One well-crafted message beats three rounds of clarification. Paste error tracebacks directly — the agent can parse them.
+
+### Use Context Files for Recurring Instructions
+
+If you find yourself repeating the same instructions ("use tabs not spaces," "we use pytest," "the API is at `/api/v2`"), put them in an `AGENTS.md` file. The agent reads it automatically every session — zero effort after setup.
+
+### Let the Agent Use Its Tools
+
+Don't try to hand-hold every step. Say "find and fix the failing test" rather than "open `tests/test_foo.py`, look at line 42, then..." The agent has file search, terminal access, and code execution — let it explore and iterate.
+
+### Use Skills for Complex Workflows
+
+Before writing a long prompt explaining how to do something, check if there's already a skill for it. Type `/skills` to browse available skills, or just invoke one directly like `/axolotl` or `/github-pr-workflow`.
+
+## CLI Power User Tips
+
+### Multi-Line Input
+
+Press **Alt+Enter** (or **Ctrl+J**) to insert a newline without sending. This lets you compose multi-line prompts, paste code blocks, or structure complex requests before hitting Enter to send.
+
+### Paste Detection
+
+The CLI auto-detects multi-line pastes. Just paste a code block or error traceback directly — it won't send each line as a separate message. The paste is buffered and sent as one message.
+
+### Interrupt and Redirect
+
+Press **Ctrl+C** once to interrupt the agent mid-response. You can then type a new message to redirect it. Double-press Ctrl+C within 2 seconds to force exit. This is invaluable when the agent starts going down the wrong path.
+
+### Resume Sessions with `-c`
+
+Forgot something from your last session? Run `hermes -c` to resume exactly where you left off, with full conversation history restored. You can also resume by title: `hermes -r "my research project"`.
+
+### Clipboard Image Paste
+
+Press **Ctrl+V** to paste an image from your clipboard directly into the chat. The agent uses vision to analyze screenshots, diagrams, error popups, or UI mockups — no need to save to a file first.
+
+### Slash Command Autocomplete
+
+Type `/` and press **Tab** to see all available commands. This includes built-in commands (`/compress`, `/model`, `/title`) and every installed skill. You don't need to memorize anything — Tab completion has you covered.
+
+:::tip
+Use `/verbose` to cycle through tool output display modes: **off → new → all → verbose**. The "all" mode is great for watching what the agent does; "off" is cleanest for simple Q&A.
+:::
+
+## Context Files
+
+### AGENTS.md: Your Project's Brain
+
+Create an `AGENTS.md` in your project root with architecture decisions, coding conventions, and project-specific instructions. This is automatically injected into every session, so the agent always knows your project's rules.
+
+```markdown
+# Project Context
+- This is a FastAPI backend with SQLAlchemy ORM
+- Always use async/await for database operations
+- Tests go in tests/ and use pytest-asyncio
+- Never commit .env files
+```
+
+### SOUL.md: Customize Personality
+
+Want the agent to be more concise? More technical? Place a `SOUL.md` in your project root or `~/.hermes/SOUL.md` for global personality customization. This shapes the agent's tone and communication style.
+
+```markdown
+# Soul
+You are a senior backend engineer. Be terse and direct.
+Skip explanations unless asked. Prefer one-liners over verbose solutions.
+Always consider error handling and edge cases.
+```
+
+### .cursorrules Compatibility
+
+Already have a `.cursorrules` or `.cursor/rules/*.mdc` file? Hermes reads those too. No need to duplicate your coding conventions — they're loaded automatically from the working directory.
+
+### Hierarchical Discovery
+
+Hermes walks the directory tree and discovers **all** `AGENTS.md` files at every level. In a monorepo, put project-wide conventions at the root and team-specific ones in subdirectories — they're all concatenated together with path headers.
+
+:::tip
+Keep context files focused and concise. Every character counts against your token budget since they're injected into every single message.
+:::
+
+## Memory & Skills
+
+### Memory vs. Skills: What Goes Where
+
+**Memory** is for facts: your environment, preferences, project locations, and things the agent has learned about you. **Skills** are for procedures: multi-step workflows, tool-specific instructions, and reusable recipes. Use memory for "what," skills for "how."
+
+### When to Create Skills
+
+If you find a task that takes 5+ steps and you'll do it again, ask the agent to create a skill for it. Say "save what you just did as a skill called `deploy-staging`." Next time, just type `/deploy-staging` and the agent loads the full procedure.
+
+### Managing Memory Capacity
+
+Memory is intentionally bounded (~2,200 chars for MEMORY.md, ~1,375 chars for USER.md). When it fills up, the agent consolidates entries. You can help by saying "clean up your memory" or "replace the old Python 3.9 note — we're on 3.12 now."
+
+### Let the Agent Remember
+
+After a productive session, say "remember this for next time" and the agent will save the key takeaways. You can also be specific: "save to memory that our CI uses GitHub Actions with the `deploy.yml` workflow."
+
+:::warning
+Memory is a frozen snapshot — changes made during a session don't appear in the system prompt until the next session starts. The agent writes to disk immediately, but the prompt cache isn't invalidated mid-session.
+:::
+
+## Performance & Cost
+
+### Don't Break the Prompt Cache
+
+Most LLM providers cache the system prompt prefix. If you keep your system prompt stable (same context files, same memory), subsequent messages in a session get **cache hits** that are significantly cheaper. Avoid changing the model or system prompt mid-session.
+
+### Use /compress Before Hitting Limits
+
+Long sessions accumulate tokens. When you notice responses slowing down or getting truncated, run `/compress`. This summarizes the conversation history, preserving key context while dramatically reducing token count. Use `/usage` to check where you stand.
+
+### Delegate for Parallel Work
+
+Need to research three topics at once? Ask the agent to use `delegate_task` with parallel subtasks. Each subagent runs independently with its own context, and only the final summaries come back — massively reducing your main conversation's token usage.
+
+### Use execute_code for Batch Operations
+
+Instead of running terminal commands one at a time, ask the agent to write a script that does everything at once. "Write a Python script to rename all `.jpeg` files to `.jpg` and run it" is cheaper and faster than renaming files individually.
+
+### Choose the Right Model
+
+Use `/model` to switch models mid-session. Use a frontier model (Claude Sonnet/Opus, GPT-4o) for complex reasoning and architecture decisions. Switch to a faster model for simple tasks like formatting, renaming, or boilerplate generation.
+
+:::tip
+Run `/usage` periodically to see your token consumption. Run `/insights` for a broader view of usage patterns over the last 30 days.
+:::
+
+## Messaging Tips
+
+### Set a Home Channel
+
+Use `/sethome` in your preferred Telegram or Discord chat to designate it as the home channel. Cron job results and scheduled task outputs are delivered here. Without it, the agent has nowhere to send proactive messages.
+
+### Use /title to Organize Sessions
+
+Name your sessions with `/title auth-refactor` or `/title research-llm-quantization`. Named sessions are easy to find with `hermes sessions list` and resume with `hermes -r "auth-refactor"`. Unnamed sessions pile up and become impossible to distinguish.
+
+### DM Pairing for Team Access
+
+Instead of manually collecting user IDs for allowlists, enable DM pairing. When a teammate DMs the bot, they get a one-time pairing code. You approve it with `hermes pairing approve telegram XKGH5N7P` — simple and secure.
+
+### Tool Progress Display Modes
+
+Use `/verbose` to control how much tool activity you see. In messaging platforms, less is usually more — keep it on "new" to see just new tool calls. In the CLI, "all" gives you a satisfying live view of everything the agent does.
+
+:::tip
+On messaging platforms, sessions auto-reset after idle time (default: 120 min) or daily at 4 AM. Adjust per-platform in `~/.hermes/gateway.json` if you need longer sessions.
+:::
+
+## Security
+
+### 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.
+
+```bash
+# In your .env:
+TERMINAL_BACKEND=docker
+TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest
+```
+
+### Review Before Choosing "Always"
+
+When the agent triggers a dangerous command approval (`rm -rf`, `DROP TABLE`, etc.), you get four options: **once**, **session**, **always**, **deny**. Think carefully before choosing "always" — it permanently allowlists that pattern. Start with "session" until you're comfortable.
+
+### Command Approval Is Your Safety Net
+
+Hermes checks every command against a curated list of dangerous patterns before execution. This includes recursive deletes, SQL drops, piping curl to shell, and more. Don't disable this in production — it exists for good reasons.
+
+:::warning
+When running in a container backend (Docker, Singularity, Modal, Daytona), dangerous command checks are **skipped** because the container is the security boundary. Make sure your container images are properly locked down.
+:::
+
+### Use Allowlists for Messaging Bots
+
+Never set `GATEWAY_ALLOW_ALL_USERS=true` on a bot with terminal access. Always use platform-specific allowlists (`TELEGRAM_ALLOWED_USERS`, `DISCORD_ALLOWED_USERS`) or DM pairing to control who can interact with your agent.
+
+```bash
+# Recommended: explicit allowlists per platform
+TELEGRAM_ALLOWED_USERS=123456789,987654321
+DISCORD_ALLOWED_USERS=123456789012345678
+
+# Or use cross-platform allowlist
+GATEWAY_ALLOWED_USERS=123456789,987654321
+```
+
+---
+
+*Have a tip that should be on this page? Open an issue or PR — community contributions are welcome.*

website/docs/index.md

@@ -25,6 +25,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 |---|---|
 | 🚀 **[Installation](/docs/getting-started/installation)** | Install in 60 seconds on Linux, macOS, or WSL2 |
 | 📖 **[Quickstart Tutorial](/docs/getting-started/quickstart)** | Your first conversation and key features to try |
+| 🗺️ **[Learning Path](/docs/getting-started/learning-path)** | Find the right docs for your experience level |
 | ⚙️ **[Configuration](/docs/user-guide/configuration)** | Config file, providers, models, and options |
 | 💬 **[Messaging Gateway](/docs/user-guide/messaging)** | Set up Telegram, Discord, Slack, or WhatsApp |
 | 🔧 **[Tools & Toolsets](/docs/user-guide/features/tools)** | 40+ built-in tools and how to configure them |
@@ -33,8 +34,9 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 | 🔌 **[MCP Integration](/docs/user-guide/features/mcp)** | Connect to any MCP server for extended capabilities |
 | 📄 **[Context Files](/docs/user-guide/features/context-files)** | Project context files that shape every conversation |
 | 🔒 **[Security](/docs/user-guide/security)** | Command approval, authorization, container isolation |
+| 💡 **[Tips & Best Practices](/docs/guides/tips)** | Quick wins to get the most out of Hermes |
 | 🏗️ **[Architecture](/docs/developer-guide/architecture)** | How it works under the hood |
-| 🤝 **[Contributing](/docs/developer-guide/contributing)** | Development setup and PR process |
+| ❓ **[FAQ & Troubleshooting](/docs/reference/faq)** | Common questions and solutions |
 
 ## Key Features
 

website/docs/reference/environment-variables.md

@@ -107,6 +107,10 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
 | `WHATSAPP_ENABLED` | Enable WhatsApp bridge (`true`/`false`) |
 | `WHATSAPP_MODE` | `bot` (separate number) or `self-chat` (message yourself) |
 | `WHATSAPP_ALLOWED_USERS` | Comma-separated phone numbers (with country code) |
+| `SIGNAL_HTTP_URL` | signal-cli daemon HTTP endpoint (e.g., `http://127.0.0.1:8080`) |
+| `SIGNAL_ACCOUNT` | Bot phone number in E.164 format (e.g., `+15551234567`) |
+| `SIGNAL_ALLOWED_USERS` | Comma-separated E.164 phone numbers or UUIDs |
+| `SIGNAL_GROUP_ALLOWED_USERS` | Comma-separated group IDs, or `*` for all groups (omit to disable groups) |
 | `MESSAGING_CWD` | Working directory for terminal in messaging (default: `~`) |
 | `GATEWAY_ALLOWED_USERS` | Comma-separated user IDs allowed across all platforms |
 | `GATEWAY_ALLOW_ALL_USERS` | Allow all users without allowlist (`true`/`false`, default: `false`) |

website/docs/reference/faq.md

@@ -0,0 +1,430 @@
+---
+sidebar_position: 3
+title: "FAQ & Troubleshooting"
+description: "Frequently asked questions and solutions to common issues with Hermes Agent"
+---
+
+# FAQ & Troubleshooting
+
+Quick answers and fixes for the most common questions and issues.
+
+---
+
+## Frequently Asked Questions
+
+### What LLM providers work with Hermes?
+
+Hermes Agent works with any OpenAI-compatible API. Supported providers include:
+
+- **[OpenRouter](https://openrouter.ai/)** — access hundreds of models through one API key (recommended for flexibility)
+- **Nous Portal** — Nous Research's own inference endpoint
+- **OpenAI** — GPT-4o, o1, o3, etc.
+- **Anthropic** — Claude models (via OpenRouter or compatible proxy)
+- **Google** — Gemini models (via OpenRouter or compatible proxy)
+- **z.ai / ZhipuAI** — GLM models
+- **Kimi / Moonshot AI** — Kimi models
+- **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.
+
+### Does it work on Windows?
+
+**Not natively.** Hermes Agent requires a Unix-like environment. On Windows, install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run Hermes from inside it. The standard install command works perfectly in WSL2:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
+```
+
+### Is my data sent anywhere?
+
+API calls go **only to the LLM provider you configure** (e.g., OpenRouter, your local Ollama instance). Hermes Agent does not collect telemetry, usage data, or analytics. Your conversations, memory, and skills are stored locally in `~/.hermes/`.
+
+### Can I use it offline / with local models?
+
+Yes. Point Hermes at any local OpenAI-compatible server:
+
+```bash
+hermes config set OPENAI_BASE_URL http://localhost:11434/v1  # Ollama
+hermes config set OPENAI_API_KEY ollama                       # Any non-empty value
+hermes config set HERMES_MODEL llama3.1
+```
+
+This works with Ollama, vLLM, llama.cpp server, SGLang, LocalAI, and others. See the [Configuration guide](../user-guide/configuration.md) for details.
+
+### How much does it cost?
+
+Hermes Agent itself is **free and open-source** (MIT license). You pay only for the LLM API usage from your chosen provider. Local models are completely free to run.
+
+### Can multiple people use one instance?
+
+Yes. The [messaging gateway](../user-guide/messaging/index.md) lets multiple users interact with the same Hermes Agent instance via Telegram, Discord, Slack, WhatsApp, or Home Assistant. Access is controlled through allowlists (specific user IDs) and DM pairing (first user to message claims access).
+
+### What's the difference between memory and skills?
+
+- **Memory** stores **facts** — things the agent knows about you, your projects, and preferences. Memories are retrieved automatically based on relevance.
+- **Skills** store **procedures** — step-by-step instructions for how to do things. Skills are recalled when the agent encounters a similar task.
+
+Both persist across sessions. See [Memory](../user-guide/features/memory.md) and [Skills](../user-guide/features/skills.md) for details.
+
+### Can I use it in my own Python project?
+
+Yes. Import the `AIAgent` class and use Hermes programmatically:
+
+```python
+from hermes.agent import AIAgent
+
+agent = AIAgent(model="openrouter/nous/hermes-3-llama-3.1-70b")
+response = await agent.chat("Explain quantum computing briefly")
+```
+
+See the [Python Library guide](../user-guide/features/code-execution.md) for full API usage.
+
+---
+
+## Troubleshooting
+
+### Installation Issues
+
+#### `hermes: command not found` after installation
+
+**Cause:** Your shell hasn't reloaded the updated PATH.
+
+**Solution:**
+```bash
+# Reload your shell profile
+source ~/.bashrc    # bash
+source ~/.zshrc     # zsh
+
+# Or start a new terminal session
+```
+
+If it still doesn't work, verify the install location:
+```bash
+which hermes
+ls ~/.local/bin/hermes
+```
+
+:::tip
+The installer adds `~/.local/bin` to your PATH. If you use a non-standard shell config, add `export PATH="$HOME/.local/bin:$PATH"` manually.
+:::
+
+#### Python version too old
+
+**Cause:** Hermes requires Python 3.11 or newer.
+
+**Solution:**
+```bash
+python3 --version   # Check current version
+
+# Install a newer Python
+sudo apt install python3.12   # Ubuntu/Debian
+brew install python@3.12      # macOS
+```
+
+The installer handles this automatically — if you see this error during manual installation, upgrade Python first.
+
+#### `uv: command not found`
+
+**Cause:** The `uv` package manager isn't installed or not in PATH.
+
+**Solution:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+```
+
+#### Permission denied errors during install
+
+**Cause:** Insufficient permissions to write to the install directory.
+
+**Solution:**
+```bash
+# Don't use sudo with the installer — it installs to ~/.local/bin
+# If you previously installed with sudo, clean up:
+sudo rm /usr/local/bin/hermes
+# Then re-run the standard installer
+curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
+```
+
+---
+
+### Provider & Model Issues
+
+#### API key not working
+
+**Cause:** Key is missing, expired, incorrectly set, or for the wrong provider.
+
+**Solution:**
+```bash
+# Check which keys are set
+hermes config get OPENROUTER_API_KEY
+
+# Re-run interactive setup
+hermes setup
+
+# Or set directly
+hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
+```
+
+:::warning
+Make sure the key matches the provider. An OpenAI key won't work with OpenRouter and vice versa. Check `~/.hermes/.env` for conflicting entries.
+:::
+
+#### Model not available / model not found
+
+**Cause:** The model identifier is incorrect or not available on your provider.
+
+**Solution:**
+```bash
+# List available models for your provider
+hermes models
+
+# Set a valid model
+hermes config set HERMES_MODEL openrouter/nous/hermes-3-llama-3.1-70b
+
+# Or specify per-session
+hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct
+```
+
+#### Rate limiting (429 errors)
+
+**Cause:** You've exceeded your provider's rate limits.
+
+**Solution:** Wait a moment and retry. For sustained usage, consider:
+- Upgrading your provider plan
+- Switching to a different model or provider
+- Using `hermes chat --provider <alternative>` to route to a different backend
+
+#### Context length exceeded
+
+**Cause:** The conversation has grown too long for the model's context window.
+
+**Solution:**
+```bash
+# Compress the current session
+/compress
+
+# Or start a fresh session
+hermes chat
+
+# Use a model with a larger context window
+hermes chat --model openrouter/google/gemini-2.0-flash-001
+```
+
+---
+
+### Terminal Issues
+
+#### Command blocked as dangerous
+
+**Cause:** Hermes detected a potentially destructive command (e.g., `rm -rf`, `DROP TABLE`). This is a safety feature.
+
+**Solution:** When prompted, review the command and type `y` to approve it. You can also:
+- Ask the agent to use a safer alternative
+- See the full list of dangerous patterns in the [Security docs](../user-guide/security.md)
+
+:::tip
+This is working as intended — Hermes never silently runs destructive commands. The approval prompt shows you exactly what will execute.
+:::
+
+#### `sudo` not working via messaging gateway
+
+**Cause:** The messaging gateway runs without an interactive terminal, so `sudo` cannot prompt for a password.
+
+**Solution:**
+- Avoid `sudo` in messaging — ask the agent to find alternatives
+- If you must use `sudo`, configure passwordless sudo for specific commands in `/etc/sudoers`
+- Or switch to the terminal interface for administrative tasks: `hermes chat`
+
+#### Docker backend not connecting
+
+**Cause:** Docker daemon isn't running or the user lacks permissions.
+
+**Solution:**
+```bash
+# Check Docker is running
+docker info
+
+# Add your user to the docker group
+sudo usermod -aG docker $USER
+newgrp docker
+
+# Verify
+docker run hello-world
+```
+
+---
+
+### Messaging Issues
+
+#### Bot not responding to messages
+
+**Cause:** The bot isn't running, isn't authorized, or your user isn't in the allowlist.
+
+**Solution:**
+```bash
+# Check if the gateway is running
+hermes gateway status
+
+# Start the gateway
+hermes gateway start
+
+# Check logs for errors
+hermes gateway logs
+```
+
+#### Messages not delivering
+
+**Cause:** Network issues, bot token expired, or platform webhook misconfiguration.
+
+**Solution:**
+- Verify your bot token is valid with `hermes setup`
+- Check gateway logs: `hermes gateway logs`
+- For webhook-based platforms (Slack, WhatsApp), ensure your server is publicly accessible
+
+#### Allowlist confusion — who can talk to the bot?
+
+**Cause:** Authorization mode determines who gets access.
+
+**Solution:**
+
+| Mode | How it works |
+|------|-------------|
+| **Allowlist** | Only user IDs listed in config can interact |
+| **DM pairing** | First user to message in DM claims exclusive access |
+| **Open** | Anyone can interact (not recommended for production) |
+
+Configure in `~/.hermes/config.yaml` under your gateway's settings. See the [Messaging docs](../user-guide/messaging/index.md).
+
+#### Gateway won't start
+
+**Cause:** Missing dependencies, port conflicts, or misconfigured tokens.
+
+**Solution:**
+```bash
+# Install messaging dependencies
+pip install hermes-agent[telegram]   # or [discord], [slack], [whatsapp]
+
+# Check for port conflicts
+lsof -i :8080
+
+# Verify configuration
+hermes config show
+```
+
+---
+
+### Performance Issues
+
+#### Slow responses
+
+**Cause:** Large model, distant API server, or heavy system prompt with many tools.
+
+**Solution:**
+- Try a faster/smaller model: `hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct`
+- Reduce active toolsets: `hermes chat -t "terminal"`
+- Check your network latency to the provider
+- For local models, ensure you have enough GPU VRAM
+
+#### High token usage
+
+**Cause:** Long conversations, verbose system prompts, or many tool calls accumulating context.
+
+**Solution:**
+```bash
+# Compress the conversation to reduce tokens
+/compress
+
+# Check session token count
+/stats
+```
+
+:::tip
+Use `/compress` regularly during long sessions. It summarizes the conversation history and reduces token usage significantly while preserving context.
+:::
+
+#### Session getting too long
+
+**Cause:** Extended conversations accumulate messages and tool outputs, approaching context limits.
+
+**Solution:**
+```bash
+# Compress current session (preserves key context)
+/compress
+
+# Start a new session with a reference to the old one
+hermes chat
+
+# Resume a specific session later if needed
+hermes chat --continue
+```
+
+---
+
+### MCP Issues
+
+#### MCP server not connecting
+
+**Cause:** Server binary not found, wrong command path, or missing runtime.
+
+**Solution:**
+```bash
+# Ensure MCP dependencies are installed
+pip install hermes-agent[mcp]
+
+# For npm-based servers, ensure Node.js is available
+node --version
+npx --version
+
+# Test the server manually
+npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Verify your `~/.hermes/config.yaml` MCP configuration:
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]
+```
+
+#### Tools not showing up from MCP server
+
+**Cause:** Server started but tool discovery failed, or tools are filtered out.
+
+**Solution:**
+- Check gateway/agent logs for MCP connection errors
+- Ensure the server responds to the `tools/list` RPC method
+- Restart the agent — MCP tools are discovered at startup
+
+```bash
+# Verify MCP servers are configured
+hermes config show | grep -A 5 mcp_servers
+
+# Restart hermes to re-discover tools
+hermes chat
+```
+
+#### MCP timeout errors
+
+**Cause:** The MCP server is taking too long to respond, or it crashed during execution.
+
+**Solution:**
+- Increase the timeout in your MCP server config if supported
+- Check if the MCP server process is still running
+- For remote HTTP MCP servers, check network connectivity
+
+:::warning
+If an MCP server crashes mid-request, Hermes will report a timeout. Check the server's own logs (not just Hermes logs) to diagnose the root cause.
+:::
+
+---
+
+## Still Stuck?
+
+If your issue isn't covered here:
+
+1. **Search existing issues:** [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
+2. **Ask the community:** [Nous Research Discord](https://discord.gg/nousresearch)
+3. **File a bug report:** Include your OS, Python version (`python3 --version`), Hermes version (`hermes --version`), and the full error message

website/docs/user-guide/configuration.md

@@ -581,6 +581,7 @@ display:
   personality: "kawaii"  # Default personality for the CLI
   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)
 ```
 
 | Mode | What you see |
@@ -620,6 +621,16 @@ code_execution:
   max_tool_calls: 50           # Max tool calls within code execution
 ```
 
+## Browser
+
+Configure browser automation behavior:
+
+```yaml
+browser:
+  inactivity_timeout: 120        # Seconds before auto-closing idle sessions
+  record_sessions: false         # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/
+```
+
 ## Delegation
 
 Configure subagent behavior for the delegate tool:

website/docs/user-guide/features/browser.md

@@ -142,6 +142,16 @@ What does the chart on this page show?
 
 Screenshots are stored in `~/.hermes/browser_screenshots/` and automatically cleaned up after 24 hours.
 
+### `browser_console`
+
+Get browser console output (log/warn/error messages) and uncaught JavaScript exceptions from the current page. Essential for detecting silent JS errors that don't appear in the accessibility tree.
+
+```
+Check the browser console for any JavaScript errors
+```
+
+Use `clear=True` to clear the console after reading, so subsequent calls only show new messages.
+
 ### `browser_close`
 
 Close the browser session and release resources. Call this when done to free up Browserbase session quota.
@@ -175,6 +185,17 @@ Agent workflow:
 4. browser_close()
 ```
 
+## Session Recording
+
+Automatically record browser sessions as WebM video files:
+
+```yaml
+browser:
+  record_sessions: true  # default: false
+```
+
+When enabled, recording starts automatically on the first `browser_navigate` and saves to `~/.hermes/browser_recordings/` when the session closes. Works in both local and cloud (Browserbase) modes. Recordings older than 72 hours are automatically cleaned up.
+
 ## Stealth Features
 
 Browserbase provides automatic stealth capabilities:

website/docs/user-guide/features/tools.md

@@ -15,7 +15,7 @@ Tools are functions that extend the agent's capabilities. They're organized into
 | **Web** | `web_search`, `web_extract` | Search the web, extract page content |
 | **Terminal** | `terminal`, `process` | Execute commands (local/docker/singularity/modal/daytona/ssh backends), manage background processes |
 | **File** | `read_file`, `write_file`, `patch`, `search_files` | Read, write, edit, and search files |
-| **Browser** | `browser_navigate`, `browser_click`, `browser_type`, etc. | Full browser automation via Browserbase |
+| **Browser** | `browser_navigate`, `browser_click`, `browser_type`, `browser_console`, etc. | Full browser automation via Browserbase |
 | **Vision** | `vision_analyze` | Image analysis via multimodal models |
 | **Image Gen** | `image_generate` | Generate images (FLUX via FAL) |
 | **TTS** | `text_to_speech` | Text-to-speech (Edge TTS / ElevenLabs / OpenAI) |

website/docs/user-guide/messaging/discord.md

@@ -6,52 +6,255 @@ description: "Set up Hermes Agent as a Discord bot"
 
 # Discord Setup
 
-Connect Hermes Agent to Discord to chat with it in DMs or server channels.
+Hermes Agent integrates with Discord as a bot, letting you chat with your AI assistant through direct messages or server channels. The bot receives your messages, processes them through the Hermes Agent pipeline (including tool use, memory, and reasoning), and responds in real time. It supports text, voice messages, file attachments, and slash commands.
 
-## Setup Steps
+This guide walks you through the full setup process — from creating your bot on Discord's Developer Portal to sending your first message.
 
-1. **Create a bot:** Go to the [Discord Developer Portal](https://discord.com/developers/applications)
-2. **Enable intents:** Bot → Privileged Gateway Intents → enable **Message Content Intent**
-3. **Get your user ID:** Enable Developer Mode in Discord settings, right-click your name → Copy ID
-4. **Invite to your server:** OAuth2 → URL Generator → scopes: `bot`, `applications.commands` → permissions: Send Messages, Read Message History, Attach Files
-5. **Configure:** Run `hermes gateway setup` and select Discord, or add to `~/.hermes/.env` manually:
+## Step 1: Create a Discord Application
 
-```bash
-DISCORD_BOT_TOKEN=MTIz...
-DISCORD_ALLOWED_USERS=YOUR_USER_ID
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and sign in with your Discord account.
+2. Click **New Application** in the top-right corner.
+3. Enter a name for your application (e.g., "Hermes Agent") and accept the Developer Terms of Service.
+4. Click **Create**.
+
+You'll land on the **General Information** page. Note the **Application ID** — you'll need it later to build the invite URL.
+
+## Step 2: Create the Bot
+
+1. In the left sidebar, click **Bot**.
+2. Discord automatically creates a bot user for your application. You'll see the bot's username, which you can customize.
+3. Under **Authorization Flow**:
+   - Set **Public Bot** to **OFF** — this prevents other people from inviting your bot to their servers.
+   - Leave **Require OAuth2 Code Grant** set to **OFF**.
+
+:::tip
+You can set a custom avatar and banner for your bot on this page. This is what users will see in Discord.
+:::
+
+## Step 3: Enable Privileged Gateway Intents
+
+This is the most critical step in the entire setup. Without the correct intents enabled, your bot will connect to Discord but **will not be able to read message content**.
+
+On the **Bot** page, scroll down to **Privileged Gateway Intents**. You'll see three toggles:
+
+| Intent | Purpose | Required? |
+|--------|---------|-----------|
+| **Presence Intent** | See user online/offline status | Optional |
+| **Server Members Intent** | Access the member list | Optional |
+| **Message Content Intent** | Read the text content of messages | **Required** |
+
+**Enable Message Content Intent** by toggling it **ON**. Without this, your bot receives message events but the message text is empty — the bot literally cannot see what you typed.
+
+:::warning[This is the #1 reason Discord bots don't work]
+If your bot is online but never responds to messages, the **Message Content Intent** is almost certainly disabled. Go back to the [Developer Portal](https://discord.com/developers/applications), select your application → Bot → Privileged Gateway Intents, and make sure **Message Content Intent** is toggled ON. Click **Save Changes**.
+:::
+
+**Regarding server count:**
+- If your bot is in **fewer than 100 servers**, you can simply toggle intents on and off freely.
+- If your bot is in **100 or more servers**, Discord requires you to submit a verification application to use privileged intents. For personal use, this is not a concern.
+
+Click **Save Changes** at the bottom of the page.
+
+## Step 4: Get the Bot Token
+
+The bot token is the credential Hermes Agent uses to log in as your bot. Still on the **Bot** page:
+
+1. Under the **Token** section, click **Reset Token**.
+2. If you have two-factor authentication enabled on your Discord account, enter your 2FA code.
+3. Discord will display your new token. **Copy it immediately.**
+
+:::warning[Token shown only once]
+The token is only displayed once. If you lose it, you'll need to reset it and generate a new one. Never share your token publicly or commit it to Git — anyone with this token has full control of your bot.
+:::
+
+Store the token somewhere safe (a password manager, for example). You'll need it in Step 8.
+
+## Step 5: Generate the Invite URL
+
+You need an OAuth2 URL to invite the bot to your server. There are two ways to do this:
+
+### Option A: Using the Installation Tab (Recommended)
+
+1. In the left sidebar, click **Installation**.
+2. Under **Installation Contexts**, enable **Guild Install**.
+3. For **Install Link**, select **Discord Provided Link**.
+4. Under **Default Install Settings** for Guild Install:
+   - **Scopes**: select `bot` and `applications.commands`
+   - **Permissions**: select the permissions listed below.
+
+### Option B: Manual URL
+
+You can construct the invite URL directly using this format:
+
+```
+https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912
 ```
 
-6. **Start the gateway:**
+Replace `YOUR_APP_ID` with the Application ID from Step 1.
+
+### Required Permissions
+
+These are the minimum permissions your bot needs:
+
+- **View Channels** — see the channels it has access to
+- **Send Messages** — respond to your messages
+- **Embed Links** — format rich responses
+- **Attach Files** — send images, audio, and file outputs
+- **Read Message History** — maintain conversation context
+
+### Recommended Additional Permissions
+
+- **Send Messages in Threads** — respond in thread conversations
+- **Add Reactions** — react to messages for acknowledgment
+
+### Permission Integers
+
+| Level | Permissions Integer | What's Included |
+|-------|-------------------|-----------------|
+| Minimal | `117760` | View Channels, Send Messages, Read Message History, Attach Files |
+| Recommended | `274878286912` | All of the above plus Embed Links, Send Messages in Threads, Add Reactions |
+
+## Step 6: Invite to Your Server
+
+1. Open the invite URL in your browser (from the Installation tab or the manual URL you constructed).
+2. In the **Add to Server** dropdown, select your server.
+3. Click **Continue**, then **Authorize**.
+4. Complete the CAPTCHA if prompted.
+
+:::info
+You need the **Manage Server** permission on the Discord server to invite a bot. If you don't see your server in the dropdown, ask a server admin to use the invite link instead.
+:::
+
+After authorizing, the bot will appear in your server's member list (it will show as offline until you start the Hermes gateway).
+
+## Step 7: Find Your Discord User ID
+
+Hermes Agent uses your Discord User ID to control who can interact with the bot. To find it:
+
+1. Open Discord (desktop or web app).
+2. Go to **Settings** → **Advanced** → toggle **Developer Mode** to **ON**.
+3. Close settings.
+4. Right-click your own username (in a message, the member list, or your profile) → **Copy User ID**.
+
+Your User ID is a long number like `284102345871466496`.
+
+:::tip
+Developer Mode also lets you copy **Channel IDs** and **Server IDs** the same way — right-click the channel or server name and select Copy ID. You'll need a Channel ID if you want to set a home channel manually.
+:::
+
+## Step 8: Configure Hermes Agent
+
+### Option A: Interactive Setup (Recommended)
+
+Run the guided setup command:
+
+```bash
+hermes gateway setup
+```
+
+Select **Discord** when prompted, then paste your bot token and user ID when asked.
+
+### Option B: Manual Configuration
+
+Add the following to your `~/.hermes/.env` file:
+
+```bash
+# Required
+DISCORD_BOT_TOKEN=your-bot-token-from-developer-portal
+DISCORD_ALLOWED_USERS=284102345871466496
+
+# Multiple allowed users (comma-separated)
+# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543
+```
+
+### Start the Gateway
+
+Once configured, start the Discord gateway:
 
 ```bash
 hermes gateway
 ```
 
-## Optional: Home Channel
+The bot should come online in Discord within a few seconds. Send it a message — either a DM or in a channel it can see — to test.
 
-Set a default channel for cron job delivery:
+:::tip
+You can run `hermes gateway` in the background or as a systemd service for persistent operation. See the deployment docs for details.
+:::
+
+## Home Channel
+
+You can designate a "home channel" where the bot sends proactive messages (such as cron job output, reminders, and notifications). There are two ways to set it:
+
+### Using the Slash Command
+
+Type `/sethome` in any Discord channel where the bot is present. That channel becomes the home channel.
+
+### Manual Configuration
+
+Add these to your `~/.hermes/.env`:
 
 ```bash
 DISCORD_HOME_CHANNEL=123456789012345678
 DISCORD_HOME_CHANNEL_NAME="#bot-updates"
 ```
 
-Or use `/sethome` in any Discord channel.
+Replace the ID with the actual channel ID (right-click → Copy Channel ID with Developer Mode on).
 
-## Required Bot Permissions
+## Bot Behavior
 
-When generating the invite URL, make sure to include:
-
-- **Send Messages** — bot needs to reply
-- **Read Message History** — for context
-- **Attach Files** — for audio, images, and file outputs
+- **Server channels**: The bot responds to all messages from allowed users in channels it can access. It does **not** require a mention or prefix — any message from an allowed user is treated as a prompt.
+- **Direct messages**: DMs always work, even without the Message Content Intent enabled (Discord exempts DMs from this requirement). However, you should still enable the intent for server channel support.
+- **Conversations**: Each channel or DM maintains its own conversation context.
 
 ## Voice Messages
 
-Voice messages on Discord are automatically transcribed (requires `VOICE_TOOLS_OPENAI_KEY`). TTS audio is sent as MP3 file attachments.
+Hermes Agent supports Discord voice messages:
+
+- **Incoming voice messages** are automatically transcribed using Whisper (requires `VOICE_TOOLS_OPENAI_KEY` to be set in your environment).
+- **Text-to-speech**: When TTS is enabled, the bot can send spoken responses as MP3 file attachments.
+
+## Troubleshooting
+
+### Bot is online but not responding to messages
+
+**Cause**: Message Content Intent is disabled.
+
+**Fix**: Go to [Developer Portal](https://discord.com/developers/applications) → your app → Bot → Privileged Gateway Intents → enable **Message Content Intent** → Save Changes. Restart the gateway.
+
+### "Disallowed Intents" error on startup
+
+**Cause**: Your code requests intents that aren't enabled in the Developer Portal.
+
+**Fix**: Enable all three Privileged Gateway Intents (Presence, Server Members, Message Content) in the Bot settings, then restart.
+
+### Bot can't see messages in a specific channel
+
+**Cause**: The bot's role doesn't have permission to view that channel.
+
+**Fix**: In Discord, go to the channel's settings → Permissions → add the bot's role with **View Channel** and **Read Message History** enabled.
+
+### 403 Forbidden errors
+
+**Cause**: The bot is missing required permissions.
+
+**Fix**: Re-invite the bot with the correct permissions using the URL from Step 5, or manually adjust the bot's role permissions in Server Settings → Roles.
+
+### Bot is offline
+
+**Cause**: The Hermes gateway isn't running, or the token is incorrect.
+
+**Fix**: Check that `hermes gateway` is running. Verify `DISCORD_BOT_TOKEN` in your `.env` file. If you recently reset the token, update it.
+
+### "User not allowed" / Bot ignores you
+
+**Cause**: Your User ID isn't in `DISCORD_ALLOWED_USERS`.
+
+**Fix**: Add your User ID to `DISCORD_ALLOWED_USERS` in `~/.hermes/.env` and restart the gateway.
 
 ## Security
 
 :::warning
-Always set `DISCORD_ALLOWED_USERS` to restrict who can use the bot. Without it, the gateway denies all users by default.
+Always set `DISCORD_ALLOWED_USERS` to restrict who can interact with the bot. Without it, the gateway denies all users by default as a safety measure. Only add User IDs of people you trust — authorized users have full access to the agent's capabilities, including tool use and system access.
 :::
+
+For more information on securing your Hermes Agent deployment, see the [Security Guide](../security.md).

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, or WhatsApp — architecture and setup overview"
+description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal — architecture and setup overview"
 ---
 
 # Messaging Gateway
 
-Chat with Hermes from Telegram, Discord, Slack, or WhatsApp. 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, 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.
 
 ## Architecture
 
@@ -15,12 +15,12 @@ Chat with Hermes from Telegram, Discord, Slack, or WhatsApp. The gateway is a si
 │                      Hermes Gateway                             │
 ├─────────────────────────────────────────────────────────────────┤
 │                                                                 │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
-│  │ Telegram │ │ Discord  │ │ WhatsApp │ │  Slack   │           │
-│  │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │           │
-│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘           │
-│       │             │            │             │                │
-│       └─────────────┼────────────┼─────────────┘                │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
+│  │ Telegram │ │ Discord  │ │ WhatsApp │ │  Slack   │ │ Signal │ │
+│  │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter  │ │ Adapter│ │
+│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
+│       │             │            │             │           │      │
+│       └─────────────┼────────────┼─────────────┼───────────┘      │
 │                           │                                     │
 │                  ┌────────▼────────┐                            │
 │                  │  Session Store  │                            │
@@ -114,6 +114,7 @@ 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
 
 # Or allow specific users across all platforms (comma-separated user IDs):
 GATEWAY_ALLOWED_USERS=123456789,987654321
@@ -200,6 +201,7 @@ Each platform has its own toolset:
 | Discord | `hermes-discord` | Full tools including terminal |
 | WhatsApp | `hermes-whatsapp` | Full tools including terminal |
 | Slack | `hermes-slack` | Full tools including terminal |
+| Signal | `hermes-signal` | Full tools including terminal |
 
 ## Next Steps
 
@@ -207,3 +209,4 @@ Each platform has its own toolset:
 - [Discord Setup](discord.md)
 - [Slack Setup](slack.md)
 - [WhatsApp Setup](whatsapp.md)
+- [Signal Setup](signal.md)

website/docs/user-guide/messaging/signal.md

@@ -0,0 +1,223 @@
+---
+sidebar_position: 6
+title: "Signal"
+description: "Set up Hermes Agent as a Signal messenger bot via signal-cli daemon"
+---
+
+# Signal Setup
+
+Hermes connects to Signal through the [signal-cli](https://github.com/AsamK/signal-cli) daemon running in HTTP mode. The adapter streams messages in real-time via SSE (Server-Sent Events) and sends responses via JSON-RPC.
+
+Signal is the most privacy-focused mainstream messenger — end-to-end encrypted by default, open-source protocol, minimal metadata collection. This makes it ideal for security-sensitive agent workflows.
+
+:::info No New Python Dependencies
+The Signal adapter uses `httpx` (already a core Hermes dependency) for all communication. No additional Python packages are required. You just need signal-cli installed externally.
+:::
+
+---
+
+## Prerequisites
+
+- **signal-cli** — Java-based Signal client ([GitHub](https://github.com/AsamK/signal-cli))
+- **Java 17+** runtime — required by signal-cli
+- **A phone number** with Signal installed (for linking as a secondary device)
+
+### Installing signal-cli
+
+```bash
+# Linux (Debian/Ubuntu)
+sudo apt install signal-cli
+
+# macOS
+brew install signal-cli
+
+# Manual install (any platform)
+# Download from https://github.com/AsamK/signal-cli/releases
+# Extract and add to PATH
+```
+
+### Alternative: Docker (signal-cli-rest-api)
+
+If you prefer Docker, use the [signal-cli-rest-api](https://github.com/bbernhard/signal-cli-rest-api) container:
+
+```bash
+docker run -d --name signal-cli \
+  -p 8080:8080 \
+  -v $HOME/.local/share/signal-cli:/home/.local/share/signal-cli \
+  -e MODE=json-rpc \
+  bbernhard/signal-cli-rest-api
+```
+
+:::tip
+Use `MODE=json-rpc` for best performance. The `normal` mode spawns a JVM per request and is much slower.
+:::
+
+---
+
+## Step 1: Link Your Signal Account
+
+Signal-cli works as a **linked device** — like WhatsApp Web, but for Signal. Your phone stays the primary device.
+
+```bash
+# Generate a linking URI (displays a QR code or link)
+signal-cli link -n "HermesAgent"
+```
+
+1. Open **Signal** on your phone
+2. Go to **Settings → Linked Devices**
+3. Tap **Link New Device**
+4. Scan the QR code or enter the URI
+
+---
+
+## Step 2: Start the signal-cli Daemon
+
+```bash
+# Replace +1234567890 with your Signal phone number (E.164 format)
+signal-cli --account +1234567890 daemon --http 127.0.0.1:8080
+```
+
+:::tip
+Keep this running in the background. You can use `systemd`, `tmux`, `screen`, or run it as a service.
+:::
+
+Verify it's running:
+
+```bash
+curl http://127.0.0.1:8080/api/v1/check
+# Should return: {"versions":{"signal-cli":...}}
+```
+
+---
+
+## Step 3: Configure Hermes
+
+The easiest way:
+
+```bash
+hermes gateway setup
+```
+
+Select **Signal** from the platform menu. The wizard will:
+
+1. Check if signal-cli is installed
+2. Prompt for the HTTP URL (default: `http://127.0.0.1:8080`)
+3. Test connectivity to the daemon
+4. Ask for your account phone number
+5. Configure allowed users and access policies
+
+### Manual Configuration
+
+Add to `~/.hermes/.env`:
+
+```bash
+# Required
+SIGNAL_HTTP_URL=http://127.0.0.1:8080
+SIGNAL_ACCOUNT=+1234567890
+
+# Security (recommended)
+SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # Comma-separated E.164 numbers or UUIDs
+
+# Optional
+SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # Enable groups (omit to disable, * for all)
+SIGNAL_HOME_CHANNEL=+1234567890                  # Default delivery target for cron jobs
+```
+
+Then start the gateway:
+
+```bash
+hermes gateway              # Foreground
+hermes gateway install      # Install as a system service
+```
+
+---
+
+## Access Control
+
+### DM Access
+
+DM access follows the same pattern as all other Hermes platforms:
+
+1. **`SIGNAL_ALLOWED_USERS` set** → only those users can message
+2. **No allowlist set** → unknown users get a DM pairing code (approve via `hermes pairing approve signal CODE`)
+3. **`SIGNAL_ALLOW_ALL_USERS=true`** → anyone can message (use with caution)
+
+### Group Access
+
+Group access is controlled by the `SIGNAL_GROUP_ALLOWED_USERS` env var:
+
+| Configuration | Behavior |
+|---------------|----------|
+| Not set (default) | All group messages are ignored. The bot only responds to DMs. |
+| Set with group IDs | Only listed groups are monitored (e.g., `groupId1,groupId2`). |
+| Set to `*` | The bot responds in any group it's a member of. |
+
+---
+
+## Features
+
+### Attachments
+
+The adapter supports sending and receiving:
+
+- **Images** — PNG, JPEG, GIF, WebP (auto-detected via magic bytes)
+- **Audio** — MP3, OGG, WAV, M4A (voice messages transcribed if Whisper is configured)
+- **Documents** — PDF, ZIP, and other file types
+
+Attachment size limit: **100 MB**.
+
+### Typing Indicators
+
+The bot sends typing indicators while processing messages, refreshing every 8 seconds.
+
+### Phone Number Redaction
+
+All phone numbers are automatically redacted in logs:
+- `+15551234567` → `+155****4567`
+- This applies to both Hermes gateway logs and the global redaction system
+
+### Health Monitoring
+
+The adapter monitors the SSE connection and automatically reconnects if:
+- The connection drops (with exponential backoff: 2s → 60s)
+- No activity is detected for 120 seconds (pings signal-cli to verify)
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"Cannot reach signal-cli"** during setup | Ensure signal-cli daemon is running: `signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080` |
+| **Messages not received** | Check that `SIGNAL_ALLOWED_USERS` includes the sender's number in E.164 format (with `+` prefix) |
+| **"signal-cli not found on PATH"** | Install signal-cli and ensure it's in your PATH, or use Docker |
+| **Connection keeps dropping** | Check signal-cli logs for errors. Ensure Java 17+ is installed. |
+| **Group messages ignored** | `SIGNAL_GROUP_POLICY` defaults to `disabled`. Set to `allowlist` or `open`. |
+| **Bot responds to everyone** | Set `SIGNAL_DM_POLICY=pairing` or `allowlist` and configure `SIGNAL_ALLOWED_USERS` |
+| **Duplicate messages** | Ensure only one signal-cli instance is listening on your phone number |
+
+---
+
+## Security
+
+:::warning
+**Always configure access controls.** The bot has terminal access by default. Without `SIGNAL_ALLOWED_USERS` or DM pairing, the gateway denies all incoming messages as a safety measure.
+:::
+
+- Phone numbers are redacted in all log output
+- Use `SIGNAL_DM_POLICY=pairing` (default) for safe onboarding of new users
+- Keep groups disabled unless you specifically need group support
+- Signal's end-to-end encryption protects message content in transit
+- The signal-cli session data in `~/.local/share/signal-cli/` contains account credentials — protect it like a password
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SIGNAL_HTTP_URL` | Yes | — | signal-cli HTTP endpoint |
+| `SIGNAL_ACCOUNT` | Yes | — | Bot phone number (E.164) |
+| `SIGNAL_ALLOWED_USERS` | No | — | Comma-separated phone numbers/UUIDs |
+| `SIGNAL_GROUP_ALLOWED_USERS` | No | — | Group IDs to monitor, or `*` for all (omit to disable groups) |
+| `SIGNAL_HOME_CHANNEL` | No | — | Default delivery target for cron jobs |

website/docs/user-guide/messaging/slack.md

@@ -1,57 +1,214 @@
 ---
 sidebar_position: 4
 title: "Slack"
-description: "Set up Hermes Agent as a Slack bot"
+description: "Set up Hermes Agent as a Slack bot using Socket Mode"
 ---
 
 # Slack Setup
 
-Connect Hermes Agent to Slack using Socket Mode for real-time communication.
+Connect Hermes Agent to Slack as a bot using Socket Mode. Socket Mode uses WebSockets instead of
+public HTTP endpoints, so your Hermes instance doesn't need to be publicly accessible — it works
+behind firewalls, on your laptop, or on a private server.
 
-## Setup Steps
+:::warning Classic Slack Apps Deprecated
+Classic Slack apps (using RTM API) were **fully deprecated in March 2025**. Hermes uses the modern
+Bolt SDK with Socket Mode. If you have an old classic app, you must create a new one following
+the steps below.
+:::
 
-1. **Create an app:** Go to [Slack API](https://api.slack.com/apps), create a new app
-2. **Enable Socket Mode:** In app settings → Socket Mode → Enable
-3. **Get tokens:**
-   - Bot Token (`xoxb-...`): OAuth & Permissions → Install to Workspace
-   - App Token (`xapp-...`): Basic Information → App-Level Tokens → Generate (with `connections:write` scope)
-4. **Configure:** Run `hermes gateway setup` and select Slack, or add to `~/.hermes/.env` manually:
+## Overview
+
+| Component | Value |
+|-----------|-------|
+| **Library** | `@slack/bolt` (Socket Mode) |
+| **Connection** | WebSocket — no public URL required |
+| **Auth tokens needed** | Bot Token (`xoxb-`) + App-Level Token (`xapp-`) |
+| **User identification** | Slack Member IDs (e.g., `U01ABC2DEF3`) |
+
+---
+
+## Step 1: Create a Slack App
+
+1. Go to [https://api.slack.com/apps](https://api.slack.com/apps)
+2. Click **Create New App**
+3. Choose **From scratch**
+4. Enter an app name (e.g., "Hermes Agent") and select your workspace
+5. Click **Create App**
+
+You'll land on the app's **Basic Information** page.
+
+---
+
+## Step 2: Configure Bot Token Scopes
+
+Navigate to **Features → OAuth & Permissions** in the sidebar. Scroll to **Scopes → Bot Token Scopes** and add the following:
+
+| Scope | Purpose |
+|-------|---------|
+| `chat:write` | Send messages as the bot |
+| `app_mentions:read` | Respond when @mentioned in channels |
+| `channels:history` | Read messages in public channels the bot is in |
+| `channels:read` | List and get info about public channels |
+| `im:history` | Read direct message history |
+| `im:read` | View basic DM info |
+| `im:write` | Open and manage DMs |
+| `users:read` | Look up user information |
+
+**Optional scopes:**
+
+| Scope | Purpose |
+|-------|---------|
+| `groups:history` | Read messages in private channels the bot is invited to |
+| `files:write` | Upload files (audio, images) |
+
+---
+
+## Step 3: Enable Socket Mode
+
+Socket Mode lets the bot connect via WebSocket instead of requiring a public URL.
+
+1. In the sidebar, go to **Settings → Socket Mode**
+2. Toggle **Enable Socket Mode** to ON
+3. You'll be prompted to create an **App-Level Token**:
+   - Name it something like `hermes-socket` (the name doesn't matter)
+   - Add the **`connections:write`** scope
+   - Click **Generate**
+4. **Copy the token** — it starts with `xapp-`. This is your `SLACK_APP_TOKEN`
+
+:::tip
+You can always find or regenerate app-level tokens under **Settings → Basic Information → App-Level Tokens**.
+:::
+
+---
+
+## Step 4: Subscribe to Events
+
+1. In the sidebar, go to **Features → Event Subscriptions**
+2. Toggle **Enable Events** to ON
+3. Expand **Subscribe to bot events** and add:
+
+| Event | Purpose |
+|-------|---------|
+| `app_mention` | Bot responds when @mentioned in any channel |
+| `message.im` | Bot responds to direct messages |
+
+**Optional event:**
+
+| Event | Purpose |
+|-------|---------|
+| `message.channels` | Bot sees all messages in public channels it's added to |
+
+4. Click **Save Changes** at the bottom of the page
+
+---
+
+## Step 5: Install App to Workspace
+
+1. In the sidebar, go to **Settings → Install App**
+2. Click **Install to Workspace**
+3. Review the permissions and click **Allow**
+4. After authorization, you'll see a **Bot User OAuth Token** starting with `xoxb-`
+5. **Copy this token** — this is your `SLACK_BOT_TOKEN`
+
+:::tip
+If you change scopes later, you'll need to **reinstall the app** for the new scopes to take effect.
+The Install App page will show a banner prompting you to do so.
+:::
+
+---
+
+## Step 6: Find User IDs for the Allowlist
+
+Hermes uses Slack **Member IDs** (not usernames or display names) for the allowlist.
+
+To find a Member ID:
+
+1. In Slack, click on the user's name or avatar
+2. Click **View full profile**
+3. Click the **⋮** (more) button
+4. Select **Copy member ID**
+
+Member IDs look like `U01ABC2DEF3`. You need your own Member ID at minimum.
+
+---
+
+## Step 7: Configure Hermes
+
+Add the following to your `~/.hermes/.env` file:
 
 ```bash
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_APP_TOKEN=xapp-...
-SLACK_ALLOWED_USERS=U01234ABCDE    # Comma-separated Slack user IDs
+# Required
+SLACK_BOT_TOKEN=xoxb-your-bot-token-here
+SLACK_APP_TOKEN=xapp-your-app-level-token-here
+SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs
+
+# Optional
+SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
 ```
 
-5. **Start the gateway:**
+Or run the interactive setup:
 
 ```bash
-hermes gateway
+hermes gateway setup    # Select Slack when prompted
 ```
 
-## Optional: Home Channel
+Then start the gateway:
 
-Set a default channel for cron job delivery:
+```bash
+hermes gateway              # Foreground
+hermes gateway install      # Install as a system service
+```
+
+---
+
+## Home Channel
+
+Set `SLACK_HOME_CHANNEL` to a channel ID where Hermes will deliver scheduled messages,
+cron job results, and other proactive notifications. To find a channel ID:
+
+1. Right-click the channel name in Slack
+2. Click **View channel details**
+3. Scroll to the bottom — the Channel ID is shown there
 
 ```bash
 SLACK_HOME_CHANNEL=C01234567890
 ```
 
-## Required Bot Scopes
+Make sure the bot has been **invited to the channel** (`/invite @Hermes Agent`).
 
-Make sure your Slack app has these OAuth scopes:
-
-- `chat:write` — Send messages
-- `channels:history` — Read channel messages
-- `im:history` — Read DM messages
-- `files:write` — Upload files (audio, images)
+---
 
 ## Voice Messages
 
-Voice messages on Slack are automatically transcribed (requires `VOICE_TOOLS_OPENAI_KEY`). TTS audio is sent as file attachments.
+Hermes supports voice on Slack:
+
+- **Incoming:** Voice/audio messages are automatically transcribed using Whisper (requires `VOICE_TOOLS_OPENAI_KEY`)
+- **Outgoing:** TTS responses are sent as audio file attachments
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Bot doesn't respond to DMs | Verify `message.im` is in your event subscriptions and the app is reinstalled |
+| Bot doesn't respond to @mentions | Verify `app_mention` is in your event subscriptions |
+| "not_authed" or "invalid_auth" errors | Regenerate your Bot Token and App Token, update `.env` |
+| Bot responds but can't post in a channel | Invite the bot to the channel with `/invite @Hermes Agent` |
+| "missing_scope" error | Add the required scope in OAuth & Permissions, then **reinstall** the app |
+| Socket disconnects frequently | Check your network; Bolt auto-reconnects but unstable connections cause lag |
+
+---
 
 ## Security
 
 :::warning
-Always set `SLACK_ALLOWED_USERS` to restrict who can use the bot. Without it, the gateway denies all users by default.
+**Always set `SLACK_ALLOWED_USERS`** with the Member IDs of authorized users. Without this setting,
+the gateway will **deny all messages** by default as a safety measure. Never share your bot tokens —
+treat them like passwords.
 :::
+
+- Tokens should be stored in `~/.hermes/.env` (file permissions `600`)
+- Rotate tokens periodically via the Slack app settings
+- Audit who has access to your Hermes config directory
+- Socket Mode means no public endpoint is exposed — one less attack surface

website/docs/user-guide/messaging/telegram.md

@@ -1,51 +1,144 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 title: "Telegram"
 description: "Set up Hermes Agent as a Telegram bot"
 ---
 
 # Telegram Setup
 
-Connect Hermes Agent to Telegram so you can chat from your phone, send voice memos, and receive scheduled task results.
+Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats. The integration is built on [python-telegram-bot](https://python-telegram-bot.org/) and supports text, voice, images, and file attachments.
 
-## Setup Steps
+## Step 1: Create a Bot via BotFather
 
-1. **Create a bot:** Message [@BotFather](https://t.me/BotFather) on Telegram, use `/newbot`
-2. **Get your user ID:** Message [@userinfobot](https://t.me/userinfobot) — it replies with your numeric ID
-3. **Configure:** Run `hermes gateway setup` and select Telegram, or add to `~/.hermes/.env` manually:
+Every Telegram bot requires an API token issued by [@BotFather](https://t.me/BotFather), Telegram's official bot management tool.
 
-```bash
-TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
-TELEGRAM_ALLOWED_USERS=YOUR_USER_ID    # Comma-separated for multiple users
+1. Open Telegram and search for **@BotFather**, or visit [t.me/BotFather](https://t.me/BotFather)
+2. Send `/newbot`
+3. Choose a **display name** (e.g., "Hermes Agent") — this can be anything
+4. Choose a **username** — this must be unique and end in `bot` (e.g., `my_hermes_bot`)
+5. BotFather replies with your **API token**. It looks like this:
+
+```
+123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
 ```
 
-4. **Start the gateway:**
+:::warning
+Keep your bot token secret. Anyone with this token can control your bot. If it leaks, revoke it immediately via `/revoke` in BotFather.
+:::
+
+## Step 2: Customize Your Bot (Optional)
+
+These BotFather commands improve the user experience. Message @BotFather and use:
+
+| Command | Purpose |
+|---------|---------|
+| `/setdescription` | The "What can this bot do?" text shown before a user starts chatting |
+| `/setabouttext` | Short text on the bot's profile page |
+| `/setuserpic` | Upload an avatar for your bot |
+| `/setcommands` | Define the command menu (the `/` button in chat) |
+| `/setprivacy` | Control whether the bot sees all group messages (see Step 3) |
+
+:::tip
+For `/setcommands`, a useful starting set:
+
+```
+help - Show help information
+new - Start a new conversation
+sethome - Set this chat as the home channel
+```
+:::
+
+## Step 3: Privacy Mode (Critical for Groups)
+
+Telegram bots have a **privacy mode** that is **enabled by default**. This is the single most common source of confusion when using bots in groups.
+
+**With privacy mode ON**, your bot can only see:
+- Messages that start with a `/` command
+- Replies directly to the bot's own messages
+- Service messages (member joins/leaves, pinned messages, etc.)
+- Messages in channels where the bot is an admin
+
+**With privacy mode OFF**, the bot receives every message in the group.
+
+### How to disable privacy mode
+
+1. Message **@BotFather**
+2. Send `/mybots`
+3. Select your bot
+4. Go to **Bot Settings → Group Privacy → Turn off**
+
+:::warning
+**You must remove and re-add the bot to any group** after changing the privacy setting. Telegram caches the privacy state when a bot joins a group, and it will not update until the bot is removed and re-added.
+:::
+
+:::tip
+An alternative to disabling privacy mode: promote the bot to **group admin**. Admin bots always receive all messages regardless of the privacy setting, and this avoids needing to toggle the global privacy mode.
+:::
+
+## Step 4: Find Your User ID
+
+Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is **not** your username — it's a number like `123456789`.
+
+**Method 1 (recommended):** Message [@userinfobot](https://t.me/userinfobot) — it instantly replies with your user ID.
+
+**Method 2:** Message [@get_id_bot](https://t.me/get_id_bot) — another reliable option.
+
+Save this number; you'll need it for the next step.
+
+## Step 5: Configure Hermes
+
+### Option A: Interactive Setup (Recommended)
+
+```bash
+hermes gateway setup
+```
+
+Select **Telegram** when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.
+
+### Option B: Manual Configuration
+
+Add the following to `~/.hermes/.env`:
+
+```bash
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
+TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users
+```
+
+### Start the Gateway
 
 ```bash
 hermes gateway
 ```
 
-## Optional: Home Channel
+The bot should come online within seconds. Send it a message on Telegram to verify.
 
-Set a home channel for cron job delivery:
+## Home Channel
+
+Use the `/sethome` command in any Telegram chat (DM or group) to designate it as the **home channel**. Scheduled tasks (cron jobs) deliver their results to this channel.
+
+You can also set it manually in `~/.hermes/.env`:
 
 ```bash
 TELEGRAM_HOME_CHANNEL=-1001234567890
 TELEGRAM_HOME_CHANNEL_NAME="My Notes"
 ```
 
-Or use the `/sethome` command in any Telegram chat to set it dynamically.
+:::tip
+Group chat IDs are negative numbers (e.g., `-1001234567890`). Your personal DM chat ID is the same as your user ID.
+:::
 
 ## Voice Messages
 
-Voice messages sent on Telegram are automatically transcribed using OpenAI's Whisper API and injected as text into the conversation. Requires `VOICE_TOOLS_OPENAI_KEY` in `~/.hermes/.env`.
+### Incoming Voice (Speech-to-Text)
 
-### Voice Bubbles (TTS)
+Voice messages you send on Telegram are automatically transcribed using OpenAI's Whisper API and injected as text into the conversation. This requires `VOICE_TOOLS_OPENAI_KEY` in `~/.hermes/.env`.
 
-When the agent generates audio via text-to-speech, it's delivered as native Telegram voice bubbles (the round, inline-playable kind).
+### Outgoing Voice (Text-to-Speech)
+
+When the agent generates audio via TTS, it's delivered as native Telegram **voice bubbles** — the round, inline-playable kind.
 
 - **OpenAI and ElevenLabs** produce Opus natively — no extra setup needed
-- **Edge TTS** (the default free provider) outputs MP3 and needs **ffmpeg** to convert to Opus:
+- **Edge TTS** (the default free provider) outputs MP3 and requires **ffmpeg** to convert to Opus:
 
 ```bash
 # Ubuntu/Debian
@@ -55,7 +148,34 @@ sudo apt install ffmpeg
 brew install ffmpeg
 ```
 
-Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but rectangular player instead of voice bubble).
+Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but uses the rectangular player instead of a voice bubble).
+
+Configure the TTS provider in your `config.yaml` under the `tts.provider` key.
+
+## Group Chat Usage
+
+Hermes Agent works in Telegram group chats with a few considerations:
+
+- **Privacy mode** determines what messages the bot can see (see [Step 3](#step-3-privacy-mode-critical-for-groups))
+- When privacy mode is on, **@mention the bot** (e.g., `@my_hermes_bot what's the weather?`) or **reply to its messages** to interact
+- When privacy mode is off (or bot is admin), the bot sees all messages and can participate naturally
+- `TELEGRAM_ALLOWED_USERS` still applies — only authorized users can trigger the bot, even in groups
+
+## Recent Bot API Features (2024–2025)
+
+- **Privacy policy:** Telegram now requires bots to have a privacy policy. Set one via BotFather with `/setprivacy_policy`, or Telegram may auto-generate a placeholder. This is particularly important if your bot is public-facing.
+- **Message streaming:** Bot API 9.x added support for streaming long responses, which can improve perceived latency for lengthy agent replies.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Bot not responding at all | Verify `TELEGRAM_BOT_TOKEN` is correct. Check `hermes gateway` logs for errors. |
+| Bot responds with "unauthorized" | Your user ID is not in `TELEGRAM_ALLOWED_USERS`. Double-check with @userinfobot. |
+| Bot ignores group messages | Privacy mode is likely on. Disable it (Step 3) or make the bot a group admin. **Remember to remove and re-add the bot after changing privacy.** |
+| Voice messages not transcribed | Check that `VOICE_TOOLS_OPENAI_KEY` is set and valid in `~/.hermes/.env`. |
+| Voice replies are files, not bubbles | Install `ffmpeg` (needed for Edge TTS Opus conversion). |
+| Bot token revoked/invalid | Generate a new token via `/revoke` then `/newbot` or `/token` in BotFather. Update your `.env` file. |
 
 ## Exec Approval
 
@@ -68,7 +188,9 @@ Reply "yes"/"y" to approve or "no"/"n" to deny.
 ## Security
 
 :::warning
-Always set `TELEGRAM_ALLOWED_USERS` to restrict who can use the bot. Without it, the gateway denies all users by default.
+Always set `TELEGRAM_ALLOWED_USERS` to restrict who can interact with your bot. Without it, the gateway denies all users by default as a safety measure.
 :::
 
-You can also use [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) for a more dynamic approach.
+Never share your bot token publicly. If compromised, revoke it immediately via BotFather's `/revoke` command.
+
+For more details, see the [Security documentation](/user-guide/security). You can also use [DM pairing](/user-guide/messaging#dm-pairing-alternative-to-allowlists) for a more dynamic approach to user authorization.

website/docs/user-guide/messaging/whatsapp.md

@@ -6,16 +6,57 @@ description: "Set up Hermes Agent as a WhatsApp bot via the built-in Baileys bri
 
 # WhatsApp Setup
 
-WhatsApp doesn't have a simple bot API like Telegram or Discord. Hermes includes a built-in bridge using [Baileys](https://github.com/WhiskeySockets/Baileys) that connects via WhatsApp Web.
+Hermes connects to WhatsApp through a built-in bridge using [whatsapp-web.js](https://github.com/pedroslopez/whatsapp-web.js)
+(Baileys-based). This works by emulating a WhatsApp Web session — **not** through the official
+WhatsApp Business API. No Meta developer account or Business verification is required.
+
+:::warning Unofficial API — Ban Risk
+WhatsApp does **not** officially support third-party bots outside the Business API. Using
+whatsapp-web.js carries a small risk of account restrictions. To minimize risk:
+- **Use a dedicated phone number** for the bot (not your personal number)
+- **Don't send bulk/spam messages** — keep usage conversational
+- **Don't automate outbound messaging** to people who haven't messaged first
+:::
+
+:::warning WhatsApp Web Protocol Updates
+WhatsApp periodically updates their Web protocol, which can temporarily break compatibility
+with whatsapp-web.js. When this happens, Hermes will update the bridge dependency. If the
+bot stops working after a WhatsApp update, pull the latest Hermes version and re-pair.
+:::
 
 ## Two Modes
 
 | Mode | How it works | Best for |
 |------|-------------|----------|
-| **Separate bot number** (recommended) | Dedicate a phone number to the bot. People message that number directly. | Clean UX, multiple users |
-| **Personal self-chat** | Use your own WhatsApp. You message yourself to talk to the agent. | Quick setup, single user |
+| **Separate bot number** (recommended) | Dedicate a phone number to the bot. People message that number directly. | Clean UX, multiple users, lower ban risk |
+| **Personal self-chat** | Use your own WhatsApp. You message yourself to talk to the agent. | Quick setup, single user, testing |
 
-## Setup
+---
+
+## Prerequisites
+
+- **Node.js v18+** and **npm** — the WhatsApp bridge runs as a Node.js process
+- **A phone with WhatsApp** installed (for scanning the QR code)
+
+**On Linux headless servers**, you also need Chromium/Puppeteer dependencies:
+
+```bash
+# Debian / Ubuntu
+sudo apt-get install -y \
+  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+  libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
+  libpango-1.0-0 libcairo2 libasound2 libxshmfence1
+
+# Fedora / RHEL
+sudo dnf install -y \
+  nss atk at-spi2-atk cups-libs libdrm libxkbcommon \
+  libXcomposite libXdamage libXrandr mesa-libgbm \
+  pango cairo alsa-lib
+```
+
+---
+
+## Step 1: Run the Setup Wizard
 
 ```bash
 hermes whatsapp
@@ -23,55 +64,130 @@ hermes whatsapp
 
 The wizard will:
 
-1. Ask which mode you want
-2. For **bot mode**: guide you through getting a second number
-3. Configure the allowlist
-4. Install bridge dependencies (Node.js required)
-5. Display a QR code — scan from WhatsApp → Settings → Linked Devices → Link a Device
-6. Exit once paired
+1. Ask which mode you want (**bot** or **self-chat**)
+2. Install bridge dependencies if needed
+3. Display a **QR code** in your terminal
+4. Wait for you to scan it
 
-## Getting a Second Number (Bot Mode)
+**To scan the QR code:**
+
+1. Open WhatsApp on your phone
+2. Go to **Settings → Linked Devices**
+3. Tap **Link a Device**
+4. Point your camera at the terminal QR code
+
+Once paired, the wizard confirms the connection and exits. Your session is saved automatically.
+
+:::tip
+If the QR code looks garbled, make sure your terminal is at least 60 columns wide and supports
+Unicode. You can also try a different terminal emulator.
+:::
+
+---
+
+## Step 2: Getting a Second Phone Number (Bot Mode)
+
+For bot mode, you need a phone number that isn't already registered with WhatsApp. Three options:
 
 | Option | Cost | Notes |
 |--------|------|-------|
-| WhatsApp Business app + dual-SIM | Free (if you have dual-SIM) | Install alongside personal WhatsApp, no second phone needed |
-| Google Voice | Free (US only) | voice.google.com, verify WhatsApp via the Google Voice app |
-| Prepaid SIM | $3-10/month | Any carrier; verify once, phone can go in a drawer on WiFi |
+| **Google Voice** | Free | US only. Get a number at [voice.google.com](https://voice.google.com). Verify WhatsApp via SMS through the Google Voice app. |
+| **Prepaid SIM** | $5–15 one-time | Any carrier. Activate, verify WhatsApp, then the SIM can sit in a drawer. Number must stay active (make a call every 90 days). |
+| **VoIP services** | Free–$5/month | TextNow, TextFree, or similar. Some VoIP numbers are blocked by WhatsApp — try a few if the first doesn't work. |
 
-## Starting the Gateway
+After getting the number:
+
+1. Install WhatsApp on a phone (or use WhatsApp Business app with dual-SIM)
+2. Register the new number with WhatsApp
+3. Run `hermes whatsapp` and scan the QR code from that WhatsApp account
+
+---
+
+## Step 3: Configure Hermes
+
+Add the following to your `~/.hermes/.env` file:
 
 ```bash
-hermes gateway            # Foreground
-hermes gateway install    # Or install as a system service
+# Required
+WHATSAPP_ENABLED=true
+WHATSAPP_MODE=bot                          # "bot" or "self-chat"
+WHATSAPP_ALLOWED_USERS=15551234567         # Comma-separated phone numbers (with country code, no +)
+
+# Optional
+WHATSAPP_HOME_CONTACT=15551234567          # Default contact for proactive/scheduled messages
+```
+
+Then start the gateway:
+
+```bash
+hermes gateway              # Foreground
+hermes gateway install      # Install as a system service
 ```
 
 The gateway starts the WhatsApp bridge automatically using the saved session.
 
-## Environment Variables
+---
+
+## Session Persistence
+
+The whatsapp-web.js `LocalAuth` strategy saves your session to the `.wwebjs_auth` folder inside
+your Hermes data directory (`~/.hermes/`). This means:
+
+- **Sessions survive restarts** — you don't need to re-scan the QR code every time
+- The session data includes encryption keys and device credentials
+- **Do not share or commit the `.wwebjs_auth` folder** — it grants full access to the WhatsApp account
+
+---
+
+## Re-pairing
+
+If the session breaks (phone reset, WhatsApp update, manually unlinked), you'll see connection
+errors in the gateway logs. To fix it:
 
 ```bash
-WHATSAPP_ENABLED=true
-WHATSAPP_MODE=bot                      # "bot" or "self-chat"
-WHATSAPP_ALLOWED_USERS=15551234567     # Comma-separated phone numbers with country code
+hermes whatsapp
 ```
 
-## Important Notes
+This generates a fresh QR code. Scan it again and the session is re-established. The gateway
+handles **temporary** disconnections (network blips, phone going offline briefly) automatically
+with reconnection logic.
 
-- Agent responses are prefixed with "⚕ **Hermes Agent**" for easy identification
-- WhatsApp Web sessions can disconnect if WhatsApp updates their protocol
-- The gateway reconnects automatically
-- If you see persistent failures, re-pair with `hermes whatsapp`
-
-:::info Re-pairing
-If WhatsApp Web sessions disconnect (protocol updates, phone reset), re-pair with `hermes whatsapp`. The gateway handles temporary disconnections automatically.
-:::
+---
 
 ## Voice Messages
 
-Voice messages sent on WhatsApp are automatically transcribed (requires `VOICE_TOOLS_OPENAI_KEY`). TTS audio is sent as MP3 file attachments.
+Hermes supports voice on WhatsApp:
+
+- **Incoming:** Voice messages (`.ogg` opus) are automatically transcribed using Whisper (requires `VOICE_TOOLS_OPENAI_KEY`)
+- **Outgoing:** TTS responses are sent as MP3 audio file attachments
+- Agent responses are prefixed with "⚕ **Hermes Agent**" for easy identification
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **QR code not scanning** | Ensure terminal is wide enough (60+ columns). Try a different terminal. Make sure you're scanning from the correct WhatsApp account (bot number, not personal). |
+| **QR code expires** | QR codes refresh every ~20 seconds. If it times out, restart `hermes whatsapp`. |
+| **Session not persisting** | Check that `~/.hermes/.wwebjs_auth/` exists and is writable. On Docker, mount this as a volume. |
+| **Logged out unexpectedly** | WhatsApp unlinks devices after ~14 days of phone inactivity. Keep the phone on and connected to WiFi. Re-pair with `hermes whatsapp`. |
+| **"Execution context was destroyed"** | Chromium crashed. Install the Puppeteer dependencies listed in Prerequisites. On low-RAM servers, add swap space. |
+| **Bot stops working after WhatsApp update** | Update Hermes to get the latest bridge version, then re-pair. |
+| **Messages not being received** | Verify `WHATSAPP_ALLOWED_USERS` includes the sender's number (with country code, no `+` or spaces). |
+
+---
 
 ## Security
 
 :::warning
-Always set `WHATSAPP_ALLOWED_USERS` with phone numbers (including country code) to restrict who can use the bot.
+**Always set `WHATSAPP_ALLOWED_USERS`** with phone numbers (including country code, without the `+`)
+of authorized users. Without this setting, the gateway will **deny all incoming messages** as a
+safety measure.
 :::
+
+- The `.wwebjs_auth` folder contains full session credentials — protect it like a password
+- Set file permissions: `chmod 700 ~/.hermes/.wwebjs_auth`
+- Use a **dedicated phone number** for the bot to isolate risk from your personal account
+- If you suspect compromise, unlink the device from WhatsApp → Settings → Linked Devices
+- Phone numbers in logs are partially redacted, but review your log retention policy

website/sidebars.ts

@@ -10,6 +10,18 @@ const sidebars: SidebarsConfig = {
         'getting-started/quickstart',
         'getting-started/installation',
         'getting-started/updating',
+        'getting-started/learning-path',
+      ],
+    },
+    {
+      type: 'category',
+      label: 'Guides & Tutorials',
+      collapsed: false,
+      items: [
+        'guides/tips',
+        'guides/daily-briefing-bot',
+        'guides/team-telegram-assistant',
+        'guides/python-library',
       ],
     },
     {
@@ -35,24 +47,48 @@ const sidebars: SidebarsConfig = {
         },
         {
           type: 'category',
-          label: 'Features',
+          label: 'Core Features',
           items: [
             'user-guide/features/tools',
             'user-guide/features/skills',
             'user-guide/features/memory',
             'user-guide/features/context-files',
             'user-guide/features/personality',
-            'user-guide/features/mcp',
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Automation',
+          items: [
             'user-guide/features/cron',
-            'user-guide/features/hooks',
             'user-guide/features/delegation',
             'user-guide/features/code-execution',
+            'user-guide/features/hooks',
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Web & Media',
+          items: [
             'user-guide/features/browser',
-            'user-guide/features/image-generation',
             'user-guide/features/vision',
+            'user-guide/features/image-generation',
             'user-guide/features/tts',
-            'user-guide/features/provider-routing',
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Integrations',
+          items: [
+            'user-guide/features/mcp',
             'user-guide/features/honcho',
+            'user-guide/features/provider-routing',
+          ],
+        },
+        {
+          type: 'category',
+          label: 'Advanced',
+          items: [
             'user-guide/features/batch-processing',
             'user-guide/features/rl-training',
           ],
@@ -76,6 +112,7 @@ const sidebars: SidebarsConfig = {
       items: [
         'reference/cli-commands',
         'reference/environment-variables',
+        'reference/faq',
       ],
     },
   ],