openwriter 0.40.1 → 0.40.2

package/dist/plugins/x-api/dist/index.js

@@ -0,0 +1,368 @@
+/**
+ * X API plugin for OpenWriter.
+ * Registers routes for checking X connection status and posting tweets.
+ * Uses @xdevplatform/xdk with OAuth1 credentials from plugin config.
+ */
+import { Client, OAuth1 } from '@xdevplatform/xdk';
+import { join, extname } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import sharp from 'sharp';
+import twitter from 'twitter-text';
+import { getServerBridge } from './server-bridge.js';
+const { parseTweet } = twitter;
+/** X Articles API base. Two-step: draft, then publish. */
+const X_API_BASE = 'https://api.x.com/2';
+/** Build the OAuth1 signer from plugin config / env. Returns null when any of
+ *  the four credentials is missing. Shared by the SDK client and the raw
+ *  Articles calls (which the SDK doesn't model). */
+function createOAuth1(config) {
+    const apiKey = config['api-key'] || process.env.X_API_KEY || '';
+    const apiSecret = config['api-secret'] || process.env.X_API_SECRET || '';
+    const accessToken = config['access-token'] || process.env.X_ACCESS_TOKEN || '';
+    const accessTokenSecret = config['access-token-secret'] || process.env.X_ACCESS_TOKEN_SECRET || '';
+    if (!apiKey || !apiSecret || !accessToken || !accessTokenSecret)
+        return null;
+    return new OAuth1({
+        apiKey,
+        apiSecret,
+        callback: 'oob',
+        accessToken,
+        accessTokenSecret,
+    });
+}
+function createXClient(config) {
+    const oauth1 = createOAuth1(config);
+    if (!oauth1)
+        return null;
+    return new Client({ oauth1 });
+}
+/** Make an OAuth1-signed JSON request to the X API. The SDK has no Articles
+ *  resource, so we sign + fetch directly. `buildRequestHeader` correctly
+ *  excludes a JSON body from the OAuth1 signature base string. */
+async function xApiFetch(oauth1, method, path, body) {
+    const url = `${X_API_BASE}${path}`;
+    const bodyStr = body ? JSON.stringify(body) : '';
+    const authHeader = await oauth1.buildRequestHeader(method, url, bodyStr);
+    const headers = { Authorization: authHeader };
+    if (body)
+        headers['Content-Type'] = 'application/json';
+    const res = await fetch(url, { method, headers, body: body ? bodyStr : undefined });
+    const data = await res.json().catch(() => ({}));
+    return { ok: res.ok, status: res.status, data };
+}
+const plugin = {
+    name: '@openwriter/plugin-x-api',
+    version: '0.1.0',
+    description: 'Post tweets from OpenWriter',
+    category: 'social-media',
+    configSchema: {
+        'api-key': { type: 'string', env: 'X_API_KEY', description: 'X API Key' },
+        'api-secret': { type: 'string', env: 'X_API_SECRET', description: 'X API Secret' },
+        'access-token': { type: 'string', env: 'X_ACCESS_TOKEN', description: 'X Access Token' },
+        'access-token-secret': { type: 'string', env: 'X_ACCESS_TOKEN_SECRET', description: 'X Access Token Secret' },
+    },
+    registerRoutes(ctx) {
+        // GET /api/x/status — check if plugin is configured + authenticated
+        ctx.app.get('/api/x/status', async (_req, res) => {
+            try {
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.json({ connected: false });
+                    return;
+                }
+                const me = await client.users.getMe();
+                const username = me?.data?.username;
+                res.json({ connected: true, username: username || undefined });
+            }
+            catch (err) {
+                console.error('[X Plugin] Status check failed:', err.message);
+                res.json({ connected: false, error: err.message });
+            }
+        });
+        // POST /api/x/post — post a tweet (with optional media)
+        ctx.app.post('/api/x/post', async (req, res) => {
+            try {
+                const { text, replyTo, quoteTweetId, mediaIds } = req.body;
+                if ((!text || typeof text !== 'string') && (!Array.isArray(mediaIds) || mediaIds.length === 0)) {
+                    res.status(400).json({ success: false, error: 'text or mediaIds is required' });
+                    return;
+                }
+                if (mediaIds && (!Array.isArray(mediaIds) || mediaIds.length > 4)) {
+                    res.status(400).json({ success: false, error: 'mediaIds must be an array of 1-4 IDs' });
+                    return;
+                }
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                const body = {};
+                if (text)
+                    body.text = text;
+                if (replyTo) {
+                    body.reply = { inReplyToTweetId: replyTo };
+                }
+                if (quoteTweetId) {
+                    body.quoteTweetId = quoteTweetId;
+                }
+                if (mediaIds && mediaIds.length > 0) {
+                    body.media = { media_ids: mediaIds };
+                }
+                const result = await client.posts.create(body);
+                const tweetId = result?.data?.id;
+                const tweetUrl = tweetId ? `https://x.com/i/status/${tweetId}` : undefined;
+                res.json({ success: true, tweetId, tweetUrl });
+            }
+            catch (err) {
+                const detail = err.data ? JSON.stringify(err.data) : err.message;
+                console.error('[X Plugin] Post failed:', detail);
+                res.status(500).json({ success: false, error: detail });
+            }
+        });
+        // POST /api/x/post-thread — post a full thread as a reply chain (with optional media per tweet)
+        ctx.app.post('/api/x/post-thread', async (req, res) => {
+            try {
+                const { tweets, replyTo } = req.body;
+                if (!Array.isArray(tweets) || tweets.length === 0) {
+                    res.status(400).json({ success: false, error: 'tweets must be a non-empty array' });
+                    return;
+                }
+                // Normalize: accept string[] or { text, mediaIds? }[]
+                const normalized = tweets.map((t) => typeof t === 'string' ? { text: t, mediaIds: undefined } : t);
+                // Validate character limits using X's weighted counting (emojis=2, URLs=23, CJK=2)
+                const CHAR_LIMIT = 25000;
+                const overLimit = normalized.map((t, i) => ({ i, len: parseTweet(t.text).weightedLength })).filter(x => x.len > CHAR_LIMIT);
+                if (overLimit.length > 0) {
+                    res.status(400).json({
+                        success: false,
+                        error: `${overLimit.length} tweet(s) exceed ${CHAR_LIMIT} chars: ${overLimit.map(x => `#${x.i + 1} (${x.len})`).join(', ')}`,
+                    });
+                    return;
+                }
+                // Validate mediaIds per tweet
+                for (let i = 0; i < normalized.length; i++) {
+                    const ids = normalized[i].mediaIds;
+                    if (ids && (!Array.isArray(ids) || ids.length > 4)) {
+                        res.status(400).json({ success: false, error: `Tweet ${i + 1}: mediaIds must be an array of 1-4 IDs` });
+                        return;
+                    }
+                }
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                const postedTweets = [];
+                let previousTweetId = replyTo;
+                for (let i = 0; i < normalized.length; i++) {
+                    const { text, mediaIds } = normalized[i];
+                    const body = {};
+                    if (text)
+                        body.text = text;
+                    if (previousTweetId) {
+                        body.reply = { inReplyToTweetId: previousTweetId };
+                    }
+                    if (mediaIds && mediaIds.length > 0) {
+                        body.media = { media_ids: mediaIds };
+                    }
+                    const result = await client.posts.create(body);
+                    const tweetId = result?.data?.id;
+                    if (!tweetId) {
+                        res.status(500).json({
+                            success: false,
+                            postedTweets,
+                            failedAt: i,
+                            error: `Tweet ${i + 1} posted but no ID returned`,
+                        });
+                        return;
+                    }
+                    postedTweets.push({ index: i, tweetId, text });
+                    previousTweetId = tweetId;
+                }
+                // Build thread URL from first tweet
+                const firstTweetId = postedTweets[0]?.tweetId;
+                const threadUrl = firstTweetId ? `https://x.com/i/status/${firstTweetId}` : undefined;
+                console.log(`[X Plugin] Thread posted: ${postedTweets.length} tweets, ${threadUrl}`);
+                res.json({ success: true, postedTweets, threadUrl });
+            }
+            catch (err) {
+                console.error('[X Plugin] Post thread failed:', err.message);
+                res.status(500).json({ success: false, error: err.message });
+            }
+        });
+        // POST /api/x/upload-media — upload a local /_images/ file for tweet attachment
+        ctx.app.post('/api/x/upload-media', async (req, res) => {
+            try {
+                const { src } = req.body;
+                if (!src || typeof src !== 'string') {
+                    res.status(400).json({ success: false, error: 'src is required' });
+                    return;
+                }
+                // Security: only allow /_images/ paths, no traversal
+                if (!/^\/_images\/[^/\\]+$/.test(src)) {
+                    res.status(400).json({ success: false, error: 'Invalid image path — must be /_images/<filename>' });
+                    return;
+                }
+                const filename = src.replace('/_images/', '');
+                const filePath = join(ctx.dataDir, '_images', filename);
+                if (!existsSync(filePath)) {
+                    res.status(404).json({ success: false, error: `Image not found: ${filename}` });
+                    return;
+                }
+                const ext = extname(filename).toLowerCase();
+                const mimeMap = {
+                    '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                    '.png': 'image/png', '.webp': 'image/webp',
+                    '.gif': 'image/jpeg', '.bmp': 'image/bmp',
+                    '.tiff': 'image/tiff', '.tif': 'image/tiff',
+                };
+                const mediaType = mimeMap[ext] || 'image/jpeg';
+                const client = createXClient(ctx.config);
+                if (!client) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                let fileBuffer = readFileSync(filePath);
+                let uploadType = mediaType;
+                const origSize = fileBuffer.length;
+                // Compress large images or PNGs to JPEG to stay under X API limits
+                if (fileBuffer.length > 3 * 1024 * 1024 || ext === '.png') {
+                    fileBuffer = Buffer.from(await sharp(fileBuffer).jpeg({ quality: 85 }).toBuffer());
+                    uploadType = 'image/jpeg';
+                    console.log(`[X Plugin] Compressed ${filename}: ${(origSize / 1024 / 1024).toFixed(2)}MB → ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB`);
+                }
+                console.log(`[X Plugin] Uploading ${filename}: ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB, type: ${uploadType}`);
+                const mediaBase64 = fileBuffer.toString('base64');
+                const uploadResult = await client.media.upload({
+                    body: { media: mediaBase64, mediaCategory: 'tweet_image', mediaType: uploadType },
+                });
+                const mediaId = uploadResult?.data?.id
+                    || uploadResult?.media_id_string;
+                if (!mediaId) {
+                    res.status(500).json({ success: false, error: 'Upload succeeded but no media ID returned' });
+                    return;
+                }
+                console.log(`[X Plugin] Media uploaded: ${filename} → ${mediaId}`);
+                res.json({ success: true, mediaId });
+            }
+            catch (err) {
+                console.error('[X Plugin] Media upload failed:', err.message);
+                if (err.response) {
+                    try {
+                        const body = await err.response.text();
+                        console.error('[X Plugin] X API response:', err.response.status, body);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (err.data)
+                    console.error('[X Plugin] Error data:', JSON.stringify(err.data));
+                console.error('[X Plugin] Full error:', JSON.stringify(err, Object.getOwnPropertyNames(err)));
+                res.status(500).json({ success: false, error: err.message });
+            }
+        });
+        // POST /api/x/post-article — publish the active document as a native X
+        // Article. Two-step X flow: draft, then publish. Reads the active server
+        // doc (same source the managed/publish path reads) and converts it to X's
+        // DraftJS content_state via the shared converter.
+        ctx.app.post('/api/x/post-article', async (_req, res) => {
+            try {
+                const oauth1 = createOAuth1(ctx.config);
+                if (!oauth1) {
+                    res.status(400).json({ success: false, error: 'X API credentials not configured' });
+                    return;
+                }
+                const bridge = await getServerBridge();
+                const doc = bridge.getDocument();
+                const title = (bridge.getTitle() || '').trim();
+                const metadata = bridge.getMetadata() || {};
+                if (!title || title === 'Untitled') {
+                    res.status(400).json({ success: false, error: 'Article needs a title before posting.' });
+                    return;
+                }
+                const contentState = bridge.tiptapToDraftjs(doc);
+                if (!contentState.blocks.some((b) => (b.text || '').trim().length > 0)) {
+                    res.status(400).json({ success: false, error: 'Article body is empty.' });
+                    return;
+                }
+                // Optional cover image — upload to X and attach as cover_media.
+                let coverMedia;
+                const coverSrc = metadata?.articleContext?.coverImage;
+                if (coverSrc && typeof coverSrc === 'string' && /^\/_images\/[^/\\]+$/.test(coverSrc)) {
+                    const client = createXClient(ctx.config);
+                    if (client) {
+                        const mediaId = await uploadCoverMedia(client, ctx.dataDir, coverSrc);
+                        if (mediaId)
+                            coverMedia = { media_category: 'TWEET_IMAGE', media_id: mediaId };
+                    }
+                }
+                // Step 1 — create the draft.
+                const draftBody = { title, content_state: contentState };
+                if (coverMedia)
+                    draftBody.cover_media = coverMedia;
+                const draft = await xApiFetch(oauth1, 'POST', '/articles/draft', draftBody);
+                if (!draft.ok) {
+                    const detail = draft.data?.detail || draft.data?.title || JSON.stringify(draft.data);
+                    console.error('[X Plugin] Article draft failed:', draft.status, detail);
+                    res.status(draft.status || 500).json({ success: false, error: `Draft failed: ${detail}` });
+                    return;
+                }
+                const articleId = draft.data?.data?.id;
+                if (!articleId) {
+                    res.status(500).json({ success: false, error: 'Draft created but no article id returned.' });
+                    return;
+                }
+                // Step 2 — publish the draft (makes it public). Surface any error
+                // verbatim — a draft is private until this succeeds.
+                const published = await xApiFetch(oauth1, 'POST', `/articles/${articleId}/publish`);
+                if (!published.ok) {
+                    const detail = published.data?.detail || published.data?.title || JSON.stringify(published.data);
+                    console.error('[X Plugin] Article publish failed:', published.status, detail);
+                    res.status(published.status || 500).json({ success: false, articleId, error: `Publish failed: ${detail}` });
+                    return;
+                }
+                const postId = published.data?.data?.post_id;
+                const articleUrl = postId ? `https://x.com/i/status/${postId}` : undefined;
+                console.log(`[X Plugin] Article published: ${articleId} -> ${articleUrl}`);
+                res.json({ success: true, articleId, postId, articleUrl });
+            }
+            catch (err) {
+                const detail = err.data ? JSON.stringify(err.data) : err.message;
+                console.error('[X Plugin] Post article failed:', detail);
+                res.status(500).json({ success: false, error: detail });
+            }
+        });
+    },
+};
+/** Upload an article cover image to X, returning its media_id. Mirrors the
+ *  /api/x/upload-media compression rules (>3MB or PNG -> JPEG). Returns null on
+ *  any failure — the article still posts, just without a cover. */
+async function uploadCoverMedia(client, dataDir, src) {
+    try {
+        const filename = src.replace('/_images/', '');
+        const filePath = join(dataDir, '_images', filename);
+        if (!existsSync(filePath))
+            return null;
+        const ext = extname(filename).toLowerCase();
+        const mimeMap = {
+            '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+            '.png': 'image/png', '.webp': 'image/webp',
+            '.gif': 'image/jpeg', '.bmp': 'image/bmp',
+            '.tiff': 'image/tiff', '.tif': 'image/tiff',
+        };
+        let fileBuffer = readFileSync(filePath);
+        let uploadType = mimeMap[ext] || 'image/jpeg';
+        if (fileBuffer.length > 3 * 1024 * 1024 || ext === '.png') {
+            fileBuffer = Buffer.from(await sharp(fileBuffer).jpeg({ quality: 85 }).toBuffer());
+            uploadType = 'image/jpeg';
+        }
+        const uploadResult = await client.media.upload({
+            body: { media: fileBuffer.toString('base64'), mediaCategory: 'tweet_image', mediaType: uploadType },
+        });
+        return uploadResult?.data?.id || uploadResult?.media_id_string || null;
+    }
+    catch (err) {
+        console.error('[X Plugin] Cover upload failed:', err.message);
+        return null;
+    }
+}
+export default plugin;

package/dist/plugins/x-api/dist/server-bridge.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Thin runtime bridge to the OpenWriter server modules this plugin needs for
+ * article publishing — the active document, its title/metadata, the data dir,
+ * and the shared TipTap -> DraftJS converter.
+ *
+ * The converter (server/tiptap-draftjs.ts) is shared with plugins/publish so
+ * both posting paths produce identical X content_state. We import the compiled
+ * server module at runtime rather than vendoring it, resolving both the npm
+ * package layout and the monorepo layout — the same dual-path trick the publish
+ * plugin's helpers use.
+ */
+export interface ServerBridge {
+    getDocument: () => any;
+    getTitle: () => string;
+    getMetadata: () => Record<string, any>;
+    getDataDir: () => string;
+    tiptapToDraftjs: (doc: any) => {
+        blocks: any[];
+        entities: any[];
+    };
+}
+export declare function getServerBridge(): Promise<ServerBridge>;

package/dist/plugins/x-api/dist/server-bridge.js

@@ -0,0 +1,43 @@
+/**
+ * Thin runtime bridge to the OpenWriter server modules this plugin needs for
+ * article publishing — the active document, its title/metadata, the data dir,
+ * and the shared TipTap -> DraftJS converter.
+ *
+ * The converter (server/tiptap-draftjs.ts) is shared with plugins/publish so
+ * both posting paths produce identical X content_state. We import the compiled
+ * server module at runtime rather than vendoring it, resolving both the npm
+ * package layout and the monorepo layout — the same dual-path trick the publish
+ * plugin's helpers use.
+ */
+// npm package: dist/plugins/x-api/dist/server-bridge.js -> dist/server/
+// monorepo:    plugins/x-api/dist/server-bridge.js      -> packages/openwriter/dist/server/
+const npmBase = new URL('../../../server/', import.meta.url).href;
+const monoBase = new URL('../../../packages/openwriter/dist/server/', import.meta.url).href;
+let cached = null;
+async function tryImport(base) {
+    const [state, helpers, draftjs] = await Promise.all([
+        import(base + 'state.js'),
+        import(base + 'helpers.js'),
+        import(base + 'tiptap-draftjs.js'),
+    ]);
+    return { state, helpers, draftjs };
+}
+export async function getServerBridge() {
+    if (cached)
+        return cached;
+    let state, helpers, draftjs;
+    try {
+        ({ state, helpers, draftjs } = await tryImport(npmBase));
+    }
+    catch {
+        ({ state, helpers, draftjs } = await tryImport(monoBase));
+    }
+    cached = {
+        getDocument: state.getDocument,
+        getTitle: state.getTitle,
+        getMetadata: state.getMetadata,
+        getDataDir: helpers.getDataDir,
+        tiptapToDraftjs: draftjs.tiptapToDraftjs,
+    };
+    return cached;
+}

package/dist/plugins/x-api/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@openwriter/plugin-x-api",
+  "version": "0.1.0",
+  "description": "Post tweets from OpenWriter",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@xdevplatform/xdk": "^0.4.0",
+    "twitter-text": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "typescript": "^5.6.0"
+  },
+  "openwriter": {
+    "displayName": "X / Twitter",
+    "category": "social-media"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.40.1",
+  "version": "0.40.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",

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.