openwriter 0.40.0 → 0.40.1

package/skill/docs/enrichment.md

@@ -1,180 +0,0 @@
-# Enrichment Dispatch — Detailed Procedure
-
-OpenWriter's frontmatter enrichment is dispatched via the
-`openwriter-enrichment-minion` custom subagent. SKILL.md firm rule 5
-covers the common case (single minion, small/medium batch). This doc
-handles the **large-corpus case** where one minion isn't enough — and
-the parallel-dispatch pattern that scales it.
-
-## When to chunk
-
-| Dirty docs (N) | Dispatch shape | Wall time |
-|---|---|---|
-| 1–30 | Single minion. Default prompt. | ~10–45 seconds |
-| 31+  | Chunked parallel minions. | ~30 seconds (regardless of N) |
-
-The minion's turn budget (`maxTurns: 500` in its frontmatter) can handle
-~50 docs serially, but at that size the wall-clock cost (3+ minutes)
-becomes visible to the user. Parallel dispatch keeps total wall time
-under ~30 seconds for any corpus size up to a few hundred docs.
-
-## Step-by-step (large corpus)
-
-### 1. Inventory the work
-
-```
-mcp__openwriter__list_dirty_docs()
-```
-
-Returns every dirty doc across all workspaces with `docId`, `title`,
-`workspaceFile`, `reason`. If `total ≤ 30`, stop — single minion path
-(firm rule 5) is correct. If `total > 30`, continue.
-
-### 2. Chunk the work
-
-v0.19.0 simplified the minion to logline-only — workspace vocab is no
-longer relevant (the `domain` field that used it was dropped). You can
-group chunks however you want; workspace-grouping is no longer required.
-Practical defaults:
-
-**Target: 12–15 docs per chunk.**
-
-- **Very large dirty list (>100 docs):** split into chunks of ~15.
-- **Workspace-grouped is still fine** if it makes the dispatch prompts
-  easier to read, but it's no longer a performance concern.
-
-You'll typically land on 4–10 chunks. Don't exceed ~10 parallel —
-Anthropic per-account rate limits kick in beyond that and you get
-serialized anyway.
-
-### 3. Dispatch all chunks in one message
-
-Send **every chunk in a single assistant message** with multiple `Agent`
-tool uses. This is the only way they actually run in parallel —
-sequential `Agent` calls block each other.
-
-Use `run_in_background: true` so you can keep talking to the user while
-the minions work. You'll receive a `<task-notification>` per chunk as
-each one finishes.
-
-### 4. Prompt format (explicit-list mode)
-
-The minion's agent file (`~/.claude/agents/openwriter-enrichment-minion.md`)
-supports an explicit-list mode — pass docIds in the prompt and the minion
-skips `list_dirty_docs` and uses your list directly.
-
-Example prompt for one chunk (v0.19.0 — logline-only):
-
-```
-Enrich these specific openwriter docs:
-
-- a1b2c3d4 — Onboarding Email Sequence
-- e5f6a7b8 — Why We Sleep — Ch 2 Notes
-- 9z8y7x6w — Product Launch Checklist
-- 1q2w3e4r — Ch 3 — Beats
-- 5t6y7u8i — Ch 4 — Draft
-
-For each: read_pad to get the body, write a logline ≤150 chars, then
-bulk mark_enriched at the end with { docId, logline } per entry.
-```
-
-Keep prompts short. The minion already knows the procedure from its
-agent file — you're just handing it the work list. The minion's tool
-allowlist (v0.19.0) is `list_dirty_docs`, `read_pad`, `mark_enriched`
-— `get_workspace_structure` is no longer needed because there's no
-workspace-vocab dependency.
-
-### 5. Surface to the user (large-batch phrasing)
-
-Before dispatching, tell the user what's happening. Firm rule 5's
-"large batch" tier (N > 20) requires a heads-up. Example:
-
-> OpenWriter detected 73 docs that haven't been summarized yet —
-> first-time setup. Refreshing them in 6 parallel batches in the
-> background; this'll take ~30 seconds and a few cents of Haiku usage.
-
-Then dispatch. Stay silent as notifications come in unless one fails.
-When all are done, report once:
-
-> Enrichment complete: 73 docs across 8 workspaces. Cost: ~$0.15.
-
-### 6. Verify completion
-
-After every chunk has notified, call `list_dirty_docs` once more. If
-`total > 0`, some docs slipped — usually because a minion errored on a
-specific doc or a doc was modified mid-enrichment. Re-dispatch a single
-minion for the stragglers; don't redo the whole batch.
-
-## Why this shape
-
-**Why parallel, not serial single-minion at maxTurns: 500?**
-A single minion processing 100 docs takes 3+ minutes wall time. The
-user sits in silence. Six parallel minions of ~15 docs each finish in
-~30 seconds. Same total token cost — much better UX.
-
-**Why explicit docId list instead of letting each minion call `list_dirty_docs`?**
-Race conditions. If you spawn 6 minions and they all call
-`list_dirty_docs`, they all see the same 100 dirty docs and try to
-enrich the same docs in parallel. Most enrichments succeed (last write
-wins on the frontmatter), but it's wasteful and the per-doc baselines
-get computed multiple times. Explicit lists partition the work cleanly.
-
-**Why 12–15 docs per chunk and not 50?**
-Two reasons: (1) turn budget — each doc costs ~1 turn (one `read_pad`
-call); ~15 docs leaves headroom inside the 500-turn ceiling even with
-retries. (2) failure isolation — if one minion's batch errors, you lose
-15 docs of work, not 50.
-
-**Why dispatch in one message, not sequential Agent calls?**
-Sequential `Agent` calls block each other. Only multiple `Agent` tool
-uses in the **same assistant message** run truly in parallel.
-
-## Cost ballpark
-
-Haiku token cost per doc: ~1.5K–3K in v0.19.0 (one read_pad + one
-logline synthesis + share of mark_enriched). Roughly half what it cost
-under v0.16's five-field schema.
-
-| Corpus size | Approx cost (v0.19.0) |
-|---|---|
-| 30 docs   | ~$0.02 |
-| 100 docs  | ~$0.08 |
-| 500 docs  | ~$0.40 |
-
-Compare to ~$5.00 per doc if you used the general-purpose subagent with
-full MCP tool registry (~50K token overhead per spawn). The custom
-minion's tool allowlist (3 tools in v0.19.0: `list_dirty_docs`,
-`read_pad`, `mark_enriched`) is what makes the math work.
-
-## Failure modes
-
-- **Minion returns with no `mark_enriched` call** — almost always means
-  it hit the turn ceiling. Confirm its agent file has `maxTurns: 500`
-  in the frontmatter, then reduce chunk size to ~10 docs and re-dispatch
-  that chunk.
-- **Minion reports "No enrichment work pending"** — its assigned docs
-  got enriched by a sibling minion first (race condition from
-  `list_dirty_docs` mode, not explicit-list mode). Benign; the other
-  minion's work landed correctly.
-- **`<task-notification>` reports an error** — re-dispatch just that
-  one chunk. Don't restart the whole batch.
-- **Logline cap violations** — the minion's agent file enforces a
-  150-char hard cap. If you spot longer loglines on disk after the
-  fact, it's a minion regression — flag for agent-file revision rather
-  than re-enriching.
-
-## When NOT to chunk
-
-If `list_dirty_docs` returns ≤30 docs, dispatch a single minion with
-the default prompt:
-
-```
-Agent({
-  subagent_type: "openwriter-enrichment-minion",
-  description: "Enrich stale openwriter docs",
-  prompt: "Enrich all currently stale openwriter docs."
-})
-```
-
-The minion calls `list_dirty_docs` itself, processes everything in one
-pass, and reports back. Chunking ≤30 docs is overhead, not gain.

package/skill/docs/footnotes.md

@@ -1,178 +0,0 @@
-# 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
-The body repairs itself during deep sleep[^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

package/skill/docs/setup.md

@@ -1,62 +0,0 @@
-# OpenWriter Setup
-
-## Quick install
-
-```bash
-npx openwriter setup
-```
-
-This installs openwriter globally, configures the MCP server for Claude Code, and copies this skill — all in one step. After it finishes, the user just needs to restart their Claude Code session.
-
-## Claude Code
-
-**Fallback (if the command above fails):** Do it manually:
-
-```bash
-npm install -g openwriter
-claude mcp add -s user openwriter -- openwriter --no-open
-```
-
-If `claude mcp add` can't run (e.g. nested session error), edit `~/.claude.json` directly. Add `openwriter` as the **first entry** in `mcpServers`:
-
-```json
-{
-  "mcpServers": {
-    "openwriter": {
-      "command": "openwriter",
-      "args": ["--no-open"]
-    }
-  }
-}
-```
-
-## OpenCode
-
-Same binary, different config format. Add to `opencode.json` at the project root:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "openwriter": {
-      "type": "local",
-      "command": ["openwriter", "--no-open"],
-      "enabled": true
-    }
-  }
-}
-```
-
-OpenCode auto-discovers the skill at `~/.claude/skills/openwriter/SKILL.md` — no copy needed.
-
-The enrichment minion is NOT auto-discovered. Place it at one of:
-
-- `~/.config/opencode/agents/openwriter-enrichment-minion.md` (global, all projects)
-- `.opencode/agents/openwriter-enrichment-minion.md` (this project only, repo root)
-
-Source file lives at `~/.claude/skills/openwriter/agents/openwriter-enrichment-minion.md` after `npx openwriter setup`. Copy it to one of the paths above and restart OpenCode. The filename becomes the agent name OpenCode resolves when the parent dispatches it.
-
-## After setup
-
-1. Restart your Claude Code or OpenCode session (MCP servers load on startup)
-2. Open http://localhost:5050 in your browser

package/skill/docs/welcome.md

@@ -1,21 +0,0 @@
-# Welcome to OpenWriter
-
-What you're looking at right now is how we collaborate. These green highlights are my proposed changes — I write, you review. Use the review panel on the right to navigate (j/k), accept (a), or reject (r) each change. Try it now.
-
-## Create Documents
-
-Hit the **+** button in the sidebar to create different document types: blog posts, newsletters, tweets, LinkedIn posts, and articles. Each type has its own compose view tailored to that format. Or just ask me to write something and I'll create the right doc type for you.
-
-## Workspaces
-
-Organize your documents into workspaces with containers and tags. This is especially powerful for book writing — each chapter is a document, grouped into sections as containers. I can see your full workspace structure and work across multiple docs.
-
-## Plugins
-
-**Author's Voice** — Feed me your writing samples and I'll write in your voice. Not an approximation — I pull your actual patterns, cadence, and word choices from your corpus.
-
-**Publish** — Send newsletters to your subscriber list, post to X/Twitter, publish blog posts to GitHub, and schedule content. All from inside the editor, no copy-pasting to other platforms.
-
-## What's Next
-
-Ask me to write something. A blog post, a tweet thread, a newsletter — whatever you're working on. I'll create a doc for it and we'll iterate together.