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

openwriter 0.16.0 → 0.17.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 (16) 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 +42 -3
package/dist/server/node-blocks.js +41 -1
package/dist/server/state.js +22 -15
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

@@ -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();
@@ -769,7 +798,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.'),
@@ -1455,9 +1484,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/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,7 @@
     "gray-matter": "^4.0.3",
     "lowlight": "^3.3.0",
     "markdown-it": "^14.1.1",
+    "markdown-it-footnote": "^4.0.0",
     "markdown-it-ins": "^4.0.0",
     "markdown-it-mark": "^4.0.0",
     "markdown-it-sub": "^2.0.0",

package/skill/SKILL.md CHANGED Viewed

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.7.5"
+  version: "0.7.6"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -303,6 +303,18 @@ When creating **two or more documents together** — a tweet thread saved as sep
 - `reply` / `quote` types still require `url`
 - For a **single** document, use `create_document` — don't reach for `declare_writes` just to wrap one entry
+### Citations & footnotes
+Long-form writing (especially academic-adjacent nonfiction) uses CommonMark / Pandoc footnote syntax:
+- **Reference** (inline in prose): `text[^1]` — renders as a superscript chip
+- **Definition** (anywhere in the markdown body): `[^1]: footnote text` — automatically corralled into a "Footnotes" section at end-of-doc on save
+- **Mnemonic labels** allowed: `[^sapolsky2017]` survives round-trip on disk; the editor shows auto-sequential display numbers regardless
+Just include the syntax in `populate_document` content or `write_to_pad` content — no special tool needed. The parser handles the tokenization, the editor handles the rendering, the serializer enforces the constrained end-of-doc shape.
+**Scope is per-doc.** Each chapter has its own `[^1]` … `[^N]` numbering; cross-doc references aren't supported at the editor level. Full guide → `docs/footnotes.md`.
 ## Companion Skills (optional)
 For voice-matched drafting without a custom Author's Voice profile, install the **voice-presets** skill — 5 frames (authority, provocateur, logical, storyteller, business). For an AI-detection pass on output, install **anti-ai**. Both are optional and ship separately from this skill.

package/skill/agents/openwriter-enrichment-minion.md CHANGED Viewed

@@ -27,16 +27,9 @@ questions. The main agent dispatched you because the work needs doing.
 Five frontmatter fields that capture each doc's identity in 50–200 tokens:
-- **logline** — one sentence, plain English. "What is this doc about?"
-  Captures the *what*, not the *how*. No jargon the reader won't recognize.
-  No promotional language. Test: a reader who has never seen this doc reads
-  the logline and knows whether to open it.
-  **Length: 140-character target, 150-character HARD CAP.** Count characters
-  literally before submitting. If your draft is over 150, rewrite it shorter
-  — don't submit and hope. Cutting the introductory clause is usually the
-  fastest fix ("Master reference for human sexual dimorphism: T-gate
-  mechanism, dimorphic traits, contest selection." → drop "Master reference
-  for" if you need room).
+- **logline** — précis (non-fiction) or logline (fiction) summarizing the
+  content. Under 250 chars. No scaffolding — describe the content itself,
+  not the kind of doc it is.
 - **domain** — single classification string. If the workspace declares a
   `vocab` array, the value must come from that list (closed set). If no
   vocab, pick a short durable label (1–3 words, title-case). Stay consistent