openwriter 0.15.0 → 0.16.0

package/dist/plugins/x-api/dist/index.js

@@ -0,0 +1,240 @@
+/**
+ * X API plugin for OpenWriter.
+ * Registers routes for checking X connection status and posting tweets.
+ * Uses @xdevplatform/xdk with OAuth1 credentials from plugin config.
+ */
+import { Client, OAuth1 } from '@xdevplatform/xdk';
+import { join, extname } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import sharp from 'sharp';
+import twitter from 'twitter-text';
+const { parseTweet } = twitter;
+function createXClient(config) {
+    const apiKey = config['api-key'] || process.env.X_API_KEY || '';
+    const apiSecret = config['api-secret'] || process.env.X_API_SECRET || '';
+    const accessToken = config['access-token'] || process.env.X_ACCESS_TOKEN || '';
+    const accessTokenSecret = config['access-token-secret'] || process.env.X_ACCESS_TOKEN_SECRET || '';
+    if (!apiKey || !apiSecret || !accessToken || !accessTokenSecret)
+        return null;
+    const oauth1 = new OAuth1({
+        apiKey,
+        apiSecret,
+        callback: 'oob',
+        accessToken,
+        accessTokenSecret,
+    });
+    return new Client({ oauth1 });
+}
+const plugin = {
+    name: '@openwriter/plugin-x-api',
+    version: '0.1.0',
+    description: 'Post tweets from OpenWriter',
+    category: 'social-media',
+    configSchema: {
+        'api-key': { type: 'string', env: 'X_API_KEY', description: 'X API Key' },
+        'api-secret': { type: 'string', env: 'X_API_SECRET', description: 'X API Secret' },
+        'access-token': { type: 'string', env: 'X_ACCESS_TOKEN', description: 'X Access Token' },
+        'access-token-secret': { type: 'string', env: 'X_ACCESS_TOKEN_SECRET', description: 'X Access Token Secret' },
+    },
+    registerRoutes(ctx) {
+        // GET /api/x/status — check if plugin is configured + authenticated
+        ctx.app.get('/api/x/status', async (_req, res) => {
+            try {
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.json({ connected: false });
+                    return;
+                }
+                const me = await client.users.getMe();
+                const username = me?.data?.username;
+                res.json({ connected: true, username: username || undefined });
+            }
+            catch (err) {
+                console.error('[X Plugin] Status check failed:', err.message);
+                res.json({ connected: false, error: err.message });
+            }
+        });
+        // POST /api/x/post — post a tweet (with optional media)
+        ctx.app.post('/api/x/post', async (req, res) => {
+            try {
+                const { text, replyTo, quoteTweetId, mediaIds } = req.body;
+                if ((!text || typeof text !== 'string') && (!Array.isArray(mediaIds) || mediaIds.length === 0)) {
+                    res.status(400).json({ success: false, error: 'text or mediaIds is required' });
+                    return;
+                }
+                if (mediaIds && (!Array.isArray(mediaIds) || mediaIds.length > 4)) {
+                    res.status(400).json({ success: false, error: 'mediaIds must be an array of 1-4 IDs' });
+                    return;
+                }
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                const body = {};
+                if (text)
+                    body.text = text;
+                if (replyTo) {
+                    body.reply = { inReplyToTweetId: replyTo };
+                }
+                if (quoteTweetId) {
+                    body.quoteTweetId = quoteTweetId;
+                }
+                if (mediaIds && mediaIds.length > 0) {
+                    body.media = { media_ids: mediaIds };
+                }
+                const result = await client.posts.create(body);
+                const tweetId = result?.data?.id;
+                const tweetUrl = tweetId ? `https://x.com/i/status/${tweetId}` : undefined;
+                res.json({ success: true, tweetId, tweetUrl });
+            }
+            catch (err) {
+                const detail = err.data ? JSON.stringify(err.data) : err.message;
+                console.error('[X Plugin] Post failed:', detail);
+                res.status(500).json({ success: false, error: detail });
+            }
+        });
+        // POST /api/x/post-thread — post a full thread as a reply chain (with optional media per tweet)
+        ctx.app.post('/api/x/post-thread', async (req, res) => {
+            try {
+                const { tweets, replyTo } = req.body;
+                if (!Array.isArray(tweets) || tweets.length === 0) {
+                    res.status(400).json({ success: false, error: 'tweets must be a non-empty array' });
+                    return;
+                }
+                // Normalize: accept string[] or { text, mediaIds? }[]
+                const normalized = tweets.map((t) => typeof t === 'string' ? { text: t, mediaIds: undefined } : t);
+                // Validate character limits using X's weighted counting (emojis=2, URLs=23, CJK=2)
+                const CHAR_LIMIT = 25000;
+                const overLimit = normalized.map((t, i) => ({ i, len: parseTweet(t.text).weightedLength })).filter(x => x.len > CHAR_LIMIT);
+                if (overLimit.length > 0) {
+                    res.status(400).json({
+                        success: false,
+                        error: `${overLimit.length} tweet(s) exceed ${CHAR_LIMIT} chars: ${overLimit.map(x => `#${x.i + 1} (${x.len})`).join(', ')}`,
+                    });
+                    return;
+                }
+                // Validate mediaIds per tweet
+                for (let i = 0; i < normalized.length; i++) {
+                    const ids = normalized[i].mediaIds;
+                    if (ids && (!Array.isArray(ids) || ids.length > 4)) {
+                        res.status(400).json({ success: false, error: `Tweet ${i + 1}: mediaIds must be an array of 1-4 IDs` });
+                        return;
+                    }
+                }
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                const postedTweets = [];
+                let previousTweetId = replyTo;
+                for (let i = 0; i < normalized.length; i++) {
+                    const { text, mediaIds } = normalized[i];
+                    const body = {};
+                    if (text)
+                        body.text = text;
+                    if (previousTweetId) {
+                        body.reply = { inReplyToTweetId: previousTweetId };
+                    }
+                    if (mediaIds && mediaIds.length > 0) {
+                        body.media = { media_ids: mediaIds };
+                    }
+                    const result = await client.posts.create(body);
+                    const tweetId = result?.data?.id;
+                    if (!tweetId) {
+                        res.status(500).json({
+                            success: false,
+                            postedTweets,
+                            failedAt: i,
+                            error: `Tweet ${i + 1} posted but no ID returned`,
+                        });
+                        return;
+                    }
+                    postedTweets.push({ index: i, tweetId, text });
+                    previousTweetId = tweetId;
+                }
+                // Build thread URL from first tweet
+                const firstTweetId = postedTweets[0]?.tweetId;
+                const threadUrl = firstTweetId ? `https://x.com/i/status/${firstTweetId}` : undefined;
+                console.log(`[X Plugin] Thread posted: ${postedTweets.length} tweets, ${threadUrl}`);
+                res.json({ success: true, postedTweets, threadUrl });
+            }
+            catch (err) {
+                console.error('[X Plugin] Post thread failed:', err.message);
+                res.status(500).json({ success: false, error: err.message });
+            }
+        });
+        // POST /api/x/upload-media — upload a local /_images/ file for tweet attachment
+        ctx.app.post('/api/x/upload-media', async (req, res) => {
+            try {
+                const { src } = req.body;
+                if (!src || typeof src !== 'string') {
+                    res.status(400).json({ success: false, error: 'src is required' });
+                    return;
+                }
+                // Security: only allow /_images/ paths, no traversal
+                if (!/^\/_images\/[^/\\]+$/.test(src)) {
+                    res.status(400).json({ success: false, error: 'Invalid image path — must be /_images/<filename>' });
+                    return;
+                }
+                const filename = src.replace('/_images/', '');
+                const filePath = join(ctx.dataDir, '_images', filename);
+                if (!existsSync(filePath)) {
+                    res.status(404).json({ success: false, error: `Image not found: ${filename}` });
+                    return;
+                }
+                const ext = extname(filename).toLowerCase();
+                const mimeMap = {
+                    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                    '.png': 'image/png', '.webp': 'image/webp',
+                    '.gif': 'image/jpeg', '.bmp': 'image/bmp',
+                    '.tiff': 'image/tiff', '.tif': 'image/tiff',
+                };
+                const mediaType = mimeMap[ext] || 'image/jpeg';
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                let fileBuffer = readFileSync(filePath);
+                let uploadType = mediaType;
+                const origSize = fileBuffer.length;
+                // Compress large images or PNGs to JPEG to stay under X API limits
+                if (fileBuffer.length > 3 * 1024 * 1024 || ext === '.png') {
+                    fileBuffer = Buffer.from(await sharp(fileBuffer).jpeg({ quality: 85 }).toBuffer());
+                    uploadType = 'image/jpeg';
+                    console.log(`[X Plugin] Compressed ${filename}: ${(origSize / 1024 / 1024).toFixed(2)}MB → ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB`);
+                }
+                console.log(`[X Plugin] Uploading ${filename}: ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB, type: ${uploadType}`);
+                const mediaBase64 = fileBuffer.toString('base64');
+                const uploadResult = await client.media.upload({
+                    body: { media: mediaBase64, mediaCategory: 'tweet_image', mediaType: uploadType },
+                });
+                const mediaId = uploadResult?.data?.id
+                    || uploadResult?.media_id_string;
+                if (!mediaId) {
+                    res.status(500).json({ success: false, error: 'Upload succeeded but no media ID returned' });
+                    return;
+                }
+                console.log(`[X Plugin] Media uploaded: ${filename} → ${mediaId}`);
+                res.json({ success: true, mediaId });
+            }
+            catch (err) {
+                console.error('[X Plugin] Media upload failed:', err.message);
+                if (err.response) {
+                    try {
+                        const body = await err.response.text();
+                        console.error('[X Plugin] X API response:', err.response.status, body);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (err.data)
+                    console.error('[X Plugin] Error data:', JSON.stringify(err.data));
+                console.error('[X Plugin] Full error:', JSON.stringify(err, Object.getOwnPropertyNames(err)));
+                res.status(500).json({ success: false, error: err.message });
+            }
+        });
+    },
+};
+export default plugin;

package/dist/plugins/x-api/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@openwriter/plugin-x-api",
+  "version": "0.1.0",
+  "description": "Post tweets from OpenWriter",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@xdevplatform/xdk": "^0.4.0",
+    "twitter-text": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "typescript": "^5.6.0"
+  },
+  "openwriter": {
+    "displayName": "X / Twitter",
+    "category": "social-media"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ]
+}

package/dist/server/documents.js

@@ -12,9 +12,10 @@ import { parseMarkdownContent } from './compact.js';
 import { getDocument, getTitle, getFilePath, getIsTemp, getMetadata, save, cancelDebouncedSave, setActiveDocument, registerExternalDoc, unregisterExternalDoc, getExternalDocs, cacheActiveDocument, getCachedDocument, invalidateDocCache, removePendingCacheEntry, resetDocVersion, markAsAgentStub, unmarkAgentStub, isAgentStub, } from './state.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath } from './helpers.js';
 import { ensureDocId } from './versions.js';
-import { renameDocInAllWorkspaces, removeDocFromAllWorkspaces } from './workspaces.js';
+import { renameDocInAllWorkspaces, removeDocFromAllWorkspaces, listWorkspaces, getWorkspace } from './workspaces.js';
+import { collectAllFiles } from './workspace-tree.js';
 import { renameComments } from './comments.js';
-import { deleteOverlay } from './pending-overlay.js';
+import { deleteOverlay, diagLog } from './pending-overlay.js';
 import { getDocId as getActiveDocId } from './state.js';
 function getDocOrderFile() { return join(getDataDir(), '_doc-order.json'); }
 /** Scan files for matching docId. Checks active doc first (free), then getDataDir(), then external docs. */
@@ -124,6 +125,18 @@ export function listDocuments() {
                 ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
                 ...(data.variantType ? { variantType: data.variantType } : {}),
                 ...(typeof data.autoAccept === 'boolean' ? { autoAccept: data.autoAccept } : {}),
+                // Tags ride along with the doc listing so the sidebar can populate its
+                // tag overlay from one HTTP round-trip instead of N. The server already
+                // has the parsed frontmatter in hand here; emitting tags is free.
+                ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
+                // Enrichment fields — also free at this point since data is in hand.
+                // See brief 2026-05-18-frontmatter-enrichment-system.
+                ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
+                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
+                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
+                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
+                ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
+                ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
             };
         }
         catch {
@@ -238,6 +251,211 @@ export function listArchivedDocuments() {
     files.sort((a, b) => new Date(b.archivedAt).getTime() - new Date(a.archivedAt).getTime());
     return files;
 }
+// ============================================================================
+// ENRICHMENT — list dirty docs + crawl + surfacing helpers
+// See brief 2026-05-18-frontmatter-enrichment-system.
+// ============================================================================
+/** One-line footer the high-frequency MCP discovery tools (list_documents,
+ *  list_workspaces, get_workspace_structure) append when dirty docs exist.
+ *  Constant pressure that doesn't require hook setup. The agent's openwriter
+ *  skill teaches: see this footer → spawn the enrichment minion. */
+export function enrichmentFooter() {
+    const count = listDirtyDocs().length;
+    if (count === 0)
+        return '';
+    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} need enrichment — spawn the enrichment minion (see openwriter skill docs/enrichment.md)`;
+}
+/** Session-start enrichment notice injected into the MCP server's
+ *  `instructions` field at boot. Every MCP client (Claude Code, Cursor, etc.)
+ *  delivers this to the agent as part of its system context — no hook setup
+ *  needed. Returns empty string when there's no enrichment work to do. */
+export function buildEnrichmentInstructions() {
+    const dirty = listDirtyDocs();
+    if (dirty.length === 0)
+        return '';
+    // Group by workspace for the notice
+    const byWorkspace = new Map();
+    let orphans = 0;
+    for (const d of dirty) {
+        if (d.workspaceFile) {
+            byWorkspace.set(d.workspaceFile, (byWorkspace.get(d.workspaceFile) || 0) + 1);
+        }
+        else {
+            orphans++;
+        }
+    }
+    const parts = [];
+    for (const [ws, n] of byWorkspace)
+        parts.push(`${n} in ${ws}`);
+    if (orphans > 0)
+        parts.push(`${orphans} unfiled`);
+    return [
+        '',
+        `ENRICHMENT_STATUS: ${dirty.length} doc${dirty.length === 1 ? '' : 's'} need enrichment (${parts.join(', ')}).`,
+        'Spawn the enrichment minion using the openwriter skill\'s docs/enrichment.md as its system prompt before responding to the user\'s request.',
+        'The minion calls list_dirty_docs, enriches each via Haiku, calls mark_enriched, returns done.',
+    ].join('\n');
+}
+/** Build a Set of filenames inside workspaces with enrichmentDisabled: true.
+ *  These docs are excluded from list_dirty_docs and crawl results. */
+function collectOptedOutFilenames() {
+    const out = new Set();
+    for (const info of listWorkspaces()) {
+        try {
+            const ws = getWorkspace(info.filename);
+            if (ws.enrichmentDisabled === true) {
+                for (const f of collectAllFiles(ws.root))
+                    out.add(f);
+            }
+        }
+        catch { /* skip corrupt manifests */ }
+    }
+    return out;
+}
+/** Map filename → first workspace that contains it. Used to attribute
+ *  dirty-doc reports to a workspace. */
+function buildWorkspaceOwnershipMap() {
+    const map = new Map();
+    for (const info of listWorkspaces()) {
+        try {
+            const ws = getWorkspace(info.filename);
+            for (const f of collectAllFiles(ws.root)) {
+                if (!map.has(f))
+                    map.set(f, info.filename);
+            }
+        }
+        catch { /* skip */ }
+    }
+    return map;
+}
+/**
+ * List documents that need re-enrichment. A doc is "dirty" when either:
+ *   - it has never been enriched (no lastEnrichedAt) — implicitly stale; or
+ *   - openwriter flipped enrichmentStale: true at save (volume or drift trip).
+ *
+ * Docs inside opt-out workspaces (enrichmentDisabled: true) are excluded.
+ * Archived docs are excluded.
+ *
+ * Optional `scopeWorkspace` narrows results to a single workspace.
+ *
+ * Cheap: reads each .md file's frontmatter via gray-matter (no TipTap parse,
+ * no body scan). Output carries only identity + reason — no enrichment fields.
+ */
+export function listDirtyDocs(scopeWorkspace) {
+    ensureDataDir();
+    const optedOut = collectOptedOutFilenames();
+    const ownership = buildWorkspaceOwnershipMap();
+    // If a workspace scope is given, build a Set of its files to filter against.
+    let scopeFiles = null;
+    if (scopeWorkspace) {
+        try {
+            const ws = getWorkspace(scopeWorkspace);
+            scopeFiles = new Set(collectAllFiles(ws.root));
+        }
+        catch {
+            // Unknown workspace → return empty rather than throw
+            return [];
+        }
+    }
+    const out = [];
+    for (const f of readdirSync(getDataDir()).filter((f) => f.endsWith('.md'))) {
+        if (optedOut.has(f))
+            continue;
+        if (scopeFiles && !scopeFiles.has(f))
+            continue;
+        try {
+            const raw = readFileSync(join(getDataDir(), f), 'utf-8');
+            const { data } = matter(raw);
+            if (data.archivedAt)
+                continue; // archived docs don't participate
+            const explicitStale = data.enrichmentStale === true;
+            const implicitStale = !data.lastEnrichedAt;
+            if (!explicitStale && !implicitStale)
+                continue;
+            out.push({
+                docId: data.docId || '',
+                filename: f,
+                title: data.title || f.replace(/\.md$/, ''),
+                ...(ownership.get(f) ? { workspaceFile: ownership.get(f) } : {}),
+                reason: explicitStale ? 'stale_flag' : 'never_enriched',
+                ...(typeof data.lastEnrichedAt === 'string' ? { lastEnrichedAt: data.lastEnrichedAt } : {}),
+            });
+        }
+        catch { /* skip unreadable */ }
+    }
+    return out;
+}
+/**
+ * Bulk-read primitive for agents building working sets. Returns enriched
+ * fields per doc, filtered by criteria. No bodies, no nodes/graveyard, no
+ * pending overlay state.
+ *
+ * Filters compose with AND semantics — a doc must match every supplied
+ * criterion. Empty filter object returns every non-archived doc with its
+ * enrichment fields (whatever's present in frontmatter).
+ *
+ * Optimization: one disk pass, one gray-matter parse per file.
+ */
+export function crawlDocs(filter = {}) {
+    ensureDataDir();
+    // If a workspace scope is given, prebuild a set of its filenames.
+    let scopeFiles = null;
+    if (filter.workspaceFile) {
+        try {
+            const ws = getWorkspace(filter.workspaceFile);
+            scopeFiles = new Set(collectAllFiles(ws.root));
+        }
+        catch {
+            return [];
+        }
+    }
+    const out = [];
+    for (const f of readdirSync(getDataDir()).filter((f) => f.endsWith('.md'))) {
+        if (scopeFiles && !scopeFiles.has(f))
+            continue;
+        try {
+            const raw = readFileSync(join(getDataDir(), f), 'utf-8');
+            const { data, content } = matter(raw);
+            if (data.archivedAt)
+                continue;
+            // Apply filters
+            if (filter.domain && data.domain !== filter.domain)
+                continue;
+            if (filter.docRole && data.docRole !== filter.docRole)
+                continue;
+            if (filter.hasLogline === true && !data.logline)
+                continue;
+            if (filter.hasLogline === false && data.logline)
+                continue;
+            if (filter.tags && filter.tags.length > 0) {
+                const docTags = Array.isArray(data.tags) ? data.tags : [];
+                if (!filter.tags.every((t) => docTags.includes(t)))
+                    continue;
+            }
+            if (filter.concepts && filter.concepts.length > 0) {
+                const docConcepts = Array.isArray(data.concepts) ? data.concepts : [];
+                if (!filter.concepts.every((c) => docConcepts.includes(c)))
+                    continue;
+            }
+            const trimmed = content.trim();
+            out.push({
+                docId: data.docId || '',
+                filename: f,
+                title: data.title || f.replace(/\.md$/, ''),
+                wordCount: trimmed ? trimmed.split(/\s+/).length : 0,
+                ...(typeof data.logline === 'string' && data.logline ? { logline: data.logline } : {}),
+                ...(typeof data.domain === 'string' && data.domain ? { domain: data.domain } : {}),
+                ...(Array.isArray(data.tags) && data.tags.length > 0 ? { tags: data.tags } : {}),
+                ...(Array.isArray(data.concepts) && data.concepts.length > 0 ? { concepts: data.concepts } : {}),
+                ...(typeof data.docRole === 'string' && data.docRole ? { docRole: data.docRole } : {}),
+                ...(typeof data.status === 'string' && data.status ? { status: data.status } : {}),
+                ...(data.enrichmentStale === true ? { enrichmentStale: true } : {}),
+            });
+        }
+        catch { /* skip */ }
+    }
+    return out;
+}
 export function archiveDocument(filename) {
     ensureDataDir();
     const targetPath = resolveDocPath(filename);
@@ -381,15 +599,21 @@ export function searchDocuments(query, includeArchived = false) {
     return results;
 }
 export function switchDocument(filename) {
+    const tStart = performance.now();
+    const prevFilename = getActiveFilename();
     // No-op if already on this document — avoids save/reload cycle that can clear editor content
-    if (filename === getActiveFilename()) {
+    if (filename === prevFilename) {
+        diagLog(`[Switch] NOOP ${filename} (${(performance.now() - tStart).toFixed(1)}ms)`);
         return { document: getDocument(), title: getTitle(), filename };
     }
     // Cancel any pending debounced save, then save current doc immediately.
     cancelDebouncedSave();
+    const tSaveStart = performance.now();
     save();
+    const tSaveEnd = performance.now();
     // Cache current doc before switching (preserves node IDs)
     cacheActiveDocument();
+    const tCacheEnd = performance.now();
     // Reset version counter — new document starts a fresh version lineage
     resetDocVersion();
     // Read target from disk — markdownToTiptap rehydrates pending state
@@ -405,15 +629,22 @@ export function switchDocument(filename) {
     const cached = getCachedDocument(targetPath);
     if (cached) {
         setActiveDocument(cached.document, cached.title, targetPath, cached.isTemp, cached.lastModified, cached.metadata, cached.originalFrontmatter);
+        const tEnd = performance.now();
+        diagLog(`[Switch] ${prevFilename} → ${filename} CACHE-HIT total=${(tEnd - tStart).toFixed(1)}ms save=${(tSaveEnd - tSaveStart).toFixed(1)}ms cache=${(tCacheEnd - tSaveEnd).toFixed(1)}ms setActive=${(tEnd - tCacheEnd).toFixed(1)}ms`);
         return { document: getDocument(), title: getTitle(), filename };
     }
+    const tReadStart = performance.now();
     const raw = readFileSync(targetPath, 'utf-8');
+    const tReadEnd = performance.now();
     const parsed = markdownToTiptap(raw);
+    const tParseEnd = performance.now();
     const mtime = new Date(statSync(targetPath).mtimeMs);
     // Ensure docId exists on loaded doc metadata (lazy migration)
     ensureDocId(parsed.metadata);
     const baseName = targetPath.split(/[/\\]/).pop() || '';
     setActiveDocument(parsed.document, parsed.title, targetPath, baseName.startsWith(TEMP_PREFIX), mtime, parsed.metadata, parsed.rawFrontmatter);
+    const tEnd = performance.now();
+    diagLog(`[Switch] ${prevFilename} → ${filename} CACHE-MISS total=${(tEnd - tStart).toFixed(1)}ms save=${(tSaveEnd - tSaveStart).toFixed(1)}ms cache=${(tCacheEnd - tSaveEnd).toFixed(1)}ms read=${(tReadEnd - tReadStart).toFixed(1)}ms parse=${(tParseEnd - tReadEnd).toFixed(1)}ms setActive=${(tEnd - tParseEnd).toFixed(1)}ms`);
     return { document: getDocument(), title: getTitle(), filename };
 }
 export function createDocument(title, content, path) {

package/dist/server/enrichment.js

@@ -0,0 +1,114 @@
+/**
+ * Frontmatter enrichment staleness detection.
+ *
+ * The matcher already splits every block into sentences and hashes each one on
+ * every save (see node-fingerprint.ts). We reuse that machinery here — no new
+ * algorithm, no new splitter. Save-time staleness is a small tag-on after the
+ * matcher: harvest the current sentence-hash set + char count, compare against
+ * the at-enrichment baseline stored in frontmatter, set `enrichmentStale: true`
+ * when either threshold trips.
+ *
+ * Volume ratio captures growth and shrinkage symmetrically. Jaccard distance
+ * over the sentence-hash set captures rewrites at constant length. Either
+ * tripping flags the doc.
+ *
+ * OpenWriter owns "is this doc stale". The agent clears the flag via
+ * mark_enriched (Phase 4). Both sides read the same field, never compute it
+ * independently.
+ *
+ * See brief: 2026-05-18-frontmatter-enrichment-system.
+ */
+import { splitSentences, simpleHash } from './node-fingerprint.js';
+/** Volume-ratio threshold above which a doc is flagged stale by size delta. */
+export const DEFAULT_ENRICHMENT_VOLUME_THRESHOLD = 1.5;
+/** Jaccard-distance threshold above which a doc is flagged stale by drift. */
+export const DEFAULT_ENRICHMENT_DRIFT_THRESHOLD = 0.3;
+/**
+ * Flatten every block's per-sentence hashes into one sorted unique set.
+ * Sorted so the on-disk representation is stable across saves (no spurious
+ * frontmatter diffs from set-order drift). Unique so duplicate sentences
+ * in the same doc don't double-count in the Jaccard math.
+ */
+export function harvestSentenceHashes(blocks) {
+    const set = new Set();
+    for (const block of blocks) {
+        const sentences = splitSentences(block.text || '');
+        for (const s of sentences) {
+            set.add(simpleHash(s.text + s.terminator));
+        }
+    }
+    return Array.from(set).sort();
+}
+/** Total char count across all blocks' text — the volume signal. */
+export function harvestCharCount(blocks) {
+    let n = 0;
+    for (const b of blocks)
+        n += (b.text || '').length;
+    return n;
+}
+/**
+ * Symmetric size delta. Returns 1 when sizes match, grows toward infinity as
+ * they diverge in either direction. Handles zero-size docs safely.
+ */
+export function volumeRatio(current, baseline) {
+    if (current === 0 && baseline === 0)
+        return 1;
+    if (current === 0 || baseline === 0)
+        return Infinity;
+    return Math.max(current, baseline) / Math.min(current, baseline);
+}
+/**
+ * Jaccard distance over two sentence-hash sets. 0 = identical, 1 = disjoint.
+ * (union - intersection) / union. Empty-vs-empty returns 0.
+ */
+export function jaccardDistance(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    let intersection = 0;
+    for (const x of setA)
+        if (setB.has(x))
+            intersection++;
+    const union = setA.size + setB.size - intersection;
+    return union === 0 ? 0 : (union - intersection) / union;
+}
+/**
+ * Compute staleness for a single doc given current matcher-derived signals
+ * and the at-enrichment baseline stored in its frontmatter.
+ *
+ * Returns true when:
+ *   - the doc has never been enriched (no lastEnrichedAt) — brief: "absent flag = stale"
+ *   - volumeRatio trips its threshold
+ *   - Jaccard drift trips its threshold
+ *
+ * Thresholds: doc-level overrides first, then global defaults. Workspace-level
+ * overrides (per the brief) will be layered in when the surfacing handlers
+ * (Phase 6) get a workspace pointer — for now the doc carries no workspace
+ * reference in writeToDisk's scope.
+ */
+export function isEnrichmentStale(currentSentenceHashes, currentCharCount, metadata, workspaceOverrides) {
+    // Never enriched → stale by default. New docs land here.
+    if (!metadata.lastEnrichedAt)
+        return true;
+    const baselineHashes = Array.isArray(metadata.lastEnrichedSentences)
+        ? metadata.lastEnrichedSentences
+        : [];
+    const baselineChars = typeof metadata.lastEnrichedCharCount === 'number'
+        ? metadata.lastEnrichedCharCount
+        : 0;
+    const volTh = pickThreshold(metadata.enrichmentVolumeThreshold, workspaceOverrides?.volume, DEFAULT_ENRICHMENT_VOLUME_THRESHOLD);
+    const driftTh = pickThreshold(metadata.enrichmentDriftThreshold, workspaceOverrides?.drift, DEFAULT_ENRICHMENT_DRIFT_THRESHOLD);
+    if (volumeRatio(currentCharCount, baselineChars) >= volTh)
+        return true;
+    if (jaccardDistance(currentSentenceHashes, baselineHashes) >= driftTh)
+        return true;
+    return false;
+}
+function pickThreshold(docLevel, wsLevel, fallback) {
+    if (typeof docLevel === 'number' && docLevel > 0)
+        return docLevel;
+    if (typeof wsLevel === 'number' && wsLevel > 0)
+        return wsLevel;
+    return fallback;
+}