openwriter 0.23.0 → 0.25.0

package/dist/server/ws.js

@@ -2,8 +2,8 @@
  * WebSocket handler: pushes NodeChanges to browser, receives doc updates + signals.
  */
 import { WebSocketServer, WebSocket } from 'ws';
-import { updateDocument, syncBrowserDocUpdate, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, debouncedSave, cancelDebouncedSave, onChanges, onIdRewrites, isAgentLocked, setAgentLockActive, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, onExternalWriteConflict, onDocumentReloaded, isAgentStub, unmarkAgentStub, } from './state.js';
-import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile } from './documents.js';
+import { updateDocument, syncBrowserDocUpdate, getDocument, getTitle, getFilePath, getDocId, getMetadata, setMetadata, save, debouncedSave, cancelDebouncedSave, onChanges, onIdRewrites, isAgentLocked, setAgentLockActive, getDocVersion, isVersionCurrent, getPendingDocInfo, updatePendingCacheForActiveDoc, stripPendingAttrs, saveDocToFile, stripPendingAttrsFromFile, onExternalWriteConflict, onDocumentReloaded, onAutoTitleApplied, isAgentStub, unmarkAgentStub, } from './state.js';
+import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile, listDocuments } from './documents.js';
 import { removeDocFromAllWorkspaces } from './workspaces.js';
 import { canonicalizeIdentifier } from './helpers.js';
 import { nodeTextPreview, diagLog } from './pending-overlay.js';
@@ -182,6 +182,18 @@ export function setupWebSocket(server) {
         }
         console.warn(`[WS] Broadcast external-write-conflict for ${filename}`);
     });
+    // Auto-title applied: the save() pipeline derived a title from body
+    // content because the doc was still on a default title. Rename the
+    // file on disk if it was a temp file, then broadcast so the sidebar
+    // and active editor reflect the new title without a page reload.
+    onAutoTitleApplied((newTitle) => {
+        const promoted = promoteTempFile(newTitle);
+        if (promoted) {
+            broadcastDocumentSwitched(getDocument(), getTitle(), promoted, getMetadata());
+        }
+        broadcastMetadataChanged(getMetadata());
+        broadcastDocumentsChanged();
+    });
     wss.on('connection', (ws) => {
         clients.add(ws);
         console.log(`[WS] Client connected (total: ${clients.size})`);
@@ -213,10 +225,13 @@ export function setupWebSocket(server) {
         }));
         // Seed the right-rail Activity tab with persisted history (newest-first).
         // The disk log is the source of truth; the client mirrors what we send.
+        // Backfilled before send so older entries (recorded before the writing-
+        // started path threaded an explicit disk filename) pick up a filename
+        // from the headline-title lookup and become clickable.
         // adr: adr/right-rail.md
         ws.send(JSON.stringify({
             type: 'activity-log',
-            entries: loadActivityTail(),
+            entries: backfillActivityFilenames(loadActivityTail()),
         }));
         // Rehydrate in-flight writing spinners across app refreshes
         const pendingWritesSnapshot = getPendingWritesSnapshot();
@@ -549,7 +564,26 @@ export function broadcastAgentStatus(connected) {
 let lastSyncStatus = null;
 const pendingWrites = new Map();
 const WRITING_TIMEOUT_MS = 60_000;
-export function broadcastWritingStarted(title, target, key) {
+export function broadcastWritingStarted(title, target, key, 
+/**
+ * Disk filename to record on the Activity-tab entry so the row links to the
+ * doc on click. Independent of `target.wsFilename` (which is the workspace
+ * anchor filename used for sidebar spinner positioning and is empty/absent
+ * for orphan docs and sidebar-action writes). Falls back to
+ * target?.wsFilename, then to `key` when it looks like a disk filename
+ * (create/declare paths already pass result.filename as the key).
+ * Filename is back-compat only — the client prefers docId.
+ * adr: adr/right-rail.md
+ */
+activityFilename, 
+/**
+ * Stable docId for the activity entry. Preferred over filename — the
+ * client resolves it to a current filename at click time, so renames
+ * don't break the link. Most callers can pass this from their result
+ * object; pass undefined if not yet known (sidebar-action passes the
+ * source doc's id here).
+ */
+activityDocId) {
     const writeKey = key || target?.wsFilename || `write:${Date.now()}:${Math.random().toString(36).slice(2, 8)}`;
     const existing = pendingWrites.get(writeKey);
     if (existing)
@@ -573,10 +607,13 @@ export function broadcastWritingStarted(title, target, key) {
     // Right-rail Activity: each agent write produces one entry, emitted at
     // start (target info is richest here, and the spinner-in-sidebar already
     // signals in-progress completion). adr: adr/right-rail.md
+    const wsFn = target?.wsFilename && target.wsFilename.length > 0 ? target.wsFilename : undefined;
+    const keyAsFilename = key && key.endsWith('.md') ? key : undefined;
     broadcastActivityEvent({
         kind: 'writing-started',
         headline: `Agent wrote in ${title || 'Untitled'}`,
-        filename: target?.wsFilename,
+        docId: activityDocId,
+        filename: activityFilename ?? wsFn ?? keyAsFilename,
     });
     return writeKey;
 }
@@ -658,12 +695,105 @@ export function broadcastActivityEvent(partial) {
  * adr: adr/right-rail.md
  */
 export function broadcastActivityLogSeed() {
-    const msg = JSON.stringify({ type: 'activity-log', entries: loadActivityTail() });
+    const msg = JSON.stringify({ type: 'activity-log', entries: backfillActivityFilenames(loadActivityTail()) });
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN)
             ws.send(msg);
     }
 }
+/**
+ * Patch activity entries before handing the seed to the client. The disk log
+ * stays append-only (we don't rewrite it); the patch only affects the
+ * in-flight payload.
+ *
+ * Three passes per entry:
+ *   1. If `filename` is set but `docId` isn't, look up docId from the current
+ *      document list (filename → docId) and stamp it on the entry.
+ *   2. If neither is set, parse the headline ("Agent wrote in <title>",
+ *      "Enrichment stamped <title>") and resolve via the title index.
+ *   3. If the entry has a docId (originally or via passes 1–2), refresh the
+ *      headline's title to the doc's *current* title. This fixes
+ *      "Agent wrote in Untitled" rows once the doc has earned a real title,
+ *      and keeps rename-stale headlines in sync. Headline is display-only —
+ *      the click still resolves via docId — so rewriting in the seed is safe.
+ *
+ * The client navigates by docId (resolving to the current filename at click
+ * time, so renames don't break the link), so backfilling docId is what makes
+ * historical entries clickable; the headline refresh is the polish on top.
+ *
+ * Entries whose original title was "Untitled" AND whose docId still can't be
+ * resolved stay un-resolved — no unique target. The client renders them dim,
+ * non-clickable, with a tooltip explaining why.
+ * adr: adr/right-rail.md
+ */
+function backfillActivityFilenames(entries) {
+    if (entries.length === 0)
+        return entries;
+    let titleToDoc = null;
+    let filenameToDocId = null;
+    let docIdToTitle = null;
+    try {
+        const docs = listDocuments();
+        titleToDoc = new Map();
+        filenameToDocId = new Map();
+        docIdToTitle = new Map();
+        for (const d of docs) {
+            if (d.docId) {
+                filenameToDocId.set(d.filename, d.docId);
+                if (d.title)
+                    docIdToTitle.set(d.docId, d.title);
+            }
+            if (d.title && !titleToDoc.has(d.title))
+                titleToDoc.set(d.title, { docId: d.docId, filename: d.filename });
+        }
+    }
+    catch {
+        return entries;
+    }
+    const HEADLINE_PREFIXES = ['Agent wrote in ', 'Enrichment stamped '];
+    const resolveTitle = (headline) => {
+        for (const prefix of HEADLINE_PREFIXES) {
+            if (headline.startsWith(prefix))
+                return headline.slice(prefix.length);
+        }
+        return null;
+    };
+    const rewriteHeadline = (headline, newTitle) => {
+        for (const prefix of HEADLINE_PREFIXES) {
+            if (headline.startsWith(prefix))
+                return prefix + newTitle;
+        }
+        return headline;
+    };
+    return entries.map((e) => {
+        let next = e;
+        // Pass 1 & 2 — fill in docId if missing.
+        if (!next.docId && (next.kind === 'writing-started' || next.kind === 'enrichment' || next.kind === 'backlinks-added')) {
+            if (next.filename) {
+                const docId = filenameToDocId.get(next.filename);
+                if (docId)
+                    next = { ...next, docId };
+            }
+            if (!next.docId) {
+                const title = resolveTitle(next.headline);
+                if (title && title !== 'Untitled') {
+                    const hit = titleToDoc.get(title);
+                    if (hit)
+                        next = { ...next, docId: hit.docId, filename: next.filename ?? hit.filename };
+                }
+            }
+        }
+        // Pass 3 — refresh headline title from current doc state when docId is known.
+        if (next.docId) {
+            const currentTitle = docIdToTitle.get(next.docId);
+            const oldTitle = resolveTitle(next.headline);
+            if (currentTitle && oldTitle !== null && oldTitle !== currentTitle) {
+                next = { ...next, headline: rewriteHeadline(next.headline, currentTitle) };
+            }
+        }
+        return next;
+    });
+}
 export function broadcastSyncStatus(status) {
     lastSyncStatus = status;
     const msg = JSON.stringify({ type: 'sync-status', ...status });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.23.0",
+  "version": "0.25.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",

package/skill/SKILL.md

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.11.2"
+  version: "0.15.0"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -43,7 +43,21 @@ You are a writing collaborator. You read documents and make edits **exclusively
    **If the subagent isn't installed** (older openwriter, or the user skipped install-skill): the Agent call returns `Agent type 'openwriter-enrichment-minion' not found`. Tell the user once: "OpenWriter has stale docs but the enrichment minion isn't installed yet — run `npx openwriter install-skill` and restart Claude Code." Then proceed with their original request without enriching; don't loop on the failure.
 
    **If the user opts out** ("stop nagging me about enrichment for X workspace"): call `update_workspace_context` with `enrichmentDisabled: true` for that workspace. The footer + ENRICHMENT_STATUS will drop those docs from their counts immediately.
-6. **Emit deep links whenever you cite a docId.** Any time you reference a specific document in chat — naming it, summarizing it, pointing the user at a beat or paragraph inside it — call `get_doc_link` and render the result using this exact presentation pattern:
+6. **Handle sort requests inline when openwriter surfaces them.** The user marks docs in the sidebar with "Request sort" when they don't know where a doc belongs and want you to file it. OpenWriter surfaces pending sorts two ways: (a) `SORT_STATUS: N docs awaiting sort` in the MCP server's session-start instructions; (b) a `⚠ N docs awaiting sort` footer on `list_documents` / `list_workspaces` / `get_workspace_structure`. **No minion.** Sorting is a judgment call (which workspace, which container, why) — handle it yourself in conversation.
+
+   **The procedure per pending doc:**
+   1. `list_pending_sorts` — returns identity + current location + any prior proposal.
+   2. `outline_doc(docId)` first to orient. If the doc has headings, the skeleton + a hit-targeted `peek_doc({ around })` is enough. Fall back to `read_pad` only when the doc has no structure or you genuinely need everything.
+   3. `get_workspace_structure` — find candidate destination containers. Look for a `purpose:` hint on containers/workspaces (strong signal — author told you what belongs there). If absent, use `browse_docs` to see what other docs in a candidate container are about.
+   4. Pick a destination. **Bias toward asking the user** when a doc could plausibly live in two places. **Never auto-execute** — every sort move needs human confirmation, either via chat ("moving Notes-on-X into Reference, good?") or via the UI accept/reject popover.
+   5. Execute. Two paths:
+      - **1–3 docs (chat flow):** discuss inline → `move_item` on confirmation → `mark_sorted({ docs: [...] })`.
+      - **Many docs (batch flow):** `propose_sort({ proposals: [...] })` writes one proposal per doc back into frontmatter. The sidebar flips each doc's badge to "proposal ready" and the user accepts/rejects via the in-menu popover — that triggers the move + mark_sorted on the backend automatically.
+
+   **Surfacing to the user:** treat sort surfacing like an inbox item, not a notification. On first surface in a session: "You've got 3 pending sorts — two obvious moves and one I want to check on." Then propose destinations and walk through them. Don't ask permission to start; just engage with the actual destination decisions.
+
+   **Skip the doc** ("not now"): `mark_sorted` it anyway with no move — clears the marker without filing. Or leave it pending if the user wants to think on it.
+7. **Emit deep links whenever you cite a docId.** Any time you reference a specific document in chat — naming it, summarizing it, pointing the user at a beat or paragraph inside it — call `get_doc_link` and render the result using this exact presentation pattern:
 
    **Doc level** (one link, header bold):
    ```
@@ -59,6 +73,24 @@ You are a writing collaborator. You read documents and make edits **exclusively
    ```
 
    Use the doc title as the link label for doc-level links. Use the beat label or a short description of the block for node-level bullets — never just "node" or a raw ID. When citing multiple nodes from the same doc, group them under one **Node level** header. When citing nodes across multiple docs, use a separate block per doc. The cost is one `get_doc_link` call per cited doc; the payoff is the user goes from "where is that?" to "right there" in one click.
+8. **Orient by content first; pick by nodeId second.** Never call `peek_doc` or `get_nodes` with cold nodeIds. Node-targeting without prior content orientation is meaningless — IDs are byproducts of orientation, never the starting point. The two legitimate entry paths into a doc:
+
+   - **Content entry** — `search_docs(query, { docId })` returns matching nodes with their IDs inside the doc. Use when you know roughly what you're looking for.
+   - **Structural entry** — `outline_doc(docId)` returns the heading tree (or top-level previews if no headings). Use when you want to see what the doc IS before reading any of it.
+
+   From either entry you get nodeIds; then `peek_doc` reads windowed slices around them. Skipping the orientation step and calling `peek_doc({ node: 'abc123' })` from nowhere is a footgun — you don't know what abc123 IS or whether it's the right place to read.
+
+   **The read ladder by cost** (use the cheapest tier that answers your question):
+   1. `search_docs(query)` — workspace content search (~50 tokens per hit)
+   2. `browse_docs({ workspaceFile })` — concept-level shelf scan (~60 tokens per doc)
+   3. `outline_doc(docId)` — heading tree (~5 tokens per heading)
+   4. `search_docs(query, { docId })` — in-doc content search → matching nodeIds
+   5. `peek_doc(docId, target)` — windowed node read
+   6. `read_pad(docId)` — first ~2,000 words of the body, ALWAYS truncated above the cap
+
+   `read_pad` is a fixed-window tool by contract. Docs ≤ ~2,000 words return in full. Above the cap, you get the doc opening (title + intro + first few sections — the most context-rich slice) plus a `lastNodeId` and a continuation hint pointing at `peek_doc({ around: lastNodeId, after: N })`, `outline_doc`, or `search_docs({ query, docId })`. There is no `force` flag — the cap is the contract.
+
+   **Implication for doc structure:** monolith docs (8k+ words in one file) push you up the ladder on every read. Splitting into chapters, sections, or topic-sized docs makes everything cheaper — outline_doc shows the whole shape, browse_docs returns concept-level summaries, and individual reads come back complete. The cap is friction designed to surface monoliths as the wrong unit for AI-assisted writing in this era.
 
 ## Setup — Which Path?
 
@@ -84,36 +116,10 @@ Skip to [Writing Strategy](#writing-strategy) below.
 
 ### MCP tools are NOT available (needs setup)
 
-The user has this skill but hasn't set up the MCP server yet. One command does everything:
-
-```bash
-npx openwriter install-skill
-```
-
-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.
-
-**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"]
-    }
-  }
-}
-```
+The user hasn't set up the MCP server yet. See `docs/setup.md` for install commands and platform-specific config (Claude Code, OpenCode, etc.).
 
 After setup, tell the user:
-1. Restart your Claude Code session (MCP servers load on startup)
+1. Restart your Claude Code or OpenCode session (MCP servers load on startup)
 2. Open http://localhost:5050 in your browser
 
 ## Document Identity: Titles vs DocIds
@@ -137,7 +143,10 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `write_to_pad` | `docId`, `changes` | Apply edits as pending decorations (rewrite, insert, delete) |
 | `populate_document` | `docId?`, `content` | Populate an empty doc with content (two-step creation flow) |
 | `get_pad_status` | — | Lightweight poll: word count, pending changes, userSignaledReview |
-| `get_nodes` | `nodeIds` | Fetch specific nodes by ID |
+| `get_nodes` | `nodeIds` | DEPRECATED — use `peek_doc({ nodes: [ids] })`. Alias kept for one release. |
+| `outline_doc` | `docId`, `underHeading?`, `depth?`, `offset?`, `limit?` | Structural skeleton — heading tree by default (~5 tokens/heading). Drill into a section with `underHeading`. Block-preview fallback for docs without headings. The cheap orientation tool before any body read. |
+| `peek_doc` | `docId`, `target` (one of: `{node}` / `{nodes}` / `{around,before,after}` / `{from,to}` / `{first}` / `{last}` / `{position,span}`) | Windowed node read once oriented. Six target shapes for different access patterns. Use this instead of `read_pad` whenever you only need part of a doc. |
+| `search_docs` | `query`, `docId?`, `limit?` | Full-text search. Default: ranked docs across the workspace (snippets). With `docId`: matching nodes inside that doc (nodeId + type + snippet). The content-to-node bridge — pairs with `peek_doc` for the read. |
 | `get_metadata` | — | Get frontmatter metadata for the active document |
 | `set_metadata` | `metadata` | Update frontmatter metadata (merge, set key to null to remove) |
 
@@ -166,7 +175,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 | `list_workspaces` | List all workspaces with title and doc count |
 | `create_workspace` | Create a new workspace |
 | `delete_workspace` | Delete a workspace and all its document files (moves to OS trash) |
-| `get_workspace_structure` | Get full workspace tree: containers, docs, per-doc enrichment (logline, status, STALE marker), workspace-level vocab/schema, plus context (characters, settings, rules) |
+| `get_workspace_structure` | Get the workspace tree shape: containers + their IDs, docs + their filenames, workspace-level structural fields (vocab, schema, enrichment flag), plus context (characters, settings, rules). **Tree shape only** — per-doc loglines, status, tags, and stale flag are NOT here. Use this when you need a destination container (sort, move) or to understand nesting. For "what is each doc about" call `browse_docs`. |
 | `get_item_context` | Get progressive disclosure context for a doc — workspace context + the doc's own enrichment (logline, status, enrichmentStale) |
 | `update_workspace_context` | Update workspace context (characters, settings, rules) |
 
@@ -197,13 +206,23 @@ OpenWriter detects when a doc has drifted past enrichment thresholds (sentence-h
 - Default to `draft` on new docs (omit `status` from `create_document` and it lands as `draft`).
 - Flip to `canonical` when the doc commits to the workspace spine (Beats locked, Research Note is now load-bearing, Master Reference is the source of truth).
 - Flip back to `draft` when superseded (e.g. Ch 7 Beats v3 ships → demote v1/v2 to `draft`).
-- The common crawl pattern is `crawl({ status: "canonical" })` — that's the trusted-shelf query.
+- The common browse pattern is `browse_docs({ status: "canonical" })` — that's the trusted-shelf query.
 
 | Tool | Key Params | Description |
 |------|-----------|-------------|
 | `list_dirty_docs` | `workspaceFile?` | List docs that need enrichment (never enriched OR explicitly flagged stale). Returns identity + reason only — no bodies. Optionally scoped to one workspace. Docs in opted-out workspaces (`enrichmentDisabled: true`) are excluded. |
 | `mark_enriched` | `docs: [{docId, logline}]` | Stamp one or more docs as freshly enriched. **Strict schema** — passing `domain` / `concepts` / `docRole` / `status` fails validation. OpenWriter auto-computes baselines (`lastEnrichedAt`, `lastEnrichedCharCount`, `lastEnrichedSentences`), clears `enrichmentStale`, and retires legacy fields from frontmatter. The minion calls this once at the end of its run with the full batch. |
-| `crawl` | `workspaceFile?`, `tags?`, `status?` (`canonical`/`draft`), `hasLogline?` | Bulk-read enrichment fields per doc with AND-composed filters. The agent's "scan the shelf" primitive — ~60 tokens per doc, no bodies. v0.19.0 dropped `domain` / `concepts` / `docRole` filters (their fields had no authority discipline); `status` is the replacement axis for the common load-bearing-vs-working query. |
+| `browse_docs` | `workspaceFile?`, `tags?`, `status?` (`canonical`/`draft`), `hasLogline?` | Bulk-read concept-level frontmatter per doc with AND-composed filters. The agent's "scan the shelf" primitive — ~60 tokens per doc, no bodies, no tree shape. Pairs with `get_workspace_structure` (tree shape), `outline_doc` (skeleton), `peek_doc` (windowed read), and `read_pad` (full body) as the read ladder. Renamed from `crawl` / `browse` — both kept as DEPRECATED aliases for one release. |
+
+### Sort Requests
+
+User-triggered file-this-for-me marker. See firm rule 6 for the full procedure. The agent picks up pending sorts via the surfacing footer / SORT_STATUS notice and handles them inline.
+
+| Tool | Key Params | Description |
+|------|-----------|-------------|
+| `list_pending_sorts` | `workspaceFile?` | List docs the user has marked for sorting. Returns identity + current location + optional `proposal` (already written by a prior pass). |
+| `propose_sort` | `proposals: [{docId, wsFilename, containerId, reasoning}]` | Write a proposal back to one or more docs (batch flow). The sidebar flips each doc's badge to "proposal ready"; the user accepts or rejects via the in-menu popover (server applies the move on accept). |
+| `mark_sorted` | `docs: [{docId}]` | Clear the sortRequest marker after a chat-flow move (`move_item` first) or after deciding the doc should stay where it is. Bulk-friendly. |
 
 ### Comments
 
@@ -256,7 +275,7 @@ For making changes to existing documents — rewrites, insertions, deletions:
 
 - Use `write_to_pad` for all edits — **`docId` is required** (8-char hex from `list_documents` or `read_pad`)
 - Send **3-8 changes per call** for a responsive, streaming feel
-- Always `read_pad` before editing to get fresh node IDs
+- Get fresh node IDs before editing. For **broad edits** spanning the doc, `read_pad` is the right call. For **surgical edits** where you already know the target area (from a prior `outline_doc`, `search_docs`, or deep-link click), `peek_doc` around the anchor returns just the nodes you need with current IDs — much cheaper on long docs.
 - Respect `pendingChanges > 0` — wait for the user to accept/reject before sending more
 - Content accepts markdown strings (preferred) or TipTap JSON
 - **`rewrite` preserves the target node's type.** Sending plain prose to rewrite a heading keeps it a heading; the same for list items and blockquotes. To intentionally change a node's type, use `delete` + `insert`. For surgical text-only edits inside a node (no risk of restructuring), `edit_text` is the smaller hammer.
@@ -367,27 +386,56 @@ For voice-matched drafting without a custom voice profile, install **voice-prese
 
 ## Workflow
 
-### Single document
+### Research (read-only, no edits coming)
+
+When the user asks "find X in this doc", "what does Y argue", "show me the beat about Z" — read-only intent. Use the ladder, not `read_pad`.
+
+```
+1. search_docs({ query: "X" })                 → ranked docs across workspace
+                                                  OR
+   browse_docs({ status: "canonical" })        → shelf-level scan of one workspace
+2. outline_doc({ docId })                      → heading skeleton (~5 tokens/heading)
+                                                  Use underHeading to drill into one section.
+3. search_docs({ query: "X", docId })          → in-doc node hits with nodeIds
+                                                  OR pick a heading nodeId from step 2.
+4. peek_doc({ docId, target: { around, before, after } })
+                                                → read the windowed slice
+```
+
+Cost on an 8,000-word chapter doc: ~1.5k tokens via the ladder vs ~10k via `read_pad`. Use the ladder.
+
+### Single document (editing)
 
 ```
 1. get_pad_status  → check pendingChanges and userSignaledReview
-2. read_pad        → get full document with node IDs + docId
+2. Orient on the doc:
+   - Short doc (≤ ~2,000 words): read_pad returns the full body — node IDs included
+   - Long doc (above the cap): outline_doc({ docId }) for shape, then
+     peek_doc({ around: nodeId, before, after }) around the area you'll edit
+     (only need fresh IDs for the region you're touching)
+   - You already know the anchor (from a prior search_docs or deep-link click):
+     skip straight to peek_doc({ around: anchor }) — no full-body read needed
 3. get_metadata    → check tweetContext/articleContext for URLs, mode, tags
 4. write_to_pad({ docId: "a1b2c3d4", changes: [...] })
 5. Wait            → user accepts/rejects in browser
 ```
 
+`read_pad` always returns the doc opening up to ~2,000 words. For broader work on a long doc, walk the outline + peek pages — never assume you got the whole body from one read_pad call. The truncation response includes a `lastNodeId` and continuation hint pointing at exactly which tool to call next.
+
 **For tweet/article docs:** step 3 gives you the parent tweet URL (in `tweetContext.url`) and mode (`reply`/`quote`/`tweet`). Use this URL with fxtwitter to read the parent tweet for free — never search externally for it.
 
 ### Multi-document
 
 ```
-1. list_documents    → see all docs with title + [docId]
-2. read_pad({ docId: "e5f6a7b8" })  → reads that doc directly, no switch needed
-3. write_to_pad({ docId: "e5f6a7b8", changes: [...] })
-                     → edits go to the identified doc, no view switch needed
+1. list_documents               → see all docs with title + [docId] + wordCount
+2. For each target doc, orient first:
+   - Short doc: read_pad({ docId }) returns full body
+   - Long doc: outline_doc({ docId }) → peek_doc({ docId, target: {...} })
+3. write_to_pad({ docId, changes: [...] })  → edits go to the identified doc
 ```
 
+The wordCount on `list_documents` tells you up-front which docs will return in full from `read_pad` and which will truncate. Use it to plan: a 500-word doc is one round trip; an 8,000-word doc is outline + a peek or two.
+
 ### Creating new content (two-step)
 
 ```

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

@@ -10,6 +10,13 @@ description: |
 model: haiku
 maxTurns: 500
 tools: mcp__openwriter__list_dirty_docs, mcp__openwriter__read_pad, mcp__openwriter__mark_enriched
+# OpenCode compatibility
+mode: subagent
+steps: 500
+permission:
+  openwriter_list_dirty_docs: allow
+  openwriter_read_pad: allow
+  openwriter_mark_enriched: allow
 ---
 
 # OpenWriter Enrichment Minion

package/skill/docs/setup.md

@@ -0,0 +1,62 @@
+# OpenWriter Setup
+
+## Quick install
+
+```bash
+npx openwriter install-skill
+```
+
+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 install-skill`. 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