Comments

Comments is the root’s one record of conversation: threaded comments on a blueprint, a top-level doc, a canvas page, or a task, 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 browser

• 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 root’s users; a thread has replies, Close (and Reopen once closed), and a delete 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 with the count of open threads: every open thread by host with its anchor label and last message, opening the target at the anchor. Show closed, show orphaned, Remove all orphaned, and on an orphaned thread, 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 sit at the foot of the task. Each of those hosts says what an anchor is. Canvas → · Backlog →

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.
• 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, --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 root user
eidos users                                      # the root'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 project                           # 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>). --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 root’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.