openwriter 0.40.1 → 0.40.3

package/dist/server/mcp.js

@@ -23,7 +23,7 @@ import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBackl
 import { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastPendingMetadataChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged, broadcastActivityEvent } from './ws.js';
 import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
-import { findDocNode } from './workspace-tree.js';
+import { findDocNode, findContainer } from './workspace-tree.js';
 import { importGoogleDoc } from './gdoc-import.js';
 import { toCompactFormat, compactNodes, parseMarkdownContent } from './compact.js';
 import matter from 'gray-matter';
@@ -484,12 +484,14 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'create_document',
-        description: 'Create a new document. content_type is REQUIRED — use "document" for plain docs, or "tweet"/"reply"/"quote"/"article"/"linkedin"/"newsletter"/"blog" for typed docs. Always provide a title. By default shows a sidebar spinner — call populate_document next to deliver content and clear it. This two-step flow is REQUIRED for all content documents: create_document → populate_document. Use empty=true ONLY for typed docs (tweets, articles) that start blank and get written to incrementally via write_to_pad. If workspace is provided, the doc is automatically added to it (workspace is created if it doesn\'t exist). If container is also provided, the doc is placed inside that container (created if it doesn\'t exist).',
+        description: 'Create a new document. content_type is REQUIRED — use "document" for plain docs, or "tweet"/"reply"/"quote"/"article"/"linkedin"/"newsletter"/"blog" for typed docs. Always provide a title. By default shows a sidebar spinner — call populate_document next to deliver content and clear it. This two-step flow is REQUIRED for all content documents: create_document → populate_document. Use empty=true ONLY for typed docs (tweets, articles) that start blank and get written to incrementally via write_to_pad. Placement accepts EITHER convention: name-based auto-create (workspace title + container name, created if absent) OR id-based targeting of existing items (workspaceFile + containerId, the same ids move_item/get_workspace_structure use). A placement param that cannot be honored (unknown workspaceFile/containerId, or a container with no workspace) is a hard error — the doc is never silently created unplaced. The result always states where the doc landed, or "UNFILED".',
         schema: {
             title: z.string().optional().describe('Title for the new document. Defaults to "Untitled".'),
             path: z.string().optional().describe('Absolute file path to create the document at (e.g. "C:/projects/doc.md"). If omitted, creates in ~/.openwriter/.'),
             workspace: z.string().optional().describe('Workspace title to add this doc to. Creates the workspace if it doesn\'t exist.'),
             container: z.string().optional().describe('Container name within the workspace (e.g. "Chapters", "Notes", "References"). Creates the container if it doesn\'t exist. Requires workspace.'),
+            workspaceFile: z.string().optional().describe('Existing workspace by manifest filename (the *.json id used by move_item / get_workspace_structure). Id-based alternative to "workspace" (title). Must already exist — errors if not found. Use when you already hold the workspaceFile from another tool.'),
+            containerId: z.string().optional().describe('Existing container by id (8-char hex, as used by move_item / get_workspace_structure). Id-based alternative to "container" (name). Must already exist in the resolved workspace — errors if not found. Requires a workspace (workspaceFile or workspace).'),
             empty: z.boolean().optional().describe('ONLY for content_type template docs (tweets, articles) that start blank. Skips the spinner and switches immediately. Do NOT set this for content documents — use the two-step flow (create_document → populate_document) instead.'),
             content_type: z.enum(['document', 'tweet', 'reply', 'quote', 'article', 'linkedin', 'newsletter', 'blog', 'manuscript']).describe('Required. Use "document" for plain documents. Tweet/reply/quote/article/linkedin/newsletter/blog set type-specific metadata automatically. "manuscript" = a binding doc whose body is an ordered list of [text](doc:ID) pointers under ## chapter headings; populate it with the manifest, then it compiles to EPUB/DOCX via the manuscript routes.'),
             url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote" (e.g. "https://x.com/user/status/123"). Sets tweetContext.url automatically. Ignored for other content types.'),
@@ -498,7 +500,7 @@ export const TOOL_REGISTRY = [
             masterDocId: z.string().optional().describe('Make this doc a VARIANT of another doc. Pass the master doc\'s docId (8-char hex). The variant nests under its master in the sidebar (expandable tree). Use when creating a derivative — e.g. a tweet thread from a blog post. Pair with variantType. See docs/variants.md.'),
             variantType: z.string().optional().describe('Label for what kind of variant this is (e.g. "tweet", "blog", "linkedin"). Shows as a badge in the sidebar. Only meaningful alongside masterDocId.'),
         },
-        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId, status, masterDocId, variantType }) => {
+        handler: async ({ title, path, workspace, container, workspaceFile, containerId, empty, content_type, url, afterId, status, masterDocId, variantType }) => {
             // Require url for reply/quote
             if ((content_type === 'reply' || content_type === 'quote') && !url) {
                 return { content: [{ type: 'text', text: `Error: content_type "${content_type}" requires a url parameter (e.g. "https://x.com/user/status/123").` }] };
@@ -511,17 +513,69 @@ export const TOOL_REGISTRY = [
                 };
                 title = typeDefaults[content_type];
             }
-            // Resolve workspace/container up front so spinner renders in the right place
+            // Resolve placement up front so the spinner renders in the right place.
+            // Accept BOTH addressing conventions: the id-based one used across the rest
+            // of the API (workspaceFile + containerId, targeting EXISTING items) and the
+            // name-based auto-create one (workspace title + container name). Whichever is
+            // given is resolved; a placement param that cannot be honored is a HARD ERROR
+            // rather than a silent drop that orphans the doc.
+            // adr: adr/create-document-placement-contract.md
             let wsTarget;
-            if (workspace) {
-                const ws = findOrCreateWorkspace(workspace);
-                let containerId = null;
-                if (container) {
-                    const c = findOrCreateContainer(ws.filename, container);
-                    containerId = c.containerId;
+            if (workspace || workspaceFile || container || containerId) {
+                // 1. Resolve the workspace. Prefer the explicit id (workspaceFile).
+                let wsFilenameResolved = null;
+                if (workspaceFile) {
+                    try {
+                        getWorkspace(workspaceFile);
+                    }
+                    catch {
+                        return { content: [{ type: 'text', text: `Error: create_document workspaceFile "${workspaceFile}" not found. Pass an existing workspace .json filename, or use "workspace" (title) to create one by name.` }] };
+                    }
+                    wsFilenameResolved = workspaceFile;
+                }
+                else if (workspace) {
+                    wsFilenameResolved = findOrCreateWorkspace(workspace).filename;
+                }
+                // 2. A container was requested but the workspace couldn't be resolved.
+                //    Previously silently dropped — now a hard error.
+                if ((container || containerId) && !wsFilenameResolved) {
+                    return { content: [{ type: 'text', text: `Error: create_document was given a container but no workspace. Pass "workspaceFile" (existing) or "workspace" (title, auto-created) alongside the container.` }] };
+                }
+                // 3. Resolve the container within that workspace.
+                let resolvedContainerId = null;
+                if (wsFilenameResolved) {
+                    if (containerId) {
+                        const wsObj = getWorkspace(wsFilenameResolved);
+                        if (!findContainer(wsObj.root, containerId)) {
+                            return { content: [{ type: 'text', text: `Error: create_document containerId "${containerId}" not found in workspace ${wsFilenameResolved}. Pass an existing containerId, or use "container" (name) to create one.` }] };
+                        }
+                        resolvedContainerId = containerId;
+                    }
+                    else if (container) {
+                        resolvedContainerId = findOrCreateContainer(wsFilenameResolved, container).containerId;
+                    }
+                    wsTarget = { wsFilename: wsFilenameResolved, containerId: resolvedContainerId };
+                    broadcastWorkspacesChanged(); // Browser sees container structure before spinner
+                }
+            }
+            // Always state the final placement in the result, so a doc that lands in no
+            // workspace says so loudly (UNFILED) — an unplaced doc can never read as a
+            // bland success again. adr: brief 2026-07-09-create-document-placement-contract.
+            let placement = ' (UNFILED — not added to any workspace; lives at ~/.openwriter)';
+            if (wsTarget) {
+                let wsLabel = wsTarget.wsFilename;
+                let cLabel = '';
+                try {
+                    const wsObj = getWorkspace(wsTarget.wsFilename);
+                    wsLabel = wsObj.title || wsTarget.wsFilename;
+                    if (wsTarget.containerId) {
+                        const found = findContainer(wsObj.root, wsTarget.containerId);
+                        if (found)
+                            cLabel = ` / ${found.node.name}`;
+                    }
                 }
-                wsTarget = { wsFilename: ws.filename, containerId };
-                broadcastWorkspacesChanged(); // Browser sees container structure before spinner
+                catch { /* keep filename */ }
+                placement = ` → workspace "${wsLabel}"${cLabel}`;
             }
             // Track the spinner key so catch can clear exactly this entry
             // (not siblings from a concurrent declare_writes).
@@ -552,13 +606,11 @@ export const TOOL_REGISTRY = [
                             Object.assign(initMeta, typeMeta);
                     }
                     setMetadata(initMeta);
-                    let wsInfo = '';
                     if (wsTarget) {
                         // Resolve afterId: it may be a docId (8-char hex) or containerId.
                         // filenameByDocId resolves docId→filename; if null, treat as containerId.
                         const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
                         addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
-                        wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                     }
                     const newDocId = getDocId();
                     save('agent');
@@ -576,7 +628,7 @@ export const TOOL_REGISTRY = [
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Created "${result.title}" [${newDocId}]${wsInfo}${content_type ? ` (${content_type})` : ''} — ready.`,
+                                text: `Created "${result.title}" [${newDocId}]${placement}${content_type ? ` (${content_type})` : ''} — ready.`,
                             }],
                     };
                 }
@@ -587,11 +639,9 @@ export const TOOL_REGISTRY = [
                 const typeMeta = content_type ? resolveTypeMeta(content_type, url) : undefined;
                 const initialMeta = { ...statusMeta, ...variantMeta, ...(typeMeta || {}) };
                 const result = createDocumentFile(title, path, initialMeta);
-                let wsInfo = '';
                 if (wsTarget) {
                     const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
                     addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
-                    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
@@ -610,7 +660,7 @@ export const TOOL_REGISTRY = [
                 return {
                     content: [{
                             type: 'text',
-                            text: `Created "${result.title}" [${result.docId}]${wsInfo} — empty. Call populate_document with docId "${result.docId}" to add content.`,
+                            text: `Created "${result.title}" [${result.docId}]${placement} — empty. Call populate_document with docId "${result.docId}" to add content.`,
                         }],
                 };
             }

package/dist/server/sync-routes.js

@@ -0,0 +1,75 @@
+/**
+ * Express routes for GitHub sync.
+ * Mounted in index.ts — follows version-routes.ts pattern.
+ */
+import { Router } from 'express';
+import { getSyncStatus, getCapabilities, getPendingFiles, setupWithGh, setupWithPat, connectExisting, pushSync, } from './git-sync.js';
+export function createSyncRouter(broadcastSyncStatus) {
+    const router = Router();
+    router.get('/api/sync/status', async (_req, res) => {
+        try {
+            res.json(await getSyncStatus());
+        }
+        catch (err) {
+            res.status(500).json({ state: 'error', error: err.message });
+        }
+    });
+    router.get('/api/sync/capabilities', async (_req, res) => {
+        try {
+            res.json(await getCapabilities());
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.get('/api/sync/pending', async (_req, res) => {
+        try {
+            res.json(await getPendingFiles());
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post('/api/sync/setup', async (req, res) => {
+        try {
+            const { method, repoName, remoteUrl, pat, isPrivate } = req.body;
+            if (method === 'gh') {
+                await setupWithGh(repoName || 'openwriter-docs', isPrivate !== false);
+            }
+            else if (method === 'pat') {
+                if (!pat) {
+                    res.status(400).json({ error: 'PAT is required' });
+                    return;
+                }
+                await setupWithPat(pat, repoName || 'openwriter-docs', isPrivate !== false);
+            }
+            else if (method === 'connect') {
+                if (!remoteUrl) {
+                    res.status(400).json({ error: 'Remote URL is required' });
+                    return;
+                }
+                await connectExisting(remoteUrl, pat);
+            }
+            else {
+                res.status(400).json({ error: 'Invalid method. Use: gh, pat, or connect' });
+                return;
+            }
+            const status = await getSyncStatus();
+            broadcastSyncStatus(status);
+            res.json({ success: true, status });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post('/api/sync/push', async (_req, res) => {
+        try {
+            const result = await pushSync(broadcastSyncStatus);
+            res.json(result);
+        }
+        catch (err) {
+            res.status(500).json({ state: 'error', error: err.message });
+        }
+    });
+    return router;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.40.1",
+  "version": "0.40.3",
   "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.18.0"
+  version: "0.19.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -201,7 +201,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `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_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace) |
+| `move_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace). To nest a doc into a container: `move_item({ type: 'doc', workspaceFile, itemId: <docId>, targetContainerId: <containerId>, afterId? })`. The target param is **`targetContainerId`** — passing `containerId`/`container` instead is silently ignored and the doc lands at workspace root. |
 | `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
 ### Enrichment (three-field schema — v0.19.0)
@@ -328,21 +328,29 @@ The user can turn on **auto-accept** on a per-doc basis (right-click the doc in
 
 ### Workspace-Integrated Creation
 
-`create_document` accepts optional `workspace` and `container` parameters for direct workspace placement:
+`create_document` takes placement in **either** convention (unified 2026-07-09):
 
 ```
 create_document({
   title: "Opening Chapter",
   content_type: "document",          ← REQUIRED: "document" for plain, or "tweet"/"article"/etc.
-  workspace: "The Immortal",        ← creates workspace if it doesn't exist
-  container: "Chapters"             ← creates container if it doesn't exist
+  workspace: "The Immortal",        ← name-based: creates workspace if it doesn't exist
+  container: "Chapters"             ← name-based: creates container if it doesn't exist
 })
 ```
 
+**Name-based (auto-create):**
 - **`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`.
-- **`afterId`** (string, optional) — docId (8-char hex) or containerId to place the new doc immediately after. Omit and the doc lands at the **bottom** of its parent (the default since 0.18.0, matching the ascending-order convention: oldest at top, newest at bottom). Use `afterId` when you need surgical placement — e.g. inserting a new chapter doc immediately after the chapter's Beats doc.
-- All three are optional — omit `workspace` for standalone docs outside any workspace.
+
+**Id-based (target existing items — the same ids `move_item`/`get_workspace_structure` use):**
+- **`workspaceFile`** (string) — existing workspace manifest filename (`*.json`). Must already exist. Alternative to `workspace`.
+- **`containerId`** (string) — existing container id (8-char hex). Must already exist in the resolved workspace. Alternative to `container`. Requires a workspace param.
+
+**Both conventions:**
+- **`afterId`** (string, optional) — docId (8-char hex) or containerId to place the new doc immediately after. Omit and the doc lands at the **bottom** of its parent (the default since 0.18.0, matching the ascending-order convention: oldest at top, newest at bottom). `afterId` alone does NOT set a workspace — pass a workspace param too.
+- Omit all placement params for a standalone doc — the result then says **UNFILED** (a doc created in no workspace announces it, rather than reading as a bland success).
+- A placement that can't be honored (unknown `workspaceFile`/`containerId`, or a container with no workspace) is a **hard error** — the doc is never silently created unplaced. The result always states where it landed.
 
 This eliminates the need for separate `create_workspace`, `create_container`, and `move_item` calls when building up a workspace. The default-bottom landing also eliminates the need for a follow-up `move_item` pass to fix sidebar order after every create — the doc lands in convention position the first time.
 

package/skill/docs/enrichment.md

@@ -0,0 +1,180 @@
+# Enrichment Dispatch — Detailed Procedure
+
+OpenWriter's frontmatter enrichment is dispatched via the
+`openwriter-enrichment-minion` custom subagent. SKILL.md firm rule 5
+covers the common case (single minion, small/medium batch). This doc
+handles the **large-corpus case** where one minion isn't enough — and
+the parallel-dispatch pattern that scales it.
+
+## When to chunk
+
+| Dirty docs (N) | Dispatch shape | Wall time |
+|---|---|---|
+| 1–30 | Single minion. Default prompt. | ~10–45 seconds |
+| 31+  | Chunked parallel minions. | ~30 seconds (regardless of N) |
+
+The minion's turn budget (`maxTurns: 500` in its frontmatter) can handle
+~50 docs serially, but at that size the wall-clock cost (3+ minutes)
+becomes visible to the user. Parallel dispatch keeps total wall time
+under ~30 seconds for any corpus size up to a few hundred docs.
+
+## Step-by-step (large corpus)
+
+### 1. Inventory the work
+
+```
+mcp__openwriter__list_dirty_docs()
+```
+
+Returns every dirty doc across all workspaces with `docId`, `title`,
+`workspaceFile`, `reason`. If `total ≤ 30`, stop — single minion path
+(firm rule 5) is correct. If `total > 30`, continue.
+
+### 2. Chunk the work
+
+v0.19.0 simplified the minion to logline-only — workspace vocab is no
+longer relevant (the `domain` field that used it was dropped). You can
+group chunks however you want; workspace-grouping is no longer required.
+Practical defaults:
+
+**Target: 12–15 docs per chunk.**
+
+- **Very large dirty list (>100 docs):** split into chunks of ~15.
+- **Workspace-grouped is still fine** if it makes the dispatch prompts
+  easier to read, but it's no longer a performance concern.
+
+You'll typically land on 4–10 chunks. Don't exceed ~10 parallel —
+Anthropic per-account rate limits kick in beyond that and you get
+serialized anyway.
+
+### 3. Dispatch all chunks in one message
+
+Send **every chunk in a single assistant message** with multiple `Agent`
+tool uses. This is the only way they actually run in parallel —
+sequential `Agent` calls block each other.
+
+Use `run_in_background: true` so you can keep talking to the user while
+the minions work. You'll receive a `<task-notification>` per chunk as
+each one finishes.
+
+### 4. Prompt format (explicit-list mode)
+
+The minion's agent file (`~/.claude/agents/openwriter-enrichment-minion.md`)
+supports an explicit-list mode — pass docIds in the prompt and the minion
+skips `list_dirty_docs` and uses your list directly.
+
+Example prompt for one chunk (v0.19.0 — logline-only):
+
+```
+Enrich these specific openwriter docs:
+
+- a1b2c3d4 — Onboarding Email Sequence
+- e5f6a7b8 — Why We Sleep — Ch 2 Notes
+- 9z8y7x6w — Product Launch Checklist
+- 1q2w3e4r — Ch 3 — Beats
+- 5t6y7u8i — Ch 4 — Draft
+
+For each: read_pad to get the body, write a logline ≤150 chars, then
+bulk mark_enriched at the end with { docId, logline } per entry.
+```
+
+Keep prompts short. The minion already knows the procedure from its
+agent file — you're just handing it the work list. The minion's tool
+allowlist (v0.19.0) is `list_dirty_docs`, `read_pad`, `mark_enriched`
+— `get_workspace_structure` is no longer needed because there's no
+workspace-vocab dependency.
+
+### 5. Surface to the user (large-batch phrasing)
+
+Before dispatching, tell the user what's happening. Firm rule 5's
+"large batch" tier (N > 20) requires a heads-up. Example:
+
+> OpenWriter detected 73 docs that haven't been summarized yet —
+> first-time setup. Refreshing them in 6 parallel batches in the
+> background; this'll take ~30 seconds and a few cents of Haiku usage.
+
+Then dispatch. Stay silent as notifications come in unless one fails.
+When all are done, report once:
+
+> Enrichment complete: 73 docs across 8 workspaces. Cost: ~$0.15.
+
+### 6. Verify completion
+
+After every chunk has notified, call `list_dirty_docs` once more. If
+`total > 0`, some docs slipped — usually because a minion errored on a
+specific doc or a doc was modified mid-enrichment. Re-dispatch a single
+minion for the stragglers; don't redo the whole batch.
+
+## Why this shape
+
+**Why parallel, not serial single-minion at maxTurns: 500?**
+A single minion processing 100 docs takes 3+ minutes wall time. The
+user sits in silence. Six parallel minions of ~15 docs each finish in
+~30 seconds. Same total token cost — much better UX.
+
+**Why explicit docId list instead of letting each minion call `list_dirty_docs`?**
+Race conditions. If you spawn 6 minions and they all call
+`list_dirty_docs`, they all see the same 100 dirty docs and try to
+enrich the same docs in parallel. Most enrichments succeed (last write
+wins on the frontmatter), but it's wasteful and the per-doc baselines
+get computed multiple times. Explicit lists partition the work cleanly.
+
+**Why 12–15 docs per chunk and not 50?**
+Two reasons: (1) turn budget — each doc costs ~1 turn (one `read_pad`
+call); ~15 docs leaves headroom inside the 500-turn ceiling even with
+retries. (2) failure isolation — if one minion's batch errors, you lose
+15 docs of work, not 50.
+
+**Why dispatch in one message, not sequential Agent calls?**
+Sequential `Agent` calls block each other. Only multiple `Agent` tool
+uses in the **same assistant message** run truly in parallel.
+
+## Cost ballpark
+
+Haiku token cost per doc: ~1.5K–3K in v0.19.0 (one read_pad + one
+logline synthesis + share of mark_enriched). Roughly half what it cost
+under v0.16's five-field schema.
+
+| Corpus size | Approx cost (v0.19.0) |
+|---|---|
+| 30 docs   | ~$0.02 |
+| 100 docs  | ~$0.08 |
+| 500 docs  | ~$0.40 |
+
+Compare to ~$5.00 per doc if you used the general-purpose subagent with
+full MCP tool registry (~50K token overhead per spawn). The custom
+minion's tool allowlist (3 tools in v0.19.0: `list_dirty_docs`,
+`read_pad`, `mark_enriched`) is what makes the math work.
+
+## Failure modes
+
+- **Minion returns with no `mark_enriched` call** — almost always means
+  it hit the turn ceiling. Confirm its agent file has `maxTurns: 500`
+  in the frontmatter, then reduce chunk size to ~10 docs and re-dispatch
+  that chunk.
+- **Minion reports "No enrichment work pending"** — its assigned docs
+  got enriched by a sibling minion first (race condition from
+  `list_dirty_docs` mode, not explicit-list mode). Benign; the other
+  minion's work landed correctly.
+- **`<task-notification>` reports an error** — re-dispatch just that
+  one chunk. Don't restart the whole batch.
+- **Logline cap violations** — the minion's agent file enforces a
+  150-char hard cap. If you spot longer loglines on disk after the
+  fact, it's a minion regression — flag for agent-file revision rather
+  than re-enriching.
+
+## When NOT to chunk
+
+If `list_dirty_docs` returns ≤30 docs, dispatch a single minion with
+the default prompt:
+
+```
+Agent({
+  subagent_type: "openwriter-enrichment-minion",
+  description: "Enrich stale openwriter docs",
+  prompt: "Enrich all currently stale openwriter docs."
+})
+```
+
+The minion calls `list_dirty_docs` itself, processes everything in one
+pass, and reports back. Chunking ≤30 docs is overhead, not gain.

package/skill/docs/footnotes.md

@@ -0,0 +1,178 @@
+# Footnotes — Author Guide for Agents
+
+OpenWriter supports CommonMark / Pandoc footnote syntax for citation-heavy
+long-form writing. The editor renders inline references as superscript
+chips and corrals definitions into an end-of-doc "Footnotes" section.
+
+This doc explains how to write footnotes via MCP tools and what to expect
+on disk and in the editor.
+
+## The syntax (Pandoc / CommonMark)
+
+Two parts:
+
+- **Reference** (inline): `text[^N]` — appears in the prose
+- **Definition** (block): `[^N]: footnote text` — appears at end of doc
+
+Labels can be numeric or mnemonic:
+
+```markdown
+The body repairs itself during deep sleep[^1] too.
+
+Per Sapolsky[^sapolsky2017], stress responses follow a pattern.
+
+[^1]: Eibl-Eibesfeldt 1973, replicated and extended by Galati et al. 2003.
+
+[^sapolsky2017]: Sapolsky, R. (2017). *Behave*. Penguin Press.
+```
+
+The author label (`1` or `sapolsky2017`) is what pairs reference to
+definition. **Display numbering is automatic** — the editor's CSS counter
+shows sequential `[1] [2] [3]` regardless of label. Mnemonic labels stay
+on disk for human-readable file diffs.
+
+## How to write footnotes from MCP
+
+Just include the syntax in your markdown content — no special tool needed.
+
+### populate_document (initial draft)
+
+```ts
+populate_document({
+  docId: "abc12345",
+  content: `# Chapter 1
+
+Theory of mind develops late[^1] in non-human primates.
+
+[^1]: Premack & Woodruff (1978), Behavioral and Brain Sciences 1: 515–526.
+`
+})
+```
+
+The parser handles `[^1]` references and `[^1]: ...` definitions. The
+editor renders the reference as a superscript chip and the definition
+inside an end-of-doc "Footnotes" section.
+
+### write_to_pad (adding to existing doc)
+
+To add a new footnote to existing prose, you have two paths.
+
+**Append a new reference + definition together** (recommended):
+
+```ts
+// Step 1: rewrite the paragraph to add the reference
+write_to_pad({
+  docId: "abc12345",
+  changes: [
+    {
+      operation: "rewrite",
+      nodeId: "para_id",
+      content: "The same sentence now with a new claim[^2]."
+    }
+  ]
+})
+
+// Step 2: append the definition. If the doc already has a footnoteSection,
+// you can insert the definition inside it via afterNodeId pointing at the
+// last definition. If the doc has no footnotes yet, the parser auto-creates
+// the section when it sees `[^N]: ...` at the end of the markdown body.
+```
+
+**Simpler: just include both the reference and the definition in one
+write_to_pad call**:
+
+```ts
+write_to_pad({
+  docId: "abc12345",
+  changes: [
+    {
+      operation: "rewrite",
+      nodeId: "para_id",
+      content: "Sentence with new claim[^2]."
+    },
+    {
+      operation: "insert",
+      afterNodeId: "end",
+      content: "[^2]: Smith et al. (2020), Nature 580: 142–148."
+    }
+  ]
+})
+```
+
+The serializer normalizes definitions to the end-of-doc `footnoteSection`
+regardless of where they're inserted in the tree.
+
+## What you see in `read_pad`
+
+```
+title: My Chapter
+id: abc12345
+words: 423
+pending: 0
+---
+[h1:aa0001] Chapter 1
+[p:bb0002] Theory of mind develops late[^1] in non-human primates.
+[fnsec:cc0003]
+  [fndef:dd0004] [^1]: Premack & Woodruff (1978), Behavioral and Brain Sciences 1: 515–526.
+```
+
+The `[^N]` in the body is the inline reference. `[fnsec:...]` is the
+end-of-doc section. `[fndef:...]` is each definition.
+
+## Per-doc scope — important
+
+**Footnote labels are local to each doc.** Chapter 3's `[^1]` does not
+refer to Chapter 4's `[^1]`. Each chapter is its own `.md` file with its
+own numbering. Cross-chapter references are not supported at the editor
+level (a future book-export pipeline will handle global numbering at
+typeset time).
+
+If the author writes "see Ch 1 note 4" they're writing prose, not a
+cross-doc footnote link.
+
+## Multi-paragraph definitions
+
+Pandoc allows multi-paragraph footnotes via 4-space-indented continuation:
+
+```markdown
+[^1]: First paragraph of the definition.
+
+    Continuation paragraph, indented 4 spaces.
+
+    Another continuation.
+```
+
+The editor preserves the multi-paragraph structure inside the definition.
+Use this for footnotes that need substantial explanation (lengthy
+methodology notes, multi-source citations, etc.).
+
+## What's NOT supported (yet)
+
+- **Cross-doc footnote references.** Each doc has its own numbering.
+- **Bibliography auto-generation.** Authors manage citation text inline.
+  Zotero / Mendeley / BibTeX integration is a future enhancement.
+- **DOI auto-resolution.** Footnote text is plain — paste a DOI manually.
+- **Per-page footnotes (Phase 3).** The editor uses end-of-doc placement;
+  per-page placement is a print-layout concern handled at book-export
+  time, not in the editor.
+
+## When to use footnotes vs inline parentheticals
+
+Use footnotes when:
+- The citation count exceeds ~3 per ~500 words (inline parentheticals
+  start visibly disrupting the prose at that density)
+- The audience expects an academic register (popular nonfiction in the
+  Sapolsky / Wrangham / Pinker lineage)
+- The work targets book-class output (cumulative citation load at book
+  scale destroys readability under inline parentheticals)
+
+Use inline parentheticals when:
+- Citations are sparse (<1 per 500 words) and short
+- The author prefers a journalistic register
+- The work is short-form (tweet thread, blog post) where there's no
+  end-of-doc section to defer to
+
+## Reference docs (for the editor maintainers, not agents)
+
+- `docs/footnotes.md` (in the openwriter repo): full architecture
+- `adr/footnote-system.md`: load-bearing invariants + decision log