better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/creative/creative-unreal-mcp.md

@@ -0,0 +1,269 @@
+---
+title: "Unreal Mcp — Automate Unreal Engine editor scenes, actors, and renders"
+sidebar_label: "Unreal Mcp"
+description: "Automate Unreal Engine editor scenes, actors, and renders"
+---
+
+{/* 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. */}
+
+# Unreal Mcp
+
+Automate Unreal Engine editor scenes, actors, and renders.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/creative/unreal-mcp` |
+| Path | `optional-skills/creative\unreal-mcp` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `unreal`, `unreal-engine`, `ue5`, `3d`, `mcp`, `scenes`, `cinematics`, `lighting`, `gamedev` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Unreal Engine MCP Skill
+
+Companion skill for the `unreal-engine` entry in the Hermes MCP catalog. The
+MCP server (Epic's official, experimental "Unreal MCP" plugin, internal id
+`ModelContextProtocol`) runs INSIDE the Unreal Editor process and exposes
+editor functionality as typed tools. This skill teaches how to drive it well:
+discovering the live tool surface, sequencing calls safely, translating
+plain-English asks into scenes that actually look good, and verifying work
+visually. The user should never need to touch the editor beyond launching it.
+
+## When to Use
+
+Use when the user wants anything done in Unreal Engine: build or dress a
+level, spawn/move/delete actors, set up lighting and atmosphere, create or
+tune material instances, frame a camera shot, capture screenshots or renders,
+import assets, inspect the scene or UI, run automation tests, or script the
+editor. Works for single actions ("make the sun golden hour") and for
+complete multi-step projects ("build me a moody forest clearing with a
+campfire and render a shot of it").
+
+Don't use for: DCC-style mesh modeling/sculpting (model in Blender and
+import the result), or for editing Unreal C++ project source (that's normal
+code work — use the terminal; this skill is about the live editor).
+
+## Prerequisites
+
+Two halves, in this order: the editor side must be up before Hermes connects.
+
+### One-time, editor side
+
+1. Unreal Editor **5.8+** with a project open. (macOS: full Xcode must be
+   installed and its license accepted — the editor exits on first launch
+   without it; see pitfalls.)
+2. **Edit > Plugins** — enable **Unreal MCP** (its Toolset Registry
+   dependency auto-enables). Restart the editor when prompted.
+3. The typed toolsets ship separately from the server: also enable the
+   **AllToolsets** plugin in the same Plugins browser. Unreal MCP ships NO
+   tools itself — AllToolsets provides the shipped toolsets (SceneTools,
+   ActorTools, MaterialInstanceTools, ObjectTools, …); skip it and the
+   server connects but the agent has nothing to call.
+4. **Edit > Editor Preferences > General > Model Context Protocol** — enable
+   **Auto Start Server**. Default bind is `http://127.0.0.1:8000/mcp`
+   (port/path configurable in the same panel; server name is `unreal-mcp`).
+   To start manually instead, run `ModelContextProtocol.StartServer` in the
+   editor console (backtick key).
+
+### One-time, Hermes side
+
+    hermes mcp install unreal-engine
+
+This writes the `mcp_servers.unreal-engine` HTTP entry pointing at
+`http://127.0.0.1:8000/mcp` and probes the live server for its tools. Run it
+while the editor + server are up so the probe sees the real surface. If the
+user changed port/path in Editor Preferences, edit the `url` in
+`~/.hermes/config.yaml` under `mcp_servers.unreal-engine` to match.
+
+Do NOT use `ModelContextProtocol.GenerateClientConfig` for Hermes — that
+writes `.mcp.json`-style files for Claude Code/Cursor/etc. Hermes connects
+from `config.yaml` via the catalog entry.
+
+### Every session
+
+1. Launch Unreal Editor, wait for the project to finish loading; confirm the
+   server started (Output Log shows the bind address, or run
+   `ModelContextProtocol.StartServer` manually).
+2. Start the Hermes session. Tools register as `mcp_unreal_engine_*`. If
+   they're missing: editor wasn't up first — start it, then open a new
+   Hermes session.
+3. Sanity check: call `mcp_unreal_engine_list_toolsets` and confirm toolsets
+   come back.
+
+## The Tool Surface: Discovery, Not a Fixed List
+
+By default the plugin runs in **tool-search mode**: `tools/list` returns only
+three meta-tools, and every real tool is reached through them. Through Hermes
+they appear as:
+
+| Hermes tool | Purpose |
+|---|---|
+| `mcp_unreal_engine_list_toolsets` | Names + descriptions of every registered toolset |
+| `mcp_unreal_engine_describe_toolset` | Full JSON schemas for one named toolset's tools |
+| `mcp_unreal_engine_call_tool` | Invoke a named tool with arguments, get the result |
+
+The discovery walk, always in this order:
+
+1. `list_toolsets` → see what capability groups this project actually has
+   (the surface is project-dependent: enabled plugins, Game Feature Plugins,
+   and any custom toolsets all contribute). Names come back FULLY QUALIFIED
+   (`editor_toolset.toolsets.scene.SceneTools`,
+   `EditorToolset.EditorAppToolset`) — use them verbatim as `toolset_name`.
+2. `describe_toolset` on the group you need → read the real parameter
+   schemas. Never guess parameter names — schemas are the contract.
+3. `call_tool` with the qualified toolset name, the SHORT tool name
+   (`find_actors`, not the dotted form), and arguments matching the schema.
+
+Cache what you learn for the session; re-list only after the editor side
+changes (new plugin enabled, toolset authored, `RefreshTools` run).
+
+The alternative eager mode (`Enable Tool Search` off in Editor Preferences)
+advertises every tool as its own `mcp_unreal_engine_<tool>` entry. Discovery
+then happens at `hermes mcp install`/`configure` time instead. Tool-search
+mode is the default and what this skill assumes; it also keeps schema tokens
+out of every API call, so prefer it.
+
+See `references/tool-surface.md` for the shipped toolset catalog, authoring
+custom toolsets, and the full plugin configuration/console-command reference.
+
+## Operating Loop
+
+Every Unreal task follows the same loop:
+
+1. **Inspect first.** List toolsets, then query the scene/level state before
+   touching anything. Never assume an empty or default level. In an
+   unfamiliar project, also check for project-registered Agent Skills
+   (`call_tool` → `AgentSkillToolset.ListSkills`): a matching project skill's
+   instructions override this skill's generic defaults.
+2. **Act in small, single-purpose calls.** One logical step per `call_tool`.
+   The server executes tools **serially on the game thread** — a big
+   monolithic operation freezes the editor UI until it finishes and risks
+   client timeouts. Exception: for loops over 5+ homogeneous operations,
+   ONE `ProgrammaticToolset.execute_tool_script` call batches them
+   server-side without breaking the serial rule
+   (`references/advanced-workflows.md`).
+3. **NEVER issue overlapping calls.** Do not batch multiple
+   `mcp_unreal_engine_*` calls in one turn — Hermes runs batched calls
+   concurrently, and parallel calls against the game thread deadlock or
+   fail. Strictly one call, await result, next call. This overrides the
+   general parallel-tool-calls guidance.
+4. **Read every result.** Many tools (Blueprint compiles, material edits,
+   widget creation) report success/failure in the response body with no
+   protocol-level exception. Anything that isn't an explicit success is a
+   stop-and-diagnose, not a shrug. After property writes, read the value
+   back — several write paths silently no-op (see pitfalls).
+5. **Verify visually and structurally.** After each milestone, confirm state
+   by querying the actors/properties you changed, and capture a viewport
+   screenshot when composition matters (see `references/tool-surface.md` for
+   the capture options; `vision_analyze` the image — you are the art
+   director, judge it).
+6. **Save often.** Editor edits are in-memory until packages/levels are
+   saved; an editor crash loses everything since the last save, and MCP
+   edits are not reliably undoable. Save before AND after any bulk change,
+   and after every milestone.
+7. **Report concretely.** Actor labels, asset paths (`/Game/...`), file
+   locations of captures/renders.
+
+Rules of the world while you work:
+
+- Units are **centimeters**; axes are **Z-up**, X-forward; rotations are
+  degrees (Rotator: Roll around X, Pitch around Y, Yaw around Z). Human eye
+  height ≈ 165 cm; a door ≈ 210×90 cm. Full tables in
+  `references/scene-craft.md`.
+- Content paths use long package names: `/Game/Folder/Asset.Asset` for
+  project content, `/Engine/BasicShapes/Cube.Cube` for engine primitives.
+- Actor **labels** (what you see in the Outliner, settable, non-unique) are
+  not actor **names** (internal, unique). Prefer resolving actors by
+  label/class queries, then hold on to whatever handle the tool returns.
+- Prefer physically-plausible lighting values (lux/candela/Kelvin) over
+  arbitrary brightness numbers — but FIRST read the existing sun's
+  intensity to learn the scene's calibration convention; template worlds
+  are often calibrated around `intensity: 10`, and physical values blow
+  them out (`references/scene-craft.md` has the numbers,
+  `references/pitfalls.md` #12b has the calibration rule).
+
+## From Plain English to a Scene
+
+The user gives intent, not specs. Translate before you build:
+
+1. **Extract the brief.** Subject, mood, time of day, interior/exterior,
+   style, deliverable (screenshot? render? playable level?). Ask at most one
+   round of clarifying questions, then commit — you are the technical
+   director; don't bounce Unreal jargon back at the user.
+2. **Plan the build order.** The order that works: level/environment shell →
+   blocking (major geometry/meshes in place) → lighting + atmosphere →
+   materials → set dressing/detail → camera → capture/render. Post the plan
+   as a todo list for multi-step builds.
+3. **Build with the loop above**, one milestone at a time, screenshot at
+   each milestone.
+4. **Art-direct yourself.** Compare each screenshot against the brief:
+   readable silhouette? believable light direction/intensity? horizon not
+   dead-center? scale correct against a human-height reference? Fix before
+   moving on.
+5. **Deliver.** Screenshots/renders as files (`MEDIA:` path), plus a short
+   summary of what exists in the level and where it was saved.
+
+`references/recipes.md` has complete worked builds (exterior daylight scene,
+moody interior, golden-hour cinematic + render, asset import & placement)
+with the exact call sequences and values.
+
+## Reference Files
+
+Load on demand; keep SKILL.md-level rules in mind throughout.
+
+| Reference | Contents |
+|---|---|
+| `references/tool-surface.md` | Shipped toolsets catalog, discovery protocol detail, plugin console commands/CVars/flags, screenshot & capture paths, MCP Inspector debugging, extending with custom Python/C++ toolsets |
+| `references/advanced-workflows.md` | Sophisticated workflows, live-verified: ProgrammaticToolset batching, Blueprint DSL authoring loop (create→DSL→compile→spawn), PIE test sessions, Sequencer orientation (140 tools), LogsToolset self-debugging, automation testing, semantic asset search, config settings, per-situation decision table |
+| `references/scene-craft.md` | Numeric cheat sheet: physical light intensities, color temperatures, exposure/EV100, fog densities, mood recipes (noon/golden hour/overcast/night/interior), scale tables, content path conventions |
+| `references/recipes.md` | End-to-end worked builds with exact call sequences |
+| `references/pitfalls.md` | Setup, runtime, and workflow pitfalls with fixes — read before your first session and whenever something misbehaves |
+
+## Pitfalls (top of mind — full list in references/pitfalls.md)
+
+- **Start order matters.** Editor + server up first, then the Hermes
+  session. Missing `mcp_unreal_engine_*` tools = wrong order.
+- **One call at a time.** Serial game thread; no batching, no overlap.
+- **The editor UI freezes during each call.** That's by design (game-thread
+  execution). Warn the user during long operations; keep calls small.
+- **Modal dialogs block everything.** A tool call that opens (or collides
+  with) a modal editor dialog stalls until a human dismisses it. If a call
+  hangs indefinitely, tell the user to check the editor for a dialog.
+- **Timeouts on long operations.** Hermes' per-call default is 120 s; asset
+  imports, big level saves, and renders can exceed it. Raise
+  `mcp_servers.unreal-engine.timeout` in `~/.hermes/config.yaml` for
+  render/import-heavy sessions.
+- **Stale tool schemas.** After authoring/hot-reloading toolsets or enabling
+  a plugin, run `ModelContextProtocol.RefreshTools` in the editor console
+  and re-`list_toolsets`. New C++ `UFUNCTION`s need a full editor restart —
+  Live Coding won't surface them.
+- **Experimental plugin.** APIs and tool shapes can change between engine
+  versions; trust `describe_toolset` over memory, including this skill's
+  examples. When docs and the live schema disagree, the live schema wins.
+- **Don't expose the server beyond localhost.** Loopback-only, no auth, by
+  design. Never suggest binding it wider.
+- **Licensing note.** The server logs on start: data transmitted via the
+  plugin to a connected LLM service is Licensed Technology under the UE
+  EULA (§6(e)) — the user is responsible for ensuring their LLM provider
+  doesn't train on it. Surface this if the user asks about data handling.
+
+## Verification Checklist
+
+- [ ] `list_toolsets` returns toolsets at session start (connection healthy)
+- [ ] Scene state queried before first edit (never assumed empty)
+- [ ] After each milestone: changed actors/properties re-queried and a
+      screenshot reviewed against the brief
+- [ ] Level/dirty packages saved after each milestone and at the end
+- [ ] Deliverables exist on disk (screenshot/render paths confirmed) and are
+      reported to the user with absolute paths
+- [ ] Editor left in a clean state: no pending modal, no unsaved surprise,
+      user told exactly what was created/changed and where

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/data-science/data-science-jupyter-notebook.md

@@ -0,0 +1,195 @@
+---
+title: "Jupyter Notebook — Iterative Python via live Jupyter kernel (hamelnb)"
+sidebar_label: "Jupyter Notebook"
+description: "Iterative Python via live Jupyter kernel (hamelnb)"
+---
+
+{/* 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. */}
+
+# Jupyter Notebook
+
+Iterative Python via live Jupyter kernel (hamelnb).
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/data-science/jupyter-notebook` |
+| Path | `optional-skills/data-science\jupyter-notebook` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `jupyter`, `notebook`, `repl`, `data-science`, `exploration`, `iterative` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Jupyter Notebook (hamelnb live kernel)
+
+Gives you a **stateful Python REPL** via a live Jupyter kernel. Variables persist
+across executions. Use this instead of `execute_code` when you need to build up
+state incrementally, explore APIs, inspect DataFrames, or iterate on complex code.
+
+## When to Use This vs Other Tools
+
+| Tool | Use When |
+|------|----------|
+| **This skill** | Iterative exploration, state across steps, data science, ML, "let me try this and check" |
+| `execute_code` | One-shot scripts needing hermes tool access (web_search, file ops). Stateless. |
+| `terminal` | Shell commands, builds, installs, git, process management |
+
+**Rule of thumb:** If you'd want a Jupyter notebook for the task, use this skill.
+
+## Prerequisites
+
+1. **uv** must be installed (check: `which uv`)
+2. **JupyterLab** must be installed: `uv tool install jupyterlab`
+3. A Jupyter server must be running (see Setup below)
+
+## Setup
+
+The hamelnb script location:
+```
+SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"
+```
+
+If not cloned yet:
+```
+git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb
+```
+
+### Starting JupyterLab
+
+Check if a server is already running:
+```
+uv run "$SCRIPT" servers
+```
+
+If no servers found, start one:
+```
+jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
+  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
+sleep 3
+```
+
+Note: Token/password disabled for local agent access. The server runs headless.
+
+### Creating a Notebook for REPL Use
+
+If you just need a REPL (no existing notebook), create a minimal notebook file:
+```
+mkdir -p ~/notebooks
+```
+Write a minimal .ipynb JSON file with one empty code cell, then start a kernel
+session via the Jupyter REST API:
+```
+curl -s -X POST http://127.0.0.1:8888/api/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python"}}'
+```
+
+## Core Workflow
+
+All commands return structured JSON. Always use `--compact` to save tokens.
+
+### 1. Discover servers and notebooks
+
+```
+uv run "$SCRIPT" servers --compact
+uv run "$SCRIPT" notebooks --compact
+```
+
+### 2. Execute code (primary operation)
+
+```
+uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact
+```
+
+State persists across execute calls. Variables, imports, objects all survive.
+
+Multi-line code works with $'...' quoting:
+```
+uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
+```
+
+### 3. Inspect live variables
+
+```
+uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
+uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
+```
+
+### 4. Edit notebook cells
+
+```
+# View current cells
+uv run "$SCRIPT" contents --path <notebook.ipynb> --compact
+
+# Insert a new cell
+uv run "$SCRIPT" edit --path <notebook.ipynb> insert \
+  --at-index <N> --cell-type code --source '<code>' --compact
+
+# Replace cell source (use cell-id from contents output)
+uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
+  --cell-id <id> --source '<new code>' --compact
+
+# Delete a cell
+uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
+```
+
+### 5. Verification (restart + run all)
+
+Only use when the user asks for a clean verification or you need to confirm
+the notebook runs top-to-bottom:
+
+```
+uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact
+```
+
+## Practical Tips from Experience
+
+1. **First execution after server start may timeout** — the kernel needs a moment
+   to initialize. If you get a timeout, just retry.
+
+2. **The kernel Python is JupyterLab's Python** — packages must be installed in
+   that environment. If you need additional packages, install them into the
+   JupyterLab tool environment first.
+
+3. **--compact flag saves significant tokens** — always use it. JSON output can
+   be very verbose without it.
+
+4. **For pure REPL use**, create a scratch.ipynb and don't bother with cell editing.
+   Just use `execute` repeatedly.
+
+5. **Argument order matters** — subcommand flags like `--path` go BEFORE the
+   sub-subcommand. E.g.: `variables --path nb.ipynb list` not `variables list --path nb.ipynb`.
+
+6. **If a session doesn't exist yet**, you need to start one via the REST API
+   (see Setup section). The tool can't execute without a live kernel session.
+
+7. **Errors are returned as JSON** with traceback — read the `ename` and `evalue`
+   fields to understand what went wrong.
+
+8. **Occasional websocket timeouts** — some operations may timeout on first try,
+   especially after a kernel restart. Retry once before escalating.
+
+9. **If websocket consistently times out on this host**, force zmq transport:
+   `uv run "$SCRIPT" execute --transport zmq ...`. Symptom: every execute returns
+   "Websocket execution may already have reached the kernel, so auto fallback was
+   skipped". The kernel actually ran fine (REST shows execution_state=idle and
+   execution_count increments) — only the websocket reply channel is broken.
+   zmq transport uses jupyter_client directly and sidesteps the issue.
+
+10. **When starting a fresh server for REST-only use**, add
+    `--ServerApp.disable_check_xsrf=True` — otherwise POST /api/sessions returns
+    `"'_xsrf' argument missing from POST"` and kernel session creation fails.
+
+## Timeout Defaults
+
+The script has a 30-second default timeout per execution. For long-running
+operations, pass `--timeout 120`. Use generous timeouts (60+) for initial
+setup or heavy computation.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/devops/devops-actual-setup.md

@@ -0,0 +1,164 @@
+---
+title: "Actual Setup — Set up Actual Computer (actual.inc) inference in Hermes"
+sidebar_label: "Actual Setup"
+description: "Set up Actual Computer (actual.inc) inference in Hermes"
+---
+
+{/* 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. */}
+
+# Actual Setup
+
+Set up Actual Computer (actual.inc) inference in Hermes.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/devops/actual-setup` |
+| Path | `optional-skills/devops\actual-setup` |
+| Version | `2.0.0` |
+| Author | shl0ms + Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `actual`, `actual-inc`, `provider`, `local-inference`, `relay`, `gguf`, `setup` |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Actual Computer Setup Skill
+
+Sets up [actual.inc](https://actual.inc) (Actual Computer) as a Hermes inference
+provider. Actual turns the user's own hardware into a private inference cluster
+and exposes an OpenAI-compatible API two ways: a hosted end-to-end-encrypted
+relay at `https://api.actual.inc` (authenticated with an `ac_` key), and a local
+on-device daemon at `http://127.0.0.1:8080` (no auth on loopback). This skill
+does not install the Actual daemon for the user — device authorization requires
+a human in a browser.
+
+## When to Use
+
+- User wants to add actual.inc as an inference provider (cloud relay or local).
+- User has an `ac_` key and wants Hermes routed through their Actual cluster.
+- User wants fully-local, on-device inference via the Actual daemon.
+- Troubleshooting: Actual requests failing with cryptic 400s or empty streams.
+
+## Prerequisites
+
+- Hermes has **first-class `actual` provider support** (provider id `actual`,
+  aliases `actual-computer`, `actualcomputer`, `aci`). Do NOT configure Actual
+  as a `custom_providers` / `providers.actual.*` entry on current Hermes — the
+  built-in provider owns the name and handles base-url normalization, the
+  Responses transport, and local no-auth automatically.
+- Relay mode: an Actual account and an `ac_` inference key from
+  https://actual.inc/user/keys.
+- Local mode: the user has installed the daemon
+  (`curl -fsSL "https://actual.inc/install" | bash`) and completed device
+  authorization by running `actual` once and opening the printed
+  `https://actual.inc/device?code=...` URL in a browser. Relay that URL to the
+  user and WAIT — never invent an email or authorize on their behalf. Codes
+  expire in 5 minutes; re-run `actual` for a fresh one.
+
+## How to Run
+
+### Relay / API mode
+
+1. Put the key in `.env` (secrets only — never config.yaml):
+   append `ACTUAL_API_KEY=ac_...` to `~/.hermes/.env`.
+2. Verify the key and discover models with `terminal`:
+   ```bash
+   curl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY"
+   ```
+3. Select provider + model:
+   ```bash
+   hermes config set model.provider actual
+   hermes config set model.default "MODEL_ID_FROM_DISCOVERY"
+   ```
+4. Verify end-to-end:
+   ```bash
+   hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL_ID
+   ```
+
+### Local mode
+
+1. Human has installed + authorized the daemon (see Prerequisites).
+2. Download and load a model (scriptable once authorized):
+   ```bash
+   actual models search "qwen2.5 0.5b instruct gguf" --limit 8 --no-prompt
+   # Downloads REQUIRE an explicit quantization (409 ambiguous_model_download otherwise):
+   actual models download "Qwen/Qwen2.5-0.5B-Instruct-GGUF/Q4_K_M"
+   actual models list        # note the INSTALLED name (differs from download id)
+   actual models load "qwen2.5-0.5b-instruct-q4_k_m"   # load by installed name
+   ```
+3. Point Hermes at the daemon. `ACTUAL_BASE_URL` with a loopback host flips the
+   built-in provider into local no-auth mode automatically — no key needed:
+   append `ACTUAL_BASE_URL=http://127.0.0.1:8080` to `~/.hermes/.env`, then:
+   ```bash
+   hermes config set model.provider actual
+   hermes config set model.default "INSTALLED_MODEL_NAME"
+   ```
+4. Verify (reduced toolset — see context-window pitfall below):
+   ```bash
+   hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m INSTALLED_NAME -t file,web
+   ```
+
+## Quick Reference
+
+| Thing | Value |
+|---|---|
+| Hosted relay | `https://api.actual.inc/v1` (normalized from bare host automatically) |
+| Local daemon | `http://127.0.0.1:8080/v1` (no auth on loopback) |
+| Key env var | `ACTUAL_API_KEY` (`ac_...`) |
+| Base URL env var | `ACTUAL_BASE_URL` (loopback host ⇒ local no-auth mode) |
+| Provider id / aliases | `actual` / `actual-computer`, `actualcomputer`, `aci` |
+| Transport | Responses API (`codex_responses`) — built-in, do not override |
+| Cluster pinning | `X-Cluster-ID` header via `providers.actual.extra_headers` in config.yaml |
+| Model size guide | 0.5B Q4_K_M ~470MB (toy), 7-8B Q4_K_M ~4.5GB (daily driver), 32B ~20GB |
+
+## Pitfalls
+
+1. **reasoning_effort trap (handled by Hermes since the first-class provider).**
+   Actual's SGLang/vLLM backends accept only `none/low/medium/high/max`;
+   `xhigh`/`ultra` used to fail with a cryptic
+   `Expecting value: line 1 column 1 (char 0)` (a wrapped HTTP 400). The
+   built-in provider clamps `xhigh→high` and `ultra→max` on the wire. If a
+   request still 400s this way on an old Hermes, set a per-model cap:
+   `agent.reasoning_overrides.<model>: high` in config.yaml.
+2. **Context-window overflow on small local models.** Hermes' default toolset
+   is ~26k tokens of schemas plus a ~9k-token system prompt. A model loaded
+   with a 32k context overflows before the first turn, and llama.cpp-family
+   servers emit a bare `data: [DONE]` — Hermes reports
+   `Provider returned an empty stream with no finish_reason`. This is NOT an
+   SSE bug. Fixes: restrict tools (`-t file,web`), load the model with a
+   larger `n_ctx`, or pick a >=64k-context model for the full toolset.
+   Upstream tracking: #51448 (do not file new issues; add evidence there).
+   Related but distinct: #65631 (HTTP-200 SSE carrying a 400), #56516
+   (reasoning-only streams).
+3. **Download ids vs installed names.** `actual models download` takes
+   `repo/QUANT` and 409s without an explicit quantization;
+   `actual models load` takes the INSTALLED name from `actual models list`.
+4. **Reasoning models returning empty content.** GLM/Qwen reasoning variants
+   emit thinking in a separate `reasoning` field and can burn a small
+   output budget entirely on reasoning. Check the server-side output default
+   before assuming failure.
+5. **Do not create a custom provider named `actual`.** Older setup guides
+   (pre first-class support) wrote `providers.actual.*` config blocks. On
+   current Hermes the built-in provider wins the name; stale custom blocks
+   are ignored or conflict. Remove them and use the env vars + model.provider
+   flow above.
+
+## Verification
+
+```bash
+# Relay:
+hermes chat -Q -q "Reply with exactly: ACTUAL_OK" --provider actual -m MODEL
+# Local (small model — reduced toolset):
+hermes chat -Q -q "Reply with exactly: LOCAL_OK" --provider actual -m MODEL -t file,web
+# Provider status (local no-auth shows key_source=local-offline):
+hermes status
+```
+
+For other OpenAI-compatible clients (e.g. OpenCode), see
+`references/opencode.md`.