# 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 document with a plan agent, editors can ask the agent about selected text or send an expanded discussion. Editors do not have to own the plan. Viewers and comment-only teammates cannot run the agent. Formats and other documents without an agent have no agent action. Review the instruction and conversation before **Send and resolve**. A confirmed send resolves the thread and 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 resolution failed, retry resolution without sending another turn. ## 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. 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.