better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/web-search-provider-plugin.md

@@ -1,260 +0,0 @@
----
-sidebar_position: 12
-title: "Web Search Provider Plugins"
-description: "How to build a web-search/extract/crawl backend plugin for Hermes Agent"
----
-
-# Building a Web Search Provider Plugin
-
-Web-search provider plugins register a backend that services `web_search`, `web_extract`, and (optionally) deep-crawl tool calls. Built-in providers — Firecrawl, SearXNG, Tavily, Perplexity, Exa, Parallel, Keenable, Brave Search (free tier), xAI, and DDGS — all ship as plugins under `plugins/web/<name>/`. You can add a new one, or override a bundled one, by dropping a directory next to them.
-
-:::tip
-Web search is one of several **backend plugins** Hermes supports. The others (with their own ABCs) are [Image Generation Provider Plugins](/developer-guide/image-gen-provider-plugin), [Video Generation Provider Plugins](/developer-guide/video-gen-provider-plugin), [Memory Provider Plugins](/developer-guide/memory-provider-plugin), [Context Engine Plugins](/developer-guide/context-engine-plugin), and [Model Provider Plugins](/developer-guide/model-provider-plugin). General tool/hook/CLI plugins live in [Build a Hermes Plugin](/developer-guide/plugins).
-:::
-
-## How discovery works
-
-Hermes scans for web-search backends in three places:
-
-1. **Bundled** — `<repo>/plugins/web/<name>/` (auto-loaded with `kind: backend`, always available)
-2. **User** — `~/.hermes/plugins/web/<name>/` (opt-in via `plugins.enabled` or `hermes plugins enable <name>`)
-3. **Pip** — packages declaring a `hermes_agent.plugins` entry point
-
-Each plugin's `register(ctx)` function calls `ctx.register_web_search_provider(...)` — that puts the instance into the registry in `agent/web_search_registry.py`. The active provider for each capability is picked by config:
-
-| Capability | Config key | Falls back to |
-|---|---|---|
-| `web_search` | `web.search_backend` | `web.backend` |
-| `web_extract` | `web.extract_backend` | `web.backend` |
-| Deep crawl modes inside `web_extract` | `web.extract_backend` | `web.backend` |
-
-When neither key is set, Hermes auto-detects the backend from whichever API key/URL is present in the environment. `hermes tools` walks users through selection.
-
-## Directory structure
-
-```
-plugins/web/my-backend/
-├── __init__.py     # register() entry point
-├── provider.py     # WebSearchProvider subclass
-└── plugin.yaml     # Manifest with kind: backend and provides_web_providers
-```
-
-`brave_free/` and `ddgs/` are the smallest in-tree references — `brave_free` for an API-key-gated search-only provider, `ddgs` for a no-key provider that lazy-installs its SDK.
-
-## The WebSearchProvider ABC
-
-Subclass `agent.web_search_provider.WebSearchProvider`. The only required members are `name`, `is_available()`, and whichever of `search()` / `extract()` you implement. (Deep crawling is not a separate method — it's a mode of `extract()`.)
-
-```python
-# plugins/web/my-backend/provider.py
-from __future__ import annotations
-
-import os
-from typing import Any, Dict, List
-
-from agent.web_search_provider import WebSearchProvider
-
-
-class MyBackendWebSearchProvider(WebSearchProvider):
-    """Minimal search-only provider against the My Backend HTTP API."""
-
-    @property
-    def name(self) -> str:
-        # Stable id used in web.search_backend / web.extract_backend / web.backend
-        # config keys. Lowercase, no spaces; hyphens permitted.
-        return "my-backend"
-
-    @property
-    def display_name(self) -> str:
-        # Human label shown in `hermes tools`. Defaults to `name`.
-        return "My Backend"
-
-    def is_available(self) -> bool:
-        # Cheap check — env var present, optional dep importable, etc.
-        # MUST NOT make network calls (runs on every `hermes tools` paint).
-        return bool(os.getenv("MY_BACKEND_API_KEY", "").strip())
-
-    def supports_search(self) -> bool:
-        return True
-
-    def supports_extract(self) -> bool:
-        return False
-
-    def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
-        import httpx
-
-        api_key = os.environ["MY_BACKEND_API_KEY"]
-        try:
-            resp = httpx.get(
-                "https://api.example.com/search",
-                params={"q": query, "count": max(1, min(int(limit), 20))},
-                headers={"Authorization": f"Bearer {api_key}"},
-                timeout=15,
-            )
-            resp.raise_for_status()
-            data = resp.json()
-        except httpx.HTTPError as exc:
-            return {"success": False, "error": str(exc)}
-
-        # Response shape is fixed — see "Response shape" below.
-        return {
-            "success": True,
-            "data": {
-                "web": [
-                    {
-                        "title": item.get("title", ""),
-                        "url": item.get("url", ""),
-                        "description": item.get("snippet", ""),
-                        "position": idx + 1,
-                    }
-                    for idx, item in enumerate(data.get("results", []))
-                ],
-            },
-        }
-```
-
-```python
-# plugins/web/my-backend/__init__.py
-from plugins.web.my_backend.provider import MyBackendWebSearchProvider
-
-
-def register(ctx) -> None:
-    """Plugin entry point — called once at load time."""
-    ctx.register_web_search_provider(MyBackendWebSearchProvider())
-```
-
-## plugin.yaml
-
-```yaml
-name: web-my-backend
-version: 1.0.0
-description: "My Backend web search — Bearer-auth REST API"
-author: Your Name
-kind: backend
-provides_web_providers:
-  - my-backend
-requires_env:
-  - MY_BACKEND_API_KEY
-```
-
-| Key | Purpose |
-|---|---|
-| `kind: backend` | Routes the plugin through the backend-loading path |
-| `provides_web_providers` | List of provider `name`s this plugin registers — used by the loader to advertise the plugin in `hermes tools` even before `register()` runs |
-| `requires_env` | Interactive credential prompt during `hermes plugins install` (see [Build a Hermes Plugin](/developer-guide/plugins#gate-on-environment-variables) for the rich format) |
-
-## ABC reference
-
-Full contract in `agent/web_search_provider.py`. Methods you may override:
-
-| Member | Required | Default | Purpose |
-|---|---|---|---|
-| `name` | ✅ | — | Stable id used in `web.*_backend` config |
-| `display_name` | — | `name` | Label shown in `hermes tools` |
-| `is_available()` | ✅ | — | Cheap availability gate — env vars, optional deps |
-| `supports_search()` | — | `True` | Capability flag for `web_search` routing |
-| `supports_extract()` | — | `False` | Capability flag for `web_extract` routing |
-| `search(query, limit)` | conditional | raises | Required when `supports_search()` returns `True` |
-| `extract(urls, **kwargs)` | conditional | raises | Required when `supports_extract()` returns `True` |
-
-Providers can advertise multiple capabilities from a single class — Firecrawl, Tavily, Perplexity, Keenable, Exa, and Parallel all implement both search and extract. Brave Search and DDGS are search-only; SearXNG is search-only with a documented "pair me with an extract provider" workflow.
-
-## Response shape
-
-The tool wrapper expects a fixed envelope so it doesn't have to translate between backends.
-
-**Search success:**
-
-```python
-{
-    "success": True,
-    "data": {
-        "web": [
-            {"title": str, "url": str, "description": str, "position": int},
-            ...
-        ],
-    },
-}
-```
-
-**Extract success:**
-
-```python
-{
-    "success": True,
-    "data": [
-        {
-            "url": str,
-            "title": str,
-            "content": str,
-            "raw_content": str,
-            "metadata": dict,    # optional
-            "error": str,        # optional, only on per-URL failure
-        },
-        ...
-    ],
-}
-```
-
-**Either capability, on failure:**
-
-```python
-{"success": False, "error": "human-readable message"}
-```
-
-Both `search()` and `extract()` may be `async def` — the dispatcher detects coroutine functions via `inspect.iscoroutinefunction` and awaits accordingly. Sync implementations that do blocking I/O (HTTP, SDK calls) are fine for small backends; the dispatcher handles threading.
-
-## Capability flags
-
-Hermes routes calls to the right provider based on the `supports_*` flags. A common multi-provider setup:
-
-```yaml
-# ~/.hermes/config.yaml
-web:
-  search_backend: "brave-free"     # search-only, fast, free 2k/mo
-  extract_backend: "firecrawl"     # extract + crawl, paid quota
-```
-
-When `web.search_backend` or `web.extract_backend` aren't set, both fall through to `web.backend`. When that's also unset, Hermes picks the first available provider that supports the requested capability based on env-var presence.
-
-If your provider only supports one capability, leave the other flags at their default (`False`) and the registry will skip it for that tool — users won't see misleading "provider X failed" errors when they're using X only for search and asking the agent to extract.
-
-## How Hermes wires it into the tools
-
-The `web_search` and `web_extract` tools live in `tools/web_tools.py`. At call time they:
-
-1. Read the relevant config key (`web.search_backend` for `web_search`, `web.extract_backend` for `web_extract`)
-2. Ask the registry for the provider with that `name`
-3. Check `is_available()` and the matching `supports_*()` flag
-4. Dispatch to `search()` / `extract()` (deep crawl runs as a mode inside `extract()`), awaiting if the method is a coroutine
-5. JSON-serialize the response envelope and hand it back to the LLM
-
-Errors surface as the tool result; the LLM decides how to explain them. If no provider is registered (or every available one fails the capability gate), the tool returns a helpful error pointing at `hermes tools`.
-
-## Lazy-installing optional dependencies
-
-If your provider wraps a third-party SDK (like DDGS does with the `ddgs` package), don't `import` it at module top level. Use `tools.lazy_deps.ensure(...)` inside `is_available()` or `search()` — Hermes will install the package on first use, gated by `security.allow_lazy_installs`. See [Build a Hermes Plugin → Lazy-install](/developer-guide/plugins#lazy-install-optional-python-dependencies) for the security model.
-
-## Reference implementations
-
-- **`plugins/web/brave_free/`** — small, API-key-gated, search-only HTTP provider. Good starting template.
-- **`plugins/web/ddgs/`** — no-key provider that lazy-installs its SDK. Useful pattern for backends that wrap a Python package.
-- **`plugins/web/firecrawl/`** — full multi-capability provider (search + extract + crawl) with multiple format modes.
-- **`plugins/web/searxng/`** — self-hosted, URL-configured backend with no auth.
-- **`plugins/web/xai/`** — LLM-backed search via Grok's server-side `web_search` tool. Shows how to reuse an existing OAuth/env-var credential surface (`tools/xai_http.py`) without adding new env vars, and how to write a cheap `is_available()` that honors the no-network contract.
-
-## Distribute via pip
-
-```toml
-# pyproject.toml
-[project.entry-points."hermes_agent.plugins"]
-my-backend-web = "my_backend_web_package"
-```
-
-`my_backend_web_package` must expose a top-level `register` function. See [Distribute via pip](/developer-guide/plugins#distribute-via-pip) in the general plugin guide for the full setup.
-
-## Related pages
-
-- [Web Search](/user-guide/features/web-search) — user-facing feature documentation and per-backend configuration
-- [Plugins overview](/user-guide/features/plugins) — all plugin types at a glance
-- [Build a Hermes Plugin](/developer-guide/plugins) — general tools/hooks/slash commands guide

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/developer-guide/worktree-ui-dev.md

@@ -1,168 +0,0 @@
----
-sidebar_position: 5
-title: "TUI & Desktop from Worktrees"
-description: "Run the Ink TUI and Electron desktop app from a git worktree without a full npm install per checkout"
----
-
-# TUI & Desktop from Worktrees
-
-The Python core runs fine from any [git worktree](../user-guide/git-worktrees.md) — `cd` in and `hermes` just works. The two TypeScript surfaces do not: `ui-tui/` and `apps/desktop/` each need a populated `node_modules`, and a fresh `npm ci` per worktree is slow and duplicates gigabytes across every branch you have checked out.
-
-`htui` and `hgui` are two shell helpers that close that gap. Each launches its surface **from the current worktree** while borrowing `node_modules` from one canonical checkout — so a throwaway branch costs a symlink, not an install.
-
-They're developer conveniences, not shipped commands. Drop them in `~/.zshrc`; adapt paths to taste.
-
-## The deps-sharing model
-
-One checkout is the **deps checkout** — the one place you actually run `npm install`. Every other worktree links against it, and only re-installs locally when its lockfile diverges (a branch that bumps a dependency must not silently run against stale packages).
-
-```mermaid
-flowchart TD
-    A[htui / hgui in a worktree] --> B{package-lock.json<br/>matches deps checkout?}
-    B -- yes --> C[symlink node_modules<br/>from deps checkout]
-    B -- no --> D[local npm ci<br/>in this worktree]
-    C --> E[launch surface]
-    D --> E
-```
-
-Two env vars name the canonical checkout:
-
-| Variable | Meaning |
-|----------|---------|
-| `HERMES_MAIN_CHECKOUT` | The deps checkout — where `node_modules` really lives, and whose `.venv/bin/python` runs the backend. |
-| `HERMES_GUI_DEPS_CHECKOUT` | Where the desktop deps (`apps/desktop/node_modules`) live. Defaults to `HERMES_MAIN_CHECKOUT`; override only if you keep desktop deps elsewhere. |
-
-Neither is read by Hermes itself — they're private to these helpers. The variables Hermes *does* read are covered in [Environment Variables](../reference/environment-variables.md).
-
-## `htui` — TUI from the worktree
-
-The Ink TUI has a dev path already: `hermes --tui --dev` runs the TypeScript sources via `tsx` instead of the prebuilt bundle. `htui` is a one-liner over it that also points the run at the current worktree's `ui-tui/`:
-
-```bash
-htui() {
-  local root
-  root="$(_hermes_root)" || { echo "htui: not in a Hermes checkout" >&2; return 1; }
-  ( cd "$root" && PYTHONPATH="$root" \
-      "$HERMES_MAIN_CHECKOUT/.venv/bin/python" -m hermes_cli.main --tui --dev "$@" )
-}
-```
-
-`--dev` compiles from source, so it links `ui-tui/node_modules` from `HERMES_MAIN_CHECKOUT` when the root lockfile matches and installs locally otherwise (see [`_hermes_root` / linking helpers](#shared-helpers)).
-
-:::warning `--dev` and `HERMES_TUI_DIR` are mutually exclusive
-`HERMES_TUI_DIR` points Hermes at a *prebuilt* bundle (Nix, system packages), which has no source to hot-reload. If it's set in your shell, `hermes --tui --dev` exits with an error. Run `unset HERMES_TUI_DIR` before `htui`.
-:::
-
-## `hgui` — desktop app from the worktree
-
-The desktop app needs dependencies at both the repo root and `apps/desktop/`, a Vite server, and a Python backend. The stock `npm run dev` pins Vite to `5174`; Electron also defaults to CDP port `9222` and takes a single-instance lock on its user-data directory. Changing only the Vite port is not enough to run two desktops.
-
-This **zsh** example gives each launch an explicit slot (`HGUI_SLOT`, default `0`). Use a different slot in each terminal. It uses the [shared helpers](#shared-helpers) below and requires `lsof`:
-
-```bash
-hgui() (
-  local root deps desktop slot="${HGUI_SLOT:-0}" vite_port cdp_port port
-  [[ "$slot" == [0-9] ]] || { print -u2 'hgui: HGUI_SLOT must be 0-9'; return 1; }
-  vite_port=$((5174 + slot))
-  cdp_port=$((9222 + slot))
-  for port in "$vite_port" "$cdp_port"; do
-    if lsof -nP -t -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; then
-      print -u2 "hgui: port $port is busy; choose another HGUI_SLOT"
-      return 1
-    fi
-  done
-
-  root="$(_hermes_root)" || { print -u2 'hgui: not in a Hermes checkout'; return 1; }
-  deps="${HERMES_GUI_DEPS_CHECKOUT:-$HERMES_MAIN_CHECKOUT}"
-  desktop="$root/apps/desktop"
-
-  if cmp -s "$root/package-lock.json" "$deps/package-lock.json"; then
-    _hermes_link_deps "$desktop" "$deps/apps/desktop" || return 1
-    _hermes_link_deps "$root" "$deps" || return 1
-  else
-    ( cd "$root" && npm ci ) || return 1
-  fi
-
-  cd "$desktop" || return 1
-  export PATH="$desktop/node_modules/.bin:$root/node_modules/.bin:$PATH"
-  export HERMES_DESKTOP_HERMES_ROOT="$root"
-  export HERMES_DESKTOP_PYTHON="$HERMES_MAIN_CHECKOUT/.venv/bin/python"
-  export HERMES_DESKTOP_CWD="$root"
-  export HERMES_DESKTOP_DEV_SERVER="http://127.0.0.1:$vite_port"
-  export HERMES_DESKTOP_CDP_PORT="$cdp_port"
-  export HERMES_DESKTOP_USER_DATA_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/hermes-hgui/slot-$slot"
-  # A userData override would otherwise also relocate the agent's home.
-  export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
-  export XCURSOR_SIZE=24
-
-  # Mirror the dev scripts, replacing their fixed ports. No repo edits needed.
-  concurrently -k -n "vite,electron" \
-    "node scripts/assert-root-install.mjs && npm run clean:renderer && vite --host 127.0.0.1 --port $vite_port --strictPort" \
-    "tsc --build tsconfig.electron.json && wait-on http://127.0.0.1:$vite_port && node scripts/bundle-electron-main.mjs --dev && electron ."
-)
-```
-
-For example, after setting `HERMES_MAIN_CHECKOUT` and sourcing the helpers:
-
-```bash
-# Terminal 1: main checkout
-cd "$HERMES_MAIN_CHECKOUT"
-HGUI_SLOT=0 hgui
-
-# Terminal 2: an existing worktree
-cd /path/to/hermes-worktree
-HGUI_SLOT=1 hgui
-```
-
-Slot `0` uses ports `5174`/`9222`; slot `1` uses `5175`/`9223`. Slots are caller-assigned, not atomically reserved: always use distinct slots for simultaneous starts. Busy ports are rejected, never evicted. Use separate checkouts for separate builds because launches in the same checkout still share build outputs.
-
-| Variable | Role in `hgui` |
-|----------|----------------|
-| `HGUI_SLOT` | Helper-only slot number, `0`–`9`; not a Hermes setting. |
-| `HERMES_DESKTOP_HERMES_ROOT` | Runs the backend from this worktree, not the packaged/PATH runtime. |
-| `HERMES_DESKTOP_PYTHON` | Reuses the main checkout's Python environment. Adjust for an installation that uses `venv` rather than `.venv`. |
-| `HERMES_DESKTOP_CWD` | Roots new desktop work in the worktree. |
-| `HERMES_DESKTOP_DEV_SERVER` | Points Electron at this instance's Vite server. |
-| `HERMES_DESKTOP_CDP_PORT` | Gives each instance its own renderer debugging port. |
-| `HERMES_DESKTOP_USER_DATA_DIR` | Separates Electron's single-instance lock, browser storage, and desktop preferences. |
-| `HERMES_HOME` | Explicitly preserves the agent home despite the Electron user-data override. |
-
-Each slot starts with fresh desktop preferences and remembers them on later launches. This example does not copy browser storage, saved navigation, or backend ownership from a running app.
-
-:::warning Separate desktops are not separate agent data
-The default `HERMES_HOME` is shared: sessions, configuration, credentials, and profiles remain the same. Avoid editing the same conversation from both instances. For destructive tests or incompatible database migrations, pass a separate temporary `HERMES_HOME` and configure that sandbox independently.
-:::
-
-Quit the app normally or press Ctrl-C in its launching terminal. `concurrently -k` manages its own child commands, and Electron owns its backend shutdown. Do not add a global `killport`, `pkill electron`, or a sweep of all `serve`/`dashboard --port 0` processes: those can terminate another instance. Remove the old `_hermes_gui_cleanup` trap if replacing an earlier version of this helper.
-
-## Shared helpers
-
-Both functions resolve the enclosing checkout and link deps the same way:
-
-```bash
-# The enclosing worktree, verified as a real Hermes checkout.
-_hermes_root() {
-  local root
-  root="$(git rev-parse --show-toplevel 2>/dev/null)" || return 1
-  [[ -f "$root/hermes_cli/main.py" && -d "$root/ui-tui" ]] && print -r "$root"
-}
-
-# Symlink node_modules from the deps checkout — never over an existing tree.
-_hermes_link_deps() {
-  local target="${1%/}" source="${2%/}"
-  [[ -d "$source/node_modules" ]] || return 1
-  [[ -e "$target/node_modules" ]] || ln -s "$source/node_modules" "$target/node_modules"
-}
-```
-
-:::info Why link only when locks match
-A symlink to a divergent `node_modules` is worse than no install — the worktree would build against packages its own lockfile never declared. Byte-comparing `package-lock.json` is the cheap, exact guard: same lock ⇒ safe to borrow; different lock ⇒ `npm ci` locally. Vite realpaths symlinks before enforcing `server.fs.allow`, which is why `apps/desktop/vite.config.ts` whitelists the real `node_modules` location.
-:::
-
-## See also
-
-- [Git Worktrees](../user-guide/git-worktrees.md) — the isolation model these helpers build on
-- [TUI](../user-guide/tui.md) — `hermes --tui --dev` and the `HERMES_TUI_DIR` prebuild path
-- [Desktop App](../user-guide/desktop.md) — building from source and the backend resolution ladder
-- [`apps/desktop/README.md`](https://github.com/NousResearch/hermes-agent/blob/main/apps/desktop/README.md) — dev server, sandbox script, and packaging
-- [Environment Variables](../reference/environment-variables.md) — every `HERMES_*` variable Hermes reads

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/getting-started/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Getting Started",
-  "position": 1,
-  "link": {
-    "type": "generated-index",
-    "description": "Get up and running with Hermes Agent in minutes."
-  }
-}

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/getting-started/installation.md

@@ -1,200 +0,0 @@
----
-sidebar_position: 2
-title: "Installation"
-description: "Install Hermes Agent on Linux, macOS, WSL2, native Windows, or Android via Termux"
----
-
-# Installation
-
-Get Hermes Agent up and running in under two minutes!
-
-:::tip Platform Support
-For the full platform support matrix (which OSes, distribution methods, and
-platform-gated features are supported), see **[Platform Support](./platform-support.md)**.
-:::
-
-## Quick Install
-### With the Hermes Desktop installer on macOS or Windows (recommended)
-To easily install the command-line and desktop applications, [download the Hermes Desktop installer](https://hermes-agent.nousresearch.com/) from our website and run it.
-
-:::note
-The macOS installer is **Apple Silicon only**. macOS on x86 (Intel) processors is [not a supported platform](./platform-support.md#unsupported).
-:::
-
-### Without Hermes Desktop:
-For a command-line only install without Hermes Desktop, run:
-
-#### Linux / macOS / WSL2 / Android (Termux)
-```bash
-curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-```
-
-#### Windows (native)
-
-Run in powershell:
-```powershell
-iex (irm https://hermes-agent.nousresearch.com/install.ps1) 
-```
-
-If you want to install & run Hermes Desktop after a command-line only install, simply run
-```bash
-hermes desktop
-```
-
-### What the Installer Does
-
-The installer handles everything automatically — all dependencies (Python, Node.js, ripgrep, ffmpeg), the repo clone, virtual environment, global `hermes` command setup, and LLM provider configuration. By the end, you're ready to chat.
-
-#### Install Layout
-
-Where the installer puts things depends on whether you're installing as a normal user or as root:
-
-| Installer                              | Code lives at                  | `hermes` binary                         | Data directory                       |
-| -------------------------------------- | ------------------------------ | --------------------------------------- | ------------------------------------ |
-| Per-user (git installer)               | `~/.hermes/hermes-agent/`      | `~/.local/bin/hermes` (symlink)         | `~/.hermes/`                         |
-| Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes`                 | `/root/.hermes/` (or `$HERMES_HOME`) |
-
-The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`.
-
-### After Installation
-
-Reload your shell and start chatting:
-
-```bash
-source ~/.bashrc   # or: source ~/.zshrc
-hermes             # Start chatting!
-```
-
-To reconfigure individual settings later, use the dedicated commands:
-
-```bash
-hermes model          # Choose your LLM provider and model
-hermes tools          # Configure which tools are enabled
-hermes gateway setup  # Set up messaging platforms
-hermes config set     # Set individual config values
-hermes config get     # Inspect individual config values
-hermes setup          # Or run the full setup wizard to configure everything at once
-```
-
-:::tip Fastest path: Nous Portal
-One subscription covers 300+ models plus the [Tool Gateway](/user-guide/features/tool-gateway) (web search, image generation, TTS, cloud browser). Skip the per-tool key juggling:
-
-```bash
-hermes setup --portal
-```
-
-That logs you in, sets Nous as your provider, and turns on the Tool Gateway in one command.
-:::
-
-:::tip Already running Hermes on another machine?
-You don't need to rebuild your setup from scratch. Restore a full backup with `hermes import` (see [Exporting Hermes to another machine](/reference/faq#exporting-hermes-to-another-machine)), or bring over a single agent with `hermes profile import` (see [Moving a single profile to another machine](/reference/faq#moving-a-single-profile-to-another-machine)). Note that a profile export excludes credentials by design, so an export alone is not a full backup — [`hermes backup` vs `hermes profile export`](/reference/faq#hermes-backup-vs-hermes-profile-export) explains which to use.
-:::
-
----
-
-## Prerequisites
-
-**Installer:** On non-Windows platforms, the only prerequisite is **Git**. On Linux, also make sure `curl` and `xz-utils` are available (the installer downloads Node.js as a `.tar.xz` archive). The desktop app additionally requires `g++` (or `build-essential` on Debian/Ubuntu) to compile native modules. The installer automatically handles everything else:
-
-- **uv** (fast Python package manager)
-- **Python 3.11** (via uv, no sudo needed)
-- **Node.js v26** (for browser automation and WhatsApp bridge; existing system Node 22.22+, 24.11+, or 26+ is used as-is)
-- **ripgrep** (fast file search)
-- **ffmpeg** (audio format conversion for TTS)
-
-:::info
-You do **not** need to install Python, Node.js, ripgrep, or ffmpeg manually. The installer detects what's missing and installs it for you. Just make sure `git` is available (`git --version`). On Linux, ensure `curl` and `xz-utils` are installed (`sudo apt install curl xz-utils` on Debian/Ubuntu). For the desktop app, also install `build-essential` (`sudo apt install build-essential`).
-:::
-
-:::tip Nix users
-Nix is **no longer an explicitly supported install path** (best-effort only). If you already use Nix (on NixOS, macOS, or Linux), there's a dedicated setup path with a Nix flake, declarative NixOS module, and optional container mode. See the **[Nix & NixOS Setup](./nix-setup.md)** guide.
-:::
-
----
-
-## Manual / Developer Installation
-
-If you want to clone the repo and install from source — for contributing, running from a specific branch, or having full control over the virtual environment — see the [Development Setup](../developer-guide/contributing.md#development-setup) section in the Contributing guide.
-
----
-
-## Non-Sudo / System Service User Installs
-
-Running Hermes as a dedicated unprivileged user (e.g. a `hermes` systemd service account, or any user without `sudo` access) is supported. The only thing on the install path that genuinely needs root is Playwright's `--with-deps` step, which `apt`-installs shared libraries (`libnss3`, `libxkbcommon`, etc.) used by Chromium. The installer detects whether sudo is available and gracefully degrades when it isn't — it will install the Chromium binary into the service user's own Playwright cache and print the exact command an administrator needs to run separately.
-
-**Recommended split (Debian/Ubuntu):**
-
-1. **One time, as an admin user with sudo**, install the system libraries Chromium needs:
-   ```bash
-   sudo npx playwright install-deps chromium
-   ```
-   (You can run this from anywhere — `npx` will fetch Playwright on the fly.)
-
-2. **As the unprivileged service user**, run the regular installer. It will detect the missing sudo, skip `--with-deps`, and install Chromium into the user's local Playwright cache:
-   ```bash
-   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
-   ```
-
-   If you want to skip the Playwright step entirely — for example because you're running headless and don't need browser automation — pass `--skip-browser`:
-   ```bash
-   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
-   ```
-
-   The installer also pre-installs [`cua-driver`](../user-guide/features/computer-use.md) so the Computer Use toolset works the moment you enable it; pass `--skip-computer-use` to opt out (it will then install on demand when you enable the tool).
-
-3. **Make `hermes` available to the service user's shells.** The installer writes the launcher to `~/.local/bin/hermes`. System service accounts often have a minimal PATH that doesn't include `~/.local/bin`. Either add it to the user's environment, or symlink the launcher into a system location:
-   ```bash
-   # Option A — add to the service user's profile
-   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
-
-   # Option B — symlink system-wide (run as an admin)
-   sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes
-   ```
-
-4. **Verify:** `hermes doctor` should now run cleanly. If you get `ModuleNotFoundError: No module named 'dotenv'`, you're invoking the repo source `hermes` file (`~/.hermes/hermes-agent/hermes`) with system Python instead of the venv launcher (`~/.hermes/hermes-agent/venv/bin/hermes`) — fix step 3.
-
-5. **Running the messaging gateway from this account?** A user-level service stops at logout and does not start at boot until you enable lingering for the service user:
-
-   ```bash
-   sudo loginctl enable-linger <service-user>
-   ```
-
-   See [Messaging Gateway](/user-guide/messaging/) for the service setup itself.
-
-The same pattern works on Arch (the installer uses pacman with the same sudo-detection logic), Fedora/RHEL, and openSUSE — those distros don't support `--with-deps` at all, so an administrator always installs the system libraries separately. The relevant `dnf`/`zypper` commands are printed by the installer.
-
----
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| `hermes: command not found` | Reload your shell (`source ~/.bashrc`) or check PATH |
-| `API key not set` | Run `hermes model` to configure your provider, or `hermes config set OPENROUTER_API_KEY your_key` |
-| Missing config after update | Run `hermes config check` then `hermes config migrate` |
-
-For more diagnostics, run `hermes doctor` — it will tell you exactly what's missing and how to fix it.
-
-### Symlinked home directories and external storage
-
-Hermes supports a symlinked `HERMES_HOME` and symlinked home subdirectories,
-including `hooks`, `skills`, `sessions`, and `logs`. During home initialization,
-existing directory links are preserved, and permissions on linked directories
-(and descendants such as `logs/curator`) are left to their owner.
-
-If a link target is missing, inaccessible, or not a directory, initialization
-stops with a storage error naming the path and link target. Hermes does **not**
-replace the link or create its missing target: doing so could write data onto
-the local disk while an external or NAS volume is unmounted. Check the reported
-link, restore the mount or correct its target, and verify access permissions
-before retrying. For a deliberately new dotfiles target, create it yourself only
-after confirming the intended storage is available.
-
-`hermes doctor` reports these failures as storage problems, not invalid YAML.
-Keep your existing `config.yaml`; running `hermes setup` is not the repair for an
-unavailable directory. This is a directory-availability check, not a mount monitor:
-an existing directory cannot establish that the intended volume is mounted.
-
-## Install method auto-detection
-
-Hermes auto-detects whether it was installed via the git installer, Docker, or NixOS, and `hermes update` prints the matching update command for that path. There's no env var to set — the detection is based on the install layout (`~/.hermes/hermes-agent/` checkout, Docker image stamp, or Nix store path). `hermes doctor` also surfaces the detected method under its environment summary.