Skip to main content

Review notes

Review notes let you attach comments to specific passages of a document, for a review pass or to leave yourself notes, without touching the document itself.

Review notes are a Twain Pro feature, along with Copy Report for Agent, which folds them into a brief. Without Pro, the note commands and the notes list open the Unlock Pro panel instead; your existing notes stay in their sidecar files untouched.

Adding a note​

  1. Switch to the raw source or side-by-side view, then select the text you want to comment on.
  2. Choose Edit ▸ Add Review Note… (⇧⌘N).
  3. Choose a kind (Note, Change request or Question), type your comment, and click Add Note.

The passage is highlighted in the source, and the status bar shows a Notes count of the notes that are still open. Resolved notes are not counted.

Managing notes​

Click the Notes count in the status bar to open the notes list. Each note shows its kind, its line number (or Orphaned), the quoted passage and your comment. From the list you can:

  • Click a located note to jump to it in the source pane. If you are in the rendered view, Twain switches to side-by-side first.
  • Mark a note resolved, or reopen it later. Resolved notes are struck through, sink to the bottom of the list, drop out of the status-bar count, and are left out of the agent report.
  • Delete a note.

Change requests are listed first, then questions, then plain notes.

Where notes are stored​

Notes are kept in a hidden companion file next to the document, named after it: a file called guide.mdx gets a .guide.mdx.mdlyreview.json sidecar in the same folder. Your document is never modified. If you delete every note, the sidecar file is removed rather than left empty.

Because notes live beside the file, they travel with it if you move the folder, and they can be committed alongside the document if you want to share a review.

How notes stay anchored​

Each note remembers the quoted text and a little of the surrounding context. When the document changes, Twain re-locates each note:

  • If the exact passage still exists, the note re-attaches to it, even if it has moved elsewhere in the file because of edits above it.
  • If the quoted text was changed or removed, the note is marked orphaned rather than being attached to the wrong place. Orphaned notes are reported honestly so you can revisit them.

Sharing a review with an agent​

If you use an AI assistant, the MCP server can read these notes through its twain_md_report tool. It re-anchors each open note against the current document and produces a single brief that lists the notes still open, together with any rendering issues, so an assistant can act on your in-app review. Resolved notes are left out of the brief and reported only as a count.

You do not need the MCP server for this. When a document has rendering diagnostics, the status bar shows a diagnostics button. Open that popover and click Copy Report for Agent to copy the same brief to the clipboard as Markdown. Paste it into whichever assistant you use.