openwriter 0.15.0 → 0.16.0

package/dist/server/install-skill.js

@@ -136,6 +136,21 @@ export function installSkill() {
         }
         log(`  ✓ Skill docs copied to ${docsTarget}`);
     }
+    // Install custom Claude Code subagents to ~/.claude/agents/. These have
+    // allowlist-restricted tools so the main agent can dispatch them without
+    // loading the full MCP tool registry into the subagent's context
+    // (~50K tokens of overhead avoided per spawn).
+    const agentsSource = path.join(__dirname, '../../skill/agents');
+    if (fs.existsSync(agentsSource)) {
+        const agentsTarget = path.join(os.homedir(), '.claude', 'agents');
+        fs.mkdirSync(agentsTarget, { recursive: true });
+        for (const file of fs.readdirSync(agentsSource)) {
+            if (!file.endsWith('.md'))
+                continue;
+            fs.copyFileSync(path.join(agentsSource, file), path.join(agentsTarget, file));
+            log(`  ✓ Subagent installed: ${file}`);
+        }
+    }
     // Step 2: Global install or update
     let useNpx = false;
     const currentVersion = getGlobalVersion();

package/dist/server/markdown-parse.js

@@ -21,6 +21,7 @@ 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';
+import { enrichEntries, enrichSlimArray, fingerprintAll, isLegacyRawEntry, anyLegacyRaw, } from './node-fingerprint.js';
 // ============================================================================
 // Markdown -> TipTap
 // ============================================================================
@@ -122,14 +123,15 @@ export function markdownToTiptap(markdown) {
         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.
+    // Resolve identity graph from frontmatter. Two on-disk formats live in the
+    // wild: ultra-lean slim tuples (current) and legacy verbose objects (v0.14
+    // and v0.15). Legacy entries get positionally re-fingerprinted from the
+    // freshly-parsed body — the body IS the previous state at load time, and
+    // re-fingerprinting produces hashes the matcher can pin against cleanly.
+    // adr: adr/node-identity-matcher.md
+    const blocksForEnrich = tiptapToBlocks(doc);
+    const previousNodes = resolvePreviousNodes(data.nodes, blocksForEnrich);
+    const graveyard = resolveGraveyard(data.graveyard);
     if (previousNodes.length > 0) {
         applyMatcher(doc, previousNodes, graveyard);
     }
@@ -151,13 +153,68 @@ export function markdownToTiptap(markdown) {
         previousNodes,
     };
 }
-/** Defensive parse of frontmatter node entries — drops any malformed rows. */
-function normalizeNodeEntries(raw) {
-    if (!Array.isArray(raw))
+/**
+ * Resolve `nodes:` frontmatter into rich NodeEntry[] suitable for the matcher.
+ *
+ * Two on-disk formats:
+ *   - Ultra-lean: each entry is an array tuple. enrichSlimArray derives all
+ *     positional/structural fields from the slim array itself — no body parse
+ *     needed. The slim array IS the previous state (position = array index,
+ *     parent = most-recent unfilled container, neighbors = slim[i±1]).
+ *   - Legacy (v0.14/v0.15): each entry is an object with `id` and `fp` keys.
+ *     We re-fingerprint positionally from the body — the body IS the previous
+ *     state at load time, and a fresh fingerprint over the same body produces
+ *     hashes the matcher can pin against. After the next save, disk is in the
+ *     ultra-lean format and the body-parse cost drops away.
+ *
+ * `blocks` is only consulted for the legacy path; slim path ignores it. Pass
+ * an empty array when you only have slim input to avoid the body parse cost.
+ */
+export function resolvePreviousNodes(raw, blocks) {
+    if (!Array.isArray(raw) || raw.length === 0)
         return [];
-    return raw
-        .filter((entry) => entry && typeof entry === 'object' && entry.id && entry.fp)
-        .map((entry) => ({ id: String(entry.id), fingerprint: entry.fp }));
+    if (anyLegacyRaw(raw)) {
+        // Positional re-fingerprint: take each legacy entry's id, assign it to a
+        // freshly-computed fingerprint at the same position in the body.
+        const freshFps = fingerprintAll(blocks);
+        const out = [];
+        for (let i = 0; i < raw.length; i++) {
+            const r = raw[i];
+            const id = isLegacyRawEntry(r) ? r.id : (Array.isArray(r) ? r[0] : null);
+            if (!id || typeof id !== 'string' || !freshFps[i])
+                continue;
+            out.push({ id, fingerprint: freshFps[i] });
+        }
+        return out;
+    }
+    // Ultra-lean: walk the slim array directly. No body parse required.
+    return enrichSlimArray(raw).map((e) => ({
+        id: e.id,
+        fingerprint: e.fingerprint,
+    }));
+}
+/**
+ * Resolve `graveyard:` frontmatter into rich NodeEntry[].
+ *
+ * Ultra-lean tuples enrich without block context (deleted blocks have no
+ * body). Derived fields default to safe values; matcher rules for graveyard
+ * restore only consult type + sentences + structureSig + childTypes, all
+ * carried in slim. Legacy graveyard entries are dropped — their stored
+ * fingerprints don't translate to the new hash semantics (terminator is now
+ * folded into the hash), so they'd never match a fresh paste-back anyway.
+ */
+export function resolveGraveyard(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return [];
+    if (anyLegacyRaw(raw)) {
+        // Mixed input: drop legacy entries, enrich slim ones.
+        const slimOnly = raw.filter((r) => Array.isArray(r));
+        return enrichEntries(slimOnly, []).map((e) => ({ id: e.id, fingerprint: e.fingerprint }));
+    }
+    return enrichEntries(raw, []).map((e) => ({
+        id: e.id,
+        fingerprint: e.fingerprint,
+    }));
 }
 /**
  * Run the matcher: compare frontmatter `nodes` (previous fingerprints) to

package/dist/server/markdown-serialize.js

@@ -18,7 +18,7 @@
  */
 import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
 import { tiptapToBlocks } from './node-blocks.js';
-import { fingerprintAll } from './node-fingerprint.js';
+import { fingerprintAll, slimEntry } from './node-fingerprint.js';
 // ============================================================================
 // TipTap -> Markdown
 // ============================================================================
@@ -74,25 +74,23 @@ function collectPendingState(doc) {
     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.
+ * Build the `nodes` frontmatter entry — one slim tuple 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).
+ * Disk shape is the ultra-lean tuple form from node-fingerprint.ts. Derived
+ * fields (position, parent indices, neighbor types, char/word counts) are
+ * recomputed at load time from the block tree itself — they don't go to disk.
  */
 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 = [];
+    const out = [];
     for (let i = 0; i < blocks.length; i++) {
         const id = ids[i] || generateNodeId();
-        entries.push({ id, fp: fingerprints[i] });
+        out.push(slimEntry(id, fingerprints[i]));
     }
-    return entries;
+    return out;
 }
 /**
  * Cap graveyard size to avoid frontmatter bloat on docs with many edits.
@@ -156,12 +154,12 @@ export function tiptapToMarkdown(doc, title, metadata) {
     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.
+    // Graveyard: recently-orphaned entries kept across saves so paste-back/undo
+    // can restore the original ID via exact fingerprint match. Caller passes
+    // `{id, fingerprint}` objects (matcher output); we cap, slim, and emit.
     if (Array.isArray(meta.graveyard) && meta.graveyard.length > 0) {
-        meta.graveyard = meta.graveyard.slice(0, GRAVEYARD_MAX);
+        const capped = meta.graveyard.slice(0, GRAVEYARD_MAX);
+        meta.graveyard = capped.map((g) => Array.isArray(g) ? g : slimEntry(g.id, g.fingerprint || g.fp));
     }
     else {
         delete meta.graveyard;

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';
@@ -332,7 +334,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_documents',
-        description: 'List all documents. Shows title, docId (8-char hex), word count, last modified date, and which document is active. Use the docId to target documents in other tools.',
+        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, domain, docRole) when present. Use the docId to target documents in other tools.',
         schema: {},
         handler: async () => {
             const docs = listDocuments();
@@ -340,9 +342,21 @@ export const TOOL_REGISTRY = [
                 const active = d.isActive ? ' (active)' : '';
                 const id = d.docId ? ` [${d.docId}]` : '';
                 const date = d.lastModified.split('T')[0];
-                return `  "${d.title}"${id}${active} — ${d.wordCount.toLocaleString()} words — ${date}`;
+                const enrichBits = [];
+                if (d.domain)
+                    enrichBits.push(d.domain);
+                if (d.docRole)
+                    enrichBits.push(d.docRole);
+                if (d.enrichmentStale === true)
+                    enrichBits.push('STALE');
+                const enrichTag = enrichBits.length > 0 ? ` (${enrichBits.join(', ')})` : '';
+                const main = `  "${d.title}"${id}${active}${enrichTag} — ${d.wordCount.toLocaleString()} words — ${date}`;
+                if (d.logline)
+                    return `${main}\n      → ${d.logline}`;
+                return main;
             });
-            return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}` }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
     {
@@ -749,6 +763,117 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: `Metadata updated (${parts.join('; ')})` }] };
         },
     },
+    {
+        name: 'mark_enriched',
+        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied enrichment fields, and clears enrichmentStale. The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. See brief 2026-05-18-frontmatter-enrichment-system.',
+        schema: {
+            docs: z.array(z.object({
+                docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+                logline: z.string().optional().describe('One-sentence "what this doc is about" — ≤150 chars recommended.'),
+                domain: z.string().optional().describe('Single domain classification from the workspace vocab.'),
+                concepts: z.array(z.string()).optional().describe('Named concepts the doc references.'),
+                docRole: z.string().optional().describe('Doc role: canonical / vignette / reference / draft / chapter / beat.'),
+                status: z.string().optional().describe('Doc status: draft / canonical / stale. Archive state is implied by archivedAt.'),
+            })).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array.'),
+        },
+        handler: async ({ docs }) => {
+            const now = new Date().toISOString();
+            const results = [];
+            let anyTitleSideEffect = false;
+            for (const item of docs) {
+                try {
+                    const target = resolveDocTarget(item.docId);
+                    // Harvest current sentence hashes + char count from canonical view.
+                    // Active doc: getCanonical() returns the no-overlay primary state.
+                    // Non-active: cloneWithPendingReverted on the cached/loaded document.
+                    const canonical = target.isActive
+                        ? getCanonical()
+                        : cloneWithPendingReverted(target.document);
+                    const blocks = tiptapToBlocks(canonical);
+                    const lastEnrichedSentences = harvestSentenceHashes(blocks);
+                    const lastEnrichedCharCount = harvestCharCount(blocks);
+                    // Build the atomic enrichment payload.
+                    const update = {
+                        lastEnrichedAt: now,
+                        lastEnrichedCharCount,
+                        lastEnrichedSentences,
+                        enrichmentStale: false,
+                    };
+                    if (item.logline !== undefined)
+                        update.logline = item.logline;
+                    if (item.domain !== undefined)
+                        update.domain = item.domain;
+                    if (item.concepts !== undefined)
+                        update.concepts = item.concepts;
+                    if (item.docRole !== undefined)
+                        update.docRole = item.docRole;
+                    if (item.status !== undefined)
+                        update.status = item.status;
+                    if (target.isActive) {
+                        // Active doc: setMetadata mutates state.metadata but doesn't bump
+                        // docVersion on its own — without an explicit bump, save() would
+                        // hit the no-op gate (docVersion === lastSavedDocVersion when
+                        // there's no body change). bumpDocVersion forces save() through.
+                        // writeToDisk's staleness check will see the just-stamped baseline
+                        // (volumeRatio=1, drift=0) and NOT flip the flag back to true.
+                        setMetadata(update);
+                        bumpDocVersion();
+                        save();
+                        broadcastMetadataChanged(getMetadata());
+                    }
+                    else {
+                        // Non-active: write directly to disk, bypassing flushDocToFile's
+                        // staleness check (which would otherwise see stale state for one
+                        // serialize cycle before the new baseline lands). Disk write +
+                        // cache invalidation mirrors set_metadata's non-active path.
+                        const newMeta = { ...target.metadata, ...update };
+                        const markdown = tiptapToMarkdown(target.document, target.title, newMeta);
+                        atomicWriteFileSync(target.filePath, markdown);
+                        invalidateDocCache(target.filePath);
+                    }
+                    results.push({ docId: item.docId, ok: true });
+                }
+                catch (err) {
+                    results.push({ docId: item.docId, ok: false, error: String(err?.message ?? err) });
+                }
+            }
+            // Single broadcast at the end so sidebar refreshes once for the whole batch.
+            broadcastDocumentsChanged();
+            const okCount = results.filter((r) => r.ok).length;
+            const failCount = results.length - okCount;
+            const summary = failCount === 0
+                ? `Enriched ${okCount} doc${okCount === 1 ? '' : 's'}`
+                : `Enriched ${okCount} doc${okCount === 1 ? '' : 's'}, ${failCount} failed`;
+            return { content: [{ type: 'text', text: `${summary}\n${JSON.stringify({ docs: results })}` }] };
+        },
+    },
+    {
+        name: 'list_dirty_docs',
+        description: 'List documents that need enrichment — never enriched (no lastEnrichedAt) or flagged stale by openwriter (drift/volume thresholds tripped). Returns identity + reason only; no enrichment fields, no bodies. The minion calls this first to know what to work on. Docs in opted-out workspaces (enrichmentDisabled: true) are excluded. See brief 2026-05-18-frontmatter-enrichment-system.',
+        schema: {
+            workspaceFile: z.string().optional().describe('Scope to one workspace. Omit to scan all workspaces.'),
+        },
+        handler: async ({ workspaceFile }) => {
+            const docs = listDirtyDocs(workspaceFile);
+            return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
+        },
+    },
+    {
+        name: 'crawl',
+        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~150 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay.',
+        schema: {
+            workspaceFile: z.string().optional().describe('Scope to one workspace.'),
+            domain: z.string().optional().describe('Exact domain match.'),
+            tags: z.array(z.string()).optional().describe('Docs must have ALL listed tags.'),
+            concepts: z.array(z.string()).optional().describe('Docs must reference ALL listed concepts.'),
+            docRole: z.string().optional().describe('Exact docRole match (canonical / vignette / reference / draft / chapter / beat).'),
+            hasLogline: z.boolean().optional().describe('True = only docs with a logline; false = only docs without one.'),
+        },
+        handler: async (filter) => {
+            const docs = crawlDocs(filter);
+            return { content: [{ type: 'text', text: JSON.stringify({ total: docs.length, docs }) }] };
+        },
+    },
     {
         name: 'list_workspaces',
         description: 'List all workspaces. Returns filename, title, and doc count.',
@@ -756,7 +881,8 @@ export const TOOL_REGISTRY = [
         handler: async () => {
             const workspaces = listWorkspaces();
             const lines = workspaces.map((w) => `  ${w.filename} — "${w.title}" — ${w.docCount} docs`);
-            return { content: [{ type: 'text', text: `workspaces:\n${lines.join('\n') || '  (none)'}` }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `workspaces:\n${lines.join('\n') || '  (none)'}${footer}` }] };
         },
     },
     {
@@ -791,57 +917,136 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_workspace_structure',
-        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc tags, plus context (characters, settings, rules). Use to understand workspace organization before writing.',
+        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, domain, tags, docRole, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies.',
         schema: {
             filename: z.string().describe('Workspace manifest filename (e.g. "my-novel-a1b2c3d4.json")'),
         },
         handler: async ({ filename }) => {
             const ws = getWorkspace(filename);
+            // Build a one-pass map of filename → frontmatter so we don't re-read each
+            // doc file per tree node. crawlDocs is cheap (one disk pass per workspace).
+            const enriched = crawlDocs({ workspaceFile: filename });
+            const enrichByFile = new Map(enriched.map((e) => [e.filename, e]));
             function renderTree(nodes, indent) {
                 const lines = [];
                 for (const node of nodes) {
                     if (node.type === 'doc') {
-                        const tags = getDocTagsByFilename(node.file);
-                        const tagStr = tags.length > 0 ? `  [${tags.join(', ')}]` : '';
-                        lines.push(`${indent}${getDocTitle(node.file)}  (${node.file})${tagStr}`);
+                        const e = enrichByFile.get(node.file);
+                        const tags = e?.tags ?? [];
+                        const enrichBits = [];
+                        if (e?.domain)
+                            enrichBits.push(e.domain);
+                        if (e?.docRole)
+                            enrichBits.push(e.docRole);
+                        if (tags.length > 0)
+                            enrichBits.push(`tags: ${tags.join(', ')}`);
+                        if (e?.enrichmentStale === true)
+                            enrichBits.push('STALE');
+                        const tagStr = enrichBits.length > 0 ? `  [${enrichBits.join(' | ')}]` : '';
+                        const docLine = `${indent}${getDocTitle(node.file)}  (${node.file})${tagStr}`;
+                        lines.push(docLine);
+                        if (e?.logline)
+                            lines.push(`${indent}    → ${e.logline}`);
                     }
                     else {
-                        lines.push(`${indent}[container] ${node.name}  (id:${node.id})`);
+                        const cBits = [];
+                        if (node.role)
+                            cBits.push(node.role);
+                        const cTag = cBits.length > 0 ? ` [${cBits.join(' | ')}]` : '';
+                        lines.push(`${indent}[container] ${node.name}  (id:${node.id})${cTag}`);
+                        if (node.logline)
+                            lines.push(`${indent}    → ${node.logline}`);
                         lines.push(...renderTree(node.items, indent + '  '));
                     }
                 }
                 return lines;
             }
             const treeLines = renderTree(ws.root, '  ');
-            let text = `workspace: "${ws.title}"\nstructure:\n${treeLines.join('\n') || '  (empty)'}`;
+            const headerBits = [`workspace: "${ws.title}"`];
+            if (ws.logline)
+                headerBits.push(`logline: ${ws.logline}`);
+            if (ws.domain)
+                headerBits.push(`domain: ${ws.domain}`);
+            if (ws.schema)
+                headerBits.push(`schema: ${ws.schema}`);
+            if (Array.isArray(ws.vocab) && ws.vocab.length > 0) {
+                headerBits.push(`vocab: ${ws.vocab.join(', ')}`);
+            }
+            if (Array.isArray(ws.relatedWorkspaces) && ws.relatedWorkspaces.length > 0) {
+                headerBits.push(`related: ${ws.relatedWorkspaces.join(', ')}`);
+            }
+            if (ws.enrichmentDisabled === true)
+                headerBits.push('enrichment: disabled');
+            let text = `${headerBits.join('\n')}\nstructure:\n${treeLines.join('\n') || '  (empty)'}`;
             if (ws.context && Object.keys(ws.context).length > 0) {
                 text += `\ncontext:\n${JSON.stringify(ws.context, null, 2)}`;
             }
-            return { content: [{ type: 'text', text }] };
+            const footer = enrichmentFooter();
+            return { content: [{ type: 'text', text: `${text}${footer}` }] };
         },
     },
     {
         name: 'get_item_context',
-        description: 'Get progressive disclosure context for a document in a workspace: workspace-level context (characters, settings, rules) and tags. Use before writing to understand context.',
+        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, domain, concepts, docRole, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary.',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             docId: z.string().describe('Document docId (8-char hex from list_documents)'),
         },
         handler: async ({ workspaceFile, docId }) => {
             const filename = resolveDocId(docId);
-            return { content: [{ type: 'text', text: JSON.stringify(getItemContext(workspaceFile, filename), null, 2) }] };
+            const base = getItemContext(workspaceFile, filename);
+            // Layer doc-level enrichment + workspace-level vocab/schema into the response.
+            // The agent's crawl pattern: get_item_context for one doc → see logline +
+            // domain + concepts. Decide whether the doc warrants a body read.
+            try {
+                const ws = getWorkspace(workspaceFile);
+                const enriched = crawlDocs({ workspaceFile });
+                const docEnrich = enriched.find((e) => e.filename === filename);
+                if (docEnrich) {
+                    if (docEnrich.logline)
+                        base.logline = docEnrich.logline;
+                    if (docEnrich.domain)
+                        base.domain = docEnrich.domain;
+                    if (docEnrich.concepts)
+                        base.concepts = docEnrich.concepts;
+                    if (docEnrich.docRole)
+                        base.docRole = docEnrich.docRole;
+                    if (docEnrich.status)
+                        base.status = docEnrich.status;
+                    if (docEnrich.enrichmentStale === true)
+                        base.enrichmentStale = true;
+                }
+                if (ws.schema)
+                    base.workspaceSchema = ws.schema;
+                if (Array.isArray(ws.vocab) && ws.vocab.length > 0)
+                    base.workspaceVocab = ws.vocab;
+                if (ws.logline)
+                    base.workspaceLogline = ws.logline;
+                if (ws.domain)
+                    base.workspaceDomain = ws.domain;
+            }
+            catch { /* best-effort enrichment overlay */ }
+            return { content: [{ type: 'text', text: JSON.stringify(base, null, 2) }] };
         },
     },
     {
         name: 'update_workspace_context',
-        description: 'Update a workspace\'s context section (characters, settings, rules). Merges with existing context — only provided keys are changed.',
+        description: 'Update workspace configuration. Accepts writing context (characters, settings, rules — merged into existing) plus enrichment fields (logline, domain, schema, vocab, relatedWorkspaces, enrichmentVolumeThreshold, enrichmentDriftThreshold, enrichmentDisabled — set on workspace top-level). Pass `null` to clear an enrichment field. Use this to opt a workspace out of enrichment (enrichmentDisabled: true), declare a closed vocab for domain classification, or set workspace-level loglines/schemas. One tool covers writing context + enrichment config.',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             context: z.object({
-                characters: z.record(z.string()).optional().describe('Character name → description'),
-                settings: z.record(z.string()).optional().describe('Setting name → description'),
-                rules: z.array(z.string()).optional().describe('Writing rules for this workspace'),
-            }).describe('Context fields to merge'),
+                characters: z.record(z.string()).optional().describe('Character name → description (merged)'),
+                settings: z.record(z.string()).optional().describe('Setting name → description (merged)'),
+                rules: z.array(z.string()).optional().describe('Writing rules for this workspace (replaces)'),
+                logline: z.string().nullable().optional().describe('One-sentence "what this workspace is for". Set null to clear.'),
+                domain: z.string().nullable().optional().describe('Subject area (e.g. "Male ethology"). Set null to clear.'),
+                schema: z.string().nullable().optional().describe('Workspace kind: book / concept-library / inbox / social / reference. Set null to clear.'),
+                vocab: z.array(z.string()).nullable().optional().describe('Closed list of valid domain names — Haiku classifies docs INTO these. Set null to clear (opens vocab to free-form).'),
+                relatedWorkspaces: z.array(z.string()).nullable().optional().describe('Sibling workspace filenames. Set null to clear.'),
+                enrichmentVolumeThreshold: z.number().nullable().optional().describe('Volume-ratio threshold (default 1.5). Set null to revert.'),
+                enrichmentDriftThreshold: z.number().nullable().optional().describe('Jaccard-drift threshold (default 0.3). Set null to revert.'),
+                enrichmentDisabled: z.boolean().nullable().optional().describe('True = opt this workspace out of enrichment surfacing. Set null or false to re-enable.'),
+            }).describe('Writing context + enrichment config to apply'),
         },
         handler: async ({ workspaceFile, context }) => {
             updateWorkspaceContext(workspaceFile, context);
@@ -1551,16 +1756,29 @@ export const TOOL_REGISTRY = [
         handler: async ({ query, limit = 10 }) => {
             const cap = Math.min(Math.max(limit, 1), 50);
             const raw = searchDocuments(query);
-            // Enrich with docId by reading each result's frontmatter
+            // Enrich with docId + enrichment fields from frontmatter so the agent
+            // can rank/pick candidates without a follow-up body read.
             const enriched = raw.slice(0, cap).map((r) => {
                 let docId = null;
+                let logline;
+                let domain;
+                let docRole;
+                let tags;
                 try {
                     const filePath = resolveDocPath(r.filename);
                     const fileRaw = readFileSync(filePath, 'utf-8');
                     const fm = matter(fileRaw);
                     docId = fm.data?.docId || null;
+                    if (typeof fm.data?.logline === 'string')
+                        logline = fm.data.logline;
+                    if (typeof fm.data?.domain === 'string')
+                        domain = fm.data.domain;
+                    if (typeof fm.data?.docRole === 'string')
+                        docRole = fm.data.docRole;
+                    if (Array.isArray(fm.data?.tags) && fm.data.tags.length > 0)
+                        tags = fm.data.tags;
                 }
-                catch { /* docId stays null */ }
+                catch { /* fields stay undefined */ }
                 return {
                     docId,
                     title: r.title,
@@ -1568,6 +1786,10 @@ export const TOOL_REGISTRY = [
                     matchType: r.matchType,
                     snippet: r.snippet,
                     matchedTag: r.matchedTag,
+                    ...(logline ? { logline } : {}),
+                    ...(domain ? { domain } : {}),
+                    ...(docRole ? { docRole } : {}),
+                    ...(tags ? { tags } : {}),
                 };
             });
             return { content: [{ type: 'text', text: JSON.stringify(enriched) }] };
@@ -1695,10 +1917,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")'.