@prismer/runtime 2.0.8 → 2.2.63

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

@@ -0,0 +1,158 @@
+# Hermes CLI Reference
+
+> 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.
+
+Live sources when anything looks stale: `hermes --help`, `hermes <command> --help`,
+https://hermes-agent.nousresearch.com/docs/reference/cli-commands
+
+### Global Flags
+
+```
+hermes [flags] [command]        (no subcommand = interactive chat)
+
+  --version, -V             Show version
+  -z, --oneshot PROMPT      One-shot: print ONLY the final response (for scripts/pipes)
+  -m MODEL  --provider P    Model/provider override for this invocation
+  -t, --toolsets LIST       Comma-separated toolsets for this invocation
+  --resume, -r SESSION      Resume session by ID or title
+  --continue, -c [NAME]     Resume by name, or most recent session
+  --worktree, -w            Isolated git worktree mode (parallel agents)
+  --skills, -s SKILL        Preload skills (comma-separate or repeat)
+  --profile, -p NAME        Use a named profile
+  --yolo                    Skip dangerous command approval
+  --tui / --cli             Force the Ink TUI / classic REPL
+  --ignore-rules            Skip AGENTS.md/SOUL.md/memory/skill injection
+  --safe-mode               Disable ALL customizations (troubleshooting)
+  --pass-session-id         Include session ID in system prompt
+```
+
+### Chat
+
+```
+hermes chat [flags]
+  -q, --query TEXT          Single query, non-interactive
+  --image PATH              Attach a local image to a single query
+  -Q, --quiet               Suppress banner, spinner, tool previews
+  --checkpoints             Enable filesystem checkpoints (/rollback)
+  --max-turns N             Cap tool-calling iterations
+  --source TAG              Session source tag (default: cli)
+```
+(plus the global flags above)
+
+### Configuration
+
+```
+hermes setup [section]      Wizard (model|tts|terminal|gateway|tools|agent)
+hermes model                Interactive model/provider picker
+hermes fallback [add|remove|list]  Fallback provider chain
+hermes config [show|edit|get|set|unset|path|env-path|check|migrate]
+hermes login / logout       OAuth sign-in / clear stored auth
+hermes doctor [--fix]       Check dependencies and config
+hermes status [--all]       Component status
+```
+
+### Tools & Skills
+
+```
+hermes tools [list|enable NAME|disable NAME]   Per-platform toolsets (curses UI with no args)
+
+hermes skills list|browse|search QUERY|inspect ID
+hermes skills install ID    Hub identifier OR a direct https://…/SKILL.md URL
+hermes skills config        Enable/disable skills per platform
+hermes skills check|update|uninstall|publish PATH
+hermes skills tap add REPO  Add a GitHub repo as a skill source
+hermes bundles              Skill bundles (one /<name> alias loads several skills)
+```
+
+### MCP Servers
+
+```
+hermes mcp add NAME (--url or --command) | remove | list | test NAME
+hermes mcp catalog | install NAME     Curated catalog install
+hermes mcp configure NAME             Toggle tool selection
+hermes mcp serve                      Run Hermes as an MCP server
+```
+Details (transport, tool discovery, catalog): `references/native-mcp.md`.
+
+### Gateway (Messaging Platforms)
+
+```
+hermes gateway run|install|start|stop|restart|status|setup
+```
+
+20+ platforms: Telegram, Discord, Slack, WhatsApp (Baileys + Business Cloud API), iMessage (Photon — `hermes photon setup`), Signal, Email, SMS, Matrix, Mattermost, Teams, LINE, SimpleX, ntfy, Google Chat, Home Assistant, DingTalk, Feishu, WeCom, Weixin, API Server, Webhooks. Open WebUI connects via the API Server adapter. Most adapters ship under `plugins/platforms/`.
+Docs: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
+
+### Sessions
+
+```
+hermes sessions list|browse|rename ID TITLE|delete ID|export OUT|prune|stats
+```
+
+### Cron / Webhooks
+
+```
+hermes cron list|create SCHED|edit ID|pause|resume|run ID|remove|status
+    Schedules: '30m', 'every 2h', '0 9 * * *', ISO timestamp
+hermes webhook subscribe NAME|list|remove NAME|test NAME
+```
+Webhook payloads/routes: `references/webhooks.md`.
+
+### Profiles
+
+```
+hermes profile list|create NAME (--clone|--clone-all|--clone-from)|use|show|delete
+hermes profile rename A B | alias NAME | export NAME | import FILE
+hermes profile migrate-identity A B   Retry a completed rename's session/routing identity migration
+```
+
+### Credentials & Pools
+
+```
+hermes auth                 Interactive credential manager
+hermes auth add [PROVIDER]  Add OAuth or API-key credential (nous, openai-codex, qwen-oauth, …)
+hermes auth list|remove P IDX|reset PROVIDER|status
+```
+Multiple credentials per provider form a pool that rotates automatically and skips exhausted keys.
+
+### Other
+
+```
+hermes desktop / gui        Native desktop app
+hermes dashboard            Web admin panel + embedded chat (--stop / --status)
+hermes proxy                OpenAI-compatible local proxy backed by an OAuth provider
+hermes portal               Quick setup / sign in via Nous Portal
+hermes kanban <verb>        Multi-agent work-queue board
+hermes project              Named multi-folder workspaces
+hermes skin list|use|set    Switch/tweak skins (see references/themes.md)
+hermes pets <verb>          Pet mascots (see references/petdex.md)
+hermes memory setup|status|off|reset   Memory provider
+hermes secrets bitwarden|onepassword   External secret stores
+hermes moa                  Mixture-of-Agents slots
+hermes hooks / security / backup / import / checkpoints / console
+hermes logs [-f] [errors]   View agent/error logs
+hermes send                 One-off message through a gateway platform
+hermes pairing / plugins / insights / journey / computer-use
+hermes acp                  ACP server (IDE integration)
+hermes completion bash|zsh|fish
+hermes update / uninstall / claw migrate
+```
+
+Plugin- and provider-supplied subcommands (e.g. `hermes photon setup`) only appear once their plugin is installed/active.
+
+### Where to Find Things
+
+| Looking for... | Location |
+|---|---|
+| Config options | `hermes config edit` · [Configuration docs](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) |
+| Tools / toolsets | `hermes tools list` · [Tools reference](https://hermes-agent.nousresearch.com/docs/reference/tools-reference) |
+| Skills catalog | `hermes skills browse` · [Skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) |
+| Provider setup | `hermes model` · [Providers guide](https://hermes-agent.nousresearch.com/docs/integrations/providers) |
+| Env variables | `hermes config env-path` · [Env vars reference](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) |
+| Gateway logs | `~/.hermes/logs/gateway.log` (or `hermes logs`) |
+| Sessions | `hermes sessions browse` (reads state.db) |

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

@@ -0,0 +1,96 @@
+# Configuration, Toolsets & Voice
+
+> 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.
+
+Edit with `hermes config edit` or `hermes config set section.key value`.
+Full reference: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
+
+### Config Sections (most-used keys)
+
+| Section | Key options |
+|---------|-------------|
+| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length`, `aliases` |
+| `agent` | `max_turns` (90), `tool_use_enforcement`, `service_tier`, `verify_on_stop` |
+| `terminal` | `backend` (local/docker/ssh/modal/daytona/singularity), `cwd`, `timeout` (180) |
+| `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
+| `display` | `skin`, `interface` (cli/tui), `language`, `show_reasoning`, `show_cost`, `pet` |
+| `approvals` | `mode` (smart/manual/off), `timeout`, `cron_mode` |
+| `stt` | `enabled`, `provider` (local/groq/openai/mistral/elevenlabs/deepinfra) |
+| `tts` | `provider` (edge/elevenlabs/openai/minimax/mistral/neutts/gemini/piper/kittentts/deepinfra/xai) |
+| `memory` | `memory_enabled`, `user_profile_enabled`, `provider`, `write_approval` |
+| `security` | `redact_secrets`, `tirith_enabled`, `website_blocklist` |
+| `delegation` | `model`, `provider`, `max_concurrent_children`, `max_iterations` (50), `max_spawn_depth` |
+| `checkpoints` | `enabled`, `max_snapshots` (50) |
+| `curator` | `enabled`, `consolidate` (false, opt-in aux-model consolidation), `interval_hours`, `stale_after_days` |
+
+`hermes config check` reports sections missing from an older config.
+
+### Toolsets
+
+Enable/disable via `hermes tools` (interactive) or `hermes tools enable/disable NAME`.
+Full enumeration: `TOOLSETS` dict in `toolsets.py` (`_HERMES_CORE_TOOLS` is the default bundle most platforms inherit).
+
+| Toolset | What it provides |
+|---------|-----------------|
+| `web` / `search` | Web search + extraction / search-only subset |
+| `browser` | Browser automation (Browserbase, Camofox, or local Chromium) |
+| `terminal` | Shell commands and process management |
+| `file` | File read/write/search/patch |
+| `code_execution` | Sandboxed Python execution |
+| `coding` | Code-editing helpers (LSP-backed) |
+| `computer_use` | Desktop GUI control (cua-driver) |
+| `vision` | Image analysis |
+| `image_gen` | Image generation and image-to-image editing |
+| `video` / `video_gen` | Video analysis / video generation |
+| `x_search` | X (Twitter) search (X OAuth or API key) |
+| `tts` | Text-to-speech |
+| `skills` | Skill browsing and management |
+| `memory` | Persistent cross-session memory |
+| `session_search` | Search past conversations |
+| `context_engine` | Pluggable context-engine hooks |
+| `project` | Named multi-folder workspace tools |
+| `delegation` | Subagent task delegation |
+| `cronjob` | Scheduled task management |
+| `clarify` | Ask user clarifying questions |
+| `todo` | In-session task planning |
+| `kanban` | Multi-agent work-queue tools (gated to workers) |
+| `debugging` | Extra introspection tools (off by default) |
+| `safe` | Minimal low-risk toolset for locked-down sessions |
+| `spotify`, `homeassistant`, `discord`, `discord_admin`, `feishu_doc`, `feishu_drive`, `yuanbao` | Service integrations (gated on their credentials) |
+
+Tool changes take effect on `/reset` (new session) — never mid-conversation, to preserve prompt caching.
+
+## Voice
+
+### STT (Voice → Text)
+
+Voice messages from messaging platforms are auto-transcribed.
+
+```yaml
+stt:
+  enabled: true
+  provider: local   # local (faster-whisper, free) | groq | openai | mistral | elevenlabs | deepinfra
+  local:
+    model: base     # tiny, base, small, medium, large-v3
+```
+
+Auto-detect priority: local faster-whisper (`pip install faster-whisper`) → Groq (`GROQ_API_KEY`, free tier) → OpenAI (`VOICE_TOOLS_OPENAI_KEY`) → Mistral Voxtral (`MISTRAL_API_KEY`).
+
+### TTS (Text → Voice)
+
+| Provider | Env var | Free? |
+|----------|---------|-------|
+| Edge TTS (default) | None | Yes |
+| ElevenLabs | `ELEVENLABS_API_KEY` | Free tier |
+| OpenAI | `VOICE_TOOLS_OPENAI_KEY` | Paid |
+| MiniMax | `MINIMAX_API_KEY` | Paid |
+| Mistral | `MISTRAL_API_KEY` | Paid |
+| Gemini | `GOOGLE_API_KEY` | Free tier |
+| NeuTTS / Piper / KittenTTS (local) | None | Free |
+
+Voice commands: `/voice on` (voice-to-voice), `/voice tts` (always voice), `/voice off`.

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

@@ -0,0 +1,151 @@
+# Contributor Quick Reference
+
+> 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.
+
+For occasional contributors and PR authors. Full developer docs: https://hermes-agent.nousresearch.com/docs/developer-guide/
+
+### Project Layout
+
+```
+hermes-agent/
+├── run_agent.py          # AIAgent — core conversation loop
+├── model_tools.py        # Tool discovery and dispatch
+├── toolsets.py           # Toolset definitions
+├── cli.py                # Interactive CLI (HermesCLI)
+├── hermes_state.py       # SQLite session store
+├── agent/                # Prompt builder, context compression, memory, model routing, credential pooling, skill dispatch
+├── hermes_cli/           # CLI subcommands, config, setup, commands
+│   ├── commands.py       # Slash command registry (CommandDef)
+│   ├── config.py         # DEFAULT_CONFIG, env var definitions
+│   └── main.py           # CLI entry point and argparse
+├── tools/                # One file per tool
+│   └── registry.py       # Central tool registry
+├── gateway/              # Messaging gateway
+│   └── platforms/        # Platform adapters (telegram, discord, etc.)
+├── cron/                 # Job scheduler
+├── tests/                # Extensive pytest suite (run via scripts/run_tests.sh)
+└── website/              # Docusaurus docs site
+```
+
+Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
+
+### Adding a Tool
+
+Two files. Auto-discovery imports any `tools/*.py` with a top-level
+`registry.register()` call, but a tool is only *exposed* to an agent once
+its name appears in a toolset.
+
+**1. Create `tools/your_tool.py`:**
+```python
+import json, os
+from tools.registry import registry
+
+def check_requirements() -> bool:
+    return bool(os.getenv("EXAMPLE_API_KEY"))
+
+def example_tool(param: str, task_id: str = None) -> str:
+    return json.dumps({"success": True, "data": "..."})
+
+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,
+    requires_env=["EXAMPLE_API_KEY"],
+)
+```
+
+**2. Wire it into a toolset in `toolsets.py`** — add the name to
+`_HERMES_CORE_TOOLS` (every platform) or to a specific toolset.
+
+All handlers must return JSON strings. Use `get_hermes_home()` for paths,
+never hardcode `~/.hermes`. For custom/local-only tools, write a plugin in
+`~/.hermes/plugins/` instead of editing core — see the developer docs.
+
+### Adding a Slash Command
+
+1. Add `CommandDef` to `COMMAND_REGISTRY` in `hermes_cli/commands.py`
+2. Add handler in `cli.py` → `process_command()`
+3. (Optional) Add gateway handler in `gateway/run.py`
+
+All consumers (help text, autocomplete, Telegram menu, Slack mapping) derive from the central registry automatically.
+
+### Agent Loop (High Level)
+
+```
+run_conversation():
+  1. Build system prompt
+  2. Loop while iterations < max:
+     a. Call LLM (OpenAI-format messages + tool schemas)
+     b. If tool_calls → dispatch each via handle_function_call() → append results → continue
+     c. If text response → return
+  3. Context compression triggers automatically near token limit
+```
+
+### Testing
+
+Use the canonical runner — it enforces CI-parity (hermetic `env -i`, unset
+credentials, TZ=UTC, per-file subprocess isolation via
+`scripts/run_tests_parallel.py` — no xdist, worker count auto-scaled):
+
+```bash
+scripts/run_tests.sh                          # full suite
+scripts/run_tests.sh tests/tools/             # one directory
+scripts/run_tests.sh tests/tools/test_x.py    # one file
+scripts/run_tests.sh -v --tb=long             # pass-through pytest flags
+```
+
+- Tests auto-redirect `HERMES_HOME` to temp dirs — never touch real `~/.hermes/`.
+- The script probes `.venv`, then `venv`, then the shared worktree venv.
+- **Windows:** the wrapper is POSIX-only; see `references/windows-quirks.md`
+  for the direct-pytest workaround.
+
+**Cross-platform test guards:** tests using POSIX-only syscalls need a skip marker. Common ones already in the codebase:
+- Symlink creation → `@pytest.mark.skipif(sys.platform == "win32", reason="Symlinks require elevated privileges on Windows")` (see `tests/cron/test_cron_script.py`)
+- POSIX file modes (0o600, etc.) → `@pytest.mark.skipif(sys.platform.startswith("win"), reason="POSIX mode bits not enforced on Windows")` (see `tests/hermes_cli/test_auth_toctou_file_modes.py`)
+- `signal.SIGALRM` → Unix-only (per-test timeouts no longer use it directly; see the win32 timeout-method shim in `tests/conftest.py::pytest_configure`)
+- Live Winsock / Windows-specific regression tests → `@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")`
+
+**Monkeypatching `sys.platform` is not enough** when the code under test also calls `platform.system()` / `platform.release()` / `platform.mac_ver()`. Those functions re-read the real OS independently, so a test that sets `sys.platform = "linux"` on a Windows runner will still see `platform.system() == "Windows"` and route through the Windows branch. Patch all three together:
+
+```python
+monkeypatch.setattr(sys, "platform", "linux")
+monkeypatch.setattr(platform, "system", lambda: "Linux")
+monkeypatch.setattr(platform, "release", lambda: "6.8.0-generic")
+```
+
+See `tests/agent/test_prompt_builder.py::TestEnvironmentHints` for a worked example.
+
+### System prompt's execution-environment block
+
+Factual host/backend guidance (OS, `$HOME`, cwd, terminal backend, shell)
+is emitted by `agent/prompt_builder.py::build_environment_hints()`. The key
+invariant for prompt authors: with a **remote** terminal backend
+(`docker, singularity, modal, daytona, ssh, managed_modal`), host info is
+suppressed and *every* file tool runs inside the backend container — the
+prompt must never describe the host the agent can't touch.
+
+### Commit Conventions
+
+```
+type: concise subject line
+
+Optional body.
+```
+
+Types: `fix:`, `feat:`, `refactor:`, `docs:`, `chore:`
+
+### Key Rules
+
+- **Never break prompt caching** — don't change context, tools, or system prompt mid-conversation
+- **Message role alternation** — never two assistant or two user messages in a row
+- Use `get_hermes_home()` from `hermes_constants` for all paths (profile-safe)
+- Config values go in `config.yaml`, secrets go in `.env`
+- New tools need a `check_fn` so they only appear when requirements are met

package/built-in-skills/prismer-hermes-agent/references/delegate-task-concurrency-diagnosis.md

@@ -0,0 +1,47 @@
+# Diagnosing delegation concurrency and total budgets
+
+Use this as a maintainer diagnostic, not permission to spawn more workers or
+edit a tenant's Runtime configuration. First identify the deployed Hermes
+version and exact resolved settings. Defaults below describe the audited source
+1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4, not every installation.
+
+## Distinct constraints
+
+- delegation.max_concurrent_children: default 10 in tools/delegate_tool_config.py.
+  Configuration/env overrides and a floor of 1 apply.
+- A batch larger than the allowed concurrent children can be rejected.
+- Multiple delegate_task calls in one turn can be truncated by the parent.
+- One-shot execution also has a TOTAL subagent budget (default 2 in the audited
+  code). A later call can exhaust that budget despite free concurrent slots.
+- Nesting depth, leaf role, approval, provider failures and tool availability
+  can prevent delegation independently of these counts.
+- A high-cost warning above 10 is emitted once; it is not itself a throttle.
+
+## Diagnostic sequence
+
+1. Read the task's actual model tool calls, returned errors and parent/child
+   lifecycle records. Redact prompts, credentials and tenant data.
+2. Inspect effective config using the deployed version's read-only config
+   command; do not assume a value typed in a source file was loaded.
+3. Compare batch length, current active workers, total children already spawned,
+   one-shot mode/budget, nesting role/depth and approvals.
+4. Trace tools/delegate_tool_config.py, tools/delegate_tool.py and the parent
+   call limiter in the exact deployed checkout if necessary.
+5. Search bounded logs for rejection/truncation AND one-shot budget errors.
+   Absence of a log line does not prove absence of a limiter or prove model
+   self-restraint; logging may differ by version or context.
+6. Only attribute model-side under-dispatch when the actual emitted tool call
+   requests fewer tasks and the other constraints are verified, not from prose.
+
+## Running the requested work
+
+Use the exposed delegate_task tool directly when available and within all
+budgets. It is not in the audited execute_code web/file/terminal allowlist;
+never attempt to route it through code execution to evade a limit.
+Queue bounded batches or perform lenses sequentially when workers are limited.
+Do not increase concurrency, disable approval or change model automatically.
+
+Concurrency is per-parent in the inspected code; account/provider/host-wide
+limits can still apply. A background child is not evidence of a durable task.
+If durable execution is required, use Prismer's task ownership and scheduler
+contract, not a second Hermes control plane.

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

@@ -0,0 +1,215 @@
+# Desktop App Plugins — UI Panes, Commands, Widgets
+
+> 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.
+
+Write plugins for the Hermes desktop app: statusbar items, layout panes,
+command-palette commands, keybinds, routes, and themes. A plugin is a single
+plain-JavaScript ESM file the app loads at runtime — no build step, no repo
+changes. A plugin can also talk to its own Python backend namespace
+(`ctx.rest`/`ctx.socket` → `/api/plugins/<id>`); the general Python plugin
+system (`~/.hermes/plugins/`) is otherwise documented separately.
+
+There are TWO on-disk doors, same contract and hot reload:
+
+- `$HERMES_HOME/desktop-plugins/<id>/plugin.js` — standalone desktop plugin.
+  Loads enabled by default.
+- `$HERMES_HOME/plugins/<id>/desktop/plugin.js` — the desktop HALF of a
+  unified agent-plugin package: the same folder that carries the Python
+  plugin (`plugin.yaml`) and its `dashboard/plugin_api.py` backend ships its
+  desktop UI beside them, so one feature installs/uninstalls as one folder.
+  The Electron shell copies that half into `desktop-plugins/<id>/` (with a
+  `.hermes-package.json` marker) — the ONLY root the renderer loads from — so
+  the pane is app-level and does not come and go with the selected profile.
+  This half is OPT-IN: it inventories in Capabilities → Plugins but stays off
+  until the user toggles it (matching the Python half's `plugins.enabled`
+  gate). Tell the user to flip it on after installing — don't debug a
+  "plugin not appearing" report before checking that toggle.
+
+Full human reference (every export, area payloads, backend, security):
+`website/docs/developer-guide/desktop-plugin-sdk.md`.
+
+## When to Use
+
+- The user asks for a new desktop UI element (a pane, a statusbar widget, a
+  dashboard, a command) without modifying the app itself.
+- You want to surface data you compute (via gateway RPC) inside the app.
+
+## Prerequisites
+
+- The Hermes desktop app (it loads plugins; the CLI/gateway alone does not).
+- Write access to `$HERMES_HOME/desktop-plugins/` (usually
+  `~/.hermes/desktop-plugins/`).
+
+## How to Run
+
+1. Create `$HERMES_HOME/desktop-plugins/<name>/plugin.js` from
+   `templates/plugin.js` (in this skill directory) — that's
+   `~/.hermes/...` by default, or `~/.hermes/profiles/<profile>/...` under a
+   named profile. Keep `<name>` equal to the plugin `id`.
+2. The desktop app watches that directory: the plugin loads within a few
+   seconds of the file landing, and every later save hot-reloads it in
+   place. No reload step. (Fallback if it doesn't appear: ⌘K →
+   **Reload desktop plugins**.)
+3. If loading fails the app shows a toast naming the error — fix the file
+   and save again.
+
+## Quick Reference
+
+The ONLY import surface is `@hermes/plugin-sdk` (plus `react` /
+`react/jsx-runtime`, which resolve to the app's own React — write UI with
+`jsx()` calls, not JSX syntax; the file is not compiled).
+
+- `host.state.*` — readonly reactive atoms: `activeSessionId`, `busy`,
+  `awaitingResponse`, `busyBySession`, `cwd`, `gateway` (socket state, not
+  turn-busy), `model`, `profile`, `viewport`, plus the tile-aware focused
+  session atoms: `focusedSessionId` (runtime id — key for `session.*` RPC),
+  `focusedStoredSessionId` (durable id — navigation / list matching),
+  `focusedSessionProfile` (owner profile of the focused chat — prefer over
+  `profile` for per-bot/profile readouts; `profile` is the gateway socket's
+  home, which does not move with tab focus), and
+  `focusedUsage` (live streamed `UsageStats` of the focused session, no RPC
+  needed). `busy` is true while the focused chat is working after a send
+  (thinking and streaming). `awaitingResponse` is true until the first
+  assistant payload. `busyBySession` maps runtime session id → mid-turn,
+  for rosters that watch every session. Prefer the focused atoms for any
+  readout that should follow the user between tiles. Read with `.get()`
+  in handlers,
+  `useValue(atom)` in components.
+- `host.request(method, params)` — gateway JSON-RPC (sessions, config,
+  skills, cron — everything the app uses).
+- `host.onEvent(type, fn)` — live gateway events (`'*'` for all). Returns a
+  disposer.
+- `host.notify({ kind, message })`, `host.navigate(path)`, `host.logs(...)`,
+  `host.status()`, `haptic('tap')`.
+- `ctx.register({ id, area, order?, render?, data? })` — contribute UI.
+  Key areas: `'statusBar.right'`/`'statusBar.left'` (chips),
+  `'panes'` (layout zones — set `title` and
+  `data: { placement, dock?, width?, height? }`; the pane auto-joins a
+  matching zone), `PALETTE_AREA` (⌘K commands), `KEYBINDS_AREA` (rebindable
+  actions), `THEMES_AREA` (`data` is a full `DesktopTheme`).
+- THEMES: registering one only lists it in the picker. Select it with
+  `useTheme().setTheme(name)` from a component, or `requestTheme(name)` from a
+  callback with no component around it (a gateway event, a socket handler).
+  `requestTheme` returns `false` for a name that doesn't resolve and leaves the
+  appearance alone, so use it as the availability check instead of coercing the
+  user back to the default skin.
+- Pane placement: `placement: 'left'|'right'|'bottom'|'main'` is the
+  semantic role — the pane stacks (tabs) with existing panes of that role.
+  To land on a specific EDGE instead, add `dock: { pane, pos }` — the same
+  gesture as dragging onto a pane's drop chip. `pane` is any pane id
+  (`workspace` is the main thread; also `sessions`, `terminal`, `files`,
+  `review`, `logs`), `pos` is `'top'|'bottom'|'left'|'right'|'center'`.
+  E.g. "below the conversation" = `dock: { pane: 'workspace', pos: 'bottom' }`
+  — declare a `height` (e.g. `'200px'`) so it doesn't take half the zone.
+- Full PAGES: register `area: ROUTES_AREA` with `data: { path: '/my-page' }`
+  and a `render` — the page mounts in the workspace (main) pane like any
+  built-in view. Make it reachable with a sidebar nav row:
+  `ctx.register({ id: 'nav', area: SIDEBAR_NAV_AREA, data: { path: '/my-page', label: 'My Page', codicon: 'project' } })`
+  (renders below Artifacts, lights up at the route) — and/or a
+  `PALETTE_AREA` command calling `host.navigate('/my-page')`.
+- TRANSCRIPT directives: register `area: TRANSCRIPT_DIRECTIVE_AREA` with
+  `data: { name: 'task', render: ({ attrs, streaming }) => jsx(...) }` and
+  the assistant can render your component inline in a chat message by
+  emitting `::task{id="BB-12"}` alone on its own line. Attrs are untrusted
+  `key="value"` strings — validate them. Unclaimed/malformed directives fall
+  back to plain text; core's own `::preview{file="…"}` is the reference.
+  After registering one, TELL the model it exists (a bundled skill or the
+  user's instructions) — it won't discover the name on its own.
+- `ctx.storage.get/set/remove` — persistence namespaced to your plugin.
+- `ctx.os` — the curated OS door, attributed to your plugin:
+  `ctx.os.notify({ title, body?, silent?, icon?, activate?, onActivate?, actions? })`
+  posts a native OS notification. Fires only while the user is away from Hermes
+  (use `host.notify` for the in-app toast); gated by Settings ▸ Notifications ▸
+  "Plugin notifications" and throttled per plugin — reserve it for genuinely
+  notable events. `activate` accepts a plugin deep link
+  (`hermes://index-network/intent/1`), a hash path (`/index-network/intent/1`),
+  or `{ path, params }` — same resolver as OS deep links. Action buttons may
+  set their own `activate` or an `onAction`
+  callback (renderer-only; only the action id crosses IPC).
+  `ctx.os.openExternal(url)`, `ctx.os.revealPath(path)`, and
+  `ctx.os.writeClipboard(text)` resolve `false` (never throw) when the
+  capability isn't available.
+- `ctx.i18n.register({ en, ja, ... })` — ship your OWN locale bundles, scoped
+  to your plugin (never edit core `en.ts`). Values are literal strings or
+  interpolator functions; nested trees are addressed by dot-path. Read them
+  reactively in components with `usePluginI18n(id)` returning `t('key', ...args)`
+  (re-renders on a locale switch), or via `ctx.i18n.t` in handlers/stores.
+  Resolution follows the app's active locale, then your `en`, then the raw key.
+- Data: `useQuery`/`useMutation`/`useQueryClient`/`queryClient` (the app's ONE
+  React Query client — cache, dedupe, `refetchInterval`, invalidate like core;
+  never hand-roll a poll loop), plus `atom`/`computed` for plugin-local state.
+- Backend: if the plugin ships a Python `plugin_api.py` (under
+  `~/.hermes/plugins/<id>/dashboard/`, manifest `"api": "plugin_api.py"`), reach
+  it with `ctx.rest('/path', { method?, body?, timeoutMs? })` and its live twin
+  `ctx.socket('/events', onMessage)` — both scoped to `/api/plugins/<id>` by
+  construction (traversal rejected). `ctx.socket` is a **no-op on OAuth
+  remotes**, so always keep a polling fallback. The Python backend is imported
+  only when the plugin is in `plugins.enabled` in `config.yaml` (separate from
+  the in-app enable toggle). For gateway-wide data use `host.request` /
+  `host.onEvent` instead.
+- `Contribute` (mount-scoped): render `jsx(Contribute, { area, id, children })`
+  inside a component so page-owned chrome (e.g. a titlebar control in
+  `TITLEBAR_AREAS.center`) leaves when the page unmounts — `ctx.register` is for
+  permanent contributions.
+- `defaultEnabled: false` on the default export ships an opt-in plugin: it
+  inventories in Settings → Plugins, off until the user flips it on.
+- Users manage plugins in Settings → Plugins (enable/disable live, reveal
+  folder). A disabled plugin stays disabled across restarts — don't fight
+  it; the user turned you off.
+- UI: the app's design language, importable directly — `Button`, `Input`,
+  `Textarea`, `Select*`, `Switch`, `Checkbox`, `SegmentedControl`, `Tabs*`,
+  `Dialog*`, `ConfirmDialog`, `DropdownMenu*`, `ContextMenu*`, `Popover*`,
+  `Tip`/`Tooltip*`, `Badge`, `Kbd`/`KbdGroup`, `SearchField`, `ScrollArea`,
+  `Separator`, `Skeleton`, `GlyphSpinner`, `EmptyState`, `ErrorState`,
+  `CopyButton`, `StatusDot`, `LogView`, `Codicon`, `DecodeText`, plus `cn`
+  and `icons.*`. Prefer these over hand-rolled elements so the plugin looks
+  native; style with theme vars, never hardcoded colors.
+
+## Procedure
+
+1. Pick a short kebab-case `id`; the folder name must match.
+2. Start from `templates/plugin.js`; keep the default export shape
+   (`{ id, name, register(ctx) }`).
+3. For a pane, register `area: 'panes'` with a `placement` hint and a
+   `render` returning your component — the app places it into a sensible
+   zone automatically; the user can drag it anywhere afterwards.
+4. Fetch data with `host.request` and/or subscribe with `host.onEvent`;
+   never poll faster than a few seconds.
+5. Write the file with your file tools, then ask the user to run
+   **Reload desktop plugins** from ⌘K.
+
+## Pitfalls
+
+- NEVER hardcode colors or backgrounds (`#000`, `black`, `rgb(...)`). Panes
+  already sit on the app's editor background — leave the background alone
+  and use theme variables for everything else: `var(--ui-text-secondary)`,
+  `var(--ui-text-quaternary)`, `var(--ui-stroke-secondary)`,
+  `var(--ui-accent)`. For canvas drawing, resolve them once with
+  `getComputedStyle(canvas).getPropertyValue('--ui-accent')`.
+- Reference only what you imported — a component you forgot to import
+  (e.g. `StatusDot`) is a ReferenceError at render. Double-check every
+  identifier in your `jsx()` calls appears in the import line.
+- Canvas panes MUST track their container with a `ResizeObserver` and
+  re-size the canvas (width/height attributes, not just CSS) — panes resize
+  constantly (sash drags, layout switches); a mount-time-only size leaves
+  blank space or blurry scaling.
+- JSX syntax will not parse — the file loads uncompiled. Use
+  `jsx('div', { children: ... })` from `react/jsx-runtime`.
+- Do not import anything except `@hermes/plugin-sdk`, `react`, and
+  `react/jsx-runtime`; other specifiers fail to resolve.
+- Handlers must read state imperatively (`$atom.get()`), never from render
+  closures — rapid events will otherwise see stale values.
+- Keep components small; subscribe (`useValue`) only in the leaf that
+  renders the value.
+
+## Verification
+
+- The plugin's UI appears after **Reload desktop plugins**.
+- No error toast ("Plugin <name> failed to load") appears; if it does, the
+  message names the failure — fix and reload.
+- For panes: the new zone is visible and draggable like any core pane.