openwriter 0.18.1 → 0.20.0

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';
@@ -363,7 +363,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'list_documents',
-        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, domain, docRole) when present. Use the docId to target documents in other tools.',
+        description: 'List all documents. Shows title, docId, word count, last modified, active flag, and enrichment fields (logline, status, STALE marker) when present. Use the docId to target documents in other tools. v0.19.0: three-field enrichment schema — logline (LLM), status (agent: canonical / draft), STALE (system).',
         schema: {},
         handler: async () => {
             const docs = listDocuments();
@@ -372,10 +372,10 @@ export const TOOL_REGISTRY = [
                 const id = d.docId ? ` [${d.docId}]` : '';
                 const date = d.lastModified.split('T')[0];
                 const enrichBits = [];
-                if (d.domain)
-                    enrichBits.push(d.domain);
-                if (d.docRole)
-                    enrichBits.push(d.docRole);
+                // v0.19.0: only canonical surfaces — draft is the default and would
+                // clutter the listing on every doc.
+                if (d.status === 'canonical')
+                    enrichBits.push('canonical');
                 if (d.enrichmentStale === true)
                     enrichBits.push('STALE');
                 const enrichTag = enrichBits.length > 0 ? ` (${enrichBits.join(', ')})` : '';
@@ -415,8 +415,9 @@ export const TOOL_REGISTRY = [
             content_type: z.enum(['document', 'tweet', 'reply', 'quote', 'article', 'linkedin', 'newsletter', 'blog']).describe('Required. Use "document" for plain documents. Tweet/reply/quote/article/linkedin/newsletter/blog set type-specific metadata automatically.'),
             url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote" (e.g. "https://x.com/user/status/123"). Sets tweetContext.url automatically. Ignored for other content types.'),
             afterId: z.string().optional().describe('Place the new doc immediately after this docId (8-char hex) or containerId inside its parent. Omit to append to the bottom of the parent (the default — matches ascending-order convention: newest at bottom). Requires workspace.'),
+            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle. "canonical" = committed to spine / load-bearing for the workspace (use for Beats docs that have locked, Research Notes, Master References). "draft" = working / not load-bearing yet / scratch (DUMP docs, first-pass beats). Defaults to "draft" when omitted. Change later via set_metadata({ status: ... }) on lifecycle transitions. v0.19.0.'),
         },
-        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId }) => {
+        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId, status }) => {
             // Require url for reply/quote
             if ((content_type === 'reply' || content_type === 'quote') && !url) {
                 return { content: [{ type: 'text', text: `Error: content_type "${content_type}" requires a url parameter (e.g. "https://x.com/user/status/123").` }] };
@@ -444,18 +445,25 @@ export const TOOL_REGISTRY = [
             // Track the spinner key so catch can clear exactly this entry
             // (not siblings from a concurrent declare_writes).
             let spinnerKey = null;
+            // v0.19.0: agent-owned status. Defaults to "draft" when not supplied —
+            // canonical is reserved for docs that have committed to the workspace
+            // spine (Beats, Research Notes, Master References). Agent flips to
+            // canonical via set_metadata({ status: "canonical" }) on lifecycle
+            // transitions. See brief 2026-05-21-simplify-enrichment-schema-three-fields.
+            const statusMeta = { status: status ?? 'draft' };
             try {
                 if (empty) {
                     // Immediate switch — no spinner, no populate_document needed
                     const result = createDocument(title, undefined, path);
                     setAgentLock(result.filename);
-                    // Apply type-specific metadata
+                    // Apply status + type-specific metadata in one merge
+                    const initMeta = { ...statusMeta };
                     if (content_type) {
                         const typeMeta = resolveTypeMeta(content_type, url);
-                        if (typeMeta) {
-                            setMetadata(typeMeta);
-                        }
+                        if (typeMeta)
+                            Object.assign(initMeta, typeMeta);
                     }
+                    setMetadata(initMeta);
                     let wsInfo = '';
                     if (wsTarget) {
                         // Resolve afterId: it may be a docId (8-char hex) or containerId.
@@ -478,8 +486,11 @@ export const TOOL_REGISTRY = [
                 }
                 // Two-step flow: create file on disk WITHOUT switching the user's view.
                 // The spinner persists in the sidebar until populate_document is called.
+                // Merge status with any content-type metadata so it lands on the first
+                // disk write.
                 const typeMeta = content_type ? resolveTypeMeta(content_type, url) : undefined;
-                const result = createDocumentFile(title, path, typeMeta);
+                const initialMeta = { ...statusMeta, ...(typeMeta || {}) };
+                const result = createDocumentFile(title, path, initialMeta);
                 let wsInfo = '';
                 if (wsTarget) {
                     const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
@@ -556,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();
@@ -733,7 +766,7 @@ export const TOOL_REGISTRY = [
     },
     {
         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.',
+        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.',
         schema: {
             docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
             metadata: z.record(z.any()).describe('Key-value pairs to merge into frontmatter. Set a key to null to remove it.'),
@@ -801,16 +834,12 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'mark_enriched',
-        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied enrichment fields, and clears enrichmentStale. The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. See brief 2026-05-18-frontmatter-enrichment-system.',
+        description: 'Mark one or more documents as freshly enriched. Stamps openwriter-maintained baselines (lastEnrichedAt, lastEnrichedCharCount, lastEnrichedSentences) atomically with the supplied logline, clears enrichmentStale, and retires legacy enrichment fields (domain, concepts, docRole, and any LLM-written status). The agent never touches the sentence-hash layer — openwriter computes the baseline from current canonical content. Accepts an array so a workspace-wide sweep is one call. Schema simplified in v0.19.0: only logline is LLM-written; status is now agent-owned via create_document / set_metadata; domain / concepts / docRole are gone. See brief 2026-05-21-simplify-enrichment-schema-three-fields.',
         schema: {
             docs: z.array(z.object({
                 docId: z.string().describe('Target document by docId (8-char hex from list_documents).'),
-                logline: z.string().optional().describe('Précis (non-fiction) or logline (fiction). Under 250 chars. Describe the content, not the kind of doc.'),
-                domain: z.string().optional().describe('Single domain classification from the workspace vocab.'),
-                concepts: z.array(z.string()).optional().describe('Named concepts the doc references.'),
-                docRole: z.string().optional().describe('Doc role: canonical / vignette / reference / draft / chapter / beat.'),
-                status: z.string().optional().describe('Doc status: draft / canonical / stale. Archive state is implied by archivedAt.'),
-            })).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array.'),
+                logline: z.string().max(150).describe('Précis (non-fiction) or logline (fiction). Under 150 chars. Describe the content, not the kind of doc.'),
+            }).strict()).describe('One or more docs to mark enriched. Single-doc calls are a length-1 array. Strict schema — passing domain / concepts / docRole / status will fail validation (v0.19.0 schema simplification).'),
         },
         handler: async ({ docs }) => {
             const now = new Date().toISOString();
@@ -828,23 +857,19 @@ export const TOOL_REGISTRY = [
                     const blocks = tiptapToBlocks(canonical);
                     const lastEnrichedSentences = harvestSentenceHashes(blocks);
                     const lastEnrichedCharCount = harvestCharCount(blocks);
-                    // Build the atomic enrichment payload.
+                    // Build the atomic enrichment payload. v0.19.0: only logline is
+                    // LLM-written. The legacy fields (domain / concepts / docRole) get
+                    // retired on this write — `LEGACY_FIELDS_TO_RETIRE` is deleted from
+                    // the merged metadata so disk slowly converges to the new schema
+                    // as each doc gets re-enriched (lazy migration path from the brief).
                     const update = {
                         lastEnrichedAt: now,
                         lastEnrichedCharCount,
                         lastEnrichedSentences,
                         enrichmentStale: false,
+                        logline: item.logline,
                     };
-                    if (item.logline !== undefined)
-                        update.logline = item.logline;
-                    if (item.domain !== undefined)
-                        update.domain = item.domain;
-                    if (item.concepts !== undefined)
-                        update.concepts = item.concepts;
-                    if (item.docRole !== undefined)
-                        update.docRole = item.docRole;
-                    if (item.status !== undefined)
-                        update.status = item.status;
+                    const LEGACY_FIELDS_TO_RETIRE = ['domain', 'concepts', 'docRole'];
                     if (target.isActive) {
                         // Active doc: setMetadata mutates state.metadata but doesn't bump
                         // docVersion on its own — without an explicit bump, save() would
@@ -853,6 +878,9 @@ export const TOOL_REGISTRY = [
                         // writeToDisk's staleness check will see the just-stamped baseline
                         // (volumeRatio=1, drift=0) and NOT flip the flag back to true.
                         setMetadata(update);
+                        const liveMeta = getMetadata();
+                        for (const k of LEGACY_FIELDS_TO_RETIRE)
+                            delete liveMeta[k];
                         bumpDocVersion();
                         save();
                         broadcastMetadataChanged(getMetadata());
@@ -863,6 +891,8 @@ export const TOOL_REGISTRY = [
                         // serialize cycle before the new baseline lands). Disk write +
                         // cache invalidation mirrors set_metadata's non-active path.
                         const newMeta = { ...target.metadata, ...update };
+                        for (const k of LEGACY_FIELDS_TO_RETIRE)
+                            delete newMeta[k];
                         const markdown = tiptapToMarkdown(target.document, target.title, newMeta);
                         atomicWriteFileSync(target.filePath, markdown);
                         invalidateDocCache(target.filePath);
@@ -896,13 +926,11 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'crawl',
-        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~150 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay.',
+        description: 'Bulk-read enriched fields per doc, filtered by criteria. The crawl primitive — agents use this to scan the workspace shelf at concept level (~60 tokens/doc) and decide which bodies to actually read. Filters compose with AND semantics. Empty filter returns every non-archived doc. No bodies, no nodes, no pending overlay. v0.19.0 schema: status (canonical / draft) replaces docRole / domain / concepts filters — those legacy filters were dropped because the fields they queried had no authority discipline. See brief 2026-05-21-simplify-enrichment-schema-three-fields.',
         schema: {
             workspaceFile: z.string().optional().describe('Scope to one workspace.'),
-            domain: z.string().optional().describe('Exact domain match.'),
             tags: z.array(z.string()).optional().describe('Docs must have ALL listed tags.'),
-            concepts: z.array(z.string()).optional().describe('Docs must reference ALL listed concepts.'),
-            docRole: z.string().optional().describe('Exact docRole match (canonical / vignette / reference / draft / chapter / beat).'),
+            status: z.enum(['canonical', 'draft']).optional().describe('Agent-owned lifecycle filter. "canonical" returns the trusted-shelf docs (load-bearing for the workspace); "draft" returns working / superseded / scratch docs. The common crawl is `status: canonical`.'),
             hasLogline: z.boolean().optional().describe('True = only docs with a logline; false = only docs without one.'),
         },
         handler: async (filter) => {
@@ -953,7 +981,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_workspace_structure',
-        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, domain, tags, docRole, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies.',
+        description: 'Get the full structure of a workspace: tree of containers and docs, per-doc enrichment (logline, status, tags, stale flag), plus workspace-level context (characters, settings, rules) and enrichment metadata (schema, vocab, logline). Use to understand a workspace at concept level before reading bodies. v0.19.0: enrichment fields shown per-doc are logline (LLM-owned), status (agent-owned: canonical / draft), tags, and the STALE marker (system-owned).',
         schema: {
             filename: z.string().describe('Workspace manifest filename (e.g. "my-novel-a1b2c3d4.json")'),
         },
@@ -970,10 +998,11 @@ export const TOOL_REGISTRY = [
                         const e = enrichByFile.get(node.file);
                         const tags = e?.tags ?? [];
                         const enrichBits = [];
-                        if (e?.domain)
-                            enrichBits.push(e.domain);
-                        if (e?.docRole)
-                            enrichBits.push(e.docRole);
+                        // v0.19.0: status (agent-owned) replaces domain + docRole.
+                        // Only "canonical" is worth surfacing — draft is the default
+                        // and would add noise on every line.
+                        if (e?.status === 'canonical')
+                            enrichBits.push('canonical');
                         if (tags.length > 0)
                             enrichBits.push(`tags: ${tags.join(', ')}`);
                         if (e?.enrichmentStale === true)
@@ -1023,7 +1052,7 @@ export const TOOL_REGISTRY = [
     },
     {
         name: 'get_item_context',
-        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, domain, concepts, docRole, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary.',
+        description: 'Get progressive-disclosure context for a document: workspace-level context (characters, settings, rules, vocab), the doc\'s own enrichment (logline, status), tags, and the enrichmentStale flag. Use before writing to understand context, or before reading to decide whether a body read is necessary. v0.19.0: returns the three-field enrichment schema — logline (LLM), status (agent), enrichmentStale (system).',
         schema: {
             workspaceFile: z.string().describe('Workspace manifest filename'),
             docId: z.string().describe('Document docId (8-char hex from list_documents)'),
@@ -1039,14 +1068,10 @@ export const TOOL_REGISTRY = [
                 const enriched = crawlDocs({ workspaceFile });
                 const docEnrich = enriched.find((e) => e.filename === filename);
                 if (docEnrich) {
+                    // v0.19.0 three-field schema: logline (LLM), status (agent),
+                    // enrichmentStale (system). domain / concepts / docRole dropped.
                     if (docEnrich.logline)
                         base.logline = docEnrich.logline;
-                    if (docEnrich.domain)
-                        base.domain = docEnrich.domain;
-                    if (docEnrich.concepts)
-                        base.concepts = docEnrich.concepts;
-                    if (docEnrich.docRole)
-                        base.docRole = docEnrich.docRole;
                     if (docEnrich.status)
                         base.status = docEnrich.status;
                     if (docEnrich.enrichmentStale === true)
@@ -1684,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,
                         }) }] };
         },
     },
@@ -1811,20 +1790,18 @@ export const TOOL_REGISTRY = [
             const enriched = raw.slice(0, cap).map((r) => {
                 let docId = null;
                 let logline;
-                let domain;
-                let docRole;
+                let status;
                 let tags;
                 try {
                     const filePath = resolveDocPath(r.filename);
                     const fileRaw = readFileSync(filePath, 'utf-8');
                     const fm = matter(fileRaw);
                     docId = fm.data?.docId || null;
+                    // v0.19.0 three-field schema: logline (LLM), status (agent), tags.
                     if (typeof fm.data?.logline === 'string')
                         logline = fm.data.logline;
-                    if (typeof fm.data?.domain === 'string')
-                        domain = fm.data.domain;
-                    if (typeof fm.data?.docRole === 'string')
-                        docRole = fm.data.docRole;
+                    if (typeof fm.data?.status === 'string')
+                        status = fm.data.status;
                     if (Array.isArray(fm.data?.tags) && fm.data.tags.length > 0)
                         tags = fm.data.tags;
                 }
@@ -1837,8 +1814,7 @@ export const TOOL_REGISTRY = [
                     snippet: r.snippet,
                     matchedTag: r.matchedTag,
                     ...(logline ? { logline } : {}),
-                    ...(domain ? { domain } : {}),
-                    ...(docRole ? { docRole } : {}),
+                    ...(status ? { status } : {}),
                     ...(tags ? { tags } : {}),
                 };
             });
@@ -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);