tandem-editor 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## \[Unreleased]
 
+## \[0.9.1] - 2026-05-01
+
+Hotfix patch bundling ADR-027 surface cleanup and file-I/O correctness fixes before the v0.10.0 Svelte conversion. All changes are patch-class; no MCP API changes.
+
+### Fixed
+
+- **Imported Word reviewer comments now surface to Claude by default (#482)** — `.docx` reviewer comments are imported as `author: "import"`, `type: "comment"` (was `type: "note"` in the unreleased PR #474 plan). Reverts the `tandem_getAnnotations` `includeImports` opt-in introduced in PR #474 — Claude can read imported comments alongside its own without an explicit flag, which matches the .docx review workflow. The opt-in plumbing (`includeImports` parameter, `importsExcluded` response field) is removed. Existing on-disk records with `author: "import", type: "note"` migrate transparently on read via `sanitizeAnnotation`; on next import the durable record is rewritten in place. Safe because PR #474 was never tagged in a release.
+- **Markdown tables preserved across Tiptap round-trip (#379)** — bidirectional MDAST↔Y.Doc table conversion added to `mdast-ydoc.ts`. Tables with mixed column alignment, inline marks in cells, and empty cells all survive load/save cycles. Flat-offset alignment preserved so annotations anchored after a table resolve correctly.
+- **HTML blocks and insertion-order fixed in mdast-ydoc (#496)** — raw HTML blocks (`<div>`, `<details>`, etc.) now round-trip as `html` nodes instead of being dropped. Insertion-order bug in `blockToYxml` fixed — the two-pass Y.XmlText attach-before-populate pattern now applied uniformly to all block types.
+- **Channel shim per-request timeouts (#364)** — event bridge and `run.ts` now use bounded request-response fetches with split SSE handshake/body watchdogs and a 1 MB SSE frame buffer cap. `tandem_reply` returns a structured timeout error instead of hanging indefinitely.
+- **Sanitize coercions routed to migration-log (#483)** — lossy ADR-027 type coercions in `sanitize.ts` (e.g. `flag` → `note`) now emit a `migration-log.ts` entry (once per doc/kind) instead of silently rewriting records, restoring the forensic trail for ADR-027 transitions.
+- **Doc hash required for collection logs (#495)** — annotation collection log entries now require a `docHash` field, preventing cross-document log pollution from unkeyed writes.
+- **Standalone monitor gated on backend readiness (#491)** — `dev:standalone` waits for the backend health endpoint before starting the monitor, eliminating the startup race that caused spurious connection errors.
+
+### Tests
+
+- **E2E toolbar regression guard (#484)** — Playwright coverage for the redesigned toolbar (ADR-027 note/comment/highlight flow), including a regression guard for the note button empty-annotation bug (#480).
+
 ## \[0.9.0] - 2026-04-28
 
 ### Breaking Changes (MCP)
@@ -17,6 +35,9 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 - **`tandem_getContent` removed (#259)** — superseded by `tandem_getTextContent`.
 - **`tandem_getSelections` removed (#259)** — superseded by `tandem_checkInbox`.
 - **`tandem_setStatus` merged into `tandem_status` (#259)** — `tandem_status` now accepts optional write params (`text`, `focusParagraph`, `focusOffset`). When params are present it writes to awareness; when absent it reads.
+- **`tandem_flag` deprecated (ADR-027, #473)** — returns a `DEPRECATED` error stub. Use `tandem_comment` instead. Hard-remove in v0.10.0.
+- **`tandem_highlight` deprecated (ADR-027, #473)** — returns a `DEPRECATED` error stub. Highlights are user-only. Hard-remove in v0.10.0.
+- **Annotation `directedAt` field removed (ADR-027, #473)** — silently ignored on input; stripped from on-disk records via `sanitizeAnnotation` and the `normalizeAnnotation` fast path on read.
 
 ### Added
 
@@ -29,6 +50,8 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 - **Highlight palette migration (#450)** — palette switched from 5 colors to 4 (yellow/green/blue/pink). `LEGACY_COLOR_MAP` migrates `red` → `yellow`, `purple` → `blue` on annotation load.
 - **CI stdio smoke test (#341)** — GitHub Actions step validates the Cowork stdio bridge (`scripts/ci/stdio-smoke.mjs`) on every push.
 - **`__MCP_SDK_VERSION__` build-time injection** — tsup reads the real SDK version from the package root (not the CJS type marker) and injects it at build time.
+- **`tandem_getAnnotations` `includeImports` opt-in (ADR-027, #473)** — accepts `includeImports: true` to surface `author: "import"` reviewer comments imported from `.docx` files. Default still excludes them so the user triages first. When imports are filtered out, the response includes `importsExcluded: N` so Claude can prompt the user to opt in.
+- **Deprecated-tool user notifications (ADR-027, #473)** — `tandem_highlight`, `tandem_flag`, and `tandem_suggest` stubs now `pushNotification` a warning toast in addition to returning the `DEPRECATED` mcpError, so the user sees what Claude tried.
 
 ### Fixed
 
@@ -39,11 +62,16 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 - **Annotation recovery guard hardening** — narrowed guard scope for edge cases in session restore.
 - **Event-bridge error handling** — uncaught errors in SSE delivery no longer crash the event loop.
 - **MCP SDK version resolution** — `require("@modelcontextprotocol/sdk/package.json")` resolves to `dist/cjs/package.json` (a CJS type marker without `version`); build now walks back past `dist/` to find the real version.
+- **Silent-migration logging (ADR-027, #473)** — `parseAnnotationDoc`, `migrateToV1`, and the `directedAt` strip fast path now log via the new `migration-log.ts` module (once per `${docHash}:${kind}`) instead of silently rewriting v0 records. Restores forensic trail for the v0→v1 transition.
+- **`normalizeReply` validation (#473)** — replies are now Zod-validated before being merged; malformed entries are dropped + logged instead of poisoning the envelope.
 
 ### Changed
 
 - **Redesign gap audit resolved (#439)** — 7 product decisions documented in ADR-026. Design response prompt at `docs/claude-design-response-prompt.md`.
 - **Distribution items deferred** — #316 (macOS/Linux Cowork auto-setup), #317 (cross-platform firewall scoping), #322 (network-type detection) moved to v0.13.0. Requires macOS/Linux validation hardware.
+- **Annotation type model unified to audience-based (ADR-027, #473)** — `flag` → `note`. Three types now: `highlight` (visual marker), `note` (private), `comment` (sent to Claude). Channel observer filters notes from SSE — they never reach Claude. `checkInbox` returns only `comment` annotations.
+- **Note toolbar UX (#480)** — Note button now opens an inline input mirroring the Comment flow.
+- **Note card visual distinction (#481)** — amber border + warning-bg tint distinguishes notes from comments in the side panel.
 
 ### Internal
 
@@ -132,14 +160,14 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 
 - **Annotation GC race on startup (#334)** — `cleanupOrphanedAnnotationFiles` previously ran as a `.then()` chain during boot, racing the boot-path doc opens. On upgrade paths where `sample/welcome.md` or `CHANGELOG.md` hadn't been opened in 30+ days, the GC could unlink the annotation file between read intent and the actual read, silently returning an empty doc. Now `await`-ed before all boot-path opens.
 - **Settings Popover extends out of view (#306)** — centered the popover in the viewport with `transform: translate(-50%, -50%)` and added `maxHeight: calc(100vh - 32px)` + `overflowY: auto` so it is always fully visible and internally scrollable on short screens.
-- **Dark-mode&#x20;****\*-bg****&#x20;tokens inconsistent (#307)** — `--tandem-success-bg` and `--tandem-warning-bg` in dark mode were hand-coded hex while `--tandem-error-bg` used `color-mix`. All three now use `color-mix(in srgb, var(--tandem-<semantic>) 15%, var(--tandem-surface))` for consistency with light-mode behavior.
+- **Dark-mode `*-bg` tokens inconsistent (#307)** — `--tandem-success-bg` and `--tandem-warning-bg` in dark mode were hand-coded hex while `--tandem-error-bg` used `color-mix`. All three now use `color-mix(in srgb, var(--tandem-<semantic>) 15%, var(--tandem-surface))` for consistency with light-mode behavior.
 - **stdio bridge silent-failure paths (#336 partial)** — three paths in `src/cli/mcp-stdio.ts` (preflight exit, `http.onclose`, `http.start()` TOCTOU) previously closed stdio without writing a JSON-RPC error, producing "tools never appear in Cowork" with no diagnostics. All three now synthesize `-32000` for any in-flight request ID before exit. Remaining #336 items (channel-shim tests, Windows npx smoke, nits) carry to v0.7.0.
 
 ### Changed
 
 - **Annotation module internals** — extracted `mergeMap<T>` helper (#324), promoted `UPLOAD_PREFIX` to shared constants (#327), centralized app-data dir resolution in `platform.ts` (#328), extracted `ReplyAuthorSchema`, trimmed module headers, and dropped unused `docContexts` map (#332). No user-facing behavior changes.
-- **Annotation serialization upgrades legacy&#x20;****type****&#x20;values on write** (#329) — records with non-canonical `type` (`"suggestion"` / `"question"` / anything outside `highlight` / `comment` / `flag`) are now routed through `sanitizeAnnotation` during snapshot serialization, which rewrites them to `"comment"`. **One-way lossy migration:** users with legacy-type annotations will see `type` flip to `"comment"` on the next durable write for that document — the original distinction between `suggestion` and `question` is not recoverable.
-- **migrateToV1****&#x20;reports drop counts** (#330) — `migrateToV1(raw)` now returns `{ doc, droppedAnnotations, droppedReplies }` so future production callers can surface lossy upgrades to users rather than silently discarding malformed records. No production caller exists yet; a follow-up will wire drop counts to `npm run doctor` or a toast when the first caller lands.
+- **Annotation serialization upgrades legacy `type` values on write (#329)** — records with non-canonical `type` (`"suggestion"` / `"question"` / anything outside `highlight` / `comment` / `flag`) are now routed through `sanitizeAnnotation` during snapshot serialization, which rewrites them to `"comment"`. **One-way lossy migration:** users with legacy-type annotations will see `type` flip to `"comment"` on the next durable write for that document — the original distinction between `suggestion` and `question` is not recoverable.
+- **`migrateToV1` reports drop counts (#330)** — `migrateToV1(raw)` now returns `{ doc, droppedAnnotations, droppedReplies }` so future production callers can surface lossy upgrades to users rather than silently discarding malformed records. No production caller exists yet; a follow-up will wire drop counts to `npm run doctor` or a toast when the first caller lands.
 
 ### Internal
 
@@ -184,9 +212,9 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 
 ### Fixed
 
-- **Monitor preserves last-known&#x20;****documentId** — doc-less events (e.g. `chat:message`) no longer blank out the tracked document, so the shutdown awareness clear always targets a valid document.
+- **Monitor preserves last-known `documentId`** — doc-less events (e.g. `chat:message`) no longer blank out the tracked document, so the shutdown awareness clear always targets a valid document.
 - **Monitor exits 1 on shutdown awareness failure** — if the final `clearAwareness` POST fails during SIGINT/SIGTERM, the monitor exits with a non-zero status rather than silently succeeding.
-- **/api/setup****&#x20;returns accurate status codes** — 207 on partial failure (some targets configured, some failed) and 500 on total failure, instead of always returning 200.
+- **`/api/setup` returns accurate status codes** — 207 on partial failure (some targets configured, some failed) and 500 on total failure, instead of always returning 200.
 - **Checkpoint after stdout write** — `lastEventId` is only advanced after `process.stdout.write` returns, so EPIPE on a closed pipe no longer silently skips an event on reconnect.
 - **Async EPIPE surfaces as exit(1)** — `process.stdout.on('error')` listener now catches asynchronous EPIPE (plugin host closes pipe mid-stream); monitor exits 1 instead of silently advancing `lastEventId` past lost events.
 - **Defensive exit on monitor fallthrough** — the retry loop exits 1 if it ever terminates without hitting the explicit exhaustion path.
@@ -196,7 +224,7 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 ### Added
 
 - **Claude Code plugin support** — monitor-based event push (`src/monitor/index.ts`) gives real-time notifications without polling or the channel shim. Install via `claude plugin marketplace add bloknayrb/tandem`.
-- **--with-channel-shim****&#x20;opt-in** — `tandem setup --with-channel-shim` writes the legacy `tandem-channel` MCP entry for setups that can't install the plugin.
+- **`--with-channel-shim` opt-in** — `tandem setup --with-channel-shim` writes the legacy `tandem-channel` MCP entry for setups that can't install the plugin.
 
 ### Changed
 
@@ -210,7 +238,7 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 - **Exponential backoff on reconnect** — monitor reconnects use 2s/4s/8s/16s/30s backoff instead of a fixed 2s delay.
 - **SIGINT/SIGTERM clears awareness** — monitor posts a final `clearAwareness` before exit so the "Claude is active" indicator doesn't hang in the browser.
 - **Per-route fetch timeouts** — `AbortSignal.timeout` enforces budgets per route (connect 10s, mode 2s, awareness 5s, error report 3s) to prevent hung SSE connects or mode lookups from stalling the monitor.
-- **SSE parse errors don't advance&#x20;****lastEventId** — JSON parse failures and schema validation errors are logged with event ID + frame tail but do not advance `lastEventId`, so bad events are re-delivered on reconnect rather than silently dropped.
+- **SSE parse errors don't advance `lastEventId`** — JSON parse failures and schema validation errors are logged with event ID + frame tail but do not advance `lastEventId`, so bad events are re-delivered on reconnect rather than silently dropped.
 - **SKILL.md corrected** — `question` annotation guidance now uses `type === 'comment' && directedAt === 'claude' && author === 'user'`; all 5 highlight colors listed (yellow, red, green, blue, purple).
 
 ## \[0.5.0] - 2026-04-13
@@ -277,7 +305,7 @@ This is the last breaking-change window before semver lock. MCP tool count: 31
 - **Annotation type unification:** Three semantically identical types (`comment`, `suggestion`, `question`) collapsed into a single `comment` type with optional `suggestedText` and `directedAt` fields. `AnnotationTypeSchema` reduced from 5 values to 3: `highlight`, `comment`, `flag`. (#193, #245, #255)
 - **Toolbar:** Three annotation buttons (Comment, Suggest, Ask Claude) replaced with a single Comment button with "Replace" and "@Claude" toggles (#193)
 - **Side panel filters:** "Suggestions" → "With replacement", "Questions" → "For Claude" (#193)
-- **sanitizeAnnotation()****&#x20;moved to&#x20;****src/shared/sanitize.ts** — now available to both server and client code. Client-side Y.Map reads are sanitized to handle legacy session data. (#255)
+- **`sanitizeAnnotation()` moved to `src/shared/sanitize.ts`** — now available to both server and client code. Client-side Y.Map reads are sanitized to handle legacy session data. (#255)
 
 ### Added
 

package/README.md

@@ -99,7 +99,7 @@ claude
 Then pick one of two ways to keep the conversation flowing:
 
 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 `/loop` (hands-off).** Ask Claude to check in on its own using the `/loop` skill:
+2. **Background polling with ****/loop**** (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
    ```
@@ -129,10 +129,10 @@ curl http://localhost:3479/health
 git clone https://github.com/bloknayrb/tandem.git
 cd tandem
 npm install
-npm run dev:standalone   # starts server (:3478/:3479) + editor client (:5173)
+npm run dev:standalone   # starts backend (:3478/:3479), editor client (:5173), and monitor
 ```
 
-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.
+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.
 
 </details>
 
@@ -197,7 +197,7 @@ See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#
 ## Documentation
 
 - **[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 + channel API endpoints
+- [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
@@ -206,17 +206,17 @@ See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#
 
 ## 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) |
+| 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
 
@@ -248,21 +248,21 @@ Both entries are cross-platform — no platform-specific configuration needed.
 
 All optional — defaults work out of the box.
 
-| 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 |
+| 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.
 
@@ -279,6 +279,8 @@ Tandem kills stale processes on :3478/:3479 at startup. If another app uses thos
 **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.
 
+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.
+
 **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.
 
@@ -287,17 +289,17 @@ On first run, `sample/welcome.md` auto-opens. If you've cleared sessions or dele
 
 ## Development
 
-| Command | What it does |
-|---------|-------------|
-| `npm run dev:standalone` | **Recommended** — both frontend + backend (via concurrently) |
-| `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) |
+| 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)                                          |
 
 **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.