Yard Docs
Sign in
On this page

Comments

Discuss blocks and passages of a spec in comment threads, attach files, docs and blocks, mention people, and resolve threads when done.

Updated November 11, 2026 · 4 min read

Comments let you talk about a piece of the workspace where it is, instead of in a separate chat. A comment starts a thread. A thread belongs to one block on a canvas, or to a passage of a project's spec.

Commenting on a block

Select the block and choose Comment from the … menu of its action bar. A panel opens beside the block with its threads and a box to write in. Write your comment and press Comment (or ⌘/Ctrl+Enter).

A block with open threads shows a badge with their number. Click the badge, or choose Comments (N) from the block's … menu, to open them again.

Commenting on a passage of a spec

In a project's spec, select the sentence or passage you mean and press Comment on the selected text in the Comments section below the document. The new thread quotes the passage, so everyone knows what it is about. All the spec's threads are listed there, and the heading counts the open ones.

Comments on passages of notes, and markers in the spec's margin that follow the text, are not available yet.

Answering and mentioning

Write in a thread's box and press Answer. Answers notify the others who took part in the thread.

To bring someone in, write @ followed by their name or email address, for example @sam. They get a notification. Only people who can still see the workspace are notified.

Mentions and answers are also emailed to people who turned on Mentions and replies under Account settings, Email (it is off until they do). Every such email has a link to turn it off again, no sign-in needed.

Attaching files, docs and blocks

A comment or an answer can carry attachments, as a prototype's comments do. Press the paperclip beside the box for This device, paste or drop a file on the box, or drag a doc, a block, a prototype or a workspace file from the sidebar, Files or the canvas onto it. Up to ten per comment; an uploaded file is saved with the comment once its upload is in, and one that failed says why and stays out. A comment may be only attachments, with no words. They show as chips under the comment; a file opens in Files and a prototype on its page. The block a thread is on is not attached to its own comment, and a repository's file is not attached (give it to a chat instead).

Comments on a canvas block or a spec are for people: an agent given the block does not read its threads yet, so give it what a comment attaches directly. A prototype's screen comments are different: the agent reads them and what they attach (prototypes). So are comments on lines of a project's diff: its agent lists, answers and resolves them with yard comments (repositories and git).

Resolving and reopening

When a thread is settled, press Resolve. It stays visible, marked resolved with the name of the person (or the project's agent) who resolved it, and its badge no longer counts it, and the mentions and replies in it stop asking for anyone in the Notifications menu. Reopen brings the thread back (those notifications stay cleared). Answering a resolved thread reopens it too.

Editing and deleting

You can delete your own comments with Delete next to them. When the last comment of a thread is deleted, the thread goes too.

Two more things are possible through the API but not yet in the app: authors can edit their comments (an edited comment is marked edited), and workspace owners can delete anyone's comment.

Who can comment

Role Can do
Owner and Editor Read, start and answer threads, resolve and reopen.
Viewer Read every thread. No box to write in.
Not in the workspace Nothing: threads are not visible.

Comments are written from the canvas and the spec, so while the runner is offline you can read them but not add new ones. Roles are explained in sharing and roles.

Live for everyone

New comments, answers and resolved threads appear for everyone who has the workspace open, without reloading. Notifications show in the Notifications menu on the account row.

Was this page useful?
Edit this page