Sidecar comments with quote-first anchors, CriticMarkup suggestions through the OT path, per-member feed; first three tasks sized for MiniMax. Written by MiniMax M3.1 Flash (OpenCode Zen free route) with web research notes; three owner questions open. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
21 KiB
Comments, suggestions, mentions and the activity feed
Extends specs/collaboration/spec.md (live co-editing, roles owner/editor/viewer, the members
list and the audit log). The owner asked on 2026-10-20 for review comments, tracked changes and
notifications inside a shared vault.
Problem
Two people reviewing the same note in a shared vault have no way to talk about a passage of it. They edit the same paragraph, one of them loses the argument, and the vault keeps no record of who asked what. The collaboration spec gives roles, presence and a "last edit" line; it gives no place to put a remark, no way to propose a change without applying it, and no inbox.
Goal
A reviewer can anchor a comment to a text range of a note, reply in a thread and resolve it; an editor can propose a change that the author accepts or rejects; a member can be mentioned by name; and every member sees, per person, what happened in the vault while they were away - all of it inside the plain-Markdown vault, through the engine command surface (SPEC 10).
Non-Goals
- Comments as a fourth vault role. A viewer may comment; only an editor or the owner accepts a
suggestion (
specs/collaboration/spec.mdkeeps three roles). - Comments in end-to-end encrypted vaults' server side: the server cannot read them, so mentions and the feed do not exist there (see D9).
- A server-side comment database in v1. The sidecar file is the store (D1).
- Editing or deleting someone else's comment. In v1 only the author may do that.
- Comments as live OT traffic: the room carries note text only, comments travel by file sync (D1).
- Reactions, assignment ("@Ana, please look"), comment search and comment export.
Design decisions
D1 - Where a comment lives: a sidecar file, not CriticMarkup in the note
Recommendation: comments live in a sidecar file next to the note; only suggestions are CriticMarkup inside the Markdown. The two layers are stored apart because they are different kinds of object.
| Axis | Sidecar <note>.comments.json |
Inline CriticMarkup {>>…<<} |
|---|---|---|
| Plain Markdown is the truth | The .md stays byte-identical to what any other tool reads |
The truth file carries markup; every external reader sees it |
| Obsidian compatibility | Invisible to Obsidian (one extra attachment file, hidden by us) | Renders literally in Obsidian: {>>text<<} is shown as text |
| Thread metadata | JSON: id, author, time, replies, resolved, mentions | None: CriticMarkup has no id, no author, no thread, no resolve state, and comments may not overlap |
| Sync conflicts | File level: the ledger makes a conflict copy, we merge by id (D5) | Text level: merges inside the note with merge3 / the OT room |
| Live OT | Untouched: the room never sees a comment, so a comment can never create an OT conflict | The markup is note text: it travels the room and every op shifts it |
| Anchors | Quote + context + offsets, re-resolved on load (D3) | Positional: the markup sits at the anchor, so the anchor cannot drift away |
CriticMarkup is the right tool for the suggestion layer: accepting or rejecting a suggestion is
an edit of the note text and must travel the ordinary edit path (D4). It is the wrong tool for
comments: a thread needs stable ids, replies, a resolved flag and a mention list, and CriticMarkup
has none of them. Inventing a convention for them inside the note (the Obsidian "Document Comments"
plugin had to invent <!--c:id-->…<!--/c:id--> plus a <!--co:id …--> block) puts the discussion
inside the text that the OT room, the search index and the publish projection all read.
The third known shape, HTML comments inside the .md, has the same defect as CriticMarkup comments
(the discussion is inside the text) without CriticMarkup's standard, so it is not used.
Sidecar path: the note path with .comments.json appended, e.g. notes/Ideas.md ->
notes/Ideas.md.comments.json. The rule is reversible, the name can never be a note (it does not
end in .md), and the rename of a note renames its sidecar with it.
D2 - The sidecar format
One JSON document per note, plain UTF-8, written with craft-atomic through Vault::write:
{
"version": 1,
"note": "notes/Ideas.md",
"comments": [
{
"id": "c-7f3a1c",
"author": "u_ana",
"created_ms": 1760000000000,
"updated_ms": 1760000000000,
"body": "Can we soften this claim?",
"anchor": {
"quote": "this always works",
"context_before": "In my experience ",
"context_after": ", except on slow disks.",
"start": 128,
"end": 145
},
"thread": [
{ "id": "r-2b90", "author": "u_bob", "created_ms": 1760000060000, "body": "Fair." }
],
"resolved": false,
"resolved_by": null,
"mentions": ["u_bob"]
}
]
}
id: 8 hex characters from the system's random source, the same one the live client uses (crates/engine/src/live/config.rs:54); unique inside the note, the key of the thread everywhere else.author: the server user id of the author (u_…), orlocalin a vault with no server.created_ms/updated_ms: when the thread was opened and when it last changed. The merge of D5 usesupdated_ms.anchor.quote: the selected text, at most 200 characters. It is the anchor (D3).anchor.start/anchor.end: byte offsets into the note text, hints only.mentions: the user ids that were mentioned, never display names (D6).- Limits: body at most 4 KiB, quote at most 200 characters, 200 replies per thread, 500 threads per note, sidecar file at most 1 MiB. A change that would break a limit is refused with an error, the file is never truncated.
D3 - Anchors and drift
An anchor is resolved against the note text the editor shows (the open buffer, or the live room text), never against a stale copy of the file. The resolution order, first hit wins:
- the recorded byte range still holds exactly the quote ->
Exact; - the quote is found in the text (nearest to the recorded range first) ->
Reanchored; - the quote is found after normalising whitespace and case ->
Reanchored; - the best fuzzy match (similarity at least 0.6, window of 2 000 bytes around the recorded range)
->
Fuzzy; - nothing found ->
Orphaned.
An orphaned comment keeps its body, its quote and its thread; it is listed under Orphaned and can be re-anchored by hand to a new selection. The state is derived, never stored, so two devices may disagree about it without corrupting the file. A fuzzy match needs a small Levenshtein ratio in the engine crate - no new dependency.
D4 - Suggestions (track changes) as CriticMarkup
The note text carries the pending suggestions: {++added++}, {--removed--}, {~~old~>new~~}.
Accept and reject are ordinary edits of the note text:
| Mark | Accept | Reject |
|---|---|---|
{++new++} |
new |
(nothing) |
{--old--} |
(nothing) | old |
{~~old~>new~~} |
new |
old |
- Accepting or rejecting rewrites the whole note text and writes it through the normal buffer path
(
Session::buffer_mut,save_buffer), so the change reaches the live room, the file sync and the audit log exactly like a typed edit. No second write path, no new server endpoint. - The suggestion is located by the byte range of the CriticMarkup span in the current text. If the
range no longer holds a span, the command answers an error (
stale_range); it never silently accepts the wrong span. - A viewer may not accept or reject: the engine refuses on the role (the role comes from the
members list) and the server refuses the resulting write with 403 (a viewer may not
PUTa file). - The Visual view renders a pending addition underlined and a pending deletion struck through; the Source view shows the raw text, because the raw text is the truth.
- A note with no pending suggestion is byte-identical to the same note edited without suggestions.
- CriticMarkup is parsed by a pure function in the engine crate. No new dependency: the marks are plain text.
D5 - Sidecar conflicts
Two devices that comment on the same note while offline produce two versions of the sidecar. The
sync ledger keeps both (a conflict copy, notescraft_sync::conflict_path). The engine merges the
two sidecars with a pure function: union of the threads by id; for the same id the copy with the
greater updated_ms wins and the replies are unioned by id. Nothing is ever dropped (sync
invariant 1: never lose data).
D6 - Mentions
- A mention names a member of the vault: the ids come from
GET /v1/vaults/{vault}/members(the same list asshare.members,Member { user_id, name, color, role }). - The sidecar stores the user id; the body keeps the visible text (
@Ana). The UI resolves the id against the current members list, so a renamed member shows the new name and a removed member shows a greyed name. - Only a member can be mentioned; a name that matches nobody is plain text, never a mention.
- A mention in a vault with no server stays local and is delivered when the vault is bound.
D7 - The activity feed
The feed is server side: a table per vault, so it survives a client restart and reaches every device of the member.
Event kinds: mention (you were mentioned), comment (someone commented on a note of the vault),
suggestion (someone proposed a change), note_changed (someone else changed a note),
invite_accepted (an invite you sent was accepted), member_joined, role_changed,
thread_resolved.
- Producer: the client posts the events it causes (
comment,mention,suggestion) when it creates them; the server writes the vault events (invite_accepted,member_joined,role_changed) where they already happen, and derivesnote_changedfrom the file upload it already handles. The server never parses the sidecar: it does not need to know the format. - The client that could not reach the server keeps the events in a local outbox
(
.notescraft/activity-outbox.json, written withVault::write_private) and posts them with the next successful sync. No mention is lost. - Read state: one row per (member, event) with a read timestamp.
activity.listanswers the events newer than a cursor plus the unread count;activity.readmarks events as read. - Delivery: the sync worker polls
GET /v1/vaults/{vault}/activityevery 30 s (the same loop that polls/changes). A Server-Sent Events stream on the sibling URL/activity/eventsis an optimisation, not the contract, and lands in phase 5. - Offline: the feed is complete on the server, so a client that was away sees everything it missed.
The unread cursor is local (
.notescraft/activity.json).
D8 - Engine commands
Every behaviour is a command (SPEC 10). Ids follow [a-z0-9._-]. ParamKind values are the ones
of crates/engine/src/params.rs (String, Integer, Bool, Array).
Read commands (added to READ_COMMANDS in crates/engine/src/ai/assistant_gate.rs):
| Command | Params | Answers |
|---|---|---|
comment.list |
path (String) |
the threads of the note with their anchor state |
suggestion.list |
path (String) |
the pending suggestions of the note |
activity.list |
since (Integer, optional), limit (Integer, optional, default 50, max 200) |
the events of the member plus the unread count |
activity.unread |
- | the unread count |
mention.candidates |
- | the members that can be mentioned (user_id, name, color) |
Write commands (added to WRITE_COMMANDS; disabled while the session is read-only, and
suggestion.accept / suggestion.reject need the editor or owner role):
| Command | Params | Answers |
|---|---|---|
comment.add |
path, quote, body, start (Integer, optional), end (Integer, optional), mentions (Array, optional) |
the id of the new thread |
comment.reply |
path, id, body |
the id of the reply |
comment.edit |
path, id, body |
- |
comment.delete |
path, id |
- |
comment.resolve |
path, id, resolved (Bool) |
- |
comment.reanchor |
path, id, quote, start, end |
the new anchor state |
suggestion.accept |
path, start (Integer), end (Integer) |
the new note text |
suggestion.reject |
path, start (Integer), end (Integer) |
the new note text |
activity.read |
ids (Array, optional) |
the new unread count |
Without ids, activity.read marks every event read up to now.
Errors are CommandError { code, message }: not_found, invalid_params, stale_range,
forbidden (role), limit (a limit of D2 reached), not_bound (no server for this vault).
In a vault with no server there is no role: the local user is the owner of the vault and every
command is enabled. A vault that is bound but whose server does not know the user yet answers
not_bound for the feed and the mention list.
D9 - What needs a server-readable vault
| Feature | E2EE vault | Shared (plain) vault |
|---|---|---|
| Comments and threads | works: the sidecar is a file and is encrypted like any file | works |
| Suggestions | works: the markup is inside the note and is encrypted with it | works |
| Mentions delivered to others | not available: the server cannot read the sidecar | works |
| Activity feed | not available: the server sees only ciphertext | works |
The encrypted vaults do not exist yet (specs/e2ee/spec.md); the column states the rule for the
day they arrive.
The UI says why, the same way the live co-editing rule is stated in specs/e2ee/spec.md.
D10 - Privacy and abuse limits
- Who reads a comment: every member with read access to the vault. The vault is the trust boundary; a comment is not a secret and must never hold one.
- Sizes: body 4 KiB, quote 200 characters, 200 replies per thread, 500 threads per note, sidecar 1 MiB, 20 mentions per comment.
- Server: the existing token buckets cap the writes; one event may wake at most 50 members; a feed page is at most 200 events; the server logs no comment body and no token.
- The client refuses a comment that breaks a limit and says which limit; it never truncates.
User stories
- As a reviewer, I want to select a sentence and leave a remark, so that the author answers next to the text instead of in a chat.
- As a reviewer, I want my remark to survive the author rewriting the paragraph, so that the discussion is not lost.
- As the author, I want to see every open remark of the note in one panel, so that I can work through them.
- As the author, I want to propose a change to a colleague's sentence and let them accept or reject it, so that the review does not fight over the file.
- As a member, I want to be mentioned by name, so that I know what needs my answer.
- As a member, I want a feed of what happened while I was away, so that I do not read everything again.
- As a viewer, I want to comment but not to change the note, so that I can help without the risk.
Acceptance Criteria
- Given a note and a selection, when
comment.addruns, thennotes/X.md.comments.jsonexists with one thread whose quote equals the selection, and the note file is byte-identical to before the command. - Given a thread with a reply, when
comment.listruns, then the thread has one root and one reply, in order, with their authors and timestamps. - Given a resolved thread, when
comment.resolvesetsresolved, then it leaves the Open filter and appears under Resolved, and the other members of the thread get athread_resolvedevent. - Given a note whose text changed so that the quote is gone, when the sidecar is loaded, then
the comment is
Orphaned, keeps its body, and is listed under Orphaned. - Given a note whose text changed so that the quote moved, when the sidecar is loaded, then the
anchor is
Reanchoredat the new position and the offsets are corrected on the next save. - Given a note with
{++new++}, whensuggestion.acceptruns with the span range, then the note text becomesnew, the markers are gone, and the write went through the ordinary buffer path (the live room receives it). - Given a note with
{~~old~>new~~}, whensuggestion.rejectruns, then the note text becomesold. - Given a stale range, when
suggestion.acceptruns, then the command answersstale_rangeand the note is unchanged. - Given a viewer token, when
suggestion.acceptruns, then the command answersforbiddenand the server refuses the write with 403. - Given a note edited without suggestions, when it is saved, then the file is byte-identical to the same note edited with the suggestion accepted.
- Given two devices that add different comments to the same note while offline, when they sync, then both threads exist in one sidecar file and neither is lost.
- Given a comment that mentions Bob, when it syncs, then Bob's feed has a
mentionevent and Ana's feed does not. - Given a client that was offline for an hour, when it polls the feed, then it gets the events it missed and the unread count matches the unread rows.
- Given a member removed from the vault, when their token calls the feed, then the answer is 403 and the feed of the other members does not change.
- Given a vault whose server cannot read the sidecar (an encrypted vault, when it exists), then the mention list and the feed are disabled with an explanation and the comments still work locally.
- Given a sidecar that would pass 1 MiB, when a comment is added, then the command answers
limitand the file is unchanged. - Given a note with comments, when the note is renamed, then the sidecar follows the new name.
Constraints
- Rust only, egui UI, server in
apps/notescraft-sync-server. No new dependency: the sidecar is JSON (serde_json), the anchors need a small Levenshtein ratio, CriticMarkup is plain text. - Plain Markdown stays the truth; the
.mdof a note with comments is byte-identical to the same note without comments. Sidecars are hidden from the explorer, from the search index and from the publish projection. - Every write to disk goes through
craft-atomic(Vault::write); the outbox and the unread cursor go throughVault::write_private(.notescraft/). - Every user-visible string goes through the i18n tables (
crates/i18n/locales/en.toml, thencargo xtask i18n). - Roles are enforced on the server; the engine refuses the write locally and says why.
- Layering: the engine is L4 and never uses egui; the UI crate is L6.
Open Questions
- Where do the comments live? The recommendation is the sidecar file (D1). The owner may prefer the comments inside the Markdown (HTML comments or CriticMarkup) for one file per note; the price is that the discussion becomes part of the note text that the OT room, the search index and the publish projection read. Recommendation: sidecar.
- Should the feed live on the server or be derived from the audit log? The recommendation is a dedicated activity table (the audit log is for the owner and holds entries without a recipient). Recommendation: dedicated table, rows per (member, event).
- Is a mention of a member who is not in the vault refused or kept as plain text? The recommendation: kept as plain text, never a mention. Recommendation: plain text.
Tasks
See tasks.md: five phases, each task independently testable and sized for one agent. The first
three (the comment model and the sidecar, the anchor resolution, the suggestion marks) are ready to
be given to MiniMax M3.1 Flash.
Designs
The surfaces, all in crates/ui-egui:
- Margin gutter: a thin strip left of the text in the note view with one marker per thread (filled = open, hollow = resolved) on the line of the anchor; tapping it opens the thread.
- Comment panel: a new tab of the right card (
RightTab,crates/ui-egui/src/panels/right_view.rs:103), next to Backlinks and Outline: the threads of the open note in document order, filters All, Open, Resolved, Orphaned, a composer on the current selection, reply, resolve/reopen and re-anchor. - Suggestions: the pending marks in the Visual view (addition underlined, deletion struck through) and a Review list with Accept, Reject and Accept all.
- Activity feed: a new right card tab with the events, newest first, unread marked, an unread badge on the tab, and a click that opens the note (and the line when the event carries one).
- Phone: the comment panel and the feed become pages of the compact shell
(
CompactPage,crates/ui-egui/src/shell/compact/mod.rs:29); the gutter markers become a tap target on the line; the composer is a sheet likeSyncSheet. - The PaperCraft project NotesCraft (page "Collaboration") holds the drawings; the review loop compares the offscreen render with them.