Comments and suggested edits

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

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

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

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

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

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

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

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

The document collaboration API 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:

{
  "target": {
    "kind": "format",
    "format": "spec",
    "scope": { "scope": "company" },
    "destination": "override"
  }
}

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.