npm - openwriter - Versions diffs - 0.30.0 → 0.31.0 - Mend

openwriter 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/dist/client/assets/{index-BtCWWQrZ.css → index-C-eMDCqj.css} +1 -1
package/dist/client/assets/{index-D1naX68L.js → index-CaFrYDJP.js} +68 -68
package/dist/client/index.html +2 -2
package/dist/plugins/authors-voice/dist/index.js +29 -6
package/dist/plugins/github/dist/blog-tools.js +14 -2
package/dist/plugins/publish/dist/index.js +20 -0
package/dist/server/documents.js +37 -5
package/dist/server/mcp.js +6 -3
package/dist/server/plugin-manager.js +11 -1
package/dist/server/workspaces.js +6 -3
package/package.json +1 -1
package/skill/SKILL.md +16 -12
package/skill/agents/openwriter-sort-minion.md +184 -0

package/dist/client/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Charter:ital,wght@0,400;0,700;1,400&family=Crimson+Pro:ital,wght@0,300;0,400;0,600;0,700;1,400&family=DM+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=DM+Serif+Display&family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600&family=Inter:wght@400;500;600;700&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,600;0,7..72,700;1,7..72,400&family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,600;1,6..72,400&family=Playfair+Display:wght@400;600;700;900&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;0,8..60,700;1,8..60,400&family=Space+Grotesk:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-D1naX68L.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BtCWWQrZ.css">
+    <script type="module" crossorigin src="/assets/index-CaFrYDJP.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-C-eMDCqj.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/plugins/authors-voice/dist/index.js CHANGED Viewed

@@ -6,6 +6,27 @@
  * Sidebar document transforms (Vary / Shrinkify / Threadify / etc.) live in
  * @openwriter/plugin-publish — they go through the metered platform path.
  */
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const PLUGIN_NAME = '@openwriter/plugin-authors-voice';
+/**
+ * Live-read the model tier from ~/.openwriter/config.json per request.
+ * The host passes plugin config ONCE at registerRoutes and never reloads it on save, so the
+ * dropdown's value would otherwise require a server restart. Reading the file per request
+ * makes a model-picker change take effect on the very next Enhance. Falls back to the
+ * load-time value on any error.
+ */
+function liveModelTier(fallback) {
+    try {
+        const cfg = JSON.parse(readFileSync(join(homedir(), '.openwriter', 'config.json'), 'utf8'));
+        const v = cfg?.plugins?.[PLUGIN_NAME]?.config?.model;
+        return typeof v === 'string' ? v : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 const plugin = {
     name: '@openwriter/plugin-authors-voice',
     version: '0.4.0',
@@ -33,9 +54,9 @@ const plugin = {
             options: [
                 { value: '', label: 'Default (Strongest)' },
                 { value: 'strongest', label: 'Strongest — Claude Opus (best quality)' },
-                { value: 'gemini-pro', label: 'Gemini Pro — flagship, strong + cheap' },
                 { value: 'balanced', label: 'Balanced — Claude Sonnet' },
-                { value: 'fast', label: 'Fast — Gemini Flash (cheapest)' },
+                { value: 'fast-plus', label: 'Fast+ — Gemini 3.5 Flash (newest, great)' },
+                { value: 'fast', label: 'Fast — Gemini 2.5 Flash (cheapest)' },
             ],
         },
     },
@@ -55,12 +76,14 @@ const plugin = {
                 return body;
             return { ...body, debug: true };
         };
-        // Inject the user's model-tier pick. Pure pass-through: the AV API validates the slug
-        // and falls back to its own default if absent/unknown. Blank → nothing injected.
+        // Inject the user's model-tier pick, read LIVE per request (dropdown changes take effect
+        // immediately, no restart). Pure pass-through: the AV API validates the slug and falls
+        // back to its own default if absent/unknown. Blank → nothing injected.
         const withModel = (body) => {
-            if (!modelTier || !body || typeof body !== 'object')
+            const tier = liveModelTier(modelTier);
+            if (!tier || !body || typeof body !== 'object')
                 return body;
-            return { ...body, modelTier };
+            return { ...body, modelTier: tier };
         };
         // Wildcard proxy for /api/voice/* routes. Pure pass-through: the AV API owns the
         // engine choice (v1/v2) via its own AV_DEFAULT_ENGINE setting, so the plugin injects

package/dist/plugins/github/dist/blog-tools.js CHANGED Viewed

@@ -562,6 +562,18 @@ export function buildFrontmatter(title, blogCtx, site, coverImagePath) {
     if (!fm[dateDest] && !(publishedDateDest && fm[publishedDateDest])) {
         fm[dateDest] = new Date().toISOString().slice(0, 10);
     }
+    // Date fields emit as UNQUOTED yaml scalars (pubDate: 2026-05-31), never
+    // quoted strings. Astro's z.date() rejects a quoted value — js-yaml parses it
+    // as a String, not a Date — which froze a live Netlify build (paybotapp.com,
+    // 2026-06-01). The unquoted form is ALSO accepted by z.coerce.date() and by
+    // Jekyll/Hugo/Next (gray-matter), so it is the universally-correct emit.
+    // adr: adr/blog-image-contract.md
+    const dateKeys = new Set([dateDest]);
+    if (publishedDateDest)
+        dateKeys.add(publishedDateDest);
+    const emitLine = (k, v) => dateKeys.has(k) && typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v)
+        ? `${k}: ${v}`
+        : `${k}: ${yamlValue(v)}`;
     // Emit in stable order: defaults first (in their declared order),
     // then title, then any new keys we added
     const lines = [];
@@ -569,7 +581,7 @@ export function buildFrontmatter(title, blogCtx, site, coverImagePath) {
     if (site.frontmatter_defaults) {
         for (const k of Object.keys(site.frontmatter_defaults)) {
             if (k in fm) {
-                lines.push(`${k}: ${yamlValue(fm[k])}`);
+                lines.push(emitLine(k, fm[k]));
                 written.add(k);
             }
         }
@@ -581,7 +593,7 @@ export function buildFrontmatter(title, blogCtx, site, coverImagePath) {
     for (const [k, v] of Object.entries(fm)) {
         if (written.has(k))
             continue;
-        lines.push(`${k}: ${yamlValue(v)}`);
+        lines.push(emitLine(k, v));
         written.add(k);
     }
     return `---\n${lines.join('\n')}\n---\n\n`;

package/dist/plugins/publish/dist/index.js CHANGED Viewed

@@ -14,6 +14,17 @@ function extractDocId(rawContent) {
         return yamlMatch[1];
     return null;
 }
+/** Server-side backstop for the transform size guard. Mirrors the client-side
+ *  cap in packages/openwriter/src/sidebar/transform-guard.ts (same 5000-word unit)
+ *  so an oversized doc can't reach the model/publish worker even when a caller
+ *  bypasses the UI guard (agent, script, stale client). */
+const MAX_TRANSFORM_WORDS = 5000;
+/** Word count of a doc's body. Strips a leading YAML frontmatter block so the
+ *  count matches the body-only wordCount the sidebar measures client-side. */
+function countBodyWords(rawContent) {
+    const body = rawContent.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+    return (body.match(/\S+/g) || []).length;
+}
 /** Map transform action to variant content type */
 const ACTION_VARIANT_TYPE = {
     vary: 'document',
@@ -1038,6 +1049,15 @@ const plugin = {
                     res.status(400).json({ error: 'Document content is required' });
                     return;
                 }
+                // Size backstop — mirror the client-side transform guard. Block before the
+                // worker model call so an oversized doc can't run up unbounded cost + time,
+                // even when a caller bypasses the UI guard.
+                const transformWords = countBodyWords(content);
+                if (transformWords > MAX_TRANSFORM_WORDS) {
+                    console.warn(`[Publish Plugin] Transform blocked — doc too large: ${transformWords} words (max ${MAX_TRANSFORM_WORDS})`);
+                    res.status(413).json({ error: `Document too large to transform: ${transformWords.toLocaleString()} words (max ${MAX_TRANSFORM_WORDS.toLocaleString()}).` });
+                    return;
+                }
                 // Call publish worker /transforms endpoint
                 const transformRes = await publishFetch(ctx.config, '/transforms', {
                     method: 'POST',

package/dist/server/documents.js CHANGED Viewed

@@ -310,16 +310,22 @@ export function buildEnrichmentInstructions() {
     ].join('\n');
 }
 /** Footer on the three high-frequency discovery tools when sort requests are
- *  pending. Stacks beneath enrichmentFooter. Sorting is a judgment call —
- *  handle it inline in conversation, don't dispatch a subagent. */
+ *  pending. Stacks beneath enrichmentFooter. Carries the exact dispatch call
+ *  so the acting agent's burden collapses to one paste — the sort minion is
+ *  autonomous and self-discovers via list_pending_sorts once it boots, files
+ *  each doc, and reports what moved. The earlier "handle it inline, no minion"
+ *  model never drained (marks rotted for days); auto-drain replaces it.
+ *  adr: adr/sort-minion-drain.md */
 export function sortFooter() {
     const count = listPendingSorts().length;
     if (count === 0)
         return '';
-    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} awaiting sort. Call list_pending_sorts to handle inline — discuss destinations with the user, then either move + mark_sorted (when the user confirms in chat) or propose_sort (UI accept/reject for batches).`;
+    return `\n\n⚠ ${count} doc${count === 1 ? '' : 's'} awaiting sort. Dispatch:\nAgent(\n  subagent_type: "openwriter-sort-minion",\n  description: "File pending sorts",\n  prompt: "File pending sorts.",\n  run_in_background: true\n)`;
 }
 /** Session-start sort notice — stacks with buildEnrichmentInstructions inside
- *  the MCP `instructions` field. Empty when no sorts pending. */
+ *  the MCP `instructions` field. Empty when no sorts pending. Mirrors
+ *  buildEnrichmentInstructions: an executable dispatch directive, not advice.
+ *  adr: adr/sort-minion-drain.md */
 export function buildSortInstructions() {
     const pending = listPendingSorts();
     if (pending.length === 0)
@@ -327,7 +333,13 @@ export function buildSortInstructions() {
     return [
         '',
         `SORT_STATUS: ${pending.length} doc${pending.length === 1 ? '' : 's'} awaiting sort.`,
-        'Call list_pending_sorts when the user engages or you have a natural moment. For each doc: read it, pick a destination (get_workspace_structure for tree shape + container purpose: hints; browse for what other docs in a container are about). For 1–3 docs, discuss in chat then move_item + mark_sorted on confirmation. For many docs, write propose_sort entries and let the user accept/reject via the sidebar popover. Sorting is a judgment call — bias toward asking when a doc could plausibly live in two places.',
+        'Dispatch the minion now — it self-discovers via list_pending_sorts, picks a destination for each doc, files it (move_item), retires the request (mark_sorted), and reports what moved:',
+        'Agent(',
+        '  subagent_type: "openwriter-sort-minion",',
+        '  description: "File pending sorts",',
+        '  prompt: "File pending sorts.",',
+        '  run_in_background: true',
+        ')',
     ].join('\n');
 }
 /**
@@ -340,6 +352,7 @@ export function listPendingSorts(scopeWorkspace) {
     ensureDataDir();
     const ownership = buildWorkspaceOwnershipMap();
     const containerByFile = buildContainerOwnershipMap();
+    const optedOut = collectAutoSortOptedOutFilenames();
     let scopeFiles = null;
     if (scopeWorkspace) {
         try {
@@ -354,6 +367,8 @@ export function listPendingSorts(scopeWorkspace) {
     for (const f of readdirSync(getDataDir()).filter((f) => f.endsWith('.md'))) {
         if (scopeFiles && !scopeFiles.has(f))
             continue;
+        if (optedOut.has(f))
+            continue;
         try {
             const raw = readFileSync(join(getDataDir(), f), 'utf-8');
             const { data } = matter(raw);
@@ -416,6 +431,23 @@ function collectOptedOutFilenames() {
     }
     return out;
 }
+/** Build a Set of filenames inside workspaces with autoSortDisabled: true.
+ *  These docs are excluded from list_pending_sorts, so the sort minion never
+ *  auto-files them — the user handles them manually via the sidebar. */
+function collectAutoSortOptedOutFilenames() {
+    const out = new Set();
+    for (const info of listWorkspaces()) {
+        try {
+            const ws = getWorkspace(info.filename);
+            if (ws.autoSortDisabled === true) {
+                for (const f of collectAllFiles(ws.root))
+                    out.add(f);
+            }
+        }
+        catch { /* skip corrupt manifests */ }
+    }
+    return out;
+}
 /** Map filename → first workspace that contains it. Used to attribute
  *  dirty-doc reports to a workspace. */
 function buildWorkspaceOwnershipMap() {

package/dist/server/mcp.js CHANGED Viewed

@@ -1064,7 +1064,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_pending_sorts',
-        description: 'List documents that the user has marked for sorting via the sidebar. Each entry includes the doc identity, where it currently lives, the requestedAt timestamp, and (when present) a proposal already written by an earlier pass. Call this first to know what sort work is pending; for each entry, read the doc body, consider workspace/container purpose hints, and either discuss the destination with the user in chat (1–3 docs) or write a proposal via propose_sort (many docs → batch UI accept/reject).',
+        description: 'List documents the user marked for sorting via the sidebar. Each entry includes the doc identity, where it currently lives, the requestedAt timestamp, and (when present) a proposal from an earlier pass. The sort minion (openwriter-sort-minion) calls this first to know what to file. For each entry: read the body, consider workspace/container purpose hints, then move_item + mark_sorted to auto-file it. Docs in opted-out workspaces (autoSortDisabled: true) are excluded. propose_sort remains for the manual sidebar accept/reject flow.',
         schema: {
             workspaceFile: z.string().optional().describe('Scope to one workspace. Omit to scan all workspaces.'),
         },
@@ -1248,6 +1248,8 @@ export const TOOL_REGISTRY = [
             }
             if (ws.enrichmentDisabled === true)
                 headerBits.push('enrichment: disabled');
+            if (ws.autoSortDisabled === true)
+                headerBits.push('auto-sort: disabled');
             let text = `${headerBits.join('\n')}\nstructure:\n${treeLines.join('\n') || '  (empty)'}`;
             if (ws.context && Object.keys(ws.context).length > 0) {
                 text += `\ncontext:\n${JSON.stringify(ws.context, null, 2)}`;
@@ -1298,7 +1300,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'update_workspace_context',
-        description: 'Update workspace configuration. Accepts writing context (characters, settings, rules — merged into existing) plus enrichment fields (logline, domain, schema, vocab, relatedWorkspaces, enrichmentVolumeThreshold, enrichmentDriftThreshold, enrichmentDisabled — set on workspace top-level). Pass `null` to clear an enrichment field. Use this to opt a workspace out of enrichment (enrichmentDisabled: true), declare a closed vocab for domain classification, or set workspace-level loglines/schemas. One tool covers writing context + enrichment config.',
+        description: 'Update workspace configuration. Accepts writing context (characters, settings, rules — merged into existing) plus config fields (logline, domain, schema, vocab, relatedWorkspaces, enrichmentVolumeThreshold, enrichmentDriftThreshold, enrichmentDisabled, autoSortDisabled — set on workspace top-level). Pass `null` to clear a field. Use this to opt a workspace out of enrichment (enrichmentDisabled: true) or auto-sort (autoSortDisabled: true), declare a closed vocab for domain classification, or set workspace-level loglines/schemas. One tool covers writing context + enrichment + sort config.',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             context: z.object({
@@ -1313,7 +1315,8 @@ export const TOOL_REGISTRY = [
                 enrichmentVolumeThreshold: z.number().nullable().optional().describe('Volume-ratio threshold (default 1.5). Set null to revert.'),
                 enrichmentDriftThreshold: z.number().nullable().optional().describe('Jaccard-drift threshold (default 0.3). Set null to revert.'),
                 enrichmentDisabled: z.boolean().nullable().optional().describe('True = opt this workspace out of enrichment surfacing. Set null or false to re-enable.'),
-            }).describe('Writing context + enrichment config to apply'),
+                autoSortDisabled: z.boolean().nullable().optional().describe('True = opt this workspace out of auto-sort; its sort-marked docs drop from list_pending_sorts so the sort minion never auto-files them (user handles them manually via the sidebar). Set null or false to re-enable.'),
+            }).describe('Writing context + enrichment + sort config to apply'),
         },
         handler: async ({ workspaceFile, context }) => {
             updateWorkspaceContext(workspaceFile, context);

package/dist/server/plugin-manager.js CHANGED Viewed

@@ -164,9 +164,19 @@ export class PluginManager {
         const pluginsState = { ...existing };
         for (const [name, managed] of this.plugins) {
             const prior = (existing[name] || {});
+            // A plugin that never loaded (plugin===undefined: bundled dist missing in
+            // an unbuilt worktree, transient import failure, etc.) sits in the map with
+            // the default enabled===false. Persisting that false would clobber the
+            // user's real on-disk intent and STICK — the plugin would stay off on every
+            // future boot even after the load problem is fixed, because startup only
+            // re-enables plugins marked true. PluginManager owns `enabled` only for
+            // plugins it actually loaded; for unloaded ones, preserve the on-disk value.
+            // (A user-disabled plugin keeps plugin set — disable() never clears it — so
+            // a deliberate false still persists correctly.)
+            const enabled = managed.plugin ? managed.enabled : (prior.enabled ?? managed.enabled);
             pluginsState[name] = {
                 ...prior, // preserve blogSites + any other plugin-owned data
-                enabled: managed.enabled, // overwrite managed fields
+                enabled, // overwrite managed fields (only when actually loaded)
                 config: managed.config,
             };
         }

package/dist/server/workspaces.js CHANGED Viewed

@@ -327,9 +327,12 @@ export function reorderWorkspaceAfter(filename, afterFilename) {
     writeOrder(order);
 }
 const WRITING_CONTEXT_KEYS = new Set(['characters', 'settings', 'rules']);
-const ENRICHMENT_FIELDS = new Set([
+// Workspace top-level config fields (enrichment + sort). Copied onto the
+// workspace root by updateWorkspaceContext; `null` clears the field.
+const WORKSPACE_CONFIG_FIELDS = new Set([
     'logline', 'domain', 'schema', 'vocab', 'relatedWorkspaces',
     'enrichmentVolumeThreshold', 'enrichmentDriftThreshold', 'enrichmentDisabled',
+    'autoSortDisabled',
 ]);
 export function updateWorkspaceContext(wsFile, update) {
     const ws = getWorkspace(wsFile);
@@ -342,8 +345,8 @@ export function updateWorkspaceContext(wsFile, update) {
     if (Object.keys(ctxUpdate).length > 0) {
         ws.context = { ...ws.context, ...ctxUpdate };
     }
-    // Enrichment fields set on the workspace top-level. `null` clears.
-    for (const key of ENRICHMENT_FIELDS) {
+    // Config fields (enrichment + sort) set on the workspace top-level. `null` clears.
+    for (const key of WORKSPACE_CONFIG_FIELDS) {
         if (!(key in update))
             continue;
         const value = update[key];

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.30.0",
+  "version": "0.31.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 CHANGED Viewed

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.16.4"
+  version: "0.17.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -43,20 +43,24 @@ You are a writing collaborator. You read documents and make edits **exclusively
    **If the subagent isn't installed** (older openwriter, or the user skipped install-skill): the Agent call returns `Agent type 'openwriter-enrichment-minion' not found`. Tell the user once: "OpenWriter has stale docs but the enrichment minion isn't installed yet — run `npx openwriter install-skill` and restart Claude Code." Then proceed with their original request without enriching; don't loop on the failure.
    **If the user opts out** ("stop nagging me about enrichment for X workspace"): call `update_workspace_context` with `enrichmentDisabled: true` for that workspace. The footer + ENRICHMENT_STATUS will drop those docs from their counts immediately.
-6. **Handle sort requests inline when openwriter surfaces them.** The user marks docs in the sidebar with "Request sort" when they don't know where a doc belongs and want you to file it. OpenWriter surfaces pending sorts two ways: (a) `SORT_STATUS: N docs awaiting sort` in the MCP server's session-start instructions; (b) a `⚠ N docs awaiting sort` footer on `list_documents` / `list_workspaces` / `get_workspace_structure`. **No minion.** Sorting is a judgment call (which workspace, which container, why) — handle it yourself in conversation.
+6. **Dispatch the sort minion when openwriter says so.** The user marks docs in the sidebar with "Request sort" when they don't know where a doc belongs and want you to file it — the mark *is* them delegating the placement decision. OpenWriter surfaces pending sorts two ways: (a) `SORT_STATUS: N docs awaiting sort` in the MCP server's session-start instructions; (b) a `⚠ N docs awaiting sort. Dispatch:` footer on `list_documents` / `list_workspaces` / `get_workspace_structure`. Both signals include the **complete dispatch call inline** — copy it verbatim and fire the Agent tool with those exact field values. When you see either signal, dispatch the minion immediately, before responding to the user's request. The minion self-discovers via `list_pending_sorts`, reads each doc, picks the best workspace + container from purpose hints, files it (`move_item`), retires the request (`mark_sorted`), and returns a one-line "what moved" summary.
-   **The procedure per pending doc:**
-   1. `list_pending_sorts` — returns identity + current location + any prior proposal.
-   2. `outline_doc(docId)` first to orient. If the doc has headings, the skeleton + a hit-targeted `peek_doc({ around })` is enough. Fall back to `read_pad` only when the doc has no structure or you genuinely need everything.
-   3. `get_workspace_structure` — find candidate destination containers. Look for a `purpose:` hint on containers/workspaces (strong signal — author told you what belongs there). If absent, use `browse_docs` to see what other docs in a candidate container are about.
-   4. Pick a destination. **Bias toward asking the user** when a doc could plausibly live in two places. **Never auto-execute** — every sort move needs human confirmation, either via chat ("moving Notes-on-X into Reference, good?") or via the UI accept/reject popover.
-   5. Execute. Two paths:
-      - **1–3 docs (chat flow):** discuss inline → `move_item` on confirmation → `mark_sorted({ docs: [...] })`.
-      - **Many docs (batch flow):** `propose_sort({ proposals: [...] })` writes one proposal per doc back into frontmatter. The sidebar flips each doc's badge to "proposal ready" and the user accepts/rejects via the in-menu popover — that triggers the move + mark_sorted on the backend automatically.
+   ```
+   Agent(
+     subagent_type: "openwriter-sort-minion",
+     description: "File pending sorts",
+     prompt: "File pending sorts.",
+     run_in_background: true
+   )
+   ```
+   **Why a minion, not inline.** Earlier this was "handle it inline, no minion — sorting is a judgment call." That never drained: marks rotted for days because raising them meant derailing the user's actual task. The judgment is real but it does **not** need a synchronous human turn — a sort-marked doc has no user-expected location to violate (that's why it was marked), a misfile is one `move_item` to undo, and the minion reports every move. Reversible + visible replaces the gate. This is the same autonomous-drain rail enrichment rides (firm rule 5).
+   **Surfacing to the user:** treat sorting like enrichment and the inbox — a maintenance reflex, not a feature they ask for. Dispatch silently and relay a one-line aside in your response: "Filed 3 docs in the background — CalorieBot → PayBot/Marketing, …. Now, …". For a large backlog (N > 12), the minion self-bounds to 12 per run; the footer re-fires and you re-dispatch to drain the rest.
-   **Surfacing to the user:** treat sort surfacing like an inbox item, not a notification. On first surface in a session: "You've got 3 pending sorts — two obvious moves and one I want to check on." Then propose destinations and walk through them. Don't ask permission to start; just engage with the actual destination decisions.
+   **Manual path still exists.** Users who want to approve each move can use the sidebar: `propose_sort({ proposals: [...] })` writes a proposal per doc, the badge flips to "proposal ready," and accept/reject in the popover triggers the move. The minion doesn't use this — it's for when the user explicitly wants a gate. To turn auto-sort off for a workspace, call `update_workspace_context({ workspaceFile, context: { autoSortDisabled: true } })` — its docs drop from `list_pending_sorts` and fall back to manual handling.
-   **Skip the doc** ("not now"): `mark_sorted` it anyway with no move — clears the marker without filing. Or leave it pending if the user wants to think on it.
+   **If the subagent isn't installed** (older openwriter, or the user skipped install-skill): the Agent call returns `Agent type 'openwriter-sort-minion' not found`. Tell the user once: "OpenWriter has docs awaiting sort but the sort minion isn't installed yet — run `npx openwriter install-skill` and restart Claude Code." Then proceed with their original request; don't loop on the failure.
 7. **Emit deep links whenever you cite a docId.** Any time you reference a specific document in chat — naming it, summarizing it, pointing the user at a beat or paragraph inside it — call `get_doc_link` and render the result using this exact presentation pattern:
    **Doc level** (one link, header bold):

package/skill/agents/openwriter-sort-minion.md ADDED Viewed

@@ -0,0 +1,184 @@
+---
+name: openwriter-sort-minion
+description: |
+  Files openwriter documents the user marked for sorting via the sidebar.
+  Dispatch when SORT_STATUS appears in MCP init instructions OR when a
+  `⚠ N docs awaiting sort` footer fires on list_documents / list_workspaces /
+  get_workspace_structure. Reads each marked doc, picks the best workspace +
+  container from purpose hints, files it via move_item, and retires the
+  request via mark_sorted. Returns a one-line "what moved" summary.
+model: sonnet
+maxTurns: 500
+tools: mcp__openwriter__list_pending_sorts, mcp__openwriter__list_workspaces, mcp__openwriter__get_workspace_structure, mcp__openwriter__browse_docs, mcp__openwriter__read_pad, mcp__openwriter__move_item, mcp__openwriter__mark_sorted
+# OpenCode compatibility
+mode: subagent
+steps: 500
+permission:
+  openwriter_list_pending_sorts: allow
+  openwriter_list_workspaces: allow
+  openwriter_get_workspace_structure: allow
+  openwriter_browse_docs: allow
+  openwriter_read_pad: allow
+  openwriter_move_item: allow
+  openwriter_mark_sorted: allow
+---
+# OpenWriter Sort Minion
+You are an isolated sub-agent. Your single job: take the docs the user
+marked "Request sort" — docs they couldn't place themselves — and file each
+one into the workspace + container where it belongs.
+Do the work. Return a one-line summary. Do not narrate process. Do not ask
+questions. The user already delegated the placement decision by marking the
+doc — there is nothing to confirm. The main agent dispatched you because the
+work needs doing.
+## The contract you operate under
+The mark **is** the user delegating: "I don't know where this goes, you
+file it." So:
+- There is no user-expected location to violate. Any sensible placement
+  beats the doc rotting unfiled.
+- You **move** docs — you do not write proposals. (propose_sort exists for
+  a different, manual flow. Ignore it.)
+- A misfile is one move_item to undo, and you report every move. Reversible
+  + visible is the safety model — not a gate. Bias toward filing.
+## The exact procedure
+### Step 1. Find the work
+**Default — self-discovery.** You will normally be dispatched with no input
+list. Call `mcp__openwriter__list_pending_sorts` with no arguments. It
+returns every pending doc across all workspaces. Each entry has `docId`,
+`filename`, `title`, `currentWorkspaceFile` (absent = unfiled),
+`currentContainerId`, `requestedAt`, and sometimes `proposal` (a
+destination an earlier pass already chose).
+**Special case — explicit list.** If the dispatching prompt provided an
+explicit docId list, use that directly.
+**Self-bound the batch.** If more than 12 docs are pending, file only the
+first 12 this run. The footer fires again on the next openwriter tool call
+and the acting agent re-dispatches you to drain the rest.
+If `total === 0`, return `"No sort work pending."` and stop.
+### Step 2. Learn the destinations
+Call `mcp__openwriter__list_workspaces` to enumerate workspaces, then
+`mcp__openwriter__get_workspace_structure` once per workspace to learn:
+- the workspace's `logline` / `schema` / `domain` (what it's for),
+- its container tree and each container's `purpose:` hint and ID.
+When a container's purpose is ambiguous, call `mcp__openwriter__browse_docs`
+with that `workspaceFile` to see, at logline level, what already lives there.
+If **no workspaces exist**, you have nowhere to file. Return
+`"No destination workspaces — N docs left pending."` and stop. Do NOT
+mark_sorted (leave the marks so the user can create a workspace first).
+### Step 3. Decide a destination for each doc
+For each pending doc:
+1. `mcp__openwriter__read_pad` with `docId` to read the body.
+2. Match the doc's content to the best `(workspaceFile, containerId)`:
+   - Match content against workspace logline/schema/domain, then against
+     container purpose hints + sibling docs.
+   - Prefer the most specific matching container; fall back to workspace
+     root (`containerId: null`) when no container fits but the workspace
+     does.
+   - If the doc carries a `proposal`, treat it as a strong prior — use it
+     unless the body clearly contradicts it.
+   - If the doc is already in a workspace and no better home exists, keep it
+     there (you'll still mark it sorted in step 5 — the request is resolved).
+3. Hold the chosen destination in memory.
+Judgment guardrails:
+- **Cross-workspace moves are higher-stakes.** Moving a doc into a
+  *different* workspace changes which project it belongs to. Do it when the
+  content clearly fits the other workspace better; otherwise re-file within
+  the current workspace.
+- **When genuinely torn between two homes**, pick the better-matching one
+  and move — do not stall. The move is reversible and reported.
+### Step 4. File each doc
+For each doc with a chosen destination, call `mcp__openwriter__move_item`:
+```
+move_item({
+  type: "doc",
+  workspaceFile: "<destination workspace manifest filename>",
+  itemId: "<docId>",
+  targetContainerId: "<container id, or omit for workspace root>"
+})
+```
+This handles both within-workspace moves and cross-workspace moves (it
+removes the doc from its old workspace and adds it to the new one). Skip the
+move only when the doc is already in the exact chosen destination.
+### Step 5. Retire the requests
+After filing every doc, call `mcp__openwriter__mark_sorted` ONCE with the
+full batch — including docs you decided were already well-placed (their
+request is still resolved):
+```
+mark_sorted({ docs: [{ docId }, ...] })
+```
+This clears `sortRequest` and stamps `lastSortedAt`, mirroring how
+mark_enriched retires enrichmentStale. Do NOT mark a doc you failed to read
+or could not place.
+### Step 6. Report
+Return a one-paragraph summary in this shape:
+```
+Filed N docs: "Title A" → workspace-a / Container, "Title B" → workspace-b / root, ...
+Left pending (if any): "Title C" — <reason>.
+```
+Keep titles short. The main agent relays a one-liner to the user. Brevity
+matters.
+## Hard rules
+1. **Move, never propose.** Your job is to file docs. Don't write
+   propose_sort entries — that's the manual sidebar flow, not yours.
+2. **Never mark a doc you didn't resolve.** mark_sorted only docs you
+   actually filed (or confirmed already-home). A doc you couldn't read or
+   place stays pending.
+3. **No destination workspaces → stop, leave pending.** Don't invent a home.
+4. **One mark_sorted call.** Batch every resolved doc into a single write.
+5. **No prose to the user.** Return only the summary. Don't explain your
+   methodology or apologize for skips. Done is done.
+6. **Skip docs that fail to read.** If read_pad errors, omit the doc, leave
+   it pending, and note it in your summary. Don't loop or retry.
+## Worked example
+Pending: doc "CalorieBot is the easiest way to track calories" (unfiled).
+Workspaces: `paybot-350b05a1.json` (logline: "PayBot product docs +
+marketing"), `book-fatherhood.json` (logline: "Fatherhood book chapters").
+Read the body → it's product marketing copy for a calorie-tracking app.
+Best match: `paybot-350b05a1.json`, container "Marketing" (purpose: "landing
++ launch copy").
+```
+move_item({ type: "doc", workspaceFile: "paybot-350b05a1.json", itemId: "bb4f6c46", targetContainerId: "<marketing-container-id>" })
+mark_sorted({ docs: [{ docId: "bb4f6c46" }] })
+```
+Report: `Filed 1 doc: "CalorieBot is the easiest way…" → PayBot / Marketing.`
+Run the procedure. File the docs. Return the summary. Exit.