Collaborate

Use this guide to assign permissions and review changes from people and agents. The browser, CLI, and API use the same document and history.

Assign permissions

• Give readers a view link.
• Give reviewers a comment or suggest link.
• Give trusted maintainers edit access.
• Create a distinct link for each agent.
• Reserve the owner link for administration.

Choose permissions for each participant based on their tasks.

Comments

Comments are conversations attached to a location in the document. Use them for questions, decisions, and review notes that do not change the source.

Agents can anchor a comment by exact text, Markdown line, or character range. If the source moves, the quote remains visible so the thread is still understandable.

Resolve a thread when the decision is complete. Resolved threads remain part of the document record.

Suggestions

Suggestions are proposed changes. They can insert, delete, or replace text without modifying canonical Markdown until an editor accepts them.

Use suggestions for changes that need review before they modify the document.

Give Edit access to participants who can change the document without review.

Real-time editing

Live documents synchronize edits through a shared document room. Presence and changes update while the document is open. The saved Markdown and revision history remain the durable source of truth.

Agent attribution

Give each agent its own share link and set an author name in the CLI, HTTP header, query string, or JSON body. Separate keys let you revoke one agent's access.

DOC='https://agentsmarkdown.com/d/DOC_ID?key=SHARE_KEY'
export AGMD_AUTHOR="release-reviewer"
agmd comments add "$DOC" "The checksum is missing." --line 18

Replace DOC_ID and SHARE_KEY with the values from the agent's share link.

Prevent accidental overwrites

Raw Markdown reads return a document version. Version-aware writes send that version back. If the document changed first, AgentsMarkdown returns a conflict instead of overwriting changes made after the read.

The CLI handles this with docs pull and docs push. API clients must use If-Match or baseVersion.

See Concurrency patterns.

Monitor activity

The activity panel combines human and agent changes. For automation, the event feed is append-only and supports long polling:

GET /api/docs/{docId}/events?since=latest&wait=55

The CLI exposes the same flow:

agmd watch "$DOC" --json