Tutorialsmarkdown-den

04 — Comments that stay put

What you will have at the end: a document with a conversation on it — pinned to the exact words it is about, surviving the edits you make afterwards, with an agent answering one of the threads.

What you need: a document with a few paragraphs in it. For the last two steps, an agent in the workspace (tutorial 02).

What this actually is

A comment here is not a note at the bottom of the page. It is anchored to a span of text, and the anchor is the point: you are not saying "something about this document", you are saying "this sentence".

That turns out to matter most when you are working with an agent. Telling an agent what you want is the easy half; telling it which part you mean is where most of the ambiguity lives, and a thread on the sentence removes it before anyone has to write a word about it.

1. Start a thread on a sentence

Select some text — a sentence, a table row, a line of a list. A small 💬 Comment button appears next to it. This works in the preview and in the editor; on a phone the button reads 💬 Comment on selection.

Click it, type, and post. Three things happen:

  • The text you selected is now highlighted in the preview.
  • The comments panel opens on the right, with your thread in it.
  • The document's row in the file explorer gains a 💬, and so does every collapsed folder above it.

That last one is worth knowing early: the 💬 rolls up, and it draws on a folder only while that folder is shut. A closed folder wearing one is telling you there is an unresolved conversation somewhere inside it, so you can find work without opening anything — and opening it hands the question to the rows now on screen.

2. Reply, react, resolve

Click the highlight, or the thread in the panel, and you can:

  • Reply — the thread is a conversation, not a sticky note.
  • React with an emoji, which is how you agree with something without adding a message everybody then has to read.
  • Edit your own comment. It keeps an edited mark, so nobody is left wondering whether they misread it.
  • Delete your own comment. The thread keeps its shape and the comment becomes a tombstone — replies underneath it still make sense.
  • Resolve the thread. The highlight goes, the 💬 clears, and the thread is still there to reopen.

Resolving is a decision, not tidying. Hold that thought until step 6 — it is the one rule that makes agents usable.

3. Why it stays put when you edit around it

Now do the thing that breaks comments in most tools. Go back to the document and:

  1. Add two paragraphs above the commented sentence.
  2. Fix a typo inside it.
  3. Delete a paragraph below it.

Look at the preview again. The highlight is still on the same sentence. Not on the same line number, and not somewhere three paragraphs off — on the words.

That is because the anchor is not a position. It is the quoted text plus a little of what surrounds it, re-found in the document each time it is drawn. A comment about a sentence follows the sentence.

When it cannot follow, the honest answer shows up rather than a wrong one: if you delete or rewrite the sentence entirely, the anchor no longer resolves. The thread is not lost — it moves to an Unanchored group below the live threads, each card flagged ⚠ and still carrying its quoted text, so you can read what was said about words that no longer exist. It just has nothing to highlight.

The practical version of that: rewrite freely, and expect a thread on a sentence you deleted to go quiet. If a conversation matters, resolve it or answer it before you delete what it was about.

4. Bring somebody in with @

In a comment, type @. You get the people and agents who can reach this workspace. Pick one, finish your sentence, post.

They get a notification with a link straight to this thread — not to the document, to the thread. And from that message on, they are subscribed: replies reach them without anyone having to remember to mention them again.

You will see notifications in the bell in the top bar. An @mention and a reply in a thread you are part of both land there.

5. Ask an agent, on the thing you are asking about

This is the step the tutorial exists for.

Select a paragraph you are unsure about and start a thread on it:

@helper-bot Does this paragraph still match what specs/04-editor-ui.md says about the tab bar? Quote the part that disagrees if it does.

Then tell your harness to check in.

What happens next is worth watching once:

  1. The agent polls its notifications and finds the mention.
  2. It reads the thread — including the text you selected, which is part of the thread, so it knows exactly which paragraph you meant without you describing it.
  3. It reads whatever else it needs.
  4. It replies on your thread. Not in your terminal. The answer lands next to the question, where the next person to read this document will find it.

That last point is the whole shape of working with agents here. The conversation about a document lives on the document, so it is still there in a month, for somebody who was not in the room.

6. Resolving is your signal, and only yours

Every agent is told, at the moment it connects and before it reads anything else, never to resolve a thread. That is the convention that keeps the arrangement working:

  • A reply is the agent's report. It has finished, and it says so by answering.
  • Resolving is your verdict. You read the answer and decide whether the thing is actually settled.

If agents resolved their own threads, "done" would mean "the agent believes it is done", and you would have no way to see the difference. Because they are told not to, your unresolved list is the set of things you have not yet accepted.

Be clear-eyed about what holds that up: an agent with write access can resolve a thread — the tool is there, and the workspace would let it. What stops it is an instruction the server pushes to every session, not a wall. It is a convention worth relying on and worth repeating in your own AGENTS.md, which is exactly what the sample playbook in tutorial 02 does.

Two habits that follow, and both are worth writing into your workspace's AGENTS.md:

  • An unresolved thread with an agent's reply is waiting for you.
  • An unresolved thread with no agent reply is waiting for the agent — and it will find it on its next check-in, because a mention it has not replied to is still open work.

7. Find the conversations without hunting

Two things do the finding for you:

  • The 💬 in the file explorer, rolled up through collapsed folders, so an unresolved thread three folders deep is visible without opening anything.
  • The bell, for anything addressed to you specifically.

Resolve a thread and both clear. That is the loop: a document with no 💬 has nothing outstanding on it.

What you have now

A document where the discussion is attached to the words it is about, survives being edited around, and is answered by an agent in the same place a colleague would answer — and a way to see, from the file tree alone, where there is still something to settle.