openwriter 0.14.0 → 0.16.0

package/dist/server/versions.js

@@ -108,6 +108,24 @@ export function forceSnapshot(docId, filePath) {
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
 }
+/**
+ * Write a snapshot from an arbitrary markdown string (rather than copying
+ * the current file). Used by `restore_version` so the safety checkpoint
+ * can represent the canonical-only state (pending reverted) rather than the
+ * flattened pending+canonical body that lives on disk.
+ *
+ * Returns the timestamp the snapshot was written at.
+ */
+export function writeSnapshotMarkdown(docId, markdown) {
+    if (!docId)
+        return 0;
+    const hash = contentHash(markdown);
+    const now = Date.now();
+    ensureDocDir(docId);
+    writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
+    lastSnapshot.set(docId, { time: now, hash });
+    return now;
+}
 // ============================================================================
 // LIST / GET
 // ============================================================================

package/dist/server/workspaces.js

@@ -326,12 +326,34 @@ export function reorderWorkspaceAfter(filename, afterFilename) {
     }
     writeOrder(order);
 }
-// ============================================================================
-// CONTEXT
-// ============================================================================
-export function updateWorkspaceContext(wsFile, context) {
+const WRITING_CONTEXT_KEYS = new Set(['characters', 'settings', 'rules']);
+const ENRICHMENT_FIELDS = new Set([
+    'logline', 'domain', 'schema', 'vocab', 'relatedWorkspaces',
+    'enrichmentVolumeThreshold', 'enrichmentDriftThreshold', 'enrichmentDisabled',
+]);
+export function updateWorkspaceContext(wsFile, update) {
     const ws = getWorkspace(wsFile);
-    ws.context = { ...ws.context, ...context };
+    // Writing context (characters/settings/rules) merge into ws.context.
+    const ctxUpdate = {};
+    for (const key of WRITING_CONTEXT_KEYS) {
+        if (key in update)
+            ctxUpdate[key] = update[key];
+    }
+    if (Object.keys(ctxUpdate).length > 0) {
+        ws.context = { ...ws.context, ...ctxUpdate };
+    }
+    // Enrichment fields set on the workspace top-level. `null` clears.
+    for (const key of ENRICHMENT_FIELDS) {
+        if (!(key in update))
+            continue;
+        const value = update[key];
+        if (value === null) {
+            delete ws[key];
+        }
+        else {
+            ws[key] = value;
+        }
+    }
     writeWorkspace(wsFile, ws);
     return ws;
 }
@@ -437,6 +459,21 @@ export function getWorkspaceAssignedFiles() {
     }
     return assigned;
 }
+/** Return every workspace manifest filename that contains this doc. A doc may
+ *  appear in multiple workspaces; callers that want one usually pick the first. */
+export function findWorkspacesContainingDoc(file) {
+    const workspaces = listWorkspaces();
+    const result = [];
+    for (const info of workspaces) {
+        try {
+            const ws = readWorkspace(info.filename);
+            if (collectAllFiles(ws.root).includes(file))
+                result.push(info);
+        }
+        catch { /* skip corrupt manifests */ }
+    }
+    return result;
+}
 /**
  * Walk every workspace and return true if `file` is inside one where auto-accept
  * is on at the workspace level or on any ancestor container. Returns false when

package/dist/server/ws.js

@@ -2,21 +2,42 @@
  * WebSocket handler: pushes NodeChanges to browser, receives doc updates + signals.
  */
 import { WebSocketServer, WebSocket } from 'ws';
-import { updateDocument, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, onChanges, isAgentLocked, setAgentLock, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, } from './state.js';
+import { updateDocument, syncBrowserDocUpdate, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, debouncedSave, cancelDebouncedSave, onChanges, onIdRewrites, isAgentLocked, setAgentLockActive, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, onExternalWriteConflict, onDocumentReloaded, isAgentStub, unmarkAgentStub, } from './state.js';
 import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile } from './documents.js';
 import { removeDocFromAllWorkspaces } from './workspaces.js';
+import { canonicalizeIdentifier } from './helpers.js';
+import { nodeTextPreview, diagLog } from './pending-overlay.js';
+import { generateRequestId, withRequestId } from './logger.js';
+/** Walk a doc and return a per-pending-node summary for diagnostic logging.
+ *  Produces lines like "nodeId/status text=\"...\" orig=\"...\"" — empty
+ *  if the doc has no pending nodes. adr: adr/pending-overlay-model.md */
+function pendingSummary(doc) {
+    if (!doc?.content)
+        return '<none>';
+    const lines = [];
+    function walk(nodes) {
+        if (!Array.isArray(nodes))
+            return;
+        for (const node of nodes) {
+            const status = node?.attrs?.pendingStatus;
+            if (status && node?.attrs?.id) {
+                const text = nodeTextPreview(node);
+                const orig = node.attrs.pendingOriginalContent ? nodeTextPreview(node.attrs.pendingOriginalContent) : '<none>';
+                const identity = (status === 'rewrite' && text === orig) ? ' IDENTITY!' : '';
+                lines.push(`${node.attrs.id}/${status} text="${text}" orig="${orig}"${identity}`);
+            }
+            if (node.content)
+                walk(node.content);
+        }
+    }
+    walk(doc.content);
+    return lines.length === 0 ? '<none>' : lines.join(' | ');
+}
 const clients = new Set();
 let currentAgentConnected = false;
-// Debounced auto-save: persist to disk 2s after last doc-update
-let saveTimer = null;
-function debouncedSave() {
-    if (saveTimer)
-        clearTimeout(saveTimer);
-    saveTimer = setTimeout(() => {
-        save();
-        console.log('[WS] Auto-saved to disk');
-    }, 2000);
-}
+// Debounced auto-save lives in state.ts now — one timer for the whole process.
+// Both browser doc-update (here) and MCP write paths (state.ts) call into the
+// same timer so a single TTL governs all save activity.
 // Debounced sidebar refresh: notify clients after title changes settle
 let docsChangedTimer = null;
 function debouncedBroadcastDocumentsChanged() {
@@ -64,7 +85,7 @@ export function setupWebSocket(server) {
             // Re-set agent lock so the 3s window starts NOW, not from the original insert.
             // Tweet thread resyncs recreate all editors which fire onUpdate → stale doc-updates.
             // Without this reset, the lock expires before the browser finishes recreating editors.
-            setAgentLock();
+            setAgentLockActive();
             const filePath = getFilePath();
             const filename = filePath ? filePath.split(/[/\\]/).pop() || '' : '';
             const msg = JSON.stringify({
@@ -90,6 +111,76 @@ export function setupWebSocket(server) {
         // Notify browser of updated pending docs list (debounced)
         broadcastPendingDocsChanged();
     });
+    // Push matcher-driven ID rewrites to clients so their in-memory TipTap state
+    // tracks the server's authoritative ID assignment. Without this, the browser
+    // can hold stale IDs after a save-time matcher reassignment, subsequent
+    // server→browser messages targeting the new IDs silently fail to resolve at
+    // the bridge anchor lookup, and the browser's debounced autosave eventually
+    // overwrites fresh server state with the stale view (the v0.14.0 bug pattern).
+    // adr: adr/node-identity-matcher.md
+    onIdRewrites((rewrites) => {
+        if (rewrites.length === 0)
+            return;
+        const msg = JSON.stringify({ type: 'id-rewrites', rewrites });
+        for (const ws of clients) {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(msg);
+        }
+        console.log(`[WS] Broadcast id-rewrites (${rewrites.length} block(s))`);
+    });
+    // Push-based: the fs.watch on the active doc fires this listener when an
+    // external writer (Edit tool, VSCode, a script) modifies the file. The
+    // server has already reloaded its in-memory state from disk and bumped
+    // docVersion — we just need to swap the browser's TipTap view so it
+    // matches and surface a toast. Stale autosaves from before the external
+    // write are rejected by the existing version check in the doc-update
+    // handler.
+    //
+    // Version sync: we include the freshly-bumped docVersion in the message.
+    // The browser adopts it as its new baseline so subsequent autosaves (from
+    // the user typing on top of the reloaded content) pass the isVersionCurrent
+    // check. Without this, browser sits at version 0 while the server is at
+    // N+1, and every browser edit gets BLOCKED — typing silently fails to save.
+    // adr: adr/active-doc-watcher.md
+    onDocumentReloaded((event) => {
+        const msg = JSON.stringify({
+            type: 'document-reloaded',
+            filename: event.filename,
+            document: event.document,
+            title: event.title,
+            docId: event.docId,
+            metadata: event.metadata,
+            version: getDocVersion(),
+            orphanCount: event.orphans.length,
+            staleBaselineCount: event.staleBaseline.length,
+        });
+        for (const ws of clients) {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(msg);
+        }
+        // Pending count may have shifted (orphan rewrites convert to inserts).
+        broadcastPendingDocsChanged();
+    });
+    // Legacy: surface external-write conflicts when writeToDisk's mtime
+    // guard fires. With the active-doc watcher in place, the watcher should
+    // reload before any save races, but the guard remains as a backstop —
+    // if it fires, we still want to tell the user.
+    // adr: adr/external-write-guard.md
+    onExternalWriteConflict((conflict) => {
+        const filename = conflict.filePath.split(/[/\\]/).pop() || conflict.filePath;
+        const msg = JSON.stringify({
+            type: 'external-write-conflict',
+            filePath: conflict.filePath,
+            filename,
+            diskMtime: conflict.diskMtime,
+            loadedMtime: conflict.loadedMtime,
+        });
+        for (const ws of clients) {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(msg);
+        }
+        console.warn(`[WS] Broadcast external-write-conflict for ${filename}`);
+    });
     wss.on('connection', (ws) => {
         clients.add(ws);
         console.log(`[WS] Client connected (total: ${clients.size})`);
@@ -103,9 +194,12 @@ export function setupWebSocket(server) {
         // (prevents stale browser tabs from displaying old content)
         const filePath = getFilePath();
         const filename = filePath ? filePath.split(/[/\\]/).pop() || '' : '';
+        const docOnConnect = getDocument();
+        const pendingOnConnect = pendingSummary(docOnConnect);
+        diagLog(`[WS] document-switched SEND on-connect docId=${getDocId()} v=${getDocVersion()} pending=[${pendingOnConnect}]`);
         ws.send(JSON.stringify({
             type: 'document-switched',
-            document: getDocument(),
+            document: docOnConnect,
             title: getTitle(),
             filename,
             docId: getDocId(),
@@ -124,22 +218,57 @@ export function setupWebSocket(server) {
         ws.on('message', async (data) => {
             try {
                 const msg = JSON.parse(data.toString());
+                // Every WS message gets a request ID — every downstream log emitted
+                // while handling this message inherits it. Trace one request through
+                // the whole system with: jq 'select(.requestId=="ws-xxxxxx")'.
+                // adr: adr/logging-system.md
+                const reqId = generateRequestId(`ws-${msg.type || 'unknown'}`);
+                return await withRequestId(reqId, async () => { return await handleMessage(msg); });
+            }
+            catch (err) {
+                console.error('[WS] Message error:', err.message);
+            }
+        });
+        /** Inner handler — body extracted so it runs inside the withRequestId
+         *  scope above. Returns void. */
+        async function handleMessage(msg) {
+            try {
                 if (msg.type === 'doc-update' && msg.document) {
                     const docContent = msg.document?.content || [];
                     const nodeCount = docContent.length;
                     const currentNodeCount = getDocument()?.content?.length || 0;
                     const browserVersion = typeof msg.version === 'number' ? msg.version : -1;
                     const serverVersion = getDocVersion();
-                    if (isAgentLocked()) {
-                        console.log(`[WS] doc-update BLOCKED by agent lock (browser: ${nodeCount} nodes, server: ${currentNodeCount} nodes)`);
+                    // Canonicalize the browser-sent filename so comparison against
+                    // getActiveFilename() doesn't trip on separator/case differences
+                    // for the same file. Without this, a browser that cached the
+                    // pre-canonicalization spelling sends doc-updates that look like
+                    // they're for a different doc, triggering saveDocToFile() to
+                    // write to the old non-canonical path — re-creating the
+                    // duplicate-document bug we just fixed.
+                    // adr: adr/path-canonicalization.md
+                    const browserFilename = msg.filename ? canonicalizeIdentifier(msg.filename) : msg.filename;
+                    if (isAgentLocked(browserFilename || getActiveFilename())) {
+                        diagLog(`[WS] doc-update BLOCKED by agent lock (browser: ${nodeCount} nodes, server: ${currentNodeCount} nodes) filename=${browserFilename || '<active>'} browserPending=[${pendingSummary(msg.document)}]`);
                     }
                     else if (browserVersion >= 0 && !isVersionCurrent(browserVersion)) {
-                        console.log(`[WS] doc-update BLOCKED by stale version (browser: v${browserVersion}, server: v${serverVersion})`);
+                        // Stale-version doc-update: instead of rejecting (which silently
+                        // discarded the user's typing), MERGE — keep browser's view of
+                        // canonical, union the overlays with server-recent additions
+                        // preserved. adr: adr/pending-overlay-model.md
+                        if (msg.document.content) {
+                            msg.document.content = msg.document.content.filter((n) => n.type !== 'imageLoading');
+                        }
+                        const result = syncBrowserDocUpdate(msg.document, browserVersion);
+                        diagLog(`[WS] doc-update SYNC-MERGED stale v${browserVersion}→v${serverVersion} preservedServerEntries=${result.preservedServerEntries}`);
+                        updatePendingCacheForActiveDoc();
+                        debouncedSave();
                     }
-                    else if (msg.filename && msg.filename !== getActiveFilename()) {
+                    else if (browserFilename && browserFilename !== getActiveFilename()) {
                         // Browser sent a doc-update for a different document (race: server switched away).
                         // Save directly to that file on disk instead of corrupting the active doc.
-                        saveDocToFile(msg.filename, msg.document);
+                        diagLog(`[WS] doc-update ROUTED-TO-NON-ACTIVE filename=${browserFilename} browserPending=[${pendingSummary(msg.document)}]`);
+                        saveDocToFile(browserFilename, msg.document);
                     }
                     else {
                         // Strip ephemeral imageLoading nodes — they're transient placeholders that should
@@ -148,7 +277,16 @@ export function setupWebSocket(server) {
                             msg.document.content = msg.document.content.filter((n) => n.type !== 'imageLoading');
                         }
                         const cleanedCount = msg.document.content?.length || 0;
-                        console.log(`[WS] doc-update ACCEPTED (browser: ${nodeCount} nodes, cleaned: ${cleanedCount}, server: ${currentNodeCount} nodes)`);
+                        // Capture server's BEFORE state so we can diff against the incoming.
+                        // adr: adr/pending-overlay-model.md
+                        const serverBefore = pendingSummary(getDocument());
+                        const browserAfter = pendingSummary(msg.document);
+                        if (serverBefore !== browserAfter) {
+                            diagLog(`[WS] doc-update PENDING-DIFF v${browserVersion}→v${serverVersion}`);
+                            diagLog(`  BEFORE(server): ${serverBefore}`);
+                            diagLog(`  AFTER (browser): ${browserAfter}`);
+                        }
+                        diagLog(`[WS] doc-update ACCEPTED (browser: ${nodeCount} nodes, cleaned: ${cleanedCount}, server: ${currentNodeCount} nodes)`);
                         updateDocument(msg.document);
                         updatePendingCacheForActiveDoc(); // Keep cache in sync after browser edits/reject-all
                         debouncedSave();
@@ -185,8 +323,18 @@ export function setupWebSocket(server) {
                 }
                 if (msg.type === 'switch-document' && msg.filename) {
                     try {
+                        // adr-perf: full server-side switch timing. [Switch] CLICK/SEND
+                        // on the client, [Switch:Server] RECV/DONE/BCAST on the server,
+                        // [Switch] RECEIVE/COMMIT and [Editor] mounted back on the
+                        // client. Each delta exposes where the latency lives.
+                        const tRecv = performance.now();
+                        diagLog(`[Switch:Server] RECV filename=${msg.filename}`);
                         const result = switchDocument(msg.filename);
+                        const tSwitchDone = performance.now();
+                        diagLog(`[Switch:Server] DONE filename=${msg.filename} switchDoc=${(tSwitchDone - tRecv).toFixed(1)}ms`);
                         broadcastDocumentSwitched(result.document, result.title, result.filename);
+                        const tBcastDone = performance.now();
+                        diagLog(`[Switch:Server] BCAST filename=${msg.filename} stringify+send=${(tBcastDone - tSwitchDone).toFixed(1)}ms totalServer=${(tBcastDone - tRecv).toFixed(1)}ms`);
                     }
                     catch (err) {
                         console.error('[WS] Switch document failed:', err.message);
@@ -256,17 +404,22 @@ export function setupWebSocket(server) {
                     const action = msg.action; // 'accept' or 'reject'
                     const resolvedFilename = msg.filename;
                     const isActiveDoc = resolvedFilename === getActiveFilename();
-                    // Get metadata from the correct source (active state or disk file)
-                    const metadata = isActiveDoc ? getMetadata() : null;
-                    if (action === 'reject' && metadata?.agentCreated) {
-                        // Agent-created doc with all content rejected → delete the file
-                        // Cancel debounced save (doc-update may have queued one for the now-empty doc)
-                        if (saveTimer) {
-                            clearTimeout(saveTimer);
-                            saveTimer = null;
-                        }
+                    // Stub-cleanup: when the user rejects all pending decorations on a
+                    // doc that's still a fresh agent stub, delete the file. The stub
+                    // had no real content; the user said no to the populated content;
+                    // there's nothing left to keep.
+                    //
+                    // Stub status is consulted from the in-memory registry — NEVER
+                    // from disk frontmatter. The previous on-disk `agentCreated: true`
+                    // model was a silent-data-loss landmine: the flag survived across
+                    // sessions, restarts, and the doc's entire useful lifetime, so a
+                    // reject-all years later would destroy real work. The in-memory
+                    // model can only mark a doc as a stub during the brief window
+                    // between create_document and the first accepted save.
+                    // adr: adr/agent-stub-model.md
+                    if (action === 'reject' && isAgentStub(resolvedFilename)) {
+                        cancelDebouncedSave();
                         try {
-                            // Remove from any workspace manifests before deleting the file
                             removeDocFromAllWorkspaces(resolvedFilename);
                             const result = await deleteDocument(resolvedFilename);
                             if (result.switched && result.newDoc) {
@@ -278,15 +431,17 @@ export function setupWebSocket(server) {
                             return; // File deleted — no strip/save needed
                         }
                         catch (err) {
-                            console.error('[WS] Failed to delete rejected agent doc:', err.message);
+                            console.error('[WS] Failed to delete rejected agent stub:', err.message);
                             // Fall through to normal strip+save (e.g. only doc remaining)
                         }
                     }
                     if (isActiveDoc) {
-                        // Normal path: resolved doc is the active one
-                        if (action === 'accept' && metadata?.agentCreated) {
-                            delete metadata.agentCreated;
-                        }
+                        // Normal path: resolved doc is the active one. Accept-all
+                        // graduates the doc out of stub status (it now has accepted
+                        // content); the writeToDisk graduation does the same for
+                        // saves with mixed pending+accepted content.
+                        if (action === 'accept')
+                            unmarkAgentStub(resolvedFilename);
                         stripPendingAttrs();
                         save();
                         updatePendingCacheForActiveDoc(); // Sync cache after strip (prevents stale "has changes" indicator)
@@ -294,6 +449,8 @@ export function setupWebSocket(server) {
                     else {
                         // Race path: resolved doc is NOT the active one (server switched away).
                         // Strip pending attrs directly from the file on disk.
+                        if (action === 'accept')
+                            unmarkAgentStub(resolvedFilename);
                         stripPendingAttrsFromFile(resolvedFilename, action === 'accept');
                     }
                     broadcastPendingDocsChanged();
@@ -302,7 +459,7 @@ export function setupWebSocket(server) {
             catch {
                 // Ignore malformed messages
             }
-        });
+        }
         ws.on('close', () => {
             clients.delete(ws);
             console.log(`[WS] Client disconnected (total: ${clients.size})`);
@@ -457,8 +614,8 @@ export function getPendingWritesSnapshot() {
         startedAt,
     }));
 }
-export function broadcastMarksChanged(filename) {
-    const msg = JSON.stringify({ type: 'marks-changed', filename });
+export function broadcastCommentsChanged(filename) {
+    const msg = JSON.stringify({ type: 'comments-changed', filename });
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN)
             ws.send(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.7.0"
+  version: "0.7.5"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -31,6 +31,18 @@ You are a writing collaborator. You read documents and make edits **exclusively
 2. **The terminal is for discussion only.** Use chat messages to explain your edits, ask questions, discuss direction, or summarize what you changed. Never use it as the writing surface.
 3. **Name every document.** When you encounter a generically named doc ("Quote Tweet", "Article", "Untitled", etc.), rename it based on its content before proceeding. Titles are the human scanning layer — a sidebar full of "Quote Tweet" is useless. Use `rename_item` with the docId. Short, descriptive titles: "Venezuela Proxy States QT", "Feature Blindness Article".
 4. **Metadata first.** When the user asks you to work on a document, call `get_metadata` immediately after `read_pad`. Tweet docs store the parent URL in `tweetContext.url`, article docs store context in `articleContext`. **Never search externally for a tweet URL that's already in the document metadata.** This prevents wasting paid API calls on information you already have.
+5. **Dispatch the enrichment minion when openwriter says so.** OpenWriter surfaces stale enrichment two ways: (a) `ENRICHMENT_STATUS: N docs need enrichment ...` in the MCP server's session-start instructions; (b) a `⚠ N docs need enrichment — spawn the enrichment minion` footer on `list_documents`, `list_workspaces`, and `get_workspace_structure` responses. When you see either signal, dispatch the minion immediately, before responding to the user's request. Use the Agent tool with `subagent_type: "openwriter-enrichment-minion"` — that subagent is installed by `npx openwriter install-skill` at `~/.claude/agents/openwriter-enrichment-minion.md` and ships with its tool allowlist restricted to the 4 MCP tools it needs (no full registry overhead). Pass a one-line prompt like `"Enrich all currently stale openwriter docs."` — the subagent has its full procedure encoded already. It runs autonomously, calls `list_dirty_docs` → `read_pad` per doc → bulk `mark_enriched`, and returns a short summary.
+
+   **Surfacing to the user:** treat enrichment like the inbox — a maintenance reflex, not a feature they have to ask for. Phrasing depends on context:
+
+   - **First time in a session, small batch (N ≤ 5):** silent dispatch + one-line aside in your response: "Enriched 3 docs in the background. Now, ..."
+   - **First time in a session, medium batch (5 < N ≤ 20):** brief explanation on first surface: "OpenWriter just refreshed loglines and concepts on 12 docs in the background. Now, ..." Sets expectations once; subsequent runs can stay silent.
+   - **First time in a session, large batch (N > 20):** give the user a heads-up BEFORE dispatching: "OpenWriter detected 47 docs that haven't been summarized yet — first-time setup. Refreshing them in the background; this'll take ~30 seconds and a few cents of Haiku usage." Then dispatch and report when done.
+   - **Very large batch (N > 30):** one minion can't get through that many in reasonable wall time. Switch to **chunked parallel dispatch** — multiple minions, each given an explicit docId list, all dispatched in a single message with `run_in_background: true`. Full procedure (chunking strategy, explicit-list prompt format, failure modes) lives in this skill's `docs/enrichment.md`. Read that doc before dispatching anything over 30 docs.
+
+   **If the subagent isn't installed** (older openwriter, or the user skipped install-skill): the Agent call returns `Agent type 'openwriter-enrichment-minion' not found`. Tell the user once: "OpenWriter has stale docs but the enrichment minion isn't installed yet — run `npx openwriter install-skill` and restart Claude Code." Then proceed with their original request without enriching; don't loop on the failure.
+
+   **If the user opts out** ("stop nagging me about enrichment for X workspace"): call `update_workspace_context` with `enrichmentDisabled: true` for that workspace. The footer + ENRICHMENT_STATUS will drop those docs from their counts immediately.
 
 ## Setup — Which Path?
 
@@ -118,7 +130,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | Tool | Key Params | Description |
 |------|-----------|-------------|
 | `list_documents` | — | List all documents with title, docId, word count, active status |
-| `switch_document` | `docId` | Switch to a different document by docId |
+| `switch_document` | `docId` | Change the user's view to a different document. **Rarely needed** — every tool targets docs by docId directly, so reads, writes, and creations never require switching. Use ONLY when you want to pull the user's attention to a specific doc (e.g. "I've loaded this up for your review"). The user may be perusing other docs — don't yank their view as part of normal work. |
 | `create_document` | `content_type`, `title?`, ... | Create a new document. `content_type` is required: "document", "tweet", "reply", "quote", "article", "linkedin", "newsletter", or "blog" |
 | `open_file` | `path` | Open an existing .md file from any location on disk |
 | `delete_document` | `docId` | Delete a document file (moves to OS trash, recoverable) |
@@ -138,8 +150,8 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `list_workspaces` | List all workspaces with title and doc count |
 | `create_workspace` | Create a new workspace |
 | `delete_workspace` | Delete a workspace and all its document files (moves to OS trash) |
-| `get_workspace_structure` | Get full workspace tree: containers, docs, tags, context |
-| `get_item_context` | Get progressive disclosure context for a doc in a workspace |
+| `get_workspace_structure` | Get full workspace tree: containers, docs, enrichment (logline/domain/docRole per doc), workspace-level vocab/schema, plus context (characters, settings, rules) |
+| `get_item_context` | Get progressive disclosure context for a doc — workspace context + the doc's own enrichment (logline, domain, concepts, docRole, status, enrichmentStale) |
 | `update_workspace_context` | Update workspace context (characters, settings, rules) |
 
 ### Workspace Organization
@@ -153,12 +165,24 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `move_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace) |
 | `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
-### Agent Marks
+### Enrichment (frontmatter classification + crawlability)
+
+OpenWriter detects when a doc has drifted past enrichment thresholds (sentence-hash Jaccard drift, character-count volume ratio) on every save and stamps `enrichmentStale: true`. The agent's job is to dispatch the enrichment minion (see firm rule 5 + `docs/enrichment.md` in this skill) to refresh the loglines, domain, concepts, docRole, and status fields.
+
+| Tool | Key Params | Description |
+|------|-----------|-------------|
+| `list_dirty_docs` | `workspaceFile?` | List docs that need enrichment (never enriched OR explicitly flagged stale). Returns identity + reason only — no bodies. Optionally scoped to one workspace. Docs in opted-out workspaces (`enrichmentDisabled: true`) are excluded. |
+| `mark_enriched` | `docs: [{docId, logline?, domain?, concepts?, docRole?, status?}]` | Stamp one or more docs as freshly enriched. OpenWriter auto-computes baselines (`lastEnrichedAt`, `lastEnrichedCharCount`, `lastEnrichedSentences`) and clears `enrichmentStale`. The minion calls this once at the end of its run with the full batch. |
+| `crawl` | `workspaceFile?`, `domain?`, `tags?`, `concepts?`, `docRole?`, `hasLogline?` | Bulk-read enrichment fields per doc with AND-composed filters. The agent's "scan the shelf" primitive — ~150 tokens per doc, no bodies. Pick which bodies to actually read after crawling. |
+
+### Comments
 
 | Tool | Key Params | Description |
 |------|-----------|-------------|
-| `get_agent_marks` | `docId?` | Get inline feedback marks left by the user (optional docId — omit for all docs) |
-| `resolve_agent_marks` | `mark_ids` | Remove marks after addressing feedback (pass mark IDs) |
+| `get_comments` | `docId?`, `scope?` | Get comments left by the user. Default scope is `workspace` when a docId is given (returns comments for every doc in the same project); pass `scope: "document"` to narrow, or `scope: "all"` for every doc on disk |
+| `resolve_comments` | `comment_ids` | Remove comments after addressing feedback (pass comment IDs) |
+
+The older names `get_agent_marks` and `resolve_agent_marks` remain as deprecated aliases.
 
 ### Task Management
 
@@ -233,7 +257,7 @@ The user can turn on **auto-accept** on a per-doc basis (right-click the doc in
 **Rules:**
 - `create_document` does NOT accept a `content` parameter — it always creates an empty doc
 - Step 1 (`create_document`) — shows spinner, creates empty doc, does NOT switch the editor
-- Step 2 (`populate_document`) — writes content to the active doc, marks as pending decorations, switches the editor, clears the spinner
+- Step 2 (`populate_document`) — pass the `docId` from step 1 to write content directly to that doc, marks as pending decorations, clears the spinner. Does NOT switch the user's view — they keep working wherever they are.
 - Never use `write_to_pad` for the initial population — use `populate_document` exclusively
 
 ### Workspace-Integrated Creation
@@ -301,7 +325,7 @@ For voice-matched drafting without a custom Author's Voice profile, install the
 
 ```
 1. list_documents    → see all docs with title + [docId]
-2. read_pad          → read active doc (or switch_document({ docId }) first)
+2. read_pad({ docId: "e5f6a7b8" })  → reads that doc directly, no switch needed
 3. write_to_pad({ docId: "e5f6a7b8", changes: [...] })
                      → edits go to the identified doc, no view switch needed
 ```
@@ -333,21 +357,23 @@ For voice-matched drafting without a custom Author's Voice profile, install the
 
 The workspace and containers are auto-created on the first `create_document` call. Subsequent calls reuse the existing workspace/containers (matched case-insensitively).
 
-### Agent marks (inline feedback)
+### Comments (inline feedback)
 
-Users can select text in the browser, right-click, and leave an "Agent Mark" — a note attached to a specific text range. Marks appear as dotted underlines in the editor. This is the user's way of marking up a document with feedback for you to address.
+Users can select text in the browser, right-click, and leave a comment — a note attached to a specific text range. Comments appear as dotted underlines in the editor. This is the user's way of marking up a document with feedback for you to address.
 
 ```
-1. User says "check my marks" (or you see the hint in read_pad output)
-2. get_agent_marks              → all marks across all docs, grouped by document
-3. Address each mark            → rewrite, insert, delete via write_to_pad (use docId)
-4. resolve_agent_marks([ids])   → clears decorations in browser
+1. User says "check my comments" (or you see the hint in read_pad output)
+2. get_comments({ docId })       → comments for the current workspace by default
+3. Address each comment          → rewrite, insert, delete via write_to_pad (use docId)
+4. resolve_comments([ids])       → clears decorations in browser
 ```
 
-- `read_pad` automatically shows mark counts: this doc + other docs
-- Always resolve marks after addressing them — the dotted underlines clear immediately
-- A mark with an empty note means "fix this" — use your judgment
-- A mark with a note is specific feedback — follow the instruction
+- `read_pad` automatically shows comment counts: this doc + other docs
+- Default scope is `workspace` when a docId is provided — you see comments across every doc in the user's current project, not just the one they're viewing
+- Pass `scope: "document"` to narrow to one doc, `scope: "all"` to span everything on disk
+- Always resolve comments after addressing them — `resolve_comments` is a state change ("addressed, archive it"), not a destructive delete. The record stays in storage; only the decoration disappears. `get_comments` skips resolved ones by default
+- A comment with an empty note means "fix this" — use your judgment
+- A comment with a note is specific feedback — follow the instruction
 
 ### Book workspace guidelines
 
@@ -638,7 +664,11 @@ Then restart your Claude Code session (`/mcp` to reconnect).
 
 **MCP tools not available** — The OpenWriter MCP server isn't configured yet. Follow the [setup instructions](#mcp-tools-are-not-available-skill-first-install) above. After adding the MCP config, the user must restart their Claude Code session.
 
-**Browser dies mid-session** — The MCP stdio pipe can break during context compaction or session resets. The HTTP server survives (crash guards), but MCP tools stop working. Tell the user: **run `/mcp` to reconnect.** The new process enters client mode and proxies MCP calls to the surviving HTTP server. The browser will auto-reconnect.
+**Browser dies mid-session** — The MCP stdio pipe can break during context compaction or session resets. The HTTP server survives (crash guards), but MCP tools stop working. Reconnect by [restarting the MCP server](#restarting-the-mcp-server) (see below). The new process enters client mode and proxies MCP calls to the surviving HTTP server. The browser will auto-reconnect.
+
+### Restarting the MCP server
+
+Both Claude Code and Claude Desktop work the same way: there's no explicit restart button. Call `list_documents` (zero params, read-only, fast). If the previous process is dead, Claude auto-spawns a fresh one to satisfy the call. After code changes, kill the old process first (`taskkill /F /PID <pid>` on Windows, `kill <pid>` on macOS/Linux) so the spawn picks up the new build. Only fall back to `/mcp` (Claude Code) if tool calls keep returning `Connection error: fetch failed`.
 
 **Port 5050 busy** — Another OpenWriter instance owns the port. New sessions auto-enter client mode (proxying via HTTP) — tools still work. No action needed.
 
@@ -648,6 +678,6 @@ Then restart your Claude Code session (`/mcp` to reconnect).
 
 **Server not starting** — Ensure `openwriter` works from your terminal (`npm install -g openwriter` first). If on Windows and the global command isn't found, the MCP config may need `"command": "cmd"` with `"args": ["/c", "openwriter", "--no-open"]`.
 
-**After code changes** — Run `npm run build` in `packages/openwriter`, then `/mcp` to restart with the new build.
+**After code changes** — Run `npm run build` in `packages/openwriter`, kill the running openwriter process, then [restart the MCP server](#restarting-the-mcp-server). `/mcp` alone only reconnects to the existing process; it won't pick up new code unless the old process dies first.
 
 **Slow to load / loads last** — MCP servers load sequentially in config order. Move `openwriter` to the first position in `mcpServers` in `~/.claude.json`. See setup instructions above.