openwriter 0.6.11 → 0.8.0

package/dist/server/mcp.js

@@ -4,26 +4,24 @@
  * Exports TOOL_REGISTRY for HTTP proxy (multi-session support).
  */
 import { join } from 'path';
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, statSync } from 'fs';
 import { randomUUID } from 'crypto';
 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 } from './helpers.js';
-import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, getMetadata, setMetadata, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, } from './state.js';
+import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync } from './helpers.js';
+import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument, invalidateDocCache, } from './state.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId } from './documents.js';
-import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished } from './ws.js';
-import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, removeContainer, renameWorkspace, renameContainer } from './workspaces.js';
-import { addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument } from './state.js';
+import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastMarksChanged } from './ws.js';
+import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces } from './workspaces.js';
 import { findDocNode } from './workspace-tree.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent, mergeParagraphsToHardBreaks } from './compact.js';
 import matter from 'gray-matter';
 import { getUpdateInfo } from './update-check.js';
 import { listVersions, forceSnapshot, restoreVersion } from './versions.js';
-import { markdownToTiptap } from './markdown.js';
+import { markdownToTiptap, tiptapToMarkdown } from './markdown.js';
 import { getMarks, getMarkCount, getGlobalMarkSummary, resolveMarks } from './marks.js';
-import { broadcastMarksChanged } from './ws.js';
 /** Map a content type string to its frontmatter metadata object. */
 function resolveTypeMeta(type) {
     switch (type) {
@@ -55,17 +53,76 @@ function isTweetDoc(filename) {
         return false;
     }
 }
+/** Resolve a docId to a full document target. Fast path for active doc (zero I/O). */
+function resolveDocTarget(docId) {
+    const filename = resolveDocId(docId);
+    const activeFilename = getActiveFilename();
+    // Fast path: active document — use in-memory state
+    if (filename === activeFilename) {
+        return {
+            filename,
+            filePath: getFilePath(),
+            docId,
+            isActive: true,
+            document: getDocument(),
+            title: getTitle(),
+            metadata: getMetadata(),
+            wordCount: getWordCount(),
+            pendingCount: getPendingChangeCount(),
+            lastModified: new Date(getStatus().lastModified),
+        };
+    }
+    // Non-active: try cache, then disk
+    const filePath = resolveDocPath(filename);
+    const cached = getCachedDocument(filePath);
+    if (cached) {
+        const text = extractText(cached.document.content);
+        return {
+            filename,
+            filePath,
+            docId: cached.docId,
+            isActive: false,
+            document: cached.document,
+            title: cached.title,
+            metadata: cached.metadata,
+            wordCount: text.trim() ? text.trim().split(/\s+/).length : 0,
+            pendingCount: countPending(cached.document.content),
+            lastModified: cached.lastModified,
+        };
+    }
+    // Read from disk
+    if (!existsSync(filePath))
+        throw new Error(`Document file not found: ${filename}`);
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = markdownToTiptap(raw);
+    const meta = parsed.metadata || {};
+    const resolvedDocId = meta.docId || docId;
+    const text = extractText(parsed.document.content);
+    return {
+        filename,
+        filePath,
+        docId: resolvedDocId,
+        isActive: false,
+        document: parsed.document,
+        title: parsed.title,
+        metadata: parsed.metadata || {},
+        wordCount: text.trim() ? text.trim().split(/\s+/).length : 0,
+        pendingCount: countPending(parsed.document.content),
+        lastModified: statSync(filePath).mtime,
+    };
+}
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
-        description: 'Read the current document. Returns compact tagged-line format with [type:id] per node, inline markdown formatting. Much more token-efficient than JSON.',
-        schema: {},
-        handler: async () => {
-            const doc = getDocument();
-            const compact = toCompactFormat(doc, getTitle(), getWordCount(), getPendingChangeCount(), getDocId());
-            const activeFile = getActiveFilename();
-            const localCount = getMarkCount(activeFile);
-            const { totalMarks: otherMarks, docCount: otherDocs } = getGlobalMarkSummary(activeFile);
+        description: 'Read a document by docId. Returns compact tagged-line format with [type:id] per node, inline markdown formatting. Much more token-efficient than JSON.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            const compact = toCompactFormat(target.document, target.title, target.wordCount, target.pendingCount, target.docId, target.metadata);
+            const localCount = getMarkCount(target.filename);
+            const { totalMarks: otherMarks, docCount: otherDocs } = getGlobalMarkSummary(target.filename);
             let hint = '';
             if (localCount > 0)
                 hint += `\n[${localCount} agent mark${localCount !== 1 ? 's' : ''} on this document]`;
@@ -101,6 +158,20 @@ export const TOOL_REGISTRY = [
                 }
                 return resolved;
             });
+            // Auto-clean: if doc has only a single empty paragraph and first change is
+            // an insert, convert to a rewrite so the empty node gets replaced silently
+            // (shows as green insert decoration, not a red delete).
+            const activeDoc = getDocument();
+            if (activeDoc.content?.length === 1) {
+                const first = activeDoc.content[0];
+                if (first.type === 'paragraph' && (!first.content || first.content.length === 0) && first.attrs?.id) {
+                    const insertIdx = processed.findIndex((c) => c.operation === 'insert');
+                    if (insertIdx !== -1) {
+                        processed[insertIdx] = { ...processed[insertIdx], operation: 'rewrite', nodeId: first.attrs.id };
+                        delete processed[insertIdx].afterNodeId;
+                    }
+                }
+            }
             const targetIsNonActive = filename && filename !== getActiveFilename();
             if (targetIsNonActive) {
                 const { count: appliedCount, lastNodeId } = applyChangesToFile(filename, processed);
@@ -134,10 +205,18 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_pad_status',
-        description: 'Get the current status of the pad: word count, pending changes. Cheap call for polling.',
-        schema: {},
-        handler: async () => {
-            const status = getStatus();
+        description: 'Get the status of a document: word count, pending changes. Cheap call for polling.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            const status = {
+                title: target.title,
+                wordCount: target.wordCount,
+                pendingChanges: target.pendingCount,
+                lastModified: target.lastModified.toISOString(),
+            };
             const latestVersion = getUpdateInfo();
             const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
             return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -147,10 +226,13 @@ export const TOOL_REGISTRY = [
         name: 'get_nodes',
         description: 'Get specific nodes by ID. Returns compact tagged-line format per node.',
         schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             nodeIds: z.array(z.string()).describe('Array of node IDs to retrieve'),
         },
-        handler: async ({ nodeIds }) => {
-            return { content: [{ type: 'text', text: compactNodes(getNodesByIds(nodeIds)) }] };
+        handler: async ({ docId, nodeIds }) => {
+            const target = resolveDocTarget(docId);
+            const nodes = target.isActive ? getNodesByIds(nodeIds) : findNodesByIds(target.document.content, nodeIds);
+            return { content: [{ type: 'text', text: compactNodes(nodes) }] };
         },
     },
     {
@@ -170,7 +252,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'switch_document',
-        description: 'Switch to a different document. Saves the current document first. Returns a compact read of the newly active document. Target document by docId (8-char hex from list_documents or read_pad).',
+        description: 'Show a document in the user\'s browser. NOT required before reading or editing — all tools target documents by docId directly. Use only when you want to change what the user sees. Saves the current document first. Returns a compact read of the newly active document.',
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents or read_pad).'),
         },
@@ -364,10 +446,12 @@ export const TOOL_REGISTRY = [
         handler: async ({ docId }) => {
             const filename = resolveDocId(docId);
             const result = await deleteDocument(filename);
+            removeDocFromAllWorkspaces(filename);
             if (result.switched && result.newDoc) {
                 broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
             }
             broadcastDocumentsChanged();
+            broadcastWorkspacesChanged();
             let text = `Deleted "${filename}" (moved to trash)`;
             if (result.switched && result.newDoc) {
                 text += `. Switched to "${result.newDoc.title}"`;
@@ -384,10 +468,12 @@ export const TOOL_REGISTRY = [
         handler: async ({ docId }) => {
             const filename = resolveDocId(docId);
             const result = archiveDocument(filename);
+            removeDocFromAllWorkspaces(filename);
             if (result.switched && result.newDoc) {
                 broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
             }
             broadcastDocumentsChanged();
+            broadcastWorkspacesChanged();
             let text = `Archived "${filename}"`;
             if (result.switched && result.newDoc) {
                 text += `. Switched to "${result.newDoc.title}"`;
@@ -410,20 +496,24 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_metadata',
-        description: 'Get the JSON frontmatter metadata for the active document. Returns all key-value pairs stored in frontmatter (title, summary, characters, tags, etc.). Useful for understanding document context without reading full content.',
-        schema: {},
-        handler: async () => {
-            const metadata = getMetadata();
-            return { content: [{ type: 'text', text: Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : '{}' }] };
+        description: 'Get the JSON frontmatter metadata for a document. Returns all key-value pairs stored in frontmatter (title, summary, characters, tags, etc.). Useful for understanding document context without reading full content.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            return { content: [{ type: 'text', text: Object.keys(target.metadata).length > 0 ? JSON.stringify(target.metadata) : '{}' }] };
         },
     },
     {
         name: 'set_metadata',
-        description: 'Update frontmatter metadata on the active document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately.',
+        description: 'Update frontmatter metadata on a document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately.',
         schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             metadata: z.record(z.any()).describe('Key-value pairs to merge into frontmatter. Set a key to null to remove it.'),
         },
-        handler: async ({ metadata: updates }) => {
+        handler: async ({ docId, metadata: updates }) => {
+            const target = resolveDocTarget(docId);
             const setKeys = [];
             const removed = [];
             for (const [key, value] of Object.entries(updates)) {
@@ -437,20 +527,41 @@ export const TOOL_REGISTRY = [
             const cleaned = {};
             for (const key of setKeys)
                 cleaned[key] = updates[key];
-            if (Object.keys(cleaned).length > 0)
-                setMetadata(cleaned);
-            const meta = getMetadata();
-            for (const key of removed)
-                delete meta[key];
-            save();
-            broadcastMetadataChanged(getMetadata());
-            if (cleaned.title) {
-                // Promote temp file → named file when title is set
-                const promoted = promoteTempFile(cleaned.title);
-                broadcastTitleChanged(cleaned.title);
-                broadcastDocumentsChanged();
-                if (promoted) {
-                    broadcastDocumentSwitched(getDocument(), getTitle(), promoted, getMetadata());
+            if (target.isActive) {
+                // Active doc: use in-memory path
+                if (Object.keys(cleaned).length > 0)
+                    setMetadata(cleaned);
+                const meta = getMetadata();
+                for (const key of removed)
+                    delete meta[key];
+                save();
+                broadcastMetadataChanged(getMetadata());
+                if (cleaned.title) {
+                    const promoted = promoteTempFile(cleaned.title);
+                    broadcastTitleChanged(cleaned.title);
+                    broadcastDocumentsChanged();
+                    if (promoted) {
+                        broadcastDocumentSwitched(getDocument(), getTitle(), promoted, getMetadata());
+                    }
+                }
+            }
+            else {
+                // Non-active doc: read → merge → write file
+                let meta = { ...target.metadata };
+                if (Object.keys(cleaned).length > 0) {
+                    const merged = mergeMetadataUpdates(meta, cleaned);
+                    if (merged)
+                        meta = merged;
+                }
+                for (const key of removed)
+                    delete meta[key];
+                const newTitle = cleaned.title || meta.title || target.title;
+                const markdown = tiptapToMarkdown(target.document, newTitle, meta);
+                atomicWriteFileSync(target.filePath, markdown);
+                invalidateDocCache(target.filePath);
+                if (cleaned.title) {
+                    updateDocumentTitle(target.filename, cleaned.title);
+                    broadcastDocumentsChanged();
                 }
             }
             const keys = Object.keys(cleaned);
@@ -618,28 +729,52 @@ export const TOOL_REGISTRY = [
         },
     },
     {
-        name: 'move_doc',
-        description: 'Add a document to a workspace, or move it within the workspace. If the doc is not yet in the workspace it will be added; if it is already present it will be moved to the target container.',
+        name: 'move_item',
+        description: 'Move or reorder a doc, container, or workspace. For docs: add to workspace or move within it. For containers: move to different parent or reorder within current parent. For workspaces: reorder in sidebar.',
         schema: {
-            workspaceFile: z.string().describe('Workspace manifest filename'),
-            docId: z.string().describe('Document docId (8-char hex from list_documents)'),
-            targetContainerId: z.string().optional().describe('Target container ID (omit for root level)'),
-            afterFile: z.string().optional().describe('Place after this file (omit for beginning)'),
-        },
-        handler: async ({ workspaceFile, docId, targetContainerId, afterFile }) => {
-            const filename = resolveDocId(docId);
-            const ws = getWorkspace(workspaceFile);
-            const existing = findDocNode(ws.root, filename);
-            if (existing) {
-                moveDoc(workspaceFile, filename, targetContainerId ?? null, afterFile ?? null);
+            type: z.enum(['doc', 'container', 'workspace']).describe('What to move'),
+            workspaceFile: z.string().optional().describe('Workspace manifest filename (required for doc/container)'),
+            itemId: z.string().describe('docId (8-char hex), containerId, or workspace filename'),
+            targetContainerId: z.string().optional().describe('Destination container (omit for root or same-parent reorder). Doc/container only.'),
+            afterId: z.string().optional().describe('Place after this item (omit for beginning)'),
+        },
+        handler: async ({ type, workspaceFile, itemId, targetContainerId, afterId }) => {
+            if (type === 'doc') {
+                if (!workspaceFile)
+                    return { content: [{ type: 'text', text: 'Error: workspaceFile is required for doc moves' }] };
+                const filename = resolveDocId(itemId);
+                const ws = getWorkspace(workspaceFile);
+                const inTarget = findDocNode(ws.root, filename);
+                if (inTarget) {
+                    // Within same workspace — reorder/move to container
+                    moveDoc(workspaceFile, filename, targetContainerId ?? null, afterId ?? null);
+                }
+                else {
+                    // Cross-workspace move: remove from old, add to new
+                    removeDocFromAllWorkspaces(filename);
+                    addDoc(workspaceFile, targetContainerId ?? null, filename, getDocTitle(filename), afterId ?? null);
+                }
+                broadcastWorkspacesChanged();
+                return { content: [{ type: 'text', text: `Moved "${filename}"${targetContainerId ? ` to container ${targetContainerId}` : ' to root'}` }] };
             }
-            else {
-                const title = getDocTitle(filename);
-                addDoc(workspaceFile, targetContainerId ?? null, filename, title, afterFile ?? null);
+            if (type === 'container') {
+                if (!workspaceFile)
+                    return { content: [{ type: 'text', text: 'Error: workspaceFile is required for container moves' }] };
+                if (targetContainerId !== undefined) {
+                    moveContainer(workspaceFile, itemId, targetContainerId, afterId ?? null);
+                }
+                else {
+                    moveContainer(workspaceFile, itemId, null, afterId ?? null);
+                }
+                broadcastWorkspacesChanged();
+                return { content: [{ type: 'text', text: `Moved container "${itemId}"${targetContainerId ? ` to container ${targetContainerId}` : ''}${afterId ? ` after ${afterId}` : ' to beginning'}` }] };
             }
-            broadcastWorkspacesChanged();
-            const action = existing ? 'Moved' : 'Added';
-            return { content: [{ type: 'text', text: `${action} "${filename}"${targetContainerId ? ` to container ${targetContainerId}` : ' to root'}` }] };
+            if (type === 'workspace') {
+                reorderWorkspaceAfter(itemId, afterId ?? null);
+                broadcastWorkspacesChanged();
+                return { content: [{ type: 'text', text: `Reordered workspace "${itemId}"${afterId ? ` after ${afterId}` : ' to beginning'}` }] };
+            }
+            return { content: [{ type: 'text', text: `Error: unknown type "${type}"` }] };
         },
     },
     {
@@ -732,104 +867,30 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text }] };
         },
     },
-    {
-        name: 'generate_image',
-        description: 'Generate an image using Gemini Nano Banana 2. Saves to ~/.openwriter/_images/. Optionally sets it as the active article\'s cover image atomically. Requires GEMINI_API_KEY env var.',
-        schema: {
-            prompt: z.string().max(1000).describe('Image generation prompt (max 1000 chars)'),
-            aspect_ratio: z.string().optional().describe('Aspect ratio (default "16:9"). Supported: 1:1, 9:16, 16:9, 4:3, 3:4.'),
-            set_cover: z.boolean().optional().describe('If true, atomically set the generated image as the article cover (articleContext.coverImage in metadata).'),
-        },
-        handler: async ({ prompt, aspect_ratio, set_cover }) => {
-            const apiKey = process.env.GEMINI_API_KEY;
-            if (!apiKey) {
-                return { content: [{ type: 'text', text: 'Error: GEMINI_API_KEY environment variable is not set.' }] };
-            }
-            // Capture document context BEFORE the async image generation.
-            // The active document can change during the await (user switches docs),
-            // so we snapshot the metadata and filePath now to stay scoped.
-            const preAwaitFilePath = getFilePath();
-            const preAwaitMeta = structuredClone(getMetadata());
-            const { GoogleGenAI } = await import('@google/genai');
-            const ai = new GoogleGenAI({ apiKey });
-            const response = await ai.models.generateContent({
-                model: 'gemini-3.1-flash-image-preview',
-                contents: `Generate a ${aspect_ratio || '16:9'} aspect ratio image: ${prompt}`,
-                config: {
-                    responseModalities: ['IMAGE'],
-                },
-            });
-            const parts = response.candidates?.[0]?.content?.parts;
-            const imagePart = parts?.find((p) => p.inlineData);
-            if (!imagePart?.inlineData?.data) {
-                return { content: [{ type: 'text', text: 'Error: Gemini returned no image data.' }] };
-            }
-            // Save to ~/.openwriter/_images/
-            ensureDataDir();
-            const imagesDir = join(getDataDir(), '_images');
-            if (!existsSync(imagesDir))
-                mkdirSync(imagesDir, { recursive: true });
-            const filename = `${randomUUID().slice(0, 8)}.png`;
-            const filePath = join(imagesDir, filename);
-            writeFileSync(filePath, Buffer.from(imagePart.inlineData.data, 'base64'));
-            const src = `/_images/${filename}`;
-            // Optionally set as article cover + append to carousel history
-            if (set_cover) {
-                const docChanged = getFilePath() !== preAwaitFilePath;
-                if (docChanged) {
-                    // Active document changed during image generation — skip set_cover
-                    // to avoid leaking cover images across documents.
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({ success: true, src, coverSet: false, warning: 'Active document changed during generation — cover not set. Use set_metadata to assign manually.' }),
-                            }],
-                    };
-                }
-                // Use LIVE metadata for coverImages (not stale pre-await snapshot)
-                // so concurrent generate_image calls don't overwrite each other's results
-                const liveMeta = getMetadata();
-                const articleContext = liveMeta.articleContext || {};
-                let existing = Array.isArray(articleContext.coverImages) ? [...articleContext.coverImages] : [];
-                // Seed with current coverImage if array is empty (first carousel entry)
-                if (existing.length === 0 && articleContext.coverImage) {
-                    existing = [articleContext.coverImage];
-                }
-                existing.push(src);
-                articleContext.coverImage = src;
-                articleContext.coverImages = existing;
-                setMetadata({ articleContext });
-                save();
-                broadcastMetadataChanged(getMetadata());
-            }
-            return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({ success: true, src, ...(set_cover ? { coverSet: true } : {}) }),
-                    }],
-            };
-        },
-    },
     {
         name: 'insert_image',
-        description: 'Generate an image via Gemini and insert it inline into a document. The image appears with a green pending decoration for user review. Uses the same change pipeline as write_to_pad.',
+        description: 'Generate an image via Gemini and optionally insert it inline or set it as article cover. Three modes: (1) docId + afterNodeId → generate + insert inline with pending decoration. (2) set_cover: true → generate + set as article cover. (3) Neither → generate to disk only, returns path. Requires GEMINI_API_KEY env var.',
         schema: {
-            docId: z.string().describe('Target document by docId (8-char hex).'),
             prompt: z.string().max(1000).describe('Gemini image generation prompt (max 1000 chars).'),
-            afterNodeId: z.string().describe('Insert after this node ID, or "end" to append at the bottom.'),
+            docId: z.string().optional().describe('Target document by docId (8-char hex). Required for inline insert.'),
+            afterNodeId: z.string().optional().describe('Insert after this node ID, or "end" to append. Required for inline insert.'),
             aspect_ratio: z.string().optional().describe('Aspect ratio (default "16:9"). Supported: 1:1, 9:16, 16:9, 4:3, 3:4.'),
             alt: z.string().optional().describe('Alt text for the image (defaults to prompt).'),
+            set_cover: z.boolean().optional().describe('If true, set the generated image as the article cover (articleContext.coverImage in metadata).'),
         },
-        handler: async ({ docId, prompt, afterNodeId, aspect_ratio, alt }) => {
+        handler: async ({ prompt, docId, afterNodeId, aspect_ratio, alt, set_cover }) => {
             const apiKey = process.env.GEMINI_API_KEY;
             if (!apiKey) {
                 return { content: [{ type: 'text', text: 'Error: GEMINI_API_KEY environment variable is not set.' }] };
             }
-            const filename = resolveDocId(docId);
+            const inlineMode = docId && afterNodeId;
+            const filename = inlineMode ? resolveDocId(docId) : undefined;
             const targetIsNonActive = filename && filename !== getActiveFilename();
-            // Phase 1: Insert imageLoading placeholder immediately (active doc only)
+            // Capture context before async work (for set_cover)
+            const preAwaitFilePath = getFilePath();
+            // Phase 1: Insert imageLoading placeholder immediately (inline + active doc only)
             const loadingNodeId = generateNodeId();
-            if (!targetIsNonActive) {
+            if (inlineMode && !targetIsNonActive) {
                 const loadingChange = {
                     operation: 'insert',
                     afterNodeId,
@@ -851,8 +912,7 @@ export const TOOL_REGISTRY = [
                 const parts = response.candidates?.[0]?.content?.parts;
                 const imagePart = parts?.find((p) => p.inlineData);
                 if (!imagePart?.inlineData?.data) {
-                    // Remove placeholder on failure
-                    if (!targetIsNonActive) {
+                    if (inlineMode && !targetIsNonActive) {
                         applyChanges([{ operation: 'delete', nodeId: loadingNodeId }]);
                     }
                     return { content: [{ type: 'text', text: 'Error: Gemini returned no image data.' }] };
@@ -863,39 +923,63 @@ export const TOOL_REGISTRY = [
                 if (!existsSync(imagesDir))
                     mkdirSync(imagesDir, { recursive: true });
                 const imgFilename = `${randomUUID().slice(0, 8)}.png`;
-                const filePath = join(imagesDir, imgFilename);
-                writeFileSync(filePath, Buffer.from(imagePart.inlineData.data, 'base64'));
+                const imgPath = join(imagesDir, imgFilename);
+                writeFileSync(imgPath, Buffer.from(imagePart.inlineData.data, 'base64'));
                 const src = `/_images/${imgFilename}`;
-                // Phase 2: Replace placeholder with real image (or direct insert for non-active)
-                if (targetIsNonActive) {
+                // Mode 1: Inline insert
+                if (inlineMode) {
                     const imageNode = { type: 'image', attrs: { src, alt: alt || prompt } };
-                    const change = { operation: 'insert', afterNodeId, content: [imageNode] };
-                    const { lastNodeId } = applyChangesToFile(filename, [change]);
-                    broadcastPendingDocsChanged();
-                    return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify({ success: true, src, ...(lastNodeId ? { lastNodeId } : {}) }),
-                            }],
-                    };
+                    if (targetIsNonActive) {
+                        const change = { operation: 'insert', afterNodeId, content: [imageNode] };
+                        const { lastNodeId } = applyChangesToFile(filename, [change]);
+                        broadcastPendingDocsChanged();
+                        return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, ...(lastNodeId ? { lastNodeId } : {}) }) }] };
+                    }
+                    // Hard-replace: mutate server doc directly, bypass applyChanges.
+                    // During async generation (5-10s) the agent lock expires and browser doc-updates
+                    // can change the imageLoading node's ID. Find it by type, not stale ID.
+                    // Then broadcast document-switched so the browser rebuilds from server truth.
+                    const doc = getDocument();
+                    const imgId = generateNodeId();
+                    const pendingImage = { ...imageNode, attrs: { ...imageNode.attrs, id: imgId, pendingStatus: 'insert' } };
+                    const idx = doc.content?.findIndex((n) => n.type === 'imageLoading') ?? -1;
+                    if (idx >= 0) {
+                        doc.content.splice(idx, 1, pendingImage);
+                    }
+                    else {
+                        doc.content.push(pendingImage);
+                    }
+                    updateDocument(doc);
+                    save();
+                    setAgentLock();
+                    broadcastDocumentSwitched(doc, getTitle(), getActiveFilename(), getMetadata());
+                    return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, lastNodeId: imgId }) }] };
                 }
-                const imageNode = { type: 'image', attrs: { src, alt: alt || prompt } };
-                const rewriteChange = {
-                    operation: 'rewrite',
-                    nodeId: loadingNodeId,
-                    content: [imageNode],
-                };
-                const { lastNodeId } = applyChanges([rewriteChange]);
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({ success: true, src, ...(lastNodeId ? { lastNodeId } : {}) }),
-                        }],
-                };
+                // Mode 2: Set as article cover
+                if (set_cover) {
+                    const docChanged = getFilePath() !== preAwaitFilePath;
+                    if (docChanged) {
+                        return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, coverSet: false, warning: 'Active document changed during generation — cover not set.' }) }] };
+                    }
+                    const liveMeta = getMetadata();
+                    const articleContext = liveMeta.articleContext || {};
+                    let existing = Array.isArray(articleContext.coverImages) ? [...articleContext.coverImages] : [];
+                    if (existing.length === 0 && articleContext.coverImage) {
+                        existing = [articleContext.coverImage];
+                    }
+                    existing.push(src);
+                    articleContext.coverImage = src;
+                    articleContext.coverImages = existing;
+                    setMetadata({ articleContext });
+                    save();
+                    broadcastMetadataChanged(getMetadata());
+                    return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, coverSet: true }) }] };
+                }
+                // Mode 3: Generate to disk only
+                return { content: [{ type: 'text', text: JSON.stringify({ success: true, src }) }] };
             }
             catch (err) {
-                // Remove placeholder on error
-                if (!targetIsNonActive) {
+                if (inlineMode && !targetIsNonActive) {
                     try {
                         applyChanges([{ operation: 'delete', nodeId: loadingNodeId }]);
                     }
@@ -907,13 +991,13 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_versions',
-        description: 'List version history for the active document. Returns timestamps, word counts, and sizes. Use to find a timestamp for restore_version.',
-        schema: {},
-        handler: async () => {
-            const docId = getDocId();
-            if (!docId)
-                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
-            const versions = listVersions(docId);
+        description: 'List version history for a document. Returns timestamps, word counts, and sizes. Use to find a timestamp for restore_version.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            const versions = listVersions(target.docId);
             if (versions.length === 0)
                 return { content: [{ type: 'text', text: 'No versions found for this document.' }] };
             const lines = versions.map((v, i) => `  ${i + 1}. ${v.date}  ts:${v.timestamp}  ${v.wordCount.toLocaleString()} words  ${(v.size / 1024).toFixed(1)}KB`);
@@ -922,60 +1006,71 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'create_checkpoint',
-        description: 'Force a version snapshot of the active document right now. Use before risky operations as a safety net.',
-        schema: {},
-        handler: async () => {
-            const docId = getDocId();
-            const filePath = getFilePath();
-            if (!docId || !filePath)
-                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
-            forceSnapshot(docId, filePath);
+        description: 'Force a version snapshot of a document right now. Use before risky operations as a safety net.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            forceSnapshot(target.docId, target.filePath);
             return { content: [{ type: 'text', text: `Checkpoint created at ${new Date().toISOString()}` }] };
         },
     },
     {
         name: 'restore_version',
-        description: 'Restore the active document to a previous version by timestamp. Automatically creates a safety checkpoint of the current state first. Get timestamps from list_versions.',
+        description: 'Restore a document to a previous version by timestamp. Automatically creates a safety checkpoint of the current state first. Get timestamps from list_versions.',
         schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             timestamp: z.number().describe('Version timestamp to restore (from list_versions)'),
         },
-        handler: async ({ timestamp }) => {
-            const docId = getDocId();
-            const filePath = getFilePath();
-            if (!docId || !filePath)
-                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
+        handler: async ({ docId, timestamp }) => {
+            const target = resolveDocTarget(docId);
             // Safety net: snapshot current state before restoring
             try {
-                forceSnapshot(docId, filePath);
+                forceSnapshot(target.docId, target.filePath);
             }
             catch { /* best effort */ }
-            const parsed = restoreVersion(docId, timestamp);
+            const parsed = restoreVersion(target.docId, timestamp);
             if (!parsed)
                 return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
-            updateDocument(parsed.document);
-            save();
-            const filename = filePath.split(/[/\\]/).pop() || '';
-            broadcastDocumentSwitched(parsed.document, parsed.title, filename);
+            if (target.isActive) {
+                updateDocument(parsed.document);
+                save();
+                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
+            }
+            else {
+                // Write restored content to file without switching active doc
+                const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+                atomicWriteFileSync(target.filePath, markdown);
+                invalidateDocCache(target.filePath);
+                broadcastDocumentsChanged();
+            }
             return { content: [{ type: 'text', text: `Restored version from ${new Date(timestamp).toISOString()} — "${parsed.title}"` }] };
         },
     },
     {
         name: 'reload_from_disk',
-        description: 'Re-read the active document from its file on disk. Use when the file was modified externally and the editor needs to pick up changes. Does NOT rescan the full document list.',
-        schema: {},
-        handler: async () => {
-            const filePath = getFilePath();
-            if (!filePath)
-                return { content: [{ type: 'text', text: 'Error: No active document.' }] };
-            if (!existsSync(filePath))
-                return { content: [{ type: 'text', text: `Error: File not found: ${filePath}` }] };
-            const markdown = readFileSync(filePath, 'utf-8');
-            const parsed = markdownToTiptap(markdown);
-            updateDocument(parsed.document);
-            save();
-            const filename = filePath.split(/[/\\]/).pop() || '';
-            broadcastDocumentSwitched(parsed.document, parsed.title, filename);
-            return { content: [{ type: 'text', text: `Reloaded "${parsed.title}" from disk` }] };
+        description: 'Re-read a document from its file on disk. Use when the file was modified externally and the editor needs to pick up changes. Does NOT rescan the full document list.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            if (!existsSync(target.filePath))
+                return { content: [{ type: 'text', text: `Error: File not found: ${target.filePath}` }] };
+            if (target.isActive) {
+                const markdown = readFileSync(target.filePath, 'utf-8');
+                const parsed = markdownToTiptap(markdown);
+                updateDocument(parsed.document);
+                save();
+                broadcastDocumentSwitched(parsed.document, parsed.title, target.filename);
+                return { content: [{ type: 'text', text: `Reloaded "${parsed.title}" from disk` }] };
+            }
+            else {
+                // Non-active: just invalidate cache so next access re-reads from disk
+                invalidateDocCache(target.filePath);
+                return { content: [{ type: 'text', text: `Cache invalidated for "${target.title}" — next access will re-read from disk` }] };
+            }
         },
     },
     {