openwriter 0.5.5 → 0.6.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, atomicWriteFileSync } from './helpers.js';
+import { getDataDir, 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',
@@ -27,18 +27,18 @@ const listeners = new Set();
 // ============================================================================
 // EXTERNAL DOCUMENT REGISTRY
 // ============================================================================
-const EXTERNAL_DOCS_FILE = join(DATA_DIR, 'external-docs.json');
+function getExternalDocsFile() { return join(getDataDir(), 'external-docs.json'); }
 const externalDocs = new Set();
 function persistExternalDocs() {
     try {
-        atomicWriteFileSync(EXTERNAL_DOCS_FILE, JSON.stringify([...externalDocs]));
+        atomicWriteFileSync(getExternalDocsFile(), JSON.stringify([...externalDocs]));
     }
     catch { /* best-effort */ }
 }
 function loadExternalDocs() {
     try {
-        if (existsSync(EXTERNAL_DOCS_FILE)) {
-            const paths = JSON.parse(readFileSync(EXTERNAL_DOCS_FILE, 'utf-8'));
+        if (existsSync(getExternalDocsFile())) {
+            const paths = JSON.parse(readFileSync(getExternalDocsFile(), 'utf-8'));
             for (const p of paths) {
                 if (existsSync(p))
                     externalDocs.add(p);
@@ -125,34 +125,65 @@ export function getPendingChangeCount() {
 }
 export function getNodesByIds(ids) {
     const result = [];
+    const idSet = new Set(ids);
     function scan(nodes) {
         if (!nodes)
             return;
-        for (const node of nodes) {
-            if (node.attrs?.id && ids.includes(node.attrs.id)) {
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            if (node.attrs?.id && idSet.has(node.attrs.id)) {
                 result.push(node);
+                // Preserve horizontalRule separators between matched nodes (thread structure)
+                if (i + 1 < nodes.length && nodes[i + 1].type === 'horizontalRule') {
+                    result.push(nodes[i + 1]);
+                }
             }
             if (node.content)
                 scan(node.content);
         }
     }
     scan(state.document.content);
+    // Remove trailing horizontalRule (don't end with separator)
+    if (result.length > 0 && result[result.length - 1].type === 'horizontalRule') {
+        result.pop();
+    }
     return result;
 }
 export function getMetadata() {
     return state.metadata;
 }
 export function setMetadata(updates) {
+    // Prevent blogContext contamination: only allow blogContext writes if
+    // the incoming update has active:true OR the doc already has active blogContext
+    if (updates.blogContext && !updates.blogContext.active && !state.metadata?.blogContext?.active) {
+        delete updates.blogContext;
+        if (Object.keys(updates).length === 0)
+            return;
+    }
+    // Same guard for newsletterContext
+    if (updates.newsletterContext && !updates.newsletterContext.active && !state.metadata?.newsletterContext?.active) {
+        delete updates.newsletterContext;
+        if (Object.keys(updates).length === 0)
+            return;
+    }
+    // Deep-merge known context objects so partial updates preserve essential fields (active, format, etc.)
+    const CONTEXT_KEYS = ['blogContext', 'newsletterContext', 'articleContext', 'tweetContext', 'linkedinContext'];
+    for (const key of CONTEXT_KEYS) {
+        if (updates[key] && typeof updates[key] === 'object' && state.metadata?.[key] && typeof state.metadata[key] === 'object') {
+            updates[key] = { ...state.metadata[key], ...updates[key] };
+        }
+    }
     state.metadata = { ...state.metadata, ...updates };
     if (updates.title)
         state.title = updates.title;
-    // Auto-tag: tweetContext / articleContext ↔ "x" + mode tag
-    for (const key of ['tweetContext', 'articleContext']) {
-        if (key in updates) {
-            const filename = state.filePath
-                ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
-                : '';
-            if (filename) {
+    // Auto-tag based on context metadata
+    const filename = state.filePath
+        ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
+        : '';
+    if (filename) {
+        // tweetContext / articleContext → "x" + mode tag
+        for (const key of ['tweetContext', 'articleContext']) {
+            if (key in updates) {
                 if (updates[key]) {
                     addDocTag(filename, 'x');
                     const mode = updates[key]?.mode || (key === 'articleContext' ? 'article' : undefined);
@@ -164,6 +195,20 @@ export function setMetadata(updates) {
                 }
             }
         }
+        // blogContext / linkedinContext / newsletterContext → single tag
+        const contextTags = {
+            blogContext: 'blog',
+            linkedinContext: 'linkedin',
+            newsletterContext: 'newsletter',
+        };
+        for (const [key, tag] of Object.entries(contextTags)) {
+            if (key in updates) {
+                if (updates[key])
+                    addDocTag(filename, tag);
+                else
+                    removeDocTag(filename, tag);
+            }
+        }
     }
 }
 export function getStatus() {
@@ -187,61 +232,85 @@ export function updateDocument(doc) {
         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.
-    if (hasPendingChanges()) {
+    // Preserve pending attrs from server state → incoming browser doc.
+    // The browser's PendingAttributes extension tracks pendingStatus in the TipTap
+    // document model, but transferPendingAttrs provides a safety net in case the
+    // browser's doc-update lost them (e.g. timing edge case, stale transaction).
+    const serverHadPending = hasPendingChanges();
+    if (serverHadPending) {
         transferPendingAttrs(state.document, doc);
     }
     state.document = doc;
     state.lastModified = new Date();
+    // Validate: if server had pending changes, verify they survived the transfer
+    if (serverHadPending && !hasPendingChanges()) {
+        console.error('[State] WARNING: pending changes lost after updateDocument — browser doc-update overwrote pending attrs');
+    }
 }
 /**
  * Transfer pending attrs from source doc to target doc by matching node IDs.
- * Copies pendingStatus, pendingOriginalContent, and pendingTextEdits.
+ * Copies all pending-related attrs: status, original content, group ID,
+ * selection ranges, and text edits.
  */
 function transferPendingAttrs(source, target) {
-    // Build a map of nodeId → pending attrs from source
+    // Build a map of nodeId → all pending attrs from source
     const pendingMap = new Map();
     function collectPending(nodes) {
         if (!nodes)
             return;
         for (const node of nodes) {
             if (node.attrs?.pendingStatus && node.attrs?.id) {
-                pendingMap.set(node.attrs.id, {
-                    status: node.attrs.pendingStatus,
-                    original: node.attrs.pendingOriginalContent,
-                    textEdits: node.attrs.pendingTextEdits,
-                });
+                const entry = {
+                    pendingStatus: node.attrs.pendingStatus,
+                };
+                // Copy all pending-related attrs if present
+                if (node.attrs.pendingOriginalContent != null)
+                    entry.pendingOriginalContent = node.attrs.pendingOriginalContent;
+                if (node.attrs.pendingTextEdits != null)
+                    entry.pendingTextEdits = node.attrs.pendingTextEdits;
+                if (node.attrs.pendingGroupId != null)
+                    entry.pendingGroupId = node.attrs.pendingGroupId;
+                if (node.attrs.pendingSelectionFrom != null)
+                    entry.pendingSelectionFrom = node.attrs.pendingSelectionFrom;
+                if (node.attrs.pendingSelectionTo != null)
+                    entry.pendingSelectionTo = node.attrs.pendingSelectionTo;
+                if (node.attrs.pendingOriginalFrom != null)
+                    entry.pendingOriginalFrom = node.attrs.pendingOriginalFrom;
+                if (node.attrs.pendingOriginalTo != null)
+                    entry.pendingOriginalTo = node.attrs.pendingOriginalTo;
+                pendingMap.set(node.attrs.id, entry);
             }
             if (node.content)
                 collectPending(node.content);
         }
     }
     collectPending(source.content);
+    if (pendingMap.size === 0)
+        return;
     // Apply pending attrs to matching nodes in target
+    let transferred = 0;
     function applyPending(nodes) {
         if (!nodes)
             return;
         for (const node of nodes) {
             if (node.attrs?.id && pendingMap.has(node.attrs.id)) {
                 const p = pendingMap.get(node.attrs.id);
-                node.attrs.pendingStatus = p.status;
-                if (p.original)
-                    node.attrs.pendingOriginalContent = p.original;
-                if (p.textEdits)
-                    node.attrs.pendingTextEdits = p.textEdits;
+                Object.assign(node.attrs, p);
+                transferred++;
             }
             if (node.content)
                 applyPending(node.content);
         }
     }
     applyPending(target.content);
+    if (transferred < pendingMap.size) {
+        console.warn(`[State] transferPendingAttrs: ${transferred}/${pendingMap.size} nodes matched — ${pendingMap.size - transferred} pending nodes missing in target doc`);
+    }
 }
 // ============================================================================
 // AGENT WRITE LOCK
 // ============================================================================
-const AGENT_LOCK_MS = 1500; // Block browser doc-updates for 1.5s after agent write
+const AGENT_LOCK_MS = 3000; // Block browser doc-updates for 3s after agent write
 let lastAgentWriteTime = 0;
 /** Set the agent write lock (called after agent changes). */
 export function setAgentLock() {
@@ -514,10 +583,10 @@ export function setPendingCacheEntry(filename, count) {
 function populatePendingCache() {
     pendingDocCache.clear();
     try {
-        const files = readdirSync(DATA_DIR).filter((f) => f.endsWith('.md'));
+        const files = readdirSync(getDataDir()).filter((f) => f.endsWith('.md'));
         for (const f of files) {
             try {
-                const raw = readFileSync(join(DATA_DIR, f), 'utf-8');
+                const raw = readFileSync(join(getDataDir(), f), 'utf-8');
                 const { data } = matter(raw);
                 if (data.pending && Object.keys(data.pending).length > 0) {
                     pendingDocCache.set(f, Object.keys(data.pending).length);
@@ -602,6 +671,21 @@ function updateCacheEntry(filePath, doc, title, metadata, isTemp, docId) {
         fileMtime,
     });
 }
+/** Reset all in-memory caches. Called on profile switch. */
+export function clearAllCaches() {
+    docCache.clear();
+    pendingDocCache.clear();
+    externalDocs.clear();
+    state = {
+        document: DEFAULT_DOC,
+        title: 'Untitled',
+        metadata: { title: 'Untitled' },
+        filePath: '',
+        isTemp: true,
+        lastModified: new Date(),
+        docId: '',
+    };
+}
 // ============================================================================
 // PENDING DOCUMENT STORE OPERATIONS
 // ============================================================================
@@ -670,7 +754,7 @@ export function getPendingDocInfo() {
     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);
+        const filePath = isExternalDoc(filename) ? filename : join(getDataDir(), filename);
         if (!existsSync(filePath)) {
             stale.push(filename);
             continue;
@@ -742,10 +826,10 @@ export function load() {
     // Clean up empty temp files from previous sessions
     cleanupEmptyTempFiles();
     // Find most recently modified .md file
-    const files = readdirSync(DATA_DIR)
+    const files = readdirSync(getDataDir())
         .filter((f) => f.endsWith('.md'))
         .map((f) => {
-        const fullPath = join(DATA_DIR, f);
+        const fullPath = join(getDataDir(), f);
         const stat = statSync(fullPath);
         return { name: f, path: fullPath, mtime: stat.mtimeMs };
     })
@@ -795,11 +879,11 @@ export function load() {
 /** Migrate legacy .sw.json files to .md format */
 function migrateSwJsonFiles() {
     try {
-        const jsonFiles = readdirSync(DATA_DIR).filter((f) => f.endsWith('.sw.json'));
+        const jsonFiles = readdirSync(getDataDir()).filter((f) => f.endsWith('.sw.json'));
         for (const f of jsonFiles) {
-            const jsonPath = join(DATA_DIR, f);
+            const jsonPath = join(getDataDir(), f);
             const mdName = f.replace(/\.sw\.json$/, '.md');
-            const mdPath = join(DATA_DIR, mdName);
+            const mdPath = join(getDataDir(), mdName);
             // Skip if .md already exists
             if (existsSync(mdPath)) {
                 try {
@@ -834,7 +918,7 @@ function migrateSwJsonFiles() {
 function getWorkspaceReferencedFiles() {
     const referenced = new Set();
     try {
-        const wsDir = join(DATA_DIR, '_workspaces');
+        const wsDir = join(getDataDir(), '_workspaces');
         if (!existsSync(wsDir))
             return referenced;
         const manifests = readdirSync(wsDir).filter((f) => f.endsWith('.json'));
@@ -871,12 +955,12 @@ function getWorkspaceReferencedFiles() {
 function cleanupEmptyTempFiles() {
     try {
         const wsRefs = getWorkspaceReferencedFiles();
-        const files = readdirSync(DATA_DIR).filter((f) => f.startsWith(TEMP_PREFIX) && f.endsWith('.md'));
+        const files = readdirSync(getDataDir()).filter((f) => f.startsWith(TEMP_PREFIX) && f.endsWith('.md'));
         for (const f of files) {
             // Never delete temp files that are referenced by a workspace
             if (wsRefs.has(f))
                 continue;
-            const fullPath = join(DATA_DIR, f);
+            const fullPath = join(getDataDir(), f);
             try {
                 const raw = readFileSync(fullPath, 'utf-8');
                 const parsed = markdownToTiptap(raw);

package/dist/server/versions.js

@@ -6,7 +6,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
-import { VERSIONS_DIR } from './helpers.js';
+import { getVersionsDir } from './helpers.js';
 import { markdownToTiptap } from './markdown.js';
 // ============================================================================
 // DEDUP STATE
@@ -16,6 +16,10 @@ const MIN_INTERVAL_MS = 30_000; // 30 seconds between snapshots of same content
 function contentHash(markdown) {
     return createHash('sha256').update(markdown).digest('hex').slice(0, 16);
 }
+/** Clear dedup state. Called on profile switch. */
+export function clearVersionsCache() {
+    lastSnapshot.clear();
+}
 // ============================================================================
 // DOC ID
 // ============================================================================
@@ -38,7 +42,7 @@ export function ensureDocId(metadata) {
 // SNAPSHOT
 // ============================================================================
 function docDir(docId) {
-    return join(VERSIONS_DIR, docId);
+    return join(getVersionsDir(), docId);
 }
 function ensureDocDir(docId) {
     const dir = docDir(docId);

package/dist/server/workspaces.js

@@ -8,16 +8,16 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import matter from 'gray-matter';
 import trash from 'trash';
-import { WORKSPACES_DIR, ensureWorkspacesDir, sanitizeFilename, resolveDocPath, isExternalDoc } from './helpers.js';
+import { getWorkspacesDir, ensureWorkspacesDir, sanitizeFilename, resolveDocPath, isExternalDoc } from './helpers.js';
 import { markdownToTiptap, tiptapToMarkdown } from './markdown.js';
-const ORDER_FILE = join(WORKSPACES_DIR, '_order.json');
+function getOrderFile() { return join(getWorkspacesDir(), '_order.json'); }
 import { isV1, migrateV1toV2 } from './workspace-types.js';
 import { addDocToContainer, addContainer as addContainerToTree, removeNode, moveNode, reorderNode, findContainer, collectAllFiles, countDocs, findDocNode } from './workspace-tree.js';
 // ============================================================================
 // INTERNAL HELPERS
 // ============================================================================
 function workspacePath(filename) {
-    return join(WORKSPACES_DIR, filename);
+    return join(getWorkspacesDir(), filename);
 }
 /**
  * Migrate workspace-level tags into document frontmatter.
@@ -75,16 +75,16 @@ function writeWorkspace(filename, workspace) {
 }
 function readOrder() {
     try {
-        if (!existsSync(ORDER_FILE))
+        if (!existsSync(getOrderFile()))
             return [];
-        return JSON.parse(readFileSync(ORDER_FILE, 'utf-8'));
+        return JSON.parse(readFileSync(getOrderFile(), 'utf-8'));
     }
     catch {
         return [];
     }
 }
 function writeOrder(order) {
-    writeFileSync(ORDER_FILE, JSON.stringify(order, null, 2), 'utf-8');
+    writeFileSync(getOrderFile(), JSON.stringify(order, null, 2), 'utf-8');
 }
 function readDocFrontmatter(filename) {
     try {
@@ -104,7 +104,7 @@ function readDocFrontmatter(filename) {
 // ============================================================================
 export function listWorkspaces() {
     ensureWorkspacesDir();
-    const files = readdirSync(WORKSPACES_DIR).filter((f) => f.endsWith('.json') && f !== '_order.json');
+    const files = readdirSync(getWorkspacesDir()).filter((f) => f.endsWith('.json') && f !== '_order.json');
     const infos = files.map((f) => {
         try {
             const ws = readWorkspace(f);

package/dist/server/ws.js

@@ -160,6 +160,12 @@ export function setupWebSocket(server) {
                             title = 'Quote Tweet';
                         else if (tmpl === 'article')
                             title = 'Article';
+                        else if (tmpl === 'linkedin')
+                            title = 'LinkedIn Post';
+                        else if (tmpl === 'newsletter')
+                            title = 'Newsletter';
+                        else if (tmpl === 'blog')
+                            title = 'Blog Post';
                         const result = createDocument(title);
                         // Set template-specific metadata
                         if (tmpl === 'tweet') {
@@ -174,6 +180,15 @@ export function setupWebSocket(server) {
                         else if (tmpl === 'article') {
                             setMetadata({ articleContext: { active: true } });
                         }
+                        else if (tmpl === 'linkedin') {
+                            setMetadata({ linkedinContext: { active: true } });
+                        }
+                        else if (tmpl === 'newsletter') {
+                            setMetadata({ newsletterContext: { active: true } });
+                        }
+                        else if (tmpl === 'blog') {
+                            setMetadata({ blogContext: { active: true } });
+                        }
                         save();
                         broadcastDocumentSwitched(result.document, getTitle(), result.filename, getMetadata());
                         broadcastDocumentsChanged();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.5.5",
+  "version": "0.6.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,9 +3,10 @@ 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. 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.
+  in-browser. 36 core MCP tools for document editing, multi-doc workspaces,
+  and organization, plus 21 publish platform tools for newsletter, social
+  posting, and scheduling. Tweet compose mode for drafting replies/QTs with
+  pixel-accurate X/Twitter UI. Plain .md files on disk — no database, no lock-in.
 
   Use when user says: "open writer", "openwriter", "write in openwriter",
   "edit my document", "review my writing", "check the pad", "write me a doc",
@@ -14,7 +15,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.1.1"
+  version: "0.2.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -35,30 +36,31 @@ Check whether the `openwriter` MCP tools are available (e.g. `read_pad`, `write_
 
 ### MCP tools ARE available (ready to use)
 
-The user already has OpenWriter configured — either they ran `npx openwriter install-skill` (which installed this skill) and added the MCP server, or they set it up manually. You're good to go.
+The user already has OpenWriter configured. You're good to go.
 
 **First action:** Share the browser URL:
 > OpenWriter is at **http://localhost:5050** — open it in your browser to see and review changes.
 
 Skip to [Writing Strategy](#writing-strategy) below.
 
-### MCP tools are NOT available (skill-first install)
+### MCP tools are NOT available (needs setup)
 
-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.
+The user has this skill but hasn't set up the MCP server yet. One command does everything:
 
-**Step 1:** Tell the user to install globally and add the MCP server:
+```bash
+npx openwriter install-skill
+```
+
+This installs openwriter globally, configures the MCP server for Claude Code, and copies this skill — all in one step. After it finishes, the user just needs to restart their Claude Code session.
+
+**Fallback (if the command above fails):** Do it manually:
 
 ```bash
-# Install globally for instant startup (no npx resolution delay)
 npm install -g openwriter
-
-# Add the OpenWriter MCP server to Claude Code
 claude mcp add -s user openwriter -- openwriter --no-open
 ```
 
-Then restart the Claude Code session. The MCP tools become available on next launch.
-
-**Step 2 (if the user can't run the command above):** Edit `~/.claude.json` directly. Add `openwriter` as the **first entry** in the `mcpServers` object — MCP servers load sequentially, so first in config = first to load:
+If `claude mcp add` can't run (e.g. nested session error), edit `~/.claude.json` directly. Add `openwriter` as the **first entry** in `mcpServers`:
 
 ```json
 {
@@ -71,14 +73,10 @@ Then restart the Claude Code session. The MCP tools become available on next lau
 }
 ```
 
-**Why first?** Claude Code loads MCP servers sequentially in config order. If `openwriter` is last, it waits for every other server to finish connecting first. Putting it first makes it available instantly.
-
-After editing, tell the user:
+After setup, tell the user:
 1. Restart your Claude Code session (MCP servers load on startup)
 2. Open http://localhost:5050 in your browser
 
-**Note:** You cannot run `claude mcp add` from inside a session (nested session error). That's why we edit the JSON directly when configuring from within Claude Code. Also, `claude mcp add` appends to the end — always verify the entry is first after adding.
-
 ## Document Identity: Titles vs DocIds
 
 Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its YAML frontmatter. Titles are for human communication and agent reasoning. DocIds are for agent action.
@@ -87,7 +85,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 - All doc-targeting tools take `docId` as their parameter (not filename)
 - Two documents can have the same title — the docId disambiguates
 
-## MCP Tools Reference (32 tools)
+## MCP Tools Reference (36 core + 21 publish platform)
 
 ### Document Operations
 
@@ -110,6 +108,8 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `create_document` | `title?`, ... | Create a new empty document — response includes docId |
 | `open_file` | `path` | Open an existing .md file from any location on disk |
 | `delete_document` | `docId` | Delete a document file (moves to OS trash, recoverable) |
+| `archive_document` | `docId` | Archive a document (hides from sidebar, keeps on disk) |
+| `unarchive_document` | `docId` | Restore an archived document back to the sidebar |
 
 ### Import
 
@@ -132,11 +132,11 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 
 | Tool | Description |
 |------|-------------|
-| `add_doc` | Add a document to a workspace (optional container placement) |
 | `create_container` | Create a folder inside a workspace (max depth: 3) |
-| `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 |
+| `delete_container` | Delete a container from a workspace (doc files stay on disk) |
+| `tag_doc` | Add a tag to a document by docId (stored in doc frontmatter) |
+| `untag_doc` | Remove a tag from a document by docId |
+| `move_doc` | Add a doc to a workspace, or move it within the workspace (by docId) |
 | `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
 ### Agent Marks
@@ -157,6 +157,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | Tool | Description |
 |------|-------------|
 | `generate_image` | Generate an image via Gemini Nano Banana 2 — optionally set as article cover (requires GEMINI_API_KEY) |
+| `insert_image` | Insert an image into the document at a specific position (from URL or local path) |
 
 ### Version Management
 
@@ -215,7 +216,7 @@ create_document({
 - **`container`** (string) — container name within the workspace (e.g. "Chapters", "Notes", "References"). Auto-creates if not found. Requires `workspace`.
 - Both are optional — omit for standalone docs outside any workspace.
 
-This eliminates the need for separate `create_workspace`, `create_container`, and `add_doc` calls when building up a workspace.
+This eliminates the need for separate `create_workspace`, `create_container`, and `move_doc` calls when building up a workspace.
 
 ## Workflow
 
@@ -370,6 +371,86 @@ Users set their X handle by clicking the avatar circle in the compose area. The
 5. **Respect pending changes.** If `pendingChanges > 0`, wait for the user
 6. **Watch for the review signal.** When `userSignaledReview` is true, the user is asking for your input — reading status clears it (one-shot)
 
+## Publish Platform (21 tools)
+
+Requires authentication via `request_login_code` + `verify_login`. All publish tools are provided by the `@openwriter/plugin-publish` plugin.
+
+### Authentication
+
+| Tool | Description |
+|------|-------------|
+| `request_login_code` | Send a 6-digit login code to an email address (signup or key recovery) |
+| `verify_login` | Verify the code → API key issued + auto-saved to plugin config |
+
+```
+1. request_login_code({ email: "user@example.com" })   → 6-digit code sent to email
+2. User reads code from inbox (or agent reads via gmail skill)
+3. verify_login({ email: "user@example.com", code: "123456" })
+   → API key issued + auto-saved to plugin config
+```
+
+- **Agents with email access** (e.g. gmail skill) can fully automate this — zero user involvement
+- **Key recovery:** Same flow. Old keys are automatically revoked when a new one is issued
+- Codes expire in 10 minutes, max 3 attempts per code, rate-limited to 1 request per 60 seconds
+
+### Custom Domains
+
+| Tool | Description |
+|------|-------------|
+| `setup_custom_domain` | Configure a custom domain + from_email for newsletter sending |
+| `check_domain_status` | Check DNS and sender verification status |
+| `resend_domain_verification` | Re-send the SendGrid sender verification email |
+
+**Setup flow:**
+1. Call `setup_custom_domain` with domain + from_email
+2. Cloudflare domains: DNS auto-added. Non-CF: show DNS records for manual setup
+3. User checks email for SendGrid sender verification
+4. Wait ~30-60s, call `check_domain_status` to confirm
+5. Both `dns_verified` + `sender_verified` = domain ready
+
+### Social Posting & Connections
+
+| Tool | Description |
+|------|-------------|
+| `list_connections` | List connected social accounts (X, LinkedIn, etc.) |
+| `post_to_x` | Post current document to X/Twitter |
+| `post_to_linkedin` | Post current document to LinkedIn |
+
+### Scheduling
+
+| Tool | Description |
+|------|-------------|
+| `schedule_post` | Schedule a post for a specific time |
+| `list_schedule` | List all scheduled posts |
+| `manage_schedule` | Update or cancel a scheduled post |
+| `list_slots` | List recurring time slots |
+| `create_slot` | Create a recurring posting slot |
+| `edit_slot` | Modify an existing slot |
+| `delete_slot` | Remove a recurring slot |
+
+### Newsletter
+
+| Tool | Key Params | Description |
+|------|-----------|-------------|
+| `send_newsletter` | `subject?`, `format?`, `test_email?`, `subscriber_ids?`, `exclude_issue_id?` | Send current document as newsletter to all subscribers, a subset, or a test address |
+| `list_subscribers` | `limit?`, `offset?` | List newsletter subscribers with IDs, emails, names |
+| `add_subscriber` | `email`, `name?` | Add a single subscriber |
+| `import_subscribers` | `file?`, `csv_text?` | Bulk import from CSV (auto-detects ConvertKit, Mailchimp, Substack, Beehiiv formats) |
+| `list_newsletter_issues` | `limit?` | List past sends with open/click stats — returns issue IDs |
+| `get_newsletter_analytics` | `issue_id` | Detailed drill-down: delivery stats, per-subscriber events, recipient list |
+
+**Subscriber selection** — `send_newsletter` supports targeting:
+- **All subscribers** (default) — omit both params
+- **Specific subscribers** — pass `subscriber_ids: ["id1", "id2"]` (use `list_subscribers` for IDs)
+- **Send to remaining** — pass `exclude_issue_id: "..."` to send to everyone who did NOT receive that issue (use `list_newsletter_issues` for issue IDs)
+
+**Analytics workflow:**
+```
+1. list_newsletter_issues()                    → see past sends with open/click counts
+2. get_newsletter_analytics({ issue_id })      → drill into a specific send
+   → returns: stats (delivered, opens, clicks, bounces), per-subscriber events, recipient list
+```
+
 ## Troubleshooting
 
 **MCP tools not available** — The OpenWriter MCP server isn't configured yet. Follow the [setup instructions](#mcp-tools-are-not-available-skill-first-install) above. After adding the MCP config, the user must restart their Claude Code session.