openwriter 0.14.0 → 0.16.0

package/dist/server/mcp.js

@@ -10,19 +10,22 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync } from './helpers.js';
-import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument, invalidateDocCache, isAutoAcceptActive, } from './state.js';
-import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, searchDocuments } from './documents.js';
+import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, getCanonical, cloneWithPendingReverted, bumpDocVersion, } from './state.js';
+import { tiptapToBlocks } from './node-blocks.js';
+import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
+import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions } from './documents.js';
 import { extractForwardLinks } from './backlinks.js';
-import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastMarksChanged } from './ws.js';
-import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces } from './workspaces.js';
+import { logger, generateRequestId, withRequestId } from './logger.js';
+import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
+import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
 import { findDocNode } from './workspace-tree.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent, mergeParagraphsToHardBreaks } from './compact.js';
 import matter from 'gray-matter';
 import { getUpdateInfo } from './update-check.js';
-import { listVersions, forceSnapshot, restoreVersion } from './versions.js';
+import { listVersions, forceSnapshot, getVersionContent } from './versions.js';
 import { markdownToTiptap, tiptapToMarkdown } from './markdown.js';
-import { getMarks, getMarkCount, getGlobalMarkSummary, resolveMarks } from './marks.js';
+import { getComments, getCommentCount, getGlobalCommentSummary, resolveComments } from './comments.js';
 import { readTasks, addTask, updateTask, removeTask } from './tasks.js';
 /** Map a content type string to its frontmatter metadata object. */
 function resolveTypeMeta(type, url) {
@@ -113,6 +116,75 @@ function resolveDocTarget(docId) {
         lastModified: statSync(filePath).mtime,
     };
 }
+/** Human-friendly relative time for ISO timestamps. */
+function relativeTime(iso) {
+    const then = new Date(iso).getTime();
+    if (!isFinite(then))
+        return '';
+    const diff = Date.now() - then;
+    if (diff < 0)
+        return 'just now';
+    const sec = Math.round(diff / 1000);
+    if (sec < 60)
+        return 'just now';
+    const min = Math.round(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.round(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.round(hr / 24);
+    if (day < 14)
+        return `${day}d ago`;
+    const wk = Math.round(day / 7);
+    if (wk < 8)
+        return `${wk}w ago`;
+    const mo = Math.round(day / 30);
+    if (mo < 12)
+        return `${mo}mo ago`;
+    return `${Math.round(day / 365)}y ago`;
+}
+/** Apply a scope filter to the comments index. Returns the matching comments
+ *  grouped by file plus a human-readable label for the scope. */
+function gatherComments(filename, scope) {
+    const effectiveScope = scope ?? (filename ? 'workspace' : 'all');
+    if (effectiveScope === 'document' && filename) {
+        return { byFile: getComments(filename), scopeLabel: `document "${filename}"` };
+    }
+    if (effectiveScope === 'workspace' && filename) {
+        const containing = findWorkspacesContainingDoc(filename);
+        if (containing.length === 0) {
+            // Doc isn't filed in any workspace — fall back to single-doc scope.
+            return { byFile: getComments(filename), scopeLabel: `document "${filename}" (not in any workspace)` };
+        }
+        const ws = containing[0];
+        const filesInWs = collectFilesInWorkspace(ws.filename);
+        const byFile = {};
+        for (const f of filesInWs) {
+            const docComments = getComments(f);
+            if (docComments[f] && docComments[f].length > 0)
+                byFile[f] = docComments[f];
+        }
+        return { byFile, scopeLabel: `workspace "${ws.title}" (${filesInWs.length} docs)` };
+    }
+    return { byFile: getComments(), scopeLabel: 'all documents' };
+}
+function formatCommentsOutput({ byFile, scopeLabel }) {
+    const entries = Object.entries(byFile);
+    if (entries.length === 0)
+        return `No comments found in ${scopeLabel}.`;
+    const total = entries.reduce((sum, [, list]) => sum + list.length, 0);
+    const lines = [`Comments in ${scopeLabel} — ${total} total:`];
+    for (const [file, comments] of entries) {
+        lines.push(`\n${file}:`);
+        for (const c of comments) {
+            const notePart = c.note ? ` — "${c.note}"` : '';
+            const age = c.createdAt ? `  [${relativeTime(c.createdAt)}]` : '';
+            lines.push(`  [${c.id}] "${c.text}"${notePart}${age}  (node:${c.nodeId})`);
+        }
+    }
+    return lines.join('\n');
+}
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
@@ -123,15 +195,15 @@ export const TOOL_REGISTRY = [
         handler: async ({ docId }) => {
             const target = resolveDocTarget(docId);
             const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
-            const localCount = getMarkCount(target.filename);
-            const { totalMarks: otherMarks, docCount: otherDocs } = getGlobalMarkSummary(target.filename);
+            const localCount = getCommentCount(target.filename);
+            const { totalComments: otherCount, docCount: otherDocs } = getGlobalCommentSummary(target.filename);
             let hint = '';
             if (localCount > 0)
-                hint += `\n[${localCount} agent mark${localCount !== 1 ? 's' : ''} on this document]`;
-            if (otherMarks > 0)
-                hint += `\n[${otherMarks} agent mark${otherMarks !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
+                hint += `\n[${localCount} comment${localCount !== 1 ? 's' : ''} on this document]`;
+            if (otherCount > 0)
+                hint += `\n[${otherCount} comment${otherCount !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
             if (hint)
-                hint += '\n[call get_agent_marks to review]';
+                hint += '\n[call get_comments to review]';
             return { content: [{ type: 'text', text: compact + hint }] };
         },
     },
@@ -226,6 +298,22 @@ export const TOOL_REGISTRY = [
             // so the agent stops waiting for review when it's on.
             if (isAutoAcceptActive(target.filename, target.metadata))
                 status.autoAccept = true;
+            // External-write drift: only meaningful for the active doc (non-active
+            // docs are read fresh from disk on each access). If the file's on-disk
+            // mtime differs from what we loaded, an external writer modified the
+            // file — the next save would be blocked by the guard. Surface this so
+            // agents can call reload_from_disk before re-attempting a write.
+            // adr: adr/external-write-guard.md
+            if (target.isActive) {
+                const drift = getExternalMtimeDrift();
+                if (drift) {
+                    status.externalWriteDetected = {
+                        diskMtime: new Date(drift.diskMtime).toISOString(),
+                        loadedMtime: new Date(drift.loadedMtime).toISOString(),
+                        note: 'File modified externally. Call reload_from_disk before writing or your changes will be blocked.',
+                    };
+                }
+            }
             const latestVersion = getUpdateInfo();
             const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
             return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -246,7 +334,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_documents',
-        description: 'List all documents. Shows title, docId (8-char hex), word count, last modified date, and which document is active. Use the docId to target documents in other tools.',
+        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, domain, docRole) when present. Use the docId to target documents in other tools.',
         schema: {},
         handler: async () => {
             const docs = listDocuments();
@@ -254,9 +342,21 @@ export const TOOL_REGISTRY = [
                 const active = d.isActive ? ' (active)' : '';
                 const id = d.docId ? ` [${d.docId}]` : '';
                 const date = d.lastModified.split('T')[0];
-                return `  "${d.title}"${id}${active} — ${d.wordCount.toLocaleString()} words — ${date}`;
+                const enrichBits = [];
+                if (d.domain)
+                    enrichBits.push(d.domain);
+                if (d.docRole)
+                    enrichBits.push(d.docRole);
+                if (d.enrichmentStale === true)
+                    enrichBits.push('STALE');
+                const enrichTag = enrichBits.length > 0 ? ` (${enrichBits.join(', ')})` : '';
+                const main = `  "${d.title}"${id}${active}${enrichTag} — ${d.wordCount.toLocaleString()} words — ${date}`;
+                if (d.logline)
+                    return `${main}\n      → ${d.logline}`;
+                return main;
             });
-            return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}` }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
     {
@@ -317,8 +417,8 @@ export const TOOL_REGISTRY = [
             try {
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
-                    setAgentLock();
                     const result = createDocument(title, undefined, path);
+                    setAgentLock(result.filename);
                     // Apply type-specific metadata
                     if (content_type) {
                         const typeMeta = resolveTypeMeta(content_type, url);
@@ -418,7 +518,7 @@ export const TOOL_REGISTRY = [
                 // Active target (or no filename): existing flow.
                 // Skip pending tagging when autoAccept is effectively on (doc flag or
                 // inherited from workspace/container) — content commits directly.
-                setAgentLock(); // Block browser doc-updates during population
+                setAgentLock(filename || getActiveFilename()); // Block browser doc-updates during population
                 if (!isAutoAcceptActive(filename || getActiveFilename(), getMetadata())) {
                     markAllNodesAsPending(doc, 'insert');
                 }
@@ -663,6 +763,117 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: `Metadata updated (${parts.join('; ')})` }] };
         },
     },
+    {
+        name: 'mark_enriched',
+        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied enrichment fields, and clears enrichmentStale. The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. See brief 2026-05-18-frontmatter-enrichment-system.',
+        schema: {
+            docs: z.array(z.object({
+                docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+                logline: z.string().optional().describe('One-sentence "what this doc is about" — ≤150 chars recommended.'),
+                domain: z.string().optional().describe('Single domain classification from the workspace vocab.'),
+                concepts: z.array(z.string()).optional().describe('Named concepts the doc references.'),
+                docRole: z.string().optional().describe('Doc role: canonical / vignette / reference / draft / chapter / beat.'),
+                status: z.string().optional().describe('Doc status: draft / canonical / stale. Archive state is implied by archivedAt.'),
+            })).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array.'),
+        },
+        handler: async ({ docs }) => {
+            const now = new Date().toISOString();
+            const results = [];
+            let anyTitleSideEffect = false;
+            for (const item of docs) {
+                try {
+                    const target = resolveDocTarget(item.docId);
+                    // Harvest current sentence hashes + char count from canonical view.
+                    // Active doc: getCanonical() returns the no-overlay primary state.
+                    // Non-active: cloneWithPendingReverted on the cached/loaded document.
+                    const canonical = target.isActive
+                        ? getCanonical()
+                        : cloneWithPendingReverted(target.document);
+                    const blocks = tiptapToBlocks(canonical);
+                    const lastEnrichedSentences = harvestSentenceHashes(blocks);
+                    const lastEnrichedCharCount = harvestCharCount(blocks);
+                    // Build the atomic enrichment payload.
+                    const update = {
+                        lastEnrichedAt: now,
+                        lastEnrichedCharCount,
+                        lastEnrichedSentences,
+                        enrichmentStale: false,
+                    };
+                    if (item.logline !== undefined)
+                        update.logline = item.logline;
+                    if (item.domain !== undefined)
+                        update.domain = item.domain;
+                    if (item.concepts !== undefined)
+                        update.concepts = item.concepts;
+                    if (item.docRole !== undefined)
+                        update.docRole = item.docRole;
+                    if (item.status !== undefined)
+                        update.status = item.status;
+                    if (target.isActive) {
+                        // Active doc: setMetadata mutates state.metadata but doesn't bump
+                        // docVersion on its own — without an explicit bump, save() would
+                        // hit the no-op gate (docVersion === lastSavedDocVersion when
+                        // there's no body change). bumpDocVersion forces save() through.
+                        // writeToDisk's staleness check will see the just-stamped baseline
+                        // (volumeRatio=1, drift=0) and NOT flip the flag back to true.
+                        setMetadata(update);
+                        bumpDocVersion();
+                        save();
+                        broadcastMetadataChanged(getMetadata());
+                    }
+                    else {
+                        // Non-active: write directly to disk, bypassing flushDocToFile's
+                        // staleness check (which would otherwise see stale state for one
+                        // serialize cycle before the new baseline lands). Disk write +
+                        // cache invalidation mirrors set_metadata's non-active path.
+                        const newMeta = { ...target.metadata, ...update };
+                        const markdown = tiptapToMarkdown(target.document, target.title, newMeta);
+                        atomicWriteFileSync(target.filePath, markdown);
+                        invalidateDocCache(target.filePath);
+                    }
+                    results.push({ docId: item.docId, ok: true });
+                }
+                catch (err) {
+                    results.push({ docId: item.docId, ok: false, error: String(err?.message ?? err) });
+                }
+            }
+            // Single broadcast at the end so sidebar refreshes once for the whole batch.
+            broadcastDocumentsChanged();
+            const okCount = results.filter((r) => r.ok).length;
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Enriched ${okCount} doc${okCount === 1 ? '' : 's'}`
+                : `Enriched ${okCount} doc${okCount === 1 ? '' : 's'}, ${failCount} failed`;
+            return { content: [{ type: 'text', text: `${summary}\n${JSON.stringify({ docs: results })}` }] };
+        },
+    },
+    {
+        name: 'list_dirty_docs',
+        description: 'List documents that need enrichment — never enriched (no lastEnrichedAt) or flagged stale by openwriter (drift/volume thresholds tripped). Returns identity + reason only; no enrichment fields, no bodies. The minion calls this first to know what to work on. Docs in opted-out workspaces (enrichmentDisabled: true) are excluded. See brief 2026-05-18-frontmatter-enrichment-system.',
+        schema: {
+            workspaceFile: z.string().optional().describe('Scope to one workspace. Omit to scan all workspaces.'),
+        },
+        handler: async ({ workspaceFile }) => {
+            const docs = listDirtyDocs(workspaceFile);
+            return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
+        },
+    },
+    {
+        name: 'crawl',
+        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~150 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay.',
+        schema: {
+            workspaceFile: z.string().optional().describe('Scope to one workspace.'),
+            domain: z.string().optional().describe('Exact domain match.'),
+            tags: z.array(z.string()).optional().describe('Docs must have ALL listed tags.'),
+            concepts: z.array(z.string()).optional().describe('Docs must reference ALL listed concepts.'),
+            docRole: z.string().optional().describe('Exact docRole match (canonical / vignette / reference / draft / chapter / beat).'),
+            hasLogline: z.boolean().optional().describe('True = only docs with a logline; false = only docs without one.'),
+        },
+        handler: async (filter) => {
+            const docs = crawlDocs(filter);
+            return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
+        },
+    },
     {
         name: 'list_workspaces',
         description: 'List all workspaces. Returns filename, title, and doc count.',
@@ -670,7 +881,8 @@ export const TOOL_REGISTRY = [
         handler: async () => {
             const workspaces = listWorkspaces();
             const lines = workspaces.map((w) => `  ${w.filename} — "${w.title}" — ${w.docCount} docs`);
-            return { content: [{ type: 'text', text: `workspaces:\n${lines.join('\n') || '  (none)'}` }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `workspaces:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
     {
@@ -705,57 +917,136 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_workspace_structure',
-        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc tags, plus context (characters, settings, rules). Use to understand workspace organization before writing.',
+        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, domain, tags, docRole, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies.',
         schema: {
             filename: z.string().describe('Workspace manifest filename (e.g. "my-novel-a1b2c3d4.json")'),
         },
         handler: async ({ filename }) => {
             const ws = getWorkspace(filename);
+            // Build a one-pass map of filename → frontmatter so we don't re-read each
+            // doc file per tree node. crawlDocs is cheap (one disk pass per workspace).
+            const enriched = crawlDocs({ workspaceFile: filename });
+            const enrichByFile = new Map(enriched.map((e) => [e.filename, e]));
             function renderTree(nodes, indent) {
                 const lines = [];
                 for (const node of nodes) {
                     if (node.type === 'doc') {
-                        const tags = getDocTagsByFilename(node.file);
-                        const tagStr = tags.length > 0 ? `  [${tags.join(', ')}]` : '';
-                        lines.push(`${indent}${getDocTitle(node.file)}  (${node.file})${tagStr}`);
+                        const e = enrichByFile.get(node.file);
+                        const tags = e?.tags ?? [];
+                        const enrichBits = [];
+                        if (e?.domain)
+                            enrichBits.push(e.domain);
+                        if (e?.docRole)
+                            enrichBits.push(e.docRole);
+                        if (tags.length > 0)
+                            enrichBits.push(`tags: ${tags.join(', ')}`);
+                        if (e?.enrichmentStale === true)
+                            enrichBits.push('STALE');
+                        const tagStr = enrichBits.length > 0 ? `  [${enrichBits.join(' | ')}]` : '';
+                        const docLine = `${indent}${getDocTitle(node.file)}  (${node.file})${tagStr}`;
+                        lines.push(docLine);
+                        if (e?.logline)
+                            lines.push(`${indent}    → ${e.logline}`);
                     }
                     else {
-                        lines.push(`${indent}[container] ${node.name}  (id:${node.id})`);
+                        const cBits = [];
+                        if (node.role)
+                            cBits.push(node.role);
+                        const cTag = cBits.length > 0 ? ` [${cBits.join(' | ')}]` : '';
+                        lines.push(`${indent}[container] ${node.name}  (id:${node.id})${cTag}`);
+                        if (node.logline)
+                            lines.push(`${indent}    → ${node.logline}`);
                         lines.push(...renderTree(node.items, indent + '  '));
                     }
                 }
                 return lines;
             }
             const treeLines = renderTree(ws.root, '  ');
-            let text = `workspace: "${ws.title}"\nstructure:\n${treeLines.join('\n') || '  (empty)'}`;
+            const headerBits = [`workspace: "${ws.title}"`];
+            if (ws.logline)
+                headerBits.push(`logline: ${ws.logline}`);
+            if (ws.domain)
+                headerBits.push(`domain: ${ws.domain}`);
+            if (ws.schema)
+                headerBits.push(`schema: ${ws.schema}`);
+            if (Array.isArray(ws.vocab) && ws.vocab.length > 0) {
+                headerBits.push(`vocab: ${ws.vocab.join(', ')}`);
+            }
+            if (Array.isArray(ws.relatedWorkspaces) && ws.relatedWorkspaces.length > 0) {
+                headerBits.push(`related: ${ws.relatedWorkspaces.join(', ')}`);
+            }
+            if (ws.enrichmentDisabled === true)
+                headerBits.push('enrichment: disabled');
+            let text = `${headerBits.join('\n')}\nstructure:\n${treeLines.join('\n') || '  (empty)'}`;
             if (ws.context && Object.keys(ws.context).length > 0) {
                 text += `\ncontext:\n${JSON.stringify(ws.context, null, 2)}`;
             }
-            return { content: [{ type: 'text', text }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `${text}${footer}` }] };
         },
     },
     {
         name: 'get_item_context',
-        description: 'Get progressive disclosure context for a document in a workspace: workspace-level context (characters, settings, rules) and tags. Use before writing to understand context.',
+        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, domain, concepts, docRole, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary.',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             docId: z.string().describe('Document docId (8-char hex from list_documents)'),
         },
         handler: async ({ workspaceFile, docId }) => {
             const filename = resolveDocId(docId);
-            return { content: [{ type: 'text', text: JSON.stringify(getItemContext(workspaceFile, filename), null, 2) }] };
+            const base = getItemContext(workspaceFile, filename);
+            // Layer doc-level enrichment + workspace-level vocab/schema into the response.
+            // The agent's crawl pattern: get_item_context for one doc → see logline +
+            // domain + concepts. Decide whether the doc warrants a body read.
+            try {
+                const ws = getWorkspace(workspaceFile);
+                const enriched = crawlDocs({ workspaceFile });
+                const docEnrich = enriched.find((e) => e.filename === filename);
+                if (docEnrich) {
+                    if (docEnrich.logline)
+                        base.logline = docEnrich.logline;
+                    if (docEnrich.domain)
+                        base.domain = docEnrich.domain;
+                    if (docEnrich.concepts)
+                        base.concepts = docEnrich.concepts;
+                    if (docEnrich.docRole)
+                        base.docRole = docEnrich.docRole;
+                    if (docEnrich.status)
+                        base.status = docEnrich.status;
+                    if (docEnrich.enrichmentStale === true)
+                        base.enrichmentStale = true;
+                }
+                if (ws.schema)
+                    base.workspaceSchema = ws.schema;
+                if (Array.isArray(ws.vocab) && ws.vocab.length > 0)
+                    base.workspaceVocab = ws.vocab;
+                if (ws.logline)
+                    base.workspaceLogline = ws.logline;
+                if (ws.domain)
+                    base.workspaceDomain = ws.domain;
+            }
+            catch { /* best-effort enrichment overlay */ }
+            return { content: [{ type: 'text', text: JSON.stringify(base, null, 2) }] };
         },
     },
     {
         name: 'update_workspace_context',
-        description: 'Update a workspace\'s context section (characters, settings, rules). Merges with existing context — only provided keys are changed.',
+        description: 'Update workspace configuration. Accepts writing context (characters, settings, rules — merged into existing) plus enrichment fields (logline, domain, schema, vocab, relatedWorkspaces, enrichmentVolumeThreshold, enrichmentDriftThreshold, enrichmentDisabled — set on workspace top-level). Pass `null` to clear an enrichment field. Use this to opt a workspace out of enrichment (enrichmentDisabled: true), declare a closed vocab for domain classification, or set workspace-level loglines/schemas. One tool covers writing context + enrichment config.',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             context: z.object({
-                characters: z.record(z.string()).optional().describe('Character name → description'),
-                settings: z.record(z.string()).optional().describe('Setting name → description'),
-                rules: z.array(z.string()).optional().describe('Writing rules for this workspace'),
-            }).describe('Context fields to merge'),
+                characters: z.record(z.string()).optional().describe('Character name → description (merged)'),
+                settings: z.record(z.string()).optional().describe('Setting name → description (merged)'),
+                rules: z.array(z.string()).optional().describe('Writing rules for this workspace (replaces)'),
+                logline: z.string().nullable().optional().describe('One-sentence "what this workspace is for". Set null to clear.'),
+                domain: z.string().nullable().optional().describe('Subject area (e.g. "Male ethology"). Set null to clear.'),
+                schema: z.string().nullable().optional().describe('Workspace kind: book / concept-library / inbox / social / reference. Set null to clear.'),
+                vocab: z.array(z.string()).nullable().optional().describe('Closed list of valid domain names — Haiku classifies docs INTO these. Set null to clear (opens vocab to free-form).'),
+                relatedWorkspaces: z.array(z.string()).nullable().optional().describe('Sibling workspace filenames. Set null to clear.'),
+                enrichmentVolumeThreshold: z.number().nullable().optional().describe('Volume-ratio threshold (default 1.5). Set null to revert.'),
+                enrichmentDriftThreshold: z.number().nullable().optional().describe('Jaccard-drift threshold (default 0.3). Set null to revert.'),
+                enrichmentDisabled: z.boolean().nullable().optional().describe('True = opt this workspace out of enrichment surfacing. Set null or false to re-enable.'),
+            }).describe('Writing context + enrichment config to apply'),
         },
         handler: async ({ workspaceFile, context }) => {
             updateWorkspaceContext(workspaceFile, context);
@@ -1075,7 +1366,7 @@ export const TOOL_REGISTRY = [
                     }
                     updateDocument(doc);
                     save();
-                    setAgentLock();
+                    setAgentLockActive();
                     broadcastDocumentSwitched(doc, getTitle(), getActiveFilename(), getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, lastNodeId: imgId }) }] };
                 }
@@ -1153,27 +1444,45 @@ export const TOOL_REGISTRY = [
         },
         handler: async ({ docId, timestamp }) => {
             const target = resolveDocTarget(docId);
-            // Safety net: snapshot current state before restoring
+            // Safety checkpoint = the current canonical state. Under the layered
+            // model, disk is already canonical (pending lives in the sidecar
+            // overlay, not in the .md), so forceSnapshot of the current file is
+            // a clean recovery point. The canonical-only-clone special case is
+            // no longer needed.
+            // adr: adr/pending-overlay-model.md
             try {
                 forceSnapshot(target.docId, target.filePath);
             }
             catch { /* best effort */ }
-            const parsed = restoreVersion(target.docId, timestamp);
-            if (!parsed)
+            // Read the target snapshot's content
+            const snapshotMarkdown = getVersionContent(target.docId, timestamp);
+            if (!snapshotMarkdown)
                 return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
+            // Write the snapshot directly to disk — this becomes the new canonical.
+            // The pending overlay sidecar is unchanged; on reload, the matcher
+            // re-pairs nodeIds and pending decorations re-attach where possible.
+            // Pending entries whose anchors disappeared become orphan-inserts.
+            atomicWriteFileSync(target.filePath, snapshotMarkdown);
             if (target.isActive) {
-                updateDocument(parsed.document);
-                save();
-                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
+                // Unified reload pathway — same code path as external-write reload
+                // and explicit reload_from_disk. Re-reads canonical + applies
+                // sidecar overlay + classifies orphans/stale-baseline.
+                const reloaded = reloadActiveDocFromDisk();
+                if (!reloaded)
+                    return { content: [{ type: 'text', text: `Error: Failed to reload after restore.` }] };
+                broadcastDocumentSwitched(reloaded.document, reloaded.title, reloaded.filename);
+                broadcastPendingDocsChanged();
+                const summary = reloaded.orphans.length > 0 || reloaded.staleBaseline.length > 0
+                    ? ` (${reloaded.orphans.length} orphan, ${reloaded.staleBaseline.length} stale-baseline pending)` : '';
+                return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()}${summary}` }] };
             }
             else {
-                // Write restored content to file without switching active doc
-                const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
-                atomicWriteFileSync(target.filePath, markdown);
                 invalidateDocCache(target.filePath);
+                removePendingCacheEntry(target.filename);
                 broadcastDocumentsChanged();
+                broadcastPendingDocsChanged();
+                return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()}` }] };
             }
-            return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()} — "${parsed.title}"` }] };
         },
     },
     {
@@ -1187,12 +1496,19 @@ export const TOOL_REGISTRY = [
             if (!existsSync(target.filePath))
                 return { content: [{ type: 'text', text: `Error: File not found: ${target.filePath}` }] };
             if (target.isActive) {
-                const markdown = readFileSync(target.filePath, 'utf-8');
-                const parsed = markdownToTiptap(markdown);
-                updateDocument(parsed.document);
-                save();
-                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
-                return { content: [{ type: 'text', text: `Reloaded "${parsed.title}" from disk` }] };
+                // Unified reload pathway — same as the fs.watch handler and
+                // restore_version. Re-parses canonical + re-applies the sidecar
+                // overlay (preserves pending changes by nodeId) + classifies any
+                // orphans / stale-baseline entries + restamps loadedMtime.
+                // adr: adr/pending-overlay-model.md · adr: adr/active-doc-watcher.md
+                const reloaded = reloadActiveDocFromDisk();
+                if (!reloaded)
+                    return { content: [{ type: 'text', text: `Error: Failed to reload from disk.` }] };
+                broadcastDocumentSwitched(reloaded.document, reloaded.title, reloaded.filename);
+                broadcastPendingDocsChanged();
+                const summary = reloaded.orphans.length > 0 || reloaded.staleBaseline.length > 0
+                    ? ` (${reloaded.orphans.length} orphan, ${reloaded.staleBaseline.length} stale-baseline pending)` : '';
+                return { content: [{ type: 'text', text: `Reloaded "${reloaded.title}" from disk${summary}` }] };
             }
             else {
                 // Non-active: just invalidate cache so next access re-reads from disk
@@ -1201,47 +1517,67 @@ export const TOOL_REGISTRY = [
             }
         },
     },
+    {
+        name: 'get_comments',
+        description: 'Get inline reader comments left by the user. Users select text in the editor, right-click → Comment, and leave a note for the agent. Returns comments grouped by document with text, note, nodeId, and a relative age. Default scope is "workspace" when docId is provided — comments for every doc in the same project. Pass scope:"document" to narrow to one doc, or scope:"all" to span every document on disk. Call resolve_comments after addressing each comment.',
+        schema: {
+            docId: z.string().optional().describe('Target document by docId (8-char hex). When provided, default scope is "workspace".'),
+            scope: z.enum(['workspace', 'document', 'all']).optional().describe('Filter scope. Default: "workspace" when docId is given, otherwise "all".'),
+        },
+        handler: async ({ docId, scope }) => {
+            const filename = docId ? resolveDocId(docId) : undefined;
+            const resolved = gatherComments(filename, scope);
+            return { content: [{ type: 'text', text: formatCommentsOutput(resolved) }] };
+        },
+    },
+    {
+        name: 'resolve_comments',
+        description: 'Remove comments after addressing the user\'s feedback. Pass the comment IDs from get_comments. Decorations clear in the browser immediately.',
+        schema: {
+            comment_ids: z.array(z.string()).describe('Array of comment IDs to resolve'),
+        },
+        handler: async ({ comment_ids }) => {
+            const resolved = resolveComments(comment_ids);
+            const activeFile = getActiveFilename();
+            broadcastCommentsChanged(activeFile);
+            return {
+                content: [{
+                        type: 'text',
+                        text: resolved.length > 0
+                            ? `Resolved ${resolved.length} comment${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
+                            : 'No matching comments found.',
+                    }],
+            };
+        },
+    },
     {
         name: 'get_agent_marks',
-        description: 'Get inline feedback marks left by the user. Users select text in the editor, right-click → Agent Mark, and leave notes for the agent. Returns marks grouped by document with text, note, and nodeId. Call resolve_agent_marks after addressing each mark.',
+        description: 'DEPRECATED — renamed to get_comments. Use get_comments instead. This alias may be removed in a future release.',
         schema: {
-            docId: z.string().optional().describe('Target document by docId (8-char hex). Omit to get marks across all documents.'),
+            docId: z.string().optional().describe('Target document by docId (8-char hex). Omit to get comments across all documents.'),
         },
         handler: async ({ docId }) => {
             const filename = docId ? resolveDocId(docId) : undefined;
-            const marks = getMarks(filename);
-            const entries = Object.entries(marks);
-            if (entries.length === 0) {
-                return { content: [{ type: 'text', text: 'No agent marks found.' }] };
-            }
-            const lines = [];
-            for (const [file, fileMarks] of entries) {
-                lines.push(`${file}:`);
-                for (const m of fileMarks) {
-                    const notePart = m.note ? ` — "${m.note}"` : '';
-                    lines.push(`  [${m.id}] "${m.text}"${notePart}  (node:${m.nodeId})`);
-                }
-            }
-            return { content: [{ type: 'text', text: lines.join('\n') }] };
+            const resolved = gatherComments(filename, undefined);
+            return { content: [{ type: 'text', text: formatCommentsOutput(resolved) }] };
         },
     },
     {
         name: 'resolve_agent_marks',
-        description: 'Remove agent marks after addressing the user\'s feedback. Pass the mark IDs from get_agent_marks. Decorations clear in the browser immediately.',
+        description: 'DEPRECATED — renamed to resolve_comments. Use resolve_comments instead. This alias may be removed in a future release.',
         schema: {
-            mark_ids: z.array(z.string()).describe('Array of mark IDs to resolve'),
+            mark_ids: z.array(z.string()).describe('Array of comment IDs to resolve'),
         },
         handler: async ({ mark_ids }) => {
-            const resolved = resolveMarks(mark_ids);
-            // Broadcast to browser so decorations update
+            const resolved = resolveComments(mark_ids);
             const activeFile = getActiveFilename();
-            broadcastMarksChanged(activeFile);
+            broadcastCommentsChanged(activeFile);
             return {
                 content: [{
                         type: 'text',
                         text: resolved.length > 0
-                            ? `Resolved ${resolved.length} mark${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
-                            : 'No matching marks found.',
+                            ? `Resolved ${resolved.length} comment${resolved.length !== 1 ? 's' : ''}: ${resolved.join(', ')}`
+                            : 'No matching comments found.',
                     }],
             };
         },
@@ -1298,17 +1634,68 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'link_to',
-        description: 'Wrap anchor text in the ACTIVE doc with a doc: link pointing at another doc. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
+        description: 'Wrap anchor text in a source doc with a doc: link pointing at another doc. Operates in place on the block containing the anchor text — never creates a duplicate paragraph. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
         schema: {
-            text: z.string().describe('Anchor text in the active doc to wrap with the link. Exact substring match. First occurrence wins if the text appears multiple times.'),
-            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs).'),
+            text: z.string().describe('Anchor text in the source doc to wrap with the link. Exact substring match. First UNLINKED occurrence wins — calling link_to N times with the same anchor wraps N distinct occurrences, skipping ones already linked to the same target.'),
+            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc containing the anchor text. NOT the active doc — must be explicit so user-driven navigation in the browser can\'t silently change the target.'),
+            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the link points AT.'),
             target_node_id: z.string().optional().describe('Optional 8-char hex nodeId for paragraph-level targeting. When provided, clicking the link scrolls to that paragraph in the target doc.'),
             quote: z.string().optional().describe('Optional text snippet for scroll-anchor fallback when target_node_id has drifted (e.g. paragraph was rewritten).'),
         },
-        handler: async ({ text, target_doc_id, target_node_id, quote }) => {
-            // 1. Locate the block in the active doc that contains the anchor text
-            const doc = getDocument();
+        handler: async ({ text, source_doc_id, target_doc_id, target_node_id, quote }) => {
+            const sourceFilename = resolveDocId(source_doc_id);
+            if (!sourceFilename) {
+                return { content: [{ type: 'text', text: `source_doc_id "${source_doc_id}" not found. Use list_documents to find the right docId.` }] };
+            }
+            // Build the href in canonical doc:DOCID#NODEID?q=quote form so we can also
+            // detect "this text is already wrapped with THIS link" and skip it.
+            let href = `doc:${target_doc_id}`;
+            if (target_node_id)
+                href += `#${target_node_id}`;
+            if (quote)
+                href += `?q=${encodeURIComponent(quote)}`;
+            // Load the source doc — from in-memory state if it's active, from disk
+            // otherwise. Explicit source dispatch prevents the active-doc race where
+            // a user click in the browser silently changes which doc gets edited.
+            const sourceIsActive = sourceFilename === getActiveFilename();
+            let sourceDoc;
+            if (sourceIsActive) {
+                sourceDoc = getDocument();
+            }
+            else {
+                const cached = getCachedDocument(resolveDocPath(sourceFilename));
+                if (cached) {
+                    sourceDoc = cached.document;
+                }
+                else {
+                    try {
+                        const raw = readFileSync(resolveDocPath(sourceFilename), 'utf-8');
+                        sourceDoc = markdownToTiptap(raw).document;
+                    }
+                    catch (err) {
+                        return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}": ${err.message}` }] };
+                    }
+                }
+            }
+            // Locate the first block containing the anchor text WHERE the text is
+            // not already entirely wrapped with a link to the same href. This makes
+            // link_to idempotent and lets repeat calls wrap successive occurrences.
             let sourceNodeId = null;
+            let totalOccurrences = 0;
+            let alreadyLinkedOccurrences = 0;
+            function isTextAlreadyLinked(nodeContent) {
+                // Concatenate text from inline children that have a link mark matching href
+                let linkedText = '';
+                for (const child of nodeContent) {
+                    if (child.type !== 'text' || !child.text)
+                        continue;
+                    const marks = child.marks || [];
+                    const hasMatchingLink = marks.some((m) => m.type === 'link' && m.attrs?.href === href);
+                    if (hasMatchingLink)
+                        linkedText += child.text;
+                }
+                return linkedText.includes(text);
+            }
             function walk(nodes) {
                 if (sourceNodeId)
                     return;
@@ -1318,6 +1705,12 @@ export const TOOL_REGISTRY = [
                     if (Array.isArray(node.content)) {
                         const blockText = node.content.map((c) => c.text || '').join('');
                         if (node.attrs?.id && blockText.includes(text)) {
+                            totalOccurrences++;
+                            if (isTextAlreadyLinked(node.content)) {
+                                alreadyLinkedOccurrences++;
+                                walk(node.content);
+                                continue;
+                            }
                             sourceNodeId = node.attrs.id;
                             return;
                         }
@@ -1325,26 +1718,32 @@ export const TOOL_REGISTRY = [
                     }
                 }
             }
-            walk(doc.content);
+            walk(sourceDoc.content);
             if (!sourceNodeId) {
-                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in the active doc. Use search_docs first to locate the right doc.` }] };
+                if (totalOccurrences > 0 && totalOccurrences === alreadyLinkedOccurrences) {
+                    return { content: [{ type: 'text', text: `Anchor text "${text}" found in source doc but all ${totalOccurrences} occurrence(s) are already linked to ${href}. Nothing to do.` }] };
+                }
+                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in source doc "${source_doc_id}" (${sourceFilename}). Use search_docs or read_pad to verify.` }] };
             }
-            // 2. Build the href in canonical doc:DOCID#NODEID?q=quote form
-            let href = `doc:${target_doc_id}`;
-            if (target_node_id)
-                href += `#${target_node_id}`;
-            if (quote)
-                href += `?q=${encodeURIComponent(quote)}`;
-            // 3. Apply the link mark to the matched substring via the existing text-edit pipeline
-            const result = applyTextEdits(sourceNodeId, [{
-                    find: text,
-                    addMark: { type: 'link', attrs: { href } },
-                }]);
-            if (!result.success) {
-                return { content: [{ type: 'text', text: `Failed to apply link mark: ${result.error}` }] };
+            // Apply the link mark in place. Dispatch by active vs non-active so the
+            // edit always lands in the right doc — never silently in whatever doc
+            // happens to be foregrounded in the browser.
+            const editResult = sourceIsActive
+                ? applyTextEdits(sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }])
+                : applyTextEditsToFile(sourceFilename, sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }]);
+            if (!editResult.success) {
+                return { content: [{ type: 'text', text: `Failed to apply link mark: ${editResult.error}` }] };
             }
-            save(); // triggers writeToDisk → backlinks pipeline auto-updates the target's frontmatter
-            return { content: [{ type: 'text', text: `Linked "${text}" in node ${sourceNodeId} → ${href}. Target doc's backlinks frontmatter will refresh on next save.` }] };
+            if (sourceIsActive)
+                save(); // triggers writeToDisk → backlinks pipeline updates target's frontmatter
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            success: true,
+                            sourceDocId: source_doc_id,
+                            sourceFilename,
+                            nodeId: sourceNodeId,
+                            href,
+                            ...(totalOccurrences > 1 ? { remainingUnlinked: totalOccurrences - alreadyLinkedOccurrences - 1 } : {}),
+                        }) }] };
         },
     },
     {
@@ -1357,16 +1756,29 @@ export const TOOL_REGISTRY = [
         handler: async ({ query, limit = 10 }) => {
             const cap = Math.min(Math.max(limit, 1), 50);
             const raw = searchDocuments(query);
-            // Enrich with docId by reading each result's frontmatter
+            // Enrich with docId + enrichment fields from frontmatter so the agent
+            // can rank/pick candidates without a follow-up body read.
             const enriched = raw.slice(0, cap).map((r) => {
                 let docId = null;
+                let logline;
+                let domain;
+                let docRole;
+                let tags;
                 try {
                     const filePath = resolveDocPath(r.filename);
                     const fileRaw = readFileSync(filePath, 'utf-8');
                     const fm = matter(fileRaw);
                     docId = fm.data?.docId || null;
+                    if (typeof fm.data?.logline === 'string')
+                        logline = fm.data.logline;
+                    if (typeof fm.data?.domain === 'string')
+                        domain = fm.data.domain;
+                    if (typeof fm.data?.docRole === 'string')
+                        docRole = fm.data.docRole;
+                    if (Array.isArray(fm.data?.tags) && fm.data.tags.length > 0)
+                        tags = fm.data.tags;
                 }
-                catch { /* docId stays null */ }
+                catch { /* fields stay undefined */ }
                 return {
                     docId,
                     title: r.title,
@@ -1374,6 +1786,10 @@ export const TOOL_REGISTRY = [
                     matchType: r.matchType,
                     snippet: r.snippet,
                     matchedTag: r.matchedTag,
+                    ...(logline ? { logline } : {}),
+                    ...(domain ? { domain } : {}),
+                    ...(docRole ? { docRole } : {}),
+                    ...(tags ? { tags } : {}),
                 };
             });
             return { content: [{ type: 'text', text: JSON.stringify(enriched) }] };
@@ -1501,12 +1917,35 @@ export function removePluginTools(names) {
     }
 }
 export async function startMcpServer() {
+    // Build session-start enrichment notice. Read once at boot — MCP's instructions
+    // field is delivered as part of the InitializeResult and becomes part of the
+    // agent's system context. Empty string when no enrichment work is pending.
+    // See brief 2026-05-18-frontmatter-enrichment-system.
+    const enrichmentNotice = buildEnrichmentInstructions();
     const server = new McpServer({
         name: 'openwriter',
         version: '0.2.0',
-    });
+    }, enrichmentNotice ? { instructions: enrichmentNotice } : undefined);
+    // Wrap each tool handler in withRequestId so every event logged during
+    // the tool's execution inherits the same request ID. Trace one MCP call
+    // through the system with: jq 'select(.requestId=="mcp-toolname-xxxxxx")'.
+    // adr: adr/logging-system.md
     for (const tool of TOOL_REGISTRY) {
-        server.tool(tool.name, tool.description, tool.schema, tool.handler);
+        const wrappedHandler = async (args) => {
+            const reqId = generateRequestId(`mcp-${tool.name}`);
+            return await withRequestId(reqId, async () => {
+                logger.debug('mcp', 'tool-call', tool.name, { tool: tool.name });
+                try {
+                    const result = await tool.handler(args);
+                    return result;
+                }
+                catch (err) {
+                    logger.error('mcp', 'tool-error', `${tool.name}: ${err.message}`, { tool: tool.name }, err);
+                    throw err;
+                }
+            });
+        };
+        server.tool(tool.name, tool.description, tool.schema, wrappedHandler);
     }
     mcpServerInstance = server;
     const transport = new StdioServerTransport();