docs: lead the README with the live review loop

README.md

@@ -1,12 +1,35 @@
-# gander — share markdown from your agent to your browser in real time
+# gander
 
-Render a Markdown file locally with `gander <file>`, or push it to a shareable URL with `gander watch <file>` that updates in place on every save. Built so humans and agents can read and collaborate on markdown at the same time.
+Gander is the live review loop for markdown an agent is still writing.
+`gander watch` gives you a short link that updates on every save. Reviewers
+comment in the browser like Docs. Comments that start with `@agent` come
+back into the agent session over MCP — no paste, no IDE for the reviewer,
+no git commit for the author.
 
-## For AI coding agents
+Site: [gander.md](https://gander.md)
 
-`gander` solves the problem of `cat`-ing a markdown file just to see what your agent wrote — open a browser tab once and the page updates in place on every save. Two workflows cover most of what you'll do:
+## How it works
+
+1. **Watch.** `gander watch plan.md` (or the agent does). Every save updates the hosted page.
+2. **Comment.** Reviewer opens the URL. No install. Inline threads on the live doc.
+3. **Act.** Comments that start with `@agent` land in the agent session. The agent edits the file. The same link updates.
+
+```bash
+brew tap gandermd/gander && brew install gander
+gander signup --email you@example.com
+gander watch plan.md
+gander mcp install   # once — the agent hears @agent comments
+```
+
+Or: `gander skill` and let the agent save the plan, watch the file, and poll for review.
 
-1. **`gander watch README.md`** — upload to `gander.md` and get a short URL. Every save hot-swaps the rendered page in every connected viewer's browser, so you can read along while your agent iterates on a design doc without copy-pasting or refreshing. (This is shorthand for `gander share README.md --watch`.)
+## For authors
+
+Reviewing a plan while the agent is still writing it usually means a screenshare, an early git commit, or sitting alone in the IDE. `gander watch` is a link instead: the reviewer reads in the browser, the author does not have to commit, and every save updates the same page.
+
+Two workflows cover most of what you'll do:
+
+1. **`gander watch plan.md`** — upload to `gander.md` and get a short URL. Every save hot-swaps the rendered page in every connected viewer's browser. (This is shorthand for `gander share plan.md --watch`.)
 
 2. **[`gandermd/gander-skill`](https://github.com/gandermd/gander-skill)** — a `SKILL.md` that wires all of this into your agent runner (OpenCode, Claude Code, Codex CLI, Cursor, Grok Build, Windsurf, and any other agent that loads `SKILL.md` files), plus two helper scripts:
    - `scripts/save-plan.sh` — pipe the agent's plan into `./plans/YYYY-MM-DD-<slug>.md`, then gander or share it.
@@ -20,6 +43,10 @@ gander skill
 
 That downloads [`gandermd/gander-skill`](https://github.com/gandermd/gander-skill) into `~/.gander/skill` and symlinks it into `~/.agents/skills/`, `~/.claude/skills/`, `~/.cursor/skills/`, and `~/.grok/skills/` so every supported agent picks it up automatically. Clone the skill repo only if you want to hack on `scripts/save-plan.sh` or `scripts/watch-markdown.sh` locally.
 
+## For reviewers
+
+Open the link in a browser. No install, no repo clone, no IDE. Select text and start a thread. Prefix a comment with `@agent` when the author's coding agent should act on it; other threads stay between humans.
+
 ## Installation
 
 ### Homebrew (recommended)
@@ -223,6 +250,28 @@ After rotating, install the new token on each machine with
 `gander auth <token>`; the CLI validates it against `/api/shares`
 before overwriting `~/.gander/config.json`.
 
+### Comments and the agent
+
+Threads live on gander.md, not in the markdown file, so the agent can rewrite the doc without destroying the discussion. Prefix a comment with `@agent` when you want the author's coding agent to change the file — that is a summons into the session that owns the file. Threads that do not start with `@agent` are human-to-human. They are not agent work.
+
+The silent path is MCP. Install once per machine; agent harnesses then launch the server on stdio:
+
+```bash
+gander mcp install
+gander mcp
+```
+
+You almost never run `gander mcp` yourself. After `gander mcp install`, supported harnesses start it.
+
+If MCP is not in the session, the CLI fallback is the same inbox:
+
+```bash
+gander comments
+gander comments plan.md
+```
+
+Reviewers do not install anything. They need a browser (and permission to comment). See [Comments](https://gander.md/docs/comments) and [MCP](https://gander.md/docs/mcp).
+
 ### Configuration (`~/.gander/`)
 
 `~/.gander` is a directory (mode 0700). JSON config lives at
@@ -299,6 +348,9 @@ gander stop [<file>|<id>] [--all] Stop a watch (by file, id, or --all)
 gander logs [<id>]                Tail the runner log (optionally filtered by watch id)
 gander runner install|uninstall   Auto-start the runner at login via LaunchAgent/systemd
 gander skill [install]            Install the agent skill (OpenCode, Claude, Cursor, Grok)
+gander comments [file]            Inbox of unresolved threads (MCP fallback)
+gander mcp                        Run the MCP server on stdio
+gander mcp install                Merge MCP config into local agent harnesses
 gander uninstall [--yes] [--keep-config]  Remove CLI, MCP, skill, runner (and optionally ~/.gander)
 gander remove [--all] [<file>]    Delete a share from gander.md
 gander list                       List shares currently on gander.md
@@ -360,7 +412,7 @@ You can then watch the run at https://github.com/gandermd/gander-cli/actions/wor
 
 MIT License — see [LICENSE](LICENSE) for details.
 
-## How it works
+## How the CLI works
 
 - **Markdown parsing**: uses [goldmark](https://github.com/yuin/goldmark) (CommonMark compliant)
 - **HTML sanitization**: uses [bluemonday](https://github.com/microcosm-cc/bluemonday) for security