better-dsh 0.2.5 → 0.3.0

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

@@ -1,269 +0,0 @@
----
-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

@@ -1,195 +0,0 @@
----
-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

@@ -1,164 +0,0 @@
----
-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`.