| name | collaborate |
| description | Orchestrates collaborative document editing. Load before any mcp__tafelmusik__ tool call. Invoke first when user says 'edit the doc', 'check the document', 'add a comment', 'write together', or 'collaborate on this' — teaches load-first workflow, edit mode selection, and comment conventions that prevent data loss. |
Collaborate
Tafelmusik is a shared CRDT document where you and Sameer co-edit markdown in real time. Sameer sees a CodeMirror editor in the browser; you operate via MCP tools. Edits merge automatically — no conflicts, no locking.
Iron law: load before editing. load_doc connects you to the room. Without it, your edits go nowhere.
Workflow
1. Find or create a document
list_docs → shows available documents (name + active status)
load_doc(room, markdown) → creates/overwrites a document with initial content
Room names are file paths: batterie/tafelmusik/docs/foo maps to ~/Repos/batterie/tafelmusik/docs/foo.md on disk. Navigating to hezza:3456/batterie/tafelmusik/docs/foo in the browser opens the same room.
2. See what's there
inspect_doc(room) → full text with authorship attrs + drift score
list_comments(room) → all comments, sorted by position
inspect_doc shows who wrote what (author attrs on each chunk) and the drift score — high drift means your mental model may be stale. Use it before editing if you haven't seen the doc recently.
3. Edit
Four modes, from lightest to heaviest:
| Mode | When to use | Parameters |
|---|
patch | Fix a typo, rewrite a paragraph, reorder a list | find + replace |
replace_section | Rewrite an entire section (h2-h6 only) | content starts with heading |
append | Add new content at the end | content |
replace_all | Full document rewrite or h1 sections | content |
Default to patch. It has the smallest blast radius — only the matched text is touched, surrounding content and authorship are preserved. Include enough context in find to match exactly once.
edit_doc(room, mode="patch", find="the the quick", replace="the quick")
edit_doc(room, mode="replace_section", content="## Revised Section\n\nNew content here.")
edit_doc(room, mode="append", content="\n## New Section\n\nAdded at the end.")
edit_doc(room, mode="replace_all", content="# Fresh Start\n\nEntire document replaced.")
Avoid replace_section on h1 headings — it extends to EOF and will destroy everything below. Use replace_all instead.
4. Comment
Comments are inline reactions anchored to specific text — not editorial workflow, not code review.
add_comment(room, quote="exact text from doc", body="Your reaction or suggestion")
resolve_comment(room, quote="the quoted text")
The quote must be an exact substring of the document. Sameer sees the comment as a highlighted annotation in the browser. Use comments to ask questions, suggest changes, or react to specific passages.
5. Persist
flush_doc(room) → writes Y.Text to .md file, git commits
Flush is the "save" — it creates the durable .md file on disk. Comments (stored in SQLite) survive flush — they're persistent, not ephemeral. Flush when the document text is in a good state; comments carry on.
When to Use
- Sameer asks you to write, edit, or review a document together
- You need to react to specific text Sameer wrote (use comments)
- Sameer says "check the doc" or "I updated the document"
When NOT to Use
- Reading/writing local files (use Read/Write tools directly)
- One-off text generation with no collaboration intent
- Sameer hasn't mentioned a shared document
Anti-Patterns
| Mistake | Consequence | Fix |
|---|
Edit without load_doc first | Edit silently fails or targets wrong room | Always load first |
replace_section on # Title | Destroys everything below h1 | Use replace_all |
replace_all for a typo fix | Stomps Sameer's concurrent edits | Use patch |
| Guessing document content | Stale edits, broken patches | inspect_doc first |
| Flushing mid-conversation | Commits half-written text to disk | Flush at natural endpoints |