tandem-editor 0.11.2 → 0.13.0

package/README.md

@@ -1,310 +1,213 @@
 <p align="center">
-  <img src="docs/assets/banner.png" alt="Tandem — Collaborative AI-Human Document Editor" width="800">
+  <a href="https://www.npmjs.com/package/tandem-editor"><img src="https://img.shields.io/npm/v/tandem-editor?label=npm" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-BUSL--1.1-blue" alt="License: BUSL-1.1"></a>
+  <a href="https://github.com/bloknayrb/tandem/releases/latest"><img src="https://img.shields.io/github/v/release/bloknayrb/tandem?label=release" alt="Latest release"></a>
 </p>
 
-Have you ever been working on a piece of writing with an LLM and caught yourself copy-pasting the same paragraph into the chat for the fifth time just so the model knows what you're talking about? That's the friction Tandem eliminates. Open a file directly, or just tell Claude "let's work on my draft in tandem" — the document appears in the editor, and from that point on you highlight text and Claude sees it directly. No pasting, no "here's the paragraph I mean," no losing your place.
+**An editor where you and an AI work on the same document at the same time.**
 
-And because Tandem hooks into Claude as an MCP server, you're not stuck in some stripped-down document-editing silo. It's the full Claude — with all its knowledge, your conversation context, and every tool it has access to — just now it can also see and edit your document.
+Tandem is a document editor that lets you and an AI work on the same file together. You highlight a passage. The AI sees what you highlighted and can ask about it, comment on it, or propose changes that appear as cards beside your document. You decide what to keep.
 
-## Why Tandem?
+Tandem is approaching v1.0 and ships continuous improvements. See [CHANGELOG.md](CHANGELOG.md) for what is in the latest release.
 
-- **No more copy-paste ping-pong.** Select text in the editor, and Claude reads your selection directly. Ask "what do you think of this?" or "make this more concise" — Claude knows exactly which text you mean.
-- **Your full LLM, not a toy editor.** Tandem connects via MCP, so Claude keeps all its knowledge, all its tools, and your full conversation context. Need it to cross-reference your document against a codebase, a URL, or another file? It can — it's still Claude.
-- **Iterate in place.** Claude can suggest rewrites, leave comments, flag issues, and edit text — all appearing as annotations you accept, dismiss, or tweak right in the document.
+## Contents
 
-## Quick Start
+- [What Tandem does](#what-tandem-does)
+- [See it in action](#see-it-in-action)
+- [Who Tandem is for](#who-tandem-is-for)
+- [Getting started](#getting-started)
+- [How you work with Tandem](#how-you-work-with-tandem)
+- [Privacy and trust](#privacy-and-trust)
+- [Where Tandem is headed](#where-tandem-is-headed)
+- [Documentation](#documentation)
+- [License](#license)
+- [For developers and contributors](#for-developers-and-contributors)
+  - [Architecture overview](#architecture-overview)
+  - [The MCP integration policy](#the-mcp-integration-policy)
+  - [MCP tools at a glance](#mcp-tools-at-a-glance)
+  - [Channel push and real-time updates](#channel-push-and-real-time-updates)
+  - [Development setup](#development-setup)
+  - [Tech stack](#tech-stack)
+  - [How to contribute](#how-to-contribute)
 
-### Option A: Desktop App
+## What Tandem does
 
-Download the installer for your platform from the [latest release](https://github.com/bloknayrb/tandem/releases/latest).
+Most people use AI on a document by copying a passage into a chat window, asking a question, and pasting the answer back. Tandem closes that loop. The AI sits beside the document you are editing and reads from it directly.
 
-The desktop app bundles everything — no Node.js required. It auto-configures Claude Code on launch, manages the server as a background process, and updates itself automatically. Just install and open.
+When you highlight text, the AI sees the selection as you make it. You can ask it for a rewrite, a summary, a check on tone, or a second opinion. Its suggestions appear as cards next to the document. Accept them, set them aside, or reply to ask for something different.
 
-### Option B: npm Global Install
+Tandem is built to work with Anthropic's Claude out of the box. Other AI tools can also connect. See [the developer section](#the-mcp-integration-policy) below for the details of which clients work and which are tested first.
 
-Requires **Node.js 22+** ([download](https://nodejs.org)) and **Claude Code** (`npm install -g @anthropic-ai/claude-code`).
+## See it in action
 
-```bash
-npm install -g tandem-editor
-tandem setup     # registers MCP tools + installs Claude Code skill
-tandem           # starts server + opens editor
-```
-
-`tandem setup` auto-detects Claude Code and Claude Desktop, writes MCP configuration, and installs a skill (`~/.claude/skills/tandem/SKILL.md`) that teaches Claude how to use Tandem's tools effectively. Re-run after upgrading (`npm update -g tandem-editor && tandem setup`).
-
-### Quickstart: Claude Code plugin (recommended)
-
-Install the plugin to expose Tandem's tools and real-time event stream into Claude Desktop chats **and** Cowork VM sessions:
-
-```bash
-claude plugin marketplace add bloknayrb/tandem
-claude plugin install tandem@tandem-editor
-```
-
-**Tandem must be running on the host before the plugin can do anything.** The plugin spawns two stdio MCP processes (`tandem mcp-stdio` and `tandem channel`) that proxy to `http://localhost:3479`. If the server isn't up they fail fast and log "Tandem server not reachable at …". Start the Tauri desktop app or run `tandem start` on the host first, then open Claude.
-
-### Legacy stdio channel shim
-
-If you can't install the plugin, use the older channel shim:
-
-```bash
-tandem setup --with-channel-shim
-```
-
-This writes a `tandem-channel` entry to your Claude Code MCP config. Start Claude Code with:
-
-```bash
-claude --dangerously-load-development-channels server:tandem-channel
-```
-
-Don't combine this with the plugin — both subscribe to `/api/events` and you'll get duplicate notifications for every event.
+<p align="center">
+  <img src="docs/screenshots/01-editor-overview.png" alt="The Tandem editor with a document open on the left and a panel of AI suggestion cards on the right" width="800">
+</p>
 
-### Connect Claude Code
+*The main view. Your document fills the left side. The chat panel and any suggestions from the AI sit on the right.*
 
-For the full Tandem experience, start Claude Code with the **channel push** flag:
+<p align="center">
+  <img src="docs/screenshots/03-side-panel.png" alt="A close-up of suggestion cards beside the document, including a replacement card showing the original text in red strikethrough and the proposed text in green" width="500">
+</p>
 
-> **Desktop app users:** Claude Code is configured automatically on every launch — skip `tandem setup` and just start Claude Code. The `tandem_*` tools will be available immediately.
+*A suggestion from the AI. Your current text and the proposed replacement appear together. Buttons let you accept the change or set it aside.*
 
-```bash
-claude --dangerously-load-development-channels server:tandem-channel
-```
+## Who Tandem is for
 
-This is the magic-sauce mode — and it's the one I'd recommend you run with. The channel shim pushes events (selections, annotations, chat) to Claude over SSE the moment they happen, so Tandem genuinely feels like there's another person on the other end of the document: someone watching what you highlight, reacting to edits you accept, and chiming in on a paragraph the instant you select it, the way a collaborator on a Google Doc would. The `--dangerously-load-development-channels` flag is an experimental Claude Code feature, which is why it isn't on by default — but turning it on is what makes the whole experience click.
+- If you draft long-form writing and want a second reader for tone and structure.
+- If you review contracts, policies, RFP responses, or compliance filings and want a faster pass.
+- When a colleague hands you a report to mark up.
+- When the AI wrote a draft and you need to decide what to keep.
 
-**Recommended layout:** snap the Claude Code terminal to one side of your screen and the Tandem editor window to the other. You'll be flipping attention between them constantly, and having both visible is what makes the side-by-side-collaborator feeling land.
+## Getting started
 
-Then try:
+### System requirements
 
-```
-"Open sample/welcome.md and review it with me"
-```
+Windows 10 version 22H2 or Windows 11. macOS 12 (Monterey) or later. Linux with glibc 2.31 or later (Ubuntu 20.04+, Debian 11+, Fedora 34+). On Windows, the first launch may show a "Windows protected your PC" warning until the installer's signing certificate accumulates SmartScreen reputation. See [docs/troubleshooting.md#windows-smartscreen-warning](docs/troubleshooting.md#windows-smartscreen-warning) for the steps to dismiss it.
 
-Claude calls `tandem_open`, the document appears in the editor, and you're ready to collaborate.
+### Download the desktop app (recommended)
 
-#### The core loop — no copy/paste
+Pick the installer for your platform from the [latest release](https://github.com/bloknayrb/tandem/releases/latest). Windows, macOS, and Linux builds are available.
 
-1. Highlight a paragraph in the editor.
-2. With channels on, Claude often reacts before you even say anything. Otherwise, just type what you want in the terminal: *"what do you think of this paragraph?"* or *"rewrite this to be more concise"*.
-3. Claude reads your selection directly from the shared Tandem state (via `activity.selectedText` on `tandem_checkInbox`). You never paste the passage into the terminal.
-4. Claude replies in the Tandem chat sidebar (`tandem_reply`) or drops annotations on the document (`tandem_annotate` / `tandem_suggestEdit`), which you can accept, dismiss, or edit in the side panel.
+The desktop app bundles the editor, the server it talks to, and storage for the connection token. Updates land automatically. Double-clicking a `.md`, `.txt`, or `.html` file opens it directly in Tandem.
 
-#### Prefer not to use the experimental flag?
+### What you get
 
-You don't have to turn on channel push — every feature of Tandem works without it. You lose the "Claude reacts on its own" magic, but Claude still sees every selection, annotation, and chat message. Start Claude Code normally:
+- Multiple documents open in tabs, with `.md`, `.txt`, `.html`, and `.docx` support (Word files open in review-only mode).
+- A scratchpad (`Ctrl+N`) for drafts you do not want to save to disk.
+- A command palette (`Ctrl+Shift+P`) for quick actions.
+- Find and replace, including across all open tabs.
+- An outline panel for navigating long documents.
+- Light and dark themes.
+- Keyboard navigation through pending suggestions: `Alt+]` and `Alt+[` to move between them, `Ctrl+Enter` to accept, `Ctrl+Shift+Enter` to dismiss.
 
-```bash
-claude
-```
+### Other ways to install
 
-Then pick one of two ways to keep the conversation flowing:
+If you use a terminal, you can also install Tandem with `npm install -g tandem-editor`, then run `tandem setup` once and `tandem` to launch. This works the same as the desktop app and is mostly useful if you already have Node.js installed.
 
-1. **Just chat in the terminal (simplest).** Every time you send Claude a message, it has a chance to call `tandem_checkInbox` and pick up your latest selection, any annotations you accepted or dismissed, and any chat messages from the Tandem sidebar. Zero setup — this is how it works out of the box. With Tandem and the terminal snapped side by side, the loop feels surprisingly natural; Claude just reacts when you nudge it rather than spontaneously.
-2. **Background polling with&#x20;****/loop****&#x20;(hands-off).** Ask Claude to check in on its own using the `/loop` skill:
-   ```
-   /loop 30s check tandem inbox and respond to any new messages
-   ```
-   Claude polls every 30 seconds — responses lag by up to that interval, but you don't have to prompt it yourself.
+### Got stuck
 
-Either way, Claude reads the exact same information (selections, annotations, chat) through the same `tandem_checkInbox` tool. The only thing channels change is *when* Claude finds out something happened — not *whether* it can see it.
+See [docs/troubleshooting.md](docs/troubleshooting.md) for common problems and how to resolve them.
 
-### Verify
+## How you work with Tandem
 
-```bash
-npm run doctor    # checks Node.js, MCP config, server health, ports
-```
+1. Open a document in Tandem.
+2. Start Claude. Tandem and Claude connect automatically once you have run setup once.
+3. Type a question in the chat panel, or highlight text in the document to focus the AI on a passage. The AI sees what you highlight as you highlight it.
+4. The AI's suggestions appear as cards beside the document. You decide what to accept.
+5. Save when you are finished.
 
-Or check the raw health endpoint:
+See [docs/workflows.md](docs/workflows.md) for examples of how this looks in daily use.
 
-```bash
-curl http://localhost:3479/health
-# → {"status":"ok","version":"0.8.0","transport":"http","hasSession":false}
-```
+## Privacy and trust
 
-`hasSession` becomes `true` once Claude Code connects.
+- Tandem itself runs on your computer and stores your documents on your disk. We do not operate any servers that hold your files.
+- When you ask the AI to do something, the text you share with it goes to whichever AI service you are using. For example, if you connect Claude, the text goes to Anthropic under their terms. Tandem does not relay or copy your document anywhere else.
+- Tandem includes a private notes feature. Notes you mark as private are stripped from every response the AI sees ([ADR-027](docs/decisions.md)).
+- Tandem does not collect telemetry or analytics.
 
-<details>
-<summary><strong>Development Setup</strong> (contributing / building from source)</summary>
+See [docs/security.md](docs/security.md) for the full security model.
 
-```bash
-git clone https://github.com/bloknayrb/tandem.git
-cd tandem
-npm install
-npm run dev:standalone   # starts backend (:3478/:3479), editor client (:5173), and monitor
-```
+## Where Tandem is headed
 
-Open <http://localhost:5173> — you'll see `sample/welcome.md` loaded automatically on first run. The `.mcp.json` in the repo configures Claude Code automatically when run from this directory.
+Tandem is on the way to a v1.0 release. Recent releases added support for multiple AI providers and in-app configuration for connections and models. Work still in progress covers improvements to how Word documents round-trip through the editor, turnkey setup on macOS and Linux, and final polish. The full plan lives in [docs/roadmap.md](docs/roadmap.md).
 
-</details>
+## Documentation
 
-## Using Tandem
+- [docs/user-guide.md](docs/user-guide.md) for a longer walkthrough of the editor.
+- [docs/workflows.md](docs/workflows.md) for daily usage patterns.
+- [docs/troubleshooting.md](docs/troubleshooting.md) for when something goes wrong.
+- [docs/positioning.md](docs/positioning.md) for the longer story of why Tandem exists.
+- [docs/decisions.md](docs/decisions.md) for design decisions (ADRs).
+- [docs/roadmap.md](docs/roadmap.md) for what is coming.
+- [docs/architecture.md](docs/architecture.md) for diagrams and the file map.
+- [docs/mcp-tools.md](docs/mcp-tools.md) for the MCP tool reference.
+- [docs/security.md](docs/security.md) for the security model.
+- [docs/configuration.md](docs/configuration.md) for advanced configuration.
+- [docs/cli.md](docs/cli.md) for CLI command reference.
+- [CHANGELOG.md](CHANGELOG.md) for release notes.
 
-You point at text, Claude sees it. Here's how that plays out day-to-day:
+## License
 
-- **Open a document.** Ask Claude (`"let's work on notes.md in tandem"`), drag a file onto the editor, or click the **+** in the tab bar. `.md`, `.txt`, `.html`, and `.docx` (review-only) are supported.
-- **Point at what you mean.** Select text in the editor and ask Claude about "this paragraph" in the terminal — or just wait for Claude to react if you have channels on. Claude reads your selection directly, no copy-paste needed. Hold the selection for about a second so it registers (dwell-time gating filters out incidental clicks).
-- **Iterate on Claude's response.** Claude's suggestions appear as annotations in the side panel — accept, dismiss, edit, or ask follow-up questions. Each round refines the text without you ever leaving the document. Press **Ctrl+Shift+R** for keyboard review mode: **Tab** to navigate, **Y** accept, **N** dismiss, **E** edit, **Z** undo within a 10-second window.
-- **Heads-down vs collaborative.** Toggle **Solo** mode when you want to write without interruptions — Tandem queues non-urgent annotations until you flip back to **Tandem** mode. Both `tandem_status` and `tandem_checkInbox` return the current mode so Claude adapts its behavior automatically.
-- **Save.** Ask Claude ("save the file"), press the save button, or let session auto-persistence take over — your documents and annotations survive server restarts either way.
+Tandem is free to use. It is licensed under the Business Source License 1.1 (BUSL-1.1); see [LICENSE](LICENSE) for the terms.
 
-## Features
+---
 
-Everything in Tandem is built around one idea: you work in the document, Claude works alongside you, and neither of you has to leave your surface to stay in sync.
+## For developers and contributors
 
-### Chat
+### Architecture overview
 
-Send messages to Claude alongside your document. Select text before sending to attach it as context — Claude sees exactly what you mean. Clicking an anchored selection later scrolls back to that passage.
+Three layers: the editor (Tiptap inside a Tauri desktop app or a browser), the Tandem server (Hocuspocus on port 3478 for collaborative edits and an MCP HTTP server on port 3479 for AI tool calls), and the AI client (Claude Code or any other MCP-capable client). The full file map and data flows live in [docs/architecture.md](docs/architecture.md).
 
-### Annotations
+### The MCP integration policy
 
-This is how Claude's feedback shows up in the document. Claude adds highlights, comments, suggestions, and flags directly on the text. Suggestion cards show a visual diff — original text in red strikethrough, replacement in green. The side panel lists all annotations with filtering by type, author, and status. Accept, dismiss, or edit each one individually — or use bulk actions to process them in batches.
+The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard for AI clients to talk to tools and data sources. Tandem exposes its document and annotation surface over MCP, which is how AI clients like Claude read and modify the file you are editing.
 
-### Review Mode
+The integration policy is set by [ADR-038](docs/decisions.md#adr-038-mcp-first-integration-policy-claude-as-default-integration):
 
-Press **Ctrl+Shift+R** to enter keyboard review mode. Navigate with **Tab**, accept with **Y**, dismiss with **N**, examine with **E**. A 10-second undo window with a visual countdown lets you reverse accidental accepts. Shortcut hints appear below the Review button.
+> Tandem's integration contract is **MCP**. The default integration is **Claude** (Claude Code + Claude Desktop) — it's what we recommend, what we test against, and it ships with the channel push, cowork, plugin monitor, and auto-launcher features. Any MCP-capable client can connect to the same MCP HTTP endpoint and use the same 26 tools, but the Claude-specific transports don't apply. Other clients are **best-effort, MCP-contract-compatible, not validated** today.
+>
+> **Integration setup** runs through the integration setup wizard (#477 PR 3). Today's transitional behavior — Tandem auto-writing its MCP entry to Claude's config files on Tauri startup — is **deprecated when the wizard ships**. Going forward, every integration (Claude included) is configured via the wizard, never silently.
 
-### More
+Client compatibility:
 
-- **Full LLM via MCP** — Claude connects through MCP tools, so it retains all its knowledge, conversation context, and tool access while working on your document
-- **Multi-document tabs** — open `.md`, `.txt`, `.html`, `.docx` files side by side; drag to reorder
-- **.docx review-only mode** — open Word documents for annotation; imported Word comments appear alongside Claude's
-- **Session persistence** — documents and annotations survive server restarts
-- **Solo / Tandem mode** — flip to Solo when you want to write heads-down; Tandem queues non-urgent annotations until you're ready
-- **Real-time channel push** *(recommended)* — with the `--dangerously-load-development-channels` Claude Code flag, selections, annotations, and chat push to Claude instantly, making Tandem feel like a live collaborator watching over your shoulder
-- **Keyboard shortcuts** — press `?` for the full reference
-- **Unsaved-changes indicator** — dot on tab title when a document has pending edits
-- **Configurable display name** — set your name so Claude knows who's reviewing
-- **Atomic file saves** — write to temp, then rename, preventing partial writes
-- **E2E tested** — Playwright tests cover the annotation lifecycle end-to-end
-- **Authorship text coloring** — blue for your edits, orange for Claude's, toggled per-document
-- **Threaded annotation replies** — back-and-forth conversation on any annotation
-- **Auto-save** — documents save on change; Ctrl+S for manual trigger
-- **Settings popover** — Light/Dark/System theme, text size (S/M/L), reduce motion, display name (Ctrl+,)
-- **Auth tokens for LAN exposure** — bind to `0.0.0.0` with auto-generated tokens; `tandem rotate-token` for rotation
-- **Durable annotation persistence** — annotations survive server restarts independently of session files
-- **Claude Code plugin** — `tandem mcp-stdio` + `tandem channel` bridge Tandem into Cowork and Claude Desktop
+| AI surface | Status |
+|---|---|
+| **Claude Code** (local CLI) | Default. Validated. Channel push supported. |
+| **Claude Desktop** (local app) | Supported via the Cowork bridge. Channel push N/A. |
+| **claude.ai web chat** | Not supported. Would require exposing the local server publicly via a tunnel, which is outside scope. |
+| **Other MCP-capable clients** (Cursor, Continue.dev, LM Studio, Ollama, …) | Best-effort, MCP-contract-compatible, not validated. |
+| **Non-MCP AIs** (ChatGPT direct, Gemini direct, etc.) | Not supported today. Multi-provider support is in progress via the Agent SDK adapter ([ADR-038 §3](docs/decisions.md#adr-038-mcp-first-integration-policy-claude-as-default-integration)); not yet shippable. |
 
-## Where Tandem is headed
+### MCP tools at a glance
 
-Since the v0.4.0 desktop app launch, Tandem has added auth tokens for LAN exposure (v0.7.0), a Claude Code plugin bridge for Cowork and Claude Desktop (v0.6.0+), durable annotation persistence, settings with Light/Dark/System theming, authorship text coloring, and coordinate system correctness fixes with semantic token enforcement (v0.8.0). A few directions on the radar for later releases:
+26 active tools across five capability areas. Full reference: [docs/mcp-tools.md](docs/mcp-tools.md).
 
-- **High-fidelity .docx round-trip** — current `.docx` support is review-only; production export is planned so you can stay in Tandem through the final draft.
-- **Exportable annotated documents** — PDF (and eventually `.docx`) with annotations baked in, so you can share reviewed drafts outside Tandem.
-- **Code editing mode** — CodeMirror 6 surface for reviewing code the same way you review prose.
-- **Standalone mode** — direct Anthropic API connection so Tandem can run without Claude Code in the loop, for users who want a pure standalone experience.
+- **Document.** Open, switch, list, close, and convert documents; read text content and outlines; save back to disk.
+- **Annotation.** Create, resolve, remove, and edit annotations; query the annotation list; export a review report.
+- **Apply.** Edit text ranges directly when an annotation is not the right surface.
+- **Navigation.** Inspect the active selection, jump to ranges, and resolve internal links.
+- **Awareness.** Read user presence and Solo/Tandem mode; check the inbox for selection events, chat messages, and annotation actions; reply in the chat sidebar.
 
-See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#known-limitations-v1) for the complete picture, including items that are explicitly out of scope for v1.
+### Channel push and real-time updates
 
-## Documentation
+Channel push delivers events (selections, annotation actions, chat messages) to the AI client over Server-Sent Events the moment they happen, so the AI does not have to poll. Two install options:
 
-- **[User Guide](docs/user-guide.md)** — How to use Tandem: editor UI, annotations, chat, review mode, keyboard shortcuts
-- [MCP Tool Reference](docs/mcp-tools.md) — 28 MCP tools (25 active, 3 deprecated stubs) + channel API endpoints
-- [Architecture](docs/architecture.md) — System design, data flows, coordinate systems, channel push
-- [Workflows](docs/workflows.md) — Claude Code usage patterns: text iteration, cross-referencing, multi-model
-- [Roadmap](docs/roadmap.md) — Phase 2+ roadmap, known issues, future extensions
-- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-024
-- [Lessons Learned](docs/lessons-learned.md) — 48 implementation lessons
-
-## CLI Commands
-
-| Command                            | What it does                                                       |
-| ---------------------------------- | ------------------------------------------------------------------ |
-| `tandem`                           | Start server and open editor (global install)                      |
-| `tandem setup`                     | Register MCP tools with Claude Code / Claude Desktop               |
-| `tandem setup --force`             | Register to default paths regardless of auto-detection             |
-| `tandem --version`                 | Show installed version                                             |
-| `tandem --help`                    | Show usage                                                         |
-| `tandem setup --with-channel-shim` | Also register the stdio channel shim                               |
-| `tandem rotate-token`              | Rotate auth token (60-second grace window)                         |
-| `tandem mcp-stdio`                 | Run as stdio MCP server (proxy to local HTTP, for plugin bridge)   |
-| `tandem channel`                   | Run the channel shim (stdio MCP for plugin's tandem-channel entry) |
-
-## MCP Configuration
-
-Tandem registers two MCP connections: **HTTP** for document tools (28 tools including annotation editing — always on), and a **channel shim** for real-time push notifications. The channel shim is what enables the live-collaborator experience described in [Connect Claude Code](#connect-claude-code) and is recommended; it activates when you start Claude Code with `--dangerously-load-development-channels server:tandem-channel`. If you'd rather not pass that experimental flag, the entry sits idle and everything still works through polling on the HTTP connection — you just lose spontaneous reactions.
-
-**Global install** (`tandem setup`): Automatically writes both entries to `~/.claude/mcp_settings.json` (Claude Code) and/or `claude_desktop_config.json` (Claude Desktop) with absolute paths. No manual configuration needed.
-
-**Development setup** (`.mcp.json`): The repo includes a `.mcp.json` that configures both entries automatically when Claude Code runs from the repo directory:
-
-```json
-{
-  "mcpServers": {
-    "tandem": {
-      "type": "http",
-      "url": "http://localhost:3479/mcp"
-    },
-    "tandem-channel": {
-      "command": "npx",
-      "args": ["tsx", "src/channel/index.ts"],
-      "env": { "TANDEM_URL": "http://localhost:3479" }
-    }
-  }
-}
+```bash
+tandem setup --with-channel-shim                           # persistent setup
+claude --dangerously-load-development-channels server:tandem-channel   # one-off
 ```
 
-Both entries are cross-platform — no platform-specific configuration needed.
+The `--dangerously-load-development-channels` flag is Claude Code's marker for unstable APIs; it becomes unnecessary when the Channels API stabilizes.
 
-## Environment Variables
+Without channel push, the AI uses `tandem_checkInbox` to pull the same events on demand. You can also ask Claude to poll periodically with `/loop 30s check tandem inbox and respond to any new messages`.
 
-All optional — defaults work out of the box.
+### Development setup
 
-| Variable                           | Default                 | Description                                                     |
-| ---------------------------------- | ----------------------- | --------------------------------------------------------------- |
-| `TANDEM_PORT`                      | `3478`                  | Hocuspocus WebSocket port                                       |
-| `TANDEM_MCP_PORT`                  | `3479`                  | MCP HTTP + REST API port                                        |
-| `TANDEM_URL`                       | `http://localhost:3479` | Channel shim server URL                                         |
-| `TANDEM_TRANSPORT`                 | `http`                  | Transport mode (`http` or `stdio`)                              |
-| `TANDEM_NO_SAMPLE`                 | unset                   | Set to `1` to skip auto-opening `sample/welcome.md`             |
-| `TANDEM_CLAUDE_CMD`                | `claude`                | Claude Code executable name (for `tandem setup` auto-detection) |
-| `TANDEM_BIND_HOST`                 | `127.0.0.1`             | Bind address for MCP HTTP (`0.0.0.0` for LAN)                   |
-| `TANDEM_AUTH_TOKEN`                | auto-generated          | Override auth token (set by Tauri; manual use rare)             |
-| `TANDEM_ALLOW_UNAUTHENTICATED_LAN` | unset                   | Set to `1` to skip token requirement on LAN bind                |
-| `TANDEM_LAN_IP`                    | auto-detected           | Explicit LAN IP for multi-homed machines                        |
-| `TANDEM_REQUEST_TIMEOUT_MS`        | `30000`                 | Per-request timeout in stdio bridge (ms)                        |
-| `TANDEM_APP_DATA_DIR`              | platform default        | Override app-data root (sessions, auth-token, annotations)      |
-| `TANDEM_ANNOTATION_STORE`          | unset                   | Set to `off` to disable durable annotation persistence          |
-
-See `.env.example` for a copy-paste template.
-
-## Troubleshooting
-
-Run `npm run doctor` for a quick diagnostic of your setup. It checks Node.js version, `.mcp.json` config, server health, and port status.
-
-**Claude Code says "MCP failed to connect"**
-Start the server first (`tandem` for global install, or `npm run dev:standalone` for dev setup), then open Claude Code. The server must be running before Claude Code probes the MCP URL. If you restart the server, run `/mcp` in Claude Code to reconnect.
-
-**Port already in use**
-Tandem kills stale processes on :3478/:3479 at startup. If another app uses those ports, set `TANDEM_PORT` / `TANDEM_MCP_PORT` to different values and update `TANDEM_URL` to match.
-
-**Channel shim fails to start**
-The `tandem-channel` entry spawns a subprocess. For global installs, `tandem setup` writes absolute paths to the bundled `dist/channel/index.js` — re-run `tandem setup` after upgrading. For dev setup, if you see `MODULE_NOT_FOUND` with a production config (`node dist/channel/index.js`), run `npm run build`. The default dev config uses `npx tsx` and doesn't require a build step.
+```bash
+git clone https://github.com/bloknayrb/tandem.git
+cd tandem
+npm install
+npm run dev:standalone   # backend (:3478, :3479) + frontend (:5173)
+```
 
-If the shim starts but logs `/api/events timed out after 10000ms`, `SSE inactivity timeout`, or `/api/channel-reply timed out after 5000ms`, the Tandem server accepted a connection but stopped responding on that path. Restart Tandem; the shim reports the timeout instead of hanging silently.
+Open <http://127.0.0.1:5173>. The repo's `.mcp.json` configures Claude Code automatically when run from this directory.
 
-**Editor shows "Cannot reach the Tandem server"**
-The editor connects to the server via WebSocket. For global installs, run `tandem` to start the server. For dev setup, use `npm run dev:standalone` (or `npm run dev:server`). The message appears after 3 seconds of failed connection.
+Verify the server is up:
 
-**Empty editor with no document**
-On first run, `sample/welcome.md` auto-opens. If you've cleared sessions or deleted the sample file, click the **+** button in the tab bar or drop a file onto the editor.
+```bash
+curl http://127.0.0.1:3479/health
+# → {"status":"ok","version":"x.y.z","transport":"http","hasSession":false}
+```
 
-## Development
+For exposing the server on a LAN, set `TANDEM_BIND_HOST` and use `tandem rotate-token` to rotate the auth token. See [docs/security.md](docs/security.md) for the full network posture.
 
-| Command                  | What it does                                                                       |
-| ------------------------ | ---------------------------------------------------------------------------------- |
-| `npm run dev:standalone` | **Recommended** — frontend + backend + monitor                                     |
-| `npm run dev:server`     | Backend only: Hocuspocus (:3478) + MCP HTTP (:3479)                                |
-| `npm run dev:client`     | Frontend only: Vite dev server (:5173)                                             |
-| `npm run build`          | Production build (`dist/server/` + `dist/channel/` + `dist/cli/` + `dist/client/`) |
-| `npm test`               | Run vitest (unit tests)                                                            |
-| `npm run test:e2e`       | Run Playwright E2E tests                                                           |
-| `npm run test:e2e:ui`    | Playwright UI mode                                                                 |
-| `cargo tauri dev`        | Tauri desktop app (dev mode with hot-reload)                                       |
-| `cargo tauri build`      | Tauri production build (installer output)                                          |
+See [docs/cli.md](docs/cli.md#npm-run-scripts-source-checkouts-only) for the full list of npm scripts.
 
-**Tauri development** requires the [Rust toolchain](https://www.rust-lang.org/tools/install) and [Tauri CLI](https://v2.tauri.app/start/prerequisites/). Web-only development (`npm run dev:standalone`) does not require Rust.
+### Tech stack
 
-**Tech Stack:** Svelte 5, Tiptap, Vite, TypeScript | Node.js, Hocuspocus (Yjs WebSocket), MCP SDK, Express | Yjs (CRDT), y-prosemirror | mammoth.js (.docx), unified/remark (.md)
+Tandem is built on [Tiptap](https://tiptap.dev) and [ProseMirror](https://prosemirror.net) (editor), [Yjs](https://yjs.dev) and [Hocuspocus](https://github.com/ueberdosis/hocuspocus) (CRDT sync), [Tauri 2](https://v2.tauri.app) (desktop), and [Svelte 5](https://svelte.dev) (UI).
 
-## License
+### How to contribute
 
-Tandem is licensed under the [Business Source License 1.1](LICENSE). See `LICENSE` for full terms.
+Open an issue first for non-trivial changes; for bug reports and small fixes, a PR is fine. Follow the workflow described in [CLAUDE.md](CLAUDE.md). Run `npm run typecheck` and `npm test` before opening a pull request.