fix: add explicit hermes-api-server toolset for API server platform

The API server adapter was creating agents without specifying enabled_toolsets, causing ALL tools from ALL toolsets to be loaded (including clarify, send_message, and text_to_speech which don't work without interactive callbacks or gateway dispatch). This could confuse models by presenting too many irrelevant tools, and meant the platform_toolsets config override didn't apply to API server. Changes: - Add hermes-api-server toolset to toolsets.py with appropriate tools (web, terminal, files, browser, vision, skills, HA tools, etc.) but excluding clarify, send_message, and text_to_speech - Update _create_agent() in api_server.py to use enabled_toolsets=[hermes-api-server] - Add api_server to PLATFORMS dict in tools_config.py for config override support - Add tests for toolset definition, tool inclusion/exclusion, and adapter wiring
2026-03-26 16:04:39 -07:00
7133 changed files with 121741 additions and 2188134 deletions
@@ -1,108 +0,0 @@
-# Git
-.git
-.gitignore
-.gitmodules
-
-# Python
-__pycache__
-*.py[cod]
-*$py.class
-*.so
-.Python
-*.egg-info/
-dist/
-build/
-
-# Virtual environments
-venv/
-env/
-ENV/
-
-# Dependencies
-node_modules
-**/node_modules
-.venv
-**/.venv
-.notebooklm-cli-venv/
-.notebooklm-playwright/
-.pip-cache/
-.uv-cache/
-
-# Built artifacts that are regenerated inside the image.  Excluded so local
-# rebuilds on the developer's machine don't invalidate the npm-install layer
-# that now depends on the full ui-tui/packages/hermes-ink/ tree being present.
-ui-tui/dist/
-ui-tui/packages/hermes-ink/dist/
-
-# CI/CD
-.github
-
-# Environment files
-.env
-.env.*
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-
-# Testing
-.pytest_cache/
-.coverage
-htmlcov/
-
-# Documentation
-*.md
-
-# Runtime data (bind-mounted at /opt/data; must not leak into build context)
-data/
-.hermes-docker/
-.notebooklm-home/
-
-# Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
-hermes-config/
-runtime/
-
-# ---------- Not needed inside the Docker image ----------
-
-# Desktop app source (Tauri/Electron); never installed in the container.
-# apps/shared is the dashboard↔desktop websocket helper and is linked from
-# web/package.json as a file: workspace dep — keep it in the build context.
-apps/
-!apps/shared/
-!apps/shared/**
-
-# Test suite — not shipped in production images
-tests/
-
-# Documentation site (Docusaurus) and supplementary docs
-website/
-docs/
-
-# Assets only used by the GitHub README
-assets/
-infographic/
-
-# Plugin-level docs (hermes-achievements ships docs/ but the runtime doesn't read them)
-plugins/hermes-achievements/docs/
-
-# Nix / Homebrew / AUR packaging metadata — irrelevant to Docker
-nix/
-flake.nix
-flake.lock
-packaging/
-
-# Design and planning documents
-plans/
-.plans/
-
-# ACP registry manifest (icon + agent.json) — not consumed at runtime
-acp_registry/
-
-# Repo-level dotfiles that are git-only or dev-tooling config
-.env.example
-.envrc
-.gitattributes
-.hadolint.yaml
-.mailmap
@@ -1,59 +1,24 @@
 # Hermes Agent Environment Configuration
 # Copy this file to .env and fill in your API keys

-# =============================================================================
-# LLM PROVIDER (Fireworks AI)
-# =============================================================================
-# Get your key at: https://app.fireworks.ai/settings/users/api-keys
-# Address models directly by catalog ID, e.g.
-#   accounts/fireworks/models/kimi-k2p6, accounts/fireworks/models/glm-5p2
-# FIREWORKS_API_KEY=
 # =============================================================================
 # LLM PROVIDER (OpenRouter)
 # =============================================================================
 # OpenRouter provides access to many models through one API
 # All LLM calls go through OpenRouter - no direct provider keys needed
 # Get your key at: https://openrouter.ai/keys
-# OPENROUTER_API_KEY=
+OPENROUTER_API_KEY=

-# Default model is configured in ~/.hermes/config.yaml (model.default).
-# Use 'hermes model' or 'hermes setup' to change it.
-# LLM_MODEL is no longer read from .env — this line is kept for reference only.
-# LLM_MODEL=anthropic/claude-opus-4.6
-
-# =============================================================================
-# LLM PROVIDER (NovitaAI)
-# =============================================================================
-# NovitaAI — 90+ models, pay-per-use
-# Get your key at: https://novita.ai/settings/key-management
-# NOVITA_API_KEY=
-# NOVITA_BASE_URL=https://api.novita.ai/openai/v1  # Override default base URL
-
-# =============================================================================
-# LLM PROVIDER (Google AI Studio / Gemini)
-# =============================================================================
-# Native Gemini API via Google's OpenAI-compatible endpoint.
-# Get your key at: https://aistudio.google.com/app/apikey
-# GOOGLE_API_KEY=your_google_ai_studio_key_here
-# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY
-# Optional base URL override (default: Google's OpenAI-compatible endpoint)
-# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
-
-# =============================================================================
-# LLM PROVIDER (Ollama Cloud)
-# =============================================================================
-# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.
-# Get your key at: https://ollama.com/settings
-# OLLAMA_API_KEY=your_ollama_key_here
-# Optional base URL override (default: https://ollama.com/v1)
-# OLLAMA_BASE_URL=https://ollama.com/v1
+# Default model to use (OpenRouter format: provider/model)
+# Examples: anthropic/claude-opus-4.6, openai/gpt-4o, google/gemini-3-flash-preview, zhipuai/glm-4-plus
+LLM_MODEL=anthropic/claude-opus-4.6

 # =============================================================================
 # LLM PROVIDER (z.ai / GLM)
 # =============================================================================
 # z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
 # Get your key at: https://z.ai or https://open.bigmodel.cn
-# GLM_API_KEY=
+GLM_API_KEY=
 # GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL

 # =============================================================================
@@ -63,30 +28,21 @@
 # Get your key at: https://platform.kimi.ai (Kimi Code console)
 # Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
 # Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
-# KIMI_API_KEY=
+KIMI_API_KEY=
 # KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys
 # KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys
 # KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys
-# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key
-
-# =============================================================================
-# LLM PROVIDER (Arcee AI)
-# =============================================================================
-# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
-# Get an Arcee key at: https://chat.arcee.ai/
-# ARCEEAI_API_KEY=
-# ARCEE_BASE_URL=                                 # Override default base URL

 # =============================================================================
 # LLM PROVIDER (MiniMax)
 # =============================================================================
 # MiniMax provides access to MiniMax models (global endpoint)
 # Get your key at: https://www.minimax.io
-# MINIMAX_API_KEY=
+MINIMAX_API_KEY=
 # MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL

 # MiniMax China endpoint (for users in mainland China)
-# MINIMAX_CN_API_KEY=
+MINIMAX_CN_API_KEY=
 # MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL

 # =============================================================================
@@ -94,7 +50,7 @@
 # =============================================================================
 # OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
 # Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
-# OPENCODE_ZEN_API_KEY=
+OPENCODE_ZEN_API_KEY=
 # OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL

 # =============================================================================
@@ -102,90 +58,34 @@
 # =============================================================================
 # OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
 # $10/month subscription. Get your key at: https://opencode.ai/auth
-# OPENCODE_GO_API_KEY=
-
-# =============================================================================
-# LLM PROVIDER (Hugging Face Inference Providers)
-# =============================================================================
-# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.
-# Free tier included ($0.10/month), no markup on provider rates.
-# Get your token at: https://huggingface.co/settings/tokens
-# Required permission: "Make calls to Inference Providers"
-# HF_TOKEN=
-# HF_BASE_URL=https://router.huggingface.co/v1  # Override default base URL
+OPENCODE_GO_API_KEY=
 # OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL

-# DeepInfra — 100+ top open models, pay-per-use.
-# Get your key at: https://deepinfra.com/dash/api_keys
-# DEEPINFRA_API_KEY=
-
-# =============================================================================
-# LLM PROVIDER (Qwen OAuth)
-# =============================================================================
-# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
-# No API key needed — credentials come from ~/.qwen/oauth_creds.json.
-# Optional base URL override:
-# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
-
-# =============================================================================
-# LLM PROVIDER (Xiaomi MiMo)
-# =============================================================================
-# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
-# Get your key at: https://platform.xiaomimimo.com
-# XIAOMI_API_KEY=your_key_here
-# Optional base URL override:
-# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
-
-# =============================================================================
-# LLM PROVIDER (Upstage Solar)
-# =============================================================================
-# Upstage provides access to Upstage Solar models.
-# Get your key at: https://console.upstage.ai/api-keys
-# UPSTAGE_API_KEY=your_key_here
-# Optional base URL override:
-# UPSTAGE_BASE_URL=https://api.upstage.ai/v1
-
 # =============================================================================
 # TOOL API KEYS
 # =============================================================================

-# Exa API Key - AI-native web search and contents
-# Get at: https://exa.ai
-# EXA_API_KEY=
-
 # Parallel API Key - AI-native web search and extract
 # Get at: https://parallel.ai
-# PARALLEL_API_KEY=
+PARALLEL_API_KEY=

 # Firecrawl API Key - Web search, extract, and crawl
 # Get at: https://firecrawl.dev/
-# FIRECRAWL_API_KEY=
+FIRECRAWL_API_KEY=


 # FAL.ai API Key - Image generation
 # Get at: https://fal.ai/
-# FAL_KEY=
+FAL_KEY=

 # Honcho - Cross-session AI-native user modeling (optional)
 # Builds a persistent understanding of the user across sessions and tools.
 # Get at: https://app.honcho.dev
 # Also requires ~/.honcho/config.json with enabled=true (see README).
-# HONCHO_API_KEY=
+HONCHO_API_KEY=

 # =============================================================================
-# HYPERLIQUID OPTIONAL SKILL
-# =============================================================================
-# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid
-#
-# Hyperliquid API base URL override
-# Default: https://api.hyperliquid.xyz
-# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
-#
-# Default address for account-level commands like state, fills, orders, and review
-# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000
-
-# =============================================================================
-# TERMINAL TOOL CONFIGURATION
+# TERMINAL TOOL CONFIGURATION (mini-swe-agent backend)
 # =============================================================================
 # Backend type: "local", "singularity", "docker", "modal", or "ssh"
 # Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
@@ -195,10 +95,6 @@
 # Only override here if you need to force a backend without touching config.yaml:
 # TERMINAL_ENV=local

-# Override the container runtime binary (e.g. to use Podman instead of Docker).
-# Useful on systems where Docker's storage driver is broken or unavailable.
-# HERMES_DOCKER_BINARY=/usr/local/bin/podman
-
 # Container images (for singularity/docker/modal backends)
 # TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
 # TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
@@ -272,10 +168,10 @@ TERMINAL_LIFETIME_SECONDS=300

 # Browserbase API Key - Cloud browser execution
 # Get at: https://browserbase.com/
-# BROWSERBASE_API_KEY=
+BROWSERBASE_API_KEY=

 # Browserbase Project ID - From your Browserbase dashboard
-# BROWSERBASE_PROJECT_ID=
+BROWSERBASE_PROJECT_ID=

 # Enable residential proxies for better CAPTCHA solving (default: true)
 # Routes traffic through residential IPs, significantly improves success rate
@@ -285,15 +181,6 @@ BROWSERBASE_PROXIES=true
 # Uses custom Chromium build to avoid bot detection altogether
 BROWSERBASE_ADVANCED_STEALTH=false

-# Browser engine for local mode (default: auto = Chrome)
-# "auto"       — use Chrome (don't pass --engine flag)
-# "lightpanda" — use Lightpanda (1.3-5.8x faster navigation, no screenshots)
-# "chrome"     — explicitly request Chrome
-# Requires agent-browser v0.25.3+. Lightpanda commands that fail or return
-# empty results are automatically retried with Chrome.
-# Also configurable via browser.engine in config.yaml.
-# AGENT_BROWSER_ENGINE=auto
-
 # Browser session timeout in seconds (default: 300)
 # Sessions are cleaned up after this duration of inactivity
 BROWSER_SESSION_TIMEOUT=300
@@ -302,27 +189,6 @@ BROWSER_SESSION_TIMEOUT=300
 # Browser sessions are automatically closed after this period of no activity
 BROWSER_INACTIVITY_TIMEOUT=120

-# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.
-# Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root
-# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,
-# many container images), so leave this unset unless you need extra flags.
-# Setting this disables the auto-injection.
-# AGENT_BROWSER_ARGS=--no-sandbox
-
-# Camofox local anti-detection browser (Camoufox-based Firefox).
-# Set CAMOFOX_URL to route the browser tools through a local Camofox server
-# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.
-# CAMOFOX_URL=http://localhost:9377
-
-# Externally managed Camofox sessions — when another app owns the visible
-# Camofox browser, set these so Hermes shares the same userId/profile instead
-# of creating its own isolated session.
-# CAMOFOX_USER_ID=
-# CAMOFOX_SESSION_KEY=
-# Set to true to reuse an already-open Camofox tab for this identity before
-# creating a new one (useful for gateway restarts).
-# CAMOFOX_ADOPT_EXISTING_TAB=false
-
 # =============================================================================
 # SESSION LOGGING
 # =============================================================================
@@ -337,7 +203,7 @@ BROWSER_INACTIVITY_TIMEOUT=120
 # Uses OpenAI's API directly (not via OpenRouter).
 # Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
 # Get at: https://platform.openai.com/api-keys
-# VOICE_TOOLS_OPENAI_KEY=
+VOICE_TOOLS_OPENAI_KEY=

 # =============================================================================
 # SLACK INTEGRATION
@@ -352,22 +218,6 @@ BROWSER_INACTIVITY_TIMEOUT=120
 # Slack allowed users (comma-separated Slack user IDs)
 # SLACK_ALLOWED_USERS=

-# =============================================================================
-# TELEGRAM INTEGRATION
-# =============================================================================
-# Telegram Bot Token - From @BotFather (https://t.me/BotFather)
-# TELEGRAM_BOT_TOKEN=
-# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs
-# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery
-# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel
-# TELEGRAM_CRON_THREAD_ID=                 # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode
-
-# Webhook mode (optional — for cloud deployments like Fly.io/Railway)
-# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
-# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
-# TELEGRAM_WEBHOOK_PORT=8443
-# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production
-
 # WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
 # WHATSAPP_ENABLED=false
 # WHATSAPP_ALLOWED_USERS=15551234567
@@ -416,6 +266,24 @@ IMAGE_TOOLS_DEBUG=false
 # CONTEXT_COMPRESSION_THRESHOLD=0.85      # Compress at 85% of context limit
 # Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)

+# =============================================================================
+# RL TRAINING (Tinker + Atropos)
+# =============================================================================
+# Run reinforcement learning training on language models using the Tinker API.
+# Requires the rl-server to be running (from tinker-atropos package).
+
+# Tinker API Key - RL training service
+# Get at: https://tinker-console.thinkingmachines.ai/keys
+TINKER_API_KEY=
+
+# Weights & Biases API Key - Experiment tracking and metrics
+# Get at: https://wandb.ai/authorize
+WANDB_API_KEY=
+
+# RL API Server URL (default: http://localhost:8080)
+# Change if running the rl-server on a different host/port
+# RL_API_URL=http://localhost:8080
+
 # =============================================================================
 # SKILLS HUB (GitHub integration for skill search/install/publish)
 # =============================================================================
@@ -432,18 +300,15 @@ IMAGE_TOOLS_DEBUG=false
 # Groq API key (free tier — used for Whisper STT in voice mode)
 # GROQ_API_KEY=

-# ElevenLabs API key (cloud STT/TTS — Scribe transcription)
-# ELEVENLABS_API_KEY=
-
 # =============================================================================
 # STT PROVIDER SELECTION
 # =============================================================================
 # Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed.
 # Install with: pip install faster-whisper
 # Model downloads automatically on first use (~150 MB for "base").
-# To use cloud providers instead, set GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, or ELEVENLABS_API_KEY above.
-# Provider priority: local > groq > openai > mistral > xai > elevenlabs
-# Configure in config.yaml: stt.provider: local | groq | openai | mistral | xai | elevenlabs
+# To use cloud providers instead, set GROQ_API_KEY or VOICE_TOOLS_OPENAI_KEY above.
+# Provider priority: local > groq > openai
+# Configure in config.yaml: stt.provider: local | groq | openai

 # =============================================================================
 # STT ADVANCED OVERRIDES (optional)
@@ -451,46 +316,7 @@ IMAGE_TOOLS_DEBUG=false
 # Override default STT models per provider (normally set via stt.model in config.yaml)
 # STT_GROQ_MODEL=whisper-large-v3-turbo
 # STT_OPENAI_MODEL=whisper-1
-# STT_ELEVENLABS_MODEL=scribe_v2

 # Override STT provider endpoints (for proxies or self-hosted instances)
 # GROQ_BASE_URL=https://api.groq.com/openai/v1
 # STT_OPENAI_BASE_URL=https://api.openai.com/v1
-# ELEVENLABS_STT_BASE_URL=https://api.elevenlabs.io/v1
-
-# =============================================================================
-# MICROSOFT TEAMS INTEGRATION
-# =============================================================================
-# Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot"
-# Or use Azure Portal: Azure Active Directory → App registrations → New registration
-# Then add the bot to Teams via the Bot Framework or App Studio.
-#
-# TEAMS_CLIENT_ID=                     # Azure AD App (client) ID
-# TEAMS_CLIENT_SECRET=                 # Azure AD client secret value
-# TEAMS_TENANT_ID=                     # Azure AD tenant ID (or "common" for multi-tenant)
-# TEAMS_ALLOWED_USERS=                 # Comma-separated AAD object IDs or UPNs
-# TEAMS_ALLOW_ALL_USERS=false          # Set true to skip the allowlist
-# TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery
-# TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel
-# TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)
-
-# =============================================================================
-# GOOGLE CHAT INTEGRATION
-# =============================================================================
-# Connects via Cloud Pub/Sub pull subscription (no public URL required).
-# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
-# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
-# 2. Create a Service Account with roles/pubsub.subscriber on the
-#    subscription (NOT project-wide); download the JSON key.
-# 3. Configure your Chat app at console.cloud.google.com/apis/credentials
-#    → Google Chat API → Configuration → Cloud Pub/Sub topic.
-# 4. (Optional, for native attachment delivery) Each user runs
-#    `/setup-files` once in their own DM after Pub/Sub is wired up.
-#
-# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
-# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>
-# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
-# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot
-# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist
-# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery
-# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel
@@ -1,5 +1 @@
-watch_file pyproject.toml uv.lock hermes
-watch_file package-lock.json package.json web/package.json ui-tui/package.json website/package.json apps/shared/package.json apps/desktop/package.json ui-tui/packages/hermes-ink/package.json
-watch_file flake.nix flake.lock nix/devShell.nix nix/tui.nix nix/package.nix nix/python.nix nix/hermes-agent.nix nix/desktop.nix
-
 use flake
@@ -1,10 +0,0 @@
-# Auto-generated files — collapse diffs and exclude from language stats
-web/package-lock.json linguist-generated=true
-
-# Enforce LF for scripts that run inside Linux containers.
-# Without this, Windows checkout converts to CRLF and breaks `exec` in the
-# container entrypoint with "no such file or directory".
-*.sh        text eol=lf
-Dockerfile  text eol=lf
-*.dockerfile text eol=lf
-docker/entrypoint.sh text eol=lf
@@ -11,7 +11,6 @@ body:
        **Before submitting**, please:
        - [ ] Search [existing issues](https://github.com/NousResearch/hermes-agent/issues) to avoid duplicates
        - [ ] Update to the latest version (`hermes update`) and confirm the bug still exists
-        - [ ] Run `hermes debug share` and paste the links below (see Debug Report section)

  - type: textarea
    id: description
@@ -83,25 +82,6 @@ body:
        - Slack
        - WhatsApp

-  - type: textarea
-    id: debug-report
-    attributes:
-      label: Debug Report
-      description: |
-        Run `hermes debug share` from your terminal and paste the links it prints here.
-        This uploads your system info, config, and recent logs to a paste service automatically.
-
-        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
-
-        If the upload fails, run `hermes debug share --local` and paste the output directly.
-      placeholder: |
-        Report   https://paste.rs/abc123
-        agent.log   https://paste.rs/def456
-        gateway.log   https://paste.rs/ghi789
-      render: shell
-    validations:
-      required: true
-
  - type: input
    id: os
    attributes:
@@ -117,6 +97,8 @@ body:
      label: Python Version
      description: Output of `python --version`
      placeholder: "3.11.9"
+    validations:
+      required: true

  - type: input
    id: hermes-version
@@ -124,14 +106,14 @@ body:
      label: Hermes Version
      description: Output of `hermes version`
      placeholder: "2.1.0"
+    validations:
+      required: true

  - type: textarea
    id: logs
    attributes:
-      label: Additional Logs / Traceback (optional)
-      description: |
-        The debug report above covers most logs. Use this field for any extra error output, 
-        tracebacks, or screenshots not captured by `hermes debug share`.
+      label: Relevant Logs / Traceback
+      description: Paste any error output, traceback, or log messages. This will be auto-formatted as code.
      render: shell

  - type: textarea
@@ -71,15 +71,3 @@ body:
      label: Contribution
      options:
        - label: I'd like to implement this myself and submit a PR
-
-  - type: textarea
-    id: debug-report
-    attributes:
-      label: Debug Report (optional)
-      description: |
-        If this feature request is related to a problem you're experiencing, run `hermes debug share` and paste the links here.
-        In an interactive chat session, you can use `/debug` instead.
-        This helps us understand your environment and any related logs.
-      placeholder: |
-        Report   https://paste.rs/abc123
-      render: shell
@@ -9,8 +9,7 @@ body:
        Sorry you're having trouble! Please fill out the details below so we can help.

        **Quick checks first:**
-        - Run `hermes debug share` and paste the links in the Debug Report section below
-        - If you're in a chat session, you can use `/debug` instead — it does the same thing
+        - Run `hermes doctor` and include the output below
        - Try `hermes update` to get the latest version
        - Check the [README troubleshooting section](https://github.com/NousResearch/hermes-agent#troubleshooting)
        - For general questions, consider the [Nous Research Discord](https://discord.gg/NousResearch) for faster help
@@ -75,21 +74,10 @@ body:
      placeholder: "2.1.0"

  - type: textarea
-    id: debug-report
+    id: doctor-output
    attributes:
-      label: Debug Report
-      description: |
-        Run `hermes debug share` from your terminal and paste the links it prints here.
-        This uploads your system info, config, and recent logs to a paste service automatically.
-
-        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
-
-        If the upload fails or install didn't get that far, run `hermes debug share --local` and paste the output directly.
-        If even that doesn't work, run `hermes doctor` and paste that output instead.
-      placeholder: |
-        Report   https://paste.rs/abc123
-        agent.log   https://paste.rs/def456
-        gateway.log   https://paste.rs/ghi789
+      label: Output of `hermes doctor`
+      description: Run `hermes doctor` and paste the full output. This will be auto-formatted.
      render: shell

  - type: textarea
@@ -1,102 +0,0 @@
-name: Detect affected areas
-description: >-
-  Classify a PR's changed files into CI work lanes (python, frontend, site,
-  scan, deps, mcp_catalog) so the orchestrator can conditionally call only
-  the sub-workflows a PR can affect. Outputs are always "true" on push/dispatch
-  events and fail open (everything "true") when the diff cannot be computed.
-
-inputs:
-  github-token:
-    description: Token for the GitHub API (gh CLI). Pass steps.app-token.outputs.token from the calling workflow.
-    required: false
-    default: ${{ github.token }}
-
-outputs:
-  python:
-    description: Run Python tests / ruff / ty / windows-footguns.
-    value: ${{ steps.classify.outputs.python }}
-  frontend:
-    description: Run the TypeScript testing matrix + desktop build.
-    value: ${{ steps.classify.outputs.frontend }}
-  docker_meta:
-    description: Docker setup and meta files have changed.
-    value: ${{ steps.classify.outputs.docker_meta }}
-  site:
-    description: Build the Docusaurus docs site.
-    value: ${{ steps.classify.outputs.site }}
-  scan:
-    description: Run the supply-chain critical-pattern scanner.
-    value: ${{ steps.classify.outputs.scan }}
-  deps:
-    description: Check pyproject.toml dependency upper bounds.
-    value: ${{ steps.classify.outputs.deps }}
-  npm_lock:
-    description: Post/update the semantic package-lock.json diff PR comment.
-    value: ${{ steps.classify.outputs.npm_lock }}
-  mcp_catalog:
-    description: Require MCP catalog security review label.
-    value: ${{ steps.classify.outputs.mcp_catalog }}
-  ci_review:
-    description: Require CI-sensitive file review label.
-    value: ${{ steps.classify.outputs.ci_review }}
-
-runs:
-  using: composite
-  steps:
-    - name: Classify changed files
-      id: classify
-      shell: bash
-      env:
-        # Fall back to the built-in read-only token when the caller passes an
-        # empty value. Fork PRs get no repo secrets, so AUTOFIX_BOT_PAT is ""
-        # there, and an input `default:` only applies when the input is omitted,
-        # not when it's passed empty. Without this fallback the compare API
-        # fails on forks and the classifier fails open (every lane forced on).
-        GH_TOKEN: ${{ inputs.github-token || github.token }}
-        REPO: ${{ github.repository }}
-        EVENT_NAME: ${{ github.event_name }}
-        BASE_SHA: ${{ github.event.pull_request.base.sha }}
-        HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-      run: |
-        set -euo pipefail
-
-        # Only pull_request events are gated. Other events (push, release,
-        # dispatch) leave CHANGED empty, so the classifier fails open and every
-        # lane runs. Post-merge / on-demand validation is never weakened.
-        if [ "$EVENT_NAME" = "pull_request" ]; then
-          # Use the compare endpoint with the pinned base/head SHAs from the
-          # event payload instead of the "current PR files" endpoint. The SHAs
-          # are frozen at trigger time, so the file list is deterministic even
-          # if the PR receives a new push between trigger and detect.
-          #
-          # Retried: a rate-limit blip or eventual-consistency 404 on a
-          # freshly-pushed HEAD would otherwise silently fall open (all lanes
-          # run — safe, but wasteful and it masks the API failure).
-          #
-          # `.files[]?` (null-safe): with --paginate, a PR more than 100
-          # commits ahead of its merge-base paginates the compare, and pages
-          # after the first carry `files: null` — bare `.files[]` makes jq
-          # die with "cannot iterate over: null", which fails every retry
-          # and forces the fail-open path (seen on stacked PRs). The full
-          # file list (up to the API's 300-file cap) is on page one.
-          CHANGED=""
-          for i in 1 2 3; do
-            if CHANGED="$(gh api \
-              --paginate \
-              "repos/${REPO}/compare/${BASE_SHA}...${HEAD_SHA}" \
-              --jq '.files[]?.filename')"; then
-              break
-            fi
-            if [ "$i" = 3 ]; then
-              echo "::warning::compare API failed after 3 attempts — failing open (all lanes run)"
-              CHANGED=""
-              break
-            fi
-            echo "::warning::compare API failed (attempt $i); retrying in 10s"
-            sleep 10
-          done
-        fi
-
-        echo "Changed files:"
-        printf '%s\n' "${CHANGED:-(none)}"
-        printf '%s\n' "${CHANGED:-}" | python3 scripts/ci/classify_changes.py
@@ -1,59 +0,0 @@
-name: Get GitHub App Token
-description: >-
-  Mint a short-lived (1-hour) installation access token from the repo's
-  GitHub App, replacing the long-lived AUTOFIX_BOT_PAT. App tokens get
-  5,000 req/hr per installation (vs 1,000 for the default GITHUB_TOKEN)
-  and are scoped to the App's installation permissions, not a user account.
-
-  Falls back to the built-in GITHUB_TOKEN when APP_CLIENT_ID is not set —
-  this happens on fork PRs where repo secrets are unavailable. The fallback
-  ensures classification, timings, and review comments still work on
-  forks (with the lower GITHUB_TOKEN rate limit).
-
-  Composite actions cannot access the secrets context directly, so the
-  calling workflow must pass secrets.APP_CLIENT_ID and secrets.APP_PRIVATE_KEY
-  as inputs. When both are empty (fork PRs), the fallback fires.
-
-inputs:
-  client-id:
-    description: GitHub App Client ID. Pass secrets.APP_CLIENT_ID from the calling workflow.
-    required: false
-    default: ''
-  private-key:
-    description: GitHub App private key PEM. Pass secrets.APP_PRIVATE_KEY from the calling workflow.
-    required: false
-    default: ''
-
-outputs:
-  token:
-    description: A GitHub App installation access token (1-hour TTL), or GITHUB_TOKEN on forks.
-    value: ${{ steps.app-token.outputs.token || steps.fallback.outputs.token }}
-
-runs:
-  using: composite
-  steps:
-    - name: Check if App credentials exist
-      id: check
-      shell: bash
-      env:
-        CLIENT_ID: ${{ inputs.client-id }}
-      run: |
-        if [ -n "$CLIENT_ID" ]; then
-          echo "has_app=true" >> "$GITHUB_OUTPUT"
-        else
-          echo "has_app=false" >> "$GITHUB_OUTPUT"
-        fi
-
-    - name: Create GitHub App token
-      id: app-token
-      if: steps.check.outputs.has_app == 'true'
-      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-      with:
-        client-id: ${{ inputs.client-id }}
-        private-key: ${{ inputs.private-key }}
-
-    - name: Fall back to GITHUB_TOKEN
-      id: fallback
-      if: steps.check.outputs.has_app != 'true'
-      shell: bash
-      run: echo "token=${{ github.token }}" >> "$GITHUB_OUTPUT"
@@ -1,18 +0,0 @@
-name: 'Setup Nix'
-description: 'Install Nix and configure Cachix binary cache'
-
-inputs:
-  cachix-auth-token:
-    description: 'Cachix auth token (enables push). Omit for read-only.'
-    required: false
-    default: ''
-
-runs:
-  using: composite
-  steps:
-    - uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
-    - uses: cachix/cachix-action@1eb2ef646ac0255473d23a5907ad7b04ce94065c # v17
-      with:
-        name: hermes-agent
-        authToken: ${{ inputs.cachix-auth-token }}
-      continue-on-error: true
@@ -1,56 +0,0 @@
-name: Hermes Plugin Validate
-description: >-
-  Validate a Hermes Agent plugin (plugin.yaml manifest schema AND
-  declared-vs-actually-registered capabilities) using
-  `hermes plugins validate`. Drop this into your plugin repo's CI:
-
-    - uses: actions/checkout@<sha>
-    - uses: NousResearch/hermes-agent/.github/actions/plugin-validate@main
-      with:
-        path: .
-
-  The caller's job owns checkout; this action installs Python + hermes-agent
-  (git install — a supported CI-context install route) and runs the
-  validator against your plugin directory.
-
-inputs:
-  path:
-    description: Path to the plugin directory (containing plugin.yaml).
-    default: "."
-  hermes-ref:
-    description: hermes-agent git ref (branch/tag/sha) to install and validate with.
-    default: "main"
-
-runs:
-  using: composite
-  steps:
-    - name: Set up Python
-      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-      with:
-        python-version: "3.11"
-
-    - name: Install hermes-agent
-      shell: bash
-      env:
-        _HERMES_REF: ${{ inputs.hermes-ref }}
-      run: |
-        set -euo pipefail
-        # CI-context install from git; the ref lets plugin authors validate
-        # against a pinned hermes release instead of main.
-        pip install "git+https://github.com/NousResearch/hermes-agent@${_HERMES_REF}"
-
-    - name: Validate plugin
-      shell: bash
-      env:
-        _PLUGIN_PATH: ${{ inputs.path }}
-      run: |
-        set -uo pipefail
-        # `hermes plugins validate` checks the plugin.yaml manifest schema
-        # and loads the plugin in a scratch subprocess to verify that the
-        # capabilities it DECLARES match what it actually registers.
-        if hermes plugins validate "$_PLUGIN_PATH"; then
-          echo "✅ PASS: plugin at '$_PLUGIN_PATH' validated cleanly"
-        else
-          echo "❌ FAIL: plugin at '$_PLUGIN_PATH' failed validation (see output above)"
-          exit 1
-        fi
@@ -1,70 +0,0 @@
-name: Retry a flaky command
-description: >-
-  Run a shell command, retrying on non-zero exit. For dependency installs
-  (npm ci, uv sync) whose only failures are transient network/toolchain
-  flakes — a node-gyp header fetch, a registry blip — so CI self-heals
-  instead of needing a manual re-run. Can also capture stdout as a step
-  output for commands whose result must be consumed by later steps.
-
-inputs:
-  command:
-    description: Shell command to run (and retry).
-    required: true
-  attempts:
-    description: Max attempts before giving up.
-    default: "3"
-  delay:
-    description: Seconds to wait between attempts.
-    default: "10"
-  working-directory:
-    description: Directory to run in.
-    default: "."
-
-outputs:
-  stdout:
-    description: Captured stdout from the successful attempt (empty if not needed).
-    value: ${{ steps.retry.outputs.stdout }}
-
-runs:
-  using: composite
-  steps:
-    - id: retry
-      shell: bash
-      working-directory: ${{ inputs.working-directory }}
-      # command goes through env, never interpolated into the script body, so
-      # a command with quotes/specials can't break or inject into the runner.
-      env:
-        _CMD: ${{ inputs.command }}
-        _ATTEMPTS: ${{ inputs.attempts }}
-        _DELAY: ${{ inputs.delay }}
-      run: |
-        set -uo pipefail
-        _OUTFILE="$(mktemp)"
-        trap 'rm -f "$_OUTFILE"' EXIT
-        n=0
-        while :; do
-          n=$((n + 1))
-          echo "::group::attempt $n/$_ATTEMPTS: $_CMD"
-          # Run the command, capturing stdout to a temp file while still
-          # streaming to the log. We redirect first, then tee the file to
-          # stdout — this avoids pipefail + tee exit-code interactions that
-          # can cause the if-branch to be skipped under set -e.
-          if bash -c "$_CMD" > "$_OUTFILE"; then
-            cat "$_OUTFILE"
-            echo "::endgroup::"
-            # Preserve newlines in the output via heredoc delimiter.
-            {
-              echo 'stdout<<__RETRY_STDOUT_EOF__'
-              cat "$_OUTFILE"
-              echo '__RETRY_STDOUT_EOF__'
-            } >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          echo "::endgroup::"
-          if [ "$n" -ge "$_ATTEMPTS" ]; then
-            echo "::error::failed after $n attempts: $_CMD"
-            exit 1
-          fi
-          echo "::warning::attempt $n failed; retrying in ${_DELAY}s: $_CMD"
-          sleep "$_DELAY"
-        done
@@ -1,44 +0,0 @@
-# Dependabot configuration for hermes-agent.
-#
-# Deliberately scoped to github-actions only.
-#
-# We do NOT enable Dependabot for pip / npm / any source-dependency ecosystem
-# because we pin source dependencies exactly (uv.lock, package-lock.json) as
-# part of our supply-chain posture. Automatic version-bump PRs against those
-# pins would undermine the strategy — pins are moved deliberately, after
-# review, not on a schedule.
-#
-# github-actions is the exception: action pins (we use full commit SHAs per
-# supply-chain policy) must be updated when upstream actions publish
-# patches — usually themselves security fixes. Dependabot opens a PR with
-# the new SHA and release notes; we review and merge like any other PR.
-#
-# Security-update PRs for source dependencies (opened ONLY when a CVE is
-# published affecting a currently-pinned version) are enabled separately
-# via the repo's Dependabot security updates setting
-# (Settings → Code security → Dependabot → Dependabot security updates).
-# Those are CVE-only, not schedule-driven, and do not conflict with our
-# pinning strategy — they fire when a pinned version becomes known-bad,
-# which is exactly when we want to move the pin.
-
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-    open-pull-requests-limit: 5
-    labels:
-      - "dependencies"
-      - "github-actions"
-    commit-message:
-      prefix: "chore(actions)"
-      include: "scope"
-    groups:
-      # Batch routine action bumps into one PR per week to reduce noise.
-      # Security updates still open individually and bypass grouping.
-      actions-minor-patch:
-        update-types:
-          - "minor"
-          - "patch"
@@ -1,399 +0,0 @@
-name: CI
-
-# Orchestrator workflow. Runs ``detect-changes`` once, then conditionally
-# calls the sub-workflows that a PR can actually affect. A final
-# ``all-checks-pass`` gate job aggregates results so branch protection only
-# needs to require a single check.
-#
-# Sub-workflows are triggered via ``workflow_call`` and keep their own job
-# definitions, matrices, and concurrency settings. They no longer have
-# ``push:`` / ``pull_request:`` triggers of their own — everything flows
-# through this file.
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-permissions:
-  contents: read
-  pull-requests: write # needed by lint (PR comment) + supply-chain review_status
-  actions: read # needed by osv-scanner (SARIF upload)
-  security-events: write # needed by osv-scanner (SARIF upload)
-  packages: write # needed by docker build
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-jobs:
-  # ─────────────────────────────────────────────────────────────────────
-  # detect: run the classifier once. Every downstream job reads its outputs
-  # to decide whether to run. On push/dispatch the classifier fails open
-  # (all lanes true) so post-merge validation is never weakened.
-  # ─────────────────────────────────────────────────────────────────────
-  detect:
-    name: Detect affected areas
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    outputs:
-      python: ${{ steps.classify.outputs.python }}
-      frontend: ${{ steps.classify.outputs.frontend }}
-      site: ${{ steps.classify.outputs.site }}
-      scan: ${{ steps.classify.outputs.scan }}
-      deps: ${{ steps.classify.outputs.deps }}
-      npm_lock: ${{ steps.classify.outputs.npm_lock }}
-      docker_meta: ${{ steps.classify.outputs.docker_meta }}
-      mcp_catalog: ${{ steps.classify.outputs.mcp_catalog }}
-      ci_review: ${{ steps.classify.outputs.ci_review }}
-      event_name: ${{ github.event_name }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-      - name: Detect affected areas
-        id: classify
-        uses: ./.github/actions/detect-changes
-        with:
-          # The get-app-token composite action falls back to GITHUB_TOKEN
-          # on fork PRs where APP_ID is unavailable.
-          github-token: ${{ steps.app-token.outputs.token }}
-
-  # ─────────────────────────────────────────────────────────────────────
-  # Lane-gated sub-workflows. Each runs in parallel after detect finishes.
-  # Skipped workflows (if condition is false) don't spin up runners.
-  # ─────────────────────────────────────────────────────────────────────
-  tests:
-    name: Python tests
-    needs: detect
-    if: needs.detect.outputs.python == 'true'
-    uses: ./.github/workflows/tests.yml
-    with:
-      slice_count: 8
-    secrets: inherit
-
-  lint:
-    name: Python lints
-    needs: detect
-    if: needs.detect.outputs.python == 'true'
-    uses: ./.github/workflows/lint.yml
-    with:
-      event_name: ${{ needs.detect.outputs.event_name }}
-    secrets: inherit
-
-  js-tests:
-    name: JS & TS checks
-    needs: detect
-    if: needs.detect.outputs.frontend == 'true'
-    uses: ./.github/workflows/js-tests.yml
-    secrets: inherit
-
-  e2e-desktop:
-    name: Desktop E2E
-    needs: detect
-    if: needs.detect.outputs.python == 'true' || needs.detect.outputs.frontend == 'true'
-    uses: ./.github/workflows/e2e-desktop.yml
-
-  docs-site:
-    name: Docs Site
-    needs: detect
-    if: needs.detect.outputs.site == 'true'
-    uses: ./.github/workflows/docs-site-checks.yml
-    secrets: inherit
-
-  history-check:
-    name: Deny unrelated histories
-    needs: detect
-    if: needs.detect.outputs.event_name == 'pull_request'
-    uses: ./.github/workflows/history-check.yml
-    secrets: inherit
-
-  contributor-check:
-    name: Check contributors
-    needs: detect
-    if: needs.detect.outputs.python == 'true'
-    uses: ./.github/workflows/contributor-check.yml
-    secrets: inherit
-
-  uv-lockfile:
-    name: Check uv.lock
-    needs: detect
-    uses: ./.github/workflows/uv-lockfile-check.yml
-    secrets: inherit
-
-  lockfile-diff:
-    name: package-lock.json diff
-    needs: detect
-    if: needs.detect.outputs.event_name == 'pull_request' && needs.detect.outputs.npm_lock == 'true'
-    uses: ./.github/workflows/lockfile-diff.yml
-    secrets: inherit
-
-  docker-lint:
-    name: Lint Docker scripts
-    needs: detect
-    if: needs.detect.outputs.docker_meta == 'true'
-    uses: ./.github/workflows/docker-lint.yml
-    secrets: inherit
-
-  docker:
-    name: Build&Test Docker image
-    needs: detect
-    if: needs.detect.outputs.python == 'true' || needs.detect.outputs.frontend == 'true' || needs.detect.outputs.docker_meta == 'true'
-    uses: ./.github/workflows/docker.yml
-    secrets: inherit
-
-  supply-chain:
-    name: Supply-chain scan
-    needs: detect
-    if: needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.scan == 'true' || needs.detect.outputs.deps == 'true')
-    uses: ./.github/workflows/supply-chain-audit.yml
-    with:
-      event_name: ${{ needs.detect.outputs.event_name }}
-      scan: ${{ needs.detect.outputs.scan == 'true' }}
-      deps: ${{ needs.detect.outputs.deps == 'true' }}
-
-  review-labels:
-    name: Review label gate
-    needs: [detect, supply-chain]
-    if: always() && needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.ci_review == 'true' || needs.detect.outputs.mcp_catalog == 'true' || needs.supply-chain.outputs.critical_findings == 'true')
-    uses: ./.github/workflows/review-labels.yml
-    with:
-      ci_review: ${{ needs.detect.outputs.ci_review == 'true' }}
-      mcp_catalog: ${{ needs.detect.outputs.mcp_catalog == 'true' }}
-      supply_chain: ${{ needs.supply-chain.outputs.critical_findings == 'true' }}
-    secrets: inherit
-
-  osv-scanner:
-    name: OSV scan
-    uses: ./.github/workflows/osv-scanner.yml
-    secrets: inherit
-
-  # ─────────────────────────────────────────────────────────────────────
-  # Live-updating PR review comment.
-  #
-  # A single ``comment-live`` job polls the GitHub Actions API every 15s
-  # for job statuses in this run, re-assembles the review comment from
-  # whatever results are available, and upserts it via the
-  # ``<!-- hermes-ci-review-bot -->`` marker.
-  #
-  # The poller exits when all non-infra jobs are completed (or on
-  # timeout). ci-timings' review_status is picked up automatically when
-  # its artifact becomes available — the poller downloads and merges it.
-  # ─────────────────────────────────────────────────────────────────────
-  comment-live:
-    name: CI review comment (live)
-    needs: [detect, review-labels, lockfile-diff, supply-chain, osv-scanner, uv-lockfile, history-check, contributor-check]
-    if: always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork != true
-    runs-on: ubuntu-latest
-    timeout-minutes: 40
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Run live comment poller
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_REPOSITORY: ${{ github.repository }}
-          GITHUB_RUN_ID: ${{ github.run_id }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-          # Commit info for the review comment header.
-          COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
-          COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message }}
-          COMMIT_URL: ${{ github.server_url }}/${{ github.repository }}/pull/${{ github.event.pull_request.number }}/commits/${{ github.event.pull_request.head.sha }}
-          # Structured review statuses from workflow_call jobs.
-          # Each job outputs a JSON array of {source, results: [...]} objects
-          # that the assembler renders directly — no hardcoded job-name
-          # matching. We merge all available outputs into one array.
-          REVIEW_STATUSES: ${{ toJSON(needs.*.outputs.review_status) }}
-        run: |
-          set -uo pipefail
-
-          # REVIEW_STATUSES is a JSON array of strings (some may be empty
-          # when a job was skipped). Parse each string and merge into one
-          # flat array for the assembler.
-          python3 - <<'PYEOF'
-          import json, os, sys
-
-          raw = os.environ.get("REVIEW_STATUSES", "")
-          merged = []
-          if raw:
-              try:
-                  arr = json.loads(raw)
-              except (json.JSONDecodeError, TypeError):
-                  arr = []
-              for item in arr:
-                  if not item:
-                      continue
-                  try:
-                      statuses = json.loads(item)
-                  except (json.JSONDecodeError, TypeError):
-                      continue
-                  if isinstance(statuses, list):
-                      merged.extend(statuses)
-
-          # Write merged array to a temp file the poller reads.
-          with open("/tmp/review_statuses.json", "w") as f:
-              json.dump(merged, f)
-          print(f"Merged {len(merged)} review status entries")
-          PYEOF
-
-          python3 scripts/ci/live_comment.py \
-            --interval 15 \
-            --timeout 2100 \
-            --review-statuses-file /tmp/review_statuses.json
-
-  # ─────────────────────────────────────────────────────────────────────
-  # Gate: runs after everything. ``if: always()`` ensures it reports a
-  # status even when some deps were skipped. Only actual ``failure``
-  # results cause it to fail; ``skipped`` is treated as success.
-  #
-  # Branch protection should require ONLY this check.
-  #
-  # Outputs ``needs-json`` — a compact ``{job_name: result}`` dict — so
-  # the live comment poller can list failed jobs in the PR comment.
-  # ─────────────────────────────────────────────────────────────────────
-  all-checks-pass:
-    name: All required checks pass
-    needs:
-      - detect
-      - tests
-      - lint
-      - js-tests
-      - e2e-desktop
-      - docs-site
-      - history-check
-      - contributor-check
-      - uv-lockfile
-      - lockfile-diff
-      - docker-lint
-      - supply-chain
-      - review-labels
-      - osv-scanner
-      # comment-live is a polling job — it doesn't block the gate.
-      # we don't require docker to pass rn because it's so slow lol
-      # - docker
-    if: always()
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    outputs:
-      needs-json: ${{ steps.evaluate.outputs.needs-json }}
-    steps:
-      - name: Evaluate job results
-        id: evaluate
-        env:
-          NEEDS: ${{ toJSON(needs) }}
-        run: |
-          echo "$NEEDS" | python3 -c "
-          import json, sys
-          needs = json.load(sys.stdin)
-          # Emit compact {job_name: result} for the comment assembler.
-          compact = {name: info['result'] for name, info in needs.items()}
-          print(f'needs-json={json.dumps(compact)}')
-          with open('$GITHUB_OUTPUT', 'a') as f:
-              f.write(f'needs-json={json.dumps(compact)}\n')
-          failed = [name for name, info in needs.items() if info['result'] == 'failure']
-          for name, info in sorted(needs.items()):
-              result = info['result']
-              icon = '✅' if result in ('success', 'skipped') else '❌'
-              print(f'{icon} {name}: {result}')
-          if failed:
-              print(f'::error::{len(failed)} job(s) failed: {\", \".join(failed)}')
-              sys.exit(1)
-          print('All checks passed (or were skipped)')
-          "
-
-  # ─────────────────────────────────────────────────────────────────────
-  # CI timing report: collect per-job/step durations from the GitHub API,
-  # cache them on main (as a baseline), and on PRs generate an HTML diff
-  # report with a gantt chart + per-step breakdown. The report is uploaded
-  # as an artifact and a markdown summary is written to $GITHUB_STEP_SUMMARY.
-  #
-  # The live comment poller picks up ci-timings' completion automatically —
-  # it reads review-status.json from the artifact when the job finishes.
-  # ─────────────────────────────────────────────────────────────────────
-  ci-timings:
-    name: CI timing report
-    needs: [all-checks-pass, docker]
-    if: always()
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - name: Restore baseline cache (PR only)
-        if: github.event_name == 'pull_request'
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: ci-timings-baseline.json
-          # Prefix-match: exact key will never hit (run_id differs), so
-          # restore-keys finds the most recent baseline from main.
-          key: ci-timings-baseline-never-exact
-          restore-keys: |
-            ci-timings-baseline-
-
-      - name: Collect timings and generate report
-        env:
-          # Forks get no repo secrets (AUTOFIX_BOT_PAT is empty); fall back to
-          # the built-in read-only token so the timings API read still works
-          # there instead of hard-failing this advisory job on every fork PR.
-          # The get-app-token composite action falls back to GITHUB_TOKEN
-          # on fork PRs where APP_ID is unavailable.
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: |
-          python3 scripts/ci/timings_report.py \
-            --baseline ci-timings-baseline.json \
-            --output ci-timings-report.html \
-            --json-out ci-timings.json \
-            --summary-out ci-timings-summary.md \
-            --review-status-out review-status.json
-
-      - name: Upload HTML report + review status
-        # Advisory report — artifact-service blips must not fail the job.
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        id: ci-timings-artifact
-        with:
-          name: ci-timings-report
-          path: |
-            ci-timings-report.html
-            review-status.json
-          retention-days: 14
-
-      - name: Output summary
-        env:
-          REPORT_URL: ${{ steps.ci-timings-artifact.outputs.artifact-url}}
-        run: |
-          echo "# CI Timing report" >> "$GITHUB_STEP_SUMMARY"
-          echo "[View the full interactive report]($REPORT_URL)" >> "$GITHUB_STEP_SUMMARY"
-          cat ci-timings-summary.md >> "$GITHUB_STEP_SUMMARY"
-
-      - name: Save baseline cache (main only)
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          # Degraded runs (API rate-limited) produce no ci-timings.json —
-          # skip rather than fail, and never cache an empty baseline.
-          if [ -f ci-timings.json ]; then
-            cp ci-timings.json ci-timings-baseline.json
-          else
-            echo "No timings JSON this run — skipping baseline update"
-          fi
-
-      - name: Upload baseline to cache (main only)
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && hashFiles('ci-timings-baseline.json') != ''
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: ci-timings-baseline.json
-          key: ci-timings-baseline-${{ github.run_id }}
@@ -1,91 +0,0 @@
-name: Contributor Attribution Check
-
-on:
-  workflow_call:
-    outputs:
-      review_status:
-        description: "JSON array of review status objects"
-        value: ${{ jobs.check-attribution.outputs.review_status }}
-
-permissions:
-  contents: read
-
-jobs:
-  check-attribution:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    outputs:
-      review_status: ${{ steps.check-emails.outputs.review_status }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          fetch-depth: 0  # Full history needed for git log
-
-      - name: Check for unmapped contributor emails
-        id: check-emails
-        run: |
-          # Get the merge base between this PR and main
-          MERGE_BASE=$(git merge-base origin/main HEAD)
-
-          # Find any new author emails in this PR's commits
-          NEW_EMAILS=$(git log ${MERGE_BASE}..HEAD --format='%ae' --no-merges | sort -u)
-
-          if [ -z "$NEW_EMAILS" ]; then
-            echo "No new commits to check."
-            echo "review_status=[]" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-
-          # An email is mapped if it has a file in contributors/emails/
-          # (one file per email — conflict-free) or an entry in the frozen
-          # legacy AUTHOR_MAP in scripts/release.py.
-          MISSING=""
-          while IFS= read -r email; do
-            # Skip teknium and bot emails
-            case "$email" in
-              *teknium*|*noreply@github.com*|*dependabot*|*github-actions*|*anthropic.com*|*cursor.com*)
-                continue ;;
-            esac
-
-            if echo "$email" | grep -qP '\+.*@users\.noreply\.github\.com'; then
-              continue  # GitHub id+login noreply emails auto-resolve
-            fi
-
-            if [ -f "contributors/emails/${email}" ]; then
-              continue  # mapped via the contributors directory
-            fi
-
-            if ! grep -qF "\"${email}\"" scripts/release.py 2>/dev/null; then
-              AUTHOR=$(git log --author="$email" --format='%an' -1)
-              MISSING="${MISSING}\n  ${email} (${AUTHOR})"
-            fi
-          done <<< "$NEW_EMAILS"
-
-          if [ -n "$MISSING" ]; then
-            echo ""
-            echo "⚠️  New contributor email(s) without a mapping:"
-            echo -e "$MISSING"
-            echo ""
-            echo "Add a mapping file (do NOT edit AUTHOR_MAP in release.py):"
-            echo -e "$MISSING" | while read -r line; do
-              email=$(echo "$line" | sed 's/^ *//' | cut -d' ' -f1)
-              [ -z "$email" ] && continue
-              echo "    python3 scripts/add_contributor.py ${email} <github-username>"
-            done
-            echo ""
-            echo "To find the GitHub username for an email:"
-            echo "  gh api 'search/users?q=EMAIL+in:email' --jq '.items[0].login'"
-
-            # Emit review_status for unmapped emails
-            DETAIL=$(echo -e "$MISSING" | sed '/^$/d; s/^  //')
-            HOW_TO_FIX=$'Add mappings to scripts/release.py AUTHOR_MAP:\n```\n"<email>": "<github-username>",\n```\nTo find the GitHub username for an email:\n```\ngh api \'search/users?q=EMAIL+in:email\' --jq \'.items[0].login\'\n```\n'
-            REVIEW_STATUS=$(jq -nc \
-              --arg detail "$DETAIL" \
-              --arg how_to_fix "$HOW_TO_FIX" \
-              '[{"source":"contributor attribution","results":[{"kind":"action_required","title":"Unmapped contributor email(s)","summary":"New contributor email(s) are not in AUTHOR_MAP.","detail":$detail,"how_to_fix":$how_to_fix}]}]')
-            echo "review_status=$REVIEW_STATUS" >> "$GITHUB_OUTPUT"
-
-            exit 1
-          else
-            echo "✅ All contributor emails are mapped."
-          fi
@@ -1,30 +1,15 @@
 name: Deploy Site

 on:
-  release:
-    types: [published]
  push:
    branches: [main]
    paths:
      - 'website/**'
-      - 'skills/**'
-      - 'optional-skills/**'
+      - 'landingpage/**'
      - '.github/workflows/deploy-site.yml'
  workflow_dispatch:
-    inputs:
-      skills_index_run_id:
-        description: 'Optional Build Skills Index run ID whose skills-index artifact should be deployed'
-        required: false
-        type: string
-      rebuild_skills_index:
-        description: 'Force a fresh multi-source crawl instead of reusing the latest healthy index'
-        required: false
-        default: false
-        type: boolean

 permissions:
-  contents: read
-  actions: read
  pages: write
  id-token: write

@@ -33,141 +18,23 @@ concurrency:
  cancel-in-progress: false

 jobs:
-  deploy-vercel:
-    # Triggered automatically on release publish (production cuts) and
-    # manually via `gh workflow run deploy-site.yml` when an out-of-band
-    # main commit needs to ship live before the next release tag — e.g.
-    # a skills-index PR that doesn't touch website/** paths and so
-    # doesn't auto-deploy via the deploy-docs path.
-    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+  build-and-deploy:
    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Trigger Vercel Deploy
-        run: curl -fsS --retry 3 --retry-delay 10 -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"
-
-  deploy-docs:
-    if: github.repository == 'NousResearch/hermes-agent'
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@v4

-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
+      - uses: actions/setup-node@v4
        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
-        with:
-          node-version: 22
+          node-version: 20
          cache: npm
          cache-dependency-path: website/package-lock.json

-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.11'
-
-      - name: Install PyYAML for skill extraction
-        uses: ./.github/actions/retry
-        with:
-          command: pip install pyyaml==6.0.2 httpx==0.28.1
-
-      - name: Prepare skills index (unified multi-source catalog)
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-          SKILLS_INDEX_RUN_ID: ${{ github.event.inputs.skills_index_run_id || '' }}
-          REBUILD_SKILLS_INDEX: ${{ github.event.inputs.rebuild_skills_index || 'false' }}
-        run: |
-          # The unified external catalog is expensive to crawl and can burn
-          # through the repository installation's GitHub API quota when several
-          # docs deploys land close together.  Normal docs deploys therefore
-          # reuse the latest healthy catalog: first the artifact from a
-          # scheduled skills-index run, then the currently live index.  Only a
-          # manual force rebuild does a fresh crawl here.
-          #
-          # If we do crawl, the build remains fatal. build_skills_index.py runs
-          # the health check BEFORE writing and exits non-zero on source
-          # collapse, keeping the last good Pages deployment live instead of
-          # publishing a degenerate catalog.
-          set -euo pipefail
-          INDEX_PATH="website/static/api/skills-index.json"
-          mkdir -p "$(dirname "$INDEX_PATH")"
-
-          validate_index() {
-            python3 - "$INDEX_PATH" <<'PY'
-          import json
-          import sys
-          from pathlib import Path
-
-          path = Path(sys.argv[1])
-          try:
-              data = json.loads(path.read_text(encoding="utf-8"))
-          except Exception as exc:
-              print(f"invalid skills index JSON: {exc}", file=sys.stderr)
-              sys.exit(1)
-          skills = data.get("skills")
-          if not isinstance(skills, list) or len(skills) < 1500:
-              count = len(skills) if isinstance(skills, list) else "missing"
-              print(f"skills index too small: {count}", file=sys.stderr)
-              sys.exit(1)
-          print(f"skills index ready: {len(skills)} skills")
-          PY
-          }
-
-          if [ "$REBUILD_SKILLS_INDEX" = "true" ]; then
-            python3 scripts/build_skills_index.py
-            validate_index
-            exit 0
-          fi
-
-          if [ -n "$SKILLS_INDEX_RUN_ID" ]; then
-            tmpdir="$(mktemp -d)"
-            echo "Downloading skills-index artifact from run $SKILLS_INDEX_RUN_ID"
-            if gh run download "$SKILLS_INDEX_RUN_ID" --name skills-index --dir "$tmpdir"; then
-              candidate="$(find "$tmpdir" -name skills-index.json -type f | head -n 1 || true)"
-              if [ -n "$candidate" ]; then
-                cp "$candidate" "$INDEX_PATH"
-                if validate_index; then
-                  exit 0
-                fi
-              fi
-            fi
-            echo "::warning::Could not use skills-index artifact from run $SKILLS_INDEX_RUN_ID; trying live index"
-          fi
-
-          echo "Downloading currently live skills index"
-          if curl -fsSL --retry 3 --retry-delay 5 \
-            "https://hermes-agent.nousresearch.com/docs/api/skills-index.json" \
-            -o "$INDEX_PATH" && validate_index; then
-            exit 0
-          fi
-
-          echo "::warning::Live skills index unavailable or unhealthy; falling back to a fresh crawl"
-          rm -f "$INDEX_PATH"
-          python3 scripts/build_skills_index.py
-          validate_index
-
-      - name: Extract skill metadata for dashboard
-        run: python3 website/scripts/extract-skills.py
-
-      - name: Extract plugin catalog for the Plugins page
-        run: python3 website/scripts/extract-plugins.py
-
-      - name: Regenerate per-skill docs pages + catalogs
-        run: python3 website/scripts/generate-skill-docs.py
-
      - name: Install dependencies
-        uses: ./.github/actions/retry
-        with:
-          command: npm ci
-          working-directory: website
+        run: npm ci
+        working-directory: website

      - name: Build Docusaurus
        run: npm run build
@@ -176,23 +43,18 @@ jobs:
      - name: Stage deployment
        run: |
          mkdir -p _site/docs
+          # Landing page at root
+          cp -r landingpage/* _site/
+          # Docusaurus at /docs/
          cp -r website/build/* _site/docs/
-          # llms.txt / llms-full.txt are also published at the site root
-          # (https://hermes-agent.nousresearch.com/llms.txt) because some
-          # agents and IDE plugins probe the classic root-level path rather
-          # than /docs/llms.txt. Same file, two URLs, one source of truth.
-          if [ -f website/build/llms.txt ]; then
-            cp website/build/llms.txt _site/llms.txt
-          fi
-          if [ -f website/build/llms-full.txt ]; then
-            cp website/build/llms-full.txt _site/llms-full.txt
-          fi
+          # CNAME so GitHub Pages keeps the custom domain between deploys
+          echo "hermes-agent.nousresearch.com" > _site/CNAME

      - name: Upload artifact
-        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
+        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

      - name: Deploy to GitHub Pages
        id: deploy
-        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4
+        uses: actions/deploy-pages@v4
@@ -1,55 +0,0 @@
-name: Docker / shell lint
-
-# Lints the container build inputs: Dockerfile (via hadolint) and any shell
-# scripts under docker/ (via shellcheck). These catch the class of regression
-# the behavioral docker smoke test can't — unquoted variable
-# expansions, silently-failing RUN commands, etc.
-#
-# Rules and ignores are documented in .hadolint.yaml at the repo root.
-# shellcheck severity is pinned to `error` so SC1091-style "can't follow
-# sourced script" info-level warnings don't fail the job — the .venv
-# activate script doesn't exist at lint time.
-
-on:
-  workflow_call:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: docker-lint-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  hadolint:
-    name: Lint Dockerfile (hadolint)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: hadolint
-        uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf # v3.1.0
-        with:
-          dockerfile: Dockerfile
-          config: .hadolint.yaml
-          failure-threshold: warning
-
-  shellcheck:
-    name: Lint docker/ shell scripts (shellcheck)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: shellcheck
-        uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # v2.0.0
-        env:
-          # Severity = error: SC1091 (can't follow sourced script) is info-
-          # level and would otherwise fail when the venv activate script
-          # doesn't exist at lint time.
-          SHELLCHECK_OPTS: --severity=error
-        with:
-          scandir: ./docker
@@ -1,219 +0,0 @@
-name: Docker Build, Test, and Publish
-
-on:
-  release:
-    types: [published]
-  workflow_call:
-
-permissions:
-  contents: read
-
-# Concurrency: push/release runs are NEVER cancelled so every merge gets
-# its own image.  PR runs reuse a PR-scoped group with
-# cancel-in-progress: true so rapid pushes to the same PR collapse to
-# the latest commit.
-concurrency:
-  group: docker-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
-
-env:
-  IMAGE_NAME: nousresearch/hermes-agent
-
-jobs:
-  # Build, test, and optionally push the image for each architecture.
-  build:
-    if: github.repository == 'NousResearch/hermes-agent'
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - arch: amd64
-            runner: ubuntu-latest
-            platform: linux/amd64
-            cache-from: type=gha,scope=docker-amd64
-            cache-to: type=gha,mode=max,scope=docker-amd64
-          - arch: arm64
-            runner: ubuntu-24.04-arm
-            platform: linux/arm64
-            cache-from: type=gha,scope=docker-arm64
-            cache-to: type=gha,mode=max,scope=docker-arm64
-
-    runs-on: ${{ matrix.runner }}
-    timeout-minutes: 45
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
-
-      # Build once, load into the local daemon for testing.  Cached
-      # per-arch; the push step below reuses every layer from this build.
-      - name: Build image (${{ matrix.arch }})
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-        with:
-          context: .
-          file: Dockerfile
-          load: true
-          platforms: ${{ matrix.platform }}
-          tags: ${{ env.IMAGE_NAME }}:test
-          build-args: |
-            HERMES_GIT_SHA=${{ github.sha }}
-          cache-from: ${{ matrix.cache-from }}
-          cache-to: ${{ (github.event_name != 'pull_request') && matrix.cache-to || '' }}
-
-      - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      # Push by digest only (no tag).  The merge job assembles the
-      # tagged manifest list.  `push-by-digest=true` is docker's recommended
-      # pattern for multi-runner multi-platform builds.
-      - name: Push ${{ matrix.arch }} by digest
-        id: push
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
-        with:
-          context: .
-          file: Dockerfile
-          platforms: ${{ matrix.platform }}
-          labels: |
-            org.opencontainers.image.revision=${{ github.sha }}
-          build-args: |
-            HERMES_GIT_SHA=${{ github.sha }}
-          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
-          cache-from: ${{ matrix.cache-from }}
-          cache-to: ${{ matrix.cache-to }}
-
-      # Write the digest to a file and upload it as an artifact so the
-      # merge job can stitch both per-arch digests into a manifest list.
-      - name: Export digest
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
-        run: |
-          mkdir -p /tmp/digests
-          digest="${{ steps.push.outputs.digest }}"
-          touch "/tmp/digests/${digest#sha256:}"
-
-      - name: Upload digest artifact
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: digest-${{ matrix.arch }}
-          path: /tmp/digests/*
-          if-no-files-found: error
-          retention-days: 1
-
-      # Run the docker-integration test suite against the freshly-built
-      # image already loaded into the local daemon (`:test`).
-      #
-      # Piggybacking here avoids a second image build: the build step
-      # already loaded the image into the daemon under
-      # `${IMAGE_NAME}:test`, so we just point ``HERMES_TEST_IMAGE`` at
-      # that.  The fixture's ``HERMES_TEST_IMAGE`` branch (see
-      # tests/docker/conftest.py:62-63) short-circuits the rebuild.
-      #
-      # Why this job and not a standalone one: the image is 5GB+; passing
-      # it between jobs via ``docker save``/``upload-artifact`` is slower
-      # than the build itself.  Reusing the existing daemon state is the
-      # cheapest path to coverage on every PR that touches docker code.
-      # ---------------------------------------------------------------------
-      - name: Install uv (for docker tests)
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-
-      - name: Set up Python 3.11 (for docker tests)
-        run: uv python install 3.11
-
-      - name: Install Python dependencies (for docker tests)
-        # ``dev`` extra pulls in pytest, pytest-asyncio —
-        # everything tests/docker/ needs.  We deliberately avoid ``all``
-        # here because the docker tests only drive the container via
-        # subprocess and don't import hermes_agent's optional deps.
-        uses: ./.github/actions/retry
-        with:
-          command: uv sync --locked --python 3.11 --extra dev
-
-      - name: Run docker integration tests
-        env:
-          # Skip rebuild; use the image already loaded by the build step.
-          HERMES_TEST_IMAGE: ${{ env.IMAGE_NAME }}:test
-          # Match the policy in tests.yml :: test job — no accidental
-          # real-API calls from inside the harness.
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""
-        run: |
-          scripts/run_tests.sh tests/docker/ --file-timeout 600
-
-  # ---------------------------------------------------------------------------
-  # Stitch both per-arch digests into a single tagged multi-arch manifest.
-  # This is a registry-side operation — no building, no layer re-push —
-  # so it runs in ~30 seconds.
-  #
-  # On main pushes: tags both :main and :latest.
-  # On releases: tags :<release_tag_name>.
-  # ---------------------------------------------------------------------------
-  merge:
-    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
-    runs-on: ubuntu-latest
-    needs: [build]
-    timeout-minutes: 10
-    steps:
-      - name: Download digests
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          path: /tmp/digests
-          pattern: digest-*
-          merge-multiple: true
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Create manifest list and push
-        working-directory: /tmp/digests
-        env:
-          IMAGE_NAME: ${{ env.IMAGE_NAME }}
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          set -euo pipefail
-          args=()
-          for digest_file in *; do
-            args+=("${IMAGE_NAME}@sha256:${digest_file}")
-          done
-          if [ "${{ github.event_name }}" = "release" ]; then
-            tags=(-t "${IMAGE_NAME}:${RELEASE_TAG}")
-          else
-            tags=(-t "${IMAGE_NAME}:main" -t "${IMAGE_NAME}:latest")
-          fi
-          # Retry: Docker Hub API + just-pushed digest eventual consistency
-          # can transiently fail the create; the operation is idempotent.
-          for i in 1 2 3; do
-            if docker buildx imagetools create "${tags[@]}" "${args[@]}"; then
-              break
-            fi
-            if [ "$i" = 3 ]; then
-              echo "::error::imagetools create failed after 3 attempts"
-              exit 1
-            fi
-            echo "::warning::imagetools create failed (attempt $i); retrying in 20s"
-            sleep 20
-          done
-
-      - name: Inspect image
-        env:
-          IMAGE_NAME: ${{ env.IMAGE_NAME }}
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          if [ "${{ github.event_name }}" = "release" ]; then
-            docker buildx imagetools inspect "${IMAGE_NAME}:${RELEASE_TAG}"
-          else
-            docker buildx imagetools inspect "${IMAGE_NAME}:main"
-          fi
@@ -1,44 +1,34 @@
 name: Docs Site Checks

 on:
-  workflow_call:
-
-permissions:
-  contents: read
+  pull_request:
+    paths:
+      - 'website/**'
+      - '.github/workflows/docs-site-checks.yml'
+  workflow_dispatch:

 jobs:
  docs-site-checks:
    runs-on: ubuntu-latest
-    timeout-minutes: 20
    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/checkout@v4

-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      - uses: actions/setup-node@v4
        with:
-          node-version: 22
+          node-version: 20
          cache: npm
          cache-dependency-path: website/package-lock.json

      - name: Install website dependencies
-        uses: ./.github/actions/retry
-        with:
-          command: npm ci
-          working-directory: website
+        run: npm ci
+        working-directory: website

-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      - uses: actions/setup-python@v5
        with:
-          python-version: "3.11"
+          python-version: '3.11'

      - name: Install ascii-guard
-        uses: ./.github/actions/retry
-        with:
-          command: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
-
-      - name: Extract skill metadata for dashboard
-        run: python3 website/scripts/extract-skills.py
-
-      - name: Regenerate per-skill docs pages + catalogs
-        run: python3 website/scripts/generate-skill-docs.py
+        run: python -m pip install ascii-guard

      - name: Lint docs diagrams
        run: npm run lint:diagrams
@@ -1,212 +0,0 @@
-name: E2E Desktop
-
-on:
-  workflow_call:
-
-permissions:
-  contents: read
-
-concurrency:
-  group: e2e-desktop-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  e2e:
-    name: Playwright E2E (Linux)
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      # ── System deps for Electron on headless Ubuntu ───────────────────
-      # Electron needs GTK, NSS,atk, etc. even under xvfb. Playwright's
-      # install-deps covers browsers; for Electron we install the apt
-      # packages directly.
-      - name: Install system dependencies for Electron
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -y -qq \
-            xvfb \
-            libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 \
-            xdg-utils libatspi2.0-0 libdrm2 libgbm1 libasound2t64
-
-      # ── Node ───────────────────────────────────────────────────────────
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-          cache: npm
-      # Full npm ci (not --ignore-scripts): electron's postinstall
-      # downloads the binary we launch, and node-pty's native build is
-      # needed for the terminal pane.
-      - uses: ./.github/actions/retry
-        with:
-          command: npm ci
-
-      # ── Python (for the hermes serve backend) ──────────────────────────
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-        with:
-          enable-cache: true
-          cache-dependency-glob: |
-            pyproject.toml
-            uv.lock
-      - name: Set up Python 3.11
-        run: uv python install 3.11
-      - name: Install Python dependencies
-        uses: ./.github/actions/retry
-        with:
-          command: uv sync --locked --python 3.11 --extra all --extra dev
-
-      # ── Build desktop app ─────────────────────────────────────────────
-      - run: npm run --prefix apps/desktop build
-
-      # ── Restore visual baseline screenshots from main ──────────────────
-      # Baselines are generated on main (via --update-snapshots) and cached.
-      # On PRs, we restore them so toHaveScreenshot has something to compare
-      # against.  The cache key is keyed on the desktop source files so a
-      # UI change naturally invalidates it — but we fall back to the main
-      # cache to avoid cold starts on unrelated PRs.
-      - name: Restore visual baseline screenshots
-        id: restore-baselines
-        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
-        with:
-          path: apps/desktop/e2e/*-snapshots
-          key: visual-baselines-${{ github.ref_name }}
-          restore-keys: |
-            visual-baselines-main
-
-      # ── Run Playwright E2E under xvfb ─────────────────────────────────
-      # xvfb runs at a fixed 1280x1024 screen so the 1220x800 Electron
-      # window always has a consistent viewport for screenshot comparison.
-      # On main, we run with --update-snapshots to generate baselines.
-      - name: Run Playwright E2E tests
-        working-directory: apps/desktop
-        run: |
-          if [ "${{ github.ref_name }}" = "main" ]; then
-            echo "On main — generating/updating baseline screenshots"
-            xvfb-run -a --server-args="-screen 0 1280x1024x24" \
-              npx playwright test --reporter=list --update-snapshots
-          else
-            echo "On PR — comparing against cached baselines"
-            xvfb-run -a --server-args="-screen 0 1280x1024x24" \
-              npx playwright test --reporter=list
-          fi
-        env:
-          CI: "true"
-          # Ensure no real API keys leak into the test env.
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""
-
-      # ── Save updated baselines to cache (main only) ───────────────────
-      - name: Save updated baselines to cache
-        if: github.ref_name == 'main' && always()
-        uses: actions/cache/save@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
-        with:
-          path: apps/desktop/e2e/*-snapshots
-          key: visual-baselines-main
-
-      # ── Upload Playwright report (HTML + traces) ──────────────────────
-      - name: Upload Playwright report
-        id: upload-report
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: playwright-report-${{ github.sha }}
-          path: apps/desktop/playwright-report
-          retention-days: 14
-          overwrite: true
-
-      # ── Upload test results (screenshots, traces, diffs) ───────────────
-      - name: Upload test results
-        id: upload-results
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: playwright-test-results-${{ github.sha }}
-          path: apps/desktop/test-results
-          retention-days: 14
-          overwrite: true
-
-      # ── Upload just the visual diffs (small, fast to review) ──────────
-      - name: Upload visual diffs
-        id: upload-diffs
-        if: always() && github.ref_name != 'main'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: visual-diffs-${{ github.sha }}
-          path: |
-            apps/desktop/test-results/**/*-diff.png
-            apps/desktop/test-results/**/*-actual.png
-            apps/desktop/test-results/**/*-expected.png
-          retention-days: 14
-          overwrite: true
-          if-no-files-found: ignore
-
-      # ── Generate step summary with visual diff info ───────────────────
-      # Parse the JSON report + scan for diff images, then post a summary
-      # to the GitHub Actions step output so reviewers can see what changed
-      # without downloading artifacts.  Runs AFTER uploads so it can link
-      # the artifact download URLs from their step outputs.
-      - name: Generate visual diff summary
-        if: always()
-        working-directory: apps/desktop
-        env:
-          REPORT_URL: ${{ steps.upload-report.outputs.artifact-url }}
-          RESULTS_URL: ${{ steps.upload-results.outputs.artifact-url }}
-          DIFFS_URL: ${{ steps.upload-diffs.outputs.artifact-url }}
-        run: |
-          echo "## Desktop E2E — Visual Diff Report" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-
-          # Count diff images (playwright writes *-diff.png on mismatch)
-          DIFF_COUNT=$(find test-results -name '*-diff.png' 2>/dev/null | wc -l)
-          ACTUAL_COUNT=$(find test-results -name '*-actual.png' 2>/dev/null | wc -l)
-
-          if [ "$DIFF_COUNT" -eq 0 ]; then
-            echo "✅ All $ACTUAL_COUNT screenshot(s) matched their baselines (or no baselines existed yet)." >> "$GITHUB_STEP_SUMMARY"
-          else
-            echo "📸 **$DIFF_COUNT of $ACTUAL_COUNT screenshot(s) differ from baseline:**" >> "$GITHUB_STEP_SUMMARY"
-            echo "" >> "$GITHUB_STEP_SUMMARY"
-            echo "| Test | Diff | Actual | Expected |" >> "$GITHUB_STEP_SUMMARY"
-            echo "|------|------|--------|----------|" >> "$GITHUB_STEP_SUMMARY"
-
-            # List each diff image with a link to the artifact
-            for diff in $(find test-results -name '*-diff.png' 2>/dev/null | sort); do
-              base=$(echo "$diff" | sed 's/-diff\.png$//')
-              test_name=$(basename "$base")
-              echo "| $test_name | [diff]($diff) | [actual](${base}-actual.png) | [expected](${base}-expected.png) |" >> "$GITHUB_STEP_SUMMARY"
-            done
-          fi
-
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "📥 **Artifacts:**" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          if [ -n "$RESULTS_URL" ]; then
-            echo "- [playwright-test-results]($RESULTS_URL) — all screenshots (actual + expected + diff) + traces" >> "$GITHUB_STEP_SUMMARY"
-          fi
-          if [ -n "$REPORT_URL" ]; then
-            echo "- [playwright-report]($REPORT_URL) — interactive HTML report" >> "$GITHUB_STEP_SUMMARY"
-          fi
-          if [ -n "$DIFFS_URL" ]; then
-            echo "- [visual-diffs]($DIFFS_URL) — just the diffed screenshots (small, fast to review)" >> "$GITHUB_STEP_SUMMARY"
-          fi
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "**To update baselines:** merge to main (baselines auto-update on main runs) or run \`npx playwright test --update-snapshots\` locally." >> "$GITHUB_STEP_SUMMARY"
-
-          # Also parse the JSON report for pass/fail counts
-          if [ -f playwright-report/results.json ]; then
-            echo "" >> "$GITHUB_STEP_SUMMARY"
-            echo "### Test Results" >> "$GITHUB_STEP_SUMMARY"
-            echo "" >> "$GITHUB_STEP_SUMMARY"
-            node -e "
-              const r = require('./playwright-report/results.json');
-              const stats = r.stats || {};
-              console.log('| Status | Count |');
-              console.log('|--------|-------|');
-              console.log('| ✅ Passed | ' + (stats.expected || 0) + ' |');
-              console.log('| ❌ Failed | ' + (stats.unexpected || 0) + ' |');
-              console.log('| ⏭️ Skipped | ' + (stats.skipped || 0) + ' |');
-              console.log('| 🔄 Flaky | ' + (stats.flaky || 0) + ' |');
-            " >> "$GITHUB_STEP_SUMMARY" 2>/dev/null || true
-          fi
@@ -1,68 +0,0 @@
-name: History Check
-
-# Rejects PRs whose branch has no common ancestor with main.
-#
-# In May 2026 PR #25045 was merged from a branch that had been disconnected
-# from main's history (likely an accidental `git checkout --orphan` or
-# `.git/` re-init).  GitHub's merge UI does not refuse merges of unrelated
-# histories, so the PR landed cleanly with the intended one-file change —
-# but its parent-less root commit (413990c94) got grafted into main as a
-# second root, and ~1500 files' worth of `git blame` history collapsed
-# onto that single commit.
-#
-# This check catches the failure mode by requiring `git merge-base` between
-# the PR head and main to be non-empty.
-
-on:
-  workflow_call:
-    outputs:
-      review_status:
-        description: "JSON array of review_status objects for the synthesizer."
-        value: ${{ jobs.check-common-ancestor.outputs.review_status }}
-
-permissions:
-  contents: read
-
-jobs:
-  check-common-ancestor:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    outputs:
-      review_status: ${{ steps.merge-base-check.outputs.review_status }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0 # full history both sides for merge-base
-
-      - id: merge-base-check
-        name: Reject PRs with no common ancestor on main
-        run: |
-          # `git merge-base` exits non-zero AND prints nothing when the two
-          # commits share no ancestor.  We check both conditions explicitly
-          # so the failure message is clear regardless of which signal fires
-          # first.
-          if ! BASE=$(git merge-base origin/main HEAD 2>/dev/null) || [ -z "$BASE" ]; then
-            STATUS='[{"source":"unrelated histories","results":[{"kind":"action_required","title":"Unrelated histories","summary":"This PR has no common ancestor with main.","detail":"","how_to_fix":"Rebase your changes onto current main:\n```\ngit fetch origin main\ngit checkout -b fix-branch origin/main\n# re-apply your changes (cherry-pick, copy files, etc.)\ngit push -f origin fix-branch\n```\n"}]}]'
-            echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
-            echo ""
-            echo "::error::This PR has no common ancestor with main."
-            echo ""
-            echo "Your branch's history is disconnected from main.  Common causes:"
-            echo "  - the branch was created with 'git checkout --orphan'"
-            echo "  - '.git/' was re-initialized at some point during the work"
-            echo "  - the branch was force-pushed from an unrelated repository"
-            echo ""
-            echo "Merging an unrelated-history PR grafts a parent-less root commit"
-            echo "into main and collapses git blame for every file in that snapshot."
-            echo "Reference: PR #25045 caused this and re-rooted blame on ~1500"
-            echo "files to a single orphan commit."
-            echo ""
-            echo "To fix, rebase your changes onto current main:"
-            echo "  git fetch origin main"
-            echo "  git checkout -b fix-branch origin/main"
-            echo "  # re-apply your changes (cherry-pick, copy files, etc.)"
-            echo "  git push -f origin fix-branch"
-            exit 1
-          fi
-          echo "::notice::Common ancestor with main: $BASE"
-          echo "review_status=[]" >> "$GITHUB_OUTPUT"
@@ -1,258 +0,0 @@
-name: auto-fix lint issues & formatting
-
-# On push to main (or manual trigger), run `npm run fix` on each workspace
-# package and apply any changes via a PR.
-#
-# Fixable lint issues (import sorting, unused imports, curly braces, etc.) are
-# auto-corrected on merge so PRs aren't blocked by them. The PR-time eslint
-# check in typecheck.yml fails only when un-fixable errors remain.
-#
-# NOTE: App token pushes DO trigger further workflow runs (unlike
-# secrets.GITHUB_TOKEN). The concurrency group (ts-autofix-${{ github.ref }})
-# with cancel-in-progress: true prevents an infinite loop — a re-triggered
-# run cancels the in-flight one, and since the second run finds no new fixes
-# (the first run already applied them), it exits with an empty patch.
-#
-# ── Security model: two-job split ───────────────────────────────────────────
-#
-# The eslint process executes repo code (eslint.config.mjs, package.json
-# scripts, installed plugins). To prevent a malicious PR from getting arbitrary
-# code execution on a runner with push access, the work is split:
-#
-#   1. generate-patch (unprivileged, contents: read only)
-#      Checks out, installs deps, runs eslint --fix, produces a .patch artifact.
-#      Worst case: malicious code runs here on an ephemeral runner with zero
-#      push permissions.
-#
-#   2. apply-patch (privileged, contents: write + pull-requests: write)
-#      Checks out, downloads the patch artifact, applies it, pushes to the
-#      bot/js-autofix branch, creates/updates a PR, and enables auto-merge.
-#      This job never runs npm, never installs anything, never executes any
-#      repo code. The only input it trusts is the patch artifact.
-#      Skipped entirely when generate-patch reports no fixes (has-fixes != true).
-#      The PR auto-merges (squash) once CI passes. If CI fails or main moves,
-#      the PR is auto-closed and the branch deleted — the next run re-applies
-#      on the current state.
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - '**/*.js'
-      - '**/*.cjs'
-      - '**/*.mjs'
-      - '**/*.ts'
-      - '**/*.tsx'
-      - 'package.json'
-      - 'package-lock.json'
-  workflow_dispatch:
-
-permissions:
-  contents: read # default; apply-patch job overrides to write
-
-concurrency:
-  group: ts-autofix-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  generate-patch:
-    name: Generate eslint --fix patch
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    outputs:
-      has-fixes: ${{ steps.produce-patch.outputs.has-fixes }}
-    # No permissions override → inherits workflow-level contents: read.
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-          cache: npm
-
-      # --ignore-scripts: eslint only needs TS sources + eslint packages.
-      - uses: ./.github/actions/retry
-        with:
-          command: npm ci --ignore-scripts
-
-      - name: npm run fix in all workspaces
-        # continue-on-error: if un-fixable errors exist on main, we still want
-        # to commit whatever fixes were applied. The PR-time check in
-        # typecheck.yml is what blocks un-fixable errors from landing.
-        continue-on-error: true
-        run: npm run fix
-
-      - name: Produce patch
-        id: produce-patch
-        run: |
-          if git diff --quiet; then
-            echo "No fixes needed."
-            echo "has-fixes=false" >> "$GITHUB_OUTPUT"
-            # Empty patch signals "nothing to do" to apply-patch.
-            : > js-fix.patch
-          else
-            git diff > js-fix.patch
-            echo "has-fixes=true" >> "$GITHUB_OUTPUT"
-            echo "Patch size: $(wc -c < js-fix.patch) bytes"
-
-            # Reject patches that touch anything outside JS/TS/JSON sources.
-            # `npm run fix` should only ever modify those; anything else means
-            # eslint/prettier or a plugin went rogue and we refuse to ship it.
-            BAD=$(git diff --name-only | grep -vE '\.(js|cjs|mjs|ts|tsx|json)$' || true)
-            if [ -n "$BAD" ]; then
-              echo "::error::Refusing to upload patch — touches disallowed files:"
-              echo "$BAD"
-              exit 1
-            fi
-          fi
-
-      - name: Upload patch artifact
-        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
-        with:
-          name: js-fix-patch
-          path: js-fix.patch
-          retention-days: 1
-          include-hidden-files: true
-
-  apply-patch:
-    name: Apply patch
-    needs: generate-patch
-    # Skip entirely when generate-patch found no fixes — saves a runner,
-    # avoids a redundant checkout/download, and keeps the job graph honest.
-    if: needs.generate-patch.outputs.has-fixes == 'true'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    permissions:
-      contents: write # needed to push to bot/js-autofix
-      pull-requests: write # needed for PR creation + auto-merge
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - name: Download patch
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: js-fix-patch
-          # ${{ runner.temp }} expands in with: params (shell-style $VAR does not).
-          # download-artifact's path is a *directory* — the artifact's js-fix.patch
-          # file lands inside it, so $RUNNER_TEMP/js-fix.patch resolves correctly
-          # in the run step below.
-          path: ${{ runner.temp }}
-
-      - name: Apply patch and push to bot branch
-        env:
-          BOT_BRANCH: bot/js-autofix
-        run: |
-          set -euo pipefail
-
-          # Empty patch = nothing to do.
-          if [ ! -s "$RUNNER_TEMP/js-fix.patch" ]; then
-            echo "Patch is empty. No fixes to apply."
-            exit 0
-          fi
-
-          # Apply the patch produced by the unprivileged job.
-          git apply --check "$RUNNER_TEMP/js-fix.patch" || {
-            echo "::error::Patch does not apply cleanly. Branch may have moved."
-            exit 1
-          }
-          git apply "$RUNNER_TEMP/js-fix.patch"
-
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add -A
-          git commit -m "fmt(js): \`npm run fix\` on merge"
-
-          # Push to the dedicated bot branch. Force-push is safe here:
-          # bot/js-autofix is a bot-only branch that gets rewritten each run.
-          # If the branch was deleted after a previous PR merge, this
-          # recreates it.
-          git push --force origin HEAD:"$BOT_BRANCH"
-
-      - name: Create/update PR and enable auto-merge
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          BOT_BRANCH: bot/js-autofix
-        run: |
-          set -euo pipefail
-
-          # Create PR if one doesn't exist. If it already exists, the
-          # force-push above already updated it with the latest fixes.
-          PR_NUM=$(gh pr list --head "$BOT_BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || true)
-          if [ -z "$PR_NUM" ]; then
-            # gh pr create prints the PR URL. Extract the number from it
-            # (https://github.com/<org>/<repo>/pull/<number>).
-            PR_URL=$(gh pr create \
-              --head "$BOT_BRANCH" --base main \
-              --title 'fmt(js): `npm run fix` auto-fix' \
-              --body 'Auto-generated by the `auto-fix lint issues & formatting` workflow. Auto-merges (squash) once CI passes. If CI fails or `main` moves, the PR is auto-closed and the branch deleted — the next run re-applies on the current state.')
-            PR_NUM=$(echo "$PR_URL" | grep -oE '[0-9]+$')
-          fi
-
-          # Enable auto-merge (squash). If already enabled, this is a no-op.
-          gh pr merge "$PR_NUM" --auto --squash || true
-
-      - name: Wait for merge, auto-close on failure or stale
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          START_SHA: ${{ github.sha }}
-        run: |
-          set -euo pipefail
-
-          PR_NUM=$(gh pr list --head bot/js-autofix --state open --json number --jq '.[0].number' 2>/dev/null || true)
-          if [ -z "$PR_NUM" ]; then
-            echo "No open PR. Nothing to wait for."
-            exit 0
-          fi
-
-          echo "Waiting for PR #$PR_NUM to merge..."
-
-          # Poll every 15s for up to ~10 minutes. Auto-merge will handle the
-          # PR even if this job times out — the polling is for cleanup only
-          # (auto-close on CI failure, conflicts, or main moving).
-          for i in $(seq 1 40); do
-            sleep 15
-
-            STATE=$(gh pr view "$PR_NUM" --json state --jq '.state')
-            if [ "$STATE" = "MERGED" ] || [ "$STATE" = "CLOSED" ]; then
-              echo "PR #$PR_NUM is $STATE."
-              exit 0
-            fi
-
-            # If main moved, the PR may have already merged (which moves
-            # main) or another commit landed. Re-check state first.
-            CURRENT_SHA=$(gh api "repos/${{ github.repository }}/branches/main" --jq '.commit.sha')
-            if [ "$CURRENT_SHA" != "$START_SHA" ]; then
-              STATE=$(gh pr view "$PR_NUM" --json state --jq '.state')
-              if [ "$STATE" = "MERGED" ]; then
-                echo "PR #$PR_NUM merged (main moved to $CURRENT_SHA)."
-                exit 0
-              fi
-              echo "Main moved ($START_SHA → $CURRENT_SHA). Closing stale PR."
-              gh pr close "$PR_NUM" --delete-branch || true
-              exit 0
-            fi
-
-            # If CI checks failed, close + delete the branch.
-            if gh pr checks "$PR_NUM" 2>/dev/null | grep -qi "fail"; then
-              echo "CI failed on PR #$PR_NUM. Closing + deleting branch."
-              gh pr close "$PR_NUM" --delete-branch
-              exit 0
-            fi
-
-            # If PR is conflicted, close + delete the branch.
-            MERGEABLE=$(gh pr view "$PR_NUM" --json mergeable --jq '.mergeable')
-            if [ "$MERGEABLE" = "CONFLICTING" ]; then
-              echo "PR #$PR_NUM is conflicted. Closing + deleting branch."
-              gh pr close "$PR_NUM" --delete-branch
-              exit 0
-            fi
-          done
-
-          echo "Timeout reached. Auto-merge will handle PR #$PR_NUM if CI passes."
@@ -1,51 +0,0 @@
-# .github/workflows/js-tests.yml
-name: JS Tests
-
-on:
-  workflow_call:
-
-jobs:
-  workspaces:
-    name: List npm workspaces
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    outputs:
-      packages: ${{ steps.set-matrix.outputs.packages }}
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-          cache: npm
-      - uses: ./.github/actions/retry
-        with:
-          command: npm ci --ignore-scripts
-      - id: set-matrix
-        run: |
-          PACKAGES=$(npm query .workspace | jq -c '[.[].location]')
-          if [ "$PACKAGES" = "[]" ] || [ -z "$PACKAGES" ]; then
-            echo "::error::Workspace discovery produced an empty package list — refusing to emit a zero-length matrix (would skip all JS/TS checks silently)."
-            exit 1
-          fi
-          echo "packages=$PACKAGES" >> "$GITHUB_OUTPUT"
-
-  check:
-    name: Typecheck & Test
-    needs: workspaces
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    strategy:
-      matrix:
-        package: ${{ fromJson(needs.workspaces.outputs.packages) }}
-      fail-fast: false # report all failures, not just the first one
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: 22
-          cache: npm
-      - uses: ./.github/actions/retry
-        with:
-          command: npm ci
-      - run: npm run --prefix ${{ matrix.package }} check
-      - run: npm run --prefix ${{ matrix.package }} fix
@@ -1,81 +0,0 @@
-name: Label rerun
-
-# When the ``ci-reviewed`` label is added to a PR, rerun all failed jobs in
-# the latest CI run. This re-evaluates ``review-labels`` (which now sees the
-# label) and GitHub automatically reruns dependent jobs (``comment-live``,
-# ``all-checks-pass``) — so the review comment gets updated too.
-#
-# If the CI run is still in progress when the label is added, we wait for it
-# to finish before rerunning (``gh run rerun`` only works on completed runs).
-# The wait can be long (20+ min for a full CI run), but it's better than
-# silently failing and leaving the reviewer stuck.
-
-on:
-  pull_request:
-    types: [labeled]
-
-permissions:
-  actions: write
-  pull-requests: read
-
-concurrency:
-  group: label-rerun-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  rerun-review-labels:
-    name: Rerun review-labels job
-    if: github.event.label.name == 'ci-reviewed'
-    runs-on: ubuntu-latest
-    timeout-minutes: 40
-    steps:
-      - name: Wait for CI run to finish, then rerun failed jobs
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REPO: ${{ github.repository }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-        run: |
-          set -uo pipefail
-
-          # Find the latest CI run for this PR's head SHA.
-          RUN_ID=$(gh run list \
-            --repo "$REPO" \
-            --commit "$HEAD_SHA" \
-            --workflow ci.yml \
-            --limit 1 \
-            --json databaseId,status \
-            --jq '.[0] | "\(.databaseId) \(.status)"' 2>/dev/null || true)
-
-          if [ -z "$RUN_ID" ]; then
-            echo "No CI run found for this PR — nothing to rerun."
-            exit 0
-          fi
-
-          # Split "RUN_ID STATUS" into two vars.
-          RUN_ID="${RUN_ID%% *}"
-          STATUS="${RUN_ID##* }"
-
-          echo "Latest CI run: $RUN_ID (status: $STATUS)"
-
-          # If the run is still in progress, wait for it to finish.
-          # gh run rerun only works on completed runs — if we try while it's
-          # running, GitHub rejects with "cannot be rerun; This workflow is
-          # already running".
-          if [ "$STATUS" != "completed" ]; then
-            echo "Run is $STATUS — waiting for completion (this may take a while)..."
-            # gh run watch --exit-status exits non-zero if the run fails,
-            # which is expected (the label gate fails). Don't let that kill
-            # the workflow — we WANT to rerun failed jobs.
-            timeout 2100 gh run watch "$RUN_ID" --repo "$REPO" --interval 15 || true
-
-            # Verify it's actually completed now.
-            STATUS=$(gh run view "$RUN_ID" --repo "$REPO" --json status --jq '.status' 2>/dev/null || echo "unknown")
-            if [ "$STATUS" != "completed" ]; then
-              echo "Run is still $STATUS after wait — giving up."
-              exit 0
-            fi
-          fi
-
-          echo "Run completed. Rerunning all failed jobs..."
-          gh run rerun "$RUN_ID" --repo "$REPO" --failed || true
-          echo "Done. GitHub will rerun review-labels and all dependent jobs."
@@ -1,162 +0,0 @@
-name: Lint (ruff + ty)
-
-# Two things here:
-#   1. Advisory diff — ruff + ty diagnostics as a diff vs the target branch.
-#      Writes a Markdown summary to the run page. Exit zero always.
-#   2. Blocking ``ruff check .`` — enforces the explicit rules in
-#      ``[tool.ruff.lint.select]`` (currently PLW1514). Failure blocks merge.
-#      Separate job so the advisory diff still runs even when enforcement
-#      fails.
-#
-# CI-sensitive file review was previously here as a ``ci-review`` job but
-# has moved to ``review-labels.yml`` so it can be rerun independently.
-
-on:
-  workflow_call:
-    inputs:
-      event_name:
-        description: The event name from the calling orchestrator (pull_request or push).
-        type: string
-        required: true
-
-permissions:
-  contents: read
-
-concurrency:
-  group: lint-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  lint-diff:
-    name: ruff + ty diff
-    if: inputs.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0 # need full history for merge-base + worktree
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-
-      - name: Install ruff + ty
-        uses: ./.github/actions/retry
-        with:
-          command: uv tool install ruff && uv tool install ty
-
-      - name: Determine base ref
-        id: base
-        run: |
-          # For PRs, diff against the merge base with the target branch.
-          # For pushes to main, diff against the previous commit on main.
-          if [ "${{ inputs.event_name }}" = "pull_request" ]; then
-            BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
-            BASE_REF="origin/${{ github.base_ref }}"
-          else
-            BASE_SHA=$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)
-            BASE_REF="HEAD~1"
-          fi
-          echo "sha=${BASE_SHA}" >> "$GITHUB_OUTPUT"
-          echo "ref=${BASE_REF}" >> "$GITHUB_OUTPUT"
-          echo "Base SHA: ${BASE_SHA}"
-          echo "Base ref: ${BASE_REF}"
-
-      - name: Run ruff + ty on HEAD
-        run: |
-          mkdir -p .lint-reports/head
-          ruff check --output-format json --exit-zero \
-            > .lint-reports/head/ruff.json || true
-          ty check --output-format gitlab --exit-zero \
-            > .lint-reports/head/ty.json || true
-          echo "HEAD ruff: $(wc -c < .lint-reports/head/ruff.json) bytes"
-          echo "HEAD ty:   $(wc -c < .lint-reports/head/ty.json) bytes"
-
-      - name: Run ruff + ty on base (via git worktree)
-        run: |
-          mkdir -p .lint-reports/base
-          # Use a worktree so we don't clobber the main checkout. If the basex
-          # SHA is identical to HEAD (e.g. first commit), skip and leave the
-          # base reports empty — the diff script handles missing files.
-          HEAD_SHA=$(git rev-parse HEAD)
-          BASE_SHA="${{ steps.base.outputs.sha }}"
-          if [ "$BASE_SHA" = "$HEAD_SHA" ]; then
-            echo "Base SHA == HEAD SHA, skipping base scan."
-            echo '[]' > .lint-reports/base/ruff.json
-            echo '[]' > .lint-reports/base/ty.json
-          else
-            git worktree add --detach /tmp/lint-base "$BASE_SHA"
-            (
-              cd /tmp/lint-base
-              ruff check --output-format json --exit-zero \
-                > "$GITHUB_WORKSPACE/.lint-reports/base/ruff.json" || true
-              ty check --output-format gitlab --exit-zero \
-                > "$GITHUB_WORKSPACE/.lint-reports/base/ty.json" || true
-            )
-            git worktree remove --force /tmp/lint-base
-          fi
-          echo "base ruff: $(wc -c < .lint-reports/base/ruff.json) bytes"
-          echo "base ty:   $(wc -c < .lint-reports/base/ty.json) bytes"
-
-      - name: Generate diff summary
-        env:
-          HEAD_REF: ${{ inputs.event_name == 'pull_request' && github.head_ref || github.ref_name }}
-        run: |
-          python scripts/lint_diff.py \
-            --base-ruff .lint-reports/base/ruff.json \
-            --head-ruff .lint-reports/head/ruff.json \
-            --base-ty   .lint-reports/base/ty.json \
-            --head-ty   .lint-reports/head/ty.json \
-            --base-ref  "${{ steps.base.outputs.ref }}" \
-            --head-ref  "$HEAD_REF" \
-            --output    .lint-reports/summary.md
-          cat .lint-reports/summary.md >> "$GITHUB_STEP_SUMMARY"
-
-  ruff-blocking:
-    # Enforce the rules in pyproject.toml [tool.ruff.lint.select]. Currently
-    # PLW1514 (unspecified-encoding) — catches bare ``open()`` /
-    # ``read_text()`` / ``write_text()`` calls that default to locale
-    # encoding on Windows. Failure here blocks merge; the advisory
-    # ``lint-diff`` job above runs independently so reviewers still get
-    # the diff comment even when enforcement fails.
-    name: ruff enforcement (blocking)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-
-      - name: Install ruff
-        uses: ./.github/actions/retry
-        with:
-          command: uv tool install ruff
-
-      - name: ruff check .
-        # No --exit-zero, no || true. Exit code propagates to the job,
-        # which propagates to the required-check gate.
-        run: |
-          ruff check .
-
-  windows-footguns:
-    # Static guardrails on Windows-unsafe Python primitives — os.kill(pid, 0),
-    # os.killpg, os.setsid, signal.SIGKILL without getattr fallback,
-    # shebang scripts via subprocess, bare open() without encoding=, etc.
-    # See scripts/check-windows-footguns.py for the full rule list.
-    name: Windows footguns (blocking)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v5
-        with:
-          python-version: "3.11"
-
-      - name: Run footgun checker
-        run: python scripts/check-windows-footguns.py --all
@@ -1,95 +0,0 @@
-name: Lockfile diff
-
-# Advisory PR comment showing the *semantic* diff of package-lock.json
-# changes — which packages were added/removed/updated and their versions.
-# The raw textual diff of a lockfile is unreadable (npm reorders entries
-# and rewrites integrity hashes), so scripts/ci/lockfile_diff.py parses
-# the ``packages`` map at the merge base and at HEAD and set-diffs the
-# {install path: version} maps instead.
-#
-# The semantic diff is exposed as a workflow_call output ``review_status``
-# (a JSON array in the unified status format) and an artifact
-# (``lockfile-diff`` containing the markdown fragment) for the step
-# summary.
-#
-# Never blocking — this is review signal, not enforcement.
-
-on:
-  workflow_call:
-    outputs:
-      changed:
-        description: Whether package-lock.json changed relative to the target branch.
-        value: ${{ jobs.diff.outputs.changed }}
-      review_status:
-        description: JSON array of review status objects for the unified PR comment.
-        value: ${{ jobs.diff.outputs.review_status }}
-
-permissions:
-  contents: read
-
-concurrency:
-  group: lockfile-diff-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  diff:
-    name: package-lock.json semantic diff
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    outputs:
-      changed: ${{ steps.diff.outputs.changed }}
-      review_status: ${{ steps.emit-status.outputs.review_status }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0 # need history for the merge base
-
-      - name: Generate semantic lockfile diff
-        id: diff
-        run: |
-          set -euo pipefail
-          # Three-dot semantics by hand: diff from the merge base with the
-          # target branch to the PR head, so changes that landed on main
-          # after the branch point don't show up as this PR's doing.
-          BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
-          echo "Merge base: ${BASE_SHA}"
-          python3 scripts/ci/lockfile_diff.py \
-            --base "$BASE_SHA" \
-            --head HEAD \
-            --output /tmp/lockfile-diff.md
-          if [ -s /tmp/lockfile-diff.md ]; then
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-            {
-              echo "## package-lock.json semantic diff"
-              echo ""
-              cat /tmp/lockfile-diff.md
-            } >> "$GITHUB_STEP_SUMMARY"
-          else
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-            : > /tmp/lockfile-diff.md
-          fi
-
-      - name: Emit review_status
-        id: emit-status
-        run: |
-          set -euo pipefail
-          CHANGED="${{ steps.diff.outputs.changed }}"
-          STATUS="[]"
-
-          if [ "$CHANGED" = "true" ]; then
-            CONTENT=$(cat /tmp/lockfile-diff.md | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
-            STATUS="[{\"source\":\"lockfile-diff\",\"results\":[{\"kind\":\"action_required\",\"title\":\"package-lock.json\",\"summary\":\"Locked npm dependency versions changed.\",\"detail\":${CONTENT},\"how_to_fix\":\"Add the \`ci-reviewed\` label after verifying the version changes are expected.\"}]}"
-          else
-            STATUS="[]"
-          fi
-
-          echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
-
-      - name: Upload diff artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: lockfile-diff
-          path: /tmp/lockfile-diff.md
-          retention-days: 1
-          overwrite: true
@@ -0,0 +1,40 @@
+name: Nix
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    paths:
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'nix/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'hermes_cli/**'
+      - 'run_agent.py'
+      - 'acp_adapter/**'
+
+concurrency:
+  group: nix-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nix:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+      - name: Check flake
+        if: runner.os == 'Linux'
+        run: nix flake check --print-build-logs
+      - name: Build package
+        if: runner.os == 'Linux'
+        run: nix build --print-build-logs
+      - name: Evaluate flake (macOS)
+        if: runner.os == 'macOS'
+        run: nix flake show --json > /dev/null
@@ -1,124 +0,0 @@
-name: OSV-Scanner
-
-# Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
-# database. Runs on every PR/push (via the ci.yml orchestrator's workflow_call)
-# and on a weekly schedule against main.
-#
-# This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
-# It reports known CVEs in currently-pinned dependency versions so we can
-# decide when and how to patch on our own schedule. Our pinning strategy
-# (full SHA / exact version) is preserved; only the notification signal
-# is added.
-#
-# Complements the supply-chain-audit.yml workflow (which scans for malicious
-# code patterns in PR diffs) by covering the orthogonal "currently-pinned
-# dep became known-vulnerable" case.
-#
-# Uses Google's officially-recommended reusable workflow, pinned by SHA.
-# Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
-# fail-on-vuln is disabled so the job does not block merges on pre-existing
-# vulnerabilities in pinned deps that we may need to patch deliberately.
-#
-# The reusable workflow can't emit custom outputs, so a wrapper job
-# downloads the SARIF result and summarizes the vulnerability count into
-# a review_status for the unified PR comment.
-
-on:
-  workflow_call:
-  schedule:
-    # Weekly scan against main — catches CVEs published after merge for
-    # deps that haven't changed since.
-    - cron: '0 9 * * 1'
-  workflow_dispatch:
-
-permissions:
-  # Required to upload SARIF file to CodeQL. See: https://github.com/github/codeql-action/issues/2117
-  actions: read
-  contents: read
-  security-events: write
-
-jobs:
-  scan:
-    name: Scan lockfiles
-    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@9a498708959aeaef5ef730655706c5a1df1edbc2 # v2.3.8
-    with:
-      # Scan explicit lockfiles rather than recursing, so we only look at
-      # the three sources of truth and skip vendored / test / worktree dirs.
-      scan-args: |-
-        --lockfile=uv.lock
-        --lockfile=package-lock.json
-        --lockfile=website/package-lock.json
-      fail-on-vuln: false
-
-  emit-status:
-    name: Emit review status
-    runs-on: ubuntu-latest
-    needs: scan
-    if: always()
-    outputs:
-      review_status: ${{ steps.emit.outputs.review_status }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Download SARIF result
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: osv-results
-          path: /tmp/osv-results
-        continue-on-error: true
-
-      - name: Emit review_status
-        id: emit
-        run: |
-          set -euo pipefail
-          STATUS="[]"
-
-          if [ -f /tmp/osv-results/osv-results.sarif ]; then
-            # Count vulnerabilities from the SARIF file
-            VULN_COUNT=$(python3 -c "
-          import json, sys
-          try:
-              with open('/tmp/osv-results/osv-results.sarif') as f:
-                  data = json.load(f)
-              count = 0
-              vulns = []
-              for run in data.get('runs', []):
-                  for result in run.get('results', []):
-                      count += 1
-                      rule_id = result.get('ruleId', 'unknown')
-                      message = result.get('message', {}).get('text', '')
-                      loc = result.get('locations', [{}])[0].get('physicalLocation', {}).get('artifactLocation', {}).get('uri', '')
-                      vulns.append(f'- {rule_id} in {loc}: {message}')
-              print(count)
-              if vulns:
-                  print('\n'.join(vulns[:20]), file=sys.stderr)
-          except Exception:
-              print(0)
-          ")
-
-            VULN_DETAIL=""
-            if [ "$VULN_COUNT" -gt 0 ] 2>/dev/null; then
-              VULN_PLURAL=$([ "$VULN_COUNT" -eq 1 ] && echo "y" || echo "ies")
-              VULN_DETAIL=$(python3 -c "
-          import json, sys
-          try:
-              with open('/tmp/osv-results/osv-results.sarif') as f:
-                  data = json.load(f)
-              vulns = []
-              for run in data.get('runs', []):
-                  for result in run.get('results', []):
-                      rule_id = result.get('ruleId', 'unknown')
-                      loc = result.get('locations', [{}])[0].get('physicalLocation', {}).get('artifactLocation', {}).get('uri', '')
-                      vulns.append(f'- {rule_id} in {loc}')
-              print(json.dumps('\n'.join(vulns[:20])))
-          except Exception:
-              print(json.dumps(''))
-          ")
-              STATUS="[{\"source\":\"osv scan\",\"results\":[{\"kind\":\"warning\",\"title\":\"OSV vulnerability scan\",\"summary\":\"${VULN_COUNT} known vulnerabilit${VULN_PLURAL} found in pinned dependencies.\",\"detail\":${VULN_DETAIL},\"how_to_fix\":\"Review the findings in the [Security tab](../../security/code-scanning). Update the affected dependencies if a patched version is available.\"}]}]"
-            else
-              STATUS="[]"
-            fi
-          fi
-
-          echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
@@ -1,140 +0,0 @@
-name: Plugin Catalog CI
-
-# Admission gate for plugin-catalog entries. Fires ONLY on PRs touching
-# plugin-catalog/** so it can never go red on unrelated PRs.
-#
-# Two gates:
-#   structural            — cheap schema check, no hermes install needed
-#   pinned-source-validate — supply-chain gate: the pinned sha MUST be
-#                            reachable in the entry's repo, and the plugin
-#                            at that exact commit must pass
-#                            `hermes plugins validate`.
-
-on:
-  pull_request:
-    paths:
-      - "plugin-catalog/**"
-
-permissions:
-  contents: read
-
-jobs:
-  structural:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.11"
-
-      - name: Install PyYAML
-        uses: ./.github/actions/retry
-        with:
-          command: pip install pyyaml==6.0.2
-
-      - name: Validate catalog files (structural)
-        run: |
-          set -euo pipefail
-          # Validating the whole directory is simpler than diffing and keeps
-          # the invariant that EVERYTHING in plugin-catalog/ stays valid.
-          python3 scripts/validate_plugin_catalog.py plugin-catalog/
-
-  pinned-source-validate:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0 # need the merge-base to diff changed catalog files
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.11"
-
-      - name: Find changed catalog entries
-        id: changed
-        run: |
-          set -euo pipefail
-          MERGE_BASE=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
-          # Added + modified entry files only; deletions and removed.yaml
-          # have nothing to clone.
-          CHANGED=$(git diff --name-only --diff-filter=AM "$MERGE_BASE"...HEAD \
-            -- 'plugin-catalog/*.yaml' 'plugin-catalog/*.yml' \
-            | grep -v '/removed\.yaml$' || true)
-          echo "Changed catalog entries:"
-          echo "${CHANGED:-<none>}"
-          {
-            echo 'files<<__EOF__'
-            echo "$CHANGED"
-            echo '__EOF__'
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Install hermes-agent from the PR's own checkout
-        if: steps.changed.outputs.files != ''
-        uses: ./.github/actions/retry
-        with:
-          command: pip install -e .
-
-      - name: Clone each entry at its pinned sha and validate
-        if: steps.changed.outputs.files != ''
-        env:
-          CHANGED_FILES: ${{ steps.changed.outputs.files }}
-        run: |
-          set -euo pipefail
-          FAILED=0
-          while IFS= read -r entry; do
-            [ -z "$entry" ] && continue
-            echo "::group::validate $entry"
-
-            # Parse repo / sha / subdir from the entry yaml.
-            eval "$(python3 - "$entry" <<'PYEOF'
-          import shlex
-          import sys
-
-          import yaml
-
-          with open(sys.argv[1], encoding="utf-8") as fh:
-              data = yaml.safe_load(fh) or {}
-          print(f"REPO={shlex.quote(str(data.get('repo', '')))}")
-          print(f"SHA={shlex.quote(str(data.get('sha', '')))}")
-          print(f"SUBDIR={shlex.quote(str(data.get('subdir', '') or ''))}")
-          PYEOF
-          )"
-            echo "repo=$REPO sha=$SHA subdir=$SUBDIR"
-
-            CLONE_DIR=$(mktemp -d)
-            # Full clone (no --depth 1): the pinned sha may not be the branch tip.
-            if ! git clone "$REPO" "$CLONE_DIR"; then
-              echo "::error file=$entry::clone failed for $REPO"
-              FAILED=1; echo "::endgroup::"; continue
-            fi
-
-            # SUPPLY-CHAIN GATE: the pinned sha must be reachable in the repo.
-            if ! git -C "$CLONE_DIR" checkout --detach "$SHA"; then
-              echo "::error file=$entry::pinned sha $SHA is not reachable in $REPO"
-              FAILED=1; echo "::endgroup::"; continue
-            fi
-
-            PLUGIN_DIR="$CLONE_DIR${SUBDIR:+/$SUBDIR}"
-            if [ ! -f "$PLUGIN_DIR/plugin.yaml" ]; then
-              echo "::error file=$entry::no plugin.yaml at subdir '$SUBDIR' of $REPO@$SHA"
-              FAILED=1; echo "::endgroup::"; continue
-            fi
-
-            # Manifest schema + declared-vs-registered capability check.
-            if hermes plugins validate "$PLUGIN_DIR"; then
-              echo "✅ PASS: $entry"
-            else
-              echo "::error file=$entry::hermes plugins validate failed"
-              FAILED=1
-            fi
-            echo "::endgroup::"
-          done <<< "$CHANGED_FILES"
-
-          if [ "$FAILED" -ne 0 ]; then
-            echo "❌ FAIL: one or more catalog entries failed pinned-source validation"
-            exit 1
-          fi
-          echo "✅ PASS: all changed catalog entries validated at their pinned shas"
@@ -1,98 +0,0 @@
-name: Review labels
-
-# Require explicit maintainer review when CI-sensitive files or the MCP
-# catalog change. Previously this was split across two jobs in two
-# workflows: ``ci-review`` in lint.yml (gated on ``ci_review``) and
-# ``mcp-catalog-review`` in supply-chain-audit.yml (gated on
-# ``mcp_catalog``). Both checked for their own label.
-#
-# Now consolidated: a single ``ci-reviewed`` label covers both. The
-# comment sections tell the reviewer exactly what to verify per area,
-# so one label is enough — the human reads the comment, not the label
-# name.
-#
-# Outputs:
-#   ci_reviewed    — "true" / "false" / "" (empty when neither lane ran)
-#   review_status  — JSON array of status objects consumed by the review
-#                    comment assembler. See scripts/ci/emit_review_status.py.
-
-on:
-  workflow_call:
-    inputs:
-      ci_review:
-        description: Whether CI-sensitive files (eslint config, workflows, actions) changed.
-        type: boolean
-        default: false
-      mcp_catalog:
-        description: Whether the MCP catalog / installer changed.
-        type: boolean
-        default: false
-      supply_chain:
-        description: Whether the critical supply-chain scan found a risk requiring review.
-        type: boolean
-        default: false
-    outputs:
-      ci_reviewed:
-        description: Whether the ci-reviewed label is present. Empty when neither input was true.
-        value: ${{ jobs.check.outputs.ci_reviewed }}
-      review_status:
-        description: JSON array of status objects for the review comment assembler.
-        value: ${{ jobs.check.outputs.review_status }}
-
-permissions:
-  contents: read
-  pull-requests: read # read PR labels
-
-jobs:
-  check:
-    name: Review label gate
-    if: inputs.ci_review || inputs.mcp_catalog || inputs.supply_chain
-    runs-on: ubuntu-latest
-    timeout-minutes: 2
-    outputs:
-      ci_reviewed: ${{ steps.label-check.outputs.ci_reviewed }}
-      review_status: ${{ steps.build-status.outputs.review_status }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Check ci-reviewed label
-        id: label-check
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REPO: ${{ github.repository }}
-        run: |
-          set -euo pipefail
-          PR="${{ github.event.pull_request.number }}"
-          LABELS=$(gh pr view "$PR" --repo "$REPO" --json labels --jq '.labels[].name' || true)
-
-          if echo "$LABELS" | grep -Fxq 'ci-reviewed'; then
-            echo "ci-reviewed label present."
-            echo "ci_reviewed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "ci-reviewed label missing."
-            echo "ci_reviewed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Build review_status JSON
-        id: build-status
-        env:
-          CI_REVIEW: ${{ inputs.ci_review }}
-          MCP_CATALOG: ${{ inputs.mcp_catalog }}
-          SUPPLY_CHAIN: ${{ inputs.supply_chain }}
-          LABEL_PRESENT: ${{ steps.label-check.outputs.ci_reviewed }}
-        run: |
-          set -euo pipefail
-          args=()
-          if [ "$CI_REVIEW" = "true" ]; then args+=(--ci-review); fi
-          if [ "$MCP_CATALOG" = "true" ]; then args+=(--mcp-catalog); fi
-          if [ "$SUPPLY_CHAIN" = "true" ]; then args+=(--supply-chain); fi
-          if [ "$LABEL_PRESENT" = "true" ]; then args+=(--label-present); fi
-
-          python3 scripts/ci/emit_review_status.py "${args[@]}" --output "$GITHUB_OUTPUT"
-
-      - name: Fail on missing label
-        if: steps.label-check.outputs.ci_reviewed != 'true'
-        run: |
-          echo "::error::CI-sensitive changes require the ci-reviewed label. Add the label and re-run this check."
-          exit 1
@@ -1,158 +0,0 @@
-name: Skills Index Freshness Check
-
-# Belt-and-suspenders for the twice-daily build_skills_index pipeline.
-# If the live /docs/api/skills-index.json ever goes more than 26 hours
-# stale OR the file disappears entirely OR a major source has collapsed,
-# this workflow opens a GitHub issue so we hear about it before users do.
-#
-# Triggered every 4 hours so we catch a stuck cron within one tick.
-
-on:
-  schedule:
-    - cron: '0 */4 * * *'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  issues: write
-
-jobs:
-  check-freshness:
-    if: github.repository == 'NousResearch/hermes-agent'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Probe live index
-        id: probe
-        run: |
-          set -e
-          URL="https://hermes-agent.nousresearch.com/docs/api/skills-index.json"
-          echo "Probing $URL"
-          # -L follows redirects; -f fails on HTTP errors; -s suppresses progress
-          if ! curl -fsSL --retry 3 --retry-delay 10 -o /tmp/skills-index.json "$URL"; then
-            echo "status=fetch-failed" >> "$GITHUB_OUTPUT"
-            echo "detail=Could not download $URL" >> "$GITHUB_OUTPUT"
-            exit 0
-          fi
-          # Validate + extract generated_at and per-source counts
-          python3 <<'PY' >> "$GITHUB_OUTPUT"
-          import json, sys
-          from datetime import datetime, timezone
-
-          try:
-              with open("/tmp/skills-index.json") as f:
-                  data = json.load(f)
-          except Exception as e:
-              print(f"status=parse-failed")
-              print(f"detail=JSON decode error: {e}")
-              sys.exit(0)
-
-          generated_at = data.get("generated_at", "")
-          total = data.get("skill_count", 0)
-          skills = data.get("skills", [])
-          if not isinstance(skills, list):
-              print("status=invalid-shape")
-              print(f"detail=skills field is not a list (got {type(skills).__name__})")
-              sys.exit(0)
-
-          # Per-source counts
-          from collections import Counter
-          by_src = Counter(s.get("source", "") for s in skills)
-
-          # Freshness
-          age_hours = None
-          try:
-              ts = datetime.fromisoformat(generated_at.replace("Z", "+00:00"))
-              age_hours = (datetime.now(timezone.utc) - ts).total_seconds() / 3600
-          except Exception:
-              pass
-
-          # Floors — same as build_skills_index.py EXPECTED_FLOORS.
-          floors = {
-              "skills.sh": 100,
-              "lobehub": 100,
-              "clawhub": 50,
-              "official": 50,
-              "github": 30,
-              "browse-sh": 50,
-          }
-          issues = []
-          if age_hours is not None and age_hours > 26:
-              issues.append(f"Index is {age_hours:.1f}h old (limit 26h)")
-          for src, floor in floors.items():
-              count = by_src.get(src, 0)
-              if src == "skills.sh":
-                  count = by_src.get("skills.sh", 0) + by_src.get("skills-sh", 0)
-              if count < floor:
-                  issues.append(f"{src}: {count} < {floor}")
-          if total < 1500:
-              issues.append(f"total skills: {total} < 1500")
-
-          if issues:
-              detail = "; ".join(issues)
-              print("status=degraded")
-              # GITHUB_OUTPUT doesn't allow newlines without explicit delimiter
-              print(f"detail={detail}")
-          else:
-              print("status=ok")
-              print(f"detail=Index OK — {total} skills, generated {generated_at}")
-              by_summary = ", ".join(f"{k}={v}" for k, v in by_src.most_common(8))
-              print(f"summary={by_summary}")
-          PY
-
-      - name: Report status
-        run: |
-          echo "Probe status: ${{ steps.probe.outputs.status }}"
-          echo "Detail:       ${{ steps.probe.outputs.detail }}"
-          if [ -n "${{ steps.probe.outputs.summary }}" ]; then
-            echo "Summary:      ${{ steps.probe.outputs.summary }}"
-          fi
-
-      - name: Get GitHub App token
-        if: steps.probe.outputs.status != 'ok'
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - name: Open issue on degraded / failed probe
-        if: steps.probe.outputs.status != 'ok'
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          STATUS: ${{ steps.probe.outputs.status }}
-          DETAIL: ${{ steps.probe.outputs.detail }}
-        run: |
-          # Find existing open issue by title prefix so we don't spam — we
-          # append a comment instead of opening a new one each tick.
-          TITLE_PREFIX="[skills-index-watchdog]"
-          existing=$(gh issue list \
-            --repo "${{ github.repository }}" \
-            --state open \
-            --search "in:title \"$TITLE_PREFIX\"" \
-            --json number,title \
-            --jq '.[] | select(.title | startswith("'"$TITLE_PREFIX"'")) | .number' \
-            | head -1)
-          BODY="Automated freshness probe failed.
-
-          **Status:** \`$STATUS\`
-          **Detail:** $DETAIL
-
-          The Skills Hub at /docs/skills depends on \`/docs/api/skills-index.json\`.
-          The unified index is rebuilt by \`.github/workflows/skills-index.yml\` (cron 6/18 UTC)
-          and \`.github/workflows/deploy-site.yml\` (on every push affecting website/skills).
-          If this issue keeps reopening, check the latest runs:
-
-          - https://github.com/${{ github.repository }}/actions/workflows/skills-index.yml
-          - https://github.com/${{ github.repository }}/actions/workflows/deploy-site.yml
-
-          This issue was opened by \`.github/workflows/skills-index-freshness.yml\`. Close it once the underlying problem is fixed; the next probe will reopen if it's still broken."
-          if [ -n "$existing" ]; then
-            echo "Appending to existing issue #$existing"
-            gh issue comment "$existing" --repo "${{ github.repository }}" --body "Probe still failing at $(date -u +%FT%TZ): \`$STATUS\` — $DETAIL"
-          else
-            echo "Opening new watchdog issue"
-            gh issue create --repo "${{ github.repository }}" \
-              --title "$TITLE_PREFIX Skills index is stale or degraded ($STATUS)" \
-              --body "$BODY"
-          fi
@@ -1,73 +0,0 @@
-name: Build Skills Index
-
-on:
-  schedule:
-    # Run twice daily: 6 AM and 6 PM UTC
-    - cron: "0 6,18 * * *"
-  workflow_dispatch: # Manual trigger
-  push:
-    branches: [main]
-    paths:
-      - "scripts/build_skills_index.py"
-      - ".github/workflows/skills-index.yml"
-
-permissions:
-  contents: read
-  actions: write # to trigger deploy-site.yml on schedule
-
-jobs:
-  build-index:
-    # Only run on the upstream repository, not on forks
-    if: github.repository == 'NousResearch/hermes-agent'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.11"
-
-      - name: Install dependencies
-        uses: ./.github/actions/retry
-        with:
-          command: pip install httpx==0.28.1 pyyaml==6.0.2
-
-      - name: Build skills index
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: python scripts/build_skills_index.py
-
-      - name: Upload index artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: skills-index
-          path: website/static/api/skills-index.json
-          retention-days: 7
-
-  # Re-trigger the docs deploy so the refreshed index lands on the live site.
-  # The deploy itself is owned by deploy-site.yml (which crawls and deploys
-  # everything in one pipeline); we just kick it on a schedule.
-  trigger-deploy:
-    needs: build-index
-    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-      - name: Trigger Deploy Site workflow
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: gh workflow run deploy-site.yml --repo ${{ github.repository }} -f skills_index_run_id=${{ github.run_id }}
@@ -1,50 +1,8 @@
 name: Supply Chain Audit

-# Narrow, high-signal scanner. Only fires on critical indicators of supply
-# chain attacks (e.g. the litellm-style payloads). Low-signal heuristics
-# (plain base64, plain exec/eval, dependency/Dockerfile/workflow edits,
-# Actions version unpinning, outbound POST/PUT) were intentionally
-# removed — they fired on nearly every PR and trained reviewers to ignore
-# the scanner. Keep this file's checks ruthlessly narrow: if you find
-# yourself adding WARNING-tier patterns here again, make a separate
-# advisory-only workflow instead.
-#
-# Path-gating is handled centrally by the ``ci.yml`` orchestrator's
-# ``detect`` job. The orchestrator passes ``scan`` / ``deps`` booleans as
-# inputs; this workflow's jobs gate on those inputs instead of re-computing
-# the diff. MCP catalog review was previously here but has moved to
-# ``review-labels.yml`` so it can be rerun independently.
-#
-# Outputs:
-#   review_status      — JSON array of status objects consumed by the review
-#                         comment assembler (scripts/ci/assemble_review_comment.py).
-#   critical_findings  — "true" when the narrow critical-pattern scan found
-#                         something. The review-label gate consumes this and
-#                         owns the action-required result, so adding
-#                         ``ci-reviewed`` can heal the run on rerun.
-
 on:
-  workflow_call:
-    inputs:
-      event_name:
-        description: The event name from the calling orchestrator.
-        type: string
-        required: true
-      scan:
-        description: Whether supply-chain-relevant files changed.
-        type: boolean
-        required: true
-      deps:
-        description: Whether pyproject.toml changed.
-        type: boolean
-        required: true
-    outputs:
-      review_status:
-        description: JSON array of review status objects for the review comment assembler.
-        value: ${{ jobs.aggregate.outputs.review_status }}
-      critical_findings:
-        description: Whether the critical-pattern scan found a risk requiring maintainer review.
-        value: ${{ jobs.aggregate.outputs.critical_findings }}
+  pull_request:
+    types: [opened, synchronize, reopened]

 permissions:
  pull-requests: write
@@ -52,52 +10,37 @@ permissions:

 jobs:
  scan:
-    name: Scan PR for critical supply chain risks
-    if: inputs.scan
+    name: Scan PR for supply chain risks
    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    outputs:
-      review_status: ${{ steps.emit-status.outputs.review_status }}
-      critical_findings: ${{ steps.scan.outputs.found }}
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@v4
        with:
          fetch-depth: 0

-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - name: Scan diff for critical patterns
+      - name: Scan diff for suspicious patterns
        id: scan
        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail

          BASE="${{ github.event.pull_request.base.sha }}"
          HEAD="${{ github.event.pull_request.head.sha }}"

-          # Added lines only, excluding lockfiles.
-          # Three-point diff (base...head) diffs from the merge base to HEAD,
-          # so only changes introduced by this PR are included — not changes
-          # that landed on main after the PR branched off.
-          DIFF=$(git diff "$BASE"..."$HEAD" -- . ':!uv.lock' ':!*.lock' ':!package-lock.json' ':!yarn.lock' || true)
+          # Get the full diff (added lines only)
+          DIFF=$(git diff "$BASE".."$HEAD" -- . ':!uv.lock' ':!*.lock' ':!package-lock.json' ':!yarn.lock' || true)

          FINDINGS=""
+          CRITICAL=false

          # --- .pth files (auto-execute on Python startup) ---
-          # The exact mechanism used in the litellm supply chain attack:
-          # https://github.com/BerriAI/litellm/issues/24512
-          PTH_FILES=$(git diff --name-only "$BASE"..."$HEAD" | grep '\.pth$' || true)
+          PTH_FILES=$(git diff --name-only "$BASE".."$HEAD" | grep '\.pth$' || true)
          if [ -n "$PTH_FILES" ]; then
+            CRITICAL=true
            FINDINGS="${FINDINGS}
          ### 🚨 CRITICAL: .pth file added or modified
-          Python \`.pth\` files in \`site-packages/\` execute automatically when the interpreter starts — no import required.
+          Python \`.pth\` files in \`site-packages/\` execute automatically when the interpreter starts — no import required. This is the exact mechanism used in the [litellm supply chain attack](https://github.com/BerriAI/litellm/issues/24512).

          **Files:**
          \`\`\`
@@ -106,12 +49,13 @@ jobs:
          "
          fi

-          # --- base64 decode + exec/eval on the same line (the litellm attack pattern) ---
-          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
+          # --- base64 + exec/eval combo (the litellm attack pattern) ---
+          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
          if [ -n "$B64_EXEC_HITS" ]; then
+            CRITICAL=true
            FINDINGS="${FINDINGS}
          ### 🚨 CRITICAL: base64 decode + exec/eval combo
-          Base64-decoded strings passed directly to exec/eval — the signature of hidden credential-stealing payloads.
+          This is the exact pattern used in the [litellm supply chain attack](https://github.com/BerriAI/litellm/issues/24512) — base64-decoded strings passed to exec/eval to hide credential-stealing payloads.

          **Matches:**
          \`\`\`
@@ -120,12 +64,41 @@ jobs:
          "
          fi

-          # --- subprocess with encoded/obfuscated command argument ---
-          PROC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
+          # --- base64 decode/encode (alone — legitimate uses exist) ---
+          B64_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'base64\.(b64decode|b64encode|decodebytes|encodebytes|urlsafe_b64decode)|atob\(|btoa\(|Buffer\.from\(.*base64' | head -20 || true)
+          if [ -n "$B64_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: base64 encoding/decoding detected
+          Base64 has legitimate uses (images, JWT, etc.) but is also commonly used to obfuscate malicious payloads. Verify the usage is appropriate.
+
+          **Matches (first 20):**
+          \`\`\`
+          ${B64_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- exec/eval with string arguments ---
+          EXEC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -E '(exec|eval)\s*\(' | grep -v '^\+\s*#' | grep -v 'test_\|mock\|assert\|# ' | head -20 || true)
+          if [ -n "$EXEC_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: exec() or eval() usage
+          Dynamic code execution can hide malicious behavior, especially when combined with base64 or network fetches.
+
+          **Matches (first 20):**
+          \`\`\`
+          ${EXEC_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- subprocess with encoded/obfuscated commands ---
+          PROC_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|decode|encode|\\x|chr\(' | head -10 || true)
          if [ -n "$PROC_HITS" ]; then
+            CRITICAL=true
            FINDINGS="${FINDINGS}
          ### 🚨 CRITICAL: subprocess with encoded/obfuscated command
-          Subprocess calls whose command strings are base64- or hex-encoded are a strong indicator of payload execution.
+          Subprocess calls with encoded arguments are a strong indicator of payload execution.

          **Matches:**
          \`\`\`
@@ -134,17 +107,25 @@ jobs:
          "
          fi

-          # --- Install-hook files (setup.py/sitecustomize/usercustomize/__init__.pth) ---
-          # These execute during pip install or interpreter startup.
-          # Anchored at repo root: only the top-level setup.py/setup.cfg run during
-          # `pip install`, and only top-level sitecustomize.py/usercustomize.py are
-          # auto-loaded by the interpreter via site.py. Any nested file with the
-          # same name (e.g. hermes_cli/setup.py — the CLI setup wizard) is unrelated
-          # and produced false positives that trained reviewers to ignore the scanner.
-          SETUP_HITS=$(git diff --name-only "$BASE"..."$HEAD" | grep -E '^(setup\.py|setup\.cfg|sitecustomize\.py|usercustomize\.py|__init__\.pth)$' || true)
+          # --- Network calls to non-standard domains ---
+          EXFIL_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'requests\.(post|put)\(|httpx\.(post|put)\(|urllib\.request\.urlopen' | grep -v '^\+\s*#' | grep -v 'test_\|mock\|assert' | head -10 || true)
+          if [ -n "$EXFIL_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: Outbound network calls (POST/PUT)
+          Outbound POST/PUT requests in new code could be data exfiltration. Verify the destination URLs are legitimate.
+
+          **Matches (first 10):**
+          \`\`\`
+          ${EXFIL_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- setup.py / setup.cfg install hooks ---
+          SETUP_HITS=$(git diff --name-only "$BASE".."$HEAD" | grep -E '(setup\.py|setup\.cfg|__init__\.pth|sitecustomize\.py|usercustomize\.py)$' || true)
          if [ -n "$SETUP_HITS" ]; then
            FINDINGS="${FINDINGS}
-          ### 🚨 CRITICAL: Install-hook file added or modified
+          ### ⚠️ WARNING: Install hook files modified
          These files can execute code during package installation or interpreter startup.

          **Files:**
@@ -154,143 +135,58 @@ jobs:
          "
          fi

+          # --- Compile/marshal/pickle (code object injection) ---
+          MARSHAL_HITS=$(echo "$DIFF" | grep -n '^\+' | grep -iE 'marshal\.loads|pickle\.loads|compile\(' | grep -v '^\+\s*#' | grep -v 'test_\|re\.compile\|ast\.compile' | head -10 || true)
+          if [ -n "$MARSHAL_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### ⚠️ WARNING: marshal/pickle/compile usage
+          These can deserialize or construct executable code objects.
+
+          **Matches:**
+          \`\`\`
+          ${MARSHAL_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- Output results ---
          if [ -n "$FINDINGS" ]; then
            echo "found=true" >> "$GITHUB_OUTPUT"
+            if [ "$CRITICAL" = true ]; then
+              echo "critical=true" >> "$GITHUB_OUTPUT"
+            else
+              echo "critical=false" >> "$GITHUB_OUTPUT"
+            fi
+            # Write findings to a file (multiline env vars are fragile)
            echo "$FINDINGS" > /tmp/findings.md
          else
            echo "found=false" >> "$GITHUB_OUTPUT"
+            echo "critical=false" >> "$GITHUB_OUTPUT"
          fi

-      - name: Emit review_status
-        id: emit-status
-        if: always()
+      - name: Post warning comment
+        if: steps.scan.outputs.found == 'true'
        env:
-          FOUND: ${{ steps.scan.outputs.found }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
-          python3 - <<'PYEOF'
-          import json, os
-
-          # The review-label gate renders and blocks critical findings. Keep
-          # this scan a fact-finder so adding ci-reviewed can rerun the gate
-          # without requiring the scanner itself to fail again.
-          status = []
-
-          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
-              f.write(f"review_status={json.dumps(status)}\n")
-          PYEOF
-
-
-  dep-bounds:
-    name: Check PyPI dependency upper bounds
-    if: inputs.deps
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    outputs:
-      review_status: ${{ steps.emit-status.outputs.review_status }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          fetch-depth: 0
-
-      - name: Check for unbounded PyPI deps
-        id: bounds
-        run: |
-          set -euo pipefail
-
-          BASE="${{ github.event.pull_request.base.sha }}"
-          HEAD="${{ github.event.pull_request.head.sha }}"
-
-          # Only check added lines in pyproject.toml
-          ADDED=$(git diff "$BASE"..."$HEAD" -- pyproject.toml | grep '^+' | grep -v '^+++' || true)
-
-          if [ -z "$ADDED" ]; then
-            echo "found=false" >> "$GITHUB_OUTPUT"
-            exit 0
+          SEVERITY="⚠️ Supply Chain Risk Detected"
+          if [ "${{ steps.scan.outputs.critical }}" = "true" ]; then
+            SEVERITY="🚨 CRITICAL Supply Chain Risk Detected"
          fi

-          # Match PyPI dep specs that have >= and no < ceiling.
-          # Pattern: "package>=version" without a following ",<" bound.
-          # Excludes git+ URLs (which use commit SHAs) and comments.
-          UNBOUNDED=$(echo "$ADDED" | grep -oE '"[a-zA-Z0-9_-]+(\[[^\]]*\])?>=[ 0-9.]+"' | grep -v ',<' || true)
+          BODY="## ${SEVERITY}

-          if [ -n "$UNBOUNDED" ]; then
-            echo "found=true" >> "$GITHUB_OUTPUT"
-            echo "$UNBOUNDED" > /tmp/unbounded.txt
-          else
-            echo "found=false" >> "$GITHUB_OUTPUT"
-          fi
+          This PR contains patterns commonly associated with supply chain attacks. This does **not** mean the PR is malicious — but these patterns require careful human review before merging.

-      - name: Emit review_status
-        id: emit-status
-        if: always()
-        env:
-          FOUND: ${{ steps.bounds.outputs.found }}
+          $(cat /tmp/findings.md)
+
+          ---
+          *Automated scan triggered by [supply-chain-audit](/.github/workflows/supply-chain-audit.yml). If this is a false positive, a maintainer can approve after manual review.*"
+
+          gh pr comment "${{ github.event.pull_request.number }}" --body "$BODY"
+
+      - name: Fail on critical findings
+        if: steps.scan.outputs.critical == 'true'
        run: |
-          python3 - <<'PYEOF'
-          import json, os
-
-          found = os.environ.get("FOUND", "") == "true"
-
-          if found:
-              with open("/tmp/unbounded.txt", encoding="utf-8") as f:
-                  detail = f.read()
-              status = [{
-                  "source": "supply chain",
-                  "results": [{
-                      "kind": "action_required",
-                      "title": "Unbounded PyPI dependencies",
-                      "summary": "This PR adds PyPI dependencies without upper bounds.",
-                      "detail": detail,
-                      "how_to_fix": 'Add a `<next_major` upper bound, e.g. `"package>=1.2.0,<2"`. See CONTRIBUTING.md dependency pinning policy.'
-                  }]
-              }]
-          else:
-              status = []
-
-          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
-              f.write(f"review_status={json.dumps(status)}\n")
-          PYEOF
-
-      - name: Fail on unbounded deps
-        if: steps.bounds.outputs.found == 'true'
-        run: |
-          echo "::error::PyPI dependencies without upper bounds detected. Add <next_major ceiling per CONTRIBUTING.md policy."
+          echo "::error::CRITICAL supply chain risk patterns detected in this PR. See the PR comment for details."
          exit 1
-
-  aggregate:
-    name: Aggregate review statuses
-    needs: [scan, dep-bounds]
-    if: always()
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    outputs:
-      review_status: ${{ steps.merge.outputs.review_status }}
-      critical_findings: ${{ steps.merge.outputs.critical_findings }}
-    steps:
-      - name: Merge review statuses
-        id: merge
-        env:
-          SCAN_STATUS: ${{ needs.scan.outputs.review_status }}
-          DEP_STATUS: ${{ needs.dep-bounds.outputs.review_status }}
-          CRITICAL_FINDINGS: ${{ needs.scan.outputs.critical_findings }}
-        run: |
-          python3 - <<'PYEOF'
-          import json, os
-
-          merged = []
-          for key in ("SCAN_STATUS", "DEP_STATUS"):
-              raw = os.environ.get(key, "")
-              if not raw:
-                  continue
-              try:
-                  data = json.loads(raw)
-              except (json.JSONDecodeError, TypeError):
-                  continue
-              if isinstance(data, list):
-                  merged.extend(data)
-
-          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
-              f.write(f"review_status={json.dumps(merged)}\n")
-              f.write("critical_findings=" + os.environ.get("CRITICAL_FINDINGS", "false") + "\n")
-          PYEOF
@@ -1,230 +1,42 @@
 name: Tests

 on:
-  workflow_call:
-    inputs:
-      slice_count:
-        description: Number of parallel test slices
-        type: number
-        default: 8
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]

-permissions:
-  contents: read
-
-# Cancel in-progress runs for the same ref
+# Cancel in-progress runs for the same PR/branch
 concurrency:
  group: tests-${{ github.ref }}
  cancel-in-progress: true

 jobs:
-  generate:
-    name: "Generate slices"
+  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10
-    outputs:
-      matrix: ${{ steps.matrix.outputs.matrix }}
    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Restore duration cache
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: test_durations.json
-          key: test-durations
-          # Saves use test-durations-${run_id}, so the exact key above never
-          # matches — without this prefix fallback the cache ALWAYS missed,
-          # LPT slicing ran on no data, and unbalanced slices pushed heavy
-          # files toward the per-file timeout under load.
-          restore-keys: |
-            test-durations-
-
-      - name: Generate test slices
-        id: matrix
-        run: |
-          MATRIX=$(python3 scripts/run_tests_parallel.py --generate-slices ${{ inputs.slice_count }})
-          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
-
-  test:
-    name: Run tests slice ${{ matrix.slice.index }}/${{ inputs.slice_count }}
-    needs: generate
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix: ${{ fromJSON(needs.generate.outputs.matrix) }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install ripgrep (prebuilt binary)
-        run: |
-          set -euo pipefail
-          RG_VERSION=15.1.0
-          RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
-          RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
-            "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
-          echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
-          tar -xzf "$RG_TARBALL"
-          sudo mv "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl/rg" /usr/local/bin/rg
-          rm -rf "$RG_TARBALL" "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl"
-          rg --version
+        uses: actions/checkout@v4

      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-        with:
-          # Persist uv's download/wheel cache (~/.cache/uv) across runs.
-          # Keyed on the dependency manifests, so the cache is reused until
-          # pyproject.toml or uv.lock changes. `uv sync` still runs every
-          # time, but resolves from the warm cache instead of re-downloading
-          # and re-building wheels.
-          enable-cache: true
-          cache-dependency-glob: |
-            pyproject.toml
-            uv.lock
+        uses: astral-sh/setup-uv@v5

      - name: Set up Python 3.11
        run: uv python install 3.11

      - name: Install dependencies
-        # `uv sync --locked` installs the exact pinned set from uv.lock (and
-        # fails if the lock is out of sync with pyproject.toml), giving a
-        # reproducible env. It also creates .venv itself, so no separate
-        # `uv venv` step is needed.
-        uses: ./.github/actions/retry
-        with:
-          command: uv sync --locked --python 3.11 --extra all --extra dev
+        run: |
+          uv venv .venv --python 3.11
+          source .venv/bin/activate
+          uv pip install -e ".[all,dev]"

-      - name: Minimize uv cache
-        # Optimized for CI: prunes pre-built wheels that are cheap to
-        # re-download, keeping the persisted cache small and fast to restore.
-        run: uv cache prune --ci
-
-      - name: Run tests (slice ${{ matrix.slice.index }}/${{ inputs.slice_count }})
-        # Per-file isolation via scripts/run_tests.sh: each test file runs
-        # in its own freshly-spawned `python -m pytest <file>` subprocess
-        # with bounded parallelism. No xdist, no shared workers, no
-        # module-level state leakage between files.
-        #
-        # File list is pre-computed by the generate job (--generate-slices)
-        # which runs LPT distribution once and passes the file list to each
-        # matrix job via --files. Previously each job re-discovered files and
-        # re-ran LPT independently — redundant N times.
+      - name: Run tests
        run: |
          source .venv/bin/activate
-          scripts/run_tests.sh --files '${{ matrix.slice.files }}'
+          python -m pytest tests/ -q --ignore=tests/integration --tb=short -n auto
        env:
          # Ensure tests don't accidentally call real APIs
          OPENROUTER_API_KEY: ""
          OPENAI_API_KEY: ""
          NOUS_API_KEY: ""
-
-      - name: Upload per-slice durations
-        # Advisory artifact (feeds slice balancing) — a transient artifact-
-        # service blip must not fail an otherwise-green test slice.
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: test-durations-slice-${{ matrix.slice.index }}
-          path: test_durations.json
-          retention-days: 1
-
-  # Merge per-slice duration data into a single cache, so future runs
-  # (including PRs) get balanced slicing.
-  save-durations:
-    needs: test
-    if: needs.test.result == 'success' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Download all slice durations
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
-        with:
-          pattern: test-durations-slice-*
-          path: durations
-          merge-multiple: true
-
-      - name: Merge into single durations file
-        run: |
-          python3 -c "
-          import json, glob, os
-          merged = {}
-          for f in glob.glob('durations/*test_durations.json'):
-            with open(f) as fh:
-              merged.update(json.load(fh))
-          with open('test_durations.json', 'w') as fh:
-            json.dump(merged, fh, indent=2, sort_keys=True)
-          print(f'Merged {len(merged)} file durations')
-          "
-
-      - name: Save merged duration cache
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
-        with:
-          path: test_durations.json
-          key: test-durations-${{ github.run_id }}
-
-  e2e:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install ripgrep (prebuilt binary)
-        run: |
-          set -euo pipefail
-          RG_VERSION=15.1.0
-          RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
-          RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
-          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
-            "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
-          echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
-          tar -xzf "$RG_TARBALL"
-          sudo mv "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl/rg" /usr/local/bin/rg
-          rm -rf "$RG_TARBALL" "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl"
-          rg --version
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-        with:
-          # Persist uv's download/wheel cache (~/.cache/uv) across runs.
-          # Keyed on the dependency manifests, so the cache is reused until
-          # pyproject.toml or uv.lock changes. `uv sync` still runs every
-          # time, but resolves from the warm cache instead of re-downloading
-          # and re-building wheels.
-          enable-cache: true
-          cache-dependency-glob: |
-            pyproject.toml
-            uv.lock
-
-      - name: Set up Python 3.11
-        run: uv python install 3.11
-
-      - name: Install dependencies
-        # `uv sync --locked` installs the exact pinned set from uv.lock (and
-        # fails if the lock is out of sync with pyproject.toml), giving a
-        # reproducible env. It also creates .venv itself, so no separate
-        # `uv venv` step is needed.
-        uses: ./.github/actions/retry
-        with:
-          command: uv sync --locked --python 3.11 --extra all --extra dev
-
-      - name: Minimize uv cache
-        # Optimized for CI: prunes pre-built wheels that are cheap to
-        # re-download, keeping the persisted cache small and fast to restore.
-        run: uv cache prune --ci
-
-      - name: Packaged-wheel i18n smoke test
-        run: |
-          source .venv/bin/activate
-          python -m pytest -m integration tests/test_wheel_locales_e2e.py -v
-
-      - name: Run e2e tests
-        run: |
-          source .venv/bin/activate
-          python -m pytest tests/e2e/ -v --tb=short
-        env:
-          OPENROUTER_API_KEY: ""
-          OPENAI_API_KEY: ""
-          NOUS_API_KEY: ""
@@ -1,188 +0,0 @@
-name: Publish to PyPI
-
-# Triggered by CalVer tag pushes from scripts/release.py (e.g. v2026.5.15)
-# Can also be triggered manually from the Actions tab as an escape hatch.
-on:
-  push:
-    tags:
-      - "v20*" # CalVer tags: v2026.5.15, v2026.5.15.2, etc.
-  workflow_dispatch:
-    inputs:
-      confirm_tag:
-        description: "Tag to publish (e.g. v2026.5.15). Must already exist."
-        required: true
-        type: string
-
-# Restrict default token to read-only; each job escalates as needed.
-permissions:
-  contents: read
-
-# Prevent overlapping publishes (e.g. two same-day tags pushed quickly).
-concurrency:
-  group: pypi-publish
-  cancel-in-progress: false
-
-jobs:
-  build:
-    name: Build distribution 📦
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-        with:
-          persist-credentials: false
-          # On workflow_dispatch, check out the confirmed tag.
-          ref: ${{ inputs.confirm_tag || github.ref }}
-          fetch-tags: true
-
-      - name: Validate tag exists
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          if ! git tag -l "${{ inputs.confirm_tag }}" | grep -q .; then
-            echo "::error::Tag '${{ inputs.confirm_tag }}' does not exist in the repo"
-            exit 1
-          fi
-
-      - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
-        with:
-          python-version: "3.13"
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-
-      - name: Set up Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
-        with:
-          node-version: "22"
-
-      - name: Build web dashboard
-        uses: ./.github/actions/retry
-        with:
-          command: npm ci
-          working-directory: web
-
-      - name: Compile web dashboard
-        run: npm run build
-        working-directory: web
-
-      - name: Build TUI bundle
-        uses: ./.github/actions/retry
-        with:
-          command: npm ci
-          working-directory: ui-tui
-
-      - name: Compile TUI bundle
-        run: npm run build
-        working-directory: ui-tui
-
-      - name: Bundle TUI into hermes_cli
-        run: |
-          mkdir -p hermes_cli/tui_dist
-          cp ui-tui/dist/entry.js hermes_cli/tui_dist/entry.js
-
-      - name: Verify frontend assets exist
-        run: |
-          test -f hermes_cli/web_dist/index.html || { echo "ERROR: web_dist not built"; exit 1; }
-          test -f hermes_cli/tui_dist/entry.js || { echo "ERROR: tui_dist not built"; exit 1; }
-
-      - name: Bundle install scripts into wheel
-        run: |
-          mkdir -p hermes_cli/scripts
-          cp scripts/install.sh hermes_cli/scripts/install.sh
-          cp scripts/install.ps1 hermes_cli/scripts/install.ps1
-
-      - name: Build wheel and sdist
-        run: uv build --sdist --wheel
-
-      - name: Upload distribution artifacts
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: python-package-distributions
-          path: dist/
-
-  publish:
-    name: Publish to PyPI
-    needs: build
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    environment:
-      name: pypi
-      url: https://pypi.org/p/hermes-agent
-    permissions:
-      id-token: write # OIDC trusted publishing
-
-    steps:
-      - name: Download distribution artifacts
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: python-package-distributions
-          path: dist/
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
-        with:
-          skip-existing: true
-
-  sign:
-    name: Sign and attach to GitHub Release
-    # Only runs on tag pushes — release.py creates the GitHub Release,
-    # and workflow_dispatch won't have a matching release to attach to.
-    if: startsWith(github.ref, 'refs/tags/')
-    needs: publish
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    permissions:
-      contents: write # attach assets to the existing release
-      id-token: write # sigstore signing
-
-    steps:
-      - name: Download distribution artifacts
-        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
-        with:
-          name: python-package-distributions
-          path: dist/
-
-      - name: Get GitHub App token
-        id: app-token
-        uses: ./.github/actions/get-app-token
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-
-      - name: Wait for GitHub Release to exist
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-        # release.py creates the GitHub Release after pushing the tag,
-        # but this workflow starts from the tag push — wait for it.
-        run: |
-          for i in $(seq 1 30); do
-            if gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-              echo "Release $GITHUB_REF_NAME found"
-              exit 0
-            fi
-            echo "Waiting for release... ($i/30)"
-            sleep 10
-          done
-          echo "::warning::Release $GITHUB_REF_NAME not found after 5 minutes — skipping signature upload"
-          echo "skip_sign=true" >> "$GITHUB_ENV"
-
-      - name: Sign with Sigstore
-        if: env.skip_sign != 'true'
-        uses: sigstore/gh-action-sigstore-python@04cffa1d795717b140764e8b640de88853c92acc # v3.3.0
-        with:
-          inputs: >-
-            ./dist/*.tar.gz
-            ./dist/*.whl
-
-      - name: Attach signed artifacts to GitHub Release
-        if: env.skip_sign != 'true'
-        env:
-          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
-        # release.py already created the GitHub Release — just upload
-        # the Sigstore signatures alongside the existing assets.
-        run: >-
-          gh release upload
-          "$GITHUB_REF_NAME" dist/*.sigstore.json
-          --repo "$GITHUB_REPOSITORY"
-          --clobber
@@ -1,132 +0,0 @@
-name: uv.lock check
-
-# Verify uv.lock is in sync with pyproject.toml.  Blocking check — PRs
-# that modify pyproject.toml without regenerating uv.lock (or vice versa)
-# must not merge, because the Docker build's `uv sync --frozen` step will
-# fail on a stale lockfile and we'd rather catch it here than in the
-# docker workflow on main.
-#
-# ─────────────────────────────────────────────────────────────────────────
-# IMPORTANT: this check runs against the MERGED state, not just your branch
-# ─────────────────────────────────────────────────────────────────────────
-#
-# For `pull_request` events, GitHub checks out `refs/pull/<N>/merge` by
-# default — a synthetic commit that merges your PR branch into the CURRENT
-# state of `main`.  That means the pyproject.toml evaluated here is
-# `main's pyproject.toml + your PR's changes to pyproject.toml`, not just
-# what's on your branch.
-#
-# Failure mode this creates: if `main` has advanced since you branched
-# (e.g. someone merged a PR that added a dep to pyproject.toml + its
-# corresponding uv.lock entries), your branch's uv.lock is missing those
-# new entries.  `uv lock --check` resolves against the merged pyproject
-# and sees a lockfile that doesn't cover all the current deps → fails
-# with "The lockfile at uv.lock needs to be updated."
-#
-# This can be confusing: `uv lock --check` passes locally (your branch
-# is internally consistent) but fails in CI (merged state isn't).
-#
-# Fix is to sync your branch with main and regenerate the lockfile:
-#
-#     git fetch origin main
-#     git rebase origin/main      # or merge, whatever the repo prefers
-#     uv lock                     # regenerates uv.lock against new pyproject.toml
-#     git add uv.lock
-#     git commit -m "chore: refresh uv.lock after rebase onto main"
-#     git push --force-with-lease # if you rebased
-#
-# If you also changed pyproject.toml in your PR, `uv lock` handles that
-# at the same time — one regeneration covers both your changes and the
-# drift from main.
-#
-# This is the correct behavior!  The check is protecting main's Docker
-# build: a post-merge build would see the same merged state and fail
-# the same way.  Better to catch it here than after merge.
-
-on:
-  workflow_call:
-    outputs:
-      review_status:
-        description: "JSON review status for the review-status aggregator"
-        value: ${{ jobs.check.outputs.review_status }}
-
-permissions:
-  contents: read
-
-concurrency:
-  group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  check:
-    name: uv lock --check
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    outputs:
-      review_status: ${{ steps.verify.outputs.review_status }}
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
-
-      # `uv lock --check` re-resolves the project from pyproject.toml and
-      # compares the result to uv.lock, exiting non-zero if they disagree.
-      # No network writes, no file modifications.
-      #
-      # On PRs this runs against the merge commit (see comment at the top
-      # of this file) — failures often mean "your branch is behind main,
-      # rebase and regenerate uv.lock."
-      - name: Verify uv.lock is up-to-date
-        id: verify
-        run: |
-          # uv lock --check re-resolves against PyPI (network). Retry so a
-          # registry blip doesn't read as "lockfile stale". A genuinely stale
-          # lockfile fails all attempts (deterministic), costing only seconds.
-          ok=false
-          for i in 1 2 3; do
-            if uv lock --check; then
-              ok=true
-              break
-            fi
-            [ "$i" = 3 ] && break
-            echo "::warning::uv lock --check failed (attempt $i); retrying in 10s"
-            sleep 10
-          done
-          if [ "$ok" != true ]; then
-            cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
-          ## ❌ uv.lock is out of sync with pyproject.toml
-
-          **If this is a PR:** this check runs against the merged state
-          (your branch + current `main`), not just your branch.  If
-          `uv lock --check` passes locally, your branch is likely behind
-          `main` — recent changes to `pyproject.toml` on `main` aren't
-          reflected in your branch's `uv.lock` yet.
-
-          To fix, sync with main and regenerate the lockfile:
-
-          ```bash
-          git fetch origin main
-          git rebase origin/main   # or `git merge origin/main`
-          uv lock                  # regenerate against new pyproject.toml
-          git add uv.lock
-          git commit -m "chore: refresh uv.lock after syncing with main"
-          git push --force-with-lease  # drop --force-with-lease if you merged
-          ```
-
-          **If you only changed pyproject.toml:** run `uv lock` locally
-          and commit the result.
-
-          This check is blocking because the Docker image build uses
-          `uv sync --frozen --extra all`, which rejects stale lockfiles
-          — catching it here avoids a ~15 min failed docker run
-          on `main` post-merge.
-          EOF
-            echo "::error title=uv.lock out of sync::Run \`uv lock\` locally and commit the result. If on a PR, sync with main first."
-            review_status='[{"source":"uv.lock check","results":[{"kind":"action_required","title":"uv.lock out of sync","summary":"uv.lock is out of sync with pyproject.toml.","how_to_fix":"Run `uv lock` locally and commit the result. If on a PR, sync with main first:\n```\ngit fetch origin main\ngit rebase origin/main\nuv lock\ngit add uv.lock\ngit commit -m \"chore: refresh uv.lock\"\n```\n"}]}]'
-            echo "review_status=${review_status}" >> "$GITHUB_OUTPUT"
-            exit 1
-          fi
-          review_status='[]'
-          echo "review_status=${review_status}" >> "$GITHUB_OUTPUT"
@@ -1,37 +1,22 @@
-.DS_Store
 /venv/
-/venv.old/
 /_pycache/
 *.pyc*
 __pycache__/
-act/
-.act-sandbox-agent.*
 .venv/
-.venv
 .vscode/
 .env
-.op.env
 .env.local
 .env.development.local
 .env.test.local
 .env.production.local
 .env.development
 .env.test
-.hermes-docker/
-.notebooklm-home/
-.notebooklm-cli-venv/
-.notebooklm-playwright/
-.pip-cache/
-.uv-cache/
-compose.hermes.local.yml
 export*
 __pycache__/model_tools.cpython-310.pyc
 __pycache__/web_tools.cpython-310.pyc
 logs/
 data/
 .pytest_cache/
-test_durations.json
-.pytest-cache/
 tmp/
 temp_vision_images/
 hermes-*/*
@@ -44,10 +29,7 @@ run_datagen_sonnet.sh
 source-data/*
 run_datagen_megascience_glm4-6.sh
 data/*
-# No trailing slash: also matches node_modules SYMLINKS (worktrees often
-# symlink node_modules to the main checkout; the dir-only pattern let one
-# slip into a commit and break `npm ci` on CI with ENOTDIR).
-node_modules
+node_modules/
 browser-use/
 agent-browser/
 # Private keys
@@ -59,10 +41,6 @@ __pycache__/
 hermes_agent.egg-info/
 wandb/
 testlogs
-playwright-report/
-test-results/
-# Playwright visual regression baselines — cached from main in CI, not committed
-*-snapshots/

 # CLI config (may contain sensitive SSH paths)
 cli-config.yaml
@@ -73,104 +51,10 @@ ignored/
 .worktrees/
 environments/benchmarks/evals/

-# Web UI build output
-hermes_cli/web_dist/
-# Cross-process web UI build lock (flock target, always empty)
-.web_ui_build.lock
-apps/desktop/build/
-apps/desktop/dist/
-
-# tsc-emitted artifacts (a stray `tsc -b` compiles into src/, and vite then
-# resolves the stale .js OVER the .tsx — never track these)
-apps/desktop/src/**/*.js
-apps/desktop/src/**/*.js.map
-apps/desktop/src/**/*.d.ts
-!apps/desktop/src/global.d.ts
-!apps/desktop/src/vite-env.d.ts
-apps/shared/src/**/*.js
-apps/shared/src/**/*.js.map
-apps/shared/src/**/*.d.ts
-apps/desktop/release/
-*.tsbuildinfo
-
-# Web UI assets — synced from @nous-research/ui at build time via
-# `npm run sync-assets` (see web/package.json).
-web/public/fonts/
-web/public/ds-assets/
-
 # Release script temp files
 .release_notes.md
 mini-swe-agent/

 # Nix
 .direnv/
-.nix-stamps/
 result
-website/static/api/skills-index.json
-# skills.json + skills-meta.json are build artifacts emitted by
-# website/scripts/extract-skills.py during prebuild — keep them out of
-# git for the same reason as skills-index.json (large, generated, change
-# every build).
-website/static/api/skills.json
-website/static/api/skills-meta.json
-# plugins.json + plugins-meta.json are build artifacts emitted by
-# website/scripts/extract-plugins.py during prebuild (Plugin Catalog page).
-website/static/api/plugins.json
-website/static/api/plugins-meta.json
-# automation-blueprints-index.json is a build artifact emitted by
-# website/scripts/extract-automation-blueprints.py during prebuild.
-website/static/api/automation-blueprints-index.json
-models-dev-upstream/
-
-# Local editor / agent tooling (machine-specific; keep in global config, not the repo)
-.codex/
-.cursor/
-.gemini/
-.zed/
-.mcp.json
-opencode.json
-config/mcporter.json
-
-hermes_cli/tui_dist/*
-hermes_cli/scripts/
-docs/superpowers/*
-# Working directory for the Hermes Agent's session state (~/.hermes/ at runtime;
-# also created in-repo when an agent operates in this checkout). Plans, audit
-# logs, and per-session caches are never artifacts of the codebase.
-.hermes/
-
-# Desktop/bootstrap install marker written into the managed checkout root by the
-# bootstrap installer. It is Hermes-managed runtime state, never a code change —
-# ignore it so `hermes update`'s `git stash push --include-untracked` does not
-# treat it as a local edit and autostash it on every run (#38529).
-.hermes-bootstrap-complete
-
-# Persistent dev sandbox dir (scripts/dev-sandbox.sh --persistent)
-.hermes-sandbox/
-
-# Interrupted-update breadcrumb + recovery lock written next to the shared venv
-# by `hermes update` / launch-time self-heal. Runtime state, never a code change
-# — ignore so `git status` stays clean and update's autostash skips them.
-.update-incomplete
-.update-incomplete.lock
-
-# Tool Search live-test harness output — non-deterministic model transcripts,
-# regenerated by scripts/tool_search_livetest.py. Never an artifact of the repo.
-scripts/out/
-
-# Per-release changelog drafts. These exist only transiently during a release
-# cut (passed to `gh release create --notes-file`); the GitHub Release itself
-# stores the published notes. They are not a build artifact and must never be
-# committed to the repo root. See the hermes-release skill.
-RELEASE_v*.md
-
-# Desktop demo-run scratch output (hermes writes demo/*.txt during recorded
-# walkthroughs). Throwaway artifacts, never part of the app.
-apps/desktop/demo/
-
-# PR infographics are rendered locally and embedded in PR descriptions via the
-# image-provider (fal.media) URL — they are NEVER committed to the repo. The
-# PR body is the archive. See the hermes-agent-dev skill's
-# pr-infographic-workflow reference (storage rule + lapse #8 / #COMMIT-1).
-infographic/
-native/fts5_cjk/*.so
@@ -0,0 +1,3 @@
+[submodule "tinker-atropos"]
+	path = tinker-atropos
+	url = https://github.com/nousresearch/tinker-atropos
@@ -1,36 +0,0 @@
-# hadolint configuration for the Hermes Agent Dockerfile.
-# See https://github.com/hadolint/hadolint#configure for rules.
-#
-# We want hadolint to surface NEW Dockerfile lint regressions, but we
-# don't want to rewrite the existing image to silence rules that are
-# either intentional or pragmatic tradeoffs for this project. Each
-# ignore below has a one-line justification.
-failure-threshold: warning
-
-ignored:
-  # Pin versions in apt get install. We intentionally don't pin common
-  # tools (curl, git, openssh-client, etc.) — security updates flow in
-  # via the periodic base-image rebuild, and pinning would lock us to
-  # superseded patch releases. Same rationale as nearly every distro-
-  # base official image (python, node, debian).
-  - DL3008
-  # Use WORKDIR to switch to a directory. The image uses `(cd web && …)`
-  # / `(cd ../ui-tui && …)` inline subshells for one-off build steps
-  # because they don't affect later RUN commands; promoting them to
-  # full WORKDIR switches with restores would obscure intent.
-  - DL3003
-  # Multiple consecutive RUN instructions. The `touch README.md` + `uv
-  # sync` split is intentional — `touch` is cheap, `uv sync` is the
-  # expensive layer-cached step we want isolated, and merging them
-  # would invalidate the cache for trivial changes.
-  - DL3059
-  # Last USER should not be root. /init (s6-overlay) runs as root so the
-  # stage2 hook can usermod/groupmod and chown the data volume per
-  # HERMES_UID at runtime; each supervised service then drops to the
-  # hermes user via `s6-setuidgid`.
-  - DL3002
-
-# Require explicit base-image pins (SHA256) — we already do this.
-trustedRegistries:
-  - docker.io
-  - ghcr.io
@@ -1,108 +0,0 @@
-# .mailmap — canonical author mapping for git shortlog / git log / GitHub
-# Format: Canonical Name <canonical@email> <commit@email>
-# See: https://git-scm.com/docs/gitmailmap
-#
-# This maps commit emails to GitHub noreply addresses so that:
-# 1. `git shortlog -sn` shows deduplicated contributor counts
-# 2. GitHub's contributor graph can attribute commits correctly
-# 3. Contributors with personal/work emails get proper credit
-#
-# When adding entries: use the contributor's GitHub noreply email as canonical
-# so GitHub can link commits to their profile.
-
-# === Teknium (multiple emails) ===
-Teknium <127238744+teknium1@users.noreply.github.com> <teknium1@gmail.com>
-Teknium <127238744+teknium1@users.noreply.github.com> <teknium@nousresearch.com>
-
-# === Contributors — personal/work emails mapped to GitHub noreply ===
-# Format: Canonical Name <GH-noreply> <commit-email>
-
-# Verified via GH API email search
-luyao618 <364939526@qq.com> <364939526@qq.com>
-ethernet8023 <arilotter@gmail.com> <arilotter@gmail.com>
-nicoloboschi <boschi1997@gmail.com> <boschi1997@gmail.com>
-cherifya <chef.ya@gmail.com> <chef.ya@gmail.com>
-BongSuCHOI <chlqhdtn98@gmail.com> <chlqhdtn98@gmail.com>
-dsocolobsky <dsocolobsky@gmail.com> <dsocolobsky@gmail.com>
-pefontana <fontana.pedro93@gmail.com> <fontana.pedro93@gmail.com>
-Helmi <frank@helmschrott.de> <frank@helmschrott.de>
-hata1234 <hata1234@gmail.com> <hata1234@gmail.com>
-
-# Verified via PR investigation / salvage PR bodies
-DeployFaith <agents@kylefrench.dev> <agents@kylefrench.dev>
-flobo3 <floptopbot33@gmail.com> <floptopbot33@gmail.com>
-gaixianggeng <gaixg94@gmail.com> <gaixg94@gmail.com>
-KUSH42 <xush@xush.org> <xush@xush.org>
-konsisumer <der@konsi.org> <der@konsi.org>
-WorldInnovationsDepartment <vorvul.danylo@gmail.com> <vorvul.danylo@gmail.com>
-m0n5t3r <iacobs@m0n5t3r.info> <iacobs@m0n5t3r.info>
-sprmn24 <oncuevtv@gmail.com> <oncuevtv@gmail.com>
-fancydirty <fancydirty@gmail.com> <fancydirty@gmail.com>
-fxfitz <francis.x.fitzpatrick@gmail.com> <francis.x.fitzpatrick@gmail.com>
-limars874 <limars874@gmail.com> <limars874@gmail.com>
-AaronWong1999 <aaronwong1999@icloud.com> <aaronwong1999@icloud.com>
-dippwho <dipp.who@gmail.com> <dipp.who@gmail.com>
-duerzy <duerzy@gmail.com> <duerzy@gmail.com>
-geoffwellman <geoff.wellman@gmail.com> <geoff.wellman@gmail.com>
-hcshen0111 <shenhaocheng19990111@gmail.com> <shenhaocheng19990111@gmail.com>
-jamesarch <han.shan@live.cn> <han.shan@live.cn>
-stephenschoettler <stephenschoettler@gmail.com> <stephenschoettler@gmail.com>
-Tranquil-Flow <tranquil_flow@protonmail.com> <tranquil_flow@protonmail.com>
-Dusk1e <yusufalweshdemir@gmail.com> <yusufalweshdemir@gmail.com>
-Awsh1 <ysfalweshcan@gmail.com> <ysfalweshcan@gmail.com>
-WAXLYY <ysfwaxlycan@gmail.com> <ysfwaxlycan@gmail.com>
-donrhmexe <don.rhm@gmail.com> <don.rhm@gmail.com>
-hqhq1025 <1506751656@qq.com> <1506751656@qq.com>
-BlackishGreen33 <s5460703@gmail.com> <s5460703@gmail.com>
-tomqiaozc <zqiao@microsoft.com> <zqiao@microsoft.com>
-MagicRay1217 <mingjwan@microsoft.com> <mingjwan@microsoft.com>
-aaronagent <1115117931@qq.com> <1115117931@qq.com>
-YoungYang963 <young@YoungdeMacBook-Pro.local> <young@YoungdeMacBook-Pro.local>
-LongOddCode <haolong@microsoft.com> <haolong@microsoft.com>
-Cafexss <coffeemjj@gmail.com> <coffeemjj@gmail.com>
-Cygra <sjtuwbh@gmail.com> <sjtuwbh@gmail.com>
-DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
-
-# Duplicate email mapping (same person, multiple emails)
-Sertug17 <104278804+Sertug17@users.noreply.github.com> <srhtsrht17@gmail.com>
-yyovil <birdiegyal@gmail.com> <tanishq231003@gmail.com>
-DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
-dsocolobsky <dsocolobsky@gmail.com> <dylan.socolobsky@lambdaclass.com>
-olafthiele <programming@olafthiele.com> <olafthiele@gmail.com>
-
-# Verified via git display name matching GH contributor username
-cokemine <aptx4561@gmail.com> <aptx4561@gmail.com>
-dalianmao000 <dalianmao0107@gmail.com> <dalianmao0107@gmail.com>
-emozilla <emozilla@nousresearch.com> <emozilla@nousresearch.com>
-jjovalle99 <juan.ovalle@mistral.ai> <juan.ovalle@mistral.ai>
-kagura-agent <kagura.chen28@gmail.com> <kagura.chen28@gmail.com>
-spniyant <niyant@spicefi.xyz> <niyant@spicefi.xyz>
-olafthiele <programming@olafthiele.com> <programming@olafthiele.com>
-r266-tech <r2668940489@gmail.com> <r2668940489@gmail.com>
-xingkongliang <tianliangjay@gmail.com> <tianliangjay@gmail.com>
-win4r <win4r@outlook.com> <win4r@outlook.com>
-zhouboli <zhouboli@gmail.com> <zhouboli@gmail.com>
-yongtenglei <yongtenglei@gmail.com> <yongtenglei@gmail.com>
-
-# Nous Research team
-benbarclay <ben@nousresearch.com> <ben@nousresearch.com>
-jquesnelle <jonny@nousresearch.com> <jonny@nousresearch.com>
-
-# GH contributor list verified
-spideystreet <dhicham.pro@gmail.com> <dhicham.pro@gmail.com>
-dorukardahan <dorukardahan@hotmail.com> <dorukardahan@hotmail.com>
-MustafaKara7 <karamusti912@gmail.com> <karamusti912@gmail.com>
-Hmbown <hmbown@gmail.com> <hmbown@gmail.com>
-kamil-gwozdz <kamil@gwozdz.me> <kamil@gwozdz.me>
-kira-ariaki <kira@ariaki.me> <kira@ariaki.me>
-knopki <knopki@duck.com> <knopki@duck.com>
-Unayung <unayung@gmail.com> <unayung@gmail.com>
-SeeYangZhi <yangzhi.see@gmail.com> <yangzhi.see@gmail.com>
-Julientalbot <julien.talbot@ergonomia.re> <julien.talbot@ergonomia.re>
-lesterli <lisicheng168@gmail.com> <lisicheng168@gmail.com>
-JiayuuWang <jiayuw794@gmail.com> <jiayuw794@gmail.com>
-tesseracttars-creator <tesseracttars@gmail.com> <tesseracttars@gmail.com>
-xinbenlv <zzn+pa@zzn.im> <zzn+pa@zzn.im>
-SaulJWu <saul.jj.wu@gmail.com> <saul.jj.wu@gmail.com>
-angelos <angelos@oikos.lan.home.malaiwah.com> <angelos@oikos.lan.home.malaiwah.com>
-MestreY0d4-Uninter <241404605+MestreY0d4-Uninter@users.noreply.github.com> <MestreY0d4-Uninter@users.noreply.github.com>
@@ -1,4 +0,0 @@
-# Lockfiles must never be reformatted — main has a repo rule requiring
-# team approval when lockfiles change, so an autofix PR touching one
-# would hang waiting for review.
-package-lock.json
@@ -1,11 +0,0 @@
-{
-  "arrowParens": "avoid",
-  "bracketSpacing": true,
-  "endOfLine": "auto",
-  "printWidth": 120,
-  "semi": false,
-  "singleQuote": true,
-  "tabWidth": 2,
-  "trailingComma": "none",
-  "useTabs": false
-}
@@ -1,602 +0,0 @@
-# Contribuir a Hermes Agent
-
-¡Gracias por contribuir a Hermes Agent! Esta guía cubre todo lo que necesitas: configurar tu entorno de desarrollo, entender la arquitectura, decidir qué construir y conseguir que tu PR sea aceptado.
-
---
-
-## Prioridades de Contribución
-
-Valoramos las contribuciones en este orden:
-
-1. **Correcciones de errores** — bloqueos, comportamiento incorrecto, pérdida de datos. Siempre la máxima prioridad.
-2. **Compatibilidad entre plataformas** — macOS, diferentes distribuciones de Linux y WSL2 en Windows. Queremos que Hermes funcione en todas partes.
-3. **Fortalecimiento de seguridad** — inyección de shell, inyección de prompts, traversal de rutas, escalada de privilegios. Ver [Consideraciones de Seguridad](#consideraciones-de-seguridad).
-4. **Rendimiento y robustez** — lógica de reintento, manejo de errores, degradación elegante.
-5. **Nuevas habilidades** — pero solo las ampliamente útiles. Ver [¿Debería ser una Habilidad o una Herramienta?](#debería-ser-una-habilidad-o-una-herramienta)
-6. **Nuevas herramientas** — raramente necesarias. La mayoría de las capacidades deberían ser habilidades. Ver más abajo.
-7. **Documentación** — correcciones, aclaraciones, nuevos ejemplos.
-
---
-
-## ¿Debería ser una Habilidad o una Herramienta?
-
-Esta es la pregunta más común para los nuevos colaboradores. La respuesta casi siempre es **habilidad**.
-
-### Hazlo una Habilidad cuando:
-
- La capacidad se puede expresar como instrucciones + comandos de shell + herramientas existentes
- Envuelve una CLI externa o API que el agente puede llamar a través de `terminal` o `web_extract`
- No necesita integración personalizada de Python ni gestión de claves API integrada en el agente
- Ejemplos: búsqueda en arXiv, flujos de trabajo de git, gestión de Docker, procesamiento de PDF, email a través de herramientas CLI
-
-### Hazlo una Herramienta cuando:
-
- Requiere integración de extremo a extremo con claves API, flujos de autenticación o configuración de múltiples componentes gestionada por el harness del agente
- Necesita lógica de procesamiento personalizada que debe ejecutarse con precisión en cada ocasión (no "mejor esfuerzo" de la interpretación del LLM)
- Maneja datos binarios, streaming o eventos en tiempo real que no pueden pasar por el terminal
- Ejemplos: automatización de navegador (gestión de sesiones Browserbase), TTS (codificación de audio + entrega en plataforma), análisis de visión (manejo de imágenes base64)
-
-### ¿Debería la Habilidad estar incluida?
-
-Las habilidades incluidas (en `skills/`) se envían con cada instalación de Hermes. Deben ser **ampliamente útiles para la mayoría de los usuarios**:
-
- Manejo de documentos, investigación web, flujos de trabajo de desarrollo comunes, administración de sistemas
- Usadas regularmente por una amplia gama de personas
-
-Si tu habilidad es oficial y útil pero no universalmente necesaria (ej., una integración de servicio de pago, una dependencia pesada), ponla en **`optional-skills/`** — se envía con el repositorio pero no está activada por defecto. Los usuarios pueden descubrirla a través de `hermes skills browse` (etiquetada como "oficial") e instalarla con `hermes skills install` (sin advertencia de terceros, confianza integrada).
-
-Si tu habilidad es especializada, contribuida por la comunidad o de nicho, es mejor para un **Skills Hub** — súbela a un registro de habilidades y compártela en el [Discord de Nous Research](https://discord.gg/NousResearch). Los usuarios pueden instalarla con `hermes skills install`.
-
---
-
-## Proveedores de Memoria: Publicar como Plugin Independiente
-
-**Ya no aceptamos nuevos proveedores de memoria en este repositorio.** El conjunto de proveedores integrados en `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) está cerrado. Si quieres añadir un nuevo backend de memoria, publícalo como un **repositorio de plugin independiente** que los usuarios instalen en `~/.hermes/plugins/` (o a través de un entry point de pip).
-
-Los plugins de memoria independientes:
-
- Implementan el mismo ABC `MemoryProvider` (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown` y opcionalmente `post_setup(hermes_home, config)` para integración con el asistente de configuración
- Usan el mismo sistema de descubrimiento — `discover_memory_providers()` los recoge desde directorios de plugins de usuario/proyecto y entry points de pip
- Se integran con `hermes memory setup` a través de `post_setup()` — sin necesidad de tocar el código base
- Pueden registrar sus propios subcomandos CLI a través de `register_cli(subparser)` en un archivo `cli.py`
- Obtienen todos los mismos hooks de ciclo de vida y plomería de configuración que los proveedores incluidos en el árbol
-
-Los PRs que añadan un nuevo directorio bajo `plugins/memory/` serán cerrados con un puntero para publicar el proveedor como su propio repositorio. Los proveedores en árbol existentes se mantienen; las correcciones de errores para ellos son bienvenidas.
-
-Esto no es una barra de calidad — es una decisión de acoplamiento y mantenimiento. Los proveedores de memoria son el tipo de plugin más común y no deberían vivir todos en este árbol.
-
---
-
-## Configuración del Desarrollo
-
-### Prerequisitos
-
-| Requisito | Notas |
-|-----------|-------|
-| **Git** | Con la extensión `git-lfs` instalada |
-| **Python 3.11–3.13** | uv lo instalará si falta |
-| **uv** | Gestor de paquetes Python rápido ([instalar](https://docs.astral.sh/uv/)) |
-| **Node.js 20+** | Opcional — necesario para herramientas de navegador y puente WhatsApp (coincide con los engines de `package.json` raíz) |
-
-### Clonar e instalar
-
-```bash
-git clone https://github.com/NousResearch/hermes-agent.git
-cd hermes-agent
-
-# Crear venv con Python 3.11
-uv venv venv --python 3.11
-export VIRTUAL_ENV="$(pwd)/venv"
-
-# Instalar con todos los extras (mensajería, cron, menús CLI, herramientas de desarrollo)
-uv pip install -e ".[all,dev]"
-
-# Opcional: herramientas de navegador
-npm install
-```
-
-### Configurar para desarrollo
-
-```bash
-mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
-cp cli-config.yaml.example ~/.hermes/config.yaml
-touch ~/.hermes/.env
-
-# Añadir al menos una clave de proveedor LLM:
-echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
-```
-
-### Ejecutar
-
-```bash
-# Enlace simbólico para acceso global
-mkdir -p ~/.local/bin
-ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
-
-# Verificar
-hermes doctor
-hermes chat -q "Hola"
-```
-
-### Ejecutar tests
-
-```bash
-# Preferido — coincide con CI (entorno hermético, 4 workers xdist); ver AGENTS.md
-scripts/run_tests.sh
-
-# Alternativa (activa el venv primero). El wrapper sigue recomendándose
-# para paridad con GitHub Actions antes de abrir un PR:
-pytest tests/ -v
-```
-
---
-
-## Estructura del Proyecto
-
-```
-hermes-agent/
-├── run_agent.py              # Clase AIAgent — bucle de conversación central, despacho de herramientas, persistencia de sesión
-├── cli.py                    # Clase HermesCLI — TUI interactiva, integración prompt_toolkit
-├── model_tools.py            # Orquestación de herramientas (capa delgada sobre tools/registry.py)
-├── toolsets.py               # Agrupaciones y presets de herramientas (hermes-cli, hermes-telegram, etc.)
-├── hermes_state.py           # Base de datos de sesiones SQLite con búsqueda de texto completo FTS5, títulos de sesión
-├── batch_runner.py           # Procesamiento en lote paralelo para generación de trayectorias
-│
-├── agent/                    # Internos del agente (módulos extraídos)
-│   ├── prompt_builder.py         # Ensamblaje del prompt del sistema (identidad, habilidades, archivos de contexto, memoria)
-│   ├── context_compressor.py     # Auto-resumición al acercarse a los límites de contexto
-│   ├── auxiliary_client.py       # Resuelve clientes OpenAI auxiliares (resumición, visión)
-│   ├── display.py                # KawaiiSpinner, formateo del progreso de herramientas
-│   ├── model_metadata.py         # Longitudes de contexto del modelo, estimación de tokens
-│   └── trajectory.py             # Ayudantes para guardar trayectorias
-│
-├── hermes_cli/               # Implementaciones de comandos CLI
-│   ├── main.py                   # Punto de entrada, análisis de argumentos, despacho de comandos
-│   ├── config.py                 # Gestión de configuración, migración, definiciones de variables de entorno
-│   ├── setup.py                  # Asistente de configuración interactivo
-│   ├── auth.py                   # Resolución de proveedor, OAuth, Nous Portal
-│   ├── models.py                 # Listas de selección de modelos de OpenRouter
-│   ├── banner.py                 # Banner de bienvenida, arte ASCII
-│   ├── commands.py               # Registro central de comandos de barra (CommandDef), autocompletado, ayudantes del gateway
-│   ├── callbacks.py              # Callbacks interactivos (aclarar, sudo, aprobación)
-│   ├── doctor.py                 # Diagnósticos
-│   ├── skills_hub.py             # CLI del Skills Hub + comando de barra /skills
-│   └── skin_engine.py            # Motor de skins/temas — personalización visual de CLI basada en datos
-│
-├── tools/                    # Implementaciones de herramientas (auto-registradas)
-│   ├── registry.py               # Registro central de herramientas (esquemas, manejadores, despacho)
-│   ├── approval.py               # Detección de comandos peligrosos + aprobación por sesión
-│   ├── terminal_tool.py          # Orquestación del terminal (sudo, ciclo de vida del entorno, backends)
-│   ├── file_operations.py        # read_file, write_file, búsqueda, patch, etc.
-│   ├── web_tools.py              # web_search, web_extract (Paralelo/Firecrawl + resumición Gemini)
-│   ├── vision_tools.py           # Análisis de imágenes a través de modelos multimodales
-│   ├── delegate_tool.py          # Lanzamiento de subagentes y ejecución paralela de tareas
-│   ├── code_execution_tool.py    # Python sandboxado con acceso a herramientas vía RPC
-│   ├── session_search_tool.py    # Búsqueda en conversaciones pasadas con FTS5 + ventanas ancladas
-│   ├── cronjob_tools.py          # Gestión de tareas programadas
-│   ├── skill_tools.py            # Búsqueda, carga y gestión de habilidades
-│   └── environments/             # Backends de ejecución del terminal
-│       ├── base.py                   # ABC BaseEnvironment
-│       ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
-│
-├── gateway/                  # Gateway de mensajería
-│   ├── run.py                    # GatewayRunner — ciclo de vida de plataformas, enrutamiento de mensajes, cron
-│   ├── config.py                 # Resolución de configuración de plataformas
-│   ├── session.py                # Almacén de sesiones, prompts de contexto, políticas de reset
-│   └── platforms/                # Adaptadores de plataformas
-│       ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py
-│
-├── scripts/                  # Scripts del instalador y puente
-│   ├── install.sh                # Instalador Linux/macOS
-│   ├── install.ps1               # Instalador Windows PowerShell
-│   └── whatsapp-bridge/          # Puente WhatsApp Node.js (Baileys)
-│
-├── skills/                   # Habilidades incluidas (copiadas a ~/.hermes/skills/ en la instalación)
-├── optional-skills/          # Habilidades opcionales oficiales (descubribles vía hub, no activadas por defecto)
-├── tests/                    # Suite de tests
-├── website/                  # Sitio de documentación (hermes-agent.nousresearch.com)
-│
-├── cli-config.yaml.example   # Configuración de ejemplo (copiada a ~/.hermes/config.yaml)
-└── AGENTS.md                 # Guía de desarrollo para asistentes de codificación IA
-```
-
-### Configuración del usuario (almacenada en `~/.hermes/`)
-
-| Ruta | Propósito |
-|------|-----------|
-| `~/.hermes/config.yaml` | Configuración (modelo, terminal, toolsets, compresión, etc.) |
-| `~/.hermes/.env` | Claves API y secretos |
-| `~/.hermes/auth.json` | Credenciales OAuth (Nous Portal) |
-| `~/.hermes/skills/` | Todas las habilidades activas (incluidas + instaladas desde hub + creadas por el agente) |
-| `~/.hermes/memories/` | Memoria persistente (MEMORY.md, USER.md) |
-| `~/.hermes/state.db` | Base de datos de sesiones SQLite |
-| `~/.hermes/sessions/` | Índice de enrutamiento del gateway (`sessions.json`), migas de pan de solicitudes, transcripciones `*.jsonl` del gateway y (opcionalmente) snapshots JSON por sesión cuando `sessions.write_json_snapshots: true` está configurado. Los snapshots por sesión están desactivados por defecto; state.db es canónica. |
-| `~/.hermes/cron/` | Datos de trabajos programados |
-| `~/.hermes/whatsapp/session/` | Credenciales del puente WhatsApp |
-
---
-
-## Descripción General de la Arquitectura
-
-### Bucle Central
-
-```
-Mensaje del usuario → AIAgent._run_agent_loop()
-  ├── Construir prompt del sistema (prompt_builder.py)
-  ├── Construir kwargs de API (modelo, mensajes, herramientas, configuración de razonamiento)
-  ├── Llamar al LLM (API compatible con OpenAI)
-  ├── Si tool_calls en la respuesta:
-  │     ├── Ejecutar cada herramienta a través del despacho del registro
-  │     ├── Añadir resultados de herramientas a la conversación
-  │     └── Volver a la llamada al LLM
-  ├── Si respuesta de texto:
-  │     ├── Persistir sesión en DB
-  │     └── Devolver final_response
-  └── Compresión de contexto si se acerca al límite de tokens
-```
-
-### Patrones de Diseño Clave
-
- **Herramientas auto-registradas**: Cada archivo de herramienta llama a `registry.register()` en el momento de importación. `model_tools.py` activa el descubrimiento importando todos los módulos de herramientas.
- **Agrupación en toolsets**: Las herramientas se agrupan en toolsets (`web`, `terminal`, `file`, `browser`, etc.) que pueden habilitarse/deshabilitarse por plataforma.
- **Persistencia de sesión**: Todas las conversaciones se almacenan en SQLite (`hermes_state.py`) con búsqueda de texto completo y títulos de sesión únicos.
- **Inyección efímera**: Los prompts del sistema y los mensajes de relleno se inyectan en el momento de la llamada API, nunca se persisten en la base de datos ni en los logs.
- **Abstracción de proveedor**: El agente funciona con cualquier API compatible con OpenAI. La resolución del proveedor ocurre en el momento de la inicialización.
- **Enrutamiento de proveedor**: Al usar OpenRouter, `provider_routing` en config.yaml controla la selección del proveedor.
-
---
-
-## Estilo de Código
-
- **PEP 8** con excepciones prácticas (no imponemos longitud de línea estricta)
- **Comentarios**: Solo cuando se explica la intención no obvia, compromisos o peculiaridades de API. No narres lo que hace el código
- **Manejo de errores**: Captura excepciones específicas. Registra con `logger.warning()`/`logger.error()` — usa `exc_info=True` para errores inesperados
- **Multiplataforma**: Nunca asumas Unix. Ver [Compatibilidad Multiplataforma](#compatibilidad-multiplataforma)
-
---
-
-## Añadir una Nueva Herramienta
-
-Antes de escribir una herramienta, pregúntate: [¿debería ser una habilidad en su lugar?](#debería-ser-una-habilidad-o-una-herramienta)
-
-Las herramientas se auto-registran en el registro central. Cada archivo de herramienta co-localiza su esquema, manejador y registro:
-
-```python
-"""my_tool — Breve descripción de lo que hace esta herramienta."""
-
-import json
-from tools.registry import registry
-
-
-def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
-    """Manejador. Devuelve un resultado en cadena (a menudo JSON)."""
-    result = do_work(param1, param2)
-    return json.dumps(result)
-
-
-MY_TOOL_SCHEMA = {
-    "type": "function",
-    "function": {
-        "name": "my_tool",
-        "description": "Qué hace esta herramienta y cuándo debería usarla el agente.",
-        "parameters": {
-            "type": "object",
-            "properties": {
-                "param1": {"type": "string", "description": "Qué es param1"},
-                "param2": {"type": "integer", "description": "Qué es param2", "default": 10},
-            },
-            "required": ["param1"],
-        },
-    },
-}
-
-
-def _check_requirements() -> bool:
-    """Devuelve True si las dependencias de esta herramienta están disponibles."""
-    return True
-
-
-registry.register(
-    name="my_tool",
-    toolset="my_toolset",
-    schema=MY_TOOL_SCHEMA,
-    handler=lambda args, **kw: my_tool(**args, **kw),
-    check_fn=_check_requirements,
-)
-```
-
-**Conectar a un toolset (requerido):** Las herramientas integradas se auto-descubren: cualquier
-archivo `tools/*.py` que contenga una llamada de nivel superior `registry.register(...)` es
-importado por `discover_builtin_tools()` en `tools/registry.py` cuando `model_tools`
-se carga. **No** hay una lista de importaciones manual en `model_tools.py` que mantener.
-
-Todavía debes añadir el nombre de la herramienta a la lista apropiada en `toolsets.py`
-(por ejemplo `_HERMES_CORE_TOOLS` o un toolset dedicado); de lo contrario la herramienta
-se registra pero nunca se expone al agente.
-
-Consulta `AGENTS.md` (sección **Adding New Tools**) para rutas conscientes del perfil y
-orientación sobre plugins vs. núcleo.
-
---
-
-## Añadir una Habilidad
-
-Las habilidades incluidas viven en `skills/` organizadas por categoría. Las habilidades opcionales oficiales usan la misma estructura en `optional-skills/`:
-
-```
-skills/
-├── research/
-│   └── arxiv/
-│       ├── SKILL.md              # Requerido: instrucciones principales
-│       └── scripts/              # Opcional: scripts auxiliares
-│           └── search_arxiv.py
-├── productivity/
-│   └── ocr-and-documents/
-│       ├── SKILL.md
-│       ├── scripts/
-│       └── references/
-└── ...
-```
-
-### Formato de SKILL.md
-
-```markdown
---
-name: my-skill
-description: Breve descripción (mostrada en los resultados de búsqueda de habilidades)
-version: 1.0.0
-author: Tu Nombre
-license: MIT
-platforms: [macos, linux]          # Opcional — restringir a plataformas de SO específicas
-required_environment_variables:    # Opcional — metadatos de configuración segura al cargar
-  - name: MY_API_KEY
-    prompt: Clave API
-    help: Dónde obtenerla
-    required_for: funcionalidad completa
-prerequisites:                     # Requisitos de tiempo de ejecución heredados opcionales
-  env_vars: [MY_API_KEY]
-  commands: [curl, jq]
-metadata:
-  hermes:
-    tags: [Categoría, Subcategoría, Palabras clave]
-    related_skills: [other-skill-name]
-    fallback_for_toolsets: [web]
-    requires_toolsets: [terminal]
---
-
-# Título de la Habilidad
-
-Introducción breve.
-
-## Cuándo Usar
-Condiciones de activación — ¿cuándo debería el agente cargar esta habilidad?
-
-## Referencia Rápida
-Tabla de comandos o llamadas API comunes.
-
-## Procedimiento
-Instrucciones paso a paso que el agente sigue.
-
-## Problemas Conocidos
-Modos de fallo conocidos y cómo manejarlos.
-
-## Verificación
-Cómo confirma el agente que funcionó.
-```
-
-### Estándares de autoría de habilidades (OBLIGATORIOS)
-
-Todo skill nuevo o modernizado — incluido, opcional o contribuido — debe cumplir estos estándares antes del merge:
-
-1. **`description` ≤ 60 caracteres, una oración, termina con punto.** Las descripciones largas saturan la UI de listado de habilidades. Indica la capacidad, no la implementación. Sin palabras de marketing ("potente", "completo", "fluido", "avanzado").
-
-2. **Las herramientas referenciadas en el cuerpo de SKILL.md deben ser herramientas nativas de Hermes o servidores MCP que la habilidad espere explícitamente.** Usa los nombres de herramientas en comillas invertidas: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, etc.
-
-3. **El campo `platforms:` auditado contra las importaciones reales del script.** Las habilidades que usen primitivos solo de POSIX deben declarar sus plataformas soportadas.
-
-4. **`author` da crédito primero al colaborador humano.**
-
-5. **El cuerpo de SKILL.md usa el orden moderno de secciones:** título, intro de 2-3 oraciones, luego: `## Cuándo Usar`, `## Prerequisitos`, `## Cómo Ejecutar`, `## Referencia Rápida`, `## Procedimiento`, `## Problemas Conocidos`, `## Verificación`.
-
-6. **Los scripts van en `scripts/`, las referencias en `references/`, las plantillas en `templates/`.**
-
-7. **Los tests viven en `tests/skills/test_<skill>_skill.py`** y usan solo stdlib + pytest + `unittest.mock`. Sin llamadas de red en vivo.
-
-8. **Las adiciones a `.env.example` están aisladas en un bloque claramente delimitado.**
-
---
-
-## Añadir una Skin / Tema
-
-Hermes usa un sistema de skins basado en datos — no se necesitan cambios de código para añadir una nueva skin.
-
-**Opción A: Skin de usuario (archivo YAML)**
-
-Crea `~/.hermes/skins/<nombre>.yaml`:
-
-```yaml
-name: mitema
-description: Breve descripción del tema
-
-colors:
-  banner_border: "#HEX"
-  banner_title: "#HEX"
-  banner_accent: "#HEX"
-  banner_dim: "#HEX"
-  banner_text: "#HEX"
-  response_border: "#HEX"
-
-spinner:
-  waiting_faces: ["(⚔)", "(⛨)"]
-  thinking_faces: ["(⚔)", "(⌁)"]
-  thinking_verbs: ["forjando", "planeando"]
-
-branding:
-  agent_name: "Mi Agente"
-  welcome: "Mensaje de bienvenida"
-  response_label: " ⚔ Agente "
-  prompt_symbol: "⚔"
-
-tool_prefix: "╎"
-```
-
-Todos los campos son opcionales — los valores faltantes se heredan de la skin predeterminada.
-
-**Opción B: Skin integrada**
-
-Añade al dict `_BUILTIN_SKINS` en `hermes_cli/skin_engine.py`. Usa el mismo esquema que arriba pero como dict de Python.
-
-**Activar:**
- CLI: `/skin mitema` o establece `display.skin: mitema` en config.yaml
-
---
-
-## Compatibilidad Multiplataforma
-
-Hermes se ejecuta en Linux, macOS y Windows nativo (además de WSL2). Al escribir código
-que toca el SO, asume que *cualquier* plataforma puede alcanzar tu ruta de código.
-
-> **Antes de hacer PR:** ejecuta `scripts/check-windows-footguns.py` para detectar
-> los patrones inseguros comunes de Windows en tu diff. Es basado en grep y barato;
-> CI también lo ejecuta en cada PR.
-
-### Reglas críticas
-
-1. **Nunca llames `os.kill(pid, 0)` para comprobaciones de liveness.** En Windows **NO es una operación sin efecto**. Usa `psutil.pid_exists(pid)` en su lugar.
-
-2. **Usa `shutil.which()` antes de hacer shell — no asumas que Windows tiene las herramientas que tiene Linux.** `ps`, `kill`, `grep`, `awk`, etc. simplemente no existen en Windows.
-
-3. **`termios` y `fcntl` son solo de Unix.** Siempre captura tanto `ImportError` como `NotImplementedError`.
-
-4. **Codificación de archivos.** Windows puede guardar archivos `.env` en `cp1252`. Siempre maneja errores de codificación.
-
-5. **Gestión de procesos.** `os.setsid()`, `os.killpg()`, `os.fork()`, `os.getuid()` y el manejo de señales POSIX difieren en Windows.
-
-6. **Señales que no existen en Windows:** `SIGALRM`, `SIGCHLD`, `SIGHUP`, `SIGUSR1`, `SIGUSR2`, etc.
-
-7. **Separadores de ruta.** Usa `pathlib.Path` en lugar de concatenación de cadenas con `/`.
-
-8. **Los enlaces simbólicos necesitan privilegios elevados en Windows** (a menos que el Modo Desarrollador esté activado).
-
-9. **Los modos de archivo POSIX (0o600, 0o644, etc.) NO se aplican en NTFS** por defecto.
-
-10. **Los daemons de fondo desacoplados en Windows necesitan `pythonw.exe`, NO `python.exe`.**
-
---
-
-## Consideraciones de Seguridad
-
-Hermes tiene acceso al terminal. La seguridad importa.
-
-### Protecciones existentes
-
-| Capa | Implementación |
-|------|---------------|
-| **Piping de contraseña sudo** | Usa `shlex.quote()` para prevenir inyección de shell |
-| **Detección de comandos peligrosos** | Patrones regex en `tools/approval.py` con flujo de aprobación del usuario |
-| **Inyección de prompts en cron** | Escáner en `tools/cronjob_tools.py` bloquea patrones de anulación de instrucciones |
-| **Lista de denegación de escritura** | Rutas protegidas resueltas a través de `os.path.realpath()` para prevenir bypass de enlaces simbólicos |
-| **Skills Guard** | Escáner de seguridad para habilidades instaladas desde el hub (`tools/skills_guard.py`) |
-| **Sandbox de ejecución de código** | El proceso hijo `execute_code` se ejecuta con claves API eliminadas del entorno |
-| **Fortalecimiento de contenedor** | Docker: todas las capacidades eliminadas, sin escalada de privilegios, límites de PID, tmpfs de tamaño limitado |
-
-### Al contribuir código sensible a la seguridad
-
- **Siempre usa `shlex.quote()`** al interpolar entrada del usuario en comandos de shell
- **Resuelve enlaces simbólicos** con `os.path.realpath()` antes de comprobaciones de control de acceso basadas en rutas
- **No registres secretos.** Las claves API, tokens y contraseñas nunca deben aparecer en la salida de log
- **Captura excepciones amplias** alrededor de la ejecución de herramientas para que un solo fallo no bloquee el bucle del agente
- **Prueba en todas las plataformas** si tu cambio toca rutas de archivos, gestión de procesos o comandos de shell
-
-### Política de fijación de dependencias (fortalecimiento de la cadena de suministro)
-
-Tras el [compromiso de la cadena de suministro de litellm](https://github.com/BerriAI/litellm/issues/24512) en marzo de 2026 y la [campaña del gusano Mini Shai-Hulud](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) en mayo de 2026, todas las dependencias deben seguir estas reglas:
-
-| Tipo de fuente | Tratamiento requerido | Justificación |
-|---|---|---|
-| **Paquete PyPI** | `>=suelo,<siguiente_mayor` | Las versiones de PyPI son inmutables una vez publicadas, pero pueden empujarse nuevas versiones en tu rango. |
-| **URL de Git** | SHA completo del commit | Las ramas y etiquetas son refs mutables; el SHA está direccionado por contenido. |
-| **GitHub Actions** | SHA completo del commit + comentario de versión | Las etiquetas de acción son refs mutables. Fija como `uses: owner/action@<sha>  # vX.Y.Z` |
-| **Instalaciones pip solo de CI** | `==exacto` | Builds de CI herméticos; el cambio es aceptable. |
-
-**Cada nueva dependencia de PyPI en un PR debe tener un límite superior `<siguiente_mayor`.** Los PRs que añadan especificaciones `>=X.Y.Z` sin límite superior serán rechazados.
-
---
-
-## Proceso de Pull Request
-
-### Nomenclatura de ramas
-
-```
-fix/descripcion        # Correcciones de errores
-feat/descripcion       # Nuevas funcionalidades
-docs/descripcion       # Documentación
-test/descripcion       # Tests
-refactor/descripcion   # Reestructuración de código
-```
-
-### Antes de enviar
-
-1. **Ejecutar tests**: `scripts/run_tests.sh` (recomendado; igual que CI) o `pytest tests/ -v` con el venv del proyecto activado
-2. **Probar manualmente**: Ejecuta `hermes` y ejercita la ruta de código que cambiaste
-3. **Verificar impacto multiplataforma**: Si tocas E/S de archivos, gestión de procesos o manejo del terminal, considera macOS, Linux y WSL2
-4. **Mantén los PRs enfocados**: Un cambio lógico por PR. No mezcles una corrección de error con una refactorización con una nueva funcionalidad.
-
-### Descripción del PR
-
-Incluye:
- **Qué** cambió y **por qué**
- **Cómo probarlo** (pasos de reproducción para errores, ejemplos de uso para funcionalidades)
- **Qué plataformas** probaste
- Referencia cualquier issue relacionado
-
-### Mensajes de commit
-
-Usamos [Conventional Commits](https://www.conventionalcommits.org/):
-
-```
-<tipo>(<alcance>): <descripción>
-```
-
-| Tipo | Usar para |
-|------|-----------|
-| `fix` | Correcciones de errores |
-| `feat` | Nuevas funcionalidades |
-| `docs` | Documentación |
-| `test` | Tests |
-| `refactor` | Reestructuración de código (sin cambio de comportamiento) |
-| `chore` | Build, CI, actualizaciones de dependencias |
-
-Alcances: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security`, etc.
-
-Ejemplos:
-```
-fix(cli): prevenir bloqueo en save_config_value cuando el modelo es una cadena
-feat(gateway): añadir aislamiento de sesión multi-usuario de WhatsApp
-fix(security): prevenir inyección de shell en el piping de contraseña sudo
-test(tools): añadir tests unitarios para file_operations
-```
-
---
-
-## Reportar Issues
-
- Usa [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
- Incluye: SO, versión de Python, versión de Hermes (`hermes version`), traza de error completa
- Incluye pasos para reproducir
- Verifica los issues existentes antes de crear duplicados
- Para vulnerabilidades de seguridad, por favor reporta de forma privada
-
---
-
-## Comunidad
-
- **Discord**: [discord.gg/NousResearch](https://discord.gg/NousResearch) — para preguntas, mostrar proyectos y compartir habilidades
- **GitHub Discussions**: Para propuestas de diseño y discusiones de arquitectura
- **Skills Hub**: Sube habilidades especializadas a un registro y compártelas con la comunidad
-
---
-
-## Licencia
-
-Al contribuir, aceptas que tus contribuciones serán licenciadas bajo la [Licencia MIT](LICENSE).
@@ -9,7 +9,7 @@ Thank you for contributing to Hermes Agent! This guide covers everything you nee
 We value contributions in this order:

 1. **Bug fixes** — crashes, incorrect behavior, data loss. Always top priority.
-2. **Cross-platform compatibility** — macOS, different Linux distros, and WSL2 on Windows. We want Hermes to work everywhere.
+2. **Cross-platform compatibility** — Windows, macOS, different Linux distros, different terminal emulators. We want Hermes to work everywhere.
 3. **Security hardening** — shell injection, prompt injection, path traversal, privilege escalation. See [Security](#security-considerations).
 4. **Performance and robustness** — retry logic, error handling, graceful degradation.
 5. **New skills** — but only broadly useful ones. See [Should it be a Skill or a Tool?](#should-it-be-a-skill-or-a-tool)
@@ -18,24 +18,6 @@ We value contributions in this order:

 ---

-## Before You Start: Search First
-
-A quick search before you build saves your time and keeps the PR queue clean — duplicates are common here, so it's worth a minute up front.
-
- **Search both open *and* merged PRs and issues** for your topic or error symptom — the duplicate-check in the PR template fires at review time, after you've already done the work:
-  ```bash
-  gh search issues --repo NousResearch/hermes-agent "<your terms>"
-  gh search prs --repo NousResearch/hermes-agent --state all "<your terms>"
-  ```
-  Or use the web UI: [issues](https://github.com/NousResearch/hermes-agent/issues?q=) · [PRs (all states)](https://github.com/NousResearch/hermes-agent/pulls?q=is%3Apr).
- **The issue tracker can lag the code.** Many requested features are already implemented in-tree, so also search the source (`search_files`, or your editor's grep) for the capability before proposing it.
- **If an open PR already addresses it**, consider reviewing or improving that one instead of opening a competing duplicate.
- **For larger work**, comment on the issue to signal you're working on it, so others don't start the same thing.
-
-Related: #38284 covers the agent-side analog — Hermes itself checking existing issues and PRs before deep self-troubleshooting. This section is the human-contributor complement.
-
---
-
 ## Should it be a Skill or a Tool?

 This is the most common question for new contributors. The answer is almost always **skill**.
@@ -61,112 +43,39 @@ Bundled skills (in `skills/`) ship with every Hermes install. They should be **b
 - Document handling, web research, common dev workflows, system administration
 - Used regularly by a wide range of people

-If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo but isn't activated by default. Users can discover it via `hermes skills browse` (labeled "official") and install it with `hermes skills install` (no third-party warning, built-in trust).
+If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo but isn't activated by default. Users can discover it via `hermes skills browse` (labeled "official") and install it with `hermes skills install` (no third-party warning, builtin trust).

 If your skill is specialized, community-contributed, or niche, it's better suited for a **Skills Hub** — upload it to a skills registry and share it in the [Nous Research Discord](https://discord.gg/NousResearch). Users can install it with `hermes skills install`.

 ---

-## Memory Providers: Ship as a Standalone Plugin
-
-**We are no longer accepting new memory providers into this repo.** The set of built-in providers under `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) is closed. If you want to add a new memory backend, publish it as a **standalone plugin repo** that users install into `~/.hermes/plugins/` (or via a pip entry point).
-
-Standalone memory plugins:
-
- Implement the same `MemoryProvider` ABC (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown`, and optionally `post_setup(hermes_home, config)` for setup-wizard integration
- Use the same discovery system — `discover_memory_providers()` picks them up from user/project plugin directories and pip entry points
- Integrate with `hermes memory setup` via `post_setup()` — no need to touch core code
- Can register their own CLI subcommands via `register_cli(subparser)` in a `cli.py` file
- Get all the same lifecycle hooks and config plumbing as in-tree providers
-
-PRs that add a new directory under `plugins/memory/` will be closed with a pointer to publish the provider as its own repo. Existing in-tree providers stay; bug fixes to them are welcome.
-
-This isn't a quality bar — it's a coupling-and-maintenance decision. Memory providers are the most common plugin type and they shouldn't all live in this tree.
-
---
-
-## Third-Party Product Integrations: Ship as a Standalone Plugin
-
-The same rule extends to **any plugin that integrates someone else's product or project** — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins, and similar third-party integrations. **These do not land in this repo.**
-
-The reason is maintenance load, not quality. Every external product absorbed into the core tree becomes ours to keep working against a fast-moving codebase, for a backend we don't own and can't control. Hermes ships a lot and the core moves quickly; coupling third-party products into it creates an open-ended burden on the maintainers.
-
-Publish these as a **standalone plugin repo** instead:
-
- Implement the relevant ABC and use the existing plugin discovery path (`~/.hermes/plugins/`, project `.hermes/plugins/`, or a pip entry point) — see [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin)
- Register lifecycle hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`), tools (`ctx.register_tool`), and CLI subcommands (`ctx.register_cli_command`) through the surface we already expose — no core changes needed
- If your plugin needs a capability the framework doesn't expose, that's a feature request to **widen the generic plugin surface** (a new hook or `ctx` method) — never special-case your plugin in core
- Promote it in the [Nous Research Discord](https://discord.gg/NousResearch) `#plugins-skills-and-skins` channel so users can find and install it
-
-A well-built third-party-product plugin can clear automated review and still be closed for this reason — it's a placement decision, not a verdict on the code. PRs that add such a directory under `plugins/` will be closed with a pointer to publish it as its own repo.
-
---
-
 ## Development Setup

 ### Prerequisites

 | Requirement | Notes |
 |-------------|-------|
-| **Git** | With the `git-lfs` extension installed |
-| **Python 3.11–3.13** | uv will install it if missing |
+| **Git** | With `--recurse-submodules` support |
+| **Python 3.11+** | uv will install it if missing |
 | **uv** | Fast Python package manager ([install](https://docs.astral.sh/uv/)) |
-| **Node.js 20+** | Optional — needed for browser tools and WhatsApp bridge (matches root `package.json` engines) |
+| **Node.js 18+** | Optional — needed for browser tools and WhatsApp bridge |

-### Install with the standard installer
-
-For most contributors, the best development bootstrap is the same path users
-take: run the standard installer, then work inside the repository it cloned.
-The installer creates the Hermes venv, wires the `hermes` command, stamps the
-install method for `hermes update`, and clones the full git project into
-`$HERMES_HOME/hermes-agent` (usually `~/.hermes/hermes-agent`). That keeps your
-development environment on the same layout the CLI, updater, lazy dependency
-installer, gateway, and docs assume.
+### Clone and install

 ```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
-
-# Add dev/test extras on top of the standard install.
-uv pip install -e ".[all,dev]"
-
-# Optional: browser tools / docs site dependencies.
-npm install
-```
-
-After that, create branches and run tests from that checkout:
-
-```bash
-git checkout -b fix/description
-scripts/run_tests.sh
-```
-
-### Manual clone fallback
-
-Use this only if you intentionally do not want Hermes' managed install layout
-(for example, a throwaway clone inside a container or CI job). If you install
-this way, make sure you run the `hermes` entrypoint from this venv; running the
-system `python3 -m hermes_cli.main` can pick up unrelated system Python
-packages.
-
-Create the venv **outside** the cloned source tree. A venv that lives inside
-the directory the agent operates from can be wiped by a relative-path command
-the agent runs against its own checkout (`rm -rf venv`, `uv venv venv`, etc.),
-which silently destroys the running runtime mid-session. Keeping it outside the
-tree means no relative path from the workspace resolves to it.
-
-```bash
-git clone https://github.com/NousResearch/hermes-agent.git
+git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
 cd hermes-agent

-# Create venv with Python 3.11, OUTSIDE the source tree
-uv venv ~/.hermes/venvs/hermes-dev --python 3.11
-export VIRTUAL_ENV="$HOME/.hermes/venvs/hermes-dev"
-export PATH="$VIRTUAL_ENV/bin:$PATH"
+# Create venv with Python 3.11
+uv venv venv --python 3.11
+export VIRTUAL_ENV="$(pwd)/venv"

 # Install with all extras (messaging, cron, CLI menus, dev tools)
 uv pip install -e ".[all,dev]"

+# Optional: RL training submodule
+# git submodule update --init tinker-atropos && uv pip install -e "./tinker-atropos"
+
 # Optional: browser tools
 npm install
 ```
@@ -179,33 +88,24 @@ cp cli-config.yaml.example ~/.hermes/config.yaml
 touch ~/.hermes/.env

 # Add at minimum an LLM provider key:
-echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
+echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env
 ```

 ### Run

 ```bash
-# The standard installer already put `hermes` on PATH.
-hermes doctor
-hermes chat -q "Hello"
-```
-
-If you used the manual clone fallback, run `./hermes` from the checkout or
-symlink this clone's venv explicitly:
-
-```bash
+# Symlink for global access
 mkdir -p ~/.local/bin
 ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
+
+# Verify
+hermes doctor
+hermes chat -q "Hello"
 ```

 ### Run tests

 ```bash
-# Preferred — matches CI (hermetic env, 4 xdist workers); see AGENTS.md
-scripts/run_tests.sh
-
-# Alternative (activate the venv first). The wrapper is still recommended
-# for parity with GitHub Actions before you open a PR:
 pytest tests/ -v
 ```

@@ -252,7 +152,7 @@ hermes-agent/
 │   ├── vision_tools.py           # Image analysis via multimodal models
 │   ├── delegate_tool.py          # Subagent spawning and parallel task execution
 │   ├── code_execution_tool.py    # Sandboxed Python with RPC tool access
-│   ├── session_search_tool.py    # Search past conversations with FTS5 + anchored windows
+│   ├── session_search_tool.py    # Search past conversations with FTS5 + summarization
 │   ├── cronjob_tools.py          # Scheduled task management
 │   ├── skill_tools.py            # Skill search, load, manage
 │   └── environments/             # Terminal execution backends
@@ -273,6 +173,7 @@ hermes-agent/
 │
 ├── skills/                   # Bundled skills (copied to ~/.hermes/skills/ on install)
 ├── optional-skills/          # Official optional skills (discoverable via hub, not activated by default)
+├── environments/             # RL training environments (Atropos integration)
 ├── tests/                    # Test suite
 ├── website/                  # Documentation site (hermes-agent.nousresearch.com)
 │
@@ -290,7 +191,7 @@ hermes-agent/
 | `~/.hermes/skills/` | All active skills (bundled + hub-installed + agent-created) |
 | `~/.hermes/memories/` | Persistent memory (MEMORY.md, USER.md) |
 | `~/.hermes/state.db` | SQLite session database |
-| `~/.hermes/sessions/` | Gateway routing index (`sessions.json`), request-dump breadcrumbs, gateway `*.jsonl` transcripts, and (optionally) per-session JSON snapshots when `sessions.write_json_snapshots: true` is set. The per-session snapshots are off by default; state.db is canonical. |
+| `~/.hermes/sessions/` | JSON session logs |
 | `~/.hermes/cron/` | Scheduled job data |
 | `~/.hermes/whatsapp/session/` | WhatsApp bridge credentials |

@@ -319,7 +220,7 @@ User message → AIAgent._run_agent_loop()

 - **Self-registering tools**: Each tool file calls `registry.register()` at import time. `model_tools.py` triggers discovery by importing all tool modules.
 - **Toolset grouping**: Tools are grouped into toolsets (`web`, `terminal`, `file`, `browser`, etc.) that can be enabled/disabled per platform.
- **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search and unique session titles. Per-session JSON snapshots in `~/.hermes/sessions/` were superseded by the SQLite store and are off by default; opt back in with `sessions.write_json_snapshots: true` if you have external tooling that consumes the JSON files directly.
+- **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search and unique session titles. JSON logs go to `~/.hermes/sessions/`.
 - **Ephemeral injection**: System prompts and prefill messages are injected at API call time, never persisted to the database or logs.
 - **Provider abstraction**: The agent works with any OpenAI-compatible API. Provider resolution happens at init time (Nous Portal OAuth, OpenRouter API key, or custom endpoint).
 - **Provider routing**: When using OpenRouter, `provider_routing` in config.yaml controls provider selection (sort by throughput/latency/price, allow/ignore specific providers, data retention policies). These are injected as `extra_body.provider` in API requests.
@@ -385,18 +286,16 @@ registry.register(
 )
 ```

-**Wire into a toolset (required):** Built-in tools are auto-discovered: any
-`tools/*.py` file that contains a top-level `registry.register(...)` call is
-imported by `discover_builtin_tools()` in `tools/registry.py` when `model_tools`
-loads. There is **no** manual import list in `model_tools.py` to maintain.
+Then add the import to `model_tools.py` in the `_modules` list:

-You must still add the tool name to the appropriate list in `toolsets.py`
-(for example `_HERMES_CORE_TOOLS` or a dedicated toolset); otherwise the tool
-registers but is never exposed to the agent. If you introduce a new toolset,
-add it in `toolsets.py` and wire it into the relevant platform presets.
+```python
+_modules = [
+    # ... existing modules ...
+    "tools.my_tool",
+]
+```

-See `AGENTS.md` (section **Adding New Tools**) for profile-aware paths and
-plugin vs core guidance.
+If it's a new toolset, add it to `toolsets.py` and to the relevant platform presets.

 ---

@@ -454,12 +353,6 @@ Brief intro.
 ## When to Use
 Trigger conditions — when should the agent load this skill?

-## Prerequisites
-Env vars, install steps, MCP setup, API key sourcing.
-
-## How to Run
-Canonical invocation through the `terminal` tool.
-
 ## Quick Reference
 Table of common commands or API calls.

@@ -561,58 +454,6 @@ Gateway and messaging sessions never collect secrets in-band; they instruct the

 See `skills/gifs/gif-search/` and `skills/email/himalaya/` for examples.

-### Skill authoring standards (HARDLINE)
-
-Every new or modernized skill — bundled, optional, or contributed — must meet these standards before merge. Reviewers reject PRs that violate them.
-
-1. **`description` ≤ 60 characters, one sentence, ends with a period.** Long descriptions bloat the skill listing UI and dilute the model's attention when many skills are loaded. State the capability, not the implementation. No marketing words ("powerful", "comprehensive", "seamless", "advanced"). Don't repeat the skill name. Verify with:
-   ```python
-   import re, pathlib
-   m = re.search(r'^description: (.*)$',
-                 pathlib.Path('skills/<cat>/<name>/SKILL.md').read_text(),
-                 re.MULTILINE)
-   assert len(m.group(1)) <= 60, len(m.group(1))
-   ```
-
-   Good: `Search arXiv papers by keyword, author, category, or ID.`
-   Bad: `A powerful and comprehensive skill that allows the agent to search arXiv for relevant academic papers using various criteria including keywords, authors, and categories.`
-
-2. **Tools referenced in SKILL.md prose must be native Hermes tools or MCP servers the skill explicitly expects.** When the skill needs a capability, point at the proper tool by name in backticks: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, `` `patch` ``, `` `search_files` ``, `` `vision_analyze` ``, `` `browser_navigate` ``, `` `delegate_task` ``, `` `image_generate` ``, `` `text_to_speech` ``, `` `cronjob` ``, `` `memory` ``, `` `skill_view` ``, `` `todo` ``, `` `execute_code` ``.
-
-   Do NOT name shell utilities the agent already has wrapped:
-
-   | Don't say | Say |
-   |---|---|
-   | `grep`, `rg` | `search_files` |
-   | `cat`, `head`, `tail` | `read_file` |
-   | `sed`, `awk` | `patch` |
-   | `find`, `ls` | `search_files` (with `target='files'`) |
-   | `curl` for content extraction | `web_extract` |
-   | `echo > file`, `cat <<EOF` | `write_file` |
-
-   If the skill depends on an MCP server, name the MCP server and document its setup in `## Prerequisites`. Third-party CLIs (e.g. `ffmpeg`, `gh`, a specific SDK) are fine to invoke from inside script files, but the prose should frame the interaction as "invoke through the `terminal` tool", not as a manual shell session.
-
-3. **`platforms:` gating audited against actual script imports.** Skills that use POSIX-only primitives (`fcntl`, `termios`, `os.setsid`, `os.kill(pid, 0)` for liveness, `/proc`, hardcoded `/tmp` paths, `signal.SIGKILL`, bash heredocs, `osascript`, `apt`, `systemctl`) must declare their supported platforms via the `platforms:` frontmatter. Default posture is to fix it cross-platform first — `tempfile.gettempdir()`, `pathlib.Path`, `psutil.pid_exists()`, Python-level filtering instead of `grep`. Gate to a narrower set only when the dependency is genuinely platform-bound (e.g. `osascript` is macOS-only, `/proc` is Linux-only).
-
-4. **`author` credits the human contributor first.** For external contributions, the contributor's real name + GitHub handle goes first (`Jane Doe (jane-doe)`); "Hermes Agent" is the secondary collaborator. If the contributor's commit shows "Hermes Agent" as author because they used Hermes to draft the skill, replace it with their actual name — credit the human, not the tool.
-
-5. **SKILL.md body uses the modern section order.** `# <Skill> Skill` title, 2-3 sentence intro stating what it does and what it doesn't do, then:
-   - `## When to Use` — trigger conditions
-   - `## Prerequisites` — env vars, install steps, MCP setup, API key sourcing
-   - `## How to Run` — canonical invocation through the `terminal` tool
-   - `## Quick Reference` — flat command/API reference
-   - `## Procedure` — numbered steps with copy-paste commands
-   - `## Pitfalls` — known limits, rate limits, things that look broken but aren't
-   - `## Verification` — single command that proves the skill works
-
-   Target ~200 lines for a complex skill, ~100 lines for a simple one. Cut redundant intro fluff, marketing prose, and re-explanations of env vars already documented in `## Prerequisites`.
-
-6. **Scripts go in `scripts/`, references in `references/`, templates in `templates/`.** Don't expect the model to inline-write parsers, XML walkers, or non-trivial logic every call — ship a helper script. Reference scripts from SKILL.md by path relative to the skill directory.
-
-7. **Tests live at `tests/skills/test_<skill>_skill.py`** and use only stdlib + pytest + `unittest.mock`. No live network calls. Run via `scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q`. Must pass under the hermetic CI env (no API keys leaking through). Use `monkeypatch` and `tmp_path` for any env-var or filesystem dependencies.
-
-8. **`.env.example` additions are isolated to a clearly delimited block.** Don't touch the surrounding file — contributor-supplied `.env.example` versions are usually stale, and edits outside the skill's own block will be dropped during salvage. Comment all values with `#` (it's documentation, not live config).
-
 ### Skill guidelines

 - **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`).
@@ -653,7 +494,7 @@ branding:
  agent_name: "My Agent"
  welcome: "Welcome message"
  response_label: " ⚔ Agent "
-  prompt_symbol: "⚔"
+  prompt_symbol: "⚔ ❯ "

 tool_prefix: "╎"             # Tool output line prefix
 ```
@@ -674,57 +515,11 @@ See `hermes_cli/skin_engine.py` for the full schema and existing skins as exampl

 ## Cross-Platform Compatibility

-Hermes runs on Linux, macOS, and native Windows (plus WSL2). When writing code
-that touches the OS, assume *any* platform can hit your code path.
-
-> **Before you PR:** run `scripts/check-windows-footguns.py` to catch the
-> common Windows-unsafe patterns in your diff. It's grep-based and cheap;
-> CI runs it on every PR too.
+Hermes runs on Linux, macOS, and Windows. When writing code that touches the OS:

 ### Critical rules

-1. **Never call `os.kill(pid, 0)` for liveness checks.** `os.kill(pid, 0)`
-   is a standard POSIX idiom to check "is this PID alive" — the signal 0
-   is a no-op permission check. **On Windows it is NOT a no-op.** Python's
-   Windows `os.kill` maps `sig=0` to `CTRL_C_EVENT` (they collide at the
-   integer value 0) and routes it through `GenerateConsoleCtrlEvent(0, pid)`,
-   which broadcasts Ctrl+C to the **entire console process group** containing
-   the target PID. "Probe if alive" silently becomes "kill the target and
-   often unrelated processes sharing its console." See [bpo-14484](https://bugs.python.org/issue14484)
-   (open since 2012 — will never be fixed for compat reasons).
-
-   **Preferred:** use `psutil` (a core dependency — always available):
-
-   ```python
-   import psutil
-   if psutil.pid_exists(pid):
-       # process is alive — safe on every platform
-       ...
-   ```
-
-   If you specifically need the hermes wrapper (it has a stdlib fallback
-   for scaffold-phase imports before pip install finishes), use
-   `gateway.status._pid_exists(pid)`. It calls `psutil.pid_exists` first
-   and falls back to a hand-rolled `OpenProcess + WaitForSingleObject`
-   dance on Windows only when psutil is somehow missing.
-
-   Audit grep for new callsites: `rg "os\.kill\([^,]+,\s*0\s*\)"`. Any hit
-   in non-test code is presumptively a Windows silent-kill bug.
-
-2. **Use `shutil.which()` before shelling out — don't assume Windows has
-   tools Linux has.** `wmic` was removed in Windows 10 21H1 and later. `ps`,
-   `kill`, `grep`, `awk`, `fuser`, `lsof`, `pgrep`, and most POSIX CLI tools
-   simply don't exist on Windows. Test availability with
-   `shutil.which("tool")` and fall back to a Windows-native equivalent —
-   usually PowerShell via `subprocess.run(["powershell", "-NoProfile",
-   "-Command", ...])`.
-
-   For process enumeration: PowerShell's `Get-CimInstance Win32_Process` is
-   the modern replacement for `wmic process`. See
-   `hermes_cli/gateway.py::_scan_gateway_pids` for the pattern.
-
-3. **`termios` and `fcntl` are Unix-only.** Always catch both `ImportError`
-   and `NotImplementedError`:
+1. **`termios` and `fcntl` are Unix-only.** Always catch both `ImportError` and `NotImplementedError`:
   ```python
   try:
       from simple_term_menu import TerminalMenu
@@ -737,126 +532,24 @@ that touches the OS, assume *any* platform can hit your code path.
       idx = int(input("Choice: ")) - 1
   ```

-4. **File encoding.** Windows may save `.env` files in `cp1252`. Always
-   handle encoding errors:
+2. **File encoding.** Windows may save `.env` files in `cp1252`. Always handle encoding errors:
   ```python
   try:
       load_dotenv(env_path)
   except UnicodeDecodeError:
       load_dotenv(env_path, encoding="latin-1")
   ```
-   Config files (`config.yaml`) may be saved with a UTF-8 BOM by Notepad and
-   similar editors — use `encoding="utf-8-sig"` when reading files that
-   could have been touched by a Windows GUI editor.

-5. **Process management.** `os.setsid()`, `os.killpg()`, `os.fork()`,
-   `os.getuid()`, and POSIX signal handling differ on Windows. Guard with
-   `platform.system()`, `sys.platform`, or `hasattr(os, "setsid")`:
+3. **Process management.** `os.setsid()`, `os.killpg()`, and signal handling differ on Windows. Use platform checks:
   ```python
+   import platform
   if platform.system() != "Windows":
       kwargs["preexec_fn"] = os.setsid
-   else:
-       kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
   ```

-   **Preferred:** for killing a process AND its children (what `os.killpg`
-   does on POSIX), use `psutil` — it works on every platform:
-   ```python
-   import psutil
-   try:
-       parent = psutil.Process(pid)
-       # Kill children first (leaf-up), then the parent.
-       for child in parent.children(recursive=True):
-           child.kill()
-       parent.kill()
-   except psutil.NoSuchProcess:
-       pass
-   ```
+4. **Path separators.** Use `pathlib.Path` instead of string concatenation with `/`.

-6. **Signals that don't exist on Windows: `SIGALRM`, `SIGCHLD`, `SIGHUP`,
-   `SIGUSR1`, `SIGUSR2`, `SIGPIPE`, `SIGQUIT`, `SIGKILL`.** Python's
-   `signal` module raises `AttributeError` at import time if you reference
-   them on Windows. Use `getattr(signal, "SIGKILL", signal.SIGTERM)` or
-   gate the whole block behind a platform check. `loop.add_signal_handler`
-   raises `NotImplementedError` on Windows — always catch it.
-
-7. **Path separators.** Use `pathlib.Path` instead of string concatenation
-   with `/`. Forward slashes work almost everywhere on Windows, but
-   `subprocess.run(["cmd.exe", "/c", ...])` and other shell contexts can
-   require backslashes — convert with `str(path)` at the subprocess boundary,
-   not inside Python logic.
-
-8. **Symlinks need elevated privileges on Windows** (unless Developer Mode is
-   on). Tests that create symlinks need `@pytest.mark.skipif(sys.platform ==
-   "win32", reason="Symlinks require elevated privileges on Windows")`.
-
-9. **POSIX file modes (0o600, 0o644, etc.) are NOT enforced on NTFS** by
-   default. Tests that assert on `stat().st_mode & 0o777` must skip on
-   Windows — the concept doesn't translate. Use ACLs (`icacls`, `pywin32`)
-   for Windows secret-file protection if needed.
-
-10. **Detached background daemons on Windows need `pythonw.exe`, NOT
-    `python.exe`.** `python.exe` always allocates or attaches to a console,
-    which makes it vulnerable to `CTRL_C_EVENT` broadcasts from any sibling
-    process. `pythonw.exe` is the no-console variant. Combine with
-    `CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP |
-    CREATE_BREAKAWAY_FROM_JOB` in `subprocess.Popen(creationflags=...)`.
-    See `hermes_cli/gateway_windows.py::_spawn_detached` for the reference
-    implementation.
-
-11. **`subprocess.Popen` with `.cmd` or `.bat` shims needs `shutil.which`
-    to resolve.** Passing `"agent-browser"` to `Popen` on Windows finds
-    the extensionless POSIX shebang shim in `node_modules/.bin/`, which
-    `CreateProcessW` can't execute — you'll get `WinError 193 "not a valid
-    Win32 application"`. Use `shutil.which("agent-browser", path=local_bin)`
-    which honors PATHEXT and picks the `.CMD` variant on Windows.
-
-12. **Don't use shell shebangs as a way to run Python.** `#!/usr/bin/env
-    python` only works when the file is executed through a Unix shell.
-    `subprocess.run(["./myscript.py"])` on Windows fails even if the file
-    has a shebang line. Always invoke Python explicitly:
-    `[sys.executable, "myscript.py"]`.
-
-13. **Shell commands in installers.** If you change `scripts/install.sh`,
-    make the equivalent change in `scripts/install.ps1`. The two scripts
-    are the canonical example of "works on Linux does not mean works on
-    Windows" and have drifted multiple times — keep them in lockstep.
-
-14. **Known paths that are OneDrive-redirected on Windows:** Desktop,
-    Documents, Pictures, Videos. The "real" path when OneDrive Backup is
-    enabled is `%USERPROFILE%\OneDrive\Desktop` (etc.), NOT
-    `%USERPROFILE%\Desktop` (which exists as an empty husk). Resolve the
-    real location via `ctypes` + `SHGetKnownFolderPath` or by reading the
-    `Shell Folders` registry key — never assume `~/Desktop`.
-
-15. **CRLF vs LF in generated scripts.** Windows `cmd.exe` and `schtasks`
-    parse line-by-line; mixed or LF-only line endings can break multi-line
-    `.cmd` / `.bat` files. Use `open(path, "w", encoding="utf-8",
-    newline="\r\n")` — or `open(path, "wb")` + explicit bytes — when
-    generating scripts Windows will execute.
-
-16. **Two different quoting schemes in one command line.** `subprocess.run
-    (["schtasks", "/TR", some_cmd])` → schtasks itself parses `/TR`, AND
-    the `some_cmd` string is re-parsed by `cmd.exe` when the task fires.
-    Different parsers, different escape rules. Use two separate quoting
-    helpers and never cross them. See `hermes_cli/gateway_windows.py::
-    _quote_cmd_script_arg` and `_quote_schtasks_arg` for the reference
-    pair.
-
-### Testing cross-platform
-
-Tests that use POSIX-only syscalls need a skip marker. Common ones:
- Symlinks → `@pytest.mark.skipif(sys.platform == "win32", ...)`
- `0o600` file modes → `@pytest.mark.skipif(sys.platform.startswith("win"), ...)`
- `signal.SIGALRM` → Unix-only (see `tests/conftest.py::_enforce_test_timeout`)
- `os.setsid` / `os.fork` → Unix-only
- Live Winsock / Windows-specific regression tests →
-  `@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")`
-
-If you monkeypatch `sys.platform` for cross-platform tests, also patch
-`platform.system()` / `platform.release()` / `platform.mac_ver()` — each
-re-reads the real OS independently, so half-patched tests still route
-through the wrong branch on a Windows runner.
+5. **Shell commands in installers.** If you change `scripts/install.sh`, check if the equivalent change is needed in `scripts/install.ps1`.

 ---

@@ -886,47 +579,6 @@ Hermes has terminal access. Security matters.

 If your PR affects security, note it explicitly in the description.

-### Dependency pinning policy (supply chain hardening)
-
-After the [litellm supply chain compromise](https://github.com/BerriAI/litellm/issues/24512) in March 2026 and the [Mini Shai-Hulud worm campaign](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) in May 2026, all dependencies must follow these rules:
-
-| Source type | Required treatment | Rationale |
-|---|---|---|
-| **PyPI package** | `>=floor,<next_major` | PyPI versions are immutable once published, but new versions can be pushed into your range. A `<next_major` ceiling stops a 1.x install from upgrading to a malicious 2.0.0. |
-| **Git URL** (atroposlib, tinker, yc-bench, Baileys) | Full commit SHA | Branches and tags are mutable refs; SHA is content-addressed. |
-| **GitHub Actions** | Full commit SHA + version comment | Action tags are mutable refs (e.g. tj-actions/changed-files March 2025). Pin as `uses: owner/action@<sha>  # vX.Y.Z` |
-| **CI-only pip installs** | `==exact` | Hermetic CI builds; churn is acceptable. |
-
-**Every new PyPI dependency in a PR must have a `<next_major` upper bound.** PRs adding unbounded `>=X.Y.Z` specs will be rejected by reviewers. The `supply-chain-audit.yml` CI workflow also flags dependency manifest changes for manual review.
-
-**How to determine the ceiling:**
- If the package is at version `1.x.y`, use `<2`.
- If the package is at version `0.x.y` (pre-1.0), use `<0.(current_minor + 2)` — e.g. if current is `0.29.x`, use `<0.32`. This gives ~2 minor versions of headroom while keeping the window small enough that a hostile takeover version is unlikely to land inside it.
- Exception: packages with very stable APIs (e.g. `aiohttp-socks`) can use `<1` at reviewer discretion.
-
-**Examples:**
-```toml
-# ✅ Correct — post-1.0
-"openai>=2.21.0,<3"
-"pydantic>=2.12.5,<3"
-
-# ✅ Correct — pre-1.0 (tight minor window)
-"asyncpg>=0.29,<0.32"
-"aiosqlite>=0.20,<0.23"
-"hindsight-client>=0.4.22,<0.5"
-
-# ❌ Rejected — no upper bound
-"some-package>=1.2.3"
-
-# ❌ Rejected — too tight (blocks legitimate patches)
-"some-package==1.2.3"
-
-# ❌ Rejected — too loose for pre-1.0 (allows 80 minor versions)
-"some-package>=0.20,<1"
-```
-
-**Reference PRs:** #2796 (litellm removal), #2810 (upper bounds pass), #9801 (SHA pinning + supply-chain-audit CI).
-
 ---

 ## Pull Request Process
@@ -943,9 +595,9 @@ refactor/description   # Code restructuring

 ### Before submitting

-1. **Run tests**: `scripts/run_tests.sh` (recommended; same as CI) or `pytest tests/ -v` with the project venv activated
+1. **Run tests**: `pytest tests/ -v`
 2. **Test manually**: Run `hermes` and exercise the code path you changed
-3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider macOS, Linux, and WSL2
+3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider Windows and macOS
 4. **Keep PRs focused**: One logical change per PR. Don't mix a bug fix with a refactor with a new feature.

 ### PR description
@@ -1,363 +0,0 @@
-FROM ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie@sha256:b3c543b6c4f23a5f2df22866bd7857e5d304b67a564f4feab6ac22044dde719b AS uv_source
-# Node 22 LTS source stage. Debian trixie's bundled nodejs is pinned to 20.x
-# which reached EOL in April 2026 — we copy node + npm + corepack from the
-# upstream node:22 image instead so we can stay on a supported LTS without
-# waiting for Debian 14 (forky, ~mid-2027).  Bookworm-based slim image used
-# so the produced binary links against glibc 2.36, which runs cleanly on
-# our Debian 13 (trixie, glibc 2.41) runtime.  Bumping to a new Node major
-# is a one-line ARG change; see #4977.
-FROM node:22-bookworm-slim@sha256:7af03b14a13c8cdd38e45058fd957bf00a72bbe17feac43b1c15a689c029c732 AS node_source
-FROM debian:13.4
-
-# Disable Python stdout buffering to ensure logs are printed immediately.
-# Do not write .pyc files at runtime: /opt/hermes is immutable in the
-# published container and writable state belongs under /opt/data.
-ENV PYTHONUNBUFFERED=1
-ENV PYTHONDONTWRITEBYTECODE=1
-
-# Store Playwright browsers outside the volume mount so the build-time
-# install survives the /opt/data volume overlay at runtime.
-ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
-
-# Install system dependencies in one layer, clear APT cache.
-# tini was previously PID 1 to reap orphaned zombie processes (MCP stdio
-# subprocesses, git, bun, etc.) that would otherwise accumulate when hermes
-# ran as PID 1. See #15012. Phase 2 of the s6-overlay supervision plan
-# replaces tini with s6-overlay's /init (PID 1 = s6-svscan), which reaps
-# zombies non-blockingly on SIGCHLD and additionally supervises the main
-# hermes process, the dashboard, and per-profile gateways.
-RUN apt-get -o Acquire::Retries=3 update && \
-    apt-get -o Acquire::Retries=3 install -y --no-install-recommends \
-    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc g++ make cmake python3-dev python3-venv libffi-dev libolm-dev procps git openssh-client docker-cli xz-utils && \
-    rm -rf /var/lib/apt/lists/*
-
-# ---------- s6-overlay install ----------
-# s6-overlay provides supervision for the main hermes process, the dashboard,
-# and per-profile gateways. /init becomes PID 1 below — see ENTRYPOINT.
-#
-# Multi-arch: BuildKit auto-populates TARGETARCH (amd64 / arm64). s6-overlay
-# uses tarball names keyed on the kernel arch string (x86_64 / aarch64), so
-# we map between them inline. The noarch + symlinks tarballs are
-# architecture-independent and reused as-is.
-#
-# We use `curl` instead of `ADD` for ALL three tarballs: `ADD` evaluates its
-# URL at parse time (no ARG / TARGETARCH substitution) and — critically for
-# CI reliability — cannot retry, so a single GitHub-release CDN blip fails
-# the whole 15-45 min build. curl -fsSL --retry 3 self-heals those blips,
-# and every tarball is still checksum-verified below before extraction.
-ARG TARGETARCH
-ARG S6_OVERLAY_VERSION=3.2.3.0
-ARG S6_OVERLAY_NOARCH_SHA256=b720f9d9340efc8bb07528b9743813c836e4b02f8693d90241f047998b4c53cf
-ARG S6_OVERLAY_X86_64_SHA256=a93f02882c6ed46b21e7adb5c0add86154f01236c93cd82c7d682722e8840563
-ARG S6_OVERLAY_AARCH64_SHA256=0952056ff913482163cc30e35b2e944b507ba1025d78f5becbb89367bf344581
-ARG S6_OVERLAY_SYMLINKS_SHA256=a60dc5235de3ecbcf874b9c1f18d73263ab99b289b9329aa950e8729c4789f0e
-RUN set -eu; \
-    case "${TARGETARCH:-amd64}" in \
-        amd64) s6_arch="x86_64"; s6_arch_sha="${S6_OVERLAY_X86_64_SHA256}" ;; \
-        arm64) s6_arch="aarch64"; s6_arch_sha="${S6_OVERLAY_AARCH64_SHA256}" ;; \
-        *) echo "Unsupported TARGETARCH=${TARGETARCH} for s6-overlay" >&2; exit 1 ;; \
-    esac; \
-    base="https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}"; \
-    curl -fsSL --retry 3 -o /tmp/s6-overlay-noarch.tar.xz \
-        "${base}/s6-overlay-noarch.tar.xz"; \
-    curl -fsSL --retry 3 -o /tmp/s6-overlay-symlinks-noarch.tar.xz \
-        "${base}/s6-overlay-symlinks-noarch.tar.xz"; \
-    curl -fsSL --retry 3 -o /tmp/s6-overlay-arch.tar.xz \
-        "${base}/s6-overlay-${s6_arch}.tar.xz"; \
-    { \
-        printf '%s  %s\n' "${S6_OVERLAY_NOARCH_SHA256}" /tmp/s6-overlay-noarch.tar.xz; \
-        printf '%s  %s\n' "${s6_arch_sha}" /tmp/s6-overlay-arch.tar.xz; \
-        printf '%s  %s\n' "${S6_OVERLAY_SYMLINKS_SHA256}" /tmp/s6-overlay-symlinks-noarch.tar.xz; \
-    } > /tmp/s6-overlay.sha256; \
-    sha256sum -c /tmp/s6-overlay.sha256; \
-    tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz; \
-    tar -C / -Jxpf /tmp/s6-overlay-arch.tar.xz; \
-    tar -C / -Jxpf /tmp/s6-overlay-symlinks-noarch.tar.xz; \
-    rm /tmp/s6-overlay-*.tar.xz /tmp/s6-overlay.sha256
-
-# #34192 / #66679: backward-compat shim for orchestration templates that
-# still reference the legacy /usr/bin/tini entrypoint (Hostinger's
-# 'Hermes WebUI' catalog, NAS compose projects that preserve an old
-# entrypoint on image update, etc.). A plain symlink to /init made the
-# path exist, but forwarded tini flags like `-g` into s6-overlay's
-# rc.init as the container CMD (`rc.init: 91: -g: not found`) and
-# boot-looped any `restart: unless-stopped` deploy. The shim strips the
-# tini CLI surface, then exec's /init + main-wrapper — see
-# docker/tini-shim.sh. Safe to drop once the affected catalogs are
-# updated.
-COPY --chmod=0755 docker/tini-shim.sh /usr/bin/tini
-
-# Non-root user for runtime; UID can be overridden via HERMES_UID at runtime
-RUN useradd -u 10000 -m -d /opt/data hermes
-
-COPY --chmod=0755 --from=uv_source /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
-
-# Node 22 LTS: copy the node binary plus the bundled npm + corepack JS
-# installs from the upstream image.  npm and npx are recreated as symlinks
-# because they're symlinks in the source image (and need to live on PATH).
-# See node_source stage at the top of the file for the version-bump
-# rationale (#4977).
-COPY --chmod=0755 --from=node_source /usr/local/bin/node /usr/local/bin/
-COPY --from=node_source /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
-COPY --from=node_source /usr/local/lib/node_modules/corepack /usr/local/lib/node_modules/corepack
-RUN ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
-    ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx && \
-    ln -sf /usr/local/lib/node_modules/corepack/dist/corepack.js /usr/local/bin/corepack
-
-WORKDIR /opt/hermes
-
-# ---------- Layer-cached dependency install ----------
-# Copy only package manifests first so npm install + Playwright are cached
-# unless the lockfiles themselves change.
-#
-# ui-tui/packages/hermes-ink/ is copied IN FULL (not just its manifests)
-# because it is referenced as a `file:` workspace dependency from
-# ui-tui/package.json.  Copying the tree up front lets npm resolve the
-# workspace to real content instead of stopping at a bare package.json.
-COPY package.json package-lock.json ./
-COPY web/package.json web/
-COPY ui-tui/package.json ui-tui/
-COPY ui-tui/packages/hermes-ink/ ui-tui/packages/hermes-ink/
-# apps/shared/ is copied IN FULL because web/package.json references it as a
-# `file:` workspace dependency (same pattern as hermes-ink above).
-COPY apps/shared/ apps/shared/
-
-# `npm_config_install_links=false` forces npm to install `file:` deps as
-# symlinks instead of copies.  This is the default since npm 10+, which is
-# what the image ships now (via the node:22 source stage).  We set it
-# explicitly anyway as defense-in-depth: the previous Debian-bundled npm
-# 9.x defaulted to install-as-copy, which produced a hidden
-# node_modules/.package-lock.json that permanently disagreed with the root
-# lock on the @hermes/ink entry, tripped the TUI launcher's
-# `_tui_need_npm_install()` check on every startup, and triggered a
-# runtime `npm install` that then failed with EACCES.  Keeping the env
-# guards against a future regression if the source npm version changes.
-ENV npm_config_install_links=false
-
-RUN npm install --prefer-offline --no-audit --fetch-retries=5 && \
-    for i in 1 2 3; do \
-        npx playwright install --with-deps chromium --only-shell && break || \
-        { [ "$i" = 3 ] && exit 1; echo "playwright install failed (attempt $i); retrying in 10s"; sleep 10; }; \
-    done && \
-    npm cache clean --force
-
-# ---------- Layer-cached Python dependency install ----------
-# Copy only pyproject.toml + uv.lock so the Python dep resolve + wheel
-# download + native-extension compile layer is cached unless those inputs
-# change.  Before this split the Python install sat after `COPY . .`, so
-# every source-only commit re-did ~4-5 min of dep work on cold builds.
-#
-# README.md is referenced by pyproject.toml's `readme =` field, but it's
-# excluded from the build context by .dockerignore's `*.md`.  uv's build
-# frontend stats the readme path during dep resolution, so we `touch` an
-# empty placeholder — the real README is restored by `COPY . .` below.
-#
-# `uv sync --frozen --no-install-project --extra all --extra messaging`
-# installs the deps reachable through the composite `[all]` extra
-# (handpicked set intended for the production image — excludes `[dev]`),
-# plus gateway messaging adapters that should work in the published image
-# without a first-boot lazy install.  We do NOT use `--all-extras`:
-# that would pull in `[rl]` (atroposlib + tinker + torch + wandb from
-# git), `[yc-bench]` (another git dep), and `[termux-all]` (Android
-# redundancy), none of which belong in the published container.
-#
-# Provider packages (anthropic, bedrock, azure-identity) are included
-# so Docker users can use these providers without requiring runtime
-# lazy-install access to PyPI (often blocked in containerized envs).
-#
-# The hindsight memory provider's client (hindsight-client) is baked in
-# for the same reason: it lazy-installs into /opt/hermes/.venv at first
-# use, which lives inside the (immutable) image layer rather than the
-# mounted /opt/data volume, so it is lost on every container recreate /
-# image update and recall/retain then fails with
-# `ModuleNotFoundError: No module named 'hindsight_client'` (#38128).
-#
-# The Matrix gateway's deps ([matrix] extra) are baked in because
-# python-olm (transitive via mautrix[encryption]) builds from source on
-# Python/image combinations without usable wheels.  The Docker image is
-# Linux-only, so keeping the native libolm/build-toolchain packages here
-# avoids the cross-platform failures that kept [matrix] out of [all]
-# while still making Matrix work in the published container. Fixes #30399.
-#
-# The editable link is created after the source copy below.
-COPY pyproject.toml uv.lock ./
-RUN touch ./README.md
-RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra anthropic --extra bedrock --extra azure-identity --extra hindsight --extra matrix
-
-# ---------- Frontend build (cached independently from Python source) ----------
-# Copy only the frontend source trees first so that Python-only changes don't
-# invalidate the (relatively slow) web + ui-tui build layer.
-COPY web/ web/
-COPY ui-tui/ ui-tui/
-COPY apps/shared/ apps/shared/
-RUN cd web && npm run build && \
-    cd ../ui-tui && npm run build
-
-# ---------- Source code ----------
-# .dockerignore excludes node_modules, so the installs above survive.
-# --link decouples this layer from parents for cache purposes; --chmod bakes
-# the final read-only permissions at copy time so we skip the separate
-# `chmod -R` pass that previously walked ~30k files across the venv +
-# node_modules + source (21s amd64 / 222s arm64 — #49113).  `a+rX,go-w`
-# gives the non-root hermes user read + traverse but no write; root retains
-# write so the build steps below don't need chmod u+w dances.
-COPY --link --chmod=a+rX,go-w . .
-
-# ---------- Permissions ----------
-# Link hermes-agent itself (editable). Deps are already installed in the
-# cached layer above; `--no-deps` makes this a fast egg-link creation with no
-# resolution or downloads.
-RUN uv pip install --no-cache-dir --no-deps -e "."
-
-# Wire the exec shim and install-method stamp.  Files under /opt/hermes are
-# already root-owned (COPY, uv sync, npm install all run as root) and
-# read-only for the hermes user (go-w from the --chmod above).
-
-USER root
-RUN mkdir -p /opt/hermes/bin && \
-    cp /opt/hermes/docker/hermes-exec-shim.sh /opt/hermes/bin/hermes && \
-    chmod 0755 /opt/hermes/bin/hermes && \
-    printf 'docker\n' > /opt/hermes/.install_method
-# The ``.install_method`` stamp is baked next to the running code (the install
-# tree), NOT into $HERMES_HOME. $HERMES_HOME (/opt/data) is a shared data
-# volume that is commonly bind-mounted from the host and even shared with a
-# host-side Desktop/CLI install; stamping it at boot used to clobber that
-# host install's marker and wrongly block its ``hermes update``. A code-scoped
-# stamp is read first by detect_install_method() and is immune to the share.
-# Start as root so the s6-overlay stage2 hook can usermod/groupmod and chown
-# the data volume. Each supervised service then drops to the hermes user via
-# `s6-setuidgid hermes` in its run script. If HERMES_UID is unset, services
-# run as the default hermes user (UID 10000).
-
-# ---------- Bake build-time git revision ----------
-# .dockerignore excludes .git, so `git rev-parse HEAD` from inside the
-# container always returns nothing — meaning `hermes dump` reports
-# "(unknown)" and the startup banner drops its `· upstream <sha>` suffix.
-# That makes support triage from container bug reports impossible:
-# we can't tell which commit the user is actually running.
-#
-# Fix: write the commit SHA passed via the HERMES_GIT_SHA build-arg to
-# /opt/hermes/.hermes_build_sha at build time, and have
-# hermes_cli/build_info.py read it at runtime.  Both `hermes dump` and
-# banner.get_git_banner_state() try the baked SHA first, then fall back
-# to live `git rev-parse` for source installs (unchanged behaviour).
-#
-# The arg is optional — local `docker build` without --build-arg simply
-# omits the file, and the runtime falls back to live-git lookup.  CI
-# (.github/workflows/docker.yml) passes ${{ github.sha }} so
-# every published image has it.
-ARG HERMES_GIT_SHA=
-RUN if [ -n "${HERMES_GIT_SHA}" ]; then \
-        printf '%s\n' "${HERMES_GIT_SHA}" > /opt/hermes/.hermes_build_sha; \
-    fi
-
-# ---------- s6-overlay service wiring ----------
-# Static services declared at build time: main-hermes + dashboard.
-# Per-profile gateway services are registered dynamically at runtime by
-# the profile create/delete hooks (Phase 4); they live under
-# /run/service/ (tmpfs) and are reconciled on container restart by
-# /etc/cont-init.d/02-reconcile-profiles (Phase 4 Task 4.0).
-COPY docker/s6-rc.d/ /etc/s6-overlay/s6-rc.d/
-
-# stage2-hook handles UID/GID remap, volume chown, config seeding,
-# skills sync — all the work the old entrypoint.sh did before
-# `exec hermes`. Wired in as cont-init.d/01- so it
-# runs before user services start.
-#
-# 02-reconcile-profiles re-creates per-profile gateway s6 service
-# slots from $HERMES_HOME/profiles/<name>/ after a container restart
-# (the /run/service/ scandir is tmpfs and wiped on restart). Phase 4.
-RUN mkdir -p /etc/cont-init.d && \
-    printf '#!/command/with-contenv sh\nexec /opt/hermes/docker/stage2-hook.sh\n' \
-        > /etc/cont-init.d/01-hermes-setup && \
-    chmod +x /etc/cont-init.d/01-hermes-setup
-COPY --chmod=0755 docker/cont-init.d/015-supervise-perms /etc/cont-init.d/015-supervise-perms
-COPY --chmod=0755 docker/cont-init.d/02-reconcile-profiles /etc/cont-init.d/02-reconcile-profiles
-
-# ---------- Runtime ----------
-ENV HERMES_WEB_DIST=/opt/hermes/hermes_cli/web_dist
-# Point the TUI launcher at the prebuilt bundle baked at build time (Layer 8:
-# `ui-tui && npm run build`). This makes _make_tui_argv take the prebuilt-bundle
-# fast path (`node --expose-gc /opt/hermes/ui-tui/dist/entry.js`) and skip the
-# _tui_need_npm_install / runtime `npm install` branch entirely — exactly the
-# nix/packaged-release path the launcher was designed for.
-#
-# Why this is required (not just an optimization): the root package-lock.json
-# describes the WHOLE monorepo workspace set (root + web + ui-tui + apps/*),
-# but the image only installs root/web/ui-tui (apps/* — the desktop app — is
-# never `npm install`ed here). So the actualized node_modules permanently
-# disagrees with the canonical lock, _tui_need_npm_install() returns True on
-# every launch, and the runtime `npm install` it triggers (a) can never
-# converge against the partial monorepo and (b) races itself across concurrent
-# embedded-chat (/api/pty) connections → ENOTEMPTY → the chat tab dies with a
-# 502 / "[session ended]". Pointing at the prebuilt bundle sidesteps the whole
-# check. (A separate launcher hardening is tracked independently.)
-ENV HERMES_TUI_DIR=/opt/hermes/ui-tui
-ENV HERMES_HOME=/opt/data
-ENV HERMES_WRITE_SAFE_ROOT=/opt/data
-ENV HERMES_DISABLE_LAZY_INSTALLS=1
-# The published image seals /opt/hermes (root-owned, read-only) so a runtime
-# lazy install can't mutate the agent's own venv and brick it. But opt-in
-# backends (Firecrawl web search, Exa, Feishu, …) keep their SDKs in
-# tools/lazy_deps.py — deliberately NOT baked into [all] (see pyproject.toml
-# policy 2026-05-12: one quarantined release must not break every install).
-# Redirect those lazy installs to a writable dir on the durable data volume.
-# lazy_deps appends this dir to the END of sys.path, so a package installed
-# here can only ADD modules — it can never shadow or downgrade a core module,
-# so the sealed-venv guarantee holds even with installs re-enabled. The dir
-# is seeded + chowned to the hermes user by docker/stage2-hook.sh and lives
-# on the /opt/data volume, so it persists across container recreates / image
-# updates (an ABI stamp invalidates it if a rebuild bumps the interpreter).
-ENV HERMES_LAZY_INSTALL_TARGET=/opt/data/lazy-packages
-
-# `docker exec` privilege-drop shim. When operators run
-# `docker exec <c> hermes ...` they default to root, and any file the
-# command writes under $HERMES_HOME (auth.json, .env, config.yaml) ends
-# up root-owned and unreadable to the supervised gateway (UID 10000).
-# The shim lives at /opt/hermes/bin/hermes, sits earliest on PATH, and
-# transparently re-exec's the real venv binary via `s6-setuidgid hermes`
-# when invoked as root. Non-root callers (supervised processes,
-# `--user hermes`, etc.) hit the short-circuit path with no overhead.
-# Recursion is impossible because the shim exec's the venv binary by
-# absolute path (/opt/hermes/.venv/bin/hermes). See the shim source for
-# the opt-out env var (HERMES_DOCKER_EXEC_AS_ROOT=1).
-
-# Pre-s6 entrypoint.sh did `source .venv/bin/activate` which exported
-# the venv bin onto PATH; Architecture B's main-wrapper.sh does the
-# same for the container's main process, but `docker exec` and our
-# cont-init.d scripts don't pass through the wrapper. Expose the venv
-# bin globally so `docker exec <container> hermes ...` and any
-# subprocess that doesn't activate the venv first still find hermes.
-#
-# /opt/hermes/bin is prepended ahead of the venv so the privilege-drop
-# shim wins PATH resolution. The shim's last act is to exec the venv
-# binary by absolute path, so this PATH ordering is transparent to
-# every other consumer.
-ENV PATH="/opt/hermes/bin:/opt/hermes/.venv/bin:/opt/data/.local/bin:${PATH}"
-RUN mkdir -p /opt/data
-VOLUME [ "/opt/data" ]
-
-# s6-overlay's /init is PID 1. It sets up the supervision tree, runs
-# /etc/cont-init.d/* (our stage2 hook), starts s6-rc services
-# declared in /etc/s6-overlay/s6-rc.d/, then exec's its remaining
-# argv as the container's "main program" with stdin/stdout/stderr
-# inherited (this is what makes interactive --tui work). When the
-# main program exits, /init begins stage 3 shutdown and the container
-# exits with the program's exit code. Replaces tini — see Phase 2 of
-# docs/plans/2026-05-07-s6-overlay-dynamic-subagent-gateways.md.
-#
-# We use the ENTRYPOINT+CMD split rather than CMD alone so the
-# wrapper is prepended to user-supplied args automatically:
-#
-#   docker run <image>                  → /init main-wrapper.sh   (CMD default)
-#   docker run <image> chat -q "hi"     → /init main-wrapper.sh chat -q hi
-#   docker run <image> sleep infinity   → /init main-wrapper.sh sleep infinity
-#   docker run <image> --tui            → /init main-wrapper.sh --tui
-#
-# main-wrapper.sh handles arg routing (bare-exec vs. hermes
-# subcommand vs. no-args), drops to the hermes user via s6-setuidgid,
-# and exec's the final program so its exit code becomes the container
-# exit code. Without the wrapper-as-ENTRYPOINT, leading-dash args
-# like `--version` would be intercepted by /init's POSIX shell.
-ENTRYPOINT [ "/init", "/opt/hermes/docker/main-wrapper.sh" ]
-CMD [ ]
@@ -1,14 +0,0 @@
-graft skills
-graft optional-skills
-graft optional-mcps
-graft hermes_cli/web_dist
-graft locales
-# Bundled plugin manifests (plugin.yaml / plugin.yml). Without these the
-# PluginManager scan (hermes_cli/plugins.py) finds zero plugins on installs
-# built from the sdist (e.g. Homebrew, downstream packagers). package-data
-# below covers the wheel; this covers the sdist. See #34034 / #28149.
-recursive-include plugins plugin.yaml plugin.yml
-# Gateway assets include images plus YAML catalogs such as status_phrases.yaml.
-recursive-include gateway/assets *
-global-exclude __pycache__
-global-exclude *.py[cod]
@@ -1,220 +0,0 @@
-<p align="center">
-  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
-</p>
-
-# Hermes Agent ☤
-<p align="center">
-  <a href="https://hermes-agent.nousresearch.com/">Hermes Agent</a> | <a href="https://hermes-agent.nousresearch.com/">Hermes Desktop</a>
-</p>
-<p align="center">
-  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentación"></a>
-  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
-  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/Licencia-MIT-green?style=for-the-badge" alt="Licencia: MIT"></a>
-  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Creado%20por-Nous%20Research-blueviolet?style=for-the-badge" alt="Creado por Nous Research"></a>
-  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-blue?style=for-the-badge" alt="English"></a>
-  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
-  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
-</p>
-
-**El agente de IA con mejora continua creado por [Nous Research](https://nousresearch.com).** Es el único agente con un bucle de aprendizaje integrado: crea habilidades a partir de la experiencia, las mejora durante el uso, se impulsa a sí mismo a persistir el conocimiento, busca en sus propias conversaciones pasadas y construye un modelo cada vez más profundo de quién eres a lo largo de las sesiones. Ejecútalo en un VPS de $5, un clúster de GPUs o infraestructura sin servidor que cuesta casi nada cuando está inactivo. No está atado a tu laptop — habla con él desde Telegram mientras trabaja en una VM en la nube.
-
-Usa cualquier modelo que quieras — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (más de 200 modelos), [NovitaAI](https://novita.ai), [NVIDIA NIM](https://build.nvidia.com) (Nemotron), [Xiaomi MiMo](https://platform.xiaomimimo.com), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), [Hugging Face](https://huggingface.co), OpenAI, o tu propio endpoint. Cambia con `hermes model` — sin cambios de código, sin dependencias.
-
-<table>
-<tr><td><b>Una interfaz de terminal real</b></td><td>TUI completa con edición multilínea, autocompletado de comandos, historial de conversaciones, interrupción y redirección, y salida de herramientas en streaming.</td></tr>
-<tr><td><b>Vive donde tú vives</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal y CLI — todo desde un único proceso gateway. Transcripción de notas de voz, continuidad de conversación entre plataformas.</td></tr>
-<tr><td><b>Un bucle de aprendizaje cerrado</b></td><td>Memoria curada por el agente con recordatorios periódicos. Creación autónoma de habilidades tras tareas complejas. Las habilidades mejoran solas durante el uso. Búsqueda FTS5 de sesiones con resumención por LLM para recuperación entre sesiones. Modelado de usuario dialéctico <a href="https://github.com/plastic-labs/honcho">Honcho</a>. Compatible con el estándar abierto de <a href="https://agentskills.io">agentskills.io</a>.</td></tr>
-<tr><td><b>Automatizaciones programadas</b></td><td>Planificador cron integrado con entrega a cualquier plataforma. Informes diarios, copias de seguridad nocturnas, auditorías semanales — todo en lenguaje natural, ejecutándose de forma autónoma.</td></tr>
-<tr><td><b>Delega y paraleliza</b></td><td>Lanza subagentes aislados para flujos de trabajo paralelos. Escribe scripts de Python que llaman a herramientas vía RPC, convirtiendo pipelines de múltiples pasos en turnos de coste cero de contexto.</td></tr>
-<tr><td><b>Funciona en cualquier lugar, no solo en tu laptop</b></td><td>Seis backends de terminal — local, Docker, SSH, Singularity, Modal y Daytona. Daytona y Modal ofrecen persistencia sin servidor — el entorno de tu agente hiberna cuando está inactivo y se activa bajo demanda, costando casi nada entre sesiones. Ejecútalo en un VPS de $5 o un clúster de GPUs.</td></tr>
-<tr><td><b>Listo para investigación</b></td><td>Generación de trayectorias en lote, compresión de trayectorias para entrenar la próxima generación de modelos de llamadas a herramientas.</td></tr>
-</table>
-
---
-
-## Instalación rápida
-
-### Linux, macOS, WSL2, Termux
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-```
-
-### Windows (nativo, PowerShell)
-
-> **Nota:** En Windows nativo, Hermes funciona sin WSL — la CLI, el gateway, la TUI y las herramientas funcionan de forma nativa. Si prefieres usar WSL2, el comando de Linux/macOS de arriba también funciona allí. ¿Encontraste un error? Por favor [crea un issue](https://github.com/NousResearch/hermes-agent/issues).
-
-Ejecuta esto en PowerShell:
-
-```powershell
-iex (irm https://hermes-agent.nousresearch.com/install.ps1)
-```
-
-El instalador se encarga de todo: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **y un Git Bash portátil** (MinGit, descomprimido en `%LOCALAPPDATA%\hermes\git` — no requiere administrador, completamente aislado de cualquier instalación de Git del sistema). Hermes usa este Git Bash incluido para ejecutar comandos de shell.
-
-Si ya tienes Git instalado, el instalador lo detecta y lo usa en su lugar. De lo contrario, una descarga de ~45MB de MinGit es todo lo que necesitas — no tocará ni interferirá con ningún Git del sistema.
-
-> **Android / Termux:** La ruta manual probada está documentada en la [guía de Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux). En Termux, Hermes instala el extra `.[termux]` curado porque el extra completo `.[all]` actualmente incluye dependencias de voz incompatibles con Android.
->
-> **Windows:** Windows nativo es totalmente compatible — el comando de PowerShell de arriba instala todo. Si prefieres usar WSL2, el comando de Linux también funciona allí. La instalación nativa de Windows se encuentra en `%LOCALAPPDATA%\hermes`; WSL2 instala en `~/.hermes` como en Linux.
-
-Después de la instalación:
-
-```bash
-source ~/.bashrc    # recargar shell (o: source ~/.zshrc)
-hermes              # ¡empieza a chatear!
-```
-
---
-
-## Primeros pasos
-
-```bash
-hermes              # CLI interactiva — inicia una conversación
-hermes model        # Elige tu proveedor y modelo LLM
-hermes tools        # Configura qué herramientas están habilitadas
-hermes config set   # Establece valores de configuración individuales
-hermes gateway      # Inicia el gateway de mensajería (Telegram, Discord, etc.)
-hermes setup        # Ejecuta el asistente de configuración completo
-hermes claw migrate # Migra desde OpenClaw (si vienes de OpenClaw)
-hermes update       # Actualiza a la última versión
-hermes doctor       # Diagnostica cualquier problema
-```
-
-📖 **[Documentación completa →](https://hermes-agent.nousresearch.com/docs/)**
-
---
-
-## Evita la colección de claves API — Nous Portal
-
-Hermes funciona con cualquier proveedor que quieras — eso no cambiará. Pero si prefieres no recopilar cinco claves API separadas para el modelo, búsqueda web, generación de imágenes, TTS y un navegador en la nube, **[Nous Portal](https://portal.nousresearch.com)** las cubre todas bajo una sola suscripción:
-
- **Más de 300 modelos** — elige cualquiera con `/model <nombre>`
- **Tool Gateway** — búsqueda web (Firecrawl), generación de imágenes (FAL), texto a voz (OpenAI), navegador en la nube (Browser Use), todo enrutado a través de tu suscripción. Sin cuentas adicionales.
-
-Un comando desde una instalación nueva:
-
-```bash
-hermes setup --portal
-```
-
-Esto te autentica vía OAuth, establece Nous como tu proveedor y activa el Tool Gateway. Comprueba qué está conectado en cualquier momento con `hermes portal info`. Detalles completos en la [página de documentación del Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
-
-Puedes seguir usando tus propias claves por herramienta cuando quieras — el gateway es por backend, no todo o nada.
-
---
-
-## Referencia rápida: CLI vs Mensajería
-
-Hermes tiene dos puntos de entrada: inicia la interfaz de terminal con `hermes`, o ejecuta el gateway y habla con él desde Telegram, Discord, Slack, WhatsApp, Signal o Email. Una vez en una conversación, muchos comandos de barra son compartidos entre ambas interfaces.
-
-| Acción                              | CLI                                           | Plataformas de mensajería                                                         |
-| ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
-| Empezar a chatear                   | `hermes`                                      | Ejecuta `hermes gateway setup` + `hermes gateway start`, luego envía un mensaje al bot |
-| Nueva conversación                  | `/new` o `/reset`                             | `/new` o `/reset`                                                                 |
-| Cambiar modelo                      | `/model [proveedor:modelo]`                   | `/model [proveedor:modelo]`                                                       |
-| Establecer personalidad             | `/personality [nombre]`                       | `/personality [nombre]`                                                           |
-| Reintentar o deshacer último turno  | `/retry`, `/undo`                             | `/retry`, `/undo`                                                                 |
-| Comprimir contexto / ver uso        | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]`                                         |
-| Explorar habilidades                | `/skills` o `/<nombre-habilidad>`             | `/<nombre-habilidad>`                                                             |
-| Interrumpir trabajo actual          | `Ctrl+C` o enviar un nuevo mensaje            | `/stop` o enviar un nuevo mensaje                                                 |
-| Estado específico de plataforma     | `/platforms`                                  | `/status`, `/sethome`                                                             |
-
-Para las listas de comandos completas, consulta la [guía de CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli) y la [guía del Gateway de Mensajería](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).
-
---
-
-## Documentación
-
-Toda la documentación está en **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
-
-| Sección                                                                                             | Contenido                                                    |
-| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| [Inicio rápido](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)              | Instalar → configurar → primera conversación en 2 minutos   |
-| [Uso de CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                             | Comandos, atajos de teclado, personalidades, sesiones        |
-| [Configuración](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)               | Archivo de configuración, proveedores, modelos, todas las opciones |
-| [Gateway de Mensajería](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)           | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant   |
-| [Seguridad](https://hermes-agent.nousresearch.com/docs/user-guide/security)                        | Aprobación de comandos, emparejamiento por DM, aislamiento en contenedor |
-| [Herramientas y Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)   | Más de 40 herramientas, sistema de toolsets, backends de terminal |
-| [Sistema de Habilidades](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)   | Memoria procedimental, Skills Hub, creación de habilidades   |
-| [Memoria](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)                   | Memoria persistente, perfiles de usuario, mejores prácticas  |
-| [Integración MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)              | Conecta cualquier servidor MCP para capacidades extendidas   |
-| [Programación Cron](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)           | Tareas programadas con entrega a plataforma                  |
-| [Archivos de Contexto](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Contexto de proyecto que da forma a cada conversación      |
-| [Arquitectura](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)            | Estructura del proyecto, bucle del agente, clases principales |
-| [Contribuir](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)              | Configuración de desarrollo, proceso de PR, estilo de código |
-| [Referencia de CLI](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)             | Todos los comandos y flags                                   |
-| [Variables de Entorno](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Referencia completa de variables de entorno                  |
-
---
-
-## Migración desde OpenClaw
-
-Si vienes de OpenClaw, Hermes puede importar automáticamente tu configuración, memorias, habilidades y claves API.
-
-**Durante la configuración inicial:** El asistente de configuración (`hermes setup`) detecta automáticamente `~/.openclaw` y ofrece migrar antes de que comience la configuración.
-
-**En cualquier momento después de instalar:**
-
-```bash
-hermes claw migrate              # Migración interactiva (preset completo)
-hermes claw migrate --dry-run    # Vista previa de qué se migraría
-hermes claw migrate --preset user-data   # Migrar sin secretos
-hermes claw migrate --overwrite  # Sobreescribir conflictos existentes
-```
-
-Qué se importa:
-
- **SOUL.md** — archivo de personalidad
- **Memorias** — entradas de MEMORY.md y USER.md
- **Habilidades** — habilidades creadas por el usuario → `~/.hermes/skills/openclaw-imports/`
- **Lista de comandos permitidos** — patrones de aprobación
- **Configuración de mensajería** — configuración de plataformas, usuarios permitidos, directorio de trabajo
- **Claves API** — secretos en lista de permitidos (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
- **Assets de TTS** — archivos de audio del espacio de trabajo
- **Instrucciones del espacio de trabajo** — AGENTS.md (con `--workspace-target`)
-
-Consulta `hermes claw migrate --help` para todas las opciones, o usa la habilidad `openclaw-migration` para una migración guiada interactiva por el agente con vistas previas de dry-run.
-
---
-
-## Contribuir
-
-¡Las contribuciones son bienvenidas! Consulta la [Guía de Contribución](CONTRIBUTING.es.md) para la configuración del desarrollo, el estilo de código y el proceso de PR.
-
-Inicio rápido para colaboradores — clona y comienza con `setup-hermes.sh`:
-
-```bash
-git clone https://github.com/NousResearch/hermes-agent.git
-cd hermes-agent
-./setup-hermes.sh     # instala uv, crea venv, instala .[all], enlaza ~/.local/bin/hermes
-./hermes              # detecta automáticamente el venv, no necesitas hacer `source` primero
-```
-
-Ruta manual (equivalente a lo anterior):
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv venv .venv --python 3.11
-source .venv/bin/activate
-uv pip install -e ".[all,dev]"
-scripts/run_tests.sh
-```
-
---
-
-## Comunidad
-
- 💬 [Discord](https://discord.gg/NousResearch)
- 📚 [Skills Hub](https://agentskills.io)
- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — Servidor MCP de control de escritorio Linux para Hermes y otros hosts MCP, con árboles de accesibilidad AT-SPI, entrada Wayland/X11, capturas de pantalla y targeting de ventanas del compositor.
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Puente WeChat comunitario: Ejecuta Hermes Agent y OpenClaw en la misma cuenta de WeChat.
-
---
-
-## Licencia
-
-MIT — ver [LICENSE](LICENSE).
-
-Creado por [Nous Research](https://nousresearch.com).
@@ -3,22 +3,17 @@
 </p>

 # Hermes Agent ☤
-<p align="center">
-  <a href="https://hermes-agent.nousresearch.com/">Hermes Agent</a> | <a href="https://hermes-agent.nousresearch.com/">Hermes Desktop</a>
-</p>
+
 <p align="center">
  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
-  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
-  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
-  <a href="README.es.md"><img src="https://img.shields.io/badge/Lang-Español-orange?style=for-the-badge" alt="Español"></a>
 </p>

 **The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.

-Use any model you want — [Nous Portal](https://portal.nousresearch.com), OpenRouter, OpenAI, your own endpoint, and [many others](https://hermes-agent.nousresearch.com/docs/integrations/providers). Switch with `hermes model` — no code changes, no lock-in.
+Use any model you want — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (200+ models), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), OpenAI, or your own endpoint. Switch with `hermes model` — no code changes, no lock-in.

 <table>
 <tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
@@ -26,37 +21,21 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), OpenR
 <tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
 <tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
 <tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
-<tr><td><b>Runs anywhere, not just your laptop</b></td><td>Six terminal backends — local, Docker, SSH, Singularity, Modal, and Daytona. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
-<tr><td><b>Research-ready</b></td><td>Batch trajectory generation, trajectory compression for training the next generation of tool-calling models.</td></tr>
+<tr><td><b>Runs anywhere, not just your laptop</b></td><td>Six terminal backends — local, Docker, SSH, Daytona, Singularity, and Modal. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
+<tr><td><b>Research-ready</b></td><td>Batch trajectory generation, Atropos RL environments, trajectory compression for training the next generation of tool-calling models.</td></tr>
 </table>

 ---

 ## Quick Install

-### Linux, macOS, WSL2, Termux
-
 ```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```

-### Windows (native, PowerShell)
+Works on Linux, macOS, and WSL2. The installer handles everything — Python, Node.js, dependencies, and the `hermes` command. No prerequisites except git.

-> **Heads up:** Native Windows runs Hermes without WSL — CLI, gateway, TUI, and tools all work natively. If you'd rather use WSL2, the Linux/macOS one-liner above works there too. Found a bug? Please [file issues](https://github.com/NousResearch/hermes-agent/issues).
-
-Run this in PowerShell:
-
-```powershell
-iex (irm https://hermes-agent.nousresearch.com/install.ps1)
-```
-
-The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **and a portable Git Bash** (MinGit, unpacked to `%LOCALAPPDATA%\hermes\git` — no admin required, completely isolated from any system Git install). Hermes uses this bundled Git Bash to run shell commands.
-
-If you already have Git installed, the installer detects it and uses that instead. Otherwise a ~45MB MinGit download is all you need — it won't touch or interfere with any system Git.
-
-> **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
->
-> **Windows:** Native Windows is fully supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under `%LOCALAPPDATA%\hermes`; WSL2 installs under `~/.hermes` as on Linux.
+> **Windows:** Native Windows is not supported. Please install [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and run the command above.

 After installation:

@@ -65,41 +44,6 @@ source ~/.bashrc    # reload shell (or: source ~/.zshrc)
 hermes              # start chatting!
 ```

-### Troubleshooting
-
-#### Windows Defender or antivirus flags `uv.exe` as malware
-
-If your antivirus (Bitdefender, Windows Defender, etc.) quarantines `uv.exe` from the Hermes `bin` folder (`%LOCALAPPDATA%\hermes\bin\uv.exe`), this is a **false positive**. The file is Astral's `uv` — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.
-
-**To verify your copy is authentic:**
-
-```powershell
-# Install GitHub CLI if needed
-winget install --id GitHub.cli
-
-# Login to GitHub
-gh auth login
-
-# Run verification
-$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
-$ver = (& $uv --version).Split(' ')[1]
-[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
-$zip = "$env:TEMP\uv.zip"
-Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
-gh attestation verify $zip --repo astral-sh/uv
-Expand-Archive $zip "$env:TEMP\uv_x" -Force
-(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash
-```
-
-If attestation says "Verification succeeded" and the last line prints `True`, you're good.
-
-**To whitelist Hermes:**
- **Windows Defender:** Run PowerShell as Admin → `Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"`
- **Bitdefender:** Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
- Whitelist the **folder**, not the file hash — Hermes updates `uv` and the hash changes every version
-
-For more context, see the upstream Astral reports: [astral-sh/uv#13553](https://github.com/astral-sh/uv/issues/13553), [astral-sh/uv#15011](https://github.com/astral-sh/uv/issues/15011), [astral-sh/uv#10079](https://github.com/astral-sh/uv/issues/10079).
-
 ---

 ## Getting Started
@@ -109,7 +53,6 @@ hermes              # Interactive CLI — start a conversation
 hermes model        # Choose your LLM provider and model
 hermes tools        # Configure which tools are enabled
 hermes config set   # Set individual config values
-hermes config get   # Print individual config values
 hermes gateway      # Start the messaging gateway (Telegram, Discord, etc.)
 hermes setup        # Run the full setup wizard (configures everything at once)
 hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw)
@@ -119,42 +62,21 @@ hermes doctor       # Diagnose any issues

 📖 **[Full documentation →](https://hermes-agent.nousresearch.com/docs/)**

---
-
-## Skip the API-key collection — Nous Portal
-
-Hermes works with whatever provider you want — that's not changing. But if you'd rather not collect five separate API keys for the model, web search, image generation, TTS, and a cloud browser, **[Nous Portal](https://portal.nousresearch.com)** covers all of them under one subscription:
-
- **300+ models** — pick any of them with `/model <name>`
- **Tool Gateway** — web search (Firecrawl), image generation (FAL), text-to-speech (OpenAI), cloud browser (Browser Use), all routed through your sub. No extra accounts.
-
-One command from a fresh install:
-
-```bash
-hermes setup --portal
-```
-
-That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with `hermes portal info`. Full details on the [Tool Gateway docs page](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
-
-You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.
-
---
-
 ## CLI vs Messaging Quick Reference

 Hermes has two entry points: start the terminal UI with `hermes`, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.

-| Action                         | CLI                                           | Messaging platforms                                                              |
-| ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- |
-| Start chatting                 | `hermes`                                      | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
-| Start fresh conversation       | `/new` or `/reset`                            | `/new` or `/reset`                                                               |
-| Change model                   | `/model [provider:model]`                     | `/model [provider:model]`                                                        |
-| Set a personality              | `/personality [name]`                         | `/personality [name]`                                                            |
-| Retry or undo the last turn    | `/retry`, `/undo`                             | `/retry`, `/undo`                                                                |
-| Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]`                                        |
-| Browse skills                  | `/skills` or `/<skill-name>`                  | `/<skill-name>`                                                                  |
-| Interrupt current work         | `Ctrl+C` or send a new message                | `/stop` or send a new message                                                    |
-| Platform-specific status       | `/platforms`                                  | `/status`, `/sethome`                                                            |
+| Action | CLI | Messaging platforms |
+|---------|-----|---------------------|
+| Start chatting | `hermes` | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
+| Start fresh conversation | `/new` or `/reset` | `/new` or `/reset` |
+| Change model | `/model [provider:model]` | `/model [provider:model]` |
+| Set a personality | `/personality [name]` | `/personality [name]` |
+| Retry or undo the last turn | `/retry`, `/undo` | `/retry`, `/undo` |
+| Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]` |
+| Browse skills | `/skills` or `/<skill-name>` | `/skills` or `/<skill-name>` |
+| Interrupt current work | `Ctrl+C` or send a new message | `/stop` or send a new message |
+| Platform-specific status | `/platforms` | `/status`, `/sethome` |

 For the full command lists, see the [CLI guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) and the [Messaging Gateway guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).

@@ -164,23 +86,23 @@ For the full command lists, see the [CLI guide](https://hermes-agent.nousresearc

 All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:

-| Section                                                                                             | What's Covered                                             |
-| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)                 | Install → setup → first conversation in 2 minutes          |
-| [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                              | Commands, keybindings, personalities, sessions             |
-| [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)                | Config file, providers, models, all options                |
-| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)                | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
-| [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)                          | Command approval, DM pairing, container isolation          |
-| [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)            | 40+ tools, toolset system, terminal backends               |
-| [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)              | Procedural memory, Skills Hub, creating skills             |
-| [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)                     | Persistent memory, user profiles, best practices           |
-| [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)               | Connect any MCP server for extended capabilities           |
-| [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)              | Scheduled tasks with platform delivery                     |
-| [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)       | Project context that shapes every conversation             |
-| [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)             | Project structure, agent loop, key classes                 |
-| [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)             | Development setup, PR process, code style                  |
-| [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)                  | All commands and flags                                     |
-| [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference                                 |
+| Section | What's Covered |
+|---------|---------------|
+| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes |
+| [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions |
+| [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options |
+| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
+| [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Command approval, DM pairing, container isolation |
+| [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ tools, toolset system, terminal backends |
+| [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Procedural memory, Skills Hub, creating skills |
+| [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Persistent memory, user profiles, best practices |
+| [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Connect any MCP server for extended capabilities |
+| [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Scheduled tasks with platform delivery |
+| [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Project context that shapes every conversation |
+| [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | Project structure, agent loop, key classes |
+| [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Development setup, PR process, code style |
+| [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | All commands and flags |
+| [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference |

 ---

@@ -200,7 +122,6 @@ hermes claw migrate --overwrite  # Overwrite existing conflicts
 ```

 What gets imported:
-
 - **SOUL.md** — persona file
 - **Memories** — MEMORY.md and USER.md entries
 - **Skills** — user-created skills → `~/.hermes/skills/openclaw-imports/`
@@ -218,33 +139,24 @@ See `hermes claw migrate --help` for all options, or use the `openclaw-migration

 We welcome contributions! See the [Contributing Guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) for development setup, code style, and PR process.

-Quick start for contributors — use the standard installer, then work from the
-full git checkout it creates at `$HERMES_HOME/hermes-agent` (usually
-`~/.hermes/hermes-agent`). This matches the layout used by `hermes update`, the
-managed venv, lazy dependencies, gateway, and docs tooling.
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
-uv pip install -e ".[all,dev]"
-scripts/run_tests.sh
-```
-
-Manual clone fallback (for throwaway clones/CI where you intentionally do not
-want the managed install layout):
-
-Create the venv outside the cloned source tree — a venv inside the directory
-the agent operates from can be wiped by a relative-path command the agent runs
-against its own checkout, destroying the running runtime mid-session.
+Quick start for contributors:

 ```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
 curl -LsSf https://astral.sh/uv/install.sh | sh
-uv venv ~/.hermes/venvs/hermes-dev --python 3.11
-source ~/.hermes/venvs/hermes-dev/bin/activate
+uv venv venv --python 3.11
+source venv/bin/activate
 uv pip install -e ".[all,dev]"
-scripts/run_tests.sh
+python -m pytest tests/ -q
 ```

+> **RL Training (optional):** To work on the RL/Tinker-Atropos integration:
+> ```bash
+> git submodule update --init tinker-atropos
+> uv pip install -e "./tinker-atropos"
+> ```
+
 ---

 ## Community
@@ -252,8 +164,7 @@ scripts/run_tests.sh
 - 💬 [Discord](https://discord.gg/NousResearch)
 - 📚 [Skills Hub](https://agentskills.io)
 - 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
+- 💡 [Discussions](https://github.com/NousResearch/hermes-agent/discussions)

 ---

@@ -1,261 +0,0 @@
-<div dir="rtl">
-
-<p align="center">
-  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
-</p>
-
-# ہرمیس ایجنٹ ☤ (Hermes Agent)
-
-<p align="center">
-  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
-  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
-  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
-  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
-  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-lightgrey?style=for-the-badge" alt="English"></a>
-  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
-</p>
-
-**[نوس ریسرچ (Nous Research)](https://nousresearch.com) کا تیار کردہ خود کو بہتر بنانے والا اے آئی (AI) ایجنٹ۔** یہ واحد ایجنٹ ہے جس میں سیکھنے کا عمل (learning loop) پہلے سے موجود ہے — یہ اپنے تجربات سے نئی مہارتیں (skills) بناتا ہے، استعمال کے دوران ان کو بہتر کرتا ہے، معلومات کو محفوظ رکھنے کے لیے خود کو یاد دہانی کرواتا ہے، اپنی پرانی بات چیت کو تلاش کر سکتا ہے، اور مختلف سیشنز کے دوران آپ کے بارے میں ایک گہری سمجھ پیدا کرتا ہے۔ اسے $5 والے VPS پر چلائیں، GPU کلسٹر پر، یا سرور لیس (serverless) انفراسٹرکچر پر جس کی قیمت استعمال نہ ہونے پر تقریباً صفر ہے۔ یہ آپ کے لیپ ٹاپ تک محدود نہیں ہے — آپ ٹیلی گرام (Telegram) سے اس کے ساتھ بات چیت کر سکتے ہیں جبکہ یہ کلاؤڈ VM پر کام کر رہا ہو۔
-
-آپ اپنی مرضی کا کوئی بھی ماڈل استعمال کر سکتے ہیں — [Nous Portal](https://portal.nousresearch.com)، [OpenRouter](https://openrouter.ai) (200 سے زائد ماڈلز)، [NovitaAI](https://novita.ai) (ماڈل API، ایجنٹ سینڈ باکس، اور GPU کلاؤڈ کے لیے اے آئی مقامی کلاؤڈ)، [NVIDIA NIM](https://build.nvidia.com) (Nemotron)، [Xiaomi MiMo](https://platform.xiaomimimo.com)، [z.ai/GLM](https://z.ai)، [Kimi/Moonshot](https://platform.moonshot.ai)، [MiniMax](https://www.minimax.io)، [Hugging Face](https://huggingface.co)، OpenAI، یا اپنا حسب ضرورت اینڈ پوائنٹ (endpoint) استعمال کریں۔ ماڈل تبدیل کرنے کے لیے صرف `hermes model` استعمال کریں — کسی کوڈ کو تبدیل کرنے کی ضرورت نہیں، کوئی پابندی نہیں۔
-
-<table>
-<tr><td><b>حقیقی ٹرمینل انٹرفیس</b></td><td>مکمل TUI جس میں ملٹی لائن ایڈیٹنگ، سلیش-کمانڈ آٹو کمپلیٹ، بات چیت کی ہسٹری، انٹرپٹ اور ری ڈائریکٹ، اور سٹریمنگ ٹول آؤٹ پٹ شامل ہے۔</td></tr>
-<tr><td><b>یہ وہاں موجود ہے جہاں آپ ہیں</b></td><td>ٹیلی گرام، ڈسکارڈ (Discord)، سلیک (Slack)، واٹس ایپ (WhatsApp)، سگنل (Signal)، اور CLI — سب ایک ہی گیٹ وے پروسیس سے کام کرتے ہیں۔ وائس میمو (Voice memo) ٹرانسکرپشن، کراس پلیٹ فارم بات چیت کا تسلسل۔</td></tr>
-<tr><td><b>سیکھنے کا ایک مکمل عمل</b></td><td>ایجنٹ کی اپنی ترتیب دی گئی میموری، جس میں وہ خود کو وقتاً فوقتاً یاد دہانی کرواتا ہے۔ پیچیدہ کاموں کے بعد خود کار طریقے سے مہارت (skill) کی تخلیق۔ استعمال کے دوران مہارتوں میں بہتری۔ LLM سمرائزیشن کے ساتھ FTS5 سیشن سرچ تاکہ پرانے سیشنز کی یاددہانی کی جا سکے۔ <a href="https://github.com/plastic-labs/honcho">Honcho</a> کے ذریعے صارف کی ماڈلنگ۔ <a href="https://agentskills.io">agentskills.io</a> اوپن سٹینڈرڈ کے ساتھ مکمل مطابقت۔</td></tr>
-<tr><td><b>شیڈول کی گئی خودکار کارروائیاں</b></td><td>بلٹ ان (Built-in) کرون (cron) شیڈیولر جو کسی بھی پلیٹ فارم پر ڈیلیوری کے لیے استعمال ہو سکتا ہے۔ روزانہ کی رپورٹس، رات کے بیک اپس، ہفتہ وار آڈٹس — یہ سب کچھ قدرتی زبان (natural language) میں اور بغیر کسی نگرانی کے کام کرتا ہے۔</td></tr>
-<tr><td><b>کام کی تقسیم اور متوازی عمل</b></td><td>متوازی (parallel) کاموں کے لیے الگ سے ذیلی ایجنٹس (subagents) بنائیں۔ پائتھون (Python) سکرپٹس لکھیں جو RPC کے ذریعے ٹولز کو استعمال کریں، تاکہ کئی مراحل پر مشتمل کاموں کو بغیر کسی سیاق و سباق (context) کے خرچ کے، ایک ہی باری میں انجام دیا جا سکے۔</td></tr>
-<tr><td><b>کہیں بھی چلائیں، صرف اپنے لیپ ٹاپ پر نہیں</b></td><td>چھ (Six) ٹرمینل بیک اینڈز — لوکل، Docker، SSH، Singularity، Modal، اور Daytona۔ ڈیٹونا (Daytona) اور موڈل (Modal) سرور لیس (serverless) فعالیت پیش کرتے ہیں — جب آپ کا ایجنٹ فارغ ہوتا ہے تو اس کا ماحول سلیپ (hibernate) ہو جاتا ہے اور ضرورت پڑنے پر خود بخود جاگ جاتا ہے، جس کی وجہ سے سیشنز کے درمیان لاگت تقریباً صفر رہتی ہے۔ اسے $5 والے VPS یا GPU کلسٹر پر چلائیں۔</td></tr>
-<tr><td><b>تحقیق کے لیے تیار</b></td><td>بیچ (Batch) ٹریجیکٹری (trajectory) جنریشن، اگلی نسل کے ٹول کالنگ ماڈلز کی تربیت کے لیے ٹریجیکٹری کمپریشن۔</td></tr>
-</table>
-
---
-
-## فوری انسٹالیشن (Quick Install)
-
-### لینکس (Linux)، میک او ایس (macOS)، ڈبلیو ایس ایل ٹو (WSL2)، ٹرمکس (Termux)
-
-<div dir="ltr">
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-```
-
-</div>
-
-### ونڈوز (نیٹو، پاور شیل)
-
-> **توجہ فرمائیں:** مقامی ونڈوز (Native Windows) پر ہرمیس بغیر WSL کے چلتا ہے — CLI، گیٹ وے، TUI، اور ٹولز سب مقامی طور پر کام کرتے ہیں۔ اگر آپ WSL2 استعمال کرنا پسند کرتے ہیں، تو اوپر دی گئی لینکس/میک او ایس کی کمانڈ وہاں بھی کام کرے گی۔ کوئی مسئلہ نظر آیا؟ براہ کرم [مسائل (issues) درج کریں](https://github.com/NousResearch/hermes-agent/issues)۔
-
-اسے پاور شیل (PowerShell) میں چلائیں:
-
-<div dir="ltr">
-
-```powershell
-iex (irm https://hermes-agent.nousresearch.com/install.ps1)
-```
-
-</div>
-
-انسٹالر سب کچھ خود سنبھالتا ہے: uv، Python 3.11، Node.js، ripgrep، ffmpeg، **اور ایک پورٹ ایبل (portable) گٹ بیش (Git Bash)** (یعنی MinGit، جو `%LOCALAPPDATA%\hermes\git` میں ان پیک ہوتا ہے — اس کے لیے ایڈمن کی اجازت درکار نہیں، اور یہ سسٹم کے کسی بھی گٹ انسٹال سے بالکل الگ ہے)۔ ہرمیس اس بنڈل شدہ گٹ بیش کو شیل کمانڈز چلانے کے لیے استعمال کرتا ہے۔
-
-اگر آپ کے پاس پہلے سے گٹ (Git) انسٹال ہے، تو انسٹالر اسے شناخت کر لیتا ہے اور اسے ہی استعمال کرتا ہے۔ بصورت دیگر آپ کو صرف ~45MB کے MinGit ڈاؤنلوڈ کی ضرورت ہوگی — یہ آپ کے سسٹم کے گٹ پر کوئی اثر نہیں ڈالے گا۔
-
-> **اینڈرائیڈ (Android) / ٹرمکس (Termux):** ٹیسٹ کیا گیا مینوئل طریقہ [Termux گائیڈ](https://hermes-agent.nousresearch.com/docs/getting-started/termux) میں موجود ہے۔ ٹرمکس پر ہرمیس ایک مخصوص `.[termux]` ایکسٹرا انسٹال کرتا ہے کیونکہ مکمل `.[all]` ایکسٹرا میں ایسی وائس ڈیپینڈینسیز شامل ہیں جو اینڈرائیڈ کے ساتھ مطابقت نہیں رکھتیں۔
->
-> **ونڈوز (Windows):** مقامی ونڈوز کی مکمل سپورٹ موجود ہے — اوپر دی گئی پاور شیل کی کمانڈ سب کچھ انسٹال کر دیتی ہے۔ اگر آپ WSL2 استعمال کرنا چاہتے ہیں، تو لینکس کی کمانڈ وہاں کام کرتی ہے۔ مقامی ونڈوز میں انسٹالیشن `%LOCALAPPDATA%\hermes` میں ہوتی ہے؛ جبکہ WSL2 میں لینکس کی طرح `~/.hermes` میں ہوتی ہے۔ ہرمیس کا وہ واحد فیچر جسے فی الحال خاص طور پر WSL2 کی ضرورت ہے وہ براؤزر پر مبنی ڈیش بورڈ چیٹ پین ہے (یہ POSIX PTY استعمال کرتا ہے — کلاسک CLI اور گیٹ وے دونوں مقامی طور پر چلتے ہیں)۔
-
-انسٹالیشن کے بعد:
-
-<div dir="ltr">
-
-```bash
-source ~/.bashrc    # شیل کو ری لوڈ کریں (یا: source ~/.zshrc)
-hermes              # بات چیت شروع کریں!
-```
-
-</div>
-
---
-
-## آغاز کریں (Getting Started)
-
-<div dir="ltr">
-
-```bash
-hermes              # انٹرایکٹو CLI — بات چیت شروع کریں
-hermes model        # اپنا LLM پرووائیڈر اور ماڈل منتخب کریں
-hermes tools        # کنفیگر کریں کہ کون سے ٹولز ایکٹو ہیں
-hermes config set   # انفرادی کنفگ (config) ویلیوز سیٹ کریں
-hermes gateway      # میسجنگ گیٹ وے شروع کریں (ٹیلی گرام، ڈسکارڈ، وغیرہ)
-hermes setup        # مکمل سیٹ اپ وزرڈ چلائیں (یہ سب کچھ ایک ساتھ کنفیگر کر دے گا)
-hermes claw migrate # OpenClaw سے مائیگریٹ کریں (اگر آپ OpenClaw سے آ رہے ہیں)
-hermes update       # لیٹسٹ ورژن پر اپ ڈیٹ کریں
-hermes doctor       # کسی بھی مسئلے کی تشخیص کریں
-```
-
-</div>
-
-📖 **[مکمل دستاویزات →](https://hermes-agent.nousresearch.com/docs/)**
-
---
-
-## API-کیز اکٹھی کرنے سے بچیں — Nous Portal
-
-ہرمیس آپ کے پسندیدہ پرووائیڈر کے ساتھ کام کرتا ہے — یہ چیز تبدیل نہیں ہو رہی۔ لیکن اگر آپ ماڈل، ویب سرچ، امیج جنریشن، TTS، اور کلاؤڈ براؤزر کے لیے پانچ الگ الگ API کیز جمع نہیں کرنا چاہتے، تو **[Nous Portal](https://portal.nousresearch.com)** ان سب کو ایک ہی سبسکرپشن کے تحت کور کرتا ہے:
-
- **300+ ماڈلز** — ان میں سے کوئی بھی ماڈل `/model <name>` کے ذریعے منتخب کریں
- **ٹول گیٹ وے (Tool Gateway)** — ویب سرچ (Firecrawl)، امیج جنریشن (FAL)، ٹیکسٹ ٹو سپیچ (OpenAI)، کلاؤڈ براؤزر (Browser Use)، یہ سب آپ کی سبسکرپشن کے ذریعے چلتے ہیں۔ کسی اضافی اکاؤنٹ کی ضرورت نہیں۔
-
-نئی انسٹالیشن کے بعد بس ایک کمانڈ کی ضرورت ہے:
-
-<div dir="ltr">
-
-```bash
-hermes setup --portal
-```
-
-</div>
-
-یہ آپ کو OAuth کے ذریعے لاگ ان کرواتا ہے، Nous کو آپ کا پرووائیڈر مقرر کرتا ہے، اور ٹول گیٹ وے کو آن کر دیتا ہے۔ `hermes portal info` کمانڈ استعمال کر کے آپ کسی بھی وقت چیک کر سکتے ہیں کہ کون کون سی سروسز منسلک ہیں۔ مکمل تفصیلات [Tool Gateway دستاویزات کے صفحے](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway) پر موجود ہیں۔
-
-آپ اب بھی کسی بھی ٹول کے لیے اپنی مرضی کی API کیز استعمال کر سکتے ہیں — گیٹ وے ہر سروس کے لیے الگ الگ کام کرتا ہے، ایسا نہیں کہ یا تو سب کچھ استعمال کریں یا کچھ بھی نہیں۔
-
---
-
-## CLI بمقابلہ میسجنگ فوری حوالہ
-
-ہرمیس کے دو بنیادی انٹر فیس ہیں: آپ ٹرمینل UI کو `hermes` کے ساتھ شروع کریں، یا گیٹ وے چلا کر اس کے ساتھ ٹیلی گرام، ڈسکارڈ، سلیک، واٹس ایپ، سگنل، یا ای میل کے ذریعے بات کریں۔ جب آپ کسی بات چیت میں ہوتے ہیں، تو بہت سی سلیش (slash) کمانڈز دونوں انٹرفیسز میں ایک جیسی ہوتی ہیں۔
-
-<div dir="ltr">
-
-| کارروائی (Action)                         | سی ایل آئی (CLI)                              | میسجنگ پلیٹ فارمز (Messaging platforms)                                          |
-| --------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
-| بات چیت شروع کریں                       | `hermes`                                      | `hermes gateway setup` اور `hermes gateway start` چلائیں، پھر بوٹ کو میسج بھیجیں |
-| نئی بات چیت شروع کریں                   | `/new` یا `/reset`                            | `/new` یا `/reset`                                                               |
-| ماڈل تبدیل کریں                         | `/model [provider:model]`                     | `/model [provider:model]`                                                        |
-| پرسنلٹی (Personality) سیٹ کریں           | `/personality [name]`                         | `/personality [name]`                                                            |
-| پچھلی باری کو دوبارہ یا منسوخ (undo) کریں | `/retry`، `/undo`                             | `/retry`، `/undo`                                                                |
-| کانٹیکسٹ (context) کمپریس کریں / استعمال چیک کریں | `/compress`، `/usage`، `/insights [--days N]` | `/compress`، `/usage`، `/insights [days]`                                        |
-| مہارتیں (Skills) براؤز کریں             | `/skills` یا `/<skill-name>`                  | `/<skill-name>`                                                                  |
-| موجودہ کام کو روکیں                     | `Ctrl+C` دبائیں یا نیا میسج بھیجیں            | `/stop` یا نیا میسج بھیجیں                                                       |
-| پلیٹ فارم کے لحاظ سے سٹیٹس              | `/platforms`                                  | `/status`، `/sethome`                                                            |
-
-</div>
-
-مکمل کمانڈ لسٹ کے لیے، [CLI گائیڈ](https://hermes-agent.nousresearch.com/docs/user-guide/cli) اور [میسجنگ گیٹ وے گائیڈ](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) دیکھیں۔
-
---
-
-## دستاویزات (Documentation)
-
-تمام دستاویزات **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)** پر موجود ہیں:
-
-<div dir="ltr">
-
-| سیکشن (Section)                                                                                     | تفصیل (What's Covered)                                     |
-| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| [فوری آغاز (Quickstart)](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)     | انسٹالیشن → سیٹ اپ → 2 منٹ میں پہلی بات چیت شروع کریں       |
-| [CLI کا استعمال](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                         | کمانڈز، کی بائنڈنگز (keybindings)، پرسنلٹیز (personalities)، سیشنز |
-| [کنفیگریشن (Configuration)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)    | کنفگ فائل، پرووائیڈرز، ماڈلز، اور تمام آپشنز               |
-| [میسجنگ گیٹ وے](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)                    | ٹیلی گرام، ڈسکارڈ، سلیک، واٹس ایپ، سگنل، ہوم اسسٹنٹ         |
-| [سیکیورٹی (Security)](https://hermes-agent.nousresearch.com/docs/user-guide/security)              | کمانڈ کی منظوری، DM پیئرنگ (pairing)، کنٹینر آئسولیشن       |
-| [ٹولز اور ٹول سیٹس](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)          | 40 سے زائد ٹولز، ٹول سیٹ سسٹم، ٹرمینل بیک اینڈز             |
-| [مہارتوں کا سسٹم (Skills System)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)| پروسیجرل (Procedural) میموری، سکلز ہب، نئی مہارتیں بنانا    |
-| [میموری (Memory)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)            | مستقل میموری، یوزر پروفائلز، بہترین طریقہ کار              |
-| [MCP انضمام (Integration)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)      | صلاحیتوں کو بڑھانے کے لیے کسی بھی MCP سرور کو جوڑیں        |
-| [کرون (Cron) شیڈیولنگ](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)         | پلیٹ فارم ڈیلیوری کے ساتھ شیڈول کیے گئے کام                 |
-| [کانٹیکسٹ (Context) فائلز](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)| پروجیکٹ کا سیاق و سباق (context) جو ہر بات چیت پر اثر انداز ہوتا ہے |
-| [آرکیٹیکچر (Architecture)](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | پروجیکٹ کا ڈھانچہ، ایجنٹ لوپ، اہم کلاسز                    |
-| [تعاون (Contributing)](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)     | ڈیویلپمنٹ سیٹ اپ، PR کا طریقہ کار، کوڈنگ کا انداز          |
-| [CLI حوالہ جات (Reference)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)      | تمام کمانڈز اور فلیگز (flags)                              |
-| [انوائرمنٹ ویری ایبلز](https://hermes-agent.nousresearch.com/docs/reference/environment-variables)  | مکمل انوائرمنٹ ویری ایبل حوالہ جات                         |
-
-</div>
-
---
-
-## OpenClaw سے منتقلی
-
-اگر آپ OpenClaw سے منتقل ہو رہے ہیں، تو ہرمیس آپ کی سیٹنگز، یادیں (memories)، مہارتیں (skills)، اور API کیز کو خود بخود امپورٹ کر سکتا ہے۔
-
-**پہلی بار سیٹ اپ کے دوران:** سیٹ اپ وزرڈ (`hermes setup`) خود بخود `~/.openclaw` کو پہچان لیتا ہے اور کنفیگریشن شروع ہونے سے پہلے مائیگریٹ (migrate) کرنے کا آپشن دیتا ہے۔
-
-**انسٹالیشن کے بعد کسی بھی وقت:**
-
-<div dir="ltr">
-
-```bash
-hermes claw migrate              # انٹرایکٹو مائیگریشن (مکمل پری سیٹ)
-hermes claw migrate --dry-run    # جائزہ لیں کہ کیا کیا مائیگریٹ ہوگا
-hermes claw migrate --preset user-data   # حساس معلومات (secrets) کے بغیر مائیگریٹ کریں
-hermes claw migrate --overwrite  # موجودہ متصادم فائلوں کو اوور رائٹ کریں
-```
-
-</div>
-
-جو چیزیں امپورٹ ہوتی ہیں:
-
- **SOUL.md** — پرسونا (persona) فائل
- **میموریز (Memories)** — MEMORY.md اور USER.md کی اندراجات
- **مہارتیں (Skills)** — صارف کی بنائی گئی مہارتیں → `~/.hermes/skills/openclaw-imports/`
- **کمانڈ الاؤ لسٹ (allowlist)** — منظوری کے پیٹرنز (approval patterns)
- **میسجنگ سیٹنگز** — پلیٹ فارم کنفیگریشنز، اجازت یافتہ صارفین، ورکنگ ڈائریکٹری
- **API کیز** — الاؤ لسٹ شدہ حساس معلومات (ٹیلی گرام، OpenRouter، OpenAI، Anthropic، ElevenLabs)
- **TTS اثاثے** — ورک اسپیس کی آڈیو فائلیں
- **ورک اسپیس کی ہدایات** — AGENTS.md (`--workspace-target` کے ساتھ)
-
-تمام آپشنز دیکھنے کے لیے `hermes claw migrate --help` استعمال کریں، یا انٹرایکٹو ایجنٹ کی مدد سے مائیگریٹ کرنے کے لیے `openclaw-migration` سکل کا استعمال کریں (جس میں ڈرائی رن (dry-run) پریویوز شامل ہیں)۔
-
---
-
-## تعاون کریں (Contributing)
-
-ہم آپ کے تعاون کا خیرمقدم کرتے ہیں! ڈیویلپمنٹ سیٹ اپ، کوڈ کے انداز اور PR کے طریقہ کار کے لیے براہ کرم ہماری [Contributing گائیڈ](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) دیکھیں۔
-
-معاونین (contributors) کے لیے فوری آغاز — کلون (clone) کریں اور `setup-hermes.sh` چلائیں:
-
-<div dir="ltr">
-
-```bash
-git clone https://github.com/NousResearch/hermes-agent.git
-cd hermes-agent
-./setup-hermes.sh     # uv کو انسٹال کرتا ہے، venv بناتا ہے، .[all] کو انسٹال کرتا ہے، اور ~/.local/bin/hermes کا سیم لنک (symlink) بناتا ہے
-./hermes              # خود بخود venv کی شناخت کرتا ہے، پہلے `source` کرنے کی ضرورت نہیں
-```
-
-</div>
-
-مینوئل طریقہ (اوپر والے طریقے کے مساوی):
-
-<div dir="ltr">
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv venv .venv --python 3.11
-source .venv/bin/activate
-uv pip install -e ".[all,dev]"
-scripts/run_tests.sh
-```
-
-</div>
-
---
-
-## کمیونٹی (Community)
-
- 💬 [ڈسکارڈ (Discord)](https://discord.gg/NousResearch)
- 📚 [سکلز ہب (Skills Hub)](https://agentskills.io)
- 🐛 [مسائل (Issues)](https://github.com/NousResearch/hermes-agent/issues)
- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — ہرمیس اور دیگر MCP ہوسٹس کے لیے لینکس (Linux) ڈیسک ٹاپ کنٹرول MCP سرور، جس میں AT-SPI ایکسیسیبلٹی ٹریز، Wayland/X11 ان پٹ، سکرین شاٹس، اور کمپوزیٹر ونڈو ٹارگیٹنگ شامل ہے۔
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — کمیونٹی وی چیٹ (WeChat) برج: ہرمیس ایجنٹ اور OpenClaw کو ایک ہی وی چیٹ اکاؤنٹ پر چلائیں۔
-
---
-
-## لائسنس (License)
-
-MIT — تفصیلات کے لیے [LICENSE](LICENSE) دیکھیں۔
-
-[نوس ریسرچ (Nous Research)](https://nousresearch.com) کی جانب سے تیار کردہ۔
-
-</div>
@@ -1,208 +0,0 @@
-<p align="center">
-  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
-</p>
-
-# Hermes Agent ☤
-
-<p align="center">
-  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
-  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
-  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
-  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
-  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-lightgrey?style=for-the-badge" alt="English"></a>
-  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
-</p>
-
-**由 [Nous Research](https://nousresearch.com) 构建的自进化 AI 代理。** 它是唯一内置学习闭环的智能代理——从经验中创建技能，在使用中改进技能，主动持久化知识，搜索过往对话，并在跨会话中逐步构建对你的深度理解。可以在 $5 的 VPS 上运行，也可以在 GPU 集群上运行，或者使用几乎零成本的 Serverless 基础设施。它不绑定你的笔记本——你可以在 Telegram 上与它对话，而它在云端 VM 上工作。
-
-支持任意模型——[Nous Portal](https://portal.nousresearch.com)、[OpenRouter](https://openrouter.ai)（200+ 模型）、[NVIDIA NIM](https://build.nvidia.com)（Nemotron）、[小米 MiMo](https://platform.xiaomimimo.com)、[z.ai/GLM](https://z.ai)、[Kimi/Moonshot](https://platform.moonshot.ai)、[MiniMax](https://www.minimax.io)、[Hugging Face](https://huggingface.co)、OpenAI，或自定义端点。使用 `hermes model` 即可切换——无需改代码，无锁定。
-
-<table>
-<tr><td><b>真正的终端界面</b></td><td>完整的 TUI，支持多行编辑、斜杠命令自动补全、对话历史、中断重定向和流式工具输出。</td></tr>
-<tr><td><b>随你所在</b></td><td>Telegram、Discord、Slack、WhatsApp、Signal 和 CLI——全部从单个网关进程运行。语音备忘录转写、跨平台对话连续性。</td></tr>
-<tr><td><b>闭环学习</b></td><td>代理管理记忆并定期自我提醒。复杂任务后自动创建技能。技能在使用中自我改进。FTS5 会话搜索配合 LLM 摘要实现跨会话回溯。<a href="https://github.com/plastic-labs/honcho">Honcho</a> 辩证式用户建模。兼容 <a href="https://agentskills.io">agentskills.io</a> 开放标准。</td></tr>
-<tr><td><b>定时自动化</b></td><td>内置 cron 调度器，支持向任何平台投递。日报、夜间备份、周审计——全部用自然语言描述，无人值守运行。</td></tr>
-<tr><td><b>委派与并行</b></td><td>生成隔离子代理处理并行工作流。编写 Python 脚本通过 RPC 调用工具，将多步管道压缩为零上下文开销的轮次。</td></tr>
-<tr><td><b>随处运行</b></td><td>六种终端后端——本地、Docker、SSH、Daytona、Singularity 和 Modal。Daytona 和 Modal 提供 Serverless 持久化——代理环境空闲时休眠、按需唤醒，空闲期间几乎零成本。$5 VPS 或 GPU 集群都能跑。</td></tr>
-<tr><td><b>研究就绪</b></td><td>批量轨迹生成、轨迹压缩——用于训练下一代工具调用模型。</td></tr>
-</table>
-
---
-
-## 快速安装
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-```
-
-支持 Linux、macOS、WSL2 和 Android (Termux)。安装程序会自动处理平台特定的配置。
-
-> **Android / Termux：** 已测试的手动安装路径请参考 [Termux 指南](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。在 Termux 上，Hermes 会安装精选的 `.[termux]` 扩展，因为完整的 `.[all]` 扩展会拉取 Android 不兼容的语音依赖。
->
-> **Windows：** 在 PowerShell 中运行：
-> ```powershell
-> iex (irm https://hermes-agent.nousresearch.com/install.ps1)
-> ```
-> 安装完成后，可能需要重启终端，然后运行 `hermes` 开始对话。
-
-安装后：
-
-```bash
-source ~/.bashrc    # 重新加载 shell（或: source ~/.zshrc）
-hermes              # 开始对话！
-```
-
---
-
-## 快速入门
-
-```bash
-hermes              # 交互式 CLI — 开始对话
-hermes model        # 选择 LLM 提供商和模型
-hermes tools        # 配置启用的工具
-hermes config set   # 设置单个配置项
-hermes gateway      # 启动消息网关（Telegram、Discord 等）
-hermes setup        # 运行完整设置向导（一次性配置所有内容）
-hermes claw migrate # 从 OpenClaw 迁移（如果来自 OpenClaw）
-hermes update       # 更新到最新版本
-hermes doctor       # 诊断问题
-```
-
-📖 **[完整文档 →](https://hermes-agent.nousresearch.com/docs/)**
-
---
-
-## 省去到处收集 API Key — Nous Portal
-
-Hermes 始终允许你使用任意服务商，这点不会改变。但如果你不想为模型、网页搜索、图像生成、TTS、云浏览器分别去申请五个不同的 API Key，**[Nous Portal](https://portal.nousresearch.com)** 用一个订阅就能覆盖全部：
-
- **300+ 模型** — 用 `/model <name>` 随时切换
- **Tool Gateway** — 网页搜索（Firecrawl）、图像生成（FAL）、文本转语音（OpenAI）、云浏览器（Browser Use），全部通过订阅托管。无需额外注册任何账户。
-
-全新安装时一条命令即可：
-
-```bash
-hermes setup --portal
-```
-
-它会通过 OAuth 登录、把 Nous 设为推理服务商，并启用 Tool Gateway。随时用 `hermes portal info` 查看路由状态。完整说明见 [Tool Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway)。
-
-你随时可以按工具单独切回自己的 API Key — Gateway 是按工具粒度生效的，不是一刀切。
-
---
-
-## CLI 与消息平台 快速对照
-
-Hermes 有两种入口：用 `hermes` 启动终端 UI，或运行网关从 Telegram、Discord、Slack、WhatsApp、Signal 或 Email 与之对话。进入对话后，许多斜杠命令在两种界面中通用。
-
-| 操作 | CLI | 消息平台 |
-|------|-----|----------|
-| 开始对话 | `hermes` | 运行 `hermes gateway setup` + `hermes gateway start`，然后给机器人发消息 |
-| 开始新对话 | `/new` 或 `/reset` | `/new` 或 `/reset` |
-| 更换模型 | `/model [provider:model]` | `/model [provider:model]` |
-| 设置人格 | `/personality [name]` | `/personality [name]` |
-| 重试或撤销上一轮 | `/retry`、`/undo` | `/retry`、`/undo` |
-| 压缩上下文 / 查看用量 | `/compress`、`/usage`、`/insights [--days N]` | `/compress`、`/usage`、`/insights [days]` |
-| 浏览技能 | `/skills` 或 `/<skill-name>` | `/skills` 或 `/<skill-name>` |
-| 中断当前工作 | `Ctrl+C` 或发送新消息 | `/stop` 或发送新消息 |
-| 平台特定状态 | `/platforms` | `/status`、`/sethome` |
-
-完整命令列表请参阅 [CLI 指南](https://hermes-agent.nousresearch.com/docs/user-guide/cli) 和 [消息网关指南](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)。
-
---
-
-## 文档
-
-所有文档位于 **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**：
-
-| 章节 | 内容 |
-|------|------|
-| [快速开始](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | 安装 → 设置 → 2 分钟内开始首次对话 |
-| [CLI 使用](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | 命令、快捷键、人格、会话 |
-| [配置](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | 配置文件、提供商、模型、所有选项 |
-| [消息网关](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant |
-| [安全](https://hermes-agent.nousresearch.com/docs/user-guide/security) | 命令审批、DM 配对、容器隔离 |
-| [工具与工具集](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ 工具、工具集系统、终端后端 |
-| [技能系统](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | 过程记忆、技能中心、创建技能 |
-| [记忆](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | 持久记忆、用户画像、最佳实践 |
-| [MCP 集成](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | 连接任意 MCP 服务器扩展能力 |
-| [定时调度](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | 定时任务与平台投递 |
-| [上下文文件](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | 影响每次对话的项目上下文 |
-| [架构](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | 项目结构、代理循环、关键类 |
-| [贡献](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | 开发设置、PR 流程、代码风格 |
-| [CLI 参考](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | 所有命令和标志 |
-| [环境变量](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | 完整环境变量参考 |
-
---
-
-## 从 OpenClaw 迁移
-
-如果你来自 OpenClaw，Hermes 可以自动导入你的设置、记忆、技能和 API 密钥。
-
-**首次安装时：** 安装向导（`hermes setup`）会自动检测 `~/.openclaw` 并在配置开始前提供迁移选项。
-
-**安装后任意时间：**
-
-```bash
-hermes claw migrate              # 交互式迁移（完整预设）
-hermes claw migrate --dry-run    # 预览将要迁移的内容
-hermes claw migrate --preset user-data   # 仅迁移用户数据，不含密钥
-hermes claw migrate --overwrite  # 覆盖已有冲突
-```
-
-导入内容：
- **SOUL.md** — 人格文件
- **记忆** — MEMORY.md 和 USER.md 条目
- **技能** — 用户创建的技能 → `~/.hermes/skills/openclaw-imports/`
- **命令白名单** — 审批模式
- **消息设置** — 平台配置、允许用户、工作目录
- **API 密钥** — 白名单中的密钥（Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs）
- **TTS 资产** — 工作区音频文件
- **工作区指令** — AGENTS.md（使用 `--workspace-target`）
-
-使用 `hermes claw migrate --help` 查看所有选项，或使用 `openclaw-migration` 技能进行交互式代理引导迁移（含干运行预览）。
-
---
-
-## 贡献
-
-欢迎贡献！请参阅 [贡献指南](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) 了解开发设置、代码风格和 PR 流程。
-
-贡献者快速开始——使用标准安装器，然后在它创建的完整 git checkout 中开发：
-`$HERMES_HOME/hermes-agent`（通常是 `~/.hermes/hermes-agent`）。这会匹配
-`hermes update`、托管 venv、lazy dependencies、gateway 和 docs tooling 使用的布局。
-
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
-uv pip install -e ".[all,dev]"
-scripts/run_tests.sh
-```
-
-手动克隆备用路径（用于一次性 clone / CI，或你明确不想使用 managed install layout 时）：
-
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-uv venv venv --python 3.11
-source venv/bin/activate
-uv pip install -e ".[all,dev]"
-python -m pytest tests/ -q
-```
-
---
-
-## 社区
-
- 💬 [Discord](https://discord.gg/NousResearch)
- 📚 [技能中心](https://agentskills.io)
- 🐛 [问题反馈](https://github.com/NousResearch/hermes-agent/issues)
- 💡 [讨论区](https://github.com/NousResearch/hermes-agent/discussions)
- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — 社区微信桥接：在同一微信账号上运行 Hermes Agent 和 OpenClaw。
-
---
-
-## 许可证
-
-MIT — 详见 [LICENSE](LICENSE)。
-
-由 [Nous Research](https://nousresearch.com) 构建。
@@ -0,0 +1,383 @@
+# Hermes Agent v0.2.0 (v2026.3.12)
+
+**Release Date:** March 12, 2026
+
+> First tagged release since v0.1.0 (the initial pre-public foundation). In just over two weeks, Hermes Agent went from a small internal project to a full-featured AI agent platform — thanks to an explosion of community contributions. This release covers **216 merged pull requests** from **63 contributors**, resolving **119 issues**.
+
+---
+
+## ✨ Highlights
+
+- **Multi-Platform Messaging Gateway** — Telegram, Discord, Slack, WhatsApp, Signal, Email (IMAP/SMTP), and Home Assistant platforms with unified session management, media attachments, and per-platform tool configuration.
+
+- **MCP (Model Context Protocol) Client** — Native MCP support with stdio and HTTP transports, reconnection, resource/prompt discovery, and sampling (server-initiated LLM requests). ([#291](https://github.com/NousResearch/hermes-agent/pull/291) — @0xbyt4, [#301](https://github.com/NousResearch/hermes-agent/pull/301), [#753](https://github.com/NousResearch/hermes-agent/pull/753))
+
+- **Skills Ecosystem** — 70+ bundled and optional skills across 15+ categories with a Skills Hub for community discovery, per-platform enable/disable, conditional activation based on tool availability, and prerequisite validation. ([#743](https://github.com/NousResearch/hermes-agent/pull/743) — @teyrebaz33, [#785](https://github.com/NousResearch/hermes-agent/pull/785) — @teyrebaz33)
+
+- **Centralized Provider Router** — Unified `call_llm()`/`async_call_llm()` API replaces scattered provider logic across vision, summarization, compression, and trajectory saving. All auxiliary consumers route through a single code path with automatic credential resolution. ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+
+- **ACP Server** — VS Code, Zed, and JetBrains editor integration via the Agent Communication Protocol standard. ([#949](https://github.com/NousResearch/hermes-agent/pull/949))
+
+- **CLI Skin/Theme Engine** — Data-driven visual customization: banners, spinners, colors, branding. 7 built-in skins + custom YAML skins.
+
+- **Git Worktree Isolation** — `hermes -w` launches isolated agent sessions in git worktrees for safe parallel work on the same repo. ([#654](https://github.com/NousResearch/hermes-agent/pull/654))
+
+- **Filesystem Checkpoints & Rollback** — Automatic snapshots before destructive operations with `/rollback` to restore. ([#824](https://github.com/NousResearch/hermes-agent/pull/824))
+
+- **3,289 Tests** — From near-zero test coverage to a comprehensive test suite covering agent, gateway, tools, cron, and CLI.
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- Centralized provider router with `resolve_provider_client()` + `call_llm()` API ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+- Nous Portal as first-class provider in setup ([#644](https://github.com/NousResearch/hermes-agent/issues/644))
+- OpenAI Codex (Responses API) with ChatGPT subscription support ([#43](https://github.com/NousResearch/hermes-agent/pull/43)) — @grp06
+- Codex OAuth vision support + multimodal content adapter
+- Validate `/model` against live API instead of hardcoded lists
+- Self-hosted Firecrawl support ([#460](https://github.com/NousResearch/hermes-agent/pull/460)) — @caentzminger
+- Kimi Code API support ([#635](https://github.com/NousResearch/hermes-agent/pull/635)) — @christomitov
+- MiniMax model ID update ([#473](https://github.com/NousResearch/hermes-agent/pull/473)) — @tars90percent
+- OpenRouter provider routing configuration (provider_preferences)
+- Nous credential refresh on 401 errors ([#571](https://github.com/NousResearch/hermes-agent/pull/571), [#269](https://github.com/NousResearch/hermes-agent/pull/269)) — @rewbs
+- z.ai/GLM, Kimi/Moonshot, MiniMax, Azure OpenAI as first-class providers
+- Unified `/model` and `/provider` into single view
+
+### Agent Loop & Conversation
+- Simple fallback model for provider resilience ([#740](https://github.com/NousResearch/hermes-agent/pull/740))
+- Shared iteration budget across parent + subagent delegation
+- Iteration budget pressure via tool result injection
+- Configurable subagent provider/model with full credential resolution
+- Handle 413 payload-too-large via compression instead of aborting ([#153](https://github.com/NousResearch/hermes-agent/pull/153)) — @tekelala
+- Retry with rebuilt payload after compression ([#616](https://github.com/NousResearch/hermes-agent/pull/616)) — @tripledoublev
+- Auto-compress pathologically large gateway sessions ([#628](https://github.com/NousResearch/hermes-agent/issues/628))
+- Tool call repair middleware — auto-lowercase and invalid tool handler
+- Reasoning effort configuration and `/reasoning` command ([#921](https://github.com/NousResearch/hermes-agent/pull/921))
+- Detect and block file re-read/search loops after context compression ([#705](https://github.com/NousResearch/hermes-agent/pull/705)) — @0xbyt4
+
+### Session & Memory
+- Session naming with unique titles, auto-lineage, rich listing, and resume by name ([#720](https://github.com/NousResearch/hermes-agent/pull/720))
+- Interactive session browser with search filtering ([#733](https://github.com/NousResearch/hermes-agent/pull/733))
+- Display previous messages when resuming a session ([#734](https://github.com/NousResearch/hermes-agent/pull/734))
+- Honcho AI-native cross-session user modeling ([#38](https://github.com/NousResearch/hermes-agent/pull/38)) — @erosika
+- Proactive async memory flush on session expiry
+- Smart context length probing with persistent caching + banner display
+- `/resume` command for switching to named sessions in gateway
+- Session reset policy for messaging platforms
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Telegram
+- Native file attachments: send_document + send_video
+- Document file processing for PDF, text, and Office files — @tekelala
+- Forum topic session isolation ([#766](https://github.com/NousResearch/hermes-agent/pull/766)) — @spanishflu-est1918
+- Browser screenshot sharing via MEDIA: protocol ([#657](https://github.com/NousResearch/hermes-agent/pull/657))
+- Location support for find-nearby skill
+- TTS voice message accumulation fix ([#176](https://github.com/NousResearch/hermes-agent/pull/176)) — @Bartok9
+- Improved error handling and logging ([#763](https://github.com/NousResearch/hermes-agent/pull/763)) — @aydnOktay
+- Italic regex newline fix + 43 format tests ([#204](https://github.com/NousResearch/hermes-agent/pull/204)) — @0xbyt4
+
+### Discord
+- Channel topic included in session context ([#248](https://github.com/NousResearch/hermes-agent/pull/248)) — @Bartok9
+- DISCORD_ALLOW_BOTS config for bot message filtering ([#758](https://github.com/NousResearch/hermes-agent/pull/758))
+- Document and video support ([#784](https://github.com/NousResearch/hermes-agent/pull/784))
+- Improved error handling and logging ([#761](https://github.com/NousResearch/hermes-agent/pull/761)) — @aydnOktay
+
+### Slack
+- App_mention 404 fix + document/video support ([#784](https://github.com/NousResearch/hermes-agent/pull/784))
+- Structured logging replacing print statements — @aydnOktay
+
+### WhatsApp
+- Native media sending — images, videos, documents ([#292](https://github.com/NousResearch/hermes-agent/pull/292)) — @satelerd
+- Multi-user session isolation ([#75](https://github.com/NousResearch/hermes-agent/pull/75)) — @satelerd
+- Cross-platform port cleanup replacing Linux-only fuser ([#433](https://github.com/NousResearch/hermes-agent/pull/433)) — @Farukest
+- DM interrupt key mismatch fix ([#350](https://github.com/NousResearch/hermes-agent/pull/350)) — @Farukest
+
+### Signal
+- Full Signal messenger gateway via signal-cli-rest-api ([#405](https://github.com/NousResearch/hermes-agent/issues/405))
+- Media URL support in message events ([#871](https://github.com/NousResearch/hermes-agent/pull/871))
+
+### Email (IMAP/SMTP)
+- New email gateway platform — @0xbyt4
+
+### Home Assistant
+- REST tools + WebSocket gateway integration ([#184](https://github.com/NousResearch/hermes-agent/pull/184)) — @0xbyt4
+- Service discovery and enhanced setup
+- Toolset mapping fix ([#538](https://github.com/NousResearch/hermes-agent/pull/538)) — @Himess
+
+### Gateway Core
+- Expose subagent tool calls and thinking to users ([#186](https://github.com/NousResearch/hermes-agent/pull/186)) — @cutepawss
+- Configurable background process watcher notifications ([#840](https://github.com/NousResearch/hermes-agent/pull/840))
+- `edit_message()` for Telegram/Discord/Slack with fallback
+- `/compress`, `/usage`, `/update` slash commands
+- Eliminated 3x SQLite message duplication in gateway sessions ([#873](https://github.com/NousResearch/hermes-agent/pull/873))
+- Stabilize system prompt across gateway turns for cache hits ([#754](https://github.com/NousResearch/hermes-agent/pull/754))
+- MCP server shutdown on gateway exit ([#796](https://github.com/NousResearch/hermes-agent/pull/796)) — @0xbyt4
+- Pass session_db to AIAgent, fixing session_search error ([#108](https://github.com/NousResearch/hermes-agent/pull/108)) — @Bartok9
+- Persist transcript changes in /retry, /undo; fix /reset attribute ([#217](https://github.com/NousResearch/hermes-agent/pull/217)) — @Farukest
+- UTF-8 encoding fix preventing Windows crashes ([#369](https://github.com/NousResearch/hermes-agent/pull/369)) — @ch3ronsa
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- Data-driven skin/theme engine — 7 built-in skins (default, ares, mono, slate, poseidon, sisyphus, charizard) + custom YAML skins
+- `/personality` command with custom personality + disable support ([#773](https://github.com/NousResearch/hermes-agent/pull/773)) — @teyrebaz33
+- User-defined quick commands that bypass the agent loop ([#746](https://github.com/NousResearch/hermes-agent/pull/746)) — @teyrebaz33
+- `/reasoning` command for effort level and display toggle ([#921](https://github.com/NousResearch/hermes-agent/pull/921))
+- `/verbose` slash command to toggle debug at runtime ([#94](https://github.com/NousResearch/hermes-agent/pull/94)) — @cesareth
+- `/insights` command — usage analytics, cost estimation & activity patterns ([#552](https://github.com/NousResearch/hermes-agent/pull/552))
+- `/background` command for managing background processes
+- `/help` formatting with command categories
+- Bell-on-complete — terminal bell when agent finishes ([#738](https://github.com/NousResearch/hermes-agent/pull/738))
+- Up/down arrow history navigation
+- Clipboard image paste (Alt+V / Ctrl+V)
+- Loading indicators for slow slash commands ([#882](https://github.com/NousResearch/hermes-agent/pull/882))
+- Spinner flickering fix under patch_stdout ([#91](https://github.com/NousResearch/hermes-agent/pull/91)) — @0xbyt4
+- `--quiet/-Q` flag for programmatic single-query mode
+- `--fuck-it-ship-it` flag to bypass all approval prompts ([#724](https://github.com/NousResearch/hermes-agent/pull/724)) — @dmahan93
+- Tools summary flag ([#767](https://github.com/NousResearch/hermes-agent/pull/767)) — @luisv-1
+- Terminal blinking fix on SSH ([#284](https://github.com/NousResearch/hermes-agent/pull/284)) — @ygd58
+- Multi-line paste detection fix ([#84](https://github.com/NousResearch/hermes-agent/pull/84)) — @0xbyt4
+
+### Setup & Configuration
+- Modular setup wizard with section subcommands and tool-first UX
+- Container resource configuration prompts
+- Backend validation for required binaries
+- Config migration system (currently v7)
+- API keys properly routed to .env instead of config.yaml ([#469](https://github.com/NousResearch/hermes-agent/pull/469)) — @ygd58
+- Atomic write for .env to prevent API key loss on crash ([#954](https://github.com/NousResearch/hermes-agent/pull/954))
+- `hermes tools` — per-platform tool enable/disable with curses UI
+- `hermes doctor` for health checks across all configured providers
+- `hermes update` with auto-restart for gateway service
+- Show update-available notice in CLI banner
+- Multiple named custom providers
+- Shell config detection improvement for PATH setup ([#317](https://github.com/NousResearch/hermes-agent/pull/317)) — @mehmetkr-31
+- Consistent HERMES_HOME and .env path resolution ([#51](https://github.com/NousResearch/hermes-agent/pull/51), [#48](https://github.com/NousResearch/hermes-agent/pull/48)) — @deankerr
+- Docker backend fix on macOS + subagent auth for Nous Portal ([#46](https://github.com/NousResearch/hermes-agent/pull/46)) — @rsavitt
+
+---
+
+## 🔧 Tool System
+
+### MCP (Model Context Protocol)
+- Native MCP client with stdio + HTTP transports ([#291](https://github.com/NousResearch/hermes-agent/pull/291) — @0xbyt4, [#301](https://github.com/NousResearch/hermes-agent/pull/301))
+- Sampling support — server-initiated LLM requests ([#753](https://github.com/NousResearch/hermes-agent/pull/753))
+- Resource and prompt discovery
+- Automatic reconnection and security hardening
+- Banner integration, `/reload-mcp` command
+- `hermes tools` UI integration
+
+### Browser
+- Local browser backend — zero-cost headless Chromium (no Browserbase needed)
+- Console/errors tool, annotated screenshots, auto-recording, dogfood QA skill ([#745](https://github.com/NousResearch/hermes-agent/pull/745))
+- Screenshot sharing via MEDIA: on all messaging platforms ([#657](https://github.com/NousResearch/hermes-agent/pull/657))
+
+### Terminal & Execution
+- `execute_code` sandbox with json_parse, shell_quote, retry helpers
+- Docker: custom volume mounts ([#158](https://github.com/NousResearch/hermes-agent/pull/158)) — @Indelwin
+- Daytona cloud sandbox backend ([#451](https://github.com/NousResearch/hermes-agent/pull/451)) — @rovle
+- SSH backend fix ([#59](https://github.com/NousResearch/hermes-agent/pull/59)) — @deankerr
+- Shell noise filtering and login shell execution for environment consistency
+- Head+tail truncation for execute_code stdout overflow
+- Configurable background process notification modes
+
+### File Operations
+- Filesystem checkpoints and `/rollback` command ([#824](https://github.com/NousResearch/hermes-agent/pull/824))
+- Structured tool result hints (next-action guidance) for patch and search_files ([#722](https://github.com/NousResearch/hermes-agent/issues/722))
+- Docker volumes passed to sandbox container config ([#687](https://github.com/NousResearch/hermes-agent/pull/687)) — @manuelschipper
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- Per-platform skill enable/disable ([#743](https://github.com/NousResearch/hermes-agent/pull/743)) — @teyrebaz33
+- Conditional skill activation based on tool availability ([#785](https://github.com/NousResearch/hermes-agent/pull/785)) — @teyrebaz33
+- Skill prerequisites — hide skills with unmet dependencies ([#659](https://github.com/NousResearch/hermes-agent/pull/659)) — @kshitijk4poor
+- Optional skills — shipped but not activated by default
+- `hermes skills browse` — paginated hub browsing
+- Skills sub-category organization
+- Platform-conditional skill loading
+- Atomic skill file writes ([#551](https://github.com/NousResearch/hermes-agent/pull/551)) — @aydnOktay
+- Skills sync data loss prevention ([#563](https://github.com/NousResearch/hermes-agent/pull/563)) — @0xbyt4
+- Dynamic skill slash commands for CLI and gateway
+
+### New Skills (selected)
+- **ASCII Art** — pyfiglet (571 fonts), cowsay, image-to-ascii ([#209](https://github.com/NousResearch/hermes-agent/pull/209)) — @0xbyt4
+- **ASCII Video** — Full production pipeline ([#854](https://github.com/NousResearch/hermes-agent/pull/854)) — @SHL0MS
+- **DuckDuckGo Search** — Firecrawl fallback ([#267](https://github.com/NousResearch/hermes-agent/pull/267)) — @gamedevCloudy; DDGS API expansion ([#598](https://github.com/NousResearch/hermes-agent/pull/598)) — @areu01or00
+- **Solana Blockchain** — Wallet balances, USD pricing, token names ([#212](https://github.com/NousResearch/hermes-agent/pull/212)) — @gizdusum
+- **AgentMail** — Agent-owned email inboxes ([#330](https://github.com/NousResearch/hermes-agent/pull/330)) — @teyrebaz33
+- **Polymarket** — Prediction market data (read-only) ([#629](https://github.com/NousResearch/hermes-agent/pull/629))
+- **OpenClaw Migration** — Official migration tool ([#570](https://github.com/NousResearch/hermes-agent/pull/570)) — @unmodeled-tyler
+- **Domain Intelligence** — Passive recon: subdomains, SSL, WHOIS, DNS ([#136](https://github.com/NousResearch/hermes-agent/pull/136)) — @FurkanL0
+- **Superpowers** — Software development skills ([#137](https://github.com/NousResearch/hermes-agent/pull/137)) — @kaos35
+- **Hermes-Atropos** — RL environment development skill ([#815](https://github.com/NousResearch/hermes-agent/pull/815))
+- Plus: arXiv search, OCR/documents, Excalidraw diagrams, YouTube transcripts, GIF search, Pokémon player, Minecraft modpack server, OpenHue (Philips Hue), Google Workspace, Notion, PowerPoint, Obsidian, find-nearby, and 40+ MLOps skills
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- Path traversal fix in skill_view — prevented reading arbitrary files ([#220](https://github.com/NousResearch/hermes-agent/issues/220)) — @Farukest
+- Shell injection prevention in sudo password piping ([#65](https://github.com/NousResearch/hermes-agent/pull/65)) — @leonsgithub
+- Dangerous command detection: multiline bypass fix ([#233](https://github.com/NousResearch/hermes-agent/pull/233)) — @Farukest; tee/process substitution patterns ([#280](https://github.com/NousResearch/hermes-agent/pull/280)) — @dogiladeveloper
+- Symlink boundary check fix in skills_guard ([#386](https://github.com/NousResearch/hermes-agent/pull/386)) — @Farukest
+- Symlink bypass fix in write deny list on macOS ([#61](https://github.com/NousResearch/hermes-agent/pull/61)) — @0xbyt4
+- Multi-word prompt injection bypass prevention ([#192](https://github.com/NousResearch/hermes-agent/pull/192)) — @0xbyt4
+- Cron prompt injection scanner bypass fix ([#63](https://github.com/NousResearch/hermes-agent/pull/63)) — @0xbyt4
+- Enforce 0600/0700 file permissions on sensitive files ([#757](https://github.com/NousResearch/hermes-agent/pull/757))
+- .env file permissions restricted to owner-only ([#529](https://github.com/NousResearch/hermes-agent/pull/529)) — @Himess
+- `--force` flag properly blocked from overriding dangerous verdicts ([#388](https://github.com/NousResearch/hermes-agent/pull/388)) — @Farukest
+- FTS5 query sanitization + DB connection leak fix ([#565](https://github.com/NousResearch/hermes-agent/pull/565)) — @0xbyt4
+- Expand secret redaction patterns + config toggle to disable
+- In-memory permanent allowlist to prevent data leak ([#600](https://github.com/NousResearch/hermes-agent/pull/600)) — @alireza78a
+
+### Atomic Writes (data loss prevention)
+- sessions.json ([#611](https://github.com/NousResearch/hermes-agent/pull/611)) — @alireza78a
+- Cron jobs ([#146](https://github.com/NousResearch/hermes-agent/pull/146)) — @alireza78a
+- .env config ([#954](https://github.com/NousResearch/hermes-agent/pull/954))
+- Process checkpoints ([#298](https://github.com/NousResearch/hermes-agent/pull/298)) — @aydnOktay
+- Batch runner ([#297](https://github.com/NousResearch/hermes-agent/pull/297)) — @aydnOktay
+- Skill files ([#551](https://github.com/NousResearch/hermes-agent/pull/551)) — @aydnOktay
+
+### Reliability
+- Guard all print() against OSError for systemd/headless environments ([#963](https://github.com/NousResearch/hermes-agent/pull/963))
+- Reset all retry counters at start of run_conversation ([#607](https://github.com/NousResearch/hermes-agent/pull/607)) — @0xbyt4
+- Return deny on approval callback timeout instead of None ([#603](https://github.com/NousResearch/hermes-agent/pull/603)) — @0xbyt4
+- Fix None message content crashes across codebase ([#277](https://github.com/NousResearch/hermes-agent/pull/277))
+- Fix context overrun crash with local LLM backends ([#403](https://github.com/NousResearch/hermes-agent/pull/403)) — @ch3ronsa
+- Prevent `_flush_sentinel` from leaking to external APIs ([#227](https://github.com/NousResearch/hermes-agent/pull/227)) — @Farukest
+- Prevent conversation_history mutation in callers ([#229](https://github.com/NousResearch/hermes-agent/pull/229)) — @Farukest
+- Fix systemd restart loop ([#614](https://github.com/NousResearch/hermes-agent/pull/614)) — @voidborne-d
+- Close file handles and sockets to prevent fd leaks ([#568](https://github.com/NousResearch/hermes-agent/pull/568) — @alireza78a, [#296](https://github.com/NousResearch/hermes-agent/pull/296) — @alireza78a, [#709](https://github.com/NousResearch/hermes-agent/pull/709) — @memosr)
+- Prevent data loss in clipboard PNG conversion ([#602](https://github.com/NousResearch/hermes-agent/pull/602)) — @0xbyt4
+- Eliminate shell noise from terminal output ([#293](https://github.com/NousResearch/hermes-agent/pull/293)) — @0xbyt4
+- Timezone-aware now() for prompt, cron, and execute_code ([#309](https://github.com/NousResearch/hermes-agent/pull/309)) — @areu01or00
+
+### Windows Compatibility
+- Guard POSIX-only process functions ([#219](https://github.com/NousResearch/hermes-agent/pull/219)) — @Farukest
+- Windows native support via Git Bash + ZIP-based update fallback
+- pywinpty for PTY support ([#457](https://github.com/NousResearch/hermes-agent/pull/457)) — @shitcoinsherpa
+- Explicit UTF-8 encoding on all config/data file I/O ([#458](https://github.com/NousResearch/hermes-agent/pull/458)) — @shitcoinsherpa
+- Windows-compatible path handling ([#354](https://github.com/NousResearch/hermes-agent/pull/354), [#390](https://github.com/NousResearch/hermes-agent/pull/390)) — @Farukest
+- Regex-based search output parsing for drive-letter paths ([#533](https://github.com/NousResearch/hermes-agent/pull/533)) — @Himess
+- Auth store file lock for Windows ([#455](https://github.com/NousResearch/hermes-agent/pull/455)) — @shitcoinsherpa
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- Fix DeepSeek V3 tool call parser silently dropping multi-line JSON arguments ([#444](https://github.com/NousResearch/hermes-agent/pull/444)) — @PercyDikec
+- Fix gateway transcript losing 1 message per turn due to offset mismatch ([#395](https://github.com/NousResearch/hermes-agent/pull/395)) — @PercyDikec
+- Fix /retry command silently discarding the agent's final response ([#441](https://github.com/NousResearch/hermes-agent/pull/441)) — @PercyDikec
+- Fix max-iterations retry returning empty string after think-block stripping ([#438](https://github.com/NousResearch/hermes-agent/pull/438)) — @PercyDikec
+- Fix max-iterations retry using hardcoded max_tokens ([#436](https://github.com/NousResearch/hermes-agent/pull/436)) — @Farukest
+- Fix Codex status dict key mismatch ([#448](https://github.com/NousResearch/hermes-agent/pull/448)) and visibility filter ([#446](https://github.com/NousResearch/hermes-agent/pull/446)) — @PercyDikec
+- Strip \<think\> blocks from final user-facing responses ([#174](https://github.com/NousResearch/hermes-agent/pull/174)) — @Bartok9
+- Fix \<think\> block regex stripping visible content when model discusses tags literally ([#786](https://github.com/NousResearch/hermes-agent/issues/786))
+- Fix Mistral 422 errors from leftover finish_reason in assistant messages ([#253](https://github.com/NousResearch/hermes-agent/pull/253)) — @Sertug17
+- Fix OPENROUTER_API_KEY resolution order across all code paths ([#295](https://github.com/NousResearch/hermes-agent/pull/295)) — @0xbyt4
+- Fix OPENAI_BASE_URL API key priority ([#420](https://github.com/NousResearch/hermes-agent/pull/420)) — @manuelschipper
+- Fix Anthropic "prompt is too long" 400 error not detected as context length error ([#813](https://github.com/NousResearch/hermes-agent/issues/813))
+- Fix SQLite session transcript accumulating duplicate messages — 3-4x token inflation ([#860](https://github.com/NousResearch/hermes-agent/issues/860))
+- Fix setup wizard skipping API key prompts on first install ([#748](https://github.com/NousResearch/hermes-agent/pull/748))
+- Fix setup wizard showing OpenRouter model list for Nous Portal ([#575](https://github.com/NousResearch/hermes-agent/pull/575)) — @PercyDikec
+- Fix provider selection not persisting when switching via hermes model ([#881](https://github.com/NousResearch/hermes-agent/pull/881))
+- Fix Docker backend failing when docker not in PATH on macOS ([#889](https://github.com/NousResearch/hermes-agent/pull/889))
+- Fix ClawHub Skills Hub adapter for API endpoint changes ([#286](https://github.com/NousResearch/hermes-agent/pull/286)) — @BP602
+- Fix Honcho auto-enable when API key is present ([#243](https://github.com/NousResearch/hermes-agent/pull/243)) — @Bartok9
+- Fix duplicate 'skills' subparser crash on Python 3.11+ ([#898](https://github.com/NousResearch/hermes-agent/issues/898))
+- Fix memory tool entry parsing when content contains section sign ([#162](https://github.com/NousResearch/hermes-agent/pull/162)) — @aydnOktay
+- Fix piped install silently aborting when interactive prompts fail ([#72](https://github.com/NousResearch/hermes-agent/pull/72)) — @cutepawss
+- Fix false positives in recursive delete detection ([#68](https://github.com/NousResearch/hermes-agent/pull/68)) — @cutepawss
+- Fix Ruff lint warnings across codebase ([#608](https://github.com/NousResearch/hermes-agent/pull/608)) — @JackTheGit
+- Fix Anthropic native base URL fail-fast ([#173](https://github.com/NousResearch/hermes-agent/pull/173)) — @adavyas
+- Fix install.sh creating ~/.hermes before moving Node.js directory ([#53](https://github.com/NousResearch/hermes-agent/pull/53)) — @JoshuaMart
+- Fix SystemExit traceback during atexit cleanup on Ctrl+C ([#55](https://github.com/NousResearch/hermes-agent/pull/55)) — @bierlingm
+- Restore missing MIT license file ([#620](https://github.com/NousResearch/hermes-agent/pull/620)) — @stablegenius49
+
+---
+
+## 🧪 Testing
+
+- **3,289 tests** across agent, gateway, tools, cron, and CLI
+- Parallelized test suite with pytest-xdist ([#802](https://github.com/NousResearch/hermes-agent/pull/802)) — @OutThisLife
+- Unit tests batch 1: 8 core modules ([#60](https://github.com/NousResearch/hermes-agent/pull/60)) — @0xbyt4
+- Unit tests batch 2: 8 more modules ([#62](https://github.com/NousResearch/hermes-agent/pull/62)) — @0xbyt4
+- Unit tests batch 3: 8 untested modules ([#191](https://github.com/NousResearch/hermes-agent/pull/191)) — @0xbyt4
+- Unit tests batch 4: 5 security/logic-critical modules ([#193](https://github.com/NousResearch/hermes-agent/pull/193)) — @0xbyt4
+- AIAgent (run_agent.py) unit tests ([#67](https://github.com/NousResearch/hermes-agent/pull/67)) — @0xbyt4
+- Trajectory compressor tests ([#203](https://github.com/NousResearch/hermes-agent/pull/203)) — @0xbyt4
+- Clarify tool tests ([#121](https://github.com/NousResearch/hermes-agent/pull/121)) — @Bartok9
+- Telegram format tests — 43 tests for italic/bold/code rendering ([#204](https://github.com/NousResearch/hermes-agent/pull/204)) — @0xbyt4
+- Vision tools type hints + 42 tests ([#792](https://github.com/NousResearch/hermes-agent/pull/792))
+- Compressor tool-call boundary regression tests ([#648](https://github.com/NousResearch/hermes-agent/pull/648)) — @intertwine
+- Test structure reorganization ([#34](https://github.com/NousResearch/hermes-agent/pull/34)) — @0xbyt4
+- Shell noise elimination + fix 36 test failures ([#293](https://github.com/NousResearch/hermes-agent/pull/293)) — @0xbyt4
+
+---
+
+## 🔬 RL & Evaluation Environments
+
+- WebResearchEnv — Multi-step web research RL environment ([#434](https://github.com/NousResearch/hermes-agent/pull/434)) — @jackx707
+- Modal sandbox concurrency limits to avoid deadlocks ([#621](https://github.com/NousResearch/hermes-agent/pull/621)) — @voteblake
+- Hermes-atropos-environments bundled skill ([#815](https://github.com/NousResearch/hermes-agent/pull/815))
+- Local vLLM instance support for evaluation — @dmahan93
+- YC-Bench long-horizon agent benchmark environment
+- OpenThoughts-TBLite evaluation environment and scripts
+
+---
+
+## 📚 Documentation
+
+- Full documentation website (Docusaurus) with 37+ pages
+- Comprehensive platform setup guides for Telegram, Discord, Slack, WhatsApp, Signal, Email
+- AGENTS.md — development guide for AI coding assistants
+- CONTRIBUTING.md ([#117](https://github.com/NousResearch/hermes-agent/pull/117)) — @Bartok9
+- Slash commands reference ([#142](https://github.com/NousResearch/hermes-agent/pull/142)) — @Bartok9
+- Comprehensive AGENTS.md accuracy audit ([#732](https://github.com/NousResearch/hermes-agent/pull/732))
+- Skin/theme system documentation
+- MCP documentation and examples
+- Docs accuracy audit — 35+ corrections
+- Documentation typo fixes ([#825](https://github.com/NousResearch/hermes-agent/pull/825), [#439](https://github.com/NousResearch/hermes-agent/pull/439)) — @JackTheGit
+- CLI config precedence and terminology standardization ([#166](https://github.com/NousResearch/hermes-agent/pull/166), [#167](https://github.com/NousResearch/hermes-agent/pull/167), [#168](https://github.com/NousResearch/hermes-agent/pull/168)) — @Jr-kenny
+- Telegram token regex documentation ([#713](https://github.com/NousResearch/hermes-agent/pull/713)) — @VolodymyrBg
+
+---
+
+## 👥 Contributors
+
+Thank you to the 63 contributors who made this release possible! In just over two weeks, the Hermes Agent community came together to ship an extraordinary amount of work.
+
+### Core
+- **@teknium1** — 43 PRs: Project lead, core architecture, provider router, sessions, skills, CLI, documentation
+
+### Top Community Contributors
+- **@0xbyt4** — 40 PRs: MCP client, Home Assistant, security fixes (symlink, prompt injection, cron), extensive test coverage (6 batches), ascii-art skill, shell noise elimination, skills sync, Telegram formatting, and dozens more
+- **@Farukest** — 16 PRs: Security hardening (path traversal, dangerous command detection, symlink boundary), Windows compatibility (POSIX guards, path handling), WhatsApp fixes, max-iterations retry, gateway fixes
+- **@aydnOktay** — 11 PRs: Atomic writes (process checkpoints, batch runner, skill files), error handling improvements across Telegram, Discord, code execution, transcription, TTS, and skills
+- **@Bartok9** — 9 PRs: CONTRIBUTING.md, slash commands reference, Discord channel topics, think-block stripping, TTS fix, Honcho fix, session count fix, clarify tests
+- **@PercyDikec** — 7 PRs: DeepSeek V3 parser fix, /retry response discard, gateway transcript offset, Codex status/visibility, max-iterations retry, setup wizard fix
+- **@teyrebaz33** — 5 PRs: Skills enable/disable system, quick commands, personality customization, conditional skill activation
+- **@alireza78a** — 5 PRs: Atomic writes (cron, sessions), fd leak prevention, security allowlist, code execution socket cleanup
+- **@shitcoinsherpa** — 3 PRs: Windows support (pywinpty, UTF-8 encoding, auth store lock)
+- **@Himess** — 3 PRs: Cron/HomeAssistant/Daytona fix, Windows drive-letter parsing, .env permissions
+- **@satelerd** — 2 PRs: WhatsApp native media, multi-user session isolation
+- **@rovle** — 1 PR: Daytona cloud sandbox backend (4 commits)
+- **@erosika** — 1 PR: Honcho AI-native memory integration
+- **@dmahan93** — 1 PR: --fuck-it-ship-it flag + RL environment work
+- **@SHL0MS** — 1 PR: ASCII video skill
+
+### All Contributors
+@0xbyt4, @BP602, @Bartok9, @Farukest, @FurkanL0, @Himess, @Indelwin, @JackTheGit, @JoshuaMart, @Jr-kenny, @OutThisLife, @PercyDikec, @SHL0MS, @Sertug17, @VencentSoliman, @VolodymyrBg, @adavyas, @alireza78a, @areu01or00, @aydnOktay, @batuhankocyigit, @bierlingm, @caentzminger, @cesareth, @ch3ronsa, @christomitov, @cutepawss, @deankerr, @dmahan93, @dogiladeveloper, @dragonkhoi, @erosika, @gamedevCloudy, @gizdusum, @grp06, @intertwine, @jackx707, @jdblackstar, @johnh4098, @kaos35, @kshitijk4poor, @leonsgithub, @luisv-1, @manuelschipper, @mehmetkr-31, @memosr, @PeterFile, @rewbs, @rovle, @rsavitt, @satelerd, @spanishflu-est1918, @stablegenius49, @tars90percent, @tekelala, @teknium1, @teyrebaz33, @tripledoublev, @unmodeled-tyler, @voidborne-d, @voteblake, @ygd58
+
+---
+
+**Full Changelog**: [v0.1.0...v2026.3.12](https://github.com/NousResearch/hermes-agent/compare/v0.1.0...v2026.3.12)
@@ -0,0 +1,377 @@
+# Hermes Agent v0.3.0 (v2026.3.17)
+
+**Release Date:** March 17, 2026
+
+> The streaming, plugins, and provider release — unified real-time token delivery, first-class plugin architecture, rebuilt provider system with Vercel AI Gateway, native Anthropic provider, smart approvals, live Chrome CDP browser connect, ACP IDE integration, Honcho memory, voice mode, persistent shell, and 50+ bug fixes across every platform.
+
+---
+
+## ✨ Highlights
+
+- **Unified Streaming Infrastructure** — Real-time token-by-token delivery in CLI and all gateway platforms. Responses stream as they're generated instead of arriving as a block. ([#1538](https://github.com/NousResearch/hermes-agent/pull/1538))
+
+- **First-Class Plugin Architecture** — Drop Python files into `~/.hermes/plugins/` to extend Hermes with custom tools, commands, and hooks. No forking required. ([#1544](https://github.com/NousResearch/hermes-agent/pull/1544), [#1555](https://github.com/NousResearch/hermes-agent/pull/1555))
+
+- **Native Anthropic Provider** — Direct Anthropic API calls with Claude Code credential auto-discovery, OAuth PKCE flows, and native prompt caching. No OpenRouter middleman needed. ([#1097](https://github.com/NousResearch/hermes-agent/pull/1097))
+
+- **Smart Approvals + /stop Command** — Codex-inspired approval system that learns which commands are safe and remembers your preferences. `/stop` kills the current agent run immediately. ([#1543](https://github.com/NousResearch/hermes-agent/pull/1543))
+
+- **Honcho Memory Integration** — Async memory writes, configurable recall modes, session title integration, and multi-user isolation in gateway mode. By @erosika. ([#736](https://github.com/NousResearch/hermes-agent/pull/736))
+
+- **Voice Mode** — Push-to-talk in CLI, voice notes in Telegram/Discord, Discord voice channel support, and local Whisper transcription via faster-whisper. ([#1299](https://github.com/NousResearch/hermes-agent/pull/1299), [#1185](https://github.com/NousResearch/hermes-agent/pull/1185), [#1429](https://github.com/NousResearch/hermes-agent/pull/1429))
+
+- **Concurrent Tool Execution** — Multiple independent tool calls now run in parallel via ThreadPoolExecutor, significantly reducing latency for multi-tool turns. ([#1152](https://github.com/NousResearch/hermes-agent/pull/1152))
+
+- **PII Redaction** — When `privacy.redact_pii` is enabled, personally identifiable information is automatically scrubbed before sending context to LLM providers. ([#1542](https://github.com/NousResearch/hermes-agent/pull/1542))
+
+- **`/browser connect` via CDP** — Attach browser tools to a live Chrome instance through Chrome DevTools Protocol. Debug, inspect, and interact with pages you already have open. ([#1549](https://github.com/NousResearch/hermes-agent/pull/1549))
+
+- **Vercel AI Gateway Provider** — Route Hermes through Vercel's AI Gateway for access to their model catalog and infrastructure. ([#1628](https://github.com/NousResearch/hermes-agent/pull/1628))
+
+- **Centralized Provider Router** — Rebuilt provider system with `call_llm` API, unified `/model` command, auto-detect provider on model switch, and direct endpoint overrides for auxiliary/delegation clients. ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003), [#1506](https://github.com/NousResearch/hermes-agent/pull/1506), [#1375](https://github.com/NousResearch/hermes-agent/pull/1375))
+
+- **ACP Server (IDE Integration)** — VS Code, Zed, and JetBrains can now connect to Hermes as an agent backend, with full slash command support. ([#1254](https://github.com/NousResearch/hermes-agent/pull/1254), [#1532](https://github.com/NousResearch/hermes-agent/pull/1532))
+
+- **Persistent Shell Mode** — Local and SSH terminal backends can maintain shell state across tool calls — cd, env vars, and aliases persist. By @alt-glitch. ([#1067](https://github.com/NousResearch/hermes-agent/pull/1067), [#1483](https://github.com/NousResearch/hermes-agent/pull/1483))
+
+- **Agentic On-Policy Distillation (OPD)** — New RL training environment for distilling agent policies, expanding the Atropos training ecosystem. ([#1149](https://github.com/NousResearch/hermes-agent/pull/1149))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### Provider & Model Support
+- **Centralized provider router** with `call_llm` API and unified `/model` command — switch models and providers seamlessly ([#1003](https://github.com/NousResearch/hermes-agent/pull/1003))
+- **Vercel AI Gateway** provider support ([#1628](https://github.com/NousResearch/hermes-agent/pull/1628))
+- **Auto-detect provider** when switching models via `/model` ([#1506](https://github.com/NousResearch/hermes-agent/pull/1506))
+- **Direct endpoint overrides** for auxiliary and delegation clients — point vision/subagent calls at specific endpoints ([#1375](https://github.com/NousResearch/hermes-agent/pull/1375))
+- **Native Anthropic auxiliary vision** — use Claude's native vision API instead of routing through OpenAI-compatible endpoints ([#1377](https://github.com/NousResearch/hermes-agent/pull/1377))
+- Anthropic OAuth flow improvements — auto-run `claude setup-token`, reauthentication, PKCE state persistence, identity fingerprinting ([#1132](https://github.com/NousResearch/hermes-agent/pull/1132), [#1360](https://github.com/NousResearch/hermes-agent/pull/1360), [#1396](https://github.com/NousResearch/hermes-agent/pull/1396), [#1597](https://github.com/NousResearch/hermes-agent/pull/1597))
+- Fix adaptive thinking without `budget_tokens` for Claude 4.6 models — by @ASRagab ([#1128](https://github.com/NousResearch/hermes-agent/pull/1128))
+- Fix Anthropic cache markers through adapter — by @brandtcormorant ([#1216](https://github.com/NousResearch/hermes-agent/pull/1216))
+- Retry Anthropic 429/529 errors and surface details to users — by @0xbyt4 ([#1585](https://github.com/NousResearch/hermes-agent/pull/1585))
+- Fix Anthropic adapter max_tokens, fallback crash, proxy base_url — by @0xbyt4 ([#1121](https://github.com/NousResearch/hermes-agent/pull/1121))
+- Fix DeepSeek V3 parser dropping multiple parallel tool calls — by @mr-emmett-one ([#1365](https://github.com/NousResearch/hermes-agent/pull/1365), [#1300](https://github.com/NousResearch/hermes-agent/pull/1300))
+- Accept unlisted models with warning instead of rejecting ([#1047](https://github.com/NousResearch/hermes-agent/pull/1047), [#1102](https://github.com/NousResearch/hermes-agent/pull/1102))
+- Skip reasoning params for unsupported OpenRouter models ([#1485](https://github.com/NousResearch/hermes-agent/pull/1485))
+- MiniMax Anthropic API compatibility fix ([#1623](https://github.com/NousResearch/hermes-agent/pull/1623))
+- Custom endpoint `/models` verification and `/v1` base URL suggestion ([#1480](https://github.com/NousResearch/hermes-agent/pull/1480))
+- Resolve delegation providers from `custom_providers` config ([#1328](https://github.com/NousResearch/hermes-agent/pull/1328))
+- Kimi model additions and User-Agent fix ([#1039](https://github.com/NousResearch/hermes-agent/pull/1039))
+- Strip `call_id`/`response_item_id` for Mistral compatibility ([#1058](https://github.com/NousResearch/hermes-agent/pull/1058))
+
+### Agent Loop & Conversation
+- **Anthropic Context Editing API** support ([#1147](https://github.com/NousResearch/hermes-agent/pull/1147))
+- Improved context compaction handoff summaries — compressor now preserves more actionable state ([#1273](https://github.com/NousResearch/hermes-agent/pull/1273))
+- Sync session_id after mid-run context compression ([#1160](https://github.com/NousResearch/hermes-agent/pull/1160))
+- Session hygiene threshold tuned to 50% for more proactive compression ([#1096](https://github.com/NousResearch/hermes-agent/pull/1096), [#1161](https://github.com/NousResearch/hermes-agent/pull/1161))
+- Include session ID in system prompt via `--pass-session-id` flag ([#1040](https://github.com/NousResearch/hermes-agent/pull/1040))
+- Prevent closed OpenAI client reuse across retries ([#1391](https://github.com/NousResearch/hermes-agent/pull/1391))
+- Sanitize chat payloads and provider precedence ([#1253](https://github.com/NousResearch/hermes-agent/pull/1253))
+- Handle dict tool call arguments from Codex and local backends ([#1393](https://github.com/NousResearch/hermes-agent/pull/1393), [#1440](https://github.com/NousResearch/hermes-agent/pull/1440))
+
+### Memory & Sessions
+- **Improve memory prioritization** — user preferences and corrections weighted above procedural knowledge ([#1548](https://github.com/NousResearch/hermes-agent/pull/1548))
+- Tighter memory and session recall guidance in system prompts ([#1329](https://github.com/NousResearch/hermes-agent/pull/1329))
+- Persist CLI token counts to session DB for `/insights` ([#1498](https://github.com/NousResearch/hermes-agent/pull/1498))
+- Keep Honcho recall out of the cached system prefix ([#1201](https://github.com/NousResearch/hermes-agent/pull/1201))
+- Correct `seed_ai_identity` to use `session.add_messages()` ([#1475](https://github.com/NousResearch/hermes-agent/pull/1475))
+- Isolate Honcho session routing for multi-user gateway ([#1500](https://github.com/NousResearch/hermes-agent/pull/1500))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### Gateway Core
+- **System gateway service mode** — run as a system-level systemd service, not just user-level ([#1371](https://github.com/NousResearch/hermes-agent/pull/1371))
+- **Gateway install scope prompts** — choose user vs system scope during setup ([#1374](https://github.com/NousResearch/hermes-agent/pull/1374))
+- **Reasoning hot reload** — change reasoning settings without restarting the gateway ([#1275](https://github.com/NousResearch/hermes-agent/pull/1275))
+- Default group sessions to per-user isolation — no more shared state across users in group chats ([#1495](https://github.com/NousResearch/hermes-agent/pull/1495), [#1417](https://github.com/NousResearch/hermes-agent/pull/1417))
+- Harden gateway restart recovery ([#1310](https://github.com/NousResearch/hermes-agent/pull/1310))
+- Cancel active runs during shutdown ([#1427](https://github.com/NousResearch/hermes-agent/pull/1427))
+- SSL certificate auto-detection for NixOS and non-standard systems ([#1494](https://github.com/NousResearch/hermes-agent/pull/1494))
+- Auto-detect D-Bus session bus for `systemctl --user` on headless servers ([#1601](https://github.com/NousResearch/hermes-agent/pull/1601))
+- Auto-enable systemd linger during gateway install on headless servers ([#1334](https://github.com/NousResearch/hermes-agent/pull/1334))
+- Fall back to module entrypoint when `hermes` is not on PATH ([#1355](https://github.com/NousResearch/hermes-agent/pull/1355))
+- Fix dual gateways on macOS launchd after `hermes update` ([#1567](https://github.com/NousResearch/hermes-agent/pull/1567))
+- Remove recursive ExecStop from systemd units ([#1530](https://github.com/NousResearch/hermes-agent/pull/1530))
+- Prevent logging handler accumulation in gateway mode ([#1251](https://github.com/NousResearch/hermes-agent/pull/1251))
+- Restart on retryable startup failures — by @jplew ([#1517](https://github.com/NousResearch/hermes-agent/pull/1517))
+- Backfill model on gateway sessions after agent runs ([#1306](https://github.com/NousResearch/hermes-agent/pull/1306))
+- PID-based gateway kill and deferred config write ([#1499](https://github.com/NousResearch/hermes-agent/pull/1499))
+
+### Telegram
+- Buffer media groups to prevent self-interruption from photo bursts ([#1341](https://github.com/NousResearch/hermes-agent/pull/1341), [#1422](https://github.com/NousResearch/hermes-agent/pull/1422))
+- Retry on transient TLS failures during connect and send ([#1535](https://github.com/NousResearch/hermes-agent/pull/1535))
+- Harden polling conflict handling ([#1339](https://github.com/NousResearch/hermes-agent/pull/1339))
+- Escape chunk indicators and inline code in MarkdownV2 ([#1478](https://github.com/NousResearch/hermes-agent/pull/1478), [#1626](https://github.com/NousResearch/hermes-agent/pull/1626))
+- Check updater/app state before disconnect ([#1389](https://github.com/NousResearch/hermes-agent/pull/1389))
+
+### Discord
+- `/thread` command with `auto_thread` config and media metadata fixes ([#1178](https://github.com/NousResearch/hermes-agent/pull/1178))
+- Auto-thread on @mention, skip mention text in bot threads ([#1438](https://github.com/NousResearch/hermes-agent/pull/1438))
+- Retry without reply reference for system messages ([#1385](https://github.com/NousResearch/hermes-agent/pull/1385))
+- Preserve native document and video attachment support ([#1392](https://github.com/NousResearch/hermes-agent/pull/1392))
+- Defer discord adapter annotations to avoid optional import crashes ([#1314](https://github.com/NousResearch/hermes-agent/pull/1314))
+
+### Slack
+- Thread handling overhaul — progress messages, responses, and session isolation all respect threads ([#1103](https://github.com/NousResearch/hermes-agent/pull/1103))
+- Formatting, reactions, user resolution, and command improvements ([#1106](https://github.com/NousResearch/hermes-agent/pull/1106))
+- Fix MAX_MESSAGE_LENGTH 3900 → 39000 ([#1117](https://github.com/NousResearch/hermes-agent/pull/1117))
+- File upload fallback preserves thread context — by @0xbyt4 ([#1122](https://github.com/NousResearch/hermes-agent/pull/1122))
+- Improve setup guidance ([#1387](https://github.com/NousResearch/hermes-agent/pull/1387))
+
+### Email
+- Fix IMAP UID tracking and SMTP TLS verification ([#1305](https://github.com/NousResearch/hermes-agent/pull/1305))
+- Add `skip_attachments` option via config.yaml ([#1536](https://github.com/NousResearch/hermes-agent/pull/1536))
+
+### Home Assistant
+- Event filtering closed by default ([#1169](https://github.com/NousResearch/hermes-agent/pull/1169))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### Interactive CLI
+- **Persistent CLI status bar** — always-visible model, provider, and token counts ([#1522](https://github.com/NousResearch/hermes-agent/pull/1522))
+- **File path autocomplete** in the input prompt ([#1545](https://github.com/NousResearch/hermes-agent/pull/1545))
+- **`/plan` command** — generate implementation plans from specs ([#1372](https://github.com/NousResearch/hermes-agent/pull/1372), [#1381](https://github.com/NousResearch/hermes-agent/pull/1381))
+- **Major `/rollback` improvements** — richer checkpoint history, clearer UX ([#1505](https://github.com/NousResearch/hermes-agent/pull/1505))
+- **Preload CLI skills on launch** — skills are ready before the first prompt ([#1359](https://github.com/NousResearch/hermes-agent/pull/1359))
+- **Centralized slash command registry** — all commands defined once, consumed everywhere ([#1603](https://github.com/NousResearch/hermes-agent/pull/1603))
+- `/bg` alias for `/background` ([#1590](https://github.com/NousResearch/hermes-agent/pull/1590))
+- Prefix matching for slash commands — `/mod` resolves to `/model` ([#1320](https://github.com/NousResearch/hermes-agent/pull/1320))
+- `/new`, `/reset`, `/clear` now start genuinely fresh sessions ([#1237](https://github.com/NousResearch/hermes-agent/pull/1237))
+- Accept session ID prefixes for session actions ([#1425](https://github.com/NousResearch/hermes-agent/pull/1425))
+- TUI prompt and accent output now respect active skin ([#1282](https://github.com/NousResearch/hermes-agent/pull/1282))
+- Centralize tool emoji metadata in registry + skin integration ([#1484](https://github.com/NousResearch/hermes-agent/pull/1484))
+- "View full command" option added to dangerous command approval — by @teknium1 based on design by community ([#887](https://github.com/NousResearch/hermes-agent/pull/887))
+- Non-blocking startup update check and banner deduplication ([#1386](https://github.com/NousResearch/hermes-agent/pull/1386))
+- `/reasoning` command output ordering and inline think extraction fixes ([#1031](https://github.com/NousResearch/hermes-agent/pull/1031))
+- Verbose mode shows full untruncated output ([#1472](https://github.com/NousResearch/hermes-agent/pull/1472))
+- Fix `/status` to report live state and tokens ([#1476](https://github.com/NousResearch/hermes-agent/pull/1476))
+- Seed a default global SOUL.md ([#1311](https://github.com/NousResearch/hermes-agent/pull/1311))
+
+### Setup & Configuration
+- **OpenClaw migration** during first-time setup — by @kshitijk4poor ([#981](https://github.com/NousResearch/hermes-agent/pull/981))
+- `hermes claw migrate` command + migration docs ([#1059](https://github.com/NousResearch/hermes-agent/pull/1059))
+- Smart vision setup that respects the user's chosen provider ([#1323](https://github.com/NousResearch/hermes-agent/pull/1323))
+- Handle headless setup flows end-to-end ([#1274](https://github.com/NousResearch/hermes-agent/pull/1274))
+- Prefer curses over `simple_term_menu` in setup.py ([#1487](https://github.com/NousResearch/hermes-agent/pull/1487))
+- Show effective model and provider in `/status` ([#1284](https://github.com/NousResearch/hermes-agent/pull/1284))
+- Config set examples use placeholder syntax ([#1322](https://github.com/NousResearch/hermes-agent/pull/1322))
+- Reload .env over stale shell overrides ([#1434](https://github.com/NousResearch/hermes-agent/pull/1434))
+- Fix is_coding_plan NameError crash — by @0xbyt4 ([#1123](https://github.com/NousResearch/hermes-agent/pull/1123))
+- Add missing packages to setuptools config — by @alt-glitch ([#912](https://github.com/NousResearch/hermes-agent/pull/912))
+- Installer: clarify why sudo is needed at every prompt ([#1602](https://github.com/NousResearch/hermes-agent/pull/1602))
+
+---
+
+## 🔧 Tool System
+
+### Terminal & Execution
+- **Persistent shell mode** for local and SSH backends — maintain shell state across tool calls — by @alt-glitch ([#1067](https://github.com/NousResearch/hermes-agent/pull/1067), [#1483](https://github.com/NousResearch/hermes-agent/pull/1483))
+- **Tirith pre-exec command scanning** — security layer that analyzes commands before execution ([#1256](https://github.com/NousResearch/hermes-agent/pull/1256))
+- Strip Hermes provider env vars from all subprocess environments ([#1157](https://github.com/NousResearch/hermes-agent/pull/1157), [#1172](https://github.com/NousResearch/hermes-agent/pull/1172), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399), [#1419](https://github.com/NousResearch/hermes-agent/pull/1419)) — initial fix by @eren-karakus0
+- SSH preflight check ([#1486](https://github.com/NousResearch/hermes-agent/pull/1486))
+- Docker backend: make cwd workspace mount explicit opt-in ([#1534](https://github.com/NousResearch/hermes-agent/pull/1534))
+- Add project root to PYTHONPATH in execute_code sandbox ([#1383](https://github.com/NousResearch/hermes-agent/pull/1383))
+- Eliminate execute_code progress spam on gateway platforms ([#1098](https://github.com/NousResearch/hermes-agent/pull/1098))
+- Clearer docker backend preflight errors ([#1276](https://github.com/NousResearch/hermes-agent/pull/1276))
+
+### Browser
+- **`/browser connect`** — attach browser tools to a live Chrome instance via CDP ([#1549](https://github.com/NousResearch/hermes-agent/pull/1549))
+- Improve browser cleanup, local browser PATH setup, and screenshot recovery ([#1333](https://github.com/NousResearch/hermes-agent/pull/1333))
+
+### MCP
+- **Selective tool loading** with utility policies — filter which MCP tools are available ([#1302](https://github.com/NousResearch/hermes-agent/pull/1302))
+- Auto-reload MCP tools when `mcp_servers` config changes without restart ([#1474](https://github.com/NousResearch/hermes-agent/pull/1474))
+- Resolve npx stdio connection failures ([#1291](https://github.com/NousResearch/hermes-agent/pull/1291))
+- Preserve MCP toolsets when saving platform tool config ([#1421](https://github.com/NousResearch/hermes-agent/pull/1421))
+
+### Vision
+- Unify vision backend gating ([#1367](https://github.com/NousResearch/hermes-agent/pull/1367))
+- Surface actual error reason instead of generic message ([#1338](https://github.com/NousResearch/hermes-agent/pull/1338))
+- Make Claude image handling work end-to-end ([#1408](https://github.com/NousResearch/hermes-agent/pull/1408))
+
+### Cron
+- **Compress cron management into one tool** — single `cronjob` tool replaces multiple commands ([#1343](https://github.com/NousResearch/hermes-agent/pull/1343))
+- Suppress duplicate cron sends to auto-delivery targets ([#1357](https://github.com/NousResearch/hermes-agent/pull/1357))
+- Persist cron sessions to SQLite ([#1255](https://github.com/NousResearch/hermes-agent/pull/1255))
+- Per-job runtime overrides (provider, model, base_url) ([#1398](https://github.com/NousResearch/hermes-agent/pull/1398))
+- Atomic write in `save_job_output` to prevent data loss on crash ([#1173](https://github.com/NousResearch/hermes-agent/pull/1173))
+- Preserve thread context for `deliver=origin` ([#1437](https://github.com/NousResearch/hermes-agent/pull/1437))
+
+### Patch Tool
+- Avoid corrupting pipe chars in V4A patch apply ([#1286](https://github.com/NousResearch/hermes-agent/pull/1286))
+- Permissive `block_anchor` thresholds and unicode normalization ([#1539](https://github.com/NousResearch/hermes-agent/pull/1539))
+
+### Delegation
+- Add observability metadata to subagent results (model, tokens, duration, tool trace) ([#1175](https://github.com/NousResearch/hermes-agent/pull/1175))
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System
+- **Integrate skills.sh** as a hub source alongside ClawHub ([#1303](https://github.com/NousResearch/hermes-agent/pull/1303))
+- Secure skill env setup on load ([#1153](https://github.com/NousResearch/hermes-agent/pull/1153))
+- Honor policy table for dangerous verdicts ([#1330](https://github.com/NousResearch/hermes-agent/pull/1330))
+- Harden ClawHub skill search exact matches ([#1400](https://github.com/NousResearch/hermes-agent/pull/1400))
+- Fix ClawHub skill install — use `/download` ZIP endpoint ([#1060](https://github.com/NousResearch/hermes-agent/pull/1060))
+- Avoid mislabeling local skills as builtin — by @arceus77-7 ([#862](https://github.com/NousResearch/hermes-agent/pull/862))
+
+### New Skills
+- **Linear** project management ([#1230](https://github.com/NousResearch/hermes-agent/pull/1230))
+- **X/Twitter** via x-cli ([#1285](https://github.com/NousResearch/hermes-agent/pull/1285))
+- **Telephony** — Twilio, SMS, and AI calls ([#1289](https://github.com/NousResearch/hermes-agent/pull/1289))
+- **1Password** — by @arceus77-7 ([#883](https://github.com/NousResearch/hermes-agent/pull/883), [#1179](https://github.com/NousResearch/hermes-agent/pull/1179))
+- **NeuroSkill BCI** integration ([#1135](https://github.com/NousResearch/hermes-agent/pull/1135))
+- **Blender MCP** for 3D modeling ([#1531](https://github.com/NousResearch/hermes-agent/pull/1531))
+- **OSS Security Forensics** ([#1482](https://github.com/NousResearch/hermes-agent/pull/1482))
+- **Parallel CLI** research skill ([#1301](https://github.com/NousResearch/hermes-agent/pull/1301))
+- **OpenCode** CLI skill ([#1174](https://github.com/NousResearch/hermes-agent/pull/1174))
+- **ASCII Video** skill refactored — by @SHL0MS ([#1213](https://github.com/NousResearch/hermes-agent/pull/1213), [#1598](https://github.com/NousResearch/hermes-agent/pull/1598))
+
+---
+
+## 🎙️ Voice Mode
+
+- Voice mode foundation — push-to-talk CLI, Telegram/Discord voice notes ([#1299](https://github.com/NousResearch/hermes-agent/pull/1299))
+- Free local Whisper transcription via faster-whisper ([#1185](https://github.com/NousResearch/hermes-agent/pull/1185))
+- Discord voice channel reliability fixes ([#1429](https://github.com/NousResearch/hermes-agent/pull/1429))
+- Restore local STT fallback for gateway voice notes ([#1490](https://github.com/NousResearch/hermes-agent/pull/1490))
+- Honor `stt.enabled: false` across gateway transcription ([#1394](https://github.com/NousResearch/hermes-agent/pull/1394))
+- Fix bogus incapability message on Telegram voice notes (Issue [#1033](https://github.com/NousResearch/hermes-agent/issues/1033))
+
+---
+
+## 🔌 ACP (IDE Integration)
+
+- Restore ACP server implementation ([#1254](https://github.com/NousResearch/hermes-agent/pull/1254))
+- Support slash commands in ACP adapter ([#1532](https://github.com/NousResearch/hermes-agent/pull/1532))
+
+---
+
+## 🧪 RL Training
+
+- **Agentic On-Policy Distillation (OPD)** environment — new RL training environment for agent policy distillation ([#1149](https://github.com/NousResearch/hermes-agent/pull/1149))
+- Make tinker-atropos RL training fully optional ([#1062](https://github.com/NousResearch/hermes-agent/pull/1062))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security Hardening
+- **Tirith pre-exec command scanning** — static analysis of terminal commands before execution ([#1256](https://github.com/NousResearch/hermes-agent/pull/1256))
+- **PII redaction** when `privacy.redact_pii` is enabled ([#1542](https://github.com/NousResearch/hermes-agent/pull/1542))
+- Strip Hermes provider/gateway/tool env vars from all subprocess environments ([#1157](https://github.com/NousResearch/hermes-agent/pull/1157), [#1172](https://github.com/NousResearch/hermes-agent/pull/1172), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399), [#1419](https://github.com/NousResearch/hermes-agent/pull/1419))
+- Docker cwd workspace mount now explicit opt-in — never auto-mount host directories ([#1534](https://github.com/NousResearch/hermes-agent/pull/1534))
+- Escape parens and braces in fork bomb regex pattern ([#1397](https://github.com/NousResearch/hermes-agent/pull/1397))
+- Harden `.worktreeinclude` path containment ([#1388](https://github.com/NousResearch/hermes-agent/pull/1388))
+- Use description as `pattern_key` to prevent approval collisions ([#1395](https://github.com/NousResearch/hermes-agent/pull/1395))
+
+### Reliability
+- Guard init-time stdio writes ([#1271](https://github.com/NousResearch/hermes-agent/pull/1271))
+- Session log writes reuse shared atomic JSON helper ([#1280](https://github.com/NousResearch/hermes-agent/pull/1280))
+- Atomic temp cleanup protected on interrupts ([#1401](https://github.com/NousResearch/hermes-agent/pull/1401))
+
+---
+
+## 🐛 Notable Bug Fixes
+
+- **`/status` always showing 0 tokens** — now reports live state (Issue [#1465](https://github.com/NousResearch/hermes-agent/issues/1465), [#1476](https://github.com/NousResearch/hermes-agent/pull/1476))
+- **Custom model endpoints not working** — restored config-saved endpoint resolution (Issue [#1460](https://github.com/NousResearch/hermes-agent/issues/1460), [#1373](https://github.com/NousResearch/hermes-agent/pull/1373))
+- **MCP tools not visible until restart** — auto-reload on config change (Issue [#1036](https://github.com/NousResearch/hermes-agent/issues/1036), [#1474](https://github.com/NousResearch/hermes-agent/pull/1474))
+- **`hermes tools` removing MCP tools** — preserve MCP toolsets when saving (Issue [#1247](https://github.com/NousResearch/hermes-agent/issues/1247), [#1421](https://github.com/NousResearch/hermes-agent/pull/1421))
+- **Terminal subprocesses inheriting `OPENAI_BASE_URL`** breaking external tools (Issue [#1002](https://github.com/NousResearch/hermes-agent/issues/1002), [#1399](https://github.com/NousResearch/hermes-agent/pull/1399))
+- **Background process lost on gateway restart** — improved recovery (Issue [#1144](https://github.com/NousResearch/hermes-agent/issues/1144))
+- **Cron jobs not persisting state** — now stored in SQLite (Issue [#1416](https://github.com/NousResearch/hermes-agent/issues/1416), [#1255](https://github.com/NousResearch/hermes-agent/pull/1255))
+- **Cronjob `deliver: origin` not preserving thread context** (Issue [#1219](https://github.com/NousResearch/hermes-agent/issues/1219), [#1437](https://github.com/NousResearch/hermes-agent/pull/1437))
+- **Gateway systemd service failing to auto-restart** when browser processes orphaned (Issue [#1617](https://github.com/NousResearch/hermes-agent/issues/1617))
+- **`/background` completion report cut off in Telegram** (Issue [#1443](https://github.com/NousResearch/hermes-agent/issues/1443))
+- **Model switching not taking effect** (Issue [#1244](https://github.com/NousResearch/hermes-agent/issues/1244), [#1183](https://github.com/NousResearch/hermes-agent/pull/1183))
+- **`hermes doctor` reporting cronjob as unavailable** (Issue [#878](https://github.com/NousResearch/hermes-agent/issues/878), [#1180](https://github.com/NousResearch/hermes-agent/pull/1180))
+- **WhatsApp bridge messages not received** from mobile (Issue [#1142](https://github.com/NousResearch/hermes-agent/issues/1142))
+- **Setup wizard hanging on headless SSH** (Issue [#905](https://github.com/NousResearch/hermes-agent/issues/905), [#1274](https://github.com/NousResearch/hermes-agent/pull/1274))
+- **Log handler accumulation** degrading gateway performance (Issue [#990](https://github.com/NousResearch/hermes-agent/issues/990), [#1251](https://github.com/NousResearch/hermes-agent/pull/1251))
+- **Gateway NULL model in DB** (Issue [#987](https://github.com/NousResearch/hermes-agent/issues/987), [#1306](https://github.com/NousResearch/hermes-agent/pull/1306))
+- **Strict endpoints rejecting replayed tool_calls** (Issue [#893](https://github.com/NousResearch/hermes-agent/issues/893))
+- **Remaining hardcoded `~/.hermes` paths** — all now respect `HERMES_HOME` (Issue [#892](https://github.com/NousResearch/hermes-agent/issues/892), [#1233](https://github.com/NousResearch/hermes-agent/pull/1233))
+- **Delegate tool not working with custom inference providers** (Issue [#1011](https://github.com/NousResearch/hermes-agent/issues/1011), [#1328](https://github.com/NousResearch/hermes-agent/pull/1328))
+- **Skills Guard blocking official skills** (Issue [#1006](https://github.com/NousResearch/hermes-agent/issues/1006), [#1330](https://github.com/NousResearch/hermes-agent/pull/1330))
+- **Setup writing provider before model selection** (Issue [#1182](https://github.com/NousResearch/hermes-agent/issues/1182))
+- **`GatewayConfig.get()` AttributeError** crashing all message handling (Issue [#1158](https://github.com/NousResearch/hermes-agent/issues/1158), [#1287](https://github.com/NousResearch/hermes-agent/pull/1287))
+- **`/update` hard-failing with "command not found"** (Issue [#1049](https://github.com/NousResearch/hermes-agent/issues/1049))
+- **Image analysis failing silently** (Issue [#1034](https://github.com/NousResearch/hermes-agent/issues/1034), [#1338](https://github.com/NousResearch/hermes-agent/pull/1338))
+- **API `BadRequestError` from `'dict'` object has no attribute `'strip'`** (Issue [#1071](https://github.com/NousResearch/hermes-agent/issues/1071))
+- **Slash commands requiring exact full name** — now uses prefix matching (Issue [#928](https://github.com/NousResearch/hermes-agent/issues/928), [#1320](https://github.com/NousResearch/hermes-agent/pull/1320))
+- **Gateway stops responding when terminal is closed on headless** (Issue [#1005](https://github.com/NousResearch/hermes-agent/issues/1005))
+
+---
+
+## 🧪 Testing
+
+- Cover empty cached Anthropic tool-call turns ([#1222](https://github.com/NousResearch/hermes-agent/pull/1222))
+- Fix stale CI assumptions in parser and quick-command coverage ([#1236](https://github.com/NousResearch/hermes-agent/pull/1236))
+- Fix gateway async tests without implicit event loop ([#1278](https://github.com/NousResearch/hermes-agent/pull/1278))
+- Make gateway async tests xdist-safe ([#1281](https://github.com/NousResearch/hermes-agent/pull/1281))
+- Cross-timezone naive timestamp regression for cron ([#1319](https://github.com/NousResearch/hermes-agent/pull/1319))
+- Isolate codex provider tests from local env ([#1335](https://github.com/NousResearch/hermes-agent/pull/1335))
+- Lock retry replacement semantics ([#1379](https://github.com/NousResearch/hermes-agent/pull/1379))
+- Improve error logging in session search tool — by @aydnOktay ([#1533](https://github.com/NousResearch/hermes-agent/pull/1533))
+
+---
+
+## 📚 Documentation
+
+- Comprehensive SOUL.md guide ([#1315](https://github.com/NousResearch/hermes-agent/pull/1315))
+- Voice mode documentation ([#1316](https://github.com/NousResearch/hermes-agent/pull/1316), [#1362](https://github.com/NousResearch/hermes-agent/pull/1362))
+- Provider contribution guide ([#1361](https://github.com/NousResearch/hermes-agent/pull/1361))
+- ACP and internal systems implementation guides ([#1259](https://github.com/NousResearch/hermes-agent/pull/1259))
+- Expand Docusaurus coverage across CLI, tools, skills, and skins ([#1232](https://github.com/NousResearch/hermes-agent/pull/1232))
+- Terminal backend and Windows troubleshooting ([#1297](https://github.com/NousResearch/hermes-agent/pull/1297))
+- Skills hub reference section ([#1317](https://github.com/NousResearch/hermes-agent/pull/1317))
+- Checkpoint, /rollback, and git worktrees guide ([#1493](https://github.com/NousResearch/hermes-agent/pull/1493), [#1524](https://github.com/NousResearch/hermes-agent/pull/1524))
+- CLI status bar and /usage reference ([#1523](https://github.com/NousResearch/hermes-agent/pull/1523))
+- Fallback providers + /background command docs ([#1430](https://github.com/NousResearch/hermes-agent/pull/1430))
+- Gateway service scopes docs ([#1378](https://github.com/NousResearch/hermes-agent/pull/1378))
+- Slack thread reply behavior docs ([#1407](https://github.com/NousResearch/hermes-agent/pull/1407))
+- Redesigned landing page with Nous blue palette — by @austinpickett ([#974](https://github.com/NousResearch/hermes-agent/pull/974))
+- Fix several documentation typos — by @JackTheGit ([#953](https://github.com/NousResearch/hermes-agent/pull/953))
+- Stabilize website diagrams ([#1405](https://github.com/NousResearch/hermes-agent/pull/1405))
+- CLI vs messaging quick reference in README ([#1491](https://github.com/NousResearch/hermes-agent/pull/1491))
+- Add search to Docusaurus ([#1053](https://github.com/NousResearch/hermes-agent/pull/1053))
+- Home Assistant integration docs ([#1170](https://github.com/NousResearch/hermes-agent/pull/1170))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** — 220+ PRs spanning every area of the codebase
+
+### Top Community Contributors
+
+- **@0xbyt4** (4 PRs) — Anthropic adapter fixes (max_tokens, fallback crash, 429/529 retry), Slack file upload thread context, setup NameError fix
+- **@erosika** (1 PR) — Honcho memory integration: async writes, memory modes, session title integration
+- **@SHL0MS** (2 PRs) — ASCII video skill design patterns and refactoring
+- **@alt-glitch** (2 PRs) — Persistent shell mode for local/SSH backends, setuptools packaging fix
+- **@arceus77-7** (2 PRs) — 1Password skill, fix skills list mislabeling
+- **@kshitijk4poor** (1 PR) — OpenClaw migration during setup wizard
+- **@ASRagab** (1 PR) — Fix adaptive thinking for Claude 4.6 models
+- **@eren-karakus0** (1 PR) — Strip Hermes provider env vars from subprocess environment
+- **@mr-emmett-one** (1 PR) — Fix DeepSeek V3 parser multi-tool call support
+- **@jplew** (1 PR) — Gateway restart on retryable startup failures
+- **@brandtcormorant** (1 PR) — Fix Anthropic cache control for empty text blocks
+- **@aydnOktay** (1 PR) — Improve error logging in session search tool
+- **@austinpickett** (1 PR) — Landing page redesign with Nous blue palette
+- **@JackTheGit** (1 PR) — Documentation typo fixes
+
+### All Contributors
+
+@0xbyt4, @alt-glitch, @arceus77-7, @ASRagab, @austinpickett, @aydnOktay, @brandtcormorant, @eren-karakus0, @erosika, @JackTheGit, @jplew, @kshitijk4poor, @mr-emmett-one, @SHL0MS, @teknium1
+
+---
+
+**Full Changelog**: [v2026.3.12...v2026.3.17](https://github.com/NousResearch/hermes-agent/compare/v2026.3.12...v2026.3.17)
@@ -0,0 +1,400 @@
+# Hermes Agent v0.4.0 (v2026.3.23)
+
+**Release Date:** March 23, 2026
+
+> The platform expansion release — OpenAI-compatible API server, 6 new messaging adapters, 4 new inference providers, MCP server management with OAuth 2.1, @ context references, gateway prompt caching, streaming enabled by default, and a sweeping reliability pass with 200+ bug fixes.
+
+---
+
+## ✨ Highlights
+
+- **OpenAI-compatible API server** — Expose Hermes as an `/v1/chat/completions` endpoint with a new `/api/jobs` REST API for cron job management, hardened with input limits, field whitelists, SQLite-backed response persistence, and CORS origin protection ([#1756](https://github.com/NousResearch/hermes-agent/pull/1756), [#2450](https://github.com/NousResearch/hermes-agent/pull/2450), [#2456](https://github.com/NousResearch/hermes-agent/pull/2456), [#2451](https://github.com/NousResearch/hermes-agent/pull/2451), [#2472](https://github.com/NousResearch/hermes-agent/pull/2472))
+
+- **6 new messaging platform adapters** — Signal, DingTalk, SMS (Twilio), Mattermost, Matrix, and Webhook adapters join Telegram, Discord, and WhatsApp. Gateway auto-reconnects failed platforms with exponential backoff ([#2206](https://github.com/NousResearch/hermes-agent/pull/2206), [#1685](https://github.com/NousResearch/hermes-agent/pull/1685), [#1688](https://github.com/NousResearch/hermes-agent/pull/1688), [#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2166](https://github.com/NousResearch/hermes-agent/pull/2166), [#2584](https://github.com/NousResearch/hermes-agent/pull/2584))
+
+- **@ context references** — Claude Code-style `@file` and `@url` context injection with tab completions in the CLI ([#2343](https://github.com/NousResearch/hermes-agent/pull/2343), [#2482](https://github.com/NousResearch/hermes-agent/pull/2482))
+
+- **4 new inference providers** — GitHub Copilot (OAuth + token validation), Alibaba Cloud / DashScope, Kilo Code, and OpenCode Zen/Go ([#1924](https://github.com/NousResearch/hermes-agent/pull/1924), [#1879](https://github.com/NousResearch/hermes-agent/pull/1879) by @mchzimm, [#1673](https://github.com/NousResearch/hermes-agent/pull/1673), [#1666](https://github.com/NousResearch/hermes-agent/pull/1666), [#1650](https://github.com/NousResearch/hermes-agent/pull/1650))
+
+- **MCP server management CLI** — `hermes mcp` commands for installing, configuring, and authenticating MCP servers with full OAuth 2.1 PKCE flow ([#2465](https://github.com/NousResearch/hermes-agent/pull/2465))
+
+- **Gateway prompt caching** — Cache AIAgent instances per session, preserving Anthropic prompt cache across turns for dramatic cost reduction on long conversations ([#2282](https://github.com/NousResearch/hermes-agent/pull/2282), [#2284](https://github.com/NousResearch/hermes-agent/pull/2284), [#2361](https://github.com/NousResearch/hermes-agent/pull/2361))
+
+- **Context compression overhaul** — Structured summaries with iterative updates, token-budget tail protection, configurable summary endpoint, and fallback model support ([#2323](https://github.com/NousResearch/hermes-agent/pull/2323), [#1727](https://github.com/NousResearch/hermes-agent/pull/1727), [#2224](https://github.com/NousResearch/hermes-agent/pull/2224))
+
+- **Streaming enabled by default** — CLI streaming on by default with proper spinner/tool progress display during streaming mode, plus extensive linebreak and concatenation fixes ([#2340](https://github.com/NousResearch/hermes-agent/pull/2340), [#2161](https://github.com/NousResearch/hermes-agent/pull/2161), [#2258](https://github.com/NousResearch/hermes-agent/pull/2258))
+
+---
+
+## 🖥️ CLI & User Experience
+
+### New Commands & Interactions
+- **@ context completions** — Tab-completable `@file`/`@url` references that inject file content or web pages into the conversation ([#2482](https://github.com/NousResearch/hermes-agent/pull/2482), [#2343](https://github.com/NousResearch/hermes-agent/pull/2343))
+- **`/statusbar`** — Toggle a persistent config bar showing model + provider info in the prompt ([#2240](https://github.com/NousResearch/hermes-agent/pull/2240), [#1917](https://github.com/NousResearch/hermes-agent/pull/1917))
+- **`/queue`** — Queue prompts for the agent without interrupting the current run ([#2191](https://github.com/NousResearch/hermes-agent/pull/2191), [#2469](https://github.com/NousResearch/hermes-agent/pull/2469))
+- **`/permission`** — Switch approval mode dynamically during a session ([#2207](https://github.com/NousResearch/hermes-agent/pull/2207))
+- **`/browser`** — Interactive browser sessions from the CLI ([#2273](https://github.com/NousResearch/hermes-agent/pull/2273), [#1814](https://github.com/NousResearch/hermes-agent/pull/1814))
+- **`/cost`** — Live pricing and usage tracking in gateway mode ([#2180](https://github.com/NousResearch/hermes-agent/pull/2180))
+- **`/approve` and `/deny`** — Replaced bare text approval in gateway with explicit commands ([#2002](https://github.com/NousResearch/hermes-agent/pull/2002))
+
+### Streaming & Display
+- Streaming enabled by default in CLI ([#2340](https://github.com/NousResearch/hermes-agent/pull/2340))
+- Show spinners and tool progress during streaming mode ([#2161](https://github.com/NousResearch/hermes-agent/pull/2161))
+- Show reasoning/thinking blocks when `show_reasoning` enabled ([#2118](https://github.com/NousResearch/hermes-agent/pull/2118))
+- Context pressure warnings for CLI and gateway ([#2159](https://github.com/NousResearch/hermes-agent/pull/2159))
+- Fix: streaming chunks concatenated without whitespace ([#2258](https://github.com/NousResearch/hermes-agent/pull/2258))
+- Fix: iteration boundary linebreak prevents stream concatenation ([#2413](https://github.com/NousResearch/hermes-agent/pull/2413))
+- Fix: defer streaming linebreak to prevent blank line stacking ([#2473](https://github.com/NousResearch/hermes-agent/pull/2473))
+- Fix: suppress spinner animation in non-TTY environments ([#2216](https://github.com/NousResearch/hermes-agent/pull/2216))
+- Fix: display provider and endpoint in API error messages ([#2266](https://github.com/NousResearch/hermes-agent/pull/2266))
+- Fix: resolve garbled ANSI escape codes in status printouts ([#2448](https://github.com/NousResearch/hermes-agent/pull/2448))
+- Fix: update gold ANSI color to true-color format ([#2246](https://github.com/NousResearch/hermes-agent/pull/2246))
+- Fix: normalize toolset labels and use skin colors in banner ([#1912](https://github.com/NousResearch/hermes-agent/pull/1912))
+
+### CLI Polish
+- Fix: prevent 'Press ENTER to continue...' on exit ([#2555](https://github.com/NousResearch/hermes-agent/pull/2555))
+- Fix: flush stdout during agent loop to prevent macOS display freeze ([#1654](https://github.com/NousResearch/hermes-agent/pull/1654))
+- Fix: show human-readable error when `hermes setup` hits permissions error ([#2196](https://github.com/NousResearch/hermes-agent/pull/2196))
+- Fix: `/stop` command crash + UnboundLocalError in streaming media delivery ([#2463](https://github.com/NousResearch/hermes-agent/pull/2463))
+- Fix: allow custom/local endpoints without API key ([#2556](https://github.com/NousResearch/hermes-agent/pull/2556))
+- Fix: Kitty keyboard protocol Shift+Enter for Ghostty/WezTerm (attempted + reverted due to prompt_toolkit crash) ([#2345](https://github.com/NousResearch/hermes-agent/pull/2345), [#2349](https://github.com/NousResearch/hermes-agent/pull/2349))
+
+### Configuration
+- **`${ENV_VAR}` substitution** in config.yaml ([#2684](https://github.com/NousResearch/hermes-agent/pull/2684))
+- **Real-time config reload** — config.yaml changes apply without restart ([#2210](https://github.com/NousResearch/hermes-agent/pull/2210))
+- **`custom_models.yaml`** for user-managed model additions ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214))
+- **Priority-based context file selection** + CLAUDE.md support ([#2301](https://github.com/NousResearch/hermes-agent/pull/2301))
+- **Merge nested YAML sections** instead of replacing on config update ([#2213](https://github.com/NousResearch/hermes-agent/pull/2213))
+- Fix: config.yaml provider key overrides env var silently ([#2272](https://github.com/NousResearch/hermes-agent/pull/2272))
+- Fix: log warning instead of silently swallowing config.yaml errors ([#2683](https://github.com/NousResearch/hermes-agent/pull/2683))
+- Fix: disabled toolsets re-enable themselves after `hermes tools` ([#2268](https://github.com/NousResearch/hermes-agent/pull/2268))
+- Fix: platform default toolsets silently override tool deselection ([#2624](https://github.com/NousResearch/hermes-agent/pull/2624))
+- Fix: honor bare YAML `approvals.mode: off` ([#2620](https://github.com/NousResearch/hermes-agent/pull/2620))
+- Fix: `hermes update` use `.[all]` extras with fallback ([#1728](https://github.com/NousResearch/hermes-agent/pull/1728))
+- Fix: `hermes update` prompt before resetting working tree on stash conflicts ([#2390](https://github.com/NousResearch/hermes-agent/pull/2390))
+- Fix: use git pull --rebase in update/install to avoid divergent branch error ([#2274](https://github.com/NousResearch/hermes-agent/pull/2274))
+- Fix: add zprofile fallback and create zshrc on fresh macOS installs ([#2320](https://github.com/NousResearch/hermes-agent/pull/2320))
+- Fix: remove `ANTHROPIC_BASE_URL` env var to avoid collisions ([#1675](https://github.com/NousResearch/hermes-agent/pull/1675))
+- Fix: don't ask IMAP password if already in keyring or env ([#2212](https://github.com/NousResearch/hermes-agent/pull/2212))
+- Fix: OpenCode Zen/Go show OpenRouter models instead of their own ([#2277](https://github.com/NousResearch/hermes-agent/pull/2277))
+
+---
+
+## 🏗️ Core Agent & Architecture
+
+### New Providers
+- **GitHub Copilot** — Full OAuth auth, API routing, token validation, and 400k context. ([#1924](https://github.com/NousResearch/hermes-agent/pull/1924), [#1896](https://github.com/NousResearch/hermes-agent/pull/1896), [#1879](https://github.com/NousResearch/hermes-agent/pull/1879) by @mchzimm, [#2507](https://github.com/NousResearch/hermes-agent/pull/2507))
+- **Alibaba Cloud / DashScope** — Full integration with DashScope v1 runtime, model dot preservation, and 401 auth fixes ([#1673](https://github.com/NousResearch/hermes-agent/pull/1673), [#2332](https://github.com/NousResearch/hermes-agent/pull/2332), [#2459](https://github.com/NousResearch/hermes-agent/pull/2459))
+- **Kilo Code** — First-class inference provider ([#1666](https://github.com/NousResearch/hermes-agent/pull/1666))
+- **OpenCode Zen and OpenCode Go** — New provider backends ([#1650](https://github.com/NousResearch/hermes-agent/pull/1650), [#2393](https://github.com/NousResearch/hermes-agent/pull/2393) by @0xbyt4)
+- **NeuTTS** — Local TTS provider backend with built-in setup flow, replacing the old optional skill ([#1657](https://github.com/NousResearch/hermes-agent/pull/1657), [#1664](https://github.com/NousResearch/hermes-agent/pull/1664))
+
+### Provider Improvements
+- **Eager fallback** to backup model on rate-limit errors ([#1730](https://github.com/NousResearch/hermes-agent/pull/1730))
+- **Endpoint metadata** for custom model context and pricing; query local servers for actual context window size ([#1906](https://github.com/NousResearch/hermes-agent/pull/1906), [#2091](https://github.com/NousResearch/hermes-agent/pull/2091) by @dusterbloom)
+- **Context length detection overhaul** — models.dev integration, provider-aware resolution, fuzzy matching for custom endpoints, `/v1/props` for llama.cpp ([#2158](https://github.com/NousResearch/hermes-agent/pull/2158), [#2051](https://github.com/NousResearch/hermes-agent/pull/2051), [#2403](https://github.com/NousResearch/hermes-agent/pull/2403))
+- **Model catalog updates** — gpt-5.4-mini, gpt-5.4-nano, healer-alpha, haiku-4.5, minimax-m2.7, claude 4.6 at 1M context ([#1913](https://github.com/NousResearch/hermes-agent/pull/1913), [#1915](https://github.com/NousResearch/hermes-agent/pull/1915), [#1900](https://github.com/NousResearch/hermes-agent/pull/1900), [#2155](https://github.com/NousResearch/hermes-agent/pull/2155), [#2474](https://github.com/NousResearch/hermes-agent/pull/2474))
+- **Custom endpoint improvements** — `model.base_url` in config.yaml, `api_mode` override for responses API, allow endpoints without API key, fail fast on missing keys ([#2330](https://github.com/NousResearch/hermes-agent/pull/2330), [#1651](https://github.com/NousResearch/hermes-agent/pull/1651), [#2556](https://github.com/NousResearch/hermes-agent/pull/2556), [#2445](https://github.com/NousResearch/hermes-agent/pull/2445), [#1994](https://github.com/NousResearch/hermes-agent/pull/1994), [#1998](https://github.com/NousResearch/hermes-agent/pull/1998))
+- Inject model and provider into system prompt ([#1929](https://github.com/NousResearch/hermes-agent/pull/1929))
+- Tie `api_mode` to provider config instead of env var ([#1656](https://github.com/NousResearch/hermes-agent/pull/1656))
+- Fix: prevent Anthropic token leaking to third-party `anthropic_messages` providers ([#2389](https://github.com/NousResearch/hermes-agent/pull/2389))
+- Fix: prevent Anthropic fallback from inheriting non-Anthropic `base_url` ([#2388](https://github.com/NousResearch/hermes-agent/pull/2388))
+- Fix: `auxiliary_is_nous` flag never resets — leaked Nous tags to other providers ([#1713](https://github.com/NousResearch/hermes-agent/pull/1713))
+- Fix: Anthropic `tool_choice 'none'` still allowed tool calls ([#1714](https://github.com/NousResearch/hermes-agent/pull/1714))
+- Fix: Mistral parser nested JSON fallback extraction ([#2335](https://github.com/NousResearch/hermes-agent/pull/2335))
+- Fix: MiniMax 401 auth resolved by defaulting to `anthropic_messages` ([#2103](https://github.com/NousResearch/hermes-agent/pull/2103))
+- Fix: case-insensitive model family matching ([#2350](https://github.com/NousResearch/hermes-agent/pull/2350))
+- Fix: ignore placeholder provider keys in activation checks ([#2358](https://github.com/NousResearch/hermes-agent/pull/2358))
+- Fix: Preserve Ollama model:tag colons in context length detection ([#2149](https://github.com/NousResearch/hermes-agent/pull/2149))
+- Fix: recognize Claude Code OAuth credentials in startup gate ([#1663](https://github.com/NousResearch/hermes-agent/pull/1663))
+- Fix: detect Claude Code version dynamically for OAuth user-agent ([#1670](https://github.com/NousResearch/hermes-agent/pull/1670))
+- Fix: OAuth flag stale after refresh/fallback ([#1890](https://github.com/NousResearch/hermes-agent/pull/1890))
+- Fix: auxiliary client skips expired Codex JWT ([#2397](https://github.com/NousResearch/hermes-agent/pull/2397))
+
+### Agent Loop
+- **Gateway prompt caching** — Cache AIAgent per session, keep assistant turns, fix session restore ([#2282](https://github.com/NousResearch/hermes-agent/pull/2282), [#2284](https://github.com/NousResearch/hermes-agent/pull/2284), [#2361](https://github.com/NousResearch/hermes-agent/pull/2361))
+- **Context compression overhaul** — Structured summaries, iterative updates, token-budget tail protection, configurable `summary_base_url` ([#2323](https://github.com/NousResearch/hermes-agent/pull/2323), [#1727](https://github.com/NousResearch/hermes-agent/pull/1727), [#2224](https://github.com/NousResearch/hermes-agent/pull/2224))
+- **Pre-call sanitization and post-call tool guardrails** ([#1732](https://github.com/NousResearch/hermes-agent/pull/1732))
+- **Auto-recover** from provider-rejected `tool_choice` by retrying without ([#2174](https://github.com/NousResearch/hermes-agent/pull/2174))
+- **Background memory/skill review** replaces inline nudges ([#2235](https://github.com/NousResearch/hermes-agent/pull/2235))
+- **SOUL.md as primary agent identity** instead of hardcoded default ([#1922](https://github.com/NousResearch/hermes-agent/pull/1922))
+- Fix: prevent silent tool result loss during context compression ([#1993](https://github.com/NousResearch/hermes-agent/pull/1993))
+- Fix: handle empty/null function arguments in tool call recovery ([#2163](https://github.com/NousResearch/hermes-agent/pull/2163))
+- Fix: handle API refusal responses gracefully instead of crashing ([#2156](https://github.com/NousResearch/hermes-agent/pull/2156))
+- Fix: prevent stuck agent loop on malformed tool calls ([#2114](https://github.com/NousResearch/hermes-agent/pull/2114))
+- Fix: return JSON parse error to model instead of dispatching with empty args ([#2342](https://github.com/NousResearch/hermes-agent/pull/2342))
+- Fix: consecutive assistant message merge drops content on mixed types ([#1703](https://github.com/NousResearch/hermes-agent/pull/1703))
+- Fix: message role alternation violations in JSON recovery and error handler ([#1722](https://github.com/NousResearch/hermes-agent/pull/1722))
+- Fix: `compression_attempts` resets each iteration — allowed unlimited compressions ([#1723](https://github.com/NousResearch/hermes-agent/pull/1723))
+- Fix: `length_continue_retries` never resets — later truncations got fewer retries ([#1717](https://github.com/NousResearch/hermes-agent/pull/1717))
+- Fix: compressor summary role violated consecutive-role constraint ([#1720](https://github.com/NousResearch/hermes-agent/pull/1720), [#1743](https://github.com/NousResearch/hermes-agent/pull/1743))
+- Fix: remove hardcoded `gemini-3-flash-preview` as default summary model ([#2464](https://github.com/NousResearch/hermes-agent/pull/2464))
+- Fix: correctly handle empty tool results ([#2201](https://github.com/NousResearch/hermes-agent/pull/2201))
+- Fix: crash on None entry in `tool_calls` list ([#2209](https://github.com/NousResearch/hermes-agent/pull/2209) by @0xbyt4, [#2316](https://github.com/NousResearch/hermes-agent/pull/2316))
+- Fix: per-thread persistent event loops in worker threads ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214) by @jquesnelle)
+- Fix: prevent 'event loop already running' when async tools run in parallel ([#2207](https://github.com/NousResearch/hermes-agent/pull/2207))
+- Fix: strip ANSI at the source — clean terminal output before it reaches the model ([#2115](https://github.com/NousResearch/hermes-agent/pull/2115))
+- Fix: skip top-level `cache_control` on role:tool for OpenRouter ([#2391](https://github.com/NousResearch/hermes-agent/pull/2391))
+- Fix: delegate tool — save parent tool names before child construction mutates global ([#2083](https://github.com/NousResearch/hermes-agent/pull/2083) by @ygd58, [#1894](https://github.com/NousResearch/hermes-agent/pull/1894))
+- Fix: only strip last assistant message if empty string ([#2326](https://github.com/NousResearch/hermes-agent/pull/2326))
+
+### Session & Memory
+- **Session search** and management slash commands ([#2198](https://github.com/NousResearch/hermes-agent/pull/2198))
+- **Auto session titles** and `.hermes.md` project config ([#1712](https://github.com/NousResearch/hermes-agent/pull/1712))
+- Fix: concurrent memory writes silently drop entries — added file locking ([#1726](https://github.com/NousResearch/hermes-agent/pull/1726))
+- Fix: search all sources by default in `session_search` ([#1892](https://github.com/NousResearch/hermes-agent/pull/1892))
+- Fix: handle hyphenated FTS5 queries and preserve quoted literals ([#1776](https://github.com/NousResearch/hermes-agent/pull/1776))
+- Fix: skip corrupt lines in `load_transcript` instead of crashing ([#1744](https://github.com/NousResearch/hermes-agent/pull/1744))
+- Fix: normalize session keys to prevent case-sensitive duplicates ([#2157](https://github.com/NousResearch/hermes-agent/pull/2157))
+- Fix: prevent `session_search` crash when no sessions exist ([#2194](https://github.com/NousResearch/hermes-agent/pull/2194))
+- Fix: reset token counters on new session for accurate usage display ([#2101](https://github.com/NousResearch/hermes-agent/pull/2101) by @InB4DevOps)
+- Fix: prevent stale memory overwrites by flush agent ([#2687](https://github.com/NousResearch/hermes-agent/pull/2687))
+- Fix: remove synthetic error message injection, fix session resume after repeated failures ([#2303](https://github.com/NousResearch/hermes-agent/pull/2303))
+- Fix: quiet mode with `--resume` now passes conversation_history ([#2357](https://github.com/NousResearch/hermes-agent/pull/2357))
+- Fix: unify resume logic in batch mode ([#2331](https://github.com/NousResearch/hermes-agent/pull/2331))
+
+### Honcho Memory
+- Honcho config fixes and @ context reference integration ([#2343](https://github.com/NousResearch/hermes-agent/pull/2343))
+- Self-hosted / Docker configuration documentation ([#2475](https://github.com/NousResearch/hermes-agent/pull/2475))
+
+---
+
+## 📱 Messaging Platforms (Gateway)
+
+### New Platform Adapters
+- **Signal Messenger** — Full adapter with attachment handling, group message filtering, and Note to Self echo-back protection ([#2206](https://github.com/NousResearch/hermes-agent/pull/2206), [#2400](https://github.com/NousResearch/hermes-agent/pull/2400), [#2297](https://github.com/NousResearch/hermes-agent/pull/2297), [#2156](https://github.com/NousResearch/hermes-agent/pull/2156))
+- **DingTalk** — Adapter with gateway wiring and setup docs ([#1685](https://github.com/NousResearch/hermes-agent/pull/1685), [#1690](https://github.com/NousResearch/hermes-agent/pull/1690), [#1692](https://github.com/NousResearch/hermes-agent/pull/1692))
+- **SMS (Twilio)** ([#1688](https://github.com/NousResearch/hermes-agent/pull/1688))
+- **Mattermost** — With @-mention-only channel filter ([#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2443](https://github.com/NousResearch/hermes-agent/pull/2443))
+- **Matrix** — With vision support and image caching ([#1683](https://github.com/NousResearch/hermes-agent/pull/1683), [#2520](https://github.com/NousResearch/hermes-agent/pull/2520))
+- **Webhook** — Platform adapter for external event triggers ([#2166](https://github.com/NousResearch/hermes-agent/pull/2166))
+- **OpenAI-compatible API server** — `/v1/chat/completions` endpoint with `/api/jobs` cron management ([#1756](https://github.com/NousResearch/hermes-agent/pull/1756), [#2450](https://github.com/NousResearch/hermes-agent/pull/2450), [#2456](https://github.com/NousResearch/hermes-agent/pull/2456))
+
+### Telegram Improvements
+- MarkdownV2 support — strikethrough, spoiler, blockquotes, escape parentheses/braces/backslashes/backticks ([#2199](https://github.com/NousResearch/hermes-agent/pull/2199), [#2200](https://github.com/NousResearch/hermes-agent/pull/2200) by @llbn, [#2386](https://github.com/NousResearch/hermes-agent/pull/2386))
+- Auto-detect HTML tags and use `parse_mode=HTML` ([#1709](https://github.com/NousResearch/hermes-agent/pull/1709))
+- Telegram group vision support + thread-based sessions ([#2153](https://github.com/NousResearch/hermes-agent/pull/2153))
+- Auto-reconnect polling after network interruption ([#2517](https://github.com/NousResearch/hermes-agent/pull/2517))
+- Aggregate split text messages before dispatching ([#1674](https://github.com/NousResearch/hermes-agent/pull/1674))
+- Fix: streaming config bridge, not-modified, flood control ([#1782](https://github.com/NousResearch/hermes-agent/pull/1782), [#1783](https://github.com/NousResearch/hermes-agent/pull/1783))
+- Fix: edited_message event crashes ([#2074](https://github.com/NousResearch/hermes-agent/pull/2074))
+- Fix: retry 409 polling conflicts before giving up ([#2312](https://github.com/NousResearch/hermes-agent/pull/2312))
+- Fix: topic delivery via `platform:chat_id:thread_id` format ([#2455](https://github.com/NousResearch/hermes-agent/pull/2455))
+
+### Discord Improvements
+- Document caching and text-file injection ([#2503](https://github.com/NousResearch/hermes-agent/pull/2503))
+- Persistent typing indicator for DMs ([#2468](https://github.com/NousResearch/hermes-agent/pull/2468))
+- Discord DM vision — inline images + attachment analysis ([#2186](https://github.com/NousResearch/hermes-agent/pull/2186))
+- Persist thread participation across gateway restarts ([#1661](https://github.com/NousResearch/hermes-agent/pull/1661))
+- Fix: gateway crash on non-ASCII guild names ([#2302](https://github.com/NousResearch/hermes-agent/pull/2302))
+- Fix: thread permission errors ([#2073](https://github.com/NousResearch/hermes-agent/pull/2073))
+- Fix: slash event routing in threads ([#2460](https://github.com/NousResearch/hermes-agent/pull/2460))
+- Fix: remove bugged followup messages + `/ask` command ([#1836](https://github.com/NousResearch/hermes-agent/pull/1836))
+- Fix: graceful WebSocket reconnection ([#2127](https://github.com/NousResearch/hermes-agent/pull/2127))
+- Fix: voice channel TTS when streaming enabled ([#2322](https://github.com/NousResearch/hermes-agent/pull/2322))
+
+### WhatsApp & Other Adapters
+- WhatsApp: outbound `send_message` routing ([#1769](https://github.com/NousResearch/hermes-agent/pull/1769) by @sai-samarth), LID format self-chat ([#1667](https://github.com/NousResearch/hermes-agent/pull/1667)), `reply_prefix` config fix ([#1923](https://github.com/NousResearch/hermes-agent/pull/1923)), restart on bridge child exit ([#2334](https://github.com/NousResearch/hermes-agent/pull/2334)), image/bridge improvements ([#2181](https://github.com/NousResearch/hermes-agent/pull/2181))
+- Matrix: correct `reply_to_message_id` parameter ([#1895](https://github.com/NousResearch/hermes-agent/pull/1895)), bare media types fix ([#1736](https://github.com/NousResearch/hermes-agent/pull/1736))
+- Mattermost: MIME types for media attachments ([#2329](https://github.com/NousResearch/hermes-agent/pull/2329))
+
+### Gateway Core
+- **Auto-reconnect** failed platforms with exponential backoff ([#2584](https://github.com/NousResearch/hermes-agent/pull/2584))
+- **Notify users when session auto-resets** ([#2519](https://github.com/NousResearch/hermes-agent/pull/2519))
+- **Reply-to message context** for out-of-session replies ([#1662](https://github.com/NousResearch/hermes-agent/pull/1662))
+- **Ignore unauthorized DMs** config option ([#1919](https://github.com/NousResearch/hermes-agent/pull/1919))
+- Fix: `/reset` in thread-mode resets global session instead of thread ([#2254](https://github.com/NousResearch/hermes-agent/pull/2254))
+- Fix: deliver MEDIA: files after streaming responses ([#2382](https://github.com/NousResearch/hermes-agent/pull/2382))
+- Fix: cap interrupt recursion depth to prevent resource exhaustion ([#1659](https://github.com/NousResearch/hermes-agent/pull/1659))
+- Fix: detect stopped processes and release stale locks on `--replace` ([#2406](https://github.com/NousResearch/hermes-agent/pull/2406), [#1908](https://github.com/NousResearch/hermes-agent/pull/1908))
+- Fix: PID-based wait with force-kill for gateway restart ([#1902](https://github.com/NousResearch/hermes-agent/pull/1902))
+- Fix: prevent `--replace` mode from killing the caller process ([#2185](https://github.com/NousResearch/hermes-agent/pull/2185))
+- Fix: `/model` shows active fallback model instead of config default ([#1660](https://github.com/NousResearch/hermes-agent/pull/1660))
+- Fix: `/title` command fails when session doesn't exist in SQLite yet ([#2379](https://github.com/NousResearch/hermes-agent/pull/2379) by @ten-jampa)
+- Fix: process `/queue`'d messages after agent completion ([#2469](https://github.com/NousResearch/hermes-agent/pull/2469))
+- Fix: strip orphaned `tool_results` + let `/reset` bypass running agent ([#2180](https://github.com/NousResearch/hermes-agent/pull/2180))
+- Fix: prevent agents from starting gateway outside systemd management ([#2617](https://github.com/NousResearch/hermes-agent/pull/2617))
+- Fix: prevent systemd restart storm on gateway connection failure ([#2327](https://github.com/NousResearch/hermes-agent/pull/2327))
+- Fix: include resolved node path in systemd unit ([#1767](https://github.com/NousResearch/hermes-agent/pull/1767) by @sai-samarth)
+- Fix: send error details to user in gateway outer exception handler ([#1966](https://github.com/NousResearch/hermes-agent/pull/1966))
+- Fix: improve error handling for 429 usage limits and 500 context overflow ([#1839](https://github.com/NousResearch/hermes-agent/pull/1839))
+- Fix: add all missing platform allowlist env vars to startup warning check ([#2628](https://github.com/NousResearch/hermes-agent/pull/2628))
+- Fix: media delivery fails for file paths containing spaces ([#2621](https://github.com/NousResearch/hermes-agent/pull/2621))
+- Fix: duplicate session-key collision in multi-platform gateway ([#2171](https://github.com/NousResearch/hermes-agent/pull/2171))
+- Fix: Matrix and Mattermost never report as connected ([#1711](https://github.com/NousResearch/hermes-agent/pull/1711))
+- Fix: PII redaction config never read — missing yaml import ([#1701](https://github.com/NousResearch/hermes-agent/pull/1701))
+- Fix: NameError on skill slash commands ([#1697](https://github.com/NousResearch/hermes-agent/pull/1697))
+- Fix: persist watcher metadata in checkpoint for crash recovery ([#1706](https://github.com/NousResearch/hermes-agent/pull/1706))
+- Fix: pass `message_thread_id` in send_image_file, send_document, send_video ([#2339](https://github.com/NousResearch/hermes-agent/pull/2339))
+- Fix: media-group aggregation on rapid successive photo messages ([#2160](https://github.com/NousResearch/hermes-agent/pull/2160))
+
+---
+
+## 🔧 Tool System
+
+### MCP Enhancements
+- **MCP server management CLI** + OAuth 2.1 PKCE auth ([#2465](https://github.com/NousResearch/hermes-agent/pull/2465))
+- **Expose MCP servers as standalone toolsets** ([#1907](https://github.com/NousResearch/hermes-agent/pull/1907))
+- **Interactive MCP tool configuration** in `hermes tools` ([#1694](https://github.com/NousResearch/hermes-agent/pull/1694))
+- Fix: MCP-OAuth port mismatch, path traversal, and shared handler state ([#2552](https://github.com/NousResearch/hermes-agent/pull/2552))
+- Fix: preserve MCP tool registrations across session resets ([#2124](https://github.com/NousResearch/hermes-agent/pull/2124))
+- Fix: concurrent file access crash + duplicate MCP registration ([#2154](https://github.com/NousResearch/hermes-agent/pull/2154))
+- Fix: normalise MCP schemas + expand session list columns ([#2102](https://github.com/NousResearch/hermes-agent/pull/2102))
+- Fix: `tool_choice` `mcp_` prefix handling ([#1775](https://github.com/NousResearch/hermes-agent/pull/1775))
+
+### Web Tool Backends
+- **Tavily** as web search/extract/crawl backend ([#1731](https://github.com/NousResearch/hermes-agent/pull/1731))
+- **Parallel** as alternative web search/extract backend ([#1696](https://github.com/NousResearch/hermes-agent/pull/1696))
+- **Configurable web backend** — Firecrawl/BeautifulSoup/Playwright selection ([#2256](https://github.com/NousResearch/hermes-agent/pull/2256))
+- Fix: whitespace-only env vars bypass web backend detection ([#2341](https://github.com/NousResearch/hermes-agent/pull/2341))
+
+### New Tools
+- **IMAP email** reading and sending ([#2173](https://github.com/NousResearch/hermes-agent/pull/2173))
+- **STT (speech-to-text)** tool using Whisper API ([#2072](https://github.com/NousResearch/hermes-agent/pull/2072))
+- **Route-aware pricing estimates** ([#1695](https://github.com/NousResearch/hermes-agent/pull/1695))
+
+### Tool Improvements
+- TTS: `base_url` support for OpenAI TTS provider ([#2064](https://github.com/NousResearch/hermes-agent/pull/2064) by @hanai)
+- Vision: configurable timeout, tilde expansion in file paths, DM vision with multi-image and base64 fallback ([#2480](https://github.com/NousResearch/hermes-agent/pull/2480), [#2585](https://github.com/NousResearch/hermes-agent/pull/2585), [#2211](https://github.com/NousResearch/hermes-agent/pull/2211))
+- Browser: race condition fix in session creation ([#1721](https://github.com/NousResearch/hermes-agent/pull/1721)), TypeError on unexpected LLM params ([#1735](https://github.com/NousResearch/hermes-agent/pull/1735))
+- File tools: strip ANSI escape codes from write_file and patch content ([#2532](https://github.com/NousResearch/hermes-agent/pull/2532)), include pagination args in repeated search key ([#1824](https://github.com/NousResearch/hermes-agent/pull/1824) by @cutepawss), improve fuzzy matching accuracy + position calculation refactor ([#2096](https://github.com/NousResearch/hermes-agent/pull/2096), [#1681](https://github.com/NousResearch/hermes-agent/pull/1681))
+- Code execution: resource leak and double socket close fix ([#2381](https://github.com/NousResearch/hermes-agent/pull/2381))
+- Delegate: thread safety for concurrent subagent delegation ([#1672](https://github.com/NousResearch/hermes-agent/pull/1672)), preserve parent agent's tool list after delegation ([#1778](https://github.com/NousResearch/hermes-agent/pull/1778))
+- Fix: make concurrent tool batching path-aware for file mutations ([#1914](https://github.com/NousResearch/hermes-agent/pull/1914))
+- Fix: chunk long messages in `send_message_tool` before platform dispatch ([#1646](https://github.com/NousResearch/hermes-agent/pull/1646))
+- Fix: add missing 'messaging' toolset ([#1718](https://github.com/NousResearch/hermes-agent/pull/1718))
+- Fix: prevent unavailable tool names from leaking into model schemas ([#2072](https://github.com/NousResearch/hermes-agent/pull/2072))
+- Fix: pass visited set by reference to prevent diamond dependency duplication ([#2311](https://github.com/NousResearch/hermes-agent/pull/2311))
+- Fix: Daytona sandbox lookup migrated from `find_one` to `get/list` ([#2063](https://github.com/NousResearch/hermes-agent/pull/2063) by @rovle)
+
+---
+
+## 🧩 Skills Ecosystem
+
+### Skills System Improvements
+- **Agent-created skills** — Caution-level findings allowed, dangerous skills ask instead of block ([#1840](https://github.com/NousResearch/hermes-agent/pull/1840), [#2446](https://github.com/NousResearch/hermes-agent/pull/2446))
+- **`--yes` flag** to bypass confirmation in `/skills install` and uninstall ([#1647](https://github.com/NousResearch/hermes-agent/pull/1647))
+- **Disabled skills respected** across banner, system prompt, and slash commands ([#1897](https://github.com/NousResearch/hermes-agent/pull/1897))
+- Fix: skills custom_tools import crash + sandbox file_tools integration ([#2239](https://github.com/NousResearch/hermes-agent/pull/2239))
+- Fix: agent-created skills with pip requirements crash on install ([#2145](https://github.com/NousResearch/hermes-agent/pull/2145))
+- Fix: race condition in `Skills.__init__` when `hub.yaml` missing ([#2242](https://github.com/NousResearch/hermes-agent/pull/2242))
+- Fix: validate skill metadata before install and block duplicates ([#2241](https://github.com/NousResearch/hermes-agent/pull/2241))
+- Fix: skills hub inspect/resolve — 4 bugs in inspect, redirects, discovery, tap list ([#2447](https://github.com/NousResearch/hermes-agent/pull/2447))
+- Fix: agent-created skills keep working after session reset ([#2121](https://github.com/NousResearch/hermes-agent/pull/2121))
+
+### New Skills
+- **OCR-and-documents** — PDF/DOCX/XLS/PPTX/image OCR with optional GPU ([#2236](https://github.com/NousResearch/hermes-agent/pull/2236), [#2461](https://github.com/NousResearch/hermes-agent/pull/2461))
+- **Huggingface-hub** bundled skill ([#1921](https://github.com/NousResearch/hermes-agent/pull/1921))
+- **Sherlock OSINT** username search ([#1671](https://github.com/NousResearch/hermes-agent/pull/1671))
+- **Meme-generation** — Image generator with Pillow ([#2344](https://github.com/NousResearch/hermes-agent/pull/2344))
+- **Bioinformatics** gateway skill — index to 400+ bio skills ([#2387](https://github.com/NousResearch/hermes-agent/pull/2387))
+- **Inference.sh** skill (terminal-based) ([#1686](https://github.com/NousResearch/hermes-agent/pull/1686))
+- **Base blockchain** optional skill ([#1643](https://github.com/NousResearch/hermes-agent/pull/1643))
+- **3D-model-viewer** optional skill ([#2226](https://github.com/NousResearch/hermes-agent/pull/2226))
+- **FastMCP** optional skill ([#2113](https://github.com/NousResearch/hermes-agent/pull/2113))
+- **Hermes-agent-setup** skill ([#1905](https://github.com/NousResearch/hermes-agent/pull/1905))
+
+---
+
+## 🔌 Plugin System Enhancements
+
+- **TUI extension hooks** — Build custom CLIs on top of Hermes ([#2333](https://github.com/NousResearch/hermes-agent/pull/2333))
+- **`hermes plugins install/remove/list`** commands ([#2337](https://github.com/NousResearch/hermes-agent/pull/2337))
+- **Slash command registration** for plugins ([#2359](https://github.com/NousResearch/hermes-agent/pull/2359))
+- **`session:end` lifecycle event** hook ([#1725](https://github.com/NousResearch/hermes-agent/pull/1725))
+- Fix: require opt-in for project plugin discovery ([#2215](https://github.com/NousResearch/hermes-agent/pull/2215))
+
+---
+
+## 🔒 Security & Reliability
+
+### Security
+- **SSRF protection** for vision_tools and web_tools ([#2679](https://github.com/NousResearch/hermes-agent/pull/2679))
+- **Shell injection prevention** in `_expand_path` via `~user` path suffix ([#2685](https://github.com/NousResearch/hermes-agent/pull/2685))
+- **Block untrusted browser-origin** API server access ([#2451](https://github.com/NousResearch/hermes-agent/pull/2451))
+- **Block sandbox backend creds** from subprocess env ([#1658](https://github.com/NousResearch/hermes-agent/pull/1658))
+- **Block @ references** from reading secrets outside workspace ([#2601](https://github.com/NousResearch/hermes-agent/pull/2601) by @Gutslabs)
+- **Malicious code pattern pre-exec scanner** for terminal_tool ([#2245](https://github.com/NousResearch/hermes-agent/pull/2245))
+- **Harden terminal safety** and sandbox file writes ([#1653](https://github.com/NousResearch/hermes-agent/pull/1653))
+- **PKCE verifier leak** fix + OAuth refresh Content-Type ([#1775](https://github.com/NousResearch/hermes-agent/pull/1775))
+- **Eliminate SQL string formatting** in `execute()` calls ([#2061](https://github.com/NousResearch/hermes-agent/pull/2061) by @dusterbloom)
+- **Harden jobs API** — input limits, field whitelist, startup check ([#2456](https://github.com/NousResearch/hermes-agent/pull/2456))
+
+### Reliability
+- Thread locks on 4 SessionDB methods ([#1704](https://github.com/NousResearch/hermes-agent/pull/1704))
+- File locking for concurrent memory writes ([#1726](https://github.com/NousResearch/hermes-agent/pull/1726))
+- Handle OpenRouter errors gracefully ([#2112](https://github.com/NousResearch/hermes-agent/pull/2112))
+- Guard print() calls against OSError ([#1668](https://github.com/NousResearch/hermes-agent/pull/1668))
+- Safely handle non-string inputs in redacting formatter ([#2392](https://github.com/NousResearch/hermes-agent/pull/2392), [#1700](https://github.com/NousResearch/hermes-agent/pull/1700))
+- ACP: preserve session provider on model switch, persist sessions to disk ([#2380](https://github.com/NousResearch/hermes-agent/pull/2380), [#2071](https://github.com/NousResearch/hermes-agent/pull/2071))
+- API server: persist ResponseStore to SQLite across restarts ([#2472](https://github.com/NousResearch/hermes-agent/pull/2472))
+- Fix: `fetch_nous_models` always TypeError from positional args ([#1699](https://github.com/NousResearch/hermes-agent/pull/1699))
+- Fix: resolve merge conflict markers in cli.py breaking startup ([#2347](https://github.com/NousResearch/hermes-agent/pull/2347))
+- Fix: `minisweagent_path.py` missing from wheel ([#2098](https://github.com/NousResearch/hermes-agent/pull/2098) by @JiwaniZakir)
+
+### Cron System
+- **`[SILENT]` response** — cron agents can suppress delivery ([#1833](https://github.com/NousResearch/hermes-agent/pull/1833))
+- **Scale missed-job grace window** with schedule frequency ([#2449](https://github.com/NousResearch/hermes-agent/pull/2449))
+- **Recover recent one-shot jobs** ([#1918](https://github.com/NousResearch/hermes-agent/pull/1918))
+- Fix: normalize `repeat<=0` to None — jobs deleted after first run when LLM passes -1 ([#2612](https://github.com/NousResearch/hermes-agent/pull/2612) by @Mibayy)
+- Fix: Matrix added to scheduler delivery platform_map ([#2167](https://github.com/NousResearch/hermes-agent/pull/2167) by @buntingszn)
+- Fix: naive ISO timestamps without timezone — jobs fire at wrong time ([#1729](https://github.com/NousResearch/hermes-agent/pull/1729))
+- Fix: `get_due_jobs` reads `jobs.json` twice — race condition ([#1716](https://github.com/NousResearch/hermes-agent/pull/1716))
+- Fix: silent jobs return empty response for delivery skip ([#2442](https://github.com/NousResearch/hermes-agent/pull/2442))
+- Fix: stop injecting cron outputs into gateway session history ([#2313](https://github.com/NousResearch/hermes-agent/pull/2313))
+- Fix: close abandoned coroutine when `asyncio.run()` raises RuntimeError ([#2317](https://github.com/NousResearch/hermes-agent/pull/2317))
+
+---
+
+## 🧪 Testing
+
+- Resolve all consistently failing tests ([#2488](https://github.com/NousResearch/hermes-agent/pull/2488))
+- Replace `FakePath` with `monkeypatch` for Python 3.12 compat ([#2444](https://github.com/NousResearch/hermes-agent/pull/2444))
+- Align Hermes setup and full-suite expectations ([#1710](https://github.com/NousResearch/hermes-agent/pull/1710))
+
+---
+
+## 📚 Documentation
+
+- Comprehensive docs update for recent features ([#1693](https://github.com/NousResearch/hermes-agent/pull/1693), [#2183](https://github.com/NousResearch/hermes-agent/pull/2183))
+- Alibaba Cloud and DingTalk setup guides ([#1687](https://github.com/NousResearch/hermes-agent/pull/1687), [#1692](https://github.com/NousResearch/hermes-agent/pull/1692))
+- Detailed skills documentation ([#2244](https://github.com/NousResearch/hermes-agent/pull/2244))
+- Honcho self-hosted / Docker configuration ([#2475](https://github.com/NousResearch/hermes-agent/pull/2475))
+- Context length detection FAQ and quickstart references ([#2179](https://github.com/NousResearch/hermes-agent/pull/2179))
+- Fix docs inconsistencies across reference and user guides ([#1995](https://github.com/NousResearch/hermes-agent/pull/1995))
+- Fix MCP install commands — use uv, not bare pip ([#1909](https://github.com/NousResearch/hermes-agent/pull/1909))
+- Replace ASCII diagrams with Mermaid/lists ([#2402](https://github.com/NousResearch/hermes-agent/pull/2402))
+- Gemini OAuth provider implementation plan ([#2467](https://github.com/NousResearch/hermes-agent/pull/2467))
+- Discord Server Members Intent marked as required ([#2330](https://github.com/NousResearch/hermes-agent/pull/2330))
+- Fix MDX build error in api-server.md ([#1787](https://github.com/NousResearch/hermes-agent/pull/1787))
+- Align venv path to match installer ([#2114](https://github.com/NousResearch/hermes-agent/pull/2114))
+- New skills added to hub index ([#2281](https://github.com/NousResearch/hermes-agent/pull/2281))
+
+---
+
+## 👥 Contributors
+
+### Core
+- **@teknium1** (Teknium) — 280 PRs
+
+### Community Contributors
+- **@mchzimm** (to_the_max) — GitHub Copilot provider integration ([#1879](https://github.com/NousResearch/hermes-agent/pull/1879))
+- **@jquesnelle** (Jeffrey Quesnelle) — Per-thread persistent event loops fix ([#2214](https://github.com/NousResearch/hermes-agent/pull/2214))
+- **@llbn** (lbn) — Telegram MarkdownV2 strikethrough, spoiler, blockquotes, and escape fixes ([#2199](https://github.com/NousResearch/hermes-agent/pull/2199), [#2200](https://github.com/NousResearch/hermes-agent/pull/2200))
+- **@dusterbloom** — SQL injection prevention + local server context window querying ([#2061](https://github.com/NousResearch/hermes-agent/pull/2061), [#2091](https://github.com/NousResearch/hermes-agent/pull/2091))
+- **@0xbyt4** — Anthropic tool_calls None guard + OpenCode-Go provider config fix ([#2209](https://github.com/NousResearch/hermes-agent/pull/2209), [#2393](https://github.com/NousResearch/hermes-agent/pull/2393))
+- **@sai-samarth** (Saisamarth) — WhatsApp send_message routing + systemd node path ([#1769](https://github.com/NousResearch/hermes-agent/pull/1769), [#1767](https://github.com/NousResearch/hermes-agent/pull/1767))
+- **@Gutslabs** (Guts) — Block @ references from reading secrets ([#2601](https://github.com/NousResearch/hermes-agent/pull/2601))
+- **@Mibayy** (Mibay) — Cron job repeat normalization ([#2612](https://github.com/NousResearch/hermes-agent/pull/2612))
+- **@ten-jampa** (Tenzin Jampa) — Gateway /title command fix ([#2379](https://github.com/NousResearch/hermes-agent/pull/2379))
+- **@cutepawss** (lila) — File tools search pagination fix ([#1824](https://github.com/NousResearch/hermes-agent/pull/1824))
+- **@hanai** (Hanai) — OpenAI TTS base_url support ([#2064](https://github.com/NousResearch/hermes-agent/pull/2064))
+- **@rovle** (Lovre Pešut) — Daytona sandbox API migration ([#2063](https://github.com/NousResearch/hermes-agent/pull/2063))
+- **@buntingszn** (bunting szn) — Matrix cron delivery support ([#2167](https://github.com/NousResearch/hermes-agent/pull/2167))
+- **@InB4DevOps** — Token counter reset on new session ([#2101](https://github.com/NousResearch/hermes-agent/pull/2101))
+- **@JiwaniZakir** (Zakir Jiwani) — Missing file in wheel fix ([#2098](https://github.com/NousResearch/hermes-agent/pull/2098))
+- **@ygd58** (buray) — Delegate tool parent tool names fix ([#2083](https://github.com/NousResearch/hermes-agent/pull/2083))
+
+---
+
+**Full Changelog**: [v2026.3.17...v2026.3.23](https://github.com/NousResearch/hermes-agent/compare/v2026.3.17...v2026.3.23)
@@ -1,322 +0,0 @@
-# Política de Seguridad de Hermes Agent
-
-Este documento describe el modelo de confianza de Hermes Agent, identifica el
-único límite de seguridad que el proyecto trata como estructural y define el
-alcance para los informes de vulnerabilidades.
-
-## 1. Reportar una Vulnerabilidad
-
-Reporta de forma privada a través de [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
-o **security@nousresearch.com**. No abras issues públicos para
-vulnerabilidades de seguridad. **Hermes Agent no opera un programa de
-recompensas por errores.**
-
-Un informe útil incluye:
-
- Una descripción concisa y evaluación de severidad.
- El componente afectado, identificado por ruta de archivo y rango de líneas
-  (ej. `path/to/file.py:120-145`).
- Detalles del entorno (`hermes version`, SHA del commit, SO, versión de Python).
- Una reproducción contra `main` o el último release.
- Una declaración de qué límite de confianza del §2 se cruza.
-
-Por favor lee el §2 y el §3 antes de enviar. Los informes que demuestren
-límites de una heurística en proceso que esta política no trate como un
-límite serán cerrados como fuera de alcance bajo el §3 — pero consulta el §3.2:
-siguen siendo bienvenidos como issues o pull requests regulares, simplemente no
-a través del canal de seguridad privado.
-
---
-
-## 2. Modelo de Confianza
-
-Hermes Agent es un agente personal de un solo inquilino. Su postura es
-por capas, y las capas no tienen el mismo peso. Los reportadores y
-operadores deben razonar sobre ellas en los mismos términos.
-
-### 2.1 Definiciones
-
- **Proceso del agente.** El intérprete Python que ejecuta Hermes Agent,
-  incluyendo cualquier módulo Python que haya cargado (habilidades, plugins,
-  manejadores de hooks).
- **Backend de terminal.** Un objetivo de ejecución conectado para la
-  herramienta `terminal()`. El predeterminado ejecuta comandos directamente en el host.
-  Otros backends ejecutan comandos dentro de un contenedor, sandbox en la nube o
-  host remoto.
- **Superficie de entrada.** Cualquier canal a través del cual el contenido entra en el
-  contexto del agente: entrada del operador, fetches web, email, mensajes del gateway,
-  lecturas de archivos, respuestas del servidor MCP, resultados de herramientas.
- **Envolvente de confianza.** El conjunto de recursos a los que un operador ha otorgado
-  implícitamente acceso a Hermes Agent al ejecutarlo — típicamente, todo lo que
-  la propia cuenta de usuario del operador puede alcanzar en el host.
- **Postura.** Una declaración explícita en la documentación o código de Hermes Agent
-  sobre cómo una capa consumidora (adaptador, UI, escritor de archivos,
-  shell) debe tratar la salida del agente — ej. "el dashboard renderiza
-  la salida del agente como HTML inerte."
-
-### 2.2 El Límite: Aislamiento a Nivel de SO
-
-**El único límite de seguridad contra un LLM adversario es el
-sistema operativo.** Nada dentro del proceso del agente constituye
-contención — ni la puerta de aprobación, ni la redacción de salida, ni ningún
-escáner de patrones, ni ninguna lista de herramientas permitidas. Cualquier componente dentro
-del proceso que filtre la salida del LLM es una heurística operando sobre una
-cadena influenciada por el atacante, y esta política lo trata como tal.
-
-Hermes Agent admite dos posturas de aislamiento a nivel de SO. Abordan
-diferentes amenazas y un operador debe elegir deliberadamente.
-
-#### Aislamiento del backend de terminal
-
-Un backend de terminal no predeterminado ejecuta comandos de shell emitidos por el LLM
-dentro de un contenedor, host remoto o sandbox en la nube. Las herramientas de archivos
-(`read_file`, `write_file`, `patch`) también se ejecutan a través de este backend,
-ya que están implementadas sobre el contrato del shell — no pueden
-alcanzar rutas que el backend no exponga.
-
-Lo que confina: todo lo que el agente hace emitiendo operaciones de shell o
-de archivos. Lo que **no** confina: todo lo que el agente hace en su propio
-proceso Python. Eso incluye la herramienta de ejecución de código (lanzada como
-subproceso del host), subprocesos MCP (lanzados desde el entorno del agente),
-carga de plugins, despacho de hooks y carga de habilidades (todos importados en el
-intérprete del agente).
-
-El aislamiento del backend de terminal es la postura correcta cuando la preocupación es
-que el LLM emita comandos de shell destructivos o escrituras de herramientas de archivo no deseadas, y el
-operador es de confianza.
-
-#### Envoltura del proceso completo
-
-La envoltura del proceso completo ejecuta todo el árbol de procesos del agente dentro de un
-sandbox. Cada ruta de código — shell, ejecución de código, MCP, herramientas de archivos,
-plugins, hooks, carga de habilidades — está sujeta a la misma política de sistema de archivos,
-red, proceso e (donde sea aplicable) inferencia.
-
-Hermes Agent admite esto de dos maneras:
-
- **La propia imagen Docker de Hermes Agent y la configuración de Compose.** Más
-  liviana; el agente se ejecuta en un contenedor estándar con montajes y
-  política de red configurados por el operador.
- **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
-  OpenShell proporciona sandboxes por sesión con política declarativa
-  a través de capas de sistema de archivos, red (egreso L7), proceso/syscall e
-  enrutamiento de inferencia. Las políticas de red e inferencia son
-  recargables en caliente. Las credenciales se inyectan desde un almacén de Proveedor
-  y nunca tocan el sistema de archivos del sandbox.
-
-Bajo una envoltura de proceso completo, las heurísticas en proceso de Hermes Agent
-(§2.4) funcionan como prevención de accidentes en capas sobre un límite real.
-Esta es la postura soportada cuando el agente ingiere contenido de superficies
-que el operador no controla — la web abierta, email entrante, canales de
-múltiples usuarios, servidores MCP no confiables — y para despliegues en
-producción o compartidos.
-
-Los operadores que ejecuten el backend local predeterminado con superficies de entrada
-no confiables, o que ejecuten un sandbox de backend de terminal esperando que contenga
-rutas de código que no pasan por el shell, están operando fuera de la postura de
-seguridad soportada.
-
-### 2.3 Alcance de Credenciales
-
-Hermes Agent filtra el entorno que pasa a sus componentes en proceso de
-menor confianza: subprocesos de shell, subprocesos MCP y el proceso hijo
-de ejecución de código. Las credenciales como las claves API del proveedor y los
-tokens del gateway se eliminan por defecto; las variables declaradas explícitamente
-por el operador o por una habilidad cargada se pasan.
-
-Esto reduce la exfiltración casual. No es contención. Cualquier
-componente que se ejecute dentro del proceso del agente (habilidades, plugins, manejadores
-de hooks) puede leer lo que el agente mismo puede leer, incluidas las
-credenciales en memoria. La mitigación contra un componente en proceso comprometido
-es la revisión del operador antes de instalar (§2.4, §2.5), no el
-saneamiento del entorno.
-
-### 2.4 Heurísticas en Proceso
-
-Los siguientes componentes filtran o advierten sobre el comportamiento del LLM. Son
-útiles. No son límites.
-
- La **puerta de aprobación** detecta patrones de shell destructivos comunes
-  y le pide al operador confirmación antes de la ejecución. El shell es Turing-
-  completo; una lista de denegación sobre cadenas de shell es estructuralmente
-  incompleta. La puerta detecta errores en modo cooperativo, no salidas
-  adversariales.
- **La redacción de salida** elimina patrones similares a secretos de la visualización.
-  Un productor de salida motivado la evitará.
- **Skills Guard** escanea el contenido de habilidades instalables en busca de patrones
-  de inyección. Es una ayuda de revisión; el límite para habilidades de terceros
-  es la revisión del operador antes de instalar. Revisar una habilidad significa
-  leer su código Python y scripts, no solo su descripción SKILL.md —
-  las habilidades ejecutan Python arbitrario en el momento de importación.
-
-### 2.5 Modelo de Confianza de Plugins
-
-Los plugins se cargan en el proceso del agente y se ejecutan con todos los privilegios
-del agente: pueden leer las mismas credenciales, llamar a las mismas
-herramientas, registrar los mismos hooks e importar los mismos módulos que
-cualquier cosa incluida en el árbol. El límite para los plugins de terceros es
-la revisión del operador antes de instalar — la misma regla que las habilidades (§2.4),
-mencionado por separado porque los plugins son arquitectónicamente más pesados
-y a menudo incluyen sus propios servicios en segundo plano, oyentes de red
-y dependencias.
-
-Un plugin malicioso o con errores no es una vulnerabilidad en Hermes Agent
-en sí mismo. Los errores en la ruta de instalación o descubrimiento de plugins de Hermes Agent
-que impidan al operador ver lo que está instalando están en alcance bajo el §3.1.
-
-### 2.6 Superficies Externas
-
-Una **superficie externa** es cualquier canal fuera del proceso del agente local
-a través del cual un llamador puede despachar trabajo del agente, resolver
-aprobaciones o recibir salida del agente. Cada superficie tiene su propio
-modelo de autorización, pero las reglas a continuación se aplican uniformemente.
-
-**Superficies en Hermes Agent:**
-
- **Adaptadores de plataforma del gateway.** Integraciones de mensajería en
-  `gateway/platforms/` (Telegram, Discord, Slack, email, SMS, etc.)
-  y adaptadores análogos incluidos como plugins.
- **Superficies HTTP expuestas en red.** El adaptador del servidor API, el
-  plugin del dashboard, los endpoints HTTP del plugin kanban, y cualquier
-  otro plugin que vincule un socket de escucha.
- **Adaptadores de Editor / IDE.** El adaptador ACP (`acp_adapter/`) e
-  integraciones equivalentes que aceptan solicitudes de un proceso cliente local.
- **El gateway TUI (`tui_gateway/`).** Backend JSON-RPC para la
-  UI de terminal Ink, alcanzado a través de IPC local.
-
-**Reglas uniformes:**
-
-1. **Se requiere autorización en cada superficie que cruce un límite de confianza.** Para
-   superficies de mensajería y HTTP en red, el límite es la red: la autorización
-   significa una lista de llamadores permitidos configurada por el operador. Para superficies
-   de editor e IPC local (ACP, gateway TUI), el límite es la cuenta de usuario del host:
-   la autorización significa depender del control de acceso a nivel de SO (permisos
-   de archivos, vinculaciones solo a loopback) y no exponer la superficie más allá
-   del usuario local sin una capa de autenticación de red explícita.
-2. **Se requiere una lista de permitidos para cada adaptador de red habilitado.**
-   Los adaptadores deben rechazar despachar trabajo del agente, resolver
-   aprobaciones o transmitir salida hasta que se establezca una lista de permitidos. Las rutas
-   de código que fallan de forma abierta cuando no hay lista de permitidos configurada son errores de código en
-   alcance bajo el §3.1.
-3. **Los identificadores de sesión son manejadores de enrutamiento, no límites de autorización.**
-   Conocer el ID de sesión de otro llamador no otorga acceso a sus aprobaciones o salida;
-   la autorización siempre se vuelve a verificar contra la lista de permitidos (o equivalente
-   a nivel de SO).
-4. **Dentro del conjunto autorizado, todos los llamadores tienen la misma confianza.**
-   Hermes Agent no modela capacidades por llamador dentro de un único adaptador.
-   Los operadores que necesiten separación de capacidades deben ejecutar instancias
-   de agente separadas con listas de permitidos separadas.
-5. **Vincular una superficie solo local a una interfaz no-loopback es una decisión de
-   operador de emergencia (§3.2).** El dashboard y otros servidores HTTP de plugins
-   son predeterminados a loopback; exponerlos a través de `--host 0.0.0.0` o equivalente
-   hace que el fortalecimiento de exposición pública (§4) sea responsabilidad del operador.
-
---
-
-## 3. Alcance
-
-### 3.1 En Alcance
-
- Escape de una postura de aislamiento a nivel de SO declarada (§2.2): una
-  ruta de código controlada por el atacante alcanzando estado que la postura
-  afirmó confinar.
- Acceso no autorizado a superficie externa: un llamador fuera del conjunto de
-  autorización configurado (lista de permitidos, o equivalente a nivel de SO
-  para superficies de IPC local) despachando trabajo, recibiendo salida o
-  resolviendo aprobaciones (§2.6).
- Exfiltración de credenciales: filtración de credenciales del operador o
-  material de autorización de sesión a un destino fuera del envolvente de
-  confianza, a través de un mecanismo que debería haberlo prevenido
-  (error de saneamiento de entorno, registro del adaptador, error de transporte
-  que vacía credenciales a un upstream, etc.).
- Violaciones de la documentación del modelo de confianza: código que se comporta
-  contrariamente a lo que esta política, la propia documentación de Hermes Agent o
-  las expectativas razonables del operador predecirían — incluyendo casos donde
-  Hermes Agent ha documentado una postura sobre cómo su salida debe ser
-  renderizada por una capa consumidora (dashboard, adaptador de gateway,
-  escritor de archivos, shell) y una ruta de código rompe esa postura.
-
-### 3.2 Fuera de Alcance
-
-"Fuera de alcance" aquí significa "no es una vulnerabilidad de seguridad bajo esta
-política." No significa "no vale la pena reportarlo." Las mejoras a las
-heurísticas en proceso, ideas de fortalecimiento y correcciones de UX son bienvenidas como
-issues o pull requests regulares — la puerta de aprobación siempre puede detectar
-más patrones, la redacción puede volverse más inteligente, el comportamiento del adaptador
-puede apretarse siempre. Estos elementos simplemente no van a través del canal de
-divulgación privada y no reciben avisos.
-
- **Bypasses de heurísticas en proceso (§2.4)** — bypasses de regex de la puerta de aprobación,
-  bypasses de redacción, bypasses de patrones de Skills Guard, e informes
-  análogos contra heurísticas futuras. Estos componentes no son límites;
-  vencerlos no es una vulnerabilidad bajo esta política.
- **Inyección de prompts per se.** Hacer que el LLM emita salida inusual
-  — a través de contenido inyectado, alucinación, artefactos de entrenamiento,
-  o cualquier otra causa — no es en sí mismo una vulnerabilidad. "Logré
-  inyección de prompts" sin un resultado encadenado del §3.1 no es un informe
-  procesable bajo esta política.
- **Consecuencias de una postura de aislamiento elegida.** Los informes de que
-  una ruta de código que opera dentro del alcance de su postura puede hacer lo que esa
-  postura permite no son vulnerabilidades. Ejemplos: herramientas de shell o archivos
-  que alcanzan estado del host bajo el backend local; subprocesos de ejecución de código
-  o MCP que alcanzan estado del host bajo aislamiento de backend de terminal que solo
-  sandboxea el shell; informes cuyas precondiciones requieren acceso de escritura preexistente
-  a archivos de configuración o credenciales propiedad del operador (esos ya están dentro
-  del envolvente de confianza).
- **Configuraciones documentadas de emergencia.** Compensaciones seleccionadas por el operador
-  que deshabilitan explícitamente protecciones: `--insecure` y flags equivalentes
-  en el dashboard u otros componentes, aprobaciones deshabilitadas,
-  backend local en producción, perfiles de desarrollo que evitan
-  la seguridad de hermes-home, y similares. Los informes contra esas
-  configuraciones no son vulnerabilidades — eso es el trabajo del flag.
- **Habilidades y plugins contribuidos por la comunidad.** Las habilidades de terceros
-  (incluyendo el repositorio de habilidades de la comunidad) y los plugins de terceros
-  están en la superficie de revisión del operador, no en la superficie de confianza de Hermes Agent
-  (§2.4, §2.5). Una habilidad o plugin que haga algo
-  malicioso es el modo de falla esperado de uno que no fue
-  revisado, no una vulnerabilidad en Hermes Agent. Los errores en la ruta de
-  instalación de habilidades o plugins de Hermes Agent que impidan al
-  operador ver lo que está instalando están en alcance bajo el §3.1.
- **Exposición pública sin controles externos.** Exponer el
-  gateway o la API a la internet pública sin autenticación,
-  VPN o firewall.
- **Restricciones de lectura/escritura a nivel de herramienta en una postura donde el shell está
-  permitido.** Si una ruta es alcanzable a través de la herramienta terminal, los informes
-  de que otras herramientas de archivos pueden alcanzarla no añaden nada.
-
---
-
-## 4. Fortalecimiento del Despliegue
-
-La decisión de fortalecimiento más importante es hacer coincidir el aislamiento
-(§2.2) con la confianza del contenido que el agente ingerirá. Más allá de eso:
-
- Ejecuta el agente como usuario no-root. La imagen de contenedor proporcionada
-  hace esto por defecto.
- Mantén las credenciales en el archivo de credenciales del operador con permisos
-  estrictos, nunca en la configuración principal, nunca en control de versiones.
-  Bajo OpenShell, usa el almacén de Proveedores en lugar de un archivo de
-  credenciales en disco.
- No expongas el gateway o la API a la internet pública sin
-  VPN, Tailscale o protección de firewall. Bajo OpenShell, usa la
-  capa de política de red para restringir el egreso.
- Configura una lista de llamadores permitidos para cada adaptador de red expuesto
-  que habilites (§2.6).
- Revisa las habilidades y plugins de terceros antes de instalar (§2.4,
-  §2.5). Para las habilidades, esto significa leer el Python y los scripts,
-  no solo SKILL.md. Los informes de Skills Guard y el registro de auditoría
-  de instalación son la superficie de revisión.
- Hermes Agent incluye guardias de cadena de suministro para lanzamientos de servidores
-  MCP y para cambios de dependencias / paquetes incluidos en CI; consulta
-  `CONTRIBUTING.es.md` para más detalles.
-
---
-
-## 5. Divulgación
-
- **Ventana de divulgación coordinada:** 90 días desde el informe, o hasta que se
-  publique una corrección, lo que ocurra primero.
- **Canal:** el hilo GHSA o correspondencia por email con
-  security@nousresearch.com.
- **Crédito:** los reportadores reciben crédito en las notas de versión a menos que
-  se solicite anonimato.
@@ -1,332 +0,0 @@
-# Hermes Agent Security Policy
-
-This document describes Hermes Agent's trust model, names the one
-security boundary the project treats as load-bearing, and defines the
-scope for vulnerability reports.
-
-## 1. Reporting a Vulnerability
-
-Report privately via [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
-or **security@nousresearch.com**. Do not open public issues for
-security vulnerabilities. **Hermes Agent does not operate a bug
-bounty program.**
-
-A useful report includes:
-
- A concise description and severity assessment.
- The affected component, identified by file path and line range
-  (e.g. `path/to/file.py:120-145`).
- Environment details (`hermes version`, commit SHA, OS, Python
-  version).
- A reproduction against `main` or the latest release.
- A statement of which trust boundary in §2 is crossed.
-
-Please read §2 and §3 before submitting. Reports that demonstrate
-limits of an in-process heuristic this policy does not treat as a
-boundary will be closed as out-of-scope under §3 — but see §3.2:
-they are still welcome as regular issues or pull requests, just not
-through the private security channel.
-
---
-
-## 2. Trust Model
-
-Hermes Agent is a single-tenant personal agent. Its posture is
-layered, and the layers are not equally load-bearing. Reporters and
-operators should reason about them in the same terms.
-
-### 2.1 Definitions
-
- **Agent process.** The Python interpreter running Hermes Agent,
-  including any Python modules it has loaded (skills, plugins,
-  hook handlers).
- **Terminal backend.** A pluggable execution target for the
-  `terminal()` tool. The default runs commands directly on the host.
-  Other backends run commands inside a container, cloud sandbox, or
-  remote host.
- **Input surface.** Any channel through which content enters the
-  agent's context: operator input, web fetches, email, gateway
-  messages, file reads, MCP server responses, tool results.
- **Trust envelope.** The set of resources an operator has implicitly
-  granted Hermes Agent access to by running it — typically, whatever
-  the operator's own user account can reach on the host.
- **Stance.** An explicit statement in Hermes Agent's documentation
-  or code about how a consuming layer (adapter, UI, file writer,
-  shell) should treat agent output — e.g. "the dashboard renders
-  agent output as inert HTML."
-
-### 2.2 The Boundary: OS-Level Isolation
-
-**The only security boundary against an adversarial LLM is the
-operating system.** Nothing inside the agent process constitutes
-containment — not the approval gate, not output redaction, not any
-pattern scanner, not any tool allowlist. Any in-process component
-that screens LLM output is a heuristic operating on an
-attacker-influenced string, and this policy treats it as such.
-
-Hermes Agent supports two OS-level isolation postures. They address
-different threats and an operator should choose deliberately.
-
-#### Terminal-backend isolation
-
-A non-default terminal backend runs LLM-emitted shell commands
-inside a container, remote host, or cloud sandbox. The file tools
-(`read_file`, `write_file`, `patch`) also run through this backend,
-since they are implemented on top of the shell contract — they
-cannot reach paths the backend doesn't expose.
-
-What this confines: anything the agent does by issuing shell or
-file operations. What this does **not** confine: everything the
-agent does in its own Python process. That includes the
-code-execution tool (spawned as a host subprocess), MCP subprocesses
-(spawned from the agent's environment), plugin loading, hook
-dispatch, and skill loading (all imported into the agent
-interpreter).
-
-Terminal-backend isolation is the right posture when the concern is
-LLM-emitted destructive shell or unwanted file-tool writes, and the
-operator is otherwise trusted.
-
-#### Whole-process wrapping
-
-Whole-process wrapping runs the entire agent process tree inside a
-sandbox. Every code path — shell, code-execution, MCP, file tools,
-plugins, hooks, skill loading — is subject to the same filesystem,
-network, process, and (where applicable) inference policy.
-
-Hermes Agent supports this in two ways:
-
- **Hermes Agent's own Docker image and Compose setup.** Lighter-
-  weight; the agent runs in a standard container with operator-
-  configured mounts and network policy.
- **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
-  OpenShell provides per-session sandboxes with declarative policy
-  across filesystem, network (L7 egress), process/syscall, and
-  inference-routing layers. Network and inference policies are
-  hot-reloadable. Credentials are injected from a Provider store
-  and never touch the sandbox filesystem.
-
-Under a whole-process wrapper, Hermes Agent's in-process heuristics
-(§2.4) function as accident-prevention layered on top of a real
-boundary. This is the supported posture when the agent ingests
-content from surfaces the operator does not control — the open web,
-inbound email, multi-user channels, untrusted MCP servers — and for
-production or shared deployments.
-
-Operators running the default local backend with untrusted input
-surfaces, or running a terminal-backend sandbox and expecting it to
-contain code paths that don't go through the shell, are operating
-outside the supported security posture.
-
-### 2.3 Credential Scoping
-
-Hermes Agent filters the environment it passes to its lower-trust
-in-process components: shell subprocesses, MCP subprocesses,
-cron job scripts, and the code-execution child. Credentials like
-provider API keys and gateway tokens are stripped by default;
-variables explicitly declared by the operator or by a loaded
-skill are passed through.
-
-This reduces casual exfiltration. It is not containment. Any
-component running inside the agent process (skills, plugins, hook
-handlers) can read whatever the agent itself can read, including
-in-memory credentials. The mitigation against a compromised
-in-process component is operator review before install (§2.4,
-§2.5), not environment scrubbing.
-
-### 2.4 In-Process Heuristics
-
-The following components screen or warn about LLM behavior. They
-are useful. They are not boundaries.
-
- The **approval gate** detects common destructive shell patterns
-  and prompts the operator before execution. Shell is Turing-
-  complete; a denylist over shell strings is structurally
-  incomplete. The gate catches cooperative-mode mistakes, not
-  adversarial output.
- **Output redaction** strips secret-like patterns from display.
-  A motivated output producer will defeat it.
- **Skills Guard** scans installable skill content for injection
-  patterns. It is a review aid; the boundary for third-party skills
-  is operator review before install. Reviewing a skill means
-  reading its Python code and scripts, not just its SKILL.md
-  description — skills execute arbitrary Python at import time.
-
-### 2.5 Plugin Trust Model
-
-Plugins load into the agent process and run with full agent
-privileges: they can read the same credentials, call the same
-tools, register the same hooks, and import the same modules as
-anything shipped in-tree. The boundary for third-party plugins is
-operator review before install — the same rule as skills (§2.4),
-called out separately because plugins are architecturally heavier
-and often ship their own background services, network listeners,
-and dependencies.
-
-A malicious or buggy plugin is not a vulnerability in Hermes Agent
-itself. Bugs in Hermes Agent's plugin-install or plugin-discovery
-path that prevent the operator from seeing what they're installing
-are in scope under §3.1.
-
-### 2.6 External Surfaces
-
-An **external surface** is any channel outside the local agent
-process through which a caller can dispatch agent work, resolve
-approvals, or receive agent output. Each surface has its own
-authorization model, but the rules below apply uniformly.
-
-**Surfaces in Hermes Agent:**
-
- **Gateway platform adapters.** Messaging integrations in
-  `gateway/platforms/` (Telegram, Discord, Slack, email, SMS, etc.)
-  and analogous adapters shipped as plugins.
- **Network-exposed HTTP surfaces.** The API server adapter, the
-  dashboard plugin, the kanban plugin's HTTP endpoints, and any
-  other plugin that binds a listening socket.
- **Editor / IDE adapters.** The ACP adapter (`acp_adapter/`) and
-  equivalent integrations that accept requests from a local client
-  process.
- **The TUI gateway (`tui_gateway/`).** JSON-RPC backend for the
-  Ink terminal UI, reached over local IPC.
-
-**Uniform rules:**
-
-1. **Authorization is required at every surface that crosses a
-   trust boundary.** For messaging and network HTTP surfaces, the
-   boundary is the network: authorization means an operator-
-   configured caller allowlist. For editor and local-IPC surfaces
-   (ACP, TUI gateway), the boundary is the host's user account:
-   authorization means relying on OS-level access control (file
-   permissions, loopback-only binds) and not exposing the surface
-   beyond the local user without an explicit network auth layer.
-2. **An allowlist is required for every enabled network-exposed
-   adapter.** Adapters must refuse to dispatch agent work, resolve
-   approvals, or relay output until an allowlist is set. Code paths
-   that fail open when no allowlist is configured are code bugs in
-   scope under §3.1.
-3. **Session identifiers are routing handles, not authorization
-   boundaries.** Knowing another caller's session ID does not grant
-   access to their approvals or output; authorization is always
-   re-checked against the allowlist (or OS-level equivalent).
-4. **Within the authorized set, all callers are equally trusted.**
-   Hermes Agent does not model per-caller capabilities inside a
-   single adapter. Operators who need capability separation should
-   run separate agent instances with separate allowlists.
-5. **Binding a local-only surface to a non-loopback interface is a
-   break-glass operator decision (§3.2).** The dashboard and other
-   plugin HTTP servers default to loopback; exposing them via
-   `--host 0.0.0.0` or equivalent makes public-exposure hardening
-   (§4) the operator's responsibility.
-
---
-
-## 3. Scope
-
-### 3.1 In Scope
-
- Escape from a declared OS-level isolation posture (§2.2): an
-  attacker-controlled code path reaching state that the posture
-  claimed to confine.
- Unauthorized external-surface access: a caller outside the
-  configured authorization set (allowlist, or OS-level equivalent
-  for local-IPC surfaces) dispatching work, receiving output, or
-  resolving approvals (§2.6).
- Credential exfiltration: leakage of operator credentials or
-  session authorization material to a destination outside the
-  trust envelope, via a mechanism that should have prevented it
-  (environment scrubbing bug, adapter logging, transport error
-  that flushes credentials to an upstream, etc.).
- Trust-model documentation violations: code behaving contrary to
-  what this policy, Hermes Agent's own documentation, or reasonable
-  operator expectations would predict — including cases where
-  Hermes Agent has documented a stance about how its output should
-  be rendered by a consuming layer (dashboard, gateway adapter,
-  file writer, shell) and a code path breaks that stance.
-
-### 3.2 Out of Scope
-
-"Out of scope" here means "not a security vulnerability under this
-policy." It does not mean "not worth reporting." Improvements to the
-in-process heuristics, hardening ideas, and UX fixes are welcome as
-regular issues or pull requests — the approval gate can always catch
-more patterns, redaction can always get smarter, adapter behavior
-can always be tightened. These items just don't go through the
-private-disclosure channel and don't receive advisories.
-
- **Bypasses of in-process heuristics (§2.4)** — approval-gate regex
-  bypasses, redaction bypasses, Skills Guard pattern bypasses, and
-  analogous reports against future heuristics. These components are
-  not boundaries; defeating them is not a vulnerability under this
-  policy.
- **Prompt injection per se.** Getting the LLM to emit unusual
-  output — via injected content, hallucination, training artifacts,
-  or any other cause — is not itself a vulnerability. "I achieved
-  prompt injection" without a chained §3.1 outcome is not an
-  actionable report under this policy.
- **Consequences of a chosen isolation posture.** Reports that a
-  code path operating within its posture's scope can do what that
-  posture permits are not vulnerabilities. Examples: shell or file
-  tools reaching host state under the local backend; code-execution
-  or MCP subprocesses reaching host state under terminal-backend
-  isolation that only sandboxes shell; reports whose preconditions
-  require pre-existing write access to operator-owned configuration
-  or credential files (those are already inside the trust envelope).
- **Documented break-glass settings.** Operator-selected trade-offs
-  that explicitly disable protections: `--insecure` and equivalent
-  flags on the dashboard or other components, disabled approvals,
-  local backend in production, development profiles that bypass
-  hermes-home security, and similar. Reports against those
-  configurations are not vulnerabilities — that's the flag's job.
- **Community-contributed skills and plugins.** Third-party skills
-  (including the community skills repository) and third-party
-  plugins are in the operator's review surface, not Hermes Agent's
-  trust surface (§2.4, §2.5). A skill or plugin doing something
-  malicious is the expected failure mode of one that wasn't
-  reviewed, not a vulnerability in Hermes Agent. Bugs in Hermes
-  Agent's skill-install or plugin-install path that prevent the
-  operator from seeing what they're installing are in scope under
-  §3.1.
- **Public exposure without external controls.** Exposing the
-  gateway or API to the public internet without authentication,
-  VPN, or firewall.
- **Tool-level read/write restrictions on a posture where shell is
-  permitted.** If a path is reachable via the terminal tool, reports
-  that other file tools can reach it add nothing.
-
---
-
-## 4. Deployment Hardening
-
-The single most important hardening decision is matching isolation
-(§2.2) to the trust of the content the agent will ingest. Beyond
-that:
-
- Run the agent as a non-root user. The supplied container image
-  does this by default.
- Keep credentials in the operator credential file with tight
-  permissions, never in the main config, never in version control.
-  Under OpenShell, use the Provider store rather than an on-disk
-  credential file.
- Do not expose the gateway or API to the public internet without
-  VPN, Tailscale, or firewall protection. Under OpenShell, use the
-  network policy layer to restrict egress.
- Configure a caller allowlist for every network-exposed adapter
-  you enable (§2.6).
- Review third-party skills and plugins before install (§2.4,
-  §2.5). For skills, this means reading the Python and scripts,
-  not just SKILL.md. Skills Guard reports and the install audit
-  log are the review surface.
- Hermes Agent includes supply-chain guards for MCP server
-  launches and for dependency / bundled-package changes in CI; see
-  `CONTRIBUTING.md` for specifics.
-
---
-
-## 5. Disclosure
-
- **Coordinated disclosure window:** 90 days from report, or until a
-  fix is released, whichever comes first.
- **Channel:** the GHSA thread or email correspondence with
-  security@nousresearch.com.
- **Credit:** reporters are credited in release notes unless
-  anonymity is requested.
@@ -1,32 +1,18 @@
-"""ACP auth helpers — detect and advertise Hermes authentication methods."""
+"""ACP auth helpers — detect the currently configured Hermes provider."""

 from __future__ import annotations

-from typing import Any, Optional
-
-
-TERMINAL_SETUP_AUTH_METHOD_ID = "hermes-setup"
+from typing import Optional


 def detect_provider() -> Optional[str]:
-    """Resolve the active Hermes runtime provider, or None if unavailable.
-
-    Treats a ``Callable`` ``api_key`` (Azure Foundry Entra ID bearer
-    token provider — see :mod:`agent.azure_identity_adapter`) as a valid
-    credential. Without this, ACP sessions for Entra-configured Foundry
-    deployments silently default to ``"openrouter"`` and the ACP auth
-    handshake rejects the legitimate provider.
-    """
+    """Resolve the active Hermes runtime provider, or None if unavailable."""
    try:
        from hermes_cli.runtime_provider import resolve_runtime_provider
        runtime = resolve_runtime_provider()
        api_key = runtime.get("api_key")
        provider = runtime.get("provider")
-        if not isinstance(provider, str) or not provider.strip():
-            return None
-        is_string_key = isinstance(api_key, str) and api_key.strip()
-        is_callable_provider = callable(api_key) and not isinstance(api_key, str)
-        if is_string_key or is_callable_provider:
+        if isinstance(api_key, str) and api_key.strip() and isinstance(provider, str) and provider.strip():
            return provider.strip().lower()
    except Exception:
        return None
@@ -36,44 +22,3 @@ def detect_provider() -> Optional[str]:
 def has_provider() -> bool:
    """Return True if Hermes can resolve any runtime provider credentials."""
    return detect_provider() is not None
-
-
-def build_auth_methods() -> list[Any]:
-    """Return registry-compatible ACP auth methods for Hermes.
-
-    The official ACP registry validates that agents advertise at least one
-    usable auth method during the initial handshake. A fresh Zed install may
-    not have Hermes provider credentials configured yet, so Hermes always
-    advertises a terminal setup method. When credentials are already present,
-    it also advertises the resolved provider as the default agent-managed
-    runtime credential method.
-    """
-    from acp.schema import AuthMethodAgent, TerminalAuthMethod
-
-    methods: list[Any] = []
-    provider = detect_provider()
-    if provider:
-        methods.append(
-            AuthMethodAgent(
-                id=provider,
-                name=f"{provider} runtime credentials",
-                description=(
-                    "Authenticate Hermes using the currently configured "
-                    f"{provider} runtime credentials."
-                ),
-            )
-        )
-
-    methods.append(
-        TerminalAuthMethod(
-            id=TERMINAL_SETUP_AUTH_METHOD_ID,
-            name="Configure Hermes provider",
-            description=(
-                "Open Hermes' interactive model/provider setup in a terminal. "
-                "Use this when Hermes has not been configured on this machine yet."
-            ),
-            type="terminal",
-            args=["--setup"],
-        )
-    )
-    return methods
@@ -1,338 +0,0 @@
-"""Pre-execution ACP edit approval helpers.
-
-This module is intentionally isolated from the generic tool registry.  ACP binds
-an edit approval requester in a ContextVar for the duration of one ACP agent run;
-CLI, gateway, and other sessions leave it unset and therefore bypass this guard.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-import re
-import tempfile
-from concurrent.futures import TimeoutError as FutureTimeout
-from contextvars import ContextVar, Token
-from dataclasses import dataclass
-from itertools import count
-from pathlib import Path
-from typing import Any, Callable
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class EditProposal:
-    """A proposed single-file edit that can be shown to an ACP client."""
-
-    tool_name: str
-    path: str
-    old_text: str | None
-    new_text: str
-    arguments: dict[str, Any]
-
-
-EditApprovalRequester = Callable[[EditProposal], bool]
-
-_EDIT_APPROVAL_REQUESTER: ContextVar[EditApprovalRequester | None] = ContextVar(
-    "ACP_EDIT_APPROVAL_REQUESTER",
-    default=None,
-)
-_PERMISSION_REQUEST_IDS = count(1)
-
-
-SENSITIVE_AUTO_APPROVE_NAMES = {".env", ".env.local", ".env.production", "id_rsa", "id_ed25519"}
-AUTO_APPROVE_ASK = "ask"
-AUTO_APPROVE_WORKSPACE = "workspace_session"
-AUTO_APPROVE_SESSION = "session"
-
-
-def set_edit_approval_requester(requester: EditApprovalRequester | None) -> Token:
-    """Bind an ACP edit approval requester for the current context."""
-
-    return _EDIT_APPROVAL_REQUESTER.set(requester)
-
-
-def reset_edit_approval_requester(token: Token) -> None:
-    """Restore a previous edit approval requester binding."""
-
-    _EDIT_APPROVAL_REQUESTER.reset(token)
-
-
-def clear_edit_approval_requester() -> None:
-    """Clear the current requester; primarily used by tests."""
-
-    _EDIT_APPROVAL_REQUESTER.set(None)
-
-
-def get_edit_approval_requester() -> EditApprovalRequester | None:
-    return _EDIT_APPROVAL_REQUESTER.get()
-
-
-def _read_text_if_exists(path: str) -> str | None:
-    p = Path(path).expanduser()
-    if not p.exists():
-        return None
-    if not p.is_file():
-        raise OSError(f"Cannot edit non-file path: {path}")
-    return p.read_text(encoding="utf-8", errors="replace")
-
-
-def _proposal_for_write_file(arguments: dict[str, Any]) -> EditProposal:
-    path = str(arguments.get("path") or "")
-    if not path:
-        raise ValueError("path required")
-    content = arguments.get("content")
-    if content is None:
-        raise ValueError("content required")
-    return EditProposal(
-        tool_name="write_file",
-        path=path,
-        old_text=_read_text_if_exists(path),
-        new_text=str(content),
-        arguments=dict(arguments),
-    )
-
-
-def _proposal_for_patch_replace(arguments: dict[str, Any]) -> EditProposal:
-    path = str(arguments.get("path") or "")
-    if not path:
-        raise ValueError("path required")
-    old_string = arguments.get("old_string")
-    new_string = arguments.get("new_string")
-    if old_string is None or new_string is None:
-        raise ValueError("old_string and new_string required")
-
-    old_text = _read_text_if_exists(path)
-    if old_text is None:
-        raise ValueError(f"Failed to read file: {path}")
-
-    from tools.fuzzy_match import fuzzy_find_and_replace
-
-    new_text, match_count, _strategy, error = fuzzy_find_and_replace(
-        old_text,
-        str(old_string),
-        str(new_string),
-        bool(arguments.get("replace_all", False)),
-    )
-    if error or match_count == 0:
-        raise ValueError(error or f"Could not find match for old_string in {path}")
-
-    return EditProposal(
-        tool_name="patch",
-        path=path,
-        old_text=old_text,
-        new_text=new_text,
-        arguments=dict(arguments),
-    )
-
-
-def _extract_v4a_patch_paths(patch_body: str) -> list[str]:
-    paths: list[str] = []
-    for match in re.finditer(
-        r'^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+)$',
-        patch_body,
-        re.MULTILINE,
-    ):
-        path = match.group(1).strip()
-        if path:
-            paths.append(path)
-    for match in re.finditer(
-        r'^\*\*\*\s+Move\s+File:\s*(.+?)\s*->\s*(.+)$',
-        patch_body,
-        re.MULTILINE,
-    ):
-        src = match.group(1).strip()
-        dst = match.group(2).strip()
-        if src:
-            paths.append(src)
-        if dst:
-            paths.append(dst)
-    return paths
-
-
-def _proposal_for_patch_v4a(arguments: dict[str, Any]) -> EditProposal:
-    patch_body = arguments.get("patch")
-    if not isinstance(patch_body, str) or not patch_body:
-        raise ValueError("patch content required")
-
-    paths = _extract_v4a_patch_paths(patch_body)
-    if not paths:
-        raise ValueError("no file paths found in V4A patch")
-
-    proposal_path = paths[0] if len(paths) == 1 else ", ".join(paths)
-    old_text = _read_text_if_exists(paths[0]) if len(paths) == 1 else None
-    return EditProposal(
-        tool_name="patch",
-        path=proposal_path,
-        old_text=old_text,
-        # ACP only supports a single diff payload here.  Surface the exact V4A
-        # patch content before execution so patch-mode calls are permissioned
-        # and denied patches cannot mutate.
-        new_text=patch_body,
-        arguments=dict(arguments),
-    )
-
-
-def build_edit_proposal(tool_name: str, arguments: dict[str, Any]) -> EditProposal | None:
-    """Return an edit proposal for supported file mutation calls."""
-
-    if tool_name == "write_file":
-        return _proposal_for_write_file(arguments)
-    if tool_name == "patch":
-        mode = arguments.get("mode", "replace")
-        if mode == "replace":
-            return _proposal_for_patch_replace(arguments)
-        if mode == "patch":
-            return _proposal_for_patch_v4a(arguments)
-    return None
-
-
-def _is_sensitive_auto_approve_path(path: str) -> bool:
-    parts = Path(path).expanduser().parts
-    lowered = {part.lower() for part in parts}
-    if ".git" in lowered or ".ssh" in lowered:
-        return True
-    return Path(path).name.lower() in SENSITIVE_AUTO_APPROVE_NAMES
-
-
-def should_auto_approve_edit(proposal: EditProposal, policy: str, cwd: str | None = None) -> bool:
-    """Return whether an ACP edit proposal may bypass the prompt for this session.
-
-    This is intentionally session-scoped and conservative: sensitive paths still
-    ask even under autonomous policies.
-    """
-
-    policy = str(policy or AUTO_APPROVE_ASK).strip()
-    if policy == AUTO_APPROVE_ASK or _is_sensitive_auto_approve_path(proposal.path):
-        return False
-    path = Path(proposal.path).expanduser().resolve(strict=False)
-    if policy == AUTO_APPROVE_SESSION:
-        return True
-    if policy == AUTO_APPROVE_WORKSPACE:
-        # `/tmp` is the POSIX path but tempfile.gettempdir() is the real one on
-        # every platform: `/private/tmp` on macOS (because `/tmp` is a symlink
-        # and Path.resolve() follows it) and the per-user Temp dir on Windows.
-        tmp_root = Path(tempfile.gettempdir()).resolve(strict=False)
-        try:
-            path.relative_to(tmp_root)
-            return True
-        except ValueError:
-            pass
-        if cwd:
-            root = Path(cwd).expanduser().resolve(strict=False)
-            try:
-                path.relative_to(root)
-                return True
-            except ValueError:
-                return False
-    return False
-
-
-def maybe_require_edit_approval(tool_name: str, arguments: dict[str, Any]) -> str | None:
-    """Run ACP edit approval if bound.
-
-    Returns a JSON tool-error string when the edit must be blocked, otherwise
-    ``None`` so dispatch can continue.  Requester exceptions deny by default.
-    """
-
-    requester = get_edit_approval_requester()
-    if requester is None:
-        return None
-
-    try:
-        proposal = build_edit_proposal(tool_name, arguments)
-    except Exception as exc:
-        logger.warning("Could not build ACP edit approval proposal for %s: %s", tool_name, exc)
-        return json.dumps({"error": f"Edit approval denied: could not prepare diff ({exc})"}, ensure_ascii=False)
-
-    if proposal is None:
-        return None
-
-    try:
-        approved = bool(requester(proposal))
-    except Exception as exc:
-        logger.warning("ACP edit approval requester failed: %s", exc)
-        approved = False
-
-    if approved:
-        return None
-    return json.dumps({"error": "Edit approval denied by ACP client; file was not modified."}, ensure_ascii=False)
-
-
-def build_acp_edit_tool_call(proposal: EditProposal):
-    """Build the ToolCallUpdate payload for ACP request_permission."""
-
-    import acp
-
-    tool_call_id = f"edit-approval-{next(_PERMISSION_REQUEST_IDS)}"
-    return acp.update_tool_call(
-        tool_call_id,
-        title=f"Approve edit: {proposal.path}",
-        kind="edit",
-        status="pending",
-        content=[
-            acp.tool_diff_content(
-                path=proposal.path,
-                old_text=proposal.old_text,
-                new_text=proposal.new_text,
-            )
-        ],
-        raw_input={"tool": proposal.tool_name, "arguments": proposal.arguments},
-    )
-
-
-def make_acp_edit_approval_requester(
-    request_permission_fn: Callable,
-    loop: asyncio.AbstractEventLoop,
-    session_id: str,
-    timeout: float = 60.0,
-    auto_approve_getter: Callable[[], tuple[str, str | None]] | None = None,
-) -> EditApprovalRequester:
-    """Return a sync requester that bridges edit proposals to ACP permissions."""
-
-    def _requester(proposal: EditProposal) -> bool:
-        from acp.schema import PermissionOption
-        from agent.async_utils import safe_schedule_threadsafe
-
-        if auto_approve_getter is not None:
-            try:
-                policy, cwd = auto_approve_getter()
-                if should_auto_approve_edit(proposal, policy, cwd):
-                    logger.info("Auto-approved ACP edit under policy %s: %s", policy, proposal.path)
-                    return True
-            except Exception:
-                logger.debug("ACP edit auto-approval policy check failed", exc_info=True)
-
-        options = [
-            PermissionOption(option_id="allow_once", kind="allow_once", name="Allow edit"),
-            PermissionOption(option_id="deny", kind="reject_once", name="Deny"),
-        ]
-        tool_call = build_acp_edit_tool_call(proposal)
-        coro = request_permission_fn(
-            session_id=session_id,
-            tool_call=tool_call,
-            options=options,
-        )
-        future = safe_schedule_threadsafe(
-            coro,
-            loop,
-            logger=logger,
-            log_message="Edit approval request: failed to schedule on loop",
-        )
-        if future is None:
-            return False
-        try:
-            response = future.result(timeout=timeout)
-        except (FutureTimeout, Exception) as exc:
-            future.cancel()
-            logger.warning("Edit approval request timed out or failed: %s", exc)
-            return False
-        outcome = getattr(response, "outcome", None)
-        return (
-            getattr(outcome, "outcome", None) == "selected"
-            and getattr(outcome, "option_id", None) == "allow_once"
-        )
-
-    return _requester
@@ -13,70 +13,14 @@ Usage::
    hermes-acp
 """

-# IMPORTANT: hermes_bootstrap must be the very first import — UTF-8 stdio
-# on Windows.  No-op on POSIX.  See hermes_bootstrap.py for full rationale.
-try:
-    import hermes_bootstrap  # noqa: F401
-except ModuleNotFoundError:
-    # Graceful fallback when hermes_bootstrap isn't registered in the venv
-    # yet — happens during partial ``hermes update`` where git-reset landed
-    # new code but ``uv pip install -e .`` didn't finish.  Missing bootstrap
-    # means UTF-8 stdio setup is skipped on Windows; POSIX is unaffected.
-    pass
-else:
-    # Stop a ``utils/``/``proxy/``/``ui/`` package in the launch directory from
-    # shadowing Hermes's own modules — ``hermes acp`` can be started from any
-    # cwd, including a project that has same-named packages on its path.
-    hermes_bootstrap.harden_import_path()
-
-import argparse
 import asyncio
 import logging
+import os
 import sys
 from pathlib import Path
 from hermes_constants import get_hermes_home


-# Methods clients send as periodic liveness probes. They are not part of the
-# ACP schema, so the acp router correctly returns JSON-RPC -32601 to the
-# caller — but the supervisor task that dispatches the request then surfaces
-# the raised RequestError via ``logging.exception("Background task failed")``,
-# which dumps a traceback to stderr every probe interval. Clients like
-# acp-bridge already treat the -32601 response as "agent alive", so the
-# traceback is pure noise. We keep the protocol response intact and only
-# silence the stderr noise for this specific benign case.
-_BENIGN_PROBE_METHODS = frozenset({"ping", "health", "healthcheck"})
-
-
-class _BenignProbeMethodFilter(logging.Filter):
-    """Suppress acp 'Background task failed' tracebacks caused by unknown
-    liveness-probe methods (e.g. ``ping``) while leaving every other
-    background-task error — including method_not_found for any non-probe
-    method — visible in stderr.
-    """
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if record.getMessage() != "Background task failed":
-            return True
-        exc_info = record.exc_info
-        if not exc_info:
-            return True
-        exc = exc_info[1]
-        # Imported lazily so this module stays importable when the optional
-        # ``agent-client-protocol`` dependency is not installed.
-        try:
-            from acp.exceptions import RequestError
-        except ImportError:
-            return True
-        if not isinstance(exc, RequestError):
-            return True
-        if getattr(exc, "code", None) != -32601:
-            return True
-        data = getattr(exc, "data", None)
-        method = data.get("method") if isinstance(data, dict) else None
-        return method not in _BENIGN_PROBE_METHODS
-
-
 def _setup_logging() -> None:
    """Route all logging to stderr so stdout stays clean for ACP stdio."""
    handler = logging.StreamHandler(sys.stderr)
@@ -86,7 +30,6 @@ def _setup_logging() -> None:
            datefmt="%Y-%m-%d %H:%M:%S",
        )
    )
-    handler.addFilter(_BenignProbeMethodFilter())
    root = logging.getLogger()
    root.handlers.clear()
    root.addHandler(handler)
@@ -113,125 +56,8 @@ def _load_env() -> None:
        )


-def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
-    parser = argparse.ArgumentParser(
-        prog="hermes-acp",
-        description="Run Hermes Agent as an ACP stdio server.",
-    )
-    parser.add_argument("--version", action="store_true", help="Print Hermes version and exit")
-    parser.add_argument(
-        "--check",
-        action="store_true",
-        help="Verify ACP dependencies and adapter imports, then exit",
-    )
-    parser.add_argument(
-        "--setup",
-        action="store_true",
-        help="Run interactive Hermes provider/model setup for ACP terminal auth",
-    )
-    parser.add_argument(
-        "--setup-browser",
-        action="store_true",
-        help="Install agent-browser + Playwright Chromium into ~/.hermes/node/ "
-             "for browser tool support. Idempotent.",
-    )
-    parser.add_argument(
-        "--yes",
-        "-y",
-        action="store_true",
-        dest="assume_yes",
-        help="Accept all prompts (currently used by --setup-browser to skip the "
-             "~400 MB Chromium download confirmation).",
-    )
-    return parser.parse_args(argv)
-
-
-def _print_version() -> None:
-    from hermes_cli import __version__ as hermes_version
-
-    print(hermes_version)
-
-
-def _run_check() -> None:
-    import acp  # noqa: F401
-    from acp_adapter.server import HermesACPAgent  # noqa: F401
-
-    print("Hermes ACP check OK")
-
-
-def _run_setup() -> None:
-    from hermes_cli.main import main as hermes_main
-
-    old_argv = sys.argv[:]
-    try:
-        sys.argv = [old_argv[0] if old_argv else "hermes", "model"]
-        hermes_main()
-    finally:
-        sys.argv = old_argv
-
-    # Offer browser-tools install as a follow-up. The terminal auth method
-    # is the one supported first-run UX for registry installs, so this is
-    # the natural moment to ask. Skip silently if stdin isn't a TTY (the
-    # answer can't be collected anyway).
-    if not sys.stdin.isatty():
-        return
-    try:
-        reply = input(
-            "\nInstall browser tools? Downloads agent-browser (npm) and "
-            "optionally Playwright Chromium (~400 MB). [y/N] "
-        ).strip().lower()
-    except (EOFError, KeyboardInterrupt):
-        return
-    if reply in {"y", "yes"}:
-        _run_setup_browser(assume_yes=False)
-
-
-def _run_setup_browser(assume_yes: bool = False) -> int:
-    """Bootstrap agent-browser + Chromium.
-
-    Routes through dep_ensure -> install.{sh,ps1} --ensure, sharing code
-    with ``hermes postinstall`` and the runtime lazy installer.
-
-    Returns 0 on success, 1 on failure.
-    """
-    from hermes_cli.dep_ensure import ensure_dependency
-
-    try:
-        node_ok = ensure_dependency("node", interactive=not assume_yes)
-        if not node_ok:
-            print("Node.js installation failed — cannot proceed with browser tools.",
-                  file=sys.stderr)
-            return 1
-
-        browser_ok = ensure_dependency("browser", interactive=not assume_yes)
-        if not browser_ok:
-            print("Browser tools installation failed.", file=sys.stderr)
-            return 1
-
-        return 0
-    except OSError as exc:
-        print(f"Browser bootstrap failed: {exc}", file=sys.stderr)
-        return 1
-
-
-def main(argv: list[str] | None = None) -> None:
+def main() -> None:
    """Entry point: load env, configure logging, run the ACP agent."""
-    args = _parse_args(argv)
-    if args.version:
-        _print_version()
-        return
-    if args.check:
-        _run_check()
-        return
-    if args.setup:
-        _run_setup()
-        return
-    if args.setup_browser:
-        rc = _run_setup_browser(assume_yes=args.assume_yes)
-        if rc != 0:
-            sys.exit(rc)
-        return
-
    _setup_logging()
    _load_env()

@@ -246,20 +72,9 @@ def main(argv: list[str] | None = None) -> None:
    import acp
    from .server import HermesACPAgent

-    # MCP tool discovery from config.yaml — run before asyncio.run() so
-    # it's safe to use blocking waits.  (ACP also registers per-session
-    # MCP servers dynamically via asyncio.to_thread inside the event
-    # loop; that path is unaffected.)  Moved from model_tools.py module
-    # scope to avoid freezing the gateway's loop on lazy import (#16856).
-    try:
-        from tools.mcp_tool import discover_mcp_tools
-        discover_mcp_tools()
-    except Exception:
-        logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
-
    agent = HermesACPAgent()
    try:
-        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
+        asyncio.run(acp.run_agent(agent))
    except KeyboardInterrupt:
        logger.info("Shutting down (KeyboardInterrupt)")
    except Exception:
@@ -14,7 +14,6 @@ from collections import deque
 from typing import Any, Callable, Deque, Dict

 import acp
-from acp.schema import AgentPlanUpdate, PlanEntry

 from .tools import (
    build_tool_complete,
@@ -25,65 +24,6 @@ from .tools import (
 logger = logging.getLogger(__name__)


-def _json_loads_maybe_prefix(value: str) -> Any:
-    """Parse a JSON object even when Hermes appended a human hint after it."""
-    text = value.strip()
-    try:
-        return json.loads(text)
-    except Exception:
-        decoder = json.JSONDecoder()
-        data, _ = decoder.raw_decode(text)
-        return data
-
-
-def _build_plan_update_from_todo_result(result: Any) -> AgentPlanUpdate | None:
-    """Translate Hermes' todo tool result into ACP's native plan update.
-
-    Zed renders ``sessionUpdate: plan`` as its first-class task/todo panel. The
-    Hermes agent already maintains task state through the ``todo`` tool, so the
-    ACP adapter should expose that state natively instead of only as a generic
-    tool-call transcript block.
-    """
-    if not isinstance(result, str) or not result.strip():
-        return None
-
-    try:
-        data = _json_loads_maybe_prefix(result)
-    except Exception:
-        return None
-
-    if not isinstance(data, dict) or not isinstance(data.get("todos"), list):
-        return None
-
-    todos = data["todos"]
-    if not todos:
-        return AgentPlanUpdate(session_update="plan", entries=[])
-
-    status_map = {
-        "pending": "pending",
-        "in_progress": "in_progress",
-        "completed": "completed",
-        # ACP plans only support pending/in_progress/completed. Preserve
-        # cancelled tasks as terminal entries instead of dropping them and
-        # making the client's full-list replacement lose visible context.
-        "cancelled": "completed",
-    }
-    entries: list[PlanEntry] = []
-    for item in todos:
-        if not isinstance(item, dict):
-            continue
-        content = str(item.get("content") or item.get("id") or "").strip()
-        if not content:
-            continue
-        raw_status = str(item.get("status") or "pending").strip()
-        status = status_map.get(raw_status, "pending")
-        if raw_status == "cancelled":
-            content = f"[cancelled] {content}"
-        entries.append(PlanEntry(content=content, priority="medium", status=status))
-
-    return AgentPlanUpdate(session_update="plan", entries=entries)
-
-
 def _send_update(
    conn: acp.Client,
    session_id: str,
@@ -91,17 +31,10 @@ def _send_update(
    update: Any,
 ) -> None:
    """Fire-and-forget an ACP session update from a worker thread."""
-    from agent.async_utils import safe_schedule_threadsafe
-
-    future = safe_schedule_threadsafe(
-        conn.session_update(session_id, update),
-        loop,
-        logger=logger,
-        log_message="Failed to send ACP update",
-    )
-    if future is None:
-        return
    try:
+        future = asyncio.run_coroutine_threadsafe(
+            conn.session_update(session_id, update), loop
+        )
        future.result(timeout=5)
    except Exception:
        logger.debug("Failed to send ACP update", exc_info=True)
@@ -116,25 +49,19 @@ def make_tool_progress_cb(
    session_id: str,
    loop: asyncio.AbstractEventLoop,
    tool_call_ids: Dict[str, Deque[str]],
-    tool_call_meta: Dict[str, Dict[str, Any]],
-    edit_approval_policy_getter: Callable[[], tuple[str, str | None]] | None = None,
 ) -> Callable:
    """Create a ``tool_progress_callback`` for AIAgent.

    Signature expected by AIAgent::

-        tool_progress_callback(event_type: str, name: str, preview: str, args: dict, **kwargs)
+        tool_progress_callback(name: str, preview: str, args: dict)

-    Emits ``ToolCallStart`` for ``tool.started`` events and tracks IDs in a FIFO
+    Emits ``ToolCallStart`` for each tool invocation and tracks IDs in a FIFO
    queue per tool name so duplicate/parallel same-name calls still complete
-    against the correct ACP tool call.  Other event types (``tool.completed``,
-    ``reasoning.available``) are silently ignored.
+    against the correct ACP tool call.
    """

-    def _tool_progress(event_type: str, name: str = None, preview: str = None, args: Any = None, **kwargs) -> None:
-        # Only emit ACP ToolCallStart for tool.started; ignore other event types
-        if event_type != "tool.started":
-            return
+    def _tool_progress(name: str, preview: str, args: Any = None) -> None:
        if isinstance(args, str):
            try:
                args = json.loads(args)
@@ -153,30 +80,7 @@ def make_tool_progress_cb(
            tool_call_ids[name] = queue
        queue.append(tc_id)

-        snapshot = None
-        if name in {"write_file", "patch", "skill_manage"}:
-            try:
-                from agent.display import capture_local_edit_snapshot
-
-                snapshot = capture_local_edit_snapshot(name, args)
-            except Exception:
-                logger.debug("Failed to capture ACP edit snapshot for %s", name, exc_info=True)
-        tool_call_meta[tc_id] = {"args": args, "snapshot": snapshot}
-
-        edit_diff = None
-        if name in {"write_file", "patch"} and edit_approval_policy_getter is not None:
-            try:
-                from acp_adapter.edit_approval import build_edit_proposal, should_auto_approve_edit
-
-                proposal = build_edit_proposal(name, args)
-                if proposal is not None:
-                    policy, cwd = edit_approval_policy_getter()
-                    if should_auto_approve_edit(proposal, policy, cwd):
-                        edit_diff = proposal
-            except Exception:
-                logger.debug("Failed to prepare auto-approved ACP edit diff for %s", name, exc_info=True)
-
-        update = build_tool_start(tc_id, name, args, edit_diff=edit_diff)
+        update = build_tool_start(tc_id, name, args)
        _send_update(conn, session_id, loop, update)

    return _tool_progress
@@ -211,7 +115,6 @@ def make_step_cb(
    session_id: str,
    loop: asyncio.AbstractEventLoop,
    tool_call_ids: Dict[str, Deque[str]],
-    tool_call_meta: Dict[str, Dict[str, Any]],
 ) -> Callable:
    """Create a ``step_callback`` for AIAgent.

@@ -225,12 +128,10 @@ def make_step_cb(
            for tool_info in prev_tools:
                tool_name = None
                result = None
-                function_args = None

                if isinstance(tool_info, dict):
                    tool_name = tool_info.get("name") or tool_info.get("function_name")
                    result = tool_info.get("result") or tool_info.get("output")
-                    function_args = tool_info.get("arguments") or tool_info.get("args")
                elif isinstance(tool_info, str):
                    tool_name = tool_info

@@ -240,19 +141,10 @@ def make_step_cb(
                    tool_call_ids[tool_name] = queue
                if tool_name and queue:
                    tc_id = queue.popleft()
-                    meta = tool_call_meta.pop(tc_id, {})
                    update = build_tool_complete(
-                        tc_id,
-                        tool_name,
-                        result=str(result) if result is not None else None,
-                        function_args=function_args or meta.get("args"),
-                        snapshot=meta.get("snapshot"),
+                        tc_id, tool_name, result=str(result) if result is not None else None
                    )
                    _send_update(conn, session_id, loop, update)
-                    if tool_name == "todo":
-                        plan_update = _build_plan_update_from_todo_result(result)
-                        if plan_update is not None:
-                            _send_update(conn, session_id, loop, plan_update)
                    if not queue:
                        tool_call_ids.pop(tool_name, None)

@@ -1,11 +1,10 @@
-"""ACP permission bridging for Hermes dangerous-command approvals."""
+"""ACP permission bridging — maps ACP approval requests to hermes approval callbacks."""

 from __future__ import annotations

 import asyncio
 import logging
 from concurrent.futures import TimeoutError as FutureTimeout
-from itertools import count
 from typing import Callable

 from acp.schema import (
@@ -15,110 +14,24 @@ from acp.schema import (

 logger = logging.getLogger(__name__)

-# Maps ACP permission option ids to Hermes approval result strings.
-# Option ids are stable across both the ``allow_permanent=True`` and
-# ``allow_permanent=False`` paths even though the option list differs.
-_OPTION_ID_TO_HERMES = {
+# Maps ACP PermissionOptionKind -> hermes approval result strings
+_KIND_TO_HERMES = {
    "allow_once": "once",
-    "allow_session": "session",
    "allow_always": "always",
-    "deny": "deny",
-    "deny_always": "deny",
+    "reject_once": "deny",
+    "reject_always": "deny",
 }

-_PERMISSION_REQUEST_IDS = count(1)
-
-
-def _permission_option_supports_kind(kind: str) -> bool:
-    """Return whether the installed ACP SDK accepts a permission option kind."""
-    try:
-        PermissionOption(option_id="__probe__", kind=kind, name="probe")
-    except Exception:
-        return False
-    return True
-
-
-def _build_permission_options(
-    *, allow_permanent: bool, smart_denied: bool = False,
-) -> list[PermissionOption]:
-    """Return ACP options that match Hermes approval semantics."""
-    options = [PermissionOption(
-        option_id="allow_once", kind="allow_once", name="Allow once",
-    )]
-    if not smart_denied:
-        options.append(PermissionOption(
-            option_id="allow_session",
-            # ACP has no session-scoped kind, so use the closest persistent
-            # hint while keeping Hermes semantics in the option id.
-            kind="allow_always",
-            name="Allow for session",
-        ))
-    if allow_permanent and not smart_denied:
-        options.append(
-            PermissionOption(
-                option_id="allow_always",
-                kind="allow_always",
-                name="Allow always",
-            ),
-        )
-    options.append(PermissionOption(option_id="deny", kind="reject_once", name="Deny"))
-    if not smart_denied and _permission_option_supports_kind("reject_always"):
-        options.append(
-            PermissionOption(
-                option_id="deny_always",
-                kind="reject_always",
-                name="Deny always",
-            ),
-        )
-    return options
-
-
-def _build_permission_tool_call(command: str, description: str):
-    """Return the ACP tool-call update attached to a permission request.
-
-    ``request_permission`` expects a ``ToolCallUpdate`` payload — produced
-    by ``_acp.update_tool_call`` — not a ``ToolCallStart``. Each request
-    gets a unique ``perm-check-N`` id so concurrent requests don't collide.
-    """
-    import acp as _acp
-
-    tool_call_id = f"perm-check-{next(_PERMISSION_REQUEST_IDS)}"
-    title = f"{description}: {command}" if description else command
-    content_text = f"{description}\n$ {command}" if description else f"$ {command}"
-    return _acp.update_tool_call(
-        tool_call_id,
-        title=title,
-        kind="execute",
-        status="pending",
-        content=[_acp.tool_content(_acp.text_block(content_text))],
-        raw_input={"command": command, "description": description},
-    )
-
-
-def _map_outcome_to_hermes(outcome: object, *, allowed_option_ids: set[str]) -> str:
-    """Map an ACP permission outcome into Hermes approval strings."""
-    if not isinstance(outcome, AllowedOutcome):
-        return "deny"
-
-    option_id = outcome.option_id
-    if option_id not in allowed_option_ids:
-        logger.warning("Permission request returned unknown option_id: %s", option_id)
-        return "deny"
-    return _OPTION_ID_TO_HERMES.get(option_id, "deny")
-

 def make_approval_callback(
    request_permission_fn: Callable,
    loop: asyncio.AbstractEventLoop,
    session_id: str,
    timeout: float = 60.0,
-) -> Callable[..., str]:
+) -> Callable[[str, str], str]:
    """
-    Return a Hermes-compatible approval callback that bridges to ACP.
-
-    The callback accepts ``command`` and ``description`` plus optional
-    keyword arguments such as ``allow_permanent`` used by
-    ``tools.approval.prompt_dangerous_approval()``.
+    Return a hermes-compatible ``approval_callback(command, description) -> str``
+    that bridges to the ACP client's ``request_permission`` call.

    Args:
        request_permission_fn: The ACP connection's ``request_permission`` coroutine.
@@ -127,49 +40,38 @@ def make_approval_callback(
        timeout: Seconds to wait for a response before auto-denying.
    """

-    def _callback(
-        command: str,
-        description: str,
-        *,
-        allow_permanent: bool = True,
-        smart_denied: bool = False,
-        **_: object,
-    ) -> str:
-        from agent.async_utils import safe_schedule_threadsafe
+    def _callback(command: str, description: str) -> str:
+        options = [
+            PermissionOption(option_id="allow_once", kind="allow_once", name="Allow once"),
+            PermissionOption(option_id="allow_always", kind="allow_always", name="Allow always"),
+            PermissionOption(option_id="deny", kind="reject_once", name="Deny"),
+        ]
+        import acp as _acp

-        options = _build_permission_options(
-            allow_permanent=allow_permanent,
-            smart_denied=smart_denied,
-        )
+        tool_call = _acp.start_tool_call("perm-check", command, kind="execute")

-        tool_call = _build_permission_tool_call(command, description)
        coro = request_permission_fn(
            session_id=session_id,
            tool_call=tool_call,
            options=options,
        )
-        future = safe_schedule_threadsafe(
-            coro, loop,
-            logger=logger,
-            log_message="Permission request: failed to schedule on loop",
-        )
-        if future is None:
-            return "deny"

        try:
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
            response = future.result(timeout=timeout)
        except (FutureTimeout, Exception) as exc:
-            future.cancel()
            logger.warning("Permission request timed out or failed: %s", exc)
            return "deny"

-        if response is None:
+        outcome = response.outcome
+        if isinstance(outcome, AllowedOutcome):
+            option_id = outcome.option_id
+            # Look up the kind from our options list
+            for opt in options:
+                if opt.option_id == option_id:
+                    return _KIND_TO_HERMES.get(opt.kind, "deny")
+            return "once"  # fallback for unknown option_id
+        else:
            return "deny"

-        allowed_option_ids = {option.option_id for option in options}
-        return _map_outcome_to_hermes(
-            response.outcome,
-            allowed_option_ids=allowed_option_ids,
-        )
-
    return _callback
@@ -1,127 +0,0 @@
-"""Derive ACP session-provenance metadata from the existing compression chain.
-
-This is an additive Hermes extension surfaced under ACP ``_meta.hermes`` so
-existing ACP clients ignore it. It carries no new persisted state: everything
-is derived on demand from the ``sessions`` table (``parent_session_id`` /
-``end_reason``), which already models compression-continuation chains.
-
-The ACP/editor ``session_id`` stays the stable public handle. When context
-compression rotates the internal Hermes head, ``build_session_provenance`` lets
-a client see the previous/current internal ids and the lineage root without
-parsing status text, guessing from token drops, or reading ``state.db``.
-"""
-
-from __future__ import annotations
-
-from typing import Any, Dict, Optional
-
-# Bound defensive walks; compression chains this deep are pathological.
-_MAX_WALK = 100
-
-
-def build_session_provenance(
-    db: Any,
-    acp_session_id: str,
-    current_hermes_session_id: str,
-    *,
-    previous_hermes_session_id: Optional[str] = None,
-) -> Optional[Dict[str, Any]]:
-    """Build ``_meta.hermes.sessionProvenance`` for an ACP session.
-
-    Args:
-        db: A ``SessionDB`` (must expose ``get_session``).
-        acp_session_id: The stable ACP/editor-facing session handle.
-        current_hermes_session_id: The live internal Hermes DB session id
-            (``state.agent.session_id``).
-        previous_hermes_session_id: The internal id from before the most recent
-            turn, when known. Supplied by ``prompt()`` to flag a rotation.
-
-    Returns:
-        A dict suitable for ``{"hermes": {"sessionProvenance": <dict>}}`` under
-        ACP ``_meta``, or ``None`` if the session can't be read.
-    """
-    try:
-        row = db.get_session(current_hermes_session_id)
-    except Exception:
-        return None
-    if not row:
-        return None
-
-    parent_id = row.get("parent_session_id")
-    end_reason = row.get("end_reason")
-
-    # Walk parents to the lineage root and count compression depth. Only
-    # compression-split parents (parent.end_reason == 'compression') count
-    # toward depth — delegate/branch children share the parent_session_id
-    # column but are not compaction boundaries.
-    root_id = current_hermes_session_id
-    compression_depth = 0
-    cursor_parent = parent_id
-    seen = {current_hermes_session_id}
-    for _ in range(_MAX_WALK):
-        if not cursor_parent or cursor_parent in seen:
-            break
-        seen.add(cursor_parent)
-        try:
-            prow = db.get_session(cursor_parent)
-        except Exception:
-            prow = None
-        if not prow:
-            break
-        root_id = cursor_parent
-        if prow.get("end_reason") == "compression":
-            compression_depth += 1
-        cursor_parent = prow.get("parent_session_id")
-
-    # A session is a compression continuation when its parent was ended with
-    # end_reason='compression'. Determine that from the immediate parent.
-    is_continuation = False
-    if parent_id:
-        try:
-            immediate_parent = db.get_session(parent_id)
-        except Exception:
-            immediate_parent = None
-        if immediate_parent and immediate_parent.get("end_reason") == "compression":
-            is_continuation = True
-
-    rotated = bool(
-        previous_hermes_session_id
-        and previous_hermes_session_id != current_hermes_session_id
-    )
-
-    provenance: Dict[str, Any] = {
-        "acpSessionId": acp_session_id,
-        "currentHermesSessionId": current_hermes_session_id,
-        "rootHermesSessionId": root_id,
-        "parentHermesSessionId": parent_id,
-        "sessionKind": "continuation" if is_continuation else "root",
-        "compressionDepth": compression_depth,
-    }
-    if previous_hermes_session_id:
-        provenance["previousHermesSessionId"] = previous_hermes_session_id
-    if rotated:
-        # The head moved during the last turn. The only mechanism that rotates
-        # the internal id mid-turn is compression-driven session splitting.
-        provenance["reason"] = "compression"
-        provenance["creatorKind"] = "compression"
-
-    return provenance
-
-
-def session_provenance_meta(
-    db: Any,
-    acp_session_id: str,
-    current_hermes_session_id: str,
-    *,
-    previous_hermes_session_id: Optional[str] = None,
-) -> Optional[Dict[str, Any]]:
-    """Return a ready ``_meta`` payload: ``{"hermes": {"sessionProvenance": ...}}``."""
-    prov = build_session_provenance(
-        db,
-        acp_session_id,
-        current_hermes_session_id,
-        previous_hermes_session_id=previous_hermes_session_id,
-    )
-    if prov is None:
-        return None
-    return {"hermes": {"sessionProvenance": prov}}
@@ -13,12 +13,7 @@ from hermes_constants import get_hermes_home
 import copy
 import json
 import logging
-import os
-import re
-import sys
-import time
 import uuid
-from datetime import datetime, timezone
 from dataclasses import dataclass, field
 from threading import Lock
 from typing import Any, Dict, List, Optional
@@ -26,124 +21,17 @@ from typing import Any, Dict, List, Optional
 logger = logging.getLogger(__name__)


-def _translate_acp_cwd(cwd: str) -> str:
-    """Translate Windows ACP cwd values when Hermes itself is running in WSL.
-
-    Windows ACP clients can launch ``hermes acp`` inside WSL while still sending
-    editor workspaces as Windows drive paths (``E:\\Projects``) or
-    ``\\\\wsl.localhost\\`` UNC paths. Store and execute against the POSIX form so
-    agents, tools, and persisted ACP sessions all agree on the usable workspace.
-    Native Linux/macOS keeps the original cwd unchanged.
-    """
-    from hermes_constants import translate_cwd_for_wsl_backend
-
-    return translate_cwd_for_wsl_backend(str(cwd))
-
-
-def _normalize_cwd_for_compare(cwd: str | None) -> str:
-    raw = str(cwd or ".").strip()
-    if not raw:
-        raw = "."
-    expanded = os.path.expanduser(raw)
-
-    # Normalize Windows drive paths into the equivalent WSL mount form so
-    # ACP history filters match the same workspace across Windows and WSL.
-    from hermes_constants import windows_path_to_wsl
-
-    translated = windows_path_to_wsl(expanded)
-    if translated is not None:
-        expanded = translated
-    elif re.match(r"^/mnt/[A-Za-z]/", expanded):
-        expanded = f"/mnt/{expanded[5].lower()}/{expanded[7:]}"
-
-    return os.path.normpath(expanded)
-
-
-def _build_session_title(title: Any, preview: Any, cwd: str | None) -> str:
-    explicit = str(title or "").strip()
-    if explicit:
-        return explicit
-    preview_text = str(preview or "").strip()
-    if preview_text:
-        return preview_text
-    leaf = os.path.basename(str(cwd or "").rstrip("/\\"))
-    return leaf or "New thread"
-
-
-def _format_updated_at(value: Any) -> str | None:
-    if value is None:
-        return None
-    if isinstance(value, str) and value.strip():
-        return value
-    try:
-        return datetime.fromtimestamp(float(value), tz=timezone.utc).isoformat()
-    except Exception:
-        return None
-
-
-def _updated_at_sort_key(value: Any) -> float:
-    if value is None:
-        return float("-inf")
-    if isinstance(value, (int, float)):
-        return float(value)
-    raw = str(value).strip()
-    if not raw:
-        return float("-inf")
-    try:
-        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
-    except Exception:
-        try:
-            return float(raw)
-        except Exception:
-            return float("-inf")
-
-
-def _acp_stderr_print(*args, **kwargs) -> None:
-    """Best-effort human-readable output sink for ACP stdio sessions.
-
-    ACP reserves stdout for JSON-RPC frames, so any incidental CLI/status output
-    from AIAgent must be redirected away from stdout. Route it to stderr instead.
-    """
-    kwargs = dict(kwargs)
-    kwargs.setdefault("file", sys.stderr)
-    print(*args, **kwargs)
-
-
 def _register_task_cwd(task_id: str, cwd: str) -> None:
-    """Bind a task/session id to the editor's working directory for tools.
-
-    Zed can launch Hermes from a Windows workspace while the ACP process runs
-    inside WSL. In that case ACP sends cwd as e.g. ``E:\\Projects\\POTI``;
-    local tools need the WSL mount equivalent or subprocess creation fails
-    before the command can run.
-    """
+    """Bind a task/session id to the editor's working directory for tools."""
    if not task_id:
        return
    try:
        from tools.terminal_tool import register_task_env_overrides
-        register_task_env_overrides(task_id, {"cwd": _translate_acp_cwd(cwd)})
+        register_task_env_overrides(task_id, {"cwd": cwd})
    except Exception:
        logger.debug("Failed to register ACP task cwd override", exc_info=True)


-def _expand_acp_enabled_toolsets(
-    toolsets: List[str] | None = None,
-    mcp_server_names: List[str] | None = None,
-) -> List[str]:
-    """Return ACP toolsets plus explicit MCP server toolsets for this session."""
-    expanded: List[str] = []
-    for name in list(toolsets or ["hermes-acp"]):
-        if name and name not in expanded:
-            expanded.append(name)
-
-    for server_name in list(mcp_server_names or []):
-        toolset_name = f"mcp-{server_name}"
-        if server_name and toolset_name not in expanded:
-            expanded.append(toolset_name)
-
-    return expanded
-
-
 def _clear_task_cwd(task_id: str) -> None:
    """Remove task-specific cwd overrides for an ACP session."""
    if not task_id:
@@ -165,11 +53,6 @@ class SessionState:
    model: str = ""
    history: List[Dict[str, Any]] = field(default_factory=list)
    cancel_event: Any = None  # threading.Event
-    is_running: bool = False
-    queued_prompts: List[str] = field(default_factory=list)
-    runtime_lock: Any = field(default_factory=Lock)
-    current_prompt_text: str = ""
-    interrupted_prompt_text: str = ""


 class SessionManager:
@@ -200,7 +83,6 @@ class SessionManager:
        """Create a new session with a unique ID and a fresh AIAgent."""
        import threading

-        cwd = _translate_acp_cwd(cwd)
        session_id = str(uuid.uuid4())
        agent = self._make_agent(session_id=session_id, cwd=cwd)
        state = SessionState(
@@ -243,7 +125,6 @@ class SessionManager:
        """Deep-copy a session's history into a new session."""
        import threading

-        cwd = _translate_acp_cwd(cwd)
        original = self.get_session(session_id)  # checks DB too
        if original is None:
            return None
@@ -269,83 +150,51 @@ class SessionManager:
        logger.info("Forked ACP session %s -> %s", session_id, new_id)
        return state

-    def list_sessions(self, cwd: str | None = None) -> List[Dict[str, Any]]:
+    def list_sessions(self) -> List[Dict[str, Any]]:
        """Return lightweight info dicts for all sessions (memory + database)."""
-        normalized_cwd = _normalize_cwd_for_compare(cwd) if cwd else None
-        db = self._get_db()
-        persisted_rows: dict[str, dict[str, Any]] = {}
-
-        if db is not None:
-            try:
-                for row in db.list_sessions_rich(source="acp", limit=1000):
-                    persisted_rows[str(row["id"])] = dict(row)
-            except Exception:
-                logger.debug("Failed to load ACP sessions from DB", exc_info=True)
-
        # Collect in-memory sessions first.
        with self._lock:
            seen_ids = set(self._sessions.keys())
-            results = []
-            for s in self._sessions.values():
-                history_len = len(s.history)
-                if history_len <= 0:
-                    continue
-                if normalized_cwd and _normalize_cwd_for_compare(s.cwd) != normalized_cwd:
-                    continue
-                persisted = persisted_rows.get(s.session_id, {})
-                preview = next(
-                    (
-                        str(msg.get("content") or "").strip()
-                        for msg in s.history
-                        if msg.get("role") == "user" and str(msg.get("content") or "").strip()
-                    ),
-                    persisted.get("preview") or "",
-                )
-                results.append(
-                    {
-                        "session_id": s.session_id,
-                        "cwd": s.cwd,
-                        "model": s.model,
-                        "history_len": history_len,
-                        "title": _build_session_title(persisted.get("title"), preview, s.cwd),
-                        "updated_at": _format_updated_at(
-                            persisted.get("last_active") or persisted.get("started_at") or time.time()
-                        ),
-                    }
-                )
+            results = [
+                {
+                    "session_id": s.session_id,
+                    "cwd": s.cwd,
+                    "model": s.model,
+                    "history_len": len(s.history),
+                }
+                for s in self._sessions.values()
+            ]

        # Merge any persisted sessions not currently in memory.
-        for sid, row in persisted_rows.items():
-            if sid in seen_ids:
-                continue
-            message_count = int(row.get("message_count") or 0)
-            if message_count <= 0:
-                continue
-            # Extract cwd from model_config JSON.
-            session_cwd = "."
-            mc = row.get("model_config")
-            if mc:
-                try:
-                    session_cwd = json.loads(mc).get("cwd", ".")
-                except (json.JSONDecodeError, TypeError):
-                    pass
-            if normalized_cwd and _normalize_cwd_for_compare(session_cwd) != normalized_cwd:
-                continue
-            results.append({
-                "session_id": sid,
-                "cwd": session_cwd,
-                "model": row.get("model") or "",
-                "history_len": message_count,
-                "title": _build_session_title(row.get("title"), row.get("preview"), session_cwd),
-                "updated_at": _format_updated_at(row.get("last_active") or row.get("started_at")),
-            })
+        db = self._get_db()
+        if db is not None:
+            try:
+                rows = db.search_sessions(source="acp", limit=1000)
+                for row in rows:
+                    sid = row["id"]
+                    if sid in seen_ids:
+                        continue
+                    # Extract cwd from model_config JSON.
+                    cwd = "."
+                    mc = row.get("model_config")
+                    if mc:
+                        try:
+                            cwd = json.loads(mc).get("cwd", ".")
+                        except (json.JSONDecodeError, TypeError):
+                            pass
+                    results.append({
+                        "session_id": sid,
+                        "cwd": cwd,
+                        "model": row.get("model") or "",
+                        "history_len": row.get("message_count") or 0,
+                    })
+            except Exception:
+                logger.debug("Failed to list ACP sessions from DB", exc_info=True)

-        results.sort(key=lambda item: _updated_at_sort_key(item.get("updated_at")), reverse=True)
        return results

    def update_cwd(self, session_id: str, cwd: str) -> Optional[SessionState]:
        """Update the working directory for a session and its tool overrides."""
-        cwd = _translate_acp_cwd(cwd)
        state = self.get_session(session_id)  # checks DB too
        if state is None:
            return None
@@ -401,6 +250,8 @@ class SessionManager:
        if self._db_instance is not None:
            return self._db_instance
        try:
+            import os
+            from pathlib import Path
            from hermes_state import SessionDB
            hermes_home = get_hermes_home()
            self._db_instance = SessionDB(db_path=hermes_home / "state.db")
@@ -446,50 +297,25 @@ class SessionManager:
            else:
                # Update model_config (contains cwd) if changed.
                try:
-                    db.update_session_meta(state.session_id, cwd_json, model_str)
+                    with db._lock:
+                        db._conn.execute(
+                            "UPDATE sessions SET model_config = ?, model = COALESCE(?, model) WHERE id = ?",
+                            (cwd_json, model_str, state.session_id),
+                        )
+                        db._conn.commit()
                except Exception:
                    logger.debug("Failed to update ACP session metadata", exc_info=True)

-            # When the agent owns persistence to this same SessionDB it has
-            # already flushed the live transcript incrementally during
-            # run_conversation (append_message), and it preserves pre-compaction
-            # turns non-destructively via archive_and_compact() — keeping them on
-            # disk as searchable active=0/compacted=1 rows. Calling
-            # replace_messages() here would then be a redundant double-write that
-            # DELETEs exactly those archived rows (and, after a compression-driven
-            # id rotation where agent.session_id no longer equals
-            # state.session_id, clobbers the ended parent transcript) — silent
-            # data loss for any ACP conversation long enough to compress.
-            #
-            # Only fall back to the destructive atomic replace when the agent is
-            # NOT persisting itself to this DB (e.g. a test agent factory, or a
-            # fresh create/fork whose copied history the agent has not flushed
-            # yet). That path still rolls back on a mid-rewrite failure so the
-            # previously persisted conversation survives (salvaged from #13675).
-            agent = state.agent
-            agent_db = getattr(agent, "_session_db", None)
-            agent_owns_persistence = (
-                agent_db is not None
-                and agent_db is db
-                and bool(getattr(agent, "_session_db_created", False))
-            )
-            if not agent_owns_persistence:
-                # Even when the current agent doesn't "own" persistence, the
-                # session on disk may already carry compaction-archived rows —
-                # e.g. after a model switch or a /restore, both of which mint a
-                # fresh agent with _session_db_created=False (so the check above
-                # is False) yet leave the durable archived transcript in place.
-                # A full-history replace would DELETE those archived rows just
-                # like the owned-agent case. Guard against it: when archived
-                # rows exist, replace ONLY the live (active=1) set and leave the
-                # archived turns untouched; otherwise the destructive replace is
-                # safe (fresh create/fork with no archived history to lose).
-                try:
-                    has_archived = db.has_archived_messages(state.session_id)
-                except Exception:
-                    has_archived = False
-                db.replace_messages(
-                    state.session_id, state.history, active_only=has_archived
+            # Replace stored messages with current history.
+            db.clear_messages(state.session_id)
+            for msg in state.history:
+                db.append_message(
+                    session_id=state.session_id,
+                    role=msg.get("role", "user"),
+                    content=msg.get("content"),
+                    tool_name=msg.get("tool_name") or msg.get("name"),
+                    tool_calls=msg.get("tool_calls"),
+                    tool_call_id=msg.get("tool_call_id"),
                )
        except Exception:
            logger.warning("Failed to persist ACP session %s", state.session_id, exc_info=True)
@@ -534,15 +360,9 @@ class SessionManager:

        model = row.get("model") or None

-        # Load conversation history. repair_alternation: this restore feeds
-        # LIVE REPLAY — the loaded list becomes the resumed agent's working
-        # conversation. A durable ``user;user`` violation left in state.db would
-        # otherwise re-fire the pre-request defensive repair on every request
-        # for the rest of the session (see hermes_state.get_messages_as_conversation).
+        # Load conversation history.
        try:
-            history = db.get_messages_as_conversation(
-                session_id, repair_alternation=True
-            )
+            history = db.get_messages_as_conversation(session_id)
        except Exception:
            logger.warning("Failed to load messages for ACP session %s", session_id, exc_info=True)
            history = []
@@ -606,7 +426,7 @@ class SessionManager:

        config = load_config()
        model_cfg = config.get("model")
-        default_model = ""
+        default_model = "anthropic/claude-opus-4.6"
        config_provider = None
        if isinstance(model_cfg, dict):
            default_model = str(model_cfg.get("default") or default_model)
@@ -614,21 +434,11 @@ class SessionManager:
        elif isinstance(model_cfg, str) and model_cfg.strip():
            default_model = model_cfg.strip()

-        configured_mcp_servers = [
-            name
-            for name, cfg in (config.get("mcp_servers") or {}).items()
-            if not isinstance(cfg, dict) or cfg.get("enabled", True) is not False
-        ]
-
        kwargs = {
            "platform": "acp",
-            "enabled_toolsets": _expand_acp_enabled_toolsets(
-                ["hermes-acp"],
-                mcp_server_names=configured_mcp_servers,
-            ),
+            "enabled_toolsets": ["hermes-acp"],
            "quiet_mode": True,
            "session_id": session_id,
-            "session_db": self._get_db(),
            "model": model or default_model,
        }

@@ -648,12 +458,4 @@ class SessionManager:
            logger.debug("ACP session falling back to default provider resolution", exc_info=True)

        _register_task_cwd(session_id, cwd)
-        agent = AIAgent(**kwargs)
-        # Codex app-server sessions are spawned lazily on the first turn. Stamp
-        # the ACP workspace onto the agent so the Codex runtime starts from the
-        # editor/session cwd instead of the Hermes daemon's process cwd.
-        agent.session_cwd = cwd
-        # ACP stdio transport requires stdout to remain protocol-only JSON-RPC.
-        # Route any incidental human-readable agent output to stderr instead.
-        agent._print_fn = _acp_stderr_print
-        return agent
+        return AIAgent(**kwargs)
@@ -1,16 +1,12 @@
 {
-  "id": "hermes-agent",
-  "name": "Hermes Agent",
-  "version": "0.19.0",
-  "description": "Self-improving open-source AI agent by Nous Research with ACP editor integration, persistent memory, skills, and rich tool support.",
-  "repository": "https://github.com/NousResearch/hermes-agent",
-  "website": "https://hermes-agent.nousresearch.com/docs/user-guide/features/acp",
-  "authors": ["Nous Research"],
-  "license": "MIT",
+  "schema_version": 1,
+  "name": "hermes-agent",
+  "display_name": "Hermes Agent",
+  "description": "AI agent by Nous Research with 90+ tools, persistent memory, and multi-platform support",
+  "icon": "icon.svg",
  "distribution": {
-    "uvx": {
-      "package": "hermes-agent[acp]==0.19.0",
-      "args": ["hermes-acp"]
-    }
+    "type": "command",
+    "command": "hermes",
+    "args": ["acp"]
  }
 }
@@ -1,8 +1,25 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16" fill="none">
-  <path d="M8 1.5v13" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
-  <path d="M8 3.25c-2.35-1.4-4.7-.95-6.25.35 1.85-.2 3.8.2 5.55 1.55" stroke="currentColor" stroke-width="1.1" stroke-linecap="round" stroke-linejoin="round"/>
-  <path d="M8 3.25c2.35-1.4 4.7-.95 6.25.35-1.85-.2-3.8.2-5.55 1.55" stroke="currentColor" stroke-width="1.1" stroke-linecap="round" stroke-linejoin="round"/>
-  <path d="M8 13.25c-2.3-1-3.05-2.65-1.35-4.15-2 .8-2.35 2.95-.35 4" stroke="currentColor" stroke-width="1.1" stroke-linecap="round" stroke-linejoin="round"/>
-  <path d="M8 13.25c2.3-1 3.05-2.65 1.35-4.15 2 .8 2.35 2.95.35 4" stroke="currentColor" stroke-width="1.1" stroke-linecap="round" stroke-linejoin="round"/>
-  <circle cx="8" cy="1.8" r="1.1" fill="currentColor"/>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="gold" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#F5C542;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#D4961C;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  <!-- Staff -->
+  <rect x="30" y="10" width="4" height="46" rx="2" fill="url(#gold)" />
+  <!-- Wings (left) -->
+  <path d="M30 18 C24 14, 14 14, 10 18 C14 16, 22 16, 28 20" fill="#F5C542" opacity="0.9" />
+  <path d="M30 22 C26 19, 18 19, 14 22 C18 20, 24 20, 28 24" fill="#D4961C" opacity="0.8" />
+  <!-- Wings (right) -->
+  <path d="M34 18 C40 14, 50 14, 54 18 C50 16, 42 16, 36 20" fill="#F5C542" opacity="0.9" />
+  <path d="M34 22 C38 19, 46 19, 50 22 C46 20, 40 20, 36 24" fill="#D4961C" opacity="0.8" />
+  <!-- Left serpent -->
+  <path d="M32 48 C22 44, 20 38, 26 34 C20 36, 18 42, 24 46 C18 40, 22 30, 30 28 C24 32, 22 38, 28 42"
+        fill="none" stroke="#F5C542" stroke-width="2.5" stroke-linecap="round" />
+  <!-- Right serpent -->
+  <path d="M32 48 C42 44, 44 38, 38 34 C44 36, 46 42, 40 46 C46 40, 42 30, 34 28 C40 32, 42 38, 36 42"
+        fill="none" stroke="#D4961C" stroke-width="2.5" stroke-linecap="round" />
+  <!-- Orb at top -->
+  <circle cx="32" cy="10" r="4" fill="#F5C542" />
+  <circle cx="32" cy="10" r="2" fill="#FFF8E1" opacity="0.7" />
 </svg>
@@ -4,5 +4,3 @@ These modules contain pure utility functions and self-contained classes
 that were previously embedded in the 3,600-line run_agent.py. Extracting
 them makes run_agent.py focused on the AIAgent orchestrator class.
 """
-
-from . import jiter_preload as _jiter_preload  # noqa: F401
@@ -1,890 +0,0 @@
-from __future__ import annotations
-
-import logging
-import math
-from dataclasses import dataclass
-from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any, Optional
-
-import httpx
-
-from agent.anthropic_adapter import _is_oauth_token, resolve_anthropic_token
-from hermes_cli.auth import AuthError, _read_codex_tokens, resolve_codex_runtime_credentials
-from hermes_cli.runtime_provider import resolve_runtime_provider
-
-if TYPE_CHECKING:
-    from typing import TypeGuard
-
-logger = logging.getLogger(__name__)
-
-
-def _utc_now() -> datetime:
-    return datetime.now(timezone.utc)
-
-
-@dataclass(frozen=True)
-class AccountUsageWindow:
-    label: str
-    used_percent: Optional[float] = None
-    reset_at: Optional[datetime] = None
-    detail: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class AccountUsageSnapshot:
-    provider: str
-    source: str
-    fetched_at: datetime
-    title: str = "Account limits"
-    plan: Optional[str] = None
-    windows: tuple[AccountUsageWindow, ...] = ()
-    details: tuple[str, ...] = ()
-    unavailable_reason: Optional[str] = None
-
-    @property
-    def available(self) -> bool:
-        return bool(self.windows or self.details) and not self.unavailable_reason
-
-
-def _title_case_slug(value: Optional[str]) -> Optional[str]:
-    cleaned = str(value or "").strip()
-    if not cleaned:
-        return None
-    return cleaned.replace("_", " ").replace("-", " ").title()
-
-
-def _parse_dt(value: Any) -> Optional[datetime]:
-    if value in {None, ""}:
-        return None
-    if isinstance(value, (int, float)):
-        return datetime.fromtimestamp(float(value), tz=timezone.utc)
-    if isinstance(value, str):
-        text = value.strip()
-        if not text:
-            return None
-        if text.endswith("Z"):
-            text = text[:-1] + "+00:00"
-        try:
-            dt = datetime.fromisoformat(text)
-            return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
-        except ValueError:
-            return None
-    return None
-
-
-def _format_reset(dt: Optional[datetime]) -> str:
-    if not dt:
-        return "unknown"
-    local_dt = dt.astimezone()
-    delta = dt - _utc_now()
-    total_seconds = int(delta.total_seconds())
-    if total_seconds <= 0:
-        return f"now ({local_dt.strftime('%Y-%m-%d %H:%M %Z')})"
-    hours, rem = divmod(total_seconds, 3600)
-    minutes = rem // 60
-    if hours >= 24:
-        days, hours = divmod(hours, 24)
-        rel = f"in {days}d {hours}h"
-    elif hours > 0:
-        rel = f"in {hours}h {minutes}m"
-    else:
-        rel = f"in {minutes}m"
-    return f"{rel} ({local_dt.strftime('%Y-%m-%d %H:%M %Z')})"
-
-
-def render_account_usage_lines(snapshot: Optional[AccountUsageSnapshot], *, markdown: bool = False) -> list[str]:
-    if not snapshot:
-        return []
-    header = f"📈 {'**' if markdown else ''}{snapshot.title}{'**' if markdown else ''}"
-    lines = [header]
-    if snapshot.plan:
-        lines.append(f"Provider: {snapshot.provider} ({snapshot.plan})")
-    else:
-        lines.append(f"Provider: {snapshot.provider}")
-    for window in snapshot.windows:
-        if window.used_percent is None:
-            base = f"{window.label}: unavailable"
-        else:
-            remaining = max(0, round(100 - float(window.used_percent)))
-            used = max(0, round(float(window.used_percent)))
-            base = f"{window.label}: {remaining}% remaining ({used}% used)"
-        if window.reset_at:
-            base += f" • resets {_format_reset(window.reset_at)}"
-        elif window.detail:
-            base += f" • {window.detail}"
-        lines.append(base)
-    for detail in snapshot.details:
-        lines.append(detail)
-    if snapshot.unavailable_reason:
-        lines.append(f"Unavailable: {snapshot.unavailable_reason}")
-    return lines
-
-
-def _fmt_usd(d: float) -> str:
-    return f"${d:,.2f}"
-
-
-def _is_finite_num(v: Any) -> TypeGuard[float]:
-    """True iff v is a real numeric value (int or float, not bool, not NaN/Inf).
-
-    Typed as a ``TypeGuard[float]`` so the type checker narrows ``v`` to a real
-    number in the positive branch — callers can then do arithmetic / pass it to
-    ``_fmt_usd`` without a None-operand warning.
-    """
-    return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
-
-
-def build_nous_credits_snapshot(account_info) -> Optional[AccountUsageSnapshot]:
-    """Map a NousPortalAccountInfo into an AccountUsageSnapshot for /usage.
-
-    Shows dollar magnitudes (subscription / top-up / total) + renewal date + a
-    portal CTA. When the portal supplies a subscription denominator
-    (``monthly_credits``), also emits a subscription-usage window so the renderer
-    shows a real ``% used`` gauge; when it's absent (older portals) the view
-    gracefully degrades to magnitudes-only. Returns None when there's no usable
-    account info to show (fail-open: caller just shows nothing).
-    """
-    try:
-        from hermes_cli.nous_account import nous_portal_topup_url
-
-        if account_info is None or not getattr(account_info, "logged_in", False):
-            return None
-
-        access = getattr(account_info, "paid_service_access_info", None)
-        sub = getattr(account_info, "subscription", None)
-
-        windows: list[AccountUsageWindow] = []
-        details: list[str] = []
-
-        # Subscription usage gauge — only when the portal supplies a positive
-        # monthly_credits denominator AND a finite remaining balance that does
-        # not exceed the cap. Money math is on float dollars (allowed: numeric
-        # account fields, NOT a server-provided *_usd string). used = cap -
-        # remaining; clamp [0,100] so a debt balance (remaining < 0) reads 100%.
-        # Excluded on purpose:
-        #   - non-finite values (NaN/Infinity slip past isinstance and json.loads
-        #     parses bare NaN/Infinity by default) → would render "$nan"/"$inf"
-        #     and a falsely-confident gauge;
-        #   - remaining > cap (rollover balance spanning the period) → monthly_credits
-        #     is no longer a meaningful denominator, and "$X of $Y left" with X>Y
-        #     reads as a contradiction. Both fall back to the magnitudes lines.
-        if sub is not None:
-            monthly_credits = getattr(sub, "monthly_credits", None)
-            sub_remaining = getattr(sub, "credits_remaining", None)
-            if (
-                _is_finite_num(monthly_credits)
-                and monthly_credits > 0
-                and _is_finite_num(sub_remaining)
-                and sub_remaining <= monthly_credits
-            ):
-                used = monthly_credits - sub_remaining
-                used_pct = max(0.0, min(100.0, used / monthly_credits * 100.0))
-                windows.append(
-                    AccountUsageWindow(
-                        label="Subscription",
-                        used_percent=used_pct,
-                        detail=f"{_fmt_usd(sub_remaining)} of {_fmt_usd(monthly_credits)} left",
-                    )
-                )
-
-        if access is not None:
-            sub_credits = getattr(access, "subscription_credits_remaining", None)
-            if _is_finite_num(sub_credits):
-                details.append(f"Subscription credits: {_fmt_usd(sub_credits)}")
-            purchased = getattr(access, "purchased_credits_remaining", None)
-            if _is_finite_num(purchased):
-                details.append(f"Top-up credits: {_fmt_usd(purchased)}")
-            total_usable = getattr(access, "total_usable_credits", None)
-            if _is_finite_num(total_usable):
-                details.append(f"Total usable: {_fmt_usd(total_usable)}")
-
-        if sub is not None:
-            rollover = getattr(sub, "rollover_credits", None)
-            if _is_finite_num(rollover) and rollover > 0:
-                details.append(f"Rollover: {_fmt_usd(rollover)}")
-            period_end = getattr(sub, "current_period_end", None)
-            if period_end:
-                details.append(f"Renews: {period_end}")
-
-        paid = getattr(account_info, "paid_service_access", None)
-        if paid is False:
-            details.append("Status: access depleted — top up to restore")
-
-        if not windows and not details:
-            return None
-
-        details.append(f"Top up: {nous_portal_topup_url(account_info)}")
-        details.append("(or run /topup)")
-
-        plan = getattr(sub, "plan", None) if sub is not None else None
-        return AccountUsageSnapshot(
-            provider="nous",
-            source="portal-account",
-            fetched_at=_utc_now(),
-            title="Nous credits",
-            plan=plan,
-            windows=tuple(windows),
-            details=tuple(details),
-        )
-    except (AttributeError, TypeError):
-        return None
-
-
-def nous_credits_lines(*, markdown: bool = False, timeout: float = 10.0) -> list[str]:
-    """Return rendered Nous-credits /usage lines, or [] when there's nothing to show.
-
-    Account-independent of any live agent: gated on "a Nous account is logged in"
-    (a cheap local auth-state check), then a wall-clock-bounded portal fetch. Shared
-    by the CLI ``_show_usage`` and the TUI ``session.usage`` RPC so both surfaces show
-    the same block regardless of session API-call count or resume state. Fail-open:
-    any auth/portal hiccup or timeout returns [] (the caller shows nothing).
-
-    Dev override: when HERMES_DEV_CREDITS_FIXTURE selects a fixture state, /usage
-    renders from that fixture instead of the real portal (so the block + gauge are
-    testable without a live account). Throwaway scaffolding.
-    """
-    # Dev fixture short-circuit — render /usage from the injected state, no portal.
-    try:
-        from agent.credits_tracker import dev_fixture_credits_state
-
-        fixture = dev_fixture_credits_state()
-    except Exception:
-        fixture = None
-    if fixture is not None:
-        snapshot = _snapshot_from_credits_state(fixture)
-        return render_account_usage_lines(snapshot, markdown=markdown)
-
-    try:
-        from hermes_cli.auth import get_provider_auth_state
-
-        tok = (get_provider_auth_state("nous") or {}).get("access_token")
-        if not (isinstance(tok, str) and tok.strip()):
-            return []
-    except Exception:
-        return []
-    try:
-        import concurrent.futures
-
-        from hermes_cli.nous_account import get_nous_portal_account_info
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            account = pool.submit(
-                get_nous_portal_account_info, force_fresh=True
-            ).result(timeout=timeout)
-        snapshot = build_nous_credits_snapshot(account)
-        return render_account_usage_lines(snapshot, markdown=markdown)
-    except Exception:
-        # Fail-open (caller shows nothing), but leave a breadcrumb so a dead
-        # /usage credits block is diagnosable in agent.log without a dev flag.
-        logger.debug("credits ▸ /usage portal fetch/render failed (fail-open)", exc_info=True)
-        return []
-
-
-def _snapshot_from_credits_state(state) -> Optional[AccountUsageSnapshot]:
-    """Map a header-shaped CreditsState (e.g. a dev fixture) to the /usage snapshot.
-
-    Renders the same magnitudes + monthly-grant % window the portal path produces,
-    so HERMES_DEV_CREDITS_FIXTURE can exercise /usage without a live account. The
-    *_usd strings are mock display values here (not server balance to compute on);
-    the % comes from CreditsState.used_fraction (micros math). Fail-open → None.
-    """
-    try:
-        if state is None:
-            return None
-
-        windows: list[AccountUsageWindow] = []
-        details: list[str] = []
-
-        uf = getattr(state, "used_fraction", None)
-        if isinstance(uf, (int, float)) and math.isfinite(uf):
-            cap_usd = getattr(state, "subscription_limit_usd", None)
-            sub_usd = getattr(state, "subscription_usd", None)
-            detail = None
-            if sub_usd and cap_usd:
-                detail = f"${sub_usd} of ${cap_usd} left"
-            windows.append(
-                AccountUsageWindow(
-                    label="Subscription",
-                    used_percent=max(0.0, min(100.0, uf * 100.0)),
-                    detail=detail,
-                )
-            )
-
-        sub_usd = getattr(state, "subscription_usd", None)
-        if sub_usd:
-            details.append(f"Subscription credits: ${sub_usd}")
-        purchased_usd = getattr(state, "purchased_usd", None)
-        if purchased_usd:
-            details.append(f"Top-up credits: ${purchased_usd}")
-        remaining_usd = getattr(state, "remaining_usd", None)
-        if remaining_usd:
-            details.append(f"Total usable: ${remaining_usd}")
-        if getattr(state, "paid_access", True) is False:
-            details.append("Status: access depleted — top up to restore")
-
-        if not windows and not details:
-            return None
-
-        details.append("(dev fixture — HERMES_DEV_CREDITS_FIXTURE)")
-        return AccountUsageSnapshot(
-            provider="nous",
-            source="dev-fixture",
-            fetched_at=_utc_now(),
-            title="Nous credits",
-            windows=tuple(windows),
-            details=tuple(details),
-        )
-    except (AttributeError, TypeError):
-        return None
-
-
-@dataclass(frozen=True)
-class CreditsView:
-    """Surface-agnostic data for the ``/topup`` balance view.
-
-    One portal fetch, one parse — consumed identically by the CLI panel, the
-    gateway button, and any other money surface. Fail-open: when not logged in
-    or the portal is unreachable, ``logged_in`` is False / ``topup_url`` is None
-    and callers degrade gracefully.
-    """
-
-    logged_in: bool
-    balance_lines: tuple[str, ...] = ()
-    identity_line: Optional[str] = None
-    topup_url: Optional[str] = None
-    depleted: bool = False
-
-
-def build_credits_view(*, markdown: bool = False, timeout: float = 10.0) -> CreditsView:
-    """Build the /topup balance view: balance block + identity line + top-up URL.
-
-    Reuses the same account fetch + snapshot + URL builder as the /usage credits
-    block, so the numbers always match. The balance block is the rendered
-    snapshot MINUS its trailing top-up/command-hint lines (the /topup surface
-    supplies its own affordance). Fail-open → ``CreditsView(logged_in=False)``.
-    """
-    not_logged_in = CreditsView(logged_in=False)
-    try:
-        from hermes_cli.auth import get_provider_auth_state
-
-        tok = (get_provider_auth_state("nous") or {}).get("access_token")
-        if not (isinstance(tok, str) and tok.strip()):
-            return not_logged_in
-    except Exception:
-        return not_logged_in
-
-    try:
-        import concurrent.futures
-
-        from hermes_cli.nous_account import (
-            get_nous_portal_account_info,
-            nous_portal_topup_url,
-        )
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            account = pool.submit(get_nous_portal_account_info, force_fresh=True).result(
-                timeout=timeout
-            )
-    except Exception:
-        logger.debug("credits ▸ /topup portal fetch failed (fail-open)", exc_info=True)
-        return not_logged_in
-
-    if account is None or not getattr(account, "logged_in", False):
-        return not_logged_in
-
-    snapshot = build_nous_credits_snapshot(account)
-    # Balance lines = the snapshot block minus the two trailing affordance lines
-    # ("Top up: <url>" + "(or run /topup)") that build_nous_credits_snapshot
-    # appends for the /usage surface. /topup renders its own button/panel.
-    balance_lines: list[str] = []
-    if snapshot is not None:
-        rendered = render_account_usage_lines(snapshot, markdown=markdown)
-        balance_lines = [
-            line
-            for line in rendered
-            if not line.lstrip().startswith("Top up:")
-            and not line.lstrip().startswith("(or run")
-        ]
-
-    # Identity line — shown before any open (roadmap §4.4).
-    email = getattr(account, "email", None)
-    org_name = getattr(account, "org_name", None)
-    who: list[str] = []
-    if email:
-        who.append(str(email))
-    if org_name:
-        who.append(f"org {org_name}")
-    identity_line = ("Topping up as " + " / ".join(who)) if who else None
-
-    return CreditsView(
-        logged_in=True,
-        balance_lines=tuple(balance_lines),
-        identity_line=identity_line,
-        topup_url=nous_portal_topup_url(account),
-        depleted=getattr(account, "paid_service_access", None) is False,
-    )
-
-
-def _codex_backend_urls(base_url: str) -> tuple[str, str, str]:
-    """Resolve the Codex backend endpoints (usage, reset-credits list, consume).
-
-    Mirrors the Codex CLI's PathStyle split (codex-rs backend-client): base URLs
-    containing ``/backend-api`` use the ChatGPT ``/wham/...`` paths; everything
-    else uses ``/api/codex/...``.
-    """
-    normalized = (base_url or "").strip().rstrip("/")
-    if not normalized:
-        normalized = "https://chatgpt.com/backend-api/codex"
-    if normalized.endswith("/codex"):
-        normalized = normalized[: -len("/codex")]
-    prefix = normalized + ("/wham" if "/backend-api" in normalized else "/api/codex")
-    return (
-        prefix + "/usage",
-        prefix + "/rate-limit-reset-credits",
-        prefix + "/rate-limit-reset-credits/consume",
-    )
-
-
-def _resolve_codex_usage_url(base_url: str) -> str:
-    return _codex_backend_urls(base_url)[0]
-
-
-def _resolve_codex_usage_credentials(
-    base_url: Optional[str],
-    api_key: Optional[str],
-) -> tuple[str, str, Optional[str]]:
-    """Resolve Codex quota credentials from the native runtime path.
-
-    Prefer explicit live-agent credentials, then the legacy singleton OAuth
-    state, then the credential pool.  Hermes's native OAuth setup now stores
-    device-code logins in the pool, so quota diagnostics must not depend only
-    on the older singleton store.
-    """
-    explicit_key = str(api_key or "").strip()
-    if explicit_key:
-        return explicit_key, str(base_url or "").strip(), None
-
-    # Tier 2: the native runtime resolver. It ALREADY falls back to the
-    # credential pool when the singleton is empty (see
-    # ``resolve_codex_runtime_credentials`` — issue #32992), so in a pool-only
-    # setup this returns a usable ``source="credential_pool"`` token.
-    #
-    # Only ``AuthError`` ("no creds" / rate-limited) is caught so tier 3 can
-    # run: a broad ``except Exception`` would (a) mask a transient refresh /
-    # network failure and silently hand back a DIFFERENT pool account's usage,
-    # and (b) hide genuine programming errors. A refresh/network error must
-    # propagate — the outer ``fetch_account_usage`` guard fails open (shows
-    # nothing this turn) rather than reporting the wrong account.
-    #
-    # The ``account_id`` (for the ``ChatGPT-Account-Id`` header) is read
-    # best-effort: a partial/missing singleton token store must not sink an
-    # otherwise-usable resolver credential and force a header-less pool fallback.
-    try:
-        creds = resolve_codex_runtime_credentials(refresh_if_expiring=True)
-        account_id: Optional[str] = None
-        try:
-            token_data = _read_codex_tokens()
-            tokens = token_data.get("tokens") or {}
-            account_id = str(tokens.get("account_id", "") or "").strip() or None
-        except AuthError:
-            # Pool-only creds carry no singleton account_id; header is optional.
-            logger.debug("codex ▸ /usage account_id read failed (best-effort)", exc_info=True)
-        return creds["api_key"], str(creds.get("base_url", "") or "").strip(), account_id
-    except AuthError:
-        logger.debug("codex ▸ /usage runtime resolver returned no creds; trying pool", exc_info=True)
-
-    # Tier 3: direct pool select. Reached only when the resolver itself raises
-    # AuthError (e.g. singleton missing AND its own pool read found nothing at
-    # resolve time, but a pool entry is usable now). Pool credentials have no
-    # account_id concept, so the ChatGPT-Account-Id header is intentionally
-    # omitted here.
-    from agent.credential_pool import load_pool
-
-    pool = load_pool("openai-codex")
-    entry = pool.select()
-    if entry is None:
-        raise RuntimeError("No available openai-codex credential in credential pool")
-    return entry.runtime_api_key, str(entry.runtime_base_url or base_url or "").strip(), None
-
-
-def _fetch_codex_account_usage(
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-) -> Optional[AccountUsageSnapshot]:
-    token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "Accept": "application/json",
-        "User-Agent": "codex-cli",
-    }
-    if account_id:
-        headers["ChatGPT-Account-Id"] = account_id
-    with httpx.Client(timeout=15.0) as client:
-        response = client.get(_resolve_codex_usage_url(resolved_base_url), headers=headers)
-        response.raise_for_status()
-    payload = response.json() or {}
-    rate_limit = payload.get("rate_limit") or {}
-    windows: list[AccountUsageWindow] = []
-    for key, label in (("primary_window", "Session"), ("secondary_window", "Weekly")):
-        window = rate_limit.get(key) or {}
-        used = window.get("used_percent")
-        if used is None:
-            continue
-        windows.append(
-            AccountUsageWindow(
-                label=label,
-                used_percent=float(used),
-                reset_at=_parse_dt(window.get("reset_at")),
-            )
-        )
-    details: list[str] = []
-    reset_credits = payload.get("rate_limit_reset_credits") or {}
-    banked = reset_credits.get("available_count")
-    if isinstance(banked, (int, float)) and int(banked) > 0:
-        count = int(banked)
-        plural = "s" if count != 1 else ""
-        details.append(
-            f"You have {count} reset{plural} banked - use /usage reset to activate"
-        )
-    credits = payload.get("credits") or {}
-    if credits.get("has_credits"):
-        balance = credits.get("balance")
-        if isinstance(balance, (int, float)):
-            details.append(f"Credits balance: ${float(balance):.2f}")
-        elif credits.get("unlimited"):
-            details.append("Credits balance: unlimited")
-    return AccountUsageSnapshot(
-        provider="openai-codex",
-        source="usage_api",
-        fetched_at=_utc_now(),
-        plan=_title_case_slug(payload.get("plan_type")),
-        windows=tuple(windows),
-        details=tuple(details),
-    )
-
-
-@dataclass(frozen=True)
-class CodexResetRedeemResult:
-    """Outcome of a `/usage reset` attempt against the Codex backend."""
-
-    status: str  # reset | nothing_to_reset | no_credit | already_redeemed |
-    #              not_exhausted | no_credits_banked | unavailable
-    message: str
-    available_count: int = 0
-    windows_reset: int = 0
-
-    @property
-    def redeemed(self) -> bool:
-        return self.status == "reset"
-
-
-# Client-side guard threshold: a rate-limit window only counts as exhausted
-# when it is fully used. Below this, redeeming a banked reset wastes most of
-# its value, so we block and point at --force instead.
-_CODEX_WINDOW_EXHAUSTED_PERCENT = 100.0
-
-
-def redeem_codex_reset_credit(
-    *,
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-    force: bool = False,
-) -> CodexResetRedeemResult:
-    """Redeem one banked Codex rate-limit reset credit (`/usage reset`).
-
-    Flow (mirrors the Codex CLI's reset-credits picker, codex-rs
-    ``backend-client``):
-
-    1. ``GET .../usage`` — read the current windows + banked credit count.
-    2. Guard: zero banked credits → refuse. No window fully used and not
-       ``force`` → refuse with a warning (a banked reset restores the WHOLE
-       5h + weekly allowance; burning it early wastes it). The backend has
-       the same protection (``nothing_to_reset`` doesn't consume the
-       credit), but failing fast client-side gives a clearer message.
-    3. ``POST .../rate-limit-reset-credits/consume`` with a fresh UUID
-       idempotency key (``redeem_request_id``). No ``credit_id`` — the
-       backend picks the next available credit, exactly like the CLI's
-       default "Full reset" option.
-
-    Never raises: every failure mode returns a ``CodexResetRedeemResult``
-    with a user-renderable message.
-    """
-    import uuid
-
-    try:
-        token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
-    except Exception:
-        return CodexResetRedeemResult(
-            status="unavailable",
-            message="No Codex credentials available. Run `hermes auth` to sign in with your ChatGPT account.",
-        )
-    usage_url, _credits_url, consume_url = _codex_backend_urls(resolved_base_url)
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "Accept": "application/json",
-        "User-Agent": "codex-cli",
-    }
-    if account_id:
-        headers["ChatGPT-Account-Id"] = account_id
-
-    try:
-        with httpx.Client(timeout=15.0) as client:
-            usage_resp = client.get(usage_url, headers=headers)
-            usage_resp.raise_for_status()
-            payload = usage_resp.json() or {}
-
-            reset_credits = payload.get("rate_limit_reset_credits") or {}
-            raw_count = reset_credits.get("available_count")
-            available = int(raw_count) if isinstance(raw_count, (int, float)) else 0
-            if available <= 0:
-                return CodexResetRedeemResult(
-                    status="no_credits_banked",
-                    message="No banked reset credits on this account — nothing to redeem.",
-                )
-
-            rate_limit = payload.get("rate_limit") or {}
-            worst_used: Optional[float] = None
-            for key in ("primary_window", "secondary_window"):
-                used = (rate_limit.get(key) or {}).get("used_percent")
-                if isinstance(used, (int, float)):
-                    worst_used = max(worst_used or 0.0, float(used))
-            exhausted = worst_used is not None and worst_used >= _CODEX_WINDOW_EXHAUSTED_PERCENT
-            if not exhausted and not force:
-                usage_note = (
-                    f"your busiest window is only {worst_used:.0f}% used"
-                    if worst_used is not None
-                    else "your current usage could not be confirmed as exhausted"
-                )
-                plural = "s" if available != 1 else ""
-                return CodexResetRedeemResult(
-                    status="not_exhausted",
-                    message=(
-                        f"⚠️ Not redeeming: {usage_note}. A banked reset restores your FULL "
-                        f"5h + weekly limits, so spending it now would waste most of it. "
-                        f"You have {available} reset{plural} banked. "
-                        f"Use `/usage reset --force` to redeem anyway."
-                    ),
-                    available_count=available,
-                )
-
-            consume_resp = client.post(
-                consume_url,
-                headers={**headers, "Content-Type": "application/json"},
-                json={"redeem_request_id": str(uuid.uuid4())},
-            )
-            consume_resp.raise_for_status()
-            body = consume_resp.json() or {}
-    except httpx.HTTPStatusError as exc:
-        code = exc.response.status_code
-        if code in (401, 403):
-            return CodexResetRedeemResult(
-                status="unavailable",
-                message=(
-                    "Codex backend rejected the request (HTTP "
-                    f"{code}). Reset credits require ChatGPT-account (OAuth) auth — "
-                    "run `hermes auth` and sign in with your ChatGPT account."
-                ),
-            )
-        return CodexResetRedeemResult(
-            status="unavailable",
-            message=f"Codex backend error (HTTP {code}) — try again shortly.",
-        )
-    except Exception as exc:
-        return CodexResetRedeemResult(
-            status="unavailable",
-            message=f"Could not reach the Codex backend: {exc}",
-        )
-
-    code = str(body.get("code", "") or "").strip().lower()
-    windows_reset = body.get("windows_reset")
-    windows_reset = int(windows_reset) if isinstance(windows_reset, (int, float)) else 0
-    remaining = max(0, available - 1)
-    plural = "s" if remaining != 1 else ""
-    if code == "reset":
-        return CodexResetRedeemResult(
-            status="reset",
-            message=(
-                f"✅ Reset redeemed — your usage limits have been reset. "
-                f"{remaining} banked reset{plural} remaining."
-            ),
-            available_count=remaining,
-            windows_reset=windows_reset,
-        )
-    if code == "nothing_to_reset":
-        return CodexResetRedeemResult(
-            status="nothing_to_reset",
-            message=(
-                "Backend reports nothing to reset — your limits aren't exhausted. "
-                "The credit was NOT spent."
-            ),
-            available_count=available,
-        )
-    if code == "no_credit":
-        return CodexResetRedeemResult(
-            status="no_credit",
-            message="Backend reports no available reset credit on this account.",
-        )
-    if code == "already_redeemed":
-        return CodexResetRedeemResult(
-            status="already_redeemed",
-            message="This redemption was already processed — no additional credit was spent.",
-            available_count=remaining,
-        )
-    return CodexResetRedeemResult(
-        status="unavailable",
-        message=f"Unexpected response from the Codex backend: {body!r}",
-    )
-
-
-def _fetch_anthropic_account_usage() -> Optional[AccountUsageSnapshot]:
-    token = (resolve_anthropic_token() or "").strip()
-    if not token:
-        return None
-    if not _is_oauth_token(token):
-        return AccountUsageSnapshot(
-            provider="anthropic",
-            source="oauth_usage_api",
-            fetched_at=_utc_now(),
-            unavailable_reason="Anthropic account limits are only available for OAuth-backed Claude accounts.",
-        )
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "Accept": "application/json",
-        "Content-Type": "application/json",
-        "anthropic-beta": "oauth-2025-04-20",
-        "User-Agent": "claude-code/2.1.0",
-    }
-    with httpx.Client(timeout=15.0) as client:
-        response = client.get("https://api.anthropic.com/api/oauth/usage", headers=headers)
-        response.raise_for_status()
-    payload = response.json() or {}
-    windows: list[AccountUsageWindow] = []
-    mapping = (
-        ("five_hour", "Current session"),
-        ("seven_day", "Current week"),
-        ("seven_day_opus", "Opus week"),
-        ("seven_day_sonnet", "Sonnet week"),
-    )
-    for key, label in mapping:
-        window = payload.get(key) or {}
-        util = window.get("utilization")
-        if util is None:
-            continue
-        used = float(util) * 100 if float(util) <= 1 else float(util)
-        windows.append(
-            AccountUsageWindow(
-                label=label,
-                used_percent=used,
-                reset_at=_parse_dt(window.get("resets_at")),
-            )
-        )
-    details: list[str] = []
-    extra = payload.get("extra_usage") or {}
-    if extra.get("is_enabled"):
-        used_credits = extra.get("used_credits")
-        monthly_limit = extra.get("monthly_limit")
-        currency = extra.get("currency") or "USD"
-        if isinstance(used_credits, (int, float)) and isinstance(monthly_limit, (int, float)):
-            details.append(
-                f"Extra usage: {used_credits:.2f} / {monthly_limit:.2f} {currency}"
-            )
-    return AccountUsageSnapshot(
-        provider="anthropic",
-        source="oauth_usage_api",
-        fetched_at=_utc_now(),
-        windows=tuple(windows),
-        details=tuple(details),
-    )
-
-
-def _fetch_openrouter_account_usage(base_url: Optional[str], api_key: Optional[str]) -> Optional[AccountUsageSnapshot]:
-    runtime = resolve_runtime_provider(
-        requested="openrouter",
-        explicit_base_url=base_url,
-        explicit_api_key=api_key,
-    )
-    token = str(runtime.get("api_key", "") or "").strip()
-    if not token:
-        return None
-    normalized = str(runtime.get("base_url", "") or "").rstrip("/")
-    credits_url = f"{normalized}/credits"
-    key_url = f"{normalized}/key"
-    headers = {
-        "Authorization": f"Bearer {token}",
-        "Accept": "application/json",
-    }
-    with httpx.Client(timeout=10.0) as client:
-        credits_resp = client.get(credits_url, headers=headers)
-        credits_resp.raise_for_status()
-        credits = (credits_resp.json() or {}).get("data") or {}
-        try:
-            key_resp = client.get(key_url, headers=headers)
-            key_resp.raise_for_status()
-            key_data = (key_resp.json() or {}).get("data") or {}
-        except Exception:
-            key_data = {}
-    total_credits = float(credits.get("total_credits") or 0.0)
-    total_usage = float(credits.get("total_usage") or 0.0)
-    details = [f"Credits balance: ${max(0.0, total_credits - total_usage):.2f}"]
-    windows: list[AccountUsageWindow] = []
-    limit = key_data.get("limit")
-    limit_remaining = key_data.get("limit_remaining")
-    limit_reset = str(key_data.get("limit_reset") or "").strip()
-    usage = key_data.get("usage")
-    if (
-        isinstance(limit, (int, float))
-        and float(limit) > 0
-        and isinstance(limit_remaining, (int, float))
-        and 0 <= float(limit_remaining) <= float(limit)
-    ):
-        limit_value = float(limit)
-        remaining_value = float(limit_remaining)
-        used_percent = ((limit_value - remaining_value) / limit_value) * 100
-        detail_parts = [f"${remaining_value:.2f} of ${limit_value:.2f} remaining"]
-        if limit_reset:
-            detail_parts.append(f"resets {limit_reset}")
-        windows.append(
-            AccountUsageWindow(
-                label="API key quota",
-                used_percent=used_percent,
-                detail=" • ".join(detail_parts),
-            )
-        )
-    if isinstance(usage, (int, float)):
-        usage_parts = [f"API key usage: ${float(usage):.2f} total"]
-        for value, label in (
-            (key_data.get("usage_daily"), "today"),
-            (key_data.get("usage_weekly"), "this week"),
-            (key_data.get("usage_monthly"), "this month"),
-        ):
-            if isinstance(value, (int, float)) and float(value) > 0:
-                usage_parts.append(f"${float(value):.2f} {label}")
-        details.append(" • ".join(usage_parts))
-    return AccountUsageSnapshot(
-        provider="openrouter",
-        source="credits_api",
-        fetched_at=_utc_now(),
-        windows=tuple(windows),
-        details=tuple(details),
-    )
-
-
-def fetch_account_usage(
-    provider: Optional[str],
-    *,
-    base_url: Optional[str] = None,
-    api_key: Optional[str] = None,
-) -> Optional[AccountUsageSnapshot]:
-    normalized = str(provider or "").strip().lower()
-    if normalized in {"", "auto", "custom"}:
-        return None
-    try:
-        if normalized == "openai-codex":
-            return _fetch_codex_account_usage(base_url=base_url, api_key=api_key)
-        if normalized == "anthropic":
-            return _fetch_anthropic_account_usage()
-        if normalized == "openrouter":
-            return _fetch_openrouter_account_usage(base_url, api_key)
-    except Exception:
-        return None
-    return None
@@ -1,84 +0,0 @@
-"""Async/sync bridging helpers.
-
-The codebase has ~30 sites that schedule a coroutine onto an event loop from a
-worker thread via :func:`asyncio.run_coroutine_threadsafe`.  That function can
-raise :class:`RuntimeError` (e.g. the loop was closed during a shutdown race),
-and when it does the coroutine object is never awaited and never closed —
-which triggers a ``"coroutine '<name>' was never awaited"`` RuntimeWarning and
-leaks the coroutine's frame until GC.
-
-:func:`safe_schedule_threadsafe` wraps the call, closes the coroutine on
-scheduling failure, and returns ``None`` (instead of a half-formed future) so
-callers can branch cleanly:
-
-    fut = safe_schedule_threadsafe(coro, loop)
-    if fut is None:
-        return  # or fallback behavior
-    fut.result(timeout=5)
-
-The helper deliberately does NOT also handle ``future.result()`` failures —
-that is a separate concern.  Once the loop has accepted the coroutine, its
-lifecycle belongs to the loop, not the scheduling thread.
-"""
-from __future__ import annotations
-
-import asyncio
-import logging
-from concurrent.futures import Future
-from typing import Any, Coroutine, Optional
-
-
-_DEFAULT_LOGGER = logging.getLogger(__name__)
-
-
-def safe_schedule_threadsafe(
-    coro: Coroutine[Any, Any, Any],
-    loop: Optional[asyncio.AbstractEventLoop],
-    *,
-    logger: Optional[logging.Logger] = None,
-    log_message: str = "Failed to schedule coroutine on loop",
-    log_level: int = logging.DEBUG,
-) -> Optional[Future]:
-    """Schedule ``coro`` on ``loop`` from a sync context, leak-safe.
-
-    Returns the :class:`concurrent.futures.Future` on success, or ``None`` if
-    the loop is missing or :func:`asyncio.run_coroutine_threadsafe` raised
-    (e.g. the loop was closed during a shutdown race).  In all failure paths
-    the coroutine is :meth:`close`-d so it does not trigger
-    ``"coroutine was never awaited"`` warnings or leak its frame.
-
-    Callers retain full control over what to do with the returned future
-    (call ``.result(timeout=...)``, attach ``add_done_callback``, ignore it
-    fire-and-forget, etc.).
-    """
-    log = logger if logger is not None else _DEFAULT_LOGGER
-
-    if loop is None:
-        if asyncio.iscoroutine(coro):
-            coro.close()
-        log.log(log_level, "%s: loop is None", log_message)
-        return None
-
-    try:
-        return asyncio.run_coroutine_threadsafe(coro, loop)
-    except Exception as exc:
-        if asyncio.iscoroutine(coro):
-            coro.close()
-        log.log(log_level, "%s: %s", log_message, exc)
-        return None
-
-
-def consume_detached_task_result(task: "asyncio.Future[Any]") -> None:
-    """Retrieve a detached task's result without surfacing cancellation.
-
-    Used as an ``add_done_callback`` on tasks that were cancelled and
-    detached (e.g. an adapter close path that swallows ``CancelledError``
-    past its teardown deadline). Observing ``task.exception()`` prevents
-    "exception was never retrieved" noise on the event loop; cancellation
-    and any terminal error are deliberately swallowed — the task's owner
-    already gave up on it.
-    """
-    try:
-        task.exception()
-    except (asyncio.CancelledError, Exception):
-        pass
@@ -1,138 +0,0 @@
-"""Ambient session-accounting context for auxiliary LLM calls.
-
-Auxiliary calls (vision, compression, title generation, web_extract,
-session_search, ...) funnel through ``agent.auxiliary_client`` which has no
-session handle — so their token usage was historically discarded, leaving
-dashboard analytics blind to aux model spend (issue #23270).
-
-Instead of threading ``session_db``/``session_id`` parameters through every
-aux call site, the agent loop publishes them here (mirroring the Nous Portal
-conversation context in ``agent.portal_tags``) and the auxiliary client
-records usage at its single response-validation chokepoint.
-
-ContextVar semantics give us the right isolation for free:
-
-* concurrent agents in one process (gateway sessions, delegate subagents)
-  never see each other's accounting context;
-* worker threads spawned via ``tools.thread_context.propagate_context_to_thread``
-  (MoA fan-out, background review) inherit the parent turn's context;
-* asyncio tasks inherit the context of the code that created them.
-
-MoA reference/aggregator slots are explicitly EXCLUDED from recording:
-``agent/conversation_loop.py`` already folds MoA advisor usage and cost into
-the main loop's ``update_token_counts`` delta, so recording them here would
-double-count (see ``_EXCLUDED_TASKS``).
-"""
-
-from __future__ import annotations
-
-import logging
-from contextvars import ContextVar
-from typing import Any, Optional
-
-logger = logging.getLogger(__name__)
-
-# (session_db, session_id) for the active agent turn, or None outside one.
-_accounting: ContextVar[Optional[tuple]] = ContextVar(
-    "aux_accounting_context", default=None
-)
-
-# Aux tasks whose usage is already accounted by the main loop — recording
-# them here would double-count. MoA advisor/aggregator usage is folded into
-# conversation_loop's update_token_counts delta (tokens AND cost).
-_EXCLUDED_TASKS = frozenset({"moa_reference", "moa_aggregator"})
-
-
-def set_accounting_context(session_db: Any, session_id: Optional[str]):
-    """Publish the active session's accounting handles for aux usage recording.
-
-    Called by the agent loop at turn entry. Returns the ContextVar token so
-    callers can ``reset_accounting_context(token)`` on turn exit. Publishing
-    ``None`` handles (no DB / no session id) clears the context.
-    """
-    if session_db is None or not session_id:
-        return _accounting.set(None)
-    return _accounting.set((session_db, session_id))
-
-
-def reset_accounting_context(token) -> None:
-    """Restore the previous accounting context (pair with ``set_...``)."""
-    try:
-        _accounting.reset(token)
-    except Exception:
-        _accounting.set(None)
-
-
-def get_accounting_context() -> Optional[tuple]:
-    """Return ``(session_db, session_id)`` for the active turn, or ``None``."""
-    return _accounting.get()
-
-
-def record_aux_usage(
-    response: Any,
-    task: Optional[str],
-    *,
-    provider: Optional[str] = None,
-    base_url: Optional[str] = None,
-) -> None:
-    """Record an auxiliary response's token usage against the ambient session.
-
-    Called from the auxiliary client's response-validation chokepoint. Strictly
-    best-effort: any failure is swallowed (accounting must never break an aux
-    call). No-ops when:
-
-    * no accounting context is published (call is outside any agent turn),
-    * the task is main-loop-accounted (MoA slots — see ``_EXCLUDED_TASKS``),
-    * the response carries no usage object.
-
-    The model is read from ``response.model`` (accurate even after the aux
-    client's provider-fallback chains); *provider*/*base_url* reflect the
-    originally-resolved route and are best-effort.
-    """
-    try:
-        if not task or task in _EXCLUDED_TASKS:
-            return
-        ctx = _accounting.get()
-        if ctx is None:
-            return
-        session_db, session_id = ctx
-        raw_usage = getattr(response, "usage", None)
-        if raw_usage is None:
-            return
-
-        from agent.usage_pricing import estimate_usage_cost, normalize_usage
-
-        usage = normalize_usage(raw_usage, provider=provider)
-        if not (
-            usage.input_tokens or usage.output_tokens
-            or usage.cache_read_tokens or usage.cache_write_tokens
-            or usage.reasoning_tokens
-        ):
-            return
-
-        model = str(getattr(response, "model", "") or "") or "unknown"
-        estimated_cost = None
-        try:
-            cost = estimate_usage_cost(
-                model, usage, provider=provider, base_url=base_url
-            )
-            if cost.amount_usd is not None:
-                estimated_cost = float(cost.amount_usd)
-        except Exception:
-            logger.debug("Aux usage cost estimation failed", exc_info=True)
-
-        session_db.record_auxiliary_usage(
-            session_id,
-            task,
-            model=model,
-            billing_provider=provider,
-            billing_base_url=base_url,
-            input_tokens=usage.input_tokens,
-            output_tokens=usage.output_tokens,
-            cache_read_tokens=usage.cache_read_tokens,
-            cache_write_tokens=usage.cache_write_tokens,
-            reasoning_tokens=usage.reasoning_tokens,
-            estimated_cost_usd=estimated_cost,
-        )
-    except Exception:
-        logger.debug("Aux usage recording failed (non-fatal)", exc_info=True)
@@ -1,555 +0,0 @@
-"""Microsoft Entra ID adapter for Microsoft Foundry.
-
-Provides keyless authentication for Microsoft Foundry deployments using the
-`azure-identity` SDK's `DefaultAzureCredential` chain (env service principal
-→ workload identity → managed identity → VS Code → Azure CLI → azd →
-PowerShell → broker).
-
-Architecture mirrors `agent/bedrock_adapter.py`:
-
-* Lazy import. `azure-identity` is only loaded when ``model.auth_mode =
-  entra_id`` is selected. Users who stick with `AZURE_FOUNDRY_API_KEY`
-  never pay the import cost.
-* SDK-callable contract. The public entry point ``build_token_provider``
-  returns a zero-arg callable produced by ``get_bearer_token_provider`` —
-  this is exactly the value Microsoft's documented sample plugs into
-  ``OpenAI(api_key=token_provider, base_url=...)``. The OpenAI SDK calls
-  it before every request, so token refresh is transparent.
-* Three explicit consumer-side helpers (display / cache / http-bearer)
-  rather than one generic "materialize" function — splitting them by
-  purpose prevents accidental token-minting in logging paths or token
-  leakage into cache keys / dashboard JSON.
-* No persisted JWT. ``azure-identity`` caches in-process and (where
-  available) in the OS keychain or ``~/.IdentityService``. Hermes does
-  not duplicate that storage in ``auth.json``.
-
-Reference: https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id
-
-Requires: ``azure-identity`` (optional dependency — only needed when
-``model.auth_mode = entra_id``).
-"""
-
-from __future__ import annotations
-
-import functools
-import logging
-import os
-import threading
-from dataclasses import dataclass
-from typing import Any, Callable, Dict, Optional
-
-logger = logging.getLogger(__name__)
-
-# Microsoft-documented scope for Foundry inference auth. Both the new
-# Foundry portal and the legacy Azure OpenAI managed-identity docs use
-# this scope for ALL Foundry endpoint shapes (*.openai.azure.com,
-# *.services.ai.azure.com, *.ai.azure.com). The older control-plane
-# scope ``https://cognitiveservices.azure.com/.default`` is for ARM
-# resource management and is rejected for inference by newer
-# resources — users with that requirement override via
-# ``model.entra.scope`` in config.yaml.
-SCOPE_AI_AZURE_DEFAULT = "https://ai.azure.com/.default"
-
-# ---------------------------------------------------------------------------
-# Lazy SDK import — only loaded when the Entra path is actually used.
-# ---------------------------------------------------------------------------
-
-_AZURE_IDENTITY_FEATURE = "provider.azure_identity"
-
-
-def has_azure_identity_installed() -> bool:
-    """Return True if `azure-identity` can be imported right now.
-
-    Cheap check — does not walk the credential chain.
-    """
-    try:
-        import azure.identity  # noqa: F401
-        return True
-    except Exception:
-        return False
-
-
-def _require_azure_identity():
-    """Import ``azure.identity``, lazy-installing it if allowed.
-
-    Raises ``ImportError`` with a clear actionable message when the
-    package is missing and lazy installs are disabled.
-    """
-    try:
-        import azure.identity as _ai
-        return _ai
-    except ImportError:
-        try:
-            from tools.lazy_deps import ensure, FeatureUnavailable
-        except ImportError as exc:
-            raise ImportError(
-                "The 'azure-identity' package is required for Azure AI "
-                "Foundry Entra ID authentication. Install it with: "
-                "pip install azure-identity"
-            ) from exc
-
-        try:
-            ensure(_AZURE_IDENTITY_FEATURE, prompt=False)
-        except FeatureUnavailable as exc:
-            raise ImportError(
-                "The 'azure-identity' package is required for Azure AI "
-                "Foundry Entra ID authentication. " + str(exc)
-            ) from exc
-
-        # Retry import after lazy install.
-        import azure.identity as _ai  # noqa: WPS440
-        return _ai
-
-
-def reset_credential_cache() -> None:
-    """Clear the cached ``DefaultAzureCredential``. Used by tests and
-    profile switches.
-
-    Defensive against tests that ``monkeypatch.setattr`` over
-    ``build_credential`` with a plain (non-lru-cached) function — those
-    won't expose ``cache_clear()`` until pytest reverts the patch.
-    """
-    cache_clear = getattr(build_credential, "cache_clear", None)
-    if callable(cache_clear):
-        cache_clear()
-
-
-# ---------------------------------------------------------------------------
-# Token-provider construction
-# ---------------------------------------------------------------------------
-
-
-@dataclass(frozen=True)
-class EntraIdentityConfig:
-    """Serializable Entra ID config.
-
-    Captures the Hermes-managed Entra knobs we need outside Azure SDK
-    environment configuration. Everything else
-    (tenant ID, service principal secret, federated token file, sovereign
-    cloud authority, etc.) flows through azure-identity's standard
-    ``AZURE_*`` env vars — see the Bedrock pattern in
-    ``hermes_cli/runtime_provider.py:1310-1377`` for the analogous
-    "let the SDK read env" approach.
-
-    ``scope`` is Microsoft's documented Foundry inference audience. Almost
-    everyone uses the default; sovereign-cloud / non-standard tenants can
-    override via ``model.entra.scope``. Identity selection (user-assigned
-    managed identity, workload identity, service principal, tenant, authority)
-    stays in the standard Azure SDK env vars such as ``AZURE_CLIENT_ID``.
-
-    ``exclude_interactive_browser`` is kept as an internal constructor knob
-    so probes stay non-interactive by default. It is not written by the setup
-    wizard.
-
-    The dataclass is frozen so it's hashable for ``functools.lru_cache``
-    keying, and serializable across multiprocessing boundaries (workers
-    rebuild the credential inside their own process).
-    """
-
-    scope: str = SCOPE_AI_AZURE_DEFAULT
-    exclude_interactive_browser: bool = True
-
-    def __post_init__(self) -> None:
-        scope = str(self.scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
-        object.__setattr__(self, "scope", scope)
-
-    def to_dict(self) -> Dict[str, Any]:
-        return {
-            "scope": self.scope,
-            "exclude_interactive_browser": self.exclude_interactive_browser,
-        }
-
-    @classmethod
-    def from_dict(cls, data: Optional[Dict[str, Any]],
-                  *, default_scope: Optional[str] = None) -> "EntraIdentityConfig":
-        data = data or {}
-        scope = str(data.get("scope") or "").strip() or default_scope or SCOPE_AI_AZURE_DEFAULT
-        exclude_browser = bool(data.get("exclude_interactive_browser", True))
-        return cls(
-            scope=scope,
-            exclude_interactive_browser=exclude_browser,
-        )
-
-
-def _build_default_credential(config: EntraIdentityConfig) -> Any:
-    """Construct a ``DefaultAzureCredential`` for ``config``.
-
-    Only Hermes-selected knobs are passed as kwargs. Everything else
-    (tenant, service principal secret, federated token file, sovereign
-    cloud authority, etc.) is read by ``azure-identity`` from the
-    standard ``AZURE_*`` environment variables — see Microsoft's
-    documented credential resolution chain. Users configure those in
-    ``~/.hermes/.env`` or the deployment environment.
-    """
-    ai = _require_azure_identity()
-    kwargs: Dict[str, Any] = {}
-    # SDK default is True (browser excluded); only pass when the user
-    # explicitly opts in to interactive browser auth.
-    if not config.exclude_interactive_browser:
-        kwargs["exclude_interactive_browser_credential"] = False
-    return ai.DefaultAzureCredential(**kwargs)
-
-
-@functools.lru_cache(maxsize=1)
-def build_credential(config: EntraIdentityConfig) -> Any:
-    """Return the cached ``DefaultAzureCredential`` for ``config``.
-
-    Hermes processes use exactly one Entra config at a time (the
-    ``model.entra.*`` block in config.yaml drives every aux task,
-    subagent, and credential probe in the session). ``maxsize=1`` is
-    intentional: it reflects the actual usage pattern and keeps the
-    cache trivially small.
-
-    ``EntraIdentityConfig`` is a frozen dataclass, so it's hashable and
-    safe as an LRU-cache key. ``functools.lru_cache`` is thread-safe in
-    CPython.
-
-    If two distinct configs are ever passed (tests do this; production
-    rarely), the LRU eviction handles it correctly — each call still
-    returns a credential matching its config; only one is cached at a
-    time. Use :func:`reset_credential_cache` to clear (e.g. in tests).
-    """
-    return _build_default_credential(config)
-
-
-def build_token_provider(scope: Optional[str] = None,
-                         *,
-                         config: Optional[EntraIdentityConfig] = None,
-                         base_url: Optional[str] = None,
-                         exclude_interactive_browser: bool = True,
-                         ) -> Callable[[], str]:
-    """Return a zero-arg callable that mints a fresh Entra bearer JWT.
-
-    The returned callable is exactly what Microsoft's documented Foundry
-    sample expects::
-
-        from openai import OpenAI
-        client = OpenAI(
-            base_url="https://my-resource.openai.azure.com/openai/v1/",
-            api_key=build_token_provider(),
-        )
-
-    Scope resolution order:
-      1. ``config.scope`` when a config object is supplied
-      2. explicit ``scope`` kwarg
-      3. ``SCOPE_AI_AZURE_DEFAULT`` (Microsoft's documented Foundry scope)
-
-    ``base_url`` is unused today and kept for back-compat. Tenant /
-    service-principal / sovereign-cloud configuration flows through
-    ``azure-identity``'s standard ``AZURE_*`` environment variables —
-    see :func:`_build_default_credential` for the rationale.
-
-    NOT serializable across process boundaries. For multiprocessing
-    workers, serialize the ``EntraIdentityConfig`` and rebuild the
-    provider inside the worker.
-    """
-    ai = _require_azure_identity()
-    if config is None:
-        config = EntraIdentityConfig(
-            scope=scope or SCOPE_AI_AZURE_DEFAULT,
-            exclude_interactive_browser=exclude_interactive_browser,
-        )
-    credential = build_credential(config)
-    return ai.get_bearer_token_provider(credential, config.scope)
-
-
-# ---------------------------------------------------------------------------
-# Credential probing
-# ---------------------------------------------------------------------------
-
-
-def has_azure_identity_credentials(scope: Optional[str] = None,
-                                   *,
-                                   config: Optional[EntraIdentityConfig] = None,
-                                   timeout_seconds: float = 10.0,
-                                   allow_install: bool = True,
-                                   **overrides: Any) -> bool:
-    """Best-effort probe: can `DefaultAzureCredential` mint a token now?
-
-    Runs ``credential.get_token(scope)`` under a thread-based timeout so
-    a slow token service can't hang the caller. Returns False on any
-    error — never raises. Use for ``hermes doctor`` /
-    ``hermes auth status`` / wizard preflight.
-
-    ``allow_install``: when True (default) and ``azure-identity`` is not
-    importable, the adapter triggers the standard lazy-install path
-    (subject to ``security.allow_lazy_installs``) before probing. Set
-    False to make this strictly an "is installed?" check — used on hot
-    paths like CLI startup where we never want pip to run.
-
-    NOT used by ``is_provider_configured()`` — that path is structural
-    only (no token mint), so CLI startup doesn't pay this latency.
-    """
-    if not has_azure_identity_installed():
-        if not allow_install:
-            return False
-        try:
-            _require_azure_identity()
-        except ImportError as exc:
-            logger.debug("azure-identity lazy install unavailable: %s", exc)
-            return False
-    if config is None:
-        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
-        config = EntraIdentityConfig(scope=effective_scope, **overrides)
-
-    result = {"ok": False}
-
-    def _probe() -> None:
-        try:
-            credential = build_credential(config)
-            tok = credential.get_token(config.scope)
-            result["ok"] = bool(getattr(tok, "token", None))
-        except Exception as exc:
-            logger.debug("Entra credential probe failed: %s", exc)
-            result["ok"] = False
-
-    thread = threading.Thread(target=_probe, daemon=True)
-    thread.start()
-    thread.join(timeout=max(0.01, timeout_seconds))
-    if thread.is_alive():
-        logger.debug("Entra token service probe timed out after %ss", timeout_seconds)
-        return False
-    return bool(result.get("ok"))
-
-
-def describe_active_credential(config: Optional[EntraIdentityConfig] = None,
-                               *,
-                               scope: Optional[str] = None,
-                               timeout_seconds: float = 10.0,
-                               allow_install: bool = True,
-                               **overrides: Any) -> Dict[str, Any]:
-    """Return diagnostic info about the active credential chain.
-
-    Best-effort: runs ``get_token()`` and inspects what came back.
-    Designed for ``hermes doctor`` and the wizard preflight — never
-    raises, returns ``{"ok": False, "error": ...}`` on failure.
-
-    ``allow_install``: when True (default) and ``azure-identity`` is not
-    importable, the adapter triggers the standard lazy-install path
-    (subject to ``security.allow_lazy_installs``) before probing. The
-    install failure is surfaced as the diagnostic error when it fails.
-    Set False for hot CLI paths that should never trigger pip.
-
-    ``azure-identity`` doesn't expose the winning inner credential as
-    a public field, so we report a coarse picture (env vars present,
-    token expiry, claims-derived tenant) rather than the credential
-    class name. Users wanting the precise class can run with
-    ``AZURE_LOG_LEVEL=DEBUG``.
-    """
-    info: Dict[str, Any] = {"ok": False}
-    if not has_azure_identity_installed():
-        if not allow_install:
-            info["error"] = "azure-identity not installed"
-            info["hint"] = (
-                "pip install azure-identity (or rely on lazy install at "
-                "first use)"
-            )
-            return info
-        try:
-            _require_azure_identity()
-        except ImportError as exc:
-            info["error"] = str(exc) or "azure-identity not installed"
-            info["hint"] = (
-                "pip install azure-identity manually, or enable lazy "
-                "installs (security.allow_lazy_installs: true in "
-                "config.yaml)."
-            )
-            return info
-
-    if config is None:
-        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
-        config = EntraIdentityConfig(scope=effective_scope, **overrides)
-
-    info["scope"] = config.scope
-    # Tenant / authority / service-principal config flow through the
-    # standard ``AZURE_*`` env vars; surface them below.
-    if os.environ.get("AZURE_TENANT_ID", "").strip():
-        info["tenant_id_env"] = os.environ["AZURE_TENANT_ID"].strip()
-
-    # Surface which env-var sources are present without minting yet.
-    env_sources = []
-    if os.environ.get("AZURE_FEDERATED_TOKEN_FILE", "").strip():
-        env_sources.append("WorkloadIdentityCredential (AZURE_FEDERATED_TOKEN_FILE)")
-    if (os.environ.get("AZURE_CLIENT_ID", "").strip()
-            and os.environ.get("AZURE_CLIENT_SECRET", "").strip()
-            and os.environ.get("AZURE_TENANT_ID", "").strip()):
-        env_sources.append("EnvironmentCredential (client secret)")
-    if os.environ.get("IDENTITY_ENDPOINT", "").strip() or os.environ.get("MSI_ENDPOINT", "").strip():
-        env_sources.append("ManagedIdentityCredential (IDENTITY_ENDPOINT)")
-    info["env_sources"] = env_sources
-
-    # Now try minting.
-    result: Dict[str, Any] = {}
-
-    def _probe() -> None:
-        try:
-            credential = build_credential(config)
-            tok = credential.get_token(config.scope)
-            result["token"] = tok
-        except Exception as exc:
-            result["error"] = str(exc)
-
-    thread = threading.Thread(target=_probe, daemon=True)
-    thread.start()
-    thread.join(timeout=max(0.01, timeout_seconds))
-    if thread.is_alive():
-        info["error"] = f"Token probe timed out after {timeout_seconds:.0f}s"
-        info["hint"] = (
-            "DefaultAzureCredential can be slow when the token service is unreachable "
-            "or when az login state is stale. Try `az login` or set "
-            "AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET."
-        )
-        return info
-
-    if "error" in result:
-        info["error"] = result["error"]
-        return info
-
-    token = result.get("token")
-    if token is None:
-        info["error"] = "credential chain exhausted"
-        return info
-
-    info["ok"] = True
-    info["expires_on"] = getattr(token, "expires_on", None)
-    return info
-
-
-# ---------------------------------------------------------------------------
-# Consumer-side helpers — split by purpose to prevent accidental token
-# minting in logging / cache-key / dashboard paths.
-# ---------------------------------------------------------------------------
-
-
-def is_token_provider(value: Any) -> bool:
-    """Return True when ``value`` is a callable Entra token provider.
-
-    Used at the seams where a consumer must decide between
-    string-API-key semantics and bearer-callable semantics.
-    """
-    return callable(value) and not isinstance(value, str)
-
-
-def materialize_bearer_for_http(value: Any) -> str:
-    """Return a fresh Bearer JWT for a manual HTTP request.
-
-    Only call this at sites that must construct an ``Authorization``
-    header outside the OpenAI SDK (e.g. ``hermes_cli/azure_detect.py``).
-    Calls the callable exactly once and returns the resulting token.
-
-    **Anthropic SDK integration:** the Anthropic Python SDK does not
-    accept a ``Callable[[], str]`` for ``auth_token``. Instead,
-    :func:`build_bearer_http_client` returns an ``httpx.Client`` whose
-    request event hook calls this function and rewrites the
-    ``Authorization`` header per request — and that client is passed to
-    the Anthropic SDK via ``http_client=...``. See
-    :func:`agent.anthropic_adapter.build_anthropic_client` for the
-    consumer.
-
-    Raises ``ValueError`` if ``value`` is not a callable token provider
-    or non-empty string.
-    """
-    if is_token_provider(value):
-        token = value()
-        if not isinstance(token, str) or not token:
-            raise ValueError("token provider returned empty value")
-        return token
-    if isinstance(value, str) and value:
-        return value
-    raise ValueError("no usable api_key / token provider")
-
-
-def build_bearer_http_client(token_provider: Callable[[], str], **httpx_kwargs: Any) -> Any:
-    """Return an ``httpx.Client`` that mints a fresh Entra bearer JWT
-    per outbound request.
-
-    The Anthropic SDK (≤ 0.86.0 at the time of writing) stores
-    ``api_key`` / ``auth_token`` as static strings and computes the
-    ``Authorization`` header at construction time. To get per-request
-    token refresh (the Microsoft-recommended Foundry pattern for
-    callable bearer providers), we install an httpx ``request`` event
-    hook on a custom client and pass that client to the SDK via
-    ``http_client=...``. The hook:
-
-      1. Calls :func:`materialize_bearer_for_http` to mint a fresh JWT
-         (azure-identity caches internally — this is cheap when the
-         cached token is still valid).
-      2. Strips any pre-set ``Authorization`` / ``api-key`` /
-         ``x-api-key`` headers the SDK may have added (avoids
-         conflicting auth values).
-      3. Sets ``Authorization: Bearer <fresh-jwt>``.
-
-    ``token_provider`` must be a zero-arg callable returning a string —
-    typically the result of :func:`build_token_provider`.
-
-    ``httpx_kwargs`` are forwarded verbatim to ``httpx.Client(...)`` so
-    callers can attach a ``timeout``, ``transport``, ``proxy``, etc.
-
-    Raises ``ImportError`` if ``httpx`` is not installed (it is a
-    transitive dependency of both ``openai`` and ``anthropic`` SDKs, so
-    in practice always available when this helper is reached).
-    """
-    if not is_token_provider(token_provider):
-        raise ValueError(
-            "build_bearer_http_client requires a zero-arg callable "
-            "token provider"
-        )
-
-    try:
-        import httpx
-    except ImportError as exc:  # pragma: no cover — httpx ships with openai/anthropic
-        raise ImportError(
-            "httpx is required for Entra ID bearer auth on Microsoft Foundry "
-            "Anthropic-style endpoints. It is normally a transitive "
-            "dependency of the openai/anthropic SDKs."
-        ) from exc
-
-    def _inject_bearer(request: "httpx.Request") -> None:
-        try:
-            token = materialize_bearer_for_http(token_provider)
-        except ValueError as exc:
-            # Token provider failed (chain exhausted, token service unreachable,
-            # az login expired, etc.). Strip any auth headers the SDK
-            # may have set — including our own placeholder sentinel
-            # ``entra-id-bearer-via-http-hook`` from
-            # ``_build_anthropic_client_with_bearer_hook`` — so the
-            # outbound request hits Azure with NO Authorization rather
-            # than with the placeholder. Azure returns a clean 401
-            # "missing auth" that is easier to diagnose than a 401
-            # against the sentinel string, and the sentinel never
-            # appears in upstream access logs.
-            #
-            # Log at WARNING (not DEBUG) so the misconfiguration is
-            # visible at default log levels.
-            logger.warning(
-                "Bearer hook: Entra ID token provider returned empty (%s) "
-                "— stripping Authorization headers. Azure will respond 401. "
-                "Run `hermes doctor` or `az login` to recover.",
-                exc,
-            )
-            for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
-                request.headers.pop(header_name, None)
-            return
-        for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
-            request.headers.pop(header_name, None)
-        request.headers["Authorization"] = f"Bearer {token}"
-
-    return httpx.Client(
-        event_hooks={"request": [_inject_bearer]},
-        **httpx_kwargs,
-    )
-
-
-__all__ = [
-    "EntraIdentityConfig",
-    "SCOPE_AI_AZURE_DEFAULT",
-    "build_bearer_http_client",
-    "build_credential",
-    "build_token_provider",
-    "describe_active_credential",
-    "has_azure_identity_credentials",
-    "has_azure_identity_installed",
-    "is_token_provider",
-    "materialize_bearer_for_http",
-    "reset_credential_cache",
-]
@@ -1,991 +0,0 @@
-"""Background memory/skill review — fork the agent to evaluate the turn.
-
-After every turn, ``AIAgent.run_conversation`` may call
-:func:`spawn_background_review` to fire off a daemon thread that replays
-the conversation snapshot in a forked :class:`AIAgent` and asks itself
-"should any skill/memory be saved or updated?".  Writes go straight to
-the memory + skill stores.  Main conversation and prompt cache are never
-touched.
-
-The fork inherits the parent's live runtime (provider, model, base_url,
-credentials, cached system prompt) so it hits the same prefix cache and
-uses the same auth.  It runs with a tool whitelist limited to memory and
-skill management tools; everything else is denied at runtime.
-
-See the ``hermes-agent-dev`` skill (``references/self-improvement-loop.md``)
-for invariants and PR review criteria.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-from typing import Any, Dict, List, Optional
-
-from agent.thread_scoped_output import thread_scoped_silence
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Background-review aux-model selector + routed digest.
-#
-# The review fork runs on the MAIN model by default ("auto"), replaying the
-# full conversation — already warm in the prompt cache, so cheap cache reads.
-# Optimal and unchanged. A user can route the review to a different, cheaper
-# model via auxiliary.background_review.{provider,model}. A different model
-# cannot reuse the parent's cache (different key), so the fork is cold
-# regardless — replaying the full transcript would just cold-write it. So when
-# (and only when) routed to a different model, we replay a compact DIGEST to
-# minimise cold-written tokens. Same model -> full replay; different model ->
-# digest. That's the whole policy.
-# ---------------------------------------------------------------------------
-
-
-def _resolve_review_runtime(agent: Any) -> Dict[str, Any]:
-    """Resolve provider/model/credentials for the review fork.
-
-    Default (auto / unset / same as parent): inherit the parent's live runtime
-    (with codex_app_server -> codex_responses downgrade). ``routed`` is False —
-    the fork uses the main model and the warm cache, exactly as before. When
-    ``auxiliary.background_review.{provider,model}`` names a concrete model
-    different from the parent's, resolve that runtime and set ``routed=True``.
-    """
-    parent_runtime = agent._current_main_runtime()
-    parent_api_mode = parent_runtime.get("api_mode") or None
-    if parent_api_mode == "codex_app_server":
-        parent_api_mode = "codex_responses"
-    parent = {
-        "provider": agent.provider,
-        "model": agent.model,
-        "api_key": parent_runtime.get("api_key") or None,
-        "base_url": parent_runtime.get("base_url") or None,
-        "api_mode": parent_api_mode,
-        "credential_pool": getattr(agent, "_credential_pool", None),
-        "request_overrides": dict(getattr(agent, "request_overrides", {}) or {}),
-        "max_tokens": getattr(agent, "max_tokens", None),
-        "command": getattr(agent, "acp_command", None),
-        "args": list(getattr(agent, "acp_args", []) or []),
-        "routed": False,
-    }
-    try:
-        from hermes_cli.config import load_config
-        cfg = load_config()
-    except Exception:
-        return parent
-    aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
-    task = aux.get("background_review", {}) if isinstance(aux.get("background_review"), dict) else {}
-    task_provider = (str(task.get("provider", "")).strip() or None)
-    task_model = (str(task.get("model", "")).strip() or None)
-    task_base_url = (str(task.get("base_url", "")).strip() or None)
-    task_api_key = (str(task.get("api_key", "")).strip() or None)
-    if not (task_provider and task_provider != "auto" and task_model):
-        return parent
-    if task_provider == (agent.provider or "") and task_model == (agent.model or ""):
-        return parent  # same model/provider as parent -> not routed
-    try:
-        from hermes_cli.runtime_provider import resolve_runtime_provider
-        rp = resolve_runtime_provider(
-            requested=task_provider,
-            target_model=task_model,
-            explicit_api_key=task_api_key,
-            explicit_base_url=task_base_url,
-        )
-        return {
-            "provider": rp.get("provider") or task_provider,
-            "model": rp.get("model") or task_model,
-            "api_key": rp.get("api_key"),
-            "base_url": rp.get("base_url"),
-            "api_mode": rp.get("api_mode"),
-            "credential_pool": rp.get("credential_pool"),
-            "request_overrides": dict(rp.get("request_overrides") or {}),
-            "max_tokens": rp.get("max_output_tokens"),
-            "command": rp.get("command"),
-            "args": list(rp.get("args") or []),
-            "routed": True,
-        }
-    except Exception as e:
-        logger.debug("background-review aux routing failed (%s); using main model", e)
-        return parent
-
-
-def _msg_text(m: Dict) -> str:
-    c = m.get("content")
-    if isinstance(c, str):
-        return c.strip()
-    if isinstance(c, list):
-        return " ".join(b.get("text", "") for b in c if isinstance(b, dict)).strip()
-    return ""
-
-
-def _digest_history(messages_snapshot: List[Dict], tail: int = 24) -> List[Dict]:
-    """Compact replay for the routed (different-model) path only.
-
-    Keeps the recent ``tail`` messages verbatim, collapses older turns into one
-    synthetic user-role digest, preserving role alternation. Used ONLY when
-    routed to a different model (cache cold regardless, so fewer cold-written
-    tokens is a pure win). Never on the main-model path (full replay stays warm).
-    """
-    msgs = list(messages_snapshot or [])
-    if len(msgs) <= tail:
-        return msgs
-    keep = msgs[-tail:]
-    while keep and isinstance(keep[0], dict) and keep[0].get("role") == "tool":
-        tail += 1
-        if len(msgs) <= tail:
-            return msgs
-        keep = msgs[-tail:]
-    old = msgs[:-len(keep)]
-    lines: List[str] = []
-    for m in old:
-        if not isinstance(m, dict):
-            continue
-        role = m.get("role")
-        text = _msg_text(m).replace("\n", " ")
-        if role == "user" and text:
-            lines.append(f"USER: {text[:300]}")
-        elif role == "assistant":
-            tcs = m.get("tool_calls") or []
-            if tcs:
-                names = [(tc.get("function") or {}).get("name", "?") for tc in tcs if isinstance(tc, dict)]
-                lines.append(f"ASSISTANT[tools: {', '.join(names)}]")
-            if text:
-                lines.append(f"ASSISTANT: {text[:200]}")
-    digest = {
-        "role": "user",
-        "content": (
-            "[Earlier conversation digest — older turns summarised to bound the "
-            "review's cold-write cost on the routed aux model. Recent turns "
-            "follow verbatim below.]\n" + "\n".join(lines)
-        ),
-    }
-    return [digest] + keep
-
-
-# Review-prompt strings — used by ``spawn_background_review_thread`` to build
-# the user-message that the forked review agent receives.  AIAgent exposes
-# them as class attributes (``_MEMORY_REVIEW_PROMPT`` etc.) for back-compat;
-# the actual text lives here so future edits are one-place.
-_MEMORY_REVIEW_PROMPT = (
-    "Review the conversation above and consider saving to memory if appropriate.\n\n"
-    "Focus on:\n"
-    "1. Has the user revealed things about themselves — their persona, desires, "
-    "preferences, or personal details worth remembering?\n"
-    "2. Has the user expressed expectations about how you should behave, their work "
-    "style, or ways they want you to operate?\n\n"
-    "If something stands out, save it using the memory tool. "
-    "If nothing is worth saving, just say 'Nothing to save.' and stop."
-)
-
-_SKILL_REVIEW_PROMPT = (
-    "Review the conversation above and update the skill library. Be "
-    "ACTIVE — most sessions produce at least one skill update, even if "
-    "small. A pass that does nothing is a missed learning opportunity, "
-    "not a neutral outcome.\n\n"
-    "Target shape of the library: CLASS-LEVEL skills, each with a rich "
-    "SKILL.md and a `references/` directory for session-specific detail. "
-    "Not a long flat list of narrow one-session-one-skill entries. This "
-    "shapes HOW you update, not WHETHER you update.\n\n"
-    "Signals to look for (any one of these warrants action):\n"
-    "  • User corrected your style, tone, format, legibility, or "
-    "verbosity. Frustration signals like 'stop doing X', 'this is too "
-    "verbose', 'don't format like this', 'why are you explaining', "
-    "'just give me the answer', 'you always do Y and I hate it', or an "
-    "explicit 'remember this' are FIRST-CLASS skill signals, not just "
-    "memory signals. Update the relevant skill(s) to embed the "
-    "preference so the next session starts already knowing.\n"
-    "  • User corrected your workflow, approach, or sequence of steps. "
-    "Encode the correction as a pitfall or explicit step in the skill "
-    "that governs that class of task.\n"
-    "  • Non-trivial technique, fix, workaround, debugging path, or "
-    "tool-usage pattern emerged that a future session would benefit "
-    "from. Capture it.\n"
-    "  • A skill that got loaded or consulted this session turned out "
-    "to be wrong, missing a step, or outdated. Patch it NOW.\n\n"
-    "Preference order — prefer the earliest action that fits, but do "
-    "pick one when a signal above fired:\n"
-    "  1. UPDATE A CURRENTLY-LOADED SKILL. Look back through the "
-    "conversation for skills the user loaded via /skill-name or you "
-    "read via skill_view. If any of them covers the territory of the "
-    "new learning, PATCH that one first. It is the skill that was in "
-    "play, so it's the right one to extend.\n"
-    "  2. UPDATE AN EXISTING UMBRELLA (via skills_list + skill_view). "
-    "If no loaded skill fits but an existing class-level skill does, "
-    "patch it. Add a subsection, a pitfall, or broaden a trigger.\n"
-    "  3. ADD A SUPPORT FILE under an existing umbrella. Skills can be "
-    "packaged with three kinds of support files — use the right "
-    "directory per kind:\n"
-    "     • `references/<topic>.md` — session-specific detail (error "
-    "transcripts, reproduction recipes, provider quirks) AND "
-    "condensed knowledge banks: quoted research, API docs, external "
-    "authoritative excerpts, or domain notes you found while working "
-    "on the problem. Write it concise and for the value of the task, "
-    "not as a full mirror of upstream docs.\n"
-    "     • `templates/<name>.<ext>` — starter files meant to be "
-    "copied and modified (boilerplate configs, scaffolding, a "
-    "known-good example the agent can `reproduce with modifications`).\n"
-    "     • `scripts/<name>.<ext>` — statically re-runnable actions "
-    "the skill can invoke directly (verification scripts, fixture "
-    "generators, deterministic probes, anything the agent should run "
-    "rather than hand-type each time).\n"
-    "     Add support files via skill_manage action=write_file with "
-    "file_path starting 'references/', 'templates/', or 'scripts/'. "
-    "The umbrella's SKILL.md should gain a one-line pointer to any "
-    "new support file so future agents know it exists.\n"
-    "  4. CREATE A NEW CLASS-LEVEL UMBRELLA SKILL when no existing "
-    "skill covers the class. The name MUST be at the class level. "
-    "The name MUST NOT be a specific PR number, error string, feature "
-    "codename, library-alone name, or 'fix-X / debug-Y / audit-Z-today' "
-    "session artifact. If the proposed name only makes sense for "
-    "today's task, it's wrong — fall back to (1), (2), or (3).\n\n"
-    "User-preference embedding (important): when the user expressed a "
-    "style/format/workflow preference, the update belongs in the "
-    "SKILL.md body, not just in memory. Memory captures 'who the user "
-    "is and what the current situation and state of your operations "
-    "are'; skills capture 'how to do this class of task for this "
-    "user'. When they complain about how you handled a task, the "
-    "skill that governs that task needs to carry the lesson.\n\n"
-    "If you notice two existing skills that overlap, note it in your "
-    "reply — the background curator handles consolidation at scale.\n\n"
-    "Protected skills (DO NOT edit these):\n"
-    "  • Bundled skills (shipped with Hermes, e.g. 'hermes-agent').\n"
-    "  • Hub-installed skills (installed via 'hermes skills install').\n"
-    "Pinned skills (marked via 'hermes curator pin') CAN be improved — "
-    "pin only blocks deletion/archive/consolidation by the curator, not "
-    "content updates. Patch them when a pitfall or missing step turns up, "
-    "same as any other agent-created skill.\n"
-    "If the only skills that need updating are protected, say\n"
-    "'Nothing to save.' and stop.\n\n"
-    "Do NOT capture (these become persistent self-imposed constraints "
-    "that bite you later when the environment changes):\n"
-    "  • Environment-dependent failures: missing binaries, fresh-install "
-    "errors, post-migration path mismatches, 'command not found', "
-    "unconfigured credentials, uninstalled packages. The user can fix "
-    "these — they are not durable rules.\n"
-    "  • Negative claims about tools or features ('browser tools do not "
-    "work', 'X tool is broken', 'cannot use Y from execute_code'). These "
-    "harden into refusals the agent cites against itself for months "
-    "after the actual problem was fixed.\n"
-    "  • Session-specific transient errors that resolved before the "
-    "conversation ended. If retrying worked, the lesson is the retry "
-    "pattern, not the original failure.\n"
-    "  • One-off task narratives. A user asking 'summarize today's "
-    "market' or 'analyze this PR' is not a class of work that warrants "
-    "a skill.\n\n"
-    "If a tool failed because of setup state, capture the FIX (install "
-    "command, config step, env var to set) under an existing setup or "
-    "troubleshooting skill — never 'this tool does not work' as a "
-    "standalone constraint.\n\n"
-    "'Nothing to save.' is a real option but should NOT be the "
-    "default. If the session ran smoothly with no corrections and "
-    "produced no new technique, just say 'Nothing to save.' and stop. "
-    "Otherwise, act."
-)
-
-_COMBINED_REVIEW_PROMPT = (
-    "Review the conversation above and update two things:\n\n"
-    "**Memory**: who the user is. Did the user reveal persona, "
-    "desires, preferences, personal details, or expectations about "
-    "how you should behave? Save facts about the user and durable "
-    "preferences with the memory tool.\n\n"
-    "**Skills**: how to do this class of task. Be ACTIVE — most "
-    "sessions produce at least one skill update. A pass that does "
-    "nothing is a missed learning opportunity, not a neutral outcome.\n\n"
-    "Target shape of the skill library: CLASS-LEVEL skills with a rich "
-    "SKILL.md and a `references/` directory for session-specific detail. "
-    "Not a long flat list of narrow one-session-one-skill entries.\n\n"
-    "Signals that warrant a skill update (any one is enough):\n"
-    "  • User corrected your style, tone, format, legibility, "
-    "verbosity, or approach. Frustration is a FIRST-CLASS skill "
-    "signal, not just a memory signal. 'stop doing X', 'don't format "
-    "like this', 'I hate when you Y' — embed the lesson in the skill "
-    "that governs that task so the next session starts fixed.\n"
-    "  • Non-trivial technique, fix, workaround, or debugging path "
-    "emerged.\n"
-    "  • A skill that was loaded or consulted turned out wrong, "
-    "missing, or outdated — patch it now.\n\n"
-    "Preference order for skills — pick the earliest that fits:\n"
-    "  1. UPDATE A CURRENTLY-LOADED SKILL. Check what skills were "
-    "loaded via /skill-name or skill_view in the conversation. If one "
-    "of them covers the learning, PATCH it first. It was in play; "
-    "it's the right place.\n"
-    "  2. UPDATE AN EXISTING UMBRELLA (skills_list + skill_view to "
-    "find the right one). Patch it.\n"
-    "  3. ADD A SUPPORT FILE under an existing umbrella via "
-    "skill_manage action=write_file. Three kinds: "
-    "`references/<topic>.md` for session-specific detail OR condensed "
-    "knowledge banks (quoted research, API docs excerpts, domain "
-    "notes) written concise and task-focused; `templates/<name>.<ext>` "
-    "for starter files meant to be copied and modified; "
-    "`scripts/<name>.<ext>` for statically re-runnable actions "
-    "(verification, fixture generators, probes). Add a one-line "
-    "pointer in SKILL.md so future agents find them.\n"
-    "  4. CREATE A NEW CLASS-LEVEL UMBRELLA when nothing exists. "
-    "Name at the class level — NOT a PR number, error string, "
-    "codename, library-alone name, or 'fix-X / debug-Y' session "
-    "artifact. If the name only fits today's task, fall back to (1), "
-    "(2), or (3).\n\n"
-    "User-preference embedding: when the user complains about how "
-    "you handled a task, update the skill that governs that task — "
-    "memory alone isn't enough. Memory says 'who the user is and "
-    "what the current situation and state of your operations are'; "
-    "skills say 'how to do this class of task for this user'. Both "
-    "should carry user-preference lessons when relevant.\n\n"
-    "If you notice overlapping existing skills, mention it — the "
-    "background curator handles consolidation.\n\n"
-    "Protected skills (DO NOT edit these):\n"
-    "  • Bundled skills (shipped with Hermes, e.g. 'hermes-agent').\n"
-    "  • Hub-installed skills (installed via 'hermes skills install').\n"
-    "Pinned skills (marked via 'hermes curator pin') CAN be improved — "
-    "pin only blocks deletion/archive/consolidation by the curator, not "
-    "content updates. Patch them when a pitfall or missing step turns up, "
-    "same as any other agent-created skill.\n"
-    "If the only skills that need updating are protected, say\n"
-    "'Nothing to save.' and stop.\n\n"
-    "Do NOT capture as skills (these become persistent self-imposed "
-    "constraints that bite you later when the environment changes):\n"
-    "  • Environment-dependent failures: missing binaries, fresh-install "
-    "errors, post-migration path mismatches, 'command not found', "
-    "unconfigured credentials, uninstalled packages. The user can fix "
-    "these — they are not durable rules.\n"
-    "  • Negative claims about tools or features ('browser tools do not "
-    "work', 'X tool is broken', 'cannot use Y from execute_code'). These "
-    "harden into refusals the agent cites against itself for months "
-    "after the actual problem was fixed.\n"
-    "  • Session-specific transient errors that resolved before the "
-    "conversation ended. If retrying worked, the lesson is the retry "
-    "pattern, not the original failure.\n"
-    "  • One-off task narratives. A user asking 'summarize today's "
-    "market' or 'analyze this PR' is not a class of work that warrants "
-    "a skill.\n\n"
-    "If a tool failed because of setup state, capture the FIX (install "
-    "command, config step, env var to set) under an existing setup or "
-    "troubleshooting skill — never 'this tool does not work' as a "
-    "standalone constraint.\n\n"
-    "Act on whichever of the two dimensions has real signal. If "
-    "genuinely nothing stands out on either, say 'Nothing to save.' "
-    "and stop — but don't reach for that conclusion as a default."
-)
-
-
-
-def summarize_background_review_actions(
-    review_messages: List[Dict],
-    prior_snapshot: List[Dict],
-    notification_mode: str = "on",
-) -> List[str]:
-    """Build the human-facing action summary for a background review pass.
-
-    Walks the review agent's session messages and collects successful memory
-    and skill-management actions to surface to the user. Tool messages already
-    present in ``prior_snapshot`` are skipped so stale inherited results are
-    not re-surfaced as fresh background work (issue #14944).
-
-    ``notification_mode`` controls display detail:
-    - ``off``: return no actions.
-    - ``on``: generic "Memory updated"/tool messages.
-    - ``verbose``: include compact content previews from tool-call arguments.
-    """
-    mode = str(notification_mode or "on").lower()
-    if mode == "off":
-        return []
-    verbose = mode == "verbose"
-
-    existing_tool_call_ids = set()
-    existing_tool_contents = set()
-    for prior in prior_snapshot or []:
-        if not isinstance(prior, dict) or prior.get("role") != "tool":
-            continue
-        tcid = prior.get("tool_call_id")
-        if tcid:
-            existing_tool_call_ids.add(tcid)
-        else:
-            content = prior.get("content")
-            if isinstance(content, str):
-                existing_tool_contents.add(content)
-
-    # Map review-agent tool results back to the calls that produced them.  The
-    # result JSON only says "Entry added"; the call arguments contain action,
-    # target, and content previews.  Restricting to notify_tools also prevents
-    # helper tools from surfacing as memory work just because they succeeded.
-    notify_tools = {"memory", "skill_manage"}
-    all_tool_call_ids: set = set()
-    call_details: dict = {}
-    for msg in review_messages or []:
-        if not isinstance(msg, dict) or msg.get("role") != "assistant":
-            continue
-        for tc in msg.get("tool_calls", []) or []:
-            if not isinstance(tc, dict):
-                continue
-            fn = tc.get("function", {}) or {}
-            fn_name = fn.get("name", "")
-            tcid = tc.get("id")
-            if tcid:
-                all_tool_call_ids.add(tcid)
-            if fn_name not in notify_tools:
-                continue
-            try:
-                args = json.loads(fn.get("arguments", "{}"))
-            except (json.JSONDecodeError, TypeError):
-                args = {}
-            if tcid:
-                call_details[tcid] = {
-                    "tool": fn_name,
-                    "action": args.get("action", "?"),
-                    "target": args.get("target", "memory"),
-                    "content": args.get("content", ""),
-                    "old_text": args.get("old_text", ""),
-                    "operations": args.get("operations") or [],
-                    "name": args.get("name", ""),
-                    "old_string": args.get("old_string", ""),
-                    "new_string": args.get("new_string", ""),
-                }
-
-    actions: List[str] = []
-    for msg in review_messages or []:
-        if not isinstance(msg, dict) or msg.get("role") != "tool":
-            continue
-        tcid = msg.get("tool_call_id")
-        if tcid and tcid in existing_tool_call_ids:
-            continue
-        if not tcid:
-            content_str = msg.get("content")
-            if isinstance(content_str, str) and content_str in existing_tool_contents:
-                continue
-        if tcid and all_tool_call_ids and tcid not in call_details:
-            continue
-        try:
-            data = json.loads(msg.get("content", "{}"))
-        except (json.JSONDecodeError, TypeError):
-            continue
-        # ``data`` may not be a dict — some memory/skill tool responses in
-        # older codepaths or wrapper MCP servers return a top-level JSON
-        # list (e.g. ``[{"success": true, ...}]``) or a scalar.  The original
-        # isinstance check below silently skips non-dict payloads, which
-        # is correct, but ``data.get("_change")`` further down can still
-        # hand back a list and break ``change.get("description", "")``.
-        # Defensively normalize everything through a dict-typed alias so
-        # the rest of the function can stay terse without per-call
-        # ``isinstance`` guards (#59437).
-        if not isinstance(data, dict) or not data.get("success"):
-            continue
-        message = data.get("message", "")
-        detail = call_details.get(tcid) or {}
-        if not isinstance(detail, dict):
-            detail = {}
-        target = data.get("target", "") or detail.get("target", "")
-        is_skill = detail.get("tool") == "skill_manage"
-
-        message_lower = message.lower()
-        if not verbose:
-            if "created" in message_lower:
-                actions.append(message)
-                continue
-            if "updated" in message_lower:
-                actions.append(message)
-                continue
-            if is_skill and "patched" in message_lower:
-                actions.append(message)
-                continue
-
-        if is_skill:
-            label = "Skill"
-        elif target:
-            label = "Memory" if target == "memory" else "User profile" if target == "user" else target
-        else:
-            continue
-
-        if verbose:
-            action = detail.get("action", "")
-            content = detail.get("content", "")
-            old_text = detail.get("old_text", "")
-            skill_name = detail.get("name", "")
-            # ``operations`` may be anything callable put into the JSON
-            # arguments.  Anything non-iterable that isn't a list[str]
-            # of dicts becomes unusable here, so coerce defensively.
-            ops_raw = detail.get("operations")
-            operations: list = (
-                ops_raw if isinstance(ops_raw, list) else []
-            )
-            max_preview = 120
-            if is_skill:
-                # ``_change`` is a free-form dict the skill tool leaves in
-                # the response.  Older / wrapper MCP backends return it
-                # as a list, an int, or a JSON-shaped scalar — normalize
-                # to a dict so the .get() calls downstream don't
-                # AttributeError (#59437).
-                change_raw = data.get("_change")
-                change: dict = (
-                    change_raw if isinstance(change_raw, dict) else {}
-                )
-                old_string = (
-                    change.get("old", "") or detail.get("old_string", "")
-                )
-                new_string = (
-                    change.get("new", "") or detail.get("new_string", "")
-                )
-                description = change.get("description", "")
-                if action == "patch" and (old_string or new_string):
-                    old_preview = old_string[:80].replace("\n", " ") + (
-                        "…" if len(old_string) > 80 else ""
-                    )
-                    new_preview = new_string[:80].replace("\n", " ") + (
-                        "…" if len(new_string) > 80 else ""
-                    )
-                    actions.append(
-                        f"📝 Skill '{skill_name}' patched: "
-                        f"\"{old_preview}\" → \"{new_preview}\""
-                    )
-                elif action == "create" and description:
-                    actions.append(f"📝 Skill '{skill_name}' created: {description}")
-                elif action == "edit" and description:
-                    actions.append(f"📝 Skill '{skill_name}' rewritten: {description}")
-                else:
-                    actions.append(f"📝 {message}" if message else f"Skill {action}")
-            elif operations:
-                for op in operations:
-                    # Each element must be a dict-of-fields; some
-                    # legacy codepaths serialize the entry as a bare
-                    # string and the message dict doesn't exist.  Skip
-                    # non-dict items defensively — they have no
-                    # actionable fields anyway (#59437).
-                    if not isinstance(op, dict):
-                        continue
-                    op_act = op.get("action", "")
-                    op_content = (op.get("content") or "")
-                    op_old = (op.get("old_text") or "")
-                    if op_act == "add" and op_content:
-                        preview = op_content[:max_preview] + ("…" if len(op_content) > max_preview else "")
-                        actions.append(f"{label} ➕ {preview}")
-                    elif op_act == "replace" and op_content:
-                        preview = op_content[:max_preview] + ("…" if len(op_content) > max_preview else "")
-                        actions.append(f"{label} ✏️ {preview}")
-                    elif op_act == "remove" and op_old:
-                        preview = op_old[:60] + ("…" if len(op_old) > 60 else "")
-                        actions.append(f"{label} ➖ {preview}")
-            elif action == "add" and content:
-                preview = content[:max_preview] + ("…" if len(content) > max_preview else "")
-                actions.append(f"{label} ➕ {preview}")
-            elif action == "replace" and content:
-                preview = content[:max_preview] + ("…" if len(content) > max_preview else "")
-                actions.append(f"{label} ✏️ {preview}")
-            elif action == "remove" and old_text:
-                preview = old_text[:60] + ("…" if len(old_text) > 60 else "")
-                actions.append(f"{label} ➖ {preview}")
-            else:
-                actions.append(f"{label} updated")
-        elif (
-            "added" in message_lower
-            or "replaced" in message_lower
-            or "removed" in message_lower
-            or "applied" in message_lower
-            or (target and "add" in message.lower())
-            or "Entry added" in message
-        ):
-            actions.append(f"{label} updated")
-    return actions
-
-
-def build_memory_write_metadata(
-    agent: Any,
-    *,
-    write_origin: Optional[str] = None,
-    execution_context: Optional[str] = None,
-    task_id: Optional[str] = None,
-    tool_call_id: Optional[str] = None,
-) -> Dict[str, Any]:
-    """Build provenance metadata for external memory-provider mirrors."""
-    metadata: Dict[str, Any] = {
-        "write_origin": write_origin or getattr(agent, "_memory_write_origin", "assistant_tool"),
-        "execution_context": (
-            execution_context
-            or getattr(agent, "_memory_write_context", "foreground")
-        ),
-        "session_id": agent.session_id or "",
-        "parent_session_id": agent._parent_session_id or "",
-        "platform": agent.platform or os.environ.get("HERMES_SESSION_SOURCE", "cli"),
-        "tool_name": "memory",
-    }
-    if task_id:
-        metadata["task_id"] = task_id
-    if tool_call_id:
-        metadata["tool_call_id"] = tool_call_id
-    return {k: v for k, v in metadata.items() if v not in {None, ""}}
-
-
-def _run_review_in_thread(
-    agent: Any,
-    messages_snapshot: List[Dict],
-    prompt: str,
-) -> None:
-    """Worker function executed in the background-review daemon thread.
-
-    Spawns a forked ``AIAgent`` inheriting the parent's runtime, runs the
-    review prompt, and surfaces a compact action summary back to the user
-    via ``agent._safe_print`` and ``agent.background_review_callback``.
-    """
-    # Local import to avoid a hard circular dep at module load.
-    from run_agent import AIAgent
-    from tools.terminal_tool import set_approval_callback as _set_approval_callback
-
-    # Install a non-interactive approval callback on this worker
-    # thread so any dangerous-command guard the review agent trips
-    # resolves to "deny" instead of falling back to input() -- which
-    # deadlocks against the parent's prompt_toolkit TUI (#15216).
-    # Same pattern as _subagent_auto_deny in tools/delegate_tool.py.
-    def _bg_review_auto_deny(command, description, **kwargs):
-        logger.warning(
-            "Background review auto-denied dangerous command: %s (%s)",
-            command, description,
-        )
-        return "deny"
-    try:
-        _set_approval_callback(_bg_review_auto_deny)
-    except Exception:
-        pass
-
-    review_agent = None
-    review_messages: List[Dict] = []
-    try:
-        # Silence stdout/stderr for THIS worker thread only.  A process-global
-        # ``contextlib.redirect_stdout(devnull)`` here would also blank
-        # ``sys.stdout``/``sys.stderr`` for every other thread — including a
-        # gateway event-loop thread driving a Telegram long-poll — for the full
-        # duration of the review (tens of seconds), swallowing their console
-        # output (#55769 / #55925).  ``thread_scoped_silence`` routes only this
-        # thread's writes to devnull and leaves all other threads on the real
-        # streams.
-        with thread_scoped_silence():
-            # Inherit the parent agent's live runtime (provider, model,
-            # base_url, api_key, api_mode) so the fork uses the exact
-            # same credentials the main turn is using.  Without this,
-            # AIAgent.__init__ re-runs auto-resolution from env vars,
-            # which fails for OAuth-only providers, session-scoped
-            # creds, or credential-pool setups where the resolver can't
-            # reconstruct auth from scratch -- producing the spurious
-            # "No LLM provider configured" warning at end of turn.
-            # _resolve_review_runtime() returns the parent's live runtime by
-            # default (routed=False; main model, warm cache), or — when the user
-            # set auxiliary.background_review.{provider,model} to a different
-            # model — that model's runtime (routed=True). The codex_app_server
-            # -> codex_responses downgrade is applied inside the resolver.
-            _rt = _resolve_review_runtime(agent)
-            _routed = bool(_rt.get("routed"))
-            # skip_memory=True keeps the review fork from
-            # touching external memory plugins (honcho, mem0,
-            # supermemory, etc.).  Without it, the fork's
-            # __init__ rebuilds its own _memory_manager from
-            # config, scoped to the parent's session_id, and
-            # run_conversation() then leaks the harness prompt
-            # into the user's real memory namespace via three
-            # ingestion sites: on_turn_start (cadence + turn
-            # message), prefetch_all (recall query), and
-            # sync_all (harness prompt + review output recorded
-            # as a (user, assistant) turn pair).  Built-in
-            # MEMORY.md / USER.md state is re-bound from the
-            # parent below so memory(action="add") writes from
-            # the review still land on disk; the review just
-            # has zero side effects on external providers.
-            # Match parent's toolset config so ``tools[]`` is byte-identical
-            # in the request body — Anthropic's cache key includes it.
-            # (The runtime whitelist below still restricts dispatch.)
-            _fork_kwargs: Dict[str, Any] = {}
-            if isinstance(_rt.get("max_tokens"), int):
-                _fork_kwargs["max_tokens"] = _rt["max_tokens"]
-            if isinstance(_rt.get("command"), str) and _rt["command"]:
-                _fork_kwargs["acp_command"] = _rt["command"]
-                _fork_kwargs["acp_args"] = _rt.get("args") or []
-            # Match parent's reasoning config so the fork's ``thinking`` /
-            # ``output_config`` are byte-identical in the request body —
-            # Anthropic's cache key is namespaced by ``thinking`` presence.
-            # Same-model path only: when routed to a different aux model the
-            # cache is cold regardless (parity buys nothing) and the parent's
-            # effort vocabulary may not be valid for the routed model/provider
-            # (e.g. OpenRouter ``extra_body.reasoning.effort`` is forwarded
-            # unclamped; codex_responses passes ``max``/``ultra`` through
-            # unmapped except on gpt-5.6/xAI). Let the routed fork use
-            # provider defaults — matching the ``not _routed`` gate on
-            # _cached_system_prompt below.
-            if not _routed:
-                _fork_kwargs["reasoning_config"] = getattr(agent, "reasoning_config", None)
-            review_agent = AIAgent(
-                model=_rt.get("model") or agent.model,
-                max_iterations=16,
-                quiet_mode=True,
-                platform=agent.platform,
-                provider=_rt.get("provider") or agent.provider,
-                api_mode=_rt.get("api_mode"),
-                base_url=_rt.get("base_url") or None,
-                api_key=_rt.get("api_key") or None,
-                credential_pool=_rt.get("credential_pool"),
-                request_overrides=_rt.get("request_overrides") or {},
-                parent_session_id=agent.session_id,
-                enabled_toolsets=getattr(agent, "enabled_toolsets", None),
-                disabled_toolsets=getattr(agent, "disabled_toolsets", None),
-                skip_memory=True,
-                **_fork_kwargs,
-            )
-            review_agent._memory_write_origin = "background_review"
-            review_agent._memory_write_context = "background_review"
-            # The review fork pins the parent's cached system prompt and keeps
-            # ``tools[]`` byte-identical to the parent so its outbound request
-            # hits the same provider cache prefix (see the toolset-parity note
-            # above). The between-turns MCP refresh in build_turn_context would
-            # add late-connecting MCP tools to this fork and break that parity,
-            # so opt the review fork out of it.
-            review_agent._skip_mcp_refresh = True
-            review_agent._memory_store = agent._memory_store
-            review_agent._memory_enabled = agent._memory_enabled
-            review_agent._user_profile_enabled = agent._user_profile_enabled
-            review_agent._memory_nudge_interval = 0
-            review_agent._skill_nudge_interval = 0
-            # PERSISTENCE ISOLATION (the curator-takeover root cause): the fork
-            # shares the parent's session_id (set below, for prompt-cache
-            # warmth), so without this it would write its harness turn ("Review
-            # the conversation above and update the skill library…") + its own
-            # response straight into the user's REAL session in state.db. On the
-            # user's next live turn the agent re-reads that injected user message
-            # as a standing instruction and "becomes" the curator, refusing the
-            # actual task. _persist_disabled hard-stops every DB write/lazy-open
-            # path (_flush_messages_to_session_db, _ensure_db_session,
-            # _get_session_db_for_recall); the review writes only to the skill
-            # and memory stores via its tools, which is all it needs.
-            review_agent._persist_disabled = True
-            review_agent._session_db = None
-            review_agent._session_json_enabled = False
-            # Suppress all status/warning emits from the fork so the
-            # user only sees the final successful-action summary.
-            # Without this, mid-review "Iteration budget exhausted",
-            # rate-limit retries, compression warnings, and other
-            # lifecycle messages bubble up through _emit_status ->
-            # _vprint and leak past the stdout redirect (they go via
-            # _print_fn/status_callback, which bypass sys.stdout).
-            review_agent.suppress_status_output = True
-            # Inherit the parent's cached system prompt verbatim so
-            # the review fork's outbound HTTP request hits the same
-            # Anthropic/OpenRouter prefix cache the parent warmed.
-            # Without this, the fork rebuilds the system prompt from
-            # scratch (fresh _hermes_now() timestamp, fresh
-            # session_id, narrower toolset → different skills_prompt)
-            # and the byte-exact prefix-cache key misses. See
-            # issue #25322 and PR #17276 for the full analysis +
-            # measured impact (~26% end-to-end cost reduction on
-            # Sonnet 4.5).
-            # Share the parent's warm cached system prompt ONLY when the review
-            # runs on the SAME model (not routed). When routed to a different
-            # model the parent's cached prompt is for the wrong model/cache key
-            # and would miss anyway, so let the routed fork build its own.
-            if not _routed:
-                review_agent._cached_system_prompt = agent._cached_system_prompt
-                # Defensive: pin session_start + session_id to the
-                # parent's so any code path that re-renders parts of
-                # the system prompt (compression, plugin hooks) still
-                # produces byte-identical output. The cached-prompt
-                # assignment above already short-circuits the normal
-                # rebuild path, but these pins guarantee parity even
-                # if a future code path bypasses the cache.
-                review_agent.session_start = agent.session_start
-            review_agent.session_id = agent.session_id
-            # The fork shares the parent's live session_id (pinned above for
-            # prefix-cache parity). It is single-lifecycle and calls close()
-            # right after this run_conversation(); without opting out, close()
-            # would finalize the parent's still-active session row mid
-            # conversation (the review fires every ~10 turns). Leave session
-            # finalization to the real owner (CLI close / gateway reset / cron).
-            review_agent._end_session_on_close = False
-            # Never let the review fork compress. It shares the parent's
-            # session_id, so if it won a compression race it would rotate the
-            # parent into a NEW child that the gateway never adopts (the fork
-            # is single-lifecycle and dies right after this run_conversation).
-            # The foreground turn would then start from the stale parent and
-            # compress it again, leaving the same parent with two sibling
-            # children (issue #38727). Review also needs full context to
-            # produce a good memory/skill summary — compressing would strip
-            # detail. Both compression triggers in conversation_loop.py gate on
-            # agent.compression_enabled, so this short-circuits both paths.
-            review_agent.compression_enabled = False
-
-            from model_tools import get_tool_definitions
-            from hermes_cli.plugins import (
-                set_thread_tool_whitelist,
-                clear_thread_tool_whitelist,
-            )
-
-            # Gate the built-in memory tool on the profile's memory_enabled flag.
-            # Hardcoding ["memory", "skills"] granted the review LLM the MEMORY.md
-            # read/write tool even when a profile set memory_enabled: false,
-            # contaminating a memory-disabled profile (#54937 layer 2).
-            review_toolsets = ["skills"]
-            if review_agent._memory_enabled or review_agent._user_profile_enabled:
-                review_toolsets.insert(0, "memory")
-            review_whitelist = {
-                t["function"]["name"]
-                for t in get_tool_definitions(
-                    enabled_toolsets=review_toolsets,
-                    quiet_mode=True,
-                )
-            }
-            set_thread_tool_whitelist(
-                review_whitelist,
-                deny_msg_fmt=(
-                    "Background review denied non-whitelisted tool: "
-                    "{tool_name}. Only memory/skill tools are allowed."
-                ),
-            )
-            try:
-                from tools.skill_manager_tool import _reset_background_review_read_marks
-
-                _reset_background_review_read_marks()
-            except Exception:
-                pass
-
-            try:
-                # Routed to a different model -> replay a digest (cache is cold
-                # on that model anyway, so minimise cold-written tokens). Same
-                # model -> replay the full snapshot (warm cache reads).
-                _review_history = (
-                    _digest_history(messages_snapshot) if _routed
-                    else messages_snapshot
-                )
-                review_agent.run_conversation(
-                    user_message=(
-                        prompt
-                        + "\n\nYou can only call memory and skill "
-                        "management tools. Other tools will be denied "
-                        "at runtime — do not attempt them."
-                    ),
-                    conversation_history=_review_history,
-                )
-            finally:
-                clear_thread_tool_whitelist()
-
-            # Snapshot review actions before teardown. close() is allowed to
-            # clean per-session state, but the user-visible self-improvement
-            # summary still needs the completed review agent's tool results.
-            review_messages = list(getattr(review_agent, "_session_messages", []))
-
-            # Tear down memory providers while stdout is still
-            # redirected so background thread teardown (Honcho flush,
-            # Hindsight sync, etc.) stays silent.  The finally block
-            # below is a safety net for the exception path.
-            try:
-                review_agent.shutdown_memory_provider()
-            except Exception:
-                pass
-            try:
-                review_agent.close()
-            except Exception:
-                pass
-            review_agent = None
-
-        # Scan the review agent's messages for successful tool actions
-        # and surface a compact summary to the user. Tool messages
-        # already present in messages_snapshot must be skipped, since
-        # the review agent inherits that history and would otherwise
-        # re-surface stale "created"/"updated" messages from the prior
-        # conversation as if they just happened (issue #14944).
-        #
-        # Wrapped in try/except: a buggy/legacy tool response shape
-        # (e.g. ``_change`` returned as a list instead of a dict, #59437)
-        # must NOT take down the whole review with an AttributeError,
-        # since the caller's outer except logs only "Background
-        # memory/skill review failed" and discards every successful
-        # action the fork DID complete before the crash. Coerce an
-        # exception into an empty actions list so the partial valid
-        # actions from earlier in the messages are returned instead.
-        try:
-            actions = summarize_background_review_actions(
-                review_messages,
-                messages_snapshot,
-                notification_mode=getattr(agent, "memory_notifications", "on"),
-            )
-        except Exception as e:
-            logger.warning(
-                "summarize_background_review_actions returned partial results "
-                "after exception (treating as empty); suppressing AttributeError "
-                "that previously aborted the entire review (#59437): %s",
-                e,
-            )
-            actions = []
-
-        if actions:
-            summary = " · ".join(dict.fromkeys(actions))
-            agent._safe_print(
-                f"  💾 Self-improvement review: {summary}"
-            )
-            _bg_cb = agent.background_review_callback
-            if _bg_cb:
-                try:
-                    _bg_cb(
-                        f"💾 Self-improvement review: {summary}"
-                    )
-                except Exception:
-                    pass
-
-    except Exception as e:
-        logger.warning("Background memory/skill review failed: %s", e)
-        agent._emit_auxiliary_failure("background review", e)
-    finally:
-        # Safety-net cleanup for the exception path.  Normal completion already
-        # shut down inside the thread-scoped silence above.  Re-enter the
-        # thread-scoped silence here so teardown output (Honcho flush, Hindsight
-        # sync, background thread joins) stays quiet even on the exception path,
-        # without blanking other threads' streams.
-        if review_agent is not None:
-            try:
-                with thread_scoped_silence():
-                    try:
-                        review_agent.shutdown_memory_provider()
-                    except Exception:
-                        pass
-                    try:
-                        review_agent.close()
-                    except Exception:
-                        pass
-            except Exception:
-                pass
-        # Clear the approval callback on this bg-review thread so a
-        # recycled thread-id doesn't inherit a stale reference.
-        try:
-            _set_approval_callback(None)
-        except Exception:
-            pass
-
-
-def spawn_background_review_thread(
-    agent: Any,
-    messages_snapshot: List[Dict],
-    review_memory: bool = False,
-    review_skills: bool = False,
-):
-    """Build the review thread target and prompt for a background review.
-
-    Returns a ``(target, prompt)`` tuple.  The caller (``AIAgent._spawn_background_review``)
-    owns the actual ``threading.Thread`` construction so test-level patches
-    of ``run_agent.threading.Thread`` keep working.
-    """
-    # Pick the right prompt based on which triggers fired.  Allow per-agent
-    # override (the prompts moved to module-level constants but old code paths
-    # that set agent._MEMORY_REVIEW_PROMPT etc. directly keep working).
-    if review_memory and review_skills:
-        prompt = getattr(agent, "_COMBINED_REVIEW_PROMPT", _COMBINED_REVIEW_PROMPT)
-    elif review_memory:
-        prompt = getattr(agent, "_MEMORY_REVIEW_PROMPT", _MEMORY_REVIEW_PROMPT)
-    else:
-        prompt = getattr(agent, "_SKILL_REVIEW_PROMPT", _SKILL_REVIEW_PROMPT)
-
-    def _target() -> None:
-        _run_review_in_thread(agent, messages_snapshot, prompt)
-
-    return _target, prompt
-
-
-__all__ = [
-    "_MEMORY_REVIEW_PROMPT",
-    "_SKILL_REVIEW_PROMPT",
-    "_COMBINED_REVIEW_PROMPT",
-    "spawn_background_review_thread",
-    "summarize_background_review_actions",
-    "build_memory_write_metadata",
-]
@@ -1,131 +0,0 @@
-"""System-battery read-out for the CLI/TUI status bar.
-
-Reads the host battery through ``psutil`` (already a Hermes dependency) and
-exposes a compact, colour-coded label.  Everything degrades to "unavailable"
-when there is no battery (desktops, servers, VMs) or when the read fails, so
-callers can render the result unconditionally and simply show nothing.
-
-The status bar repaints often (every keystroke and on a ~1s idle refresh), so
-:func:`read_battery` memoises the last reading for a few seconds instead of
-hitting ``psutil`` on every frame.
-"""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass
-from typing import Optional
-
-
-@dataclass(frozen=True)
-class BatteryStatus:
-    """A single battery reading.
-
-    ``available`` is False on machines without a battery (or when the read
-    failed).  ``percent`` is clamped to 0-100.  ``plugged`` is True when on AC
-    power, False on battery, and None when the platform can't tell.
-    """
-
-    available: bool
-    percent: Optional[int] = None
-    plugged: Optional[bool] = None
-
-    @property
-    def charging(self) -> bool:
-        return bool(self.plugged)
-
-
-UNAVAILABLE = BatteryStatus(available=False)
-
-# Colour buckets, mirroring the status-bar context styles but inverted (a full
-# battery is "good", an empty one is "critical").
-CATEGORY_GOOD = "good"
-CATEGORY_WARN = "warn"
-CATEGORY_BAD = "bad"
-CATEGORY_CRITICAL = "critical"
-CATEGORY_DIM = "dim"
-
-_CACHE_TTL_SECONDS = 8.0
-_cache: Optional[tuple[float, BatteryStatus]] = None
-
-
-def _read_battery_uncached() -> BatteryStatus:
-    try:
-        import psutil
-    except Exception:
-        return UNAVAILABLE
-
-    # ``sensors_battery`` is missing on some platforms/builds of psutil.
-    reader = getattr(psutil, "sensors_battery", None)
-    if reader is None:
-        return UNAVAILABLE
-
-    try:
-        batt = reader()
-    except Exception:
-        return UNAVAILABLE
-
-    if batt is None:
-        return UNAVAILABLE
-
-    percent: Optional[int] = None
-    raw_percent = getattr(batt, "percent", None)
-    if raw_percent is not None:
-        try:
-            percent = max(0, min(100, int(round(float(raw_percent)))))
-        except (TypeError, ValueError):
-            percent = None
-
-    plugged = getattr(batt, "power_plugged", None)
-    if plugged is not None:
-        plugged = bool(plugged)
-
-    return BatteryStatus(available=True, percent=percent, plugged=plugged)
-
-
-def read_battery(use_cache: bool = True) -> BatteryStatus:
-    """Return the current battery status (cached for a few seconds)."""
-    global _cache
-    if use_cache and _cache is not None:
-        ts, cached = _cache
-        if time.monotonic() - ts < _CACHE_TTL_SECONDS:
-            return cached
-
-    status = _read_battery_uncached()
-    _cache = (time.monotonic(), status)
-    return status
-
-
-def clear_cache() -> None:
-    """Drop the memoised reading (used by tests)."""
-    global _cache
-    _cache = None
-
-
-def battery_category(status: BatteryStatus) -> str:
-    """Bucket a reading into a colour category: good/warn/bad/critical/dim."""
-    if not status.available or status.percent is None:
-        return CATEGORY_DIM
-    # On AC power the level isn't a concern — always read as healthy.
-    if status.charging:
-        return CATEGORY_GOOD
-    pct = status.percent
-    if pct <= 10:
-        return CATEGORY_CRITICAL
-    if pct <= 20:
-        return CATEGORY_BAD
-    if pct <= 50:
-        return CATEGORY_WARN
-    return CATEGORY_GOOD
-
-
-def battery_glyph(status: BatteryStatus) -> str:
-    """Return the leading glyph: a bolt while charging, else a battery."""
-    return "\u26a1" if status.charging else "\U0001f50b"  # ⚡ / 🔋
-
-
-def format_battery(status: BatteryStatus) -> str:
-    """Return a compact label like ``🔋 82%`` / ``⚡ 82%`` (empty if N/A)."""
-    if not status.available or status.percent is None:
-        return ""
-    return f"{battery_glyph(status)} {status.percent}%"
@@ -1,323 +0,0 @@
-"""Shared dollar-denominated usage model for the billing/subscription surfaces.
-
-The single source of truth behind the ``/usage`` and ``/subscription`` usage
-bars (TUI + CLI). User feedback (Jun 2026): the terminal surfaces show
-**dollars**, never "credits", and every usage bar must make the monthly
-subscription allowance and separately-purchased top-up dollars distinctly
-visible.
-
-Data source: the NAS account-info fetch (``NousPortalAccountInfo``), whose
-``paid_service_access_info`` carries the three dollar magnitudes we render
-(despite the legacy ``*_credits`` field names, these are USD floats):
-
-  - ``subscription_credits_remaining``  -> plan dollars left this month
-  - ``purchased_credits_remaining``     -> top-up dollars left (rolls over)
-  - ``total_usable_credits``            -> total spendable
-
-plus ``subscription.monthly_credits`` (the plan's monthly $ allowance, the
-denominator for the "% used" plan bar) and ``current_period_end`` (renewal).
-
-Design: two SEPARATE bars (decided with the user) rather than one crammed
-three-segment bar — at terminal widths three same-glyph density segments are
-unreadable. The plan bar is "spent vs allowance this month" (carries % used);
-the top-up bar is "money you bought, doesn't expire". Each gets full
-resolution and a single fill glyph, so the bar is never ambiguous and never
-relies on color.
-
-Fail-open everywhere: any missing/non-finite field degrades to fewer bars or a
-magnitudes-only view; a logged-out / unreachable portal yields
-``available=False`` and the surface shows nothing.
-"""
-
-from __future__ import annotations
-
-import logging
-import math
-import os
-from dataclasses import dataclass, field
-from typing import Any, Optional
-
-logger = logging.getLogger(__name__)
-
-# Below this TOTAL spendable ($), a paid account is flagged "low" — the alert
-# state that nudges top-up/upgrade before a mid-run cutoff. Product threshold
-# (user feedback): "any amount below $5 should be an alert status."
-LOW_BALANCE_THRESHOLD_USD = 5.0
-
-
-def _finite(value: Any) -> Optional[float]:
-    """Return value as a float iff it's a real finite number (not bool/NaN/Inf)."""
-    if isinstance(value, bool) or not isinstance(value, (int, float)):
-        return None
-    f = float(value)
-    return f if math.isfinite(f) else None
-
-
-def _fmt_usd(value: Optional[float]) -> str:
-    """``$X.YY`` for display. ``None`` -> ``$0.00`` (callers gate on presence)."""
-    return f"${(value or 0.0):,.2f}"
-
-
-def format_renews(value: Optional[str]) -> Optional[str]:
-    """Format an ISO date/timestamp as a human date, e.g. ``Jul 24, 2026``.
-
-    Accepts ``2026-07-24``, ``2026-07-24T11:05:01.000Z``, etc. Returns the raw
-    string unchanged if it can't be parsed (never raises), and ``None`` for
-    empty input.
-    """
-    if not value:
-        return None
-    from datetime import datetime
-
-    text = str(value).strip()
-    if not text:
-        return None
-    iso = text[:-1] + "+00:00" if text.endswith("Z") else text
-    try:
-        dt = datetime.fromisoformat(iso)
-    except ValueError:
-        # Fall back to a bare date prefix (YYYY-MM-DD) if present.
-        try:
-            dt = datetime.strptime(text[:10], "%Y-%m-%d")
-        except ValueError:
-            return text
-    # %-d isn't portable to Windows; build the day without a leading zero.
-    return f"{dt.strftime('%b')} {dt.day}, {dt.year}"
-
-
-@dataclass(frozen=True)
-class UsageBar:
-    """One full-resolution bar: ``spent`` of ``total``, plus a remaining figure.
-
-    ``kind`` is ``"plan"`` (monthly allowance, shows % used) or ``"topup"``
-    (purchased dollars, no denominator — ``spent`` is 0 and ``total`` ==
-    ``remaining`` so it renders as a full bar of available balance).
-    """
-
-    kind: str  # "plan" | "topup"
-    remaining_usd: float
-    total_usd: float
-    spent_usd: float = 0.0
-
-    @property
-    def pct_used(self) -> Optional[int]:
-        if self.kind != "plan" or self.total_usd <= 0:
-            return None
-        return max(0, min(100, round(self.spent_usd / self.total_usd * 100)))
-
-    @property
-    def fill_fraction(self) -> float:
-        """Fraction of the bar that should read as 'remaining' (filled)."""
-        if self.total_usd <= 0:
-            return 0.0
-        return max(0.0, min(1.0, self.remaining_usd / self.total_usd))
-
-
-@dataclass(frozen=True)
-class UsageModel:
-    """Surface-agnostic dollar usage model shared by /usage and /subscription.
-
-    ``status`` classifies the account for copy selection:
-      - ``"free"``     : no paid access / no subscription (free models only)
-      - ``"low"``      : paid, but total spendable < $5 (ALERT)
-      - ``"healthy"``  : paid, total spendable >= $5
-      - ``"depleted"`` : paid access lost (balance exhausted)
-    """
-
-    available: bool
-    status: str = "free"
-    plan_name: Optional[str] = None
-    renews_at: Optional[str] = None
-    renews_display: Optional[str] = None
-    subscription_remaining_usd: Optional[float] = None
-    topup_remaining_usd: Optional[float] = None
-    total_spendable_usd: Optional[float] = None
-    plan_bar: Optional[UsageBar] = None
-    topup_bar: Optional[UsageBar] = None
-
-    @property
-    def has_topup(self) -> bool:
-        return bool(self.topup_remaining_usd and self.topup_remaining_usd > 0)
-
-
-def usage_model_from_account(account_info: Any) -> UsageModel:
-    """Build a :class:`UsageModel` from a ``NousPortalAccountInfo``. Fail-open.
-
-    Returns ``UsageModel(available=False)`` when there's no usable account info
-    (logged out, no entitlement block). Never raises.
-    """
-    try:
-        if account_info is None or not getattr(account_info, "logged_in", False):
-            return UsageModel(available=False)
-
-        access = getattr(account_info, "paid_service_access_info", None)
-        sub = getattr(account_info, "subscription", None)
-        paid = getattr(account_info, "paid_service_access", None)
-
-        sub_remaining = _finite(getattr(access, "subscription_credits_remaining", None)) if access else None
-        topup_remaining = _finite(getattr(access, "purchased_credits_remaining", None)) if access else None
-        total_usable = _finite(getattr(access, "total_usable_credits", None)) if access else None
-
-        plan_name = getattr(sub, "plan", None) if sub is not None else None
-        renews_at = getattr(sub, "current_period_end", None) if sub is not None else None
-        monthly = _finite(getattr(sub, "monthly_credits", None)) if sub is not None else None
-
-        has_subscription = bool(plan_name) or (monthly is not None and monthly > 0)
-
-        # Total spendable: prefer the server's total; else sum the parts we have.
-        if total_usable is not None:
-            total_spendable = total_usable
-        else:
-            parts = [v for v in (sub_remaining, topup_remaining) if v is not None]
-            total_spendable = sum(parts) if parts else None
-
-        # Status classification.
-        if paid is False:
-            status = "depleted"
-        elif not has_subscription and not (topup_remaining and topup_remaining > 0):
-            # No plan and no purchased balance -> free-models-only.
-            status = "free"
-        elif total_spendable is not None and total_spendable < LOW_BALANCE_THRESHOLD_USD:
-            status = "low"
-        else:
-            status = "healthy"
-
-        # Plan bar — only with a positive monthly allowance AND a remaining we
-        # can place on it. spent = cap - remaining, clamped (a debt/over-cap
-        # balance reads as fully spent rather than a nonsensical negative).
-        plan_bar: Optional[UsageBar] = None
-        if monthly is not None and monthly > 0 and sub_remaining is not None:
-            remaining = max(0.0, min(monthly, sub_remaining))
-            plan_bar = UsageBar(
-                kind="plan",
-                remaining_usd=remaining,
-                total_usd=monthly,
-                spent_usd=max(0.0, monthly - sub_remaining),
-            )
-
-        # Top-up bar — only when there are purchased dollars to show. No
-        # denominator (top-up has no monthly cap), so it renders full = balance.
-        topup_bar: Optional[UsageBar] = None
-        if topup_remaining is not None and topup_remaining > 0:
-            topup_bar = UsageBar(
-                kind="topup",
-                remaining_usd=topup_remaining,
-                total_usd=topup_remaining,
-                spent_usd=0.0,
-            )
-
-        return UsageModel(
-            available=True,
-            status=status,
-            plan_name=plan_name,
-            renews_at=renews_at,
-            renews_display=format_renews(renews_at),
-            subscription_remaining_usd=sub_remaining,
-            topup_remaining_usd=topup_remaining,
-            total_spendable_usd=total_spendable,
-            plan_bar=plan_bar,
-            topup_bar=topup_bar,
-        )
-    except Exception:
-        logger.debug("usage ▸ model build failed (fail-open)", exc_info=True)
-        return UsageModel(available=False)
-
-
-def build_usage_model(*, timeout: float = 10.0) -> UsageModel:
-    """Fetch account-info and build the shared usage model. Fail-open.
-
-    Dev override: ``HERMES_DEV_CREDITS_FIXTURE`` short-circuits to a fixture so
-    every usage state is testable without a live account (mirrors the existing
-    ``/usage`` credits-block fixture path).
-    """
-    fixture = _dev_fixture_usage_model()
-    if fixture is not None:
-        return fixture
-
-    try:
-        from hermes_cli.auth import get_provider_auth_state
-
-        tok = (get_provider_auth_state("nous") or {}).get("access_token")
-        if not (isinstance(tok, str) and tok.strip()):
-            return UsageModel(available=False)
-    except Exception:
-        return UsageModel(available=False)
-
-    try:
-        import concurrent.futures
-
-        from hermes_cli.nous_account import get_nous_portal_account_info
-
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            account = pool.submit(get_nous_portal_account_info, force_fresh=True).result(timeout=timeout)
-        return usage_model_from_account(account)
-    except Exception:
-        logger.debug("usage ▸ portal fetch failed (fail-open)", exc_info=True)
-        return UsageModel(available=False)
-
-
-# =============================================================================
-# Dev fixtures (throwaway scaffolding — env-var driven, no live portal)
-# =============================================================================
-
-
-def _dev_fixture_usage_model() -> Optional[UsageModel]:
-    """Map ``HERMES_DEV_CREDITS_FIXTURE`` to a usage model for offline UX work.
-
-    Recognized names: ``free | healthy | low | topup | depleted``. Returns
-    ``None`` when the env var is unset (real portal path runs).
-    """
-    name = (os.getenv("HERMES_DEV_CREDITS_FIXTURE") or "").strip().lower()
-    if not name:
-        return None
-
-    if name == "free":
-        return UsageModel(available=True, status="free", plan_name=None)
-
-    if name in ("healthy", "mid"):
-        return UsageModel(
-            available=True,
-            status="healthy",
-            plan_name="Plus",
-            renews_at="2026-07-01",
-            subscription_remaining_usd=14.0,
-            total_spendable_usd=14.0,
-            plan_bar=UsageBar(kind="plan", remaining_usd=14.0, total_usd=20.0, spent_usd=6.0),
-        )
-
-    if name in ("topup", "top-up"):
-        return UsageModel(
-            available=True,
-            status="healthy",
-            plan_name="Plus",
-            renews_at="2026-07-01",
-            subscription_remaining_usd=14.0,
-            topup_remaining_usd=12.0,
-            total_spendable_usd=26.0,
-            plan_bar=UsageBar(kind="plan", remaining_usd=14.0, total_usd=20.0, spent_usd=6.0),
-            topup_bar=UsageBar(kind="topup", remaining_usd=12.0, total_usd=12.0, spent_usd=0.0),
-        )
-
-    if name == "low":
-        return UsageModel(
-            available=True,
-            status="low",
-            plan_name="Plus",
-            renews_at="2026-07-01",
-            subscription_remaining_usd=3.4,
-            total_spendable_usd=3.4,
-            plan_bar=UsageBar(kind="plan", remaining_usd=3.4, total_usd=20.0, spent_usd=16.6),
-        )
-
-    if name == "depleted":
-        return UsageModel(
-            available=True,
-            status="depleted",
-            plan_name="Plus",
-            renews_at="2026-07-01",
-            subscription_remaining_usd=0.0,
-            total_spendable_usd=0.0,
-            plan_bar=UsageBar(kind="plan", remaining_usd=0.0, total_usd=20.0, spent_usd=20.0),
-        )
-
-    return None
@@ -1,458 +0,0 @@
-"""Surface-agnostic core for the Phase 2b Remote Spending screens.
-
-One fetch/parse per concern, consumed identically by the CLI handler
-(``cli.py::_show_billing``), the TUI JSON-RPC methods
-(``tui_gateway/server.py``), and any other surface. Mirrors the proven
-``agent/account_usage.py::build_credits_view`` pattern: parse the server payload
-into a frozen dataclass; **fail open** — when not logged in or the portal is
-unreachable, return a struct with ``logged_in=False`` and let the surface degrade
-gracefully (never crash).
-
-Money discipline: the server emits decimal STRINGS (``"142.5"``, not fixed 2dp).
-We keep them as :class:`decimal.Decimal` end-to-end and only format for display.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-import uuid
-from dataclasses import dataclass, field
-from decimal import Decimal, InvalidOperation
-from typing import Any, Optional
-
-logger = logging.getLogger(__name__)
-
-
-# =============================================================================
-# Decimal money helpers
-# =============================================================================
-
-
-def parse_money(value: Any) -> Optional[Decimal]:
-    """Parse a server money value (decimal string) into :class:`Decimal`.
-
-    Returns None for missing/invalid input. Never raises. Accepts str/int (and,
-    defensively, float — though the server always sends strings).
-    """
-    if value is None:
-        return None
-    try:
-        # Decimal(str(...)) avoids binary-float artifacts if a float ever sneaks in.
-        return Decimal(str(value).strip())
-    except (InvalidOperation, ValueError, TypeError):
-        return None
-
-
-def format_money(value: Optional[Decimal]) -> str:
-    """Format a Decimal as ``$X`` / ``$X.YY`` for display.
-
-    Whole dollars show no decimals; any fractional amount shows exactly 2dp:
-    ``Decimal("142.5")`` → ``"$142.50"``, ``Decimal("100")`` → ``"$100"``,
-    ``Decimal("0.01")`` → ``"$0.01"``.
-    """
-    if value is None:
-        return "—"
-    if value == value.to_integral_value():
-        # Whole dollars — no decimal point. format(..., "f") avoids 1E+3 for 1000.
-        return f"${format(value.to_integral_value(), 'f')}"
-    # Fractional — always show 2dp.
-    return f"${format(value.quantize(Decimal('0.01')), 'f')}"
-
-
-# =============================================================================
-# Parsed sub-structures
-# =============================================================================
-
-
-# resolvedVia → the human answer to "why THIS card?". Keys are the server's card
-# resolution rungs (NAS card-on-file ladder); absent/unknown rungs render no label
-# so the display degrades cleanly on servers that don't send resolvedVia yet.
-_CARD_PROVENANCE_LABELS = {
-    "subPin": "the card on your subscription",
-    "customerDefault": "your default card saved on the portal",
-    "autoRefill": "your auto-reload card",
-}
-
-
-@dataclass(frozen=True)
-class CardInfo:
-    brand: str
-    last4: str
-    # NAS card-on-file field (post card-resolver): which ladder rung found the
-    # card. Defaults off so pre-resolver payloads parse unchanged.
-    resolved_via: Optional[str] = None
-
-    @property
-    def masked(self) -> str:
-        # A Link payment method has no card number (last4 = "") — render the
-        # brand alone, not "Link ····".
-        if not self.last4:
-            return self.brand
-        return f"{self.brand} ····{self.last4}"
-
-    @property
-    def provenance(self) -> Optional[str]:
-        """Human label for why this card was picked, or None (unknown rung /
-        server too old to say)."""
-        if self.resolved_via is None:
-            return None
-        return _CARD_PROVENANCE_LABELS.get(self.resolved_via)
-
-    @property
-    def display(self) -> str:
-        """The one-line card display: ``Visa ····4242 — the card on your
-        subscription`` (or just the masked card when provenance is unknown)."""
-        label = self.provenance
-        return f"{self.masked} — {label}" if label else self.masked
-
-
-@dataclass(frozen=True)
-class MonthlyCap:
-    limit_usd: Optional[Decimal] = None
-    spent_this_month_usd: Optional[Decimal] = None
-    is_default_ceiling: bool = False
-
-
-@dataclass(frozen=True)
-class AutoReloadCard:
-    kind: str  # "canonical" | "distinct" | "none"
-    payment_method_id: Optional[str] = None
-    brand: Optional[str] = None
-    last4: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class AutoReload:
-    enabled: bool = False
-    threshold_usd: Optional[Decimal] = None
-    reload_to_usd: Optional[Decimal] = None
-    card: Optional[AutoReloadCard] = None
-
-
-@dataclass(frozen=True)
-class BillingState:
-    """Parsed ``GET /api/billing/state`` — the overview screen's data.
-
-    Fail-open: ``logged_in=False`` (and empty fields) when not logged in or the
-    portal is unreachable.
-    """
-
-    logged_in: bool
-    org_id: Optional[str] = None
-    org_slug: Optional[str] = None
-    org_name: Optional[str] = None
-    role: Optional[str] = None  # "OWNER" | "ADMIN" | "FINANCE_ADMIN" | "SECURITY_ADMIN" | "MEMBER"
-    can_change_plan_raw: Optional[bool] = None
-    balance_usd: Optional[Decimal] = None
-    cli_billing_enabled: bool = False
-    charge_presets: tuple[Decimal, ...] = ()
-    min_usd: Optional[Decimal] = None
-    max_usd: Optional[Decimal] = None
-    card: Optional[CardInfo] = None
-    monthly_cap: Optional[MonthlyCap] = None
-    auto_reload: Optional[AutoReload] = None
-    portal_url: Optional[str] = None
-    # When the fetch failed (vs cleanly not-logged-in), the message for the surface.
-    error: Optional[str] = None
-
-    @property
-    def is_admin(self) -> bool:
-        """Deprecated/display only — a legacy OWNER/ADMIN check.
-
-        NOT a capability check; use :attr:`can_change_plan` for gating billing
-        plan-change actions.
-        """
-        return (self.role or "").upper() in ("OWNER", "ADMIN")
-
-    @property
-    def can_change_plan(self) -> bool:
-        """Server capability when supplied; otherwise the legacy role fallback."""
-        if self.can_change_plan_raw is not None:
-            return self.can_change_plan_raw
-        return self.is_admin
-
-    @property
-    def can_charge(self) -> bool:
-        """True when the UI should offer charge/auto-reload actions.
-
-        Uses the server-granted plan-change capability (``can_change_plan``,
-        which itself falls back to the legacy OWNER/ADMIN role check when the
-        server omits ``canChangePlan``) AND the per-org kill-switch. This lets
-        the server grant charge capability to non-OWNER/ADMIN roles (e.g.
-        FINANCE_ADMIN) via ``canChangePlan``, instead of hard-coding the
-        deprecated 3-role admin check. (The server still enforces; this is
-        just for graying out actions the user can't take.)
-        """
-        return self.can_change_plan and self.cli_billing_enabled
-
-
-def _parse_card(raw: Any) -> Optional[CardInfo]:
-    if not isinstance(raw, dict):
-        return None
-    brand = raw.get("brand")
-    last4 = raw.get("last4")
-    if not (isinstance(brand, str) and isinstance(last4, str)):
-        return None
-    # Post-resolver fields — all optional so both payload generations parse.
-    resolved_via = raw.get("resolvedVia")
-    if not isinstance(resolved_via, str):
-        resolved_via = None
-    return CardInfo(brand=brand, last4=last4, resolved_via=resolved_via)
-
-
-def _parse_monthly_cap(raw: Any) -> Optional[MonthlyCap]:
-    if not isinstance(raw, dict):
-        return None
-    return MonthlyCap(
-        limit_usd=parse_money(raw.get("limitUsd")),
-        spent_this_month_usd=parse_money(raw.get("spentThisMonthUsd")),
-        is_default_ceiling=bool(raw.get("isDefaultCeiling")),
-    )
-
-
-def _parse_auto_reload(raw: Any) -> Optional[AutoReload]:
-    if not isinstance(raw, dict):
-        return None
-    return AutoReload(
-        enabled=bool(raw.get("enabled")),
-        threshold_usd=parse_money(raw.get("thresholdUsd")),
-        reload_to_usd=parse_money(raw.get("reloadToUsd")),
-        card=_parse_auto_reload_card(raw.get("card")),
-    )
-
-
-def _parse_auto_reload_card(raw: Any) -> Optional[AutoReloadCard]:
-    if not isinstance(raw, dict):
-        return None
-    kind = raw.get("kind")
-    if kind not in ("canonical", "distinct", "none"):
-        return None
-    if kind in ("canonical", "none"):
-        return AutoReloadCard(kind=kind)
-
-    payment_method_id = raw.get("paymentMethodId")
-    brand = raw.get("brand")
-    last4 = raw.get("last4")
-    return AutoReloadCard(
-        kind=kind,
-        payment_method_id=payment_method_id if isinstance(payment_method_id, str) else None,
-        brand=brand if isinstance(brand, str) else None,
-        last4=last4 if isinstance(last4, str) else None,
-    )
-
-
-def billing_state_from_payload(
-    payload: dict[str, Any], *, portal_url: Optional[str] = None
-) -> BillingState:
-    """Map a raw ``/api/billing/state`` JSON dict into :class:`BillingState`."""
-    raw_org = payload.get("org")
-    org: dict[str, Any] = raw_org if isinstance(raw_org, dict) else {}
-    raw_bounds = payload.get("bounds")
-    bounds: dict[str, Any] = raw_bounds if isinstance(raw_bounds, dict) else {}
-
-    presets: list[Decimal] = []
-    for item in payload.get("chargePresets") or ():
-        parsed = parse_money(item)
-        if parsed is not None:
-            presets.append(parsed)
-
-    return BillingState(
-        logged_in=True,
-        org_id=org.get("id"),
-        org_slug=org.get("slug"),
-        org_name=org.get("name"),
-        role=org.get("role"),
-        can_change_plan_raw=(
-            payload.get("canChangePlan")
-            if isinstance(payload.get("canChangePlan"), bool)
-            else None
-        ),
-        balance_usd=parse_money(payload.get("balanceUsd")),
-        cli_billing_enabled=bool(payload.get("cliBillingEnabled")),
-        charge_presets=tuple(presets),
-        min_usd=parse_money(bounds.get("minUsd")),
-        max_usd=parse_money(bounds.get("maxUsd")),
-        card=_parse_card(payload.get("card")),
-        monthly_cap=_parse_monthly_cap(payload.get("monthlyCap")),
-        auto_reload=_parse_auto_reload(payload.get("autoReload")),
-        portal_url=portal_url,
-    )
-
-
-# =============================================================================
-# Fail-open builders (the surface front doors)
-# =============================================================================
-
-
-def build_billing_state(*, timeout: float = 15.0) -> BillingState:
-    """Fetch + parse ``/api/billing/state``. Fail-open.
-
-    Returns ``BillingState(logged_in=False)`` when not logged in. On a portal/HTTP
-    failure, returns ``logged_in=False`` with ``error`` set so the surface can show
-    a clear message rather than crashing.
-
-    Dev override: ``HERMES_DEV_BILLING_FIXTURE`` short-circuits to a fixture so the
-    card-on-file / admin / scope states are testable offline (mirrors
-    ``HERMES_DEV_CREDITS_FIXTURE`` for the usage model).
-    """
-    fixture = _dev_fixture_billing_state()
-    if fixture is not None:
-        return fixture
-
-    try:
-        from hermes_cli.nous_billing import (
-            BillingAuthError,
-            BillingError,
-            _absolutize_portal_url,
-            get_billing_state,
-            resolve_portal_base_url,
-        )
-    except Exception:
-        return BillingState(logged_in=False, error="billing client unavailable")
-
-    try:
-        payload = get_billing_state(timeout=timeout)
-    except BillingAuthError:
-        return BillingState(logged_in=False)
-    except BillingError as exc:
-        logger.debug("billing ▸ /state fetch failed (fail-open)", exc_info=True)
-        return BillingState(logged_in=False, error=str(exc))
-    except Exception:
-        logger.debug("billing ▸ /state unexpected error (fail-open)", exc_info=True)
-        return BillingState(logged_in=False, error="could not load billing state")
-
-    # Prefer a server-supplied portalUrl if present (resolved to absolute in case
-    # it's relative); else build the standard one.
-    raw_portal = payload.get("portalUrl") if isinstance(payload, dict) else None
-    portal_url = _absolutize_portal_url(raw_portal) if raw_portal else None
-    if not portal_url:
-        try:
-            portal_url = _fallback_portal_url(resolve_portal_base_url())
-        except Exception:
-            portal_url = None
-
-    return billing_state_from_payload(payload, portal_url=portal_url)
-
-
-def _fallback_portal_url(base: str) -> str:
-    """Standard billing deep-link when the server omits ``portalUrl``."""
-    return f"{base.rstrip('/')}/billing?topup=open"
-
-
-# =============================================================================
-# Dev fixtures (throwaway scaffolding — env-var driven, no live portal)
-# =============================================================================
-
-
-def _dev_fixture_billing_state() -> Optional[BillingState]:
-    """Map ``HERMES_DEV_BILLING_FIXTURE`` to a :class:`BillingState` for offline UX.
-
-    Recognized names::
-
-        nocard           logged in · billing on · admin · NO card on file
-        card             card on file · auto-reload off
-        card-autoreload  card on file · auto-reload on
-        notadmin         logged in · MEMBER role (billing actions disabled)
-        billing-off      logged in · admin · per-org kill-switch OFF
-        logged-out       not logged in
-
-    Returns ``None`` when the env var is unset (the real portal path runs).
-    Mirrors ``HERMES_DEV_CREDITS_FIXTURE``; the usage *bar* still comes from
-    ``HERMES_DEV_CREDITS_FIXTURE`` (set both to pair a bar with a billing state).
-    """
-    name = (os.getenv("HERMES_DEV_BILLING_FIXTURE") or "").strip().lower()
-    if not name:
-        return None
-
-    # Shared fixture portal host (matches subscription_view._DEV_FIXTURE_PORTAL —
-    # prod host, not staging; the ?topup=open suffix is the /topup deep-link).
-    portal = "https://portal.nousresearch.com/billing?topup=open"
-    common: dict[str, Any] = dict(
-        org_id="org_acme",
-        org_slug="acme",
-        org_name="Acme Inc",
-        role="OWNER",
-        balance_usd=Decimal("3.40"),
-        cli_billing_enabled=True,
-        charge_presets=(Decimal("10"), Decimal("25"), Decimal("50")),
-        min_usd=Decimal("5"),
-        max_usd=Decimal("500"),
-        portal_url=portal,
-    )
-    card = CardInfo(brand="Visa", last4="4242")
-    autoreload_on = AutoReload(enabled=True, threshold_usd=Decimal("5"), reload_to_usd=Decimal("25"))
-
-    if name in ("logged-out", "logged_out", "loggedout"):
-        return BillingState(logged_in=False)
-    if name == "nocard":
-        return BillingState(logged_in=True, card=None, **common)
-    if name == "card":
-        return BillingState(logged_in=True, card=card, **common)
-    if name in ("card-sub", "card_sub"):
-        # Post-resolver: the card came from the subscription (provenance label).
-        _sub_card = CardInfo(brand="Visa", last4="4242", resolved_via="subPin")
-        return BillingState(logged_in=True, card=_sub_card, **common)
-    if name in ("card-autoreload", "card_autoreload", "autoreload"):
-        return BillingState(logged_in=True, card=card, auto_reload=autoreload_on, **common)
-    if name in ("notadmin", "not-admin", "member"):
-        opts = {**common, "role": "MEMBER"}
-        return BillingState(logged_in=True, card=card, **opts)
-    if name in ("billing-off", "billing_off", "off"):
-        opts = {**common, "cli_billing_enabled": False}
-        return BillingState(logged_in=True, card=None, **opts)
-
-    # Unknown name → logged-out so the misconfiguration is visible.
-    return BillingState(logged_in=False, error=f"unknown HERMES_DEV_BILLING_FIXTURE: {name}")
-
-
-# =============================================================================
-# Idempotency
-# =============================================================================
-
-
-def new_idempotency_key() -> str:
-    """Fresh UUID for a user-confirmed purchase (reuse on retry of the SAME buy).
-
-    The ``Idempotency-Key`` header is mandatory on ``POST /charge``; generate one
-    per confirmed purchase and reuse it across retries so a double-submit collapses
-    to a single charge. Never reuse a key across different amounts (the server
-    returns 409 idempotency_conflict).
-    """
-    return str(uuid.uuid4())
-
-
-# =============================================================================
-# Amount validation (Screen 3 custom input)
-# =============================================================================
-
-
-@dataclass(frozen=True)
-class AmountValidation:
-    ok: bool
-    amount: Optional[Decimal] = None
-    error: Optional[str] = None
-
-
-def validate_charge_amount(
-    raw: str, *, min_usd: Optional[Decimal], max_usd: Optional[Decimal]
-) -> AmountValidation:
-    """Validate a custom charge amount against bounds + 2dp (multipleOf 0.01).
-
-    Mirrors the server's accept/reject so the UI can give instant feedback rather
-    than round-tripping a sure-to-fail charge. The server is still authoritative.
-    """
-    cleaned = (raw or "").strip().lstrip("$").strip()
-    amount = parse_money(cleaned)
-    if amount is None:
-        return AmountValidation(ok=False, error="Enter a dollar amount, e.g. 100")
-    if amount <= 0:
-        return AmountValidation(ok=False, error="Amount must be greater than $0")
-    # multipleOf 0.01 — reject sub-cent precision.
-    if amount != amount.quantize(Decimal("0.01")):
-        return AmountValidation(ok=False, error="Amount can't be smaller than a cent")
-    if min_usd is not None and amount < min_usd:
-        return AmountValidation(ok=False, error=f"Minimum is {format_money(min_usd)}")
-    if max_usd is not None and amount > max_usd:
-        return AmountValidation(ok=False, error=f"Maximum is {format_money(max_usd)}")
-    return AmountValidation(ok=True, amount=amount)
@@ -1,148 +0,0 @@
-"""Bounded reads of HTTP error response bodies.
-
-When a provider returns a non-OK status on a *streaming* request, Hermes reads
-the response body to build a useful diagnostic error. A bare ``response.read()``
-on a streaming httpx response is unbounded in two dangerous ways:
-
-1. A server can declare (or stream) an arbitrarily large body, so the read can
-   balloon memory.
-2. A server can open the body and then stall forever (no ``Content-Length``,
-   no further bytes), so the read hangs the agent indefinitely.
-
-Both are realistic against a misbehaving proxy, a hijacked endpoint, or a
-provider having a bad day. The diagnostic body is only ever shown to the user
-truncated to a few hundred characters, so reading megabytes — or blocking
-forever — buys nothing.
-
-``read_streaming_error_body`` bounds the read to a byte cap and enforces a
-hard wall-clock deadline, returning the decoded text snippet. Callers pass the
-returned text into their existing error builders instead of touching
-``response.text`` (which would be unbounded / would raise after a partial
-stream read).
-
-A subtlety the implementation must respect: ``httpx``'s ``iter_bytes()`` blocks
-*inside* the C/socket read while waiting for the next chunk. A wall-clock check
-placed only between yielded chunks cannot interrupt a server that opens the
-body and then stalls mid-chunk — control never returns to Python until httpx's
-own (often 30s+) read timeout fires. To guarantee a bounded stop regardless of
-socket behavior, the read runs on a daemon worker thread and the caller waits
-on it with a hard deadline; on timeout we close the response (which unblocks /
-cancels the read) and return whatever partial bytes were collected.
-
-Ported and adapted from openclaw/openclaw#95108 ("bound Anthropic error
-streams"), generalized to cover Hermes's three streaming error-body sites
-(native Gemini, Gemini Cloud Code, Antigravity Cloud Code).
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from typing import List, Optional
-
-import httpx
-
-logger = logging.getLogger(__name__)
-
-# Defaults chosen to comfortably hold any real provider error envelope (Google
-# RPC error JSON, Anthropic error JSON) while rejecting pathological bodies.
-DEFAULT_ERROR_BODY_MAX_BYTES = 64 * 1024
-# Hard wall-clock deadline for the whole bounded read. A streaming error body
-# that does not finish within this window is abandoned and the connection is
-# closed; we keep whatever partial bytes arrived.
-DEFAULT_ERROR_BODY_TIMEOUT_S = 10.0
-
-
-def read_streaming_error_body(
-    response: httpx.Response,
-    *,
-    max_bytes: int = DEFAULT_ERROR_BODY_MAX_BYTES,
-    timeout_s: float = DEFAULT_ERROR_BODY_TIMEOUT_S,
-) -> str:
-    """Read a non-OK streaming response body with a byte cap and a hard deadline.
-
-    Returns the decoded body text (UTF-8, errors replaced), truncated to
-    ``max_bytes``. Never raises: any transport error, stall, or oversize
-    condition is swallowed and the best-effort partial text (or an empty
-    string) is returned, because this runs on the error path and must not
-    mask the original HTTP failure with a read error.
-
-    The byte cap protects against huge bodies; the wall-clock deadline (enforced
-    via a worker thread so it can interrupt a socket read that stalls mid-chunk)
-    protects against bodies that open and then hang.
-    """
-    chunks: List[bytes] = []
-    state = {"truncated": False}
-    done = threading.Event()
-
-    def _drain() -> None:
-        total = 0
-        try:
-            for chunk in response.iter_bytes():
-                if not chunk:
-                    continue
-                remaining = max_bytes - total
-                if remaining <= 0:
-                    state["truncated"] = True
-                    break
-                if len(chunk) > remaining:
-                    chunks.append(chunk[:remaining])
-                    total += remaining
-                    state["truncated"] = True
-                    break
-                chunks.append(chunk)
-                total += len(chunk)
-        except Exception as exc:  # noqa: BLE001 - error path must not raise
-            logger.debug("bounded error-body read failed: %s", exc)
-        finally:
-            done.set()
-
-    worker = threading.Thread(
-        target=_drain, name="bounded-error-body-read", daemon=True
-    )
-    worker.start()
-    finished = done.wait(timeout=timeout_s)
-
-    if not finished:
-        logger.debug(
-            "bounded error-body read: hard timeout after %.1fs (%d bytes so far)",
-            timeout_s,
-            sum(len(c) for c in chunks),
-        )
-        # Closing the response cancels the in-flight socket read, letting the
-        # worker thread unwind. We do not join (it is a daemon and may be
-        # blocked in C); the partial `chunks` collected so far are returned.
-        _safe_close(response)
-    else:
-        _safe_close(response)
-
-    if state["truncated"]:
-        logger.debug(
-            "bounded error-body read: capped at %d bytes (max=%d)",
-            sum(len(c) for c in chunks),
-            max_bytes,
-        )
-    return b"".join(chunks).decode("utf-8", errors="replace")
-
-
-def _safe_close(response: httpx.Response) -> None:
-    try:
-        response.close()
-    except Exception:  # noqa: BLE001
-        pass
-
-
-def read_error_body_or_default(
-    response: httpx.Response,
-    *,
-    max_bytes: int = DEFAULT_ERROR_BODY_MAX_BYTES,
-    timeout_s: float = DEFAULT_ERROR_BODY_TIMEOUT_S,
-) -> Optional[str]:
-    """Like ``read_streaming_error_body`` but returns ``None`` on empty body.
-
-    Convenience for callers that distinguish "no body" from "empty string".
-    """
-    text = read_streaming_error_body(
-        response, max_bytes=max_bytes, timeout_s=timeout_s
-    )
-    return text or None
@@ -1,175 +0,0 @@
-"""
-Browser Provider ABC
-====================
-
-Defines the pluggable-backend interface for cloud browser providers
-(Browserbase, Browser Use, Firecrawl, …). Providers register instances via
-:meth:`PluginContext.register_browser_provider`; the active one (selected via
-``browser.cloud_provider`` in ``config.yaml``) services every cloud-mode
-``browser_*`` tool call.
-
-Providers live in ``<repo>/plugins/browser/<name>/`` (built-in, auto-loaded as
-``kind: backend``) or ``~/.hermes/plugins/browser/<name>/`` (user, opt-in via
-``plugins.enabled``).
-
-This ABC mirrors :class:`agent.web_search_provider.WebSearchProvider` (PR
-#25182) — same shape, same registration flow, same picker integration. The
-legacy in-tree ``tools.browser_providers.base.CloudBrowserProvider`` ABC was
-deleted in PR #25214 (this work) along with the per-vendor inline modules in
-``tools/browser_providers/``; the lifecycle contract documented below is
-preserved bit-for-bit so the tool wrapper (:mod:`tools.browser_tool`) does
-not have to translate.
-
-Session metadata contract (preserved from the legacy ``CloudBrowserProvider``)::
-
-    {
-        "session_name": str,        # unique name for agent-browser --session
-        "bb_session_id": str,       # provider session ID (for close/cleanup)
-        "cdp_url": str,             # CDP websocket URL
-        "features": dict,           # feature flags that were enabled
-        "external_call_id": str,    # optional, managed-gateway billing key
-    }
-
-``bb_session_id`` is a legacy key name kept verbatim for backward compat with
-:mod:`tools.browser_tool` — it holds the provider's session ID regardless of
-which provider is in use.
-"""
-
-from __future__ import annotations
-
-import abc
-from typing import Any, Dict
-
-
-# ---------------------------------------------------------------------------
-# ABC
-# ---------------------------------------------------------------------------
-
-
-class BrowserProvider(abc.ABC):
-    """Abstract base class for a cloud browser backend.
-
-    Subclasses must implement :meth:`name`, :meth:`is_available`, and the
-    three lifecycle methods: :meth:`create_session`, :meth:`close_session`,
-    :meth:`emergency_cleanup`.
-
-    The lifecycle shape preserves the legacy ``CloudBrowserProvider`` contract
-    bit-for-bit so the dispatcher in :mod:`tools.browser_tool` is a pure
-    registry lookup — no per-provider conditionals, no shape translation.
-    """
-
-    @property
-    @abc.abstractmethod
-    def name(self) -> str:
-        """Stable short identifier used in the ``browser.cloud_provider``
-        config key.
-
-        Lowercase, hyphens permitted to preserve existing user-visible names.
-        Examples: ``browserbase``, ``browser-use``, ``firecrawl``.
-        """
-
-    @property
-    def display_name(self) -> str:
-        """Human-readable label shown in ``hermes tools``. Defaults to ``name``."""
-        return self.name
-
-    @abc.abstractmethod
-    def is_available(self) -> bool:
-        """Return True when this provider can service calls.
-
-        Typically a cheap check (env var present, managed-gateway token
-        readable, optional Python dep importable). Must NOT make network
-        calls — this runs at tool-registration time and on every
-        ``hermes tools`` paint.
-
-        Mirrors the legacy ``CloudBrowserProvider.is_configured()`` method;
-        renamed for parity with :class:`agent.web_search_provider.WebSearchProvider`.
-        """
-
-    @abc.abstractmethod
-    def create_session(self, task_id: str) -> Dict[str, object]:
-        """Create a cloud browser session and return session metadata.
-
-        Must return a dict with at least::
-
-            {
-                "session_name": str,    # unique name for agent-browser --session
-                "bb_session_id": str,   # provider session ID (for close/cleanup)
-                "cdp_url": str,         # CDP websocket URL
-                "features": dict,       # feature flags that were enabled
-            }
-
-        ``bb_session_id`` is a legacy key name kept for backward compat with
-        the rest of :mod:`tools.browser_tool` — it holds the provider's
-        session ID regardless of which provider is in use.
-
-        May raise ``ValueError`` (missing credentials) or ``RuntimeError``
-        (network / API failure); the dispatcher surfaces these to the user.
-        """
-
-    @abc.abstractmethod
-    def close_session(self, session_id: str) -> bool:
-        """Release / terminate a cloud session by its provider session ID.
-
-        Returns True on success, False on failure. Should not raise — log and
-        return False on any exception so the dispatcher's cleanup loop keeps
-        moving across sessions.
-        """
-
-    @abc.abstractmethod
-    def emergency_cleanup(self, session_id: str) -> None:
-        """Best-effort session teardown during process exit.
-
-        Called from atexit / signal handlers. Must tolerate missing
-        credentials, network errors, etc. — log and move on. Must not raise.
-        """
-
-    def get_setup_schema(self) -> Dict[str, Any]:
-        """Return provider metadata for the ``hermes tools`` picker.
-
-        Used by :mod:`hermes_cli.tools_config` to inject this provider as a
-        row in the Browser Automation picker. Shape mirrors the existing
-        hardcoded entries in ``TOOL_CATEGORIES["browser"]``::
-
-            {
-                "name": "Browserbase",
-                "badge": "paid",
-                "tag": "Cloud browser with stealth and proxies",
-                "env_vars": [
-                    {"key": "BROWSERBASE_API_KEY",
-                     "prompt": "Browserbase API key",
-                     "url": "https://browserbase.com"},
-                ],
-                "post_setup": "agent_browser",
-            }
-
-        Default: minimal entry derived from :attr:`display_name`. Override to
-        expose API key prompts, badges, managed-Nous gating, and the
-        ``post_setup`` install hook.
-        """
-        return {
-            "name": self.display_name,
-            "badge": "",
-            "tag": "",
-            "env_vars": [],
-        }
-
-    # ------------------------------------------------------------------
-    # Backward-compat shims for the legacy CloudBrowserProvider API
-    # ------------------------------------------------------------------
-    #
-    # The pre-PR-#25214 ABC exposed ``is_configured()`` and ``provider_name()``;
-    # ``tools.browser_tool`` has ~6 callers that still use those names. Rather
-    # than churn every callsite (and break out-of-tree downstream code that
-    # subclassed CloudBrowserProvider), we expose the old names as thin
-    # delegations to the new API. Subclasses MUST implement :meth:`is_available`
-    # and :attr:`name`; they may override ``is_configured`` / ``provider_name``
-    # for compatibility with the legacy ABC but it is not required.
-
-    def is_configured(self) -> bool:
-        """Backward-compat alias for :meth:`is_available`."""
-        return self.is_available()
-
-    def provider_name(self) -> str:
-        """Backward-compat alias returning :attr:`display_name`."""
-        return self.display_name
@@ -1,192 +0,0 @@
-"""
-Browser Provider Registry
-=========================
-
-Central map of registered cloud browser providers. Populated by plugins at
-import-time via :meth:`PluginContext.register_browser_provider`; consumed by
-:func:`tools.browser_tool._get_cloud_provider` to route each cloud-mode
-``browser_*`` tool call to the active backend.
-
-Active selection
----------------
-The active provider is chosen by configuration with this precedence:
-
-1. ``browser.cloud_provider`` in ``config.yaml`` (explicit override).
-2. Legacy preference order — ``browser-use`` → ``browserbase`` — filtered by
-   availability. Matches the historic auto-detect order in
-   :func:`tools.browser_tool._get_cloud_provider` (Browser Use checked first
-   because it covers both the managed Nous gateway and direct API key path;
-   Browserbase as the older direct-credentials fallback). ``firecrawl`` is
-   intentionally NOT in the legacy walk — users only get Firecrawl as a
-   cloud browser when they explicitly set ``browser.cloud_provider:
-   firecrawl``, matching pre-migration behaviour where Firecrawl was never
-   auto-selected.
-3. Otherwise ``None`` — the dispatcher falls back to local browser mode.
-
-The explicit-config branch (rule 1) intentionally ignores ``is_available()``
-so the dispatcher surfaces a typed "X_API_KEY is not set" error to the user
-instead of silently switching backends. Matches the legacy
-:func:`tools.browser_tool._get_cloud_provider` behaviour for configured names.
-
-Note: there is no "capability" split here (unlike the web subsystem, which
-has search/extract/crawl). Every browser provider implements the full
-:class:`agent.browser_provider.BrowserProvider` lifecycle; the registry's
-job is purely selection, not capability routing.
-"""
-
-from __future__ import annotations
-
-import logging
-import threading
-from typing import Dict, List, Optional
-
-from agent.browser_provider import BrowserProvider
-
-logger = logging.getLogger(__name__)
-
-
-_providers: Dict[str, BrowserProvider] = {}
-_lock = threading.Lock()
-
-
-def register_provider(provider: BrowserProvider) -> None:
-    """Register a cloud browser provider.
-
-    Re-registration (same ``name``) overwrites the previous entry and logs
-    a debug message — makes hot-reload scenarios (tests, dev loops) behave
-    predictably.
-    """
-    if not isinstance(provider, BrowserProvider):
-        raise TypeError(
-            f"register_provider() expects a BrowserProvider instance, "
-            f"got {type(provider).__name__}"
-        )
-    name = provider.name
-    if not isinstance(name, str) or not name.strip():
-        raise ValueError("Browser provider .name must be a non-empty string")
-    with _lock:
-        existing = _providers.get(name)
-        _providers[name] = provider
-    if existing is not None:
-        logger.debug(
-            "Browser provider '%s' re-registered (was %r)",
-            name, type(existing).__name__,
-        )
-    else:
-        logger.debug(
-            "Registered browser provider '%s' (%s)",
-            name, type(provider).__name__,
-        )
-
-
-def list_providers() -> List[BrowserProvider]:
-    """Return all registered providers, sorted by name."""
-    with _lock:
-        items = list(_providers.values())
-    return sorted(items, key=lambda p: p.name)
-
-
-def get_provider(name: str) -> Optional[BrowserProvider]:
-    """Return the provider registered under *name*, or None."""
-    if not isinstance(name, str):
-        return None
-    with _lock:
-        return _providers.get(name.strip())
-
-
-# ---------------------------------------------------------------------------
-# Active-provider resolution
-# ---------------------------------------------------------------------------
-
-
-# Legacy auto-detect order — used when no ``browser.cloud_provider`` is set.
-# Matches the pre-migration walk in :func:`tools.browser_tool._get_cloud_provider`.
-# Firecrawl is intentionally absent so users with ``FIRECRAWL_API_KEY`` set
-# for web-extract don't get silently routed to a paid cloud browser. See
-# :func:`_resolve` for the full rationale.
-_LEGACY_PREFERENCE = (
-    "browser-use",
-    "browserbase",
-)
-
-
-def _resolve(configured: Optional[str]) -> Optional[BrowserProvider]:
-    """Resolve the active browser provider.
-
-    Resolution rules (in order):
-
-    1. **Explicit "local".** Returns None — the dispatcher disables cloud
-       mode entirely. Mirrors legacy short-circuit in
-       :func:`tools.browser_tool._get_cloud_provider`.
-    2. **Explicit config wins, ignoring availability.** If ``configured``
-       names a registered provider, return it even if its
-       :meth:`is_available` returns False — the dispatcher will surface a
-       precise "X_API_KEY is not set" error instead of silently routing
-       somewhere else.
-    3. **Legacy preference walk, filtered by availability.** Walk
-       :data:`_LEGACY_PREFERENCE` (``browser-use`` → ``browserbase``) looking
-       for a provider whose ``is_available()`` is True.
-
-    There is intentionally NO "single-eligible shortcut" rule here (unlike
-    :func:`agent.web_search_registry._resolve`). Pre-migration, the
-    auto-detect branch in ``tools.browser_tool._get_cloud_provider`` only
-    considered Browser Use and Browserbase; Firecrawl was reachable only
-    via an explicit ``browser.cloud_provider: firecrawl`` config key.
-    Preserving that gate matters because Firecrawl shares its API key with
-    the *web* extract plugin (``plugins/web/firecrawl/``), so users who set
-    ``FIRECRAWL_API_KEY`` for web extract must NOT get silently routed to a
-    paid cloud browser on a fresh install. Third-party browser-provider
-    plugins added under ``~/.hermes/plugins/browser/<vendor>/`` are subject
-    to the same gate — they must be explicitly configured to take effect.
-
-    Returns None when no provider is configured AND no available provider
-    matches the legacy preference; the dispatcher then falls back to local
-    browser mode.
-    """
-    with _lock:
-        snapshot = dict(_providers)
-
-    def _is_available_safe(p: BrowserProvider) -> bool:
-        """Wrap ``is_available()`` so a buggy provider doesn't kill resolution."""
-        try:
-            return bool(p.is_available())
-        except Exception as exc:  # noqa: BLE001
-            logger.warning(
-                "Browser provider %s.is_available() raised %s — treating as unavailable",
-                p.name, exc, exc_info=True,
-            )
-            return False
-
-    # 1. Explicit "local" short-circuit.
-    if configured == "local":
-        return None
-
-    # 2. Explicit config wins — return regardless of is_available() so the
-    #    user gets a precise downstream error message rather than a silent
-    #    backend switch. Matches _get_cloud_provider() in browser_tool.py.
-    if configured:
-        provider = snapshot.get(configured)
-        if provider is not None:
-            return provider
-        logger.debug(
-            "browser cloud_provider '%s' configured but not registered; "
-            "falling back to auto-detect",
-            configured,
-        )
-
-    # 3. Legacy preference walk — only providers in _LEGACY_PREFERENCE are
-    #    auto-eligible. Filtered by availability so we don't surface a
-    #    provider the user has no credentials for. See docstring for why
-    #    we do NOT fall back to "any single-eligible registered provider".
-    for legacy in _LEGACY_PREFERENCE:
-        provider = snapshot.get(legacy)
-        if provider is not None and _is_available_safe(provider):
-            return provider
-
-    return None
-
-
-def _reset_for_tests() -> None:
-    """Clear the registry. **Test-only.**"""
-    with _lock:
-        _providers.clear()
@@ -1,887 +0,0 @@
-"""Coding-context awareness — base Hermes, every interactive surface.
-
-When the user runs Hermes inside a code workspace (CLI, TUI, desktop app, or an
-editor over ACP), Hermes shifts into a **coding posture**. This module is the
-single place that decides whether we're in that posture and what it implies,
-so the rest of the codebase never re-derives "are we coding?" on its own.
-
-Architecture — one seam, many consumers
----------------------------------------
-The posture is modelled as a frozen :class:`RuntimeMode` selected from a small
-:class:`ContextProfile` registry (today: ``coding`` and ``general``). A profile
-is *data* — it declares the toolset to collapse to, the operating brief to
-inject, and hints for other domains (model routing, memory, subagents). Every
-domain reads the same resolved object instead of probing git/config itself:
-
-  * **System prompt** — ``RuntimeMode.system_blocks()`` → the operating brief +
-    a live git/workspace snapshot (``agent/system_prompt.py``).
-  * **Toolset** — ``RuntimeMode.toolset_selection()`` → the ``coding`` toolset
-    plus the user's enabled MCP servers (``cli.py`` / ``tui_gateway``). Only
-    under the opt-in ``focus`` mode: the default posture is prompt-only and
-    never touches the user's configured toolsets (toolsets like messaging /
-    smart-home / music are off-by-default anyway, and someone who explicitly
-    enabled image-gen or Spotify shouldn't lose it for being in a git repo).
-  * **Delegation** — subagents inherit the parent's toolset and run through the
-    same prompt builder, so the coding posture propagates to children for free.
-  * **Model / memory / compression** — declared on the profile
-    (``model_hint``, ``memory_policy``) as the extension seam; consumers read
-    ``mode.profile`` rather than re-deciding.
-
-Cache safety
------------
-The mode is resolved **once** and is immutable. The workspace snapshot is built
-once at prompt-build time and baked into the *stable* system-prompt tier — never
-re-probed per turn (that would shatter the prompt cache). Branch and dirty state
-drift mid-session, so the brief tells the model to re-check with ``git`` before
-acting on the snapshot. A ``/coding`` flip therefore only takes effect next
-session (deferred), the same contract as ``/skills install`` vs ``--now``.
-
-Activation (config ``agent.coding_context``):
-
-  * ``auto`` (default) — posture (brief + snapshot) on an interactive coding
-    surface sitting in a code workspace (git repo or recognised project root).
-    Prompt-only; toolsets and the skill index untouched.
-  * ``focus`` — like ``auto``, but additionally collapses the toolset to the
-    ``coding`` set + enabled MCP servers and demotes non-coding skill
-    categories to names-only in the prompt's skill index (no skill is ever
-    hidden). Explicit opt-in for a lean schema.
-  * ``on`` — force the posture anywhere (incl. non-workspaces). Prompt-only.
-  * ``off`` — disable entirely.
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import re
-import tempfile
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any, Optional
-
-from hermes_cli._subprocess_compat import bounded_git_probe
-
-logger = logging.getLogger("hermes.coding_context")
-
-CODING_TOOLSET = "coding"
-
-# Surfaces where a coding posture makes sense under ``auto``. Messaging
-# platforms (telegram, discord, slack, …) are intentionally absent — a chat bot
-# in a group is not pair-programming.
-INTERACTIVE_CODING_PLATFORMS = {"cli", "tui", "acp", "desktop", ""}
-
-# Project-root signals that mark a directory as a code workspace even when it
-# isn't (yet) a git repo. Cheap filename checks — no parsing.
-_PROJECT_MARKERS = (
-    "pyproject.toml", "setup.py", "setup.cfg", "requirements.txt",
-    "package.json", "tsconfig.json", "deno.json",
-    "Cargo.toml", "go.mod", "pom.xml", "build.gradle", "build.gradle.kts",
-    "Gemfile", "composer.json", "mix.exs", "pubspec.yaml",
-    "CMakeLists.txt", "Makefile", "Dockerfile",
-    "AGENTS.md", "CLAUDE.md", ".cursorrules",
-)
-
-# Agent-instruction files surfaced separately from manifests in the snapshot.
-_CONTEXT_FILES = ("AGENTS.md", "CLAUDE.md", ".cursorrules")
-
-# Source-file extensions that make a git repo a *code* workspace even with no
-# manifest. Without this, `git init` on a notes/writing/research folder (a huge
-# non-coding use case) would flip the whole session into the coding posture just
-# for having a `.git`. A manifest still wins on its own (see `_PROJECT_MARKERS`).
-_CODE_EXTENSIONS = frozenset({
-    ".py", ".pyi", ".ipynb", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
-    ".go", ".rs", ".java", ".kt", ".kts", ".scala", ".rb", ".php", ".c", ".h",
-    ".cc", ".cpp", ".hpp", ".cs", ".swift", ".m", ".mm", ".dart", ".ex", ".exs",
-    ".lua", ".sh", ".bash", ".zsh", ".sql", ".vue", ".svelte", ".r", ".jl",
-    ".hs", ".clj", ".erl", ".pl",
-})
-
-# Dirs never worth scanning for the code check (deps/build/vcs/venv noise).
-_CODE_SCAN_SKIP_DIRS = frozenset({
-    ".git", "node_modules", "venv", ".venv", "__pycache__", "dist", "build",
-    "target", ".next", ".turbo", "vendor",
-})
-
-# Bounded sweep: a code workspace reveals itself in the first handful of entries.
-_CODE_SCAN_MAX_ENTRIES = 500
-
-
-def _has_code_files(root: Path) -> bool:
-    """Cheap, bounded check for source files in a repo's top two levels.
-
-    Lets a git repo of loose scripts (no manifest) still read as a code
-    workspace while a bare notes/writing repo does not. Scans the root and its
-    immediate subdirectories only, capped at ``_CODE_SCAN_MAX_ENTRIES`` stats —
-    a handful of readdirs at session start, not a full walk.
-    """
-    seen = 0
-    stack = [(root, True)]
-    while stack:
-        directory, is_root = stack.pop()
-        try:
-            with os.scandir(directory) as entries:
-                for entry in entries:
-                    seen += 1
-                    if seen > _CODE_SCAN_MAX_ENTRIES:
-                        return False
-                    name = entry.name
-                    try:
-                        if entry.is_file():
-                            if os.path.splitext(name)[1].lower() in _CODE_EXTENSIONS:
-                                return True
-                        elif is_root and entry.is_dir() and name not in _CODE_SCAN_SKIP_DIRS and not name.startswith("."):
-                            stack.append((Path(entry.path), False))
-                    except OSError:
-                        continue
-        except OSError:
-            continue
-    return False
-
-# Lockfile → package manager, checked in priority order.
-_PY_LOCKFILES = (("uv.lock", "uv"), ("poetry.lock", "poetry"), ("Pipfile.lock", "pipenv"))
-_JS_LOCKFILES = (
-    ("pnpm-lock.yaml", "pnpm"), ("bun.lockb", "bun"), ("bun.lock", "bun"),
-    ("yarn.lock", "yarn"), ("package-lock.json", "npm"),
-)
-
-# package.json scripts / Makefile targets worth surfacing as verify commands.
-_VERIFY_TARGETS = ("test", "tests", "lint", "typecheck", "check", "build", "fmt", "format")
-_MAX_VERIFY_COMMANDS = 8
-_MAX_FACT_FILE_BYTES = 256 * 1024
-
-_GIT_TIMEOUT = 2.5
-
-
-# Per-model edit-format steering. Matching the edit tool format to how a model
-# was trained reduces mistakes and wasted reasoning (OpenAI/Codex handle
-# patch-style diffs best; Anthropic models — and most open-weight coding
-# models, whose RL scaffolds use str_replace-style editors — do best with
-# string-replacement). Our `patch` tool exposes both: mode="patch" (V4A
-# multi-file) and mode="replace" (find-and-swap). We nudge each family toward
-# its native format. Unknown families get nothing (the brief's neutral wording
-# stands). Substrings match the model id; aligned with TOOL_USE_ENFORCEMENT_MODELS.
-#
-# GPT/Codex get V4A for ALL edits, single-file included: in codex-rs,
-# apply_patch (V4A — apply_patch.lark) is the ONLY file editor, no
-# str_replace-style tool exists, and the shipped model prompts say to use
-# apply_patch even "for single file edits" — so a replace-mode nudge would
-# steer those models toward a format their first-party harness never taught
-# them.
-_EDIT_FORMAT_GUIDANCE: dict[str, tuple[tuple[str, ...], str]] = {
-    "patch": (
-        ("gpt", "codex"),
-        "- Edit format: author new files with `write_file`; for edits to "
-        "existing code use `patch` with `mode='patch'` (V4A diff) — including "
-        "single-file edits. It's the edit format you handle most reliably.",
-    ),
-    "replace": (
-        ("claude", "sonnet", "opus", "haiku",
-         "gemini", "gemma", "deepseek", "qwen", "kimi", "glm", "grok",
-         "hermes", "llama", "mistral", "devstral", "minimax"),
-        "- Edit format: author new files with `write_file`; for edits to "
-        "existing code prefer `patch` in `mode='replace'` — match a unique "
-        "snippet and swap it. Reach for `mode='patch'` (V4A) only when an edit "
-        "genuinely spans several files at once.",
-    ),
-}
-
-
-def _model_family(model: Optional[str]) -> Optional[str]:
-    """Classify a model id into an edit-format family key, or ``None``.
-
-    Used to steer the coding posture toward the edit tool format a model was
-    trained on. Family-agnostic by design: an unrecognised model gets ``None``
-    and the operating brief's neutral edit wording applies.
-    """
-    if not model:
-        return None
-    lowered = model.lower()
-    for family, (needles, _line) in _EDIT_FORMAT_GUIDANCE.items():
-        if any(n in lowered for n in needles):
-            return family
-    return None
-
-
-def _edit_format_line(model: Optional[str]) -> str:
-    """The edit-format guidance line for this model's family (``""`` if none)."""
-    family = _model_family(model)
-    if family is None:
-        return ""
-    return _EDIT_FORMAT_GUIDANCE[family][1]
-
-
-# Operating brief for the coding posture. Tool names referenced here (read_file,
-# search_files, patch, write_file, terminal, todo) are in the coding toolset and
-# in _HERMES_CORE_TOOLS, so they're present on every surface this fires on.
-CODING_AGENT_GUIDANCE = (
-    "You are a coding agent pairing with the user inside their codebase. "
-    "Operate like a careful senior engineer.\n"
-    "\n"
-    "Gather context first:\n"
-    "- Read the relevant files with `read_file` and locate code with "
-    "`search_files` before changing anything. Trace a symbol to its definition "
-    "and usages rather than guessing its shape.\n"
-    "- Batch independent lookups: when several reads/searches don't depend on "
-    "each other, issue them together in one turn instead of one at a time.\n"
-    "- Never invent files, symbols, APIs, or imports. If you haven't seen it in "
-    "the repo, go look. Don't assume a library is available — check the project "
-    "manifest (pyproject.toml / package.json / Cargo.toml / go.mod) and how "
-    "neighbouring files import it.\n"
-    "\n"
-    "Make changes through the tools, not the chat:\n"
-    "- Edit with `patch`/`write_file`. Do NOT print code blocks to the user as "
-    "a substitute for editing — apply the change, then summarise it. Only show "
-    "code when the user explicitly asks to see it.\n"
-    "- Match the project's existing style and conventions; AGENTS.md / "
-    "CLAUDE.md / .cursorrules already in context win over your defaults. Touch "
-    "only what the task needs — no drive-by refactors, renames, or reformatting "
-    "— and add any imports/dependencies your code requires.\n"
-    "- If an edit fails to apply, re-read the file to get the current exact "
-    "contents before retrying — don't repeat a stale patch. If the same region "
-    "fails twice, rewrite the enclosing function or file with `write_file` "
-    "instead of attempting a third patch.\n"
-    "\n"
-    "Verify, and know when to stop:\n"
-    "- Use `terminal` for git, builds, tests, and inspection. Run the relevant "
-    "tests/linter/build and confirm they pass before claiming the work is done.\n"
-    "- Terminal state persists across calls: current directory and exported "
-    "environment variables carry forward. Activate a virtualenv or export setup "
-    "vars once, then reuse that state instead of re-sourcing it before every "
-    "test command.\n"
-    "- Fix root causes, not symptoms: when you find a bug, check sibling call "
-    "paths for the same flaw and fix the class, not just the reported site.\n"
-    "- When fixing linter/type errors on a file, stop after about three "
-    "attempts on the same file and ask the user rather than looping.\n"
-    "- Track multi-step work with `todo`. Reference code as `path:line` instead "
-    "of pasting whole files.\n"
-    "\n"
-    "Respect the user's repo: don't commit, push, or rewrite history unless "
-    "asked, and never read, print, or commit secrets — leave `.env` and "
-    "credential files alone unless the user explicitly asks. The Workspace "
-    "block below is a snapshot from session start — re-run `git status`/"
-    "`git branch` before relying on it. Be concise: lead with the change or "
-    "answer, not a preamble."
-)
-
-
-# ── Context profiles (declarative posture definitions) ──────────────────────
-
-
-@dataclass(frozen=True)
-class ContextProfile:
-    """A named operating posture. Pure data — consumers read these fields.
-
-    ``toolset``      — collapse to this toolset (+ enabled MCP) when no explicit
-                       selection is pinned; ``None`` keeps the platform default.
-    ``guidance``     — operating brief injected into the stable system prompt;
-                       ``""`` injects nothing.
-    ``model_hint``   — routing preference key for smart model routing
-                       (extension seam; not yet consumed by the router).
-    ``memory_policy``— memory namespace/weighting hint (extension seam).
-    ``compact_skill_categories`` — skill categories DEMOTED to names-only in
-                       the system-prompt skill index under the opt-in ``focus``
-                       mode. Never hidden: every skill name stays visible
-                       (so memory-anchored recall keeps working) — only the
-                       descriptions are dropped to cut index noise. Deny-list
-                       semantics so unknown/custom categories keep full
-                       entries.
-    """
-
-    name: str
-    toolset: Optional[str] = None
-    guidance: str = ""
-    model_hint: Optional[str] = None
-    memory_policy: str = "default"
-    compact_skill_categories: tuple[str, ...] = ()
-
-
-# Skill categories that are clearly not part of a coding workflow. Demoted to
-# names-only in the prompt's skill index under the opt-in ``focus`` mode only
-# (deny-list — anything not listed here, incl. custom user categories, keeps
-# full entries). Coding-adjacent categories (devops, github, mcp,
-# data-science, diagramming, research, security, …) are intentionally absent.
-_NON_CODING_SKILL_CATEGORIES = (
-    "apple", "communication", "cooking", "creative", "email", "finance",
-    "gaming", "gifs", "health", "media", "music", "note-taking",
-    "productivity", "shopping", "smart-home", "social-media", "travel",
-    "yuanbao",
-)
-
-
-GENERAL_PROFILE = ContextProfile(name="general")
-CODING_PROFILE = ContextProfile(
-    name="coding",
-    toolset=CODING_TOOLSET,
-    guidance=CODING_AGENT_GUIDANCE,
-    model_hint="coding",
-    memory_policy="project",
-    compact_skill_categories=_NON_CODING_SKILL_CATEGORIES,
-)
-
-_PROFILES: dict[str, ContextProfile] = {
-    GENERAL_PROFILE.name: GENERAL_PROFILE,
-    CODING_PROFILE.name: CODING_PROFILE,
-}
-
-
-def get_profile(name: str) -> ContextProfile:
-    """Return a registered profile, falling back to ``general``."""
-    return _PROFILES.get(name, GENERAL_PROFILE)
-
-
-# ── Helpers ─────────────────────────────────────────────────────────────────
-
-
-def _coding_mode(config: Optional[dict[str, Any]]) -> str:
-    """Return the normalized ``agent.coding_context`` mode (auto/focus/on/off)."""
-    if config is None:
-        try:
-            from hermes_cli.config import load_config
-
-            config = load_config()
-        except Exception:
-            config = {}
-    raw = ((config or {}).get("agent", {}) or {}).get("coding_context", "auto")
-    mode = str(raw).strip().lower()
-    if mode in {"focus", "strict", "lean"}:
-        return "focus"
-    if mode in {"on", "true", "yes", "1", "always"}:
-        return "on"
-    if mode in {"off", "false", "no", "0", "never"}:
-        return "off"
-    return "auto"
-
-
-def _coding_instructions(config: Optional[dict[str, Any]]) -> str:
-    """Standing operator instructions for the coding posture (config).
-
-    ``agent.coding_instructions`` — a string or list of strings appended to the
-    coding brief as an extra stable system block, so a user can pin project-wide
-    coding-workflow rules (e.g. "for UI work don't run tsc/lint until I approve;
-    clean the diff before committing") without editing the shipped brief.
-    Cache-safe: resolved once per session into the stable system-prompt tier,
-    like the rest of the posture.
-    """
-    if config is None:
-        try:
-            from hermes_cli.config import load_config
-
-            config = load_config()
-        except Exception:
-            config = {}
-    raw = ((config or {}).get("agent", {}) or {}).get("coding_instructions", "")
-    if isinstance(raw, (list, tuple)):
-        return "\n".join(str(item).strip() for item in raw if str(item).strip())
-    return str(raw or "").strip()
-
-
-def _resolve_cwd(cwd: Optional[str | Path]) -> Path:
-    if cwd:
-        return Path(cwd).expanduser()
-    try:
-        from agent.runtime_cwd import resolve_agent_cwd
-
-        return resolve_agent_cwd()
-    except Exception:
-        return Path(os.getcwd())
-
-
-def _git_root(cwd: Path) -> Optional[Path]:
-    current = cwd.resolve()
-    for parent in [current, *current.parents]:
-        if (parent / ".git").exists():
-            return parent
-    return None
-
-
-def _home() -> Optional[Path]:
-    try:
-        return Path.home().resolve()
-    except (OSError, RuntimeError):
-        return None
-
-
-def _marker_root(cwd: Path) -> Optional[Path]:
-    """Nearest ancestor that looks like a project root, or ``None``.
-
-    Walks up at most a few levels so a manifest in the workspace root counts
-    even when the user is in a subdirectory. ``$HOME`` itself is skipped — a
-    Makefile or AGENTS.md sitting in the home directory is global user config,
-    not a project-root signal.
-    """
-    current = cwd.resolve()
-    home = _home()
-    # Shared world-writable temp roots are never project roots: a stray
-    # manifest in /tmp (left by any process) must not flip every session
-    # whose cwd lives under the temp dir into the coding posture. Same
-    # reasoning as the $HOME skip below.
-    try:
-        temp_root = Path(tempfile.gettempdir()).resolve()
-    except Exception:
-        temp_root = None
-    for depth, parent in enumerate([current, *current.parents]):
-        if depth > 6:
-            break
-        if parent == home or (temp_root is not None and parent == temp_root):
-            continue
-        for marker in _PROJECT_MARKERS:
-            if (parent / marker).exists():
-                return parent
-    return None
-
-
-def _detect_profile_name(mode: str, platform: str, cwd_str: str) -> str:
-    """Resolve which profile applies.
-
-    ``auto``/``focus``: coding when the surface is interactive AND the cwd is a
-    code workspace (a git repo or a recognised project root). ``on``: always
-    coding. ``off``: always general.
-
-    A git repo rooted at ``$HOME`` (the dotfiles pattern) is NOT a workspace
-    signal — without the guard, every session anywhere under a dotfiles-managed
-    home directory would silently flip to the coding posture.
-
-    Detection is intentionally not memoized: it's a handful of ``stat`` calls,
-    and callers resolve the mode once per session anyway. Caching here would
-    risk a stale posture if a long-lived process (gateway/TUI) serves sessions
-    from different working directories.
-    """
-    if mode == "off":
-        return GENERAL_PROFILE.name
-    if mode == "on":
-        return CODING_PROFILE.name
-    if platform and platform.strip().lower() not in INTERACTIVE_CODING_PLATFORMS:
-        return GENERAL_PROFILE.name
-    cwd = Path(cwd_str)
-    # A recognized project root (manifest / AGENTS.md / .cursorrules) is a code
-    # workspace on its own — cheap stat checks, no scan.
-    if _marker_root(cwd) is not None:
-        return CODING_PROFILE.name
-    git_root = _git_root(cwd)
-    if git_root is not None and git_root == _home():
-        git_root = None  # dotfiles repo at $HOME — not a code workspace
-    # A bare git repo only counts when it actually holds code, so `git init` on a
-    # notes/writing/research folder stays in the general posture.
-    if git_root is not None and _has_code_files(git_root):
-        return CODING_PROFILE.name
-    return GENERAL_PROFILE.name
-
-
-# ── RuntimeMode (the seam) ──────────────────────────────────────────────────
-
-
-@dataclass(frozen=True)
-class RuntimeMode:
-    """The resolved operating posture for a session. Immutable by construction.
-
-    Built once via :func:`resolve_runtime_mode` and consumed by every domain
-    that cares about the coding/general distinction. Never mutate or re-resolve
-    mid-session — that would break the prompt cache.
-    """
-
-    profile: ContextProfile
-    surface: str
-    cwd: Path
-    # The normalized ``agent.coding_context`` mode this posture was resolved
-    # under (auto/focus/on/off). Toolset collapse is gated on ``focus``.
-    config_mode: str = "auto"
-    # The model id this session runs (e.g. "anthropic/claude-opus-4.8"). Used
-    # only to steer edit-format guidance toward the model's family — see
-    # ``_edit_format_line``. Fixed for the session, so cache-safe.
-    model: Optional[str] = None
-    # Standing operator instructions (``agent.coding_instructions``), appended
-    # as an extra stable system block. Empty unless the user configures it.
-    instructions: str = ""
-
-    @property
-    def kind(self) -> str:
-        return self.profile.name
-
-    @property
-    def is_coding(self) -> bool:
-        return self.profile.name == CODING_PROFILE.name
-
-    def toolset_selection(self, config: Optional[dict[str, Any]] = None) -> Optional[list[str]]:
-        """Toolset list for this posture, or ``None`` to keep the platform default.
-
-        Non-``None`` only under the opt-in ``focus`` mode. The default posture
-        is prompt-only: most strippable toolsets are off-by-default anyway, and
-        a user who explicitly enabled one (image-gen for frontend/game assets,
-        messaging for build notifications, …) keeps it while coding.
-
-        Callers apply this only when the user hasn't pinned an explicit
-        selection (``--toolsets``, ``HERMES_TUI_TOOLSETS``, …); they never
-        override a pin. Returns the profile's toolset plus enabled MCP servers.
-        """
-        if self.config_mode != "focus":
-            return None
-        if self.profile.toolset is None:
-            return None
-        return [self.profile.toolset, *_enabled_mcp_servers(config)]
-
-    def system_blocks(self) -> list[str]:
-        """Stable system-prompt blocks for this posture (brief + workspace).
-
-        The operating brief carries a model-family edit-format nudge appended
-        to it (one cached string, not a separate block) so the model is steered
-        toward the `patch` mode it handles best — see ``_edit_format_line``.
-        """
-        if not self.is_coding:
-            return []
-        blocks: list[str] = []
-        if self.profile.guidance:
-            brief = self.profile.guidance
-            edit_line = _edit_format_line(self.model)
-            if edit_line:
-                brief = f"{brief}\n{edit_line}"
-            blocks.append(brief)
-        workspace = build_coding_workspace_block(self.cwd)
-        if workspace:
-            blocks.append(workspace)
-        # Operator instructions ride their own block so the brief (block 0) stays
-        # byte-stable and cache-keyed independently of user config.
-        if self.instructions:
-            blocks.append(f"Operator instructions (from config):\n{self.instructions}")
-        return blocks
-
-    def compact_skill_categories(self) -> frozenset[str]:
-        """Skill categories to demote to names-only in the prompt's skill index.
-
-        Gated on the opt-in ``focus`` mode, like the toolset collapse: the
-        default posture leaves the skill index untouched. Users who didn't ask
-        for a lean prompt keep full entries for every category — index changes
-        under ``auto`` proved too surprising in practice, even names-only ones
-        (a demoted description is information the model no longer weighs when
-        deciding what to load).
-
-        Demoted — never hidden — even under ``focus``. An earlier revision
-        fully pruned these categories from the index, which caused silent
-        capability loss in a real workflow: agent-created skills are the
-        model's accumulated project memory (server-ops runbooks, learned
-        pitfalls, …), and models do not reliably reach for ``skills_list`` to
-        rediscover what the index stopped showing them. Names-only keeps every
-        skill loadable on recall while still cutting the description noise.
-        """
-        if not self.is_coding or self.config_mode != "focus":
-            return frozenset()
-        return frozenset(self.profile.compact_skill_categories)
-
-
-def resolve_runtime_mode(
-    *,
-    platform: Optional[str] = None,
-    cwd: Optional[str | Path] = None,
-    config: Optional[dict[str, Any]] = None,
-    model: Optional[str] = None,
-) -> RuntimeMode:
-    """Resolve the operating posture once. Cheap — a handful of ``stat`` calls.
-
-    This is the single entry point every domain should call. The returned
-    object is immutable and safe to cache for the session. Detection itself is
-    intentionally *not* memoized (see ``_detect_profile_name``) so a long-lived
-    process can't pin a stale posture; callers resolve once per session and
-    hold the result. ``model`` is recorded only to steer edit-format guidance;
-    it never affects detection.
-    """
-    resolved_cwd = _resolve_cwd(cwd)
-    mode = _coding_mode(config)
-    name = _detect_profile_name(
-        mode, (platform or "").strip().lower(), str(resolved_cwd)
-    )
-    return RuntimeMode(
-        profile=get_profile(name),
-        surface=platform or "",
-        cwd=resolved_cwd,
-        config_mode=mode,
-        model=model,
-        instructions=_coding_instructions(config),
-    )
-
-
-# ── Back-compat surface (thin wrappers over RuntimeMode) ────────────────────
-
-
-def is_coding_context(
-    *,
-    platform: Optional[str] = None,
-    cwd: Optional[str | Path] = None,
-    config: Optional[dict[str, Any]] = None,
-) -> bool:
-    """Whether Hermes should operate in its coding posture right now."""
-    return resolve_runtime_mode(platform=platform, cwd=cwd, config=config).is_coding
-
-
-def coding_selection(
-    *,
-    platform: Optional[str] = None,
-    cwd: Optional[str | Path] = None,
-    config: Optional[dict[str, Any]] = None,
-) -> Optional[list[str]]:
-    """Toolset selection for the coding posture.
-
-    ``None`` unless the user opted into ``focus`` mode AND the posture is
-    active — the default coding posture never overrides configured toolsets.
-    """
-    return resolve_runtime_mode(
-        platform=platform, cwd=cwd, config=config
-    ).toolset_selection(config)
-
-
-def coding_system_blocks(
-    *,
-    platform: Optional[str] = None,
-    cwd: Optional[str | Path] = None,
-    config: Optional[dict[str, Any]] = None,
-    model: Optional[str] = None,
-) -> list[str]:
-    """Stable system-prompt blocks for the current posture (empty when general).
-
-    ``model`` steers the brief's edit-format nudge toward the model's family.
-    """
-    return resolve_runtime_mode(
-        platform=platform, cwd=cwd, config=config, model=model
-    ).system_blocks()
-
-
-def coding_compact_skill_categories(
-    *,
-    platform: Optional[str] = None,
-    cwd: Optional[str | Path] = None,
-    config: Optional[dict[str, Any]] = None,
-) -> frozenset[str]:
-    """Skill categories the active posture demotes to names-only in the index.
-
-    Empty outside the coding posture and outside the opt-in ``focus`` mode —
-    the default posture never touches the skill index. Under ``focus``,
-    demoted — never hidden: every skill name stays in the index and remains
-    loadable via ``skill_view`` / ``skills_list``; only descriptions are
-    dropped.
-    """
-    return resolve_runtime_mode(
-        platform=platform, cwd=cwd, config=config
-    ).compact_skill_categories()
-
-
-def _enabled_mcp_servers(config: Optional[dict[str, Any]]) -> list[str]:
-    """Names of MCP servers the user has enabled — kept in the coding posture.
-
-    MCP servers (figma, browser, tophat, …) are explicitly configured and part
-    of the coding workflow, not noise to strip.
-    """
-    try:
-        from hermes_cli.config import read_raw_config
-        from hermes_cli.tools_config import _parse_enabled_flag
-
-        servers = read_raw_config().get("mcp_servers") or {}
-        return [
-            str(name)
-            for name, cfg in servers.items()
-            if isinstance(cfg, dict)
-            and _parse_enabled_flag(cfg.get("enabled", True), default=True)
-        ]
-    except Exception:
-        return []
-
-
-# ── git/workspace probe ─────────────────────────────────────────────────────
-
-
-def _git(cwd: Path, *args: str) -> str:
-    """``git -C <cwd> <args>`` → stripped stdout, or ``""`` on any failure.
-
-    Uses the shared :func:`bounded_git_probe` so the post-kill cleanup is bounded
-    on Windows — a plain ``subprocess.run(timeout=...)`` here deadlocked the agent
-    turn inside ``build_coding_workspace_block`` when a killed git left a suspended
-    descendant holding the pipe handles (issue #66037).
-    """
-    return bounded_git_probe(["git", "-C", str(cwd), *args], timeout=_GIT_TIMEOUT)
-
-
-def _parse_status(porcelain: str) -> tuple[dict[str, str], dict[str, int]]:
-    """Parse ``git status --porcelain=2 --branch`` into branch + counts."""
-    branch: dict[str, str] = {}
-    counts = {"staged": 0, "modified": 0, "untracked": 0, "conflicts": 0}
-    for line in porcelain.splitlines():
-        if line.startswith("# branch.head"):
-            branch["head"] = line.split(maxsplit=2)[-1]
-        elif line.startswith("# branch.upstream"):
-            branch["upstream"] = line.split(maxsplit=2)[-1]
-        elif line.startswith("# branch.ab"):
-            parts = line.split()
-            branch["ahead"], branch["behind"] = parts[2].lstrip("+"), parts[3].lstrip("-")
-        elif line.startswith(("1 ", "2 ")):
-            xy = line.split(maxsplit=2)[1]
-            if xy[0] != ".":
-                counts["staged"] += 1
-            if xy[1] != ".":
-                counts["modified"] += 1
-        elif line.startswith("u "):
-            counts["conflicts"] += 1
-        elif line.startswith("? "):
-            counts["untracked"] += 1
-    return branch, counts
-
-
-def _read_small(path: Path) -> str:
-    """Read a small text file, or ``""`` — never raises, never reads huge files."""
-    try:
-        if not path.is_file() or path.stat().st_size > _MAX_FACT_FILE_BYTES:
-            return ""
-        return path.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return ""
-
-
-@dataclass(frozen=True)
-class ProjectFacts:
-    """Structured project facts — the model's verify loop, detected once.
-
-    The same data that feeds the workspace snapshot, exposed structurally so
-    non-prompt consumers (e.g. the desktop verify UI) read it instead of
-    re-detecting and drifting from the prompt.
-    """
-
-    manifests: list[str]
-    package_managers: list[str]
-    verify_commands: list[str]
-    context_files: list[str]
-
-
-def detect_project_facts(root: Path) -> ProjectFacts:
-    """Detect manifests, package manager(s), verify commands, and context files.
-
-    Cheap: stat calls plus reads of a couple of small files. The single source
-    of truth for both the prompt snapshot (:func:`_project_facts`) and the
-    gateway's ``project.facts`` — so the UI never re-sniffs verify commands.
-    """
-    manifests = [m for m in _PROJECT_MARKERS if m not in _CONTEXT_FILES and (root / m).is_file()]
-    package_managers = list(
-        dict.fromkeys(pm for lock, pm in (*_PY_LOCKFILES, *_JS_LOCKFILES) if (root / lock).is_file())
-    )
-
-    verify: list[str] = []
-    if (root / "scripts" / "run_tests.sh").is_file():
-        verify.append("scripts/run_tests.sh")
-    if (root / "package.json").is_file():
-        try:
-            scripts = json.loads(_read_small(root / "package.json") or "{}").get("scripts") or {}
-        except (json.JSONDecodeError, AttributeError):
-            scripts = {}
-        js_pm = next((pm for lock, pm in _JS_LOCKFILES if (root / lock).is_file()), "npm")
-        verify.extend(f"{js_pm} run {name}" for name in _VERIFY_TARGETS if name in scripts)
-    if (root / "pytest.ini").is_file() or "[tool.pytest" in _read_small(root / "pyproject.toml"):
-        verify.append("pytest")
-    makefile = _read_small(root / "Makefile")
-    if makefile:
-        verify.extend(
-            f"make {name}" for name in _VERIFY_TARGETS
-            if re.search(rf"^{re.escape(name)}\s*:", makefile, re.MULTILINE)
-        )
-
-    return ProjectFacts(
-        manifests=manifests,
-        package_managers=package_managers,
-        verify_commands=list(dict.fromkeys(verify))[:_MAX_VERIFY_COMMANDS],
-        context_files=[c for c in _CONTEXT_FILES if (root / c).is_file()],
-    )
-
-
-def _project_facts(root: Path) -> list[str]:
-    """Render :func:`detect_project_facts` as workspace-snapshot lines.
-
-    Hands the model its *verify loop* up front — which manifest, which package
-    manager, and the exact test/lint/build commands — instead of making it
-    rediscover them every session. Built once at prompt-build time; the string
-    output must stay byte-stable to preserve the prompt cache.
-    """
-    f = detect_project_facts(root)
-    facts: list[str] = []
-
-    if f.manifests:
-        line = f"- Project: {', '.join(f.manifests[:6])}"
-        if f.package_managers:
-            line += f" ({'/'.join(f.package_managers)})"
-        facts.append(line)
-    if f.verify_commands:
-        facts.append(f"- Verify: {'; '.join(f.verify_commands)}")
-    if f.context_files:
-        facts.append(f"- Context files: {', '.join(f.context_files)}")
-
-    return facts
-
-
-def project_facts_for(cwd: Optional[str | Path] = None) -> Optional[dict[str, Any]]:
-    """Structured project facts for ``cwd`` — ``None`` outside a workspace.
-
-    Same detection the system-prompt snapshot uses (git root, else marker root),
-    exposed for non-prompt consumers (the desktop verify UI) so they never
-    re-derive "are we coding?" or duplicate the verify-command sniffing.
-    """
-    resolved = _resolve_cwd(cwd)
-    root = _git_root(resolved) or _marker_root(resolved)
-    if root is None:
-        return None
-
-    f = detect_project_facts(root)
-    return {
-        "root": str(root),
-        "manifests": f.manifests,
-        "packageManagers": f.package_managers,
-        "verifyCommands": f.verify_commands,
-        "contextFiles": f.context_files,
-    }
-
-
-def build_coding_workspace_block(cwd: Optional[str | Path] = None) -> str:
-    """Workspace snapshot for the system prompt (empty outside a workspace).
-
-    Git state (branch/status/commits) when the cwd is in a repo, plus detected
-    project facts (manifest, package manager, verify commands, context files)
-    — so marker-only (non-git) projects still get a snapshot.
-    """
-    resolved = _resolve_cwd(cwd)
-    git_root = _git_root(resolved)
-    root = git_root or _marker_root(resolved)
-    if root is None:
-        return ""
-
-    lines = ["Workspace (snapshot at session start — re-check with `git` before acting on it):"]
-    lines.append(f"- Root: {root}")
-
-    if git_root is not None:
-        branch, counts = _parse_status(_git(root, "status", "--porcelain=2", "--branch"))
-        head = branch.get("head", "")
-        if head and head != "(detached)":
-            line = f"- Branch: {head}"
-            if branch.get("upstream"):
-                line += f" \u2192 {branch['upstream']}"
-                ahead, behind = branch.get("ahead", "0"), branch.get("behind", "0")
-                if ahead != "0" or behind != "0":
-                    line += f" (ahead {ahead}, behind {behind})"
-            lines.append(line)
-        elif head == "(detached)":
-            lines.append("- Branch: (detached HEAD)")
-
-        # Linked worktree: the per-worktree git dir differs from the shared common dir.
-        # We surface the fact that it's a worktree (so the model knows branches/stashes
-        # are shared state) but deliberately do NOT expose the primary tree path —
-        # giving the model a second absolute path causes it to sometimes run commands
-        # in the wrong directory.
-        git_dir, common_dir = _git(root, "rev-parse", "--git-dir"), _git(root, "rev-parse", "--git-common-dir")
-        if git_dir and common_dir and Path(git_dir).resolve() != Path(common_dir).resolve():
-            lines.append("- Worktree: linked (git state shared with primary tree)")
-
-        dirty = [f"{n} {label}" for label, n in (
-            ("staged", counts["staged"]), ("modified", counts["modified"]),
-            ("untracked", counts["untracked"]), ("conflicts", counts["conflicts"]),
-        ) if n]
-        lines.append(f"- Status: {', '.join(dirty) if dirty else 'clean'}")
-
-        recent = _git(root, "log", "-3", "--pretty=%h %s")
-        if recent:
-            lines.append("- Recent commits:")
-            lines.extend(f"    {c}" for c in recent.splitlines())
-
-    lines.extend(_project_facts(root))
-    return "\n".join(lines)
@@ -1,156 +0,0 @@
-"""Live session context-window breakdown for UI surfaces.
-
-Estimates how the next provider request is composed: system prompt tiers,
-tool schemas, and conversation history. Uses the same rough char/4 heuristic
-as ``agent.model_metadata.estimate_request_tokens_rough`` so numbers align
-with compression thresholds — not exact tokenizer counts.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-from typing import Any, Dict, List, Optional, Sequence, Tuple
-
-_SKILLS_BLOCK_RE = re.compile(r"<available_skills>.*?</available_skills>", re.DOTALL)
-
-_SUBAGENT_TOOL_NAMES = frozenset({"delegate_task"})
-
-_CATEGORY_COLORS = {
-    "system_prompt": "var(--context-usage-system)",
-    "tool_definitions": "var(--context-usage-tools)",
-    "rules": "var(--context-usage-rules)",
-    "skills": "var(--context-usage-skills)",
-    "mcp": "var(--context-usage-mcp)",
-    "subagent_definitions": "var(--context-usage-subagents)",
-    "memory": "var(--context-usage-memory)",
-    "conversation": "var(--context-usage-conversation)",
-}
-
-
-def _chars_to_tokens(text: str) -> int:
-    if not text:
-        return 0
-    return (len(text) + 3) // 4
-
-
-def _json_tokens(value: Any) -> int:
-    if not value:
-        return 0
-    return _chars_to_tokens(json.dumps(value, ensure_ascii=False))
-
-
-def _tool_name(tool: dict) -> str:
-    fn = tool.get("function") if isinstance(tool, dict) else None
-    if isinstance(fn, dict):
-        return str(fn.get("name") or "")
-    return str(tool.get("name") or "")
-
-
-def _split_tools(tools: Sequence[dict]) -> Tuple[List[dict], List[dict], List[dict]]:
-    builtin: List[dict] = []
-    mcp: List[dict] = []
-    subagent: List[dict] = []
-    for tool in tools:
-        name = _tool_name(tool)
-        if name.startswith("mcp_"):
-            mcp.append(tool)
-        elif name in _SUBAGENT_TOOL_NAMES:
-            subagent.append(tool)
-        else:
-            builtin.append(tool)
-    return builtin, mcp, subagent
-
-
-def _memory_blocks(agent: Any) -> Tuple[str, str]:
-    memory_block = ""
-    user_block = ""
-    store = getattr(agent, "_memory_store", None)
-    if store is None:
-        return memory_block, user_block
-    try:
-        if getattr(agent, "_memory_enabled", True):
-            memory_block = store.format_for_system_prompt("memory") or ""
-        if getattr(agent, "_user_profile_enabled", True):
-            user_block = store.format_for_system_prompt("user") or ""
-    except Exception:
-        pass
-    return memory_block, user_block
-
-
-def _strip_blocks(text: str, *blocks: str) -> str:
-    out = text
-    for block in blocks:
-        if block:
-            out = out.replace(block, "")
-    return out.strip()
-
-
-def compute_session_context_breakdown(
-    agent: Any,
-    messages: Optional[List[dict]] = None,
-) -> Dict[str, Any]:
-    """Return a Cursor-style context usage breakdown for one live agent."""
-    from agent.model_metadata import estimate_messages_tokens_rough
-    from agent.system_prompt import build_system_prompt_parts
-
-    parts = build_system_prompt_parts(agent)
-    stable = parts.get("stable", "") or ""
-    context = parts.get("context", "") or ""
-    volatile = parts.get("volatile", "") or ""
-
-    skills_match = _SKILLS_BLOCK_RE.search(stable)
-    skills_index = skills_match.group(0) if skills_match else ""
-
-    memory_block, user_block = _memory_blocks(agent)
-    memory_text = "\n\n".join(part for part in (memory_block, user_block) if part).strip()
-
-    system_core = _strip_blocks(stable, skills_index)
-    system_tail = _strip_blocks(volatile, memory_block, user_block)
-    system_prompt_text = "\n\n".join(part for part in (system_core, system_tail) if part).strip()
-
-    tools = list(getattr(agent, "tools", None) or [])
-    builtin_tools, mcp_tools, subagent_tools = _split_tools(tools)
-
-    conversation_tokens = estimate_messages_tokens_rough(messages or [])
-
-    categories = [
-        ("system_prompt", "System prompt", _chars_to_tokens(system_prompt_text)),
-        ("tool_definitions", "Tool definitions", _json_tokens(builtin_tools)),
-        ("rules", "Rules", _chars_to_tokens(context)),
-        ("skills", "Skills", _chars_to_tokens(skills_index)),
-        ("mcp", "MCP", _json_tokens(mcp_tools)),
-        ("subagent_definitions", "Subagent definitions", _json_tokens(subagent_tools)),
-        ("memory", "Memory", _chars_to_tokens(memory_text)),
-        ("conversation", "Conversation", conversation_tokens),
-    ]
-
-    estimated_total = sum(tokens for _, _, tokens in categories)
-
-    comp = getattr(agent, "context_compressor", None)
-    context_max = int(getattr(comp, "context_length", 0) or 0) if comp else 0
-    measured_used = int(getattr(comp, "last_prompt_tokens", 0) or 0) if comp else 0
-    context_used = measured_used if measured_used > 0 else estimated_total
-    context_percent = (
-        max(0, min(100, round(context_used / context_max * 100)))
-        if context_max
-        else 0
-    )
-
-    return {
-        "categories": [
-            {
-                "color": _CATEGORY_COLORS.get(category_id, "var(--ui-text-tertiary)"),
-                "id": category_id,
-                "label": label,
-                "tokens": tokens,
-            }
-            for category_id, label, tokens in categories
-            if tokens > 0
-        ],
-        "context_max": context_max,
-        "context_percent": context_percent,
-        "context_used": context_used,
-        "estimated_total": estimated_total,
-        "model": getattr(agent, "model", "") or "",
-    }
@@ -1,278 +0,0 @@
-"""Abstract base class for pluggable context engines.
-
-A context engine controls how conversation context is managed when
-approaching the model's token limit. The built-in ContextCompressor
-is the default implementation. Third-party engines (e.g. LCM) can
-replace it via the plugin system or by being placed in the
-``plugins/context_engine/<name>/`` directory.
-
-Selection is config-driven: ``context.engine`` in config.yaml.
-Default is ``"compressor"`` (the built-in). Only one engine is active.
-
-The engine is responsible for:
-  - Deciding when compaction should fire
-  - Performing compaction (summarization, DAG construction, etc.)
-  - Optionally exposing tools the agent can call (e.g. lcm_grep)
-  - Tracking token usage from API responses
-
-Lifecycle:
-  1. Engine is instantiated and registered (plugin register() or default)
-  2. on_session_start() called when a conversation begins
-  3. update_from_response() called after each API response with usage data
-  4. should_compress() checked after each turn
-  5. compress() called when should_compress() returns True
-  6. on_session_end() called at real session boundaries (CLI exit, /reset,
-     gateway session expiry) — NOT per-turn
-"""
-
-from abc import ABC, abstractmethod
-from typing import Any, Dict, List, Optional
-
-from agent.redact import redact_sensitive_text
-
-
-MEMORY_CONTEXT_MAX_CHARS = 6_000
-_MEMORY_CONTEXT_HEAD_CHARS = 4_000
-_MEMORY_CONTEXT_TAIL_CHARS = 1_500
-_MEMORY_CONTEXT_TRUNCATION_MARKER = "\n...[memory provider context truncated]...\n"
-
-
-def sanitize_memory_context(memory_context: str) -> str:
-    """Prepare provider context for a context-engine/LLM egress boundary."""
-    sanitized = redact_sensitive_text(
-        memory_context.strip(),
-        force=True,
-        redact_url_credentials=True,
-    )
-    if len(sanitized) <= MEMORY_CONTEXT_MAX_CHARS:
-        return sanitized
-    return (
-        sanitized[:_MEMORY_CONTEXT_HEAD_CHARS]
-        + _MEMORY_CONTEXT_TRUNCATION_MARKER
-        + sanitized[-_MEMORY_CONTEXT_TAIL_CHARS:]
-    )
-
-
-class ContextEngine(ABC):
-    """Base class all context engines must implement."""
-
-    # -- Identity ----------------------------------------------------------
-
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """Short identifier (e.g. 'compressor', 'lcm')."""
-
-    # -- Token state (read by run_agent.py for display/logging) ------------
-    #
-    # Engines MUST maintain these. run_agent.py reads them directly.
-
-    last_prompt_tokens: int = 0
-    last_completion_tokens: int = 0
-    last_total_tokens: int = 0
-    threshold_tokens: int = 0
-    context_length: int = 0
-    compression_count: int = 0
-
-    # -- Compaction parameters (read by run_agent.py for preflight) --------
-    #
-    # These control the preflight compression check.  Subclasses may
-    # override via __init__ or property; defaults are sensible for most
-    # engines.
-    #
-    # protect_first_n semantics (since PR #13754): count of non-system head
-    # messages always preserved verbatim, IN ADDITION to the system prompt
-    # which is always implicitly protected.  Default 3 keeps the
-    # historical "system + first 3 non-system messages" head shape.
-
-    threshold_percent: float = 0.75
-    protect_first_n: int = 3
-    protect_last_n: int = 6
-
-    # -- Core interface ----------------------------------------------------
-
-    @abstractmethod
-    def update_from_response(self, usage: Dict[str, Any]) -> None:
-        """Update tracked token usage from an API response.
-
-        Called after every LLM call with a normalized usage dict. The legacy
-        keys ``prompt_tokens``, ``completion_tokens``, and ``total_tokens``
-        are always present. Newer hosts also include canonical buckets:
-        ``input_tokens``, ``output_tokens``, ``cache_read_tokens``,
-        ``cache_write_tokens``, and ``reasoning_tokens``. Engines should
-        treat those fields as optional for compatibility with older hosts.
-        """
-
-    @abstractmethod
-    def should_compress(self, prompt_tokens: int = None) -> bool:
-        """Return True if compaction should fire this turn."""
-
-    @abstractmethod
-    def compress(
-        self,
-        messages: List[Dict[str, Any]],
-        current_tokens: Optional[int] = None,
-        focus_topic: Optional[str] = None,
-        force: bool = False,
-        memory_context: str = "",
-    ) -> List[Dict[str, Any]]:
-        """Compact the message list and return the new message list.
-
-        This is the main entry point. The engine receives the full message
-        list and returns a (possibly shorter) list that fits within the
-        context budget. The implementation is free to summarize, build a
-        DAG, or do anything else — as long as the returned list is a valid
-        OpenAI-format message sequence.
-
-        Args:
-            focus_topic: Optional topic string from manual ``/compress <focus>``.
-                Engines that support guided compression should prioritise
-                preserving information related to this topic.  Engines that
-                don't support it may simply ignore this argument.
-            force: Whether a user-requested compression should bypass an
-                engine-owned cooldown. Engines without cooldowns may ignore it.
-            memory_context: Text returned by memory providers immediately before
-                compaction. Summarizing engines should include non-empty text in
-                their handoff prompt. Older engines may omit this parameter; the
-                host filters unsupported optional arguments by signature.
-        """
-
-    # -- Optional: pre-flight check ----------------------------------------
-
-    def should_compress_preflight(self, messages: List[Dict[str, Any]]) -> bool:
-        """Quick rough check before the API call (no real token count yet).
-
-        Default returns False (skip pre-flight). Override if your engine
-        can do a cheap estimate.
-        """
-        return False
-
-    def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
-        """Return True when preflight should trust recent real usage instead.
-
-        Built-in compression uses this to avoid re-compacting from known-noisy
-        rough estimates after a compressed request has already fit. Third-party
-        engines can ignore it safely.
-        """
-        return False
-
-    # -- Optional: manual /compress preflight ------------------------------
-
-    def has_content_to_compress(self, messages: List[Dict[str, Any]]) -> bool:
-        """Quick check: is there anything in ``messages`` that can be compacted?
-
-        Used by the gateway ``/compress`` command as a preflight guard —
-        returning False lets the gateway report "nothing to compress yet"
-        without making an LLM call.
-
-        Default returns True (always attempt).  Engines with a cheap way
-        to introspect their own head/tail boundaries should override this
-        to return False when the transcript is still entirely protected.
-        """
-        return True
-
-    # -- Optional: session lifecycle ---------------------------------------
-
-    def on_session_start(self, session_id: str, **kwargs) -> None:
-        """Called when a new conversation session begins.
-
-        Use this to load persisted state (DAG, store) for the session.
-        kwargs may include hermes_home, platform, model, etc.
-        """
-
-    def on_session_end(self, session_id: str, messages: List[Dict[str, Any]]) -> None:
-        """Called at real session boundaries (CLI exit, /reset, gateway expiry).
-
-        Use this to flush state, close DB connections, etc.
-        NOT called per-turn — only when the session truly ends.
-        """
-
-    def on_session_reset(self) -> None:
-        """Called on /new or /reset. Reset per-session state.
-
-        Default resets compression_count and token tracking.
-        """
-        self.last_prompt_tokens = 0
-        self.last_completion_tokens = 0
-        self.last_total_tokens = 0
-        self.compression_count = 0
-
-    # -- Optional: tools ---------------------------------------------------
-
-    def get_tool_schemas(self) -> List[Dict[str, Any]]:
-        """Return tool schemas this engine provides to the agent.
-
-        Default returns empty list (no tools). LCM would return schemas
-        for lcm_grep, lcm_describe, lcm_expand here.
-        """
-        return []
-
-    def handle_tool_call(self, name: str, args: Dict[str, Any], **kwargs) -> str:
-        """Handle a tool call from the agent.
-
-        Only called for tool names returned by get_tool_schemas().
-        Must return a JSON string.
-
-        kwargs may include:
-          messages: the current in-memory message list (for live ingestion)
-        """
-        import json
-        return json.dumps({"error": f"Unknown context engine tool: {name}"})
-
-    # -- Optional: status / display ----------------------------------------
-
-    def get_status(self) -> Dict[str, Any]:
-        """Return status dict for display/logging.
-
-        Default returns the standard fields run_agent.py expects.
-        """
-        # Clamp the -1 "compression just ran, awaiting real usage" sentinel
-        # (set by conversation_compression) to 0 so status readers don't see a
-        # raw -1 or a negative usage_percent on the transitional turn. Mirrors
-        # the CLI/gateway status-bar paths (cli.py, tui_gateway/server.py).
-        last_prompt = self.last_prompt_tokens if self.last_prompt_tokens > 0 else 0
-        return {
-            "last_prompt_tokens": last_prompt,
-            "threshold_tokens": self.threshold_tokens,
-            "context_length": self.context_length,
-            "usage_percent": (
-                min(100, last_prompt / self.context_length * 100)
-                if self.context_length else 0
-            ),
-            "compression_count": self.compression_count,
-        }
-
-    # -- Optional: model switch support ------------------------------------
-
-    def update_model(
-        self,
-        model: str,
-        context_length: int,
-        base_url: str = "",
-        api_key: str = "",
-        provider: str = "",
-        api_mode: str = "",
-    ) -> None:
-        """Called when the user switches models or on fallback activation.
-
-        Default updates context_length and recalculates threshold_tokens
-        from threshold_percent. Override if your engine needs more
-        (e.g. recalculate DAG budgets, switch summary models).
-        """
-        self.context_length = context_length
-        # Apply per-model threshold overrides if set (longest substring match).
-        # Falls back to _config_threshold_percent (the raw config value) when
-        # no override matches. Plugin engines that override update_model() can
-        # call resolve_model_threshold() for the same logic.
-        from agent.context_compressor import resolve_model_threshold
-        if not hasattr(self, "_config_threshold_percent"):
-            # Snapshot the pre-override percent ONCE so repeated model
-            # switches fall back to the engine's configured value, not the
-            # previous model's override.
-            self._config_threshold_percent = self.threshold_percent
-        self._base_threshold_percent = resolve_model_threshold(
-            model, getattr(self, "model_thresholds", {}),
-            self._config_threshold_percent,
-        )
-        self.threshold_percent = self._base_threshold_percent
-        self.threshold_tokens = int(context_length * self.threshold_percent)
@@ -12,14 +12,12 @@ from pathlib import Path
 from typing import Awaitable, Callable

 from agent.model_metadata import estimate_tokens_rough
-from hermes_cli._subprocess_compat import IS_WINDOWS, windows_hide_flags

-_QUOTED_REFERENCE_VALUE = r'(?:`[^`\n]+`|"[^"\n]+"|\'[^\'\n]+\')'
 REFERENCE_PATTERN = re.compile(
-    rf"(?<![\w/])@(?:(?P<simple>diff|staged)\b|(?P<kind>file|folder|git|url):(?P<value>{_QUOTED_REFERENCE_VALUE}(?::\d+(?:-\d+)?)?|\S+))"
+    r"(?<![\w/])@(?:(?P<simple>diff|staged)\b|(?P<kind>file|folder|git|url):(?P<value>\S+))"
 )
 TRAILING_PUNCTUATION = ",.;!?"
-_SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube", ".docker", ".azure", ".config/gh")
+_SENSITIVE_HOME_DIRS = (".ssh", ".aws", ".gnupg", ".kube")
 _SENSITIVE_HERMES_DIRS = (Path("skills") / ".hub",)
 _SENSITIVE_HOME_FILES = (
    Path(".ssh") / "authorized_keys",
@@ -83,10 +81,14 @@ def parse_context_references(message: str) -> list[ContextReference]:
        value = _strip_trailing_punctuation(match.group("value") or "")
        line_start = None
        line_end = None
-        target = _strip_reference_wrappers(value)
+        target = value

        if kind == "file":
-            target, line_start, line_end = _parse_file_reference_value(value)
+            range_match = re.match(r"^(?P<path>.+?):(?P<start>\d+)(?:-(?P<end>\d+))?$", value)
+            if range_match:
+                target = range_match.group("path")
+                line_start = int(range_match.group("start"))
+                line_end = int(range_match.group("end") or range_match.group("start"))

        refs.append(
            ContextReference(
@@ -152,24 +154,13 @@ async def preprocess_context_references_async(
    blocks: list[str] = []
    injected_tokens = 0

-    # Expand all references concurrently. Each _expand_reference is independent
-    # (no shared state during expansion) — a message with several @url: refs
-    # would otherwise pay one full web_extract round-trip per ref in series.
-    # gather preserves positional order, so we reassemble warnings/blocks in the
-    # original ref order exactly as the prior serial loop did; the token-budget
-    # check below is unchanged (it runs once, after all refs are expanded).
-    expanded = await asyncio.gather(
-        *(
-            _expand_reference(
-                ref,
-                cwd_path,
-                url_fetcher=url_fetcher,
-                allowed_root=allowed_root_path,
-            )
-            for ref in refs
+    for ref in refs:
+        warning, block = await _expand_reference(
+            ref,
+            cwd_path,
+            url_fetcher=url_fetcher,
+            allowed_root=allowed_root_path,
        )
-    )
-    for warning, block in expanded:
        if warning:
            warnings.append(warning)
        if block:
@@ -258,14 +249,7 @@ def _expand_file_reference(
    if not path.is_file():
        return f"{ref.raw}: path is not a file", None
    if _is_binary_file(path):
-        # A binary file can't be inlined as text, but it IS on disk (the agent's
-        # tools run where this resolves — the local cwd, or the staged copy in a
-        # remote session workspace). Returning a bare "not supported" warning
-        # with no content was a dead end: the model saw a failure and gave up
-        # (told the user the file type wasn't supported). Instead, hand it an
-        # actionable block — the path, type, size, and a nudge to use its tools —
-        # so it can read/convert/view the file itself.
-        return None, _binary_reference_block(ref, path)
+        return f"{ref.raw}: binary files are not supported", None

    text = path.read_text(encoding="utf-8")
    if ref.line_start is not None:
@@ -302,19 +286,12 @@ def _expand_git_reference(
    args: list[str],
    label: str,
 ) -> tuple[str | None, str | None]:
-    _popen_kwargs = {"creationflags": windows_hide_flags()} if IS_WINDOWS else {}
-    try:
-        result = subprocess.run(
-            ["git", *args],
-            cwd=cwd,
-            capture_output=True,
-            text=True,
-            timeout=30,
-            stdin=subprocess.DEVNULL,
-            **_popen_kwargs,
-        )
-    except subprocess.TimeoutExpired:
-        return f"{ref.raw}: git command timed out (30s)", None
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+    )
    if result.returncode != 0:
        stderr = (result.stderr or "").strip() or "git command failed"
        return f"{ref.raw}: {stderr}", None
@@ -339,9 +316,9 @@ async def _fetch_url_content(
 async def _default_url_fetcher(url: str) -> str:
    from tools.web_tools import web_extract_tool

-    raw = await web_extract_tool([url], format="markdown")
+    raw = await web_extract_tool([url], format="markdown", use_llm_processing=True)
    payload = json.loads(raw)
-    docs = payload.get("results", [])
+    docs = payload.get("data", {}).get("documents", [])
    if not docs:
        return ""
    doc = docs[0]
@@ -362,9 +339,10 @@ def _resolve_path(cwd: Path, target: str, *, allowed_root: Path | None = None) -


 def _ensure_reference_path_allowed(path: Path) -> None:
-    from hermes_constants import get_hermes_home
    home = Path(os.path.expanduser("~")).resolve()
-    hermes_home = get_hermes_home().resolve()
+    hermes_home = Path(
+        os.getenv("HERMES_HOME", str(home / ".hermes"))
+    ).expanduser().resolve()

    blocked_exact = {home / rel for rel in _SENSITIVE_HOME_FILES}
    blocked_exact.add(hermes_home / ".env")
@@ -381,37 +359,6 @@ def _ensure_reference_path_allowed(path: Path) -> None:
            continue
        raise ValueError("path is a sensitive credential or internal Hermes path and cannot be attached")

-    # Anchor to the canonical read deny-list (agent/file_safety.get_read_block_error),
-    # the single source of truth used by the file/terminal read path. The narrow
-    # list above predates that guard and never caught the real credential stores:
-    # provider keys (auth.json), Anthropic OAuth tokens (.anthropic_oauth.json),
-    # MCP OAuth material (mcp-tokens/), webhook HMAC secrets, and project-local
-    # .env files. That gap matters because the gateway feeds UNTRUSTED remote
-    # message text into reference expansion, so `@file:~/.hermes/auth.json` from a
-    # chat peer would otherwise read the operator's keys straight into context.
-    # Routing through the canonical guard closes the gap today and keeps this path
-    # protected automatically whenever that deny-list grows.
-    try:
-        from agent.file_safety import get_read_block_error
-
-        if get_read_block_error(str(path)) is not None:
-            raise ValueError(
-                "path is a sensitive credential or internal Hermes path and cannot be attached"
-            )
-    except ValueError:
-        raise
-    except Exception:
-        # Fail CLOSED on the security path. This guard exists specifically to
-        # cover credential stores the narrow list above misses (auth.json,
-        # .anthropic_oauth.json, mcp-tokens/, ...). If the canonical lookup
-        # ever fails, silently falling through would re-open that exact hole —
-        # the gateway feeds untrusted remote text here, so a probe could then
-        # attach the operator's keys. Refuse instead: a spurious block on a
-        # legitimate file is a recoverable annoyance; a leaked credential is not.
-        raise ValueError(
-            "path could not be verified against the credential deny-list and cannot be attached"
-        )
-

 def _strip_trailing_punctuation(value: str) -> str:
    stripped = value.rstrip(TRAILING_PUNCTUATION)
@@ -425,38 +372,6 @@ def _strip_trailing_punctuation(value: str) -> str:
    return stripped


-def _strip_reference_wrappers(value: str) -> str:
-    if len(value) >= 2 and value[0] == value[-1] and value[0] in "`\"'":
-        return value[1:-1]
-    return value
-
-
-def _parse_file_reference_value(value: str) -> tuple[str, int | None, int | None]:
-    quoted_match = re.match(
-        r'^(?P<quote>`|"|\')(?P<path>.+?)(?P=quote)(?::(?P<start>\d+)(?:-(?P<end>\d+))?)?$',
-        value,
-    )
-    if quoted_match:
-        line_start = quoted_match.group("start")
-        line_end = quoted_match.group("end")
-        return (
-            quoted_match.group("path"),
-            int(line_start) if line_start is not None else None,
-            int(line_end or line_start) if line_start is not None else None,
-        )
-
-    range_match = re.match(r"^(?P<path>.+?):(?P<start>\d+)(?:-(?P<end>\d+))?$", value)
-    if range_match:
-        line_start = int(range_match.group("start"))
-        return (
-            range_match.group("path"),
-            line_start,
-            int(range_match.group("end") or range_match.group("start")),
-        )
-
-    return _strip_reference_wrappers(value), None, None
-
-
 def _remove_reference_tokens(message: str, refs: list[ContextReference]) -> str:
    pieces: list[str] = []
    cursor = 0
@@ -528,18 +443,14 @@ def _iter_visible_entries(path: Path, cwd: Path, limit: int) -> list[Path]:


 def _rg_files(path: Path, cwd: Path, limit: int) -> list[Path] | None:
-    _popen_kwargs = {"creationflags": windows_hide_flags()} if IS_WINDOWS else {}
    try:
        result = subprocess.run(
            ["rg", "--files", str(path.relative_to(cwd))],
            cwd=cwd,
            capture_output=True,
            text=True,
-            timeout=10,
-            stdin=subprocess.DEVNULL,
-            **_popen_kwargs,
        )
-    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+    except FileNotFoundError:
        return None
    if result.returncode != 0:
        return None
@@ -547,30 +458,6 @@ def _rg_files(path: Path, cwd: Path, limit: int) -> list[Path] | None:
    return files[:limit]


-def _human_bytes(n: int) -> str:
-    size = float(n)
-    for unit in ("B", "KB", "MB", "GB"):
-        if size < 1024 or unit == "GB":
-            return f"{int(size)} {unit}" if unit == "B" else f"{size:.1f} {unit}"
-        size /= 1024
-    return f"{size:.1f} GB"
-
-
-def _binary_reference_block(ref: ContextReference, path: Path) -> str:
-    mime, _ = mimetypes.guess_type(path.name)
-    mime = mime or "application/octet-stream"
-    try:
-        size = _human_bytes(path.stat().st_size)
-    except OSError:
-        size = "unknown size"
-    return (
-        f"📎 {ref.raw} ({mime}, {size}) — binary file, not inlined as text. "
-        f"It is available on disk at `{path}`. Use your tools to work with it "
-        f"(read or convert it, extract its text, or view/render it as needed); "
-        f"do not tell the user the file type is unsupported."
-    )
-
-
 def _file_metadata(path: Path) -> str:
    if _is_binary_file(path):
        return f"{path.stat().st_size} bytes"
--- a/Show More
+++ b/Show More