openwriter 0.25.0 → 0.27.0

package/dist/server/state.js

@@ -16,7 +16,8 @@ import { matchNodes } from './node-matcher.js';
 import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
 import { anyLegacyRaw } from './node-fingerprint.js';
 import { markdownToNodes, resolvePreviousNodes, resolveGraveyard } from './markdown-parse.js';
-import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
+import { extractOverlay, applyOverlayPure, splitMergedDoc, saveOverlay, loadOverlay, loadDocFromDisk, deleteOverlay, repairOverlaysOnStartup, diagLog } from './pending-overlay.js';
+import { loadPendingMetadata, savePendingMetadata } from './pending-metadata.js';
 import { harvestSentenceHashes, harvestCharCount, isEnrichmentStale } from './enrichment.js';
 import { clearActivityBuffer } from './activity-log.js';
 import { titleFromDoc, shouldAutoTitle } from './title-from-body.js';
@@ -84,6 +85,7 @@ const DEFAULT_DOC = {
 let state = {
     canonical: DEFAULT_DOC,
     overlay: new Map(),
+    pendingMetadata: null,
     document: DEFAULT_DOC,
     title: 'Untitled',
     metadata: { title: 'Untitled' },
@@ -543,6 +545,21 @@ export function getOverlay() {
 export function getTitle() {
     return state.title;
 }
+/** Snapshot of the active doc's pending metadata (title, etc.). Null if no
+ *  metadata is staged. The sidebar / title bar / ReviewTab consult this to
+ *  decide whether to render a metadata-pending decoration.
+ *  adr: adr/pending-overlay-model.md */
+export function getPendingMetadata() {
+    return state.pendingMetadata ? { ...state.pendingMetadata } : null;
+}
+/** Replace the active doc's pending metadata. Persists to the sidecar so the
+ *  proposal survives a doc switch or restart. Pass null to clear. */
+export function setPendingMetadata(meta) {
+    state.pendingMetadata = meta && Object.keys(meta).length > 0 ? meta : null;
+    if (state.docId) {
+        savePendingMetadata(state.docId, state.pendingMetadata);
+    }
+}
 export function getFilePath() {
     return state.filePath;
 }
@@ -775,6 +792,13 @@ export function setMetadata(updates) {
     state.metadata = merged;
     if (updates.title)
         state.title = updates.title;
+    // Same contract as updateDocument: any path that mutates persistent state
+    // MUST bump docVersion, otherwise writeToDisk's no-op gate
+    // (docVersion === lastSavedDocVersion) silently drops the write and the
+    // mutation never reaches disk. Metadata-only changes (mark-sent tweetUrl,
+    // schedule edits, autoAccept toggle) all flow through here.
+    // adr: adr/pending-overlay-model.md
+    bumpDocVersion();
     // Auto-tag based on context metadata
     const filename = state.filePath
         ? (isExternalDoc(state.filePath) ? state.filePath : state.filePath.split(/[/\\]/).pop() || '')
@@ -1026,11 +1050,19 @@ export function cancelDebouncedSave() {
     }
 }
 export function applyChanges(changes) {
-    // Apply to server-side document (source of truth)
-    const processed = applyChangesToDocument(changes);
-    // Bump version + lock browser doc-updates to prevent stale state overwrite
+    // Bump version BEFORE applying so new overlay entries created by
+    // applyChangesToDocument's setPrimaryFromMerged → setOverlayFromEntries
+    // pass are stamped with the post-bump version (the version we're about
+    // to broadcast), not the pre-bump version. Without this, a stale
+    // browser doc-update arriving with browserVersion == preBump satisfies
+    // syncBrowserDocUpdate's `addedAtVersion > browserVersion` filter as
+    // FALSE for entries just added by this call — preservedServerEntries
+    // becomes 0, the overlay is wiped, and the agent's write silently
+    // vanishes despite a success response. adr: adr/pending-overlay-model.md
     const version = bumpDocVersion();
     setAgentLockActive();
+    // Apply to server-side document (source of truth)
+    const processed = applyChangesToDocument(changes);
     // Broadcast processed changes (with server-assigned IDs + version) to browser clients
     for (const listener of listeners) {
         listener(processed, version);
@@ -1466,6 +1498,9 @@ export function setActiveDocument(doc, title, filePath, isTemp, lastModified, me
     // Pending overlay rehydration. See mergeOverlayOnLoad for the three cases
     // (sidecar present, legacy migration, no pending).
     mergeOverlayOnLoad();
+    // Pending metadata rehydration. Read the sidecar's `metadata:` slot so a
+    // staged title rename survives doc-switch and restart. adr: adr/pending-overlay-model.md
+    state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
     // Subscribe the fs watcher to this doc so external writes (Edit tool,
     // VSCode, scripts) trigger a unified reload + version bump + broadcast.
     // adr: adr/active-doc-watcher.md
@@ -1649,6 +1684,7 @@ export function clearAllCaches() {
     state = {
         canonical: DEFAULT_DOC,
         overlay: new Map(),
+        pendingMetadata: null,
         document: DEFAULT_DOC,
         title: 'Untitled',
         metadata: { title: 'Untitled' },
@@ -1750,6 +1786,12 @@ export function reloadActiveDocFromDisk() {
     // sidecar (or legacy migration). Recompute merged via the helper.
     state.canonical = canonical;
     setOverlayFromEntries(entries);
+    // Pending metadata rehydration — mirror what setActiveDocument does.
+    // External-write reloads must keep state.pendingMetadata aligned with the
+    // sidecar's metadata: slot, otherwise a staged title rename gets dropped
+    // from in-memory state the moment fs.watch fires.
+    // adr: adr/pending-overlay-model.md
+    state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
     // External writes change the body but leave disk frontmatter pointing at
     // the previous save's fingerprints. If the user cuts/deletes a block before
     // the next browser-driven save, the matcher graveyards with that stale
@@ -2355,6 +2397,12 @@ export function load() {
             // source.
             // adr: adr/pending-overlay-model.md
             mergeOverlayOnLoad();
+            // Pending metadata rehydration. Boot path bypasses setActiveDocument,
+            // so the per-doc sidecar's `metadata:` slot must be loaded here too.
+            // Without this, a server restart drops staged title renames from
+            // in-memory state until the user switches docs.
+            // adr: adr/pending-overlay-model.md
+            state.pendingMetadata = state.docId ? loadPendingMetadata(state.docId) : null;
             break;
         }
         catch {
@@ -2545,11 +2593,25 @@ export function addDocTag(filename, tag) {
         if (!tags.includes(tag)) {
             tags.push(tag);
             state.metadata.tags = tags;
-            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            // Same docVersion contract as setMetadata: tag changes mutate
+            // state.metadata, so they must bump or writeToDisk's no-op gate
+            // silently drops the write.
+            bumpDocVersion();
+            // Preserve mtime — tag changes shouldn't affect sidebar sort order.
+            // After rolling back disk mtime, we MUST also roll back state.loadedMtime
+            // (which writeToDisk just stamped to the post-write disk mtime).
+            // The fs.watch self-suppression contract is `diskMtime === loadedMtime`;
+            // a divergence here will fire a phantom "external write detected"
+            // reload banner when the watcher's debounced handler runs.
             const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
-            if (mtime && state.filePath)
+            if (mtime && state.filePath) {
                 safeRestoreMtime(state.filePath, mtime);
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
+            }
         }
     }
     else {
@@ -2585,11 +2647,19 @@ export function removeDocTag(filename, tag) {
         if (idx >= 0) {
             tags.splice(idx, 1);
             state.metadata.tags = tags.length > 0 ? tags : undefined;
-            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            // Same docVersion contract as addDocTag — mutation must bump or
+            // writeToDisk's no-op gate silently drops the write.
+            bumpDocVersion();
+            // Same loadedMtime re-stamp as addDocTag — see comment there.
             const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
-            if (mtime && state.filePath)
+            if (mtime && state.filePath) {
                 safeRestoreMtime(state.filePath, mtime);
+                try {
+                    state.loadedMtime = statSync(state.filePath).mtimeMs;
+                }
+                catch { /* best-effort */ }
+            }
         }
     }
     else {
@@ -2897,41 +2967,50 @@ function flushDocToFile(filename, doc, title, metadata) {
     invalidateBacklinksCache();
 }
 export function populateDocumentFile(filename, doc) {
-    const targetPath = resolveDocPath(filename);
-    const raw = readFileSync(targetPath, 'utf-8');
-    const parsed = markdownToTiptap(raw);
+    // Read the existing doc as the user-visible MERGED view — canonical body
+    // plus any pre-existing sidecar overlay. Using the bare markdownToTiptap
+    // here would silently drop pre-existing pending entries (the file's
+    // sidecar lives outside the .md body), so a re-populate or a populate on
+    // a doc with prior pending state would clobber the overlay on the
+    // subsequent flushDocToFile. adr: adr/pending-overlay-model.md
+    const loaded = loadDocFromDisk(filename);
     // Skip pending tagging when the target doc effectively has autoAccept on —
     // content commits directly as accepted.
-    if (!isAutoAcceptActive(filename, parsed.metadata)) {
+    if (!isAutoAcceptActive(filename, loaded.metadata)) {
         markAllNodesAsPending(doc, 'insert');
     }
-    // Bug #1 fix (v0.20.0): preserve the stub's trailing canonical paragraph(s).
-    // flushDocToFile writes `doc` directly — it does NOT merge with the existing
-    // parsed.document on disk. Without this merge step, the stub's auto-generated
-    // trailing paragraph falls out of canonical, the matcher's `previousNodes`
-    // for any subsequent save no longer references it, and a follow-up Accept All
-    // doc-update can find itself with no matching previousNodes to anchor against.
-    // Cascading: the matcher classifies the newly accepted inserts as deletions
-    // (orphaned from the empty previousNodes set), they go to graveyard, the disk
-    // body ends up empty.
-    // Mirrors the active-doc fix in mcp.ts:populate_document.
-    if (parsed.document?.content?.length) {
+    // Preserve any pre-existing real content (pending nodes from a prior
+    // populate or write) that isn't in the incoming set — so a re-populate or
+    // populate-on-top doesn't clobber prior agent proposals. flushDocToFile
+    // writes `doc` directly and extracts its overlay wholesale, so what isn't
+    // in `doc.content` after this step disappears from the next save.
+    //
+    // Empty paragraphs are explicitly NOT preserved. createDocumentFile mints
+    // a trailing empty paragraph as a TipTap "doc must have at least one
+    // node" stub; that stub is obsolete the moment populate provides real
+    // content, and preserving it leaves a phantom empty paragraph at the end
+    // of every populated doc forever. Mirrors the active-doc preserve in
+    // mcp.ts:populate_document. adr: adr/pending-overlay-model.md
+    if (loaded.document?.content?.length) {
         const incomingIds = new Set(doc.content
             .map((n) => n?.attrs?.id)
             .filter((id) => typeof id === 'string'));
-        const preserved = parsed.document.content.filter((n) => {
+        const preserved = loaded.document.content.filter((n) => {
             const id = n?.attrs?.id;
-            return id && !incomingIds.has(id);
+            if (!id || incomingIds.has(id))
+                return false;
+            const isEmptyParagraph = n.type === 'paragraph' && (!n.content || n.content.length === 0);
+            return !isEmptyParagraph;
         });
         if (preserved.length > 0) {
             doc.content = [...doc.content, ...preserved];
         }
     }
-    flushDocToFile(filename, doc, parsed.title, parsed.metadata);
+    flushDocToFile(filename, doc, loaded.title, loaded.metadata);
     const pendingCount = countPending(doc.content);
     const text = extractText(doc.content);
     const wordCount = text.trim() ? text.trim().split(/\s+/).length : 0;
-    return { title: parsed.title, wordCount, pendingCount };
+    return { title: loaded.title, wordCount, pendingCount };
 }
 /**
  * Apply node changes to a non-active document file on disk.
@@ -2954,12 +3033,17 @@ export function applyChangesToFile(filename, changes) {
         isTemp = cached.isTemp;
     }
     else {
-        const raw = readFileSync(targetPath, 'utf-8');
-        const parsed = markdownToTiptap(raw);
-        doc = parsed.document;
-        title = parsed.title;
-        metadata = parsed.metadata;
-        docId = metadata.docId || '';
+        // Cache miss — load the MERGED view (canonical + sidecar overlay). The
+        // bare markdownToTiptap would give canonical-only, so pre-existing pending
+        // entries would not be in `doc` when we apply the new changes. The
+        // subsequent flushDocToFile then extracts the overlay from `doc` and
+        // overwrites the sidecar — silently dropping every prior pending entry.
+        // adr: adr/pending-overlay-model.md
+        const loaded = loadDocFromDisk(filename);
+        doc = loaded.document;
+        title = loaded.title;
+        metadata = loaded.metadata;
+        docId = loaded.docId;
         isTemp = false;
     }
     const autoAccept = isAutoAcceptActive(filename, metadata);
@@ -3003,12 +3087,15 @@ export function applyTextEditsToFile(filename, nodeId, edits) {
         isTemp = cached.isTemp;
     }
     else {
-        const raw = readFileSync(targetPath, 'utf-8');
-        const parsed = markdownToTiptap(raw);
-        doc = parsed.document;
-        title = parsed.title;
-        metadata = parsed.metadata;
-        docId = metadata.docId || '';
+        // Cache miss — load the merged view so a target node living in the
+        // sidecar overlay (a pending insert the agent is now text-editing) is
+        // findable. Bare markdownToTiptap would only show canonical, and the
+        // findNode call below would fail. adr: adr/pending-overlay-model.md
+        const loaded = loadDocFromDisk(filename);
+        doc = loaded.document;
+        title = loaded.title;
+        metadata = loaded.metadata;
+        docId = loaded.docId;
         isTemp = false;
     }
     const found = findNode(doc.content, nodeId, doc.content);

package/dist/server/ws.js

@@ -3,7 +3,7 @@
  */
 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, onAutoTitleApplied, isAgentStub, unmarkAgentStub, } from './state.js';
-import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile, listDocuments } from './documents.js';
+import { switchDocument, createDocument, deleteDocument, getActiveFilename, promoteTempFile, listDocuments, acceptPendingTitle, rejectPendingTitle, getPendingTitle } from './documents.js';
 import { removeDocFromAllWorkspaces } from './workspaces.js';
 import { canonicalizeIdentifier } from './helpers.js';
 import { nodeTextPreview, diagLog } from './pending-overlay.js';
@@ -48,6 +48,29 @@ function debouncedBroadcastDocumentsChanged() {
         broadcastDocumentsChanged();
     }, 2100);
 }
+/**
+ * Build a document-switched payload object that includes pendingMetadata
+ * (currently a staged title rename, if any) for the active doc. Every
+ * call site that emits a document-switched message — initial connect,
+ * request-document, tweet-thread HR resync, switchDocument result —
+ * must use this so the title-bar inline diff renders consistently
+ * regardless of which path delivered the doc state.
+ * adr: adr/pending-overlay-model.md
+ */
+function buildDocumentSwitchedPayload(document, title, filename, metadata) {
+    const docId = getDocId();
+    const pendingTitle = docId ? getPendingTitle(docId) : null;
+    const pendingMetadata = pendingTitle ? { title: { from: pendingTitle.from, to: pendingTitle.to } } : null;
+    return {
+        type: 'document-switched',
+        document,
+        title,
+        filename,
+        docId,
+        metadata,
+        pendingMetadata,
+    };
+}
 export function setupWebSocket(server) {
     const wss = new WebSocketServer({
         server,
@@ -89,14 +112,7 @@ export function setupWebSocket(server) {
             setAgentLockActive();
             const filePath = getFilePath();
             const filename = filePath ? filePath.split(/[/\\]/).pop() || '' : '';
-            const msg = JSON.stringify({
-                type: 'document-switched',
-                document: getDocument(),
-                title: getTitle(),
-                filename,
-                docId: getDocId(),
-                metadata,
-            });
+            const msg = JSON.stringify(buildDocumentSwitchedPayload(getDocument(), getTitle(), filename, metadata));
             for (const ws of clients) {
                 if (ws.readyState === WebSocket.OPEN)
                     ws.send(msg);
@@ -210,14 +226,7 @@ export function setupWebSocket(server) {
         const docOnConnect = getDocument();
         const pendingOnConnect = pendingSummary(docOnConnect);
         diagLog(`[WS] document-switched SEND on-connect docId=${getDocId()} v=${getDocVersion()} pending=[${pendingOnConnect}]`);
-        ws.send(JSON.stringify({
-            type: 'document-switched',
-            document: docOnConnect,
-            title: getTitle(),
-            filename,
-            docId: getDocId(),
-            metadata: getMetadata(),
-        }));
+        ws.send(JSON.stringify(buildDocumentSwitchedPayload(docOnConnect, getTitle(), filename, getMetadata())));
         // Send pending docs info on connect
         ws.send(JSON.stringify({
             type: 'pending-docs-changed',
@@ -319,16 +328,21 @@ export function setupWebSocket(server) {
                 if (msg.type === 'request-document') {
                     const filePath = getFilePath();
                     const filename = filePath ? filePath.split(/[/\\]/).pop() || '' : '';
-                    ws.send(JSON.stringify({
-                        type: 'document-switched',
-                        document: getDocument(),
-                        title: getTitle(),
-                        filename,
-                        docId: getDocId(),
-                        metadata: getMetadata(),
-                    }));
+                    ws.send(JSON.stringify(buildDocumentSwitchedPayload(getDocument(), getTitle(), filename, getMetadata())));
                 }
                 if (msg.type === 'title-update' && msg.title) {
+                    // User typed directly in the title bar — this is "the user disposing."
+                    // It always lands hot. If an agent had a pending title proposal, the
+                    // user's direct edit supersedes it; clear the pending entry so the
+                    // diff UI dismisses. adr: adr/pending-overlay-model.md
+                    const activeDocId = getDocId();
+                    if (activeDocId) {
+                        const existing = getPendingTitle(activeDocId);
+                        if (existing) {
+                            rejectPendingTitle(activeDocId);
+                            broadcastPendingMetadataChanged(activeDocId, null);
+                        }
+                    }
                     setMetadata({ title: msg.title });
                     const promoted = promoteTempFile(msg.title);
                     if (promoted) {
@@ -341,6 +355,36 @@ export function setupWebSocket(server) {
                         debouncedBroadcastDocumentsChanged();
                     }
                 }
+                if (msg.type === 'accept-pending-title' && msg.docId) {
+                    try {
+                        const result = acceptPendingTitle(msg.docId);
+                        broadcastPendingMetadataChanged(msg.docId, null);
+                        if (result) {
+                            // updateDocumentTitle (inside acceptPendingTitle) re-runs
+                            // setActiveDocument when the doc is active, which clears state
+                            // and rebroadcasts. We also explicitly fire title-changed +
+                            // documents-changed to update sidebar + title bar.
+                            if (result.filename === getActiveFilename()) {
+                                broadcastTitleChanged(result.to);
+                            }
+                            broadcastDocumentsChanged();
+                            broadcastPendingDocsChanged();
+                        }
+                    }
+                    catch (err) {
+                        console.error('[WS] accept-pending-title failed:', err.message);
+                    }
+                }
+                if (msg.type === 'reject-pending-title' && msg.docId) {
+                    try {
+                        rejectPendingTitle(msg.docId);
+                        broadcastPendingMetadataChanged(msg.docId, null);
+                        broadcastPendingDocsChanged();
+                    }
+                    catch (err) {
+                        console.error('[WS] reject-pending-title failed:', err.message);
+                    }
+                }
                 if (msg.type === 'save') {
                     save();
                 }
@@ -491,7 +535,7 @@ export function setupWebSocket(server) {
 }
 export function broadcastDocumentSwitched(document, title, filename, metadata) {
     const resolvedMeta = metadata ?? getMetadata();
-    const msg = JSON.stringify({ type: 'document-switched', document, title, filename, docId: getDocId(), metadata: resolvedMeta });
+    const msg = JSON.stringify(buildDocumentSwitchedPayload(document, title, filename, resolvedMeta));
     for (const ws of clients) {
         if (ws.readyState === WebSocket.OPEN) {
             ws.send(msg);
@@ -527,6 +571,21 @@ export function broadcastTitleChanged(title) {
             ws.send(msg);
     }
 }
+/**
+ * Broadcast a pending-metadata change for a specific docId. The client reads
+ * this and updates the title bar / sidebar to render the proposal-in-review
+ * decoration. Passing `pendingMetadata: null` signals "the proposal cleared"
+ * (either accepted, rejected, or matched canonical).
+ *
+ * adr: adr/pending-overlay-model.md
+ */
+export function broadcastPendingMetadataChanged(docId, pendingMetadata) {
+    const msg = JSON.stringify({ type: 'pending-metadata-changed', docId, pendingMetadata });
+    for (const ws of clients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(msg);
+    }
+}
 // Debounced: coalesces rapid agent writes into a single broadcast.
 let pendingDocsTimer = null;
 const PENDING_DOCS_DEBOUNCE_MS = 500;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.25.0",
+  "version": "0.27.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.15.0"
+  version: "0.16.3"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -73,6 +73,8 @@ 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.
+
+   **The URL must come from `get_doc_link`** — it returns a real `http://...` URL. Never invent a URL scheme like `docId:abc123` or hand-construct a path; the link will be dead.
 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.
@@ -85,10 +87,18 @@ You are a writing collaborator. You read documents and make edits **exclusively
    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
+   5. `peek_doc(docId, target)` — windowed node read by nodeId
+   6. `read_pad(docId, ...)` — fixed-window word-position read (default: first ~2,000 words)
+
+   `read_pad` is a fixed-window tool by default but accepts two knobs for full control:
+
+   - **Default** — `read_pad({ docId })` returns the first ~2,000 words. Docs at or under the cap return in full.
+   - **Slice** — `read_pad({ docId, slice: { from: 0.5, to: 1 } })` reads a percentile range. `{from:0.5, to:1}` = back half, `{from:0.25, to:0.75}` = middle 50%, sequential `{from:0.0,to:0.1}` → `{from:0.1,to:0.2}` … = 10% chunks for whole-doc coverage at predictable per-call cost. Snaps to top-level node boundaries; subject to the cap unless `force` is set.
+   - **Force** — `read_pad({ docId, force: true })` bypasses the cap and returns the full requested region. Use for full-doc audits, rewrites, or anywhere you've explicitly accepted the cost.
 
-   `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.
+   Slice vs peek: peek anchors to a known nodeId (good for "read around this hit"); slice anchors to a word-position percentile (good for "give me the back half" or "walk this doc in 10% chunks"). Use the one that matches your intent — neither is strictly better.
+
+   When the cap kicks in, the response includes `lastNodeId` plus continuation hints for all four follow-up tools (read_pad slice, read_pad force, peek_doc, outline_doc).
 
    **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.
 
@@ -139,7 +149,7 @@ Every document has an immutable **docId** (8-char hex, e.g. `a1b2c3d4`) in its Y
 
 | Tool | Key Params | Description |
 |------|-----------|-------------|
-| `read_pad` | — | Read the current document (compact tagged-line format with `id:` in header) |
+| `read_pad` | `docId`, `slice?` (`{from,to}` floats in [0,1]), `force?` (boolean) | Fixed-window word-position read. **Default:** first ~2,000 words; docs at or under the cap return in full. **`slice: {from, to}`** reads a percentile range (e.g. `{from: 0.5, to: 1}` = back half, `{from: 0.25, to: 0.75}` = middle 50%, sequential `{from: 0, to: 0.1}` → `{from: 0.1, to: 0.2}` … = 10% chunks at predictable per-call cost). Snaps to top-level node boundaries, subject to the cap unless `force` is set. **`force: true`** bypasses the cap entirely — returns the full requested region (whole doc, or whole slice). Use for full-doc audits and rewrites where you've accepted the cost. Truncated responses include `lastNodeId` + continuation hints for slice / force / peek_doc / outline_doc. |
 | `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 |
@@ -275,7 +285,10 @@ 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
-- 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.
+- Get fresh node IDs before editing. Three patterns by edit scope:
+  - **Short doc broad edit** (≤ ~2,000 words): `read_pad({ docId })` returns the full body with all node IDs in one call.
+  - **Long doc broad edit**: either `read_pad({ docId, force: true })` for the whole body in one shot (cost acknowledged), or `read_pad({ docId, slice: {from, to} })` walking 10% chunks if the edit spans the whole doc but you want predictable per-call cost.
+  - **Surgical edit** (you already know the anchor from `outline_doc` / `search_docs` / deep-link click): `peek_doc({ around: anchor })` returns just the relevant region's current IDs — much cheaper than any read_pad form for targeted work.
 - 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.
@@ -388,7 +401,7 @@ For voice-matched drafting without a custom voice profile, install **voice-prese
 
 ### 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`.
+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 a default `read_pad`.
 
 ```
 1. search_docs({ query: "X" })                 → ranked docs across workspace
@@ -398,29 +411,38 @@ When the user asks "find X in this doc", "what does Y argue", "show me the beat
                                                   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
+4. Read the region — pick by how wide:
+   - peek_doc({ docId, target: { around: nodeId, before, after } })
+                                                → node-anchored window (small, surgical)
+   - read_pad({ docId, slice: { from: 0.4, to: 0.6 } })
+                                                → percentile-anchored region (wider, contiguous)
+   - read_pad({ docId, force: true })           → whole body (you've accepted the cost)
 ```
 
-Cost on an 8,000-word chapter doc: ~1.5k tokens via the ladder vs ~10k via `read_pad`. Use the ladder.
+**Pattern:** `search_docs` returns hits with node IDs *and* approximate doc positions. When the user wants the matched paragraph + a sentence either side, `peek_doc` around the node is right. When they want "the section that hit lives in" or "the back half of the doc that contains the hit" or "a contiguous region wider than peek's 100-node window," `read_pad` with a slice is the better call.
+
+Cost on an 8,000-word chapter doc: ~1.5k tokens via the ladder (search + peek), ~3k tokens via search + read_pad slice for a 25% region, ~10k tokens for the full body via `read_pad force`. Match the read to the question.
 
 ### Single document (editing)
 
 ```
 1. get_pad_status  → check pendingChanges and userSignaledReview
-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
+2. Orient on the doc — pick by edit shape:
+   - Short doc (≤ ~2,000 words): read_pad({ docId }) returns the full body
+   - Long doc, surgical edit (you know roughly what you're touching):
+     search_docs({ query, docId }) → peek_doc({ around: hitNodeId, before, after })
+     — fresh IDs for just the region you'll edit, ~500 tokens
+   - Long doc, broad edit on one section:
+     outline_doc({ docId }) → read_pad({ docId, slice: { from, to } })
+     where {from, to} bounds the section's percentile range
+   - Long doc, whole-body rewrite:
+     read_pad({ docId, force: true }) — explicit, cost acknowledged
 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.
+`read_pad` always returns the doc opening up to ~2,000 words unless you pass `slice` or `force`. Never assume you got the whole body from a default `read_pad` — the truncation response tells you what's missing and gives you the exact slice/force/peek/outline calls to continue.
 
 **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.
 
@@ -428,13 +450,29 @@ Cost on an 8,000-word chapter doc: ~1.5k tokens via the ladder vs ~10k via `read
 
 ```
 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: {...} })
+2. For each target doc, orient by wordCount:
+   - ≤ ~2,000 words: read_pad({ docId }) — full body in one call
+   - Long doc, targeted: search_docs({ query, docId }) → peek_doc({ around: hit })
+   - Long doc, sectional: outline_doc({ docId }) → read_pad({ docId, slice })
+   - Long doc, full pass: read_pad({ docId, force: true })
 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.
+The wordCount on `list_documents` tells you up-front which docs return in full from a default `read_pad` and which will truncate — use it to plan the read shape per doc. A 500-word doc is one round trip; an 8,000-word doc is search + peek for surgical work, outline + slice for sectional work, or force for the rare whole-body case.
+
+### Reading patterns at a glance
+
+| Intent | Best tool |
+|--------|-----------|
+| "What's in this doc?" | `outline_doc({ docId })` |
+| "Find X in this doc" | `search_docs({ query, docId })` → `peek_doc({ around: hit })` |
+| "Read around this node I already know" | `peek_doc({ around: anchor })` |
+| "Read this specific region of the doc" | `read_pad({ docId, slice: { from, to } })` |
+| "Walk the whole doc in predictable chunks" | `read_pad({ docId, slice })` × N sequential calls |
+| "Give me everything" | `read_pad({ docId, force: true })` |
+| "What's in this doc and what's it about" | `outline_doc` + frontmatter via `get_metadata` |
+| "Which docs in the workspace talk about X" | `search_docs({ query })` (no docId) |
+| "Scan the shelf — concept-level only" | `browse_docs({ workspaceFile })` |
 
 ### Creating new content (two-step)