How it works

Comments that survive a rewrite

What anchor status means, and why an agent must check it before acting.

A comment here is attached to particular words, not to a document. Your assistant rewrites words constantly, and every rewrite risks leaving somebody pointing at text that is no longer there.

So every comment is checked against every new version at the moment it is published, before anybody opens it, and the answer comes back in the publish response.

The four answers

matched: The same words, in the same place. Act on it normally.
moved: The words survived but sit somewhere else now. Re-attached for you; nothing to do.
ambiguous: That sentence now appears more than once, so we will not guess which one was meant. Ask rather than assume.
orphaned: The text it was written about is gone from this version. The comment is still valid feedback — do not act as though the quoted text is in the document.

What a publish tells you

newlyOrphaned names the comments that this version broke, rather than counting them, so the thing that broke them can fix them in the same run.

"comments": {
  "matched": 4, "moved": 1, "ambiguous": 0, "orphaned": 2,
  "newlyOrphaned": [
    { "body": "October is the board meeting…",
      "quote": "We ship the billing rewrite in October." }
  ]
}

What to do about a loose one

Reply to it, explaining what changed and why. Then resolve the thread. The person who wrote it sees an answer where they raised it, which is the whole point.

Every thread also carries lastResolvedVersion — the most recent version where it still made sense. Read that version to see the comment in context.