# Comments & reviewing edits

Comments explain a question or requested change. Tracked changes record who changed what in the source, so that each edit can be accepted or rejected. These are related activities, but resolving a comment and accepting a change are separate author decisions.

## Create an anchored discussion

Select a passage in the source or PDF and use the comment action; **⌘ShiftM** comments on the source selection. Inspect the saved quote and location. PDF comments preserve the selected text, so check reading order when selecting across columns or unusual typesetting.

Open **Comments/Notes** to read threads, reply, edit messages, filter them and inspect resolved discussions. Click a location to return to the relevant source or PDF passage. A general comment can describe a project-level concern, while an anchored comment is easier to act on precisely.

Write actionable comments: identify the issue, explain the desired outcome and preserve uncertainties. “Explain why the baseline uses a different split” is more useful than “Fix this”.

## Track changes

Tracked changes work as in Overleaf. The file always holds the text with every change accepted: an insertion is in it, a deletion is not, so compiling, search, the outline and every other tool read the paper as it currently stands. On top of that text the LaTeX editor shows what is still pending, in each author's colour: inserted text underlined and tinted, deleted text struck through where it was, and a bar in the gutter next to each changed line.

Switch **Track changes** on in the editor header (**⌘ShiftE**). While it reads **Track changes on**, everything you type, delete, paste or replace is recorded as your tracked change. The switch belongs to you, in this workspace, on this device; your collaborators each have their own. Turn it off to edit plainly again. Tracked changes need live editing, which is on unless the workspace switched it off.

How edits are recorded:

- Typing next to your own insertion from the last few seconds extends it; typing inside your own pending insertion always does.
- Deleting text you inserted and nobody has accepted yet just removes it; nothing is recorded.
- Deleting accepted text records a deletion that keeps the text. Backspacing or deleting forward through a passage makes one deletion, not one per character.
- Deleting someone else's pending insertion records a deletion over it, and both show. Accepting your deletion removes that text for good; rejecting it gives the text back to their insertion, still pending; rejecting their insertion removes it, and your deletion of part of it with it.
- Replacing a selection is a deletion followed by an insertion; the review shows it as one replacement.
- **Undo** takes back a tracked change together with its record.

Edits made by agents are tracked without asking, attributed to the agent (the built-in agent by model, an external agent by its connection name), with a link to the conversation that made them. Edits written to the files by another program (a second editor, a script, a Git pull) are not tracked unless you ask for it. Both choices are workspace settings at the bottom of the Review panel: **Edits made by agents** (on) and **Edits from other programs** (off).

## Accept and reject changes

Hover a change in the LaTeX editor to see who made it and when, with **Accept** and **Reject** (for a deletion, **Restore**); clicking struck-through text shows the same card. **⌘Option]** and **⌘Option[** move to the next and previous change in the file and open its card.

The **Review** tab on the right (**⌘ShiftR**, also **Review → Track changes**) lists every pending change of the workspace, by file and then by author, with the number of pending changes on the tab. Click a change to go to it. Accept or reject one change, all of one author's changes in a file, everything in a file, or everything the filters show: filter by author (for example only agents, then **Accept all**), by file and by kind.

Accepting keeps the text as it is: an insertion stays, a deletion stays gone. Rejecting removes an insertion or puts deleted text back where it was. A decision applies at once for everyone who has the file open, and is never recorded as a new change. **Show markup** off shows the final text only. The Visual editor marks changes the same way (insertions underlined, deletions struck through) and follows the same switch; the PDF always shows the final text.

People with write access to a file accept and reject its changes. Anyone may reject (withdraw) their own changes. A collaborator on a suggest link can do only that.

## Where tracked changes are kept

Pending changes live in each file's shared document while it is open, and on disk in `.versofold/track-changes.json`, written together with the file. They survive restarts and follow a file that is renamed in VersoFold. If a file is changed by another program while nothing has it open, its changes are carried through that edit the next time it opens; a change inside text that was rewritten can no longer be placed and is dropped, which the server log records.

Versions and automatic checkpoints save the text as it is, with pending insertions in and pending deletions out. **Save version** says how many changes are still pending.

## Compare with approved version

**Review → Compare with approved version** (also at the bottom of the Review panel) compares the whole draft with the version you last signed off: side by side, inline with word-level changes, or as two compiled PDFs. **Approve file** or **Approve all** moves that baseline forward; rejecting a hunk or reverting a file writes the approved text back. Use it before a submission, or for changes that were made without tracking.

Read the exact change before accepting it. A grammatically polished revision can still alter a scientific claim. Rejecting a hunk puts the source back only when the comparison is still current; newer changes can make an old decision stale.

## Understand review baselines

The review baseline is the source state against which **Compare with approved version** works. It is preserved through project history. **Mark as seen** changes your reading position, while shared approval is a separate record.

When old history objects are missing, the app can explain recovery using the oldest available snapshot. It cannot reconstruct lost snapshots. Preserve the hidden history directory when moving or backing up a workspace.

Historical PDFs may be compiled in temporary isolated folders and cached. A current PDF and a historical PDF may differ because the source changed; inspect their labels and build status before interpreting a comparison.

## Work with agent suggestions

Give the agent a focused request and the relevant selected passage or files. Discuss mode is for analysis. Edit mode can apply authorized live changes, while staged source proposals need explicit acceptance.

After the agent finishes:

1. Read its report and referenced source locations.
2. Open **Review** and filter by the agent: its edits are tracked changes in its colour. Look for removed qualifications and changed numbers.
3. Check the recorded build outcome and the actual PDF when layout matters.
4. Accept, reject or revise the changes, one by one or all of the agent's at once.
5. Resolve the original feedback only when the requested work is complete.

The agent can also read the pending changes and, when you ask (“accept my coauthor's changes in the method section”, “reject your edits to the abstract”), accept or reject them for you. A live agent edit is already in the working source before review; a staged proposal is separate until accepted, and becomes tracked changes when you accept it. Undoing an agent edit from its transcript takes its tracked changes with it.

## Collaborators and imported annotations

Shared workspaces can grant reading, comments, suggestions or writing according to the owner's choices. On a suggest link a collaborator edits the live files, but every edit is a tracked change for someone with write access to accept or reject. Reviewer access also depends on whether sources, compilation and history were granted. See [sharing](sharing-export.md).

Use **Import an annotated PDF** to inspect external PDF annotations and bring supported notes into comments. Imported annotation anchors depend on what the PDF contains; verify the result. For Word tracked changes, use the dedicated round-trip workflow instead of treating a DOCX as LaTeX source. Edits in a review file sent back by email arrive as a proposal in **Compare with approved version**.

Related: [versions](versions.md), [agent](agent.md), [deadlines and rebuttals](deadlines-rebuttal.md).