openwriter 0.36.2 → 0.37.0

package/dist/server/mcp.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteFileSync, readConfig } from './helpers.js';
 import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, getIsTemp, extractText, countPending, addDocTag, removeDocTag, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, getCanonical, cloneWithPendingReverted, bumpDocVersion, setSortProposalOnFile, clearSortRequestOnFile, } from './state.js';
 import { tiptapToBlocks } from './node-blocks.js';
+import { readBlame, summarizeBlame } from './attribution.js';
 import { outline, peek, searchInDoc, truncateRead } from './peek-outline.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
 import { resolveTypeMeta } from './content-type-meta.js';
@@ -551,7 +552,7 @@ export const TOOL_REGISTRY = [
                         wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                     }
                     const newDocId = getDocId();
-                    save();
+                    save('agent');
                     broadcastDocumentsChanged();
                     broadcastWorkspacesChanged();
                     broadcastDocumentSwitched(getDocument(), getTitle(), getActiveFilename(), getMetadata());
@@ -692,7 +693,7 @@ export const TOOL_REGISTRY = [
                 }
                 updateDocument(doc);
                 updatePendingCacheForActiveDoc();
-                save();
+                save('agent');
                 // Broadcast sidebar updates first (deferred from create_document) so the doc
                 // entry and spinner removal arrive in the same render cycle
                 broadcastDocumentsChanged();
@@ -880,6 +881,31 @@ export const TOOL_REGISTRY = [
             return { content: [{ type: 'text', text: Object.keys(target.metadata).length > 0 ? JSON.stringify(target.metadata) : '{}' }] };
         },
     },
+    {
+        name: 'get_attribution',
+        description: 'Get human-vs-agent author attribution for a document. Returns the char-weighted composition (% human / % agent / % unknown) plus per-node coarse origin (human | agent | mixed | unknown). Attribution is captured automatically at save time and anchored to sentence content, so it survives edits, splits, and paste-back. "unknown" = content authored before attribution tracking began. Use to report how much of a doc is genuinely author-written vs agent-scaffolded.',
+        schema: {
+            docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
+        },
+        handler: async ({ docId }) => {
+            const target = resolveDocTarget(docId);
+            const blocks = tiptapToBlocks(target.document);
+            const blame = readBlame(docId);
+            const summary = summarizeBlame(blame, blocks);
+            const nodeCounts = { human: 0, agent: 0, mixed: 0, unknown: 0 };
+            for (const origin of Object.values(summary.nodes))
+                nodeCounts[origin] = (nodeCounts[origin] ?? 0) + 1;
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            docId,
+                            percent: summary.percent,
+                            chars: summary.chars,
+                            nodeOrigins: summary.nodes,
+                            nodeCounts,
+                            tracked: blame !== null,
+                            attributionSince: blame?.attributionSince ?? null,
+                        }) }] };
+        },
+    },
     {
         name: 'set_metadata',
         description: 'Update frontmatter metadata on a document. Merges with existing metadata — only provided keys are changed. Use for summaries, character lists, tags, arc notes, or any organizational data. Saves to disk immediately. Lifecycle convention (v0.19.0): use `set_metadata({ status: "canonical" })` when a doc commits to the workspace spine (Beats locks, Research Note becomes load-bearing); use `set_metadata({ status: "draft" })` when a doc is superseded or demoted. Status is the agent\'s field — the enrichment minion never writes it.',
@@ -923,7 +949,7 @@ export const TOOL_REGISTRY = [
                 const meta = getMetadata();
                 for (const key of removed)
                     delete meta[key];
-                save();
+                save('agent');
                 broadcastMetadataChanged(getMetadata());
                 if (cleaned.title) {
                     // Reached only on temp-file creation titling — hot promote.
@@ -1015,7 +1041,7 @@ export const TOOL_REGISTRY = [
                         for (const k of LEGACY_FIELDS_TO_RETIRE)
                             delete liveMeta[k];
                         bumpDocVersion();
-                        save();
+                        save('agent');
                         broadcastMetadataChanged(getMetadata());
                     }
                     else {
@@ -1647,7 +1673,7 @@ export const TOOL_REGISTRY = [
                         doc.content.push(pendingImage);
                     }
                     updateDocument(doc);
-                    save();
+                    save('agent');
                     setAgentLockActive();
                     broadcastDocumentSwitched(doc, getTitle(), getActiveFilename(), getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, lastNodeId: imgId }) }] };
@@ -1668,7 +1694,7 @@ export const TOOL_REGISTRY = [
                     articleContext.coverImage = src;
                     articleContext.coverImages = existing;
                     setMetadata({ articleContext });
-                    save();
+                    save('agent');
                     broadcastMetadataChanged(getMetadata());
                     return { content: [{ type: 'text', text: JSON.stringify({ success: true, src, coverSet: true }) }] };
                 }
@@ -1970,7 +1996,7 @@ export const TOOL_REGISTRY = [
                 // Active doc: mutate state.metadata and let save() persist the frontmatter.
                 // save()'s writeToDisk path invalidates the backlinks cache.
                 setMetadata({ references: newReferences });
-                save();
+                save('agent');
                 broadcastMetadataChanged(getMetadata());
             }
             else {

package/dist/server/state.js

@@ -10,6 +10,8 @@ import { tiptapToMarkdown, tiptapToMarkdownChecked, tiptapToBody, markdownToTipt
 import { applyTextEditsToNode } from './text-edit.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, LEAF_BLOCK_TYPES, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath, canonicalizeIdentifier } from './helpers.js';
 import { snapshotIfNeeded, ensureDocId, forceSnapshot } from './versions.js';
+import { captureAttribution, bindBlameToVersion } from './attribution.js';
+import { scheduleAgentCommit } from './commits.js';
 import { syncReferencesFromProse, invalidateBacklinksCache, writeFrontmatter } from './backlinks.js';
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
@@ -1087,12 +1089,29 @@ export function resetDocVersion() {
 // adr: adr/pending-overlay-model.md
 let saveTimer = null;
 const SAVE_DEBOUNCE_MS = 500;
-export function debouncedSave() {
+// The actor whose edits are sitting in the current debounce window. Set at
+// schedule time (NOT flush time) so attribution can't bleed across actors.
+// adr: adr/document-history-attribution.md (invariant 3 — no module-global shim;
+// this is save-scoped: it tracks the SCHEDULER of the pending batch and is
+// cleared the moment that batch flushes).
+let pendingSaveActor = null;
+export function debouncedSave(actor = 'human') {
+    // If a save is already pending under a DIFFERENT actor, flush that batch now
+    // under ITS actor before this actor's edits join the window — otherwise the
+    // single coalesced flush would attribute both actors' new sentences to one.
+    if (saveTimer && pendingSaveActor && pendingSaveActor !== actor) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+        save(pendingSaveActor);
+    }
+    pendingSaveActor = actor;
     if (saveTimer)
         clearTimeout(saveTimer);
     saveTimer = setTimeout(() => {
         saveTimer = null;
-        save();
+        const a = pendingSaveActor ?? 'human';
+        pendingSaveActor = null;
+        save(a);
     }, SAVE_DEBOUNCE_MS);
 }
 /** Cancel any pending debounced save. Call before doc switch (which does its own save). */
@@ -1101,6 +1120,7 @@ export function cancelDebouncedSave() {
         clearTimeout(saveTimer);
         saveTimer = null;
     }
+    pendingSaveActor = null;
 }
 export function applyChanges(changes) {
     // Bump version BEFORE applying so new overlay entries created by
@@ -1120,8 +1140,10 @@ export function applyChanges(changes) {
     for (const listener of listeners) {
         listener(processed, version);
     }
-    // Debounced save — coalesces rapid agent writes into a single disk write
-    debouncedSave();
+    // Debounced save — coalesces rapid agent writes into a single disk write.
+    // applyChanges is an AGENT door (MCP write tools land here); tag the batch
+    // so the flush attributes its new content to the agent.
+    debouncedSave('agent');
     // Update pending doc cache for the active document
     updatePendingCacheForActiveDoc();
     // Find the last created node ID for chaining inserts
@@ -2129,7 +2151,7 @@ export function getPendingDocInfo() {
 // ============================================================================
 // PERSISTENCE
 // ============================================================================
-function writeToDisk() {
+function writeToDisk(actor = 'human') {
     // No-op gate: when the in-memory document hasn't been mutated since the
     // last successful write (or byte-equality skip), bail before any work.
     // Skips the full serialize + matcher pipeline (~50ms on medium docs), the
@@ -2270,6 +2292,34 @@ function writeToDisk() {
         // The serializer no longer emits `meta.pending` (overlay handles that).
         const result = tiptapToMarkdownChecked(canonical, state.title, metaWithGraveyard);
         markdown = result.markdown;
+        // Author attribution (Tier A + Tier B). MUST run here — alongside the
+        // overlay save and BEFORE the "content identical" / external-write /
+        // destructive-save guards below. An agent that adds ONLY pending content
+        // leaves the canonical body byte-identical, so those guards short-circuit
+        // the disk write; but the MERGED state (state.document) DID change and was
+        // just persisted to the overlay sidecar — so its attribution must be
+        // captured too. Capture from the MERGED doc (NOT canonical) so an agent's
+        // pending proposals are stamped 'agent' at write time; because blame is
+        // anchored to the sentence content hash, a later human ACCEPT leaves the
+        // hash unchanged and the agent origin holds (accept never launders).
+        // The version binding happens after the body write (a pending-only save
+        // produces no new snapshot, which is correct — it isn't a new version).
+        // adr: adr/document-history-attribution.md
+        if (state.docId) {
+            try {
+                captureAttribution(state.docId, tiptapToBlocks(state.document), actor, Date.now());
+                // Agent-finished commit trigger (debounced, per-doc). Fires from the
+                // CAPTURE site — the only place that reliably sees every agent edit tool
+                // (write_to_pad/populate/edit_text) with the exact target docId. The
+                // spinner broadcast (broadcastWritingFinished) was the wrong hook: not
+                // all write tools fire it. adr: adr/document-history-attribution.md
+                if (actor === 'agent' && state.filePath)
+                    scheduleAgentCommit(state.docId, state.filePath);
+            }
+            catch (err) {
+                console.error('[Attribution] capture failed:', err);
+            }
+        }
     }
     if (existsSync(state.filePath)) {
         // Skip write if content is identical (prevents phantom git changes on doc switch)
@@ -2342,11 +2392,22 @@ function writeToDisk() {
     // Record that disk now matches in-memory at this docVersion. Subsequent
     // save() calls without further mutations will bail at the top-level gate.
     lastSavedDocVersion = docVersion;
-    // Best-effort version snapshot — never blocks saves
+    // Best-effort version snapshot — never blocks saves. Returns the cut ts
+    // (or null if throttled/unchanged) so attribution can bind to this version.
+    // Attribution itself was already captured in the else branch above (so a
+    // pending-only save, which skips the body write, is still attributed); here
+    // we just stamp the blame with the version cut when a real snapshot landed.
+    let snapshotTs = null;
     try {
-        snapshotIfNeeded(state.docId, state.filePath);
+        snapshotTs = snapshotIfNeeded(state.docId, state.filePath);
     }
     catch { /* ignore */ }
+    if (snapshotTs && !isExternalDoc(state.filePath) && state.docId) {
+        try {
+            bindBlameToVersion(state.docId, snapshotTs);
+        }
+        catch { /* best-effort */ }
+    }
     // Auto-sync references from prose: legacy `doc:` prose links still render
     // (PadLink extension), but the graph/crawl/backlinks-panel read the
     // structural `references:` field. After every save, scan the body for
@@ -2370,7 +2431,22 @@ function writeToDisk() {
         invalidateBacklinksCache();
     }
 }
-export function save() {
+export function save(actor) {
+    // Resolve the save-scoped actor. Explicit arg wins; else fall back to the
+    // actor who scheduled the pending debounce batch this save is flushing; else
+    // 'human' (system/user-initiated saves that don't author prose produce no
+    // attribution spans anyway). adr: adr/document-history-attribution.md
+    // If an explicit actor differs from a pending-batch actor, flush that batch
+    // first under its own actor so this save never absorbs another actor's edits.
+    if (actor && saveTimer && pendingSaveActor && pendingSaveActor !== actor) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+        const prior = pendingSaveActor;
+        pendingSaveActor = null;
+        writeToDisk(prior);
+    }
+    const resolvedActor = actor ?? pendingSaveActor ?? 'human';
+    pendingSaveActor = null;
     // Auto-title from body content if the title is still default/empty.
     // Runs BEFORE filePath assignment so a brand-new doc lands at its
     // derived-title filename directly (no temp-file detour). For already-
@@ -2406,7 +2482,7 @@ export function save() {
             state.isTemp = false;
         }
     }
-    writeToDisk();
+    writeToDisk(resolvedActor);
 }
 export function load() {
     ensureDataDir();
@@ -2809,6 +2885,23 @@ export function saveDocToFile(filename, doc) {
         if (docId) {
             const overlay = extractOverlay(doc);
             saveOverlay(docId, overlay);
+            // This routes a BROWSER doc-update to a non-active file — the content is
+            // the human's. Snapshot + attribute as 'human'. adr: adr/document-history-attribution.md
+            if (!isExternalDoc(targetPath)) {
+                let snapshotTs = null;
+                try {
+                    snapshotTs = snapshotIfNeeded(docId, targetPath);
+                }
+                catch { /* ignore */ }
+                try {
+                    captureAttribution(docId, tiptapToBlocks(doc), 'human', Date.now());
+                    if (snapshotTs)
+                        bindBlameToVersion(docId, snapshotTs);
+                }
+                catch (err) {
+                    console.error('[Attribution] saveDocToFile capture failed:', err);
+                }
+            }
         }
         // Backlinks cache invalidate — browser sent a doc-update for a non-active
         // doc; the prose-link set on that doc may have changed.
@@ -3041,6 +3134,29 @@ function flushDocToFile(filename, doc, title, metadata) {
     if (docId) {
         const overlay = extractOverlay(doc);
         saveOverlay(docId, overlay);
+        // Door 3: non-active agent writes (populate_document / write_to_pad /
+        // edit_text targeting a non-active doc). This path bypasses writeToDisk
+        // and historically produced NO snapshot — so it had neither a restore
+        // floor nor attribution. Add both. This door is ALWAYS the agent (humans
+        // only edit the active doc in the browser), so actor is 'agent'.
+        // adr: adr/document-history-attribution.md
+        if (!isExternalDoc(targetPath)) {
+            let snapshotTs = null;
+            try {
+                snapshotTs = snapshotIfNeeded(docId, targetPath);
+            }
+            catch { /* ignore */ }
+            try {
+                captureAttribution(docId, tiptapToBlocks(doc), 'agent', Date.now());
+                if (snapshotTs)
+                    bindBlameToVersion(docId, snapshotTs);
+                // Door 3 is always an agent write (non-active). Schedule its commit.
+                scheduleAgentCommit(docId, targetPath);
+            }
+            catch (err) {
+                console.error('[Attribution] door-3 capture failed:', err);
+            }
+        }
     }
     setPendingCacheEntry(filename, countPending(doc.content));
     // Backlinks cache invalidation — non-active write paths (populate_document on

package/dist/server/versions.js

@@ -70,30 +70,46 @@ function seedLastSnapshot(docId) {
     const content = readFileSync(join(dir, `${latest}.md`), 'utf-8');
     lastSnapshot.set(docId, { time: latest, hash: contentHash(content) });
 }
+/**
+ * Pick a free, strictly-increasing integer timestamp for a new snapshot file.
+ * Two snapshots in the same millisecond would collide on `${Date.now()}.md`;
+ * bumping (rather than adding a `-N` suffix) keeps the filename a parseable
+ * integer so listVersions/seedLastSnapshot's parseInt never yields NaN.
+ */
+function freeSnapshotTs(docId) {
+    const dir = docDir(docId);
+    let now = Date.now();
+    while (existsSync(join(dir, `${now}.md`)))
+        now++;
+    return now;
+}
 /**
  * Snapshot after every writeToDisk() — skips if content unchanged or within throttle window.
- * Called in best-effort mode (caller wraps in try/catch).
+ * Called in best-effort mode (caller wraps in try/catch). Returns the timestamp
+ * written (so attribution can bind the blame state to this version cut), or
+ * null when the snapshot was skipped.
  */
 export function snapshotIfNeeded(docId, filePath) {
     if (!docId || !filePath || !existsSync(filePath))
-        return;
+        return null;
     seedLastSnapshot(docId);
     const markdown = readFileSync(filePath, 'utf-8');
     const hash = contentHash(markdown);
-    const now = Date.now();
     const last = lastSnapshot.get(docId);
     if (last) {
         // Skip if content hasn't changed (regardless of time)
         if (hash === last.hash)
-            return;
+            return null;
         // Skip if within minimum interval even if content changed
-        if ((now - last.time) < MIN_INTERVAL_MS)
-            return;
+        if ((Date.now() - last.time) < MIN_INTERVAL_MS)
+            return null;
     }
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
     pruneVersions(docId);
+    return now;
 }
 /**
  * Force a snapshot regardless of dedup. Used before restores as a safety net.
@@ -103,8 +119,8 @@ export function forceSnapshot(docId, filePath) {
         return;
     const markdown = readFileSync(filePath, 'utf-8');
     const hash = contentHash(markdown);
-    const now = Date.now();
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
 }
@@ -120,8 +136,15 @@ export function writeSnapshotMarkdown(docId, markdown) {
     if (!docId)
         return 0;
     const hash = contentHash(markdown);
-    const now = Date.now();
+    // Dedup: if the most recent snapshot already holds this exact content, reuse
+    // its timestamp instead of writing a duplicate .md. Prevents a commit
+    // snapshot from duplicating the auto-snapshot the same save just wrote.
+    seedLastSnapshot(docId);
+    const last = lastSnapshot.get(docId);
+    if (last && last.hash === hash)
+        return last.time;
     ensureDocDir(docId);
+    const now = freeSnapshotTs(docId);
     writeFileSync(join(docDir(docId), `${now}.md`), markdown, 'utf-8');
     lastSnapshot.set(docId, { time: now, hash });
     return now;

package/dist/server/ws.js

@@ -5,6 +5,7 @@ import { WebSocketServer, WebSocket } from 'ws';
 import { updateDocument, syncBrowserDocUpdate, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, debouncedSave, cancelDebouncedSave, onChanges, onIdRewrites, isAgentLocked, setAgentLockActive, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, onExternalWriteConflict, onDocumentReloaded, onAutoTitleApplied, isAgentStub, unmarkAgentStub, } from './state.js';
 import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile, listDocuments, acceptPendingTitle, rejectPendingTitle, getPendingTitle } from './documents.js';
 import { removeDocFromAllWorkspaces } from './workspaces.js';
+import { commitFromFile } from './commits.js';
 import { canonicalizeIdentifier } from './helpers.js';
 import { nodeTextPreview, diagLog } from './pending-overlay.js';
 import { generateRequestId, withRequestId } from './logger.js';
@@ -294,7 +295,7 @@ export function setupWebSocket(server) {
                         const result = syncBrowserDocUpdate(msg.document, browserVersion);
                         diagLog(`[WS] doc-update SYNC-MERGED stale v${browserVersion}→v${serverVersion} preservedServerEntries=${result.preservedServerEntries}`);
                         updatePendingCacheForActiveDoc();
-                        debouncedSave();
+                        debouncedSave('human');
                     }
                     else if (browserFilename && browserFilename !== getActiveFilename()) {
                         // Browser sent a doc-update for a different document (race: server switched away).
@@ -321,7 +322,7 @@ export function setupWebSocket(server) {
                         diagLog(`[WS] doc-update ACCEPTED (browser: ${nodeCount} nodes, cleaned: ${cleanedCount}, server: ${currentNodeCount} nodes)`);
                         updateDocument(msg.document);
                         updatePendingCacheForActiveDoc(); // Keep cache in sync after browser edits/reject-all
-                        debouncedSave();
+                        debouncedSave('human');
                     }
                 }
                 // Browser requests fresh state on reconnect (instead of pushing stale state)
@@ -351,7 +352,7 @@ export function setupWebSocket(server) {
                         broadcastDocumentsChanged();
                     }
                     else {
-                        debouncedSave();
+                        debouncedSave('human');
                         debouncedBroadcastDocumentsChanged();
                     }
                 }
@@ -512,6 +513,19 @@ export function setupWebSocket(server) {
                         stripPendingAttrs();
                         save();
                         updatePendingCacheForActiveDoc(); // Sync cache after strip (prevents stale "has changes" indicator)
+                        // Commit trigger: accepting agent changes is a version boundary.
+                        // Bundles the agent's attributed edit-events into a commit (the
+                        // changeset actors reflect who authored; trigger records the accept).
+                        // adr: adr/document-history-attribution.md
+                        if (action === 'accept') {
+                            try {
+                                const did = getDocId();
+                                const fp = getFilePath();
+                                if (did && fp)
+                                    commitFromFile(did, fp, { trigger: 'accept', actor: 'human', nowTs: Date.now() });
+                            }
+                            catch { /* best-effort */ }
+                        }
                     }
                     else {
                         // Race path: resolved doc is NOT the active one (server switched away).
@@ -691,6 +705,11 @@ activityDocId) {
     });
     return writeKey;
 }
+// NOTE: the agent-finished commit trigger lives at the CAPTURE site
+// (state.ts writeToDisk / flushDocToFile via scheduleAgentCommit), NOT here.
+// broadcastWritingFinished is the spinner mechanism and is not fired by every
+// agent edit tool (write_to_pad never calls it), so it was the wrong hook.
+// adr: adr/document-history-attribution.md
 // key omitted → clear all (legacy single-write flows). Pass a key for multi-doc.
 export function broadcastWritingFinished(key) {
     if (key) {

package/package.json

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

@@ -40,7 +40,7 @@ You are a writing collaborator. You read documents and make edits **exclusively
    - **First time in a session, large batch (N > 20):** give the user a heads-up BEFORE dispatching: "OpenWriter detected 47 docs that haven't been summarized yet — first-time setup. Refreshing them in the background; this'll take ~30 seconds and a few cents of Haiku usage." Then dispatch and report when done.
    - **Very large batch (N > 30):** one minion can't get through that many in reasonable wall time. Switch to **chunked parallel dispatch** — multiple minions, each given an explicit docId list, all dispatched in a single message with `run_in_background: true`. Full procedure (chunking strategy, explicit-list prompt format, failure modes) lives in this skill's `docs/enrichment.md`. Read that doc before dispatching anything over 30 docs.
 
-   **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 subagent isn't installed** (older openwriter, or the user skipped setup): 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 setup` 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. **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.
@@ -60,7 +60,7 @@ You are a writing collaborator. You read documents and make edits **exclusively
 
    **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.
 
-   **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.
+   **If the subagent isn't installed** (older openwriter, or the user skipped setup): 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 setup` 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):
@@ -650,7 +650,7 @@ The plugin ships with the Author's Voice skill built in (`plugins/authors-voice/
 
 ```bash
 npm install -g openwriter@latest
-npx openwriter install-skill
+npx openwriter setup
 ```
 
 Then restart your Claude Code session (`/mcp` to reconnect).

package/skill/docs/setup.md

@@ -3,7 +3,7 @@
 ## Quick install
 
 ```bash
-npx openwriter install-skill
+npx openwriter setup
 ```
 
 This installs openwriter globally, configures the MCP server for Claude Code, and copies this skill — all in one step. After it finishes, the user just needs to restart their Claude Code session.
@@ -54,7 +54,7 @@ The enrichment minion is NOT auto-discovered. Place it at one of:
 - `~/.config/opencode/agents/openwriter-enrichment-minion.md` (global, all projects)
 - `.opencode/agents/openwriter-enrichment-minion.md` (this project only, repo root)
 
-Source file lives at `~/.claude/skills/openwriter/agents/openwriter-enrichment-minion.md` after `npx openwriter install-skill`. Copy it to one of the paths above and restart OpenCode. The filename becomes the agent name OpenCode resolves when the parent dispatches it.
+Source file lives at `~/.claude/skills/openwriter/agents/openwriter-enrichment-minion.md` after `npx openwriter setup`. Copy it to one of the paths above and restart OpenCode. The filename becomes the agent name OpenCode resolves when the parent dispatches it.
 
 ## After setup