From 41a4af034975c09c311e3741c5ee107b104a9327 Mon Sep 17 00:00:00 2001 From: Scott Miller Date: Mon, 14 Sep 2026 17:32:22 -0600 Subject: [PATCH] docs(readme): lead with the live review loop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite the README top around Watch → Comment → Act. Add For authors / For reviewers, a Comments and the agent section, and the missing comments/MCP subcommands. Rename the technical how-it-works heading so it does not collide with the new product loop. Closes #120 --- README.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 24f2e5c..5b7dc93 100644 --- a/README.md +++ b/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 `, or push it to a shareable URL with `gander watch ` 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-.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 `; 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 [|] [--all] Stop a watch (by file, id, or --all) gander logs [] 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] [] 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