openwriter 0.15.0 → 0.17.0

package/dist/server/mcp.js

@@ -10,8 +10,10 @@ 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, getDocTagsByFilename, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, } 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 { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
@@ -114,6 +116,35 @@ function resolveDocTarget(docId) {
         lastModified: statSync(filePath).mtime,
     };
 }
+/**
+ * Override the `autoAccept` field in a snapshot's frontmatter without
+ * reparsing the body. Used by `restore_version` to preserve the CURRENT
+ * user toggle (a per-doc UI preference) across a content-restore. Editing
+ * the frontmatter line directly avoids a full parse + reserialize, which
+ * would re-run the matcher and risk minor body-shape drift for what's
+ * supposed to be an exact content restore.
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+function applyAutoAcceptOverride(snapshotMarkdown, currentAutoAccept) {
+    const fmMatch = snapshotMarkdown.match(/^---\n(.+?)\n---\n/s);
+    if (!fmMatch)
+        return snapshotMarkdown; // no frontmatter to update
+    try {
+        const fm = JSON.parse(fmMatch[1]);
+        if (currentAutoAccept) {
+            fm.autoAccept = true;
+        }
+        else {
+            delete fm.autoAccept;
+        }
+        const newFmLine = JSON.stringify(fm);
+        return snapshotMarkdown.replace(/^---\n.+?\n---\n/s, `---\n${newFmLine}\n---\n`);
+    }
+    catch {
+        return snapshotMarkdown; // malformed frontmatter — leave alone
+    }
+}
 /** Human-friendly relative time for ISO timestamps. */
 function relativeTime(iso) {
     const then = new Date(iso).getTime();
@@ -332,7 +363,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();
@@ -340,9 +371,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}` }] };
         },
     },
     {
@@ -749,6 +792,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('Précis (non-fiction) or logline (fiction). Under 250 chars. Describe the content, not the kind of doc.'),
+                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.',
@@ -756,7 +910,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}` }] };
         },
     },
     {
@@ -791,57 +946,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);
@@ -1250,9 +1484,19 @@ export const TOOL_REGISTRY = [
             }
             catch { /* best effort */ }
             // Read the target snapshot's content
-            const snapshotMarkdown = getVersionContent(target.docId, timestamp);
-            if (!snapshotMarkdown)
+            const rawSnapshot = getVersionContent(target.docId, timestamp);
+            if (!rawSnapshot)
                 return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
+            // Preserve the CURRENT autoAccept setting rather than rolling it back
+            // to the snapshot-era value. `autoAccept` is a per-doc user preference
+            // (toggled in the sidebar) that governs how FUTURE writes behave —
+            // it's not document content. Without this, a user who toggled
+            // autoAccept off to review incoming changes would silently lose that
+            // preference when the agent calls restore_version, and the next
+            // write_to_pad would auto-apply instead of arriving as pending.
+            // adr: adr/pending-overlay-model.md
+            const currentAutoAccept = target.metadata?.autoAccept === true;
+            const snapshotMarkdown = applyAutoAcceptOverride(rawSnapshot, currentAutoAccept);
             // 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.
@@ -1551,16 +1795,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,
@@ -1568,6 +1825,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) }] };
@@ -1695,10 +1956,15 @@ 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")'.

package/dist/server/node-blocks.js

@@ -36,6 +36,8 @@ const CONTAINER_TYPES = new Set([
     'tableRow',
     'tableCell',
     'tableHeader',
+    'footnoteSection',
+    'footnoteDefinition',
 ]);
 function walkNodes(nodes, blocks, parentPosition) {
     let ordinalInParent = 0;
@@ -105,6 +107,40 @@ function walkNodes(nodes, blocks, parentPosition) {
             });
             walkNodes(node.content || [], blocks, bqPosition);
         }
+        else if (node.type === 'footnoteSection') {
+            // Container holding all `footnoteDefinition`s at end-of-doc. Treated
+            // like a blockquote: container fingerprint is content-empty, identity
+            // travels through the matcher's structural rules. The serializer
+            // enforces end-of-doc position regardless of where it appears in the
+            // tree, so position-stability is guaranteed at the boundary.
+            // adr: adr/footnote-system.md
+            const sectionPosition = blocks.length;
+            blocks.push({
+                position: sectionPosition,
+                type: 'footnoteSection',
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, sectionPosition);
+        }
+        else if (node.type === 'footnoteDefinition') {
+            // Container for one footnote's content (typically a single paragraph,
+            // occasionally multiple). The label attr round-trips with the node;
+            // the matcher fingerprints by content + slot like any container.
+            // adr: adr/footnote-system.md
+            const defPosition = blocks.length;
+            blocks.push({
+                position: defPosition,
+                type: 'footnoteDefinition',
+                text: firstParagraphText(node.content || []),
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, defPosition);
+        }
         else if (node.type === 'codeBlock') {
             const text = extractInlineText(node.content || []);
             blocks.push({
@@ -236,6 +272,8 @@ export function applyIdsToTiptap(doc, pinnedByPosition) {
                 node.type === 'horizontalRule' ||
                 node.type === 'table' ||
                 node.type === 'image' ||
+                node.type === 'footnoteSection' ||
+                node.type === 'footnoteDefinition' ||
                 CONTAINER_TYPES.has(node.type);
             if (isBlock) {
                 const id = pinnedByPosition.get(position);
@@ -261,7 +299,9 @@ export function applyIdsToTiptap(doc, pinnedByPosition) {
                     node.type === 'taskList' ||
                     node.type === 'listItem' ||
                     node.type === 'taskItem' ||
-                    node.type === 'blockquote';
+                    node.type === 'blockquote' ||
+                    node.type === 'footnoteSection' ||
+                    node.type === 'footnoteDefinition';
                 if (isContainer && node.content)
                     walk(node.content);
             }