openwriter 0.10.0 → 0.12.0

package/dist/server/mcp.js

@@ -221,6 +221,9 @@ export const TOOL_REGISTRY = [
                 pendingChanges: target.pendingCount,
                 lastModified: target.lastModified.toISOString(),
             };
+            // Surface autoAccept so the agent stops waiting for review when it's on.
+            if (target.metadata?.autoAccept === true)
+                status.autoAccept = true;
             const latestVersion = getUpdateInfo();
             const payload = latestVersion ? { ...status, updateAvailable: latestVersion } : status;
             return { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -306,11 +309,9 @@ export const TOOL_REGISTRY = [
                 wsTarget = { wsFilename: ws.filename, containerId };
                 broadcastWorkspacesChanged(); // Browser sees container structure before spinner
             }
-            if (!empty) {
-                broadcastWritingStarted(title || 'Untitled', wsTarget);
-                // Yield so the browser receives and renders the spinner before heavy work
-                await new Promise((resolve) => setTimeout(resolve, 200));
-            }
+            // Track the spinner key so catch can clear exactly this entry
+            // (not siblings from a concurrent declare_writes).
+            let spinnerKey = null;
             try {
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
@@ -349,6 +350,11 @@ export const TOOL_REGISTRY = [
                     addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
                     wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                 }
+                // Broadcast spinner keyed by filename so populate_document can clear exactly
+                // this entry. Fires after the file exists, so documents-changed arrives with
+                // the real entry that the sidebar filters behind the spinner until populate.
+                spinnerKey = result.filename;
+                broadcastWritingStarted(title || 'Untitled', wsTarget, spinnerKey);
                 broadcastDocumentsChanged();
                 return {
                     content: [{
@@ -358,8 +364,8 @@ export const TOOL_REGISTRY = [
                 };
             }
             catch (err) {
-                if (!empty)
-                    broadcastWritingFinished();
+                if (spinnerKey)
+                    broadcastWritingFinished(spinnerKey);
                 throw err;
             }
         },
@@ -387,7 +393,7 @@ export const TOOL_REGISTRY = [
                     doc = content;
                 }
                 else {
-                    broadcastWritingFinished();
+                    broadcastWritingFinished(filename);
                     return {
                         content: [{ type: 'text', text: 'Error: content must be a markdown string or TipTap JSON { type: "doc", content: [...] }' }],
                     };
@@ -399,7 +405,7 @@ export const TOOL_REGISTRY = [
                     broadcastDocumentsChanged();
                     broadcastWorkspacesChanged();
                     broadcastPendingDocsChanged();
-                    broadcastWritingFinished();
+                    broadcastWritingFinished(filename);
                     return {
                         content: [{
                                 type: 'text',
@@ -407,9 +413,12 @@ export const TOOL_REGISTRY = [
                             }],
                     };
                 }
-                // Active target (or no filename): existing flow
+                // Active target (or no filename): existing flow.
+                // Skip pending tagging when autoAccept is on for this doc — content commits directly.
                 setAgentLock(); // Block browser doc-updates during population
-                markAllNodesAsPending(doc, 'insert');
+                if (getMetadata()?.autoAccept !== true) {
+                    markAllNodesAsPending(doc, 'insert');
+                }
                 updateDocument(doc);
                 updatePendingCacheForActiveDoc();
                 save();
@@ -419,7 +428,7 @@ export const TOOL_REGISTRY = [
                 broadcastWorkspacesChanged();
                 broadcastDocumentSwitched(doc, getTitle(), getActiveFilename());
                 broadcastPendingDocsChanged();
-                broadcastWritingFinished();
+                broadcastWritingFinished(filename || getActiveFilename());
                 const wordCount = getWordCount();
                 return {
                     content: [{
@@ -429,11 +438,78 @@ export const TOOL_REGISTRY = [
                 };
             }
             catch (err) {
-                broadcastWritingFinished();
+                broadcastWritingFinished(filename);
                 throw err;
             }
         },
     },
+    {
+        name: 'declare_writes',
+        description: 'Declare a batch of documents to create at once. Use this when creating multiple documents in parallel (e.g. a series of blog drafts, a tweet thread saved as separate docs, newsletter variants). Each write gets its own sidebar spinner keyed to its filename — spinners persist across app refreshes and only clear when you call populate_document for that specific doc. Returns an array of { docId, filename, title }. Next step: call populate_document once per docId (in parallel is fine). For creating a single document, prefer create_document.',
+        schema: {
+            writes: z.array(z.object({
+                title: z.string().describe('Title for the document.'),
+                content_type: z.enum(['document', 'tweet', 'reply', 'quote', 'article', 'linkedin', 'newsletter', 'blog']).describe('Content type. Use "document" for plain docs.'),
+                workspace: z.string().optional().describe('Workspace title to add this doc to. Creates the workspace if it does not exist.'),
+                container: z.string().optional().describe('Container name within the workspace (e.g. "Chapters"). Requires workspace.'),
+                url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote".'),
+                path: z.string().optional().describe('Absolute file path to create the document at. If omitted, creates in ~/.openwriter/.'),
+            })).min(1).describe('List of documents to declare (minimum 1).'),
+        },
+        handler: async ({ writes }) => {
+            const results = [];
+            let workspacesChanged = false;
+            const broadcastedKeys = [];
+            for (const w of writes) {
+                try {
+                    if ((w.content_type === 'reply' || w.content_type === 'quote') && !w.url) {
+                        results.push({ docId: '', filename: '', title: w.title, error: `content_type "${w.content_type}" requires a url parameter` });
+                        continue;
+                    }
+                    let wsTarget;
+                    if (w.workspace) {
+                        const ws = findOrCreateWorkspace(w.workspace);
+                        let containerId = null;
+                        if (w.container) {
+                            const c = findOrCreateContainer(ws.filename, w.container);
+                            containerId = c.containerId;
+                        }
+                        wsTarget = { wsFilename: ws.filename, containerId };
+                        workspacesChanged = true;
+                    }
+                    const typeMeta = resolveTypeMeta(w.content_type, w.url);
+                    const result = createDocumentFile(w.title, w.path, typeMeta);
+                    if (wsTarget) {
+                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                    }
+                    broadcastWritingStarted(w.title, wsTarget, result.filename);
+                    broadcastedKeys.push(result.filename);
+                    results.push({ docId: result.docId, filename: result.filename, title: result.title });
+                }
+                catch (err) {
+                    results.push({ docId: '', filename: '', title: w.title, error: err.message });
+                }
+            }
+            broadcastDocumentsChanged();
+            if (workspacesChanged)
+                broadcastWorkspacesChanged();
+            const successes = results.filter((r) => !r.error);
+            const failures = results.filter((r) => r.error);
+            const lines = [
+                `Declared ${successes.length} write${successes.length === 1 ? '' : 's'}${failures.length ? ` (${failures.length} failed)` : ''}:`,
+                ...successes.map((r) => `  "${r.title}" [${r.docId}] → ${r.filename}`),
+            ];
+            if (failures.length) {
+                lines.push('', 'Errors:');
+                for (const r of failures)
+                    lines.push(`  "${r.title}" — ${r.error}`);
+            }
+            if (successes.length) {
+                lines.push('', 'Next: call populate_document once per docId to fill in content.');
+            }
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        },
+    },
     {
         name: 'open_file',
         description: 'Open an existing .md file from any location on disk. Saves the current document first, then loads the file and sets it as active. The file appears in the sidebar and edits save back to the original path.',

package/dist/server/state.js

@@ -559,8 +559,13 @@ function findNodeInDoc(nodes, id) {
 /**
  * Core change application logic — operates on any document object.
  * Mutates doc in place and returns processed changes with server-assigned IDs.
+ *
+ * When `autoAccept` is true, changes commit directly: no pendingStatus tagging,
+ * no pendingOriginalContent baseline, and deletes hard-remove from the array
+ * (rather than tagging for review). Processed changes carry autoAccept: true
+ * so the client knows to apply them as committed edits, not pending review.
  */
-function applyChangesToDoc(doc, changes) {
+function applyChangesToDoc(doc, changes, autoAccept = false) {
     const processed = [];
     // Track last insert anchor → last inserted node ID, so consecutive inserts
     // with the same afterNodeId chain naturally (array order = document order).
@@ -581,16 +586,21 @@ function applyChangesToDoc(doc, changes) {
             // Detect partial change: if only a sub-range of the node text changed,
             // attach selection range attrs so the frontend decorates only that part
             let partialRange = null;
-            if (!isEmptyNode && contentArray.length === 1) {
+            if (!isEmptyNode && contentArray.length === 1 && !autoAccept) {
                 // Use true original for partial range when a prior pending rewrite exists,
                 // so offsets align with pendingOriginalContent
                 const baseContent = existingOriginal?.content || originalNode.content || [];
                 partialRange = computePartialRange(baseContent, contentArray[0].content || []);
             }
-            // First node replaces the target (rewrite or insert if empty)
+            // First node replaces the target (rewrite or insert if empty).
+            // In autoAccept mode, omit all pendingStatus/pendingOriginalContent attrs
+            // so the change commits cleanly with no review surface.
             const firstNode = {
                 ...contentArray[0],
-                attrs: {
+                attrs: autoAccept ? {
+                    ...contentArray[0].attrs,
+                    id: change.nodeId,
+                } : {
                     ...contentArray[0].attrs,
                     id: change.nodeId,
                     pendingStatus: isEmptyNode ? 'insert' : 'rewrite',
@@ -603,7 +613,8 @@ function applyChangesToDoc(doc, changes) {
                     } : {}),
                 },
             };
-            // Additional nodes get inserted after as pending inserts
+            // Additional nodes get inserted after — as pending inserts in normal mode,
+            // as plain blocks in autoAccept mode.
             const extraNodes = contentArray.slice(1).map((node) => ({
                 ...node,
                 attrs: {
@@ -611,11 +622,13 @@ function applyChangesToDoc(doc, changes) {
                     id: node.attrs?.id || generateNodeId(),
                 },
             }));
-            markLeafBlocksAsPending(extraNodes, 'insert');
+            if (!autoAccept)
+                markLeafBlocksAsPending(extraNodes, 'insert');
             found.parent.splice(found.index, 1, firstNode, ...extraNodes);
             processed.push({
                 ...change,
                 content: [firstNode, ...extraNodes],
+                ...(autoAccept ? { autoAccept: true } : {}),
             });
         }
         else if (change.operation === 'insert' && change.content) {
@@ -628,8 +641,10 @@ function applyChangesToDoc(doc, changes) {
                     id: node.attrs?.id || (change.nodeId && !change.afterNodeId && i === 0 ? change.nodeId : generateNodeId()),
                 },
             }));
-            // Mark leaf blocks as pending (not containers) for correct serialization
-            markLeafBlocksAsPending(contentWithIds, 'insert');
+            // Mark leaf blocks as pending (not containers) — skipped in autoAccept mode
+            // so inserts commit as plain content without decoration.
+            if (!autoAccept)
+                markLeafBlocksAsPending(contentWithIds, 'insert');
             let resolvedAfterId;
             // Auto-chain: if this insert targets the same anchor as the previous insert,
             // redirect it to insert after the last inserted node instead (preserves array order).
@@ -671,6 +686,7 @@ function applyChangesToDoc(doc, changes) {
                     ? resolvedAfterId
                     : effectiveAfterId ?? change.afterNodeId,
                 content: contentWithIds.length === 1 ? contentWithIds[0] : contentWithIds,
+                ...(autoAccept ? { autoAccept: true } : {}),
             });
         }
         else if (change.operation === 'delete' && change.nodeId) {
@@ -698,21 +714,29 @@ function applyChangesToDoc(doc, changes) {
                 processed.push({ operation: 'delete', nodeId: change.nodeId, content: [{ type: 'horizontalRule' }] });
                 continue;
             }
-            found.parent[found.index] = {
-                ...found.parent[found.index],
-                attrs: {
-                    ...found.parent[found.index].attrs,
-                    pendingStatus: 'delete',
-                },
-            };
-            processed.push(change);
+            if (autoAccept) {
+                // Hard-delete: remove the node entirely from its parent array.
+                found.parent.splice(found.index, 1);
+                processed.push({ ...change, autoAccept: true });
+            }
+            else {
+                found.parent[found.index] = {
+                    ...found.parent[found.index],
+                    attrs: {
+                        ...found.parent[found.index].attrs,
+                        pendingStatus: 'delete',
+                    },
+                };
+                processed.push(change);
+            }
         }
     }
     return processed;
 }
 /** Apply changes to the active document singleton. */
 function applyChangesToDocument(changes) {
-    const processed = applyChangesToDoc(state.document, changes);
+    const autoAccept = state.metadata?.autoAccept === true;
+    const processed = applyChangesToDoc(state.document, changes, autoAccept);
     if (processed.length > 0) {
         state.lastModified = new Date();
     }
@@ -730,11 +754,13 @@ export function applyTextEdits(nodeId, edits) {
     const result = applyTextEditsToNode(originalNode, edits);
     if (!result)
         return { success: false, error: 'No edits matched' };
-    // Store inline edit ranges for fine-grained decoration
-    result.node.attrs = {
-        ...result.node.attrs,
-        pendingTextEdits: result.textEdits,
-    };
+    // Inline edit decoration only matters when there's a review surface — skip in autoAccept.
+    if (state.metadata?.autoAccept !== true) {
+        result.node.attrs = {
+            ...result.node.attrs,
+            pendingTextEdits: result.textEdits,
+        };
+    }
     // Route through applyChanges as a rewrite so it goes through the normal pipeline
     applyChanges([{
             operation: 'rewrite',
@@ -1369,6 +1395,39 @@ export function saveDocToFile(filename, doc) {
     }
     catch { /* best-effort */ }
 }
+/**
+ * Set or clear the autoAccept flag on a non-active document file on disk.
+ * Reads the file, mutates metadata, writes back. Does not touch pending attrs —
+ * callers should run stripPendingAttrsFromFile first when enabling.
+ */
+export function setAutoAcceptOnFile(filename, enabled) {
+    const targetPath = resolveDocPath(filename);
+    if (!existsSync(targetPath))
+        return;
+    try {
+        const raw = readFileSync(targetPath, 'utf-8');
+        const parsed = markdownToTiptap(raw);
+        if (enabled) {
+            parsed.metadata.autoAccept = true;
+        }
+        else {
+            delete parsed.metadata.autoAccept;
+        }
+        let markdown;
+        if (isExternalDoc(targetPath)) {
+            const body = tiptapToBody(parsed.document);
+            markdown = parsed.rawFrontmatter
+                ? `---\n${parsed.rawFrontmatter}\n---\n\n${body}`
+                : body;
+        }
+        else {
+            markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
+        }
+        atomicWriteFileSync(targetPath, markdown);
+        invalidateDocCache(targetPath);
+    }
+    catch { /* best-effort */ }
+}
 /**
  * Strip pending attrs from a specific file on disk (not the active document).
  * Optionally clears agentCreated metadata (on accept).
@@ -1442,7 +1501,11 @@ export function populateDocumentFile(filename, doc) {
     const targetPath = resolveDocPath(filename);
     const raw = readFileSync(targetPath, 'utf-8');
     const parsed = markdownToTiptap(raw);
-    markAllNodesAsPending(doc, 'insert');
+    // Skip pending tagging when the target doc has autoAccept on —
+    // content commits directly as accepted.
+    if (parsed.metadata?.autoAccept !== true) {
+        markAllNodesAsPending(doc, 'insert');
+    }
     flushDocToFile(filename, doc, parsed.title, parsed.metadata);
     const pendingCount = countPending(doc.content);
     const text = extractText(doc.content);
@@ -1478,7 +1541,8 @@ export function applyChangesToFile(filename, changes) {
         docId = metadata.docId || '';
         isTemp = false;
     }
-    const processed = applyChangesToDoc(doc, changes);
+    const autoAccept = metadata?.autoAccept === true;
+    const processed = applyChangesToDoc(doc, changes, autoAccept);
     if (processed.length > 0) {
         flushDocToFile(filename, doc, title, metadata);
         updateCacheEntry(targetPath, doc, title, metadata, isTemp, docId);
@@ -1533,16 +1597,21 @@ export function applyTextEditsToFile(filename, nodeId, edits) {
     const result = applyTextEditsToNode(originalNode, edits);
     if (!result)
         return { success: false, error: 'No edits matched' };
-    result.node.attrs = {
-        ...result.node.attrs,
-        pendingTextEdits: result.textEdits,
-    };
+    const autoAccept = metadata?.autoAccept === true;
+    // pendingTextEdits is the fine-grained inline-edit decoration — skip in autoAccept
+    // since the change commits directly.
+    if (!autoAccept) {
+        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,
-        }]);
+        }], autoAccept);
     if (processed.length > 0) {
         flushDocToFile(filename, doc, title, metadata);
         updateCacheEntry(targetPath, doc, title, metadata, isTemp, docId);

package/dist/server/ws.js

@@ -116,6 +116,11 @@ export function setupWebSocket(server) {
             type: 'pending-docs-changed',
             pendingDocs: getPendingDocInfo(),
         }));
+        // Rehydrate in-flight writing spinners across app refreshes
+        const pendingWritesSnapshot = getPendingWritesSnapshot();
+        if (pendingWritesSnapshot.length > 0) {
+            ws.send(JSON.stringify({ type: 'pending-writes-sync', writes: pendingWritesSnapshot }));
+        }
         ws.on('message', async (data) => {
             try {
                 const msg = JSON.parse(data.toString());
@@ -377,32 +382,80 @@ export function broadcastAgentStatus(connected) {
     }
 }
 let lastSyncStatus = null;
-// Safety net: auto-clear spinner if writing-finished never arrives
-let writingTimer = null;
+const pendingWrites = new Map();
 const WRITING_TIMEOUT_MS = 60_000;
-export function broadcastWritingStarted(title, target) {
-    if (writingTimer)
-        clearTimeout(writingTimer);
-    writingTimer = setTimeout(() => {
-        console.log('[WS] Writing spinner timed out — auto-clearing');
-        broadcastWritingFinished();
+export function broadcastWritingStarted(title, target, key) {
+    const writeKey = key || target?.wsFilename || `write:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
+    const existing = pendingWrites.get(writeKey);
+    if (existing)
+        clearTimeout(existing.timer);
+    const timer = setTimeout(() => {
+        console.log(`[WS] Writing spinner timed out for ${writeKey} — auto-clearing`);
+        broadcastWritingFinished(writeKey);
     }, WRITING_TIMEOUT_MS);
-    const msg = JSON.stringify({ type: 'writing-started', title, target: target || null });
+    pendingWrites.set(writeKey, {
+        key: writeKey,
+        title,
+        target: target || null,
+        startedAt: Date.now(),
+        timer,
+    });
+    const msg = JSON.stringify({ type: 'writing-started', title, target: target || null, key: writeKey });
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN)
             ws.send(msg);
     }
+    return writeKey;
 }
-export function broadcastWritingFinished() {
-    if (writingTimer) {
-        clearTimeout(writingTimer);
-        writingTimer = null;
+// key omitted → clear all (legacy single-write flows). Pass a key for multi-doc.
+export function broadcastWritingFinished(key) {
+    if (key) {
+        const entry = pendingWrites.get(key);
+        if (entry) {
+            clearTimeout(entry.timer);
+            pendingWrites.delete(key);
+        }
+    }
+    else {
+        for (const entry of pendingWrites.values())
+            clearTimeout(entry.timer);
+        pendingWrites.clear();
     }
-    const msg = JSON.stringify({ type: 'writing-finished' });
+    // Always send writing-finished with the key so the client can drop it from
+    // its pending set. Then, if siblings remain, re-surface the latest with a
+    // writing-started so the spinner doesn't vanish mid-batch.
+    const finishedMsg = JSON.stringify({ type: 'writing-finished', key: key || null });
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN)
-            ws.send(msg);
+            ws.send(finishedMsg);
     }
+    if (key && pendingWrites.size > 0) {
+        let next = null;
+        for (const e of pendingWrites.values()) {
+            if (!next || e.startedAt > next.startedAt)
+                next = e;
+        }
+        if (next) {
+            const startedMsg = JSON.stringify({
+                type: 'writing-started',
+                title: next.title,
+                target: next.target,
+                key: next.key,
+            });
+            for (const ws of clients) {
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(startedMsg);
+            }
+        }
+    }
+}
+export function getPendingWritesSnapshot() {
+    return Array.from(pendingWrites.values()).map(({ key, title, target, startedAt }) => ({
+        key,
+        title,
+        target,
+        startedAt,
+    }));
 }
 export function broadcastMarksChanged(filename) {
     const msg = JSON.stringify({ type: 'marks-changed', filename });

package/package.json

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

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.4.5"
+  version: "0.6.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -208,6 +208,16 @@ For making changes to existing documents — rewrites, insertions, deletions:
 - Decoration colors: **blue** = rewrite, **green** = insert, **red** = delete
 - **Never re-populate a document to fix it.** `populate_document` re-sends the entire document body — extremely token-expensive. To remove nodes, use `write_to_pad` with `{ operation: "delete", nodeId: "..." }`. To fix content, use `rewrite`. Only use `populate_document` once during initial creation, or as a last resort if the document is severely broken.
 
+### Auto-accept mode (no pending review)
+
+The user can turn on **auto-accept** on a per-doc basis (right-click the doc in the sidebar). When on, your edits commit directly — no pending decorations, no review panel for that doc. Used during fast drafting where the user isn't reviewing as you go.
+
+- `get_pad_status` returns `autoAccept: true` when the active doc has it on. Use this to decide your cadence.
+- **When autoAccept is true:** keep writing without polling for review. Don't wait between batches. Send the next 3-8 changes the moment you're ready.
+- **When autoAccept is false (default):** respect `pendingChanges > 0` — wait for the user to accept/reject before sending more.
+- You don't toggle this flag yourself — only the user does, from the sidebar. If you think the user wants it, ask first.
+- The flag is persisted in the doc's frontmatter as `autoAccept: true`. Visible in `get_metadata`.
+
 ### Creating New Documents (two-step flow)
 
 **Always use the two-step flow** when creating new content:
@@ -244,6 +254,38 @@ create_document({
 
 This eliminates the need for separate `create_workspace`, `create_container`, and `move_item` calls when building up a workspace.
 
+### Batched Creation (multiple docs at once)
+
+When creating **two or more documents together** — a tweet thread saved as separate docs, a series of blog drafts, newsletter variants, a workspace populated with several files — use `declare_writes` instead of looping `create_document`. It's one tool call, registers all sidebar spinners atomically, and survives app refreshes.
+
+```
+1. declare_writes({
+     writes: [
+       { title: "Post 1", content_type: "tweet" },
+       { title: "Post 2", content_type: "tweet" },
+       { title: "Post 3", content_type: "tweet" },
+     ]
+   })
+   → returns [{ docId, filename, title }, ...]
+
+2. populate_document({ docId: "...", content: "..." })  ← one call per doc, parallel is fine
+```
+
+**Rules:**
+- Each write in the batch gets its own sidebar spinner keyed to its filename — a spinner only clears when you `populate_document` that specific `docId`
+- Spinners persist across app refreshes (server-side registry)
+- Same per-write fields as `create_document`: `title`, `content_type`, optional `workspace`/`container`/`url`/`path`
+- `reply` / `quote` types still require `url`
+- For a **single** document, use `create_document` — don't reach for `declare_writes` just to wrap one entry
+
+## Voice Frames
+
+Pre-built voice postures for when the user wants a specific style but has no custom voice profile. Five frames cover the common needs: authority, provocateur, logical, storyteller, business.
+
+**Triggers** — any of the following should make you load frames: "write authoritatively", "authority voice", "contrarian take", "provocateur", "first principles", "logical/analytical essay", "tell the story", "storyteller", "business email", "high-status brevity", or an explicit frame name.
+
+**Protocol** — load `docs/voices.md` for the full selection guide and 4-step protocol. Then read the specific `voices/<frame>.md` for the rules. Apply all 6 category rules as hard constraints while drafting in the editor, and run the `docs/anti-ai.md` Tier 1 pass before leaving the output.
+
 ## Workflow
 
 ### Single document

package/skill/docs/anti-ai.md

@@ -0,0 +1,71 @@
+# Anti-AI Detection Rules
+
+Two tiers. Tier 1 rules are **hard rules** — fix unconditionally, no voice profile override. These patterns are so statistically associated with AI that detectors flag them regardless of context. Tier 2 rules are **voice-gated** — check against the voice profile before fixing.
+
+---
+
+## Tier 1: Hard Rules (Always Fix)
+
+**Em-dashes — eliminate, then calibrate.** AI uses em-dashes at 5-10x human density. This is one of the strongest AI signals.
+- **Default (no profile or generic voice)**: Zero em-dashes. Convert to periods, commas, or parentheses.
+- **With voice profile**: Check the author's samples. If they use em-dashes, match their frequency — never exceed it. An author at 1 per 300 words gets 1 per 300 words. An author who never uses them gets zero.
+
+**Contrastive formula — never use.** These constructions are AI fingerprints:
+- "It's not X, it's Y" / "This isn't X, it's Y"
+- "Rather than X, we should Y"
+- "Instead of X, consider Y"
+- "Not merely X, but Y"
+Rewrite without the formula. State the point directly.
+
+**Nuclear phrases — kill on sight.** These phrases are 100-900x more frequent in AI text than human text. No human writes them at this density:
+- "valuable insights" (902x) · "indelible mark" (319x) · "rich tapestry" (227x)
+- "crucial role in shaping" (250x) · "adds a layer of complexity" (194x)
+- "a stark reminder" (151x) · "fostering a sense" (138x) · "nuanced understanding" (115x)
+- "unwavering commitment" (256x) · "multifaceted nature" (92x) · "beacon of hope" (58x)
+- "delve deeper" (72x) · "navigate the complex" (87x) · "transformative power" (74x)
+- "shed light on" · "serves as a testament" · "underscores the importance"
+
+**Copula avoidance — use simple verbs.** AI replaces "is" with "serves as", "has" with "boasts", "shows" with "underscores." This is a telltale pattern. Use the simple verb.
+
+**Sycophantic filler — cut unconditionally.** "Interestingly", "It's worth noting", "Notably", "It is important to note that", "It's crucial to understand" — these are AI padding. Delete them. They add nothing.
+
+**Contraction consistency — mix intentionally.** Uniform contraction use (100% contractions OR 100% expanded) is an AI signal. Real humans are inconsistent. Use "don't" in one sentence and "does not" three sentences later. The inconsistency IS the authenticity signal. Check the voice frame or profile for specific guidance.
+
+**Colon density — cap usage.** AI overuses colons. Cap at 1 per 400-500 words depending on the voice frame. Business Framed and Provocateur: no colons at all. Authority: 1 per post. Long-form frames: 1 per 400-500 words.
+
+**Register uniformity — break it.** AI maintains a single consistent register throughout. Real writing mixes formal vocabulary with casual asides, academic precision with colloquial reactions. Intentionally vary register within a piece. This is the "bidirectional sophistication" principle from empirical testing (GPTZero 100% → 3%).
+
+---
+
+## Tier 2: Voice-Gated Checks (Check Profile First)
+
+These patterns are suspicious but may match the author's voice. Check the profile before fixing.
+
+- **AI vocabulary**: "additionally", "furthermore", "landscape", "tapestry", "interplay", "pivotal", "delve", "paradigm", "leverage", "robust", "seamlessly" — check every word against the author's diction. If they don't use it, you can't either
+- **Inflated significance**: "marking a pivotal moment", "a significant milestone" — does the author elevate this way? If not, cut it
+- **Vague attribution**: "Experts argue", "Studies show" — does the author cite this way or make direct claims?
+- **Formula transitions**: "Despite these challenges", "Future Outlook", "In conclusion", "Moreover", "Furthermore" — does the author use these? Check discourse rules
+- **Rule of three**: Forcing ideas into triplets. Some authors do this naturally (check rhetoric rules). If not, break it
+- **Elegant variation**: Cycling synonyms — "the man...the individual...the person." Use whatever the author would repeat
+- **Sentence length uniformity**: AI defaults to medium-length sentences. Check your short/medium/long/very-long percentages against the author's distribution. Force variation to match
+- **Too-clean structure**: AI writes perfect essay structure. Real writing has asides, interruptions, unexpected turns. Match the author's discourse patterns
+- **Uniform paragraph length**: AI writes ~3-4 sentence paragraphs consistently. Match the author's paragraph rhythm from samples
+- **Mid-formal default**: AI gravitates toward neutral professional register. Match the author's register exactly, even if blunt, profane, or fragmentary
+- **Hedging where the author asserts**: "could potentially", "it might be argued" — if the rhetoric rules say direct claims, delete all hedging
+
+---
+
+## Final Check
+
+Re-read the complete output:
+1. Count em-dashes. No profile: should be zero. With profile: does the count match the author's observed frequency? Convert any excess
+2. Scan for any contrastive formula. Rewrite if found
+3. Grep for nuclear phrases. Kill any survivors
+4. Check contraction consistency. Are contractions mixed inconsistently (not 100% one way)?
+5. Count colons. Within the frame's limit?
+6. Check register variation. Is the tone monotonously consistent, or does it mix naturally?
+7. Scan for copula inflation ("serves as", "boasts", "underscores"). Simplify to plain verbs
+8. Would a reader who knows this author believe they wrote this?
+9. Does any sentence sound like "AI writing" rather than this specific person?
+
+If anything fails, rewrite that section. Don't patch — rewrite using the samples as reference.