fix: prevent context pressure warning spam (agent loop + gateway rate-limit)

Two complementary fixes for repeated context pressure warnings spamming gateway users (Telegram, Discord, etc.): 1. Agent-level loop fix (run_agent.py): After compression, only reset _context_pressure_warned if the post-compression estimate is actually below the 85% warning level. Previously the flag was unconditionally reset, causing the warning to re-fire every loop iteration when compression couldn't reduce below 85% of the threshold (e.g. very low threshold like 15%, or system prompt alone exceeds the warning level). 2. Gateway-level rate-limit (gateway/run.py, salvaged from PR #3786): Per-chat_id cooldown of 1 hour on compression warning messages. Both warning paths ('still large after compression' and 'compression failed') are gated. Defense-in-depth — even if the agent-level fix has edge cases, users won't see more than one warning per hour. Co-authored-by: dlkakbs <dlkakbs@users.noreply.github.com>
feat: add /yolo slash command to toggle dangerous command approvals
2026-03-30 13:02:57 -07:00 · 2026-03-30 09:18:04 -07:00 · 2026-03-30 08:37:19 -07:00 · 2026-03-30 08:29:38 -07:00 · 2026-03-30 08:13:01 -07:00 · 2026-03-30 08:10:23 -07:00
180 changed files with 24212 additions and 984 deletions
@@ -98,7 +98,7 @@ FAL_KEY=
 HONCHO_API_KEY=

 # =============================================================================
-# TERMINAL TOOL CONFIGURATION (mini-swe-agent backend)
+# TERMINAL TOOL CONFIGURATION
 # =============================================================================
 # Backend type: "local", "singularity", "docker", "modal", or "ssh"
 # Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
@@ -210,6 +210,10 @@ registry.register(

 The registry handles schema collection, dispatch, availability checking, and error wrapping. All handlers MUST return a JSON string.

+**Path references in tool schemas**: If the schema description mentions file paths (e.g. default output directories), use `display_hermes_home()` to make them profile-aware. The schema is generated at import time, which is after `_apply_profile_override()` sets `HERMES_HOME`.
+
+**State files**: If a tool stores persistent state (caches, logs, checkpoints), use `get_hermes_home()` for the base directory — never `Path.home() / ".hermes"`. This ensures each profile gets its own state.
+
 **Agent-level tools** (todo, memory): intercepted by `run_agent.py` before `handle_function_call()`. See `todo_tool.py` for the pattern.

 ---
@@ -358,8 +362,69 @@ in config.yaml (or `HERMES_BACKGROUND_NOTIFICATIONS` env var):

 ---

+## Profiles: Multi-Instance Support
+
+Hermes supports **profiles** — multiple fully isolated instances, each with its own
+`HERMES_HOME` directory (config, API keys, memory, sessions, skills, gateway, etc.).
+
+The core mechanism: `_apply_profile_override()` in `hermes_cli/main.py` sets
+`HERMES_HOME` before any module imports. All 119+ references to `get_hermes_home()`
+automatically scope to the active profile.
+
+### Rules for profile-safe code
+
+1. **Use `get_hermes_home()` for all HERMES_HOME paths.** Import from `hermes_constants`.
+   NEVER hardcode `~/.hermes` or `Path.home() / ".hermes"` in code that reads/writes state.
+   ```python
+   # GOOD
+   from hermes_constants import get_hermes_home
+   config_path = get_hermes_home() / "config.yaml"
+
+   # BAD — breaks profiles
+   config_path = Path.home() / ".hermes" / "config.yaml"
+   ```
+
+2. **Use `display_hermes_home()` for user-facing messages.** Import from `hermes_constants`.
+   This returns `~/.hermes` for default or `~/.hermes/profiles/<name>` for profiles.
+   ```python
+   # GOOD
+   from hermes_constants import display_hermes_home
+   print(f"Config saved to {display_hermes_home()}/config.yaml")
+
+   # BAD — shows wrong path for profiles
+   print("Config saved to ~/.hermes/config.yaml")
+   ```
+
+3. **Module-level constants are fine** — they cache `get_hermes_home()` at import time,
+   which is AFTER `_apply_profile_override()` sets the env var. Just use `get_hermes_home()`,
+   not `Path.home() / ".hermes"`.
+
+4. **Tests that mock `Path.home()` must also set `HERMES_HOME`** — since code now uses
+   `get_hermes_home()` (reads env var), not `Path.home() / ".hermes"`:
+   ```python
+   with patch.object(Path, "home", return_value=tmp_path), \
+        patch.dict(os.environ, {"HERMES_HOME": str(tmp_path / ".hermes")}):
+       ...
+   ```
+
+5. **Gateway platform adapters should use token locks** — if the adapter connects with
+   a unique credential (bot token, API key), call `acquire_scoped_lock()` from
+   `gateway.status` in the `connect()`/`start()` method and `release_scoped_lock()` in
+   `disconnect()`/`stop()`. This prevents two profiles from using the same credential.
+   See `gateway/platforms/telegram.py` for the canonical pattern.
+
+6. **Profile operations are HOME-anchored, not HERMES_HOME-anchored** — `_get_profiles_root()`
+   returns `Path.home() / ".hermes" / "profiles"`, NOT `get_hermes_home() / "profiles"`.
+   This is intentional — it lets `hermes -p coder profile list` see all profiles regardless
+   of which one is active.
+
 ## Known Pitfalls

+### DO NOT hardcode `~/.hermes` paths
+Use `get_hermes_home()` from `hermes_constants` for code paths. Use `display_hermes_home()`
+for user-facing print/log messages. Hardcoding `~/.hermes` breaks profiles — each profile
+has its own `HERMES_HOME` directory. This was the source of 5 bugs fixed in PR #3575.
+
 ### DO NOT use `simple_term_menu` for interactive menus
 Rendering bugs in tmux/iTerm2 — ghosting on scroll. Use `curses` (stdlib) instead. See `hermes_cli/tools_config.py` for the pattern.

@@ -375,6 +440,19 @@ Tool schema descriptions must not mention tools from other toolsets by name (e.g
 ### Tests must not write to `~/.hermes/`
 The `_isolate_hermes_home` autouse fixture in `tests/conftest.py` redirects `HERMES_HOME` to a temp dir. Never hardcode `~/.hermes/` paths in tests.

+**Profile tests**: When testing profile features, also mock `Path.home()` so that
+`_get_profiles_root()` and `_get_default_hermes_home()` resolve within the temp dir.
+Use the pattern from `tests/hermes_cli/test_profiles.py`:
+```python
+@pytest.fixture
+def profile_env(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    return home
+```
+
 ---

 ## Testing
@@ -0,0 +1,249 @@
+# Hermes Agent v0.6.0 (v2026.3.30)
+
+**Release Date:** March 30, 2026
+
+> The multi-instance release — Profiles for running isolated agent instances, MCP server mode, Docker container, fallback provider chains, two new messaging platforms (Feishu/Lark and WeCom), Telegram webhook mode, Slack multi-workspace OAuth, 95 PRs and 16 resolved issues in 2 days.
+
+---
+
+## ✨ Highlights
+
+- **Profiles — Multi-Instance Hermes** — Run multiple isolated Hermes instances from the same installation. Each profile gets its own config, memory, sessions, skills, and gateway service. Create with `hermes profile create`, switch with `hermes -p <name>`, export/import for sharing. Full token-lock isolation prevents two profiles from using the same bot credential. ([#3681](https://github.com/NousResearch/hermes-agent/pull/3681))
+
+- **MCP Server Mode** — Expose Hermes conversations and sessions to any MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.) via `hermes mcp serve`. Browse conversations, read messages, search across sessions, and manage attachments — all through the Model Context Protocol. Supports both stdio and Streamable HTTP transports. ([#3795](https://github.com/NousResearch/hermes-agent/pull/3795))
+
+- **Docker Container** — Official Dockerfile for running Hermes Agent in a container. Supports both CLI and gateway modes with volume-mounted config. ([#3668](https://github.com/NousResearch/hermes-agent/pull/3668), closes [#850](https://github.com/NousResearch/hermes-agent/issues/850))
+
+- **Ordered Fallback Provider Chain** — Configure multiple inference providers with automatic failover. When your primary provider returns errors or is unreachable, Hermes automatically tries the next provider in the chain. Configure via `fallback_providers` in config.yaml. ([#3813](https://github.com/NousResearch/hermes-agent/pull/3813), closes [#1734](https://github.com/NousResearch/hermes-agent/issues/1734))
+
+- **Feishu/Lark Platform Support** — Full gateway adapter for Feishu (飞书) and Lark with event subscriptions, message cards, group chat, image/file attachments, and interactive card callbacks. ([#3799](https://github.com/NousResearch/hermes-agent/pull/3799), [#3817](https://github.com/NousResearch/hermes-agent/pull/3817), closes [#1788](https://github.com/NousResearch/hermes-agent/issues/1788))
+
+- **WeCom (Enterprise WeChat) Platform Support** — New gateway adapter for WeCom (企业微信) with text/image/voice messages, group chats, and callback verification. ([#3847](https://github.com/NousResearch/hermes-agent/pull/3847))
+
+- **Slack Multi-Workspace OAuth** — Connect a single Hermes gateway to multiple Slack workspaces via OAuth token file. Each workspace gets its own bot token, resolved dynamically per incoming event. ([#3903](https://github.com/NousResearch/hermes-agent/pull/3903))
+
+- **Telegram Webhook Mode & Group Controls** — Run the Telegram adapter in webhook mode as an alternative to polling — faster response times and better for production deployments behind a reverse proxy. New group mention gating controls when the bot responds: always, only when @mentioned, or via regex triggers. ([#3880](https://github.com/NousResearch/hermes-agent/pull/3880), [#3870](https://github.com/NousResearch/hermes-agent/pull/3870))
+
+- **Exa Search Backend** — Add Exa as an alternative web search and content extraction backend alongside Firecrawl and DuckDuckGo. Set `EXA_API_KEY` and configure as preferred backend. ([#3648](https://github.com/NousResearch/hermes-agent/pull/3648))
+
+- **Skills & Credentials on Remote Backends** — Mount skill directories and credential files into Modal and Docker containers, so remote terminal sessions have access to the same skills and secrets as local execution. ([#3890](https://github.com/NousResearch/hermes-agent/pull/3890), [#3671](https://github.com/NousResearch/hermes-agent/pull/3671), closes [#3665](https://github.com/NousResearch/hermes-agent/issues/3665), [#3433](https://github.com/NousResearch/hermes-agent/issues/3433))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Ordered fallback provider chain** — automatic failover across multiple configured providers ([#3813](https://github.com/NousResearch/hermes-agent/pull/3813))
+- **Fix api_mode on provider switch** — switching providers via `hermes model` now correctly clears stale `api_mode` instead of hardcoding `chat_completions`, fixing 404s for providers with Anthropic-compatible endpoints ([#3726](https://github.com/NousResearch/hermes-agent/pull/3726), [#3857](https://github.com/NousResearch/hermes-agent/pull/3857), closes [#3685](https://github.com/NousResearch/hermes-agent/issues/3685))
+- **Stop silent OpenRouter fallback** — when no provider is configured, Hermes now raises a clear error instead of silently routing to OpenRouter ([#3807](https://github.com/NousResearch/hermes-agent/pull/3807), [#3862](https://github.com/NousResearch/hermes-agent/pull/3862))
+- **Gemini 3.1 preview models** — added to OpenRouter and Nous Portal catalogs ([#3803](https://github.com/NousResearch/hermes-agent/pull/3803), closes [#3753](https://github.com/NousResearch/hermes-agent/issues/3753))
+- **Gemini direct API context length** — full context length resolution for direct Google AI endpoints ([#3876](https://github.com/NousResearch/hermes-agent/pull/3876))
+- **gpt-5.4-mini** added to Codex fallback catalog ([#3855](https://github.com/NousResearch/hermes-agent/pull/3855))
+- **Curated model lists preferred** over live API probe when the probe returns fewer models ([#3856](https://github.com/NousResearch/hermes-agent/pull/3856), [#3867](https://github.com/NousResearch/hermes-agent/pull/3867))
+- **User-friendly 429 rate limit messages** with Retry-After countdown ([#3809](https://github.com/NousResearch/hermes-agent/pull/3809))
+- **Auxiliary client placeholder key** for local servers without auth requirements ([#3842](https://github.com/NousResearch/hermes-agent/pull/3842))
+- **INFO-level logging** for auxiliary provider resolution ([#3866](https://github.com/NousResearch/hermes-agent/pull/3866))
+
+### Agent Loop & Conversation
+- **Subagent status reporting** — reports `completed` status when summary exists instead of generic failure ([#3829](https://github.com/NousResearch/hermes-agent/pull/3829))
+- **Session log file updated during compression** — prevents stale file references after context compression ([#3835](https://github.com/NousResearch/hermes-agent/pull/3835))
+- **Omit empty tools param** — sends no `tools` parameter when empty instead of `None`, fixing compatibility with strict providers ([#3820](https://github.com/NousResearch/hermes-agent/pull/3820))
+
+### Profiles & Multi-Instance
+- **Profiles system** — `hermes profile create/list/switch/delete/export/import/rename`. Each profile gets isolated HERMES_HOME, gateway service, CLI wrapper. Token locks prevent credential collisions. Tab completion for profile names. ([#3681](https://github.com/NousResearch/hermes-agent/pull/3681))
+- **Profile-aware display paths** — all user-facing `~/.hermes` paths replaced with `display_hermes_home()` to show the correct profile directory ([#3623](https://github.com/NousResearch/hermes-agent/pull/3623))
+- **Lazy display_hermes_home imports** — prevents `ImportError` during `hermes update` when modules cache stale bytecode ([#3776](https://github.com/NousResearch/hermes-agent/pull/3776))
+- **HERMES_HOME for protected paths** — `.env` write-deny path now respects HERMES_HOME instead of hardcoded `~/.hermes` ([#3840](https://github.com/NousResearch/hermes-agent/pull/3840))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New Platforms
+- **Feishu/Lark** — Full adapter with event subscriptions, message cards, group chat, image/file attachments, interactive card callbacks ([#3799](https://github.com/NousResearch/hermes-agent/pull/3799), [#3817](https://github.com/NousResearch/hermes-agent/pull/3817))
+- **WeCom (Enterprise WeChat)** — Text/image/voice messages, group chats, callback verification ([#3847](https://github.com/NousResearch/hermes-agent/pull/3847))
+
+### Telegram
+- **Webhook mode** — run as webhook endpoint instead of polling for production deployments ([#3880](https://github.com/NousResearch/hermes-agent/pull/3880))
+- **Group mention gating & regex triggers** — configurable bot response behavior in groups: always, @mention-only, or regex-matched ([#3870](https://github.com/NousResearch/hermes-agent/pull/3870))
+- **Gracefully handle deleted reply targets** — no more crashes when the message being replied to was deleted ([#3858](https://github.com/NousResearch/hermes-agent/pull/3858), closes [#3229](https://github.com/NousResearch/hermes-agent/issues/3229))
+
+### Discord
+- **Message processing reactions** — adds a reaction emoji while processing and removes it when done, giving visual feedback in channels ([#3871](https://github.com/NousResearch/hermes-agent/pull/3871))
+- **DISCORD_IGNORE_NO_MENTION** — skip messages that @mention other users/bots but not Hermes ([#3640](https://github.com/NousResearch/hermes-agent/pull/3640))
+- **Clean up deferred "thinking..."** — properly removes the "thinking..." indicator after slash commands complete ([#3674](https://github.com/NousResearch/hermes-agent/pull/3674), closes [#3595](https://github.com/NousResearch/hermes-agent/issues/3595))
+
+### Slack
+- **Multi-workspace OAuth** — connect to multiple Slack workspaces from a single gateway via OAuth token file ([#3903](https://github.com/NousResearch/hermes-agent/pull/3903))
+
+### WhatsApp
+- **Persistent aiohttp session** — reuse HTTP sessions across requests instead of creating new ones per message ([#3818](https://github.com/NousResearch/hermes-agent/pull/3818))
+- **LID↔phone alias resolution** — correctly match Linked ID and phone number formats in allowlists ([#3830](https://github.com/NousResearch/hermes-agent/pull/3830))
+- **Skip reply prefix in bot mode** — cleaner message formatting when running as a WhatsApp bot ([#3931](https://github.com/NousResearch/hermes-agent/pull/3931))
+
+### Matrix
+- **Native voice messages via MSC3245** — send voice messages as proper Matrix voice events instead of file attachments ([#3877](https://github.com/NousResearch/hermes-agent/pull/3877))
+
+### Mattermost
+- **Configurable mention behavior** — respond to messages without requiring @mention ([#3664](https://github.com/NousResearch/hermes-agent/pull/3664))
+
+### Signal
+- **URL-encode phone numbers** and correct attachment RPC parameter — fixes delivery failures with certain phone number formats ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670)) — @kshitijk4poor
+
+### Email
+- **Close SMTP/IMAP connections on failure** — prevents connection leaks during error scenarios ([#3804](https://github.com/NousResearch/hermes-agent/pull/3804))
+
+### Gateway Core
+- **Atomic config writes** — use atomic file writes for config.yaml to prevent data loss during crashes ([#3800](https://github.com/NousResearch/hermes-agent/pull/3800))
+- **Home channel env overrides** — apply environment variable overrides for home channels consistently ([#3796](https://github.com/NousResearch/hermes-agent/pull/3796), [#3808](https://github.com/NousResearch/hermes-agent/pull/3808))
+- **Replace print() with logger** — BasePlatformAdapter now uses proper logging instead of print statements ([#3669](https://github.com/NousResearch/hermes-agent/pull/3669))
+- **Cron delivery labels** — resolve human-friendly delivery labels via channel directory ([#3860](https://github.com/NousResearch/hermes-agent/pull/3860), closes [#1945](https://github.com/NousResearch/hermes-agent/issues/1945))
+- **Cron [SILENT] tightening** — prevent agents from prefixing reports with [SILENT] to suppress delivery ([#3901](https://github.com/NousResearch/hermes-agent/pull/3901))
+- **Background task media delivery** and vision download timeout fixes ([#3919](https://github.com/NousResearch/hermes-agent/pull/3919))
+- **Boot-md hook** — example built-in hook to run a BOOT.md file on gateway startup ([#3733](https://github.com/NousResearch/hermes-agent/pull/3733))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Configurable tool preview length** — show full file paths by default instead of truncating at 40 chars ([#3841](https://github.com/NousResearch/hermes-agent/pull/3841))
+- **Tool token context display** — `hermes tools` checklist now shows estimated token cost per toolset ([#3805](https://github.com/NousResearch/hermes-agent/pull/3805))
+- **/bg spinner TUI fix** — route background task spinner through the TUI widget to prevent status bar collision ([#3643](https://github.com/NousResearch/hermes-agent/pull/3643))
+- **Prevent status bar wrapping** into duplicate rows ([#3883](https://github.com/NousResearch/hermes-agent/pull/3883)) — @kshitijk4poor
+- **Handle closed stdout ValueError** in safe print paths — fixes crashes when stdout is closed during gateway thread shutdown ([#3843](https://github.com/NousResearch/hermes-agent/pull/3843), closes [#3534](https://github.com/NousResearch/hermes-agent/issues/3534))
+- **Remove input() from /tools disable** — eliminates freeze in terminal when disabling tools ([#3918](https://github.com/NousResearch/hermes-agent/pull/3918))
+- **TTY guard for interactive CLI commands** — prevent CPU spin when launched without a terminal ([#3933](https://github.com/NousResearch/hermes-agent/pull/3933))
+- **Argparse entrypoint** — use argparse in the top-level launcher for cleaner error handling ([#3874](https://github.com/NousResearch/hermes-agent/pull/3874))
+- **Lazy-initialized tools show yellow** in banner instead of red, reducing false alarm about "missing" tools ([#3822](https://github.com/NousResearch/hermes-agent/pull/3822))
+- **Honcho tools shown in banner** when configured ([#3810](https://github.com/NousResearch/hermes-agent/pull/3810))
+
+### Setup & Configuration
+- **Auto-install matrix-nio** during `hermes setup` when Matrix is selected ([#3802](https://github.com/NousResearch/hermes-agent/pull/3802), [#3873](https://github.com/NousResearch/hermes-agent/pull/3873))
+- **Session export stdout support** — export sessions to stdout with `-` for piping ([#3641](https://github.com/NousResearch/hermes-agent/pull/3641), closes [#3609](https://github.com/NousResearch/hermes-agent/issues/3609))
+- **Configurable approval timeouts** — set how long dangerous command approval prompts wait before auto-denying ([#3886](https://github.com/NousResearch/hermes-agent/pull/3886), closes [#3765](https://github.com/NousResearch/hermes-agent/issues/3765))
+- **Clear __pycache__ during update** — prevents stale bytecode ImportError after `hermes update` ([#3819](https://github.com/NousResearch/hermes-agent/pull/3819))
+
+---
+
+## 🔧 Tool System
+
+### MCP
+- **MCP Server Mode** — `hermes mcp serve` exposes conversations, sessions, and attachments to MCP clients via stdio or Streamable HTTP ([#3795](https://github.com/NousResearch/hermes-agent/pull/3795))
+- **Dynamic tool discovery** — respond to `notifications/tools/list_changed` events to pick up new tools from MCP servers without reconnecting ([#3812](https://github.com/NousResearch/hermes-agent/pull/3812))
+- **Non-deprecated HTTP transport** — switched from `sse_client` to `streamable_http_client` ([#3646](https://github.com/NousResearch/hermes-agent/pull/3646))
+
+### Web Tools
+- **Exa search backend** — alternative to Firecrawl and DuckDuckGo for web search and extraction ([#3648](https://github.com/NousResearch/hermes-agent/pull/3648))
+
+### Browser
+- **Guard against None LLM responses** in browser snapshot and vision tools ([#3642](https://github.com/NousResearch/hermes-agent/pull/3642))
+
+### Terminal & Remote Backends
+- **Mount skill directories** into Modal and Docker containers ([#3890](https://github.com/NousResearch/hermes-agent/pull/3890))
+- **Mount credential files** into remote backends with mtime+size caching ([#3671](https://github.com/NousResearch/hermes-agent/pull/3671))
+- **Preserve partial output** when commands time out instead of losing everything ([#3868](https://github.com/NousResearch/hermes-agent/pull/3868))
+- **Stop marking persisted env vars as missing** on remote backends ([#3650](https://github.com/NousResearch/hermes-agent/pull/3650))
+
+### Audio
+- **.aac format support** in transcription tool ([#3865](https://github.com/NousResearch/hermes-agent/pull/3865), closes [#1963](https://github.com/NousResearch/hermes-agent/issues/1963))
+- **Audio download retry** — retry logic for `cache_audio_from_url` matching the existing image download pattern ([#3401](https://github.com/NousResearch/hermes-agent/pull/3401)) — @binhnt92
+
+### Vision
+- **Reject non-image files** and enforce website-only policy for vision analysis ([#3845](https://github.com/NousResearch/hermes-agent/pull/3845))
+
+### Tool Schema
+- **Ensure name field** always present in tool definitions, fixing `KeyError: 'name'` crashes ([#3811](https://github.com/NousResearch/hermes-agent/pull/3811), closes [#3729](https://github.com/NousResearch/hermes-agent/issues/3729))
+
+### ACP (Editor Integration)
+- **Complete session management surface** for VS Code/Zed/JetBrains clients — proper task lifecycle, cancel support, session persistence ([#3675](https://github.com/NousResearch/hermes-agent/pull/3675))
+
+---
+
+## 🧩 Skills & Plugins
+
+### Skills System
+- **External skill directories** — configure additional skill directories via `skills.external_dirs` in config.yaml ([#3678](https://github.com/NousResearch/hermes-agent/pull/3678))
+- **Category path traversal blocked** — prevents `../` attacks in skill category names ([#3844](https://github.com/NousResearch/hermes-agent/pull/3844))
+- **parallel-cli moved to optional-skills** — reduces default skill footprint ([#3673](https://github.com/NousResearch/hermes-agent/pull/3673)) — @kshitijk4poor
+
+### New Skills
+- **memento-flashcards** — spaced repetition flashcard system ([#3827](https://github.com/NousResearch/hermes-agent/pull/3827))
+- **songwriting-and-ai-music** — songwriting craft and AI music generation prompts ([#3834](https://github.com/NousResearch/hermes-agent/pull/3834))
+- **SiYuan Note** — integration with SiYuan note-taking app ([#3742](https://github.com/NousResearch/hermes-agent/pull/3742))
+- **Scrapling** — web scraping skill using Scrapling library ([#3742](https://github.com/NousResearch/hermes-agent/pull/3742))
+- **one-three-one-rule** — communication framework skill ([#3797](https://github.com/NousResearch/hermes-agent/pull/3797))
+
+### Plugin System
+- **Plugin enable/disable commands** — `hermes plugins enable/disable <name>` for managing plugin state without removing them ([#3747](https://github.com/NousResearch/hermes-agent/pull/3747))
+- **Plugin message injection** — plugins can now inject messages into the conversation stream on behalf of the user via `ctx.inject_message()` ([#3778](https://github.com/NousResearch/hermes-agent/pull/3778)) — @winglian
+- **Honcho self-hosted support** — allow local Honcho instances without requiring an API key ([#3644](https://github.com/NousResearch/hermes-agent/pull/3644))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Hardened dangerous command detection** — expanded pattern matching for risky shell commands and added file tool path guards for sensitive locations (`/etc/`, `/boot/`, docker.sock) ([#3872](https://github.com/NousResearch/hermes-agent/pull/3872))
+- **Sensitive path write checks** in approval system — catch writes to system config files through file tools, not just terminal ([#3859](https://github.com/NousResearch/hermes-agent/pull/3859))
+- **Secret redaction expansion** — now covers ElevenLabs, Tavily, and Exa API keys ([#3920](https://github.com/NousResearch/hermes-agent/pull/3920))
+- **Vision file rejection** — reject non-image files passed to vision analysis to prevent information disclosure ([#3845](https://github.com/NousResearch/hermes-agent/pull/3845))
+- **Category path traversal blocking** — prevent directory traversal in skill category names ([#3844](https://github.com/NousResearch/hermes-agent/pull/3844))
+
+### Reliability
+- **Atomic config.yaml writes** — prevent data loss during gateway crashes ([#3800](https://github.com/NousResearch/hermes-agent/pull/3800))
+- **Clear __pycache__ on update** — prevent stale bytecode from causing ImportError after updates ([#3819](https://github.com/NousResearch/hermes-agent/pull/3819))
+- **Lazy imports for update safety** — prevent ImportError chains during `hermes update` when modules reference new functions ([#3776](https://github.com/NousResearch/hermes-agent/pull/3776))
+- **Restore terminalbench2 from patch corruption** — recovered file damaged by patch tool's secret redaction ([#3801](https://github.com/NousResearch/hermes-agent/pull/3801))
+- **Terminal timeout preserves partial output** — no more lost command output on timeout ([#3868](https://github.com/NousResearch/hermes-agent/pull/3868))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **OpenClaw migration model config overwrite** — migration no longer overwrites model config dict with a string ([#3924](https://github.com/NousResearch/hermes-agent/pull/3924)) — @0xbyt4
+- **OpenClaw migration expanded** — covers full data footprint including sessions, cron, memory ([#3869](https://github.com/NousResearch/hermes-agent/pull/3869))
+- **Telegram deleted reply targets** — gracefully handle replies to deleted messages instead of crashing ([#3858](https://github.com/NousResearch/hermes-agent/pull/3858))
+- **Discord "thinking..." persistence** — properly cleans up deferred response indicators ([#3674](https://github.com/NousResearch/hermes-agent/pull/3674))
+- **WhatsApp LID↔phone aliases** — fixes allowlist matching failures with Linked ID format ([#3830](https://github.com/NousResearch/hermes-agent/pull/3830))
+- **Signal URL-encoded phone numbers** — fixes delivery failures with certain formats ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670))
+- **Email connection leaks** — properly close SMTP/IMAP connections on error ([#3804](https://github.com/NousResearch/hermes-agent/pull/3804))
+- **_safe_print ValueError** — no more gateway thread crashes on closed stdout ([#3843](https://github.com/NousResearch/hermes-agent/pull/3843))
+- **Tool schema KeyError 'name'** — ensure name field always present in tool definitions ([#3811](https://github.com/NousResearch/hermes-agent/pull/3811))
+- **api_mode stale on provider switch** — correctly clear when switching providers via `hermes model` ([#3857](https://github.com/NousResearch/hermes-agent/pull/3857))
+
+---
+
+## 🧪 Testing
+
+- Resolved 10+ CI failures across hooks, tiktoken, plugins, and skill tests ([#3848](https://github.com/NousResearch/hermes-agent/pull/3848), [#3721](https://github.com/NousResearch/hermes-agent/pull/3721), [#3936](https://github.com/NousResearch/hermes-agent/pull/3936))
+
+---
+
+## 📚 Documentation
+
+- **Comprehensive OpenClaw migration guide** — step-by-step guide for migrating from OpenClaw/Claw3D to Hermes Agent ([#3864](https://github.com/NousResearch/hermes-agent/pull/3864), [#3900](https://github.com/NousResearch/hermes-agent/pull/3900))
+- **Credential file passthrough docs** — document how to forward credential files and env vars to remote backends ([#3677](https://github.com/NousResearch/hermes-agent/pull/3677))
+- **DuckDuckGo requirements clarified** — note runtime dependency on duckduckgo-search package ([#3680](https://github.com/NousResearch/hermes-agent/pull/3680))
+- **Skills catalog updated** — added red-teaming category and optional skills listing ([#3745](https://github.com/NousResearch/hermes-agent/pull/3745))
+- **Feishu docs MDX fix** — escape angle-bracket URLs that break Docusaurus build ([#3902](https://github.com/NousResearch/hermes-agent/pull/3902))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 90 PRs across all subsystems
+
+### Community Contributors
+- **@kshitijk4poor** — 3 PRs: Signal phone number fix ([#3670](https://github.com/NousResearch/hermes-agent/pull/3670)), parallel-cli to optional-skills ([#3673](https://github.com/NousResearch/hermes-agent/pull/3673)), status bar wrapping fix ([#3883](https://github.com/NousResearch/hermes-agent/pull/3883))
+- **@winglian** — 1 PR: Plugin message injection interface ([#3778](https://github.com/NousResearch/hermes-agent/pull/3778))
+- **@binhnt92** — 1 PR: Audio download retry logic ([#3401](https://github.com/NousResearch/hermes-agent/pull/3401))
+- **@0xbyt4** — 1 PR: OpenClaw migration model config fix ([#3924](https://github.com/NousResearch/hermes-agent/pull/3924))
+
+### Issues Resolved from Community
+@Material-Scientist ([#850](https://github.com/NousResearch/hermes-agent/issues/850)), @hanxu98121 ([#1734](https://github.com/NousResearch/hermes-agent/issues/1734)), @penwyp ([#1788](https://github.com/NousResearch/hermes-agent/issues/1788)), @dan-and ([#1945](https://github.com/NousResearch/hermes-agent/issues/1945)), @AdrianScott ([#1963](https://github.com/NousResearch/hermes-agent/issues/1963)), @clawdbot47 ([#3229](https://github.com/NousResearch/hermes-agent/issues/3229)), @alanfwilliams ([#3404](https://github.com/NousResearch/hermes-agent/issues/3404)), @kentimsit ([#3433](https://github.com/NousResearch/hermes-agent/issues/3433)), @hayka-pacha ([#3534](https://github.com/NousResearch/hermes-agent/issues/3534)), @primmer ([#3595](https://github.com/NousResearch/hermes-agent/issues/3595)), @dagelf ([#3609](https://github.com/NousResearch/hermes-agent/issues/3609)), @HenkDz ([#3685](https://github.com/NousResearch/hermes-agent/issues/3685)), @tmdgusya ([#3729](https://github.com/NousResearch/hermes-agent/issues/3729)), @TypQxQ ([#3753](https://github.com/NousResearch/hermes-agent/issues/3753)), @acsezen ([#3765](https://github.com/NousResearch/hermes-agent/issues/3765))
+
+---
+
+**Full Changelog**: [v2026.3.28...v2026.3.30](https://github.com/NousResearch/hermes-agent/compare/v2026.3.28...v2026.3.30)
@@ -74,7 +74,7 @@ def main() -> None:

    agent = HermesACPAgent()
    try:
-        asyncio.run(acp.run_agent(agent))
+        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
    except KeyboardInterrupt:
        logger.info("Shutting down (KeyboardInterrupt)")
    except Exception:
@@ -25,6 +25,9 @@ from acp.schema import (
    NewSessionResponse,
    PromptResponse,
    ResumeSessionResponse,
+    SetSessionConfigOptionResponse,
+    SetSessionModelResponse,
+    SetSessionModeResponse,
    ResourceContentBlock,
    SessionCapabilities,
    SessionForkCapabilities,
@@ -94,11 +97,14 @@ class HermesACPAgent(acp.Agent):

    async def initialize(
        self,
-        protocol_version: int,
+        protocol_version: int | None = None,
        client_capabilities: ClientCapabilities | None = None,
        client_info: Implementation | None = None,
        **kwargs: Any,
    ) -> InitializeResponse:
+        resolved_protocol_version = (
+            protocol_version if isinstance(protocol_version, int) else acp.PROTOCOL_VERSION
+        )
        provider = detect_provider()
        auth_methods = None
        if provider:
@@ -111,7 +117,11 @@ class HermesACPAgent(acp.Agent):
            ]

        client_name = client_info.name if client_info else "unknown"
-        logger.info("Initialize from %s (protocol v%s)", client_name, protocol_version)
+        logger.info(
+            "Initialize from %s (protocol v%s)",
+            client_name,
+            resolved_protocol_version,
+        )

        return InitializeResponse(
            protocol_version=acp.PROTOCOL_VERSION,
@@ -471,7 +481,7 @@ class HermesACPAgent(acp.Agent):

    async def set_session_model(
        self, model_id: str, session_id: str, **kwargs: Any
-    ):
+    ) -> SetSessionModelResponse | None:
        """Switch the model for a session (called by ACP protocol)."""
        state = self.session_manager.get_session(session_id)
        if state:
@@ -489,4 +499,37 @@ class HermesACPAgent(acp.Agent):
            )
            self.session_manager.save_session(session_id)
            logger.info("Session %s: model switched to %s", session_id, model_id)
+            return SetSessionModelResponse()
+        logger.warning("Session %s: model switch requested for missing session", session_id)
        return None
+
+    async def set_session_mode(
+        self, mode_id: str, session_id: str, **kwargs: Any
+    ) -> SetSessionModeResponse | None:
+        """Persist the editor-requested mode so ACP clients do not fail on mode switches."""
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            logger.warning("Session %s: mode switch requested for missing session", session_id)
+            return None
+        setattr(state, "mode", mode_id)
+        self.session_manager.save_session(session_id)
+        logger.info("Session %s: mode switched to %s", session_id, mode_id)
+        return SetSessionModeResponse()
+
+    async def set_config_option(
+        self, config_id: str, session_id: str, value: str, **kwargs: Any
+    ) -> SetSessionConfigOptionResponse | None:
+        """Accept ACP config option updates even when Hermes has no typed ACP config surface yet."""
+        state = self.session_manager.get_session(session_id)
+        if state is None:
+            logger.warning("Session %s: config update requested for missing session", session_id)
+            return None
+
+        options = getattr(state, "config_options", None)
+        if not isinstance(options, dict):
+            options = {}
+        options[str(config_id)] = value
+        setattr(state, "config_options", options)
+        self.session_manager.save_session(session_id)
+        logger.info("Session %s: config option %s updated", session_id, config_id)
+        return SetSessionConfigOptionResponse(config_options=[])
@@ -627,8 +627,6 @@ def _resolve_custom_runtime() -> Tuple[Optional[str], Optional[str]]:
    custom_key = runtime.get("api_key")
    if not isinstance(custom_base, str) or not custom_base.strip():
        return None, None
-    if not isinstance(custom_key, str) or not custom_key.strip():
-        return None, None

    custom_base = custom_base.strip().rstrip("/")
    if "openrouter.ai" in custom_base.lower():
@@ -636,6 +634,13 @@ def _resolve_custom_runtime() -> Tuple[Optional[str], Optional[str]]:
        # configured. Treat that as "no custom endpoint" for auxiliary routing.
        return None, None

+    # Local servers (Ollama, llama.cpp, vLLM, LM Studio) don't require auth.
+    # Use a placeholder key — the OpenAI SDK requires a non-empty string but
+    # local servers ignore the Authorization header.  Same fix as cli.py
+    # _ensure_runtime_credentials() (PR #2556).
+    if not isinstance(custom_key, str) or not custom_key.strip():
+        custom_key = "no-key-required"
+
    return custom_base, custom_key.strip()


@@ -737,16 +742,37 @@ def _resolve_forced_provider(forced: str) -> Tuple[Optional[OpenAI], Optional[st
    return None, None


+_AUTO_PROVIDER_LABELS = {
+    "_try_openrouter": "openrouter",
+    "_try_nous": "nous",
+    "_try_custom_endpoint": "local/custom",
+    "_try_codex": "openai-codex",
+    "_resolve_api_key_provider": "api-key",
+}
+
+
 def _resolve_auto() -> Tuple[Optional[OpenAI], Optional[str]]:
    """Full auto-detection chain: OpenRouter → Nous → custom → Codex → API-key → None."""
    global auxiliary_is_nous
    auxiliary_is_nous = False  # Reset — _try_nous() will set True if it wins
+    tried = []
    for try_fn in (_try_openrouter, _try_nous, _try_custom_endpoint,
                   _try_codex, _resolve_api_key_provider):
+        fn_name = getattr(try_fn, "__name__", "unknown")
+        label = _AUTO_PROVIDER_LABELS.get(fn_name, fn_name)
        client, model = try_fn()
        if client is not None:
+            if tried:
+                logger.info("Auxiliary auto-detect: using %s (%s) — skipped: %s",
+                            label, model or "default", ", ".join(tried))
+            else:
+                logger.info("Auxiliary auto-detect: using %s (%s)", label, model or "default")
            return client, model
-    logger.debug("Auxiliary client: none available")
+        tried.append(label)
+    logger.warning("Auxiliary auto-detect: no provider available (tried: %s). "
+                   "Compression, summarization, and memory flush will not work. "
+                   "Set OPENROUTER_API_KEY or configure a local model in config.yaml.",
+                   ", ".join(tried))
    return None, None


@@ -897,11 +923,12 @@ def resolve_provider_client(
            custom_key = (
                (explicit_api_key or "").strip()
                or os.getenv("OPENAI_API_KEY", "").strip()
+                or "no-key-required"  # local servers don't need auth
            )
-            if not custom_base or not custom_key:
+            if not custom_base:
                logger.warning(
                    "resolve_provider_client: explicit custom endpoint requested "
-                    "but no API key was found (set explicit_api_key or OPENAI_API_KEY)"
+                    "but base_url is empty"
                )
                return None, None
            final_model = model or _read_main_model() or "gpt-4o-mini"
@@ -1612,8 +1639,8 @@ def call_llm(
                )
            # For auto/custom, fall back to OpenRouter
            if not resolved_base_url:
-                logger.warning("Provider %s unavailable, falling back to openrouter",
-                               resolved_provider)
+                logger.info("Auxiliary %s: provider %s unavailable, falling back to openrouter",
+                            task or "call", resolved_provider)
                client, final_model = _get_cached_client(
                    "openrouter", resolved_model or _OPENROUTER_MODEL)
        if client is None:
@@ -1623,6 +1650,13 @@ def call_llm(

    effective_timeout = timeout if timeout is not None else _get_task_timeout(task)

+    # Log what we're about to do — makes auxiliary operations visible
+    _base_info = str(getattr(client, "base_url", resolved_base_url) or "")
+    if task:
+        logger.info("Auxiliary %s: using %s (%s)%s",
+                     task, resolved_provider or "auto", final_model or "default",
+                     f" at {_base_info}" if _base_info and "openrouter" not in _base_info else "")
+
    kwargs = _build_call_kwargs(
        resolved_provider, final_model, messages,
        temperature=temperature, max_tokens=max_tokens,
@@ -17,6 +17,23 @@ _RESET = "\033[0m"

 logger = logging.getLogger(__name__)

+# =========================================================================
+# Configurable tool preview length (0 = no limit)
+# Set once at startup by CLI or gateway from display.tool_preview_length config.
+# =========================================================================
+_tool_preview_max_len: int = 0  # 0 = unlimited
+
+
+def set_tool_preview_max_len(n: int) -> None:
+    """Set the global max length for tool call previews. 0 = no limit."""
+    global _tool_preview_max_len
+    _tool_preview_max_len = max(int(n), 0) if n else 0
+
+
+def get_tool_preview_max_len() -> int:
+    """Return the configured max preview length (0 = unlimited)."""
+    return _tool_preview_max_len
+

 # =========================================================================
 # Skin-aware helpers (lazy import to avoid circular deps)
@@ -94,8 +111,14 @@ def _oneline(text: str) -> str:
    return " ".join(text.split())


-def build_tool_preview(tool_name: str, args: dict, max_len: int = 40) -> str | None:
-    """Build a short preview of a tool call's primary argument for display."""
+def build_tool_preview(tool_name: str, args: dict, max_len: int | None = None) -> str | None:
+    """Build a short preview of a tool call's primary argument for display.
+
+    *max_len* controls truncation.  ``None`` (default) defers to the global
+    ``_tool_preview_max_len`` set via config; ``0`` means unlimited.
+    """
+    if max_len is None:
+        max_len = _tool_preview_max_len
    if not args:
        return None
    primary_args = {
@@ -190,7 +213,7 @@ def build_tool_preview(tool_name: str, args: dict, max_len: int = 40) -> str | N
    preview = _oneline(str(value))
    if not preview:
        return None
-    if len(preview) > max_len:
+    if max_len > 0 and len(preview) > max_len:
        preview = preview[:max_len - 3] + "..."
    return preview

@@ -484,10 +507,14 @@ def get_cute_tool_message(

    def _trunc(s, n=40):
        s = str(s)
+        if _tool_preview_max_len == 0:
+            return s  # no limit
        return (s[:n-3] + "...") if len(s) > n else s

    def _path(p, n=35):
        p = str(p)
+        if _tool_preview_max_len == 0:
+            return p  # no limit
        return ("..." + p[-(n-3):]) if len(p) > n else p

    def _wrap(line: str) -> str:
@@ -171,6 +171,7 @@ _URL_TO_PROVIDER: Dict[str, str] = {
    "dashscope.aliyuncs.com": "alibaba",
    "dashscope-intl.aliyuncs.com": "alibaba",
    "openrouter.ai": "openrouter",
+    "generativelanguage.googleapis.com": "google",
    "inference-api.nousresearch.com": "nous",
    "api.deepseek.com": "deepseek",
    "api.githubcopilot.com": "copilot",
@@ -18,6 +18,7 @@ from typing import Optional
 from agent.skill_utils import (
    extract_skill_conditions,
    extract_skill_description,
+    get_all_skills_dirs,
    get_disabled_skill_names,
    iter_skill_index_files,
    parse_frontmatter,
@@ -444,16 +445,23 @@ def build_skills_system_prompt(
         mtime/size manifest — survives process restarts

    Falls back to a full filesystem scan when both layers miss.
+
+    External skill directories (``skills.external_dirs`` in config.yaml) are
+    scanned alongside the local ``~/.hermes/skills/`` directory.  External dirs
+    are read-only — they appear in the index but new skills are always created
+    in the local dir.  Local skills take precedence when names collide.
    """
    hermes_home = get_hermes_home()
    skills_dir = hermes_home / "skills"
+    external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)

-    if not skills_dir.exists():
+    if not skills_dir.exists() and not external_dirs:
        return ""

    # ── Layer 1: in-process LRU cache ─────────────────────────────────
    cache_key = (
        str(skills_dir.resolve()),
+        tuple(str(d) for d in external_dirs),
        tuple(sorted(str(t) for t in (available_tools or set()))),
        tuple(sorted(str(ts) for ts in (available_toolsets or set()))),
    )
@@ -540,6 +548,56 @@ def build_skills_system_prompt(
            category_descriptions,
        )

+    # ── External skill directories ─────────────────────────────────────
+    # Scan external dirs directly (no snapshot caching — they're read-only
+    # and typically small).  Local skills already in skills_by_category take
+    # precedence: we track seen names and skip duplicates from external dirs.
+    seen_skill_names: set[str] = set()
+    for cat_skills in skills_by_category.values():
+        for name, _desc in cat_skills:
+            seen_skill_names.add(name)
+
+    for ext_dir in external_dirs:
+        if not ext_dir.exists():
+            continue
+        for skill_file in iter_skill_index_files(ext_dir, "SKILL.md"):
+            try:
+                is_compatible, frontmatter, desc = _parse_skill_file(skill_file)
+                if not is_compatible:
+                    continue
+                entry = _build_snapshot_entry(skill_file, ext_dir, frontmatter, desc)
+                skill_name = entry["skill_name"]
+                if skill_name in seen_skill_names:
+                    continue
+                if entry["frontmatter_name"] in disabled or skill_name in disabled:
+                    continue
+                if not _skill_should_show(
+                    extract_skill_conditions(frontmatter),
+                    available_tools,
+                    available_toolsets,
+                ):
+                    continue
+                seen_skill_names.add(skill_name)
+                skills_by_category.setdefault(entry["category"], []).append(
+                    (skill_name, entry["description"])
+                )
+            except Exception as e:
+                logger.debug("Error reading external skill %s: %s", skill_file, e)
+
+        # External category descriptions
+        for desc_file in iter_skill_index_files(ext_dir, "DESCRIPTION.md"):
+            try:
+                content = desc_file.read_text(encoding="utf-8")
+                fm, _ = parse_frontmatter(content)
+                cat_desc = fm.get("description")
+                if not cat_desc:
+                    continue
+                rel = desc_file.relative_to(ext_dir)
+                cat = "/".join(rel.parts[:-1]) if len(rel.parts) > 1 else "general"
+                category_descriptions.setdefault(cat, str(cat_desc).strip().strip("'\""))
+            except Exception as e:
+                logger.debug("Could not read external skill description %s: %s", desc_file, e)
+
    if not skills_by_category:
        result = ""
    else:
@@ -37,6 +37,9 @@ _PREFIX_PATTERNS = [
    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
+    r"sk_[A-Za-z0-9_]{10,}",            # ElevenLabs TTS key (sk_ underscore, not sk- dash)
+    r"tvly-[A-Za-z0-9]{10,}",           # Tavily search API key
+    r"exa_[A-Za-z0-9]{10,}",            # Exa search API key
 ]

 # ENV assignment patterns: KEY=value where KEY contains a secret-like name
@@ -128,7 +128,11 @@ def _build_skill_message(
                        supporting.append(rel)

    if supporting and skill_dir:
-        skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
+        try:
+            skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
+        except ValueError:
+            # Skill is from an external dir — use the skill name instead
+            skill_view_target = skill_dir.name
        parts.append("")
        parts.append("[This skill has supporting files you can load with the skill_view tool:]")
        for sf in supporting:
@@ -158,38 +162,49 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
    _skill_commands = {}
    try:
        from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, _get_disabled_skill_names
-        if not SKILLS_DIR.exists():
-            return _skill_commands
+        from agent.skill_utils import get_external_skills_dirs
        disabled = _get_disabled_skill_names()
-        for skill_md in SKILLS_DIR.rglob("SKILL.md"):
-            if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
-                continue
-            try:
-                content = skill_md.read_text(encoding='utf-8')
-                frontmatter, body = _parse_frontmatter(content)
-                # Skip skills incompatible with the current OS platform
-                if not skill_matches_platform(frontmatter):
+        seen_names: set = set()
+
+        # Scan local dir first, then external dirs
+        dirs_to_scan = []
+        if SKILLS_DIR.exists():
+            dirs_to_scan.append(SKILLS_DIR)
+        dirs_to_scan.extend(get_external_skills_dirs())
+
+        for scan_dir in dirs_to_scan:
+            for skill_md in scan_dir.rglob("SKILL.md"):
+                if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
                    continue
-                name = frontmatter.get('name', skill_md.parent.name)
-                # Respect user's disabled skills config
-                if name in disabled:
+                try:
+                    content = skill_md.read_text(encoding='utf-8')
+                    frontmatter, body = _parse_frontmatter(content)
+                    # Skip skills incompatible with the current OS platform
+                    if not skill_matches_platform(frontmatter):
+                        continue
+                    name = frontmatter.get('name', skill_md.parent.name)
+                    if name in seen_names:
+                        continue
+                    # Respect user's disabled skills config
+                    if name in disabled:
+                        continue
+                    description = frontmatter.get('description', '')
+                    if not description:
+                        for line in body.strip().split('\n'):
+                            line = line.strip()
+                            if line and not line.startswith('#'):
+                                description = line[:80]
+                                break
+                    seen_names.add(name)
+                    cmd_name = name.lower().replace(' ', '-').replace('_', '-')
+                    _skill_commands[f"/{cmd_name}"] = {
+                        "name": name,
+                        "description": description or f"Invoke the {name} skill",
+                        "skill_md_path": str(skill_md),
+                        "skill_dir": str(skill_md.parent),
+                    }
+                except Exception:
                    continue
-                description = frontmatter.get('description', '')
-                if not description:
-                    for line in body.strip().split('\n'):
-                        line = line.strip()
-                        if line and not line.startswith('#'):
-                            description = line[:80]
-                            break
-                cmd_name = name.lower().replace(' ', '-').replace('_', '-')
-                _skill_commands[f"/{cmd_name}"] = {
-                    "name": name,
-                    "description": description or f"Invoke the {name} skill",
-                    "skill_md_path": str(skill_md),
-                    "skill_dir": str(skill_md.parent),
-                }
-            except Exception:
-                continue
    except Exception:
        pass
    return _skill_commands
@@ -158,6 +158,73 @@ def _normalize_string_set(values) -> Set[str]:
    return {str(v).strip() for v in values if str(v).strip()}


+# ── External skills directories ──────────────────────────────────────────
+
+
+def get_external_skills_dirs() -> List[Path]:
+    """Read ``skills.external_dirs`` from config.yaml and return validated paths.
+
+    Each entry is expanded (``~`` and ``${VAR}``) and resolved to an absolute
+    path.  Only directories that actually exist are returned.  Duplicates and
+    paths that resolve to the local ``~/.hermes/skills/`` are silently skipped.
+    """
+    config_path = get_hermes_home() / "config.yaml"
+    if not config_path.exists():
+        return []
+    try:
+        parsed = yaml_load(config_path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+    if not isinstance(parsed, dict):
+        return []
+
+    skills_cfg = parsed.get("skills")
+    if not isinstance(skills_cfg, dict):
+        return []
+
+    raw_dirs = skills_cfg.get("external_dirs")
+    if not raw_dirs:
+        return []
+    if isinstance(raw_dirs, str):
+        raw_dirs = [raw_dirs]
+    if not isinstance(raw_dirs, list):
+        return []
+
+    local_skills = (get_hermes_home() / "skills").resolve()
+    seen: Set[Path] = set()
+    result: List[Path] = []
+
+    for entry in raw_dirs:
+        entry = str(entry).strip()
+        if not entry:
+            continue
+        # Expand ~ and environment variables
+        expanded = os.path.expanduser(os.path.expandvars(entry))
+        p = Path(expanded).resolve()
+        if p == local_skills:
+            continue
+        if p in seen:
+            continue
+        if p.is_dir():
+            seen.add(p)
+            result.append(p)
+        else:
+            logger.debug("External skills dir does not exist, skipping: %s", p)
+
+    return result
+
+
+def get_all_skills_dirs() -> List[Path]:
+    """Return all skill directories: local ``~/.hermes/skills/`` first, then external.
+
+    The local dir is always first (and always included even if it doesn't exist
+    yet — callers handle that).  External dirs follow in config order.
+    """
+    dirs = [get_hermes_home() / "skills"]
+    dirs.extend(get_external_skills_dirs())
+    return dirs
+
+
 # ── Condition extraction ──────────────────────────────────────────────────


@@ -11,14 +11,29 @@ model:
  default: "anthropic/claude-opus-4.6"
  
  # Inference provider selection:
-  #   "auto"       - Use Nous Portal if logged in, otherwise OpenRouter/env vars (default)
-  #   "nous-api"   - Use Nous Portal via API key (requires: NOUS_API_KEY)
-  #   "openrouter" - Always use OpenRouter API key from OPENROUTER_API_KEY
-  #   "nous"       - Always use Nous Portal (requires: hermes login)
-  #   "zai"        - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)
-  #   "kimi-coding"- Use Kimi / Moonshot AI models (requires: KIMI_API_KEY)
-  #   "minimax"    - Use MiniMax global endpoint (requires: MINIMAX_API_KEY)
-  #   "minimax-cn" - Use MiniMax China endpoint (requires: MINIMAX_CN_API_KEY)
+  #   "auto"         - Auto-detect from credentials (default)
+  #   "openrouter"   - OpenRouter (requires: OPENROUTER_API_KEY or OPENAI_API_KEY)
+  #   "nous"         - Nous Portal OAuth (requires: hermes login)
+  #   "nous-api"     - Nous Portal API key (requires: NOUS_API_KEY)
+  #   "anthropic"    - Direct Anthropic API (requires: ANTHROPIC_API_KEY)
+  #   "openai-codex" - OpenAI Codex (requires: hermes login --provider openai-codex)
+  #   "copilot"      - GitHub Copilot / GitHub Models (requires: GITHUB_TOKEN)
+  #   "zai"          - z.ai / ZhipuAI GLM (requires: GLM_API_KEY)
+  #   "kimi-coding"  - Kimi / Moonshot AI (requires: KIMI_API_KEY)
+  #   "minimax"      - MiniMax global (requires: MINIMAX_API_KEY)
+  #   "minimax-cn"   - MiniMax China (requires: MINIMAX_CN_API_KEY)
+  #   "huggingface"  - Hugging Face Inference (requires: HF_TOKEN)
+  #   "kilocode"     - KiloCode gateway (requires: KILOCODE_API_KEY)
+  #   "ai-gateway"   - Vercel AI Gateway (requires: AI_GATEWAY_API_KEY)
+  #
+  # Local servers (LM Studio, Ollama, vLLM, llama.cpp):
+  #   "custom"       - Any OpenAI-compatible endpoint. Set base_url below.
+  #   Aliases: "lmstudio", "ollama", "vllm", "llamacpp" all map to "custom".
+  #   Example for LM Studio:
+  #     provider: "lmstudio"
+  #     base_url: "http://localhost:1234/v1"
+  #   No API key needed — local servers typically ignore auth.
+  #
  # Can also be overridden with --provider flag or HERMES_INFERENCE_PROVIDER env var.
  provider: "auto"
  
@@ -309,6 +324,9 @@ compression:
 #   vision:
 #     provider: "auto"
 #     model: ""              # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"
+#     timeout: 30            # LLM API call timeout (seconds)
+#     download_timeout: 30   # Image HTTP download timeout (seconds)
+#                            # Increase for slow connections or self-hosted image servers
 #
 #   # Web page scraping / summarization + browser page text extraction
 #   web_extract:
@@ -402,6 +420,15 @@ skills:
  # Set to 0 to disable.
  creation_nudge_interval: 15

+  # External skill directories — share skills across tools/agents without
+  # copying them into ~/.hermes/skills/.  Each path is expanded (~ and ${VAR})
+  # and resolved to an absolute path.  External dirs are read-only: skill
+  # creation always writes to ~/.hermes/skills/.  Local skills take precedence
+  # when names collide.
+  # external_dirs:
+  #   - ~/.agents/skills
+  #   - /home/shared/team-skills
+
 # =============================================================================
 # Agent Behavior
 # =============================================================================
@@ -70,7 +70,7 @@ _COMMAND_SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧

 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
-from hermes_constants import get_hermes_home, OPENROUTER_BASE_URL
+from hermes_constants import get_hermes_home, display_hermes_home, OPENROUTER_BASE_URL
 from hermes_cli.env_loader import load_hermes_dotenv

 _hermes_home = get_hermes_home()
@@ -449,6 +449,14 @@ try:
 except Exception:
    pass  # Skin engine is optional — default skin used if unavailable

+# Initialize tool preview length from config
+try:
+    from agent.display import set_tool_preview_max_len
+    _tpl = CLI_CONFIG.get("display", {}).get("tool_preview_length", 0)
+    set_tool_preview_max_len(int(_tpl) if _tpl else 0)
+except Exception:
+    pass
+
 # Neuter AsyncHttpxClientWrapper.__del__ before any AsyncOpenAI clients are
 # created.  The SDK's __del__ schedules aclose() on asyncio.get_running_loop()
 # which, during CLI idle time, finds prompt_toolkit's event loop and tries to
@@ -1079,10 +1087,10 @@ class HermesCLI:
        # env vars would stomp each other.
        _model_config = CLI_CONFIG.get("model", {})
        _config_model = (_model_config.get("default") or _model_config.get("model") or "") if isinstance(_model_config, dict) else (_model_config or "")
-        _FALLBACK_MODEL = "anthropic/claude-opus-4.6"
-        self.model = model or _config_model or _FALLBACK_MODEL
-        # Auto-detect model from local server if still on fallback
-        if self.model == _FALLBACK_MODEL:
+        _DEFAULT_CONFIG_MODEL = "anthropic/claude-opus-4.6"
+        self.model = model or _config_model or _DEFAULT_CONFIG_MODEL
+        # Auto-detect model from local server if still on default
+        if self.model == _DEFAULT_CONFIG_MODEL:
            _base_url = (_model_config.get("base_url") or "") if isinstance(_model_config, dict) else ""
            if "localhost" in _base_url or "127.0.0.1" in _base_url:
                from hermes_cli.runtime_provider import _auto_detect_local_model
@@ -1096,7 +1104,7 @@ class HermesCLI:
        # explicit choice — the user just never changed it.  But a config model
        # like "gpt-5.3-codex" IS explicit and must be preserved.
        self._model_is_default = not model and (
-            not _config_model or _config_model == _FALLBACK_MODEL
+            not _config_model or _config_model == _DEFAULT_CONFIG_MODEL
        )

        self._explicit_api_key = api_key
@@ -1182,9 +1190,13 @@ 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
+        # Fallback provider chain — tried in order when primary fails after retries.
+        # Supports new list format (fallback_providers) and legacy single-dict (fallback_model).
+        fb = CLI_CONFIG.get("fallback_providers") or CLI_CONFIG.get("fallback_model") or []
+        # Normalize legacy single-dict to a one-element list
+        if isinstance(fb, dict):
+            fb = [fb] if fb.get("provider") and fb.get("model") else []
+        self._fallback_model = fb

        # Optional cheap-vs-strong routing for simple turns
        self._smart_model_routing = CLI_CONFIG.get("smart_model_routing", {}) or {}
@@ -1343,6 +1355,49 @@ class HermesCLI:

        return snapshot

+    @staticmethod
+    def _status_bar_display_width(text: str) -> int:
+        """Return terminal cell width for status-bar text.
+
+        len() is not enough for prompt_toolkit layout decisions because some
+        glyphs can render wider than one Python codepoint. Keeping the status
+        bar within the real display width prevents it from wrapping onto a
+        second line and leaving behind duplicate rows.
+        """
+        try:
+            from prompt_toolkit.utils import get_cwidth
+            return get_cwidth(text or "")
+        except Exception:
+            return len(text or "")
+
+    @classmethod
+    def _trim_status_bar_text(cls, text: str, max_width: int) -> str:
+        """Trim status-bar text to a single terminal row."""
+        if max_width <= 0:
+            return ""
+        try:
+            from prompt_toolkit.utils import get_cwidth
+        except Exception:
+            get_cwidth = None
+
+        if cls._status_bar_display_width(text) <= max_width:
+            return text
+
+        ellipsis = "..."
+        ellipsis_width = cls._status_bar_display_width(ellipsis)
+        if max_width <= ellipsis_width:
+            return ellipsis[:max_width]
+
+        out = []
+        width = 0
+        for ch in text:
+            ch_width = get_cwidth(ch) if get_cwidth else len(ch)
+            if width + ch_width + ellipsis_width > max_width:
+                break
+            out.append(ch)
+            width += ch_width
+        return "".join(out).rstrip() + ellipsis
+
    def _build_status_bar_text(self, width: Optional[int] = None) -> str:
        try:
            snapshot = self._get_status_bar_snapshot()
@@ -1357,11 +1412,12 @@ class HermesCLI:
            duration_label = snapshot["duration"]

            if width < 52:
-                return f"⚕ {snapshot['model_short']} · {duration_label}"
+                text = f"⚕ {snapshot['model_short']} · {duration_label}"
+                return self._trim_status_bar_text(text, width)
            if width < 76:
                parts = [f"⚕ {snapshot['model_short']}", percent_label]
                parts.append(duration_label)
-                return " · ".join(parts)
+                return self._trim_status_bar_text(" · ".join(parts), width)

            if snapshot["context_length"]:
                ctx_total = _format_context_length(snapshot["context_length"])
@@ -1372,7 +1428,7 @@ class HermesCLI:

            parts = [f"⚕ {snapshot['model_short']}", context_label, percent_label]
            parts.append(duration_label)
-            return " │ ".join(parts)
+            return self._trim_status_bar_text(" │ ".join(parts), width)
        except Exception:
            return f"⚕ {self.model if getattr(self, 'model', None) else 'Hermes'}"

@@ -1394,53 +1450,54 @@ class HermesCLI:
            duration_label = snapshot["duration"]

            if width < 52:
-                return [
-                    ("class:status-bar", " ⚕ "),
-                    ("class:status-bar-strong", snapshot["model_short"]),
-                    ("class:status-bar-dim", " · "),
-                    ("class:status-bar-dim", duration_label),
-                    ("class:status-bar", " "),
-                ]
-
-            percent = snapshot["context_percent"]
-            percent_label = f"{percent}%" if percent is not None else "--"
-            if width < 76:
                frags = [
                    ("class:status-bar", " ⚕ "),
                    ("class:status-bar-strong", snapshot["model_short"]),
-                    ("class:status-bar-dim", " · "),
-                    (self._status_bar_context_style(percent), percent_label),
-                ]
-                frags.extend([
                    ("class:status-bar-dim", " · "),
                    ("class:status-bar-dim", duration_label),
                    ("class:status-bar", " "),
-                ])
-                return frags
-
-            if snapshot["context_length"]:
-                ctx_total = _format_context_length(snapshot["context_length"])
-                ctx_used = format_token_count_compact(snapshot["context_tokens"])
-                context_label = f"{ctx_used}/{ctx_total}"
+                ]
            else:
-                context_label = "ctx --"
+                percent = snapshot["context_percent"]
+                percent_label = f"{percent}%" if percent is not None else "--"
+                if width < 76:
+                    frags = [
+                        ("class:status-bar", " ⚕ "),
+                        ("class:status-bar-strong", snapshot["model_short"]),
+                        ("class:status-bar-dim", " · "),
+                        (self._status_bar_context_style(percent), percent_label),
+                        ("class:status-bar-dim", " · "),
+                        ("class:status-bar-dim", duration_label),
+                        ("class:status-bar", " "),
+                    ]
+                else:
+                    if snapshot["context_length"]:
+                        ctx_total = _format_context_length(snapshot["context_length"])
+                        ctx_used = format_token_count_compact(snapshot["context_tokens"])
+                        context_label = f"{ctx_used}/{ctx_total}"
+                    else:
+                        context_label = "ctx --"

-            bar_style = self._status_bar_context_style(percent)
-            frags = [
-                ("class:status-bar", " ⚕ "),
-                ("class:status-bar-strong", snapshot["model_short"]),
-                ("class:status-bar-dim", " │ "),
-                ("class:status-bar-dim", context_label),
-                ("class:status-bar-dim", " │ "),
-                (bar_style, self._build_context_bar(percent)),
-                ("class:status-bar-dim", " "),
-                (bar_style, percent_label),
-            ]
-            frags.extend([
-                ("class:status-bar-dim", " │ "),
-                ("class:status-bar-dim", duration_label),
-                ("class:status-bar", " "),
-            ])
+                    bar_style = self._status_bar_context_style(percent)
+                    frags = [
+                        ("class:status-bar", " ⚕ "),
+                        ("class:status-bar-strong", snapshot["model_short"]),
+                        ("class:status-bar-dim", " │ "),
+                        ("class:status-bar-dim", context_label),
+                        ("class:status-bar-dim", " │ "),
+                        (bar_style, self._build_context_bar(percent)),
+                        ("class:status-bar-dim", " "),
+                        (bar_style, percent_label),
+                        ("class:status-bar-dim", " │ "),
+                        ("class:status-bar-dim", duration_label),
+                        ("class:status-bar", " "),
+                    ]
+
+            total_width = sum(self._status_bar_display_width(text) for _, text in frags)
+            if total_width > width:
+                plain_text = "".join(text for _, text in frags)
+                trimmed = self._trim_status_bar_text(plain_text, width)
+                return [("class:status-bar", trimmed)]
            return frags
        except Exception:
            return [("class:status-bar", f" {self._build_status_bar_text()} ")]
@@ -2732,22 +2789,12 @@ class HermesCLI:
            print(f"  MCP tool:          /tools {subcommand} github:create_issue")
            return

-        # Confirm session reset before applying
-        verb = "Disable" if subcommand == "disable" else "Enable"
+        # Apply the change directly — the user typing the command is implicit
+        # consent.  Do NOT use input() here; it hangs inside prompt_toolkit's
+        # TUI event loop (known pitfall).
+        verb = "Disabling" if subcommand == "disable" else "Enabling"
        label = ", ".join(names)
-        _cprint(f"{_GOLD}{verb} {label}?{_RST}")
-        _cprint(f"{_DIM}This will save to config and reset your session so the "
-                f"change takes effect cleanly.{_RST}")
-        try:
-            answer = input("  Continue? [y/N] ").strip().lower()
-        except (EOFError, KeyboardInterrupt):
-            print()
-            _cprint(f"{_DIM}Cancelled.{_RST}")
-            return
-
-        if answer not in ("y", "yes"):
-            _cprint(f"{_DIM}Cancelled.{_RST}")
-            return
+        _cprint(f"{_GOLD}{verb} {label}...{_RST}")

        tools_disable_enable_command(
            Namespace(tools_action=subcommand, names=names, platform="cli"))
@@ -3594,7 +3641,7 @@ class HermesCLI:
            print("  To start the gateway:")
            print("    python cli.py --gateway")
            print()
-            print("  Configuration file: ~/.hermes/config.yaml")
+            print(f"  Configuration file: {display_hermes_home()}/config.yaml")
            print()
            
        except Exception as e:
@@ -3604,7 +3651,7 @@ class HermesCLI:
            print("    1. Set environment variables:")
            print("       TELEGRAM_BOT_TOKEN=your_token")
            print("       DISCORD_BOT_TOKEN=your_token")
-            print("    2. Or configure settings in ~/.hermes/config.yaml")
+            print(f"    2. Or configure settings in {display_hermes_home()}/config.yaml")
            print()
    
    def process_command(self, command: str) -> bool:
@@ -3789,6 +3836,8 @@ class HermesCLI:
            self.console.print(f"  Status bar {state}")
        elif canonical == "verbose":
            self._toggle_verbose()
+        elif canonical == "yolo":
+            self._toggle_yolo()
        elif canonical == "reasoning":
            self._handle_reasoning_command(cmd_original)
        elif canonical == "compress":
@@ -3811,7 +3860,7 @@ class HermesCLI:
                plugins = mgr.list_plugins()
                if not plugins:
                    print("No plugins installed.")
-                    print("Drop plugin directories into ~/.hermes/plugins/ to get started.")
+                    print(f"Drop plugin directories into {display_hermes_home()}/plugins/ to get started.")
                else:
                    print(f"Plugins ({len(plugins)}):")
                    for p in plugins:
@@ -4340,7 +4389,7 @@ class HermesCLI:
                source = f" ({s['source']})" if s["source"] == "user" else ""
                print(f"   {marker} {s['name']}{source} — {s['description']}")
            print("\n  Usage: /skin <name>")
-            print("  Custom skins: drop a YAML file in ~/.hermes/skins/\n")
+            print(f"  Custom skins: drop a YAML file in {display_hermes_home()}/skins/\n")
            return

        new_skin = parts[1].strip().lower()
@@ -4387,6 +4436,17 @@ class HermesCLI:
        }
        _cprint(labels.get(self.tool_progress_mode, ""))

+    def _toggle_yolo(self):
+        """Toggle YOLO mode — skip all dangerous command approval prompts."""
+        import os
+        current = bool(os.environ.get("HERMES_YOLO_MODE"))
+        if current:
+            os.environ.pop("HERMES_YOLO_MODE", None)
+            self.console.print("  ⚠ YOLO mode [bold red]OFF[/] — dangerous commands will require approval.")
+        else:
+            os.environ["HERMES_YOLO_MODE"] = "1"
+            self.console.print("  ⚡ YOLO mode [bold green]ON[/] — all commands auto-approved. Use with caution.")
+
    def _handle_reasoning_command(self, cmd: str):
        """Handle /reasoning — manage effort level and display toggle.

@@ -4778,8 +4838,10 @@ class HermesCLI:
            from agent.display import get_tool_emoji
            emoji = get_tool_emoji(function_name)
            label = preview or function_name
-            if len(label) > 50:
-                label = label[:47] + "..."
+            from agent.display import get_tool_preview_max_len
+            _pl = get_tool_preview_max_len()
+            if _pl > 0 and len(label) > _pl:
+                label = label[:_pl - 3] + "..."
            self._spinner_text = f"{emoji} {label}"
            self._invalidate()

@@ -5944,6 +6006,9 @@ class HermesCLI:
        ``normal_prompt`` is the full ``branding.prompt_symbol``.
        ``state_suffix`` is what special states (sudo/secret/approval/agent)
        should render after their leading icon.
+
+        When a profile is active (not "default"), the profile name is
+        prepended to the prompt symbol: ``coder ❯`` instead of ``❯``.
        """
        try:
            from hermes_cli.skin_engine import get_active_prompt_symbol
@@ -5952,6 +6017,15 @@ class HermesCLI:
            symbol = "❯ "

        symbol = (symbol or "❯ ").rstrip() + " "
+
+        # Prepend profile name when not default
+        try:
+            from hermes_cli.profiles import get_active_profile_name
+            profile = get_active_profile_name()
+            if profile not in ("default", "custom"):
+                symbol = f"{profile} {symbol}"
+        except Exception:
+            pass
        stripped = symbol.rstrip()
        if not stripped:
            return "❯ ", "❯ "
@@ -6139,6 +6213,11 @@ class HermesCLI:
        self._interrupt_queue = queue.Queue()   # For messages typed while agent is running
        self._should_exit = False
        self._last_ctrl_c_time = 0  # Track double Ctrl+C for force exit
+
+        # Give plugin manager a CLI reference so plugins can inject messages
+        from hermes_cli.plugins import get_plugin_manager
+        get_plugin_manager()._cli_ref = self
+
        # Config file watcher — detect mcp_servers changes and auto-reload
        from hermes_cli.config import get_config_path as _get_config_path
        _cfg_path = _get_config_path()
@@ -6488,6 +6567,24 @@ class HermesCLI:
            self._should_exit = True
            event.app.exit()

+        @kb.add('c-z')
+        def handle_ctrl_z(event):
+            """Handle Ctrl+Z - suspend process to background (Unix only)."""
+            import sys
+            if sys.platform == 'win32':
+                _cprint(f"\n{_DIM}Suspend (Ctrl+Z) is not supported on Windows.{_RST}")
+                event.app.invalidate()
+                return
+            import os, signal as _sig
+            from prompt_toolkit.application import run_in_terminal
+            from hermes_cli.skin_engine import get_active_skin
+            agent_name = get_active_skin().get_branding("agent_name", "Hermes Agent")
+            msg = f"\n{agent_name} has been suspended. Run `fg` to bring {agent_name} back."
+            def _suspend():
+                os.write(1, msg.encode())
+                os.kill(0, _sig.SIGTSTP)
+            run_in_terminal(_suspend)
+
        # Voice push-to-talk key: configurable via config.yaml (voice.record_key)
        # Default: Ctrl+B (avoids conflict with Ctrl+R readline reverse-search)
        # Config uses "ctrl+b" format; prompt_toolkit expects "c-b" format.
@@ -26,6 +26,7 @@ except ImportError:
        msvcrt = None
 from pathlib import Path
 from hermes_constants import get_hermes_home
+from hermes_cli.config import load_config
 from typing import Optional

 from hermes_time import now as _hermes_now
@@ -86,6 +87,22 @@ def _resolve_delivery_target(job: dict) -> Optional[dict]:
            chat_id, thread_id = rest.split(":", 1)
        else:
            chat_id, thread_id = rest, None
+
+        # Resolve human-friendly labels like "Alice (dm)" to real IDs.
+        # send_message(action="list") shows labels with display suffixes
+        # that aren't valid platform IDs (e.g. WhatsApp JIDs).
+        try:
+            from gateway.channel_directory import resolve_channel_name
+            target = chat_id
+            # Strip display suffix like " (dm)" or " (group)"
+            if target.endswith(")") and " (" in target:
+                target = target.rsplit(" (", 1)[0].strip()
+            resolved = resolve_channel_name(platform_name.lower(), target)
+            if resolved:
+                chat_id = resolved
+        except Exception:
+            pass
+
        return {
            "platform": platform_name,
            "chat_id": chat_id,
@@ -145,6 +162,8 @@ def _deliver_result(job: dict, content: str) -> None:
        "mattermost": Platform.MATTERMOST,
        "homeassistant": Platform.HOMEASSISTANT,
        "dingtalk": Platform.DINGTALK,
+        "feishu": Platform.FEISHU,
+        "wecom": Platform.WECOM,
        "email": Platform.EMAIL,
        "sms": Platform.SMS,
    }
@@ -164,18 +183,29 @@ def _deliver_result(job: dict, content: str) -> None:
        logger.warning("Job '%s': platform '%s' not configured/enabled", job["id"], platform_name)
        return

-    # Wrap the content so the user knows this is a cron delivery and that
-    # the interactive agent has no visibility into it.
-    task_name = job.get("name", job["id"])
-    wrapped = (
-        f"Cronjob Response: {task_name}\n"
-        f"-------------\n\n"
-        f"{content}\n\n"
-        f"Note: The agent cannot see this message, and therefore cannot respond to it."
-    )
+    # Optionally wrap the content with a header/footer so the user knows this
+    # is a cron delivery.  Wrapping is on by default; set cron.wrap_response: false
+    # in config.yaml for clean output.
+    wrap_response = True
+    try:
+        user_cfg = load_config()
+        wrap_response = user_cfg.get("cron", {}).get("wrap_response", True)
+    except Exception:
+        pass
+
+    if wrap_response:
+        task_name = job.get("name", job["id"])
+        delivery_content = (
+            f"Cronjob Response: {task_name}\n"
+            f"-------------\n\n"
+            f"{content}\n\n"
+            f"Note: The agent cannot see this message, and therefore cannot respond to it."
+        )
+    else:
+        delivery_content = content

    # Run the async send in a fresh event loop (safe from any thread)
-    coro = _send_to_platform(platform, pconfig, chat_id, wrapped, thread_id=thread_id)
+    coro = _send_to_platform(platform, pconfig, chat_id, delivery_content, thread_id=thread_id)
    try:
        result = asyncio.run(coro)
    except RuntimeError:
@@ -186,7 +216,7 @@ def _deliver_result(job: dict, content: str) -> None:
        coro.close()
        import concurrent.futures
        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, wrapped, thread_id=thread_id))
+            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, delivery_content, thread_id=thread_id))
            result = future.result(timeout=30)
    except Exception as e:
        logger.error("Job '%s': delivery to %s:%s failed: %s", job["id"], platform_name, chat_id, e)
@@ -206,11 +236,12 @@ def _build_job_prompt(job: dict) -> str:
    # Always prepend [SILENT] guidance so the cron agent can suppress
    # delivery when it has nothing new or noteworthy to report.
    silent_hint = (
-        "[SYSTEM: If you have nothing new or noteworthy to report, respond "
-        "with exactly \"[SILENT]\" (optionally followed by a brief internal "
-        "note). This suppresses delivery to the user while still saving "
-        "output locally. Only use [SILENT] when there are genuinely no "
-        "changes worth reporting.]\n\n"
+        "[SYSTEM: If you have a meaningful status report or findings, "
+        "send them — that is the whole point of this job. Only respond "
+        "with exactly \"[SILENT]\" (nothing else) when there is genuinely "
+        "nothing new to report. [SILENT] suppresses delivery to the user. "
+        "Never combine [SILENT] with content — either report your "
+        "findings normally, or say [SILENT] and nothing more.]\n\n"
    )
    prompt = silent_hint + prompt
    if skills is None:
@@ -308,7 +339,7 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
            if delivery_target.get("thread_id") is not None:
                os.environ["HERMES_CRON_AUTO_DELIVER_THREAD_ID"] = str(delivery_target["thread_id"])

-        model = job.get("model") or os.getenv("HERMES_MODEL") or "anthropic/claude-opus-4.6"
+        model = job.get("model") or os.getenv("HERMES_MODEL") or ""

        # Load config.yaml for model, reasoning, prefill, toolsets, provider routing
        _cfg = {}
@@ -5,8 +5,11 @@ set -e
 HERMES_HOME="/opt/data"
 INSTALL_DIR="/opt/hermes"

-# Create directory structure
-mkdir -p "$HERMES_HOME"/{cron,sessions,logs,pairing,hooks,image_cache,audio_cache,memories,skills,whatsapp/session}
+# Create essential directory structure.  Cache and platform directories
+# (cache/images, cache/audio, platforms/whatsapp, etc.) are created on
+# demand by the application — don't pre-create them here so new installs
+# get the consolidated layout from get_hermes_dir().
+mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills}

 # .env
 if [ ! -f "$HERMES_HOME/.env" ]; then
@@ -209,7 +209,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):

            # Agent settings -- TB2 tasks are complex, need many turns
            max_agent_turns=60,
-            max_token_length=***
+            max_token_length=16000,
            agent_temperature=0.6,
            system_prompt=None,

@@ -233,7 +233,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
            steps_per_eval=1,
            total_steps=1,

-            tokenizer_name="NousRe...1-8B",
+            tokenizer_name="NousResearch/Hermes-3-Llama-3.1-8B",
            use_wandb=True,
            wandb_name="terminal-bench-2",
            ensure_scores_are_not_same=False,  # Binary rewards may all be 0 or 1
@@ -245,7 +245,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                base_url="https://openrouter.ai/api/v1",
                model_name="anthropic/claude-sonnet-4",
                server_type="openai",
-                api_key=os.get...EY", ""),
+                api_key=os.getenv("OPENROUTER_API_KEY", ""),
                health_check=False,
            )
        ]
@@ -513,3 +513,446 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                reward = 0.0
            else:
                # Run tests in a thread so the blocking ctx.terminal() calls
+                # don't freeze the entire event loop (which would stall all
+                # other tasks, tqdm updates, and timeout timers).
+                ctx = ToolContext(task_id)
+                try:
+                    loop = asyncio.get_event_loop()
+                    reward = await loop.run_in_executor(
+                        None,  # default thread pool
+                        self._run_tests, eval_item, ctx, task_name,
+                    )
+                except Exception as e:
+                    logger.error("Task %s: test verification failed: %s", task_name, e)
+                    reward = 0.0
+                finally:
+                    ctx.cleanup()
+
+            passed = reward == 1.0
+            status = "PASS" if passed else "FAIL"
+            elapsed = time.time() - task_start
+            tqdm.write(f"  [{status}] {task_name} (turns={result.turns_used}, {elapsed:.0f}s)")
+            logger.info(
+                "Task %s: reward=%.1f, turns=%d, finished=%s",
+                task_name, reward, result.turns_used, result.finished_naturally,
+            )
+
+            out = {
+                "passed": passed,
+                "reward": reward,
+                "task_name": task_name,
+                "category": category,
+                "turns_used": result.turns_used,
+                "finished_naturally": result.finished_naturally,
+                "messages": result.messages,
+            }
+            self._save_result(out)
+            return out
+
+        except Exception as e:
+            elapsed = time.time() - task_start
+            logger.error("Task %s: rollout failed: %s", task_name, e, exc_info=True)
+            tqdm.write(f"  [ERROR] {task_name}: {e} ({elapsed:.0f}s)")
+            out = {
+                "passed": False, "reward": 0.0,
+                "task_name": task_name, "category": category,
+                "error": str(e),
+            }
+            self._save_result(out)
+            return out
+
+        finally:
+            # --- Cleanup: clear overrides, sandbox, and temp files ---
+            clear_task_env_overrides(task_id)
+            try:
+                cleanup_vm(task_id)
+            except Exception as e:
+                logger.debug("VM cleanup for %s: %s", task_id[:8], e)
+            if task_dir and task_dir.exists():
+                shutil.rmtree(task_dir, ignore_errors=True)
+
+    def _run_tests(
+        self, item: Dict[str, Any], ctx: ToolContext, task_name: str
+    ) -> float:
+        """
+        Upload and execute the test suite in the agent's sandbox, then
+        download the verifier output locally to read the reward.
+
+        Follows Harbor's verification pattern:
+        1. Upload tests/ directory into the sandbox
+        2. Execute test.sh inside the sandbox
+        3. Download /logs/verifier/ directory to a local temp dir
+        4. Read reward.txt locally with native Python I/O
+
+        Downloading locally avoids issues with the file_read tool on
+        the Modal VM and matches how Harbor handles verification.
+
+        TB2 test scripts (test.sh) typically:
+        1. Install pytest via uv/pip
+        2. Run pytest against the test files in /tests/
+        3. Write results to /logs/verifier/reward.txt
+
+        Args:
+            item: The TB2 task dict (contains tests_tar, test_sh)
+            ctx: ToolContext scoped to this task's sandbox
+            task_name: For logging
+
+        Returns:
+            1.0 if tests pass, 0.0 otherwise
+        """
+        tests_tar = item.get("tests_tar", "")
+        test_sh = item.get("test_sh", "")
+
+        if not test_sh:
+            logger.warning("Task %s: no test_sh content, reward=0", task_name)
+            return 0.0
+
+        # Create required directories in the sandbox
+        ctx.terminal("mkdir -p /tests /logs/verifier")
+
+        # Upload test files into the sandbox (binary-safe via base64)
+        if tests_tar:
+            tests_temp = Path(tempfile.mkdtemp(prefix=f"tb2-tests-{task_name}-"))
+            try:
+                _extract_base64_tar(tests_tar, tests_temp)
+                ctx.upload_dir(str(tests_temp), "/tests")
+            except Exception as e:
+                logger.warning("Task %s: failed to upload test files: %s", task_name, e)
+            finally:
+                shutil.rmtree(tests_temp, ignore_errors=True)
+
+        # Write the test runner script (test.sh)
+        ctx.write_file("/tests/test.sh", test_sh)
+        ctx.terminal("chmod +x /tests/test.sh")
+
+        # Execute the test suite
+        logger.info(
+            "Task %s: running test suite (timeout=%ds)",
+            task_name, self.config.test_timeout,
+        )
+        test_result = ctx.terminal(
+            "bash /tests/test.sh",
+            timeout=self.config.test_timeout,
+        )
+
+        exit_code = test_result.get("exit_code", -1)
+        output = test_result.get("output", "")
+
+        # Download the verifier output directory locally, then read reward.txt
+        # with native Python I/O. This avoids issues with file_read on the
+        # Modal VM and matches Harbor's verification pattern.
+        reward = 0.0
+        local_verifier_dir = Path(tempfile.mkdtemp(prefix=f"tb2-verifier-{task_name}-"))
+        try:
+            ctx.download_dir("/logs/verifier", str(local_verifier_dir))
+
+            reward_file = local_verifier_dir / "reward.txt"
+            if reward_file.exists() and reward_file.stat().st_size > 0:
+                content = reward_file.read_text().strip()
+                if content == "1":
+                    reward = 1.0
+                elif content == "0":
+                    reward = 0.0
+                else:
+                    # Unexpected content -- try parsing as float
+                    try:
+                        reward = float(content)
+                    except (ValueError, TypeError):
+                        logger.warning(
+                            "Task %s: reward.txt content unexpected (%r), "
+                            "falling back to exit_code=%d",
+                            task_name, content, exit_code,
+                        )
+                        reward = 1.0 if exit_code == 0 else 0.0
+            else:
+                # reward.txt not written -- fall back to exit code
+                logger.warning(
+                    "Task %s: reward.txt not found after download, "
+                    "falling back to exit_code=%d",
+                    task_name, exit_code,
+                )
+                reward = 1.0 if exit_code == 0 else 0.0
+        except Exception as e:
+            logger.warning(
+                "Task %s: failed to download verifier dir: %s, "
+                "falling back to exit_code=%d",
+                task_name, e, exit_code,
+            )
+            reward = 1.0 if exit_code == 0 else 0.0
+        finally:
+            shutil.rmtree(local_verifier_dir, ignore_errors=True)
+
+        # Log test output for debugging failures
+        if reward == 0.0:
+            output_preview = output[-500:] if output else "(no output)"
+            logger.info(
+                "Task %s: FAIL (exit_code=%d)\n%s",
+                task_name, exit_code, output_preview,
+            )
+
+        return reward
+
+    # =========================================================================
+    # Evaluate -- main entry point for the eval subcommand
+    # =========================================================================
+
+    async def _eval_with_timeout(self, item: Dict[str, Any]) -> Dict:
+        """
+        Wrap rollout_and_score_eval with a per-task wall-clock timeout.
+
+        If the task exceeds task_timeout seconds, it's automatically scored
+        as FAIL. This prevents any single task from hanging indefinitely.
+        """
+        task_name = item.get("task_name", "unknown")
+        category = item.get("category", "unknown")
+        try:
+            return await asyncio.wait_for(
+                self.rollout_and_score_eval(item),
+                timeout=self.config.task_timeout,
+            )
+        except asyncio.TimeoutError:
+            from tqdm import tqdm
+            elapsed = self.config.task_timeout
+            tqdm.write(f"  [TIMEOUT] {task_name} (exceeded {elapsed}s wall-clock limit)")
+            logger.error("Task %s: wall-clock timeout after %ds", task_name, elapsed)
+            out = {
+                "passed": False, "reward": 0.0,
+                "task_name": task_name, "category": category,
+                "error": f"timeout ({elapsed}s)",
+            }
+            self._save_result(out)
+            return out
+
+    async def evaluate(self, *args, **kwargs) -> None:
+        """
+        Run Terminal-Bench 2.0 evaluation over all tasks.
+
+        This is the main entry point when invoked via:
+            python environments/terminalbench2_env.py evaluate
+
+        Runs all tasks through rollout_and_score_eval() via asyncio.gather()
+        (same pattern as GPQA and other Atropos eval envs). Each task is
+        wrapped with a wall-clock timeout so hung tasks auto-fail.
+
+        Suppresses noisy Modal/terminal output (HERMES_QUIET) so the tqdm
+        bar stays visible.
+        """
+        start_time = time.time()
+
+        # Route all logging through tqdm.write() so the progress bar stays
+        # pinned at the bottom while log lines scroll above it.
+        from tqdm import tqdm
+
+        class _TqdmHandler(logging.Handler):
+            def emit(self, record):
+                try:
+                    tqdm.write(self.format(record))
+                except Exception:
+                    self.handleError(record)
+
+        handler = _TqdmHandler()
+        handler.setFormatter(logging.Formatter(
+            "%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+            datefmt="%H:%M:%S",
+        ))
+        root = logging.getLogger()
+        root.handlers = [handler]  # Replace any existing handlers
+        root.setLevel(logging.INFO)
+
+        # Silence noisy third-party loggers that flood the output
+        logging.getLogger("httpx").setLevel(logging.WARNING)      # Every HTTP request
+        logging.getLogger("openai").setLevel(logging.WARNING)     # OpenAI client retries
+        logging.getLogger("rex-deploy").setLevel(logging.WARNING) # Swerex deployment
+        logging.getLogger("rex_image_builder").setLevel(logging.WARNING)  # Image builds
+
+        print(f"\n{'='*60}")
+        print("Starting Terminal-Bench 2.0 Evaluation")
+        print(f"{'='*60}")
+        print(f"  Dataset: {self.config.dataset_name}")
+        print(f"  Total tasks: {len(self.all_eval_items)}")
+        print(f"  Max agent turns: {self.config.max_agent_turns}")
+        print(f"  Task timeout: {self.config.task_timeout}s")
+        print(f"  Terminal backend: {self.config.terminal_backend}")
+        print(f"  Tool thread pool: {self.config.tool_pool_size}")
+        print(f"  Terminal timeout: {self.config.terminal_timeout}s/cmd")
+        print(f"  Terminal lifetime: {self.config.terminal_lifetime}s (auto: task_timeout + 120)")
+        print(f"  Max concurrent tasks: {self.config.max_concurrent_tasks}")
+        print(f"{'='*60}\n")
+
+        # Semaphore to limit concurrent Modal sandbox creations.
+        # Without this, all 86 tasks fire simultaneously, each creating a Modal
+        # sandbox via asyncio.run() inside a thread pool worker. Modal's blocking
+        # calls (App.lookup, etc.) deadlock when too many are created at once.
+        semaphore = asyncio.Semaphore(self.config.max_concurrent_tasks)
+
+        async def _eval_with_semaphore(item):
+            async with semaphore:
+                return await self._eval_with_timeout(item)
+
+        # Fire all tasks with wall-clock timeout, track live accuracy on the bar
+        total_tasks = len(self.all_eval_items)
+        eval_tasks = [
+            asyncio.ensure_future(_eval_with_semaphore(item))
+            for item in self.all_eval_items
+        ]
+
+        results = []
+        passed_count = 0
+        pbar = tqdm(total=total_tasks, desc="Evaluating TB2", dynamic_ncols=True)
+        try:
+            for coro in asyncio.as_completed(eval_tasks):
+                result = await coro
+                results.append(result)
+                if result and result.get("passed"):
+                    passed_count += 1
+                done = len(results)
+                pct = (passed_count / done * 100) if done else 0
+                pbar.set_postfix_str(f"pass={passed_count}/{done} ({pct:.1f}%)")
+                pbar.update(1)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            pbar.close()
+            print(f"\n\nInterrupted! Cleaning up {len(eval_tasks)} tasks...")
+            # Cancel all pending tasks
+            for task in eval_tasks:
+                task.cancel()
+            # Let cancellations propagate (finally blocks run cleanup_vm)
+            await asyncio.gather(*eval_tasks, return_exceptions=True)
+            # Belt-and-suspenders: clean up any remaining sandboxes
+            from tools.terminal_tool import cleanup_all_environments
+            cleanup_all_environments()
+            print("All sandboxes cleaned up.")
+            return
+        finally:
+            pbar.close()
+
+        end_time = time.time()
+
+        # Filter out None results (shouldn't happen, but be safe)
+        valid_results = [r for r in results if r is not None]
+
+        if not valid_results:
+            print("Warning: No valid evaluation results obtained")
+            return
+
+        # ---- Compute metrics ----
+        total = len(valid_results)
+        passed = sum(1 for r in valid_results if r.get("passed"))
+        overall_pass_rate = passed / total if total > 0 else 0.0
+
+        # Per-category breakdown
+        cat_results: Dict[str, List[Dict]] = defaultdict(list)
+        for r in valid_results:
+            cat_results[r.get("category", "unknown")].append(r)
+
+        # Build metrics dict
+        eval_metrics = {
+            "eval/pass_rate": overall_pass_rate,
+            "eval/total_tasks": total,
+            "eval/passed_tasks": passed,
+            "eval/evaluation_time_seconds": end_time - start_time,
+        }
+
+        # Per-category metrics
+        for category, cat_items in sorted(cat_results.items()):
+            cat_passed = sum(1 for r in cat_items if r.get("passed"))
+            cat_total = len(cat_items)
+            cat_pass_rate = cat_passed / cat_total if cat_total > 0 else 0.0
+            cat_key = category.replace(" ", "_").replace("-", "_").lower()
+            eval_metrics[f"eval/pass_rate_{cat_key}"] = cat_pass_rate
+
+        # Store metrics for wandb_log
+        self.eval_metrics = [(k, v) for k, v in eval_metrics.items()]
+
+        # ---- Print summary ----
+        print(f"\n{'='*60}")
+        print("Terminal-Bench 2.0 Evaluation Results")
+        print(f"{'='*60}")
+        print(f"Overall Pass Rate: {overall_pass_rate:.4f} ({passed}/{total})")
+        print(f"Evaluation Time: {end_time - start_time:.1f} seconds")
+
+        print("\nCategory Breakdown:")
+        for category, cat_items in sorted(cat_results.items()):
+            cat_passed = sum(1 for r in cat_items if r.get("passed"))
+            cat_total = len(cat_items)
+            cat_rate = cat_passed / cat_total if cat_total > 0 else 0.0
+            print(f"  {category}: {cat_rate:.1%} ({cat_passed}/{cat_total})")
+
+        # Print individual task results
+        print("\nTask Results:")
+        for r in sorted(valid_results, key=lambda x: x.get("task_name", "")):
+            status = "PASS" if r.get("passed") else "FAIL"
+            turns = r.get("turns_used", "?")
+            error = r.get("error", "")
+            extra = f" (error: {error})" if error else ""
+            print(f"  [{status}] {r['task_name']} (turns={turns}){extra}")
+
+        print(f"{'='*60}\n")
+
+        # Build sample records for evaluate_log (includes full conversations)
+        samples = [
+            {
+                "task_name": r.get("task_name"),
+                "category": r.get("category"),
+                "passed": r.get("passed"),
+                "reward": r.get("reward"),
+                "turns_used": r.get("turns_used"),
+                "error": r.get("error"),
+                "messages": r.get("messages"),
+            }
+            for r in valid_results
+        ]
+
+        # Log evaluation results
+        try:
+            await self.evaluate_log(
+                metrics=eval_metrics,
+                samples=samples,
+                start_time=start_time,
+                end_time=end_time,
+                generation_parameters={
+                    "temperature": self.config.agent_temperature,
+                    "max_tokens": self.config.max_token_length,
+                    "max_agent_turns": self.config.max_agent_turns,
+                    "terminal_backend": self.config.terminal_backend,
+                },
+            )
+        except Exception as e:
+            print(f"Error logging evaluation results: {e}")
+
+        # Close streaming file
+        if hasattr(self, "_streaming_file") and not self._streaming_file.closed:
+            self._streaming_file.close()
+            print(f"  Live results saved to: {self._streaming_path}")
+
+        # Kill all remaining sandboxes. Timed-out tasks leave orphaned thread
+        # pool workers still executing commands -- cleanup_all stops them.
+        from tools.terminal_tool import cleanup_all_environments
+        print("\nCleaning up all sandboxes...")
+        cleanup_all_environments()
+
+        # Shut down the tool thread pool so orphaned workers from timed-out
+        # tasks are killed immediately instead of retrying against dead
+        # sandboxes and spamming the console with TimeoutError warnings.
+        from environments.agent_loop import _tool_executor
+        _tool_executor.shutdown(wait=False, cancel_futures=True)
+        print("Done.")
+
+    # =========================================================================
+    # Wandb logging
+    # =========================================================================
+
+    async def wandb_log(self, wandb_metrics: Optional[Dict] = None):
+        """Log TB2-specific metrics to wandb."""
+        if wandb_metrics is None:
+            wandb_metrics = {}
+
+        # Add stored eval metrics
+        for metric_name, metric_value in self.eval_metrics:
+            wandb_metrics[metric_name] = metric_value
+        self.eval_metrics = []
+
+        await super().wandb_log(wandb_metrics)
+
+
+if __name__ == "__main__":
+    TerminalBench2EvalEnv.cli()
@@ -0,0 +1 @@
+"""Built-in gateway hooks that are always registered."""
@@ -0,0 +1,86 @@
+"""Built-in boot-md hook — run ~/.hermes/BOOT.md on gateway startup.
+
+This hook is always registered. It silently skips if no BOOT.md exists.
+To activate, create ``~/.hermes/BOOT.md`` with instructions for the
+agent to execute on every gateway restart.
+
+Example BOOT.md::
+
+    # Startup Checklist
+
+    1. Check if any cron jobs failed overnight
+    2. Send a status update to Discord #general
+    3. If there are errors in /opt/app/deploy.log, summarize them
+
+The agent runs in a background thread so it doesn't block gateway
+startup. If nothing needs attention, it replies with [SILENT] to
+suppress delivery.
+"""
+
+import logging
+import os
+import threading
+from pathlib import Path
+
+logger = logging.getLogger("hooks.boot-md")
+
+HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+BOOT_FILE = HERMES_HOME / "BOOT.md"
+
+
+def _build_boot_prompt(content: str) -> str:
+    """Wrap BOOT.md content in a system-level instruction."""
+    return (
+        "You are running a startup boot checklist. Follow the BOOT.md "
+        "instructions below exactly.\n\n"
+        "---\n"
+        f"{content}\n"
+        "---\n\n"
+        "Execute each instruction. If you need to send a message to a "
+        "platform, use the send_message tool.\n"
+        "If nothing needs attention and there is nothing to report, "
+        "reply with ONLY: [SILENT]"
+    )
+
+
+def _run_boot_agent(content: str) -> None:
+    """Spawn a one-shot agent session to execute the boot instructions."""
+    try:
+        from run_agent import AIAgent
+
+        prompt = _build_boot_prompt(content)
+        agent = AIAgent(
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            max_iterations=20,
+        )
+        result = agent.run_conversation(prompt)
+        response = result.get("final_response", "")
+        if response and "[SILENT]" not in response:
+            logger.info("boot-md completed: %s", response[:200])
+        else:
+            logger.info("boot-md completed (nothing to report)")
+    except Exception as e:
+        logger.error("boot-md agent failed: %s", e)
+
+
+async def handle(event_type: str, context: dict) -> None:
+    """Gateway startup handler — run BOOT.md if it exists."""
+    if not BOOT_FILE.exists():
+        return
+
+    content = BOOT_FILE.read_text(encoding="utf-8").strip()
+    if not content:
+        return
+
+    logger.info("Running BOOT.md (%d chars)", len(content))
+
+    # Run in a background thread so we don't block gateway startup.
+    thread = threading.Thread(
+        target=_run_boot_agent,
+        args=(content,),
+        name="boot-md",
+        daemon=True,
+    )
+    thread.start()
@@ -57,6 +57,8 @@ class Platform(Enum):
    DINGTALK = "dingtalk"
    API_SERVER = "api_server"
    WEBHOOK = "webhook"
+    FEISHU = "feishu"
+    WECOM = "wecom"


@dataclass
@@ -274,6 +276,12 @@ class GatewayConfig:
            # Webhook uses enabled flag only (secrets are per-route)
            elif platform == Platform.WEBHOOK:
                connected.append(platform)
+            # Feishu uses extra dict for app credentials
+            elif platform == Platform.FEISHU and config.extra.get("app_id"):
+                connected.append(platform)
+            # WeCom uses extra dict for bot credentials
+            elif platform == Platform.WECOM and config.extra.get("bot_id"):
+                connected.append(platform)
        return connected
    
    def get_home_channel(self, platform: Platform) -> Optional[HomeChannel]:
@@ -507,6 +515,10 @@ def load_gateway_config() -> GatewayConfig:
                    )
                if "reply_prefix" in platform_cfg:
                    bridged["reply_prefix"] = platform_cfg["reply_prefix"]
+                if "require_mention" in platform_cfg:
+                    bridged["require_mention"] = platform_cfg["require_mention"]
+                if "mention_patterns" in platform_cfg:
+                    bridged["mention_patterns"] = platform_cfg["mention_patterns"]
                if not bridged:
                    continue
                plat_data = platforms_data.setdefault(plat.value, {})
@@ -531,6 +543,20 @@ def load_gateway_config() -> GatewayConfig:
                    os.environ["DISCORD_FREE_RESPONSE_CHANNELS"] = str(frc)
                if "auto_thread" in discord_cfg and not os.getenv("DISCORD_AUTO_THREAD"):
                    os.environ["DISCORD_AUTO_THREAD"] = str(discord_cfg["auto_thread"]).lower()
+
+            # Telegram settings → env vars (env vars take precedence)
+            telegram_cfg = yaml_cfg.get("telegram", {})
+            if isinstance(telegram_cfg, dict):
+                if "require_mention" in telegram_cfg and not os.getenv("TELEGRAM_REQUIRE_MENTION"):
+                    os.environ["TELEGRAM_REQUIRE_MENTION"] = str(telegram_cfg["require_mention"]).lower()
+                if "mention_patterns" in telegram_cfg and not os.getenv("TELEGRAM_MENTION_PATTERNS"):
+                    import json as _json
+                    os.environ["TELEGRAM_MENTION_PATTERNS"] = _json.dumps(telegram_cfg["mention_patterns"])
+                frc = telegram_cfg.get("free_response_chats")
+                if frc is not None and not os.getenv("TELEGRAM_FREE_RESPONSE_CHATS"):
+                    if isinstance(frc, list):
+                        frc = ",".join(str(v) for v in frc)
+                    os.environ["TELEGRAM_FREE_RESPONSE_CHATS"] = str(frc)
    except Exception as e:
        logger.warning(
            "Failed to process config.yaml — falling back to .env / gateway.json values. "
@@ -647,14 +673,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            config.platforms[Platform.SLACK] = PlatformConfig()
        config.platforms[Platform.SLACK].enabled = True
        config.platforms[Platform.SLACK].token = slack_token
-        # Home channel
-        slack_home = os.getenv("SLACK_HOME_CHANNEL")
-        if slack_home:
-            config.platforms[Platform.SLACK].home_channel = HomeChannel(
-                platform=Platform.SLACK,
-                chat_id=slack_home,
-                name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
-            )
+    slack_home = os.getenv("SLACK_HOME_CHANNEL")
+    if slack_home and Platform.SLACK in config.platforms:
+        config.platforms[Platform.SLACK].home_channel = HomeChannel(
+            platform=Platform.SLACK,
+            chat_id=slack_home,
+            name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
+        )
    
    # Signal
    signal_url = os.getenv("SIGNAL_HTTP_URL")
@@ -668,13 +693,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            "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"),
-            )
+    signal_home = os.getenv("SIGNAL_HOME_CHANNEL")
+    if signal_home and Platform.SIGNAL in config.platforms:
+        config.platforms[Platform.SIGNAL].home_channel = HomeChannel(
+            platform=Platform.SIGNAL,
+            chat_id=signal_home,
+            name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
+        )

    # Mattermost
    mattermost_token = os.getenv("MATTERMOST_TOKEN")
@@ -687,13 +712,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
        config.platforms[Platform.MATTERMOST].enabled = True
        config.platforms[Platform.MATTERMOST].token = mattermost_token
        config.platforms[Platform.MATTERMOST].extra["url"] = mattermost_url
-        mattermost_home = os.getenv("MATTERMOST_HOME_CHANNEL")
-        if mattermost_home:
-            config.platforms[Platform.MATTERMOST].home_channel = HomeChannel(
-                platform=Platform.MATTERMOST,
-                chat_id=mattermost_home,
-                name=os.getenv("MATTERMOST_HOME_CHANNEL_NAME", "Home"),
-            )
+    mattermost_home = os.getenv("MATTERMOST_HOME_CHANNEL")
+    if mattermost_home and Platform.MATTERMOST in config.platforms:
+        config.platforms[Platform.MATTERMOST].home_channel = HomeChannel(
+            platform=Platform.MATTERMOST,
+            chat_id=mattermost_home,
+            name=os.getenv("MATTERMOST_HOME_CHANNEL_NAME", "Home"),
+        )

    # Matrix
    matrix_token = os.getenv("MATRIX_ACCESS_TOKEN")
@@ -715,13 +740,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            config.platforms[Platform.MATRIX].extra["password"] = matrix_password
        matrix_e2ee = os.getenv("MATRIX_ENCRYPTION", "").lower() in ("true", "1", "yes")
        config.platforms[Platform.MATRIX].extra["encryption"] = matrix_e2ee
-        matrix_home = os.getenv("MATRIX_HOME_ROOM")
-        if matrix_home:
-            config.platforms[Platform.MATRIX].home_channel = HomeChannel(
-                platform=Platform.MATRIX,
-                chat_id=matrix_home,
-                name=os.getenv("MATRIX_HOME_ROOM_NAME", "Home"),
-            )
+    matrix_home = os.getenv("MATRIX_HOME_ROOM")
+    if matrix_home and Platform.MATRIX in config.platforms:
+        config.platforms[Platform.MATRIX].home_channel = HomeChannel(
+            platform=Platform.MATRIX,
+            chat_id=matrix_home,
+            name=os.getenv("MATRIX_HOME_ROOM_NAME", "Home"),
+        )

    # Home Assistant
    hass_token = os.getenv("HASS_TOKEN")
@@ -748,13 +773,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            "imap_host": email_imap,
            "smtp_host": email_smtp,
        })
-        email_home = os.getenv("EMAIL_HOME_ADDRESS")
-        if email_home:
-            config.platforms[Platform.EMAIL].home_channel = HomeChannel(
-                platform=Platform.EMAIL,
-                chat_id=email_home,
-                name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
-            )
+    email_home = os.getenv("EMAIL_HOME_ADDRESS")
+    if email_home and Platform.EMAIL in config.platforms:
+        config.platforms[Platform.EMAIL].home_channel = HomeChannel(
+            platform=Platform.EMAIL,
+            chat_id=email_home,
+            name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
+        )

    # SMS (Twilio)
    twilio_sid = os.getenv("TWILIO_ACCOUNT_SID")
@@ -763,13 +788,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
            config.platforms[Platform.SMS] = PlatformConfig()
        config.platforms[Platform.SMS].enabled = True
        config.platforms[Platform.SMS].api_key = os.getenv("TWILIO_AUTH_TOKEN", "")
-        sms_home = os.getenv("SMS_HOME_CHANNEL")
-        if sms_home:
-            config.platforms[Platform.SMS].home_channel = HomeChannel(
-                platform=Platform.SMS,
-                chat_id=sms_home,
-                name=os.getenv("SMS_HOME_CHANNEL_NAME", "Home"),
-            )
+    sms_home = os.getenv("SMS_HOME_CHANNEL")
+    if sms_home and Platform.SMS in config.platforms:
+        config.platforms[Platform.SMS].home_channel = HomeChannel(
+            platform=Platform.SMS,
+            chat_id=sms_home,
+            name=os.getenv("SMS_HOME_CHANNEL_NAME", "Home"),
+        )

    # API Server
    api_server_enabled = os.getenv("API_SERVER_ENABLED", "").lower() in ("true", "1", "yes")
@@ -811,6 +836,55 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
        if webhook_secret:
            config.platforms[Platform.WEBHOOK].extra["secret"] = webhook_secret

+    # Feishu / Lark
+    feishu_app_id = os.getenv("FEISHU_APP_ID")
+    feishu_app_secret = os.getenv("FEISHU_APP_SECRET")
+    if feishu_app_id and feishu_app_secret:
+        if Platform.FEISHU not in config.platforms:
+            config.platforms[Platform.FEISHU] = PlatformConfig()
+        config.platforms[Platform.FEISHU].enabled = True
+        config.platforms[Platform.FEISHU].extra.update({
+            "app_id": feishu_app_id,
+            "app_secret": feishu_app_secret,
+            "domain": os.getenv("FEISHU_DOMAIN", "feishu"),
+            "connection_mode": os.getenv("FEISHU_CONNECTION_MODE", "websocket"),
+        })
+        feishu_encrypt_key = os.getenv("FEISHU_ENCRYPT_KEY", "")
+        if feishu_encrypt_key:
+            config.platforms[Platform.FEISHU].extra["encrypt_key"] = feishu_encrypt_key
+        feishu_verification_token = os.getenv("FEISHU_VERIFICATION_TOKEN", "")
+        if feishu_verification_token:
+            config.platforms[Platform.FEISHU].extra["verification_token"] = feishu_verification_token
+        feishu_home = os.getenv("FEISHU_HOME_CHANNEL")
+        if feishu_home:
+            config.platforms[Platform.FEISHU].home_channel = HomeChannel(
+                platform=Platform.FEISHU,
+                chat_id=feishu_home,
+                name=os.getenv("FEISHU_HOME_CHANNEL_NAME", "Home"),
+            )
+
+    # WeCom (Enterprise WeChat)
+    wecom_bot_id = os.getenv("WECOM_BOT_ID")
+    wecom_secret = os.getenv("WECOM_SECRET")
+    if wecom_bot_id and wecom_secret:
+        if Platform.WECOM not in config.platforms:
+            config.platforms[Platform.WECOM] = PlatformConfig()
+        config.platforms[Platform.WECOM].enabled = True
+        config.platforms[Platform.WECOM].extra.update({
+            "bot_id": wecom_bot_id,
+            "secret": wecom_secret,
+        })
+        wecom_ws_url = os.getenv("WECOM_WEBSOCKET_URL", "")
+        if wecom_ws_url:
+            config.platforms[Platform.WECOM].extra["websocket_url"] = wecom_ws_url
+        wecom_home = os.getenv("WECOM_HOME_CHANNEL")
+        if wecom_home:
+            config.platforms[Platform.WECOM].home_channel = HomeChannel(
+                platform=Platform.WECOM,
+                chat_id=wecom_home,
+                name=os.getenv("WECOM_HOME_CHANNEL_NAME", "Home"),
+            )
+
    # Session settings
    idle_minutes = os.getenv("SESSION_IDLE_MINUTES")
    if idle_minutes:
@@ -51,14 +51,33 @@ class HookRegistry:
        """Return metadata about all loaded hooks."""
        return list(self._loaded_hooks)

+    def _register_builtin_hooks(self) -> None:
+        """Register built-in hooks that are always active."""
+        try:
+            from gateway.builtin_hooks.boot_md import handle as boot_md_handle
+
+            self._handlers.setdefault("gateway:startup", []).append(boot_md_handle)
+            self._loaded_hooks.append({
+                "name": "boot-md",
+                "description": "Run ~/.hermes/BOOT.md on gateway startup",
+                "events": ["gateway:startup"],
+                "path": "(builtin)",
+            })
+        except Exception as e:
+            print(f"[hooks] Could not load built-in boot-md hook: {e}", flush=True)
+
    def discover_and_load(self) -> None:
        """
        Scan the hooks directory for hook directories and load their handlers.

+        Also registers built-in hooks that are always active.
+
        Each hook directory must contain:
          - HOOK.yaml with at least 'name' and 'events' keys
          - handler.py with a top-level 'handle' function (sync or async)
        """
+        self._register_builtin_hooks()
+
        if not HOOKS_DIR.exists():
            return

@@ -1261,6 +1261,17 @@ class APIServerAdapter(BasePlatformAdapter):
            self._app.router.add_post("/api/jobs/{job_id}/resume", self._handle_resume_job)
            self._app.router.add_post("/api/jobs/{job_id}/run", self._handle_run_job)

+            # Port conflict detection — fail fast if port is already in use
+            import socket as _socket
+            try:
+                with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
+                    _s.settimeout(1)
+                    _s.connect(('127.0.0.1', self._port))
+                logger.error('[%s] Port %d already in use. Set a different port in config.yaml: platforms.api_server.port', self.name, self._port)
+                return False
+            except (ConnectionRefusedError, OSError):
+                pass  # port is free
+
            self._runner = web.AppRunner(self._app)
            await self._runner.setup()
            self._site = web.TCPSite(self._runner, self._host, self._port)
@@ -898,6 +898,26 @@ class BasePlatformAdapter(ABC):
                except Exception:
                    pass
    
+    # ── Processing lifecycle hooks ──────────────────────────────────────────
+    # Subclasses override these to react to message processing events
+    # (e.g. Discord adds 👀/✅/❌ reactions).
+
+    async def on_processing_start(self, event: MessageEvent) -> None:
+        """Hook called when background processing begins."""
+
+    async def on_processing_complete(self, event: MessageEvent, success: bool) -> None:
+        """Hook called when background processing completes."""
+
+    async def _run_processing_hook(self, hook_name: str, *args: Any, **kwargs: Any) -> None:
+        """Run a lifecycle hook without letting failures break message flow."""
+        hook = getattr(self, hook_name, None)
+        if not callable(hook):
+            return
+        try:
+            await hook(*args, **kwargs)
+        except Exception as e:
+            logger.warning("[%s] %s hook failed: %s", self.name, hook_name, e)
+
    @staticmethod
    def _is_retryable_error(error: Optional[str]) -> bool:
        """Return True if the error string looks like a transient network failure."""
@@ -1005,7 +1025,7 @@ class BasePlatformAdapter(ABC):
            # simultaneous messages. Queue them without interrupting the active run,
            # then process them immediately after the current task finishes.
            if event.message_type == MessageType.PHOTO:
-                print(f"[{self.name}] 🖼️ Queuing photo follow-up for session {session_key} without interrupt")
+                logger.debug("[%s] Queuing photo follow-up for session %s without interrupt", self.name, session_key)
                existing = self._pending_messages.get(session_key)
                if existing and existing.message_type == MessageType.PHOTO:
                    existing.media_urls.extend(event.media_urls)
@@ -1020,7 +1040,7 @@ class BasePlatformAdapter(ABC):
                return  # Don't interrupt now - will run after current task completes

            # Default behavior for non-photo follow-ups: interrupt the running agent
-            print(f"[{self.name}] ⚡ New message while session {session_key} is active - triggering interrupt")
+            logger.debug("[%s] New message while session %s is active — triggering interrupt", self.name, session_key)
            self._pending_messages[session_key] = event
            # Signal the interrupt (the processing task checks this)
            self._active_sessions[session_key].set()
@@ -1060,6 +1080,18 @@ class BasePlatformAdapter(ABC):

    async def _process_message_background(self, event: MessageEvent, session_key: str) -> None:
        """Background task that actually processes the message."""
+        # Track delivery outcomes for the processing-complete hook
+        delivery_attempted = False
+        delivery_succeeded = False
+
+        def _record_delivery(result):
+            nonlocal delivery_attempted, delivery_succeeded
+            if result is None:
+                return
+            delivery_attempted = True
+            if getattr(result, "success", False):
+                delivery_succeeded = True
+
        # Create interrupt event for this session
        interrupt_event = asyncio.Event()
        self._active_sessions[session_key] = interrupt_event
@@ -1069,6 +1101,8 @@ class BasePlatformAdapter(ABC):
        typing_task = asyncio.create_task(self._keep_typing(event.source.chat_id, metadata=_thread_metadata))
        
        try:
+            await self._run_processing_hook("on_processing_start", event)
+
            # Call the handler (this can take a while with tool calls)
            response = await self._message_handler(event)
            
@@ -1138,6 +1172,7 @@ class BasePlatformAdapter(ABC):
                        reply_to=event.message_id,
                        metadata=_thread_metadata,
                    )
+                    _record_delivery(result)

                # Human-like pacing delay between text and media
                human_delay = self._get_human_delay()
@@ -1206,9 +1241,9 @@ class BasePlatformAdapter(ABC):
                            )

                        if not media_result.success:
-                            print(f"[{self.name}] Failed to send media ({ext}): {media_result.error}")
+                            logger.warning("[%s] Failed to send media (%s): %s", self.name, ext, media_result.error)
                    except Exception as media_err:
-                        print(f"[{self.name}] Error sending media: {media_err}")
+                        logger.warning("[%s] Error sending media: %s", self.name, media_err)

                # Send auto-detected local files as native attachments
                for file_path in local_files:
@@ -1237,10 +1272,14 @@ class BasePlatformAdapter(ABC):
                    except Exception as file_err:
                        logger.error("[%s] Error sending local file %s: %s", self.name, file_path, file_err)

+            # Determine overall success for the processing hook
+            processing_ok = delivery_succeeded if delivery_attempted else not bool(response)
+            await self._run_processing_hook("on_processing_complete", event, processing_ok)
+
            # Check if there's a pending message that was queued during our processing
            if session_key in self._pending_messages:
                pending_event = self._pending_messages.pop(session_key)
-                print(f"[{self.name}] 📨 Processing queued message from interrupt")
+                logger.debug("[%s] Processing queued message from interrupt", self.name)
                # Clean up current session before processing pending
                if session_key in self._active_sessions:
                    del self._active_sessions[session_key]
@@ -1253,10 +1292,12 @@ class BasePlatformAdapter(ABC):
                await self._process_message_background(pending_event, session_key)
                return  # Already cleaned up
                
+        except asyncio.CancelledError:
+            await self._run_processing_hook("on_processing_complete", event, False)
+            raise
        except Exception as e:
-            print(f"[{self.name}] Error handling message: {e}")
-            import traceback
-            traceback.print_exc()
+            await self._run_processing_hook("on_processing_complete", event, False)
+            logger.error("[%s] Error handling message: %s", self.name, e, exc_info=True)
            # Send the error to the user so they aren't left with radio silence
            try:
                error_type = type(e).__name__
@@ -486,6 +486,17 @@ class DiscordAdapter(BasePlatformAdapter):
            return False
        
        try:
+            # Acquire scoped lock to prevent duplicate bot token usage
+            from gateway.status import acquire_scoped_lock
+            self._token_lock_identity = self.config.token
+            acquired, existing = acquire_scoped_lock('discord-bot-token', self._token_lock_identity, metadata={'platform': 'discord'})
+            if not acquired:
+                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
+                message = f'Discord bot token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
+                logger.error('[%s] %s', self.name, message)
+                self._set_fatal_error('discord_token_lock', message, retryable=False)
+                return False
+
            # Set up intents -- members intent needed for username-to-ID resolution
            intents = Intents.default()
            intents.message_content = True
@@ -638,7 +649,52 @@ class DiscordAdapter(BasePlatformAdapter):
        self._running = False
        self._client = None
        self._ready_event.clear()
+
+        # Release the token lock
+        try:
+            from gateway.status import release_scoped_lock
+            if getattr(self, '_token_lock_identity', None):
+                release_scoped_lock('discord-bot-token', self._token_lock_identity)
+                self._token_lock_identity = None
+        except Exception:
+            pass
+
        logger.info("[%s] Disconnected", self.name)
+
+    async def _add_reaction(self, message: Any, emoji: str) -> bool:
+        """Add an emoji reaction to a Discord message."""
+        if not message or not hasattr(message, "add_reaction"):
+            return False
+        try:
+            await message.add_reaction(emoji)
+            return True
+        except Exception as e:
+            logger.debug("[%s] add_reaction failed (%s): %s", self.name, emoji, e)
+            return False
+
+    async def _remove_reaction(self, message: Any, emoji: str) -> bool:
+        """Remove the bot's own emoji reaction from a Discord message."""
+        if not message or not hasattr(message, "remove_reaction") or not self._client or not self._client.user:
+            return False
+        try:
+            await message.remove_reaction(emoji, self._client.user)
+            return True
+        except Exception as e:
+            logger.debug("[%s] remove_reaction failed (%s): %s", self.name, emoji, e)
+            return False
+
+    async def on_processing_start(self, event: MessageEvent) -> None:
+        """Add an in-progress reaction for normal Discord message events."""
+        message = event.raw_message
+        if hasattr(message, "add_reaction"):
+            await self._add_reaction(message, "👀")
+
+    async def on_processing_complete(self, event: MessageEvent, success: bool) -> None:
+        """Swap the in-progress reaction for a final success/failure reaction."""
+        message = event.raw_message
+        if hasattr(message, "add_reaction"):
+            await self._remove_reaction(message, "👀")
+            await self._add_reaction(message, "✅" if success else "❌")
    
    async def send(
        self,
@@ -1429,15 +1485,23 @@ class DiscordAdapter(BasePlatformAdapter):
        command_text: str,
        followup_msg: str | None = None,
    ) -> None:
-        """Common handler for simple slash commands that dispatch a command string."""
+        """Common handler for simple slash commands that dispatch a command string.
+
+        Defers the interaction (shows "thinking..."), dispatches the command,
+        then cleans up the deferred response.  If *followup_msg* is provided
+        the "thinking..." indicator is replaced with that text; otherwise it
+        is deleted so the channel isn't cluttered.
+        """
        await interaction.response.defer(ephemeral=True)
        event = self._build_slash_event(interaction, command_text)
        await self.handle_message(event)
-        if followup_msg:
-            try:
-                await interaction.followup.send(followup_msg, ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
+        try:
+            if followup_msg:
+                await interaction.edit_original_response(content=followup_msg)
+            else:
+                await interaction.delete_original_response()
+        except Exception as e:
+            logger.debug("Discord interaction cleanup failed: %s", e)

    def _register_slash_commands(self) -> None:
        """Register Discord slash commands on the command tree."""
@@ -1462,9 +1526,7 @@ class DiscordAdapter(BasePlatformAdapter):
        @tree.command(name="reasoning", description="Show or change reasoning effort")
        @discord.app_commands.describe(effort="Reasoning effort: xhigh, high, medium, low, minimal, or none.")
        async def slash_reasoning(interaction: discord.Interaction, effort: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/reasoning {effort}".strip())
-            await self.handle_message(event)
+            await self._run_simple_slash(interaction, f"/reasoning {effort}".strip())

        @tree.command(name="personality", description="Set a personality")
        @discord.app_commands.describe(name="Personality name. Leave empty to list available.")
@@ -1537,9 +1599,7 @@ class DiscordAdapter(BasePlatformAdapter):
            discord.app_commands.Choice(name="status — show current mode", value="status"),
        ])
        async def slash_voice(interaction: discord.Interaction, mode: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/voice {mode}".strip())
-            await self.handle_message(event)
+            await self._run_simple_slash(interaction, f"/voice {mode}".strip())

        @tree.command(name="update", description="Update Hermes Agent to the latest version")
        async def slash_update(interaction: discord.Interaction):
@@ -337,60 +337,63 @@ class EmailAdapter(BasePlatformAdapter):
        results = []
        try:
            imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port, timeout=30)
-            imap.login(self._address, self._password)
-            imap.select("INBOX")
+            try:
+                imap.login(self._address, self._password)
+                imap.select("INBOX")

-            status, data = imap.uid("search", None, "UNSEEN")
-            if status != "OK" or not data or not data[0]:
-                imap.logout()
-                return results
+                status, data = imap.uid("search", None, "UNSEEN")
+                if status != "OK" or not data or not data[0]:
+                    return results

-            for uid in data[0].split():
-                if uid in self._seen_uids:
-                    continue
-                self._seen_uids.add(uid)
-                # Trim periodically to prevent unbounded memory growth
-                if len(self._seen_uids) > self._seen_uids_max:
-                    self._trim_seen_uids()
+                for uid in data[0].split():
+                    if uid in self._seen_uids:
+                        continue
+                    self._seen_uids.add(uid)
+                    # Trim periodically to prevent unbounded memory growth
+                    if len(self._seen_uids) > self._seen_uids_max:
+                        self._trim_seen_uids()

-                status, msg_data = imap.uid("fetch", uid, "(RFC822)")
-                if status != "OK":
-                    continue
+                    status, msg_data = imap.uid("fetch", uid, "(RFC822)")
+                    if status != "OK":
+                        continue

-                raw_email = msg_data[0][1]
-                msg = email_lib.message_from_bytes(raw_email)
+                    raw_email = msg_data[0][1]
+                    msg = email_lib.message_from_bytes(raw_email)

-                sender_raw = msg.get("From", "")
-                sender_addr = _extract_email_address(sender_raw)
-                sender_name = _decode_header_value(sender_raw)
-                # Remove email from name if present
-                if "<" in sender_name:
-                    sender_name = sender_name.split("<")[0].strip().strip('"')
+                    sender_raw = msg.get("From", "")
+                    sender_addr = _extract_email_address(sender_raw)
+                    sender_name = _decode_header_value(sender_raw)
+                    # Remove email from name if present
+                    if "<" in sender_name:
+                        sender_name = sender_name.split("<")[0].strip().strip('"')

-                subject = _decode_header_value(msg.get("Subject", "(no subject)"))
-                message_id = msg.get("Message-ID", "")
-                in_reply_to = msg.get("In-Reply-To", "")
-                # Skip automated/noreply senders before any processing
-                msg_headers = dict(msg.items())
-                if _is_automated_sender(sender_addr, msg_headers):
-                    logger.debug("[Email] Skipping automated sender: %s", sender_addr)
-                    continue
-                body = _extract_text_body(msg)
-                attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)
+                    subject = _decode_header_value(msg.get("Subject", "(no subject)"))
+                    message_id = msg.get("Message-ID", "")
+                    in_reply_to = msg.get("In-Reply-To", "")
+                    # Skip automated/noreply senders before any processing
+                    msg_headers = dict(msg.items())
+                    if _is_automated_sender(sender_addr, msg_headers):
+                        logger.debug("[Email] Skipping automated sender: %s", sender_addr)
+                        continue
+                    body = _extract_text_body(msg)
+                    attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)

-                results.append({
-                    "uid": uid,
-                    "sender_addr": sender_addr,
-                    "sender_name": sender_name,
-                    "subject": subject,
-                    "message_id": message_id,
-                    "in_reply_to": in_reply_to,
-                    "body": body,
-                    "attachments": attachments,
-                    "date": msg.get("Date", ""),
-                })
-
-            imap.logout()
+                    results.append({
+                        "uid": uid,
+                        "sender_addr": sender_addr,
+                        "sender_name": sender_name,
+                        "subject": subject,
+                        "message_id": message_id,
+                        "in_reply_to": in_reply_to,
+                        "body": body,
+                        "attachments": attachments,
+                        "date": msg.get("Date", ""),
+                    })
+            finally:
+                try:
+                    imap.logout()
+                except Exception:
+                    pass
        except Exception as e:
            logger.error("[Email] IMAP fetch error: %s", e)
        return results
@@ -503,10 +506,15 @@ class EmailAdapter(BasePlatformAdapter):
        msg.attach(MIMEText(body, "plain", "utf-8"))

        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
-        smtp.starttls(context=ssl.create_default_context())
-        smtp.login(self._address, self._password)
-        smtp.send_message(msg)
-        smtp.quit()
+        try:
+            smtp.starttls(context=ssl.create_default_context())
+            smtp.login(self._address, self._password)
+            smtp.send_message(msg)
+        finally:
+            try:
+                smtp.quit()
+            except Exception:
+                smtp.close()

        logger.info("[Email] Sent reply to %s (subject: %s)", to_addr, subject)
        return msg_id
@@ -590,10 +598,15 @@ class EmailAdapter(BasePlatformAdapter):
            msg.attach(part)

        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
-        smtp.starttls(context=ssl.create_default_context())
-        smtp.login(self._address, self._password)
-        smtp.send_message(msg)
-        smtp.quit()
+        try:
+            smtp.starttls(context=ssl.create_default_context())
+            smtp.login(self._address, self._password)
+            smtp.send_message(msg)
+        finally:
+            try:
+                smtp.quit()
+            except Exception:
+                smtp.close()

        return msg_id

@@ -17,6 +17,8 @@ Environment variables:
 from __future__ import annotations

 import asyncio
+import io
+import json
 import logging
 import mimetypes
 import os
@@ -512,8 +514,11 @@ class MatrixAdapter(BasePlatformAdapter):
        reply_to: Optional[str] = None,
        metadata: Optional[Dict[str, Any]] = None,
    ) -> SendResult:
-        """Upload an audio file as a voice message."""
-        return await self._send_local_file(chat_id, audio_path, "m.audio", caption, reply_to, metadata=metadata)
+        """Upload an audio file as a voice message (MSC3245 native voice)."""
+        return await self._send_local_file(
+            chat_id, audio_path, "m.audio", caption, reply_to, 
+            metadata=metadata, is_voice=True
+        )

    async def send_video(
        self,
@@ -546,13 +551,16 @@ class MatrixAdapter(BasePlatformAdapter):
        caption: Optional[str] = None,
        reply_to: Optional[str] = None,
        metadata: Optional[Dict[str, Any]] = None,
+        is_voice: bool = False,
    ) -> SendResult:
        """Upload bytes to Matrix and send as a media message."""
        import nio

        # Upload to homeserver.
-        resp = await self._client.upload(
-            data,
+        # nio expects a DataProvider (callable) or file-like object, not raw bytes.
+        # nio.upload() returns a tuple (UploadResponse|UploadError, Optional[Dict])
+        resp, maybe_encryption_info = await self._client.upload(
+            io.BytesIO(data),
            content_type=content_type,
            filename=filename,
        )
@@ -574,6 +582,10 @@ class MatrixAdapter(BasePlatformAdapter):
            },
        }

+        # Add MSC3245 voice flag for native voice messages.
+        if is_voice:
+            msg_content["org.matrix.msc3245.voice"] = {}
+
        if reply_to:
            msg_content["m.relates_to"] = {
                "m.in_reply_to": {"event_id": reply_to}
@@ -601,6 +613,7 @@ class MatrixAdapter(BasePlatformAdapter):
        reply_to: Optional[str] = None,
        file_name: Optional[str] = None,
        metadata: Optional[Dict[str, Any]] = None,
+        is_voice: bool = False,
    ) -> SendResult:
        """Read a local file and upload it."""
        p = Path(file_path)
@@ -613,7 +626,7 @@ class MatrixAdapter(BasePlatformAdapter):
        ct = mimetypes.guess_type(fname)[0] or "application/octet-stream"
        data = p.read_bytes()

-        return await self._upload_and_send(room_id, data, fname, ct, msgtype, caption, reply_to, metadata)
+        return await self._upload_and_send(room_id, data, fname, ct, msgtype, caption, reply_to, metadata, is_voice)

    # ------------------------------------------------------------------
    # Sync loop
@@ -808,11 +821,19 @@ class MatrixAdapter(BasePlatformAdapter):
        event_mimetype = (content_info.get("info") or {}).get("mimetype", "")
        media_type = "application/octet-stream"
        msg_type = MessageType.DOCUMENT
+        is_voice_message = False
+        
        if isinstance(event, nio.RoomMessageImage):
            msg_type = MessageType.PHOTO
            media_type = event_mimetype or "image/png"
        elif isinstance(event, nio.RoomMessageAudio):
-            msg_type = MessageType.AUDIO
+            # Check for MSC3245 voice flag: org.matrix.msc3245.voice: {}
+            source_content = getattr(event, "source", {}).get("content", {})
+            if source_content.get("org.matrix.msc3245.voice") is not None:
+                is_voice_message = True
+                msg_type = MessageType.VOICE
+            else:
+                msg_type = MessageType.AUDIO
            media_type = event_mimetype or "audio/ogg"
        elif isinstance(event, nio.RoomMessageVideo):
            msg_type = MessageType.VIDEO
@@ -850,6 +871,31 @@ class MatrixAdapter(BasePlatformAdapter):
        if relates_to.get("rel_type") == "m.thread":
            thread_id = relates_to.get("event_id")

+        # For voice messages, cache audio locally for transcription tools.
+        # Use the authenticated nio client to download (Matrix requires auth for media).
+        media_urls = [http_url] if http_url else None
+        media_types = [media_type] if http_url else None
+        
+        if is_voice_message and url and url.startswith("mxc://"):
+            try:
+                import nio
+                from gateway.platforms.base import cache_audio_from_bytes
+                
+                resp = await self._client.download(mxc=url)
+                if isinstance(resp, nio.MemoryDownloadResponse):
+                    # Extract extension from mimetype or default to .ogg
+                    ext = ".ogg"
+                    if media_type and "/" in media_type:
+                        subtype = media_type.split("/")[1]
+                        ext = f".{subtype}" if subtype else ".ogg"
+                    local_path = cache_audio_from_bytes(resp.body, ext)
+                    media_urls = [local_path]
+                    logger.debug("Matrix: cached voice message to %s", local_path)
+                else:
+                    logger.warning("Matrix: failed to download voice: %s", getattr(resp, "message", resp))
+            except Exception as e:
+                logger.warning("Matrix: failed to cache voice message, using HTTP URL: %s", e)
+
        source = self.build_source(
            chat_id=room.room_id,
            chat_type=chat_type,
@@ -858,8 +904,9 @@ class MatrixAdapter(BasePlatformAdapter):
            thread_id=thread_id,
        )

-        # Use cached local path for images, HTTP URL for other media types
-        media_urls = [cached_path] if cached_path else ([http_url] if http_url else None)
+        # Use cached local path for images (voice messages already handled above).
+        if cached_path:
+            media_urls = [cached_path]
        media_types = [media_type] if media_urls else None

        msg_event = MessageEvent(
@@ -603,9 +603,19 @@ class MattermostAdapter(BasePlatformAdapter):
        # For DMs, user_id is sufficient.  For channels, check for @mention.
        message_text = post.get("message", "")

-        # Mention-only mode: skip channel messages that don't @mention the bot.
-        # DMs (type "D") are always processed.
+        # Mention-gating for non-DM channels.
+        # Config (env vars):
+        #   MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
+        #   MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
        if channel_type_raw != "D":
+            require_mention = os.getenv(
+                "MATTERMOST_REQUIRE_MENTION", "true"
+            ).lower() not in ("false", "0", "no")
+
+            free_channels_raw = os.getenv("MATTERMOST_FREE_RESPONSE_CHANNELS", "")
+            free_channels = {ch.strip() for ch in free_channels_raw.split(",") if ch.strip()}
+            is_free_channel = channel_id in free_channels
+
            mention_patterns = [
                f"@{self._bot_username}",
                f"@{self._bot_user_id}",
@@ -614,13 +624,21 @@ class MattermostAdapter(BasePlatformAdapter):
                pattern.lower() in message_text.lower()
                for pattern in mention_patterns
            )
-            if not has_mention:
+
+            if require_mention and not is_free_channel and not has_mention:
                logger.debug(
                    "Mattermost: skipping non-DM message without @mention (channel=%s)",
                    channel_id,
                )
                return

+            # Strip @mention from the message text so the agent sees clean input.
+            if has_mention:
+                for pattern in mention_patterns:
+                    message_text = re.sub(
+                        re.escape(pattern), "", message_text, flags=re.IGNORECASE
+                    ).strip()
+
        # Resolve sender info.
        sender_id = post.get("user_id", "")
        sender_name = data.get("sender_name", "").lstrip("@") or sender_id
@@ -22,7 +22,7 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, List, Optional, Any
-from urllib.parse import unquote
+from urllib.parse import quote, unquote

 import httpx

@@ -184,6 +184,8 @@ class SignalAdapter(BasePlatformAdapter):
        self._recent_sent_timestamps: set = set()
        self._max_recent_timestamps = 50

+        self._phone_lock_identity: Optional[str] = None
+
        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")
@@ -198,6 +200,29 @@ class SignalAdapter(BasePlatformAdapter):
            logger.error("Signal: SIGNAL_HTTP_URL and SIGNAL_ACCOUNT are required")
            return False

+        # Acquire scoped lock to prevent duplicate Signal listeners for the same phone
+        try:
+            from gateway.status import acquire_scoped_lock
+
+            self._phone_lock_identity = self.account
+            acquired, existing = acquire_scoped_lock(
+                "signal-phone",
+                self._phone_lock_identity,
+                metadata={"platform": self.platform.value},
+            )
+            if not acquired:
+                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
+                message = (
+                    "Another local Hermes gateway is already using this Signal account"
+                    + (f" (PID {owner_pid})." if owner_pid else ".")
+                    + " Stop the other gateway before starting a second Signal listener."
+                )
+                logger.error("Signal: %s", message)
+                self._set_fatal_error("signal_phone_lock", message, retryable=False)
+                return False
+        except Exception as e:
+            logger.warning("Signal: Could not acquire phone lock (non-fatal): %s", e)
+
        self.client = httpx.AsyncClient(timeout=30.0)

        # Health check — verify signal-cli daemon is reachable
@@ -245,6 +270,14 @@ class SignalAdapter(BasePlatformAdapter):
            await self.client.aclose()
            self.client = None

+        if self._phone_lock_identity:
+            try:
+                from gateway.status import release_scoped_lock
+                release_scoped_lock("signal-phone", self._phone_lock_identity)
+            except Exception as e:
+                logger.warning("Signal: Error releasing phone lock: %s", e, exc_info=True)
+            self._phone_lock_identity = None
+
        logger.info("Signal: disconnected")

    # ------------------------------------------------------------------
@@ -253,7 +286,7 @@ class SignalAdapter(BasePlatformAdapter):

    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}"
+        url = f"{self.http_url}/api/v1/events?account={quote(self.account, safe='')}"
        backoff = SSE_RETRY_DELAY_INITIAL

        while self._running:
@@ -521,7 +554,7 @@ class SignalAdapter(BasePlatformAdapter):
        """Fetch an attachment via JSON-RPC and cache it. Returns (path, ext)."""
        result = await self._rpc("getAttachment", {
            "account": self.account,
-            "attachmentId": attachment_id,
+            "id": attachment_id,
        })

        if not result:
@@ -9,6 +9,7 @@ Uses slack-bolt (Python) with Socket Mode for:
 """

 import asyncio
+import json
 import logging
 import os
 import re
@@ -73,6 +74,10 @@ class SlackAdapter(BasePlatformAdapter):
        self._bot_user_id: Optional[str] = None
        self._user_name_cache: Dict[str, str] = {}  # user_id → display name
        self._socket_mode_task: Optional[asyncio.Task] = None
+        # Multi-workspace support
+        self._team_clients: Dict[str, AsyncWebClient] = {}   # team_id → WebClient
+        self._team_bot_user_ids: Dict[str, str] = {}          # team_id → bot_user_id
+        self._channel_team: Dict[str, str] = {}                # channel_id → team_id

    async def connect(self) -> bool:
        """Connect to Slack via Socket Mode."""
@@ -82,23 +87,70 @@ class SlackAdapter(BasePlatformAdapter):
            )
            return False

-        bot_token = self.config.token
+        raw_token = self.config.token
        app_token = os.getenv("SLACK_APP_TOKEN")

-        if not bot_token:
+        if not raw_token:
            logger.error("[Slack] SLACK_BOT_TOKEN not set")
            return False
        if not app_token:
            logger.error("[Slack] SLACK_APP_TOKEN not set")
            return False

-        try:
-            self._app = AsyncApp(token=bot_token)
+        # Support comma-separated bot tokens for multi-workspace
+        bot_tokens = [t.strip() for t in raw_token.split(",") if t.strip()]

-            # Get our own bot user ID for mention detection
-            auth_response = await self._app.client.auth_test()
-            self._bot_user_id = auth_response.get("user_id")
-            bot_name = auth_response.get("user", "unknown")
+        # Also load tokens from OAuth token file
+        from hermes_constants import get_hermes_home
+        tokens_file = get_hermes_home() / "slack_tokens.json"
+        if tokens_file.exists():
+            try:
+                saved = json.loads(tokens_file.read_text(encoding="utf-8"))
+                for team_id, entry in saved.items():
+                    tok = entry.get("token", "") if isinstance(entry, dict) else ""
+                    if tok and tok not in bot_tokens:
+                        bot_tokens.append(tok)
+                        team_label = entry.get("team_name", team_id) if isinstance(entry, dict) else team_id
+                        logger.info("[Slack] Loaded saved token for workspace %s", team_label)
+            except Exception as e:
+                logger.warning("[Slack] Failed to read %s: %s", tokens_file, e)
+
+        try:
+            # Acquire scoped lock to prevent duplicate app token usage
+            from gateway.status import acquire_scoped_lock
+            self._token_lock_identity = app_token
+            acquired, existing = acquire_scoped_lock('slack-app-token', app_token, metadata={'platform': 'slack'})
+            if not acquired:
+                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
+                message = f'Slack app token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
+                logger.error('[%s] %s', self.name, message)
+                self._set_fatal_error('slack_token_lock', message, retryable=False)
+                return False
+
+            # First token is the primary — used for AsyncApp / Socket Mode
+            primary_token = bot_tokens[0]
+            self._app = AsyncApp(token=primary_token)
+
+            # Register each bot token and map team_id → client
+            for token in bot_tokens:
+                client = AsyncWebClient(token=token)
+                auth_response = await client.auth_test()
+                team_id = auth_response.get("team_id", "")
+                bot_user_id = auth_response.get("user_id", "")
+                bot_name = auth_response.get("user", "unknown")
+                team_name = auth_response.get("team", "unknown")
+
+                self._team_clients[team_id] = client
+                self._team_bot_user_ids[team_id] = bot_user_id
+
+                # First token sets the primary bot_user_id (backward compat)
+                if self._bot_user_id is None:
+                    self._bot_user_id = bot_user_id
+
+                logger.info(
+                    "[Slack] Authenticated as @%s in workspace %s (team: %s)",
+                    bot_name, team_name, team_id,
+                )

            # Register message event handler
            @self._app.event("message")
@@ -123,7 +175,10 @@ class SlackAdapter(BasePlatformAdapter):
            self._socket_mode_task = asyncio.create_task(self._handler.start_async())

            self._running = True
-            logger.info("[Slack] Connected as @%s (Socket Mode)", bot_name)
+            logger.info(
+                "[Slack] Socket Mode connected (%d workspace(s))",
+                len(self._team_clients),
+            )
            return True

        except Exception as e:  # pragma: no cover - defensive logging
@@ -138,8 +193,25 @@ class SlackAdapter(BasePlatformAdapter):
            except Exception as e:  # pragma: no cover - defensive logging
                logger.warning("[Slack] Error while closing Socket Mode handler: %s", e, exc_info=True)
        self._running = False
+
+        # Release the token lock (use stored identity, not re-read env)
+        try:
+            from gateway.status import release_scoped_lock
+            if getattr(self, '_token_lock_identity', None):
+                release_scoped_lock('slack-app-token', self._token_lock_identity)
+                self._token_lock_identity = None
+        except Exception:
+            pass
+
        logger.info("[Slack] Disconnected")

+    def _get_client(self, chat_id: str) -> AsyncWebClient:
+        """Return the workspace-specific WebClient for a channel."""
+        team_id = self._channel_team.get(chat_id)
+        if team_id and team_id in self._team_clients:
+            return self._team_clients[team_id]
+        return self._app.client  # fallback to primary
+
    async def send(
        self,
        chat_id: str,
@@ -176,7 +248,7 @@ class SlackAdapter(BasePlatformAdapter):
                    if broadcast and i == 0:
                        kwargs["reply_broadcast"] = True

-                last_result = await self._app.client.chat_postMessage(**kwargs)
+                last_result = await self._get_client(chat_id).chat_postMessage(**kwargs)

            return SendResult(
                success=True,
@@ -198,7 +270,7 @@ class SlackAdapter(BasePlatformAdapter):
        if not self._app:
            return SendResult(success=False, error="Not connected")
        try:
-            await self._app.client.chat_update(
+            await self._get_client(chat_id).chat_update(
                channel=chat_id,
                ts=message_id,
                text=content,
@@ -232,7 +304,7 @@ class SlackAdapter(BasePlatformAdapter):
            return  # Can only set status in a thread context

        try:
-            await self._app.client.assistant_threads_setStatus(
+            await self._get_client(chat_id).assistant_threads_setStatus(
                channel_id=chat_id,
                thread_ts=thread_ts,
                status="is thinking...",
@@ -274,7 +346,7 @@ class SlackAdapter(BasePlatformAdapter):
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

-        result = await self._app.client.files_upload_v2(
+        result = await self._get_client(chat_id).files_upload_v2(
            channel=chat_id,
            file=file_path,
            filename=os.path.basename(file_path),
@@ -376,7 +448,7 @@ class SlackAdapter(BasePlatformAdapter):
        if not self._app:
            return False
        try:
-            await self._app.client.reactions_add(
+            await self._get_client(channel).reactions_add(
                channel=channel, timestamp=timestamp, name=emoji
            )
            return True
@@ -392,7 +464,7 @@ class SlackAdapter(BasePlatformAdapter):
        if not self._app:
            return False
        try:
-            await self._app.client.reactions_remove(
+            await self._get_client(channel).reactions_remove(
                channel=channel, timestamp=timestamp, name=emoji
            )
            return True
@@ -402,7 +474,7 @@ class SlackAdapter(BasePlatformAdapter):

    # ----- User identity resolution -----

-    async def _resolve_user_name(self, user_id: str) -> str:
+    async def _resolve_user_name(self, user_id: str, chat_id: str = "") -> str:
        """Resolve a Slack user ID to a display name, with caching."""
        if not user_id:
            return ""
@@ -413,7 +485,8 @@ class SlackAdapter(BasePlatformAdapter):
            return user_id

        try:
-            result = await self._app.client.users_info(user=user_id)
+            client = self._get_client(chat_id) if chat_id else self._app.client
+            result = await client.users_info(user=user_id)
            user = result.get("user", {})
            # Prefer display_name → real_name → user_id
            profile = user.get("profile", {})
@@ -477,7 +550,7 @@ class SlackAdapter(BasePlatformAdapter):
                response = await client.get(image_url)
                response.raise_for_status()

-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                channel=chat_id,
                content=response.content,
                filename="image.png",
@@ -537,7 +610,7 @@ class SlackAdapter(BasePlatformAdapter):
            return SendResult(success=False, error=f"Video file not found: {video_path}")

        try:
-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                channel=chat_id,
                file=video_path,
                filename=os.path.basename(video_path),
@@ -578,7 +651,7 @@ class SlackAdapter(BasePlatformAdapter):
        display_name = file_name or os.path.basename(file_path)

        try:
-            result = await self._app.client.files_upload_v2(
+            result = await self._get_client(chat_id).files_upload_v2(
                channel=chat_id,
                file=file_path,
                filename=display_name,
@@ -606,7 +679,7 @@ class SlackAdapter(BasePlatformAdapter):
            return {"name": chat_id, "type": "unknown"}

        try:
-            result = await self._app.client.conversations_info(channel=chat_id)
+            result = await self._get_client(chat_id).conversations_info(channel=chat_id)
            channel = result.get("channel", {})
            is_dm = channel.get("is_im", False)
            return {
@@ -639,6 +712,11 @@ class SlackAdapter(BasePlatformAdapter):
        user_id = event.get("user", "")
        channel_id = event.get("channel", "")
        ts = event.get("ts", "")
+        team_id = event.get("team", "")
+
+        # Track which workspace owns this channel
+        if team_id and channel_id:
+            self._channel_team[channel_id] = team_id

        # Determine if this is a DM or channel message
        channel_type = event.get("channel_type", "")
@@ -655,11 +733,12 @@ class SlackAdapter(BasePlatformAdapter):
            thread_ts = event.get("thread_ts") or ts  # ts fallback for channels

        # In channels, only respond if bot is mentioned
-        if not is_dm and self._bot_user_id:
-            if f"<@{self._bot_user_id}>" not in text:
+        bot_uid = self._team_bot_user_ids.get(team_id, self._bot_user_id)
+        if not is_dm and bot_uid:
+            if f"<@{bot_uid}>" not in text:
                return
            # Strip the bot mention from the text
-            text = text.replace(f"<@{self._bot_user_id}>", "").strip()
+            text = text.replace(f"<@{bot_uid}>", "").strip()

        # Determine message type
        msg_type = MessageType.TEXT
@@ -679,7 +758,7 @@ class SlackAdapter(BasePlatformAdapter):
                    if ext not in (".jpg", ".jpeg", ".png", ".gif", ".webp"):
                        ext = ".jpg"
                    # Slack private URLs require the bot token as auth header
-                    cached = await self._download_slack_file(url, ext)
+                    cached = await self._download_slack_file(url, ext, team_id=team_id)
                    media_urls.append(cached)
                    media_types.append(mimetype)
                    msg_type = MessageType.PHOTO
@@ -690,7 +769,7 @@ class SlackAdapter(BasePlatformAdapter):
                    ext = "." + mimetype.split("/")[-1].split(";")[0]
                    if ext not in (".ogg", ".mp3", ".wav", ".webm", ".m4a"):
                        ext = ".ogg"
-                    cached = await self._download_slack_file(url, ext, audio=True)
+                    cached = await self._download_slack_file(url, ext, audio=True, team_id=team_id)
                    media_urls.append(cached)
                    media_types.append(mimetype)
                    msg_type = MessageType.VOICE
@@ -721,7 +800,7 @@ class SlackAdapter(BasePlatformAdapter):
                        continue

                    # Download and cache
-                    raw_bytes = await self._download_slack_file_bytes(url)
+                    raw_bytes = await self._download_slack_file_bytes(url, team_id=team_id)
                    cached_path = cache_document_from_bytes(
                        raw_bytes, original_filename or f"document{ext}"
                    )
@@ -750,7 +829,7 @@ class SlackAdapter(BasePlatformAdapter):
                    logger.warning("[Slack] Failed to cache document from %s: %s", url, e, exc_info=True)

        # Resolve user display name (cached after first lookup)
-        user_name = await self._resolve_user_name(user_id)
+        user_name = await self._resolve_user_name(user_id, chat_id=channel_id)

        # Build source
        source = self.build_source(
@@ -787,6 +866,11 @@ class SlackAdapter(BasePlatformAdapter):
        text = command.get("text", "").strip()
        user_id = command.get("user_id", "")
        channel_id = command.get("channel_id", "")
+        team_id = command.get("team_id", "")
+
+        # Track which workspace owns this channel
+        if team_id and channel_id:
+            self._channel_team[channel_id] = team_id

        # Map subcommands to gateway commands — derived from central registry.
        # Also keep "compact" as a Slack-specific alias for /compress.
@@ -818,12 +902,12 @@ class SlackAdapter(BasePlatformAdapter):

        await self.handle_message(event)

-    async def _download_slack_file(self, url: str, ext: str, audio: bool = False) -> str:
+    async def _download_slack_file(self, url: str, ext: str, audio: bool = False, team_id: str = "") -> str:
        """Download a Slack file using the bot token for auth, with retry."""
        import asyncio
        import httpx

-        bot_token = self.config.token
+        bot_token = self._team_clients[team_id].token if team_id and team_id in self._team_clients else self.config.token
        last_exc = None

        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
@@ -853,12 +937,12 @@ class SlackAdapter(BasePlatformAdapter):
                    raise
        raise last_exc

-    async def _download_slack_file_bytes(self, url: str) -> bytes:
+    async def _download_slack_file_bytes(self, url: str, team_id: str = "") -> bytes:
        """Download a Slack file and return raw bytes, with retry."""
        import asyncio
        import httpx

-        bot_token = self.config.token
+        bot_token = self._team_clients[team_id].token if team_id and team_id in self._team_clients else self.config.token
        last_exc = None

        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
@@ -8,6 +8,7 @@ Uses python-telegram-bot library for:
 """

 import asyncio
+import json
 import logging
 import os
 import re
@@ -122,6 +123,8 @@ class TelegramAdapter(BasePlatformAdapter):
        super().__init__(config, Platform.TELEGRAM)
        self._app: Optional[Application] = None
        self._bot: Optional[Bot] = None
+        self._webhook_mode: bool = False
+        self._mention_patterns = self._compile_mention_patterns()
        self._reply_to_mode: str = getattr(config, 'reply_to_mode', 'first') or 'first'
        # Buffer rapid/album photo updates so Telegram image bursts are handled
        # as a single MessageEvent instead of self-interrupting multiple turns.
@@ -456,7 +459,19 @@ class TelegramAdapter(BasePlatformAdapter):
                    self._persist_dm_topic_thread_id(int(chat_id), topic_name, thread_id)

    async def connect(self) -> bool:
-        """Connect to Telegram and start polling for updates."""
+        """Connect to Telegram via polling or webhook.
+
+        By default, uses long polling (outbound connection to Telegram).
+        If ``TELEGRAM_WEBHOOK_URL`` is set, starts an HTTP webhook server
+        instead.  Webhook mode is useful for cloud deployments (Fly.io,
+        Railway) where inbound HTTP can wake a suspended machine.
+
+        Env vars for webhook mode::
+
+            TELEGRAM_WEBHOOK_URL    Public HTTPS URL (e.g. https://app.fly.dev/telegram)
+            TELEGRAM_WEBHOOK_PORT   Local listen port (default 8443)
+            TELEGRAM_WEBHOOK_SECRET Secret token for update verification
+        """
        if not TELEGRAM_AVAILABLE:
            logger.error(
                "[%s] python-telegram-bot not installed. Run: pip install python-telegram-bot",
@@ -550,27 +565,57 @@ class TelegramAdapter(BasePlatformAdapter):
                    else:
                        raise
            await self._app.start()
-            loop = asyncio.get_running_loop()

-            def _polling_error_callback(error: Exception) -> None:
-                if self._polling_error_task and not self._polling_error_task.done():
-                    return
-                if self._looks_like_polling_conflict(error):
-                    self._polling_error_task = loop.create_task(self._handle_polling_conflict(error))
-                elif self._looks_like_network_error(error):
-                    logger.warning("[%s] Telegram network error, scheduling reconnect: %s", self.name, error)
-                    self._polling_error_task = loop.create_task(self._handle_polling_network_error(error))
-                else:
-                    logger.error("[%s] Telegram polling error: %s", self.name, error, exc_info=True)
+            # Decide between webhook and polling mode
+            webhook_url = os.getenv("TELEGRAM_WEBHOOK_URL", "").strip()

-            # Store reference for retry use in _handle_polling_conflict
-            self._polling_error_callback_ref = _polling_error_callback
+            if webhook_url:
+                # ── Webhook mode ─────────────────────────────────────
+                # Telegram pushes updates to our HTTP endpoint.  This
+                # enables cloud platforms (Fly.io, Railway) to auto-wake
+                # suspended machines on inbound HTTP traffic.
+                webhook_port = int(os.getenv("TELEGRAM_WEBHOOK_PORT", "8443"))
+                webhook_secret = os.getenv("TELEGRAM_WEBHOOK_SECRET", "").strip() or None
+                from urllib.parse import urlparse
+                webhook_path = urlparse(webhook_url).path or "/telegram"

-            await self._app.updater.start_polling(
-                allowed_updates=Update.ALL_TYPES,
-                drop_pending_updates=True,
-                error_callback=_polling_error_callback,
-            )
+                await self._app.updater.start_webhook(
+                    listen="0.0.0.0",
+                    port=webhook_port,
+                    url_path=webhook_path,
+                    webhook_url=webhook_url,
+                    secret_token=webhook_secret,
+                    allowed_updates=Update.ALL_TYPES,
+                    drop_pending_updates=True,
+                )
+                self._webhook_mode = True
+                logger.info(
+                    "[%s] Webhook server listening on 0.0.0.0:%d%s",
+                    self.name, webhook_port, webhook_path,
+                )
+            else:
+                # ── Polling mode (default) ───────────────────────────
+                loop = asyncio.get_running_loop()
+
+                def _polling_error_callback(error: Exception) -> None:
+                    if self._polling_error_task and not self._polling_error_task.done():
+                        return
+                    if self._looks_like_polling_conflict(error):
+                        self._polling_error_task = loop.create_task(self._handle_polling_conflict(error))
+                    elif self._looks_like_network_error(error):
+                        logger.warning("[%s] Telegram network error, scheduling reconnect: %s", self.name, error)
+                        self._polling_error_task = loop.create_task(self._handle_polling_network_error(error))
+                    else:
+                        logger.error("[%s] Telegram polling error: %s", self.name, error, exc_info=True)
+
+                # Store reference for retry use in _handle_polling_conflict
+                self._polling_error_callback_ref = _polling_error_callback
+
+                await self._app.updater.start_polling(
+                    allowed_updates=Update.ALL_TYPES,
+                    drop_pending_updates=True,
+                    error_callback=_polling_error_callback,
+                )
            
            # Register bot commands so Telegram shows a hint menu when users type /
            # List is derived from the central COMMAND_REGISTRY — adding a new
@@ -590,7 +635,8 @@ class TelegramAdapter(BasePlatformAdapter):
                )
            
            self._mark_connected()
-            logger.info("[%s] Connected and polling for Telegram updates", self.name)
+            mode = "webhook" if self._webhook_mode else "polling"
+            logger.info("[%s] Connected to Telegram (%s mode)", self.name, mode)

            # Set up DM topics (Bot API 9.4 — Private Chat Topics)
            # Runs after connection is established so the bot can call createForumTopic.
@@ -618,7 +664,7 @@ class TelegramAdapter(BasePlatformAdapter):
            return False
    
    async def disconnect(self) -> None:
-        """Stop polling, cancel pending album flushes, and disconnect."""
+        """Stop polling/webhook, cancel pending album flushes, and disconnect."""
        pending_media_group_tasks = list(self._media_group_tasks.values())
        for task in pending_media_group_tasks:
            task.cancel()
@@ -762,6 +808,16 @@ class TelegramAdapter(BasePlatformAdapter):
                                )
                                effective_thread_id = None
                                continue
+                            if "message to be replied not found" in err_lower and reply_to_id is not None:
+                                # Original message was deleted before we
+                                # could reply — clear reply target and retry
+                                # so the response is still delivered.
+                                logger.warning(
+                                    "[%s] Reply target deleted, retrying without reply_to: %s",
+                                    self.name, send_err,
+                                )
+                                reply_to_id = None
+                                continue
                            # Other BadRequest errors are permanent — don't retry
                            raise
                        if _send_attempt < 2:
@@ -1315,6 +1371,148 @@ class TelegramAdapter(BasePlatformAdapter):

        return text
    
+    # ── Group mention gating ──────────────────────────────────────────────
+
+    def _telegram_require_mention(self) -> bool:
+        """Return whether group chats should require an explicit bot trigger."""
+        configured = self.config.extra.get("require_mention")
+        if configured is not None:
+            if isinstance(configured, str):
+                return configured.lower() in ("true", "1", "yes", "on")
+            return bool(configured)
+        return os.getenv("TELEGRAM_REQUIRE_MENTION", "false").lower() in ("true", "1", "yes", "on")
+
+    def _telegram_free_response_chats(self) -> set[str]:
+        raw = self.config.extra.get("free_response_chats")
+        if raw is None:
+            raw = os.getenv("TELEGRAM_FREE_RESPONSE_CHATS", "")
+        if isinstance(raw, list):
+            return {str(part).strip() for part in raw if str(part).strip()}
+        return {part.strip() for part in str(raw).split(",") if part.strip()}
+
+    def _compile_mention_patterns(self) -> List[re.Pattern]:
+        """Compile optional regex wake-word patterns for group triggers."""
+        patterns = self.config.extra.get("mention_patterns")
+        if patterns is None:
+            raw = os.getenv("TELEGRAM_MENTION_PATTERNS", "").strip()
+            if raw:
+                try:
+                    loaded = json.loads(raw)
+                except Exception:
+                    loaded = [part.strip() for part in raw.splitlines() if part.strip()]
+                    if not loaded:
+                        loaded = [part.strip() for part in raw.split(",") if part.strip()]
+                patterns = loaded
+
+        if patterns is None:
+            return []
+        if isinstance(patterns, str):
+            patterns = [patterns]
+        if not isinstance(patterns, list):
+            logger.warning(
+                "[%s] telegram mention_patterns must be a list or string; got %s",
+                self.name,
+                type(patterns).__name__,
+            )
+            return []
+
+        compiled: List[re.Pattern] = []
+        for pattern in patterns:
+            if not isinstance(pattern, str) or not pattern.strip():
+                continue
+            try:
+                compiled.append(re.compile(pattern, re.IGNORECASE))
+            except re.error as exc:
+                logger.warning("[%s] Invalid Telegram mention pattern %r: %s", self.name, pattern, exc)
+        if compiled:
+            logger.info("[%s] Loaded %d Telegram mention pattern(s)", self.name, len(compiled))
+        return compiled
+
+    def _is_group_chat(self, message: Message) -> bool:
+        chat = getattr(message, "chat", None)
+        if not chat:
+            return False
+        chat_type = str(getattr(chat, "type", "")).split(".")[-1].lower()
+        return chat_type in ("group", "supergroup")
+
+    def _is_reply_to_bot(self, message: Message) -> bool:
+        if not self._bot or not getattr(message, "reply_to_message", None):
+            return False
+        reply_user = getattr(message.reply_to_message, "from_user", None)
+        return bool(reply_user and getattr(reply_user, "id", None) == getattr(self._bot, "id", None))
+
+    def _message_mentions_bot(self, message: Message) -> bool:
+        if not self._bot:
+            return False
+
+        bot_username = (getattr(self._bot, "username", None) or "").lstrip("@").lower()
+        bot_id = getattr(self._bot, "id", None)
+
+        def _iter_sources():
+            yield getattr(message, "text", None) or "", getattr(message, "entities", None) or []
+            yield getattr(message, "caption", None) or "", getattr(message, "caption_entities", None) or []
+
+        for source_text, entities in _iter_sources():
+            if bot_username and f"@{bot_username}" in source_text.lower():
+                return True
+            for entity in entities:
+                entity_type = str(getattr(entity, "type", "")).split(".")[-1].lower()
+                if entity_type == "mention" and bot_username:
+                    offset = int(getattr(entity, "offset", -1))
+                    length = int(getattr(entity, "length", 0))
+                    if offset < 0 or length <= 0:
+                        continue
+                    if source_text[offset:offset + length].strip().lower() == f"@{bot_username}":
+                        return True
+                elif entity_type == "text_mention":
+                    user = getattr(entity, "user", None)
+                    if user and getattr(user, "id", None) == bot_id:
+                        return True
+        return False
+
+    def _message_matches_mention_patterns(self, message: Message) -> bool:
+        if not self._mention_patterns:
+            return False
+        for candidate in (getattr(message, "text", None), getattr(message, "caption", None)):
+            if not candidate:
+                continue
+            for pattern in self._mention_patterns:
+                if pattern.search(candidate):
+                    return True
+        return False
+
+    def _clean_bot_trigger_text(self, text: Optional[str]) -> Optional[str]:
+        if not text or not self._bot or not getattr(self._bot, "username", None):
+            return text
+        username = re.escape(self._bot.username)
+        cleaned = re.sub(rf"(?i)@{username}\b[,:\-]*\s*", "", text).strip()
+        return cleaned or text
+
+    def _should_process_message(self, message: Message, *, is_command: bool = False) -> bool:
+        """Apply Telegram group trigger rules.
+
+        DMs remain unrestricted. Group/supergroup messages are accepted when:
+        - the chat is explicitly allowlisted in ``free_response_chats``
+        - ``require_mention`` is disabled
+        - the message is a command
+        - the message replies to the bot
+        - the bot is @mentioned
+        - the text/caption matches a configured regex wake-word pattern
+        """
+        if not self._is_group_chat(message):
+            return True
+        if str(getattr(getattr(message, "chat", None), "id", "")) in self._telegram_free_response_chats():
+            return True
+        if not self._telegram_require_mention():
+            return True
+        if is_command:
+            return True
+        if self._is_reply_to_bot(message):
+            return True
+        if self._message_mentions_bot(message):
+            return True
+        return self._message_matches_mention_patterns(message)
+
    async def _handle_text_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
        """Handle incoming text messages.

@@ -1324,14 +1522,19 @@ class TelegramAdapter(BasePlatformAdapter):
        """
        if not update.message or not update.message.text:
            return
+        if not self._should_process_message(update.message):
+            return

        event = self._build_message_event(update.message, MessageType.TEXT)
+        event.text = self._clean_bot_trigger_text(event.text)
        self._enqueue_text_event(event)
    
    async def _handle_command(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
        """Handle incoming command messages."""
        if not update.message or not update.message.text:
            return
+        if not self._should_process_message(update.message, is_command=True):
+            return
        
        event = self._build_message_event(update.message, MessageType.COMMAND)
        await self.handle_message(event)
@@ -1340,6 +1543,8 @@ class TelegramAdapter(BasePlatformAdapter):
        """Handle incoming location/venue pin messages."""
        if not update.message:
            return
+        if not self._should_process_message(update.message):
+            return

        msg = update.message
        venue = getattr(msg, "venue", None)
@@ -1483,6 +1688,8 @@ class TelegramAdapter(BasePlatformAdapter):
        """Handle incoming media messages, downloading images to local cache."""
        if not update.message:
            return
+        if not self._should_process_message(update.message):
+            return
        
        msg = update.message
        
@@ -1506,7 +1713,7 @@ class TelegramAdapter(BasePlatformAdapter):
        
        # Add caption as text
        if msg.caption:
-            event.text = msg.caption
+            event.text = self._clean_bot_trigger_text(msg.caption)
        
        # Handle stickers: describe via vision tool with caching
        if msg.sticker:
@@ -118,6 +118,17 @@ class WebhookAdapter(BasePlatformAdapter):
        app.router.add_get("/health", self._handle_health)
        app.router.add_post("/webhooks/{route_name}", self._handle_webhook)

+        # Port conflict detection — fail fast if port is already in use
+        import socket as _socket
+        try:
+            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
+                _s.settimeout(1)
+                _s.connect(('127.0.0.1', self._port))
+            logger.error('[webhook] Port %d already in use. Set a different port in config.yaml: platforms.webhook.port', self._port)
+            return False
+        except (ConnectionRefusedError, OSError):
+            pass  # port is free
+
        self._runner = web.AppRunner(app)
        await self._runner.setup()
        site = web.TCPSite(self._runner, self._host, self._port)
@@ -142,6 +142,8 @@ class WhatsAppAdapter(BasePlatformAdapter):
        self._bridge_log_fh = None
        self._bridge_log: Optional[Path] = None
        self._poll_task: Optional[asyncio.Task] = None
+        self._http_session: Optional["aiohttp.ClientSession"] = None
+        self._session_lock_identity: Optional[str] = None
    
    async def connect(self) -> bool:
        """
@@ -160,6 +162,29 @@ class WhatsAppAdapter(BasePlatformAdapter):
        
        logger.info("[%s] Bridge found at %s", self.name, bridge_path)
        
+        # Acquire scoped lock to prevent duplicate sessions
+        try:
+            from gateway.status import acquire_scoped_lock
+
+            self._session_lock_identity = str(self._session_path)
+            acquired, existing = acquire_scoped_lock(
+                "whatsapp-session",
+                self._session_lock_identity,
+                metadata={"platform": self.platform.value},
+            )
+            if not acquired:
+                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
+                message = (
+                    "Another local Hermes gateway is already using this WhatsApp session"
+                    + (f" (PID {owner_pid})." if owner_pid else ".")
+                    + " Stop the other gateway before starting a second WhatsApp bridge."
+                )
+                logger.error("[%s] %s", self.name, message)
+                self._set_fatal_error("whatsapp_session_lock", message, retryable=False)
+                return False
+        except Exception as e:
+            logger.warning("[%s] Could not acquire session lock (non-fatal): %s", self.name, e)
+
        # Auto-install npm dependencies if node_modules doesn't exist
        bridge_dir = bridge_path.parent
        if not (bridge_dir / "node_modules").exists():
@@ -200,6 +225,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
                                print(f"[{self.name}] Using existing bridge (status: {bridge_status})")
                                self._mark_connected()
                                self._bridge_process = None  # Not managed by us
+                                self._http_session = aiohttp.ClientSession()
                                self._poll_task = asyncio.create_task(self._poll_messages())
                                return True
                            else:
@@ -305,6 +331,9 @@ class WhatsAppAdapter(BasePlatformAdapter):
                    print(f"[{self.name}]   Bridge log: {self._bridge_log}")
                    print(f"[{self.name}]   If session expired, re-pair: hermes whatsapp")
            
+            # Create a persistent HTTP session for all bridge communication
+            self._http_session = aiohttp.ClientSession()
+
            # Start message polling task
            self._poll_task = asyncio.create_task(self._poll_messages())
            
@@ -313,6 +342,12 @@ class WhatsAppAdapter(BasePlatformAdapter):
            return True
            
        except Exception as e:
+            if self._session_lock_identity:
+                try:
+                    from gateway.status import release_scoped_lock
+                    release_scoped_lock("whatsapp-session", self._session_lock_identity)
+                except Exception:
+                    pass
            logger.error("[%s] Failed to start bridge: %s", self.name, e, exc_info=True)
            self._close_bridge_log()
            return False
@@ -370,10 +405,32 @@ class WhatsAppAdapter(BasePlatformAdapter):
        else:
            # Bridge was not started by us, don't kill it
            print(f"[{self.name}] Disconnecting (external bridge left running)")
-        
+
+        # Cancel the poll task explicitly
+        if self._poll_task and not self._poll_task.done():
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        self._poll_task = None
+
+        # Close the persistent HTTP session
+        if self._http_session and not self._http_session.closed:
+            await self._http_session.close()
+        self._http_session = None
+
+        if self._session_lock_identity:
+            try:
+                from gateway.status import release_scoped_lock
+                release_scoped_lock("whatsapp-session", self._session_lock_identity)
+            except Exception as e:
+                logger.warning("[%s] Error releasing WhatsApp session lock: %s", self.name, e, exc_info=True)
+
        self._mark_disconnected()
        self._bridge_process = None
        self._close_bridge_log()
+        self._session_lock_identity = None
        print(f"[{self.name}] Disconnected")
    
    async def send(
@@ -384,7 +441,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
        metadata: Optional[Dict[str, Any]] = None
    ) -> SendResult:
        """Send a message via the WhatsApp bridge."""
-        if not self._running:
+        if not self._running or not self._http_session:
            return SendResult(success=False, error="Not connected")
        bridge_exit = await self._check_managed_bridge_exit()
        if bridge_exit:
@@ -392,36 +449,29 @@ class WhatsAppAdapter(BasePlatformAdapter):
        
        try:
            import aiohttp
+
+            payload = {
+                "chatId": chat_id,
+                "message": content,
+            }
+            if reply_to:
+                payload["replyTo"] = reply_to
            
-            async with aiohttp.ClientSession() as session:
-                payload = {
-                    "chatId": chat_id,
-                    "message": content,
-                }
-                if reply_to:
-                    payload["replyTo"] = reply_to
-                
-                async with session.post(
-                    f"http://127.0.0.1:{self._bridge_port}/send",
-                    json=payload,
-                    timeout=aiohttp.ClientTimeout(total=30)
-                ) as resp:
-                    if resp.status == 200:
-                        data = await resp.json()
-                        return SendResult(
-                            success=True,
-                            message_id=data.get("messageId"),
-                            raw_response=data
-                        )
-                    else:
-                        error = await resp.text()
-                        return SendResult(success=False, error=error)
-                        
-        except ImportError:
-            return SendResult(
-                success=False, 
-                error="aiohttp not installed. Run: pip install aiohttp"
-            )
+            async with self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/send",
+                json=payload,
+                timeout=aiohttp.ClientTimeout(total=30)
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return SendResult(
+                        success=True,
+                        message_id=data.get("messageId"),
+                        raw_response=data
+                    )
+                else:
+                    error = await resp.text()
+                    return SendResult(success=False, error=error)
        except Exception as e:
            return SendResult(success=False, error=str(e))

@@ -432,28 +482,27 @@ class WhatsAppAdapter(BasePlatformAdapter):
        content: str,
    ) -> SendResult:
        """Edit a previously sent message via the WhatsApp bridge."""
-        if not self._running:
+        if not self._running or not self._http_session:
            return SendResult(success=False, error="Not connected")
        bridge_exit = await self._check_managed_bridge_exit()
        if bridge_exit:
            return SendResult(success=False, error=bridge_exit)
        try:
            import aiohttp
-            async with aiohttp.ClientSession() as session:
-                async with session.post(
-                    f"http://127.0.0.1:{self._bridge_port}/edit",
-                    json={
-                        "chatId": chat_id,
-                        "messageId": message_id,
-                        "message": content,
-                    },
-                    timeout=aiohttp.ClientTimeout(total=15)
-                ) as resp:
-                    if resp.status == 200:
-                        return SendResult(success=True, message_id=message_id)
-                    else:
-                        error = await resp.text()
-                        return SendResult(success=False, error=error)
+            async with self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/edit",
+                json={
+                    "chatId": chat_id,
+                    "messageId": message_id,
+                    "message": content,
+                },
+                timeout=aiohttp.ClientTimeout(total=15)
+            ) as resp:
+                if resp.status == 200:
+                    return SendResult(success=True, message_id=message_id)
+                else:
+                    error = await resp.text()
+                    return SendResult(success=False, error=error)
        except Exception as e:
            return SendResult(success=False, error=str(e))

@@ -466,7 +515,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
        file_name: Optional[str] = None,
    ) -> SendResult:
        """Send any media file via bridge /send-media endpoint."""
-        if not self._running:
+        if not self._running or not self._http_session:
            return SendResult(success=False, error="Not connected")
        bridge_exit = await self._check_managed_bridge_exit()
        if bridge_exit:
@@ -487,22 +536,21 @@ class WhatsAppAdapter(BasePlatformAdapter):
            if file_name:
                payload["fileName"] = file_name

-            async with aiohttp.ClientSession() as session:
-                async with session.post(
-                    f"http://127.0.0.1:{self._bridge_port}/send-media",
-                    json=payload,
-                    timeout=aiohttp.ClientTimeout(total=120),
-                ) as resp:
-                    if resp.status == 200:
-                        data = await resp.json()
-                        return SendResult(
-                            success=True,
-                            message_id=data.get("messageId"),
-                            raw_response=data,
-                        )
-                    else:
-                        error = await resp.text()
-                        return SendResult(success=False, error=error)
+            async with self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/send-media",
+                json=payload,
+                timeout=aiohttp.ClientTimeout(total=120),
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return SendResult(
+                        success=True,
+                        message_id=data.get("messageId"),
+                        raw_response=data,
+                    )
+                else:
+                    error = await resp.text()
+                    return SendResult(success=False, error=error)

        except Exception as e:
            return SendResult(success=False, error=str(e))
@@ -560,45 +608,43 @@ class WhatsAppAdapter(BasePlatformAdapter):

    async def send_typing(self, chat_id: str, metadata=None) -> None:
        """Send typing indicator via bridge."""
-        if not self._running:
+        if not self._running or not self._http_session:
            return
        if await self._check_managed_bridge_exit():
            return
        
        try:
            import aiohttp
-            
-            async with aiohttp.ClientSession() as session:
-                await session.post(
-                    f"http://127.0.0.1:{self._bridge_port}/typing",
-                    json={"chatId": chat_id},
-                    timeout=aiohttp.ClientTimeout(total=5)
-                )
+
+            await self._http_session.post(
+                f"http://127.0.0.1:{self._bridge_port}/typing",
+                json={"chatId": chat_id},
+                timeout=aiohttp.ClientTimeout(total=5)
+            )
        except Exception:
            pass  # Ignore typing indicator failures
    
    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
        """Get information about a WhatsApp chat."""
-        if not self._running:
+        if not self._running or not self._http_session:
            return {"name": "Unknown", "type": "dm"}
        if await self._check_managed_bridge_exit():
            return {"name": chat_id, "type": "dm"}
        
        try:
            import aiohttp
-            
-            async with aiohttp.ClientSession() as session:
-                async with session.get(
-                    f"http://127.0.0.1:{self._bridge_port}/chat/{chat_id}",
-                    timeout=aiohttp.ClientTimeout(total=10)
-                ) as resp:
-                    if resp.status == 200:
-                        data = await resp.json()
-                        return {
-                            "name": data.get("name", chat_id),
-                            "type": "group" if data.get("isGroup") else "dm",
-                            "participants": data.get("participants", []),
-                        }
+
+            async with self._http_session.get(
+                f"http://127.0.0.1:{self._bridge_port}/chat/{chat_id}",
+                timeout=aiohttp.ClientTimeout(total=10)
+            ) as resp:
+                if resp.status == 200:
+                    data = await resp.json()
+                    return {
+                        "name": data.get("name", chat_id),
+                        "type": "group" if data.get("isGroup") else "dm",
+                        "participants": data.get("participants", []),
+                    }
        except Exception as e:
            logger.debug("Could not get WhatsApp chat info for %s: %s", chat_id, e)
        
@@ -606,29 +652,26 @@ class WhatsAppAdapter(BasePlatformAdapter):
    
    async def _poll_messages(self) -> None:
        """Poll the bridge for incoming messages."""
-        try:
-            import aiohttp
-        except ImportError:
-            print(f"[{self.name}] aiohttp not installed, message polling disabled")
-            return
-        
+        import aiohttp
+
        while self._running:
+            if not self._http_session:
+                break
            bridge_exit = await self._check_managed_bridge_exit()
            if bridge_exit:
                print(f"[{self.name}] {bridge_exit}")
                break
            try:
-                async with aiohttp.ClientSession() as session:
-                    async with session.get(
-                        f"http://127.0.0.1:{self._bridge_port}/messages",
-                        timeout=aiohttp.ClientTimeout(total=30)
-                    ) as resp:
-                        if resp.status == 200:
-                            messages = await resp.json()
-                            for msg_data in messages:
-                                event = await self._build_message_event(msg_data)
-                                if event:
-                                    await self.handle_message(event)
+                async with self._http_session.get(
+                    f"http://127.0.0.1:{self._bridge_port}/messages",
+                    timeout=aiohttp.ClientTimeout(total=30)
+                ) as resp:
+                    if resp.status == 200:
+                        messages = await resp.json()
+                        for msg_data in messages:
+                            event = await self._build_message_event(msg_data)
+                            if event:
+                                await self.handle_message(event)
            except asyncio.CancelledError:
                break
            except Exception as e:
@@ -77,6 +77,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))

 # Resolve Hermes home directory (respects HERMES_HOME override)
 from hermes_constants import get_hermes_home
+from utils import atomic_yaml_write
 _hermes_home = get_hermes_home()

 # Load environment variables from ~/.hermes/.env first.
@@ -224,6 +225,49 @@ from gateway.session import (
 from gateway.delivery import DeliveryRouter
 from gateway.platforms.base import BasePlatformAdapter, MessageEvent, MessageType

+
+def _normalize_whatsapp_identifier(value: str) -> str:
+    """Strip WhatsApp JID/LID syntax down to its stable numeric identifier."""
+    return (
+        str(value or "")
+        .strip()
+        .replace("+", "", 1)
+        .split(":", 1)[0]
+        .split("@", 1)[0]
+    )
+
+
+def _expand_whatsapp_auth_aliases(identifier: str) -> set:
+    """Resolve WhatsApp phone/LID aliases using bridge session mapping files."""
+    normalized = _normalize_whatsapp_identifier(identifier)
+    if not normalized:
+        return set()
+
+    session_dir = _hermes_home / "whatsapp" / "session"
+    resolved = set()
+    queue = [normalized]
+
+    while queue:
+        current = queue.pop(0)
+        if not current or current in resolved:
+            continue
+
+        resolved.add(current)
+        for suffix in ("", "_reverse"):
+            mapping_path = session_dir / f"lid-mapping-{current}{suffix}.json"
+            if not mapping_path.exists():
+                continue
+            try:
+                mapped = _normalize_whatsapp_identifier(
+                    json.loads(mapping_path.read_text(encoding="utf-8"))
+                )
+            except Exception:
+                continue
+            if mapped and mapped not in resolved:
+                queue.append(mapped)
+
+    return resolved
+
 logger = logging.getLogger(__name__)

 # Sentinel placed into _running_agents immediately when a session starts
@@ -279,10 +323,10 @@ def _resolve_gateway_model(config: dict | None = None) -> str:
    """Read model from env/config — mirrors the resolution in _run_agent_sync.

    Without this, temporary AIAgent instances (memory flush, /compress) fall
-    back to the hardcoded default ("anthropic/claude-opus-4.6") which fails
-    when the active provider is openai-codex.
+    back to the hardcoded default which fails when the active provider is
+    openai-codex.
    """
-    model = os.getenv("HERMES_MODEL") or os.getenv("LLM_MODEL") or "anthropic/claude-opus-4.6"
+    model = os.getenv("HERMES_MODEL") or os.getenv("LLM_MODEL") or ""
    cfg = config if config is not None else _load_gateway_config()
    model_cfg = cfg.get("model", {})
    if isinstance(model_cfg, str):
@@ -388,6 +432,13 @@ class GatewayRunner:
        self._honcho_managers: Dict[str, Any] = {}
        self._honcho_configs: Dict[str, Any] = {}

+        # Rate-limit compression warning messages sent to users.
+        # Keyed by chat_id — value is the timestamp of the last warning sent.
+        # Prevents the warning from firing on every message when a session
+        # remains above the threshold after compression.
+        self._compression_warn_sent: Dict[str, float] = {}
+        self._compression_warn_cooldown: int = 3600  # seconds (1 hour)
+
        # Ensure tirith security scanner is available (downloads if needed)
        try:
            from tools.tirith_security import ensure_installed
@@ -918,11 +969,12 @@ class GatewayRunner:
        return {}

    @staticmethod
-    def _load_fallback_model() -> dict | None:
-        """Load fallback model config from config.yaml.
+    def _load_fallback_model() -> list | dict | None:
+        """Load fallback provider chain from config.yaml.

-        Returns a dict with 'provider' and 'model' keys, or None if
-        not configured / both fields empty.
+        Returns a list of provider dicts (``fallback_providers``), a single
+        dict (legacy ``fallback_model``), or None if not configured.
+        AIAgent.__init__ normalizes both formats into a chain.
        """
        try:
            import yaml as _y
@@ -930,8 +982,8 @@ class GatewayRunner:
            if cfg_path.exists():
                with open(cfg_path, encoding="utf-8") as _f:
                    cfg = _y.safe_load(_f) or {}
-                fb = cfg.get("fallback_model", {}) or {}
-                if fb.get("provider") and fb.get("model"):
+                fb = cfg.get("fallback_providers") or cfg.get("fallback_model") or None
+                if fb:
                    return fb
        except Exception:
            pass
@@ -959,6 +1011,13 @@ class GatewayRunner:
        """
        logger.info("Starting Hermes Gateway...")
        logger.info("Session storage: %s", self.config.sessions_dir)
+        try:
+            from hermes_cli.profiles import get_active_profile_name
+            _profile = get_active_profile_name()
+            if _profile and _profile != "default":
+                logger.info("Active profile: %s", _profile)
+        except Exception:
+            pass
        try:
            from gateway.status import write_runtime_status
            write_runtime_status(gateway_state="starting", exit_reason=None)
@@ -974,6 +1033,8 @@ class GatewayRunner:
                       "EMAIL_ALLOWED_USERS",
                       "SMS_ALLOWED_USERS", "MATTERMOST_ALLOWED_USERS",
                       "MATRIX_ALLOWED_USERS", "DINGTALK_ALLOWED_USERS",
+                       "FEISHU_ALLOWED_USERS",
+                       "WECOM_ALLOWED_USERS",
                       "GATEWAY_ALLOWED_USERS")
        )
        _allow_all = os.getenv("GATEWAY_ALLOW_ALL_USERS", "").lower() in ("true", "1", "yes") or any(
@@ -982,7 +1043,9 @@ class GatewayRunner:
                       "WHATSAPP_ALLOW_ALL_USERS", "SLACK_ALLOW_ALL_USERS",
                       "SIGNAL_ALLOW_ALL_USERS", "EMAIL_ALLOW_ALL_USERS",
                       "SMS_ALLOW_ALL_USERS", "MATTERMOST_ALLOW_ALL_USERS",
-                       "MATRIX_ALLOW_ALL_USERS", "DINGTALK_ALLOW_ALL_USERS")
+                       "MATRIX_ALLOW_ALL_USERS", "DINGTALK_ALLOW_ALL_USERS",
+                       "FEISHU_ALLOW_ALL_USERS",
+                       "WECOM_ALLOW_ALL_USERS")
        )
        if not _any_allowlist and not _allow_all:
            logger.warning(
@@ -1425,6 +1488,20 @@ class GatewayRunner:
                return None
            return DingTalkAdapter(config)

+        elif platform == Platform.FEISHU:
+            from gateway.platforms.feishu import FeishuAdapter, check_feishu_requirements
+            if not check_feishu_requirements():
+                logger.warning("Feishu: lark-oapi not installed or FEISHU_APP_ID/SECRET not set")
+                return None
+            return FeishuAdapter(config)
+
+        elif platform == Platform.WECOM:
+            from gateway.platforms.wecom import WeComAdapter, check_wecom_requirements
+            if not check_wecom_requirements():
+                logger.warning("WeCom: aiohttp not installed or WECOM_BOT_ID/SECRET not set")
+                return None
+            return WeComAdapter(config)
+
        elif platform == Platform.MATTERMOST:
            from gateway.platforms.mattermost import MattermostAdapter, check_mattermost_requirements
            if not check_mattermost_requirements():
@@ -1491,6 +1568,8 @@ class GatewayRunner:
            Platform.MATTERMOST: "MATTERMOST_ALLOWED_USERS",
            Platform.MATRIX: "MATRIX_ALLOWED_USERS",
            Platform.DINGTALK: "DINGTALK_ALLOWED_USERS",
+            Platform.FEISHU: "FEISHU_ALLOWED_USERS",
+            Platform.WECOM: "WECOM_ALLOWED_USERS",
        }
        platform_allow_all_map = {
            Platform.TELEGRAM: "TELEGRAM_ALLOW_ALL_USERS",
@@ -1503,6 +1582,8 @@ class GatewayRunner:
            Platform.MATTERMOST: "MATTERMOST_ALLOW_ALL_USERS",
            Platform.MATRIX: "MATRIX_ALLOW_ALL_USERS",
            Platform.DINGTALK: "DINGTALK_ALLOW_ALL_USERS",
+            Platform.FEISHU: "FEISHU_ALLOW_ALL_USERS",
+            Platform.WECOM: "WECOM_ALLOW_ALL_USERS",
        }

        # Per-platform allow-all flag (e.g., DISCORD_ALLOW_ALL_USERS=true)
@@ -1530,10 +1611,23 @@ class GatewayRunner:
        if global_allowlist:
            allowed_ids.update(uid.strip() for uid in global_allowlist.split(",") if uid.strip())

-        # WhatsApp JIDs have @s.whatsapp.net suffix — strip it for comparison
        check_ids = {user_id}
        if "@" in user_id:
            check_ids.add(user_id.split("@")[0])
+
+        # WhatsApp: resolve phone↔LID aliases from bridge session mapping files
+        if source.platform == Platform.WHATSAPP:
+            normalized_allowed_ids = set()
+            for allowed_id in allowed_ids:
+                normalized_allowed_ids.update(_expand_whatsapp_auth_aliases(allowed_id))
+            if normalized_allowed_ids:
+                allowed_ids = normalized_allowed_ids
+
+            check_ids.update(_expand_whatsapp_auth_aliases(user_id))
+            normalized_user_id = _normalize_whatsapp_identifier(user_id)
+            if normalized_user_id:
+                check_ids.add(normalized_user_id)
+
        return bool(check_ids & allowed_ids)

    def _get_unauthorized_dm_behavior(self, platform: Optional[Platform]) -> str:
@@ -1743,6 +1837,9 @@ class GatewayRunner:
        if canonical == "verbose":
            return await self._handle_verbose_command(event)

+        if canonical == "yolo":
+            return await self._handle_yolo_command(event)
+
        if canonical == "provider":
            return await self._handle_provider_command(event)
        
@@ -2257,13 +2354,18 @@ class GatewayRunner:
                                        pass

                                # Still too large after compression — warn user
+                                # Rate-limited to once per cooldown period per
+                                # chat to avoid spamming on every message.
                                if _new_tokens >= _warn_token_threshold:
                                    logger.warning(
                                        "Session hygiene: still ~%s tokens after "
                                        "compression — suggesting /reset",
                                        f"{_new_tokens:,}",
                                    )
-                                    if _hyg_adapter:
+                                    _now = time.time()
+                                    _last_warn = self._compression_warn_sent.get(source.chat_id, 0)
+                                    if _hyg_adapter and _now - _last_warn >= self._compression_warn_cooldown:
+                                        self._compression_warn_sent[source.chat_id] = _now
                                        try:
                                            await _hyg_adapter.send(
                                                source.chat_id,
@@ -2285,7 +2387,10 @@ class GatewayRunner:
                        if _approx_tokens >= _warn_token_threshold:
                            _hyg_adapter = self.adapters.get(source.platform)
                            _hyg_meta = {"thread_id": source.thread_id} if source.thread_id else None
-                            if _hyg_adapter:
+                            _now = time.time()
+                            _last_warn = self._compression_warn_sent.get(source.chat_id, 0)
+                            if _hyg_adapter and _now - _last_warn >= self._compression_warn_cooldown:
+                                self._compression_warn_sent[source.chat_id] = _now
                                try:
                                    await _hyg_adapter.send(
                                        source.chat_id,
@@ -3088,8 +3193,7 @@ class GatewayRunner:
                if "agent" not in config or not isinstance(config.get("agent"), dict):
                    config["agent"] = {}
                config["agent"]["system_prompt"] = ""
-                with open(config_path, "w") as f:
-                    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+                atomic_yaml_write(config_path, config)
            except Exception as e:
                return f"⚠️ Failed to save personality change: {e}"
            self._ephemeral_system_prompt = ""
@@ -3102,8 +3206,7 @@ class GatewayRunner:
                if "agent" not in config or not isinstance(config.get("agent"), dict):
                    config["agent"] = {}
                config["agent"]["system_prompt"] = new_prompt
-                with open(config_path, 'w', encoding="utf-8") as f:
-                    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
+                atomic_yaml_write(config_path, config)
            except Exception as e:
                return f"⚠️ Failed to save personality change: {e}"

@@ -3193,8 +3296,7 @@ class GatewayRunner:
                with open(config_path, encoding="utf-8") as f:
                    user_config = yaml.safe_load(f) or {}
            user_config[env_key] = chat_id
-            with open(config_path, 'w', encoding="utf-8") as f:
-                yaml.dump(user_config, f, default_flow_style=False)
+            atomic_yaml_write(config_path, user_config)
            # Also set in the current environment so it takes effect immediately
            os.environ[env_key] = str(chat_id)
        except Exception as e:
@@ -3807,7 +3909,7 @@ class GatewayRunner:
                # Send media files
                for media_path in (media_files or []):
                    try:
-                        await adapter.send_file(
+                        await adapter.send_document(
                            chat_id=source.chat_id,
                            file_path=media_path,
                        )
@@ -3862,8 +3964,7 @@ class GatewayRunner:
                        current[k] = {}
                    current = current[k]
                current[keys[-1]] = value
-                with open(config_path, "w", encoding="utf-8") as f:
-                    yaml.dump(user_config, f, default_flow_style=False, sort_keys=False)
+                atomic_yaml_write(config_path, user_config)
                return True
            except Exception as e:
                logger.error("Failed to save config key %s: %s", key_path, e)
@@ -3916,6 +4017,16 @@ class GatewayRunner:
        else:
            return f"🧠 ✓ Reasoning effort set to `{effort}` (this session only)"

+    async def _handle_yolo_command(self, event: MessageEvent) -> str:
+        """Handle /yolo — toggle dangerous command approval bypass."""
+        current = bool(os.environ.get("HERMES_YOLO_MODE"))
+        if current:
+            os.environ.pop("HERMES_YOLO_MODE", None)
+            return "⚠️ YOLO mode **OFF** — dangerous commands will require approval."
+        else:
+            os.environ["HERMES_YOLO_MODE"] = "1"
+            return "⚡ YOLO mode **ON** — all commands auto-approved. Use with caution."
+
    async def _handle_verbose_command(self, event: MessageEvent) -> str:
        """Handle /verbose command — cycle tool progress display mode.

@@ -3971,8 +4082,7 @@ class GatewayRunner:
            if "display" not in user_config or not isinstance(user_config.get("display"), dict):
                user_config["display"] = {}
            user_config["display"]["tool_progress"] = new_mode
-            with open(config_path, "w", encoding="utf-8") as f:
-                yaml.dump(user_config, f, default_flow_style=False, sort_keys=False)
+            atomic_yaml_write(config_path, user_config)
            return f"{descriptions[new_mode]}\n_(saved to config — takes effect on next message)_"
        except Exception as e:
            logger.warning("Failed to save tool_progress mode: %s", e)
@@ -4937,6 +5047,14 @@ class GatewayRunner:
        from hermes_cli.tools_config import _get_platform_tools
        enabled_toolsets = sorted(_get_platform_tools(user_config, platform_key))

+        # Apply tool preview length config (0 = no limit)
+        try:
+            from agent.display import set_tool_preview_max_len
+            _tpl = user_config.get("display", {}).get("tool_preview_length", 0)
+            set_tool_preview_max_len(int(_tpl) if _tpl else 0)
+        except Exception:
+            pass
+
        # Tool progress mode from config.yaml: "all", "new", "verbose", "off"
        # Falls back to env vars for backward compatibility.
        # YAML 1.1 parses bare `off` as boolean False — normalise before
@@ -4982,9 +5100,11 @@ class GatewayRunner:
                return
            
            if preview:
-                # Truncate preview to keep messages clean
-                if len(preview) > 80:
-                    preview = preview[:77] + "..."
+                # Truncate preview unless config says unlimited
+                from agent.display import get_tool_preview_max_len
+                _pl = get_tool_preview_max_len()
+                if _pl > 0 and len(preview) > _pl:
+                    preview = preview[:_pl - 3] + "..."
                msg = f"{emoji} {tool_name}: \"{preview}\""
            else:
                msg = f"{emoji} {tool_name}..."
@@ -1,12 +1,11 @@
 #!/usr/bin/env python3
 """
-Hermes Agent CLI Launcher
+Hermes Agent CLI launcher.

-This is a convenience wrapper to launch the Hermes CLI.
-Usage: ./hermes [options]
+This wrapper should behave like the installed `hermes` command, including
+subcommands such as `gateway`, `cron`, and `doctor`.
 """

 if __name__ == "__main__":
-    from cli import main
-    import fire
-    fire.Fire(main)
+    from hermes_cli.main import main
+    main()
@@ -11,5 +11,5 @@ Provides subcommands for:
 - hermes cron          - Manage cron jobs
 """

-__version__ = "0.5.0"
-__release_date__ = "2026.3.28"
+__version__ = "0.6.0"
+__release_date__ = "2026.3.30"
@@ -696,6 +696,10 @@ def resolve_provider(
        "hf": "huggingface", "hugging-face": "huggingface", "huggingface-hub": "huggingface",
        "go": "opencode-go", "opencode-go-sub": "opencode-go",
        "kilo": "kilocode", "kilo-code": "kilocode", "kilo-gateway": "kilocode",
+        # Local server aliases — route through the generic custom provider
+        "lmstudio": "custom", "lm-studio": "custom", "lm_studio": "custom",
+        "ollama": "custom", "vllm": "custom", "llamacpp": "custom",
+        "llama.cpp": "custom", "llama-cpp": "custom",
    }
    normalized = _PROVIDER_ALIASES.get(normalized, normalized)

@@ -742,7 +746,12 @@ def resolve_provider(
            if has_usable_secret(os.getenv(env_var, "")):
                return pid

-    return "openrouter"
+    raise AuthError(
+        "No inference provider configured. Run 'hermes model' to choose a "
+        "provider and model, or set an API key (OPENROUTER_API_KEY, "
+        "OPENAI_API_KEY, etc.) in ~/.hermes/.env.",
+        code="no_provider_configured",
+    )


 # =============================================================================
@@ -2021,7 +2030,8 @@ def _login_openai_codex(args, pconfig: ProviderConfig) -> None:
    config_path = _update_config_for_provider("openai-codex", creds.get("base_url", DEFAULT_CODEX_BASE_URL))
    print()
    print("Login successful!")
-    print("  Auth state: ~/.hermes/auth.json")
+    from hermes_constants import display_hermes_home as _dhh
+    print(f"  Auth state: {_dhh()}/auth.json")
    print(f"  Config updated: {config_path} (model.provider=openai-codex)")


@@ -2300,21 +2310,20 @@ def _login_nous(args, pconfig: ProviderConfig) -> None:
                raise AuthError("No runtime API key available to fetch models",
                                provider="nous", code="invalid_token")

-            model_ids = fetch_nous_models(
-                inference_base_url=runtime_base_url,
-                api_key=runtime_key,
-                timeout_seconds=timeout_seconds,
-                verify=verify,
-            )
+            # Use curated model list (same as OpenRouter defaults) instead
+            # of the full /models dump which returns hundreds of models.
+            from hermes_cli.models import _PROVIDER_MODELS
+            model_ids = _PROVIDER_MODELS.get("nous", [])

            print()
            if model_ids:
+                print(f"Showing {len(model_ids)} curated models — use \"Enter custom model name\" for others.")
                selected_model = _prompt_model_selection(model_ids)
                if selected_model:
                    _save_model_choice(selected_model)
                    print(f"Default model set to: {selected_model}")
            else:
-                print("No models were returned by the inference API.")
+                print("No curated models available for Nous Portal.")
        except Exception as exc:
            message = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)
            print()
@@ -258,7 +258,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
        get_toolset_for_tool: Callable to map tool name -> toolset name.
        context_length: Model's context window size in tokens.
    """
-    from model_tools import check_tool_availability
+    from model_tools import check_tool_availability, TOOLSET_REQUIREMENTS
    if get_toolset_for_tool is None:
        from model_tools import get_toolset_for_tool

@@ -267,8 +267,18 @@ def build_welcome_banner(console: Console, model: str, cwd: str,

    _, unavailable_toolsets = check_tool_availability(quiet=True)
    disabled_tools = set()
+    # Tools whose toolset has a check_fn are lazy-initialized (e.g. honcho,
+    # homeassistant) — they show as unavailable at banner time because the
+    # check hasn't run yet, but they aren't misconfigured.
+    lazy_tools = set()
    for item in unavailable_toolsets:
-        disabled_tools.update(item.get("tools", []))
+        toolset_name = item.get("name", "")
+        ts_req = TOOLSET_REQUIREMENTS.get(toolset_name, {})
+        tools_in_ts = item.get("tools", [])
+        if ts_req.get("check_fn"):
+            lazy_tools.update(tools_in_ts)
+        else:
+            disabled_tools.update(tools_in_ts)

    layout_table = Table.grid(padding=(0, 2))
    layout_table.add_column("left", justify="center")
@@ -328,6 +338,8 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
        for name in sorted(tool_names):
            if name in disabled_tools:
                colored_names.append(f"[red]{name}[/]")
+            elif name in lazy_tools:
+                colored_names.append(f"[yellow]{name}[/]")
            else:
                colored_names.append(f"[{text}]{name}[/]")

@@ -347,6 +359,8 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
                    colored_names.append("[dim]...[/]")
                elif name in disabled_tools:
                    colored_names.append(f"[red]{name}[/]")
+                elif name in lazy_tools:
+                    colored_names.append(f"[yellow]{name}[/]")
                else:
                    colored_names.append(f"[{text}]{name}[/]")
            tools_str = ", ".join(colored_names)
@@ -403,6 +417,15 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
    if mcp_connected:
        summary_parts.append(f"{mcp_connected} MCP servers")
    summary_parts.append("/help for commands")
+    # Show active profile name when not 'default'
+    try:
+        from hermes_cli.profiles import get_active_profile_name
+        _profile_name = get_active_profile_name()
+        if _profile_name and _profile_name != "default":
+            right_lines.append(f"[bold {accent}]Profile:[/] [{text}]{_profile_name}[/]")
+    except Exception:
+        pass  # Never break the banner over a profiles.py bug
+
    right_lines.append(f"[dim {dim}]{' · '.join(summary_parts)}[/]")

    # Update check — use prefetched result if available
@@ -12,6 +12,7 @@ import getpass

 from hermes_cli.banner import cprint, _DIM, _RST
 from hermes_cli.config import save_env_value_secure
+from hermes_constants import display_hermes_home


 def clarify_callback(cli, question, choices):
@@ -131,7 +132,8 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
            }

        stored = save_env_value_secure(var_name, value)
-        cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
+        _dhh = display_hermes_home()
+        cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
        return {
            **stored,
            "skipped": False,
@@ -183,7 +185,8 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
                }

            stored = save_env_value_secure(var_name, value)
-            cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
+            _dhh = display_hermes_home()
+            cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
            return {
                **stored,
                "skipped": False,
@@ -238,7 +241,8 @@ def approval_callback(cli, command: str, description: str) -> str:
        lock = cli._approval_lock

    with lock:
-        timeout = 60
+        from cli import CLI_CONFIG
+        timeout = CLI_CONFIG.get("approvals", {}).get("timeout", 60)
        response_queue = queue.Queue()
        choices = ["once", "session", "always", "deny"]
        if len(command) > 70:
@@ -5,6 +5,7 @@ toggleable list of items.  Falls back to a numbered text UI when
 curses is unavailable (Windows without curses, piped stdin, etc.).
 """

+import sys
 from typing import List, Set

 from hermes_cli.colors import Colors, color
@@ -26,6 +27,10 @@ def curses_checklist(
        The indices the user confirmed as checked.  On cancel (ESC/q),
        returns ``pre_selected`` unchanged.
    """
+    # Safety: return defaults when stdin is not a terminal.
+    if not sys.stdin.isatty():
+        return set(pre_selected)
+
    try:
        import curses
        selected = set(pre_selected)
@@ -88,7 +88,19 @@ def claw_command(args):

 def _cmd_migrate(args):
    """Run the OpenClaw → Hermes migration."""
-    source_dir = Path(getattr(args, "source", None) or Path.home() / ".openclaw")
+    # Check current and legacy OpenClaw directories
+    explicit_source = getattr(args, "source", None)
+    if explicit_source:
+        source_dir = Path(explicit_source)
+    else:
+        source_dir = Path.home() / ".openclaw"
+        if not source_dir.is_dir():
+            # Try legacy directory names
+            for legacy in (".clawdbot", ".moldbot"):
+                candidate = Path.home() / legacy
+                if candidate.is_dir():
+                    source_dir = candidate
+                    break
    dry_run = getattr(args, "dry_run", False)
    preset = getattr(args, "preset", "full")
    overwrite = getattr(args, "overwrite", False)
@@ -12,6 +12,8 @@ import os
 logger = logging.getLogger(__name__)

 DEFAULT_CODEX_MODELS: List[str] = [
+    "gpt-5.4-mini",
+    "gpt-5.4",
    "gpt-5.3-codex",
    "gpt-5.2-codex",
    "gpt-5.1-codex-max",
@@ -19,8 +21,9 @@ DEFAULT_CODEX_MODELS: List[str] = [
 ]

 _FORWARD_COMPAT_TEMPLATE_MODELS: List[tuple[str, tuple[str, ...]]] = [
-    ("gpt-5.3-codex", ("gpt-5.2-codex",)),
+    ("gpt-5.4-mini", ("gpt-5.3-codex", "gpt-5.2-codex")),
    ("gpt-5.4", ("gpt-5.3-codex", "gpt-5.2-codex")),
+    ("gpt-5.3-codex", ("gpt-5.2-codex",)),
    ("gpt-5.3-codex-spark", ("gpt-5.3-codex", "gpt-5.2-codex")),
 ]

@@ -90,6 +90,8 @@ COMMAND_REGISTRY: list[CommandDef] = [
    CommandDef("verbose", "Cycle tool progress display: off -> new -> all -> verbose",
               "Configuration", cli_only=True,
               gateway_config_gate="display.tool_progress_command"),
+    CommandDef("yolo", "Toggle YOLO mode (skip all dangerous command approvals)",
+               "Configuration"),
    CommandDef("reasoning", "Manage reasoning effort and display", "Configuration",
               args_hint="[level|show|hide]",
               subcommands=("none", "low", "minimal", "medium", "high", "xhigh", "show", "hide", "on", "off")),
@@ -34,6 +34,8 @@ _EXTRA_ENV_KEYS = frozenset({
    "SIGNAL_ACCOUNT", "SIGNAL_HTTP_URL",
    "SIGNAL_ALLOWED_USERS", "SIGNAL_GROUP_ALLOWED_USERS",
    "DINGTALK_CLIENT_ID", "DINGTALK_CLIENT_SECRET",
+    "FEISHU_APP_ID", "FEISHU_APP_SECRET", "FEISHU_ENCRYPT_KEY", "FEISHU_VERIFICATION_TOKEN",
+    "WECOM_BOT_ID", "WECOM_SECRET",
    "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT",
    "WHATSAPP_MODE", "WHATSAPP_ENABLED",
    "MATTERMOST_HOME_CHANNEL", "MATTERMOST_REPLY_MODE",
@@ -135,6 +137,7 @@ def ensure_hermes_home():

 DEFAULT_CONFIG = {
    "model": "anthropic/claude-opus-4.6",
+    "fallback_providers": [],
    "toolsets": ["hermes-cli"],
    "agent": {
        "max_turns": 90,
@@ -220,7 +223,8 @@ DEFAULT_CONFIG = {
            "model": "",           # e.g. "google/gemini-2.5-flash", "gpt-4o"
            "base_url": "",        # direct OpenAI-compatible endpoint (takes precedence over provider)
            "api_key": "",         # API key for base_url (falls back to OPENAI_API_KEY)
-            "timeout": 30,         # seconds — increase for slow local vision models
+            "timeout": 30,         # seconds — LLM API call timeout; increase for slow local vision models
+            "download_timeout": 30,  # seconds — image HTTP download timeout; increase for slow connections
        },
        "web_extract": {
            "provider": "auto",
@@ -284,6 +288,7 @@ DEFAULT_CONFIG = {
        "show_cost": False,       # Show $ cost in the status bar (off by default)
        "skin": "default",
        "tool_progress_command": False,  # Enable /verbose command in messaging gateway
+        "tool_preview_length": 0,  # Max chars for tool call previews (0 = no limit, show full paths/commands)
    },

    # Privacy settings
@@ -366,6 +371,13 @@ DEFAULT_CONFIG = {
    # Never saved to sessions, logs, or trajectories.
    "prefill_messages_file": "",
    
+    # Skills — external skill directories for sharing skills across tools/agents.
+    # Each path is expanded (~, ${VAR}) and resolved.  Read-only — skill creation
+    # always goes to ~/.hermes/skills/.
+    "skills": {
+        "external_dirs": [],   # e.g. ["~/.agents/skills", "/shared/team-skills"]
+    },
+
    # Honcho AI-native memory -- reads ~/.honcho/config.json as single source of truth.
    # This section is only needed for hermes-specific overrides; everything else
    # (apiKey, workspace, peerName, sessions, enabled) comes from the global config.
@@ -396,6 +408,7 @@ DEFAULT_CONFIG = {
    #   off    — skip all approval prompts (equivalent to --yolo)
    "approvals": {
        "mode": "manual",
+        "timeout": 60,
    },

    # Permanently allowed dangerous command patterns (added via "always" approval)
@@ -421,6 +434,12 @@ DEFAULT_CONFIG = {
        },
    },

+    "cron": {
+        # Wrap delivered cron responses with a header (task name) and footer
+        # ("The agent cannot see this message").  Set to false for clean output.
+        "wrap_response": True,
+    },
+
    # Config schema version - bump this when adding new required fields
    "_config_version": 10,
 }
@@ -817,6 +836,20 @@ OPTIONAL_ENV_VARS = {
        "password": False,
        "category": "messaging",
    },
+    "MATTERMOST_REQUIRE_MENTION": {
+        "description": "Require @mention in Mattermost channels (default: true). Set to false to respond to all messages.",
+        "prompt": "Require @mention in channels",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+    },
+    "MATTERMOST_FREE_RESPONSE_CHANNELS": {
+        "description": "Comma-separated Mattermost channel IDs where bot responds without @mention",
+        "prompt": "Free-response channel IDs (comma-separated)",
+        "url": None,
+        "password": False,
+        "category": "messaging",
+    },
    "MATRIX_HOMESERVER": {
        "description": "Matrix homeserver URL (e.g. https://matrix.example.org)",
        "prompt": "Matrix homeserver URL",
@@ -4,7 +4,8 @@ Used by `hermes tools` and `hermes skills` for interactive checklists.
 Provides a curses multi-select with keyboard navigation, plus a
 text-based numbered fallback for terminals without curses support.
 """
-from typing import List, Set
+import sys
+from typing import Callable, List, Optional, Set

 from hermes_cli.colors import Colors, color

@@ -15,6 +16,7 @@ def curses_checklist(
    selected: Set[int],
    *,
    cancel_returns: Set[int] | None = None,
+    status_fn: Optional[Callable[[Set[int]], str]] = None,
 ) -> Set[int]:
    """Curses multi-select checklist. Returns set of selected indices.

@@ -23,10 +25,18 @@ def curses_checklist(
        items: Display labels for each row.
        selected: Indices that start checked (pre-selected).
        cancel_returns: Returned on ESC/q. Defaults to the original *selected*.
+        status_fn: Optional callback ``f(chosen_indices) -> str`` whose return
+            value is rendered on the bottom row of the terminal.  Use this for
+            live aggregate info (e.g. estimated token counts).
    """
    if cancel_returns is None:
        cancel_returns = set(selected)

+    # Safety: curses and input() both hang or spin when stdin is not a
+    # terminal (e.g. subprocess pipe).  Return defaults immediately.
+    if not sys.stdin.isatty():
+        return cancel_returns
+
    try:
        import curses
        chosen = set(selected)
@@ -47,6 +57,9 @@ def curses_checklist(
                stdscr.clear()
                max_y, max_x = stdscr.getmaxyx()

+                # Reserve bottom row for status bar when status_fn provided
+                footer_rows = 1 if status_fn else 0
+
                # Header
                try:
                    hattr = curses.A_BOLD
@@ -62,7 +75,7 @@ def curses_checklist(
                    pass

                # Scrollable item list
-                visible_rows = max_y - 3
+                visible_rows = max_y - 3 - footer_rows
                if cursor < scroll_offset:
                    scroll_offset = cursor
                elif cursor >= scroll_offset + visible_rows:
@@ -72,7 +85,7 @@ def curses_checklist(
                    range(scroll_offset, min(len(items), scroll_offset + visible_rows))
                ):
                    y = draw_i + 3
-                    if y >= max_y - 1:
+                    if y >= max_y - 1 - footer_rows:
                        break
                    check = "✓" if i in chosen else " "
                    arrow = "→" if i == cursor else " "
@@ -87,6 +100,20 @@ def curses_checklist(
                    except curses.error:
                        pass

+                # Status bar (bottom row, right-aligned)
+                if status_fn:
+                    try:
+                        status_text = status_fn(chosen)
+                        if status_text:
+                            # Right-align on the bottom row
+                            sx = max(0, max_x - len(status_text) - 1)
+                            sattr = curses.A_DIM
+                            if curses.has_colors():
+                                sattr |= curses.color_pair(3)
+                            stdscr.addnstr(max_y - 1, sx, status_text, max_x - sx - 1, sattr)
+                    except curses.error:
+                        pass
+
                stdscr.refresh()
                key = stdscr.getch()

@@ -107,7 +134,7 @@ def curses_checklist(
        return result_holder[0] if result_holder[0] is not None else cancel_returns

    except Exception:
-        return _numbered_fallback(title, items, selected, cancel_returns)
+        return _numbered_fallback(title, items, selected, cancel_returns, status_fn)


 def _numbered_fallback(
@@ -115,6 +142,7 @@ def _numbered_fallback(
    items: List[str],
    selected: Set[int],
    cancel_returns: Set[int],
+    status_fn: Optional[Callable[[Set[int]], str]] = None,
 ) -> Set[int]:
    """Text-based toggle fallback for terminals without curses."""
    chosen = set(selected)
@@ -125,6 +153,10 @@ def _numbered_fallback(
        for i, label in enumerate(items):
            marker = color("[✓]", Colors.GREEN) if i in chosen else "[ ]"
            print(f"  {marker} {i + 1:>2}. {label}")
+        if status_fn:
+            status_text = status_fn(chosen)
+            if status_text:
+                print(color(f"\n  {status_text}", Colors.DIM))
        print()
        try:
            val = input(color("  Toggle # (or Enter to confirm): ", Colors.DIM)).strip()
@@ -10,9 +10,11 @@ import subprocess
 import shutil

 from hermes_cli.config import get_project_root, get_hermes_home, get_env_path
+from hermes_constants import display_hermes_home

 PROJECT_ROOT = get_project_root()
 HERMES_HOME = get_hermes_home()
+_DHH = display_hermes_home()  # user-facing display path (e.g. ~/.hermes or ~/.hermes/profiles/coder)

 # Load environment variables from ~/.hermes/.env so API key checks work
 from dotenv import load_dotenv
@@ -209,14 +211,14 @@ def run_doctor(args):
    # Check ~/.hermes/.env (primary location for user config)
    env_path = HERMES_HOME / '.env'
    if env_path.exists():
-        check_ok("~/.hermes/.env file exists")
+        check_ok(f"{_DHH}/.env file exists")
        
        # Check for common issues
        content = env_path.read_text()
        if _has_provider_env_config(content):
            check_ok("API key or custom endpoint configured")
        else:
-            check_warn("No API key found in ~/.hermes/.env")
+            check_warn(f"No API key found in {_DHH}/.env")
            issues.append("Run 'hermes setup' to configure API keys")
    else:
        # Also check project root as fallback
@@ -224,11 +226,11 @@ def run_doctor(args):
        if fallback_env.exists():
            check_ok(".env file exists (in project directory)")
        else:
-            check_fail("~/.hermes/.env file missing")
+            check_fail(f"{_DHH}/.env file missing")
            if should_fix:
                env_path.parent.mkdir(parents=True, exist_ok=True)
                env_path.touch()
-                check_ok("Created empty ~/.hermes/.env")
+                check_ok(f"Created empty {_DHH}/.env")
                check_info("Run 'hermes setup' to configure API keys")
                fixed_count += 1
            else:
@@ -238,7 +240,7 @@ def run_doctor(args):
    # Check ~/.hermes/config.yaml (primary) or project cli-config.yaml (fallback)
    config_path = HERMES_HOME / 'config.yaml'
    if config_path.exists():
-        check_ok("~/.hermes/config.yaml exists")
+        check_ok(f"{_DHH}/config.yaml exists")
    else:
        fallback_config = PROJECT_ROOT / 'cli-config.yaml'
        if fallback_config.exists():
@@ -248,11 +250,11 @@ def run_doctor(args):
            if should_fix and example_config.exists():
                config_path.parent.mkdir(parents=True, exist_ok=True)
                shutil.copy2(str(example_config), str(config_path))
-                check_ok("Created ~/.hermes/config.yaml from cli-config.yaml.example")
+                check_ok(f"Created {_DHH}/config.yaml from cli-config.yaml.example")
                fixed_count += 1
            elif should_fix:
                check_warn("config.yaml not found and no example to copy from")
-                manual_issues.append("Create ~/.hermes/config.yaml manually")
+                manual_issues.append(f"Create {_DHH}/config.yaml manually")
            else:
                check_warn("config.yaml not found", "(using defaults)")
    
@@ -294,28 +296,28 @@ def run_doctor(args):
    
    hermes_home = HERMES_HOME
    if hermes_home.exists():
-        check_ok("~/.hermes directory exists")
+        check_ok(f"{_DHH} directory exists")
    else:
        if should_fix:
            hermes_home.mkdir(parents=True, exist_ok=True)
-            check_ok("Created ~/.hermes directory")
+            check_ok(f"Created {_DHH} directory")
            fixed_count += 1
        else:
-            check_warn("~/.hermes not found", "(will be created on first use)")
+            check_warn(f"{_DHH} not found", "(will be created on first use)")
    
    # Check expected subdirectories
    expected_subdirs = ["cron", "sessions", "logs", "skills", "memories"]
    for subdir_name in expected_subdirs:
        subdir_path = hermes_home / subdir_name
        if subdir_path.exists():
-            check_ok(f"~/.hermes/{subdir_name}/ exists")
+            check_ok(f"{_DHH}/{subdir_name}/ exists")
        else:
            if should_fix:
                subdir_path.mkdir(parents=True, exist_ok=True)
-                check_ok(f"Created ~/.hermes/{subdir_name}/")
+                check_ok(f"Created {_DHH}/{subdir_name}/")
                fixed_count += 1
            else:
-                check_warn(f"~/.hermes/{subdir_name}/ not found", "(will be created on first use)")
+                check_warn(f"{_DHH}/{subdir_name}/ not found", "(will be created on first use)")
    
    # Check for SOUL.md persona file
    soul_path = hermes_home / "SOUL.md"
@@ -324,11 +326,11 @@ def run_doctor(args):
        # Check if it's just the template comments (no real content)
        lines = [l for l in content.splitlines() if l.strip() and not l.strip().startswith(("<!--", "-->", "#"))]
        if lines:
-            check_ok("~/.hermes/SOUL.md exists (persona configured)")
+            check_ok(f"{_DHH}/SOUL.md exists (persona configured)")
        else:
-            check_info("~/.hermes/SOUL.md exists but is empty — edit it to customize personality")
+            check_info(f"{_DHH}/SOUL.md exists but is empty — edit it to customize personality")
    else:
-        check_warn("~/.hermes/SOUL.md not found", "(create it to give Hermes a custom personality)")
+        check_warn(f"{_DHH}/SOUL.md not found", "(create it to give Hermes a custom personality)")
        if should_fix:
            soul_path.parent.mkdir(parents=True, exist_ok=True)
            soul_path.write_text(
@@ -337,13 +339,13 @@ def run_doctor(args):
                "You are Hermes, a helpful AI assistant.\n",
                encoding="utf-8",
            )
-            check_ok("Created ~/.hermes/SOUL.md with basic template")
+            check_ok(f"Created {_DHH}/SOUL.md with basic template")
            fixed_count += 1
    
    # Check memory directory
    memories_dir = hermes_home / "memories"
    if memories_dir.exists():
-        check_ok("~/.hermes/memories/ directory exists")
+        check_ok(f"{_DHH}/memories/ directory exists")
        memory_file = memories_dir / "MEMORY.md"
        user_file = memories_dir / "USER.md"
        if memory_file.exists():
@@ -357,10 +359,10 @@ def run_doctor(args):
        else:
            check_info("USER.md not created yet (will be created when the agent first writes a memory)")
    else:
-        check_warn("~/.hermes/memories/ not found", "(will be created on first use)")
+        check_warn(f"{_DHH}/memories/ not found", "(will be created on first use)")
        if should_fix:
            memories_dir.mkdir(parents=True, exist_ok=True)
-            check_ok("Created ~/.hermes/memories/")
+            check_ok(f"Created {_DHH}/memories/")
            fixed_count += 1
    
    # Check SQLite session store
@@ -372,11 +374,11 @@ def run_doctor(args):
            cursor = conn.execute("SELECT COUNT(*) FROM sessions")
            count = cursor.fetchone()[0]
            conn.close()
-            check_ok(f"~/.hermes/state.db exists ({count} sessions)")
+            check_ok(f"{_DHH}/state.db exists ({count} sessions)")
        except Exception as e:
-            check_warn(f"~/.hermes/state.db exists but has issues: {e}")
+            check_warn(f"{_DHH}/state.db exists but has issues: {e}")
    else:
-        check_info("~/.hermes/state.db not created yet (will be created on first session)")
+        check_info(f"{_DHH}/state.db not created yet (will be created on first session)")

    _check_gateway_service_linger(issues)
    
@@ -691,7 +693,7 @@ def run_doctor(args):
    if github_token:
        check_ok("GitHub token configured (authenticated API access)")
    else:
-        check_warn("No GITHUB_TOKEN", "(60 req/hr rate limit — set in ~/.hermes/.env for better rates)")
+        check_warn("No GITHUB_TOKEN", f"(60 req/hr rate limit — set in {_DHH}/.env for better rates)")

    # =========================================================================
    # Honcho memory
@@ -728,6 +730,53 @@ def run_doctor(args):
    except Exception as _e:
        check_warn("Honcho check failed", str(_e))

+    # =========================================================================
+    # Profiles
+    # =========================================================================
+    try:
+        from hermes_cli.profiles import list_profiles, _get_wrapper_dir, profile_exists
+        import re as _re
+
+        named_profiles = [p for p in list_profiles() if not p.is_default]
+        if named_profiles:
+            print()
+            print(color("◆ Profiles", Colors.CYAN, Colors.BOLD))
+            check_ok(f"{len(named_profiles)} profile(s) found")
+            wrapper_dir = _get_wrapper_dir()
+            for p in named_profiles:
+                parts = []
+                if p.gateway_running:
+                    parts.append("gateway running")
+                if p.model:
+                    parts.append(p.model[:30])
+                if not (p.path / "config.yaml").exists():
+                    parts.append("⚠ missing config")
+                if not (p.path / ".env").exists():
+                    parts.append("no .env")
+                wrapper = wrapper_dir / p.name
+                if not wrapper.exists():
+                    parts.append("no alias")
+                status = ", ".join(parts) if parts else "configured"
+                check_ok(f"  {p.name}: {status}")
+
+            # Check for orphan wrappers
+            if wrapper_dir.is_dir():
+                for wrapper in wrapper_dir.iterdir():
+                    if not wrapper.is_file():
+                        continue
+                    try:
+                        content = wrapper.read_text()
+                        if "hermes -p" in content:
+                            _m = _re.search(r"hermes -p (\S+)", content)
+                            if _m and not profile_exists(_m.group(1)):
+                                check_warn(f"Orphan alias: {wrapper.name} → profile '{_m.group(1)}' no longer exists")
+                    except Exception:
+                        pass
+    except ImportError:
+        pass
+    except Exception as _e:
+        logger.debug("Profile health check failed: %s", _e)
+
    # =========================================================================
    # Summary
    # =========================================================================
@@ -15,6 +15,8 @@ from pathlib import Path
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()

 from hermes_cli.config import get_env_value, get_hermes_home, save_env_value, is_managed, managed_error
+# display_hermes_home is imported lazily at call sites to avoid ImportError
+# when hermes_constants is cached from a pre-update version during `hermes update`.
 from hermes_cli.setup import (
    print_header, print_info, print_success, print_warning, print_error,
    prompt, prompt_choice, prompt_yes_no,
@@ -935,7 +937,8 @@ def launchd_install(force: bool = False):
    print()
    print("Next steps:")
    print("  hermes gateway status             # Check status")
-    print("  tail -f ~/.hermes/logs/gateway.log  # View logs")
+    from hermes_constants import display_hermes_home as _dhh
+    print(f"  tail -f {_dhh()}/logs/gateway.log  # View logs")

 def launchd_uninstall():
    plist_path = get_launchd_plist_path()
@@ -1319,6 +1322,59 @@ _PLATFORMS = [
             "help": "The AppSecret from your DingTalk application credentials."},
        ],
    },
+    {
+        "key": "feishu",
+        "label": "Feishu / Lark",
+        "emoji": "🪽",
+        "token_var": "FEISHU_APP_ID",
+        "setup_instructions": [
+            "1. Go to https://open.feishu.cn/ (or https://open.larksuite.com/ for Lark)",
+            "2. Create an app and copy the App ID and App Secret",
+            "3. Enable the Bot capability for the app",
+            "4. Choose WebSocket (recommended) or Webhook connection mode",
+            "5. Add the bot to a group chat or message it directly",
+            "6. Restrict access with FEISHU_ALLOWED_USERS for production use",
+        ],
+        "vars": [
+            {"name": "FEISHU_APP_ID", "prompt": "App ID", "password": False,
+             "help": "The App ID from your Feishu/Lark application."},
+            {"name": "FEISHU_APP_SECRET", "prompt": "App Secret", "password": True,
+             "help": "The App Secret from your Feishu/Lark application."},
+            {"name": "FEISHU_DOMAIN", "prompt": "Domain — feishu or lark (default: feishu)", "password": False,
+             "help": "Use 'feishu' for Feishu China, or 'lark' for Lark international."},
+            {"name": "FEISHU_CONNECTION_MODE", "prompt": "Connection mode — websocket or webhook (default: websocket)", "password": False,
+             "help": "websocket is recommended unless you specifically need webhook mode."},
+            {"name": "FEISHU_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, or empty)", "password": False,
+             "is_allowlist": True,
+             "help": "Restrict which Feishu/Lark users can interact with the bot."},
+            {"name": "FEISHU_HOME_CHANNEL", "prompt": "Home chat ID (optional, for cron/notifications)", "password": False,
+             "help": "Chat ID for scheduled results and notifications."},
+        ],
+    },
+    {
+        "key": "wecom",
+        "label": "WeCom (Enterprise WeChat)",
+        "emoji": "💬",
+        "token_var": "WECOM_BOT_ID",
+        "setup_instructions": [
+            "1. Go to WeCom Admin Console → Applications → Create AI Bot",
+            "2. Copy the Bot ID and Secret from the bot's credentials page",
+            "3. The bot connects via WebSocket — no public endpoint needed",
+            "4. Add the bot to a group chat or message it directly in WeCom",
+            "5. Restrict access with WECOM_ALLOWED_USERS for production use",
+        ],
+        "vars": [
+            {"name": "WECOM_BOT_ID", "prompt": "Bot ID", "password": False,
+             "help": "The Bot ID from your WeCom AI Bot."},
+            {"name": "WECOM_SECRET", "prompt": "Secret", "password": True,
+             "help": "The secret from your WeCom AI Bot."},
+            {"name": "WECOM_ALLOWED_USERS", "prompt": "Allowed user IDs (comma-separated, or empty)", "password": False,
+             "is_allowlist": True,
+             "help": "Restrict which WeCom users can interact with the bot."},
+            {"name": "WECOM_HOME_CHANNEL", "prompt": "Home chat ID (optional, for cron/notifications)", "password": False,
+             "help": "Chat ID for scheduled results and notifications."},
+        ],
+    },
 ]


@@ -50,10 +50,92 @@ import sys
 from pathlib import Path
 from typing import Optional

+def _require_tty(command_name: str) -> None:
+    """Exit with a clear error if stdin is not a terminal.
+
+    Interactive TUI commands (hermes tools, hermes setup, hermes model) use
+    curses or input() prompts that spin at 100% CPU when stdin is a pipe.
+    This guard prevents accidental non-interactive invocation.
+    """
+    if not sys.stdin.isatty():
+        print(
+            f"Error: 'hermes {command_name}' requires an interactive terminal.\n"
+            f"It cannot be run through a pipe or non-interactive subprocess.\n"
+            f"Run it directly in your terminal instead.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
 # Add project root to path
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 sys.path.insert(0, str(PROJECT_ROOT))

+# ---------------------------------------------------------------------------
+# Profile override — MUST happen before any hermes module import.
+#
+# Many modules cache HERMES_HOME at import time (module-level constants).
+# We intercept --profile/-p from sys.argv here and set the env var so that
+# every subsequent ``os.getenv("HERMES_HOME", ...)`` resolves correctly.
+# The flag is stripped from sys.argv so argparse never sees it.
+# Falls back to ~/.hermes/active_profile for sticky default.
+# ---------------------------------------------------------------------------
+def _apply_profile_override() -> None:
+    """Pre-parse --profile/-p and set HERMES_HOME before module imports."""
+    argv = sys.argv[1:]
+    profile_name = None
+    consume = 0
+
+    # 1. Check for explicit -p / --profile flag
+    for i, arg in enumerate(argv):
+        if arg in ("--profile", "-p") and i + 1 < len(argv):
+            profile_name = argv[i + 1]
+            consume = 2
+            break
+        elif arg.startswith("--profile="):
+            profile_name = arg.split("=", 1)[1]
+            consume = 1
+            break
+
+    # 2. If no flag, check ~/.hermes/active_profile
+    if profile_name is None:
+        try:
+            active_path = Path.home() / ".hermes" / "active_profile"
+            if active_path.exists():
+                name = active_path.read_text().strip()
+                if name and name != "default":
+                    profile_name = name
+                    consume = 0  # don't strip anything from argv
+        except (UnicodeDecodeError, OSError):
+            pass  # corrupted file, skip
+
+    # 3. If we found a profile, resolve and set HERMES_HOME
+    if profile_name is not None:
+        try:
+            from hermes_cli.profiles import resolve_profile_env
+            hermes_home = resolve_profile_env(profile_name)
+        except (ValueError, FileNotFoundError) as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            sys.exit(1)
+        except Exception as exc:
+            # A bug in profiles.py must NEVER prevent hermes from starting
+            print(f"Warning: profile override failed ({exc}), using default", file=sys.stderr)
+            return
+        os.environ["HERMES_HOME"] = hermes_home
+        # Strip the flag from argv so argparse doesn't choke
+        if consume > 0:
+            for i, arg in enumerate(argv):
+                if arg in ("--profile", "-p"):
+                    start = i + 1  # +1 because argv is sys.argv[1:]
+                    sys.argv = sys.argv[:start] + sys.argv[start + consume:]
+                    break
+                elif arg.startswith("--profile="):
+                    start = i + 1
+                    sys.argv = sys.argv[:start] + sys.argv[start + 1:]
+                    break
+
+_apply_profile_override()
+
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
 from hermes_cli.config import get_hermes_home
@@ -552,6 +634,7 @@ def cmd_gateway(args):

 def cmd_whatsapp(args):
    """Set up WhatsApp: choose mode, configure, install bridge, pair via QR."""
+    _require_tty("whatsapp")
    import subprocess
    from pathlib import Path
    from hermes_cli.config import get_env_value, save_env_value
@@ -738,12 +821,14 @@ def cmd_whatsapp(args):

 def cmd_setup(args):
    """Interactive setup wizard."""
+    _require_tty("setup")
    from hermes_cli.setup import run_setup_wizard
    run_setup_wizard(args)


 def cmd_model(args):
    """Select default model — starts with provider selection, then model picker."""
+    _require_tty("model")
    from hermes_cli.auth import (
        resolve_provider, AuthError, format_auth_error,
    )
@@ -980,6 +1065,7 @@ def _model_flow_openrouter(config, current_model=""):
            cfg["model"] = model
        model["provider"] = "openrouter"
        model["base_url"] = OPENROUTER_BASE_URL
+        model["api_mode"] = "chat_completions"
        save_config(cfg)
        deactivate_provider()
        print(f"Default model set to: {selected} (via OpenRouter)")
@@ -1018,14 +1104,20 @@ def _model_flow_nous(config, current_model=""):
        # login_nous already handles model selection + config update
        return

-    # Already logged in — fetch models and select
-    print("Fetching models from Nous Portal...")
+    # Already logged in — use curated model list (same as OpenRouter defaults).
+    # The live /models endpoint returns hundreds of models; the curated list
+    # shows only agentic models users recognize from OpenRouter.
+    from hermes_cli.models import _PROVIDER_MODELS
+    model_ids = _PROVIDER_MODELS.get("nous", [])
+    if not model_ids:
+        print("No curated models available for Nous Portal.")
+        return
+
+    print(f"Showing {len(model_ids)} curated models — use \"Enter custom model name\" for others.")
+
+    # Verify credentials are still valid (catches expired sessions early)
    try:
        creds = resolve_nous_runtime_credentials(min_key_ttl_seconds=5 * 60)
-        model_ids = fetch_nous_models(
-            inference_base_url=creds.get("base_url", ""),
-            api_key=creds.get("api_key", ""),
-        )
    except Exception as exc:
        relogin = isinstance(exc, AuthError) and exc.relogin_required
        msg = format_auth_error(exc) if isinstance(exc, AuthError) else str(exc)
@@ -1042,11 +1134,7 @@ def _model_flow_nous(config, current_model=""):
            except Exception as login_exc:
                print(f"Re-login failed: {login_exc}")
            return
-        print(f"Could not fetch models: {msg}")
-        return
-
-    if not model_ids:
-        print("No models returned by the inference API.")
+        print(f"Could not verify credentials: {msg}")
        return

    selected = _prompt_model_selection(model_ids, current_model=current_model)
@@ -1203,6 +1291,7 @@ def _model_flow_custom(config):
            cfg["model"] = model
        model["provider"] = "custom"
        model["base_url"] = effective_url
+        model.pop("api_mode", None)  # let runtime auto-detect from URL
        save_config(cfg)
        deactivate_provider()

@@ -1984,6 +2073,7 @@ def _model_flow_kimi(config, current_model=""):
            cfg["model"] = model
        model["provider"] = provider_id
        model["base_url"] = effective_base
+        model.pop("api_mode", None)  # let runtime auto-detect from URL
        save_config(cfg)
        deactivate_provider()

@@ -2057,7 +2147,7 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
        api_key_for_probe = existing_key or (get_env_value(key_env) if key_env else "")
        live_models = fetch_api_models(api_key_for_probe, effective_base)

-    if live_models:
+    if live_models and len(live_models) >= len(curated):
        model_list = live_models
        print(f"  Found {len(model_list)} model(s) from {pconfig.name} API")
    else:
@@ -2090,6 +2180,7 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
            cfg["model"] = model
        model["provider"] = provider_id
        model["base_url"] = effective_base
+        model.pop("api_mode", None)  # let runtime auto-detect from URL
        save_config(cfg)
        deactivate_provider()

@@ -2121,7 +2212,8 @@ def _run_anthropic_oauth_flow(save_env_value):
        ):
            use_anthropic_claude_code_credentials(save_fn=save_env_value)
            print("  ✓ Claude Code credentials linked.")
-            print("    Hermes will use Claude's credential store directly instead of copying a setup-token into ~/.hermes/.env.")
+            from hermes_constants import display_hermes_home as _dhh_fn
+            print(f"    Hermes will use Claude's credential store directly instead of copying a setup-token into {_dhh_fn()}/.env.")
            return True
        return False

@@ -2387,10 +2479,39 @@ def cmd_version(args):

 def cmd_uninstall(args):
    """Uninstall Hermes Agent."""
+    _require_tty("uninstall")
    from hermes_cli.uninstall import run_uninstall
    run_uninstall(args)


+def _clear_bytecode_cache(root: Path) -> int:
+    """Remove all __pycache__ directories under *root*.
+
+    Stale .pyc files can cause ImportError after code updates when Python
+    loads a cached bytecode file that references names that no longer exist
+    (or don't yet exist) in the updated source.  Clearing them forces Python
+    to recompile from the .py source on next import.
+
+    Returns the number of directories removed.
+    """
+    removed = 0
+    for dirpath, dirnames, _ in os.walk(root):
+        # Skip venv / node_modules / .git entirely
+        dirnames[:] = [
+            d for d in dirnames
+            if d not in ("venv", ".venv", "node_modules", ".git", ".worktrees")
+        ]
+        if os.path.basename(dirpath) == "__pycache__":
+            try:
+                import shutil as _shutil
+                _shutil.rmtree(dirpath)
+                removed += 1
+            except OSError:
+                pass
+            dirnames.clear()  # nothing left to recurse into
+    return removed
+
+
 def _update_via_zip(args):
    """Update Hermes Agent by downloading a ZIP archive.
    
@@ -2432,7 +2553,7 @@ def _update_via_zip(args):
                    break
        
        # Copy updated files over existing installation, preserving venv/node_modules/.git
-        preserve = {'venv', 'node_modules', '.git', '__pycache__', '.env'}
+        preserve = {'venv', 'node_modules', '.git', '.env'}
        update_count = 0
        for item in os.listdir(extracted):
            if item in preserve:
@@ -2455,6 +2576,11 @@ def _update_via_zip(args):
    except Exception as e:
        print(f"✗ ZIP update failed: {e}")
        sys.exit(1)
+
+    # Clear stale bytecode after ZIP extraction
+    removed = _clear_bytecode_cache(PROJECT_ROOT)
+    if removed:
+        print(f"  ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}")
    
    # Reinstall Python dependencies (try .[all] first for optional extras,
    # fall back to . if extras fail — mirrors the install script behavior)
@@ -2853,6 +2979,13 @@ def cmd_update(args):
                    )
        
        _invalidate_update_cache()
+
+        # Clear stale .pyc bytecode cache — prevents ImportError on gateway
+        # restart when updated source references names that didn't exist in
+        # the old bytecode (e.g. get_hermes_home added to hermes_constants).
+        removed = _clear_bytecode_cache(PROJECT_ROOT)
+        if removed:
+            print(f"  ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}")
        
        # Reinstall Python dependencies (try .[all] first for optional extras,
        # fall back to . if extras fail — mirrors the install script behavior)
@@ -2901,6 +3034,17 @@ def cmd_update(args):
        print()
        print("✓ Code updated!")
        
+        # After git pull, source files on disk are newer than cached Python
+        # modules in this process.  Reload hermes_constants so that any lazy
+        # import executed below (skills sync, gateway restart) sees new
+        # attributes like display_hermes_home() added since the last release.
+        try:
+            import importlib
+            import hermes_constants as _hc
+            importlib.reload(_hc)
+        except Exception:
+            pass  # non-fatal — worst case a lazy import fails gracefully
+        
        # Sync bundled skills (copies new, updates changed, respects user deletions)
        try:
            from tools.skills_sync import sync_skills
@@ -2919,7 +3063,35 @@ def cmd_update(args):
                print("  ✓ Skills are up to date")
        except Exception as e:
            logger.debug("Skills sync during update failed: %s", e)
-        
+
+        # Sync bundled skills to all other profiles
+        try:
+            from hermes_cli.profiles import list_profiles, get_active_profile_name, seed_profile_skills
+            active = get_active_profile_name()
+            other_profiles = [p for p in list_profiles() if not p.is_default and p.name != active]
+            if other_profiles:
+                print()
+                print("→ Syncing bundled skills to other profiles...")
+                for p in other_profiles:
+                    try:
+                        r = seed_profile_skills(p.path, quiet=True)
+                        if r:
+                            copied = len(r.get("copied", []))
+                            updated = len(r.get("updated", []))
+                            modified = len(r.get("user_modified", []))
+                            parts = []
+                            if copied: parts.append(f"+{copied} new")
+                            if updated: parts.append(f"↑{updated} updated")
+                            if modified: parts.append(f"~{modified} user-modified")
+                            status = ", ".join(parts) if parts else "up to date"
+                        else:
+                            status = "sync failed"
+                        print(f"  {p.name}: {status}")
+                    except Exception as pe:
+                        print(f"  {p.name}: error ({pe})")
+        except Exception:
+            pass  # profiles module not available or no profiles
+
        # Check for config migrations
        print()
        print("→ Checking configuration for new options...")
@@ -3117,6 +3289,7 @@ def _coalesce_session_name_args(argv: list) -> list:
        "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
        "status", "cron", "doctor", "config", "pairing", "skills", "tools",
        "mcp", "sessions", "insights", "version", "update", "uninstall",
+        "profile",
    }
    _SESSION_FLAGS = {"-c", "--continue", "-r", "--resume"}

@@ -3140,6 +3313,253 @@ def _coalesce_session_name_args(argv: list) -> list:
    return result


+def cmd_profile(args):
+    """Profile management — create, delete, list, switch, alias."""
+    from hermes_cli.profiles import (
+        list_profiles, create_profile, delete_profile, seed_profile_skills,
+        get_active_profile, set_active_profile, get_active_profile_name,
+        check_alias_collision, create_wrapper_script, remove_wrapper_script,
+        _is_wrapper_dir_in_path, _get_wrapper_dir,
+    )
+    from hermes_constants import display_hermes_home
+
+    action = getattr(args, "profile_action", None)
+
+    if action is None:
+        # Bare `hermes profile` — show current profile status
+        profile_name = get_active_profile_name()
+        dhh = display_hermes_home()
+        print(f"\nActive profile: {profile_name}")
+        print(f"Path:           {dhh}")
+
+        profiles = list_profiles()
+        for p in profiles:
+            if p.name == profile_name or (profile_name == "default" and p.is_default):
+                if p.model:
+                    print(f"Model:          {p.model}" + (f" ({p.provider})" if p.provider else ""))
+                print(f"Gateway:        {'running' if p.gateway_running else 'stopped'}")
+                print(f"Skills:         {p.skill_count} installed")
+                if p.alias_path:
+                    print(f"Alias:          {p.name} → hermes -p {p.name}")
+                break
+        print()
+        return
+
+    if action == "list":
+        profiles = list_profiles()
+        active = get_active_profile_name()
+
+        if not profiles:
+            print("No profiles found.")
+            return
+
+        # Header
+        print(f"\n {'Profile':<16} {'Model':<28} {'Gateway':<12} {'Alias'}")
+        print(f" {'─' * 15}    {'─' * 27}    {'─' * 11}    {'─' * 12}")
+
+        for p in profiles:
+            marker = " ◆" if (p.name == active or (active == "default" and p.is_default)) else "  "
+            name = p.name
+            model = (p.model or "—")[:26]
+            gw = "running" if p.gateway_running else "stopped"
+            alias = p.name if p.alias_path else "—"
+            if p.is_default:
+                alias = "—"
+            print(f"{marker}{name:<15} {model:<28} {gw:<12} {alias}")
+        print()
+
+    elif action == "use":
+        name = args.profile_name
+        try:
+            set_active_profile(name)
+            if name == "default":
+                print(f"Switched to: default (~/.hermes)")
+            else:
+                print(f"Switched to: {name}")
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "create":
+        name = args.profile_name
+        clone = getattr(args, "clone", False)
+        clone_all = getattr(args, "clone_all", False)
+        no_alias = getattr(args, "no_alias", False)
+
+        try:
+            clone_from = getattr(args, "clone_from", None)
+
+            profile_dir = create_profile(
+                name=name,
+                clone_from=clone_from,
+                clone_all=clone_all,
+                clone_config=clone,
+                no_alias=no_alias,
+            )
+            print(f"\nProfile '{name}' created at {profile_dir}")
+
+            if clone or clone_all:
+                source_label = getattr(args, "clone_from", None) or get_active_profile_name()
+                if clone_all:
+                    print(f"Full copy from {source_label}.")
+                else:
+                    print(f"Cloned config, .env, SOUL.md from {source_label}.")
+
+            # Seed bundled skills (skip if --clone-all already copied them)
+            if not clone_all:
+                result = seed_profile_skills(profile_dir)
+                if result:
+                    copied = len(result.get("copied", []))
+                    print(f"{copied} bundled skills synced.")
+                else:
+                    print("⚠ Skills could not be seeded. Run `{} update` to retry.".format(name))
+
+            # Create wrapper alias
+            if not no_alias:
+                collision = check_alias_collision(name)
+                if collision:
+                    print(f"\n⚠ Cannot create alias '{name}' — {collision}")
+                    print(f"  Choose a custom alias:  hermes profile alias {name} --name <custom>")
+                    print(f"  Or access via flag:     hermes -p {name} chat")
+                else:
+                    wrapper_path = create_wrapper_script(name)
+                    if wrapper_path:
+                        print(f"Wrapper created: {wrapper_path}")
+                        if not _is_wrapper_dir_in_path():
+                            print(f"\n⚠ {_get_wrapper_dir()} is not in your PATH.")
+                            print(f'  Add to your shell config (~/.bashrc or ~/.zshrc):')
+                            print(f'    export PATH="$HOME/.local/bin:$PATH"')
+
+            # Next steps
+            print(f"\nNext steps:")
+            print(f"  {name} setup              Configure API keys and model")
+            print(f"  {name} chat               Start chatting")
+            print(f"  {name} gateway start      Start the messaging gateway")
+            if clone or clone_all:
+                from hermes_constants import get_hermes_home
+                profile_dir_display = f"~/.hermes/profiles/{name}"
+                print(f"\n  Edit {profile_dir_display}/.env for different API keys")
+                print(f"  Edit {profile_dir_display}/SOUL.md for different personality")
+            print()
+
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "delete":
+        name = args.profile_name
+        yes = getattr(args, "yes", False)
+        try:
+            delete_profile(name, yes=yes)
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "show":
+        name = args.profile_name
+        from hermes_cli.profiles import get_profile_dir, profile_exists, _read_config_model, _check_gateway_running, _count_skills
+        if not profile_exists(name):
+            print(f"Error: Profile '{name}' does not exist.")
+            sys.exit(1)
+        profile_dir = get_profile_dir(name)
+        model, provider = _read_config_model(profile_dir)
+        gw = _check_gateway_running(profile_dir)
+        skills = _count_skills(profile_dir)
+        wrapper = _get_wrapper_dir() / name
+
+        print(f"\nProfile: {name}")
+        print(f"Path:    {profile_dir}")
+        if model:
+            print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
+        print(f"Gateway: {'running' if gw else 'stopped'}")
+        print(f"Skills:  {skills}")
+        print(f".env:    {'exists' if (profile_dir / '.env').exists() else 'not configured'}")
+        print(f"SOUL.md: {'exists' if (profile_dir / 'SOUL.md').exists() else 'not configured'}")
+        if wrapper.exists():
+            print(f"Alias:   {wrapper}")
+        print()
+
+    elif action == "alias":
+        name = args.profile_name
+        remove = getattr(args, "remove", False)
+        custom_name = getattr(args, "alias_name", None)
+
+        from hermes_cli.profiles import profile_exists
+        if not profile_exists(name):
+            print(f"Error: Profile '{name}' does not exist.")
+            sys.exit(1)
+
+        alias_name = custom_name or name
+
+        if remove:
+            if remove_wrapper_script(alias_name):
+                print(f"✓ Removed alias '{alias_name}'")
+            else:
+                print(f"No alias '{alias_name}' found to remove.")
+        else:
+            collision = check_alias_collision(alias_name)
+            if collision:
+                print(f"Error: {collision}")
+                sys.exit(1)
+            wrapper_path = create_wrapper_script(alias_name)
+            if wrapper_path:
+                # If custom name, write the profile name into the wrapper
+                if custom_name:
+                    wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
+                print(f"✓ Alias created: {wrapper_path}")
+                if not _is_wrapper_dir_in_path():
+                    print(f"⚠ {_get_wrapper_dir()} is not in your PATH.")
+
+    elif action == "rename":
+        from hermes_cli.profiles import rename_profile
+        try:
+            new_dir = rename_profile(args.old_name, args.new_name)
+            print(f"\nProfile renamed: {args.old_name} → {args.new_name}")
+            print(f"Path: {new_dir}\n")
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "export":
+        from hermes_cli.profiles import export_profile
+        name = args.profile_name
+        output = args.output or f"{name}.tar.gz"
+        try:
+            result_path = export_profile(name, output)
+            print(f"✓ Exported '{name}' to {result_path}")
+        except (ValueError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+    elif action == "import":
+        from hermes_cli.profiles import import_profile
+        try:
+            profile_dir = import_profile(args.archive, name=getattr(args, "import_name", None))
+            name = profile_dir.name
+            print(f"✓ Imported profile '{name}' at {profile_dir}")
+
+            # Offer to create alias
+            collision = check_alias_collision(name)
+            if not collision:
+                wrapper_path = create_wrapper_script(name)
+                if wrapper_path:
+                    print(f"  Wrapper created: {wrapper_path}")
+            print()
+        except (ValueError, FileExistsError, FileNotFoundError) as e:
+            print(f"Error: {e}")
+            sys.exit(1)
+
+
+def cmd_completion(args):
+    """Print shell completion script."""
+    from hermes_cli.profiles import generate_bash_completion, generate_zsh_completion
+    shell = getattr(args, "shell", "bash")
+    if shell == "zsh":
+        print(generate_zsh_completion())
+    else:
+        print(generate_bash_completion())
+
+
 def main():
    """Main entry point for hermes CLI."""
    parser = argparse.ArgumentParser(
@@ -3732,6 +4152,7 @@ For more help on a command:
    def cmd_skills(args):
        # Route 'config' action to skills_config module
        if getattr(args, 'skills_action', None) == 'config':
+            _require_tty("skills config")
            from hermes_cli.skills_config import skills_command as skills_config_command
            skills_config_command(args)
        else:
@@ -3774,6 +4195,16 @@ For more help on a command:

    plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins")

+    plugins_enable = plugins_subparsers.add_parser(
+        "enable", help="Enable a disabled plugin"
+    )
+    plugins_enable.add_argument("name", help="Plugin name to enable")
+
+    plugins_disable = plugins_subparsers.add_parser(
+        "disable", help="Disable a plugin without removing it"
+    )
+    plugins_disable.add_argument("name", help="Plugin name to disable")
+
    def cmd_plugins(args):
        from hermes_cli.plugins_cmd import plugins_command
        plugins_command(args)
@@ -3932,6 +4363,7 @@ For more help on a command:
            from hermes_cli.tools_config import tools_disable_enable_command
            tools_disable_enable_command(args)
        else:
+            _require_tty("tools")
            from hermes_cli.tools_config import tools_command
            tools_command(args)

@@ -3941,16 +4373,25 @@ For more help on a command:
    # =========================================================================
    mcp_parser = subparsers.add_parser(
        "mcp",
-        help="Manage MCP server connections",
+        help="Manage MCP servers and run Hermes as an MCP server",
        description=(
-            "Add, remove, list, test, and configure MCP server connections.\n\n"
+            "Manage MCP server connections and run Hermes as an MCP server.\n\n"
            "MCP servers provide additional tools via the Model Context Protocol.\n"
-            "Use 'hermes mcp add' to connect to a new server with interactive\n"
-            "tool discovery. Run 'hermes mcp' with no subcommand to list servers."
+            "Use 'hermes mcp add' to connect to a new server, or\n"
+            "'hermes mcp serve' to expose Hermes conversations over MCP."
        ),
    )
    mcp_sub = mcp_parser.add_subparsers(dest="mcp_action")

+    mcp_serve_p = mcp_sub.add_parser(
+        "serve",
+        help="Run Hermes as an MCP server (expose conversations to other agents)",
+    )
+    mcp_serve_p.add_argument(
+        "-v", "--verbose", action="store_true",
+        help="Enable verbose logging on stderr",
+    )
+
    mcp_add_p = mcp_sub.add_parser("add", help="Add an MCP server (discovery-first install)")
    mcp_add_p.add_argument("name", help="Server name (used as config key)")
    mcp_add_p.add_argument("--url", help="HTTP/SSE endpoint URL")
@@ -4327,7 +4768,75 @@ For more help on a command:
            sys.exit(1)

    acp_parser.set_defaults(func=cmd_acp)
-    
+
+    # =========================================================================
+    # profile command
+    # =========================================================================
+    profile_parser = subparsers.add_parser(
+        "profile",
+        help="Manage profiles — multiple isolated Hermes instances",
+    )
+    profile_subparsers = profile_parser.add_subparsers(dest="profile_action")
+
+    profile_list = profile_subparsers.add_parser("list", help="List all profiles")
+    profile_use = profile_subparsers.add_parser("use", help="Set sticky default profile")
+    profile_use.add_argument("profile_name", help="Profile name (or 'default')")
+
+    profile_create = profile_subparsers.add_parser("create", help="Create a new profile")
+    profile_create.add_argument("profile_name", help="Profile name (lowercase, alphanumeric)")
+    profile_create.add_argument("--clone", action="store_true",
+                                help="Copy config.yaml, .env, SOUL.md from active profile")
+    profile_create.add_argument("--clone-all", action="store_true",
+                                help="Full copy of active profile (all state)")
+    profile_create.add_argument("--clone-from", metavar="SOURCE",
+                                help="Source profile to clone from (default: active)")
+    profile_create.add_argument("--no-alias", action="store_true",
+                                help="Skip wrapper script creation")
+
+    profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile")
+    profile_delete.add_argument("profile_name", help="Profile to delete")
+    profile_delete.add_argument("-y", "--yes", action="store_true",
+                                help="Skip confirmation prompt")
+
+    profile_show = profile_subparsers.add_parser("show", help="Show profile details")
+    profile_show.add_argument("profile_name", help="Profile to show")
+
+    profile_alias = profile_subparsers.add_parser("alias", help="Manage wrapper scripts")
+    profile_alias.add_argument("profile_name", help="Profile name")
+    profile_alias.add_argument("--remove", action="store_true",
+                               help="Remove the wrapper script")
+    profile_alias.add_argument("--name", dest="alias_name", metavar="NAME",
+                               help="Custom alias name (default: profile name)")
+
+    profile_rename = profile_subparsers.add_parser("rename", help="Rename a profile")
+    profile_rename.add_argument("old_name", help="Current profile name")
+    profile_rename.add_argument("new_name", help="New profile name")
+
+    profile_export = profile_subparsers.add_parser("export", help="Export a profile to archive")
+    profile_export.add_argument("profile_name", help="Profile to export")
+    profile_export.add_argument("-o", "--output", default=None,
+                                help="Output file (default: <name>.tar.gz)")
+
+    profile_import = profile_subparsers.add_parser("import", help="Import a profile from archive")
+    profile_import.add_argument("archive", help="Path to .tar.gz archive")
+    profile_import.add_argument("--name", dest="import_name", metavar="NAME",
+                                help="Profile name (default: inferred from archive)")
+
+    profile_parser.set_defaults(func=cmd_profile)
+
+    # =========================================================================
+    # completion command
+    # =========================================================================
+    completion_parser = subparsers.add_parser(
+        "completion",
+        help="Print shell completion script (bash or zsh)",
+    )
+    completion_parser.add_argument(
+        "shell", nargs="?", default="bash", choices=["bash", "zsh"],
+        help="Shell type (default: bash)",
+    )
+    completion_parser.set_defaults(func=cmd_completion)
+
    # =========================================================================
    # Parse and execute
    # =========================================================================
@@ -24,6 +24,7 @@ from hermes_cli.config import (
    get_hermes_home,  # noqa: F401 — used by test mocks
 )
 from hermes_cli.colors import Colors, color
+from hermes_constants import display_hermes_home

 logger = logging.getLogger(__name__)

@@ -244,7 +245,7 @@ def cmd_mcp_add(args):
                    api_key = _prompt("API key / Bearer token", password=True)
                    if api_key:
                        save_env_value(env_key, api_key)
-                        _success(f"Saved to ~/.hermes/.env as {env_key}")
+                        _success(f"Saved to {display_hermes_home()}/.env as {env_key}")

                # Set header with env var interpolation
                if api_key or existing_key:
@@ -332,7 +333,7 @@ def cmd_mcp_add(args):
    _save_mcp_server(name, server_config)

    print()
-    _success(f"Saved '{name}' to ~/.hermes/config.yaml ({tool_count}/{total} tools enabled)")
+    _success(f"Saved '{name}' to {display_hermes_home()}/config.yaml ({tool_count}/{total} tools enabled)")
    _info("Start a new session to use these tools.")


@@ -510,6 +511,10 @@ def _interpolate_value(value: str) -> str:

 def cmd_mcp_configure(args):
    """Reconfigure which tools are enabled for an existing MCP server."""
+    import sys as _sys
+    if not _sys.stdin.isatty():
+        print("Error: 'hermes mcp configure' requires an interactive terminal.", file=_sys.stderr)
+        _sys.exit(1)
    name = args.name
    servers = _get_mcp_servers()

@@ -607,6 +612,11 @@ def mcp_command(args):
    """Main dispatcher for ``hermes mcp`` subcommands."""
    action = getattr(args, "mcp_action", None)

+    if action == "serve":
+        from mcp_serve import run_mcp_server
+        run_mcp_server(verbose=getattr(args, "verbose", False))
+        return
+
    handlers = {
        "add": cmd_mcp_add,
        "remove": cmd_mcp_remove,
@@ -625,6 +635,7 @@ def mcp_command(args):
        # No subcommand — show list
        cmd_mcp_list()
        print(color("  Commands:", Colors.CYAN))
+        _info("hermes mcp serve                              Run as MCP server")
        _info("hermes mcp add <name> --url <endpoint>        Add an MCP server")
        _info("hermes mcp add <name> --command <cmd>         Add a stdio server")
        _info("hermes mcp remove <name>                      Remove a server")
@@ -35,6 +35,8 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
    ("openai/gpt-5.3-codex",            ""),
    ("google/gemini-3-pro-preview",     ""),
    ("google/gemini-3-flash-preview",   ""),
+    ("google/gemini-3.1-pro-preview",     ""),
+    ("google/gemini-3.1-flash-lite-preview",   ""),
    ("qwen/qwen3.5-plus-02-15",         ""),
    ("qwen/qwen3.5-35b-a3b",            ""),
    ("stepfun/step-3.5-flash",          ""),
@@ -62,6 +64,8 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
        "openai/gpt-5.3-codex",
        "google/gemini-3-pro-preview",
        "google/gemini-3-flash-preview",
+        "google/gemini-3.1-pro-preview",
+        "google/gemini-3.1-flash-lite-preview",
        "qwen/qwen3.5-plus-02-15",
        "qwen/qwen3.5-35b-a3b",
        "stepfun/step-3.5-flash",
@@ -68,6 +68,17 @@ def _env_enabled(name: str) -> bool:
    return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}


+def _get_disabled_plugins() -> set:
+    """Read the disabled plugins list from config.yaml."""
+    try:
+        from hermes_cli.config import load_config
+        config = load_config()
+        disabled = config.get("plugins", {}).get("disabled", [])
+        return set(disabled) if isinstance(disabled, list) else set()
+    except Exception:
+        return set()
+
+
 # ---------------------------------------------------------------------------
 # Data classes
 # ---------------------------------------------------------------------------
@@ -141,6 +152,34 @@ class PluginContext:
        self._manager._plugin_tool_names.add(name)
        logger.debug("Plugin %s registered tool: %s", self.manifest.name, name)

+    # -- message injection --------------------------------------------------
+
+    def inject_message(self, content: str, role: str = "user") -> bool:
+        """Inject a message into the active conversation.
+
+        If the agent is idle (waiting for user input), this starts a new turn.
+        If the agent is running, this interrupts and injects the message.
+
+        This enables plugins (e.g. remote control viewers, messaging bridges)
+        to send messages into the conversation from external sources.
+
+        Returns True if the message was queued successfully.
+        """
+        cli = self._manager._cli_ref
+        if cli is None:
+            logger.warning("inject_message: no CLI reference (not available in gateway mode)")
+            return False
+
+        msg = content if role == "user" else f"[{role}] {content}"
+
+        if getattr(cli, "_agent_running", False):
+            # Agent is mid-turn — interrupt with the message
+            cli._interrupt_queue.put(msg)
+        else:
+            # Agent is idle — queue as next input
+            cli._pending_input.put(msg)
+        return True
+
    # -- hook registration --------------------------------------------------

    def register_hook(self, hook_name: str, callback: Callable) -> None:
@@ -173,6 +212,7 @@ class PluginManager:
        self._hooks: Dict[str, List[Callable]] = {}
        self._plugin_tool_names: Set[str] = set()
        self._discovered: bool = False
+        self._cli_ref = None  # Set by CLI after plugin discovery

    # -----------------------------------------------------------------------
    # Public
@@ -199,8 +239,15 @@ class PluginManager:
        # 3. Pip / entry-point plugins
        manifests.extend(self._scan_entry_points())

-        # Load each manifest
+        # Load each manifest (skip user-disabled plugins)
+        disabled = _get_disabled_plugins()
        for manifest in manifests:
+            if manifest.name in disabled:
+                loaded = LoadedPlugin(manifest=manifest, enabled=False)
+                loaded.error = "disabled via config"
+                self._plugins[manifest.name] = loaded
+                logger.debug("Skipping disabled plugin '%s'", manifest.name)
+                continue
            self._load_plugin(manifest)

        if manifests:
@@ -374,6 +374,73 @@ def cmd_remove(name: str) -> None:
    _display_removed(name, plugins_dir)


+def _get_disabled_set() -> set:
+    """Read the disabled plugins set from config.yaml."""
+    try:
+        from hermes_cli.config import load_config
+        config = load_config()
+        disabled = config.get("plugins", {}).get("disabled", [])
+        return set(disabled) if isinstance(disabled, list) else set()
+    except Exception:
+        return set()
+
+
+def _save_disabled_set(disabled: set) -> None:
+    """Write the disabled plugins list to config.yaml."""
+    from hermes_cli.config import load_config, save_config
+    config = load_config()
+    if "plugins" not in config:
+        config["plugins"] = {}
+    config["plugins"]["disabled"] = sorted(disabled)
+    save_config(config)
+
+
+def cmd_enable(name: str) -> None:
+    """Enable a previously disabled plugin."""
+    from rich.console import Console
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    # Verify the plugin exists
+    target = plugins_dir / name
+    if not target.is_dir():
+        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
+        sys.exit(1)
+
+    disabled = _get_disabled_set()
+    if name not in disabled:
+        console.print(f"[dim]Plugin '{name}' is already enabled.[/dim]")
+        return
+
+    disabled.discard(name)
+    _save_disabled_set(disabled)
+    console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] enabled. Takes effect on next session.")
+
+
+def cmd_disable(name: str) -> None:
+    """Disable a plugin without removing it."""
+    from rich.console import Console
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    # Verify the plugin exists
+    target = plugins_dir / name
+    if not target.is_dir():
+        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
+        sys.exit(1)
+
+    disabled = _get_disabled_set()
+    if name in disabled:
+        console.print(f"[dim]Plugin '{name}' is already disabled.[/dim]")
+        return
+
+    disabled.add(name)
+    _save_disabled_set(disabled)
+    console.print(f"[yellow]⊘[/yellow] Plugin [bold]{name}[/bold] disabled. Takes effect on next session.")
+
+
 def cmd_list() -> None:
    """List installed plugins."""
    from rich.console import Console
@@ -393,8 +460,11 @@ def cmd_list() -> None:
        console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
        return

+    disabled = _get_disabled_set()
+
    table = Table(title="Installed Plugins", show_lines=False)
    table.add_column("Name", style="bold")
+    table.add_column("Status")
    table.add_column("Version", style="dim")
    table.add_column("Description")
    table.add_column("Source", style="dim")
@@ -420,11 +490,86 @@ def cmd_list() -> None:
        if (d / ".git").exists():
            source = "git"

-        table.add_row(name, str(version), description, source)
+        is_disabled = name in disabled or d.name in disabled
+        status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]"
+        table.add_row(name, status, str(version), description, source)

    console.print()
    console.print(table)
    console.print()
+    console.print("[dim]Interactive toggle:[/dim] hermes plugins")
+    console.print("[dim]Enable/disable:[/dim] hermes plugins enable/disable <name>")
+
+
+def cmd_toggle() -> None:
+    """Interactive curses checklist to enable/disable installed plugins."""
+    from rich.console import Console
+
+    try:
+        import yaml
+    except ImportError:
+        yaml = None
+
+    console = Console()
+    plugins_dir = _plugins_dir()
+
+    dirs = sorted(d for d in plugins_dir.iterdir() if d.is_dir())
+    if not dirs:
+        console.print("[dim]No plugins installed.[/dim]")
+        console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
+        return
+
+    disabled = _get_disabled_set()
+
+    # Build items list: "name — description" for display
+    names = []
+    labels = []
+    selected = set()
+
+    for i, d in enumerate(dirs):
+        manifest_file = d / "plugin.yaml"
+        name = d.name
+        description = ""
+
+        if manifest_file.exists() and yaml:
+            try:
+                with open(manifest_file) as f:
+                    manifest = yaml.safe_load(f) or {}
+                name = manifest.get("name", d.name)
+                description = manifest.get("description", "")
+            except Exception:
+                pass
+
+        names.append(name)
+        label = f"{name} — {description}" if description else name
+        labels.append(label)
+
+        if name not in disabled and d.name not in disabled:
+            selected.add(i)
+
+    from hermes_cli.curses_ui import curses_checklist
+
+    result = curses_checklist(
+        title="Plugins — toggle enabled/disabled",
+        items=labels,
+        selected=selected,
+    )
+
+    # Compute new disabled set from deselected items
+    new_disabled = set()
+    for i, name in enumerate(names):
+        if i not in result:
+            new_disabled.add(name)
+
+    if new_disabled != disabled:
+        _save_disabled_set(new_disabled)
+        enabled_count = len(names) - len(new_disabled)
+        console.print(
+            f"\n[green]✓[/green] {enabled_count} enabled, {len(new_disabled)} disabled. "
+            f"Takes effect on next session."
+        )
+    else:
+        console.print("\n[dim]No changes.[/dim]")


 def plugins_command(args) -> None:
@@ -437,8 +582,14 @@ def plugins_command(args) -> None:
        cmd_update(args.name)
    elif action in ("remove", "rm", "uninstall"):
        cmd_remove(args.name)
-    elif action in ("list", "ls") or action is None:
+    elif action == "enable":
+        cmd_enable(args.name)
+    elif action == "disable":
+        cmd_disable(args.name)
+    elif action in ("list", "ls"):
        cmd_list()
+    elif action is None:
+        cmd_toggle()
    else:
        from rich.console import Console

@@ -0,0 +1,906 @@
+"""
+Profile management for multiple isolated Hermes instances.
+
+Each profile is a fully independent HERMES_HOME directory with its own
+config.yaml, .env, memory, sessions, skills, gateway, cron, and logs.
+Profiles live under ``~/.hermes/profiles/<name>/`` by default.
+
+The "default" profile is ``~/.hermes`` itself — backward compatible,
+zero migration needed.
+
+Usage::
+
+    hermes profile create coder          # fresh profile + bundled skills
+    hermes profile create coder --clone  # also copy config, .env, SOUL.md
+    hermes profile create coder --clone-all  # full copy of source profile
+    coder chat                           # use via wrapper alias
+    hermes -p coder chat                 # or via flag
+    hermes profile use coder             # set as sticky default
+    hermes profile delete coder          # remove profile + alias + service
+"""
+
+import json
+import os
+import re
+import shutil
+import stat
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+_PROFILE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+# Directories bootstrapped inside every new profile
+_PROFILE_DIRS = [
+    "memories",
+    "sessions",
+    "skills",
+    "skins",
+    "logs",
+    "plans",
+    "workspace",
+    "cron",
+]
+
+# Files copied during --clone (if they exist in the source)
+_CLONE_CONFIG_FILES = [
+    "config.yaml",
+    ".env",
+    "SOUL.md",
+]
+
+# Runtime files stripped after --clone-all (shouldn't carry over)
+_CLONE_ALL_STRIP = [
+    "gateway.pid",
+    "gateway_state.json",
+    "processes.json",
+]
+
+# Names that cannot be used as profile aliases
+_RESERVED_NAMES = frozenset({
+    "hermes", "default", "test", "tmp", "root", "sudo",
+})
+
+# Hermes subcommands that cannot be used as profile names/aliases
+_HERMES_SUBCOMMANDS = frozenset({
+    "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
+    "status", "cron", "doctor", "config", "pairing", "skills", "tools",
+    "mcp", "sessions", "insights", "version", "update", "uninstall",
+    "profile", "plugins", "honcho", "acp",
+})
+
+
+# ---------------------------------------------------------------------------
+# Path helpers
+# ---------------------------------------------------------------------------
+
+def _get_profiles_root() -> Path:
+    """Return the directory where named profiles are stored.
+
+    Always ``~/.hermes/profiles/`` — anchored to the user's home,
+    NOT to the current HERMES_HOME (which may itself be a profile).
+    This ensures ``coder profile list`` can see all profiles.
+    """
+    return Path.home() / ".hermes" / "profiles"
+
+
+def _get_default_hermes_home() -> Path:
+    """Return the default (pre-profile) HERMES_HOME path."""
+    return Path.home() / ".hermes"
+
+
+def _get_active_profile_path() -> Path:
+    """Return the path to the sticky active_profile file."""
+    return _get_default_hermes_home() / "active_profile"
+
+
+def _get_wrapper_dir() -> Path:
+    """Return the directory for wrapper scripts."""
+    return Path.home() / ".local" / "bin"
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+def validate_profile_name(name: str) -> None:
+    """Raise ``ValueError`` if *name* is not a valid profile identifier."""
+    if name == "default":
+        return  # special alias for ~/.hermes
+    if not _PROFILE_ID_RE.match(name):
+        raise ValueError(
+            f"Invalid profile name {name!r}. Must match "
+            f"[a-z0-9][a-z0-9_-]{{0,63}}"
+        )
+
+
+def get_profile_dir(name: str) -> Path:
+    """Resolve a profile name to its HERMES_HOME directory."""
+    if name == "default":
+        return _get_default_hermes_home()
+    return _get_profiles_root() / name
+
+
+def profile_exists(name: str) -> bool:
+    """Check whether a profile directory exists."""
+    if name == "default":
+        return True
+    return get_profile_dir(name).is_dir()
+
+
+# ---------------------------------------------------------------------------
+# Alias / wrapper script management
+# ---------------------------------------------------------------------------
+
+def check_alias_collision(name: str) -> Optional[str]:
+    """Return a human-readable collision message, or None if the name is safe.
+
+    Checks: reserved names, hermes subcommands, existing binaries in PATH.
+    """
+    if name in _RESERVED_NAMES:
+        return f"'{name}' is a reserved name"
+    if name in _HERMES_SUBCOMMANDS:
+        return f"'{name}' conflicts with a hermes subcommand"
+
+    # Check existing commands in PATH
+    wrapper_dir = _get_wrapper_dir()
+    try:
+        result = subprocess.run(
+            ["which", name], capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0:
+            existing_path = result.stdout.strip()
+            # Allow overwriting our own wrappers
+            if existing_path == str(wrapper_dir / name):
+                try:
+                    content = (wrapper_dir / name).read_text()
+                    if "hermes -p" in content:
+                        return None  # it's our wrapper, safe to overwrite
+                except Exception:
+                    pass
+            return f"'{name}' conflicts with an existing command ({existing_path})"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    return None  # safe
+
+
+def _is_wrapper_dir_in_path() -> bool:
+    """Check if ~/.local/bin is in PATH."""
+    wrapper_dir = str(_get_wrapper_dir())
+    return wrapper_dir in os.environ.get("PATH", "").split(os.pathsep)
+
+
+def create_wrapper_script(name: str) -> Optional[Path]:
+    """Create a shell wrapper script at ~/.local/bin/<name>.
+
+    Returns the path to the created wrapper, or None if creation failed.
+    """
+    wrapper_dir = _get_wrapper_dir()
+    try:
+        wrapper_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as e:
+        print(f"⚠ Could not create {wrapper_dir}: {e}")
+        return None
+
+    wrapper_path = wrapper_dir / name
+    try:
+        wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
+        wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+        return wrapper_path
+    except OSError as e:
+        print(f"⚠ Could not create wrapper at {wrapper_path}: {e}")
+        return None
+
+
+def remove_wrapper_script(name: str) -> bool:
+    """Remove the wrapper script for a profile. Returns True if removed."""
+    wrapper_path = _get_wrapper_dir() / name
+    if wrapper_path.exists():
+        try:
+            # Verify it's our wrapper before removing
+            content = wrapper_path.read_text()
+            if "hermes -p" in content:
+                wrapper_path.unlink()
+                return True
+        except Exception:
+            pass
+    return False
+
+
+# ---------------------------------------------------------------------------
+# ProfileInfo
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ProfileInfo:
+    """Summary information about a profile."""
+    name: str
+    path: Path
+    is_default: bool
+    gateway_running: bool
+    model: Optional[str] = None
+    provider: Optional[str] = None
+    has_env: bool = False
+    skill_count: int = 0
+    alias_path: Optional[Path] = None
+
+
+def _read_config_model(profile_dir: Path) -> tuple:
+    """Read model/provider from a profile's config.yaml. Returns (model, provider)."""
+    config_path = profile_dir / "config.yaml"
+    if not config_path.exists():
+        return None, None
+    try:
+        import yaml
+        with open(config_path, "r") as f:
+            cfg = yaml.safe_load(f) or {}
+        model_cfg = cfg.get("model", {})
+        if isinstance(model_cfg, str):
+            return model_cfg, None
+        if isinstance(model_cfg, dict):
+            return model_cfg.get("model"), model_cfg.get("provider")
+        return None, None
+    except Exception:
+        return None, None
+
+
+def _check_gateway_running(profile_dir: Path) -> bool:
+    """Check if a gateway is running for a given profile directory."""
+    pid_file = profile_dir / "gateway.pid"
+    if not pid_file.exists():
+        return False
+    try:
+        raw = pid_file.read_text().strip()
+        if not raw:
+            return False
+        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
+        pid = int(data["pid"])
+        os.kill(pid, 0)  # existence check
+        return True
+    except (json.JSONDecodeError, KeyError, ValueError, TypeError,
+            ProcessLookupError, PermissionError, OSError):
+        return False
+
+
+def _count_skills(profile_dir: Path) -> int:
+    """Count installed skills in a profile."""
+    skills_dir = profile_dir / "skills"
+    if not skills_dir.is_dir():
+        return 0
+    count = 0
+    for md in skills_dir.rglob("SKILL.md"):
+        if "/.hub/" not in str(md) and "/.git/" not in str(md):
+            count += 1
+    return count
+
+
+# ---------------------------------------------------------------------------
+# CRUD operations
+# ---------------------------------------------------------------------------
+
+def list_profiles() -> List[ProfileInfo]:
+    """Return info for all profiles, including the default."""
+    profiles = []
+    wrapper_dir = _get_wrapper_dir()
+
+    # Default profile
+    default_home = _get_default_hermes_home()
+    if default_home.is_dir():
+        model, provider = _read_config_model(default_home)
+        profiles.append(ProfileInfo(
+            name="default",
+            path=default_home,
+            is_default=True,
+            gateway_running=_check_gateway_running(default_home),
+            model=model,
+            provider=provider,
+            has_env=(default_home / ".env").exists(),
+            skill_count=_count_skills(default_home),
+        ))
+
+    # Named profiles
+    profiles_root = _get_profiles_root()
+    if profiles_root.is_dir():
+        for entry in sorted(profiles_root.iterdir()):
+            if not entry.is_dir():
+                continue
+            name = entry.name
+            if not _PROFILE_ID_RE.match(name):
+                continue
+            model, provider = _read_config_model(entry)
+            alias_path = wrapper_dir / name
+            profiles.append(ProfileInfo(
+                name=name,
+                path=entry,
+                is_default=False,
+                gateway_running=_check_gateway_running(entry),
+                model=model,
+                provider=provider,
+                has_env=(entry / ".env").exists(),
+                skill_count=_count_skills(entry),
+                alias_path=alias_path if alias_path.exists() else None,
+            ))
+
+    return profiles
+
+
+def create_profile(
+    name: str,
+    clone_from: Optional[str] = None,
+    clone_all: bool = False,
+    clone_config: bool = False,
+    no_alias: bool = False,
+) -> Path:
+    """Create a new profile directory.
+
+    Parameters
+    ----------
+    name:
+        Profile identifier (lowercase, alphanumeric, hyphens, underscores).
+    clone_from:
+        Source profile to clone from. If ``None`` and clone_config/clone_all
+        is True, defaults to the currently active profile.
+    clone_all:
+        If True, do a full copytree of the source (all state).
+    clone_config:
+        If True, copy only config files (config.yaml, .env, SOUL.md).
+    no_alias:
+        If True, skip wrapper script creation.
+
+    Returns
+    -------
+    Path
+        The newly created profile directory.
+    """
+    validate_profile_name(name)
+
+    if name == "default":
+        raise ValueError(
+            "Cannot create a profile named 'default' — it is the built-in profile (~/.hermes)."
+        )
+
+    profile_dir = get_profile_dir(name)
+    if profile_dir.exists():
+        raise FileExistsError(f"Profile '{name}' already exists at {profile_dir}")
+
+    # Resolve clone source
+    source_dir = None
+    if clone_from is not None or clone_all or clone_config:
+        if clone_from is None:
+            # Default: clone from active profile
+            from hermes_constants import get_hermes_home
+            source_dir = get_hermes_home()
+        else:
+            validate_profile_name(clone_from)
+            source_dir = get_profile_dir(clone_from)
+        if not source_dir.is_dir():
+            raise FileNotFoundError(
+                f"Source profile '{clone_from or 'active'}' does not exist at {source_dir}"
+            )
+
+    if clone_all and source_dir:
+        # Full copy of source profile
+        shutil.copytree(source_dir, profile_dir)
+        # Strip runtime files
+        for stale in _CLONE_ALL_STRIP:
+            (profile_dir / stale).unlink(missing_ok=True)
+    else:
+        # Bootstrap directory structure
+        profile_dir.mkdir(parents=True, exist_ok=True)
+        for subdir in _PROFILE_DIRS:
+            (profile_dir / subdir).mkdir(parents=True, exist_ok=True)
+
+        # Clone config files from source
+        if source_dir is not None:
+            for filename in _CLONE_CONFIG_FILES:
+                src = source_dir / filename
+                if src.exists():
+                    shutil.copy2(src, profile_dir / filename)
+
+    return profile_dir
+
+
+def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict]:
+    """Seed bundled skills into a profile via subprocess.
+
+    Uses subprocess because sync_skills() caches HERMES_HOME at module level.
+    Returns the sync result dict, or None on failure.
+    """
+    project_root = Path(__file__).parent.parent.resolve()
+    try:
+        result = subprocess.run(
+            [sys.executable, "-c",
+             "import json; from tools.skills_sync import sync_skills; "
+             "r = sync_skills(quiet=True); print(json.dumps(r))"],
+            env={**os.environ, "HERMES_HOME": str(profile_dir)},
+            cwd=str(project_root),
+            capture_output=True, text=True, timeout=60,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return json.loads(result.stdout.strip())
+        if not quiet:
+            print(f"⚠ Skill seeding returned exit code {result.returncode}")
+            if result.stderr.strip():
+                print(f"  {result.stderr.strip()[:200]}")
+        return None
+    except subprocess.TimeoutExpired:
+        if not quiet:
+            print("⚠ Skill seeding timed out (60s)")
+        return None
+    except Exception as e:
+        if not quiet:
+            print(f"⚠ Skill seeding failed: {e}")
+        return None
+
+
+def delete_profile(name: str, yes: bool = False) -> Path:
+    """Delete a profile, its wrapper script, and its gateway service.
+
+    Stops the gateway if running. Disables systemd/launchd service first
+    to prevent auto-restart.
+
+    Returns the path that was removed.
+    """
+    validate_profile_name(name)
+
+    if name == "default":
+        raise ValueError(
+            "Cannot delete the default profile (~/.hermes).\n"
+            "To remove everything, use: hermes uninstall"
+        )
+
+    profile_dir = get_profile_dir(name)
+    if not profile_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+
+    # Show what will be deleted
+    model, provider = _read_config_model(profile_dir)
+    gw_running = _check_gateway_running(profile_dir)
+    skill_count = _count_skills(profile_dir)
+
+    print(f"\nProfile: {name}")
+    print(f"Path:    {profile_dir}")
+    if model:
+        print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
+    if skill_count:
+        print(f"Skills:  {skill_count}")
+
+    items = [
+        "All config, API keys, memories, sessions, skills, cron jobs",
+    ]
+
+    # Check for service
+    from hermes_cli.gateway import _profile_suffix, get_service_name
+    wrapper_path = _get_wrapper_dir() / name
+    has_wrapper = wrapper_path.exists()
+    if has_wrapper:
+        items.append(f"Command alias ({wrapper_path})")
+
+    print(f"\nThis will permanently delete:")
+    for item in items:
+        print(f"  • {item}")
+    if gw_running:
+        print(f"  ⚠ Gateway is running — it will be stopped.")
+
+    # Confirmation
+    if not yes:
+        print()
+        try:
+            confirm = input(f"Type '{name}' to confirm: ").strip()
+        except (KeyboardInterrupt, EOFError):
+            print("\nCancelled.")
+            return profile_dir
+        if confirm != name:
+            print("Cancelled.")
+            return profile_dir
+
+    # 1. Disable service (prevents auto-restart)
+    _cleanup_gateway_service(name, profile_dir)
+
+    # 2. Stop running gateway
+    if gw_running:
+        _stop_gateway_process(profile_dir)
+
+    # 3. Remove wrapper script
+    if has_wrapper:
+        if remove_wrapper_script(name):
+            print(f"✓ Removed {wrapper_path}")
+
+    # 4. Remove profile directory
+    try:
+        shutil.rmtree(profile_dir)
+        print(f"✓ Removed {profile_dir}")
+    except Exception as e:
+        print(f"⚠ Could not remove {profile_dir}: {e}")
+
+    # 5. Clear active_profile if it pointed to this profile
+    try:
+        active = get_active_profile()
+        if active == name:
+            set_active_profile("default")
+            print("✓ Active profile reset to default")
+    except Exception:
+        pass
+
+    print(f"\nProfile '{name}' deleted.")
+    return profile_dir
+
+
+def _cleanup_gateway_service(name: str, profile_dir: Path) -> None:
+    """Disable and remove systemd/launchd service for a profile."""
+    import platform as _platform
+
+    # Derive service name for this profile
+    # Temporarily set HERMES_HOME so _profile_suffix resolves correctly
+    old_home = os.environ.get("HERMES_HOME")
+    try:
+        os.environ["HERMES_HOME"] = str(profile_dir)
+        from hermes_cli.gateway import get_service_name, get_launchd_plist_path
+
+        if _platform.system() == "Linux":
+            svc_name = get_service_name()
+            svc_file = Path.home() / ".config" / "systemd" / "user" / f"{svc_name}.service"
+            if svc_file.exists():
+                subprocess.run(
+                    ["systemctl", "--user", "disable", svc_name],
+                    capture_output=True, check=False, timeout=10,
+                )
+                subprocess.run(
+                    ["systemctl", "--user", "stop", svc_name],
+                    capture_output=True, check=False, timeout=10,
+                )
+                svc_file.unlink(missing_ok=True)
+                subprocess.run(
+                    ["systemctl", "--user", "daemon-reload"],
+                    capture_output=True, check=False, timeout=10,
+                )
+                print(f"✓ Service {svc_name} removed")
+
+        elif _platform.system() == "Darwin":
+            plist_path = get_launchd_plist_path()
+            if plist_path.exists():
+                subprocess.run(
+                    ["launchctl", "unload", str(plist_path)],
+                    capture_output=True, check=False, timeout=10,
+                )
+                plist_path.unlink(missing_ok=True)
+                print(f"✓ Launchd service removed")
+    except Exception as e:
+        print(f"⚠ Service cleanup: {e}")
+    finally:
+        if old_home is not None:
+            os.environ["HERMES_HOME"] = old_home
+        elif "HERMES_HOME" in os.environ:
+            del os.environ["HERMES_HOME"]
+
+
+def _stop_gateway_process(profile_dir: Path) -> None:
+    """Stop a running gateway process via its PID file."""
+    import signal as _signal
+    import time as _time
+
+    pid_file = profile_dir / "gateway.pid"
+    if not pid_file.exists():
+        return
+
+    try:
+        raw = pid_file.read_text().strip()
+        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
+        pid = int(data["pid"])
+        os.kill(pid, _signal.SIGTERM)
+        # Wait up to 10s for graceful shutdown
+        for _ in range(20):
+            _time.sleep(0.5)
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                print(f"✓ Gateway stopped (PID {pid})")
+                return
+        # Force kill
+        try:
+            os.kill(pid, _signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        print(f"✓ Gateway force-stopped (PID {pid})")
+    except (ProcessLookupError, PermissionError):
+        print("✓ Gateway already stopped")
+    except Exception as e:
+        print(f"⚠ Could not stop gateway: {e}")
+
+
+# ---------------------------------------------------------------------------
+# Active profile (sticky default)
+# ---------------------------------------------------------------------------
+
+def get_active_profile() -> str:
+    """Read the sticky active profile name.
+
+    Returns ``"default"`` if no active_profile file exists or it's empty.
+    """
+    path = _get_active_profile_path()
+    try:
+        name = path.read_text().strip()
+        if not name:
+            return "default"
+        return name
+    except (FileNotFoundError, UnicodeDecodeError, OSError):
+        return "default"
+
+
+def set_active_profile(name: str) -> None:
+    """Set the sticky active profile.
+
+    Writes to ``~/.hermes/active_profile``. Use ``"default"`` to clear.
+    """
+    validate_profile_name(name)
+    if name != "default" and not profile_exists(name):
+        raise FileNotFoundError(
+            f"Profile '{name}' does not exist. "
+            f"Create it with: hermes profile create {name}"
+        )
+
+    path = _get_active_profile_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if name == "default":
+        # Remove the file to indicate default
+        path.unlink(missing_ok=True)
+    else:
+        # Atomic write
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(name + "\n")
+        tmp.replace(path)
+
+
+def get_active_profile_name() -> str:
+    """Infer the current profile name from HERMES_HOME.
+
+    Returns ``"default"`` if HERMES_HOME is not set or points to ``~/.hermes``.
+    Returns the profile name if HERMES_HOME points into ``~/.hermes/profiles/<name>``.
+    Returns ``"custom"`` if HERMES_HOME is set to an unrecognized path.
+    """
+    from hermes_constants import get_hermes_home
+    hermes_home = get_hermes_home()
+    resolved = hermes_home.resolve()
+
+    default_resolved = _get_default_hermes_home().resolve()
+    if resolved == default_resolved:
+        return "default"
+
+    profiles_root = _get_profiles_root().resolve()
+    try:
+        rel = resolved.relative_to(profiles_root)
+        parts = rel.parts
+        if len(parts) == 1 and _PROFILE_ID_RE.match(parts[0]):
+            return parts[0]
+    except ValueError:
+        pass
+
+    return "custom"
+
+
+# ---------------------------------------------------------------------------
+# Export / Import
+# ---------------------------------------------------------------------------
+
+def export_profile(name: str, output_path: str) -> Path:
+    """Export a profile to a tar.gz archive.
+
+    Returns the output file path.
+    """
+    validate_profile_name(name)
+    profile_dir = get_profile_dir(name)
+    if not profile_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+
+    output = Path(output_path)
+    # shutil.make_archive wants the base name without extension
+    base = str(output).removesuffix(".tar.gz").removesuffix(".tgz")
+    result = shutil.make_archive(base, "gztar", str(profile_dir.parent), name)
+    return Path(result)
+
+
+def import_profile(archive_path: str, name: Optional[str] = None) -> Path:
+    """Import a profile from a tar.gz archive.
+
+    If *name* is not given, infers it from the archive's top-level directory.
+    Returns the imported profile directory.
+    """
+    import tarfile
+
+    archive = Path(archive_path)
+    if not archive.exists():
+        raise FileNotFoundError(f"Archive not found: {archive}")
+
+    # Peek at the archive to find the top-level directory name
+    with tarfile.open(archive, "r:gz") as tf:
+        top_dirs = {m.name.split("/")[0] for m in tf.getmembers() if "/" in m.name}
+        if not top_dirs:
+            top_dirs = {m.name for m in tf.getmembers() if m.isdir()}
+
+    inferred_name = name or (top_dirs.pop() if len(top_dirs) == 1 else None)
+    if not inferred_name:
+        raise ValueError(
+            "Cannot determine profile name from archive. "
+            "Specify it explicitly: hermes profile import <archive> --name <name>"
+        )
+
+    validate_profile_name(inferred_name)
+    profile_dir = get_profile_dir(inferred_name)
+    if profile_dir.exists():
+        raise FileExistsError(f"Profile '{inferred_name}' already exists at {profile_dir}")
+
+    profiles_root = _get_profiles_root()
+    profiles_root.mkdir(parents=True, exist_ok=True)
+
+    shutil.unpack_archive(str(archive), str(profiles_root))
+
+    # If the archive extracted under a different name, rename
+    extracted = profiles_root / (top_dirs.pop() if top_dirs else inferred_name)
+    if extracted != profile_dir and extracted.exists():
+        extracted.rename(profile_dir)
+
+    return profile_dir
+
+
+# ---------------------------------------------------------------------------
+# Rename
+# ---------------------------------------------------------------------------
+
+def rename_profile(old_name: str, new_name: str) -> Path:
+    """Rename a profile: directory, wrapper script, service, active_profile.
+
+    Returns the new profile directory.
+    """
+    validate_profile_name(old_name)
+    validate_profile_name(new_name)
+
+    if old_name == "default":
+        raise ValueError("Cannot rename the default profile.")
+    if new_name == "default":
+        raise ValueError("Cannot rename to 'default' — it is reserved.")
+
+    old_dir = get_profile_dir(old_name)
+    new_dir = get_profile_dir(new_name)
+
+    if not old_dir.is_dir():
+        raise FileNotFoundError(f"Profile '{old_name}' does not exist.")
+    if new_dir.exists():
+        raise FileExistsError(f"Profile '{new_name}' already exists.")
+
+    # 1. Stop gateway if running
+    if _check_gateway_running(old_dir):
+        _cleanup_gateway_service(old_name, old_dir)
+        _stop_gateway_process(old_dir)
+
+    # 2. Rename directory
+    old_dir.rename(new_dir)
+    print(f"✓ Renamed {old_dir.name} → {new_dir.name}")
+
+    # 3. Update wrapper script
+    remove_wrapper_script(old_name)
+    collision = check_alias_collision(new_name)
+    if not collision:
+        create_wrapper_script(new_name)
+        print(f"✓ Alias updated: {new_name}")
+    else:
+        print(f"⚠ Cannot create alias '{new_name}' — {collision}")
+
+    # 4. Update active_profile if it pointed to old name
+    try:
+        if get_active_profile() == old_name:
+            set_active_profile(new_name)
+            print(f"✓ Active profile updated: {new_name}")
+    except Exception:
+        pass
+
+    return new_dir
+
+
+# ---------------------------------------------------------------------------
+# Tab completion
+# ---------------------------------------------------------------------------
+
+def generate_bash_completion() -> str:
+    """Generate a bash completion script for hermes profile names."""
+    return '''# Hermes Agent profile completion
+# Add to ~/.bashrc: eval "$(hermes completion bash)"
+
+_hermes_profiles() {
+    local profiles_dir="$HOME/.hermes/profiles"
+    local profiles="default"
+    if [ -d "$profiles_dir" ]; then
+        profiles="$profiles $(ls "$profiles_dir" 2>/dev/null)"
+    fi
+    echo "$profiles"
+}
+
+_hermes_completion() {
+    local cur prev
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+    # Complete profile names after -p / --profile
+    if [[ "$prev" == "-p" || "$prev" == "--profile" ]]; then
+        COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
+        return
+    fi
+
+    # Complete profile subcommands
+    if [[ "${COMP_WORDS[1]}" == "profile" ]]; then
+        case "$prev" in
+            profile)
+                COMPREPLY=($(compgen -W "list use create delete show alias rename export import" -- "$cur"))
+                return
+                ;;
+            use|delete|show|alias|rename|export)
+                COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
+                return
+                ;;
+        esac
+    fi
+
+    # Top-level subcommands
+    if [[ "$COMP_CWORD" == 1 ]]; then
+        local commands="chat model gateway setup status cron doctor config skills tools mcp sessions profile update version"
+        COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    fi
+}
+
+complete -F _hermes_completion hermes
+'''
+
+
+def generate_zsh_completion() -> str:
+    """Generate a zsh completion script for hermes profile names."""
+    return '''#compdef hermes
+# Hermes Agent profile completion
+# Add to ~/.zshrc: eval "$(hermes completion zsh)"
+
+_hermes() {
+    local -a profiles
+    profiles=(default)
+    if [[ -d "$HOME/.hermes/profiles" ]]; then
+        profiles+=("${(@f)$(ls $HOME/.hermes/profiles 2>/dev/null)}")
+    fi
+
+    _arguments \\
+        '-p[Profile name]:profile:($profiles)' \\
+        '--profile[Profile name]:profile:($profiles)' \\
+        '1:command:(chat model gateway setup status cron doctor config skills tools mcp sessions profile update version)' \\
+        '*::arg:->args'
+
+    case $words[1] in
+        profile)
+            _arguments '1:action:(list use create delete show alias rename export import)' \\
+                        '2:profile:($profiles)'
+            ;;
+    esac
+}
+
+_hermes "$@"
+'''
+
+
+# ---------------------------------------------------------------------------
+# Profile env resolution (called from _apply_profile_override)
+# ---------------------------------------------------------------------------
+
+def resolve_profile_env(profile_name: str) -> str:
+    """Resolve a profile name to a HERMES_HOME path string.
+
+    Called early in the CLI entry point, before any hermes modules
+    are imported, to set the HERMES_HOME environment variable.
+    """
+    validate_profile_name(profile_name)
+    profile_dir = get_profile_dir(profile_name)
+
+    if profile_name != "default" and not profile_dir.is_dir():
+        raise FileNotFoundError(
+            f"Profile '{profile_name}' does not exist. "
+            f"Create it with: hermes profile create {profile_name}"
+        )
+
+    return str(profile_dir)
@@ -289,6 +289,7 @@ from hermes_cli.config import (
    get_env_value,
    ensure_hermes_home,
 )
+# display_hermes_home imported lazily at call sites (stale-module safety during hermes update)

 from hermes_cli.colors import Colors, color

@@ -683,7 +684,8 @@ def _print_setup_summary(config: dict, hermes_home):
        print_warning(
            "Some tools are disabled. Run 'hermes setup tools' to configure them,"
        )
-        print_warning("or edit ~/.hermes/.env directly to add the missing API keys.")
+        from hermes_constants import display_hermes_home as _dhh
+        print_warning(f"or edit {_dhh()}/.env directly to add the missing API keys.")
        print()

    # Done banner
@@ -706,7 +708,8 @@ def _print_setup_summary(config: dict, hermes_home):
    print()

    # Show file locations prominently
-    print(color("📁 All your files are in ~/.hermes/:", Colors.CYAN, Colors.BOLD))
+    from hermes_constants import display_hermes_home as _dhh
+    print(color(f"📁 All your files are in {_dhh()}/:", Colors.CYAN, Colors.BOLD))
    print()
    print(f"   {color('Settings:', Colors.YELLOW)}  {get_config_path()}")
    print(f"   {color('API Keys:', Colors.YELLOW)}  {get_env_path()}")
@@ -999,10 +1002,9 @@ def setup_model_provider(config: dict):
                    min_key_ttl_seconds=5 * 60,
                    timeout_seconds=15.0,
                )
-                nous_models = fetch_nous_models(
-                    inference_base_url=creds.get("base_url", ""),
-                    api_key=creds.get("api_key", ""),
-                )
+                # Use curated model list instead of full /models dump
+                from hermes_cli.models import _PROVIDER_MODELS
+                nous_models = _PROVIDER_MODELS.get("nous", [])
            except Exception as e:
                logger.debug("Could not fetch Nous models after login: %s", e)

@@ -2707,10 +2709,38 @@ def setup_gateway(config: dict):
        if token or get_env_value("MATRIX_PASSWORD"):
            # E2EE
            print()
-            if prompt_yes_no("Enable end-to-end encryption (E2EE)?", False):
+            want_e2ee = prompt_yes_no("Enable end-to-end encryption (E2EE)?", False)
+            if want_e2ee:
                save_env_value("MATRIX_ENCRYPTION", "true")
                print_success("E2EE enabled")
-                print_info("   Requires: pip install 'matrix-nio[e2e]'")
+
+            # Auto-install matrix-nio
+            matrix_pkg = "matrix-nio[e2e]" if want_e2ee else "matrix-nio"
+            try:
+                __import__("nio")
+            except ImportError:
+                print_info(f"Installing {matrix_pkg}...")
+                import subprocess
+
+                uv_bin = shutil.which("uv")
+                if uv_bin:
+                    result = subprocess.run(
+                        [uv_bin, "pip", "install", "--python", sys.executable, matrix_pkg],
+                        capture_output=True,
+                        text=True,
+                    )
+                else:
+                    result = subprocess.run(
+                        [sys.executable, "-m", "pip", "install", matrix_pkg],
+                        capture_output=True,
+                        text=True,
+                    )
+                if result.returncode == 0:
+                    print_success(f"{matrix_pkg} installed")
+                else:
+                    print_warning(f"Install failed — run manually: pip install '{matrix_pkg}'")
+                    if result.stderr:
+                        print_info(f"  Error: {result.stderr.strip().splitlines()[-1]}")

            # Allowed users
            print()
@@ -2837,7 +2867,8 @@ def setup_gateway(config: dict):
        save_env_value("WEBHOOK_ENABLED", "true")
        print()
        print_success("Webhooks enabled! Next steps:")
-        print_info("   1. Define webhook routes in ~/.hermes/config.yaml")
+        from hermes_constants import display_hermes_home as _dhh
+        print_info(f"   1. Define webhook routes in {_dhh()}/config.yaml")
        print_info("   2. Point your service (GitHub, GitLab, etc.) at:")
        print_info("      http://your-server:8644/webhooks/<route-name>")
        print()
@@ -28,6 +28,8 @@ PLATFORMS = {
    "mattermost": "💬 Mattermost",
    "matrix":   "💬 Matrix",
    "dingtalk": "💬 DingTalk",
+    "feishu": "🪽 Feishu",
+    "wecom": "💬 WeCom",
 }

 # ─── Config Helpers ───────────────────────────────────────────────────────────
@@ -21,6 +21,7 @@ from rich.table import Table

 # Lazy imports to avoid circular dependencies and slow startup.
 # tools.skills_hub and tools.skills_guard are imported inside functions.
+from hermes_constants import display_hermes_home

 _console = Console()

@@ -353,7 +354,14 @@ def do_install(identifier: str, category: str = "", force: bool = False,
    extra_metadata.update(getattr(bundle, "metadata", {}) or {})

    # Quarantine the bundle
-    q_path = quarantine_bundle(bundle)
+    try:
+        q_path = quarantine_bundle(bundle)
+    except ValueError as exc:
+        c.print(f"[bold red]Installation blocked:[/] {exc}\n")
+        from tools.skills_hub import append_audit_log
+        append_audit_log("BLOCKED", bundle.name, bundle.source,
+                         bundle.trust_level, "invalid_path", str(exc))
+        return
    c.print(f"[dim]Quarantined to {q_path.relative_to(q_path.parent.parent.parent)}[/]")

    # Scan
@@ -388,7 +396,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                "[bold bright_cyan]This is an official optional skill maintained by Nous Research.[/]\n\n"
                "It ships with hermes-agent but is not activated by default.\n"
                "Installing will copy it to your skills directory where the agent can use it.\n\n"
-                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                title="Official Skill",
                border_style="bright_cyan",
            ))
@@ -398,7 +406,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                "External skills can contain instructions that influence agent behavior,\n"
                "shell commands, and scripts. Even after automated scanning, you should\n"
                "review the installed files before use.\n\n"
-                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                title="Disclaimer",
                border_style="yellow",
            ))
@@ -413,7 +421,15 @@ def do_install(identifier: str, category: str = "", force: bool = False,
            return

    # Install
-    install_dir = install_from_quarantine(q_path, bundle.name, category, bundle, result)
+    try:
+        install_dir = install_from_quarantine(q_path, bundle.name, category, bundle, result)
+    except ValueError as exc:
+        c.print(f"[bold red]Installation blocked:[/] {exc}\n")
+        shutil.rmtree(q_path, ignore_errors=True)
+        from tools.skills_hub import append_audit_log
+        append_audit_log("BLOCKED", bundle.name, bundle.source,
+                         bundle.trust_level, "invalid_path", str(exc))
+        return
    from tools.skills_hub import SKILLS_DIR
    c.print(f"[bold green]Installed:[/] {install_dir.relative_to(SKILLS_DIR)}")
    c.print(f"[dim]Files: {', '.join(bundle.files.keys())}[/]\n")
@@ -744,7 +760,7 @@ def do_publish(skill_path: str, target: str = "github", repo: str = "",
        auth = GitHubAuth()
        if not auth.is_authenticated():
            c.print("[bold red]Error:[/] GitHub authentication required.\n"
-                    "Set GITHUB_TOKEN in ~/.hermes/.env or run 'gh auth login'.\n")
+                    f"Set GITHUB_TOKEN in {display_hermes_home()}/.env or run 'gh auth login'.\n")
            return

        c.print(f"[bold]Publishing '{name}' to {repo}...[/]")
@@ -254,6 +254,9 @@ def show_status(args):
        "Slack": ("SLACK_BOT_TOKEN", None),
        "Email": ("EMAIL_ADDRESS", "EMAIL_HOME_ADDRESS"),
        "SMS": ("TWILIO_ACCOUNT_SID", "SMS_HOME_CHANNEL"),
+        "DingTalk": ("DINGTALK_CLIENT_ID", None),
+        "Feishu": ("FEISHU_APP_ID", "FEISHU_HOME_CHANNEL"),
+        "WeCom": ("WECOM_BOT_ID", "WECOM_HOME_CHANNEL"),
    }
    
    for name, (token_var, home_var) in platforms.items():
@@ -9,6 +9,8 @@ Saves per-platform tool configuration to ~/.hermes/config.yaml under
 the `platform_toolsets` key.
 """

+import json as _json
+import logging
 import sys
 from pathlib import Path
 from typing import Dict, List, Optional, Set
@@ -19,6 +21,8 @@ from hermes_cli.config import (
 )
 from hermes_cli.colors import Colors, color

+logger = logging.getLogger(__name__)
+
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()


@@ -136,7 +140,9 @@ PLATFORMS = {
    "homeassistant": {"label": "🏠 Home Assistant", "default_toolset": "hermes-homeassistant"},
    "email":    {"label": "📧 Email",      "default_toolset": "hermes-email"},
    "matrix":   {"label": "💬 Matrix",     "default_toolset": "hermes-matrix"},
-    "dingtalk": {"label": "💬 DingTalk",   "default_toolset": "hermes-dingtalk"},
+ "dingtalk": {"label": "💬 DingTalk", "default_toolset": "hermes-dingtalk"},
+    "feishu": {"label": "🪽 Feishu", "default_toolset": "hermes-feishu"},
+    "wecom": {"label": "💬 WeCom", "default_toolset": "hermes-wecom"},
    "api_server": {"label": "🌐 API Server", "default_toolset": "hermes-api-server"},
    "mattermost": {"label": "💬 Mattermost", "default_toolset": "hermes-mattermost"},
 }
@@ -326,7 +332,8 @@ def _run_post_setup(post_setup_key: str):
            if result.returncode == 0:
                _print_success("    Node.js dependencies installed")
            else:
-                _print_warning("    npm install failed - run manually: cd ~/.hermes/hermes-agent && npm install")
+                from hermes_constants import display_hermes_home
+                _print_warning(f"    npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install")
        elif not node_modules.exists():
            _print_warning("    Node.js not found - browser tools require: npm install (in hermes-agent directory)")

@@ -652,9 +659,61 @@ def _prompt_choice(question: str, choices: list, default: int = 0) -> int:
            return default


+# ─── Token Estimation ────────────────────────────────────────────────────────
+
+# Module-level cache so discovery + tokenization runs at most once per process.
+_tool_token_cache: Optional[Dict[str, int]] = None
+
+
+def _estimate_tool_tokens() -> Dict[str, int]:
+    """Return estimated token counts per individual tool name.
+
+    Uses tiktoken (cl100k_base) to count tokens in the JSON-serialised
+    OpenAI-format tool schema.  Triggers tool discovery on first call,
+    then caches the result for the rest of the process.
+
+    Returns an empty dict when tiktoken or the registry is unavailable.
+    """
+    global _tool_token_cache
+    if _tool_token_cache is not None:
+        return _tool_token_cache
+
+    try:
+        import tiktoken
+        enc = tiktoken.get_encoding("cl100k_base")
+    except Exception:
+        logger.debug("tiktoken unavailable; skipping tool token estimation")
+        _tool_token_cache = {}
+        return _tool_token_cache
+
+    try:
+        # Trigger full tool discovery (imports all tool modules).
+        import model_tools  # noqa: F401
+        from tools.registry import registry
+    except Exception:
+        logger.debug("Tool registry unavailable; skipping token estimation")
+        _tool_token_cache = {}
+        return _tool_token_cache
+
+    counts: Dict[str, int] = {}
+    for name in registry.get_all_tool_names():
+        schema = registry.get_schema(name)
+        if schema:
+            # Mirror what gets sent to the API:
+            # {"type": "function", "function": <schema>}
+            text = _json.dumps({"type": "function", "function": schema})
+            counts[name] = len(enc.encode(text))
+    _tool_token_cache = counts
+    return _tool_token_cache
+
+
 def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str]:
    """Multi-select checklist of toolsets. Returns set of selected toolset keys."""
    from hermes_cli.curses_ui import curses_checklist
+    from toolsets import resolve_toolset
+
+    # Pre-compute per-tool token counts (cached after first call).
+    tool_tokens = _estimate_tool_tokens()

    effective = _get_effective_configurable_toolsets()

@@ -670,11 +729,27 @@ def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str
        if ts_key in enabled
    }

+    # Build a live status function that shows deduplicated total token cost.
+    status_fn = None
+    if tool_tokens:
+        ts_keys = [ts_key for ts_key, _, _ in effective]
+
+        def status_fn(chosen: set) -> str:
+            # Collect unique tool names across all selected toolsets
+            all_tools: set = set()
+            for idx in chosen:
+                all_tools.update(resolve_toolset(ts_keys[idx]))
+            total = sum(tool_tokens.get(name, 0) for name in all_tools)
+            if total >= 1000:
+                return f"Est. tool context: ~{total / 1000:.1f}k tokens"
+            return f"Est. tool context: ~{total} tokens"
+
    chosen = curses_checklist(
        f"Tools for {platform_label}",
        labels,
        pre_selected,
        cancel_returns=pre_selected,
+        status_fn=status_fn,
    )
    return {effective[i][0] for i in chosen}

@@ -1264,7 +1339,8 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
        platform_choices[idx] = f"Configure {pinfo['label']}  ({new_count}/{total} enabled)"

    print()
-    print(color("  Tool configuration saved to ~/.hermes/config.yaml", Colors.DIM))
+    from hermes_constants import display_hermes_home
+    print(color(f"  Tool configuration saved to {display_hermes_home()}/config.yaml", Colors.DIM))
    print(color("  Changes take effect on next 'hermes' or gateway restart.", Colors.DIM))
    print()

@@ -18,6 +18,8 @@ import time
 from pathlib import Path
 from typing import Dict, Optional

+from hermes_constants import display_hermes_home
+

 _SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json"

@@ -76,13 +78,15 @@ def _get_webhook_base_url() -> str:
    return f"http://{display_host}:{port}"


-_SETUP_HINT = """
+def _setup_hint() -> str:
+    _dhh = display_hermes_home()
+    return f"""
  Webhook platform is not enabled. To set it up:

  1. Run the gateway setup wizard:
     hermes gateway setup

-  2. Or manually add to ~/.hermes/config.yaml:
+  2. Or manually add to {_dhh}/config.yaml:
     platforms:
       webhook:
         enabled: true
@@ -91,7 +95,7 @@ _SETUP_HINT = """
           port: 8644
           secret: "your-global-hmac-secret"

-  3. Or set environment variables in ~/.hermes/.env:
+  3. Or set environment variables in {_dhh}/.env:
     WEBHOOK_ENABLED=true
     WEBHOOK_PORT=8644
     WEBHOOK_SECRET=your-global-secret
@@ -104,7 +108,7 @@ def _require_webhook_enabled() -> bool:
    """Check webhook is enabled. Print setup guide and return False if not."""
    if _is_webhook_enabled():
        return True
-    print(_SETUP_HINT)
+    print(_setup_hint())
    return False


@@ -38,6 +38,26 @@ def get_hermes_dir(new_subpath: str, old_name: str) -> Path:
    return home / new_subpath


+def display_hermes_home() -> str:
+    """Return a user-friendly display string for the current HERMES_HOME.
+
+    Uses ``~/`` shorthand for readability::
+
+        default:  ``~/.hermes``
+        profile:  ``~/.hermes/profiles/coder``
+        custom:   ``/opt/hermes-custom``
+
+    Use this in **user-facing** print/log messages instead of hardcoding
+    ``~/.hermes``.  For code that needs a real ``Path``, use
+    :func:`get_hermes_home` instead.
+    """
+    home = get_hermes_home()
+    try:
+        return "~/" + str(home.relative_to(Path.home()))
+    except ValueError:
+        return str(home)
+
+
 VALID_REASONING_EFFORTS = ("xhigh", "high", "medium", "low", "minimal")


@@ -0,0 +1,868 @@
+"""
+Hermes MCP Server — expose messaging conversations as MCP tools.
+
+Starts a stdio MCP server that lets any MCP client (Claude Code, Cursor, Codex,
+etc.) list conversations, read message history, send messages, poll for live
+events, and manage approval requests across all connected platforms.
+
+Matches OpenClaw's 9-tool MCP channel bridge surface:
+  conversations_list, conversation_get, messages_read, attachments_fetch,
+  events_poll, events_wait, messages_send, permissions_list_open,
+  permissions_respond
+
+Plus: channels_list (Hermes-specific extra)
+
+Usage:
+    hermes mcp serve
+    hermes mcp serve --verbose
+
+MCP client config (e.g. claude_desktop_config.json):
+    {
+        "mcpServers": {
+            "hermes": {
+                "command": "hermes",
+                "args": ["mcp", "serve"]
+            }
+        }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("hermes.mcp_serve")
+
+# ---------------------------------------------------------------------------
+# Lazy MCP SDK import
+# ---------------------------------------------------------------------------
+
+_MCP_SERVER_AVAILABLE = False
+try:
+    from mcp.server.fastmcp import FastMCP
+
+    _MCP_SERVER_AVAILABLE = True
+except ImportError:
+    FastMCP = None  # type: ignore[assignment,misc]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _get_sessions_dir() -> Path:
+    """Return the sessions directory using HERMES_HOME."""
+    try:
+        from hermes_constants import get_hermes_home
+        return get_hermes_home() / "sessions"
+    except ImportError:
+        return Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "sessions"
+
+
+def _get_session_db():
+    """Get a SessionDB instance for reading message transcripts."""
+    try:
+        from hermes_state import SessionDB
+        return SessionDB()
+    except Exception as e:
+        logger.debug("SessionDB unavailable: %s", e)
+        return None
+
+
+def _load_sessions_index() -> dict:
+    """Load the gateway sessions.json index directly.
+
+    Returns a dict of session_key -> entry_dict with platform routing info.
+    This avoids importing the full SessionStore which needs GatewayConfig.
+    """
+    sessions_file = _get_sessions_dir() / "sessions.json"
+    if not sessions_file.exists():
+        return {}
+    try:
+        with open(sessions_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        logger.debug("Failed to load sessions.json: %s", e)
+        return {}
+
+
+def _load_channel_directory() -> dict:
+    """Load the cached channel directory for available targets."""
+    try:
+        from hermes_constants import get_hermes_home
+        directory_file = get_hermes_home() / "channel_directory.json"
+    except ImportError:
+        directory_file = Path(
+            os.environ.get("HERMES_HOME", Path.home() / ".hermes")
+        ) / "channel_directory.json"
+
+    if not directory_file.exists():
+        return {}
+    try:
+        with open(directory_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        logger.debug("Failed to load channel_directory.json: %s", e)
+        return {}
+
+
+def _extract_message_content(msg: dict) -> str:
+    """Extract text content from a message, handling multi-part content."""
+    content = msg.get("content", "")
+    if isinstance(content, list):
+        text_parts = [
+            p.get("text", "") for p in content
+            if isinstance(p, dict) and p.get("type") == "text"
+        ]
+        return "\n".join(text_parts)
+    return str(content) if content else ""
+
+
+def _extract_attachments(msg: dict) -> List[dict]:
+    """Extract non-text attachments from a message.
+
+    Finds: multi-part image/file content blocks, MEDIA: tags in text,
+    image URLs, and file references.
+    """
+    attachments = []
+    content = msg.get("content", "")
+
+    # Multi-part content blocks (image_url, file, etc.)
+    if isinstance(content, list):
+        for part in content:
+            if not isinstance(part, dict):
+                continue
+            ptype = part.get("type", "")
+            if ptype == "image_url":
+                url = part.get("image_url", {}).get("url", "") if isinstance(part.get("image_url"), dict) else ""
+                if url:
+                    attachments.append({"type": "image", "url": url})
+            elif ptype == "image":
+                url = part.get("url", part.get("source", {}).get("url", ""))
+                if url:
+                    attachments.append({"type": "image", "url": url})
+            elif ptype not in ("text",):
+                # Unknown non-text content type
+                attachments.append({"type": ptype, "data": part})
+
+    # MEDIA: tags in text content
+    text = _extract_message_content(msg)
+    if text:
+        media_pattern = re.compile(r'MEDIA:\s*(\S+)')
+        for match in media_pattern.finditer(text):
+            path = match.group(1)
+            attachments.append({"type": "media", "path": path})
+
+    return attachments
+
+
+# ---------------------------------------------------------------------------
+# Event Bridge — polls SessionDB for new messages, maintains event queue
+# ---------------------------------------------------------------------------
+
+QUEUE_LIMIT = 1000
+POLL_INTERVAL = 0.2  # seconds between DB polls (200ms)
+
+
+@dataclass
+class QueueEvent:
+    """An event in the bridge's in-memory queue."""
+    cursor: int
+    type: str  # "message", "approval_requested", "approval_resolved"
+    session_key: str = ""
+    data: dict = field(default_factory=dict)
+
+
+class EventBridge:
+    """Background poller that watches SessionDB for new messages and
+    maintains an in-memory event queue with waiter support.
+
+    This is the Hermes equivalent of OpenClaw's WebSocket gateway bridge.
+    Instead of WebSocket events, we poll the SQLite database for changes.
+    """
+
+    def __init__(self):
+        self._queue: List[QueueEvent] = []
+        self._cursor = 0
+        self._lock = threading.Lock()
+        self._new_event = threading.Event()
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+        self._last_poll_timestamps: Dict[str, float] = {}  # session_key -> unix timestamp
+        # In-memory approval tracking (populated from events)
+        self._pending_approvals: Dict[str, dict] = {}
+        # mtime cache — skip expensive work when files haven't changed
+        self._sessions_json_mtime: float = 0.0
+        self._state_db_mtime: float = 0.0
+        self._cached_sessions_index: dict = {}
+
+    def start(self):
+        """Start the background polling thread."""
+        if self._running:
+            return
+        self._running = True
+        self._thread = threading.Thread(target=self._poll_loop, daemon=True)
+        self._thread.start()
+        logger.debug("EventBridge started")
+
+    def stop(self):
+        """Stop the background polling thread."""
+        self._running = False
+        self._new_event.set()  # Wake any waiters
+        if self._thread:
+            self._thread.join(timeout=5)
+        logger.debug("EventBridge stopped")
+
+    def poll_events(
+        self,
+        after_cursor: int = 0,
+        session_key: Optional[str] = None,
+        limit: int = 20,
+    ) -> dict:
+        """Return events since after_cursor, optionally filtered by session_key."""
+        with self._lock:
+            events = [
+                e for e in self._queue
+                if e.cursor > after_cursor
+                and (not session_key or e.session_key == session_key)
+            ][:limit]
+
+        next_cursor = events[-1].cursor if events else after_cursor
+        return {
+            "events": [
+                {"cursor": e.cursor, "type": e.type,
+                 "session_key": e.session_key, **e.data}
+                for e in events
+            ],
+            "next_cursor": next_cursor,
+        }
+
+    def wait_for_event(
+        self,
+        after_cursor: int = 0,
+        session_key: Optional[str] = None,
+        timeout_ms: int = 30000,
+    ) -> Optional[dict]:
+        """Block until a matching event arrives or timeout expires."""
+        deadline = time.monotonic() + (timeout_ms / 1000.0)
+
+        while time.monotonic() < deadline:
+            with self._lock:
+                for e in self._queue:
+                    if e.cursor > after_cursor and (
+                        not session_key or e.session_key == session_key
+                    ):
+                        return {
+                            "cursor": e.cursor, "type": e.type,
+                            "session_key": e.session_key, **e.data,
+                        }
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            self._new_event.clear()
+            self._new_event.wait(timeout=min(remaining, POLL_INTERVAL))
+
+        return None
+
+    def list_pending_approvals(self) -> List[dict]:
+        """List approval requests observed during this bridge session."""
+        with self._lock:
+            return sorted(
+                self._pending_approvals.values(),
+                key=lambda a: a.get("created_at", ""),
+            )
+
+    def respond_to_approval(self, approval_id: str, decision: str) -> dict:
+        """Resolve a pending approval (best-effort without gateway IPC)."""
+        with self._lock:
+            approval = self._pending_approvals.pop(approval_id, None)
+
+        if not approval:
+            return {"error": f"Approval not found: {approval_id}"}
+
+        self._enqueue(QueueEvent(
+            cursor=0,  # Will be set by _enqueue
+            type="approval_resolved",
+            session_key=approval.get("session_key", ""),
+            data={"approval_id": approval_id, "decision": decision},
+        ))
+
+        return {"resolved": True, "approval_id": approval_id, "decision": decision}
+
+    def _enqueue(self, event: QueueEvent) -> None:
+        """Add an event to the queue and wake any waiters."""
+        with self._lock:
+            self._cursor += 1
+            event.cursor = self._cursor
+            self._queue.append(event)
+            # Trim queue to limit
+            while len(self._queue) > QUEUE_LIMIT:
+                self._queue.pop(0)
+        self._new_event.set()
+
+    def _poll_loop(self):
+        """Background loop: poll SessionDB for new messages."""
+        db = _get_session_db()
+        if not db:
+            logger.warning("EventBridge: SessionDB unavailable, event polling disabled")
+            return
+
+        while self._running:
+            try:
+                self._poll_once(db)
+            except Exception as e:
+                logger.debug("EventBridge poll error: %s", e)
+            time.sleep(POLL_INTERVAL)
+
+    def _poll_once(self, db):
+        """Check for new messages across all sessions.
+
+        Uses mtime checks on sessions.json and state.db to skip work
+        when nothing has changed — makes 200ms polling essentially free.
+        """
+        # Check if sessions.json has changed (mtime check is ~1μs)
+        sessions_file = _get_sessions_dir() / "sessions.json"
+        try:
+            sj_mtime = sessions_file.stat().st_mtime if sessions_file.exists() else 0.0
+        except OSError:
+            sj_mtime = 0.0
+
+        if sj_mtime != self._sessions_json_mtime:
+            self._sessions_json_mtime = sj_mtime
+            self._cached_sessions_index = _load_sessions_index()
+
+        # Check if state.db has changed
+        try:
+            from hermes_constants import get_hermes_home
+            db_file = get_hermes_home() / "state.db"
+        except ImportError:
+            db_file = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "state.db"
+
+        try:
+            db_mtime = db_file.stat().st_mtime if db_file.exists() else 0.0
+        except OSError:
+            db_mtime = 0.0
+
+        if db_mtime == self._state_db_mtime and sj_mtime == self._sessions_json_mtime:
+            return  # Nothing changed since last poll — skip entirely
+
+        self._state_db_mtime = db_mtime
+        entries = self._cached_sessions_index
+
+        for session_key, entry in entries.items():
+            session_id = entry.get("session_id", "")
+            if not session_id:
+                continue
+
+            last_seen = self._last_poll_timestamps.get(session_key, 0.0)
+
+            try:
+                messages = db.get_messages(session_id)
+            except Exception:
+                continue
+
+            if not messages:
+                continue
+
+            # Normalize timestamps to float for comparison
+            def _ts_float(ts) -> float:
+                if isinstance(ts, (int, float)):
+                    return float(ts)
+                if isinstance(ts, str) and ts:
+                    try:
+                        return float(ts)
+                    except ValueError:
+                        # ISO string — parse to epoch
+                        try:
+                            from datetime import datetime
+                            return datetime.fromisoformat(ts).timestamp()
+                        except Exception:
+                            return 0.0
+                return 0.0
+
+            # Find messages newer than our last seen timestamp
+            new_messages = []
+            for msg in messages:
+                ts = _ts_float(msg.get("timestamp", 0))
+                role = msg.get("role", "")
+                if role not in ("user", "assistant"):
+                    continue
+                if ts > last_seen:
+                    new_messages.append(msg)
+
+            for msg in new_messages:
+                content = _extract_message_content(msg)
+                if not content:
+                    continue
+                self._enqueue(QueueEvent(
+                    cursor=0,
+                    type="message",
+                    session_key=session_key,
+                    data={
+                        "role": msg.get("role", ""),
+                        "content": content[:500],
+                        "timestamp": str(msg.get("timestamp", "")),
+                        "message_id": str(msg.get("id", "")),
+                    },
+                ))
+
+            # Update last seen to the most recent message timestamp
+            all_ts = [_ts_float(m.get("timestamp", 0)) for m in messages]
+            if all_ts:
+                latest = max(all_ts)
+                if latest > last_seen:
+                    self._last_poll_timestamps[session_key] = latest
+
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+
+def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
+    """Create and return the Hermes MCP server with all tools registered."""
+    if not _MCP_SERVER_AVAILABLE:
+        raise ImportError(
+            "MCP server requires the 'mcp' package. "
+            "Install with: pip install 'hermes-agent[mcp]'"
+        )
+
+    mcp = FastMCP(
+        "hermes",
+        instructions=(
+            "Hermes Agent messaging bridge. Use these tools to interact with "
+            "conversations across Telegram, Discord, Slack, WhatsApp, Signal, "
+            "Matrix, and other connected platforms."
+        ),
+    )
+
+    bridge = event_bridge or EventBridge()
+
+    # -- conversations_list ------------------------------------------------
+
+    @mcp.tool()
+    def conversations_list(
+        platform: Optional[str] = None,
+        limit: int = 50,
+        search: Optional[str] = None,
+    ) -> str:
+        """List active messaging conversations across connected platforms.
+
+        Returns conversations with their session keys (needed for messages_read),
+        platform, chat type, display name, and last activity time.
+
+        Args:
+            platform: Filter by platform name (telegram, discord, slack, etc.)
+            limit: Maximum number of conversations to return (default 50)
+            search: Optional text to filter conversations by name
+        """
+        entries = _load_sessions_index()
+        conversations = []
+
+        for key, entry in entries.items():
+            origin = entry.get("origin", {})
+            entry_platform = entry.get("platform") or origin.get("platform", "")
+
+            if platform and entry_platform.lower() != platform.lower():
+                continue
+
+            display_name = entry.get("display_name", "")
+            chat_name = origin.get("chat_name", "")
+            if search:
+                search_lower = search.lower()
+                if (search_lower not in display_name.lower()
+                        and search_lower not in chat_name.lower()
+                        and search_lower not in key.lower()):
+                    continue
+
+            conversations.append({
+                "session_key": key,
+                "session_id": entry.get("session_id", ""),
+                "platform": entry_platform,
+                "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
+                "display_name": display_name,
+                "chat_name": chat_name,
+                "user_name": origin.get("user_name", ""),
+                "updated_at": entry.get("updated_at", ""),
+            })
+
+        conversations.sort(key=lambda c: c.get("updated_at", ""), reverse=True)
+        conversations = conversations[:limit]
+
+        return json.dumps({
+            "count": len(conversations),
+            "conversations": conversations,
+        }, indent=2)
+
+    # -- conversation_get --------------------------------------------------
+
+    @mcp.tool()
+    def conversation_get(session_key: str) -> str:
+        """Get detailed info about one conversation by its session key.
+
+        Args:
+            session_key: The session key from conversations_list
+        """
+        entries = _load_sessions_index()
+        entry = entries.get(session_key)
+
+        if not entry:
+            return json.dumps({"error": f"Conversation not found: {session_key}"})
+
+        origin = entry.get("origin", {})
+        return json.dumps({
+            "session_key": session_key,
+            "session_id": entry.get("session_id", ""),
+            "platform": entry.get("platform") or origin.get("platform", ""),
+            "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
+            "display_name": entry.get("display_name", ""),
+            "user_name": origin.get("user_name", ""),
+            "chat_name": origin.get("chat_name", ""),
+            "chat_id": origin.get("chat_id", ""),
+            "thread_id": origin.get("thread_id"),
+            "updated_at": entry.get("updated_at", ""),
+            "created_at": entry.get("created_at", ""),
+            "input_tokens": entry.get("input_tokens", 0),
+            "output_tokens": entry.get("output_tokens", 0),
+            "total_tokens": entry.get("total_tokens", 0),
+        }, indent=2)
+
+    # -- messages_read -----------------------------------------------------
+
+    @mcp.tool()
+    def messages_read(
+        session_key: str,
+        limit: int = 50,
+    ) -> str:
+        """Read recent messages from a conversation.
+
+        Returns the message history in chronological order with role, content,
+        and timestamp for each message.
+
+        Args:
+            session_key: The session key from conversations_list
+            limit: Maximum number of messages to return (default 50, most recent)
+        """
+        entries = _load_sessions_index()
+        entry = entries.get(session_key)
+        if not entry:
+            return json.dumps({"error": f"Conversation not found: {session_key}"})
+
+        session_id = entry.get("session_id", "")
+        if not session_id:
+            return json.dumps({"error": "No session ID for this conversation"})
+
+        db = _get_session_db()
+        if not db:
+            return json.dumps({"error": "Session database unavailable"})
+
+        try:
+            all_messages = db.get_messages(session_id)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to read messages: {e}"})
+
+        filtered = []
+        for msg in all_messages:
+            role = msg.get("role", "")
+            if role in ("user", "assistant"):
+                content = _extract_message_content(msg)
+                if content:
+                    filtered.append({
+                        "id": str(msg.get("id", "")),
+                        "role": role,
+                        "content": content[:2000],
+                        "timestamp": msg.get("timestamp", ""),
+                    })
+
+        messages = filtered[-limit:]
+
+        return json.dumps({
+            "session_key": session_key,
+            "count": len(messages),
+            "total_in_session": len(filtered),
+            "messages": messages,
+        }, indent=2)
+
+    # -- attachments_fetch -------------------------------------------------
+
+    @mcp.tool()
+    def attachments_fetch(
+        session_key: str,
+        message_id: str,
+    ) -> str:
+        """List non-text attachments for a message in a conversation.
+
+        Extracts images, media files, and other non-text content blocks
+        from the specified message.
+
+        Args:
+            session_key: The session key from conversations_list
+            message_id: The message ID from messages_read
+        """
+        entries = _load_sessions_index()
+        entry = entries.get(session_key)
+        if not entry:
+            return json.dumps({"error": f"Conversation not found: {session_key}"})
+
+        session_id = entry.get("session_id", "")
+        if not session_id:
+            return json.dumps({"error": "No session ID for this conversation"})
+
+        db = _get_session_db()
+        if not db:
+            return json.dumps({"error": "Session database unavailable"})
+
+        try:
+            all_messages = db.get_messages(session_id)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to read messages: {e}"})
+
+        # Find the target message
+        target_msg = None
+        for msg in all_messages:
+            if str(msg.get("id", "")) == message_id:
+                target_msg = msg
+                break
+
+        if not target_msg:
+            return json.dumps({"error": f"Message not found: {message_id}"})
+
+        attachments = _extract_attachments(target_msg)
+
+        return json.dumps({
+            "message_id": message_id,
+            "count": len(attachments),
+            "attachments": attachments,
+        }, indent=2)
+
+    # -- events_poll -------------------------------------------------------
+
+    @mcp.tool()
+    def events_poll(
+        after_cursor: int = 0,
+        session_key: Optional[str] = None,
+        limit: int = 20,
+    ) -> str:
+        """Poll for new conversation events since a cursor position.
+
+        Returns events that have occurred since the given cursor. Use the
+        returned next_cursor value for subsequent polls.
+
+        Event types: message, approval_requested, approval_resolved
+
+        Args:
+            after_cursor: Return events after this cursor (0 for all)
+            session_key: Optional filter to one conversation
+            limit: Maximum events to return (default 20)
+        """
+        result = bridge.poll_events(
+            after_cursor=after_cursor,
+            session_key=session_key,
+            limit=limit,
+        )
+        return json.dumps(result, indent=2)
+
+    # -- events_wait -------------------------------------------------------
+
+    @mcp.tool()
+    def events_wait(
+        after_cursor: int = 0,
+        session_key: Optional[str] = None,
+        timeout_ms: int = 30000,
+    ) -> str:
+        """Wait for the next conversation event (long-poll).
+
+        Blocks until a matching event arrives or the timeout expires.
+        Use this for near-real-time event delivery without polling.
+
+        Args:
+            after_cursor: Wait for events after this cursor
+            session_key: Optional filter to one conversation
+            timeout_ms: Maximum wait time in milliseconds (default 30000)
+        """
+        event = bridge.wait_for_event(
+            after_cursor=after_cursor,
+            session_key=session_key,
+            timeout_ms=min(timeout_ms, 300000),  # Cap at 5 minutes
+        )
+        if event:
+            return json.dumps({"event": event}, indent=2)
+        return json.dumps({"event": None, "reason": "timeout"}, indent=2)
+
+    # -- messages_send -----------------------------------------------------
+
+    @mcp.tool()
+    def messages_send(
+        target: str,
+        message: str,
+    ) -> str:
+        """Send a message to a platform conversation.
+
+        The target format is "platform:chat_id" — same format used by the
+        channels_list tool. You can also use human-friendly channel names
+        that will be resolved automatically.
+
+        Examples:
+            target="telegram:6308981865"
+            target="discord:#general"
+            target="slack:#engineering"
+
+        Args:
+            target: Platform target in "platform:identifier" format
+            message: The message text to send
+        """
+        if not target or not message:
+            return json.dumps({"error": "Both target and message are required"})
+
+        try:
+            from tools.send_message_tool import send_message_tool
+            result_str = send_message_tool(
+                {"action": "send", "target": target, "message": message}
+            )
+            return result_str
+        except ImportError:
+            return json.dumps({"error": "Send message tool not available"})
+        except Exception as e:
+            return json.dumps({"error": f"Send failed: {e}"})
+
+    # -- channels_list -----------------------------------------------------
+
+    @mcp.tool()
+    def channels_list(platform: Optional[str] = None) -> str:
+        """List available messaging channels and targets across platforms.
+
+        Returns channels that you can send messages to. The target strings
+        returned here can be used directly with the messages_send tool.
+
+        Args:
+            platform: Filter by platform name (telegram, discord, slack, etc.)
+        """
+        directory = _load_channel_directory()
+        if not directory:
+            entries = _load_sessions_index()
+            targets = []
+            seen = set()
+            for key, entry in entries.items():
+                origin = entry.get("origin", {})
+                p = entry.get("platform") or origin.get("platform", "")
+                chat_id = origin.get("chat_id", "")
+                if not p or not chat_id:
+                    continue
+                if platform and p.lower() != platform.lower():
+                    continue
+                target_str = f"{p}:{chat_id}"
+                if target_str in seen:
+                    continue
+                seen.add(target_str)
+                targets.append({
+                    "target": target_str,
+                    "platform": p,
+                    "name": entry.get("display_name") or origin.get("chat_name", ""),
+                    "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
+                })
+            return json.dumps({"count": len(targets), "channels": targets}, indent=2)
+
+        channels = []
+        for plat, entries_list in directory.items():
+            if platform and plat.lower() != platform.lower():
+                continue
+            if isinstance(entries_list, list):
+                for ch in entries_list:
+                    if isinstance(ch, dict):
+                        chat_id = ch.get("id", ch.get("chat_id", ""))
+                        channels.append({
+                            "target": f"{plat}:{chat_id}" if chat_id else plat,
+                            "platform": plat,
+                            "name": ch.get("name", ch.get("display_name", "")),
+                            "chat_type": ch.get("type", ""),
+                        })
+
+        return json.dumps({"count": len(channels), "channels": channels}, indent=2)
+
+    # -- permissions_list_open ---------------------------------------------
+
+    @mcp.tool()
+    def permissions_list_open() -> str:
+        """List pending approval requests observed during this bridge session.
+
+        Returns exec and plugin approval requests that the bridge has seen
+        since it started. Approvals are live-session only — older approvals
+        from before the bridge connected are not included.
+        """
+        approvals = bridge.list_pending_approvals()
+        return json.dumps({
+            "count": len(approvals),
+            "approvals": approvals,
+        }, indent=2)
+
+    # -- permissions_respond -----------------------------------------------
+
+    @mcp.tool()
+    def permissions_respond(
+        id: str,
+        decision: str,
+    ) -> str:
+        """Respond to a pending approval request.
+
+        Args:
+            id: The approval ID from permissions_list_open
+            decision: One of "allow-once", "allow-always", or "deny"
+        """
+        if decision not in ("allow-once", "allow-always", "deny"):
+            return json.dumps({
+                "error": f"Invalid decision: {decision}. "
+                         f"Must be allow-once, allow-always, or deny"
+            })
+
+        result = bridge.respond_to_approval(id, decision)
+        return json.dumps(result, indent=2)
+
+    return mcp
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def run_mcp_server(verbose: bool = False) -> None:
+    """Start the Hermes MCP server on stdio."""
+    if not _MCP_SERVER_AVAILABLE:
+        print(
+            "Error: MCP server requires the 'mcp' package.\n"
+            "Install with: pip install 'hermes-agent[mcp]'",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)
+    else:
+        logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
+
+    bridge = EventBridge()
+    bridge.start()
+
+    server = create_mcp_server(event_bridge=bridge)
+
+    import asyncio
+
+    async def _run():
+        try:
+            await server.run_stdio_async()
+        finally:
+            bridge.stop()
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        bridge.stop()
@@ -0,0 +1 @@
+Communication and decision-making frameworks — structured response formats for proposals, trade-off analysis, and stakeholder-ready recommendations.
@@ -0,0 +1,103 @@
+---
+name: one-three-one-rule
+description: >
+  Structured decision-making framework for technical proposals and trade-off analysis.
+  When the user faces a choice between multiple approaches (architecture decisions,
+  tool selection, refactoring strategies, migration paths), this skill produces a
+  1-3-1 format: one clear problem statement, three distinct options with pros/cons,
+  and one concrete recommendation with definition of done and implementation plan.
+  Use when the user asks for a "1-3-1", says "give me options", or needs help
+  choosing between competing approaches.
+version: 1.0.0
+author: Willard Moore
+license: MIT
+category: communication
+metadata:
+  hermes:
+    tags: [communication, decision-making, proposals, trade-offs]
+---
+
+# 1-3-1 Communication Rule
+
+Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
+
+## When to Use
+
+- The user explicitly asks for a "1-3-1" response.
+- The user says "give me options" or "what are my choices" for a technical decision.
+- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
+- The user needs a proposal they can forward to a team or stakeholder.
+
+Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
+
+## Procedure
+
+1. **Problem** (one sentence)
+   - State the core decision or desired outcome in a single concise sentence.
+   - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
+   - Keep it tight. If you need "and", you're describing two problems.
+
+2. **Options** (exactly three)
+   - Present three distinct, viable approaches labeled A, B, C.
+   - Each option gets a brief description, pros, and cons.
+   - Options should represent genuinely different strategies, not minor variations of the same approach.
+
+3. **Recommendation** (one option)
+   - State which option you recommend and why, based on the user's context and priorities.
+   - Be direct — this is your professional judgment, not a hedge.
+
+4. **Definition of Done**
+   - List the specific success criteria for the recommended option.
+   - These are concrete, verifiable outcomes — not vague aspirations.
+   - If the user picks a different option, revise this section to match.
+
+5. **Implementation Plan**
+   - Concrete steps to execute the recommended option.
+   - Include specific commands, tools, or actions where applicable.
+   - If the user picks a different option, revise this section to match.
+
+## Verification
+
+- Response has exactly one Problem sentence.
+- Response has exactly three Options (A, B, C) with pros and cons for each.
+- Response has a single Recommendation that picks one option with reasoning.
+- Definition of Done and Implementation Plan align with the recommended option.
+- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
+
+## Example
+
+User: "Give me a 1-3-1 for adding retry logic to our API client."
+
+Agent:
+
+**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
+
+**Options:**
+
+- **Option A: Exponential backoff with jitter in a shared utility.**
+  Pros: Simple, well-understood pattern; single implementation shared across all callers.
+  Cons: No circuit-breaking; callers still block during retries.
+
+- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
+  Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
+  Cons: Adds a dependency; decorator pattern can obscure control flow.
+
+- **Option C: Queue-based async retry with dead letter handling.**
+  Pros: Non-blocking; failed calls are tracked and replayable; scales well.
+  Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
+
+**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
+
+**Definition of Done:**
+- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
+- Retries up to 3 times with exponential backoff and jitter.
+- All external API calls route through the retry utility.
+- Logs each retry attempt with endpoint and attempt number.
+- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
+
+**Implementation Plan:**
+1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
+2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
+3. Wrap existing API calls in `api_client.py` with the retry utility.
+4. Add unit tests mocking HTTP responses for each retry scenario.
+5. Verify under load with a simple stress test against a flaky endpoint mock.
@@ -304,6 +304,29 @@ def ensure_parent(path: Path) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)


+def resolve_secret_input(value: Any, env: Optional[Dict[str, str]] = None) -> Optional[str]:
+    """Resolve an OpenClaw SecretInput value to a plain string.
+
+    SecretInput can be:
+    - A plain string: "sk-..."
+    - An env template: "${OPENROUTER_API_KEY}"
+    - A SecretRef object: {"source": "env", "id": "OPENROUTER_API_KEY"}
+    """
+    if isinstance(value, str):
+        # Check for env template: "${VAR_NAME}"
+        m = re.match(r"^\$\{(\w+)\}$", value.strip())
+        if m and env:
+            return env.get(m.group(1), "").strip() or None
+        return value.strip() or None
+    if isinstance(value, dict):
+        source = value.get("source", "")
+        ref_id = value.get("id", "")
+        if source == "env" and ref_id and env:
+            return env.get(ref_id, "").strip() or None
+        # File/exec sources can't be resolved here — return None
+    return None
+
+
 def load_yaml_file(path: Path) -> Dict[str, Any]:
    if yaml is None or not path.exists():
        return {}
@@ -890,14 +913,20 @@ class Migrator:
            self.record("command-allowlist", source, destination, "migrated", "Would merge patterns", added_patterns=added)

    def load_openclaw_config(self) -> Dict[str, Any]:
-        config_path = self.source_root / "openclaw.json"
-        if not config_path.exists():
-            return {}
-        try:
-            data = json.loads(config_path.read_text(encoding="utf-8"))
-            return data if isinstance(data, dict) else {}
-        except json.JSONDecodeError:
-            return {}
+        # Check current name and legacy config filenames
+        for name in ("openclaw.json", "clawdbot.json", "moldbot.json"):
+            config_path = self.source_root / name
+            if config_path.exists():
+                try:
+                    data = json.loads(config_path.read_text(encoding="utf-8"))
+                    return data if isinstance(data, dict) else {}
+                except json.JSONDecodeError:
+                    continue
+        return {}
+
+    def load_openclaw_env(self) -> Dict[str, str]:
+        """Load the OpenClaw .env file for secrets that live there instead of config."""
+        return parse_env_file(self.source_root / ".env")

    def merge_env_values(self, additions: Dict[str, str], kind: str, source: Path) -> None:
        destination = self.target_root / ".env"
@@ -1024,6 +1053,10 @@ class Migrator:
                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
            )

+    def _resolve_channel_secret(self, value: Any) -> Optional[str]:
+        """Resolve a channel config value that may be a SecretRef."""
+        return resolve_secret_input(value, self.load_openclaw_env())
+
    def migrate_discord_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
        config = config or self.load_openclaw_config()
        additions: Dict[str, str] = {}
@@ -1118,15 +1151,17 @@ class Migrator:
        secret_additions: Dict[str, str] = {}

        # Extract provider API keys from models.providers
+        # Note: apiKey values can be strings, env templates, or SecretRef objects
+        openclaw_env = self.load_openclaw_env()
        providers = config.get("models", {}).get("providers", {})
        if isinstance(providers, dict):
            for provider_name, provider_cfg in providers.items():
                if not isinstance(provider_cfg, dict):
                    continue
-                api_key = provider_cfg.get("apiKey")
-                if not isinstance(api_key, str) or not api_key.strip():
+                raw_key = provider_cfg.get("apiKey")
+                api_key = resolve_secret_input(raw_key, openclaw_env)
+                if not api_key:
                    continue
-                api_key = api_key.strip()

                base_url = provider_cfg.get("baseUrl", "")
                api_type = provider_cfg.get("api", "")
@@ -1170,6 +1205,50 @@ class Migrator:
                if isinstance(oai_key, str) and oai_key.strip():
                    secret_additions["VOICE_TOOLS_OPENAI_KEY"] = oai_key.strip()

+        # Also check the OpenClaw .env file — many users store keys there
+        # instead of inline in openclaw.json
+        openclaw_env = self.load_openclaw_env()
+        env_key_mapping = {
+            "OPENROUTER_API_KEY": "OPENROUTER_API_KEY",
+            "OPENAI_API_KEY": "OPENAI_API_KEY",
+            "ANTHROPIC_API_KEY": "ANTHROPIC_API_KEY",
+            "ELEVENLABS_API_KEY": "ELEVENLABS_API_KEY",
+            "TELEGRAM_BOT_TOKEN": "TELEGRAM_BOT_TOKEN",
+            "DEEPSEEK_API_KEY": "DEEPSEEK_API_KEY",
+            "GEMINI_API_KEY": "GEMINI_API_KEY",
+            "ZAI_API_KEY": "ZAI_API_KEY",
+            "MINIMAX_API_KEY": "MINIMAX_API_KEY",
+        }
+        for oc_key, hermes_key in env_key_mapping.items():
+            val = openclaw_env.get(oc_key, "").strip()
+            if val and hermes_key not in secret_additions:
+                secret_additions[hermes_key] = val
+
+        # Check per-agent auth-profiles.json for additional credentials
+        auth_profiles_path = self.source_root / "agents" / "main" / "agent" / "auth-profiles.json"
+        if auth_profiles_path.exists():
+            try:
+                profiles = json.loads(auth_profiles_path.read_text(encoding="utf-8"))
+                if isinstance(profiles, dict):
+                    # auth-profiles.json wraps profiles in a "profiles" key
+                    profile_entries = profiles.get("profiles", profiles) if isinstance(profiles.get("profiles"), dict) else profiles
+                    for profile_name, profile_data in profile_entries.items():
+                        if not isinstance(profile_data, dict):
+                            continue
+                        # Canonical field is "key", "apiKey" is accepted as alias
+                        api_key = profile_data.get("key", "") or profile_data.get("apiKey", "")
+                        if not isinstance(api_key, str) or not api_key.strip():
+                            continue
+                        name_lower = profile_name.lower()
+                        if "openrouter" in name_lower and "OPENROUTER_API_KEY" not in secret_additions:
+                            secret_additions["OPENROUTER_API_KEY"] = api_key.strip()
+                        elif "openai" in name_lower and "OPENAI_API_KEY" not in secret_additions:
+                            secret_additions["OPENAI_API_KEY"] = api_key.strip()
+                        elif "anthropic" in name_lower and "ANTHROPIC_API_KEY" not in secret_additions:
+                            secret_additions["ANTHROPIC_API_KEY"] = api_key.strip()
+            except (json.JSONDecodeError, OSError):
+                pass
+
        if secret_additions:
            self.merge_env_values(secret_additions, "provider-keys", self.source_root / "openclaw.json")
        else:
@@ -1218,7 +1297,11 @@ class Migrator:

        if self.execute:
            backup_path = self.maybe_backup(destination)
-            hermes_config["model"] = model_str
+            existing_model = hermes_config.get("model")
+            if isinstance(existing_model, dict):
+                existing_model["default"] = model_str
+            else:
+                hermes_config["model"] = {"default": model_str}
            dump_yaml_file(destination, hermes_config)
            self.record("model-config", source_path, destination, "migrated", backup=str(backup_path) if backup_path else "", model=model_str)
        else:
@@ -1244,22 +1327,44 @@ class Migrator:
        if isinstance(provider, str) and provider in ("elevenlabs", "openai", "edge"):
            tts_data["provider"] = provider

-        elevenlabs = tts.get("elevenlabs", {})
+        # TTS provider settings live under messages.tts.providers.{provider}
+        # in OpenClaw (not messages.tts.elevenlabs directly)
+        providers = tts.get("providers") or {}
+
+        # Also check the top-level "talk" config which has provider settings too
+        talk_cfg = (config or self.load_openclaw_config()).get("talk") or {}
+        talk_providers = talk_cfg.get("providers") or {}
+
+        # Merge: messages.tts.providers takes priority, then talk.providers,
+        # then legacy flat keys (messages.tts.elevenlabs, etc.)
+        elevenlabs = (
+            (providers.get("elevenlabs") or {})
+            if isinstance(providers.get("elevenlabs"), dict) else
+            (talk_providers.get("elevenlabs") or {})
+            if isinstance(talk_providers.get("elevenlabs"), dict) else
+            (tts.get("elevenlabs") or {})
+        )
        if isinstance(elevenlabs, dict):
            el_settings: Dict[str, str] = {}
-            voice_id = elevenlabs.get("voiceId")
+            voice_id = elevenlabs.get("voiceId") or talk_cfg.get("voiceId")
            if isinstance(voice_id, str) and voice_id.strip():
                el_settings["voice_id"] = voice_id.strip()
-            model_id = elevenlabs.get("modelId")
+            model_id = elevenlabs.get("modelId") or talk_cfg.get("modelId")
            if isinstance(model_id, str) and model_id.strip():
                el_settings["model_id"] = model_id.strip()
            if el_settings:
                tts_data["elevenlabs"] = el_settings

-        openai_tts = tts.get("openai", {})
+        openai_tts = (
+            (providers.get("openai") or {})
+            if isinstance(providers.get("openai"), dict) else
+            (talk_providers.get("openai") or {})
+            if isinstance(talk_providers.get("openai"), dict) else
+            (tts.get("openai") or {})
+        )
        if isinstance(openai_tts, dict):
            oai_settings: Dict[str, str] = {}
-            oai_model = openai_tts.get("model")
+            oai_model = openai_tts.get("model") or openai_tts.get("modelId")
            if isinstance(oai_model, str) and oai_model.strip():
                oai_settings["model"] = oai_model.strip()
            oai_voice = openai_tts.get("voice")
@@ -1268,7 +1373,11 @@ class Migrator:
            if oai_settings:
                tts_data["openai"] = oai_settings

-        edge_tts = tts.get("edge", {})
+        edge_tts = (
+            (providers.get("edge") or {})
+            if isinstance(providers.get("edge"), dict) else
+            (tts.get("edge") or {})
+        )
        if isinstance(edge_tts, dict):
            edge_voice = edge_tts.get("voice")
            if isinstance(edge_voice, str) and edge_voice.strip():
@@ -1298,15 +1407,29 @@ class Migrator:
            self.record("tts-config", source_path, destination, "migrated", "Would set TTS config", settings=list(tts_data.keys()))

    def migrate_shared_skills(self) -> None:
-        source_root = self.source_root / "skills"
+        # Check all OpenClaw skill sources: managed, personal, project-level
+        skill_sources = [
+            (self.source_root / "skills", "shared-skills", "managed skills"),
+            (Path.home() / ".agents" / "skills", "personal-skills", "personal cross-project skills"),
+            (self.source_root / "workspace" / ".agents" / "skills", "project-skills", "project-level shared skills"),
+            (self.source_root / "workspace.default" / ".agents" / "skills", "project-skills", "project-level shared skills"),
+        ]
+        found_any = False
+        for source_root, kind_label, desc in skill_sources:
+            if source_root.exists():
+                found_any = True
+                self._import_skill_directory(source_root, kind_label, desc)
+        if not found_any:
+            destination_root = self.target_root / "skills" / SKILL_CATEGORY_DIRNAME
+            self.record("shared-skills", None, destination_root, "skipped", "No shared OpenClaw skills directories found")
+
+    def _import_skill_directory(self, source_root: Path, kind_label: str, desc: str) -> None:
+        """Import skills from a single source directory into openclaw-imports."""
        destination_root = self.target_root / "skills" / SKILL_CATEGORY_DIRNAME
-        if not source_root.exists():
-            self.record("shared-skills", None, destination_root, "skipped", "No shared OpenClaw skills directory found")
-            return

        skill_dirs = [p for p in sorted(source_root.iterdir()) if p.is_dir() and (p / "SKILL.md").exists()]
        if not skill_dirs:
-            self.record("shared-skills", source_root, destination_root, "skipped", "No shared skills with SKILL.md found")
+            self.record(kind_label, source_root, destination_root, "skipped", f"No skills with SKILL.md found in {desc}")
            return

        for skill_dir in skill_dirs:
@@ -1314,7 +1437,7 @@ class Migrator:
            final_destination = destination
            if destination.exists():
                if self.skill_conflict_mode == "skip":
-                    self.record("shared-skill", skill_dir, destination, "conflict", "Destination skill already exists")
+                    self.record(kind_label, skill_dir, destination, "conflict", "Destination skill already exists")
                    continue
                if self.skill_conflict_mode == "rename":
                    final_destination = self.resolve_skill_destination(destination)
@@ -1329,19 +1452,19 @@ class Migrator:
                details: Dict[str, Any] = {"backup": str(backup_path) if backup_path else ""}
                if final_destination != destination:
                    details["renamed_from"] = str(destination)
-                self.record("shared-skill", skill_dir, final_destination, "migrated", **details)
+                self.record(kind_label, skill_dir, final_destination, "migrated", **details)
            else:
                if final_destination != destination:
                    self.record(
-                        "shared-skill",
+                        kind_label,
                        skill_dir,
                        final_destination,
                        "migrated",
-                        "Would copy shared skill directory under a renamed folder",
+                        f"Would copy {desc} directory under a renamed folder",
                        renamed_from=str(destination),
                    )
                else:
-                    self.record("shared-skill", skill_dir, final_destination, "migrated", "Would copy shared skill directory")
+                    self.record(kind_label, skill_dir, final_destination, "migrated", f"Would copy {desc} directory")

        desc_path = destination_root / "DESCRIPTION.md"
        if self.execute:
@@ -1518,6 +1641,7 @@ class Migrator:
            self.source_candidate("workspace/IDENTITY.md", "workspace.default/IDENTITY.md"),
            self.source_candidate("workspace/TOOLS.md", "workspace.default/TOOLS.md"),
            self.source_candidate("workspace/HEARTBEAT.md", "workspace.default/HEARTBEAT.md"),
+            self.source_candidate("workspace/BOOTSTRAP.md", "workspace.default/BOOTSTRAP.md"),
        ]
        for candidate in candidates:
            if candidate:
@@ -1789,8 +1913,9 @@ class Migrator:
        human_delay = defaults.get("humanDelay") or {}
        if human_delay:
            hd = hermes_cfg.get("human_delay") or {}
-            if human_delay.get("enabled"):
-                hd["mode"] = "natural"
+            hd_mode = human_delay.get("mode") or ("natural" if human_delay.get("enabled") else None)
+            if hd_mode and hd_mode != "off":
+                hd["mode"] = hd_mode
            if human_delay.get("minMs"):
                hd["min_ms"] = human_delay["minMs"]
            if human_delay.get("maxMs"):
@@ -1804,11 +1929,11 @@ class Migrator:
            changes = True

        # Map terminal/exec settings
-        exec_cfg = defaults.get("exec") or (config.get("tools") or {}).get("exec") or {}
+        exec_cfg = (config.get("tools") or {}).get("exec") or {}
        if exec_cfg:
            terminal_cfg = hermes_cfg.get("terminal") or {}
-            if exec_cfg.get("timeout"):
-                terminal_cfg["timeout"] = exec_cfg["timeout"]
+            if exec_cfg.get("timeoutSec") or exec_cfg.get("timeout"):
+                terminal_cfg["timeout"] = exec_cfg.get("timeoutSec") or exec_cfg.get("timeout")
                changes = True
            hermes_cfg["terminal"] = terminal_cfg

@@ -1883,24 +2008,34 @@ class Migrator:
        sr = hermes_cfg.get("session_reset") or {}
        changes = False

-        reset_triggers = session.get("resetTriggers") or session.get("reset_triggers") or {}
-        if reset_triggers:
-            daily = reset_triggers.get("daily") or {}
-            idle = reset_triggers.get("idle") or {}
+        # OpenClaw uses session.reset (structured) and session.resetTriggers (string array)
+        reset = session.get("reset") or {}
+        reset_triggers = session.get("resetTriggers") or session.get("reset_triggers") or []

-            if daily.get("enabled") and idle.get("enabled"):
-                sr["mode"] = "both"
-            elif daily.get("enabled"):
+        if reset:
+            # Structured reset config: has mode, atHour, idleMinutes
+            mode = reset.get("mode", "")
+            if mode == "daily":
                sr["mode"] = "daily"
-            elif idle.get("enabled"):
+            elif mode == "idle":
                sr["mode"] = "idle"
            else:
-                sr["mode"] = "none"
-
-            if daily.get("hour") is not None:
-                sr["at_hour"] = daily["hour"]
-            if idle.get("minutes") or idle.get("timeoutMinutes"):
-                sr["idle_minutes"] = idle.get("minutes") or idle.get("timeoutMinutes")
+                sr["mode"] = mode or "none"
+            if reset.get("atHour") is not None:
+                sr["at_hour"] = reset["atHour"]
+            if reset.get("idleMinutes"):
+                sr["idle_minutes"] = reset["idleMinutes"]
+            changes = True
+        elif isinstance(reset_triggers, list) and reset_triggers:
+            # Simple string triggers: ["daily", "idle"]
+            has_daily = "daily" in reset_triggers
+            has_idle = "idle" in reset_triggers
+            if has_daily and has_idle:
+                sr["mode"] = "both"
+            elif has_daily:
+                sr["mode"] = "daily"
+            elif has_idle:
+                sr["mode"] = "idle"
            changes = True

        if changes:
@@ -2092,11 +2227,12 @@ class Migrator:
        browser_hermes = hermes_cfg.get("browser") or {}
        changed = False

-        if browser.get("inactivityTimeoutMs"):
-            browser_hermes["inactivity_timeout"] = browser["inactivityTimeoutMs"] // 1000
+        # Map fields that have Hermes equivalents
+        if browser.get("cdpUrl"):
+            browser_hermes["cdp_url"] = browser["cdpUrl"]
            changed = True
-        if browser.get("commandTimeoutMs"):
-            browser_hermes["command_timeout"] = browser["commandTimeoutMs"] // 1000
+        if browser.get("headless") is not None:
+            browser_hermes["headless"] = browser["headless"]
            changed = True

        if changed:
@@ -2107,9 +2243,9 @@ class Migrator:
            self.record("browser-config", "openclaw.json browser.*", "config.yaml browser",
                        "migrated")

-        # Archive advanced browser settings
+        # Archive remaining browser settings
        advanced = {k: v for k, v in browser.items()
-                   if k not in ("inactivityTimeoutMs", "commandTimeoutMs") and v}
+                   if k not in ("cdpUrl", "headless") and v}
        if advanced and self.archive_dir:
            if self.execute:
                self.archive_dir.mkdir(parents=True, exist_ok=True)
@@ -2130,18 +2266,22 @@ class Migrator:
        hermes_cfg = load_yaml_file(hermes_cfg_path)
        changed = False

-        # Map exec timeout -> terminal timeout
+        # Map exec timeout -> terminal timeout (field is timeoutSec in OpenClaw)
        exec_cfg = tools.get("exec") or {}
-        if exec_cfg.get("timeout"):
+        timeout_val = exec_cfg.get("timeoutSec") or exec_cfg.get("timeout")
+        if timeout_val:
            terminal_cfg = hermes_cfg.get("terminal") or {}
-            terminal_cfg["timeout"] = exec_cfg["timeout"]
+            terminal_cfg["timeout"] = timeout_val
            hermes_cfg["terminal"] = terminal_cfg
            changed = True

-        # Map web search API key
-        web_cfg = tools.get("webSearch") or tools.get("web") or {}
-        if web_cfg.get("braveApiKey") and self.migrate_secrets:
-            self._set_env_var("BRAVE_API_KEY", web_cfg["braveApiKey"], "tools.webSearch.braveApiKey")
+        # Map web search API key (path: tools.web.search.brave.apiKey in OpenClaw)
+        web_cfg = tools.get("web") or tools.get("webSearch") or {}
+        search_cfg = web_cfg.get("search") or web_cfg if not web_cfg.get("search") else web_cfg["search"]
+        brave_cfg = search_cfg.get("brave") or {}
+        brave_key = brave_cfg.get("apiKey") or search_cfg.get("braveApiKey") or web_cfg.get("braveApiKey")
+        if brave_key and isinstance(brave_key, str) and self.migrate_secrets:
+            self._set_env_var("BRAVE_API_KEY", brave_key, "tools.web.search.brave.apiKey")

        if changed and self.execute:
            self.maybe_backup(hermes_cfg_path)
@@ -2169,8 +2309,9 @@ class Migrator:
        hermes_cfg_path = self.target_root / "config.yaml"
        hermes_cfg = load_yaml_file(hermes_cfg_path)

-        # Map approval mode
-        mode = approvals.get("mode") or approvals.get("defaultMode")
+        # Map approval mode (nested under approvals.exec.mode in OpenClaw)
+        exec_approvals = approvals.get("exec") or {}
+        mode = (exec_approvals.get("mode") if isinstance(exec_approvals, dict) else None) or approvals.get("mode") or approvals.get("defaultMode")
        if mode:
            mode_map = {"auto": "off", "always": "manual", "smart": "smart", "manual": "manual"}
            hermes_mode = mode_map.get(mode, "manual")
@@ -0,0 +1,97 @@
+---
+name: canvas
+description: Canvas LMS integration — fetch enrolled courses and assignments using API token authentication.
+version: 1.0.0
+author: community
+license: MIT
+prerequisites:
+  env_vars: [CANVAS_API_TOKEN, CANVAS_BASE_URL]
+metadata:
+  hermes:
+    tags: [Canvas, LMS, Education, Courses, Assignments]
+---
+
+# Canvas LMS — Course & Assignment Access
+
+Read-only access to Canvas LMS for listing courses and assignments.
+
+## Scripts
+
+- `scripts/canvas_api.py` — Python CLI for Canvas API calls
+
+## Setup
+
+1. Log in to your Canvas instance in a browser
+2. Go to **Account → Settings** (click your profile icon, then Settings)
+3. Scroll to **Approved Integrations** and click **+ New Access Token**
+4. Name the token (e.g., "Hermes Agent"), set an optional expiry, and click **Generate Token**
+5. Copy the token and add to `~/.hermes/.env`:
+
+```
+CANVAS_API_TOKEN=your_token_here
+CANVAS_BASE_URL=https://yourschool.instructure.com
+```
+
+The base URL is whatever appears in your browser when you're logged into Canvas (no trailing slash).
+
+## Usage
+
+```bash
+CANVAS="python $HERMES_HOME/skills/productivity/canvas/scripts/canvas_api.py"
+
+# List all active courses
+$CANVAS list_courses --enrollment-state active
+
+# List all courses (any state)
+$CANVAS list_courses
+
+# List assignments for a specific course
+$CANVAS list_assignments 12345
+
+# List assignments ordered by due date
+$CANVAS list_assignments 12345 --order-by due_at
+```
+
+## Output Format
+
+**list_courses** returns:
+```json
+[{"id": 12345, "name": "Intro to CS", "course_code": "CS101", "workflow_state": "available", "start_at": "...", "end_at": "..."}]
+```
+
+**list_assignments** returns:
+```json
+[{"id": 67890, "name": "Homework 1", "due_at": "2025-02-15T23:59:00Z", "points_possible": 100, "submission_types": ["online_upload"], "html_url": "...", "description": "...", "course_id": 12345}]
+```
+
+Note: Assignment descriptions are truncated to 500 characters. The `html_url` field links to the full assignment page in Canvas.
+
+## API Reference (curl)
+
+```bash
+# List courses
+curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
+  "$CANVAS_BASE_URL/api/v1/courses?enrollment_state=active&per_page=10"
+
+# List assignments for a course
+curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
+  "$CANVAS_BASE_URL/api/v1/courses/COURSE_ID/assignments?per_page=10&order_by=due_at"
+```
+
+Canvas uses `Link` headers for pagination. The Python script handles pagination automatically.
+
+## Rules
+
+- This skill is **read-only** — it only fetches data, never modifies courses or assignments
+- On first use, verify auth by running `$CANVAS list_courses` — if it fails with 401, guide the user through setup
+- Canvas rate-limits to ~700 requests per 10 minutes; check `X-Rate-Limit-Remaining` header if hitting limits
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| 401 Unauthorized | Token invalid or expired — regenerate in Canvas Settings |
+| 403 Forbidden | Token lacks permission for this course |
+| Empty course list | Try `--enrollment-state active` or omit the flag to see all states |
+| Wrong institution | Verify `CANVAS_BASE_URL` matches the URL in your browser |
+| Timeout errors | Check network connectivity to your Canvas instance |
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Canvas LMS API CLI for Hermes Agent.
+
+A thin CLI wrapper around the Canvas REST API.
+Authenticates using a personal access token from environment variables.
+
+Usage:
+  python canvas_api.py list_courses [--per-page N] [--enrollment-state STATE]
+  python canvas_api.py list_assignments COURSE_ID [--per-page N] [--order-by FIELD]
+"""
+
+import argparse
+import json
+import os
+import sys
+
+import requests
+
+CANVAS_API_TOKEN = os.environ.get("CANVAS_API_TOKEN", "")
+CANVAS_BASE_URL = os.environ.get("CANVAS_BASE_URL", "").rstrip("/")
+
+
+def _check_config():
+    """Validate required environment variables are set."""
+    missing = []
+    if not CANVAS_API_TOKEN:
+        missing.append("CANVAS_API_TOKEN")
+    if not CANVAS_BASE_URL:
+        missing.append("CANVAS_BASE_URL")
+    if missing:
+        print(
+            f"Missing required environment variables: {', '.join(missing)}\n"
+            "Set them in ~/.hermes/.env or export them in your shell.\n"
+            "See the canvas skill SKILL.md for setup instructions.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+
+def _headers():
+    return {"Authorization": f"Bearer {CANVAS_API_TOKEN}"}
+
+
+def _paginated_get(url, params=None, max_items=200):
+    """Fetch all pages up to max_items, following Canvas Link headers."""
+    results = []
+    while url and len(results) < max_items:
+        resp = requests.get(url, headers=_headers(), params=params, timeout=30)
+        resp.raise_for_status()
+        results.extend(resp.json())
+        params = None  # params are included in the Link URL for subsequent pages
+        url = None
+        link = resp.headers.get("Link", "")
+        for part in link.split(","):
+            if 'rel="next"' in part:
+                url = part.split(";")[0].strip().strip("<>")
+    return results[:max_items]
+
+
+# =========================================================================
+# Commands
+# =========================================================================
+
+
+def list_courses(args):
+    """List enrolled courses."""
+    _check_config()
+    url = f"{CANVAS_BASE_URL}/api/v1/courses"
+    params = {"per_page": args.per_page}
+    if args.enrollment_state:
+        params["enrollment_state"] = args.enrollment_state
+    try:
+        courses = _paginated_get(url, params)
+    except requests.HTTPError as e:
+        print(f"API error: {e.response.status_code} {e.response.text}", file=sys.stderr)
+        sys.exit(1)
+    output = [
+        {
+            "id": c["id"],
+            "name": c.get("name", ""),
+            "course_code": c.get("course_code", ""),
+            "enrollment_term_id": c.get("enrollment_term_id"),
+            "start_at": c.get("start_at"),
+            "end_at": c.get("end_at"),
+            "workflow_state": c.get("workflow_state", ""),
+        }
+        for c in courses
+    ]
+    print(json.dumps(output, indent=2))
+
+
+def list_assignments(args):
+    """List assignments for a course."""
+    _check_config()
+    url = f"{CANVAS_BASE_URL}/api/v1/courses/{args.course_id}/assignments"
+    params = {"per_page": args.per_page}
+    if args.order_by:
+        params["order_by"] = args.order_by
+    try:
+        assignments = _paginated_get(url, params)
+    except requests.HTTPError as e:
+        print(f"API error: {e.response.status_code} {e.response.text}", file=sys.stderr)
+        sys.exit(1)
+    output = [
+        {
+            "id": a["id"],
+            "name": a.get("name", ""),
+            "description": (a.get("description") or "")[:500],
+            "due_at": a.get("due_at"),
+            "points_possible": a.get("points_possible"),
+            "submission_types": a.get("submission_types", []),
+            "html_url": a.get("html_url", ""),
+            "course_id": a.get("course_id"),
+        }
+        for a in assignments
+    ]
+    print(json.dumps(output, indent=2))
+
+
+# =========================================================================
+# CLI parser
+# =========================================================================
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Canvas LMS API CLI for Hermes Agent"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- list_courses ---
+    p = sub.add_parser("list_courses", help="List enrolled courses")
+    p.add_argument("--per-page", type=int, default=50, help="Results per page (default 50)")
+    p.add_argument(
+        "--enrollment-state",
+        default="",
+        help="Filter by enrollment state (active, invited_or_pending, completed)",
+    )
+    p.set_defaults(func=list_courses)
+
+    # --- list_assignments ---
+    p = sub.add_parser("list_assignments", help="List assignments for a course")
+    p.add_argument("course_id", help="Canvas course ID")
+    p.add_argument("--per-page", type=int, default=50, help="Results per page (default 50)")
+    p.add_argument(
+        "--order-by",
+        default="",
+        help="Order by field (due_at, name, position)",
+    )
+    p.set_defaults(func=list_assignments)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,324 @@
+---
+name: memento-flashcards
+description: >-
+  Spaced-repetition flashcard system. Create cards from facts or text,
+  chat with flashcards using free-text answers graded by the agent,
+  generate quizzes from YouTube transcripts, review due cards with
+  adaptive scheduling, and export/import decks as CSV.
+version: 1.0.0
+author: Memento AI
+license: MIT
+platforms: [macos, linux]
+metadata:
+  hermes:
+    tags: [Education, Flashcards, Spaced Repetition, Learning, Quiz, YouTube]
+    requires_toolsets: [terminal]
+    category: productivity
+---
+
+# Memento Flashcards — Spaced-Repetition Flashcard Skill
+
+## Overview
+
+Memento gives you a local, file-based flashcard system with spaced-repetition scheduling.
+Users can chat with their flashcards by answering in free text and having the agent grade the response before scheduling the next review.
+Use it whenever the user wants to:
+
+- **Remember a fact** — turn any statement into a Q/A flashcard
+- **Study with spaced repetition** — review due cards with adaptive intervals and agent-graded free-text answers
+- **Quiz from a YouTube video** — fetch a transcript and generate a 5-question quiz
+- **Manage decks** — organise cards into collections, export/import CSV
+
+All card data lives in a single JSON file. No external API keys are required — you (the agent) generate flashcard content and quiz questions directly.
+
+User-facing response style for Memento Flashcards:
+- Use plain text only. Do not use Markdown formatting in replies to the user.
+- Keep review and quiz feedback brief and neutral. Avoid extra praise, pep, or long explanations.
+
+## When to Use
+
+Use this skill when the user wants to:
+- Save facts as flashcards for later review
+- Review due cards with spaced repetition
+- Generate a quiz from a YouTube video transcript
+- Import, export, inspect, or delete flashcard data
+
+Do not use this skill for general Q&A, coding help, or non-memory tasks.
+
+## Quick Reference
+
+| User intent | Action |
+|---|---|
+| "Remember that X" / "save this as a flashcard" | Generate a Q/A card, call `memento_cards.py add` |
+| Sends a fact without mentioning flashcards | Ask "Want me to save this as a Memento flashcard?" — only create if confirmed |
+| "Create a flashcard" | Ask for Q, A, collection; call `memento_cards.py add` |
+| "Review my cards" | Call `memento_cards.py due`, present cards one-by-one |
+| "Quiz me on [YouTube URL]" | Call `youtube_quiz.py fetch VIDEO_ID`, generate 5 questions, call `memento_cards.py add-quiz` |
+| "Export my cards" | Call `memento_cards.py export --output PATH` |
+| "Import cards from CSV" | Call `memento_cards.py import --file PATH --collection NAME` |
+| "Show my stats" | Call `memento_cards.py stats` |
+| "Delete a card" | Call `memento_cards.py delete --id ID` |
+| "Delete a collection" | Call `memento_cards.py delete-collection --collection NAME` |
+
+## Card Storage
+
+Cards are stored in a JSON file at:
+
+```
+~/.hermes/skills/productivity/memento-flashcards/data/cards.json
+```
+
+**Never edit this file directly.** Always use `memento_cards.py` subcommands. The script handles atomic writes (write to temp file, then rename) to prevent corruption.
+
+The file is created automatically on first use.
+
+## Procedure
+
+### Creating Cards from Facts
+
+### Activation Rules
+
+Not every factual statement should become a flashcard. Use this three-tier check:
+
+1. **Explicit intent** — the user mentions "memento", "flashcard", "remember this", "save this card", "add a card", or similar phrasing that clearly requests a flashcard → **create the card directly**, no confirmation needed.
+2. **Implicit intent** — the user sends a factual statement without mentioning flashcards (e.g. "The speed of light is 299,792 km/s") → **ask first**: "Want me to save this as a Memento flashcard?" Only create the card if the user confirms.
+3. **No intent** — the message is a coding task, a question, instructions, normal conversation, or anything that is clearly not a fact to memorize → **do NOT activate this skill at all**. Let other skills or default behavior handle it.
+
+When activation is confirmed (tier 1 directly, tier 2 after confirmation), generate a flashcard:
+
+**Step 1:** Turn the statement into a Q/A pair. Use this format internally:
+
+```
+Turn the factual statement into a front-back pair.
+Return exactly two lines:
+Q: <question text>
+A: <answer text>
+
+Statement: "{statement}"
+```
+
+Rules:
+- The question should test recall of the key fact
+- The answer should be concise and direct
+
+**Step 2:** Call the script to store the card:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add \
+  --question "What year did World War 2 end?" \
+  --answer "1945" \
+  --collection "History"
+```
+
+If the user doesn't specify a collection, use `"General"` as the default.
+
+The script outputs JSON confirming the created card.
+
+### Manual Card Creation
+
+When the user explicitly asks to create a flashcard, ask them for:
+1. The question (front of card)
+2. The answer (back of card)
+3. The collection name (optional — default to `"General"`)
+
+Then call `memento_cards.py add` as above.
+
+### Reviewing Due Cards
+
+When the user wants to review, fetch all due cards:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
+```
+
+This returns a JSON array of cards where `next_review_at <= now`. If a collection filter is needed:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due --collection "History"
+```
+
+**Review flow (free-text grading):**
+
+Here is an example of the EXACT interaction pattern you must follow. The user answers, you grade them, tell them the correct answer, then rate the card.
+
+**Example interaction:**
+
+> **Agent:** What year did the Berlin Wall fall?
+>
+> **User:** 1991
+>
+> **Agent:** Not quite. The Berlin Wall fell in 1989. Next review is tomorrow.
+> *(agent calls: memento_cards.py rate --id ABC --rating hard --user-answer "1991")*
+>
+> Next question: Who was the first person to walk on the moon?
+
+**The rules:**
+
+1. Show only the question. Wait for the user to answer.
+2. After receiving their answer, compare it to the expected answer and grade it:
+   - **correct** → user got the key fact right (even if worded differently)
+   - **partial** → right track but missing the core detail
+   - **incorrect** → wrong or off-topic
+3. **You MUST tell the user the correct answer and how they did.** Keep it short and plain-text. Use this format:
+   - correct: "Correct. Answer: {answer}. Next review in 7 days."
+   - partial: "Close. Answer: {answer}. {what they missed}. Next review in 3 days."
+   - incorrect: "Not quite. Answer: {answer}. Next review tomorrow."
+4. Then call the rate command: correct→easy, partial→good, incorrect→hard.
+5. Then show the next question.
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
+  --id CARD_ID --rating easy --user-answer "what the user said"
+```
+
+**Never skip step 3.** The user must always see the correct answer and feedback before you move on.
+
+If no cards are due, tell the user: "No cards due for review right now. Check back later!"
+
+**Retire override:** At any point the user can say "retire this card" to permanently remove it from reviews. Use `--rating retire` for this.
+
+### Spaced Repetition Algorithm
+
+The rating determines the next review interval:
+
+| Rating | Interval | ease_streak | Status change |
+|---|---|---|---|
+| **hard** | +1 day | reset to 0 | stays learning |
+| **good** | +3 days | reset to 0 | stays learning |
+| **easy** | +7 days | +1 | if ease_streak >= 3 → retired |
+| **retire** | permanent | reset to 0 | → retired |
+
+- **learning**: card is actively in rotation
+- **retired**: card won't appear in reviews (user has mastered it or manually retired it)
+- Three consecutive "easy" ratings automatically retire a card
+
+### YouTube Quiz Generation
+
+When the user sends a YouTube URL and wants a quiz:
+
+**Step 1:** Extract the video ID from the URL (e.g. `dQw4w9WgXcQ` from `https://www.youtube.com/watch?v=dQw4w9WgXcQ`).
+
+**Step 2:** Fetch the transcript:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/youtube_quiz.py fetch VIDEO_ID
+```
+
+This returns `{"title": "...", "transcript": "..."}` or an error.
+
+If the script reports `missing_dependency`, tell the user to install it:
+```bash
+pip install youtube-transcript-api
+```
+
+**Step 3:** Generate 5 quiz questions from the transcript. Use these rules:
+
+```
+You are creating a 5-question quiz for a podcast episode.
+Return ONLY a JSON array with exactly 5 objects.
+Each object must contain keys 'question' and 'answer'.
+
+Selection criteria:
+- Prioritize important, surprising, or foundational facts.
+- Skip filler, obvious details, and facts that require heavy context.
+- Never return true/false questions.
+- Never ask only for a date.
+
+Question rules:
+- Each question must test exactly one discrete fact.
+- Use clear, unambiguous wording.
+- Prefer What, Who, How many, Which.
+- Avoid open-ended Describe or Explain prompts.
+
+Answer rules:
+- Each answer must be under 240 characters.
+- Lead with the answer itself, not preamble.
+- Add only minimal clarifying detail if needed.
+```
+
+Use the first 15,000 characters of the transcript as context. Generate the questions yourself (you are the LLM).
+
+**Step 4:** Validate the output is valid JSON with exactly 5 items, each having non-empty `question` and `answer` strings. If validation fails, retry once.
+
+**Step 5:** Store quiz cards:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add-quiz \
+  --video-id "VIDEO_ID" \
+  --questions '[{"question":"...","answer":"..."},...]' \
+  --collection "Quiz - Episode Title"
+```
+
+The script deduplicates by `video_id` — if cards for that video already exist, it skips creation and reports the existing cards.
+
+**Step 6:** Present questions one-by-one using the same free-text grading flow:
+1. Show "Question 1/5: ..." and wait for the user's answer. Never include the answer or any hint about revealing it.
+2. Wait for the user to answer in their own words
+3. Grade their answer using the grading prompt (see "Reviewing Due Cards" section)
+4. **IMPORTANT: You MUST reply to the user with feedback before doing anything else.** Show the grade, the correct answer, and when the card is next due. Do NOT silently skip to the next question. Keep it short and plain-text. Example: "Not quite. Answer: {answer}. Next review tomorrow."
+5. **After showing feedback**, call the rate command and then show the next question in the same message:
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
+  --id CARD_ID --rating easy --user-answer "what the user said"
+```
+6. Repeat. Every answer MUST receive visible feedback before the next question.
+
+### Export/Import CSV
+
+**Export:**
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py export \
+  --output ~/flashcards.csv
+```
+
+Produces a 3-column CSV: `question,answer,collection` (no header row).
+
+**Import:**
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py import \
+  --file ~/flashcards.csv \
+  --collection "Imported"
+```
+
+Reads a CSV with columns: question, answer, and optionally collection (column 3). If the collection column is missing, uses the `--collection` argument.
+
+### Statistics
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
+```
+
+Returns JSON with:
+- `total`: total card count
+- `learning`: cards in active rotation
+- `retired`: mastered cards
+- `due_now`: cards due for review right now
+- `collections`: breakdown by collection name
+
+## Pitfalls
+
+- **Never edit `cards.json` directly** — always use the script subcommands to avoid corruption
+- **Transcript failures** — some YouTube videos have no English transcript or have transcripts disabled; inform the user and suggest another video
+- **Optional dependency** — `youtube_quiz.py` needs `youtube-transcript-api`; if missing, tell the user to run `pip install youtube-transcript-api`
+- **Large imports** — CSV imports with thousands of rows work fine but the JSON output may be verbose; summarize the result for the user
+- **Video ID extraction** — support both `youtube.com/watch?v=ID` and `youtu.be/ID` URL formats
+
+## Verification
+
+Verify the helper scripts directly:
+
+```bash
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add --question "Capital of France?" --answer "Paris" --collection "General"
+python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
+```
+
+If you are testing from the repo checkout, run:
+
+```bash
+pytest tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q
+```
+
+Agent-level verification:
+- Start a review and confirm feedback is plain text, brief, and always includes the correct answer before the next card
+- Run a YouTube quiz flow and confirm each answer receives visible feedback before the next question
@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""Memento card storage, spaced-repetition engine, and CSV I/O.
+
+Stdlib-only. All output is JSON for agent parsing.
+Data file: $HERMES_HOME/skills/productivity/memento-flashcards/data/cards.json
+"""
+
+import argparse
+import csv
+import json
+import os
+import sys
+import tempfile
+import uuid
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+DATA_DIR = _HERMES_HOME / "skills" / "productivity" / "memento-flashcards" / "data"
+CARDS_FILE = DATA_DIR / "cards.json"
+
+RETIRED_SENTINEL = "9999-12-31T23:59:59+00:00"
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _iso(dt: datetime) -> str:
+    return dt.isoformat()
+
+
+def _parse_iso(s: str) -> datetime:
+    return datetime.fromisoformat(s)
+
+
+def _empty_store() -> dict:
+    return {"cards": [], "version": 1}
+
+
+def _load() -> dict:
+    if not CARDS_FILE.exists():
+        return _empty_store()
+    try:
+        with open(CARDS_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        if not isinstance(data, dict) or "cards" not in data:
+            return _empty_store()
+        return data
+    except (json.JSONDecodeError, OSError):
+        return _empty_store()
+
+
+def _save(data: dict) -> None:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=DATA_DIR, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+            f.write("\n")
+        os.replace(tmp, CARDS_FILE)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def _out(obj: object) -> None:
+    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+# ── Subcommands ──────────────────────────────────────────────────────────────
+
+def cmd_add(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    card = {
+        "id": str(uuid.uuid4()),
+        "question": args.question,
+        "answer": args.answer,
+        "collection": args.collection or "General",
+        "status": "learning",
+        "ease_streak": 0,
+        "next_review_at": _iso(now),
+        "created_at": _iso(now),
+        "video_id": None,
+        "last_user_answer": None,
+    }
+    data["cards"].append(card)
+    _save(data)
+    _out({"ok": True, "card": card})
+
+
+def cmd_add_quiz(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+
+    try:
+        questions = json.loads(args.questions)
+    except json.JSONDecodeError as exc:
+        _out({"ok": False, "error": f"Invalid JSON for --questions: {exc}"})
+        sys.exit(1)
+
+    # Dedup: skip if cards with this video_id already exist
+    existing_ids = {c["video_id"] for c in data["cards"] if c.get("video_id")}
+    if args.video_id in existing_ids:
+        existing = [c for c in data["cards"] if c.get("video_id") == args.video_id]
+        _out({"ok": True, "skipped": True, "reason": "duplicate_video_id", "existing_count": len(existing), "cards": existing})
+        return
+
+    created = []
+    for qa in questions:
+        card = {
+            "id": str(uuid.uuid4()),
+            "question": qa["question"],
+            "answer": qa["answer"],
+            "collection": args.collection or "Quiz",
+            "status": "learning",
+            "ease_streak": 0,
+            "next_review_at": _iso(now),
+            "created_at": _iso(now),
+            "video_id": args.video_id,
+            "last_user_answer": None,
+        }
+        data["cards"].append(card)
+        created.append(card)
+
+    _save(data)
+    _out({"ok": True, "created_count": len(created), "cards": created})
+
+
+def cmd_due(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    due = []
+    for card in data["cards"]:
+        if card["status"] == "retired":
+            continue
+        review_at = _parse_iso(card["next_review_at"])
+        if review_at <= now:
+            if args.collection and card["collection"] != args.collection:
+                continue
+            due.append(card)
+    _out({"ok": True, "count": len(due), "cards": due})
+
+
+def cmd_rate(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    card = None
+    for c in data["cards"]:
+        if c["id"] == args.id:
+            card = c
+            break
+    if not card:
+        _out({"ok": False, "error": f"Card not found: {args.id}"})
+        sys.exit(1)
+
+    rating = args.rating
+    user_answer = getattr(args, "user_answer", None)
+    if user_answer is not None:
+        card["last_user_answer"] = user_answer
+
+    if rating == "retire":
+        card["status"] = "retired"
+        card["next_review_at"] = RETIRED_SENTINEL
+        card["ease_streak"] = 0
+    elif rating == "hard":
+        card["next_review_at"] = _iso(now + timedelta(days=1))
+        card["ease_streak"] = 0
+    elif rating == "good":
+        card["next_review_at"] = _iso(now + timedelta(days=3))
+        card["ease_streak"] = 0
+    elif rating == "easy":
+        card["next_review_at"] = _iso(now + timedelta(days=7))
+        card["ease_streak"] = card.get("ease_streak", 0) + 1
+        if card["ease_streak"] >= 3:
+            card["status"] = "retired"
+
+    _save(data)
+    _out({"ok": True, "card": card})
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    data = _load()
+    cards = data["cards"]
+    if args.collection:
+        cards = [c for c in cards if c["collection"] == args.collection]
+    if args.status:
+        cards = [c for c in cards if c["status"] == args.status]
+    _out({"ok": True, "count": len(cards), "cards": cards})
+
+
+def cmd_stats(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    total = len(data["cards"])
+    learning = sum(1 for c in data["cards"] if c["status"] == "learning")
+    retired = sum(1 for c in data["cards"] if c["status"] == "retired")
+    due_now = 0
+    for c in data["cards"]:
+        if c["status"] != "retired" and _parse_iso(c["next_review_at"]) <= now:
+            due_now += 1
+
+    collections: dict[str, int] = {}
+    for c in data["cards"]:
+        name = c["collection"]
+        collections[name] = collections.get(name, 0) + 1
+
+    _out({
+        "ok": True,
+        "total": total,
+        "learning": learning,
+        "retired": retired,
+        "due_now": due_now,
+        "collections": collections,
+    })
+
+
+def cmd_export(args: argparse.Namespace) -> None:
+    data = _load()
+    output_path = Path(args.output).expanduser()
+    with open(output_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.writer(f, lineterminator="\n")
+        for card in data["cards"]:
+            writer.writerow([card["question"], card["answer"], card["collection"]])
+    _out({"ok": True, "exported": len(data["cards"]), "path": str(output_path)})
+
+
+def cmd_import(args: argparse.Namespace) -> None:
+    data = _load()
+    now = _now()
+    file_path = Path(args.file).expanduser()
+
+    if not file_path.exists():
+        _out({"ok": False, "error": f"File not found: {file_path}"})
+        sys.exit(1)
+
+    created = 0
+    with open(file_path, "r", encoding="utf-8") as f:
+        reader = csv.reader(f)
+        for row in reader:
+            if len(row) < 2:
+                continue
+            question = row[0].strip()
+            answer = row[1].strip()
+            collection = row[2].strip() if len(row) >= 3 and row[2].strip() else (args.collection or "Imported")
+            if not question or not answer:
+                continue
+            card = {
+                "id": str(uuid.uuid4()),
+                "question": question,
+                "answer": answer,
+                "collection": collection,
+                "status": "learning",
+                "ease_streak": 0,
+                "next_review_at": _iso(now),
+                "created_at": _iso(now),
+                "video_id": None,
+                "last_user_answer": None,
+            }
+            data["cards"].append(card)
+            created += 1
+
+    _save(data)
+    _out({"ok": True, "imported": created})
+
+
+def cmd_delete(args: argparse.Namespace) -> None:
+    data = _load()
+    original = len(data["cards"])
+    data["cards"] = [c for c in data["cards"] if c["id"] != args.id]
+    removed = original - len(data["cards"])
+    if removed == 0:
+        _out({"ok": False, "error": f"Card not found: {args.id}"})
+        sys.exit(1)
+    _save(data)
+    _out({"ok": True, "deleted": args.id})
+
+
+def cmd_delete_collection(args: argparse.Namespace) -> None:
+    data = _load()
+    original = len(data["cards"])
+    data["cards"] = [c for c in data["cards"] if c["collection"] != args.collection]
+    removed = original - len(data["cards"])
+    _save(data)
+    _out({"ok": True, "deleted_count": removed, "collection": args.collection})
+
+
+# ── CLI ──────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Memento flashcard manager")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_add = sub.add_parser("add", help="Create one card")
+    p_add.add_argument("--question", required=True)
+    p_add.add_argument("--answer", required=True)
+    p_add.add_argument("--collection", default="General")
+
+    p_quiz = sub.add_parser("add-quiz", help="Batch-add quiz cards")
+    p_quiz.add_argument("--video-id", required=True)
+    p_quiz.add_argument("--questions", required=True, help="JSON array of {question, answer}")
+    p_quiz.add_argument("--collection", default="Quiz")
+
+    p_due = sub.add_parser("due", help="List due cards")
+    p_due.add_argument("--collection", default=None)
+
+    p_rate = sub.add_parser("rate", help="Rate a card")
+    p_rate.add_argument("--id", required=True)
+    p_rate.add_argument("--rating", required=True, choices=["easy", "good", "hard", "retire"])
+    p_rate.add_argument("--user-answer", default=None)
+
+    p_list = sub.add_parser("list", help="List cards")
+    p_list.add_argument("--collection", default=None)
+    p_list.add_argument("--status", default=None, choices=["learning", "retired"])
+
+    sub.add_parser("stats", help="Show statistics")
+
+    p_export = sub.add_parser("export", help="Export cards to CSV")
+    p_export.add_argument("--output", required=True)
+
+    p_import = sub.add_parser("import", help="Import cards from CSV")
+    p_import.add_argument("--file", required=True)
+    p_import.add_argument("--collection", default="Imported")
+
+    p_del = sub.add_parser("delete", help="Delete one card")
+    p_del.add_argument("--id", required=True)
+
+    p_delcol = sub.add_parser("delete-collection", help="Delete all cards in a collection")
+    p_delcol.add_argument("--collection", required=True)
+
+    args = parser.parse_args()
+    cmd_map = {
+        "add": cmd_add,
+        "add-quiz": cmd_add_quiz,
+        "due": cmd_due,
+        "rate": cmd_rate,
+        "list": cmd_list,
+        "stats": cmd_stats,
+        "export": cmd_export,
+        "import": cmd_import,
+        "delete": cmd_delete,
+        "delete-collection": cmd_delete_collection,
+    }
+    cmd_map[args.command](args)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Fetch YouTube transcripts for Memento quiz generation.
+
+Requires: pip install youtube-transcript-api
+The quiz question *generation* is done by the agent's LLM — this script only fetches transcripts.
+"""
+
+import argparse
+import json
+import re
+import sys
+
+
+def _out(obj: object) -> None:
+    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def _normalize_segments(segments: list) -> str:
+    parts = []
+    for seg in segments:
+        text = str(seg.get("text", "")).strip()
+        if text:
+            parts.append(text)
+    return re.sub(r"\s+", " ", " ".join(parts)).strip()
+
+
+def cmd_fetch(args: argparse.Namespace) -> None:
+    try:
+        import youtube_transcript_api  # noqa: F811
+    except ImportError:
+        _out({
+            "ok": False,
+            "error": "missing_dependency",
+            "message": "Run: pip install youtube-transcript-api",
+        })
+        sys.exit(1)
+
+    video_id = args.video_id
+    languages = ["en", "en-US", "en-GB", "en-CA", "en-AU"]
+
+    api = youtube_transcript_api.YouTubeTranscriptApi()
+    try:
+        raw = api.fetch(video_id, languages=languages)
+    except Exception as exc:
+        error_type = type(exc).__name__
+        _out({
+            "ok": False,
+            "error": "transcript_unavailable",
+            "error_type": error_type,
+            "message": f"Could not fetch transcript for {video_id}: {exc}",
+        })
+        sys.exit(1)
+
+    segments = raw
+    if hasattr(raw, "to_raw_data"):
+        segments = raw.to_raw_data()
+
+    text = _normalize_segments(segments)
+    if not text:
+        _out({
+            "ok": False,
+            "error": "empty_transcript",
+            "message": f"Transcript for {video_id} contained no usable text.",
+        })
+        sys.exit(1)
+
+    _out({
+        "ok": True,
+        "video_id": video_id,
+        "transcript": text,
+    })
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Memento YouTube transcript fetcher")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_fetch = sub.add_parser("fetch", help="Fetch transcript for a video")
+    p_fetch.add_argument("video_id", help="YouTube video ID")
+
+    args = parser.parse_args()
+    if args.command == "fetch":
+        cmd_fetch(args)
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,297 @@
+---
+name: siyuan
+description: SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
+version: 1.0.0
+author: FEUAZUR
+license: MIT
+metadata:
+  hermes:
+    tags: [SiYuan, Notes, Knowledge Base, PKM, API]
+    related_skills: [obsidian, notion]
+    homepage: https://github.com/siyuan-note/siyuan
+prerequisites:
+  env_vars: [SIYUAN_TOKEN]
+  commands: [curl, jq]
+required_environment_variables:
+  - name: SIYUAN_TOKEN
+    prompt: SiYuan API token
+    help: "Settings > About in SiYuan desktop app"
+  - name: SIYUAN_URL
+    prompt: SiYuan instance URL (default http://127.0.0.1:6806)
+    required_for: remote instances
+---
+
+# SiYuan Note API
+
+Use the [SiYuan](https://github.com/siyuan-note/siyuan) kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed -- just curl and an API token.
+
+## Prerequisites
+
+1. Install and run SiYuan (desktop or Docker)
+2. Get your API token: **Settings > About > API token**
+3. Store it in `~/.hermes/.env`:
+   ```
+   SIYUAN_TOKEN=your_token_here
+   SIYUAN_URL=http://127.0.0.1:6806
+   ```
+   `SIYUAN_URL` defaults to `http://127.0.0.1:6806` if not set.
+
+## API Basics
+
+All SiYuan API calls are **POST with JSON body**. Every request follows this pattern:
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"param": "value"}'
+```
+
+Responses are JSON with this structure:
+```json
+{"code": 0, "msg": "", "data": { ... }}
+```
+`code: 0` means success. Any other value is an error -- check `msg` for details.
+
+**ID format:** SiYuan IDs look like `20210808180117-6v0mkxr` (14-digit timestamp + 7 alphanumeric chars).
+
+## Quick Reference
+
+| Operation | Endpoint |
+|-----------|----------|
+| Full-text search | `/api/search/fullTextSearchBlock` |
+| SQL query | `/api/query/sql` |
+| Read block | `/api/block/getBlockKramdown` |
+| Read children | `/api/block/getChildBlocks` |
+| Get path | `/api/filetree/getHPathByID` |
+| Get attributes | `/api/attr/getBlockAttrs` |
+| List notebooks | `/api/notebook/lsNotebooks` |
+| List documents | `/api/filetree/listDocsByPath` |
+| Create notebook | `/api/notebook/createNotebook` |
+| Create document | `/api/filetree/createDocWithMd` |
+| Append block | `/api/block/appendBlock` |
+| Update block | `/api/block/updateBlock` |
+| Rename document | `/api/filetree/renameDocByID` |
+| Set attributes | `/api/attr/setBlockAttrs` |
+| Delete block | `/api/block/deleteBlock` |
+| Delete document | `/api/filetree/removeDocByID` |
+| Export as Markdown | `/api/export/exportMdContent` |
+
+## Common Operations
+
+### Search (Full-Text)
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
+```
+
+### Search (SQL)
+
+Query the blocks database directly. Only SELECT statements are safe.
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'
+```
+
+Useful columns: `id`, `parent_id`, `root_id`, `box` (notebook ID), `path`, `content`, `type`, `subtype`, `created`, `updated`.
+
+### Read Block Content
+
+Returns block content in Kramdown (Markdown-like) format.
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
+```
+
+### Read Child Blocks
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### Get Human-Readable Path
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### Get Block Attributes
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
+```
+
+### List Notebooks
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'
+```
+
+### List Documents in a Notebook
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
+```
+
+### Create a Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "notebook": "NOTEBOOK_ID",
+    "path": "/Meeting Notes/2026-03-22",
+    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
+  }' | jq '.data'
+```
+
+### Create a Notebook
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
+```
+
+### Append Block to Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "parentID": "DOCUMENT_OR_BLOCK_ID",
+    "data": "New paragraph added at the end.",
+    "dataType": "markdown"
+  }' | jq '.data'
+```
+
+Also available: `/api/block/prependBlock` (same params, inserts at the beginning) and `/api/block/insertBlock` (uses `previousID` instead of `parentID` to insert after a specific block).
+
+### Update Block Content
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "BLOCK_ID",
+    "data": "Updated content here.",
+    "dataType": "markdown"
+  }' | jq '.data'
+```
+
+### Rename a Document
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'
+```
+
+### Set Block Attributes
+
+Custom attributes must be prefixed with `custom-`:
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "BLOCK_ID",
+    "attrs": {
+      "custom-status": "reviewed",
+      "custom-priority": "high"
+    }
+  }'
+```
+
+### Delete a Block
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "BLOCK_ID"}'
+```
+
+To delete a whole document: use `/api/filetree/removeDocByID` with `{"id": "DOC_ID"}`.
+To delete a notebook: use `/api/notebook/removeNotebook` with `{"notebook": "NOTEBOOK_ID"}`.
+
+### Export Document as Markdown
+
+```bash
+curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
+  -H "Authorization: Token $SIYUAN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'
+```
+
+## Block Types
+
+Common `type` values in SQL queries:
+
+| Type | Description |
+|------|-------------|
+| `d` | Document (root block) |
+| `p` | Paragraph |
+| `h` | Heading |
+| `l` | List |
+| `i` | List item |
+| `c` | Code block |
+| `m` | Math block |
+| `t` | Table |
+| `b` | Blockquote |
+| `s` | Super block |
+| `html` | HTML block |
+
+## Pitfalls
+
+- **All endpoints are POST** -- even read-only operations. Do not use GET.
+- **SQL safety**: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
+- **ID validation**: IDs match the pattern `YYYYMMDDHHmmss-xxxxxxx`. Reject anything else.
+- **Error responses**: always check `code != 0` in responses before processing `data`.
+- **Large documents**: block content and export results can be very large. Use `LIMIT` in SQL and pipe through `jq` to extract only what you need.
+- **Notebook IDs**: when working with a specific notebook, get its ID first via `lsNotebooks`.
+
+## Alternative: MCP Server
+
+If you prefer a native integration instead of curl, install the SiYuan MCP server:
+
+```yaml
+# In ~/.hermes/config.yaml under mcp_servers:
+mcp_servers:
+  siyuan:
+    command: npx
+    args: ["-y", "@porkll/siyuan-mcp"]
+    env:
+      SIYUAN_TOKEN: "your_token"
+      SIYUAN_URL: "http://127.0.0.1:6806"
+```
@@ -0,0 +1,335 @@
+---
+name: scrapling
+description: Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python.
+version: 1.0.0
+author: FEUAZUR
+license: MIT
+metadata:
+  hermes:
+    tags: [Web Scraping, Browser, Cloudflare, Stealth, Crawling, Spider]
+    related_skills: [duckduckgo-search, domain-intel]
+    homepage: https://github.com/D4Vinci/Scrapling
+prerequisites:
+  commands: [scrapling, python]
+---
+
+# Scrapling
+
+[Scrapling](https://github.com/D4Vinci/Scrapling) is a web scraping framework with anti-bot bypass, stealth browser automation, and a spider framework. It provides three fetching strategies (HTTP, dynamic JS, stealth/Cloudflare) and a full CLI.
+
+**This skill is for educational and research purposes only.** Users must comply with local/international data scraping laws and respect website Terms of Service.
+
+## When to Use
+
+- Scraping static HTML pages (faster than browser tools)
+- Scraping JS-rendered pages that need a real browser
+- Bypassing Cloudflare Turnstile or bot detection
+- Crawling multiple pages with a spider
+- When the built-in `web_extract` tool does not return the data you need
+
+## Installation
+
+```bash
+pip install "scrapling[all]"
+scrapling install
+```
+
+Minimal install (HTTP only, no browser):
+```bash
+pip install scrapling
+```
+
+With browser automation only:
+```bash
+pip install "scrapling[fetchers]"
+scrapling install
+```
+
+## Quick Reference
+
+| Approach | Class | Use When |
+|----------|-------|----------|
+| HTTP | `Fetcher` / `FetcherSession` | Static pages, APIs, fast bulk requests |
+| Dynamic | `DynamicFetcher` / `DynamicSession` | JS-rendered content, SPAs |
+| Stealth | `StealthyFetcher` / `StealthySession` | Cloudflare, anti-bot protected sites |
+| Spider | `Spider` | Multi-page crawling with link following |
+
+## CLI Usage
+
+### Extract Static Page
+
+```bash
+scrapling extract get 'https://example.com' output.md
+```
+
+With CSS selector and browser impersonation:
+
+```bash
+scrapling extract get 'https://example.com' output.md \
+  --css-selector '.content' \
+  --impersonate 'chrome'
+```
+
+### Extract JS-Rendered Page
+
+```bash
+scrapling extract fetch 'https://example.com' output.md \
+  --css-selector '.dynamic-content' \
+  --disable-resources \
+  --network-idle
+```
+
+### Extract Cloudflare-Protected Page
+
+```bash
+scrapling extract stealthy-fetch 'https://protected-site.com' output.html \
+  --solve-cloudflare \
+  --block-webrtc \
+  --hide-canvas
+```
+
+### POST Request
+
+```bash
+scrapling extract post 'https://example.com/api' output.json \
+  --json '{"query": "search term"}'
+```
+
+### Output Formats
+
+The output format is determined by the file extension:
+- `.html` -- raw HTML
+- `.md` -- converted to Markdown
+- `.txt` -- plain text
+- `.json` / `.jsonl` -- JSON
+
+## Python: HTTP Scraping
+
+### Single Request
+
+```python
+from scrapling.fetchers import Fetcher
+
+page = Fetcher.get('https://quotes.toscrape.com/')
+quotes = page.css('.quote .text::text').getall()
+for q in quotes:
+    print(q)
+```
+
+### Session (Persistent Cookies)
+
+```python
+from scrapling.fetchers import FetcherSession
+
+with FetcherSession(impersonate='chrome') as session:
+    page = session.get('https://example.com/', stealthy_headers=True)
+    links = page.css('a::attr(href)').getall()
+    for link in links[:5]:
+        sub = session.get(link)
+        print(sub.css('h1::text').get())
+```
+
+### POST / PUT / DELETE
+
+```python
+page = Fetcher.post('https://api.example.com/data', json={"key": "value"})
+page = Fetcher.put('https://api.example.com/item/1', data={"name": "updated"})
+page = Fetcher.delete('https://api.example.com/item/1')
+```
+
+### With Proxy
+
+```python
+page = Fetcher.get('https://example.com', proxy='http://user:pass@proxy:8080')
+```
+
+## Python: Dynamic Pages (JS-Rendered)
+
+For pages that require JavaScript execution (SPAs, lazy-loaded content):
+
+```python
+from scrapling.fetchers import DynamicFetcher
+
+page = DynamicFetcher.fetch('https://example.com', headless=True)
+data = page.css('.js-loaded-content::text').getall()
+```
+
+### Wait for Specific Element
+
+```python
+page = DynamicFetcher.fetch(
+    'https://example.com',
+    wait_selector=('.results', 'visible'),
+    network_idle=True,
+)
+```
+
+### Disable Resources for Speed
+
+Blocks fonts, images, media, stylesheets (~25% faster):
+
+```python
+from scrapling.fetchers import DynamicSession
+
+with DynamicSession(headless=True, disable_resources=True, network_idle=True) as session:
+    page = session.fetch('https://example.com')
+    items = page.css('.item::text').getall()
+```
+
+### Custom Page Automation
+
+```python
+from playwright.sync_api import Page
+from scrapling.fetchers import DynamicFetcher
+
+def scroll_and_click(page: Page):
+    page.mouse.wheel(0, 3000)
+    page.wait_for_timeout(1000)
+    page.click('button.load-more')
+    page.wait_for_selector('.extra-results')
+
+page = DynamicFetcher.fetch('https://example.com', page_action=scroll_and_click)
+results = page.css('.extra-results .item::text').getall()
+```
+
+## Python: Stealth Mode (Anti-Bot Bypass)
+
+For Cloudflare-protected or heavily fingerprinted sites:
+
+```python
+from scrapling.fetchers import StealthyFetcher
+
+page = StealthyFetcher.fetch(
+    'https://protected-site.com',
+    headless=True,
+    solve_cloudflare=True,
+    block_webrtc=True,
+    hide_canvas=True,
+)
+content = page.css('.protected-content::text').getall()
+```
+
+### Stealth Session
+
+```python
+from scrapling.fetchers import StealthySession
+
+with StealthySession(headless=True, solve_cloudflare=True) as session:
+    page1 = session.fetch('https://protected-site.com/page1')
+    page2 = session.fetch('https://protected-site.com/page2')
+```
+
+## Element Selection
+
+All fetchers return a `Selector` object with these methods:
+
+### CSS Selectors
+
+```python
+page.css('h1::text').get()              # First h1 text
+page.css('a::attr(href)').getall()      # All link hrefs
+page.css('.quote .text::text').getall() # Nested selection
+```
+
+### XPath
+
+```python
+page.xpath('//div[@class="content"]/text()').getall()
+page.xpath('//a/@href').getall()
+```
+
+### Find Methods
+
+```python
+page.find_all('div', class_='quote')       # By tag + attribute
+page.find_by_text('Read more', tag='a')    # By text content
+page.find_by_regex(r'\$\d+\.\d{2}')       # By regex pattern
+```
+
+### Similar Elements
+
+Find elements with similar structure (useful for product listings, etc.):
+
+```python
+first_product = page.css('.product')[0]
+all_similar = first_product.find_similar()
+```
+
+### Navigation
+
+```python
+el = page.css('.target')[0]
+el.parent                # Parent element
+el.children              # Child elements
+el.next_sibling          # Next sibling
+el.prev_sibling          # Previous sibling
+```
+
+## Python: Spider Framework
+
+For multi-page crawling with link following:
+
+```python
+from scrapling.spiders import Spider, Request, Response
+
+class QuotesSpider(Spider):
+    name = "quotes"
+    start_urls = ["https://quotes.toscrape.com/"]
+    concurrent_requests = 10
+    download_delay = 1
+
+    async def parse(self, response: Response):
+        for quote in response.css('.quote'):
+            yield {
+                "text": quote.css('.text::text').get(),
+                "author": quote.css('.author::text').get(),
+                "tags": quote.css('.tag::text').getall(),
+            }
+
+        next_page = response.css('.next a::attr(href)').get()
+        if next_page:
+            yield response.follow(next_page)
+
+result = QuotesSpider().start()
+print(f"Scraped {len(result.items)} quotes")
+result.items.to_json("quotes.json")
+```
+
+### Multi-Session Spider
+
+Route requests to different fetcher types:
+
+```python
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
+
+class SmartSpider(Spider):
+    name = "smart"
+    start_urls = ["https://example.com/"]
+
+    def configure_sessions(self, manager):
+        manager.add("fast", FetcherSession(impersonate="chrome"))
+        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)
+
+    async def parse(self, response: Response):
+        for link in response.css('a::attr(href)').getall():
+            if "protected" in link:
+                yield Request(link, sid="stealth")
+            else:
+                yield Request(link, sid="fast", callback=self.parse)
+```
+
+### Pause/Resume Crawling
+
+```python
+spider = QuotesSpider(crawldir="./crawl_checkpoint")
+spider.start()  # Ctrl+C to pause, re-run to resume from checkpoint
+```
+
+## Pitfalls
+
+- **Browser install required**: run `scrapling install` after pip install -- without it, `DynamicFetcher` and `StealthyFetcher` will fail
+- **Timeouts**: DynamicFetcher/StealthyFetcher timeout is in **milliseconds** (default 30000), Fetcher timeout is in **seconds**
+- **Cloudflare bypass**: `solve_cloudflare=True` adds 5-15 seconds to fetch time -- only enable when needed
+- **Resource usage**: StealthyFetcher runs a real browser -- limit concurrent usage
+- **Legal**: always check robots.txt and website ToS before scraping. This library is for educational and research purposes
+- **Python version**: requires Python 3.10+
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

 [project]
 name = "hermes-agent"
-version = "0.5.0"
+version = "0.6.0"
 description = "The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -58,6 +58,7 @@ homeassistant = ["aiohttp>=3.9.0,<4"]
 sms = ["aiohttp>=3.9.0,<4"]
 acp = ["agent-client-protocol>=0.8.1,<0.9"]
 dingtalk = ["dingtalk-stream>=0.1.0,<1"]
+feishu = ["lark-oapi>=1.5.3,<2"]
 rl = [
  "atroposlib @ git+https://github.com/NousResearch/atropos.git",
  "tinker @ git+https://github.com/thinking-machines-lab/tinker.git",
@@ -70,6 +71,7 @@ all = [
  "hermes-agent[modal]",
  "hermes-agent[daytona]",
  "hermes-agent[messaging]",
+  "hermes-agent[matrix]",
  "hermes-agent[cron]",
  "hermes-agent[cli]",
  "hermes-agent[dev]",
@@ -83,6 +85,7 @@ all = [
  "hermes-agent[acp]",
  "hermes-agent[voice]",
  "hermes-agent[dingtalk]",
+  "hermes-agent[feishu]",
 ]

 [project.scripts]
@@ -896,16 +896,30 @@ 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
+        # Provider fallback chain — ordered list of backup providers tried
+        # when the primary is exhausted (rate-limit, overload, connection
+        # failure).  Supports both legacy single-dict ``fallback_model`` and
+        # new list ``fallback_providers`` format.
+        if isinstance(fallback_model, list):
+            self._fallback_chain = [
+                f for f in fallback_model
+                if isinstance(f, dict) and f.get("provider") and f.get("model")
+            ]
+        elif isinstance(fallback_model, dict) and fallback_model.get("provider") and fallback_model.get("model"):
+            self._fallback_chain = [fallback_model]
+        else:
+            self._fallback_chain = []
+        self._fallback_index = 0
        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})")
+        # Legacy attribute kept for backward compat (tests, external callers)
+        self._fallback_model = self._fallback_chain[0] if self._fallback_chain else None
+        if self._fallback_chain and not self.quiet_mode:
+            if len(self._fallback_chain) == 1:
+                fb = self._fallback_chain[0]
+                print(f"🔄 Fallback model: {fb['model']} ({fb['provider']})")
+            else:
+                print(f"🔄 Fallback chain ({len(self._fallback_chain)} providers): " +
+                      " → ".join(f"{f['model']} ({f['provider']})" for f in self._fallback_chain))

        # Get available tools with filtering
        self.tools = get_tool_definitions(
@@ -1271,7 +1285,7 @@ class AIAgent:
        try:
            fn = self._print_fn or print
            fn(*args, **kwargs)
-        except OSError:
+        except (OSError, ValueError):
            pass

    def _vprint(self, *args, force: bool = False, **kwargs):
@@ -4318,25 +4332,26 @@ class AIAgent:
    # ── Provider fallback ──────────────────────────────────────────────────

    def _try_activate_fallback(self) -> bool:
-        """Switch to the configured fallback model/provider.
+        """Switch to the next fallback model/provider in the chain.

-        Called when the primary model is failing after retries.  Swaps the
+        Called when the current 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.
+        can continue with the new backend.  Advances through the chain on
+        each call; returns False when exhausted.

        Uses the centralized provider router (resolve_provider_client) for
        auth resolution and client construction — no duplicated provider→key
        mappings.
        """
-        if self._fallback_activated or not self._fallback_model:
+        if self._fallback_index >= len(self._fallback_chain):
            return False

-        fb = self._fallback_model
+        fb = self._fallback_chain[self._fallback_index]
+        self._fallback_index += 1
        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
+            return self._try_activate_fallback()  # skip invalid, try next

        # Use centralized router for client construction.
        # raw_codex=True because the main agent needs direct responses.stream()
@@ -4349,7 +4364,7 @@ class AIAgent:
                logging.warning(
                    "Fallback to %s failed: provider not configured",
                    fb_provider)
-                return False
+                return self._try_activate_fallback()  # try next in chain

            # Determine api_mode from provider / base URL
            fb_api_mode = "chat_completions"
@@ -4424,8 +4439,8 @@ class AIAgent:
            )
            return True
        except Exception as e:
-            logging.error("Failed to activate fallback model: %s", e)
-            return False
+            logging.error("Failed to activate fallback %s: %s", fb_model, e)
+            return self._try_activate_fallback()  # try next in chain

    # ── End provider fallback ──────────────────────────────────────────────

@@ -4706,9 +4721,10 @@ class AIAgent:
        api_kwargs = {
            "model": self.model,
            "messages": sanitized_messages,
-            "tools": self.tools if self.tools else None,
            "timeout": float(os.getenv("HERMES_API_TIMEOUT", 1800.0)),
        }
+        if self.tools:
+            api_kwargs["tools"] = self.tools

        if self.max_tokens is not None:
            api_kwargs.update(self._max_tokens_param(self.max_tokens))
@@ -5167,6 +5183,8 @@ class AIAgent:
                self._session_db.end_session(self.session_id, "compression")
                old_session_id = self.session_id
                self.session_id = f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{uuid.uuid4().hex[:6]}"
+                # Update session_log_file to point to the new session's JSON file
+                self.session_log_file = self.logs_dir / f"session_{self.session_id}.json"
                self._session_db.create_session(
                    session_id=self.session_id,
                    source=self.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
@@ -5186,11 +5204,8 @@ class AIAgent:
            except Exception as e:
                logger.warning("Session DB compression split failed — new session will NOT be indexed: %s", e)

-        # Reset context pressure warning and token estimate — usage drops
-        # after compaction.  Without this, the stale last_prompt_tokens from
-        # the previous API call causes the pressure calculation to stay at
-        # >1000% and spam warnings / re-trigger compression in a loop.
-        self._context_pressure_warned = False
+        # Update token estimate after compaction so pressure calculations
+        # use the post-compression count, not the stale pre-compression one.
        _compressed_est = (
            estimate_tokens_rough(new_system_prompt)
            + estimate_messages_tokens_rough(compressed)
@@ -5198,6 +5213,16 @@ class AIAgent:
        self.context_compressor.last_prompt_tokens = _compressed_est
        self.context_compressor.last_completion_tokens = 0

+        # Only reset the pressure warning if compression actually brought
+        # us below the warning level (85% of threshold).  When compression
+        # can't reduce enough (e.g. threshold is very low, or system prompt
+        # alone exceeds the warning level), keep the flag set to prevent
+        # spamming the user with repeated warnings every loop iteration.
+        if self.context_compressor.threshold_tokens > 0:
+            _post_progress = _compressed_est / self.context_compressor.threshold_tokens
+            if _post_progress < 0.85:
+                self._context_pressure_warned = False
+
        return compressed, new_system_prompt

    def _execute_tool_calls(self, assistant_message, messages: list, effective_task_id: str, api_call_count: int = 0) -> None:
@@ -5644,8 +5669,6 @@ class AIAgent:
                    face = random.choice(KawaiiSpinner.KAWAII_WAITING)
                    emoji = _get_tool_emoji(function_name)
                    preview = _build_tool_preview(function_name, function_args) or function_name
-                    if len(preview) > 30:
-                        preview = preview[:27] + "..."
                    spinner = KawaiiSpinner(f"{face} {emoji} {preview}", spinner_type='dots', print_fn=self._print_fn)
                    spinner.start()
                _spinner_result = None
@@ -6528,9 +6551,9 @@ class AIAgent:
                        # Eager fallback: empty/malformed responses are a common
                        # rate-limit symptom.  Switch to fallback immediately
                        # rather than retrying with extended backoff.
-                        if not self._fallback_activated:
+                        if self._fallback_index < len(self._fallback_chain):
                            self._emit_status("⚠️ Empty/malformed response — switching to fallback...")
-                        if not self._fallback_activated and self._try_activate_fallback():
+                        if self._try_activate_fallback():
                            retry_count = 0
                            continue

@@ -6924,8 +6947,10 @@ class AIAgent:
                        print(f"{self.log_prefix}   Auth method: {auth_method}")
                        print(f"{self.log_prefix}   Token prefix: {key[:12]}..." if key and len(key) > 12 else f"{self.log_prefix}   Token: (empty or short)")
                        print(f"{self.log_prefix}   Troubleshooting:")
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in ~/.hermes/.env for Hermes-managed OAuth/setup tokens")
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in ~/.hermes/.env for API keys or legacy token values")
+                        from hermes_constants import display_hermes_home as _dhh_fn
+                        _dhh = _dhh_fn()
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in {_dhh}/.env for Hermes-managed OAuth/setup tokens")
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in {_dhh}/.env for API keys or legacy token values")
                        print(f"{self.log_prefix}     • For API keys: verify at https://console.anthropic.com/settings/keys")
                        print(f"{self.log_prefix}     • For Claude Code: run 'claude /login' to refresh, then retry")
                        print(f"{self.log_prefix}     • Clear stale keys: hermes config set ANTHROPIC_TOKEN \"\"")
@@ -6991,7 +7016,7 @@ class AIAgent:
                        or "usage limit" in error_msg
                        or "quota" in error_msg
                    )
-                    if is_rate_limited and not self._fallback_activated:
+                    if is_rate_limited and self._fallback_index < len(self._fallback_chain):
                        self._emit_status("⚠️ Rate limited — switching to fallback provider...")
                        if self._try_activate_fallback():
                            retry_count = 0
@@ -7227,7 +7252,10 @@ class AIAgent:
                            retry_count = 0
                            continue
                        _final_summary = self._summarize_api_error(api_error)
-                        self._vprint(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded. Giving up.", force=True)
+                        if is_rate_limited:
+                            self._vprint(f"{self.log_prefix}❌ Rate limit persisted after {max_retries} retries. Please try again later.", force=True)
+                        else:
+                            self._vprint(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded. Giving up.", force=True)
                        self._vprint(f"{self.log_prefix}   💀 Final error: {_final_summary}", force=True)

                        # Detect SSE stream-drop pattern (e.g. "Network
@@ -7287,8 +7315,22 @@ class AIAgent:
                            "error": _final_summary,
                        }

-                    wait_time = min(2 ** retry_count, 60)  # Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s, 60s
-                    self._emit_status(f"⏳ Retrying in {wait_time}s (attempt {retry_count}/{max_retries})...")
+                    # For rate limits, respect the Retry-After header if present
+                    _retry_after = None
+                    if is_rate_limited:
+                        _resp_headers = getattr(getattr(api_error, "response", None), "headers", None)
+                        if _resp_headers and hasattr(_resp_headers, "get"):
+                            _ra_raw = _resp_headers.get("retry-after") or _resp_headers.get("Retry-After")
+                            if _ra_raw:
+                                try:
+                                    _retry_after = min(int(_ra_raw), 120)  # Cap at 2 minutes
+                                except (TypeError, ValueError):
+                                    pass
+                    wait_time = _retry_after if _retry_after else min(2 ** retry_count, 60)
+                    if is_rate_limited:
+                        self._emit_status(f"⏱️ Rate limit reached. Waiting {wait_time}s before retry (attempt {retry_count + 1}/{max_retries})...")
+                    else:
+                        self._emit_status(f"⏳ Retrying in {wait_time}s (attempt {retry_count}/{max_retries})...")
                    logger.warning(
                        "Retrying API call in %ss (attempt %s/%s) %s error=%s",
                        wait_time,
@@ -7874,7 +7916,7 @@ class AIAgent:
                error_msg = f"Error during OpenAI-compatible API call #{api_call_count}: {str(e)}"
                try:
                    print(f"❌ {error_msg}")
-                except OSError:
+                except (OSError, ValueError):
                    logger.error(error_msg)
                
                if self.verbose_logging:
@@ -0,0 +1,79 @@
+import path from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+export function normalizeWhatsAppIdentifier(value) {
+  return String(value || '')
+    .trim()
+    .replace(/:.*@/, '@')
+    .replace(/@.*/, '')
+    .replace(/^\+/, '');
+}
+
+export function parseAllowedUsers(rawValue) {
+  return new Set(
+    String(rawValue || '')
+      .split(',')
+      .map((value) => normalizeWhatsAppIdentifier(value))
+      .filter(Boolean)
+  );
+}
+
+function readMappingFile(sessionDir, identifier, suffix = '') {
+  const filePath = path.join(sessionDir, `lid-mapping-${identifier}${suffix}.json`);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    const normalized = normalizeWhatsAppIdentifier(parsed);
+    return normalized || null;
+  } catch {
+    return null;
+  }
+}
+
+export function expandWhatsAppIdentifiers(identifier, sessionDir) {
+  const normalized = normalizeWhatsAppIdentifier(identifier);
+  if (!normalized) {
+    return new Set();
+  }
+
+  // Walk both phone->LID and LID->phone mapping files so allowlists can use
+  // either form transparently in bot mode.
+  const resolved = new Set();
+  const queue = [normalized];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || resolved.has(current)) {
+      continue;
+    }
+
+    resolved.add(current);
+
+    for (const suffix of ['', '_reverse']) {
+      const mapped = readMappingFile(sessionDir, current, suffix);
+      if (mapped && !resolved.has(mapped)) {
+        queue.push(mapped);
+      }
+    }
+  }
+
+  return resolved;
+}
+
+export function matchesAllowedUser(senderId, allowedUsers, sessionDir) {
+  if (!allowedUsers || allowedUsers.size === 0) {
+    return true;
+  }
+
+  const aliases = expandWhatsAppIdentifiers(senderId, sessionDir);
+  for (const alias of aliases) {
+    if (allowedUsers.has(alias)) {
+      return true;
+    }
+  }
+
+  return false;
+}
@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+
+import {
+  expandWhatsAppIdentifiers,
+  matchesAllowedUser,
+  normalizeWhatsAppIdentifier,
+  parseAllowedUsers,
+} from './allowlist.js';
+
+test('normalizeWhatsAppIdentifier strips jid syntax and plus prefix', () => {
+  assert.equal(normalizeWhatsAppIdentifier('+19175395595@s.whatsapp.net'), '19175395595');
+  assert.equal(normalizeWhatsAppIdentifier('267383306489914@lid'), '267383306489914');
+  assert.equal(normalizeWhatsAppIdentifier('19175395595:12@s.whatsapp.net'), '19175395595');
+});
+
+test('expandWhatsAppIdentifiers resolves phone and lid aliases from session files', () => {
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    writeFileSync(path.join(sessionDir, 'lid-mapping-19175395595.json'), JSON.stringify('267383306489914'));
+    writeFileSync(path.join(sessionDir, 'lid-mapping-267383306489914_reverse.json'), JSON.stringify('19175395595'));
+
+    const aliases = expandWhatsAppIdentifiers('267383306489914@lid', sessionDir);
+    assert.deepEqual([...aliases].sort(), ['19175395595', '267383306489914']);
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
+
+test('matchesAllowedUser accepts mapped lid sender when allowlist only contains phone number', () => {
+  const sessionDir = mkdtempSync(path.join(os.tmpdir(), 'hermes-wa-allowlist-'));
+
+  try {
+    writeFileSync(path.join(sessionDir, 'lid-mapping-19175395595.json'), JSON.stringify('267383306489914'));
+    writeFileSync(path.join(sessionDir, 'lid-mapping-267383306489914_reverse.json'), JSON.stringify('19175395595'));
+
+    const allowedUsers = parseAllowedUsers('+19175395595');
+    assert.equal(matchesAllowedUser('267383306489914@lid', allowedUsers, sessionDir), true);
+    assert.equal(matchesAllowedUser('188012763865257@lid', allowedUsers, sessionDir), false);
+  } finally {
+    rmSync(sessionDir, { recursive: true, force: true });
+  }
+});
@@ -26,6 +26,7 @@ import path from 'path';
 import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync } from 'fs';
 import { randomBytes } from 'crypto';
 import qrcode from 'qrcode-terminal';
+import { matchesAllowedUser, parseAllowedUsers } from './allowlist.js';

 // Parse CLI args
 const args = process.argv.slice(2);
@@ -47,13 +48,17 @@ const DOCUMENT_CACHE_DIR = path.join(process.env.HOME || '~', '.hermes', 'docume
 const AUDIO_CACHE_DIR = path.join(process.env.HOME || '~', '.hermes', 'audio_cache');
 const PAIR_ONLY = args.includes('--pair-only');
 const WHATSAPP_MODE = getArg('mode', process.env.WHATSAPP_MODE || 'self-chat'); // "bot" or "self-chat"
-const ALLOWED_USERS = (process.env.WHATSAPP_ALLOWED_USERS || '').split(',').map(s => s.trim()).filter(Boolean);
+const ALLOWED_USERS = parseAllowedUsers(process.env.WHATSAPP_ALLOWED_USERS || '');
 const DEFAULT_REPLY_PREFIX = '⚕ *Hermes Agent*\n────────────\n';
 const REPLY_PREFIX = process.env.WHATSAPP_REPLY_PREFIX === undefined
  ? DEFAULT_REPLY_PREFIX
  : process.env.WHATSAPP_REPLY_PREFIX.replace(/\\n/g, '\n');

 function formatOutgoingMessage(message) {
+  // In bot mode, messages come from a different number so the prefix is
+  // redundant — the sender identity is already clear.  Only prepend in
+  // self-chat mode where bot and user share the same number.
+  if (WHATSAPP_MODE !== 'self-chat') return message;
  return REPLY_PREFIX ? `${REPLY_PREFIX}${message}` : message;
 }

@@ -190,10 +195,9 @@ async function startSocket() {
        if (!isSelfChat) continue;
      }

-      // Check allowlist for messages from others (resolve LID → phone if needed)
-      if (!msg.key.fromMe && ALLOWED_USERS.length > 0) {
-        const resolvedNumber = lidToPhone[senderNumber] || senderNumber;
-        if (!ALLOWED_USERS.includes(resolvedNumber)) continue;
+      // Check allowlist for messages from others (resolve LID ↔ phone aliases)
+      if (!msg.key.fromMe && !matchesAllowedUser(senderId, ALLOWED_USERS, SESSION_DIR)) {
+        continue;
      }

      // Extract message body
@@ -515,8 +519,8 @@ if (PAIR_ONLY) {
  app.listen(PORT, '127.0.0.1', () => {
    console.log(`🌉 WhatsApp bridge listening on port ${PORT} (mode: ${WHATSAPP_MODE})`);
    console.log(`📁 Session stored in: ${SESSION_DIR}`);
-    if (ALLOWED_USERS.length > 0) {
-      console.log(`🔒 Allowed users: ${ALLOWED_USERS.join(', ')}`);
+    if (ALLOWED_USERS.size > 0) {
+      console.log(`🔒 Allowed users: ${Array.from(ALLOWED_USERS).join(', ')}`);
    } else {
      console.log(`⚠️  No WHATSAPP_ALLOWED_USERS set — all messages will be processed`);
    }
@@ -0,0 +1,289 @@
+---
+name: songwriting-and-ai-music
+description: >
+  Songwriting craft, AI music generation prompts (Suno focus), parody/adaptation
+  techniques, phonetic tricks, and lessons learned. These are tools and ideas,
+  not rules. Break any of them when the art calls for it.
+tags: [songwriting, music, suno, parody, lyrics, creative]
+triggers:
+  - writing a song
+  - song lyrics
+  - music prompt
+  - suno prompt
+  - parody song
+  - adapting a song
+  - AI music generation
+---
+
+# Songwriting & AI Music Generation
+
+Everything here is a GUIDELINE, not a rule. Art breaks rules on purpose.
+Use what serves the song. Ignore what doesn't.
+
+---
+
+## 1. Song Structure (Pick One or Invent Your Own)
+
+Common skeletons — mix, modify, or throw out as needed:
+
+```
+ABABCB  Verse/Chorus/Verse/Chorus/Bridge/Chorus    (most pop/rock)
+AABA    Verse/Verse/Bridge/Verse (refrain-based)    (jazz standards, ballads)
+ABAB    Verse/Chorus alternating                    (simple, direct)
+AAA     Verse/Verse/Verse (strophic, no chorus)     (folk, storytelling)
+```
+
+The six building blocks:
+- Intro      — set the mood, pull the listener in
+- Verse      — the story, the details, the world-building
+- Pre-Chorus — optional tension ramp before the payoff
+- Chorus     — the emotional core, the part people remember
+- Bridge     — a detour, a shift in perspective or key
+- Outro      — the farewell, can echo or subvert the rest
+
+You don't need all of these. Some great songs are just one section
+that evolves. Structure serves the emotion, not the other way around.
+
+---
+
+## 2. Rhyme, Meter, and Sound
+
+RHYME TYPES (from tight to loose):
+- Perfect: lean/mean
+- Family: crate/braid
+- Assonance: had/glass (same vowels, different endings)
+- Consonance: scene/when (different vowels, similar endings)
+- Near/slant: enough to suggest connection without locking it down
+
+Mix them. All perfect rhymes can sound like a nursery rhyme.
+All slant rhymes can sound lazy. The blend is where it lives.
+
+INTERNAL RHYME: Rhyming within a line, not just at the ends.
+  "We pruned the lies from bleeding trees / Distilled the storm
+   from entropy" — "lies/flies," "trees/entropy" create internal echoes.
+
+METER: The rhythm of stressed vs unstressed syllables.
+- Matching syllable counts between parallel lines helps singability
+- The STRESSED syllables matter more than total count
+- Say it out loud. If you stumble, the meter needs work.
+- Intentionally breaking meter can create emphasis or surprise
+
+---
+
+## 3. Emotional Arc and Dynamics
+
+Think of a song as a journey, not a flat road.
+
+ENERGY MAPPING (rough idea, not prescription):
+  Intro: 2-3  |  Verse: 5-6  |  Pre-Chorus: 7
+  Chorus: 8-9  |  Bridge: varies  |  Final Chorus: 9-10
+
+The most powerful dynamic trick: CONTRAST.
+- Whisper before a scream hits harder than just screaming
+- Sparse before dense. Slow before fast. Low before high.
+- The drop only works because of the buildup
+- Silence is an instrument
+
+"Whisper to roar to whisper" — start intimate, build to full power,
+strip back to vulnerability. Works for ballads, epics, anthems.
+
+---
+
+## 4. Writing Lyrics That Work
+
+SHOW, DON'T TELL (usually):
+- "I was sad" = flat
+- "Your hoodie's still on the hook by the door" = alive
+- But sometimes "I give my life" said plainly IS the power
+
+THE HOOK:
+- The line people remember, hum, repeat
+- Usually the title or core phrase
+- Works best when melody + lyric + emotion all align
+- Place it where it lands hardest (often first/last line of chorus)
+
+PROSODY — lyrics and music supporting each other:
+- Stable feelings (resolution, peace) pair with settled melodies,
+  perfect rhymes, resolved chords
+- Unstable feelings (longing, doubt) pair with wandering melodies,
+  near-rhymes, unresolved chords
+- Verse melody typically sits lower, chorus goes higher
+- But flip this if it serves the song
+
+AVOID (unless you're doing it on purpose):
+- Cliches on autopilot ("heart of gold" without earning it)
+- Forcing word order to hit a rhyme ("Yoda-speak")
+- Same energy in every section (flat dynamics)
+- Treating your first draft as sacred — revision is creation
+
+---
+
+## 5. Parody and Adaptation
+
+When rewriting an existing song with new lyrics:
+
+THE SKELETON: Map the original's structure first.
+- Count syllables per line
+- Mark the rhyme scheme (ABAB, AABB, etc.)
+- Identify which syllables are STRESSED
+- Note where held/sustained notes fall
+
+FITTING NEW WORDS:
+- Match stressed syllables to the same beats as the original
+- Total syllable count can flex by 1-2 unstressed syllables
+- On long held notes, try to match the VOWEL SOUND of the original
+  (if original holds "LOOOVE" with an "oo" vowel, "FOOOD" fits
+   better than "LIFE")
+- Monosyllabic swaps in key spots keep rhythm intact
+  (Crime -> Code, Snake -> Noose)
+- Sing your new words over the original — if you stumble, revise
+
+CONCEPT:
+- Pick a concept strong enough to sustain the whole song
+- Start from the title/hook and build outward
+- Generate lots of raw material (puns, phrases, images) FIRST,
+  then fit the best ones into the structure
+- If you need a specific line somewhere, reverse-engineer the
+  rhyme scheme backward to set it up
+
+KEEP SOME ORIGINALS: Leaving a few original lines or structures
+intact adds recognizability and lets the audience feel the connection.
+
+---
+
+## 6. Suno AI Prompt Engineering
+
+### Style/Genre Description Field
+
+FORMULA (adapt as needed):
+  Genre + Mood + Era + Instruments + Vocal Style + Production + Dynamics
+
+```
+BAD:  "sad rock song"
+GOOD: "Cinematic orchestral spy thriller, 1960s Cold War era, smoky
+       sultry female vocalist, big band jazz, brass section with
+       trumpets and french horns, sweeping strings, minor key,
+       vintage analog warmth"
+```
+
+DESCRIBE THE JOURNEY, not just the genre:
+```
+"Begins as a haunting whisper over sparse piano. Gradually layers
+ in muted brass. Builds through the chorus with full orchestra.
+ Second verse erupts with raw belting intensity. Outro strips back
+ to a lone piano and a fragile whisper fading to silence."
+```
+
+TIPS:
+- V4.5+ supports up to 1,000 chars in Style field — use them
+- NO artist names or trademarks. Describe the sound instead.
+  "1960s Cold War spy thriller brass" not "James Bond style"
+  "90s grunge" not "Nirvana-style"
+- Specify BPM and key when you have a preference
+- Use Exclude Styles field for what you DON'T want
+- Unexpected genre combos can be gold: "bossa nova trap",
+  "Appalachian gothic", "chiptune jazz"
+- Build a vocal PERSONA, not just a gender:
+  "A weathered torch singer with a smoky alto, slight rasp,
+   who starts vulnerable and builds to devastating power"
+
+### Metatags (place in [brackets] inside lyrics field)
+
+STRUCTURE:
+  [Intro] [Verse] [Verse 1] [Pre-Chorus] [Chorus]
+  [Post-Chorus] [Hook] [Bridge] [Interlude]
+  [Instrumental] [Instrumental Break] [Guitar Solo]
+  [Breakdown] [Build-up] [Outro] [Silence] [End]
+
+VOCAL PERFORMANCE:
+  [Whispered] [Spoken Word] [Belted] [Falsetto] [Powerful]
+  [Soulful] [Raspy] [Breathy] [Smooth] [Gritty]
+  [Staccato] [Legato] [Vibrato] [Melismatic]
+  [Harmonies] [Choir] [Harmonized Chorus]
+
+DYNAMICS:
+  [High Energy] [Low Energy] [Building Energy] [Explosive]
+  [Emotional Climax] [Gradual swell] [Orchestral swell]
+  [Quiet arrangement] [Falling tension] [Slow Down]
+
+GENDER:
+  [Female Vocals] [Male Vocals]
+
+ATMOSPHERE:
+  [Melancholic] [Euphoric] [Nostalgic] [Aggressive]
+  [Dreamy] [Intimate] [Dark Atmosphere]
+
+SFX:
+  [Vinyl Crackle] [Rain] [Applause] [Static] [Thunder]
+
+Put tags in BOTH style field AND lyrics for reinforcement.
+Keep to 5-8 tags per section max — too many confuses the AI.
+Don't contradict yourself ([Calm] + [Aggressive] in same section).
+
+### Custom Mode
+- Always use Custom Mode for serious work (separate Style + Lyrics)
+- Lyrics field limit: ~3,000 chars (~40-60 lines)
+- Always add structural tags — without them Suno defaults to
+  flat verse/chorus/verse with no emotional arc
+
+---
+
+## 7. Phonetic Tricks for AI Singers
+
+AI vocalists don't read — they pronounce. Help them:
+
+PHONETIC RESPELLING:
+- Spell words as they SOUND: "through" -> "thru"
+- Proper nouns are highest failure rate — test early
+- "Nous" -> "Noose" (forces correct pronunciation)
+- Hyphenate to guide syllables: "Re-search", "bio-engineering"
+
+DELIVERY CONTROL:
+- ALL CAPS = louder, more intense
+- Vowel extension: "lo-o-o-ove" = sustained/melisma
+- Ellipses: "I... need... you" = dramatic pauses
+- Hyphenated stretch: "ne-e-ed" = emotional stretch
+
+ALWAYS:
+- Spell out numbers: "24/7" -> "twenty four seven"
+- Space acronyms: "AI" -> "A I" or "A-I"
+- Test proper nouns/unusual words in a short 30-second clip first
+- Once generated, pronunciation is baked in — fix in lyrics BEFORE
+
+---
+
+## 8. Workflow
+
+1. Write the concept/hook first — what's the emotional core?
+2. If adapting, map the original structure (syllables, rhyme, stress)
+3. Generate raw material — brainstorm freely before structuring
+4. Draft lyrics into the structure
+5. Read/sing aloud — catch stumbles, fix meter
+6. Build the Suno style description — paint the dynamic journey
+7. Add metatags to lyrics for performance direction
+8. Generate 3-5 variations minimum — treat them like recording takes
+9. Pick the best, use Extend/Continue to build on promising sections
+10. If something great happens by accident, keep it
+
+EXPECT: ~3-5 generations per 1 good result. Revision is normal.
+Style can drift in extensions — restate genre/mood when extending.
+
+---
+
+## 9. Lessons Learned
+
+- Describing the dynamic ARC in the style field matters way more
+  than just listing genres. "Whisper to roar to whisper" gives
+  Suno a performance map.
+- Keeping some original lines intact in a parody adds recognizability
+  and emotional weight — the audience feels the ghost of the original.
+- The bridge slot in a song is where you can transform imagery.
+  Swap the original's specific references for your theme's metaphors
+  while keeping the emotional function (reflection, shift, revelation).
+- Monosyllabic word swaps in hooks/tags are the cleanest way to
+  maintain rhythm while changing meaning.
+- A strong vocal persona description in the style field makes a
+  bigger difference than any single metatag.
+- Don't be precious about rules. If a line breaks meter but hits
+  harder, keep it. The feeling is what matters. Craft serves art,
+  not the other way around.
@@ -1,3 +0,0 @@
---
-description: Skills for generating, editing, and processing music and audio using AI models and audio tools.
---
@@ -4,6 +4,11 @@ description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via
 version: 1.0.0
 author: Nous Research
 license: MIT
+required_credential_files:
+  - path: google_token.json
+    description: Google OAuth2 token (created by setup script)
+  - path: google_client_secret.json
+    description: Google OAuth2 client credentials (downloaded from Google Cloud Console)
 metadata:
  hermes:
    tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]
@@ -1,7 +1,7 @@
 ---
 name: duckduckgo-search
-description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content.
-version: 1.2.0
+description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
+version: 1.3.0
 author: gamedevCloudy
 license: MIT
 metadata:
@@ -9,26 +9,96 @@ metadata:
    tags: [search, duckduckgo, web-search, free, fallback]
    related_skills: [arxiv]
    fallback_for_toolsets: [web]
-prerequisites:
-  commands: [ddgs]
 ---

 # DuckDuckGo Search

 Free web search using DuckDuckGo. **No API key required.**

-Preferred when `web_search` tool is unavailable or unsuitable (no `FIRECRAWL_API_KEY` set). Can also be used as a standalone search tool.
+Preferred when `web_search` is unavailable or unsuitable (for example when `FIRECRAWL_API_KEY` is not set). Can also be used as a standalone search path when DuckDuckGo results are specifically desired.

-## Setup
+## Detection Flow
+
+Check what is actually available before choosing an approach:

 ```bash
-# Install the ddgs package (one-time)
-pip install ddgs
+# Check CLI availability
+command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"
 ```

-## Python API (Primary)
+Decision tree:
+1. If `ddgs` CLI is installed, prefer `terminal` + `ddgs`
+2. If `ddgs` CLI is missing, do not assume `execute_code` can import `ddgs`
+3. If the user wants DuckDuckGo specifically, install `ddgs` first in the relevant environment
+4. Otherwise fall back to built-in web/browser tools

-Use the `DDGS` class in `execute_code` for structured results with typed fields.
+Important runtime note:
+- Terminal and `execute_code` are separate runtimes
+- A successful shell install does not guarantee `execute_code` can import `ddgs`
+- Never assume third-party Python packages are preinstalled inside `execute_code`
+
+## Installation
+
+Install `ddgs` only when DuckDuckGo search is specifically needed and the runtime does not already provide it.
+
+```bash
+# Python package + CLI entrypoint
+pip install ddgs
+
+# Verify CLI
+ddgs --help
+```
+
+If a workflow depends on Python imports, verify that same runtime can import `ddgs` before using `from ddgs import DDGS`.
+
+## Method 1: CLI Search (Preferred)
+
+Use the `ddgs` command via `terminal` when it exists. This is the preferred path because it avoids assuming the `execute_code` sandbox has the `ddgs` Python package installed.
+
+```bash
+# Text search
+ddgs text -k "python async programming" -m 5
+
+# News search
+ddgs news -k "artificial intelligence" -m 5
+
+# Image search
+ddgs images -k "landscape photography" -m 10
+
+# Video search
+ddgs videos -k "python tutorial" -m 5
+
+# With region filter
+ddgs text -k "best restaurants" -m 5 -r us-en
+
+# Recent results only (d=day, w=week, m=month, y=year)
+ddgs text -k "latest AI news" -m 5 -t w
+
+# JSON output for parsing
+ddgs text -k "fastapi tutorial" -m 5 -o json
+```
+
+### CLI Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-k` | Keywords (query) — **required** | `-k "search terms"` |
+| `-m` | Max results | `-m 5` |
+| `-r` | Region | `-r us-en` |
+| `-t` | Time limit | `-t w` (week) |
+| `-s` | Safe search | `-s off` |
+| `-o` | Output format | `-o json` |
+
+## Method 2: Python API (Only After Verification)
+
+Use the `DDGS` class in `execute_code` or another Python runtime only after verifying that `ddgs` is installed there. Do not assume `execute_code` includes third-party packages by default.
+
+Safe wording:
+- "Use `execute_code` with `ddgs` after installing or verifying the package if needed"
+
+Avoid saying:
+- "`execute_code` includes `ddgs`"
+- "DuckDuckGo search works by default in `execute_code`"

 **Important:** `max_results` must always be passed as a **keyword argument** — positional usage raises an error on all methods.

@@ -76,7 +146,7 @@ from ddgs import DDGS
 with DDGS() as ddgs:
    for r in ddgs.images("semiconductor chip", max_results=5):
        print(r["title"])
-        print(r["image"])       # direct image URL
+        print(r["image"])
        print(r.get("thumbnail", ""))
        print(r.get("source", ""))
        print()
@@ -94,9 +164,9 @@ from ddgs import DDGS
 with DDGS() as ddgs:
    for r in ddgs.videos("FastAPI tutorial", max_results=5):
        print(r["title"])
-        print(r.get("content", ""))       # video URL
-        print(r.get("duration", ""))       # e.g. "26:03"
-        print(r.get("provider", ""))       # YouTube, etc.
+        print(r.get("content", ""))
+        print(r.get("duration", ""))
+        print(r.get("provider", ""))
        print(r.get("published", ""))
        print()
 ```
@@ -112,50 +182,17 @@ Returns: `title`, `content`, `description`, `duration`, `provider`, `published`,
 | `images()` | Visuals, diagrams | title, image, thumbnail, url |
 | `videos()` | Tutorials, demos | title, content, duration, provider |

-## CLI (Alternative)
-
-Use the `ddgs` command via terminal when you don't need structured field access.
-
-```bash
-# Text search
-ddgs text -k "python async programming" -m 5
-
-# News search
-ddgs news -k "artificial intelligence" -m 5
-
-# Image search
-ddgs images -k "landscape photography" -m 10
-
-# Video search
-ddgs videos -k "python tutorial" -m 5
-
-# With region filter
-ddgs text -k "best restaurants" -m 5 -r us-en
-
-# Recent results only (d=day, w=week, m=month, y=year)
-ddgs text -k "latest AI news" -m 5 -t w
-
-# JSON output for parsing
-ddgs text -k "fastapi tutorial" -m 5 -o json
-```
-
-### CLI Flags
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `-k` | Keywords (query) — **required** | `-k "search terms"` |
-| `-m` | Max results | `-m 5` |
-| `-r` | Region | `-r us-en` |
-| `-t` | Time limit | `-t w` (week) |
-| `-s` | Safe search | `-s off` |
-| `-o` | Output format | `-o json` |
-
 ## Workflow: Search then Extract

-DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full content, follow up with `web_extract`:
+DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full page content, search first and then extract the most relevant URL with `web_extract`, browser tools, or curl.

-1. **Search** with ddgs to find relevant URLs
-2. **Extract** content using the `web_extract` tool (if available) or curl
+CLI example:
+
+```bash
+ddgs text -k "fastapi deployment guide" -m 3 -o json
+```
+
+Python example, only after verifying `ddgs` is installed in that runtime:

 ```python
 from ddgs import DDGS
@@ -164,25 +201,37 @@ with DDGS() as ddgs:
    results = list(ddgs.text("fastapi deployment guide", max_results=3))
    for r in results:
        print(r["title"], "->", r["href"])
-
-# Then use web_extract tool on the best URL
 ```

+Then extract the best URL with `web_extract` or another content-retrieval tool.
+
 ## Limitations

 - **Rate limiting**: DuckDuckGo may throttle after many rapid requests. Add a short delay between searches if needed.
- **No content extraction**: ddgs returns snippets, not full page content. Use `web_extract` or curl for that.
+- **No content extraction**: `ddgs` returns snippets, not full page content. Use `web_extract`, browser tools, or curl for the full article/page.
 - **Results quality**: Generally good but less configurable than Firecrawl's search.
 - **Availability**: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or wait a few seconds.
- **Field variability**: Return fields may vary between results or ddgs versions. Use `.get()` for optional fields to avoid KeyError.
+- **Field variability**: Return fields may vary between results or `ddgs` versions. Use `.get()` for optional fields to avoid `KeyError`.
+- **Separate runtimes**: A successful `ddgs` install in terminal does not automatically mean `execute_code` can import it.
+
+## Troubleshooting
+
+| Problem | Likely Cause | What To Do |
+|---------|--------------|------------|
+| `ddgs: command not found` | CLI not installed in the shell environment | Install `ddgs`, or use built-in web/browser tools instead |
+| `ModuleNotFoundError: No module named 'ddgs'` | Python runtime does not have the package installed | Do not use Python DDGS there until that runtime is prepared |
+| Search returns nothing | Temporary rate limiting or poor query | Wait a few seconds, retry, or adjust the query |
+| CLI works but `execute_code` import fails | Terminal and `execute_code` are different runtimes | Keep using CLI, or separately prepare the Python runtime |

 ## Pitfalls

 - **`max_results` is keyword-only**: `ddgs.text("query", 5)` raises an error. Use `ddgs.text("query", max_results=5)`.
+- **Do not assume the CLI exists**: Check `command -v ddgs` before using it.
+- **Do not assume `execute_code` can import `ddgs`**: `from ddgs import DDGS` may fail with `ModuleNotFoundError` unless that runtime was prepared separately.
+- **Package name**: The package is `ddgs` (previously `duckduckgo-search`). Install with `pip install ddgs`.
 - **Don't confuse `-k` and `-m`** (CLI): `-k` is for keywords, `-m` is for max results count.
- **Package name**: The package is `ddgs` (was previously `duckduckgo-search`). Install with `pip install ddgs`.
- **Empty results**: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.
+- **Empty results**: If `ddgs` returns nothing, it may be rate-limited. Wait a few seconds and retry.

 ## Validated With

-Smoke-tested with `ddgs==9.11.2` on Python 3.13. All four methods (text, news, images, videos) confirmed working with keyword `max_results`.
+Validated examples against `ddgs==9.11.2` semantics. Skill guidance now treats CLI availability and Python import availability as separate concerns so the documented workflow matches actual runtime behavior.
@@ -0,0 +1,20 @@
+"""Tests for acp_adapter.entry startup wiring."""
+
+import acp
+
+from acp_adapter import entry
+
+
+def test_main_enables_unstable_protocol(monkeypatch):
+    calls = {}
+
+    async def fake_run_agent(agent, **kwargs):
+        calls["kwargs"] = kwargs
+
+    monkeypatch.setattr(entry, "_setup_logging", lambda: None)
+    monkeypatch.setattr(entry, "_load_env", lambda: None)
+    monkeypatch.setattr(acp, "run_agent", fake_run_agent)
+
+    entry.main()
+
+    assert calls["kwargs"]["use_unstable_protocol"] is True
@@ -8,6 +8,7 @@ from unittest.mock import MagicMock, AsyncMock, patch
 import pytest

 import acp
+from acp.agent.router import build_agent_router
 from acp.schema import (
    AgentCapabilities,
    AuthenticateResponse,
@@ -18,6 +19,8 @@ from acp.schema import (
    NewSessionResponse,
    PromptResponse,
    ResumeSessionResponse,
+    SetSessionConfigOptionResponse,
+    SetSessionModeResponse,
    SessionInfo,
    TextContentBlock,
    Usage,
@@ -168,6 +171,74 @@ class TestListAndFork:
        assert fork_resp.session_id != new_resp.session_id


+# ---------------------------------------------------------------------------
+# session configuration / model routing
+# ---------------------------------------------------------------------------
+
+
+class TestSessionConfiguration:
+    @pytest.mark.asyncio
+    async def test_set_session_mode_returns_response(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        resp = await agent.set_session_mode(mode_id="chat", session_id=new_resp.session_id)
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert isinstance(resp, SetSessionModeResponse)
+        assert getattr(state, "mode", None) == "chat"
+
+    @pytest.mark.asyncio
+    async def test_set_config_option_returns_response(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        resp = await agent.set_config_option(
+            config_id="approval_mode",
+            session_id=new_resp.session_id,
+            value="auto",
+        )
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert isinstance(resp, SetSessionConfigOptionResponse)
+        assert getattr(state, "config_options", {}) == {"approval_mode": "auto"}
+        assert resp.config_options == []
+
+    @pytest.mark.asyncio
+    async def test_router_accepts_stable_session_config_methods(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        router = build_agent_router(agent)
+
+        mode_result = await router(
+            "session/set_mode",
+            {"modeId": "chat", "sessionId": new_resp.session_id},
+            False,
+        )
+        config_result = await router(
+            "session/set_config_option",
+            {
+                "configId": "approval_mode",
+                "sessionId": new_resp.session_id,
+                "value": "auto",
+            },
+            False,
+        )
+
+        assert mode_result == {}
+        assert config_result == {"configOptions": []}
+
+    @pytest.mark.asyncio
+    async def test_router_accepts_unstable_model_switch_when_enabled(self, agent):
+        new_resp = await agent.new_session(cwd="/tmp")
+        router = build_agent_router(agent, use_unstable_protocol=True)
+
+        result = await router(
+            "session/set_model",
+            {"modelId": "gpt-5.4", "sessionId": new_resp.session_id},
+            False,
+        )
+        state = agent.session_manager.get_session(new_resp.session_id)
+
+        assert result == {}
+        assert state.model == "gpt-5.4"
+
+
 # ---------------------------------------------------------------------------
 # prompt
 # ---------------------------------------------------------------------------
@@ -491,15 +491,17 @@ class TestGetTextAuxiliaryClient:
        assert mock_openai.call_args.kwargs["base_url"] == "http://localhost:2345/v1"
        assert mock_openai.call_args.kwargs["api_key"] == "task-key"

-    def test_task_direct_endpoint_without_openai_key_does_not_fall_back(self, monkeypatch):
+    def test_task_direct_endpoint_without_openai_key_uses_placeholder(self, monkeypatch):
+        """Local endpoints without an API key should use 'no-key-required' placeholder."""
        monkeypatch.setenv("OPENROUTER_API_KEY", "or-key")
        monkeypatch.setenv("AUXILIARY_WEB_EXTRACT_BASE_URL", "http://localhost:2345/v1")
        monkeypatch.setenv("AUXILIARY_WEB_EXTRACT_MODEL", "task-model")
        with patch("agent.auxiliary_client.OpenAI") as mock_openai:
            client, model = get_text_auxiliary_client("web_extract")
-        assert client is None
-        assert model is None
-        mock_openai.assert_not_called()
+        assert client is not None
+        assert model == "task-model"
+        assert mock_openai.call_args.kwargs["api_key"] == "no-key-required"
+        assert mock_openai.call_args.kwargs["base_url"] == "http://localhost:2345/v1"

    def test_custom_endpoint_uses_config_saved_base_url(self, monkeypatch):
        config = {
@@ -696,15 +698,16 @@ class TestVisionClientFallback:
        assert mock_openai.call_args.kwargs["base_url"] == "http://localhost:4567/v1"
        assert mock_openai.call_args.kwargs["api_key"] == "vision-key"

-    def test_vision_direct_endpoint_requires_openai_api_key(self, monkeypatch):
+    def test_vision_direct_endpoint_without_key_uses_placeholder(self, monkeypatch):
+        """Vision endpoint without API key should use 'no-key-required' placeholder."""
        monkeypatch.setenv("OPENROUTER_API_KEY", "or-key")
        monkeypatch.setenv("AUXILIARY_VISION_BASE_URL", "http://localhost:4567/v1")
        monkeypatch.setenv("AUXILIARY_VISION_MODEL", "vision-model")
        with patch("agent.auxiliary_client.OpenAI") as mock_openai:
            client, model = get_vision_auxiliary_client()
-        assert client is None
-        assert model is None
-        mock_openai.assert_not_called()
+        assert client is not None
+        assert model == "vision-model"
+        assert mock_openai.call_args.kwargs["api_key"] == "no-key-required"

    def test_vision_uses_openrouter_when_available(self, monkeypatch):
        monkeypatch.setenv("OPENROUTER_API_KEY", "or-key")
@@ -0,0 +1,157 @@
+"""Tests for external skill directories (skills.external_dirs config)."""
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+
+@pytest.fixture
+def external_skills_dir(tmp_path):
+    """Create a temp dir with a sample external skill."""
+    ext_dir = tmp_path / "external-skills"
+    skill_dir = ext_dir / "my-external-skill"
+    skill_dir.mkdir(parents=True)
+    (skill_dir / "SKILL.md").write_text(
+        "---\nname: my-external-skill\ndescription: A skill from an external directory\n---\n\n# My External Skill\n\nDo external things.\n"
+    )
+    return ext_dir
+
+
+@pytest.fixture
+def hermes_home(tmp_path):
+    """Create a minimal HERMES_HOME with config."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    (home / "skills").mkdir()
+    return home
+
+
+class TestGetExternalSkillsDirs:
+    def test_empty_config(self, hermes_home):
+        (hermes_home / "config.yaml").write_text("skills:\n  external_dirs: []\n")
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_nonexistent_dir_skipped(self, hermes_home):
+        (hermes_home / "config.yaml").write_text(
+            "skills:\n  external_dirs:\n    - /nonexistent/path\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_valid_dir_returned(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+        assert result[0] == external_skills_dir.resolve()
+
+    def test_duplicate_dirs_deduplicated(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+
+    def test_local_skills_dir_excluded(self, hermes_home):
+        local_skills = hermes_home / "skills"
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {local_skills}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_no_config_file(self, hermes_home):
+        # No config.yaml at all
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert result == []
+
+    def test_string_value_converted_to_list(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs: {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_external_skills_dirs
+            result = get_external_skills_dirs()
+        assert len(result) == 1
+
+
+class TestGetAllSkillsDirs:
+    def test_local_always_first(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            from agent.skill_utils import get_all_skills_dirs
+            result = get_all_skills_dirs()
+        assert result[0] == hermes_home / "skills"
+        assert result[1] == external_skills_dir.resolve()
+
+
+class TestExternalSkillsInFindAll:
+    def test_external_skills_found(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        local_skills = hermes_home / "skills"
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import _find_all_skills
+            skills = _find_all_skills()
+        names = [s["name"] for s in skills]
+        assert "my-external-skill" in names
+
+    def test_local_takes_precedence(self, hermes_home, external_skills_dir):
+        """If the same skill name exists locally and externally, local wins."""
+        local_skills = hermes_home / "skills"
+        local_skill = local_skills / "my-external-skill"
+        local_skill.mkdir(parents=True)
+        (local_skill / "SKILL.md").write_text(
+            "---\nname: my-external-skill\ndescription: Local version\n---\n\nLocal.\n"
+        )
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import _find_all_skills
+            skills = _find_all_skills()
+        matching = [s for s in skills if s["name"] == "my-external-skill"]
+        assert len(matching) == 1
+        assert matching[0]["description"] == "Local version"
+
+
+class TestExternalSkillView:
+    def test_skill_view_finds_external(self, hermes_home, external_skills_dir):
+        (hermes_home / "config.yaml").write_text(
+            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
+        )
+        local_skills = hermes_home / "skills"
+        with (
+            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
+            patch("tools.skills_tool.SKILLS_DIR", local_skills),
+        ):
+            from tools.skills_tool import skill_view
+            result = json.loads(skill_view("my-external-skill"))
+        assert result["success"] is True
+        assert "external things" in result["content"]
@@ -5,6 +5,8 @@ import importlib
 import logging
 import sys

+import pytest
+
 from agent.prompt_builder import (
    _scan_context_content,
    _truncate_content,
@@ -194,7 +196,7 @@ class TestParseSkillFile:
        )
        from unittest.mock import patch

-        with patch("tools.skills_tool.sys") as mock_sys:
+        with patch("agent.skill_utils.sys") as mock_sys:
            mock_sys.platform = "linux"
            is_compat, _, _ = _parse_skill_file(skill_file)
        assert is_compat is False
@@ -234,9 +236,6 @@ class TestPromptBuilderImports:
 # =========================================================================


-import pytest
-
-
 class TestBuildSkillsSystemPrompt:
    @pytest.fixture(autouse=True)
    def _clear_skills_cache(self):
@@ -296,7 +295,7 @@ class TestBuildSkillsSystemPrompt:

        from unittest.mock import patch

-        with patch("tools.skills_tool.sys") as mock_sys:
+        with patch("agent.skill_utils.sys") as mock_sys:
            mock_sys.platform = "linux"
            result = build_skills_system_prompt()

@@ -574,6 +573,10 @@ class TestBuildContextFilesPrompt:
        result = build_context_files_prompt(cwd=str(tmp_path))
        assert "Lowercase claude rules" in result

+    @pytest.mark.skipif(
+        sys.platform == "darwin",
+        reason="APFS default volume is case-insensitive; CLAUDE.md and claude.md alias the same path",
+    )
    def test_claude_md_uppercase_takes_priority(self, tmp_path):
        (tmp_path / "CLAUDE.md").write_text("From uppercase.")
        (tmp_path / "claude.md").write_text("From lowercase.")
@@ -201,3 +201,52 @@ class TestSecretCapturePayloadRedaction:
        text = '{"raw_secret": "ghp_abc123def456ghi789jkl"}'
        result = redact_sensitive_text(text)
        assert "abc123def456" not in result
+
+
+class TestElevenLabsTavilyExaKeys:
+    """Regression tests for ElevenLabs (sk_), Tavily (tvly-), and Exa (exa_) keys."""
+
+    def test_elevenlabs_key_redacted(self):
+        text = "ELEVENLABS_API_KEY=sk_abc123def456ghi789jklmnopqrstu"
+        result = redact_sensitive_text(text)
+        assert "abc123def456ghi" not in result
+
+    def test_elevenlabs_key_in_log_line(self):
+        text = "Connecting to ElevenLabs with key sk_abc123def456ghi789jklmnopqrstu"
+        result = redact_sensitive_text(text)
+        assert "abc123def456ghi" not in result
+
+    def test_tavily_key_redacted(self):
+        text = "TAVILY_API_KEY=tvly-ABCdef123456789GHIJKL0000"
+        result = redact_sensitive_text(text)
+        assert "ABCdef123456789" not in result
+
+    def test_tavily_key_in_log_line(self):
+        text = "Initialising Tavily client with tvly-ABCdef123456789GHIJKL0000"
+        result = redact_sensitive_text(text)
+        assert "ABCdef123456789" not in result
+
+    def test_exa_key_redacted(self):
+        text = "EXA_API_KEY=exa_XYZ789abcdef000000000000000"
+        result = redact_sensitive_text(text)
+        assert "XYZ789abcdef" not in result
+
+    def test_exa_key_in_log_line(self):
+        text = "Using Exa client with key exa_XYZ789abcdef000000000000000"
+        result = redact_sensitive_text(text)
+        assert "XYZ789abcdef" not in result
+
+    def test_all_three_in_env_dump(self):
+        env_dump = (
+            "HOME=/home/user\n"
+            "ELEVENLABS_API_KEY=sk_abc123def456ghi789jklmnopqrstu\n"
+            "TAVILY_API_KEY=tvly-ABCdef123456789GHIJKL0000\n"
+            "EXA_API_KEY=exa_XYZ789abcdef000000000000000\n"
+            "SHELL=/bin/bash\n"
+        )
+        result = redact_sensitive_text(env_dump)
+        assert "abc123def456ghi" not in result
+        assert "ABCdef123456789" not in result
+        assert "XYZ789abcdef" not in result
+        assert "HOME=/home/user" in result
+        assert "SHELL=/bin/bash" in result
@@ -246,20 +246,10 @@ Generate some audio.
    def test_preserves_remaining_remote_setup_warning(self, tmp_path, monkeypatch):
        monkeypatch.setenv("TERMINAL_ENV", "ssh")
        monkeypatch.delenv("TENOR_API_KEY", raising=False)
-
-        def fake_secret_callback(var_name, prompt, metadata=None):
-            os.environ[var_name] = "stored-in-test"
-            return {
-                "success": True,
-                "stored_as": var_name,
-                "validated": False,
-                "skipped": False,
-            }
-
        monkeypatch.setattr(
            skills_tool_module,
            "_secret_capture_callback",
-            fake_secret_callback,
+            None,
            raising=False,
        )

@@ -84,6 +84,48 @@ class TestResolveDeliveryTarget:
            "thread_id": None,
        }

+    def test_human_friendly_label_resolved_via_channel_directory(self):
+        """deliver: 'whatsapp:Alice (dm)' resolves to the real JID."""
+        job = {"deliver": "whatsapp:Alice (dm)"}
+        with patch(
+            "gateway.channel_directory.resolve_channel_name",
+            return_value="12345678901234@lid",
+        ):
+            result = _resolve_delivery_target(job)
+        assert result == {
+            "platform": "whatsapp",
+            "chat_id": "12345678901234@lid",
+            "thread_id": None,
+        }
+
+    def test_human_friendly_label_without_suffix_resolved(self):
+        """deliver: 'telegram:My Group' resolves without display suffix."""
+        job = {"deliver": "telegram:My Group"}
+        with patch(
+            "gateway.channel_directory.resolve_channel_name",
+            return_value="-1009999",
+        ):
+            result = _resolve_delivery_target(job)
+        assert result == {
+            "platform": "telegram",
+            "chat_id": "-1009999",
+            "thread_id": None,
+        }
+
+    def test_raw_id_not_mangled_when_directory_returns_none(self):
+        """deliver: 'whatsapp:12345@lid' passes through when directory has no match."""
+        job = {"deliver": "whatsapp:12345@lid"}
+        with patch(
+            "gateway.channel_directory.resolve_channel_name",
+            return_value=None,
+        ):
+            result = _resolve_delivery_target(job)
+        assert result == {
+            "platform": "whatsapp",
+            "chat_id": "12345@lid",
+            "thread_id": None,
+        }
+
    def test_bare_platform_uses_matching_origin_chat(self):
        job = {
            "deliver": "telegram",
@@ -167,6 +209,32 @@ class TestDeliverResultWrapping:
        sent_content = send_mock.call_args.kwargs.get("content") or send_mock.call_args[0][-1]
        assert "Cronjob Response: abc-123" in sent_content

+    def test_delivery_skips_wrapping_when_config_disabled(self):
+        """When cron.wrap_response is false, deliver raw content without header/footer."""
+        from gateway.config import Platform
+
+        pconfig = MagicMock()
+        pconfig.enabled = True
+        mock_cfg = MagicMock()
+        mock_cfg.platforms = {Platform.TELEGRAM: pconfig}
+
+        with patch("gateway.config.load_gateway_config", return_value=mock_cfg), \
+             patch("tools.send_message_tool._send_to_platform", new=AsyncMock(return_value={"success": True})) as send_mock, \
+             patch("cron.scheduler.load_config", return_value={"cron": {"wrap_response": False}}):
+            job = {
+                "id": "test-job",
+                "name": "daily-report",
+                "deliver": "origin",
+                "origin": {"platform": "telegram", "chat_id": "123"},
+            }
+            _deliver_result(job, "Clean output only.")
+
+        send_mock.assert_called_once()
+        sent_content = send_mock.call_args.kwargs.get("content") or send_mock.call_args[0][-1]
+        assert sent_content == "Clean output only."
+        assert "Cronjob Response" not in sent_content
+        assert "The agent cannot see" not in sent_content
+
    def test_no_mirror_to_session_call(self):
        """Cron deliveries should NOT mirror into the gateway session."""
        from gateway.config import Platform
@@ -13,7 +13,7 @@ def _would_warn():
                   "SIGNAL_ALLOWED_USERS", "SIGNAL_GROUP_ALLOWED_USERS",
                   "EMAIL_ALLOWED_USERS",
                   "SMS_ALLOWED_USERS", "MATTERMOST_ALLOWED_USERS",
-                   "MATRIX_ALLOWED_USERS", "DINGTALK_ALLOWED_USERS",
+                   "MATRIX_ALLOWED_USERS", "DINGTALK_ALLOWED_USERS", "FEISHU_ALLOWED_USERS", "WECOM_ALLOWED_USERS",
                   "GATEWAY_ALLOWED_USERS")
    )
    _allow_all = os.getenv("GATEWAY_ALLOW_ALL_USERS", "").lower() in ("true", "1", "yes") or any(
@@ -22,7 +22,7 @@ def _would_warn():
                   "WHATSAPP_ALLOW_ALL_USERS", "SLACK_ALLOW_ALL_USERS",
                   "SIGNAL_ALLOW_ALL_USERS", "EMAIL_ALLOW_ALL_USERS",
                   "SMS_ALLOW_ALL_USERS", "MATTERMOST_ALLOW_ALL_USERS",
-                   "MATRIX_ALLOW_ALL_USERS", "DINGTALK_ALLOW_ALL_USERS")
+                   "MATRIX_ALLOW_ALL_USERS", "DINGTALK_ALLOW_ALL_USERS", "FEISHU_ALLOW_ALL_USERS", "WECOM_ALLOW_ALL_USERS")
    )
    return not _any_allowlist and not _allow_all

@@ -15,6 +15,7 @@ class DummyTelegramAdapter(BasePlatformAdapter):
        super().__init__(PlatformConfig(enabled=True, token="fake-token"), Platform.TELEGRAM)
        self.sent = []
        self.typing = []
+        self.processing_hooks = []

    async def connect(self) -> bool:
        return True
@@ -40,6 +41,12 @@ class DummyTelegramAdapter(BasePlatformAdapter):
    async def get_chat_info(self, chat_id: str):
        return {"id": chat_id}

+    async def on_processing_start(self, event: MessageEvent) -> None:
+        self.processing_hooks.append(("start", event.message_id))
+
+    async def on_processing_complete(self, event: MessageEvent, success: bool) -> None:
+        self.processing_hooks.append(("complete", event.message_id, success))
+

 def _make_event(chat_id: str, thread_id: str, message_id: str = "1") -> MessageEvent:
    return MessageEvent(
@@ -133,3 +140,83 @@ class TestBasePlatformTopicSessions:
                "metadata": {"thread_id": "17585"},
            }
        ]
+        assert adapter.processing_hooks == [
+            ("start", "1"),
+            ("complete", "1", True),
+        ]
+
+    @pytest.mark.asyncio
+    async def test_process_message_background_marks_total_send_failure_unsuccessful(self):
+        adapter = DummyTelegramAdapter()
+
+        async def handler(_event):
+            await asyncio.sleep(0)
+            return "ack"
+
+        async def failing_send(*_args, **_kwargs):
+            return SendResult(success=False, error="send failed")
+
+        async def hold_typing(_chat_id, interval=2.0, metadata=None):
+            await asyncio.Event().wait()
+
+        adapter.set_message_handler(handler)
+        adapter.send = failing_send
+        adapter._keep_typing = hold_typing
+
+        event = _make_event("-1001", "17585")
+        await adapter._process_message_background(event, build_session_key(event.source))
+
+        assert adapter.processing_hooks == [
+            ("start", "1"),
+            ("complete", "1", False),
+        ]
+
+    @pytest.mark.asyncio
+    async def test_process_message_background_marks_exception_unsuccessful(self):
+        adapter = DummyTelegramAdapter()
+
+        async def handler(_event):
+            await asyncio.sleep(0)
+            raise RuntimeError("boom")
+
+        async def hold_typing(_chat_id, interval=2.0, metadata=None):
+            await asyncio.Event().wait()
+
+        adapter.set_message_handler(handler)
+        adapter._keep_typing = hold_typing
+
+        event = _make_event("-1001", "17585")
+        await adapter._process_message_background(event, build_session_key(event.source))
+
+        assert adapter.processing_hooks == [
+            ("start", "1"),
+            ("complete", "1", False),
+        ]
+
+    @pytest.mark.asyncio
+    async def test_process_message_background_marks_cancellation_unsuccessful(self):
+        adapter = DummyTelegramAdapter()
+        release = asyncio.Event()
+
+        async def handler(_event):
+            await release.wait()
+            return "ack"
+
+        async def hold_typing(_chat_id, interval=2.0, metadata=None):
+            await asyncio.Event().wait()
+
+        adapter.set_message_handler(handler)
+        adapter._keep_typing = hold_typing
+
+        event = _make_event("-1001", "17585")
+        task = asyncio.create_task(adapter._process_message_background(event, build_session_key(event.source)))
+        await asyncio.sleep(0)
+        task.cancel()
+
+        with pytest.raises(asyncio.CancelledError):
+            await task
+
+        assert adapter.processing_hooks == [
+            ("start", "1"),
+            ("complete", "1", False),
+        ]
@@ -1,11 +1,15 @@
 """Tests for gateway configuration management."""

+import os
+from unittest.mock import patch
+
 from gateway.config import (
    GatewayConfig,
    HomeChannel,
    Platform,
    PlatformConfig,
    SessionResetPolicy,
+    _apply_env_overrides,
    load_gateway_config,
 )

@@ -192,3 +196,75 @@ class TestLoadGatewayConfig:

        assert config.unauthorized_dm_behavior == "ignore"
        assert config.platforms[Platform.WHATSAPP].extra["unauthorized_dm_behavior"] == "pair"
+
+
+class TestHomeChannelEnvOverrides:
+    """Home channel env vars should apply even when the platform was already
+    configured via config.yaml (not just when credential env vars create it)."""
+
+    def test_existing_platform_configs_accept_home_channel_env_overrides(self):
+        cases = [
+            (
+                Platform.SLACK,
+                PlatformConfig(enabled=True, token="xoxb-from-config"),
+                {"SLACK_HOME_CHANNEL": "C123", "SLACK_HOME_CHANNEL_NAME": "Ops"},
+                ("C123", "Ops"),
+            ),
+            (
+                Platform.SIGNAL,
+                PlatformConfig(
+                    enabled=True,
+                    extra={"http_url": "http://localhost:9090", "account": "+15551234567"},
+                ),
+                {"SIGNAL_HOME_CHANNEL": "+1555000", "SIGNAL_HOME_CHANNEL_NAME": "Phone"},
+                ("+1555000", "Phone"),
+            ),
+            (
+                Platform.MATTERMOST,
+                PlatformConfig(
+                    enabled=True,
+                    token="mm-token",
+                    extra={"url": "https://mm.example.com"},
+                ),
+                {"MATTERMOST_HOME_CHANNEL": "ch_abc123", "MATTERMOST_HOME_CHANNEL_NAME": "General"},
+                ("ch_abc123", "General"),
+            ),
+            (
+                Platform.MATRIX,
+                PlatformConfig(
+                    enabled=True,
+                    token="syt_abc123",
+                    extra={"homeserver": "https://matrix.example.org"},
+                ),
+                {"MATRIX_HOME_ROOM": "!room123:example.org", "MATRIX_HOME_ROOM_NAME": "Bot Room"},
+                ("!room123:example.org", "Bot Room"),
+            ),
+            (
+                Platform.EMAIL,
+                PlatformConfig(
+                    enabled=True,
+                    extra={
+                        "address": "hermes@test.com",
+                        "imap_host": "imap.test.com",
+                        "smtp_host": "smtp.test.com",
+                    },
+                ),
+                {"EMAIL_HOME_ADDRESS": "user@test.com", "EMAIL_HOME_ADDRESS_NAME": "Inbox"},
+                ("user@test.com", "Inbox"),
+            ),
+            (
+                Platform.SMS,
+                PlatformConfig(enabled=True, api_key="token_abc"),
+                {"SMS_HOME_CHANNEL": "+15559876543", "SMS_HOME_CHANNEL_NAME": "My Phone"},
+                ("+15559876543", "My Phone"),
+            ),
+        ]
+
+        for platform, platform_config, env, expected in cases:
+            config = GatewayConfig(platforms={platform: platform_config})
+            with patch.dict(os.environ, env, clear=True):
+                _apply_env_overrides(config)
+
+            home = config.platforms[platform].home_channel
+            assert home is not None, f"{platform.value}: home_channel should not be None"
+            assert (home.chat_id, home.name) == expected, platform.value
@@ -0,0 +1,170 @@
+"""Tests for Discord message reactions tied to processing lifecycle hooks."""
+
+import asyncio
+import sys
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from gateway.config import Platform, PlatformConfig
+from gateway.platforms.base import MessageEvent, MessageType, SendResult
+from gateway.session import SessionSource, build_session_key
+
+
+def _ensure_discord_mock():
+    if "discord" in sys.modules and hasattr(sys.modules["discord"], "__file__"):
+        return
+
+    discord_mod = MagicMock()
+    discord_mod.Intents.default.return_value = MagicMock()
+    discord_mod.DMChannel = type("DMChannel", (), {})
+    discord_mod.Thread = type("Thread", (), {})
+    discord_mod.ForumChannel = type("ForumChannel", (), {})
+    discord_mod.Interaction = object
+    discord_mod.app_commands = SimpleNamespace(
+        describe=lambda **kwargs: (lambda fn: fn),
+        choices=lambda **kwargs: (lambda fn: fn),
+        Choice=lambda **kwargs: SimpleNamespace(**kwargs),
+    )
+
+    ext_mod = MagicMock()
+    commands_mod = MagicMock()
+    commands_mod.Bot = MagicMock
+    ext_mod.commands = commands_mod
+
+    sys.modules.setdefault("discord", discord_mod)
+    sys.modules.setdefault("discord.ext", ext_mod)
+    sys.modules.setdefault("discord.ext.commands", commands_mod)
+
+
+_ensure_discord_mock()
+
+from gateway.platforms.discord import DiscordAdapter  # noqa: E402
+
+
+class FakeTree:
+    def __init__(self):
+        self.commands = {}
+
+    def command(self, *, name, description):
+        def decorator(fn):
+            self.commands[name] = fn
+            return fn
+
+        return decorator
+
+
+@pytest.fixture
+def adapter():
+    config = PlatformConfig(enabled=True, token="***")
+    adapter = DiscordAdapter(config)
+    adapter._client = SimpleNamespace(
+        tree=FakeTree(),
+        get_channel=lambda _id: None,
+        fetch_channel=AsyncMock(),
+        user=SimpleNamespace(id=99999, name="HermesBot"),
+    )
+    return adapter
+
+
+def _make_event(message_id: str, raw_message) -> MessageEvent:
+    return MessageEvent(
+        text="hello",
+        message_type=MessageType.TEXT,
+        source=SessionSource(
+            platform=Platform.DISCORD,
+            chat_id="123",
+            chat_type="dm",
+            user_id="42",
+            user_name="Jezza",
+        ),
+        raw_message=raw_message,
+        message_id=message_id,
+    )
+
+
+@pytest.mark.asyncio
+async def test_process_message_background_adds_and_swaps_reactions(adapter):
+    raw_message = SimpleNamespace(
+        add_reaction=AsyncMock(),
+        remove_reaction=AsyncMock(),
+    )
+
+    async def handler(_event):
+        await asyncio.sleep(0)
+        return "ack"
+
+    async def hold_typing(_chat_id, interval=2.0, metadata=None):
+        await asyncio.Event().wait()
+
+    adapter.set_message_handler(handler)
+    adapter.send = AsyncMock(return_value=SendResult(success=True, message_id="999"))
+    adapter._keep_typing = hold_typing
+
+    event = _make_event("1", raw_message)
+    await adapter._process_message_background(event, build_session_key(event.source))
+
+    assert raw_message.add_reaction.await_args_list[0].args == ("👀",)
+    assert raw_message.remove_reaction.await_args_list[0].args == ("👀", adapter._client.user)
+    assert raw_message.add_reaction.await_args_list[1].args == ("✅",)
+
+
+@pytest.mark.asyncio
+async def test_interaction_backed_events_do_not_attempt_reactions(adapter):
+    interaction = SimpleNamespace(guild_id=123456789)
+
+    async def handler(_event):
+        await asyncio.sleep(0)
+        return None
+
+    async def hold_typing(_chat_id, interval=2.0, metadata=None):
+        await asyncio.Event().wait()
+
+    adapter.set_message_handler(handler)
+    adapter._add_reaction = AsyncMock()
+    adapter._remove_reaction = AsyncMock()
+    adapter._keep_typing = hold_typing
+
+    event = MessageEvent(
+        text="/status",
+        message_type=MessageType.COMMAND,
+        source=SessionSource(
+            platform=Platform.DISCORD,
+            chat_id="123",
+            chat_type="dm",
+            user_id="42",
+            user_name="Jezza",
+        ),
+        raw_message=interaction,
+        message_id="2",
+    )
+
+    await adapter._process_message_background(event, build_session_key(event.source))
+
+    adapter._add_reaction.assert_not_awaited()
+    adapter._remove_reaction.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_reaction_helper_failures_do_not_break_message_flow(adapter):
+    raw_message = SimpleNamespace(
+        add_reaction=AsyncMock(side_effect=[RuntimeError("no perms"), RuntimeError("no perms")]),
+        remove_reaction=AsyncMock(side_effect=RuntimeError("no perms")),
+    )
+
+    async def handler(_event):
+        await asyncio.sleep(0)
+        return "ack"
+
+    async def hold_typing(_chat_id, interval=2.0, metadata=None):
+        await asyncio.Event().wait()
+
+    adapter.set_message_handler(handler)
+    adapter.send = AsyncMock(return_value=SendResult(success=True, message_id="999"))
+    adapter._keep_typing = hold_typing
+
+    event = _make_event("3", raw_message)
+    await adapter._process_message_background(event, build_session_key(event.source))
+
+    adapter.send.assert_awaited_once()
@@ -1057,5 +1057,122 @@ class TestSendEmailStandalone(unittest.TestCase):
        self.assertIn("not configured", result["error"])


+class TestSmtpConnectionCleanup(unittest.TestCase):
+    """Verify SMTP connections are closed even when send_message raises."""
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+        "EMAIL_SMTP_PORT": "587",
+    }, clear=False)
+    def _make_adapter(self):
+        from gateway.config import PlatformConfig
+        from gateway.platforms.email import EmailAdapter
+        return EmailAdapter(PlatformConfig(enabled=True))
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+        "EMAIL_SMTP_PORT": "587",
+    }, clear=False)
+    def test_smtp_quit_called_on_send_message_failure(self):
+        """SMTP quit() must be called even when send_message() raises."""
+        adapter = self._make_adapter()
+        mock_smtp = MagicMock()
+        mock_smtp.send_message.side_effect = Exception("send failed")
+
+        with patch("smtplib.SMTP", return_value=mock_smtp):
+            with self.assertRaises(Exception):
+                adapter._send_email("user@test.com", "Hello")
+
+        mock_smtp.quit.assert_called_once()
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+        "EMAIL_SMTP_PORT": "587",
+    }, clear=False)
+    def test_smtp_close_called_when_quit_also_fails(self):
+        """If both send_message() and quit() fail, close() is the fallback."""
+        adapter = self._make_adapter()
+        mock_smtp = MagicMock()
+        mock_smtp.send_message.side_effect = Exception("send failed")
+        mock_smtp.quit.side_effect = Exception("quit failed")
+
+        with patch("smtplib.SMTP", return_value=mock_smtp):
+            with self.assertRaises(Exception):
+                adapter._send_email("user@test.com", "Hello")
+
+        mock_smtp.close.assert_called_once()
+
+
+class TestImapConnectionCleanup(unittest.TestCase):
+    """Verify IMAP connections are closed even when fetch raises."""
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_IMAP_PORT": "993",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+    }, clear=False)
+    def _make_adapter(self):
+        from gateway.config import PlatformConfig
+        from gateway.platforms.email import EmailAdapter
+        return EmailAdapter(PlatformConfig(enabled=True))
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_IMAP_PORT": "993",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+    }, clear=False)
+    def test_imap_logout_called_on_uid_fetch_failure(self):
+        """IMAP logout() must be called even when uid fetch raises."""
+        adapter = self._make_adapter()
+        mock_imap = MagicMock()
+
+        def uid_handler(command, *args):
+            if command == "search":
+                return ("OK", [b"1"])
+            if command == "fetch":
+                raise Exception("fetch failed")
+            return ("NO", [])
+
+        mock_imap.uid.side_effect = uid_handler
+
+        with patch("imaplib.IMAP4_SSL", return_value=mock_imap):
+            results = adapter._fetch_new_messages()
+
+        self.assertEqual(results, [])
+        mock_imap.logout.assert_called_once()
+
+    @patch.dict(os.environ, {
+        "EMAIL_ADDRESS": "hermes@test.com",
+        "EMAIL_PASSWORD": "secret",
+        "EMAIL_IMAP_HOST": "imap.test.com",
+        "EMAIL_IMAP_PORT": "993",
+        "EMAIL_SMTP_HOST": "smtp.test.com",
+    }, clear=False)
+    def test_imap_logout_called_on_early_return(self):
+        """IMAP logout() must be called even when returning early (no unseen)."""
+        adapter = self._make_adapter()
+        mock_imap = MagicMock()
+        mock_imap.uid.return_value = ("OK", [b""])
+
+        with patch("imaplib.IMAP4_SSL", return_value=mock_imap):
+            results = adapter._fetch_new_messages()
+
+        self.assertEqual(results, [])
+        mock_imap.logout.assert_called_once()
+
+
 if __name__ == "__main__":
    unittest.main()
@@ -29,13 +29,18 @@ class TestHookRegistryInit:
        assert reg._handlers == {}


+def _patch_no_builtins(reg):
+    """Suppress built-in hook registration so tests only exercise user-hook discovery."""
+    return patch.object(reg, "_register_builtin_hooks")
+
+
 class TestDiscoverAndLoad:
    def test_loads_valid_hook(self, tmp_path):
        _create_hook(tmp_path, "my-hook", '["agent:start"]',
                      "def handle(event_type, context):\n    pass\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 1
@@ -48,7 +53,7 @@ class TestDiscoverAndLoad:
        (hook_dir / "handler.py").write_text("def handle(e, c): pass\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 0
@@ -59,7 +64,7 @@ class TestDiscoverAndLoad:
        (hook_dir / "HOOK.yaml").write_text("name: bad\nevents: ['agent:start']\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 0
@@ -71,7 +76,7 @@ class TestDiscoverAndLoad:
        (hook_dir / "handler.py").write_text("def handle(e, c): pass\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 0
@@ -83,14 +88,14 @@ class TestDiscoverAndLoad:
        (hook_dir / "handler.py").write_text("def something_else(): pass\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 0

    def test_nonexistent_hooks_dir(self, tmp_path):
        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path / "nonexistent"):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path / "nonexistent"), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 0
@@ -102,7 +107,7 @@ class TestDiscoverAndLoad:
                      "def handle(e, c): pass\n")

        reg = HookRegistry()
-        with patch("gateway.hooks.HOOKS_DIR", tmp_path):
+        with patch("gateway.hooks.HOOKS_DIR", tmp_path), _patch_no_builtins(reg):
            reg.discover_and_load()

        assert len(reg.loaded_hooks) == 2
@@ -0,0 +1,340 @@
+"""Tests for Matrix voice message support (MSC3245)."""
+import io
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+nio = pytest.importorskip("nio", reason="matrix-nio not installed")
+
+from gateway.platforms.base import MessageType
+
+
+# ---------------------------------------------------------------------------
+# Adapter helpers
+# ---------------------------------------------------------------------------
+
+def _make_adapter():
+    """Create a MatrixAdapter with mocked config."""
+    from gateway.platforms.matrix import MatrixAdapter
+    from gateway.config import PlatformConfig
+    
+    config = PlatformConfig(
+        enabled=True,
+        token="***",
+        extra={
+            "homeserver": "https://matrix.example.org",
+            "user_id": "@bot:example.org",
+        },
+    )
+    adapter = MatrixAdapter(config)
+    return adapter
+
+
+def _make_room(room_id: str = "!test:example.org", member_count: int = 2):
+    """Create a mock Matrix room."""
+    room = MagicMock()
+    room.room_id = room_id
+    room.member_count = member_count
+    return room
+
+
+def _make_audio_event(
+    event_id: str = "$audio_event",
+    sender: str = "@alice:example.org",
+    body: str = "Voice message",
+    url: str = "mxc://example.org/abc123",
+    is_voice: bool = False,
+    mimetype: str = "audio/ogg",
+    timestamp: float = 9999999999000,  # ms
+):
+    """
+    Create a mock RoomMessageAudio event that passes isinstance checks.
+    
+    Args:
+        is_voice: If True, adds org.matrix.msc3245.voice field to content
+    """
+    import nio
+    
+    # Build the source dict that nio events expose via .source
+    content = {
+        "msgtype": "m.audio",
+        "body": body,
+        "url": url,
+        "info": {
+            "mimetype": mimetype,
+        },
+    }
+    
+    if is_voice:
+        content["org.matrix.msc3245.voice"] = {}
+    
+    # Create a real nio RoomMessageAudio-like object
+    # We use MagicMock but configure __class__ to pass isinstance check
+    event = MagicMock(spec=nio.RoomMessageAudio)
+    event.event_id = event_id
+    event.sender = sender
+    event.body = body
+    event.url = url
+    event.server_timestamp = timestamp
+    event.source = {
+        "type": "m.room.message",
+        "content": content,
+    }
+    # For MIME type extraction - needs to be a dict
+    event.content = content
+    
+    return event
+
+
+def _make_download_response(body: bytes = b"fake audio data"):
+    """Create a mock nio.MemoryDownloadResponse."""
+    import nio
+    resp = MagicMock()
+    resp.body = body
+    resp.__class__ = nio.MemoryDownloadResponse
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# Tests: MSC3245 Voice Detection (RED -> GREEN)
+# ---------------------------------------------------------------------------
+
+class TestMatrixVoiceMessageDetection:
+    """Test that MSC3245 voice messages are detected and tagged correctly."""
+
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._user_id = "@bot:example.org"
+        self.adapter._startup_ts = 0.0
+        self.adapter._dm_rooms = {}
+        self.adapter._message_handler = AsyncMock()
+        # Mock _mxc_to_http to return a fake HTTP URL
+        self.adapter._mxc_to_http = lambda url: f"https://matrix.example.org/_matrix/media/v3/download/{url[6:]}"
+        # Mock client for authenticated download
+        self.adapter._client = MagicMock()
+        self.adapter._client.download = AsyncMock(return_value=_make_download_response())
+
+    @pytest.mark.asyncio
+    async def test_voice_message_has_type_voice(self):
+        """Voice messages (with MSC3245 field) should be MessageType.VOICE."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=True)
+        
+        # Capture the MessageEvent passed to handle_message
+        captured_event = None
+        
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+        
+        self.adapter.handle_message = capture
+        
+        await self.adapter._on_room_message_media(room, event)
+        
+        assert captured_event is not None, "No event was captured"
+        assert captured_event.message_type == MessageType.VOICE, \
+            f"Expected MessageType.VOICE, got {captured_event.message_type}"
+
+    @pytest.mark.asyncio
+    async def test_voice_message_has_local_path(self):
+        """Voice messages should have a local cached path in media_urls."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=True)
+        
+        captured_event = None
+        
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+        
+        self.adapter.handle_message = capture
+        
+        await self.adapter._on_room_message_media(room, event)
+        
+        assert captured_event is not None
+        assert captured_event.media_urls is not None
+        assert len(captured_event.media_urls) > 0
+        # Should be a local path, not an HTTP URL
+        assert not captured_event.media_urls[0].startswith("http"), \
+            f"media_urls should contain local path, got {captured_event.media_urls[0]}"
+        self.adapter._client.download.assert_awaited_once_with(mxc=event.url)
+        assert captured_event.media_types == ["audio/ogg"]
+
+    @pytest.mark.asyncio
+    async def test_audio_without_msc3245_stays_audio_type(self):
+        """Regular audio uploads (no MSC3245 field) should remain MessageType.AUDIO."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=False)  # NOT a voice message
+        
+        captured_event = None
+        
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+        
+        self.adapter.handle_message = capture
+        
+        await self.adapter._on_room_message_media(room, event)
+        
+        assert captured_event is not None
+        assert captured_event.message_type == MessageType.AUDIO, \
+            f"Expected MessageType.AUDIO for non-voice, got {captured_event.message_type}"
+
+    @pytest.mark.asyncio
+    async def test_regular_audio_has_http_url(self):
+        """Regular audio uploads should keep HTTP URL (not cached locally)."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=False)
+        
+        captured_event = None
+        
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+        
+        self.adapter.handle_message = capture
+        
+        await self.adapter._on_room_message_media(room, event)
+        
+        assert captured_event is not None
+        assert captured_event.media_urls is not None
+        # Should be HTTP URL, not local path
+        assert captured_event.media_urls[0].startswith("http"), \
+            f"Non-voice audio should have HTTP URL, got {captured_event.media_urls[0]}"
+        self.adapter._client.download.assert_not_awaited()
+        assert captured_event.media_types == ["audio/ogg"]
+
+
+class TestMatrixVoiceCacheFallback:
+    """Test graceful fallback when voice caching fails."""
+
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._user_id = "@bot:example.org"
+        self.adapter._startup_ts = 0.0
+        self.adapter._dm_rooms = {}
+        self.adapter._message_handler = AsyncMock()
+        self.adapter._mxc_to_http = lambda url: f"https://matrix.example.org/_matrix/media/v3/download/{url[6:]}"
+        self.adapter._client = MagicMock()
+
+    @pytest.mark.asyncio
+    async def test_voice_cache_failure_falls_back_to_http_url(self):
+        """If caching fails, voice message should still be delivered with HTTP URL."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=True)
+        
+        # Make download fail
+        import nio
+        error_resp = MagicMock()
+        error_resp.__class__ = nio.DownloadError
+        self.adapter._client.download = AsyncMock(return_value=error_resp)
+        
+        captured_event = None
+        
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+        
+        self.adapter.handle_message = capture
+        
+        await self.adapter._on_room_message_media(room, event)
+        
+        assert captured_event is not None
+        assert captured_event.media_urls is not None
+        # Should fall back to HTTP URL
+        assert captured_event.media_urls[0].startswith("http"), \
+            f"Should fall back to HTTP URL on cache failure, got {captured_event.media_urls[0]}"
+
+    @pytest.mark.asyncio
+    async def test_voice_cache_exception_falls_back_to_http_url(self):
+        """Unexpected download exceptions should also fall back to HTTP URL."""
+        room = _make_room()
+        event = _make_audio_event(is_voice=True)
+
+        self.adapter._client.download = AsyncMock(side_effect=RuntimeError("boom"))
+
+        captured_event = None
+
+        async def capture(msg_event):
+            nonlocal captured_event
+            captured_event = msg_event
+
+        self.adapter.handle_message = capture
+
+        await self.adapter._on_room_message_media(room, event)
+
+        assert captured_event is not None
+        assert captured_event.media_urls is not None
+        assert captured_event.media_urls[0].startswith("http"), \
+            f"Should fall back to HTTP URL on exception, got {captured_event.media_urls[0]}"
+
+
+# ---------------------------------------------------------------------------
+# Tests: send_voice includes MSC3245 field (RED -> GREEN)
+# ---------------------------------------------------------------------------
+
+class TestMatrixSendVoiceMSC3245:
+    """Test that send_voice includes MSC3245 field for native voice rendering."""
+
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._user_id = "@bot:example.org"
+        # Mock client with successful upload
+        self.adapter._client = MagicMock()
+        self.upload_call = None
+
+        async def mock_upload(*args, **kwargs):
+            self.upload_call = (args, kwargs)
+            import nio
+            resp = MagicMock()
+            resp.content_uri = "mxc://example.org/uploaded"
+            resp.__class__ = nio.UploadResponse
+            return resp, None
+
+        self.adapter._client.upload = mock_upload
+
+    @pytest.mark.asyncio
+    async def test_send_voice_includes_msc3245_field(self):
+        """send_voice should include org.matrix.msc3245.voice in message content."""
+        import tempfile
+        import os
+        
+        # Create a temp audio file
+        with tempfile.NamedTemporaryFile(suffix=".ogg", delete=False) as f:
+            f.write(b"fake audio data")
+            temp_path = f.name
+        
+        try:
+            # Capture the message content sent to room_send
+            sent_content = None
+            
+            async def mock_room_send(room_id, event_type, content):
+                nonlocal sent_content
+                sent_content = content
+                resp = MagicMock()
+                resp.event_id = "$sent_event"
+                import nio
+                resp.__class__ = nio.RoomSendResponse
+                return resp
+            
+            self.adapter._client.room_send = mock_room_send
+            
+            await self.adapter.send_voice(
+                chat_id="!room:example.org",
+                audio_path=temp_path,
+                caption="Test voice",
+            )
+            
+            assert sent_content is not None, "No message was sent"
+            assert "org.matrix.msc3245.voice" in sent_content, \
+                f"MSC3245 voice field missing from content: {sent_content.keys()}"
+            assert sent_content["msgtype"] == "m.audio"
+            assert sent_content["info"]["mimetype"] == "audio/ogg"
+            assert self.upload_call is not None, "Expected upload() to be called"
+            args, kwargs = self.upload_call
+            assert isinstance(args[0], io.BytesIO)
+            assert kwargs["content_type"] == "audio/ogg"
+            assert kwargs["filename"].endswith(".ogg")
+
+        finally:
+            os.unlink(temp_path)
@@ -1,5 +1,6 @@
 """Tests for Mattermost platform adapter."""
 import json
+import os
 import time
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
@@ -269,6 +270,7 @@ class TestMattermostWebSocketParsing:
    def setup_method(self):
        self.adapter = _make_adapter()
        self.adapter._bot_user_id = "bot_user_id"
+        self.adapter._bot_username = "hermes-bot"
        # Mock handle_message to capture the MessageEvent without processing
        self.adapter.handle_message = AsyncMock()

@@ -293,7 +295,8 @@ class TestMattermostWebSocketParsing:
        await self.adapter._handle_ws_event(event)
        assert self.adapter.handle_message.called
        msg_event = self.adapter.handle_message.call_args[0][0]
-        assert msg_event.text == "@bot_user_id Hello from Matrix!"
+        # @mention is stripped from the message text
+        assert msg_event.text == "Hello from Matrix!"
        assert msg_event.message_id == "post_abc"

    @pytest.mark.asyncio
@@ -410,6 +413,87 @@ class TestMattermostWebSocketParsing:
        assert not self.adapter.handle_message.called


+# ---------------------------------------------------------------------------
+# Mention behavior (require_mention + free_response_channels)
+# ---------------------------------------------------------------------------
+
+class TestMattermostMentionBehavior:
+    def setup_method(self):
+        self.adapter = _make_adapter()
+        self.adapter._bot_user_id = "bot_user_id"
+        self.adapter._bot_username = "hermes-bot"
+        self.adapter.handle_message = AsyncMock()
+
+    def _make_event(self, message, channel_type="O", channel_id="chan_456"):
+        post_data = {
+            "id": "post_mention",
+            "user_id": "user_123",
+            "channel_id": channel_id,
+            "message": message,
+        }
+        return {
+            "event": "posted",
+            "data": {
+                "post": json.dumps(post_data),
+                "channel_type": channel_type,
+                "sender_name": "@alice",
+            },
+        }
+
+    @pytest.mark.asyncio
+    async def test_require_mention_true_skips_without_mention(self):
+        """Default: messages without @mention in channels are skipped."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            os.environ.pop("MATTERMOST_FREE_RESPONSE_CHANNELS", None)
+            await self.adapter._handle_ws_event(self._make_event("hello"))
+            assert not self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_require_mention_false_responds_to_all(self):
+        """MATTERMOST_REQUIRE_MENTION=false: respond to all channel messages."""
+        with patch.dict(os.environ, {"MATTERMOST_REQUIRE_MENTION": "false"}):
+            await self.adapter._handle_ws_event(self._make_event("hello"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_free_response_channel_responds_without_mention(self):
+        """Messages in free-response channels don't need @mention."""
+        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_456,chan_789"}):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_non_free_channel_still_requires_mention(self):
+        """Channels NOT in free-response list still require @mention."""
+        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_789"}):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
+            assert not self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_dm_always_responds(self):
+        """DMs (channel_type=D) always respond regardless of mention settings."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(self._make_event("hello", channel_type="D"))
+            assert self.adapter.handle_message.called
+
+    @pytest.mark.asyncio
+    async def test_mention_stripped_from_text(self):
+        """@mention is stripped from message text."""
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
+            await self.adapter._handle_ws_event(
+                self._make_event("@hermes-bot what is 2+2")
+            )
+            assert self.adapter.handle_message.called
+            msg = self.adapter.handle_message.call_args[0][0]
+            assert "@hermes-bot" not in msg.text
+            assert "2+2" in msg.text
+
+
 # ---------------------------------------------------------------------------
 # File upload (send_image)
 # ---------------------------------------------------------------------------
@@ -212,6 +212,49 @@ class TestSessionHygieneWarnThreshold:
        assert post_compress_tokens < warn_threshold


+class TestCompressionWarnRateLimit:
+    """Compression warning messages must be rate-limited per chat_id."""
+
+    def _make_runner(self):
+        from unittest.mock import MagicMock, patch
+        with patch("gateway.run.load_gateway_config"), \
+             patch("gateway.run.SessionStore"), \
+             patch("gateway.run.DeliveryRouter"):
+            from gateway.run import GatewayRunner
+            runner = GatewayRunner.__new__(GatewayRunner)
+            runner._compression_warn_sent = {}
+            runner._compression_warn_cooldown = 3600
+            return runner
+
+    def test_first_warn_is_sent(self):
+        runner = self._make_runner()
+        now = 1_000_000.0
+        last = runner._compression_warn_sent.get("chat:1", 0)
+        assert now - last >= runner._compression_warn_cooldown
+
+    def test_second_warn_suppressed_within_cooldown(self):
+        runner = self._make_runner()
+        now = 1_000_000.0
+        runner._compression_warn_sent["chat:1"] = now - 60  # 1 minute ago
+        last = runner._compression_warn_sent.get("chat:1", 0)
+        assert now - last < runner._compression_warn_cooldown
+
+    def test_warn_allowed_after_cooldown(self):
+        runner = self._make_runner()
+        now = 1_000_000.0
+        runner._compression_warn_sent["chat:1"] = now - 3601  # just past cooldown
+        last = runner._compression_warn_sent.get("chat:1", 0)
+        assert now - last >= runner._compression_warn_cooldown
+
+    def test_rate_limit_is_per_chat(self):
+        """Rate-limiting one chat must not suppress warnings for another."""
+        runner = self._make_runner()
+        now = 1_000_000.0
+        runner._compression_warn_sent["chat:1"] = now - 60  # suppressed
+        last_other = runner._compression_warn_sent.get("chat:2", 0)
+        assert now - last_other >= runner._compression_warn_cooldown
+
+
 class TestEstimatedTokenThreshold:
    """Verify that hygiene thresholds are always below the model's context
    limit — for both actual and estimated token counts.
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`"""Built-in gateway hooks that are always registered."""`
				`@@ -0,0 +1 @@`
				`Communication and decision-making frameworks — structured response formats for proposals, trade-off analysis, and stakeholder-ready recommendations.`