Comments

Comments is the project’s one record of conversation: threaded comments on a blueprint, a top-level doc, a canvas page, a task, a record, or an asset, closed when settled, signed by whoever wrote them. Every thread lives in the plugin’s workspace, and the plugin projects a file’s threads into one region at the foot of its body as readable markdown. The store is the truth; the region is what it shows. On by default.

A thread points at its target by a permanent id, never a path, and at a place inside it by content (a heading’s text, an item’s text), never a line number. An edit above it does not move it; when the content it pointed at is gone, the thread is shown orphaned rather than chased.

In the app

• On the page, the threads sit at the foot of the body in every mode, in the modal and on the full page. A + on a heading or an acceptance criterion starts a thread anchored there; @alias completes from the project’s users; a thread has replies, Close (and Reopen once closed), and a delete on hover, and a message of your own is edited or deleted from its pencil and trash on hover. A message takes reactions: the face on hover opens a picker of emoji, a person may add several, each reaction shows its count and who reacted on hover, and a click on one takes yours off or adds it.
• Comments, an activity in the Activity Bar whose badge counts the orphaned threads. It leads into the Comments table at /p/comments through For me (the open threads you wrote in or are mentioned in, on a target not done), Open, Orphaned, and All comments, each with its count, then your saved views, and under them lists the threads you pick under Sidebar shows (For me until you pick another, or a saved view), the latest first, each opening its target at the anchor. The table filters by status, what a thread is on, whether its target is done, its anchor, its author, and who it mentions; the filters sit in the page’s address and save as a view. On the orphaned threads, Remove all orphaned, and on one, Re-anchor…, close, or delete. A host that is off leaves its threads listed under Elsewhere.
• A message is signed by the user this machine acts as (from the shell, the user --as or EIDOS_USER names comes first), else the git identity matched to a listed user through the Git plugin, else the git name with the role in me.md. Attribution, not authentication.

Threads on a canvas page draw as pins; threads on a task, a record, an asset file, or a bundle sit at the foot of its page. Each of those hosts says what an anchor is. Canvas → · Backlog → · Assets →

On disk

• .eidos/plugins/comments/threads/<thread-id>.yaml: one thread. id; target { host, id } (host is blueprint, doc, or a plugin’s name); at, the host’s own anchor keys (a blueprint’s are section, a heading’s text, and item, an item’s text), absent for a thread on the whole; resolved, true when the thread is closed; messages[{ author, role?, user?, text, at, reactions? }], where reactions maps each emoji to the users who reacted with it. A file edited by hand is read as written.
• .eidos/plugins/comments/settings.yaml: delete_orphaned, shared, off by default; on, a thread whose target or anchor is gone is deleted at the next read instead of listed as orphaned.
• .eidos/plugins/comments/local.yaml, local: sidebar, what the Comments sidebar lists (for-me, open, orphaned, all, or a saved view’s id).
• In each commented file, the region between <!-- comments:threads --> and <!-- /comments:threads --> at the foot of the body: every thread, open and closed, as markdown. It is written with the first thread and removed with the last, so a file nobody commented on carries no region. Never type into it; the next rewrite replaces it wholesale. A comment is a save of the file and shows in git history as one.

From the shell

eidos comments                                   # every open thread, grouped by host
eidos comments @login                            # the threads on one blueprint; --closed, --active, --json
eidos comments add @login "Is the limit per user?" --section "Behaviors"
eidos comments add @login "Per user." --reply <thread>
eidos comments add @login "Checked." --reply <thread> --as agent   # signed as a project user
eidos users                                      # the project's users; --json
eidos users add "AI Agent" --alias agent --agent # a user on the fly: only the name is needed
eidos comments close @login <thread>             # resolve is the same command
eidos comments reopen @login <thread>
eidos comments react @login <thread> 1 👍        # on the first message; again takes it off
eidos comments delete @login <thread>
eidos comments render                           # rewrite every region that drifted; or one target

A target is a blueprint reference (@<id>, a path, a filename), a doc, or <host>:<id> (backlog:<task>, canvas:<page>, records:<id>). --active leaves out threads on a target its host calls closed, such as a task that is done. --section, --item, and --at key=value anchor a thread inside its target.

An agent reads a target’s threads before editing it, answers a question with add --reply, and closes a thread only when the owner says a thing is settled. The command signs the message; a thread file is never edited for a comment.

An agent comments as itself, never as the person it works for. Without --as, a comment is signed as the acting user, which in someone’s checkout is that person. So an agent checks eidos users, adds itself once with eidos users add "<Its name>" --alias <alias> --agent when it is not there (no role is needed), and passes --as <alias> on every comments add. A name that is no user is refused with the eidos users add that creates it. AI Agent starts its agent signing as the user it takes actions as, by default an AI Agent user it adds to the project’s users; with AI Agent as a user switched off in the AI Agent’s settings, its agent comments as nobody and every comment it tries is refused. On the Users settings page, the Agent switch on a row marks a user as an agent.

What the check reports

comments/anchor-missing (a thread whose host says its target or anchor no longer resolves) and comments/region-stale (a file whose region is not what the store would write, including one left behind after its last thread was deleted). Project fixes the second.