openwriter 0.23.0 → 0.25.0

package/dist/server/mcp.js

@@ -10,10 +10,11 @@ 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, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, getCanonical, cloneWithPendingReverted, bumpDocVersion, } from './state.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, setSortProposalOnFile, clearSortRequestOnFile, } from './state.js';
 import { tiptapToBlocks } from './node-blocks.js';
+import { outline, peek, searchInDoc, truncateRead } from './peek-outline.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
-import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions } from './documents.js';
+import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions, listPendingSorts, sortFooter, buildSortInstructions } from './documents.js';
 import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBacklinksCache } from './backlinks.js';
 import { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged, broadcastActivityEvent } from './ws.js';
@@ -214,16 +215,28 @@ function formatCommentsOutput({ byFile, scopeLabel }) {
     }
     return lines.join('\n');
 }
+/** Hard cap on words returned per read_pad call. Above this, the response
+ *  is truncated at a top-level node boundary and a continuation hint is
+ *  appended pointing at peek_doc / outline_doc / search_docs. The cap exists
+ *  so the agent can't accidentally token-blow a 50k-word doc — read_pad's
+ *  contract is "doc opening + handle to continue," not "everything."
+ *  v0.25 — see CHANGELOG. */
+const READ_PAD_MAX_WORDS = 2000;
+/** First-truncation FYI shows once per MCP process lifetime so the agent
+ *  learns the new behavior without repeating the explanation. Resets on
+ *  server restart. */
+let firstTruncationShown = false;
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
-        description: 'Read a document by docId. Returns compact tagged-line format with [type:id] per node, inline markdown formatting. Much more token-efficient than JSON.',
+        description: `Read a document by docId. Returns compact tagged-line format with [type:id] per node. Capped at ~${READ_PAD_MAX_WORDS} words per call — for longer docs you get the opening slice plus a lastNodeId hint. Use peek_doc({ around: lastNodeId, after: N }) to continue linearly, outline_doc to jump by heading, or search_docs({ query, docId }) to find a specific passage. For docs under the cap, returns the full body as before.`,
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
         },
         handler: async ({ docId }) => {
             const target = resolveDocTarget(docId);
-            const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
+            const trunc = truncateRead(target.document, READ_PAD_MAX_WORDS);
+            const compact = toCompactFormat(trunc.doc, target.title, trunc.returnedWords, target.pendingCount, target.docId, target.metadata);
             const localCount = getCommentCount(target.filename);
             const { totalComments: otherCount, docCount: otherDocs } = getGlobalCommentSummary(target.filename);
             let hint = '';
@@ -233,6 +246,17 @@ export const TOOL_REGISTRY = [
                 hint += `\n[${otherCount} comment${otherCount !== 1 ? 's' : ''} on ${otherDocs} other document${otherDocs !== 1 ? 's' : ''}]`;
             if (hint)
                 hint += '\n[call get_comments to review]';
+            if (trunc.truncated) {
+                if (!firstTruncationShown) {
+                    hint += `\n\n[FYI: read_pad caps at ~${READ_PAD_MAX_WORDS} words to keep cost predictable. This notice shows once per session — future truncations skip the explanation.]`;
+                    firstTruncationShown = true;
+                }
+                const anchor = trunc.lastNodeId ?? '<no-id>';
+                hint += `\n[TRUNCATED — ${trunc.totalWords.toLocaleString()} words total, ${trunc.returnedWords.toLocaleString()} returned, ${trunc.remaining.toLocaleString()} remain. Continue with:`
+                    + `\n  peek_doc({ docId: "${target.docId}", target: { around: "${anchor}", after: 100 } })  — linear continuation`
+                    + `\n  outline_doc({ docId: "${target.docId}" })  — heading skeleton to jump to a section`
+                    + `\n  search_docs({ query: "...", docId: "${target.docId}" })  — find a specific passage]`;
+            }
             return { content: [{ type: 'text', text: compact + hint }] };
         },
     },
@@ -348,9 +372,46 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
         },
     },
+    {
+        name: 'outline_doc',
+        description: 'Get the structural skeleton of a doc — heading tree by default, optionally drill into one section. The right tool to orient on a long doc before reading anything. Heading tree only is ~5 tokens per heading vs read_pad\'s ~50–100 per block. For 1000-node docs the entire outline is typically <500 tokens. Drill into a section with `underHeading: nodeId` to see one section\'s block previews (~15 tokens/block). Falls back to top-level block previews when the doc has no headings. Use after `search_docs` finds the doc but before `read_pad` or `peek_doc`.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex).'),
+            underHeading: z.string().optional().describe('Heading nodeId — drill into that section and return all blocks beneath it (until the next same-or-shallower heading).'),
+            depth: z.number().optional().describe('Cap on heading levels shown (1 = h1 only, 2 = h1+h2, etc.). Default 3. Ignored when underHeading is set.'),
+            offset: z.number().optional().describe('Pagination start index (default 0). Useful for very long unstructured docs.'),
+            limit: z.number().optional().describe('Pagination max lines (default 200).'),
+        },
+        handler: async ({ docId, underHeading, depth, offset, limit }) => {
+            const target = resolveDocTarget(docId);
+            const text = outline(target.document, { underHeading, depth, offset, limit });
+            return { content: [{ type: 'text', text }] };
+        },
+    },
+    {
+        name: 'peek_doc',
+        description: 'Read a windowed slice of nodes from a doc — once you have a nodeId from search_docs or outline_doc. Six target shapes: { node } single block, { nodes } array of explicit IDs, { around, before, after } window around an anchor, { from, to } range between two anchors, { first } top N blocks, { last } bottom N blocks, { position, span } positional read (position 0.0–1.0). All return compact tagged-line format. Use this instead of read_pad whenever you only need part of a doc.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex).'),
+            target: z.union([
+                z.object({ node: z.string() }).strict(),
+                z.object({ nodes: z.array(z.string()) }).strict(),
+                z.object({ around: z.string(), before: z.number().optional(), after: z.number().optional() }).strict(),
+                z.object({ from: z.string(), to: z.string() }).strict(),
+                z.object({ first: z.number() }).strict(),
+                z.object({ last: z.number() }).strict(),
+                z.object({ position: z.number(), span: z.number().optional() }).strict(),
+            ]).describe('Target spec — exactly one shape. See description for the six options.'),
+        },
+        handler: async ({ docId, target }) => {
+            const docTarget = resolveDocTarget(docId);
+            const nodes = peek(docTarget.document, target);
+            return { content: [{ type: 'text', text: compactNodes(nodes) }] };
+        },
+    },
     {
         name: 'get_nodes',
-        description: 'Get specific nodes by ID. Returns compact tagged-line format per node.',
+        description: 'DEPRECATED — superseded by peek_doc. Use peek_doc with target { nodes: [ids] } for the same behavior, or one of the other target shapes for richer windowed reads. This alias may be removed in a future release.',
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             nodeIds: z.array(z.string()).describe('Array of node IDs to retrieve'),
@@ -384,7 +445,7 @@ export const TOOL_REGISTRY = [
                     return `${main}\n      → ${d.logline}`;
                 return main;
             });
-            const footer = enrichmentFooter();
+            const footer = `${enrichmentFooter()}${sortFooter()}`;
             return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
@@ -501,7 +562,7 @@ export const TOOL_REGISTRY = [
                 // this entry. Fires after the file exists, so documents-changed arrives with
                 // the real entry that the sidebar filters behind the spinner until populate.
                 spinnerKey = result.filename;
-                broadcastWritingStarted(title || 'Untitled', wsTarget, spinnerKey);
+                broadcastWritingStarted(title || 'Untitled', wsTarget, spinnerKey, result.filename, result.docId);
                 broadcastDocumentsChanged();
                 return {
                     content: [{
@@ -654,7 +715,7 @@ export const TOOL_REGISTRY = [
                         const afterRef = w.afterId ? (filenameByDocId(w.afterId) ?? w.afterId) : null;
                         addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
                     }
-                    broadcastWritingStarted(w.title, wsTarget, result.filename);
+                    broadcastWritingStarted(w.title, wsTarget, result.filename, result.filename, result.docId);
                     broadcastedKeys.push(result.filename);
                     results.push({ docId: result.docId, filename: result.filename, title: result.title });
                 }
@@ -902,6 +963,7 @@ export const TOOL_REGISTRY = [
                         kind: 'enrichment',
                         headline: `Enrichment stamped ${target.title || target.filename}`,
                         detail: item.logline,
+                        docId: item.docId,
                         filename: target.filename,
                     });
                     results.push({ docId: item.docId, ok: true });
@@ -932,12 +994,84 @@ export const TOOL_REGISTRY = [
         },
     },
     {
-        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 (~60 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. v0.19.0 schema: status (canonical / draft) replaces docRole / domain / concepts filters — those legacy filters were dropped because the fields they queried had no authority discipline. See brief 2026-05-21-simplify-enrichment-schema-three-fields.',
+        name: 'list_pending_sorts',
+        description: 'List documents that the user has marked for sorting via the sidebar. Each entry includes the doc identity, where it currently lives, the requestedAt timestamp, and (when present) a proposal already written by an earlier pass. Call this first to know what sort work is pending; for each entry, read the doc body, consider workspace/container purpose hints, and either discuss the destination with the user in chat (1–3 docs) or write a proposal via propose_sort (many docs → batch UI accept/reject).',
+        schema: {
+            workspaceFile: z.string().optional().describe('Scope to one workspace. Omit to scan all workspaces.'),
+        },
+        handler: async ({ workspaceFile }) => {
+            const docs = listPendingSorts(workspaceFile);
+            return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
+        },
+    },
+    {
+        name: 'propose_sort',
+        description: 'Write a sort proposal back to a doc. Used in confirm-mode: the minion picks a destination (workspace + container) and a one-line reasoning, stamps it onto the doc\'s sortRequest, and the sidebar flips the doc\'s badge to "proposal ready" so the user can accept or reject in-browser. Does NOT move the doc — that happens on user accept (via the UI) or in auto-mode via mark_sorted+move_item. Accepts an array so a batch lands in one call.',
+        schema: {
+            proposals: z.array(z.object({
+                docId: z.string().describe('Target document by docId (8-char hex from list_pending_sorts).'),
+                wsFilename: z.string().describe('Destination workspace manifest filename.'),
+                containerId: z.string().nullable().describe('Destination container ID, or null for workspace root.'),
+                reasoning: z.string().max(200).describe('One-line rationale shown to the user beside the proposal. Under 200 chars.'),
+            }).strict()).describe('One or more proposals. Single-doc calls are a length-1 array.'),
+        },
+        handler: async ({ proposals }) => {
+            const results = [];
+            for (const p of proposals) {
+                try {
+                    const filename = resolveDocId(p.docId);
+                    setSortProposalOnFile(filename, { wsFilename: p.wsFilename, containerId: p.containerId, reasoning: p.reasoning });
+                    results.push({ docId: p.docId, ok: true });
+                }
+                catch (err) {
+                    results.push({ docId: p.docId, ok: false, error: String(err?.message ?? err) });
+                }
+            }
+            broadcastDocumentsChanged();
+            const okCount = results.filter((r) => r.ok).length;
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Wrote ${okCount} proposal${okCount === 1 ? '' : 's'}`
+                : `Wrote ${okCount} proposal${okCount === 1 ? '' : 's'}, ${failCount} failed`;
+            return { content: [{ type: 'text', text: `${summary}\n${JSON.stringify({ proposals: results })}` }] };
+        },
+    },
+    {
+        name: 'mark_sorted',
+        description: 'Clear a doc\'s sortRequest and stamp lastSortedAt. Used in auto-mode after the minion has actually called move_item (or decided the doc is already in the right place), and in confirm-mode after the user has accepted/rejected via the UI. Accepts an array for batch fulfillment. Does NOT perform the move — call move_item first. The retire-on-fulfillment pattern mirrors mark_enriched / enrichmentStale.',
+        schema: {
+            docs: z.array(z.object({
+                docId: z.string().describe('Target document by docId.'),
+            }).strict()).describe('One or more docs to mark sorted.'),
+        },
+        handler: async ({ docs }) => {
+            const results = [];
+            for (const item of docs) {
+                try {
+                    const filename = resolveDocId(item.docId);
+                    clearSortRequestOnFile(filename);
+                    results.push({ docId: item.docId, ok: true });
+                }
+                catch (err) {
+                    results.push({ docId: item.docId, ok: false, error: String(err?.message ?? err) });
+                }
+            }
+            broadcastDocumentsChanged();
+            const okCount = results.filter((r) => r.ok).length;
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Marked ${okCount} sorted`
+                : `Marked ${okCount} sorted, ${failCount} failed`;
+            return { content: [{ type: 'text', text: `${summary}\n${JSON.stringify({ docs: results })}` }] };
+        },
+    },
+    {
+        name: 'browse_docs',
+        description: 'Browse the workspace shelf at concept level — bulk-read enriched frontmatter per doc, filtered by criteria. Returns identity + logline + status + tags + stale flag (~60 tokens/doc). No bodies, no nodes, no pending overlay, no container nesting. Filters compose with AND semantics; empty filter returns every non-archived doc. Use this between get_workspace_structure (tree shape) and read_pad (full body) — see which docs look relevant before paying to read one.',
         schema: {
             workspaceFile: z.string().optional().describe('Scope to one workspace.'),
             tags: z.array(z.string()).optional().describe('Docs must have ALL listed tags.'),
-            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle filter. "canonical" returns the trusted-shelf docs (load-bearing for the workspace); "draft" returns working / superseded / scratch docs. The common crawl is `status: canonical`.'),
+            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle filter. "canonical" returns the trusted-shelf docs (load-bearing for the workspace); "draft" returns working / superseded / scratch docs. The common browse is `status: canonical`.'),
             hasLogline: z.boolean().optional().describe('True = only docs with a logline; false = only docs without one.'),
         },
         handler: async (filter) => {
@@ -945,6 +1079,20 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
         },
     },
+    {
+        name: 'crawl',
+        description: 'DEPRECATED — renamed to browse_docs. Use browse_docs instead. This alias may be removed in a future release.',
+        schema: {
+            workspaceFile: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            status: z.enum(['canonical', 'draft']).optional(),
+            hasLogline: z.boolean().optional(),
+        },
+        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.',
@@ -952,7 +1100,7 @@ export const TOOL_REGISTRY = [
         handler: async () => {
             const workspaces = listWorkspaces();
             const lines = workspaces.map((w) => `  ${w.filename} — "${w.title}" — ${w.docCount} docs`);
-            const footer = enrichmentFooter();
+            const footer = `${enrichmentFooter()}${sortFooter()}`;
             return { content: [{ type: 'text', text: `workspaces:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
@@ -988,46 +1136,20 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_workspace_structure',
-        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, status, tags, 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. v0.19.0: enrichment fields shown per-doc are logline (LLM-owned), status (agent-owned: canonical / draft), tags, and the STALE marker (system-owned).',
+        description: 'Get the tree shape of a workspace: containers and docs with their IDs/filenames, plus workspace-level structural fields (schema, vocab, enrichment flag). NO per-doc loglines, status, tags, or stale flags — those are concept-level and live in `browse`. Use this when you need to find a destination container (sort, move) or understand nesting. For "what is each doc about" call `browse` instead.',
         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 e = enrichByFile.get(node.file);
-                        const tags = e?.tags ?? [];
-                        const enrichBits = [];
-                        // v0.19.0: status (agent-owned) replaces domain + docRole.
-                        // Only "canonical" is worth surfacing — draft is the default
-                        // and would add noise on every line.
-                        if (e?.status === 'canonical')
-                            enrichBits.push('canonical');
-                        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}`);
+                        lines.push(`${indent}${getDocTitle(node.file)}  (${node.file})`);
                     }
                     else {
-                        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(`${indent}[container] ${node.name}  (id:${node.id})`);
                         lines.push(...renderTree(node.items, indent + '  '));
                     }
                 }
@@ -1035,25 +1157,18 @@ export const TOOL_REGISTRY = [
             }
             const treeLines = renderTree(ws.root, '  ');
             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)}`;
             }
-            const footer = enrichmentFooter();
+            const footer = `${enrichmentFooter()}${sortFooter()}`;
             return { content: [{ type: 'text', text: `${text}${footer}` }] };
         },
     },
@@ -1785,6 +1900,7 @@ export const TOOL_REGISTRY = [
                 broadcastActivityEvent({
                     kind: 'backlinks-added',
                     headline: `Linked ${sourceTitle} → ${targetTitle}`,
+                    docId: source_doc_id,
                     filename: sourceFilename,
                 });
             }
@@ -1823,18 +1939,26 @@ export const TOOL_REGISTRY = [
     },
     {
         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.',
+        description: 'Full-text search. Default (no docId): ranked candidates across every workspace doc, returning docId + title + match type + snippet. Scoped (docId set): search inside one doc and return matching NODES with nodeId + type + snippet — the content-to-node bridge that lets the agent jump from "I want the beat about X" to a known nodeId without ever reading the full doc. Pairs with peek_doc for the actual node read. Use the workspace search before link_to. Use the doc-scoped search before peek_doc when researching inside a long doc.',
         schema: {
-            query: z.string().describe('Search query (case-insensitive substring match against title, tags, then content).'),
+            query: z.string().describe('Search query (case-insensitive substring match).'),
+            docId: z.string().optional().describe('When set, scope the search to one doc and return matching nodes (with nodeId) instead of doc snippets. The content-orientation entry point for in-doc research.'),
             limit: z.number().optional().describe('Max results to return (default 10, max 50).'),
         },
-        handler: async ({ query, limit = 10 }) => {
+        handler: async ({ query, docId, limit = 10 }) => {
             const cap = Math.min(Math.max(limit, 1), 50);
+            // Doc-scoped path: walk the doc's blocks and return matching nodes.
+            if (docId) {
+                const target = resolveDocTarget(docId);
+                const matches = searchInDoc(target.document, query, cap);
+                return { content: [{ type: 'text', text: JSON.stringify({ docId, total: matches.length, matches }) }] };
+            }
+            // Workspace-wide path: existing behavior.
             const raw = searchDocuments(query);
             // 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 resolvedDocId = null;
                 let logline;
                 let status;
                 let tags;
@@ -1842,7 +1966,7 @@ export const TOOL_REGISTRY = [
                     const filePath = resolveDocPath(r.filename);
                     const fileRaw = readFileSync(filePath, 'utf-8');
                     const fm = matter(fileRaw);
-                    docId = fm.data?.docId || null;
+                    resolvedDocId = fm.data?.docId || null;
                     // v0.19.0 three-field schema: logline (LLM), status (agent), tags.
                     if (typeof fm.data?.logline === 'string')
                         logline = fm.data.logline;
@@ -1853,7 +1977,7 @@ export const TOOL_REGISTRY = [
                 }
                 catch { /* fields stay undefined */ }
                 return {
-                    docId,
+                    docId: resolvedDocId,
                     title: r.title,
                     filename: r.filename,
                     matchType: r.matchType,
@@ -1984,10 +2108,15 @@ export async function startMcpServer() {
     // agent's system context. Empty string when no enrichment work is pending.
     // See brief 2026-05-18-frontmatter-enrichment-system.
     const enrichmentNotice = buildEnrichmentInstructions();
+    const sortNotice = buildSortInstructions();
+    // Stack notices in the MCP instructions field. Both notices stand on their
+    // own — agents can read and dispatch them independently. Empty when neither
+    // system has pending work.
+    const combinedNotice = [enrichmentNotice, sortNotice].filter(Boolean).join('\n');
     const server = new McpServer({
         name: 'openwriter',
         version: '0.2.0',
-    }, enrichmentNotice ? { instructions: enrichmentNotice } : undefined);
+    }, combinedNotice ? { instructions: combinedNotice } : 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")'.