tandem-editor 0.4.0 → 0.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tandem-editor",
-  "version": "0.4.0",
-  "description": "Collaborative AI-human document editor with MCP tool integration for Claude",
+  "version": "0.6.0",
+  "description": "Edit and iterate on documents with Claude — no copy-paste, real-time push via plugin monitor",
   "repository": {
     "type": "git",
     "url": "https://github.com/bloknayrb/tandem"
@@ -23,7 +23,9 @@
   "files": [
     "dist/",
     "sample/",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    ".claude-plugin/",
+    "skills/"
   ],
   "exports": {
     ".": "./dist/cli/index.js",
@@ -71,11 +73,14 @@
     ],
     "*.json !package-lock.json": [
       "biome check --write"
+    ],
+    "*.{yml,yaml,md}": [
+      "node scripts/normalize-eol.mjs"
     ]
   },
   "dependencies": {
-    "@hocuspocus/provider": "^3.4.4",
-    "@hocuspocus/server": "^2.13.0",
+    "@hocuspocus/provider": "3.4.4",
+    "@hocuspocus/server": "2.15.3",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@tauri-apps/api": "^2.10.1",
     "@tauri-apps/plugin-dialog": "^2.7.0",
@@ -111,9 +116,9 @@
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.0",
     "update-notifier": "^7.3.1",
-    "y-prosemirror": "^1.2.12",
-    "y-protocols": "^1.0.6",
-    "yjs": "^13.6.0",
+    "y-prosemirror": "1.3.7",
+    "y-protocols": "1.0.7",
+    "yjs": "13.6.30",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/sample/welcome.md

@@ -1,6 +1,6 @@
 # Welcome to Tandem
 
-Tandem is a collaborative document editor where you and Claude can review your documents together in real-time.
+Tandem lets you work on documents with Claude — highlight text and Claude sees it directly, no copy-paste needed. Because Claude connects via MCP, it brings all its knowledge and tools to the document.
 
 ## Getting Started
 
@@ -10,7 +10,7 @@ Open Claude Code from any directory -- your Tandem tools are already configured.
 
 ## Try These
 
-1. **Review an annotation** -- Look at the highlighted text in this document. Open the side panel to accept or dismiss annotations, or press Ctrl+Shift+R for Review Mode.
+1. **Respond to a suggestion** -- Look at the highlighted text in this document. Open the side panel to accept or dismiss annotations, or press Ctrl+Shift+R for Review Mode.
 2. **Ask Claude a question** -- Select some text and press Ctrl+Shift+A, or type in the Chat panel.
 3. **Make an edit** -- Click anywhere in the document and start typing. You can simplify sentences, fix typos, or add new content.
 
@@ -18,4 +18,4 @@ Open Claude Code from any directory -- your Tandem tools are already configured.
 
 The project launched in early 2025 with three core goals: simplify onboarding, reduce support tickets by 40%, and ship a self-service dashboard by Q3. The team completed the first two milestones ahead of schedule, but the dashboard timeline slipped due to an unexpected API redesign in May.
 
-> Once Claude connects, ask it to review this document -- you'll see highlights and suggestions appear in the side panel.
+> Once Claude connects, try asking it to help you improve this text -- you'll see highlights and suggestions appear in the side panel.

package/skills/tandem/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: tandem
+description: >
+  Use when tandem_* MCP tools are available, the user asks about Tandem
+  document editing, or iterating on text collaboratively. Provides workflow
+  guidance, annotation strategy, and tool usage patterns for the Tandem
+  collaborative editor.
+---
+
+# Tandem — Collaborative Document Editor
+
+Tandem lets you annotate and edit documents alongside the user in real time. The user sees your changes in a browser editor; you interact via the tandem_* MCP tool suite.
+
+## Hard Rules
+
+These prevent the most common failures. Follow them always.
+
+1. **Resolve before mutating.** Call `tandem_resolveRange` (or `tandem_search`) to get offsets before calling `tandem_edit`, `tandem_highlight`, `tandem_comment`, `tandem_suggest`, or `tandem_flag`. Never compute offsets by counting characters in previously-read text — they go stale when the user edits.
+2. **Pass `textSnapshot`.** Include the matched text as `textSnapshot` on mutations and annotations. If the text moved, the server returns `RANGE_MOVED` with relocated coordinates instead of corrupting the document.
+3. **Use `tandem_getTextContent`, not `tandem_getContent`.** `getContent` returns ProseMirror JSON and burns tokens. Use `getTextContent({ section: "Section Name" })` for targeted reads. The `section` parameter is case-insensitive.
+4. **`tandem_edit` cannot create paragraphs.** Newlines become literal characters. For multi-paragraph changes, use multiple `tandem_edit` calls or `tandem_suggest`.
+5. **`.docx` files are read-only.** Use annotations instead of `tandem_edit`. Offer `tandem_convertToMarkdown` if the user wants an editable copy.
+
+## Workflow
+
+Standard workflow:
+
+1. `tandem_status` — check for already-open documents (sessions restore automatically)
+2. `tandem_getOutline` — understand document structure
+3. `tandem_setStatus("Working on [section]...", { focusParagraph: N })` — show progress (use `index` from outline)
+4. `tandem_getTextContent({ section: "..." })` — read one section at a time
+5. Annotate or edit as needed (see annotation guide below)
+6. `tandem_checkInbox` — check for user messages and actions
+7. Repeat steps 3-6 for each section
+8. `tandem_save` — persist edits to disk when done
+
+## Annotation Guide
+
+Choose the right type for each finding:
+
+- **`tandem_highlight`** — Visual marker with a short note. Colors (full set): `green` (verified/good), `red` (problem), `yellow` (needs attention), `blue` (informational), `purple` (style/tone). Prefer the first three for review work; `blue`/`purple` are available when a fourth/fifth category is meaningful. Use when the finding is self-evident from the color and a brief note.
+- **`tandem_comment`** — Observation requiring explanation. Use when you need more than one sentence to convey reasoning.
+- **`tandem_suggest`** — Specific text replacement. **Prefer over comment when you can provide replacement text** — the user gets one-click accept/reject. Cannot create new paragraphs.
+- **`tandem_flag`** — Factual errors, compliance risks, missing required content. Signals a blocking issue the user must address before the document ships.
+
+**User questions to Claude.** Users can author a "question" annotation in the UI. The server normalizes it to `type: "comment"` with `directedAt: "claude"` before returning it — so when scanning `tandem_checkInbox` or `tandem_getAnnotations`, match on `type === "comment" && directedAt === "claude" && author === "user"`, not `type === "question"`. Respond with `tandem_reply` for conversational answers, or a new `tandem_comment` on the same range for a textual annotation.
+
+## Collaboration Mode
+
+Check `mode` from `tandem_status` or `tandem_checkInbox` and adapt:
+
+- **Tandem** (`"tandem"`, default) — Full collaboration. Annotate freely and react to selections and document changes.
+- **Solo** (`"solo"`) — The user wants to write undisturbed. Only respond when the user sends a chat message. Do not proactively annotate or react to document activity.
+
+## Reacting to Document Events
+
+Selections are **not** sent as standalone events. Instead, when the user sends a chat message, any buffered selection is attached as a `selection` field on the `chat:message` payload. This gives you context about what text the user was looking at when they wrote their message. When polling via `tandem_checkInbox`, the current selection shows up under `activity.selectedText`. Use `tandem_reply` for any document-context reaction (chat messages, question annotations); reserve terminal output for non-document work the user explicitly requests. In Solo mode, hold reactions until the user sends a chat message.
+
+## Collaboration Etiquette
+
+- Check `tandem_getActivity()` before annotating near the user's cursor. If `isTyping` is true, wait for typing to stop before annotating that area.
+- Use `tandem_setStatus` to show what you're working on — the user sees it in the browser status bar.
+- **Call `tandem_checkInbox` every 2-3 tool calls**, not just at the end of a task. The real-time channel is often not connected; polling is the reliable path.
+- Reply to chat messages with `tandem_reply`, not annotations.
+
+## .docx Review Workflow
+
+1. `tandem_open` — opens in read-only mode (`readOnly: true`)
+2. `tandem_getAnnotations({ author: "import" })` — check for imported Word comments; read and act on them
+3. Annotate with findings (highlight, comment, suggest, flag)
+4. `tandem_exportAnnotations` — generate a review summary the user can share
+5. If the user wants editable text, offer `tandem_convertToMarkdown`
+
+## Error Recovery
+
+- **`RANGE_MOVED`** — Text shifted since you read it. The response includes `resolvedFrom`/`resolvedTo` — use those coordinates for your next call.
+- **`RANGE_GONE`** — The text was deleted. Re-read the section with `tandem_getTextContent` and re-assess.
+- **`INVALID_RANGE`** — You hit heading markup (e.g., `## `). Target text content only, not the heading prefix.
+- **`FORMAT_ERROR`** — Attempted `tandem_edit` on a read-only `.docx`. Use annotations instead.
+
+## Session Handoff
+
+When starting a new Claude session with Tandem already running:
+
+1. `tandem_status()` — check `openDocuments` array for restored sessions
+2. `tandem_listDocuments()` — see all open docs with details
+3. `tandem_getOutline()` — orient on the active document
+4. `tandem_getAnnotations()` — see what was already reviewed
+5. Continue where the previous session left off
+
+## Multi-Document
+
+When multiple documents are open, always pass `documentId` explicitly — omitting it targets the active document, which may have changed since your last call. Use `tandem_listDocuments` to see what's available. Cross-reference by reading both docs via `tandem_getTextContent({ documentId: "..." })` and annotating the relevant one.