openwriter 0.4.0 → 0.5.1

package/dist/server/state.js

@@ -8,7 +8,7 @@ import { join } from 'path';
 import matter from 'gray-matter';
 import { tiptapToMarkdown, markdownToTiptap } from './markdown.js';
 import { applyTextEditsToNode } from './text-edit.js';
-import { DATA_DIR, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc } from './helpers.js';
+import { DATA_DIR, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync } from './helpers.js';
 import { snapshotIfNeeded, ensureDocId } from './versions.js';
 const DEFAULT_DOC = {
     type: 'doc',
@@ -31,7 +31,7 @@ const EXTERNAL_DOCS_FILE = join(DATA_DIR, 'external-docs.json');
 const externalDocs = new Set();
 function persistExternalDocs() {
     try {
-        writeFileSync(EXTERNAL_DOCS_FILE, JSON.stringify([...externalDocs]), 'utf-8');
+        atomicWriteFileSync(EXTERNAL_DOCS_FILE, JSON.stringify([...externalDocs]));
     }
     catch { /* best-effort */ }
 }
@@ -172,6 +172,15 @@ export function getStatus() {
 // SETTERS
 // ============================================================================
 export function updateDocument(doc) {
+    // Safety: reject dramatically smaller documents (same logic as destructive save check).
+    // Prevents stale browser tabs from overwriting the correct in-memory state with
+    // corrupted content (e.g. tweet compose view sending 4-node doc vs 40-node original).
+    const currentNodes = state.document?.content?.length ?? 0;
+    const incomingNodes = doc?.content?.length ?? 0;
+    if (currentNodes > 5 && incomingNodes < currentNodes * 0.3) {
+        console.error(`[State] BLOCKED destructive updateDocument: ${incomingNodes} nodes would replace ${currentNodes} nodes`);
+        return;
+    }
     // Preserve pending attrs that the browser doesn't track in its document model.
     // Browser manages pending state as decorations, so its doc-updates lack pendingStatus.
     // Without this, browser overwrites server state and pending info is lost on next save.
@@ -291,13 +300,11 @@ export function onChanges(listener) {
 // ============================================================================
 // generateNodeId imported from helpers.ts
 /**
- * Find a node by ID in the document tree.
- * Returns the parent array and index for in-place mutation.
+ * Find a node by ID in any document tree.
+ * topLevel is used to resolve the "end" sentinel.
  */
-function findNodeInDoc(nodes, id) {
-    // Special sentinel: "end" resolves to the last top-level node in the document
+function findNode(nodes, id, topLevel) {
     if (id === 'end') {
-        const topLevel = state.document.content;
         if (topLevel && topLevel.length > 0) {
             return { parent: topLevel, index: topLevel.length - 1 };
         }
@@ -308,36 +315,43 @@ function findNodeInDoc(nodes, id) {
             return { parent: nodes, index: i };
         }
         if (nodes[i].content && Array.isArray(nodes[i].content)) {
-            const result = findNodeInDoc(nodes[i].content, id);
+            const result = findNode(nodes[i].content, id, topLevel);
             if (result)
                 return result;
         }
     }
     return null;
 }
+/** Find a node in the active document. */
+function findNodeInDoc(nodes, id) {
+    return findNode(nodes, id, state.document.content);
+}
 /**
- * Apply changes to server-side document and return processed changes
- * with server-assigned IDs for broadcast to browsers.
+ * Core change application logic — operates on any document object.
+ * Mutates doc in place and returns processed changes with server-assigned IDs.
  */
-function applyChangesToDocument(changes) {
+function applyChangesToDoc(doc, changes) {
     const processed = [];
     for (const change of changes) {
         if (change.operation === 'rewrite' && change.nodeId && change.content) {
-            const found = findNodeInDoc(state.document.content, change.nodeId);
+            const found = findNode(doc.content, change.nodeId, doc.content);
             if (!found)
                 continue;
             const contentArray = Array.isArray(change.content) ? change.content : [change.content];
             const originalNode = structuredClone(found.parent[found.index]);
+            // Empty node rewrite → treat as insert (green, not blue)
+            const originalText = extractText(originalNode.content || []);
+            const isEmptyNode = !originalText.trim();
             // Only store original on first rewrite (preserve baseline for reject)
             const existingOriginal = found.parent[found.index].attrs?.pendingOriginalContent;
-            // First node replaces the target (rewrite)
+            // First node replaces the target (rewrite or insert if empty)
             const firstNode = {
                 ...contentArray[0],
                 attrs: {
                     ...contentArray[0].attrs,
                     id: change.nodeId,
-                    pendingStatus: 'rewrite',
-                    pendingOriginalContent: existingOriginal || originalNode,
+                    pendingStatus: isEmptyNode ? 'insert' : 'rewrite',
+                    ...(isEmptyNode ? {} : { pendingOriginalContent: existingOriginal || originalNode }),
                 },
             };
             // Additional nodes get inserted after as pending inserts
@@ -367,17 +381,20 @@ function applyChangesToDocument(changes) {
             }));
             // Mark leaf blocks as pending (not containers) for correct serialization
             markLeafBlocksAsPending(contentWithIds, 'insert');
+            let resolvedAfterId;
             if (change.nodeId && !change.afterNodeId) {
                 // Replace empty node
-                const found = findNodeInDoc(state.document.content, change.nodeId);
+                const found = findNode(doc.content, change.nodeId, doc.content);
                 if (!found)
                     continue;
                 found.parent.splice(found.index, 1, ...contentWithIds);
             }
             else if (change.afterNodeId) {
-                const found = findNodeInDoc(state.document.content, change.afterNodeId);
+                const found = findNode(doc.content, change.afterNodeId, doc.content);
                 if (!found)
                     continue;
+                // Resolve "end" sentinel to actual node ID so browser can find it
+                resolvedAfterId = found.parent[found.index]?.attrs?.id;
                 found.parent.splice(found.index + 1, 0, ...contentWithIds);
             }
             else {
@@ -386,11 +403,13 @@ function applyChangesToDocument(changes) {
             // Broadcast with server-assigned IDs so browser uses the same IDs
             processed.push({
                 ...change,
+                // Replace "end" with the resolved node ID so browser can look it up
+                ...(resolvedAfterId && change.afterNodeId === 'end' ? { afterNodeId: resolvedAfterId } : {}),
                 content: contentWithIds.length === 1 ? contentWithIds[0] : contentWithIds,
             });
         }
         else if (change.operation === 'delete' && change.nodeId) {
-            const found = findNodeInDoc(state.document.content, change.nodeId);
+            const found = findNode(doc.content, change.nodeId, doc.content);
             if (!found)
                 continue;
             found.parent[found.index] = {
@@ -403,6 +422,11 @@ function applyChangesToDocument(changes) {
             processed.push(change);
         }
     }
+    return processed;
+}
+/** Apply changes to the active document singleton. */
+function applyChangesToDocument(changes) {
+    const processed = applyChangesToDoc(state.document, changes);
     if (processed.length > 0) {
         state.lastModified = new Date();
     }
@@ -471,6 +495,15 @@ export function updatePendingCacheForActiveDoc() {
 export function removePendingCacheEntry(filename) {
     pendingDocCache.delete(filename);
 }
+/** Set the pending cache entry for a specific filename (for non-active doc population). */
+export function setPendingCacheEntry(filename, count) {
+    if (count > 0) {
+        pendingDocCache.set(filename, count);
+    }
+    else {
+        pendingDocCache.delete(filename);
+    }
+}
 /** Populate the pending cache from a full disk scan. Called once on startup. */
 function populatePendingCache() {
     pendingDocCache.clear();
@@ -502,6 +535,67 @@ function populatePendingCache() {
         catch { /* skip unreadable files */ }
     }
 }
+const docCache = new Map(); // key = filePath
+/** Cache the active document's full state, keyed by filePath. Call after save(). */
+export function cacheActiveDocument() {
+    if (!state.filePath)
+        return;
+    let fileMtime = 0;
+    try {
+        fileMtime = statSync(state.filePath).mtimeMs;
+    }
+    catch { /* file may not exist yet */ }
+    docCache.set(state.filePath, {
+        document: structuredClone(state.document),
+        metadata: structuredClone(state.metadata),
+        title: state.title,
+        isTemp: state.isTemp,
+        lastModified: state.lastModified,
+        docId: state.docId,
+        fileMtime,
+    });
+}
+/** Get a cached document if the file hasn't been modified externally. Returns null on miss or stale. */
+export function getCachedDocument(filePath) {
+    const cached = docCache.get(filePath);
+    if (!cached)
+        return null;
+    try {
+        const currentMtime = statSync(filePath).mtimeMs;
+        if (currentMtime !== cached.fileMtime) {
+            // File changed on disk — invalidate cache
+            docCache.delete(filePath);
+            return null;
+        }
+    }
+    catch {
+        // File doesn't exist or can't be read — invalidate
+        docCache.delete(filePath);
+        return null;
+    }
+    return cached;
+}
+/** Remove a specific file from the document cache. */
+export function invalidateDocCache(filePath) {
+    docCache.delete(filePath);
+}
+/** Update the cache entry for a file after writing changes (without cloning the active state). */
+function updateCacheEntry(filePath, doc, title, metadata, isTemp, docId) {
+    let fileMtime = 0;
+    try {
+        fileMtime = statSync(filePath).mtimeMs;
+    }
+    catch { /* best-effort */ }
+    docCache.set(filePath, {
+        document: structuredClone(doc),
+        metadata: structuredClone(metadata),
+        title,
+        isTemp,
+        lastModified: new Date(),
+        docId,
+        fileMtime,
+    });
+}
 // ============================================================================
 // PENDING DOCUMENT STORE OPERATIONS
 // ============================================================================
@@ -567,10 +661,20 @@ export function markAllNodesAsPending(doc, status) {
 export function getPendingDocInfo() {
     const filenames = [];
     const counts = {};
+    const stale = [];
     for (const [filename, count] of pendingDocCache) {
+        // Validate file still exists on disk (prunes ghost entries after server restart)
+        const filePath = isExternalDoc(filename) ? filename : join(DATA_DIR, filename);
+        if (!existsSync(filePath)) {
+            stale.push(filename);
+            continue;
+        }
         filenames.push(filename);
         counts[filename] = count;
     }
+    // Clean up stale entries
+    for (const f of stale)
+        pendingDocCache.delete(f);
     return { filenames, counts };
 }
 // ============================================================================
@@ -601,7 +705,7 @@ function writeToDisk() {
             catch { /* stat failed, proceed with save */ }
         }
     }
-    writeFileSync(state.filePath, markdown, 'utf-8');
+    atomicWriteFileSync(state.filePath, markdown);
     // Best-effort version snapshot — never blocks saves
     try {
         snapshotIfNeeded(state.docId, state.filePath);
@@ -661,7 +765,7 @@ export function load() {
             state.docId = ensureDocId(state.metadata);
             if (!hadDocId) {
                 const md = tiptapToMarkdown(state.document, state.title, state.metadata);
-                writeFileSync(state.filePath, md, 'utf-8');
+                atomicWriteFileSync(state.filePath, md);
             }
             break;
         }
@@ -770,7 +874,11 @@ function cleanupEmptyTempFiles() {
             try {
                 const raw = readFileSync(fullPath, 'utf-8');
                 const parsed = markdownToTiptap(raw);
-                if (isDocEmpty(parsed.document)) {
+                // Keep temp files that have meaningful metadata (templates, pending changes, tags)
+                const meta = parsed.metadata || {};
+                const hasMetadata = meta.tweetContext || meta.articleContext || meta.pending || meta.agentCreated
+                    || (Array.isArray(meta.tags) && meta.tags.length > 0);
+                if (isDocEmpty(parsed.document) && !hasMetadata) {
                     unlinkSync(fullPath);
                 }
             }
@@ -841,7 +949,7 @@ export function addDocTag(filename, tag) {
                 tags.push(tag);
                 parsed.metadata.tags = tags;
                 const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
-                writeFileSync(targetPath, markdown, 'utf-8');
+                atomicWriteFileSync(targetPath, markdown);
             }
         }
         catch { /* best-effort */ }
@@ -874,7 +982,7 @@ export function removeDocTag(filename, tag) {
                 tags.splice(idx, 1);
                 parsed.metadata.tags = tags.length > 0 ? tags : undefined;
                 const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
-                writeFileSync(targetPath, markdown, 'utf-8');
+                atomicWriteFileSync(targetPath, markdown);
             }
         }
         catch { /* best-effort */ }
@@ -899,7 +1007,7 @@ export function saveDocToFile(filename, doc) {
             transferPendingAttrs(parsed.document, doc);
         }
         const markdown = tiptapToMarkdown(doc, parsed.title, parsed.metadata);
-        writeFileSync(targetPath, markdown, 'utf-8');
+        atomicWriteFileSync(targetPath, markdown);
     }
     catch { /* best-effort */ }
 }
@@ -933,8 +1041,144 @@ export function stripPendingAttrsFromFile(filename, clearAgentCreated) {
             delete parsed.metadata.agentCreated;
         }
         const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
-        writeFileSync(targetPath, markdown, 'utf-8');
+        atomicWriteFileSync(targetPath, markdown);
         removePendingCacheEntry(filename);
     }
     catch { /* best-effort */ }
 }
+/**
+ * Populate a non-active document file with content.
+ * Writes directly to disk without touching the active singleton.
+ * Returns { title, wordCount, pendingCount } for the response message.
+ */
+/** Count pending nodes in a document tree. */
+function countPending(nodes) {
+    let count = 0;
+    if (!nodes)
+        return 0;
+    for (const node of nodes) {
+        if (node.attrs?.pendingStatus)
+            count++;
+        if (node.content)
+            count += countPending(node.content);
+    }
+    return count;
+}
+/** Write a mutated doc back to disk and update the pending cache. */
+function flushDocToFile(filename, doc, title, metadata) {
+    const targetPath = resolveDocPath(filename);
+    const markdown = tiptapToMarkdown(doc, title, metadata);
+    atomicWriteFileSync(targetPath, markdown);
+    setPendingCacheEntry(filename, countPending(doc.content));
+}
+export function populateDocumentFile(filename, doc) {
+    const targetPath = resolveDocPath(filename);
+    const raw = readFileSync(targetPath, 'utf-8');
+    const parsed = markdownToTiptap(raw);
+    markAllNodesAsPending(doc, 'insert');
+    flushDocToFile(filename, doc, parsed.title, parsed.metadata);
+    const pendingCount = countPending(doc.content);
+    const text = extractText(doc.content);
+    const wordCount = text.trim() ? text.trim().split(/\s+/).length : 0;
+    return { title: parsed.title, wordCount, pendingCount };
+}
+/**
+ * Apply node changes to a non-active document file on disk.
+ * Same logic as applyChanges but without touching the active singleton or broadcasting to browser.
+ */
+export function applyChangesToFile(filename, changes) {
+    const targetPath = resolveDocPath(filename);
+    // Try cache first — preserves stable node IDs
+    const cached = getCachedDocument(targetPath);
+    let doc;
+    let title;
+    let metadata;
+    let docId;
+    let isTemp;
+    if (cached) {
+        doc = structuredClone(cached.document);
+        title = cached.title;
+        metadata = cached.metadata;
+        docId = cached.docId;
+        isTemp = cached.isTemp;
+    }
+    else {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        doc = parsed.document;
+        title = parsed.title;
+        metadata = parsed.metadata;
+        docId = metadata.docId || '';
+        isTemp = false;
+    }
+    const processed = applyChangesToDoc(doc, changes);
+    if (processed.length > 0) {
+        flushDocToFile(filename, doc, title, metadata);
+        updateCacheEntry(targetPath, doc, title, metadata, isTemp, docId);
+    }
+    // Find the last created node ID for chaining inserts
+    let lastNodeId = null;
+    for (let i = processed.length - 1; i >= 0; i--) {
+        const change = processed[i];
+        if (change.content) {
+            const contentArr = Array.isArray(change.content) ? change.content : [change.content];
+            const lastNode = contentArr[contentArr.length - 1];
+            if (lastNode?.attrs?.id) {
+                lastNodeId = lastNode.attrs.id;
+                break;
+            }
+        }
+    }
+    return { count: processed.length, lastNodeId };
+}
+/**
+ * Apply fine-grained text edits to a node in a non-active document file on disk.
+ */
+export function applyTextEditsToFile(filename, nodeId, edits) {
+    const targetPath = resolveDocPath(filename);
+    // Try cache first — preserves stable node IDs
+    const cached = getCachedDocument(targetPath);
+    let doc;
+    let title;
+    let metadata;
+    let docId;
+    let isTemp;
+    if (cached) {
+        doc = structuredClone(cached.document);
+        title = cached.title;
+        metadata = cached.metadata;
+        docId = cached.docId;
+        isTemp = cached.isTemp;
+    }
+    else {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        doc = parsed.document;
+        title = parsed.title;
+        metadata = parsed.metadata;
+        docId = metadata.docId || '';
+        isTemp = false;
+    }
+    const found = findNode(doc.content, nodeId, doc.content);
+    if (!found)
+        return { success: false, error: `Node ${nodeId} not found` };
+    const originalNode = found.parent[found.index];
+    const result = applyTextEditsToNode(originalNode, edits);
+    if (!result)
+        return { success: false, error: 'No edits matched' };
+    result.node.attrs = {
+        ...result.node.attrs,
+        pendingTextEdits: result.textEdits,
+    };
+    // Apply as a rewrite to the doc
+    const processed = applyChangesToDoc(doc, [{
+            operation: 'rewrite',
+            nodeId,
+            content: result.node,
+        }]);
+    if (processed.length > 0) {
+        flushDocToFile(filename, doc, title, metadata);
+        updateCacheEntry(targetPath, doc, title, metadata, isTemp, docId);
+    }
+    return { success: true };
+}

package/dist/server/workspace-routes.js

@@ -3,7 +3,7 @@
  * Mounted in index.ts to keep the main file lean.
  */
 import { Router } from 'express';
-import { listWorkspaces, getWorkspace, createWorkspace, deleteWorkspace, reorderWorkspaces, addDoc, removeDoc, moveDoc, reorderDoc, addContainerToWorkspace, removeContainer, renameContainer, reorderContainer, } from './workspaces.js';
+import { listWorkspaces, getWorkspace, createWorkspace, deleteWorkspace, reorderWorkspaces, addDoc, removeDoc, moveDoc, reorderDoc, addContainerToWorkspace, removeContainer, renameContainer, renameWorkspace, reorderContainer, } from './workspaces.js';
 export function createWorkspaceRouter(b) {
     const router = Router();
     router.get('/api/workspaces', (_req, res) => {
@@ -30,6 +30,16 @@ export function createWorkspaceRouter(b) {
             res.status(404).json({ error: err.message });
         }
     });
+    router.put('/api/workspaces/:filename', (req, res) => {
+        try {
+            const ws = renameWorkspace(req.params.filename, req.body.title);
+            b.broadcastWorkspacesChanged();
+            res.json(ws);
+        }
+        catch (err) {
+            res.status(400).json({ error: err.message });
+        }
+    });
     router.delete('/api/workspaces/:filename', async (req, res) => {
         try {
             await deleteWorkspace(req.params.filename);

package/dist/server/workspaces.js

@@ -234,6 +234,12 @@ export function renameContainer(wsFile, containerId, name) {
     writeWorkspace(wsFile, ws);
     return ws;
 }
+export function renameWorkspace(wsFile, newTitle) {
+    const ws = getWorkspace(wsFile);
+    ws.title = newTitle;
+    writeWorkspace(wsFile, ws);
+    return ws;
+}
 export function reorderContainer(wsFile, containerId, afterIdentifier) {
     const ws = getWorkspace(wsFile);
     reorderNode(ws.root, containerId, afterIdentifier);

package/dist/server/ws.js

@@ -27,7 +27,23 @@ function debouncedBroadcastDocumentsChanged() {
     }, 2100);
 }
 export function setupWebSocket(server) {
-    const wss = new WebSocketServer({ server });
+    const wss = new WebSocketServer({
+        server,
+        verifyClient: ({ req }) => {
+            const origin = req.headers.origin;
+            // Allow connections with no origin (non-browser clients like MCP)
+            // and localhost origins only (blocks cross-site WebSocket hijacking)
+            if (!origin)
+                return true;
+            try {
+                const url = new URL(origin);
+                return url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+            }
+            catch {
+                return false;
+            }
+        },
+    });
     // Push agent changes to all browser clients
     onChanges((changes) => {
         const msg = JSON.stringify({ type: 'node-changes', changes });
@@ -126,20 +142,29 @@ export function setupWebSocket(server) {
                     try {
                         const tmpl = msg.template;
                         const url = msg.url;
-                        // Create with no title → temp file path (avoids naming conflicts)
-                        const result = createDocument();
-                        // Set template-appropriate metadata
+                        // Create named document (dedup handles collisions)
+                        let title = 'Untitled';
+                        if (tmpl === 'tweet')
+                            title = 'Tweet';
+                        else if (tmpl === 'reply')
+                            title = 'Reply';
+                        else if (tmpl === 'quote')
+                            title = 'Quote Tweet';
+                        else if (tmpl === 'article')
+                            title = 'Article';
+                        const result = createDocument(title);
+                        // Set template-specific metadata
                         if (tmpl === 'tweet') {
-                            setMetadata({ tweetContext: { mode: 'tweet' }, title: 'Tweet' });
+                            setMetadata({ tweetContext: { mode: 'tweet' } });
                         }
                         else if (tmpl === 'reply') {
-                            setMetadata({ tweetContext: { url, mode: 'reply' }, title: 'Reply' });
+                            setMetadata({ tweetContext: { url, mode: 'reply' } });
                         }
                         else if (tmpl === 'quote') {
-                            setMetadata({ tweetContext: { url, mode: 'quote' }, title: 'Quote Tweet' });
+                            setMetadata({ tweetContext: { url, mode: 'quote' } });
                         }
                         else if (tmpl === 'article') {
-                            setMetadata({ articleContext: { active: true }, title: 'Article' });
+                            setMetadata({ articleContext: { active: true } });
                         }
                         save();
                         broadcastDocumentSwitched(result.document, getTitle(), result.filename, getMetadata());
@@ -186,6 +211,7 @@ export function setupWebSocket(server) {
                         }
                         stripPendingAttrs();
                         save();
+                        updatePendingCacheForActiveDoc(); // Sync cache after strip (prevents stale "has changes" indicator)
                     }
                     else {
                         // Race path: resolved doc is NOT the active one (server switched away).
@@ -206,7 +232,8 @@ export function setupWebSocket(server) {
     });
 }
 export function broadcastDocumentSwitched(document, title, filename, metadata) {
-    const msg = JSON.stringify({ type: 'document-switched', document, title, filename, docId: getDocId(), metadata: metadata ?? getMetadata() });
+    const resolvedMeta = metadata ?? getMetadata();
+    const msg = JSON.stringify({ type: 'document-switched', document, title, filename, docId: getDocId(), metadata: resolvedMeta });
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN) {
             ws.send(msg);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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",

package/skill/SKILL.md

@@ -3,7 +3,7 @@ name: openwriter
 description: |
   OpenWriter — the writing surface for AI agents. A markdown-native rich text
   editor where agents write via MCP tools and users accept or reject changes
-  in-browser. 30 MCP tools for document editing, multi-doc workspaces, and
+  in-browser. 31 MCP tools for document editing, multi-doc workspaces, and
   organization. Tweet compose mode for drafting replies/QTs with pixel-accurate
   X/Twitter UI. Plain .md files on disk — no database, no lock-in.
 
@@ -14,7 +14,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.4.0"
+  version: "0.5.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -38,7 +38,7 @@ Skip to [Writing Strategy](#writing-strategy) below.
 
 ### MCP tools are NOT available (skill-first install)
 
-The user installed this skill from a directory but hasn't set up the MCP server yet. OpenWriter needs an MCP server to provide the 30 editing tools.
+The user installed this skill from a directory but hasn't set up the MCP server yet. OpenWriter needs an MCP server to provide the 31 editing tools.
 
 **Step 1:** Tell the user to install globally and add the MCP server:
 
@@ -123,6 +123,7 @@ After editing, tell the user:
 | `tag_doc` | Add a tag to a document (stored in doc frontmatter) |
 | `untag_doc` | Remove a tag from a document (stored in doc frontmatter) |
 | `move_doc` | Move a document to a different container or root level |
+| `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
 ### Text Operations
 
@@ -134,7 +135,7 @@ After editing, tell the user:
 
 | Tool | Description |
 |------|-------------|
-| `generate_image` | Generate an image via Gemini Imagen 4 — optionally set as article cover (requires GEMINI_API_KEY) |
+| `generate_image` | Generate an image via Gemini Nano Banana 2 — optionally set as article cover (requires GEMINI_API_KEY) |
 
 ### Version Management
 
@@ -153,7 +154,7 @@ OpenWriter has two distinct modes: **editing** existing documents and **creating
 
 For making changes to existing documents — rewrites, insertions, deletions:
 
-- Use `write_to_pad` for all edits
+- Use `write_to_pad` for all edits — **`filename` is required**
 - Send **3-8 changes per call** for a responsive, streaming feel
 - Always `read_pad` before editing to get fresh node IDs
 - Respect `pendingChanges > 0` — wait for the user to accept/reject before sending more
@@ -202,7 +203,7 @@ This eliminates the need for separate `create_workspace`, `create_container`, an
 ```
 1. get_pad_status  → check pendingChanges and userSignaledReview
 2. read_pad        → get full document with node IDs
-3. write_to_pad    → send changes (3-8 per call)
+3. write_to_pad({ filename: "Doc.md", changes: [...] })
 4. Wait            → user accepts/rejects in browser
 ```
 
@@ -210,9 +211,9 @@ This eliminates the need for separate `create_workspace`, `create_container`, an
 
 ```
 1. list_documents    → see all docs, find target
-2. switch_document   → save current, load target (returns content)
-3. read_pad          → read full content with node IDs
-4. write_to_pad      → apply edits
+2. read_pad          → read active doc (or switch_document first)
+3. write_to_pad({ filename: "Target.md", changes: [...] })
+                     → edits go to the named file, no view switch needed
 ```
 
 ### Creating new content (two-step)