NousResearch/hermes-agent

Himalaya skill CLI syntax fixes and docs updates

Cluster 48835 · skills. Data as of 2026-10-25 11:21 UTC

2 open items. Fix merged in #49914 on 21 Jun 2026. Check it covers your case.

open issue

open PR

items grouped

Known?: Yes. 5 related items grouped here, 1 issue already closed.
Fix event: A fix was merged to main in PR #49914. Check it covers your case. No release data is tracked.
Tracker: The maintainers' tracker marks this unresolved. That is separate from the fix event.
Still open: 1 issue and 1 PR.

Next step: read #49914, then check whether your report is the one still open.

Read #49914 Pick up a Lab task

These issues and PRs address incorrect or outdated CLI flag syntax in the Himalaya skill, targeting v1.2.0 compatibility. A broader docs salvage effort is also included alongside the Himalaya-specific corrections.

Open issues1

Issue#58239bug: himalaya skill has incorrect flag command syntax for v1.2.0

Open PRs1

PR#58354fix(skills/himalaya): correct flag add/remove syntax for v1.2.0

Fixes on record

Merged to main. A stamp counts the issues a fix is linked to.

#49914 docs: salvage 9 validated docs-update PRs (cluster)

merged to main

files: CONTRIBUTING.md, README.md, README.zh-CN.md, scripts/release.py, skills/email/himalaya/SKILL.md, website/docs/guides/use-mcp-with-hermes.md, website/docs/reference/optional-skills-catalog.md, website/docs/user-guide/messaging/homeassistant.md, website/docs/user-guide/profile-distributions.md, website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md, website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md, website/docs/user-guide/skills/bundled/email/email-himalaya.md, website/docs/user-guide/skills/bundled/github/github-github-auth.md, website/docs/user-guide/skills/bundled/github/github-github-code-review.md, website/docs/user-guide/skills/bundled/github/github-github-issues.md, website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md, website/docs/user-guide/skills/bundled/github/github-github-repo-management.md, website/docs/user-guide/skills/bundled/media/media-gif-search.md, website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md, website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md (+26 more)

Show the diff

CONTRIBUTING.md

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

README.md

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

README.zh-CN.md

@@ -39,7 +39,11 @@ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
 
 > **Android / Termux：** 已测试的手动安装路径请参考 [Termux 指南](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。在 Termux 上，Hermes 会安装精选的 `.[termux]` 扩展，因为完整的 `.[all]` 扩展会拉取 Android 不兼容的语音依赖。
 >
-> **Windows：** 原生 Windows 不受支持。请安装 [WSL2](https://learn.microsoft.com/zh-cn/windows/wsl/install) 并运行上述命令。
+> **Windows：** 在 PowerShell 中运行：
+> ```powershell
+> iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+> ```
+> 安装完成后，可能需要重启终端，然后运行 `hermes` 开始对话。
 
 安装后：

scripts/release.py

@@ -113,6 +113,12 @@
     "[email protected]": "synapsesx",
     "[email protected]": "itsflownium",
     "[email protected]": "dirtyren",
+    "[email protected]": "yapsrubricsz0",
+    "[redacted:email]": "Railway9784",
+    "[email protected]": "graphanov",
+    "[email protected]": "Antimatter543",
+    "[redacted:email]": "mkslzk",
+    "[email protected]": "baolingao",
     "[email protected]": "hakanpak",
     "[redacted:email]": "lgalabru",
     "[email protected]": "johnjacobkenny",

skills/email/himalaya/SKILL.md

@@ -213,16 +213,16 @@ Note: `himalaya message write` without piped input opens `$EDITOR`. This works w
 
 ### Move/Copy Emails
 
-Move to folder:
+Move to folder (target folder comes first, then the message ID):
 
 ```bash
-himalaya message move 42 "Archive"
+himalaya message move "Archive" 42
 ```
 
-Copy to folder:
+Copy to folder (target folder comes first, then the message ID):
 
 ```bash
-himalaya message copy 42 "Important"
+himalaya message copy "Important" 42
 ```
 
 ### Delete an Email
@@ -270,7 +270,7 @@ himalaya attachment download 42
 Save to specific directory:
 
 ```bash
-himalaya attachment download 42 --dir ~/Downloads
+himalaya attachment download 42 --downloads-dir ~/Downloads
 ```
 
 ## Output Formats

website/docs/guides/use-mcp-with-hermes.md

@@ -264,7 +264,58 @@ Review the project structure and identify where configuration lives.
 Check the local git state and summarize what changed recently.
 ```
 
-### Pattern 2: GitHub triage assistant
+### Pattern 2: repo-native work record with Open Scaffold
+
+Use [Open Scaffold](https://github.com/graphanov/open-scaffold) when you want Hermes to read a repository's durable AI-work record: mission, plans, evidence notes, handoff packets, and review/gate results. Hermes remains the agent; Open Scaffold remains the repo-local record.
+
+Add the server for one scaffolded repository:
+
+```bash
+hermes mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /absolute/path/to/repo
+hermes mcp test open_scaffold
+```
+
+Then keep the exposed surface read-oriented. Choose `select` in the `hermes mcp add` prompt, or edit `config.yaml` afterward:
+
+```yaml
+mcp_servers:
+  open_scaffold:
+    command: "npx"
+    args: ["-y", "open-scaffold@latest", "mcp", "serve", "--repo", "/absolute/path/to/repo"]
+    tools:
+      include:
+        - list_plans
+        - get_plan
+        - get_mission
+        - list_evidence
+        - get_evidence
+        - get_status
+        - search_plans
+        - list_amendments
+        - get_handoff
+        - analyze_loop
+        - gate_loop
+      prompts: false
+```
+
+Good prompts:
+
+```text
+Use the Open Scaffold MCP tools to compile the current handoff packet and tell me the next legal action.
+```
+
+```text
+Inspect the active plans and evidence notes, then say whether this repo is ready for human review or needs another attempt.
+```
+
+Boundary notes:
+
+- Open Scaffold MCP is local-first and read-only by default.
+- Its write tools require the server to be started with `--allow-write`; do not enable that until you explicitly want Hermes to mutate `.osc` files.
+- Open Scaffold records and gates work; it does not authorize Hermes to merge, publish, deploy, or spawn runtimes.
+- Pin `open-scaffold@<version>` instead of `@latest` if you need reproducible tool schemas.
+
+### Pattern 3: GitHub triage assistant
 
 ```yaml
 mcp_servers:
@@ -289,7 +340,7 @@ List open issues about MCP, cluster them by theme, and draft a high-quality issu
 Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.
 ```
 
-### Pattern 3: internal API assistant
+### Pattern 4: internal API assistant
 
 ```yaml
 mcp_servers:

website/docs/reference/optional-skills-catalog.md

@@ -59,7 +59,7 @@ hermes skills uninstall <skill-name>
 | [**baoyu-comic**](/docs/user-guide/skills/optional/creative/creative-baoyu-comic) | Knowledge comics (知识漫画): educational, biography, tutorial. |
 | [**blender-mcp**](/docs/user-guide/skills/optional/creative/creative-blender-mcp) | Control Blender directly from Hermes via socket connection to the blender-mcp addon. Create 3D objects, materials, animations, and run arbitrary Blender Python (bpy) code. Use when user wants to create or modify anything in Blender. |
 | [**concept-diagrams**](/docs/user-guide/skills/optional/creative/creative-concept-diagrams) | Generate flat, minimal light/dark-aware SVG diagrams as standalone HTML files, using a unified educational visual language with 9 semantic color ramps, sentence-case typography, and automatic dark mode. Best suited for educational and no... |
-| [**ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate project ideas via creative constraints. |
+| [**creative-ideation**](/docs/user-guide/skills/optional/creative/creative-creative-ideation) | Generate ideas via named methods from creative practice. |
 | [**hyperframes**](/docs/user-guide/skills/optional/creative/creative-hyperframes) | Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants... |
 | [**kanban-video-orchestrator**](/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator) | Plan, set up, and monitor a multi-agent video production pipeline backed by Hermes Kanban. Use when the user wants to make ANY video — narrative film, product/marketing, music video, explainer, ASCII/terminal art, abstract/generative loo... |
 | [**meme-generation**](/docs/user-guide/skills/optional/creative/creative-meme-generation) | Generate real meme images by picking a template and overlaying text with Pillow. Produces actual .png meme files. |

website/docs/user-guide/messaging/homeassistant.md

@@ -259,12 +259,6 @@ from `config.yaml`. Double-check the file lives under the active Hermes profile
 home and that there's no stray quoting around the URL/token. Restart the gateway
 after editing — env changes are only applied on process start.
 
-**`conversation entity not found` / agent never replies.**
-Home Assistant's conversation API requires a configured *Assist* conversation
-agent. In HA, open **Settings → Voice assistants → Add assistant** and note the
-resulting entity id (looks like `conversation.home_assistant` or
-`conversation.openai_<name>`). Set that entity id in the adapter's
-`conversation_entity` setting; the default may not exist on your instance.
 
 **REST auth failing (`401 Unauthorized`).**
 The token must be a *Long-Lived Access Token* created from your HA user profile

website/docs/user-guide/profile-distributions.md

@@ -69,6 +69,10 @@ Not a fit:
 - **You want to share API keys alongside the agent.** `auth.json` and `.env` are deliberately excluded from distributions. Each installer brings their own credentials.
 - **You want to share memories / sessions / conversation history.** Those are user data, not distribution content. Never shipped.
 
+:::caution
+**Hermes does not control git.** The file exclusions described on this page are applied by the **installer** when someone runs `hermes profile install` or `hermes profile update`. They are **not** applied when you run `git add` or `git commit`.
+:::
+
 ## The lifecycle: author to installer to update
 
 Below is the full end-to-end flow. Pick the side you care about.
@@ -116,7 +120,73 @@ env_requires:
 
 That's the whole manifest. Every field except `name` has a sensible default.
 
-### Step 3 — Push to a git repo
+### Step 3 — Create a `.gitignore` before the first commit
+
+:::warning
+Do this **before** running `git init` or `git add`. If you have already chatted with the profile, run setup, or otherwise used it, the directory now contains files you must not ship: `.env`, `auth.json`, `memories/`, `sessions/`, `state.db*`, `logs/`, and more. 
+:::
+
+Create `~/.hermes/profiles/research-bot/.gitignore` with at minimum:
+
+```gitignore
+# Credentials & secrets — NEVER commit
+auth.json
+.env
+.env.EXAMPLE    # generated by install, not authorship domain
+
+# Runtime databases & state
+state.db
+state.db-shm
+state.db-wal
+hermes_state.db
+response_store.db
+response_store.db-shm
+response_store.db-wal
+gateway.pid
+gateway_state.json
+processes.json
+auth.lock
+active_profile
+.update_check
+
+# User data — NEVER commit
+memories/
+sessions/
+logs/
+plans/
+workspace/
+home/
+
+# Caches & generated artifacts
+image_cache/
+audio_cache/
+document_cache/
+browser_screenshots/
+cache/
+
+# Infrastructure (should not be in profile dir, but safe to exclude)
+hermes-agent/
+.worktrees/
+profiles/
+bin/
+node_modules/
+
+# User customization namespace — your local overrides
+local/
+
+# Checkpoints & backups (can be huge)
+checkpoints/
+sandboxes/
+backups/
+
+# Logs
+errors.log
+.hermes_history
+```
+
+This mirrors the [hard-excluded paths](#whats-not-in-a-distribution-ever) that the installer strips on its end. Anything else you want to keep out of the repo (scratch files, large assets, local-only skills) should also go in here.
+
+### Step 4 — Push to a git repo
 
 ```bash
 cd ~/.hermes/profiles/research-bot
@@ -131,10 +201,10 @@ git push -u origin main --tags
 The repo is now a distribution. Anyone with access can install it.
 
 :::note
-The git repo contains **everything in the profile directory except things already excluded from distributions**: `auth.json`, `.env`, `memories/`, `sessions/`, `state.db*`, `logs/`, `workspace/`, `*_cache/`, `local/`. Those stay on your machine. You can also add a `.gitignore` if you want to exclude additional paths.
+The installer will additionally strip the [hard-excluded paths](#whats-not-in-a-distribution-ever) even if an author somehow ships them — but that only protects installers, not the author. 
 :::
 
-### Step 4 — Tag versioned releases
+### Step 5 — Tag versioned releases
 
 Every time the agent reaches a stable point, bump the version and tag:
 
@@ -154,6 +224,7 @@ A complete authored distribution:
 
 ```
 research-bot/
+├── .gitignore                   # excludes secrets & user data (see Step 3)
 ├── distribution.yaml            # required
 ├── SOUL.md                      # strongly recommended
 ├── config.yaml                  # model, provider, tool defaults
@@ -204,7 +275,7 @@ What happens:
 2. Reads `distribution.yaml`, shows you the manifest (name, version, description, author, required env vars).
 3. Checks each required env var against your shell environment and the target profile's existing `.env`. Marks each as `✓ set` or `needs setting` so you know exactly what to configure.
 4. Asks for confirmation. Pass `-y` / `--yes` to skip.
-5. Copies distribution-owned files into `~/.hermes/profiles/research-bot/` (or wherever the manifest's `name` resolves).
+5. Copies distribution-owned files into `~/.hermes/profiles/research-bot/` (or wherever the manifest's `name` resolves). The [hard-excluded paths](#whats-not-in-a-distribution-ever) are stripped during this copy, even if the author accidentally left them in the repo.
 6. Writes `.env.EXAMPLE` with the required keys commented out — copy to `.env` and fill in.
 7. With `--alias`, creates a wrapper so you can run `research-bot chat` directly.
 
@@ -351,9 +422,10 @@ So you never accidentally delete an agent without knowing where it came from or
 You built a research assistant on your laptop. You want the same agent on your workstation.
 
 ```bash
-# Laptop
+# Laptop — create .gitignore first (see "For authors" Step 3), then:
 cd ~/.hermes/profiles/research-bot
-git init && git add . && git commit -m "initial"
+git init && git add . && git status   # confirm no secrets staged
+git commit -m "initial"
 git remote add origin [redacted:email]:you/research-bot.git
 git push -u origin main
 
@@ -369,10 +441,11 @@ Any iteration on the laptop (`git commit && push`) pulls onto the workstation wi
 Your engineering team wants a shared PR-review bot with a specific SOUL, specific skills, and a cron that runs every PR through it.
 
 ```bash
-# Engineering lead
+# Engineering lead — create .gitignore first (see "For authors" Step 3), then:
 cd ~/.hermes/profiles/pr-reviewer
 # ... build and tune ...
-git init && git add . && git commit -m "v1.0 PR reviewer"
+git init && git add . && git status   # confirm no secrets staged
+git commit -m "v1.0 PR reviewer"
 git tag v1.0.0
 git push -u origin main --tags    # push to your company's internal Git host
 
@@ -389,10 +462,11 @@ When the lead ships v1.1 (better SOUL, new skill), engineers run `hermes profile
 You built something novel — maybe a "Polymarket trader" or an "academic paper summarizer" or a "Minecraft server ops assistant." You want to share it.
 
 ```bash
-# You
+# You — create .gitignore first (see "For authors" Step 3), then:
 cd ~/.hermes/profiles/polymarket-trader
 # Write a solid README.md at the repo root — GitHub shows it on the repo page
-git init && git add . && git commit -m "v1.0"
+git init && git add . && git status   # confirm no secrets staged
+git commit -m "v1.0"
 git tag v1.0.0
 # Publish to a public GitHub repo
 git remote add origin https://github.com/you/hermes-polymarket-trader.git
@@ -437,7 +511,7 @@ Your customers install via a single command; the install preview tells them exac
 You're the ops lead. You want a temporary agent that diagnoses a production incident — a canned SOUL with the right tools and MCP connections — and runs on three on-call engineers' laptops for the next week.
 
 ```bash
-# You
+# You — create .gitignore first (see "For authors" Step 3), then:
 # Build the profile, commit, push a private repo
 git push -u origin main
 
@@ -536,7 +610,11 @@ The installer hard-excludes these paths even if an author accidentally ships the
 - `*_cache/` — image / audio / document caches
 - `local/` — user-reserved customization namespace
 
-When you clone a distribution, these simply aren't there. When you update, they stay put. If you installed the same distribution on five machines, you have five isolated sets of this data — one per machine.
+When you clone a distribution as an installer, these simply aren't copied into your profile directory. When you update, your copies stay put. If you installed the same distribution on five machines, you have five isolated sets of this data — one per machine.
+
+:::caution
+This exclusion runs at **install / update time on the installer's machine**. It does **not** prevent an author from commiting sensitive/unnecessary files. Authors must use a [`.gitignore`](#step-3--create-a-gitignore-before-the-first-commit) to keep secrets out of the repo.
+:::
 
 ## Security and trust

website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md

@@ -360,7 +360,7 @@ The registry of record is `hermes_cli/commands.py` — every consumer
 
 ```
 ~/.hermes/config.yaml       Main configuration
-~/.hermes/.env              API keys and secrets
+~/.hermes/.env              API keys and secrets (under $HERMES_HOME if set)
 $HERMES_HOME/skills/        Installed skills
 ~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true)
 ~/.hermes/state.db          Canonical session store (SQLite + FTS5)
@@ -377,7 +377,7 @@ Edit with `hermes config edit` or `hermes config set section.key value`.
 
 | Section | Key options |
 |---------|-------------|
-| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` |
+| `model` | `default`, `provider`, `base_url`, `api_key`, `context_length` (explicit override; clear to `""` for auto-detect from server `/v1/models`) |
 | `agent` | `max_turns` (90), `tool_use_enforcement` |
 | `terminal` | `backend` (local/docker/ssh/modal), `cwd`, `timeout` (180) |
 | `compression` | `enabled`, `threshold` (0.50), `target_ratio` (0.20) |
@@ -875,6 +875,22 @@ hermes config set auxiliary.vision.model <model_name>
 ```
 
 ---
+### Context window shows wrong size
+
+If Hermes reports a smaller context window than your local model supports
+(e.g., 128k when llama-server has `-c 262144`):
+
+**Check if `model.context_length` is explicitly set.** Hermes uses a
+multi-source resolution chain (highest priority first):
+
+1. `model.context_length` in config.yaml — **blocks auto-detection if set**
+2. Custom provider per-model setting
+3. Persistent cache (survives restarts)
+4. `/v1/models` endpoint from your server — auto-detected when nothing
+   above overrides it
+
+**Fix:** Clear the override so auto-detection falls through:
+
 
 ## Where to Find Things
 
@@ -927,7 +943,7 @@ hermes-agent/
 ```
 <!-- ascii-guard-ignore-end -->
 
-Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys).
+Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
 
 ### Adding a Tool (3 files)

website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md

@@ -21,7 +21,7 @@ Control a running TouchDesigner instance via twozero MCP — create operators, s
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `TouchDesigner`, `MCP`, `twozero`, `creative-coding`, `real-time-visuals`, `generative-art`, `audio-reactive`, `VJ`, `installation`, `GLSL` |
-| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
+| Related skills | `native-mcp`, [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), `hermes-video` |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/bundled/email/email-himalaya.md

@@ -32,6 +32,11 @@ The following is the complete skill definition that Hermes loads when this skill
 
 Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.
 
+This skill is separate from the Hermes Email gateway adapter. The gateway
+adapter lets people email the agent and uses Hermes' built-in IMAP/SMTP
+adapter; this skill lets the agent operate a mailbox from terminal tools and
+requires the external `himalaya` CLI.
+
 ## References
 
 - `references/configuration.md` (config file setup + IMAP/SMTP authentication)
@@ -226,13 +231,13 @@ Note: `himalaya message write` without piped input opens `$EDITOR`. This works w
 Move to folder:
 
 ```bash
-himalaya message move 42 "Archive"
+himalaya message move "Archive" 42
 ```
 
 Copy to folder:
 
 ```bash
-himalaya message copy 42 "Important"
+himalaya message copy "Important" 42
 ```
 
 ### Delete an Email
@@ -280,7 +285,7 @@ himalaya attachment download 42
 Save to specific directory:
 
 ```bash
-himalaya attachment download 42 --dir ~/Downloads
+himalaya attachment download 42 --downloads-dir ~/Downloads
 ```
 
 ## Output Formats

website/docs/user-guide/skills/bundled/github/github-github-auth.md

@@ -238,8 +238,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
   echo "AUTH_METHOD=gh"
 elif [ -n "$GITHUB_TOKEN" ]; then
   echo "AUTH_METHOD=curl"
-elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-  export GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+elif _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+  export GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
   echo "AUTH_METHOD=curl"
 elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
   export GITHUB_TOKEN=[redacted:secret-assignment] "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')

website/docs/user-guide/skills/bundled/github/github-github-code-review.md

@@ -46,8 +46,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=[redacted:secret-assignment] "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

website/docs/user-guide/skills/bundled/github/github-github-issues.md

@@ -46,8 +46,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=[redacted:secret-assignment] "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

website/docs/user-guide/skills/bundled/github/github-github-pr-workflow.md

@@ -48,8 +48,8 @@ else
   AUTH="git"
   # Ensure we have a token for API calls
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=[redacted:secret-assignment] "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

website/docs/user-guide/skills/bundled/github/github-github-repo-management.md

@@ -45,8 +45,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=[redacted:secret-assignment] "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=[redacted:secret-assignment] "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

website/docs/user-guide/skills/bundled/media/media-gif-search.md

@@ -38,7 +38,7 @@ Useful for finding reaction GIFs, creating visual content, and sending GIFs in c
 
 ## Setup
 
-Set your Tenor API key in your environment (add to `~/.hermes/.env`):
+Set your Tenor API key in your environment (add to `${HERMES_HOME:-~/.hermes}/.env`):
 
 ```bash
 TENOR_API_KEY=[redacted:secret-assignment]

website/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian.md

@@ -32,7 +32,7 @@ Use this skill for filesystem-first Obsidian vault work: reading notes, listing
 
 Use a known or resolved vault path before calling file tools.
 
-The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
+The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `${HERMES_HOME:-~/.hermes}/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
 
 File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.

website/docs/user-guide/skills/bundled/productivity/productivity-airtable.md

@@ -40,7 +40,7 @@ Work with Airtable's REST API directly via `curl` using the `terminal` tool. No
    - `data.records:write` — create / update / delete rows
    - `schema.bases:read` — list bases and tables
 3. **Important:** in the same token UI, add each base you want to access to the token's **Access** list. PATs are scoped per-base — a valid token on the wrong base returns `403`.
-4. Store the token in `~/.hermes/.env` (or via `hermes setup`):
+4. Store the token in `${HERMES_HOME:-~/.hermes}/.env` (or via `hermes setup`):
    ```
    AIRTABLE_API_KEY=[redacted:secret-assignment]
    ```
@@ -236,7 +236,7 @@ done
 ## Important Notes for Hermes
 
 - **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow).
-- **`AIRTABLE_API_KEY` flows from `~/.hermes/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
+- **`AIRTABLE_API_KEY` flows from `${HERMES_HOME:-~/.hermes}/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
 - **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL.
 - **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection.
 - **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent.

website/docs/user-guide/skills/bundled/productivity/productivity-notion.md

@@ -41,7 +41,7 @@ Talk to Notion two ways. Same integration token works for both — pick by what'
 
 1. Create an integration at https://notion.so/my-integrations
 2. Copy the API key (starts with `ntn_` or `secret_`)
-3. Store in `~/.hermes/.env`:
+3. Store in `${HERMES_HOME:-~/.hermes}/.env`:
    ```
    NOTION_API_KEY=[redacted:secret-assignment]
    ```
@@ -65,7 +65,7 @@ export NOTION_API_TOKEN=[redacted:secret-assignment]      # ntn reads NOTION_API_TOKEN
 export NOTION_KEYRING=0                       # don't try to use the OS keychain
 ```
 
-Add those exports to your shell profile (or to `~/.hermes/.env`) so every session inherits them.
+Add those exports to your shell profile (or to `${HERMES_HOME:-~/.hermes}/.env`) so every session inherits them.
 
 ### 3. Choose path at runtime

website/docs/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md

@@ -50,7 +50,7 @@ Multilingual trigger examples (not exhaustive):
 
 ## Prerequisites
 
-Before using the pipeline, verify these are set in `~/.hermes/.env`:
+Before using the pipeline, verify these are set in `${HERMES_HOME:-~/.hermes}/.env`:
 
 ```bash
 MSGRAPH_TENANT_ID=...

website/docs/user-guide/skills/bundled/research/research-llm-wiki.md

@@ -52,7 +52,7 @@ Use this skill when the user:
 
 ## Wiki Location
 
-**Location:** Set via `WIKI_PATH` environment variable (e.g. in `~/.hermes/.env`).
+**Location:** Set via `WIKI_PATH` environment variable (e.g. in `${HERMES_HOME:-~/.hermes}/.env`).
 
 If unset, defaults to `~/wiki`.

website/docs/user-guide/skills/bundled/research/research-research-paper-writing.md

@@ -22,7 +22,7 @@ Write ML papers for NeurIPS/ICML/ICLR: design→submit.
 | Dependencies | `semanticscholar`, `arxiv`, `habanero`, `requests`, `scipy`, `numpy`, `matplotlib`, `SciencePlots` |
 | Platforms | linux, macos |
 | Tags | `Research`, `Paper Writing`, `Experiments`, `ML`, `AI`, `NeurIPS`, `ICML`, `ICLR`, `ACL`, `AAAI`, `COLM`, `LaTeX`, `Citations`, `Statistical Analysis` |
-| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/bundled/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
+| Related skills | [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv), `ml-paper-writing`, [`subagent-driven-development`](/docs/user-guide/skills/optional/software-development/software-development-subagent-driven-development), [`plan`](/docs/user-guide/skills/bundled/software-development/software-development-plan) |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger.md

@@ -21,7 +21,7 @@ Debug Node.js via --inspect + Chrome DevTools Protocol CLI.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `debugging`, `nodejs`, `node-inspect`, `cdp`, `breakpoints`, `ui-tui` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
+| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`python-debugpy`](/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy), `debugging-hermes-tui-commands` |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/bundled/software-development/software-development-python-debugpy.md

@@ -21,7 +21,7 @@ Debug Python: pdb REPL + debugpy remote (DAP).
 | License | MIT |
 | Platforms | linux, macos |
 | Tags | `debugging`, `python`, `pdb`, `debugpy`, `breakpoints`, `dap`, `post-mortem` |
-| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), [`debugging-hermes-tui-commands`](/docs/user-guide/skills/bundled/software-development/software-development-debugging-hermes-tui-commands) |
+| Related skills | [`systematic-debugging`](/docs/user-guide/skills/bundled/software-development/software-development-systematic-debugging), [`node-inspect-debugger`](/docs/user-guide/skills/bundled/software-development/software-development-node-inspect-debugger), `debugging-hermes-tui-commands` |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/bundled/software-development/software-development-simplify-code.md

@@ -105,8 +105,20 @@ toolsets (so they can `git`, `read_file`, and `search_files`/grep).
 
 Tell each reviewer to:
 - Search the existing codebase for evidence (don't reason from the diff alone).
-- Report findings as a concrete list: `file:line → problem → suggested fix`.
-- Rank each finding `high` / `medium` / `low` confidence.
+- **Apply Chesterton's Fence:** before flagging anything for removal, run
+  `git blame` on the line to understand why it exists. If you can't determine
+  the original purpose, mark it `confidence: low` — don't guess.
+- Report findings as structured output with confidence and risk:
+  ```
+  file:line → problem → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
+  ```
+  - **SAFE** = proven not to affect behavior (unused imports, commented-out
+    code, pass-through wrappers). Auto-apply these.
+  - **CAREFUL** = improves without changing semantics (rename local variable,
+    flatten nested ternary, extract helper). Apply with test verification.
+  - **RISKY** = may change behavior or breaks public contracts (N+1
+    restructuring, public API rename, memory lifecycle change). Flag for
+    human review — do NOT auto-apply.
 - Skip nits and style-only churn. Only flag things that materially improve
   the code.
 
@@ -130,7 +142,11 @@ Pass these three goals (drop any the user's focus excludes):
 > blocks that should share an abstraction); leaky abstractions (exposing
 > internals, breaking an existing encapsulation boundary); stringly-typed
 > code (raw strings where a constant/enum/registry already exists — check the
-> canonical registries before flagging). For each, give the concrete refactor.
+> canonical registries before flagging); AI-generated slop patterns (extra
+> comments restating obvious code like `// increment counter` above `count++`;
+> unnecessary defensive null-checks on already-validated inputs; `as any`
+> casts that bypass the type system; patterns inconsistent with the rest of
+> the file). For each, give the concrete refactor.
 
 **Reviewer 3 — Efficiency**
 > Review this diff for efficiency problems. Look for: unnecessary work
@@ -140,8 +156,10 @@ Pass these three goals (drop any the user's focus excludes):
 > TOCTOU anti-patterns (existence pre-checks before an op instead of doing
 > the op and handling the error); memory issues (unbounded growth, missing
 > cleanup, listener/handle leaks); overly broad reads (loading whole files
-> when a slice would do). For each, give the concrete fix and why it's faster
-> or lighter.
+> when a slice would do); silent failures (empty catch blocks, ignored error
+> returns, `except: pass`, `.catch(() => {})` with no handling, error
+> propagation gaps — these hide bugs and should at minimum log before
+> swallowing). For each, give the concrete fix and why it's faster or safer.
 
 ### Phase 3 — Aggregate and apply
 
@@ -156,13 +174,22 @@ Wait for all three to return (batch mode returns them together).
    Don't apply a perf "fix" that hurts clarity unless the path is genuinely
    hot. When two suggestions are mutually exclusive and both defensible, pick
    the one that touches less code and note the alternative.
-4. **Apply** the surviving fixes directly with `patch` / `write_file` — unless
-   the user asked for a dry run, in which case present the list and ask first.
+4. **Apply in risk-tier order:**
+   - **SAFE first** (auto-apply): unused imports, commented-out code,
+     pass-through wrappers, redundant type assertions. Run tests after.
+   - **CAREFUL next** (apply with verification, one file at a time): rename
+     locals, flatten ternaries, extract helpers, consolidate dupes. Run tests
+     after each file. Revert any that break.
+   - **RISKY last** (flag for review — do NOT auto-apply): N+1 restructuring,
+     public API changes, concurrency fixes, error-handling changes. Present
+     each with risk description and test coverage status.
+   If the user opted for a dry run, present all three tiers and apply nothing.
 5. **Verify** you didn't break anything: run the project's targeted tests for
    the touched files (not the full suite), and re-run any linter/type check the
    repo uses. If a fix breaks a test, revert that one fix and report it.
 6. **Summarize** what you changed: a short list of applied fixes grouped by
-   reviewer category, plus any findings you deliberately skipped and why.
+   reviewer category and risk tier, plus any findings you deliberately skipped
+   and why.
 
 ## Pitfalls
 
@@ -184,6 +211,16 @@ Wait for all three to return (batch mode returns them together).
 - **Large diffs blow context.** If the diff is huge, scope it down before
   delegating — three subagents each carrying a 5000-line diff is expensive and
   may truncate.
+- **Over-trusting dead code tools.** `knip`, `ts-prune`, and `depcheck` flag
+  exports that ARE used dynamically (string-based imports, reflection). Always
+  grep for the symbol name before removing — a clean tool report is not proof.
+- **Renaming without checking public contracts.** Export names, API route
+  paths, DB column names, and config keys are contracts — even if the name is
+  bad, renaming breaks consumers. Tag public-contract changes as RISKY; never
+  auto-rename them.
+- **Removing "unnecessary" error handling.** An empty catch block or ignored
+  error might be intentional — the error is expected and benign in that
+  context. Flag it, don't remove it; let the human decide.
 
 ## Related

website/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-honcho.md

@@ -47,14 +47,14 @@ Honcho provides AI-native cross-session user modeling. It learns who the user is
 ### Cloud (app.honcho.dev)
 
 ```bash
-hermes honcho setup
+hermes memory setup honcho
 # select "cloud", paste API key from https://app.honcho.dev
 ```
 
 ### Self-hosted
 
 ```bash
-hermes honcho setup
+hermes memory setup honcho
 # select "local", enter base URL (e.g. http://localhost:8000)
 ```

website/docs/user-guide/skills/optional/blockchain/blockchain-hyperliquid.md

@@ -53,7 +53,7 @@ Read-only — no API key, no signing, no order placement.
 
 Stdlib only — no external packages, no API key.
 
-The script reads `~/.hermes/.env` for two optional defaults:
+The script reads `${HERMES_HOME:-~/.hermes}/.env` for two optional defaults:
 
 - `HYPERLIQUID_API_URL` — defaults to `https://api.hyperliquid.xyz`. Set to
   `https://api.hyperliquid-testnet.xyz` for testnet.
@@ -97,7 +97,7 @@ hyperliquid_client.py export <coin> [--interval 1h] [--hours N] [--output PATH]
 ```
 
 For `state`, `spot-balances`, `fills`, `orders`, and `review`, the address is
-optional when `HYPERLIQUID_USER_ADDRESS` is set in `~/.hermes/.env`.
+optional when `HYPERLIQUID_USER_ADDRESS` is set in `${HERMES_HOME:-~/.hermes}/.env`.
 
 ---

website/docs/user-guide/skills/optional/creative/creative-creative-ideation.md

@@ -1,14 +1,14 @@
 ---
-title: "Ideation — Generate project ideas via creative constraints"
-sidebar_label: "Ideation"
-description: "Generate project ideas via creative constraints"
+title: "Creative Ideation — Generate ideas via named methods from creative practice"
+sidebar_label: "Creative Ideation"
+description: "Generate ideas via named methods from creative practice"
 ---
 
 {/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
 
-# Ideation
+# Creative Ideation
 
-Generate project ideas via creative constraints.
+Generate ideas via named methods from creative practice.
 
 ## Skill metadata
 
@@ -16,11 +16,11 @@ Generate project ideas via creative constraints.
 |---|---|
 | Source | Optional — install with `hermes skills install official/creative/creative-ideation` |
 | Path | `optional-skills/creative/creative-ideation` |
-| Version | `1.0.0` |
+| Version | `2.1.0` |
 | Author | SHL0MS |
 | License | MIT |
 | Platforms | linux, macos, windows |
-| Tags | `Creative`, `Ideation`, `Projects`, `Brainstorming`, `Inspiration` |
+| Tags | `Creative`, `Ideation`, `Brainstorming`, `Methods`, `Inspiration` |
 
 ## Reference: full SKILL.md
 
@@ -30,138 +30,163 @@ The following is the complete skill definition that Hermes loads when this skill
 
 # Creative Ideation
 
-## When to use
-
-Use when the user says 'I want to build something', 'give me a project idea', 'I'm bored', 'what should I make', 'inspire me', or any variant of 'I have tools but no direction'. Works for code, art, hardware, writing, tools, and anything that can be made.
-
-Generate project ideas through creative constraints. Constraint + direction = creativity.
-
-## How It Works
-
-1. **Pick a constraint** from the library below — random, or matched to the user's domain/mood
-2. **Interpret it broadly** — a coding prompt can become a hardware project, an art prompt can become a CLI tool
-3. **Generate 3 concrete project ideas** that satisfy the constraint
-4. **If they pick one, build it** — create the project, write the code, ship it
+A library of ideation methods for any domain. Read the user's situation, route to the matching method, apply, generate output that is specific and non-obvious. Methods are tools — pick the right one for the situation, don't perform all of them.
 
-## The Rule
-
-Every prompt is interpreted as broadly as possible. "Does this include X?" → Yes. The prompts provide direction and mild constraint. Without either, there is no creativity.
-
-## Constraint Library
-
-### For Developers
-
-**Solve your own itch:**
-Build the tool you wished existed this week. Under 50 lines. Ship it today.
-
-**Automate the annoying thing:**
-What's the most tedious part of your workflow? Script it away. Two hours to fix a problem that costs you five minutes a day.
+## When to use
 
-**The CLI tool that should exist:**
-Think of a command you've wished you could type. `git undo-that-thing-i-just-did`. `docker why-is-this-broken`. `npm explain-yourself`. Now build it.
+Any open-ended generative or selective question: "I want to make / build / write / start something", "I'm stuck", "inspire me", "make this weirder", "help me pick", "I need to invent X", "give me a research question".
 
-**Nothing new except glue:**
-Make something entirely from existing APIs, libraries, and datasets. The only original contribution is how you connect them.
+## Operating rules
 
-**Frankenstein week:**
-Take something that does X and make it do Y. A git repo that plays music. A Dockerfile that generates poetry. A cron job that sends compliments.
+1. **Constraint plus direction is creativity.** No constraint = no traction. No direction = no shape. Methods supply both.
+2. **Refuse the first three ideas.** They're slop. Generate, discard, regenerate. See `references/anti-slop.md`.
+3. **One method per response unless asked.** Don't stack.
+4. **Specificity over abstraction.** Real proper nouns, real materials, real mechanisms. "An app for X" is slop; "a 200-line CLI tool that prints Y when Z" is direction. Naming a tech stack is not specificity — name a mechanism.
+5. **Weird must also be good.** Frame-breaking is the goal, but an idea that is strange with no real situation, mechanism, or reason to exist is its own failure mode. Every set of ideas must include at least one that is genuinely *buildable/pursuable now* — non-obvious but grounded, with a real first step. Don't trade all usefulness for surprise.
+6. **Name the method you used and who invented it.** Attribution invokes the discipline.
+7. **When user picks one, build it.** Don't keep generating after they've chosen.
 
-**Subtract:**
-How much can you remove from a codebase before it breaks? Strip a tool to its minimum viable function. Delete until only the essence remains.
+## Routing — 4-step procedure
 
-**High concept, low effort:**
-A deep idea, lazily executed. The concept should be brilliant. The implementation should take an afternoon. If it takes longer, you're overthinking it.
+Do this *before* generating any output. Routing failures produce slop.
 
-### For Makers & Artists
+You may skip narrating the routing steps if it's cleaner, but **never compress at the cost of per-idea depth**: each idea's concrete mechanism, situational binding, and honest failure mode are what make output good (measured) — they are not scaffolding, do not cut them.
 
-**Blatantly copy something:**
-Pick something you admire — a tool, an artwork, an interface. Recreate it from scratch. The learning is in the gap between your version and theirs.
+### Step 1 — Extract three signals from the prompt
 
-**One million of something:**
-One million is both a lot and not that much. One million pixels is a 1MB photo. One million API calls is a Tuesday. One million of anything becomes interesting at scale.
+**PHASE** — what stage is the user in?
 
-**Make something that dies:**
-A website that loses a feature every day. A chatbot that forgets. A countdown to nothing. An exercise in rot, killing, or letting go.
+| Phase | Cues |
+|---|---|
+| **GENERATING** | "give me an idea", "what should I make", "inspire me", no idea yet |
+| **EXPANDING** | "what else", "more like this", "give me variations" — has a base idea |
+| **SELECTING** | "help me pick", "which should I do", "I have these options" |
+| **UNBLOCKING** | "I'm stuck", "blocked", "going in circles", "stale" — has material |
+| **SUBVERTING** | "make it weirder", "less obvious", "this is too safe" |
+| **REFINING** | "this is fine but missing something", "feels rough" |
+| **SYNTHESIZING** | "I have a pile of notes / interviews / observations" |
 
-**Do a lot of math:**
-Generative geometry, shader golf, mathematical art, computational origami. Time to re-learn what an arcsin is.
+**DOMAIN** — what is the user making/doing?
 
-### For Anyone
+| Domain | Cues |
+|---|---|
+| **TEXT** | fiction, essay, poem, lyric, script, copy |
+| **OBJECT** | visual art, music, sound, performance, installation, sculpture |
+| **ARTIFACT** | software, hardware, mechanism, device |
+| **SYSTEM** | org, civic, institution, ecology, community |
+| **SELF** | life decision, career, personal practice |
+| **RESEARCH** | paper, thesis, scholarly question |
+| **PRODUCT** | business, market, service |
 
-**Text is the universal interface:**
-Build something where text is the only interface. No buttons, no graphics, just words in and words out. Text can go in and out of almost anything.
+**SPECIFICITY** — how much constraint is in the prompt?
 
-**Start at the punchline:**
-Think of something that would be a funny sentence. Work backwards to make it real. "I taught my thermostat to gaslight me" → now build it.
+| Level | Cues |
+|---|---|
+| **NONE** | "I'm bored", "inspire me" — no domain, no project |
+| **DOMAIN** | "I want to write something" — knows the field, no project |
+| **PROJECT** | "I'm working on this specific X" |
+| **PROBLEM** | "I have this specific friction within X" |
 
-**Hostile UI:**
-Make something intentionally painful to use. A password field that requires 47 conditions. A form where every label lies. A CLI that judges your commands.
+### Step 2 — Apply overrides (highest priority, fire first)
 
-**Take two:**
-Remember an old project. Do it again from scratch. No looking at the original. See what changed about how you think.
+Override rules beat the routing table:
 
-See `references/full-prompt-library.md` for 30+ additional constraints across communication, scale, philosophy, transformation, and more.
+- **Mood signal** — user says "weird", "strange", "surprising", "less obvious", "more interesting" → `references/methods/lateral-provocations.md` or `references/methods/pataphysics.md`, regardless of domain.
+- **User names a method** — use it.
+- **User asks for a method recommendation** ("which method") → surface 2–3 candidates with one-line each, ask which to apply. Don't silently default.
+- **High-slop terrain** — "AI ideas", "startup ideas", "habit tracker", "productivity / wellness / fitness / food / travel app" → force `references/methods/lateral-provocations.md` or `references/methods/pataphysics.md` over the obvious method. Refuse the first **5** ideas, not 3.
 
-## Matching Constraints to Users
+### Step 3 — Route by phase first, then domain
 
-| User says | Pick from |
-|-----------|-----------|
-| "I want to build something" (no direction) | Random — any constraint |
-| "I'm learning [language]" | Blatantly copy something, Automate the annoying thing |
-| "I want something weird" | Hostile UI, Frankenstein week, Start at the punchline |
-| "I want something useful" | Solve your own itch, The CLI that should exist, Automate the annoying thing |
-| "I want something beautiful" | Do a lot of math, One million of something |
-| "I'm burned out" | High concept low effort, Make something that dies |
-| "Weekend project" | Nothing new except glue, Start at the punchline |
-| "I want a challenge" | One million of something, Subtract, Take two |
+**By phase (applies regardless of domain):**
 
-## Output Format
+| Phase | Default route |
+|---|---|
+| GENERATING + SPECIFICITY=NONE | `references/full-prompt-library.md` **General** section (constraint dispatch) |
+| GENERATING + DOMAIN known | route by domain (next table) |
+| EXPANDING | `references/methods/scamper.md` |
+| SELECTING | `references/methods/premortem-and-inversion.md` (or `references/methods/compression-progress.md` for upside) |
+| UNBLOCKING | `references/methods/oblique-strategies.md` |
+| SUBVERTING | `references/methods/lateral-provocations.md` (fallback `references/methods/pataphysics.md`) |
+| REFINING (text) | `references/methods/defamiliarization.md` |
+| REFINING (other) | `references/methods/creative-discipline.md` (Tharp's spine) |
+| SYNTHESIZING | `references/methods/affinity-diagrams.md` |
+| Volume needed fast | `references/methods/volume-generation.md` |
+
+**By domain (when GENERATING with DOMAIN known):**
+
+| Domain | Default route |
+|---|---|
+| TEXT — formal / poetry | `references/methods/oulipo.md` |
+| TEXT — narrative | `references/methods/story-skeletons.md` |
+| TEXT — has source material to remix | `references/methods/chance-and-remix.md` |
+| OBJECT (music, visual, performance) | `references/methods/oblique-strategies.md` |
+| OBJECT — physical maker / wants a starting constraint | `references/full-prompt-library.md` **Physical / object** section |
+| ARTIFACT — wants a starting constraint | `references/full-prompt-library.md` **Software / artifact** section |
+| ARTIFACT — engineering invention with parameter conflict | `references/methods/triz-principles.md` |
+| ARTIFACT — software architecture | `references/methods/pattern-languages.md` |
+| ARTIFACT — has natural-system analog | `references/methods/biomimicry.md` |
+| ARTIFACT — accumulated assumptions to question | `references/methods/first-principles.md` |
+| SYSTEM (civic, org, institutional) | `references/methods/leverage-points.md` |
+| SYSTEM — collective / participatory | `references/full-prompt-library.md` **Social / collective** section |
+| SELF (life, career, what-to-study) | `references/methods/derive-and-mapping.md` |
+| RESEARCH — picking a question | `references/methods/compression-progress.md` |
+| RESEARCH — attacking a known problem | `references/methods/polya.md` |
+| PRODUCT (business, service) | `references/methods/jobs-to-be-done.md` |
+| Need to break a frame / find analogy | `references/methods/analogy-and-blending.md` |
+
+### Step 4 — Handle ambiguity and contradiction
+
+- **Multiple paths plausible** → pick the one closest to the user's actual phrasing. Don't pick the most interesting method to seem sophisticated.
+- **Genuinely ambiguous** → ask ONE clarifying question, don't silently guess. Examples: *"Are you generating ideas or picking between ones you have?"* / *"Is this for fiction, essay, or something else?"*
+- **Signals contradict** (e.g., "weird startup ideas" → product domain + weird mood) → **stack two methods explicitly**. State what you're doing: *"Using `jobs-to-be-done` for the product framing + `lateral-provocations` to break the obvious shape."*
+- **No match** → constraint dispatch (`references/full-prompt-library.md`) is the safe fallback.
+- **Same question asked again** → switch methods. Variation in method = variation in idea distribution.
+
+### Anti-default check (run before generating)
+
+- About to write "Here are 5 ideas:" or a bare numbered list? → STOP. Pick a method first.
+- About to default to generic LLM-mode brainstorming? → STOP. Pick a path above.
+- Output looks like what an unrouted LLM would produce? → routing failed, redo.
+
+The default LLM mode is exactly what this skill exists to displace. If you generate without routing, you've defeated the skill.
+
+For deeper edge cases (mood signals, stacking, anti-patterns) see `references/heuristics.md`.
+
+## Output format
+
+For the constraint-dispatch default path:
 
 ```
-## Constraint: [Name]
+## Constraint: [Name] — from [Source]
 > [The constraint, one sentence]
 
 ### Ideas
 
 1. **[One-line pitch]**
-   [2-3 sentences: what you'd build and why it's interesting]
-   ⏱ [weekend / week / month] • 🔧 [stack]
-
-2. **[One-line pitch]**
-   [2-3 sentences]
-   ⏱ ... • 🔧 ...
+   [2-3 sentences — what specifically is made, why it's interesting]
+   ⏱ [weekend/week/month]  •  🔧 [stack/medium/materials]
 
-3. **[One-line pitch]**
-   [2-3 sentences]
-   ⏱ ... • 🔧 ...
+2. ...
+3. ...
 ```
 
-## Example
+For other methods, use the format the method specifies (TRIZ produces a contradiction analysis; OuLiPo produces constrained text; Oblique Strategies produces a single applied card → next move). Don't force every method into the constraint template.
 
-```
-## Constraint: The CLI tool that should exist
-> Think of a command you've wished you could type. Now build it.
-
-### Ideas
+**Every idea set, regardless of method:**
+- Name the method used. On slop terrain, name the obvious ideas you refused.
+- Give each idea its concrete mechanism and its honest failure mode / tradeoff / who-it's-for. This depth is what makes ideas land — measured, not decorative.
+- Mark at least one idea as the **grounded** one — buildable/pursuable now, non-obvious but with a real first step. The others can run further toward the strange; this one has to be genuinely doable. Don't let the whole set be weird-but-impractical.
 
-1. **`git whatsup` — show what happened while you were away**
-   Compares your last active commit to HEAD and summarizes what changed,
-   who committed, and what PRs merged. Like a morning standup from your repo.
-   ⏱ weekend • 🔧 Python, GitPython, click
-
-2. **`explain 503` — HTTP status codes for humans**
-   Pipe any status code or error message and get a plain-English explanation
-   with common causes and fixes. Pulls from a curated database, not an LLM.
-   ⏱ weekend • 🔧 Rust or Go, static dataset
-
-3. **`deps why <package>` — why is this in my dependency tree**
-   Traces a transitive dependency back to the direct dependency that pulled
-   it in. Answers "why do I have 47 copies of lodash" in one command.
-   ⏱ weekend • 🔧 Node.js, npm/yarn lockfile parsing
-```
+## File map
 
-After the user picks one, start building — create the project, write the code, iterate.
+- `references/full-prompt-library.md` — constraint library, sectioned by domain (General, Software, Physical, Social, Lists). Default path for SPECIFICITY=NONE.
+- `references/method-catalog.md` — one-line summary + when-to-use per method
+- `references/heuristics.md` — extended decision tree for edge cases
+- `references/anti-slop.md` — anti-slop rules; apply to every output
+- `references/exercises.md` — time-boxed exercises (5min / 30min / 1hr / day / week)
+- `references/methods/` — 22 named methods, one file each, load only the one you're using
 
 ## Attribution
 
-Constraint approach inspired by [wttdotm.com/prompts.html](https://wttdotm.com/prompts.html). Adapted and expanded for software development and general-purpose ideation.
+Constraint-dispatch core adapted from [wttdotm.com/prompts.html](https://wttdotm.com/prompts.html). Methods drawn from primary sources cited in each method file.

website/docs/user-guide/skills/optional/creative/creative-kanban-video-orchestrator.md

@@ -21,7 +21,7 @@ Plan, set up, and monitor a multi-agent video production pipeline backed by Herm
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `video`, `kanban`, `multi-agent`, `orchestration`, `production-pipeline` |
-| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator), [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/bundled/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), [`spotify`](/docs/user-guide/skills/bundled/media/media-spotify), [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
+| Related skills | [`kanban-orchestrator`](/docs/user-guide/skills/bundled/devops/devops-kanban-orchestrator), [`kanban-worker`](/docs/user-guide/skills/bundled/devops/devops-kanban-worker), [`ascii-video`](/docs/user-guide/skills/bundled/creative/creative-ascii-video), [`manim-video`](/docs/user-guide/skills/bundled/creative/creative-manim-video), [`p5js`](/docs/user-guide/skills/bundled/creative/creative-p5js), [`comfyui`](/docs/user-guide/skills/bundled/creative/creative-comfyui), [`touchdesigner-mcp`](/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp), [`blender-mcp`](/docs/user-guide/skills/optional/creative/creative-blender-mcp), [`pixel-art`](/docs/user-guide/skills/optional/creative/creative-pixel-art), [`ascii-art`](/docs/user-guide/skills/bundled/creative/creative-ascii-art), [`songwriting-and-ai-music`](/docs/user-guide/skills/bundled/creative/creative-songwriting-and-ai-music), [`heartmula`](/docs/user-guide/skills/bundled/media/media-heartmula), [`songsee`](/docs/user-guide/skills/bundled/media/media-songsee), `spotify`, [`youtube-content`](/docs/user-guide/skills/bundled/media/media-youtube-content), [`claude-design`](/docs/user-guide/skills/bundled/creative/creative-claude-design), [`excalidraw`](/docs/user-guide/skills/bundled/creative/creative-excalidraw), [`architecture-diagram`](/docs/user-guide/skills/bundled/creative/creative-architecture-diagram), [`concept-diagrams`](/docs/user-guide/skills/optional/creative/creative-concept-diagrams), [`baoyu-comic`](/docs/user-guide/skills/optional/creative/creative-baoyu-comic), [`baoyu-infographic`](/docs/user-guide/skills/bundled/creative/creative-baoyu-infographic), [`humanizer`](/docs/user-guide/skills/bundled/creative/creative-humanizer), [`gif-search`](/docs/user-guide/skills/bundled/media/media-gif-search), [`meme-generation`](/docs/user-guide/skills/optional/creative/creative-meme-generation) |
 
 ## Reference: full SKILL.md
 
@@ -194,7 +194,7 @@ task graphs. See **[references/examples.md](https://github.com/NousResearch/herm
    right human-review gates.
 
 8. **Verify API keys BEFORE firing.** External APIs (TTS, image-gen,
-   image-to-video) need keys in `~/.hermes/.env` or the user's secret store.
+   image-to-video) need keys in `${HERMES_HOME:-~/.hermes}/.env` or the user's secret store.
    A worker that hits a missing-key error wastes a task slot. The setup
    script's `check_key` helper aborts cleanly if a required key is missing.

website/docs/user-guide/skills/optional/devops/devops-pinggy-tunnel.md

@@ -21,7 +21,7 @@ Zero-install localhost tunnels over SSH via Pinggy.
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
-| Related skills | `cloudflared-quick-tunnel`, [`webhook-subscriptions`](/docs/user-guide/skills/bundled/devops/devops-webhook-subscriptions) |
+| Related skills | `cloudflared-quick-tunnel`, `webhook-subscriptions` |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/optional/devops/devops-watchers.md

@@ -77,7 +77,7 @@ python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
   --name hn --url https://news.ycombinator.com/rss --max 5
 ```
 
-Watch a GitHub repo (set `GITHUB_TOKEN` in `~/.hermes/.env` to avoid the 60 req/hr anonymous rate limit):
+Watch a GitHub repo (set `GITHUB_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` to avoid the 60 req/hr anonymous rate limit):
 
 ```bash
 python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \

website/docs/user-guide/skills/optional/mcp/mcp-fastmcp.md

@@ -21,7 +21,7 @@ Build, test, inspect, install, and deploy MCP servers with FastMCP in Python. Us
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
-| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
+| Related skills | `native-mcp`, [`mcporter`](/docs/user-guide/skills/optional/mcp/mcp-mcporter) |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/optional/payments/payments-stripe-projects.md

@@ -44,7 +44,7 @@ Trigger phrases:
 - "manage my stack credentials", "rotate this key", "upgrade my plan"
 - "what providers can I add?"
 
-If the user already has a provider account, this skill can still connect it with `stripe projects link &lt;provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
+If the user already has a provider account, this skill can still connect it with `stripe projects link <provider>`. If the user wants to use an existing provider resource, such as an existing database or Vercel project, check provider support first; many providers currently support provisioning new resources but not importing existing ones.
 
 ## Prerequisites

website/docs/user-guide/skills/optional/productivity/productivity-canvas.md

@@ -42,7 +42,7 @@ Read-only access to Canvas LMS for listing courses and assignments.
 2. Go to **Account → Settings** (click your profile icon, then Settings)
 3. Scroll to **Approved Integrations** and click **+ New Access Token**
 4. Name the token (e.g., "Hermes Agent"), set an optional expiry, and click **Generate Token**
-5. Copy the token and add to `~/.hermes/.env`:
+5. Copy the token and add to `${HERMES_HOME:-~/.hermes}/.env`:
 
 ```
 CANVAS_API_TOKEN=[redacted:secret-assignment]

website/docs/user-guide/skills/optional/productivity/productivity-shopify.md

@@ -40,7 +40,7 @@ The REST Admin API is legacy since 2024-04 and only receives security fixes. **U
 1. In Shopify admin: **Settings → Apps and sales channels → Develop apps → Create an app**.
 2. Click **Configure Admin API scopes**, select what you need (examples below), save.
 3. **Install app** → the Admin API access token appears ONCE. Copy it immediately — Shopify will never show it again. Tokens start with `shpat_`.
-4. Save to `~/.hermes/.env`:
+4. Save to `${HERMES_HOME:-~/.hermes}/.env`:
    ```
    SHOPIFY_ACCESS_TOKEN=[redacted:secret-assignment]
    SHOPIFY_STORE_DOMAIN=my-store.myshopify.com

website/docs/user-guide/skills/optional/productivity/productivity-siyuan.md

@@ -37,7 +37,7 @@ Use the [SiYuan](https://github.com/siyuan-note/siyuan) kernel API via curl to s
 
 1. Install and run SiYuan (desktop or Docker)
 2. Get your API token: [redacted:secret-assignment] > About > API token**
-3. Store it in `~/.hermes/.env`:
+3. Store it in `${HERMES_HOME:-~/.hermes}/.env`:
    ```
    SIYUAN_TOKEN=[redacted:secret-assignment]
    SIYUAN_URL=http://127.0.0.1:6806

website/docs/user-guide/skills/optional/productivity/productivity-telephony.md

@@ -34,7 +34,7 @@ The following is the complete skill definition that Hermes loads when this skill
 This optional skill gives Hermes practical phone capabilities while keeping telephony out of the core tool list.
 
 It ships with a helper script, `scripts/telephony.py`, that can:
-- save provider credentials into `~/.hermes/.env`
+- save provider credentials into `${HERMES_HOME:-~/.hermes}/.env`
 - search for and buy a Twilio phone number
 - remember that owned number for later sessions
 - send SMS / MMS from the owned number
@@ -121,7 +121,7 @@ Why:
 
 The skill persists telephony state in two places:
 
-### `~/.hermes/.env`
+### `${HERMES_HOME:-~/.hermes}/.env`
 Used for long-lived provider credentials and owned-number IDs, for example:
 - `TWILIO_ACCOUNT_SID`
 - `TWILIO_AUTH_TOKEN`
@@ -258,7 +258,7 @@ python3 "$SCRIPT" save-twilio AC... auth_token_here
 python3 "$SCRIPT" twilio-search --country US --area-code 702 --limit 10
 ```
 
-3. Buy it and save it into `~/.hermes/.env` + state:
+3. Buy it and save it into `${HERMES_HOME:-~/.hermes}/.env` + state:
 ```bash
 python3 "$SCRIPT" twilio-buy "+17025551234" --save-env
 ```
@@ -420,7 +420,7 @@ After setup, you should be able to do all of the following with just this skill:
 
 1. `diagnose` shows provider readiness and remembered state
 2. search and buy a Twilio number
-3. persist that number to `~/.hermes/.env`
+3. persist that number to `${HERMES_HOME:-~/.hermes}/.env`
 4. send an SMS from the owned number
 5. poll inbound texts for the owned number later
 6. place a direct Twilio call

website/docs/user-guide/skills/optional/research/research-gitnexus-explorer.md

@@ -21,7 +21,7 @@ Index a codebase with GitNexus and serve an interactive knowledge graph via web
 | License | MIT |
 | Platforms | linux, macos, windows |
 | Tags | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
-| Related skills | [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
+| Related skills | `native-mcp`, [`codebase-inspection`](/docs/user-guide/skills/bundled/github/github-codebase-inspection) |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/optional/research/research-qmd.md

@@ -21,7 +21,7 @@ Search personal knowledge bases, notes, docs, and meeting transcripts locally us
 | License | MIT |
 | Platforms | macos, linux |
 | Tags | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
-| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`native-mcp`](/docs/user-guide/skills/bundled/mcp/mcp-native-mcp), [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
+| Related skills | [`obsidian`](/docs/user-guide/skills/bundled/note-taking/note-taking-obsidian), `native-mcp`, [`arxiv`](/docs/user-guide/skills/bundled/research/research-arxiv) |
 
 ## Reference: full SKILL.md

website/docs/user-guide/skills/optional/security/security-1password.md

@@ -51,7 +51,7 @@ Use this skill when the user wants secrets managed through 1Password instead of
 
 ### Service Account (recommended for Hermes)
 
-Set `OP_SERVICE_ACCOUNT_TOKEN` in `~/.hermes/.env` (the skill will prompt for this on first load).
+Set `OP_SERVICE_ACCOUNT_TOKEN` in `${HERMES_HOME:-~/.hermes}/.env` (the skill will prompt for this on first load).
 No desktop app needed. Supports `op read`, `op inject`, `op run`.
 
 ```bash

website/docs/user-guide/skills/optional/security/security-godmode.md

@@ -418,4 +418,4 @@ Claude Sonnet 4 is robust against all current techniques for clearly harmful con
 9. **Always use `load_godmode.py` in execute_code** — The individual scripts (`parseltongue.py`, `godmode_race.py`, `auto_jailbreak.py`) have argparse CLI entry points with `if __name__ == '__main__'` blocks. When loaded via `exec()` in execute_code, `__name__` is `'__main__'` and argparse fires, crashing the script. The `load_godmode.py` loader handles this by setting `__name__` to a non-main value and managing sys.argv.
 10. **boundary_inversion is model-version specific** — Works on Claude 3.5 Sonnet but NOT Claude Sonnet 4 or Claude 4.6. The strategy order in auto_jailbreak tries it first for Claude models, but falls through to refusal_inversion when it fails. Update the strategy order if you know the model version.
 11. **Gray-area vs hard queries** — Jailbreak techniques work much better on "dual-use" queries (lock picking, security tools, chemistry) than on overtly harmful ones (phishing templates, malware). For hard queries, skip directly to ULTRAPLINIAN or use Hermes/Grok models that don't refuse.
-12. **execute_code sandbox has no env vars** — When Hermes runs auto_jailbreak via execute_code, the sandbox doesn't inherit `~/.hermes/.env`. Load dotenv explicitly: `from dotenv import load_dotenv; load_dotenv(os.path.expanduser("~/.hermes/.env"))`
+12. **execute_code sandbox has no env vars** — When Hermes runs auto_jailbreak via execute_code, the sandbox doesn't inherit the Hermes `.env`. Load dotenv explicitly: `import os; from dotenv import load_dotenv; load_dotenv(os.path.join(os.environ.get("HERMES_HOME", os.path.expanduser("~/.hermes")), ".env"))`

website/docs/user-guide/skills/optional/software-development/software-development-rest-graphql-debug.md

@@ -414,7 +414,7 @@ class TestAPISmoke:
 
 ### Token handling
 - Never log full tokens. Redact: `Bearer <REDACTED>`.
-- Never hardcode tokens in scripts. Read from env (`os.environ["API_TOKEN"]`) or `~/.hermes/.env`.
+- Never hardcode tokens in scripts. Read from env (`os.environ["API_TOKEN"]`) or `${HERMES_HOME:-~/.hermes}/.env`.
 - Rotate immediately if a token surfaces in logs, error messages, or git history.
 
 ### Safe logging

website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/bundled/email/email-himalaya.md

@@ -217,13 +217,13 @@ himalaya message write -H "To:[redacted:email]" -H "Subject:Test" "Message
 移动到文件夹：
 
 ```bash
-himalaya message move 42 "Archive"
+himalaya message move "Archive" 42
 ```
 
 复制到文件夹：
 
 ```bash
-himalaya message copy 42 "Important"
+himalaya message copy "Important" 42
 ```
 
 ### 删除邮件
@@ -271,7 +271,7 @@ himalaya attachment download 42
 保存到指定目录：
 
 ```bash
-himalaya attachment download 42 --dir ~/Downloads
+himalaya attachment download 42 --downloads-dir ~/Downloads
 ```
 
 ## 输出格式

website/sidebars.ts

@@ -60,6 +60,7 @@ const sidebars: SidebarsConfig = {
           label: 'Core',
           items: [
             'user-guide/features/tools',
+            'user-guide/features/tool-search',
             'user-guide/features/skills',
             'user-guide/features/lsp',
             'user-guide/features/curator',
@@ -151,7 +152,6 @@ const sidebars: SidebarsConfig = {
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent',
-                    'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-kanban-codex-lane',
                     'user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode',
                   ],
                 },

1 PR closed without merging

From the close comments: merged via another change 1

#48898 docs(skills): fix himalaya CLI arg order and download flag (closes #48835) · merged via another change → #49914

Closed issues · 1

Closed#48835[Bug]: Himalaya skill outdated / out of sync with current CLI usage

How this cluster was grouped

Link evidence (partly structural links): some members are connected by structural evidence (shared changed files, or a closing/superseded reference); the rest are joined by an automated relevance judgement over their text.
Members outside that structural core may belong to a different underlying problem.
Pairwise link density 0.34: the share of item pairs that carry a link, counting a structural link in full and a relevance-only link at 0.36. 1.00 means every pair is linked.

Pick up a Lab task

Check whether a fix covers the open issues here, with your own agent. Bring back evidence for maintainers.

Open the Lab

At a glance

Subsystem: skills
Merged PRs: #49914
Closed issues: 1
Attempts: 1 PR closed without merging
Fix link checked: 21 Jun 2026

For your agent

The same facts, typed.

cluster/48835.json
cluster/48835.md