Comments

Needs gander signup. These commands are hidden from gander --help until a token is saved.

Comments are Docs-style threads on the rendered page, anchored to a selection. They live on gander.md, not in the markdown file, so the agent can rewrite the doc without destroying the discussion. Threads survive those rewrites; if the quoted text disappeared, the thread is marked orphaned but still listed.

Each thread stores the highlighted span itself (the selected text plus its character offsets), not only the block it sits in. Duplicate phrases are distinct: highlighting the second “foo” and writing @agent remove this means that span, not the first copy and not the file. @agent threads on a share are a FIFO queue ordered by time; the agent should work the oldest unanswered one, then re-list before the next.

You need signup to host comments. Reviewers need a browser and permission from commenting policy. They do not install the CLI.

Two kinds of thread

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 for humans on the share (author, teammates, anyone-commenters). They stay unresolved until someone resolves them. They are not agent work, even if unresolved_count is greater than zero.

A follow-up that does not start with @agent is not a new summons. The agent should not treat it as a fresh task.

How the agent hears them

The silent path is MCP. Install once per machine:

gander mcp install

The agent then lists the inbox, fetches bodies only when agent_unresolved_count is greater than zero, edits the file, and replies. If the file is not already on hosted watch, it should gander watch so the reviewer sees the edit live.

After a gander, that inbox list runs on a backoff: sooner at first, then less often if nothing new arrives, and it stops after two idle hours. It is not a check on every message and not a flat five-minute loop. See MCP for tools, poll fields, and rules.

The CLI fallback, when MCP is not in the session:

gander comments
gander comments plan.md

No argument prints one line per file that has unresolved work (path, URL, whether it is watched). Pass a file when you want the quotes and comment bodies. That is the same inbox MCP uses.

Resolve, reply, unresolve

Reviewers resolve a thread in the browser when the note is done. Authors can resolve from the dashboard or via the API. Agents should resolve only after a simple doc edit (typo, wording, one-line fix). After a question or a large rewrite, they should reply and leave the thread open so the reviewer can still read it.

gander comments does not resolve. MCP's gander_resolve_thread / gander_unresolve_thread do.

What the reviewer sees

Select text, start a thread, optionally type a name, reply, resolve. If commenting is disabled, they can still read the doc. If the doc is private, they sign in or accept an invite first. Walkthrough: the share viewer.