openwriter 0.12.1 → 0.14.0

package/dist/server/markdown-parse.js

@@ -1,6 +1,15 @@
 /**
  * Markdown -> TipTap JSON parsing.
  * Parses markdown (with optional YAML frontmatter) into TipTap document JSON.
+ *
+ * Node identity is reassigned via the matcher when the frontmatter carries a
+ * `nodes` array (the new path). For legacy docs without `nodes`, trailing
+ * `^id` caret anchors and `<!-- ^id -->` empty-paragraph markers are still
+ * recognized as ID sources so existing files keep their identities through
+ * the migration. Once a migrated doc is saved, the body is clean and all
+ * identity lives in frontmatter.
+ *
+ * adr: adr/node-identity-matcher.md
  */
 import MarkdownIt from 'markdown-it';
 import matter from 'gray-matter';
@@ -10,6 +19,8 @@ import markdownItSub from 'markdown-it-sub';
 import markdownItSup from 'markdown-it-sup';
 import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
 import { nodeText } from './markdown-serialize.js';
+import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
+import { matchNodes } from './node-matcher.js';
 // ============================================================================
 // Markdown -> TipTap
 // ============================================================================
@@ -19,24 +30,152 @@ md.use(markdownItIns);
 md.use(markdownItMark);
 md.use(markdownItSub);
 md.use(markdownItSup);
+/**
+ * Normalize blank lines INSIDE markdown tables before parsing.
+ *
+ * Per CommonMark, a blank line terminates a table block. Agents writing
+ * markdown content frequently insert blank lines between table rows for
+ * readability (e.g. `| row |\n\n| row |`), which the strict parser then
+ * splits into "table with 1 header row" + N orphan paragraphs that happen
+ * to contain pipe characters. The broken structure persists across saves
+ * because every serialize → re-parse cycle re-breaks it.
+ *
+ * This pre-pass detects "table region" (saw a separator row `| --- |`,
+ * haven't hit a non-pipe-row yet) and strips blank lines between pipe-rows
+ * inside that region. Code fences (` ``` `, `~~~`) are honored — pipes
+ * inside them stay untouched.
+ *
+ * Self-healing: a doc on disk with blank-separated rows loads as a proper
+ * N-row table; the next save writes contiguous markdown. No migration
+ * script needed.
+ */
+function normalizeTableBlankLines(markdown) {
+    if (!markdown.includes('|'))
+        return markdown;
+    const lines = markdown.split('\n');
+    const out = [];
+    let inFence = false;
+    let inTable = false; // true between a separator row and the next non-pipe-row
+    const isPipeRow = (s) => /^\s*\|.*\|\s*$/.test(s);
+    const isSeparator = (s) => /^\s*\|[\s:|-]+\|\s*$/.test(s);
+    const isBlank = (s) => s.trim() === '';
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Code-fence toggle — pipes inside fences stay verbatim
+        if (/^[`~]{3,}/.test(line)) {
+            inFence = !inFence;
+            inTable = false;
+            out.push(line);
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        if (isSeparator(line)) {
+            // Separator confirms we're in a table region from here on
+            inTable = true;
+            out.push(line);
+            continue;
+        }
+        if (inTable && isBlank(line)) {
+            // Look ahead past additional blanks for the next non-blank line
+            let j = i + 1;
+            while (j < lines.length && lines[j].trim() === '')
+                j++;
+            // If the next non-blank line is another pipe-row, it's EITHER a
+            // continuation row (merge across the blank) OR the header of a NEW
+            // table (the blank is the boundary, don't merge). We tell them apart
+            // by peeking one further: if line j+1 is a separator row, j is a new
+            // table's header — preserve the blank and exit the current table region.
+            if (j < lines.length && isPipeRow(lines[j])) {
+                if (j + 1 < lines.length && isSeparator(lines[j + 1])) {
+                    // New table starting — keep the boundary blank, end current region
+                    inTable = false;
+                    out.push(line);
+                    continue;
+                }
+                // Continuation row — drop the blank
+                continue;
+            }
+            // Lookahead found non-pipe content — table region is ending
+            inTable = false;
+            out.push(line);
+            continue;
+        }
+        if (inTable && !isPipeRow(line)) {
+            // Non-pipe content ends the table region
+            inTable = false;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
 export function markdownToTiptap(markdown) {
     const result = matter(markdown);
     const { data, content } = result;
     const title = data.title || 'Untitled';
-    const tokens = md.parse(content, {});
+    const normalizedContent = normalizeTableBlankLines(content);
+    const tokens = md.parse(normalizedContent, {});
     const docContent = tokensToTiptap(tokens);
     const doc = {
         type: 'doc',
         content: docContent.length > 0 ? docContent : [{ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] }],
     };
+    // Extract identity graph from frontmatter — these become the matcher's
+    // previousNodes input on both the load-time pass below AND on every
+    // subsequent save-time pass while the doc stays loaded.
+    const previousNodes = normalizeNodeEntries(data.nodes);
+    const graveyard = normalizeNodeEntries(data.graveyard);
+    // Load-time matcher pass — when frontmatter carries `nodes`, reassign IDs
+    // based on fingerprint match. Legacy docs (no `nodes` field) keep whatever
+    // IDs the body parser extracted from caret anchors or minted fresh.
+    if (previousNodes.length > 0) {
+        applyMatcher(doc, previousNodes, graveyard);
+    }
     // Rehydrate pending state from frontmatter into node attrs
     if (data.pending) {
         rehydratePendingState(doc, data.pending);
     }
-    // Strip pending from returned metadata (consumed into node attrs)
+    // Strip consumed keys from returned metadata
     const metadata = { ...data };
     delete metadata.pending;
-    return { title, metadata, document: doc, rawFrontmatter: result.matter || null };
+    delete metadata.nodes;
+    delete metadata.graveyard;
+    return {
+        title,
+        metadata,
+        document: doc,
+        rawFrontmatter: result.matter || null,
+        graveyard,
+        previousNodes,
+    };
+}
+/** Defensive parse of frontmatter node entries — drops any malformed rows. */
+function normalizeNodeEntries(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((entry) => entry && typeof entry === 'object' && entry.id && entry.fp)
+        .map((entry) => ({ id: String(entry.id), fingerprint: entry.fp }));
+}
+/**
+ * Run the matcher: compare frontmatter `nodes` (previous fingerprints) to
+ * the current TipTap tree's blocks, then apply pinned IDs back onto the tree.
+ *
+ * Graveyard is passed through so paste-back of recently-deleted content
+ * restores the original ID (matched by exact fingerprint).
+ */
+function applyMatcher(doc, previousNodes, graveyard) {
+    if (previousNodes.length === 0)
+        return;
+    const newBlocks = tiptapToBlocks(doc);
+    const matchResult = matchNodes(previousNodes, newBlocks, { graveyard });
+    const pinnedByPosition = new Map();
+    for (const p of matchResult.pinned) {
+        pinnedByPosition.set(p.position, p.id);
+    }
+    applyIdsToTiptap(doc, pinnedByPosition);
 }
 /**
  * Rehydrate pending state from frontmatter into leaf block node attrs.
@@ -116,19 +255,21 @@ function tokensToTiptap(tokens) {
         if (token.type === 'heading_open') {
             const level = parseInt(token.tag.slice(1));
             const inlineToken = tokens[i + 1];
-            const content = inlineToken?.children ? inlineTokensToTiptap(inlineToken.children) : [];
-            nodes.push({ type: 'heading', attrs: { id: generateNodeId(), level }, content });
+            const rawContent = inlineToken?.children ? inlineTokensToTiptap(inlineToken.children) : [];
+            const { content, id } = extractTrailingNodeId(rawContent);
+            nodes.push({ type: 'heading', attrs: { id: id || generateNodeId(), level }, content });
             i += 3;
         }
         else if (token.type === 'paragraph_open') {
             const inlineToken = tokens[i + 1];
-            const content = inlineToken?.children ? inlineTokensToTiptap(inlineToken.children) : [];
+            const rawContent = inlineToken?.children ? inlineTokensToTiptap(inlineToken.children) : [];
+            const { content, id } = extractTrailingNodeId(rawContent);
             // Check for solo image — promote to block-level image node
             if (content.length === 1 && content[0].type === 'image') {
                 nodes.push(content[0]);
             }
             else {
-                nodes.push({ type: 'paragraph', attrs: { id: generateNodeId() }, content });
+                nodes.push({ type: 'paragraph', attrs: { id: id || generateNodeId() }, content });
             }
             i += 3;
         }
@@ -168,10 +309,18 @@ function tokensToTiptap(tokens) {
             i += 1;
         }
         else if (token.type === 'html_block') {
-            // <!-- --> is our sentinel for empty paragraphs
-            if (token.content.trim() === '<!-- -->') {
+            // <!-- --> is our sentinel for empty paragraphs.
+            // <!-- ^abc12345 --> is the same sentinel with a persisted nodeId.
+            const trimmed = token.content.trim();
+            if (trimmed === '<!-- -->') {
                 nodes.push({ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] });
             }
+            else {
+                const idMatch = trimmed.match(/^<!--\s*\^([a-f0-9]{8})\s*-->$/);
+                if (idMatch) {
+                    nodes.push({ type: 'paragraph', attrs: { id: idMatch[1] }, content: [] });
+                }
+            }
             i += 1;
         }
         else if (token.type === 'table_open') {
@@ -440,3 +589,32 @@ function popMarkByType(stack, type) {
         }
     }
 }
+/**
+ * Extract a trailing nodeId anchor from inline content.
+ * Format: ` ^abc12345` (space + caret + 8 lowercase hex chars at end of line).
+ * Strips the marker from the visible text and returns the captured id.
+ * Returns id=null if no anchor found.
+ *
+ * Known limit: prose ending with the literal pattern ` ^[8 lowercase hex]`
+ * will be interpreted as an anchor. Vanishingly rare in real writing.
+ */
+function extractTrailingNodeId(content) {
+    if (!content || content.length === 0)
+        return { content, id: null };
+    const lastNode = content[content.length - 1];
+    if (lastNode.type !== 'text' || !lastNode.text)
+        return { content, id: null };
+    const match = lastNode.text.match(/ \^([a-f0-9]{8})\s*$/);
+    if (!match)
+        return { content, id: null };
+    const id = match[1];
+    const newText = lastNode.text.slice(0, match.index);
+    const newContent = [...content];
+    if (newText) {
+        newContent[newContent.length - 1] = { ...lastNode, text: newText };
+    }
+    else {
+        newContent.pop();
+    }
+    return { content: newContent, id };
+}

package/dist/server/markdown-serialize.js

@@ -1,8 +1,24 @@
 /**
  * TipTap JSON -> Markdown serialization.
  * Converts TipTap document to markdown with YAML frontmatter.
+ *
+ * Node identity persistence:
+ *   - Frontmatter `nodes` array carries the (id, fingerprint) pair for every
+ *     block in the document. On load, markdown-parse.ts runs the matcher
+ *     against this array to reassign IDs to surviving blocks.
+ *   - Markdown body is COMPLETELY UNDISTURBED — no anchors, no comment
+ *     sentinels (except the legacy `<!-- -->` empty-paragraph marker which
+ *     has no semantic ID attached anymore).
+ *   - Legacy `^id` caret anchors are no longer emitted. Old docs that still
+ *     contain them are migrated transparently on the next save: parse reads
+ *     the anchors, matcher pins them, serialize emits the new `nodes`
+ *     frontmatter and a clean body.
+ *
+ * adr: adr/node-identity-matcher.md
  */
-import { LEAF_BLOCK_TYPES } from './helpers.js';
+import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
+import { tiptapToBlocks } from './node-blocks.js';
+import { fingerprintAll } from './node-fingerprint.js';
 // ============================================================================
 // TipTap -> Markdown
 // ============================================================================
@@ -57,11 +73,67 @@ function collectPendingState(doc) {
     walk(doc.content || []);
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
+/**
+ * Build the `nodes` frontmatter entry — one (id, fingerprint) per block
+ * in pre-order traversal of the TipTap tree.
+ *
+ * Each block's ID comes from its TipTap node's `attrs.id`. Fingerprints are
+ * computed from the walker-style block list derived directly from the TipTap
+ * tree (no separate markdown re-parse — same source of truth that builds
+ * the visible doc).
+ */
+function collectNodesFrontmatter(doc) {
+    const blocks = tiptapToBlocks(doc);
+    const fingerprints = fingerprintAll(blocks);
+    const ids = collectBlockIds(doc);
+    // ids array is parallel to blocks array — same pre-order traversal.
+    const entries = [];
+    for (let i = 0; i < blocks.length; i++) {
+        const id = ids[i] || generateNodeId();
+        entries.push({ id, fp: fingerprints[i] });
+    }
+    return entries;
+}
+/**
+ * Cap graveyard size to avoid frontmatter bloat on docs with many edits.
+ * Newest entries (highest position) win — the ones most likely to be
+ * paste-back targets. Older entries expire silently.
+ */
+const GRAVEYARD_MAX = 50;
+/** Walk the TipTap tree in the SAME pre-order as tiptapToBlocks, collect IDs. */
+function collectBlockIds(doc) {
+    const ids = [];
+    const blockTypes = new Set([
+        'heading', 'paragraph', 'bulletList', 'orderedList', 'taskList',
+        'listItem', 'taskItem', 'blockquote', 'codeBlock', 'horizontalRule',
+        'table', 'image', 'tableRow', 'tableCell', 'tableHeader',
+    ]);
+    const containerTypes = new Set([
+        'bulletList', 'orderedList', 'taskList', 'listItem', 'taskItem', 'blockquote',
+    ]);
+    function walk(nodes) {
+        if (!nodes)
+            return;
+        for (const node of nodes) {
+            if (blockTypes.has(node.type)) {
+                ids.push(node.attrs?.id || '');
+                if (containerTypes.has(node.type) && node.content)
+                    walk(node.content);
+            }
+            else if (node.content) {
+                walk(node.content);
+            }
+        }
+    }
+    walk(doc.content || []);
+    return ids;
+}
 /**
  * Convert TipTap document to markdown with JSON frontmatter.
  * Metadata stored as minified JSON between --- delimiters (valid YAML).
  * Editor never sees frontmatter — it's stripped on load, regenerated on save.
  * Pending state is persisted in frontmatter `pending` key.
+ * Node identity persisted in frontmatter `nodes` key (id + fingerprint per block).
  */
 export function tiptapToMarkdown(doc, title, metadata) {
     const meta = { ...metadata, title };
@@ -73,6 +145,24 @@ export function tiptapToMarkdown(doc, title, metadata) {
     else {
         delete meta.pending;
     }
+    // Collect node identity graph (id + fingerprint per block) for next-load matcher
+    const nodes = collectNodesFrontmatter(doc);
+    if (nodes.length > 0) {
+        meta.nodes = nodes;
+    }
+    else {
+        delete meta.nodes;
+    }
+    // Graveyard: recently-orphaned (id, fingerprint) entries kept across saves so
+    // paste-back/undo can restore the original ID via exact fingerprint match.
+    // The caller (writeToDisk) puts the matcher's nextGraveyard into metadata.graveyard;
+    // we cap it here to keep the file small.
+    if (Array.isArray(meta.graveyard) && meta.graveyard.length > 0) {
+        meta.graveyard = meta.graveyard.slice(0, GRAVEYARD_MAX);
+    }
+    else {
+        delete meta.graveyard;
+    }
     // Strip undefined/null values
     for (const key of Object.keys(meta)) {
         if (meta[key] === undefined || meta[key] === null)
@@ -98,11 +188,16 @@ function nodeToMarkdown(node, indent) {
         case 'heading': {
             const level = node.attrs?.level || 1;
             const prefix = '#'.repeat(level);
+            // Body stays undisturbed — node ID is persisted in frontmatter `nodes`, not as a trailing anchor.
             return `${prefix} ${inlineToMarkdown(node.content)}\n\n`;
         }
         case 'paragraph': {
             const text = inlineToMarkdown(node.content);
-            return text ? `${indent}${text}\n\n` : `${indent}<!-- -->\n\n`;
+            if (text) {
+                return `${indent}${text}\n\n`;
+            }
+            // Empty paragraph: use plain sentinel (frontmatter `nodes` carries the ID).
+            return `${indent}<!-- -->\n\n`;
         }
         case 'bulletList':
             return listToMarkdown(node.content, '- ', indent);

package/dist/server/markdown.js

@@ -1,6 +1,38 @@
 /**
  * Barrel re-export for markdown serialization and parsing.
  * All existing imports from './markdown.js' continue to work unchanged.
+ *
+ * Also exposes `tiptapToMarkdownChecked` — a sync-observed wrapper that
+ * verifies the TipTap → markdown → TipTap round-trip preserves document
+ * shape. Use this when you want to catch silent drift; the unchecked
+ * `tiptapToMarkdown` stays the cheap path for hot loops.
  */
+import { tiptapToMarkdown } from './markdown-serialize.js';
+import { markdownToTiptap } from './markdown-parse.js';
+import { shapeOfTiptap, compareShapes, formatSyncReport, } from './node-sync-check.js';
 export { tiptapToMarkdown, tiptapToBody, nodeText, inlineToMarkdown } from './markdown-serialize.js';
 export { markdownToTiptap, markdownToNodes } from './markdown-parse.js';
+export { shapeOfTiptap, computeShape, compareShapes, formatSyncReport, } from './node-sync-check.js';
+/**
+ * Serialize TipTap to markdown, then re-parse and verify that the round-trip
+ * preserved document shape. If the shapes diverge, a node was misapplied —
+ * content ended up in the wrong block on save, or the parse interpreted
+ * something differently than the serialize emitted.
+ *
+ * Returns the markdown AND the sync report. Callers decide whether a failed
+ * report should block the save (throw) or just log and continue.
+ *
+ * Cost: one extra parse + two shape computations per save. Acceptable for
+ * any user-driven save; consider the unchecked path inside tight loops.
+ */
+export function tiptapToMarkdownChecked(doc, title, metadata) {
+    const markdown = tiptapToMarkdown(doc, title, metadata);
+    const expectedShape = shapeOfTiptap(doc);
+    const reparsed = markdownToTiptap(markdown);
+    const actualShape = shapeOfTiptap(reparsed.document);
+    const syncReport = compareShapes(expectedShape, actualShape);
+    if (!syncReport.ok) {
+        console.error(formatSyncReport(syncReport, `serialize:${title}`));
+    }
+    return { markdown, syncReport };
+}

package/dist/server/marks.js

@@ -114,6 +114,15 @@ export function getGlobalMarkSummary(excludeFilename) {
     catch { /* dir doesn't exist */ }
     return { totalMarks, docCount };
 }
+export function editMark(filename, id, note) {
+    const data = readMarkFile(filename);
+    const mark = data.marks.find((m) => m.id === id);
+    if (!mark)
+        return null;
+    mark.note = note;
+    writeMarkFile(filename, data);
+    return mark;
+}
 export function resolveMarks(ids) {
     const idSet = new Set(ids);
     const resolved = [];

package/dist/server/mcp.js

@@ -10,8 +10,9 @@ 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, } from './state.js';
-import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId } from './documents.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 { 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 { findDocNode } from './workspace-tree.js';
@@ -221,8 +222,9 @@ export const TOOL_REGISTRY = [
                 pendingChanges: target.pendingCount,
                 lastModified: target.lastModified.toISOString(),
             };
-            // Surface autoAccept so the agent stops waiting for review when it's on.
-            if (target.metadata?.autoAccept === true)
+            // Surface effective autoAccept (doc flag OR workspace/container inherited)
+            // so the agent stops waiting for review when it's on.
+            if (isAutoAcceptActive(target.filename, target.metadata))
                 status.autoAccept = true;
             const latestVersion = getUpdateInfo();
             const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
@@ -414,9 +416,10 @@ export const TOOL_REGISTRY = [
                     };
                 }
                 // Active target (or no filename): existing flow.
-                // Skip pending tagging when autoAccept is on for this doc — content commits directly.
+                // 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
-                if (getMetadata()?.autoAccept !== true) {
+                if (!isAutoAcceptActive(filename || getActiveFilename(), getMetadata())) {
                     markAllNodesAsPending(doc, 'insert');
                 }
                 updateDocument(doc);
@@ -1293,6 +1296,145 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: ok ? `Removed task ${id}.` : `Task ${id} not found.` }] };
         },
     },
+    {
+        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.',
+        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).'),
+            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();
+            let sourceNodeId = null;
+            function walk(nodes) {
+                if (sourceNodeId)
+                    return;
+                for (const node of nodes) {
+                    if (sourceNodeId)
+                        return;
+                    if (Array.isArray(node.content)) {
+                        const blockText = node.content.map((c) => c.text || '').join('');
+                        if (node.attrs?.id && blockText.includes(text)) {
+                            sourceNodeId = node.attrs.id;
+                            return;
+                        }
+                        walk(node.content);
+                    }
+                }
+            }
+            walk(doc.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.` }] };
+            }
+            // 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}` }] };
+            }
+            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.` }] };
+        },
+    },
+    {
+        name: 'search_docs',
+        description: 'Full-text search across all documents. Returns ranked candidates with docId, title, match type, and snippet. Use this BEFORE link_to to find the right target — the agent\'s primary primitive for resolving concept references to their canonical docs.',
+        schema: {
+            query: z.string().describe('Search query (case-insensitive substring match against title, tags, then content).'),
+            limit: z.number().optional().describe('Max results to return (default 10, max 50).'),
+        },
+        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
+            const enriched = raw.slice(0, cap).map((r) => {
+                let docId = null;
+                try {
+                    const filePath = resolveDocPath(r.filename);
+                    const fileRaw = readFileSync(filePath, 'utf-8');
+                    const fm = matter(fileRaw);
+                    docId = fm.data?.docId || null;
+                }
+                catch { /* docId stays null */ }
+                return {
+                    docId,
+                    title: r.title,
+                    filename: r.filename,
+                    matchType: r.matchType,
+                    snippet: r.snippet,
+                    matchedTag: r.matchedTag,
+                };
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(enriched) }] };
+        },
+    },
+    {
+        name: 'get_graph',
+        description: 'Return forward links + backlinks for a doc — the crawl primitive for cross-doc context retrieval. Forward links extracted from the doc body, backlinks read from the doc\'s frontmatter (maintained by the on-save backlinks pipeline). Optional depth walks neighbors recursively (cap 3).',
+        schema: {
+            docId: z.string().describe('Center docId for the graph walk (8-char hex).'),
+            depth: z.number().optional().describe('Hops to walk outward (default 1, max 3). depth=1 returns just the center\'s links; depth=2 also includes neighbors\' links.'),
+        },
+        handler: async ({ docId, depth = 1 }) => {
+            const maxDepth = Math.min(Math.max(depth, 1), 3);
+            const seen = new Set();
+            const nodes = [];
+            function visit(id, hopsLeft) {
+                if (seen.has(id) || hopsLeft < 0)
+                    return;
+                seen.add(id);
+                let target;
+                try {
+                    target = resolveDocTarget(id);
+                }
+                catch {
+                    return;
+                }
+                const forward = extractForwardLinks(target.document, id);
+                const backlinks = Array.isArray(target.metadata.backlinks) ? target.metadata.backlinks : [];
+                nodes.push({
+                    docId: id,
+                    title: target.title,
+                    forward: forward.map((l) => ({
+                        text: l.text,
+                        from_node: l.from_node,
+                        to_doc: l.to_doc,
+                        ...(l.to_node ? { to_node: l.to_node } : {}),
+                    })),
+                    backlinks: backlinks.map((b) => ({
+                        text: b.text,
+                        from_doc: b.from_doc,
+                        from_node: b.from_node,
+                        ...(b.to_node ? { to_node: b.to_node } : {}),
+                    })),
+                });
+                if (hopsLeft > 0) {
+                    const neighbors = new Set();
+                    for (const l of forward)
+                        neighbors.add(l.to_doc);
+                    for (const b of backlinks)
+                        neighbors.add(b.from_doc);
+                    for (const n of neighbors) {
+                        if (!seen.has(n))
+                            visit(n, hopsLeft - 1);
+                    }
+                }
+            }
+            visit(docId, maxDepth - 1);
+            return { content: [{ type: 'text', text: JSON.stringify(nodes) }] };
+        },
+    },
 ];
 /** Live MCP server instance — used to register plugin tools dynamically. */
 let mcpServerInstance = null;