quill: draft-hermes-quick-ref.md

wizard-work/quill/draft-hermes-quick-ref.md

@@ -0,0 +1,71 @@
+# Hermes Agent Quick Reference (Draft v0.1)
+> One-page cheat sheet for core Hermes tools. For full docs see https://hermes-agent.nousresearch.com/docs
+
+## Core Tools
+
+| Tool | Purpose |
+|------|---------|
+| `terminal(command)` | Run shell commands. |
+| `execute_code(code)` | Run Python with Hermes tool imports. |
+| `web_search(query)` | Search the web (returns up to 5). |
+| `web_extract(urls)` | Extract page content as markdown. |
+| `read_file(path)` | Read text files with pagination. |
+| `write_file(path, content)` | Overwrite a file (read first if existing). |
+| `patch(path, old_string, new_string)` | Targeted find-and-replace. |
+| `search_files(pattern)` | Ripgrep-backed content or filename search. |
+| `browser_exec(code)` | Drive a real browser via Python. |
+| `delegate_task(tasks)` | Spawn parallel subagents. |
+| `clarify(questions)` | Ask the user multiple questions in one form. |
+| `memory(action, target, ...)` | Persistent memory across sessions. |
+| `skill_view(name)` | Load a skill's full content and templates. |
+| `tool_search(queries)` | Find deferred tool schemas. |
+| `tool_call(calls)` | Invoke deferred tools. |
+| `manage_connections(...)` | Hosted connectors and MCP servers. |
+
+## Common Patterns
+
+### Shell
+- Foreground: `terminal("ls -la /root")`
+- Background: `terminal("python server.py", background=True, notify=True)`
+- Timeout override: `terminal("long-task", timeout=600)`
+
+### Files
+- Read: `read_file("/path/to/file", offset=1, limit=2000)`
+- Write: `read_file(path) first, then write_file(path, content)`
+- Edit: `patch(path, "OLD", "NEW")` (fuzzy match, unique required)
+
+### Code Execution
+```python
+from hermes_tools import web_search, terminal
+print(web_search("hermes agent docs", limit=3)["data"]["web"])
+```
+
+### Delegation
+- One task: `delegate_task([{"goal": "Do X", "context": "..."}])`
+- Parallel: multiple entries in `tasks` array
+- Live control: `delegate_task(action="list")` or `"steer"`
+
+### Browser
+- First nav: `new_tab("https://example.com")`
+- Subsequent: `goto_url(url)`
+- Extract text: `js("document.body.innerText")`
+- Screenshot: `capture_screenshot()`
+
+## Flags Cheat Sheet
+
+| Flag | Tool | Effect |
+|------|------|--------|
+| `background=True` | terminal | Returns session_id immediately |
+| `notify=['pattern']` | terminal | Notify on line match |
+| `pty=True` | terminal | Interactive REPL support |
+| `persist_on_release=True` | terminal | Survive session end |
+| `timeout=N` | terminal, browser_exec | Max seconds (600+ = tracked bg) |
+| `file_glob="*.py"` | search_files | Filter files by extension |
+| `output_mode="files_only"` | search_files | Return paths only |
+| `char_limit=N` | web_extract | Per-page budget (min 2000) |
+
+## Rules
+- Evidence only: measured > claimed. No fabricated results.
+- One artifact per lane call. Commit to troupe repo when done.
+- CHECK command must be a real test, not a tautology.
+- Memory budget: 2200 chars. Save durable facts only.