fix(model): preserve custom endpoint credentials and accept cloud models not in /v1/models

When switching models on a custom endpoint (ollama-launch):
- Same-provider switches no longer re-resolve credentials (fixes base_url
  being lost for 'custom' provider on subsequent switches)
- Named providers (ollama-launch) are resolved via user_providers so
  switch_model can find their base_url from config
- Models not in the /v1/models probe but present in the user's saved
  provider config are accepted with a warning instead of rejected
- CLI /model and TUI /model both pass user_providers/custom_providers
  to switch_model so the config model list is available for validation

Closes #15088

cli-config.yaml.example

@@ -790,9 +790,16 @@ code_execution:
 # Supports single tasks and batch mode (default 3 parallel, configurable).
 delegation:
   max_iterations: 50                          # Max tool-calling turns per child (default: 50)
-  # max_concurrent_children: 3                # Max parallel child agents (default: 3)
-  # max_spawn_depth: 1                        # Tree depth cap (1-3, default: 1 = flat). Raise to 2 or 3 to allow orchestrator children to spawn their own workers.
+  # max_concurrent_children: 3                # Max parallel child agents per batch (default: 3, floor: 1, no ceiling).
+                                              # WARNING: values above 10 multiply API cost linearly.
+  # max_spawn_depth: 1                        # Delegation tree depth cap (range: 1-3, default: 1 = flat).
+                                              # Raise to 2 to allow workers to spawn their own subagents.
+                                              # Requires role="orchestrator" on intermediate agents.
   # orchestrator_enabled: true                # Kill switch for role="orchestrator" children (default: true).
+  # subagent_auto_approve: false              # When a subagent hits a dangerous-command approval prompt, auto-deny (default: false)
+                                              # or auto-approve "once" (true) instead of blocking on stdin.
+                                              # The parent TUI owns stdin, so blocking would deadlock; non-interactive resolution is required.
+                                              # Both choices emit a logger.warning audit line. Flip to true only for cron/batch pipelines.
   # inherit_mcp_toolsets: true                # When explicit child toolsets are narrowed, also keep the parent's MCP toolsets (default: true). Set false for strict intersection.
   # model: "google/gemini-3-flash-preview"    # Override model for subagents (empty = inherit parent)
   # provider: "openrouter"                    # Override provider for subagents (empty = inherit parent)

cli.py

@@ -5270,24 +5270,22 @@ class HermesCLI:
         # Parse --provider and --global flags
         model_input, explicit_provider, persist_global = parse_model_flags(raw_args)
 
+        # Load providers for switch_model (picker path needs them below)
         user_provs = None
         custom_provs = None
+        try:
+            from hermes_cli.config import get_compatible_custom_providers, load_config
+            cfg = load_config()
+            user_provs = cfg.get("providers")
+            custom_provs = get_compatible_custom_providers(cfg)
+        except Exception:
+            pass
 
         # No args at all: open prompt_toolkit-native picker modal
         if not model_input and not explicit_provider:
             model_display = self.model or "unknown"
             provider_display = get_label(self.provider) if self.provider else "unknown"
 
-            user_provs = None
-            custom_provs = None
-            try:
-                from hermes_cli.config import get_compatible_custom_providers, load_config
-                cfg = load_config()
-                user_provs = cfg.get("providers")
-                custom_provs = get_compatible_custom_providers(cfg)
-            except Exception:
-                pass
-
             try:
                 providers = list_authenticated_providers(
                     current_provider=self.provider or "",

gateway/platforms/base.py

@@ -2543,9 +2543,6 @@ class BasePlatformAdapter(ABC):
         user_id_alt: Optional[str] = None,
         chat_id_alt: Optional[str] = None,
         is_bot: bool = False,
-        guild_id: Optional[str] = None,
-        parent_chat_id: Optional[str] = None,
-        message_id: Optional[str] = None,
     ) -> SessionSource:
         """Helper to build a SessionSource for this platform."""
         # Normalize empty topic to None
@@ -2563,9 +2560,6 @@ class BasePlatformAdapter(ABC):
             user_id_alt=user_id_alt,
             chat_id_alt=chat_id_alt,
             is_bot=is_bot,
-            guild_id=str(guild_id) if guild_id else None,
-            parent_chat_id=str(parent_chat_id) if parent_chat_id else None,
-            message_id=str(message_id) if message_id else None,
         )
     
     @abstractmethod

gateway/platforms/discord.py

@@ -3261,7 +3261,6 @@ class DiscordAdapter(BasePlatformAdapter):
             if auto_thread and not skip_thread and not is_voice_linked_channel and not is_reply_message:
                 thread = await self._auto_create_thread(message)
                 if thread:
-                    parent_channel_id = str(message.channel.id)
                     is_thread = True
                     thread_id = str(thread.id)
                     auto_threaded_channel = thread
@@ -3321,9 +3320,6 @@ class DiscordAdapter(BasePlatformAdapter):
             thread_id=thread_id,
             chat_topic=chat_topic,
             is_bot=getattr(message.author, "bot", False),
-            guild_id=str(message.guild.id) if message.guild else None,
-            parent_chat_id=parent_channel_id,
-            message_id=str(message.id),
         )
 
         # Build media URLs -- download image attachments to local cache so the

gateway/platforms/matrix.py

@@ -532,6 +532,20 @@ class MatrixAdapter(BasePlatformAdapter):
                 )
                 await crypto_store.open()
 
+                # Bind the store to the runtime device_id before any
+                # put_account() runs. PgCryptoStore defaults _device_id
+                # to "" and its crypto_account UPSERT never updates the
+                # device_id column on conflict — so once put_account
+                # writes blank, it stays blank forever. That breaks
+                # every downstream device-scoped olm operation: peer
+                # to-device ciphertext can't find our identity key and
+                # no megolm sessions ever land. Setting _device_id here
+                # (in-memory; the on-disk row may not exist yet) makes
+                # the first put_account write the correct value.
+                # DeviceID is a NewType(str) so plain str works at runtime.
+                if client.device_id:
+                    await crypto_store.put_device_id(client.device_id)
+
                 crypto_state = _CryptoStateStore(state_store, self._joined_rooms)
                 olm = OlmMachine(client, crypto_store, crypto_state)
 

gateway/session.py

@@ -87,9 +87,6 @@ class SessionSource:
     user_id_alt: Optional[str] = None  # Platform-specific stable alt ID (Signal UUID, Feishu union_id)
     chat_id_alt: Optional[str] = None  # Signal group internal ID
     is_bot: bool = False  # True when the message author is a bot/webhook (Discord)
-    guild_id: Optional[str] = None  # Discord guild / Slack workspace / Matrix server scope
-    parent_chat_id: Optional[str] = None  # Parent channel when chat_id refers to a thread
-    message_id: Optional[str] = None  # ID of the triggering message (for pin/reply/react)
     
     @property
     def description(self) -> str:
@@ -127,14 +124,8 @@ class SessionSource:
             d["user_id_alt"] = self.user_id_alt
         if self.chat_id_alt:
             d["chat_id_alt"] = self.chat_id_alt
-        if self.guild_id:
-            d["guild_id"] = self.guild_id
-        if self.parent_chat_id:
-            d["parent_chat_id"] = self.parent_chat_id
-        if self.message_id:
-            d["message_id"] = self.message_id
         return d
-
+    
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "SessionSource":
         return cls(
@@ -148,9 +139,6 @@ class SessionSource:
             chat_topic=data.get("chat_topic"),
             user_id_alt=data.get("user_id_alt"),
             chat_id_alt=data.get("chat_id_alt"),
-            guild_id=data.get("guild_id"),
-            parent_chat_id=data.get("parent_chat_id"),
-            message_id=data.get("message_id"),
         )
     
 
@@ -289,34 +277,14 @@ def build_session_context_prompt(
             "that you can only read messages sent directly to you and respond."
         )
     elif context.source.platform == Platform.DISCORD:
-        # The discord tool self-gates on DISCORD_BOT_TOKEN at registry
-        # check time.  Match that condition so the prompt stays honest:
-        # with a token the agent has fetch_messages/search_members/
-        # create_thread (and optionally discord_admin) and should know
-        # the IDs it can call them with; without one it really is
-        # limited to reading/replying via the gateway.
-        if (os.environ.get("DISCORD_BOT_TOKEN") or "").strip():
-            src = context.source
-            id_lines = ["", "**Discord IDs (for the `discord` / `discord_admin` tools):**"]
-            if src.guild_id:
-                id_lines.append(f"  - Guild: `{src.guild_id}`")
-            if src.thread_id and src.parent_chat_id:
-                id_lines.append(f"  - Parent channel: `{src.parent_chat_id}`")
-                id_lines.append(f"  - Thread: `{src.thread_id}` (use as `channel_id` for fetch_messages etc.)")
-            else:
-                id_lines.append(f"  - Channel: `{src.chat_id}`")
-            if src.message_id:
-                id_lines.append(f"  - Triggering message: `{src.message_id}`")
-            lines.extend(id_lines)
-        else:
-            lines.append("")
-            lines.append(
-                "**Platform notes:** You are running inside Discord. "
-                "You do NOT have access to Discord-specific APIs — you cannot search "
-                "channel history, pin messages, manage roles, or list server members. "
-                "Do not promise to perform these actions. If the user asks, explain "
-                "that you can only read messages sent directly to you and respond."
-            )
+        lines.append("")
+        lines.append(
+            "**Platform notes:** You are running inside Discord. "
+            "You do NOT have access to Discord-specific APIs — you cannot search "
+            "channel history, pin messages, manage roles, or list server members. "
+            "Do not promise to perform these actions. If the user asks, explain "
+            "that you can only read messages sent directly to you and respond."
+        )
     elif context.source.platform == Platform.BLUEBUBBLES:
         lines.append("")
         lines.append(

hermes_cli/config.py

@@ -783,6 +783,15 @@ DEFAULT_CONFIG = {
         # warning log if out of range.
         "max_spawn_depth": 1,        # depth cap (1 = flat [default], 2 = orchestrator→leaf, 3 = three-level)
         "orchestrator_enabled": True,  # kill switch for role="orchestrator"
+        # When a subagent hits a dangerous-command approval prompt, the parent's
+        # prompt_toolkit TUI owns stdin — a thread-local input() call from the
+        # subagent worker would deadlock the parent UI. To avoid the deadlock,
+        # subagent threads ALWAYS resolve approvals non-interactively:
+        #   false (default) → auto-deny with a logger.warning audit line (safe)
+        #   true             → auto-approve "once" with a logger.warning audit line
+        # Flip to true only if you trust delegated work to run dangerous cmds
+        # without human review (cron pipelines, batch automation, etc.).
+        "subagent_auto_approve": False,
     },
 
     # Ephemeral prefill messages file — JSON list of {role, content} dicts
@@ -839,7 +848,7 @@ DEFAULT_CONFIG = {
         "auto_thread": True,           # Auto-create threads on @mention in channels (like Slack)
         "reactions": True,             # Add 👀/✅/❌ reactions to messages during processing
         "channel_prompts": {},         # Per-channel ephemeral system prompts (forum parents apply to child threads)
-        # discord / discord_admin tools: restrict which actions the agent may call.
+        # discord_server tool: restrict which actions the agent may call.
         # Default (empty) = all actions allowed (subject to bot privileged intents).
         # Accepts comma-separated string ("list_guilds,list_channels,fetch_messages")
         # or YAML list. Unknown names are dropped with a warning at load time.

hermes_cli/model_switch.py

@@ -831,9 +831,14 @@ def switch_model(
                 requested=current_provider,
                 target_model=new_model,
             )
-            api_key = runtime.get("api_key", "")
-            base_url = runtime.get("base_url", "")
-            api_mode = runtime.get("api_mode", "")
+            # If resolution fell through to "custom" (e.g. named custom provider like
+            # "ollama-launch" that resolve_runtime_provider doesn't know), keep existing
+            # credentials. Otherwise use the resolved values (picks up credential rotation,
+            # base_url adjustments for OpenCode, etc.).
+            if runtime.get("provider") != "custom":
+                api_key = runtime.get("api_key", "")
+                base_url = runtime.get("base_url", "")
+                api_mode = runtime.get("api_mode", "")
         except Exception:
             pass
 
@@ -867,16 +872,31 @@ def switch_model(
             "message": f"Could not validate `{new_model}`: {e}",
         }
 
+    # Override rejection if model is in the user's saved provider config.
+    # API /v1/models may not list cloud/aliased models even though the server supports them.
     if not validation.get("accepted"):
-        msg = validation.get("message", "Invalid model")
-        return ModelSwitchResult(
-            success=False,
-            new_model=new_model,
-            target_provider=target_provider,
-            provider_label=provider_label,
-            is_global=is_global,
-            error_message=msg,
-        )
+        override = False
+        if user_providers:
+            for up in user_providers:
+                if isinstance(up, dict) and up.get("provider") == target_provider:
+                    cfg_models = up.get("models", [])
+                    if new_model in cfg_models or any(
+                        m.get("name") == new_model for m in cfg_models if isinstance(m, dict)
+                    ):
+                        override = True
+                        break
+        if override:
+            validation = {"accepted": True, "persist": True, "recognized": False, "message": validation.get("message", "")}
+        else:
+            msg = validation.get("message", "Invalid model")
+            return ModelSwitchResult(
+                success=False,
+                new_model=new_model,
+                target_provider=target_provider,
+                provider_label=provider_label,
+                is_global=is_global,
+                error_message=msg,
+            )
 
     # Apply auto-correction if validation found a closer match
     if validation.get("corrected_model"):

hermes_cli/models.py

@@ -2571,8 +2571,8 @@ def validate_requested_model(
                 )
 
             return {
-                "accepted": False,
-                "persist": False,
+                "accepted": True,
+                "persist": True,
                 "recognized": False,
                 "message": message,
             }

hermes_cli/tools_config.py

@@ -68,13 +68,12 @@ CONFIGURABLE_TOOLSETS = [
     ("rl",              "🧪 RL Training",               "Tinker-Atropos training tools"),
     ("homeassistant",    "🏠 Home Assistant",           "smart home device control"),
     ("spotify",          "🎵 Spotify",                  "playback, search, playlists, library"),
-    ("discord_admin",   "🛡️  Discord Server Admin",    "list channels/roles, pin, assign roles"),
 ]
 
 # Toolsets that are OFF by default for new installs.
 # They're still in _HERMES_CORE_TOOLS (available at runtime if enabled),
 # but the setup checklist won't pre-select them for first-time users.
-_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl", "spotify", "discord_admin"}
+_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl", "spotify"}
 
 
 def _get_effective_configurable_toolsets():
@@ -592,7 +591,7 @@ def _get_platform_tools(
     include_default_mcp_servers: bool = True,
 ) -> Set[str]:
     """Resolve which individual toolset names are enabled for a platform."""
-    from toolsets import resolve_toolset, TOOLSETS
+    from toolsets import resolve_toolset
 
     platform_toolsets = config.get("platform_toolsets") or {}
     toolset_names = platform_toolsets.get(platform)
@@ -606,8 +605,6 @@ def _get_platform_tools(
     toolset_names = [str(ts) for ts in toolset_names]
 
     configurable_keys = {ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS}
-    plugin_ts_keys = _get_plugin_toolset_keys()
-    platform_default_keys = {p["default_toolset"] for p in PLATFORMS.values()}
 
     # If the saved list contains any configurable keys directly, the user
     # has explicitly configured this platform — use direct membership.
@@ -630,42 +627,11 @@ def _get_platform_tools(
             ts_tools = set(resolve_toolset(ts_key))
             if ts_tools and ts_tools.issubset(all_tool_names):
                 enabled_toolsets.add(ts_key)
-
         default_off = set(_DEFAULT_OFF_TOOLSETS)
         if platform in default_off:
             default_off.remove(platform)
         enabled_toolsets -= default_off
 
-    # Recover non-configurable platform toolsets (e.g. discord, feishu_doc,
-    # feishu_drive).  These are part of the platform's default composite but
-    # absent from CONFIGURABLE_TOOLSETS, so they can't appear in the TUI
-    # checklist or in a user-saved config.  Must run in BOTH branches —
-    # otherwise saving via `hermes tools` (which flips has_explicit_config
-    # to True) silently drops them.
-    platform_tool_universe = set(resolve_toolset(PLATFORMS[platform]["default_toolset"]))
-    configurable_tool_universe = set()
-    for ck in configurable_keys:
-        configurable_tool_universe.update(resolve_toolset(ck))
-    claimed = set()
-    for ts_key in enabled_toolsets:
-        claimed.update(resolve_toolset(ts_key))
-    skip = configurable_keys | plugin_ts_keys | platform_default_keys
-    skip |= {k for k in TOOLSETS if k.startswith("hermes-")}
-    skip |= set(_DEFAULT_OFF_TOOLSETS) - {platform}
-    for ts_key, ts_def in TOOLSETS.items():
-        if ts_key in skip:
-            continue
-        if ts_def.get("includes"):
-            continue
-        ts_tools = set(resolve_toolset(ts_key))
-        if not ts_tools or not ts_tools.issubset(platform_tool_universe):
-            continue
-        if ts_tools.issubset(configurable_tool_universe):
-            continue
-        if not ts_tools.issubset(claimed):
-            enabled_toolsets.add(ts_key)
-            claimed.update(ts_tools)
-
     # Plugin toolsets: enabled by default unless explicitly disabled, or
     # unless the toolset is in _DEFAULT_OFF_TOOLSETS (e.g. spotify —
     # shipped as a bundled plugin but user must opt in via `hermes tools`
@@ -673,6 +639,7 @@ def _get_platform_tools(
     # A plugin toolset is "known" for a platform once `hermes tools`
     # has been saved for that platform (tracked via known_plugin_toolsets).
     # Unknown plugins default to enabled; known-but-absent = disabled.
+    plugin_ts_keys = _get_plugin_toolset_keys()
     if plugin_ts_keys:
         known_map = config.get("known_plugin_toolsets", {})
         known_for_platform = set(known_map.get(platform, []))
@@ -690,6 +657,7 @@ def _get_platform_tools(
 
     # Preserve any explicit non-configurable toolset entries (for example,
     # custom toolsets or MCP server names saved in platform_toolsets).
+    platform_default_keys = {p["default_toolset"] for p in PLATFORMS.values()}
     explicit_passthrough = {
         ts
         for ts in toolset_names

model_tools.py

@@ -288,34 +288,30 @@ def get_tool_definitions(
                 filtered_tools[i] = {"type": "function", "function": dynamic_schema}
                 break
 
-    # Rebuild discord / discord_admin schemas based on the bot's privileged
-    # intents (detected from GET /applications/@me) and the user's action
-    # allowlist in config.  Hides actions the bot's intents don't support so
-    # the model never attempts them, and annotates fetch_messages when the
+    # Rebuild discord_server schema based on the bot's privileged intents
+    # (detected from GET /applications/@me) and the user's action allowlist
+    # in config.  Hides actions the bot's intents don't support so the
+    # model never attempts them, and annotates fetch_messages when the
     # MESSAGE_CONTENT intent is missing.
-    _discord_schema_fns = {
-        "discord": "get_dynamic_schema_core",
-        "discord_admin": "get_dynamic_schema_admin",
-    }
-    for discord_tool_name in _discord_schema_fns:
-        if discord_tool_name in available_tool_names:
-            try:
-                from tools import discord_tool as _dt
-                schema_fn = getattr(_dt, _discord_schema_fns[discord_tool_name])
-                dynamic = schema_fn()
-            except Exception:
-                dynamic = None
-            if dynamic is None:
-                filtered_tools = [
-                    t for t in filtered_tools
-                    if t.get("function", {}).get("name") != discord_tool_name
-                ]
-                available_tool_names.discard(discord_tool_name)
-            else:
-                for i, td in enumerate(filtered_tools):
-                    if td.get("function", {}).get("name") == discord_tool_name:
-                        filtered_tools[i] = {"type": "function", "function": dynamic}
-                        break
+    if "discord_server" in available_tool_names:
+        try:
+            from tools.discord_tool import get_dynamic_schema
+            dynamic = get_dynamic_schema()
+        except Exception:  # pragma: no cover — defensive, fall back to static
+            dynamic = None
+        if dynamic is None:
+            # Tool filtered out entirely (empty allowlist or detection disabled
+            # the only remaining actions).  Drop it from the schema list.
+            filtered_tools = [
+                t for t in filtered_tools
+                if t.get("function", {}).get("name") != "discord_server"
+            ]
+            available_tool_names.discard("discord_server")
+        else:
+            for i, td in enumerate(filtered_tools):
+                if td.get("function", {}).get("name") == "discord_server":
+                    filtered_tools[i] = {"type": "function", "function": dynamic}
+                    break
 
     # Strip web tool cross-references from browser_navigate description when
     # web_search / web_extract are not available.  The static schema says

scripts/release.py

@@ -503,6 +503,7 @@ AUTHOR_MAP = {
     "codex@openai.invalid": "teknium1",
     "screenmachine@gmail.com": "teknium1",
     "chenzeshi@live.com": "chen1749144759",
+    "mor.aleksandr@yahoo.com": "MorAlekss",
 }
 
 

tests/gateway/test_matrix.py

@@ -197,10 +197,14 @@ def _make_fake_mautrix():
             self.account_id = account_id
             self.pickle_key = pickle_key
             self.db = db
+            self._device_id = ""
 
         async def open(self):
             pass
 
+        async def put_device_id(self, device_id):
+            self._device_id = device_id
+
     mautrix_crypto_store_asyncpg.PgCryptoStore = PgCryptoStore
 
     # --- mautrix.util ---

tests/hermes_cli/test_tools_config.py

@@ -601,72 +601,3 @@ class TestImagegenModelPicker:
             _configure_imagegen_model("fal", config)
         assert isinstance(config["image_gen"], dict)
         assert config["image_gen"]["model"] == "fal-ai/flux-2/klein/9b"
-
-
-def test_get_platform_tools_recovers_non_configurable_toolsets_from_composite():
-    """Non-configurable toolsets whose tools are in the composite but not in
-    CONFIGURABLE_TOOLSETS should still appear in the result.
-    """
-    from toolsets import TOOLSETS
-    from hermes_cli.tools_config import PLATFORMS
-    from unittest.mock import patch as mock_patch
-
-    fake_toolsets = dict(TOOLSETS)
-    fake_toolsets["_test_platform_tool"] = {
-        "description": "test",
-        "tools": ["_test_special_tool"],
-        "includes": [],
-    }
-    fake_toolsets["hermes-_test_platform"] = {
-        "description": "test composite",
-        "tools": ["web_search", "web_extract", "terminal", "process", "_test_special_tool"],
-        "includes": [],
-    }
-
-    test_platforms = {
-        "_test_platform": {"label": "Test", "default_toolset": "hermes-_test_platform"},
-    }
-
-    with mock_patch("hermes_cli.tools_config.PLATFORMS", {**PLATFORMS, **test_platforms}):
-        with mock_patch("toolsets.TOOLSETS", fake_toolsets):
-            enabled = _get_platform_tools({}, "_test_platform")
-
-    assert "_test_platform_tool" in enabled
-    assert "web" in enabled
-    assert "terminal" in enabled
-
-
-def test_get_platform_tools_second_pass_skips_fully_claimed_toolsets():
-    """Toolsets whose tools are fully covered by configurable keys should NOT
-    be added by the second pass (prevents 'search', 'hermes-acp' noise).
-    """
-    enabled = _get_platform_tools({}, "cli")
-
-    assert "search" not in enabled
-
-
-def test_get_platform_tools_discord_includes_discord_not_admin():
-    enabled = _get_platform_tools({}, "discord")
-    assert "discord" in enabled
-    assert "discord_admin" not in enabled
-
-
-def test_discord_admin_in_configurable_toolsets():
-    assert any(ts_key == "discord_admin" for ts_key, _, _ in CONFIGURABLE_TOOLSETS)
-
-
-def test_discord_admin_in_default_off():
-    assert "discord_admin" in _DEFAULT_OFF_TOOLSETS
-
-
-def test_get_platform_tools_feishu_includes_doc_and_drive():
-    enabled = _get_platform_tools({}, "feishu")
-    assert "feishu_doc" in enabled
-    assert "feishu_drive" in enabled
-
-
-def test_get_platform_tools_feishu_tools_not_on_other_platforms():
-    for plat in ["cli", "telegram", "discord"]:
-        enabled = _get_platform_tools({}, plat)
-        assert "feishu_doc" not in enabled, f"feishu_doc leaked onto {plat}"
-        assert "feishu_drive" not in enabled, f"feishu_drive leaked onto {plat}"

tests/test_toolsets.py

@@ -200,8 +200,8 @@ class TestToolsetConsistency:
     def test_hermes_platforms_share_core_tools(self):
         """All hermes-* platform toolsets share the same core tools.
 
-        Platform-specific additions (e.g. ``discord`` / ``discord_admin``
-        on hermes-discord, gated on DISCORD_BOT_TOKEN) are allowed on top —
+        Platform-specific additions (e.g. ``discord_server`` on
+        hermes-discord, gated on DISCORD_BOT_TOKEN) are allowed on top —
         the invariant is that the core set is identical across platforms.
         """
         platforms = ["hermes-cli", "hermes-telegram", "hermes-discord", "hermes-whatsapp", "hermes-slack", "hermes-signal", "hermes-homeassistant"]

tests/tools/test_delegate.py

@@ -2128,5 +2128,103 @@ class TestOrchestratorEndToEnd(unittest.TestCase):
         self.assertFalse(built_agents[2]["is_orchestrator_prompt"])
 
 
+class TestSubagentApprovalCallback(unittest.TestCase):
+    """Subagent worker threads must have a non-interactive approval callback
+    installed so dangerous-command prompts don't fall back to input() and
+    deadlock the parent's prompt_toolkit TUI.
+
+    Governed by delegation.subagent_auto_approve:
+      false (default) → _subagent_auto_deny
+      true            → _subagent_auto_approve
+    """
+
+    def test_auto_deny_returns_deny(self):
+        from tools.delegate_tool import _subagent_auto_deny
+        self.assertEqual(
+            _subagent_auto_deny("rm -rf /tmp/x", "dangerous"),
+            "deny",
+        )
+
+    def test_auto_approve_returns_once(self):
+        from tools.delegate_tool import _subagent_auto_approve
+        self.assertEqual(
+            _subagent_auto_approve("rm -rf /tmp/x", "dangerous"),
+            "once",
+        )
+
+    @patch("tools.delegate_tool._load_config", return_value={})
+    def test_getter_defaults_to_deny(self, _mock_cfg):
+        from tools.delegate_tool import (
+            _get_subagent_approval_callback,
+            _subagent_auto_deny,
+        )
+        self.assertIs(_get_subagent_approval_callback(), _subagent_auto_deny)
+
+    @patch(
+        "tools.delegate_tool._load_config",
+        return_value={"subagent_auto_approve": False},
+    )
+    def test_getter_explicit_false_is_deny(self, _mock_cfg):
+        from tools.delegate_tool import (
+            _get_subagent_approval_callback,
+            _subagent_auto_deny,
+        )
+        self.assertIs(_get_subagent_approval_callback(), _subagent_auto_deny)
+
+    @patch(
+        "tools.delegate_tool._load_config",
+        return_value={"subagent_auto_approve": True},
+    )
+    def test_getter_true_is_approve(self, _mock_cfg):
+        from tools.delegate_tool import (
+            _get_subagent_approval_callback,
+            _subagent_auto_approve,
+        )
+        self.assertIs(_get_subagent_approval_callback(), _subagent_auto_approve)
+
+    @patch(
+        "tools.delegate_tool._load_config",
+        return_value={"subagent_auto_approve": "yes"},
+    )
+    def test_getter_truthy_string_is_approve(self, _mock_cfg):
+        """is_truthy_value accepts 'yes'/'1'/'true' as truthy."""
+        from tools.delegate_tool import (
+            _get_subagent_approval_callback,
+            _subagent_auto_approve,
+        )
+        self.assertIs(_get_subagent_approval_callback(), _subagent_auto_approve)
+
+    def test_executor_initializer_installs_callback_in_worker(self):
+        """The initializer sets the callback on the worker thread's TLS,
+        not the parent's — verifies the fix actually scopes to workers.
+        """
+        from concurrent.futures import ThreadPoolExecutor
+        from tools.terminal_tool import (
+            set_approval_callback as _set_cb,
+            _get_approval_callback,
+        )
+        from tools.delegate_tool import _subagent_auto_deny
+
+        # Parent thread has no callback.
+        _set_cb(None)
+        self.assertIsNone(_get_approval_callback())
+
+        seen = []
+
+        def worker():
+            seen.append(_get_approval_callback())
+
+        with ThreadPoolExecutor(
+            max_workers=1,
+            initializer=_set_cb,
+            initargs=(_subagent_auto_deny,),
+        ) as executor:
+            executor.submit(worker).result()
+
+        self.assertEqual(seen, [_subagent_auto_deny])
+        # Parent's callback slot is still empty (TLS isolates threads).
+        self.assertIsNone(_get_approval_callback())
+
+
 if __name__ == "__main__":
     unittest.main()

tests/tools/test_discord_tool.py

@@ -11,8 +11,6 @@ import pytest
 from tools.discord_tool import (
     DiscordAPIError,
     _ACTIONS,
-    _ADMIN_ACTIONS,
-    _CORE_ACTIONS,
     _available_actions,
     _build_schema,
     _channel_type_name,
@@ -23,11 +21,8 @@ from tools.discord_tool import (
     _load_allowed_actions_config,
     _reset_capability_cache,
     check_discord_tool_requirements,
-    discord_admin_handler,
-    discord_core,
+    discord_server,
     get_dynamic_schema,
-    get_dynamic_schema_admin,
-    get_dynamic_schema_core,
 )
 
 
@@ -152,32 +147,32 @@ class TestDiscordRequest:
 class TestDiscordServerValidation:
     def test_no_token(self, monkeypatch):
         monkeypatch.delenv("DISCORD_BOT_TOKEN", raising=False)
-        result = json.loads(discord_admin_handler(action="list_guilds"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert "error" in result
         assert "DISCORD_BOT_TOKEN" in result["error"]
 
     def test_unknown_action(self, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
-        result = json.loads(discord_core(action="bad_action"))
+        result = json.loads(discord_server(action="bad_action"))
         assert "error" in result
         assert "Unknown action" in result["error"]
         assert "available_actions" in result
 
     def test_missing_required_guild_id(self, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
-        result = json.loads(discord_admin_handler(action="list_channels"))
+        result = json.loads(discord_server(action="list_channels"))
         assert "error" in result
         assert "guild_id" in result["error"]
 
     def test_missing_required_channel_id(self, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
-        result = json.loads(discord_core(action="fetch_messages"))
+        result = json.loads(discord_server(action="fetch_messages"))
         assert "error" in result
         assert "channel_id" in result["error"]
 
     def test_missing_multiple_params(self, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
-        result = json.loads(discord_admin_handler(action="add_role"))
+        result = json.loads(discord_server(action="add_role"))
         assert "error" in result
         assert "guild_id" in result["error"]
         assert "user_id" in result["error"]
@@ -196,7 +191,7 @@ class TestListGuilds:
             {"id": "111", "name": "Test Server", "icon": "abc", "owner": True, "permissions": "123"},
             {"id": "222", "name": "Other Server", "icon": None, "owner": False, "permissions": "456"},
         ]
-        result = json.loads(discord_admin_handler(action="list_guilds"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert result["count"] == 2
         assert result["guilds"][0]["name"] == "Test Server"
         assert result["guilds"][1]["id"] == "222"
@@ -224,7 +219,7 @@ class TestServerInfo:
             "premium_subscription_count": 5,
             "verification_level": 1,
         }
-        result = json.loads(discord_admin_handler(action="server_info", guild_id="111"))
+        result = json.loads(discord_server(action="server_info", guild_id="111"))
         assert result["name"] == "My Server"
         assert result["member_count"] == 42
         assert result["online_count"] == 10
@@ -247,7 +242,7 @@ class TestListChannels:
             {"id": "12", "name": "voice", "type": 2, "position": 1, "parent_id": "10", "topic": None, "nsfw": False},
             {"id": "13", "name": "no-category", "type": 0, "position": 0, "parent_id": None, "topic": None, "nsfw": False},
         ]
-        result = json.loads(discord_admin_handler(action="list_channels", guild_id="111"))
+        result = json.loads(discord_server(action="list_channels", guild_id="111"))
         assert result["total_channels"] == 3  # excludes the category itself
         groups = result["channel_groups"]
         # Uncategorized first
@@ -262,7 +257,7 @@ class TestListChannels:
     def test_empty_guild(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = []
-        result = json.loads(discord_admin_handler(action="list_channels", guild_id="111"))
+        result = json.loads(discord_server(action="list_channels", guild_id="111"))
         assert result["total_channels"] == 0
 
 
@@ -279,7 +274,7 @@ class TestChannelInfo:
             "topic": "Welcome!", "nsfw": False, "position": 0,
             "parent_id": "10", "rate_limit_per_user": 0, "last_message_id": "999",
         }
-        result = json.loads(discord_admin_handler(action="channel_info", channel_id="11"))
+        result = json.loads(discord_server(action="channel_info", channel_id="11"))
         assert result["name"] == "general"
         assert result["type"] == "text"
         assert result["guild_id"] == "111"
@@ -298,7 +293,7 @@ class TestListRoles:
             {"id": "2", "name": "Admin", "position": 2, "color": 16711680, "mentionable": True, "managed": False, "hoist": True},
             {"id": "3", "name": "Mod", "position": 1, "color": 255, "mentionable": True, "managed": False, "hoist": True},
         ]
-        result = json.loads(discord_admin_handler(action="list_roles", guild_id="111"))
+        result = json.loads(discord_server(action="list_roles", guild_id="111"))
         assert result["count"] == 3
         # Should be sorted by position descending
         assert result["roles"][0]["name"] == "Admin"
@@ -322,7 +317,7 @@ class TestMemberInfo:
             "joined_at": "2024-01-01T00:00:00Z",
             "premium_since": None,
         }
-        result = json.loads(discord_admin_handler(action="member_info", guild_id="111", user_id="42"))
+        result = json.loads(discord_server(action="member_info", guild_id="111", user_id="42"))
         assert result["username"] == "testuser"
         assert result["nickname"] == "Testy"
         assert result["roles"] == ["2", "3"]
@@ -339,7 +334,7 @@ class TestSearchMembers:
         mock_req.return_value = [
             {"user": {"id": "42", "username": "testuser", "global_name": "Test", "bot": False}, "nick": None, "roles": []},
         ]
-        result = json.loads(discord_core(action="search_members", guild_id="111", query="test"))
+        result = json.loads(discord_server(action="search_members", guild_id="111", query="test"))
         assert result["count"] == 1
         assert result["members"][0]["username"] == "testuser"
         mock_req.assert_called_once_with(
@@ -351,7 +346,7 @@ class TestSearchMembers:
     def test_search_members_limit_capped(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = []
-        discord_core(action="search_members", guild_id="111", query="x", limit=200)
+        discord_server(action="search_members", guild_id="111", query="x", limit=200)
         call_params = mock_req.call_args[1]["params"]
         assert call_params["limit"] == "100"  # Capped at 100
 
@@ -375,7 +370,7 @@ class TestFetchMessages:
                 "pinned": False,
             },
         ]
-        result = json.loads(discord_core(action="fetch_messages", channel_id="11"))
+        result = json.loads(discord_server(action="fetch_messages", channel_id="11"))
         assert result["count"] == 1
         assert result["messages"][0]["content"] == "Hello world"
         assert result["messages"][0]["author"]["username"] == "user1"
@@ -384,7 +379,7 @@ class TestFetchMessages:
     def test_fetch_messages_with_pagination(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = []
-        discord_core(action="fetch_messages", channel_id="11", before="999", limit=10)
+        discord_server(action="fetch_messages", channel_id="11", before="999", limit=10)
         call_params = mock_req.call_args[1]["params"]
         assert call_params["before"] == "999"
         assert call_params["limit"] == "10"
@@ -401,7 +396,7 @@ class TestListPins:
         mock_req.return_value = [
             {"id": "500", "content": "Important announcement", "author": {"username": "admin"}, "timestamp": "2024-01-01T00:00:00Z"},
         ]
-        result = json.loads(discord_admin_handler(action="list_pins", channel_id="11"))
+        result = json.loads(discord_server(action="list_pins", channel_id="11"))
         assert result["count"] == 1
         assert result["pinned_messages"][0]["content"] == "Important announcement"
 
@@ -415,7 +410,7 @@ class TestPinUnpin:
     def test_pin_message(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = None  # 204
-        result = json.loads(discord_admin_handler(action="pin_message", channel_id="11", message_id="500"))
+        result = json.loads(discord_server(action="pin_message", channel_id="11", message_id="500"))
         assert result["success"] is True
         mock_req.assert_called_once_with("PUT", "/channels/11/pins/500", "test-token")
 
@@ -423,7 +418,7 @@ class TestPinUnpin:
     def test_unpin_message(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = None
-        result = json.loads(discord_admin_handler(action="unpin_message", channel_id="11", message_id="500"))
+        result = json.loads(discord_server(action="unpin_message", channel_id="11", message_id="500"))
         assert result["success"] is True
 
 
@@ -436,7 +431,7 @@ class TestCreateThread:
     def test_create_standalone_thread(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = {"id": "800", "name": "New Thread"}
-        result = json.loads(discord_core(action="create_thread", channel_id="11", name="New Thread"))
+        result = json.loads(discord_server(action="create_thread", channel_id="11", name="New Thread"))
         assert result["success"] is True
         assert result["thread_id"] == "800"
         # Verify the API call
@@ -449,7 +444,7 @@ class TestCreateThread:
     def test_create_thread_from_message(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = {"id": "801", "name": "Discussion"}
-        result = json.loads(discord_core(
+        result = json.loads(discord_server(
             action="create_thread", channel_id="11", name="Discussion", message_id="1001",
         ))
         assert result["success"] is True
@@ -468,7 +463,7 @@ class TestRoleManagement:
     def test_add_role(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = None
-        result = json.loads(discord_admin_handler(
+        result = json.loads(discord_server(
             action="add_role", guild_id="111", user_id="42", role_id="2",
         ))
         assert result["success"] is True
@@ -480,7 +475,7 @@ class TestRoleManagement:
     def test_remove_role(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.return_value = None
-        result = json.loads(discord_admin_handler(
+        result = json.loads(discord_server(
             action="remove_role", guild_id="111", user_id="42", role_id="2",
         ))
         assert result["success"] is True
@@ -495,23 +490,15 @@ class TestErrorHandling:
     def test_api_error_handled(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.side_effect = DiscordAPIError(403, '{"message": "Missing Access"}')
-        result = json.loads(discord_admin_handler(action="list_guilds"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert "error" in result
         assert "403" in result["error"]
 
     @patch("tools.discord_tool._discord_request")
-    def test_unexpected_error_handled_admin(self, mock_req, monkeypatch):
+    def test_unexpected_error_handled(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
         mock_req.side_effect = RuntimeError("something broke")
-        result = json.loads(discord_admin_handler(action="list_guilds"))
-        assert "error" in result
-        assert "something broke" in result["error"]
-
-    @patch("tools.discord_tool._discord_request")
-    def test_unexpected_error_handled_core(self, mock_req, monkeypatch):
-        monkeypatch.setenv("DISCORD_BOT_TOKEN", "test-token")
-        mock_req.side_effect = RuntimeError("something broke")
-        result = json.loads(discord_core(action="fetch_messages", channel_id="11"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert "error" in result
         assert "something broke" in result["error"]
 
@@ -521,109 +508,79 @@ class TestErrorHandling:
 # ---------------------------------------------------------------------------
 
 class TestRegistration:
-    def test_core_tool_registered(self):
+    def test_tool_registered(self):
         from tools.registry import registry
-        entry = registry._tools.get("discord")
+        entry = registry._tools.get("discord_server")
         assert entry is not None
-        assert entry.schema["name"] == "discord"
+        assert entry.schema["name"] == "discord_server"
         assert entry.toolset == "discord"
         assert entry.check_fn is not None
         assert entry.requires_env == ["DISCORD_BOT_TOKEN"]
 
-    def test_admin_tool_registered(self):
+    def test_schema_actions(self):
+        """Static schema should list all actions (the model_tools post-processing
+        narrows this per-session; static registration is the superset)."""
         from tools.registry import registry
-        entry = registry._tools.get("discord_admin")
-        assert entry is not None
-        assert entry.schema["name"] == "discord_admin"
-        assert entry.toolset == "discord_admin"
-        assert entry.check_fn is not None
-        assert entry.requires_env == ["DISCORD_BOT_TOKEN"]
-
-    def test_core_schema_actions(self):
-        """Core static schema should list only core actions."""
-        from tools.registry import registry
-        entry = registry._tools["discord"]
-        actions = set(entry.schema["parameters"]["properties"]["action"]["enum"])
-        assert actions == {"fetch_messages", "search_members", "create_thread"}
-
-    def test_admin_schema_actions(self):
-        """Admin static schema should list only admin actions."""
-        from tools.registry import registry
-        entry = registry._tools["discord_admin"]
-        actions = set(entry.schema["parameters"]["properties"]["action"]["enum"])
-        expected_admin = set(_ACTIONS.keys()) - {"fetch_messages", "search_members", "create_thread"}
-        assert actions == expected_admin
-
-    def test_all_actions_covered(self):
-        """Core + admin actions should cover all known actions."""
-        assert set(_CORE_ACTIONS.keys()) | set(_ADMIN_ACTIONS.keys()) == set(_ACTIONS.keys())
-        assert set(_CORE_ACTIONS.keys()) & set(_ADMIN_ACTIONS.keys()) == set()
+        entry = registry._tools["discord_server"]
+        actions = entry.schema["parameters"]["properties"]["action"]["enum"]
+        expected = [
+            "list_guilds", "server_info", "list_channels", "channel_info",
+            "list_roles", "member_info", "search_members", "fetch_messages",
+            "list_pins", "pin_message", "unpin_message", "create_thread",
+            "add_role", "remove_role",
+        ]
+        assert set(actions) == set(expected)
+        assert set(_ACTIONS.keys()) == set(expected)
 
     def test_schema_parameter_bounds(self):
         from tools.registry import registry
-        entry = registry._tools["discord"]
+        entry = registry._tools["discord_server"]
         props = entry.schema["parameters"]["properties"]
         assert props["limit"]["minimum"] == 1
         assert props["limit"]["maximum"] == 100
         assert props["auto_archive_duration"]["enum"] == [60, 1440, 4320, 10080]
 
-    def test_core_schema_description(self):
-        """Core schema description should mention core actions."""
+    def test_schema_description_is_action_manifest(self):
+        """The top-level description should include the action manifest
+        (one-line signatures per action) so the model can find required
+        params without re-reading every parameter description."""
         from tools.registry import registry
-        entry = registry._tools["discord"]
-        desc = entry.schema["description"]
-        assert "fetch_messages(channel_id)" in desc
-        assert "search_members(guild_id, query)" in desc
-        assert "create_thread(channel_id, name)" in desc
-        # Admin actions should NOT be in core description
-        assert "list_guilds()" not in desc
-        assert "add_role(" not in desc
-
-    def test_admin_schema_description(self):
-        """Admin schema description should mention admin actions."""
-        from tools.registry import registry
-        entry = registry._tools["discord_admin"]
+        entry = registry._tools["discord_server"]
         desc = entry.schema["description"]
+        # Spot-check a few entries
         assert "list_guilds()" in desc
+        assert "fetch_messages(channel_id)" in desc
         assert "add_role(guild_id, user_id, role_id)" in desc
-        # Core actions should NOT be in admin description
-        assert "fetch_messages(" not in desc
-        assert "create_thread(" not in desc
 
     def test_handler_callable(self):
         from tools.registry import registry
-        entry = registry._tools["discord"]
+        entry = registry._tools["discord_server"]
         assert callable(entry.handler)
-        entry_admin = registry._tools["discord_admin"]
-        assert callable(entry_admin.handler)
 
 
 # ---------------------------------------------------------------------------
-# Toolset: discord / discord_admin only in hermes-discord
+# Toolset: discord_server only in hermes-discord
 # ---------------------------------------------------------------------------
 
 class TestToolsetInclusion:
-    def test_discord_tools_in_hermes_discord_toolset(self):
+    def test_discord_server_in_hermes_discord_toolset(self):
         from toolsets import TOOLSETS
-        assert "discord" in TOOLSETS["hermes-discord"]["tools"]
-        assert "discord_admin" in TOOLSETS["hermes-discord"]["tools"]
+        assert "discord_server" in TOOLSETS["hermes-discord"]["tools"]
 
-    def test_discord_tools_not_in_core_tools(self):
+    def test_discord_server_not_in_core_tools(self):
         from toolsets import _HERMES_CORE_TOOLS
-        assert "discord" not in _HERMES_CORE_TOOLS
-        assert "discord_admin" not in _HERMES_CORE_TOOLS
+        assert "discord_server" not in _HERMES_CORE_TOOLS
 
-    def test_discord_tools_not_in_other_toolsets(self):
+    def test_discord_server_not_in_other_toolsets(self):
         from toolsets import TOOLSETS
         for name, ts in TOOLSETS.items():
-            if name in ("hermes-discord", "hermes-gateway", "discord", "discord_admin"):
+            if name == "hermes-discord":
                 continue
-            tools = ts.get("tools", [])
-            assert "discord" not in tools or name == "discord", (
-                f"discord tool should not be in toolset '{name}'"
-            )
-            assert "discord_admin" not in tools or name == "discord_admin", (
-                f"discord_admin tool should not be in toolset '{name}'"
+            # The gateway toolset might include it if it unions all platform tools
+            if name == "hermes-gateway":
+                continue
+            assert "discord_server" not in ts.get("tools", []), (
+                f"discord_server should not be in toolset '{name}'"
             )
 
 
@@ -841,69 +798,40 @@ class TestDynamicSchema:
     @patch("tools.discord_tool._discord_request")
     def test_no_token_returns_none(self, mock_req, monkeypatch):
         monkeypatch.delenv("DISCORD_BOT_TOKEN", raising=False)
-        assert get_dynamic_schema_core() is None
-        assert get_dynamic_schema_admin() is None
+        assert get_dynamic_schema() is None
         mock_req.assert_not_called()
 
     @patch("tools.discord_tool._discord_request")
-    def test_full_intents_core_schema(self, mock_req, monkeypatch):
+    def test_full_intents_full_schema(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
         monkeypatch.setattr(
             "hermes_cli.config.load_config",
             lambda: {"discord": {"server_actions": ""}},
         )
         mock_req.return_value = {"flags": (1 << 14) | (1 << 18)}
-        schema = get_dynamic_schema_core()
-        actions = set(schema["parameters"]["properties"]["action"]["enum"])
-        assert actions == set(_CORE_ACTIONS.keys())
-        assert schema["name"] == "discord"
-
-    @patch("tools.discord_tool._discord_request")
-    def test_full_intents_admin_schema(self, mock_req, monkeypatch):
-        monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
-        monkeypatch.setattr(
-            "hermes_cli.config.load_config",
-            lambda: {"discord": {"server_actions": ""}},
-        )
-        mock_req.return_value = {"flags": (1 << 14) | (1 << 18)}
-        schema = get_dynamic_schema_admin()
-        actions = set(schema["parameters"]["properties"]["action"]["enum"])
-        assert actions == set(_ADMIN_ACTIONS.keys())
-        assert schema["name"] == "discord_admin"
-        # No content warning when MESSAGE_CONTENT is enabled
+        schema = get_dynamic_schema()
+        actions = schema["parameters"]["properties"]["action"]["enum"]
+        assert set(actions) == set(_ACTIONS.keys())
+        # No content warning
         assert "MESSAGE_CONTENT" not in schema["description"]
 
     @patch("tools.discord_tool._discord_request")
-    def test_no_members_intent_removes_member_actions_from_admin_schema(
+    def test_no_members_intent_removes_member_actions_from_schema(
         self, mock_req, monkeypatch,
     ):
-        """member_info is an admin action; it should be hidden when
-        GUILD_MEMBERS intent is missing."""
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
         monkeypatch.setattr(
             "hermes_cli.config.load_config",
             lambda: {"discord": {"server_actions": ""}},
         )
         mock_req.return_value = {"flags": 1 << 18}  # only MESSAGE_CONTENT
-        schema = get_dynamic_schema_admin()
-        actions = schema["parameters"]["properties"]["action"]["enum"]
-        assert "member_info" not in actions
-        assert "member_info" not in schema["description"]
-
-    @patch("tools.discord_tool._discord_request")
-    def test_no_members_intent_hides_search_members_from_core(
-        self, mock_req, monkeypatch,
-    ):
-        """search_members is a core action gated by GUILD_MEMBERS intent."""
-        monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
-        monkeypatch.setattr(
-            "hermes_cli.config.load_config",
-            lambda: {"discord": {"server_actions": ""}},
-        )
-        mock_req.return_value = {"flags": 1 << 18}  # only MESSAGE_CONTENT
-        schema = get_dynamic_schema_core()
+        schema = get_dynamic_schema()
         actions = schema["parameters"]["properties"]["action"]["enum"]
         assert "search_members" not in actions
+        assert "member_info" not in actions
+        # Manifest description should also not advertise them
+        assert "search_members" not in schema["description"]
+        assert "member_info" not in schema["description"]
 
     @patch("tools.discord_tool._discord_request")
     def test_no_message_content_adds_warning_note(self, mock_req, monkeypatch):
@@ -913,53 +841,41 @@ class TestDynamicSchema:
             lambda: {"discord": {"server_actions": ""}},
         )
         mock_req.return_value = {"flags": 1 << 14}  # only GUILD_MEMBERS
-        schema = get_dynamic_schema_core()
+        schema = get_dynamic_schema()
         assert "MESSAGE_CONTENT" in schema["description"]
         # But fetch_messages is still available
         actions = schema["parameters"]["properties"]["action"]["enum"]
         assert "fetch_messages" in actions
 
     @patch("tools.discord_tool._discord_request")
-    def test_config_allowlist_narrows_admin_schema(self, mock_req, monkeypatch):
+    def test_config_allowlist_narrows_schema(self, mock_req, monkeypatch):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
         monkeypatch.setattr(
             "hermes_cli.config.load_config",
             lambda: {"discord": {"server_actions": "list_guilds,list_channels"}},
         )
         mock_req.return_value = {"flags": (1 << 14) | (1 << 18)}
-        schema = get_dynamic_schema_admin()
+        schema = get_dynamic_schema()
         actions = schema["parameters"]["properties"]["action"]["enum"]
         assert actions == ["list_guilds", "list_channels"]
+        # Manifest description should only show allowed ones (check for
+        # the signature marker, which is specific to manifest lines)
         assert "list_guilds()" in schema["description"]
         assert "add_role(" not in schema["description"]
+        assert "create_thread(" not in schema["description"]
 
     @patch("tools.discord_tool._discord_request")
-    def test_empty_allowlist_with_valid_values_hides_tools(self, mock_req, monkeypatch):
+    def test_empty_allowlist_with_valid_values_hides_tool(self, mock_req, monkeypatch):
         """If the allowlist resolves to zero valid actions (e.g. all names
-        were typos), get_dynamic_schema returns None so the tool is dropped."""
+        were typos), get_dynamic_schema returns None so the tool is dropped
+        entirely rather than showing an empty enum."""
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
         monkeypatch.setattr(
             "hermes_cli.config.load_config",
             lambda: {"discord": {"server_actions": "typo_one,typo_two"}},
         )
         mock_req.return_value = {"flags": (1 << 14) | (1 << 18)}
-        assert get_dynamic_schema_core() is None
-        assert get_dynamic_schema_admin() is None
-
-    @patch("tools.discord_tool._discord_request")
-    def test_backward_compat_wrapper(self, mock_req, monkeypatch):
-        """get_dynamic_schema() should delegate to get_dynamic_schema_core()."""
-        monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
-        monkeypatch.setattr(
-            "hermes_cli.config.load_config",
-            lambda: {"discord": {"server_actions": ""}},
-        )
-        mock_req.return_value = {"flags": (1 << 14) | (1 << 18)}
-        schema = get_dynamic_schema()
-        assert schema is not None
-        assert schema["name"] == "discord"
-        actions = set(schema["parameters"]["properties"]["action"]["enum"])
-        assert actions == set(_CORE_ACTIONS.keys())
+        assert get_dynamic_schema() is None
 
 
 # ---------------------------------------------------------------------------
@@ -974,7 +890,7 @@ class TestRuntimeAllowlistEnforcement:
             "hermes_cli.config.load_config",
             lambda: {"discord": {"server_actions": "list_guilds"}},
         )
-        result = json.loads(discord_admin_handler(action="add_role", guild_id="1", user_id="2", role_id="3"))
+        result = json.loads(discord_server(action="add_role", guild_id="1", user_id="2", role_id="3"))
         assert "error" in result
         assert "disabled by config" in result["error"]
         mock_req.assert_not_called()
@@ -987,7 +903,7 @@ class TestRuntimeAllowlistEnforcement:
             lambda: {"discord": {"server_actions": "list_guilds"}},
         )
         mock_req.return_value = []
-        result = json.loads(discord_admin_handler(action="list_guilds"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert "guilds" in result
 
 
@@ -1014,7 +930,7 @@ class Test403Enrichment:
             lambda: {"discord": {"server_actions": ""}},
         )
         mock_req.side_effect = DiscordAPIError(403, '{"message":"Missing Permissions"}')
-        result = json.loads(discord_admin_handler(
+        result = json.loads(discord_server(
             action="add_role", guild_id="1", user_id="2", role_id="3",
         ))
         assert "error" in result
@@ -1028,7 +944,7 @@ class Test403Enrichment:
             lambda: {"discord": {"server_actions": ""}},
         )
         mock_req.side_effect = DiscordAPIError(500, "server error")
-        result = json.loads(discord_admin_handler(action="list_guilds"))
+        result = json.loads(discord_server(action="list_guilds"))
         assert "500" in result["error"]
         assert "MANAGE_ROLES" not in result["error"]
 
@@ -1045,10 +961,10 @@ class TestModelToolsIntegration:
         _reset_capability_cache()
 
     @patch("tools.discord_tool._discord_request")
-    def test_discord_admin_schema_rebuilt_by_get_tool_definitions(
+    def test_discord_server_schema_rebuilt_by_get_tool_definitions(
         self, mock_req, monkeypatch,
     ):
-        """When model_tools.get_tool_definitions runs with discord_admin
+        """When model_tools.get_tool_definitions runs with discord_server
         available, it should replace the static schema with the dynamic one."""
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
         monkeypatch.setattr(
@@ -1060,16 +976,16 @@ class TestModelToolsIntegration:
 
         from model_tools import get_tool_definitions
         tools = get_tool_definitions(enabled_toolsets=["hermes-discord"], quiet_mode=True)
-        discord_admin_tool = next(
-            (t for t in tools if t.get("function", {}).get("name") == "discord_admin"),
+        discord_tool = next(
+            (t for t in tools if t.get("function", {}).get("name") == "discord_server"),
             None,
         )
-        assert discord_admin_tool is not None, "discord_admin should be in the schema"
-        actions = discord_admin_tool["function"]["parameters"]["properties"]["action"]["enum"]
+        assert discord_tool is not None, "discord_server should be in the schema"
+        actions = discord_tool["function"]["parameters"]["properties"]["action"]["enum"]
         assert actions == ["list_guilds", "server_info"]
 
     @patch("tools.discord_tool._discord_request")
-    def test_discord_tools_dropped_when_allowlist_empties_them(
+    def test_discord_server_dropped_when_allowlist_empties_it(
         self, mock_req, monkeypatch,
     ):
         monkeypatch.setenv("DISCORD_BOT_TOKEN", "tok")
@@ -1082,6 +998,4 @@ class TestModelToolsIntegration:
         from model_tools import get_tool_definitions
         tools = get_tool_definitions(enabled_toolsets=["hermes-discord"], quiet_mode=True)
         names = [t.get("function", {}).get("name") for t in tools]
-        assert "discord" not in names
-        assert "discord_admin" not in names
         assert "discord_server" not in names

tools/delegate_tool.py

@@ -33,6 +33,7 @@ from typing import Any, Dict, List, Optional
 
 from toolsets import TOOLSETS
 from tools import file_state
+from tools.terminal_tool import set_approval_callback as _set_subagent_approval_cb
 from utils import base_url_hostname, is_truthy_value
 
 
@@ -47,6 +48,64 @@ DELEGATE_BLOCKED_TOOLS = frozenset(
     ]
 )
 
+
+# ---------------------------------------------------------------------------
+# Subagent approval callbacks
+# ---------------------------------------------------------------------------
+# Subagents run inside a ThreadPoolExecutor worker. The CLI's interactive
+# approval callback is stored in tools/terminal_tool.py's threading.local(),
+# so worker threads do NOT inherit it. Without a callback,
+# prompt_dangerous_approval() falls back to input() from the worker thread,
+# which deadlocks against the parent's prompt_toolkit TUI that owns stdin.
+#
+# Fix: install a non-interactive callback into every subagent worker thread
+# via ThreadPoolExecutor(initializer=_set_subagent_approval_cb, initargs=(cb,)).
+# The callback is chosen by the `delegation.subagent_auto_approve` config:
+#   false (default) → _subagent_auto_deny (safe; matches leaf tool blocklist)
+#   true            → _subagent_auto_approve (opt-in YOLO for cron/batch)
+# Both emit a logger.warning for audit; gateway sessions are unaffected
+# because they resolve approvals via tools/approval.py's per-session queue,
+# not through these TLS callbacks.
+def _subagent_auto_deny(command: str, description: str, **kwargs) -> str:
+    """Auto-deny dangerous commands in subagent threads (safe default).
+
+    Returns 'deny' so the subagent sees a refusal it can recover from, and
+    never calls input() (which would deadlock the parent TUI).
+    """
+    logger.warning(
+        "Subagent auto-denied dangerous command: %s (%s). "
+        "Set delegation.subagent_auto_approve: true to allow.",
+        command, description,
+    )
+    return "deny"
+
+
+def _subagent_auto_approve(command: str, description: str, **kwargs) -> str:
+    """Auto-approve dangerous commands in subagent threads (opt-in YOLO).
+
+    Only installed when delegation.subagent_auto_approve=true. Returns 'once'
+    so the subagent proceeds without blocking the parent UI.
+    """
+    logger.warning(
+        "Subagent auto-approved dangerous command: %s (%s)",
+        command, description,
+    )
+    return "once"
+
+
+def _get_subagent_approval_callback():
+    """Return the callback to install into subagent worker threads.
+
+    Config key: delegation.subagent_auto_approve (bool, default False).
+    Reads via the same _load_config() path as the rest of delegate_task so
+    priority is config.yaml > (no env override for this knob) > default.
+    """
+    cfg = _load_config()
+    val = cfg.get("subagent_auto_approve", False)
+    if is_truthy_value(val):
+        return _subagent_auto_approve
+    return _subagent_auto_deny
+
 # Build a description fragment listing toolsets available for subagents.
 # Excludes toolsets where ALL tools are blocked, composite/platform toolsets
 # (hermes-* prefixed), and scenario toolsets.
@@ -276,7 +335,14 @@ def _get_max_concurrent_children() -> int:
     val = cfg.get("max_concurrent_children")
     if val is not None:
         try:
-            return max(1, int(val))
+            result = max(1, int(val))
+            if result > 10:
+                logger.warning(
+                    "delegation.max_concurrent_children=%d: each child consumes API tokens "
+                    "independently. High values multiply cost linearly.",
+                    result,
+                )
+            return result
         except (TypeError, ValueError):
             logger.warning(
                 "delegation.max_concurrent_children=%r is not a valid integer; "
@@ -1337,7 +1403,15 @@ def _run_single_child(
         # Run child with a hard timeout to prevent indefinite blocking
         # when the child's API call or tool-level HTTP request hangs.
         child_timeout = _get_child_timeout()
-        _timeout_executor = ThreadPoolExecutor(max_workers=1)
+        _timeout_executor = ThreadPoolExecutor(
+            max_workers=1,
+            # Install a non-interactive approval callback in the worker thread
+            # so dangerous-command prompts from the subagent don't fall back to
+            # input() and deadlock the parent's prompt_toolkit TUI.
+            # Callback (deny vs approve) is governed by delegation.subagent_auto_approve.
+            initializer=_set_subagent_approval_cb,
+            initargs=(_get_subagent_approval_callback(),),
+        )
         # Capture the worker thread so the timeout diagnostic can dump its
         # Python stack (see #14726 — 0-API-call hangs are opaque without it).
         _worker_thread_holder: Dict[str, Optional[threading.Thread]] = {"t": None}
@@ -2229,8 +2303,8 @@ DELEGATE_TASK_SCHEMA = {
         "never enter your context window.\n\n"
         "TWO MODES (one of 'goal' or 'tasks' is required):\n"
         "1. Single task: provide 'goal' (+ optional context, toolsets)\n"
-        "2. Batch (parallel): provide 'tasks' array with up to delegation.max_concurrent_children items (default 3). "
-        "All run concurrently and results are returned together.\n\n"
+        "2. Batch (parallel): provide 'tasks' array with up to delegation.max_concurrent_children items (default 3, configurable via config.yaml, no hard ceiling). "
+        "All run concurrently and results are returned together. Nested delegation requires role='orchestrator' and delegation.max_spawn_depth >= 2.\n\n"
         "WHEN TO USE delegate_task:\n"
         "- Reasoning-heavy subtasks (debugging, code review, research synthesis)\n"
         "- Tasks that would flood your context with intermediate data\n"

tools/discord_tool.py

@@ -473,12 +473,6 @@ _ACTIONS = {
     "remove_role": _remove_role,
 }
 
-_CORE_ACTION_NAMES = frozenset({"fetch_messages", "search_members", "create_thread"})
-_ADMIN_ACTION_NAMES = frozenset(_ACTIONS.keys()) - _CORE_ACTION_NAMES
-
-_CORE_ACTIONS = {k: v for k, v in _ACTIONS.items() if k in _CORE_ACTION_NAMES}
-_ADMIN_ACTIONS = {k: v for k, v in _ACTIONS.items() if k in _ADMIN_ACTION_NAMES}
-
 # Single-source-of-truth manifest: action → (signature, one-line description).
 # Consumed by :func:`_build_schema` so the schema's top-level description
 # always matches the registered action set.
@@ -537,7 +531,7 @@ def _load_allowed_actions_config() -> Optional[List[str]]:
         from hermes_cli.config import load_config
         cfg = load_config()
     except Exception as exc:
-        logger.debug("discord: could not load config (%s); allowing all actions.", exc)
+        logger.debug("discord_server: could not load config (%s); allowing all actions.", exc)
         return None
 
     raw = (cfg.get("discord") or {}).get("server_actions")
@@ -592,16 +586,12 @@ def _available_actions(
 def _build_schema(
     actions: List[str],
     caps: Optional[Dict[str, Any]] = None,
-    tool_name: str = "discord",
-) -> Optional[Dict[str, Any]]:
-    """Build the tool schema for the given filtered action list.
-
-    Returns ``None`` when *actions* is empty — callers should drop the
-    tool from registration in that case.
-    """
+) -> Dict[str, Any]:
+    """Build the tool schema for the given filtered action list."""
     caps = caps or {}
     if not actions:
-        return None
+        # Tool shouldn't be registered when empty, but guard anyway.
+        actions = list(_ACTIONS.keys())
 
     # Action manifest lines (action-first, parameter-scoped).
     manifest_lines = [
@@ -612,36 +602,24 @@ def _build_schema(
     manifest_block = "\n".join(manifest_lines)
 
     content_note = ""
-    affected_actions = {"fetch_messages", "list_pins"} & set(actions)
-    if affected_actions and caps.get("detected") and caps.get("has_message_content") is False:
-        names = " and ".join(sorted(affected_actions))
+    if caps.get("detected") and caps.get("has_message_content") is False:
         content_note = (
-            f"\n\nNOTE: Bot does NOT have the MESSAGE_CONTENT privileged intent. "
-            f"{names} will return message metadata (author, "
+            "\n\nNOTE: Bot does NOT have the MESSAGE_CONTENT privileged intent. "
+            "fetch_messages and list_pins will return message metadata (author, "
             "timestamps, attachments, reactions, pin state) but `content` will be "
             "empty for messages not sent as a direct mention to the bot or in DMs. "
             "Enable the intent in the Discord Developer Portal to see all content."
         )
 
-    if tool_name == "discord_admin":
-        description = (
-            "Manage a Discord server via the REST API.\n\n"
-            "Available actions:\n"
-            f"{manifest_block}\n\n"
-            "Call list_guilds first to discover guild_ids, then list_channels for "
-            "channel_ids. Runtime errors will tell you if the bot lacks a specific "
-            "per-guild permission (e.g. MANAGE_ROLES for add_role)."
-            f"{content_note}"
-        )
-    else:
-        description = (
-            "Read and participate in a Discord server.\n\n"
-            "Available actions:\n"
-            f"{manifest_block}\n\n"
-            "Use the channel_id from the current conversation context. "
-            "Use search_members to look up user IDs by name prefix."
-            f"{content_note}"
-        )
+    description = (
+        "Query and manage a Discord server via the REST API.\n\n"
+        "Available actions:\n"
+        f"{manifest_block}\n\n"
+        "Call list_guilds first to discover guild_ids, then list_channels for "
+        "channel_ids. Runtime errors will tell you if the bot lacks a specific "
+        "per-guild permission (e.g. MANAGE_ROLES for add_role)."
+        f"{content_note}"
+    )
 
     properties: Dict[str, Any] = {
         "action": {
@@ -698,7 +676,7 @@ def _build_schema(
     }
 
     return {
-        "name": tool_name,
+        "name": "discord_server",
         "description": description,
         "parameters": {
             "type": "object",
@@ -708,33 +686,28 @@ def _build_schema(
     }
 
 
-def _get_dynamic_schema(
-    action_subset: Dict[str, Any],
-    tool_name: str,
-) -> Optional[Dict[str, Any]]:
-    """Build a dynamic schema for *action_subset* filtered by intents + config."""
+def get_dynamic_schema() -> Optional[Dict[str, Any]]:
+    """Return a schema filtered by current intents + config allowlist.
+
+    Called by ``model_tools.get_tool_definitions`` as a post-processing
+    step so the schema the model sees always reflects reality. Returns
+    ``None`` when no actions are available (tool should be removed from
+    the schema list entirely).
+    """
     token = _get_bot_token()
     if not token:
         return None
+
     caps = _detect_capabilities(token)
     allowlist = _load_allowed_actions_config()
-    actions = [a for a in _available_actions(caps, allowlist) if a in action_subset]
+    actions = _available_actions(caps, allowlist)
     if not actions:
+        logger.warning(
+            "discord_server: config allowlist/intents left zero available actions; "
+            "hiding tool from this session."
+        )
         return None
-    return _build_schema(actions, caps, tool_name=tool_name)
-
-
-def get_dynamic_schema_core() -> Optional[Dict[str, Any]]:
-    return _get_dynamic_schema(_CORE_ACTIONS, "discord")
-
-
-def get_dynamic_schema_admin() -> Optional[Dict[str, Any]]:
-    return _get_dynamic_schema(_ADMIN_ACTIONS, "discord_admin")
-
-
-def get_dynamic_schema() -> Optional[Dict[str, Any]]:
-    """Backward-compat wrapper — returns core schema."""
-    return get_dynamic_schema_core()
+    return _build_schema(actions, caps)
 
 
 # ---------------------------------------------------------------------------
@@ -801,13 +774,11 @@ def check_discord_tool_requirements() -> bool:
 
 
 # ---------------------------------------------------------------------------
-# Handlers
+# Main handler
 # ---------------------------------------------------------------------------
 
-def _run_discord_action(
+def discord_server(
     action: str,
-    valid_actions: Dict[str, Any],
-    tool_label: str,
     guild_id: str = "",
     channel_id: str = "",
     user_id: str = "",
@@ -819,17 +790,18 @@ def _run_discord_action(
     before: str = "",
     after: str = "",
     auto_archive_duration: int = 1440,
+    task_id: str = None,
 ) -> str:
-    """Shared handler logic for both discord tools."""
+    """Execute a Discord server action."""
     token = _get_bot_token()
     if not token:
         return json.dumps({"error": "DISCORD_BOT_TOKEN not configured."})
 
-    action_fn = valid_actions.get(action)
+    action_fn = _ACTIONS.get(action)
     if not action_fn:
         return json.dumps({
             "error": f"Unknown action: {action}",
-            "available_actions": list(valid_actions.keys()),
+            "available_actions": list(_ACTIONS.keys()),
         })
 
     # Config-level allowlist gate (defense in depth — schema already filtered,
@@ -876,64 +848,44 @@ def _run_discord_action(
             auto_archive_duration=auto_archive_duration,
         )
     except DiscordAPIError as e:
-        logger.warning("Discord API error in %s action '%s': %s", tool_label, action, e)
+        logger.warning("Discord API error in action '%s': %s", action, e)
         if e.status == 403:
             return json.dumps({"error": _enrich_403(action, e.body)})
         return json.dumps({"error": str(e)})
     except Exception as e:
-        logger.exception("Unexpected error in %s action '%s'", tool_label, action)
+        logger.exception("Unexpected error in discord_server action '%s'", action)
         return json.dumps({"error": f"Unexpected error: {e}"})
 
 
-def discord_core(action: str, **kwargs) -> str:
-    """Execute a core Discord action (fetch_messages, search_members, create_thread)."""
-    return _run_discord_action(action, _CORE_ACTIONS, "discord", **kwargs)
-
-
-def discord_admin_handler(action: str, **kwargs) -> str:
-    """Execute a Discord admin action (server management)."""
-    return _run_discord_action(action, _ADMIN_ACTIONS, "discord_admin", **kwargs)
-
-
 # ---------------------------------------------------------------------------
 # Tool registration
 # ---------------------------------------------------------------------------
 
-_HANDLER_DEFAULTS = {
-    "action": "", "guild_id": "", "channel_id": "", "user_id": "",
-    "role_id": "", "message_id": "", "query": "", "name": "",
-    "limit": 50, "before": "", "after": "", "auto_archive_duration": 1440,
-}
-
-
-def _make_handler(handler_fn):
-    """Create a registry-compatible handler lambda for a discord handler."""
-    return lambda args, **kw: handler_fn(
-        **{k: args.get(k, v) for k, v in _HANDLER_DEFAULTS.items()},
-    )
-
-
-_STATIC_CORE_SCHEMA = _build_schema(
-    list(_CORE_ACTIONS.keys()), caps={"detected": False}, tool_name="discord",
-)
-_STATIC_ADMIN_SCHEMA = _build_schema(
-    list(_ADMIN_ACTIONS.keys()), caps={"detected": False}, tool_name="discord_admin",
-)
+# Register with the full unfiltered schema. ``model_tools.get_tool_definitions``
+# rebuilds this per-session via ``get_dynamic_schema`` so the model only ever
+# sees intent-available, config-allowed actions. The static registration is a
+# safe baseline for tools that inspect the registry directly.
+_STATIC_SCHEMA = _build_schema(list(_ACTIONS.keys()), caps={"detected": False})
 
 registry.register(
-    name="discord",
+    name="discord_server",
     toolset="discord",
-    schema=_STATIC_CORE_SCHEMA,
-    handler=_make_handler(discord_core),
-    check_fn=check_discord_tool_requirements,
-    requires_env=["DISCORD_BOT_TOKEN"],
-)
-
-registry.register(
-    name="discord_admin",
-    toolset="discord_admin",
-    schema=_STATIC_ADMIN_SCHEMA,
-    handler=_make_handler(discord_admin_handler),
+    schema=_STATIC_SCHEMA,
+    handler=lambda args, **kw: discord_server(
+        action=args.get("action", ""),
+        guild_id=args.get("guild_id", ""),
+        channel_id=args.get("channel_id", ""),
+        user_id=args.get("user_id", ""),
+        role_id=args.get("role_id", ""),
+        message_id=args.get("message_id", ""),
+        query=args.get("query", ""),
+        name=args.get("name", ""),
+        limit=args.get("limit", 50),
+        before=args.get("before", ""),
+        after=args.get("after", ""),
+        auto_archive_duration=args.get("auto_archive_duration", 1440),
+        task_id=kw.get("task_id"),
+    ),
     check_fn=check_discord_tool_requirements,
     requires_env=["DISCORD_BOT_TOKEN"],
 )

toolsets.py

@@ -202,18 +202,6 @@ TOOLSETS = {
         "includes": []
     },
 
-    "discord": {
-        "description": "Discord read and participate tools (fetch messages, search members, create threads)",
-        "tools": ["discord"],
-        "includes": [],
-    },
-
-    "discord_admin": {
-        "description": "Discord server management (list channels/roles, pin messages, assign roles)",
-        "tools": ["discord_admin"],
-        "includes": [],
-    },
-
     "feishu_doc": {
         "description": "Read Feishu/Lark document content",
         "tools": ["feishu_doc_read"],
@@ -338,8 +326,8 @@ TOOLSETS = {
     "hermes-discord": {
         "description": "Discord bot toolset - full access (terminal has safety checks via dangerous command approval)",
         "tools": _HERMES_CORE_TOOLS + [
-            "discord",
-            "discord_admin",
+            # Discord server introspection & management (gated on DISCORD_BOT_TOKEN via check_fn)
+            "discord_server",
         ],
         "includes": []
     },
@@ -400,13 +388,7 @@ TOOLSETS = {
 
     "hermes-feishu": {
         "description": "Feishu/Lark bot toolset - enterprise messaging via Feishu/Lark (full access)",
-        "tools": _HERMES_CORE_TOOLS + [
-            "feishu_doc_read",
-            "feishu_drive_list_comments",
-            "feishu_drive_list_comment_replies",
-            "feishu_drive_reply_comment",
-            "feishu_drive_add_comment",
-        ],
+        "tools": _HERMES_CORE_TOOLS,
         "includes": []
     },
 

tui_gateway/server.py

@@ -712,6 +712,18 @@ def _apply_model_switch(sid: str, session: dict, raw_input: str) -> dict:
         current_base_url = str(runtime.get("base_url", "") or "")
         current_api_key = str(runtime.get("api_key", "") or "")
 
+    # Load user-defined providers so switch_model can resolve named custom
+    # endpoints (e.g. "ollama-launch") and validate against saved model lists.
+    user_provs = None
+    custom_provs = None
+    try:
+        from hermes_cli.config import get_compatible_custom_providers, load_config
+        cfg = load_config()
+        user_provs = [{"provider": k, **v} for k, v in (cfg.get("providers") or {}).items()]
+        custom_provs = get_compatible_custom_providers(cfg)
+    except Exception:
+        pass
+
     result = switch_model(
         raw_input=model_input,
         current_provider=current_provider,
@@ -720,6 +732,8 @@ def _apply_model_switch(sid: str, session: dict, raw_input: str) -> dict:
         current_api_key=current_api_key,
         is_global=persist_global,
         explicit_provider=explicit_provider,
+        user_providers=user_provs,
+        custom_providers=custom_provs,
     )
     if not result.success:
         raise ValueError(result.error_message or "model switch failed")
@@ -2789,6 +2803,23 @@ def _(rid, params: dict) -> dict:
         _write_config_key("display.tui_statusbar", nv)
         return _ok(rid, {"key": key, "value": nv})
 
+    if key == "mouse":
+        raw = str(value or "").strip().lower()
+        display = _load_cfg().get("display") if isinstance(_load_cfg().get("display"), dict) else {}
+        current = bool(display.get("tui_mouse", True))
+
+        if raw in ("", "toggle"):
+            nv = not current
+        elif raw == "on":
+            nv = True
+        elif raw == "off":
+            nv = False
+        else:
+            return _err(rid, 4002, f"unknown mouse value: {value}")
+
+        _write_config_key("display.tui_mouse", nv)
+        return _ok(rid, {"key": key, "value": "on" if nv else "off"})
+
     if key in ("prompt", "personality", "skin"):
         try:
             cfg = _load_cfg()
@@ -2917,6 +2948,10 @@ def _(rid, params: dict) -> dict:
             display.get("tui_statusbar", "top") if isinstance(display, dict) else "top"
         )
         return _ok(rid, {"value": _coerce_statusbar(raw)})
+    if key == "mouse":
+        display = _load_cfg().get("display")
+        on = display.get("tui_mouse", True) if isinstance(display, dict) else True
+        return _ok(rid, {"value": "on" if on else "off"})
     if key == "mtime":
         cfg_path = _hermes_home / "config.yaml"
         try:

ui-tui/packages/hermes-ink/src/ink/components/AlternateScreen.tsx

@@ -53,7 +53,7 @@ export function AlternateScreen(t0: Props) {
       }
 
       writeRaw(
-        ENTER_ALT_SCREEN + ERASE_SCROLLBACK + ERASE_SCREEN + CURSOR_HOME + (mouseTracking ? ENABLE_MOUSE_TRACKING : '')
+        ENTER_ALT_SCREEN + ERASE_SCROLLBACK + ERASE_SCREEN + CURSOR_HOME + (mouseTracking ? ENABLE_MOUSE_TRACKING : DISABLE_MOUSE_TRACKING)
       )
       ink?.setAltScreenActive(true, mouseTracking)
 

ui-tui/packages/hermes-ink/src/ink/ink.tsx

@@ -1121,6 +1121,23 @@ export default class Ink {
       this.repaint()
     }
   }
+
+  /**
+   * Toggle mouse tracking at runtime while the alt screen is active.
+   * Writes the appropriate DEC reset/set sequences so the terminal
+   * (and ConPTY on Windows WSL2) reflects the change immediately.
+   */
+  setAltScreenMouseTracking(enabled: boolean): void {
+    if (this.altScreenMouseTracking === enabled) {
+      return
+    }
+
+    this.altScreenMouseTracking = enabled
+
+    if (this.altScreenActive) {
+      this.options.stdout.write(enabled ? ENABLE_MOUSE_TRACKING : DISABLE_MOUSE_TRACKING)
+    }
+  }
   get isAltScreenActive(): boolean {
     return this.altScreenActive
   }

ui-tui/src/app.tsx

@@ -1,18 +1,21 @@
+import { useStore } from '@nanostores/react'
+
 import { GatewayProvider } from './app/gatewayContext.js'
 import { useMainApp } from './app/useMainApp.js'
+import { $uiState } from './app/uiStore.js'
 import { AppLayout } from './components/appLayout.js'
-import { MOUSE_TRACKING } from './config/env.js'
 import type { GatewayClient } from './gatewayClient.js'
 
 export function App({ gw }: { gw: GatewayClient }) {
   const { appActions, appComposer, appProgress, appStatus, appTranscript, gateway } = useMainApp(gw)
+  const { mouseTracking } = useStore($uiState)
 
   return (
     <GatewayProvider value={gateway}>
       <AppLayout
         actions={appActions}
         composer={appComposer}
-        mouseTracking={MOUSE_TRACKING}
+        mouseTracking={mouseTracking}
         progress={appProgress}
         status={appStatus}
         transcript={appTranscript}

ui-tui/src/app/interfaces.ts

@@ -88,6 +88,7 @@ export interface UiState {
   detailsMode: DetailsMode
   info: null | SessionInfo
   inlineDiffs: boolean
+  mouseTracking: boolean
   sections: SectionVisibility
   showCost: boolean
   showReasoning: boolean

ui-tui/src/app/slash/commands/core.ts

@@ -84,6 +84,27 @@ export const coreCommands: SlashCommand[] = [
     run: (_arg, ctx) => ctx.session.die()
   },
 
+  {
+    aliases: ['scroll'],
+    help: 'toggle mouse/wheel tracking [on|off|toggle]',
+    name: 'mouse',
+    run: (arg, ctx) => {
+      const current = ctx.ui.mouseTracking
+      const next = flagFromArg(arg, current)
+
+      if (next === null) {
+        return ctx.transcript.sys('usage: /mouse [on|off|toggle]')
+      }
+
+      patchUiState({ mouseTracking: next })
+      ctx.gateway
+        .rpc<ConfigSetResponse>('config.set', { key: 'mouse', value: next ? 'on' : 'off' })
+        .catch(() => {})
+
+      queueMicrotask(() => ctx.transcript.sys(`mouse tracking ${next ? 'on' : 'off'}`))
+    }
+  },
+
   {
     aliases: ['new'],
     help: 'start a new session',

ui-tui/src/app/uiStore.ts

@@ -2,6 +2,7 @@ import { atom } from 'nanostores'
 
 import { ZERO } from '../domain/usage.js'
 import { DEFAULT_THEME } from '../theme.js'
+import { MOUSE_TRACKING } from '../config/env.js'
 
 import type { UiState } from './interfaces.js'
 
@@ -12,6 +13,7 @@ const buildUiState = (): UiState => ({
   detailsMode: 'collapsed',
   info: null,
   inlineDiffs: true,
+  mouseTracking: MOUSE_TRACKING,
   sections: {},
   showCost: false,
   showReasoning: false,

ui-tui/src/app/useConfigSync.ts

@@ -46,6 +46,7 @@ export const applyDisplay = (cfg: ConfigFullResponse | null, setBell: (v: boolea
     compact: !!d.tui_compact,
     detailsMode: resolveDetailsMode(d),
     inlineDiffs: d.inline_diffs !== false,
+    mouseTracking: d.tui_mouse !== false,
     sections: resolveSections(d.sections),
     showCost: !!d.show_cost,
     showReasoning: !!d.show_reasoning,

ui-tui/src/gatewayTypes.ts

@@ -61,6 +61,7 @@ export interface ConfigDisplayConfig {
   streaming?: boolean
   thinking_mode?: string
   tui_compact?: boolean
+  tui_mouse?: boolean
   tui_statusbar?: 'bottom' | 'off' | 'on' | 'top' | boolean
 }
 

website/docs/guides/delegation-patterns.md

@@ -216,8 +216,24 @@ Restricting toolsets keeps the subagent focused and prevents accidental side eff
 
 ## Constraints
 
-- **Default 3 parallel tasks** — batches default to 3 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml — no hard ceiling, only a floor of 1)
-- **Nested delegation is opt-in** — leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (1-3 supported); the other four remain blocked. Disable globally via `delegation.orchestrator_enabled: false`.
+- **Default 3 parallel tasks**: batches default to 3 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml, no hard ceiling, only a floor of 1)
+- **Nested delegation is opt-in**: leaf subagents (default) cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code`. Orchestrator subagents (`role="orchestrator"`) retain `delegate_task` for further delegation, but only when `delegation.max_spawn_depth` is raised above the default of 1 (1-3 supported); the other four remain blocked. Disable globally via `delegation.orchestrator_enabled: false`.
+
+### Tuning Concurrency and Depth
+
+| Config | Default | Range | Effect |
+|--------|---------|-------|--------|
+| `max_concurrent_children` | 3 | >=1 | Parallel batch size per `delegate_task` call |
+| `max_spawn_depth` | 1 | 1-3 | How many delegation levels can spawn further |
+
+Example: running 30 parallel workers with nested subagents:
+
+```yaml
+delegation:
+  max_concurrent_children: 30
+  max_spawn_depth: 2
+```
+
 - **Separate terminals** — each subagent gets its own terminal session with separate working directory and state
 - **No conversation history** — subagents see only the `goal` and `context` the parent agent passes when calling `delegate_task`
 - **Default 50 iterations** — set `max_iterations` lower for simple tasks to save cost

website/docs/user-guide/features/dashboard-plugins.md

@@ -1,336 +0,0 @@
----
-sidebar_position: 16
-title: "Dashboard Plugins"
-description: "Build custom tabs and extensions for the Hermes web dashboard"
----
-
-# Dashboard Plugins
-
-Dashboard plugins let you add custom tabs to the web dashboard. A plugin can display its own UI, call the Hermes API, and optionally register backend endpoints — all without touching the dashboard source code.
-
-## Quick Start
-
-Create a plugin directory with a manifest and a JS file:
-
-```bash
-mkdir -p ~/.hermes/plugins/my-plugin/dashboard/dist
-```
-
-**manifest.json:**
-
-```json
-{
-  "name": "my-plugin",
-  "label": "My Plugin",
-  "icon": "Sparkles",
-  "version": "1.0.0",
-  "tab": {
-    "path": "/my-plugin",
-    "position": "after:skills"
-  },
-  "entry": "dist/index.js"
-}
-```
-
-**dist/index.js:**
-
-```javascript
-(function () {
-  var SDK = window.__HERMES_PLUGIN_SDK__;
-  var React = SDK.React;
-  var Card = SDK.components.Card;
-  var CardHeader = SDK.components.CardHeader;
-  var CardTitle = SDK.components.CardTitle;
-  var CardContent = SDK.components.CardContent;
-
-  function MyPage() {
-    return React.createElement(Card, null,
-      React.createElement(CardHeader, null,
-        React.createElement(CardTitle, null, "My Plugin")
-      ),
-      React.createElement(CardContent, null,
-        React.createElement("p", { className: "text-sm text-muted-foreground" },
-          "Hello from my custom dashboard tab!"
-        )
-      )
-    );
-  }
-
-  window.__HERMES_PLUGINS__.register("my-plugin", MyPage);
-})();
-```
-
-Refresh the dashboard — your tab appears in the navigation bar.
-
-## Plugin Structure
-
-Plugins live inside the standard `~/.hermes/plugins/` directory. The dashboard extension is a `dashboard/` subfolder:
-
-```
-~/.hermes/plugins/my-plugin/
-  plugin.yaml              # optional — existing CLI/gateway plugin manifest
-  __init__.py              # optional — existing CLI/gateway hooks
-  dashboard/               # dashboard extension
-    manifest.json          # required — tab config, icon, entry point
-    dist/
-      index.js             # required — pre-built JS bundle
-      style.css            # optional — custom CSS
-    plugin_api.py          # optional — backend API routes
-```
-
-A single plugin can extend both the CLI/gateway (via `plugin.yaml` + `__init__.py`) and the dashboard (via `dashboard/`) from one directory.
-
-## Manifest Reference
-
-The `manifest.json` file describes your plugin to the dashboard:
-
-```json
-{
-  "name": "my-plugin",
-  "label": "My Plugin",
-  "description": "What this plugin does",
-  "icon": "Sparkles",
-  "version": "1.0.0",
-  "tab": {
-    "path": "/my-plugin",
-    "position": "after:skills"
-  },
-  "entry": "dist/index.js",
-  "css": "dist/style.css",
-  "api": "plugin_api.py"
-}
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Unique plugin identifier (lowercase, hyphens ok) |
-| `label` | Yes | Display name shown in the nav tab |
-| `description` | No | Short description |
-| `icon` | No | Lucide icon name (default: `Puzzle`) |
-| `version` | No | Semver version string |
-| `tab.path` | Yes | URL path for the tab (e.g. `/my-plugin`) |
-| `tab.position` | No | Where to insert the tab: `end` (default), `after:<tab>`, `before:<tab>` |
-| `entry` | Yes | Path to the JS bundle relative to `dashboard/` |
-| `css` | No | Path to a CSS file to inject |
-| `api` | No | Path to a Python file with FastAPI routes |
-
-### Tab Position
-
-The `position` field controls where your tab appears in the navigation:
-
-- `"end"` — after all built-in tabs (default)
-- `"after:skills"` — after the Skills tab
-- `"before:config"` — before the Config tab
-- `"after:cron"` — after the Cron tab
-
-The value after the colon is the path segment of the target tab (without the leading slash).
-
-### Available Icons
-
-Plugins can use any of these Lucide icon names:
-
-`Activity`, `BarChart3`, `Clock`, `Code`, `Database`, `Eye`, `FileText`, `Globe`, `Heart`, `KeyRound`, `MessageSquare`, `Package`, `Puzzle`, `Settings`, `Shield`, `Sparkles`, `Star`, `Terminal`, `Wrench`, `Zap`
-
-Unrecognized icon names fall back to `Puzzle`.
-
-## Plugin SDK
-
-Plugins don't bundle React or UI components — they use the SDK exposed on `window.__HERMES_PLUGIN_SDK__`. This avoids version conflicts and keeps plugin bundles tiny.
-
-### SDK Contents
-
-```javascript
-var SDK = window.__HERMES_PLUGIN_SDK__;
-
-// React
-SDK.React              // React instance
-SDK.hooks.useState     // React hooks
-SDK.hooks.useEffect
-SDK.hooks.useCallback
-SDK.hooks.useMemo
-SDK.hooks.useRef
-SDK.hooks.useContext
-SDK.hooks.createContext
-
-// API
-SDK.api                // Hermes API client (getStatus, getSessions, etc.)
-SDK.fetchJSON          // Raw fetch for custom endpoints — handles auth automatically
-
-// UI Components (shadcn/ui style)
-SDK.components.Card
-SDK.components.CardHeader
-SDK.components.CardTitle
-SDK.components.CardContent
-SDK.components.Badge
-SDK.components.Button
-SDK.components.Input
-SDK.components.Label
-SDK.components.Select
-SDK.components.SelectOption
-SDK.components.Separator
-SDK.components.Tabs
-SDK.components.TabsList
-SDK.components.TabsTrigger
-
-// Utilities
-SDK.utils.cn           // Tailwind class merger (clsx + twMerge)
-SDK.utils.timeAgo      // "5m ago" from unix timestamp
-SDK.utils.isoTimeAgo   // "5m ago" from ISO string
-
-// Hooks
-SDK.useI18n            // i18n translations
-SDK.useTheme           // Current theme info
-```
-
-### Using SDK.fetchJSON
-
-For calling your plugin's backend API endpoints:
-
-```javascript
-SDK.fetchJSON("/api/plugins/my-plugin/data")
-  .then(function (result) {
-    console.log(result);
-  })
-  .catch(function (err) {
-    console.error("API call failed:", err);
-  });
-```
-
-`fetchJSON` automatically injects the session auth token, handles errors, and parses JSON.
-
-### Using Existing API Methods
-
-The `SDK.api` object has methods for all built-in Hermes endpoints:
-
-```javascript
-// Fetch agent status
-SDK.api.getStatus().then(function (status) {
-  console.log("Version:", status.version);
-});
-
-// List sessions
-SDK.api.getSessions(10).then(function (resp) {
-  console.log("Sessions:", resp.sessions.length);
-});
-```
-
-## Backend API Routes
-
-Plugins can register FastAPI routes by setting the `api` field in the manifest. Create a Python file that exports a `router`:
-
-```python
-# plugin_api.py
-from fastapi import APIRouter
-
-router = APIRouter()
-
-@router.get("/data")
-async def get_data():
-    return {"items": ["one", "two", "three"]}
-
-@router.post("/action")
-async def do_action(body: dict):
-    return {"ok": True, "received": body}
-```
-
-Routes are mounted at `/api/plugins/<name>/`, so the above becomes:
-- `GET /api/plugins/my-plugin/data`
-- `POST /api/plugins/my-plugin/action`
-
-Plugin API routes bypass session token authentication since the dashboard server only binds to localhost.
-
-### Accessing Hermes Internals
-
-Backend routes can import from the hermes-agent codebase:
-
-```python
-from fastapi import APIRouter
-from hermes_state import SessionDB
-from hermes_cli.config import load_config
-
-router = APIRouter()
-
-@router.get("/session-count")
-async def session_count():
-    db = SessionDB()
-    try:
-        count = len(db.list_sessions(limit=9999))
-        return {"count": count}
-    finally:
-        db.close()
-```
-
-## Custom CSS
-
-If your plugin needs custom styles, add a CSS file and reference it in the manifest:
-
-```json
-{
-  "css": "dist/style.css"
-}
-```
-
-The CSS file is injected as a `<link>` tag when the plugin loads. Use specific class names to avoid conflicts with the dashboard's existing styles.
-
-```css
-/* dist/style.css */
-.my-plugin-chart {
-  border: 1px solid var(--color-border);
-  background: var(--color-card);
-  padding: 1rem;
-}
-```
-
-You can use the dashboard's CSS custom properties (e.g. `--color-border`, `--color-foreground`) to match the active theme.
-
-## Plugin Loading Flow
-
-1. Dashboard loads — `main.tsx` exposes the SDK on `window.__HERMES_PLUGIN_SDK__`
-2. `App.tsx` calls `usePlugins()` which fetches `GET /api/dashboard/plugins`
-3. For each plugin: CSS `<link>` injected (if declared), JS `<script>` loaded
-4. Plugin JS calls `window.__HERMES_PLUGINS__.register(name, Component)`
-5. Dashboard adds the tab to navigation and mounts the component as a route
-
-Plugins have up to 2 seconds to register after their script loads. If a plugin fails to load, the dashboard continues without it.
-
-## Plugin Discovery
-
-The dashboard scans these directories for `dashboard/manifest.json`:
-
-1. **User plugins:** `~/.hermes/plugins/<name>/dashboard/manifest.json`
-2. **Bundled plugins:** `<repo>/plugins/<name>/dashboard/manifest.json`
-3. **Project plugins:** `./.hermes/plugins/<name>/dashboard/manifest.json` (only when `HERMES_ENABLE_PROJECT_PLUGINS` is set)
-
-User plugins take precedence — if the same plugin name exists in multiple sources, the user version wins.
-
-To force re-scanning after adding a new plugin without restarting the server:
-
-```bash
-curl http://127.0.0.1:9119/api/dashboard/plugins/rescan
-```
-
-## Plugin API Endpoints
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/dashboard/plugins` | GET | List discovered plugins |
-| `/api/dashboard/plugins/rescan` | GET | Force re-scan for new plugins |
-| `/dashboard-plugins/<name>/<path>` | GET | Serve plugin static assets |
-| `/api/plugins/<name>/*` | * | Plugin-registered API routes |
-
-## Example Plugin
-
-The repository includes an example plugin at `plugins/example-dashboard/` that demonstrates:
-
-- Using SDK components (Card, Badge, Button)
-- Calling a backend API route
-- Registering via `window.__HERMES_PLUGINS__.register()`
-
-To try it, run `hermes dashboard` — the "Example" tab appears after Skills.
-
-## Tips
-
-- **No build step required** — write plain JavaScript IIFEs. If you prefer JSX, use any bundler (esbuild, Vite, webpack) targeting IIFE output with React as an external.
-- **Keep bundles small** — React and all UI components are provided by the SDK. Your bundle should only contain your plugin logic.
-- **Use theme variables** — reference `var(--color-*)` in CSS to automatically match whatever theme the user has selected.
-- **Test locally** — run `hermes dashboard --no-open` and use browser dev tools to verify your plugin loads and registers correctly.

website/docs/user-guide/features/extending-the-dashboard.md

@@ -0,0 +1,818 @@
+---
+sidebar_position: 17
+title: "Extending the Dashboard"
+description: "Build themes and plugins for the Hermes web dashboard — palettes, typography, layouts, custom tabs, shell slots, and backend API routes"
+---
+
+# Extending the Dashboard
+
+The Hermes web dashboard (`hermes dashboard`) is built to be reskinned and extended without forking the codebase. Three layers are exposed:
+
+1. **Themes** — YAML files that repaint the dashboard's palette, typography, layout, and per-component chrome. Drop a file in `~/.hermes/dashboard-themes/`; it appears in the theme switcher.
+2. **UI plugins** — a directory with `manifest.json` + a JavaScript bundle that registers a tab, replaces a built-in page, or injects components into named shell slots.
+3. **Backend plugins** — a Python file inside that plugin directory that exposes a FastAPI `router`; routes are mounted under `/api/plugins/<name>/` and called from the plugin's UI.
+
+All three are **drop-in at runtime**: no repo clone, no `npm run build`, no patching the dashboard source. This page is the canonical reference for all three.
+
+If you just want to use the dashboard, see [Web Dashboard](./web-dashboard). If you want to reskin the terminal CLI (not the web dashboard), see [Skins & Themes](./skins) — the CLI skin system is unrelated to dashboard themes.
+
+:::note How the pieces compose
+Themes and plugins are independent but synergistic. A theme can stand alone (just a YAML file). A plugin can stand alone (just a tab). Together they let you build a complete visual reskin with custom HUDs — the bundled `strike-freedom-cockpit` demo does exactly that. See [Combined theme + plugin demo](#combined-theme--plugin-demo).
+:::
+
+---
+
+## Table of contents
+
+- [Themes](#themes)
+  - [Quick start — your first theme](#quick-start--your-first-theme)
+  - [Palette, typography, layout](#palette-typography-layout)
+  - [Layout variants](#layout-variants)
+  - [Theme assets (images as CSS vars)](#theme-assets-images-as-css-vars)
+  - [Component chrome overrides](#component-chrome-overrides)
+  - [Color overrides](#color-overrides)
+  - [Raw `customCSS`](#raw-customcss)
+  - [Built-in themes](#built-in-themes)
+  - [Full theme YAML reference](#full-theme-yaml-reference)
+- [Plugins](#plugins)
+  - [Quick start — your first plugin](#quick-start--your-first-plugin)
+  - [Directory layout](#directory-layout)
+  - [Manifest reference](#manifest-reference)
+  - [The Plugin SDK](#the-plugin-sdk)
+  - [Shell slots](#shell-slots)
+  - [Replacing built-in pages (`tab.override`)](#replacing-built-in-pages-taboverride)
+  - [Slot-only plugins (`tab.hidden`)](#slot-only-plugins-tabhidden)
+  - [Backend API routes](#backend-api-routes)
+  - [Custom CSS per plugin](#custom-css-per-plugin)
+  - [Plugin discovery & reload](#plugin-discovery--reload)
+- [Combined theme + plugin demo](#combined-theme--plugin-demo)
+- [API reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Themes
+
+Themes are YAML files stored in `~/.hermes/dashboard-themes/`. The file name doesn't matter (the theme's `name:` field is what the system uses), but convention is `<name>.yaml`. Every field is optional — missing keys fall back to the built-in `default` theme, so a theme can be as small as one color.
+
+### Quick start — your first theme
+
+```bash
+mkdir -p ~/.hermes/dashboard-themes
+```
+
+```yaml
+# ~/.hermes/dashboard-themes/neon.yaml
+name: neon
+label: Neon
+description: Pure magenta on black
+
+palette:
+  background: "#000000"
+  midground: "#ff00ff"
+```
+
+Refresh the dashboard. Click the palette icon in the header and pick **Neon**. The background goes black, text and accents go magenta, and every derived color (card, border, muted, ring, etc.) is recomputed from that 2-color triplet via `color-mix()` in CSS.
+
+That's the whole onboarding: one file, two colors. Everything below is optional refinement.
+
+### Palette, typography, layout
+
+These three blocks are the heart of a theme. Each is independent — override one, leave the others.
+
+#### Palette (3-layer)
+
+The palette is a triplet of color layers plus a warm-glow vignette color and a noise-grain multiplier. The dashboard's design-system cascade derives every shadcn-compatible token (card, popover, muted, border, primary, destructive, ring, etc.) from this triplet via CSS `color-mix()`. Overriding three colors cascades into the whole UI.
+
+| Key | Description |
+|-----|-------------|
+| `palette.background` | Deepest canvas color — typically near-black. Drives the page background and card fill. |
+| `palette.midground` | Primary text and accent. Most UI chrome reads this (foreground text, button outlines, focus rings). |
+| `palette.foreground` | Top-layer highlight. The default theme sets this to white at alpha 0 (invisible); themes that want a bright accent on top can raise its alpha. |
+| `palette.warmGlow` | `rgba(...)` string used as the vignette color by `<Backdrop />`. |
+| `palette.noiseOpacity` | 0–1.2 multiplier on the grain overlay. Lower = softer, higher = grittier. |
+
+Each layer accepts either `{hex: "#RRGGBB", alpha: 0.0–1.0}` or a bare hex string (alpha defaults to 1.0).
+
+```yaml
+palette:
+  background:
+    hex: "#05091a"
+    alpha: 1.0
+  midground: "#d8f0ff"          # bare hex, alpha = 1.0
+  foreground:
+    hex: "#ffffff"
+    alpha: 0                    # invisible top layer
+  warmGlow: "rgba(255, 199, 55, 0.24)"
+  noiseOpacity: 0.7
+```
+
+#### Typography
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `fontSans` | string | CSS font-family stack for body copy (applied to `html`, `body`). |
+| `fontMono` | string | CSS font-family stack for code blocks, `<code>`, `.font-mono` utilities. |
+| `fontDisplay` | string | Optional heading/display stack. Falls back to `fontSans`. |
+| `fontUrl` | string | Optional external stylesheet URL. Injected as `<link rel="stylesheet">` in `<head>` on theme switch. Same URL is never injected twice. Works with Google Fonts, Bunny Fonts, self-hosted `@font-face` sheets — anything linkable. |
+| `baseSize` | string | Root font size — controls the rem scale. E.g. `"14px"`, `"16px"`. |
+| `lineHeight` | string | Default line-height. E.g. `"1.5"`, `"1.65"`. |
+| `letterSpacing` | string | Default letter-spacing. E.g. `"0"`, `"0.01em"`, `"-0.01em"`. |
+
+```yaml
+typography:
+  fontSans: '"Orbitron", "Eurostile", "Impact", sans-serif'
+  fontMono: '"Share Tech Mono", ui-monospace, monospace'
+  fontDisplay: '"Orbitron", "Eurostile", sans-serif'
+  fontUrl: "https://fonts.googleapis.com/css2?family=Orbitron:wght@400;500;600;700&family=Share+Tech+Mono&display=swap"
+  baseSize: "14px"
+  lineHeight: "1.5"
+  letterSpacing: "0.04em"
+```
+
+#### Layout
+
+| Key | Values | Description |
+|-----|--------|-------------|
+| `radius` | any CSS length (`"0"`, `"0.25rem"`, `"0.5rem"`, `"1rem"`, ...) | Corner-radius token. Maps to `--radius` and cascades into `--radius-sm/md/lg/xl` — every rounded element shifts together. |
+| `density` | `compact` \| `comfortable` \| `spacious` | Spacing multiplier applied as the `--spacing-mul` CSS var. `compact = 0.85×`, `comfortable = 1.0×` (default), `spacious = 1.2×`. Scales Tailwind's base spacing, so padding, gap, and space-between utilities all shift proportionally. |
+
+```yaml
+layout:
+  radius: "0"
+  density: compact
+```
+
+### Layout variants
+
+`layoutVariant` picks the overall shell layout. Defaults to `"standard"` when absent.
+
+| Variant | Behaviour |
+|---------|-----------|
+| `standard` | Single column, 1600px max-width (default). |
+| `cockpit` | Left sidebar rail (260px) + main content. Populated by plugins via the `sidebar` slot — see [Shell slots](#shell-slots). Without a plugin the rail shows a placeholder. |
+| `tiled` | Drops the max-width clamp so pages can use the full viewport width. |
+
+```yaml
+layoutVariant: cockpit
+```
+
+The current variant is exposed as `document.documentElement.dataset.layoutVariant`, so raw CSS in `customCSS` can target it via `:root[data-layout-variant="cockpit"] ...`.
+
+### Theme assets (images as CSS vars)
+
+Ship artwork URLs with a theme. Each named slot becomes a CSS var (`--theme-asset-<name>`) that the built-in shell and any plugin can read. The `bg` slot is automatically wired into the backdrop; other slots are plugin-facing.
+
+```yaml
+assets:
+  bg: "https://example.com/hero-bg.jpg"           # auto-wired into <Backdrop />
+  hero: "/my-images/strike-freedom.png"           # for plugin sidebars
+  crest: "/my-images/crest.svg"                   # for header-left plugins
+  logo: "/my-images/logo.png"
+  sidebar: "/my-images/rail.png"
+  header: "/my-images/header-art.png"
+  custom:
+    scanLines: "/my-images/scanlines.png"         # → --theme-asset-custom-scanLines
+```
+
+Values accept:
+
+- Bare URLs — wrapped in `url(...)` automatically.
+- Pre-wrapped `url(...)`, `linear-gradient(...)`, `radial-gradient(...)` expressions — used as-is.
+- `"none"` — explicit opt-out.
+
+Every asset is also emitted as `--theme-asset-<name>-raw` (the unwrapped URL), in case a plugin needs to pass it to `<img src>` instead of `background-image`.
+
+Plugins read these with plain CSS or JS:
+
+```javascript
+// In a plugin slot
+const hero = getComputedStyle(document.documentElement)
+  .getPropertyValue("--theme-asset-hero").trim();
+```
+
+### Component chrome overrides
+
+`componentStyles` restyles individual shell components without writing CSS selectors. Each bucket's entries become CSS vars (`--component-<bucket>-<kebab-property>`) that the shell's shared components read. So `card:` overrides apply to every `<Card>`, `header:` to the app bar, etc.
+
+```yaml
+componentStyles:
+  card:
+    clipPath: "polygon(12px 0, 100% 0, 100% calc(100% - 12px), calc(100% - 12px) 100%, 0 100%, 0 12px)"
+    background: "linear-gradient(180deg, rgba(10, 22, 52, 0.85), rgba(5, 9, 26, 0.92))"
+    boxShadow: "inset 0 0 0 1px rgba(64, 200, 255, 0.28)"
+  header:
+    background: "linear-gradient(180deg, rgba(16, 32, 72, 0.95), rgba(5, 9, 26, 0.9))"
+  tab:
+    clipPath: "polygon(6px 0, 100% 0, calc(100% - 6px) 100%, 0 100%)"
+  sidebar: {}
+  backdrop: {}
+  footer: {}
+  progress: {}
+  badge: {}
+  page: {}
+```
+
+Supported buckets: `card`, `header`, `footer`, `sidebar`, `tab`, `progress`, `badge`, `backdrop`, `page`.
+
+Property names use camelCase (`clipPath`) and are emitted as kebab (`clip-path`). Values are plain CSS strings — anything CSS accepts (`clip-path`, `border-image`, `background`, `box-shadow`, `animation`, ...).
+
+### Color overrides
+
+Most themes won't need this — the 3-layer palette derives every shadcn token. Use `colorOverrides` when you want a specific accent the derivation won't produce (a softer destructive red for a pastel theme, a specific success green for a brand).
+
+```yaml
+colorOverrides:
+  primary: "#ffce3a"
+  primaryForeground: "#05091a"
+  accent: "#3fd3ff"
+  ring: "#3fd3ff"
+  destructive: "#ff3a5e"
+  border: "rgba(64, 200, 255, 0.28)"
+```
+
+Supported keys: `card`, `cardForeground`, `popover`, `popoverForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `success`, `warning`, `border`, `input`, `ring`.
+
+Each key maps 1:1 to the `--color-<kebab>` CSS var (e.g. `primaryForeground` → `--color-primary-foreground`). Any key set here wins over the palette cascade for the active theme only — switching to another theme clears the overrides.
+
+### Raw `customCSS`
+
+For selector-level chrome that `componentStyles` can't express — pseudo-elements, animations, media queries, theme-scoped overrides — drop raw CSS into `customCSS`:
+
+```yaml
+customCSS: |
+  /* Scanline overlay — only visible when cockpit variant is active. */
+  :root[data-layout-variant="cockpit"] body::before {
+    content: "";
+    position: fixed;
+    inset: 0;
+    pointer-events: none;
+    z-index: 100;
+    background: repeating-linear-gradient(to bottom,
+      transparent 0px, transparent 2px,
+      rgba(64, 200, 255, 0.035) 3px, rgba(64, 200, 255, 0.035) 4px);
+    mix-blend-mode: screen;
+  }
+```
+
+The CSS is injected as a single scoped `<style data-hermes-theme-css>` tag on theme apply and cleaned up on theme switch. **Capped at 32 KiB per theme.**
+
+### Built-in themes
+
+Each built-in ships its own palette, typography, and layout — switching produces visible changes beyond color alone.
+
+| Theme | Palette | Typography | Layout |
+|-------|---------|------------|--------|
+| **Hermes Teal** (`default`) | Dark teal + cream | System stack, 15px | 0.5rem radius, comfortable |
+| **Midnight** (`midnight`) | Deep blue-violet | Inter + JetBrains Mono, 14px | 0.75rem radius, comfortable |
+| **Ember** (`ember`) | Warm crimson + bronze | Spectral (serif) + IBM Plex Mono, 15px | 0.25rem radius, comfortable |
+| **Mono** (`mono`) | Grayscale | IBM Plex Sans + IBM Plex Mono, 13px | 0 radius, compact |
+| **Cyberpunk** (`cyberpunk`) | Neon green on black | Share Tech Mono everywhere, 14px | 0 radius, compact |
+| **Rosé** (`rose`) | Pink + ivory | Fraunces (serif) + DM Mono, 16px | 1rem radius, spacious |
+
+Themes that reference Google Fonts (all except Hermes Teal) load the stylesheet on demand — the first time you switch to them a `<link>` tag is injected into `<head>`.
+
+### Full theme YAML reference
+
+Every knob in one file — copy and trim what you don't need:
+
+```yaml
+# ~/.hermes/dashboard-themes/ocean.yaml
+name: ocean
+label: Ocean Deep
+description: Deep sea blues with coral accents
+
+# 3-layer palette (accepts {hex, alpha} or bare hex)
+palette:
+  background:
+    hex: "#0a1628"
+    alpha: 1.0
+  midground:
+    hex: "#a8d0ff"
+    alpha: 1.0
+  foreground:
+    hex: "#ffffff"
+    alpha: 0.0
+  warmGlow: "rgba(255, 107, 107, 0.35)"
+  noiseOpacity: 0.7
+
+typography:
+  fontSans: "Poppins, system-ui, sans-serif"
+  fontMono: "Fira Code, ui-monospace, monospace"
+  fontDisplay: "Poppins, system-ui, sans-serif"   # optional
+  fontUrl: "https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600&family=Fira+Code:wght@400;500&display=swap"
+  baseSize: "15px"
+  lineHeight: "1.6"
+  letterSpacing: "-0.003em"
+
+layout:
+  radius: "0.75rem"
+  density: comfortable
+
+layoutVariant: standard        # standard | cockpit | tiled
+
+assets:
+  bg: "https://example.com/ocean-bg.jpg"
+  hero: "/my-images/kraken.png"
+  crest: "/my-images/anchor.svg"
+  logo: "/my-images/logo.png"
+  custom:
+    pattern: "/my-images/waves.svg"
+
+componentStyles:
+  card:
+    boxShadow: "inset 0 0 0 1px rgba(168, 208, 255, 0.18)"
+  header:
+    background: "linear-gradient(180deg, rgba(10, 22, 40, 0.95), rgba(5, 9, 26, 0.9))"
+
+colorOverrides:
+  destructive: "#ff6b6b"
+  ring: "#ff6b6b"
+
+customCSS: |
+  /* Any additional selector-level tweaks */
+```
+
+Refresh the dashboard after creating the file. Switch themes live from the header bar — click the palette icon. Selection persists to `config.yaml` under `dashboard.theme` and is restored on reload.
+
+---
+
+## Plugins
+
+A dashboard plugin is a directory with a `manifest.json`, a pre-built JS bundle, and optionally a CSS file and a Python file with FastAPI routes. Plugins live next to other Hermes plugins in `~/.hermes/plugins/<name>/` — the dashboard extension is a `dashboard/` subfolder inside that plugin directory, so one plugin can extend both the CLI/gateway and the dashboard from a single install.
+
+Plugins don't bundle React or UI components. They use the **Plugin SDK** exposed on `window.__HERMES_PLUGIN_SDK__`. This keeps plugin bundles tiny (typically a few KB) and avoids version conflicts.
+
+### Quick start — your first plugin
+
+Create the directory structure:
+
+```bash
+mkdir -p ~/.hermes/plugins/my-plugin/dashboard/dist
+```
+
+Write the manifest:
+
+```json
+// ~/.hermes/plugins/my-plugin/dashboard/manifest.json
+{
+  "name": "my-plugin",
+  "label": "My Plugin",
+  "icon": "Sparkles",
+  "version": "1.0.0",
+  "tab": {
+    "path": "/my-plugin",
+    "position": "after:skills"
+  },
+  "entry": "dist/index.js"
+}
+```
+
+Write the JS bundle (a plain IIFE — no build step needed):
+
+```javascript
+// ~/.hermes/plugins/my-plugin/dashboard/dist/index.js
+(function () {
+  "use strict";
+
+  const SDK = window.__HERMES_PLUGIN_SDK__;
+  const { React } = SDK;
+  const { Card, CardHeader, CardTitle, CardContent } = SDK.components;
+
+  function MyPage() {
+    return React.createElement(Card, null,
+      React.createElement(CardHeader, null,
+        React.createElement(CardTitle, null, "My Plugin"),
+      ),
+      React.createElement(CardContent, null,
+        React.createElement("p", { className: "text-sm text-muted-foreground" },
+          "Hello from my custom dashboard tab.",
+        ),
+      ),
+    );
+  }
+
+  window.__HERMES_PLUGINS__.register("my-plugin", MyPage);
+})();
+```
+
+Refresh the dashboard — your tab appears in the nav bar, after **Skills**.
+
+:::tip Skip React.createElement
+If you prefer JSX, use any bundler (esbuild, Vite, rollup) with React as an external and IIFE output. The only hard requirement is that the final file is a single JS file loadable via `<script>`. React is never bundled; it comes from `SDK.React`.
+:::
+
+### Directory layout
+
+```
+~/.hermes/plugins/my-plugin/
+├── plugin.yaml              # optional — existing CLI/gateway plugin manifest
+├── __init__.py              # optional — existing CLI/gateway hooks
+└── dashboard/               # dashboard extension
+    ├── manifest.json        # required — tab config, icon, entry point
+    ├── dist/
+    │   ├── index.js         # required — pre-built JS bundle (IIFE)
+    │   └── style.css        # optional — custom CSS
+    └── plugin_api.py        # optional — backend API routes (FastAPI)
+```
+
+A single plugin directory can carry three orthogonal extensions:
+
+- `plugin.yaml` + `__init__.py` — CLI/gateway plugin ([see plugins page](./plugins)).
+- `dashboard/manifest.json` + `dashboard/dist/index.js` — dashboard UI plugin.
+- `dashboard/plugin_api.py` — dashboard backend routes.
+
+None of them are required; include only the layers you need.
+
+### Manifest reference
+
+```json
+{
+  "name": "my-plugin",
+  "label": "My Plugin",
+  "description": "What this plugin does",
+  "icon": "Sparkles",
+  "version": "1.0.0",
+  "tab": {
+    "path": "/my-plugin",
+    "position": "after:skills",
+    "override": "/",
+    "hidden": false
+  },
+  "slots": ["sidebar", "header-left"],
+  "entry": "dist/index.js",
+  "css": "dist/style.css",
+  "api": "plugin_api.py"
+}
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique plugin identifier. Lowercase, hyphens ok. Used in URLs and registration. |
+| `label` | Yes | Display name shown in the nav tab. |
+| `description` | No | Short description (shown in dashboard admin surfaces). |
+| `icon` | No | Lucide icon name. Defaults to `Puzzle`. Unknown names fall back to `Puzzle`. |
+| `version` | No | Semver string. Defaults to `0.0.0`. |
+| `tab.path` | Yes | URL path for the tab (e.g. `/my-plugin`). |
+| `tab.position` | No | Where to insert the tab. `"end"` (default), `"after:<path>"`, or `"before:<path>"` — value after the colon is the **path segment** of the target tab (no leading slash). Examples: `"after:skills"`, `"before:config"`. |
+| `tab.override` | No | Set to a built-in route path (`"/"`, `"/sessions"`, `"/config"`, ...) to **replace** that page instead of adding a new tab. See [Replacing built-in pages](#replacing-built-in-pages-taboverride). |
+| `tab.hidden` | No | When true, register the component and any slots without adding a tab to the nav. Used by slot-only plugins. See [Slot-only plugins](#slot-only-plugins-tabhidden). |
+| `slots` | No | Named shell slots this plugin populates. **Documentation aid only** — actual registration happens from the JS bundle via `registerSlot()`. Listing slots here makes discovery surfaces more informative. |
+| `entry` | Yes | Path to the JS bundle relative to `dashboard/`. Defaults to `dist/index.js`. |
+| `css` | No | Path to a CSS file to inject as a `<link>` tag. |
+| `api` | No | Path to a Python file with FastAPI routes. Mounted at `/api/plugins/<name>/`. |
+
+#### Available icons
+
+Plugins use Lucide icon names. The dashboard maps these by name — unknown names silently fall back to `Puzzle`.
+
+Currently mapped: `Activity`, `BarChart3`, `Clock`, `Code`, `Database`, `Eye`, `FileText`, `Globe`, `Heart`, `KeyRound`, `MessageSquare`, `Package`, `Puzzle`, `Settings`, `Shield`, `Sparkles`, `Star`, `Terminal`, `Wrench`, `Zap`.
+
+Need a different icon? Open a PR to `web/src/App.tsx`'s `ICON_MAP` — pure additive change.
+
+### The Plugin SDK
+
+Everything a plugin needs is on `window.__HERMES_PLUGIN_SDK__`. Plugins should never import React directly.
+
+```javascript
+const SDK = window.__HERMES_PLUGIN_SDK__;
+
+// React + hooks
+SDK.React                    // the React instance
+SDK.hooks.useState
+SDK.hooks.useEffect
+SDK.hooks.useCallback
+SDK.hooks.useMemo
+SDK.hooks.useRef
+SDK.hooks.useContext
+SDK.hooks.createContext
+
+// UI components (shadcn/ui primitives)
+SDK.components.Card
+SDK.components.CardHeader
+SDK.components.CardTitle
+SDK.components.CardContent
+SDK.components.Badge
+SDK.components.Button
+SDK.components.Input
+SDK.components.Label
+SDK.components.Select
+SDK.components.SelectOption
+SDK.components.Separator
+SDK.components.Tabs
+SDK.components.TabsList
+SDK.components.TabsTrigger
+SDK.components.PluginSlot    // render a named slot (useful for nested plugin UIs)
+
+// Hermes API client + raw fetcher
+SDK.api                      // typed client — getStatus, getSessions, getConfig, ...
+SDK.fetchJSON                // raw fetch for custom endpoints (plugin-registered routes)
+
+// Utilities
+SDK.utils.cn                 // Tailwind class merger (clsx + twMerge)
+SDK.utils.timeAgo            // "5m ago" from unix timestamp
+SDK.utils.isoTimeAgo         // "5m ago" from ISO string
+
+// Hooks
+SDK.useI18n                  // i18n hook for multi-language plugins
+```
+
+#### Calling your plugin's backend
+
+```javascript
+SDK.fetchJSON("/api/plugins/my-plugin/data")
+  .then((data) => console.log(data))
+  .catch((err) => console.error("API call failed:", err));
+```
+
+`fetchJSON` injects the session auth token, surfaces errors as thrown exceptions, and parses JSON automatically.
+
+#### Calling built-in Hermes endpoints
+
+```javascript
+// Agent status
+SDK.api.getStatus().then((s) => console.log("Version:", s.version));
+
+// Recent sessions
+SDK.api.getSessions(10).then((resp) => console.log(resp.sessions.length));
+```
+
+See [Web Dashboard → REST API](./web-dashboard#rest-api) for the full list.
+
+### Shell slots
+
+Slots let a plugin inject components into named locations of the app shell — the cockpit sidebar, the header, the footer, an overlay layer — without claiming a whole tab. Multiple plugins can populate the same slot; they render stacked in registration order.
+
+Register from inside the plugin bundle:
+
+```javascript
+window.__HERMES_PLUGINS__.registerSlot("my-plugin", "sidebar", MySidebar);
+window.__HERMES_PLUGINS__.registerSlot("my-plugin", "header-left", MyCrest);
+```
+
+#### Slot catalogue
+
+| Slot | Location |
+|------|----------|
+| `backdrop` | Inside the `<Backdrop />` layer stack, above the noise layer. |
+| `header-left` | Before the Hermes brand in the top bar. |
+| `header-right` | Before the theme/language switchers in the top bar. |
+| `header-banner` | Full-width strip below the nav. |
+| `sidebar` | Cockpit sidebar rail — **only rendered when `layoutVariant === "cockpit"`**. |
+| `pre-main` | Above the route outlet (inside `<main>`). |
+| `post-main` | Below the route outlet (inside `<main>`). |
+| `footer-left` | Footer cell content (replaces default). |
+| `footer-right` | Footer cell content (replaces default). |
+| `overlay` | Fixed-position layer above everything else. Useful for chrome (scanlines, vignettes) `customCSS` can't achieve alone. |
+
+The shell only renders `<PluginSlot name="..." />` for the slots above. Additional names are accepted by the registry for nested plugin UIs — a plugin can expose its own slots via `SDK.components.PluginSlot`.
+
+#### Re-registration and HMR
+
+If the same `(plugin, slot)` pair is registered twice, the later call replaces the earlier one — this matches how React HMR expects plugin re-mounts to behave.
+
+### Replacing built-in pages (`tab.override`)
+
+Setting `tab.override` to a built-in route path makes the plugin's component replace that page instead of adding a new tab. Useful when a theme wants a custom home page (`/`) but wants to keep the rest of the dashboard intact.
+
+```json
+{
+  "name": "my-home",
+  "label": "Home",
+  "tab": {
+    "path": "/my-home",
+    "override": "/",
+    "position": "end"
+  },
+  "entry": "dist/index.js"
+}
+```
+
+With `override` set:
+
+- The original page component at `/` is removed from the router.
+- Your plugin renders at `/` instead.
+- No nav tab is added for `tab.path` (the override is the point).
+
+Only one plugin can override a given path. If two plugins claim the same override, the first wins and the second is ignored with a dev-mode warning.
+
+### Slot-only plugins (`tab.hidden`)
+
+When `tab.hidden: true`, the plugin registers its component (for direct URL visits) and any slots, but never adds a tab to the navigation. Used by plugins that only exist to inject into slots — a header crest, a sidebar HUD, an overlay.
+
+```json
+{
+  "name": "header-crest",
+  "label": "Header Crest",
+  "tab": {
+    "path": "/header-crest",
+    "position": "end",
+    "hidden": true
+  },
+  "slots": ["header-left"],
+  "entry": "dist/index.js"
+}
+```
+
+The bundle still calls `register()` with a placeholder component (good practice in case someone hits the URL directly) and then `registerSlot()` to do the real work.
+
+### Backend API routes
+
+Plugins can register FastAPI routes by setting `api` in the manifest. Create the file and export a `router`:
+
+```python
+# ~/.hermes/plugins/my-plugin/dashboard/plugin_api.py
+from fastapi import APIRouter
+
+router = APIRouter()
+
+@router.get("/data")
+async def get_data():
+    return {"items": ["one", "two", "three"]}
+
+@router.post("/action")
+async def do_action(body: dict):
+    return {"ok": True, "received": body}
+```
+
+Routes are mounted under `/api/plugins/<name>/`, so the above becomes:
+
+- `GET  /api/plugins/my-plugin/data`
+- `POST /api/plugins/my-plugin/action`
+
+Plugin API routes bypass session-token authentication since the dashboard server binds to localhost by default. **Don't expose the dashboard on a public interface with `--host 0.0.0.0` if you run untrusted plugins** — their routes become reachable too.
+
+#### Accessing Hermes internals
+
+Backend routes run inside the dashboard process, so they can import from the hermes-agent codebase directly:
+
+```python
+from fastapi import APIRouter
+from hermes_state import SessionDB
+from hermes_cli.config import load_config
+
+router = APIRouter()
+
+@router.get("/session-count")
+async def session_count():
+    db = SessionDB()
+    try:
+        count = len(db.list_sessions(limit=9999))
+        return {"count": count}
+    finally:
+        db.close()
+
+@router.get("/config-snapshot")
+async def config_snapshot():
+    cfg = load_config()
+    return {"model": cfg.get("model", {})}
+```
+
+### Custom CSS per plugin
+
+If your plugin needs styles beyond Tailwind classes and inline `style=`, add a CSS file and reference it in the manifest:
+
+```json
+{
+  "css": "dist/style.css"
+}
+```
+
+The file is injected as a `<link>` tag on plugin load. Use specific class names to avoid conflicts with the dashboard's styles, and reference the dashboard's CSS vars to stay theme-aware:
+
+```css
+/* dist/style.css */
+.my-plugin-chart {
+  border: 1px solid var(--color-border);
+  background: var(--color-card);
+  color: var(--color-card-foreground);
+  padding: 1rem;
+}
+.my-plugin-chart:hover {
+  border-color: var(--color-ring);
+}
+```
+
+The dashboard exposes every shadcn token as `--color-*` plus theme extras (`--theme-asset-*`, `--component-<bucket>-*`, `--radius`, `--spacing-mul`). Reference those and your plugin automatically reskins with the active theme.
+
+### Plugin discovery & reload
+
+The dashboard scans three directories for `dashboard/manifest.json`:
+
+| Priority | Directory | Source label |
+|----------|-----------|--------------|
+| 1 (wins on conflict) | `~/.hermes/plugins/<name>/dashboard/` | `user` |
+| 2 | `<repo>/plugins/memory/<name>/dashboard/` | `bundled` |
+| 2 | `<repo>/plugins/<name>/dashboard/` | `bundled` |
+| 3 | `./.hermes/plugins/<name>/dashboard/` | `project` — only when `HERMES_ENABLE_PROJECT_PLUGINS` is set |
+
+Discovery results are cached per dashboard process. After adding a new plugin, either:
+
+```bash
+# Force a rescan without restart
+curl http://127.0.0.1:9119/api/dashboard/plugins/rescan
+```
+
+…or restart `hermes dashboard`.
+
+#### Plugin load lifecycle
+
+1. Dashboard loads. `main.tsx` exposes the SDK on `window.__HERMES_PLUGIN_SDK__` and the registry on `window.__HERMES_PLUGINS__`.
+2. `App.tsx` calls `usePlugins()` → fetches `GET /api/dashboard/plugins`.
+3. For each manifest: CSS `<link>` is injected (if declared), then a `<script>` tag loads the JS bundle.
+4. The plugin's IIFE runs and calls `window.__HERMES_PLUGINS__.register(name, Component)` — and optionally `.registerSlot(name, slot, Component)` for each slot.
+5. The dashboard resolves the registered component against the manifest, adds the tab to navigation (unless `hidden`), and mounts the component as a route.
+
+Plugins have up to **2 seconds** after their script loads to call `register()`. After that the dashboard stops waiting and finishes initial render. If a plugin later registers, it still appears — the nav is reactive.
+
+If a plugin's script fails to load (404, syntax error, exception during IIFE), the dashboard logs a warning to the browser console and continues without it.
+
+---
+
+## Combined theme + plugin demo
+
+The repo ships `plugins/strike-freedom-cockpit/` as a complete reskin demo. It pairs a theme YAML with a slot-only plugin to produce a cockpit-style HUD without forking the dashboard.
+
+**What it demonstrates:**
+
+- A full theme using palette, typography, `fontUrl`, `layoutVariant: cockpit`, `assets`, `componentStyles` (notched card corners, gradient backgrounds), `colorOverrides`, and `customCSS` (scanline overlay).
+- A slot-only plugin (`tab.hidden: true`) that registers into three slots:
+  - `sidebar` — an MS-STATUS panel with live telemetry bars driven by `SDK.api.getStatus()`.
+  - `header-left` — a faction crest that reads `--theme-asset-crest` from the active theme.
+  - `footer-right` — a custom tagline replacing the default org line.
+- The plugin reads theme-supplied artwork via CSS vars, so swapping themes changes the hero/crest without plugin code changes.
+
+**Install:**
+
+```bash
+# Theme
+cp plugins/strike-freedom-cockpit/theme/strike-freedom.yaml \
+   ~/.hermes/dashboard-themes/
+
+# Plugin
+cp -r plugins/strike-freedom-cockpit ~/.hermes/plugins/
+```
+
+Open the dashboard, pick **Strike Freedom** from the theme switcher. The cockpit sidebar appears, the crest shows in the header, the tagline replaces the footer. Switch back to **Hermes Teal** and the plugin remains installed but invisible (the `sidebar` slot only renders under the `cockpit` layout variant).
+
+Read the plugin source (`plugins/strike-freedom-cockpit/dashboard/dist/index.js`) to see how it reads CSS vars, guards against older dashboards without slot support, and registers three slots from one bundle.
+
+---
+
+## API reference
+
+### Theme endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/dashboard/themes` | GET | List available themes + active name. Built-ins return `{name, label, description}`; user themes also include a `definition` field with the full normalised theme object. |
+| `/api/dashboard/theme` | PUT | Set active theme. Body: `{"name": "midnight"}`. Persists to `config.yaml` under `dashboard.theme`. |
+
+### Plugin endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/dashboard/plugins` | GET | List discovered plugins (with manifests, minus internal fields). |
+| `/api/dashboard/plugins/rescan` | GET | Force re-scan the plugin directories without restarting. |
+| `/dashboard-plugins/<name>/<path>` | GET | Serve static assets from a plugin's `dashboard/` directory. Path traversal is blocked. |
+| `/api/plugins/<name>/*` | * | Plugin-registered backend routes. |
+
+### SDK on `window`
+
+| Global | Type | Provider |
+|--------|------|----------|
+| `window.__HERMES_PLUGIN_SDK__` | object | `registry.ts` — React, hooks, UI components, API client, utils. |
+| `window.__HERMES_PLUGINS__.register(name, Component)` | function | Register a plugin's main component. |
+| `window.__HERMES_PLUGINS__.registerSlot(name, slot, Component)` | function | Register into a named shell slot. |
+
+---
+
+## Troubleshooting
+
+**My theme doesn't appear in the picker.**
+Check that the file is in `~/.hermes/dashboard-themes/` and ends in `.yaml` or `.yml`. Refresh the page. Run `curl http://127.0.0.1:9119/api/dashboard/themes` — your theme should be in the response. If the YAML has a parse error, the dashboard logs to `errors.log` under `~/.hermes/logs/`.
+
+**My plugin's tab doesn't show up.**
+1. Check the manifest is at `~/.hermes/plugins/<name>/dashboard/manifest.json` (note the `dashboard/` subdirectory).
+2. `curl http://127.0.0.1:9119/api/dashboard/plugins/rescan` to force re-discovery.
+3. Open browser dev tools → Network — confirm `manifest.json`, `index.js`, and any CSS loaded without 404s.
+4. Open browser dev tools → Console — look for errors during the IIFE or `window.__HERMES_PLUGINS__ is undefined` (indicates the SDK didn't initialize, usually a React render crash earlier).
+5. Verify your bundle calls `window.__HERMES_PLUGINS__.register(...)` with the **same name** as `manifest.json:name`.
+
+**Slot-registered components don't render.**
+The `sidebar` slot only renders when the active theme has `layoutVariant: cockpit`. Other slots always render. If you're registering into a slot with no hits, add `console.log` inside `registerSlot` to confirm the plugin bundle ran at all.
+
+**Plugin backend routes return 404.**
+1. Confirm the manifest has `"api": "plugin_api.py"` pointing to an existing file inside `dashboard/`.
+2. Restart `hermes dashboard` — plugin API routes are mounted once at startup, **not** on rescan.
+3. Check that `plugin_api.py` exports a module-level `router = APIRouter()`. Other export names are not picked up.
+4. Tail `~/.hermes/logs/errors.log` for `Failed to load plugin <name> API routes` — import errors are logged there.
+
+**Theme change drops my color overrides.**
+`colorOverrides` are scoped to the active theme and cleared on theme switch — that's by design. If you want overrides that persist, put them in your theme's YAML, not in the live switcher.
+
+**Theme customCSS gets truncated.**
+The `customCSS` block is capped at 32 KiB per theme. Split large stylesheets across multiple themes, or switch to a plugin that injects a full stylesheet via its `css` field (no size cap).
+
+**I want to ship a plugin on PyPI.**
+Dashboard plugins are installed by directory layout, not by pip entry point. The cleanest distribution path today is a git repo the user clones into `~/.hermes/plugins/`. A pip-based installer for dashboard plugins is not currently wired up.

website/docs/user-guide/features/web-dashboard.md

@@ -321,274 +321,27 @@ The frontend is built with React 19, TypeScript, Tailwind CSS v4, and shadcn/ui-
 
 When you run `hermes update`, the web frontend is automatically rebuilt if `npm` is available. This keeps the dashboard in sync with code updates. If `npm` isn't installed, the update skips the frontend build and `hermes dashboard` will build it on first launch.
 
-## Themes
+## Themes & plugins
 
-Themes control the dashboard's visual presentation across three layers:
+The dashboard ships with six built-in themes and can be extended with user-defined themes, plugin tabs, and backend API routes — all drop-in, no repo clone needed.
 
-- **Palette** — colors (background, text, accents, warm glow, noise)
-- **Typography** — font families, base size, line height, letter spacing
-- **Layout** — corner radius and density (spacing multiplier)
+**Switch themes live** from the header bar — click the palette icon next to the language switcher. Selection persists to `config.yaml` under `dashboard.theme` and is restored on page load.
 
-Switch themes live from the header bar — click the palette icon next to the language switcher. Selection persists to `config.yaml` under `dashboard.theme` and is restored on page load.
+Built-in themes:
 
-### Built-in themes
+| Theme | Character |
+|-------|-----------|
+| **Hermes Teal** (`default`) | Dark teal + cream, system fonts, comfortable spacing |
+| **Midnight** (`midnight`) | Deep blue-violet, Inter + JetBrains Mono |
+| **Ember** (`ember`) | Warm crimson + bronze, Spectral serif + IBM Plex Mono |
+| **Mono** (`mono`) | Grayscale, IBM Plex, compact |
+| **Cyberpunk** (`cyberpunk`) | Neon green on black, Share Tech Mono |
+| **Rosé** (`rose`) | Pink + ivory, Fraunces serif, spacious |
 
-Each built-in ships its own palette, typography, and layout — switching produces visible changes beyond color alone.
+To build your own theme, add a plugin tab, inject into shell slots, or expose plugin-specific REST endpoints, see **[Extending the Dashboard](./extending-the-dashboard)** — the complete guide covers:
 
-| Theme | Palette | Typography | Layout |
-|-------|---------|------------|--------|
-| **Hermes Teal** (`default`) | Dark teal + cream | System stack, 15px | 0.5rem radius, comfortable |
-| **Midnight** (`midnight`) | Deep blue-violet | Inter + JetBrains Mono, 14px | 0.75rem radius, comfortable |
-| **Ember** (`ember`) | Warm crimson / bronze | Spectral (serif) + IBM Plex Mono, 15px | 0.25rem radius, comfortable |
-| **Mono** (`mono`) | Grayscale | IBM Plex Sans + IBM Plex Mono, 13px | 0 radius, compact |
-| **Cyberpunk** (`cyberpunk`) | Neon green on black | Share Tech Mono everywhere, 14px | 0 radius, compact |
-| **Rosé** (`rose`) | Pink and ivory | Fraunces (serif) + DM Mono, 16px | 1rem radius, spacious |
-
-Themes that reference Google Fonts (everything except Hermes Teal) load the stylesheet on demand — the first time you switch to them, a `<link>` tag is injected into `<head>`.
-
-### Custom themes
-
-Drop a YAML file in `~/.hermes/dashboard-themes/` and it appears in the picker automatically. The file can be as minimal as a name plus the fields you want to override — every missing field inherits a sane default.
-
-Minimal example (colors only, bare hex shorthand):
-
-```yaml
-# ~/.hermes/dashboard-themes/neon.yaml
-name: neon
-label: Neon
-description: Pure magenta on black
-colors:
-  background: "#000000"
-  midground: "#ff00ff"
-```
-
-Full example (every knob):
-
-```yaml
-# ~/.hermes/dashboard-themes/ocean.yaml
-name: ocean
-label: Ocean Deep
-description: Deep sea blues with coral accents
-
-palette:
-  background:
-    hex: "#0a1628"
-    alpha: 1.0
-  midground:
-    hex: "#a8d0ff"
-    alpha: 1.0
-  foreground:
-    hex: "#ffffff"
-    alpha: 0.0
-  warmGlow: "rgba(255, 107, 107, 0.35)"
-  noiseOpacity: 0.7
-
-typography:
-  fontSans: "Poppins, system-ui, sans-serif"
-  fontMono: "Fira Code, ui-monospace, monospace"
-  fontDisplay: "Poppins, system-ui, sans-serif"   # optional, falls back to fontSans
-  fontUrl: "https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600&family=Fira+Code:wght@400;500&display=swap"
-  baseSize: "15px"
-  lineHeight: "1.6"
-  letterSpacing: "-0.003em"
-
-layout:
-  radius: "0.75rem"      # 0 | 0.25rem | 0.5rem | 0.75rem | 1rem | any length
-  density: comfortable   # compact | comfortable | spacious
-
-# Optional — pin individual shadcn tokens that would otherwise derive from
-# the palette. Any key listed here wins over the palette cascade.
-colorOverrides:
-  destructive: "#ff6b6b"
-  ring: "#ff6b6b"
-```
-
-Refresh the dashboard after creating the file.
-
-### Palette model
-
-The palette is a 3-layer triplet — **background**, **midground**, **foreground** — plus a warm-glow rgba() string and a noise-opacity multiplier. Every shadcn token (card, muted, border, primary, popover, etc.) is derived from this triplet via CSS `color-mix()` in the dashboard's stylesheet, so overriding three colors cascades into the whole UI.
-
-- `background` — deepest canvas color (typically near-black). The page background and card fill come from this.
-- `midground` — primary text and accent. Most UI chrome reads this.
-- `foreground` — top-layer highlight. In the default theme this is white at alpha 0 (invisible); themes that want a bright accent on top can raise its alpha.
-- `warmGlow` — rgba() vignette color used by the ambient backdrop.
-- `noiseOpacity` — 0–1.2 multiplier on the grain overlay. Lower = softer, higher = grittier.
-
-Each layer accepts `{hex, alpha}` or a bare hex string (alpha defaults to 1.0).
-
-### Typography model
-
-| Key | Type | Description |
-|-----|------|-------------|
-| `fontSans` | string | CSS font-family stack for body copy (applied to `html`, `body`) |
-| `fontMono` | string | CSS font-family stack for code blocks, `<code>`, `.font-mono` utilities, dense readouts |
-| `fontDisplay` | string | Optional heading/display font stack. Falls back to `fontSans` |
-| `fontUrl` | string | Optional external stylesheet URL. Injected as `<link rel="stylesheet">` in `<head>` on theme switch. Same URL is never injected twice. Works with Google Fonts, Bunny Fonts, self-hosted `@font-face` sheets, anything you can link |
-| `baseSize` | string | Root font size — controls the rem scale for the whole dashboard. Example: `"14px"`, `"16px"` |
-| `lineHeight` | string | Default line-height, e.g. `"1.5"`, `"1.65"` |
-| `letterSpacing` | string | Default letter-spacing, e.g. `"0"`, `"0.01em"`, `"-0.01em"` |
-
-### Layout model
-
-| Key | Values | Description |
-|-----|--------|-------------|
-| `radius` | any CSS length | Corner-radius token. Cascades into `--radius-sm/md/lg/xl` so every rounded element shifts together. |
-| `density` | `compact` \| `comfortable` \| `spacious` | Spacing multiplier. Compact = 0.85×, comfortable = 1.0× (default), spacious = 1.2×. Scales Tailwind's base spacing, so padding, gap, and space-between utilities all shift proportionally. |
-
-### Color overrides (optional)
-
-Most themes won't need this — the 3-layer palette derives every shadcn token. But if you want a specific accent that the derivation won't produce (a softer destructive red for a pastel theme, a specific success green for a brand), pin individual tokens here.
-
-Supported keys: `card`, `cardForeground`, `popover`, `popoverForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `success`, `warning`, `border`, `input`, `ring`.
-
-Any key set here overrides the derived value for the active theme only — switching to another theme clears the overrides.
-
-### Layout variants
-
-`layoutVariant` selects the overall shell layout. Defaults to `standard`.
-
-| Variant | Behaviour |
-|---------|-----------|
-| `standard` | Single column, 1600px max-width (default) |
-| `cockpit` | Left sidebar rail (260px) + main content. Populated by plugins via the `sidebar` slot |
-| `tiled` | Drops the max-width clamp so pages can use the full viewport |
-
-```yaml
-layoutVariant: cockpit
-```
-
-The current variant is exposed as `document.documentElement.dataset.layoutVariant` so custom CSS can target it via `:root[data-layout-variant="cockpit"]`.
-
-### Theme assets
-
-Ship artwork URLs with a theme. Each named slot becomes a CSS var (`--theme-asset-<name>`) that plugins and the built-in shell read; the `bg` slot is automatically wired into the backdrop.
-
-```yaml
-assets:
-  bg: "https://example.com/hero-bg.jpg"       # full-viewport background
-  hero: "/my-images/strike-freedom.png"       # for plugin sidebars
-  crest: "/my-images/crest.svg"               # for header slot plugins
-  logo: "/my-images/logo.png"
-  sidebar: "/my-images/rail.png"
-  header: "/my-images/header-art.png"
-  custom:
-    scanLines: "/my-images/scanlines.png"     # → --theme-asset-custom-scanLines
-```
-
-Values accept bare URLs (wrapped in `url(...)` automatically), pre-wrapped `url(...)`/`linear-gradient(...)`/`radial-gradient(...)` expressions, and `none`.
-
-### Component chrome overrides
-
-Themes can restyle individual shell components without writing CSS selectors via the `componentStyles` block. Each bucket's entries become CSS vars (`--component-<bucket>-<kebab-property>`) that the shell's shared components read — so `card:` overrides apply to every `<Card>`, `header:` to the app bar, etc.
-
-```yaml
-componentStyles:
-  card:
-    clipPath: "polygon(12px 0, 100% 0, 100% calc(100% - 12px), calc(100% - 12px) 100%, 0 100%, 0 12px)"
-    background: "linear-gradient(180deg, rgba(10, 22, 52, 0.85), rgba(5, 9, 26, 0.92))"
-    boxShadow: "inset 0 0 0 1px rgba(64, 200, 255, 0.28)"
-  header:
-    background: "linear-gradient(180deg, rgba(16, 32, 72, 0.95), rgba(5, 9, 26, 0.9))"
-  tab:
-    clipPath: "polygon(6px 0, 100% 0, calc(100% - 6px) 100%, 0 100%)"
-  sidebar: {...}
-  backdrop: {...}
-  footer: {...}
-  progress: {...}
-  badge: {...}
-  page: {...}
-```
-
-Supported buckets: `card`, `header`, `footer`, `sidebar`, `tab`, `progress`, `badge`, `backdrop`, `page`. Property names use camelCase (`clipPath`) and are emitted as kebab (`clip-path`). Values are plain CSS strings — anything CSS accepts (`clip-path`, `border-image`, `background`, `box-shadow`, animations, etc.).
-
-### Custom CSS
-
-For selector-level chrome that doesn't fit `componentStyles` — pseudo-elements, animations, media queries, theme-scoped overrides — drop raw CSS into the `customCSS` field:
-
-```yaml
-customCSS: |
-  :root[data-layout-variant="cockpit"] body::before {
-    content: "";
-    position: fixed;
-    inset: 0;
-    pointer-events: none;
-    z-index: 100;
-    background: repeating-linear-gradient(to bottom,
-      transparent 0px, transparent 2px,
-      rgba(64, 200, 255, 0.035) 3px, rgba(64, 200, 255, 0.035) 4px);
-    mix-blend-mode: screen;
-  }
-```
-
-The CSS is injected as a single scoped `<style data-hermes-theme-css>` tag on theme apply and cleaned up on theme switch. Capped at 32 KiB per theme.
-
-## Dashboard plugins
-
-Plugins live in `~/.hermes/plugins/<name>/dashboard/` (user) or repo `plugins/<name>/dashboard/` (bundled). Each ships a `manifest.json` plus a plain JS bundle that uses the plugin SDK exposed on `window.__HERMES_PLUGIN_SDK__`.
-
-### Manifest
-
-```json
-{
-  "name": "my-plugin",
-  "label": "My Plugin",
-  "icon": "Sparkles",
-  "version": "1.0.0",
-  "tab": {
-    "path": "/my-plugin",
-    "position": "after:skills",
-    "override": "/",
-    "hidden": false
-  },
-  "slots": ["sidebar", "header-left"],
-  "entry": "dist/index.js",
-  "css": "dist/index.css",
-  "api": "api.py"
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `tab.path` | Route path the plugin component renders at |
-| `tab.position` | `end`, `after:<tab>`, or `before:<tab>` |
-| `tab.override` | When set to a built-in path (`/`, `/sessions`, etc.), this plugin replaces that page instead of adding a new tab |
-| `tab.hidden` | When true, register component + slots but skip the nav entry. Used by slot-only plugins |
-| `slots` | Shell slots this plugin populates (documentation aid; actual registration happens from the JS bundle) |
-
-### Shell slots
-
-Plugins inject components into named shell locations by calling `window.__HERMES_PLUGINS__.registerSlot(pluginName, slotName, Component)`. Multiple plugins can populate the same slot — they render stacked in registration order.
-
-| Slot | Location |
-|------|----------|
-| `backdrop` | Inside the backdrop layer stack |
-| `header-left` | Before the Hermes brand in the top bar |
-| `header-right` | Before the theme/language switchers |
-| `header-banner` | Full-width strip below the nav |
-| `sidebar` | Cockpit sidebar rail (only rendered when `layoutVariant === "cockpit"`) |
-| `pre-main` | Above the route outlet |
-| `post-main` | Below the route outlet |
-| `footer-left` / `footer-right` | Footer cell content (replaces default) |
-| `overlay` | Fixed-position layer above everything else |
-
-### Plugin SDK
-
-Exposed on `window.__HERMES_PLUGIN_SDK__`:
-
-- `React` + `hooks` (useState, useEffect, useCallback, useMemo, useRef, useContext, createContext)
-- `components` — Card, Badge, Button, Input, Label, Select, Separator, Tabs, **PluginSlot**
-- `api` — Hermes API client, plus raw `fetchJSON`
-- `utils` — `cn()`, `timeAgo()`, `isoTimeAgo()`
-- `useI18n` — i18n hook for multi-language plugins
-
-### Demo: Strike Freedom Cockpit
-
-`plugins/strike-freedom-cockpit/` ships a complete skin demo showing every extension point — cockpit layout variant, theme-supplied hero/crest assets, notched card corners via `componentStyles`, scanlines via `customCSS`, and a slot-only plugin that populates the sidebar, header, and footer. Copy the theme YAML into `~/.hermes/dashboard-themes/` and the plugin directory into `~/.hermes/plugins/` to try it.
-
-### Theme API
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/dashboard/themes` | GET | List available themes + active name. Built-ins return `{name, label, description}`; user themes also include a `definition` field with the full normalised theme object. |
-| `/api/dashboard/theme` | PUT | Set active theme. Body: `{"name": "midnight"}` |
+- Theme YAML schema — palette, typography, layout, assets, componentStyles, colorOverrides, customCSS
+- Layout variants — `standard`, `cockpit`, `tiled`
+- Plugin manifest, SDK, shell slots, backend FastAPI routes
+- A full combined theme-plus-plugin walkthrough (Strike Freedom cockpit demo)
+- Discovery, reload, and troubleshooting

website/sidebars.ts

@@ -81,7 +81,7 @@ const sidebars: SidebarsConfig = {
           label: 'Management',
           items: [
             'user-guide/features/web-dashboard',
-            'user-guide/features/dashboard-plugins',
+            'user-guide/features/extending-the-dashboard',
           ],
         },
         {