openwriter 0.16.0 → 0.18.0

package/dist/server/workspaces.js

@@ -210,9 +210,9 @@ export function reorderDoc(wsFile, file, afterFile) {
 // ============================================================================
 // CONTAINER OPERATIONS
 // ============================================================================
-export function addContainerToWorkspace(wsFile, parentContainerId, name) {
+export function addContainerToWorkspace(wsFile, parentContainerId, name, afterIdentifier) {
     const ws = getWorkspace(wsFile);
-    const container = addContainerToTree(ws.root, parentContainerId, name);
+    const container = addContainerToTree(ws.root, parentContainerId, name, afterIdentifier ?? null);
     writeWorkspace(wsFile, ws);
     return { workspace: ws, containerId: container.id };
 }

package/package.json

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

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.7.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

@@ -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

package/skill/docs/footnotes.md

@@ -0,0 +1,178 @@
+# Footnotes — Author Guide for Agents
+
+OpenWriter supports CommonMark / Pandoc footnote syntax for citation-heavy
+long-form writing. The editor renders inline references as superscript
+chips and corrals definitions into an end-of-doc "Footnotes" section.
+
+This doc explains how to write footnotes via MCP tools and what to expect
+on disk and in the editor.
+
+## The syntax (Pandoc / CommonMark)
+
+Two parts:
+
+- **Reference** (inline): `text[^N]` — appears in the prose
+- **Definition** (block): `[^N]: footnote text` — appears at end of doc
+
+Labels can be numeric or mnemonic:
+
+```markdown
+Humans run fixed action patterns[^1] too.
+
+Per Sapolsky[^sapolsky2017], stress responses follow a pattern.
+
+[^1]: Eibl-Eibesfeldt 1973, replicated and extended by Galati et al. 2003.
+
+[^sapolsky2017]: Sapolsky, R. (2017). *Behave*. Penguin Press.
+```
+
+The author label (`1` or `sapolsky2017`) is what pairs reference to
+definition. **Display numbering is automatic** — the editor's CSS counter
+shows sequential `[1] [2] [3]` regardless of label. Mnemonic labels stay
+on disk for human-readable file diffs.
+
+## How to write footnotes from MCP
+
+Just include the syntax in your markdown content — no special tool needed.
+
+### populate_document (initial draft)
+
+```ts
+populate_document({
+  docId: "abc12345",
+  content: `# Chapter 1
+
+Theory of mind develops late[^1] in non-human primates.
+
+[^1]: Premack & Woodruff (1978), Behavioral and Brain Sciences 1: 515–526.
+`
+})
+```
+
+The parser handles `[^1]` references and `[^1]: ...` definitions. The
+editor renders the reference as a superscript chip and the definition
+inside an end-of-doc "Footnotes" section.
+
+### write_to_pad (adding to existing doc)
+
+To add a new footnote to existing prose, you have two paths.
+
+**Append a new reference + definition together** (recommended):
+
+```ts
+// Step 1: rewrite the paragraph to add the reference
+write_to_pad({
+  docId: "abc12345",
+  changes: [
+    {
+      operation: "rewrite",
+      nodeId: "para_id",
+      content: "The same sentence now with a new claim[^2]."
+    }
+  ]
+})
+
+// Step 2: append the definition. If the doc already has a footnoteSection,
+// you can insert the definition inside it via afterNodeId pointing at the
+// last definition. If the doc has no footnotes yet, the parser auto-creates
+// the section when it sees `[^N]: ...` at the end of the markdown body.
+```
+
+**Simpler: just include both the reference and the definition in one
+write_to_pad call**:
+
+```ts
+write_to_pad({
+  docId: "abc12345",
+  changes: [
+    {
+      operation: "rewrite",
+      nodeId: "para_id",
+      content: "Sentence with new claim[^2]."
+    },
+    {
+      operation: "insert",
+      afterNodeId: "end",
+      content: "[^2]: Smith et al. (2020), Nature 580: 142–148."
+    }
+  ]
+})
+```
+
+The serializer normalizes definitions to the end-of-doc `footnoteSection`
+regardless of where they're inserted in the tree.
+
+## What you see in `read_pad`
+
+```
+title: My Chapter
+id: abc12345
+words: 423
+pending: 0
+---
+[h1:aa0001] Chapter 1
+[p:bb0002] Theory of mind develops late[^1] in non-human primates.
+[fnsec:cc0003]
+  [fndef:dd0004] [^1]: Premack & Woodruff (1978), Behavioral and Brain Sciences 1: 515–526.
+```
+
+The `[^N]` in the body is the inline reference. `[fnsec:...]` is the
+end-of-doc section. `[fndef:...]` is each definition.
+
+## Per-doc scope — important
+
+**Footnote labels are local to each doc.** Chapter 3's `[^1]` does not
+refer to Chapter 4's `[^1]`. Each chapter is its own `.md` file with its
+own numbering. Cross-chapter references are not supported at the editor
+level (a future book-export pipeline will handle global numbering at
+typeset time).
+
+If the author writes "see Ch 1 note 4" they're writing prose, not a
+cross-doc footnote link.
+
+## Multi-paragraph definitions
+
+Pandoc allows multi-paragraph footnotes via 4-space-indented continuation:
+
+```markdown
+[^1]: First paragraph of the definition.
+
+    Continuation paragraph, indented 4 spaces.
+
+    Another continuation.
+```
+
+The editor preserves the multi-paragraph structure inside the definition.
+Use this for footnotes that need substantial explanation (lengthy
+methodology notes, multi-source citations, etc.).
+
+## What's NOT supported (yet)
+
+- **Cross-doc footnote references.** Each doc has its own numbering.
+- **Bibliography auto-generation.** Authors manage citation text inline.
+  Zotero / Mendeley / BibTeX integration is a future enhancement.
+- **DOI auto-resolution.** Footnote text is plain — paste a DOI manually.
+- **Per-page footnotes (Phase 3).** The editor uses end-of-doc placement;
+  per-page placement is a print-layout concern handled at book-export
+  time, not in the editor.
+
+## When to use footnotes vs inline parentheticals
+
+Use footnotes when:
+- The citation count exceeds ~3 per ~500 words (inline parentheticals
+  start visibly disrupting the prose at that density)
+- The audience expects an academic register (popular nonfiction in the
+  Sapolsky / Wrangham / Pinker lineage)
+- The work targets book-class output (cumulative citation load at book
+  scale destroys readability under inline parentheticals)
+
+Use inline parentheticals when:
+- Citations are sparse (<1 per 500 words) and short
+- The author prefers a journalistic register
+- The work is short-form (tweet thread, blog post) where there's no
+  end-of-doc section to defer to
+
+## Reference docs (for the editor maintainers, not agents)
+
+- `docs/footnotes.md` (in the openwriter repo): full architecture
+- `adr/footnote-system.md`: load-bearing invariants + decision log