npm - openwriter - Versions diffs - 0.16.0 → 0.18.0 - Mend

openwriter 0.16.0 → 0.18.0

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

Files changed (18) hide show

package/dist/client/assets/index-0ttVnjRp.css +1 -0
package/dist/client/assets/{index-JMMJM_G_.js → index-BZ7LCzrR.js} +57 -57
package/dist/client/index.html +2 -2
package/dist/server/compact.js +28 -2
package/dist/server/enrichment.js +13 -2
package/dist/server/export-routes.js +2 -0
package/dist/server/markdown-parse.js +82 -0
package/dist/server/markdown-serialize.js +86 -1
package/dist/server/mcp.js +60 -10
package/dist/server/node-blocks.js +41 -1
package/dist/server/state.js +22 -15
package/dist/server/workspace-tree.js +18 -3
package/dist/server/workspaces.js +2 -2
package/package.json +2 -1
package/skill/SKILL.md +13 -1
package/skill/agents/openwriter-enrichment-minion.md +3 -10
package/skill/docs/footnotes.md +178 -0
package/dist/client/assets/index-CbSQ8xxn.css +0 -1

package/dist/client/index.html CHANGED Viewed

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

package/dist/server/compact.js CHANGED Viewed

@@ -33,6 +33,8 @@ const TYPE_MAP = {
     taskList: 'tasks',
     taskItem: 'task',
     image: 'img',
+    footnoteSection: 'fnsec',
+    footnoteDefinition: 'fndef',
 };
 function nodeId(id) {
     return id || '________';
@@ -50,6 +52,10 @@ function inlineToCompact(nodes) {
     return nodes.map((node) => {
         if (node.type === 'hardBreak')
             return '\n';
+        if (node.type === 'footnoteReference') {
+            const label = node.attrs?.label || '';
+            return `[^${label}]`;
+        }
         if (node.type !== 'text')
             return '';
         let text = node.text || '';
@@ -127,14 +133,34 @@ function nodeToCompactLines(node, indent) {
         lines.push(`${indent}${tag} ![${alt}](${src})`);
         return lines;
     }
-    // Container nodes (lists, blockquotes, taskLists)
-    if (['bulletList', 'orderedList', 'blockquote', 'taskList'].includes(node.type)) {
+    // Container nodes (lists, blockquotes, taskLists, footnoteSection)
+    if (['bulletList', 'orderedList', 'blockquote', 'taskList', 'footnoteSection'].includes(node.type)) {
         lines.push(`${indent}${tag}`);
         for (const child of node.content || []) {
             lines.push(...nodeToCompactLines(child, indent + '  '));
         }
         return lines;
     }
+    // Footnote definition — show label inline + first paragraph's text;
+    // nest additional paragraphs (rare).
+    if (node.type === 'footnoteDefinition') {
+        const label = node.attrs?.label || '';
+        const children = node.content || [];
+        if (children.length > 0 && children[0].type === 'paragraph') {
+            const text = inlineToCompact(children[0].content);
+            lines.push(`${indent}${tag} [^${label}]: ${text}`);
+            for (let i = 1; i < children.length; i++) {
+                lines.push(...nodeToCompactLines(children[i], indent + '  '));
+            }
+        }
+        else {
+            lines.push(`${indent}${tag} [^${label}]:`);
+            for (const child of children) {
+                lines.push(...nodeToCompactLines(child, indent + '  '));
+            }
+        }
+        return lines;
+    }
     // Task items — checkbox prefix + first paragraph inline
     if (node.type === 'taskItem') {
         const checked = node.attrs?.checked ? '[x]' : '[ ]';

package/dist/server/enrichment.js CHANGED Viewed

@@ -21,8 +21,19 @@
 import { splitSentences, simpleHash } from './node-fingerprint.js';
 /** Volume-ratio threshold above which a doc is flagged stale by size delta. */
 export const DEFAULT_ENRICHMENT_VOLUME_THRESHOLD = 1.5;
-/** Jaccard-distance threshold above which a doc is flagged stale by drift. */
-export const DEFAULT_ENRICHMENT_DRIFT_THRESHOLD = 0.3;
+/**
+ * Jaccard-distance threshold above which a doc is flagged stale by drift.
+ *
+ * 0.10 catches in-place architectural rewrites that volume-ratio misses —
+ * e.g. inserting a Status Update section into a 200-sentence doc adds
+ * ~25 new sentences, ~0 removed: distance = 25/225 ≈ 0.11, trips at 0.10.
+ * Won't false-positive on routine editing — a 3-sentence paragraph addition
+ * to a 200-sentence doc is 3/203 ≈ 0.015, well below.
+ *
+ * Tightened from 0.3 → 0.10 after 2026-05-19 brief reported the Argument
+ * Arc class of rewrites slipping through.
+ */
+export const DEFAULT_ENRICHMENT_DRIFT_THRESHOLD = 0.10;
 /**
  * Flatten every block's per-sentence hashes into one sorted unique set.
  * Sorted so the on-disk representation is stable across saves (no spurious

package/dist/server/export-routes.js CHANGED Viewed

@@ -8,6 +8,7 @@ import markdownItIns from 'markdown-it-ins';
 import markdownItMark from 'markdown-it-mark';
 import markdownItSub from 'markdown-it-sub';
 import markdownItSup from 'markdown-it-sup';
+import markdownItFootnote from 'markdown-it-footnote';
 import { tiptapToMarkdown } from './markdown.js';
 import { getDocument, getTitle, getPlainText, getMetadata } from './state.js';
 import { buildExportHtml } from './export-html-template.js';
@@ -18,6 +19,7 @@ md.use(markdownItIns);
 md.use(markdownItMark);
 md.use(markdownItSub);
 md.use(markdownItSup);
+md.use(markdownItFootnote);
 /** Strip YAML frontmatter (---\n...\n---\n\n) from markdown output. */
 function stripFrontmatter(markdown) {
     const match = markdown.match(/^---\n[\s\S]*?\n---\n\n/);

package/dist/server/markdown-parse.js CHANGED Viewed

@@ -17,6 +17,7 @@ import markdownItIns from 'markdown-it-ins';
 import markdownItMark from 'markdown-it-mark';
 import markdownItSub from 'markdown-it-sub';
 import markdownItSup from 'markdown-it-sup';
+import markdownItFootnote from 'markdown-it-footnote';
 import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
 import { nodeText } from './markdown-serialize.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
@@ -31,6 +32,7 @@ md.use(markdownItIns);
 md.use(markdownItMark);
 md.use(markdownItSub);
 md.use(markdownItSup);
+md.use(markdownItFootnote);
 /**
  * Normalize blank lines INSIDE markdown tables before parsing.
  *
@@ -386,12 +388,81 @@ function tokensToTiptap(tokens) {
             nodes.push(tableNode);
             i = end + 1;
         }
+        else if (token.type === 'footnote_block_open') {
+            // Footnote definitions section. markdown-it-footnote always emits
+            // this block at end-of-doc with all `[^N]: ...` definitions inside,
+            // regardless of where in the source the `[^N]:` lines appeared.
+            // Parse accepts flexibly; serializer always emits at end-of-doc.
+            // adr: adr/footnote-system.md
+            const end = findClosingToken(tokens, i, 'footnote_block');
+            const definitions = parseFootnoteDefinitions(tokens.slice(i + 1, end));
+            if (definitions.length > 0) {
+                nodes.push({
+                    type: 'footnoteSection',
+                    attrs: { id: generateNodeId() },
+                    content: definitions,
+                });
+            }
+            i = end + 1;
+        }
         else {
             i += 1;
         }
     }
     return nodes;
 }
+/**
+ * Parse the contents of a footnote_block (between footnote_block_open and
+ * footnote_block_close). Each footnote is a footnote_open ... footnote_close
+ * range containing block-level tokens (paragraphs, lists, etc).
+ *
+ * Strips the trailing `footnote_anchor` back-link that markdown-it-footnote
+ * appends to each footnote's last paragraph — it's a renderer artifact, not
+ * source content.
+ */
+function parseFootnoteDefinitions(tokens) {
+    const definitions = [];
+    let i = 0;
+    while (i < tokens.length) {
+        if (tokens[i].type === 'footnote_open') {
+            const label = tokens[i].meta?.label || String(tokens[i].meta?.id ?? '');
+            const end = findClosingToken(tokens, i, 'footnote');
+            const innerTokens = stripFootnoteAnchors(tokens.slice(i + 1, end));
+            const content = tokensToTiptap(innerTokens);
+            definitions.push({
+                type: 'footnoteDefinition',
+                attrs: { id: generateNodeId(), label },
+                content: content.length > 0
+                    ? content
+                    : [{ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] }],
+            });
+            i = end + 1;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return definitions;
+}
+/**
+ * Remove `footnote_anchor` tokens from inline children. markdown-it-footnote
+ * appends an anchor (rendered as ↩︎) to the last paragraph of each footnote
+ * to back-link to the reference. We strip it on parse because it's a
+ * rendering artifact, not source content the author wrote.
+ */
+function stripFootnoteAnchors(tokens) {
+    return tokens.map((token) => {
+        if (token.type !== 'inline' || !token.children)
+            return token;
+        const filtered = token.children.filter((c) => c.type !== 'footnote_anchor');
+        if (filtered.length === token.children.length)
+            return token;
+        // Clone token with filtered children
+        const cloned = Object.assign(Object.create(Object.getPrototypeOf(token)), token);
+        cloned.children = filtered;
+        return cloned;
+    });
+}
 function findClosingToken(tokens, startIndex, type) {
     let depth = 0;
     for (let i = startIndex; i < tokens.length; i++) {
@@ -624,6 +695,17 @@ function inlineTokensToTiptap(tokens) {
         else if (token.type === 'softbreak') {
             nodes.push({ type: 'text', text: ' ' });
         }
+        else if (token.type === 'footnote_ref') {
+            // `[^N]` inline reference. Carry the author-written label verbatim so
+            // mnemonic labels (`[^sapolsky2017]`) survive round-trip. Display
+            // numbering is recomputed by the renderer.
+            // adr: adr/footnote-system.md
+            const label = token.meta?.label || String(token.meta?.id ?? '');
+            nodes.push({
+                type: 'footnoteReference',
+                attrs: { label },
+            });
+        }
     }
     return nodes;
 }

package/dist/server/markdown-serialize.js CHANGED Viewed

@@ -105,9 +105,11 @@ function collectBlockIds(doc) {
         'heading', 'paragraph', 'bulletList', 'orderedList', 'taskList',
         'listItem', 'taskItem', 'blockquote', 'codeBlock', 'horizontalRule',
         'table', 'image', 'tableRow', 'tableCell', 'tableHeader',
+        'footnoteSection', 'footnoteDefinition',
     ]);
     const containerTypes = new Set([
         'bulletList', 'orderedList', 'taskList', 'listItem', 'taskItem', 'blockquote',
+        'footnoteSection', 'footnoteDefinition',
     ]);
     function walk(nodes) {
         if (!nodes)
@@ -224,12 +226,84 @@ function revertPendingForSerialization(doc) {
     return { type: 'doc', content: walk(doc?.content || []) };
 }
 function nodesToMarkdown(nodes) {
-    let result = '';
+    // Constrained model: `footnoteSection` is always emitted last, regardless of
+    // its position in the tree. Authors / agents / editor drag operations may
+    // place it anywhere; the serializer normalizes. Parse accepts flexibly;
+    // serialize produces strictly. First save of any non-canonical file becomes
+    // the one-time migration.
+    //
+    // Trailing-empty-paragraph stripping: TipTap inserts an empty paragraph at
+    // end-of-doc as a cursor-landing artifact. It serializes to a stray
+    // `<!-- -->` marker — visual cruft with no semantic value, and the next
+    // load just re-creates the cursor-landing paragraph anyway. Drop trailing
+    // empty paragraphs unconditionally (whether or not a footnoteSection is
+    // present): they're editor state, not on-disk content.
+    //
+    // Empty paragraphs in the MIDDLE of the doc are preserved — those are
+    // authored blank lines between sections and carry intent. Only the trailing
+    // run of empties at end-of-body gets stripped.
+    //
+    // adr: adr/footnote-system.md
+    let deferredSection = null;
+    const body = [];
     for (const node of nodes) {
+        if (node.type === 'footnoteSection') {
+            deferredSection = node;
+            continue;
+        }
+        body.push(node);
+    }
+    while (body.length > 0) {
+        const last = body[body.length - 1];
+        if (last.type === 'paragraph' && (!last.content || last.content.length === 0)) {
+            body.pop();
+        }
+        else {
+            break;
+        }
+    }
+    let result = '';
+    for (const node of body) {
         result += nodeToMarkdown(node, '');
     }
+    if (deferredSection) {
+        result += footnoteSectionToMarkdown(deferredSection);
+    }
     return result;
 }
+/**
+ * Serialize the footnoteSection block. Each definition emits as
+ * `[^label]: first-paragraph-content` with continuation paragraphs indented
+ * 4 spaces (Pandoc continuation convention). Empty section emits nothing.
+ *
+ * Definitions with no content still emit a `[^label]:` line so the reference
+ * doesn't dangle on round-trip.
+ *
+ * adr: adr/footnote-system.md
+ */
+function footnoteSectionToMarkdown(section) {
+    const definitions = (section.content || []).filter((d) => d.type === 'footnoteDefinition');
+    if (definitions.length === 0)
+        return '';
+    const lines = [];
+    for (const def of definitions) {
+        const label = def.attrs?.label || '';
+        const paragraphs = (def.content || []).filter((c) => c.type === 'paragraph');
+        if (paragraphs.length === 0) {
+            lines.push(`[^${label}]: `);
+            continue;
+        }
+        const firstText = inlineToMarkdown(paragraphs[0].content || []);
+        lines.push(`[^${label}]: ${firstText}`);
+        // Continuation paragraphs: 4-space indent per Pandoc convention.
+        for (let i = 1; i < paragraphs.length; i++) {
+            const text = inlineToMarkdown(paragraphs[i].content || []);
+            lines.push('');
+            lines.push(`    ${text}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
 function nodeToMarkdown(node, indent) {
     switch (node.type) {
         case 'heading': {
@@ -407,6 +481,17 @@ export function inlineToMarkdown(nodes) {
             result += '<br>';
             continue;
         }
+        if (node.type === 'footnoteReference') {
+            // Close any open marks so `[^N]` lands at the prose level, not inside
+            // a bold/italic span. Footnote references are visually distinct chips;
+            // wrapping them in bold or italic doesn't make sense.
+            // adr: adr/footnote-system.md
+            result += closeAllMarks(openMarks);
+            openMarks = [];
+            const label = node.attrs?.label || '';
+            result += `[^${label}]`;
+            continue;
+        }
         if (node.type !== 'text')
             continue;
         const targetMarks = (node.marks || [])

package/dist/server/mcp.js CHANGED Viewed

@@ -13,7 +13,7 @@ import { getDataDir, ensureDataDir, resolveDocPath, generateNodeId, atomicWriteF
 import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus, getNodesByIds, findNodesByIds, getMetadata, setMetadata, mergeMetadataUpdates, applyChanges, applyTextEdits, updateDocument, save, markAllNodesAsPending, setAgentLock, setAgentLockActive, updatePendingCacheForActiveDoc, populateDocumentFile, applyChangesToFile, applyTextEditsToFile, getDocId, getFilePath, extractText, countPending, addDocTag, removeDocTag, getCachedDocument, invalidateDocCache, isAutoAcceptActive, removePendingCacheEntry, getExternalMtimeDrift, reloadActiveDocFromDisk, getCanonical, cloneWithPendingReverted, bumpDocVersion, } from './state.js';
 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, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions } from './documents.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 { logger, generateRequestId, withRequestId } from './logger.js';
 import { broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastTitleChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
@@ -116,6 +116,35 @@ function resolveDocTarget(docId) {
         lastModified: statSync(filePath).mtime,
     };
 }
+/**
+ * Override the `autoAccept` field in a snapshot's frontmatter without
+ * reparsing the body. Used by `restore_version` to preserve the CURRENT
+ * user toggle (a per-doc UI preference) across a content-restore. Editing
+ * the frontmatter line directly avoids a full parse + reserialize, which
+ * would re-run the matcher and risk minor body-shape drift for what's
+ * supposed to be an exact content restore.
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+function applyAutoAcceptOverride(snapshotMarkdown, currentAutoAccept) {
+    const fmMatch = snapshotMarkdown.match(/^---\n(.+?)\n---\n/s);
+    if (!fmMatch)
+        return snapshotMarkdown; // no frontmatter to update
+    try {
+        const fm = JSON.parse(fmMatch[1]);
+        if (currentAutoAccept) {
+            fm.autoAccept = true;
+        }
+        else {
+            delete fm.autoAccept;
+        }
+        const newFmLine = JSON.stringify(fm);
+        return snapshotMarkdown.replace(/^---\n.+?\n---\n/s, `---\n${newFmLine}\n---\n`);
+    }
+    catch {
+        return snapshotMarkdown; // malformed frontmatter — leave alone
+    }
+}
 /** Human-friendly relative time for ISO timestamps. */
 function relativeTime(iso) {
     const then = new Date(iso).getTime();
@@ -385,8 +414,9 @@ export const TOOL_REGISTRY = [
             empty: z.boolean().optional().describe('ONLY for content_type template docs (tweets, articles) that start blank. Skips the spinner and switches immediately. Do NOT set this for content documents — use the two-step flow (create_document → populate_document) instead.'),
             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.'),
         },
-        handler: async ({ title, path, workspace, container, empty, content_type, url }) => {
+        handler: async ({ title, path, workspace, container, empty, content_type, url, afterId }) => {
             // 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").` }] };
@@ -428,7 +458,10 @@ export const TOOL_REGISTRY = [
                     }
                     let wsInfo = '';
                     if (wsTarget) {
-                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                        // Resolve afterId: it may be a docId (8-char hex) or containerId.
+                        // filenameByDocId resolves docId→filename; if null, treat as containerId.
+                        const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
+                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
                         wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                     }
                     const newDocId = getDocId();
@@ -449,7 +482,8 @@ export const TOOL_REGISTRY = [
                 const result = createDocumentFile(title, path, typeMeta);
                 let wsInfo = '';
                 if (wsTarget) {
-                    addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                    const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
+                    addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
                     wsInfo = ` → workspace "${workspace}"${container ? ` / ${container}` : ''}`;
                 }
                 // Broadcast spinner keyed by filename so populate_document can clear exactly
@@ -557,6 +591,7 @@ export const TOOL_REGISTRY = [
                 container: z.string().optional().describe('Container name within the workspace (e.g. "Chapters"). Requires workspace.'),
                 url: z.string().optional().describe('Tweet URL — REQUIRED for content_type "reply" or "quote".'),
                 path: z.string().optional().describe('Absolute file path to create the document at. If omitted, creates in ~/.openwriter/.'),
+                afterId: z.string().optional().describe('Place the new doc immediately after this docId or containerId inside its parent. Omit to append to the bottom (default, ascending-order convention). Requires workspace.'),
             })).min(1).describe('List of documents to declare (minimum 1).'),
         },
         handler: async ({ writes }) => {
@@ -583,7 +618,8 @@ export const TOOL_REGISTRY = [
                     const typeMeta = resolveTypeMeta(w.content_type, w.url);
                     const result = createDocumentFile(w.title, w.path, typeMeta);
                     if (wsTarget) {
-                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title);
+                        const afterRef = w.afterId ? (filenameByDocId(w.afterId) ?? w.afterId) : null;
+                        addDoc(wsTarget.wsFilename, wsTarget.containerId, result.filename, result.title, afterRef);
                     }
                     broadcastWritingStarted(w.title, wsTarget, result.filename);
                     broadcastedKeys.push(result.filename);
@@ -769,7 +805,7 @@ export const TOOL_REGISTRY = [
         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('One-sentence "what this doc is about" — ≤150 chars recommended.'),
+                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.'),
@@ -1061,9 +1097,13 @@ export const TOOL_REGISTRY = [
             workspaceFile: z.string().describe('Workspace manifest filename'),
             name: z.string().describe('Container name (e.g. "Chapters", "Research")'),
             parentContainerId: z.string().optional().describe('Parent container ID for nesting (null = root level)'),
+            afterId: z.string().optional().describe('Place the new container 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).'),
         },
-        handler: async ({ workspaceFile, name, parentContainerId }) => {
-            const result = addContainerToWorkspace(workspaceFile, parentContainerId ?? null, name);
+        handler: async ({ workspaceFile, name, parentContainerId, afterId }) => {
+            // Resolve afterId: may be docId (8-char hex) or containerId. filenameByDocId
+            // resolves docId→filename; if null, treat as containerId.
+            const afterRef = afterId ? (filenameByDocId(afterId) ?? afterId) : null;
+            const result = addContainerToWorkspace(workspaceFile, parentContainerId ?? null, name, afterRef);
             broadcastWorkspacesChanged();
             return { content: [{ type: 'text', text: `Created container "${name}" (id:${result.containerId})` }] };
         },
@@ -1455,9 +1495,19 @@ export const TOOL_REGISTRY = [
             }
             catch { /* best effort */ }
             // Read the target snapshot's content
-            const snapshotMarkdown = getVersionContent(target.docId, timestamp);
-            if (!snapshotMarkdown)
+            const rawSnapshot = getVersionContent(target.docId, timestamp);
+            if (!rawSnapshot)
                 return { content: [{ type: 'text', text: `Error: Version ${timestamp} not found.` }] };
+            // Preserve the CURRENT autoAccept setting rather than rolling it back
+            // to the snapshot-era value. `autoAccept` is a per-doc user preference
+            // (toggled in the sidebar) that governs how FUTURE writes behave —
+            // it's not document content. Without this, a user who toggled
+            // autoAccept off to review incoming changes would silently lose that
+            // preference when the agent calls restore_version, and the next
+            // write_to_pad would auto-apply instead of arriving as pending.
+            // adr: adr/pending-overlay-model.md
+            const currentAutoAccept = target.metadata?.autoAccept === true;
+            const snapshotMarkdown = applyAutoAcceptOverride(rawSnapshot, currentAutoAccept);
             // Write the snapshot directly to disk — this becomes the new canonical.
             // The pending overlay sidecar is unchanged; on reload, the matcher
             // re-pairs nodeIds and pending decorations re-attach where possible.

package/dist/server/node-blocks.js CHANGED Viewed

@@ -36,6 +36,8 @@ const CONTAINER_TYPES = new Set([
     'tableRow',
     'tableCell',
     'tableHeader',
+    'footnoteSection',
+    'footnoteDefinition',
 ]);
 function walkNodes(nodes, blocks, parentPosition) {
     let ordinalInParent = 0;
@@ -105,6 +107,40 @@ function walkNodes(nodes, blocks, parentPosition) {
             });
             walkNodes(node.content || [], blocks, bqPosition);
         }
+        else if (node.type === 'footnoteSection') {
+            // Container holding all `footnoteDefinition`s at end-of-doc. Treated
+            // like a blockquote: container fingerprint is content-empty, identity
+            // travels through the matcher's structural rules. The serializer
+            // enforces end-of-doc position regardless of where it appears in the
+            // tree, so position-stability is guaranteed at the boundary.
+            // adr: adr/footnote-system.md
+            const sectionPosition = blocks.length;
+            blocks.push({
+                position: sectionPosition,
+                type: 'footnoteSection',
+                text: '',
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, sectionPosition);
+        }
+        else if (node.type === 'footnoteDefinition') {
+            // Container for one footnote's content (typically a single paragraph,
+            // occasionally multiple). The label attr round-trips with the node;
+            // the matcher fingerprints by content + slot like any container.
+            // adr: adr/footnote-system.md
+            const defPosition = blocks.length;
+            blocks.push({
+                position: defPosition,
+                type: 'footnoteDefinition',
+                text: firstParagraphText(node.content || []),
+                parentPosition,
+                ordinalInParent: ordinalInParent++,
+                id: node.attrs?.id,
+            });
+            walkNodes(node.content || [], blocks, defPosition);
+        }
         else if (node.type === 'codeBlock') {
             const text = extractInlineText(node.content || []);
             blocks.push({
@@ -236,6 +272,8 @@ export function applyIdsToTiptap(doc, pinnedByPosition) {
                 node.type === 'horizontalRule' ||
                 node.type === 'table' ||
                 node.type === 'image' ||
+                node.type === 'footnoteSection' ||
+                node.type === 'footnoteDefinition' ||
                 CONTAINER_TYPES.has(node.type);
             if (isBlock) {
                 const id = pinnedByPosition.get(position);
@@ -261,7 +299,9 @@ export function applyIdsToTiptap(doc, pinnedByPosition) {
                     node.type === 'taskList' ||
                     node.type === 'listItem' ||
                     node.type === 'taskItem' ||
-                    node.type === 'blockquote';
+                    node.type === 'blockquote' ||
+                    node.type === 'footnoteSection' ||
+                    node.type === 'footnoteDefinition';
                 if (isContainer && node.content)
                     walk(node.content);
             }

package/dist/server/state.js CHANGED Viewed

@@ -805,17 +805,18 @@ 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();
     // Bump docVersion so the writeToDisk no-op gate (which compares
@@ -826,10 +827,6 @@ export function updateDocument(doc) {
     // state.document MUST bump docVersion. applyChanges does the same.
     // adr: adr/pending-overlay-model.md
     bumpDocVersion();
-    // 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');
-    }
 }
 /**
  * Transfer pending attrs from source doc to target doc by matching node IDs.
@@ -1922,6 +1919,16 @@ 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

package/dist/server/workspace-tree.js CHANGED Viewed

@@ -89,10 +89,13 @@ export function addDocToContainer(root, containerId, file, title, afterIdentifie
         }
     }
     else {
-        target.unshift(doc);
+        // Default: append to the bottom of the parent's child list. This matches
+        // the ascending-order convention (newest at bottom, oldest at top). Callers
+        // that want top-insertion must pass an explicit afterIdentifier.
+        target.push(doc);
     }
 }
-export function addContainer(root, parentContainerId, name) {
+export function addContainer(root, parentContainerId, name, afterIdentifier) {
     const depth = getContainerDepth(root, parentContainerId);
     if (depth >= MAX_DEPTH) {
         throw new Error(`Maximum nesting depth (${MAX_DEPTH}) reached`);
@@ -106,7 +109,19 @@ export function addContainer(root, parentContainerId, name) {
         name,
         items: [],
     };
-    target.unshift(container);
+    if (afterIdentifier) {
+        const afterIdx = target.findIndex((n) => (n.type === 'doc' && n.file === afterIdentifier) || (n.type === 'container' && n.id === afterIdentifier));
+        if (afterIdx === -1) {
+            target.push(container);
+        }
+        else {
+            target.splice(afterIdx + 1, 0, container);
+        }
+    }
+    else {
+        // Default: append to the bottom (ascending-order convention).
+        target.push(container);
+    }
     return container;
 }
 // ============================================================================