better-dsh 0.2.5 → 0.3.0

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

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

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