openwriter 0.15.0 → 0.17.0

package/dist/server/state.js

@@ -14,36 +14,67 @@ import { extractForwardLinks, extractForwardLinksFromDisk, updateBacklinksForSou
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
+import { anyLegacyRaw } from './node-fingerprint.js';
+import { markdownToNodes, resolvePreviousNodes, resolveGraveyard } from './markdown-parse.js';
 import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
+import { harvestSentenceHashes, harvestCharCount, isEnrichmentStale } from './enrichment.js';
 /** Read the persisted identity graph (nodes + graveyard) from a file's
- *  frontmatter. This is the matcher's previousNodes baseline at save time —
- *  the disk is the source of truth, not a parallel in-memory cache. Returns
- *  empty arrays for a brand-new file or unreadable frontmatter. */
+ *  frontmatter. The save-time matcher reads previousNodes + graveyard
+ *  directly from disk every write — the disk is the source of truth, not
+ *  a parallel in-memory cache.
+ *
+ *  Slim disk entries are enriched against the freshly-parsed disk body so
+ *  derived fields (position, neighbor types, etc.) flow into the rich
+ *  Fingerprint the matcher expects. Legacy verbose-object entries are
+ *  positionally re-fingerprinted via the same helper.
+ *  adr: adr/node-identity-matcher.md */
 function readPersistedIdentity(filePath) {
     if (!filePath || !existsSync(filePath))
         return { previousNodes: [], graveyard: [] };
     try {
         const raw = readFileSync(filePath, 'utf-8');
-        const { data } = matter(raw);
+        // Bypass gray-matter for identity reads. gray-matter caches its parsed
+        // `data` object by raw string within a process, so any upstream
+        // mutation (test wrappers, dev tools) leaks into the matcher's input
+        // on subsequent reads. Identity fields live in a JSON frontmatter
+        // block emitted by tiptapToMarkdown — parse it directly so we always
+        // see fresh data.
+        const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        let rawNodes = [];
+        let rawGraveyard = [];
+        let body = raw;
+        if (fmMatch) {
+            try {
+                const fmObj = JSON.parse(fmMatch[1]);
+                if (Array.isArray(fmObj.nodes))
+                    rawNodes = fmObj.nodes;
+                if (Array.isArray(fmObj.graveyard))
+                    rawGraveyard = fmObj.graveyard;
+            }
+            catch { /* malformed JSON frontmatter — treat as no identity */ }
+            body = raw.slice(fmMatch[0].length).replace(/^[\r\n]+/, '');
+        }
+        // Slim entries derive position/parent/neighbors from the slim array
+        // itself — no body parse needed. Legacy entries need positional
+        // re-fingerprinting from the body, so we parse it lazily only then.
+        // This avoids a full markdown re-parse on every save for the common
+        // (ultra-lean) case, which was the dominant cost of switchDocument's
+        // pre-switch save() for large docs.
+        const needsBodyParse = (Array.isArray(rawNodes) && rawNodes.length > 0 && anyLegacyRaw(rawNodes));
+        let previousBlocks = [];
+        if (needsBodyParse) {
+            const previousDocContent = markdownToNodes(body);
+            previousBlocks = tiptapToBlocks({ content: previousDocContent });
+        }
         return {
-            previousNodes: normalizeNodeEntries(data.nodes),
-            graveyard: normalizeNodeEntries(data.graveyard),
+            previousNodes: resolvePreviousNodes(rawNodes, previousBlocks),
+            graveyard: resolveGraveyard(rawGraveyard),
         };
     }
     catch {
         return { previousNodes: [], graveyard: [] };
     }
 }
-/** Defensive parse of frontmatter node entries — drops any malformed rows.
- *  Mirrors the same-named helper in markdown-parse.ts so save and load apply
- *  identical validation. */
-function normalizeNodeEntries(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    return raw
-        .filter((entry) => entry && typeof entry === 'object' && entry.id && entry.fp)
-        .map((entry) => ({ id: String(entry.id), fingerprint: entry.fp }));
-}
 const DEFAULT_DOC = {
     type: 'doc',
     content: [{ type: 'paragraph', content: [] }],
@@ -293,11 +324,8 @@ function handleWatcherEvent() {
     const reloaded = reloadActiveDocFromDisk();
     if (!reloaded)
         return;
-    // Bump version so any in-flight stale browser autosave is rejected by
-    // the existing version check in the WS handler. Without this bump, the
-    // browser's pre-external-write state would silently overwrite the
-    // freshly-loaded disk content.
-    bumpDocVersion();
+    // (docVersion already bumped inside reloadActiveDocFromDisk — single
+    // source of truth for the reload-version-bump.)
     notifyDocumentReloaded({
         filePath: state.filePath,
         filename: reloaded.filename,
@@ -777,23 +805,28 @@ export function updateDocument(doc) {
         console.error(`[State] BLOCKED destructive updateDocument: ${incomingNodes} nodes would replace ${currentNodes} nodes`);
         return;
     }
-    // Preserve pending attrs from server state → incoming browser doc.
-    // The browser's PendingAttributes extension tracks pendingStatus in the TipTap
-    // document model, but transferPendingAttrs provides a safety net in case the
-    // browser's doc-update lost them (e.g. timing edge case, stale transaction).
-    const serverHadPending = hasPendingChanges();
-    if (serverHadPending) {
-        transferPendingAttrs(state.document, doc);
-    }
-    // Route the incoming merged-shape doc through the primary-state setter
-    // so canonical + overlay get refreshed and state.document is the
-    // recomputed merged view. Direct assignment is forbidden.
+    // Trust the browser-sent doc as authoritative. The WebSocket handler's
+    // version gate (isVersionCurrent) already routed stale browser submissions
+    // through syncBrowserDocUpdate (the merge path); by the time we land here,
+    // the browser saw the same view of pending state the server has. An
+    // incoming doc with pending markers cleared is by definition an intentional
+    // accept — never an attrs-lost-in-transit error. The older safety net
+    // (transferPendingAttrs re-stamping server's pending onto the incoming doc)
+    // worked under the pre-fb666e6 model where state.document was authoritative,
+    // but under the canonical+overlay split model it actively reverted user
+    // accepts: re-stamped 'insert' markers got filtered out of canonical by
+    // stripPendingFromDoc, and the just-accepted body disappeared from disk.
+    // adr: adr/pending-overlay-model.md
     setPrimaryFromMerged(doc);
     state.lastModified = new Date();
-    // Validate: if server had pending changes, verify they survived the transfer
-    if (serverHadPending && !hasPendingChanges()) {
-        console.error('[State] WARNING: pending changes lost after updateDocument — browser doc-update overwrote pending attrs');
-    }
+    // Bump docVersion so the writeToDisk no-op gate (which compares
+    // docVersion to lastSavedDocVersion) sees this mutation. Browser
+    // doc-updates flow through here, and without the bump the subsequent
+    // debouncedSave would short-circuit and the user's edits would never
+    // hit disk. The canonical contract: any path that mutates
+    // state.document MUST bump docVersion. applyChanges does the same.
+    // adr: adr/pending-overlay-model.md
+    bumpDocVersion();
 }
 /**
  * Transfer pending attrs from source doc to target doc by matching node IDs.
@@ -913,6 +946,14 @@ export function isAgentLocked(filename) {
 }
 // ---- Document version counter: prevents stale browser doc-updates ----
 let docVersion = 0;
+// Counterpart to docVersion: the docVersion at which we last confirmed
+// in-memory state matches disk. save()/writeToDisk() is a strict no-op when
+// these are equal (and a file exists on disk). This is the server-side
+// counterpart to the client diff-gate in App.tsx — it makes doc-switches
+// between unchanged docs free (no serialize, no sidecar write, no snapshot,
+// no mtime bump that would invalidate the doc cache).
+// adr: adr/pending-overlay-model.md
+let lastSavedDocVersion = 0;
 /** Increment version after agent writes. Returns the new version. */
 export function bumpDocVersion() {
     return ++docVersion;
@@ -925,9 +966,13 @@ export function getDocVersion() {
 export function isVersionCurrent(browserVersion) {
     return browserVersion >= docVersion;
 }
-/** Reset version on document switch (new document = new version lineage). */
+/** Reset version on document switch (new document = new version lineage).
+ *  Both counters move together: the new doc was just loaded from disk (or
+ *  cache, which mtime-validates against disk), so in-memory matches disk
+ *  by definition. */
 export function resetDocVersion() {
     docVersion = 0;
+    lastSavedDocVersion = 0;
 }
 // ---- Debounced save: coalesces rapid agent writes into a single disk write ----
 //
@@ -1669,6 +1714,26 @@ export function reloadActiveDocFromDisk() {
     // sidecar (or legacy migration). Recompute merged via the helper.
     state.canonical = canonical;
     setOverlayFromEntries(entries);
+    // External writes change the body but leave disk frontmatter pointing at
+    // the previous save's fingerprints. If the user cuts/deletes a block before
+    // the next browser-driven save, the matcher graveyards with that stale
+    // fingerprint and a later paste-back can't match by exact fingerprint —
+    // graveyard-restore silently misses. Resync disk frontmatter with the
+    // reloaded body now: the matcher's edit rule pins IDs and emits fresh
+    // per-block fingerprints. fs.watch self-suppression via state.loadedMtime
+    // (handleWatcherEvent) prevents a reload→save→reload loop.
+    //
+    // Bump docVersion BEFORE writeToDisk: serves two purposes at once. (1)
+    // Rejects any in-flight stale browser autosaves (the WS handler checks
+    // version currency). (2) Forces writeToDisk's no-op gate to see "dirty"
+    // state and actually persist the refreshed frontmatter — without the bump,
+    // the gate would short-circuit and the stale-fingerprint bug returns.
+    // adr: adr/node-identity-matcher.md
+    bumpDocVersion();
+    try {
+        writeToDisk();
+    }
+    catch { /* best-effort — reload still useful even if save fails */ }
     return {
         document: state.document,
         title: state.title,
@@ -1822,7 +1887,8 @@ export function hasAcceptedContent(doc) {
  * Mark leaf block nodes as pending within a node array.
  * Only marks text-containing blocks (paragraph, heading, codeBlock, etc.)
  * NOT container nodes (bulletList, orderedList, listItem, blockquote).
- * This ensures collectPendingState captures them correctly on save.
+ * Used by `applyChangesToDoc` for write_to_pad inserts where containers
+ * are handled by the explicit firstNode top-level mark.
  */
 function markLeafBlocksAsPending(nodes, status) {
     if (!nodes)
@@ -1839,8 +1905,55 @@ function markLeafBlocksAsPending(nodes, status) {
         }
     }
 }
+/**
+ * Block-level container types. Tagged as pending alongside leaves on the
+ * populate path so a fresh doc with nested content (lists, blockquotes)
+ * records the wrappers as overlay entries, not just the inner paragraphs.
+ * Without this, on reload the wrappers are gone (empty containers have no
+ * markdown representation) and inner-paragraph entries with parentNodeId
+ * pointing at the missing wrapper get classified as orphans.
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+const CONTAINER_BLOCK_TYPES = new Set([
+    'bulletList', 'orderedList', 'listItem',
+    'taskList', 'taskItem',
+    'blockquote',
+    // Footnote containers — without these, populate_document's
+    // markAllNodesAsPending pass skipped the section + definition shells,
+    // leaving their pendingStatus unset. The serializer's revert pass then
+    // dropped the inner pending paragraphs but kept the empty container
+    // shells, producing an on-disk file with `[^N]:` definition headers and
+    // no content. Marking them container-level pending makes the entire
+    // subtree get dropped together on canonical serialize and carried whole
+    // in the pending overlay.
+    // adr: adr/footnote-system.md
+    'footnoteSection', 'footnoteDefinition',
+]);
+/**
+ * Mark every block node (leaves + containers) as pending. Used by the
+ * populate path where the entire doc tree is the agent's proposal — every
+ * structural node must become an overlay entry so on reload the leaves'
+ * parentNodeId references resolve through entries placed earlier in the
+ * same batch.
+ */
+function markAllBlockNodesAsPending(nodes, status) {
+    if (!nodes)
+        return;
+    for (const node of nodes) {
+        if (node.type && (LEAF_BLOCK_TYPES.has(node.type) || CONTAINER_BLOCK_TYPES.has(node.type))) {
+            node.attrs = { ...node.attrs, pendingStatus: status };
+            if (!node.attrs.id) {
+                node.attrs.id = generateNodeId();
+            }
+        }
+        if (node.content && !LEAF_BLOCK_TYPES.has(node.type)) {
+            markAllBlockNodesAsPending(node.content, status);
+        }
+    }
+}
 export function markAllNodesAsPending(doc, status) {
-    markLeafBlocksAsPending(doc.content, status);
+    markAllBlockNodesAsPending(doc.content, status);
 }
 /** Read pending doc info from in-memory cache (O(1) instead of disk scan). */
 export function getPendingDocInfo() {
@@ -1866,6 +1979,16 @@ export function getPendingDocInfo() {
 // PERSISTENCE
 // ============================================================================
 function writeToDisk() {
+    // 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
+    // sidecar overlay write, the snapshot read+write, and the mtime bump that
+    // would invalidate the doc cache. The existsSync check ensures first-save
+    // of a new file still runs even when version state looks clean.
+    // adr: adr/pending-overlay-model.md
+    if (state.filePath && existsSync(state.filePath) && docVersion === lastSavedDocVersion) {
+        return;
+    }
     ensureDataDir();
     // Capture old forward links BEFORE we overwrite the file — needed by the
     // backlinks engine to know which target docs to refresh when source changes.
@@ -1915,12 +2038,23 @@ function writeToDisk() {
         // adr: adr/node-identity-matcher.md · adr: adr/pending-overlay-model.md
         const canonical = cloneWithPendingReverted(state.document);
         const { previousNodes, graveyard } = readPersistedIdentity(state.filePath);
+        // previousNodes and graveyard are already in rich Fingerprint form —
+        // readPersistedIdentity handles slim-tuple enrichment and legacy
+        // re-fingerprinting before returning. Matcher gets a uniform input
+        // regardless of what's on disk.
+        // adr: adr/node-identity-matcher.md
+        //
+        // newBlocks is computed once and reused by:
+        //   (a) the matcher branch below (when there are previous nodes to match)
+        //   (b) the enrichment staleness check (always — even on first save)
+        // Hoisted outside the matcher conditional so first-save staleness still
+        // gets the current sentence-hash signal.
+        const newBlocks = tiptapToBlocks(canonical);
         let nextGraveyard = graveyard;
         const idTranslation = new Map();
         if (previousNodes.length > 0) {
-            const newBlocks = tiptapToBlocks(canonical);
             const beforeIds = newBlocks.map((b) => b.id);
-            const matchResult = matchNodes(previousNodes, newBlocks, { graveyard });
+            const matchResult = matchNodes(previousNodes, newBlocks, { graveyard: nextGraveyard });
             const pinnedByPosition = new Map();
             for (const p of matchResult.pinned)
                 pinnedByPosition.set(p.position, p.id);
@@ -1964,6 +2098,27 @@ function writeToDisk() {
         if (state.docId) {
             saveOverlay(state.docId, Array.from(state.overlay.values()));
         }
+        // ENRICHMENT STALENESS — reuses the matcher's sentence-hash machinery.
+        // After the matcher pass, harvest current sentence hashes + char count
+        // from the same blocks the matcher just operated on; compare against the
+        // at-enrichment baseline in frontmatter. Flip enrichmentStale=true when
+        // volume or drift thresholds trip. OpenWriter never clears the flag —
+        // that's the agent's job via mark_enriched (Phase 4).
+        //
+        // adr: see brief 2026-05-18-frontmatter-enrichment-system
+        try {
+            const currentSentences = harvestSentenceHashes(newBlocks);
+            const currentChars = harvestCharCount(newBlocks);
+            const stale = isEnrichmentStale(currentSentences, currentChars, state.metadata);
+            if (stale && state.metadata.enrichmentStale !== true) {
+                state.metadata.enrichmentStale = true;
+                diagLog(`[Enrichment] stale: ${state.filePath}`);
+            }
+        }
+        catch (err) {
+            // Staleness detection is observational, never load-bearing for the save.
+            console.error('[Enrichment] staleness check failed:', err);
+        }
         // Pass graveyard through metadata so the serializer can emit it in frontmatter.
         const metaWithGraveyard = nextGraveyard.length > 0
             ? { ...state.metadata, graveyard: nextGraveyard.map((g) => ({ id: g.id, fp: g.fingerprint })) }
@@ -1984,6 +2139,10 @@ function writeToDisk() {
                     state.loadedMtime = statSync(state.filePath).mtimeMs;
                 }
                 catch { /* best-effort */ }
+                // Mark in-sync at this docVersion so the next save bails at the
+                // top-level gate before re-running serialize. Without this, the
+                // gate would only kick in after a real disk write.
+                lastSavedDocVersion = docVersion;
                 return;
             }
         }
@@ -2037,6 +2196,9 @@ function writeToDisk() {
         state.loadedMtime = statSync(state.filePath).mtimeMs;
     }
     catch { /* best-effort */ }
+    // 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
     try {
         snapshotIfNeeded(state.docId, state.filePath);
@@ -2554,6 +2716,28 @@ export function countPending(nodes) {
  *  adr: adr/pending-overlay-model.md */
 function flushDocToFile(filename, doc, title, metadata) {
     const targetPath = resolveDocPath(filename);
+    // Enrichment staleness — same signal as writeToDisk, but flushDocToFile
+    // bypasses the matcher entirely so we harvest sentence hashes directly.
+    // Measure the canonical (pending-reverted) view since that's what lands on
+    // disk; pending overlay content rides in the sidecar and isn't part of the
+    // doc's "published" content for enrichment purposes. External docs skip —
+    // they don't participate in the enrichment graph.
+    // adr: see brief 2026-05-18-frontmatter-enrichment-system
+    if (!isExternalDoc(targetPath)) {
+        try {
+            const canonical = cloneWithPendingReverted(doc);
+            const blocks = tiptapToBlocks(canonical);
+            const currentSentences = harvestSentenceHashes(blocks);
+            const currentChars = harvestCharCount(blocks);
+            const stale = isEnrichmentStale(currentSentences, currentChars, metadata);
+            if (stale && metadata.enrichmentStale !== true) {
+                metadata.enrichmentStale = true;
+            }
+        }
+        catch (err) {
+            console.error('[Enrichment] staleness check (flush) failed:', err);
+        }
+    }
     const markdown = tiptapToMarkdown(doc, title, metadata);
     atomicWriteFileSync(targetPath, markdown);
     const docId = (metadata && typeof metadata.docId === 'string') ? metadata.docId : '';

package/dist/server/workspaces.js

@@ -326,12 +326,34 @@ export function reorderWorkspaceAfter(filename, afterFilename) {
     }
     writeOrder(order);
 }
-// ============================================================================
-// CONTEXT
-// ============================================================================
-export function updateWorkspaceContext(wsFile, context) {
+const WRITING_CONTEXT_KEYS = new Set(['characters', 'settings', 'rules']);
+const ENRICHMENT_FIELDS = new Set([
+    'logline', 'domain', 'schema', 'vocab', 'relatedWorkspaces',
+    'enrichmentVolumeThreshold', 'enrichmentDriftThreshold', 'enrichmentDisabled',
+]);
+export function updateWorkspaceContext(wsFile, update) {
     const ws = getWorkspace(wsFile);
-    ws.context = { ...ws.context, ...context };
+    // Writing context (characters/settings/rules) merge into ws.context.
+    const ctxUpdate = {};
+    for (const key of WRITING_CONTEXT_KEYS) {
+        if (key in update)
+            ctxUpdate[key] = update[key];
+    }
+    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) {
+        if (!(key in update))
+            continue;
+        const value = update[key];
+        if (value === null) {
+            delete ws[key];
+        }
+        else {
+            ws[key] = value;
+        }
+    }
     writeWorkspace(wsFile, ws);
     return ws;
 }

package/dist/server/ws.js

@@ -323,8 +323,18 @@ export function setupWebSocket(server) {
                 }
                 if (msg.type === 'switch-document' && msg.filename) {
                     try {
+                        // adr-perf: full server-side switch timing. [Switch] CLICK/SEND
+                        // on the client, [Switch:Server] RECV/DONE/BCAST on the server,
+                        // [Switch] RECEIVE/COMMIT and [Editor] mounted back on the
+                        // client. Each delta exposes where the latency lives.
+                        const tRecv = performance.now();
+                        diagLog(`[Switch:Server] RECV filename=${msg.filename}`);
                         const result = switchDocument(msg.filename);
+                        const tSwitchDone = performance.now();
+                        diagLog(`[Switch:Server] DONE filename=${msg.filename} switchDoc=${(tSwitchDone - tRecv).toFixed(1)}ms`);
                         broadcastDocumentSwitched(result.document, result.title, result.filename);
+                        const tBcastDone = performance.now();
+                        diagLog(`[Switch:Server] BCAST filename=${msg.filename} stringify+send=${(tBcastDone - tSwitchDone).toFixed(1)}ms totalServer=${(tBcastDone - tRecv).toFixed(1)}ms`);
                     }
                     catch (err) {
                         console.error('[WS] Switch document failed:', err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.15.0",
+  "version": "0.17.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",
@@ -64,6 +64,7 @@
     "gray-matter": "^4.0.3",
     "lowlight": "^3.3.0",
     "markdown-it": "^14.1.1",
+    "markdown-it-footnote": "^4.0.0",
     "markdown-it-ins": "^4.0.0",
     "markdown-it-mark": "^4.0.0",
     "markdown-it-sub": "^2.0.0",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.7.3"
+  version: "0.7.6"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -31,6 +31,18 @@ You are a writing collaborator. You read documents and make edits **exclusively
 2. **The terminal is for discussion only.** Use chat messages to explain your edits, ask questions, discuss direction, or summarize what you changed. Never use it as the writing surface.
 3. **Name every document.** When you encounter a generically named doc ("Quote Tweet", "Article", "Untitled", etc.), rename it based on its content before proceeding. Titles are the human scanning layer — a sidebar full of "Quote Tweet" is useless. Use `rename_item` with the docId. Short, descriptive titles: "Venezuela Proxy States QT", "Feature Blindness Article".
 4. **Metadata first.** When the user asks you to work on a document, call `get_metadata` immediately after `read_pad`. Tweet docs store the parent URL in `tweetContext.url`, article docs store context in `articleContext`. **Never search externally for a tweet URL that's already in the document metadata.** This prevents wasting paid API calls on information you already have.
+5. **Dispatch the enrichment minion when openwriter says so.** OpenWriter surfaces stale enrichment two ways: (a) `ENRICHMENT_STATUS: N docs need enrichment ...` in the MCP server's session-start instructions; (b) a `⚠ N docs need enrichment — spawn the enrichment minion` footer on `list_documents`, `list_workspaces`, and `get_workspace_structure` responses. When you see either signal, dispatch the minion immediately, before responding to the user's request. Use the Agent tool with `subagent_type: "openwriter-enrichment-minion"` — that subagent is installed by `npx openwriter install-skill` at `~/.claude/agents/openwriter-enrichment-minion.md` and ships with its tool allowlist restricted to the 4 MCP tools it needs (no full registry overhead). Pass a one-line prompt like `"Enrich all currently stale openwriter docs."` — the subagent has its full procedure encoded already. It runs autonomously, calls `list_dirty_docs` → `read_pad` per doc → bulk `mark_enriched`, and returns a short summary.
+
+   **Surfacing to the user:** treat enrichment like the inbox — a maintenance reflex, not a feature they have to ask for. Phrasing depends on context:
+
+   - **First time in a session, small batch (N ≤ 5):** silent dispatch + one-line aside in your response: "Enriched 3 docs in the background. Now, ..."
+   - **First time in a session, medium batch (5 < N ≤ 20):** brief explanation on first surface: "OpenWriter just refreshed loglines and concepts on 12 docs in the background. Now, ..." Sets expectations once; subsequent runs can stay silent.
+   - **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 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.
 
 ## Setup — Which Path?
 
@@ -138,8 +150,8 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `list_workspaces` | List all workspaces with title and doc count |
 | `create_workspace` | Create a new workspace |
 | `delete_workspace` | Delete a workspace and all its document files (moves to OS trash) |
-| `get_workspace_structure` | Get full workspace tree: containers, docs, tags, context |
-| `get_item_context` | Get progressive disclosure context for a doc in a workspace |
+| `get_workspace_structure` | Get full workspace tree: containers, docs, enrichment (logline/domain/docRole per doc), workspace-level vocab/schema, plus context (characters, settings, rules) |
+| `get_item_context` | Get progressive disclosure context for a doc — workspace context + the doc's own enrichment (logline, domain, concepts, docRole, status, enrichmentStale) |
 | `update_workspace_context` | Update workspace context (characters, settings, rules) |
 
 ### Workspace Organization
@@ -153,6 +165,16 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `move_item` | Move or reorder a doc, container, or workspace (type: doc/container/workspace) |
 | `rename_item` | Rename a workspace, container, or document (type: workspace/container/document) |
 
+### Enrichment (frontmatter classification + crawlability)
+
+OpenWriter detects when a doc has drifted past enrichment thresholds (sentence-hash Jaccard drift, character-count volume ratio) on every save and stamps `enrichmentStale: true`. The agent's job is to dispatch the enrichment minion (see firm rule 5 + `docs/enrichment.md` in this skill) to refresh the loglines, domain, concepts, docRole, and status fields.
+
+| Tool | Key Params | Description |
+|------|-----------|-------------|
+| `list_dirty_docs` | `workspaceFile?` | List docs that need enrichment (never enriched OR explicitly flagged stale). Returns identity + reason only — no bodies. Optionally scoped to one workspace. Docs in opted-out workspaces (`enrichmentDisabled: true`) are excluded. |
+| `mark_enriched` | `docs: [{docId, logline?, domain?, concepts?, docRole?, status?}]` | Stamp one or more docs as freshly enriched. OpenWriter auto-computes baselines (`lastEnrichedAt`, `lastEnrichedCharCount`, `lastEnrichedSentences`) and clears `enrichmentStale`. The minion calls this once at the end of its run with the full batch. |
+| `crawl` | `workspaceFile?`, `domain?`, `tags?`, `concepts?`, `docRole?`, `hasLogline?` | Bulk-read enrichment fields per doc with AND-composed filters. The agent's "scan the shelf" primitive — ~150 tokens per doc, no bodies. Pick which bodies to actually read after crawling. |
+
 ### Comments
 
 | Tool | Key Params | Description |
@@ -281,6 +303,18 @@ When creating **two or more documents together** — a tweet thread saved as sep
 - `reply` / `quote` types still require `url`
 - For a **single** document, use `create_document` — don't reach for `declare_writes` just to wrap one entry
 
+### Citations & footnotes
+
+Long-form writing (especially academic-adjacent nonfiction) uses CommonMark / Pandoc footnote syntax:
+
+- **Reference** (inline in prose): `text[^1]` — renders as a superscript chip
+- **Definition** (anywhere in the markdown body): `[^1]: footnote text` — automatically corralled into a "Footnotes" section at end-of-doc on save
+- **Mnemonic labels** allowed: `[^sapolsky2017]` survives round-trip on disk; the editor shows auto-sequential display numbers regardless
+
+Just include the syntax in `populate_document` content or `write_to_pad` content — no special tool needed. The parser handles the tokenization, the editor handles the rendering, the serializer enforces the constrained end-of-doc shape.
+
+**Scope is per-doc.** Each chapter has its own `[^1]` … `[^N]` numbering; cross-doc references aren't supported at the editor level. Full guide → `docs/footnotes.md`.
+
 ## Companion Skills (optional)
 
 For voice-matched drafting without a custom Author's Voice profile, install the **voice-presets** skill — 5 frames (authority, provocateur, logical, storyteller, business). For an AI-detection pass on output, install **anti-ai**. Both are optional and ship separately from this skill.
@@ -646,10 +680,7 @@ Then restart your Claude Code session (`/mcp` to reconnect).
 
 ### Restarting the MCP server
 
-Depends on how OpenWriter is configured:
-
-- **Claude Code with `~/.claude.json`** — run `/mcp` to reconnect.
-- **Claude Desktop with settings → developer** — there's no explicit restart button. Call `list_documents` (zero params, read-only, fast). If the previous process is dead, Claude auto-spawns a fresh one to satisfy the call. After code changes, kill the old process (`taskkill /F /PID <pid>` on Windows, `kill <pid>` on macOS/Linux) first so the spawn picks up the new build.
+Both Claude Code and Claude Desktop work the same way: there's no explicit restart button. Call `list_documents` (zero params, read-only, fast). If the previous process is dead, Claude auto-spawns a fresh one to satisfy the call. After code changes, kill the old process first (`taskkill /F /PID <pid>` on Windows, `kill <pid>` on macOS/Linux) so the spawn picks up the new build. Only fall back to `/mcp` (Claude Code) if tool calls keep returning `Connection error: fetch failed`.
 
 **Port 5050 busy** — Another OpenWriter instance owns the port. New sessions auto-enter client mode (proxying via HTTP) — tools still work. No action needed.