openwriter 0.2.0 → 0.2.2

package/dist/server/workspaces.js

@@ -1,30 +1,72 @@
 /**
  * Workspace manifest CRUD for OpenWriter v2.
- * Unified container model: containers (ordered/unordered) hold docs, tags are cross-cutting.
+ * Unified container model: containers hold docs in an ordered tree.
  * Manifests live in ~/.openwriter/_workspaces/*.json.
  */
-import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 import matter from 'gray-matter';
-import { WORKSPACES_DIR, ensureWorkspacesDir, sanitizeFilename, resolveDocPath } from './helpers.js';
+import trash from 'trash';
+import { WORKSPACES_DIR, ensureWorkspacesDir, sanitizeFilename, resolveDocPath, isExternalDoc } from './helpers.js';
+import { markdownToTiptap, tiptapToMarkdown } from './markdown.js';
 const ORDER_FILE = join(WORKSPACES_DIR, '_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';
-import { addTag, removeTag, removeFileFromAllTags, listTagsForFile } from './workspace-tags.js';
 // ============================================================================
 // INTERNAL HELPERS
 // ============================================================================
 function workspacePath(filename) {
     return join(WORKSPACES_DIR, filename);
 }
+/**
+ * Migrate workspace-level tags into document frontmatter.
+ * Old format: workspace.tags = { "tag1": ["file1.md", "file2.md"], ... }
+ * New format: each doc file has `tags: ["tag1", ...]` in its frontmatter.
+ * Returns true if migration occurred and the workspace was modified.
+ */
+function migrateWorkspaceTags(ws) {
+    if (!ws.tags || typeof ws.tags !== 'object')
+        return false;
+    const tagMap = ws.tags;
+    const entries = Object.entries(tagMap);
+    if (entries.length === 0) {
+        delete ws.tags;
+        return true;
+    }
+    for (const [tagName, files] of entries) {
+        for (const file of files) {
+            try {
+                const targetPath = resolveDocPath(file);
+                if (!existsSync(targetPath))
+                    continue;
+                const raw = readFileSync(targetPath, 'utf-8');
+                const parsed = markdownToTiptap(raw);
+                const tags = Array.isArray(parsed.metadata.tags) ? [...parsed.metadata.tags] : [];
+                if (!tags.includes(tagName)) {
+                    tags.push(tagName);
+                    parsed.metadata.tags = tags;
+                    const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+                    writeFileSync(targetPath, markdown, 'utf-8');
+                }
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    delete ws.tags;
+    return true;
+}
 function readWorkspace(filename) {
     const raw = readFileSync(workspacePath(filename), 'utf-8');
-    const parsed = JSON.parse(raw);
+    let parsed = JSON.parse(raw);
     if (isV1(parsed)) {
-        const migrated = migrateV1toV2(parsed);
-        writeWorkspace(filename, migrated);
-        return migrated;
+        parsed = migrateV1toV2(parsed);
+        writeWorkspace(filename, parsed);
+        return parsed;
+    }
+    // Migrate workspace-level tags to doc frontmatter
+    if (migrateWorkspaceTags(parsed)) {
+        writeWorkspace(filename, parsed);
     }
     return parsed;
 }
@@ -96,7 +138,7 @@ export function createWorkspace(options) {
     const { title, voiceProfileId = null } = options;
     const slug = sanitizeFilename(title).toLowerCase().replace(/\s+/g, '-');
     const filename = `${slug}-${randomUUID().slice(0, 8)}.json`;
-    const workspace = { version: 2, title, voiceProfileId, root: [], tags: {} };
+    const workspace = { version: 2, title, voiceProfileId, root: [] };
     writeWorkspace(filename, workspace);
     // Append to order
     const order = readOrder();
@@ -104,12 +146,27 @@ export function createWorkspace(options) {
     writeOrder(order);
     return { filename, title, docCount: 0 };
 }
-export function deleteWorkspace(filename) {
+export async function deleteWorkspace(filename) {
     ensureWorkspacesDir();
     const p = workspacePath(filename);
     if (!existsSync(p))
         throw new Error(`Workspace not found: ${filename}`);
-    unlinkSync(p);
+    const ws = readWorkspace(filename);
+    const files = collectAllFiles(ws.root);
+    const deletedFiles = [];
+    const skippedExternal = [];
+    for (const file of files) {
+        if (isExternalDoc(file)) {
+            skippedExternal.push(file);
+            continue;
+        }
+        const filePath = resolveDocPath(file);
+        if (existsSync(filePath)) {
+            await trash(filePath);
+            deletedFiles.push(file);
+        }
+    }
+    await trash(p);
     // Remove from order
     const order = readOrder();
     const idx = order.indexOf(filename);
@@ -117,6 +174,7 @@ export function deleteWorkspace(filename) {
         order.splice(idx, 1);
         writeOrder(order);
     }
+    return { deletedFiles, skippedExternal };
 }
 export function reorderWorkspaces(orderedFilenames) {
     ensureWorkspacesDir();
@@ -134,7 +192,6 @@ export function addDoc(wsFile, containerId, file, title, afterFile) {
 export function removeDoc(wsFile, file) {
     const ws = getWorkspace(wsFile);
     removeNode(ws.root, file);
-    removeFileFromAllTags(ws.tags, file);
     writeWorkspace(wsFile, ws);
     return ws;
 }
@@ -164,11 +221,7 @@ export function removeContainer(wsFile, containerId) {
     const found = findContainer(ws.root, containerId);
     if (!found)
         throw new Error(`Container "${containerId}" not found`);
-    // Collect files in container to clean up tags
-    const files = collectAllFiles(found.node.items || []);
     removeNode(ws.root, containerId);
-    for (const file of files)
-        removeFileFromAllTags(ws.tags, file);
     writeWorkspace(wsFile, ws);
     return ws;
 }
@@ -188,27 +241,6 @@ export function reorderContainer(wsFile, containerId, afterIdentifier) {
     return ws;
 }
 // ============================================================================
-// TAG OPERATIONS
-// ============================================================================
-export function tagDoc(wsFile, file, tag) {
-    const ws = getWorkspace(wsFile);
-    if (!findDocNode(ws.root, file))
-        throw new Error(`Document "${file}" not in workspace`);
-    addTag(ws.tags, tag, file);
-    writeWorkspace(wsFile, ws);
-    return ws;
-}
-export function untagDoc(wsFile, file, tag) {
-    const ws = getWorkspace(wsFile);
-    removeTag(ws.tags, tag, file);
-    writeWorkspace(wsFile, ws);
-    return ws;
-}
-export function getDocTags(wsFile, file) {
-    const ws = getWorkspace(wsFile);
-    return listTagsForFile(ws.tags, file);
-}
-// ============================================================================
 // CONTEXT
 // ============================================================================
 export function updateWorkspaceContext(wsFile, context) {
@@ -222,7 +254,9 @@ export function getItemContext(wsFile, docFile) {
     const found = findDocNode(ws.root, docFile);
     if (!found)
         throw new Error(`Document "${docFile}" not found in workspace`);
-    const tags = listTagsForFile(ws.tags, docFile);
+    // Read tags from document frontmatter (not workspace manifest)
+    const fm = readDocFrontmatter(docFile);
+    const tags = Array.isArray(fm?.tags) ? fm.tags : [];
     return {
         workspaceTitle: ws.title,
         workspaceContext: ws.context || {},
@@ -230,8 +264,64 @@ export function getItemContext(wsFile, docFile) {
     };
 }
 // ============================================================================
+// FIND-OR-CREATE HELPERS
+// ============================================================================
+/** Find an existing workspace by title (case-insensitive). Returns null if not found. */
+export function findWorkspaceByTitle(title) {
+    const all = listWorkspaces();
+    const lower = title.toLowerCase();
+    return all.find((w) => w.title.toLowerCase() === lower) || null;
+}
+/** Find a container by name in a workspace. Returns its ID, or null if not found. */
+export function findContainerByName(wsFile, name) {
+    const ws = getWorkspace(wsFile);
+    const lower = name.toLowerCase();
+    function scan(nodes) {
+        for (const n of nodes) {
+            if (n.type === 'container') {
+                if (n.name.toLowerCase() === lower)
+                    return n.id;
+                const found = scan(n.items);
+                if (found)
+                    return found;
+            }
+        }
+        return null;
+    }
+    return scan(ws.root);
+}
+/** Find workspace by title or create it. Returns workspace filename. */
+export function findOrCreateWorkspace(title) {
+    const existing = findWorkspaceByTitle(title);
+    if (existing)
+        return { filename: existing.filename, created: false };
+    const info = createWorkspace({ title });
+    return { filename: info.filename, created: true };
+}
+/** Find container by name in workspace, or create it. Returns container ID. */
+export function findOrCreateContainer(wsFile, name) {
+    const existing = findContainerByName(wsFile, name);
+    if (existing)
+        return { containerId: existing, created: false };
+    const result = addContainerToWorkspace(wsFile, null, name);
+    return { containerId: result.containerId, created: true };
+}
+// ============================================================================
 // CROSS-WORKSPACE QUERIES
 // ============================================================================
+/** Remove a document from every workspace that references it. */
+export function removeDocFromAllWorkspaces(file) {
+    const workspaces = listWorkspaces();
+    for (const info of workspaces) {
+        try {
+            const ws = readWorkspace(info.filename);
+            if (collectAllFiles(ws.root).includes(file)) {
+                removeDoc(info.filename, file);
+            }
+        }
+        catch { /* skip corrupt manifests */ }
+    }
+}
 export function getWorkspaceAssignedFiles() {
     const assigned = new Set();
     const workspaces = listWorkspaces();

package/dist/server/ws.js

@@ -2,8 +2,9 @@
  * WebSocket handler: pushes NodeChanges to browser, receives doc updates + signals.
  */
 import { WebSocketServer, WebSocket } from 'ws';
-import { updateDocument, getDocument, getTitle, getFilePath, getDocId, setMetadata, save, onChanges, isAgentLocked, getPendingDocFilenames, getPendingDocCounts, stripPendingAttrs, } from './state.js';
-import { switchDocument, createDocument, deleteDocument } from './documents.js';
+import { updateDocument, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, onChanges, isAgentLocked, getPendingDocFilenames, getPendingDocCounts, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, } from './state.js';
+import { switchDocument, createDocument, deleteDocument, getActiveFilename } from './documents.js';
+import { removeDocFromAllWorkspaces } from './workspaces.js';
 const clients = new Set();
 let currentAgentConnected = false;
 // Debounced auto-save: persist to disk 2s after last doc-update
@@ -57,13 +58,18 @@ export function setupWebSocket(server) {
                 counts: getPendingDocCounts(),
             },
         }));
-        ws.on('message', (data) => {
+        ws.on('message', async (data) => {
             try {
                 const msg = JSON.parse(data.toString());
                 if (msg.type === 'doc-update' && msg.document) {
                     if (isAgentLocked()) {
                         // Agent write in progress — ignore browser doc-updates
                     }
+                    else if (msg.filename && msg.filename !== getActiveFilename()) {
+                        // Browser sent a doc-update for a different document (race: server switched away).
+                        // Save directly to that file on disk instead of corrupting the active doc.
+                        saveDocToFile(msg.filename, msg.document);
+                    }
                     else {
                         updateDocument(msg.document);
                         debouncedSave();
@@ -109,19 +115,46 @@ export function setupWebSocket(server) {
                 if (msg.type === 'pending-resolved' && msg.filename) {
                     const action = msg.action; // 'accept' or 'reject'
                     const resolvedFilename = msg.filename;
-                    if (action === 'reject' && msg.wasAgentCreated) {
+                    const isActiveDoc = resolvedFilename === getActiveFilename();
+                    // Get metadata from the correct source (active state or disk file)
+                    const metadata = isActiveDoc ? getMetadata() : null;
+                    if (action === 'reject' && metadata?.agentCreated) {
                         // Agent-created doc with all content rejected → delete the file
+                        // Cancel debounced save (doc-update may have queued one for the now-empty doc)
+                        if (saveTimer) {
+                            clearTimeout(saveTimer);
+                            saveTimer = null;
+                        }
                         try {
-                            deleteDocument(resolvedFilename);
+                            // Remove from any workspace manifests before deleting the file
+                            removeDocFromAllWorkspaces(resolvedFilename);
+                            const result = await deleteDocument(resolvedFilename);
+                            if (result.switched && result.newDoc) {
+                                broadcastDocumentSwitched(result.newDoc.document, result.newDoc.title, result.newDoc.filename);
+                            }
+                            broadcastDocumentsChanged();
+                            broadcastWorkspacesChanged();
+                            broadcastPendingDocsChanged();
+                            return; // File deleted — no strip/save needed
                         }
                         catch (err) {
                             console.error('[WS] Failed to delete rejected agent doc:', err.message);
+                            // Fall through to normal strip+save (e.g. only doc remaining)
                         }
                     }
-                    // Strip pending attrs that transferPendingAttrs() re-added from stale server state,
-                    // then save clean markdown to disk.
-                    stripPendingAttrs();
-                    save();
+                    if (isActiveDoc) {
+                        // Normal path: resolved doc is the active one
+                        if (action === 'accept' && metadata?.agentCreated) {
+                            delete metadata.agentCreated;
+                        }
+                        stripPendingAttrs();
+                        save();
+                    }
+                    else {
+                        // Race path: resolved doc is NOT the active one (server switched away).
+                        // Strip pending attrs directly from the file on disk.
+                        stripPendingAttrsFromFile(resolvedFilename, action === 'accept');
+                    }
                     broadcastPendingDocsChanged();
                 }
             }
@@ -187,6 +220,13 @@ export function broadcastPendingDocsChanged() {
         }
     }, PENDING_DOCS_DEBOUNCE_MS);
 }
+export function broadcastPluginsChanged() {
+    const msg = JSON.stringify({ type: 'plugins-changed' });
+    for (const ws of clients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(msg);
+    }
+}
 export function broadcastAgentStatus(connected) {
     currentAgentConnected = connected;
     const msg = JSON.stringify({ type: 'agent-status', agentConnected: connected });
@@ -197,6 +237,20 @@ export function broadcastAgentStatus(connected) {
     }
 }
 let lastSyncStatus = null;
+export function broadcastWritingStarted(title, target) {
+    const msg = JSON.stringify({ type: 'writing-started', title, target: target || null });
+    for (const ws of clients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(msg);
+    }
+}
+export function broadcastWritingFinished() {
+    const msg = JSON.stringify({ type: 'writing-finished' });
+    for (const ws of clients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(msg);
+    }
+}
 export function broadcastSyncStatus(status) {
     lastSyncStatus = status;
     const msg = JSON.stringify({ type: 'sync-status', ...status });
@@ -206,6 +260,3 @@ export function broadcastSyncStatus(status) {
         }
     }
 }
-export function getLastSyncStatus() {
-    return lastSyncStatus;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openwriter",
-  "version": "0.2.0",
-  "description": "Local TipTap editor for human-agent collaboration via MCP",
+  "version": "0.2.2",
+  "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",
   "author": "Travis Steward",
@@ -66,6 +66,7 @@
     "open": "^10.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "trash": "^10.1.0",
     "ws": "^8.18.0",
     "zod": "^3.25.76"
   },

package/skill/SKILL.md

@@ -1,39 +1,53 @@
 ---
 name: openwriter
 description: |
-  OpenWriter — local TipTap editor for human-agent collaboration.
-  Agent reads/edits documents via MCP tools (read_pad, write_to_pad, etc.).
-  Changes appear as pending decorations the user accepts or rejects.
-  Multi-document workspace with sidebar navigation.
+  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. 26 MCP tools for document editing, multi-doc workspaces, and
+  organization. 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".
+  "edit my document", "review my writing", "check the pad", "write me a doc".
 
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
+metadata:
+  author: travsteward
+  version: "0.2.0"
+  repository: https://github.com/travsteward/openwriter
+license: MIT
 ---
 
-# OpenWriter — Public Companion Skill
+# OpenWriter Skill
 
-You are a writing collaborator. The user has a document open in OpenWriter (http://localhost:5050). You read their document and make edits **exclusively via MCP tools**. Edits appear as pending decorations (colored highlights) that the user can accept or reject.
+You are a writing collaborator. You read documents and make edits **exclusively via MCP tools**. Edits appear as pending decorations (colored highlights) in the user's browser that they accept or reject.
 
-**First action when activated:** Always share the browser URL:
-> OpenWriter is at **http://localhost:5050**
+## Setup — Which Path?
 
-## Quick Setup
+Check whether the `open-writer` MCP tools are available (e.g. `read_pad`, `write_to_pad`). This determines setup state:
 
-OpenWriter must be configured as an MCP server before use. Two paths:
+### MCP tools ARE available (ready to use)
 
-### Option A: User runs it from their terminal (outside Claude Code)
+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.
+
+**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)
+
+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 24 editing tools.
+
+**Step 1:** Tell the user to install the npm package and MCP server:
 
 ```bash
+# Add the OpenWriter MCP server to Claude Code
 claude mcp add -s user open-writer -- npx openwriter --no-open
 ```
 
-Then restart the Claude Code session. The MCP tools become available automatically.
-
-### Option B: Agent configures it (when user asks you to set it up)
+Then restart the Claude Code session. The MCP tools become available on next launch.
 
-Edit `~/.claude.json` and add to the `mcpServers` object:
+**Step 2 (if the user can't run the command above):** Edit `~/.claude.json` directly. Add to the `mcpServers` object:
 
 ```json
 "open-writer": {
@@ -42,7 +56,7 @@ Edit `~/.claude.json` and add to the `mcpServers` object:
 }
 ```
 
-The `mcpServers` key is at the top level of `~/.claude.json`. If it doesn't exist, create it. Example:
+The `mcpServers` key is at the top level of `~/.claude.json`. If it doesn't exist, create it:
 
 ```json
 {
@@ -56,12 +70,12 @@ The `mcpServers` key is at the top level of `~/.claude.json`. If it doesn't exis
 ```
 
 After editing, tell the user:
-1. Restart your Claude Code session (the MCP server loads on startup)
+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.
+**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.
 
-## MCP Tools Reference (24 tools)
+## MCP Tools Reference (26 tools)
 
 ### Document Operations
 
@@ -69,6 +83,7 @@ After editing, tell the user:
 |------|-------------|
 | `read_pad` | Read the current document (compact tagged-line format) |
 | `write_to_pad` | Apply edits as pending decorations (rewrite, insert, delete) |
+| `populate_document` | Populate an empty doc with content (two-step creation flow) |
 | `get_pad_status` | Lightweight poll: word count, pending changes, userSignaledReview |
 | `get_nodes` | Fetch specific nodes by ID |
 | `get_metadata` | Get frontmatter metadata for the active document |
@@ -80,14 +95,14 @@ After editing, tell the user:
 |------|-------------|
 | `list_documents` | List all documents with filename, word count, active status |
 | `switch_document` | Switch to a different document by filename |
-| `create_document` | Create a new document (optional title, content, path) |
+| `create_document` | Create a new empty document (optional workspace + container placement) |
 | `open_file` | Open an existing .md file from any location on disk |
+| `delete_document` | Delete a document file (moves to OS trash, recoverable) |
 
 ### Import
 
 | Tool | Description |
 |------|-------------|
-| `replace_document` | Import external content into a new/blank document |
 | `import_gdoc` | Import a Google Doc (auto-splits multi-chapter docs) |
 
 ### Workspace Management
@@ -96,6 +111,7 @@ After editing, tell the user:
 |------|-------------|
 | `list_workspaces` | List all workspaces with title and doc count |
 | `create_workspace` | Create a new workspace |
+| `delete_workspace` | Delete a workspace and all its document files (moves to OS trash) |
 | `get_workspace_structure` | Get full workspace tree: containers, docs, tags, context |
 | `get_item_context` | Get progressive disclosure context for a doc in a workspace |
 | `update_workspace_context` | Update workspace context (characters, settings, rules) |
@@ -106,8 +122,8 @@ After editing, tell the user:
 |------|-------------|
 | `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 in a workspace |
-| `untag_doc` | Remove a tag from a document |
+| `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 |
 
 ### Text Operations
@@ -118,15 +134,54 @@ After editing, tell the user:
 
 ## Writing Strategy
 
-**Incremental edits, not monolithic replacement.**
+OpenWriter has two distinct modes: **editing** existing documents and **creating** new content. Use the right approach for each.
+
+### Editing (write_to_pad)
+
+For making changes to existing documents — rewrites, insertions, deletions:
 
-- Use `write_to_pad` for all edits — never `replace_document` (unless importing into a blank doc)
+- Use `write_to_pad` for all edits
 - Send **3-8 changes per call** for a responsive, streaming feel
-- Always `read_pad` before writing — you need fresh node IDs
+- Always `read_pad` before editing to get fresh node IDs
 - Respect `pendingChanges > 0` — wait for the user to accept/reject before sending more
 - Content accepts markdown strings (preferred) or TipTap JSON
 - Decoration colors: **blue** = rewrite, **green** = insert, **red** = delete
 
+### Creating New Documents (two-step flow)
+
+**Always use the two-step flow** when creating new content:
+
+```
+1. create_document({ title: "My Doc" })      ← no content, fires instantly, shows spinner
+2. populate_document({ content: "..." })      ← delivers content, clears spinner
+```
+
+**Why two steps?** MCP tool calls are atomic — the server doesn't receive the call until ALL parameters are fully generated. For a document with hundreds or thousands of words, the user would wait 30+ seconds with zero feedback while you generate content tokens. The two-step flow shows a sidebar spinner immediately (step 1 has no content to generate), then the spinner persists while you generate and deliver the content (step 2).
+
+**Rules:**
+- `create_document` does NOT accept a `content` parameter — it always creates an empty doc
+- Step 1 (`create_document`) — shows spinner, creates empty doc, does NOT switch the editor
+- Step 2 (`populate_document`) — writes content to the active doc, marks as pending decorations, switches the editor, clears the spinner
+- Never use `write_to_pad` for the initial population — use `populate_document` exclusively
+
+### Workspace-Integrated Creation
+
+`create_document` accepts optional `workspace` and `container` parameters for direct workspace placement:
+
+```
+create_document({
+  title: "Opening Chapter",
+  workspace: "The Immortal",        ← creates workspace if it doesn't exist
+  container: "Chapters"             ← creates container if it doesn't exist
+})
+```
+
+- **`workspace`** (string) — workspace title to add the doc to. Auto-creates if not found (case-insensitive match).
+- **`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.
+
 ## Workflow
 
 ### Single document
@@ -147,14 +202,39 @@ After editing, tell the user:
 4. write_to_pad      → apply edits
 ```
 
-### Creating new content
+### Creating new content (two-step)
 
 ```
-1. create_document({ title: "My Doc", content: "# Heading\n\nContent..." })
-2. read_pad          → get node IDs from created content
-3. write_to_pad      → refine with edits
+1. create_document({ title: "My Doc", workspace: "Project", container: "Chapters" })
+                                                → spinner appears, doc placed in workspace
+2. populate_document({ content: "# ..." })     → content delivered, spinner clears
+3. read_pad                                     → get node IDs if further edits needed
+4. write_to_pad                                 → refine with edits
 ```
 
+### Building a workspace (multiple docs)
+
+```
+1. create_document({ title: "Ch 1", workspace: "My Book", container: "Chapters" })
+2. populate_document({ content: "..." })
+3. create_document({ title: "Ch 2", workspace: "My Book", container: "Chapters" })
+4. populate_document({ content: "..." })
+5. create_document({ title: "Character Bible", workspace: "My Book", container: "References" })
+6. populate_document({ content: "..." })
+7. tag_doc + update_workspace_context           → organize and add context
+```
+
+The workspace and containers are auto-created on the first `create_document` call. Subsequent calls reuse the existing workspace/containers (matched case-insensitively).
+
+### Book workspace guidelines
+
+When importing or organizing book-length projects, read the source material first and **follow the grain** — break content into the categories the author is already thinking in, don't impose a template.
+
+- **One concept per doc.** Don't create one giant reference doc. If the material covers characters, setting, plot, and themes, those are separate documents.
+- **Preserve originals.** Keep raw drafts separate from revised versions (e.g. Drafts vs. Chapters containers). The author needs both.
+- **Synthesize, don't just copy.** Reorganize messy notes into clean, scannable docs (headers, bullets, sections) while keeping the author's voice and prose verbatim.
+- **Surface open threads.** Unanswered questions, brainstorm lists, and loose ideas get their own doc — don't bury them inside reference material.
+
 ## Review Etiquette
 
 1. **Share the URL.** Always tell the user: http://localhost:5050
@@ -166,7 +246,7 @@ After editing, tell the user:
 
 ## Troubleshooting
 
-**MCP tools not available** — Run `/mcp` in Claude Code to check connection status. Click reconnect if needed.
+**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.
 
 **Port 5050 busy** — Another OpenWriter instance owns the port. New sessions auto-enter client mode (proxying via HTTP) — tools still work. No action needed.