openwriter 0.5.2 → 0.5.4

package/dist/server/index.js

@@ -12,8 +12,7 @@ import { TOOL_REGISTRY } from './mcp.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { save, getDocument, getTitle, getFilePath, getDocId, getMetadata, getStatus, updateDocument, setMetadata, applyTextEdits, isAgentLocked, getPendingDocInfo, getDocTagsByFilename, addDocTag, removeDocTag, markAllNodesAsPending, updatePendingCacheForActiveDoc } from './state.js';
-import { listDocuments, switchDocument, createDocument, deleteDocument, duplicateDocument, reloadDocument, updateDocumentTitle, openFile, reorderDocs } from './documents.js';
-import { writePromptDebug } from './prompt-debug.js';
+import { listDocuments, switchDocument, createDocument, deleteDocument, duplicateDocument, reloadDocument, updateDocumentTitle, openFile, reorderDocs, searchDocuments, listArchivedDocuments, archiveDocument, unarchiveDocument } from './documents.js';
 import { createWorkspaceRouter } from './workspace-routes.js';
 import { createLinkRouter } from './link-routes.js';
 import { createTweetRouter } from './tweet-routes.js';
@@ -56,7 +55,14 @@ export async function startHttpServer(options = {}) {
                 res.status(404).json({ error: `Unknown tool: ${toolName}` });
                 return;
             }
-            const result = await tool.handler(args || {});
+            // Validate arguments against the tool's Zod schema (mirrors McpServer.validateToolInput)
+            const schema = z.object(tool.schema);
+            const parsed = schema.safeParse(args || {});
+            if (!parsed.success) {
+                res.status(400).json({ content: [{ type: 'text', text: `Validation error: ${parsed.error.message}` }] });
+                return;
+            }
+            const result = await tool.handler(parsed.data);
             res.json(result);
         }
         catch (err) {
@@ -223,6 +229,39 @@ export async function startHttpServer(options = {}) {
             res.status(500).json({ error: err.message });
         }
     });
+    app.get('/api/documents/archived', (_req, res) => {
+        res.json(listArchivedDocuments());
+    });
+    app.get('/api/documents/search', (req, res) => {
+        const q = req.query.q || '';
+        const includeArchived = req.query.archived === 'true';
+        res.json(searchDocuments(q, includeArchived));
+    });
+    app.post('/api/documents/:filename/archive', (req, res) => {
+        try {
+            removeDocFromAllWorkspaces(req.params.filename);
+            const result = archiveDocument(req.params.filename);
+            if (result.switched && result.newDoc) {
+                broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
+            }
+            broadcastDocumentsChanged();
+            broadcastWorkspacesChanged();
+            res.json(result);
+        }
+        catch (err) {
+            res.status(400).json({ error: err.message });
+        }
+    });
+    app.post('/api/documents/:filename/unarchive', (req, res) => {
+        try {
+            const result = unarchiveDocument(req.params.filename);
+            broadcastDocumentsChanged();
+            res.json(result);
+        }
+        catch (err) {
+            res.status(400).json({ error: err.message });
+        }
+    });
     app.get('/api/documents/:filename/content', (req, res) => {
         try {
             const targetPath = resolveDocPath(req.params.filename);
@@ -361,22 +400,6 @@ export async function startHttpServer(options = {}) {
             res.status(500).json({ error: err.message });
         }
     });
-    // Prompt debug: write full prompt to a timestamped .md file for inspection
-    app.post('/api/prompt-debug', (req, res) => {
-        try {
-            const { action, debug, metadata } = req.body;
-            if (!debug) {
-                res.status(400).json({ error: 'debug payload is required' });
-                return;
-            }
-            const filename = writePromptDebug(action, debug, metadata);
-            broadcastDocumentsChanged();
-            res.json({ success: true, filename });
-        }
-        catch (err) {
-            res.status(500).json({ error: err.message });
-        }
-    });
     // Google Doc import
     app.post('/api/import/gdoc', (req, res) => {
         try {
@@ -523,8 +546,26 @@ export async function startHttpServer(options = {}) {
     setupWebSocket(server);
     // Broadcast agent status now that WS is ready
     broadcastAgentStatus(true);
-    server.listen(port, '127.0.0.1', () => {
-        console.log(`OpenWriter running at http://localhost:${port}`);
+    await new Promise((resolve, reject) => {
+        server.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                console.error(`[HTTP] Port ${port} in use — retrying in 2s...`);
+                setTimeout(() => {
+                    server.listen(port, '127.0.0.1', () => {
+                        console.log(`OpenWriter running at http://localhost:${port}`);
+                        resolve();
+                    });
+                }, 2000);
+            }
+            else {
+                console.error(`[HTTP] Server error:`, err);
+                reject(err);
+            }
+        });
+        server.listen(port, '127.0.0.1', () => {
+            console.log(`OpenWriter running at http://localhost:${port}`);
+            resolve();
+        });
     });
     // Open browser unless --no-open or running as MCP stdio pipe
     const isMcpStdio = !process.stdout.isTTY;

package/dist/server/mcp.js

@@ -9,19 +9,38 @@ 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 { DATA_DIR, ensureDataDir } from './helpers.js';
+import { DATA_DIR, ensureDataDir, resolveDocPath } 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 { listDocuments, switchDocument, createDocument, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile } from './documents.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, renameWorkspace, renameContainer } from './workspaces.js';
-import { addDocTag, removeDocTag, getDocTagsByFilename } from './state.js';
+import { addDocTag, removeDocTag, getDocTagsByFilename, getCachedDocument } from './state.js';
 import { importGoogleDoc } from './gdoc-import.js';
-import { toCompactFormat, compactNodes, parseMarkdownContent } from './compact.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 { getMarks, getMarkCount, getGlobalMarkSummary, resolveMarks } from './marks.js';
 import { broadcastMarksChanged } from './ws.js';
+/** Check if a document is in tweet compose mode (has tweetContext metadata). */
+function isTweetDoc(filename) {
+    if (!filename || filename === getActiveFilename()) {
+        return !!getMetadata()?.tweetContext;
+    }
+    const targetPath = resolveDocPath(filename);
+    const cached = getCachedDocument(targetPath);
+    if (cached)
+        return !!cached.metadata?.tweetContext;
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const { data } = matter(raw);
+        return !!data?.tweetContext;
+    }
+    catch {
+        return false;
+    }
+}
 export const TOOL_REGISTRY = [
     {
         name: 'read_pad',
@@ -29,7 +48,7 @@ export const TOOL_REGISTRY = [
         schema: {},
         handler: async () => {
             const doc = getDocument();
-            const compact = toCompactFormat(doc, getTitle(), getWordCount(), getPendingChangeCount());
+            const compact = toCompactFormat(doc, getTitle(), getWordCount(), getPendingChangeCount(), getDocId());
             const activeFile = getActiveFilename();
             const localCount = getMarkCount(activeFile);
             const { totalMarks: otherMarks, docCount: otherDocs } = getGlobalMarkSummary(activeFile);
@@ -45,7 +64,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'write_to_pad',
-        description: 'Preferred tool for all document edits. Send 3-8 changes per call for responsive feel. Multiple rapid calls better than one monolithic call. Content can be a markdown string (preferred) or TipTap JSON. Markdown strings are auto-converted. Changes appear as pending decorations the user accepts or rejects. Use afterNodeId: "end" to append to the document without knowing node IDs. Response includes lastNodeId for chaining subsequent inserts. Always specify filename — edits target that file directly without switching the user\'s view.',
+        description: 'Preferred tool for all document edits. Send 3-8 changes per call for responsive feel. Multiple rapid calls better than one monolithic call. Content can be a markdown string (preferred) or TipTap JSON. Markdown strings are auto-converted. Changes appear as pending decorations the user accepts or rejects. Use afterNodeId: "end" to append to the document without knowing node IDs. Response includes lastNodeId for chaining subsequent inserts. Target document by docId (8-char hex from list_documents or read_pad).',
         schema: {
             changes: z.array(z.object({
                 operation: z.enum(['rewrite', 'insert', 'delete']),
@@ -53,13 +72,18 @@ export const TOOL_REGISTRY = [
                 afterNodeId: z.string().optional(),
                 content: z.any().optional(),
             })).describe('Array of node changes. Content accepts markdown strings or TipTap JSON.'),
-            filename: z.string().describe('Target filename (e.g. "My Essay.md"). Required — identifies which document to edit.'),
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents or read_pad).'),
         },
-        handler: async ({ changes, filename }) => {
+        handler: async ({ changes, docId }) => {
+            const filename = resolveDocId(docId);
+            const tweetMode = isTweetDoc(filename);
             const processed = changes.map((change) => {
                 const resolved = { ...change };
                 if (typeof resolved.content === 'string') {
-                    resolved.content = parseMarkdownContent(resolved.content);
+                    let nodes = parseMarkdownContent(resolved.content);
+                    if (tweetMode)
+                        nodes = mergeParagraphsToHardBreaks(nodes);
+                    resolved.content = nodes;
                 }
                 return resolved;
             });
@@ -117,30 +141,32 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_documents',
-        description: 'List all documents in the workspace. Shows filename, word count, last modified date, and which document is active.',
+        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.',
         schema: {},
         handler: async () => {
             const docs = listDocuments();
             const lines = docs.map((d) => {
                 const active = d.isActive ? ' (active)' : '';
+                const id = d.docId ? ` [${d.docId}]` : '';
                 const date = d.lastModified.split('T')[0];
-                return `  ${d.filename}${active} — ${d.wordCount.toLocaleString()} words — ${date}`;
+                return `  "${d.title}"${id}${active} — ${d.wordCount.toLocaleString()} words — ${date}`;
             });
             return { content: [{ type: 'text', text: `documents:\n${lines.join('\n') || '  (none)'}` }] };
         },
     },
     {
         name: 'switch_document',
-        description: 'Switch to a different document by filename. Saves the current document first. Returns a compact read of the newly active 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).',
         schema: {
-            filename: z.string().describe('Filename of the document to switch to (e.g. "My Essay.md")'),
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents or read_pad).'),
         },
-        handler: async ({ filename }) => {
+        handler: async ({ docId }) => {
+            const filename = resolveDocId(docId);
             broadcastWritingFinished(); // Clear any in-progress creation spinner
             const result = switchDocument(filename);
             broadcastDocumentSwitched(result.document, result.title, result.filename);
-            const compact = toCompactFormat(result.document, result.title, getWordCount(), getPendingChangeCount());
-            return { content: [{ type: 'text', text: `Switched to "${result.title}"\n\n${compact}` }] };
+            const compact = toCompactFormat(result.document, result.title, getWordCount(), getPendingChangeCount(), getDocId());
+            return { content: [{ type: 'text', text: `Switched to "${result.title}" [${docId}]\n\n${compact}` }] };
         },
     },
     {
@@ -172,18 +198,16 @@ export const TOOL_REGISTRY = [
                 await new Promise((resolve) => setTimeout(resolve, 200));
             }
             try {
-                // Lock browser doc-updates: prevents race where browser sends a doc-update
-                // for the previous document but server has already switched active doc.
-                setAgentLock();
-                const result = createDocument(title, undefined, path);
-                // Auto-add to workspace if specified
-                let wsInfo = '';
-                if (wsTarget) {
-                    addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
-                    wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
-                }
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
+                    setAgentLock();
+                    const result = createDocument(title, undefined, path);
+                    let wsInfo = '';
+                    if (wsTarget) {
+                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                        wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
+                    }
+                    const newDocId = getDocId();
                     save();
                     broadcastDocumentsChanged();
                     broadcastWorkspacesChanged();
@@ -191,19 +215,23 @@ export const TOOL_REGISTRY = [
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Created "${result.title}" (${result.filename})${wsInfo} — ready.`,
+                                text: `Created "${result.title}" [${newDocId}]${wsInfo} — ready.`,
                             }],
                     };
                 }
-                // Two-step flow: spinner persists until populate_document is called
-                setMetadata({ agentCreated: true });
-                save(); // Persist agentCreated flag to frontmatter
+                // Two-step flow: create file on disk WITHOUT switching the user's view.
+                // The spinner persists in the sidebar until populate_document is called.
+                const result = createDocumentFile(title, path);
+                let wsInfo = '';
+                if (wsTarget) {
+                    addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                    wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
+                }
                 broadcastDocumentsChanged();
-                broadcastDocumentSwitched(getDocument(), getTitle(), getActiveFilename());
                 return {
                     content: [{
                             type: 'text',
-                            text: `Created "${result.title}" (${result.filename})${wsInfo} — empty. Call populate_document to add content.`,
+                            text: `Created "${result.title}" [${result.docId}]${wsInfo} — empty. Call populate_document with docId "${result.docId}" to add content.`,
                         }],
                 };
             }
@@ -216,16 +244,20 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'populate_document',
-        description: 'Populate a document with content. Use after create_document (without content) to complete the two-step creation flow. Content appears as pending decorations for user review. Clears the sidebar creation spinner and shows the document. Pass the filename from create_document\'s response to ensure content goes to the right doc even if the user switched away.',
+        description: 'Populate a document with content. Use after create_document (without content) to complete the two-step creation flow. Content appears as pending decorations for user review. Clears the sidebar creation spinner and shows the document. Pass the docId from create_document\'s response to ensure content goes to the right doc even if the user switched away.',
         schema: {
             content: z.any().describe('Document content: markdown string (preferred) or TipTap JSON doc object.'),
-            filename: z.string().optional().describe('Target filename (e.g. "My Essay.md"). If provided and differs from the active doc, writes directly to disk without switching the user\'s view. Recommended — prevents race conditions when the user navigates during content generation.'),
+            docId: z.string().optional().describe('Target document by docId (8-char hex from create_document or list_documents). If provided and differs from the active doc, writes directly to disk without switching the user\'s view. Recommended — prevents race conditions when the user navigates during content generation.'),
         },
-        handler: async ({ content, filename }) => {
+        handler: async ({ content, docId }) => {
+            const filename = docId ? resolveDocId(docId) : undefined;
             try {
                 let doc;
                 if (typeof content === 'string') {
-                    doc = { type: 'doc', content: parseMarkdownContent(content) };
+                    let nodes = parseMarkdownContent(content);
+                    if (isTweetDoc(filename))
+                        nodes = mergeParagraphsToHardBreaks(nodes);
+                    doc = { type: 'doc', content: nodes };
                 }
                 else if (content?.type === 'doc' && Array.isArray(content.content)) {
                     doc = content;
@@ -287,17 +319,19 @@ export const TOOL_REGISTRY = [
         handler: async ({ path }) => {
             const result = openFile(path);
             broadcastDocumentSwitched(result.document, result.title, result.filename);
-            const compact = toCompactFormat(result.document, result.title, getWordCount(), getPendingChangeCount());
-            return { content: [{ type: 'text', text: `Opened "${result.title}" from ${path}\n\n${compact}` }] };
+            const openedDocId = getDocId();
+            const compact = toCompactFormat(result.document, result.title, getWordCount(), getPendingChangeCount(), openedDocId);
+            return { content: [{ type: 'text', text: `Opened "${result.title}" [${openedDocId}] from ${path}\n\n${compact}` }] };
         },
     },
     {
         name: 'delete_document',
-        description: 'Delete a document file. Moves to OS trash (Recycle Bin / macOS Trash). If deleting the active document, automatically switches to the most recent remaining doc. Cannot delete the last document. IMPORTANT: Always confirm with the user before calling this tool.',
+        description: 'Delete a document file. Moves to OS trash (Recycle Bin / macOS Trash). If deleting the active document, automatically switches to the most recent remaining doc. Cannot delete the last document. IMPORTANT: Always confirm with the user before calling this tool. Target document by docId (8-char hex from list_documents or read_pad).',
         schema: {
-            filename: z.string().describe('Filename of the document to delete (e.g. "My Essay.md")'),
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents or read_pad).'),
         },
-        handler: async ({ filename }) => {
+        handler: async ({ docId }) => {
+            const filename = resolveDocId(docId);
             const result = await deleteDocument(filename);
             if (result.switched && result.newDoc) {
                 broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
@@ -305,11 +339,44 @@ export const TOOL_REGISTRY = [
             broadcastDocumentsChanged();
             let text = `Deleted "${filename}" (moved to trash)`;
             if (result.switched && result.newDoc) {
-                text += `. Switched to "${result.newDoc.filename}"`;
+                text += `. Switched to "${result.newDoc.title}"`;
             }
             return { content: [{ type: 'text', text }] };
         },
     },
+    {
+        name: 'archive_document',
+        description: 'Archive a document. Removes it from the active document list without deleting the file. Archived docs can be restored later with unarchive_document. If archiving the active document, automatically switches to the most recent remaining doc. Target document by docId (8-char hex from list_documents).',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const filename = resolveDocId(docId);
+            const result = archiveDocument(filename);
+            if (result.switched && result.newDoc) {
+                broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
+            }
+            broadcastDocumentsChanged();
+            let text = `Archived "${filename}"`;
+            if (result.switched && result.newDoc) {
+                text += `. Switched to "${result.newDoc.title}"`;
+            }
+            return { content: [{ type: 'text', text }] };
+        },
+    },
+    {
+        name: 'unarchive_document',
+        description: 'Restore an archived document back to the active document list. Target document by docId (8-char hex from list_documents with includeArchived).',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex).'),
+        },
+        handler: async ({ docId }) => {
+            const filename = resolveDocId(docId);
+            const result = unarchiveDocument(filename);
+            broadcastDocumentsChanged();
+            return { content: [{ type: 'text', text: `Restored "${result.title}" [${docId}] from archive` }] };
+        },
+    },
     {
         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.',
@@ -537,22 +604,27 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'rename_item',
-        description: 'Rename a workspace, container, or document. For workspaces: updates the manifest title. For containers: updates the container name in the workspace tree. For documents: updates the title in frontmatter.',
+        description: 'Rename a workspace, container, or document. For workspaces: updates the manifest title. For containers: updates the container name in the workspace tree. For documents: updates the title in frontmatter — use docId to identify the document.',
         schema: {
             type: z.enum(['workspace', 'container', 'document']).describe('What to rename'),
-            filename: z.string().describe('Workspace manifest filename (for workspace/container) or document filename (for document)'),
+            filename: z.string().optional().describe('Workspace manifest filename (required for workspace/container renames). Not used for document renames.'),
+            docId: z.string().optional().describe('Document docId (required for document renames, 8-char hex from list_documents).'),
             newName: z.string().describe('The new name/title'),
             containerId: z.string().optional().describe('Container ID (required for container renames)'),
             workspaceFile: z.string().optional().describe('Parent workspace filename (required for container renames)'),
         },
-        handler: async ({ type, filename, newName, containerId, workspaceFile }) => {
+        handler: async ({ type, filename, docId, newName, containerId, workspaceFile }) => {
             if (type === 'workspace') {
+                if (!filename)
+                    return { content: [{ type: 'text', text: 'Error: filename is required for workspace renames' }] };
                 renameWorkspace(filename, newName);
                 broadcastWorkspacesChanged();
                 return { content: [{ type: 'text', text: `Renamed workspace to "${newName}"` }] };
             }
             if (type === 'container') {
                 const wsFile = workspaceFile || filename;
+                if (!wsFile)
+                    return { content: [{ type: 'text', text: 'Error: workspaceFile or filename is required for container renames' }] };
                 if (!containerId)
                     return { content: [{ type: 'text', text: 'Error: containerId is required for container renames' }] };
                 renameContainer(wsFile, containerId, newName);
@@ -560,19 +632,22 @@ export const TOOL_REGISTRY = [
                 return { content: [{ type: 'text', text: `Renamed container ${containerId} to "${newName}"` }] };
             }
             if (type === 'document') {
-                updateDocumentTitle(filename, newName);
+                if (!docId)
+                    return { content: [{ type: 'text', text: 'Error: docId is required for document renames' }] };
+                const resolvedFilename = resolveDocId(docId);
+                updateDocumentTitle(resolvedFilename, newName);
                 broadcastDocumentsChanged();
-                if (filename === getActiveFilename()) {
+                if (resolvedFilename === getActiveFilename()) {
                     broadcastTitleChanged(newName);
                 }
-                return { content: [{ type: 'text', text: `Renamed document "${filename}" to "${newName}"` }] };
+                return { content: [{ type: 'text', text: `Renamed document [${docId}] to "${newName}"` }] };
             }
             return { content: [{ type: 'text', text: `Error: unknown type "${type}"` }] };
         },
     },
     {
         name: 'edit_text',
-        description: 'Apply fine-grained text edits within a node. Find text by exact match and replace it, or add/remove marks on matched text. More precise than rewriting the whole node. Always specify filename — edits target that file directly without switching the user\'s view.',
+        description: 'Apply fine-grained text edits within a node. Find text by exact match and replace it, or add/remove marks on matched text. More precise than rewriting the whole node. Target document by docId (8-char hex from list_documents or read_pad).',
         schema: {
             nodeId: z.string().describe('ID of the node to edit'),
             edits: z.array(z.object({
@@ -584,9 +659,10 @@ export const TOOL_REGISTRY = [
                 }).optional().describe('Mark to add to the matched text (e.g. link, bold)'),
                 removeMark: z.string().optional().describe('Mark type to remove from matched text'),
             })).describe('Array of text edits to apply'),
-            filename: z.string().describe('Target filename (e.g. "My Essay.md"). Required — identifies which document to edit.'),
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents or read_pad).'),
         },
-        handler: async ({ nodeId, edits, filename }) => {
+        handler: async ({ nodeId, edits, docId }) => {
+            const filename = resolveDocId(docId);
             const targetIsNonActive = filename && filename !== getActiveFilename();
             if (targetIsNonActive) {
                 const result = applyTextEditsToFile(filename, nodeId, edits);
@@ -629,6 +705,11 @@ export const TOOL_REGISTRY = [
             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({
@@ -654,9 +735,20 @@ export const TOOL_REGISTRY = [
             const src = `/_images/${filename}`;
             // Optionally set as article cover + append to carousel history
             if (set_cover) {
-                const meta = getMetadata();
-                const articleContext = meta.articleContext || {};
-                let existing = Array.isArray(articleContext.coverImages) ? articleContext.coverImages : [];
+                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 pre-await metadata snapshot to build the update (not live state)
+                const articleContext = preAwaitMeta.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];
@@ -676,6 +768,69 @@ export const TOOL_REGISTRY = [
             };
         },
     },
+    {
+        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.',
+        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.'),
+            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).'),
+        },
+        handler: async ({ docId, prompt, afterNodeId, aspect_ratio, alt }) => {
+            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);
+            // Generate image via Gemini
+            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(DATA_DIR, '_images');
+            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 src = `/_images/${imgFilename}`;
+            // Build image node and insert change
+            const imageNode = { type: 'image', attrs: { src, alt: alt || prompt } };
+            const change = { operation: 'insert', afterNodeId, content: [imageNode] };
+            const targetIsNonActive = filename && filename !== getActiveFilename();
+            if (targetIsNonActive) {
+                const { lastNodeId } = applyChangesToFile(filename, [change]);
+                broadcastPendingDocsChanged();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({ success: true, src, ...(lastNodeId ? { lastNodeId } : {}) }),
+                        }],
+                };
+            }
+            const { lastNodeId } = applyChanges([change]);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: true, src, ...(lastNodeId ? { lastNodeId } : {}) }),
+                    }],
+            };
+        },
+    },
     {
         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.',
@@ -751,11 +906,12 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_agent_marks',
-        description: 'Get inline feedback marks left by the user. Users select text in the editor, right-click → Agent Mark, and leave notes for the agent. Returns marks grouped by filename with text, note, and nodeId. Call resolve_agent_marks after addressing each mark.',
+        description: 'Get inline feedback marks left by the user. Users select text in the editor, right-click → Agent Mark, and leave notes for the agent. Returns marks grouped by document with text, note, and nodeId. Call resolve_agent_marks after addressing each mark.',
         schema: {
-            filename: z.string().optional().describe('Document filename to get marks for. Omit to get marks across all documents.'),
+            docId: z.string().optional().describe('Target document by docId (8-char hex). Omit to get marks across all documents.'),
         },
-        handler: async ({ filename }) => {
+        handler: async ({ docId }) => {
+            const filename = docId ? resolveDocId(docId) : undefined;
             const marks = getMarks(filename);
             const entries = Object.entries(marks);
             if (entries.length === 0) {

package/dist/server/state.js

@@ -146,7 +146,7 @@ export function setMetadata(updates) {
     state.metadata = { ...state.metadata, ...updates };
     if (updates.title)
         state.title = updates.title;
-    // Auto-tag: tweetContext / articleContext ↔ "x" tag
+    // Auto-tag: tweetContext / articleContext ↔ "x" + mode tag
     for (const key of ['tweetContext', 'articleContext']) {
         if (key in updates) {
             const filename = state.filePath
@@ -155,6 +155,9 @@ export function setMetadata(updates) {
             if (filename) {
                 if (updates[key]) {
                     addDocTag(filename, 'x');
+                    const mode = updates[key]?.mode || (key === 'articleContext' ? 'article' : undefined);
+                    if (mode)
+                        addDocTag(filename, mode);
                 }
                 else {
                     removeDocTag(filename, 'x');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.server.json",
+    "prepublishOnly": "cp ../../skills/openwriter/SKILL.md skill/SKILL.md",
     "preview": "node dist/bin/pad.js",
     "lint": "eslint src server bin --ext .ts,.tsx"
   },