better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md

@@ -0,0 +1,230 @@
+---
+title: "Hermes Agent — Use, configure, theme, extend, and orchestrate Hermes Agent"
+sidebar_label: "Hermes Agent"
+description: "Use, configure, theme, extend, and orchestrate Hermes Agent"
+---
+
+{/* 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. */}
+
+# Hermes Agent
+
+Use, configure, theme, extend, and orchestrate Hermes Agent.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/autonomous-ai-agents\hermes-agent` |
+| Version | `3.2.0` |
+| Author | Hermes Agent + Teknium |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `hermes`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |
+| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |
+
+## 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.
+:::
+
+# Hermes Agent
+
+Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.
+
+What makes Hermes different:
+
+- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills that load into future sessions.
+- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
+- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
+- **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
+- **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
+- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
+- **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.
+
+**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.
+
+**Docs:** https://hermes-agent.nousresearch.com/docs/
+
+## Scope & Verification
+
+This skill is a concise operating guide, not the complete source of truth for every Hermes feature. If a Hermes feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.
+
+Good verification targets, cheapest first:
+
+- **Every shipped feature, one line each: https://hermes-agent.nousresearch.com/docs/llms.txt.** Start here for any "can Hermes do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://hermes-agent.nousresearch.com/docs/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.
+- CLI commands: `hermes --help`, `hermes <command> --help`, and `hermes_cli/main.py`
+- Source tree: https://github.com/NousResearch/hermes-agent
+
+Never answer "Hermes can't do that" from memory. Hermes ships far more than this skill body describes, and the index exists so a negative answer is always checkable.
+
+## Quick Start
+
+```bash
+# Install (shell installer — sets up uv, Python, the venv, and the launcher)
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+
+# Interactive chat (default surface; set display.interface: tui to launch the Ink TUI instead)
+hermes
+
+# Single query
+hermes chat -q "What is the capital of France?"
+
+# Setup wizard  /  pick model+provider  /  health check
+hermes setup
+hermes model
+hermes doctor
+
+# Other surfaces
+hermes desktop                 # launch the native desktop app (alias: hermes gui)
+hermes dashboard               # web admin panel + embedded chat
+hermes proxy                   # OpenAI-compatible local proxy backed by your OAuth provider
+```
+
+## Key Paths
+
+```
+~/.hermes/config.yaml       Main configuration (settings — never secrets)
+~/.hermes/.env              API keys and secrets ONLY (under $HERMES_HOME if set)
+$HERMES_HOME/skills/        Installed skills
+~/.hermes/skins/            Custom themes (see references/themes.md)
+~/.hermes/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
+~/.hermes/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
+~/.hermes/pets/             Installed pet mascots (see references/petdex.md)
+~/.hermes/state.db          Canonical session store (SQLite + FTS5)
+~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
+~/.hermes/logs/             Gateway and error logs
+~/.hermes/auth.json         OAuth tokens and credential pools
+~/.hermes/hermes-agent/     Source code (if git-installed)
+```
+
+Profiles use `~/.hermes/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$HERMES_HOME` — never hardcode `~/.hermes`.
+
+## Routing Table — load the reference for the task
+
+| User wants... | Load |
+|---|---|
+| **Anything not listed below — "can Hermes do X?", "how do I set up X?"** | **https://hermes-agent.nousresearch.com/docs/llms.txt** |
+| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |
+| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
+| In-session slash commands | `references/slash-commands.md` |
+| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
+| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
+| AGENTS.md / .hermes.md / CLAUDE.md project rules | `references/project-context-files.md` |
+| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
+| Delegation, cron, curator, kanban | `references/background-systems.md` |
+| MCP servers (add, catalog, `hermes mcp`) | `references/native-mcp.md` |
+| Webhook routes and event-driven runs | `references/webhooks.md` |
+| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
+| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
+| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
+| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
+| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
+| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
+| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
+| delegate_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
+| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
+| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |
+
+The reference list above is not the feature list — it is the set of topics that
+need more than their docs page. For everything else Hermes ships, fetch
+`llms.txt` and it maps the question to the page that answers it.
+
+Two theming rules that hold even without loading the reference: **you apply skins yourself** (`hermes config set display.skin <name>` — every surface repaints live within ~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`hermes skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.
+
+## Spawning Additional Hermes Instances
+
+Run additional Hermes processes as fully independent subprocesses — separate sessions, tools, and environments.
+
+### When to Use This vs delegate_task
+
+| | `delegate_task` | Spawning `hermes` process |
+|-|-----------------|--------------------------|
+| Isolation | Separate conversation, shared process | Fully independent process |
+| Duration | Minutes (bounded by parent loop) | Hours/days |
+| Tool access | Subset of parent's tools | Full tool access |
+| Interactive | No | Yes (PTY mode) |
+| Use case | Quick parallel subtasks | Long autonomous missions |
+
+### One-Shot Mode
+
+```
+terminal(command="hermes chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)
+
+# Background for long tasks:
+terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
+```
+
+### Interactive PTY Mode (via tmux)
+
+Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
+
+```
+# Start
+terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)
+
+# Wait for startup, then send a message
+terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)
+
+# Read output
+terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)
+
+# Send follow-up
+terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)
+
+# Exit
+terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
+```
+
+### Multi-Agent Coordination
+
+```
+# Agent A: backend
+terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
+terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)
+
+# Agent B: frontend
+terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
+terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)
+
+# Check progress, relay context between them
+terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
+terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
+```
+
+### Session Resume
+
+```
+# Resume most recent session
+terminal(command="tmux new-session -d -s resumed 'hermes --continue'", timeout=10)
+
+# Resume specific session
+terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_143052_a1b2c3'", timeout=10)
+```
+
+### Tips
+
+- **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process
+- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
+- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
+- **Use `hermes chat -q` for fire-and-forget** — no PTY needed
+- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
+- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
+- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
+- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
+
+## Surfaces (quick orientation)
+
+- **Desktop app** (`hermes desktop` / `hermes gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
+- **Web dashboard** (`hermes dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `hermes --tui` chat. Secured behind an OAuth/token gate.
+- **Ink TUI** (`hermes --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
+- **OpenAI-compatible proxy** (`hermes proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.
+
+## Hard Invariants (never violate, regardless of what you loaded)
+
+- **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
+- **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
+- **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
+- **Profile-safe paths** — `get_hermes_home()` in code, `$HERMES_HOME` when resolving paths in a session.
+- **Never hand-edit `config.yaml` for the user** — use `hermes config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-merge-reconciler.md

@@ -0,0 +1,176 @@
+---
+title: "Merge Reconciler — Neutral third-party resolution of agent merge conflicts"
+sidebar_label: "Merge Reconciler"
+description: "Neutral third-party resolution of agent merge conflicts"
+---
+
+{/* 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. */}
+
+# Merge Reconciler
+
+Neutral third-party resolution of agent merge conflicts.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/autonomous-ai-agents\merge-reconciler` |
+| Version | `1.0.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Multi-Agent`, `Git`, `Merge-Conflict`, `Kanban`, `Arbitration` |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+
+## 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.
+:::
+
+# Merge Reconciler
+
+Resolve a git merge conflict between two AGENTS' branches as an impartial third
+party. Agents resolving conflicts against a peer's work reliably either
+overwrite the peer or abandon their own change — they lack the peer's context
+and are biased toward their own side. This skill is the fix: a neutral
+reconciler that receives both diffs plus both sides' stated intents and
+produces a merged result, like a merge-queue arbiter.
+
+## When to Use
+
+- Two agent branches/worktrees collide during a parallel campaign (kanban
+  engineering pipeline, parallel-PR wave, multi-worktree refactor).
+- `git merge` or `git rebase` halts on conflicts between two agents' work and
+  neither original agent should self-adjudicate.
+- Do NOT use for conflicts within a single agent's own work, or for trivial
+  lockfile/generated-file conflicts (regenerate those instead).
+
+## Prerequisites
+
+- A repo checkout containing the halted merge, or the two branch names plus
+  permission to run the merge yourself.
+- Both sides' intent sources: kanban completion summaries (`terminal` running
+  `hermes kanban show <task-id>`), PR bodies, or at minimum each branch's
+  commit messages.
+- The project's build/test command, if one exists.
+
+## How to Run
+
+**Standalone** — a human (or agent) invokes this skill inside the conflicted
+repo: load the skill, then follow the Procedure top to bottom.
+
+**Spawned neutral agent** — the preferred shape in multi-agent campaigns:
+
+- `delegate_task`: spawn a subagent whose task message contains the repo path,
+  both branch names, and both sides' intent summaries verbatim, plus an
+  instruction to follow this skill.
+- Kanban-native: create a reconciliation card assigned to a **third profile**
+  (not either worker's profile) with BOTH conflicted cards linked as parents —
+  `kanban_create(title="reconcile branch-a x branch-b", assignee="reconciler",
+  parents=["t_a", "t_b"])`. The parent links carry both sides' completion
+  summaries into the reconciler's context automatically; the card body should
+  name the repo path and the two branches.
+
+## Quick Reference
+
+| Hunk class | Definition | Resolution |
+|---|---|---|
+| disjoint-intent | The two changes serve different goals and can coexist | Combine both |
+| same-question-different-answer | Both sides answered one design question differently | Pick ONE per stated intents; surface the decision |
+| superseded | One side's premise no longer holds after the other's change | Keep the surviving side; note why |
+
+Impartiality contract: never favor the side that spawned you; touch ONLY
+conflicted regions (no drive-by edits); every design-question pick must appear
+explicitly in the hand-back summary.
+
+## Procedure
+
+### 1. Gather both sides
+
+- Run via `terminal`: `git status` (confirm the conflicted state and list
+  conflicted files), `git merge-base <A> <B>`, then for each side
+  `git log --oneline <base>..<side>` and `git diff <base>..<side> -- <file>`
+  for every conflicted file. In a halted merge, `HEAD` is one side and
+  `MERGE_HEAD` is the other.
+- Collect each side's intent: `hermes kanban show <task-id>` for completion
+  summaries/metadata, or the PR body, or the commit messages from the log
+  above. Write down one sentence of intent per side before touching any file.
+- Done when: you can state both intents in your own words and have both diffs
+  for every conflicted file.
+
+### 2. Classify every conflicted hunk
+
+- Open each conflicted file with `read_file` and locate each
+  `<<<<<<<`/`=======`/`>>>>>>>` block.
+- Assign each hunk exactly one class from the Quick Reference table, judging
+  by the stated intents — not by which change looks nicer.
+- If a single hunk contains multiple independent decisions (e.g., new logic
+  that combines cleanly PLUS a styling/rounding choice both sides answered
+  differently), decompose it into sub-decisions and classify each one.
+- A single file often mixes classes: one hunk may be a design collision while
+  a neighboring hunk is disjoint. Classify per hunk, not per file.
+- Done when: every hunk has a written class and a one-line rationale.
+
+### 3. Resolve under the impartiality contract
+
+- Edit each hunk with `patch` (or `write_file` for whole-file rewrites):
+  - disjoint-intent → merge both changes so each intent is fully served.
+  - same-question-different-answer → pick the answer that best serves the
+    STATED intents (e.g., an intent of "strict validation" beats "quick
+    default" if the task required correctness). Never split the difference
+    into a hybrid neither side asked for.
+  - superseded → keep the surviving side; delete the dead premise.
+- Never favor the side that spawned you. If intents genuinely tie, escalate
+  (block the kanban card / report back) rather than guess.
+- Change nothing outside conflict markers — no formatting, renames, or
+  opportunistic fixes.
+- `git add` each resolved file via `terminal`.
+- Done when: `search_files` finds no `<<<<<<<` markers in the repo and every
+  resolved file is staged.
+
+### 4. Verify
+
+- Run the project's build/tests via `terminal`; at minimum import/execute the
+  touched modules. Both intents must be observable in the merged behavior
+  (e.g., side A's new semantics AND side B's disjoint addition both present).
+- Complete the merge: `git commit` (the default merge message plus a body
+  listing hunk decisions is fine).
+- Done when: verification passes and the merge commit exists.
+
+### 5. Hand back
+
+- Produce a completion summary naming EVERY hunk decision:
+  `file:lines — class — which side(s) kept — rationale`. For every
+  same-question-different-answer hunk, state the design question and the
+  answer you picked so a human can veto it — never bury a design call.
+- Kanban: `kanban_complete(summary=...)`. Standalone: print the summary.
+- Done when: the summary is delivered and lists all hunks.
+
+## Pitfalls
+
+- **Self-favoring**: if you were spawned by one of the conflicting agents,
+  you are structurally biased — state this and weigh the other side's intent
+  deliberately. Prefer the third-profile shape so this never arises.
+- **Splitting the difference** on a design collision produces a hybrid nobody
+  designed; pick one answer and surface it.
+- **Per-file classification**: files usually mix hunk classes; classifying a
+  whole file as one class silently drops a disjoint change.
+- **Drive-by edits** make the merge unreviewable and steal decisions from the
+  original agents.
+- **Missing intents**: commit messages alone can be thin; prefer kanban
+  completion summaries or PR bodies. If neither side's intent is recoverable,
+  escalate instead of guessing.
+- **Repeat offenders**: repeated conflicts on the SAME file across rounds are
+  a hotspot signal, not routine reconciliation work — flag it (e.g. a
+  `hotspot: <path> — <reason>` kanban comment) so the orchestrator decomposes
+  that file, rather than serially reconciling every new collision on it.
+
+## Verification
+
+- `git status` shows a clean tree on the target branch with a merge commit.
+- No conflict markers remain (`search_files` pattern `<<<<<<<`).
+- Build/tests pass; both sides' intents are demonstrably present or the
+  dropped one is explicitly named in the summary.
+- The hand-back summary enumerates every hunk with class and rationale.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode.md

@@ -0,0 +1,237 @@
+---
+title: "Opencode — Delegate coding to OpenCode CLI (features, PR review)"
+sidebar_label: "Opencode"
+description: "Delegate coding to OpenCode CLI (features, PR review)"
+---
+
+{/* 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. */}
+
+# Opencode
+
+Delegate coding to OpenCode CLI (features, PR review).
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/autonomous-ai-agents\opencode` |
+| Version | `1.2.0` |
+| Author | Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Coding-Agent`, `OpenCode`, `Autonomous`, `Refactoring`, `Code-Review` |
+| Related skills | [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent) |
+
+## 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.
+:::
+
+# OpenCode CLI
+
+Use [OpenCode](https://opencode.ai) as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.
+
+## When to Use
+
+- User explicitly asks to use OpenCode
+- You want an external coding agent to implement/refactor/review code
+- You need long-running coding sessions with progress checks
+- You want parallel task execution in isolated workdirs/worktrees
+
+## Prerequisites
+
+- OpenCode installed: `npm i -g opencode-ai@latest` or `brew install anomalyco/tap/opencode`
+- Auth configured: `opencode auth login` or set provider env vars (OPENROUTER_API_KEY, etc.)
+- Verify: `opencode auth list` should show at least one provider
+- Git repository for code tasks (recommended)
+- `pty=true` for interactive TUI sessions
+
+## Binary Resolution (Important)
+
+Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check:
+
+```
+terminal(command="which -a opencode")
+terminal(command="opencode --version")
+```
+
+If needed, pin an explicit binary path:
+
+```
+terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)
+```
+
+## One-Shot Tasks
+
+Use `opencode run` for bounded, non-interactive tasks:
+
+```
+terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")
+```
+
+Attach context files with `-f`:
+
+```
+terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")
+```
+
+Show model thinking with `--thinking`:
+
+```
+terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")
+```
+
+Force a specific model:
+
+```
+terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")
+```
+
+## Interactive Sessions (Background)
+
+For iterative work requiring multiple exchanges, start the TUI in background:
+
+```
+terminal(command="opencode", workdir="~/project", background=true, pty=true)
+# Returns session_id
+
+# Send a prompt
+process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")
+
+# Monitor progress
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+
+# Send follow-up input
+process(action="submit", session_id="<id>", data="Now add error handling for token expiry")
+
+# Exit cleanly — Ctrl+C
+process(action="write", session_id="<id>", data="\x03")
+# Or just kill the process
+process(action="kill", session_id="<id>")
+```
+
+**Important:** Do NOT use `/exit` — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (`\x03`) or `process(action="kill")` to exit.
+
+### TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Submit message (press twice if needed) |
+| `Tab` | Switch between agents (build/plan) |
+| `Ctrl+P` | Open command palette |
+| `Ctrl+X L` | Switch session |
+| `Ctrl+X M` | Switch model |
+| `Ctrl+X N` | New session |
+| `Ctrl+X E` | Open editor |
+| `Ctrl+C` | Exit OpenCode |
+
+### Resuming Sessions
+
+After exiting, OpenCode prints a session ID. Resume with:
+
+```
+terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # Continue last session
+terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # Specific session
+```
+
+## Common Flags
+
+| Flag | Use |
+|------|-----|
+| `run 'prompt'` | One-shot execution and exit |
+| `--continue` / `-c` | Continue the last OpenCode session |
+| `--session <id>` / `-s` | Continue a specific session |
+| `--agent <name>` | Choose OpenCode agent (build or plan) |
+| `--model provider/model` | Force specific model |
+| `--format json` | Machine-readable output/events |
+| `--file <path>` / `-f` | Attach file(s) to the message |
+| `--thinking` | Show model thinking blocks |
+| `--variant <level>` | Reasoning effort (high, max, minimal) |
+| `--title <name>` | Name the session |
+| `--attach <url>` | Connect to a running opencode server |
+
+## Procedure
+
+1. Verify tool readiness:
+   - `terminal(command="opencode --version")`
+   - `terminal(command="opencode auth list")`
+2. For bounded tasks, use `opencode run '...'` (no pty needed).
+3. For iterative tasks, start `opencode` with `background=true, pty=true`.
+4. Monitor long tasks with `process(action="poll"|"log")`.
+5. If OpenCode asks for input, respond via `process(action="submit", ...)`.
+6. Exit with `process(action="write", data="\x03")` or `process(action="kill")`.
+7. Summarize file changes, test results, and next steps back to user.
+
+## PR Review Workflow
+
+OpenCode has a built-in PR command:
+
+```
+terminal(command="opencode pr 42", workdir="~/project", pty=true)
+```
+
+Or review in a temporary clone for isolation:
+
+```
+terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)
+```
+
+## Parallel Work Pattern
+
+Use separate workdirs/worktrees to avoid collisions:
+
+```
+terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
+terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
+process(action="list")
+```
+
+## Session & Cost Management
+
+List past sessions:
+
+```
+terminal(command="opencode session list")
+```
+
+Check token usage and costs:
+
+```
+terminal(command="opencode stats")
+terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")
+```
+
+## Pitfalls
+
+- Interactive `opencode` (TUI) sessions require `pty=true`. The `opencode run` command does NOT need pty.
+- `/exit` is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
+- PATH mismatch can select the wrong OpenCode binary/model config.
+- If OpenCode appears stuck, inspect logs before killing:
+  - `process(action="log", session_id="<id>")`
+- Avoid sharing one working directory across parallel OpenCode sessions.
+- Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).
+
+## Verification
+
+Smoke test:
+
+```
+terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")
+```
+
+Success criteria:
+- Output includes `OPENCODE_SMOKE_OK`
+- Command exits without provider/model errors
+- For code tasks: expected files changed and tests pass
+
+## Rules
+
+1. Prefer `opencode run` for one-shot automation — it's simpler and doesn't need pty.
+2. Use interactive background mode only when iteration is needed.
+3. Always scope OpenCode sessions to a single repo/workdir.
+4. For long tasks, provide progress updates from `process` logs.
+5. Report concrete outcomes (files changed, tests, remaining risks).
+6. Exit interactive sessions with Ctrl+C or kill, never `/exit`.