# Comments and suggested edits Discuss a document, propose a change, and bring the right people into the conversation. Open a document and choose **Comments**. Start a discussion about the whole document, or select a passage and choose **Comment** or **Suggest edit**. Each discussion has its own link, replies, and resolved state. ## Who can participate [#who-can-participate] Anyone who can read a document can comment, reply and suggest edits, including viewers and comment-only teammates. Accepting a suggestion requires permission to maintain its source. Workspace owners maintain formats. Plan editors maintain their editable plan documents. A discussion link preserves access rules. It does not make a private plan public or give the recipient permission to edit. Public prototype links support guest discussions; guest composers do not offer workspace mentions. ## Keep the conversation beside the change [#keep-the-conversation-beside-the-change] Replies stay with their thread, including replies to a suggested edit. Resolving a thread moves it to **Resolved**. A reply does not reopen it. Reopen explicitly when the discussion needs more attention. You can edit your own comments and inspect their history. Removing a root comment keeps its replies. Removed text is hidden from ordinary readers; authors and maintainers retain the appropriate history access. Drafts stay in the current browser for the current account and document. If a request loses its response, **Retry** checks the same request rather than posting a second copy. A failed request keeps your text available. ## Suggest an exact edit [#suggest-an-exact-edit] Select the passage, write its replacement, and explain why. The review shows the original and proposed text. Use the source view when Markdown details matter. Teammates can reply on the proposal before a maintainer accepts or rejects it. The author can withdraw a pending proposal. Acceptance checks the document revision you reviewed. If someone has changed the source, refresh the proposal against the current text and review it again. A stale proposal cannot replace newer work. Accepted, rejected and withdrawn proposals keep their discussion and decision history. Resolving the discussion does not accept the edit. Reopening it does not reverse an earlier decision. To propose another change after a decision, create a new suggestion. For a readable copy of an uploaded or connected document, check the application target shown in the review. An edit to a Plansmith copy changes that copy. An external proposal records a change made in the original system: a maintainer chooses **Applied externally** and explains where it was applied. That action does not write to the external source. ## Mention someone [#mention-someone] Type `@` and select a teammate from the picker. It only offers people who can read this document and its plan discussion. A pasted email address, an `@name` in code, or text inside a proposed replacement does not create a mention notification. The selected teammate receives an Inbox item. Editing a comment notifies newly added mentions; it does not notify the same people again for every wording change. ## Who gets updates [#who-gets-updates] | Discussion | Responsible recipient | | ---------------------------------------------- | ------------------------------------------------------------ | | Plan document or context discussed in a plan | That plan's owner | | Shared context discussed in different plans | Each thread's own plan owner | | Spec format, epic format or prototype template | Eligible workspace owners | | Personal instructions | The personal owner, within the existing private access rules | Other participants can follow the thread. **Unfollow** stops ordinary updates; **Mute** keeps them off until you choose to follow again. Explicit mentions still appear in your Inbox. Notifications never grant access to a document. ## Your Inbox [#your-inbox] Open the bell in the header. The Inbox belongs to the workspace shown in its header. Choose **All** or **Unread**, mark individual items read or unread, or open an item to go directly to its conversation. **Mark all read** applies through the viewed snapshot, so a new arrival stays unread. Under **Preferences**, choose email for mentions, new discussions, replies and review decisions separately. These switches leave Inbox delivery available. Ordinary reply bursts share an email after a short delay; explicit mentions remain separate. Email delivery also checks current document access. ## Ask the plan agent [#ask-the-plan-agent] On a spec or an epic, choose **Ask agent to address N open comments** at the top of the discussion, or ask in the chat ("apply the comments on SPEC-3"). The agent reads each open thread, updates the spec, replies in the thread to say what changed, and marks the thread **Addressed**. You can also paste a thread link into the chat. Editors do not have to own the plan. Viewers and comment-only teammates cannot run the agent. An Addressed thread waits for its author, who chooses **Looks good** to resolve it, or **Resolve your N** to close all of their own Addressed threads at once. A plan editor can still resolve someone else's thread from its header. Replying sends the thread back to **Open**. The agent treats a teammate's comment as a request about that spec: anything it asks for beyond editing the spec, such as deleting a spec or pushing the plan, the agent raises with you first. To send one thread, choose **Send to agent** on it. The instruction is optional. The thread stays open until the agent addresses it, and the send keeps a link to the chat. Sending a suggested edit includes its proposal but does not accept it. A failed send leaves the thread open and preserves the instruction. If the send succeeded but its confirmation failed, retry the confirmation without sending another turn. ### What the agent can change [#what-the-agent-can-change] The agent reads, replies and marks threads Addressed on its own. Every other change waits for your approval in the chat: resolving, reopening or sending back a thread, accepting or rejecting a suggested edit, and editing, deleting or starting a comment. The approval card lists each change in plain words. **Allow once** applies exactly those changes, as you and with your permissions, and **Cancel** applies none. Comment changes ask every time. The agent never approves a change for you. ## API, CLI and MCP [#api-cli-and-mcp] The [document collaboration API](/docs/api-reference/document-collaboration/createV1DocumentCollaboration) exposes document resolution, threads, replies, comment history, suggestions, mentions and subscriptions. The Inbox API exposes notification lists, read state and preferences. A read credential cannot perform mutations, even when its user can comment in the app. Threads have three states: `OPEN`, `ADDRESSED` and `RESOLVED`. Only the plan agent in the app marks a thread `ADDRESSED`; from the API, the CLI and MCP a reply never does. Resolve and reopen work on an Addressed thread, and reopening it sends it back to `OPEN`. A reply's response says the thread's state after it. The CLI passes structured requests through `discussion`. For example, save this as `document.json` to resolve the company's spec format: ```json { "target": { "kind": "format", "format": "spec", "scope": { "scope": "company" }, "destination": "override" } } ``` ```sh plansmith discussion resolve-document --file document.json --json plansmith inbox list --unread --json plansmith inbox preferences --json ``` Use the returned document ID and revision in later requests. Keep the same `requestId` when retrying a mutation. Hosted and stdio MCP expose the same discussion and notification services; their tools return the current capabilities and revision checks.