openwriter 0.19.0 → 0.20.1

package/dist/server/mcp.js

@@ -14,7 +14,7 @@ import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus,
 import { tiptapToBlocks } from './node-blocks.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, updateDocumentTitle, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions } from './documents.js';
-import { extractForwardLinks } from './backlinks.js';
+import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBacklinksCache } from './backlinks.js';
 import { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
 import { listWorkspaces, getWorkspace, getDocTitle, getItemContext, addDoc, updateWorkspaceContext, createWorkspace, deleteWorkspace, addContainerToWorkspace, findOrCreateWorkspace, findOrCreateContainer, moveDoc, moveContainer, reorderWorkspaceAfter, removeContainer, renameWorkspace, renameContainer, removeDocFromAllWorkspaces, findWorkspacesContainingDoc, collectFilesInWorkspace } from './workspaces.js';
@@ -567,6 +567,28 @@ export const TOOL_REGISTRY = [
                 if (!isAutoAcceptActive(filename || getActiveFilename(), getMetadata())) {
                     markAllNodesAsPending(doc, 'insert');
                 }
+                // Bug #1 fix (v0.20.0): preserve the stub's trailing canonical paragraph(s).
+                // updateDocument(doc) overwrites state.canonical wholesale — without this
+                // merge, the create_document → populate_document sequence loses the stub's
+                // auto-generated trailing paragraph from canonical. When the browser later
+                // accepts the inserts and sends a doc-update with its TipTap-rendered tree
+                // (which also has a trailing empty paragraph, but a different ID), the
+                // save-time matcher classifies the stub's original trailing as deleted →
+                // graveyard, while the freshly added inserts have no previousNodes match.
+                // Cascading state corruption observed in live test 2026-05-22.
+                const existingCanonical = getCanonical();
+                if (existingCanonical?.content?.length) {
+                    const incomingIds = new Set(doc.content
+                        .map((n) => n?.attrs?.id)
+                        .filter((id) => typeof id === 'string'));
+                    const preserved = existingCanonical.content.filter((n) => {
+                        const id = n?.attrs?.id;
+                        return id && !incomingIds.has(id);
+                    });
+                    if (preserved.length > 0) {
+                        doc.content = [...doc.content, ...preserved];
+                    }
+                }
                 updateDocument(doc);
                 updatePendingCacheForActiveDoc();
                 save();
@@ -1687,115 +1709,69 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'link_to',
-        description: 'Wrap anchor text in a source doc with a doc: link pointing at another doc. Operates in place on the block containing the anchor text — never creates a duplicate paragraph. Optionally target a specific paragraph (target_node_id) for paragraph-level navigation, with an optional quote for scroll-anchor fallback. The on-save backlinks pipeline then auto-updates the target doc\'s frontmatter `backlinks` field — so this single tool call creates both the forward link and the backlink. Use after writing prose to cross-reference concepts: agent writes about "territorial imperative" then calls link_to to point that phrase at the canonical concept doc.',
+        description: 'Declare a structural doc-to-doc connection. Writes target_doc_id into the source doc\'s `references:` frontmatter array. Body markdown is NEVER mutated — this is metadata, not prose. Idempotent: calling twice with the same source/target is a no-op. The inbound list on the target is computed live from the inverse of every doc\'s references — no stored derived field. v0.20.0 breaking change: dropped `text`, `target_node_id`, and `quote` parameters; connections are structural, not anchored to prose. Legacy prose `doc:` links continue to render and auto-populate `references` on save (backward compat).',
         schema: {
-            text: z.string().describe('Anchor text in the source doc to wrap with the link. Exact substring match. First UNLINKED occurrence wins — calling link_to N times with the same anchor wraps N distinct occurrences, skipping ones already linked to the same target.'),
-            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc containing the anchor text. NOT the active doc — must be explicit so user-driven navigation in the browser can\'t silently change the target.'),
-            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the link points AT.'),
-            target_node_id: z.string().optional().describe('Optional 8-char hex nodeId for paragraph-level targeting. When provided, clicking the link scrolls to that paragraph in the target doc.'),
-            quote: z.string().optional().describe('Optional text snippet for scroll-anchor fallback when target_node_id has drifted (e.g. paragraph was rewritten).'),
+            source_doc_id: z.string().describe('Source document docId (8-char hex from list_documents). The doc declaring the connection.'),
+            target_doc_id: z.string().describe('Target document docId (8-char hex from list_documents or search_docs). The doc the connection points AT.'),
         },
-        handler: async ({ text, source_doc_id, target_doc_id, target_node_id, quote }) => {
+        handler: async ({ source_doc_id, target_doc_id }) => {
             const sourceFilename = resolveDocId(source_doc_id);
             if (!sourceFilename) {
                 return { content: [{ type: 'text', text: `source_doc_id "${source_doc_id}" not found. Use list_documents to find the right docId.` }] };
             }
-            // Build the href in canonical doc:DOCID#NODEID?q=quote form so we can also
-            // detect "this text is already wrapped with THIS link" and skip it.
-            let href = `doc:${target_doc_id}`;
-            if (target_node_id)
-                href += `#${target_node_id}`;
-            if (quote)
-                href += `?q=${encodeURIComponent(quote)}`;
-            // Load the source doc — from in-memory state if it's active, from disk
-            // otherwise. Explicit source dispatch prevents the active-doc race where
-            // a user click in the browser silently changes which doc gets edited.
+            const targetFilename = resolveDocId(target_doc_id);
+            if (!targetFilename) {
+                return { content: [{ type: 'text', text: `target_doc_id "${target_doc_id}" not found. Use list_documents or search_docs to find the right docId.` }] };
+            }
+            if (source_doc_id === target_doc_id) {
+                return { content: [{ type: 'text', text: `Cannot link a document to itself (source_doc_id and target_doc_id are both "${source_doc_id}").` }] };
+            }
+            // Load source's current references (active doc → in-memory; otherwise → disk).
             const sourceIsActive = sourceFilename === getActiveFilename();
-            let sourceDoc;
+            let currentReferences;
             if (sourceIsActive) {
-                sourceDoc = getDocument();
+                const meta = getMetadata();
+                currentReferences = Array.isArray(meta?.references) ? [...meta.references] : [];
             }
             else {
-                const cached = getCachedDocument(resolveDocPath(sourceFilename));
-                if (cached) {
-                    sourceDoc = cached.document;
-                }
-                else {
-                    try {
-                        const raw = readFileSync(resolveDocPath(sourceFilename), 'utf-8');
-                        sourceDoc = markdownToTiptap(raw).document;
-                    }
-                    catch (err) {
-                        return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}": ${err.message}` }] };
-                    }
-                }
+                const fm = readFrontmatter(sourceFilename);
+                currentReferences = Array.isArray(fm?.data?.references) ? [...fm.data.references] : [];
             }
-            // Locate the first block containing the anchor text WHERE the text is
-            // not already entirely wrapped with a link to the same href. This makes
-            // link_to idempotent and lets repeat calls wrap successive occurrences.
-            let sourceNodeId = null;
-            let totalOccurrences = 0;
-            let alreadyLinkedOccurrences = 0;
-            function isTextAlreadyLinked(nodeContent) {
-                // Concatenate text from inline children that have a link mark matching href
-                let linkedText = '';
-                for (const child of nodeContent) {
-                    if (child.type !== 'text' || !child.text)
-                        continue;
-                    const marks = child.marks || [];
-                    const hasMatchingLink = marks.some((m) => m.type === 'link' && m.attrs?.href === href);
-                    if (hasMatchingLink)
-                        linkedText += child.text;
-                }
-                return linkedText.includes(text);
+            // Idempotent: target already declared → no-op.
+            if (currentReferences.includes(target_doc_id)) {
+                return { content: [{ type: 'text', text: JSON.stringify({
+                                success: true,
+                                sourceDocId: source_doc_id,
+                                targetDocId: target_doc_id,
+                                alreadyReferenced: true,
+                                references: currentReferences,
+                            }) }] };
             }
-            function walk(nodes) {
-                if (sourceNodeId)
-                    return;
-                for (const node of nodes) {
-                    if (sourceNodeId)
-                        return;
-                    if (Array.isArray(node.content)) {
-                        const blockText = node.content.map((c) => c.text || '').join('');
-                        if (node.attrs?.id && blockText.includes(text)) {
-                            totalOccurrences++;
-                            if (isTextAlreadyLinked(node.content)) {
-                                alreadyLinkedOccurrences++;
-                                walk(node.content);
-                                continue;
-                            }
-                            sourceNodeId = node.attrs.id;
-                            return;
-                        }
-                        walk(node.content);
-                    }
-                }
+            // Append + dedup via Set round-trip.
+            const newReferences = Array.from(new Set([...currentReferences, target_doc_id]));
+            if (sourceIsActive) {
+                // Active doc: mutate state.metadata and let save() persist the frontmatter.
+                // save()'s writeToDisk path invalidates the backlinks cache.
+                setMetadata({ references: newReferences });
+                save();
+                broadcastMetadataChanged(getMetadata());
             }
-            walk(sourceDoc.content);
-            if (!sourceNodeId) {
-                if (totalOccurrences > 0 && totalOccurrences === alreadyLinkedOccurrences) {
-                    return { content: [{ type: 'text', text: `Anchor text "${text}" found in source doc but all ${totalOccurrences} occurrence(s) are already linked to ${href}. Nothing to do.` }] };
+            else {
+                // Non-active doc: write frontmatter directly, preserving body verbatim.
+                const fm = readFrontmatter(sourceFilename);
+                if (!fm) {
+                    return { content: [{ type: 'text', text: `Failed to read source doc "${source_doc_id}" frontmatter.` }] };
                 }
-                return { content: [{ type: 'text', text: `Anchor text "${text}" not found in source doc "${source_doc_id}" (${sourceFilename}). Use search_docs or read_pad to verify.` }] };
-            }
-            // Apply the link mark in place. Dispatch by active vs non-active so the
-            // edit always lands in the right doc — never silently in whatever doc
-            // happens to be foregrounded in the browser.
-            const editResult = sourceIsActive
-                ? applyTextEdits(sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }])
-                : applyTextEditsToFile(sourceFilename, sourceNodeId, [{ find: text, addMark: { type: 'link', attrs: { href } } }]);
-            if (!editResult.success) {
-                return { content: [{ type: 'text', text: `Failed to apply link mark: ${editResult.error}` }] };
+                const merged = { ...fm.data, references: newReferences };
+                writeFrontmatter(sourceFilename, merged);
+                invalidateDocCache(resolveDocPath(sourceFilename));
+                invalidateBacklinksCache();
             }
-            if (sourceIsActive)
-                save(); // triggers writeToDisk → backlinks pipeline updates target's frontmatter
             return { content: [{ type: 'text', text: JSON.stringify({
                             success: true,
                             sourceDocId: source_doc_id,
-                            sourceFilename,
-                            nodeId: sourceNodeId,
-                            href,
-                            ...(totalOccurrences > 1 ? { remainingUnlinked: totalOccurrences - alreadyLinkedOccurrences - 1 } : {}),
+                            targetDocId: target_doc_id,
+                            references: newReferences,
                         }) }] };
         },
     },
@@ -1847,7 +1823,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_graph',
-        description: 'Return forward links + backlinks for a doc — the crawl primitive for cross-doc context retrieval. Forward links extracted from the doc body, backlinks read from the doc\'s frontmatter (maintained by the on-save backlinks pipeline). Optional depth walks neighbors recursively (cap 3).',
+        description: 'Return forward + inbound connections for a doc — the crawl primitive for cross-doc context retrieval. Forward connections read from the doc\'s `references:` frontmatter (structural data, v0.20). Inbound computed live by scanning every doc\'s references for entries pointing at this one (no stored derived field). Optional depth walks neighbors recursively (cap 3). v0.20.0 breaking change: edges are doc-to-doc; per-paragraph granularity (from_node/to_node/anchor text) was dropped — that was an artifact of the prose-link model.',
         schema: {
             docId: z.string().describe('Center docId for the graph walk (8-char hex).'),
             depth: z.number().optional().describe('Hops to walk outward (default 1, max 3). depth=1 returns just the center\'s links; depth=2 also includes neighbors\' links.'),
@@ -1867,28 +1843,18 @@ export const TOOL_REGISTRY = [
                 catch {
                     return;
                 }
-                const forward = extractForwardLinks(target.document, id);
-                const backlinks = Array.isArray(target.metadata.backlinks) ? target.metadata.backlinks : [];
+                const forward = Array.isArray(target.metadata.references) ? target.metadata.references : [];
+                const backlinks = computeBacklinksFor(id);
                 nodes.push({
                     docId: id,
                     title: target.title,
-                    forward: forward.map((l) => ({
-                        text: l.text,
-                        from_node: l.from_node,
-                        to_doc: l.to_doc,
-                        ...(l.to_node ? { to_node: l.to_node } : {}),
-                    })),
-                    backlinks: backlinks.map((b) => ({
-                        text: b.text,
-                        from_doc: b.from_doc,
-                        from_node: b.from_node,
-                        ...(b.to_node ? { to_node: b.to_node } : {}),
-                    })),
+                    forward: forward.map((to_doc) => ({ to_doc })),
+                    backlinks: backlinks.map((b) => ({ from_doc: b.from_doc })),
                 });
                 if (hopsLeft > 0) {
                     const neighbors = new Set();
-                    for (const l of forward)
-                        neighbors.add(l.to_doc);
+                    for (const to_doc of forward)
+                        neighbors.add(to_doc);
                     for (const b of backlinks)
                         neighbors.add(b.from_doc);
                     for (const n of neighbors) {

package/dist/server/state.js

@@ -10,7 +10,7 @@ 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 } from './versions.js';
-import { extractForwardLinks, extractForwardLinksFromDisk, updateBacklinksForSource } from './backlinks.js';
+import { syncReferencesFromProse, invalidateBacklinksCache, writeFrontmatter } from './backlinks.js';
 import { isAutoAcceptInheritedForDoc } from './workspaces.js';
 import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
@@ -434,6 +434,15 @@ function stripLegacyAgentCreated(metadata) {
     if (metadata && 'agentCreated' in metadata)
         delete metadata.agentCreated;
 }
+/** Strip the legacy `backlinks` field. v0.19 stored derived inbound edges in
+ *  frontmatter; v0.20 computes them live from the inverse of `references`
+ *  across the workspace. Any save that visits a doc with the stale field drops
+ *  it — lazy migration. No data loss because the new `references` field on
+ *  source docs is the authoritative inbound source; we can always recompute. */
+function stripLegacyBacklinks(metadata) {
+    if (metadata && 'backlinks' in metadata)
+        delete metadata.backlinks;
+}
 function persistExternalDocs() {
     try {
         atomicWriteFileSync(getExternalDocsFile(), JSON.stringify([...externalDocs]));
@@ -1990,16 +1999,6 @@ function writeToDisk() {
         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.
-    // Skip for external docs (they don't participate in the doc graph).
-    let oldForwardLinks = [];
-    if (!isExternalDoc(state.filePath) && state.docId) {
-        try {
-            oldForwardLinks = extractForwardLinksFromDisk(state.filePath, state.docId);
-        }
-        catch { /* best-effort */ }
-    }
     // Stub graduation: once the doc contains accepted content, it's no longer
     // a fresh stub. Remove it from the in-memory stub registry so reject-all
     // can never trigger the cleanup-delete on it.
@@ -2009,8 +2008,10 @@ function writeToDisk() {
     }
     // Defensive: never serialize `agentCreated` to disk. The field is dead;
     // any code reading it would be the bug, not the field's presence.
-    if (state.metadata)
+    if (state.metadata) {
         stripLegacyAgentCreated(state.metadata);
+        stripLegacyBacklinks(state.metadata);
+    }
     let markdown;
     if (isExternalDoc(state.filePath)) {
         // External files: preserve original frontmatter verbatim, no OpenWriter metadata injected.
@@ -2204,16 +2205,27 @@ function writeToDisk() {
         snapshotIfNeeded(state.docId, state.filePath);
     }
     catch { /* ignore */ }
-    // Backlinks update: refresh target docs' backlinks frontmatter if source's
-    // forward links changed. Best-effort — never blocks the save it follows.
+    // 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
+    // prose links and merge their targets into references — backward compat
+    // without forcing rewrites. Then invalidate the live-backlinks cache so
+    // the next /api/backlinks/:docId call sees the fresh inverse.
+    // Best-effort — never blocks the save it follows.
     if (!isExternalDoc(state.filePath) && state.docId) {
         try {
-            const newForwardLinks = extractForwardLinks(state.document, state.docId);
-            updateBacklinksForSource(state.docId, newForwardLinks, oldForwardLinks);
+            const sync = syncReferencesFromProse(state.docId, state.document, state.metadata || {});
+            if (sync && state.metadata) {
+                state.metadata.references = sync.newReferences;
+                // Second tiny write: re-persist frontmatter only (body already on disk).
+                const filename = state.filePath.split(/[/\\]/).pop() || '';
+                writeFrontmatter(filename, state.metadata);
+            }
         }
         catch (err) {
-            console.error('[State] backlinks update failed:', err);
+            console.error('[State] references auto-sync failed:', err);
         }
+        invalidateBacklinksCache();
     }
 }
 export function save() {
@@ -2756,6 +2768,28 @@ export function populateDocumentFile(filename, doc) {
     if (!isAutoAcceptActive(filename, parsed.metadata)) {
         markAllNodesAsPending(doc, 'insert');
     }
+    // Bug #1 fix (v0.20.0): preserve the stub's trailing canonical paragraph(s).
+    // flushDocToFile writes `doc` directly — it does NOT merge with the existing
+    // parsed.document on disk. Without this merge step, the stub's auto-generated
+    // trailing paragraph falls out of canonical, the matcher's `previousNodes`
+    // for any subsequent save no longer references it, and a follow-up Accept All
+    // doc-update can find itself with no matching previousNodes to anchor against.
+    // Cascading: the matcher classifies the newly accepted inserts as deletions
+    // (orphaned from the empty previousNodes set), they go to graveyard, the disk
+    // body ends up empty.
+    // Mirrors the active-doc fix in mcp.ts:populate_document.
+    if (parsed.document?.content?.length) {
+        const incomingIds = new Set(doc.content
+            .map((n) => n?.attrs?.id)
+            .filter((id) => typeof id === 'string'));
+        const preserved = parsed.document.content.filter((n) => {
+            const id = n?.attrs?.id;
+            return id && !incomingIds.has(id);
+        });
+        if (preserved.length > 0) {
+            doc.content = [...doc.content, ...preserved];
+        }
+    }
     flushDocToFile(filename, doc, parsed.title, parsed.metadata);
     const pendingCount = countPending(doc.content);
     const text = extractText(doc.content);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.7.6"
+  version: "0.10.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -31,12 +31,12 @@ 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.
+5. **Dispatch the enrichment minion when openwriter says so.** OpenWriter surfaces stale enrichment two ways: (a) `ENRICHMENT_STATUS: ...` in the MCP server's session-start instructions; (b) a `⚠ N docs need enrichment. Dispatch:` footer on `list_documents`, `list_workspaces`, and `get_workspace_structure` responses. 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 is orchestrator-mode by default: it calls `list_dirty_docs` itself, self-bounds the batch, reads each doc, writes a logline, calls `mark_enriched` once with the whole batch, and returns a short summary. **v0.19.0 schema:** the minion writes ONE field — `logline`. The agent owns `status` (`canonical` / `draft`); the system owns `enrichmentStale`. The legacy fields `domain`, `concepts`, and `docRole` were dropped. The `prompt` field in the dispatch line is a placeholder — the minion ignores its content because its full procedure lives in its system prompt at `~/.claude/agents/openwriter-enrichment-minion.md`.
 
    **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, medium batch (5 < N ≤ 20):** brief explanation on first surface: "OpenWriter just refreshed loglines 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.
 
@@ -150,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, 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) |
+| `get_workspace_structure` | Get full workspace tree: containers, docs, per-doc enrichment (logline, status, STALE marker), 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, status, enrichmentStale) |
 | `update_workspace_context` | Update workspace context (characters, settings, rules) |
 
 ### Workspace Organization
@@ -165,15 +165,29 @@ 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)
+### Enrichment (three-field schema — v0.19.0)
 
-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.
+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 logline.
+
+**The three-field schema** — each field has exactly one owner:
+
+| Field | Owner | Set how |
+|-------|-------|---------|
+| `logline` | LLM (minion) | `mark_enriched({ docs: [{ docId, logline }] })` |
+| `status` (`canonical` / `draft`) | Agent | `create_document({ status })` on create; `set_metadata({ status })` on lifecycle change |
+| `enrichmentStale` | System | OpenWriter sets on save; minion clears on `mark_enriched` |
+
+**Lifecycle convention for `status`:**
+- Default to `draft` on new docs (omit `status` from `create_document` and it lands as `draft`).
+- Flip to `canonical` when the doc commits to the workspace spine (Beats locked, Research Note is now load-bearing, Master Reference is the source of truth).
+- Flip back to `draft` when superseded (e.g. Ch 7 Beats v3 ships → demote v1/v2 to `draft`).
+- The common crawl pattern is `crawl({ status: "canonical" })` — that's the trusted-shelf query.
 
 | 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. |
+| `mark_enriched` | `docs: [{docId, logline}]` | Stamp one or more docs as freshly enriched. **Strict schema** — passing `domain` / `concepts` / `docRole` / `status` fails validation. OpenWriter auto-computes baselines (`lastEnrichedAt`, `lastEnrichedCharCount`, `lastEnrichedSentences`), clears `enrichmentStale`, and retires legacy fields from frontmatter. The minion calls this once at the end of its run with the full batch. |
+| `crawl` | `workspaceFile?`, `tags?`, `status?` (`canonical`/`draft`), `hasLogline?` | Bulk-read enrichment fields per doc with AND-composed filters. The agent's "scan the shelf" primitive — ~60 tokens per doc, no bodies. v0.19.0 dropped `domain` / `concepts` / `docRole` filters (their fields had no authority discipline); `status` is the replacement axis for the common load-bearing-vs-working query. |
 
 ### Comments
 
@@ -275,9 +289,12 @@ create_document({
 
 - **`workspace`** (string) — workspace title to add the doc to. Auto-creates if not found (case-insensitive match).
 - **`container`** (string) — container name within the workspace (e.g. "Chapters", "Notes", "References"). Auto-creates if not found. Requires `workspace`.
-- Both are optional — omit for standalone docs outside any workspace.
+- **`afterId`** (string, optional) — docId (8-char hex) or containerId to place the new doc immediately after. Omit and the doc lands at the **bottom** of its parent (the default since 0.18.0, matching the ascending-order convention: oldest at top, newest at bottom). Use `afterId` when you need surgical placement — e.g. inserting a new chapter doc immediately after the chapter's Beats doc.
+- All three are optional — omit `workspace` for standalone docs outside any workspace.
+
+This eliminates the need for separate `create_workspace`, `create_container`, and `move_item` calls when building up a workspace. The default-bottom landing also eliminates the need for a follow-up `move_item` pass to fix sidebar order after every create — the doc lands in convention position the first time.
 
-This eliminates the need for separate `create_workspace`, `create_container`, and `move_item` calls when building up a workspace.
+`create_container` accepts the same `afterId` parameter with identical semantics — new containers default to the bottom of their parent and can be precisely placed via `afterId`. The Drafts sub-container that goes under every chapter container, for example, can be created with `afterId` set to the chapter's Research Notes docId so it lands at the very bottom in one call.
 
 ### Batched Creation (multiple docs at once)
 
@@ -299,7 +316,7 @@ When creating **two or more documents together** — a tweet thread saved as sep
 **Rules:**
 - Each write in the batch gets its own sidebar spinner keyed to its filename — a spinner only clears when you `populate_document` that specific `docId`
 - Spinners persist across app refreshes (server-side registry)
-- Same per-write fields as `create_document`: `title`, `content_type`, optional `workspace`/`container`/`url`/`path`
+- Same per-write fields as `create_document`: `title`, `content_type`, optional `workspace`/`container`/`url`/`path`/`afterId`
 - `reply` / `quote` types still require `url`
 - For a **single** document, use `create_document` — don't reach for `declare_writes` just to wrap one entry