fix: skip tests when atroposlib/minisweagent unavailable in CI

- test_agent_loop_tool_calling.py: import atroposlib at module level
  to trigger skip (environments.agent_loop is now importable without
  atroposlib due to __init__.py graceful fallback)
- test_modal_sandbox_fixes.py: skip TestToolResolution tests when
  minisweagent not installed

.env.example

@@ -53,6 +53,10 @@ MINIMAX_CN_API_KEY=
 # Get at: https://firecrawl.dev/
 FIRECRAWL_API_KEY=
 
+# Nous Research API Key - Vision analysis and multi-model reasoning
+# Get at: https://inference-api.nousresearch.com/
+NOUS_API_KEY=
+
 # FAL.ai API Key - Image generation
 # Get at: https://fal.ai/
 FAL_KEY=
@@ -201,18 +205,6 @@ VOICE_TOOLS_OPENAI_KEY=
 # WHATSAPP_ENABLED=false
 # WHATSAPP_ALLOWED_USERS=15551234567
 
-# Email (IMAP/SMTP — send and receive emails as Hermes)
-# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords
-# EMAIL_ADDRESS=hermes@gmail.com
-# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
-# EMAIL_IMAP_HOST=imap.gmail.com
-# EMAIL_IMAP_PORT=993
-# EMAIL_SMTP_HOST=smtp.gmail.com
-# EMAIL_SMTP_PORT=587
-# EMAIL_POLL_INTERVAL=15
-# EMAIL_ALLOWED_USERS=your@email.com
-# EMAIL_HOME_ADDRESS=your@email.com
-
 # Gateway-wide: allow ALL users without an allowlist (default: false = deny)
 # Only set to true if you intentionally want open access.
 # GATEWAY_ALLOW_ALL_USERS=false

.github/workflows/tests.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Run tests
         run: |
           source .venv/bin/activate
-          python -m pytest tests/ -q --ignore=tests/integration --tb=short -n auto
+          python -m pytest tests/ -q --ignore=tests/integration --tb=short
         env:
           # Ensure tests don't accidentally call real APIs
           OPENROUTER_API_KEY: ""

.gitignore

@@ -1,55 +1,52 @@
-/venv/
-/_pycache/
-*.pyc*
-__pycache__/
-.venv/
-.vscode/
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-.env.development
-.env.test
-export*
-__pycache__/model_tools.cpython-310.pyc
-__pycache__/web_tools.cpython-310.pyc
-logs/
-data/
-.pytest_cache/
-tmp/
-temp_vision_images/
-hermes-*/*
-examples/
-tests/quick_test_dataset.jsonl
-tests/sample_dataset.jsonl
-run_datagen_kimik2-thinking.sh
-run_datagen_megascience_glm4-6.sh
-run_datagen_sonnet.sh
-source-data/*
-run_datagen_megascience_glm4-6.sh
-data/*
-node_modules/
-browser-use/
-agent-browser/
-# Private keys
-*.ppk
-*.pem
-privvy*
-images/
-__pycache__/
-hermes_agent.egg-info/
-wandb/
-testlogs
-
-# CLI config (may contain sensitive SSH paths)
-cli-config.yaml
-
-# Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case)
-skills/.hub/
+/venv/
+/_pycache/
+*.pyc*
+__pycache__/
+.venv/
+.vscode/
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.development
+.env.test
+export*
+__pycache__/model_tools.cpython-310.pyc
+__pycache__/web_tools.cpython-310.pyc
+logs/
+data/
+.pytest_cache/
+tmp/
+temp_vision_images/
+hermes-*/*
+examples/
+tests/quick_test_dataset.jsonl
+tests/sample_dataset.jsonl
+run_datagen_kimik2-thinking.sh
+run_datagen_megascience_glm4-6.sh
+run_datagen_sonnet.sh
+source-data/*
+run_datagen_megascience_glm4-6.sh
+data/*
+node_modules/
+browser-use/
+agent-browser/
+# Private keys
+*.ppk
+*.pem
+privvy*
+images/
+__pycache__/
+hermes_agent.egg-info/
+wandb/
+testlogs
+
+# CLI config (may contain sensitive SSH paths)
+cli-config.yaml
+
+# Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case)
+skills/.hub/
 ignored/
 .worktrees/
 environments/benchmarks/evals/
-
-# Release script temp files
-.release_notes.md

.plans/openai-api-server.md

@@ -1,291 +0,0 @@
-# OpenAI-Compatible API Server for Hermes Agent
-
-## Motivation
-
-Every major chat frontend (Open WebUI 126k★, LobeChat 73k★, LibreChat 34k★,
-AnythingLLM 56k★, NextChat 87k★, ChatBox 39k★, Jan 26k★, HF Chat-UI 8k★,
-big-AGI 7k★) connects to backends via the OpenAI-compatible REST API with
-SSE streaming. By exposing this endpoint, hermes-agent becomes instantly
-usable as a backend for all of them — no custom adapters needed.
-
-## What It Enables
-
-```
-┌──────────────────┐
-│  Open WebUI      │──┐
-│  LobeChat        │  │    POST /v1/chat/completions
-│  LibreChat       │  ├──► Authorization: Bearer <key>     ┌─────────────────┐
-│  AnythingLLM     │  │    {"messages": [...]}             │  hermes-agent   │
-│  NextChat        │  │                                    │  gateway        │
-│  Any OAI client  │──┘    ◄── SSE streaming response      │  (API server)   │
-└──────────────────┘                                        └─────────────────┘
-```
-
-A user would:
-1. Set `API_SERVER_ENABLED=true` in `~/.hermes/.env`
-2. Run `hermes gateway` (API server starts alongside Telegram/Discord/etc.)
-3. Point Open WebUI (or any frontend) at `http://localhost:8642/v1`
-4. Chat with hermes-agent through any OpenAI-compatible UI
-
-## Endpoints
-
-| Method | Path | Purpose |
-|--------|------|---------|
-| POST | `/v1/chat/completions` | Chat with the agent (streaming + non-streaming) |
-| GET | `/v1/models` | List available "models" (returns hermes-agent as a model) |
-| GET | `/health` | Health check |
-
-## Architecture
-
-### Option A: Gateway Platform Adapter (recommended)
-
-Create `gateway/platforms/api_server.py` as a new platform adapter that
-extends `BasePlatformAdapter`. This is the cleanest approach because:
-
-- Reuses all gateway infrastructure (session management, auth, context building)
-- Runs in the same async loop as other adapters
-- Gets message handling, interrupt support, and session persistence for free
-- Follows the established pattern (like Telegram, Discord, etc.)
-- Uses `aiohttp.web` (already a dependency) for the HTTP server
-
-The adapter would start an `aiohttp.web.Application` server in `connect()`
-and route incoming HTTP requests through the standard `handle_message()` pipeline.
-
-### Option B: Standalone Component
-
-A separate HTTP server class in `gateway/api_server.py` that creates its own
-AIAgent instances directly. Simpler but duplicates session/auth logic.
-
-**Recommendation: Option A** — fits the existing architecture, less code to
-maintain, gets all gateway features for free.
-
-## Request/Response Format
-
-### Chat Completions (non-streaming)
-
-```
-POST /v1/chat/completions
-Authorization: Bearer hermes-api-key-here
-Content-Type: application/json
-
-{
-  "model": "hermes-agent",
-  "messages": [
-    {"role": "system", "content": "You are a helpful assistant."},
-    {"role": "user", "content": "What files are in the current directory?"}
-  ],
-  "stream": false,
-  "temperature": 0.7
-}
-```
-
-Response:
-```json
-{
-  "id": "chatcmpl-abc123",
-  "object": "chat.completion",
-  "created": 1710000000,
-  "model": "hermes-agent",
-  "choices": [{
-    "index": 0,
-    "message": {
-      "role": "assistant",
-      "content": "Here are the files in the current directory:\n..."
-    },
-    "finish_reason": "stop"
-  }],
-  "usage": {
-    "prompt_tokens": 50,
-    "completion_tokens": 200,
-    "total_tokens": 250
-  }
-}
-```
-
-### Chat Completions (streaming)
-
-Same request with `"stream": true`. Response is SSE:
-
-```
-data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
-
-data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Here "},"finish_reason":null}]}
-
-data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"are "},"finish_reason":null}]}
-
-data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
-
-data: [DONE]
-```
-
-### Models List
-
-```
-GET /v1/models
-Authorization: Bearer hermes-api-key-here
-```
-
-Response:
-```json
-{
-  "object": "list",
-  "data": [{
-    "id": "hermes-agent",
-    "object": "model",
-    "created": 1710000000,
-    "owned_by": "hermes-agent"
-  }]
-}
-```
-
-## Key Design Decisions
-
-### 1. Session Management
-
-The OpenAI API is stateless — each request includes the full conversation.
-But hermes-agent sessions have persistent state (memory, skills, tool context).
-
-**Approach: Hybrid**
-- Default: Stateless. Each request is independent. The `messages` array IS
-  the conversation. No session persistence between requests.
-- Opt-in persistent sessions via `X-Session-ID` header. When provided, the
-  server maintains session state across requests (conversation history,
-  memory context, tool state). This enables richer agent behavior.
-- The session ID also enables interrupt support — a subsequent request with
-  the same session ID while one is running triggers an interrupt.
-
-### 2. Streaming
-
-The agent's `run_conversation()` is synchronous and returns the full response.
-For real SSE streaming, we need to emit chunks as they're generated.
-
-**Phase 1 (MVP):** Run agent in a thread, return the complete response as
-a single SSE chunk + `[DONE]`. This works with all frontends — they just see
-a fast single-chunk response. Not true streaming but functional.
-
-**Phase 2:** Add a response callback to AIAgent that emits text chunks as the
-LLM generates them. The API server captures these via a queue and streams them
-as SSE events. This gives real token-by-token streaming.
-
-**Phase 3:** Stream tool execution progress too — emit tool call/result events
-as the agent works, giving frontends visibility into what the agent is doing.
-
-### 3. Tool Transparency
-
-Two modes:
-- **Opaque (default):** Frontends see only the final response. Tool calls
-  happen server-side and are invisible. Best for general-purpose UIs.
-- **Transparent (opt-in via header):** Tool calls are emitted as OpenAI-format
-  tool_call/tool_result messages in the stream. Useful for agent-aware frontends.
-
-### 4. Authentication
-
-- Bearer token via `Authorization: Bearer <key>` header
-- Token configured via `API_SERVER_KEY` env var
-- Optional: allow unauthenticated local-only access (127.0.0.1 bind)
-- Follows the same pattern as other platform adapters
-
-### 5. Model Mapping
-
-Frontends send `"model": "hermes-agent"` (or whatever). The actual LLM model
-used is configured server-side in config.yaml. The API server maps any
-requested model name to the configured hermes-agent model.
-
-Optionally, allow model passthrough: if the frontend sends
-`"model": "anthropic/claude-sonnet-4"`, the agent uses that model. Controlled
-by a config flag.
-
-## Configuration
-
-```yaml
-# In config.yaml
-api_server:
-  enabled: true
-  port: 8642
-  host: "127.0.0.1"        # localhost only by default
-  key: "your-secret-key"   # or via API_SERVER_KEY env var
-  allow_model_override: false  # let clients choose the model
-  max_concurrent: 5         # max simultaneous requests
-```
-
-Environment variables:
-```bash
-API_SERVER_ENABLED=true
-API_SERVER_PORT=8642
-API_SERVER_HOST=127.0.0.1
-API_SERVER_KEY=your-secret-key
-```
-
-## Implementation Plan
-
-### Phase 1: MVP (non-streaming) — PR
-
-1. `gateway/platforms/api_server.py` — new adapter
-   - aiohttp.web server with endpoints:
-     - `POST /v1/chat/completions` — Chat Completions API (universal compat)
-     - `POST /v1/responses` — Responses API (server-side state, tool preservation)
-     - `GET /v1/models` — list available models
-     - `GET /health` — health check
-   - Bearer token auth middleware
-   - Non-streaming responses (run agent, return full result)
-   - Chat Completions: stateless, messages array is the conversation
-   - Responses API: server-side conversation storage via previous_response_id
-     - Store full internal conversation (including tool calls) keyed by response ID
-     - On subsequent requests, reconstruct full context from stored chain
-   - Frontend system prompt layered on top of hermes-agent's core prompt
-
-2. `gateway/config.py` — add `Platform.API_SERVER` enum + config
-
-3. `gateway/run.py` — register adapter in `_create_adapter()`
-
-4. Tests in `tests/gateway/test_api_server.py`
-
-### Phase 2: SSE Streaming
-
-1. Add response streaming to both endpoints
-   - Chat Completions: `choices[0].delta.content` SSE format
-   - Responses API: semantic events (response.output_text.delta, etc.)
-   - Run agent in thread, collect output via callback queue
-   - Handle client disconnect (cancel agent)
-
-2. Add `stream_callback` parameter to `AIAgent.run_conversation()`
-
-### Phase 3: Enhanced Features
-
-1. Tool call transparency mode (opt-in)
-2. Model passthrough/override
-3. Concurrent request limiting
-4. Usage tracking / rate limiting
-5. CORS headers for browser-based frontends
-6. GET /v1/responses/{id} — retrieve stored response
-7. DELETE /v1/responses/{id} — delete stored response
-
-## Files Changed
-
-| File | Change |
-|------|--------|
-| `gateway/platforms/api_server.py` | NEW — main adapter (~300 lines) |
-| `gateway/config.py` | Add Platform.API_SERVER + config (~20 lines) |
-| `gateway/run.py` | Register adapter in _create_adapter() (~10 lines) |
-| `tests/gateway/test_api_server.py` | NEW — tests (~200 lines) |
-| `cli-config.yaml.example` | Add api_server section |
-| `README.md` | Mention API server in platform list |
-
-## Compatibility Matrix
-
-Once implemented, hermes-agent works as a drop-in backend for:
-
-| Frontend | Stars | How to Connect |
-|----------|-------|---------------|
-| Open WebUI | 126k | Settings → Connections → Add OpenAI API, URL: `http://localhost:8642/v1` |
-| NextChat | 87k | BASE_URL env var |
-| LobeChat | 73k | Custom provider endpoint |
-| AnythingLLM | 56k | LLM Provider → Generic OpenAI |
-| Oobabooga | 42k | Already a backend, not a frontend |
-| ChatBox | 39k | API Host setting |
-| LibreChat | 34k | librechat.yaml custom endpoint |
-| Chatbot UI | 29k | Custom API endpoint |
-| Jan | 26k | Remote model config |
-| AionUI | 18k | Custom API endpoint |
-| HF Chat-UI | 8k | OPENAI_BASE_URL env var |
-| big-AGI | 7k | Custom endpoint |

.plans/streaming-support.md

@@ -1,705 +0,0 @@
-# Streaming LLM Response Support for Hermes Agent
-
-## Overview
-
-Add token-by-token streaming of LLM responses across all platforms. When enabled,
-users see the response typing out live instead of waiting for the full generation.
-Streaming is opt-in via config, defaults to off, and all existing non-streaming
-code paths remain intact as the default.
-
-## Design Principles
-
-1. **Feature-flagged**: `streaming.enabled: true` in config.yaml. Off by default.
-   When off, all existing code paths are unchanged — zero risk to current behavior.
-2. **Callback-based**: A simple `stream_callback(text_delta: str)` function injected
-   into AIAgent. The agent doesn't know or care what the consumer does with tokens.
-3. **Graceful degradation**: If the provider doesn't support streaming, or streaming
-   fails for any reason, silently fall back to the non-streaming path.
-4. **Platform-agnostic core**: The streaming mechanism in AIAgent works the same
-   regardless of whether the consumer is CLI, Telegram, Discord, or the API server.
-
----
-
-## Architecture
-
-```
-                              stream_callback(delta)
-                                    │
-  ┌─────────────┐    ┌─────────────▼──────────────┐
-  │  LLM API    │    │      queue.Queue()          │
-  │  (stream)   │───►│  thread-safe bridge between │
-  │             │    │  agent thread & consumer    │
-  └─────────────┘    └─────────────┬──────────────┘
-                                   │
-                    ┌──────────────┼──────────────┐
-                    │              │              │
-              ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
-              │    CLI     │ │  Gateway  │ │ API Server│
-              │ print to   │ │ edit msg  │ │ SSE event │
-              │ terminal   │ │ on Tg/Dc  │ │ to client │
-              └───────────┘ └───────────┘ └───────────┘
-```
-
-The agent runs in a thread. The callback puts tokens into a thread-safe queue.
-Each consumer reads the queue in its own context (async task, main thread, etc.).
-
----
-
-## Configuration
-
-### config.yaml
-
-```yaml
-streaming:
-  enabled: false          # Master switch. Default off.
-  # Per-platform overrides (optional):
-  # cli: true             # Override for CLI only
-  # telegram: true        # Override for Telegram only
-  # discord: false        # Keep Discord non-streaming
-  # api_server: true      # Override for API server
-```
-
-### Environment variables
-
-```
-HERMES_STREAMING_ENABLED=true    # Master switch via env
-```
-
-### How the flag is read
-
-- **CLI**: `load_cli_config()` reads `streaming.enabled`, sets env var. AIAgent
-  checks at init time.
-- **Gateway**: `_run_agent()` reads config, decides whether to pass
-  `stream_callback` to the AIAgent constructor.
-- **API server**: For Chat Completions `stream=true` requests, always uses streaming
-  regardless of config (the client is explicitly requesting it). For non-stream
-  requests, uses config.
-
-### Precedence
-
-1. API server: client's `stream` field overrides everything
-2. Per-platform config override (e.g., `streaming.telegram: true`)
-3. Master `streaming.enabled` flag
-4. Default: off
-
----
-
-## Implementation Plan
-
-### Phase 1: Core streaming infrastructure in AIAgent
-
-**File: run_agent.py**
-
-#### 1a. Add stream_callback parameter to __init__ (~5 lines)
-
-```python
-def __init__(self, ..., stream_callback: callable = None, ...):
-    self.stream_callback = stream_callback
-```
-
-No other init changes. The callback is optional — when None, everything
-works exactly as before.
-
-#### 1b. Add _run_streaming_chat_completion() method (~65 lines)
-
-New method for Chat Completions API streaming:
-
-```python
-def _run_streaming_chat_completion(self, api_kwargs: dict):
-    """Stream a chat completion, emitting text tokens via stream_callback.
-    
-    Returns a fake response object compatible with the non-streaming code path.
-    Falls back to non-streaming on any error.
-    """
-    stream_kwargs = dict(api_kwargs)
-    stream_kwargs["stream"] = True
-    stream_kwargs["stream_options"] = {"include_usage": True}
-    
-    accumulated_content = []
-    accumulated_tool_calls = {}  # index -> {id, name, arguments}
-    final_usage = None
-    
-    try:
-        stream = self.client.chat.completions.create(**stream_kwargs)
-        
-        for chunk in stream:
-            if not chunk.choices:
-                # Usage-only chunk (final)
-                if chunk.usage:
-                    final_usage = chunk.usage
-                continue
-            
-            delta = chunk.choices[0].delta
-            
-            # Text content — emit via callback
-            if delta.content:
-                accumulated_content.append(delta.content)
-                if self.stream_callback:
-                    try:
-                        self.stream_callback(delta.content)
-                    except Exception:
-                        pass
-            
-            # Tool call deltas — accumulate silently
-            if delta.tool_calls:
-                for tc_delta in delta.tool_calls:
-                    idx = tc_delta.index
-                    if idx not in accumulated_tool_calls:
-                        accumulated_tool_calls[idx] = {
-                            "id": tc_delta.id or "",
-                            "name": "", "arguments": ""
-                        }
-                    if tc_delta.function:
-                        if tc_delta.function.name:
-                            accumulated_tool_calls[idx]["name"] = tc_delta.function.name
-                        if tc_delta.function.arguments:
-                            accumulated_tool_calls[idx]["arguments"] += tc_delta.function.arguments
-        
-        # Build fake response compatible with existing code
-        tool_calls = []
-        for idx in sorted(accumulated_tool_calls):
-            tc = accumulated_tool_calls[idx]
-            if tc["name"]:
-                tool_calls.append(SimpleNamespace(
-                    id=tc["id"], type="function",
-                    function=SimpleNamespace(name=tc["name"], arguments=tc["arguments"]),
-                ))
-        
-        return SimpleNamespace(
-            choices=[SimpleNamespace(
-                message=SimpleNamespace(
-                    content="".join(accumulated_content) or "",
-                    tool_calls=tool_calls or None,
-                    role="assistant",
-                ),
-                finish_reason="tool_calls" if tool_calls else "stop",
-            )],
-            usage=final_usage,
-            model=self.model,
-        )
-    
-    except Exception as e:
-        logger.debug("Streaming failed, falling back to non-streaming: %s", e)
-        return self.client.chat.completions.create(**api_kwargs)
-```
-
-#### 1c. Modify _run_codex_stream() for Responses API (~10 lines)
-
-The method already iterates the stream. Add callback emission:
-
-```python
-def _run_codex_stream(self, api_kwargs: dict):
-    with self.client.responses.stream(**api_kwargs) as stream:
-        for event in stream:
-            # Emit text deltas if streaming callback is set
-            if self.stream_callback and hasattr(event, 'type'):
-                if event.type == 'response.output_text.delta':
-                    try:
-                        self.stream_callback(event.delta)
-                    except Exception:
-                        pass
-        return stream.get_final_response()
-```
-
-#### 1d. Modify _interruptible_api_call() (~5 lines)
-
-Add the streaming branch:
-
-```python
-def _call():
-    try:
-        if self.api_mode == "codex_responses":
-            result["response"] = self._run_codex_stream(api_kwargs)
-        elif self.stream_callback is not None:
-            result["response"] = self._run_streaming_chat_completion(api_kwargs)
-        else:
-            result["response"] = self.client.chat.completions.create(**api_kwargs)
-    except Exception as e:
-        result["error"] = e
-```
-
-#### 1e. Signal end-of-stream to consumers (~5 lines)
-
-After the API call returns, signal the callback that streaming is done
-so consumers can finalize (remove cursor, close SSE, etc.):
-
-```python
-# In run_conversation(), after _interruptible_api_call returns:
-if self.stream_callback:
-    try:
-        self.stream_callback(None)  # None = end of stream signal
-    except Exception:
-        pass
-```
-
-Consumers check: `if delta is None: finalize()`
-
-**Tests for Phase 1:** (~150 lines)
-- Test _run_streaming_chat_completion with mocked stream
-- Test fallback to non-streaming on error
-- Test tool_call accumulation during streaming
-- Test stream_callback receives correct deltas
-- Test None signal at end of stream
-- Test streaming disabled when callback is None
-
----
-
-### Phase 2: Gateway consumers (Telegram, Discord, etc.)
-
-**File: gateway/run.py**
-
-#### 2a. Read streaming config (~15 lines)
-
-In `_run_agent()`, before creating the AIAgent:
-
-```python
-# Read streaming config
-_streaming_enabled = False
-try:
-    # Check per-platform override first
-    platform_key = source.platform.value if source.platform else ""
-    _stream_cfg = {}  # loaded from config.yaml streaming section
-    if _stream_cfg.get(platform_key) is not None:
-        _streaming_enabled = bool(_stream_cfg[platform_key])
-    else:
-        _streaming_enabled = bool(_stream_cfg.get("enabled", False))
-except Exception:
-    pass
-# Env var override
-if os.getenv("HERMES_STREAMING_ENABLED", "").lower() in ("true", "1", "yes"):
-    _streaming_enabled = True
-```
-
-#### 2b. Set up queue + callback (~15 lines)
-
-```python
-_stream_q = None
-_stream_done = None
-_stream_msg_id = [None]  # mutable ref for the async task
-
-if _streaming_enabled:
-    import queue as _q
-    _stream_q = _q.Queue()
-    _stream_done = threading.Event()
-    
-    def _on_token(delta):
-        if delta is None:
-            _stream_done.set()
-        else:
-            _stream_q.put(delta)
-```
-
-Pass `stream_callback=_on_token` to the AIAgent constructor.
-
-#### 2c. Telegram/Discord stream preview task (~50 lines)
-
-```python
-async def stream_preview():
-    """Progressively edit a message with streaming tokens."""
-    if not _stream_q:
-        return
-    adapter = self.adapters.get(source.platform)
-    if not adapter:
-        return
-    
-    accumulated = []
-    token_count = 0
-    last_edit = 0.0
-    MIN_TOKENS = 20          # Don't show until enough context
-    EDIT_INTERVAL = 1.5      # Respect Telegram rate limits
-    
-    try:
-        while not _stream_done.is_set():
-            try:
-                chunk = _stream_q.get(timeout=0.1)
-                accumulated.append(chunk)
-                token_count += 1
-            except queue.Empty:
-                continue
-            
-            now = time.monotonic()
-            if token_count >= MIN_TOKENS and (now - last_edit) >= EDIT_INTERVAL:
-                preview = "".join(accumulated) + " ▌"
-                if _stream_msg_id[0] is None:
-                    r = await adapter.send(
-                        chat_id=source.chat_id,
-                        content=preview,
-                        metadata=_thread_metadata,
-                    )
-                    if r.success and r.message_id:
-                        _stream_msg_id[0] = r.message_id
-                else:
-                    await adapter.edit_message(
-                        chat_id=source.chat_id,
-                        message_id=_stream_msg_id[0],
-                        content=preview,
-                    )
-                last_edit = now
-        
-        # Drain remaining tokens
-        while not _stream_q.empty():
-            accumulated.append(_stream_q.get_nowait())
-        
-        # Final edit — remove cursor, show complete text
-        if _stream_msg_id[0] and accumulated:
-            await adapter.edit_message(
-                chat_id=source.chat_id,
-                message_id=_stream_msg_id[0],
-                content="".join(accumulated),
-            )
-    
-    except asyncio.CancelledError:
-        # Clean up on cancel
-        if _stream_msg_id[0] and accumulated:
-            try:
-                await adapter.edit_message(
-                    chat_id=source.chat_id,
-                    message_id=_stream_msg_id[0],
-                    content="".join(accumulated),
-                )
-            except Exception:
-                pass
-    except Exception as e:
-        logger.debug("stream_preview error: %s", e)
-```
-
-#### 2d. Skip final send if already streamed (~10 lines)
-
-In `_process_message_background()` (base.py), after getting the response,
-if streaming was active and `_stream_msg_id[0]` is set, the final response
-was already delivered via progressive edits. Skip the normal `self.send()`
-call to avoid duplicating the message.
-
-This is the most delicate integration point — we need to communicate from
-the gateway's `_run_agent` back to the base adapter's response sender that
-the response was already delivered. Options:
-
-- **Option A**: Return a special marker in the result dict:
-  `result["_streamed_msg_id"] = _stream_msg_id[0]`
-  The base adapter checks this and skips `send()`.
-  
-- **Option B**: Edit the already-sent message with the final response
-  (which may differ slightly from accumulated tokens due to think-block
-  stripping, etc.) and don't send a new one.
-
-- **Option C**: The stream preview task handles the FULL final response
-  (including any post-processing), and the handler returns None to skip
-  the normal send path.
-
-Recommended: **Option A** — cleanest separation. The result dict already
-carries metadata; adding one more field is low-risk.
-
-**Platform-specific considerations:**
-
-| Platform | Edit support | Rate limits | Streaming approach |
-|----------|-------------|-------------|-------------------|
-| Telegram | ✅ edit_message_text | ~20 edits/min | Edit every 1.5s |
-| Discord | ✅ message.edit | 5 edits/5s per message | Edit every 1.2s |
-| Slack | ✅ chat.update | Tier 3 (~50/min) | Edit every 1.5s |
-| WhatsApp | ❌ no edit support | N/A | Skip streaming, use normal path |
-| HomeAssistant | ❌ no edit | N/A | Skip streaming |
-| API Server | ✅ SSE native | No limit | Real SSE events |
-
-WhatsApp and HomeAssistant fall back to non-streaming automatically because
-they don't support message editing.
-
-**Tests for Phase 2:** (~100 lines)
-- Test stream_preview sends/edits correctly
-- Test skip-final-send when streaming delivered
-- Test WhatsApp/HA graceful fallback
-- Test streaming disabled per-platform config
-- Test thread_id metadata forwarded in stream messages
-
----
-
-### Phase 3: CLI streaming
-
-**File: cli.py**
-
-#### 3a. Set up callback in the CLI chat loop (~20 lines)
-
-In `_chat_once()` or wherever the agent is invoked:
-
-```python
-if streaming_enabled:
-    _stream_q = queue.Queue()
-    _stream_done = threading.Event()
-    
-    def _cli_stream_callback(delta):
-        if delta is None:
-            _stream_done.set()
-        else:
-            _stream_q.put(delta)
-    
-    agent.stream_callback = _cli_stream_callback
-```
-
-#### 3b. Token display thread/task (~30 lines)
-
-Start a thread that reads the queue and prints tokens:
-
-```python
-def _stream_display():
-    """Print tokens to terminal as they arrive."""
-    first_token = True
-    while not _stream_done.is_set():
-        try:
-            delta = _stream_q.get(timeout=0.1)
-        except queue.Empty:
-            continue
-        if first_token:
-            # Print response box top border
-            _cprint(f"\n{top}")
-            first_token = False
-        sys.stdout.write(delta)
-        sys.stdout.flush()
-    # Drain remaining
-    while not _stream_q.empty():
-        sys.stdout.write(_stream_q.get_nowait())
-    sys.stdout.flush()
-    # Print bottom border
-    _cprint(f"\n\n{bot}")
-```
-
-**Integration challenge: prompt_toolkit**
-
-The CLI uses prompt_toolkit which controls the terminal. Writing directly
-to stdout while prompt_toolkit is active can cause display corruption.
-The existing KawaiiSpinner already solves this by using prompt_toolkit's
-`patch_stdout` context. The streaming display would need to do the same.
-
-Alternative: use `_cprint()` for each token chunk (routes through
-prompt_toolkit's renderer). But this might be slow for individual tokens.
-
-Recommended approach: accumulate tokens in small batches (e.g., every 50ms)
-and `_cprint()` the batch. This balances display responsiveness with
-prompt_toolkit compatibility.
-
-**Tests for Phase 3:** (~50 lines)
-- Test CLI streaming callback setup
-- Test response box borders with streaming
-- Test fallback when streaming disabled
-
----
-
-### Phase 4: API Server real streaming
-
-**File: gateway/platforms/api_server.py**
-
-Replace the pseudo-streaming `_write_sse_chat_completion()` with real
-token-by-token SSE when the agent supports it.
-
-#### 4a. Wire streaming callback for stream=true requests (~20 lines)
-
-```python
-if stream:
-    _stream_q = queue.Queue()
-    
-    def _api_stream_callback(delta):
-        _stream_q.put(delta)  # None = done
-    
-    # Pass callback to _run_agent
-    result, usage = await self._run_agent(
-        ..., stream_callback=_api_stream_callback,
-    )
-```
-
-#### 4b. Real SSE writer (~40 lines)
-
-```python
-async def _write_real_sse(self, request, completion_id, model, stream_q):
-    response = web.StreamResponse(
-        headers={"Content-Type": "text/event-stream", "Cache-Control": "no-cache"},
-    )
-    await response.prepare(request)
-    
-    # Role chunk
-    await response.write(...)
-    
-    # Stream content chunks as they arrive
-    while True:
-        try:
-            delta = await asyncio.get_event_loop().run_in_executor(
-                None, lambda: stream_q.get(timeout=0.1)
-            )
-        except queue.Empty:
-            continue
-        
-        if delta is None:  # End of stream
-            break
-        
-        chunk = {"id": completion_id, "object": "chat.completion.chunk", ...
-                 "choices": [{"delta": {"content": delta}, ...}]}
-        await response.write(f"data: {json.dumps(chunk)}\n\n".encode())
-    
-    # Finish + [DONE]
-    await response.write(...)
-    await response.write(b"data: [DONE]\n\n")
-    return response
-```
-
-**Challenge: concurrent execution**
-
-The agent runs in a thread executor. SSE writing happens in the async event
-loop. The queue bridges them. But `_run_agent()` currently awaits the full
-result before returning. For real streaming, we need to start the agent in
-the background and stream tokens while it runs:
-
-```python
-# Start agent in background
-agent_task = asyncio.create_task(self._run_agent_async(...))
-
-# Stream tokens while agent runs
-await self._write_real_sse(request, ..., stream_q)
-
-# Agent is done by now (stream_q received None)
-result, usage = await agent_task
-```
-
-This requires splitting `_run_agent` into an async version that doesn't
-block waiting for the result, or running it in a separate task.
-
-**Responses API SSE format:**
-
-For `/v1/responses` with `stream=true`, the SSE events are different:
-
-```
-event: response.output_text.delta
-data: {"type":"response.output_text.delta","delta":"Hello"}
-
-event: response.completed  
-data: {"type":"response.completed","response":{...}}
-```
-
-This needs a separate SSE writer that emits Responses API format events.
-
-**Tests for Phase 4:** (~80 lines)
-- Test real SSE streaming with mocked agent
-- Test SSE event format (Chat Completions vs Responses)
-- Test client disconnect during streaming
-- Test fallback to pseudo-streaming when callback not available
-
----
-
-## Integration Issues & Edge Cases
-
-### 1. Tool calls during streaming
-
-When the model returns tool calls instead of text, no text tokens are emitted.
-The stream_callback is simply never called with text. After tools execute, the
-next API call may produce the final text response — streaming picks up again.
-
-The stream preview task needs to handle this: if no tokens arrive during a
-tool-call round, don't send/edit any message. The tool progress messages
-continue working as before.
-
-### 2. Duplicate messages
-
-The biggest risk: the agent sends the final response normally (via the
-existing send path) AND the stream preview already showed it. The user
-sees the response twice.
-
-Prevention: when streaming is active and tokens were delivered, the final
-response send must be suppressed. The `result["_streamed_msg_id"]` marker
-tells the base adapter to skip its normal send.
-
-### 3. Response post-processing
-
-The final response may differ from the accumulated streamed tokens:
-- Think block stripping (`<think>...</think>` removed)
-- Trailing whitespace cleanup
-- Tool result media tag appending
-
-The stream preview shows raw tokens. The final edit should use the
-post-processed version. This means the final edit (removing the cursor)
-should use the post-processed `final_response`, not just the accumulated
-stream text.
-
-### 4. Context compression during streaming
-
-If the agent triggers context compression mid-conversation, the streaming
-tokens from BEFORE compression are from a different context than those
-after. This isn't a problem in practice — compression happens between
-API calls, not during streaming.
-
-### 5. Interrupt during streaming
-
-User sends a new message while streaming → interrupt. The stream is killed
-(HTTP connection closed), accumulated tokens are shown as-is (no cursor),
-and the interrupt message is processed normally. This is already handled by
-`_interruptible_api_call` closing the client.
-
-### 6. Multi-model / fallback
-
-If the primary model fails and the agent falls back to a different model,
-streaming state resets. The fallback call may or may not support streaming.
-The graceful fallback in `_run_streaming_chat_completion` handles this.
-
-### 7. Rate limiting on edits
-
-Telegram: ~20 edits/minute (~1 every 3 seconds to be safe)
-Discord: 5 edits per 5 seconds per message
-Slack: ~50 API calls/minute
-
-The 1.5s edit interval is conservative enough for all platforms. If we get
-429 rate limit errors on edits, just skip that edit cycle and try next time.
-
----
-
-## Files Changed Summary
-
-| File | Phase | Changes |
-|------|-------|---------|
-| `run_agent.py` | 1 | +stream_callback param, +_run_streaming_chat_completion(), modify _run_codex_stream(), modify _interruptible_api_call() |
-| `gateway/run.py` | 2 | +streaming config reader, +queue/callback setup, +stream_preview task, +skip-final-send logic |
-| `gateway/platforms/base.py` | 2 | +check for _streamed_msg_id in response handler |
-| `cli.py` | 3 | +streaming setup, +token display, +response box integration |
-| `gateway/platforms/api_server.py` | 4 | +real SSE writer, +streaming callback wiring |
-| `hermes_cli/config.py` | 1 | +streaming config defaults |
-| `cli-config.yaml.example` | 1 | +streaming section |
-| `tests/test_streaming.py` | 1-4 | NEW — ~380 lines of tests |
-
-**Total new code**: ~500 lines across all phases
-**Total test code**: ~380 lines
-
----
-
-## Rollout Plan
-
-1. **Phase 1** (core): Merge to main. Streaming disabled by default.
-   Zero impact on existing behavior. Can be tested with env var.
-
-2. **Phase 2** (gateway): Merge to main. Test on Telegram manually.
-   Enable per-platform: `streaming.telegram: true` in config.
-
-3. **Phase 3** (CLI): Merge to main. Test in terminal.
-   Enable: `streaming.cli: true` or `streaming.enabled: true`.
-
-4. **Phase 4** (API server): Merge to main. Test with Open WebUI.
-   Auto-enabled when client sends `stream: true`.
-
-Each phase is independently mergeable and testable. Streaming stays
-off by default throughout. Once all phases are stable, consider
-changing the default to enabled.
-
----
-
-## Config Reference (final state)
-
-```yaml
-# config.yaml
-streaming:
-  enabled: false          # Master switch (default: off)
-  cli: true               # Per-platform override
-  telegram: true
-  discord: true
-  slack: true
-  api_server: true        # API server always streams when client requests it
-  edit_interval: 1.5      # Seconds between message edits (default: 1.5)
-  min_tokens: 20          # Tokens before first display (default: 20)
-```
-
-```bash
-# Environment variable override
-HERMES_STREAMING_ENABLED=true
-```

AGENTS.md

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

CONTRIBUTING.md

@@ -139,8 +139,7 @@ hermes-agent/
 │   ├── commands.py               # Slash command definitions + autocomplete
 │   ├── callbacks.py              # Interactive callbacks (clarify, sudo, approval)
 │   ├── doctor.py                 # Diagnostics
-│   ├── skills_hub.py             # Skills Hub CLI + /skills slash command
-│   └── skin_engine.py            # Skin/theme engine — data-driven CLI visual customization
+│   └── skills_hub.py             # Skills Hub CLI + /skills slash command
 │
 ├── tools/                    # Tool implementations (self-registering)
 │   ├── registry.py               # Central tool registry (schemas, handlers, dispatch)
@@ -333,8 +332,6 @@ metadata:
   hermes:
     tags: [Category, Subcategory, Keywords]
     related_skills: [other-skill-name]
-    fallback_for_toolsets: [web]       # Optional — show only when toolset is unavailable
-    requires_toolsets: [terminal]      # Optional — show only when toolset is available
 ---
 
 # Skill Title
@@ -369,48 +366,6 @@ platforms: [windows]          # Windows only
 
 If the field is omitted or empty, the skill loads on all platforms (backward compatible). See `skills/apple/` for examples of macOS-only skills.
 
-### Conditional skill activation
-
-Skills can declare conditions that control when they appear in the system prompt, based on which tools and toolsets are available in the current session. This is primarily used for **fallback skills** — alternatives that should only be shown when a primary tool is unavailable.
-
-Four fields are supported under `metadata.hermes`:
-
-```yaml
-metadata:
-  hermes:
-    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
-    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
-    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
-    requires_tools: [terminal]        # Show ONLY when these specific tools are available
-```
-
-**Semantics:**
-- `fallback_for_*`: The skill is a backup. It is **hidden** when the listed tools/toolsets are available, and **shown** when they are unavailable. Use this for free alternatives to premium tools.
-- `requires_*`: The skill needs certain tools to function. It is **hidden** when the listed tools/toolsets are unavailable. Use this for skills that depend on specific capabilities (e.g., a skill that only makes sense with terminal access).
-- If both are specified, both conditions must be satisfied for the skill to appear.
-- If neither is specified, the skill is always shown (backward compatible).
-
-**Examples:**
-
-```yaml
-# DuckDuckGo search — shown when Firecrawl (web toolset) is unavailable
-metadata:
-  hermes:
-    fallback_for_toolsets: [web]
-
-# Smart home skill — only useful when terminal is available
-metadata:
-  hermes:
-    requires_toolsets: [terminal]
-
-# Local browser fallback — shown when Browserbase is unavailable
-metadata:
-  hermes:
-    fallback_for_toolsets: [browser]
-```
-
-The filtering happens at prompt build time in `agent/prompt_builder.py`. The `build_skills_system_prompt()` function receives the set of available tools and toolsets from the agent and uses `_skill_should_show()` to evaluate each skill's conditions.
-
 ### Skill guidelines
 
 - **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`).
@@ -420,56 +375,6 @@ The filtering happens at prompt build time in `agent/prompt_builder.py`. The `bu
 
 ---
 
-## Adding a Skin / Theme
-
-Hermes uses a data-driven skin system — no code changes needed to add a new skin.
-
-**Option A: User skin (YAML file)**
-
-Create `~/.hermes/skins/<name>.yaml`:
-
-```yaml
-name: mytheme
-description: Short description of the theme
-
-colors:
-  banner_border: "#HEX"     # Panel border color
-  banner_title: "#HEX"      # Panel title color
-  banner_accent: "#HEX"     # Section header color
-  banner_dim: "#HEX"        # Muted/dim text color
-  banner_text: "#HEX"       # Body text color
-  response_border: "#HEX"   # Response box border
-
-spinner:
-  waiting_faces: ["(⚔)", "(⛨)"]
-  thinking_faces: ["(⚔)", "(⌁)"]
-  thinking_verbs: ["forging", "plotting"]
-  wings:                     # Optional left/right decorations
-    - ["⟪⚔", "⚔⟫"]
-
-branding:
-  agent_name: "My Agent"
-  welcome: "Welcome message"
-  response_label: " ⚔ Agent "
-  prompt_symbol: "⚔ ❯ "
-
-tool_prefix: "╎"             # Tool output line prefix
-```
-
-All fields are optional — missing values inherit from the default skin.
-
-**Option B: Built-in skin**
-
-Add to `_BUILTIN_SKINS` dict in `hermes_cli/skin_engine.py`. Use the same schema as above but as a Python dict. Built-in skins ship with the package and are always available.
-
-**Activating:**
-- CLI: `/skin mytheme` or set `display.skin: mytheme` in config.yaml
-- Config: `display: { skin: mytheme }`
-
-See `hermes_cli/skin_engine.py` for the full schema and existing skins as examples.
-
----
-
 ## Cross-Platform Compatibility
 
 Hermes runs on Linux, macOS, and Windows. When writing code that touches the OS:

README.md

@@ -17,7 +17,7 @@ Use any model you want — [Nous Portal](https://portal.nousresearch.com), [Open
 
 <table>
 <tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
-<tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
+<tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
 <tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
 <tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
 <tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
@@ -41,6 +41,7 @@ After installation:
 
 ```bash
 source ~/.bashrc    # reload shell (or: source ~/.zshrc)
+hermes setup        # configure your LLM provider
 hermes              # start chatting!
 ```
 
@@ -50,12 +51,9 @@ hermes              # start chatting!
 
 ```bash
 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 model        # Switch provider or model
+hermes setup        # Re-run the setup wizard
 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)
 hermes update       # Update to the latest version
 hermes doctor       # Diagnose any issues
 ```
@@ -73,7 +71,7 @@ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes
 | [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes |
 | [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions |
 | [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options |
-| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
+| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, 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 |
@@ -88,35 +86,6 @@ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes
 
 ---
 
-## Migrating from OpenClaw
-
-If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.
-
-**During first-time setup:** The setup wizard (`hermes setup`) automatically detects `~/.openclaw` and offers to migrate before configuration begins.
-
-**Anytime after install:**
-
-```bash
-hermes claw migrate              # Interactive migration (full preset)
-hermes claw migrate --dry-run    # Preview what would be migrated
-hermes claw migrate --preset user-data   # Migrate without secrets
-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/`
-- **Command allowlist** — approval patterns
-- **Messaging settings** — platform configs, allowed users, working directory
-- **API keys** — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
-- **TTS assets** — workspace audio files
-- **Workspace instructions** — AGENTS.md (with `--workspace-target`)
-
-See `hermes claw migrate --help` for all options, or use the `openclaw-migration` skill for an interactive agent-guided migration with dry-run previews.
-
----
-
 ## Contributing
 
 We welcome contributions! See the [Contributing Guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) for development setup, code style, and PR process.
@@ -124,9 +93,8 @@ We welcome contributions! See the [Contributing Guide](https://hermes-agent.nous
 Quick start for contributors:
 
 ```bash
-git clone https://github.com/NousResearch/hermes-agent.git
+git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
 cd hermes-agent
-git submodule update --init mini-swe-agent   # required terminal backend
 curl -LsSf https://astral.sh/uv/install.sh | sh
 uv venv .venv --python 3.11
 source .venv/bin/activate
@@ -135,12 +103,6 @@ uv pip install -e "./mini-swe-agent"
 python -m pytest tests/ -q
 ```
 
-> **RL Training (optional):** To work on the RL/Tinker-Atropos integration, also run:
-> ```bash
-> git submodule update --init tinker-atropos
-> uv pip install -e "./tinker-atropos"
-> ```
-
 ---
 
 ## Community

RELEASE_v0.2.0.md

@@ -1,383 +0,0 @@
-# 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)

agent/auxiliary_client.py

@@ -4,7 +4,7 @@ Provides a single resolution chain so every consumer (context compression,
 session search, web extraction, vision analysis, browser vision) picks up
 the best available backend without duplicating fallback logic.
 
-Resolution order for text tasks (auto mode):
+Resolution order for text tasks:
   1. OpenRouter  (OPENROUTER_API_KEY)
   2. Nous Portal (~/.hermes/auth.json active provider)
   3. Custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY)
@@ -14,22 +14,10 @@ Resolution order for text tasks (auto mode):
      — checked via PROVIDER_REGISTRY entries with auth_type='api_key'
   6. None
 
-Resolution order for vision/multimodal tasks (auto mode):
+Resolution order for vision/multimodal tasks:
   1. OpenRouter
   2. Nous Portal
-  3. Codex OAuth (gpt-5.3-codex supports vision via Responses API)
-  4. Custom endpoint (for local vision models: Qwen-VL, LLaVA, Pixtral, etc.)
-  5. None  (API-key providers like z.ai/Kimi/MiniMax are skipped —
-     they may not support multimodal)
-
-Per-task provider overrides (e.g. AUXILIARY_VISION_PROVIDER,
-CONTEXT_COMPRESSION_PROVIDER) can force a specific provider for each task:
-"openrouter", "nous", "codex", or "main" (= steps 3-5).
-Default "auto" follows the chains above.
-
-Per-task model overrides (e.g. AUXILIARY_VISION_MODEL,
-AUXILIARY_WEB_EXTRACT_MODEL) let callers use a different model slug
-than the provider's default.
+  3. None  (custom endpoints can't substitute for Gemini multimodal)
 """
 
 import json
@@ -85,55 +73,6 @@ _CODEX_AUX_BASE_URL = "https://chatgpt.com/backend-api/codex"
 # read response.choices[0].message.content. This adapter translates those
 # calls to the Codex Responses API so callers don't need any changes.
 
-
-def _convert_content_for_responses(content: Any) -> Any:
-    """Convert chat.completions content to Responses API format.
-
-    chat.completions uses:
-      {"type": "text", "text": "..."}
-      {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
-
-    Responses API uses:
-      {"type": "input_text", "text": "..."}
-      {"type": "input_image", "image_url": "data:image/png;base64,..."}
-
-    If content is a plain string, it's returned as-is (the Responses API
-    accepts strings directly for text-only messages).
-    """
-    if isinstance(content, str):
-        return content
-    if not isinstance(content, list):
-        return str(content) if content else ""
-
-    converted: List[Dict[str, Any]] = []
-    for part in content:
-        if not isinstance(part, dict):
-            continue
-        ptype = part.get("type", "")
-        if ptype == "text":
-            converted.append({"type": "input_text", "text": part.get("text", "")})
-        elif ptype == "image_url":
-            # chat.completions nests the URL: {"image_url": {"url": "..."}}
-            image_data = part.get("image_url", {})
-            url = image_data.get("url", "") if isinstance(image_data, dict) else str(image_data)
-            entry: Dict[str, Any] = {"type": "input_image", "image_url": url}
-            # Preserve detail if specified
-            detail = image_data.get("detail") if isinstance(image_data, dict) else None
-            if detail:
-                entry["detail"] = detail
-            converted.append(entry)
-        elif ptype in ("input_text", "input_image"):
-            # Already in Responses format — pass through
-            converted.append(part)
-        else:
-            # Unknown content type — try to preserve as text
-            text = part.get("text", "")
-            if text:
-                converted.append({"type": "input_text", "text": text})
-
-    return converted or ""
-
-
 class _CodexCompletionsAdapter:
     """Drop-in shim that accepts chat.completions.create() kwargs and
     routes them through the Codex Responses streaming API."""
@@ -147,31 +86,30 @@ class _CodexCompletionsAdapter:
         model = kwargs.get("model", self._model)
         temperature = kwargs.get("temperature")
 
-        # Separate system/instructions from conversation messages.
-        # Convert chat.completions multimodal content blocks to Responses
-        # API format (input_text / input_image instead of text / image_url).
+        # Separate system/instructions from conversation messages
         instructions = "You are a helpful assistant."
         input_msgs: List[Dict[str, Any]] = []
         for msg in messages:
             role = msg.get("role", "user")
             content = msg.get("content") or ""
             if role == "system":
-                instructions = content if isinstance(content, str) else str(content)
+                instructions = content
             else:
-                input_msgs.append({
-                    "role": role,
-                    "content": _convert_content_for_responses(content),
-                })
+                input_msgs.append({"role": role, "content": content})
 
         resp_kwargs: Dict[str, Any] = {
             "model": model,
             "instructions": instructions,
             "input": input_msgs or [{"role": "user", "content": ""}],
+            "stream": True,
             "store": False,
         }
 
-        # Note: the Codex endpoint (chatgpt.com/backend-api/codex) does NOT
-        # support max_output_tokens or temperature — omit to avoid 400 errors.
+        max_tokens = kwargs.get("max_output_tokens") or kwargs.get("max_completion_tokens") or kwargs.get("max_tokens")
+        if max_tokens is not None:
+            resp_kwargs["max_output_tokens"] = int(max_tokens)
+        if temperature is not None:
+            resp_kwargs["temperature"] = temperature
 
         # Tools support for flush_memories and similar callers
         tools = kwargs.get("tools")
@@ -399,124 +337,71 @@ def _resolve_api_key_provider() -> Tuple[Optional[OpenAI], Optional[str]]:
     return None, None
 
 
-# ── Provider resolution helpers ─────────────────────────────────────────────
+# ── Public API ──────────────────────────────────────────────────────────────
 
-def _get_auxiliary_provider(task: str = "") -> str:
-    """Read the provider override for a specific auxiliary task.
+def get_text_auxiliary_client() -> Tuple[Optional[OpenAI], Optional[str]]:
+    """Return (client, model_slug) for text-only auxiliary tasks.
 
-    Checks AUXILIARY_{TASK}_PROVIDER first (e.g. AUXILIARY_VISION_PROVIDER),
-    then CONTEXT_{TASK}_PROVIDER (for the compression section's summary_provider),
-    then falls back to "auto".  Returns one of: "auto", "openrouter", "nous", "main".
+    Falls through OpenRouter -> Nous Portal -> custom endpoint -> Codex OAuth
+    -> direct API-key providers -> (None, None).
     """
-    if task:
-        for prefix in ("AUXILIARY_", "CONTEXT_"):
-            val = os.getenv(f"{prefix}{task.upper()}_PROVIDER", "").strip().lower()
-            if val and val != "auto":
-                return val
-    return "auto"
-
-
-def _try_openrouter() -> Tuple[Optional[OpenAI], Optional[str]]:
+    # 1. OpenRouter
     or_key = os.getenv("OPENROUTER_API_KEY")
-    if not or_key:
-        return None, None
-    logger.debug("Auxiliary client: OpenRouter")
-    return OpenAI(api_key=or_key, base_url=OPENROUTER_BASE_URL,
-                   default_headers=_OR_HEADERS), _OPENROUTER_MODEL
+    if or_key:
+        logger.debug("Auxiliary text client: OpenRouter")
+        return OpenAI(api_key=or_key, base_url=OPENROUTER_BASE_URL,
+                       default_headers=_OR_HEADERS), _OPENROUTER_MODEL
 
-
-def _try_nous() -> Tuple[Optional[OpenAI], Optional[str]]:
+    # 2. Nous Portal
     nous = _read_nous_auth()
-    if not nous:
-        return None, None
-    global auxiliary_is_nous
-    auxiliary_is_nous = True
-    logger.debug("Auxiliary client: Nous Portal")
-    return (
-        OpenAI(api_key=_nous_api_key(nous), base_url=_nous_base_url()),
-        _NOUS_MODEL,
-    )
+    if nous:
+        global auxiliary_is_nous
+        auxiliary_is_nous = True
+        logger.debug("Auxiliary text client: Nous Portal")
+        return (
+            OpenAI(api_key=_nous_api_key(nous), base_url=_nous_base_url()),
+            _NOUS_MODEL,
+        )
 
-
-def _try_custom_endpoint() -> Tuple[Optional[OpenAI], Optional[str]]:
+    # 3. Custom endpoint (both base URL and key must be set)
     custom_base = os.getenv("OPENAI_BASE_URL")
     custom_key = os.getenv("OPENAI_API_KEY")
-    if not custom_base or not custom_key:
-        return None, None
-    model = os.getenv("OPENAI_MODEL") or "gpt-4o-mini"
-    logger.debug("Auxiliary client: custom endpoint (%s)", model)
-    return OpenAI(api_key=custom_key, base_url=custom_base), model
+    if custom_base and custom_key:
+        model = os.getenv("OPENAI_MODEL") or os.getenv("LLM_MODEL") or "gpt-4o-mini"
+        logger.debug("Auxiliary text client: custom endpoint (%s)", model)
+        return OpenAI(api_key=custom_key, base_url=custom_base), model
 
-
-def _try_codex() -> Tuple[Optional[Any], Optional[str]]:
+    # 4. Codex OAuth -- uses the Responses API (only endpoint the token
+    # can access), wrapped to look like a chat.completions client.
     codex_token = _read_codex_access_token()
-    if not codex_token:
-        return None, None
-    logger.debug("Auxiliary client: Codex OAuth (%s via Responses API)", _CODEX_AUX_MODEL)
-    real_client = OpenAI(api_key=codex_token, base_url=_CODEX_AUX_BASE_URL)
-    return CodexAuxiliaryClient(real_client, _CODEX_AUX_MODEL), _CODEX_AUX_MODEL
+    if codex_token:
+        logger.debug("Auxiliary text client: Codex OAuth (%s via Responses API)", _CODEX_AUX_MODEL)
+        real_client = OpenAI(api_key=codex_token, base_url=_CODEX_AUX_BASE_URL)
+        return CodexAuxiliaryClient(real_client, _CODEX_AUX_MODEL), _CODEX_AUX_MODEL
 
+    # 5. Direct API-key providers (z.ai/GLM, Kimi/Moonshot, MiniMax, etc.)
+    api_client, api_model = _resolve_api_key_provider()
+    if api_client is not None:
+        return api_client, api_model
 
-def _resolve_forced_provider(forced: str) -> Tuple[Optional[OpenAI], Optional[str]]:
-    """Resolve a specific forced provider.  Returns (None, None) if creds missing."""
-    if forced == "openrouter":
-        client, model = _try_openrouter()
-        if client is None:
-            logger.warning("auxiliary.provider=openrouter but OPENROUTER_API_KEY not set")
-        return client, model
-
-    if forced == "nous":
-        client, model = _try_nous()
-        if client is None:
-            logger.warning("auxiliary.provider=nous but Nous Portal not configured (run: hermes login)")
-        return client, model
-
-    if forced == "codex":
-        client, model = _try_codex()
-        if client is None:
-            logger.warning("auxiliary.provider=codex but no Codex OAuth token found (run: hermes model)")
-        return client, model
-
-    if forced == "main":
-        # "main" = skip OpenRouter/Nous, use the main chat model's credentials.
-        for try_fn in (_try_custom_endpoint, _try_codex, _resolve_api_key_provider):
-            client, model = try_fn()
-            if client is not None:
-                return client, model
-        logger.warning("auxiliary.provider=main but no main endpoint credentials found")
-        return None, None
-
-    # Unknown provider name — fall through to auto
-    logger.warning("Unknown auxiliary.provider=%r, falling back to auto", forced)
+    # 6. Nothing available
+    logger.debug("Auxiliary text client: none available")
     return None, None
 
 
-def _resolve_auto() -> Tuple[Optional[OpenAI], Optional[str]]:
-    """Full auto-detection chain: OpenRouter → Nous → custom → Codex → API-key → None."""
-    for try_fn in (_try_openrouter, _try_nous, _try_custom_endpoint,
-                   _try_codex, _resolve_api_key_provider):
-        client, model = try_fn()
-        if client is not None:
-            return client, model
-    logger.debug("Auxiliary client: none available")
-    return None, None
+def get_async_text_auxiliary_client():
+    """Return (async_client, model_slug) for async consumers.
 
-
-# ── Centralized Provider Router ─────────────────────────────────────────────
-#
-# resolve_provider_client() is the single entry point for creating a properly
-# configured client given a (provider, model) pair.  It handles auth lookup,
-# base URL resolution, provider-specific headers, and API format differences
-# (Chat Completions vs Responses API for Codex).
-#
-# All auxiliary consumer code should go through this or the public helpers
-# below — never look up auth env vars ad-hoc.
-
-
-def _to_async_client(sync_client, model: str):
-    """Convert a sync client to its async counterpart, preserving Codex routing."""
+    For standard providers returns (AsyncOpenAI, model). For Codex returns
+    (AsyncCodexAuxiliaryClient, model) which wraps the Responses API.
+    Returns (None, None) when no provider is available.
+    """
     from openai import AsyncOpenAI
 
+    sync_client, model = get_text_auxiliary_client()
+    if sync_client is None:
+        return None, None
+
     if isinstance(sync_client, CodexAuxiliaryClient):
         return AsyncCodexAuxiliaryClient(sync_client), model
 
@@ -524,258 +409,40 @@ def _to_async_client(sync_client, model: str):
         "api_key": sync_client.api_key,
         "base_url": str(sync_client.base_url),
     }
-    base_lower = str(sync_client.base_url).lower()
-    if "openrouter" in base_lower:
+    if "openrouter" in str(sync_client.base_url).lower():
         async_kwargs["default_headers"] = dict(_OR_HEADERS)
-    elif "api.kimi.com" in base_lower:
+    elif "api.kimi.com" in str(sync_client.base_url).lower():
         async_kwargs["default_headers"] = {"User-Agent": "KimiCLI/1.0"}
     return AsyncOpenAI(**async_kwargs), model
 
 
-def resolve_provider_client(
-    provider: str,
-    model: str = None,
-    async_mode: bool = False,
-    raw_codex: bool = False,
-) -> Tuple[Optional[Any], Optional[str]]:
-    """Central router: given a provider name and optional model, return a
-    configured client with the correct auth, base URL, and API format.
-
-    The returned client always exposes ``.chat.completions.create()`` — for
-    Codex/Responses API providers, an adapter handles the translation
-    transparently.
-
-    Args:
-        provider: Provider identifier.  One of:
-            "openrouter", "nous", "openai-codex" (or "codex"),
-            "zai", "kimi-coding", "minimax", "minimax-cn",
-            "custom" (OPENAI_BASE_URL + OPENAI_API_KEY),
-            "auto" (full auto-detection chain).
-        model: Model slug override.  If None, uses the provider's default
-               auxiliary model.
-        async_mode: If True, return an async-compatible client.
-        raw_codex: If True, return a raw OpenAI client for Codex providers
-            instead of wrapping in CodexAuxiliaryClient.  Use this when
-            the caller needs direct access to responses.stream() (e.g.,
-            the main agent loop).
-
-    Returns:
-        (client, resolved_model) or (None, None) if auth is unavailable.
-    """
-    # Normalise aliases
-    provider = (provider or "auto").strip().lower()
-    if provider == "codex":
-        provider = "openai-codex"
-    if provider == "main":
-        provider = "custom"
-
-    # ── Auto: try all providers in priority order ────────────────────
-    if provider == "auto":
-        client, resolved = _resolve_auto()
-        if client is None:
-            return None, None
-        final_model = model or resolved
-        return (_to_async_client(client, final_model) if async_mode
-                else (client, final_model))
-
-    # ── OpenRouter ───────────────────────────────────────────────────
-    if provider == "openrouter":
-        client, default = _try_openrouter()
-        if client is None:
-            logger.warning("resolve_provider_client: openrouter requested "
-                           "but OPENROUTER_API_KEY not set")
-            return None, None
-        final_model = model or default
-        return (_to_async_client(client, final_model) if async_mode
-                else (client, final_model))
-
-    # ── Nous Portal (OAuth) ──────────────────────────────────────────
-    if provider == "nous":
-        client, default = _try_nous()
-        if client is None:
-            logger.warning("resolve_provider_client: nous requested "
-                           "but Nous Portal not configured (run: hermes login)")
-            return None, None
-        final_model = model or default
-        return (_to_async_client(client, final_model) if async_mode
-                else (client, final_model))
-
-    # ── OpenAI Codex (OAuth → Responses API) ─────────────────────────
-    if provider == "openai-codex":
-        if raw_codex:
-            # Return the raw OpenAI client for callers that need direct
-            # access to responses.stream() (e.g., the main agent loop).
-            codex_token = _read_codex_access_token()
-            if not codex_token:
-                logger.warning("resolve_provider_client: openai-codex requested "
-                               "but no Codex OAuth token found (run: hermes model)")
-                return None, None
-            final_model = model or _CODEX_AUX_MODEL
-            raw_client = OpenAI(api_key=codex_token, base_url=_CODEX_AUX_BASE_URL)
-            return (raw_client, final_model)
-        # Standard path: wrap in CodexAuxiliaryClient adapter
-        client, default = _try_codex()
-        if client is None:
-            logger.warning("resolve_provider_client: openai-codex requested "
-                           "but no Codex OAuth token found (run: hermes model)")
-            return None, None
-        final_model = model or default
-        return (_to_async_client(client, final_model) if async_mode
-                else (client, final_model))
-
-    # ── Custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY) ───────────
-    if provider == "custom":
-        # Try custom first, then codex, then API-key providers
-        for try_fn in (_try_custom_endpoint, _try_codex,
-                       _resolve_api_key_provider):
-            client, default = try_fn()
-            if client is not None:
-                final_model = model or default
-                return (_to_async_client(client, final_model) if async_mode
-                        else (client, final_model))
-        logger.warning("resolve_provider_client: custom/main requested "
-                       "but no endpoint credentials found")
-        return None, None
-
-    # ── API-key providers from PROVIDER_REGISTRY ─────────────────────
-    try:
-        from hermes_cli.auth import PROVIDER_REGISTRY, _resolve_kimi_base_url
-    except ImportError:
-        logger.debug("hermes_cli.auth not available for provider %s", provider)
-        return None, None
-
-    pconfig = PROVIDER_REGISTRY.get(provider)
-    if pconfig is None:
-        logger.warning("resolve_provider_client: unknown provider %r", provider)
-        return None, None
-
-    if pconfig.auth_type == "api_key":
-        # Find the first configured API key
-        api_key = ""
-        for env_var in pconfig.api_key_env_vars:
-            api_key = os.getenv(env_var, "").strip()
-            if api_key:
-                break
-        if not api_key:
-            logger.warning("resolve_provider_client: provider %s has no API "
-                           "key configured (tried: %s)",
-                           provider, ", ".join(pconfig.api_key_env_vars))
-            return None, None
-
-        # Resolve base URL (env override → provider-specific logic → default)
-        base_url_override = os.getenv(pconfig.base_url_env_var, "").strip() if pconfig.base_url_env_var else ""
-        if provider == "kimi-coding":
-            base_url = _resolve_kimi_base_url(api_key, pconfig.inference_base_url, base_url_override)
-        elif base_url_override:
-            base_url = base_url_override
-        else:
-            base_url = pconfig.inference_base_url
-
-        default_model = _API_KEY_PROVIDER_AUX_MODELS.get(provider, "")
-        final_model = model or default_model
-
-        # Provider-specific headers
-        headers = {}
-        if "api.kimi.com" in base_url.lower():
-            headers["User-Agent"] = "KimiCLI/1.0"
-
-        client = OpenAI(api_key=api_key, base_url=base_url,
-                        **({"default_headers": headers} if headers else {}))
-        logger.debug("resolve_provider_client: %s (%s)", provider, final_model)
-        return (_to_async_client(client, final_model) if async_mode
-                else (client, final_model))
-
-    elif pconfig.auth_type in ("oauth_device_code", "oauth_external"):
-        # OAuth providers — route through their specific try functions
-        if provider == "nous":
-            return resolve_provider_client("nous", model, async_mode)
-        if provider == "openai-codex":
-            return resolve_provider_client("openai-codex", model, async_mode)
-        # Other OAuth providers not directly supported
-        logger.warning("resolve_provider_client: OAuth provider %s not "
-                       "directly supported, try 'auto'", provider)
-        return None, None
-
-    logger.warning("resolve_provider_client: unhandled auth_type %s for %s",
-                   pconfig.auth_type, provider)
-    return None, None
-
-
-# ── Public API ──────────────────────────────────────────────────────────────
-
-def get_text_auxiliary_client(task: str = "") -> Tuple[Optional[OpenAI], Optional[str]]:
-    """Return (client, default_model_slug) for text-only auxiliary tasks.
-
-    Args:
-        task: Optional task name ("compression", "web_extract") to check
-              for a task-specific provider override.
-
-    Callers may override the returned model with a per-task env var
-    (e.g. CONTEXT_COMPRESSION_MODEL, AUXILIARY_WEB_EXTRACT_MODEL).
-    """
-    forced = _get_auxiliary_provider(task)
-    if forced != "auto":
-        return resolve_provider_client(forced)
-    return resolve_provider_client("auto")
-
-
-def get_async_text_auxiliary_client(task: str = ""):
-    """Return (async_client, model_slug) for async consumers.
-
-    For standard providers returns (AsyncOpenAI, model). For Codex returns
-    (AsyncCodexAuxiliaryClient, model) which wraps the Responses API.
-    Returns (None, None) when no provider is available.
-    """
-    forced = _get_auxiliary_provider(task)
-    if forced != "auto":
-        return resolve_provider_client(forced, async_mode=True)
-    return resolve_provider_client("auto", async_mode=True)
-
-
 def get_vision_auxiliary_client() -> Tuple[Optional[OpenAI], Optional[str]]:
-    """Return (client, default_model_slug) for vision/multimodal auxiliary tasks.
+    """Return (client, model_slug) for vision/multimodal auxiliary tasks.
 
-    Checks AUXILIARY_VISION_PROVIDER for a forced provider, otherwise
-    auto-detects.  Callers may override the returned model with
-    AUXILIARY_VISION_MODEL.
-
-    In auto mode, only providers known to support multimodal are tried:
-    OpenRouter, Nous Portal, and Codex OAuth (gpt-5.3-codex supports
-    vision via the Responses API).  Custom endpoints and API-key
-    providers are skipped — they may not handle vision input.  To use
-    them, set AUXILIARY_VISION_PROVIDER explicitly.
+    Only OpenRouter and Nous Portal qualify — custom endpoints cannot
+    substitute for Gemini multimodal.
     """
-    forced = _get_auxiliary_provider("vision")
-    if forced != "auto":
-        return resolve_provider_client(forced)
-    # Auto: try providers known to support multimodal first, then fall
-    # back to the user's custom endpoint.  Many local models (Qwen-VL,
-    # LLaVA, Pixtral, etc.) support vision — skipping them entirely
-    # caused silent failures for local-only users.
-    for try_fn in (_try_openrouter, _try_nous, _try_codex,
-                   _try_custom_endpoint):
-        client, model = try_fn()
-        if client is not None:
-            return client, model
+    # 1. OpenRouter
+    or_key = os.getenv("OPENROUTER_API_KEY")
+    if or_key:
+        logger.debug("Auxiliary vision client: OpenRouter")
+        return OpenAI(api_key=or_key, base_url=OPENROUTER_BASE_URL,
+                       default_headers=_OR_HEADERS), _OPENROUTER_MODEL
+
+    # 2. Nous Portal
+    nous = _read_nous_auth()
+    if nous:
+        logger.debug("Auxiliary vision client: Nous Portal")
+        return (
+            OpenAI(api_key=_nous_api_key(nous), base_url=_nous_base_url()),
+            _NOUS_MODEL,
+        )
+
+    # 3. Nothing suitable
     logger.debug("Auxiliary vision client: none available")
     return None, None
 
 
-def get_async_vision_auxiliary_client():
-    """Return (async_client, model_slug) for async vision consumers.
-
-    Properly handles Codex routing — unlike manually constructing
-    AsyncOpenAI from a sync client, this preserves the Responses API
-    adapter for Codex providers.
-
-    Returns (None, None) when no provider is available.
-    """
-    sync_client, model = get_vision_auxiliary_client()
-    if sync_client is None:
-        return None, None
-    return _to_async_client(sync_client, model)
-
-
 def get_auxiliary_extra_body() -> dict:
     """Return extra_body kwargs for auxiliary API calls.
     
@@ -801,253 +468,3 @@ def auxiliary_max_tokens_param(value: int) -> dict:
             and "api.openai.com" in custom_base.lower()):
         return {"max_completion_tokens": value}
     return {"max_tokens": value}
-
-
-# ── Centralized LLM Call API ────────────────────────────────────────────────
-#
-# call_llm() and async_call_llm() own the full request lifecycle:
-#   1. Resolve provider + model from task config (or explicit args)
-#   2. Get or create a cached client for that provider
-#   3. Format request args for the provider + model (max_tokens handling, etc.)
-#   4. Make the API call
-#   5. Return the response
-#
-# Every auxiliary LLM consumer should use these instead of manually
-# constructing clients and calling .chat.completions.create().
-
-# Client cache: (provider, async_mode) -> (client, default_model)
-_client_cache: Dict[tuple, tuple] = {}
-
-
-def _get_cached_client(
-    provider: str, model: str = None, async_mode: bool = False,
-) -> Tuple[Optional[Any], Optional[str]]:
-    """Get or create a cached client for the given provider."""
-    cache_key = (provider, async_mode)
-    if cache_key in _client_cache:
-        cached_client, cached_default = _client_cache[cache_key]
-        return cached_client, model or cached_default
-    client, default_model = resolve_provider_client(provider, model, async_mode)
-    if client is not None:
-        _client_cache[cache_key] = (client, default_model)
-    return client, model or default_model
-
-
-def _resolve_task_provider_model(
-    task: str = None,
-    provider: str = None,
-    model: str = None,
-) -> Tuple[str, Optional[str]]:
-    """Determine provider + model for a call.
-
-    Priority:
-      1. Explicit provider/model args (always win)
-      2. Env var overrides (AUXILIARY_{TASK}_PROVIDER, etc.)
-      3. Config file (auxiliary.{task}.provider/model or compression.*)
-      4. "auto" (full auto-detection chain)
-
-    Returns (provider, model) where model may be None (use provider default).
-    """
-    if provider:
-        return provider, model
-
-    if task:
-        # Check env var overrides first
-        env_provider = _get_auxiliary_provider(task)
-        if env_provider != "auto":
-            # Check for env var model override too
-            env_model = None
-            for prefix in ("AUXILIARY_", "CONTEXT_"):
-                val = os.getenv(f"{prefix}{task.upper()}_MODEL", "").strip()
-                if val:
-                    env_model = val
-                    break
-            return env_provider, model or env_model
-
-        # Read from config file
-        try:
-            from hermes_cli.config import load_config
-            config = load_config()
-        except ImportError:
-            return "auto", model
-
-        # Check auxiliary.{task} section
-        aux = config.get("auxiliary", {})
-        task_config = aux.get(task, {})
-        cfg_provider = task_config.get("provider", "").strip() or None
-        cfg_model = task_config.get("model", "").strip() or None
-
-        # Backwards compat: compression section has its own keys
-        if task == "compression" and not cfg_provider:
-            comp = config.get("compression", {})
-            cfg_provider = comp.get("summary_provider", "").strip() or None
-            cfg_model = cfg_model or comp.get("summary_model", "").strip() or None
-
-        if cfg_provider and cfg_provider != "auto":
-            return cfg_provider, model or cfg_model
-        return "auto", model or cfg_model
-
-    return "auto", model
-
-
-def _build_call_kwargs(
-    provider: str,
-    model: str,
-    messages: list,
-    temperature: Optional[float] = None,
-    max_tokens: Optional[int] = None,
-    tools: Optional[list] = None,
-    timeout: float = 30.0,
-    extra_body: Optional[dict] = None,
-) -> dict:
-    """Build kwargs for .chat.completions.create() with model/provider adjustments."""
-    kwargs: Dict[str, Any] = {
-        "model": model,
-        "messages": messages,
-        "timeout": timeout,
-    }
-
-    if temperature is not None:
-        kwargs["temperature"] = temperature
-
-    if max_tokens is not None:
-        # Codex adapter handles max_tokens internally; OpenRouter/Nous use max_tokens.
-        # Direct OpenAI api.openai.com with newer models needs max_completion_tokens.
-        if provider == "custom":
-            custom_base = os.getenv("OPENAI_BASE_URL", "")
-            if "api.openai.com" in custom_base.lower():
-                kwargs["max_completion_tokens"] = max_tokens
-            else:
-                kwargs["max_tokens"] = max_tokens
-        else:
-            kwargs["max_tokens"] = max_tokens
-
-    if tools:
-        kwargs["tools"] = tools
-
-    # Provider-specific extra_body
-    merged_extra = dict(extra_body or {})
-    if provider == "nous" or auxiliary_is_nous:
-        merged_extra.setdefault("tags", []).extend(["product=hermes-agent"])
-    if merged_extra:
-        kwargs["extra_body"] = merged_extra
-
-    return kwargs
-
-
-def call_llm(
-    task: str = None,
-    *,
-    provider: str = None,
-    model: str = None,
-    messages: list,
-    temperature: float = None,
-    max_tokens: int = None,
-    tools: list = None,
-    timeout: float = 30.0,
-    extra_body: dict = None,
-) -> Any:
-    """Centralized synchronous LLM call.
-
-    Resolves provider + model (from task config, explicit args, or auto-detect),
-    handles auth, request formatting, and model-specific arg adjustments.
-
-    Args:
-        task: Auxiliary task name ("compression", "vision", "web_extract",
-              "session_search", "skills_hub", "mcp", "flush_memories").
-              Reads provider:model from config/env. Ignored if provider is set.
-        provider: Explicit provider override.
-        model: Explicit model override.
-        messages: Chat messages list.
-        temperature: Sampling temperature (None = provider default).
-        max_tokens: Max output tokens (handles max_tokens vs max_completion_tokens).
-        tools: Tool definitions (for function calling).
-        timeout: Request timeout in seconds.
-        extra_body: Additional request body fields.
-
-    Returns:
-        Response object with .choices[0].message.content
-
-    Raises:
-        RuntimeError: If no provider is configured.
-    """
-    resolved_provider, resolved_model = _resolve_task_provider_model(
-        task, provider, model)
-
-    client, final_model = _get_cached_client(resolved_provider, resolved_model)
-    if client is None:
-        # Fallback: try openrouter
-        if resolved_provider != "openrouter":
-            logger.warning("Provider %s unavailable, falling back to openrouter",
-                           resolved_provider)
-            client, final_model = _get_cached_client(
-                "openrouter", resolved_model or _OPENROUTER_MODEL)
-    if client is None:
-        raise RuntimeError(
-            f"No LLM provider configured for task={task} provider={resolved_provider}. "
-            f"Run: hermes setup")
-
-    kwargs = _build_call_kwargs(
-        resolved_provider, final_model, messages,
-        temperature=temperature, max_tokens=max_tokens,
-        tools=tools, timeout=timeout, extra_body=extra_body)
-
-    # Handle max_tokens vs max_completion_tokens retry
-    try:
-        return client.chat.completions.create(**kwargs)
-    except Exception as first_err:
-        err_str = str(first_err)
-        if "max_tokens" in err_str or "unsupported_parameter" in err_str:
-            kwargs.pop("max_tokens", None)
-            kwargs["max_completion_tokens"] = max_tokens
-            return client.chat.completions.create(**kwargs)
-        raise
-
-
-async def async_call_llm(
-    task: str = None,
-    *,
-    provider: str = None,
-    model: str = None,
-    messages: list,
-    temperature: float = None,
-    max_tokens: int = None,
-    tools: list = None,
-    timeout: float = 30.0,
-    extra_body: dict = None,
-) -> Any:
-    """Centralized asynchronous LLM call.
-
-    Same as call_llm() but async. See call_llm() for full documentation.
-    """
-    resolved_provider, resolved_model = _resolve_task_provider_model(
-        task, provider, model)
-
-    client, final_model = _get_cached_client(
-        resolved_provider, resolved_model, async_mode=True)
-    if client is None:
-        if resolved_provider != "openrouter":
-            logger.warning("Provider %s unavailable, falling back to openrouter",
-                           resolved_provider)
-            client, final_model = _get_cached_client(
-                "openrouter", resolved_model or _OPENROUTER_MODEL,
-                async_mode=True)
-    if client is None:
-        raise RuntimeError(
-            f"No LLM provider configured for task={task} provider={resolved_provider}. "
-            f"Run: hermes setup")
-
-    kwargs = _build_call_kwargs(
-        resolved_provider, final_model, messages,
-        temperature=temperature, max_tokens=max_tokens,
-        tools=tools, timeout=timeout, extra_body=extra_body)
-
-    try:
-        return await client.chat.completions.create(**kwargs)
-    except Exception as first_err:
-        err_str = str(first_err)
-        if "max_tokens" in err_str or "unsupported_parameter" in err_str:
-            kwargs.pop("max_tokens", None)
-            kwargs["max_completion_tokens"] = max_tokens
-            return await client.chat.completions.create(**kwargs)
-        raise

agent/context_compressor.py

@@ -9,7 +9,7 @@ import logging
 import os
 from typing import Any, Dict, List, Optional
 
-from agent.auxiliary_client import call_llm
+from agent.auxiliary_client import get_text_auxiliary_client
 from agent.model_metadata import (
     get_model_context_length,
     estimate_messages_tokens_rough,
@@ -53,7 +53,8 @@ class ContextCompressor:
         self.last_completion_tokens = 0
         self.last_total_tokens = 0
 
-        self.summary_model = summary_model_override or ""
+        self.client, default_model = get_text_auxiliary_client()
+        self.summary_model = summary_model_override or default_model
 
     def update_from_response(self, usage: Dict[str, Any]):
         """Update tracked token usage from API response."""
@@ -119,30 +120,84 @@ TURNS TO SUMMARIZE:
 
 Write only the summary, starting with "[CONTEXT SUMMARY]:" prefix."""
 
-        # Use the centralized LLM router — handles provider resolution,
-        # auth, and fallback internally.
+        # 1. Try the auxiliary model (cheap/fast)
+        if self.client:
+            try:
+                return self._call_summary_model(self.client, self.summary_model, prompt)
+            except Exception as e:
+                logging.warning(f"Failed to generate context summary with auxiliary model: {e}")
+
+        # 2. Fallback: try the user's main model endpoint
+        fallback_client, fallback_model = self._get_fallback_client()
+        if fallback_client is not None:
+            try:
+                logger.info("Retrying context summary with main model (%s)", fallback_model)
+                summary = self._call_summary_model(fallback_client, fallback_model, prompt)
+                self.client = fallback_client
+                self.summary_model = fallback_model
+                return summary
+            except Exception as fallback_err:
+                logging.warning(f"Main model summary also failed: {fallback_err}")
+
+        # 3. All models failed — return None so the caller drops turns without a summary
+        logging.warning("Context compression: no model available for summary. Middle turns will be dropped without summary.")
+        return None
+
+    def _call_summary_model(self, client, model: str, prompt: str) -> str:
+        """Make the actual LLM call to generate a summary. Raises on failure."""
+        kwargs = {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": 0.3,
+            "timeout": 30.0,
+        }
+        # Most providers (OpenRouter, local models) use max_tokens.
+        # Direct OpenAI with newer models (gpt-4o, o-series, gpt-5+)
+        # requires max_completion_tokens instead.
         try:
-            call_kwargs = {
-                "task": "compression",
-                "messages": [{"role": "user", "content": prompt}],
-                "temperature": 0.3,
-                "max_tokens": self.summary_target_tokens * 2,
-                "timeout": 30.0,
-            }
-            if self.summary_model:
-                call_kwargs["model"] = self.summary_model
-            response = call_llm(**call_kwargs)
-            summary = response.choices[0].message.content.strip()
-            if not summary.startswith("[CONTEXT SUMMARY]:"):
-                summary = "[CONTEXT SUMMARY]: " + summary
-            return summary
-        except RuntimeError:
-            logging.warning("Context compression: no provider available for "
-                            "summary. Middle turns will be dropped without summary.")
-            return None
-        except Exception as e:
-            logging.warning("Failed to generate context summary: %s", e)
-            return None
+            kwargs["max_tokens"] = self.summary_target_tokens * 2
+            response = client.chat.completions.create(**kwargs)
+        except Exception as first_err:
+            if "max_tokens" in str(first_err) or "unsupported_parameter" in str(first_err):
+                kwargs.pop("max_tokens", None)
+                kwargs["max_completion_tokens"] = self.summary_target_tokens * 2
+                response = client.chat.completions.create(**kwargs)
+            else:
+                raise
+
+        summary = response.choices[0].message.content.strip()
+        if not summary.startswith("[CONTEXT SUMMARY]:"):
+            summary = "[CONTEXT SUMMARY]: " + summary
+        return summary
+
+    def _get_fallback_client(self):
+        """Try to build a fallback client from the main model's endpoint config.
+
+        When the primary auxiliary client fails (e.g. stale OpenRouter key), this
+        creates a client using the user's active custom endpoint (OPENAI_BASE_URL)
+        so compression can still produce a real summary instead of a static string.
+
+        Returns (client, model) or (None, None).
+        """
+        custom_base = os.getenv("OPENAI_BASE_URL")
+        custom_key = os.getenv("OPENAI_API_KEY")
+        if not custom_base or not custom_key:
+            return None, None
+
+        # Don't fallback to the same provider that just failed
+        from hermes_constants import OPENROUTER_BASE_URL
+        if custom_base.rstrip("/") == OPENROUTER_BASE_URL.rstrip("/"):
+            return None, None
+
+        model = os.getenv("LLM_MODEL") or os.getenv("OPENAI_MODEL") or self.model
+        try:
+            from openai import OpenAI as _OpenAI
+            client = _OpenAI(api_key=custom_key, base_url=custom_base)
+            logger.debug("Built fallback auxiliary client: %s via %s", model, custom_base)
+            return client, model
+        except Exception as exc:
+            logger.debug("Could not build fallback auxiliary client: %s", exc)
+            return None, None
 
     # ------------------------------------------------------------------
     # Tool-call / tool-result pair integrity helpers
@@ -287,9 +342,7 @@ Write only the summary, starting with "[CONTEXT SUMMARY]:" prefix."""
             compressed.append(msg)
 
         if summary:
-            last_head_role = messages[compress_start - 1].get("role", "user") if compress_start > 0 else "user"
-            summary_role = "user" if last_head_role in ("assistant", "tool") else "assistant"
-            compressed.append({"role": summary_role, "content": summary})
+            compressed.append({"role": "user", "content": summary})
         else:
             if not self.quiet_mode:
                 print("   ⚠️  No summary model available — middle turns dropped without summary")

agent/display.py

@@ -5,8 +5,8 @@ Used by AIAgent._execute_tool_calls for CLI feedback.
 """
 
 import json
-import logging
 import os
+import random
 import sys
 import threading
 import time
@@ -15,49 +15,6 @@ import time
 _RED = "\033[31m"
 _RESET = "\033[0m"
 
-logger = logging.getLogger(__name__)
-
-
-# =========================================================================
-# Skin-aware helpers (lazy import to avoid circular deps)
-# =========================================================================
-
-def _get_skin():
-    """Get the active skin config, or None if not available."""
-    try:
-        from hermes_cli.skin_engine import get_active_skin
-        return get_active_skin()
-    except Exception:
-        return None
-
-
-def get_skin_faces(key: str, default: list) -> list:
-    """Get spinner face list from active skin, falling back to default."""
-    skin = _get_skin()
-    if skin:
-        faces = skin.get_spinner_list(key)
-        if faces:
-            return faces
-    return default
-
-
-def get_skin_verbs() -> list:
-    """Get thinking verbs from active skin."""
-    skin = _get_skin()
-    if skin:
-        verbs = skin.get_spinner_list("thinking_verbs")
-        if verbs:
-            return verbs
-    return KawaiiSpinner.THINKING_VERBS
-
-
-def get_skin_tool_prefix() -> str:
-    """Get tool output prefix character from active skin."""
-    skin = _get_skin()
-    if skin:
-        return skin.tool_prefix
-    return "┊"
-
 
 # =========================================================================
 # Tool preview (one-line summary of a tool call's primary argument)
@@ -65,8 +22,6 @@ def get_skin_tool_prefix() -> str:
 
 def build_tool_preview(tool_name: str, args: dict, max_len: int = 40) -> str:
     """Build a short preview of a tool call's primary argument for display."""
-    if not args:
-        return None
     primary_args = {
         "terminal": "command", "web_search": "query", "web_extract": "urls",
         "read_file": "path", "write_file": "path", "patch": "path",
@@ -208,7 +163,6 @@ class KawaiiSpinner:
         self.frame_idx = 0
         self.start_time = None
         self.last_line_len = 0
-        self._last_flush_time = 0.0  # Rate-limit flushes for patch_stdout compat
         # Capture stdout NOW, before any redirect_stdout(devnull) from
         # child agents can replace sys.stdout with a black hole.
         self._out = sys.stdout
@@ -223,34 +177,15 @@ class KawaiiSpinner:
             pass
 
     def _animate(self):
-        # Cache skin wings at start (avoid per-frame imports)
-        skin = _get_skin()
-        wings = skin.get_spinner_wings() if skin else []
-
         while self.running:
             if os.getenv("HERMES_SPINNER_PAUSE"):
                 time.sleep(0.1)
                 continue
             frame = self.spinner_frames[self.frame_idx % len(self.spinner_frames)]
             elapsed = time.time() - self.start_time
-            if wings:
-                left, right = wings[self.frame_idx % len(wings)]
-                line = f"  {left} {frame} {self.message} {right} ({elapsed:.1f}s)"
-            else:
-                line = f"  {frame} {self.message} ({elapsed:.1f}s)"
+            line = f"  {frame} {self.message} ({elapsed:.1f}s)"
             pad = max(self.last_line_len - len(line), 0)
-            # Rate-limit flush() calls to avoid spinner spam under
-            # prompt_toolkit's patch_stdout.  Each flush() pushes a queue
-            # item that may trigger a separate run_in_terminal() call; if
-            # items are processed one-at-a-time the \r overwrite is lost
-            # and every frame appears on its own line.  By flushing at
-            # most every 0.4s we guarantee multiple \r-frames are batched
-            # into a single write, so the terminal collapses them correctly.
-            now = time.time()
-            should_flush = (now - self._last_flush_time) >= 0.4
-            self._write(f"\r{line}{' ' * pad}", end='', flush=should_flush)
-            if should_flush:
-                self._last_flush_time = now
+            self._write(f"\r{line}{' ' * pad}", end='', flush=True)
             self.last_line_len = len(line)
             self.frame_idx += 1
             time.sleep(0.12)
@@ -365,7 +300,7 @@ def _detect_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]
             if exit_code is not None and exit_code != 0:
                 return True, f" [exit {exit_code}]"
         except (json.JSONDecodeError, TypeError, AttributeError):
-            logger.debug("Could not parse terminal result as JSON for exit code check")
+            pass
         return False, ""
 
     # Memory-specific: distinguish "full" from real errors
@@ -375,7 +310,7 @@ def _detect_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]
             if data.get("success") is False and "exceed the limit" in data.get("error", ""):
                 return True, " [full]"
         except (json.JSONDecodeError, TypeError, AttributeError):
-            logger.debug("Could not parse memory result as JSON for capacity check")
+            pass
 
     # Generic heuristic for non-terminal tools
     lower = result[:500].lower()
@@ -397,7 +332,6 @@ def get_cute_tool_message(
     """
     dur = f"{duration:.1f}s"
     is_failure, failure_suffix = _detect_tool_failure(tool_name, result)
-    skin_prefix = get_skin_tool_prefix()
 
     def _trunc(s, n=40):
         s = str(s)
@@ -408,9 +342,7 @@ def get_cute_tool_message(
         return ("..." + p[-(n-3):]) if len(p) > n else p
 
     def _wrap(line: str) -> str:
-        """Apply skin tool prefix and failure suffix."""
-        if skin_prefix != "┊":
-            line = line.replace("┊", skin_prefix, 1)
+        """Append failure suffix when the tool failed."""
         if not is_failure:
             return line
         return f"{line}{failure_suffix}"

agent/model_metadata.py

@@ -53,10 +53,8 @@ DEFAULT_CONTEXT_LENGTHS = {
     "glm-5": 202752,
     "glm-4.5": 131072,
     "glm-4.5-flash": 131072,
-    "kimi-for-coding": 262144,
     "kimi-k2.5": 262144,
     "kimi-k2-thinking": 262144,
-    "kimi-k2-thinking-turbo": 262144,
     "kimi-k2-turbo-preview": 262144,
     "kimi-k2-0905-preview": 131072,
     "MiniMax-M2.5": 204800,

agent/prompt_builder.py

@@ -122,23 +122,6 @@ PLATFORM_HINTS = {
         "attachments, audio as file attachments. You can also include image URLs "
         "in markdown format ![alt](url) and they will be uploaded as attachments."
     ),
-    "signal": (
-        "You are on a text messaging communication platform, Signal. "
-        "Please do not use markdown as it does not render. "
-        "You can send media files natively: to deliver a file to the user, "
-        "include MEDIA:/absolute/path/to/file in your response. Images "
-        "(.png, .jpg, .webp) appear as photos, audio as attachments, and other "
-        "files arrive as downloadable documents. You can also include image "
-        "URLs in markdown format ![alt](url) and they will be sent as photos."
-    ),
-    "email": (
-        "You are communicating via email. Write clear, well-structured responses "
-        "suitable for email. Use plain text formatting (no markdown). "
-        "Keep responses concise but complete. You can send file attachments — "
-        "include MEDIA:/absolute/path/to/file in your response. The subject line "
-        "is preserved for threading. Do not include greetings or sign-offs unless "
-        "contextually appropriate."
-    ),
     "cli": (
         "You are a CLI AI Agent. Try not to use markdown but simple text "
         "renderable inside a terminal."
@@ -167,8 +150,8 @@ def _read_skill_description(skill_file: Path, max_chars: int = 60) -> str:
             if len(desc) > max_chars:
                 desc = desc[:max_chars - 3] + "..."
             return desc
-    except Exception as e:
-        logger.debug("Failed to read skill description from %s: %s", skill_file, e)
+    except Exception:
+        pass
     return ""
 
 
@@ -187,58 +170,7 @@ def _skill_is_platform_compatible(skill_file: Path) -> bool:
         return True  # Err on the side of showing the skill
 
 
-def _read_skill_conditions(skill_file: Path) -> dict:
-    """Extract conditional activation fields from SKILL.md frontmatter."""
-    try:
-        from tools.skills_tool import _parse_frontmatter
-        raw = skill_file.read_text(encoding="utf-8")[:2000]
-        frontmatter, _ = _parse_frontmatter(raw)
-        hermes = frontmatter.get("metadata", {}).get("hermes", {})
-        return {
-            "fallback_for_toolsets": hermes.get("fallback_for_toolsets", []),
-            "requires_toolsets": hermes.get("requires_toolsets", []),
-            "fallback_for_tools": hermes.get("fallback_for_tools", []),
-            "requires_tools": hermes.get("requires_tools", []),
-        }
-    except Exception:
-        return {}
-
-
-def _skill_should_show(
-    conditions: dict,
-    available_tools: "set[str] | None",
-    available_toolsets: "set[str] | None",
-) -> bool:
-    """Return False if the skill's conditional activation rules exclude it."""
-    if available_tools is None and available_toolsets is None:
-        return True  # No filtering info — show everything (backward compat)
-
-    at = available_tools or set()
-    ats = available_toolsets or set()
-
-    # fallback_for: hide when the primary tool/toolset IS available
-    for ts in conditions.get("fallback_for_toolsets", []):
-        if ts in ats:
-            return False
-    for t in conditions.get("fallback_for_tools", []):
-        if t in at:
-            return False
-
-    # requires: hide when a required tool/toolset is NOT available
-    for ts in conditions.get("requires_toolsets", []):
-        if ts not in ats:
-            return False
-    for t in conditions.get("requires_tools", []):
-        if t not in at:
-            return False
-
-    return True
-
-
-def build_skills_system_prompt(
-    available_tools: "set[str] | None" = None,
-    available_toolsets: "set[str] | None" = None,
-) -> str:
+def build_skills_system_prompt() -> str:
     """Build a compact skill index for the system prompt.
 
     Scans ~/.hermes/skills/ for SKILL.md files grouped by category.
@@ -254,27 +186,16 @@ def build_skills_system_prompt(
 
     # Collect skills with descriptions, grouped by category
     # Each entry: (skill_name, description)
-    # Supports sub-categories: skills/mlops/training/axolotl/SKILL.md
-    # → category "mlops/training", skill "axolotl"
     skills_by_category: dict[str, list[tuple[str, str]]] = {}
     for skill_file in skills_dir.rglob("SKILL.md"):
         # Skip skills incompatible with the current OS platform
         if not _skill_is_platform_compatible(skill_file):
             continue
-        # Skip skills whose conditional activation rules exclude them
-        conditions = _read_skill_conditions(skill_file)
-        if not _skill_should_show(conditions, available_tools, available_toolsets):
-            continue
         rel_path = skill_file.relative_to(skills_dir)
         parts = rel_path.parts
         if len(parts) >= 2:
-            # Category is everything between skills_dir and the skill folder
-            # e.g. parts = ("mlops", "training", "axolotl", "SKILL.md")
-            #   → category = "mlops/training", skill_name = "axolotl"
-            # e.g. parts = ("github", "github-auth", "SKILL.md")
-            #   → category = "github", skill_name = "github-auth"
+            category = parts[0]
             skill_name = parts[-2]
-            category = "/".join(parts[:-2]) if len(parts) > 2 else parts[0]
         else:
             category = "general"
             skill_name = skill_file.parent.name
@@ -285,11 +206,9 @@ def build_skills_system_prompt(
         return ""
 
     # Read category-level descriptions from DESCRIPTION.md
-    # Checks both the exact category path and parent directories
     category_descriptions = {}
     for category in skills_by_category:
-        cat_path = Path(category)
-        desc_file = skills_dir / cat_path / "DESCRIPTION.md"
+        desc_file = skills_dir / category / "DESCRIPTION.md"
         if desc_file.exists():
             try:
                 content = desc_file.read_text(encoding="utf-8")

agent/redact.py

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

batch_runner.py

@@ -606,7 +606,7 @@ class BatchRunner:
         # Create batches
         self.batches = self._create_batches()
         
-        print("📊 Batch Runner Initialized")
+        print(f"📊 Batch Runner Initialized")
         print(f"   Dataset: {self.dataset_file} ({len(self.dataset)} prompts)")
         print(f"   Batch size: {self.batch_size}")
         print(f"   Total batches: {len(self.batches)}")
@@ -826,7 +826,7 @@ class BatchRunner:
             print("=" * 70)
             print(f"   Original dataset size:     {len(self.dataset):,} prompts")
             print(f"   Already completed:         {len(skipped_indices):,} prompts")
-            print("   ─────────────────────────────────────────")
+            print(f"   ─────────────────────────────────────────")
             print(f"   🎯 RESUMING WITH:          {len(filtered_entries):,} prompts")
             print(f"   New batches created:       {len(batches_to_process)}")
             print("=" * 70 + "\n")
@@ -888,7 +888,7 @@ class BatchRunner:
             ]
             
             print(f"✅ Created {len(tasks)} batch tasks")
-            print("🚀 Starting parallel batch processing...\n")
+            print(f"🚀 Starting parallel batch processing...\n")
             
             # Use rich Progress for better visual tracking with persistent bottom bar
             # redirect_stdout/stderr lets rich manage all output so progress bar stays clean
@@ -1057,7 +1057,7 @@ class BatchRunner:
         print(f"✅ Total trajectories in merged file: {total_entries - filtered_entries}")
         print(f"✅ Total batch files merged: {batch_files_found}")
         print(f"⏱️  Total duration: {round(time.time() - start_time, 2)}s")
-        print("\n📈 Tool Usage Statistics:")
+        print(f"\n📈 Tool Usage Statistics:")
         print("-" * 70)
         
         if total_tool_stats:
@@ -1084,7 +1084,7 @@ class BatchRunner:
         # Print reasoning coverage stats
         total_discarded = sum(r.get("discarded_no_reasoning", 0) for r in results)
         
-        print("\n🧠 Reasoning Coverage:")
+        print(f"\n🧠 Reasoning Coverage:")
         print("-" * 70)
         total_turns = total_reasoning_stats["total_assistant_turns"]
         with_reasoning = total_reasoning_stats["turns_with_reasoning"]
@@ -1101,8 +1101,8 @@ class BatchRunner:
             print(f"   🚫 Samples discarded (zero reasoning): {total_discarded:,}")
         
         print(f"\n💾 Results saved to: {self.output_dir}")
-        print("   - Trajectories: trajectories.jsonl (combined)")
-        print("   - Individual batches: batch_*.jsonl (for debugging)")
+        print(f"   - Trajectories: trajectories.jsonl (combined)")
+        print(f"   - Individual batches: batch_*.jsonl (for debugging)")
         print(f"   - Statistics: {self.stats_file.name}")
         print(f"   - Checkpoint: {self.checkpoint_file.name}")
 
@@ -1238,7 +1238,7 @@ def main(
             with open(prefill_messages_file, 'r', encoding='utf-8') as f:
                 prefill_messages = json.load(f)
             if not isinstance(prefill_messages, list):
-                print("❌ Error: prefill_messages_file must contain a JSON array of messages")
+                print(f"❌ Error: prefill_messages_file must contain a JSON array of messages")
                 return
             print(f"💬 Loaded {len(prefill_messages)} prefill messages from {prefill_messages_file}")
         except Exception as e:

cli-config.yaml.example

@@ -11,7 +11,6 @@ model:
   
   # Inference provider selection:
   #   "auto"       - Use Nous Portal if logged in, otherwise OpenRouter/env vars (default)
-  #   "nous-api"   - Use Nous Portal via API key (requires: NOUS_API_KEY)
   #   "openrouter" - Always use OpenRouter API key from OPENROUTER_API_KEY
   #   "nous"       - Always use Nous Portal (requires: hermes login)
   #   "zai"        - Use z.ai / ZhipuAI GLM models (requires: GLM_API_KEY)
@@ -210,58 +209,8 @@ compression:
   threshold: 0.85
   
   # Model to use for generating summaries (fast/cheap recommended)
-  # This model compresses the middle turns into a concise summary.
-  # IMPORTANT: it receives the full middle section of the conversation, so it
-  # MUST support a context length at least as large as your main model's.
+  # This model compresses the middle turns into a concise summary
   summary_model: "google/gemini-3-flash-preview"
-  
-  # Provider for the summary model (default: "auto")
-  # Options: "auto", "openrouter", "nous", "main"
-  # summary_provider: "auto"
-
-# =============================================================================
-# Auxiliary Models (Advanced — Experimental)
-# =============================================================================
-# Hermes uses lightweight "auxiliary" models for side tasks: image analysis,
-# browser screenshot analysis, web page summarization, and context compression.
-#
-# By default these use Gemini Flash via OpenRouter or Nous Portal and are
-# auto-detected from your credentials.  You do NOT need to change anything
-# here for normal usage.
-#
-# WARNING: Overriding these with providers other than OpenRouter or Nous Portal
-# is EXPERIMENTAL and may not work.  Not all models/providers support vision,
-# produce usable summaries, or accept the same API format.  Change at your own
-# risk — if things break, reset to "auto" / empty values.
-#
-# Each task has its own provider + model pair so you can mix providers.
-# For example: OpenRouter for vision (needs multimodal), but your main
-# local endpoint for compression (just needs text).
-#
-# Provider options:
-#   "auto"       - Best available: OpenRouter → Nous Portal → main endpoint (default)
-#   "openrouter" - Force OpenRouter (requires OPENROUTER_API_KEY)
-#   "nous"       - Force Nous Portal (requires: hermes login)
-#   "codex"      - Force Codex OAuth (requires: hermes model → Codex).
-#                  Uses gpt-5.3-codex which supports vision.
-#   "main"       - Use your custom endpoint (OPENAI_BASE_URL + OPENAI_API_KEY).
-#                  Works with OpenAI API, local models, or any OpenAI-compatible
-#                  endpoint.  Also falls back to Codex OAuth and API-key providers.
-#
-# Model: leave empty to use the provider's default.  When empty, OpenRouter
-# uses "google/gemini-3-flash-preview" and Nous uses "gemini-3-flash".
-# Other providers pick a sensible default automatically.
-#
-# auxiliary:
-#   # Image analysis: vision_analyze tool + browser screenshots
-#   vision:
-#     provider: "auto"
-#     model: ""              # e.g. "google/gemini-2.5-flash", "openai/gpt-4o"
-#
-#   # Web page scraping / summarization + browser page text extraction
-#   web_extract:
-#     provider: "auto"
-#     model: ""
 
 # =============================================================================
 # Persistent Memory
@@ -403,13 +352,11 @@ agent:
 #     discord: [web, vision, skills, todo]
 #
 # If not set, defaults are:
-#   cli:           hermes-cli            (everything + cronjob management)
-#   telegram:      hermes-telegram       (terminal, file, web, vision, image, tts, browser, skills, todo, cronjob, messaging)
-#   discord:       hermes-discord        (same as telegram)
-#   whatsapp:      hermes-whatsapp       (same as telegram)
-#   slack:         hermes-slack          (same as telegram)
-#   signal:        hermes-signal         (same as telegram)
-#   homeassistant: hermes-homeassistant  (same as telegram)
+#   cli:      hermes-cli      (everything + cronjob management)
+#   telegram: hermes-telegram  (terminal, file, web, vision, image, tts, browser, skills, todo, cronjob, messaging)
+#   discord:  hermes-discord   (same as telegram)
+#   whatsapp: hermes-whatsapp  (same as telegram)
+#   slack:    hermes-slack     (same as telegram)
 #
 platform_toolsets:
   cli: [hermes-cli]
@@ -417,8 +364,6 @@ platform_toolsets:
   discord: [hermes-discord]
   whatsapp: [hermes-whatsapp]
   slack: [hermes-slack]
-  signal: [hermes-signal]
-  homeassistant: [hermes-homeassistant]
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Available toolsets (use these names in platform_toolsets or the toolsets list)
@@ -560,21 +505,6 @@ toolsets:
 #     args: ["-y", "@modelcontextprotocol/server-github"]
 #     env:
 #       GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
-#
-# Sampling (server-initiated LLM requests) — enabled by default.
-# Per-server config under the 'sampling' key:
-#   analysis:
-#     command: npx
-#     args: ["-y", "analysis-server"]
-#     sampling:
-#       enabled: true           # default: true
-#       model: "gemini-3-flash" # override model (optional)
-#       max_tokens_cap: 4096    # max tokens per request
-#       timeout: 30             # LLM call timeout (seconds)
-#       max_rpm: 10             # max requests per minute
-#       allowed_models: []      # model whitelist (empty = all)
-#       max_tool_rounds: 5      # tool loop limit (0 = disable)
-#       log_level: "info"       # audit verbosity
 
 # =============================================================================
 # Voice Transcription (Speech-to-Text)
@@ -626,10 +556,6 @@ code_execution:
 delegation:
   max_iterations: 50                          # Max tool-calling turns per child (default: 50)
   default_toolsets: ["terminal", "file", "web"]  # Default toolsets for subagents
-  # model: "google/gemini-3-flash-preview"    # Override model for subagents (empty = inherit parent)
-  # provider: "openrouter"                    # Override provider for subagents (empty = inherit parent)
-  #                                           # Resolves full credentials (base_url, api_key) automatically.
-  #                                           # Supported: openrouter, nous, zai, kimi-coding, minimax
 
 # =============================================================================
 # Honcho Integration (Cross-Session User Modeling)
@@ -659,63 +585,3 @@ display:
   #   verbose: Full args, results, and debug logs (same as /verbose)
   # Toggle at runtime with /verbose in the CLI
   tool_progress: all
-
-  # Background process notifications (gateway/messaging only).
-  # Controls how chatty the process watcher is when you use
-  # terminal(background=true, check_interval=...) from Telegram/Discord/etc.
-  #   off:     No watcher messages at all
-  #   result:  Only the final completion message
-  #   error:   Only the final message when exit code != 0
-  #   all:     Running output updates + final message (default)
-  background_process_notifications: all
-
-  # Play terminal bell when agent finishes a response.
-  # Useful for long-running tasks — your terminal will ding when the agent is done.
-  # Works over SSH. Most terminals can be configured to flash the taskbar or play a sound.
-  bell_on_complete: false
-
-  # Show model reasoning/thinking before each response.
-  # When enabled, a dim box shows the model's thought process above the response.
-  # Toggle at runtime with /reasoning show or /reasoning hide.
-  show_reasoning: false
-
-  # ───────────────────────────────────────────────────────────────────────────
-  # Skin / Theme
-  # ───────────────────────────────────────────────────────────────────────────
-  # Customize CLI visual appearance — banner colors, spinner faces, tool prefix,
-  # response box label, and branding text. Change at runtime with /skin <name>.
-  #
-  # Built-in skins:
-  #   default  — Classic Hermes gold/kawaii
-  #   ares     — Crimson/bronze war-god theme with spinner wings
-  #   mono     — Clean grayscale monochrome
-  #   slate    — Cool blue developer-focused
-  #
-  # Custom skins: drop a YAML file in ~/.hermes/skins/<name>.yaml
-  # Schema (all fields optional, missing values inherit from default):
-  #
-  #   name: my-theme
-  #   description: Short description
-  #   colors:
-  #     banner_border: "#HEX"    # Panel border
-  #     banner_title: "#HEX"     # Panel title
-  #     banner_accent: "#HEX"    # Section headers (Available Tools, etc.)
-  #     banner_dim: "#HEX"       # Dim/muted text
-  #     banner_text: "#HEX"      # Body text (tool names, skill names)
-  #     ui_accent: "#HEX"        # UI accent color
-  #     response_border: "#HEX"  # Response box border color
-  #   spinner:
-  #     waiting_faces: ["(⚔)", "(⛨)"]       # Faces shown while waiting
-  #     thinking_faces: ["(⚔)", "(⌁)"]      # Faces shown while thinking
-  #     thinking_verbs: ["forging", "plotting"]  # Verbs for spinner messages
-  #     wings:                                # Optional left/right spinner decorations
-  #       - ["⟪⚔", "⚔⟫"]
-  #       - ["⟪▲", "▲⟫"]
-  #   branding:
-  #     agent_name: "My Agent"               # Banner title and branding
-  #     welcome: "Welcome message"           # Shown at CLI startup
-  #     response_label: " ⚔ Agent "         # Response box header label
-  #     prompt_symbol: "⚔ ❯ "              # Prompt symbol
-  #   tool_prefix: "╎"                       # Tool output line prefix (default: ┊)
-  #
-  skin: default

cron/jobs.py

@@ -26,35 +26,16 @@ except ImportError:
 # Configuration
 # =============================================================================
 
-HERMES_DIR = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+HERMES_DIR = Path.home() / ".hermes"
 CRON_DIR = HERMES_DIR / "cron"
 JOBS_FILE = CRON_DIR / "jobs.json"
 OUTPUT_DIR = CRON_DIR / "output"
 
 
-def _secure_dir(path: Path):
-    """Set directory to owner-only access (0700). No-op on Windows."""
-    try:
-        os.chmod(path, 0o700)
-    except (OSError, NotImplementedError):
-        pass  # Windows or other platforms where chmod is not supported
-
-
-def _secure_file(path: Path):
-    """Set file to owner-only read/write (0600). No-op on Windows."""
-    try:
-        if path.exists():
-            os.chmod(path, 0o600)
-    except (OSError, NotImplementedError):
-        pass
-
-
 def ensure_dirs():
-    """Ensure cron directories exist with secure permissions."""
+    """Ensure cron directories exist."""
     CRON_DIR.mkdir(parents=True, exist_ok=True)
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
-    _secure_dir(CRON_DIR)
-    _secure_dir(OUTPUT_DIR)
 
 
 # =============================================================================
@@ -168,22 +149,16 @@ def parse_schedule(schedule: str) -> Dict[str, Any]:
 
 
 def _ensure_aware(dt: datetime) -> datetime:
-    """Return a timezone-aware datetime in Hermes configured timezone.
+    """Make a naive datetime tz-aware using the configured timezone.
 
-    Backward compatibility:
-    - Older stored timestamps may be naive.
-    - Naive values are interpreted as *system-local wall time* (the timezone
-      `datetime.now()` used when they were created), then converted to the
-      configured Hermes timezone.
-
-    This preserves relative ordering for legacy naive timestamps across
-    timezone changes and avoids false not-due results.
+    Handles backward compatibility: timestamps stored before timezone support
+    are naive (server-local).  We assume they were in the same timezone as
+    the current configuration so comparisons work without crashing.
     """
-    target_tz = _hermes_now().tzinfo
     if dt.tzinfo is None:
-        local_tz = datetime.now().astimezone().tzinfo
-        return dt.replace(tzinfo=local_tz).astimezone(target_tz)
-    return dt.astimezone(target_tz)
+        tz = _hermes_now().tzinfo
+        return dt.replace(tzinfo=tz)
+    return dt
 
 
 def compute_next_run(schedule: Dict[str, Any], last_run_at: Optional[str] = None) -> Optional[str]:
@@ -248,7 +223,6 @@ def save_jobs(jobs: List[Dict[str, Any]]):
             f.flush()
             os.fsync(f.fileno())
         os.replace(tmp_path, JOBS_FILE)
-        _secure_file(JOBS_FILE)
     except BaseException:
         try:
             os.unlink(tmp_path)
@@ -426,13 +400,11 @@ def save_job_output(job_id: str, output: str):
     ensure_dirs()
     job_output_dir = OUTPUT_DIR / job_id
     job_output_dir.mkdir(parents=True, exist_ok=True)
-    _secure_dir(job_output_dir)
     
     timestamp = _hermes_now().strftime("%Y-%m-%d_%H-%M-%S")
     output_file = job_output_dir / f"{timestamp}.md"
     
     with open(output_file, 'w', encoding='utf-8') as f:
         f.write(output)
-    _secure_file(output_file)
     
     return output_file

cron/scheduler.py

@@ -45,7 +45,7 @@ _LOCK_FILE = _LOCK_DIR / ".tick.lock"
 
 
 def _resolve_origin(job: dict) -> Optional[dict]:
-    """Extract origin info from a job, preserving any extra routing metadata."""
+    """Extract origin info from a job, returning {platform, chat_id, chat_name} or None."""
     origin = job.get("origin")
     if not origin:
         return None
@@ -69,8 +69,6 @@ def _deliver_result(job: dict, content: str) -> None:
     if deliver == "local":
         return
 
-    thread_id = None
-
     # Resolve target platform + chat_id
     if deliver == "origin":
         if not origin:
@@ -78,7 +76,6 @@ def _deliver_result(job: dict, content: str) -> None:
             return
         platform_name = origin["platform"]
         chat_id = origin["chat_id"]
-        thread_id = origin.get("thread_id")
     elif ":" in deliver:
         platform_name, chat_id = deliver.split(":", 1)
     else:
@@ -86,7 +83,6 @@ def _deliver_result(job: dict, content: str) -> None:
         platform_name = deliver
         if origin and origin.get("platform") == platform_name:
             chat_id = origin["chat_id"]
-            thread_id = origin.get("thread_id")
         else:
             # Fall back to home channel
             chat_id = os.getenv(f"{platform_name.upper()}_HOME_CHANNEL", "")
@@ -102,8 +98,6 @@ def _deliver_result(job: dict, content: str) -> None:
         "discord": Platform.DISCORD,
         "slack": Platform.SLACK,
         "whatsapp": Platform.WHATSAPP,
-        "signal": Platform.SIGNAL,
-        "email": Platform.EMAIL,
     }
     platform = platform_map.get(platform_name.lower())
     if not platform:
@@ -123,13 +117,13 @@ def _deliver_result(job: dict, content: str) -> None:
 
     # Run the async send in a fresh event loop (safe from any thread)
     try:
-        result = asyncio.run(_send_to_platform(platform, pconfig, chat_id, content, thread_id=thread_id))
+        result = asyncio.run(_send_to_platform(platform, pconfig, chat_id, content))
     except RuntimeError:
         # asyncio.run() fails if there's already a running loop in this thread;
         # spin up a new thread to avoid that.
         import concurrent.futures
         with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, content, thread_id=thread_id))
+            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, content))
             result = future.result(timeout=30)
     except Exception as e:
         logger.error("Job '%s': delivery to %s:%s failed: %s", job["id"], platform_name, chat_id, e)
@@ -142,9 +136,9 @@ def _deliver_result(job: dict, content: str) -> None:
         # Mirror the delivered content into the target's gateway session
         try:
             from gateway.mirror import mirror_to_session
-            mirror_to_session(platform_name, chat_id, content, source_label="cron", thread_id=thread_id)
-        except Exception as e:
-            logger.warning("Job '%s': mirror_to_session failed: %s", job["id"], e)
+            mirror_to_session(platform_name, chat_id, content, source_label="cron")
+        except Exception:
+            pass
 
 
 def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
@@ -180,7 +174,7 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         except UnicodeDecodeError:
             load_dotenv(str(_hermes_home / ".env"), override=True, encoding="latin-1")
 
-        model = os.getenv("HERMES_MODEL") or "anthropic/claude-opus-4.6"
+        model = os.getenv("HERMES_MODEL") or os.getenv("LLM_MODEL") or "anthropic/claude-opus-4.6"
 
         # Load config.yaml for model, reasoning, prefill, toolsets, provider routing
         _cfg = {}
@@ -195,8 +189,8 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
                     model = _model_cfg
                 elif isinstance(_model_cfg, dict):
                     model = _model_cfg.get("default", model)
-        except Exception as e:
-            logger.warning("Job '%s': failed to load config.yaml, using defaults: %s", job_id, e)
+        except Exception:
+            pass
 
         # Reasoning config from env or config.yaml
         reasoning_config = None
@@ -224,8 +218,7 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
                         prefill_messages = _json.load(_pf)
                     if not isinstance(prefill_messages, list):
                         prefill_messages = None
-                except Exception as e:
-                    logger.warning("Job '%s': failed to parse prefill messages file '%s': %s", job_id, pfpath, e)
+                except Exception:
                     prefill_messages = None
 
         # Max iterations

datagen-config-examples/web_research.yaml

@@ -1,46 +0,0 @@
-# datagen-config-examples/web_research.yaml
-#
-# Batch data generation config for WebResearchEnv.
-# Generates tool-calling trajectories for multi-step web research tasks.
-#
-# Usage:
-#   python batch_runner.py \
-#     --config datagen-config-examples/web_research.yaml \
-#     --run_name web_research_v1
-
-environment: web-research
-
-# Toolsets available to the agent during data generation
-toolsets:
-  - web
-  - file
-
-# How many parallel workers to use
-num_workers: 4
-
-# Questions per batch
-batch_size: 20
-
-# Total trajectories to generate (comment out to run full dataset)
-max_items: 500
-
-# Model to use for generation (override with --model flag)
-model: openrouter/nousresearch/hermes-3-llama-3.1-405b
-
-# System prompt additions (ephemeral — not saved to trajectories)
-ephemeral_system_prompt: |
-  You are a highly capable research agent. When asked a factual question,
-  always use web_search to find current, accurate information before answering.
-  Cite at least 2 sources. Be concise and accurate.
-
-# Output directory
-output_dir: data/web_research_v1
-
-# Trajectory compression settings (for fitting into training token budgets)
-compression:
-  enabled: true
-  target_max_tokens: 16000
-
-# Eval settings
-eval_every: 100       # Run eval every N trajectories
-eval_size: 25         # Number of held-out questions per eval run

docs/README.md

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

docs/migration/openclaw.md

@@ -1,110 +0,0 @@
-# Migrating from OpenClaw to Hermes Agent
-
-This guide covers how to import your OpenClaw settings, memories, skills, and API keys into Hermes Agent.
-
-## Three Ways to Migrate
-
-### 1. Automatic (during first-time setup)
-
-When you run `hermes setup` for the first time and Hermes detects `~/.openclaw`, it automatically offers to import your OpenClaw data before configuration begins. Just accept the prompt and everything is handled for you.
-
-### 2. CLI Command (quick, scriptable)
-
-```bash
-hermes claw migrate                      # Full migration with confirmation prompt
-hermes claw migrate --dry-run            # Preview what would happen
-hermes claw migrate --preset user-data   # Migrate without API keys/secrets
-hermes claw migrate --yes                # Skip confirmation prompt
-```
-
-**All options:**
-
-| Flag | Description |
-|------|-------------|
-| `--source PATH` | Path to OpenClaw directory (default: `~/.openclaw`) |
-| `--dry-run` | Preview only — no files are modified |
-| `--preset {user-data,full}` | Migration preset (default: `full`). `user-data` excludes secrets |
-| `--overwrite` | Overwrite existing files (default: skip conflicts) |
-| `--migrate-secrets` | Include allowlisted secrets (auto-enabled with `full` preset) |
-| `--workspace-target PATH` | Copy workspace instructions (AGENTS.md) to this absolute path |
-| `--skill-conflict {skip,overwrite,rename}` | How to handle skill name conflicts (default: `skip`) |
-| `--yes`, `-y` | Skip confirmation prompts |
-
-### 3. Agent-Guided (interactive, with previews)
-
-Ask the agent to run the migration for you:
-
-```
-> Migrate my OpenClaw setup to Hermes
-```
-
-The agent will use the `openclaw-migration` skill to:
-1. Run a dry-run first to preview changes
-2. Ask about conflict resolution (SOUL.md, skills, etc.)
-3. Let you choose between `user-data` and `full` presets
-4. Execute the migration with your choices
-5. Print a detailed summary of what was migrated
-
-## What Gets Migrated
-
-### `user-data` preset
-| Item | Source | Destination |
-|------|--------|-------------|
-| SOUL.md | `~/.openclaw/workspace/SOUL.md` | `~/.hermes/SOUL.md` |
-| Memory entries | `~/.openclaw/workspace/MEMORY.md` | `~/.hermes/memories/MEMORY.md` |
-| User profile | `~/.openclaw/workspace/USER.md` | `~/.hermes/memories/USER.md` |
-| Skills | `~/.openclaw/workspace/skills/` | `~/.hermes/skills/openclaw-imports/` |
-| Command allowlist | `~/.openclaw/workspace/exec_approval_patterns.yaml` | Merged into `~/.hermes/config.yaml` |
-| Messaging settings | `~/.openclaw/config.yaml` (TELEGRAM_ALLOWED_USERS, MESSAGING_CWD) | `~/.hermes/.env` |
-| TTS assets | `~/.openclaw/workspace/tts/` | `~/.hermes/tts/` |
-
-### `full` preset (adds to `user-data`)
-| Item | Source | Destination |
-|------|--------|-------------|
-| Telegram bot token | `~/.openclaw/config.yaml` | `~/.hermes/.env` |
-| OpenRouter API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
-| OpenAI API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
-| Anthropic API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
-| ElevenLabs API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
-
-Only these 6 allowlisted secrets are ever imported. Other credentials are skipped and reported.
-
-## Conflict Handling
-
-By default, the migration **will not overwrite** existing Hermes data:
-
-- **SOUL.md** — skipped if one already exists in `~/.hermes/`
-- **Memory entries** — skipped if memories already exist (to avoid duplicates)
-- **Skills** — skipped if a skill with the same name already exists
-- **API keys** — skipped if the key is already set in `~/.hermes/.env`
-
-To overwrite conflicts, use `--overwrite`. The migration creates backups before overwriting.
-
-For skills, you can also use `--skill-conflict rename` to import conflicting skills under a new name (e.g., `skill-name-imported`).
-
-## Migration Report
-
-Every migration (including dry runs) produces a report showing:
-- **Migrated items** — what was successfully imported
-- **Conflicts** — items skipped because they already exist
-- **Skipped items** — items not found in the source
-- **Errors** — items that failed to import
-
-For execute runs, the full report is saved to `~/.hermes/migration/openclaw/<timestamp>/`.
-
-## Troubleshooting
-
-### "OpenClaw directory not found"
-The migration looks for `~/.openclaw` by default. If your OpenClaw is installed elsewhere, use `--source`:
-```bash
-hermes claw migrate --source /path/to/.openclaw
-```
-
-### "Migration script not found"
-The migration script ships with Hermes Agent. If you installed via pip (not git clone), the `optional-skills/` directory may not be present. Install the skill from the Skills Hub:
-```bash
-hermes skills install openclaw-migration
-```
-
-### Memory overflow
-If your OpenClaw MEMORY.md or USER.md exceeds Hermes' character limits, excess entries are exported to an overflow file in the migration report directory. You can manually review and add the most important ones.

docs/send_file_integration_map.md

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

docs/skins/example-skin.yaml

@@ -1,89 +0,0 @@
-# ============================================================================
-# Hermes Agent — Example Skin Template
-# ============================================================================
-#
-# Copy this file to ~/.hermes/skins/<name>.yaml to create a custom skin.
-# All fields are optional — missing values inherit from the default skin.
-# Activate with: /skin <name>  or  display.skin: <name> in config.yaml
-#
-# See hermes_cli/skin_engine.py for the full schema reference.
-# ============================================================================
-
-# Required: unique skin name (used in /skin command and config)
-name: example
-description: An example custom skin — copy and modify this template
-
-# ── Colors ──────────────────────────────────────────────────────────────────
-# Hex color values for Rich markup. These control the CLI's visual palette.
-colors:
-  # Banner panel (the startup welcome box)
-  banner_border: "#CD7F32"        # Panel border
-  banner_title: "#FFD700"         # Panel title text
-  banner_accent: "#FFBF00"        # Section headers (Available Tools, Skills, etc.)
-  banner_dim: "#B8860B"           # Dim/muted text (separators, model info)
-  banner_text: "#FFF8DC"          # Body text (tool names, skill names)
-
-  # UI elements
-  ui_accent: "#FFBF00"            # General accent color
-  ui_label: "#4dd0e1"             # Labels
-  ui_ok: "#4caf50"                # Success indicators
-  ui_error: "#ef5350"             # Error indicators
-  ui_warn: "#ffa726"              # Warning indicators
-
-  # Input area
-  prompt: "#FFF8DC"               # Prompt text color
-  input_rule: "#CD7F32"           # Horizontal rule around input
-
-  # Response box
-  response_border: "#FFD700"      # Response box border (ANSI color)
-
-  # Session display
-  session_label: "#DAA520"        # Session label
-  session_border: "#8B8682"       # Session ID dim color
-
-# ── Spinner ─────────────────────────────────────────────────────────────────
-# Customize the animated spinner shown during API calls and tool execution.
-spinner:
-  # Faces shown while waiting for the API response
-  waiting_faces:
-    - "(｡◕‿◕｡)"
-    - "(◕‿◕✿)"
-    - "٩(◕‿◕｡)۶"
-
-  # Faces shown during extended thinking/reasoning
-  thinking_faces:
-    - "(｡•́︿•̀｡)"
-    - "(◔_◔)"
-    - "(¬‿¬)"
-
-  # Verbs used in spinner messages (e.g., "pondering your request...")
-  thinking_verbs:
-    - "pondering"
-    - "contemplating"
-    - "musing"
-    - "ruminating"
-
-  # Optional: left/right decorations around the spinner
-  # Each entry is a [left, right] pair. Omit entirely for no wings.
-  # wings:
-  #   - ["⟪⚔", "⚔⟫"]
-  #   - ["⟪▲", "▲⟫"]
-
-# ── Branding ────────────────────────────────────────────────────────────────
-# Text strings used throughout the CLI interface.
-branding:
-  agent_name: "Hermes Agent"          # Banner title, about display
-  welcome: "Welcome! Type your message or /help for commands."
-  goodbye: "Goodbye! ⚕"              # Exit message
-  response_label: " ⚕ Hermes "       # Response box header label
-  prompt_symbol: "❯ "                 # Input prompt symbol
-  help_header: "(^_^)? Available Commands"  # /help header text
-
-# ── Tool Output ─────────────────────────────────────────────────────────────
-# Character used as the prefix for tool output lines.
-# Default is "┊" (thin dotted vertical line). Some alternatives:
-#   "╎" (light triple dash vertical)
-#   "▏" (left one-eighth block)
-#   "│" (box drawing light vertical)
-#   "┃" (box drawing heavy vertical)
-tool_prefix: "┊"

environments/benchmarks/terminalbench_2/default.yaml

@@ -29,10 +29,6 @@ env:
   wandb_name: "terminal-bench-2"
   ensure_scores_are_not_same: false
   data_dir_to_save_evals: "environments/benchmarks/evals/terminal-bench-2"
-  # CRITICAL: Limit concurrent Modal sandbox creations to avoid deadlocks.
-  # Modal's blocking calls (App.lookup, etc.) deadlock when too many sandboxes
-  # are created simultaneously inside thread pool workers via asyncio.run().
-  max_concurrent_tasks: 8
 
 openai:
   base_url: "https://openrouter.ai/api/v1"

environments/benchmarks/terminalbench_2/terminalbench2_env.py

@@ -118,15 +118,6 @@ class TerminalBench2EvalConfig(HermesAgentEnvConfig):
         "Tasks exceeding this are scored as FAIL. Default 30 minutes.",
     )
 
-    # --- Concurrency control ---
-    max_concurrent_tasks: int = Field(
-        default=8,
-        description="Maximum number of tasks to run concurrently. "
-        "Limits concurrent Modal sandbox creations to avoid async/threading deadlocks. "
-        "Modal has internal limits and creating too many sandboxes simultaneously "
-        "causes blocking calls to deadlock inside the thread pool.",
-    )
-
     # --- Eval concurrency ---
     eval_concurrency: int = Field(
         default=0,
@@ -209,7 +200,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
 
             # Agent settings -- TB2 tasks are complex, need many turns
             max_agent_turns=60,
-            max_token_length=***
+            max_token_length=16000,
             agent_temperature=0.6,
             system_prompt=None,
 
@@ -233,7 +224,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
             steps_per_eval=1,
             total_steps=1,
 
-            tokenizer_name="NousRe...1-8B",
+            tokenizer_name="NousResearch/Hermes-3-Llama-3.1-8B",
             use_wandb=True,
             wandb_name="terminal-bench-2",
             ensure_scores_are_not_same=False,  # Binary rewards may all be 0 or 1
@@ -245,7 +236,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                 base_url="https://openrouter.ai/api/v1",
                 model_name="anthropic/claude-sonnet-4",
                 server_type="openai",
-                api_key=os.get...EY", ""),
+                api_key=os.getenv("OPENROUTER_API_KEY", ""),
                 health_check=False,
             )
         ]
@@ -452,7 +443,6 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
             register_task_env_overrides(task_id, {
                 "modal_image": modal_image,
                 "docker_image": modal_image,
-                "cwd": "/app",
             })
             logger.info(
                 "Task %s: registered image override for task_id %s",
@@ -513,3 +503,451 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                 reward = 0.0
             else:
                 # Run tests in a thread so the blocking ctx.terminal() calls
+                # don't freeze the entire event loop (which would stall all
+                # other tasks, tqdm updates, and timeout timers).
+                ctx = ToolContext(task_id)
+                try:
+                    loop = asyncio.get_event_loop()
+                    reward = await loop.run_in_executor(
+                        None,  # default thread pool
+                        self._run_tests, eval_item, ctx, task_name,
+                    )
+                except Exception as e:
+                    logger.error("Task %s: test verification failed: %s", task_name, e)
+                    reward = 0.0
+                finally:
+                    ctx.cleanup()
+
+            passed = reward == 1.0
+            status = "PASS" if passed else "FAIL"
+            elapsed = time.time() - task_start
+            tqdm.write(f"  [{status}] {task_name} (turns={result.turns_used}, {elapsed:.0f}s)")
+            logger.info(
+                "Task %s: reward=%.1f, turns=%d, finished=%s",
+                task_name, reward, result.turns_used, result.finished_naturally,
+            )
+
+            out = {
+                "passed": passed,
+                "reward": reward,
+                "task_name": task_name,
+                "category": category,
+                "turns_used": result.turns_used,
+                "finished_naturally": result.finished_naturally,
+                "messages": result.messages,
+            }
+            self._save_result(out)
+            return out
+
+        except Exception as e:
+            elapsed = time.time() - task_start
+            logger.error("Task %s: rollout failed: %s", task_name, e, exc_info=True)
+            tqdm.write(f"  [ERROR] {task_name}: {e} ({elapsed:.0f}s)")
+            out = {
+                "passed": False, "reward": 0.0,
+                "task_name": task_name, "category": category,
+                "error": str(e),
+            }
+            self._save_result(out)
+            return out
+
+        finally:
+            # --- Cleanup: clear overrides, sandbox, and temp files ---
+            clear_task_env_overrides(task_id)
+            try:
+                cleanup_vm(task_id)
+            except Exception as e:
+                logger.debug("VM cleanup for %s: %s", task_id[:8], e)
+            if task_dir and task_dir.exists():
+                shutil.rmtree(task_dir, ignore_errors=True)
+
+    def _run_tests(
+        self, item: Dict[str, Any], ctx: ToolContext, task_name: str
+    ) -> float:
+        """
+        Upload and execute the test suite in the agent's sandbox, then
+        download the verifier output locally to read the reward.
+
+        Follows Harbor's verification pattern:
+        1. Upload tests/ directory into the sandbox
+        2. Execute test.sh inside the sandbox
+        3. Download /logs/verifier/ directory to a local temp dir
+        4. Read reward.txt locally with native Python I/O
+
+        Downloading locally avoids issues with the file_read tool on
+        the Modal VM and matches how Harbor handles verification.
+
+        TB2 test scripts (test.sh) typically:
+        1. Install pytest via uv/pip
+        2. Run pytest against the test files in /tests/
+        3. Write results to /logs/verifier/reward.txt
+
+        Args:
+            item: The TB2 task dict (contains tests_tar, test_sh)
+            ctx: ToolContext scoped to this task's sandbox
+            task_name: For logging
+
+        Returns:
+            1.0 if tests pass, 0.0 otherwise
+        """
+        tests_tar = item.get("tests_tar", "")
+        test_sh = item.get("test_sh", "")
+
+        if not test_sh:
+            logger.warning("Task %s: no test_sh content, reward=0", task_name)
+            return 0.0
+
+        # Create required directories in the sandbox
+        ctx.terminal("mkdir -p /tests /logs/verifier")
+
+        # Upload test files into the sandbox (binary-safe via base64)
+        if tests_tar:
+            tests_temp = Path(tempfile.mkdtemp(prefix=f"tb2-tests-{task_name}-"))
+            try:
+                _extract_base64_tar(tests_tar, tests_temp)
+                ctx.upload_dir(str(tests_temp), "/tests")
+            except Exception as e:
+                logger.warning("Task %s: failed to upload test files: %s", task_name, e)
+            finally:
+                shutil.rmtree(tests_temp, ignore_errors=True)
+
+        # Write the test runner script (test.sh)
+        ctx.write_file("/tests/test.sh", test_sh)
+        ctx.terminal("chmod +x /tests/test.sh")
+
+        # Execute the test suite
+        logger.info(
+            "Task %s: running test suite (timeout=%ds)",
+            task_name, self.config.test_timeout,
+        )
+        test_result = ctx.terminal(
+            "bash /tests/test.sh",
+            timeout=self.config.test_timeout,
+        )
+
+        exit_code = test_result.get("exit_code", -1)
+        output = test_result.get("output", "")
+
+        # Download the verifier output directory locally, then read reward.txt
+        # with native Python I/O. This avoids issues with file_read on the
+        # Modal VM and matches Harbor's verification pattern.
+        reward = 0.0
+        local_verifier_dir = Path(tempfile.mkdtemp(prefix=f"tb2-verifier-{task_name}-"))
+        try:
+            ctx.download_dir("/logs/verifier", str(local_verifier_dir))
+
+            reward_file = local_verifier_dir / "reward.txt"
+            if reward_file.exists() and reward_file.stat().st_size > 0:
+                content = reward_file.read_text().strip()
+                if content == "1":
+                    reward = 1.0
+                elif content == "0":
+                    reward = 0.0
+                else:
+                    # Unexpected content -- try parsing as float
+                    try:
+                        reward = float(content)
+                    except (ValueError, TypeError):
+                        logger.warning(
+                            "Task %s: reward.txt content unexpected (%r), "
+                            "falling back to exit_code=%d",
+                            task_name, content, exit_code,
+                        )
+                        reward = 1.0 if exit_code == 0 else 0.0
+            else:
+                # reward.txt not written -- fall back to exit code
+                logger.warning(
+                    "Task %s: reward.txt not found after download, "
+                    "falling back to exit_code=%d",
+                    task_name, exit_code,
+                )
+                reward = 1.0 if exit_code == 0 else 0.0
+        except Exception as e:
+            logger.warning(
+                "Task %s: failed to download verifier dir: %s, "
+                "falling back to exit_code=%d",
+                task_name, e, exit_code,
+            )
+            reward = 1.0 if exit_code == 0 else 0.0
+        finally:
+            shutil.rmtree(local_verifier_dir, ignore_errors=True)
+
+        # Log test output for debugging failures
+        if reward == 0.0:
+            output_preview = output[-500:] if output else "(no output)"
+            logger.info(
+                "Task %s: FAIL (exit_code=%d)\n%s",
+                task_name, exit_code, output_preview,
+            )
+
+        return reward
+
+    # =========================================================================
+    # Evaluate -- main entry point for the eval subcommand
+    # =========================================================================
+
+    async def _eval_with_timeout(self, item: Dict[str, Any]) -> Dict:
+        """
+        Wrap rollout_and_score_eval with a per-task wall-clock timeout
+        and optional concurrency limit via semaphore.
+
+        If the task exceeds task_timeout seconds, it's automatically scored
+        as FAIL. This prevents any single task from hanging indefinitely.
+        """
+        task_name = item.get("task_name", "unknown")
+        category = item.get("category", "unknown")
+
+        # Acquire concurrency semaphore if configured
+        if self._eval_semaphore:
+            await self._eval_semaphore.acquire()
+
+        try:
+            return await asyncio.wait_for(
+                self.rollout_and_score_eval(item),
+                timeout=self.config.task_timeout,
+            )
+        except asyncio.TimeoutError:
+            from tqdm import tqdm
+            elapsed = self.config.task_timeout
+            tqdm.write(f"  [TIMEOUT] {task_name} (exceeded {elapsed}s wall-clock limit)")
+            logger.error("Task %s: wall-clock timeout after %ds", task_name, elapsed)
+            out = {
+                "passed": False, "reward": 0.0,
+                "task_name": task_name, "category": category,
+                "error": f"timeout ({elapsed}s)",
+            }
+            self._save_result(out)
+            return out
+        finally:
+            if self._eval_semaphore:
+                self._eval_semaphore.release()
+
+    async def evaluate(self, *args, **kwargs) -> None:
+        """
+        Run Terminal-Bench 2.0 evaluation over all tasks.
+
+        This is the main entry point when invoked via:
+            python environments/terminalbench2_env.py evaluate
+
+        Runs all tasks through rollout_and_score_eval() via asyncio.gather()
+        (same pattern as GPQA and other Atropos eval envs). Each task is
+        wrapped with a wall-clock timeout so hung tasks auto-fail.
+
+        Suppresses noisy Modal/terminal output (HERMES_QUIET) so the tqdm
+        bar stays visible.
+        """
+        start_time = time.time()
+
+        # Set up concurrency limit if configured
+        if self.config.eval_concurrency > 0:
+            self._eval_semaphore = asyncio.Semaphore(self.config.eval_concurrency)
+            print(f"  Eval concurrency: {self.config.eval_concurrency} tasks at a time")
+        else:
+            self._eval_semaphore = None
+
+        # Route all logging through tqdm.write() so the progress bar stays
+        # pinned at the bottom while log lines scroll above it.
+        from tqdm import tqdm
+
+        class _TqdmHandler(logging.Handler):
+            def emit(self, record):
+                try:
+                    tqdm.write(self.format(record))
+                except Exception:
+                    self.handleError(record)
+
+        handler = _TqdmHandler()
+        handler.setFormatter(logging.Formatter(
+            "%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+            datefmt="%H:%M:%S",
+        ))
+        root = logging.getLogger()
+        root.handlers = [handler]  # Replace any existing handlers
+        root.setLevel(logging.INFO)
+
+        # Silence noisy third-party loggers that flood the output
+        logging.getLogger("httpx").setLevel(logging.WARNING)      # Every HTTP request
+        logging.getLogger("openai").setLevel(logging.WARNING)     # OpenAI client retries
+        logging.getLogger("rex-deploy").setLevel(logging.WARNING) # Swerex deployment
+        logging.getLogger("rex_image_builder").setLevel(logging.WARNING)  # Image builds
+
+        print(f"\n{'='*60}")
+        print("Starting Terminal-Bench 2.0 Evaluation")
+        print(f"{'='*60}")
+        print(f"  Dataset: {self.config.dataset_name}")
+        print(f"  Total tasks: {len(self.all_eval_items)}")
+        print(f"  Max agent turns: {self.config.max_agent_turns}")
+        print(f"  Task timeout: {self.config.task_timeout}s")
+        print(f"  Terminal backend: {self.config.terminal_backend}")
+        print(f"  Tool thread pool: {self.config.tool_pool_size}")
+        print(f"  Terminal timeout: {self.config.terminal_timeout}s/cmd")
+        print(f"  Terminal lifetime: {self.config.terminal_lifetime}s (auto: task_timeout + 120)")
+        print(f"{'='*60}\n")
+
+        # Fire all tasks with wall-clock timeout, track live accuracy on the bar
+        total_tasks = len(self.all_eval_items)
+        eval_tasks = [
+            asyncio.ensure_future(self._eval_with_timeout(item))
+            for item in self.all_eval_items
+        ]
+
+        results = []
+        passed_count = 0
+        pbar = tqdm(total=total_tasks, desc="Evaluating TB2", dynamic_ncols=True)
+        try:
+            for coro in asyncio.as_completed(eval_tasks):
+                result = await coro
+                results.append(result)
+                if result and result.get("passed"):
+                    passed_count += 1
+                done = len(results)
+                pct = (passed_count / done * 100) if done else 0
+                pbar.set_postfix_str(f"pass={passed_count}/{done} ({pct:.1f}%)")
+                pbar.update(1)
+        except (KeyboardInterrupt, asyncio.CancelledError):
+            pbar.close()
+            print(f"\n\nInterrupted! Cleaning up {len(eval_tasks)} tasks...")
+            # Cancel all pending tasks
+            for task in eval_tasks:
+                task.cancel()
+            # Let cancellations propagate (finally blocks run cleanup_vm)
+            await asyncio.gather(*eval_tasks, return_exceptions=True)
+            # Belt-and-suspenders: clean up any remaining sandboxes
+            from tools.terminal_tool import cleanup_all_environments
+            cleanup_all_environments()
+            print("All sandboxes cleaned up.")
+            return
+        finally:
+            pbar.close()
+
+        end_time = time.time()
+
+        # Filter out None results (shouldn't happen, but be safe)
+        valid_results = [r for r in results if r is not None]
+
+        if not valid_results:
+            print("Warning: No valid evaluation results obtained")
+            return
+
+        # ---- Compute metrics ----
+        total = len(valid_results)
+        passed = sum(1 for r in valid_results if r.get("passed"))
+        overall_pass_rate = passed / total if total > 0 else 0.0
+
+        # Per-category breakdown
+        cat_results: Dict[str, List[Dict]] = defaultdict(list)
+        for r in valid_results:
+            cat_results[r.get("category", "unknown")].append(r)
+
+        # Build metrics dict
+        eval_metrics = {
+            "eval/pass_rate": overall_pass_rate,
+            "eval/total_tasks": total,
+            "eval/passed_tasks": passed,
+            "eval/evaluation_time_seconds": end_time - start_time,
+        }
+
+        # Per-category metrics
+        for category, cat_items in sorted(cat_results.items()):
+            cat_passed = sum(1 for r in cat_items if r.get("passed"))
+            cat_total = len(cat_items)
+            cat_pass_rate = cat_passed / cat_total if cat_total > 0 else 0.0
+            cat_key = category.replace(" ", "_").replace("-", "_").lower()
+            eval_metrics[f"eval/pass_rate_{cat_key}"] = cat_pass_rate
+
+        # Store metrics for wandb_log
+        self.eval_metrics = [(k, v) for k, v in eval_metrics.items()]
+
+        # ---- Print summary ----
+        print(f"\n{'='*60}")
+        print("Terminal-Bench 2.0 Evaluation Results")
+        print(f"{'='*60}")
+        print(f"Overall Pass Rate: {overall_pass_rate:.4f} ({passed}/{total})")
+        print(f"Evaluation Time: {end_time - start_time:.1f} seconds")
+
+        print("\nCategory Breakdown:")
+        for category, cat_items in sorted(cat_results.items()):
+            cat_passed = sum(1 for r in cat_items if r.get("passed"))
+            cat_total = len(cat_items)
+            cat_rate = cat_passed / cat_total if cat_total > 0 else 0.0
+            print(f"  {category}: {cat_rate:.1%} ({cat_passed}/{cat_total})")
+
+        # Print individual task results
+        print("\nTask Results:")
+        for r in sorted(valid_results, key=lambda x: x.get("task_name", "")):
+            status = "PASS" if r.get("passed") else "FAIL"
+            turns = r.get("turns_used", "?")
+            error = r.get("error", "")
+            extra = f" (error: {error})" if error else ""
+            print(f"  [{status}] {r['task_name']} (turns={turns}){extra}")
+
+        print(f"{'='*60}\n")
+
+        # Build sample records for evaluate_log (includes full conversations)
+        samples = [
+            {
+                "task_name": r.get("task_name"),
+                "category": r.get("category"),
+                "passed": r.get("passed"),
+                "reward": r.get("reward"),
+                "turns_used": r.get("turns_used"),
+                "error": r.get("error"),
+                "messages": r.get("messages"),
+            }
+            for r in valid_results
+        ]
+
+        # Log evaluation results
+        try:
+            await self.evaluate_log(
+                metrics=eval_metrics,
+                samples=samples,
+                start_time=start_time,
+                end_time=end_time,
+                generation_parameters={
+                    "temperature": self.config.agent_temperature,
+                    "max_tokens": self.config.max_token_length,
+                    "max_agent_turns": self.config.max_agent_turns,
+                    "terminal_backend": self.config.terminal_backend,
+                },
+            )
+        except Exception as e:
+            print(f"Error logging evaluation results: {e}")
+
+        # Close streaming file
+        if hasattr(self, "_streaming_file") and not self._streaming_file.closed:
+            self._streaming_file.close()
+            print(f"  Live results saved to: {self._streaming_path}")
+
+        # Kill all remaining sandboxes. Timed-out tasks leave orphaned thread
+        # pool workers still executing commands -- cleanup_all stops them.
+        from tools.terminal_tool import cleanup_all_environments
+        print("\nCleaning up all sandboxes...")
+        cleanup_all_environments()
+
+        # Shut down the tool thread pool so orphaned workers from timed-out
+        # tasks are killed immediately instead of retrying against dead
+        # sandboxes and spamming the console with TimeoutError warnings.
+        from environments.agent_loop import _tool_executor
+        _tool_executor.shutdown(wait=False, cancel_futures=True)
+        print("Done.")
+
+    # =========================================================================
+    # Wandb logging
+    # =========================================================================
+
+    async def wandb_log(self, wandb_metrics: Optional[Dict] = None):
+        """Log TB2-specific metrics to wandb."""
+        if wandb_metrics is None:
+            wandb_metrics = {}
+
+        # Add stored eval metrics
+        for metric_name, metric_value in self.eval_metrics:
+            wandb_metrics[metric_name] = metric_value
+        self.eval_metrics = []
+
+        await super().wandb_log(wandb_metrics)
+
+
+if __name__ == "__main__":
+    TerminalBench2EvalEnv.cli()

environments/web_research_env.py

@@ -1,718 +0,0 @@
-"""
-WebResearchEnv — RL Environment for Multi-Step Web Research
-============================================================
-
-Trains models to do accurate, efficient, multi-source web research.
-
-Reward signals:
-  - Answer correctness  (LLM judge, 0.0–1.0)
-  - Source diversity    (used ≥2 distinct domains)
-  - Efficiency          (penalizes excessive tool calls)
-  - Tool usage          (bonus for actually using web tools)
-
-Dataset: FRAMES benchmark (Google, 2024) — multi-hop factual questions
-  HuggingFace: google/frames-benchmark
-  Fallback:    built-in sample questions (no HF token needed)
-
-Usage:
-    # Phase 1 (OpenAI-compatible server)
-    python environments/web_research_env.py serve \\
-        --openai.base_url http://localhost:8000/v1 \\
-        --openai.model_name YourModel \\
-        --openai.server_type openai
-
-    # Process mode (offline data generation)
-    python environments/web_research_env.py process \\
-        --env.data_path_to_save_groups data/web_research.jsonl
-
-    # Standalone eval
-    python environments/web_research_env.py evaluate \\
-        --openai.base_url http://localhost:8000/v1 \\
-        --openai.model_name YourModel
-
-Built by: github.com/jackx707
-Inspired by: GroceryMind — production Hermes agent doing live web research
-             across German grocery stores (firecrawl + hermes-agent)
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-import os
-import random
-import re
-import sys
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-from urllib.parse import urlparse
-
-from pydantic import Field
-
-# Ensure hermes-agent root is on path
-_repo_root = Path(__file__).resolve().parent.parent
-if str(_repo_root) not in sys.path:
-    sys.path.insert(0, str(_repo_root))
-
-# ---------------------------------------------------------------------------
-# Optional HuggingFace datasets import
-# ---------------------------------------------------------------------------
-try:
-    from datasets import load_dataset
-    HF_AVAILABLE = True
-except ImportError:
-    HF_AVAILABLE = False
-
-from atroposlib.envs.base import ScoredDataGroup
-from atroposlib.envs.server_handling.server_manager import APIServerConfig
-from atroposlib.type_definitions import Item
-
-from environments.hermes_base_env import HermesAgentBaseEnv, HermesAgentEnvConfig
-from environments.agent_loop import AgentResult
-from environments.tool_context import ToolContext
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Fallback sample dataset (used when HuggingFace is unavailable)
-# Multi-hop questions requiring real web search to answer.
-# ---------------------------------------------------------------------------
-SAMPLE_QUESTIONS = [
-    {
-        "question": "What is the current population of the capital city of the country that won the 2022 FIFA World Cup?",
-        "answer": "Buenos Aires has approximately 3 million people in the city proper, or around 15 million in the greater metro area.",
-        "difficulty": "medium",
-        "hops": 2,
-    },
-    {
-        "question": "Who is the CEO of the company that makes the most widely used open-source container orchestration platform?",
-        "answer": "The Linux Foundation oversees Kubernetes. CNCF (Cloud Native Computing Foundation) is the specific body — it does not have a traditional CEO but has an executive director.",
-        "difficulty": "medium",
-        "hops": 2,
-    },
-    {
-        "question": "What programming language was used to write the original version of the web framework used by Instagram?",
-        "answer": "Django, which Instagram was built on, is written in Python.",
-        "difficulty": "easy",
-        "hops": 2,
-    },
-    {
-        "question": "In what year was the university founded where the inventor of the World Wide Web currently holds a professorship?",
-        "answer": "Tim Berners-Lee holds a professorship at MIT (founded 1861) and the University of Southampton (founded 1952).",
-        "difficulty": "hard",
-        "hops": 3,
-    },
-    {
-        "question": "What is the latest stable version of the programming language that ranks #1 on the TIOBE index as of this year?",
-        "answer": "Python is currently #1 on TIOBE. The latest stable version should be verified via the official python.org site.",
-        "difficulty": "medium",
-        "hops": 2,
-    },
-    {
-        "question": "How many employees does the parent company of Instagram have?",
-        "answer": "Meta Platforms (parent of Instagram) employs approximately 70,000+ people as of recent reports.",
-        "difficulty": "medium",
-        "hops": 2,
-    },
-    {
-        "question": "What is the current interest rate set by the central bank of the country where the Eiffel Tower is located?",
-        "answer": "The European Central Bank sets rates for France/eurozone. The current rate should be verified — it has changed frequently in 2023-2025.",
-        "difficulty": "hard",
-        "hops": 2,
-    },
-    {
-        "question": "Which company acquired the startup founded by the creator of Oculus VR?",
-        "answer": "Palmer Luckey founded Oculus VR, which was acquired by Facebook (now Meta). He later founded Anduril Industries.",
-        "difficulty": "medium",
-        "hops": 2,
-    },
-    {
-        "question": "What is the market cap of the company that owns the most popular search engine in Russia?",
-        "answer": "Yandex (now split into separate entities after 2024 restructuring). Current market cap should be verified via financial sources.",
-        "difficulty": "hard",
-        "hops": 2,
-    },
-    {
-        "question": "What was the GDP growth rate of the country that hosted the most recent Summer Olympics?",
-        "answer": "Paris, France hosted the 2024 Summer Olympics. France's recent GDP growth should be verified via World Bank or IMF data.",
-        "difficulty": "hard",
-        "hops": 2,
-    },
-]
-
-
-# ---------------------------------------------------------------------------
-# Configuration
-# ---------------------------------------------------------------------------
-
-class WebResearchEnvConfig(HermesAgentEnvConfig):
-    """Configuration for the web research RL environment."""
-
-    # Reward weights
-    correctness_weight: float = Field(
-        default=0.6,
-        description="Weight for answer correctness in reward (LLM judge score).",
-    )
-    tool_usage_weight: float = Field(
-        default=0.2,
-        description="Weight for tool usage signal (did the model actually use web tools?).",
-    )
-    efficiency_weight: float = Field(
-        default=0.2,
-        description="Weight for efficiency signal (penalizes excessive tool calls).",
-    )
-    diversity_bonus: float = Field(
-        default=0.1,
-        description="Bonus reward for citing ≥2 distinct domains.",
-    )
-
-    # Efficiency thresholds
-    efficient_max_calls: int = Field(
-        default=5,
-        description="Maximum tool calls before efficiency penalty begins.",
-    )
-    heavy_penalty_calls: int = Field(
-        default=10,
-        description="Tool call count where efficiency penalty steepens.",
-    )
-
-    # Eval
-    eval_size: int = Field(
-        default=20,
-        description="Number of held-out items for evaluation.",
-    )
-    eval_split_ratio: float = Field(
-        default=0.1,
-        description="Fraction of dataset to hold out for evaluation (0.0–1.0).",
-    )
-
-    # Dataset
-    dataset_name: str = Field(
-        default="google/frames-benchmark",
-        description="HuggingFace dataset name for research questions.",
-    )
-
-
-# ---------------------------------------------------------------------------
-# Environment
-# ---------------------------------------------------------------------------
-
-class WebResearchEnv(HermesAgentBaseEnv):
-    """
-    RL environment for training multi-step web research skills.
-
-    The model is given a factual question requiring 2-3 hops of web research
-    and must use web_search / web_extract tools to find and synthesize the answer.
-
-    Reward is multi-signal:
-      60% — answer correctness (LLM judge)
-      20% — tool usage (did the model actually search the web?)
-      20% — efficiency (penalizes >5 tool calls)
-
-    Bonus +0.1 for source diversity (≥2 distinct domains cited).
-    """
-
-    name = "web-research"
-    env_config_cls = WebResearchEnvConfig
-
-    # Default toolsets for this environment — web + file for saving notes
-    default_toolsets = ["web", "file"]
-
-    @classmethod
-    def config_init(cls) -> Tuple[WebResearchEnvConfig, List[APIServerConfig]]:
-        """Default configuration for the web research environment."""
-        env_config = WebResearchEnvConfig(
-            enabled_toolsets=["web", "file"],
-            max_agent_turns=15,
-            agent_temperature=1.0,
-            system_prompt=(
-                "You are a highly capable research agent. When asked a factual question, "
-                "always use web_search to find current, accurate information before answering. "
-                "Cite at least 2 sources. Be concise and accurate."
-            ),
-            group_size=4,
-            total_steps=1000,
-            steps_per_eval=100,
-            use_wandb=True,
-            wandb_name="web-research",
-        )
-
-        server_configs = [
-            APIServerConfig(
-                base_url="https://openrouter.ai/api/v1",
-                model_name="anthropic/claude-sonnet-4.5",
-                server_type="openai",
-                api_key=os.getenv("OPENROUTER_API_KEY", ""),
-                health_check=False,
-            )
-        ]
-
-        return env_config, server_configs
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self._items: list[dict] = []
-        self._eval_items: list[dict] = []
-        self._index: int = 0
-
-        # Metrics tracking for wandb
-        self._reward_buffer: list[float] = []
-        self._correctness_buffer: list[float] = []
-        self._tool_usage_buffer: list[float] = []
-        self._efficiency_buffer: list[float] = []
-        self._diversity_buffer: list[float] = []
-
-    # ------------------------------------------------------------------
-    # 1. Setup — load dataset
-    # ------------------------------------------------------------------
-
-    async def setup(self) -> None:
-        """Load the FRAMES benchmark or fall back to built-in samples."""
-        if HF_AVAILABLE:
-            try:
-                logger.info("Loading FRAMES benchmark from HuggingFace...")
-                ds = load_dataset(self.config.dataset_name, split="test")
-                self._items = [
-                    {
-                        "question": row["Prompt"],
-                        "answer": row["Answer"],
-                        "difficulty": row.get("reasoning_types", "unknown"),
-                        "hops": 2,
-                    }
-                    for row in ds
-                ]
-                # Hold out for eval
-                eval_size = max(
-                    self.config.eval_size,
-                    int(len(self._items) * self.config.eval_split_ratio),
-                )
-                random.shuffle(self._items)
-                self._eval_items = self._items[:eval_size]
-                self._items = self._items[eval_size:]
-                logger.info(
-                    f"Loaded {len(self._items)} train / {len(self._eval_items)} eval items "
-                    f"from FRAMES benchmark."
-                )
-                return
-            except Exception as e:
-                logger.warning(f"Could not load FRAMES from HuggingFace: {e}. Using built-in samples.")
-
-        # Fallback
-        random.shuffle(SAMPLE_QUESTIONS)
-        split = max(1, len(SAMPLE_QUESTIONS) * 8 // 10)
-        self._items = SAMPLE_QUESTIONS[:split]
-        self._eval_items = SAMPLE_QUESTIONS[split:]
-        logger.info(
-            f"Using built-in sample dataset: {len(self._items)} train / "
-            f"{len(self._eval_items)} eval items."
-        )
-
-    # ------------------------------------------------------------------
-    # 2. get_next_item — return the next question
-    # ------------------------------------------------------------------
-
-    async def get_next_item(self) -> dict:
-        """Return the next item, cycling through the dataset."""
-        if not self._items:
-            raise RuntimeError("Dataset is empty. Did you call setup()?")
-        item = self._items[self._index % len(self._items)]
-        self._index += 1
-        return item
-
-    # ------------------------------------------------------------------
-    # 3. format_prompt — build the user-facing prompt
-    # ------------------------------------------------------------------
-
-    def format_prompt(self, item: dict) -> str:
-        """Format the research question as a task prompt."""
-        return (
-            f"Research the following question thoroughly using web search. "
-            f"You MUST search the web to find current, accurate information — "
-            f"do not rely solely on your training data.\n\n"
-            f"Question: {item['question']}\n\n"
-            f"Requirements:\n"
-            f"- Use web_search and/or web_extract tools to find information\n"
-            f"- Search at least 2 different sources\n"
-            f"- Provide a concise, accurate answer (2-4 sentences)\n"
-            f"- Cite the sources you used"
-        )
-
-    # ------------------------------------------------------------------
-    # 4. compute_reward — multi-signal scoring
-    # ------------------------------------------------------------------
-
-    async def compute_reward(
-        self,
-        item: dict,
-        result: AgentResult,
-        ctx: ToolContext,
-    ) -> float:
-        """
-        Multi-signal reward function:
-
-          correctness_weight * correctness  — LLM judge comparing answer to ground truth
-          tool_usage_weight  * tool_used    — binary: did the model use web tools?
-          efficiency_weight  * efficiency   — penalizes wasteful tool usage
-          + diversity_bonus                 — source diversity (≥2 distinct domains)
-        """
-        # Extract final response from messages (last assistant message with content)
-        final_response = ""
-        tools_used: list[str] = []
-        for msg in reversed(result.messages):
-            if msg.get("role") == "assistant" and msg.get("content") and not final_response:
-                final_response = msg["content"]
-            # Collect tool names from tool call messages
-            if msg.get("role") == "assistant" and msg.get("tool_calls"):
-                for tc in msg["tool_calls"]:
-                    fn = tc.get("function", {}) if isinstance(tc, dict) else {}
-                    name = fn.get("name", "")
-                    if name:
-                        tools_used.append(name)
-        tool_call_count: int = result.turns_used or len(tools_used)
-
-        cfg = self.config
-
-        # ---- Signal 1: Answer correctness (LLM judge) ----------------
-        correctness = await self._llm_judge(
-            question=item["question"],
-            expected=item["answer"],
-            model_answer=final_response,
-        )
-
-        # ---- Signal 2: Web tool usage --------------------------------
-        web_tools = {"web_search", "web_extract", "search", "firecrawl"}
-        tool_used = 1.0 if any(t in web_tools for t in tools_used) else 0.0
-
-        # ---- Signal 3: Efficiency ------------------------------------
-        if tool_call_count <= cfg.efficient_max_calls:
-            efficiency = 1.0
-        elif tool_call_count <= cfg.heavy_penalty_calls:
-            efficiency = 1.0 - (tool_call_count - cfg.efficient_max_calls) * 0.08
-        else:
-            efficiency = max(0.0, 1.0 - (tool_call_count - cfg.efficient_max_calls) * 0.12)
-
-        # ---- Bonus: Source diversity ---------------------------------
-        domains = self._extract_domains(final_response)
-        diversity = cfg.diversity_bonus if len(domains) >= 2 else 0.0
-
-        # ---- Combine ------------------------------------------------
-        reward = (
-            cfg.correctness_weight * correctness
-            + cfg.tool_usage_weight * tool_used
-            + cfg.efficiency_weight * efficiency
-            + diversity
-        )
-        reward = min(1.0, max(0.0, reward))  # clamp to [0, 1]
-
-        # Track for wandb
-        self._reward_buffer.append(reward)
-        self._correctness_buffer.append(correctness)
-        self._tool_usage_buffer.append(tool_used)
-        self._efficiency_buffer.append(efficiency)
-        self._diversity_buffer.append(diversity)
-
-        logger.debug(
-            f"Reward breakdown — correctness={correctness:.2f}, "
-            f"tool_used={tool_used:.1f}, efficiency={efficiency:.2f}, "
-            f"diversity={diversity:.1f} → total={reward:.3f}"
-        )
-
-        return reward
-
-    # ------------------------------------------------------------------
-    # 5. evaluate — run on held-out eval split
-    # ------------------------------------------------------------------
-
-    async def evaluate(self, *args, **kwargs) -> None:
-        """Run evaluation on the held-out split using the full agent loop with tools.
-
-        Each eval item runs through the same agent loop as training —
-        the model can use web_search, web_extract, etc. to research answers.
-        This measures actual agentic research capability, not just knowledge.
-        """
-        import time
-        import uuid
-        from environments.agent_loop import HermesAgentLoop
-        from environments.tool_context import ToolContext
-
-        items = self._eval_items
-        if not items:
-            logger.warning("No eval items available.")
-            return
-
-        eval_size = min(self.config.eval_size, len(items))
-        eval_items = items[:eval_size]
-
-        logger.info(f"Running eval on {len(eval_items)} questions (with agent loop + tools)...")
-        start_time = time.time()
-        samples = []
-
-        # Resolve tools once for all eval items
-        tools, valid_names = self._resolve_tools_for_group()
-
-        for i, item in enumerate(eval_items):
-            task_id = str(uuid.uuid4())
-            logger.info(f"Eval [{i+1}/{len(eval_items)}]: {item['question'][:80]}...")
-
-            try:
-                # Build messages
-                messages: List[Dict[str, Any]] = []
-                if self.config.system_prompt:
-                    messages.append({"role": "system", "content": self.config.system_prompt})
-                messages.append({"role": "user", "content": self.format_prompt(item)})
-
-                # Run the full agent loop with tools
-                agent = HermesAgentLoop(
-                    server=self.server,
-                    tool_schemas=tools,
-                    valid_tool_names=valid_names,
-                    max_turns=self.config.max_agent_turns,
-                    task_id=task_id,
-                    temperature=0.0,  # Deterministic for eval
-                    max_tokens=self.config.max_token_length,
-                    extra_body=self.config.extra_body,
-                )
-                result = await agent.run(messages)
-
-                # Extract final response and tool usage from messages
-                final_response = ""
-                tool_call_count = 0
-                for msg in reversed(result.messages):
-                    if msg.get("role") == "assistant" and msg.get("content") and not final_response:
-                        final_response = msg["content"]
-                    if msg.get("role") == "assistant" and msg.get("tool_calls"):
-                        tool_call_count += len(msg["tool_calls"])
-
-                # Compute reward (includes LLM judge for correctness)
-                # Temporarily save buffer lengths so we can extract the
-                # correctness score without calling judge twice, and avoid
-                # polluting training metric buffers with eval data.
-                buf_len = len(self._correctness_buffer)
-                ctx = ToolContext(task_id)
-                try:
-                    reward = await self.compute_reward(item, result, ctx)
-                finally:
-                    ctx.cleanup()
-
-                # Extract correctness from the buffer (compute_reward appended it)
-                # then remove eval entries from training buffers
-                correctness = (
-                    self._correctness_buffer[buf_len]
-                    if len(self._correctness_buffer) > buf_len
-                    else 0.0
-                )
-                # Roll back buffers to avoid polluting training metrics
-                for buf in (
-                    self._reward_buffer, self._correctness_buffer,
-                    self._tool_usage_buffer, self._efficiency_buffer,
-                    self._diversity_buffer,
-                ):
-                    if len(buf) > buf_len:
-                        buf.pop()
-
-                samples.append({
-                    "prompt": item["question"],
-                    "response": final_response[:500],
-                    "expected": item["answer"],
-                    "correctness": correctness,
-                    "reward": reward,
-                    "tool_calls": tool_call_count,
-                    "turns": result.turns_used,
-                })
-
-                logger.info(
-                    f"  → correctness={correctness:.2f}, reward={reward:.3f}, "
-                    f"tools={tool_call_count}, turns={result.turns_used}"
-                )
-
-            except Exception as e:
-                logger.error(f"Eval error on item: {e}")
-                samples.append({
-                    "prompt": item["question"],
-                    "response": f"ERROR: {e}",
-                    "expected": item["answer"],
-                    "correctness": 0.0,
-                    "reward": 0.0,
-                    "tool_calls": 0,
-                    "turns": 0,
-                })
-
-        end_time = time.time()
-
-        # Compute aggregate metrics
-        correctness_scores = [s["correctness"] for s in samples]
-        rewards = [s["reward"] for s in samples]
-        tool_counts = [s["tool_calls"] for s in samples]
-        n = len(samples)
-
-        eval_metrics = {
-            "eval/mean_correctness": sum(correctness_scores) / n if n else 0.0,
-            "eval/mean_reward": sum(rewards) / n if n else 0.0,
-            "eval/mean_tool_calls": sum(tool_counts) / n if n else 0.0,
-            "eval/tool_usage_rate": sum(1 for t in tool_counts if t > 0) / n if n else 0.0,
-            "eval/n_items": n,
-        }
-
-        logger.info(
-            f"Eval complete — correctness={eval_metrics['eval/mean_correctness']:.3f}, "
-            f"reward={eval_metrics['eval/mean_reward']:.3f}, "
-            f"tool_usage={eval_metrics['eval/tool_usage_rate']:.0%}"
-        )
-
-        await self.evaluate_log(
-            metrics=eval_metrics,
-            samples=samples,
-            start_time=start_time,
-            end_time=end_time,
-        )
-
-    # ------------------------------------------------------------------
-    # 6. wandb_log — custom metrics
-    # ------------------------------------------------------------------
-
-    async def wandb_log(self, wandb_metrics: Optional[Dict] = None) -> None:
-        """Log reward breakdown metrics to wandb."""
-        if wandb_metrics is None:
-            wandb_metrics = {}
-
-        if self._reward_buffer:
-            n = len(self._reward_buffer)
-            wandb_metrics["train/mean_reward"] = sum(self._reward_buffer) / n
-            wandb_metrics["train/mean_correctness"] = sum(self._correctness_buffer) / n
-            wandb_metrics["train/mean_tool_usage"] = sum(self._tool_usage_buffer) / n
-            wandb_metrics["train/mean_efficiency"] = sum(self._efficiency_buffer) / n
-            wandb_metrics["train/mean_diversity"] = sum(self._diversity_buffer) / n
-            wandb_metrics["train/total_rollouts"] = n
-
-            # Accuracy buckets
-            wandb_metrics["train/correct_rate"] = (
-                sum(1 for c in self._correctness_buffer if c >= 0.7) / n
-            )
-            wandb_metrics["train/tool_usage_rate"] = (
-                sum(1 for t in self._tool_usage_buffer if t > 0) / n
-            )
-
-            # Clear buffers
-            self._reward_buffer.clear()
-            self._correctness_buffer.clear()
-            self._tool_usage_buffer.clear()
-            self._efficiency_buffer.clear()
-            self._diversity_buffer.clear()
-
-        await super().wandb_log(wandb_metrics)
-
-    # ------------------------------------------------------------------
-    # Private helpers
-    # ------------------------------------------------------------------
-
-    async def _llm_judge(
-        self,
-        question: str,
-        expected: str,
-        model_answer: str,
-    ) -> float:
-        """
-        Use the server's LLM to judge answer correctness.
-        Falls back to keyword heuristic if LLM call fails.
-        """
-        if not model_answer or not model_answer.strip():
-            return 0.0
-
-        judge_prompt = (
-            "You are an impartial judge evaluating the quality of an AI research answer.\n\n"
-            f"Question: {question}\n\n"
-            f"Reference answer: {expected}\n\n"
-            f"Model answer: {model_answer}\n\n"
-            "Score the model answer on a scale from 0.0 to 1.0 where:\n"
-            "  1.0 = fully correct and complete\n"
-            "  0.7 = mostly correct with minor gaps\n"
-            "  0.4 = partially correct\n"
-            "  0.1 = mentions relevant topic but wrong or very incomplete\n"
-            "  0.0 = completely wrong or no answer\n\n"
-            "Consider: factual accuracy, completeness, and relevance.\n"
-            'Respond with ONLY a JSON object: {"score": <float>, "reason": "<one sentence>"}'
-        )
-
-        try:
-            response = await self.server.chat_completion(
-                messages=[{"role": "user", "content": judge_prompt}],
-                n=1,
-                max_tokens=150,
-                temperature=0.0,
-                split="eval",
-            )
-            text = response.choices[0].message.content if response.choices else ""
-            parsed = self._parse_judge_json(text)
-            if parsed is not None:
-                return float(parsed)
-        except Exception as e:
-            logger.debug(f"LLM judge failed: {e}. Using heuristic.")
-
-        return self._heuristic_score(expected, model_answer)
-
-    @staticmethod
-    def _parse_judge_json(text: str) -> Optional[float]:
-        """Extract the score float from LLM judge JSON response."""
-        try:
-            clean = re.sub(r"```(?:json)?|```", "", text).strip()
-            data = json.loads(clean)
-            score = float(data.get("score", -1))
-            if 0.0 <= score <= 1.0:
-                return score
-        except Exception:
-            match = re.search(r'"score"\s*:\s*([0-9.]+)', text)
-            if match:
-                score = float(match.group(1))
-                if 0.0 <= score <= 1.0:
-                    return score
-        return None
-
-    @staticmethod
-    def _heuristic_score(expected: str, model_answer: str) -> float:
-        """Lightweight keyword overlap score as fallback."""
-        stopwords = {
-            "the", "a", "an", "is", "are", "was", "were", "of", "in", "on",
-            "at", "to", "for", "with", "and", "or", "but", "it", "its",
-            "this", "that", "as", "by", "from", "be", "has", "have", "had",
-        }
-
-        def tokenize(text: str) -> set:
-            tokens = re.findall(r'\b\w+\b', text.lower())
-            return {t for t in tokens if t not in stopwords and len(t) > 2}
-
-        expected_tokens = tokenize(expected)
-        answer_tokens = tokenize(model_answer)
-
-        if not expected_tokens:
-            return 0.5
-
-        overlap = len(expected_tokens & answer_tokens)
-        union = len(expected_tokens | answer_tokens)
-
-        jaccard = overlap / union if union > 0 else 0.0
-        recall = overlap / len(expected_tokens)
-        return min(1.0, 0.4 * jaccard + 0.6 * recall)
-
-    @staticmethod
-    def _extract_domains(text: str) -> set:
-        """Extract unique domains from URLs cited in the response."""
-        urls = re.findall(r'https?://[^\s\)>\]"\']+', text)
-        domains = set()
-        for url in urls:
-            try:
-                parsed = urlparse(url)
-                domain = parsed.netloc.lower().lstrip("www.")
-                if domain:
-                    domains.add(domain)
-            except Exception:
-                pass
-        return domains
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-if __name__ == "__main__":
-    WebResearchEnv.cli()

gateway/channel_directory.py

@@ -17,26 +17,6 @@ logger = logging.getLogger(__name__)
 DIRECTORY_PATH = Path.home() / ".hermes" / "channel_directory.json"
 
 
-def _session_entry_id(origin: Dict[str, Any]) -> Optional[str]:
-    chat_id = origin.get("chat_id")
-    if not chat_id:
-        return None
-    thread_id = origin.get("thread_id")
-    if thread_id:
-        return f"{chat_id}:{thread_id}"
-    return str(chat_id)
-
-
-def _session_entry_name(origin: Dict[str, Any]) -> str:
-    base_name = origin.get("chat_name") or origin.get("user_name") or str(origin.get("chat_id"))
-    thread_id = origin.get("thread_id")
-    if not thread_id:
-        return base_name
-
-    topic_label = origin.get("chat_topic") or f"topic {thread_id}"
-    return f"{base_name} / {topic_label}"
-
-
 # ---------------------------------------------------------------------------
 # Build / refresh
 # ---------------------------------------------------------------------------
@@ -60,8 +40,8 @@ def build_channel_directory(adapters: Dict[Any, Any]) -> Dict[str, Any]:
         except Exception as e:
             logger.warning("Channel directory: failed to build %s: %s", platform.value, e)
 
-    # Telegram, WhatsApp & Signal can't enumerate chats -- pull from session history
-    for plat_name in ("telegram", "whatsapp", "signal", "email"):
+    # Telegram & WhatsApp can't enumerate chats -- pull from session history
+    for plat_name in ("telegram", "whatsapp"):
         if plat_name not in platforms:
             platforms[plat_name] = _build_from_sessions(plat_name)
 
@@ -72,7 +52,7 @@ def build_channel_directory(adapters: Dict[Any, Any]) -> Dict[str, Any]:
 
     try:
         DIRECTORY_PATH.parent.mkdir(parents=True, exist_ok=True)
-        with open(DIRECTORY_PATH, "w", encoding="utf-8") as f:
+        with open(DIRECTORY_PATH, "w") as f:
             json.dump(directory, f, indent=2, ensure_ascii=False)
     except Exception as e:
         logger.warning("Channel directory: failed to write: %s", e)
@@ -135,7 +115,7 @@ def _build_from_sessions(platform_name: str) -> List[Dict[str, str]]:
 
     entries = []
     try:
-        with open(sessions_path, encoding="utf-8") as f:
+        with open(sessions_path) as f:
             data = json.load(f)
 
         seen_ids = set()
@@ -143,15 +123,14 @@ def _build_from_sessions(platform_name: str) -> List[Dict[str, str]]:
             origin = session.get("origin") or {}
             if origin.get("platform") != platform_name:
                 continue
-            entry_id = _session_entry_id(origin)
-            if not entry_id or entry_id in seen_ids:
+            chat_id = origin.get("chat_id")
+            if not chat_id or chat_id in seen_ids:
                 continue
-            seen_ids.add(entry_id)
+            seen_ids.add(chat_id)
             entries.append({
-                "id": entry_id,
-                "name": _session_entry_name(origin),
+                "id": str(chat_id),
+                "name": origin.get("chat_name") or origin.get("user_name") or str(chat_id),
                 "type": session.get("chat_type", "dm"),
-                "thread_id": origin.get("thread_id"),
             })
     except Exception as e:
         logger.debug("Channel directory: failed to read sessions for %s: %s", platform_name, e)
@@ -168,7 +147,7 @@ def load_directory() -> Dict[str, Any]:
     if not DIRECTORY_PATH.exists():
         return {"updated_at": None, "platforms": {}}
     try:
-        with open(DIRECTORY_PATH, encoding="utf-8") as f:
+        with open(DIRECTORY_PATH) as f:
             return json.load(f)
     except Exception:
         return {"updated_at": None, "platforms": {}}

gateway/config.py

@@ -26,9 +26,7 @@ class Platform(Enum):
     DISCORD = "discord"
     WHATSAPP = "whatsapp"
     SLACK = "slack"
-    SIGNAL = "signal"
     HOMEASSISTANT = "homeassistant"
-    EMAIL = "email"
 
 
 @dataclass
@@ -157,19 +155,7 @@ class GatewayConfig:
         """Return list of platforms that are enabled and configured."""
         connected = []
         for platform, config in self.platforms.items():
-            if not config.enabled:
-                continue
-            # Platforms that use token/api_key auth
-            if config.token or config.api_key:
-                connected.append(platform)
-            # WhatsApp uses enabled flag only (bridge handles auth)
-            elif platform == Platform.WHATSAPP:
-                connected.append(platform)
-            # Signal uses extra dict for config (http_url + account)
-            elif platform == Platform.SIGNAL and config.extra.get("http_url"):
-                connected.append(platform)
-            # Email uses extra dict for config (address + imap_host + smtp_host)
-            elif platform == Platform.EMAIL and config.extra.get("address"):
+            if config.enabled and (config.token or config.api_key):
                 connected.append(platform)
         return connected
     
@@ -274,7 +260,7 @@ def load_gateway_config() -> GatewayConfig:
     gateway_config_path = Path.home() / ".hermes" / "gateway.json"
     if gateway_config_path.exists():
         try:
-            with open(gateway_config_path, "r", encoding="utf-8") as f:
+            with open(gateway_config_path, "r") as f:
                 data = json.load(f)
                 config = GatewayConfig.from_dict(data)
         except Exception as e:
@@ -287,23 +273,11 @@ def load_gateway_config() -> GatewayConfig:
         import yaml
         config_yaml_path = Path.home() / ".hermes" / "config.yaml"
         if config_yaml_path.exists():
-            with open(config_yaml_path, encoding="utf-8") as f:
+            with open(config_yaml_path) as f:
                 yaml_cfg = yaml.safe_load(f) or {}
             sr = yaml_cfg.get("session_reset")
             if sr and isinstance(sr, dict):
                 config.default_reset_policy = SessionResetPolicy.from_dict(sr)
-
-            # Bridge discord settings from config.yaml to env vars
-            # (env vars take precedence — only set if not already defined)
-            discord_cfg = yaml_cfg.get("discord", {})
-            if isinstance(discord_cfg, dict):
-                if "require_mention" in discord_cfg and not os.getenv("DISCORD_REQUIRE_MENTION"):
-                    os.environ["DISCORD_REQUIRE_MENTION"] = str(discord_cfg["require_mention"]).lower()
-                frc = discord_cfg.get("free_response_channels")
-                if frc is not None and not os.getenv("DISCORD_FREE_RESPONSE_CHANNELS"):
-                    if isinstance(frc, list):
-                        frc = ",".join(str(v) for v in frc)
-                    os.environ["DISCORD_FREE_RESPONSE_CHANNELS"] = str(frc)
     except Exception:
         pass
 
@@ -405,26 +379,6 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
             )
     
-    # Signal
-    signal_url = os.getenv("SIGNAL_HTTP_URL")
-    signal_account = os.getenv("SIGNAL_ACCOUNT")
-    if signal_url and signal_account:
-        if Platform.SIGNAL not in config.platforms:
-            config.platforms[Platform.SIGNAL] = PlatformConfig()
-        config.platforms[Platform.SIGNAL].enabled = True
-        config.platforms[Platform.SIGNAL].extra.update({
-            "http_url": signal_url,
-            "account": signal_account,
-            "ignore_stories": os.getenv("SIGNAL_IGNORE_STORIES", "true").lower() in ("true", "1", "yes"),
-        })
-        signal_home = os.getenv("SIGNAL_HOME_CHANNEL")
-        if signal_home:
-            config.platforms[Platform.SIGNAL].home_channel = HomeChannel(
-                platform=Platform.SIGNAL,
-                chat_id=signal_home,
-                name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
-            )
-
     # Home Assistant
     hass_token = os.getenv("HASS_TOKEN")
     if hass_token:
@@ -436,28 +390,6 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
         if hass_url:
             config.platforms[Platform.HOMEASSISTANT].extra["url"] = hass_url
 
-    # Email
-    email_addr = os.getenv("EMAIL_ADDRESS")
-    email_pwd = os.getenv("EMAIL_PASSWORD")
-    email_imap = os.getenv("EMAIL_IMAP_HOST")
-    email_smtp = os.getenv("EMAIL_SMTP_HOST")
-    if all([email_addr, email_pwd, email_imap, email_smtp]):
-        if Platform.EMAIL not in config.platforms:
-            config.platforms[Platform.EMAIL] = PlatformConfig()
-        config.platforms[Platform.EMAIL].enabled = True
-        config.platforms[Platform.EMAIL].extra.update({
-            "address": email_addr,
-            "imap_host": email_imap,
-            "smtp_host": email_smtp,
-        })
-        email_home = os.getenv("EMAIL_HOME_ADDRESS")
-        if email_home:
-            config.platforms[Platform.EMAIL].home_channel = HomeChannel(
-                platform=Platform.EMAIL,
-                chat_id=email_home,
-                name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
-            )
-
     # Session settings
     idle_minutes = os.getenv("SESSION_IDLE_MINUTES")
     if idle_minutes:
@@ -479,5 +411,5 @@ def save_gateway_config(config: GatewayConfig) -> None:
     gateway_config_path = Path.home() / ".hermes" / "gateway.json"
     gateway_config_path.parent.mkdir(parents=True, exist_ok=True)
     
-    with open(gateway_config_path, "w", encoding="utf-8") as f:
+    with open(gateway_config_path, "w") as f:
         json.dump(config.to_dict(), f, indent=2)

gateway/delivery.py

@@ -37,7 +37,6 @@ class DeliveryTarget:
     """
     platform: Platform
     chat_id: Optional[str] = None  # None means use home channel
-    thread_id: Optional[str] = None
     is_origin: bool = False
     is_explicit: bool = False  # True if chat_id was explicitly specified
     
@@ -59,7 +58,6 @@ class DeliveryTarget:
                 return cls(
                     platform=origin.platform,
                     chat_id=origin.chat_id,
-                    thread_id=origin.thread_id,
                     is_origin=True,
                 )
             else:
@@ -152,7 +150,7 @@ class DeliveryRouter:
                     continue
             
             # Deduplicate
-            key = (target.platform, target.chat_id, target.thread_id)
+            key = (target.platform, target.chat_id)
             if key not in seen_platforms:
                 seen_platforms.add(key)
                 targets.append(target)
@@ -287,10 +285,7 @@ class DeliveryRouter:
                 + f"\n\n... [truncated, full output saved to {saved_path}]"
             )
         
-        send_metadata = dict(metadata or {})
-        if target.thread_id and "thread_id" not in send_metadata:
-            send_metadata["thread_id"] = target.thread_id
-        return await adapter.send(target.chat_id, content, metadata=send_metadata or None)
+        return await adapter.send(target.chat_id, content, metadata=metadata)
 
 
 def parse_deliver_spec(

gateway/mirror.py

@@ -26,7 +26,6 @@ def mirror_to_session(
     chat_id: str,
     message_text: str,
     source_label: str = "cli",
-    thread_id: Optional[str] = None,
 ) -> bool:
     """
     Append a delivery-mirror message to the target session's transcript.
@@ -38,9 +37,9 @@ def mirror_to_session(
     All errors are caught -- this is never fatal.
     """
     try:
-        session_id = _find_session_id(platform, str(chat_id), thread_id=thread_id)
+        session_id = _find_session_id(platform, str(chat_id))
         if not session_id:
-            logger.debug("Mirror: no session found for %s:%s:%s", platform, chat_id, thread_id)
+            logger.debug("Mirror: no session found for %s:%s", platform, chat_id)
             return False
 
         mirror_msg = {
@@ -58,11 +57,11 @@ def mirror_to_session(
         return True
 
     except Exception as e:
-        logger.debug("Mirror failed for %s:%s:%s: %s", platform, chat_id, thread_id, e)
+        logger.debug("Mirror failed for %s:%s: %s", platform, chat_id, e)
         return False
 
 
-def _find_session_id(platform: str, chat_id: str, thread_id: Optional[str] = None) -> Optional[str]:
+def _find_session_id(platform: str, chat_id: str) -> Optional[str]:
     """
     Find the active session_id for a platform + chat_id pair.
 
@@ -74,7 +73,7 @@ def _find_session_id(platform: str, chat_id: str, thread_id: Optional[str] = Non
         return None
 
     try:
-        with open(_SESSIONS_INDEX, encoding="utf-8") as f:
+        with open(_SESSIONS_INDEX) as f:
             data = json.load(f)
     except Exception:
         return None
@@ -92,9 +91,6 @@ def _find_session_id(platform: str, chat_id: str, thread_id: Optional[str] = Non
 
         origin_chat_id = str(origin.get("chat_id", ""))
         if origin_chat_id == str(chat_id):
-            origin_thread_id = origin.get("thread_id")
-            if thread_id is not None and str(origin_thread_id or "") != str(thread_id):
-                continue
             updated = entry.get("updated_at", "")
             if updated > best_updated:
                 best_updated = updated
@@ -107,7 +103,7 @@ def _append_to_jsonl(session_id: str, message: dict) -> None:
     """Append a message to the JSONL transcript file."""
     transcript_path = _SESSIONS_DIR / f"{session_id}.jsonl"
     try:
-        with open(transcript_path, "a", encoding="utf-8") as f:
+        with open(transcript_path, "a") as f:
             f.write(json.dumps(message, ensure_ascii=False) + "\n")
     except Exception as e:
         logger.debug("Mirror JSONL write failed: %s", e)
@@ -115,7 +111,6 @@ def _append_to_jsonl(session_id: str, message: dict) -> None:
 
 def _append_to_sqlite(session_id: str, message: dict) -> None:
     """Append a message to the SQLite session database."""
-    db = None
     try:
         from hermes_state import SessionDB
         db = SessionDB()
@@ -126,6 +121,3 @@ def _append_to_sqlite(session_id: str, message: dict) -> None:
         )
     except Exception as e:
         logger.debug("Mirror SQLite write failed: %s", e)
-    finally:
-        if db is not None:
-            db.close()

gateway/platforms/ADDING_A_PLATFORM.md

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

gateway/platforms/base.py

@@ -24,7 +24,7 @@ from pathlib import Path as _Path
 sys.path.insert(0, str(_Path(__file__).resolve().parents[2]))
 
 from gateway.config import Platform, PlatformConfig
-from gateway.session import SessionSource, build_session_key
+from gateway.session import SessionSource
 
 
 # ---------------------------------------------------------------------------
@@ -252,7 +252,6 @@ def cleanup_document_cache(max_age_hours: int = 24) -> int:
 class MessageType(Enum):
     """Types of incoming messages."""
     TEXT = "text"
-    LOCATION = "location"
     PHOTO = "photo"
     VIDEO = "video"
     AUDIO = "audio"
@@ -413,12 +412,11 @@ class BasePlatformAdapter(ABC):
         """
         return SendResult(success=False, error="Not supported")
 
-    async def send_typing(self, chat_id: str, metadata=None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """
         Send a typing indicator.
         
         Override in subclasses if the platform supports it.
-        metadata: optional dict with platform-specific context (e.g. thread_id for Slack).
         """
         pass
     
@@ -516,7 +514,6 @@ class BasePlatformAdapter(ABC):
         audio_path: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        **kwargs,
     ) -> SendResult:
         """
         Send an audio file as a native voice message via the platform API.
@@ -536,7 +533,6 @@ class BasePlatformAdapter(ABC):
         video_path: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        **kwargs,
     ) -> SendResult:
         """
         Send a video natively via the platform API.
@@ -556,7 +552,6 @@ class BasePlatformAdapter(ABC):
         caption: Optional[str] = None,
         file_name: Optional[str] = None,
         reply_to: Optional[str] = None,
-        **kwargs,
     ) -> SendResult:
         """
         Send a document/file natively via the platform API.
@@ -575,7 +570,6 @@ class BasePlatformAdapter(ABC):
         image_path: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        **kwargs,
     ) -> SendResult:
         """
         Send a local image file natively via the platform API.
@@ -625,7 +619,7 @@ class BasePlatformAdapter(ABC):
         
         return media, cleaned
     
-    async def _keep_typing(self, chat_id: str, interval: float = 2.0, metadata=None) -> None:
+    async def _keep_typing(self, chat_id: str, interval: float = 2.0) -> None:
         """
         Continuously send typing indicator until cancelled.
         
@@ -634,7 +628,7 @@ class BasePlatformAdapter(ABC):
         """
         try:
             while True:
-                await self.send_typing(chat_id, metadata=metadata)
+                await self.send_typing(chat_id)
                 await asyncio.sleep(interval)
         except asyncio.CancelledError:
             pass  # Normal cancellation when handler completes
@@ -650,7 +644,7 @@ class BasePlatformAdapter(ABC):
         if not self._message_handler:
             return
         
-        session_key = build_session_key(event.source)
+        session_key = event.source.chat_id
         
         # Check if there's already an active handler for this session
         if session_key in self._active_sessions:
@@ -692,8 +686,7 @@ class BasePlatformAdapter(ABC):
         self._active_sessions[session_key] = interrupt_event
         
         # Start continuous typing indicator (refreshes every 2 seconds)
-        _thread_metadata = {"thread_id": event.source.thread_id} if event.source.thread_id else None
-        typing_task = asyncio.create_task(self._keep_typing(event.source.chat_id, metadata=_thread_metadata))
+        typing_task = asyncio.create_task(self._keep_typing(event.source.chat_id))
         
         try:
             # Call the handler (this can take a while with tool calls)
@@ -717,8 +710,7 @@ class BasePlatformAdapter(ABC):
                     result = await self.send(
                         chat_id=event.source.chat_id,
                         content=text_content,
-                        reply_to=event.message_id,
-                        metadata=_thread_metadata,
+                        reply_to=event.message_id
                     )
                     
                     # Log send failures (don't raise - user already saw tool progress)
@@ -728,8 +720,7 @@ class BasePlatformAdapter(ABC):
                         fallback_result = await self.send(
                             chat_id=event.source.chat_id,
                             content=f"(Response formatting failed, plain text:)\n\n{text_content[:3500]}",
-                            reply_to=event.message_id,
-                            metadata=_thread_metadata,
+                            reply_to=event.message_id
                         )
                         if not fallback_result.success:
                             print(f"[{self.name}] Fallback send also failed: {fallback_result.error}")
@@ -751,14 +742,12 @@ class BasePlatformAdapter(ABC):
                                 chat_id=event.source.chat_id,
                                 animation_url=image_url,
                                 caption=alt_text if alt_text else None,
-                                metadata=_thread_metadata,
                             )
                         else:
                             img_result = await self.send_image(
                                 chat_id=event.source.chat_id,
                                 image_url=image_url,
                                 caption=alt_text if alt_text else None,
-                                metadata=_thread_metadata,
                             )
                         if not img_result.success:
                             logger.error("[%s] Failed to send image: %s", self.name, img_result.error)
@@ -779,25 +768,21 @@ class BasePlatformAdapter(ABC):
                             media_result = await self.send_voice(
                                 chat_id=event.source.chat_id,
                                 audio_path=media_path,
-                                metadata=_thread_metadata,
                             )
                         elif ext in _VIDEO_EXTS:
                             media_result = await self.send_video(
                                 chat_id=event.source.chat_id,
                                 video_path=media_path,
-                                metadata=_thread_metadata,
                             )
                         elif ext in _IMAGE_EXTS:
                             media_result = await self.send_image_file(
                                 chat_id=event.source.chat_id,
                                 image_path=media_path,
-                                metadata=_thread_metadata,
                             )
                         else:
                             media_result = await self.send_document(
                                 chat_id=event.source.chat_id,
                                 file_path=media_path,
-                                metadata=_thread_metadata,
                             )
 
                         if not media_result.success:
@@ -853,8 +838,6 @@ class BasePlatformAdapter(ABC):
         user_name: Optional[str] = None,
         thread_id: Optional[str] = None,
         chat_topic: Optional[str] = None,
-        user_id_alt: Optional[str] = None,
-        chat_id_alt: Optional[str] = None,
     ) -> SessionSource:
         """Helper to build a SessionSource for this platform."""
         # Normalize empty topic to None
@@ -869,8 +852,6 @@ class BasePlatformAdapter(ABC):
             user_name=user_name,
             thread_id=str(thread_id) if thread_id else None,
             chat_topic=chat_topic.strip() if chat_topic else None,
-            user_id_alt=user_id_alt,
-            chat_id_alt=chat_id_alt,
         )
     
     @abstractmethod

gateway/platforms/discord.py

@@ -72,11 +72,11 @@ class DiscordAdapter(BasePlatformAdapter):
     async def connect(self) -> bool:
         """Connect to Discord and start receiving events."""
         if not DISCORD_AVAILABLE:
-            logger.error("[%s] discord.py not installed. Run: pip install discord.py", self.name)
+            print(f"[{self.name}] discord.py not installed. Run: pip install discord.py")
             return False
         
         if not self.config.token:
-            logger.error("[%s] No bot token configured", self.name)
+            print(f"[{self.name}] No bot token configured")
             return False
         
         try:
@@ -105,7 +105,7 @@ class DiscordAdapter(BasePlatformAdapter):
             # Register event handlers
             @self._client.event
             async def on_ready():
-                logger.info("[%s] Connected as %s", adapter_self.name, adapter_self._client.user)
+                print(f"[{adapter_self.name}] Connected as {adapter_self._client.user}")
                 
                 # Resolve any usernames in the allowed list to numeric IDs
                 await adapter_self._resolve_allowed_usernames()
@@ -113,30 +113,16 @@ class DiscordAdapter(BasePlatformAdapter):
                 # Sync slash commands with Discord
                 try:
                     synced = await adapter_self._client.tree.sync()
-                    logger.info("[%s] Synced %d slash command(s)", adapter_self.name, len(synced))
-                except Exception as e:  # pragma: no cover - defensive logging
-                    logger.warning("[%s] Slash command sync failed: %s", adapter_self.name, e, exc_info=True)
+                    print(f"[{adapter_self.name}] Synced {len(synced)} slash command(s)")
+                except Exception as e:
+                    print(f"[{adapter_self.name}] Slash command sync failed: {e}")
                 adapter_self._ready_event.set()
             
             @self._client.event
             async def on_message(message: DiscordMessage):
-                # Always ignore our own messages
+                # Ignore bot's own messages
                 if message.author == self._client.user:
                     return
-                
-                # Bot message filtering (DISCORD_ALLOW_BOTS):
-                #   "none"     — ignore all other bots (default)
-                #   "mentions" — accept bot messages only when they @mention us
-                #   "all"      — accept all bot messages
-                if getattr(message.author, "bot", False):
-                    allow_bots = os.getenv("DISCORD_ALLOW_BOTS", "none").lower().strip()
-                    if allow_bots == "none":
-                        return
-                    elif allow_bots == "mentions":
-                        if not self._client.user or self._client.user not in message.mentions:
-                            return
-                    # "all" falls through to handle_message
-                
                 await self._handle_message(message)
             
             # Register slash commands
@@ -152,10 +138,10 @@ class DiscordAdapter(BasePlatformAdapter):
             return True
             
         except asyncio.TimeoutError:
-            logger.error("[%s] Timeout waiting for connection to Discord", self.name, exc_info=True)
+            print(f"[{self.name}] Timeout waiting for connection")
             return False
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to connect to Discord: %s", self.name, e, exc_info=True)
+        except Exception as e:
+            print(f"[{self.name}] Failed to connect: {e}")
             return False
     
     async def disconnect(self) -> None:
@@ -163,13 +149,13 @@ class DiscordAdapter(BasePlatformAdapter):
         if self._client:
             try:
                 await self._client.close()
-            except Exception as e:  # pragma: no cover - defensive logging
-                logger.warning("[%s] Error during disconnect: %s", self.name, e, exc_info=True)
+            except Exception as e:
+                print(f"[{self.name}] Error during disconnect: {e}")
         
         self._running = False
         self._client = None
         self._ready_event.clear()
-        logger.info("[%s] Disconnected", self.name)
+        print(f"[{self.name}] Disconnected")
     
     async def send(
         self,
@@ -218,8 +204,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 raw_response={"message_ids": message_ids}
             )
             
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to send Discord message: %s", self.name, e, exc_info=True)
+        except Exception as e:
             return SendResult(success=False, error=str(e))
 
     async def edit_message(
@@ -241,8 +226,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 formatted = formatted[:self.MAX_MESSAGE_LENGTH - 3] + "..."
             await msg.edit(content=formatted)
             return SendResult(success=True, message_id=message_id)
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to edit Discord message %s: %s", self.name, message_id, e, exc_info=True)
+        except Exception as e:
             return SendResult(success=False, error=str(e))
 
     async def send_voice(
@@ -279,8 +263,8 @@ class DiscordAdapter(BasePlatformAdapter):
                 )
                 return SendResult(success=True, message_id=str(msg.id))
         
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to send audio, falling back to base adapter: %s", self.name, e, exc_info=True)
+        except Exception as e:
+            print(f"[{self.name}] Failed to send audio: {e}")
             return await super().send_voice(chat_id, audio_path, caption, reply_to)
     
     async def send_image_file(
@@ -316,8 +300,8 @@ class DiscordAdapter(BasePlatformAdapter):
                 )
                 return SendResult(success=True, message_id=str(msg.id))
         
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to send local image, falling back to base adapter: %s", self.name, e, exc_info=True)
+        except Exception as e:
+            print(f"[{self.name}] Failed to send local image: {e}")
             return await super().send_image_file(chat_id, image_path, caption, reply_to)
 
     async def send_image(
@@ -369,22 +353,13 @@ class DiscordAdapter(BasePlatformAdapter):
                     return SendResult(success=True, message_id=str(msg.id))
         
         except ImportError:
-            logger.warning(
-                "[%s] aiohttp not installed, falling back to URL. Run: pip install aiohttp",
-                self.name,
-                exc_info=True,
-            )
+            print(f"[{self.name}] aiohttp not installed, falling back to URL. Run: pip install aiohttp")
             return await super().send_image(chat_id, image_url, caption, reply_to)
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[%s] Failed to send image attachment, falling back to URL: %s",
-                self.name,
-                e,
-                exc_info=True,
-            )
+        except Exception as e:
+            print(f"[{self.name}] Failed to send image attachment, falling back to URL: {e}")
             return await super().send_image(chat_id, image_url, caption, reply_to)
     
-    async def send_typing(self, chat_id: str, metadata=None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """Send typing indicator."""
         if self._client:
             try:
@@ -429,8 +404,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 "guild_id": str(channel.guild.id) if hasattr(channel, "guild") and channel.guild else None,
                 "guild_name": channel.guild.name if hasattr(channel, "guild") and channel.guild else None,
             }
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[%s] Failed to get chat info for %s: %s", self.name, chat_id, e, exc_info=True)
+        except Exception as e:
             return {"name": str(chat_id), "type": "dm", "error": str(e)}
     
     async def _resolve_allowed_usernames(self) -> None:
@@ -618,89 +592,6 @@ class DiscordAdapter(BasePlatformAdapter):
             except Exception as e:
                 logger.debug("Discord followup failed: %s", e)
 
-        @tree.command(name="compress", description="Compress conversation context")
-        async def slash_compress(interaction: discord.Interaction):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, "/compress")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="title", description="Set or show the session title")
-        @discord.app_commands.describe(name="Session title. Leave empty to show current.")
-        async def slash_title(interaction: discord.Interaction, name: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/title {name}".strip())
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="resume", description="Resume a previously-named session")
-        @discord.app_commands.describe(name="Session name to resume. Leave empty to list sessions.")
-        async def slash_resume(interaction: discord.Interaction, name: str = ""):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/resume {name}".strip())
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="usage", description="Show token usage for this session")
-        async def slash_usage(interaction: discord.Interaction):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, "/usage")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="provider", description="Show available providers")
-        async def slash_provider(interaction: discord.Interaction):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, "/provider")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="help", description="Show available commands")
-        async def slash_help(interaction: discord.Interaction):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, "/help")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="insights", description="Show usage insights and analytics")
-        @discord.app_commands.describe(days="Number of days to analyze (default: 7)")
-        async def slash_insights(interaction: discord.Interaction, days: int = 7):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, f"/insights {days}")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
-        @tree.command(name="reload-mcp", description="Reload MCP servers from config")
-        async def slash_reload_mcp(interaction: discord.Interaction):
-            await interaction.response.defer(ephemeral=True)
-            event = self._build_slash_event(interaction, "/reload-mcp")
-            await self.handle_message(event)
-            try:
-                await interaction.followup.send("Done~", ephemeral=True)
-            except Exception as e:
-                logger.debug("Discord followup failed: %s", e)
-
         @tree.command(name="update", description="Update Hermes Agent to the latest version")
         async def slash_update(interaction: discord.Interaction):
             await interaction.response.defer(ephemeral=True)
@@ -775,46 +666,6 @@ class DiscordAdapter(BasePlatformAdapter):
         except Exception as e:
             return SendResult(success=False, error=str(e))
 
-    def _get_parent_channel_id(self, channel: Any) -> Optional[str]:
-        """Return the parent channel ID for a Discord thread-like channel, if present."""
-        parent = getattr(channel, "parent", None)
-        if parent is not None and getattr(parent, "id", None) is not None:
-            return str(parent.id)
-        parent_id = getattr(channel, "parent_id", None)
-        if parent_id is not None:
-            return str(parent_id)
-        return None
-
-    def _is_forum_parent(self, channel: Any) -> bool:
-        """Best-effort check for whether a Discord channel is a forum channel."""
-        if channel is None:
-            return False
-        forum_cls = getattr(discord, "ForumChannel", None)
-        if forum_cls and isinstance(channel, forum_cls):
-            return True
-        channel_type = getattr(channel, "type", None)
-        if channel_type is not None:
-            type_value = getattr(channel_type, "value", channel_type)
-            if type_value == 15:
-                return True
-        return False
-
-    def _format_thread_chat_name(self, thread: Any) -> str:
-        """Build a readable chat name for thread-like Discord channels, including forum context when available."""
-        thread_name = getattr(thread, "name", None) or str(getattr(thread, "id", "thread"))
-        parent = getattr(thread, "parent", None)
-        guild = getattr(thread, "guild", None) or getattr(parent, "guild", None)
-        guild_name = getattr(guild, "name", None)
-        parent_name = getattr(parent, "name", None)
-
-        if self._is_forum_parent(parent) and guild_name and parent_name:
-            return f"{guild_name} / {parent_name} / {thread_name}"
-        if parent_name and guild_name:
-            return f"{guild_name} / #{parent_name} / {thread_name}"
-        if parent_name:
-            return f"{parent_name} / {thread_name}"
-        return thread_name
-
     async def _handle_message(self, message: DiscordMessage) -> None:
         """Handle incoming Discord messages."""
         # In server channels (not DMs), require the bot to be @mentioned
@@ -825,33 +676,28 @@ class DiscordAdapter(BasePlatformAdapter):
         #       bot responds to every message without needing a mention.
         #   DISCORD_REQUIRE_MENTION: Set to "false" to disable mention requirement
         #       globally (all channels become free-response). Default: "true".
-        #       Can also be set via discord.require_mention in config.yaml.
-
-        thread_id = None
-        parent_channel_id = None
-        is_thread = isinstance(message.channel, discord.Thread)
-        if is_thread:
-            thread_id = str(message.channel.id)
-            parent_channel_id = self._get_parent_channel_id(message.channel)
-
+        
         if not isinstance(message.channel, discord.DMChannel):
+            # Check if this channel is in the free-response list
             free_channels_raw = os.getenv("DISCORD_FREE_RESPONSE_CHANNELS", "")
             free_channels = {ch.strip() for ch in free_channels_raw.split(",") if ch.strip()}
-            channel_ids = {str(message.channel.id)}
-            if parent_channel_id:
-                channel_ids.add(parent_channel_id)
-
+            channel_id = str(message.channel.id)
+            
+            # Global override: if DISCORD_REQUIRE_MENTION=false, all channels are free
             require_mention = os.getenv("DISCORD_REQUIRE_MENTION", "true").lower() not in ("false", "0", "no")
-            is_free_channel = bool(channel_ids & free_channels)
-
+            
+            is_free_channel = channel_id in free_channels
+            
             if require_mention and not is_free_channel:
+                # Must be @mentioned to respond
                 if self._client.user not in message.mentions:
-                    return
-
+                    return  # Silently ignore messages that don't mention the bot
+            
+            # Strip the bot mention from the message text so the agent sees clean input
             if self._client.user and self._client.user in message.mentions:
                 message.content = message.content.replace(f"<@{self._client.user.id}>", "").strip()
                 message.content = message.content.replace(f"<@!{self._client.user.id}>", "").strip()
-
+        
         # Determine message type
         msg_type = MessageType.TEXT
         if message.content.startswith("/"):
@@ -874,15 +720,20 @@ class DiscordAdapter(BasePlatformAdapter):
         if isinstance(message.channel, discord.DMChannel):
             chat_type = "dm"
             chat_name = message.author.name
-        elif is_thread:
+        elif isinstance(message.channel, discord.Thread):
             chat_type = "thread"
-            chat_name = self._format_thread_chat_name(message.channel)
+            chat_name = message.channel.name
         else:
-            chat_type = "group"
+            chat_type = "group"  # Treat server channels as groups
             chat_name = getattr(message.channel, "name", str(message.channel.id))
             if hasattr(message.channel, "guild") and message.channel.guild:
                 chat_name = f"{message.channel.guild.name} / #{chat_name}"
-
+        
+        # Get thread ID if in a thread
+        thread_id = None
+        if isinstance(message.channel, discord.Thread):
+            thread_id = str(message.channel.id)
+        
         # Get channel topic (if available - TextChannels have topics, DMs/threads don't)
         chat_topic = getattr(message.channel, "topic", None)
         

gateway/platforms/email.py

@@ -1,533 +0,0 @@
-"""
-Email platform adapter for the Hermes gateway.
-
-Allows users to interact with Hermes by sending emails.
-Uses IMAP to receive and SMTP to send messages.
-
-Environment variables:
-    EMAIL_IMAP_HOST     — IMAP server host (e.g., imap.gmail.com)
-    EMAIL_IMAP_PORT     — IMAP server port (default: 993)
-    EMAIL_SMTP_HOST     — SMTP server host (e.g., smtp.gmail.com)
-    EMAIL_SMTP_PORT     — SMTP server port (default: 587)
-    EMAIL_ADDRESS       — Email address for the agent
-    EMAIL_PASSWORD      — Email password or app-specific password
-    EMAIL_POLL_INTERVAL — Seconds between mailbox checks (default: 15)
-    EMAIL_ALLOWED_USERS — Comma-separated list of allowed sender addresses
-"""
-
-import asyncio
-import email as email_lib
-import imaplib
-import logging
-import os
-import re
-import smtplib
-import uuid
-from datetime import datetime
-from email.header import decode_header
-from email.mime.multipart import MIMEMultipart
-from email.mime.text import MIMEText
-from email.mime.base import MIMEBase
-from email import encoders
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from gateway.platforms.base import (
-    BasePlatformAdapter,
-    MessageEvent,
-    MessageType,
-    SendResult,
-    cache_document_from_bytes,
-    cache_image_from_bytes,
-)
-from gateway.config import Platform, PlatformConfig
-
-logger = logging.getLogger(__name__)
-
-# Gmail-safe max length per email body
-MAX_MESSAGE_LENGTH = 50_000
-
-# Supported image extensions for inline detection
-_IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
-
-
-def check_email_requirements() -> bool:
-    """Check if email platform dependencies are available."""
-    addr = os.getenv("EMAIL_ADDRESS")
-    pwd = os.getenv("EMAIL_PASSWORD")
-    imap = os.getenv("EMAIL_IMAP_HOST")
-    smtp = os.getenv("EMAIL_SMTP_HOST")
-    if not all([addr, pwd, imap, smtp]):
-        return False
-    return True
-
-
-def _decode_header_value(raw: str) -> str:
-    """Decode an RFC 2047 encoded email header into a plain string."""
-    parts = decode_header(raw)
-    decoded = []
-    for part, charset in parts:
-        if isinstance(part, bytes):
-            decoded.append(part.decode(charset or "utf-8", errors="replace"))
-        else:
-            decoded.append(part)
-    return " ".join(decoded)
-
-
-def _extract_text_body(msg: email_lib.message.Message) -> str:
-    """Extract the plain-text body from a potentially multipart email."""
-    if msg.is_multipart():
-        for part in msg.walk():
-            content_type = part.get_content_type()
-            disposition = str(part.get("Content-Disposition", ""))
-            # Skip attachments
-            if "attachment" in disposition:
-                continue
-            if content_type == "text/plain":
-                payload = part.get_payload(decode=True)
-                if payload:
-                    charset = part.get_content_charset() or "utf-8"
-                    return payload.decode(charset, errors="replace")
-        # Fallback: try text/html and strip tags
-        for part in msg.walk():
-            content_type = part.get_content_type()
-            disposition = str(part.get("Content-Disposition", ""))
-            if "attachment" in disposition:
-                continue
-            if content_type == "text/html":
-                payload = part.get_payload(decode=True)
-                if payload:
-                    charset = part.get_content_charset() or "utf-8"
-                    html = payload.decode(charset, errors="replace")
-                    return _strip_html(html)
-        return ""
-    else:
-        payload = msg.get_payload(decode=True)
-        if payload:
-            charset = msg.get_content_charset() or "utf-8"
-            text = payload.decode(charset, errors="replace")
-            if msg.get_content_type() == "text/html":
-                return _strip_html(text)
-            return text
-        return ""
-
-
-def _strip_html(html: str) -> str:
-    """Naive HTML tag stripper for fallback text extraction."""
-    text = re.sub(r"<br\s*/?>", "\n", html, flags=re.IGNORECASE)
-    text = re.sub(r"<p[^>]*>", "\n", text, flags=re.IGNORECASE)
-    text = re.sub(r"</p>", "\n", text, flags=re.IGNORECASE)
-    text = re.sub(r"<[^>]+>", "", text)
-    text = re.sub(r"&nbsp;", " ", text)
-    text = re.sub(r"&amp;", "&", text)
-    text = re.sub(r"&lt;", "<", text)
-    text = re.sub(r"&gt;", ">", text)
-    text = re.sub(r"\n{3,}", "\n\n", text)
-    return text.strip()
-
-
-def _extract_email_address(raw: str) -> str:
-    """Extract bare email address from 'Name <addr>' format."""
-    match = re.search(r"<([^>]+)>", raw)
-    if match:
-        return match.group(1).strip().lower()
-    return raw.strip().lower()
-
-
-def _extract_attachments(msg: email_lib.message.Message) -> List[Dict[str, Any]]:
-    """Extract attachment metadata and cache files locally."""
-    attachments = []
-    if not msg.is_multipart():
-        return attachments
-
-    for part in msg.walk():
-        disposition = str(part.get("Content-Disposition", ""))
-        if "attachment" not in disposition and "inline" not in disposition:
-            continue
-        # Skip text/plain and text/html body parts
-        content_type = part.get_content_type()
-        if content_type in ("text/plain", "text/html") and "attachment" not in disposition:
-            continue
-
-        filename = part.get_filename()
-        if filename:
-            filename = _decode_header_value(filename)
-        else:
-            ext = part.get_content_subtype() or "bin"
-            filename = f"attachment.{ext}"
-
-        payload = part.get_payload(decode=True)
-        if not payload:
-            continue
-
-        ext = Path(filename).suffix.lower()
-        if ext in _IMAGE_EXTS:
-            cached_path = cache_image_from_bytes(payload, ext)
-            attachments.append({
-                "path": cached_path,
-                "filename": filename,
-                "type": "image",
-                "media_type": content_type,
-            })
-        else:
-            cached_path = cache_document_from_bytes(payload, filename)
-            attachments.append({
-                "path": cached_path,
-                "filename": filename,
-                "type": "document",
-                "media_type": content_type,
-            })
-
-    return attachments
-
-
-class EmailAdapter(BasePlatformAdapter):
-    """Email gateway adapter using IMAP (receive) and SMTP (send)."""
-
-    def __init__(self, config: PlatformConfig):
-        super().__init__(config, Platform.EMAIL)
-
-        self._address = os.getenv("EMAIL_ADDRESS", "")
-        self._password = os.getenv("EMAIL_PASSWORD", "")
-        self._imap_host = os.getenv("EMAIL_IMAP_HOST", "")
-        self._imap_port = int(os.getenv("EMAIL_IMAP_PORT", "993"))
-        self._smtp_host = os.getenv("EMAIL_SMTP_HOST", "")
-        self._smtp_port = int(os.getenv("EMAIL_SMTP_PORT", "587"))
-        self._poll_interval = int(os.getenv("EMAIL_POLL_INTERVAL", "15"))
-
-        # Track message IDs we've already processed to avoid duplicates
-        self._seen_uids: set = set()
-        self._poll_task: Optional[asyncio.Task] = None
-
-        # Map chat_id (sender email) -> last subject + message-id for threading
-        self._thread_context: Dict[str, Dict[str, str]] = {}
-
-        logger.info("[Email] Adapter initialized for %s", self._address)
-
-    async def connect(self) -> bool:
-        """Connect to the IMAP server and start polling for new messages."""
-        try:
-            # Test IMAP connection
-            imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port)
-            imap.login(self._address, self._password)
-            # Mark all existing messages as seen so we only process new ones
-            imap.select("INBOX")
-            status, data = imap.search(None, "ALL")
-            if status == "OK" and data[0]:
-                for uid in data[0].split():
-                    self._seen_uids.add(uid)
-            imap.logout()
-            logger.info("[Email] IMAP connection test passed. %d existing messages skipped.", len(self._seen_uids))
-        except Exception as e:
-            logger.error("[Email] IMAP connection failed: %s", e)
-            return False
-
-        try:
-            # Test SMTP connection
-            smtp = smtplib.SMTP(self._smtp_host, self._smtp_port)
-            smtp.starttls()
-            smtp.login(self._address, self._password)
-            smtp.quit()
-            logger.info("[Email] SMTP connection test passed.")
-        except Exception as e:
-            logger.error("[Email] SMTP connection failed: %s", e)
-            return False
-
-        self._running = True
-        self._poll_task = asyncio.create_task(self._poll_loop())
-        print(f"[Email] Connected as {self._address}")
-        return True
-
-    async def disconnect(self) -> None:
-        """Stop polling and disconnect."""
-        self._running = False
-        if self._poll_task:
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except asyncio.CancelledError:
-                pass
-            self._poll_task = None
-        logger.info("[Email] Disconnected.")
-
-    async def _poll_loop(self) -> None:
-        """Poll IMAP for new messages at regular intervals."""
-        while self._running:
-            try:
-                await self._check_inbox()
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                logger.error("[Email] Poll error: %s", e)
-            await asyncio.sleep(self._poll_interval)
-
-    async def _check_inbox(self) -> None:
-        """Check INBOX for unseen messages and dispatch them."""
-        # Run IMAP operations in a thread to avoid blocking the event loop
-        loop = asyncio.get_running_loop()
-        messages = await loop.run_in_executor(None, self._fetch_new_messages)
-        for msg_data in messages:
-            await self._dispatch_message(msg_data)
-
-    def _fetch_new_messages(self) -> List[Dict[str, Any]]:
-        """Fetch new (unseen) messages from IMAP. Runs in executor thread."""
-        results = []
-        try:
-            imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port)
-            imap.login(self._address, self._password)
-            imap.select("INBOX")
-
-            status, data = imap.search(None, "UNSEEN")
-            if status != "OK" or not data[0]:
-                imap.logout()
-                return results
-
-            for uid in data[0].split():
-                if uid in self._seen_uids:
-                    continue
-                self._seen_uids.add(uid)
-
-                status, msg_data = imap.fetch(uid, "(RFC822)")
-                if status != "OK":
-                    continue
-
-                raw_email = msg_data[0][1]
-                msg = email_lib.message_from_bytes(raw_email)
-
-                sender_raw = msg.get("From", "")
-                sender_addr = _extract_email_address(sender_raw)
-                sender_name = _decode_header_value(sender_raw)
-                # Remove email from name if present
-                if "<" in sender_name:
-                    sender_name = sender_name.split("<")[0].strip().strip('"')
-
-                subject = _decode_header_value(msg.get("Subject", "(no subject)"))
-                message_id = msg.get("Message-ID", "")
-                in_reply_to = msg.get("In-Reply-To", "")
-                body = _extract_text_body(msg)
-                attachments = _extract_attachments(msg)
-
-                results.append({
-                    "uid": uid,
-                    "sender_addr": sender_addr,
-                    "sender_name": sender_name,
-                    "subject": subject,
-                    "message_id": message_id,
-                    "in_reply_to": in_reply_to,
-                    "body": body,
-                    "attachments": attachments,
-                    "date": msg.get("Date", ""),
-                })
-
-            imap.logout()
-        except Exception as e:
-            logger.error("[Email] IMAP fetch error: %s", e)
-        return results
-
-    async def _dispatch_message(self, msg_data: Dict[str, Any]) -> None:
-        """Convert a fetched email into a MessageEvent and dispatch it."""
-        sender_addr = msg_data["sender_addr"]
-
-        # Skip self-messages
-        if sender_addr == self._address.lower():
-            return
-
-        subject = msg_data["subject"]
-        body = msg_data["body"].strip()
-        attachments = msg_data["attachments"]
-
-        # Build message text: include subject as context
-        text = body
-        if subject and not subject.startswith("Re:"):
-            text = f"[Subject: {subject}]\n\n{body}"
-
-        # Determine message type and media
-        media_urls = []
-        media_types = []
-        msg_type = MessageType.TEXT
-
-        for att in attachments:
-            media_urls.append(att["path"])
-            media_types.append(att["media_type"])
-            if att["type"] == "image":
-                msg_type = MessageType.PHOTO
-
-        # Store thread context for reply threading
-        self._thread_context[sender_addr] = {
-            "subject": subject,
-            "message_id": msg_data["message_id"],
-        }
-
-        source = self.build_source(
-            chat_id=sender_addr,
-            chat_name=msg_data["sender_name"] or sender_addr,
-            chat_type="dm",
-            user_id=sender_addr,
-            user_name=msg_data["sender_name"] or sender_addr,
-        )
-
-        event = MessageEvent(
-            text=text or "(empty email)",
-            message_type=msg_type,
-            source=source,
-            message_id=msg_data["message_id"],
-            media_urls=media_urls,
-            media_types=media_types,
-            reply_to_message_id=msg_data["in_reply_to"] or None,
-        )
-
-        logger.info("[Email] New message from %s: %s", sender_addr, subject)
-        await self.handle_message(event)
-
-    async def send(
-        self,
-        chat_id: str,
-        content: str,
-        reply_to: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> SendResult:
-        """Send an email reply to the given address."""
-        try:
-            loop = asyncio.get_running_loop()
-            message_id = await loop.run_in_executor(
-                None, self._send_email, chat_id, content, reply_to
-            )
-            return SendResult(success=True, message_id=message_id)
-        except Exception as e:
-            logger.error("[Email] Send failed to %s: %s", chat_id, e)
-            return SendResult(success=False, error=str(e))
-
-    def _send_email(
-        self,
-        to_addr: str,
-        body: str,
-        reply_to_msg_id: Optional[str] = None,
-    ) -> str:
-        """Send an email via SMTP. Runs in executor thread."""
-        msg = MIMEMultipart()
-        msg["From"] = self._address
-        msg["To"] = to_addr
-
-        # Thread context for reply
-        ctx = self._thread_context.get(to_addr, {})
-        subject = ctx.get("subject", "Hermes Agent")
-        if not subject.startswith("Re:"):
-            subject = f"Re: {subject}"
-        msg["Subject"] = subject
-
-        # Threading headers
-        original_msg_id = reply_to_msg_id or ctx.get("message_id")
-        if original_msg_id:
-            msg["In-Reply-To"] = original_msg_id
-            msg["References"] = original_msg_id
-
-        msg_id = f"<hermes-{uuid.uuid4().hex[:12]}@{self._address.split('@')[1]}>"
-        msg["Message-ID"] = msg_id
-
-        msg.attach(MIMEText(body, "plain", "utf-8"))
-
-        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port)
-        smtp.starttls()
-        smtp.login(self._address, self._password)
-        smtp.send_message(msg)
-        smtp.quit()
-
-        logger.info("[Email] Sent reply to %s (subject: %s)", to_addr, subject)
-        return msg_id
-
-    async def send_typing(self, chat_id: str) -> None:
-        """Email has no typing indicator — no-op."""
-        pass
-
-    async def send_image(
-        self,
-        chat_id: str,
-        image_url: str,
-        caption: Optional[str] = None,
-        reply_to: Optional[str] = None,
-    ) -> SendResult:
-        """Send an image URL as part of an email body."""
-        text = caption or ""
-        text += f"\n\nImage: {image_url}"
-        return await self.send(chat_id, text.strip(), reply_to)
-
-    async def send_document(
-        self,
-        chat_id: str,
-        file_path: str,
-        caption: Optional[str] = None,
-        file_name: Optional[str] = None,
-        reply_to: Optional[str] = None,
-    ) -> SendResult:
-        """Send a file as an email attachment."""
-        try:
-            loop = asyncio.get_running_loop()
-            message_id = await loop.run_in_executor(
-                None,
-                self._send_email_with_attachment,
-                chat_id,
-                caption or "",
-                file_path,
-                file_name,
-            )
-            return SendResult(success=True, message_id=message_id)
-        except Exception as e:
-            logger.error("[Email] Send document failed: %s", e)
-            return SendResult(success=False, error=str(e))
-
-    def _send_email_with_attachment(
-        self,
-        to_addr: str,
-        body: str,
-        file_path: str,
-        file_name: Optional[str] = None,
-    ) -> str:
-        """Send an email with a file attachment via SMTP."""
-        msg = MIMEMultipart()
-        msg["From"] = self._address
-        msg["To"] = to_addr
-
-        ctx = self._thread_context.get(to_addr, {})
-        subject = ctx.get("subject", "Hermes Agent")
-        if not subject.startswith("Re:"):
-            subject = f"Re: {subject}"
-        msg["Subject"] = subject
-
-        original_msg_id = ctx.get("message_id")
-        if original_msg_id:
-            msg["In-Reply-To"] = original_msg_id
-            msg["References"] = original_msg_id
-
-        msg_id = f"<hermes-{uuid.uuid4().hex[:12]}@{self._address.split('@')[1]}>"
-        msg["Message-ID"] = msg_id
-
-        if body:
-            msg.attach(MIMEText(body, "plain", "utf-8"))
-
-        # Attach file
-        p = Path(file_path)
-        fname = file_name or p.name
-        with open(p, "rb") as f:
-            part = MIMEBase("application", "octet-stream")
-            part.set_payload(f.read())
-            encoders.encode_base64(part)
-            part.add_header("Content-Disposition", f"attachment; filename={fname}")
-            msg.attach(part)
-
-        smtp = smtplib.SMTP(self._smtp_host, self._smtp_port)
-        smtp.starttls()
-        smtp.login(self._address, self._password)
-        smtp.send_message(msg)
-        smtp.quit()
-
-        return msg_id
-
-    async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
-        """Return basic info about the email chat."""
-        ctx = self._thread_context.get(chat_id, {})
-        return {
-            "name": chat_id,
-            "type": "dm",
-            "chat_id": chat_id,
-            "subject": ctx.get("subject", ""),
-        }

gateway/platforms/homeassistant.py

@@ -419,7 +419,7 @@ class HomeAssistantAdapter(BasePlatformAdapter):
         except Exception as e:
             return SendResult(success=False, error=str(e))
 
-    async def send_typing(self, chat_id: str, metadata=None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """No typing indicator for Home Assistant."""
         pass
 

gateway/platforms/signal.py

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

gateway/platforms/slack.py

@@ -9,9 +9,7 @@ Uses slack-bolt (Python) with Socket Mode for:
 """
 
 import asyncio
-import logging
 import os
-import re
 from typing import Dict, List, Optional, Any
 
 try:
@@ -35,16 +33,11 @@ from gateway.platforms.base import (
     MessageEvent,
     MessageType,
     SendResult,
-    SUPPORTED_DOCUMENT_TYPES,
-    cache_document_from_bytes,
     cache_image_from_url,
     cache_audio_from_url,
 )
 
 
-logger = logging.getLogger(__name__)
-
-
 def check_slack_requirements() -> bool:
     """Check if Slack dependencies are available."""
     return SLACK_AVAILABLE
@@ -77,19 +70,17 @@ class SlackAdapter(BasePlatformAdapter):
     async def connect(self) -> bool:
         """Connect to Slack via Socket Mode."""
         if not SLACK_AVAILABLE:
-            logger.error(
-                "[Slack] slack-bolt not installed. Run: pip install slack-bolt",
-            )
+            print("[Slack] slack-bolt not installed. Run: pip install slack-bolt")
             return False
 
         bot_token = self.config.token
         app_token = os.getenv("SLACK_APP_TOKEN")
 
         if not bot_token:
-            logger.error("[Slack] SLACK_BOT_TOKEN not set")
+            print("[Slack] SLACK_BOT_TOKEN not set")
             return False
         if not app_token:
-            logger.error("[Slack] SLACK_APP_TOKEN not set")
+            print("[Slack] SLACK_APP_TOKEN not set")
             return False
 
         try:
@@ -105,13 +96,6 @@ class SlackAdapter(BasePlatformAdapter):
             async def handle_message_event(event, say):
                 await self._handle_slack_message(event)
 
-            # Acknowledge app_mention events to prevent Bolt 404 errors.
-            # The "message" handler above already processes @mentions in
-            # channels, so this is intentionally a no-op to avoid duplicates.
-            @self._app.event("app_mention")
-            async def handle_app_mention(event, say):
-                pass
-
             # Register slash command handler
             @self._app.command("/hermes")
             async def handle_hermes_command(ack, command):
@@ -123,22 +107,19 @@ class SlackAdapter(BasePlatformAdapter):
             asyncio.create_task(self._handler.start_async())
 
             self._running = True
-            logger.info("[Slack] Connected as @%s (Socket Mode)", bot_name)
+            print(f"[Slack] Connected as @{bot_name} (Socket Mode)")
             return True
 
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[Slack] Connection failed: %s", e, exc_info=True)
+        except Exception as e:
+            print(f"[Slack] Connection failed: {e}")
             return False
 
     async def disconnect(self) -> None:
         """Disconnect from Slack."""
         if self._handler:
-            try:
-                await self._handler.close_async()
-            except Exception as e:  # pragma: no cover - defensive logging
-                logger.warning("[Slack] Error while closing Socket Mode handler: %s", e, exc_info=True)
+            await self._handler.close_async()
         self._running = False
-        logger.info("[Slack] Disconnected")
+        print("[Slack] Disconnected")
 
     async def send(
         self,
@@ -171,8 +152,8 @@ class SlackAdapter(BasePlatformAdapter):
                 raw_response=result,
             )
 
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error("[Slack] Send error: %s", e, exc_info=True)
+        except Exception as e:
+            print(f"[Slack] Send error: {e}")
             return SendResult(success=False, error=str(e))
 
     async def edit_message(
@@ -191,17 +172,10 @@ class SlackAdapter(BasePlatformAdapter):
                 text=content,
             )
             return SendResult(success=True, message_id=message_id)
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[Slack] Failed to edit message %s in channel %s: %s",
-                message_id,
-                chat_id,
-                e,
-                exc_info=True,
-            )
+        except Exception as e:
             return SendResult(success=False, error=str(e))
 
-    async def send_typing(self, chat_id: str, metadata=None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """Slack doesn't have a direct typing indicator API for bots."""
         pass
 
@@ -230,14 +204,8 @@ class SlackAdapter(BasePlatformAdapter):
             )
             return SendResult(success=True, raw_response=result)
 
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[%s] Failed to send local Slack image %s: %s",
-                self.name,
-                image_path,
-                e,
-                exc_info=True,
-            )
+        except Exception as e:
+            print(f"[{self.name}] Failed to send local image: {e}")
             return await super().send_image_file(chat_id, image_path, caption, reply_to)
 
     async def send_image(
@@ -269,13 +237,7 @@ class SlackAdapter(BasePlatformAdapter):
 
             return SendResult(success=True, raw_response=result)
 
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.warning(
-                "[Slack] Failed to upload image from URL %s, falling back to text: %s",
-                image_url,
-                e,
-                exc_info=True,
-            )
+        except Exception as e:
             # Fall back to sending the URL as text
             text = f"{caption}\n{image_url}" if caption else image_url
             return await self.send(chat_id=chat_id, content=text, reply_to=reply_to)
@@ -301,86 +263,9 @@ class SlackAdapter(BasePlatformAdapter):
             )
             return SendResult(success=True, raw_response=result)
 
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[Slack] Failed to send audio file %s: %s",
-                audio_path,
-                e,
-                exc_info=True,
-            )
+        except Exception as e:
             return SendResult(success=False, error=str(e))
 
-    async def send_video(
-        self,
-        chat_id: str,
-        video_path: str,
-        caption: Optional[str] = None,
-        reply_to: Optional[str] = None,
-    ) -> SendResult:
-        """Send a video file to Slack."""
-        if not self._app:
-            return SendResult(success=False, error="Not connected")
-
-        if not os.path.exists(video_path):
-            return SendResult(success=False, error=f"Video file not found: {video_path}")
-
-        try:
-            result = await self._app.client.files_upload_v2(
-                channel=chat_id,
-                file=video_path,
-                filename=os.path.basename(video_path),
-                initial_comment=caption or "",
-                thread_ts=reply_to,
-            )
-            return SendResult(success=True, raw_response=result)
-
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[%s] Failed to send video %s: %s",
-                self.name,
-                video_path,
-                e,
-                exc_info=True,
-            )
-            return await super().send_video(chat_id, video_path, caption, reply_to)
-
-    async def send_document(
-        self,
-        chat_id: str,
-        file_path: str,
-        caption: Optional[str] = None,
-        file_name: Optional[str] = None,
-        reply_to: Optional[str] = None,
-    ) -> SendResult:
-        """Send a document/file attachment to Slack."""
-        if not self._app:
-            return SendResult(success=False, error="Not connected")
-
-        if not os.path.exists(file_path):
-            return SendResult(success=False, error=f"File not found: {file_path}")
-
-        display_name = file_name or os.path.basename(file_path)
-
-        try:
-            result = await self._app.client.files_upload_v2(
-                channel=chat_id,
-                file=file_path,
-                filename=display_name,
-                initial_comment=caption or "",
-                thread_ts=reply_to,
-            )
-            return SendResult(success=True, raw_response=result)
-
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[%s] Failed to send document %s: %s",
-                self.name,
-                file_path,
-                e,
-                exc_info=True,
-            )
-            return await super().send_document(chat_id, file_path, caption, file_name, reply_to)
-
     async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
         """Get information about a Slack channel."""
         if not self._app:
@@ -394,13 +279,7 @@ class SlackAdapter(BasePlatformAdapter):
                 "name": channel.get("name", chat_id),
                 "type": "dm" if is_dm else "group",
             }
-        except Exception as e:  # pragma: no cover - defensive logging
-            logger.error(
-                "[Slack] Failed to fetch chat info for %s: %s",
-                chat_id,
-                e,
-                exc_info=True,
-            )
+        except Exception:
             return {"name": chat_id, "type": "unknown"}
 
     # ----- Internal handlers -----
@@ -455,8 +334,8 @@ class SlackAdapter(BasePlatformAdapter):
                     media_urls.append(cached)
                     media_types.append(mimetype)
                     msg_type = MessageType.PHOTO
-                except Exception as e:  # pragma: no cover - defensive logging
-                    logger.warning("[Slack] Failed to cache image from %s: %s", url, e, exc_info=True)
+                except Exception as e:
+                    print(f"[Slack] Failed to cache image: {e}", flush=True)
             elif mimetype.startswith("audio/") and url:
                 try:
                     ext = "." + mimetype.split("/")[-1].split(";")[0]
@@ -466,60 +345,8 @@ class SlackAdapter(BasePlatformAdapter):
                     media_urls.append(cached)
                     media_types.append(mimetype)
                     msg_type = MessageType.VOICE
-                except Exception as e:  # pragma: no cover - defensive logging
-                    logger.warning("[Slack] Failed to cache audio from %s: %s", url, e, exc_info=True)
-            elif url:
-                # Try to handle as a document attachment
-                try:
-                    original_filename = f.get("name", "")
-                    ext = ""
-                    if original_filename:
-                        _, ext = os.path.splitext(original_filename)
-                        ext = ext.lower()
-
-                    # Fallback: reverse-lookup from MIME type
-                    if not ext and mimetype:
-                        mime_to_ext = {v: k for k, v in SUPPORTED_DOCUMENT_TYPES.items()}
-                        ext = mime_to_ext.get(mimetype, "")
-
-                    if ext not in SUPPORTED_DOCUMENT_TYPES:
-                        continue  # Skip unsupported file types silently
-
-                    # Check file size (Slack limit: 20 MB for bots)
-                    file_size = f.get("size", 0)
-                    MAX_DOC_BYTES = 20 * 1024 * 1024
-                    if not file_size or file_size > MAX_DOC_BYTES:
-                        logger.warning("[Slack] Document too large or unknown size: %s", file_size)
-                        continue
-
-                    # Download and cache
-                    raw_bytes = await self._download_slack_file_bytes(url)
-                    cached_path = cache_document_from_bytes(
-                        raw_bytes, original_filename or f"document{ext}"
-                    )
-                    doc_mime = SUPPORTED_DOCUMENT_TYPES[ext]
-                    media_urls.append(cached_path)
-                    media_types.append(doc_mime)
-                    msg_type = MessageType.DOCUMENT
-                    logger.debug("[Slack] Cached user document: %s", cached_path)
-
-                    # Inject text content for .txt/.md files (capped at 100 KB)
-                    MAX_TEXT_INJECT_BYTES = 100 * 1024
-                    if ext in (".md", ".txt") and len(raw_bytes) <= MAX_TEXT_INJECT_BYTES:
-                        try:
-                            text_content = raw_bytes.decode("utf-8")
-                            display_name = original_filename or f"document{ext}"
-                            display_name = re.sub(r'[^\w.\- ]', '_', display_name)
-                            injection = f"[Content of {display_name}]:\n{text_content}"
-                            if text:
-                                text = f"{injection}\n\n{text}"
-                            else:
-                                text = injection
-                        except UnicodeDecodeError:
-                            pass  # Binary content, skip injection
-
-                except Exception as e:  # pragma: no cover - defensive logging
-                    logger.warning("[Slack] Failed to cache document from %s: %s", url, e, exc_info=True)
+                except Exception as e:
+                    print(f"[Slack] Failed to cache audio: {e}", flush=True)
 
         # Build source
         source = self.build_source(
@@ -600,16 +427,3 @@ class SlackAdapter(BasePlatformAdapter):
         else:
             from gateway.platforms.base import cache_image_from_bytes
             return cache_image_from_bytes(response.content, ext)
-
-    async def _download_slack_file_bytes(self, url: str) -> bytes:
-        """Download a Slack file and return raw bytes."""
-        import httpx
-
-        bot_token = self.config.token
-        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
-            response = await client.get(
-                url,
-                headers={"Authorization": f"Bearer {bot_token}"},
-            )
-            response.raise_for_status()
-        return response.content

gateway/platforms/telegram.py

@@ -86,9 +86,6 @@ def _strip_mdv2(text: str) -> str:
     cleaned = re.sub(r'\\([_*\[\]()~`>#\+\-=|{}.!\\])', r'\1', text)
     # Remove MarkdownV2 bold markers that format_message converted from **bold**
     cleaned = re.sub(r'\*([^*]+)\*', r'\1', cleaned)
-    # Remove MarkdownV2 italic markers that format_message converted from *italic*
-    # Use word boundary (\b) to avoid breaking snake_case like my_variable_name
-    cleaned = re.sub(r'(?<!\w)_([^_]+)_(?!\w)', r'\1', cleaned)
     return cleaned
 
 
@@ -114,14 +111,11 @@ class TelegramAdapter(BasePlatformAdapter):
     async def connect(self) -> bool:
         """Connect to Telegram and start polling for updates."""
         if not TELEGRAM_AVAILABLE:
-            logger.error(
-                "[%s] python-telegram-bot not installed. Run: pip install python-telegram-bot",
-                self.name,
-            )
+            print(f"[{self.name}] python-telegram-bot not installed. Run: pip install python-telegram-bot")
             return False
         
         if not self.config.token:
-            logger.error("[%s] No bot token configured", self.name)
+            print(f"[{self.name}] No bot token configured")
             return False
         
         try:
@@ -138,10 +132,6 @@ class TelegramAdapter(BasePlatformAdapter):
                 filters.COMMAND,
                 self._handle_command
             ))
-            self._app.add_handler(TelegramMessageHandler(
-                filters.LOCATION | getattr(filters, "VENUE", filters.LOCATION),
-                self._handle_location_message
-            ))
             self._app.add_handler(TelegramMessageHandler(
                 filters.PHOTO | filters.VIDEO | filters.AUDIO | filters.VOICE | filters.Document.ALL | filters.Sticker.ALL,
                 self._handle_media_message
@@ -165,30 +155,17 @@ class TelegramAdapter(BasePlatformAdapter):
                     BotCommand("status", "Show session info"),
                     BotCommand("stop", "Stop the running agent"),
                     BotCommand("sethome", "Set this chat as the home channel"),
-                    BotCommand("compress", "Compress conversation context"),
-                    BotCommand("title", "Set or show the session title"),
-                    BotCommand("resume", "Resume a previously-named session"),
-                    BotCommand("usage", "Show token usage for this session"),
-                    BotCommand("provider", "Show available providers"),
-                    BotCommand("insights", "Show usage insights and analytics"),
-                    BotCommand("update", "Update Hermes to the latest version"),
-                    BotCommand("reload_mcp", "Reload MCP servers from config"),
                     BotCommand("help", "Show available commands"),
                 ])
             except Exception as e:
-                logger.warning(
-                    "[%s] Could not register Telegram command menu: %s",
-                    self.name,
-                    e,
-                    exc_info=True,
-                )
+                print(f"[{self.name}] Could not register command menu: {e}")
             
             self._running = True
-            logger.info("[%s] Connected and polling for Telegram updates", self.name)
+            print(f"[{self.name}] Connected and polling for updates")
             return True
             
         except Exception as e:
-            logger.error("[%s] Failed to connect to Telegram: %s", self.name, e, exc_info=True)
+            print(f"[{self.name}] Failed to connect: {e}")
             return False
     
     async def disconnect(self) -> None:
@@ -199,12 +176,12 @@ class TelegramAdapter(BasePlatformAdapter):
                 await self._app.stop()
                 await self._app.shutdown()
             except Exception as e:
-                logger.warning("[%s] Error during Telegram disconnect: %s", self.name, e, exc_info=True)
+                print(f"[{self.name}] Error during disconnect: {e}")
         
         self._running = False
         self._app = None
         self._bot = None
-        logger.info("[%s] Disconnected from Telegram", self.name)
+        print(f"[{self.name}] Disconnected")
     
     async def send(
         self,
@@ -260,7 +237,6 @@ class TelegramAdapter(BasePlatformAdapter):
             )
             
         except Exception as e:
-            logger.error("[%s] Failed to send Telegram message: %s", self.name, e, exc_info=True)
             return SendResult(success=False, error=str(e))
 
     async def edit_message(
@@ -290,13 +266,6 @@ class TelegramAdapter(BasePlatformAdapter):
                 )
             return SendResult(success=True, message_id=message_id)
         except Exception as e:
-            logger.error(
-                "[%s] Failed to edit Telegram message %s: %s",
-                self.name,
-                message_id,
-                e,
-                exc_info=True,
-            )
             return SendResult(success=False, error=str(e))
 
     async def send_voice(
@@ -305,7 +274,6 @@ class TelegramAdapter(BasePlatformAdapter):
         audio_path: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
         """Send audio as a native Telegram voice message or audio file."""
         if not self._bot:
@@ -319,32 +287,23 @@ class TelegramAdapter(BasePlatformAdapter):
             with open(audio_path, "rb") as audio_file:
                 # .ogg files -> send as voice (round playable bubble)
                 if audio_path.endswith(".ogg") or audio_path.endswith(".opus"):
-                    _voice_thread = metadata.get("thread_id") if metadata else None
                     msg = await self._bot.send_voice(
                         chat_id=int(chat_id),
                         voice=audio_file,
                         caption=caption[:1024] if caption else None,
                         reply_to_message_id=int(reply_to) if reply_to else None,
-                        message_thread_id=int(_voice_thread) if _voice_thread else None,
                     )
                 else:
                     # .mp3 and others -> send as audio file
-                    _audio_thread = metadata.get("thread_id") if metadata else None
                     msg = await self._bot.send_audio(
                         chat_id=int(chat_id),
                         audio=audio_file,
                         caption=caption[:1024] if caption else None,
                         reply_to_message_id=int(reply_to) if reply_to else None,
-                        message_thread_id=int(_audio_thread) if _audio_thread else None,
                     )
             return SendResult(success=True, message_id=str(msg.message_id))
         except Exception as e:
-            logger.error(
-                "[%s] Failed to send Telegram voice/audio, falling back to base adapter: %s",
-                self.name,
-                e,
-                exc_info=True,
-            )
+            print(f"[{self.name}] Failed to send voice/audio: {e}")
             return await super().send_voice(chat_id, audio_path, caption, reply_to)
     
     async def send_image_file(
@@ -353,7 +312,6 @@ class TelegramAdapter(BasePlatformAdapter):
         image_path: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        **kwargs,
     ) -> SendResult:
         """Send a local image file natively as a Telegram photo."""
         if not self._bot:
@@ -373,81 +331,15 @@ class TelegramAdapter(BasePlatformAdapter):
                 )
             return SendResult(success=True, message_id=str(msg.message_id))
         except Exception as e:
-            logger.error(
-                "[%s] Failed to send Telegram local image, falling back to base adapter: %s",
-                self.name,
-                e,
-                exc_info=True,
-            )
+            print(f"[{self.name}] Failed to send local image: {e}")
             return await super().send_image_file(chat_id, image_path, caption, reply_to)
 
-    async def send_document(
-        self,
-        chat_id: str,
-        file_path: str,
-        caption: Optional[str] = None,
-        file_name: Optional[str] = None,
-        reply_to: Optional[str] = None,
-        **kwargs,
-    ) -> SendResult:
-        """Send a document/file natively as a Telegram file attachment."""
-        if not self._bot:
-            return SendResult(success=False, error="Not connected")
-
-        try:
-            if not os.path.exists(file_path):
-                return SendResult(success=False, error=f"File not found: {file_path}")
-
-            display_name = file_name or os.path.basename(file_path)
-
-            with open(file_path, "rb") as f:
-                msg = await self._bot.send_document(
-                    chat_id=int(chat_id),
-                    document=f,
-                    filename=display_name,
-                    caption=caption[:1024] if caption else None,
-                    reply_to_message_id=int(reply_to) if reply_to else None,
-                )
-            return SendResult(success=True, message_id=str(msg.message_id))
-        except Exception as e:
-            print(f"[{self.name}] Failed to send document: {e}")
-            return await super().send_document(chat_id, file_path, caption, file_name, reply_to)
-
-    async def send_video(
-        self,
-        chat_id: str,
-        video_path: str,
-        caption: Optional[str] = None,
-        reply_to: Optional[str] = None,
-        **kwargs,
-    ) -> SendResult:
-        """Send a video natively as a Telegram video message."""
-        if not self._bot:
-            return SendResult(success=False, error="Not connected")
-
-        try:
-            if not os.path.exists(video_path):
-                return SendResult(success=False, error=f"Video file not found: {video_path}")
-
-            with open(video_path, "rb") as f:
-                msg = await self._bot.send_video(
-                    chat_id=int(chat_id),
-                    video=f,
-                    caption=caption[:1024] if caption else None,
-                    reply_to_message_id=int(reply_to) if reply_to else None,
-                )
-            return SendResult(success=True, message_id=str(msg.message_id))
-        except Exception as e:
-            print(f"[{self.name}] Failed to send video: {e}")
-            return await super().send_video(chat_id, video_path, caption, reply_to)
-
     async def send_image(
         self,
         chat_id: str,
         image_url: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
         """Send an image natively as a Telegram photo.
         
@@ -459,22 +351,15 @@ class TelegramAdapter(BasePlatformAdapter):
         
         try:
             # Telegram can send photos directly from URLs (up to ~5MB)
-            _photo_thread = metadata.get("thread_id") if metadata else None
             msg = await self._bot.send_photo(
                 chat_id=int(chat_id),
                 photo=image_url,
                 caption=caption[:1024] if caption else None,  # Telegram caption limit
                 reply_to_message_id=int(reply_to) if reply_to else None,
-                message_thread_id=int(_photo_thread) if _photo_thread else None,
             )
             return SendResult(success=True, message_id=str(msg.message_id))
         except Exception as e:
-            logger.warning(
-                "[%s] URL-based send_photo failed, trying file upload: %s",
-                self.name,
-                e,
-                exc_info=True,
-            )
+            logger.warning("[%s] URL-based send_photo failed (%s), trying file upload", self.name, e)
             # Fallback: download and upload as file (supports up to 10MB)
             try:
                 import httpx
@@ -491,12 +376,7 @@ class TelegramAdapter(BasePlatformAdapter):
                 )
                 return SendResult(success=True, message_id=str(msg.message_id))
             except Exception as e2:
-                logger.error(
-                    "[%s] File upload send_photo also failed: %s",
-                    self.name,
-                    e2,
-                    exc_info=True,
-                )
+                logger.error("[%s] File upload send_photo also failed: %s", self.name, e2)
                 # Final fallback: send URL as text
                 return await super().send_image(chat_id, image_url, caption, reply_to)
     
@@ -506,50 +386,34 @@ class TelegramAdapter(BasePlatformAdapter):
         animation_url: str,
         caption: Optional[str] = None,
         reply_to: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
     ) -> SendResult:
         """Send an animated GIF natively as a Telegram animation (auto-plays inline)."""
         if not self._bot:
             return SendResult(success=False, error="Not connected")
         
         try:
-            _anim_thread = metadata.get("thread_id") if metadata else None
             msg = await self._bot.send_animation(
                 chat_id=int(chat_id),
                 animation=animation_url,
                 caption=caption[:1024] if caption else None,
                 reply_to_message_id=int(reply_to) if reply_to else None,
-                message_thread_id=int(_anim_thread) if _anim_thread else None,
             )
             return SendResult(success=True, message_id=str(msg.message_id))
         except Exception as e:
-            logger.error(
-                "[%s] Failed to send Telegram animation, falling back to photo: %s",
-                self.name,
-                e,
-                exc_info=True,
-            )
+            print(f"[{self.name}] Failed to send animation, falling back to photo: {e}")
             # Fallback: try as a regular photo
             return await self.send_image(chat_id, animation_url, caption, reply_to)
 
-    async def send_typing(self, chat_id: str, metadata: Optional[Dict[str, Any]] = None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """Send typing indicator."""
         if self._bot:
             try:
-                _typing_thread = metadata.get("thread_id") if metadata else None
                 await self._bot.send_chat_action(
                     chat_id=int(chat_id),
-                    action="typing",
-                    message_thread_id=int(_typing_thread) if _typing_thread else None,
-                )
-            except Exception as e:
-                # Typing failures are non-fatal; log at debug level only.
-                logger.debug(
-                    "[%s] Failed to send Telegram typing indicator: %s",
-                    self.name,
-                    e,
-                    exc_info=True,
+                    action="typing"
                 )
+            except Exception:
+                pass  # Ignore typing indicator failures
     
     async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
         """Get information about a Telegram chat."""
@@ -576,13 +440,6 @@ class TelegramAdapter(BasePlatformAdapter):
                 "is_forum": getattr(chat, "is_forum", False),
             }
         except Exception as e:
-            logger.error(
-                "[%s] Failed to get Telegram chat info for %s: %s",
-                self.name,
-                chat_id,
-                e,
-                exc_info=True,
-            )
             return {"name": str(chat_id), "type": "dm", "error": str(e)}
     
     def format_message(self, content: str) -> str:
@@ -681,41 +538,6 @@ class TelegramAdapter(BasePlatformAdapter):
         event = self._build_message_event(update.message, MessageType.COMMAND)
         await self.handle_message(event)
     
-    async def _handle_location_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
-        """Handle incoming location/venue pin messages."""
-        if not update.message:
-            return
-
-        msg = update.message
-        venue = getattr(msg, "venue", None)
-        location = getattr(venue, "location", None) if venue else getattr(msg, "location", None)
-
-        if not location:
-            return
-
-        lat = getattr(location, "latitude", None)
-        lon = getattr(location, "longitude", None)
-        if lat is None or lon is None:
-            return
-
-        # Build a text message with coordinates and context
-        parts = ["[The user shared a location pin.]"]
-        if venue:
-            title = getattr(venue, "title", None)
-            address = getattr(venue, "address", None)
-            if title:
-                parts.append(f"Venue: {title}")
-            if address:
-                parts.append(f"Address: {address}")
-        parts.append(f"latitude: {lat}")
-        parts.append(f"longitude: {lon}")
-        parts.append(f"Map: https://www.google.com/maps/search/?api=1&query={lat},{lon}")
-        parts.append("Ask what they'd like to find nearby (restaurants, cafes, etc.) and any preferences.")
-
-        event = self._build_message_event(msg, MessageType.LOCATION)
-        event.text = "\n".join(parts)
-        await self.handle_message(event)
-
     async def _handle_media_message(self, update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
         """Handle incoming media messages, downloading images to local cache."""
         if not update.message:
@@ -771,9 +593,9 @@ class TelegramAdapter(BasePlatformAdapter):
                 cached_path = cache_image_from_bytes(bytes(image_bytes), ext=ext)
                 event.media_urls = [cached_path]
                 event.media_types = [f"image/{ext.lstrip('.')}"]
-                logger.info("[Telegram] Cached user photo at %s", cached_path)
+                print(f"[Telegram] Cached user photo: {cached_path}", flush=True)
             except Exception as e:
-                logger.warning("[Telegram] Failed to cache photo: %s", e, exc_info=True)
+                print(f"[Telegram] Failed to cache photo: {e}", flush=True)
         
         # Download voice/audio messages to cache for STT transcription
         if msg.voice:
@@ -783,9 +605,9 @@ class TelegramAdapter(BasePlatformAdapter):
                 cached_path = cache_audio_from_bytes(bytes(audio_bytes), ext=".ogg")
                 event.media_urls = [cached_path]
                 event.media_types = ["audio/ogg"]
-                logger.info("[Telegram] Cached user voice at %s", cached_path)
+                print(f"[Telegram] Cached user voice: {cached_path}", flush=True)
             except Exception as e:
-                logger.warning("[Telegram] Failed to cache voice: %s", e, exc_info=True)
+                print(f"[Telegram] Failed to cache voice: {e}", flush=True)
         elif msg.audio:
             try:
                 file_obj = await msg.audio.get_file()
@@ -793,9 +615,9 @@ class TelegramAdapter(BasePlatformAdapter):
                 cached_path = cache_audio_from_bytes(bytes(audio_bytes), ext=".mp3")
                 event.media_urls = [cached_path]
                 event.media_types = ["audio/mp3"]
-                logger.info("[Telegram] Cached user audio at %s", cached_path)
+                print(f"[Telegram] Cached user audio: {cached_path}", flush=True)
             except Exception as e:
-                logger.warning("[Telegram] Failed to cache audio: %s", e, exc_info=True)
+                print(f"[Telegram] Failed to cache audio: {e}", flush=True)
 
         # Download document files to cache for agent processing
         elif msg.document:
@@ -820,7 +642,7 @@ class TelegramAdapter(BasePlatformAdapter):
                         f"Unsupported document type '{ext or 'unknown'}'. "
                         f"Supported types: {supported_list}"
                     )
-                    logger.info("[Telegram] Unsupported document type: %s", ext or "unknown")
+                    print(f"[Telegram] Unsupported document type: {ext or 'unknown'}", flush=True)
                     await self.handle_message(event)
                     return
 
@@ -831,7 +653,7 @@ class TelegramAdapter(BasePlatformAdapter):
                         "The document is too large or its size could not be verified. "
                         "Maximum: 20 MB."
                     )
-                    logger.info("[Telegram] Document too large: %s bytes", doc.file_size)
+                    print(f"[Telegram] Document too large: {doc.file_size} bytes", flush=True)
                     await self.handle_message(event)
                     return
 
@@ -843,7 +665,7 @@ class TelegramAdapter(BasePlatformAdapter):
                 mime_type = SUPPORTED_DOCUMENT_TYPES[ext]
                 event.media_urls = [cached_path]
                 event.media_types = [mime_type]
-                logger.info("[Telegram] Cached user document at %s", cached_path)
+                print(f"[Telegram] Cached user document: {cached_path}", flush=True)
 
                 # For text files, inject content into event.text (capped at 100 KB)
                 MAX_TEXT_INJECT_BYTES = 100 * 1024
@@ -858,13 +680,10 @@ class TelegramAdapter(BasePlatformAdapter):
                         else:
                             event.text = injection
                     except UnicodeDecodeError:
-                        logger.warning(
-                            "[Telegram] Could not decode text file as UTF-8, skipping content injection",
-                            exc_info=True,
-                        )
+                        print(f"[Telegram] Could not decode text file as UTF-8, skipping content injection", flush=True)
 
             except Exception as e:
-                logger.warning("[Telegram] Failed to cache document: %s", e, exc_info=True)
+                print(f"[Telegram] Failed to cache document: {e}", flush=True)
 
         await self.handle_message(event)
     
@@ -899,7 +718,7 @@ class TelegramAdapter(BasePlatformAdapter):
             event.text = build_sticker_injection(
                 cached["description"], cached.get("emoji", emoji), cached.get("set_name", set_name)
             )
-            logger.info("[Telegram] Sticker cache hit: %s", sticker.file_unique_id)
+            print(f"[Telegram] Sticker cache hit: {sticker.file_unique_id}", flush=True)
             return
 
         # Cache miss -- download and analyze
@@ -907,7 +726,7 @@ class TelegramAdapter(BasePlatformAdapter):
             file_obj = await sticker.get_file()
             image_bytes = await file_obj.download_as_bytearray()
             cached_path = cache_image_from_bytes(bytes(image_bytes), ext=".webp")
-            logger.info("[Telegram] Analyzing sticker at %s", cached_path)
+            print(f"[Telegram] Analyzing sticker: {cached_path}", flush=True)
 
             from tools.vision_tools import vision_analyze_tool
             import json as _json
@@ -929,7 +748,7 @@ class TelegramAdapter(BasePlatformAdapter):
                     emoji, set_name,
                 )
         except Exception as e:
-            logger.warning("[Telegram] Sticker analysis error: %s", e, exc_info=True)
+            print(f"[Telegram] Sticker analysis error: {e}", flush=True)
             event.text = build_sticker_injection(
                 f"a sticker with emoji {emoji}" if emoji else "a sticker",
                 emoji, set_name,

gateway/platforms/whatsapp.py

@@ -181,8 +181,8 @@ class WhatsAppAdapter(BasePlatformAdapter):
             
             # Kill any orphaned bridge from a previous gateway run
             _kill_port_process(self._bridge_port)
-            import asyncio
-            await asyncio.sleep(1)
+            import time
+            time.sleep(1)
             
             # Start the bridge process in its own process group.
             # Route output to a log file so QR codes, errors, and reconnection
@@ -493,7 +493,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
             file_name or os.path.basename(file_path),
         )
 
-    async def send_typing(self, chat_id: str, metadata=None) -> None:
+    async def send_typing(self, chat_id: str) -> None:
         """Send typing indicator via bridge."""
         if not self._running:
             return

gateway/session.py

@@ -45,8 +45,6 @@ class SessionSource:
     user_name: Optional[str] = None
     thread_id: Optional[str] = None  # For forum topics, Discord threads, etc.
     chat_topic: Optional[str] = None  # Channel topic/description (Discord, Slack)
-    user_id_alt: Optional[str] = None  # Signal UUID (alternative to phone number)
-    chat_id_alt: Optional[str] = None  # Signal group internal ID
     
     @property
     def description(self) -> str:
@@ -70,7 +68,7 @@ class SessionSource:
         return ", ".join(parts)
     
     def to_dict(self) -> Dict[str, Any]:
-        d = {
+        return {
             "platform": self.platform.value,
             "chat_id": self.chat_id,
             "chat_name": self.chat_name,
@@ -80,11 +78,6 @@ class SessionSource:
             "thread_id": self.thread_id,
             "chat_topic": self.chat_topic,
         }
-        if self.user_id_alt:
-            d["user_id_alt"] = self.user_id_alt
-        if self.chat_id_alt:
-            d["chat_id_alt"] = self.chat_id_alt
-        return d
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "SessionSource":
@@ -97,8 +90,6 @@ class SessionSource:
             user_name=data.get("user_name"),
             thread_id=data.get("thread_id"),
             chat_topic=data.get("chat_topic"),
-            user_id_alt=data.get("user_id_alt"),
-            chat_id_alt=data.get("chat_id_alt"),
         )
     
     @classmethod
@@ -241,9 +232,6 @@ class SessionEntry:
     output_tokens: int = 0
     total_tokens: int = 0
     
-    # Last API-reported prompt tokens (for accurate compression pre-check)
-    last_prompt_tokens: int = 0
-    
     # Set when a session was created because the previous one expired;
     # consumed once by the message handler to inject a notice into context
     was_auto_reset: bool = False
@@ -260,7 +248,6 @@ class SessionEntry:
             "input_tokens": self.input_tokens,
             "output_tokens": self.output_tokens,
             "total_tokens": self.total_tokens,
-            "last_prompt_tokens": self.last_prompt_tokens,
         }
         if self.origin:
             result["origin"] = self.origin.to_dict()
@@ -276,8 +263,8 @@ class SessionEntry:
         if data.get("platform"):
             try:
                 platform = Platform(data["platform"])
-            except ValueError as e:
-                logger.debug("Unknown platform value %r: %s", data["platform"], e)
+            except ValueError:
+                pass
         
         return cls(
             session_key=data["session_key"],
@@ -291,7 +278,6 @@ class SessionEntry:
             input_tokens=data.get("input_tokens", 0),
             output_tokens=data.get("output_tokens", 0),
             total_tokens=data.get("total_tokens", 0),
-            last_prompt_tokens=data.get("last_prompt_tokens", 0),
         )
 
 
@@ -306,8 +292,6 @@ def build_session_key(source: SessionSource) -> str:
         if platform == "whatsapp" and source.chat_id:
             return f"agent:main:{platform}:dm:{source.chat_id}"
         return f"agent:main:{platform}:dm"
-    if source.thread_id:
-        return f"agent:main:{platform}:{source.chat_type}:{source.chat_id}:{source.thread_id}"
     return f"agent:main:{platform}:{source.chat_type}:{source.chat_id}"
 
 
@@ -349,7 +333,7 @@ class SessionStore:
         
         if sessions_file.exists():
             try:
-                with open(sessions_file, "r", encoding="utf-8") as f:
+                with open(sessions_file, "r") as f:
                     data = json.load(f)
                     for key, entry_data in data.items():
                         self._entries[key] = SessionEntry.from_dict(entry_data)
@@ -360,26 +344,12 @@ class SessionStore:
     
     def _save(self) -> None:
         """Save sessions index to disk (kept for session key -> ID mapping)."""
-        import tempfile
         self.sessions_dir.mkdir(parents=True, exist_ok=True)
         sessions_file = self.sessions_dir / "sessions.json"
-
+        
         data = {key: entry.to_dict() for key, entry in self._entries.items()}
-        fd, tmp_path = tempfile.mkstemp(
-            dir=str(self.sessions_dir), suffix=".tmp", prefix=".sessions_"
-        )
-        try:
-            with os.fdopen(fd, "w", encoding="utf-8") as f:
-                json.dump(data, f, indent=2)
-                f.flush()
-                os.fsync(f.fileno())
-            os.replace(tmp_path, sessions_file)
-        except BaseException:
-            try:
-                os.unlink(tmp_path)
-            except OSError as e:
-                logger.debug("Could not remove temp file %s: %s", tmp_path, e)
-            raise
+        with open(sessions_file, "w") as f:
+            json.dump(data, f, indent=2)
     
     def _generate_session_key(self, source: SessionSource) -> str:
         """Generate a session key from a source."""
@@ -557,8 +527,7 @@ class SessionStore:
         self, 
         session_key: str,
         input_tokens: int = 0,
-        output_tokens: int = 0,
-        last_prompt_tokens: int = None,
+        output_tokens: int = 0
     ) -> None:
         """Update a session's metadata after an interaction."""
         self._ensure_loaded()
@@ -568,8 +537,6 @@ class SessionStore:
             entry.updated_at = datetime.now()
             entry.input_tokens += input_tokens
             entry.output_tokens += output_tokens
-            if last_prompt_tokens is not None:
-                entry.last_prompt_tokens = last_prompt_tokens
             entry.total_tokens = entry.input_tokens + entry.output_tokens
             self._save()
             
@@ -626,49 +593,7 @@ class SessionStore:
                 logger.debug("Session DB operation failed: %s", e)
         
         return new_entry
-
-    def switch_session(self, session_key: str, target_session_id: str) -> Optional[SessionEntry]:
-        """Switch a session key to point at an existing session ID.
-
-        Used by ``/resume`` to restore a previously-named session.
-        Ends the current session in SQLite (like reset), but instead of
-        generating a fresh session ID, re-uses ``target_session_id`` so the
-        old transcript is loaded on the next message.
-        """
-        self._ensure_loaded()
-
-        if session_key not in self._entries:
-            return None
-
-        old_entry = self._entries[session_key]
-
-        # Don't switch if already on that session
-        if old_entry.session_id == target_session_id:
-            return old_entry
-
-        # End the current session in SQLite
-        if self._db:
-            try:
-                self._db.end_session(old_entry.session_id, "session_switch")
-            except Exception as e:
-                logger.debug("Session DB end_session failed: %s", e)
-
-        now = datetime.now()
-        new_entry = SessionEntry(
-            session_key=session_key,
-            session_id=target_session_id,
-            created_at=now,
-            updated_at=now,
-            origin=old_entry.origin,
-            display_name=old_entry.display_name,
-            platform=old_entry.platform,
-            chat_type=old_entry.chat_type,
-        )
-
-        self._entries[session_key] = new_entry
-        self._save()
-        return new_entry
-
+    
     def list_sessions(self, active_minutes: Optional[int] = None) -> List[SessionEntry]:
         """List all sessions, optionally filtered by activity."""
         self._ensure_loaded()
@@ -687,17 +612,10 @@ class SessionStore:
         """Get the path to a session's legacy transcript file."""
         return self.sessions_dir / f"{session_id}.jsonl"
     
-    def append_to_transcript(self, session_id: str, message: Dict[str, Any], skip_db: bool = False) -> None:
-        """Append a message to a session's transcript (SQLite + legacy JSONL).
-
-        Args:
-            skip_db: When True, only write to JSONL and skip the SQLite write.
-                     Used when the agent already persisted messages to SQLite
-                     via its own _flush_messages_to_session_db(), preventing
-                     the duplicate-write bug (#860).
-        """
-        # Write to SQLite (unless the agent already handled it)
-        if self._db and not skip_db:
+    def append_to_transcript(self, session_id: str, message: Dict[str, Any]) -> None:
+        """Append a message to a session's transcript (SQLite + legacy JSONL)."""
+        # Write to SQLite
+        if self._db:
             try:
                 self._db.append_message(
                     session_id=session_id,
@@ -712,7 +630,7 @@ class SessionStore:
         
         # Also write legacy JSONL (keeps existing tooling working during transition)
         transcript_path = self.get_transcript_path(session_id)
-        with open(transcript_path, "a", encoding="utf-8") as f:
+        with open(transcript_path, "a") as f:
             f.write(json.dumps(message, ensure_ascii=False) + "\n")
     
     def rewrite_transcript(self, session_id: str, messages: List[Dict[str, Any]]) -> None:
@@ -739,7 +657,7 @@ class SessionStore:
         
         # JSONL: overwrite the file
         transcript_path = self.get_transcript_path(session_id)
-        with open(transcript_path, "w", encoding="utf-8") as f:
+        with open(transcript_path, "w") as f:
             for msg in messages:
                 f.write(json.dumps(msg, ensure_ascii=False) + "\n")
 
@@ -761,7 +679,7 @@ class SessionStore:
             return []
         
         messages = []
-        with open(transcript_path, "r", encoding="utf-8") as f:
+        with open(transcript_path, "r") as f:
             for line in f:
                 line = line.strip()
                 if line:

hermes_cli/__init__.py

@@ -11,5 +11,4 @@ Provides subcommands for:
 - hermes cron          - Manage cron jobs
 """
 
-__version__ = "0.2.0"
-__release_date__ = "2026.3.12"
+__version__ = "v1.0.0"

hermes_cli/auth.py

@@ -23,7 +23,6 @@ import stat
 import base64
 import hashlib
 import subprocess
-import threading
 import time
 import uuid
 import webbrowser
@@ -45,10 +44,6 @@ try:
     import fcntl
 except Exception:
     fcntl = None
-try:
-    import msvcrt
-except Exception:
-    msvcrt = None
 
 # =============================================================================
 # Constants
@@ -304,64 +299,31 @@ def _auth_lock_path() -> Path:
     return _auth_file_path().with_suffix(".lock")
 
 
-_auth_lock_holder = threading.local()
-
 @contextmanager
 def _auth_store_lock(timeout_seconds: float = AUTH_LOCK_TIMEOUT_SECONDS):
-    """Cross-process advisory lock for auth.json reads+writes.  Reentrant."""
-    # Reentrant: if this thread already holds the lock, just yield.
-    if getattr(_auth_lock_holder, "depth", 0) > 0:
-        _auth_lock_holder.depth += 1
-        try:
-            yield
-        finally:
-            _auth_lock_holder.depth -= 1
-        return
-
+    """Cross-process advisory lock for auth.json reads+writes."""
     lock_path = _auth_lock_path()
     lock_path.parent.mkdir(parents=True, exist_ok=True)
 
-    if fcntl is None and msvcrt is None:
-        _auth_lock_holder.depth = 1
-        try:
+    with lock_path.open("a+") as lock_file:
+        if fcntl is None:
             yield
-        finally:
-            _auth_lock_holder.depth = 0
-        return
+            return
 
-    # On Windows, msvcrt.locking needs the file to have content and the
-    # file pointer at position 0.  Ensure the lock file has at least 1 byte.
-    if msvcrt and (not lock_path.exists() or lock_path.stat().st_size == 0):
-        lock_path.write_text(" ", encoding="utf-8")
-
-    with lock_path.open("r+" if msvcrt else "a+") as lock_file:
         deadline = time.time() + max(1.0, timeout_seconds)
         while True:
             try:
-                if fcntl:
-                    fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-                else:
-                    lock_file.seek(0)
-                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_NBLCK, 1)
+                fcntl.flock(lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
                 break
-            except (BlockingIOError, OSError, PermissionError):
+            except BlockingIOError:
                 if time.time() >= deadline:
                     raise TimeoutError("Timed out waiting for auth store lock")
                 time.sleep(0.05)
 
-        _auth_lock_holder.depth = 1
         try:
             yield
         finally:
-            _auth_lock_holder.depth = 0
-            if fcntl:
-                fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
-            elif msvcrt:
-                try:
-                    lock_file.seek(0)
-                    msvcrt.locking(lock_file.fileno(), msvcrt.LK_UNLCK, 1)
-                except (OSError, IOError):
-                    pass
+            fcntl.flock(lock_file.fileno(), fcntl.LOCK_UN)
 
 
 def _load_auth_store(auth_file: Optional[Path] = None) -> Dict[str, Any]:
@@ -1094,19 +1056,6 @@ def fetch_nous_models(
                 continue
             model_ids.append(mid)
 
-    # Sort: prefer opus > pro > haiku/flash > sonnet (sonnet is cheap/fast,
-    # users who want the best model should see opus first).
-    def _model_priority(mid: str) -> tuple:
-        low = mid.lower()
-        if "opus" in low:
-            return (0, mid)
-        if "pro" in low and "sonnet" not in low:
-            return (1, mid)
-        if "sonnet" in low:
-            return (3, mid)
-        return (2, mid)
-
-    model_ids.sort(key=_model_priority)
     return list(dict.fromkeys(model_ids))
 
 
@@ -1671,20 +1620,17 @@ def _prompt_model_selection(model_ids: List[str], current_model: str = "") -> Op
 
 
 def _save_model_choice(model_id: str) -> None:
-    """Save the selected model to config.yaml (single source of truth).
-
-    The model is stored in config.yaml only — NOT in .env.  This avoids
-    conflicts in multi-agent setups where env vars would stomp each other.
-    """
-    from hermes_cli.config import save_config, load_config
+    """Save the selected model to config.yaml and .env."""
+    from hermes_cli.config import save_config, load_config, save_env_value
 
     config = load_config()
-    # Always use dict format so provider/base_url can be stored alongside
+    # Handle both string and dict model formats
     if isinstance(config.get("model"), dict):
         config["model"]["default"] = model_id
     else:
-        config["model"] = {"default": model_id}
+        config["model"] = model_id
     save_config(config)
+    save_env_value("LLM_MODEL", model_id)
 
 
 def login_command(args) -> None:

hermes_cli/banner.py

@@ -36,33 +36,11 @@ def cprint(text: str):
     _pt_print(_PT_ANSI(text))
 
 
-# =========================================================================
-# Skin-aware color helpers
-# =========================================================================
-
-def _skin_color(key: str, fallback: str) -> str:
-    """Get a color from the active skin, or return fallback."""
-    try:
-        from hermes_cli.skin_engine import get_active_skin
-        return get_active_skin().get_color(key, fallback)
-    except Exception:
-        return fallback
-
-
-def _skin_branding(key: str, fallback: str) -> str:
-    """Get a branding string from the active skin, or return fallback."""
-    try:
-        from hermes_cli.skin_engine import get_active_skin
-        return get_active_skin().get_branding(key, fallback)
-    except Exception:
-        return fallback
-
-
 # =========================================================================
 # ASCII Art & Branding
 # =========================================================================
 
-from hermes_cli import __version__ as VERSION, __release_date__ as RELEASE_DATE
+from hermes_cli import __version__ as VERSION
 
 HERMES_AGENT_LOGO = """[bold #FFD700]██╗  ██╗███████╗██████╗ ███╗   ███╗███████╗███████╗       █████╗  ██████╗ ███████╗███╗   ██╗████████╗[/]
 [bold #FFD700]██║  ██║██╔════╝██╔══██╗████╗ ████║██╔════╝██╔════╝      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝[/]
@@ -239,24 +217,18 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
     layout_table.add_column("left", justify="center")
     layout_table.add_column("right", justify="left")
 
-    # Resolve skin colors once for the entire banner
-    accent = _skin_color("banner_accent", "#FFBF00")
-    dim = _skin_color("banner_dim", "#B8860B")
-    text = _skin_color("banner_text", "#FFF8DC")
-    session_color = _skin_color("session_border", "#8B8682")
-
     left_lines = ["", HERMES_CADUCEUS, ""]
     model_short = model.split("/")[-1] if "/" in model else model
     if len(model_short) > 28:
         model_short = model_short[:25] + "..."
-    ctx_str = f" [dim {dim}]·[/] [dim {dim}]{_format_context_length(context_length)} context[/]" if context_length else ""
-    left_lines.append(f"[{accent}]{model_short}[/]{ctx_str} [dim {dim}]·[/] [dim {dim}]Nous Research[/]")
-    left_lines.append(f"[dim {dim}]{cwd}[/]")
+    ctx_str = f" [dim #B8860B]·[/] [dim #B8860B]{_format_context_length(context_length)} context[/]" if context_length else ""
+    left_lines.append(f"[#FFBF00]{model_short}[/]{ctx_str} [dim #B8860B]·[/] [dim #B8860B]Nous Research[/]")
+    left_lines.append(f"[dim #B8860B]{cwd}[/]")
     if session_id:
-        left_lines.append(f"[dim {session_color}]Session: {session_id}[/]")
+        left_lines.append(f"[dim #8B8682]Session: {session_id}[/]")
     left_content = "\n".join(left_lines)
 
-    right_lines = [f"[bold {accent}]Available Tools[/]"]
+    right_lines = ["[bold #FFBF00]Available Tools[/]"]
     toolsets_dict: Dict[str, list] = {}
 
     for tool in tools:
@@ -284,7 +256,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
             if name in disabled_tools:
                 colored_names.append(f"[red]{name}[/]")
             else:
-                colored_names.append(f"[{text}]{name}[/]")
+                colored_names.append(f"[#FFF8DC]{name}[/]")
 
         tools_str = ", ".join(colored_names)
         if len(", ".join(sorted(tool_names))) > 45:
@@ -303,7 +275,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
                 elif name in disabled_tools:
                     colored_names.append(f"[red]{name}[/]")
                 else:
-                    colored_names.append(f"[{text}]{name}[/]")
+                    colored_names.append(f"[#FFF8DC]{name}[/]")
             tools_str = ", ".join(colored_names)
 
         right_lines.append(f"[dim #B8860B]{toolset}:[/] {tools_str}")
@@ -334,7 +306,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
                 )
 
     right_lines.append("")
-    right_lines.append(f"[bold {accent}]Available Skills[/]")
+    right_lines.append("[bold #FFBF00]Available Skills[/]")
     skills_by_category = get_available_skills()
     total_skills = sum(len(s) for s in skills_by_category.values())
 
@@ -348,9 +320,9 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
                 skills_str = ", ".join(skill_names)
             if len(skills_str) > 50:
                 skills_str = skills_str[:47] + "..."
-            right_lines.append(f"[dim {dim}]{category}:[/] [{text}]{skills_str}[/]")
+            right_lines.append(f"[dim #B8860B]{category}:[/] [#FFF8DC]{skills_str}[/]")
     else:
-        right_lines.append(f"[dim {dim}]No skills installed[/]")
+        right_lines.append("[dim #B8860B]No skills installed[/]")
 
     right_lines.append("")
     mcp_connected = sum(1 for s in mcp_status if s["connected"]) if mcp_status else 0
@@ -358,7 +330,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
     if mcp_connected:
         summary_parts.append(f"{mcp_connected} MCP servers")
     summary_parts.append("/help for commands")
-    right_lines.append(f"[dim {dim}]{' · '.join(summary_parts)}[/]")
+    right_lines.append(f"[dim #B8860B]{' · '.join(summary_parts)}[/]")
 
     # Update check — show if behind origin/main
     try:
@@ -375,13 +347,10 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
     right_content = "\n".join(right_lines)
     layout_table.add_row(left_content, right_content)
 
-    agent_name = _skin_branding("agent_name", "Hermes Agent")
-    title_color = _skin_color("banner_title", "#FFD700")
-    border_color = _skin_color("banner_border", "#CD7F32")
     outer_panel = Panel(
         layout_table,
-        title=f"[bold {title_color}]{agent_name} v{VERSION} ({RELEASE_DATE})[/]",
-        border_style=border_color,
+        title=f"[bold #FFD700]Hermes Agent {VERSION}[/]",
+        border_style="#CD7F32",
         padding=(0, 2),
     )
 

hermes_cli/callbacks.py

@@ -105,14 +105,10 @@ def approval_callback(cli, command: str, description: str) -> str:
     """Prompt for dangerous command approval through the TUI.
 
     Shows a selection UI with choices: once / session / always / deny.
-    When the command is longer than 70 characters, a "view" option is
-    included so the user can reveal the full text before deciding.
     """
     timeout = 60
     response_queue = queue.Queue()
     choices = ["once", "session", "always", "deny"]
-    if len(command) > 70:
-        choices.append("view")
 
     cli._approval_state = {
         "command": command,

hermes_cli/checklist.py

@@ -1,135 +0,0 @@
-"""Shared curses-based multi-select checklist for Hermes CLI.
-
-Used by both ``hermes tools`` and ``hermes skills`` to present a
-toggleable list of items.  Falls back to a numbered text UI when
-curses is unavailable (Windows without curses, piped stdin, etc.).
-"""
-
-from typing import List, Set
-
-from hermes_cli.colors import Colors, color
-
-
-def curses_checklist(
-    title: str,
-    items: List[str],
-    pre_selected: Set[int],
-) -> Set[int]:
-    """Multi-select checklist.  Returns set of **selected** indices.
-
-    Args:
-        title: Header text shown at the top of the checklist.
-        items: Display labels for each row.
-        pre_selected: Indices that start checked.
-
-    Returns:
-        The indices the user confirmed as checked.  On cancel (ESC/q),
-        returns ``pre_selected`` unchanged.
-    """
-    try:
-        import curses
-        selected = set(pre_selected)
-        result = [None]
-
-        def _ui(stdscr):
-            curses.curs_set(0)
-            if curses.has_colors():
-                curses.start_color()
-                curses.use_default_colors()
-                curses.init_pair(1, curses.COLOR_GREEN, -1)
-                curses.init_pair(2, curses.COLOR_YELLOW, -1)
-                curses.init_pair(3, 8, -1)  # dim gray
-            cursor = 0
-            scroll_offset = 0
-
-            while True:
-                stdscr.clear()
-                max_y, max_x = stdscr.getmaxyx()
-
-                # Header
-                try:
-                    hattr = curses.A_BOLD | (curses.color_pair(2) if curses.has_colors() else 0)
-                    stdscr.addnstr(0, 0, title, max_x - 1, hattr)
-                    stdscr.addnstr(
-                        1, 0,
-                        "  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel",
-                        max_x - 1, curses.A_DIM,
-                    )
-                except curses.error:
-                    pass
-
-                # Scrollable item list
-                visible_rows = max_y - 3
-                if cursor < scroll_offset:
-                    scroll_offset = cursor
-                elif cursor >= scroll_offset + visible_rows:
-                    scroll_offset = cursor - visible_rows + 1
-
-                for draw_i, i in enumerate(
-                    range(scroll_offset, min(len(items), scroll_offset + visible_rows))
-                ):
-                    y = draw_i + 3
-                    if y >= max_y - 1:
-                        break
-                    check = "✓" if i in selected else " "
-                    arrow = "→" if i == cursor else " "
-                    line = f" {arrow} [{check}] {items[i]}"
-
-                    attr = curses.A_NORMAL
-                    if i == cursor:
-                        attr = curses.A_BOLD
-                        if curses.has_colors():
-                            attr |= curses.color_pair(1)
-                    try:
-                        stdscr.addnstr(y, 0, line, max_x - 1, attr)
-                    except curses.error:
-                        pass
-
-                stdscr.refresh()
-                key = stdscr.getch()
-
-                if key in (curses.KEY_UP, ord("k")):
-                    cursor = (cursor - 1) % len(items)
-                elif key in (curses.KEY_DOWN, ord("j")):
-                    cursor = (cursor + 1) % len(items)
-                elif key == ord(" "):
-                    selected.symmetric_difference_update({cursor})
-                elif key in (curses.KEY_ENTER, 10, 13):
-                    result[0] = set(selected)
-                    return
-                elif key in (27, ord("q")):
-                    result[0] = set(pre_selected)
-                    return
-
-        curses.wrapper(_ui)
-        return result[0] if result[0] is not None else set(pre_selected)
-
-    except Exception:
-        pass  # fall through to numbered fallback
-
-    # ── Numbered text fallback ────────────────────────────────────────────
-    selected = set(pre_selected)
-    print(color(f"\n  {title}", Colors.YELLOW))
-    print(color("  Toggle by number, Enter to confirm.\n", Colors.DIM))
-
-    while True:
-        for i, label in enumerate(items):
-            check = "✓" if i in selected else " "
-            print(f"    {i + 1:3}. [{check}] {label}")
-        print()
-
-        try:
-            raw = input(color("  Number to toggle, 's' to save, 'q' to cancel: ", Colors.DIM)).strip()
-        except (KeyboardInterrupt, EOFError):
-            return set(pre_selected)
-
-        if raw.lower() == "s" or raw == "":
-            return selected
-        if raw.lower() == "q":
-            return set(pre_selected)
-        try:
-            idx = int(raw) - 1
-            if 0 <= idx < len(items):
-                selected.symmetric_difference_update({idx})
-        except ValueError:
-            print(color("  Invalid input", Colors.DIM))

hermes_cli/claw.py

@@ -1,296 +0,0 @@
-"""hermes claw — OpenClaw migration commands.
-
-Usage:
-    hermes claw migrate              # Interactive migration from ~/.openclaw
-    hermes claw migrate --dry-run    # Preview what would be migrated
-    hermes claw migrate --preset full --overwrite  # Full migration, overwrite conflicts
-"""
-
-import importlib.util
-import logging
-import sys
-from pathlib import Path
-
-from hermes_cli.config import get_hermes_home, get_config_path, load_config, save_config
-from hermes_cli.setup import (
-    Colors,
-    color,
-    print_header,
-    print_info,
-    print_success,
-    print_warning,
-    print_error,
-    prompt_yes_no,
-    prompt_choice,
-)
-
-logger = logging.getLogger(__name__)
-
-PROJECT_ROOT = Path(__file__).parent.parent.resolve()
-
-_OPENCLAW_SCRIPT = (
-    PROJECT_ROOT
-    / "optional-skills"
-    / "migration"
-    / "openclaw-migration"
-    / "scripts"
-    / "openclaw_to_hermes.py"
-)
-
-# Fallback: user may have installed the skill from the Hub
-_OPENCLAW_SCRIPT_INSTALLED = (
-    get_hermes_home()
-    / "skills"
-    / "migration"
-    / "openclaw-migration"
-    / "scripts"
-    / "openclaw_to_hermes.py"
-)
-
-
-def _find_migration_script() -> Path | None:
-    """Find the openclaw_to_hermes.py script in known locations."""
-    for candidate in [_OPENCLAW_SCRIPT, _OPENCLAW_SCRIPT_INSTALLED]:
-        if candidate.exists():
-            return candidate
-    return None
-
-
-def _load_migration_module(script_path: Path):
-    """Dynamically load the migration script as a module."""
-    spec = importlib.util.spec_from_file_location("openclaw_to_hermes", script_path)
-    if spec is None or spec.loader is None:
-        return None
-    mod = importlib.util.module_from_spec(spec)
-    # Register in sys.modules so @dataclass can resolve the module
-    # (Python 3.11+ requires this for dynamically loaded modules)
-    sys.modules[spec.name] = mod
-    try:
-        spec.loader.exec_module(mod)
-    except Exception:
-        sys.modules.pop(spec.name, None)
-        raise
-    return mod
-
-
-def claw_command(args):
-    """Route hermes claw subcommands."""
-    action = getattr(args, "claw_action", None)
-
-    if action == "migrate":
-        _cmd_migrate(args)
-    else:
-        print("Usage: hermes claw migrate [options]")
-        print()
-        print("Commands:")
-        print("  migrate          Migrate settings from OpenClaw to Hermes")
-        print()
-        print("Run 'hermes claw migrate --help' for migration options.")
-
-
-def _cmd_migrate(args):
-    """Run the OpenClaw → Hermes migration."""
-    source_dir = Path(getattr(args, "source", None) or Path.home() / ".openclaw")
-    dry_run = getattr(args, "dry_run", False)
-    preset = getattr(args, "preset", "full")
-    overwrite = getattr(args, "overwrite", False)
-    migrate_secrets = getattr(args, "migrate_secrets", False)
-    workspace_target = getattr(args, "workspace_target", None)
-    skill_conflict = getattr(args, "skill_conflict", "skip")
-
-    # If using the "full" preset, secrets are included by default
-    if preset == "full":
-        migrate_secrets = True
-
-    print()
-    print(
-        color(
-            "┌─────────────────────────────────────────────────────────┐",
-            Colors.MAGENTA,
-        )
-    )
-    print(
-        color(
-            "│          ⚕ Hermes — OpenClaw Migration                 │",
-            Colors.MAGENTA,
-        )
-    )
-    print(
-        color(
-            "└─────────────────────────────────────────────────────────┘",
-            Colors.MAGENTA,
-        )
-    )
-
-    # Check source directory
-    if not source_dir.is_dir():
-        print()
-        print_error(f"OpenClaw directory not found: {source_dir}")
-        print_info("Make sure your OpenClaw installation is at the expected path.")
-        print_info(f"You can specify a custom path: hermes claw migrate --source /path/to/.openclaw")
-        return
-
-    # Find the migration script
-    script_path = _find_migration_script()
-    if not script_path:
-        print()
-        print_error("Migration script not found.")
-        print_info("Expected at one of:")
-        print_info(f"  {_OPENCLAW_SCRIPT}")
-        print_info(f"  {_OPENCLAW_SCRIPT_INSTALLED}")
-        print_info("Make sure the openclaw-migration skill is installed.")
-        return
-
-    # Show what we're doing
-    hermes_home = get_hermes_home()
-    print()
-    print_header("Migration Settings")
-    print_info(f"Source:      {source_dir}")
-    print_info(f"Target:      {hermes_home}")
-    print_info(f"Preset:      {preset}")
-    print_info(f"Mode:        {'dry run (preview only)' if dry_run else 'execute'}")
-    print_info(f"Overwrite:   {'yes' if overwrite else 'no (skip conflicts)'}")
-    print_info(f"Secrets:     {'yes (allowlisted only)' if migrate_secrets else 'no'}")
-    if skill_conflict != "skip":
-        print_info(f"Skill conflicts: {skill_conflict}")
-    if workspace_target:
-        print_info(f"Workspace:   {workspace_target}")
-    print()
-
-    # For execute mode (non-dry-run), confirm unless --yes was passed
-    if not dry_run and not getattr(args, "yes", False):
-        if not prompt_yes_no("Proceed with migration?", default=True):
-            print_info("Migration cancelled.")
-            return
-
-    # Ensure config.yaml exists before migration tries to read it
-    config_path = get_config_path()
-    if not config_path.exists():
-        save_config(load_config())
-
-    # Load and run the migration
-    try:
-        mod = _load_migration_module(script_path)
-        if mod is None:
-            print_error("Could not load migration script.")
-            return
-
-        selected = mod.resolve_selected_options(None, None, preset=preset)
-        ws_target = Path(workspace_target).resolve() if workspace_target else None
-
-        migrator = mod.Migrator(
-            source_root=source_dir.resolve(),
-            target_root=hermes_home.resolve(),
-            execute=not dry_run,
-            workspace_target=ws_target,
-            overwrite=overwrite,
-            migrate_secrets=migrate_secrets,
-            output_dir=None,
-            selected_options=selected,
-            preset_name=preset,
-            skill_conflict_mode=skill_conflict,
-        )
-        report = migrator.migrate()
-    except Exception as e:
-        print()
-        print_error(f"Migration failed: {e}")
-        logger.debug("OpenClaw migration error", exc_info=True)
-        return
-
-    # Print results
-    _print_migration_report(report, dry_run)
-
-
-def _print_migration_report(report: dict, dry_run: bool):
-    """Print a formatted migration report."""
-    summary = report.get("summary", {})
-    migrated = summary.get("migrated", 0)
-    skipped = summary.get("skipped", 0)
-    conflicts = summary.get("conflict", 0)
-    errors = summary.get("error", 0)
-    total = migrated + skipped + conflicts + errors
-
-    print()
-    if dry_run:
-        print_header("Dry Run Results")
-        print_info("No files were modified. This is a preview of what would happen.")
-    else:
-        print_header("Migration Results")
-
-    print()
-
-    # Detailed items
-    items = report.get("items", [])
-    if items:
-        # Group by status
-        migrated_items = [i for i in items if i.get("status") == "migrated"]
-        skipped_items = [i for i in items if i.get("status") == "skipped"]
-        conflict_items = [i for i in items if i.get("status") == "conflict"]
-        error_items = [i for i in items if i.get("status") == "error"]
-
-        if migrated_items:
-            label = "Would migrate" if dry_run else "Migrated"
-            print(color(f"  ✓ {label}:", Colors.GREEN))
-            for item in migrated_items:
-                kind = item.get("kind", "unknown")
-                dest = item.get("destination", "")
-                if dest:
-                    dest_short = str(dest).replace(str(Path.home()), "~")
-                    print(f"      {kind:<22s} → {dest_short}")
-                else:
-                    print(f"      {kind}")
-            print()
-
-        if conflict_items:
-            print(color(f"  ⚠ Conflicts (skipped — use --overwrite to force):", Colors.YELLOW))
-            for item in conflict_items:
-                kind = item.get("kind", "unknown")
-                reason = item.get("reason", "already exists")
-                print(f"      {kind:<22s}  {reason}")
-            print()
-
-        if skipped_items:
-            print(color(f"  ─ Skipped:", Colors.DIM))
-            for item in skipped_items:
-                kind = item.get("kind", "unknown")
-                reason = item.get("reason", "")
-                print(f"      {kind:<22s}  {reason}")
-            print()
-
-        if error_items:
-            print(color(f"  ✗ Errors:", Colors.RED))
-            for item in error_items:
-                kind = item.get("kind", "unknown")
-                reason = item.get("reason", "unknown error")
-                print(f"      {kind:<22s}  {reason}")
-            print()
-
-    # Summary line
-    parts = []
-    if migrated:
-        action = "would migrate" if dry_run else "migrated"
-        parts.append(f"{migrated} {action}")
-    if conflicts:
-        parts.append(f"{conflicts} conflict(s)")
-    if skipped:
-        parts.append(f"{skipped} skipped")
-    if errors:
-        parts.append(f"{errors} error(s)")
-
-    if parts:
-        print_info(f"Summary: {', '.join(parts)}")
-    else:
-        print_info("Nothing to migrate.")
-
-    # Output directory
-    output_dir = report.get("output_dir")
-    if output_dir:
-        print_info(f"Full report saved to: {output_dir}")
-
-    if dry_run:
-        print()
-        print_info("To execute the migration, run without --dry-run:")
-        print_info(f"  hermes claw migrate --preset {report.get('preset', 'full')}")
-    elif migrated:
-        print()
-        print_success("Migration complete!")

hermes_cli/clipboard.py

@@ -254,7 +254,6 @@ def _wayland_save(dest: Path) -> bool:
             )
 
         if not dest.exists() or dest.stat().st_size == 0:
-            dest.unlink(missing_ok=True)
             return False
 
         # BMP needs conversion to PNG (common in WSLg where only BMP
@@ -286,27 +285,20 @@ def _convert_to_png(path: Path) -> bool:
         logger.debug("Pillow BMP→PNG conversion failed: %s", e)
 
     # Fall back to ImageMagick convert
-    tmp = path.with_suffix(".bmp")
     try:
+        tmp = path.with_suffix(".bmp")
         path.rename(tmp)
         r = subprocess.run(
             ["convert", str(tmp), "png:" + str(path)],
             capture_output=True, timeout=5,
         )
+        tmp.unlink(missing_ok=True)
         if r.returncode == 0 and path.exists() and path.stat().st_size > 0:
-            tmp.unlink(missing_ok=True)
             return True
-        else:
-            # Convert failed — restore the original file
-            tmp.rename(path)
     except FileNotFoundError:
         logger.debug("ImageMagick not installed — cannot convert BMP to PNG")
-        if tmp.exists() and not path.exists():
-            tmp.rename(path)
     except Exception as e:
         logger.debug("ImageMagick BMP→PNG conversion failed: %s", e)
-        if tmp.exists() and not path.exists():
-            tmp.rename(path)
 
     # Can't convert — BMP is still usable as-is for most APIs
     return path.exists() and path.stat().st_size > 0

hermes_cli/codex_models.py

@@ -47,7 +47,7 @@ def _fetch_models_from_api(access_token: str) -> List[str]:
         if item.get("supported_in_api") is False:
             continue
         visibility = item.get("visibility", "")
-        if isinstance(visibility, str) and visibility.strip().lower() in ("hide", "hidden"):
+        if isinstance(visibility, str) and visibility.strip().lower() == "hide":
             continue
         priority = item.get("priority")
         rank = int(priority) if isinstance(priority, (int, float)) else 10_000
@@ -94,10 +94,12 @@ def _read_cache_models(codex_home: Path) -> List[str]:
             if not isinstance(slug, str) or not slug.strip():
                 continue
             slug = slug.strip()
+            if "codex" not in slug.lower():
+                continue
             if item.get("supported_in_api") is False:
                 continue
             visibility = item.get("visibility")
-            if isinstance(visibility, str) and visibility.strip().lower() in ("hide", "hidden"):
+            if isinstance(visibility, str) and visibility.strip().lower() == "hidden":
                 continue
             priority = item.get("priority")
             rank = int(priority) if isinstance(priority, (int, float)) else 10_000

hermes_cli/commands.py

@@ -13,55 +13,35 @@ from typing import Any
 from prompt_toolkit.completion import Completer, Completion
 
 
-# Commands organized by category for better help display
-COMMANDS_BY_CATEGORY = {
-    "Session": {
-        "/new": "Start a new conversation (reset history)",
-        "/reset": "Reset conversation only (keep screen)",
-        "/clear": "Clear screen and reset conversation (fresh start)",
-        "/history": "Show conversation history",
-        "/save": "Save the current conversation",
-        "/retry": "Retry the last message (resend to agent)",
-        "/undo": "Remove the last user/assistant exchange",
-        "/title": "Set a title for the current session (usage: /title My Session Name)",
-        "/compress": "Manually compress conversation context (flush memories + summarize)",
-        "/rollback": "List or restore filesystem checkpoints (usage: /rollback [number])",
-        "/background": "Run a prompt in the background (usage: /background <prompt>)",
-    },
-    "Configuration": {
-        "/config": "Show current configuration",
-        "/model": "Show or change the current model",
-        "/provider": "Show available providers and current provider",
-        "/prompt": "View/set custom system prompt",
-        "/personality": "Set a predefined personality",
-        "/verbose": "Cycle tool progress display: off → new → all → verbose",
-        "/reasoning": "Manage reasoning effort and display (usage: /reasoning [level|show|hide])",
-        "/skin": "Show or change the display skin/theme",
-    },
-    "Tools & Skills": {
-        "/tools": "List available tools",
-        "/toolsets": "List available toolsets",
-        "/skills": "Search, install, inspect, or manage skills from online registries",
-        "/cron": "Manage scheduled tasks (list, add, remove)",
-        "/reload-mcp": "Reload MCP servers from config.yaml",
-    },
-    "Info": {
-        "/help": "Show this help message",
-        "/usage": "Show token usage for the current session",
-        "/insights": "Show usage insights and analytics (last 30 days)",
-        "/platforms": "Show gateway/messaging platform status",
-        "/paste": "Check clipboard for an image and attach it",
-    },
-    "Exit": {
-        "/quit": "Exit the CLI (also: /exit, /q)",
-    },
+COMMANDS = {
+    "/help": "Show this help message",
+    "/tools": "List available tools",
+    "/toolsets": "List available toolsets",
+    "/model": "Show or change the current model",
+    "/provider": "Show available providers and current provider",
+    "/prompt": "View/set custom system prompt",
+    "/personality": "Set a predefined personality",
+    "/clear": "Clear screen and reset conversation (fresh start)",
+    "/history": "Show conversation history",
+    "/new": "Start a new conversation (reset history)",
+    "/reset": "Reset conversation only (keep screen)",
+    "/retry": "Retry the last message (resend to agent)",
+    "/undo": "Remove the last user/assistant exchange",
+    "/save": "Save the current conversation",
+    "/config": "Show current configuration",
+    "/cron": "Manage scheduled tasks (list, add, remove)",
+    "/skills": "Search, install, inspect, or manage skills from online registries",
+    "/platforms": "Show gateway/messaging platform status",
+    "/verbose": "Cycle tool progress display: off → new → all → verbose",
+    "/compress": "Manually compress conversation context (flush memories + summarize)",
+    "/title": "Set a title for the current session (usage: /title My Session Name)",
+    "/usage": "Show token usage for the current session",
+    "/insights": "Show usage insights and analytics (last 30 days)",
+    "/paste": "Check clipboard for an image and attach it",
+    "/reload-mcp": "Reload MCP servers from config.yaml",
+    "/quit": "Exit the CLI (also: /exit, /q)",
 }
 
-# Flat dict for backwards compatibility and autocomplete
-COMMANDS = {}
-for category_commands in COMMANDS_BY_CATEGORY.values():
-    COMMANDS.update(category_commands)
-
 
 class SlashCommandCompleter(Completer):
     """Autocomplete for built-in slash commands and optional skill commands."""

hermes_cli/config.py

@@ -14,10 +14,8 @@ This module provides:
 
 import os
 import platform
-import stat
-import subprocess
 import sys
-import tempfile
+import subprocess
 from pathlib import Path
 from typing import Dict, Any, Optional, List, Tuple
 
@@ -48,32 +46,13 @@ def get_project_root() -> Path:
     """Get the project installation directory."""
     return Path(__file__).parent.parent.resolve()
 
-def _secure_dir(path):
-    """Set directory to owner-only access (0700). No-op on Windows."""
-    try:
-        os.chmod(path, 0o700)
-    except (OSError, NotImplementedError):
-        pass
-
-
-def _secure_file(path):
-    """Set file to owner-only read/write (0600). No-op on Windows."""
-    try:
-        if os.path.exists(str(path)):
-            os.chmod(path, 0o600)
-    except (OSError, NotImplementedError):
-        pass
-
-
 def ensure_hermes_home():
-    """Ensure ~/.hermes directory structure exists with secure permissions."""
+    """Ensure ~/.hermes directory structure exists."""
     home = get_hermes_home()
-    home.mkdir(parents=True, exist_ok=True)
-    _secure_dir(home)
-    for subdir in ("cron", "sessions", "logs", "memories"):
-        d = home / subdir
-        d.mkdir(parents=True, exist_ok=True)
-        _secure_dir(d)
+    (home / "cron").mkdir(parents=True, exist_ok=True)
+    (home / "sessions").mkdir(parents=True, exist_ok=True)
+    (home / "logs").mkdir(parents=True, exist_ok=True)
+    (home / "memories").mkdir(parents=True, exist_ok=True)
 
 
 # =============================================================================
@@ -83,9 +62,7 @@ def ensure_hermes_home():
 DEFAULT_CONFIG = {
     "model": "anthropic/claude-opus-4.6",
     "toolsets": ["hermes-cli"],
-    "agent": {
-        "max_turns": 90,
-    },
+    "max_turns": 100,
     
     "terminal": {
         "backend": "local",
@@ -100,76 +77,21 @@ DEFAULT_CONFIG = {
         "container_memory": 5120,       # MB (default 5GB)
         "container_disk": 51200,        # MB (default 50GB)
         "container_persistent": True,   # Persist filesystem across sessions
-        # Docker volume mounts — share host directories with the container.
-        # Each entry is "host_path:container_path" (standard Docker -v syntax).
-        # Example: ["/home/user/projects:/workspace/projects", "/data:/data"]
-        "docker_volumes": [],
     },
     
     "browser": {
         "inactivity_timeout": 120,
-        "record_sessions": False,  # Auto-record browser sessions as WebM videos
-    },
-    
-    # Filesystem checkpoints — automatic snapshots before destructive file ops.
-    # When enabled, the agent takes a snapshot of the working directory once per
-    # conversation turn (on first write_file/patch call).  Use /rollback to restore.
-    "checkpoints": {
-        "enabled": False,
-        "max_snapshots": 50,  # Max checkpoints to keep per directory
     },
     
     "compression": {
         "enabled": True,
         "threshold": 0.85,
         "summary_model": "google/gemini-3-flash-preview",
-        "summary_provider": "auto",
-    },
-    
-    # Auxiliary model config — provider:model for each side task.
-    # Format: provider is the provider name, model is the model slug.
-    # "auto" for provider = auto-detect best available provider.
-    # Empty model = use provider's default auxiliary model.
-    # All tasks fall back to openrouter:google/gemini-3-flash-preview if
-    # the configured provider is unavailable.
-    "auxiliary": {
-        "vision": {
-            "provider": "auto",    # auto | openrouter | nous | codex | custom
-            "model": "",           # e.g. "google/gemini-2.5-flash", "gpt-4o"
-        },
-        "web_extract": {
-            "provider": "auto",
-            "model": "",
-        },
-        "compression": {
-            "provider": "auto",
-            "model": "",
-        },
-        "session_search": {
-            "provider": "auto",
-            "model": "",
-        },
-        "skills_hub": {
-            "provider": "auto",
-            "model": "",
-        },
-        "mcp": {
-            "provider": "auto",
-            "model": "",
-        },
-        "flush_memories": {
-            "provider": "auto",
-            "model": "",
-        },
     },
     
     "display": {
         "compact": False,
         "personality": "kawaii",
-        "resume_display": "full",
-        "bell_on_complete": False,
-        "show_reasoning": False,
-        "skin": "default",
     },
     
     # Text-to-speech configuration
@@ -208,16 +130,7 @@ DEFAULT_CONFIG = {
         "memory_char_limit": 2200,   # ~800 tokens at 2.75 chars/token
         "user_char_limit": 1375,     # ~500 tokens at 2.75 chars/token
     },
-
-    # Subagent delegation — override the provider:model used by delegate_task
-    # so child agents can run on a different (cheaper/faster) provider and model.
-    # Uses the same runtime provider resolution as CLI/gateway startup, so all
-    # configured providers (OpenRouter, Nous, Z.ai, Kimi, etc.) are supported.
-    "delegation": {
-        "model": "",       # e.g. "google/gemini-3-flash-preview" (empty = inherit parent model)
-        "provider": "",    # e.g. "openrouter" (empty = inherit parent provider + credentials)
-    },
-
+    
     # Ephemeral prefill messages file — JSON list of {role, content} dicts
     # injected at the start of every API call for few-shot priming.
     # Never saved to sessions, logs, or trajectories.
@@ -232,23 +145,11 @@ DEFAULT_CONFIG = {
     # Empty string means use server-local time.
     "timezone": "",
 
-    # Discord platform settings (gateway mode)
-    "discord": {
-        "require_mention": True,       # Require @mention to respond in server channels
-        "free_response_channels": "",  # Comma-separated channel IDs where bot responds without mention
-    },
-
     # Permanently allowed dangerous command patterns (added via "always" approval)
     "command_allowlist": [],
-    # User-defined quick commands that bypass the agent loop (type: exec only)
-    "quick_commands": {},
-    # Custom personalities — add your own entries here
-    # Supports string format: {"name": "system prompt"}
-    # Or dict format: {"name": {"description": "...", "system_prompt": "...", "tone": "...", "style": "..."}}
-    "personalities": {},
 
     # Config schema version - bump this when adding new required fields
-    "_config_version": 7,
+    "_config_version": 5,
 }
 
 # =============================================================================
@@ -273,14 +174,6 @@ REQUIRED_ENV_VARS = {}
 # Optional environment variables that enhance functionality
 OPTIONAL_ENV_VARS = {
     # ── Provider (handled in provider selection, not shown in checklists) ──
-    "NOUS_BASE_URL": {
-        "description": "Nous Portal base URL override",
-        "prompt": "Nous Portal base URL (leave empty for default)",
-        "url": None,
-        "password": False,
-        "category": "provider",
-        "advanced": True,
-    },
     "OPENROUTER_API_KEY": {
         "description": "OpenRouter API key (for vision, web scraping helpers, and MoA)",
         "prompt": "OpenRouter API key",
@@ -491,18 +384,14 @@ OPTIONAL_ENV_VARS = {
         "category": "messaging",
     },
     "SLACK_BOT_TOKEN": {
-        "description": "Slack bot token (xoxb-). Get from OAuth & Permissions after installing your app. "
-                       "Required scopes: chat:write, app_mentions:read, channels:history, groups:history, "
-                       "im:history, im:read, im:write, users:read, files:write",
+        "description": "Slack bot integration",
         "prompt": "Slack Bot Token (xoxb-...)",
         "url": "https://api.slack.com/apps",
         "password": True,
         "category": "messaging",
     },
     "SLACK_APP_TOKEN": {
-        "description": "Slack app-level token (xapp-) for Socket Mode. Get from Basic Information → "
-                       "App-Level Tokens. Also ensure Event Subscriptions include: message.im, "
-                       "message.channels, message.groups, app_mention",
+        "description": "Slack Socket Mode connection",
         "prompt": "Slack App Token (xapp-...)",
         "url": "https://api.slack.com/apps",
         "password": True,
@@ -533,7 +422,7 @@ OPTIONAL_ENV_VARS = {
         "category": "setting",
     },
     "HERMES_MAX_ITERATIONS": {
-        "description": "Maximum tool-calling iterations per conversation (default: 90)",
+        "description": "Maximum tool-calling iterations per conversation (default: 60)",
         "prompt": "Max iterations",
         "url": None,
         "password": False,
@@ -834,23 +723,6 @@ def _deep_merge(base: dict, override: dict) -> dict:
     return result
 
 
-def _normalize_max_turns_config(config: Dict[str, Any]) -> Dict[str, Any]:
-    """Normalize legacy root-level max_turns into agent.max_turns."""
-    config = dict(config)
-    agent_config = dict(config.get("agent") or {})
-
-    if "max_turns" in config and "max_turns" not in agent_config:
-        agent_config["max_turns"] = config["max_turns"]
-
-    if "max_turns" not in agent_config:
-        agent_config["max_turns"] = DEFAULT_CONFIG["agent"]["max_turns"]
-
-    config["agent"] = agent_config
-    config.pop("max_turns", None)
-    return config
-
-
-
 def load_config() -> Dict[str, Any]:
     """Load configuration from ~/.hermes/config.yaml."""
     import copy
@@ -860,77 +732,23 @@ def load_config() -> Dict[str, Any]:
     
     if config_path.exists():
         try:
-            with open(config_path, encoding="utf-8") as f:
+            with open(config_path) as f:
                 user_config = yaml.safe_load(f) or {}
-
-            if "max_turns" in user_config:
-                agent_user_config = dict(user_config.get("agent") or {})
-                if agent_user_config.get("max_turns") is None:
-                    agent_user_config["max_turns"] = user_config["max_turns"]
-                user_config["agent"] = agent_user_config
-                user_config.pop("max_turns", None)
-
+            
             config = _deep_merge(config, user_config)
         except Exception as e:
             print(f"Warning: Failed to load config: {e}")
     
-    return _normalize_max_turns_config(config)
-
-
-_COMMENTED_SECTIONS = """
-# ── Security ──────────────────────────────────────────────────────────
-# API keys, tokens, and passwords are redacted from tool output by default.
-# Set to false to see full values (useful for debugging auth issues).
-#
-# security:
-#   redact_secrets: false
-
-# ── Fallback Model ────────────────────────────────────────────────────
-# Automatic provider failover when primary is unavailable.
-# Uncomment and configure to enable. Triggers on rate limits (429),
-# overload (529), service errors (503), or connection failures.
-#
-# Supported providers:
-#   openrouter   (OPENROUTER_API_KEY)  — routes to any model
-#   openai-codex (OAuth — hermes login) — OpenAI Codex
-#   nous         (OAuth — hermes login) — Nous Portal
-#   zai          (ZAI_API_KEY)         — Z.AI / GLM
-#   kimi-coding  (KIMI_API_KEY)        — Kimi / Moonshot
-#   minimax      (MINIMAX_API_KEY)     — MiniMax
-#   minimax-cn   (MINIMAX_CN_API_KEY)  — MiniMax (China)
-#
-# For custom OpenAI-compatible endpoints, add base_url and api_key_env.
-#
-# fallback_model:
-#   provider: openrouter
-#   model: anthropic/claude-sonnet-4
-"""
+    return config
 
 
 def save_config(config: Dict[str, Any]):
     """Save configuration to ~/.hermes/config.yaml."""
-    from utils import atomic_yaml_write
-
     ensure_hermes_home()
     config_path = get_config_path()
-    normalized = _normalize_max_turns_config(config)
-
-    # Build optional commented-out sections for features that are off by
-    # default or only relevant when explicitly configured.
-    sections = []
-    sec = normalized.get("security", {})
-    if not sec or sec.get("redact_secrets") is None:
-        sections.append("security")
-    fb = normalized.get("fallback_model", {})
-    if not fb or not (fb.get("provider") and fb.get("model")):
-        sections.append("fallback")
-
-    atomic_yaml_write(
-        config_path,
-        normalized,
-        extra_content=_COMMENTED_SECTIONS if sections else None,
-    )
-    _secure_file(config_path)
+    
+    with open(config_path, 'w') as f:
+        yaml.dump(config, f, default_flow_style=False, sort_keys=False)
 
 
 def load_env() -> Dict[str, str]:
@@ -981,27 +799,8 @@ def save_env_value(key: str, value: str):
             lines[-1] += "\n"
         lines.append(f"{key}={value}\n")
     
-    fd, tmp_path = tempfile.mkstemp(dir=str(env_path.parent), suffix='.tmp', prefix='.env_')
-    try:
-        with os.fdopen(fd, 'w', **write_kw) as f:
-            f.writelines(lines)
-            f.flush()
-            os.fsync(f.fileno())
-        os.replace(tmp_path, env_path)
-    except BaseException:
-        try:
-            os.unlink(tmp_path)
-        except OSError:
-            pass
-        raise
-    _secure_file(env_path)
-
-    # Restrict .env permissions to owner-only (contains API keys)
-    if not _IS_WINDOWS:
-        try:
-            os.chmod(env_path, stat.S_IRUSR | stat.S_IWUSR)
-        except OSError:
-            pass
+    with open(env_path, 'w', **write_kw) as f:
+        f.writelines(lines)
 
 
 def get_env_value(key: str) -> Optional[str]:
@@ -1066,17 +865,9 @@ def show_config():
     print()
     print(color("◆ Model", Colors.CYAN, Colors.BOLD))
     print(f"  Model:        {config.get('model', 'not set')}")
-    print(f"  Max turns:    {config.get('agent', {}).get('max_turns', DEFAULT_CONFIG['agent']['max_turns'])}")
+    print(f"  Max turns:    {config.get('max_turns', 100)}")
     print(f"  Toolsets:     {', '.join(config.get('toolsets', ['all']))}")
     
-    # Display
-    print()
-    print(color("◆ Display", Colors.CYAN, Colors.BOLD))
-    display = config.get('display', {})
-    print(f"  Personality:  {display.get('personality', 'kawaii')}")
-    print(f"  Reasoning:    {'on' if display.get('show_reasoning', False) else 'off'}")
-    print(f"  Bell:         {'on' if display.get('bell_on_complete', False) else 'off'}")
-
     # Terminal
     print()
     print(color("◆ Terminal", Colors.CYAN, Colors.BOLD))
@@ -1121,31 +912,6 @@ def show_config():
     if enabled:
         print(f"  Threshold:    {compression.get('threshold', 0.85) * 100:.0f}%")
         print(f"  Model:        {compression.get('summary_model', 'google/gemini-3-flash-preview')}")
-        comp_provider = compression.get('summary_provider', 'auto')
-        if comp_provider != 'auto':
-            print(f"  Provider:     {comp_provider}")
-    
-    # Auxiliary models
-    auxiliary = config.get('auxiliary', {})
-    aux_tasks = {
-        "Vision":      auxiliary.get('vision', {}),
-        "Web extract": auxiliary.get('web_extract', {}),
-    }
-    has_overrides = any(
-        t.get('provider', 'auto') != 'auto' or t.get('model', '')
-        for t in aux_tasks.values()
-    )
-    if has_overrides:
-        print()
-        print(color("◆ Auxiliary Models (overrides)", Colors.CYAN, Colors.BOLD))
-        for label, task_cfg in aux_tasks.items():
-            prov = task_cfg.get('provider', 'auto')
-            mdl = task_cfg.get('model', '')
-            if prov != 'auto' or mdl:
-                parts = [f"provider={prov}"]
-                if mdl:
-                    parts.append(f"model={mdl}")
-                print(f"  {label:12s}  {', '.join(parts)}")
     
     # Messaging
     print()
@@ -1203,7 +969,7 @@ def set_config_value(key: str, value: str):
         'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN',
         'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY',
         'SUDO_PASSWORD', 'SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN',
-        'GITHUB_TOKEN', 'HONCHO_API_KEY', 'WANDB_API_KEY',
+        'GITHUB_TOKEN', 'HONCHO_API_KEY', 'NOUS_API_KEY', 'WANDB_API_KEY',
         'TINKER_API_KEY',
     ]
     
@@ -1219,7 +985,7 @@ def set_config_value(key: str, value: str):
     user_config = {}
     if config_path.exists():
         try:
-            with open(config_path, encoding="utf-8") as f:
+            with open(config_path) as f:
                 user_config = yaml.safe_load(f) or {}
         except Exception:
             user_config = {}
@@ -1247,7 +1013,7 @@ def set_config_value(key: str, value: str):
     
     # Write only user config back (not the full merged defaults)
     ensure_hermes_home()
-    with open(config_path, 'w', encoding="utf-8") as f:
+    with open(config_path, 'w') as f:
         yaml.dump(user_config, f, default_flow_style=False, sort_keys=False)
     
     # Keep .env in sync for keys that terminal_tool reads directly from env vars.

hermes_cli/curses_ui.py

@@ -1,140 +0,0 @@
-"""Shared curses-based UI components for Hermes CLI.
-
-Used by `hermes tools` and `hermes skills` for interactive checklists.
-Provides a curses multi-select with keyboard navigation, plus a
-text-based numbered fallback for terminals without curses support.
-"""
-from typing import List, Set
-
-from hermes_cli.colors import Colors, color
-
-
-def curses_checklist(
-    title: str,
-    items: List[str],
-    selected: Set[int],
-    *,
-    cancel_returns: Set[int] | None = None,
-) -> Set[int]:
-    """Curses multi-select checklist. Returns set of selected indices.
-
-    Args:
-        title: Header line displayed above the checklist.
-        items: Display labels for each row.
-        selected: Indices that start checked (pre-selected).
-        cancel_returns: Returned on ESC/q. Defaults to the original *selected*.
-    """
-    if cancel_returns is None:
-        cancel_returns = set(selected)
-
-    try:
-        import curses
-        chosen = set(selected)
-        result_holder: list = [None]
-
-        def _draw(stdscr):
-            curses.curs_set(0)
-            if curses.has_colors():
-                curses.start_color()
-                curses.use_default_colors()
-                curses.init_pair(1, curses.COLOR_GREEN, -1)
-                curses.init_pair(2, curses.COLOR_YELLOW, -1)
-                curses.init_pair(3, 8, -1)  # dim gray
-            cursor = 0
-            scroll_offset = 0
-
-            while True:
-                stdscr.clear()
-                max_y, max_x = stdscr.getmaxyx()
-
-                # Header
-                try:
-                    hattr = curses.A_BOLD
-                    if curses.has_colors():
-                        hattr |= curses.color_pair(2)
-                    stdscr.addnstr(0, 0, title, max_x - 1, hattr)
-                    stdscr.addnstr(
-                        1, 0,
-                        "  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel",
-                        max_x - 1, curses.A_DIM,
-                    )
-                except curses.error:
-                    pass
-
-                # Scrollable item list
-                visible_rows = max_y - 3
-                if cursor < scroll_offset:
-                    scroll_offset = cursor
-                elif cursor >= scroll_offset + visible_rows:
-                    scroll_offset = cursor - visible_rows + 1
-
-                for draw_i, i in enumerate(
-                    range(scroll_offset, min(len(items), scroll_offset + visible_rows))
-                ):
-                    y = draw_i + 3
-                    if y >= max_y - 1:
-                        break
-                    check = "✓" if i in chosen else " "
-                    arrow = "→" if i == cursor else " "
-                    line = f" {arrow} [{check}] {items[i]}"
-                    attr = curses.A_NORMAL
-                    if i == cursor:
-                        attr = curses.A_BOLD
-                        if curses.has_colors():
-                            attr |= curses.color_pair(1)
-                    try:
-                        stdscr.addnstr(y, 0, line, max_x - 1, attr)
-                    except curses.error:
-                        pass
-
-                stdscr.refresh()
-                key = stdscr.getch()
-
-                if key in (curses.KEY_UP, ord("k")):
-                    cursor = (cursor - 1) % len(items)
-                elif key in (curses.KEY_DOWN, ord("j")):
-                    cursor = (cursor + 1) % len(items)
-                elif key == ord(" "):
-                    chosen.symmetric_difference_update({cursor})
-                elif key in (curses.KEY_ENTER, 10, 13):
-                    result_holder[0] = set(chosen)
-                    return
-                elif key in (27, ord("q")):
-                    result_holder[0] = cancel_returns
-                    return
-
-        curses.wrapper(_draw)
-        return result_holder[0] if result_holder[0] is not None else cancel_returns
-
-    except Exception:
-        return _numbered_fallback(title, items, selected, cancel_returns)
-
-
-def _numbered_fallback(
-    title: str,
-    items: List[str],
-    selected: Set[int],
-    cancel_returns: Set[int],
-) -> Set[int]:
-    """Text-based toggle fallback for terminals without curses."""
-    chosen = set(selected)
-    print(color(f"\n  {title}", Colors.YELLOW))
-    print(color("  Toggle by number, Enter to confirm.\n", Colors.DIM))
-
-    while True:
-        for i, label in enumerate(items):
-            marker = color("[✓]", Colors.GREEN) if i in chosen else "[ ]"
-            print(f"  {marker} {i + 1:>2}. {label}")
-        print()
-        try:
-            val = input(color("  Toggle # (or Enter to confirm): ", Colors.DIM)).strip()
-            if not val:
-                break
-            idx = int(val) - 1
-            if 0 <= idx < len(items):
-                chosen.symmetric_difference_update({idx})
-        except (ValueError, KeyboardInterrupt, EOFError):
-            return cancel_returns
-        print()
-
-    return chosen

hermes_cli/doctor.py

@@ -490,16 +490,13 @@ def run_doctor(args):
             print(f"\r  {color('⚠', Colors.YELLOW)} Anthropic API {color(f'({e})', Colors.DIM)}                 ")
 
     # -- API-key providers (Z.AI/GLM, Kimi, MiniMax, MiniMax-CN) --
-    # Tuple: (name, env_vars, default_url, base_env, supports_models_endpoint)
-    # If supports_models_endpoint is False, we skip the health check and just show "configured"
     _apikey_providers = [
-        ("Z.AI / GLM",      ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL", True),
-        ("Kimi / Moonshot",  ("KIMI_API_KEY",),                              "https://api.moonshot.ai/v1/models",   "KIMI_BASE_URL", True),
-        # MiniMax APIs don't support /models endpoint — https://github.com/NousResearch/hermes-agent/issues/811
-        ("MiniMax",          ("MINIMAX_API_KEY",),                            None,                                  "MINIMAX_BASE_URL", False),
-        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                         None,                                  "MINIMAX_CN_BASE_URL", False),
+        ("Z.AI / GLM",      ("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), "https://api.z.ai/api/paas/v4/models", "GLM_BASE_URL"),
+        ("Kimi / Moonshot",  ("KIMI_API_KEY",),                              "https://api.moonshot.ai/v1/models",   "KIMI_BASE_URL"),
+        ("MiniMax",          ("MINIMAX_API_KEY",),                            "https://api.minimax.io/v1/models",    "MINIMAX_BASE_URL"),
+        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                         "https://api.minimaxi.com/v1/models",  "MINIMAX_CN_BASE_URL"),
     ]
-    for _pname, _env_vars, _default_url, _base_env, _supports_health_check in _apikey_providers:
+    for _pname, _env_vars, _default_url, _base_env in _apikey_providers:
         _key = ""
         for _ev in _env_vars:
             _key = os.getenv(_ev, "")
@@ -507,10 +504,6 @@ def run_doctor(args):
                 break
         if _key:
             _label = _pname.ljust(20)
-            # Some providers (like MiniMax) don't support /models endpoint
-            if not _supports_health_check:
-                print(f"  {color('✓', Colors.GREEN)} {_label} {color('(key configured)', Colors.DIM)}")
-                continue
             print(f"  Checking {_pname} API...", end="", flush=True)
             try:
                 import httpx

hermes_cli/gateway.py

@@ -482,19 +482,14 @@ _PLATFORMS = [
         "token_var": "SLACK_BOT_TOKEN",
         "setup_instructions": [
             "1. Go to https://api.slack.com/apps → Create New App → From Scratch",
-            "2. Enable Socket Mode: Settings → Socket Mode → Enable",
-            "   Create an App-Level Token with scope: connections:write → copy xapp-... token",
-            "3. Add Bot Token Scopes: Features → OAuth & Permissions → Scopes",
-            "   Required: chat:write, app_mentions:read, channels:history, channels:read,",
-            "   groups:history, im:history, im:read, im:write, users:read, files:write",
-            "4. Subscribe to Events: Features → Event Subscriptions → Enable",
-            "   Required events: message.im, message.channels, app_mention",
-            "   Optional: message.groups (for private channels)",
-            "   ⚠ Without message.channels the bot will ONLY work in DMs!",
-            "5. Install to Workspace: Settings → Install App → copy xoxb-... token",
-            "6. Reinstall the app after any scope or event changes",
+            "2. Enable Socket Mode: App Settings → Socket Mode → Enable",
+            "3. Get Bot Token: OAuth & Permissions → Install to Workspace → copy xoxb-... token",
+            "4. Get App Token: Basic Information → App-Level Tokens → Generate",
+            "   Name it anything, add scope: connections:write → copy xapp-... token",
+            "5. Add bot scopes: OAuth & Permissions → Scopes → chat:write, im:history,",
+            "   im:read, im:write, channels:history, channels:read",
+            "6. Reinstall the app to your workspace after adding scopes",
             "7. Find your user ID: click your profile → three dots → Copy member ID",
-            "8. Invite the bot to channels: /invite @YourBot",
         ],
         "vars": [
             {"name": "SLACK_BOT_TOKEN", "prompt": "Bot Token (xoxb-...)", "password": True,
@@ -512,38 +507,6 @@ _PLATFORMS = [
         "emoji": "📲",
         "token_var": "WHATSAPP_ENABLED",
     },
-    {
-        "key": "signal",
-        "label": "Signal",
-        "emoji": "📡",
-        "token_var": "SIGNAL_HTTP_URL",
-    },
-    {
-        "key": "email",
-        "label": "Email",
-        "emoji": "📧",
-        "token_var": "EMAIL_ADDRESS",
-        "setup_instructions": [
-            "1. Use a dedicated email account for your Hermes agent",
-            "2. For Gmail: enable 2FA, then create an App Password at",
-            "   https://myaccount.google.com/apppasswords",
-            "3. For other providers: use your email password or app-specific password",
-            "4. IMAP must be enabled on your email account",
-        ],
-        "vars": [
-            {"name": "EMAIL_ADDRESS", "prompt": "Email address", "password": False,
-             "help": "The email address Hermes will use (e.g., hermes@gmail.com)."},
-            {"name": "EMAIL_PASSWORD", "prompt": "Email password (or app password)", "password": True,
-             "help": "For Gmail, use an App Password (not your regular password)."},
-            {"name": "EMAIL_IMAP_HOST", "prompt": "IMAP host", "password": False,
-             "help": "e.g., imap.gmail.com for Gmail, outlook.office365.com for Outlook."},
-            {"name": "EMAIL_SMTP_HOST", "prompt": "SMTP host", "password": False,
-             "help": "e.g., smtp.gmail.com for Gmail, smtp.office365.com for Outlook."},
-            {"name": "EMAIL_ALLOWED_USERS", "prompt": "Allowed sender emails (comma-separated)", "password": False,
-             "is_allowlist": True,
-             "help": "Only emails from these addresses will be processed."},
-        ],
-    },
 ]
 
 
@@ -562,22 +525,6 @@ def _platform_status(platform: dict) -> str:
                 return "configured + paired"
             return "enabled, not paired"
         return "not configured"
-    if platform.get("key") == "signal":
-        account = get_env_value("SIGNAL_ACCOUNT")
-        if val and account:
-            return "configured"
-        if val or account:
-            return "partially configured"
-        return "not configured"
-    if platform.get("key") == "email":
-        pwd = get_env_value("EMAIL_PASSWORD")
-        imap = get_env_value("EMAIL_IMAP_HOST")
-        smtp = get_env_value("EMAIL_SMTP_HOST")
-        if all([val, pwd, imap, smtp]):
-            return "configured"
-        if any([val, pwd, imap, smtp]):
-            return "partially configured"
-        return "not configured"
     if val:
         return "configured"
     return "not configured"
@@ -703,121 +650,6 @@ def _is_service_running() -> bool:
     return len(find_gateway_pids()) > 0
 
 
-def _setup_signal():
-    """Interactive setup for Signal messenger."""
-    import shutil
-
-    print()
-    print(color("  ─── 📡 Signal Setup ───", Colors.CYAN))
-
-    existing_url = get_env_value("SIGNAL_HTTP_URL")
-    existing_account = get_env_value("SIGNAL_ACCOUNT")
-    if existing_url and existing_account:
-        print()
-        print_success("Signal is already configured.")
-        if not prompt_yes_no("  Reconfigure Signal?", False):
-            return
-
-    # Check if signal-cli is available
-    print()
-    if shutil.which("signal-cli"):
-        print_success("signal-cli found on PATH.")
-    else:
-        print_warning("signal-cli not found on PATH.")
-        print_info("  Signal requires signal-cli running as an HTTP daemon.")
-        print_info("  Install options:")
-        print_info("    Linux:  sudo apt install signal-cli")
-        print_info("            or download from https://github.com/AsamK/signal-cli")
-        print_info("    macOS:  brew install signal-cli")
-        print_info("    Docker: bbernhard/signal-cli-rest-api")
-        print()
-        print_info("  After installing, link your account and start the daemon:")
-        print_info("    signal-cli link -n \"HermesAgent\"")
-        print_info("    signal-cli --account +YOURNUMBER daemon --http 127.0.0.1:8080")
-        print()
-
-    # HTTP URL
-    print()
-    print_info("  Enter the URL where signal-cli HTTP daemon is running.")
-    default_url = existing_url or "http://127.0.0.1:8080"
-    try:
-        url = input(f"  HTTP URL [{default_url}]: ").strip() or default_url
-    except (EOFError, KeyboardInterrupt):
-        print("\n  Setup cancelled.")
-        return
-
-    # Test connectivity
-    print_info("  Testing connection...")
-    try:
-        import httpx
-        resp = httpx.get(f"{url.rstrip('/')}/api/v1/check", timeout=10.0)
-        if resp.status_code == 200:
-            print_success("  signal-cli daemon is reachable!")
-        else:
-            print_warning(f"  signal-cli responded with status {resp.status_code}.")
-            if not prompt_yes_no("  Continue anyway?", False):
-                return
-    except Exception as e:
-        print_warning(f"  Could not reach signal-cli at {url}: {e}")
-        if not prompt_yes_no("  Save this URL anyway? (you can start signal-cli later)", True):
-            return
-
-    save_env_value("SIGNAL_HTTP_URL", url)
-
-    # Account phone number
-    print()
-    print_info("  Enter your Signal account phone number in E.164 format.")
-    print_info("  Example: +15551234567")
-    default_account = existing_account or ""
-    try:
-        account = input(f"  Account number{f' [{default_account}]' if default_account else ''}: ").strip()
-        if not account:
-            account = default_account
-    except (EOFError, KeyboardInterrupt):
-        print("\n  Setup cancelled.")
-        return
-
-    if not account:
-        print_error("  Account number is required.")
-        return
-
-    save_env_value("SIGNAL_ACCOUNT", account)
-
-    # Allowed users
-    print()
-    print_info("  The gateway DENIES all users by default for security.")
-    print_info("  Enter phone numbers or UUIDs of allowed users (comma-separated).")
-    existing_allowed = get_env_value("SIGNAL_ALLOWED_USERS") or ""
-    default_allowed = existing_allowed or account
-    try:
-        allowed = input(f"  Allowed users [{default_allowed}]: ").strip() or default_allowed
-    except (EOFError, KeyboardInterrupt):
-        print("\n  Setup cancelled.")
-        return
-
-    save_env_value("SIGNAL_ALLOWED_USERS", allowed)
-
-    # Group messaging
-    print()
-    if prompt_yes_no("  Enable group messaging? (disabled by default for security)", False):
-        print()
-        print_info("  Enter group IDs to allow, or * for all groups.")
-        existing_groups = get_env_value("SIGNAL_GROUP_ALLOWED_USERS") or ""
-        try:
-            groups = input(f"  Group IDs [{existing_groups or '*'}]: ").strip() or existing_groups or "*"
-        except (EOFError, KeyboardInterrupt):
-            print("\n  Setup cancelled.")
-            return
-        save_env_value("SIGNAL_GROUP_ALLOWED_USERS", groups)
-
-    print()
-    print_success("Signal configured!")
-    print_info(f"  URL: {url}")
-    print_info(f"  Account: {account}")
-    print_info(f"  DM auth: via SIGNAL_ALLOWED_USERS + DM pairing")
-    print_info(f"  Groups: {'enabled' if get_env_value('SIGNAL_GROUP_ALLOWED_USERS') else 'disabled'}")
-
-
 def gateway_setup():
     """Interactive setup for messaging platforms + gateway service."""
 
@@ -870,8 +702,6 @@ def gateway_setup():
 
         if platform["key"] == "whatsapp":
             _setup_whatsapp()
-        elif platform["key"] == "signal":
-            _setup_signal()
         else:
             _setup_standard_platform(platform)
 

hermes_cli/models.py

@@ -31,19 +31,6 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
 ]
 
 _PROVIDER_MODELS: dict[str, list[str]] = {
-    "nous": [
-        "claude-opus-4-6",
-        "claude-sonnet-4-6",
-        "gpt-5.4",
-        "gemini-3-flash",
-        "gemini-3.0-pro-preview",
-        "deepseek-v3.2",
-    ],
-    "openai-codex": [
-        "gpt-5.2-codex",
-        "gpt-5.1-codex-mini",
-        "gpt-5.1-codex-max",
-    ],
     "zai": [
         "glm-5",
         "glm-4.7",
@@ -51,10 +38,8 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
         "glm-4.5-flash",
     ],
     "kimi-coding": [
-        "kimi-for-coding",
         "kimi-k2.5",
         "kimi-k2-thinking",
-        "kimi-k2-thinking-turbo",
         "kimi-k2-turbo-preview",
         "kimi-k2-0905-preview",
     ],
@@ -78,7 +63,7 @@ _PROVIDER_LABELS = {
     "kimi-coding": "Kimi / Moonshot",
     "minimax": "MiniMax",
     "minimax-cn": "MiniMax (China)",
-    "custom": "Custom endpoint",
+    "custom": "custom endpoint",
 }
 
 _PROVIDER_ALIASES = {
@@ -179,22 +164,10 @@ def parse_model_input(raw: str, current_provider: str) -> tuple[str, str]:
 
 
 def curated_models_for_provider(provider: Optional[str]) -> list[tuple[str, str]]:
-    """Return ``(model_id, description)`` tuples for a provider's model list.
-
-    Tries to fetch the live model list from the provider's API first,
-    falling back to the static ``_PROVIDER_MODELS`` catalog if the API
-    is unreachable.
-    """
+    """Return ``(model_id, description)`` tuples for a provider's curated list."""
     normalized = normalize_provider(provider)
     if normalized == "openrouter":
         return list(OPENROUTER_MODELS)
-
-    # Try live API first (Codex, Nous, etc. all support /models)
-    live = provider_model_ids(normalized)
-    if live:
-        return [(m, "") for m in live]
-
-    # Fallback to static catalog
     models = _PROVIDER_MODELS.get(normalized, [])
     return [(m, "") for m in models]
 
@@ -211,11 +184,7 @@ def normalize_provider(provider: Optional[str]) -> str:
 
 
 def provider_model_ids(provider: Optional[str]) -> list[str]:
-    """Return the best known model catalog for a provider.
-
-    Tries live API endpoints for providers that support them (Codex, Nous),
-    falling back to static lists.
-    """
+    """Return the best known model catalog for a provider."""
     normalized = normalize_provider(provider)
     if normalized == "openrouter":
         return model_ids()
@@ -223,17 +192,6 @@ def provider_model_ids(provider: Optional[str]) -> list[str]:
         from hermes_cli.codex_models import get_codex_model_ids
 
         return get_codex_model_ids()
-    if normalized == "nous":
-        # Try live Nous Portal /models endpoint
-        try:
-            from hermes_cli.auth import fetch_nous_models, resolve_nous_runtime_credentials
-            creds = resolve_nous_runtime_credentials()
-            if creds:
-                live = fetch_nous_models(creds.get("api_key", ""), creds.get("base_url", ""))
-                if live:
-                    return live
-        except Exception:
-            pass
     return list(_PROVIDER_MODELS.get(normalized, []))
 
 
@@ -305,15 +263,6 @@ def validate_requested_model(
             "message": "Model names cannot contain spaces.",
         }
 
-    # Custom endpoints can serve any model — skip validation
-    if normalized == "custom":
-        return {
-            "accepted": True,
-            "persist": True,
-            "recognized": False,
-            "message": None,
-        }
-
     # Probe the live API to check if the model actually exists
     api_models = fetch_api_models(api_key, base_url)
 

hermes_cli/runtime_provider.py

@@ -66,14 +66,9 @@ def _resolve_openrouter_runtime(
             if not cfg_provider or cfg_provider == "auto":
                 use_config_base_url = True
 
-    # When the user explicitly requested the openrouter provider, skip
-    # OPENAI_BASE_URL — it typically points to a custom / non-OpenRouter
-    # endpoint and would prevent switching back to OpenRouter (#874).
-    skip_openai_base = requested_norm == "openrouter"
-
     base_url = (
         (explicit_base_url or "").strip()
-        or ("" if skip_openai_base else env_openai_base_url)
+        or env_openai_base_url
         or (cfg_base_url.strip() if use_config_base_url else "")
         or env_openrouter_base_url
         or OPENROUTER_BASE_URL

hermes_cli/skills_config.py

@@ -1,181 +0,0 @@
-"""
-Skills configuration for Hermes Agent.
-`hermes skills` enters this module.
-
-Toggle individual skills or categories on/off, globally or per-platform.
-Config stored in ~/.hermes/config.yaml under:
-
-  skills:
-    disabled: [skill-a, skill-b]          # global disabled list
-    platform_disabled:                    # per-platform overrides
-      telegram: [skill-c]
-      cli: []
-"""
-from typing import Dict, List, Optional, Set
-
-from hermes_cli.config import load_config, save_config
-from hermes_cli.colors import Colors, color
-
-PLATFORMS = {
-    "cli":      "🖥️  CLI",
-    "telegram": "📱 Telegram",
-    "discord":  "💬 Discord",
-    "slack":    "💼 Slack",
-    "whatsapp": "📱 WhatsApp",
-    "signal":   "📡 Signal",
-    "email":    "📧 Email",
-}
-
-# ─── Config Helpers ───────────────────────────────────────────────────────────
-
-def get_disabled_skills(config: dict, platform: Optional[str] = None) -> Set[str]:
-    """Return disabled skill names. Platform-specific list falls back to global."""
-    skills_cfg = config.get("skills", {})
-    global_disabled = set(skills_cfg.get("disabled", []))
-    if platform is None:
-        return global_disabled
-    platform_disabled = skills_cfg.get("platform_disabled", {}).get(platform)
-    if platform_disabled is None:
-        return global_disabled
-    return set(platform_disabled)
-
-
-def save_disabled_skills(config: dict, disabled: Set[str], platform: Optional[str] = None):
-    """Persist disabled skill names to config."""
-    config.setdefault("skills", {})
-    if platform is None:
-        config["skills"]["disabled"] = sorted(disabled)
-    else:
-        config["skills"].setdefault("platform_disabled", {})
-        config["skills"]["platform_disabled"][platform] = sorted(disabled)
-    save_config(config)
-
-
-# ─── Skill Discovery ─────────────────────────────────────────────────────────
-
-def _list_all_skills() -> List[dict]:
-    """Return all installed skills (ignoring disabled state)."""
-    try:
-        from tools.skills_tool import _find_all_skills
-        return _find_all_skills(skip_disabled=True)
-    except Exception:
-        return []
-
-
-def _get_categories(skills: List[dict]) -> List[str]:
-    """Return sorted unique category names (None -> 'uncategorized')."""
-    return sorted({s["category"] or "uncategorized" for s in skills})
-
-
-# ─── Platform Selection ──────────────────────────────────────────────────────
-
-def _select_platform() -> Optional[str]:
-    """Ask user which platform to configure, or global."""
-    options = [("global", "All platforms (global default)")] + list(PLATFORMS.items())
-    print()
-    print(color("  Configure skills for:", Colors.BOLD))
-    for i, (key, label) in enumerate(options, 1):
-        print(f"  {i}. {label}")
-    print()
-    try:
-        raw = input(color("  Select [1]: ", Colors.YELLOW)).strip()
-    except (KeyboardInterrupt, EOFError):
-        return None
-    if not raw:
-        return None  # global
-    try:
-        idx = int(raw) - 1
-        if 0 <= idx < len(options):
-            key = options[idx][0]
-            return None if key == "global" else key
-    except ValueError:
-        pass
-    return None
-
-
-# ─── Category Toggle ─────────────────────────────────────────────────────────
-
-def _toggle_by_category(skills: List[dict], disabled: Set[str]) -> Set[str]:
-    """Toggle all skills in a category at once."""
-    from hermes_cli.curses_ui import curses_checklist
-
-    categories = _get_categories(skills)
-    cat_labels = []
-    # A category is "enabled" (checked) when NOT all its skills are disabled
-    pre_selected = set()
-    for i, cat in enumerate(categories):
-        cat_skills = [s["name"] for s in skills if (s["category"] or "uncategorized") == cat]
-        cat_labels.append(f"{cat} ({len(cat_skills)} skills)")
-        if not all(s in disabled for s in cat_skills):
-            pre_selected.add(i)
-
-    chosen = curses_checklist(
-        "Categories — toggle entire categories",
-        cat_labels, pre_selected, cancel_returns=pre_selected,
-    )
-
-    new_disabled = set(disabled)
-    for i, cat in enumerate(categories):
-        cat_skills = {s["name"] for s in skills if (s["category"] or "uncategorized") == cat}
-        if i in chosen:
-            new_disabled -= cat_skills  # category enabled → remove from disabled
-        else:
-            new_disabled |= cat_skills  # category disabled → add to disabled
-    return new_disabled
-
-
-# ─── Entry Point ──────────────────────────────────────────────────────────────
-
-def skills_command(args=None):
-    """Entry point for `hermes skills`."""
-    from hermes_cli.curses_ui import curses_checklist
-
-    config = load_config()
-    skills = _list_all_skills()
-
-    if not skills:
-        print(color("  No skills installed.", Colors.DIM))
-        return
-
-    # Step 1: Select platform
-    platform = _select_platform()
-    platform_label = PLATFORMS.get(platform, "All platforms") if platform else "All platforms"
-
-    # Step 2: Select mode — individual or by category
-    print()
-    print(color(f"  Configure for: {platform_label}", Colors.DIM))
-    print()
-    print("  1. Toggle individual skills")
-    print("  2. Toggle by category")
-    print()
-    try:
-        mode = input(color("  Select [1]: ", Colors.YELLOW)).strip() or "1"
-    except (KeyboardInterrupt, EOFError):
-        return
-
-    disabled = get_disabled_skills(config, platform)
-
-    if mode == "2":
-        new_disabled = _toggle_by_category(skills, disabled)
-    else:
-        # Build labels and map indices → skill names
-        labels = [
-            f"{s['name']}  ({s['category'] or 'uncategorized'})  —  {s['description'][:55]}"
-            for s in skills
-        ]
-        # "selected" = enabled (not disabled) — matches the [✓] convention
-        pre_selected = {i for i, s in enumerate(skills) if s["name"] not in disabled}
-        chosen = curses_checklist(
-            f"Skills for {platform_label}",
-            labels, pre_selected, cancel_returns=pre_selected,
-        )
-        # Anything NOT chosen is disabled
-        new_disabled = {skills[i]["name"] for i in range(len(skills)) if i not in chosen}
-
-    if new_disabled == disabled:
-        print(color("  No changes.", Colors.DIM))
-        return
-
-    save_disabled_skills(config, new_disabled, platform)
-    enabled_count = len(skills) - len(new_disabled)
-    print(color(f"✓ Saved: {enabled_count} enabled, {len(new_disabled)} disabled ({platform_label}).", Colors.GREEN))

hermes_cli/skills_hub.py

@@ -407,16 +407,13 @@ def do_inspect(identifier: str, console: Optional[Console] = None) -> None:
 
 
 def do_list(source_filter: str = "all", console: Optional[Console] = None) -> None:
-    """List installed skills, distinguishing hub, builtin, and local skills."""
-    from tools.skills_hub import HubLockFile, ensure_hub_dirs
-    from tools.skills_sync import _read_manifest
+    """List installed skills, distinguishing builtins from hub-installed."""
+    from tools.skills_hub import HubLockFile, SKILLS_DIR
     from tools.skills_tool import _find_all_skills
 
     c = console or _console
-    ensure_hub_dirs()
     lock = HubLockFile()
     hub_installed = {e["name"]: e for e in lock.list_installed()}
-    builtin_names = set(_read_manifest())
 
     all_skills = _find_all_skills()
 
@@ -426,42 +423,30 @@ def do_list(source_filter: str = "all", console: Optional[Console] = None) -> No
     table.add_column("Source", style="dim")
     table.add_column("Trust", style="dim")
 
-    hub_count = 0
-    builtin_count = 0
-    local_count = 0
-
     for skill in sorted(all_skills, key=lambda s: (s.get("category") or "", s["name"])):
         name = skill["name"]
         category = skill.get("category", "")
         hub_entry = hub_installed.get(name)
 
         if hub_entry:
-            source_type = "hub"
             source_display = hub_entry.get("source", "hub")
             trust = hub_entry.get("trust_level", "community")
-            hub_count += 1
-        elif name in builtin_names:
-            source_type = "builtin"
+        else:
             source_display = "builtin"
             trust = "builtin"
-            builtin_count += 1
-        else:
-            source_type = "local"
-            source_display = "local"
-            trust = "local"
-            local_count += 1
 
-        if source_filter != "all" and source_filter != source_type:
+        if source_filter == "hub" and not hub_entry:
+            continue
+        if source_filter == "builtin" and hub_entry:
             continue
 
-        trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow", "local": "dim"}.get(trust, "dim")
+        trust_style = {"builtin": "bright_cyan", "trusted": "green", "community": "yellow"}.get(trust, "dim")
         trust_label = "official" if source_display == "official" else trust
         table.add_row(name, category, source_display, f"[{trust_style}]{trust_label}[/]")
 
     c.print(table)
-    c.print(
-        f"[dim]{hub_count} hub-installed, {builtin_count} builtin, {local_count} local[/]\n"
-    )
+    c.print(f"[dim]{len(hub_installed)} hub-installed, "
+            f"{len(all_skills) - len(hub_installed)} builtin[/]\n")
 
 
 def do_audit(name: Optional[str] = None, console: Optional[Console] = None) -> None:
@@ -1028,7 +1013,7 @@ def _print_skills_help(console: Console) -> None:
         "  [cyan]search[/] <query>              Search registries for skills\n"
         "  [cyan]install[/] <identifier>        Install a skill (with security scan)\n"
         "  [cyan]inspect[/] <identifier>        Preview a skill without installing\n"
-        "  [cyan]list[/] [--source hub|builtin|local] List installed skills\n"
+        "  [cyan]list[/] [--source hub|builtin] List installed skills\n"
         "  [cyan]audit[/] [name]                Re-scan hub skills for security\n"
         "  [cyan]uninstall[/] <name>            Remove a hub-installed skill\n"
         "  [cyan]publish[/] <path> --repo <r>   Publish a skill to GitHub via PR\n"

hermes_cli/skin_engine.py

@@ -1,630 +0,0 @@
-"""Hermes CLI skin/theme engine.
-
-A data-driven skin system that lets users customize the CLI's visual appearance.
-Skins are defined as YAML files in ~/.hermes/skins/ or as built-in presets.
-No code changes are needed to add a new skin.
-
-SKIN YAML SCHEMA
-================
-
-All fields are optional. Missing values inherit from the ``default`` skin.
-
-.. code-block:: yaml
-
-    # Required: skin identity
-    name: mytheme                         # Unique skin name (lowercase, hyphens ok)
-    description: Short description        # Shown in /skin listing
-
-    # Colors: hex values for Rich markup (banner, UI, response box)
-    colors:
-      banner_border: "#CD7F32"            # Panel border color
-      banner_title: "#FFD700"             # Panel title text color
-      banner_accent: "#FFBF00"            # Section headers (Available Tools, etc.)
-      banner_dim: "#B8860B"               # Dim/muted text (separators, labels)
-      banner_text: "#FFF8DC"              # Body text (tool names, skill names)
-      ui_accent: "#FFBF00"               # General UI accent
-      ui_label: "#4dd0e1"                # UI labels
-      ui_ok: "#4caf50"                   # Success indicators
-      ui_error: "#ef5350"                # Error indicators
-      ui_warn: "#ffa726"                 # Warning indicators
-      prompt: "#FFF8DC"                  # Prompt text color
-      input_rule: "#CD7F32"              # Input area horizontal rule
-      response_border: "#FFD700"         # Response box border (ANSI)
-      session_label: "#DAA520"           # Session label color
-      session_border: "#8B8682"          # Session ID dim color
-
-    # Spinner: customize the animated spinner during API calls
-    spinner:
-      waiting_faces:                      # Faces shown while waiting for API
-        - "(⚔)"
-        - "(⛨)"
-      thinking_faces:                     # Faces shown during reasoning
-        - "(⌁)"
-        - "(<>)"
-      thinking_verbs:                     # Verbs for spinner messages
-        - "forging"
-        - "plotting"
-      wings:                              # Optional left/right spinner decorations
-        - ["⟪⚔", "⚔⟫"]                  # Each entry is [left, right] pair
-        - ["⟪▲", "▲⟫"]
-
-    # Branding: text strings used throughout the CLI
-    branding:
-      agent_name: "Hermes Agent"          # Banner title, status display
-      welcome: "Welcome message"          # Shown at CLI startup
-      goodbye: "Goodbye! ⚕"              # Shown on exit
-      response_label: " ⚕ Hermes "       # Response box header label
-      prompt_symbol: "❯ "                # Input prompt symbol
-      help_header: "(^_^)? Commands"      # /help header text
-
-    # Tool prefix: character for tool output lines (default: ┊)
-    tool_prefix: "┊"
-
-USAGE
-=====
-
-.. code-block:: python
-
-    from hermes_cli.skin_engine import get_active_skin, list_skins, set_active_skin
-
-    skin = get_active_skin()
-    print(skin.colors["banner_title"])    # "#FFD700"
-    print(skin.get_branding("agent_name"))  # "Hermes Agent"
-
-    set_active_skin("ares")               # Switch to built-in ares skin
-    set_active_skin("mytheme")            # Switch to user skin from ~/.hermes/skins/
-
-BUILT-IN SKINS
-==============
-
-- ``default`` — Classic Hermes gold/kawaii (the current look)
-- ``ares``    — Crimson/bronze war-god theme with custom spinner wings
-- ``mono``    — Clean grayscale monochrome
-- ``slate``   — Cool blue developer-focused theme
-
-USER SKINS
-==========
-
-Drop a YAML file in ``~/.hermes/skins/<name>.yaml`` following the schema above.
-Activate with ``/skin <name>`` in the CLI or ``display.skin: <name>`` in config.yaml.
-"""
-
-import logging
-import os
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-logger = logging.getLogger(__name__)
-
-
-# =============================================================================
-# Skin data structure
-# =============================================================================
-
-@dataclass
-class SkinConfig:
-    """Complete skin configuration."""
-    name: str
-    description: str = ""
-    colors: Dict[str, str] = field(default_factory=dict)
-    spinner: Dict[str, Any] = field(default_factory=dict)
-    branding: Dict[str, str] = field(default_factory=dict)
-    tool_prefix: str = "┊"
-    banner_logo: str = ""    # Rich-markup ASCII art logo (replaces HERMES_AGENT_LOGO)
-    banner_hero: str = ""    # Rich-markup hero art (replaces HERMES_CADUCEUS)
-
-    def get_color(self, key: str, fallback: str = "") -> str:
-        """Get a color value with fallback."""
-        return self.colors.get(key, fallback)
-
-    def get_spinner_list(self, key: str) -> List[str]:
-        """Get a spinner list (faces, verbs, etc.)."""
-        return self.spinner.get(key, [])
-
-    def get_spinner_wings(self) -> List[Tuple[str, str]]:
-        """Get spinner wing pairs, or empty list if none."""
-        raw = self.spinner.get("wings", [])
-        result = []
-        for pair in raw:
-            if isinstance(pair, (list, tuple)) and len(pair) == 2:
-                result.append((str(pair[0]), str(pair[1])))
-        return result
-
-    def get_branding(self, key: str, fallback: str = "") -> str:
-        """Get a branding value with fallback."""
-        return self.branding.get(key, fallback)
-
-
-# =============================================================================
-# Built-in skin definitions
-# =============================================================================
-
-_BUILTIN_SKINS: Dict[str, Dict[str, Any]] = {
-    "default": {
-        "name": "default",
-        "description": "Classic Hermes — gold and kawaii",
-        "colors": {
-            "banner_border": "#CD7F32",
-            "banner_title": "#FFD700",
-            "banner_accent": "#FFBF00",
-            "banner_dim": "#B8860B",
-            "banner_text": "#FFF8DC",
-            "ui_accent": "#FFBF00",
-            "ui_label": "#4dd0e1",
-            "ui_ok": "#4caf50",
-            "ui_error": "#ef5350",
-            "ui_warn": "#ffa726",
-            "prompt": "#FFF8DC",
-            "input_rule": "#CD7F32",
-            "response_border": "#FFD700",
-            "session_label": "#DAA520",
-            "session_border": "#8B8682",
-        },
-        "spinner": {
-            # Empty = use hardcoded defaults in display.py
-        },
-        "branding": {
-            "agent_name": "Hermes Agent",
-            "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.",
-            "goodbye": "Goodbye! ⚕",
-            "response_label": " ⚕ Hermes ",
-            "prompt_symbol": "❯ ",
-            "help_header": "(^_^)? Available Commands",
-        },
-        "tool_prefix": "┊",
-    },
-    "ares": {
-        "name": "ares",
-        "description": "War-god theme — crimson and bronze",
-        "colors": {
-            "banner_border": "#9F1C1C",
-            "banner_title": "#C7A96B",
-            "banner_accent": "#DD4A3A",
-            "banner_dim": "#6B1717",
-            "banner_text": "#F1E6CF",
-            "ui_accent": "#DD4A3A",
-            "ui_label": "#C7A96B",
-            "ui_ok": "#4caf50",
-            "ui_error": "#ef5350",
-            "ui_warn": "#ffa726",
-            "prompt": "#F1E6CF",
-            "input_rule": "#9F1C1C",
-            "response_border": "#C7A96B",
-            "session_label": "#C7A96B",
-            "session_border": "#6E584B",
-        },
-        "spinner": {
-            "waiting_faces": ["(⚔)", "(⛨)", "(▲)", "(<>)", "(/)"],
-            "thinking_faces": ["(⚔)", "(⛨)", "(▲)", "(⌁)", "(<>)"],
-            "thinking_verbs": [
-                "forging", "marching", "sizing the field", "holding the line",
-                "hammering plans", "tempering steel", "plotting impact", "raising the shield",
-            ],
-            "wings": [
-                ["⟪⚔", "⚔⟫"],
-                ["⟪▲", "▲⟫"],
-                ["⟪╸", "╺⟫"],
-                ["⟪⛨", "⛨⟫"],
-            ],
-        },
-        "branding": {
-            "agent_name": "Ares Agent",
-            "welcome": "Welcome to Ares Agent! Type your message or /help for commands.",
-            "goodbye": "Farewell, warrior! ⚔",
-            "response_label": " ⚔ Ares ",
-            "prompt_symbol": "⚔ ❯ ",
-            "help_header": "(⚔) Available Commands",
-        },
-        "tool_prefix": "╎",
-        "banner_logo": """[bold #A3261F] █████╗ ██████╗ ███████╗███████╗       █████╗  ██████╗ ███████╗███╗   ██╗████████╗[/]
-[bold #B73122]██╔══██╗██╔══██╗██╔════╝██╔════╝      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝[/]
-[#C93C24]███████║██████╔╝█████╗  ███████╗█████╗███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║[/]
-[#D84A28]██╔══██║██╔══██╗██╔══╝  ╚════██║╚════╝██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║[/]
-[#E15A2D]██║  ██║██║  ██║███████╗███████║      ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║[/]
-[#EB6C32]╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝      ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝[/]""",
-        "banner_hero": """[#9F1C1C]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⣤⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#9F1C1C]⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⠟⠻⣿⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#C7A96B]⠀⠀⠀⠀⠀⠀⠀⣠⣾⡿⠋⠀⠀⠀⠙⢿⣷⣄⠀⠀⠀⠀⠀⠀⠀[/]
-[#C7A96B]⠀⠀⠀⠀⠀⢀⣾⡿⠋⠀⠀⢠⡄⠀⠀⠙⢿⣷⡀⠀⠀⠀⠀⠀[/]
-[#DD4A3A]⠀⠀⠀⠀⣰⣿⠟⠀⠀⠀⣰⣿⣿⣆⠀⠀⠀⠻⣿⣆⠀⠀⠀⠀[/]
-[#DD4A3A]⠀⠀⠀⢰⣿⠏⠀⠀⢀⣾⡿⠉⢿⣷⡀⠀⠀⠹⣿⡆⠀⠀⠀[/]
-[#9F1C1C]⠀⠀⠀⣿⡟⠀⠀⣠⣿⠟⠀⠀⠀⠻⣿⣄⠀⠀⢻⣿⠀⠀⠀[/]
-[#9F1C1C]⠀⠀⠀⣿⡇⠀⠀⠙⠋⠀⠀⚔⠀⠀⠙⠋⠀⠀⢸⣿⠀⠀⠀[/]
-[#6B1717]⠀⠀⠀⢿⣧⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣼⡿⠀⠀⠀[/]
-[#6B1717]⠀⠀⠀⠘⢿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⡿⠃⠀⠀⠀[/]
-[#C7A96B]⠀⠀⠀⠀⠈⠻⣿⣷⣦⣤⣀⣀⣤⣤⣶⣿⠿⠋⠀⠀⠀⠀[/]
-[#C7A96B]⠀⠀⠀⠀⠀⠀⠀⠉⠛⠿⠿⠿⠿⠛⠉⠀⠀⠀⠀⠀⠀⠀[/]
-[#DD4A3A]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⚔⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[dim #6B1717]⠀⠀⠀⠀⠀⠀⠀⠀war god online⠀⠀⠀⠀⠀⠀⠀⠀[/]""",
-    },
-    "mono": {
-        "name": "mono",
-        "description": "Monochrome — clean grayscale",
-        "colors": {
-            "banner_border": "#555555",
-            "banner_title": "#e6edf3",
-            "banner_accent": "#aaaaaa",
-            "banner_dim": "#444444",
-            "banner_text": "#c9d1d9",
-            "ui_accent": "#aaaaaa",
-            "ui_label": "#888888",
-            "ui_ok": "#888888",
-            "ui_error": "#cccccc",
-            "ui_warn": "#999999",
-            "prompt": "#c9d1d9",
-            "input_rule": "#444444",
-            "response_border": "#aaaaaa",
-            "session_label": "#888888",
-            "session_border": "#555555",
-        },
-        "spinner": {},
-        "branding": {
-            "agent_name": "Hermes Agent",
-            "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.",
-            "goodbye": "Goodbye! ⚕",
-            "response_label": " ⚕ Hermes ",
-            "prompt_symbol": "❯ ",
-            "help_header": "[?] Available Commands",
-        },
-        "tool_prefix": "┊",
-    },
-    "slate": {
-        "name": "slate",
-        "description": "Cool blue — developer-focused",
-        "colors": {
-            "banner_border": "#4169e1",
-            "banner_title": "#7eb8f6",
-            "banner_accent": "#8EA8FF",
-            "banner_dim": "#4b5563",
-            "banner_text": "#c9d1d9",
-            "ui_accent": "#7eb8f6",
-            "ui_label": "#8EA8FF",
-            "ui_ok": "#63D0A6",
-            "ui_error": "#F7A072",
-            "ui_warn": "#e6a855",
-            "prompt": "#c9d1d9",
-            "input_rule": "#4169e1",
-            "response_border": "#7eb8f6",
-            "session_label": "#7eb8f6",
-            "session_border": "#4b5563",
-        },
-        "spinner": {},
-        "branding": {
-            "agent_name": "Hermes Agent",
-            "welcome": "Welcome to Hermes Agent! Type your message or /help for commands.",
-            "goodbye": "Goodbye! ⚕",
-            "response_label": " ⚕ Hermes ",
-            "prompt_symbol": "❯ ",
-            "help_header": "(^_^)? Available Commands",
-        },
-        "tool_prefix": "┊",
-    },
-    "poseidon": {
-        "name": "poseidon",
-        "description": "Ocean-god theme — deep blue and seafoam",
-        "colors": {
-            "banner_border": "#2A6FB9",
-            "banner_title": "#A9DFFF",
-            "banner_accent": "#5DB8F5",
-            "banner_dim": "#153C73",
-            "banner_text": "#EAF7FF",
-            "ui_accent": "#5DB8F5",
-            "ui_label": "#A9DFFF",
-            "ui_ok": "#4caf50",
-            "ui_error": "#ef5350",
-            "ui_warn": "#ffa726",
-            "prompt": "#EAF7FF",
-            "input_rule": "#2A6FB9",
-            "response_border": "#5DB8F5",
-            "session_label": "#A9DFFF",
-            "session_border": "#496884",
-        },
-        "spinner": {
-            "waiting_faces": ["(≈)", "(Ψ)", "(∿)", "(◌)", "(◠)"],
-            "thinking_faces": ["(Ψ)", "(∿)", "(≈)", "(⌁)", "(◌)"],
-            "thinking_verbs": [
-                "charting currents", "sounding the depth", "reading foam lines",
-                "steering the trident", "tracking undertow", "plotting sea lanes",
-                "calling the swell", "measuring pressure",
-            ],
-            "wings": [
-                ["⟪≈", "≈⟫"],
-                ["⟪Ψ", "Ψ⟫"],
-                ["⟪∿", "∿⟫"],
-                ["⟪◌", "◌⟫"],
-            ],
-        },
-        "branding": {
-            "agent_name": "Poseidon Agent",
-            "welcome": "Welcome to Poseidon Agent! Type your message or /help for commands.",
-            "goodbye": "Fair winds! Ψ",
-            "response_label": " Ψ Poseidon ",
-            "prompt_symbol": "Ψ ❯ ",
-            "help_header": "(Ψ) Available Commands",
-        },
-        "tool_prefix": "│",
-        "banner_logo": """[bold #B8E8FF]██████╗  ██████╗ ███████╗██╗██████╗ ███████╗ ██████╗ ███╗   ██╗       █████╗  ██████╗ ███████╗███╗   ██╗████████╗[/]
-[bold #97D6FF]██╔══██╗██╔═══██╗██╔════╝██║██╔══██╗██╔════╝██╔═══██╗████╗  ██║      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝[/]
-[#75C1F6]██████╔╝██║   ██║███████╗██║██║  ██║█████╗  ██║   ██║██╔██╗ ██║█████╗███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║[/]
-[#4FA2E0]██╔═══╝ ██║   ██║╚════██║██║██║  ██║██╔══╝  ██║   ██║██║╚██╗██║╚════╝██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║[/]
-[#2E7CC7]██║     ╚██████╔╝███████║██║██████╔╝███████╗╚██████╔╝██║ ╚████║      ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║[/]
-[#1B4F95]╚═╝      ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚══════╝ ╚═════╝ ╚═╝  ╚═══╝      ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝[/]""",
-        "banner_hero": """[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⢠⣿⠏⠀Ψ⠀⠹⣿⡄⠀⠀⠀⠀⠀⠀⠀[/]
-[#A9DFFF]⠀⠀⠀⠀⠀⠀⠀⣿⡟⠀⠀⠀⠀⠀⢻⣿⠀⠀⠀⠀⠀⠀⠀[/]
-[#A9DFFF]⠀⠀⠀≈≈≈≈≈⣿⡇⠀⠀⠀⠀⠀⢸⣿≈≈≈≈≈⠀⠀⠀[/]
-[#5DB8F5]⠀⠀⠀⠀⠀⠀⠀⣿⡇⠀⠀⠀⠀⠀⢸⣿⠀⠀⠀⠀⠀⠀⠀[/]
-[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⢿⣧⠀⠀⠀⠀⠀⣼⡿⠀⠀⠀⠀⠀⠀⠀[/]
-[#2A6FB9]⠀⠀⠀⠀⠀⠀⠀⠘⢿⣷⣄⣀⣠⣾⡿⠃⠀⠀⠀⠀⠀⠀⠀[/]
-[#153C73]⠀⠀⠀⠀⠀⠀⠀⠀⠈⠻⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#153C73]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#5DB8F5]⠀⠀⠀⠀⠀≈≈≈≈≈≈≈≈≈≈≈≈≈≈≈⠀⠀⠀⠀⠀[/]
-[#A9DFFF]⠀⠀⠀⠀⠀⠀≈≈≈≈≈≈≈≈≈≈≈≈≈⠀⠀⠀⠀⠀⠀[/]
-[dim #153C73]⠀⠀⠀⠀⠀⠀⠀deep waters hold⠀⠀⠀⠀⠀⠀⠀[/]""",
-    },
-    "sisyphus": {
-        "name": "sisyphus",
-        "description": "Sisyphean theme — austere grayscale with persistence",
-        "colors": {
-            "banner_border": "#B7B7B7",
-            "banner_title": "#F5F5F5",
-            "banner_accent": "#E7E7E7",
-            "banner_dim": "#4A4A4A",
-            "banner_text": "#D3D3D3",
-            "ui_accent": "#E7E7E7",
-            "ui_label": "#D3D3D3",
-            "ui_ok": "#919191",
-            "ui_error": "#E7E7E7",
-            "ui_warn": "#B7B7B7",
-            "prompt": "#F5F5F5",
-            "input_rule": "#656565",
-            "response_border": "#B7B7B7",
-            "session_label": "#919191",
-            "session_border": "#656565",
-        },
-        "spinner": {
-            "waiting_faces": ["(◉)", "(◌)", "(◬)", "(⬤)", "(::)"],
-            "thinking_faces": ["(◉)", "(◬)", "(◌)", "(○)", "(●)"],
-            "thinking_verbs": [
-                "finding traction", "measuring the grade", "resetting the boulder",
-                "counting the ascent", "testing leverage", "setting the shoulder",
-                "pushing uphill", "enduring the loop",
-            ],
-            "wings": [
-                ["⟪◉", "◉⟫"],
-                ["⟪◬", "◬⟫"],
-                ["⟪◌", "◌⟫"],
-                ["⟪⬤", "⬤⟫"],
-            ],
-        },
-        "branding": {
-            "agent_name": "Sisyphus Agent",
-            "welcome": "Welcome to Sisyphus Agent! Type your message or /help for commands.",
-            "goodbye": "The boulder waits. ◉",
-            "response_label": " ◉ Sisyphus ",
-            "prompt_symbol": "◉ ❯ ",
-            "help_header": "(◉) Available Commands",
-        },
-        "tool_prefix": "│",
-        "banner_logo": """[bold #F5F5F5]███████╗██╗███████╗██╗   ██╗██████╗ ██╗  ██╗██╗   ██╗███████╗       █████╗  ██████╗ ███████╗███╗   ██╗████████╗[/]
-[bold #E7E7E7]██╔════╝██║██╔════╝╚██╗ ██╔╝██╔══██╗██║  ██║██║   ██║██╔════╝      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝[/]
-[#D7D7D7]███████╗██║███████╗ ╚████╔╝ ██████╔╝███████║██║   ██║███████╗█████╗███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║[/]
-[#BFBFBF]╚════██║██║╚════██║  ╚██╔╝  ██╔═══╝ ██╔══██║██║   ██║╚════██║╚════╝██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║[/]
-[#8F8F8F]███████║██║███████║   ██║   ██║     ██║  ██║╚██████╔╝███████║      ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║[/]
-[#626262]╚══════╝╚═╝╚══════╝   ╚═╝   ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝      ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝[/]""",
-        "banner_hero": """[#B7B7B7]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#D3D3D3]⠀⠀⠀⠀⠀⠀⠀⣠⣾⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#E7E7E7]⠀⠀⠀⠀⠀⠀⣾⣿⣿⣿⣿⣿⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀[/]
-[#F5F5F5]⠀⠀⠀⠀⠀⢸⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀[/]
-[#E7E7E7]⠀⠀⠀⠀⠀⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀[/]
-[#D3D3D3]⠀⠀⠀⠀⠀⠀⠘⢿⣿⣿⣿⣿⣿⡿⠃⠀⠀⠀⠀⠀⠀⠀[/]
-[#B7B7B7]⠀⠀⠀⠀⠀⠀⠀⠀⠙⠿⣿⠿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#919191]⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#656565]⠀⠀⠀⠀⠀⠀⠀⠀⠀⣰⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#656565]⠀⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#4A4A4A]⠀⠀⠀⠀⠀⠀⠀⣰⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#4A4A4A]⠀⠀⠀⠀⠀⣀⣴⣿⣿⣿⣿⣿⣿⣦⣀⠀⠀⠀⠀⠀⠀[/]
-[#656565]⠀⠀⠀━━━━━━━━━━━━━━━━━━━━━━━⠀⠀⠀[/]
-[dim #4A4A4A]⠀⠀⠀⠀⠀⠀⠀⠀⠀the boulder⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]""",
-    },
-    "charizard": {
-        "name": "charizard",
-        "description": "Volcanic theme — burnt orange and ember",
-        "colors": {
-            "banner_border": "#C75B1D",
-            "banner_title": "#FFD39A",
-            "banner_accent": "#F29C38",
-            "banner_dim": "#7A3511",
-            "banner_text": "#FFF0D4",
-            "ui_accent": "#F29C38",
-            "ui_label": "#FFD39A",
-            "ui_ok": "#4caf50",
-            "ui_error": "#ef5350",
-            "ui_warn": "#ffa726",
-            "prompt": "#FFF0D4",
-            "input_rule": "#C75B1D",
-            "response_border": "#F29C38",
-            "session_label": "#FFD39A",
-            "session_border": "#6C4724",
-        },
-        "spinner": {
-            "waiting_faces": ["(✦)", "(▲)", "(◇)", "(<>)", "(🔥)"],
-            "thinking_faces": ["(✦)", "(▲)", "(◇)", "(⌁)", "(🔥)"],
-            "thinking_verbs": [
-                "banking into the draft", "measuring burn", "reading the updraft",
-                "tracking ember fall", "setting wing angle", "holding the flame core",
-                "plotting a hot landing", "coiling for lift",
-            ],
-            "wings": [
-                ["⟪✦", "✦⟫"],
-                ["⟪▲", "▲⟫"],
-                ["⟪◌", "◌⟫"],
-                ["⟪◇", "◇⟫"],
-            ],
-        },
-        "branding": {
-            "agent_name": "Charizard Agent",
-            "welcome": "Welcome to Charizard Agent! Type your message or /help for commands.",
-            "goodbye": "Flame out! ✦",
-            "response_label": " ✦ Charizard ",
-            "prompt_symbol": "✦ ❯ ",
-            "help_header": "(✦) Available Commands",
-        },
-        "tool_prefix": "│",
-        "banner_logo": """[bold #FFF0D4] ██████╗██╗  ██╗ █████╗ ██████╗ ██╗███████╗ █████╗ ██████╗ ██████╗        █████╗  ██████╗ ███████╗███╗   ██╗████████╗[/]
-[bold #FFD39A]██╔════╝██║  ██║██╔══██╗██╔══██╗██║╚══███╔╝██╔══██╗██╔══██╗██╔══██╗      ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝[/]
-[#F29C38]██║     ███████║███████║██████╔╝██║  ███╔╝ ███████║██████╔╝██║  ██║█████╗███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║[/]
-[#E2832B]██║     ██╔══██║██╔══██║██╔══██╗██║ ███╔╝  ██╔══██║██╔══██╗██║  ██║╚════╝██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║[/]
-[#C75B1D]╚██████╗██║  ██║██║  ██║██║  ██║██║███████╗██║  ██║██║  ██║██████╔╝      ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║[/]
-[#7A3511] ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝       ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝[/]""",
-        "banner_hero": """[#FFD39A]⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⠶⠶⠶⣤⣀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#F29C38]⠀⠀⠀⠀⠀⠀⣴⠟⠁⠀⠀⠀⠀⠈⠻⣦⠀⠀⠀⠀⠀⠀[/]
-[#F29C38]⠀⠀⠀⠀⠀⣼⠏⠀⠀⠀✦⠀⠀⠀⠀⠹⣧⠀⠀⠀⠀⠀[/]
-[#E2832B]⠀⠀⠀⠀⢰⡟⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢻⡆⠀⠀⠀⠀[/]
-[#E2832B]⠀⠀⣠⡾⠛⠁⣠⣾⠟⠉⠀⠉⠻⣷⣄⠀⠈⠛⢷⣄⠀⠀[/]
-[#C75B1D]⠀⣼⠟⠀⢀⣾⠟⠁⠀⠀⠀⠀⠀⠈⠻⣷⡀⠀⠻⣧⠀[/]
-[#C75B1D]⢸⡟⠀⠀⣿⡟⠀⠀⠀🔥⠀⠀⠀⠀⢻⣿⠀⠀⢻⡇[/]
-[#7A3511]⠀⠻⣦⡀⠘⢿⣧⡀⠀⠀⠀⠀⠀⢀⣼⡿⠃⢀⣴⠟⠀[/]
-[#7A3511]⠀⠀⠈⠻⣦⣀⠙⢿⣷⣤⣤⣤⣾⡿⠋⣀⣴⠟⠁⠀⠀[/]
-[#C75B1D]⠀⠀⠀⠀⠈⠙⠛⠶⠤⠭⠭⠤⠶⠛⠋⠁⠀⠀⠀⠀[/]
-[#F29C38]⠀⠀⠀⠀⠀⠀⠀⠀⣰⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[#F29C38]⠀⠀⠀⠀⠀⠀⠀⣼⡟⠀⠀⢻⣧⠀⠀⠀⠀⠀⠀⠀⠀[/]
-[dim #7A3511]⠀⠀⠀⠀⠀⠀⠀tail flame lit⠀⠀⠀⠀⠀⠀⠀⠀[/]""",
-    },
-}
-
-
-# =============================================================================
-# Skin loading and management
-# =============================================================================
-
-_active_skin: Optional[SkinConfig] = None
-_active_skin_name: str = "default"
-
-
-def _skins_dir() -> Path:
-    """User skins directory."""
-    home = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
-    return home / "skins"
-
-
-def _load_skin_from_yaml(path: Path) -> Optional[Dict[str, Any]]:
-    """Load a skin definition from a YAML file."""
-    try:
-        import yaml
-        with open(path, "r", encoding="utf-8") as f:
-            data = yaml.safe_load(f)
-        if isinstance(data, dict) and "name" in data:
-            return data
-    except Exception as e:
-        logger.debug("Failed to load skin from %s: %s", path, e)
-    return None
-
-
-def _build_skin_config(data: Dict[str, Any]) -> SkinConfig:
-    """Build a SkinConfig from a raw dict (built-in or loaded from YAML)."""
-    # Start with default values as base for missing keys
-    default = _BUILTIN_SKINS["default"]
-    colors = dict(default.get("colors", {}))
-    colors.update(data.get("colors", {}))
-    spinner = dict(default.get("spinner", {}))
-    spinner.update(data.get("spinner", {}))
-    branding = dict(default.get("branding", {}))
-    branding.update(data.get("branding", {}))
-
-    return SkinConfig(
-        name=data.get("name", "unknown"),
-        description=data.get("description", ""),
-        colors=colors,
-        spinner=spinner,
-        branding=branding,
-        tool_prefix=data.get("tool_prefix", default.get("tool_prefix", "┊")),
-        banner_logo=data.get("banner_logo", ""),
-        banner_hero=data.get("banner_hero", ""),
-    )
-
-
-def list_skins() -> List[Dict[str, str]]:
-    """List all available skins (built-in + user-installed).
-
-    Returns list of {"name": ..., "description": ..., "source": "builtin"|"user"}.
-    """
-    result = []
-    for name, data in _BUILTIN_SKINS.items():
-        result.append({
-            "name": name,
-            "description": data.get("description", ""),
-            "source": "builtin",
-        })
-
-    skins_path = _skins_dir()
-    if skins_path.is_dir():
-        for f in sorted(skins_path.glob("*.yaml")):
-            data = _load_skin_from_yaml(f)
-            if data:
-                skin_name = data.get("name", f.stem)
-                # Skip if it shadows a built-in
-                if any(s["name"] == skin_name for s in result):
-                    continue
-                result.append({
-                    "name": skin_name,
-                    "description": data.get("description", ""),
-                    "source": "user",
-                })
-
-    return result
-
-
-def load_skin(name: str) -> SkinConfig:
-    """Load a skin by name. Checks user skins first, then built-in."""
-    # Check user skins directory
-    skins_path = _skins_dir()
-    user_file = skins_path / f"{name}.yaml"
-    if user_file.is_file():
-        data = _load_skin_from_yaml(user_file)
-        if data:
-            return _build_skin_config(data)
-
-    # Check built-in skins
-    if name in _BUILTIN_SKINS:
-        return _build_skin_config(_BUILTIN_SKINS[name])
-
-    # Fallback to default
-    logger.warning("Skin '%s' not found, using default", name)
-    return _build_skin_config(_BUILTIN_SKINS["default"])
-
-
-def get_active_skin() -> SkinConfig:
-    """Get the currently active skin config (cached)."""
-    global _active_skin
-    if _active_skin is None:
-        _active_skin = load_skin(_active_skin_name)
-    return _active_skin
-
-
-def set_active_skin(name: str) -> SkinConfig:
-    """Switch the active skin. Returns the new SkinConfig."""
-    global _active_skin, _active_skin_name
-    _active_skin_name = name
-    _active_skin = load_skin(name)
-    return _active_skin
-
-
-def get_active_skin_name() -> str:
-    """Get the name of the currently active skin."""
-    return _active_skin_name
-
-
-def init_skin_from_config(config: dict) -> None:
-    """Initialize the active skin from CLI config at startup.
-
-    Call this once during CLI init with the loaded config dict.
-    """
-    display = config.get("display", {})
-    skin_name = display.get("skin", "default")
-    if isinstance(skin_name, str) and skin_name.strip():
-        set_active_skin(skin_name.strip())
-    else:
-        set_active_skin("default")

hermes_cli/status.py

@@ -206,9 +206,6 @@ def show_status(args):
         "Telegram": ("TELEGRAM_BOT_TOKEN", "TELEGRAM_HOME_CHANNEL"),
         "Discord": ("DISCORD_BOT_TOKEN", "DISCORD_HOME_CHANNEL"),
         "WhatsApp": ("WHATSAPP_ENABLED", None),
-        "Signal": ("SIGNAL_HTTP_URL", "SIGNAL_HOME_CHANNEL"),
-        "Slack": ("SLACK_BOT_TOKEN", None),
-        "Email": ("EMAIL_ADDRESS", "EMAIL_HOME_ADDRESS"),
     }
     
     for name, (token_var, home_var) in platforms.items():
@@ -264,7 +261,7 @@ def show_status(args):
     if jobs_file.exists():
         import json
         try:
-            with open(jobs_file, encoding="utf-8") as f:
+            with open(jobs_file) as f:
                 data = json.load(f)
                 jobs = data.get("jobs", [])
                 enabled_jobs = [j for j in jobs if j.get("enabled", True)]
@@ -284,7 +281,7 @@ def show_status(args):
     if sessions_file.exists():
         import json
         try:
-            with open(sessions_file, encoding="utf-8") as f:
+            with open(sessions_file) as f:
                 data = json.load(f)
                 print(f"  Active:       {len(data)} session(s)")
         except Exception:

hermes_cli/tools_config.py

@@ -11,7 +11,7 @@ the `platform_toolsets` key.
 
 import sys
 from pathlib import Path
-from typing import Dict, List, Optional, Set
+from typing import Dict, List, Set
 
 import os
 
@@ -96,11 +96,6 @@ CONFIGURABLE_TOOLSETS = [
     ("homeassistant",    "🏠 Home Assistant",           "smart home device control"),
 ]
 
-# Toolsets that are OFF by default for new installs.
-# They're still in _HERMES_CORE_TOOLS (available at runtime if enabled),
-# but the setup checklist won't pre-select them for first-time users.
-_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl"}
-
 # Platform display config
 PLATFORMS = {
     "cli":      {"label": "🖥️  CLI",       "default_toolset": "hermes-cli"},
@@ -108,8 +103,6 @@ PLATFORMS = {
     "discord":  {"label": "💬 Discord",    "default_toolset": "hermes-discord"},
     "slack":    {"label": "💼 Slack",      "default_toolset": "hermes-slack"},
     "whatsapp": {"label": "📱 WhatsApp",   "default_toolset": "hermes-whatsapp"},
-    "signal":   {"label": "📡 Signal",     "default_toolset": "hermes-signal"},
-    "email":    {"label": "📧 Email",      "default_toolset": "hermes-email"},
 }
 
 
@@ -149,8 +142,6 @@ TOOL_CATEGORIES = {
     },
     "web": {
         "name": "Web Search & Extract",
-        "setup_title": "Select Search Provider",
-        "setup_note": "A free DuckDuckGo search skill is also included — skip this if you don't need Firecrawl.",
         "icon": "🔍",
         "providers": [
             {
@@ -310,22 +301,6 @@ def _get_enabled_platforms() -> List[str]:
     return enabled
 
 
-def _platform_toolset_summary(config: dict, platforms: Optional[List[str]] = None) -> Dict[str, Set[str]]:
-    """Return a summary of enabled toolsets per platform.
-
-    When ``platforms`` is None, this uses ``_get_enabled_platforms`` to
-    auto-detect platforms. Tests can pass an explicit list to avoid relying
-    on environment variables.
-    """
-    if platforms is None:
-        platforms = _get_enabled_platforms()
-
-    summary: Dict[str, Set[str]] = {}
-    for pkey in platforms:
-        summary[pkey] = _get_platform_tools(config, pkey)
-    return summary
-
-
 def _get_platform_tools(config: dict, platform: str) -> Set[str]:
     """Resolve which individual toolset names are enabled for a platform."""
     from toolsets import resolve_toolset, TOOLSETS
@@ -465,7 +440,6 @@ def _prompt_choice(question: str, choices: list, default: int = 0) -> int:
 
 def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str]:
     """Multi-select checklist of toolsets. Returns set of selected toolset keys."""
-    from hermes_cli.curses_ui import curses_checklist
 
     labels = []
     for ts_key, ts_label, ts_desc in CONFIGURABLE_TOOLSETS:
@@ -474,18 +448,112 @@ def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str
             suffix = "  [no API key]"
         labels.append(f"{ts_label}  ({ts_desc}){suffix}")
 
-    pre_selected = {
+    pre_selected_indices = [
         i for i, (ts_key, _, _) in enumerate(CONFIGURABLE_TOOLSETS)
         if ts_key in enabled
-    }
+    ]
 
-    chosen = curses_checklist(
-        f"Tools for {platform_label}",
-        labels,
-        pre_selected,
-        cancel_returns=pre_selected,
-    )
-    return {CONFIGURABLE_TOOLSETS[i][0] for i in chosen}
+    # Curses-based multi-select — arrow keys + space to toggle + enter to confirm.
+    # simple_term_menu has rendering bugs in tmux, iTerm, and other terminals.
+    try:
+        import curses
+        selected = set(pre_selected_indices)
+        result_holder = [None]
+
+        def _curses_checklist(stdscr):
+            curses.curs_set(0)
+            if curses.has_colors():
+                curses.start_color()
+                curses.use_default_colors()
+                curses.init_pair(1, curses.COLOR_GREEN, -1)
+                curses.init_pair(2, curses.COLOR_YELLOW, -1)
+                curses.init_pair(3, 8, -1)  # dim gray
+            cursor = 0
+            scroll_offset = 0
+
+            while True:
+                stdscr.clear()
+                max_y, max_x = stdscr.getmaxyx()
+                header = f"Tools for {platform_label}  —  ↑↓ navigate, SPACE toggle, ENTER confirm"
+                try:
+                    stdscr.addnstr(0, 0, header, max_x - 1, curses.A_BOLD | curses.color_pair(2) if curses.has_colors() else curses.A_BOLD)
+                except curses.error:
+                    pass
+
+                visible_rows = max_y - 3
+                if cursor < scroll_offset:
+                    scroll_offset = cursor
+                elif cursor >= scroll_offset + visible_rows:
+                    scroll_offset = cursor - visible_rows + 1
+
+                for draw_i, i in enumerate(range(scroll_offset, min(len(labels), scroll_offset + visible_rows))):
+                    y = draw_i + 2
+                    if y >= max_y - 1:
+                        break
+                    check = "✓" if i in selected else " "
+                    arrow = "→" if i == cursor else " "
+                    line = f" {arrow} [{check}] {labels[i]}"
+
+                    attr = curses.A_NORMAL
+                    if i == cursor:
+                        attr = curses.A_BOLD
+                        if curses.has_colors():
+                            attr |= curses.color_pair(1)
+                    try:
+                        stdscr.addnstr(y, 0, line, max_x - 1, attr)
+                    except curses.error:
+                        pass
+
+                stdscr.refresh()
+                key = stdscr.getch()
+
+                if key in (curses.KEY_UP, ord('k')):
+                    cursor = (cursor - 1) % len(labels)
+                elif key in (curses.KEY_DOWN, ord('j')):
+                    cursor = (cursor + 1) % len(labels)
+                elif key == ord(' '):
+                    if cursor in selected:
+                        selected.discard(cursor)
+                    else:
+                        selected.add(cursor)
+                elif key in (curses.KEY_ENTER, 10, 13):
+                    result_holder[0] = {CONFIGURABLE_TOOLSETS[i][0] for i in selected}
+                    return
+                elif key in (27, ord('q')):  # ESC or q
+                    result_holder[0] = enabled
+                    return
+
+        curses.wrapper(_curses_checklist)
+        return result_holder[0] if result_holder[0] is not None else enabled
+
+    except Exception:
+        pass  # fall through to numbered toggle
+
+    # Final fallback: numbered toggle (Windows without curses, etc.)
+    selected = set(pre_selected_indices)
+    print(color(f"\n  Tools for {platform_label}", Colors.YELLOW))
+    print(color("  Toggle by number, Enter to confirm.\n", Colors.DIM))
+
+    while True:
+        for i, label in enumerate(labels):
+            marker = color("[✓]", Colors.GREEN) if i in selected else "[ ]"
+            print(f"  {marker} {i + 1:>2}. {label}")
+        print()
+        try:
+            val = input(color("  Toggle # (or Enter to confirm): ", Colors.DIM)).strip()
+            if not val:
+                break
+            idx = int(val) - 1
+            if 0 <= idx < len(labels):
+                if idx in selected:
+                    selected.discard(idx)
+                else:
+                    selected.add(idx)
+        except (ValueError, KeyboardInterrupt, EOFError):
+            return enabled
+        print()
+
+    return {CONFIGURABLE_TOOLSETS[i][0] for i in selected}
 
 
 # ─── Provider-Aware Configuration ────────────────────────────────────────────
@@ -527,18 +595,11 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
         print(color(f"  --- {icon} {name} ({provider['name']}) ---", Colors.CYAN))
         if provider.get("tag"):
             _print_info(f"  {provider['tag']}")
-        # For single-provider tools, show a note if available
-        if cat.get("setup_note"):
-            _print_info(f"  {cat['setup_note']}")
         _configure_provider(provider, config)
     else:
         # Multiple providers - let user choose
         print()
-        # Use custom title if provided (e.g. "Select Search Provider")
-        title = cat.get("setup_title", f"Choose a provider")
-        print(color(f"  --- {icon} {name} - {title} ---", Colors.CYAN))
-        if cat.get("setup_note"):
-            _print_info(f"  {cat['setup_note']}")
+        print(color(f"  --- {icon} {name} - Choose a provider ---", Colors.CYAN))
         print()
 
         # Plain text labels only (no ANSI codes in menu items)
@@ -556,9 +617,6 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
                     configured = " [configured]"
             provider_choices.append(f"{p['name']}{tag}{configured}")
 
-        # Add skip option
-        provider_choices.append("Skip — keep defaults / configure later")
-
         # Detect current provider as default
         default_idx = 0
         for i, p in enumerate(providers):
@@ -570,13 +628,7 @@ def _configure_tool_category(ts_key: str, cat: dict, config: dict):
                 default_idx = i
                 break
 
-        provider_idx = _prompt_choice(f"  {title}:", provider_choices, default_idx)
-
-        # Skip selected
-        if provider_idx >= len(providers):
-            _print_info(f"  Skipped {name}")
-            return
-
+        provider_idx = _prompt_choice("  Select provider:", provider_choices, default_idx)
         _configure_provider(providers[provider_idx], config)
 
 
@@ -783,98 +835,17 @@ def _reconfigure_simple_requirements(ts_key: str):
 
 # ─── Main Entry Point ─────────────────────────────────────────────────────────
 
-def tools_command(args=None, first_install: bool = False, config: dict = None):
-    """Entry point for `hermes tools` and `hermes setup tools`.
-
-    Args:
-        first_install: When True (set by the setup wizard on fresh installs),
-            skip the platform menu, go straight to the CLI checklist, and
-            prompt for API keys on all enabled tools that need them.
-        config: Optional config dict to use.  When called from the setup
-            wizard, the wizard passes its own dict so that platform_toolsets
-            are written into it and survive the wizard's final save_config().
-    """
-    if config is None:
-        config = load_config()
+def tools_command(args=None):
+    """Entry point for `hermes tools` and `hermes setup tools`."""
+    config = load_config()
     enabled_platforms = _get_enabled_platforms()
 
     print()
-
-    # Non-interactive summary mode for CLI usage
-    if getattr(args, "summary", False):
-        total = len(CONFIGURABLE_TOOLSETS)
-        print(color("⚕ Tool Summary", Colors.CYAN, Colors.BOLD))
-        print()
-        summary = _platform_toolset_summary(config, enabled_platforms)
-        for pkey in enabled_platforms:
-            pinfo = PLATFORMS[pkey]
-            enabled = summary.get(pkey, set())
-            count = len(enabled)
-            print(color(f"  {pinfo['label']}", Colors.BOLD) + color(f"  ({count}/{total})", Colors.DIM))
-            if enabled:
-                for ts_key in sorted(enabled):
-                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts_key), ts_key)
-                    print(color(f"    ✓ {label}", Colors.GREEN))
-            else:
-                print(color("    (none enabled)", Colors.DIM))
-        print()
-        return
     print(color("⚕ Hermes Tool Configuration", Colors.CYAN, Colors.BOLD))
     print(color("  Enable or disable tools per platform.", Colors.DIM))
     print(color("  Tools that need API keys will be configured when enabled.", Colors.DIM))
     print()
 
-    # ── First-time install: linear flow, no platform menu ──
-    if first_install:
-        for pkey in enabled_platforms:
-            pinfo = PLATFORMS[pkey]
-            current_enabled = _get_platform_tools(config, pkey)
-
-            # Uncheck toolsets that should be off by default
-            checklist_preselected = current_enabled - _DEFAULT_OFF_TOOLSETS
-
-            # Show checklist
-            new_enabled = _prompt_toolset_checklist(pinfo["label"], checklist_preselected)
-
-            added = new_enabled - current_enabled
-            removed = current_enabled - new_enabled
-            if added:
-                for ts in sorted(added):
-                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
-                    print(color(f"  + {label}", Colors.GREEN))
-            if removed:
-                for ts in sorted(removed):
-                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
-                    print(color(f"  - {label}", Colors.RED))
-
-            # Walk through ALL selected tools that have provider options or
-            # need API keys.  This ensures browser (Local vs Browserbase),
-            # TTS (Edge vs OpenAI vs ElevenLabs), etc. are shown even when
-            # a free provider exists.
-            to_configure = [
-                ts_key for ts_key in sorted(new_enabled)
-                if TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)
-            ]
-
-            if to_configure:
-                print()
-                print(color(f"  Configuring {len(to_configure)} tool(s):", Colors.YELLOW))
-                for ts_key in to_configure:
-                    label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts_key), ts_key)
-                    print(color(f"    • {label}", Colors.DIM))
-                print(color("  You can skip any tool you don't need right now.", Colors.DIM))
-                print()
-                for ts_key in to_configure:
-                    _configure_toolset(ts_key, config)
-
-            _save_platform_tools(config, pkey, new_enabled)
-            save_config(config)
-            print(color(f"  ✓ Saved {pinfo['label']} tool configuration", Colors.GREEN))
-            print()
-
-        return
-
-    # ── Returning user: platform menu loop ──
     # Build platform choices
     platform_choices = []
     platform_keys = []
@@ -886,68 +857,22 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
         platform_choices.append(f"Configure {pinfo['label']}  ({count}/{total} enabled)")
         platform_keys.append(pkey)
 
-    if len(platform_keys) > 1:
-        platform_choices.append("Configure all platforms (global)")
     platform_choices.append("Reconfigure an existing tool's provider or API key")
     platform_choices.append("Done")
 
-    # Index offsets for the extra options after per-platform entries
-    _global_idx = len(platform_keys) if len(platform_keys) > 1 else -1
-    _reconfig_idx = len(platform_keys) + (1 if len(platform_keys) > 1 else 0)
-    _done_idx = _reconfig_idx + 1
-
     while True:
         idx = _prompt_choice("Select an option:", platform_choices, default=0)
 
         # "Done" selected
-        if idx == _done_idx:
+        if idx == len(platform_keys) + 1:
             break
 
         # "Reconfigure" selected
-        if idx == _reconfig_idx:
+        if idx == len(platform_keys):
             _reconfigure_tool(config)
             print()
             continue
 
-        # "Configure all platforms (global)" selected
-        if idx == _global_idx:
-            # Use the union of all platforms' current tools as the starting state
-            all_current = set()
-            for pk in platform_keys:
-                all_current |= _get_platform_tools(config, pk)
-            new_enabled = _prompt_toolset_checklist("All platforms", all_current)
-            if new_enabled != all_current:
-                for pk in platform_keys:
-                    prev = _get_platform_tools(config, pk)
-                    added = new_enabled - prev
-                    removed = prev - new_enabled
-                    pinfo_inner = PLATFORMS[pk]
-                    if added or removed:
-                        print(color(f"  {pinfo_inner['label']}:", Colors.DIM))
-                        for ts in sorted(added):
-                            label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
-                            print(color(f"    + {label}", Colors.GREEN))
-                        for ts in sorted(removed):
-                            label = next((l for k, l, _ in CONFIGURABLE_TOOLSETS if k == ts), ts)
-                            print(color(f"    - {label}", Colors.RED))
-                    # Configure API keys for newly enabled tools
-                    for ts_key in sorted(added):
-                        if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)):
-                            if not _toolset_has_keys(ts_key):
-                                _configure_toolset(ts_key, config)
-                    _save_platform_tools(config, pk, new_enabled)
-                save_config(config)
-                print(color("  ✓ Saved configuration for all platforms", Colors.GREEN))
-                # Update choice labels
-                for ci, pk in enumerate(platform_keys):
-                    new_count = len(_get_platform_tools(config, pk))
-                    total = len(CONFIGURABLE_TOOLSETS)
-                    platform_choices[ci] = f"Configure {PLATFORMS[pk]['label']}  ({new_count}/{total} enabled)"
-            else:
-                print(color("  No changes", Colors.DIM))
-            print()
-            continue
-
         pkey = platform_keys[idx]
         pinfo = PLATFORMS[pkey]
 
@@ -971,10 +896,11 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
                     print(color(f"  - {label}", Colors.RED))
 
             # Configure newly enabled toolsets that need API keys
-            for ts_key in sorted(added):
-                if (TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key)):
-                    if not _toolset_has_keys(ts_key):
-                        _configure_toolset(ts_key, config)
+            if added:
+                for ts_key in sorted(added):
+                    if TOOL_CATEGORIES.get(ts_key) or TOOLSET_ENV_REQUIREMENTS.get(ts_key):
+                        if not _toolset_has_keys(ts_key):
+                            _configure_toolset(ts_key, config)
 
             _save_platform_tools(config, pkey, new_enabled)
             save_config(config)

hermes_constants.py

@@ -7,6 +7,3 @@ without risk of circular imports.
 OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1"
 OPENROUTER_MODELS_URL = f"{OPENROUTER_BASE_URL}/models"
 OPENROUTER_CHAT_URL = f"{OPENROUTER_BASE_URL}/chat/completions"
-
-NOUS_API_BASE_URL = "https://inference-api.nousresearch.com/v1"
-NOUS_API_CHAT_URL = f"{NOUS_API_BASE_URL}/chat/completions"

hermes_state.py

@@ -16,7 +16,6 @@ Key design decisions:
 
 import json
 import os
-import re
 import sqlite3
 import time
 from pathlib import Path
@@ -491,16 +490,12 @@ class SessionDB:
         msg_id = cursor.lastrowid
 
         # Update counters
-        # Count actual tool calls from the tool_calls list (not from tool responses).
-        # A single assistant message can contain multiple parallel tool calls.
-        num_tool_calls = 0
-        if tool_calls is not None:
-            num_tool_calls = len(tool_calls) if isinstance(tool_calls, list) else 1
-        if num_tool_calls > 0:
+        is_tool_related = role == "tool" or tool_calls is not None
+        if is_tool_related:
             self._conn.execute(
                 """UPDATE sessions SET message_count = message_count + 1,
-                   tool_call_count = tool_call_count + ? WHERE id = ?""",
-                (num_tool_calls, session_id),
+                   tool_call_count = tool_call_count + 1 WHERE id = ?""",
+                (session_id,),
             )
         else:
             self._conn.execute(
@@ -558,32 +553,6 @@ class SessionDB:
     # Search
     # =========================================================================
 
-    @staticmethod
-    def _sanitize_fts5_query(query: str) -> str:
-        """Sanitize user input for safe use in FTS5 MATCH queries.
-
-        FTS5 has its own query syntax where characters like ``"``, ``(``, ``)``,
-        ``+``, ``*``, ``{``, ``}`` and bare boolean operators (``AND``, ``OR``,
-        ``NOT``) have special meaning.  Passing raw user input directly to
-        MATCH can cause ``sqlite3.OperationalError``.
-
-        Strategy: strip characters that are only meaningful as FTS5 operators
-        and would otherwise cause syntax errors.  This preserves normal keyword
-        search while preventing crashes on inputs like ``C++``, ``"unterminated``,
-        or ``hello AND``.
-        """
-        # Remove FTS5-special characters that are not useful in keyword search
-        sanitized = re.sub(r'[+{}()"^]', " ", query)
-        # Collapse repeated * (e.g. "***") into a single one, and remove
-        # leading * (prefix-only matching requires at least one char before *)
-        sanitized = re.sub(r"\*+", "*", sanitized)
-        sanitized = re.sub(r"(^|\s)\*", r"\1", sanitized)
-        # Remove dangling boolean operators at start/end that would cause
-        # syntax errors (e.g. "hello AND" or "OR world")
-        sanitized = re.sub(r"(?i)^(AND|OR|NOT)\b\s*", "", sanitized.strip())
-        sanitized = re.sub(r"(?i)\s+(AND|OR|NOT)\s*$", "", sanitized.strip())
-        return sanitized.strip()
-
     def search_messages(
         self,
         query: str,
@@ -607,10 +576,6 @@ class SessionDB:
         if not query or not query.strip():
             return []
 
-        query = self._sanitize_fts5_query(query)
-        if not query:
-            return []
-
         if source_filter is None:
             source_filter = ["cli", "telegram", "discord", "whatsapp", "slack"]
 
@@ -650,11 +615,7 @@ class SessionDB:
             LIMIT ? OFFSET ?
         """
 
-        try:
-            cursor = self._conn.execute(sql, params)
-        except sqlite3.OperationalError:
-            # FTS5 query syntax error despite sanitization — return empty
-            return []
+        cursor = self._conn.execute(sql, params)
         matches = [dict(row) for row in cursor.fetchall()]
 
         # Add surrounding context (1 message before + after each match)

landingpage/index.html

@@ -19,10 +19,7 @@
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
     
     <link rel="stylesheet" href="style.css">
-    <link rel="icon" type="image/x-icon" href="favicon.ico">
-    <link rel="icon" type="image/png" sizes="32x32" href="favicon-32x32.png">
-    <link rel="icon" type="image/png" sizes="16x16" href="favicon-16x16.png">
-    <link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
+    <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚕</text></svg>">
 </head>
 <body>
     <!-- Ambient glow effects -->

mini_swe_runner.py

@@ -189,30 +189,29 @@ class MiniSWERunner:
         )
         self.logger = logging.getLogger(__name__)
         
-        # Initialize LLM client via centralized provider router.
-        # If explicit api_key/base_url are provided (e.g. from CLI args),
-        # construct directly.  Otherwise use the router for OpenRouter.
-        if api_key or base_url:
-            from openai import OpenAI
-            client_kwargs = {
-                "base_url": base_url or "https://openrouter.ai/api/v1",
-                "api_key": api_key or os.getenv(
-                    "OPENROUTER_API_KEY",
-                    os.getenv("ANTHROPIC_API_KEY",
-                              os.getenv("OPENAI_API_KEY", ""))),
-            }
-            self.client = OpenAI(**client_kwargs)
+        # Initialize OpenAI client - defaults to OpenRouter
+        from openai import OpenAI
+        
+        client_kwargs = {}
+        
+        # Default to OpenRouter if no base_url provided
+        if base_url:
+            client_kwargs["base_url"] = base_url
         else:
-            from agent.auxiliary_client import resolve_provider_client
-            self.client, _ = resolve_provider_client("openrouter", model=model)
-            if self.client is None:
-                # Fallback: try auto-detection
-                self.client, _ = resolve_provider_client("auto", model=model)
-            if self.client is None:
-                from openai import OpenAI
-                self.client = OpenAI(
-                    base_url="https://openrouter.ai/api/v1",
-                    api_key=os.getenv("OPENROUTER_API_KEY", ""))
+            client_kwargs["base_url"] = "https://openrouter.ai/api/v1"
+
+
+        
+        # Handle API key - OpenRouter is the primary provider
+        if api_key:
+            client_kwargs["api_key"] = api_key
+        else:
+            client_kwargs["api_key"] = os.getenv(
+                "OPENROUTER_API_KEY",
+                os.getenv("ANTHROPIC_API_KEY", os.getenv("OPENAI_API_KEY", ""))
+            )
+        
+        self.client = OpenAI(**client_kwargs)
         
         # Environment will be created per-task
         self.env = None

model_tools.py

@@ -266,7 +266,6 @@ def handle_function_call(
     function_args: Dict[str, Any],
     task_id: Optional[str] = None,
     user_task: Optional[str] = None,
-    enabled_tools: Optional[List[str]] = None,
 ) -> str:
     """
     Main function call dispatcher that routes calls to the tool registry.
@@ -276,36 +275,19 @@ def handle_function_call(
         function_args: Arguments for the function.
         task_id: Unique identifier for terminal/browser session isolation.
         user_task: The user's original task (for browser_snapshot context).
-        enabled_tools: Tool names enabled for this session.  When provided,
-                       execute_code uses this list to determine which sandbox
-                       tools to generate.  Falls back to the process-global
-                       ``_last_resolved_tool_names`` for backward compat.
 
     Returns:
         Function result as a JSON string.
     """
-    # Notify the read-loop tracker when a non-read/search tool runs,
-    # so the *consecutive* counter resets (reads after other work are fine).
-    _READ_SEARCH_TOOLS = {"read_file", "search_files"}
-    if function_name not in _READ_SEARCH_TOOLS:
-        try:
-            from tools.file_tools import notify_other_tool_call
-            notify_other_tool_call(task_id or "default")
-        except Exception:
-            pass  # file_tools may not be loaded yet
-
     try:
         if function_name in _AGENT_LOOP_TOOLS:
             return json.dumps({"error": f"{function_name} must be handled by the agent loop"})
 
         if function_name == "execute_code":
-            # Prefer the caller-provided list so subagents can't overwrite
-            # the parent's tool set via the process-global.
-            sandbox_enabled = enabled_tools if enabled_tools is not None else _last_resolved_tool_names
             return registry.dispatch(
                 function_name, function_args,
                 task_id=task_id,
-                enabled_tools=sandbox_enabled,
+                enabled_tools=_last_resolved_tool_names,
             )
 
         return registry.dispatch(

optional-skills/blockchain/solana/SKILL.md

@@ -1,207 +0,0 @@
----
-name: solana
-description: Query Solana blockchain data with USD pricing — wallet balances, token portfolios with values, transaction details, NFTs, whale detection, and live network stats. Uses Solana RPC + CoinGecko. No API key required.
-version: 0.2.0
-author: Deniz Alagoz (gizdusum), enhanced by Hermes Agent
-license: MIT
-metadata:
-  hermes:
-    tags: [Solana, Blockchain, Crypto, Web3, RPC, DeFi, NFT]
-    related_skills: []
----
-
-# Solana Blockchain Skill
-
-Query Solana on-chain data enriched with USD pricing via CoinGecko.
-8 commands: wallet portfolio, token info, transactions, activity, NFTs,
-whale detection, network stats, and price lookup.
-
-No API key needed. Uses only Python standard library (urllib, json, argparse).
-
----
-
-## When to Use
-
-- User asks for a Solana wallet balance, token holdings, or portfolio value
-- User wants to inspect a specific transaction by signature
-- User wants SPL token metadata, price, supply, or top holders
-- User wants recent transaction history for an address
-- User wants NFTs owned by a wallet
-- User wants to find large SOL transfers (whale detection)
-- User wants Solana network health, TPS, epoch, or SOL price
-- User asks "what's the price of BONK/JUP/SOL?"
-
----
-
-## Prerequisites
-
-The helper script uses only Python standard library (urllib, json, argparse).
-No external packages required.
-
-Pricing data comes from CoinGecko's free API (no key needed, rate-limited
-to ~10-30 requests/minute). For faster lookups, use `--no-prices` flag.
-
----
-
-## Quick Reference
-
-RPC endpoint (default): https://api.mainnet-beta.solana.com
-Override: export SOLANA_RPC_URL=https://your-private-rpc.com
-
-Helper script path: ~/.hermes/skills/blockchain/solana/scripts/solana_client.py
-
-```
-python3 solana_client.py wallet   <address> [--limit N] [--all] [--no-prices]
-python3 solana_client.py tx       <signature>
-python3 solana_client.py token    <mint_address>
-python3 solana_client.py activity <address> [--limit N]
-python3 solana_client.py nft      <address>
-python3 solana_client.py whales   [--min-sol N]
-python3 solana_client.py stats
-python3 solana_client.py price    <mint_or_symbol>
-```
-
----
-
-## Procedure
-
-### 0. Setup Check
-
-```bash
-python3 --version
-
-# Optional: set a private RPC for better rate limits
-export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"
-
-# Confirm connectivity
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
-```
-
-### 1. Wallet Portfolio
-
-Get SOL balance, SPL token holdings with USD values, NFT count, and
-portfolio total. Tokens sorted by value, dust filtered, known tokens
-labeled by name (BONK, JUP, USDC, etc.).
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  wallet 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
-```
-
-Flags:
-- `--limit N` — show top N tokens (default: 20)
-- `--all` — show all tokens, no dust filter, no limit
-- `--no-prices` — skip CoinGecko price lookups (faster, RPC-only)
-
-Output includes: SOL balance + USD value, token list with prices sorted
-by value, dust count, NFT summary, total portfolio value in USD.
-
-### 2. Transaction Details
-
-Inspect a full transaction by its base58 signature. Shows balance changes
-in both SOL and USD.
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  tx 5j7s8K...your_signature_here
-```
-
-Output: slot, timestamp, fee, status, balance changes (SOL + USD),
-program invocations.
-
-### 3. Token Info
-
-Get SPL token metadata, current price, market cap, supply, decimals,
-mint/freeze authorities, and top 5 holders.
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  token DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
-```
-
-Output: name, symbol, decimals, supply, price, market cap, top 5
-holders with percentages.
-
-### 4. Recent Activity
-
-List recent transactions for an address (default: last 10, max: 25).
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  activity 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM --limit 25
-```
-
-### 5. NFT Portfolio
-
-List NFTs owned by a wallet (heuristic: SPL tokens with amount=1, decimals=0).
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  nft 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM
-```
-
-Note: Compressed NFTs (cNFTs) are not detected by this heuristic.
-
-### 6. Whale Detector
-
-Scan the most recent block for large SOL transfers with USD values.
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py \
-  whales --min-sol 500
-```
-
-Note: scans the latest block only — point-in-time snapshot, not historical.
-
-### 7. Network Stats
-
-Live Solana network health: current slot, epoch, TPS, supply, validator
-version, SOL price, and market cap.
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
-```
-
-### 8. Price Lookup
-
-Quick price check for any token by mint address or known symbol.
-
-```bash
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price BONK
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price JUP
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price SOL
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py price DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
-```
-
-Known symbols: SOL, USDC, USDT, BONK, JUP, WETH, JTO, mSOL, stSOL,
-PYTH, HNT, RNDR, WEN, W, TNSR, DRIFT, bSOL, JLP, WIF, MEW, BOME, PENGU.
-
----
-
-## Pitfalls
-
-- **CoinGecko rate-limits** — free tier allows ~10-30 requests/minute.
-  Price lookups use 1 request per token. Wallets with many tokens may
-  not get prices for all of them. Use `--no-prices` for speed.
-- **Public RPC rate-limits** — Solana mainnet public RPC limits requests.
-  For production use, set SOLANA_RPC_URL to a private endpoint
-  (Helius, QuickNode, Triton).
-- **NFT detection is heuristic** — amount=1 + decimals=0. Compressed
-  NFTs (cNFTs) and Token-2022 NFTs won't appear.
-- **Whale detector scans latest block only** — not historical. Results
-  vary by the moment you query.
-- **Transaction history** — public RPC keeps ~2 days. Older transactions
-  may not be available.
-- **Token names** — ~25 well-known tokens are labeled by name. Others
-  show abbreviated mint addresses. Use the `token` command for full info.
-- **Retry on 429** — both RPC and CoinGecko calls retry up to 2 times
-  with exponential backoff on rate-limit errors.
-
----
-
-## Verification
-
-```bash
-# Should print current Solana slot, TPS, and SOL price
-python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats
-```

optional-skills/blockchain/solana/scripts/solana_client.py

@@ -1,698 +0,0 @@
-#!/usr/bin/env python3
-"""
-Solana Blockchain CLI Tool for Hermes Agent
---------------------------------------------
-Queries the Solana JSON-RPC API and CoinGecko for enriched on-chain data.
-Uses only Python standard library — no external packages required.
-
-Usage:
-  python3 solana_client.py stats
-  python3 solana_client.py wallet   <address> [--limit N] [--all] [--no-prices]
-  python3 solana_client.py tx       <signature>
-  python3 solana_client.py token    <mint_address>
-  python3 solana_client.py activity <address> [--limit N]
-  python3 solana_client.py nft      <address>
-  python3 solana_client.py whales   [--min-sol N]
-  python3 solana_client.py price    <mint_address_or_symbol>
-
-Environment:
-  SOLANA_RPC_URL  Override the default RPC endpoint (default: mainnet-beta public)
-"""
-
-import argparse
-import json
-import os
-import sys
-import time
-import urllib.request
-import urllib.error
-from typing import Any, Dict, List, Optional
-
-RPC_URL = os.environ.get(
-    "SOLANA_RPC_URL",
-    "https://api.mainnet-beta.solana.com",
-)
-
-LAMPORTS_PER_SOL = 1_000_000_000
-
-# Well-known Solana token names — avoids API calls for common tokens.
-# Maps mint address → (symbol, name).
-KNOWN_TOKENS: Dict[str, tuple] = {
-    "So11111111111111111111111111111111111111112":  ("SOL",   "Solana"),
-    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": ("USDC",  "USD Coin"),
-    "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB":  ("USDT",  "Tether"),
-    "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263": ("BONK",  "Bonk"),
-    "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN":  ("JUP",   "Jupiter"),
-    "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs": ("WETH",  "Wrapped Ether"),
-    "jtojtomepa8beP8AuQc6eXt5FriJwfFMwQx2v2f9mCL":  ("JTO",   "Jito"),
-    "mSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So":  ("mSOL",  "Marinade Staked SOL"),
-    "7dHbWXmci3dT8UFYWYZweBLXgycu7Y3iL6trKn1Y7ARj": ("stSOL", "Lido Staked SOL"),
-    "HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3": ("PYTH",  "Pyth Network"),
-    "RLBxxFkseAZ4RgJH3Sqn8jXxhmGoz9jWxDNJMh8pL7a":  ("RLBB",  "Rollbit"),
-    "hntyVP6YFm1Hg25TN9WGLqM12b8TQmcknKrdu1oxWux":  ("HNT",   "Helium"),
-    "rndrizKT3MK1iimdxRdWabcF7Zg7AR5T4nud4EkHBof":  ("RNDR",  "Render"),
-    "WENWENvqqNya429ubCdR81ZmD69brwQaaBYY6p91oHQQ":  ("WEN",   "Wen"),
-    "85VBFQZC9TZkfaptBWjvUw7YbZjy52A6mjtPGjstQAmQ": ("W",     "Wormhole"),
-    "TNSRxcUxoT9xBG3de7PiJyTDYu7kskLqcpddxnEJAS6":  ("TNSR",  "Tensor"),
-    "DriFtupJYLTosbwoN8koMbEYSx54aFAVLddWsbksjwg7":  ("DRIFT", "Drift"),
-    "bSo13r4TkiE4KumL71LsHTPpL2euBYLFx6h9HP3piy1":  ("bSOL",  "BlazeStake Staked SOL"),
-    "27G8MtK7VtTcCHkpASjSDdkWWYfoqT6ggEuKidVJidD4": ("JLP",   "Jupiter LP"),
-    "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm": ("WIF",   "dogwifhat"),
-    "MEW1gQWJ3nEXg2qgERiKu7FAFj79PHvQVREQUzScPP5":  ("MEW",   "cat in a dogs world"),
-    "ukHH6c7mMyiWCf1b9pnWe25TSpkDDt3H5pQZgZ74J82":  ("BOME",  "Book of Meme"),
-    "A8C3xuqscfmyLrte3VwJvtPHXvcSN3FjDbUaSMAkQrCS": ("PENGU", "Pudgy Penguins"),
-}
-
-# Reverse lookup: symbol → mint (for the `price` command).
-_SYMBOL_TO_MINT = {v[0].upper(): k for k, v in KNOWN_TOKENS.items()}
-
-
-# ---------------------------------------------------------------------------
-# HTTP / RPC helpers
-# ---------------------------------------------------------------------------
-
-def _http_get_json(url: str, timeout: int = 10, retries: int = 2) -> Any:
-    """GET JSON from a URL with retry on 429 rate-limit. Returns parsed JSON or None."""
-    for attempt in range(retries + 1):
-        req = urllib.request.Request(
-            url, headers={"Accept": "application/json", "User-Agent": "HermesAgent/1.0"},
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=timeout) as resp:
-                return json.load(resp)
-        except urllib.error.HTTPError as exc:
-            if exc.code == 429 and attempt < retries:
-                time.sleep(2.0 * (attempt + 1))
-                continue
-            return None
-        except Exception:
-            return None
-    return None
-
-
-def _rpc_call(method: str, params: list = None, retries: int = 2) -> Any:
-    """Send a JSON-RPC request with retry on 429 rate-limit."""
-    payload = json.dumps({
-        "jsonrpc": "2.0", "id": 1,
-        "method": method, "params": params or [],
-    }).encode()
-
-    for attempt in range(retries + 1):
-        req = urllib.request.Request(
-            RPC_URL, data=payload,
-            headers={"Content-Type": "application/json"}, method="POST",
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=20) as resp:
-                body = json.load(resp)
-            if "error" in body:
-                err = body["error"]
-                # Rate-limit: retry after delay
-                if isinstance(err, dict) and err.get("code") == 429:
-                    if attempt < retries:
-                        time.sleep(1.5 * (attempt + 1))
-                        continue
-                sys.exit(f"RPC error: {err}")
-            return body.get("result")
-        except urllib.error.HTTPError as exc:
-            if exc.code == 429 and attempt < retries:
-                time.sleep(1.5 * (attempt + 1))
-                continue
-            sys.exit(f"RPC HTTP error: {exc}")
-        except urllib.error.URLError as exc:
-            sys.exit(f"RPC connection error: {exc}")
-    return None
-
-
-# Keep backward compat — the rest of the code uses `rpc()`.
-rpc = _rpc_call
-
-
-def rpc_batch(calls: list) -> list:
-    """Send a batch of JSON-RPC requests (with retry on 429)."""
-    payload = json.dumps([
-        {"jsonrpc": "2.0", "id": i, "method": c["method"], "params": c.get("params", [])}
-        for i, c in enumerate(calls)
-    ]).encode()
-
-    for attempt in range(3):
-        req = urllib.request.Request(
-            RPC_URL, data=payload,
-            headers={"Content-Type": "application/json"}, method="POST",
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=20) as resp:
-                return json.load(resp)
-        except urllib.error.HTTPError as exc:
-            if exc.code == 429 and attempt < 2:
-                time.sleep(1.5 * (attempt + 1))
-                continue
-            sys.exit(f"RPC batch HTTP error: {exc}")
-        except urllib.error.URLError as exc:
-            sys.exit(f"RPC batch error: {exc}")
-    return []
-
-
-def lamports_to_sol(lamports: int) -> float:
-    return lamports / LAMPORTS_PER_SOL
-
-
-def print_json(obj: Any) -> None:
-    print(json.dumps(obj, indent=2))
-
-
-def _short_mint(mint: str) -> str:
-    """Abbreviate a mint address for display: first 4 + last 4."""
-    if len(mint) <= 12:
-        return mint
-    return f"{mint[:4]}...{mint[-4:]}"
-
-
-# ---------------------------------------------------------------------------
-# Price & token name helpers (CoinGecko — free, no API key)
-# ---------------------------------------------------------------------------
-
-def fetch_prices(mints: List[str], max_lookups: int = 20) -> Dict[str, float]:
-    """Fetch USD prices for mint addresses via CoinGecko (one per request).
-
-    CoinGecko free tier doesn't support batch Solana token lookups,
-    so we do individual calls — capped at *max_lookups* to stay within
-    rate limits. Returns {mint: usd_price}.
-    """
-    prices: Dict[str, float] = {}
-    for i, mint in enumerate(mints[:max_lookups]):
-        url = (
-            f"https://api.coingecko.com/api/v3/simple/token_price/solana"
-            f"?contract_addresses={mint}&vs_currencies=usd"
-        )
-        data = _http_get_json(url, timeout=10)
-        if data and isinstance(data, dict):
-            for addr, info in data.items():
-                if isinstance(info, dict) and "usd" in info:
-                    prices[mint] = info["usd"]
-                    break
-        # Pause between calls to respect CoinGecko free-tier rate-limits
-        if i < len(mints[:max_lookups]) - 1:
-            time.sleep(1.0)
-    return prices
-
-
-def fetch_sol_price() -> Optional[float]:
-    """Fetch current SOL price in USD via CoinGecko."""
-    data = _http_get_json(
-        "https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd"
-    )
-    if data and "solana" in data:
-        return data["solana"].get("usd")
-    return None
-
-
-def resolve_token_name(mint: str) -> Optional[Dict[str, str]]:
-    """Look up token name and symbol from CoinGecko by mint address.
-
-    Returns {"name": ..., "symbol": ...} or None.
-    """
-    if mint in KNOWN_TOKENS:
-        sym, name = KNOWN_TOKENS[mint]
-        return {"symbol": sym, "name": name}
-    url = f"https://api.coingecko.com/api/v3/coins/solana/contract/{mint}"
-    data = _http_get_json(url, timeout=10)
-    if data and "symbol" in data:
-        return {"symbol": data["symbol"].upper(), "name": data.get("name", "")}
-    return None
-
-
-def _token_label(mint: str) -> str:
-    """Return a human-readable label for a mint: symbol if known, else abbreviated address."""
-    if mint in KNOWN_TOKENS:
-        return KNOWN_TOKENS[mint][0]
-    return _short_mint(mint)
-
-
-# ---------------------------------------------------------------------------
-# 1. Network Stats
-# ---------------------------------------------------------------------------
-
-def cmd_stats(_args):
-    """Live Solana network: slot, epoch, TPS, supply, version, SOL price."""
-    results = rpc_batch([
-        {"method": "getSlot"},
-        {"method": "getEpochInfo"},
-        {"method": "getRecentPerformanceSamples", "params": [1]},
-        {"method": "getSupply"},
-        {"method": "getVersion"},
-    ])
-
-    by_id = {r["id"]: r.get("result") for r in results}
-
-    slot         = by_id.get(0)
-    epoch_info   = by_id.get(1)
-    perf_samples = by_id.get(2)
-    supply       = by_id.get(3)
-    version      = by_id.get(4)
-
-    tps = None
-    if perf_samples:
-        s = perf_samples[0]
-        tps = round(s["numTransactions"] / s["samplePeriodSecs"], 1)
-
-    total_supply = lamports_to_sol(supply["value"]["total"])      if supply else None
-    circ_supply  = lamports_to_sol(supply["value"]["circulating"]) if supply else None
-
-    sol_price = fetch_sol_price()
-
-    out = {
-        "slot":                   slot,
-        "epoch":                  epoch_info.get("epoch")     if epoch_info else None,
-        "slot_in_epoch":          epoch_info.get("slotIndex") if epoch_info else None,
-        "tps":                    tps,
-        "total_supply_SOL":       round(total_supply, 2) if total_supply else None,
-        "circulating_supply_SOL": round(circ_supply, 2)  if circ_supply  else None,
-        "validator_version":      version.get("solana-core")  if version   else None,
-    }
-    if sol_price is not None:
-        out["sol_price_usd"] = sol_price
-        if circ_supply:
-            out["market_cap_usd"] = round(sol_price * circ_supply, 0)
-    print_json(out)
-
-
-# ---------------------------------------------------------------------------
-# 2. Wallet Info (enhanced with prices, sorting, filtering)
-# ---------------------------------------------------------------------------
-
-def cmd_wallet(args):
-    """SOL balance + SPL token holdings with USD values."""
-    address = args.address
-    show_all = getattr(args, "all", False)
-    limit = getattr(args, "limit", 20) or 20
-    skip_prices = getattr(args, "no_prices", False)
-
-    # Fetch SOL balance
-    balance_result = rpc("getBalance", [address])
-    sol_balance = lamports_to_sol(balance_result["value"])
-
-    # Fetch all SPL token accounts
-    token_result = rpc("getTokenAccountsByOwner", [
-        address,
-        {"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},
-        {"encoding": "jsonParsed"},
-    ])
-
-    raw_tokens = []
-    for acct in (token_result.get("value") or []):
-        info = acct["account"]["data"]["parsed"]["info"]
-        ta = info["tokenAmount"]
-        amount = float(ta.get("uiAmountString") or 0)
-        if amount > 0:
-            raw_tokens.append({
-                "mint":     info["mint"],
-                "amount":   amount,
-                "decimals": ta["decimals"],
-            })
-
-    # Separate NFTs (amount=1, decimals=0) from fungible tokens
-    nfts = [t for t in raw_tokens if t["decimals"] == 0 and t["amount"] == 1]
-    fungible = [t for t in raw_tokens if not (t["decimals"] == 0 and t["amount"] == 1)]
-
-    # Fetch prices for fungible tokens (cap lookups to avoid API abuse)
-    sol_price = None
-    prices: Dict[str, float] = {}
-    if not skip_prices and fungible:
-        sol_price = fetch_sol_price()
-        # Prioritize known tokens, then a small sample of unknowns.
-        # CoinGecko free tier = 1 request per mint, so we cap lookups.
-        known_mints = [t["mint"] for t in fungible if t["mint"] in KNOWN_TOKENS]
-        other_mints = [t["mint"] for t in fungible if t["mint"] not in KNOWN_TOKENS][:15]
-        mints_to_price = known_mints + other_mints
-        if mints_to_price:
-            prices = fetch_prices(mints_to_price, max_lookups=30)
-
-    # Enrich tokens with labels and USD values
-    enriched = []
-    dust_count = 0
-    dust_value = 0.0
-    for t in fungible:
-        mint = t["mint"]
-        label = _token_label(mint)
-        usd_price = prices.get(mint)
-        usd_value = round(usd_price * t["amount"], 2) if usd_price else None
-
-        # Filter dust (< $0.01) unless --all
-        if not show_all and usd_value is not None and usd_value < 0.01:
-            dust_count += 1
-            dust_value += usd_value
-            continue
-
-        entry = {"token": label, "mint": mint, "amount": t["amount"]}
-        if usd_price is not None:
-            entry["price_usd"] = usd_price
-            entry["value_usd"] = usd_value
-        enriched.append(entry)
-
-    # Sort: tokens with known USD value first (highest→lowest), then unknowns
-    enriched.sort(key=lambda x: (x.get("value_usd") is not None, x.get("value_usd") or 0), reverse=True)
-
-    # Apply limit unless --all
-    total_tokens = len(enriched)
-    if not show_all and len(enriched) > limit:
-        enriched = enriched[:limit]
-
-    # Compute portfolio total
-    total_usd = sum(t.get("value_usd", 0) for t in enriched)
-    sol_value_usd = round(sol_price * sol_balance, 2) if sol_price else None
-    if sol_value_usd:
-        total_usd += sol_value_usd
-    total_usd += dust_value
-
-    output = {
-        "address":     address,
-        "sol_balance":  round(sol_balance, 9),
-    }
-    if sol_price:
-        output["sol_price_usd"] = sol_price
-        output["sol_value_usd"] = sol_value_usd
-    output["tokens_shown"] = len(enriched)
-    if total_tokens > len(enriched):
-        output["tokens_hidden"] = total_tokens - len(enriched)
-    output["spl_tokens"] = enriched
-    if dust_count > 0:
-        output["dust_filtered"] = {"count": dust_count, "total_value_usd": round(dust_value, 4)}
-    output["nft_count"] = len(nfts)
-    if nfts:
-        output["nfts"] = [_token_label(n["mint"]) + f" ({_short_mint(n['mint'])})" for n in nfts[:10]]
-        if len(nfts) > 10:
-            output["nfts"].append(f"... and {len(nfts) - 10} more")
-    if total_usd > 0:
-        output["portfolio_total_usd"] = round(total_usd, 2)
-
-    print_json(output)
-
-
-# ---------------------------------------------------------------------------
-# 3. Transaction Details
-# ---------------------------------------------------------------------------
-
-def cmd_tx(args):
-    """Full transaction details by signature."""
-    result = rpc("getTransaction", [
-        args.signature,
-        {"encoding": "jsonParsed", "maxSupportedTransactionVersion": 0},
-    ])
-
-    if result is None:
-        sys.exit("Transaction not found (may be too old for public RPC history).")
-
-    meta         = result.get("meta", {}) or {}
-    msg          = result.get("transaction", {}).get("message", {})
-    account_keys = msg.get("accountKeys", [])
-
-    pre  = meta.get("preBalances",  [])
-    post = meta.get("postBalances", [])
-
-    balance_changes = []
-    for i, key in enumerate(account_keys):
-        acct_key = key["pubkey"] if isinstance(key, dict) else key
-        if i < len(pre) and i < len(post):
-            change = lamports_to_sol(post[i] - pre[i])
-            if change != 0:
-                balance_changes.append({"account": acct_key, "change_SOL": round(change, 9)})
-
-    programs = []
-    for ix in msg.get("instructions", []):
-        prog = ix.get("programId")
-        if prog is None and "programIdIndex" in ix:
-            k = account_keys[ix["programIdIndex"]]
-            prog = k["pubkey"] if isinstance(k, dict) else k
-        if prog:
-            programs.append(prog)
-
-    # Add USD value for SOL changes
-    sol_price = fetch_sol_price()
-    if sol_price and balance_changes:
-        for bc in balance_changes:
-            bc["change_USD"] = round(bc["change_SOL"] * sol_price, 2)
-
-    print_json({
-        "signature":        args.signature,
-        "slot":             result.get("slot"),
-        "block_time":       result.get("blockTime"),
-        "fee_SOL":          lamports_to_sol(meta.get("fee", 0)),
-        "status":           "success" if meta.get("err") is None else "failed",
-        "balance_changes":  balance_changes,
-        "programs_invoked": list(dict.fromkeys(programs)),
-    })
-
-
-# ---------------------------------------------------------------------------
-# 4. Token Info (enhanced with name + price)
-# ---------------------------------------------------------------------------
-
-def cmd_token(args):
-    """SPL token metadata, supply, decimals, price, top holders."""
-    mint = args.mint
-
-    mint_info = rpc("getAccountInfo", [mint, {"encoding": "jsonParsed"}])
-    if mint_info is None or mint_info.get("value") is None:
-        sys.exit("Mint account not found.")
-
-    parsed       = mint_info["value"]["data"]["parsed"]["info"]
-    decimals     = parsed.get("decimals", 0)
-    supply_raw   = int(parsed.get("supply", 0))
-    supply_human = supply_raw / (10 ** decimals) if decimals else supply_raw
-
-    largest = rpc("getTokenLargestAccounts", [mint])
-    holders = []
-    for acct in (largest.get("value") or [])[:5]:
-        amount = float(acct.get("uiAmountString") or 0)
-        pct = round((amount / supply_human * 100), 4) if supply_human > 0 else 0
-        holders.append({
-            "account": acct["address"],
-            "amount":  amount,
-            "percent": pct,
-        })
-
-    # Resolve name + price
-    token_meta = resolve_token_name(mint)
-    price_data = fetch_prices([mint])
-
-    out = {"mint": mint}
-    if token_meta:
-        out["name"] = token_meta["name"]
-        out["symbol"] = token_meta["symbol"]
-    out["decimals"] = decimals
-    out["supply"] = round(supply_human, min(decimals, 6))
-    out["mint_authority"] = parsed.get("mintAuthority")
-    out["freeze_authority"] = parsed.get("freezeAuthority")
-    if mint in price_data:
-        out["price_usd"] = price_data[mint]
-        out["market_cap_usd"] = round(price_data[mint] * supply_human, 0)
-    out["top_5_holders"] = holders
-
-    print_json(out)
-
-
-# ---------------------------------------------------------------------------
-# 5. Recent Activity
-# ---------------------------------------------------------------------------
-
-def cmd_activity(args):
-    """Recent transaction signatures for an address."""
-    limit  = min(args.limit, 25)
-    result = rpc("getSignaturesForAddress", [args.address, {"limit": limit}])
-
-    txs = [
-        {
-            "signature": item["signature"],
-            "slot":       item.get("slot"),
-            "block_time": item.get("blockTime"),
-            "err":        item.get("err"),
-        }
-        for item in (result or [])
-    ]
-
-    print_json({"address": args.address, "transactions": txs})
-
-
-# ---------------------------------------------------------------------------
-# 6. NFT Portfolio
-# ---------------------------------------------------------------------------
-
-def cmd_nft(args):
-    """NFTs owned by a wallet (amount=1 && decimals=0 heuristic)."""
-    result = rpc("getTokenAccountsByOwner", [
-        args.address,
-        {"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"},
-        {"encoding": "jsonParsed"},
-    ])
-
-    nfts = [
-        acct["account"]["data"]["parsed"]["info"]["mint"]
-        for acct in (result.get("value") or [])
-        if acct["account"]["data"]["parsed"]["info"]["tokenAmount"]["decimals"] == 0
-        and int(acct["account"]["data"]["parsed"]["info"]["tokenAmount"]["amount"]) == 1
-    ]
-
-    print_json({
-        "address":   args.address,
-        "nft_count": len(nfts),
-        "nfts":      nfts,
-        "note":      "Heuristic only. Compressed NFTs (cNFTs) are not detected.",
-    })
-
-
-# ---------------------------------------------------------------------------
-# 7. Whale Detector (enhanced with USD values)
-# ---------------------------------------------------------------------------
-
-def cmd_whales(args):
-    """Scan the latest block for large SOL transfers."""
-    min_lamports = int(args.min_sol * LAMPORTS_PER_SOL)
-
-    slot  = rpc("getSlot")
-    block = rpc("getBlock", [
-        slot,
-        {
-            "encoding": "jsonParsed",
-            "transactionDetails": "full",
-            "maxSupportedTransactionVersion": 0,
-            "rewards": False,
-        },
-    ])
-
-    if block is None:
-        sys.exit("Could not retrieve latest block.")
-
-    sol_price = fetch_sol_price()
-
-    whales = []
-    for tx in (block.get("transactions") or []):
-        meta = tx.get("meta", {}) or {}
-        if meta.get("err") is not None:
-            continue
-
-        msg          = tx["transaction"].get("message", {})
-        account_keys = msg.get("accountKeys", [])
-        pre          = meta.get("preBalances",  [])
-        post         = meta.get("postBalances", [])
-
-        for i in range(len(pre)):
-            change = post[i] - pre[i]
-            if change >= min_lamports:
-                k        = account_keys[i]
-                receiver = k["pubkey"] if isinstance(k, dict) else k
-                sender   = None
-                for j in range(len(pre)):
-                    if pre[j] - post[j] >= min_lamports:
-                        sk     = account_keys[j]
-                        sender = sk["pubkey"] if isinstance(sk, dict) else sk
-                        break
-                entry = {
-                    "sender":     sender,
-                    "receiver":   receiver,
-                    "amount_SOL": round(lamports_to_sol(change), 4),
-                }
-                if sol_price:
-                    entry["amount_USD"] = round(lamports_to_sol(change) * sol_price, 2)
-                whales.append(entry)
-
-    out = {
-        "slot":              slot,
-        "min_threshold_SOL": args.min_sol,
-        "large_transfers":   whales,
-        "note":              "Scans latest block only — point-in-time snapshot.",
-    }
-    if sol_price:
-        out["sol_price_usd"] = sol_price
-    print_json(out)
-
-
-# ---------------------------------------------------------------------------
-# 8. Price Lookup
-# ---------------------------------------------------------------------------
-
-def cmd_price(args):
-    """Quick price lookup for a token by mint address or known symbol."""
-    query = args.token
-
-    # Check if it's a known symbol
-    mint = _SYMBOL_TO_MINT.get(query.upper(), query)
-
-    # Try to resolve name
-    token_meta = resolve_token_name(mint)
-
-    # Fetch price
-    prices = fetch_prices([mint])
-
-    out = {"query": query, "mint": mint}
-    if token_meta:
-        out["name"] = token_meta["name"]
-        out["symbol"] = token_meta["symbol"]
-    if mint in prices:
-        out["price_usd"] = prices[mint]
-    else:
-        out["price_usd"] = None
-        out["note"] = "Price not available — token may not be listed on CoinGecko."
-    print_json(out)
-
-
-# ---------------------------------------------------------------------------
-# CLI
-# ---------------------------------------------------------------------------
-
-def main():
-    parser = argparse.ArgumentParser(
-        prog="solana_client.py",
-        description="Solana blockchain query tool for Hermes Agent",
-    )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    sub.add_parser("stats", help="Network stats: slot, epoch, TPS, supply, SOL price")
-
-    p_wallet = sub.add_parser("wallet", help="SOL balance + SPL tokens with USD values")
-    p_wallet.add_argument("address")
-    p_wallet.add_argument("--limit", type=int, default=20,
-                          help="Max tokens to display (default: 20)")
-    p_wallet.add_argument("--all", action="store_true",
-                          help="Show all tokens (no limit, no dust filter)")
-    p_wallet.add_argument("--no-prices", action="store_true",
-                          help="Skip price lookups (faster, RPC-only)")
-
-    p_tx = sub.add_parser("tx", help="Transaction details by signature")
-    p_tx.add_argument("signature")
-
-    p_token = sub.add_parser("token", help="SPL token metadata, price, and top holders")
-    p_token.add_argument("mint")
-
-    p_activity = sub.add_parser("activity", help="Recent transactions for an address")
-    p_activity.add_argument("address")
-    p_activity.add_argument("--limit", type=int, default=10,
-                            help="Number of transactions (max 25, default 10)")
-
-    p_nft = sub.add_parser("nft", help="NFT portfolio for a wallet")
-    p_nft.add_argument("address")
-
-    p_whales = sub.add_parser("whales", help="Large SOL transfers in the latest block")
-    p_whales.add_argument("--min-sol", type=float, default=1000.0,
-                          help="Minimum SOL transfer size (default: 1000)")
-
-    p_price = sub.add_parser("price", help="Quick price lookup by mint or symbol")
-    p_price.add_argument("token", help="Mint address or known symbol (SOL, BONK, JUP, ...)")
-
-    args = parser.parse_args()
-
-    dispatch = {
-        "stats":    cmd_stats,
-        "wallet":   cmd_wallet,
-        "tx":       cmd_tx,
-        "token":    cmd_token,
-        "activity": cmd_activity,
-        "nft":      cmd_nft,
-        "whales":   cmd_whales,
-        "price":    cmd_price,
-    }
-    dispatch[args.command](args)
-
-
-if __name__ == "__main__":
-    main()

optional-skills/email/agentmail/SKILL.md

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

optional-skills/migration/DESCRIPTION.md

@@ -1,2 +0,0 @@
-Optional migration workflows for importing user state and customizations from
-other agent systems into Hermes Agent.

optional-skills/migration/openclaw-migration/SKILL.md

@@ -1,297 +0,0 @@
----
-name: openclaw-migration
-description: Migrate a user's OpenClaw customization footprint into Hermes Agent. Imports Hermes-compatible memories, SOUL.md, command allowlists, user skills, and selected workspace assets from ~/.openclaw, then reports exactly what could not be migrated and why.
-version: 1.0.0
-author: Hermes Agent (Nous Research)
-license: MIT
-metadata:
-  hermes:
-    tags: [Migration, OpenClaw, Hermes, Memory, Persona, Import]
-    related_skills: [hermes-agent]
----
-
-# OpenClaw -> Hermes Migration
-
-Use this skill when a user wants to move their OpenClaw setup into Hermes Agent with minimal manual cleanup.
-
-## CLI Command
-
-For a quick, non-interactive migration, use the built-in CLI command:
-
-```bash
-hermes claw migrate              # Full interactive migration
-hermes claw migrate --dry-run    # Preview what would be migrated
-hermes claw migrate --preset user-data   # Migrate without secrets
-hermes claw migrate --overwrite  # Overwrite existing conflicts
-hermes claw migrate --source /custom/path/.openclaw  # Custom source
-```
-
-The CLI command runs the same migration script described below. Use this skill (via the agent) when you want an interactive, guided migration with dry-run previews and per-item conflict resolution.
-
-**First-time setup:** The `hermes setup` wizard automatically detects `~/.openclaw` and offers migration before configuration begins.
-
-## What this skill does
-
-It uses `scripts/openclaw_to_hermes.py` to:
-
-- import `SOUL.md` into the Hermes home directory as `SOUL.md`
-- transform OpenClaw `MEMORY.md` and `USER.md` into Hermes memory entries
-- merge OpenClaw command approval patterns into Hermes `command_allowlist`
-- migrate Hermes-compatible messaging settings such as `TELEGRAM_ALLOWED_USERS` and `MESSAGING_CWD`
-- copy OpenClaw skills into `~/.hermes/skills/openclaw-imports/`
-- optionally copy the OpenClaw workspace instructions file into a chosen Hermes workspace
-- mirror compatible workspace assets such as `workspace/tts/` into `~/.hermes/tts/`
-- archive non-secret docs that do not have a direct Hermes destination
-- produce a structured report listing migrated items, conflicts, skipped items, and reasons
-
-## Path resolution
-
-The helper script lives in this skill directory at:
-
-- `scripts/openclaw_to_hermes.py`
-
-When this skill is installed from the Skills Hub, the normal location is:
-
-- `~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py`
-
-Do not guess a shorter path like `~/.hermes/skills/openclaw-migration/...`.
-
-Before running the helper:
-
-1. Prefer the installed path under `~/.hermes/skills/migration/openclaw-migration/`.
-2. If that path fails, inspect the installed skill directory and resolve the script relative to the installed `SKILL.md`.
-3. Only use `find` as a fallback if the installed location is missing or the skill was moved manually.
-4. When calling the terminal tool, do not pass `workdir: "~"`. Use an absolute directory such as the user's home directory, or omit `workdir` entirely.
-
-With `--migrate-secrets`, it will also import a small allowlisted set of Hermes-compatible secrets, currently:
-
-- `TELEGRAM_BOT_TOKEN`
-
-## Default workflow
-
-1. Inspect first with a dry run.
-2. Present a simple summary of what can be migrated, what cannot be migrated, and what would be archived.
-3. If the `clarify` tool is available, use it for user decisions instead of asking for a free-form prose reply.
-4. If the dry run finds imported skill directory conflicts, ask how those should be handled before executing.
-5. Ask the user to choose between the two supported migration modes before executing.
-6. Ask for a target workspace path only if the user wants the workspace instructions file brought over.
-7. Execute the migration with the matching preset and flags.
-8. Summarize the results, especially:
-   - what was migrated
-   - what was archived for manual review
-   - what was skipped and why
-
-## User interaction protocol
-
-Hermes CLI supports the `clarify` tool for interactive prompts, but it is limited to:
-
-- one choice at a time
-- up to 4 predefined choices
-- an automatic `Other` free-text option
-
-It does **not** support true multi-select checkboxes in a single prompt.
-
-For every `clarify` call:
-
-- always include a non-empty `question`
-- include `choices` only for real selectable prompts
-- keep `choices` to 2-4 plain string options
-- never emit placeholder or truncated options such as `...`
-- never pad or stylize choices with extra whitespace
-- never include fake form fields in the question such as `enter directory here`, blank lines to fill in, or underscores like `_____`
-- for open-ended path questions, ask only the plain sentence; the user types in the normal CLI prompt below the panel
-
-If a `clarify` call returns an error, inspect the error text, correct the payload, and retry once with a valid `question` and clean choices.
-
-When `clarify` is available and the dry run reveals any required user decision, your **next action must be a `clarify` tool call**.
-Do not end the turn with a normal assistant message such as:
-
-- "Let me present the choices"
-- "What would you like to do?"
-- "Here are the options"
-
-If a user decision is required, collect it via `clarify` before producing more prose.
-If multiple unresolved decisions remain, do not insert an explanatory assistant message between them. After one `clarify` response is received, your next action should usually be the next required `clarify` call.
-
-Treat `workspace-agents` as an unresolved decision whenever the dry run reports:
-
-- `kind="workspace-agents"`
-- `status="skipped"`
-- reason containing `No workspace target was provided`
-
-In that case, you must ask about workspace instructions before execution. Do not silently treat that as a decision to skip.
-
-Because of that limitation, use this simplified decision flow:
-
-1. For `SOUL.md` conflicts, use `clarify` with choices such as:
-   - `keep existing`
-   - `overwrite with backup`
-   - `review first`
-2. If the dry run shows one or more `kind="skill"` items with `status="conflict"`, use `clarify` with choices such as:
-   - `keep existing skills`
-   - `overwrite conflicting skills with backup`
-   - `import conflicting skills under renamed folders`
-3. For workspace instructions, use `clarify` with choices such as:
-   - `skip workspace instructions`
-   - `copy to a workspace path`
-   - `decide later`
-4. If the user chooses to copy workspace instructions, ask a follow-up open-ended `clarify` question requesting an **absolute path**.
-5. If the user chooses `skip workspace instructions` or `decide later`, proceed without `--workspace-target`.
-5. For migration mode, use `clarify` with these 3 choices:
-   - `user-data only`
-   - `full compatible migration`
-   - `cancel`
-6. `user-data only` means: migrate user data and compatible config, but do **not** import allowlisted secrets.
-7. `full compatible migration` means: migrate the same compatible user data plus the allowlisted secrets when present.
-8. If `clarify` is not available, ask the same question in normal text, but still constrain the answer to `user-data only`, `full compatible migration`, or `cancel`.
-
-Execution gate:
-
-- Do not execute while a `workspace-agents` skip caused by `No workspace target was provided` remains unresolved.
-- The only valid ways to resolve it are:
-  - user explicitly chooses `skip workspace instructions`
-  - user explicitly chooses `decide later`
-  - user provides a workspace path after choosing `copy to a workspace path`
-- Absence of a workspace target in the dry run is not itself permission to execute.
-- Do not execute while any required `clarify` decision remains unresolved.
-
-Use these exact `clarify` payload shapes as the default pattern:
-
-- `{"question":"Your existing SOUL.md conflicts with the imported one. What should I do?","choices":["keep existing","overwrite with backup","review first"]}`
-- `{"question":"One or more imported OpenClaw skills already exist in Hermes. How should I handle those skill conflicts?","choices":["keep existing skills","overwrite conflicting skills with backup","import conflicting skills under renamed folders"]}`
-- `{"question":"Choose migration mode: migrate only user data, or run the full compatible migration including allowlisted secrets?","choices":["user-data only","full compatible migration","cancel"]}`
-- `{"question":"Do you want to copy the OpenClaw workspace instructions file into a Hermes workspace?","choices":["skip workspace instructions","copy to a workspace path","decide later"]}`
-- `{"question":"Please provide an absolute path where the workspace instructions should be copied."}`
-
-## Decision-to-command mapping
-
-Map user decisions to command flags exactly:
-
-- If the user chooses `keep existing` for `SOUL.md`, do **not** add `--overwrite`.
-- If the user chooses `overwrite with backup`, add `--overwrite`.
-- If the user chooses `review first`, stop before execution and review the relevant files.
-- If the user chooses `keep existing skills`, add `--skill-conflict skip`.
-- If the user chooses `overwrite conflicting skills with backup`, add `--skill-conflict overwrite`.
-- If the user chooses `import conflicting skills under renamed folders`, add `--skill-conflict rename`.
-- If the user chooses `user-data only`, execute with `--preset user-data` and do **not** add `--migrate-secrets`.
-- If the user chooses `full compatible migration`, execute with `--preset full --migrate-secrets`.
-- Only add `--workspace-target` if the user explicitly provided an absolute workspace path.
-- If the user chooses `skip workspace instructions` or `decide later`, do not add `--workspace-target`.
-
-Before executing, restate the exact command plan in plain language and make sure it matches the user's choices.
-
-## Post-run reporting rules
-
-After execution, treat the script's JSON output as the source of truth.
-
-1. Base all counts on `report.summary`.
-2. Only list an item under "Successfully Migrated" if its `status` is exactly `migrated`.
-3. Do not claim a conflict was resolved unless the report shows that item as `migrated`.
-4. Do not say `SOUL.md` was overwritten unless the report item for `kind="soul"` has `status="migrated"`.
-5. If `report.summary.conflict > 0`, include a conflict section instead of silently implying success.
-6. If counts and listed items disagree, fix the list to match the report before responding.
-7. Include the `output_dir` path from the report when available so the user can inspect `report.json`, `summary.md`, backups, and archived files.
-8. For memory or user-profile overflow, do not say the entries were archived unless the report explicitly shows an archive path. If `details.overflow_file` exists, say the full overflow list was exported there.
-9. If a skill was imported under a renamed folder, report the final destination and mention `details.renamed_from`.
-10. If `report.skill_conflict_mode` is present, use it as the source of truth for the selected imported-skill conflict policy.
-11. If an item has `status="skipped"`, do not describe it as overwritten, backed up, migrated, or resolved.
-12. If `kind="soul"` has `status="skipped"` with reason `Target already matches source`, say it was left unchanged and do not mention a backup.
-13. If a renamed imported skill has an empty `details.backup`, do not imply the existing Hermes skill was renamed or backed up. Say only that the imported copy was placed in the new destination and reference `details.renamed_from` as the pre-existing folder that remained in place.
-
-## Migration presets
-
-Prefer these two presets in normal use:
-
-- `user-data`
-- `full`
-
-`user-data` includes:
-
-- `soul`
-- `workspace-agents`
-- `memory`
-- `user-profile`
-- `messaging-settings`
-- `command-allowlist`
-- `skills`
-- `tts-assets`
-- `archive`
-
-`full` includes everything in `user-data` plus:
-
-- `secret-settings`
-
-The helper script still supports category-level `--include` / `--exclude`, but treat that as an advanced fallback rather than the default UX.
-
-## Commands
-
-Dry run with full discovery:
-
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py
-```
-
-When using the terminal tool, prefer an absolute invocation pattern such as:
-
-```json
-{"command":"python3 /home/USER/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py","workdir":"/home/USER"}
-```
-
-Dry run with the user-data preset:
-
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --preset user-data
-```
-
-Execute a user-data migration:
-
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict skip
-```
-
-Execute a full compatible migration:
-
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset full --migrate-secrets --skill-conflict skip
-```
-
-Execute with workspace instructions included:
-
-```bash
-python3 ~/.hermes/skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py --execute --preset user-data --skill-conflict rename --workspace-target "/absolute/workspace/path"
-```
-
-Do not use `$PWD` or the home directory as the workspace target by default. Ask for an explicit workspace path first.
-
-## Important rules
-
-1. Run a dry run before writing unless the user explicitly says to proceed immediately.
-2. Do not migrate secrets by default. Tokens, auth blobs, device credentials, and raw gateway config should stay out of Hermes unless the user explicitly asks for secret migration.
-3. Do not silently overwrite non-empty Hermes targets unless the user explicitly wants that. The helper script will preserve backups when overwriting is enabled.
-4. Always give the user the skipped-items report. That report is part of the migration, not an optional extra.
-5. Prefer the primary OpenClaw workspace (`~/.openclaw/workspace/`) over `workspace.default/`. Only use the default workspace as fallback when the primary files are missing.
-6. Even in secret-migration mode, only migrate secrets with a clean Hermes destination. Unsupported auth blobs must still be reported as skipped.
-7. If the dry run shows a large asset copy, a conflicting `SOUL.md`, or overflowed memory entries, call those out separately before execution.
-8. Default to `user-data only` if the user is unsure.
-9. Only include `workspace-agents` when the user has explicitly provided a destination workspace path.
-10. Treat category-level `--include` / `--exclude` as an advanced escape hatch, not the normal flow.
-11. Do not end the dry-run summary with a vague “What would you like to do?” if `clarify` is available. Use structured follow-up prompts instead.
-12. Do not use an open-ended `clarify` prompt when a real choice prompt would work. Prefer selectable choices first, then free text only for absolute paths or file review requests.
-13. After a dry run, never stop after summarizing if there is still an unresolved decision. Use `clarify` immediately for the highest-priority blocking decision.
-14. Priority order for follow-up questions:
-    - `SOUL.md` conflict
-    - imported skill conflicts
-    - migration mode
-    - workspace instructions destination
-15. Do not promise to present choices later in the same message. Present them by actually calling `clarify`.
-16. After the migration-mode answer, explicitly check whether `workspace-agents` is still unresolved. If it is, your next action must be the workspace-instructions `clarify` call.
-17. After any `clarify` answer, if another required decision remains, do not narrate what was just decided. Ask the next required question immediately.
-
-## Expected result
-
-After a successful run, the user should have:
-
-- Hermes persona state imported
-- Hermes memory files populated with converted OpenClaw knowledge
-- OpenClaw skills available under `~/.hermes/skills/openclaw-imports/`
-- a migration report showing any conflicts, omissions, or unsupported data

plans/checkpoint-rollback.md

@@ -1,218 +0,0 @@
-# Checkpoint & Rollback — Implementation Plan
-
-## Goal
-
-Automatic filesystem snapshots before destructive file operations, with user-facing rollback. The agent never sees or interacts with this — it's transparent infrastructure.
-
-## Design Principles
-
-1. **Not a tool** — the LLM never knows about it. Zero prompt tokens, zero tool schema overhead.
-2. **Once per turn** — checkpoint at most once per conversation turn (user message → agent response cycle), triggered lazily on the first file-mutating operation. Not on every write.
-3. **Opt-in via config** — disabled by default, enabled with `checkpoints: true` in config.yaml.
-4. **Works on any directory** — uses a shadow git repo completely separate from the user's project git. Works on git repos, non-git directories, anything.
-5. **User-facing rollback** — `/rollback` slash command (CLI + gateway) to list and restore checkpoints. Also `hermes rollback` CLI subcommand.
-
-## Architecture
-
-```
-~/.hermes/checkpoints/
-  {sha256(abs_dir)[:16]}/       # Shadow git repo per working directory
-    HEAD, refs/, objects/...    # Standard git internals
-    HERMES_WORKDIR              # Original dir path (for display)
-    info/exclude                # Default excludes (node_modules, .env, etc.)
-```
-
-### Core: CheckpointManager (new file: tools/checkpoint_manager.py)
-
-Adapted from PR #559's CheckpointStore. Key changes from the PR:
-
-- **Not a tool** — no schema, no registry entry, no handler
-- **Turn-scoped deduplication** — tracks `_checkpointed_dirs: Set[str]` per turn
-- **Configurable** — reads `checkpoints` config key
-- **Pruning** — keeps last N snapshots per directory (default 50), prunes on take
-
-```python
-class CheckpointManager:
-    def __init__(self, enabled: bool = False, max_snapshots: int = 50):
-        self.enabled = enabled
-        self.max_snapshots = max_snapshots
-        self._checkpointed_dirs: Set[str] = set()  # reset each turn
-
-    def new_turn(self):
-        """Call at start of each conversation turn to reset dedup."""
-        self._checkpointed_dirs.clear()
-
-    def ensure_checkpoint(self, working_dir: str, reason: str = "auto") -> None:
-        """Take a checkpoint if enabled and not already done this turn."""
-        if not self.enabled:
-            return
-        abs_dir = str(Path(working_dir).resolve())
-        if abs_dir in self._checkpointed_dirs:
-            return
-        self._checkpointed_dirs.add(abs_dir)
-        try:
-            self._take(abs_dir, reason)
-        except Exception as e:
-            logger.debug("Checkpoint failed (non-fatal): %s", e)
-
-    def list_checkpoints(self, working_dir: str) -> List[dict]:
-        """List available checkpoints for a directory."""
-        ...
-
-    def restore(self, working_dir: str, commit_hash: str) -> dict:
-        """Restore files to a checkpoint state."""
-        ...
-
-    def _take(self, working_dir: str, reason: str):
-        """Shadow git: add -A + commit. Prune if over max_snapshots."""
-        ...
-
-    def _prune(self, shadow_repo: Path):
-        """Keep only last max_snapshots commits."""
-        ...
-```
-
-### Integration Point: run_agent.py
-
-The AIAgent already owns the conversation loop. Add CheckpointManager as an instance attribute:
-
-```python
-class AIAgent:
-    def __init__(self, ...):
-        ...
-        # Checkpoint manager — reads config to determine if enabled
-        self._checkpoint_mgr = CheckpointManager(
-            enabled=config.get("checkpoints", False),
-            max_snapshots=config.get("checkpoint_max_snapshots", 50),
-        )
-```
-
-**Turn boundary** — in `run_conversation()`, call `new_turn()` at the start of each agent iteration (before processing tool calls):
-
-```python
-# Inside the main loop, before _execute_tool_calls():
-self._checkpoint_mgr.new_turn()
-```
-
-**Trigger point** — in `_execute_tool_calls()`, before dispatching file-mutating tools:
-
-```python
-# Before the handle_function_call dispatch:
-if function_name in ("write_file", "patch"):
-    # Determine working dir from the file path in the args
-    file_path = function_args.get("path", "") or function_args.get("old_string", "")
-    if file_path:
-        work_dir = str(Path(file_path).parent.resolve())
-        self._checkpoint_mgr.ensure_checkpoint(work_dir, f"before {function_name}")
-```
-
-This means:
-- First `write_file` in a turn → checkpoint (fast, one `git add -A && git commit`)
-- Subsequent writes in the same turn → no-op (already checkpointed)
-- Next turn (new user message) → fresh checkpoint eligibility
-
-### Config
-
-Add to `DEFAULT_CONFIG` in `hermes_cli/config.py`:
-
-```python
-"checkpoints": False,          # Enable filesystem checkpoints before destructive ops
-"checkpoint_max_snapshots": 50, # Max snapshots to keep per directory
-```
-
-User enables with:
-```yaml
-# ~/.hermes/config.yaml
-checkpoints: true
-```
-
-### User-Facing Rollback
-
-**CLI slash command** — add `/rollback` to `process_command()` in `cli.py`:
-
-```
-/rollback         — List recent checkpoints for the current directory
-/rollback <hash>  — Restore files to that checkpoint
-```
-
-Shows a numbered list:
-```
-📸 Checkpoints for /home/user/project:
-  1. abc1234  2026-03-09 21:15  before write_file (3 files changed)
-  2. def5678  2026-03-09 20:42  before patch (1 file changed)
-  3. ghi9012  2026-03-09 20:30  before write_file (2 files changed)
-
-Use /rollback <number> to restore, e.g. /rollback 1
-```
-
-**Gateway slash command** — add `/rollback` to gateway/run.py with the same behavior.
-
-**CLI subcommand** — `hermes rollback` (optional, lower priority).
-
-### What Gets Excluded (not checkpointed)
-
-Same as the PR's defaults — written to the shadow repo's `info/exclude`:
-
-```
-node_modules/
-dist/
-build/
-.env
-.env.*
-__pycache__/
-*.pyc
-.DS_Store
-*.log
-.cache/
-.venv/
-.git/
-```
-
-Also respects the project's `.gitignore` if present (shadow repo can read it via `core.excludesFile`).
-
-### Safety
-
-- `ensure_checkpoint()` wraps everything in try/except — a checkpoint failure never blocks the actual file operation
-- Shadow repo is completely isolated — GIT_DIR + GIT_WORK_TREE env vars, never touches user's .git
-- If git isn't installed, checkpoints silently disable
-- Large directories: add a file count check — skip checkpoint if >50K files to avoid slowdowns
-
-## Files to Create/Modify
-
-| File | Change |
-|------|--------|
-| `tools/checkpoint_manager.py` | **NEW** — CheckpointManager class (adapted from PR #559) |
-| `run_agent.py` | Add CheckpointManager init + trigger in `_execute_tool_calls()` |
-| `hermes_cli/config.py` | Add `checkpoints` + `checkpoint_max_snapshots` to DEFAULT_CONFIG |
-| `cli.py` | Add `/rollback` slash command handler |
-| `gateway/run.py` | Add `/rollback` slash command handler |
-| `tests/tools/test_checkpoint_manager.py` | **NEW** — tests (adapted from PR #559's tests) |
-
-## What We Take From PR #559
-
-- `_shadow_repo_path()` — deterministic path hashing ✅
-- `_git_env()` — GIT_DIR/GIT_WORK_TREE isolation ✅
-- `_run_git()` — subprocess wrapper with timeout ✅
-- `_init_shadow_repo()` — shadow repo initialization ✅
-- `DEFAULT_EXCLUDES` list ✅
-- Test structure and patterns ✅
-
-## What We Change From PR #559
-
-- **Remove tool schema/registry** — not a tool
-- **Remove injection into file_operations.py and patch_parser.py** — trigger from run_agent.py instead
-- **Add turn-scoped deduplication** — one checkpoint per turn, not per operation
-- **Add pruning** — keep last N snapshots
-- **Add config flag** — opt-in, not mandatory
-- **Add /rollback command** — user-facing restore UI
-- **Add file count guard** — skip huge directories
-
-## Implementation Order
-
-1. `tools/checkpoint_manager.py` — core class with take/list/restore/prune
-2. `tests/tools/test_checkpoint_manager.py` — tests
-3. `hermes_cli/config.py` — config keys
-4. `run_agent.py` — integration (init + trigger)
-5. `cli.py` — `/rollback` slash command
-6. `gateway/run.py` — `/rollback` slash command
-7. Full test suite run + manual smoke test

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hermes-agent"
-version = "0.2.0"
+version = "0.1.0"
 description = "The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -40,26 +40,16 @@ dependencies = [
 [project.optional-dependencies]
 modal = ["swe-rex[modal]>=1.4.0"]
 daytona = ["daytona>=0.148.0"]
-dev = ["pytest", "pytest-asyncio", "pytest-xdist", "mcp>=1.2.0"]
+dev = ["pytest", "pytest-asyncio"]
 messaging = ["python-telegram-bot>=20.0", "discord.py>=2.0", "aiohttp>=3.9.0", "slack-bolt>=1.18.0", "slack-sdk>=3.27.0"]
 cron = ["croniter"]
 slack = ["slack-bolt>=1.18.0", "slack-sdk>=3.27.0"]
 cli = ["simple-term-menu"]
 tts-premium = ["elevenlabs"]
-pty = [
-  "ptyprocess>=0.7.0; sys_platform != 'win32'",
-  "pywinpty>=2.0.0; sys_platform == 'win32'",
-]
+pty = ["ptyprocess>=0.7.0"]
 honcho = ["honcho-ai>=2.0.1"]
 mcp = ["mcp>=1.2.0"]
 homeassistant = ["aiohttp>=3.9.0"]
-rl = [
-  "atroposlib @ git+https://github.com/NousResearch/atropos.git",
-  "tinker @ git+https://github.com/thinking-machines-lab/tinker.git",
-  "fastapi>=0.104.0",
-  "uvicorn[standard]>=0.24.0",
-  "wandb>=0.15.0",
-]
 yc-bench = ["yc-bench @ git+https://github.com/collinear-ai/yc-bench.git"]
 all = [
   "hermes-agent[modal]",
@@ -91,4 +81,4 @@ testpaths = ["tests"]
 markers = [
     "integration: marks tests requiring external services (API keys, Modal, etc.)",
 ]
-addopts = "-m 'not integration' -n auto"
+addopts = "-m 'not integration'"

scripts/install.sh

@@ -492,23 +492,9 @@ install_system_packages() {
                         return 0
                     fi
                 fi
-            elif [ -e /dev/tty ]; then
-                # Non-interactive (e.g. curl | bash) but a terminal is available.
-                # Read the prompt from /dev/tty (same approach the setup wizard uses).
-                echo ""
-                log_info "Installing ${description} requires sudo."
-                read -p "Install? [Y/n] " -n 1 -r < /dev/tty
-                echo
-                if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
-                    if sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a $install_cmd < /dev/tty; then
-                        [ "$need_ripgrep" = true ] && HAS_RIPGREP=true && log_success "ripgrep installed"
-                        [ "$need_ffmpeg" = true ]  && HAS_FFMPEG=true  && log_success "ffmpeg installed"
-                        return 0
-                    fi
-                fi
             else
-                log_warn "Non-interactive mode and no terminal available — cannot install system packages"
-                log_info "Install manually after setup completes: sudo $install_cmd"
+                log_warn "Non-interactive mode: cannot prompt for sudo password"
+                log_info "Install missing packages manually: sudo $install_cmd"
             fi
         fi
     fi
@@ -572,16 +558,17 @@ clone_repo() {
         fi
     else
         # Try SSH first (for private repo access), fall back to HTTPS
+        # Use --recurse-submodules to also clone mini-swe-agent and tinker-atropos
         # GIT_SSH_COMMAND disables interactive prompts and sets a short timeout
         # so SSH fails fast instead of hanging when no key is configured.
         log_info "Trying SSH clone..."
         if GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=5" \
-           git clone --branch "$BRANCH" "$REPO_URL_SSH" "$INSTALL_DIR" 2>/dev/null; then
+           git clone --branch "$BRANCH" --recurse-submodules "$REPO_URL_SSH" "$INSTALL_DIR" 2>/dev/null; then
             log_success "Cloned via SSH"
         else
             rm -rf "$INSTALL_DIR" 2>/dev/null  # Clean up partial SSH clone
             log_info "SSH failed, trying HTTPS..."
-            if git clone --branch "$BRANCH" "$REPO_URL_HTTPS" "$INSTALL_DIR"; then
+            if git clone --branch "$BRANCH" --recurse-submodules "$REPO_URL_HTTPS" "$INSTALL_DIR"; then
                 log_success "Cloned via HTTPS"
             else
                 log_error "Failed to clone repository"
@@ -592,12 +579,10 @@ clone_repo() {
 
     cd "$INSTALL_DIR"
 
-    # Only init mini-swe-agent (terminal tool backend — required).
-    # tinker-atropos (RL training) is optional and heavy — users can opt in later
-    # with: git submodule update --init tinker-atropos && uv pip install -e ./tinker-atropos
-    log_info "Initializing mini-swe-agent submodule (terminal backend)..."
-    git submodule update --init mini-swe-agent
-    log_success "Submodule ready"
+    # Ensure submodules are initialized and updated (for existing installs or if --recurse failed)
+    log_info "Initializing submodules (mini-swe-agent, tinker-atropos)..."
+    git submodule update --init --recursive
+    log_success "Submodules ready"
 
     log_success "Repository ready"
 }
@@ -680,11 +665,12 @@ install_deps() {
         log_warn "mini-swe-agent not found (run: git submodule update --init)"
     fi
 
-    # tinker-atropos (RL training) is optional — skip by default.
-    # To enable RL tools: git submodule update --init tinker-atropos && uv pip install -e "./tinker-atropos"
+    log_info "Installing tinker-atropos (RL training backend)..."
     if [ -d "tinker-atropos" ] && [ -f "tinker-atropos/pyproject.toml" ]; then
-        log_info "tinker-atropos submodule found — skipping install (optional, for RL training)"
-        log_info "  To install: $UV_CMD pip install -e \"./tinker-atropos\""
+        $UV_CMD pip install -e "./tinker-atropos" || log_warn "tinker-atropos install failed (RL tools may not work)"
+        log_success "tinker-atropos installed"
+    else
+        log_warn "tinker-atropos not found (run: git submodule update --init)"
     fi
 
     log_success "All dependencies installed"

scripts/release.py

@@ -1,540 +0,0 @@
-#!/usr/bin/env python3
-"""Hermes Agent Release Script
-
-Generates changelogs and creates GitHub releases with CalVer tags.
-
-Usage:
-    # Preview changelog (dry run)
-    python scripts/release.py
-
-    # Preview with semver bump
-    python scripts/release.py --bump minor
-
-    # Create the release
-    python scripts/release.py --bump minor --publish
-
-    # First release (no previous tag)
-    python scripts/release.py --bump minor --publish --first-release
-
-    # Override CalVer date (e.g. for a belated release)
-    python scripts/release.py --bump minor --publish --date 2026.3.15
-"""
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-from collections import defaultdict
-from datetime import datetime
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-VERSION_FILE = REPO_ROOT / "hermes_cli" / "__init__.py"
-PYPROJECT_FILE = REPO_ROOT / "pyproject.toml"
-
-# ──────────────────────────────────────────────────────────────────────
-# Git email → GitHub username mapping
-# ──────────────────────────────────────────────────────────────────────
-
-# Auto-extracted from noreply emails + manual overrides
-AUTHOR_MAP = {
-    # teknium (multiple emails)
-    "teknium1@gmail.com": "teknium1",
-    "teknium@nousresearch.com": "teknium1",
-    "127238744+teknium1@users.noreply.github.com": "teknium1",
-    # contributors (from noreply pattern)
-    "35742124+0xbyt4@users.noreply.github.com": "0xbyt4",
-    "82637225+kshitijk4poor@users.noreply.github.com": "kshitijk4poor",
-    "16443023+stablegenius49@users.noreply.github.com": "stablegenius49",
-    "185121704+stablegenius49@users.noreply.github.com": "stablegenius49",
-    "101283333+batuhankocyigit@users.noreply.github.com": "batuhankocyigit",
-    "126368201+vilkasdev@users.noreply.github.com": "vilkasdev",
-    "137614867+cutepawss@users.noreply.github.com": "cutepawss",
-    "96793918+memosr@users.noreply.github.com": "memosr",
-    "131039422+SHL0MS@users.noreply.github.com": "SHL0MS",
-    "77628552+raulvidis@users.noreply.github.com": "raulvidis",
-    "145567217+Aum08Desai@users.noreply.github.com": "Aum08Desai",
-    "256820943+kshitij-eliza@users.noreply.github.com": "kshitij-eliza",
-    "44278268+shitcoinsherpa@users.noreply.github.com": "shitcoinsherpa",
-    "104278804+Sertug17@users.noreply.github.com": "Sertug17",
-    "112503481+caentzminger@users.noreply.github.com": "caentzminger",
-    "258577966+voidborne-d@users.noreply.github.com": "voidborne-d",
-    "70424851+insecurejezza@users.noreply.github.com": "insecurejezza",
-    "259807879+Bartok9@users.noreply.github.com": "Bartok9",
-    # contributors (manual mapping from git names)
-    "dmayhem93@gmail.com": "dmahan93",
-    "samherring99@gmail.com": "samherring99",
-    "desaiaum08@gmail.com": "Aum08Desai",
-    "shannon.sands.1979@gmail.com": "shannonsands",
-    "shannon@nousresearch.com": "shannonsands",
-    "eri@plasticlabs.ai": "Erosika",
-    "hjcpuro@gmail.com": "hjc-puro",
-    "xaydinoktay@gmail.com": "aydnOktay",
-    "abdullahfarukozden@gmail.com": "Farukest",
-    "lovre.pesut@gmail.com": "rovle",
-    "hakanerten02@hotmail.com": "teyrebaz33",
-    "alireza78.crypto@gmail.com": "alireza78a",
-    "brooklyn.bb.nicholson@gmail.com": "brooklynnicholson",
-    "gpickett00@gmail.com": "gpickett00",
-    "mcosma@gmail.com": "wakamex",
-    "clawdia.nash@proton.me": "clawdia-nash",
-    "pickett.austin@gmail.com": "austinpickett",
-    "jaisehgal11299@gmail.com": "jaisup",
-    "percydikec@gmail.com": "PercyDikec",
-    "dean.kerr@gmail.com": "deankerr",
-    "socrates1024@gmail.com": "socrates1024",
-    "satelerd@gmail.com": "satelerd",
-    "numman.ali@gmail.com": "nummanali",
-    "0xNyk@users.noreply.github.com": "0xNyk",
-    "0xnykcd@googlemail.com": "0xNyk",
-    "buraysandro9@gmail.com": "buray",
-    "contact@jomar.fr": "joshmartinelle",
-    "camilo@tekelala.com": "tekelala",
-    "vincentcharlebois@gmail.com": "vincentcharlebois",
-    "aryan@synvoid.com": "aryansingh",
-    "johnsonblake1@gmail.com": "blakejohnson",
-    "bryan@intertwinesys.com": "bryanyoung",
-    "christo.mitov@gmail.com": "christomitov",
-    "hermes@nousresearch.com": "NousResearch",
-    "openclaw@sparklab.ai": "openclaw",
-    "semihcvlk53@gmail.com": "Himess",
-    "erenkar950@gmail.com": "erenkarakus",
-    "adavyasharma@gmail.com": "adavyas",
-    "acaayush1111@gmail.com": "aayushchaudhary",
-    "jason@outland.art": "jasonoutland",
-    "mrflu1918@proton.me": "SPANISHFLU",
-    "morganemoss@gmai.com": "mormio",
-    "kopjop926@gmail.com": "cesareth",
-    "fuleinist@gmail.com": "fuleinist",
-    "jack.47@gmail.com": "JackTheGit",
-    "dalvidjr2022@gmail.com": "Jr-kenny",
-    "m@statecraft.systems": "mbierling",
-    "balyan.sid@gmail.com": "balyansid",
-}
-
-
-def git(*args, cwd=None):
-    """Run a git command and return stdout."""
-    result = subprocess.run(
-        ["git"] + list(args),
-        capture_output=True, text=True,
-        cwd=cwd or str(REPO_ROOT),
-    )
-    if result.returncode != 0:
-        print(f"git {' '.join(args)} failed: {result.stderr}", file=sys.stderr)
-        return ""
-    return result.stdout.strip()
-
-
-def get_last_tag():
-    """Get the most recent CalVer tag."""
-    tags = git("tag", "--list", "v20*", "--sort=-v:refname")
-    if tags:
-        return tags.split("\n")[0]
-    return None
-
-
-def get_current_version():
-    """Read current semver from __init__.py."""
-    content = VERSION_FILE.read_text()
-    match = re.search(r'__version__\s*=\s*"([^"]+)"', content)
-    return match.group(1) if match else "0.0.0"
-
-
-def bump_version(current: str, part: str) -> str:
-    """Bump a semver version string."""
-    parts = current.split(".")
-    if len(parts) != 3:
-        parts = ["0", "0", "0"]
-    major, minor, patch = int(parts[0]), int(parts[1]), int(parts[2])
-
-    if part == "major":
-        major += 1
-        minor = 0
-        patch = 0
-    elif part == "minor":
-        minor += 1
-        patch = 0
-    elif part == "patch":
-        patch += 1
-    else:
-        raise ValueError(f"Unknown bump part: {part}")
-
-    return f"{major}.{minor}.{patch}"
-
-
-def update_version_files(semver: str, calver_date: str):
-    """Update version strings in source files."""
-    # Update __init__.py
-    content = VERSION_FILE.read_text()
-    content = re.sub(
-        r'__version__\s*=\s*"[^"]+"',
-        f'__version__ = "{semver}"',
-        content,
-    )
-    content = re.sub(
-        r'__release_date__\s*=\s*"[^"]+"',
-        f'__release_date__ = "{calver_date}"',
-        content,
-    )
-    VERSION_FILE.write_text(content)
-
-    # Update pyproject.toml
-    pyproject = PYPROJECT_FILE.read_text()
-    pyproject = re.sub(
-        r'^version\s*=\s*"[^"]+"',
-        f'version = "{semver}"',
-        pyproject,
-        flags=re.MULTILINE,
-    )
-    PYPROJECT_FILE.write_text(pyproject)
-
-
-def resolve_author(name: str, email: str) -> str:
-    """Resolve a git author to a GitHub @mention."""
-    # Try email lookup first
-    gh_user = AUTHOR_MAP.get(email)
-    if gh_user:
-        return f"@{gh_user}"
-
-    # Try noreply pattern
-    noreply_match = re.match(r"(\d+)\+(.+)@users\.noreply\.github\.com", email)
-    if noreply_match:
-        return f"@{noreply_match.group(2)}"
-
-    # Try username@users.noreply.github.com
-    noreply_match2 = re.match(r"(.+)@users\.noreply\.github\.com", email)
-    if noreply_match2:
-        return f"@{noreply_match2.group(1)}"
-
-    # Fallback to git name
-    return name
-
-
-def categorize_commit(subject: str) -> str:
-    """Categorize a commit by its conventional commit prefix."""
-    subject_lower = subject.lower()
-
-    # Match conventional commit patterns
-    patterns = {
-        "breaking": [r"^breaking[\s:(]", r"^!:", r"BREAKING CHANGE"],
-        "features": [r"^feat[\s:(]", r"^feature[\s:(]", r"^add[\s:(]"],
-        "fixes": [r"^fix[\s:(]", r"^bugfix[\s:(]", r"^bug[\s:(]", r"^hotfix[\s:(]"],
-        "improvements": [r"^improve[\s:(]", r"^perf[\s:(]", r"^enhance[\s:(]",
-                         r"^refactor[\s:(]", r"^cleanup[\s:(]", r"^clean[\s:(]",
-                         r"^update[\s:(]", r"^optimize[\s:(]"],
-        "docs": [r"^doc[\s:(]", r"^docs[\s:(]"],
-        "tests": [r"^test[\s:(]", r"^tests[\s:(]"],
-        "chore": [r"^chore[\s:(]", r"^ci[\s:(]", r"^build[\s:(]",
-                  r"^deps[\s:(]", r"^bump[\s:(]"],
-    }
-
-    for category, regexes in patterns.items():
-        for regex in regexes:
-            if re.match(regex, subject_lower):
-                return category
-
-    # Heuristic fallbacks
-    if any(w in subject_lower for w in ["add ", "new ", "implement", "support "]):
-        return "features"
-    if any(w in subject_lower for w in ["fix ", "fixed ", "resolve", "patch "]):
-        return "fixes"
-    if any(w in subject_lower for w in ["refactor", "cleanup", "improve", "update "]):
-        return "improvements"
-
-    return "other"
-
-
-def clean_subject(subject: str) -> str:
-    """Clean up a commit subject for display."""
-    # Remove conventional commit prefix
-    cleaned = re.sub(r"^(feat|fix|docs|chore|refactor|test|perf|ci|build|improve|add|update|cleanup|hotfix|breaking|enhance|optimize|bugfix|bug|feature|tests|deps|bump)[\s:(!]+\s*", "", subject, flags=re.IGNORECASE)
-    # Remove trailing issue refs that are redundant with PR links
-    cleaned = cleaned.strip()
-    # Capitalize first letter
-    if cleaned:
-        cleaned = cleaned[0].upper() + cleaned[1:]
-    return cleaned
-
-
-def get_commits(since_tag=None):
-    """Get commits since a tag (or all commits if None)."""
-    if since_tag:
-        range_spec = f"{since_tag}..HEAD"
-    else:
-        range_spec = "HEAD"
-
-    # Format: hash|author_name|author_email|subject
-    log = git(
-        "log", range_spec,
-        "--format=%H|%an|%ae|%s",
-        "--no-merges",
-    )
-
-    if not log:
-        return []
-
-    commits = []
-    for line in log.split("\n"):
-        if not line.strip():
-            continue
-        parts = line.split("|", 3)
-        if len(parts) != 4:
-            continue
-        sha, name, email, subject = parts
-        commits.append({
-            "sha": sha,
-            "short_sha": sha[:8],
-            "author_name": name,
-            "author_email": email,
-            "subject": subject,
-            "category": categorize_commit(subject),
-            "github_author": resolve_author(name, email),
-        })
-
-    return commits
-
-
-def get_pr_number(subject: str) -> str:
-    """Extract PR number from commit subject if present."""
-    match = re.search(r"#(\d+)", subject)
-    if match:
-        return match.group(1)
-    return None
-
-
-def generate_changelog(commits, tag_name, semver, repo_url="https://github.com/NousResearch/hermes-agent",
-                       prev_tag=None, first_release=False):
-    """Generate markdown changelog from categorized commits."""
-    lines = []
-
-    # Header
-    now = datetime.now()
-    date_str = now.strftime("%B %d, %Y")
-    lines.append(f"# Hermes Agent v{semver} ({tag_name})")
-    lines.append("")
-    lines.append(f"**Release Date:** {date_str}")
-    lines.append("")
-
-    if first_release:
-        lines.append("> 🎉 **First official release!** This marks the beginning of regular weekly releases")
-        lines.append("> for Hermes Agent. See below for everything included in this initial release.")
-        lines.append("")
-
-    # Group commits by category
-    categories = defaultdict(list)
-    all_authors = set()
-    teknium_aliases = {"@teknium1"}
-
-    for commit in commits:
-        categories[commit["category"]].append(commit)
-        author = commit["github_author"]
-        if author not in teknium_aliases:
-            all_authors.add(author)
-
-    # Category display order and emoji
-    category_order = [
-        ("breaking", "⚠️ Breaking Changes"),
-        ("features", "✨ Features"),
-        ("improvements", "🔧 Improvements"),
-        ("fixes", "🐛 Bug Fixes"),
-        ("docs", "📚 Documentation"),
-        ("tests", "🧪 Tests"),
-        ("chore", "🏗️ Infrastructure"),
-        ("other", "📦 Other Changes"),
-    ]
-
-    for cat_key, cat_title in category_order:
-        cat_commits = categories.get(cat_key, [])
-        if not cat_commits:
-            continue
-
-        lines.append(f"## {cat_title}")
-        lines.append("")
-
-        for commit in cat_commits:
-            subject = clean_subject(commit["subject"])
-            pr_num = get_pr_number(commit["subject"])
-            author = commit["github_author"]
-
-            # Build the line
-            parts = [f"- {subject}"]
-            if pr_num:
-                parts.append(f"([#{pr_num}]({repo_url}/pull/{pr_num}))")
-            else:
-                parts.append(f"([`{commit['short_sha']}`]({repo_url}/commit/{commit['sha']}))")
-
-            if author not in teknium_aliases:
-                parts.append(f"— {author}")
-
-            lines.append(" ".join(parts))
-
-        lines.append("")
-
-    # Contributors section
-    if all_authors:
-        # Sort contributors by commit count
-        author_counts = defaultdict(int)
-        for commit in commits:
-            author = commit["github_author"]
-            if author not in teknium_aliases:
-                author_counts[author] += 1
-
-        sorted_authors = sorted(author_counts.items(), key=lambda x: -x[1])
-
-        lines.append("## 👥 Contributors")
-        lines.append("")
-        lines.append("Thank you to everyone who contributed to this release!")
-        lines.append("")
-        for author, count in sorted_authors:
-            commit_word = "commit" if count == 1 else "commits"
-            lines.append(f"- {author} ({count} {commit_word})")
-        lines.append("")
-
-    # Full changelog link
-    if prev_tag:
-        lines.append(f"**Full Changelog**: [{prev_tag}...{tag_name}]({repo_url}/compare/{prev_tag}...{tag_name})")
-    else:
-        lines.append(f"**Full Changelog**: [{tag_name}]({repo_url}/commits/{tag_name})")
-    lines.append("")
-
-    return "\n".join(lines)
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Hermes Agent Release Tool")
-    parser.add_argument("--bump", choices=["major", "minor", "patch"],
-                        help="Which semver component to bump")
-    parser.add_argument("--publish", action="store_true",
-                        help="Actually create the tag and GitHub release (otherwise dry run)")
-    parser.add_argument("--date", type=str,
-                        help="Override CalVer date (format: YYYY.M.D)")
-    parser.add_argument("--first-release", action="store_true",
-                        help="Mark as first release (no previous tag expected)")
-    parser.add_argument("--output", type=str,
-                        help="Write changelog to file instead of stdout")
-    args = parser.parse_args()
-
-    # Determine CalVer date
-    if args.date:
-        calver_date = args.date
-    else:
-        now = datetime.now()
-        calver_date = f"{now.year}.{now.month}.{now.day}"
-
-    tag_name = f"v{calver_date}"
-
-    # Check for existing tag with same date
-    existing = git("tag", "--list", tag_name)
-    if existing and not args.publish:
-        # Append a suffix for same-day releases
-        suffix = 2
-        while git("tag", "--list", f"{tag_name}.{suffix}"):
-            suffix += 1
-        tag_name = f"{tag_name}.{suffix}"
-        calver_date = f"{calver_date}.{suffix}"
-        print(f"Note: Tag {tag_name[:-2]} already exists, using {tag_name}")
-
-    # Determine semver
-    current_version = get_current_version()
-    if args.bump:
-        new_version = bump_version(current_version, args.bump)
-    else:
-        new_version = current_version
-
-    # Get previous tag
-    prev_tag = get_last_tag()
-    if not prev_tag and not args.first_release:
-        print("No previous tags found. Use --first-release for the initial release.")
-        print(f"Would create tag: {tag_name}")
-        print(f"Would set version: {new_version}")
-
-    # Get commits
-    commits = get_commits(since_tag=prev_tag)
-    if not commits:
-        print("No new commits since last tag.")
-        if not args.first_release:
-            return
-
-    print(f"{'='*60}")
-    print(f"  Hermes Agent Release Preview")
-    print(f"{'='*60}")
-    print(f"  CalVer tag:      {tag_name}")
-    print(f"  SemVer:          v{current_version} → v{new_version}")
-    print(f"  Previous tag:    {prev_tag or '(none — first release)'}")
-    print(f"  Commits:         {len(commits)}")
-    print(f"  Unique authors:  {len(set(c['github_author'] for c in commits))}")
-    print(f"  Mode:            {'PUBLISH' if args.publish else 'DRY RUN'}")
-    print(f"{'='*60}")
-    print()
-
-    # Generate changelog
-    changelog = generate_changelog(
-        commits, tag_name, new_version,
-        prev_tag=prev_tag,
-        first_release=args.first_release,
-    )
-
-    if args.output:
-        Path(args.output).write_text(changelog)
-        print(f"Changelog written to {args.output}")
-    else:
-        print(changelog)
-
-    if args.publish:
-        print(f"\n{'='*60}")
-        print("  Publishing release...")
-        print(f"{'='*60}")
-
-        # Update version files
-        if args.bump:
-            update_version_files(new_version, calver_date)
-            print(f"  ✓ Updated version files to v{new_version} ({calver_date})")
-
-            # Commit version bump
-            git("add", str(VERSION_FILE), str(PYPROJECT_FILE))
-            git("commit", "-m", f"chore: bump version to v{new_version} ({calver_date})")
-            print(f"  ✓ Committed version bump")
-
-        # Create annotated tag
-        git("tag", "-a", tag_name, "-m",
-            f"Hermes Agent v{new_version} ({calver_date})\n\nWeekly release")
-        print(f"  ✓ Created tag {tag_name}")
-
-        # Push
-        push_result = git("push", "origin", "HEAD", "--tags")
-        print(f"  ✓ Pushed to origin")
-
-        # Create GitHub release
-        changelog_file = REPO_ROOT / ".release_notes.md"
-        changelog_file.write_text(changelog)
-
-        result = subprocess.run(
-            ["gh", "release", "create", tag_name,
-             "--title", f"Hermes Agent v{new_version} ({calver_date})",
-             "--notes-file", str(changelog_file)],
-            capture_output=True, text=True,
-            cwd=str(REPO_ROOT),
-        )
-
-        changelog_file.unlink(missing_ok=True)
-
-        if result.returncode == 0:
-            print(f"  ✓ GitHub release created: {result.stdout.strip()}")
-        else:
-            print(f"  ✗ GitHub release failed: {result.stderr}")
-            print(f"    Tag was created. Create the release manually:")
-            print(f"    gh release create {tag_name} --title 'Hermes Agent v{new_version} ({calver_date})'")
-
-        print(f"\n  🎉 Release v{new_version} ({tag_name}) published!")
-    else:
-        print(f"\n{'='*60}")
-        print(f"  Dry run complete. To publish, add --publish")
-        print(f"  Example: python scripts/release.py --bump minor --publish")
-        print(f"{'='*60}")
-
-
-if __name__ == "__main__":
-    main()

skills/creative/DESCRIPTION.md

@@ -1,3 +0,0 @@
----
-description: Creative content generation — ASCII art, hand-drawn style diagrams, and visual design tools.
----

skills/creative/ascii-art/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ascii-art
-description: Generate ASCII art using pyfiglet (571 fonts), cowsay, boxes, toilet, image-to-ascii, remote APIs (asciified, ascii.co.uk), and LLM fallback. No API keys required.
-version: 4.0.0
+description: Generate ASCII art using pyfiglet (571 fonts), cowsay, boxes, toilet, image-to-ascii conversion, and search curated art from emojicombos.com and asciiart.eu (11,000+ artworks). Falls back to LLM-generated art.
+version: 3.1.0
 author: 0xbyt4, Hermes Agent
 license: MIT
 dependencies: []
@@ -14,9 +14,9 @@ metadata:
 
 # ASCII Art Skill
 
-Multiple tools for different ASCII art needs. All tools are local CLI programs or free REST APIs — no API keys required.
+Multiple tools for different ASCII art needs. All tools are local CLI programs — no API keys required.
 
-## Tool 1: Text Banners (pyfiglet — local)
+## Tool 1: Text Banners (pyfiglet)
 
 Render text as large ASCII art banners. 571 built-in fonts.
 
@@ -53,35 +53,7 @@ python3 -m pyfiglet --list_fonts             # List all 571 fonts
 - Short text (1-8 chars) works best with detailed fonts like `doom` or `block`
 - Long text works better with compact fonts like `small` or `mini`
 
-## Tool 2: Text Banners (asciified API — remote, no install)
-
-Free REST API that converts text to ASCII art. 250+ FIGlet fonts. Returns plain text directly — no parsing needed. Use this when pyfiglet is not installed or as a quick alternative.
-
-### Usage (via terminal curl)
-
-```bash
-# Basic text banner (default font)
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello+World"
-
-# With a specific font
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Slant"
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Doom"
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Star+Wars"
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=3-D"
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=Hello&font=Banner3"
-
-# List all available fonts (returns JSON array)
-curl -s "https://asciified.thelicato.io/api/v2/fonts"
-```
-
-### Tips
-
-- URL-encode spaces as `+` in the text parameter
-- The response is plain text ASCII art — no JSON wrapping, ready to display
-- Font names are case-sensitive; use the fonts endpoint to get exact names
-- Works from any terminal with curl — no Python or pip needed
-
-## Tool 3: Cowsay (Message Art)
+## Tool 2: Cowsay (Message Art)
 
 Classic tool that wraps text in a speech bubble with an ASCII character.
 
@@ -125,7 +97,7 @@ cowsay -e "OO" "Msg"   # Custom eyes
 cowsay -T "U " "Msg"   # Custom tongue
 ```
 
-## Tool 4: Boxes (Decorative Borders)
+## Tool 3: Boxes (Decorative Borders)
 
 Draw decorative ASCII art borders/frames around any text. 70+ built-in designs.
 
@@ -152,15 +124,13 @@ echo "Hello World" | boxes -a c               # Center text
 boxes -l                                       # List all 70+ designs
 ```
 
-### Combine with pyfiglet or asciified
+### Combine with pyfiglet
 
 ```bash
 python3 -m pyfiglet "HERMES" -f slant | boxes -d stone
-# Or without pyfiglet installed:
-curl -s "https://asciified.thelicato.io/api/v2/ascii?text=HERMES&font=Slant" | boxes -d stone
 ```
 
-## Tool 5: TOIlet (Colored Text Art)
+## Tool 4: TOIlet (Colored Text Art)
 
 Like pyfiglet but with ANSI color effects and visual filters. Great for terminal eye candy.
 
@@ -190,14 +160,14 @@ toilet -F list                          # List available filters
 
 **Note**: toilet outputs ANSI escape codes for colors — works in terminals but may not render in all contexts (e.g., plain text files, some chat platforms).
 
-## Tool 6: Image to ASCII Art
+## Tool 5: Image to ASCII Art
 
 Convert images (PNG, JPEG, GIF, WEBP) to ASCII art.
 
 ### Option A: ascii-image-converter (recommended, modern)
 
 ```bash
-# Install
+# Install via snap or Go
 sudo snap install ascii-image-converter
 # OR: go install github.com/TheZoraiz/ascii-image-converter@latest
 ```
@@ -220,77 +190,63 @@ jp2a --width=80 image.jpg
 jp2a --colors image.jpg              # Colorized
 ```
 
-## Tool 7: Search Pre-Made ASCII Art
+## Tool 6: Search Pre-Made ASCII Art (Web APIs)
 
-Search curated ASCII art from the web. Use `terminal` with `curl`.
+Search curated ASCII art databases via `web_extract`. No API keys needed.
 
-### Source A: ascii.co.uk (recommended for pre-made art)
+### Source A: emojicombos.com (recommended first)
 
-Large collection of classic ASCII art organized by subject. Art is inside HTML `<pre>` tags. Fetch the page with curl, then extract art with a small Python snippet.
+Huge collection of ASCII art, dot art, kaomoji, and emoji combos. Modern, meme-aware, user-submitted content. Great for pop culture, animals, objects, aesthetics.
 
-**URL pattern:** `https://ascii.co.uk/art/{subject}`
+**URL pattern:** `https://emojicombos.com/{term}-ascii-art`
 
-**Step 1 — Fetch the page:**
-
-```bash
-curl -s 'https://ascii.co.uk/art/cat' -o /tmp/ascii_art.html
 ```
-
-**Step 2 — Extract art from pre tags:**
-
-```python
-import re, html
-with open('/tmp/ascii_art.html') as f:
-    text = f.read()
-arts = re.findall(r'<pre[^>]*>(.*?)</pre>', text, re.DOTALL)
-for art in arts:
-    clean = re.sub(r'<[^>]+>', '', art)
-    clean = html.unescape(clean).strip()
-    if len(clean) > 30:
-        print(clean)
-        print('\n---\n')
+web_extract(urls=["https://emojicombos.com/cat-ascii-art"])
+web_extract(urls=["https://emojicombos.com/rocket-ascii-art"])
+web_extract(urls=["https://emojicombos.com/dragon-ascii-art"])
+web_extract(urls=["https://emojicombos.com/skull-ascii-art"])
+web_extract(urls=["https://emojicombos.com/heart-ascii-art"])
 ```
 
-**Available subjects** (use as URL path):
-- Animals: `cat`, `dog`, `horse`, `bird`, `fish`, `dragon`, `snake`, `rabbit`, `elephant`, `dolphin`, `butterfly`, `owl`, `wolf`, `bear`, `penguin`, `turtle`
-- Objects: `car`, `ship`, `airplane`, `rocket`, `guitar`, `computer`, `coffee`, `beer`, `cake`, `house`, `castle`, `sword`, `crown`, `key`
-- Nature: `tree`, `flower`, `sun`, `moon`, `star`, `mountain`, `ocean`, `rainbow`
-- Characters: `skull`, `robot`, `angel`, `wizard`, `pirate`, `ninja`, `alien`
-- Holidays: `christmas`, `halloween`, `valentine`
-
 **Tips:**
-- Preserve artist signatures/initials — important etiquette
-- Multiple art pieces per page — pick the best one for the user
-- Works reliably via curl, no JavaScript needed
+- Use hyphenated search terms: `hello-kitty-ascii-art`, `star-wars-ascii-art`
+- Returns a mix of classic ASCII, Braille dot art, and kaomoji — pick the best style for the user
+- Includes modern meme art and pop culture references
+- Great for kaomoji/emoticons too: `https://emojicombos.com/cat-kaomoji`
 
-### Source B: GitHub Octocat API (fun easter egg)
+### Source B: asciiart.eu (classic archive)
 
-Returns a random GitHub Octocat with a wise quote. No auth needed.
+11,000+ classic ASCII artworks organized by category. More traditional/vintage art.
+
+**Browse by category** (use as URL paths):
+- `animals/cats`, `animals/dogs`, `animals/birds`, `animals/horses`
+- `animals/dolphins`, `animals/dragons`, `animals/insects`
+- `space/rockets`, `space/stars`, `space/planets`
+- `vehicles/cars`, `vehicles/ships`, `vehicles/airplanes`
+- `food-and-drinks/coffee`, `food-and-drinks/beer`
+- `computers/computers`, `electronics/robots`
+- `art-and-design/hearts`, `art-and-design/skulls`
+- `plants/flowers`, `plants/trees`
+- `mythology/dragons`, `mythology/unicorns`
+
+```
+web_extract(urls=["https://www.asciiart.eu/animals/cats"])
+web_extract(urls=["https://www.asciiart.eu/search?q=rocket"])
+```
+
+**Tips:**
+- Preserve artist initials/signatures (e.g., `jgs`, `hjw`) — this is important etiquette
+- Better for classic/vintage ASCII art style
+
+### Source C: GitHub Octocat API (fun easter egg)
+
+Returns a random GitHub Octocat with a quote. No auth needed.
 
 ```bash
 curl -s https://api.github.com/octocat
 ```
 
-## Tool 8: Fun ASCII Utilities (via curl)
-
-These free services return ASCII art directly — great for fun extras.
-
-### QR Codes as ASCII Art
-
-```bash
-curl -s "qrenco.de/Hello+World"
-curl -s "qrenco.de/https://example.com"
-```
-
-### Weather as ASCII Art
-
-```bash
-curl -s "wttr.in/London"          # Full weather report with ASCII graphics
-curl -s "wttr.in/Moon"            # Moon phase in ASCII art
-curl -s "v2.wttr.in/London"       # Detailed version
-```
-
-## Tool 9: LLM-Generated Custom Art (Fallback)
+## Tool 7: LLM-Generated Custom Art (Fallback)
 
 When tools above don't have what's needed, generate ASCII art directly using these Unicode characters:
 
@@ -308,14 +264,28 @@ When tools above don't have what's needed, generate ASCII art directly using the
 - Max height: 15 lines for banners, 25 for scenes
 - Monospace only: output must render correctly in fixed-width fonts
 
+## Fun Extras
+
+### Star Wars in ASCII (via telnet)
+
+```bash
+telnet towel.blinkenlights.nl
+```
+
+### Useful Resources
+
+- [asciiart.eu](https://www.asciiart.eu/) — 11,000+ artworks, searchable
+- [patorjk.com/software/taag](http://patorjk.com/software/taag/) — Web-based text-to-ASCII with font preview
+- [asciiflow.com](http://asciiflow.com/) — Interactive ASCII diagram editor (browser)
+- [awesome-ascii-art](https://github.com/moul/awesome-ascii-art) — Curated resource list
+
 ## Decision Flow
 
-1. **Text as a banner** → pyfiglet if installed, otherwise asciified API via curl
+1. **Text as a banner** → pyfiglet (or toilet for colored output)
 2. **Wrap a message in fun character art** → cowsay
-3. **Add decorative border/frame** → boxes (can combine with pyfiglet/asciified)
-4. **Art of a specific thing** (cat, rocket, dragon) → ascii.co.uk via curl + parsing
-5. **Convert an image to ASCII** → ascii-image-converter or jp2a
-6. **QR code** → qrenco.de via curl
-7. **Weather/moon art** → wttr.in via curl
-8. **Something custom/creative** → LLM generation with Unicode palette
-9. **Any tool not installed** → install it, or fall back to next option
+3. **Add decorative border/frame** → boxes (can combine with pyfiglet)
+4. **Art of a thing** (cat, rocket, dragon) → emojicombos.com first, then asciiart.eu
+5. **Kaomoji / emoticons** → emojicombos.com (`{term}-kaomoji`)
+6. **Convert an image to ASCII** → ascii-image-converter or jp2a
+7. **Something custom/creative** → LLM generation with Unicode palette
+8. **Any tool not installed** → install it, or fall back to next option

skills/creative/ascii-video/SKILL.md

@@ -1,250 +0,0 @@
----
-name: ascii-video
-description: "Production pipeline for ASCII art video — any format. Converts video/audio/images/generative input into colored ASCII character video output (MP4, GIF, image sequence). Covers: video-to-ASCII conversion, audio-reactive music visualizers, generative ASCII art animations, hybrid video+audio reactive, text/lyrics overlays, real-time terminal rendering. Use when users request: ASCII video, text art video, terminal-style video, character art animation, retro text visualization, audio visualizer in ASCII, converting video to ASCII art, matrix-style effects, or any animated ASCII output."
----
-
-# ASCII Video Production Pipeline
-
-Full production pipeline for rendering any content as colored ASCII character video.
-
-## Modes
-
-| Mode | Input | Output | Read |
-|------|-------|--------|------|
-| **Video-to-ASCII** | Video file | ASCII recreation of source footage | `references/inputs.md` § Video Sampling |
-| **Audio-reactive** | Audio file | Generative visuals driven by audio features | `references/inputs.md` § Audio Analysis |
-| **Generative** | None (or seed params) | Procedural ASCII animation | `references/effects.md` |
-| **Hybrid** | Video + audio | ASCII video with audio-reactive overlays | Both input refs |
-| **Lyrics/text** | Audio + text/SRT | Timed text with visual effects | `references/inputs.md` § Text/Lyrics |
-| **TTS narration** | Text quotes + TTS API | Narrated testimonial/quote video with typed text | `references/inputs.md` § TTS Integration |
-
-## Stack
-
-Single self-contained Python script per project. No GPU.
-
-| Layer | Tool | Purpose |
-|-------|------|---------|
-| Core | Python 3.10+, NumPy | Math, array ops, vectorized effects |
-| Signal | SciPy | FFT, peak detection (audio modes only) |
-| Imaging | Pillow (PIL) | Font rasterization, video frame decoding, image I/O |
-| Video I/O | ffmpeg (CLI) | Decode input, encode output segments, mux audio, mix tracks |
-| Parallel | concurrent.futures / multiprocessing | N workers for batch/clip rendering |
-| TTS | ElevenLabs API (or similar) | Generate narration clips for quote/testimonial videos |
-| Optional | OpenCV | Video frame sampling, edge detection, optical flow |
-
-## Pipeline Architecture (v2)
-
-Every mode follows the same 6-stage pipeline. See `references/architecture.md` for implementation details, `references/scenes.md` for scene protocol, and `references/composition.md` for multi-grid composition and tonemap.
-
-```
-┌─────────┐   ┌──────────┐   ┌───────────┐   ┌──────────┐   ┌─────────┐   ┌────────┐
-│ 1.INPUT  │→│ 2.ANALYZE │→│ 3.SCENE_FN │→│ 4.TONEMAP │→│ 5.SHADE  │→│ 6.ENCODE│
-│ load src │  │ features  │  │ → canvas   │  │ normalize │  │ post-fx  │  │ → video │
-└─────────┘   └──────────┘   └───────────┘   └──────────┘   └─────────┘   └────────┘
-```
-
-1. **INPUT** — Load/decode source material (video frames, audio samples, images, or nothing)
-2. **ANALYZE** — Extract per-frame features (audio bands, video luminance/edges, motion vectors)
-3. **SCENE_FN** — Scene function renders directly to pixel canvas (`uint8 H,W,3`). May internally compose multiple character grids via `_render_vf()` + pixel blend modes. See `references/composition.md`
-4. **TONEMAP** — Percentile-based adaptive brightness normalization with per-scene gamma. Replaces linear brightness multipliers. See `references/composition.md` § Adaptive Tonemap
-5. **SHADE** — Apply post-processing `ShaderChain` + `FeedbackBuffer`. See `references/shaders.md`
-6. **ENCODE** — Pipe raw RGB frames to ffmpeg for H.264/GIF encoding
-
-## Creative Direction
-
-**Every project should look and feel different.** The references provide a vocabulary of building blocks — don't copy them verbatim. Combine, modify, and invent.
-
-### Aesthetic Dimensions to Vary
-
-| Dimension | Options | Reference |
-|-----------|---------|-----------|
-| **Character palette** | Density ramps, block elements, symbols, scripts (katakana, Greek, runes, braille), dots, project-specific | `architecture.md` § Character Palettes |
-| **Color strategy** | HSV (angle/distance/time/value mapped), discrete RGB palettes, monochrome, complementary, triadic, temperature | `architecture.md` § Color System |
-| **Color tint** | Warm, cool, amber, matrix green, neon pink, sepia, ice, blood, void, sunset | `shaders.md` § Color Grade |
-| **Background texture** | Sine fields, noise, smooth noise, cellular/voronoi, video source | `effects.md` § Background Fills |
-| **Primary effects** | Rings, spirals, tunnel, vortex, waves, interference, aurora, ripple, fire | `effects.md` § Radial / Wave / Fire |
-| **Particles** | Energy sparks, snow, rain, bubbles, runes, binary data, orbits, gravity wells | `effects.md` § Particle Systems |
-| **Shader mood** | Retro CRT, clean modern, glitch art, cinematic, dreamy, harsh industrial, psychedelic | `shaders.md` § Design Philosophy |
-| **Grid density** | xs(8px) through xxl(40px), mixed per layer | `architecture.md` § Grid System |
-| **Font** | Menlo, Monaco, Courier, SF Mono, JetBrains Mono, Fira Code, IBM Plex | `architecture.md` § Font Selection |
-| **Mirror mode** | None, horizontal, vertical, quad, diagonal, kaleidoscope | `shaders.md` § Mirror Effects |
-| **Transition style** | Crossfade, wipe (directional/radial), dissolve, glitch cut | `shaders.md` § Transitions |
-
-### Per-Section Variation
-
-Never use the same config for the entire video. For each section/scene/quote:
-- Choose a **different background effect** (or compose 2-3)
-- Choose a **different character palette** (match the mood)
-- Choose a **different color strategy** (or at minimum a different hue)
-- Vary **shader intensity** (more bloom during peaks, more grain during quiet)
-- Use **different particle types** if particles are active
-
-### Project-Specific Invention
-
-For every project, invent at least one of:
-- A custom character palette matching the theme
-- A custom background effect (combine/modify existing ones)
-- A custom color palette (discrete RGB set matching the brand/mood)
-- A custom particle character set
-
-## Workflow
-
-### Step 1: Determine Mode and Gather Requirements
-
-Establish with user:
-- **Input source** — file path, format, duration
-- **Mode** — which of the 6 modes above
-- **Sections** — time-mapped style changes (timestamps → effect names)
-- **Resolution** — default 1920x1080 @ 24fps; GIFs typically 640x360 @ 15fps
-- **Style direction** — dense/sparse, bright/dark, chaotic/minimal, color palette
-- **Text/branding** — easter eggs, overlays, credits, themed character sets
-- **Output format** — MP4 (default), GIF, PNG sequence
-
-### Step 2: Detect Hardware and Set Quality
-
-Before building the script, detect the user's hardware and set appropriate defaults. See `references/optimization.md` § Hardware Detection.
-
-```python
-hw = detect_hardware()
-profile = quality_profile(hw, target_duration, user_quality_pref)
-log(f"Hardware: {hw['cpu_count']} cores, {hw['mem_gb']:.1f}GB RAM")
-log(f"Render: {profile['vw']}x{profile['vh']} @{profile['fps']}fps, {profile['workers']} workers")
-```
-
-Never hardcode worker counts, resolution, or CRF. Always detect and adapt.
-
-### Step 3: Build the Script
-
-Write as a single Python file. Major components:
-
-1. **Hardware detection + quality profile** — see `references/optimization.md`
-2. **Input loader** — mode-dependent; see `references/inputs.md`
-3. **Feature analyzer** — audio FFT, video luminance, or pass-through
-4. **Grid + renderer** — multi-density character grids with bitmap cache; `_render_vf()` helper for value/hue field → canvas
-5. **Character palettes** — multiple palettes chosen per project theme; see `references/architecture.md`
-6. **Color system** — HSV + discrete RGB palettes as needed; see `references/architecture.md`
-7. **Scene functions** — each returns `canvas (uint8 H,W,3)` directly. May compose multiple grids internally via pixel blend modes. See `references/scenes.md` + `references/composition.md`
-8. **Tonemap** — adaptive brightness normalization with per-scene gamma; see `references/composition.md`
-9. **Shader pipeline** — `ShaderChain` + `FeedbackBuffer` per-section config; see `references/shaders.md`
-10. **Scene table + dispatcher** — maps time ranges to scene functions + shader/feedback configs; see `references/scenes.md`
-11. **Parallel encoder** — N-worker batch clip rendering with ffmpeg pipes
-12. **Main** — orchestrate full pipeline
-
-### Step 4: Handle Critical Bugs
-
-#### Font Cell Height (macOS Pillow)
-
-`textbbox()` returns wrong height. Use `font.getmetrics()`:
-
-```python
-ascent, descent = font.getmetrics()
-cell_height = ascent + descent  # correct
-```
-
-#### ffmpeg Pipe Deadlock
-
-Never use `stderr=subprocess.PIPE` with long-running ffmpeg. Redirect to file:
-
-```python
-stderr_fh = open(err_path, "w")
-pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=stderr_fh)
-```
-
-#### Brightness — Use `tonemap()`, Not Linear Multipliers
-
-ASCII on black is inherently dark. This is the #1 visual issue. **Do NOT use linear `* N` brightness multipliers** — they clip highlights and wash out the image. Instead, use the **adaptive tonemap** function from `references/composition.md`:
-
-```python
-def tonemap(canvas, gamma=0.75):
-    """Percentile-based adaptive normalization + gamma. Replaces all brightness multipliers."""
-    f = canvas.astype(np.float32)
-    lo = np.percentile(f, 1)          # black point (1st percentile)
-    hi = np.percentile(f, 99.5)       # white point (99.5th percentile)
-    if hi - lo < 1: hi = lo + 1
-    f = (f - lo) / (hi - lo)
-    f = np.clip(f, 0, 1) ** gamma     # gamma < 1 = brighter mids
-    return (f * 255).astype(np.uint8)
-```
-
-Pipeline ordering: `scene_fn() → tonemap() → FeedbackBuffer → ShaderChain → ffmpeg`
-
-Per-scene gamma overrides for destructive effects:
-- Default: `gamma=0.75`
-- Solarize scenes: `gamma=0.55` (solarize darkens above-threshold pixels)
-- Posterize scenes: `gamma=0.50` (quantization loses brightness range)
-- Already-bright scenes: `gamma=0.85`
-
-Additional brightness best practices:
-- Dense animated backgrounds — never flat black, always fill the grid
-- Vignette minimum clamped to 0.15 (not 0.12)
-- Bloom threshold lowered to 130 (not 170) so more pixels contribute to glow
-- Use `screen` blend mode (not `overlay`) when compositing dark ASCII layers — overlay squares dark values: `2 * 0.12 * 0.12 = 0.03`
-
-#### Font Compatibility
-
-Not all Unicode characters render in all fonts. Validate palettes at init:
-```python
-for c in palette:
-    img = Image.new("L", (20, 20), 0)
-    ImageDraw.Draw(img).text((0, 0), c, fill=255, font=font)
-    if np.array(img).max() == 0:
-        log(f"WARNING: char '{c}' (U+{ord(c):04X}) not in font, removing from palette")
-```
-
-### Step 4b: Per-Clip Architecture (for segmented videos)
-
-When the video has discrete segments (quotes, scenes, chapters), render each as a separate clip file. This enables:
-- Re-rendering individual clips without touching the rest (`--clip q05`)
-- Faster iteration on specific sections
-- Easy reordering or trimming in post
-
-```python
-segments = [
-    {"id": "intro", "start": 0.0, "end": 5.0, "type": "intro"},
-    {"id": "q00", "start": 5.0, "end": 12.0, "type": "quote", "qi": 0, ...},
-    {"id": "t00", "start": 12.0, "end": 13.5, "type": "transition", ...},
-    {"id": "outro", "start": 208.0, "end": 211.6, "type": "outro"},
-]
-
-from concurrent.futures import ProcessPoolExecutor, as_completed
-with ProcessPoolExecutor(max_workers=hw["workers"]) as pool:
-    futures = {pool.submit(render_clip, seg, features, path): seg["id"]
-               for seg, path in clip_args}
-    for fut in as_completed(futures):
-        fut.result()
-```
-
-CLI: `--clip q00 t00 q01` to re-render specific clips, `--list` to show segments, `--skip-render` to re-stitch only.
-
-### Step 5: Render and Iterate
-
-Performance targets per frame:
-
-| Component | Budget |
-|-----------|--------|
-| Feature extraction | 1-5ms |
-| Effect function | 2-15ms |
-| Character render | 80-150ms (bottleneck) |
-| Shader pipeline | 5-25ms |
-| **Total** | ~100-200ms/frame |
-
-**Fast iteration**: render single test frames to check brightness/layout before full render:
-```python
-canvas = render_single_frame(frame_index, features, renderer)
-Image.fromarray(canvas).save("test.png")
-```
-
-**Brightness verification**: sample 5-10 frames across video, check `mean > 8` for ASCII content.
-
-## References
-
-| File | Contents |
-|------|----------|
-| `references/architecture.md` | Grid system, font selection, character palettes (library of 20+), color system (HSV + discrete RGB), `_render_vf()` helper, compositing, v2 effect function contract |
-| `references/inputs.md` | All input sources: audio analysis, video sampling, image conversion, text/lyrics, TTS integration (ElevenLabs, voice assignment, audio mixing) |
-| `references/effects.md` | Effect building blocks: 12 value field generators (`vf_sinefield` through `vf_noise_static`), 8 hue field generators (`hf_fixed` through `hf_plasma`), radial/wave/fire effects, particles, composing guide |
-| `references/shaders.md` | 38 shader implementations (geometry, channel, color, glow, noise, pattern, tone, glitch, mirror), `ShaderChain` class, full `_apply_shader_step()` dispatch, audio-reactive scaling, transitions, tint presets |
-| `references/composition.md` | **v2 core**: pixel blend modes (20 modes with implementations), multi-grid composition, `_render_vf()` helper, adaptive `tonemap()`, per-scene gamma, `FeedbackBuffer` with spatial transforms, `PixelBlendStack` |
-| `references/scenes.md` | **v2 scene protocol**: scene function contract, `Renderer` class, `SCENES` table structure, `render_clip()` loop, beat-synced cutting, parallel rendering + pickling constraints, 4 complete scene examples, scene design checklist |
-| `references/troubleshooting.md` | NumPy broadcasting traps, blend mode pitfalls, multiprocessing/pickling issues, brightness diagnostics, ffmpeg deadlocks, font issues, performance bottlenecks, common mistakes |
-| `references/optimization.md` | Hardware detection, adaptive quality profiles (draft/preview/production/max), CLI integration, vectorized effect patterns, parallel rendering, memory management |

skills/creative/ascii-video/references/architecture.md

@@ -1,528 +0,0 @@
-# Architecture Reference
-
-## Grid System
-
-### Multi-Density Grids
-
-Pre-initialize multiple grid sizes. Switch per section for visual variety.
-
-| Key | Font Size | Grid (1920x1080) | Use |
-|-----|-----------|-------------------|-----|
-| xs | 8 | 400x108 | Ultra-dense data fields |
-| sm | 10 | 320x83 | Dense detail, rain, starfields |
-| md | 16 | 192x56 | Default balanced, transitions |
-| lg | 20 | 160x45 | Quote/lyric text (readable at 1080p) |
-| xl | 24 | 137x37 | Short quotes, large titles |
-| xxl | 40 | 80x22 | Giant text, minimal |
-
-**Grid sizing for text-heavy content**: When displaying readable text (quotes, lyrics, testimonials), use 20px (`lg`) as the primary grid. This gives 160 columns -- plenty for lines up to ~50 chars centered. For very short quotes (< 60 chars, <= 3 lines), 24px (`xl`) makes them more impactful. Only init the grids you actually use -- each grid pre-rasterizes all characters which costs ~0.3-0.5s.
-
-Grid dimensions: `cols = VW // cell_width`, `rows = VH // cell_height`.
-
-### Font Selection
-
-Don't hardcode a single font. Choose fonts to match the project's mood. Monospace fonts are required for grid alignment but vary widely in personality:
-
-| Font | Personality | Platform |
-|------|-------------|----------|
-| Menlo | Clean, neutral, Apple-native | macOS |
-| Monaco | Retro terminal, compact | macOS |
-| Courier New | Classic typewriter, wide | Cross-platform |
-| SF Mono | Modern, tight spacing | macOS |
-| Consolas | Windows native, clean | Windows |
-| JetBrains Mono | Developer, ligature-ready | Install |
-| Fira Code | Geometric, modern | Install |
-| IBM Plex Mono | Corporate, authoritative | Install |
-| Source Code Pro | Adobe, balanced | Install |
-
-**Font detection at init**: probe available fonts and fall back gracefully:
-
-```python
-import platform
-
-def find_font(preferences):
-    """Try fonts in order, return first that exists."""
-    for name, path in preferences:
-        if os.path.exists(path):
-            return path
-    raise FileNotFoundError(f"No monospace font found. Tried: {[p for _,p in preferences]}")
-
-FONT_PREFS_MACOS = [
-    ("Menlo", "/System/Library/Fonts/Menlo.ttc"),
-    ("Monaco", "/System/Library/Fonts/Monaco.ttf"),
-    ("SF Mono", "/System/Library/Fonts/SFNSMono.ttf"),
-    ("Courier", "/System/Library/Fonts/Courier.ttc"),
-]
-FONT_PREFS_LINUX = [
-    ("DejaVu Sans Mono", "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"),
-    ("Liberation Mono", "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf"),
-    ("Noto Sans Mono", "/usr/share/fonts/truetype/noto/NotoSansMono-Regular.ttf"),
-    ("Ubuntu Mono", "/usr/share/fonts/truetype/ubuntu/UbuntuMono-R.ttf"),
-]
-FONT_PREFS = FONT_PREFS_MACOS if platform.system() == "Darwin" else FONT_PREFS_LINUX
-```
-
-**Multi-font rendering**: use different fonts for different layers (e.g., monospace for background, a bolder variant for overlay text). Each GridLayer owns its own font:
-
-```python
-grid_bg = GridLayer(find_font(FONT_PREFS), 16)       # background
-grid_text = GridLayer(find_font(BOLD_PREFS), 20)      # readable text
-```
-
-### Collecting All Characters
-
-Before initializing grids, gather all characters that need bitmap pre-rasterization:
-
-```python
-all_chars = set()
-for pal in [PAL_DEFAULT, PAL_DENSE, PAL_BLOCKS, PAL_RUNE, PAL_KATA,
-            PAL_GREEK, PAL_MATH, PAL_DOTS, PAL_BRAILLE, PAL_STARS,
-            PAL_BINARY, PAL_MUSIC, PAL_BOX, PAL_CIRCUIT, PAL_ARROWS,
-            PAL_HERMES]:  # ... all palettes used in project
-    all_chars.update(pal)
-# Add any overlay text characters
-all_chars.update("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 .,-:;!?/|")
-all_chars.discard(" ")  # space is never rendered
-```
-
-### GridLayer Initialization
-
-Each grid pre-computes coordinate arrays for vectorized effect math:
-
-```python
-class GridLayer:
-    def __init__(self, font_path, font_size):
-        self.font = ImageFont.truetype(font_path, font_size)
-        asc, desc = self.font.getmetrics()
-        bbox = self.font.getbbox("M")
-        self.cw = bbox[2] - bbox[0]  # character cell width
-        self.ch = asc + desc  # CRITICAL: not textbbox height
-
-        self.cols = VW // self.cw
-        self.rows = VH // self.ch
-        self.ox = (VW - self.cols * self.cw) // 2  # centering
-        self.oy = (VH - self.rows * self.ch) // 2
-
-        # Index arrays
-        self.rr = np.arange(self.rows, dtype=np.float32)[:, None]
-        self.cc = np.arange(self.cols, dtype=np.float32)[None, :]
-
-        # Polar coordinates (aspect-corrected)
-        cx, cy = self.cols / 2.0, self.rows / 2.0
-        asp = self.cw / self.ch
-        self.dx = self.cc - cx
-        self.dy = (self.rr - cy) * asp
-        self.dist = np.sqrt(self.dx**2 + self.dy**2)
-        self.angle = np.arctan2(self.dy, self.dx)
-
-        # Normalized (0-1 range) -- for distance falloff
-        self.dx_n = (self.cc - cx) / max(self.cols, 1)
-        self.dy_n = (self.rr - cy) / max(self.rows, 1) * asp
-        self.dist_n = np.sqrt(self.dx_n**2 + self.dy_n**2)
-
-        # Pre-rasterize all characters to float32 bitmaps
-        self.bm = {}
-        for c in all_chars:
-            img = Image.new("L", (self.cw, self.ch), 0)
-            ImageDraw.Draw(img).text((0, 0), c, fill=255, font=self.font)
-            self.bm[c] = np.array(img, dtype=np.float32) / 255.0
-```
-
-### Character Render Loop
-
-The bottleneck. Composites pre-rasterized bitmaps onto pixel canvas:
-
-```python
-def render(self, chars, colors, canvas=None):
-    if canvas is None:
-        canvas = np.zeros((VH, VW, 3), dtype=np.uint8)
-    for row in range(self.rows):
-        y = self.oy + row * self.ch
-        if y + self.ch > VH: break
-        for col in range(self.cols):
-            c = chars[row, col]
-            if c == " ": continue
-            x = self.ox + col * self.cw
-            if x + self.cw > VW: break
-            a = self.bm[c]  # float32 bitmap
-            canvas[y:y+self.ch, x:x+self.cw] = np.maximum(
-                canvas[y:y+self.ch, x:x+self.cw],
-                (a[:, :, None] * colors[row, col]).astype(np.uint8))
-    return canvas
-```
-
-Use `np.maximum` for additive blending (brighter chars overwrite dimmer ones, never darken).
-
-### Multi-Layer Rendering
-
-Render multiple grids onto the same canvas for depth:
-
-```python
-canvas = np.zeros((VH, VW, 3), dtype=np.uint8)
-canvas = grid_lg.render(bg_chars, bg_colors, canvas)   # background layer
-canvas = grid_md.render(main_chars, main_colors, canvas)  # main layer
-canvas = grid_sm.render(detail_chars, detail_colors, canvas)  # detail overlay
-```
-
----
-
-## Character Palettes
-
-### Design Principles
-
-Character palettes are the primary visual texture of ASCII video. They control not just brightness mapping but the entire visual feel. Design palettes intentionally:
-
-- **Visual weight**: characters sorted by the amount of ink/pixels they fill. Space is always index 0.
-- **Coherence**: characters within a palette should belong to the same visual family.
-- **Density curve**: the brightness-to-character mapping is nonlinear. Dense palettes (many chars) give smoother gradients; sparse palettes (5-8 chars) give posterized/graphic looks.
-- **Rendering compatibility**: every character in the palette must exist in the font. Test at init and remove missing glyphs.
-
-### Palette Library
-
-Organized by visual family. Mix and match per project -- don't default to PAL_DEFAULT for everything.
-
-#### Density / Brightness Palettes
-```python
-PAL_DEFAULT  = " .`'-:;!><=+*^~?/|(){}[]#&$@%"       # classic ASCII art
-PAL_DENSE    = " .:;+=xX$#@\u2588"                          # simple 11-level ramp
-PAL_MINIMAL  = " .:-=+#@"                               # 8-level, graphic
-PAL_BINARY   = " \u2588"                                      # 2-level, extreme contrast
-PAL_GRADIENT = " \u2591\u2592\u2593\u2588"                              # 4-level block gradient
-```
-
-#### Unicode Block Elements
-```python
-PAL_BLOCKS   = " \u2591\u2592\u2593\u2588\u2584\u2580\u2590\u258c"                 # standard blocks
-PAL_BLOCKS_EXT = " \u2596\u2597\u2598\u2599\u259a\u259b\u259c\u259d\u259e\u259f\u2591\u2592\u2593\u2588"  # quadrant blocks (more detail)
-PAL_SHADE    = " \u2591\u2592\u2593\u2588\u2587\u2586\u2585\u2584\u2583\u2582\u2581"          # vertical fill progression
-```
-
-#### Symbolic / Thematic
-```python
-PAL_MATH     = " \u00b7\u2218\u2219\u2022\u00b0\u00b1\u2213\u00d7\u00f7\u2248\u2260\u2261\u2264\u2265\u221e\u222b\u2211\u220f\u221a\u2207\u2202\u2206\u03a9"    # math symbols
-PAL_BOX      = " \u2500\u2502\u250c\u2510\u2514\u2518\u251c\u2524\u252c\u2534\u253c\u2550\u2551\u2554\u2557\u255a\u255d\u2560\u2563\u2566\u2569\u256c"          # box drawing
-PAL_CIRCUIT  = " .\u00b7\u2500\u2502\u250c\u2510\u2514\u2518\u253c\u25cb\u25cf\u25a1\u25a0\u2206\u2207\u2261"                 # circuit board
-PAL_RUNE     = " .\u16a0\u16a2\u16a6\u16b1\u16b7\u16c1\u16c7\u16d2\u16d6\u16da\u16de\u16df"                   # elder futhark runes
-PAL_ALCHEMIC = " \u2609\u263d\u2640\u2642\u2643\u2644\u2645\u2646\u2647\u2648\u2649\u264a\u264b"            # planetary/alchemical symbols
-PAL_ZODIAC   = " \u2648\u2649\u264a\u264b\u264c\u264d\u264e\u264f\u2650\u2651\u2652\u2653"            # zodiac
-PAL_ARROWS   = " \u2190\u2191\u2192\u2193\u2194\u2195\u2196\u2197\u2198\u2199\u21a9\u21aa\u21bb\u27a1"             # directional arrows
-PAL_MUSIC    = " \u266a\u266b\u266c\u2669\u266d\u266e\u266f\u25cb\u25cf"                       # musical notation
-```
-
-#### Script / Writing System
-```python
-PAL_KATA     = " \u00b7\uff66\uff67\uff68\uff69\uff6a\uff6b\uff6c\uff6d\uff6e\uff6f\uff70\uff71\uff72\uff73\uff74\uff75\uff76\uff77"          # katakana halfwidth (matrix rain)
-PAL_GREEK    = " \u03b1\u03b2\u03b3\u03b4\u03b5\u03b6\u03b7\u03b8\u03b9\u03ba\u03bb\u03bc\u03bd\u03be\u03c0\u03c1\u03c3\u03c4\u03c6\u03c8\u03c9"    # Greek lowercase
-PAL_CYRILLIC = " \u0430\u0431\u0432\u0433\u0434\u0435\u0436\u0437\u0438\u043a\u043b\u043c\u043d\u043e\u043f\u0440\u0441\u0442\u0443\u0444\u0445\u0446\u0447\u0448"  # Cyrillic lowercase
-PAL_ARABIC   = " \u0627\u0628\u062a\u062b\u062c\u062d\u062e\u062f\u0630\u0631\u0632\u0633\u0634\u0635\u0636\u0637"       # Arabic letters (isolated forms)
-```
-
-#### Dot / Point Progressions
-```python
-PAL_DOTS     = " \u22c5\u2218\u2219\u25cf\u25c9\u25ce\u25c6\u2726\u2605"                   # dot size progression
-PAL_BRAILLE  = " \u2801\u2802\u2803\u2804\u2805\u2806\u2807\u2808\u2809\u280a\u280b\u280c\u280d\u280e\u280f\u2810\u2811\u2812\u2813\u2814\u2815\u2816\u2817\u2818\u2819\u281a\u281b\u281c\u281d\u281e\u281f\u283f"  # braille patterns
-PAL_STARS    = " \u00b7\u2727\u2726\u2729\u2728\u2605\u2736\u2733\u2738"               # star progression
-```
-
-#### Project-Specific (examples -- invent new ones per project)
-```python
-PAL_HERMES   = " .\u00b7~=\u2248\u221e\u26a1\u263f\u2726\u2605\u2295\u25ca\u25c6\u25b2\u25bc\u25cf\u25a0"   # mythology/tech blend
-PAL_OCEAN    = " ~\u2248\u2248\u2248\u223c\u2307\u2248\u224b\u224c\u2248"                       # water/wave characters
-PAL_ORGANIC  = " .\u00b0\u2218\u2022\u25e6\u25c9\u2742\u273f\u2741\u2743"                 # growing/botanical
-PAL_MACHINE  = " _\u2500\u2502\u250c\u2510\u253c\u2261\u25a0\u2588\u2593\u2592\u2591"             # mechanical/industrial
-```
-
-### Creating Custom Palettes
-
-When designing for a project, build palettes from the content's theme:
-
-1. **Choose a visual family** (dots, blocks, symbols, script)
-2. **Sort by visual weight** -- render each char at target font size, count lit pixels, sort ascending
-3. **Test at target grid size** -- some chars collapse to blobs at small sizes
-4. **Validate in font** -- remove chars the font can't render:
-
-```python
-def validate_palette(pal, font):
-    """Remove characters the font can't render."""
-    valid = []
-    for c in pal:
-        if c == " ":
-            valid.append(c)
-            continue
-        img = Image.new("L", (20, 20), 0)
-        ImageDraw.Draw(img).text((0, 0), c, fill=255, font=font)
-        if np.array(img).max() > 0:  # char actually rendered something
-            valid.append(c)
-    return "".join(valid)
-```
-
-### Mapping Values to Characters
-
-```python
-def val2char(v, mask, pal=PAL_DEFAULT):
-    """Map float array (0-1) to character array using palette."""
-    n = len(pal)
-    idx = np.clip((v * n).astype(int), 0, n - 1)
-    out = np.full(v.shape, " ", dtype="U1")
-    for i, ch in enumerate(pal):
-        out[mask & (idx == i)] = ch
-    return out
-```
-
-**Nonlinear mapping** for different visual curves:
-
-```python
-def val2char_gamma(v, mask, pal, gamma=1.0):
-    """Gamma-corrected palette mapping. gamma<1 = brighter, gamma>1 = darker."""
-    v_adj = np.power(np.clip(v, 0, 1), gamma)
-    return val2char(v_adj, mask, pal)
-
-def val2char_step(v, mask, pal, thresholds):
-    """Custom threshold mapping. thresholds = list of float breakpoints."""
-    out = np.full(v.shape, pal[0], dtype="U1")
-    for i, thr in enumerate(thresholds):
-        out[mask & (v > thr)] = pal[min(i + 1, len(pal) - 1)]
-    return out
-```
-
----
-
-## Color System
-
-### HSV->RGB (Vectorized)
-
-All color computation in HSV for intuitive control, converted at render time:
-
-```python
-def hsv2rgb(h, s, v):
-    """Vectorized HSV->RGB. h,s,v are numpy arrays. Returns (R,G,B) uint8 arrays."""
-    h = h % 1.0
-    c = v * s; x = c * (1 - np.abs((h*6) % 2 - 1)); m = v - c
-    # ... 6 sector assignment ...
-    return (np.clip((r+m)*255, 0, 255).astype(np.uint8),
-            np.clip((g+m)*255, 0, 255).astype(np.uint8),
-            np.clip((b+m)*255, 0, 255).astype(np.uint8))
-```
-
-### Color Mapping Strategies
-
-Don't default to a single strategy. Choose based on the visual intent:
-
-| Strategy | Hue source | Effect | Good for |
-|----------|------------|--------|----------|
-| Angle-mapped | `g.angle / (2*pi)` | Rainbow around center | Radial effects, kaleidoscopes |
-| Distance-mapped | `g.dist_n * 0.3` | Gradient from center | Tunnels, depth effects |
-| Frequency-mapped | `f["cent"] * 0.2` | Timbral color shifting | Audio-reactive |
-| Value-mapped | `val * 0.15` | Brightness-dependent hue | Fire, heat maps |
-| Time-cycled | `t * rate` | Slow color rotation | Ambient, chill |
-| Source-sampled | Video frame pixel colors | Preserve original color | Video-to-ASCII |
-| Palette-indexed | Discrete color lookup | Flat graphic style | Retro, pixel art |
-| Temperature | Blend between warm/cool | Emotional tone | Mood-driven scenes |
-| Complementary | `hue` and `hue + 0.5` | High contrast | Bold, dramatic |
-| Triadic | `hue`, `hue + 0.33`, `hue + 0.66` | Vibrant, balanced | Psychedelic |
-| Analogous | `hue +/- 0.08` | Harmonious, subtle | Elegant, cohesive |
-| Monochrome | Fixed hue, vary S and V | Restrained, focused | Noir, minimal |
-
-### Color Palettes (Discrete RGB)
-
-For non-HSV workflows -- direct RGB color sets for graphic/retro looks:
-
-```python
-# Named color palettes -- use for flat/graphic styles or per-character coloring
-COLORS_NEON = [(255,0,102), (0,255,153), (102,0,255), (255,255,0), (0,204,255)]
-COLORS_PASTEL = [(255,179,186), (255,223,186), (255,255,186), (186,255,201), (186,225,255)]
-COLORS_MONO_GREEN = [(0,40,0), (0,80,0), (0,140,0), (0,200,0), (0,255,0)]
-COLORS_MONO_AMBER = [(40,20,0), (80,50,0), (140,90,0), (200,140,0), (255,191,0)]
-COLORS_CYBERPUNK = [(255,0,60), (0,255,200), (180,0,255), (255,200,0)]
-COLORS_VAPORWAVE = [(255,113,206), (1,205,254), (185,103,255), (5,255,161)]
-COLORS_EARTH = [(86,58,26), (139,90,43), (189,154,91), (222,193,136), (245,230,193)]
-COLORS_ICE = [(200,230,255), (150,200,240), (100,170,230), (60,130,210), (30,80,180)]
-COLORS_BLOOD = [(80,0,0), (140,10,10), (200,20,20), (255,50,30), (255,100,80)]
-COLORS_FOREST = [(10,30,10), (20,60,15), (30,100,20), (50,150,30), (80,200,50)]
-
-def rgb_palette_map(val, mask, palette):
-    """Map float array (0-1) to RGB colors from a discrete palette."""
-    n = len(palette)
-    idx = np.clip((val * n).astype(int), 0, n - 1)
-    R = np.zeros(val.shape, dtype=np.uint8)
-    G = np.zeros(val.shape, dtype=np.uint8)
-    B = np.zeros(val.shape, dtype=np.uint8)
-    for i, (r, g, b) in enumerate(palette):
-        m = mask & (idx == i)
-        R[m] = r; G[m] = g; B[m] = b
-    return R, G, B
-```
-
-### Compositing Helpers
-
-```python
-def mkc(R, G, B, rows, cols):
-    """Pack 3 uint8 arrays into (rows, cols, 3) color array."""
-    o = np.zeros((rows, cols, 3), dtype=np.uint8)
-    o[:,:,0] = R; o[:,:,1] = G; o[:,:,2] = B
-    return o
-
-def layer_over(base_ch, base_co, top_ch, top_co):
-    """Composite top layer onto base. Non-space chars overwrite."""
-    m = top_ch != " "
-    base_ch[m] = top_ch[m]; base_co[m] = top_co[m]
-    return base_ch, base_co
-
-def layer_blend(base_co, top_co, alpha):
-    """Alpha-blend top color layer onto base. alpha is float array (0-1) or scalar."""
-    if isinstance(alpha, (int, float)):
-        alpha = np.full(base_co.shape[:2], alpha, dtype=np.float32)
-    a = alpha[:,:,None]
-    return np.clip(base_co * (1 - a) + top_co * a, 0, 255).astype(np.uint8)
-
-def stamp(ch, co, text, row, col, color=(255,255,255)):
-    """Write text string at position."""
-    for i, c in enumerate(text):
-        cc = col + i
-        if 0 <= row < ch.shape[0] and 0 <= cc < ch.shape[1]:
-            ch[row, cc] = c; co[row, cc] = color
-```
-
----
-
-## Section System
-
-Map time ranges to effect functions + shader configs + grid sizes:
-
-```python
-SECTIONS = [
-    (0.0, "void"), (3.94, "starfield"), (21.0, "matrix"),
-    (46.0, "drop"), (130.0, "glitch"), (187.0, "outro"),
-]
-
-FX_DISPATCH = {"void": fx_void, "starfield": fx_starfield, ...}
-SECTION_FX = {"void": {"vignette": 0.3, "bloom": 170}, ...}
-SECTION_GRID = {"void": "md", "starfield": "sm", "drop": "lg", ...}
-SECTION_MIRROR = {"drop": "h", "bass_rings": "quad"}
-
-def get_section(t):
-    sec = SECTIONS[0][1]
-    for ts, name in SECTIONS:
-        if t >= ts: sec = name
-    return sec
-```
-
----
-
-## Parallel Encoding
-
-Split frames across N workers. Each pipes raw RGB to its own ffmpeg subprocess:
-
-```python
-def render_batch(batch_id, frame_start, frame_end, features, seg_path):
-    r = Renderer()
-    cmd = ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
-           "-s", f"{VW}x{VH}", "-r", str(FPS), "-i", "pipe:0",
-           "-c:v", "libx264", "-preset", "fast", "-crf", "18",
-           "-pix_fmt", "yuv420p", seg_path]
-
-    # CRITICAL: stderr to file, not pipe
-    stderr_fh = open(os.path.join(workdir, f"err_{batch_id:02d}.log"), "w")
-    pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
-                            stdout=subprocess.DEVNULL, stderr=stderr_fh)
-
-    for fi in range(frame_start, frame_end):
-        t = fi / FPS
-        sec = get_section(t)
-        f = {k: float(features[k][fi]) for k in features}
-        ch, co = FX_DISPATCH[sec](r, f, t)
-        canvas = r.render(ch, co)
-        canvas = apply_mirror(canvas, sec, f)
-        canvas = apply_shaders(canvas, sec, f, t)
-        pipe.stdin.write(canvas.tobytes())
-
-    pipe.stdin.close()
-    pipe.wait()
-    stderr_fh.close()
-```
-
-Concatenate segments + mux audio:
-
-```python
-# Write concat file
-with open(concat_path, "w") as cf:
-    for seg in segments:
-        cf.write(f"file '{seg}'\n")
-
-subprocess.run(["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", concat_path,
-                "-i", audio_path, "-c:v", "copy", "-c:a", "aac", "-b:a", "192k",
-                "-shortest", output_path])
-```
-
-## Effect Function Contract
-
-### v2 Protocol (Current)
-
-Every scene function: `(renderer, features_dict, time_float, state_dict) -> canvas_uint8`
-
-```python
-def fx_example(r, f, t, S):
-    """Scene function returns a full pixel canvas (uint8 H,W,3).
-    Scenes have full control over multi-grid rendering and pixel-level composition.
-    """
-    # Render multiple layers at different grid densities
-    canvas_a = _render_vf(r, "md", vf_plasma, hf_angle(0.0), PAL_DENSE, f, t, S)
-    canvas_b = _render_vf(r, "sm", vf_vortex, hf_time_cycle(0.1), PAL_RUNE, f, t, S)
-
-    # Pixel-level blend
-    result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
-    return result
-```
-
-See `references/scenes.md` for the full scene protocol, the Renderer class, `_render_vf()` helper, and complete scene examples.
-
-See `references/composition.md` for blend modes, tone mapping, feedback buffers, and multi-grid composition.
-
-### v1 Protocol (Legacy)
-
-Simple scenes that use a single grid can still return `(chars, colors)` and let the caller handle rendering, but the v2 canvas protocol is preferred for all new code.
-
-```python
-def fx_simple(r, f, t, S):
-    g = r.get_grid("md")
-    val = np.sin(g.dist * 0.1 - t * 3) * f.get("bass", 0.3) * 2
-    val = np.clip(val, 0, 1); mask = val > 0.03
-    ch = val2char(val, mask, PAL_DEFAULT)
-    R, G, B = hsv2rgb(np.full_like(val, 0.6), np.full_like(val, 0.7), val)
-    co = mkc(R, G, B, g.rows, g.cols)
-    return g.render(ch, co)  # returns canvas directly
-```
-
-### Persistent State
-
-Effects that need state across frames (particles, rain columns) use the `S` dict parameter (which is `r.S` — same object, but passed explicitly for clarity):
-
-```python
-def fx_with_state(r, f, t, S):
-    if "particles" not in S:
-        S["particles"] = initialize_particles()
-    update_particles(S["particles"])
-    # ...
-```
-
-State persists across frames within a single scene/clip. Each worker process (and each scene) gets its own independent state.
-
-### Helper Functions
-
-```python
-def hsv2rgb_scalar(h, s, v):
-    """Single-value HSV to RGB. Returns (R, G, B) tuple of ints 0-255."""
-    h = h % 1.0
-    c = v * s; x = c * (1 - abs((h * 6) % 2 - 1)); m = v - c
-    if h * 6 < 1:   r, g, b = c, x, 0
-    elif h * 6 < 2:  r, g, b = x, c, 0
-    elif h * 6 < 3:  r, g, b = 0, c, x
-    elif h * 6 < 4:  r, g, b = 0, x, c
-    elif h * 6 < 5:  r, g, b = x, 0, c
-    else:             r, g, b = c, 0, x
-    return (int((r+m)*255), int((g+m)*255), int((b+m)*255))
-
-def log(msg):
-    """Print timestamped log message."""
-    print(msg, flush=True)
-```

skills/creative/ascii-video/references/composition.md

@@ -1,476 +0,0 @@
-# Composition & Brightness Reference
-
-The composable system is the core of visual complexity. It operates at three levels: pixel-level blend modes, multi-grid composition, and adaptive brightness management. This document covers all three.
-
-## Pixel-Level Blend Modes
-
-### The `blend_canvas()` Function
-
-All blending operates on full pixel canvases (`uint8 H,W,3`). Internally converts to float32 [0,1] for precision, blends, lerps by opacity, converts back.
-
-```python
-def blend_canvas(base, top, mode="normal", opacity=1.0):
-    af = base.astype(np.float32) / 255.0
-    bf = top.astype(np.float32) / 255.0
-    fn = BLEND_MODES.get(mode, BLEND_MODES["normal"])
-    result = fn(af, bf)
-    if opacity < 1.0:
-        result = af * (1 - opacity) + result * opacity
-    return np.clip(result * 255, 0, 255).astype(np.uint8)
-```
-
-### 20 Blend Modes
-
-```python
-BLEND_MODES = {
-    # Basic arithmetic
-    "normal":       lambda a, b: b,
-    "add":          lambda a, b: np.clip(a + b, 0, 1),
-    "subtract":     lambda a, b: np.clip(a - b, 0, 1),
-    "multiply":     lambda a, b: a * b,
-    "screen":       lambda a, b: 1 - (1 - a) * (1 - b),
-
-    # Contrast
-    "overlay":      lambda a, b: np.where(a < 0.5, 2*a*b, 1 - 2*(1-a)*(1-b)),
-    "softlight":    lambda a, b: (1 - 2*b)*a*a + 2*b*a,
-    "hardlight":    lambda a, b: np.where(b < 0.5, 2*a*b, 1 - 2*(1-a)*(1-b)),
-
-    # Difference
-    "difference":   lambda a, b: np.abs(a - b),
-    "exclusion":    lambda a, b: a + b - 2*a*b,
-
-    # Dodge / burn
-    "colordodge":   lambda a, b: np.clip(a / (1 - b + 1e-6), 0, 1),
-    "colorburn":    lambda a, b: np.clip(1 - (1 - a) / (b + 1e-6), 0, 1),
-
-    # Light
-    "linearlight":  lambda a, b: np.clip(a + 2*b - 1, 0, 1),
-    "vividlight":   lambda a, b: np.where(b < 0.5,
-                        np.clip(1 - (1-a)/(2*b + 1e-6), 0, 1),
-                        np.clip(a / (2*(1-b) + 1e-6), 0, 1)),
-    "pin_light":    lambda a, b: np.where(b < 0.5,
-                        np.minimum(a, 2*b), np.maximum(a, 2*b - 1)),
-    "hard_mix":     lambda a, b: np.where(a + b >= 1.0, 1.0, 0.0),
-
-    # Compare
-    "lighten":      lambda a, b: np.maximum(a, b),
-    "darken":       lambda a, b: np.minimum(a, b),
-
-    # Grain
-    "grain_extract": lambda a, b: np.clip(a - b + 0.5, 0, 1),
-    "grain_merge":  lambda a, b: np.clip(a + b - 0.5, 0, 1),
-}
-```
-
-### Blend Mode Selection Guide
-
-**Modes that brighten** (safe for dark inputs):
-- `screen` — always brightens. Two 50% gray layers screen to 75%. The go-to safe blend.
-- `add` — simple addition, clips at white. Good for sparkles, glows, particle overlays.
-- `colordodge` — extreme brightening at overlap zones. Can blow out. Use low opacity (0.3-0.5).
-- `linearlight` — aggressive brightening. Similar to add but with offset.
-
-**Modes that darken** (avoid with dark inputs):
-- `multiply` — darkens everything. Only use when both layers are already bright.
-- `overlay` — darkens when base < 0.5, brightens when base > 0.5. Crushes dark inputs: `2 * 0.12 * 0.12 = 0.03`. Use `screen` instead for dark material.
-- `colorburn` — extreme darkening at overlap zones.
-
-**Modes that create contrast**:
-- `softlight` — gentle contrast. Good for subtle texture overlay.
-- `hardlight` — strong contrast. Like overlay but keyed on the top layer.
-- `vividlight` — very aggressive contrast. Use sparingly.
-
-**Modes that create color effects**:
-- `difference` — XOR-like patterns. Two identical layers difference to black; offset layers create wild colors. Great for psychedelic looks.
-- `exclusion` — softer version of difference. Creates complementary color patterns.
-- `hard_mix` — posterizes to pure black/white/saturated color at intersections.
-
-**Modes for texture blending**:
-- `grain_extract` / `grain_merge` — extract a texture from one layer, apply it to another.
-
-### Multi-Layer Chaining
-
-```python
-# Pattern: render layers -> blend sequentially
-canvas_a = _render_vf(r, "md", vf_plasma, hf_angle(0.0), PAL_DENSE, f, t, S)
-canvas_b = _render_vf(r, "sm", vf_vortex, hf_time_cycle(0.1), PAL_RUNE, f, t, S)
-canvas_c = _render_vf(r, "lg", vf_rings, hf_distance(), PAL_BLOCKS, f, t, S)
-
-result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
-result = blend_canvas(result, canvas_c, "difference", 0.6)
-```
-
-Order matters: `screen(A, B)` is commutative, but `difference(screen(A,B), C)` differs from `difference(A, screen(B,C))`.
-
----
-
-## Multi-Grid Composition
-
-This is the core visual technique. Rendering the same conceptual scene at different grid densities (character sizes) creates natural texture interference, because characters at different scales overlap at different spatial frequencies.
-
-### Why It Works
-
-- `sm` grid (10pt font): 320x83 characters. Fine detail, dense texture.
-- `md` grid (16pt): 192x56 characters. Medium density.
-- `lg` grid (20pt): 160x45 characters. Coarse, chunky characters.
-
-When you render a plasma field on `sm` and a vortex on `lg`, then screen-blend them, the fine plasma texture shows through the gaps in the coarse vortex characters. The result has more visual complexity than either layer alone.
-
-### The `_render_vf()` Helper
-
-This is the workhorse function. It takes a value field + hue field + palette + grid, renders to a complete pixel canvas:
-
-```python
-def _render_vf(r, grid_key, val_fn, hue_fn, pal, f, t, S, sat=0.8, threshold=0.03):
-    """Render a value field + hue field to a pixel canvas via a named grid.
-
-    Args:
-        r: Renderer instance (has .get_grid())
-        grid_key: "xs", "sm", "md", "lg", "xl", "xxl"
-        val_fn: (g, f, t, S) -> float32 [0,1] array (rows, cols)
-        hue_fn: callable (g, f, t, S) -> float32 hue array, OR float scalar
-        pal: character palette string
-        f: feature dict
-        t: time in seconds
-        S: persistent state dict
-        sat: HSV saturation (0-1)
-        threshold: minimum value to render (below = space)
-
-    Returns:
-        uint8 array (VH, VW, 3) — full pixel canvas
-    """
-    g = r.get_grid(grid_key)
-    val = np.clip(val_fn(g, f, t, S), 0, 1)
-    mask = val > threshold
-    ch = val2char(val, mask, pal)
-
-    # Hue: either a callable or a fixed float
-    if callable(hue_fn):
-        h = hue_fn(g, f, t, S) % 1.0
-    else:
-        h = np.full((g.rows, g.cols), float(hue_fn), dtype=np.float32)
-
-    # CRITICAL: broadcast to full shape and copy (see Troubleshooting)
-    h = np.broadcast_to(h, (g.rows, g.cols)).copy()
-
-    R, G, B = hsv2rgb(h, np.full_like(val, sat), val)
-    co = mkc(R, G, B, g.rows, g.cols)
-    return g.render(ch, co)
-```
-
-### Grid Combination Strategies
-
-| Combination | Effect | Good For |
-|-------------|--------|----------|
-| `sm` + `lg` | Maximum contrast between fine detail and chunky blocks | Bold, graphic looks |
-| `sm` + `md` | Subtle texture layering, similar scales | Organic, flowing looks |
-| `md` + `lg` + `xs` | Three-scale interference, maximum complexity | Psychedelic, dense |
-| `sm` + `sm` (different effects) | Same scale, pattern interference only | Moire, interference |
-
-### Complete Multi-Grid Scene Example
-
-```python
-def fx_psychedelic(r, f, t, S):
-    """Three-layer multi-grid scene with beat-reactive kaleidoscope."""
-    # Layer A: plasma on medium grid with rainbow hue
-    canvas_a = _render_vf(r, "md",
-        lambda g, f, t, S: vf_plasma(g, f, t, S) * 1.3,
-        hf_angle(0.0), PAL_DENSE, f, t, S, sat=0.8)
-
-    # Layer B: vortex on small grid with cycling hue
-    canvas_b = _render_vf(r, "sm",
-        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=5.0) * 1.2,
-        hf_time_cycle(0.1), PAL_RUNE, f, t, S, sat=0.7)
-
-    # Layer C: rings on large grid with distance hue
-    canvas_c = _render_vf(r, "lg",
-        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=8, spacing_base=3) * 1.4,
-        hf_distance(0.3, 0.02), PAL_BLOCKS, f, t, S, sat=0.9)
-
-    # Blend: A screened with B, then difference with C
-    result = blend_canvas(canvas_a, canvas_b, "screen", 0.8)
-    result = blend_canvas(result, canvas_c, "difference", 0.6)
-
-    # Beat-triggered kaleidoscope
-    if f.get("bdecay", 0) > 0.3:
-        result = sh_kaleidoscope(result.copy(), folds=6)
-
-    return result
-```
-
----
-
-## Adaptive Tone Mapping
-
-### The Brightness Problem
-
-ASCII characters are small bright dots on a black background. Most pixels in any frame are background (black). This means:
-- Mean frame brightness is inherently low (often 5-30 out of 255)
-- Different effect combinations produce wildly different brightness levels
-- A spiral scene might be 50 mean, while a fire scene is 9 mean
-- Linear multipliers (e.g., `canvas * 2.0`) either leave dark scenes dark or blow out bright scenes
-
-### The `tonemap()` Function
-
-Replaces linear brightness multipliers with adaptive per-frame normalization + gamma correction:
-
-```python
-def tonemap(canvas, target_mean=90, gamma=0.75, black_point=2, white_point=253):
-    """Adaptive tone-mapping: normalizes + gamma-corrects so no frame is
-    fully dark or washed out.
-
-    1. Compute 1st and 99.5th percentile (ignores outlier pixels)
-    2. Stretch that range to [0, 1]
-    3. Apply gamma curve (< 1 lifts shadows, > 1 darkens)
-    4. Rescale to [black_point, white_point]
-    """
-    f = canvas.astype(np.float32)
-    lo = np.percentile(f, 1)
-    hi = np.percentile(f, 99.5)
-    if hi - lo < 10:
-        hi = max(hi, lo + 10)  # near-uniform frame fallback
-    f = np.clip((f - lo) / (hi - lo), 0.0, 1.0)
-    f = np.power(f, gamma)
-    f = f * (white_point - black_point) + black_point
-    return np.clip(f, 0, 255).astype(np.uint8)
-```
-
-### Why Gamma, Not Linear
-
-Linear multiplier `* 2.0`:
-```
-input 10  -> output 20   (still dark)
-input 100 -> output 200  (ok)
-input 200 -> output 255  (clipped, lost detail)
-```
-
-Gamma 0.75 after normalization:
-```
-input 0.04 -> output 0.08 (lifted from invisible to visible)
-input 0.39 -> output 0.50 (moderate lift)
-input 0.78 -> output 0.84 (gentle lift, no clipping)
-```
-
-Gamma < 1 compresses the highlights and expands the shadows. This is exactly what we need: lift dark ASCII content into visibility without blowing out the bright parts.
-
-### Pipeline Ordering
-
-The pipeline in `render_clip()` is:
-
-```
-scene_fn(r, f, t, S)  ->  canvas
-         |
-    tonemap(canvas, gamma=scene_gamma)
-         |
-    FeedbackBuffer.apply(canvas, ...)
-         |
-    ShaderChain.apply(canvas, f=f, t=t)
-         |
-    ffmpeg pipe
-```
-
-Tonemap runs BEFORE feedback and shaders. This means:
-- Feedback operates on normalized data (consistent behavior regardless of scene brightness)
-- Shaders like solarize, posterize, contrast operate on properly-ranged data
-- The brightness shader in the chain is no longer needed (tonemap handles it)
-
-### Per-Scene Gamma Tuning
-
-Default gamma is 0.75. Scenes that apply destructive post-processing need more aggressive lift because the destruction happens after tonemap:
-
-| Scene Type | Recommended Gamma | Why |
-|------------|-------------------|-----|
-| Standard effects | 0.75 | Default, works for most scenes |
-| Solarize post-process | 0.50-0.60 | Solarize inverts bright pixels, reducing overall brightness |
-| Posterize post-process | 0.50-0.55 | Posterize quantizes, often crushing mid-values to black |
-| Heavy difference blending | 0.60-0.70 | Difference mode creates many near-zero pixels |
-| Already bright scenes | 0.85-1.0 | Don't over-boost scenes that are naturally bright |
-
-Configure via the scene table:
-
-```python
-SCENES = [
-    {"start": 9.17, "end": 11.25, "name": "fire", "gamma": 0.55,
-     "fx": fx_fire, "shaders": [("solarize", {"threshold": 200}), ...]},
-    {"start": 25.96, "end": 27.29, "name": "diamond", "gamma": 0.5,
-     "fx": fx_diamond, "shaders": [("bloom", {"thr": 90}), ...]},
-]
-```
-
-### Brightness Verification
-
-After rendering, spot-check frame brightness:
-
-```python
-# In test-frame mode
-canvas = scene["fx"](r, feat, t, r.S)
-canvas = tonemap(canvas, gamma=scene.get("gamma", 0.75))
-chain = ShaderChain()
-for sn, kw in scene.get("shaders", []):
-    chain.add(sn, **kw)
-canvas = chain.apply(canvas, f=feat, t=t)
-print(f"Mean brightness: {canvas.astype(float).mean():.1f}, max: {canvas.max()}")
-```
-
-Target ranges after tonemap + shaders:
-- Quiet/ambient scenes: mean 30-60
-- Active scenes: mean 40-100
-- Climax/peak scenes: mean 60-150
-- If mean < 20: gamma is too high or a shader is destroying brightness
-- If mean > 180: gamma is too low or add is stacking too much
-
----
-
-## FeedbackBuffer Spatial Transforms
-
-The feedback buffer stores the previous frame and blends it into the current frame with decay. Spatial transforms applied to the buffer before blending create the illusion of motion in the feedback trail.
-
-### Implementation
-
-```python
-class FeedbackBuffer:
-    def __init__(self):
-        self.buf = None
-
-    def apply(self, canvas, decay=0.85, blend="screen", opacity=0.5,
-              transform=None, transform_amt=0.02, hue_shift=0.0):
-        if self.buf is None:
-            self.buf = canvas.astype(np.float32) / 255.0
-            return canvas
-
-        # Decay old buffer
-        self.buf *= decay
-
-        # Spatial transform
-        if transform:
-            self.buf = self._transform(self.buf, transform, transform_amt)
-
-        # Hue shift the feedback for rainbow trails
-        if hue_shift > 0:
-            self.buf = self._hue_shift(self.buf, hue_shift)
-
-        # Blend feedback into current frame
-        result = blend_canvas(canvas,
-                              np.clip(self.buf * 255, 0, 255).astype(np.uint8),
-                              blend, opacity)
-
-        # Update buffer with current frame
-        self.buf = result.astype(np.float32) / 255.0
-        return result
-
-    def _transform(self, buf, transform, amt):
-        h, w = buf.shape[:2]
-        if transform == "zoom":
-            # Zoom in: sample from slightly inside (creates expanding tunnel)
-            m = int(h * amt); n = int(w * amt)
-            if m > 0 and n > 0:
-                cropped = buf[m:-m or None, n:-n or None]
-                # Resize back to full (nearest-neighbor for speed)
-                buf = np.array(Image.fromarray(
-                    np.clip(cropped * 255, 0, 255).astype(np.uint8)
-                ).resize((w, h), Image.NEAREST)).astype(np.float32) / 255.0
-        elif transform == "shrink":
-            # Zoom out: pad edges, shrink center
-            m = int(h * amt); n = int(w * amt)
-            small = np.array(Image.fromarray(
-                np.clip(buf * 255, 0, 255).astype(np.uint8)
-            ).resize((w - 2*n, h - 2*m), Image.NEAREST))
-            new = np.zeros((h, w, 3), dtype=np.uint8)
-            new[m:m+small.shape[0], n:n+small.shape[1]] = small
-            buf = new.astype(np.float32) / 255.0
-        elif transform == "rotate_cw":
-            # Small clockwise rotation via affine
-            angle = amt * 10  # amt=0.005 -> 0.05 degrees per frame
-            cy, cx = h / 2, w / 2
-            Y = np.arange(h, dtype=np.float32)[:, None]
-            X = np.arange(w, dtype=np.float32)[None, :]
-            cos_a, sin_a = np.cos(angle), np.sin(angle)
-            sx = (X - cx) * cos_a + (Y - cy) * sin_a + cx
-            sy = -(X - cx) * sin_a + (Y - cy) * cos_a + cy
-            sx = np.clip(sx.astype(int), 0, w - 1)
-            sy = np.clip(sy.astype(int), 0, h - 1)
-            buf = buf[sy, sx]
-        elif transform == "rotate_ccw":
-            angle = -amt * 10
-            cy, cx = h / 2, w / 2
-            Y = np.arange(h, dtype=np.float32)[:, None]
-            X = np.arange(w, dtype=np.float32)[None, :]
-            cos_a, sin_a = np.cos(angle), np.sin(angle)
-            sx = (X - cx) * cos_a + (Y - cy) * sin_a + cx
-            sy = -(X - cx) * sin_a + (Y - cy) * cos_a + cy
-            sx = np.clip(sx.astype(int), 0, w - 1)
-            sy = np.clip(sy.astype(int), 0, h - 1)
-            buf = buf[sy, sx]
-        elif transform == "shift_up":
-            pixels = max(1, int(h * amt))
-            buf = np.roll(buf, -pixels, axis=0)
-            buf[-pixels:] = 0  # black fill at bottom
-        elif transform == "shift_down":
-            pixels = max(1, int(h * amt))
-            buf = np.roll(buf, pixels, axis=0)
-            buf[:pixels] = 0
-        elif transform == "mirror_h":
-            buf = buf[:, ::-1]
-        return buf
-
-    def _hue_shift(self, buf, amount):
-        """Rotate hues of the feedback buffer. Operates on float32 [0,1]."""
-        rgb = np.clip(buf * 255, 0, 255).astype(np.uint8)
-        hsv = np.zeros_like(buf)
-        # Simple approximate RGB->HSV->shift->RGB
-        r, g, b = buf[:,:,0], buf[:,:,1], buf[:,:,2]
-        mx = np.maximum(np.maximum(r, g), b)
-        mn = np.minimum(np.minimum(r, g), b)
-        delta = mx - mn + 1e-10
-        # Hue
-        h = np.where(mx == r, ((g - b) / delta) % 6,
-            np.where(mx == g, (b - r) / delta + 2, (r - g) / delta + 4))
-        h = (h / 6 + amount) % 1.0
-        # Reconstruct with shifted hue (simplified)
-        s = delta / (mx + 1e-10)
-        v = mx
-        c = v * s; x = c * (1 - np.abs((h * 6) % 2 - 1)); m = v - c
-        ro = np.zeros_like(h); go = np.zeros_like(h); bo = np.zeros_like(h)
-        for lo, hi, rv, gv, bv in [(0,1,c,x,0),(1,2,x,c,0),(2,3,0,c,x),
-                                     (3,4,0,x,c),(4,5,x,0,c),(5,6,c,0,x)]:
-            mask = ((h*6) >= lo) & ((h*6) < hi)
-            ro[mask] = rv[mask] if not isinstance(rv, (int,float)) else rv
-            go[mask] = gv[mask] if not isinstance(gv, (int,float)) else gv
-            bo[mask] = bv[mask] if not isinstance(bv, (int,float)) else bv
-        return np.stack([ro+m, go+m, bo+m], axis=2)
-```
-
-### Feedback Presets
-
-| Preset | Config | Visual Effect |
-|--------|--------|---------------|
-| Infinite zoom tunnel | `decay=0.8, blend="screen", transform="zoom", transform_amt=0.015` | Expanding ring patterns |
-| Rainbow trails | `decay=0.7, blend="screen", transform="zoom", transform_amt=0.01, hue_shift=0.02` | Psychedelic color trails |
-| Ghostly echo | `decay=0.9, blend="add", opacity=0.15, transform="shift_up", transform_amt=0.01` | Faint upward smearing |
-| Kaleidoscopic recursion | `decay=0.75, blend="screen", transform="rotate_cw", transform_amt=0.005, hue_shift=0.01` | Rotating mandala feedback |
-| Color evolution | `decay=0.8, blend="difference", opacity=0.4, hue_shift=0.03` | Frame-to-frame color XOR |
-| Rising heat haze | `decay=0.5, blend="add", opacity=0.2, transform="shift_up", transform_amt=0.02` | Hot air shimmer |
-
----
-
-## PixelBlendStack
-
-Higher-level wrapper for multi-layer compositing:
-
-```python
-class PixelBlendStack:
-    def __init__(self):
-        self.layers = []
-
-    def add(self, canvas, mode="normal", opacity=1.0):
-        self.layers.append((canvas, mode, opacity))
-        return self
-
-    def composite(self):
-        if not self.layers:
-            return np.zeros((VH, VW, 3), dtype=np.uint8)
-        result = self.layers[0][0]
-        for canvas, mode, opacity in self.layers[1:]:
-            result = blend_canvas(result, canvas, mode, opacity)
-        return result
-```

skills/creative/ascii-video/references/effects.md

@@ -1,893 +0,0 @@
-# Effect Catalog
-
-Effect building blocks that produce visual patterns. In v2, these are used **inside scene functions** that return a pixel canvas directly. The building blocks below operate on grid coordinate arrays and produce `(chars, colors)` or value/hue fields that the scene function renders to canvas via `_render_vf()`. See `composition.md` for the v2 rendering pattern and `scenes.md` for scene function examples.
-
-## Design Philosophy
-
-Effects are the creative core. Don't copy these verbatim for every project -- use them as **building blocks** and **combine, modify, and invent** new ones. Every project should feel distinct.
-
-Key principles:
-- **Layer multiple effects** rather than using a single monolithic function
-- **Parameterize everything** -- hue, speed, density, amplitude should all be arguments
-- **React to features** -- audio/video features should modulate at least 2-3 parameters per effect
-- **Vary per section** -- never use the same effect config for the entire video
-- **Invent project-specific effects** -- the catalog below is a starting vocabulary, not a fixed set
-
----
-
-## Background Fills
-
-Every effect should start with a background. Never leave flat black.
-
-### Animated Sine Field (General Purpose)
-```python
-def bg_sinefield(g, f, t, hue=0.6, bri=0.5, pal=PAL_DEFAULT,
-                 freq=(0.13, 0.17, 0.07, 0.09), speed=(0.5, -0.4, -0.3, 0.2)):
-    """Layered sine field. Adjust freq/speed tuples for different textures."""
-    v1 = np.sin(g.cc*freq[0] + t*speed[0]) * np.sin(g.rr*freq[1] - t*speed[1]) * 0.5 + 0.5
-    v2 = np.sin(g.cc*freq[2] - t*speed[2] + g.rr*freq[3]) * 0.4 + 0.5
-    v3 = np.sin(g.dist_n*5 + t*0.2) * 0.3 + 0.4
-    v4 = np.cos(g.angle*3 - t*0.6) * 0.15 + 0.5
-    val = np.clip((v1*0.3 + v2*0.25 + v3*0.25 + v4*0.2) * bri * (0.6 + f["rms"]*0.6), 0.06, 1)
-    mask = val > 0.03
-    ch = val2char(val, mask, pal)
-    h = np.full_like(val, hue) + f.get("cent", 0.5)*0.1 + val*0.08
-    R, G, B = hsv2rgb(h, np.clip(0.35+f.get("flat",0.4)*0.4, 0, 1) * np.ones_like(val), val)
-    return ch, mkc(R, G, B, g.rows, g.cols)
-```
-
-### Video-Source Background
-```python
-def bg_video(g, frame_rgb, pal=PAL_DEFAULT, brightness=0.5):
-    small = np.array(Image.fromarray(frame_rgb).resize((g.cols, g.rows)))
-    lum = np.mean(small, axis=2) / 255.0 * brightness
-    mask = lum > 0.02
-    ch = val2char(lum, mask, pal)
-    co = np.clip(small * np.clip(lum[:,:,None]*1.5+0.3, 0.3, 1), 0, 255).astype(np.uint8)
-    return ch, co
-```
-
-### Noise / Static Field
-```python
-def bg_noise(g, f, t, pal=PAL_BLOCKS, density=0.3, hue_drift=0.02):
-    val = np.random.random((g.rows, g.cols)).astype(np.float32) * density * (0.5 + f["rms"]*0.5)
-    val = np.clip(val, 0, 1); mask = val > 0.02
-    ch = val2char(val, mask, pal)
-    R, G, B = hsv2rgb(np.full_like(val, t*hue_drift % 1), np.full_like(val, 0.3), val)
-    return ch, mkc(R, G, B, g.rows, g.cols)
-```
-
-### Perlin-Like Smooth Noise
-```python
-def bg_smooth_noise(g, f, t, hue=0.5, bri=0.5, pal=PAL_DOTS, octaves=3):
-    """Layered sine approximation of Perlin noise. Cheap, smooth, organic."""
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(octaves):
-        freq = 0.05 * (2 ** i)
-        amp = 0.5 / (i + 1)
-        phase = t * (0.3 + i * 0.2)
-        val += np.sin(g.cc * freq + phase) * np.cos(g.rr * freq * 0.7 - phase * 0.5) * amp
-    val = np.clip(val * 0.5 + 0.5, 0, 1) * bri
-    mask = val > 0.03
-    ch = val2char(val, mask, pal)
-    h = np.full_like(val, hue) + val * 0.1
-    R, G, B = hsv2rgb(h, np.full_like(val, 0.5), val)
-    return ch, mkc(R, G, B, g.rows, g.cols)
-```
-
-### Cellular / Voronoi Approximation
-```python
-def bg_cellular(g, f, t, n_centers=12, hue=0.5, bri=0.6, pal=PAL_BLOCKS):
-    """Voronoi-like cells using distance to nearest of N moving centers."""
-    rng = np.random.RandomState(42)  # deterministic centers
-    cx = (rng.rand(n_centers) * g.cols).astype(np.float32)
-    cy = (rng.rand(n_centers) * g.rows).astype(np.float32)
-    # Animate centers
-    cx_t = cx + np.sin(t * 0.5 + np.arange(n_centers) * 0.7) * 5
-    cy_t = cy + np.cos(t * 0.4 + np.arange(n_centers) * 0.9) * 3
-    # Min distance to any center
-    min_d = np.full((g.rows, g.cols), 999.0, dtype=np.float32)
-    for i in range(n_centers):
-        d = np.sqrt((g.cc - cx_t[i])**2 + (g.rr - cy_t[i])**2)
-        min_d = np.minimum(min_d, d)
-    val = np.clip(1.0 - min_d / (g.cols * 0.3), 0, 1) * bri
-    # Cell edges (where distance is near-equal between two centers)
-    # ... second-nearest trick for edge highlighting
-    mask = val > 0.03
-    ch = val2char(val, mask, pal)
-    R, G, B = hsv2rgb(np.full_like(val, hue) + min_d * 0.005, np.full_like(val, 0.5), val)
-    return ch, mkc(R, G, B, g.rows, g.cols)
-```
-
----
-
-## Radial Effects
-
-### Concentric Rings
-Bass/sub-driven pulsing rings from center. Scale ring count and thickness with bass energy.
-```python
-def eff_rings(g, f, t, hue=0.5, n_base=6, pal=PAL_DEFAULT):
-    n_rings = int(n_base + f["sub_r"] * 25 + f["bass"] * 10)
-    spacing = 2 + f["bass_r"] * 7 + f["rms"] * 3
-    ring_cv = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ri in range(n_rings):
-        rad = (ri+1) * spacing + f["bdecay"] * 15
-        wobble = f["mid_r"]*5*np.sin(g.angle*3 + t*4) + f["hi_r"]*3*np.sin(g.angle*7 - t*6)
-        rd = np.abs(g.dist - rad - wobble)
-        th = 1 + f["sub"] * 3
-        ring_cv = np.maximum(ring_cv, np.clip((1 - rd/th) * (0.4 + f["bass"]*0.8), 0, 1))
-    # Color by angle + distance for rainbow rings
-    h = g.angle/(2*np.pi) + g.dist*0.005 + f["sub_r"]*0.2
-    return ring_cv, h
-```
-
-### Radial Rays
-```python
-def eff_rays(g, f, t, n_base=8, hue=0.5):
-    n_rays = int(n_base + f["hi_r"] * 25)
-    ray = np.clip(np.cos(g.angle*n_rays + t*3) * f["bdecay"]*0.6 * (1-g.dist_n), 0, 0.7)
-    return ray
-```
-
-### Spiral Arms (Logarithmic)
-```python
-def eff_spiral(g, f, t, n_arms=3, tightness=2.5, hue=0.5):
-    arm_cv = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ai in range(n_arms):
-        offset = ai * 2*np.pi / n_arms
-        log_r = np.log(g.dist + 1) * tightness
-        arm_phase = g.angle + offset - log_r + t * 0.8
-        arm_val = np.clip(np.cos(arm_phase * n_arms) * 0.6 + 0.2, 0, 1)
-        arm_val *= (0.4 + f["rms"]*0.6) * np.clip(1 - g.dist_n*0.5, 0.2, 1)
-        arm_cv = np.maximum(arm_cv, arm_val)
-    return arm_cv
-```
-
-### Center Glow / Pulse
-```python
-def eff_glow(g, f, t, intensity=0.6, spread=2.0):
-    return np.clip(intensity * np.exp(-g.dist_n * spread) * (0.5 + f["rms"]*2 + np.sin(t*1.2)*0.2), 0, 0.9)
-```
-
-### Tunnel / Depth
-```python
-def eff_tunnel(g, f, t, speed=3.0, complexity=6):
-    tunnel_d = 1.0 / (g.dist_n + 0.1)
-    v1 = np.sin(tunnel_d*2 - t*speed) * 0.45 + 0.55
-    v2 = np.sin(g.angle*complexity + tunnel_d*1.5 - t*2) * 0.35 + 0.55
-    return v1 * 0.5 + v2 * 0.5
-```
-
-### Vortex (Rotating Distortion)
-```python
-def eff_vortex(g, f, t, twist=3.0, pulse=True):
-    """Twisting radial pattern -- distance modulates angle."""
-    twisted = g.angle + g.dist_n * twist * np.sin(t * 0.5)
-    val = np.sin(twisted * 4 - t * 2) * 0.5 + 0.5
-    if pulse:
-        val *= 0.5 + f.get("bass", 0.3) * 0.8
-    return np.clip(val, 0, 1)
-```
-
----
-
-## Wave Effects
-
-### Multi-Band Frequency Waves
-Each frequency band draws its own wave at different spatial/temporal frequencies:
-```python
-def eff_freq_waves(g, f, t, bands=None):
-    if bands is None:
-        bands = [("sub",0.06,1.2,0.0), ("bass",0.10,2.0,0.08), ("lomid",0.15,3.0,0.16),
-                 ("mid",0.22,4.5,0.25), ("himid",0.32,6.5,0.4), ("hi",0.45,8.5,0.55)]
-    mid = g.rows / 2.0
-    composite = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for band_key, sf, tf, hue_base in bands:
-        amp = f.get(band_key, 0.3) * g.rows * 0.4
-        y_wave = mid - np.sin(g.cc*sf + t*tf) * amp
-        y_wave += np.sin(g.cc*sf*2.3 + t*tf*1.7) * amp * 0.2  # harmonic
-        dist = np.abs(g.rr - y_wave)
-        thickness = 2 + f.get(band_key, 0.3) * 5
-        intensity = np.clip((1 - dist/thickness) * f.get(band_key, 0.3) * 1.5, 0, 1)
-        composite = np.maximum(composite, intensity)
-    return composite
-```
-
-### Interference Pattern
-6-8 overlapping sine waves creating moire-like patterns:
-```python
-def eff_interference(g, f, t, n_waves=5):
-    """Parametric interference -- vary n_waves for complexity."""
-    # Each wave has different orientation, frequency, and feature driver
-    drivers = ["mid_r", "himid_r", "bass_r", "lomid_r", "hi_r"]
-    vals = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(min(n_waves, len(drivers))):
-        angle = i * np.pi / n_waves  # spread orientations
-        freq = 0.06 + i * 0.03
-        sp = 0.5 + i * 0.3
-        proj = g.cc * np.cos(angle) + g.rr * np.sin(angle)
-        vals += np.sin(proj * freq + t * sp) * f.get(drivers[i], 0.3) * 2.5
-    return np.clip(vals * 0.12 + 0.45, 0.1, 1)
-```
-
-### Aurora / Horizontal Bands
-```python
-def eff_aurora(g, f, t, hue=0.4, n_bands=3):
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(n_bands):
-        freq_r = 0.08 + i * 0.04
-        freq_c = 0.012 + i * 0.008
-        sp_r = 0.7 + i * 0.3
-        sp_c = 0.18 + i * 0.12
-        val += np.sin(g.rr*freq_r + t*sp_r) * np.sin(g.cc*freq_c + t*sp_c) * (0.6 / n_bands)
-    return np.clip(val * (f.get("lomid_r", 0.3)*3 + 0.2), 0, 0.7)
-```
-
-### Ripple (Point-Source Waves)
-```python
-def eff_ripple(g, f, t, sources=None, freq=0.3, damping=0.02):
-    """Concentric ripples from point sources. Sources = [(row_frac, col_frac), ...]"""
-    if sources is None:
-        sources = [(0.5, 0.5)]  # center
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ry, rx in sources:
-        dy = g.rr - g.rows * ry
-        dx = g.cc - g.cols * rx
-        d = np.sqrt(dy**2 + dx**2)
-        val += np.sin(d * freq - t * 4) * np.exp(-d * damping) * 0.5
-    return np.clip(val + 0.5, 0, 1)
-```
-
----
-
-## Particle Systems
-
-### General Pattern
-All particle systems use persistent state:
-```python
-S = state  # dict persisted across frames
-if "px" not in S:
-    S["px"]=[]; S["py"]=[]; S["vx"]=[]; S["vy"]=[]; S["life"]=[]; S["char"]=[]
-
-# Emit new particles (on beat, continuously, or on trigger)
-# Update: position += velocity, apply forces, decay life
-# Draw: map to grid, set char/color based on life
-# Cull: remove dead, cap total count
-```
-
-### Particle Character Sets
-
-Don't hardcode particle chars. Choose per project/mood:
-
-```python
-# Energy / explosive
-PART_ENERGY  = list("*+#@\u26a1\u2726\u2605\u2588\u2593")
-PART_SPARK   = list("\u00b7\u2022\u25cf\u2605\u2736*+")
-# Organic / natural
-PART_LEAF    = list("\u2740\u2741\u2742\u2743\u273f\u2618\u2022")
-PART_SNOW    = list("\u2744\u2745\u2746\u00b7\u2022*\u25cb")
-PART_RAIN    = list("|\u2502\u2503\u2551/\\")
-PART_BUBBLE  = list("\u25cb\u25ce\u25c9\u25cf\u2218\u2219\u00b0")
-# Data / tech
-PART_DATA    = list("01{}[]<>|/\\")
-PART_HEX     = list("0123456789ABCDEF")
-PART_BINARY  = list("01")
-# Mystical
-PART_RUNE    = list("\u16a0\u16a2\u16a6\u16b1\u16b7\u16c1\u16c7\u16d2\u16d6\u16da\u16de\u16df\u2726\u2605")
-PART_ZODIAC  = list("\u2648\u2649\u264a\u264b\u264c\u264d\u264e\u264f\u2650\u2651\u2652\u2653")
-# Minimal
-PART_DOT     = list("\u00b7\u2022\u25cf")
-PART_DASH    = list("-=~\u2500\u2550")
-```
-
-### Explosion (Beat-Triggered)
-```python
-def emit_explosion(S, f, center_r, center_c, char_set=PART_ENERGY, count_base=80):
-    if f.get("beat", 0) > 0:
-        for _ in range(int(count_base + f["rms"]*150)):
-            ang = random.uniform(0, 2*math.pi)
-            sp = random.uniform(1, 9) * (0.5 + f.get("sub_r", 0.3)*2)
-            S["px"].append(float(center_c))
-            S["py"].append(float(center_r))
-            S["vx"].append(math.cos(ang)*sp*2.5)
-            S["vy"].append(math.sin(ang)*sp)
-            S["life"].append(1.0)
-            S["char"].append(random.choice(char_set))
-# Update: gravity on vy += 0.03, life -= 0.015
-# Color: life * 255 for brightness, hue fade controlled by caller
-```
-
-### Rising Embers
-```python
-# Emit: sy = rows-1, vy = -random.uniform(1,5), vx = random.uniform(-1.5,1.5)
-# Update: vx += random jitter * 0.3, life -= 0.01
-# Cap at ~1500 particles
-```
-
-### Dissolving Cloud
-```python
-# Init: N=600 particles spread across screen
-# Update: slow upward drift, fade life progressively
-# life -= 0.002 * (1 + elapsed * 0.05)  # accelerating fade
-```
-
-### Starfield (3D Projection)
-```python
-# N stars with (sx, sy, sz) in normalized coords
-# Move: sz -= speed (stars approach camera)
-# Project: px = cx + sx/sz * cx, py = cy + sy/sz * cy
-# Reset stars that pass camera (sz <= 0.01)
-# Brightness = (1 - sz), draw streaks behind bright stars
-```
-
-### Orbit (Circular/Elliptical Motion)
-```python
-def emit_orbit(S, n=20, radius=15, speed=1.0, char_set=PART_DOT):
-    """Particles orbiting a center point."""
-    for i in range(n):
-        angle = i * 2 * math.pi / n
-        S["px"].append(0.0); S["py"].append(0.0)  # will be computed from angle
-        S["vx"].append(angle)  # store angle as "vx" for orbit
-        S["vy"].append(radius + random.uniform(-2, 2))  # store radius
-        S["life"].append(1.0)
-        S["char"].append(random.choice(char_set))
-# Update: angle += speed * dt, px = cx + radius * cos(angle), py = cy + radius * sin(angle)
-```
-
-### Gravity Well
-```python
-# Particles attracted toward one or more gravity points
-# Update: compute force vector toward each well, apply as acceleration
-# Particles that reach well center respawn at edges
-```
-
----
-
-## Rain / Matrix Effects
-
-### Column Rain (Vectorized)
-```python
-def eff_matrix_rain(g, f, t, state, hue=0.33, bri=0.6, pal=PAL_KATA,
-                    speed_base=0.5, speed_beat=3.0):
-    """Vectorized matrix rain. state dict persists column positions."""
-    if "ry" not in state or len(state["ry"]) != g.cols:
-        state["ry"] = np.random.uniform(-g.rows, g.rows, g.cols).astype(np.float32)
-        state["rsp"] = np.random.uniform(0.3, 2.0, g.cols).astype(np.float32)
-        state["rln"] = np.random.randint(8, 40, g.cols)
-        state["rch"] = np.random.randint(0, len(pal), (g.rows, g.cols))  # pre-assign chars
-
-    speed_mult = speed_base + f.get("bass", 0.3)*speed_beat + f.get("sub_r", 0.3)*3
-    if f.get("beat", 0) > 0: speed_mult *= 2.5
-    state["ry"] += state["rsp"] * speed_mult
-
-    # Reset columns that fall past bottom
-    rst = (state["ry"] - state["rln"]) > g.rows
-    state["ry"][rst] = np.random.uniform(-25, -2, rst.sum())
-
-    # Vectorized draw using fancy indexing
-    ch = np.full((g.rows, g.cols), " ", dtype="U1")
-    co = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
-    heads = state["ry"].astype(int)
-    for c in range(g.cols):
-        head = heads[c]
-        trail_len = state["rln"][c]
-        for i in range(trail_len):
-            row = head - i
-            if 0 <= row < g.rows:
-                fade = 1.0 - i / trail_len
-                ci = state["rch"][row, c] % len(pal)
-                ch[row, c] = pal[ci]
-                v = fade * bri * 255
-                if i == 0:  # head is bright white-ish
-                    co[row, c] = (int(v*0.9), int(min(255, v*1.1)), int(v*0.9))
-                else:
-                    R, G, B = hsv2rgb_single(hue, 0.7, fade * bri)
-                    co[row, c] = (R, G, B)
-    return ch, co, state
-```
-
----
-
-## Glitch / Data Effects
-
-### Horizontal Band Displacement
-```python
-def eff_glitch_displace(ch, co, f, intensity=1.0):
-    n_bands = int(8 + f.get("flux", 0.3)*25 + f.get("bdecay", 0)*15) * intensity
-    for _ in range(int(n_bands)):
-        y = random.randint(0, ch.shape[0]-1)
-        h = random.randint(1, int(3 + f.get("sub", 0.3)*8))
-        shift = int((random.random()-0.5) * f.get("rms", 0.3)*40 + f.get("bdecay", 0)*20*(random.random()-0.5))
-        if shift != 0:
-            for row in range(h):
-                rr = y + row
-                if 0 <= rr < ch.shape[0]:
-                    ch[rr] = np.roll(ch[rr], shift)
-                    co[rr] = np.roll(co[rr], shift, axis=0)
-    return ch, co
-```
-
-### Block Corruption
-```python
-def eff_block_corrupt(ch, co, f, char_pool=None, count_base=20):
-    if char_pool is None:
-        char_pool = list(PAL_BLOCKS[4:] + PAL_KATA[2:8])
-    for _ in range(int(count_base + f.get("flux", 0.3)*60 + f.get("bdecay", 0)*40)):
-        bx = random.randint(0, max(1, ch.shape[1]-6))
-        by = random.randint(0, max(1, ch.shape[0]-4))
-        bw, bh = random.randint(2,6), random.randint(1,4)
-        block_char = random.choice(char_pool)
-        # Fill rectangle with single char and random color
-        for r in range(bh):
-            for c in range(bw):
-                rr, cc = by+r, bx+c
-                if 0 <= rr < ch.shape[0] and 0 <= cc < ch.shape[1]:
-                    ch[rr, cc] = block_char
-                    co[rr, cc] = (random.randint(100,255), random.randint(0,100), random.randint(0,80))
-    return ch, co
-```
-
-### Scan Bars (Vertical)
-```python
-def eff_scanbars(ch, co, f, t, n_base=4, chars="|\u2551|!1l"):
-    for bi in range(int(n_base + f.get("himid_r", 0.3)*12)):
-        sx = int((t*50*(1+bi*0.3) + bi*37) % ch.shape[1])
-        for rr in range(ch.shape[0]):
-            if random.random() < 0.7:
-                ch[rr, sx] = random.choice(chars)
-    return ch, co
-```
-
-### Error Messages
-```python
-# Parameterize the error vocabulary per project:
-ERRORS_TECH = ["SEGFAULT","0xDEADBEEF","BUFFER_OVERRUN","PANIC!","NULL_PTR",
-               "CORRUPT","SIGSEGV","ERR_OVERFLOW","STACK_SMASH","BAD_ALLOC"]
-ERRORS_COSMIC = ["VOID_BREACH","ENTROPY_MAX","SINGULARITY","DIMENSION_FAULT",
-                 "REALITY_ERR","TIME_PARADOX","DARK_MATTER_LEAK","QUANTUM_DECOHERE"]
-ERRORS_ORGANIC = ["CELL_DIVISION_ERR","DNA_MISMATCH","MUTATION_OVERFLOW",
-                  "NEURAL_DEADLOCK","SYNAPSE_TIMEOUT","MEMBRANE_BREACH"]
-```
-
-### Hex Data Stream
-```python
-hex_str = "".join(random.choice("0123456789ABCDEF") for _ in range(random.randint(8,20)))
-stamp(ch, co, hex_str, rand_row, rand_col, (0, 160, 80))
-```
-
----
-
-## Spectrum / Visualization
-
-### Mirrored Spectrum Bars
-```python
-def eff_spectrum(g, f, t, n_bars=64, pal=PAL_BLOCKS, mirror=True):
-    bar_w = max(1, g.cols // n_bars); mid = g.rows // 2
-    band_vals = np.array([f.get("sub",0.3), f.get("bass",0.3), f.get("lomid",0.3),
-                          f.get("mid",0.3), f.get("himid",0.3), f.get("hi",0.3)])
-    ch = np.full((g.rows, g.cols), " ", dtype="U1")
-    co = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
-    for b in range(n_bars):
-        frac = b / n_bars
-        fi = frac * 5; lo_i = int(fi); hi_i = min(lo_i+1, 5)
-        bval = min(1, (band_vals[lo_i]*(1-fi%1) + band_vals[hi_i]*(fi%1)) * 1.8)
-        height = int(bval * (g.rows//2 - 2))
-        for dy in range(height):
-            hue = (f.get("cent",0.5)*0.3 + frac*0.3 + dy/max(height,1)*0.15) % 1.0
-            ci = pal[min(int(dy/max(height,1)*len(pal)*0.7+len(pal)*0.2), len(pal)-1)]
-            for dc in range(bar_w - (1 if bar_w > 2 else 0)):
-                cc = b*bar_w + dc
-                if 0 <= cc < g.cols:
-                    rows_to_draw = [mid - dy, mid + dy] if mirror else [g.rows - 1 - dy]
-                    for row in rows_to_draw:
-                        if 0 <= row < g.rows:
-                            ch[row, cc] = ci
-                            co[row, cc] = hsv_to_rgb_single(hue, 0.85, 0.5+dy/max(height,1)*0.5)
-    return ch, co
-```
-
-### Waveform
-```python
-def eff_waveform(g, f, t, row_offset=-5, hue=0.1):
-    ch = np.full((g.rows, g.cols), " ", dtype="U1")
-    co = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
-    for c in range(g.cols):
-        wv = (math.sin(c*0.15+t*5)*f.get("bass",0.3)*0.5
-            + math.sin(c*0.3+t*8)*f.get("mid",0.3)*0.3
-            + math.sin(c*0.6+t*12)*f.get("hi",0.3)*0.15)
-        wr = g.rows + row_offset + int(wv * 4)
-        if 0 <= wr < g.rows:
-            ch[wr, c] = "~"
-            v = int(120 + f.get("rms",0.3)*135)
-            co[wr, c] = [v, int(v*0.7), int(v*0.4)]
-    return ch, co
-```
-
----
-
-## Fire / Lava
-
-### Fire Columns
-```python
-def eff_fire(g, f, t, n_base=20, hue_base=0.02, hue_range=0.12, pal=PAL_BLOCKS):
-    n_cols = int(n_base + f.get("bass",0.3)*30 + f.get("sub_r",0.3)*20)
-    ch = np.full((g.rows, g.cols), " ", dtype="U1")
-    co = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
-    for fi in range(n_cols):
-        fx_c = int((fi*g.cols/n_cols + np.sin(t*2+fi*0.7)*3) % g.cols)
-        height = int((f.get("bass",0.3)*0.4 + f.get("sub_r",0.3)*0.3 + f.get("rms",0.3)*0.3) * g.rows * 0.7)
-        for dy in range(min(height, g.rows)):
-            fr = g.rows - 1 - dy
-            frac = dy / max(height, 1)
-            bri = max(0.1, (1 - frac*0.6) * (0.5 + f.get("rms",0.3)*0.5))
-            hue = hue_base + frac * hue_range
-            ci = "\u2588" if frac<0.2 else ("\u2593" if frac<0.4 else ("\u2592" if frac<0.6 else "\u2591"))
-            ch[fr, fx_c] = ci
-            R, G, B = hsv2rgb_single(hue, 0.9, bri)
-            co[fr, fx_c] = (R, G, B)
-    return ch, co
-```
-
-### Ice / Cold Fire (same structure, different hue range)
-```python
-# hue_base=0.55, hue_range=0.15 -- blue to cyan
-# Lower intensity, slower movement
-```
-
----
-
-## Text Overlays
-
-### Scrolling Ticker
-```python
-def eff_ticker(ch, co, t, text, row, speed=15, color=(80, 100, 140)):
-    off = int(t * speed) % max(len(text), 1)
-    doubled = text + "   " + text
-    stamp(ch, co, doubled[off:off+ch.shape[1]], row, 0, color)
-```
-
-### Beat-Triggered Words
-```python
-def eff_beat_words(ch, co, f, words, row_center=None, color=(255,240,220)):
-    if f.get("beat", 0) > 0:
-        w = random.choice(words)
-        r = (row_center or ch.shape[0]//2) + random.randint(-5,5)
-        stamp(ch, co, w, r, (ch.shape[1]-len(w))//2, color)
-```
-
-### Fading Message Sequence
-```python
-def eff_fading_messages(ch, co, t, elapsed, messages, period=4.0, color_base=(220,220,220)):
-    msg_idx = int(elapsed / period) % len(messages)
-    phase = elapsed % period
-    fade = max(0, min(1.0, phase) * min(1.0, period - phase))
-    if fade > 0.05:
-        v = fade
-        msg = messages[msg_idx]
-        cr, cg, cb = [int(c * v) for c in color_base]
-        stamp(ch, co, msg, ch.shape[0]//2, (ch.shape[1]-len(msg))//2, (cr, cg, cb))
-```
-
----
-
-## Screen Shake
-Shift entire char/color arrays on beat:
-```python
-def eff_shake(ch, co, f, x_amp=6, y_amp=3):
-    shake_x = int(f.get("sub",0.3)*x_amp*(random.random()-0.5)*2 + f.get("bdecay",0)*4*(random.random()-0.5)*2)
-    shake_y = int(f.get("bass",0.3)*y_amp*(random.random()-0.5)*2)
-    if abs(shake_x) > 0:
-        ch = np.roll(ch, shake_x, axis=1)
-        co = np.roll(co, shake_x, axis=1)
-    if abs(shake_y) > 0:
-        ch = np.roll(ch, shake_y, axis=0)
-        co = np.roll(co, shake_y, axis=0)
-    return ch, co
-```
-
----
-
-## Composable Effect System
-
-The real creative power comes from **composition**. There are three levels:
-
-### Level 1: Character-Level Layering
-
-Stack multiple effects as `(chars, colors)` layers:
-
-```python
-class LayerStack(EffectNode):
-    """Render effects bottom-to-top with character-level compositing."""
-    def add(self, effect, alpha=1.0):
-        """alpha < 1.0 = probabilistic override (sparse overlay)."""
-        self.layers.append((effect, alpha))
-
-# Usage:
-stack = LayerStack()
-stack.add(bg_effect)           # base — fills screen
-stack.add(main_effect)         # overlay on top (space chars = transparent)
-stack.add(particle_effect)     # sparse overlay on top of that
-ch, co = stack.render(g, f, t, S)
-```
-
-### Level 2: Pixel-Level Blending
-
-After rendering to canvases, blend with Photoshop-style modes:
-
-```python
-class PixelBlendStack:
-    """Stack canvases with blend modes for complex compositing."""
-    def add(self, canvas, mode="normal", opacity=1.0)
-    def composite(self) -> canvas
-
-# Usage:
-pbs = PixelBlendStack()
-pbs.add(canvas_a)                        # base
-pbs.add(canvas_b, "screen", 0.7)        # additive glow
-pbs.add(canvas_c, "difference", 0.5)    # psychedelic interference
-result = pbs.composite()
-```
-
-### Level 3: Temporal Feedback
-
-Feed previous frame back into current frame for recursive effects:
-
-```python
-fb = FeedbackBuffer()
-for each frame:
-    canvas = render_current()
-    canvas = fb.apply(canvas, decay=0.8, blend="screen",
-                      transform="zoom", transform_amt=0.015, hue_shift=0.02)
-```
-
-### Effect Nodes — Uniform Interface
-
-In the v2 protocol, effect nodes are used **inside** scene functions. The scene function itself returns a canvas. Effect nodes produce intermediate `(chars, colors)` that are rendered to canvas via the grid's `.render()` method or `_render_vf()`.
-
-```python
-class EffectNode:
-    def render(self, g, f, t, S) -> (chars, colors)
-
-# Concrete implementations:
-class ValueFieldEffect(EffectNode):
-    """Wraps a value field function + hue field function + palette."""
-    def __init__(self, val_fn, hue_fn, pal=PAL_DEFAULT, sat=0.7)
-
-class LambdaEffect(EffectNode):
-    """Wrap any (g,f,t,S) -> (ch,co) function."""
-    def __init__(self, fn)
-
-class ConditionalEffect(EffectNode):
-    """Switch effects based on audio features."""
-    def __init__(self, condition, if_true, if_false=None)
-```
-
-### Value Field Generators (Atomic Building Blocks)
-
-These produce float32 arrays `(rows, cols)` in range [0,1]. They are the raw visual patterns. All have signature `(g, f, t, S, **params) -> float32 array`.
-
-```python
-def vf_sinefield(g, f, t, S, bri=0.5,
-                 freq=(0.13, 0.17, 0.07, 0.09), speed=(0.5, -0.4, -0.3, 0.2)):
-    """Layered sine field. General purpose background/texture."""
-    v1 = np.sin(g.cc*freq[0] + t*speed[0]) * np.sin(g.rr*freq[1] - t*speed[1]) * 0.5 + 0.5
-    v2 = np.sin(g.cc*freq[2] - t*speed[2] + g.rr*freq[3]) * 0.4 + 0.5
-    v3 = np.sin(g.dist_n*5 + t*0.2) * 0.3 + 0.4
-    return np.clip((v1*0.35 + v2*0.35 + v3*0.3) * bri * (0.6 + f.get("rms",0.3)*0.6), 0, 1)
-
-def vf_smooth_noise(g, f, t, S, octaves=3, bri=0.5):
-    """Multi-octave sine approximation of Perlin noise."""
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(octaves):
-        freq = 0.05 * (2 ** i); amp = 0.5 / (i + 1)
-        phase = t * (0.3 + i * 0.2)
-        val = val + np.sin(g.cc*freq + phase) * np.cos(g.rr*freq*0.7 - phase*0.5) * amp
-    return np.clip(val * 0.5 + 0.5, 0, 1) * bri
-
-def vf_rings(g, f, t, S, n_base=6, spacing_base=4):
-    """Concentric rings, bass-driven count and wobble."""
-    n = int(n_base + f.get("sub_r",0.3)*25 + f.get("bass",0.3)*10)
-    sp = spacing_base + f.get("bass_r",0.3)*7 + f.get("rms",0.3)*3
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ri in range(n):
-        rad = (ri+1)*sp + f.get("bdecay",0)*15
-        wobble = f.get("mid_r",0.3)*5*np.sin(g.angle*3+t*4)
-        rd = np.abs(g.dist - rad - wobble)
-        th = 1 + f.get("sub",0.3)*3
-        val = np.maximum(val, np.clip((1 - rd/th) * (0.4 + f.get("bass",0.3)*0.8), 0, 1))
-    return val
-
-def vf_spiral(g, f, t, S, n_arms=3, tightness=2.5):
-    """Logarithmic spiral arms."""
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ai in range(n_arms):
-        offset = ai * 2*np.pi / n_arms
-        log_r = np.log(g.dist + 1) * tightness
-        arm_phase = g.angle + offset - log_r + t * 0.8
-        arm_val = np.clip(np.cos(arm_phase * n_arms) * 0.6 + 0.2, 0, 1)
-        arm_val *= (0.4 + f.get("rms",0.3)*0.6) * np.clip(1 - g.dist_n*0.5, 0.2, 1)
-        val = np.maximum(val, arm_val)
-    return val
-
-def vf_tunnel(g, f, t, S, speed=3.0, complexity=6):
-    """Tunnel depth effect — infinite zoom feeling."""
-    tunnel_d = 1.0 / (g.dist_n + 0.1)
-    v1 = np.sin(tunnel_d*2 - t*speed) * 0.45 + 0.55
-    v2 = np.sin(g.angle*complexity + tunnel_d*1.5 - t*2) * 0.35 + 0.55
-    return np.clip(v1*0.5 + v2*0.5, 0, 1)
-
-def vf_vortex(g, f, t, S, twist=3.0):
-    """Twisting radial pattern — distance modulates angle."""
-    twisted = g.angle + g.dist_n * twist * np.sin(t * 0.5)
-    val = np.sin(twisted * 4 - t * 2) * 0.5 + 0.5
-    return np.clip(val * (0.5 + f.get("bass",0.3)*0.8), 0, 1)
-
-def vf_interference(g, f, t, S, n_waves=6):
-    """Overlapping sine waves creating moire patterns."""
-    drivers = ["mid_r", "himid_r", "bass_r", "lomid_r", "hi_r", "sub_r"]
-    vals = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(min(n_waves, len(drivers))):
-        angle = i * np.pi / n_waves
-        freq = 0.06 + i * 0.03; sp = 0.5 + i * 0.3
-        proj = g.cc * np.cos(angle) + g.rr * np.sin(angle)
-        vals = vals + np.sin(proj*freq + t*sp) * f.get(drivers[i], 0.3) * 2.5
-    return np.clip(vals * 0.12 + 0.45, 0.1, 1)
-
-def vf_aurora(g, f, t, S, n_bands=3):
-    """Horizontal aurora bands."""
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for i in range(n_bands):
-        fr = 0.08 + i*0.04; fc = 0.012 + i*0.008
-        sr = 0.7 + i*0.3; sc = 0.18 + i*0.12
-        val = val + np.sin(g.rr*fr + t*sr) * np.sin(g.cc*fc + t*sc) * (0.6/n_bands)
-    return np.clip(val * (f.get("lomid_r",0.3)*3 + 0.2), 0, 0.7)
-
-def vf_ripple(g, f, t, S, sources=None, freq=0.3, damping=0.02):
-    """Concentric ripples from point sources."""
-    if sources is None: sources = [(0.5, 0.5)]
-    val = np.zeros((g.rows, g.cols), dtype=np.float32)
-    for ry, rx in sources:
-        dy = g.rr - g.rows*ry; dx = g.cc - g.cols*rx
-        d = np.sqrt(dy**2 + dx**2)
-        val = val + np.sin(d*freq - t*4) * np.exp(-d*damping) * 0.5
-    return np.clip(val + 0.5, 0, 1)
-
-def vf_plasma(g, f, t, S):
-    """Classic plasma: sum of sines at different orientations and speeds."""
-    v = np.sin(g.cc * 0.03 + t * 0.7) * 0.5
-    v = v + np.sin(g.rr * 0.04 - t * 0.5) * 0.4
-    v = v + np.sin((g.cc * 0.02 + g.rr * 0.03) + t * 0.3) * 0.3
-    v = v + np.sin(g.dist_n * 4 - t * 0.8) * 0.3
-    return np.clip(v * 0.5 + 0.5, 0, 1)
-
-def vf_diamond(g, f, t, S, freq=0.15):
-    """Diamond/checkerboard pattern."""
-    val = np.abs(np.sin(g.cc * freq + t * 0.5)) * np.abs(np.sin(g.rr * freq * 1.2 - t * 0.3))
-    return np.clip(val * (0.6 + f.get("rms",0.3)*0.8), 0, 1)
-
-def vf_noise_static(g, f, t, S, density=0.4):
-    """Random noise — different each frame. Non-deterministic."""
-    return np.random.random((g.rows, g.cols)).astype(np.float32) * density * (0.5 + f.get("rms",0.3)*0.5)
-```
-
-### Hue Field Generators (Color Mapping)
-
-These produce float32 hue arrays [0,1]. Independently combinable with any value field. Each is a factory returning a closure with signature `(g, f, t, S) -> float32 array`. Can also be a plain float for fixed hue.
-
-```python
-def hf_fixed(hue):
-    """Single hue everywhere."""
-    def fn(g, f, t, S):
-        return np.full((g.rows, g.cols), hue, dtype=np.float32)
-    return fn
-
-def hf_angle(offset=0.0):
-    """Hue mapped to angle from center — rainbow wheel."""
-    def fn(g, f, t, S):
-        return (g.angle / (2 * np.pi) + offset + t * 0.05) % 1.0
-    return fn
-
-def hf_distance(base=0.5, scale=0.02):
-    """Hue mapped to distance from center."""
-    def fn(g, f, t, S):
-        return (base + g.dist * scale + t * 0.03) % 1.0
-    return fn
-
-def hf_time_cycle(speed=0.1):
-    """Hue cycles uniformly over time."""
-    def fn(g, f, t, S):
-        return np.full((g.rows, g.cols), (t * speed) % 1.0, dtype=np.float32)
-    return fn
-
-def hf_audio_cent():
-    """Hue follows spectral centroid — timbral color shifting."""
-    def fn(g, f, t, S):
-        return np.full((g.rows, g.cols), f.get("cent", 0.5) * 0.3, dtype=np.float32)
-    return fn
-
-def hf_gradient_h(start=0.0, end=1.0):
-    """Left-to-right hue gradient."""
-    def fn(g, f, t, S):
-        h = np.broadcast_to(
-            start + (g.cc / g.cols) * (end - start),
-            (g.rows, g.cols)
-        ).copy()  # .copy() is CRITICAL — see troubleshooting.md
-        return h % 1.0
-    return fn
-
-def hf_gradient_v(start=0.0, end=1.0):
-    """Top-to-bottom hue gradient."""
-    def fn(g, f, t, S):
-        h = np.broadcast_to(
-            start + (g.rr / g.rows) * (end - start),
-            (g.rows, g.cols)
-        ).copy()
-        return h % 1.0
-    return fn
-
-def hf_plasma(speed=0.3):
-    """Plasma-style hue field — organic color variation."""
-    def fn(g, f, t, S):
-        return (np.sin(g.cc*0.02 + t*speed)*0.5 + np.sin(g.rr*0.015 + t*speed*0.7)*0.5) % 1.0
-    return fn
-```
-
-### Combining Value Fields
-
-The combinatorial explosion comes from mixing value fields with math:
-
-```python
-# Multiplication = intersection (only shows where both have brightness)
-combined = vf_plasma(g,f,t,S) * vf_vortex(g,f,t,S)
-
-# Addition = union (shows both, clips at 1.0)
-combined = np.clip(vf_rings(g,f,t,S) + vf_spiral(g,f,t,S), 0, 1)
-
-# Interference = beat pattern (shows XOR-like patterns)
-combined = np.abs(vf_plasma(g,f,t,S) - vf_tunnel(g,f,t,S))
-
-# Modulation = one effect shapes the other
-combined = vf_rings(g,f,t,S) * (0.3 + 0.7 * vf_plasma(g,f,t,S))
-
-# Maximum = shows the brightest of two effects
-combined = np.maximum(vf_spiral(g,f,t,S), vf_aurora(g,f,t,S))
-```
-
-### Full Scene Example (v2 — Canvas Return)
-
-A v2 scene function composes effects internally and returns a pixel canvas:
-
-```python
-def scene_complex(r, f, t, S):
-    """v2 scene function: returns canvas (uint8 H,W,3).
-    r = Renderer, f = audio features, t = time, S = persistent state dict."""
-    g = r.grids["md"]
-    rows, cols = g.rows, g.cols
-    
-    # 1. Value field composition
-    plasma = vf_plasma(g, f, t, S)
-    vortex = vf_vortex(g, f, t, S, twist=4.0)
-    combined = np.clip(plasma * 0.6 + vortex * 0.5 + plasma * vortex * 0.4, 0, 1)
-    
-    # 2. Color from hue field
-    h = (hf_angle(0.3)(g,f,t,S) * 0.5 + hf_time_cycle(0.08)(g,f,t,S) * 0.5) % 1.0
-    
-    # 3. Render to canvas via _render_vf helper
-    canvas = _render_vf(g, combined, h, sat=0.75, pal=PAL_DENSE)
-    
-    # 4. Optional: blend a second layer
-    overlay = _render_vf(r.grids["sm"], vf_rings(r.grids["sm"],f,t,S),
-                         hf_fixed(0.6)(r.grids["sm"],f,t,S), pal=PAL_BLOCK)
-    canvas = blend_canvas(canvas, overlay, "screen", 0.4)
-    
-    return canvas
-    
-# In the render_clip() loop (handled by the framework):
-# canvas = scene_fn(r, f, t, S)
-# canvas = tonemap(canvas, gamma=scene_gamma)
-# canvas = feedback.apply(canvas, ...)
-# canvas = shader_chain.apply(canvas, f=f, t=t)
-# pipe.stdin.write(canvas.tobytes())
-```
-
-Vary the **value field combo**, **hue field**, **palette**, **blend modes**, **feedback config**, and **shader chain** per section for maximum visual variety. With 12 value fields × 8 hue fields × 14 palettes × 20 blend modes × 7 feedback transforms × 38 shaders, the combinations are effectively infinite.

skills/creative/ascii-video/references/inputs.md

@@ -1,407 +0,0 @@
-# Input Sources
-
-## Audio Analysis
-
-### Loading
-
-```python
-tmp = tempfile.mktemp(suffix=".wav")
-subprocess.run(["ffmpeg", "-y", "-i", input_path, "-ac", "1", "-ar", "22050",
-                "-sample_fmt", "s16", tmp], capture_output=True, check=True)
-with wave.open(tmp) as wf:
-    sr = wf.getframerate()
-    raw = wf.readframes(wf.getnframes())
-samples = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
-```
-
-### Per-Frame FFT
-
-```python
-hop = sr // fps          # samples per frame
-win = hop * 2            # analysis window (2x hop for overlap)
-window = np.hanning(win)
-freqs = rfftfreq(win, 1.0 / sr)
-
-bands = {
-    "sub":   (freqs >= 20)  & (freqs < 80),
-    "bass":  (freqs >= 80)  & (freqs < 250),
-    "lomid": (freqs >= 250) & (freqs < 500),
-    "mid":   (freqs >= 500) & (freqs < 2000),
-    "himid": (freqs >= 2000)& (freqs < 6000),
-    "hi":    (freqs >= 6000),
-}
-```
-
-For each frame: extract chunk, apply window, FFT, compute band energies.
-
-### Feature Set
-
-| Feature | Formula | Controls |
-|---------|---------|----------|
-| `rms` | `sqrt(mean(chunk²))` | Overall loudness/energy |
-| `sub`..`hi` | `sqrt(mean(band_magnitudes²))` | Per-band energy |
-| `centroid` | `sum(freq*mag) / sum(mag)` | Brightness/timbre |
-| `flatness` | `geomean(mag) / mean(mag)` | Noise vs tone |
-| `flux` | `sum(max(0, mag - prev_mag))` | Transient strength |
-| `sub_r`..`hi_r` | `band / sum(all_bands)` | Spectral shape (volume-independent) |
-| `cent_d` | `abs(gradient(centroid))` | Timbral change rate |
-| `beat` | Flux peak detection | Binary beat onset |
-| `bdecay` | Exponential decay from beats | Smooth beat pulse (0→1→0) |
-
-**Band ratios are critical** — they decouple spectral shape from volume, so a quiet bass section and a loud bass section both read as "bassy" rather than just "loud" vs "quiet".
-
-### Smoothing
-
-EMA prevents visual jitter:
-
-```python
-def ema(arr, alpha):
-    out = np.empty_like(arr); out[0] = arr[0]
-    for i in range(1, len(arr)):
-        out[i] = alpha * arr[i] + (1 - alpha) * out[i-1]
-    return out
-
-# Slow-moving features (alpha=0.12): centroid, flatness, band ratios, cent_d
-# Fast-moving features (alpha=0.3): rms, flux, raw bands
-```
-
-### Beat Detection
-
-```python
-flux_smooth = np.convolve(flux, np.ones(5)/5, mode="same")
-peaks, _ = signal.find_peaks(flux_smooth, height=0.15, distance=fps//5, prominence=0.05)
-
-beat = np.zeros(n_frames)
-bdecay = np.zeros(n_frames, dtype=np.float32)
-for p in peaks:
-    beat[p] = 1.0
-    for d in range(fps // 2):
-        if p + d < n_frames:
-            bdecay[p + d] = max(bdecay[p + d], math.exp(-d * 2.5 / (fps // 2)))
-```
-
-`bdecay` gives smooth 0→1→0 pulse per beat, decaying over ~0.5s. Use for flash/glitch/mirror triggers.
-
-### Normalization
-
-After computing all frames, normalize each feature to 0-1:
-
-```python
-for k in features:
-    a = features[k]
-    lo, hi = a.min(), a.max()
-    features[k] = (a - lo) / (hi - lo + 1e-10)
-```
-
-## Video Sampling
-
-### Frame Extraction
-
-```python
-# Method 1: ffmpeg pipe (memory efficient)
-cmd = ["ffmpeg", "-i", input_video, "-f", "rawvideo", "-pix_fmt", "rgb24",
-       "-s", f"{target_w}x{target_h}", "-r", str(fps), "-"]
-pipe = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
-frame_size = target_w * target_h * 3
-for fi in range(n_frames):
-    raw = pipe.stdout.read(frame_size)
-    if len(raw) < frame_size: break
-    frame = np.frombuffer(raw, dtype=np.uint8).reshape(target_h, target_w, 3)
-    # process frame...
-
-# Method 2: OpenCV (if available)
-cap = cv2.VideoCapture(input_video)
-```
-
-### Luminance-to-Character Mapping
-
-Convert video pixels to ASCII characters based on brightness:
-
-```python
-def frame_to_ascii(frame_rgb, grid, pal=PAL_DEFAULT):
-    """Convert video frame to character + color arrays."""
-    rows, cols = grid.rows, grid.cols
-    # Resize frame to grid dimensions
-    small = np.array(Image.fromarray(frame_rgb).resize((cols, rows), Image.LANCZOS))
-    # Luminance
-    lum = (0.299 * small[:,:,0] + 0.587 * small[:,:,1] + 0.114 * small[:,:,2]) / 255.0
-    # Map to chars
-    chars = val2char(lum, lum > 0.02, pal)
-    # Colors: use source pixel colors, scaled by luminance for visibility
-    colors = np.clip(small * np.clip(lum[:,:,None] * 1.5 + 0.3, 0.3, 1), 0, 255).astype(np.uint8)
-    return chars, colors
-```
-
-### Edge-Weighted Character Mapping
-
-Use edge detection for more detail in contour regions:
-
-```python
-def frame_to_ascii_edges(frame_rgb, grid, pal=PAL_DEFAULT, edge_pal=PAL_BOX):
-    gray = np.mean(frame_rgb, axis=2)
-    small_gray = resize(gray, (grid.rows, grid.cols))
-    lum = small_gray / 255.0
-
-    # Sobel edge detection
-    gx = np.abs(small_gray[:, 2:] - small_gray[:, :-2])
-    gy = np.abs(small_gray[2:, :] - small_gray[:-2, :])
-    edge = np.zeros_like(small_gray)
-    edge[:, 1:-1] += gx; edge[1:-1, :] += gy
-    edge = np.clip(edge / edge.max(), 0, 1)
-
-    # Edge regions get box drawing chars, flat regions get brightness chars
-    is_edge = edge > 0.15
-    chars = val2char(lum, lum > 0.02, pal)
-    edge_chars = val2char(edge, is_edge, edge_pal)
-    chars[is_edge] = edge_chars[is_edge]
-
-    return chars, colors
-```
-
-### Motion Detection
-
-Detect pixel changes between frames for motion-reactive effects:
-
-```python
-prev_frame = None
-def compute_motion(frame):
-    global prev_frame
-    if prev_frame is None:
-        prev_frame = frame.astype(np.float32)
-        return np.zeros(frame.shape[:2])
-    diff = np.abs(frame.astype(np.float32) - prev_frame).mean(axis=2)
-    prev_frame = frame.astype(np.float32) * 0.7 + prev_frame * 0.3  # smoothed
-    return np.clip(diff / 30.0, 0, 1)  # normalized motion map
-```
-
-Use motion map to drive particle emission, glitch intensity, or character density.
-
-### Video Feature Extraction
-
-Per-frame features analogous to audio features, for driving effects:
-
-```python
-def analyze_video_frame(frame_rgb):
-    gray = np.mean(frame_rgb, axis=2)
-    return {
-        "brightness": gray.mean() / 255.0,
-        "contrast": gray.std() / 128.0,
-        "edge_density": compute_edge_density(gray),
-        "motion": compute_motion(frame_rgb).mean(),
-        "dominant_hue": compute_dominant_hue(frame_rgb),
-        "color_variance": compute_color_variance(frame_rgb),
-    }
-```
-
-## Image Sequence
-
-### Static Image to ASCII
-
-Same as single video frame conversion. For animated sequences:
-
-```python
-import glob
-frames = sorted(glob.glob("frames/*.png"))
-for fi, path in enumerate(frames):
-    img = np.array(Image.open(path).resize((VW, VH)))
-    chars, colors = frame_to_ascii(img, grid, pal)
-```
-
-### Image as Texture Source
-
-Use an image as a background texture that effects modulate:
-
-```python
-def load_texture(path, grid):
-    img = np.array(Image.open(path).resize((grid.cols, grid.rows)))
-    lum = np.mean(img, axis=2) / 255.0
-    return lum, img  # luminance for char mapping, RGB for colors
-```
-
-## Text / Lyrics
-
-### SRT Parsing
-
-```python
-import re
-def parse_srt(path):
-    """Returns [(start_sec, end_sec, text), ...]"""
-    entries = []
-    with open(path) as f:
-        content = f.read()
-    blocks = content.strip().split("\n\n")
-    for block in blocks:
-        lines = block.strip().split("\n")
-        if len(lines) >= 3:
-            times = lines[1]
-            m = re.match(r"(\d+):(\d+):(\d+),(\d+) --> (\d+):(\d+):(\d+),(\d+)", times)
-            if m:
-                g = [int(x) for x in m.groups()]
-                start = g[0]*3600 + g[1]*60 + g[2] + g[3]/1000
-                end = g[4]*3600 + g[5]*60 + g[6] + g[7]/1000
-                text = " ".join(lines[2:])
-                entries.append((start, end, text))
-    return entries
-```
-
-### Lyrics Display Modes
-
-- **Typewriter**: characters appear left-to-right over the time window
-- **Fade-in**: whole line fades from dark to bright
-- **Flash**: appear instantly on beat, fade out
-- **Scatter**: characters start at random positions, converge to final position
-- **Wave**: text follows a sine wave path
-
-```python
-def lyrics_typewriter(ch, co, text, row, col, t, t_start, t_end, color):
-    """Reveal characters progressively over time window."""
-    progress = np.clip((t - t_start) / (t_end - t_start), 0, 1)
-    n_visible = int(len(text) * progress)
-    stamp(ch, co, text[:n_visible], row, col, color)
-```
-
-## Generative (No Input)
-
-For pure generative ASCII art, the "features" dict is synthesized from time:
-
-```python
-def synthetic_features(t, bpm=120):
-    """Generate audio-like features from time alone."""
-    beat_period = 60.0 / bpm
-    beat_phase = (t % beat_period) / beat_period
-    return {
-        "rms": 0.5 + 0.3 * math.sin(t * 0.5),
-        "bass": 0.5 + 0.4 * math.sin(t * 2 * math.pi / beat_period),
-        "sub": 0.3 + 0.3 * math.sin(t * 0.8),
-        "mid": 0.4 + 0.3 * math.sin(t * 1.3),
-        "hi": 0.3 + 0.2 * math.sin(t * 2.1),
-        "cent": 0.5 + 0.2 * math.sin(t * 0.3),
-        "flat": 0.4,
-        "flux": 0.3 + 0.2 * math.sin(t * 3),
-        "beat": 1.0 if beat_phase < 0.05 else 0.0,
-        "bdecay": max(0, 1.0 - beat_phase * 4),
-        # ratios
-        "sub_r": 0.2, "bass_r": 0.25, "lomid_r": 0.15,
-        "mid_r": 0.2, "himid_r": 0.12, "hi_r": 0.08,
-        "cent_d": 0.1,
-    }
-```
-
-## TTS Integration
-
-For narrated videos (testimonials, quotes, storytelling), generate speech audio per segment and mix with background music.
-
-### ElevenLabs Voice Generation
-
-```python
-import requests
-
-def generate_tts(text, voice_id, api_key, output_path, model="eleven_multilingual_v2"):
-    """Generate TTS audio via ElevenLabs API."""
-    url = f"https://api.elevenlabs.io/v1/text-to-speech/{voice_id}"
-    headers = {"xi-api-key": api_key, "Content-Type": "application/json"}
-    data = {"text": text, "model_id": model,
-            "voice_settings": {"stability": 0.5, "similarity_boost": 0.75}}
-    resp = requests.post(url, json=data, headers=headers, timeout=30)
-    resp.raise_for_status()
-    with open(output_path, "wb") as f:
-        f.write(resp.content)
-```
-
-### Voice Assignment
-
-Use multiple voices for variety. Shuffle deterministically so re-runs are consistent:
-
-```python
-import random as _rng
-
-def assign_voices(n_quotes, voice_pool, seed=42):
-    """Assign a different voice to each quote, cycling if needed."""
-    r = _rng.Random(seed)
-    shuffled = list(voice_pool)
-    r.shuffle(shuffled)
-    return [shuffled[i % len(shuffled)] for i in range(n_quotes)]
-```
-
-### Pronunciation Control
-
-TTS text should be separate from display text. Common fixes:
-- Brand names: spell phonetically ("Nous" -> "Noose", "nginx" -> "engine-x")
-- Abbreviations: expand ("API" -> "A P I", "CLI" -> "C L I")
-- Technical terms: add phonetic hints
-
-```python
-QUOTES = [("Display text here", "Author")]
-QUOTES_TTS = ["TTS text with phonetic spelling here"]
-# Keep both arrays in sync -- same indices
-```
-
-### Audio Pipeline
-
-1. Generate individual TTS clips (MP3/WAV per quote)
-2. Get duration of each clip
-3. Calculate timing: speech start/end per quote with gaps
-4. Concatenate into single TTS track with silence padding
-5. Mix with background music
-
-```python
-def build_tts_track(tts_clips, target_duration, gap_seconds=2.0):
-    """Concatenate TTS clips with gaps, pad to target duration."""
-    # Get durations
-    durations = []
-    for clip in tts_clips:
-        result = subprocess.run(
-            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
-             "-of", "csv=p=0", clip],
-            capture_output=True, text=True)
-        durations.append(float(result.stdout.strip()))
-    
-    # Calculate timing
-    total_speech = sum(durations)
-    total_gaps = target_duration - total_speech
-    gap = max(0.5, total_gaps / (len(tts_clips) + 1))
-    
-    timing = []  # (start, end, quote_index)
-    t = gap  # start after initial gap
-    for i, dur in enumerate(durations):
-        timing.append((t, t + dur, i))
-        t += dur + gap
-    
-    # Concatenate with ffmpeg
-    # ... silence padding + concat filter
-    return timing
-```
-
-### Audio Mixing
-
-Mix TTS (center) with background music (wide stereo, low volume):
-
-```python
-def mix_audio(tts_path, bgm_path, output_path, bgm_volume=0.15):
-    """Mix TTS centered with BGM panned wide stereo."""
-    cmd = [
-        "ffmpeg", "-y",
-        "-i", tts_path,   # mono TTS
-        "-i", bgm_path,   # stereo BGM
-        "-filter_complex",
-        f"[0:a]aformat=sample_fmts=fltp:sample_rates=44100:channel_layouts=mono,"
-        f"pan=stereo|c0=c0|c1=c0[tts];"  # TTS center
-        f"[1:a]loudnorm=I=-16:TP=-1.5:LRA=11,"
-        f"volume={bgm_volume},"
-        f"extrastereo=2.5[bgm];"  # BGM wide stereo
-        f"[tts][bgm]amix=inputs=2:duration=longest[out]",
-        "-map", "[out]", "-c:a", "pcm_s16le", output_path
-    ]
-    subprocess.run(cmd, capture_output=True, check=True)
-```
-
-### Feature Analysis on Mixed Audio
-
-Run the standard audio analysis (FFT, beat detection) on the final mixed track so visual effects react to both TTS and music:
-
-```python
-# Analyze mixed_final.wav (not individual tracks)
-features = analyze_audio("mixed_final.wav", fps=24)
-```
-
-This means visuals will pulse with both the music beats and the speech energy -- creating natural synchronization.

skills/creative/ascii-video/references/optimization.md

@@ -1,435 +0,0 @@
-# Optimization Reference
-
-## Hardware Detection
-
-Detect the user's hardware at script startup and adapt rendering parameters automatically. Never hardcode worker counts or resolution.
-
-### CPU and Memory Detection
-
-```python
-import multiprocessing
-import platform
-import shutil
-import os
-
-def detect_hardware():
-    """Detect hardware capabilities and return render config."""
-    cpu_count = multiprocessing.cpu_count()
-    
-    # Leave 1-2 cores free for OS + ffmpeg encoding
-    if cpu_count >= 16:
-        workers = cpu_count - 2
-    elif cpu_count >= 8:
-        workers = cpu_count - 1
-    elif cpu_count >= 4:
-        workers = cpu_count - 1
-    else:
-        workers = max(1, cpu_count)
-    
-    # Memory detection (platform-specific)
-    try:
-        if platform.system() == "Darwin":
-            import subprocess
-            mem_bytes = int(subprocess.check_output(["sysctl", "-n", "hw.memsize"]).strip())
-        elif platform.system() == "Linux":
-            with open("/proc/meminfo") as f:
-                for line in f:
-                    if line.startswith("MemTotal"):
-                        mem_bytes = int(line.split()[1]) * 1024
-                        break
-        else:
-            mem_bytes = 8 * 1024**3  # assume 8GB on unknown
-    except Exception:
-        mem_bytes = 8 * 1024**3
-
-    mem_gb = mem_bytes / (1024**3)
-    
-    # Each worker uses ~50-150MB depending on grid sizes
-    # Cap workers if memory is tight
-    mem_per_worker_mb = 150
-    max_workers_by_mem = int(mem_gb * 1024 * 0.6 / mem_per_worker_mb)  # use 60% of RAM
-    workers = min(workers, max_workers_by_mem)
-    
-    # ffmpeg availability and codec support
-    has_ffmpeg = shutil.which("ffmpeg") is not None
-    
-    return {
-        "cpu_count": cpu_count,
-        "workers": workers,
-        "mem_gb": mem_gb,
-        "platform": platform.system(),
-        "arch": platform.machine(),
-        "has_ffmpeg": has_ffmpeg,
-    }
-```
-
-### Adaptive Quality Profiles
-
-Scale resolution, FPS, CRF, and grid density based on hardware:
-
-```python
-def quality_profile(hw, target_duration_s, user_preference="auto"):
-    """
-    Returns render settings adapted to hardware.
-    user_preference: "auto", "draft", "preview", "production", "max"
-    """
-    if user_preference == "draft":
-        return {"vw": 960, "vh": 540, "fps": 12, "crf": 28, "workers": min(4, hw["workers"]),
-                "grid_scale": 0.5, "shaders": "minimal", "particles_max": 200}
-    
-    if user_preference == "preview":
-        return {"vw": 1280, "vh": 720, "fps": 15, "crf": 25, "workers": hw["workers"],
-                "grid_scale": 0.75, "shaders": "standard", "particles_max": 500}
-    
-    if user_preference == "max":
-        return {"vw": 3840, "vh": 2160, "fps": 30, "crf": 15, "workers": hw["workers"],
-                "grid_scale": 2.0, "shaders": "full", "particles_max": 3000}
-    
-    # "production" or "auto"
-    # Auto-detect: estimate render time, downgrade if it would take too long
-    n_frames = int(target_duration_s * 24)
-    est_seconds_per_frame = 0.18  # ~180ms at 1080p
-    est_total_s = n_frames * est_seconds_per_frame / max(1, hw["workers"])
-    
-    if hw["mem_gb"] < 4 or hw["cpu_count"] <= 2:
-        # Low-end: 720p, 15fps
-        return {"vw": 1280, "vh": 720, "fps": 15, "crf": 23, "workers": hw["workers"],
-                "grid_scale": 0.75, "shaders": "standard", "particles_max": 500}
-    
-    if est_total_s > 3600:  # would take over an hour
-        # Downgrade to 720p to speed up
-        return {"vw": 1280, "vh": 720, "fps": 24, "crf": 20, "workers": hw["workers"],
-                "grid_scale": 0.75, "shaders": "standard", "particles_max": 800}
-    
-    # Standard production: 1080p 24fps
-    return {"vw": 1920, "vh": 1080, "fps": 24, "crf": 20, "workers": hw["workers"],
-            "grid_scale": 1.0, "shaders": "full", "particles_max": 1200}
-
-
-def apply_quality_profile(profile):
-    """Set globals from quality profile."""
-    global VW, VH, FPS, N_WORKERS
-    VW = profile["vw"]
-    VH = profile["vh"]
-    FPS = profile["fps"]
-    N_WORKERS = profile["workers"]
-    # Grid sizes scale with resolution
-    # CRF passed to ffmpeg encoder
-    # Shader set determines which post-processing is active
-```
-
-### CLI Integration
-
-```python
-parser = argparse.ArgumentParser()
-parser.add_argument("--quality", choices=["draft", "preview", "production", "max", "auto"],
-                    default="auto", help="Render quality preset")
-parser.add_argument("--workers", type=int, default=0, help="Override worker count (0=auto)")
-parser.add_argument("--resolution", type=str, default="", help="Override resolution e.g. 1280x720")
-args = parser.parse_args()
-
-hw = detect_hardware()
-if args.workers > 0:
-    hw["workers"] = args.workers
-profile = quality_profile(hw, target_duration, args.quality)
-if args.resolution:
-    w, h = args.resolution.split("x")
-    profile["vw"], profile["vh"] = int(w), int(h)
-apply_quality_profile(profile)
-
-log(f"Hardware: {hw['cpu_count']} cores, {hw['mem_gb']:.1f}GB RAM, {hw['platform']}")
-log(f"Render:   {profile['vw']}x{profile['vh']} @{profile['fps']}fps, "
-    f"CRF {profile['crf']}, {profile['workers']} workers")
-```
-
-## Performance Budget
-
-Target: 100-200ms per frame (5-10 fps single-threaded, 40-80 fps across 8 workers).
-
-| Component | Time | Notes |
-|-----------|------|-------|
-| Feature extraction | 1-5ms | Pre-computed for all frames before render |
-| Effect function | 2-15ms | Vectorized numpy, avoid Python loops |
-| Character render | 80-150ms | **Bottleneck** -- per-cell Python loop |
-| Shader pipeline | 5-25ms | Depends on active shaders |
-| ffmpeg encode | ~5ms | Amortized by pipe buffering |
-
-## Bitmap Pre-Rasterization
-
-Rasterize every character at init, not per-frame:
-
-```python
-# At init time -- done once
-for c in all_characters:
-    img = Image.new("L", (cell_w, cell_h), 0)
-    ImageDraw.Draw(img).text((0, 0), c, fill=255, font=font)
-    bitmaps[c] = np.array(img, dtype=np.float32) / 255.0  # float32 for fast multiply
-
-# At render time -- fast lookup
-bitmap = bitmaps[char]
-canvas[y:y+ch, x:x+cw] = np.maximum(canvas[y:y+ch, x:x+cw],
-                                      (bitmap[:,:,None] * color).astype(np.uint8))
-```
-
-Collect all characters from all palettes + overlay text into the init set. Lazy-init for any missed characters.
-
-## Coordinate Array Caching
-
-Pre-compute all grid-relative coordinate arrays at init, not per-frame:
-
-```python
-# These are O(rows*cols) and used in every effect
-self.rr = np.arange(rows)[:, None]    # row indices
-self.cc = np.arange(cols)[None, :]    # col indices
-self.dist = np.sqrt(dx**2 + dy**2)   # distance from center
-self.angle = np.arctan2(dy, dx)       # angle from center
-self.dist_n = ...                      # normalized distance
-```
-
-## Vectorized Effect Patterns
-
-### Avoid Per-Cell Python Loops in Effects
-
-The render loop (compositing bitmaps) is unavoidably per-cell. But effect functions must be fully vectorized numpy -- never iterate over rows/cols in Python.
-
-Bad (O(rows*cols) Python loop):
-```python
-for r in range(rows):
-    for c in range(cols):
-        val[r, c] = math.sin(c * 0.1 + t) * math.cos(r * 0.1 - t)
-```
-
-Good (vectorized):
-```python
-val = np.sin(g.cc * 0.1 + t) * np.cos(g.rr * 0.1 - t)
-```
-
-### Vectorized Matrix Rain
-
-The naive per-column per-trail-pixel loop is the second biggest bottleneck after the render loop. Use numpy fancy indexing:
-
-```python
-# Instead of nested Python loops over columns and trail pixels:
-# Build row index arrays for all active trail pixels at once
-all_rows = []
-all_cols = []
-all_fades = []
-for c in range(cols):
-    head = int(state["ry"][c])
-    trail_len = state["rln"][c]
-    for i in range(trail_len):
-        row = head - i
-        if 0 <= row < rows:
-            all_rows.append(row)
-            all_cols.append(c)
-            all_fades.append(1.0 - i / trail_len)
-
-# Vectorized assignment
-ar = np.array(all_rows)
-ac = np.array(all_cols)
-af = np.array(all_fades, dtype=np.float32)
-# Assign chars and colors in bulk using fancy indexing
-ch[ar, ac] = ...  # vectorized char assignment
-co[ar, ac, 1] = (af * bri * 255).astype(np.uint8)  # green channel
-```
-
-### Vectorized Fire Columns
-
-Same pattern -- accumulate index arrays, assign in bulk:
-
-```python
-fire_val = np.zeros((rows, cols), dtype=np.float32)
-for fi in range(n_cols):
-    fx_c = int((fi * cols / n_cols + np.sin(t * 2 + fi * 0.7) * 3) % cols)
-    height = int(energy * rows * 0.7)
-    dy = np.arange(min(height, rows))
-    fr = rows - 1 - dy
-    frac = dy / max(height, 1)
-    # Width spread: base columns wider at bottom
-    for dx in range(-1, 2):  # 3-wide columns
-        c = fx_c + dx
-        if 0 <= c < cols:
-            fire_val[fr, c] = np.maximum(fire_val[fr, c],
-                                          (1 - frac * 0.6) * (0.5 + rms * 0.5))
-# Now map fire_val to chars and colors in one vectorized pass
-```
-
-## Bloom Optimization
-
-**Do NOT use `scipy.ndimage.uniform_filter`** -- measured at 424ms/frame.
-
-Use 4x downsample + manual box blur instead -- 84ms/frame (5x faster):
-
-```python
-sm = canvas[::4, ::4].astype(np.float32)  # 4x downsample
-br = np.where(sm > threshold, sm, 0)
-for _ in range(3):                          # 3-pass manual box blur
-    p = np.pad(br, ((1,1),(1,1),(0,0)), mode='edge')
-    br = (p[:-2,:-2] + p[:-2,1:-1] + p[:-2,2:] +
-          p[1:-1,:-2] + p[1:-1,1:-1] + p[1:-1,2:] +
-          p[2:,:-2] + p[2:,1:-1] + p[2:,2:]) / 9.0
-bl = np.repeat(np.repeat(br, 4, axis=0), 4, axis=1)[:H, :W]
-```
-
-## Vignette Caching
-
-Distance field is resolution- and strength-dependent, never changes per frame:
-
-```python
-_vig_cache = {}
-def sh_vignette(canvas, strength):
-    key = (canvas.shape[0], canvas.shape[1], round(strength, 2))
-    if key not in _vig_cache:
-        Y = np.linspace(-1, 1, H)[:, None]
-        X = np.linspace(-1, 1, W)[None, :]
-        _vig_cache[key] = np.clip(1.0 - np.sqrt(X**2+Y**2) * strength, 0.15, 1).astype(np.float32)
-    return np.clip(canvas * _vig_cache[key][:,:,None], 0, 255).astype(np.uint8)
-```
-
-Same pattern for CRT barrel distortion (cache remap coordinates).
-
-## Film Grain Optimization
-
-Generate noise at half resolution, tile up:
-
-```python
-noise = np.random.randint(-amt, amt+1, (H//2, W//2, 1), dtype=np.int16)
-noise = np.repeat(np.repeat(noise, 2, axis=0), 2, axis=1)[:H, :W]
-```
-
-2x blocky grain looks like film grain and costs 1/4 the random generation.
-
-## Parallel Rendering
-
-### Worker Architecture
-
-```python
-hw = detect_hardware()
-N_WORKERS = hw["workers"]
-
-# Batch splitting (for non-clip architectures)
-batch_size = (n_frames + N_WORKERS - 1) // N_WORKERS
-batches = [(i, i*batch_size, min((i+1)*batch_size, n_frames), features, seg_path) ...]
-
-with multiprocessing.Pool(N_WORKERS) as pool:
-    segments = pool.starmap(render_batch, batches)
-```
-
-### Per-Clip Parallelism (Preferred for Segmented Videos)
-
-```python
-from concurrent.futures import ProcessPoolExecutor, as_completed
-
-with ProcessPoolExecutor(max_workers=N_WORKERS) as pool:
-    futures = {pool.submit(render_clip, seg, features, path): seg["id"]
-               for seg, path in clip_args}
-    for fut in as_completed(futures):
-        clip_id = futures[fut]
-        try:
-            fut.result()
-            log(f"  {clip_id} done")
-        except Exception as e:
-            log(f"  {clip_id} FAILED: {e}")
-```
-
-### Worker Isolation
-
-Each worker:
-- Creates its own `Renderer` instance (with full grid + bitmap init)
-- Opens its own ffmpeg subprocess
-- Has independent random seed (`random.seed(batch_id * 10000)`)
-- Writes to its own segment file and stderr log
-
-### ffmpeg Pipe Safety
-
-**CRITICAL**: Never `stderr=subprocess.PIPE` with long-running ffmpeg. The stderr buffer fills at ~64KB and deadlocks:
-
-```python
-# WRONG -- will deadlock
-pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
-
-# RIGHT -- stderr to file
-stderr_fh = open(err_path, "w")
-pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=stderr_fh)
-# ... write all frames ...
-pipe.stdin.close()
-pipe.wait()
-stderr_fh.close()
-```
-
-### Concatenation
-
-```python
-with open(concat_file, "w") as cf:
-    for seg in segments:
-        cf.write(f"file '{seg}'\n")
-
-cmd = ["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", concat_file]
-if audio_path:
-    cmd += ["-i", audio_path, "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-shortest"]
-else:
-    cmd += ["-c:v", "copy"]
-cmd.append(output_path)
-subprocess.run(cmd, capture_output=True, check=True)
-```
-
-## Particle System Performance
-
-Cap particle counts based on quality profile:
-
-| System | Low | Standard | High |
-|--------|-----|----------|------|
-| Explosion | 300 | 1000 | 2500 |
-| Embers | 500 | 1500 | 3000 |
-| Starfield | 300 | 800 | 1500 |
-| Dissolve | 200 | 600 | 1200 |
-
-Cull by truncating lists:
-```python
-MAX_PARTICLES = profile.get("particles_max", 1200)
-if len(S["px"]) > MAX_PARTICLES:
-    for k in ("px", "py", "vx", "vy", "life", "char"):
-        S[k] = S[k][-MAX_PARTICLES:]  # keep newest
-```
-
-## Memory Management
-
-- Feature arrays: pre-computed for all frames, shared across workers via fork semantics (COW)
-- Canvas: allocated once per worker, reused (`np.zeros(...)`)
-- Character arrays: allocated per frame (cheap -- rows*cols U1 strings)
-- Bitmap cache: ~500KB per grid size, initialized once per worker
-
-Total memory per worker: ~50-150MB. Total: ~400-800MB for 8 workers.
-
-For low-memory systems (< 4GB), reduce worker count and use smaller grids.
-
-## Brightness Verification
-
-After render, spot-check brightness at sample timestamps:
-
-```python
-for t in [2, 30, 60, 120, 180]:
-    cmd = ["ffmpeg", "-ss", str(t), "-i", output_path,
-           "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]
-    r = subprocess.run(cmd, capture_output=True)
-    arr = np.frombuffer(r.stdout, dtype=np.uint8)
-    print(f"t={t}s  mean={arr.mean():.1f}  max={arr.max()}")
-```
-
-Target: mean > 5 for quiet sections, mean > 15 for active sections. If consistently below, increase brightness floor in effects and/or global boost multiplier.
-
-## Render Time Estimates
-
-Scale with hardware. Baseline: 1080p, 24fps, ~180ms/frame/worker.
-
-| Duration | Frames | 4 workers | 8 workers | 16 workers |
-|----------|--------|-----------|-----------|------------|
-| 30s | 720 | ~3 min | ~2 min | ~1 min |
-| 2 min | 2,880 | ~13 min | ~7 min | ~4 min |
-| 3.5 min | 5,040 | ~23 min | ~12 min | ~6 min |
-| 5 min | 7,200 | ~33 min | ~17 min | ~9 min |
-| 10 min | 14,400 | ~65 min | ~33 min | ~17 min |
-
-At 720p: multiply times by ~0.5. At 4K: multiply by ~4.
-
-Heavier effects (many particles, dense grids, extra shader passes) add ~20-50%.

skills/creative/ascii-video/references/scenes.md

@@ -1,382 +0,0 @@
-# Scene System Reference
-
-Scenes are the top-level creative unit. Each scene is a time-bounded segment with its own effect function, shader chain, feedback configuration, and tone-mapping gamma.
-
-## Scene Protocol (v2)
-
-### Function Signature
-
-```python
-def fx_scene_name(r, f, t, S) -> canvas:
-    """
-    Args:
-        r: Renderer instance — access multiple grids via r.get_grid("sm")
-        f: dict of audio/video features, all values normalized to [0, 1]
-        t: time in seconds (global, not local to scene)
-        S: dict for persistent state (particles, rain columns, etc.)
-
-    Returns:
-        canvas: numpy uint8 array, shape (VH, VW, 3) — full pixel frame
-    """
-```
-
-This replaces the v1 protocol where scenes returned `(chars, colors)` tuples. The v2 protocol gives scenes full control over multi-grid rendering and pixel-level composition internally.
-
-### The Renderer Class
-
-```python
-class Renderer:
-    def __init__(self):
-        self.grids = {}   # lazy-initialized grid cache
-        self.g = None      # "active" grid (for backward compat)
-        self.S = {}        # persistent state dict
-
-    def get_grid(self, key):
-        """Get or create a GridLayer by size key."""
-        if key not in self.grids:
-            sizes = {"xs": 8, "sm": 10, "md": 16, "lg": 20, "xl": 24, "xxl": 40}
-            self.grids[key] = GridLayer(FONT_PATH, sizes[key])
-        return self.grids[key]
-
-    def set_grid(self, key):
-        """Set active grid (legacy). Prefer get_grid() for multi-grid scenes."""
-        self.g = self.get_grid(key)
-        return self.g
-```
-
-**Key difference from v1**: scenes call `r.get_grid("sm")`, `r.get_grid("lg")`, etc. to access multiple grids. Each grid is lazy-initialized and cached. The `set_grid()` method still works for single-grid scenes.
-
-### Minimal Scene (Single Grid)
-
-```python
-def fx_simple_rings(r, f, t, S):
-    """Single-grid scene: rings with distance-mapped hue."""
-    canvas = _render_vf(r, "md",
-        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=8, spacing_base=3),
-        hf_distance(0.3, 0.02), PAL_STARS, f, t, S, sat=0.85)
-    return canvas
-```
-
-### Standard Scene (Two Grids + Blend)
-
-```python
-def fx_tunnel_ripple(r, f, t, S):
-    """Two-grid scene: tunnel depth exclusion-blended with ripple."""
-    canvas_a = _render_vf(r, "md",
-        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10) * 1.3,
-        hf_distance(0.55, 0.02), PAL_GREEK, f, t, S, sat=0.7)
-
-    canvas_b = _render_vf(r, "sm",
-        lambda g, f, t, S: vf_ripple(g, f, t, S,
-            sources=[(0.3,0.3), (0.7,0.7), (0.5,0.2)], freq=0.5, damping=0.012) * 1.4,
-        hf_angle(0.1), PAL_STARS, f, t, S, sat=0.8)
-
-    return blend_canvas(canvas_a, canvas_b, "exclusion", 0.8)
-```
-
-### Complex Scene (Three Grids + Conditional + Custom Rendering)
-
-```python
-def fx_rings_explosion(r, f, t, S):
-    """Three-grid scene with particles and conditional kaleidoscope."""
-    # Layer 1: rings
-    canvas_a = _render_vf(r, "sm",
-        lambda g, f, t, S: vf_rings(g, f, t, S, n_base=10, spacing_base=2) * 1.4,
-        lambda g, f, t, S: (g.angle / (2*np.pi) + t * 0.15) % 1.0,
-        PAL_STARS, f, t, S, sat=0.9)
-
-    # Layer 2: vortex on different grid
-    canvas_b = _render_vf(r, "md",
-        lambda g, f, t, S: vf_vortex(g, f, t, S, twist=6.0) * 1.2,
-        hf_time_cycle(0.15), PAL_BLOCKS, f, t, S, sat=0.8)
-
-    result = blend_canvas(canvas_b, canvas_a, "screen", 0.7)
-
-    # Layer 3: particles (custom rendering, not _render_vf)
-    g = r.get_grid("sm")
-    if "px" not in S:
-        S["px"], S["py"], S["vx"], S["vy"], S["life"], S["pch"] = (
-            [], [], [], [], [], [])
-    if f.get("beat", 0) > 0.5:
-        chars = list("\u2605\u2736\u2733\u2738\u2726\u2728*+")
-        for _ in range(int(80 + f.get("rms", 0.3) * 120)):
-            ang = random.uniform(0, 2 * math.pi)
-            sp = random.uniform(1, 10) * (0.5 + f.get("sub_r", 0.3) * 2)
-            S["px"].append(float(g.cols // 2))
-            S["py"].append(float(g.rows // 2))
-            S["vx"].append(math.cos(ang) * sp * 2.5)
-            S["vy"].append(math.sin(ang) * sp)
-            S["life"].append(1.0)
-            S["pch"].append(random.choice(chars))
-
-    # Update + draw particles
-    ch_p = np.full((g.rows, g.cols), " ", dtype="U1")
-    co_p = np.zeros((g.rows, g.cols, 3), dtype=np.uint8)
-    i = 0
-    while i < len(S["px"]):
-        S["px"][i] += S["vx"][i]; S["py"][i] += S["vy"][i]
-        S["vy"][i] += 0.03; S["life"][i] -= 0.02
-        if S["life"][i] <= 0:
-            for k in ("px","py","vx","vy","life","pch"): S[k].pop(i)
-        else:
-            pr, pc = int(S["py"][i]), int(S["px"][i])
-            if 0 <= pr < g.rows and 0 <= pc < g.cols:
-                ch_p[pr, pc] = S["pch"][i]
-                co_p[pr, pc] = hsv2rgb_scalar(
-                    0.08 + (1-S["life"][i])*0.15, 0.95, S["life"][i])
-            i += 1
-
-    canvas_p = g.render(ch_p, co_p)
-    result = blend_canvas(result, canvas_p, "add", 0.8)
-
-    # Conditional kaleidoscope on strong beats
-    if f.get("bdecay", 0) > 0.4:
-        result = sh_kaleidoscope(result.copy(), folds=6)
-
-    return result
-```
-
-### Scene with Custom Character Rendering (Matrix Rain)
-
-When you need per-cell control beyond what `_render_vf()` provides:
-
-```python
-def fx_matrix_layered(r, f, t, S):
-    """Matrix rain blended with tunnel — two grids, screen blend."""
-    # Layer 1: Matrix rain (custom per-column rendering)
-    g = r.get_grid("md")
-    rows, cols = g.rows, g.cols
-    pal = PAL_KATA
-
-    if "ry" not in S or len(S["ry"]) != cols:
-        S["ry"] = np.random.uniform(-rows, rows, cols).astype(np.float32)
-        S["rsp"] = np.random.uniform(0.3, 2.0, cols).astype(np.float32)
-        S["rln"] = np.random.randint(8, 35, cols)
-        S["rch"] = np.random.randint(1, len(pal), (rows, cols))
-
-    speed = 0.6 + f.get("bass", 0.3) * 3
-    if f.get("beat", 0) > 0.5: speed *= 2.5
-    S["ry"] += S["rsp"] * speed
-
-    ch = np.full((rows, cols), " ", dtype="U1")
-    co = np.zeros((rows, cols, 3), dtype=np.uint8)
-    heads = S["ry"].astype(int)
-    for c in range(cols):
-        head = heads[c]
-        for i in range(S["rln"][c]):
-            row = head - i
-            if 0 <= row < rows:
-                fade = 1.0 - i / S["rln"][c]
-                ch[row, c] = pal[S["rch"][row, c] % len(pal)]
-                if i == 0:
-                    v = int(min(255, fade * 300))
-                    co[row, c] = (int(v*0.9), v, int(v*0.9))
-                else:
-                    v = int(fade * 240)
-                    co[row, c] = (int(v*0.1), v, int(v*0.4))
-    canvas_a = g.render(ch, co)
-
-    # Layer 2: Tunnel on sm grid for depth texture
-    canvas_b = _render_vf(r, "sm",
-        lambda g, f, t, S: vf_tunnel(g, f, t, S, speed=5.0, complexity=10),
-        hf_distance(0.3, 0.02), PAL_BLOCKS, f, t, S, sat=0.6)
-
-    return blend_canvas(canvas_a, canvas_b, "screen", 0.5)
-```
-
----
-
-## Scene Table
-
-The scene table defines the timeline: which scene plays when, with what configuration.
-
-### Structure
-
-```python
-SCENES = [
-    {
-        "start": 0.0,           # start time in seconds
-        "end": 3.96,            # end time in seconds
-        "name": "starfield",    # identifier (used for clip filenames)
-        "grid": "sm",           # default grid (for render_clip setup)
-        "fx": fx_starfield,     # scene function reference (must be module-level)
-        "gamma": 0.75,          # tonemap gamma override (default 0.75)
-        "shaders": [            # shader chain (applied after tonemap + feedback)
-            ("bloom", {"thr": 120}),
-            ("vignette", {"s": 0.2}),
-            ("grain", {"amt": 8}),
-        ],
-        "feedback": None,       # feedback buffer config (None = disabled)
-        # "feedback": {"decay": 0.8, "blend": "screen", "opacity": 0.3,
-        #              "transform": "zoom", "transform_amt": 0.02, "hue_shift": 0.02},
-    },
-    {
-        "start": 3.96,
-        "end": 6.58,
-        "name": "matrix_layered",
-        "grid": "md",
-        "fx": fx_matrix_layered,
-        "shaders": [
-            ("crt", {"strength": 0.05}),
-            ("scanlines", {"intensity": 0.12}),
-            ("color_grade", {"tint": (0.7, 1.2, 0.7)}),
-            ("bloom", {"thr": 100}),
-        ],
-        "feedback": {"decay": 0.5, "blend": "add", "opacity": 0.2},
-    },
-    # ... more scenes ...
-]
-```
-
-### Beat-Synced Scene Cutting
-
-Derive cut points from audio analysis:
-
-```python
-# Get beat timestamps
-beats = [fi / FPS for fi in range(N_FRAMES) if features["beat"][fi] > 0.5]
-
-# Group beats into phrase boundaries (every 4-8 beats)
-cuts = [0.0]
-for i in range(0, len(beats), 4):  # cut every 4 beats
-    cuts.append(beats[i])
-cuts.append(DURATION)
-
-# Or use the music's structure: silence gaps, energy changes
-energy = features["rms"]
-# Find timestamps where energy drops significantly -> natural break points
-```
-
-### `render_clip()` — The Render Loop
-
-This function renders one scene to a clip file:
-
-```python
-def render_clip(seg, features, clip_path):
-    r = Renderer()
-    r.set_grid(seg["grid"])
-    S = r.S
-    random.seed(hash(seg["id"]) + 42)  # deterministic per scene
-
-    # Build shader chain from config
-    chain = ShaderChain()
-    for shader_name, kwargs in seg.get("shaders", []):
-        chain.add(shader_name, **kwargs)
-
-    # Setup feedback buffer
-    fb = None
-    fb_cfg = seg.get("feedback", None)
-    if fb_cfg:
-        fb = FeedbackBuffer()
-
-    fx_fn = seg["fx"]
-
-    # Open ffmpeg pipe
-    cmd = ["ffmpeg", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
-           "-s", f"{VW}x{VH}", "-r", str(FPS), "-i", "pipe:0",
-           "-c:v", "libx264", "-preset", "fast", "-crf", "20",
-           "-pix_fmt", "yuv420p", clip_path]
-    stderr_fh = open(clip_path.replace(".mp4", ".log"), "w")
-    pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
-                            stdout=subprocess.DEVNULL, stderr=stderr_fh)
-
-    for fi in range(seg["frame_start"], seg["frame_end"]):
-        t = fi / FPS
-        feat = {k: float(features[k][fi]) for k in features}
-
-        # 1. Scene renders canvas
-        canvas = fx_fn(r, feat, t, S)
-
-        # 2. Tonemap normalizes brightness
-        canvas = tonemap(canvas, gamma=seg.get("gamma", 0.75))
-
-        # 3. Feedback adds temporal recursion
-        if fb and fb_cfg:
-            canvas = fb.apply(canvas, **{k: fb_cfg[k] for k in fb_cfg})
-
-        # 4. Shader chain adds post-processing
-        canvas = chain.apply(canvas, f=feat, t=t)
-
-        pipe.stdin.write(canvas.tobytes())
-
-    pipe.stdin.close(); pipe.wait(); stderr_fh.close()
-```
-
-### Building Segments from Scene Table
-
-```python
-segments = []
-for i, scene in enumerate(SCENES):
-    segments.append({
-        "id": f"s{i:02d}_{scene['name']}",
-        "name": scene["name"],
-        "grid": scene["grid"],
-        "fx": scene["fx"],
-        "shaders": scene.get("shaders", []),
-        "feedback": scene.get("feedback", None),
-        "gamma": scene.get("gamma", 0.75),
-        "frame_start": int(scene["start"] * FPS),
-        "frame_end": int(scene["end"] * FPS),
-    })
-```
-
-### Parallel Rendering
-
-Scenes are independent units dispatched to a process pool:
-
-```python
-from concurrent.futures import ProcessPoolExecutor, as_completed
-
-with ProcessPoolExecutor(max_workers=N_WORKERS) as pool:
-    futures = {
-        pool.submit(render_clip, seg, features, clip_path): seg["id"]
-        for seg, clip_path in zip(segments, clip_paths)
-    }
-    for fut in as_completed(futures):
-        try:
-            fut.result()
-        except Exception as e:
-            log(f"ERROR {futures[fut]}: {e}")
-```
-
-**Pickling constraint**: `ProcessPoolExecutor` serializes arguments via pickle. Module-level functions can be pickled; lambdas and closures cannot. All `fx_*` scene functions MUST be defined at module level, not as closures or class methods.
-
-### Test-Frame Mode
-
-Render a single frame at a specific timestamp to verify visuals without a full render:
-
-```python
-if args.test_frame >= 0:
-    fi = min(int(args.test_frame * FPS), N_FRAMES - 1)
-    t = fi / FPS
-    feat = {k: float(features[k][fi]) for k in features}
-    scene = next(sc for sc in reversed(SCENES) if t >= sc["start"])
-    r = Renderer()
-    r.set_grid(scene["grid"])
-    canvas = scene["fx"](r, feat, t, r.S)
-    canvas = tonemap(canvas, gamma=scene.get("gamma", 0.75))
-    chain = ShaderChain()
-    for sn, kw in scene.get("shaders", []):
-        chain.add(sn, **kw)
-    canvas = chain.apply(canvas, f=feat, t=t)
-    Image.fromarray(canvas).save(f"test_{args.test_frame:.1f}s.png")
-    print(f"Mean brightness: {canvas.astype(float).mean():.1f}")
-```
-
-CLI: `python reel.py --test-frame 10.0`
-
----
-
-## Scene Design Checklist
-
-For each scene:
-
-1. **Choose 2-3 grid sizes** — different scales create interference
-2. **Choose different value fields** per layer — don't use the same effect on every grid
-3. **Choose different hue fields** per layer — or at minimum different hue offsets
-4. **Choose different palettes** per layer — mixing PAL_RUNE with PAL_BLOCKS looks different from PAL_RUNE with PAL_DENSE
-5. **Choose a blend mode** that matches the energy — screen for bright, difference for psychedelic, exclusion for subtle
-6. **Add conditional effects** on beat — kaleidoscope, mirror, glitch
-7. **Configure feedback** for trailing/recursive looks — or None for clean cuts
-8. **Set gamma** if using destructive shaders (solarize, posterize)
-9. **Test with --test-frame** at the scene's midpoint before full render

skills/creative/ascii-video/references/troubleshooting.md

@@ -1,331 +0,0 @@
-# Troubleshooting Reference
-
-Common bugs, gotchas, and platform-specific issues encountered during ASCII video development.
-
-## NumPy Broadcasting
-
-### The `broadcast_to().copy()` Trap
-
-Hue field generators often return arrays that are broadcast views — they have shape `(1, cols)` or `(rows, 1)` that numpy broadcasts to `(rows, cols)`. These views are **read-only**. If any downstream code tries to modify them in-place (e.g., `h %= 1.0`), numpy raises:
-
-```
-ValueError: output array is read-only
-```
-
-**Fix**: Always `.copy()` after `broadcast_to()`:
-
-```python
-h = np.broadcast_to(h, (g.rows, g.cols)).copy()
-```
-
-This is especially important in `_render_vf()` where hue arrays flow through `hsv2rgb()`.
-
-### The `+=` vs `+` Trap
-
-Broadcasting also fails with in-place operators when operand shapes don't match exactly:
-
-```python
-# FAILS if result is (rows,1) and operand is (rows, cols)
-val += np.sin(g.cc * 0.02 + t * 0.3) * 0.5
-
-# WORKS — creates a new array
-val = val + np.sin(g.cc * 0.02 + t * 0.3) * 0.5
-```
-
-The `vf_plasma()` function had this bug. Use `+` instead of `+=` when mixing different-shaped arrays.
-
-### Shape Mismatch in `hsv2rgb()`
-
-`hsv2rgb(h, s, v)` requires all three arrays to have identical shapes. If `h` is `(1, cols)` and `s` is `(rows, cols)`, the function crashes or produces wrong output.
-
-**Fix**: Ensure all inputs are broadcast and copied to `(rows, cols)` before calling.
-
----
-
-## Blend Mode Pitfalls
-
-### Overlay Crushes Dark Inputs
-
-`overlay(a, b) = 2*a*b` when `a < 0.5`. Two values of 0.12 produce `2 * 0.12 * 0.12 = 0.03`. The result is darker than either input.
-
-**Impact**: If both layers are dark (which ASCII art usually is), overlay produces near-black output.
-
-**Fix**: Use `screen` for dark source material. Screen always brightens: `1 - (1-a)*(1-b)`.
-
-### Colordodge Division by Zero
-
-`colordodge(a, b) = a / (1 - b)`. When `b = 1.0` (pure white pixels), this divides by zero.
-
-**Fix**: Add epsilon: `a / (1 - b + 1e-6)`. The implementation in `BLEND_MODES` should include this.
-
-### Colorburn Division by Zero
-
-`colorburn(a, b) = 1 - (1-a) / b`. When `b = 0` (pure black pixels), this divides by zero.
-
-**Fix**: Add epsilon: `1 - (1-a) / (b + 1e-6)`.
-
-### Multiply Always Darkens
-
-`multiply(a, b) = a * b`. Since both operands are [0,1], the result is always <= min(a,b). Never use multiply as a feedback blend mode — the frame goes black within a few frames.
-
-**Fix**: Use `screen` for feedback, or `add` with low opacity.
-
----
-
-## Multiprocessing
-
-### Pickling Constraints
-
-`ProcessPoolExecutor` serializes function arguments via pickle. This constrains what you can pass to workers:
-
-| Can Pickle | Cannot Pickle |
-|-----------|---------------|
-| Module-level functions (`def fx_foo():`) | Lambdas (`lambda x: x + 1`) |
-| Dicts, lists, numpy arrays | Closures (functions defined inside functions) |
-| Class instances (with `__reduce__`) | Instance methods |
-| Strings, numbers | File handles, sockets |
-
-**Impact**: All scene functions referenced in the SCENES table must be defined at module level with `def`. If you use a lambda or closure, you get:
-
-```
-_pickle.PicklingError: Can't pickle <function <lambda> at 0x...>
-```
-
-**Fix**: Define all scene functions at module top level. Lambdas used inside `_render_vf()` as val_fn/hue_fn are fine because they execute within the worker process — they're not pickled across process boundaries.
-
-### macOS spawn vs Linux fork
-
-On macOS, `multiprocessing` defaults to `spawn` (full serialization). On Linux, it defaults to `fork` (copy-on-write). This means:
-
-- **macOS**: Feature arrays are serialized per worker (~57KB for 30s video, but scales with duration). Each worker re-imports the entire module.
-- **Linux**: Feature arrays are shared via COW. Workers inherit the parent's memory.
-
-**Impact**: On macOS, module-level code (like `detect_hardware()`) runs in every worker process. If it has side effects (e.g., subprocess calls), those happen N+1 times.
-
-### Per-Worker State Isolation
-
-Each worker creates its own:
-- `Renderer` instance (with fresh grid cache)
-- `FeedbackBuffer` (feedback doesn't cross scene boundaries)
-- Random seed (`random.seed(hash(seg_id) + 42)`)
-
-This means:
-- Particle state doesn't carry between scenes (expected)
-- Feedback trails reset at scene cuts (expected)
-- `np.random` state is NOT seeded by `random.seed()` — they use separate RNGs
-
-**Fix for deterministic noise**: Use `np.random.RandomState(seed)` explicitly:
-
-```python
-rng = np.random.RandomState(hash(seg_id) + 42)
-noise = rng.random((rows, cols))
-```
-
----
-
-## Brightness Issues
-
-### Dark Scenes After Tonemap
-
-If a scene is still dark after tonemap, check:
-
-1. **Gamma too high**: Lower gamma (0.5-0.6) for scenes with destructive post-processing
-2. **Shader destroying brightness**: Solarize, posterize, or contrast adjustments in the shader chain can undo tonemap's work. Move destructive shaders earlier in the chain, or increase gamma to compensate.
-3. **Feedback with multiply**: Multiply feedback darkens every frame. Switch to screen or add.
-4. **Overlay blend in scene**: If the scene function uses `blend_canvas(..., "overlay", ...)` with dark layers, switch to screen.
-
-### Diagnostic: Test-Frame Brightness
-
-```bash
-python reel.py --test-frame 10.0
-# Output: Mean brightness: 44.3, max: 255
-```
-
-If mean < 20, the scene needs attention. Common fixes:
-- Lower gamma in the SCENES entry
-- Change internal blend modes from overlay/multiply to screen/add
-- Increase value field multipliers (e.g., `vf_plasma(...) * 1.5`)
-- Check that the shader chain doesn't have an aggressive solarize or threshold
-
-### v1 Brightness Pattern (Deprecated)
-
-The old pattern used a linear multiplier:
-
-```python
-# OLD — don't use
-canvas = np.clip(canvas.astype(np.float32) * 2.0, 0, 255).astype(np.uint8)
-```
-
-This fails because:
-- Dark scenes (mean 8): `8 * 2.0 = 16` — still dark
-- Bright scenes (mean 130): `130 * 2.0 = 255` — clipped, lost detail
-
-Use `tonemap()` instead. See `composition.md` § Adaptive Tone Mapping.
-
----
-
-## ffmpeg Issues
-
-### Pipe Deadlock
-
-The #1 production bug. If you use `stderr=subprocess.PIPE`:
-
-```python
-# DEADLOCK — stderr buffer fills at 64KB, blocks ffmpeg, blocks your writes
-pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
-```
-
-**Fix**: Always redirect stderr to a file:
-
-```python
-stderr_fh = open(err_path, "w")
-pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
-                        stdout=subprocess.DEVNULL, stderr=stderr_fh)
-```
-
-### Frame Count Mismatch
-
-If the number of frames written to the pipe doesn't match what ffmpeg expects (based on `-r` and duration), the output may have:
-- Missing frames at the end
-- Incorrect duration
-- Audio-video desync
-
-**Fix**: Calculate frame count explicitly: `n_frames = int(duration * FPS)`. Don't use `range(int(start*FPS), int(end*FPS))` without verifying the total matches.
-
-### Concat Fails with "unsafe file name"
-
-```
-[concat @ ...] Unsafe file name
-```
-
-**Fix**: Always use `-safe 0`:
-```python
-["ffmpeg", "-f", "concat", "-safe", "0", "-i", concat_path, ...]
-```
-
----
-
-## Font Issues
-
-### Cell Height (macOS Pillow)
-
-`textbbox()` and `getbbox()` return incorrect heights on some macOS Pillow versions. Use `getmetrics()`:
-
-```python
-ascent, descent = font.getmetrics()
-cell_height = ascent + descent  # correct
-# NOT: font.getbbox("M")[3]  # wrong on some versions
-```
-
-### Missing Unicode Glyphs
-
-Not all fonts render all Unicode characters. If a palette character isn't in the font, the glyph renders as a blank or tofu box, appearing as a dark hole in the output.
-
-**Fix**: Validate at init:
-
-```python
-all_chars = set()
-for pal in [PAL_DEFAULT, PAL_DENSE, PAL_RUNE, ...]:
-    all_chars.update(pal)
-
-valid_chars = set()
-for c in all_chars:
-    if c == " ":
-        valid_chars.add(c)
-        continue
-    img = Image.new("L", (20, 20), 0)
-    ImageDraw.Draw(img).text((0, 0), c, fill=255, font=font)
-    if np.array(img).max() > 0:
-        valid_chars.add(c)
-    else:
-        log(f"WARNING: '{c}' (U+{ord(c):04X}) missing from font")
-```
-
-### Platform Font Paths
-
-| Platform | Common Paths |
-|----------|-------------|
-| macOS | `/System/Library/Fonts/Menlo.ttc`, `/System/Library/Fonts/Monaco.ttf` |
-| Linux | `/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf` |
-| Windows | `C:\Windows\Fonts\consola.ttf` (Consolas) |
-
-Always probe multiple paths and fall back gracefully. See `architecture.md` § Font Selection.
-
----
-
-## Performance
-
-### Slow Shaders
-
-Some shaders use Python loops and are very slow at 1080p:
-
-| Shader | Issue | Fix |
-|--------|-------|-----|
-| `wave_distort` | Per-row Python loop | Use vectorized fancy indexing |
-| `halftone` | Triple-nested loop | Vectorize with block reduction |
-| `matrix rain` | Per-column per-trail loop | Accumulate index arrays, bulk assign |
-
-### Render Time Scaling
-
-If render is taking much longer than expected:
-1. Check grid count — each extra grid adds ~100-150ms/frame for init
-2. Check particle count — cap at quality-appropriate limits
-3. Check shader count — each shader adds 2-25ms
-4. Check for accidental Python loops in effects (should be numpy only)
-
----
-
-## Common Mistakes
-
-### Using `r.S` vs the `S` Parameter
-
-The v2 scene protocol passes `S` (the state dict) as an explicit parameter. But `S` IS `r.S` — they're the same object. Both work:
-
-```python
-def fx_scene(r, f, t, S):
-    S["counter"] = S.get("counter", 0) + 1   # via parameter (preferred)
-    r.S["counter"] = r.S.get("counter", 0) + 1  # via renderer (also works)
-```
-
-Use the `S` parameter for clarity. The explicit parameter makes it obvious that the function has persistent state.
-
-### Forgetting to Handle Empty Feature Values
-
-Audio features default to 0.0 if the audio is silent. Use `.get()` with sensible defaults:
-
-```python
-energy = f.get("bass", 0.3)  # default to 0.3, not 0
-```
-
-If you default to 0, effects go blank during silence.
-
-### Writing New Files Instead of Editing Existing State
-
-A common bug in particle systems: creating new arrays every frame instead of updating persistent state.
-
-```python
-# WRONG — particles reset every frame
-S["px"] = []
-for _ in range(100):
-    S["px"].append(random.random())
-
-# RIGHT — only initialize once, update each frame
-if "px" not in S:
-    S["px"] = []
-# ... emit new particles based on beats
-# ... update existing particles
-```
-
-### Not Clipping Value Fields
-
-Value fields should be [0, 1]. If they exceed this range, `val2char()` produces index errors:
-
-```python
-# WRONG — vf_plasma() * 1.5 can exceed 1.0
-val = vf_plasma(g, f, t, S) * 1.5
-
-# RIGHT — clip after scaling
-val = np.clip(vf_plasma(g, f, t, S) * 1.5, 0, 1)
-```
-
-The `_render_vf()` helper clips automatically, but if you're building custom scenes, clip explicitly.