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, resolved 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, Resolve, and a delete on hover.
• 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 resolved, show orphaned, Remove all orphaned, and on an orphaned thread, re-anchor, resolve, 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; messages[{ author, role?, user?, text, at }]. 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 resolved, 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; --resolved, --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 plato   # signed as a root user
eidos users                                      # the root's users; --json
eidos users add "Plato" --alias plato --agent    # a user on the fly: only the name is needed
eidos comments resolve @login <thread>           # --reopen
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 resolves 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. Plato starts its agent signing as the user it takes actions as, by default a Plato user it adds to the root’s users; with Plato as a user switched off in Plato’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.