annotate

name	annotate
description	Work through markdown annotations (comments and questions queued on documents linked to this thread). Use when the user asks you to address annotations, comments, review feedback, or questions on a markdown document.

Working through MD Annotate annotations

Documents annotated with MD Annotate carry inline comments and questions on selected text. When linked to this thread, they queue here for you to answer one at a time.

The flow

1. annotations_status — list pending annotations (id, quote, kind, age).
2. annotations_next — take the next one. It marks it in-progress and prints the file, the selected text with <selected> tags around the surrounding lines, and the comment thread. It refuses to advance while another annotation is in progress — reply, resolve, or annotations_end it first.
3. annotations_reply — put your full answer here (annotationId, text, and resolve: true when fully addressed). The user reads your reply in the annotation UI, not in this chat — do not repeat it as chat prose.
4. annotations_resolve — close an annotation after replying.

Rules

• Questions are answer-only. Never edit the document for a question — answer in the annotations_reply call.
• Comments may warrant an edit. For a comment you may edit the document to address it, and say what you changed in the reply.
• Don't answer stale context. If annotations_reply is blocked because the user added a new comment since you last read the annotation, re-read with annotations_show and address the latest comments before retrying.
• One at a time. Take the next annotation only after the current one is replied or resolved. annotations_show <id> reprints an annotation at any time without changing its state.

CLI (for scripts and shells)

The same operations exist as bb annotate (from a thread context, or with --thread <threadId>): next, status, show <id>, reply <id> "text" [--resolve], resolve <id>, start <id>, end <id>.