@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/prismer-hermes-agent/references/providers-and-models.md

@@ -0,0 +1,81 @@
+# Providers & Model Aliases
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Set via `hermes model` (picker) or `hermes setup`. 35+ provider profiles ship as
+plugins under `plugins/model-providers/`; user plugins of the same name override.
+Full docs: https://hermes-agent.nousresearch.com/docs/integrations/providers
+
+### Providers
+
+| Provider | Auth | Key env var(s) |
+|----------|------|----------------|
+| openrouter | API key | `OPENROUTER_API_KEY` |
+| anthropic | API key | `ANTHROPIC_API_KEY` (also `CLAUDE_CODE_OAUTH_TOKEN`) |
+| nous | OAuth device code | `hermes auth add nous` (or `NOUS_API_KEY`) |
+| openai-codex | OAuth | `hermes auth add openai-codex` |
+| qwen-oauth | OAuth | `hermes auth add qwen-oauth` |
+| minimax-oauth | OAuth | `hermes auth add minimax-oauth` |
+| copilot | Token | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` (Copilot device flow — `gh auth login` tokens do NOT work) |
+| copilot-acp | External CLI | Copilot CLI on PATH or `COPILOT_CLI_PATH` |
+| gemini | API key | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
+| xai | API key | `XAI_API_KEY` (SuperGrok OAuth also supported) |
+| deepseek | API key | `DEEPSEEK_API_KEY` |
+| zai (GLM) | API key | `GLM_API_KEY` / `ZAI_API_KEY` |
+| minimax / minimax-cn | API key | `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY` |
+| kimi-coding / -cn | API key | `KIMI_API_KEY` / `KIMI_CN_API_KEY` |
+| alibaba (+coding-plan) | API key | `DASHSCOPE_API_KEY` / `ALIBABA_CODING_PLAN_API_KEY` |
+| xiaomi | API key | `XIAOMI_API_KEY` |
+| huggingface | Token | `HF_TOKEN` |
+| fireworks / novita / nvidia / deepinfra / gmi / arcee / stepfun / upstage / kilocode / ai-gateway / opencode-zen / opencode-go / ollama-cloud | API key | `<NAME>_API_KEY` |
+| bedrock / vertex / azure-foundry | Cloud SDK / key | AWS SDK creds / Vertex ADC / `AZURE_FOUNDRY_API_KEY` |
+| custom | Config | `model.base_url` + `model.api_key` in config.yaml |
+
+Multiple credentials per provider pool and rotate automatically (`hermes auth`).
+Fallback chain when the primary fails: `hermes fallback add|remove|list`.
+
+### User-defined model aliases
+
+Work with `/model <name>` in CLI and every gateway platform. Resolved by
+`hermes_cli/model_switch.py::resolve_alias()`; user aliases are checked BEFORE
+the built-in table, so a user `sonnet`/`grok` shadows the built-in.
+
+```yaml
+# Full form
+model_aliases:
+  fav:
+    model: claude-sonnet-4.6
+    provider: anthropic
+  local-qwen:
+    model: qwen3.5:397b
+    provider: custom
+    base_url: "https://ollama.com/v1"
+  theta:
+    model: theta-1
+    provider: custom
+    base_url: "https://theta.example.com/v1"
+    key_env: THETA_API_KEY        # or: api_key: "${THETA_API_KEY}"
+
+# Short form ("provider/model"), also via CLI:
+#   hermes config set model.aliases.fav openrouter/anthropic/claude-sonnet-4.6
+model:
+  aliases:
+    fav: openrouter/anthropic/claude-sonnet-4.6
+```
+
+`/model fav` — session-scoped; add `--global` to persist as default.
+
+An alias with its own `base_url` authenticates with its own credential
+(`api_key`, which also accepts a `"${VAR}"` reference, or `key_env`). With
+neither set the key is resolved from the alias HOST, never carried over from
+the provider that was active before the switch.
+
+Built-in aliases (catalog-resolved against the active provider): `sonnet`,
+`opus`, `haiku`, `claude`, `gpt5`, `gpt`, `codex`, `o3`, `o4`, `gemini`,
+`deepseek`, `grok`, `llama`, `qwen`, `minimax`, `nemotron`, `kimi`, `glm`,
+`step`, `mimo`, `trinity`.

package/built-in-skills/prismer-hermes-agent/references/security-privacy.md

@@ -0,0 +1,73 @@
+# Security & Privacy Toggles
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Common "why is Hermes doing X to my output / tool calls / commands?" toggles — and the exact commands to change them. Most of these need a fresh session (`/reset` in chat, or start a new `hermes` invocation) because they're read once at startup.
+
+### Secret redaction in tool output
+
+Secret redaction is **on by default** — tool output (terminal stdout, `read_file`, web content, subagent summaries, etc.) is scanned for strings that look like API keys, tokens, and secrets before it enters the conversation context and logs. Leave it enabled for normal use:
+
+```bash
+hermes config set security.redact_secrets true       # keep enabled globally
+```
+
+**Restart required.** `security.redact_secrets` is snapshotted at import time — toggling it mid-session (e.g. via `export HERMES_REDACT_SECRETS=false` from a tool call) will NOT take effect for the running process. Tell the user to change it in config from a terminal, then start a new session. This is deliberate — it prevents an LLM from flipping the toggle on itself mid-task.
+
+Disable only when you deliberately need raw credential-like strings for debugging or redactor development:
+```bash
+hermes config set security.redact_secrets false
+```
+
+### PII redaction in gateway messages
+
+Separate from secret redaction. When enabled, the gateway hashes user IDs and strips phone numbers from the session context before it reaches the model:
+
+```bash
+hermes config set privacy.redact_pii true    # enable
+hermes config set privacy.redact_pii false   # disable (default)
+```
+
+### Command approval prompts
+
+By default (`approvals.mode: smart`), Hermes asks an auxiliary LLM to assess shell commands flagged as destructive (`rm -rf`, `git reset --hard`, etc.). The modes are:
+
+- `smart` — auto-approve a low-risk command once, deny high-risk commands, and prompt when uncertain (default)
+- `manual` — always prompt
+- `off` — skip all approval prompts (equivalent to `--yolo`)
+
+```bash
+hermes config set approvals.mode smart       # recommended middle ground
+hermes config set approvals.mode off         # bypass everything (not recommended)
+```
+
+Per-invocation bypass without changing config:
+- `hermes --yolo …`
+- `export HERMES_YOLO_MODE=1`
+
+Note: YOLO / `approvals.mode: off` does NOT turn off secret redaction. They are independent.
+
+### "Reset permissions" / "make Hermes ask again"
+
+The user usually means: wipe the accumulated "Always allow" state — NOT yolo
+mode, and NOT a per-edit diff prompt (which doesn't exist; file writes never
+go through the approval prompt, only shell commands do). Two stores hold it:
+
+1. Shell-command allowlist: `hermes config set command_allowlist '[]'`
+2. Shell-hook consent (only if present): `rm -f ~/.hermes/shell-hooks-allowlist.json`
+
+Then sanity-check `hermes config get approvals.mode` (should not be `off`)
+and confirm `--yolo` isn't baked into their launch alias or systemd unit.
+
+### Shell hooks allowlist
+
+Some shell-hook integrations require explicit allowlisting before they fire. Managed via `~/.hermes/shell-hooks-allowlist.json` — prompted interactively the first time a hook wants to run.
+
+### Disabling the web/browser/image-gen tools
+
+To keep the model away from network or media tools entirely, open `hermes tools` and toggle per-platform. Takes effect on next session (`/reset`). See `references/configuration.md` for the toolset list.

package/built-in-skills/prismer-hermes-agent/references/slash-commands.md

@@ -0,0 +1,119 @@
+# Slash Commands (In-Session)
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Registry of record: `hermes_cli/commands.py` (`COMMAND_REGISTRY`) — every
+consumer (autocomplete, `/help`, Telegram menu, Slack mapping) derives from
+it. New commands land often; `/help` in-session is always authoritative.
+(CLI) = interactive CLI/TUI only. (GW) = gateway platforms only.
+
+### Session
+```
+/new (/reset) [name]     Fresh session
+/clear                   Clear screen + new session (CLI)
+/retry                   Resend last message
+/undo [N]                Back up N user turns and re-prompt
+/title [name]            Name the session
+/prompt (/compose)       Compose next prompt in $EDITOR (CLI)
+/compress (/compact)     Compress context ('here [N]' keeps N turns; --preview)
+/stop                    Kill background processes
+/rollback [N]            List/restore filesystem checkpoints
+/diff [mode] [--stat]    Git changes in cwd (staged|all|session modes)
+/snapshot [sub]          Create/restore Hermes config+state snapshots (CLI)
+/bg <prompt>              Run a prompt in a separate background session
+/btw <question>           Ask a side question about the current conversation without interrupting it
+/queue (/q) <prompt>     Queue prompt for next turn
+/steer <prompt>          Inject a message after the next tool call
+/agents (/tasks)         Show active agents and running tasks
+/goal [text|sub]         Standing goal across turns (status|pause|resume|clear)
+/subgoal [text]          Add/manage criteria on the active goal
+/branch (/fork) [name]   Branch the session
+/resume [name]           Resume a named session
+/sessions                Browse and resume previous sessions
+/handoff <platform>      Hand live session off to a messaging platform (CLI)
+/status                  Session, model, token, and context info
+/redraw                  Force full UI repaint (CLI)
+```
+
+### Configuration
+```
+/config                  Show config (CLI)
+/model [name] [--global] Switch model (session-scoped by default)
+/personality [name]      Set a personality
+/reasoning [level|show|hide] Reasoning effort/display (none..xhigh|max|ultra)
+/fast [normal|fast]      Priority/fast processing tier
+/verbose                 Cycle tool progress: off → new → all → verbose → log (CLI)
+/voice [on|off|tts]      Voice mode
+/yolo                    Toggle approval bypass
+/busy [queue|steer|interrupt] How messages behave while working (CLI + gateway)
+/indicator [style]       TUI busy indicator: kaomoji|emoji|unicode|ascii (CLI)
+/footer [on|off]         Gateway runtime-metadata footer on replies
+/skin [name]             Change theme (CLI)
+/statusbar (/sb)         Toggle status bar (CLI)
+/battery [on|off]        Battery indicator in status bar (CLI)
+/timestamps (/ts) [on|off] Message timestamps (CLI)
+/codex-runtime [auto|codex_app_server] Codex runtime toggle
+```
+
+### Tools & Skills
+```
+/tools [list|enable|disable] Manage tools (CLI)
+/toolsets                List toolsets (CLI)
+/skills                  Search/install/manage skills (CLI)
+/bundles                 List skill bundles (/<name> loads several skills)
+/learn <source>          Learn a reusable skill from dirs/URLs/this chat
+/memory [pending|approve|reject] Review pending memory writes / approval gate
+/pet [toggle|list|<slug>] Petdex mascot control (CLI)
+/hatch [description]     Generate a new pet from a description (CLI)
+/cron [sub]              Manage scheduled tasks (CLI)
+/suggestions (/suggest)  Review suggested automations
+/blueprint (/bp) [name]  Set up an automation from a blueprint
+/curator [sub]           Skill maintenance (status, run, pin, archive, …)
+/kanban [sub]            Multi-profile collaboration board
+/moa <prompt>            One prompt through the Mixture-of-Agents preset
+/reload                  Reload .env into the running session (CLI)
+/reload-mcp              Reload MCP servers
+/reload-skills           Re-scan skills directory
+/browser [connect|status] CDP connection to your live browser (CLI)
+/plugins                 List plugins (CLI)
+```
+
+### Gateway
+```
+/approve [session|always]  Approve a pending dangerous command (GW)
+/deny [all] [reason]       Deny a pending dangerous command (GW)
+/restart                   Restart gateway after draining active runs (GW)
+/sethome                   Set current chat as home channel (GW)
+/topic [off|help]          Telegram DM topic sessions (GW)
+/platform <pause|resume|list> Pause/resume a failing platform (GW)
+/commands [page]           Browse all commands, paginated (GW)
+```
+
+### Info
+```
+/help                    Show commands
+/usage [reset]           Token usage and rate limits
+/insights [days]         Usage analytics
+/whoami                  Slash-command access level (admin/user)
+/profile                 Active profile info
+/platforms (/gateway)    Platform connection status (CLI)
+/journey (/learning)     Learned skills + memories timeline (CLI)
+/subscription (/upgrade) Nous plan info (CLI)
+/topup                   Nous balance / billing
+/copy [N]                Copy last response to clipboard (CLI)
+/paste                   Attach clipboard image (CLI)
+/image <path>            Attach a local image file (CLI)
+/update                  Update Hermes to latest
+/version (/v)            Show version
+/debug [nous|local]      Upload debug report, get shareable links
+```
+
+### Exit
+```
+/quit (/exit) [--delete] Exit CLI; --delete also removes session history
+```

package/built-in-skills/prismer-hermes-agent/references/themes.md

@@ -0,0 +1,134 @@
+# Themes / Skins — Author a Hermes Color Theme
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Author a Hermes **skin** — one YAML file that themes the CLI, the TUI, and the
+desktop GUI at once. The skin engine (`hermes_cli/skin_engine.py`) resolves the
+active skin and the gateway pushes it to every surface, so a file dropped in
+`~/.hermes/skins/` is the theme analogue of a plugin: no code, all surfaces. This
+skill covers writing a good skin and activating it; it does not build GUI theme
+editors or ship built-in presets.
+
+## When to Use
+
+- The user asks for a custom look ("make me a synthwave theme", "dark forest
+  vibes", "match my brand colors") for Hermes itself.
+- The user wants the CLI/TUI/desktop to share one coordinated palette.
+- The user wants to iterate live ("that coral is too loud, make it teal") — edit
+  the active skin's YAML and every surface repaints as your tool finishes.
+
+## Prerequisites
+
+- Write access to the Hermes home dir — `~/.hermes` by default, or `$HERMES_HOME`
+  / the active profile's dir. Skins live in `<hermes-home>/skins/`.
+- Native tools: `write_file` (create the YAML), `read_file` / `search_files`
+  (inspect existing skins), `terminal` (activate via `hermes config set`).
+
+## How to Run
+
+1. Pick a lowercase, hyphen-safe `name` (e.g. `synthwave`).
+2. Copy `templates/skin.yaml` and fill in the palette (keep every key — missing
+   keys inherit the `default` skin).
+3. `write_file` it to `<hermes-home>/skins/<name>.yaml`.
+4. Activate it (see Procedure). Confirm the change landed.
+
+## Quick Reference — element → key
+
+Hex (`#rrggbb`). Theming is **semantic**: one key colors every element that plays
+that role, so match the element to its key. To recolor a specific element, set the
+key in its row (element-specific keys fall back to the shared one when unset).
+
+| Visible element | Key to set | Falls back to |
+|---|---|---|
+| App background (whole TUI + GUI) | `background` | terminal default |
+| **Tool-call marker** (`●`, tool spinner) | `ui_tool` | `ui_accent` |
+| **Thinking / reasoning text** | `ui_thinking` | `banner_dim` |
+| Accent — headings, links, chevrons, `Σ` | `ui_accent` / `banner_accent` | — |
+| Heading / primary text | `banner_title` / `ui_primary` | — |
+| Body / label text, user messages | `ui_text` / `banner_text`, `ui_label` | — |
+| Muted / secondary, tree connectors | `banner_dim` | — |
+| Borders, rules, gutters | `ui_border` / `banner_border` | — |
+| Prompt symbol color | `prompt` | `banner_text` |
+| Success / warn / error | `ui_ok` / `ui_warn` / `ui_error` | — |
+| Status bar text + usage | `status_bar_text`, `status_bar_good/warn/bad/critical` | — |
+| Diff add/remove (line + word) | `diff_added` / `diff_removed` / `diff_added_word` / `diff_removed_word` | built-in |
+| Code syntax (string/number/keyword/comment) | `syntax_string` / `syntax_number` / `syntax_keyword` / `syntax_comment` | accent/text/border/muted |
+| Completion menu | `completion_menu_bg` / `completion_menu_current_bg` / `…_meta_bg` | — |
+
+Note the sharing: `ui_accent` colors tool markers **and** headings/links/chevrons,
+so to recolor *only* tool calls (the classic "change the gold `●`") set `ui_tool`.
+`branding` (`agent_name`, `prompt_symbol`, `welcome`, `goodbye`, `help_header`),
+`spinner`, and `tool_prefix` are optional flavor; full schema in
+`hermes_cli/skin_engine.py`.
+
+## Procedure
+
+1. **Design the palette.** Choose a `background` first, then an `ui_accent` that
+   clears WCAG AA against it (~4.5:1) so labels stay legible — the GUI enforces
+   contrast but a low-contrast accent still looks washed out. Keep
+   `ui_ok`/`ui_warn`/`ui_error` recognizably green/amber/red.
+2. **Write the file** to `<hermes-home>/skins/<name>.yaml`. Every top-level
+   `colors` key from the template should be present.
+3. **Apply it yourself — never hand-edit `config.yaml`.** Run the safe writer via
+   `terminal`:
+   ```
+   hermes config set display.skin <name>
+   ```
+   The gateway's skin watcher notices the change and **repaints every surface live
+   within ~a second** — CLI, TUI, and desktop — and the skin appears in
+   Appearance / `Cmd-K` / `/skin`. You apply it; do NOT tell the user to run
+   `/skin` (they still can, but it's your job). The writer emits valid YAML — a
+   hand-edit can corrupt the file and break the live gateway (including `/`).
+4. **Confirm the new look landed** and tell the user how to revert: run
+   `hermes config set display.skin default` (or they can `/skin default`).
+
+## Tweak the active look (change one thing)
+
+When the user wants to adjust the CURRENT look ("make the tool `●` cyan", "warmer
+background"), use the one deterministic command — it edits the ACTIVE skin's ONE
+key in place, so everything else (background included) is untouched:
+
+```
+hermes skin set <key> <hex>      # e.g. hermes skin set ui_tool "#00FFFF"
+```
+
+It edits the active skin's file (a built-in is forked into an editable copy that
+keeps its full palette), the watcher repaints live, and nothing else moves. Do
+NOT hand-write a new skin from `default` for a tweak — that drops the current
+palette and resets the background. `hermes skin set background "#08201f"` changes
+only the background; `hermes skin use <name>` / `hermes skin list` switch and
+enumerate.
+
+## Pitfalls
+
+- **Don't hardcode `~/.hermes`** when a profile is active — resolve the real home
+  from `$HERMES_HOME` first, falling back to `~/.hermes`.
+- **Keep `#rrggbb` hex.** Shorthand `#rgb`, `rgb()`, and named colors are not
+  guaranteed to parse on every surface.
+- **Set `background`.** Without it the GUI has to guess a base surface from text
+  luminance — usable, but you lose control of the app background.
+- **Name collisions**: a skin named like a desktop built-in (`mono`, `slate`,
+  `cyberpunk`, `nous`, `midnight`, `ember`) won't override that built-in on the
+  GUI. Pick a fresh name.
+- **Never hand-edit `config.yaml` to activate.** Use `hermes config set
+  display.skin <name>` — a stray indent in a manual edit corrupts the file and
+  can break the live gateway (including `/`). One command, always valid.
+- **You apply it, not the user.** `hermes config set display.skin <name>` is
+  enough — the gateway's watcher repaints every surface within ~a second. Don't
+  defer to "type /skin yourself"; that's the old behavior.
+- **To change one color, edit the ACTIVE skin — never fork `default`.** Forking
+  `default` for a tweak drops the current palette: a skin with no `background`
+  resets the terminal to its own default (often black). Patch the active skin's
+  file in place so `background` and everything else survive.
+
+## Verification
+
+- `read_file` the written `<hermes-home>/skins/<name>.yaml` and confirm valid
+  YAML with the intended `name` and `colors`.
+- Run `hermes config get display.skin` and confirm it reports `<name>`.
+- The repaint lands as this turn ends — ask the user to confirm the new look.

package/built-in-skills/prismer-hermes-agent/references/troubleshooting.md

@@ -0,0 +1,87 @@
+# Troubleshooting
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+### Voice not working
+1. Check `stt.enabled: true` in config.yaml
+2. Verify provider: `pip install faster-whisper` or set API key
+3. In gateway: `/restart`. In CLI: exit and relaunch.
+
+### Tool not available
+1. `hermes tools` — check if toolset is enabled for your platform
+2. Some tools need env vars (check `.env`)
+3. `/reset` after enabling tools
+
+### Model/provider issues
+1. `hermes doctor` — check config and dependencies
+2. `hermes auth` — re-authenticate OAuth providers (or `hermes auth add <provider>`)
+3. Check `.env` has the right API key
+4. **Copilot 403**: `gh auth login` tokens do NOT work for Copilot API. You must use the Copilot-specific OAuth device code flow via `hermes model` → GitHub Copilot.
+
+### Changes not taking effect
+- **Tools/skills:** `/reset` starts a new session with updated toolset
+- **Config changes:** In gateway: `/restart`. In CLI: exit and relaunch.
+- **Code changes:** Restart the CLI or gateway process
+
+### web_extract shows a stale page (result caching)
+`web_search`/`web_extract` cache results for 20 minutes (PR #94618) — a
+repeat fetch of the same URL within the TTL is served from cache, which
+can look like "my website changes aren't showing up."
+
+Automatic carveouts (always fetched live, never cached):
+- localhost / 127.0.0.1 / `*.local` / `*.localhost` / single-label LAN
+  hostnames / private + link-local IP ranges (dev servers, hot-reload
+  builds, chat-GUI artifact previews)
+- URLs matched by `security.website_blocklist`
+- failed responses and keyless-rescue-served responses
+
+Developing a site tested over the PUBLIC internet (Vercel/Netlify
+preview, ngrok/cloudflared tunnel, staging domain)? Public DNS isn't
+auto-carved-out — list the host in config.yaml:
+
+```yaml
+web:
+  cache_exempt_hosts:      # always fetched live; effective immediately
+    - mysite.vercel.app
+    - "*.ngrok-free.app"
+    - mysite.dev           # suffix match: also covers preview.mysite.dev
+```
+
+Blunt instruments: `web.cache_ttl_minutes: 1` (min) or
+`web.cache_enabled: false` disables both caches entirely.
+
+### Skills not showing
+1. `hermes skills list` — verify installed
+2. `hermes skills config` — check platform enablement
+3. Load explicitly: `hermes -s name` (or the skill's own `/<name>` slash command)
+
+### Gateway issues
+Check logs first:
+```bash
+grep -i "failed to send\|error" ~/.hermes/logs/gateway.log | tail -20
+```
+
+Common gateway problems:
+- **Gateway dies on SSH logout**: Enable linger: `sudo loginctl enable-linger $USER`
+- **Gateway dies on WSL2 close**: WSL2 requires `systemd=true` in `/etc/wsl.conf` for systemd services to work. Without it, gateway falls back to `nohup` (dies when session closes).
+- **Gateway crash loop**: Reset the failed state: `systemctl --user reset-failed hermes-gateway`
+
+### Platform-specific issues
+- **Discord bot silent**: Must enable **Message Content Intent** in Bot → Privileged Gateway Intents.
+- **Slack bot only works in DMs**: Must subscribe to `message.channels` event. Without it, the bot ignores public channels.
+- **Windows-specific issues** (`Alt+Enter` newline, WinError 10106, UTF-8 BOM config, line endings): see `references/windows-quirks.md`.
+
+### Auxiliary models not working
+If `auxiliary` tasks (vision, compression, session_search) fail silently, the `auto` provider can't find a backend. Either set `OPENROUTER_API_KEY` or `GOOGLE_API_KEY`, or explicitly configure each auxiliary task's provider:
+```bash
+hermes config set auxiliary.vision.provider <your_provider>
+hermes config set auxiliary.vision.model <model_name>
+```
+
+### "Reset permissions" / auto-approving everything
+See `references/security-privacy.md` — wipe the "Always allow" stores, don't touch yolo mode.

package/built-in-skills/prismer-hermes-agent/references/tui-widgets.md

@@ -0,0 +1,144 @@
+# TUI Widgets — Live Panels for the Ink TUI Dock
+
+> Maintainer reference only. Read-only diagnosis may use the deployed Hermes
+> version; mutation, installation, provider credentials, cron, webhook, profile
+> and lifecycle changes require a separate authorized Runtime maintenance task.
+> These examples do not install tools or grant permissions in a tenant session.
+> Do not copy literal secret placeholders into config; inject scoped credentials
+> through the existing Runtime mechanism. Verify version-specific commands.
+
+Author widget apps for the Hermes TUI (`hermes --tui`): glanceable ambient
+panels docked above the status bar, or modal overlays that own the keyboard.
+Widgets are plain ESM files the TUI loads at startup — no build step, no
+repo changes. This skill does not cover desktop-app or web-dashboard
+widgets.
+
+## When to Use
+
+- The user asks for a live panel in the TUI (ticker, clock, countdown,
+  status card, API-backed readout).
+- The user wants a custom modal tool (picker, calculator, viewer) bound to
+  a slash command.
+
+## Prerequisites
+
+- The TUI must be in use (`hermes --tui`). Widgets do not render in the
+  classic CLI or messaging platforms.
+- Network-backed widgets need whatever credentials their API needs; fetch
+  failures must land as an error phase, never a crash.
+
+## How to Run
+
+1. Use `write_file` to create `~/.hermes/tui-widgets/<name>.mjs` (see
+   `templates/clock.mjs` for a complete working widget).
+2. If the TUI is running it hot-loads the file within ~a second (the
+   widgets directory is watched); `/widgets-reload` forces a rescan.
+3. The widget's id becomes its slash command automatically (`/<id>`), with
+   its `help` in the `/` completion popover. No other registration exists.
+4. Auto-open (no command needed): end `register(sdk)` with
+   `sdk.openWidget(app, app.init(''))` — the widget docks itself the moment
+   the file loads. Only do this when the user asked for it; note it re-docks
+   on every `/widgets-reload`.
+
+## Quick Reference
+
+A widget file default-exports `register(sdk)`:
+
+```js
+export default function register(sdk) {
+  const { Box, Text, defineWidgetApp, h } = sdk
+
+  defineWidgetApp({
+    id: 'clock',                    // slash command name
+    help: 'live clock in the dock', // `/` completion metadata
+    mode: 'ambient',                // 'ambient' docks; 'modal' takes input
+    init: arg => ({ label: arg.trim() || 'UTC' }),   // null = print usage
+    reduce: (state, { ch, key }) => (key.escape || ch === 'q' ? null : state),
+    render: ({ state, t }) => h(sdk.Dialog, { width: 24 }, h(Text, { color: t.color.label }, state.label))
+  })
+}
+```
+
+`sdk` contents: `defineWidgetApp`, `openWidget`, `updateWidget`, `isCtrl`,
+`React`, `h` (createElement — no JSX in .mjs), components `Box`, `Text`,
+`Dialog`, `Overlay`, `WidgetGrid`, `GridAreas`, and loaders `Shimmer`,
+`ShimmerRows`, `useShimmerPhase` — use `ShimmerRows` for loading phases
+instead of a bare "loading…" line.
+
+Expand/collapse: `sdk.Accordion` — the same primitive the session panel's
+tool/skill sections use. `h(Accordion, { t, title: 'details', count: 3,
+defaultOpen: false }, body)` toggles on CLICK (works in ambient widgets,
+which receive no keys); modal apps may pass `open` + `onToggle` to drive it
+from reducer state instead.
+
+Stable sizing (cards must NEVER resize while ticking):
+
+- Give `Dialog` an explicit `width`; charts already return exactly the
+  `width` you ask for (short series pad-left while history warms up).
+- Pad dynamic numbers: `String(v).padStart(6)` — `51 ms` → `112 ms` must
+  not change the line length.
+- Keep row counts constant per phase; swap content, not structure.
+
+Charts (pure string builders — color the result with theme tones):
+
+- `sdk.sparkline(series, width?)` → `▂▃▅▇█▆` one-row trend
+- `sdk.sparkRows(series, width, rows)` → multi-row column chart (top line
+  first) — the mission-control panel look; taller cells gain resolution
+- `sdk.gauge(ratio, width)` → `█████░░░` fill bar for a 0..1 value
+- `sdk.hbars(values, width)` → horizontal bar chart, one bar per value,
+  eighth-block tips, scaled to the max
+
+Keep a rolling series in component state (push per tick, cap ~120 samples)
+and render `sparkRows` for dashboard panels, `sparkline` for one-liners.
+
+Contract essentials:
+
+- `mode: 'ambient'` — captures no input, the command toggles it; `render`
+  returns a CARD (usually `Dialog`), never `Overlay`.   Placement via `zone` — every zone RESERVES real space (nothing ever
+  paints over the transcript):
+  - Docks (chrome rows): `dock-top` (under the top status bar),
+    `dock-bottom` (default — above the bottom one).
+  - Rails (side columns beside the transcript; text reflows around them):
+    `top-left`, `top-right`, `bottom-left`, `bottom-right` — corner names
+    pick the rail side and its top/bottom anchor. Set `width` on the app
+    to the card's width (match your Dialog width; default 44) — the rail
+    reserves exactly that many columns.
+  Map the user's words to the nearest zone: "top right" → `top-right`,
+  "above/next to the status bar" → a dock. Rails suit narrow cards
+  (~30-46 cols); full-width or short-and-wide content belongs in a dock.
+- `mode: 'modal'` (default) — owns every keypress; `reduce` returns next
+  state, the same reference to swallow a key, or `null` to close; `render`
+  wraps content in `Overlay` for placement.
+- Async data: fire the fetch from `init`, land results with
+  `sdk.updateWidget(app, fn)` — it no-ops if the widget was closed, so a
+  late reply can never resurrect it.
+- Animation: own a timer inside a component via `React.useState` +
+  `React.useEffect` (see the template); keep intervals ≥ 250ms.
+- Colors: ALWAYS theme tones (`t.color.primary/label/muted/ok/error/…`),
+  never hardcoded hexes — widgets must survive `/skin` and light/dark.
+
+## Procedure
+
+1. Pick `id`, `mode`, and the state shape; keep state serializable.
+2. Write the file from the template; wire data via `init` + `updateWidget`.
+3. `/<id>` to launch (hot-loaded on write); relaunch `/<id>` to dismiss an
+   ambient widget.
+4. Iterate: edit the file — it hot-reloads on save (last-writer-wins, the
+   fresh definition shadows the old one). Relaunch `/<id>` to remount.
+
+## Pitfalls
+
+- No JSX and no bare imports in `.mjs` — everything comes from the `sdk`
+  parameter; `h(...)` builds elements.
+- Don't ship a modal without a close path (`Esc`/`q` returning `null`).
+- Ambient widgets must stay small (≤ ~6 rows) — the dock sits between the
+  transcript and the status bar.
+- A thrown `register()` is logged and skipped; check
+  `~/.hermes/logs/tui_gateway_crash.log` if a widget never appears.
+
+## Verification
+
+Run `/widgets-reload` — the transcript line must list the file under
+`loaded:`. Then `/<id>`: an ambient widget appears docked right, above the
+status bar, while the composer keeps accepting input; `/<id>` again removes
+it.