better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/optional/autonomous-ai-agents/autonomous-ai-agents-dynamic-workflow.md

@@ -0,0 +1,198 @@
+---
+title: "Dynamic Workflow — Plan-in-code fan-outs, adversarial verification, waves"
+sidebar_label: "Dynamic Workflow"
+description: "Plan-in-code fan-outs, adversarial verification, waves"
+---
+
+{/* 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. */}
+
+# Dynamic Workflow
+
+Plan-in-code fan-outs, adversarial verification, waves.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/dynamic-workflow` |
+| Path | `optional-skills/autonomous-ai-agents/dynamic-workflow` |
+| Version | `2.0.0` |
+| Author | Teknium + Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `orchestration`, `fan-out`, `subagents`, `delegation`, `verification`, `migration`, `audit`, `research`, `campaign` |
+| Related skills | [`hermes-agent`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`simplify-code`](/docs/user-guide/skills/bundled/software-development/software-development-simplify-code) |
+
+## 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.
+:::
+
+# Dynamic Workflow Skill
+
+Runs large fan-out work as a workflow: the plan, the loop and every intermediate
+result live in a script and on disk, so the parent's context holds only verified
+results. Covers one-shot fan-outs, adversarial convergence (attempts + refuters),
+and multi-wave campaigns that integrate dozens of worker branches. It does not
+make `delegate_task` durable across restarts; that is the kanban swarm's job.
+
+## When to Use
+
+Reach for it when the unit of work is clear (a file, an endpoint, a record) and
+there are more units than one context can hold. Skip it for under ~10 units or
+for serial chains. For a refactor or fix campaign on hermes-agent itself, load
+`hermes-agent` (the dev workflow) alongside; this skill owns the fan-out shape.
+
+## Prerequisites
+
+- `delegate_task` available and `delegation.max_concurrent_children` sized for
+  the wave (default 10; the runtime rejects a `tasks=[]` larger than that with a
+  clear error rather than queueing). `delegation.max_spawn_depth >= 2` only if
+  children must fan out themselves.
+- A writable run directory resolved from the terminal environment's temp dir
+  (`$TMPDIR`, else the platform temp dir). Never a literal `/tmp`: Termux has no
+  `/tmp`, native Windows breaks on it. Use `<tmp>/wf_<name>_<uuid>/`, unique per
+  run, so an interrupted earlier run cannot leave stale outputs to be misread.
+- `execute_code` for the deterministic layer (only `web_search`, `web_extract`,
+  `read_file`, `write_file`, `search_files`, `terminal`, `patch` exist inside it).
+
+## How to Run
+
+Two layers, split by a real capability boundary:
+
+| | Layer A - `execute_code` script | Layer B - `delegate_task` batch |
+|---|---|---|
+| Use for | DETERMINISTIC work: fetch N URLs, parse N files, run N commands, template N outputs, build manifests, merge outputs | LLM-JUDGMENT work: classify, review, decide, write, refute, refactor one unit |
+| Holds | loop, branching, intermediate variables | nothing; one call with `tasks=[...]`, each task its own isolated agent |
+| Tools | the sandbox set above; it can NOT call `delegate_task` | the parent's toolsets, inherited unchanged (no per-task narrowing); children lose `delegate_task`, `clarify`, `memory`, `send_message`, `cronjob_manage` |
+| Concurrency | yours (`ThreadPoolExecutor`, batches) | bounded by `delegation.max_concurrent_children` |
+| Cost | tool calls only | one full agent tree per task; multiplies linearly |
+
+Do the deterministic part in Layer A first, fan out only the irreducibly-LLM
+step in Layer B, synthesize on the parent.
+
+### Background-first: results re-enter as messages
+
+A top-level `delegate_task` returns immediately with one handle per task; each
+child's result re-enters the conversation as a new message when it finishes. You
+cannot read `out_*.csv` on the line after the call. Finish whatever does not
+depend on the children, give a one-line status, and END YOUR TURN; act on each
+result message as it lands. An ordinary follow-up user message does not cancel
+children; `/stop`, `/new` and process exit do. Only a delegation issued by an
+orchestrator subagent (depth > 0) is synchronous.
+
+## Quick Reference
+
+- Unit must be answerable without sibling output, else it is serial.
+- Manifest: one unit per line in `<run>/manifest.jsonl`; print count + run dir.
+- Per child: ~8-12 mechanical edits, or ~2-3k lines of reading, or ~50-70 KB of
+  corpus; size by the LARGEST unit. Structured output goes to files, never the
+  `summary` field (it truncates under load); delimiter-separated lines over JSON.
+- Parent verifies file count and per-run freshness before merging.
+- A "stalled" child usually completed its write; check the filesystem first.
+- Scoped slice first (one directory, 20 records), report token cost, then scale.
+
+## Procedure
+
+### One-shot fan-out
+
+1. Decompose into independent units.
+2. Layer A pre-pass writes the manifest.
+3. Size chunks against the limits above; for more tasks than
+   `max_concurrent_children`, issue bounded waves yourself.
+4. Layer B: one `delegate_task(tasks=[...])`; each task reads its slice, writes
+   `<run>/out_<i>.csv`, prints a status word, stops.
+5. End the turn. As result messages arrive, read the files, verify, merge; the
+   cross-cutting synthesis stays on the parent.
+
+### Adversarial convergence (finding-quality work)
+
+1. Independent attempts: the SAME question to N children (2-4) with DIFFERENT
+   framings in each `context`, each writing one claim per line to
+   `<run>/attempt_<i>.md`. Located, individually falsifiable claims only
+   ("`POST /api/users/:id/role` in `src/routes/users.ts:142` has no role check");
+   a refuter cannot break "the auth layer has problems".
+2. Merge and dedupe on the parent; note the agreement count per claim.
+3. Refuters: a second batch told to BREAK each claim with counter-evidence,
+   emitting `claim_idx|survives|counter_evidence`. Give them the sources, not the
+   attempts' reasoning.
+4. Surface only survivors; drop refuted claims with a one-line reason.
+5. Feed new claims from round 2 through one more refutation; stop when a round
+   adds no survivors, cap at 3 rounds.
+
+The same mechanic protects the parent from its own wrong premises: when you
+hand children a heuristic ("every patch target on a facade is a dead seam"),
+tell them to refute it with evidence before acting on it. Four squads doing so
+turned a 647-site blanket rewrite into 59 real fixes and saved 130+ green tests.
+
+### Campaign shape (dozens of workers, several waves, hours)
+
+The one-shot recipe does not scale to a whole-codebase pass. What did:
+
+1. Measure first (LOC, hotspots, dead symbols, oracle corpora) and write ONE
+   shared `BRIEF.md` plus a per-cluster `task_<cluster>.md`. Every child reads
+   both. When the fleet drifts (children shaving docstrings instead of cutting
+   code), patch the brief once and steer; re-dispatched children inherit the fix.
+2. Exclusive ownership: one cluster of files per worker, edits outside it are
+   discarded at integration. Sub-fan-outs inside one file own line RANGES and
+   define helpers inside their range so diffs merge cleanly.
+3. Commit per verified step, locally, no push, no PR, no rebase from children.
+   Committed state is the only handoff; every worker that died mid-campaign lost
+   exactly its uncommitted tail. A worker sharing a worktree index commits with
+   `git commit -- <paths>` only; a bare commit swept a sibling's staged hunks.
+4. Fleet size 12-16 concurrent. Above ~40 processes on one OAuth grant the
+   hourly token refresh stampedes into 401s and kills the wave. Queue the rest.
+5. Parent liveness: a child reporting `completed` with a few dozen log lines, or
+   with 0 commits on its branch, has not finished; look for its sub-branches or
+   re-dispatch it with the predecessor's worktree and diff.
+6. Integration per round: freeze a base SHA, rebase clean branches mechanically,
+   give each conflicting branch its own rebase worker ("main's behaviour wins,
+   re-applied inside the new structure"), merge onto one integration branch,
+   run the FULL suite on the combined tree. Collisions that every branch passed
+   alone appear only here. The next round branches from the integrated commit
+   so its workers cannot conflict with each other.
+7. Before declaring a round integrated: `git rev-list --count <integration>..<branch>`
+   is 0 for EVERY branch. Workers keep committing after you merge their tip;
+   168 commits across six slices were once left behind that way.
+8. Test runs: exactly one runner on the box, behind a lock file, at high `-j`.
+   Many parallel low-`-j` runners were slower AND killed each other's process
+   groups. Red files are re-run on a bare `origin/main` worktree in the same
+   venv; identical per-file failure sets are pre-existing, not yours.
+9. Forward-port at the end, not per round: freeze main's SHA, fan out the
+   conflicted files by directory to workers editing ONE merge worktree with
+   no commits, then the parent commits the merge once. CI never runs on a
+   conflicted PR, so re-merge main before every push.
+10. Live QA is its own wave: one squad per surface, isolated `HERMES_HOME`,
+    expectation written before the check, evidence on disk, report only, and a
+    PR-vs-main difference is the only thing that counts as a regression. Green
+    unit tests missed the one P0 (a logged-in code path no test exercised).
+11. Reviewer claims get the same treatment as child claims: A/B against the
+    base before "restoring" anything. Several confidently stated review deltas
+    already behaved that way on base.
+12. A parent restart needs a `HANDOFF.md`: why it died, which handles are dead,
+    per-branch scorecard (LOC delta, import smoke, targeted tests), and the exact
+    re-dispatch text. Snapshot every dirty worktree into a `wip:` commit first.
+
+## Pitfalls
+
+- Calling `delegate_task` inside an `execute_code` script: not in the sandbox.
+- Synthesizing on the same turn as the fan-out call: the files do not exist yet.
+- Promising background-durable-for-days from `delegate_task`: it is turn-scoped
+  and dies with the process. Durable graph = kanban swarm; one-off = `cronjob`.
+- Trusting `summary` for content, or `status=completed` for completion.
+- Same framing in every "independent" attempt: they collapse to one answer.
+- `git stash` anywhere in a worktree campaign: `refs/stash` is shared across
+  worktrees and another worker will pop your edits. Compare via a temp worktree.
+- Reporting a hit target when the honest number is lower. Say "16% so far, here
+  is the path to 30%" and run the next round.
+
+## Verification
+
+- Manifest line count matches the expected unit count.
+- Every `out_*.csv` exists and was written this run.
+- Every dropped claim has recorded counter-evidence; every surfaced claim went
+  through refutation.
+- Campaign: every branch at 0 unmerged commits, full suite on the integrated
+  tree with reds triaged against bare main, live QA report per surface, token
+  cost reported on the scoped slice before the full run.

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

@@ -0,0 +1,326 @@
+---
+title: "Grok — Delegate coding to xAI Grok Build CLI (features, PRs)"
+sidebar_label: "Grok"
+description: "Delegate coding to xAI Grok Build CLI (features, PRs)"
+---
+
+{/* 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. */}
+
+# Grok
+
+Delegate coding to xAI Grok Build CLI (features, PRs).
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Optional — install with `hermes skills install official/autonomous-ai-agents/grok` |
+| Path | `optional-skills/autonomous-ai-agents\grok` |
+| Version | `0.1.1` |
+| Author | Matt Maximo (MattMaximo), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Coding-Agent`, `Grok`, `xAI`, `Code-Review`, `Refactoring`, `Automation` |
+| Related skills | [`codex`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`claude-code`](/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`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.
+:::
+
+# Grok Build CLI — Hermes Orchestration Guide
+
+Delegate coding tasks to [Grok Build](https://docs.x.ai/build/overview) (xAI's
+autonomous coding agent CLI, the `grok` command) via the Hermes terminal. Grok
+can read files, write code, run shell commands, spawn subagents, and manage git
+workflows. It runs three ways: an interactive TUI, **headless** (`-p`), and as
+an **ACP agent** over JSON-RPC.
+
+This is the third sibling to `codex` and `claude-code`. The orchestration
+pattern is nearly identical — **prefer headless `-p` for one-shots**, use a PTY
+for interactive sessions.
+
+## When to use
+
+- Building features
+- Refactoring
+- PR reviews
+- Batch issue fixing
+- Any task where you'd otherwise reach for Codex / Claude Code but want Grok
+
+## Prerequisites
+
+- **Install (preferred):** `npm install -g @xai-official/grok`
+  - The official installer `curl -fsSL https://x.ai/cli/install.sh | bash` also
+    works, but the `x.ai` host is Cloudflare-walled in some environments. The
+    npm path avoids that dependency entirely.
+- **Auth — SuperGrok / X Premium+ subscription (primary path):**
+  - Run `grok login` once → opens a browser for OAuth → token cached in
+    `~/.grok/auth.json`. This uses your **SuperGrok or X Premium+** subscription
+    (no per-token API billing).
+  - Check sign-in state by looking for `~/.grok/auth.json`, or run a cheap
+    headless smoke test: `grok --no-auto-update -p "Say ok."`
+  - In the TUI, `/logout` signs out and `/login` (or relaunching) signs back in.
+- **No git repo required** — unlike Codex, Grok runs fine outside a git
+  directory (good for scratch/throwaway tasks).
+- **Claude Code / AGENTS.md compatible with zero config** — Grok auto-reads
+  `CLAUDE.md`, `.claude/` (skills, agents, MCPs, hooks, rules), and the
+  `AGENTS.md` family. Existing project context just works.
+
+> **API-key fallback (not the default for this user):** Grok also supports
+> setting the `XAI_API_KEY` environment variable for pay-as-you-go billing
+> via `api.x.ai`. Only use
+> this if `grok login` / SuperGrok auth is unavailable. The subscription path
+> (`grok login`) is the intended setup here.
+
+## Two Orchestration Modes
+
+### Mode 1: Headless (`-p`) — Non-Interactive (PREFERRED)
+
+Runs a one-shot task, prints the result, and exits. No PTY, no interactive
+dialogs to navigate. This is the cleanest integration path — the analog of
+`claude -p` and `codex exec`.
+
+```
+terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)
+```
+
+Always pass `--no-auto-update` in automation to skip background update checks.
+
+**When to use headless:**
+- One-shot coding tasks (fix a bug, add a feature, refactor)
+- CI/CD automation and scripting
+- Structured output parsing with `--output-format json`
+- Any task that doesn't need multi-turn conversation
+
+### Mode 2: Interactive PTY — Multi-Turn TUI Sessions
+
+The TUI is a fullscreen, mouse-interactive app. Drive it with `pty=true`. For
+robust monitoring/input use tmux (same pattern as the `claude-code` skill).
+
+```
+# Launch in a tmux session for capture-pane monitoring
+terminal(command="tmux new-session -d -s grok-work -x 140 -y 40")
+terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter")
+
+# Wait for startup, then send a task
+terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter")
+
+# Monitor progress
+terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50")
+
+# Exit when done
+terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work")
+```
+
+**Tip for headless-but-inline output:** if you want TUI-style output without the
+fullscreen alt-screen takeover (e.g. for cleaner logs), add `--no-alt-screen`.
+For pure automation, headless `-p` is still cleaner than the TUI.
+
+## Headless Deep Dive
+
+### Common Flags
+
+| Flag | Effect |
+|------|--------|
+| `-p, --single <PROMPT>` | Send one prompt, run headless, exit |
+| `-m, --model <MODEL>` | Choose a model |
+| `-s, --session-id <UUID>` | Assign a **NEW** valid UUID to a fresh conversation (must not already exist). Does **not** resume — use `--resume`/`--continue` for that. Only valid with `--resume`/`--continue` when paired with `--fork-session` |
+| `-r, --resume [<UUID>]` | Resume an existing session by its UUID (or the most recent if omitted) |
+| `-c, --continue` | Continue the most recent session in the current directory |
+| `--fork-session` | When resuming, create a new session ID instead of reusing the original |
+| `--max-turns <N>` | Cap the maximum number of agent turns |
+| `--cwd <PATH>` | Set the working directory |
+| `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` |
+| `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) |
+| `--no-alt-screen` | Run inline, no fullscreen TUI takeover |
+| `--no-auto-update` | Skip background update checks (use in all automation; hidden from `--help` but still works) |
+
+### Output Formats
+
+- `plain` — human-readable text (default)
+- `json` — one JSON object at the end of the run (parse the result cleanly)
+- `streaming-json` — newline-delimited JSON events as they arrive
+
+```
+# Structured result for parsing
+terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120)
+
+# Auto-approve for autonomous building
+terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300)
+```
+
+### Background Mode (Long Tasks)
+
+```
+# Start headless in background
+terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true)
+# Returns session_id
+
+# Monitor
+process(action="poll", session_id="<id>")
+process(action="log", session_id="<id>")
+
+# Kill if needed
+process(action="kill", session_id="<id>")
+```
+
+For an interactive (TUI) background session, use `pty=true` + tmux and monitor
+with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills.
+
+### Session Continuation
+
+Sessions are keyed by **UUID**, not by name. `--session-id` assigns a *new* UUID
+to a fresh run (it does **not** resume); `--resume` takes an existing session's
+UUID (or omit the value to resume the most recent).
+
+```
+# Start a session with a self-assigned UUID (must be a valid, unused UUID)
+SID=$(uuidgen)
+terminal(command="grok --no-auto-update -s $SID -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240)
+
+# Resume that exact session later by its UUID
+terminal(command="grok --no-auto-update -r $SID -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180)
+
+# Or just continue the most recent session in this directory (no UUID needed)
+terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60)
+```
+
+## Read-Only Audit → Markdown Note Pattern
+
+To have Grok review local artifacts and return a clean markdown note (for
+Obsidian or a repo) without mutating anything:
+
+1. Prepare stable input files first with Hermes tools (`read_file`,
+   `write_file`). Snapshot only the relevant context into a temp file rather
+   than dumping raw paths.
+2. Run Grok headless **without** `--always-approve` so it cannot auto-write, and
+   demand `markdown only, no preamble`.
+3. Save Grok's stdout straight into the destination note with `write_file()`.
+
+```
+grok --no-auto-update -p "Read /tmp/current.md and /tmp/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain
+```
+
+**Pitfall (same as Claude Code):** for document rewrites, a loose "rewrite this"
+prompt may return a change summary instead of the full file. Instead: pipe the
+file in, and demand `Return ONLY the full revised markdown document. No intro,
+no explanation, no code fences. Start immediately with '# Title'.` Verify the
+first lines with `read_file()` before overwriting the destination.
+
+## PR Review Patterns
+
+### Quick Review (Headless)
+
+```
+terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120)
+```
+
+### Clone-to-temp Review (safe, no repo mutation)
+
+```
+terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300)
+```
+
+### Post the review
+
+```
+terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo")
+```
+
+## Parallel Issue Fixing with Worktrees
+
+```
+# Create worktrees
+terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
+terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
+
+# Launch Grok headless in each (background)
+terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, notify_on_complete=true)
+terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, notify_on_complete=true)
+
+# Monitor
+process(action="list")
+
+# After completion: push and open PRs
+terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
+terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
+
+# Cleanup
+terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
+```
+
+## Useful Subcommands & TUI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `grok` | Start the interactive TUI |
+| `grok -p "query"` | Headless one-shot |
+| `grok login` / `grok logout` | Sign in / out (SuperGrok / X Premium+ OAuth) |
+| `grok inspect` | Show what Grok discovered in cwd: config sources, instructions, skills, plugins, hooks, MCP servers |
+| `grok agent stdio` | Run as an ACP agent over JSON-RPC (for IDE/tool integration) |
+| `grok update` | Update the CLI (needs the `x.ai` host; skip in automation) |
+
+TUI slash commands (interactive only): `/model <name>`, `/always-approve`,
+`/plan`, `/context`, `/compact`, `/resume`, `/sessions`, `/fork`, `/usage`,
+`/quit`. `Shift+Tab` cycles session modes (including Plan mode, which blocks
+write tools except the session plan file).
+
+## Config (`~/.grok/config.toml`)
+
+```toml
+[cli]
+auto_update = false          # skip background update checks persistently
+
+[ui]
+permission_mode = "ask"      # or "always-approve" to skip tool prompts by default
+
+[models]
+default = "grok-build-0.1"
+```
+
+Put global preferences in `~/.grok/config.toml` (not project-scoped
+`.grok/config.toml`). `permission_mode` supersedes the legacy `approval_mode` /
+`yolo = true` keys.
+
+## Pitfalls & Gotchas
+
+1. **Auth is subscription-gated.** `grok login` requires a SuperGrok or X
+   Premium+ subscription. If login fails or there's no `~/.grok/auth.json`,
+   confirm the subscription is active before falling back to `XAI_API_KEY`.
+2. **Don't conflate Hermes' xAI auth with the `grok` CLI's auth.** Hermes'
+   `x_search` runs on its own xAI OAuth; the standalone `grok` CLI has a
+   separate token in `~/.grok/auth.json`. A working `x_search` does NOT mean
+   `grok` is logged in.
+3. **Always pass `--no-auto-update` in automation** — otherwise Grok phones home
+   for update checks (and `x.ai`/`storage.googleapis.com` may be unreachable).
+4. **Prefer npm install over the curl installer** — `npm install -g
+   @xai-official/grok` avoids the Cloudflare-walled `x.ai` host.
+5. **`--always-approve` is the autonomous-build switch.** Without it, headless
+   runs may stall waiting on tool-approval prompts. Omit it deliberately for
+   read-only review/audit work so Grok can't mutate files.
+6. **Headless `-p` skips TUI dialogs**; the TUI needs `pty=true` (+ tmux for
+   monitoring), just like Claude Code.
+7. **Use `--no-alt-screen`** if you run the TUI inline and the fullscreen
+   alt-screen takeover garbles captured output.
+8. **No git repo needed**, but for PR/commit workflows you still want one — use
+   `mktemp -d && git init` for scratch commit tasks.
+9. **Clean up tmux sessions** with `tmux kill-session -t <name>` when done.
+
+## Rules for Hermes Agents
+
+1. **Prefer headless `-p`** for single tasks — cleanest integration, structured
+   output via `--output-format json`.
+2. **Always set `workdir`** (or `--cwd`) so Grok targets the right project.
+3. **Pass `--no-auto-update`** in every automated invocation.
+4. **Use `--always-approve` only when Grok should write autonomously**; omit it
+   for read-only reviews and audits.
+5. **Background long tasks** with `background=true, notify_on_complete=true` and
+   monitor via the `process` tool.
+6. **Use tmux for multi-turn interactive work** and monitor with
+   `tmux capture-pane -t <session> -p -S -50`.
+7. **Verify auth before relying on it** — check `~/.grok/auth.json` or run a
+   cheap `grok -p "Say ok."` smoke test; don't assume Hermes' xAI auth carries
+   over.
+8. **Report results to the user** — summarize what Grok changed and what's left.