moss-comments

Comments

Comments require both body markers and comments.json.

Body Markers

Wrap the exact annotated range:

The %%m:c1:start%%current layout%%m:c1:end%% needs work.

• IDs may contain letters, numbers, hyphens, and underscores.
• Start and end markers are both required.
• Multiple comments can share one range: %%m:a,b:start%%text%%m:a,b:end%%.

Sidecar Metadata

Write comments.json beside the note markdown file:

{"c1":{"text":"Tighten this wording.","createdAt":1707900000,"updatedAt":1707900000,"source":"external"}}

• Every marker ID needs matching sidecar metadata.
• Every sidecar key needs matching body markers.
• source values: "external" for comments written by an agent outside of Moss, "agent" reserved for the in-app Moss agent, "user" for human comments. Always set "external" explicitly for comments you write.

Placement

• Plain text: wrap the exact words.
• Inline nodes: wrap the entire token, for example %%m:x:start%%[[Project Plan]]%%m:x:end%%.
• Block nodes: put markers on standalone lines around the whole block.

%%m:b1:start%%
![Demo](assets/demo.png)
%%m:b1:end%%

Do not place markers inside wiki links, formula/variable pills, color code pills, fenced block payloads, or raw HTML comments. Treat atomic inline pills as indivisible. For color literals such as #4f8a6b, rebeccapurple, or rgb(72, 67, 60), prefer annotating the surrounding sentence or phrase rather than trying to split the literal itself.

Image Attachments

Comments may include image attachments stored under the note's assets/ directory:

{"c1":{"text":"See screenshot.","createdAt":1707900000,"updatedAt":1707900000,"source":"external","imageUrls":["assets/comment-abc.png"]}}

• Use the imageUrls array with note-relative paths under assets/.
• To read an attached image, resolve the path against the note's directory and read the file from assets/.

@Mentions

Mentions in comment text are references to notes, files, or folders. Each displayed mention is wrapped with U+2063 (INVISIBLE SEPARATOR) before and U+2064 (INVISIBLE PLUS) after, e.g. Re: ⁣@Project Plan⁤ scope.

• When a comment asks you to use or inspect an @mention, use the available mention id/path or note sidecar metadata to resolve and read the referenced target before acting.
• Mentioned targets may be inside or outside the Moss notes directory; do not assume ~/Moss/Notes/.
• If the mention cannot be resolved or multiple targets match, report the ambiguity instead of inventing a path.
• Preserve the wrappers verbatim when editing existing comment text — the renderer uses them to display the mention as a pill.