docs: streamline the agent workflows guide

.changeset/agent-workflows-guide-cleanup.md

@@ -0,0 +1,2 @@
+---
+---

docs/agent-workflows.md

@@ -1,158 +1,92 @@
 # Agent workflows
 
-Use Hunk with agents in two ways:
+There are two ways to combine Hunk with a coding agent:
 
-- **Recommended:** steer a live Hunk window from another terminal with `hunk session ...`
-- **Alternative:** load prewritten agent notes from a file with `--agent-context`
+- **Recommended:** the agent steers a live Hunk window from another terminal with `hunk session ...`
+- **Alternative:** load prewritten agent notes from a JSON sidecar with `--agent-context`
 
-## Recommended workflow: steer a live Hunk window
+This page is the short human-facing overview. The generated review skill is the
+authoritative agent-facing reference for every session command, flag, and error
+message — agents should follow the skill, not this page. The hosted guides live
+at [hunk.dev/docs](https://hunk.dev/docs/agents/review-with-an-agent/).
 
-1. Open Hunk in one terminal with a normal review command such as `hunk diff` or `hunk show`.
-2. Load the Hunk review skill: [`skills/hunk-review/SKILL.md`](../skills/hunk-review/SKILL.md).
-3. Ask the agent to use the skill and review the current session.
+## Steer a live Hunk window
 
-A good generic prompt is:
+1. Open Hunk in one terminal with a normal review command such as `hunk diff` or `hunk show`, and keep it open.
+2. In the agent's terminal, locate the bundled skill with `hunk skill path`.
+3. Ask the agent to load that file and use it for the review:
 
 ```text
 Load the Hunk skill and use it for this review. Run `hunk skill path` to get the skill path.
 ```
 
-That skill teaches the agent how to inspect a live Hunk session, navigate it, reload it, and leave inline comments.
+The skill teaches the agent to inspect the live session, navigate it, reload
+it, and leave inline comments — and to never launch the interactive TUI itself.
 
-## How live session control works
-
-When a Hunk TUI starts, it registers with a local loopback daemon. `hunk session ...` talks to that daemon to find the right live window and control it.
-
-Most users only need `hunk session ...`. Use `hunk mcp serve` only for manual startup or debugging of the local daemon.
-
-If `hunk session list` reports no sessions while Hunk is visibly running, the agent sandbox may be blocking loopback access. Probe the daemon directly:
-
-```bash
-curl -s -X POST http://127.0.0.1:47657/session-api \
-  -H 'content-type: application/json' \
-  --data '{"action":"list"}'
-```
-
-If this shows sessions, rerun the command with the agent's network/sandbox escalation. If you run the daemon with a custom `HUNK_MCP_PORT`, use that port instead.
-
-## The commands you will use most
-
-### Inspect the current review
+## What the agent runs
 
-Start here before navigating or commenting:
-
-```bash
-hunk session list
-hunk session get --repo .
-hunk session review --repo . --json
-```
-
-- `list` shows the active Hunk windows
-- `get --repo .` confirms which live session matches the current repo
-- `review --json` returns the loaded file and hunk structure without dumping the full raw patch
-
-Only add `--include-patch` when an agent truly needs raw unified diff text:
-
-```bash
-hunk session review --repo . --include-patch --json
-```
-
-### Move the live window to the right place
-
-Use `navigate` to jump to the file or hunk you want the user to see:
+A typical review looks like:
 
 ```bash
+hunk session list                            # find live sessions
+hunk session review --repo . --json          # file/hunk structure, no raw patch
 hunk session navigate --repo . --file src/App.tsx --hunk 2
-hunk session navigate --repo . --next-comment
+hunk session comment add --repo . --file src/App.tsx --new-line 42 --summary "Check this boundary"
+hunk session reload --repo . -- show HEAD~1  # swap what the window shows
 ```
 
-Use `reload` when you want the already-open Hunk window to show a different diff or commit:
+- `--repo <path>` selects the session by its loaded repo root; pass a session id instead when several windows share one repo.
+- `review --json` keeps raw diff text out of agent context; `--include-patch` opts in per call.
+- `comment apply --stdin` applies a JSON batch of notes in one call.
 
-```bash
-hunk session reload --repo . -- diff
-hunk session reload --repo . -- show HEAD~1 -- README.md
-```
+Full syntax, advanced reload targeting (`--session-path`, `--source`), and
+error remedies are in the skill
+([`skills/hunk-review/SKILL.md`](../skills/hunk-review/SKILL.md)).
 
-Notes:
-
-- always include `--` before the nested Hunk command in `reload`
-- `--hunk` is 1-based
-- `--next-comment` and `--prev-comment` are handy when an agent is walking the user through existing notes
-
-### Add comments
-
-For one note, use `comment add`:
-
-```bash
-hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"
-```
-
-For multiple notes, use one stdin batch with `comment apply`:
-
-```bash
-printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' \
-  | hunk session comment apply --repo . --stdin
-```
-
-`comment apply` payload items need:
-
-- `filePath`
-- `summary`
-- exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`
+## How live session control works
 
-If you want the UI to jump to the new note, add `--focus` to `comment add` or `comment apply`.
+Every normal Hunk TUI registers with a local loopback daemon, and
+`hunk session ...` asks that daemon for the right live window. Nothing needs to
+be started by hand — `hunk daemon serve` exists only for manual startup or
+debugging of the daemon.
 
-For comment cleanup and inspection, use:
+If `hunk session list` reports no sessions while Hunk is visibly running, the
+agent sandbox is likely blocking loopback access. Probe the daemon directly:
 
 ```bash
-hunk session comment list --repo .
-hunk session comment rm --repo . <comment-id>
-hunk session comment clear --repo . --file README.md --yes
-hunk session comment clear --repo . --all --yes # also clears human `c` notes
+curl -s -X POST http://127.0.0.1:47657/session-api \
+  -H 'content-type: application/json' \
+  --data '{"action":"list"}'
 ```
 
-Agents can remove or bulk-clear human notes for cleanup, but cannot create or edit them through the session CLI.
-
-## Session targeting
-
-Most commands can target the live session in a few ways:
+If that shows sessions, rerun the session command with the agent's
+network/sandbox escalation. With a custom `HUNK_MCP_PORT`, use that port
+instead.
 
-- `--repo <path>`: most common; matches the live session by its current repo root
-- `<session-id>`: useful when multiple Hunk windows are open for the same repo
-- if only one session exists, Hunk can auto-resolve it
+## Load agent notes from a file
 
-`reload` also supports some advanced selectors:
-
-- `--session-path <path>` targets the live Hunk window by its current working directory
-- `--source <path>` changes where the replacement `diff` or `show` command runs
-
-For normal worktree use, prefer `--repo /path/to/worktree`. Reach for `--session-path` and `--source` only when you need to repoint an already-open window to another checkout or path.
-
-## Alternative workflow: load agent comments from a file
-
-Use `--agent-context` when you already have agent-written rationale or notes in a JSON sidecar file and want to render them beside the diff.
+Use `--agent-context` when agent-written rationale already exists as a JSON
+sidecar and should render beside the diff:
 
 ```bash
 hunk diff --agent-context notes.json
 hunk patch change.patch --agent-context notes.json
 ```
 
-For a compact real example, see [`examples/3-agent-review-demo/agent-context.json`](../examples/3-agent-review-demo/agent-context.json).
+For a compact real example, see
+[`examples/3-agent-review-demo/agent-context.json`](../examples/3-agent-review-demo/agent-context.json).
 
-## Opt into experimental rich notes
+## Experimental rich notes (STML)
 
-STML note bodies are experimental and disabled by default. Start a new review with `--experimental` to render sidecar `markup` fields and accept live comments that carry markup:
+STML markup note bodies are off by default. Start the review with
+`--experimental` to render sidecar `markup` fields and accept live comments
+that carry markup:
 
 ```bash
 hunk --experimental diff --agent-context notes.json
-# Equivalent: hunk diff --experimental --agent-context notes.json
 ```
 
-Normal reviews keep using each annotation's required plain-text `summary` fallback. Opted-in live sessions list `stml` in `hunk session context --json` under `experimentalFeatures`; reload commands cannot change the launch opt-in.
-
-## Practical defaults
-
-- start with `hunk session review --repo . --json`
-- only add `--include-patch` when the raw patch is actually needed
-- use `comment add` for one-off notes and `comment apply` for batches
-- prefer `--repo` over `--session-path` unless you have a specific advanced reload case
+Plain-text `summary` fields stay required as the fallback, and a reload cannot
+change the launch opt-in. Agents check support via `experimentalFeatures` in
+`hunk session context --json` and learn the markup language from
+`hunk markup guide`.