From c17a978773373a37986b9c91206c621709ff1440 Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Mon, 7 Sep 2026 23:29:20 +0200
Subject: [PATCH 1/5] feat(documents): add document workspaces
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An experimental project type for exploring problems in prose — architecture
notes, specs, ADRs, research. Several agents get the same passage and the same
base version; you read the alternatives and decide what enters the document.
Behind the Document workspaces switch in Settings → Experimental.

- Markdown documents and whole HTML pages, the latter rendered with their own
  stylesheet and their innermost elements as the blocks, matching what a
  browser shows: a page's custom properties, `rem` basis, reset and `position`
  survive, and page CSS cannot reach the app's own controls.
- A composer that is always there: it rests at the foot of the column and acts
  on the whole document until you pick a passage by text, block or heading,
  then moves under the passage and follows it.
- A task either goes to the long-running agent session, which edits the
  checkout as you watch, or runs as headless candidates in their own worktrees,
  with the agents, candidate counts, model and reasoning level chosen per
  project and remembered.
- Compare proposals against the base in a modal, accept one or reject all, or
  take a candidate's changes one at a time and preview the result before it
  lands. The columns are resizable and remember their widths.
- Refine a candidate instead of accepting it: a fresh isolated run seeded with
  that proposal's content, reviewed whole, leaving the original available.
- Edit a block's Markdown or HTML source in place from its hover pencil or the
  toolbar; the rest of the file, and its line endings, are preserved, and a
  save refuses to overwrite a document that changed meanwhile.
- Notes and agent-answered questions hang off a passage as margin markers,
  reachable with the mouse and marked while an answer is still coming.
- History is git log for the document with the Parallel-* trailers parsed,
  showing diffs, rendering older versions and reverting entries.
- A right panel with the agent terminal, the runs and the project's files;
  relative links inside a document open the file they point at.

Hardened against a multi-agent review: the watcher compares snapshots rather
than a proxy with itself, a block that parted from its file reports so in the
dialog instead of tripping the window's error boundary, page stylesheets are
brace-balanced before scoping, markup the app did not write goes through one
sanitize policy, documents are not read through symlinks, proposals on an
uncommitted document are refused, and a candidate finishing early no longer
strands its peers as running.

Also corrects `EMPTY_TREE` in electron/ipc/git.ts, which was not the empty
tree, so the pre-existing root-commit diff paths never matched.

Claude-Session: https://claude.ai/code/session_01Gso9dUvEZF5orpAwWhHACi
Claude-Session: https://claude.ai/code/session_01EQcZpLJ71Nbf7XsZPJeYeK
Claude-Session: https://claude.ai/code/session_01NZFMpgnLkK1nLq3AKf63nd
---
 .dependency-cruiser.cjs                       |    2 +
 .gitignore                                    |    1 +
 docs/document-workspaces.md                   |  314 +++
 electron/documents/agents.test.ts             |  244 ++
 electron/documents/agents.ts                  |  331 +++
 electron/documents/annotations.test.ts        |  183 ++
 electron/documents/annotations.ts             |  400 ++++
 electron/documents/editing.test.ts            |  100 +
 electron/documents/files.test.ts              |   39 +
 electron/documents/files.ts                   |   27 +
 electron/documents/git.ts                     |   24 +
 electron/documents/logs.ts                    |   62 +
 electron/documents/prompt.test.ts             |  111 +
 electron/documents/prompt.ts                  |  145 ++
 .../documents/refinement.integration.test.ts  |   86 +
 electron/documents/register.ts                |  193 ++
 electron/documents/runs.integration.test.ts   |  577 +++++
 .../runs.real-claude.integration.test.ts      |  211 ++
 electron/documents/runs.test.ts               |  138 ++
 electron/documents/runs.ts                    | 1550 +++++++++++++
 electron/documents/setup.test.ts              |  205 ++
 electron/documents/setup.ts                   |  180 ++
 electron/documents/shared.ts                  |   58 +
 electron/documents/types.ts                   |  219 ++
 electron/ipc/channel-manifest.json            |   27 +-
 electron/ipc/git.ts                           |    2 +-
 electron/ipc/register.ts                      |   11 +-
 electron/ipc/validate.ts                      |    8 +
 electron/main.ts                              |   10 +-
 electron/preload.cjs                          |   25 +
 electron/test-env.test.ts                     |   38 +
 package-lock.json                             |    3 +-
 package.json                                  |    1 +
 src/App.tsx                                   |   17 +
 src/components/AddProjectMenu.tsx             |  114 +
 src/components/EditProjectDialog.tsx          |  352 +--
 src/components/IconButton.tsx                 |    2 +-
 src/components/NewTaskDialog.tsx              |    5 +-
 src/components/PlanViewerDialog.tsx           |   17 +-
 src/components/ProjectSelect.tsx              |    4 +-
 src/components/SettingsDialog.tsx             |    9 +
 src/components/Sidebar.tsx                    |   88 +-
 src/components/TaskNotesBody.client.test.tsx  |   91 +
 src/components/TaskNotesBody.tsx              |   32 +-
 src/components/TilingLayout.tsx               |    3 +-
 src/documents/AgentTerminal.tsx               |  103 +
 src/documents/AnnotationBubble.tsx            |  224 ++
 .../AnnotationMarker.client.test.tsx          |  116 +
 src/documents/AnnotationMarker.tsx            |  108 +
 src/documents/BlockActions.client.test.tsx    |  128 ++
 src/documents/BlockActions.tsx                |  111 +
 src/documents/BlockEditor.client.test.tsx     |   92 +
 src/documents/BlockEditor.tsx                 |  112 +
 src/documents/CandidateOutputDialog.tsx       |  101 +
 .../CandidateRefinement.client.test.tsx       |   80 +
 src/documents/CandidateRefinement.tsx         |   76 +
 src/documents/CompareDialog.tsx               |   87 +
 src/documents/CompareView.client.test.tsx     |  289 +++
 src/documents/CompareView.tsx                 |  656 ++++++
 src/documents/DocumentIcon.tsx                |   19 +
 src/documents/DocumentViewer.client.test.tsx  |  313 +++
 src/documents/DocumentViewer.tsx              |  298 +++
 .../DocumentWorkspaceOverlay.client.test.tsx  |  184 ++
 src/documents/DocumentWorkspaceOverlay.tsx    |  591 +++++
 src/documents/FileTreePanel.tsx               |  121 +
 src/documents/HistoryView.tsx                 |  219 ++
 src/documents/ModelRows.tsx                   |   77 +
 .../NewDocumentProjectDialog.client.test.tsx  |   65 +
 src/documents/NewDocumentProjectDialog.tsx    |  324 +++
 src/documents/PageBlocks.tsx                  |  128 ++
 src/documents/RightPanel.tsx                  |  119 +
 .../RunComposer.annotate.client.test.tsx      |  125 +
 src/documents/RunComposer.client.test.tsx     |  130 ++
 .../RunComposer.draft.client.test.tsx         |   88 +
 src/documents/RunComposer.tsx                 |  529 +++++
 src/documents/RunsRail.tsx                    |  173 ++
 src/documents/SourceDiff.tsx                  |   43 +
 src/documents/agent-terminal.ts               |   59 +
 src/documents/annotation-anchor.test.ts       |  236 ++
 src/documents/annotation-anchor.ts            |  268 +++
 src/documents/block-edit.test.ts              |   30 +
 src/documents/block-edit.ts                   |   27 +
 src/documents/block-merge.test.ts             |  263 +++
 src/documents/block-merge.ts                  |  257 +++
 src/documents/documents-styles.test.ts        |   42 +
 src/documents/documents.css                   | 2017 +++++++++++++++++
 src/documents/html-blocks.test.ts             |  183 ++
 src/documents/html-blocks.ts                  |  391 ++++
 src/documents/html-document.test.ts           |   29 +
 src/documents/html-document.ts                |   11 +
 src/documents/interactive-prompt.test.ts      |   59 +
 src/documents/interactive-prompt.ts           |   39 +
 src/documents/links.test.ts                   |   50 +
 src/documents/links.ts                        |   73 +
 src/documents/markdown-blocks.test.ts         |  129 ++
 src/documents/markdown-blocks.ts              |  230 ++
 src/documents/path-tree.test.ts               |   15 +
 src/documents/path-tree.ts                    |   41 +
 src/documents/render-document.test.ts         |   24 +
 src/documents/render-document.ts              |   19 +
 src/documents/store.ts                        |  837 +++++++
 src/documents/types.ts                        |    2 +
 src/documents/use-blocks.ts                   |   48 +
 src/documents/workspace-ui.ts                 |   63 +
 src/lib/marked-shiki.ts                       |   10 +-
 src/lib/mermaid.client.test.tsx               |   68 +
 src/lib/mermaid.ts                            |   33 +
 src/lib/sanitize.ts                           |   11 +
 src/store/autosave.ts                         |    1 +
 src/store/core.ts                             |    2 +
 src/store/persistence.ts                      |    3 +
 src/store/projects.ts                         |   42 +
 src/store/remoteTaskHandler.ts                |    3 +-
 src/store/store.ts                            |    4 +
 src/store/tasks.ts                            |    3 +
 src/store/types.ts                            |   30 +
 src/store/ui.ts                               |    5 +
 vitest.client.config.ts                       |    1 +
 vitest.config.ts                              |    1 +
 vitest.setup.ts                               |   22 +
 120 files changed, 17532 insertions(+), 237 deletions(-)
 create mode 100644 docs/document-workspaces.md
 create mode 100644 electron/documents/agents.test.ts
 create mode 100644 electron/documents/agents.ts
 create mode 100644 electron/documents/annotations.test.ts
 create mode 100644 electron/documents/annotations.ts
 create mode 100644 electron/documents/editing.test.ts
 create mode 100644 electron/documents/files.test.ts
 create mode 100644 electron/documents/files.ts
 create mode 100644 electron/documents/git.ts
 create mode 100644 electron/documents/logs.ts
 create mode 100644 electron/documents/prompt.test.ts
 create mode 100644 electron/documents/prompt.ts
 create mode 100644 electron/documents/refinement.integration.test.ts
 create mode 100644 electron/documents/register.ts
 create mode 100644 electron/documents/runs.integration.test.ts
 create mode 100644 electron/documents/runs.real-claude.integration.test.ts
 create mode 100644 electron/documents/runs.test.ts
 create mode 100644 electron/documents/runs.ts
 create mode 100644 electron/documents/setup.test.ts
 create mode 100644 electron/documents/setup.ts
 create mode 100644 electron/documents/shared.ts
 create mode 100644 electron/documents/types.ts
 create mode 100644 electron/test-env.test.ts
 create mode 100644 src/components/AddProjectMenu.tsx
 create mode 100644 src/components/TaskNotesBody.client.test.tsx
 create mode 100644 src/documents/AgentTerminal.tsx
 create mode 100644 src/documents/AnnotationBubble.tsx
 create mode 100644 src/documents/AnnotationMarker.client.test.tsx
 create mode 100644 src/documents/AnnotationMarker.tsx
 create mode 100644 src/documents/BlockActions.client.test.tsx
 create mode 100644 src/documents/BlockActions.tsx
 create mode 100644 src/documents/BlockEditor.client.test.tsx
 create mode 100644 src/documents/BlockEditor.tsx
 create mode 100644 src/documents/CandidateOutputDialog.tsx
 create mode 100644 src/documents/CandidateRefinement.client.test.tsx
 create mode 100644 src/documents/CandidateRefinement.tsx
 create mode 100644 src/documents/CompareDialog.tsx
 create mode 100644 src/documents/CompareView.client.test.tsx
 create mode 100644 src/documents/CompareView.tsx
 create mode 100644 src/documents/DocumentIcon.tsx
 create mode 100644 src/documents/DocumentViewer.client.test.tsx
 create mode 100644 src/documents/DocumentViewer.tsx
 create mode 100644 src/documents/DocumentWorkspaceOverlay.client.test.tsx
 create mode 100644 src/documents/DocumentWorkspaceOverlay.tsx
 create mode 100644 src/documents/FileTreePanel.tsx
 create mode 100644 src/documents/HistoryView.tsx
 create mode 100644 src/documents/ModelRows.tsx
 create mode 100644 src/documents/NewDocumentProjectDialog.client.test.tsx
 create mode 100644 src/documents/NewDocumentProjectDialog.tsx
 create mode 100644 src/documents/PageBlocks.tsx
 create mode 100644 src/documents/RightPanel.tsx
 create mode 100644 src/documents/RunComposer.annotate.client.test.tsx
 create mode 100644 src/documents/RunComposer.client.test.tsx
 create mode 100644 src/documents/RunComposer.draft.client.test.tsx
 create mode 100644 src/documents/RunComposer.tsx
 create mode 100644 src/documents/RunsRail.tsx
 create mode 100644 src/documents/SourceDiff.tsx
 create mode 100644 src/documents/agent-terminal.ts
 create mode 100644 src/documents/annotation-anchor.test.ts
 create mode 100644 src/documents/annotation-anchor.ts
 create mode 100644 src/documents/block-edit.test.ts
 create mode 100644 src/documents/block-edit.ts
 create mode 100644 src/documents/block-merge.test.ts
 create mode 100644 src/documents/block-merge.ts
 create mode 100644 src/documents/documents-styles.test.ts
 create mode 100644 src/documents/documents.css
 create mode 100644 src/documents/html-blocks.test.ts
 create mode 100644 src/documents/html-blocks.ts
 create mode 100644 src/documents/html-document.test.ts
 create mode 100644 src/documents/html-document.ts
 create mode 100644 src/documents/interactive-prompt.test.ts
 create mode 100644 src/documents/interactive-prompt.ts
 create mode 100644 src/documents/links.test.ts
 create mode 100644 src/documents/links.ts
 create mode 100644 src/documents/markdown-blocks.test.ts
 create mode 100644 src/documents/markdown-blocks.ts
 create mode 100644 src/documents/path-tree.test.ts
 create mode 100644 src/documents/path-tree.ts
 create mode 100644 src/documents/render-document.test.ts
 create mode 100644 src/documents/render-document.ts
 create mode 100644 src/documents/store.ts
 create mode 100644 src/documents/types.ts
 create mode 100644 src/documents/use-blocks.ts
 create mode 100644 src/documents/workspace-ui.ts
 create mode 100644 src/lib/mermaid.client.test.tsx
 create mode 100644 src/lib/mermaid.ts
 create mode 100644 src/lib/sanitize.ts
 create mode 100644 vitest.setup.ts

diff --git a/.dependency-cruiser.cjs b/.dependency-cruiser.cjs
index 35f5dd564..88fb383e6 100644
--- a/.dependency-cruiser.cjs
+++ b/.dependency-cruiser.cjs
@@ -16,12 +16,14 @@ module.exports = {
         //   - electron/mcp/validation.ts — string-only branch/UUID validators; the renderer
         //     shares them so it never offers a branch the IPC layer would reject
         //   - electron/shared/ — renderer-safe constants/pure helpers (no Node/Electron imports)
+        //   - electron/documents/shared.ts — agent ids/labels the document workspace shows
         pathNot: [
           '^electron/ipc/channels\\.ts',
           '^electron/mcp/prompt-detect\\.ts',
           '^electron/mcp/validation\\.ts',
           '^electron/agent-hooks/status\\.ts',
           '^electron/shared/',
+          '^electron/documents/shared\\.ts',
         ],
       },
     },
diff --git a/.gitignore b/.gitignore
index 7d5ed2181..ff871a58d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ update-test/
 # Keep generated docs content ignored, but track the authored architecture overview.
 docs/*
 !docs/architecture-overview.html
+!docs/document-workspaces.md
 
 # Sandbox bind-mount artifacts from user home (not project files).
 # Root-anchored so legitimate nested files with these names are still tracked.
diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
new file mode 100644
index 000000000..9b0203edf
--- /dev/null
+++ b/docs/document-workspaces.md
@@ -0,0 +1,314 @@
+# Document Workspaces
+
+**A project type in Parallel Code for exploring problems in prose**
+
+Status: experimental, behind the _Document workspaces_ switch in Settings → Experimental.
+Slices 1 to 4 of the plan below are built (the loop, comparison, annotations, HTML pages).
+
+Parallel Code already runs several agents against the same codebase and keeps the results
+isolated, attributable, and comparable. Document Workspaces applies the same machine to
+writing and thinking: architecture notes, specs, ADRs, research. Several agents get the
+same passage and the same base version. You read the alternatives and decide what enters
+the document.
+
+```
+                    ┌──────────────  Claude Code  ──────────────●  accepted
+                    │                                            \
+   ────────●  base ─┤                                             ●──────
+                    │                                            /
+                    └──────────────  Codex  ───────────────○  discarded
+```
+
+## What is built
+
+### Using it
+
+1. Enable _Document workspaces_ under Settings → Experimental.
+2. Click **+** next to Projects and choose **Document project…**. Type or browse to a
+   folder and name the project; a new Markdown document is named after it. Start with a
+   spec, architecture decision, or design note. Existing Markdown and HTML documents can
+   still be opened from the folder list. Neither has to exist: type a new name onto
+   the end of the path and that folder is the project. A folder that already holds
+   documents lists them, to open one of those instead. The dialog says what it will do —
+   create the folder, `git init`, create the file, make the first commit — and does it on
+   confirm.
+3. The workspace opens full-window with two tabs, **Document** and **History**; comparing
+   proposals happens in a modal over either.
+   A **Files** tab in the right panel lists every file of the project; click one to open
+   it, and click a relative link inside a document to follow it to the file (and heading)
+   it points at. Web links open in the browser. The history, the composer and the runs
+   follow the open document.
+4. The composer is a popover over the prose, never inside it, and is always there: with
+   nothing picked it rests at the foot of the column, acts on the whole document, and fades
+   back while you read. Select text, click a block, or press **§** next to a heading to
+   narrow it to a passage: it moves right under the passage (above it when the foot is
+   close), at full strength and with the cursor in it, and follows the passage as you
+   scroll. It steps back once you leave it. Type an instruction and press Enter. Hovering a
+   block shows five icons in the gap just above it, clear of the prose so a click meant
+   for the passage cannot land on one, each named as you point at it: task, proposals,
+   note and ask pick the block and open the composer on that mode (its tabs carry the same
+   icons), and the pencil, set apart, opens the block's source for editing. The picked
+   block's icons step aside while the composer is up on it; the other blocks keep theirs,
+   so one click moves the composer to another block. The **×** in the composer's corner,
+   or Esc, lets go of the passage and returns it to the foot.
+   The composer's four tabs are the four things one does with a passage; **Task** and
+   **Proposals** are the same instruction sent two ways:
+   - **Task** types it into the long-running agent session on the right, which
+     works in the checkout as you watch. Its edits show up in the viewer as they land and
+     are committed as `Manual edits` before the next one-shot run.
+   - **Proposals** runs headless candidates in their own worktrees. Expand
+     **Agents and models** to choose agents and candidate counts. Each candidate gets a
+     **Model** field and, where the CLI has one, a **Reasoning** level, so one agent can run
+     its main session on one model and an
+     alternate on another; both are the CLI's defaults until you choose, and the choice is
+     remembered per project, agent and candidate.
+5. The right-hand panel has three tabs and a draggable seam (double-click it to reset the
+   width; the width is remembered). **Agent** is the interactive session in the app's
+   terminal, with a status chip that says _needs you_ while it waits for an answer; its
+   process survives closing the workspace, and **Restart**, or picking another agent,
+   starts it afresh. **Runs** lists the one-shot runs as they finish; click any candidate to
+   read everything it printed.
+   Runs that wait for a decision also appear as a strip over the agent, so nothing sits
+   unnoticed behind another tab. **Review** (one candidate) or **Compare** (several), or the
+   _n to review_ button in the header, opens the compare view as a large modal over the
+   workspace, with **Fullscreen** to fill the window: base on the left, candidates to the
+   right, each starting with its rationale. Accept one, reject all, or choose **Refine this candidate** and describe
+   what should change. A candidate with more than one change carries a checkbox beside each
+   of them: every change is kept until you clear its box, the passages you dropped recede
+   in place so you can still read what you turned down, and the button then says
+   **Accept n of m changes** and takes only those. **Preview result** shows the complete
+   document with the selected changes applied and declined passages restored from the base.
+   **Back to changes** preserves your choices. Acceptance waits for the combination to be
+   verified and is disabled if it cannot be combined cleanly. Refinement uses the same agent and model in a fresh isolated run,
+   starts from that candidate's content, and leaves the original proposal available.
+   The revision appears in Runs and still needs acceptance.
+6. **History** is `git log` for the document with the `Parallel-*` trailers parsed:
+   what changed, which agent, which instruction, which base. Show the diff or render the
+   older version. Revert any entry.
+7. **Annotations.** The same composer offers **Note** and **Ask** beside **Task**. A note
+   attaches to the passage as a symbol in its margin; hover it, tab to it, or click it to
+   pin it open, and the bubble opens over the document. A question is a bubble an agent
+   answers into, running read-only in the checkout; question and answer stay visible
+   together. Resolve (`r`) collapses a bubble to one line, Delete removes it with an Undo
+   in the toolbar, and **Make task** reopens the composer on the passage with the bubble's
+   text (and answer) as the instruction; the bubble then collapses as `task`.
+
+8. **Edit a block.** Hover a block and click its pencil, or click the block and choose
+   **Edit block** in the toolbar. Edit its
+   Markdown or HTML source, then **Save block** to update the document directly. Surrounding
+   content and line endings are preserved. If the file changed meanwhile, saving refuses
+   to overwrite it and keeps your text available to copy.
+
+### How it works
+
+- **Editing happens in the block editor, your editor, or the interactive session.** The app
+  watches the open file and re-renders; an external change drops any active selection. The session
+  on the Agent tab is an ordinary terminal (`TerminalView`) running the chosen agent's
+  CLI in the checkout, one per project, keyed `doc-agent-<project>`; a scoped instruction
+  is pasted into it as _Document, Scope, the passage verbatim, your words_. Because it
+  edits the checkout directly, its work is committed as `Manual edits` by the next
+  one-shot dispatch rather than as a proposal to compare. A restart, or a switch to another
+  agent, spawns fresh instead of attaching: the spawn replaces the live session in one
+  step, so the new terminal never inherits the exit of the one it replaced.
+- **Every file of the project is one click away.** The file tree is `git ls-files`
+  (tracked and untracked, ignores respected) minus `.parallel/`, `.worktrees/` and `.git/`,
+  capped at 5,000 entries, refreshed on every new head. Opening a file swaps the watcher
+  and the snapshot; annotations are filtered to the open file's path, and runs against
+  other documents say which. Links resolve against the open document's folder, never
+  above the project root.
+- **Output is kept.** Each candidate's readable log is appended to
+  `.parallel/logs/<run>/<candidate>.log` as it streams (the rail shows the tail); the
+  folder is git-excluded through `.git/info/exclude`. The output dialog reads it back,
+  capped at the last 2 MB, and re-reads every second while the candidate runs.
+- **Dispatch commits pending edits first** as a plain `Manual edits` commit so every run
+  has a real base. Only tracked files count as pending edits: untracked scratch files
+  and everything under `.parallel/` stay out of that commit.
+- **Headless agents.** Each candidate runs the official CLI in print mode inside its own
+  worktree under `.worktrees/parallel-doc/`: `claude -p --output-format stream-json`
+  with tools limited to Read/Edit/Write/Glob/Grep, `codex exec --json --sandbox
+workspace-write` (the sandbox blocks writes outside the worktree),
+  `gemini -p --output-format json --approval-mode auto_edit` (`plan`, Gemini's read-only
+  mode, for annotation questions). Process exit means the
+  proposal is ready. Cancelling kills the CLI's whole process group. OpenCode and Copilot
+  expose an unrestricted shell in print mode and are not offered until they can be
+  restricted. A model or reasoning level chosen in the composer goes to the CLI as
+  `claude --model … --effort …`, `codex --model … -c model_reasoning_effort=…` or
+  `gemini --model …`, is kept on the candidate in the run record, and lands in the
+  `Parallel-Model` and `Parallel-Effort` trailers of the proposal and integration commits.
+- **The main session stays warm.** One agent owns the project's main session (choose it in
+  the composer). Its worktree is persistent (`.worktrees/parallel-doc-main`) so the working
+  directory, and with it the provider's prompt cache, never changes; each run resumes the
+  session by id (`claude --resume`, `codex exec resume`). After the canonical document
+  moves, the next prompt to that session carries the diff since it last saw the file.
+  Other agents, and extra candidates from the main agent, are one-shot alternates. While
+  the main session is working, a new run can only use alternates.
+- **Scope is enforced, not trusted.** Files the agent touched or staged outside the
+  document are reverted before the proposal commit and listed on the candidate; the
+  proposal commit is verified to contain the document alone. Hunks inside the document
+  but outside the selected passage are counted and flagged.
+- **Structured rationale.** Every prompt asks the agent to end with a JSON block:
+  summary, changes, assumptions, questions, warnings. It opens each candidate in the
+  compare view and becomes the commit message.
+- **One proposal commit per candidate** on a `parallel-doc/<run>-<label>` branch, carrying
+  `Parallel-Run`, `Parallel-Agent`, `Parallel-Candidate`, `Parallel-Scope` and
+  `Parallel-Base` trailers.
+- **Refinement keeps the canonical base.** A new isolated worktree starts at the original
+  run's base, then receives the selected candidate's document before the agent starts.
+  The new proposal therefore includes both the original changes and the refinement;
+  accepting it uses the existing three-way integration. The run records its source run
+  and candidate in `refinement`. Refinement covers the whole proposal because passage
+  line numbers may have changed. Dispatch does not commit pending canonical edits.
+- **Acceptance is one squashed integration commit** on the checked-out branch, containing
+  the document and the run record `.parallel/runs/<id>.json`. A proposal whose base is
+  behind HEAD is merged three-way on acceptance and marked stale if it no longer applies.
+- **Partial acceptance composes rather than merges.** Changes are grouped into hunks — a
+  run of base blocks and the run of candidate blocks replacing it, so an insertion has no
+  base blocks and a deletion no candidate ones. The renderer splices the base and the
+  candidate at their recorded block offsets, verifying each block still matches the text
+  those offsets describe, and sends the result as content; the commit carries a
+  `Parallel-Partial: n/m changes` trailer and the run records the counts. Splicing text is
+  not the same as splicing structure — markdown separates blocks by a blank line but not
+  always by two newlines, so a heading and its paragraph sit on consecutive lines — so each
+  seam of a spliced passage is opened to a blank line and the result is parsed back and
+  compared, block for block, against the passages the reader picked. A composition that
+  does not re-read as those blocks is refused rather than written. Because the composition
+  is made from the base, it is written only while the document itself has not moved since;
+  otherwise the run is marked stale, as a hand-picked mix has no side for a three-way merge
+  to take each declined passage from. Main verifies as well as trusts: it re-reads the base
+  and the candidate from their commits and refuses content that is not a mix of the two, so
+  a composition the renderer got wrong cannot reach the file. Two removals can want the same
+  checkbox — the last block of a document takes every deletion that ends it — so a block
+  carries a stack of them rather than dropping the second and leaving a change nobody can
+  decline. Keeping every change is still the ordinary git path, untouched. HTML pages are
+  accepted whole: their blocks are elements of a parsed page, not spans the composer can
+  splice back together.
+  Rejection commits the run record alone, so the history view (which excludes `.parallel/`)
+  never shows it. Reverting from the history view undoes a commit's content and keeps the
+  run records, with a `Parallel-Revert` trailer.
+- **Run records are checked on load.** They travel with the repository, so a clone can
+  carry records written elsewhere. Worktree paths, branch names and commit hashes are
+  validated against what this app would have produced before they reach git or the
+  filesystem; a record that fails is ignored.
+- **Compare view** renders base and candidates with the same renderer, marks changed,
+  added and removed blocks at block granularity, navigates by changed block, and hides
+  agent identity until you toggle _Show agents_. _Source diff_ swaps the rendering for the
+  unified diff. Each candidate has a free-text note stored in the run record.
+- **Anchors stay out of the prose.** An annotation records path, base commit, lines, the
+  exact quote, the neighbouring text and the nearest heading in
+  `.parallel/annotations.json` (`version: 1`). On every version the app relocates it by
+  quote; failing that — the normal case here, since an accepted proposal rewords the very
+  passage a note hangs on — by similarity, a Sørensen–Dice score over word bigrams, with
+  neighbours, heading and the recorded lines breaking ties. The two recorded neighbours also
+  bracket where the passage can be: a candidate reaching the block that followed the note
+  has passed its end, one reaching back to the block that preceded it has not arrived at its
+  start, and either way it is the section next door rather than the passage. That is what
+  keeps a note detached when its own section is dropped and a sibling worded almost the same
+  survives — and what lets the note follow its passage when the two sections swap places. A passage too unlike the quote, or no further ahead than an unrelated one, shows
+  as **detached** rather than being attached to the wrong place. Annotations are committed
+  along with the next content or metadata commit, never on their own.
+- **Run records are versioned** (`version: 1`) so a format change is a migration.
+- **Setup is part of the feature.** Creating a project runs whatever is missing — the
+  folder, `git init`, the starter document, the first commit — so the workspace never opens
+  on a folder its own dispatch would reject. Every step is skipped when it is already true,
+  and the commit takes the document alone, leaving anything you had staged staged.
+- **HTML pages are worked on as pages.** A document that starts with a doctype or `<html>`
+  is parsed with parse5 and rendered inline as itself: the body's markup stays whole, so
+  its own layout holds, and the innermost block-level elements (a paragraph, a heading, a
+  list, a table; not the `<main>` or `<div>` around them) are marked as the blocks. The
+  page's stylesheet comes along, scoped to the viewer with `@scope`, `html`/`body` rules
+  pointed at the page root, the app's annotation markers kept out of it, scripts and
+  `@import` dropped. Every block carries its source lines, so selection, the composer,
+  annotations, compare marking and history work on the rendered page exactly as on
+  Markdown; marks are outlines and markers hang out of the page's flow, so nothing the
+  app adds moves the page's own elements. A **Page** toggle
+  shows the sandboxed iframe render for pages that lean on scripts or external
+  stylesheets, which the inline view does not follow.
+- **It lives in two folders.** `electron/documents/` holds the runs, agents, prompts,
+  annotations, setup, IPC shapes and the registrar for every channel it owns;
+  `src/documents/` holds the UI with its store, types and markdown helpers. The seams are
+  `registerDocumentHandlers(win)` and `stopAllDocumentWork()` in main,
+  `<DocumentWorkspaceOverlay />` in `App.tsx`, and the sidebar's project row and `+` menu.
+  The one runtime module the renderer imports across the process boundary is
+  `electron/documents/shared.ts`.
+
+### Not in this slice
+
+Evaluator agents, threaded annotations, rich-text editing,
+external stylesheets and images in HTML pages. Custom agents, OpenCode and
+Copilot cannot be picked. Gemini runs one-shot only. Non-document files open in the viewer
+as Markdown, so a source file renders as prose rather than as code. The interactive
+session's edits are not proposals: they are not compared, and the compare view never sees
+them.
+
+---
+
+## The plan
+
+### The constraint that shapes the compare view
+
+**Restructuring is the normal case, not the edge case.** Agents rewrite whole paragraphs by
+default, so line diffs on prose are noise from the first day. The cheap answer is not
+semantic diffing. It is requiring every proposal to return a structured account of itself:
+what changed, why, what it assumed, what it could not resolve.
+
+### Core concepts
+
+- **Document project.** A Git repository holding one or more related documents plus
+  sources, assets, annotations, and run metadata under `.parallel/`.
+- **Canonical document.** The checked-out branch is the state you see. No agent changes it
+  except through an explicit acceptance action. You change it whenever you like.
+- **Scope.** Every task carries an explicit scope: a selection, a section, a document, the
+  project. Scope is a guardrail; out-of-scope changes are flagged rather than trusted away.
+- **Main session and alternates.** One long-lived main session per project holds context
+  and is the default target. Other agents spawn alternates from the same base for one task.
+  The main session has no special write rights, and after every accepted change it is
+  handed the resulting diff.
+- **Proposal.** A Git-backed result carrying its base commit, agent, instruction, scope,
+  resulting commit, structured rationale, and open questions. A proposal whose base is no
+  longer HEAD is stale.
+
+### The loop
+
+1. Open a document project. 2. Read the rendered document. 3. Select a passage, section,
+   or document. 4. Write an instruction. 5. Pick agents. 6. Each candidate gets a worktree from
+   the same base. 7. Agents return a proposal with rationale and questions. 8. Compare against
+   the base and each other. 9. Accept one, refine, or reject everything. 10. The result lands as
+   one readable commit, revertible through Git.
+
+### Compare view
+
+Judged on time-to-decision, not on how much it displays. Rationale first, rendered
+candidates side by side, changed blocks marked at block granularity, source diff as a
+toggle, navigation by changed passage, model-blind by default.
+
+### Git and history
+
+Git holds the content; Parallel Code adds provenance a person can read. One worktree and
+branch per candidate, one proposal commit per result, one squashed integration commit per
+acceptance, run metadata under `.parallel/runs/`. The history view is derived from Git plus
+run records at read time. No separate event log.
+
+### Security model
+
+Official CLI processes, so subscriptions and local config keep working. Repositories,
+prompts and diffs stay local except where the chosen provider receives them. Modifying
+tasks run in isolated worktrees with explicit scopes and no shell tools. Nothing is
+integrated without an explicit acceptance.
+
+### After this slice
+
+Further HTML work, research roles and evaluator agents are deferred until the Markdown
+selection → proposals → comparison → acceptance loop proves useful in real writing tasks.
+The items below are possibilities, not commitments for the next iteration.
+
+1. Annotations: bubbles on anchors, agent-answered questions, single-keypress dismissal.
+2. HTML: the page rendered inline as element blocks with source mapping.
+3. Durable anchors and selective integration; research projects with sources and roles;
+   semantic comparison by claim and decision.
+
+### Kill criteria
+
+Judging candidates takes longer than writing the passage yourself, or you find yourself
+accepting the first candidate without reading the rest. Either means the comparison loop
+does not hold for prose, and the answer is to stop rather than to add roles, formats, or
+evaluator agents.
diff --git a/electron/documents/agents.test.ts b/electron/documents/agents.test.ts
new file mode 100644
index 000000000..44cb13edd
--- /dev/null
+++ b/electron/documents/agents.test.ts
@@ -0,0 +1,244 @@
+import { describe, expect, it } from 'vitest';
+import { buildHeadlessLaunch, createHeadlessParser, CLAUDE_DOCUMENT_TOOLS } from './agents.js';
+
+describe('buildHeadlessLaunch', () => {
+  it('starts a fresh claude session with a fixed id and no shell tools', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'claude-code',
+      command: 'claude',
+      prompt: 'Do it',
+      newSessionId: 'sid-1',
+    });
+    expect(launch.command).toBe('claude');
+    expect(launch.args).toContain('--session-id');
+    expect(launch.args).toContain('sid-1');
+    expect(launch.args).not.toContain('--resume');
+    const toolsIdx = launch.args.indexOf('--tools');
+    expect(launch.args[toolsIdx + 1]).toBe(CLAUDE_DOCUMENT_TOOLS);
+    expect(launch.args).not.toContain('--dangerously-skip-permissions');
+  });
+
+  it('resumes claude by session id', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'claude-code',
+      command: 'claude',
+      prompt: 'Again',
+      sessionId: 'old',
+      newSessionId: 'new',
+    });
+    expect(launch.args).toContain('--resume');
+    expect(launch.args).toContain('old');
+    expect(launch.args).not.toContain('--session-id');
+  });
+
+  it('puts codex flags before the resume subcommand', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'codex',
+      command: 'codex',
+      prompt: 'P',
+      sessionId: 'thread-1',
+      newSessionId: 'x',
+    });
+    expect(launch.args.slice(0, 2)).toEqual(['exec', '--json']);
+    expect(launch.args.indexOf('resume')).toBeGreaterThan(launch.args.indexOf('--sandbox'));
+    expect(launch.args.slice(-2)).toEqual(['thread-1', 'P']);
+  });
+
+  it('ignores a session id for agents that cannot resume', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'gemini',
+      command: 'gemini',
+      prompt: 'P',
+      sessionId: 'ignored',
+      newSessionId: 'x',
+    });
+    expect(launch.args).not.toContain('ignored');
+  });
+
+  it('starts with the CLI defaults when no model or effort is chosen', () => {
+    for (const agentId of ['claude-code', 'codex', 'gemini']) {
+      const launch = buildHeadlessLaunch({ agentId, command: 'x', prompt: 'P', newSessionId: 's' });
+      expect(launch.args).not.toContain('--model');
+      expect(launch.args).not.toContain('--effort');
+      expect(launch.args).not.toContain('-c');
+    }
+  });
+
+  it('passes model and effort to claude', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'claude-code',
+      command: 'claude',
+      prompt: 'P',
+      newSessionId: 's',
+      model: 'opus',
+      effort: 'high',
+    });
+    expect(launch.args.indexOf('--model')).toBeGreaterThan(-1);
+    expect(launch.args[launch.args.indexOf('--model') + 1]).toBe('opus');
+    expect(launch.args[launch.args.indexOf('--effort') + 1]).toBe('high');
+  });
+
+  it('gives codex its model flag and effort override before the resume subcommand', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'codex',
+      command: 'codex',
+      prompt: 'P',
+      sessionId: 'thread-1',
+      newSessionId: 's',
+      model: 'gpt-5-codex',
+      effort: 'xhigh',
+    });
+    const resumeAt = launch.args.indexOf('resume');
+    expect(launch.args.indexOf('--model')).toBeLessThan(resumeAt);
+    expect(launch.args[launch.args.indexOf('--model') + 1]).toBe('gpt-5-codex');
+    const configAt = launch.args.indexOf('-c');
+    expect(configAt).toBeLessThan(resumeAt);
+    expect(launch.args[configAt + 1]).toBe('model_reasoning_effort="xhigh"');
+    expect(launch.args.slice(-2)).toEqual(['thread-1', 'P']);
+  });
+
+  it('passes a gemini model and drops the effort it has no flag for', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'gemini',
+      command: 'gemini',
+      prompt: 'P',
+      newSessionId: 's',
+      model: 'gemini-2.5-pro',
+      effort: 'high',
+    });
+    expect(launch.args[launch.args.indexOf('--model') + 1]).toBe('gemini-2.5-pro');
+    expect(launch.args).not.toContain('high');
+  });
+
+  it('rejects agents without a headless mode', () => {
+    expect(() =>
+      buildHeadlessLaunch({
+        agentId: 'antigravity',
+        command: 'agy',
+        prompt: 'P',
+        newSessionId: 'x',
+      }),
+    ).toThrow(/no headless mode/);
+  });
+});
+
+describe('claude stream-json parser', () => {
+  it('collects session id, tool log lines and the final result across chunks', () => {
+    const parser = createHeadlessParser('claude-code');
+    const lines = [
+      JSON.stringify({ type: 'system', subtype: 'init', session_id: 's1' }),
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          content: [
+            { type: 'text', text: 'Looking' },
+            { type: 'tool_use', name: 'Edit', input: { file_path: 'docs/a.md' } },
+          ],
+        },
+      }),
+      JSON.stringify({
+        type: 'result',
+        subtype: 'success',
+        result: 'Final ```json\n{}\n```',
+        session_id: 's1',
+      }),
+    ];
+    const joined = lines.join('\n') + '\n';
+    const log = [...parser.feed(joined.slice(0, 40)), ...parser.feed(joined.slice(40))];
+    expect(log).toEqual(['session started', 'Looking', '→ Edit docs/a.md']);
+    const outcome = parser.finish();
+    expect(outcome.sessionId).toBe('s1');
+    expect(outcome.resultText).toContain('Final');
+    expect(outcome.error).toBeUndefined();
+  });
+
+  it('surfaces an error result', () => {
+    const parser = createHeadlessParser('claude-code');
+    parser.feed(
+      JSON.stringify({ type: 'result', subtype: 'error', is_error: true, result: 'boom' }) + '\n',
+    );
+    expect(parser.finish().error).toBe('boom');
+  });
+
+  it('names the failure from errors or the subtype when the result is empty', () => {
+    const detailed = createHeadlessParser('claude-code');
+    detailed.feed(
+      JSON.stringify({
+        type: 'result',
+        subtype: 'error_during_execution',
+        is_error: true,
+        errors: ['rate limited'],
+      }) + '\n',
+    );
+    expect(detailed.finish().error).toBe('rate limited');
+
+    const bare = createHeadlessParser('claude-code');
+    bare.feed(
+      JSON.stringify({ type: 'result', subtype: 'error_max_turns', is_error: true }) + '\n',
+    );
+    expect(bare.finish().error).toBe('max turns');
+
+    const blank = createHeadlessParser('claude-code');
+    blank.feed(JSON.stringify({ type: 'result', subtype: 'error', is_error: true }) + '\n');
+    expect(blank.finish().error).toBe('agent reported an error');
+  });
+
+  it('passes non-json lines through and falls back to assistant text', () => {
+    const parser = createHeadlessParser('claude-code');
+    const log = parser.feed('warning: something\n');
+    expect(log).toEqual(['warning: something']);
+    parser.feed(
+      JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'T' }] } }),
+    );
+    expect(parser.finish().resultText).toBe('T');
+  });
+});
+
+describe('codex jsonl parser', () => {
+  it('reads the thread id, file changes and last agent message', () => {
+    const parser = createHeadlessParser('codex');
+    const events = [
+      { type: 'thread.started', thread_id: 't1' },
+      { type: 'item.completed', item: { type: 'agent_message', text: 'first' } },
+      {
+        type: 'item.completed',
+        item: { type: 'file_change', changes: [{ path: 'a.md', kind: 'update' }] },
+      },
+      { type: 'item.completed', item: { type: 'agent_message', text: 'last' } },
+      { type: 'turn.completed', usage: {} },
+    ];
+    const log = parser.feed(events.map((e) => JSON.stringify(e)).join('\n'));
+    expect(log).toEqual(['session started', 'first', '→ update a.md', 'last']);
+    const outcome = parser.finish();
+    expect(outcome.sessionId).toBe('t1');
+    expect(outcome.resultText).toBe('last');
+  });
+
+  it('records stream errors', () => {
+    const parser = createHeadlessParser('codex');
+    parser.feed(JSON.stringify({ type: 'error', message: 'quota' }) + '\n');
+    expect(parser.finish().error).toBe('quota');
+  });
+});
+
+describe('gemini and plain parsers', () => {
+  it('extracts the gemini response', () => {
+    const parser = createHeadlessParser('gemini');
+    parser.feed('{"response": "hello", ');
+    parser.feed('"session_id": "g1"}');
+    expect(parser.finish()).toEqual({ resultText: 'hello', sessionId: 'g1', error: undefined });
+  });
+
+  it('treats unparseable gemini output as text', () => {
+    const parser = createHeadlessParser('gemini');
+    parser.feed('plain');
+    expect(parser.finish().resultText).toBe('plain');
+  });
+
+  it('keeps everything for plain-text agents', () => {
+    const parser = createHeadlessParser('custom-agent');
+    const log = parser.feed('one\ntwo\n');
+    expect(log).toEqual(['one', 'two']);
+    expect(parser.finish().resultText).toBe('one\ntwo\n');
+  });
+});
diff --git a/electron/documents/agents.ts b/electron/documents/agents.ts
new file mode 100644
index 000000000..1e075b59f
--- /dev/null
+++ b/electron/documents/agents.ts
@@ -0,0 +1,331 @@
+/**
+ * Headless launches for document proposals: how each supported CLI is
+ * started in print mode, and how its output is turned into a readable log,
+ * a final message and a session id.
+ */
+import { documentAgentSupport } from './shared.js';
+
+export interface HeadlessLaunch {
+  command: string;
+  args: string[];
+}
+
+export interface HeadlessLaunchOptions {
+  agentId: string;
+  command: string;
+  prompt: string;
+  /** Session to resume; ignored when the agent cannot resume. */
+  sessionId?: string;
+  /** Session id to assign to a fresh Claude run so it can be resumed later. */
+  newSessionId: string;
+  /** Answering a question: the agent may read but never write. */
+  readOnly?: boolean;
+  /** Model to start with; the CLI's default when absent. */
+  model?: string;
+  /** Reasoning level; ignored for CLIs without such a flag. */
+  effort?: string;
+}
+
+export interface HeadlessOutcome {
+  resultText: string;
+  sessionId?: string;
+  /** Provider-reported error, when the stream carried one. */
+  error?: string;
+}
+
+/** Incremental parser over a CLI's stdout. */
+export interface HeadlessOutputParser {
+  /** Feed raw stdout; returns human-readable log lines to forward. */
+  feed(chunk: string): string[];
+  /** Flush and return the final outcome once the process exited. */
+  finish(): HeadlessOutcome;
+}
+
+/** Tools a document proposal may use: read and edit files, nothing that runs code. */
+export const CLAUDE_DOCUMENT_TOOLS = 'Read,Edit,Write,Glob,Grep';
+/** Tools for answering a question about a document: reading only. */
+export const CLAUDE_READ_ONLY_TOOLS = 'Read,Glob,Grep';
+
+export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch {
+  const support = documentAgentSupport(opts.agentId);
+  if (!support.headless) {
+    throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
+  }
+  const resume = support.resume && opts.sessionId ? opts.sessionId : undefined;
+
+  switch (opts.agentId) {
+    case 'claude-code': {
+      const args = [
+        '-p',
+        opts.prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        '--permission-mode',
+        opts.readOnly ? 'default' : 'acceptEdits',
+        '--tools',
+        opts.readOnly ? CLAUDE_READ_ONLY_TOOLS : CLAUDE_DOCUMENT_TOOLS,
+      ];
+      if (opts.model) args.push('--model', opts.model);
+      if (opts.effort) args.push('--effort', opts.effort);
+      if (resume) args.push('--resume', resume);
+      else args.push('--session-id', opts.newSessionId);
+      return { command: opts.command, args };
+    }
+    case 'codex': {
+      const args = [
+        'exec',
+        '--json',
+        '--sandbox',
+        opts.readOnly ? 'read-only' : 'workspace-write',
+        '--skip-git-repo-check',
+      ];
+      if (opts.model) args.push('--model', opts.model);
+      // Codex has no effort flag; the config override takes a TOML value.
+      if (opts.effort) args.push('-c', `model_reasoning_effort="${opts.effort}"`);
+      if (resume) args.push('resume', resume, opts.prompt);
+      else args.push(opts.prompt);
+      return { command: opts.command, args };
+    }
+    case 'gemini': {
+      const args = [
+        '-p',
+        opts.prompt,
+        '--output-format',
+        'json',
+        '--approval-mode',
+        // `plan` is Gemini's read-only mode; `default` would only withhold
+        // approval, which is a prompt nobody is there to decline.
+        opts.readOnly ? 'plan' : 'auto_edit',
+      ];
+      if (opts.model) args.push('--model', opts.model);
+      return { command: opts.command, args };
+    }
+    default:
+      throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
+  }
+}
+
+function tryParseJson(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('{')) return null;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function describeToolInput(name: string, input: unknown): string {
+  if (!input || typeof input !== 'object') return name;
+  const obj = input as Record<string, unknown>;
+  const target =
+    asString(obj.file_path) ?? asString(obj.path) ?? asString(obj.pattern) ?? asString(obj.command);
+  return target ? `${name} ${target}` : name;
+}
+
+/** Splits a stream into complete lines, keeping a partial tail between feeds. */
+class LineBuffer {
+  private tail = '';
+  push(chunk: string): string[] {
+    const data = this.tail + chunk;
+    const lines = data.split('\n');
+    this.tail = lines.pop() ?? '';
+    return lines;
+  }
+  flush(): string[] {
+    const rest = this.tail;
+    this.tail = '';
+    return rest.trim() ? [rest] : [];
+  }
+}
+
+/** Parser for `claude -p --output-format stream-json --verbose`. */
+class ClaudeStreamParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private sessionId?: string;
+  private result?: string;
+  private error?: string;
+  private lastAssistantText = '';
+
+  feed(chunk: string): string[] {
+    return this.lines.push(chunk).flatMap((line) => this.handle(line));
+  }
+
+  private handle(line: string): string[] {
+    const event = tryParseJson(line);
+    if (!event) return line.trim() ? [line] : [];
+    const sid = asString(event.session_id);
+    if (sid) this.sessionId = sid;
+
+    switch (event.type) {
+      case 'system':
+        return event.subtype === 'init' ? ['session started'] : [];
+      case 'assistant': {
+        const message = event.message as { content?: unknown } | undefined;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        const out: string[] = [];
+        for (const block of content as Record<string, unknown>[]) {
+          if (block.type === 'text' && typeof block.text === 'string') {
+            this.lastAssistantText = block.text;
+            out.push(block.text);
+          } else if (block.type === 'tool_use') {
+            out.push(`→ ${describeToolInput(asString(block.name) ?? 'tool', block.input)}`);
+          }
+        }
+        return out;
+      }
+      case 'result': {
+        const text = asString(event.result);
+        if (text) this.result = text;
+        if (event.is_error === true) {
+          // Newer CLIs put the detail in `errors` and only name the failure
+          // class in `subtype` (error_max_turns, error_during_execution).
+          const errors = Array.isArray(event.errors) ? event.errors.map(asString) : [];
+          const subtype =
+            asString(event.subtype)
+              ?.replace(/^error_?/, '')
+              .replace(/_/g, ' ') || undefined;
+          this.error =
+            text ??
+            asString(event.error) ??
+            errors.find(Boolean) ??
+            subtype ??
+            'agent reported an error';
+        }
+        return [];
+      }
+      default:
+        return [];
+    }
+  }
+
+  finish(): HeadlessOutcome {
+    const rest = this.lines.flush().flatMap((line) => this.handle(line));
+    void rest;
+    return {
+      resultText: this.result ?? this.lastAssistantText,
+      sessionId: this.sessionId,
+      error: this.error,
+    };
+  }
+}
+
+/** Parser for `codex exec --json` (JSONL thread events). */
+class CodexJsonlParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private threadId?: string;
+  private lastMessage = '';
+  private error?: string;
+
+  feed(chunk: string): string[] {
+    return this.lines.push(chunk).flatMap((line) => this.handle(line));
+  }
+
+  private handle(line: string): string[] {
+    const event = tryParseJson(line);
+    if (!event) return line.trim() ? [line] : [];
+
+    switch (event.type) {
+      case 'thread.started': {
+        const id = asString(event.thread_id);
+        if (id) this.threadId = id;
+        return ['session started'];
+      }
+      case 'item.completed': {
+        const item = (event.item ?? {}) as Record<string, unknown>;
+        switch (item.type) {
+          case 'agent_message': {
+            const text = asString(item.text) ?? '';
+            if (text) this.lastMessage = text;
+            return text ? [text] : [];
+          }
+          case 'file_change': {
+            const changes = Array.isArray(item.changes) ? item.changes : [];
+            return changes.map((c) => {
+              const change = c as Record<string, unknown>;
+              return `→ ${asString(change.kind) ?? 'edit'} ${asString(change.path) ?? ''}`.trim();
+            });
+          }
+          case 'command_execution':
+            return [`→ ran ${asString(item.command) ?? 'command'}`];
+          case 'error':
+            this.error = asString(item.message) ?? 'agent reported an error';
+            return [`error: ${this.error}`];
+          default:
+            return [];
+        }
+      }
+      case 'error': {
+        this.error = asString(event.message) ?? 'agent reported an error';
+        return [`error: ${this.error}`];
+      }
+      default:
+        return [];
+    }
+  }
+
+  finish(): HeadlessOutcome {
+    for (const line of this.lines.flush()) this.handle(line);
+    return { resultText: this.lastMessage, sessionId: this.threadId, error: this.error };
+  }
+}
+
+/** Parser for `gemini -p --output-format json`: a single JSON document with `response`. */
+class GeminiJsonParser implements HeadlessOutputParser {
+  private raw = '';
+
+  feed(chunk: string): string[] {
+    this.raw += chunk;
+    return [];
+  }
+
+  finish(): HeadlessOutcome {
+    const parsed = tryParseJson(this.raw);
+    if (parsed) {
+      const response = asString(parsed.response);
+      const error = parsed.error as Record<string, unknown> | undefined;
+      return {
+        resultText: response ?? '',
+        sessionId: asString(parsed.session_id),
+        error: error ? (asString(error.message) ?? 'agent reported an error') : undefined,
+      };
+    }
+    return { resultText: this.raw };
+  }
+}
+
+/** Plain-text fallback: everything is the final message. */
+class PlainTextParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private raw = '';
+
+  feed(chunk: string): string[] {
+    this.raw += chunk;
+    return this.lines.push(chunk).filter((l) => l.trim().length > 0);
+  }
+
+  finish(): HeadlessOutcome {
+    return { resultText: this.raw };
+  }
+}
+
+export function createHeadlessParser(agentId: string): HeadlessOutputParser {
+  switch (agentId) {
+    case 'claude-code':
+      return new ClaudeStreamParser();
+    case 'codex':
+      return new CodexJsonlParser();
+    case 'gemini':
+      return new GeminiJsonParser();
+    default:
+      return new PlainTextParser();
+  }
+}
diff --git a/electron/documents/annotations.test.ts b/electron/documents/annotations.test.ts
new file mode 100644
index 000000000..569db8f0d
--- /dev/null
+++ b/electron/documents/annotations.test.ts
@@ -0,0 +1,183 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import {
+  askAnnotation,
+  buildAnnotationPrompt,
+  deleteAnnotation,
+  readAnnotations,
+  saveAnnotation,
+  validateAnnotationInput,
+} from './annotations.js';
+import type { DocumentAnnotation, DocumentAnnotationEvent } from './types.js';
+
+const anchor = {
+  path: 'docs/spec.md',
+  baseSha: 'abcdef1234567',
+  startLine: 5,
+  endLine: 7,
+  quote: '## Goals\n\nOld goals text.',
+  prefix: 'Intro paragraph.',
+  suffix: '## Later',
+  heading: 'Goals',
+};
+
+function note(id: string, extra: Partial<DocumentAnnotation> = {}): Record<string, unknown> {
+  return {
+    id,
+    kind: 'note',
+    anchor,
+    text: `note ${id}`,
+    createdAt: '2026-01-01T00:00:00Z',
+    ...extra,
+  };
+}
+
+describe('validateAnnotationInput', () => {
+  it('normalizes a note', () => {
+    const a = validateAnnotationInput(note('n-1', { resolved: true }));
+    expect(a.kind).toBe('note');
+    expect(a.resolved).toBe(true);
+    expect(a.anchor.heading).toBe('Goals');
+    expect(a.answer).toBeUndefined();
+  });
+  it('rejects bad ids, kinds, anchors and shas', () => {
+    expect(() => validateAnnotationInput(note('bad id!'))).toThrow(/id/);
+    expect(() => validateAnnotationInput({ ...note('n-1'), kind: 'task' })).toThrow(/kind/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, startLine: 9, endLine: 2 } }),
+    ).toThrow(/lines/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, baseSha: 'HEAD' } }),
+    ).toThrow(/baseSha/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, path: '../x.md' } }),
+    ).toThrow();
+  });
+  it('drops unknown statuses and run ids', () => {
+    const a = validateAnnotationInput({ ...note('n-1'), answerStatus: 'weird', runId: 'bad id' });
+    expect(a.answerStatus).toBeUndefined();
+    expect(a.runId).toBeUndefined();
+  });
+});
+
+describe('buildAnnotationPrompt', () => {
+  it('quotes the passage and forbids edits', () => {
+    const prompt = buildAnnotationPrompt(
+      validateAnnotationInput({ ...note('q-1'), kind: 'question', text: 'Why?' }),
+    );
+    expect(prompt).toContain('Document: docs/spec.md');
+    expect(prompt).toContain('lines 5-7 (under "Goals")');
+    expect(prompt).toContain('> Old goals text.');
+    expect(prompt).toContain('Question:\nWhy?');
+    expect(prompt).toContain('Do not edit');
+  });
+});
+
+describe('annotations file and asking', () => {
+  let root: string;
+  let fakeAgent: string;
+  const events: DocumentAnnotationEvent[] = [];
+  const win = {
+    isDestroyed: () => false,
+    webContents: { send: (_ch: string, payload: DocumentAnnotationEvent) => events.push(payload) },
+  } as unknown as BrowserWindow;
+
+  beforeAll(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-'));
+    const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-bin-'));
+    fakeAgent = path.join(binDir, 'fake-claude.sh');
+    fs.writeFileSync(
+      fakeAgent,
+      [
+        '#!/bin/sh',
+        // Prove read-only tools were requested and answer.
+        'case "$*" in *"Read,Glob,Grep"*) ;; *) echo "wrong tools" >&2; exit 2;; esac',
+        'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"s","result":"The passage assumes **nothing**."}\'',
+      ].join('\n') + '\n',
+      { mode: 0o755 },
+    );
+  });
+
+  afterAll(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('round-trips annotations and keeps a pending answer across edits', async () => {
+    expect(readAnnotations(root)).toEqual([]);
+    await saveAnnotation(root, note('a-1'));
+    await saveAnnotation(root, note('a-2', { kind: 'question', text: 'Why?' }));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-1', 'a-2']);
+    expect(fs.existsSync(path.join(root, '.parallel', 'annotations.json'))).toBe(true);
+
+    const edited = await saveAnnotation(root, { ...note('a-1'), text: 'edited', resolved: true });
+    expect(edited.text).toBe('edited');
+    expect(readAnnotations(root)[0].createdAt).toBe('2026-01-01T00:00:00Z');
+
+    await deleteAnnotation(root, 'a-1');
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('skips malformed entries instead of losing the file', async () => {
+    const file = path.join(root, '.parallel', 'annotations.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as { annotations: unknown[] };
+    raw.annotations.push({ id: 'bad', kind: 'note' });
+    fs.writeFileSync(file, JSON.stringify(raw));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('asks a read-only agent and stores the answer in the bubble', async () => {
+    const pending = await askAnnotation(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      annotationId: 'a-2',
+      agentId: 'claude-code',
+      agentName: 'Fake Claude',
+      command: fakeAgent,
+    });
+    expect(pending.answerStatus).toBe('pending');
+    const answered = await new Promise<DocumentAnnotation>((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = events.find(
+          (e) => e.annotation.id === 'a-2' && e.annotation.answerStatus !== 'pending',
+        );
+        if (done) return resolve(done.annotation);
+        if (Date.now() - started > 10_000) return reject(new Error('no answer'));
+        setTimeout(tick, 50);
+      };
+      tick();
+    });
+    expect(answered.answerStatus).toBe('answered');
+    expect(answered.answer?.text).toContain('assumes **nothing**');
+    expect(answered.answer?.agentName).toBe('Fake Claude');
+    expect(readAnnotations(root)[0].answer?.text).toContain('nothing');
+    // Question and answer both survive: the question text is untouched.
+    expect(readAnnotations(root)[0].text).toBe('Why?');
+  });
+
+  it('refuses agents without a headless mode and unknown annotations', async () => {
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'a-2',
+        agentId: 'opencode',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/no headless mode/);
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'missing-1',
+        agentId: 'claude-code',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/not found/);
+  });
+});
diff --git a/electron/documents/annotations.ts b/electron/documents/annotations.ts
new file mode 100644
index 000000000..d9d0ab8a6
--- /dev/null
+++ b/electron/documents/annotations.ts
@@ -0,0 +1,400 @@
+/**
+ * Annotations for document workspaces: notes and agent-answered questions
+ * anchored to a passage. They sit beside the document and never modify it,
+ * which makes them the safe way to interrogate a draft.
+ */
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import { errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { documentAgentSupport } from './shared.js';
+import { validateDocumentPath, validateSha } from './runs.js';
+import type {
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationsFile,
+} from './types.js';
+
+export const ANNOTATIONS_REL_PATH = path.posix.join('.parallel', 'annotations.json');
+const MAX_TEXT_CHARS = 20_000;
+const MAX_ANSWER_CHARS = 50_000;
+const MAX_ANNOTATIONS = 2_000;
+const ANSWER_TIMEOUT_MS = 10 * 60_000;
+const KILL_GRACE_MS = 5_000;
+
+function annotationsPath(projectRoot: string): string {
+  return path.join(projectRoot, ANNOTATIONS_REL_PATH);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+// --- Validation -----------------------------------------------------------
+
+function validateAnnotationId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{1,64}$/i.test(value))
+    throw new Error('annotation id is invalid');
+  return value;
+}
+
+function text(value: unknown, label: string, max = MAX_TEXT_CHARS): string {
+  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
+  return value.slice(0, max);
+}
+
+function validateAnchor(value: unknown): DocumentAnchor {
+  if (!value || typeof value !== 'object') throw new Error('anchor must be an object');
+  const a = value as Record<string, unknown>;
+  const startLine = Number(a.startLine);
+  const endLine = Number(a.endLine);
+  if (
+    !Number.isInteger(startLine) ||
+    !Number.isInteger(endLine) ||
+    startLine < 1 ||
+    endLine < startLine
+  )
+    throw new Error('anchor lines are invalid');
+  const baseSha =
+    a.baseSha === null || a.baseSha === undefined ? null : validateSha(a.baseSha, 'anchor.baseSha');
+  const heading =
+    typeof a.heading === 'string' && a.heading.trim() ? a.heading.slice(0, 300) : undefined;
+  return {
+    path: validateDocumentPath(a.path),
+    baseSha,
+    startLine,
+    endLine,
+    quote: text(a.quote, 'anchor.quote'),
+    prefix: text(a.prefix, 'anchor.prefix', 500),
+    suffix: text(a.suffix, 'anchor.suffix', 500),
+    heading,
+  };
+}
+
+/** Accepts what the renderer sends for a new or edited annotation. */
+export function validateAnnotationInput(value: unknown): DocumentAnnotation {
+  if (!value || typeof value !== 'object') throw new Error('annotation must be an object');
+  const v = value as Record<string, unknown>;
+  const kind = v.kind === 'question' ? 'question' : v.kind === 'note' ? 'note' : null;
+  if (!kind) throw new Error('annotation kind is invalid');
+  const id = validateAnnotationId(v.id);
+  const answer =
+    v.answer && typeof v.answer === 'object'
+      ? {
+          text: text((v.answer as Record<string, unknown>).text, 'answer.text', MAX_ANSWER_CHARS),
+          agentId: text((v.answer as Record<string, unknown>).agentId, 'answer.agentId', 64),
+          agentName: text((v.answer as Record<string, unknown>).agentName, 'answer.agentName', 64),
+          answeredAt: text(
+            (v.answer as Record<string, unknown>).answeredAt,
+            'answer.answeredAt',
+            64,
+          ),
+        }
+      : undefined;
+  const status = v.answerStatus;
+  const runId =
+    typeof v.runId === 'string' && /^[a-z0-9-]{1,64}$/i.test(v.runId) ? v.runId : undefined;
+  return {
+    id,
+    kind,
+    anchor: validateAnchor(v.anchor),
+    text: text(v.text, 'text'),
+    createdAt: typeof v.createdAt === 'string' ? v.createdAt.slice(0, 64) : nowIso(),
+    updatedAt: nowIso(),
+    resolved: v.resolved === true,
+    answer,
+    answerStatus:
+      status === 'pending' || status === 'answered' || status === 'failed' ? status : undefined,
+    answerError: typeof v.answerError === 'string' ? v.answerError.slice(0, 2_000) : undefined,
+    runId,
+  };
+}
+
+// --- File -----------------------------------------------------------------
+
+export function readAnnotations(projectRoot: string): DocumentAnnotation[] {
+  try {
+    const raw = JSON.parse(fs.readFileSync(annotationsPath(projectRoot), 'utf-8')) as unknown;
+    if (!raw || typeof raw !== 'object') return [];
+    const file = raw as Partial<DocumentAnnotationsFile>;
+    if (file.version !== 1 || !Array.isArray(file.annotations)) return [];
+    const out: DocumentAnnotation[] = [];
+    for (const entry of file.annotations) {
+      try {
+        const valid = validateAnnotationInput(entry);
+        // Keep the stored timestamp; validation stamps "now" for edits only.
+        valid.updatedAt =
+          typeof (entry as DocumentAnnotation).updatedAt === 'string'
+            ? (entry as DocumentAnnotation).updatedAt
+            : valid.updatedAt;
+        out.push(valid);
+      } catch {
+        // A malformed entry (hand-edited or from another tool) is skipped, not fatal.
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function writeAnnotations(projectRoot: string, annotations: DocumentAnnotation[]): void {
+  const file: DocumentAnnotationsFile = { version: 1, annotations };
+  fs.mkdirSync(path.dirname(annotationsPath(projectRoot)), { recursive: true });
+  atomicWriteFileSync(annotationsPath(projectRoot), JSON.stringify(file, null, 2) + '\n');
+}
+
+const fileLocks = new Map<string, Promise<void>>();
+
+function withFileLock<T>(projectRoot: string, fn: () => T | Promise<T>): Promise<T> {
+  const key = path.resolve(projectRoot);
+  const prev = fileLocks.get(key) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  fileLocks.set(
+    key,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+export function saveAnnotation(projectRoot: string, input: unknown): Promise<DocumentAnnotation> {
+  const annotation = validateAnnotationInput(input);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const idx = all.findIndex((a) => a.id === annotation.id);
+    if (idx >= 0) {
+      // A pending answer belongs to the running ask, not to the edit.
+      const stored = all[idx];
+      if (stored.answerStatus === 'pending' && annotation.answerStatus !== 'pending') {
+        annotation.answer = stored.answer;
+        annotation.answerStatus = stored.answerStatus;
+      }
+      annotation.createdAt = stored.createdAt;
+      all[idx] = annotation;
+    } else {
+      if (all.length >= MAX_ANNOTATIONS) throw new Error('Too many annotations in this project.');
+      all.push(annotation);
+    }
+    writeAnnotations(projectRoot, all);
+    return annotation;
+  });
+}
+
+export function deleteAnnotation(projectRoot: string, idRaw: unknown): Promise<void> {
+  const id = validateAnnotationId(idRaw);
+  cancelAsk(id);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    writeAnnotations(
+      projectRoot,
+      all.filter((a) => a.id !== id),
+    );
+  });
+}
+
+function updateAnnotation(
+  projectRoot: string,
+  id: string,
+  mutate: (a: DocumentAnnotation) => void,
+): Promise<DocumentAnnotation | null> {
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const target = all.find((a) => a.id === id);
+    if (!target) return null;
+    mutate(target);
+    target.updatedAt = nowIso();
+    writeAnnotations(projectRoot, all);
+    return target;
+  });
+}
+
+// --- Asking an agent ------------------------------------------------------
+
+export interface AskAnnotationArgs {
+  projectRoot: string;
+  documentPath: unknown;
+  annotationId: unknown;
+  agentId: unknown;
+  agentName: unknown;
+  command: unknown;
+  envFile?: unknown;
+}
+
+interface ActiveAsk {
+  proc: ChildProcess;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const activeAsks = new Map<string, ActiveAsk>();
+
+/** Builds the read-only question prompt. Exported for tests. */
+export function buildAnnotationPrompt(annotation: DocumentAnnotation): string {
+  const a = annotation.anchor;
+  const where = a.heading
+    ? `lines ${a.startLine}-${a.endLine} (under "${a.heading}")`
+    : `lines ${a.startLine}-${a.endLine}`;
+  const quote = a.quote
+    .split('\n')
+    .map((l) => `> ${l}`)
+    .join('\n');
+  return [
+    'You are answering a question about a document in a Parallel Code document workspace. ' +
+      'Read the document (and anything else in the project you need) but do not modify any file.',
+    `Document: ${a.path}`,
+    `Passage: ${where}\n${quote}`,
+    `Question:\n${annotation.text.trim()}`,
+    [
+      'Rules:',
+      '- Answer the question about this passage directly and concisely, in Markdown.',
+      '- Quote the document where it supports your answer; say plainly when it does not.',
+      '- Do not rewrite the passage unless the question asks for a rewrite, and then show it as a suggestion.',
+      '- Do not edit, create or delete files, and do not run commands.',
+    ].join('\n'),
+  ].join('\n\n');
+}
+
+function killAsk(entry: ActiveAsk): void {
+  const pid = entry.proc.pid;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      if (pid) process.kill(-pid, sig);
+      else entry.proc.kill(sig);
+    } catch {
+      // Already gone.
+    }
+  };
+  signal('SIGTERM');
+  setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS).unref?.();
+}
+
+export function cancelAsk(annotationId: string): void {
+  const entry = activeAsks.get(annotationId);
+  if (!entry) return;
+  clearTimeout(entry.timer);
+  activeAsks.delete(annotationId);
+  killAsk(entry);
+}
+
+export function stopAllAsks(): void {
+  for (const id of [...activeAsks.keys()]) cancelAsk(id);
+}
+
+/**
+ * Runs a headless, read-only agent in the project checkout and writes its
+ * final message into the annotation. Progress is pushed as
+ * `IPC.DocumentAnnotationEvent`.
+ */
+export async function askAnnotation(
+  win: BrowserWindow,
+  args: AskAnnotationArgs,
+): Promise<DocumentAnnotation> {
+  const { projectRoot } = args;
+  validateDocumentPath(args.documentPath);
+  const annotationId = validateAnnotationId(args.annotationId);
+  const agentId = text(args.agentId, 'agentId', 64);
+  if (!documentAgentSupport(agentId).headless)
+    throw new Error(`Agent "${agentId}" has no headless mode for document questions.`);
+  const agentName = text(args.agentName, 'agentName', 64);
+  const command = text(args.command, 'command', 200);
+  if (!command.trim() || /[\s;&|<>$`'"\\]/.test(command)) throw new Error('command is invalid');
+  const envFile = args.envFile === undefined ? undefined : text(args.envFile, 'envFile', 1_000);
+  validateCommand(command);
+
+  cancelAsk(annotationId);
+  const annotation = await updateAnnotation(projectRoot, annotationId, (a) => {
+    a.kind = 'question';
+    a.answerStatus = 'pending';
+    a.answerError = undefined;
+  });
+  if (!annotation) throw new Error('Annotation not found');
+
+  const launch = buildHeadlessLaunch({
+    agentId,
+    command,
+    prompt: buildAnnotationPrompt(annotation),
+    newSessionId: randomUUID(),
+    readOnly: true,
+  });
+  const env = buildPtySpawnEnv({}, envFile?.trim() ? loadEnvFile(envFile) : {});
+  const parser = createHeadlessParser(agentId);
+  const proc = spawn(launch.command, launch.args, {
+    cwd: projectRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  proc.stdout?.setEncoding('utf8');
+  proc.stderr?.setEncoding('utf8');
+  let stderrTail = '';
+  proc.stdout?.on('data', (chunk: string) => void parser.feed(chunk));
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-4_000);
+  });
+
+  const entry: ActiveAsk = {
+    proc,
+    timer: setTimeout(() => {
+      stderrTail = 'Timed out.';
+      killAsk(entry);
+    }, ANSWER_TIMEOUT_MS),
+  };
+  activeAsks.set(annotationId, entry);
+
+  const emit = (a: DocumentAnnotation) => {
+    if (!win.isDestroyed()) {
+      const event: DocumentAnnotationEvent = { projectRoot, annotation: a };
+      win.webContents.send(IPC.DocumentAnnotationEvent, event);
+    }
+  };
+  emit(annotation);
+
+  let settled = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(entry.timer);
+    const wasActive = activeAsks.get(annotationId) === entry;
+    if (wasActive) activeAsks.delete(annotationId);
+    const outcome = parser.finish();
+    const failure =
+      spawnError?.message ??
+      outcome.error ??
+      (!outcome.resultText.trim()
+        ? stderrTail.trim() || `The agent exited with code ${exitCode ?? 'unknown'} and no answer.`
+        : undefined);
+    const updated = await updateAnnotation(projectRoot, annotationId, (a) => {
+      if (!wasActive) return; // cancelled or superseded: leave whatever the newer ask wrote
+      if (failure && !outcome.resultText.trim()) {
+        a.answerStatus = 'failed';
+        a.answerError = failure.slice(0, 2_000);
+      } else {
+        a.answerStatus = 'answered';
+        a.answerError = failure?.slice(0, 2_000);
+        a.answer = {
+          text: outcome.resultText.slice(0, MAX_ANSWER_CHARS),
+          agentId,
+          agentName,
+          answeredAt: nowIso(),
+        };
+      }
+    }).catch((err) => {
+      console.warn('[annotations] failed to store answer:', errMessage(err));
+      return null;
+    });
+    if (updated && wasActive) emit(updated);
+  };
+  proc.on('close', (code) => void settle(code));
+  proc.on('error', (err) => void settle(1, err));
+  return annotation;
+}
diff --git a/electron/documents/editing.test.ts b/electron/documents/editing.test.ts
new file mode 100644
index 000000000..3885a9f7c
--- /dev/null
+++ b/electron/documents/editing.test.ts
@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { readDocumentSnapshot, writeDocumentBlock } from './runs.js';
+
+const roots: string[] = [];
+function folder() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-doc-edit-'));
+  roots.push(root);
+  return root;
+}
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('writeDocumentBlock', () => {
+  it('changes only the selected source range and preserves file permissions', async () => {
+    const root = folder();
+    const expectedContent = '# Plan\r\n\r\nA typo.\r\n\r\nOther.\r\n';
+    const file = path.join(root, 'plan.md');
+    fs.writeFileSync(file, expectedContent, { mode: 0o640 });
+    const startOffset = expectedContent.indexOf('A typo.');
+    await writeDocumentBlock(root, {
+      documentPath: 'plan.md',
+      expectedContent,
+      startOffset,
+      endOffset: startOffset + 7,
+      replacement: 'A correction.',
+    });
+    expect(fs.readFileSync(file, 'utf8')).toBe(expectedContent.replace('A typo.', 'A correction.'));
+    expect(fs.statSync(file).mode & 0o777).toBe(0o640);
+  });
+
+  it('rejects an outdated editor without losing external changes', async () => {
+    const root = folder();
+    const file = path.join(root, 'plan.md');
+    fs.writeFileSync(file, 'Newer content');
+    await expect(
+      writeDocumentBlock(root, {
+        documentPath: 'plan.md',
+        expectedContent: 'Old content',
+        startOffset: 0,
+        endOffset: 3,
+        replacement: 'My',
+      }),
+    ).rejects.toThrow(/changed/);
+    expect(fs.readFileSync(file, 'utf8')).toBe('Newer content');
+  });
+
+  it('rejects invalid ranges, traversal, metadata paths, and symbolic links', async () => {
+    const root = folder();
+    const outside = folder();
+    fs.writeFileSync(path.join(root, 'plan.md'), 'Plan');
+    fs.writeFileSync(path.join(outside, 'plan.md'), 'Outside');
+    fs.symlinkSync(outside, path.join(root, 'linked'));
+    const args = {
+      documentPath: 'plan.md',
+      expectedContent: 'Plan',
+      startOffset: 0,
+      endOffset: 4,
+      replacement: 'Edit',
+    };
+    for (const documentPath of ['../plan.md', '.parallel/runs/test.json', 'linked/plan.md']) {
+      await expect(writeDocumentBlock(root, { ...args, documentPath })).rejects.toThrow();
+    }
+    for (const [startOffset, endOffset] of [
+      [-1, 1],
+      [2, 1],
+      [0, 5],
+      [0.5, 2],
+    ]) {
+      await expect(writeDocumentBlock(root, { ...args, startOffset, endOffset })).rejects.toThrow(
+        /range/,
+      );
+    }
+    expect(fs.readFileSync(path.join(root, 'plan.md'), 'utf8')).toBe('Plan');
+    expect(fs.readFileSync(path.join(outside, 'plan.md'), 'utf8')).toBe('Outside');
+  });
+});
+
+describe('readDocumentSnapshot', () => {
+  it('does not read a document through a symbolic link', async () => {
+    const root = folder();
+    const outside = folder();
+    fs.writeFileSync(path.join(outside, 'secret.md'), 'Not for the viewer');
+    fs.symlinkSync(path.join(outside, 'secret.md'), path.join(root, 'linked.md'));
+    const snapshot = await readDocumentSnapshot(root, 'linked.md');
+    expect(snapshot.content).toBe('');
+    expect(snapshot.missing).toBe(true);
+  });
+
+  it('reads a plain document under a project root that is itself a symlink', async () => {
+    const root = folder();
+    fs.writeFileSync(path.join(root, 'plan.md'), 'Real content');
+    const snapshot = await readDocumentSnapshot(root, 'plan.md');
+    expect(snapshot.content).toBe('Real content');
+    expect(snapshot.missing).toBe(false);
+  });
+});
diff --git a/electron/documents/files.test.ts b/electron/documents/files.test.ts
new file mode 100644
index 000000000..92738bad1
--- /dev/null
+++ b/electron/documents/files.test.ts
@@ -0,0 +1,39 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { listProjectFiles } from './files.js';
+
+const made: string[] = [];
+
+function tmpRepo(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docfiles-'));
+  made.push(dir);
+  execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+  return dir;
+}
+
+function write(dir: string, rel: string, content = 'x\n'): void {
+  fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+  fs.writeFileSync(path.join(dir, rel), content);
+}
+
+afterEach(() => {
+  while (made.length) fs.rmSync(made.pop() as string, { recursive: true, force: true });
+});
+
+describe('listProjectFiles', () => {
+  it('lists tracked and untracked files, sorted, without ignored or app-owned paths', async () => {
+    const dir = tmpRepo();
+    write(dir, 'notes.md');
+    write(dir, 'src/plan.md');
+    write(dir, 'build/out.txt');
+    write(dir, '.gitignore', 'build/\n');
+    write(dir, '.parallel/runs/r.json', '{}');
+    write(dir, '.worktrees/x/notes.md');
+    execFileSync('git', ['add', 'notes.md'], { cwd: dir });
+
+    expect(await listProjectFiles(dir)).toEqual(['.gitignore', 'notes.md', 'src/plan.md']);
+  });
+});
diff --git a/electron/documents/files.ts b/electron/documents/files.ts
new file mode 100644
index 000000000..4391df111
--- /dev/null
+++ b/electron/documents/files.ts
@@ -0,0 +1,27 @@
+/**
+ * The files of a document project, for the workspace's file tree. Git decides
+ * what counts: tracked files plus untracked ones that are not ignored, so
+ * scratch files show up but build output and the app's own folders do not.
+ */
+import { git } from './git.js';
+
+/** A tree beyond this is a code project, not a document project. */
+const MAX_FILES = 5_000;
+/** Folders the workspace owns or must never offer to open. */
+const HIDDEN_PREFIXES = ['.parallel/', '.worktrees/', '.git/'];
+
+export async function listProjectFiles(projectRoot: string): Promise<string[]> {
+  const out = await git(projectRoot, [
+    'ls-files',
+    '-z',
+    '--cached',
+    '--others',
+    '--exclude-standard',
+  ]);
+  const files = out
+    .split('\0')
+    .filter((p) => p && !HIDDEN_PREFIXES.some((prefix) => p.startsWith(prefix)));
+  // `--cached` and `--others` never overlap, but a path can be listed twice
+  // when the index holds a merge conflict; the tree wants each once.
+  return [...new Set(files)].sort().slice(0, MAX_FILES);
+}
diff --git a/electron/documents/git.ts b/electron/documents/git.ts
new file mode 100644
index 000000000..7ed8485bd
--- /dev/null
+++ b/electron/documents/git.ts
@@ -0,0 +1,24 @@
+/** The `git` invocation every document-workspace module shares. */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { debug as logDebug } from '../log.js';
+
+const execFileAsync = promisify(execFile);
+/** A document's history can be large; `git log -p` on it must not be truncated. */
+const MAX_BUFFER = 20 * 1024 * 1024;
+
+export async function git(cwd: string, args: string[]): Promise<string> {
+  logDebug('git', args.join(' '));
+  const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: MAX_BUFFER });
+  return stdout;
+}
+
+/** `git` for commands whose failure is an answer rather than an error. */
+export async function gitOk(cwd: string, args: string[]): Promise<boolean> {
+  try {
+    await git(cwd, args);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/electron/documents/logs.ts b/electron/documents/logs.ts
new file mode 100644
index 000000000..15304abc3
--- /dev/null
+++ b/electron/documents/logs.ts
@@ -0,0 +1,62 @@
+/**
+ * What a one-shot candidate printed, kept on disk so the output can be read
+ * after the run finished or the app restarted. Logs live under
+ * `.parallel/logs/` in the project, git-excluded: they are local output, not
+ * part of the record that travels with the repository.
+ */
+import fs from 'fs';
+import path from 'path';
+import { appendGitInfoExcludeBlock } from '../ipc/git-exclude.js';
+
+const LOGS_DIR = path.join('.parallel', 'logs');
+const EXCLUDE_HEADER = '# parallel-code: document run output';
+const EXCLUDE_PATTERN = '/.parallel/logs/';
+/** Longest log handed back to the renderer; the tail is what matters. */
+const MAX_READ_CHARS = 2_000_000;
+
+const ID_RE = /^[a-z0-9-]{1,64}$/i;
+
+function logPath(projectRoot: string, runId: string, candidateId: string): string {
+  if (!ID_RE.test(runId) || !ID_RE.test(candidateId)) throw new Error('log id is invalid');
+  return path.join(projectRoot, LOGS_DIR, runId, `${candidateId}.log`);
+}
+
+/** Keeps the logs folder out of the project's `git status`. */
+export function ensureDocumentLogsExclude(projectRoot: string): void {
+  appendGitInfoExcludeBlock(
+    projectRoot,
+    EXCLUDE_PATTERN,
+    `${EXCLUDE_HEADER}\n${EXCLUDE_PATTERN}\n`,
+    (err) => console.warn(`[documents] failed to git-exclude ${EXCLUDE_PATTERN}:`, err),
+  );
+}
+
+export function appendCandidateLog(
+  projectRoot: string,
+  runId: string,
+  candidateId: string,
+  line: string,
+): void {
+  try {
+    const file = logPath(projectRoot, runId, candidateId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, line.endsWith('\n') ? line : `${line}\n`);
+  } catch (err) {
+    console.warn('[documents] failed to write candidate log:', err);
+  }
+}
+
+/** The log so far; empty when the candidate printed nothing (or never ran here). */
+export function readCandidateLog(
+  projectRoot: string,
+  runId: unknown,
+  candidateId: unknown,
+): string {
+  if (typeof runId !== 'string' || typeof candidateId !== 'string') return '';
+  try {
+    const text = fs.readFileSync(logPath(projectRoot, runId, candidateId), 'utf-8');
+    return text.length > MAX_READ_CHARS ? text.slice(-MAX_READ_CHARS) : text;
+  } catch {
+    return '';
+  }
+}
diff --git a/electron/documents/prompt.test.ts b/electron/documents/prompt.test.ts
new file mode 100644
index 000000000..92bdfc1d8
--- /dev/null
+++ b/electron/documents/prompt.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+
+const scope = {
+  path: 'docs/spec.md',
+  wholeDocument: false,
+  startLine: 10,
+  endLine: 12,
+  quote: 'First line\nSecond line',
+  heading: 'Overview',
+};
+
+describe('buildDocumentPrompt', () => {
+  it('quotes the scoped passage and names the file', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Tighten this.',
+    });
+    expect(prompt).toContain('Document: docs/spec.md');
+    expect(prompt).toContain('lines 10-12 (under "Overview")');
+    expect(prompt).toContain('> First line\n> Second line');
+    expect(prompt).toContain('Instruction:\nTighten this.');
+    expect(prompt).toContain('```json');
+    expect(prompt).not.toContain('Since your previous turn');
+  });
+
+  it('describes a whole-document scope', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'Review.',
+    });
+    expect(prompt).toContain('Scope: the whole document.');
+    expect(prompt).not.toContain('verbatim');
+  });
+
+  it('explains that refinement starts from an unaccepted proposal and preserves its other improvements', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'Clarify the assumptions.',
+      refinementInstruction: 'Simplify the architecture.',
+    });
+    expect(prompt).toContain('unaccepted candidate');
+    expect(prompt).toContain('preserving its other improvements');
+    expect(prompt).toContain('The earlier instruction was:\nSimplify the architecture.');
+    expect(prompt).toContain('Instruction:\nClarify the assumptions.');
+  });
+
+  it('hands a resumed session the diff since it last saw the document', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Go on.',
+      catchUpDiff: '--- a\n+++ b\n@@ -1 +1 @@\n-old\n+new',
+    });
+    expect(prompt).toContain('Since your previous turn');
+    expect(prompt).toContain('+new');
+  });
+
+  it('truncates an oversized catch-up diff', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Go on.',
+      catchUpDiff: 'x'.repeat(30_000),
+    });
+    expect(prompt).toContain('(diff truncated)');
+    expect(prompt.length).toBeLessThan(25_000);
+  });
+});
+
+describe('parseDocumentRationale', () => {
+  it('takes the last fenced json block', () => {
+    const text =
+      'Some prose.\n```json\n{"summary": "early"}\n```\nMore.\n```json\n{"summary": "final", "changes": ["a", "b"], "questions": ["q"]}\n```';
+    const r = parseDocumentRationale(text);
+    expect(r.summary).toBe('final');
+    expect(r.changes).toEqual(['a', 'b']);
+    expect(r.questions).toEqual(['q']);
+    expect(r.assumptions).toEqual([]);
+  });
+
+  it('accepts an unlabeled fence and drops non-string entries', () => {
+    const r = parseDocumentRationale('```\n{"summary":"s","changes":["ok", 3, ""]}\n```');
+    expect(r.summary).toBe('s');
+    expect(r.changes).toEqual(['ok']);
+  });
+
+  it('parses bare json', () => {
+    expect(parseDocumentRationale('{"summary":"bare"}').summary).toBe('bare');
+  });
+
+  it('falls back to the first line of prose', () => {
+    const r = parseDocumentRationale('\n\nI rewrote the intro.\nDetails follow.');
+    expect(r.summary).toBe('I rewrote the intro.');
+    expect(r.warnings).toEqual([]);
+  });
+
+  it('flags an empty result', () => {
+    const r = parseDocumentRationale('   ');
+    expect(r.summary).toBe('No rationale returned.');
+    expect(r.warnings).toHaveLength(1);
+  });
+
+  it('ignores a fence that is valid json but not a rationale', () => {
+    const r = parseDocumentRationale('```json\n[1,2]\n```\nSummary line');
+    expect(r.summary).toBe('Summary line');
+  });
+});
diff --git a/electron/documents/prompt.ts b/electron/documents/prompt.ts
new file mode 100644
index 000000000..0dffe87f7
--- /dev/null
+++ b/electron/documents/prompt.ts
@@ -0,0 +1,145 @@
+import type { DocumentRationale, DocumentScope } from './types.js';
+
+/** Largest diff (in characters) handed to a resumed main session. */
+const MAX_CATCH_UP_DIFF_CHARS = 20_000;
+
+export interface DocumentPromptInput {
+  documentPath: string;
+  scope: DocumentScope;
+  instruction: string;
+  /** Diff of the canonical document since the resumed session last saw it. */
+  catchUpDiff?: string;
+  /** Original task for the proposal already seeded into the worktree. */
+  refinementInstruction?: string;
+}
+
+function quoteBlock(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n');
+}
+
+/** Builds the instruction a headless agent receives for one proposal. */
+export function buildDocumentPrompt(input: DocumentPromptInput): string {
+  const { documentPath, scope, instruction } = input;
+  const parts: string[] = [];
+
+  parts.push(
+    'You are revising a document in a Parallel Code document workspace. ' +
+      'Your working directory is an isolated copy of the project; the file on disk is the current version.',
+  );
+
+  if (input.catchUpDiff?.trim()) {
+    const diff =
+      input.catchUpDiff.length > MAX_CATCH_UP_DIFF_CHARS
+        ? input.catchUpDiff.slice(0, MAX_CATCH_UP_DIFF_CHARS) + '\n… (diff truncated)'
+        : input.catchUpDiff;
+    parts.push(
+      'Since your previous turn the canonical document changed. Do not rely on the version you remember; ' +
+        're-read the file. The changes were:\n```diff\n' +
+        diff +
+        '\n```',
+    );
+  }
+
+  parts.push(`Document: ${documentPath}`);
+  if (input.refinementInstruction !== undefined) {
+    parts.push(
+      'The file contains an unaccepted candidate, not the canonical document. ' +
+        'Refine this candidate using the feedback below, preserving its other improvements. ' +
+        `The earlier instruction was:\n${input.refinementInstruction.slice(0, 20_000)}`,
+    );
+  }
+
+  if (scope.wholeDocument) {
+    parts.push('Scope: the whole document.');
+  } else {
+    const where = scope.heading
+      ? `lines ${scope.startLine}-${scope.endLine} (under "${scope.heading}")`
+      : `lines ${scope.startLine}-${scope.endLine}`;
+    parts.push(`Scope: ${where}. The scoped passage, verbatim:\n${quoteBlock(scope.quote)}`);
+  }
+
+  parts.push(`Instruction:\n${instruction.trim()}`);
+
+  parts.push(
+    [
+      'Rules:',
+      `- Edit only ${documentPath}, and only inside the scoped passage. Changes elsewhere are discarded.`,
+      '- Do not touch other files, do not run shell commands or git, do not create or delete files.',
+      '- Keep the document format, structure conventions and voice unless the instruction says otherwise.',
+      '- Do not add markers, identifiers or comments to the document.',
+      '- If the instruction cannot be carried out safely, change nothing and explain why.',
+      '- End your final message with exactly one fenced ```json block of this shape, and nothing after it:',
+      '```json',
+      '{"summary": "one line: what changed and why", "changes": ["…"], "assumptions": ["…"], "questions": ["open questions for the reviewer"], "warnings": ["anything the reviewer must know"]}',
+      '```',
+    ].join('\n'),
+  );
+
+  return parts.join('\n\n');
+}
+
+/** Rationale entries end up in commit bodies: one line each, no stray newlines. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((v): v is string => typeof v === 'string' && v.trim().length > 0)
+    .map(oneLine);
+}
+
+function rationaleFromObject(value: unknown): DocumentRationale | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const obj = value as Record<string, unknown>;
+  const summary = typeof obj.summary === 'string' ? oneLine(obj.summary) : '';
+  const changes = stringList(obj.changes);
+  if (!summary && changes.length === 0) return null;
+  return {
+    summary: summary || changes[0],
+    changes,
+    assumptions: stringList(obj.assumptions),
+    questions: stringList(obj.questions),
+    warnings: stringList(obj.warnings),
+  };
+}
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extracts the structured rationale from an agent's final message. Takes the
+ * last fenced JSON block; falls back to the whole text as JSON, then to a
+ * summary made from the first non-empty line.
+ */
+export function parseDocumentRationale(text: string): DocumentRationale {
+  const fences = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)\n\s*```/g)];
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const parsed = rationaleFromObject(tryParse(fences[i][1].trim()));
+    if (parsed) return parsed;
+  }
+  const whole = rationaleFromObject(tryParse(text.trim()));
+  if (whole) return whole;
+
+  const prose = text.replace(/```[\s\S]*?```/g, '');
+  const firstLine = prose
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  return {
+    summary: firstLine ? firstLine.slice(0, 200) : 'No rationale returned.',
+    changes: [],
+    assumptions: [],
+    questions: [],
+    warnings: firstLine ? [] : ['The agent returned no rationale.'],
+  };
+}
diff --git a/electron/documents/refinement.integration.test.ts b/electron/documents/refinement.integration.test.ts
new file mode 100644
index 000000000..1f4e15f28
--- /dev/null
+++ b/electron/documents/refinement.integration.test.ts
@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import { acceptDocumentCandidate, dispatchDocumentRun, listDocumentRuns } from './runs.js';
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+function git(root: string, ...args: string[]) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+describe('candidate refinement', () => {
+  it('starts from the proposal, keeps canonical edits untouched, and accepts the complete revision', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-refine-'));
+    roots.push(root);
+    git(root, 'init', '-q', '-b', 'main');
+    git(root, 'config', 'user.name', 'Test');
+    git(root, 'config', 'user.email', 'test@example.com');
+    fs.writeFileSync(path.join(root, 'plan.md'), '# Plan\n\nOriginal.\n');
+    git(root, 'add', '.');
+    git(root, 'commit', '-qm', 'Initial');
+    const baseSha = git(root, 'rev-parse', 'HEAD');
+    // A deterministic agent: each invocation adds a revision to the file it sees.
+    const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-refine-agent-'));
+    roots.push(bin);
+    const command = path.join(bin, 'agent.sh');
+    fs.writeFileSync(command, '#!/bin/sh\nprintf "\\nRevision.\\n" >> plan.md\n', { mode: 0o755 });
+    const win = { isDestroyed: () => true } as unknown as BrowserWindow;
+    const args = {
+      projectRoot: root,
+      documentPath: 'plan.md',
+      instruction: 'Improve the plan',
+      scope: { wholeDocument: true },
+      candidates: [
+        { id: 'c1', label: 'A', agentId: 'claude-code', agentName: 'Test', command, isMain: false },
+      ],
+    };
+    const first = await dispatchDocumentRun(win, args);
+    await expect
+      .poll(async () => (await listDocumentRuns(root)).find((r) => r.id === first.id)?.status)
+      .toBe('finished');
+    const original = fs.readFileSync(path.join(root, 'plan.md'), 'utf8');
+    fs.writeFileSync(path.join(root, 'plan.md'), original.replace('# Plan', '# Local title'));
+    const refinement = { runId: first.id, candidateId: 'c1' };
+    const next = await dispatchDocumentRun(win, {
+      ...args,
+      instruction: 'Clarify the assumptions',
+      refinement,
+    });
+    await expect
+      .poll(async () => (await listDocumentRuns(root)).find((r) => r.id === next.id)?.status)
+      .toBe('finished');
+    const finished = (await listDocumentRuns(root)).find((r) => r.id === next.id);
+    if (!finished) throw new Error('Refinement run not found');
+    expect(finished.refinement).toEqual(refinement);
+    expect(finished.baseSha).toBe(baseSha);
+    expect(git(root, 'rev-parse', 'HEAD')).toBe(baseSha);
+    expect(fs.readFileSync(path.join(root, 'plan.md'), 'utf8')).toBe(
+      original.replace('# Plan', '# Local title'),
+    );
+    expect(git(root, 'show', `${finished.candidates[0].commitSha}:plan.md`)).toBe(
+      '# Plan\n\nOriginal.\n\nRevision.\n\nRevision.',
+    );
+    await acceptDocumentCandidate(root, next.id, 'c1');
+    expect(fs.readFileSync(path.join(root, 'plan.md'), 'utf8')).toBe(
+      '# Local title\n\nOriginal.\n\nRevision.\n\nRevision.\n',
+    );
+    expect((await listDocumentRuns(root)).find((r) => r.id === first.id)?.status).toBe('finished');
+    await expect(
+      dispatchDocumentRun(win, { ...args, refinement: { runId: next.id, candidateId: 'c1' } }),
+    ).rejects.toThrow(/accepted|review/);
+    await expect(
+      dispatchDocumentRun(win, { ...args, documentPath: 'other.md', refinement }),
+    ).rejects.toThrow(/document/);
+    const recordPath = path.join(root, '.parallel', 'runs', `${first.id}.json`);
+    const record = JSON.parse(fs.readFileSync(recordPath, 'utf8')) as Record<string, unknown>;
+    fs.writeFileSync(recordPath, JSON.stringify({ ...record, instruction: 123 }));
+    await expect(dispatchDocumentRun(win, { ...args, refinement })).rejects.toThrow(/instruction/);
+  });
+});
diff --git a/electron/documents/register.ts b/electron/documents/register.ts
new file mode 100644
index 000000000..d1298c5be
--- /dev/null
+++ b/electron/documents/register.ts
@@ -0,0 +1,193 @@
+/**
+ * Every IPC handler the document workspace owns, in one place. Handlers take
+ * the project root from the renderer and validate it; document paths are
+ * repo-relative and checked against traversal.
+ */
+import { ipcMain, type BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import {
+  assertOptionalBoolean,
+  assertOptionalString,
+  assertString,
+  validatePath,
+} from '../ipc/validate.js';
+import {
+  acceptDocumentCandidate,
+  cancelDocumentRun,
+  dispatchDocumentRun,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+  revertDocumentCommit,
+  setDocumentCandidateNote,
+  startDocumentWatcher,
+  stopAllDocumentRuns,
+  stopAllDocumentWatchers,
+  stopDocumentWatcher,
+  validateDocumentPath,
+  validateSha,
+  writeDocumentBlock,
+} from './runs.js';
+import { inspectDocumentFolder, prepareDocumentProject } from './setup.js';
+import { listProjectFiles } from './files.js';
+import { readCandidateLog } from './logs.js';
+import {
+  askAnnotation,
+  deleteAnnotation,
+  readAnnotations,
+  saveAnnotation,
+  stopAllAsks,
+} from './annotations.js';
+
+type IpcArgs = Record<string, unknown>;
+
+function projectRootArg(args: IpcArgs): string {
+  validatePath(args.projectRoot, 'projectRoot');
+  return args.projectRoot as string;
+}
+
+export function registerDocumentHandlers(win: BrowserWindow): void {
+  ipcMain.handle(IPC.ReadDocument, (_e, args) => {
+    return readDocumentSnapshot(projectRootArg(args), validateDocumentPath(args.documentPath));
+  });
+  ipcMain.handle(IPC.WriteDocumentBlock, (_e, args) => {
+    return writeDocumentBlock(projectRootArg(args), args);
+  });
+
+  ipcMain.handle(IPC.StartDocumentWatcher, (_e, args) => {
+    assertString(args.key, 'key');
+    const projectRoot = projectRootArg(args);
+    startDocumentWatcher(win, args.key, projectRoot, validateDocumentPath(args.documentPath));
+  });
+
+  ipcMain.handle(IPC.StopDocumentWatcher, (_e, args) => {
+    assertString(args.key, 'key');
+    stopDocumentWatcher(args.key);
+  });
+
+  ipcMain.handle(IPC.InspectDocumentFolder, (_e, args) => {
+    return inspectDocumentFolder(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.PrepareDocumentProject, (_e, args) => {
+    return prepareDocumentProject(
+      projectRootArg(args),
+      args.documentPath,
+      typeof args.title === 'string' ? args.title : undefined,
+    );
+  });
+
+  ipcMain.handle(IPC.ListDocumentRuns, (_e, args) => {
+    return listDocumentRuns(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.ListDocumentFiles, (_e, args) => {
+    return listProjectFiles(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.ReadDocumentCandidateLog, (_e, args) => {
+    return readCandidateLog(projectRootArg(args), args.runId, args.candidateId);
+  });
+
+  ipcMain.handle(IPC.DispatchDocumentRun, (_e, args) => {
+    return dispatchDocumentRun(win, {
+      projectRoot: projectRootArg(args),
+      documentPath: args.documentPath,
+      instruction: args.instruction,
+      scope: args.scope,
+      candidates: args.candidates,
+      refinement: args.refinement,
+    });
+  });
+
+  ipcMain.handle(IPC.CancelDocumentRun, (_e, args) => {
+    cancelDocumentRun(args.runId);
+  });
+
+  ipcMain.handle(IPC.AcceptDocumentCandidate, (_e, args) => {
+    return acceptDocumentCandidate(
+      projectRootArg(args),
+      args.runId,
+      args.candidateId,
+      args.partial,
+    );
+  });
+
+  ipcMain.handle(IPC.RejectDocumentRun, (_e, args) => {
+    return rejectDocumentRun(projectRootArg(args), args.runId);
+  });
+
+  ipcMain.handle(IPC.SetDocumentCandidateNote, (_e, args) => {
+    return setDocumentCandidateNote(projectRootArg(args), args.runId, args.candidateId, args.note);
+  });
+
+  ipcMain.handle(IPC.GetDocumentHistory, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    assertOptionalBoolean(args.wholeProject, 'wholeProject');
+    return getDocumentHistory(
+      projectRoot,
+      validateDocumentPath(args.documentPath),
+      args.wholeProject === true,
+    );
+  });
+
+  ipcMain.handle(IPC.GetDocumentAtCommit, (_e, args) => {
+    return getDocumentAtCommit(
+      projectRootArg(args),
+      validateSha(args.sha),
+      validateDocumentPath(args.documentPath),
+    );
+  });
+
+  ipcMain.handle(IPC.GetDocumentDiff, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    const to = validateSha(args.to, 'to');
+    // `from` is a commit hash, or that hash's parent for history entries.
+    assertString(args.from, 'from');
+    const from = args.from.endsWith('^')
+      ? `${validateSha(args.from.slice(0, -1), 'from')}^`
+      : validateSha(args.from, 'from');
+    return getDocumentDiff(projectRoot, from, to, validateDocumentPath(args.documentPath));
+  });
+
+  ipcMain.handle(IPC.RevertDocumentCommit, (_e, args) => {
+    return revertDocumentCommit(projectRootArg(args), validateSha(args.sha));
+  });
+
+  // --- Annotations ---
+  ipcMain.handle(IPC.ListDocumentAnnotations, (_e, args) => {
+    return readAnnotations(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.SaveDocumentAnnotation, (_e, args) => {
+    return saveAnnotation(projectRootArg(args), args.annotation);
+  });
+
+  ipcMain.handle(IPC.DeleteDocumentAnnotation, (_e, args) => {
+    return deleteAnnotation(projectRootArg(args), args.id);
+  });
+
+  ipcMain.handle(IPC.AskDocumentAnnotation, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    assertOptionalString(args.envFile, 'envFile');
+    return askAnnotation(win, {
+      projectRoot,
+      documentPath: args.documentPath,
+      annotationId: args.annotationId,
+      agentId: args.agentId,
+      agentName: args.agentName,
+      command: args.command,
+      envFile: args.envFile,
+    });
+  });
+}
+
+/** Everything the feature keeps alive; called on app quit. */
+export function stopAllDocumentWork(): void {
+  stopAllDocumentWatchers();
+  stopAllDocumentRuns();
+  stopAllAsks();
+}
diff --git a/electron/documents/runs.integration.test.ts b/electron/documents/runs.integration.test.ts
new file mode 100644
index 000000000..ab09aea8f
--- /dev/null
+++ b/electron/documents/runs.integration.test.ts
@@ -0,0 +1,577 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import {
+  acceptDocumentCandidate,
+  commitPendingEdits,
+  dispatchDocumentRun,
+  revertDocumentCommit,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+} from './runs.js';
+import { inspectDocumentFolder } from './setup.js';
+import type { DocumentRunEvent, DocumentRunRecord } from './types.js';
+
+/**
+ * Exercises the whole proposal lifecycle against a real temporary repository
+ * with a fake "claude" script standing in for the CLI: it rewrites the scoped
+ * passage, touches a file outside scope, and prints a stream-json result.
+ */
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+const DOC = [
+  '# Spec',
+  '',
+  'Intro paragraph.',
+  '',
+  '## Goals',
+  '',
+  'Old goals text.',
+  '',
+  '## Later',
+  '',
+  'Untouched.',
+  '',
+].join('\n');
+
+let root: string;
+let fakeAgent: string;
+const events: DocumentRunEvent[] = [];
+const win = {
+  isDestroyed: () => false,
+  webContents: { send: (_ch: string, payload: DocumentRunEvent) => events.push(payload) },
+} as unknown as BrowserWindow;
+
+function waitForRunFinish(runId: string): Promise<DocumentRunRecord> {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const tick = () => {
+      const done = events.find(
+        (e): e is Extract<DocumentRunEvent, { type: 'run' }> =>
+          e.type === 'run' && e.run.id === runId && e.run.status !== 'running',
+      );
+      if (done) return resolve(done.run);
+      if (Date.now() - started > 20_000) return reject(new Error('run did not finish'));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+beforeAll(() => {
+  process.env.GIT_AUTHOR_NAME = 'Test';
+  process.env.GIT_AUTHOR_EMAIL = 'test@example.com';
+  process.env.GIT_COMMITTER_NAME = 'Test';
+  process.env.GIT_COMMITTER_EMAIL = 'test@example.com';
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-'));
+  git(root, 'init', '-q', '-b', 'main');
+  fs.mkdirSync(path.join(root, 'docs'));
+  fs.writeFileSync(path.join(root, 'docs', 'spec.md'), DOC);
+  fs.writeFileSync(path.join(root, 'README.md'), '# Readme\n');
+  git(root, 'add', '.');
+  git(root, 'commit', '-q', '-m', 'initial');
+
+  // The fake CLI lives outside the repo so it never shows up as a change.
+  const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-bin-'));
+  fakeAgent = path.join(binDir, 'fake-claude.sh');
+  fs.writeFileSync(
+    fakeAgent,
+    [
+      '#!/bin/sh',
+      'sed -i.bak "s/Old goals text./New goals text, sharper./" docs/spec.md && rm -f docs/spec.md.bak',
+      'echo "stray" > STRAY.txt && git add STRAY.txt',
+      'echo "scratch" > notes.tmp',
+      'printf \'%s\\n\' \'{"type":"system","subtype":"init","session_id":"sess-1"}\'',
+      'printf \'%s\\n\' \'{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit","input":{"file_path":"docs/spec.md"}}]}}\'',
+      'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"sess-1","result":"Done.\\n```json\\n{\\"summary\\":\\"Sharpened the goals\\",\\"changes\\":[\\"rewrote goals\\"],\\"questions\\":[\\"ok?\\"]}\\n```"}\'',
+    ].join('\n') + '\n',
+    { mode: 0o755 },
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('document workspace lifecycle', () => {
+  it('lists the markdown a ready repository offers', async () => {
+    expect(await inspectDocumentFolder(root)).toMatchObject({
+      isRepo: true,
+      hasCommits: true,
+      files: [
+        { path: 'README.md', committed: true },
+        { path: 'docs/spec.md', committed: true },
+      ],
+    });
+  });
+
+  it('diffs the root commit against the empty tree', async () => {
+    const rootSha = git(root, 'rev-list', '--max-parents=0', 'HEAD').trim();
+    const diff = await getDocumentDiff(root, `${rootSha}^`, rootSha, 'docs/spec.md');
+    expect(diff).toContain('+# Spec');
+  });
+
+  it('reads a snapshot', async () => {
+    const snap = await readDocumentSnapshot(root, 'docs/spec.md');
+    expect(snap.content).toBe(DOC);
+    expect(snap.branch).toBe('main');
+    expect(snap.dirty).toBe(false);
+    expect(snap.headSha).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('commits pending edits, runs a candidate in a worktree, strips out-of-scope files and commits a proposal', async () => {
+    // A pending manual edit must become the base; an untracked scratch file must not.
+    fs.appendFileSync(path.join(root, 'README.md'), 'manual\n');
+    fs.writeFileSync(path.join(root, 'scratch.txt'), 'not for history\n');
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Sharpen the goals.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Goals\n\nOld goals text.',
+        heading: 'Goals',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: true,
+        },
+      ],
+    });
+    expect(run.status).toBe('running');
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Manual edits');
+    expect(git(root, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('README.md');
+    expect(git(root, 'status', '--porcelain', 'scratch.txt').trim()).toMatch(/^\?\? scratch.txt/);
+    fs.rmSync(path.join(root, 'scratch.txt'));
+    expect(run.baseSha).toBe(git(root, 'rev-parse', 'HEAD').trim());
+
+    const finished = await waitForRunFinish(run.id);
+    const c = finished.candidates[0];
+    const proposalSha = String(c.commitSha);
+    expect(c.status).toBe('done');
+    expect(c.sessionId).toBe('sess-1');
+    expect(c.rationale?.summary).toBe('Sharpened the goals');
+    expect(c.rationale?.questions).toEqual(['ok?']);
+    expect(c.outOfScopeFiles?.sort()).toEqual(['STRAY.txt', 'notes.tmp']);
+    expect(c.outOfScopeHunks).toBeUndefined();
+    expect(c.commitSha).toMatch(/^[0-9a-f]{40}$/);
+    expect(c.worktreePath).toBe(path.join(root, '.worktrees', 'parallel-doc-main'));
+    expect(events.some((e) => e.type === 'log' && e.text.includes('Edit docs/spec.md'))).toBe(true);
+
+    // The proposal commit carries only the document and readable trailers.
+    const files = git(root, 'show', '--format=', '--name-only', proposalSha).trim();
+    expect(files).toBe('docs/spec.md');
+    const message = git(root, 'show', '-s', '--format=%B', proposalSha);
+    expect(message).toContain('Sharpened the goals');
+    expect(message).toContain('Parallel-Agent: Fake Claude');
+    expect(message).toContain('Parallel-Scope: docs/spec.md#L5-L7');
+    expect(message).toContain(`Parallel-Base: ${run.baseSha}`);
+
+    // The canonical document is untouched until acceptance.
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toBe(DOC);
+    expect(await getDocumentAtCommit(root, proposalSha, 'docs/spec.md')).toContain(
+      'New goals text',
+    );
+    expect(await getDocumentDiff(root, run.baseSha, proposalSha, 'docs/spec.md')).toContain(
+      '+New goals text',
+    );
+
+    // Records are persisted and reloadable.
+    const listed = listDocumentRuns(root);
+    expect(listed.map((r) => r.id)).toEqual([run.id]);
+    expect(listed[0].status).toBe('finished');
+
+    // Accept: one squashed integration commit with the run record.
+    const { sha } = await acceptDocumentCandidate(root, run.id, 'c1');
+    expect(sha).toBe(git(root, 'rev-parse', 'HEAD').trim());
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toContain('New goals text');
+    const accepted = git(root, 'show', '--format=%B', '--name-only', sha);
+    expect(accepted).toContain('Parallel-Run: ' + run.id);
+    expect(accepted).toContain('Parallel-Candidate: A');
+    expect(accepted).toContain('docs/spec.md');
+    expect(accepted).toContain(`.parallel/runs/${run.id}.json`);
+    expect(git(root, 'rev-list', '--count', 'HEAD').trim()).toBe('3');
+    expect(listDocumentRuns(root)[0].status).toBe('accepted');
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/already accepted/);
+
+    // History for the document parses trailers and marks manual commits.
+    const history = await getDocumentHistory(root, 'docs/spec.md', false);
+    expect(history.map((h) => h.manual)).toEqual([false, true]);
+    expect(history[0].trailers.Agent).toBe('Fake Claude');
+    expect(history[0].body).not.toContain('Parallel-');
+    const whole = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(whole).toHaveLength(3);
+
+    // Reverting the acceptance restores the document but keeps the run record.
+    const reverted = await revertDocumentCommit(root, sha);
+    expect(reverted).toBe(git(root, 'rev-parse', 'HEAD').trim());
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toBe(DOC);
+    expect(fs.existsSync(path.join(root, '.parallel', 'runs', `${run.id}.json`))).toBe(true);
+    expect(git(root, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('docs/spec.md');
+    expect(git(root, 'show', '-s', '--format=%B', 'HEAD')).toContain(`Parallel-Revert: ${sha}`);
+    expect(listDocumentRuns(root).map((r) => r.id)).toEqual([run.id]);
+  });
+
+  it('refuses to reuse the main worktree while its candidate is still running', async () => {
+    const binDir = path.dirname(fakeAgent);
+    const slow = path.join(binDir, 'slow.sh');
+    fs.writeFileSync(slow, '#!/bin/sh\nsleep 3\n', { mode: 0o755 });
+    const base = {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Slow.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    };
+    const running = await dispatchDocumentRun(win, {
+      ...base,
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Slow',
+          command: slow,
+          isMain: true,
+        },
+      ],
+    });
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [
+          {
+            id: 'c1',
+            label: 'A',
+            agentId: 'claude-code',
+            agentName: 'Slow',
+            command: slow,
+            isMain: true,
+          },
+        ],
+      }),
+    ).rejects.toThrow(/main session is still working/);
+    // An alternate-only run is fine meanwhile.
+    const alt = await dispatchDocumentRun(win, {
+      ...base,
+      candidates: [
+        {
+          id: 'c1',
+          label: 'B',
+          agentId: 'claude-code',
+          agentName: 'Slow',
+          command: slow,
+          isMain: false,
+        },
+      ],
+    });
+    // Rejecting a running run kills it and waits for it to settle before cleanup.
+    const rejected = await rejectDocumentRun(root, running.id);
+    expect(rejected.status).toBe('rejected');
+    expect(rejected.candidates[0].status).toBe('cancelled');
+    expect(listDocumentRuns(root).find((r) => r.id === running.id)?.status).toBe('rejected');
+    await waitForRunFinish(alt.id);
+    await rejectDocumentRun(root, alt.id);
+  });
+
+  // Its own repository: the tests above share one and depend on its state.
+  it('leaves what the user staged by hand out of its own commits', async () => {
+    const solo = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-staged-'));
+    git(solo, 'init', '-q', '-b', 'main');
+    fs.mkdirSync(path.join(solo, 'docs'));
+    fs.writeFileSync(path.join(solo, 'docs', 'spec.md'), DOC);
+    fs.writeFileSync(path.join(solo, 'README.md'), '# Readme\n');
+    git(solo, 'add', '.');
+    git(solo, 'commit', '-q', '-m', 'initial');
+
+    // The user stages a new file of their own and edits a tracked one.
+    fs.writeFileSync(path.join(solo, 'staged-by-user.md'), '# Not ours\n');
+    git(solo, 'add', 'staged-by-user.md');
+    fs.appendFileSync(path.join(solo, 'README.md'), 'manual edit\n');
+
+    const base = await commitPendingEdits(solo);
+    expect(git(solo, 'show', '--format=', '--name-only', base).trim()).toBe('README.md');
+    const stillStaged = () => git(solo, 'status', '--porcelain', '--', 'staged-by-user.md').trim();
+    expect(stillStaged()).toBe('A  staged-by-user.md');
+
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: solo,
+      documentPath: 'docs/spec.md',
+      instruction: 'Sharpen the goals.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    await waitForRunFinish(run.id);
+    const { sha } = await acceptDocumentCandidate(solo, run.id, 'c1');
+    expect(git(solo, 'show', '--format=', '--name-only', sha).trim().split('\n').sort()).toEqual([
+      `.parallel/runs/${run.id}.json`,
+      'docs/spec.md',
+    ]);
+    expect(stillStaged()).toBe('A  staged-by-user.md');
+    fs.rmSync(solo, { recursive: true, force: true });
+  });
+
+  // Its own repository: partial acceptance writes the document rather than
+  // merging the proposal, so it must not run against shared state.
+  it('accepts only the changes the reader kept, and refuses once the document moved', async () => {
+    const partialRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-partial-'));
+    git(partialRoot, 'init', '-q', '-b', 'main');
+    fs.mkdirSync(path.join(partialRoot, 'docs'));
+    fs.writeFileSync(path.join(partialRoot, 'docs', 'spec.md'), DOC);
+    git(partialRoot, 'add', '.');
+    git(partialRoot, 'commit', '-q', '-m', 'initial');
+
+    // This candidate rewrites two paragraphs; the reader keeps one of them.
+    const twoChanges = path.join(path.dirname(fakeAgent), 'fake-claude-two.sh');
+    fs.writeFileSync(
+      twoChanges,
+      [
+        '#!/bin/sh',
+        'sed -i.bak "s/Intro paragraph./Sharper intro./;s/Old goals text./New goals text, sharper./" docs/spec.md && rm -f docs/spec.md.bak',
+        'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"s","result":"```json\\n{\\"summary\\":\\"Two rewrites\\",\\"changes\\":[\\"intro\\",\\"goals\\"]}\\n```"}\'',
+      ].join('\n') + '\n',
+      { mode: 0o755 },
+    );
+
+    const dispatch = () =>
+      dispatchDocumentRun(win, {
+        projectRoot: partialRoot,
+        documentPath: 'docs/spec.md',
+        instruction: 'Sharpen it.',
+        scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+        candidates: [
+          {
+            id: 'c1',
+            label: 'A',
+            agentId: 'claude-code',
+            agentName: 'Fake Claude',
+            command: twoChanges,
+            isMain: false,
+          },
+        ],
+      });
+
+    const run = await dispatch();
+    await waitForRunFinish(run.id);
+    const kept = DOC.replace('Old goals text.', 'New goals text, sharper.');
+    const { sha } = await acceptDocumentCandidate(partialRoot, run.id, 'c1', {
+      content: kept,
+      accepted: 1,
+      total: 2,
+    });
+
+    // Only the kept change landed, in one commit holding the document and record.
+    expect(fs.readFileSync(path.join(partialRoot, 'docs', 'spec.md'), 'utf8')).toBe(kept);
+    expect(
+      git(partialRoot, 'show', '--format=', '--name-only', sha).trim().split('\n').sort(),
+    ).toEqual([`.parallel/runs/${run.id}.json`, 'docs/spec.md']);
+    const message = git(partialRoot, 'show', '-s', '--format=%B', sha);
+    expect(message).toContain('Parallel-Partial: 1/2 changes');
+    expect(message).toContain('Parallel-Candidate: A');
+    const record = listDocumentRuns(partialRoot)[0];
+    expect(record.status).toBe('accepted');
+    expect(record.partialAcceptance).toEqual({ accepted: 1, total: 2 });
+
+    // Prose the renderer invented is refused: a composition is a mix of the
+    // base and the candidate, never anything else.
+    const second = await dispatch();
+    await waitForRunFinish(second.id);
+    await expect(
+      acceptDocumentCandidate(partialRoot, second.id, 'c1', {
+        content: `${kept}\nSomething no agent proposed.\n`,
+        accepted: 1,
+        total: 2,
+      }),
+    ).rejects.toThrow(/does not match the proposal/);
+    expect(fs.readFileSync(path.join(partialRoot, 'docs', 'spec.md'), 'utf8')).toBe(kept);
+
+    // An unrelated commit moves HEAD without touching the document, so the
+    // composition still describes what is there and is allowed through.
+    fs.writeFileSync(path.join(partialRoot, 'NOTES.md'), 'unrelated\n');
+    git(partialRoot, 'add', 'NOTES.md');
+    git(partialRoot, 'commit', '-q', '-m', 'unrelated');
+    expect(git(partialRoot, 'rev-parse', 'HEAD').trim()).not.toBe(second.baseSha);
+    const sharpened = kept.replace('Intro paragraph.', 'Sharper intro.');
+    await acceptDocumentCandidate(partialRoot, second.id, 'c1', {
+      content: sharpened,
+      accepted: 1,
+      total: 1,
+    });
+    expect(fs.readFileSync(path.join(partialRoot, 'docs', 'spec.md'), 'utf8')).toBe(sharpened);
+
+    // A composition made from a base the document has left is refused, not
+    // merged. Restore the phrases the fake agent rewrites so it has work to do;
+    // dispatch commits that edit, so it becomes this run's base.
+    fs.writeFileSync(path.join(partialRoot, 'docs', 'spec.md'), DOC);
+    const third = await dispatch();
+    await waitForRunFinish(third.id);
+    fs.appendFileSync(path.join(partialRoot, 'docs', 'spec.md'), '\nA later thought.\n');
+    await expect(
+      acceptDocumentCandidate(partialRoot, third.id, 'c1', {
+        content: kept,
+        accepted: 1,
+        total: 2,
+      }),
+    ).rejects.toThrow(/changes you picked no longer apply/);
+    expect(fs.readFileSync(path.join(partialRoot, 'docs', 'spec.md'), 'utf8')).toContain(
+      'A later thought.',
+    );
+    expect(listDocumentRuns(partialRoot).find((r) => r.id === third.id)?.status).toBe('stale');
+
+    // Counts that do not describe a real choice, and content that would empty
+    // the document, are rejected before any git runs.
+    await expect(
+      acceptDocumentCandidate(partialRoot, third.id, 'c1', {
+        content: kept,
+        accepted: 0,
+        total: 2,
+      }),
+    ).rejects.toThrow(/Invalid partial acceptance counts/);
+    await expect(
+      acceptDocumentCandidate(partialRoot, third.id, 'c1', {
+        content: '  ',
+        accepted: 1,
+        total: 2,
+      }),
+    ).rejects.toThrow(/cannot empty the document/);
+
+    fs.rmSync(partialRoot, { recursive: true, force: true });
+  });
+
+  it('rejects candidate specs that would smuggle flags into git or the CLI', async () => {
+    const base = {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'x',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    };
+    const spec = {
+      id: 'c1',
+      label: 'A',
+      agentId: 'claude-code',
+      agentName: 'F',
+      command: fakeAgent,
+      isMain: true,
+    };
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [{ ...spec, sessionLastSha: '--output=/tmp/x' }],
+      }),
+    ).rejects.toThrow(/sessionLastSha/);
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [{ ...spec, sessionId: '--dangerously-skip-permissions' }],
+      }),
+    ).rejects.toThrow(/sessionId/);
+    await expect(
+      dispatchDocumentRun(win, { ...base, candidates: [{ ...spec, agentId: 'opencode' }] }),
+    ).rejects.toThrow(/no headless mode/);
+    await expect(commitPendingEdits(root)).resolves.toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('marks a proposal stale when the base moved and it conflicts, and rejects cleanly', async () => {
+    // The revert above restored the original text, so the fake edit applies again.
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Again.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    const finished = await waitForRunFinish(run.id);
+    const c = finished.candidates[0];
+    expect(c.commitSha).toBeTruthy();
+    // Alternates get seeded sandbox files; those must not count as strays.
+    expect(c.outOfScopeFiles?.some((f) => f.startsWith('.claude/'))).toBe(false);
+
+    // Meanwhile the user rewrites the same line by hand and commits it.
+    fs.writeFileSync(
+      path.join(root, 'docs', 'spec.md'),
+      DOC.replace('Old goals text.', 'Hand-written goals.'),
+    );
+    git(root, 'commit', '-q', '-am', 'hand edit');
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/no longer applies/);
+    expect(listDocumentRuns(root).find((r) => r.id === run.id)?.status).toBe('stale');
+    expect(git(root, 'status', '--porcelain', '--', 'docs').trim()).toBe('');
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toContain('Hand-written');
+
+    const rejected = await rejectDocumentRun(root, run.id);
+    expect(rejected.status).toBe('rejected');
+    expect(fs.existsSync(c.worktreePath)).toBe(false);
+    expect(git(root, 'branch', '--list', c.branch).trim()).toBe('');
+    // The rejection is a metadata-only commit, invisible in the document history.
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Reject proposals');
+    const history = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(history.map((h) => h.subject)).not.toContain('Reject proposals');
+  });
+
+  // Runs after the test above, which already replaced the text the fake agent
+  // looks for, so this candidate finds nothing to change.
+  it('records a candidate that changed nothing, and rejects it cleanly', async () => {
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Again.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    const finished = await waitForRunFinish(run.id);
+    // The fake edit no longer matches (text already replaced) so nothing changes.
+    expect(finished.candidates[0].noChanges).toBe(true);
+    expect(finished.candidates[0].commitSha).toBeNull();
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/no change/);
+    const rejected = await rejectDocumentRun(root, run.id);
+    expect(rejected.status).toBe('rejected');
+    expect(fs.existsSync(finished.candidates[0].worktreePath)).toBe(false);
+    expect(git(root, 'branch', '--list', finished.candidates[0].branch).trim()).toBe('');
+    // The rejection is a metadata-only commit, invisible in the document history.
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Reject proposals');
+    const history = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(history.map((h) => h.subject)).not.toContain('Reject proposals');
+  });
+});
diff --git a/electron/documents/runs.real-claude.integration.test.ts b/electron/documents/runs.real-claude.integration.test.ts
new file mode 100644
index 000000000..202fd91d6
--- /dev/null
+++ b/electron/documents/runs.real-claude.integration.test.ts
@@ -0,0 +1,211 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import { acceptDocumentCandidate, dispatchDocumentRun } from './runs.js';
+import { askAnnotation, readAnnotations, saveAnnotation } from './annotations.js';
+import type {
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentRunEvent,
+  DocumentRunRecord,
+} from './types.js';
+
+/**
+ * Drives the real `claude` CLI through one proposal and one resumed follow-up.
+ * Costs a few API calls, so it only runs when explicitly asked for:
+ *   RUN_REAL_CLAUDE_DOC_TEST=1 npx vitest run electron/documents/runs.real-claude.integration.test.ts
+ */
+const RUN = process.env.RUN_REAL_CLAUDE_DOC_TEST === '1';
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+const DOC = [
+  '# Notes',
+  '',
+  'Intro stays as it is.',
+  '',
+  '## Weather',
+  '',
+  'The weather is nice.',
+  '',
+  '## Closing',
+  '',
+  'Bye.',
+  '',
+].join('\n');
+
+describe.skipIf(!RUN)('document workspace with the real claude CLI', () => {
+  let root: string;
+  const events: DocumentRunEvent[] = [];
+  const annotationEvents: DocumentAnnotationEvent[] = [];
+  const win = {
+    isDestroyed: () => false,
+    webContents: {
+      send: (ch: string, payload: DocumentRunEvent | DocumentAnnotationEvent) => {
+        if (ch === 'document_annotation_event')
+          annotationEvents.push(payload as DocumentAnnotationEvent);
+        else events.push(payload as DocumentRunEvent);
+      },
+    },
+  } as unknown as BrowserWindow;
+
+  function waitForRun(runId: string): Promise<DocumentRunRecord> {
+    return new Promise((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = events.find(
+          (e): e is Extract<DocumentRunEvent, { type: 'run' }> =>
+            e.type === 'run' && e.run.id === runId && e.run.status !== 'running',
+        );
+        if (done) return resolve(done.run);
+        if (Date.now() - started > 240_000) return reject(new Error('run did not finish'));
+        setTimeout(tick, 250);
+      };
+      tick();
+    });
+  }
+
+  beforeAll(() => {
+    process.env.GIT_AUTHOR_NAME ??= 'Test';
+    process.env.GIT_AUTHOR_EMAIL ??= 'test@example.com';
+    process.env.GIT_COMMITTER_NAME ??= 'Test';
+    process.env.GIT_COMMITTER_EMAIL ??= 'test@example.com';
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-real-'));
+    git(root, 'init', '-q', '-b', 'main');
+    fs.writeFileSync(path.join(root, 'notes.md'), DOC);
+    git(root, 'add', '.');
+    git(root, 'commit', '-q', '-m', 'initial');
+  });
+
+  afterAll(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('proposes, accepts, then resumes the main session with the catch-up diff', async () => {
+    const first = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      instruction:
+        'Replace the sentence in this section with exactly: "The weather is stormy today." Keep the heading.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is nice.',
+        heading: 'Weather',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Claude Code',
+          command: 'claude',
+          isMain: true,
+        },
+      ],
+    });
+    const done = await waitForRun(first.id);
+    const c = done.candidates[0];
+    expect(c.status, c.error).toBe('done');
+    expect(c.sessionId).toBeTruthy();
+    expect(c.commitSha).toBeTruthy();
+    expect(c.outOfScopeFiles ?? []).toEqual([]);
+    expect(c.rationale?.summary).toBeTruthy();
+    const proposed = git(root, 'show', `${c.commitSha}:notes.md`);
+    expect(proposed).toContain('stormy');
+    expect(proposed).toContain('Intro stays as it is.');
+
+    await acceptDocumentCandidate(root, first.id, 'c1');
+    expect(fs.readFileSync(path.join(root, 'notes.md'), 'utf8')).toContain('stormy');
+
+    // Second turn resumes the same session; it must answer from memory of the
+    // instruction it was given while seeing the accepted document.
+    const second = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      instruction:
+        'In this section, add one more sentence after the existing one that repeats, in quotes, the exact sentence you were asked to insert in your previous turn.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is stormy today.',
+        heading: 'Weather',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Claude Code',
+          command: 'claude',
+          isMain: true,
+          sessionId: c.sessionId,
+          sessionLastSha: first.baseSha,
+        },
+      ],
+    });
+    const done2 = await waitForRun(second.id);
+    const c2 = done2.candidates[0];
+    expect(c2.status, c2.error).toBe('done');
+    expect(c2.sessionId).toBe(c.sessionId);
+    expect(c2.commitSha).toBeTruthy();
+    const proposed2 = git(root, 'show', `${c2.commitSha}:notes.md`);
+    expect(proposed2).toContain('The weather is stormy today.');
+    expect(proposed2.match(/stormy/g)?.length).toBeGreaterThanOrEqual(2);
+  }, 300_000);
+
+  it('answers a question about a passage without touching the document', async () => {
+    const before = fs.readFileSync(path.join(root, 'notes.md'), 'utf8');
+    const head = git(root, 'rev-parse', 'HEAD').trim();
+    await saveAnnotation(root, {
+      id: 'q-real-1',
+      kind: 'question',
+      text: 'In one short sentence: what is the weather in this passage? Do not edit anything.',
+      anchor: {
+        path: 'notes.md',
+        baseSha: head,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is stormy today.',
+        prefix: 'Intro stays as it is.',
+        suffix: '## Closing',
+        heading: 'Weather',
+      },
+      createdAt: new Date().toISOString(),
+    });
+    await askAnnotation(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      annotationId: 'q-real-1',
+      agentId: 'claude-code',
+      agentName: 'Claude Code',
+      command: 'claude',
+    });
+    const answered = await new Promise<DocumentAnnotation>((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = annotationEvents.find(
+          (e) => e.annotation.id === 'q-real-1' && e.annotation.answerStatus !== 'pending',
+        );
+        if (done) return resolve(done.annotation);
+        if (Date.now() - started > 240_000) return reject(new Error('no answer'));
+        setTimeout(tick, 250);
+      };
+      tick();
+    });
+    expect(answered.answerStatus, answered.answerError).toBe('answered');
+    expect(answered.answer?.text.toLowerCase()).toContain('storm');
+    expect(readAnnotations(root).find((a) => a.id === 'q-real-1')?.answer?.text).toBeTruthy();
+    // Read-only: no file changed, no commit made.
+    expect(fs.readFileSync(path.join(root, 'notes.md'), 'utf8')).toBe(before);
+    expect(git(root, 'rev-parse', 'HEAD').trim()).toBe(head);
+    expect(git(root, 'status', '--porcelain', '--', 'notes.md').trim()).toBe('');
+  }, 300_000);
+});
diff --git a/electron/documents/runs.test.ts b/electron/documents/runs.test.ts
new file mode 100644
index 000000000..a1085d922
--- /dev/null
+++ b/electron/documents/runs.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import {
+  countOutOfScopeHunks,
+  parseCommitBody,
+  sanitizeRunRecord,
+  validateDocumentPath,
+  validateSha,
+} from './runs.js';
+
+describe('validateDocumentPath', () => {
+  it('accepts a relative markdown path and normalizes ./', () => {
+    expect(validateDocumentPath('./docs/spec.md')).toBe('docs/spec.md');
+  });
+  it('rejects traversal, absolute paths and metadata directories', () => {
+    expect(() => validateDocumentPath('../x.md')).toThrow();
+    expect(() => validateDocumentPath('docs/../x.md')).toThrow();
+    expect(() => validateDocumentPath('/abs/x.md')).toThrow();
+    expect(() => validateDocumentPath('.parallel/runs/a.json')).toThrow();
+    expect(() => validateDocumentPath('.worktrees/x/a.md')).toThrow();
+    expect(() => validateDocumentPath('.git/config')).toThrow();
+    expect(validateDocumentPath('.github/README.md')).toBe('.github/README.md');
+    expect(() => validateDocumentPath('')).toThrow();
+    expect(() => validateDocumentPath(3)).toThrow();
+  });
+});
+
+describe('validateSha', () => {
+  it('accepts hex hashes only', () => {
+    expect(validateSha('abcdef1')).toBe('abcdef1');
+    expect(() => validateSha('HEAD~1')).toThrow();
+    expect(() => validateSha('abc')).toThrow();
+  });
+});
+
+describe('countOutOfScopeHunks', () => {
+  const scope = {
+    path: 'a.md',
+    wholeDocument: false,
+    startLine: 10,
+    endLine: 20,
+    quote: '',
+  };
+  it('counts nothing for a whole-document scope', () => {
+    expect(countOutOfScopeHunks('@@ -1,3 +1,4 @@\n', { ...scope, wholeDocument: true })).toBe(0);
+  });
+  it('accepts hunks inside or adjacent to the scope', () => {
+    const diff = ['@@ -10,3 +10,4 @@', '@@ -19,2 +20,2 @@', '@@ -9 +9 @@', '@@ -21 +22 @@'].join(
+      '\n',
+    );
+    expect(countOutOfScopeHunks(diff, scope)).toBe(0);
+  });
+  it('flags hunks clearly outside the scope, including pure insertions', () => {
+    const diff = ['@@ -2,3 +2,4 @@', '@@ -30,0 +32,2 @@', '@@ -15 +16 @@'].join('\n');
+    expect(countOutOfScopeHunks(diff, scope)).toBe(2);
+  });
+  it('treats an insertion right after the scope as in scope', () => {
+    expect(countOutOfScopeHunks('@@ -20,0 +21,3 @@', scope)).toBe(0);
+    expect(countOutOfScopeHunks('@@ -22,0 +23,3 @@', scope)).toBe(1);
+  });
+});
+
+describe('parseCommitBody', () => {
+  it('separates prose from Parallel trailers', () => {
+    const body =
+      'Rewrote the intro.\n\n- shorter\n\nParallel-Run: r1\nParallel-Agent: Claude Code\nParallel-Scope: a.md#L1-L3\n';
+    const { text, trailers } = parseCommitBody(body);
+    expect(text).toBe('Rewrote the intro.\n\n- shorter');
+    expect(trailers).toEqual({ Run: 'r1', Agent: 'Claude Code', Scope: 'a.md#L1-L3' });
+  });
+  it('returns empty trailers for a manual commit', () => {
+    expect(parseCommitBody('just a note').trailers).toEqual({});
+  });
+  it('ignores trailer-shaped lines outside the final paragraph', () => {
+    const body =
+      'Prose.\nParallel-Agent: Human\n\n- more\n\nParallel-Run: r1\nParallel-Agent: Codex';
+    const { text, trailers } = parseCommitBody(body);
+    expect(trailers.Agent).toBe('Codex');
+    expect(text).toContain('Parallel-Agent: Human');
+  });
+  it('treats a mixed last paragraph as prose', () => {
+    expect(parseCommitBody('Parallel-Agent: X\nnot a trailer').trailers).toEqual({});
+  });
+});
+
+describe('sanitizeRunRecord', () => {
+  const root = '/repo';
+  const good = {
+    version: 1,
+    id: 'run-1',
+    documentPath: 'docs/a.md',
+    baseSha: 'abcdef1234567',
+    status: 'finished',
+    createdAt: 'x',
+    instruction: 'i',
+    scope: { path: 'docs/a.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    candidates: [
+      {
+        id: 'c1',
+        label: 'A',
+        agentId: 'claude-code',
+        agentName: 'Claude',
+        isMain: false,
+        branch: 'parallel-doc/abc-a',
+        worktreePath: '/repo/.worktrees/parallel-doc/abc-a',
+        status: 'done',
+        commitSha: 'abcdef1234567',
+        startedAt: 'x',
+      },
+    ],
+  };
+  it('accepts a record this app would have written', () => {
+    expect(sanitizeRunRecord(root, good)).not.toBeNull();
+  });
+  it('rejects a worktree path outside .worktrees', () => {
+    const bad = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/home/me/Documents' }],
+    };
+    expect(sanitizeRunRecord(root, bad)).toBeNull();
+    const sneaky = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/repo/.worktrees/../../etc' }],
+    };
+    expect(sanitizeRunRecord(root, sneaky)).toBeNull();
+  });
+  it('rejects foreign branch names and bad shas', () => {
+    expect(
+      sanitizeRunRecord(root, { ...good, candidates: [{ ...good.candidates[0], branch: 'main' }] }),
+    ).toBeNull();
+    expect(
+      sanitizeRunRecord(root, {
+        ...good,
+        candidates: [{ ...good.candidates[0], commitSha: '--output=x' }],
+      }),
+    ).toBeNull();
+    expect(sanitizeRunRecord(root, { ...good, baseSha: 'HEAD' })).toBeNull();
+  });
+});
diff --git a/electron/documents/runs.ts b/electron/documents/runs.ts
new file mode 100644
index 000000000..1bd721b52
--- /dev/null
+++ b/electron/documents/runs.ts
@@ -0,0 +1,1550 @@
+/**
+ * Document workspaces: proposals from headless agents in isolated worktrees,
+ * accepted into the canonical branch as one readable commit.
+ *
+ * Git holds the content; `.parallel/runs/` holds the run records. Proposals
+ * change the canonical document only on acceptance; block edits are manual saves.
+ */
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import { errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from '../ipc/git.js';
+import { git, gitOk } from './git.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+import { appendCandidateLog, ensureDocumentLogsExclude } from './logs.js';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from './shared.js';
+import type {
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentHistoryEntry,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from './types.js';
+
+/** A proposal that runs longer than this is killed and marked failed. */
+const CANDIDATE_TIMEOUT_MS = 30 * 60_000;
+/** Longest instruction accepted from the renderer. */
+const MAX_INSTRUCTION_CHARS = 20_000;
+const RUNS_DIR = path.join('.parallel', 'runs');
+/** Annotations ride along with content commits; kept in sync with document-annotations.ts. */
+const ANNOTATIONS_FILE = path.posix.join('.parallel', 'annotations.json');
+const MAIN_WORKTREE_DIR = path.join('.worktrees', 'parallel-doc-main');
+const BRANCH_PREFIX = 'parallel-doc';
+const WATCH_DEBOUNCE_MS = 200;
+const WATCH_POLL_MS = 3_000;
+const STDERR_TAIL_CHARS = 4_000;
+const MAX_LOG_LINE_CHARS = 4_000;
+/** Grace period between SIGTERM and SIGKILL when cancelling a candidate. */
+const KILL_GRACE_MS = 5_000;
+/** How long rejection waits for killed processes to settle before cleaning up. */
+const SETTLE_WAIT_MS = 8_000;
+/** Files the app seeds into a worktree; never the agent's doing. */
+const SEEDED_PREFIXES = ['.claude/'];
+
+// --- Validation -----------------------------------------------------------
+
+/** A document path is repo-relative and stays inside the project's content. */
+export function validateDocumentPath(value: unknown): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('documentPath must be a string');
+  const normalized = value.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path.isAbsolute(normalized)) throw new Error('documentPath must be relative');
+  if (normalized.split('/').some((seg) => seg === '..' || seg === ''))
+    throw new Error('documentPath must not contain ".." or empty segments');
+  if (/^\.(parallel|worktrees|git)(\/|$)/.test(normalized))
+    throw new Error('documentPath must not point into .parallel, .worktrees or .git');
+  return normalized;
+}
+
+function validateRunId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{4,64}$/i.test(value))
+    throw new Error('runId is invalid');
+  return value;
+}
+
+function validateCandidateId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{1,64}$/i.test(value))
+    throw new Error('candidateId is invalid');
+  return value;
+}
+
+export function validateSha(value: unknown, label = 'sha'): string {
+  if (typeof value !== 'string' || !/^[0-9a-f]{7,64}$/i.test(value))
+    throw new Error(`${label} must be a commit hash`);
+  return value;
+}
+
+const BRANCH_RE = /^parallel-doc\/[a-z0-9][a-z0-9-]{0,80}$/;
+
+function validateScope(value: unknown, documentPath: string): DocumentScope {
+  if (!value || typeof value !== 'object') throw new Error('scope must be an object');
+  const s = value as Record<string, unknown>;
+  const wholeDocument = s.wholeDocument === true;
+  const startLine = Number(s.startLine);
+  const endLine = Number(s.endLine);
+  if (!wholeDocument) {
+    if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1)
+      throw new Error('scope lines must be positive integers');
+    if (endLine < startLine) throw new Error('scope endLine must not precede startLine');
+  }
+  const quote = typeof s.quote === 'string' ? s.quote : '';
+  const heading = typeof s.heading === 'string' && s.heading.trim() ? s.heading.trim() : undefined;
+  return {
+    path: documentPath,
+    wholeDocument,
+    startLine: wholeDocument ? 1 : startLine,
+    endLine: wholeDocument ? 1 : endLine,
+    quote: quote.slice(0, 20_000),
+    heading,
+  };
+}
+
+function validateCandidateSpecs(value: unknown): DocumentCandidateSpec[] {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('candidates must be a list');
+  if (value.length > MAX_DOCUMENT_CANDIDATES)
+    throw new Error(`At most ${MAX_DOCUMENT_CANDIDATES} candidates per run`);
+  const seen = new Set<string>();
+  return value.map((raw): DocumentCandidateSpec => {
+    if (!raw || typeof raw !== 'object') throw new Error('candidate must be an object');
+    const c = raw as Record<string, unknown>;
+    const id = validateCandidateId(c.id);
+    if (seen.has(id)) throw new Error('duplicate candidate id');
+    seen.add(id);
+    const str = (key: string): string => {
+      const v = c[key];
+      if (typeof v !== 'string' || !v.trim()) throw new Error(`candidate.${key} must be a string`);
+      return v;
+    };
+    const optStr = (key: string): string | undefined => {
+      const v = c[key];
+      if (v === undefined || v === null || v === '') return undefined;
+      if (typeof v !== 'string') throw new Error(`candidate.${key} must be a string`);
+      return v;
+    };
+    const label = str('label');
+    if (!/^[A-Za-z0-9 _-]{1,24}$/.test(label)) throw new Error('candidate.label is invalid');
+    const agentId = str('agentId');
+    if (!documentAgentSupport(agentId).headless)
+      throw new Error(`Agent "${agentId}" has no headless mode for document runs.`);
+    const command = str('command');
+    if (/[\s;&|<>$`'"\\]/.test(command)) throw new Error('candidate.command is invalid');
+    // Session ids and shas are handed to CLIs and git as positional values;
+    // a leading dash would turn them into flags.
+    const sessionId = optStr('sessionId');
+    if (sessionId && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(sessionId))
+      throw new Error('candidate.sessionId is invalid');
+    // Model names go straight to the CLI as a flag value: a leading dash
+    // would make a flag of it.
+    const model = optStr('model');
+    if (model && !/^[A-Za-z0-9][A-Za-z0-9_.:/@-]{0,63}$/.test(model))
+      throw new Error('candidate.model is invalid');
+    const effort = optStr('effort');
+    if (effort && !documentAgentSupport(agentId).efforts.includes(effort))
+      throw new Error(`candidate.effort "${effort}" is not a level ${agentId} accepts`);
+    const sessionLastShaRaw = optStr('sessionLastSha');
+    const sessionLastSha =
+      sessionLastShaRaw === undefined
+        ? undefined
+        : validateSha(sessionLastShaRaw, 'candidate.sessionLastSha');
+    return {
+      id,
+      label,
+      agentId,
+      agentName: str('agentName').slice(0, 64),
+      command,
+      isMain: c.isMain === true,
+      model,
+      effort,
+      sessionId,
+      sessionLastSha,
+      envFile: optStr('envFile'),
+    };
+  });
+}
+
+/** True when `candidate` (typically a persisted path) resolves under `dir`. */
+function isInside(dir: string, candidate: string): boolean {
+  const rel = path.relative(path.resolve(dir), path.resolve(candidate));
+  return rel.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// --- Snapshots and watcher ------------------------------------------------
+
+async function headSha(projectRoot: string): Promise<string | null> {
+  try {
+    return (await git(projectRoot, ['rev-parse', '--verify', 'HEAD'])).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function currentBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const out = (await git(projectRoot, ['symbolic-ref', '--short', '-q', 'HEAD'])).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Pathspec for "pending edits": tracked content only, never run records. */
+const CONTENT_PATHSPEC = ['--', '.', ':(exclude).parallel'];
+
+/**
+ * Uncommitted changes to tracked files. Untracked files are deliberately not
+ * "pending edits": sweeping them into a commit would put scratch files into
+ * the canonical history.
+ */
+async function isDirty(projectRoot: string): Promise<boolean> {
+  const out = await git(projectRoot, [
+    'status',
+    '--porcelain',
+    '--untracked-files=no',
+    ...CONTENT_PATHSPEC,
+  ]);
+  return out.trim().length > 0;
+}
+
+/**
+ * Where a document really lives inside the project. A clone can track a
+ * symlink pointing anywhere its owner can read, and the file's contents go on
+ * into prompts and annotations, so neither reading nor writing follows one.
+ */
+function documentFilePath(projectRoot: string, documentPath: string): string {
+  const target = path.join(fs.realpathSync(projectRoot), documentPath);
+  if (fs.realpathSync(target) !== target || !fs.lstatSync(target).isFile())
+    throw new Error('Cannot use a document reached through a symbolic link.');
+  return target;
+}
+
+export async function readDocumentSnapshot(
+  projectRoot: string,
+  documentPath: string,
+): Promise<DocumentSnapshot> {
+  let content = '';
+  let missing = false;
+  try {
+    content = await fs.promises.readFile(documentFilePath(projectRoot, documentPath), 'utf-8');
+  } catch {
+    missing = true;
+  }
+  const [sha, branch, dirty] = await Promise.all([
+    headSha(projectRoot),
+    currentBranch(projectRoot),
+    isDirty(projectRoot).catch(() => false),
+  ]);
+  return { content, headSha: sha, branch, dirty, missing };
+}
+
+/** Manual block edits share the project lock with acceptance and dispatch. */
+export async function writeDocumentBlock(
+  projectRoot: string,
+  args: Record<string, unknown>,
+): Promise<void> {
+  const documentPath = validateDocumentPath(args.documentPath);
+  const { expectedContent, startOffset, endOffset, replacement } = args;
+  if (typeof expectedContent !== 'string' || typeof replacement !== 'string')
+    throw new Error('Document content and replacement must be strings.');
+  if (expectedContent.length > 5_000_000 || replacement.length > 5_000_000)
+    throw new Error('The document is too large for block editing.');
+  if (
+    typeof startOffset !== 'number' ||
+    typeof endOffset !== 'number' ||
+    !Number.isInteger(startOffset) ||
+    !Number.isInteger(endOffset) ||
+    startOffset < 0 ||
+    endOffset < startOffset ||
+    endOffset > expectedContent.length
+  )
+    throw new Error('Invalid block range.');
+  return withProjectLock(projectRoot, async () => {
+    const target = documentFilePath(projectRoot, documentPath);
+    if (fs.readFileSync(target, 'utf8') !== expectedContent)
+      throw new Error(
+        'The document changed while you were editing. Copy your edit, then reopen the block.',
+      );
+    atomicWriteFileSync(
+      target,
+      expectedContent.slice(0, startOffset) + replacement + expectedContent.slice(endOffset),
+    );
+  });
+}
+
+interface DocumentWatcher {
+  fsWatcher: fs.FSWatcher | null;
+  debounce: ReturnType<typeof setTimeout> | null;
+  poll: ReturnType<typeof setInterval>;
+  lastKey: string;
+}
+
+const watchers = new Map<string, DocumentWatcher>();
+
+function snapshotKey(s: DocumentSnapshot): string {
+  return `${s.headSha ?? ''}|${s.branch ?? ''}|${s.dirty}|${s.missing}|${s.content.length}|${s.content}`;
+}
+
+export function startDocumentWatcher(
+  win: BrowserWindow,
+  key: string,
+  projectRoot: string,
+  documentPath: string,
+): void {
+  stopDocumentWatcher(key);
+  const docDir = path.dirname(path.join(projectRoot, documentPath));
+  const docName = path.basename(documentPath);
+
+  const emit = async () => {
+    const current = watchers.get(key);
+    if (!current || win.isDestroyed()) return;
+    const snapshot = await readDocumentSnapshot(projectRoot, documentPath).catch(() => null);
+    if (!snapshot) return;
+    const k = snapshotKey(snapshot);
+    if (k === current.lastKey) return;
+    current.lastKey = k;
+    win.webContents.send(IPC.DocumentChanged, { key, snapshot });
+  };
+
+  const schedule = () => {
+    const current = watchers.get(key);
+    if (!current) return;
+    if (current.debounce) clearTimeout(current.debounce);
+    current.debounce = setTimeout(() => {
+      current.debounce = null;
+      void emit();
+    }, WATCH_DEBOUNCE_MS);
+  };
+
+  let fsWatcher: fs.FSWatcher | null = null;
+  try {
+    fsWatcher = fs.watch(docDir, (_event, fileName) => {
+      if (fileName && fileName !== docName) return;
+      schedule();
+    });
+    fsWatcher.on('error', (err) => console.warn(`[documents] watcher error for ${docDir}:`, err));
+  } catch (err) {
+    console.warn(`[documents] cannot watch ${docDir}:`, err);
+  }
+
+  watchers.set(key, {
+    fsWatcher,
+    debounce: null,
+    // HEAD and dirty state change without touching the document (commits in
+    // a terminal, edits to other files), so poll those on a slow cadence.
+    poll: setInterval(() => void emit(), WATCH_POLL_MS),
+    lastKey: '',
+  });
+}
+
+export function stopDocumentWatcher(key: string): void {
+  const entry = watchers.get(key);
+  if (!entry) return;
+  if (entry.debounce) clearTimeout(entry.debounce);
+  clearInterval(entry.poll);
+  entry.fsWatcher?.close();
+  watchers.delete(key);
+}
+
+export function stopAllDocumentWatchers(): void {
+  for (const key of [...watchers.keys()]) stopDocumentWatcher(key);
+}
+
+// --- Run records ----------------------------------------------------------
+
+function runsDir(projectRoot: string): string {
+  return path.join(projectRoot, RUNS_DIR);
+}
+
+function runRecordRelPath(runId: string): string {
+  return path.posix.join('.parallel', 'runs', `${runId}.json`);
+}
+
+function runRecordPath(projectRoot: string, runId: string): string {
+  return path.join(runsDir(projectRoot), `${runId}.json`);
+}
+
+function writeRunRecord(projectRoot: string, run: DocumentRunRecord): void {
+  fs.mkdirSync(runsDir(projectRoot), { recursive: true });
+  atomicWriteFileSync(runRecordPath(projectRoot, run.id), JSON.stringify(run, null, 2) + '\n');
+}
+
+/**
+ * Run records travel with the repository, so a clone can carry records
+ * written by someone else. Anything that is later handed to git or the
+ * filesystem is checked against what this app would have produced; a record
+ * that fails is treated as absent.
+ */
+export function sanitizeRunRecord(projectRoot: string, raw: unknown): DocumentRunRecord | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const run = raw as DocumentRunRecord;
+  if (run.version !== 1 || !Array.isArray(run.candidates)) return null;
+  try {
+    validateRunId(run.id);
+    validateDocumentPath(run.documentPath);
+    validateSha(run.baseSha, 'baseSha');
+    if (run.refinement) {
+      validateRunId(run.refinement.runId);
+      validateCandidateId(run.refinement.candidateId);
+    }
+  } catch {
+    return null;
+  }
+  const worktreesDir = path.join(projectRoot, '.worktrees');
+  for (const c of run.candidates) {
+    if (!c || typeof c !== 'object') return null;
+    try {
+      validateCandidateId(c.id);
+      if (c.commitSha !== null && c.commitSha !== undefined) validateSha(c.commitSha, 'commitSha');
+    } catch {
+      return null;
+    }
+    if (typeof c.branch !== 'string' || !BRANCH_RE.test(c.branch)) return null;
+    if (typeof c.worktreePath !== 'string' || !isInside(worktreesDir, c.worktreePath)) return null;
+  }
+  return run;
+}
+
+function readRunRecord(projectRoot: string, runId: string): DocumentRunRecord | null {
+  try {
+    const raw = fs.readFileSync(runRecordPath(projectRoot, runId), 'utf-8');
+    return sanitizeRunRecord(projectRoot, JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function requireRunRecord(projectRoot: string, runId: string): DocumentRunRecord {
+  const run = readRunRecord(projectRoot, runId);
+  if (!run) throw new Error(`Run ${runId} not found`);
+  return run;
+}
+
+// --- Active runs ----------------------------------------------------------
+
+interface ActiveCandidate {
+  proc: ChildProcess;
+  timer: ReturnType<typeof setTimeout>;
+  killTimer: ReturnType<typeof setTimeout> | null;
+  cancelled: boolean;
+  /** Resolves once the process has exited and its record was written. */
+  settled: Promise<void>;
+  resolveSettled: () => void;
+  /** Record of the candidate this process works for. */
+  candidate: DocumentCandidateRecord;
+}
+
+interface ActiveRun {
+  projectRoot: string;
+  candidates: Map<string, ActiveCandidate>;
+  /** Dispatch is still handing candidates out, so an empty map is not the end. */
+  spawning: boolean;
+}
+
+const activeRuns = new Map<string, ActiveRun>();
+const projectLocks = new Map<string, Promise<void>>();
+
+function withProjectLock<T>(projectRoot: string, fn: () => Promise<T>): Promise<T> {
+  const key = path.resolve(projectRoot);
+  const prev = projectLocks.get(key) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  projectLocks.set(
+    key,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+function sendEvent(win: BrowserWindow, event: DocumentRunEvent): void {
+  if (!win.isDestroyed()) win.webContents.send(IPC.DocumentRunEvent, event);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/** Whether an active run in this project still has its main candidate working. */
+function mainSessionBusy(projectRoot: string): boolean {
+  const root = path.resolve(projectRoot);
+  for (const run of activeRuns.values()) {
+    if (path.resolve(run.projectRoot) !== root) continue;
+    for (const entry of run.candidates.values()) {
+      if (entry.candidate.isMain) return true;
+    }
+  }
+  return false;
+}
+
+/** Kills a candidate's whole process group, escalating to SIGKILL after a grace period. */
+function killCandidate(entry: ActiveCandidate): void {
+  const pid = entry.proc.pid;
+  if (!pid || entry.proc.exitCode !== null || entry.proc.signalCode !== null) return;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      // Negative pid: the process group created by `detached: true`.
+      process.kill(-pid, sig);
+    } catch {
+      try {
+        entry.proc.kill(sig);
+      } catch {
+        // Already gone.
+      }
+    }
+  };
+  signal('SIGTERM');
+  if (!entry.killTimer) {
+    entry.killTimer = setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS);
+    entry.killTimer.unref?.();
+  }
+}
+
+/** Runs the app persisted as running but that no process backs any more. */
+function reconcileInterrupted(projectRoot: string, run: DocumentRunRecord): DocumentRunRecord {
+  if (run.status !== 'running' || activeRuns.has(run.id)) return run;
+  for (const c of run.candidates) {
+    if (c.status === 'running') {
+      c.status = 'interrupted';
+      c.finishedAt = nowIso();
+      c.error = 'The app was closed while this proposal was running.';
+    }
+  }
+  run.status = 'finished';
+  run.finishedAt = run.finishedAt ?? nowIso();
+  writeRunRecord(projectRoot, run);
+  return run;
+}
+
+export function listDocumentRuns(projectRoot: string): DocumentRunRecord[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(runsDir(projectRoot)).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const runs: DocumentRunRecord[] = [];
+  for (const name of names) {
+    const run = readRunRecord(projectRoot, name.slice(0, -'.json'.length));
+    if (run) runs.push(reconcileInterrupted(projectRoot, run));
+  }
+  runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  return runs;
+}
+
+/** The run whose candidate owns `branch`, if any record says so. */
+function runOwningBranch(projectRoot: string, branch: string): DocumentRunRecord | undefined {
+  return listDocumentRuns(projectRoot).find((r) => r.candidates.some((c) => c.branch === branch));
+}
+
+// --- Pending manual edits -------------------------------------------------
+
+/**
+ * Tracked content that differs from HEAD: what the user has been editing.
+ * `--diff-filter=MDT` leaves out additions, so a new file the user staged by
+ * hand is not swept into a commit this app writes.
+ */
+async function pendingContentPaths(projectRoot: string): Promise<string[]> {
+  const out = await git(projectRoot, [
+    'diff',
+    '--name-only',
+    '-z',
+    '--diff-filter=MDT',
+    'HEAD',
+    ...CONTENT_PATHSPEC,
+  ]).catch(() => '');
+  return out.split('\0').filter(Boolean);
+}
+
+/**
+ * Commits the user's edits to tracked files as a plain commit, so the run
+ * has a real base. Returns HEAD afterwards. Throws in an empty repository.
+ */
+export async function commitPendingEdits(projectRoot: string): Promise<string> {
+  ensureWorktreeContainerExclude(projectRoot);
+  const paths = await pendingContentPaths(projectRoot);
+  await git(projectRoot, ['add', '-u', ...CONTENT_PATHSPEC]);
+  if (await stageAnnotations(projectRoot)) paths.push(ANNOTATIONS_FILE);
+  if (paths.length > 0) await commitPaths(projectRoot, 'Manual edits', paths);
+  const sha = await headSha(projectRoot);
+  if (!sha) throw new Error('The project repository has no commits yet.');
+  return sha;
+}
+
+/**
+ * Commits exactly `paths`. `--only` takes them from the working tree and
+ * leaves the rest of the index alone, so whatever the user had staged stays
+ * staged instead of riding along in a commit this app attributes to itself.
+ */
+async function commitPaths(projectRoot: string, message: string, paths: string[]): Promise<void> {
+  await git(projectRoot, ['commit', '-q', '--only', '-m', message, '--', ...paths]);
+}
+
+/**
+ * Annotations are committed alongside content and metadata, never on their
+ * own. Returns true when the file exists and differs from HEAD.
+ */
+async function stageAnnotations(projectRoot: string): Promise<boolean> {
+  if (!fs.existsSync(path.join(projectRoot, ANNOTATIONS_FILE))) return false;
+  if (!(await gitOk(projectRoot, ['add', '-f', '--', ANNOTATIONS_FILE]))) return false;
+  return !(await gitOk(projectRoot, ['diff', '--cached', '--quiet', '--', ANNOTATIONS_FILE]));
+}
+
+// --- Worktrees ------------------------------------------------------------
+
+function shortRunId(runId: string): string {
+  return runId.replace(/-/g, '').slice(0, 8);
+}
+
+function candidateBranch(runId: string, label: string): string {
+  return `${BRANCH_PREFIX}/${shortRunId(runId)}-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+}
+
+/** The main session keeps one worktree so its working directory never changes. */
+async function prepareMainWorktree(
+  projectRoot: string,
+  branch: string,
+  baseSha: string,
+): Promise<string> {
+  const worktreePath = path.join(projectRoot, MAIN_WORKTREE_DIR);
+  ensureWorktreeContainerExclude(projectRoot);
+  await gitOk(projectRoot, ['worktree', 'prune']);
+  if (!fs.existsSync(path.join(worktreePath, '.git'))) {
+    fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+    await git(projectRoot, ['worktree', 'add', '-b', branch, worktreePath, baseSha]);
+    return worktreePath;
+  }
+  const previous = await currentBranch(worktreePath);
+  await git(worktreePath, ['reset', '--hard', '-q']);
+  await git(worktreePath, ['clean', '-fdq']);
+  await git(worktreePath, ['checkout', '-q', '-B', branch, baseSha]);
+  // The branch the worktree just left belongs to an earlier run. Drop it
+  // once that run is settled; a proposal still under review keeps its branch.
+  if (previous && previous !== branch && BRANCH_RE.test(previous)) {
+    const owner = runOwningBranch(projectRoot, previous);
+    if (!owner || owner.status === 'accepted' || owner.status === 'rejected') {
+      await gitOk(projectRoot, ['branch', '-D', previous]);
+    }
+  }
+  return worktreePath;
+}
+
+async function prepareAlternateWorktree(
+  projectRoot: string,
+  branch: string,
+  baseSha: string,
+): Promise<string> {
+  const { path: worktreePath } = await createWorktree(projectRoot, branch, [], baseSha, true);
+  return worktreePath;
+}
+
+async function cleanupCandidate(
+  projectRoot: string,
+  candidate: DocumentCandidateRecord,
+): Promise<void> {
+  // Records are sanitized on load, but this is the destructive step: check again.
+  if (!BRANCH_RE.test(candidate.branch)) return;
+  if (!isInside(path.join(projectRoot, '.worktrees'), candidate.worktreePath)) return;
+  if (candidate.isMain) {
+    // The persistent worktree stays; only drop the branch when it is no
+    // longer checked out there (the next dispatch moves it and deletes it).
+    const mainPath = path.join(projectRoot, MAIN_WORKTREE_DIR);
+    const checkedOut = await currentBranch(mainPath).catch(() => null);
+    if (checkedOut !== candidate.branch)
+      await gitOk(projectRoot, ['branch', '-D', candidate.branch]);
+    return;
+  }
+  await removeWorktree(projectRoot, candidate.branch, true, candidate.worktreePath).catch((err) =>
+    console.warn(`[documents] cleanup of ${candidate.branch} failed:`, err),
+  );
+}
+
+// --- Scope enforcement ----------------------------------------------------
+
+/** Counts hunks of a `-U0` diff whose old-file range lies outside the scope. */
+export function countOutOfScopeHunks(diffU0: string, scope: DocumentScope): number {
+  if (scope.wholeDocument) return 0;
+  let count = 0;
+  const re = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(diffU0)) !== null) {
+    const start = Number(m[1]);
+    const len = m[2] === undefined ? 1 : Number(m[2]);
+    // A pure insertion reports the line *before* it with length 0; treat it
+    // as touching that line and the next.
+    const from = start;
+    const to = len === 0 ? start + 1 : start + len - 1;
+    // One line of slack on either side: agents routinely re-wrap the
+    // neighbouring blank line or paragraph boundary.
+    const inScope = to >= scope.startLine - 1 && from <= scope.endLine + 1;
+    if (!inScope) count++;
+  }
+  return count;
+}
+
+// --- Dispatch -------------------------------------------------------------
+
+export interface DispatchDocumentRunArgs {
+  projectRoot: string;
+  documentPath: unknown;
+  instruction: unknown;
+  scope: unknown;
+  candidates: unknown;
+  refinement?: unknown;
+}
+
+function parseChangedPaths(porcelainZ: string): string[] {
+  const out: string[] = [];
+  for (const entry of porcelainZ.split('\0')) {
+    if (!entry.trim()) continue;
+    // "XY path". Renames would add a second, status-less NUL entry that this
+    // would mangle — callers reset the index first, so status never reports
+    // one here.
+    const p = entry.slice(3);
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+function trailerBlock(entries: [string, string][]): string {
+  return entries
+    .filter(([, v]) => v.trim().length > 0)
+    .map(([k, v]) => `Parallel-${k}: ${v.replace(/\s+/g, ' ').trim()}`)
+    .join('\n');
+}
+
+function scopeTrailer(scope: DocumentScope): string {
+  if (scope.wholeDocument) return scope.path;
+  return `${scope.path}#L${scope.startLine}-L${scope.endLine}`;
+}
+
+function commitTitle(summary: string, fallback: string): string {
+  const line = (summary || fallback).split('\n')[0].trim();
+  return line.length > 72 ? line.slice(0, 69).trimEnd() + '…' : line;
+}
+
+/** Agent-written text that lands in a commit body: one line, no trailer look-alikes. */
+function bodyLine(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .replace(/^Parallel-/i, 'Parallel ')
+    .trim();
+}
+
+/**
+ * Turns whatever the agent left in its worktree into a proposal commit that
+ * contains only the document, and records what was stripped.
+ */
+async function finalizeCandidate(
+  run: DocumentRunRecord,
+  candidate: DocumentCandidateRecord,
+  outcome: { resultText: string; sessionId?: string; error?: string },
+  exitCode: number | null,
+  stderrTail: string,
+  cancelled: boolean,
+): Promise<void> {
+  const { worktreePath } = candidate;
+  candidate.exitCode = exitCode;
+  candidate.finishedAt = nowIso();
+  if (outcome.sessionId) candidate.sessionId = outcome.sessionId;
+  candidate.resultText = outcome.resultText.slice(0, 50_000);
+
+  if (cancelled) {
+    candidate.status = 'cancelled';
+    candidate.error = 'Cancelled.';
+    return;
+  }
+
+  try {
+    // The worktree must still be on this candidate's branch; otherwise the
+    // commit would land on someone else's proposal.
+    const onBranch = await currentBranch(worktreePath);
+    if (onBranch !== candidate.branch) {
+      throw new Error(
+        `The worktree moved to '${onBranch ?? 'a detached HEAD'}' while the agent was working.`,
+      );
+    }
+
+    // An agent with a shell may have staged files; scope is judged against
+    // HEAD, not the index, so unstage everything first.
+    await git(worktreePath, ['reset', '-q']);
+    const docPath = run.documentPath;
+    const changed = parseChangedPaths(
+      await git(worktreePath, ['status', '--porcelain', '-z', '--untracked-files=all']),
+    );
+    const outOfScope = changed.filter(
+      (p) => p !== docPath && !SEEDED_PREFIXES.some((prefix) => p.startsWith(prefix)),
+    );
+    if (changed.some((p) => p !== docPath)) {
+      // Keep the document edit, drop everything else.
+      const docAbs = path.join(worktreePath, docPath);
+      const keep = fs.existsSync(docAbs) ? fs.readFileSync(docAbs, 'utf-8') : null;
+      await git(worktreePath, ['checkout', '-q', '--', '.']);
+      await git(worktreePath, ['clean', '-fdq']);
+      if (keep !== null) fs.writeFileSync(docAbs, keep);
+    }
+    if (outOfScope.length > 0) candidate.outOfScopeFiles = outOfScope.slice(0, 50);
+
+    const docChanged = !(await gitOk(worktreePath, ['diff', '--quiet', 'HEAD', '--', docPath]));
+    const rationale = parseDocumentRationale(outcome.resultText);
+    candidate.rationale = rationale;
+
+    if (!docChanged) {
+      candidate.noChanges = true;
+      candidate.commitSha = null;
+      candidate.status = outcome.error || (exitCode !== 0 && exitCode !== null) ? 'failed' : 'done';
+      candidate.error = outcome.error ?? (candidate.status === 'failed' ? stderrTail : undefined);
+      return;
+    }
+
+    const diffU0 = await git(worktreePath, ['diff', '-U0', 'HEAD', '--', docPath]);
+    const strayHunks = countOutOfScopeHunks(diffU0, run.scope);
+    if (strayHunks > 0) candidate.outOfScopeHunks = strayHunks;
+
+    const body = [
+      commitTitle(bodyLine(rationale.summary), `Proposal from ${candidate.agentName}`),
+      '',
+      ...rationale.changes.map((c) => `- ${bodyLine(c)}`),
+      '',
+      trailerBlock([
+        ['Run', run.id],
+        ['Agent', candidate.agentName],
+        ...modelTrailers(candidate),
+        ['Candidate', candidate.label],
+        ['Scope', scopeTrailer(run.scope)],
+        ['Base', run.baseSha],
+      ]),
+    ].join('\n');
+    await git(worktreePath, ['add', '--', docPath]);
+    await git(worktreePath, ['commit', '-q', '--only', '-m', body, '--', docPath]);
+    const committed = (await git(worktreePath, ['show', '--format=', '--name-only', 'HEAD']))
+      .split('\n')
+      .filter((l) => l.trim());
+    if (committed.length !== 1 || committed[0] !== docPath) {
+      throw new Error(`Proposal commit touched ${committed.join(', ')} instead of ${docPath}.`);
+    }
+    candidate.commitSha = (await git(worktreePath, ['rev-parse', 'HEAD'])).trim();
+    candidate.status = 'done';
+    if (outcome.error) candidate.error = outcome.error;
+  } catch (err) {
+    candidate.status = 'failed';
+    candidate.error = errMessage(err);
+    candidate.commitSha = null;
+  }
+}
+
+/**
+ * Persists a finished candidate under the project lock, re-reading the
+ * record so a note or a rejection written meanwhile survives. Returns the
+ * record as stored.
+ */
+async function storeCandidateResult(
+  projectRoot: string,
+  runId: string,
+  candidate: DocumentCandidateRecord,
+  allSettled: boolean,
+): Promise<DocumentRunRecord | null> {
+  return withProjectLock(projectRoot, async () => {
+    const fresh = readRunRecord(projectRoot, runId);
+    if (!fresh) return null;
+    const idx = fresh.candidates.findIndex((c) => c.id === candidate.id);
+    const stored = idx >= 0 ? fresh.candidates[idx] : undefined;
+    const merged: DocumentCandidateRecord = { ...candidate, note: stored?.note ?? candidate.note };
+    // A rejection that landed first wins over the process's own verdict.
+    if (stored?.status === 'cancelled' && fresh.status === 'rejected') merged.status = 'cancelled';
+    if (idx >= 0) fresh.candidates[idx] = merged;
+    else fresh.candidates.push(merged);
+    if (allSettled && fresh.status === 'running') {
+      fresh.status = 'finished';
+      fresh.finishedAt = nowIso();
+    }
+    writeRunRecord(projectRoot, fresh);
+    return fresh;
+  });
+}
+
+function spawnCandidate(
+  win: BrowserWindow,
+  projectRoot: string,
+  run: DocumentRunRecord,
+  spec: DocumentCandidateSpec,
+  candidate: DocumentCandidateRecord,
+  prompt: string,
+): void {
+  const active = activeRuns.get(run.id);
+  if (!active) return;
+
+  const launch = buildHeadlessLaunch({
+    agentId: spec.agentId,
+    command: spec.command,
+    prompt,
+    sessionId: spec.sessionId,
+    newSessionId: randomUUID(),
+    model: spec.model,
+    effort: spec.effort,
+  });
+  const fileEnv = spec.envFile?.trim() ? loadEnvFile(spec.envFile) : {};
+  const env = buildPtySpawnEnv({}, fileEnv);
+  const parser = createHeadlessParser(spec.agentId);
+
+  const proc = spawn(launch.command, launch.args, {
+    cwd: candidate.worktreePath,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // Own process group, so cancelling reaches the CLI's children too.
+    detached: true,
+  });
+  proc.stdout?.setEncoding('utf8');
+  proc.stderr?.setEncoding('utf8');
+
+  let resolveSettled: () => void = () => undefined;
+  const settled = new Promise<void>((resolve) => {
+    resolveSettled = resolve;
+  });
+  const entry: ActiveCandidate = {
+    proc,
+    cancelled: false,
+    killTimer: null,
+    settled,
+    resolveSettled,
+    candidate,
+    timer: setTimeout(() => {
+      candidate.error = 'Timed out.';
+      killCandidate(entry);
+    }, CANDIDATE_TIMEOUT_MS),
+  };
+  active.candidates.set(candidate.id, entry);
+
+  let stderrTail = '';
+  const log = (text: string) => {
+    const clipped =
+      text.length > MAX_LOG_LINE_CHARS ? text.slice(0, MAX_LOG_LINE_CHARS) + '…' : text;
+    // The rail shows a bounded tail; the file keeps everything for later reading.
+    appendCandidateLog(projectRoot, run.id, candidate.id, clipped);
+    sendEvent(win, {
+      type: 'log',
+      projectRoot,
+      runId: run.id,
+      candidateId: candidate.id,
+      text: clipped,
+    });
+  };
+
+  proc.stdout?.on('data', (chunk: string) => {
+    for (const line of parser.feed(chunk)) log(line);
+  });
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+    if (chunk.trim()) log(chunk.trimEnd());
+  });
+
+  let settledOnce = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settledOnce) return;
+    settledOnce = true;
+    clearTimeout(entry.timer);
+    if (entry.killTimer) clearTimeout(entry.killTimer);
+    const outcome = parser.finish();
+    if (spawnError) outcome.error = spawnError.message;
+    else if (candidate.error === 'Timed out.') outcome.error = 'Timed out.';
+    await finalizeCandidate(run, candidate, outcome, exitCode, stderrTail, entry.cancelled);
+    active.candidates.delete(candidate.id);
+    const allSettled = active.candidates.size === 0 && !active.spawning;
+    if (allSettled) activeRuns.delete(run.id);
+    let stored: DocumentRunRecord | null = null;
+    try {
+      stored = await storeCandidateResult(projectRoot, run.id, candidate, allSettled);
+    } catch (err) {
+      console.warn('[documents] failed to write run record:', err);
+    }
+    sendEvent(win, { type: 'candidate', projectRoot, runId: run.id, candidate });
+    if (stored && stored.status !== 'running') {
+      sendEvent(win, { type: 'run', projectRoot, run: stored });
+    }
+    entry.resolveSettled();
+  };
+
+  proc.on('close', (code) => void settle(code));
+  proc.on('error', (err) => void settle(1, err));
+}
+
+export async function dispatchDocumentRun(
+  win: BrowserWindow,
+  args: DispatchDocumentRunArgs,
+): Promise<DocumentRunRecord> {
+  const { projectRoot } = args;
+  const documentPath = validateDocumentPath(args.documentPath);
+  if (typeof args.instruction !== 'string' || !args.instruction.trim())
+    throw new Error('instruction must be a non-empty string');
+  if (args.instruction.length > MAX_INSTRUCTION_CHARS) throw new Error('instruction is too long');
+  const instruction = args.instruction;
+  let scope = validateScope(args.scope, documentPath);
+  let refinement: DocumentRunRecord['refinement'];
+  if (args.refinement !== undefined) {
+    if (!args.refinement || typeof args.refinement !== 'object')
+      throw new Error('refinement must identify a candidate');
+    const source = args.refinement as Record<string, unknown>;
+    refinement = {
+      runId: validateRunId(source.runId),
+      candidateId: validateCandidateId(source.candidateId),
+    };
+    // A rewritten candidate has different lines. Review the entire revision.
+    scope = validateScope({ wholeDocument: true }, documentPath);
+  }
+  const specs = validateCandidateSpecs(args.candidates);
+  if (refinement) {
+    for (const spec of specs) {
+      spec.isMain = false;
+      spec.sessionId = undefined;
+      spec.sessionLastSha = undefined;
+    }
+  }
+  if (specs.filter((s) => s.isMain).length > 1) throw new Error('Only one main candidate per run');
+  for (const spec of specs) validateCommand(spec.command);
+
+  return withProjectLock(projectRoot, async () => {
+    let sourceRun: DocumentRunRecord | undefined;
+    let sourceContent: string | undefined;
+    if (refinement) {
+      sourceRun = requireRunRecord(projectRoot, refinement.runId);
+      if (typeof sourceRun.instruction !== 'string')
+        throw new Error('The original proposal has an invalid instruction.');
+      if (sourceRun.documentPath !== documentPath)
+        throw new Error('The candidate belongs to another document.');
+      if (sourceRun.status !== 'finished' && sourceRun.status !== 'stale')
+        throw new Error('Only proposals awaiting review can be refined.');
+      const source = sourceRun.candidates.find((c) => c.id === refinement.candidateId);
+      if (source?.status !== 'done' || !source.commitSha)
+        throw new Error('The candidate has no completed proposal to refine.');
+      const content = await getDocumentAtCommit(projectRoot, source.commitSha, documentPath);
+      if (content === null) throw new Error('The proposal document no longer exists.');
+      sourceContent = content;
+    }
+    if (!fs.existsSync(path.join(projectRoot, documentPath)))
+      throw new Error(`Document not found: ${documentPath}`);
+    if (specs.some((s) => s.isMain) && mainSessionBusy(projectRoot)) {
+      throw new Error(
+        'The main session is still working on an earlier run. Wait for it or cancel that run first.',
+      );
+    }
+    // Retain the canonical ancestor, so acceptance integrates both the original
+    // proposal and its refinement. Dispatch never changes the canonical checkout.
+    const baseSha = sourceRun?.baseSha ?? (await commitPendingEdits(projectRoot));
+    // Candidate worktrees are made from `baseSha`, and untracked files are
+    // deliberately not swept into it: without this the agents would be asked to
+    // edit a file that is not there and every proposal would come back empty.
+    if (!(await gitOk(projectRoot, ['cat-file', '-e', `${baseSha}:${documentPath}`])))
+      throw new Error(
+        `${documentPath} is not committed yet. Commit it first — agents work in a copy of the last commit.`,
+      );
+    const runId = randomUUID();
+    const run: DocumentRunRecord = {
+      version: 1,
+      id: runId,
+      documentPath,
+      createdAt: nowIso(),
+      instruction,
+      scope,
+      baseSha,
+      status: 'running',
+      candidates: [],
+      refinement,
+    };
+
+    const prepared: { spec: DocumentCandidateSpec; candidate: DocumentCandidateRecord }[] = [];
+    try {
+      for (const spec of specs) {
+        const branch = candidateBranch(runId, spec.label);
+        const worktreePath = spec.isMain
+          ? await prepareMainWorktree(projectRoot, branch, baseSha)
+          : await prepareAlternateWorktree(projectRoot, branch, baseSha);
+        const candidate: DocumentCandidateRecord = {
+          id: spec.id,
+          label: spec.label,
+          agentId: spec.agentId,
+          agentName: spec.agentName,
+          isMain: spec.isMain,
+          model: spec.model,
+          effort: spec.effort,
+          branch,
+          worktreePath,
+          status: 'running',
+          commitSha: null,
+          startedAt: nowIso(),
+        };
+        run.candidates.push(candidate);
+        prepared.push({ spec, candidate });
+        if (sourceContent !== undefined) {
+          const target = path.join(worktreePath, documentPath);
+          if (fs.realpathSync(target) !== path.join(fs.realpathSync(worktreePath), documentPath))
+            throw new Error('Cannot refine a document through a symbolic link.');
+          atomicWriteFileSync(target, sourceContent);
+        }
+      }
+    } catch (err) {
+      for (const { candidate } of prepared) await cleanupCandidate(projectRoot, candidate);
+      throw err;
+    }
+
+    writeRunRecord(projectRoot, run);
+    ensureDocumentLogsExclude(projectRoot);
+    activeRuns.set(runId, { projectRoot, candidates: new Map(), spawning: true });
+
+    try {
+      for (const { spec, candidate } of prepared) {
+        let catchUpDiff: string | undefined;
+        if (spec.sessionId && spec.sessionLastSha && spec.sessionLastSha !== baseSha) {
+          catchUpDiff = await git(projectRoot, [
+            'diff',
+            `${spec.sessionLastSha}..${baseSha}`,
+            '--',
+            documentPath,
+          ]).catch(() => undefined);
+        }
+        const prompt = buildDocumentPrompt({
+          documentPath,
+          scope,
+          instruction,
+          catchUpDiff,
+          refinementInstruction: sourceRun?.instruction,
+        });
+        try {
+          spawnCandidate(win, projectRoot, run, spec, candidate, prompt);
+        } catch (err) {
+          candidate.status = 'failed';
+          candidate.error = errMessage(err);
+          candidate.finishedAt = nowIso();
+        }
+      }
+    } finally {
+      // A candidate can settle while this loop awaits a catch-up diff. Until
+      // the loop is done an empty candidate map does not mean the run ended,
+      // so `spawning` held it open; release it here however the loop left.
+      const stillActive = activeRuns.get(runId);
+      if (stillActive) {
+        stillActive.spawning = false;
+        if (stillActive.candidates.size === 0) activeRuns.delete(runId);
+      }
+    }
+
+    // The settle path writes the authoritative record, so merge in only the
+    // candidates this function knows about — the ones whose spawn threw —
+    // instead of writing the in-memory copy over it and resurrecting `running`.
+    const stored = readRunRecord(projectRoot, runId) ?? run;
+    for (const { candidate } of prepared) {
+      if (candidate.status !== 'failed') continue;
+      const idx = stored.candidates.findIndex((c) => c.id === candidate.id);
+      if (idx >= 0) stored.candidates[idx] = candidate;
+    }
+    if (stored.status === 'running' && !activeRuns.has(runId)) {
+      stored.status = 'finished';
+      stored.finishedAt = stored.finishedAt ?? nowIso();
+    }
+    writeRunRecord(projectRoot, stored);
+    sendEvent(win, { type: 'run', projectRoot, run: stored });
+    return stored;
+  });
+}
+
+/** Signals every candidate of a run; returns a promise that settles when they have exited. */
+function killRun(runId: string): Promise<void> {
+  const active = activeRuns.get(runId);
+  if (!active) return Promise.resolve();
+  const pending: Promise<void>[] = [];
+  for (const entry of active.candidates.values()) {
+    entry.cancelled = true;
+    killCandidate(entry);
+    pending.push(entry.settled);
+  }
+  return Promise.all(pending).then(() => undefined);
+}
+
+export function cancelDocumentRun(runId: unknown): void {
+  void killRun(validateRunId(runId));
+}
+
+// --- Accept / reject ------------------------------------------------------
+
+/** `Model` and `Effort` trailers, only when the run departed from the CLI's defaults. */
+function modelTrailers(candidate: DocumentCandidateRecord): [string, string][] {
+  const out: [string, string][] = [];
+  if (candidate.model) out.push(['Model', candidate.model]);
+  if (candidate.effort) out.push(['Effort', candidate.effort]);
+  return out;
+}
+
+/**
+ * The document as it stands at a commit, or null when the path is not there.
+ * Null is an answer, not a swallowed error: the caller treats "cannot read the
+ * base" the same as "the base moved".
+ */
+async function documentBlob(
+  projectRoot: string,
+  sha: string,
+  documentPath: string,
+): Promise<string | null> {
+  try {
+    return (await git(projectRoot, ['rev-parse', `${sha}:${documentPath}`])).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Every line of a composed document must come from the base or the candidate:
+ * it is a mix of the two, never new prose. The renderer builds it, so this is
+ * the one acceptance path git does not verify on its own — the check keeps a
+ * renderer fault from being committed under the agent's name.
+ */
+function isMixOf(content: string, base: string, candidate: string): boolean {
+  const known = new Set([...base.split('\n'), ...candidate.split('\n')].map((l) => l.trim()));
+  return content.split('\n').every((line) => known.has(line.trim()));
+}
+
+/** The reader's choice when they declined some of a candidate's changes. */
+export interface PartialAcceptance {
+  content: string;
+  accepted: number;
+  total: number;
+}
+
+function validatePartial(value: unknown): PartialAcceptance | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'object') throw new Error('Invalid partial acceptance.');
+  const { content, accepted, total } = value as Record<string, unknown>;
+  if (typeof content !== 'string') throw new Error('The composed document must be a string.');
+  if (content.trim() === '') throw new Error('A partial acceptance cannot empty the document.');
+  if (content.length > 5_000_000) throw new Error('The document is too large to accept in parts.');
+  if (
+    !Number.isInteger(accepted) ||
+    !Number.isInteger(total) ||
+    (accepted as number) < 1 ||
+    (total as number) < (accepted as number)
+  )
+    throw new Error('Invalid partial acceptance counts.');
+  return { content, accepted: accepted as number, total: total as number };
+}
+
+function integrationMessage(run: DocumentRunRecord, candidate: DocumentCandidateRecord): string {
+  const rationale = candidate.rationale;
+  const lines = [
+    commitTitle(bodyLine(rationale?.summary ?? ''), `Accept proposal from ${candidate.agentName}`),
+    '',
+  ];
+  const section = (label: string, items: string[] | undefined) => {
+    if (!items?.length) return;
+    lines.push(label, ...items.map((c) => `- ${bodyLine(c)}`), '');
+  };
+  section('Changes:', rationale?.changes);
+  section('Assumptions:', rationale?.assumptions);
+  section('Open questions:', rationale?.questions);
+  lines.push(
+    trailerBlock([
+      ['Run', run.id],
+      ['Agent', candidate.agentName],
+      ...modelTrailers(candidate),
+      ['Candidate', candidate.label],
+      ...(run.partialAcceptance
+        ? ([
+            ['Partial', `${run.partialAcceptance.accepted}/${run.partialAcceptance.total} changes`],
+          ] as [string, string][])
+        : []),
+      ['Scope', scopeTrailer(run.scope)],
+      ['Base', run.baseSha],
+      ['Instruction', run.instruction.slice(0, 300)],
+    ]),
+  );
+  return lines.join('\n');
+}
+
+export async function acceptDocumentCandidate(
+  projectRoot: string,
+  runIdRaw: unknown,
+  candidateIdRaw: unknown,
+  partialRaw?: unknown,
+): Promise<{ sha: string }> {
+  const runId = validateRunId(runIdRaw);
+  const candidateId = validateCandidateId(candidateIdRaw);
+  const partial = validatePartial(partialRaw);
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    if (run.status === 'accepted') throw new Error('This run was already accepted.');
+    if (run.status === 'rejected') throw new Error('This run was rejected.');
+    if (activeRuns.has(runId)) throw new Error('Wait for every candidate to finish first.');
+    const candidate = run.candidates.find((c) => c.id === candidateId);
+    if (!candidate) throw new Error('Candidate not found');
+    if (!candidate.commitSha) throw new Error('This candidate produced no change to accept.');
+    if (!(await gitOk(projectRoot, ['cat-file', '-e', `${candidate.commitSha}^{commit}`])))
+      throw new Error('The proposal commit no longer exists.');
+
+    await commitPendingEdits(projectRoot);
+    const head = await headSha(projectRoot);
+    if (partial) {
+      // The composition was made from the base, so it may only be written when
+      // the document has not moved since. An unrelated commit is fine; a change
+      // to this document is not, and merging a hand-picked mix three ways would
+      // be guessing at which side each declined passage should come from.
+      const baseBlob = await documentBlob(projectRoot, run.baseSha, run.documentPath);
+      const headBlob = head ? await documentBlob(projectRoot, head, run.documentPath) : null;
+      if (!baseBlob || baseBlob !== headBlob) {
+        run.status = 'stale';
+        writeRunRecord(projectRoot, run);
+        throw new Error(
+          'The document changed since this proposal was made, so the changes you picked no longer apply. Re-run it.',
+        );
+      }
+      const [baseText, candidateText] = await Promise.all([
+        getDocumentAtCommit(projectRoot, run.baseSha, run.documentPath),
+        getDocumentAtCommit(projectRoot, candidate.commitSha, run.documentPath),
+      ]);
+      if (
+        baseText === null ||
+        candidateText === null ||
+        !isMixOf(partial.content, baseText, candidateText)
+      )
+        throw new Error('The composed document does not match the proposal it came from.');
+      atomicWriteFileSync(documentFilePath(projectRoot, run.documentPath), partial.content);
+    } else if (head !== run.baseSha) {
+      // The base moved: a three-way squash merge either applies cleanly or
+      // the proposal is stale. Never leave a half-merged tree behind.
+      const ok = await gitOk(projectRoot, ['merge', '--squash', '-q', candidate.commitSha]);
+      if (!ok) {
+        await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
+        run.status = 'stale';
+        writeRunRecord(projectRoot, run);
+        throw new Error(
+          'The document changed since this proposal was made and the change no longer applies. Re-run it.',
+        );
+      }
+    } else {
+      await git(projectRoot, ['merge', '--squash', '-q', candidate.commitSha]);
+    }
+
+    run.status = 'accepted';
+    run.acceptedCandidateId = candidateId;
+    run.partialAcceptance = partial
+      ? { accepted: partial.accepted, total: partial.total }
+      : undefined;
+    run.finishedAt = run.finishedAt ?? nowIso();
+    writeRunRecord(projectRoot, run);
+    try {
+      await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      // The proposal commit was verified to hold the document alone, so the
+      // squash brought in exactly that path; a partial acceptance wrote that
+      // same path itself.
+      const paths = [run.documentPath, runRecordRelPath(runId)];
+      if (await stageAnnotations(projectRoot)) paths.push(ANNOTATIONS_FILE);
+      await commitPaths(projectRoot, integrationMessage(run, candidate), paths);
+    } catch (err) {
+      await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
+      run.status = 'finished';
+      run.acceptedCandidateId = undefined;
+      run.partialAcceptance = undefined;
+      writeRunRecord(projectRoot, run);
+      throw new Error(`Integration commit failed: ${errMessage(err)}`);
+    }
+    const sha = (await git(projectRoot, ['rev-parse', 'HEAD'])).trim();
+    for (const c of run.candidates) await cleanupCandidate(projectRoot, c);
+    return { sha };
+  });
+}
+
+export async function rejectDocumentRun(
+  projectRoot: string,
+  runIdRaw: unknown,
+): Promise<DocumentRunRecord> {
+  const runId = validateRunId(runIdRaw);
+  // Let killed processes settle before their worktrees go away; a CLI that
+  // ignores signals is not allowed to hold the rejection hostage.
+  await Promise.race([
+    killRun(runId),
+    new Promise<void>((resolve) => setTimeout(resolve, SETTLE_WAIT_MS).unref?.()),
+  ]);
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    if (run.status === 'accepted') throw new Error('An accepted run cannot be rejected.');
+    activeRuns.delete(runId);
+    for (const c of run.candidates) await cleanupCandidate(projectRoot, c);
+    run.status = 'rejected';
+    run.finishedAt = run.finishedAt ?? nowIso();
+    for (const c of run.candidates) {
+      if (c.status === 'running') c.status = 'cancelled';
+    }
+    writeRunRecord(projectRoot, run);
+    // Keep the record in history (it documents what was tried) without
+    // touching content: a metadata-only commit the history view filters out.
+    try {
+      await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      const paths = [runRecordRelPath(runId)];
+      if (await stageAnnotations(projectRoot)) paths.push(ANNOTATIONS_FILE);
+      await commitPaths(
+        projectRoot,
+        `Reject proposals\n\nParallel-Run: ${runId}\nParallel-Metadata: true`,
+        paths,
+      );
+    } catch (err) {
+      console.warn('[documents] could not commit rejected run record:', err);
+    }
+    return run;
+  });
+}
+
+export function setDocumentCandidateNote(
+  projectRoot: string,
+  runIdRaw: unknown,
+  candidateIdRaw: unknown,
+  note: unknown,
+): Promise<DocumentRunRecord> {
+  const runId = validateRunId(runIdRaw);
+  const candidateId = validateCandidateId(candidateIdRaw);
+  if (typeof note !== 'string') throw new Error('note must be a string');
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    const candidate = run.candidates.find((c) => c.id === candidateId);
+    if (!candidate) throw new Error('Candidate not found');
+    candidate.note = note.slice(0, 5_000) || undefined;
+    writeRunRecord(projectRoot, run);
+    return run;
+  });
+}
+
+// --- History --------------------------------------------------------------
+
+const TRAILER_RE = /^Parallel-([A-Za-z]+):\s*(.*)$/;
+
+/**
+ * Splits a commit body into prose and `Parallel-*` trailers. Only the last
+ * paragraph counts as trailers, like git itself, so agent prose that happens
+ * to contain a trailer-shaped line cannot re-attribute a commit. Exported
+ * for tests.
+ */
+export function parseCommitBody(body: string): { text: string; trailers: Record<string, string> } {
+  const trimmed = body.replace(/\s+$/, '');
+  const paragraphs = trimmed.split(/\n\s*\n/);
+  const last = paragraphs[paragraphs.length - 1] ?? '';
+  const lastLines = last.split('\n').map((l) => l.trim());
+  const isTrailerBlock = lastLines.length > 0 && lastLines.every((l) => TRAILER_RE.test(l));
+  const trailers: Record<string, string> = {};
+  if (isTrailerBlock) {
+    for (const line of lastLines) {
+      const m = TRAILER_RE.exec(line);
+      if (m) trailers[m[1]] = m[2].trim();
+    }
+    paragraphs.pop();
+  }
+  return { text: paragraphs.join('\n\n').trim(), trailers };
+}
+
+export async function getDocumentHistory(
+  projectRoot: string,
+  documentPath: string,
+  wholeProject: boolean,
+  limit = 200,
+): Promise<DocumentHistoryEntry[]> {
+  const pathArgs = wholeProject ? ['--', '.', ':(exclude).parallel'] : ['--', documentPath];
+  let out = '';
+  try {
+    out = await git(projectRoot, [
+      'log',
+      `--max-count=${limit}`,
+      '--format=%H%x1f%h%x1f%an%x1f%at%x1f%s%x1f%b%x1e',
+      ...pathArgs,
+    ]);
+  } catch {
+    return [];
+  }
+  const entries: DocumentHistoryEntry[] = [];
+  for (const record of out.split('\x1e')) {
+    if (!record.trim()) continue;
+    const [sha, shortSha, author, at, subject, body = ''] = record.replace(/^\n/, '').split('\x1f');
+    if (!sha) continue;
+    const { text, trailers } = parseCommitBody(body);
+    entries.push({
+      sha,
+      shortSha,
+      subject,
+      body: text,
+      author,
+      timestamp: Number(at) || 0,
+      trailers,
+      manual: !trailers.Agent,
+    });
+  }
+  return entries;
+}
+
+export async function getDocumentAtCommit(
+  projectRoot: string,
+  sha: string,
+  documentPath: string,
+): Promise<string | null> {
+  try {
+    return await git(projectRoot, ['show', `${sha}:${documentPath}`]);
+  } catch {
+    return null;
+  }
+}
+
+/** Git's well-known empty tree, what a root commit is diffed against. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+/** Unified diff of one document between two commits (`from` may be `<sha>^`). */
+export async function getDocumentDiff(
+  projectRoot: string,
+  from: string,
+  to: string,
+  documentPath: string,
+): Promise<string> {
+  try {
+    return await git(projectRoot, ['diff', '-U3', `${from}..${to}`, '--', documentPath]);
+  } catch {
+    // `<sha>^` does not exist for a root commit; the whole file is its change.
+    if (!from.endsWith('^')) return '';
+    return git(projectRoot, ['diff', '-U3', `${EMPTY_TREE}..${to}`, '--', documentPath]).catch(
+      () => '',
+    );
+  }
+}
+
+/**
+ * Reverts a commit's content changes with a new commit. Run records under
+ * `.parallel/` are kept as they are: they document what happened, and the
+ * revert itself becomes part of that history.
+ */
+export async function revertDocumentCommit(projectRoot: string, sha: string): Promise<string> {
+  return withProjectLock(projectRoot, async () => {
+    await commitPendingEdits(projectRoot);
+    const subject = (await git(projectRoot, ['log', '-1', '--format=%s', sha])).trim();
+    // The paths the commit touched are the ones the revert may undo; run
+    // records are not among them.
+    const paths = (await git(projectRoot, ['show', '--format=', '--name-only', '-z', sha]))
+      .split('\0')
+      .filter((p) => p && !p.startsWith('.parallel/'));
+    try {
+      await git(projectRoot, ['revert', '--no-commit', sha]);
+      // Restore run records the reverted commit may have added or changed.
+      await gitOk(projectRoot, ['checkout', '-q', 'HEAD', '--', '.parallel']);
+      await gitOk(projectRoot, ['reset', '-q', '--', '.parallel']);
+      if (paths.length === 0) throw new Error('Nothing to revert outside run metadata.');
+      await commitPaths(projectRoot, `Revert "${subject}"\n\nParallel-Revert: ${sha}`, paths);
+    } catch (err) {
+      await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
+      await gitOk(projectRoot, ['clean', '-fdq', '--', '.parallel']);
+      throw new Error(`Revert failed: ${errMessage(err)}`);
+    }
+    return (await git(projectRoot, ['rev-parse', 'HEAD'])).trim();
+  });
+}
+
+/** Kill every running proposal process; used on app quit. */
+export function stopAllDocumentRuns(): void {
+  for (const runId of [...activeRuns.keys()]) void killRun(runId);
+}
diff --git a/electron/documents/setup.test.ts b/electron/documents/setup.test.ts
new file mode 100644
index 000000000..59c811b25
--- /dev/null
+++ b/electron/documents/setup.test.ts
@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { inspectDocumentFolder, prepareDocumentProject } from './setup.js';
+
+const made: string[] = [];
+
+function tmpFolder(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docsetup-'));
+  made.push(dir);
+  return dir;
+}
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir: string): void {
+  git(dir, 'init', '-q', '-b', 'main');
+  git(dir, 'config', 'user.email', 'test@example.com');
+  git(dir, 'config', 'user.name', 'Test');
+}
+
+afterEach(() => {
+  while (made.length) fs.rmSync(made.pop() as string, { recursive: true, force: true });
+});
+
+describe('inspectDocumentFolder', () => {
+  it('finds markdown and HTML in a folder that is not a repository yet', async () => {
+    const dir = tmpFolder();
+    fs.mkdirSync(path.join(dir, 'notes'));
+    fs.writeFileSync(path.join(dir, 'notes', 'plan.md'), '# Plan\n');
+    fs.writeFileSync(path.join(dir, 'page.html'), '<!doctype html>\n');
+    fs.writeFileSync(path.join(dir, 'ignore.txt'), 'x');
+
+    expect(await inspectDocumentFolder(dir)).toEqual({
+      exists: true,
+      isRepo: false,
+      enclosingRepo: null,
+      hasCommits: false,
+      files: [
+        { path: 'notes/plan.md', committed: false },
+        { path: 'page.html', committed: false },
+      ],
+    });
+  });
+
+  it('reports untracked markdown alongside committed markdown', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    fs.writeFileSync(path.join(dir, 'committed.md'), '# One\n');
+    git(dir, 'add', 'committed.md');
+    git(dir, 'commit', '-q', '-m', 'initial');
+    fs.writeFileSync(path.join(dir, 'loose.md'), '# Two\n');
+
+    expect(await inspectDocumentFolder(dir)).toEqual({
+      exists: true,
+      isRepo: true,
+      enclosingRepo: null,
+      hasCommits: true,
+      files: [
+        { path: 'committed.md', committed: true },
+        { path: 'loose.md', committed: false },
+      ],
+    });
+  });
+
+  it('reports a folder that does not exist yet as empty rather than failing', async () => {
+    const missing = path.join(tmpFolder(), 'not', 'made', 'yet');
+
+    expect(await inspectDocumentFolder(missing)).toEqual({
+      exists: false,
+      isRepo: false,
+      enclosingRepo: null,
+      hasCommits: false,
+      files: [],
+    });
+  });
+
+  it('names the enclosing repository instead of claiming a subfolder is one', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    fs.mkdirSync(path.join(dir, 'sub'));
+
+    const info = await inspectDocumentFolder(path.join(dir, 'sub'));
+    expect(info.isRepo).toBe(false);
+    expect(info.enclosingRepo).toBe(fs.realpathSync(dir));
+  });
+});
+
+describe('prepareDocumentProject', () => {
+  it('turns a plain folder into a repository with the document committed', async () => {
+    const dir = tmpFolder();
+    fs.writeFileSync(path.join(dir, 'plan.md'), '# Plan\n');
+
+    const result = await prepareDocumentProject(dir, 'plan.md');
+
+    expect(result.documentPath).toBe('plan.md');
+    expect(result.actions).toEqual(['Initialised a Git repository', 'Committed plan.md']);
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('plan.md');
+  });
+
+  it('creates the folder itself when the path does not exist yet', async () => {
+    const dir = path.join(tmpFolder(), 'design-notes');
+
+    const result = await prepareDocumentProject(dir, 'notes');
+
+    expect(result.actions).toEqual([
+      'Created the folder',
+      'Initialised a Git repository',
+      'Created notes.md',
+      'Committed notes.md',
+    ]);
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('notes.md');
+  });
+
+  it('refuses a path that is a file', async () => {
+    const file = path.join(tmpFolder(), 'a-file.txt');
+    fs.writeFileSync(file, 'x');
+
+    await expect(prepareDocumentProject(file, 'notes.md')).rejects.toThrow(/not a folder/);
+  });
+
+  it('creates a starter document when the name is new, adding the extension', async () => {
+    const dir = tmpFolder();
+
+    const result = await prepareDocumentProject(dir, 'release-notes');
+
+    expect(result.documentPath).toBe('release-notes.md');
+    expect(result.actions).toEqual([
+      'Initialised a Git repository',
+      'Created release-notes.md',
+      'Committed release-notes.md',
+    ]);
+    expect(fs.readFileSync(path.join(dir, 'release-notes.md'), 'utf8')).toBe('# Release notes\n\n');
+  });
+
+  it('creates a starter page when the document is HTML', async () => {
+    const dir = tmpFolder();
+
+    const result = await prepareDocumentProject(dir, 'onboarding-flow.html');
+
+    expect(result.documentPath).toBe('onboarding-flow.html');
+    const page = fs.readFileSync(path.join(dir, 'onboarding-flow.html'), 'utf8');
+    expect(page.startsWith('<!doctype html>\n')).toBe(true);
+    expect(page).toContain('<title>Onboarding flow</title>');
+    expect(page).toContain('<h1>Onboarding flow</h1>');
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe(
+      'onboarding-flow.html',
+    );
+  });
+
+  it('opens the starter with the project title when one is given', async () => {
+    const dir = tmpFolder();
+
+    await prepareDocumentProject(dir, 'api-notes.md', 'API  Notes ');
+    await prepareDocumentProject(dir, 'api-notes.html', 'API <Notes>');
+
+    expect(fs.readFileSync(path.join(dir, 'api-notes.md'), 'utf8')).toBe('# API Notes\n\n');
+    expect(fs.readFileSync(path.join(dir, 'api-notes.html'), 'utf8')).toContain(
+      '<h1>API &lt;Notes&gt;</h1>',
+    );
+  });
+
+  it('does nothing to a repository whose document is already committed', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    fs.writeFileSync(path.join(dir, 'spec.md'), '# Spec\n');
+    git(dir, 'add', 'spec.md');
+    git(dir, 'commit', '-q', '-m', 'initial');
+    const before = git(dir, 'rev-parse', 'HEAD').trim();
+
+    expect((await prepareDocumentProject(dir, 'spec.md')).actions).toEqual([]);
+    expect(git(dir, 'rev-parse', 'HEAD').trim()).toBe(before);
+  });
+
+  it('commits an untracked document without disturbing what the user staged', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    fs.writeFileSync(path.join(dir, 'seed.md'), '# Seed\n');
+    git(dir, 'add', 'seed.md');
+    git(dir, 'commit', '-q', '-m', 'initial');
+    fs.writeFileSync(path.join(dir, 'spec.md'), '# Spec\n');
+    fs.writeFileSync(path.join(dir, 'staged-by-user.txt'), 'mine\n');
+    git(dir, 'add', 'staged-by-user.txt');
+
+    expect((await prepareDocumentProject(dir, 'spec.md')).actions).toEqual(['Committed spec.md']);
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('spec.md');
+    expect(git(dir, 'status', '--porcelain', '--', 'staged-by-user.txt').trim()).toBe(
+      'A  staged-by-user.txt',
+    );
+  });
+
+  it('refuses to nest a new repository inside an existing one', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    const sub = path.join(dir, 'sub');
+    fs.mkdirSync(sub);
+
+    await expect(prepareDocumentProject(sub, 'plan.md')).rejects.toThrow(/sits inside/);
+    expect(fs.existsSync(path.join(sub, '.git'))).toBe(false);
+  });
+});
diff --git a/electron/documents/setup.ts b/electron/documents/setup.ts
new file mode 100644
index 000000000..5b8e0ce42
--- /dev/null
+++ b/electron/documents/setup.ts
@@ -0,0 +1,180 @@
+/**
+ * Onboarding for document projects: what a folder already offers, and the
+ * smallest set of steps that turns it into something the workspace can run
+ * against — a Git repository whose chosen document is committed.
+ */
+import fs from 'fs';
+import path from 'path';
+import { ensureWorktreeContainerExclude } from '../ipc/git.js';
+import { git, gitOk } from './git.js';
+import { validateDocumentPath } from './runs.js';
+import type { DocumentFileInfo, DocumentFolderInfo, DocumentProjectSetup } from './types.js';
+
+const MAX_FILES = 1000;
+/** How far the pre-repository scan walks before it stops looking. */
+const SCAN_DEPTH = 4;
+const DOCUMENT_RE = /\.(md|markdown|html?)$/i;
+const HTML_RE = /\.html?$/i;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.parallel', '.worktrees']);
+
+function isDocument(file: string): boolean {
+  return DOCUMENT_RE.test(file);
+}
+
+async function repoToplevel(folder: string): Promise<string | null> {
+  try {
+    const out = await git(folder, ['rev-parse', '--show-toplevel']);
+    return fs.realpathSync(out.trim());
+  } catch {
+    return null;
+  }
+}
+
+/** Documents in a folder that is not a repository yet, so the picker still has something to show. */
+function scanDocuments(folder: string): string[] {
+  const found: string[] = [];
+  const walk = (dir: string, rel: string, depth: number): void => {
+    if (depth > SCAN_DEPTH || found.length >= MAX_FILES) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (found.length >= MAX_FILES) return;
+      if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name)) continue;
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), child, depth + 1);
+      else if (entry.isFile() && isDocument(entry.name)) found.push(child);
+    }
+  };
+  walk(folder, '', 0);
+  return found.sort();
+}
+
+const DOCUMENT_PATHSPEC = ['--', '*.md', '*.markdown', '*.html', '*.htm'];
+
+async function listDocuments(folder: string, lsFilesArgs: string[]): Promise<string[]> {
+  const out = await git(folder, ['ls-files', '-z', ...lsFilesArgs, ...DOCUMENT_PATHSPEC]);
+  return out
+    .split('\0')
+    .filter((p) => p && !p.startsWith('.parallel/') && !p.startsWith('.worktrees/'));
+}
+
+/**
+ * What the picker needs to decide between "open this document" and "set this
+ * folder up first". Untracked files are listed too: `prepareDocumentProject`
+ * commits whatever the user picks, so there is no reason to hide it.
+ */
+export async function inspectDocumentFolder(folder: string): Promise<DocumentFolderInfo> {
+  // The folder is allowed not to exist: the picker inspects what the user is
+  // still typing, and setup creates whatever is missing.
+  if (!fs.existsSync(folder))
+    return { exists: false, isRepo: false, enclosingRepo: null, hasCommits: false, files: [] };
+  const toplevel = await repoToplevel(folder);
+  const isRepo = toplevel !== null && toplevel === fs.realpathSync(folder);
+  if (!isRepo) {
+    const files = scanDocuments(folder).map(
+      (p): DocumentFileInfo => ({ path: p, committed: false }),
+    );
+    return { exists: true, isRepo: false, enclosingRepo: toplevel, hasCommits: false, files };
+  }
+  const hasCommits = await gitOk(folder, ['rev-parse', '--verify', 'HEAD']);
+  const tracked = new Set(await listDocuments(folder, []));
+  const untracked = await listDocuments(folder, ['--others', '--exclude-standard']);
+  const files = [...tracked, ...untracked]
+    .sort()
+    .slice(0, MAX_FILES)
+    .map((p): DocumentFileInfo => ({ path: p, committed: hasCommits && tracked.has(p) }));
+  return { exists: true, isRepo: true, enclosingRepo: null, hasCommits, files };
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/** `notes.md` → `Notes`; the heading a brand-new document opens with. */
+function starterTitle(documentPath: string, title?: string): string {
+  const given = title?.replace(/\s+/g, ' ').trim();
+  if (given) return given;
+  const name = path.basename(documentPath).replace(DOCUMENT_RE, '').replace(/[-_]+/g, ' ').trim();
+  return `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+}
+
+function starterContent(documentPath: string, title?: string): string {
+  const heading = starterTitle(documentPath, title);
+  if (!HTML_RE.test(documentPath)) return `# ${heading}\n\n`;
+  const safe = escapeHtml(heading);
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '  <meta charset="utf-8">',
+    `  <title>${safe}</title>`,
+    '</head>',
+    '<body>',
+    `  <h1>${safe}</h1>`,
+    '</body>',
+    '</html>',
+    '',
+  ].join('\n');
+}
+
+/** A name without a document extension becomes markdown. */
+function withDocumentExtension(documentPath: string): string {
+  return isDocument(documentPath) ? documentPath : `${documentPath}.md`;
+}
+
+/**
+ * Brings `folder` up to what the workspace assumes: a folder that exists, is a
+ * repository of its own, and holds `requestedPath` as a commit. Every step is
+ * skipped when it is already true, so re-running this on a ready project does
+ * nothing. `title` is the heading a document created here opens with; without
+ * it the file name serves.
+ */
+export async function prepareDocumentProject(
+  folder: string,
+  requestedPath: string,
+  title?: string,
+): Promise<DocumentProjectSetup> {
+  if (fs.existsSync(folder) && !fs.statSync(folder).isDirectory())
+    throw new Error(`${folder} is a file, not a folder.`);
+  const documentPath = withDocumentExtension(validateDocumentPath(requestedPath));
+  const actions: string[] = [];
+
+  if (!fs.existsSync(folder)) {
+    fs.mkdirSync(folder, { recursive: true });
+    actions.push('Created the folder');
+  }
+
+  const toplevel = await repoToplevel(folder);
+  if (toplevel !== null && toplevel !== fs.realpathSync(folder))
+    throw new Error(
+      `That folder sits inside the Git repository at ${toplevel}. Pick that repository instead, ` +
+        'so proposals and history stay in one place.',
+    );
+  if (toplevel === null) {
+    await git(folder, ['init', '-b', 'main']);
+    actions.push('Initialised a Git repository');
+  }
+  ensureWorktreeContainerExclude(folder);
+
+  const absolute = path.join(folder, documentPath);
+  if (!fs.existsSync(absolute)) {
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    fs.writeFileSync(absolute, starterContent(documentPath, title));
+    actions.push(`Created ${documentPath}`);
+  }
+
+  // Runs need a commit to branch from, so an uncommitted document is the one
+  // gap setup always closes. `--only` commits the document alone and leaves
+  // anything the user had staged staged; the `add` before it is what makes an
+  // untracked path committable, and is required at all in a repo with no HEAD.
+  if (!(await gitOk(folder, ['cat-file', '-e', `HEAD:${documentPath}`]))) {
+    await git(folder, ['add', '-f', '--', documentPath]);
+    await git(folder, ['commit', '-q', '--only', '-m', `Add ${documentPath}`, '--', documentPath]);
+    actions.push(`Committed ${documentPath}`);
+  }
+  return { documentPath, actions };
+}
diff --git a/electron/documents/shared.ts b/electron/documents/shared.ts
new file mode 100644
index 000000000..db6a940b2
--- /dev/null
+++ b/electron/documents/shared.ts
@@ -0,0 +1,58 @@
+/**
+ * Which built-in agents can run a document proposal headlessly, and whether
+ * the CLI can resume a previous session (needed for the warm main session).
+ * Renderer-safe: no Node or Electron imports.
+ */
+export interface DocumentAgentSupport {
+  /** The CLI has a non-interactive mode the runner knows how to drive. */
+  headless: boolean;
+  /** The CLI can resume a session by id in that mode. */
+  resume: boolean;
+  /** Model names the CLI is known to accept, offered as suggestions; any name it takes works. */
+  models: readonly string[];
+  /** Reasoning levels the CLI accepts, lowest first; empty when it has no such flag. */
+  efforts: readonly string[];
+}
+
+/**
+ * Only CLIs whose headless mode can be kept away from the canonical checkout
+ * are listed: Claude Code runs with file tools only, Codex inside its
+ * workspace-write sandbox (writes outside the worktree are blocked), Gemini
+ * with edits auto-approved and shell commands needing an approval that a
+ * non-interactive run cannot give. OpenCode and Copilot expose a full shell
+ * in print mode and stay out until they can be restricted.
+ */
+export const DOCUMENT_AGENT_SUPPORT: Record<string, DocumentAgentSupport> = {
+  'claude-code': {
+    headless: true,
+    resume: true,
+    // Aliases resolve to the latest model of each tier, so they do not go stale.
+    models: ['fable', 'opus', 'sonnet', 'haiku'],
+    efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+  },
+  codex: {
+    headless: true,
+    resume: true,
+    models: [],
+    // Which of these a model takes varies by model; the CLI rejects the rest.
+    efforts: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'],
+  },
+  gemini: { headless: true, resume: false, models: [], efforts: [] },
+};
+
+const NO_SUPPORT: DocumentAgentSupport = {
+  headless: false,
+  resume: false,
+  models: [],
+  efforts: [],
+};
+
+export function documentAgentSupport(agentId: string): DocumentAgentSupport {
+  return DOCUMENT_AGENT_SUPPORT[agentId] ?? NO_SUPPORT;
+}
+
+/** Default agent for a project's main session. */
+export const DEFAULT_DOCUMENT_MAIN_AGENT = 'claude-code';
+
+/** Hard cap on candidates per run; each one is a worktree plus a CLI process. */
+export const MAX_DOCUMENT_CANDIDATES = 6;
diff --git a/electron/documents/types.ts b/electron/documents/types.ts
new file mode 100644
index 000000000..6c640c79e
--- /dev/null
+++ b/electron/documents/types.ts
@@ -0,0 +1,219 @@
+/**
+ * The shapes the document workspace sends across IPC. Renderer-safe: types
+ * only, no runtime imports.
+ */
+
+/** A Markdown file a folder offers as the document to work on. */
+export interface DocumentFileInfo {
+  path: string;
+  /** False for files setup still has to commit before runs can branch from them. */
+  committed: boolean;
+}
+
+/** What a candidate folder already has, so the picker can offer to fill the gaps. */
+export interface DocumentFolderInfo {
+  /** False for a folder the user named but has not created; setup makes it. */
+  exists: boolean;
+  isRepo: boolean;
+  /** Set when the folder is inside someone else's repository, which setup refuses to nest in. */
+  enclosingRepo: string | null;
+  hasCommits: boolean;
+  files: DocumentFileInfo[];
+}
+
+/** What `prepareDocumentProject` did, in order, so the app can say so. */
+export interface DocumentProjectSetup {
+  documentPath: string;
+  actions: string[];
+}
+
+/** Current state of the canonical document in the project checkout. */
+export interface DocumentSnapshot {
+  content: string;
+  /** HEAD sha of the canonical branch; null in an empty repository. */
+  headSha: string | null;
+  /** Checked-out branch name; null when HEAD is detached. */
+  branch: string | null;
+  /** True when the working tree has uncommitted changes (outside `.worktrees/`). */
+  dirty: boolean;
+  /** True when the document file is missing from the checkout. */
+  missing: boolean;
+}
+
+/** What part of the document a run is allowed to change. Lines are 1-based and
+ *  inclusive at the base commit; a whole-document scope has `wholeDocument`. */
+export interface DocumentScope {
+  path: string;
+  wholeDocument: boolean;
+  startLine: number;
+  endLine: number;
+  /** Exact quoted text of the selected passage (block-aligned). */
+  quote: string;
+  /** Nearest heading above the selection, when any. */
+  heading?: string;
+}
+
+export interface DocumentRationale {
+  summary: string;
+  changes: string[];
+  assumptions: string[];
+  questions: string[];
+  warnings: string[];
+}
+
+export type DocumentCandidateStatus = 'running' | 'done' | 'failed' | 'cancelled' | 'interrupted';
+
+export interface DocumentCandidateRecord {
+  id: string;
+  /** Neutral label used when the comparison hides agent identity ("A", "B", …). */
+  label: string;
+  agentId: string;
+  agentName: string;
+  /** The project's warm main session rather than a throwaway alternate. */
+  isMain: boolean;
+  /** Model and reasoning level the CLI was started with; absent means its defaults. */
+  model?: string;
+  effort?: string;
+  branch: string;
+  worktreePath: string;
+  status: DocumentCandidateStatus;
+  /** Proposal commit on `branch`; null while running or when nothing changed. */
+  commitSha: string | null;
+  /** Provider session id, when the CLI reported one (used to resume the main session). */
+  sessionId?: string;
+  exitCode?: number | null;
+  startedAt: string;
+  finishedAt?: string;
+  rationale?: DocumentRationale;
+  /** Final assistant text, kept when it does not parse as a rationale. */
+  resultText?: string;
+  /** Files the agent touched outside the scoped document. They are reverted
+   *  before the proposal commit and listed here so the reviewer sees it. */
+  outOfScopeFiles?: string[];
+  /** Hunks inside the document that fall outside the selected passage. */
+  outOfScopeHunks?: number;
+  noChanges?: boolean;
+  error?: string;
+  /** Reviewer's note on this candidate from the compare view. */
+  note?: string;
+}
+
+export type DocumentRunStatus = 'running' | 'finished' | 'accepted' | 'rejected' | 'stale';
+
+/** Persisted under `.parallel/runs/<id>.json` inside the document project. */
+export interface DocumentRunRecord {
+  /** Format version of this record. */
+  version: 1;
+  id: string;
+  documentPath: string;
+  createdAt: string;
+  instruction: string;
+  scope: DocumentScope;
+  baseSha: string;
+  status: DocumentRunStatus;
+  candidates: DocumentCandidateRecord[];
+  /** Proposal used as the starting content of this revision; never accepted implicitly. */
+  refinement?: { runId: string; candidateId: string };
+  acceptedCandidateId?: string;
+  /** Set when the reader kept only some of the accepted candidate's changes. */
+  partialAcceptance?: { accepted: number; total: number };
+  finishedAt?: string;
+}
+
+/** Streamed from the main process while a run is in flight. */
+export type DocumentRunEvent =
+  | { type: 'log'; projectRoot: string; runId: string; candidateId: string; text: string }
+  | { type: 'candidate'; projectRoot: string; runId: string; candidate: DocumentCandidateRecord }
+  | { type: 'run'; projectRoot: string; run: DocumentRunRecord };
+
+export interface DocumentCandidateSpec {
+  id: string;
+  label: string;
+  agentId: string;
+  agentName: string;
+  command: string;
+  isMain: boolean;
+  /** Model and reasoning level to start the CLI with; absent means its defaults. */
+  model?: string;
+  effort?: string;
+  /** Provider session to resume for the main candidate. */
+  sessionId?: string;
+  /** Sha the resumed session last saw; the prompt carries the diff since then. */
+  sessionLastSha?: string;
+  /** Per-agent env file, when configured. */
+  envFile?: string;
+}
+
+export interface DocumentHistoryEntry {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  body: string;
+  author: string;
+  /** Unix seconds. */
+  timestamp: number;
+  /** `Parallel-*` trailers, keys without the prefix (e.g. `Agent`, `Run`). */
+  trailers: Record<string, string>;
+  /** True when no agent trailer is present: a manual commit. */
+  manual: boolean;
+}
+
+// --- Document annotations ---
+
+/**
+ * Where an annotation sits. Offsets alone go stale as soon as anything above
+ * them changes, so the anchor also carries the exact quote, its neighbours
+ * and the nearest heading; the renderer relocates it on the current version
+ * and shows it detached when it cannot.
+ */
+export interface DocumentAnchor {
+  path: string;
+  /** Commit the offsets were taken against. */
+  baseSha: string | null;
+  startLine: number;
+  endLine: number;
+  /** Exact source text of the anchored blocks. */
+  quote: string;
+  /** Tail of the preceding block and head of the following one. */
+  prefix: string;
+  suffix: string;
+  heading?: string;
+}
+
+export type DocumentAnnotationKind = 'note' | 'question';
+
+export interface DocumentAnnotationAnswer {
+  text: string;
+  agentId: string;
+  agentName: string;
+  answeredAt: string;
+}
+
+export type DocumentAnswerStatus = 'pending' | 'answered' | 'failed';
+
+/** A bubble beside the document: a note, or a question an agent answers into it. */
+export interface DocumentAnnotation {
+  id: string;
+  kind: DocumentAnnotationKind;
+  anchor: DocumentAnchor;
+  text: string;
+  createdAt: string;
+  updatedAt: string;
+  resolved: boolean;
+  answer?: DocumentAnnotationAnswer;
+  answerStatus?: DocumentAnswerStatus;
+  answerError?: string;
+  /** Run this annotation was turned into, if any. */
+  runId?: string;
+}
+
+/** Persisted as `.parallel/annotations.json` inside the document project. */
+export interface DocumentAnnotationsFile {
+  version: 1;
+  annotations: DocumentAnnotation[];
+}
+
+export interface DocumentAnnotationEvent {
+  projectRoot: string;
+  annotation: DocumentAnnotation;
+}
diff --git a/electron/ipc/channel-manifest.json b/electron/ipc/channel-manifest.json
index 3eeba5c8d..3159120ab 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -147,5 +147,30 @@
   "MCP_TaskHydrated": "mcp_task_hydrated",
   "MCP_StaleUrlWarning": "mcp_stale_url_warning",
   "MCP_CoordinatedTaskClosed": "mcp_coordinated_task_closed",
-  "MCP_TaskCleanupFailed": "mcp_task_cleanup_failed"
+  "MCP_TaskCleanupFailed": "mcp_task_cleanup_failed",
+  "ReadDocument": "read_document",
+  "WriteDocumentBlock": "write_document_block",
+  "StartDocumentWatcher": "start_document_watcher",
+  "StopDocumentWatcher": "stop_document_watcher",
+  "DispatchDocumentRun": "dispatch_document_run",
+  "CancelDocumentRun": "cancel_document_run",
+  "ListDocumentRuns": "list_document_runs",
+  "AcceptDocumentCandidate": "accept_document_candidate",
+  "RejectDocumentRun": "reject_document_run",
+  "SetDocumentCandidateNote": "set_document_candidate_note",
+  "GetDocumentHistory": "get_document_history",
+  "GetDocumentAtCommit": "get_document_at_commit",
+  "GetDocumentDiff": "get_document_diff",
+  "RevertDocumentCommit": "revert_document_commit",
+  "InspectDocumentFolder": "inspect_document_folder",
+  "PrepareDocumentProject": "prepare_document_project",
+  "DocumentChanged": "document_changed",
+  "DocumentRunEvent": "document_run_event",
+  "ListDocumentAnnotations": "list_document_annotations",
+  "SaveDocumentAnnotation": "save_document_annotation",
+  "DeleteDocumentAnnotation": "delete_document_annotation",
+  "AskDocumentAnnotation": "ask_document_annotation",
+  "DocumentAnnotationEvent": "document_annotation_event",
+  "ListDocumentFiles": "list_document_files",
+  "ReadDocumentCandidateLog": "read_document_candidate_log"
 }
diff --git a/electron/ipc/git.ts b/electron/ipc/git.ts
index 467521113..8b5531f57 100644
--- a/electron/ipc/git.ts
+++ b/electron/ipc/git.ts
@@ -71,7 +71,7 @@ const DIFF_BASE_TTL = 30_000; // 30s
 const MAX_BUFFER = 10 * 1024 * 1024; // 10MB
 const STDERR_CAP = 4096; // cap for stderr buffers in spawned git processes
 /** Git's well-known empty tree SHA — used to diff the initial commit against nothing. */
-const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf899d69f82cf7202';
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
 
 // Sweep expired cache entries periodically so stale entries from repos that
 // are no longer queried don't accumulate (lazy deletion alone isn't enough).
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index aadab018a..187317626 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -106,7 +106,9 @@ import {
   assertStringArray,
   assertOptionalString,
   assertOptionalBoolean,
+  validatePath,
 } from './validate.js';
+import { registerDocumentHandlers } from '../documents/register.js';
 import { validateBranchName as sharedValidateBranchName, validateUUID } from '../mcp/validation.js';
 import { debug as logDebug, warn as logWarn, errMessage } from '../log.js';
 import { getMCPRemoteServerUrl, detectStaleDockerMCPUrl } from '../mcp/config.js';
@@ -179,13 +181,6 @@ async function startRemoteServerOnFreePort(
   throw new Error(`No free port found in range ${start}–${end}`);
 }
 
-/** Reject paths that are non-absolute or attempt directory traversal. */
-function validatePath(p: unknown, label: string): void {
-  if (typeof p !== 'string') throw new Error(`${label} must be a string`);
-  if (!path.isAbsolute(p)) throw new Error(`${label} must be absolute`);
-  if (p.includes('..')) throw new Error(`${label} must not contain ".."`);
-}
-
 function isMissingCommandError(err: unknown, command: string): boolean {
   const e = err as { path?: unknown; syscall?: unknown };
   return (
@@ -962,6 +957,8 @@ export function registerAllHandlers(win: BrowserWindow): void {
     cancelAskAboutCode(args.requestId);
   });
 
+  registerDocumentHandlers(win);
+
   // --- File links ---
   ipcMain.handle(IPC.OpenPath, (_e, args) => {
     validatePath(args.filePath, 'filePath');
diff --git a/electron/ipc/validate.ts b/electron/ipc/validate.ts
index a4baf4822..9ad3c9ea3 100644
--- a/electron/ipc/validate.ts
+++ b/electron/ipc/validate.ts
@@ -1,4 +1,12 @@
 /** Runtime type assertion helpers for IPC handler args. */
+import path from 'path';
+
+/** Reject paths that are non-absolute or attempt directory traversal. */
+export function validatePath(p: unknown, label: string): void {
+  if (typeof p !== 'string') throw new Error(`${label} must be a string`);
+  if (!path.isAbsolute(p)) throw new Error(`${label} must be absolute`);
+  if (p.includes('..')) throw new Error(`${label} must not contain ".."`);
+}
 
 export function assertString(val: unknown, label: string): asserts val is string {
   if (typeof val !== 'string') throw new Error(`${label} must be a string`);
diff --git a/electron/main.ts b/electron/main.ts
index cbeeba525..0ce78a07a 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -2,7 +2,7 @@ import { app, autoUpdater, BrowserWindow, Menu, ipcMain, session, shell } from '
 import { buildMenuTemplate } from './menu-template.js';
 import path from 'path';
 import fs from 'fs';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { execFileSync } from 'child_process';
 import { registerAllHandlers } from './ipc/register.js';
 import { registerLogHandler } from './log.js';
@@ -10,6 +10,7 @@ import { installIpcTracing } from './ipc/trace.js';
 import { startAgentHookRuntime, stopAgentHookRuntime } from './agent-hooks/runtime.js';
 import { killAllAgents } from './ipc/pty.js';
 import { stopAllPlanWatchers } from './ipc/plans.js';
+import { stopAllDocumentWork } from './documents/register.js';
 import { stopAllStepsWatchers } from './ipc/steps.js';
 import { verificationRunner } from './ipc/verify.js';
 import { IPC } from './ipc/channels.js';
@@ -192,9 +193,13 @@ function createWindow() {
     // Malformed dev URL — skip origin allowlist
   }
 
+  // The app's own page, and nothing else on the disk: a document's markup is
+  // rendered in this window, and a navigation away from index.html would hand
+  // the preload's IPC surface to whatever it landed on.
+  const appPage = pathToFileURL(path.join(__dirname, '../dist/index.html')).href;
   mainWindow.webContents.on('will-navigate', (event, url) => {
     if (allowedOrigin && url.startsWith(allowedOrigin)) return;
-    if (url.startsWith('file://')) return;
+    if (url.split(/[?#]/)[0] === appPage) return;
     event.preventDefault();
     if (url.startsWith('http:') || url.startsWith('https:')) {
       shell
@@ -288,6 +293,7 @@ app.on('will-quit', () => {
   verificationRunner.cancelAll();
   stopAgentHookRuntime();
   stopAllPlanWatchers();
+  stopAllDocumentWork();
   stopAllStepsWatchers();
 });
 
diff --git a/electron/preload.cjs b/electron/preload.cjs
index f301b25e6..9cd93e97d 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -152,6 +152,31 @@ const ALLOWED_CHANNELS = new Set([
   'mcp_stale_url_warning',
   'mcp_coordinated_task_closed',
   'mcp_task_cleanup_failed',
+  'read_document',
+  'write_document_block',
+  'start_document_watcher',
+  'stop_document_watcher',
+  'dispatch_document_run',
+  'cancel_document_run',
+  'list_document_runs',
+  'accept_document_candidate',
+  'reject_document_run',
+  'set_document_candidate_note',
+  'get_document_history',
+  'get_document_at_commit',
+  'get_document_diff',
+  'revert_document_commit',
+  'inspect_document_folder',
+  'prepare_document_project',
+  'document_changed',
+  'document_run_event',
+  'list_document_annotations',
+  'save_document_annotation',
+  'delete_document_annotation',
+  'ask_document_annotation',
+  'document_annotation_event',
+  'list_document_files',
+  'read_document_candidate_log',
 ]);
 
 function isAllowedChannel(channel) {
diff --git a/electron/test-env.test.ts b/electron/test-env.test.ts
new file mode 100644
index 000000000..02097396d
--- /dev/null
+++ b/electron/test-env.test.ts
@@ -0,0 +1,38 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+/**
+ * Guards the invariant every git-touching test depends on: a `git` spawned by a
+ * test acts on its own temp repository, never on the checkout the suite runs in.
+ * Run from a git hook without `vitest.setup.ts` scrubbing the inherited
+ * `GIT_DIR`/`GIT_INDEX_FILE`, both of these fail.
+ */
+describe('test environment', () => {
+  const made: string[] = [];
+  afterEach(() => {
+    for (const dir of made.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('hands tests no pointer to a surrounding repository', () => {
+    for (const name of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'])
+      expect({ [name]: process.env[name] }).toEqual({ [name]: undefined });
+  });
+
+  it('creates a temp repository in the temp folder, not in the ambient one', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-test-env-'));
+    made.push(dir);
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+
+    // `--show-toplevel` would pass either way: an inherited GIT_DIR leaves the
+    // work tree at cwd. Only the git dir itself reveals the hijack.
+    const gitDir = execFileSync('git', ['rev-parse', '--absolute-git-dir'], {
+      cwd: dir,
+      encoding: 'utf8',
+    }).trim();
+
+    expect(fs.realpathSync(gitDir)).toBe(path.join(fs.realpathSync(dir), '.git'));
+  });
+});
diff --git a/package-lock.json b/package-lock.json
index 68dc1b0e5..8ad357e21 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -27,6 +27,7 @@
         "mermaid": "^11.15.0",
         "monaco-editor": "^0.55.1",
         "node-pty": "^1.1.0",
+        "parse5": "^7.3.0",
         "qrcode": "^1.5.4",
         "shiki": "^4.0.2",
         "solid-js": "^1.9.11",
@@ -7049,7 +7050,6 @@
       "version": "6.0.1",
       "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
       "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
-      "dev": true,
       "license": "BSD-2-Clause",
       "engines": {
         "node": ">=0.12"
@@ -11180,7 +11180,6 @@
       "version": "7.3.0",
       "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
       "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "entities": "^6.0.0"
diff --git a/package.json b/package.json
index a68a43519..6376cbd3a 100644
--- a/package.json
+++ b/package.json
@@ -57,6 +57,7 @@
     "mermaid": "^11.15.0",
     "monaco-editor": "^0.55.1",
     "node-pty": "^1.1.0",
+    "parse5": "^7.3.0",
     "qrcode": "^1.5.4",
     "shiki": "^4.0.2",
     "solid-js": "^1.9.11",
diff --git a/src/App.tsx b/src/App.tsx
index 033f91efb..382a181b7 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -87,6 +87,13 @@ import { isMac, mod } from './lib/platform';
 import { createCtrlWheelZoomHandler } from './lib/wheelZoom';
 import { redrawAllTerminals } from './lib/terminalFitManager';
 import { ArenaOverlay } from './arena/ArenaOverlay';
+import { DocumentWorkspaceOverlay } from './documents/DocumentWorkspaceOverlay';
+import {
+  closeDocumentWorkspace,
+  documentStore,
+  initDocumentListeners,
+  setDocumentSelection,
+} from './documents/store';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
@@ -336,6 +343,7 @@ function App() {
     // Before the first await: restored agents start firing hooks as soon as
     // loadState spawns them, and IPC does not replay what nobody listened to.
     const stopAgentHookStatusListener = startAgentHookStatusListener();
+    const stopDocumentListeners = initDocumentListeners();
     void syncWindowFocused();
     void syncWindowMaximized();
 
@@ -697,6 +705,11 @@ function App() {
           closeArena();
           return;
         }
+        if (store.activeDocumentProjectId) {
+          if (documentStore.selection) setDocumentSelection(null);
+          else closeDocumentWorkspace();
+          return;
+        }
         if (store.showHelpDialog) {
           toggleHelpDialog(false);
           return;
@@ -742,6 +755,7 @@ function App() {
       stopRemoteTaskHandlers();
       stopRemoteStatusSync();
       stopAgentHookStatusListener();
+      stopDocumentListeners();
       offPlanContent();
       offStepsContent();
       unlistenFocusChanged?.();
@@ -919,6 +933,9 @@ function App() {
         <Show when={store.showArena}>
           <ArenaOverlay onClose={closeArena} />
         </Show>
+        <Show when={store.activeDocumentProjectId}>
+          <DocumentWorkspaceOverlay />
+        </Show>
         <Show when={showDropOverlay()}>
           <DropOverlay />
         </Show>
diff --git a/src/components/AddProjectMenu.tsx b/src/components/AddProjectMenu.tsx
new file mode 100644
index 000000000..4a8170b71
--- /dev/null
+++ b/src/components/AddProjectMenu.tsx
@@ -0,0 +1,114 @@
+import { onCleanup, onMount } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { theme } from '../lib/theme';
+import { sf } from '../lib/fontScale';
+import { DocumentIcon } from '../documents/DocumentIcon';
+
+export type ProjectKindChoice = 'code' | 'document';
+
+interface AddProjectMenuProps {
+  /** Viewport coordinates of the "+" button this hangs from. */
+  anchor: { left: number; top: number };
+  onPick: (kind: ProjectKindChoice) => void;
+  onClose: () => void;
+}
+
+const MENU_WIDTH = 232;
+
+/**
+ * The two project kinds, offered rather than asked. This replaces a native
+ * message box: that blocked the window to pose a question in a dialog system
+ * the app does not control, and its Escape cancelled the whole add instead of
+ * backing out of the question.
+ */
+export function AddProjectMenu(props: AddProjectMenuProps) {
+  onMount(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        props.onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey, true);
+    onCleanup(() => window.removeEventListener('keydown', onKey, true));
+  });
+
+  const row = (kind: ProjectKindChoice, icon: () => unknown, label: string, hint: string) => (
+    <button
+      type="button"
+      onClick={() => props.onPick(kind)}
+      style={{
+        display: 'flex',
+        'align-items': 'flex-start',
+        gap: '9px',
+        padding: '8px 10px',
+        background: 'transparent',
+        border: 'none',
+        'border-radius': 'var(--radius-sm)',
+        color: theme.fg,
+        cursor: 'pointer',
+        'text-align': 'left',
+        font: 'inherit',
+      }}
+      onMouseEnter={(e) => (e.currentTarget.style.background = theme.bgHover)}
+      onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+    >
+      <span style={{ color: theme.fgMuted, 'margin-top': '1px', 'flex-shrink': '0' }}>
+        {icon() as never}
+      </span>
+      <span style={{ display: 'flex', 'flex-direction': 'column', gap: '1px', 'min-width': '0' }}>
+        <span style={{ 'font-size': sf(12), 'font-weight': '500' }}>{label}</span>
+        <span style={{ 'font-size': sf(11), color: theme.fgMuted }}>{hint}</span>
+      </span>
+    </button>
+  );
+
+  return (
+    <Portal>
+      <div
+        onClick={() => props.onClose()}
+        onContextMenu={() => props.onClose()}
+        style={{ position: 'fixed', inset: '0', 'z-index': '1200' }}
+      >
+        <div
+          role="menu"
+          aria-label="Add project"
+          onClick={(e) => e.stopPropagation()}
+          style={{
+            position: 'fixed',
+            left: `${props.anchor.left}px`,
+            top: `${props.anchor.top}px`,
+            width: `${MENU_WIDTH}px`,
+            background: theme.bgElevated,
+            border: `1px solid ${theme.border}`,
+            'border-radius': 'var(--radius-md)',
+            'box-shadow': '0 6px 20px rgba(0, 0, 0, 0.35)',
+            padding: '4px',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '1px',
+          }}
+        >
+          {row(
+            'code',
+            () => (
+              <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M1.5 3.25A1.75 1.75 0 0 1 3.25 1.5h2.9c.46 0 .9.18 1.23.51l.86.86h4.51c.97 0 1.75.78 1.75 1.75v7.63c0 .97-.78 1.75-1.75 1.75H3.25a1.75 1.75 0 0 1-1.75-1.75z" />
+              </svg>
+            ),
+            'Code project…',
+            'A git repo that holds tasks',
+          )}
+          {row(
+            'document',
+            () => (
+              <DocumentIcon size={14} />
+            ),
+            'Document project…',
+            'A folder with one Markdown document',
+          )}
+        </div>
+      </div>
+    </Portal>
+  );
+}
diff --git a/src/components/EditProjectDialog.tsx b/src/components/EditProjectDialog.tsx
index b6b664b66..97e2caae9 100644
--- a/src/components/EditProjectDialog.tsx
+++ b/src/components/EditProjectDialog.tsx
@@ -8,6 +8,7 @@ import { SegmentedButtons } from './SegmentedButtons';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
 import { CloseIcon } from './icons';
 import { RemoveProjectConfirm } from './RemoveProjectConfirm';
+import { isDocumentProject } from '../store/projects';
 
 interface EditProjectDialogProps {
   project: Project | null;
@@ -32,6 +33,9 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
   const [newCommand, setNewCommand] = createSignal('');
   const [showImportDialog, setShowImportDialog] = createSignal(false);
   const [confirmRemove, setConfirmRemove] = createSignal(false);
+  /** Branch and worktree settings only mean something where tasks run. */
+  const isDocument = () => isDocumentProject(props.project ?? undefined);
+  const showsTaskSettings = () => props.project?.isGitRepo !== false && !isDocument();
   let nameRef!: HTMLInputElement;
 
   // Sync signals when project prop changes
@@ -130,22 +134,24 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
               >
                 {project().path}
               </div>
-              <button
-                type="button"
-                onClick={() => setShowImportDialog(true)}
-                style={{
-                  padding: '3px 10px',
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': 'var(--radius-sm)',
-                  color: theme.fgMuted,
-                  cursor: 'pointer',
-                  'font-size': '11px',
-                  'flex-shrink': '0',
-                }}
-              >
-                Import Worktrees
-              </button>
+              <Show when={!isDocument()}>
+                <button
+                  type="button"
+                  onClick={() => setShowImportDialog(true)}
+                  style={{
+                    padding: '3px 10px',
+                    background: theme.bgInput,
+                    border: `1px solid ${theme.border}`,
+                    'border-radius': 'var(--radius-sm)',
+                    color: theme.fgMuted,
+                    cursor: 'pointer',
+                    'font-size': '11px',
+                    'flex-shrink': '0',
+                  }}
+                >
+                  Import Worktrees
+                </button>
+              </Show>
               <button
                 type="button"
                 onClick={() => relinkProject(project().id)}
@@ -242,7 +248,7 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
             </div>
 
             {/* Branch prefix — git projects only */}
-            <Show when={props.project?.isGitRepo !== false}>
+            <Show when={showsTaskSettings()}>
               <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
                 <label style={sectionLabelStyle}>Branch prefix</label>
                 <input
@@ -325,7 +331,7 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
             </div>
 
             {/* Git-specific settings — hidden for non-git projects */}
-            <Show when={props.project?.isGitRepo !== false}>
+            <Show when={showsTaskSettings()}>
               {/* Close cleanup preference */}
               <label
                 style={{
@@ -386,177 +392,181 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
               </div>
             </Show>
 
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>
-                Verify command{' '}
-                <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
-                  (runs in the task worktree)
-                </span>
-              </label>
-              <input
-                class="input-field"
-                type="text"
-                value={verifyCommand()}
-                onInput={(e) => setVerifyCommand(e.currentTarget.value)}
-                placeholder="npm run typecheck && npm test"
-                style={{
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': '8px',
-                  padding: '10px 14px',
-                  color: theme.fg,
-                  'font-size': '14px',
-                  'font-family': "'JetBrains Mono', monospace",
-                  outline: 'none',
-                }}
-              />
-              <div
-                style={{
-                  'font-size': '12px',
-                  color: theme.fgSubtle,
-                  padding: '2px 2px 0',
-                }}
-              >
-                Runs from the merge dialog, when an agent calls <code>land_self</code>, and before
-                the coordinator merges. A failure is advisory in the merge dialog, but{' '}
-                <code>land_self</code> and <code>merge_task</code> refuse to merge until it passes.{' '}
-                <code>PARALLEL_CODE_TASK_ID</code> and <code>PARALLEL_CODE_BRANCH</code> are set for
-                namespacing shared resources.
-              </div>
-            </div>
-
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>
-                Coverage report path{' '}
-                <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
-                  (relative to repo root)
-                </span>
-              </label>
-              <input
-                class="input-field"
-                type="text"
-                value={coverageReportPath()}
-                onInput={(e) => setCoverageReportPath(e.currentTarget.value)}
-                placeholder="coverage/coverage-summary.json or coverage/lcov.info"
-                style={{
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': 'var(--radius-md)',
-                  padding: '10px 14px',
-                  color: theme.fg,
-                  'font-size': '14px',
-                  'font-family': "'JetBrains Mono', monospace",
-                  outline: 'none',
-                }}
-              />
-              <div
-                style={{
-                  'font-size': '12px',
-                  color: theme.fgSubtle,
-                  padding: '2px 2px 0',
-                }}
-              >
-                Leave blank to try <code>coverage/coverage-summary.json</code>, then{' '}
-                <code>coverage/lcov.info</code>.
-              </div>
-            </div>
-
-            {/* Command Bookmarks */}
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>Command Bookmarks</label>
-              <Show when={bookmarks().length > 0}>
-                <div style={{ display: 'flex', 'flex-direction': 'column', gap: '4px' }}>
-                  <For each={bookmarks()}>
-                    {(bookmark) => (
-                      <div
-                        style={{
-                          display: 'flex',
-                          'align-items': 'center',
-                          gap: '8px',
-                          padding: '4px 8px',
-                          background: theme.bgInput,
-                          'border-radius': 'var(--radius-sm)',
-                          border: `1px solid ${theme.border}`,
-                        }}
-                      >
-                        <span
-                          style={{
-                            flex: '1',
-                            'font-size': '12px',
-                            'font-family': "'JetBrains Mono', monospace",
-                            color: theme.fgSubtle,
-                            overflow: 'hidden',
-                            'text-overflow': 'ellipsis',
-                            'white-space': 'nowrap',
-                          }}
-                        >
-                          {bookmark.command}
-                        </span>
-                        <button
-                          type="button"
-                          onClick={() => removeBookmark(bookmark.id)}
-                          style={{
-                            background: 'transparent',
-                            border: 'none',
-                            color: theme.fgSubtle,
-                            cursor: 'pointer',
-                            padding: '2px',
-                            'line-height': '1',
-                            'flex-shrink': '0',
-                          }}
-                          title="Remove bookmark"
-                        >
-                          <CloseIcon size={12} />
-                        </button>
-                      </div>
-                    )}
-                  </For>
-                </div>
-              </Show>
-              <div style={{ display: 'flex', gap: '6px' }}>
+            {/* Worktrees, verification, coverage and terminal bookmarks belong to
+                code tasks; a document project runs none of them. */}
+            <Show when={!isDocument()}>
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>
+                  Verify command{' '}
+                  <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
+                    (runs in the task worktree)
+                  </span>
+                </label>
                 <input
                   class="input-field"
                   type="text"
-                  value={newCommand()}
-                  onInput={(e) => setNewCommand(e.currentTarget.value)}
-                  onKeyDown={(e) => {
-                    if (e.key === 'Enter') {
-                      e.preventDefault();
-                      addBookmark();
-                    }
-                  }}
-                  placeholder="e.g. npm run dev"
+                  value={verifyCommand()}
+                  onInput={(e) => setVerifyCommand(e.currentTarget.value)}
+                  placeholder="npm run typecheck && npm test"
                   style={{
-                    flex: '1',
                     background: theme.bgInput,
                     border: `1px solid ${theme.border}`,
-                    'border-radius': 'var(--radius-md)',
-                    padding: '8px 12px',
+                    'border-radius': '8px',
+                    padding: '10px 14px',
                     color: theme.fg,
-                    'font-size': '13px',
+                    'font-size': '14px',
                     'font-family': "'JetBrains Mono', monospace",
                     outline: 'none',
                   }}
                 />
-                <button
-                  type="button"
-                  onClick={addBookmark}
-                  disabled={!newCommand().trim()}
+                <div
+                  style={{
+                    'font-size': '12px',
+                    color: theme.fgSubtle,
+                    padding: '2px 2px 0',
+                  }}
+                >
+                  Runs from the merge dialog, when an agent calls <code>land_self</code>, and before
+                  the coordinator merges. A failure is advisory in the merge dialog, but{' '}
+                  <code>land_self</code> and <code>merge_task</code> refuse to merge until it
+                  passes. <code>PARALLEL_CODE_TASK_ID</code> and <code>PARALLEL_CODE_BRANCH</code>{' '}
+                  are set for namespacing shared resources.
+                </div>
+              </div>
+
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>
+                  Coverage report path{' '}
+                  <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
+                    (relative to repo root)
+                  </span>
+                </label>
+                <input
+                  class="input-field"
+                  type="text"
+                  value={coverageReportPath()}
+                  onInput={(e) => setCoverageReportPath(e.currentTarget.value)}
+                  placeholder="coverage/coverage-summary.json or coverage/lcov.info"
                   style={{
-                    padding: '8px 14px',
                     background: theme.bgInput,
                     border: `1px solid ${theme.border}`,
                     'border-radius': 'var(--radius-md)',
-                    color: newCommand().trim() ? theme.fg : theme.fgSubtle,
-                    cursor: newCommand().trim() ? 'pointer' : 'not-allowed',
-                    'font-size': '13px',
-                    'flex-shrink': '0',
+                    padding: '10px 14px',
+                    color: theme.fg,
+                    'font-size': '14px',
+                    'font-family': "'JetBrains Mono', monospace",
+                    outline: 'none',
+                  }}
+                />
+                <div
+                  style={{
+                    'font-size': '12px',
+                    color: theme.fgSubtle,
+                    padding: '2px 2px 0',
                   }}
                 >
-                  Add
-                </button>
+                  Leave blank to try <code>coverage/coverage-summary.json</code>, then{' '}
+                  <code>coverage/lcov.info</code>.
+                </div>
               </div>
-            </div>
+
+              {/* Command Bookmarks */}
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>Command Bookmarks</label>
+                <Show when={bookmarks().length > 0}>
+                  <div style={{ display: 'flex', 'flex-direction': 'column', gap: '4px' }}>
+                    <For each={bookmarks()}>
+                      {(bookmark) => (
+                        <div
+                          style={{
+                            display: 'flex',
+                            'align-items': 'center',
+                            gap: '8px',
+                            padding: '4px 8px',
+                            background: theme.bgInput,
+                            'border-radius': 'var(--radius-sm)',
+                            border: `1px solid ${theme.border}`,
+                          }}
+                        >
+                          <span
+                            style={{
+                              flex: '1',
+                              'font-size': '12px',
+                              'font-family': "'JetBrains Mono', monospace",
+                              color: theme.fgSubtle,
+                              overflow: 'hidden',
+                              'text-overflow': 'ellipsis',
+                              'white-space': 'nowrap',
+                            }}
+                          >
+                            {bookmark.command}
+                          </span>
+                          <button
+                            type="button"
+                            onClick={() => removeBookmark(bookmark.id)}
+                            style={{
+                              background: 'transparent',
+                              border: 'none',
+                              color: theme.fgSubtle,
+                              cursor: 'pointer',
+                              padding: '2px',
+                              'line-height': '1',
+                              'flex-shrink': '0',
+                            }}
+                            title="Remove bookmark"
+                          >
+                            <CloseIcon size={12} />
+                          </button>
+                        </div>
+                      )}
+                    </For>
+                  </div>
+                </Show>
+                <div style={{ display: 'flex', gap: '6px' }}>
+                  <input
+                    class="input-field"
+                    type="text"
+                    value={newCommand()}
+                    onInput={(e) => setNewCommand(e.currentTarget.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter') {
+                        e.preventDefault();
+                        addBookmark();
+                      }
+                    }}
+                    placeholder="e.g. npm run dev"
+                    style={{
+                      flex: '1',
+                      background: theme.bgInput,
+                      border: `1px solid ${theme.border}`,
+                      'border-radius': 'var(--radius-md)',
+                      padding: '8px 12px',
+                      color: theme.fg,
+                      'font-size': '13px',
+                      'font-family': "'JetBrains Mono', monospace",
+                      outline: 'none',
+                    }}
+                  />
+                  <button
+                    type="button"
+                    onClick={addBookmark}
+                    disabled={!newCommand().trim()}
+                    style={{
+                      padding: '8px 14px',
+                      background: theme.bgInput,
+                      border: `1px solid ${theme.border}`,
+                      'border-radius': 'var(--radius-md)',
+                      color: newCommand().trim() ? theme.fg : theme.fgSubtle,
+                      cursor: newCommand().trim() ? 'pointer' : 'not-allowed',
+                      'font-size': '13px',
+                      'flex-shrink': '0',
+                    }}
+                  >
+                    Add
+                  </button>
+                </div>
+              </div>
+            </Show>
 
             {/* Buttons */}
             <div
diff --git a/src/components/IconButton.tsx b/src/components/IconButton.tsx
index b46181d47..c5fce9d42 100644
--- a/src/components/IconButton.tsx
+++ b/src/components/IconButton.tsx
@@ -3,7 +3,7 @@ import { theme } from '../lib/theme';
 
 interface IconButtonProps {
   icon: string | JSX.Element;
-  onClick: (e: MouseEvent) => void;
+  onClick: JSX.EventHandler<HTMLButtonElement, MouseEvent>;
   title?: string;
   size?: 'sm' | 'md';
 }
diff --git a/src/components/NewTaskDialog.tsx b/src/components/NewTaskDialog.tsx
index f50f0c1b2..b4b4429b3 100644
--- a/src/components/NewTaskDialog.tsx
+++ b/src/components/NewTaskDialog.tsx
@@ -30,6 +30,7 @@ import {
   setPrefillPrompt,
   setDockerAvailable,
   setDockerImage,
+  codeProjects,
 } from '../store/store';
 import type { GitIsolationMode } from '../store/types';
 import {
@@ -551,7 +552,9 @@ export function NewTaskDialog(props: NewTaskDialogProps) {
 
             // Pre-fill from drop data if present
             const dropUrl = store.newTaskDropUrl;
-            const fallbackProjectId = store.lastProjectId ?? store.projects[0]?.id ?? null;
+            const targets = codeProjects();
+            const fallbackProjectId =
+              targets.find((p) => p.id === store.lastProjectId)?.id ?? targets[0]?.id ?? null;
             const defaults = dropUrl ? getGitHubDropDefaults(dropUrl) : null;
 
             if (dropUrl) setPrompt(`review ${dropUrl}`);
diff --git a/src/components/PlanViewerDialog.tsx b/src/components/PlanViewerDialog.tsx
index 36a5fd76d..4d82476dd 100644
--- a/src/components/PlanViewerDialog.tsx
+++ b/src/components/PlanViewerDialog.tsx
@@ -9,6 +9,7 @@ import { InlineInput } from './InlineInput';
 import { AskCodeCard } from './AskCodeCard';
 import { CloseIcon } from './icons';
 import { createHighlightedMarkdown } from '../lib/marked-shiki';
+import { renderMermaidIn } from '../lib/mermaid';
 import {
   getPlanSelection,
   getPlanSelectionFlowAnchor,
@@ -134,21 +135,7 @@ function PlanViewerContent(props: PlanViewerContentProps) {
   // Render mermaid blocks after HTML is inserted
   createEffect(() => {
     void planHtml(); // track dependency
-    if (!contentRef) return;
-    const blocks = contentRef.querySelectorAll('.mermaid-block');
-    if (blocks.length === 0) return;
-    import('mermaid').then(({ default: mermaid }) => {
-      mermaid.initialize({ startOnLoad: false, theme: 'dark' });
-      blocks.forEach((el, i) => {
-        const source = el.getAttribute('data-mermaid');
-        if (!source) return;
-        const id = `mermaid-plan-${Date.now()}-${i}`;
-        mermaid.render(id, source).then(({ svg }) => {
-          el.innerHTML = svg; // nosemgrep: semgrep.no-inner-html-without-sanitize -- mermaid renders its own sanitized SVG; source is plan text not user HTML
-          el.classList.add('mermaid-rendered');
-        });
-      });
-    });
+    renderMermaidIn(contentRef, 'plan');
   });
 
   // Scroll to annotation when scrollTarget changes
diff --git a/src/components/ProjectSelect.tsx b/src/components/ProjectSelect.tsx
index 26ec7fb11..806727749 100644
--- a/src/components/ProjectSelect.tsx
+++ b/src/components/ProjectSelect.tsx
@@ -1,5 +1,5 @@
 import { For, Show } from 'solid-js';
-import { store } from '../store/store';
+import { codeProjects } from '../store/projects';
 
 interface ProjectSelectProps {
   value: string | null;
@@ -20,7 +20,7 @@ export function ProjectSelect(props: ProjectSelectProps) {
           {props.placeholder}
         </option>
       </Show>
-      <For each={[...store.projects].sort((a, b) => a.name.localeCompare(b.name))}>
+      <For each={codeProjects().sort((a, b) => a.name.localeCompare(b.name))}>
         {(project) => (
           <option value={project.id}>
             {project.name} — {project.path}
diff --git a/src/components/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index c17d14e96..13e9372af 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -35,6 +35,7 @@ import {
   setLightTheme,
   setDarkTheme,
   setCoordinatorModeEnabled,
+  setDocumentWorkspacesEnabled,
   setCoordinatorNotificationDelayMs,
   setDefaultStepsEnabled,
   setDefaultSkipPermissions,
@@ -1075,6 +1076,14 @@ export function SettingsDialog(props: SettingsDialogProps) {
           aria-labelledby="settings-tabbutton-experimental"
           style={{ display: 'flex', 'flex-direction': 'column', gap: '18px' }}
         >
+          <SettingsSection title="Document workspaces">
+            <SettingsCheckboxRow
+              label="Document workspaces"
+              checked={store.documentWorkspacesEnabled}
+              onChange={setDocumentWorkspacesEnabled}
+              description="Add document projects: a folder with one Markdown document, set up for you if it is not a Git repository yet. Select a passage, send the same instruction to one or more agents running headlessly in isolated worktrees, compare the proposals side by side, and accept one as a single readable commit. Adds Document project to the + button next to Projects."
+            />
+          </SettingsSection>
           <SettingsSection title="Coordinator">
             <SettingsCheckboxRow
               label="Coordinator mode"
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index b0fcaf095..853721ce1 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -40,6 +40,11 @@ import { computeNeedsInputTasks, jumpToWaitingTask } from '../store/sidebar-atte
 import { ConnectPhoneModal } from './ConnectPhoneModal';
 import { RemoveProjectConfirm } from './RemoveProjectConfirm';
 import { EditProjectDialog } from './EditProjectDialog';
+import { NewDocumentProjectDialog } from '../documents/NewDocumentProjectDialog';
+import { openDocumentWorkspace } from '../documents/store';
+import { codeProjects, isDocumentProject } from '../store/projects';
+import { DocumentIcon } from '../documents/DocumentIcon';
+import { AddProjectMenu } from './AddProjectMenu';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
 import { SidebarFooter } from './SidebarFooter';
 import { IconButton } from './IconButton';
@@ -595,7 +600,27 @@ export function Sidebar() {
     });
   });
 
-  async function handleAddProject() {
+  const [showNewDocumentProject, setShowNewDocumentProject] = createSignal(false);
+  const [addMenuAt, setAddMenuAt] = createSignal<{ left: number; top: number } | null>(null);
+
+  /** With one project kind there is nothing to choose, so "+" stays direct. */
+  function handleAddProject(anchor: HTMLElement) {
+    if (!store.documentWorkspacesEnabled) {
+      void addCodeProject();
+      return;
+    }
+    const rect = anchor.getBoundingClientRect();
+    setAddMenuAt({ left: rect.left, top: rect.bottom + 4 });
+  }
+
+  /** A document project navigates; a code project opens its settings. */
+  function openProjectRow(project: Project): void {
+    if (isDocumentProject(project) && !isProjectMissing(project.id))
+      void openDocumentWorkspace(project.id);
+    else setEditingProject(project);
+  }
+
+  async function addCodeProject() {
     const projectId = await pickAndAddProject();
     if (!projectId) return;
 
@@ -830,7 +855,7 @@ export function Sidebar() {
                   <path d="M7.75 2a.75.75 0 0 1 .75.75V7h4.25a.75.75 0 0 1 0 1.5H8.5v4.25a.75.75 0 0 1-1.5 0V8.5H2.75a.75.75 0 0 1 0-1.5H7V2.75A.75.75 0 0 1 7.75 2Z" />
                 </svg>
               }
-              onClick={() => handleAddProject()}
+              onClick={(e) => handleAddProject(e.currentTarget)}
               title="Add project"
               size="sm"
             />
@@ -862,14 +887,17 @@ export function Sidebar() {
                       tabIndex={0}
                       class="project-row"
                       data-project-id={project.id}
-                      onClick={() => setEditingProject(project)}
+                      onClick={() => openProjectRow(project)}
                       onKeyDown={(e) => {
-                        if (e.key === 'Enter') setEditingProject(project);
+                        if (e.key !== 'Enter') return;
+                        openProjectRow(project);
                       }}
                       title={
                         isProjectMissing(project.id)
                           ? `Folder not found: ${abbreviateHomePath(project.path)}`
-                          : abbreviateHomePath(project.path)
+                          : isDocumentProject(project)
+                            ? `Document workspace: ${project.documentPath} (${abbreviateHomePath(project.path)})`
+                            : abbreviateHomePath(project.path)
                       }
                       style={{
                         display: 'flex',
@@ -886,15 +914,24 @@ export function Sidebar() {
                         'flex-shrink': '0',
                       }}
                     >
-                      <div
-                        style={{
-                          width: '8px',
-                          height: '8px',
-                          'border-radius': '50%',
-                          background: project.color,
-                          'flex-shrink': '0',
-                        }}
-                      />
+                      <Show
+                        when={isDocumentProject(project)}
+                        fallback={
+                          <div
+                            style={{
+                              width: '8px',
+                              height: '8px',
+                              'border-radius': '50%',
+                              background: project.color,
+                              'flex-shrink': '0',
+                            }}
+                          />
+                        }
+                      >
+                        <span style={{ color: project.color, display: 'flex', 'flex-shrink': '0' }}>
+                          <DocumentIcon size={12} />
+                        </span>
+                      </Show>
                       <span
                         style={{
                           flex: '1',
@@ -957,11 +994,11 @@ export function Sidebar() {
 
         {/* New task / Link project button */}
         <Show
-          when={store.projects.length > 0}
+          when={codeProjects().length > 0}
           fallback={
             <button
               class="icon-btn"
-              onClick={() => handleAddProject()}
+              onClick={(e) => handleAddProject(e.currentTarget)}
               style={{
                 background: 'transparent',
                 border: `1px solid ${theme.border}`,
@@ -1031,7 +1068,7 @@ export function Sidebar() {
               const focusedProjectId = store.sidebarFocusedProjectId;
               if (focusedProjectId) {
                 const project = store.projects.find((p) => p.id === focusedProjectId);
-                if (project) setEditingProject(project);
+                if (project) openProjectRow(project);
                 return;
               }
               const taskId = store.sidebarFocusedTaskId;
@@ -1148,6 +1185,23 @@ export function Sidebar() {
         <ConnectPhoneModal open={showConnectPhone()} onClose={() => setShowConnectPhone(false)} />
 
         <EditProjectDialog project={editingProject()} onClose={() => setEditingProject(null)} />
+        <Show when={addMenuAt()}>
+          {(at) => (
+            <AddProjectMenu
+              anchor={at()}
+              onClose={() => setAddMenuAt(null)}
+              onPick={(kind) => {
+                setAddMenuAt(null);
+                if (kind === 'document') setShowNewDocumentProject(true);
+                else void addCodeProject();
+              }}
+            />
+          )}
+        </Show>
+        <NewDocumentProjectDialog
+          open={showNewDocumentProject()}
+          onClose={() => setShowNewDocumentProject(false)}
+        />
         <ImportWorktreesDialog
           open={importProject() !== null}
           project={importProject()}
diff --git a/src/components/TaskNotesBody.client.test.tsx b/src/components/TaskNotesBody.client.test.tsx
new file mode 100644
index 000000000..60750cf8b
--- /dev/null
+++ b/src/components/TaskNotesBody.client.test.tsx
@@ -0,0 +1,91 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { Task } from '../store/types';
+import { TaskNotesBody } from './TaskNotesBody';
+
+vi.mock('../store/store', () => ({
+  store: { showPlans: true, focusMode: false },
+  updateTaskNotes: vi.fn(),
+  setTaskFocusedPanel: vi.fn(),
+  sendPrompt: vi.fn(),
+  isAgentAskingQuestion: () => false,
+  isPanelFocused: () => false,
+  registerFocusFn: vi.fn(),
+  unregisterFocusFn: vi.fn(),
+}));
+
+vi.mock('mermaid', () => ({
+  default: {
+    initialize: vi.fn(),
+    render: async (id: string) => ({ svg: `<svg id="${id}"></svg>` }),
+  },
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+});
+
+async function waitFor<T>(probe: () => T | null | undefined): Promise<T> {
+  for (let attempt = 0; attempt < 200; attempt++) {
+    const value = probe();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  throw new Error('Condition never became true');
+}
+
+const task: Task = {
+  id: 'task-1',
+  name: 'Task',
+  projectId: 'project-1',
+  branchName: 'task/plan',
+  worktreePath: '/tmp/task',
+  agentIds: [],
+  shellAgentIds: [],
+  notes: '',
+  lastPrompt: '',
+  gitIsolation: 'worktree',
+  planContent: '# Plan\n\n```mermaid\ngraph TD;\n  A-->B;\n```\n',
+  planFileName: 'plan.md',
+};
+
+describe('TaskNotesBody plan tab', () => {
+  it('renders mermaid fences as diagrams', async () => {
+    const container = document.createElement('div');
+    document.body.append(container);
+    disposers.push(
+      render(
+        () => <TaskNotesBody task={task} agentId="agent-1" onPlanFullscreen={() => undefined} />,
+        container,
+      ),
+    );
+
+    const block = await waitFor(() => container.querySelector<HTMLElement>('.mermaid-block'));
+    expect(block.getAttribute('data-mermaid')).toContain('graph TD');
+
+    await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    expect(block.innerHTML).toContain('<svg');
+  });
+
+  it('re-renders the diagram after switching away from the plan tab and back', async () => {
+    const container = document.createElement('div');
+    document.body.append(container);
+    disposers.push(
+      render(
+        () => <TaskNotesBody task={task} agentId="agent-1" onPlanFullscreen={() => undefined} />,
+        container,
+      ),
+    );
+
+    const first = await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    const [notesTab, planTab] = Array.from(container.querySelectorAll('button'));
+    notesTab.click();
+    planTab.click();
+
+    const second = await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    expect(second).not.toBe(first);
+  });
+});
diff --git a/src/components/TaskNotesBody.tsx b/src/components/TaskNotesBody.tsx
index c5246649d..af0405a06 100644
--- a/src/components/TaskNotesBody.tsx
+++ b/src/components/TaskNotesBody.tsx
@@ -10,6 +10,7 @@ import {
 import { theme } from '../lib/theme';
 import { sf } from '../lib/fontScale';
 import { createHighlightedMarkdown } from '../lib/marked-shiki';
+import { renderMermaidIn } from '../lib/mermaid';
 import { useFocusRegistration } from '../lib/focus-registration';
 import type { Task } from '../store/types';
 
@@ -59,13 +60,21 @@ export function TaskNotesBody(props: TaskNotesBodyProps) {
   });
 
   let notesRef: HTMLTextAreaElement | undefined;
-  let planScrollRef: HTMLDivElement | undefined;
+  // A signal, not a plain ref: the plan pane is inside <Show>, so it is created
+  // anew on every tab switch and the mermaid effect has to run again for it.
+  const [planScrollRef, setPlanScrollRef] = createSignal<HTMLDivElement>();
+
+  // The markdown renderer only leaves placeholders for ```mermaid fences.
+  createEffect(() => {
+    void planHtml(); // track dependency
+    renderMermaidIn(planScrollRef(), `notes-${props.task.id}`);
+  });
 
   onMount(() => {
     const id = props.task.id;
     useFocusRegistration(`${id}:notes`, () => {
       if (notesTab() === 'plan') {
-        planScrollRef?.focus();
+        planScrollRef()?.focus();
       } else {
         notesRef?.focus();
       }
@@ -211,7 +220,7 @@ export function TaskNotesBody(props: TaskNotesBodyProps) {
           }}
         >
           <div
-            ref={(el) => (planScrollRef = el)}
+            ref={setPlanScrollRef}
             tabIndex={0}
             class="plan-markdown"
             style={{
@@ -230,33 +239,34 @@ export function TaskNotesBody(props: TaskNotesBodyProps) {
                 props.onPlanFullscreen();
                 return;
               }
-              if (!planScrollRef) return;
+              const pane = planScrollRef();
+              if (!pane) return;
               const step = 40;
-              const page = Math.max(100, planScrollRef.clientHeight - 40);
+              const page = Math.max(100, pane.clientHeight - 40);
               switch (e.key) {
                 case 'ArrowDown':
                   e.preventDefault();
-                  planScrollRef.scrollTop += step;
+                  pane.scrollTop += step;
                   break;
                 case 'ArrowUp':
                   e.preventDefault();
-                  planScrollRef.scrollTop -= step;
+                  pane.scrollTop -= step;
                   break;
                 case 'PageDown':
                   e.preventDefault();
-                  planScrollRef.scrollTop += page;
+                  pane.scrollTop += page;
                   break;
                 case 'PageUp':
                   e.preventDefault();
-                  planScrollRef.scrollTop -= page;
+                  pane.scrollTop -= page;
                   break;
                 case 'Home':
                   e.preventDefault();
-                  planScrollRef.scrollTop = 0;
+                  pane.scrollTop = 0;
                   break;
                 case 'End':
                   e.preventDefault();
-                  planScrollRef.scrollTop = planScrollRef.scrollHeight;
+                  pane.scrollTop = pane.scrollHeight;
                   break;
               }
             }}
diff --git a/src/components/TilingLayout.tsx b/src/components/TilingLayout.tsx
index 013be69b0..4858ca87c 100644
--- a/src/components/TilingLayout.tsx
+++ b/src/components/TilingLayout.tsx
@@ -21,6 +21,7 @@ import {
   deletePanelUserSize,
   scrollTaskElementIntoView,
 } from '../store/store';
+import { codeProjects } from '../store/projects';
 import { closeTask } from '../store/tasks';
 import { TaskPanel } from './TaskPanel';
 import { TerminalPanel } from './TerminalPanel';
@@ -441,7 +442,7 @@ export function TilingLayout() {
                 }
               >
                 <Show
-                  when={store.projects.length > 0}
+                  when={codeProjects().length > 0}
                   fallback={
                     <>
                       <div
diff --git a/src/documents/AgentTerminal.tsx b/src/documents/AgentTerminal.tsx
new file mode 100644
index 000000000..e56b80bf4
--- /dev/null
+++ b/src/documents/AgentTerminal.tsx
@@ -0,0 +1,103 @@
+import { For, Show, createMemo, createSignal } from 'solid-js';
+import { TerminalView } from '../components/TerminalView';
+import { store } from '../store/core';
+import { getAgentHookStatus } from '../store/agentHookStatus';
+import { updateProject } from '../store/projects';
+import type { Project } from '../store/types';
+import { documentMainAgentId } from './store';
+import { documentAgentPtyId, documentAgentTaskId } from './agent-terminal';
+import { setAgentRunning, workspaceUi } from './workspace-ui';
+
+interface AgentTerminalProps {
+  project: Project;
+}
+
+/**
+ * The project's long-running interactive agent, in the app's own terminal.
+ * It works in the checkout with the user watching, so its edits show up in the
+ * viewer as they land and are committed as manual edits before the next run.
+ * The session outlives the workspace: closing and reopening re-attaches.
+ */
+export function AgentTerminal(props: AgentTerminalProps) {
+  const [generation, setGeneration] = createSignal(0);
+  const [exited, setExited] = createSignal<number | null | undefined>(undefined);
+  const ptyId = () => documentAgentPtyId(props.project.id);
+  const agents = createMemo(() => store.availableAgents.filter((a) => a.available !== false));
+  const agentId = () => props.project.documentTerminalAgentId ?? documentMainAgentId(props.project);
+  const agent = () => agents().find((a) => a.id === agentId()) ?? agents()[0];
+  const hook = () => getAgentHookStatus(ptyId());
+  const statusLabel = () => {
+    if (exited() !== undefined) return `exited (${exited() ?? '?'})`;
+    const h = hook();
+    if (h?.state === 'waiting') return 'needs you';
+    if (h?.state === 'working') return 'working';
+    return workspaceUi.agentRunning ? 'idle' : 'starting…';
+  };
+
+  // A restart remounts the terminal without attaching: the spawn replaces the
+  // live session in one step. Killing first and then attaching would latch
+  // the new terminal onto the dying process and show its exit.
+  function restart(nextAgentId?: string) {
+    setAgentRunning(false);
+    setExited(undefined);
+    setGeneration((g) => g + 1);
+    if (nextAgentId) updateProject(props.project.id, { documentTerminalAgentId: nextAgentId });
+  }
+
+  return (
+    <div class="docws-agent-pane">
+      <div class="docws-agent-head">
+        <select
+          class="docws-select"
+          aria-label="Interactive agent"
+          value={agent()?.id}
+          onChange={(e) => restart(e.currentTarget.value)}
+        >
+          <For each={agents()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
+        </select>
+        <span
+          class="docws-agent-status"
+          classList={{ 'is-waiting': hook()?.state === 'waiting' && exited() === undefined }}
+        >
+          {statusLabel()}
+        </span>
+        <span class="docws-spacer" />
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm"
+          title="Stop the session and start a fresh one"
+          onClick={() => restart()}
+        >
+          Restart
+        </button>
+      </div>
+      <Show when={agent()} keyed fallback={<div class="docws-empty">No agent is installed.</div>}>
+        {(def) => (
+          <div class="docws-agent-term">
+            <Show when={`${def.id}:${generation()}`} keyed>
+              <TerminalView
+                taskId={documentAgentTaskId(props.project.id)}
+                agentId={ptyId()}
+                command={def.command}
+                args={def.args}
+                cwd={props.project.path}
+                envFile={store.agentEnvFiles[def.id]}
+                bookmarksEnabled={false}
+                attachExisting={generation() === 0}
+                preserveSessionOnCleanup
+                fontSize={12}
+                onData={() => {
+                  if (!workspaceUi.agentRunning) setAgentRunning(true);
+                }}
+                onExit={(info) => {
+                  setAgentRunning(false);
+                  setExited(info.exit_code);
+                }}
+              />
+            </Show>
+          </div>
+        )}
+      </Show>
+    </div>
+  );
+}
diff --git a/src/documents/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
new file mode 100644
index 000000000..1418aed80
--- /dev/null
+++ b/src/documents/AnnotationBubble.tsx
@@ -0,0 +1,224 @@
+import { For, Show, createMemo, createSignal } from 'solid-js';
+import { createHighlightedMarkdown } from '../lib/marked-shiki';
+import { store } from '../store/core';
+import { getProject } from '../store/projects';
+import {
+  askDocumentAnnotation,
+  deleteDocumentAnnotation,
+  documentMainAgentId,
+  documentStore,
+  setDocumentAnnotationResolved,
+  updateDocumentAnnotationText,
+} from './store';
+import { documentAgentSupport } from '../../electron/documents/shared';
+import type { DocumentAnnotation } from './types';
+
+interface AnnotationBubbleProps {
+  annotation: DocumentAnnotation;
+  /** The passage could not be found in the current version. */
+  detached?: boolean;
+  onMakeTask: (annotation: DocumentAnnotation) => void;
+}
+
+/** Short enough to share the head's row with the bubble's buttons. */
+function shortTime(iso: string): string {
+  return new Date(iso).toLocaleString(undefined, { dateStyle: 'short', timeStyle: 'short' });
+}
+
+/**
+ * A note or a question beside the document. Resolved bubbles collapse to one
+ * line; Delete or Backspace on a focused bubble removes it, with undo in the
+ * toolbar instead of a confirmation.
+ */
+export function AnnotationBubble(props: AnnotationBubbleProps) {
+  const [editing, setEditing] = createSignal(false);
+  const [draft, setDraft] = createSignal('');
+  const answerHtml = createHighlightedMarkdown(() => props.annotation.answer?.text);
+  const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
+  const askAgents = createMemo(() =>
+    store.availableAgents.filter(
+      (a) => a.available !== false && documentAgentSupport(a.id).headless,
+    ),
+  );
+  const defaultAgent = () =>
+    askAgents().find((a) => a.id === documentMainAgentId(project())) ?? askAgents()[0];
+  const isQuestion = () => props.annotation.kind === 'question';
+  const status = () => props.annotation.answerStatus;
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (editing()) return;
+    if (e.target instanceof HTMLTextAreaElement || e.target instanceof HTMLInputElement) return;
+    if (e.key === 'Delete' || e.key === 'Backspace') {
+      e.preventDefault();
+      void deleteDocumentAnnotation(props.annotation.id);
+    } else if (e.key === 'r' && !e.metaKey && !e.ctrlKey) {
+      e.preventDefault();
+      void setDocumentAnnotationResolved(props.annotation.id, !props.annotation.resolved);
+    }
+  }
+
+  function startEdit() {
+    setDraft(props.annotation.text);
+    setEditing(true);
+  }
+
+  function commitEdit() {
+    setEditing(false);
+    void updateDocumentAnnotationText(props.annotation.id, draft().trim() || props.annotation.text);
+  }
+
+  const kindLabel = () => (isQuestion() ? 'Question' : 'Note');
+
+  return (
+    <div
+      class="docws-bubble"
+      classList={{
+        'is-resolved': props.annotation.resolved,
+        'is-detached': props.detached === true,
+        'is-question': isQuestion(),
+      }}
+      tabIndex={0}
+      role="group"
+      aria-label={`${kindLabel()}: ${props.annotation.text.slice(0, 80)}`}
+      onKeyDown={handleKeyDown}
+    >
+      <Show
+        when={!props.annotation.resolved}
+        fallback={
+          <button
+            type="button"
+            class="docws-bubble-collapsed"
+            title="Resolved. Click to reopen."
+            onClick={() => void setDocumentAnnotationResolved(props.annotation.id, false)}
+          >
+            <span class="docws-badge">{props.annotation.runId ? 'task' : 'resolved'}</span>
+            <span class="docws-bubble-collapsed-text">{props.annotation.text}</span>
+          </button>
+        }
+      >
+        <div class="docws-bubble-head">
+          <span class="docws-badge">{kindLabel()}</span>
+          <Show when={props.detached}>
+            <span
+              class="docws-badge docws-badge-stale"
+              title="The passage this was attached to is no longer in the document"
+            >
+              detached
+            </span>
+          </Show>
+          <time
+            class="docws-bubble-time"
+            dateTime={props.annotation.createdAt}
+            title={new Date(props.annotation.createdAt).toLocaleString()}
+          >
+            {shortTime(props.annotation.createdAt)}
+          </time>
+          <span class="docws-spacer" />
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title="Resolve (r)"
+            onClick={() => void setDocumentAnnotationResolved(props.annotation.id, true)}
+          >
+            Resolve
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title="Send this to an agent as a task on the passage"
+            onClick={() => props.onMakeTask(props.annotation)}
+          >
+            Make task
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-danger"
+            title="Delete (Del). Undo from the toolbar."
+            onClick={() => void deleteDocumentAnnotation(props.annotation.id)}
+          >
+            ×
+          </button>
+        </div>
+        <Show when={props.detached}>
+          <div class="docws-bubble-quote" title="Passage as it was when the note was written">
+            {props.annotation.anchor.quote.slice(0, 300)}
+          </div>
+        </Show>
+        <Show
+          when={!editing()}
+          fallback={
+            <textarea
+              class="docws-note"
+              value={draft()}
+              onInput={(e) => setDraft(e.currentTarget.value)}
+              onBlur={commitEdit}
+              onKeyDown={(e) => {
+                if (e.key === 'Escape') {
+                  e.stopPropagation();
+                  setEditing(false);
+                }
+                if (e.key === 'Enter' && !e.shiftKey) {
+                  e.preventDefault();
+                  commitEdit();
+                }
+              }}
+              ref={(el) => requestAnimationFrame(() => el.focus())}
+            />
+          }
+        >
+          <div class="docws-bubble-text" onDblClick={startEdit} title="Double-click to edit">
+            {props.annotation.text}
+          </div>
+        </Show>
+        <Show when={isQuestion()}>
+          <div class="docws-bubble-answer">
+            <Show when={status() === 'pending'}>
+              <div class="docws-bubble-pending">
+                <span class="docws-dot docws-dot-running" /> Answering…
+              </div>
+            </Show>
+            <Show when={status() === 'failed'}>
+              <div class="docws-error">
+                {props.annotation.answerError ?? 'The agent gave no answer.'}
+              </div>
+            </Show>
+            <Show when={props.annotation.answer}>
+              {(answer) => (
+                <>
+                  <div class="docws-bubble-answer-head">
+                    <span class="docws-badge">answer</span>
+                    <span>{answer().agentName}</span>
+                    <Show when={status() === 'answered' && props.annotation.answerError}>
+                      <span class="docws-warning">{props.annotation.answerError}</span>
+                    </Show>
+                  </div>
+                  {/* eslint-disable-next-line solid/no-innerhtml -- DOMPurify-sanitized markdown from the agent's answer */}
+                  <div class="plan-markdown docws-bubble-answer-body" innerHTML={answerHtml()} />
+                </>
+              )}
+            </Show>
+            <Show when={status() !== 'pending' && askAgents().length > 0}>
+              <div class="docws-run-actions">
+                <For each={askAgents()}>
+                  {(agent) => (
+                    <button
+                      type="button"
+                      class="docws-btn docws-btn-sm"
+                      title={`${props.annotation.answer ? 'Ask again' : 'Ask'} ${agent.name}`}
+                      onClick={() => void askDocumentAnnotation(props.annotation.id, agent)}
+                    >
+                      {props.annotation.answer ? 'Ask again' : 'Ask'}
+                      {askAgents().length > 1 || agent.id !== defaultAgent()?.id
+                        ? ` · ${agent.name}`
+                        : ''}
+                    </button>
+                  )}
+                </For>
+              </div>
+            </Show>
+          </div>
+        </Show>
+      </Show>
+    </div>
+  );
+}
diff --git a/src/documents/AnnotationMarker.client.test.tsx b/src/documents/AnnotationMarker.client.test.tsx
new file mode 100644
index 000000000..a6f44ca63
--- /dev/null
+++ b/src/documents/AnnotationMarker.client.test.tsx
@@ -0,0 +1,116 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it } from 'vitest';
+import { AnnotationMarker } from './AnnotationMarker';
+import type { DocumentAnnotation, DocumentAnnotationKind } from './types';
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+});
+
+function annotation(id: string, text: string, kind: DocumentAnnotationKind): DocumentAnnotation {
+  return {
+    id,
+    kind,
+    text,
+    anchor: {
+      path: 'notes.md',
+      baseSha: null,
+      startLine: 1,
+      endLine: 2,
+      quote: 'The passage',
+      prefix: '',
+      suffix: '',
+    },
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    resolved: false,
+  };
+}
+
+function mount(annotations: DocumentAnnotation[]): HTMLDivElement {
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(() => <AnnotationMarker annotations={annotations} onMakeTask={() => {}} />, host),
+  );
+  return host;
+}
+
+describe('AnnotationMarker', () => {
+  it('names the notes and questions it holds', () => {
+    const host = mount([
+      annotation('a', 'A thought', 'note'),
+      annotation('b', 'A doubt', 'question'),
+    ]);
+
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+
+    expect(button?.getAttribute('aria-label')).toBe('1 note and 1 question on this passage');
+    expect(button?.textContent).toContain('2');
+  });
+
+  it('spins while a question waits on its agent', () => {
+    const host = mount([
+      { ...annotation('b', 'A doubt', 'question'), answerStatus: 'pending' as const },
+    ]);
+
+    expect(host.querySelector('.docws-marker-btn .inline-spinner')).not.toBeNull();
+    expect(host.querySelector('.docws-marker-btn svg')).toBeNull();
+    expect(host.querySelector('.docws-marker-btn')?.getAttribute('aria-label')).toBe(
+      '1 question on this passage, waiting for an answer',
+    );
+  });
+
+  it('goes back to the glyph once the answer is in, and never spins for a note', () => {
+    const answered = mount([
+      { ...annotation('b', 'A doubt', 'question'), answerStatus: 'answered' as const },
+    ]);
+    const note = mount([annotation('a', 'A thought', 'note')]);
+
+    for (const host of [answered, note]) {
+      expect(host.querySelector('.inline-spinner')).toBeNull();
+      expect(host.querySelector('.docws-marker-btn svg')).not.toBeNull();
+    }
+  });
+
+  it('keeps the notes out of the prose and in the marker instead', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+
+    expect(host.querySelector('.docws-marker-pop')?.textContent).toContain('A thought');
+    // Nothing but the marker: the block itself is left as it was written.
+    expect(host.firstElementChild?.className).toContain('docws-marker');
+  });
+
+  it('shortens the time in the popover but keeps the exact stamp reachable', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const time = host.querySelector<HTMLElement>('.docws-marker-pop .docws-bubble-time');
+    const exact = new Date('2026-01-01T00:00:00.000Z').toLocaleString();
+
+    // The head shares its row with three buttons, so the stamp travels in the
+    // title and the machine-readable value in the attribute, leaving only the
+    // short form to take space.
+    expect(time?.tagName).toBe('TIME');
+    expect(time?.getAttribute('datetime')).toBe('2026-01-01T00:00:00.000Z');
+    expect(time?.title).toBe(exact);
+    expect(time?.textContent).toMatch(/\d/);
+    expect(time?.textContent?.length ?? 0).toBeLessThan(exact.length);
+  });
+
+  it('pins the notes open on a click and lets Escape close them again', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const marker = host.querySelector<HTMLElement>('.docws-marker');
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+
+    button?.click();
+    expect(button?.getAttribute('aria-expanded')).toBe('true');
+    expect(marker?.className).toContain('is-pinned');
+
+    marker?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+
+    expect(button?.getAttribute('aria-expanded')).toBe('false');
+    expect(marker?.className).not.toContain('is-pinned');
+  });
+});
diff --git a/src/documents/AnnotationMarker.tsx b/src/documents/AnnotationMarker.tsx
new file mode 100644
index 000000000..d73678066
--- /dev/null
+++ b/src/documents/AnnotationMarker.tsx
@@ -0,0 +1,108 @@
+import { For, Show, createEffect, createSignal, onCleanup } from 'solid-js';
+import { AnnotationBubble } from './AnnotationBubble';
+import type { DocumentAnnotation } from './types';
+
+interface AnnotationMarkerProps {
+  annotations: DocumentAnnotation[];
+  onMakeTask: (annotation: DocumentAnnotation) => void;
+}
+
+function describe(annotations: readonly DocumentAnnotation[]): string {
+  const questions = annotations.filter((a) => a.kind === 'question').length;
+  const notes = annotations.length - questions;
+  const parts: string[] = [];
+  if (notes > 0) parts.push(`${notes} note${notes === 1 ? '' : 's'}`);
+  if (questions > 0) parts.push(`${questions} question${questions === 1 ? '' : 's'}`);
+  return `${parts.join(' and ')} on this passage`;
+}
+
+/** A question the agent has not come back on yet. */
+function isAwaitingAnswer(annotation: DocumentAnnotation): boolean {
+  return annotation.kind === 'question' && annotation.answerStatus === 'pending';
+}
+
+/**
+ * The notes on a passage as a symbol in its margin. They open over the
+ * document on hover, on keyboard focus, or pinned by a click, so the prose
+ * reads exactly as it does without them.
+ */
+export function AnnotationMarker(props: AnnotationMarkerProps) {
+  let root: HTMLDivElement | undefined;
+  const [pinned, setPinned] = createSignal(false);
+  const awaiting = () => props.annotations.some(isAwaitingAnswer);
+  const label = () =>
+    `${describe(props.annotations)}${awaiting() ? ', waiting for an answer' : ''}`;
+
+  // A pinned bubble covers the prose, so anything else the reader does closes it.
+  createEffect(() => {
+    if (!pinned()) return;
+    const close = (e: MouseEvent) => {
+      if (!root?.contains(e.target as Node)) setPinned(false);
+    };
+    document.addEventListener('mousedown', close);
+    onCleanup(() => document.removeEventListener('mousedown', close));
+  });
+
+  return (
+    <div
+      ref={root}
+      class="docws-marker"
+      classList={{
+        'is-pinned': pinned(),
+        'is-question': props.annotations.some((a) => a.kind === 'question'),
+      }}
+      onKeyDown={(e) => {
+        if (e.key !== 'Escape' || !pinned()) return;
+        e.stopPropagation();
+        setPinned(false);
+      }}
+    >
+      <button
+        type="button"
+        class="docws-marker-btn"
+        aria-label={label()}
+        aria-expanded={pinned()}
+        onClick={(e) => {
+          const open = !pinned();
+          setPinned(open);
+          // Focus alone holds the bubble open, so a click that closes it has to
+          // give the focus back. A keyboard activation (detail 0) keeps it.
+          if (!open && e.detail > 0) e.currentTarget.blur();
+        }}
+      >
+        {/* A question waiting on its agent spins in the margin, so the wait is
+            visible without opening the bubble to read "Answering…". */}
+        <Show
+          when={awaiting()}
+          fallback={
+            <svg
+              width="12"
+              height="12"
+              viewBox="0 0 16 16"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="1.6"
+              stroke-linecap="round"
+              aria-hidden="true"
+            >
+              <rect x="1.6" y="2.6" width="12.8" height="10.8" rx="2.4" />
+              <path d="M4.6 6.4h6.8M4.6 9.4h4.2" />
+            </svg>
+          }
+        >
+          <span class="inline-spinner" aria-hidden="true" />
+        </Show>
+        <Show when={props.annotations.length > 1}>
+          <span class="docws-marker-count">{props.annotations.length}</span>
+        </Show>
+      </button>
+      <div class="docws-marker-pop" role="group" aria-label={label()}>
+        <For each={props.annotations}>
+          {(annotation) => (
+            <AnnotationBubble annotation={annotation} onMakeTask={props.onMakeTask} />
+          )}
+        </For>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/BlockActions.client.test.tsx b/src/documents/BlockActions.client.test.tsx
new file mode 100644
index 000000000..db5815f4a
--- /dev/null
+++ b/src/documents/BlockActions.client.test.tsx
@@ -0,0 +1,128 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DocumentViewer } from './DocumentViewer';
+import type { DocumentBlock } from './markdown-blocks';
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'heading',
+    raw: '# Title\n',
+    html: '<h1>Title</h1>',
+    startLine: 1,
+    endLine: 1,
+    headingLevel: 1,
+    headingText: 'Title',
+  },
+  {
+    index: 1,
+    type: 'paragraph',
+    raw: 'Body text.\n',
+    html: '<p>Body text.</p>',
+    startLine: 3,
+    endLine: 3,
+  },
+];
+
+describe('block hover actions', () => {
+  it('offers every composer mode and edit on each block, and reports the block picked', () => {
+    const onAction = vi.fn();
+    const onSelect = vi.fn();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => (
+          <DocumentViewer
+            blocks={blocks}
+            renderKey="t"
+            selectable
+            onSelect={onSelect}
+            onAction={onAction}
+          />
+        ),
+        host,
+      ),
+    );
+
+    const toolbars = host.querySelectorAll('[data-block-index] .docws-block-actions');
+    expect(toolbars).toHaveLength(2);
+    const second = host.querySelector<HTMLElement>('[data-block-index="1"]');
+    const labels = Array.from(second?.querySelectorAll('button') ?? []).map((b) =>
+      b.getAttribute('aria-label'),
+    );
+    expect(labels).toEqual([
+      'Task on this block',
+      'Proposals for this block',
+      'Note beside this block',
+      'Ask an agent about this block',
+      'Edit this block',
+    ]);
+
+    second?.querySelector<HTMLButtonElement>('[aria-label="Note beside this block"]')?.click();
+    second?.querySelector<HTMLButtonElement>('[aria-label="Proposals for this block"]')?.click();
+    second?.querySelector<HTMLButtonElement>('[aria-label="Edit this block"]')?.click();
+
+    expect(onAction).toHaveBeenNthCalledWith(1, 'note', 1);
+    expect(onAction).toHaveBeenNthCalledWith(2, 'proposals', 1);
+    expect(onAction).toHaveBeenNthCalledWith(3, 'edit', 1);
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  it('gives the task and edit actions different icons', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => <DocumentViewer blocks={blocks} renderKey="t" selectable onAction={() => {}} />,
+        host,
+      ),
+    );
+
+    const icon = (label: string) =>
+      host.querySelector(`[aria-label="${label}"] path`)?.getAttribute('d');
+    expect(icon('Task on this block')).not.toEqual(icon('Edit this block'));
+  });
+
+  it('keeps the toolbars on the other blocks while a passage is picked', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => (
+          <DocumentViewer
+            blocks={blocks}
+            renderKey="t"
+            selectable
+            selection={{ start: 1, end: 1 }}
+            onAction={() => {}}
+          />
+        ),
+        host,
+      ),
+    );
+
+    // The picked block's toolbar is hidden by style; the rest stay in reach.
+    expect(host.querySelector('[data-block-index="1"]')?.classList.contains('is-selected')).toBe(
+      true,
+    );
+    expect(host.querySelectorAll('[data-block-index="0"] .docws-block-actions')).toHaveLength(1);
+  });
+
+  it('shows no toolbar when the viewer is not selectable', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <DocumentViewer blocks={blocks} renderKey="t" onAction={() => {}} />, host),
+    );
+
+    expect(host.querySelector('.docws-block-actions')).toBeNull();
+  });
+});
diff --git a/src/documents/BlockActions.tsx b/src/documents/BlockActions.tsx
new file mode 100644
index 000000000..c9b214e54
--- /dev/null
+++ b/src/documents/BlockActions.tsx
@@ -0,0 +1,111 @@
+import { For } from 'solid-js';
+import type { ComposerMode } from './store';
+
+/** A composer mode, or editing the block's source in place. */
+export type BlockActionKind = ComposerMode | 'edit';
+
+interface BlockAction {
+  kind: BlockActionKind;
+  title: string;
+  /** 16×16 icon path. */
+  path: string;
+}
+
+/** What one can do with a block: the composer's tabs in order, then editing. */
+export const BLOCK_ACTIONS: readonly BlockAction[] = [
+  {
+    kind: 'task',
+    title: 'Task on this block',
+    path: 'M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004L9.503.429Zm1.047 1.074L3.286 8.571A.25.25 0 0 0 3.462 9H6.75a.75.75 0 0 1 .694 1.034l-1.713 4.188 6.982-6.793A.25.25 0 0 0 12.538 7H9.25a.75.75 0 0 1-.683-1.06l2.008-4.418.003-.006a.036.036 0 0 0-.004-.009l-.006-.006-.008-.001c-.003 0-.006.002-.009.004Z',
+  },
+  {
+    kind: 'proposals',
+    title: 'Proposals for this block',
+    path: 'M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z',
+  },
+  {
+    kind: 'note',
+    title: 'Note beside this block',
+    path: 'M0 3.75C0 2.784.784 2 1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25Zm1.75-.25a.25.25 0 0 0-.25.25v8.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25ZM3.5 6.25a.75.75 0 0 1 .75-.75h7a.75.75 0 0 1 0 1.5h-7a.75.75 0 0 1-.75-.75Zm.75 2.25h4a.75.75 0 0 1 0 1.5h-4a.75.75 0 0 1 0-1.5Z',
+  },
+  {
+    kind: 'question',
+    title: 'Ask an agent about this block',
+    path: 'M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.92 6.085h.001a.749.749 0 1 1-1.342-.67c.169-.339.436-.701.849-.977C6.845 4.16 7.369 4 8 4a2.756 2.756 0 0 1 1.637.525c.503.377.863.965.863 1.725 0 .448-.115.83-.329 1.15-.205.307-.47.513-.692.662-.109.072-.22.138-.313.195l-.006.004a6.24 6.24 0 0 0-.26.16.952.952 0 0 0-.276.245.75.75 0 0 1-1.248-.832c.184-.264.42-.489.692-.661.103-.067.207-.132.313-.195l.007-.004c.1-.061.182-.11.258-.161a.969.969 0 0 0 .277-.245C8.96 6.514 9 6.427 9 6.25a.612.612 0 0 0-.262-.525A1.27 1.27 0 0 0 8 5.5c-.369 0-.595.09-.74.187a1.01 1.01 0 0 0-.34.398ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z',
+  },
+  {
+    kind: 'edit',
+    title: 'Edit this block',
+    path: 'M11.013 1.427a1.75 1.75 0 0 1 2.474 0l1.086 1.086a1.75 1.75 0 0 1 0 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 0 1-.927-.928l.929-3.25c.081-.286.235-.547.445-.758l8.61-8.61Zm.176 4.823L9.75 4.81l-6.286 6.287a.253.253 0 0 0-.064.108l-.558 1.953 1.953-.558a.253.253 0 0 0 .108-.064Zm1.238-3.763a.25.25 0 0 0-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 0 0 0-.354Z',
+  },
+];
+
+function iconPath(kind: BlockActionKind): string {
+  return BLOCK_ACTIONS.find((a) => a.kind === kind)?.path ?? '';
+}
+
+function iconSvg(path: string): string {
+  return `<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="${path}"/></svg>`;
+}
+
+/** One action's glyph, the same in the block toolbar and on the composer's tabs. */
+export function ActionIcon(props: { kind: BlockActionKind }) {
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      <path d={iconPath(props.kind)} />
+    </svg>
+  );
+}
+
+/**
+ * A block's hover toolbar: task, note, ask, edit. One click picks the block
+ * and opens the composer on that mode (or the source editor), instead of pick
+ * first and choose after.
+ */
+export function BlockActions(props: { onAction: (kind: BlockActionKind) => void }) {
+  return (
+    <span class="docws-block-actions" role="toolbar" aria-label="Block actions">
+      <For each={BLOCK_ACTIONS}>
+        {(action) => (
+          <button
+            type="button"
+            class="docws-block-action"
+            data-kind={action.kind}
+            aria-label={action.title}
+            onClick={(e) => {
+              e.stopPropagation();
+              props.onAction(action.kind);
+            }}
+          >
+            <ActionIcon kind={action.kind} />
+          </button>
+        )}
+      </For>
+    </span>
+  );
+}
+
+/** The same toolbar as plain DOM, for pages whose markup is rendered whole. */
+export function createBlockActionsElement(
+  onAction: (kind: BlockActionKind, e: MouseEvent) => void,
+): HTMLSpanElement {
+  const bar = document.createElement('span');
+  bar.className = 'docws-block-actions';
+  bar.setAttribute('role', 'toolbar');
+  bar.setAttribute('aria-label', 'Block actions');
+  for (const action of BLOCK_ACTIONS) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'docws-block-action';
+    button.dataset.kind = action.kind;
+    button.setAttribute('aria-label', action.title);
+    // A constant icon of our own, not page content.
+    button.innerHTML = iconSvg(action.path);
+    button.onclick = (e) => {
+      e.stopPropagation();
+      onAction(action.kind, e);
+    };
+    bar.append(button);
+  }
+  return bar;
+}
diff --git a/src/documents/BlockEditor.client.test.tsx b/src/documents/BlockEditor.client.test.tsx
new file mode 100644
index 000000000..b79d872b4
--- /dev/null
+++ b/src/documents/BlockEditor.client.test.tsx
@@ -0,0 +1,92 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { BlockEditor, type BlockEditTarget } from './BlockEditor';
+import { invoke } from '../lib/ipc';
+import { IPC } from '../../electron/ipc/channels';
+
+vi.mock('../lib/ipc', () => ({ invoke: vi.fn() }));
+let dispose: (() => void) | undefined;
+afterEach(() => {
+  dispose?.();
+  document.body.replaceChildren();
+  vi.resetAllMocks();
+});
+
+const target: BlockEditTarget = {
+  projectRoot: '/project',
+  documentPath: 'plan.md',
+  source: '# Plan\r\n\r\nTypo.\r\n',
+  block: {
+    index: 1,
+    type: 'paragraph',
+    raw: 'Typo.\n',
+    html: '<p>Typo.</p>',
+    startLine: 3,
+    endLine: 3,
+    startOffset: 8,
+    endOffset: 13,
+  },
+};
+
+function mount() {
+  const host = document.createElement('div');
+  document.body.append(host);
+  const onClose = vi.fn();
+  const onSaved = vi.fn();
+  dispose = render(() => <BlockEditor target={target} onClose={onClose} onSaved={onSaved} />, host);
+  return { onClose, onSaved };
+}
+
+describe('BlockEditor', () => {
+  it('reports a block that no longer matches the file instead of throwing', () => {
+    const moved: BlockEditTarget = { ...target, source: '# Plan\r\n\r\nSomething else.\r\n' };
+    const host = document.createElement('div');
+    document.body.append(host);
+    expect(() => {
+      dispose = render(
+        () => <BlockEditor target={moved} onClose={() => {}} onSaved={() => {}} />,
+        host,
+      );
+    }).not.toThrow();
+    expect(document.querySelector('[role="alert"]')?.textContent).toContain('Select it again');
+    expect(document.querySelector('textarea')).toBeNull();
+    expect(document.querySelector('.docws-btn-primary')).toBeNull();
+  });
+
+  it('saves just the selected range with the original newline convention', async () => {
+    vi.mocked(invoke).mockResolvedValue(undefined);
+    const { onClose, onSaved } = mount();
+    const input = document.querySelector('textarea') as HTMLTextAreaElement;
+    const save = document.querySelector('.docws-btn-primary') as HTMLButtonElement;
+    expect(input.value).toBe('Typo.');
+    expect(save.disabled).toBe(true);
+    input.value = 'Corrected.\nAnother line.';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    save.click();
+    await vi.waitFor(() => expect(onSaved).toHaveBeenCalledOnce());
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(invoke).toHaveBeenCalledWith(IPC.WriteDocumentBlock, {
+      projectRoot: '/project',
+      documentPath: 'plan.md',
+      expectedContent: target.source,
+      startOffset: 10,
+      endOffset: 15,
+      replacement: 'Corrected.\r\nAnother line.',
+    });
+  });
+
+  it('preserves the edit and stays open when the file has changed', async () => {
+    vi.mocked(invoke).mockRejectedValue(new Error('The document changed.'));
+    const { onClose, onSaved } = mount();
+    const input = document.querySelector('textarea') as HTMLTextAreaElement;
+    input.value = 'My correction';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    (document.querySelector('.docws-btn-primary') as HTMLButtonElement).click();
+    await vi.waitFor(() =>
+      expect(document.querySelector('[role="alert"]')?.textContent).toBe('The document changed.'),
+    );
+    expect(input.value).toBe('My correction');
+    expect(onClose).not.toHaveBeenCalled();
+    expect(onSaved).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/documents/BlockEditor.tsx b/src/documents/BlockEditor.tsx
new file mode 100644
index 000000000..6ed63b6f2
--- /dev/null
+++ b/src/documents/BlockEditor.tsx
@@ -0,0 +1,112 @@
+import { Show, createSignal, createUniqueId, untrack } from 'solid-js';
+import { Dialog } from '../components/Dialog';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { errMessage } from '../lib/log';
+import { normalizeSource, type DocumentBlock } from './markdown-blocks';
+import { blockEditRange } from './block-edit';
+
+export interface BlockEditTarget {
+  projectRoot: string;
+  documentPath: string;
+  source: string;
+  block: DocumentBlock;
+}
+
+/** A small source editor; the surrounding document is preserved byte for byte. */
+export function BlockEditor(props: {
+  target: BlockEditTarget;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const target = untrack(() => props.target);
+  // The block was rendered from an earlier read of the file. If the two have
+  // parted since, the dialog says so; throwing here would escape the render
+  // and take the whole window's error boundary with it.
+  const prepared = ((): { range: ReturnType<typeof blockEditRange> } | { stale: string } => {
+    try {
+      return { range: blockEditRange(target.source, target.block) };
+    } catch (err) {
+      return { stale: errMessage(err) };
+    }
+  })();
+  const stale = 'stale' in prepared ? prepared.stale : '';
+  const initial =
+    'stale' in prepared
+      ? ''
+      : normalizeSource(target.source.slice(prepared.range.startOffset, prepared.range.endOffset));
+  const [text, setText] = createSignal(initial);
+  const [saving, setSaving] = createSignal(false);
+  const [error, setError] = createSignal('');
+  const titleId = createUniqueId();
+  const close = () => {
+    if (!saving()) props.onClose();
+  };
+
+  async function save() {
+    if (saving() || stale || text() === initial) return;
+    setSaving(true);
+    setError('');
+    try {
+      const newline = target.source.match(/\r\n|\r|\n/)?.[0] ?? '\n';
+      await invoke(IPC.WriteDocumentBlock, {
+        projectRoot: target.projectRoot,
+        documentPath: target.documentPath,
+        expectedContent: target.source,
+        ...('stale' in prepared ? {} : prepared.range),
+        replacement: normalizeSource(text()).replace(/\n/g, newline),
+      });
+      props.onSaved();
+      props.onClose();
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <Dialog open onClose={close} width="min(760px, 92vw)" labelledBy={titleId}>
+      <div class="docws-block-editor">
+        <h2 id={titleId}>Edit block</h2>
+        <Show
+          when={!stale}
+          fallback={
+            <p class="docws-error" role="alert">
+              {stale}
+            </p>
+          }
+        >
+          <p>Edit the source for this block. Saving updates {target.documentPath} directly.</p>
+          <textarea
+            aria-label="Block source"
+            value={text()}
+            disabled={saving()}
+            ref={(el) => queueMicrotask(() => el.focus())}
+            onInput={(e) => setText(e.currentTarget.value)}
+          />
+        </Show>
+        <Show when={error()}>
+          <p class="docws-error" role="alert">
+            {error()}
+          </p>
+        </Show>
+        <div class="docws-run-actions">
+          <button class="docws-btn" type="button" onClick={close} disabled={saving()}>
+            {stale ? 'Close' : 'Cancel'}
+          </button>
+          <Show when={!stale}>
+            <button
+              class="docws-btn docws-btn-primary"
+              type="button"
+              disabled={saving() || text() === initial}
+              onClick={() => void save()}
+            >
+              {saving() ? 'Saving…' : 'Save block'}
+            </button>
+          </Show>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/src/documents/CandidateOutputDialog.tsx b/src/documents/CandidateOutputDialog.tsx
new file mode 100644
index 000000000..7fd52ad14
--- /dev/null
+++ b/src/documents/CandidateOutputDialog.tsx
@@ -0,0 +1,101 @@
+import { Show, createEffect, createMemo, createSignal, on, onCleanup } from 'solid-js';
+import { Dialog } from '../components/Dialog';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { errMessage } from '../lib/log';
+import { getProject } from '../store/projects';
+import { documentStore, modelLabel } from './store';
+import { openCandidateOutput, workspaceUi } from './workspace-ui';
+
+/** How often a running candidate's log is re-read. */
+const LIVE_POLL_MS = 1_000;
+
+/**
+ * What one one-shot candidate printed: the readable log the run streamed,
+ * read back from disk so it is there after the run finished or the app
+ * restarted. A running candidate's log grows while the dialog is open.
+ */
+export function CandidateOutputDialog() {
+  const [text, setText] = createSignal('');
+  const [error, setError] = createSignal<string | null>(null);
+  let bodyRef: HTMLPreElement | undefined;
+  const target = () => workspaceUi.output;
+  const run = () => {
+    const t = target();
+    return t ? documentStore.runs[t.runId] : undefined;
+  };
+  const candidate = createMemo(() => run()?.candidates.find((c) => c.id === target()?.candidateId));
+  const projectRoot = () =>
+    documentStore.projectId ? getProject(documentStore.projectId)?.path : undefined;
+
+  async function load() {
+    const t = target();
+    const root = projectRoot();
+    if (!t || !root) return;
+    try {
+      const log = await invoke<string>(IPC.ReadDocumentCandidateLog, { projectRoot: root, ...t });
+      if (workspaceUi.output !== t) return;
+      const stuck =
+        !!bodyRef && bodyRef.scrollTop + bodyRef.clientHeight >= bodyRef.scrollHeight - 8;
+      setText(log);
+      setError(null);
+      if (stuck) requestAnimationFrame(() => bodyRef?.scrollTo({ top: bodyRef.scrollHeight }));
+    } catch (err) {
+      setError(errMessage(err));
+    }
+  }
+
+  createEffect(
+    on(target, (t) => {
+      setText('');
+      setError(null);
+      if (!t) return;
+      void load();
+    }),
+  );
+
+  createEffect(() => {
+    if (!target() || candidate()?.status !== 'running') return;
+    const timer = setInterval(() => void load(), LIVE_POLL_MS);
+    onCleanup(() => clearInterval(timer));
+  });
+
+  return (
+    <Dialog open={!!target()} onClose={() => openCandidateOutput(null)} width="min(900px, 92vw)">
+      <Show when={candidate()}>
+        {(c) => (
+          <div class="docws-output">
+            <div class="docws-output-head">
+              <span class="docws-candidate-label">{c().label}</span>
+              <span>{c().agentName}</span>
+              <Show when={c().model || c().effort}>
+                <span class="docws-candidate-model">{modelLabel(c())}</span>
+              </Show>
+              <span class={`docws-badge docws-badge-${c().status}`}>{c().status}</span>
+              <span class="docws-spacer" />
+              <button
+                type="button"
+                class="docws-btn docws-btn-sm"
+                onClick={() => openCandidateOutput(null)}
+              >
+                Close
+              </button>
+            </div>
+            <div class="docws-run-instruction" title={run()?.instruction}>
+              {run()?.instruction}
+            </div>
+            <Show when={c().error}>
+              <div class="docws-error">{c().error}</div>
+            </Show>
+            <Show when={error()}>
+              <div class="docws-error">{error()}</div>
+            </Show>
+            <pre class="docws-output-body" ref={bodyRef}>
+              {text() || (c().status === 'running' ? 'Waiting for output…' : 'No output was kept.')}
+            </pre>
+          </div>
+        )}
+      </Show>
+    </Dialog>
+  );
+}
diff --git a/src/documents/CandidateRefinement.client.test.tsx b/src/documents/CandidateRefinement.client.test.tsx
new file mode 100644
index 000000000..edd9f2fee
--- /dev/null
+++ b/src/documents/CandidateRefinement.client.test.tsx
@@ -0,0 +1,80 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CandidateRefinement } from './CandidateRefinement';
+import { refineDocumentCandidate } from './store';
+import type { DocumentRunRecord } from './types';
+
+vi.mock('./store', () => ({ refineDocumentCandidate: vi.fn() }));
+let dispose: (() => void) | undefined;
+afterEach(() => {
+  dispose?.();
+  document.body.replaceChildren();
+  vi.resetAllMocks();
+});
+
+const run: DocumentRunRecord = {
+  version: 1,
+  id: 'run-1',
+  documentPath: 'plan.md',
+  createdAt: '',
+  instruction: 'Plan',
+  scope: { path: 'plan.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+  baseSha: 'abcdef123',
+  status: 'finished',
+  candidates: [
+    {
+      id: 'c1',
+      label: 'A',
+      agentId: 'codex',
+      agentName: 'Codex',
+      isMain: false,
+      branch: 'parallel-doc/test-a',
+      worktreePath: '/tmp/test',
+      status: 'done',
+      commitSha: 'abcdef456',
+      startedAt: '',
+    },
+  ],
+};
+
+function mount() {
+  const host = document.createElement('div');
+  document.body.append(host);
+  dispose = render(() => <CandidateRefinement run={run} candidate={run.candidates[0]} />, host);
+  host.querySelector('button')?.click();
+  return host;
+}
+
+describe('CandidateRefinement', () => {
+  it('requires feedback, starts a revision, and closes after success', async () => {
+    vi.mocked(refineDocumentCandidate).mockResolvedValue();
+    const host = mount();
+    const submit = host.querySelector('.docws-btn-primary') as HTMLButtonElement;
+    expect(submit.disabled).toBe(true);
+    const input = host.querySelector('textarea') as HTMLTextAreaElement;
+    input.value = '  Explain the tradeoff  ';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    submit.click();
+    expect(submit.disabled).toBe(true);
+    await vi.waitFor(() => expect(host.querySelector('textarea')).toBeNull());
+    expect(refineDocumentCandidate).toHaveBeenCalledWith(
+      run,
+      run.candidates[0],
+      'Explain the tradeoff',
+    );
+  });
+
+  it('keeps feedback available when dispatch fails', async () => {
+    vi.mocked(refineDocumentCandidate).mockRejectedValue(new Error('Agent is unavailable'));
+    const host = mount();
+    const input = host.querySelector('textarea') as HTMLTextAreaElement;
+    input.value = 'Keep this feedback';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    (host.querySelector('.docws-btn-primary') as HTMLButtonElement).click();
+    await vi.waitFor(() =>
+      expect(host.querySelector('[role="alert"]')?.textContent).toBe('Agent is unavailable'),
+    );
+    expect(input.value).toBe('Keep this feedback');
+    expect(host.querySelector<HTMLButtonElement>('.docws-btn-primary')?.disabled).toBe(false);
+  });
+});
diff --git a/src/documents/CandidateRefinement.tsx b/src/documents/CandidateRefinement.tsx
new file mode 100644
index 000000000..c20938d38
--- /dev/null
+++ b/src/documents/CandidateRefinement.tsx
@@ -0,0 +1,76 @@
+import { Show, createSignal } from 'solid-js';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
+import { refineDocumentCandidate } from './store';
+import { errMessage } from '../lib/log';
+
+export function CandidateRefinement(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+}) {
+  const [open, setOpen] = createSignal(false);
+  const [feedback, setFeedback] = createSignal('');
+  const [starting, setStarting] = createSignal(false);
+  const [error, setError] = createSignal('');
+  const available = () =>
+    props.candidate.status === 'done' &&
+    !!props.candidate.commitSha &&
+    (props.run.status === 'finished' || props.run.status === 'stale');
+
+  async function refine() {
+    if (!available() || !feedback().trim() || starting()) return;
+    setStarting(true);
+    setError('');
+    try {
+      await refineDocumentCandidate(props.run, props.candidate, feedback().trim());
+      setOpen(false);
+      setFeedback('');
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setStarting(false);
+    }
+  }
+
+  return (
+    <Show when={available()}>
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        aria-expanded={open()}
+        onClick={() => setOpen(!open())}
+        disabled={starting()}
+      >
+        Refine this candidate
+      </button>
+      <Show when={open()}>
+        <div class="docws-refinement">
+          <p>
+            Revise this whole proposal with the same agent and model. Your document stays unchanged.
+          </p>
+          <textarea
+            class="docws-note"
+            aria-label="Refinement feedback"
+            placeholder="What should change in this candidate?"
+            ref={(el) => queueMicrotask(() => el.focus())}
+            value={feedback()}
+            onInput={(e) => setFeedback(e.currentTarget.value)}
+            disabled={starting()}
+          />
+          <Show when={error()}>
+            <p class="docws-error" role="alert">
+              {error()}
+            </p>
+          </Show>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            disabled={!feedback().trim() || starting()}
+            onClick={() => void refine()}
+          >
+            {starting() ? 'Starting…' : 'Generate revision'}
+          </button>
+        </div>
+      </Show>
+    </Show>
+  );
+}
diff --git a/src/documents/CompareDialog.tsx b/src/documents/CompareDialog.tsx
new file mode 100644
index 000000000..34e4340a7
--- /dev/null
+++ b/src/documents/CompareDialog.tsx
@@ -0,0 +1,87 @@
+import { For, Show, createMemo, createSignal, type JSX } from 'solid-js';
+import { Dialog } from '../components/Dialog';
+import { closeDocumentCompare, documentStore, openDocumentCompare, reviewableRuns } from './store';
+import { CompareView } from './CompareView';
+
+const WINDOWED: JSX.CSSProperties = {
+  padding: '0',
+  gap: '0',
+  overflow: 'hidden',
+  height: 'min(920px, 88vh)',
+  'max-height': '88vh',
+};
+
+const FULLSCREEN: JSX.CSSProperties = {
+  padding: '0',
+  gap: '0',
+  overflow: 'hidden',
+  height: '100vh',
+  'max-height': '100vh',
+  'border-radius': '0',
+  border: 'none',
+};
+
+/**
+ * The compare view as a modal over the workspace: it wants the whole width
+ * for base and candidates side by side, and it is a decision to make and
+ * leave, not a place to stay. Grows to the full window on request.
+ */
+export function CompareDialog() {
+  const [fullscreen, setFullscreen] = createSignal(false);
+  const reviewable = createMemo(() => reviewableRuns());
+  const runId = () => documentStore.compareRunId;
+  const run = () => {
+    const id = runId();
+    return id ? documentStore.runs[id] : undefined;
+  };
+
+  return (
+    <Dialog
+      open={!!run()}
+      onClose={closeDocumentCompare}
+      width={fullscreen() ? '100vw' : 'min(1500px, 94vw)'}
+      panelStyle={fullscreen() ? FULLSCREEN : WINDOWED}
+    >
+      <div class="docws-compare-dialog">
+        <div class="docws-compare-dialog-head">
+          <span class="docws-rail-title">Compare</span>
+          <Show when={reviewable().length > 1}>
+            <select
+              class="docws-select"
+              aria-label="Run to compare"
+              value={runId() ?? ''}
+              onChange={(e) => openDocumentCompare(e.currentTarget.value)}
+            >
+              <For each={reviewable()}>
+                {(r) => <option value={r.id}>{r.instruction.slice(0, 80)}</option>}
+              </For>
+            </select>
+          </Show>
+          <span class="docws-spacer" />
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            aria-pressed={fullscreen()}
+            title={fullscreen() ? 'Back to a window' : 'Fill the window'}
+            onClick={() => setFullscreen((f) => !f)}
+          >
+            {fullscreen() ? 'Shrink' : 'Fullscreen'}
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title="Close (Esc)"
+            onClick={closeDocumentCompare}
+          >
+            Close
+          </button>
+        </div>
+        <div class="docws-compare-dialog-body">
+          <Show when={run() ? runId() : null} keyed>
+            {(id) => <CompareView run={documentStore.runs[id]} />}
+          </Show>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/src/documents/CompareView.client.test.tsx b/src/documents/CompareView.client.test.tsx
new file mode 100644
index 000000000..63c2dec8b
--- /dev/null
+++ b/src/documents/CompareView.client.test.tsx
@@ -0,0 +1,289 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CompareView } from './CompareView';
+import { deletePanelUserSize, getPanelUserSize, setPanelUserSize } from '../store/store';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
+import { acceptDocumentCandidate } from './store';
+import { IPC } from '../../electron/ipc/channels';
+import * as blockMerge from './block-merge';
+
+const { invoke } = vi.hoisted(() => ({
+  invoke: vi.fn<(channel: string, args?: unknown) => Promise<unknown>>(() =>
+    Promise.resolve('# Doc\n'),
+  ),
+}));
+vi.mock('../lib/ipc', () => ({ invoke }));
+vi.mock('./store', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./store')>()),
+  acceptDocumentCandidate: vi.fn(async () => {}),
+}));
+
+const disposers: Array<() => void> = [];
+const KEYS = ['docws-compare:base', 'docws-compare:candidate-0', 'docws-compare:candidate-1'];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  deletePanelUserSize(KEYS);
+  vi.clearAllMocks();
+  vi.restoreAllMocks();
+  invoke.mockImplementation(() => Promise.resolve('# Doc\n'));
+});
+
+const BASE = '# Doc\n\nOriginal intro.\n\n## Keep\n\nRemove me.\n\n## End\n\nTail.\n';
+const CANDIDATE = '# Doc\n\nBetter intro.\n\n## Keep\n\n## End\n\nTail.\n\nNew ending.\n';
+
+function button(root: ParentNode, label: string): HTMLButtonElement {
+  const found = Array.from(root.querySelectorAll('button')).find((b) => b.textContent === label);
+  if (!found) throw new Error(`Missing button: ${label}`);
+  return found;
+}
+
+async function comparison() {
+  invoke.mockImplementation(async (channel, args) => {
+    if (channel !== IPC.GetDocumentAtCommit) return '';
+    return (args as { sha: string }).sha === run.baseSha ? BASE : CANDIDATE;
+  });
+  const host = mount();
+  const column = host.querySelector('[aria-label="Candidate A"]');
+  if (!column) throw new Error('Candidate A did not render');
+  await vi.waitFor(() =>
+    expect(column.querySelectorAll('.docws-hunk-toggle input')).toHaveLength(3),
+  );
+  return column;
+}
+
+it('previews retained prose, accepted deletions and insertions, then accepts that content', async () => {
+  const column = await comparison();
+  column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.click();
+  button(column, 'Preview result').click();
+  await vi.waitFor(() => {
+    const result = column.querySelector('[aria-label="Result preview"]');
+    expect(result?.textContent).toContain('Original intro.');
+    expect(result?.textContent).toContain('New ending.');
+    expect(result?.textContent).not.toContain('Better intro.');
+    expect(result?.textContent).not.toContain('Remove me.');
+  });
+  button(column, 'Accept 2 of 3 changes').click();
+  await vi.waitFor(() =>
+    expect(acceptDocumentCandidate).toHaveBeenCalledWith('run-1', 'c1', {
+      content: '# Doc\n\nOriginal intro.\n\n## Keep\n\n## End\n\nTail.\n\nNew ending.\n',
+      accepted: 2,
+      total: 3,
+    }),
+  );
+});
+
+it('preserves choices when returning to changes and refreshes the preview after another choice', async () => {
+  const column = await comparison();
+  column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.click();
+  button(column, 'Preview result').click();
+  await vi.waitFor(() =>
+    expect(column.querySelector('[aria-label="Result preview"]')?.textContent).toContain(
+      'Original intro.',
+    ),
+  );
+  button(column, 'Back to changes').click();
+  const toggles = column.querySelectorAll<HTMLInputElement>('.docws-hunk-toggle input');
+  expect(toggles[0].checked).toBe(false);
+  toggles[1].click();
+  button(column, 'Preview result').click();
+  await vi.waitFor(() =>
+    expect(column.querySelector('[aria-label="Result preview"]')?.textContent).toContain(
+      'Remove me.',
+    ),
+  );
+  expect(button(column, 'Accept 1 of 3 changes').disabled).toBe(false);
+});
+
+it('shows the base when every change is declined and prevents accepting nothing', async () => {
+  const column = await comparison();
+  column
+    .querySelectorAll<HTMLInputElement>('.docws-hunk-toggle input')
+    .forEach((input) => input.click());
+  button(column, 'Preview result').click();
+  await vi.waitFor(() => {
+    const result = column.querySelector('[aria-label="Result preview"]');
+    expect(result?.textContent).toContain('Original intro.');
+    expect(result?.textContent).toContain('Remove me.');
+    expect(result?.textContent).not.toContain('New ending.');
+  });
+  expect(button(column, 'Accept 0 of 3 changes').disabled).toBe(true);
+});
+
+it('disables acceptance while composing and reports a failed composition', async () => {
+  const column = await comparison();
+  let finish: (value: null) => void = () => {};
+  vi.spyOn(blockMerge, 'composeVerifiedDocument').mockImplementation(
+    () =>
+      new Promise((resolve) => {
+        finish = resolve;
+      }),
+  );
+  column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.click();
+  button(column, 'Preview result').click();
+  expect(button(column, 'Accept 2 of 3 changes').disabled).toBe(true);
+  expect(column.textContent).toContain('Preparing preview');
+  finish(null);
+  await vi.waitFor(() =>
+    expect(column.querySelector('[role="alert"]')?.textContent).toContain(
+      'cannot be combined cleanly',
+    ),
+  );
+  expect(button(column, 'Accept 2 of 3 changes').disabled).toBe(true);
+  expect(column.textContent).toContain('Preview unavailable');
+  expect(acceptDocumentCandidate).not.toHaveBeenCalled();
+});
+
+it('keeps whole-candidate acceptance when every change is selected', async () => {
+  const column = await comparison();
+  button(column, 'Accept this candidate').click();
+  await vi.waitFor(() => expect(acceptDocumentCandidate).toHaveBeenCalledWith('run-1', 'c1'));
+});
+
+function candidate(id: string, label: string): DocumentCandidateRecord {
+  return {
+    id,
+    label,
+    agentId: 'claude',
+    agentName: 'Claude Code',
+    isMain: label === 'A',
+    branch: `docws/${id}`,
+    worktreePath: `/tmp/${id}`,
+    status: 'done',
+    commitSha: `sha-${id}`,
+    startedAt: new Date(0).toISOString(),
+  };
+}
+
+const run: DocumentRunRecord = {
+  version: 1,
+  id: 'run-1',
+  documentPath: 'doc.md',
+  createdAt: new Date(0).toISOString(),
+  instruction: 'Tighten the intro',
+  scope: { path: 'doc.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+  baseSha: 'abcdef1234',
+  status: 'finished',
+  candidates: [candidate('c1', 'A'), candidate('c2', 'B')],
+};
+
+function mount(): HTMLElement {
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(render(() => <CompareView run={run} />, host));
+  return host;
+}
+
+function drag(seam: Element, from: number, to: number): void {
+  seam.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, clientX: from }));
+  window.dispatchEvent(new MouseEvent('mousemove', { clientX: to }));
+  window.dispatchEvent(new MouseEvent('mouseup'));
+}
+
+describe('CompareView columns', () => {
+  /** happy-dom lays nothing out, so a column reports the width it is given. */
+  function widen(column: Element, width: number): void {
+    column.getBoundingClientRect = () => ({ width }) as DOMRect;
+  }
+
+  function columns(): { host: HTMLElement; seam: Element; base: HTMLElement } {
+    const host = mount();
+    const seam = host.querySelector('.docws-columns > .resize-handle');
+    const base = host.querySelector<HTMLElement>('.docws-column-base');
+    if (!seam || !base) throw new Error('compare columns did not render');
+    return { host, seam, base };
+  }
+
+  it('offers a seam on every column', () => {
+    const host = mount();
+    expect(host.querySelectorAll('.docws-columns > .resize-handle')).toHaveLength(3);
+  });
+
+  it('sizes the column its seam sits behind, starting from that column\u2019s width', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+
+    drag(seam, 100, 200);
+
+    expect(getPanelUserSize('docws-compare:base')).toBe(400);
+    expect(base.style.minWidth).toBe('400px');
+    expect(base.style.maxWidth).toBe('400px');
+  });
+
+  it('follows the pointer live but saves the width only on release', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+
+    seam.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, clientX: 100 }));
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 250 }));
+
+    expect(base.style.minWidth).toBe('450px');
+    expect(getPanelUserSize('docws-compare:base')).toBeUndefined();
+
+    window.dispatchEvent(new MouseEvent('mouseup'));
+
+    expect(getPanelUserSize('docws-compare:base')).toBe(450);
+  });
+
+  it('stops following the pointer once the button is up', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+    drag(seam, 100, 200);
+
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 900 }));
+
+    expect(getPanelUserSize('docws-compare:base')).toBe(400);
+    expect(base.style.minWidth).toBe('400px');
+  });
+
+  it('opens on a width the reader saved earlier', () => {
+    setPanelUserSize('docws-compare:base', 512);
+
+    const { base } = columns();
+
+    expect(base.style.minWidth).toBe('512px');
+  });
+
+  it('gives the width back to the layout on double-click', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+    drag(seam, 100, 200);
+
+    seam.dispatchEvent(new MouseEvent('dblclick', { bubbles: true }));
+
+    expect(getPanelUserSize('docws-compare:base')).toBeUndefined();
+    expect(base.style.minWidth).toBe('');
+  });
+
+  it('never sizes a column below what still reads', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+
+    drag(seam, 600, 0);
+
+    expect(getPanelUserSize('docws-compare:base')).toBe(260);
+  });
+
+  it('leaves the columns alone on a right-button press', () => {
+    const { seam, base } = columns();
+    widen(base, 300);
+
+    seam.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, clientX: 100, button: 2 }));
+    window.dispatchEvent(new MouseEvent('mousemove', { clientX: 500 }));
+    window.dispatchEvent(new MouseEvent('mouseup'));
+
+    expect(getPanelUserSize('docws-compare:base')).toBeUndefined();
+    expect(base.style.minWidth).toBe('');
+  });
+
+  it('sizes a candidate column from its own seam', () => {
+    const host = mount();
+    const seams = host.querySelectorAll('.docws-columns > .resize-handle');
+
+    drag(seams[1], 100, 500);
+
+    expect(getPanelUserSize('docws-compare:candidate-0')).toBeGreaterThan(260);
+    expect(getPanelUserSize('docws-compare:base')).toBeUndefined();
+  });
+});
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
new file mode 100644
index 000000000..4e2684ebb
--- /dev/null
+++ b/src/documents/CompareView.tsx
@@ -0,0 +1,656 @@
+import {
+  For,
+  Index,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  on,
+  onCleanup,
+  untrack,
+  type JSX,
+} from 'solid-js';
+import { CandidateRefinement } from './CandidateRefinement';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { diffBlocks, type BlockChange, type DocumentBlock } from './markdown-blocks';
+import { blockHunks, composeVerifiedDocument, hunkLabel, hunkLeadBlocks } from './block-merge';
+import {
+  acceptDocumentCandidate,
+  documentStore,
+  modelLabel,
+  rejectDocumentRun,
+  setDocumentCandidateNote,
+} from './store';
+import { getProject } from '../store/projects';
+import { deletePanelUserSize, getPanelUserSize, setPanelUserSize } from '../store/store';
+import { showNotification } from '../store/notification';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
+import { DocumentViewer, type BlockRange } from './DocumentViewer';
+import { SourceDiff } from './SourceDiff';
+import { createRenderedBlocks } from './use-blocks';
+import { renderDocument } from './render-document';
+
+function projectRoot(): string {
+  const project = documentStore.projectId ? getProject(documentStore.projectId) : undefined;
+  return project?.path ?? '';
+}
+
+async function fetchDocumentAt(sha: string, documentPath: string): Promise<string | null> {
+  return invoke<string | null>(IPC.GetDocumentAtCommit, {
+    projectRoot: projectRoot(),
+    sha,
+    documentPath,
+  });
+}
+
+/** Blocks that lie inside the run's line scope at the base commit. */
+function scopeRange(blocks: readonly DocumentBlock[], run: DocumentRunRecord): BlockRange | null {
+  if (run.scope.wholeDocument || blocks.length === 0) return null;
+  let start = -1;
+  let end = -1;
+  blocks.forEach((b, i) => {
+    if (b.endLine >= run.scope.startLine && b.startLine <= run.scope.endLine) {
+      if (start === -1) start = i;
+      end = i;
+    }
+  });
+  return start === -1 ? null : { start, end };
+}
+
+/** Scroll a column so its first block matching `selector` sits in the upper third. */
+function revealFirst(body: HTMLElement | undefined, selector: string): void {
+  const target = body?.querySelector<HTMLElement>(selector);
+  if (!body || !target) return;
+  const offset = target.getBoundingClientRect().top - body.getBoundingClientRect().top;
+  body.scrollTop += offset - body.clientHeight / 3;
+}
+
+function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: number }) {
+  const [cursor, setCursor] = createSignal(-1);
+  function go(delta: number) {
+    const body = props.body();
+    if (!body) return;
+    const targets = body.querySelectorAll<HTMLElement>('.doc-block:not([data-change="same"])');
+    if (targets.length === 0) return;
+    const next = (cursor() + delta + targets.length) % targets.length;
+    setCursor(next);
+    targets[next].scrollIntoView({ block: 'center', behavior: 'smooth' });
+  }
+  return (
+    <span class="docws-nav">
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(-1)}
+        title="Previous change"
+      >
+        ‹
+      </button>
+      <span>
+        {props.count} changed block{props.count === 1 ? '' : 's'}
+      </span>
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(1)}
+        title="Next change"
+      >
+        ›
+      </button>
+    </span>
+  );
+}
+
+function Rationale(props: { candidate: DocumentCandidateRecord }) {
+  const r = () => props.candidate.rationale;
+  const list = (label: string, items: string[] | undefined, cls?: string) => (
+    <Show when={items && items.length > 0}>
+      <div class="docws-rationale-label">{label}</div>
+      <ul class={cls}>
+        <For each={items}>{(item) => <li>{item}</li>}</For>
+      </ul>
+    </Show>
+  );
+  return (
+    <div class="docws-rationale">
+      <div class="docws-rationale-summary">{r()?.summary ?? 'No rationale returned.'}</div>
+      {list('Changes', r()?.changes)}
+      {list('Assumptions', r()?.assumptions)}
+      {list('Open questions', r()?.questions)}
+      {list('Warnings', r()?.warnings, 'docws-warning')}
+      <Show when={props.candidate.outOfScopeFiles?.length}>
+        <div class="docws-warning">
+          Touched files outside the document (reverted):{' '}
+          {props.candidate.outOfScopeFiles?.join(', ')}
+        </div>
+      </Show>
+      <Show when={props.candidate.outOfScopeHunks}>
+        <div class="docws-warning">
+          {props.candidate.outOfScopeHunks} change{props.candidate.outOfScopeHunks === 1 ? '' : 's'}{' '}
+          outside the selected passage.
+        </div>
+      </Show>
+      <Show when={props.candidate.error}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+    </div>
+  );
+}
+
+/** Narrower than this a column reads as a sliver, whatever the reader drags. */
+const MIN_COLUMN_WIDTH = 260;
+
+/* Keyed by position rather than by candidate: a column width is a layout
+   preference, so it holds as the reader moves from one run to the next. */
+const columnKey = (column: string) => `docws-compare:${column}`;
+
+/**
+ * The seam on a column's right edge: drag it to size the column it follows,
+ * double-click to hand the width back to the layout.
+ *
+ * `ResizablePanel` is the app's splitter, but it puts `overflow: hidden` on the
+ * row and on every cell. This row scrolls sideways instead, so a column made
+ * wide pushes its neighbours along rather than clipping them out of reach.
+ */
+function ColumnSeam(props: {
+  /** True while this seam is the one under the pointer. */
+  dragging: boolean;
+  /** The width under the pointer, reported for as long as the drag lasts. */
+  onDrag: (width: number) => void;
+  onRelease: () => void;
+  onReset: () => void;
+}) {
+  let seam: HTMLDivElement | undefined;
+  /** The listeners of the drag in flight, so an unmount can take them down too. */
+  let live: { move: (e: MouseEvent) => void; up: () => void } | undefined;
+
+  function detach() {
+    if (!live) return;
+    window.removeEventListener('mousemove', live.move);
+    window.removeEventListener('mouseup', live.up);
+    live = undefined;
+  }
+  onCleanup(detach);
+
+  function begin(e: MouseEvent) {
+    if (e.button !== 0) return;
+    e.preventDefault();
+    // The column this seam sizes is the one it sits behind in the row.
+    const column = seam?.previousElementSibling;
+    if (!column?.classList.contains('docws-column')) return;
+    const startX = e.clientX;
+    const startWidth = column.getBoundingClientRect().width;
+    const move = (ev: MouseEvent) =>
+      props.onDrag(Math.max(MIN_COLUMN_WIDTH, startWidth + ev.clientX - startX));
+    const up = () => {
+      detach();
+      props.onRelease();
+    };
+    live = { move, up };
+    window.addEventListener('mousemove', move);
+    window.addEventListener('mouseup', up);
+  }
+
+  return (
+    <div
+      ref={seam}
+      class="resize-handle resize-handle-h"
+      classList={{ dragging: props.dragging }}
+      title="Drag to resize · double-click to reset"
+      onMouseDown={begin}
+      onDblClick={() => props.onReset()}
+    />
+  );
+}
+
+function CandidateColumn(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+  baseBlocks: DocumentBlock[];
+  baseSource: string;
+  /** False for HTML pages, whose blocks the composer cannot splice back together. */
+  partialCapable: boolean;
+  revealAgents: boolean;
+  showSource: boolean;
+  /** Reports which base blocks this candidate changed or removed. */
+  onBaseChanges: (candidateId: string, changes: BlockChange[]) => void;
+  /** Width the reader dragged this column to, if any. */
+  style?: JSX.CSSProperties;
+}) {
+  let bodyRef: HTMLDivElement | undefined;
+  const [content] = createResource(
+    () =>
+      props.candidate.commitSha
+        ? { sha: props.candidate.commitSha, path: props.run.documentPath }
+        : null,
+    ({ sha, path }) => fetchDocumentAt(sha, path),
+  );
+  const rendered = createRenderedBlocks(() => content() ?? null);
+  const blockDiff = createMemo(() => diffBlocks(props.baseBlocks, rendered.blocks()));
+  const changes = () => blockDiff().candidate;
+  const changedCount = () => changes().filter((c) => c !== 'same').length;
+  createEffect(() => {
+    if (rendered.blocks().length > 0) props.onBaseChanges(props.candidate.id, blockDiff().base);
+  });
+  // Open on the first changed block: the decision is there, not at the title.
+  createEffect(
+    on(changedCount, (count) => {
+      if (count === 0) return;
+      requestAnimationFrame(() => revealFirst(bodyRef, '.doc-block:not([data-change="same"])'));
+    }),
+  );
+  const [diff] = createResource(
+    () =>
+      props.showSource && props.candidate.commitSha
+        ? {
+            projectRoot: projectRoot(),
+            from: props.run.baseSha,
+            to: props.candidate.commitSha,
+            documentPath: props.run.documentPath,
+          }
+        : null,
+    (args) => invoke<string>(IPC.GetDocumentDiff, args),
+  );
+  // Partial acceptance: every change is kept until the reader declines it, so
+  // the default is exactly the whole-candidate acceptance it replaces.
+  const hunks = createMemo(() => blockHunks(blockDiff()));
+  const leads = createMemo(() => hunkLeadBlocks(hunks(), rendered.blocks().length));
+  const partial = createMemo(
+    () => props.partialCapable && !rendered.page() && hunks().length > 1 && !!leads(),
+  );
+  const [declined, setDeclined] = createSignal<ReadonlySet<number>>(new Set<number>());
+  // Reset on the shape of the changes, not on the memo's identity: the run
+  // object is replaced whenever anything about it is saved — writing a note on
+  // this very candidate does it — and resetting then would silently re-accept
+  // passages the reader had declined.
+  const hunkShape = createMemo(() =>
+    hunks()
+      .map((h) => `${h.baseStart}-${h.baseEnd}-${h.candStart}-${h.candEnd}`)
+      .join('|'),
+  );
+  createEffect(on(hunkShape, () => setDeclined(new Set<number>())));
+  const keptCount = () => hunks().length - declined().size;
+  function toggleHunk(id: number) {
+    if (accepting()) return;
+    setDeclined((prev) => {
+      const next = new Set(prev);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+  }
+  // Blocks of a declined change are still shown — you are choosing against
+  // them, so they have to stay readable — but marked as not landing.
+  const declinedBlocks = createMemo(() => {
+    const out = new Set<number>();
+    if (!partial()) return out;
+    for (const hunk of hunks()) {
+      if (!declined().has(hunk.id)) continue;
+      for (let i = hunk.candStart; i < hunk.candEnd; i++) out.add(i);
+    }
+    return out;
+  });
+  const hunkLeads = (index: number) => {
+    if (!partial()) return [];
+    return (leads()?.get(index) ?? []).map((hunk) => ({
+      id: hunk.id,
+      accepted: !declined().has(hunk.id),
+      label: hunkLabel(hunk, props.baseBlocks),
+    }));
+  };
+
+  const [note, setNote] = createSignal(untrack(() => props.candidate.note ?? ''));
+  const [accepting, setAccepting] = createSignal(false);
+  const canAccept = () =>
+    !!props.candidate.commitSha &&
+    props.run.status === 'finished' &&
+    !accepting() &&
+    (!partial() || keptCount() > 0) &&
+    (declined().size === 0 || (!composed.loading && typeof composed() === 'string'));
+  const title = () =>
+    props.revealAgents
+      ? [
+          props.candidate.agentName,
+          modelLabel(props.candidate),
+          props.candidate.isMain ? 'main session' : '',
+        ]
+          .filter(Boolean)
+          .join(' · ')
+      : `Candidate ${props.candidate.label}`;
+
+  /**
+   * Declining nothing is the whole candidate, which git merges as before.
+   * Anything else is composed here and sent as content: the base with the kept
+   * changes spliced in. A composition that cannot be verified falls back to
+   * refusing rather than writing a document nobody chose.
+   */
+  const [composed] = createResource(
+    () => {
+      const source = content();
+      if (!partial() || declined().size === 0 || typeof source !== 'string') return null;
+      return {
+        baseSource: props.baseSource,
+        baseBlocks: props.baseBlocks,
+        candidateSource: source,
+        candidateBlocks: rendered.blocks(),
+        hunks: hunks(),
+        accepted: new Set(
+          hunks()
+            .filter((h) => !declined().has(h.id))
+            .map((h) => h.id),
+        ),
+      };
+    },
+    (args) => composeVerifiedDocument(args).catch(() => null),
+  );
+  const [showPreview, setShowPreview] = createSignal(false);
+  const previewing = () => showPreview() && declined().size > 0;
+  const [preview] = createResource(
+    () => (previewing() && !composed.loading ? composed() : null),
+    (source) => renderDocument(source).catch(() => null),
+  );
+
+  async function accept() {
+    if (!canAccept()) return;
+    setAccepting(true);
+    try {
+      if (declined().size === 0) {
+        await acceptDocumentCandidate(props.run.id, props.candidate.id);
+        return;
+      }
+      const result = composed();
+      if (typeof result !== 'string') {
+        showNotification(
+          'The changes you picked cannot be combined cleanly. Accept the candidate whole, or refine it.',
+        );
+        return;
+      }
+      await acceptDocumentCandidate(props.run.id, props.candidate.id, {
+        content: result,
+        accepted: keptCount(),
+        total: hunks().length,
+      });
+    } finally {
+      setAccepting(false);
+    }
+  }
+
+  return (
+    <section class="docws-column" style={props.style} aria-label={title()}>
+      <div class="docws-column-head">
+        <div class="docws-column-title">
+          <span class="docws-candidate-label">{props.candidate.label}</span>
+          <span>{title()}</span>
+          <span style={{ 'margin-left': 'auto' }}>
+            <Show when={!previewing()}>
+              <ChangeNav body={() => bodyRef} count={changedCount()} />
+            </Show>
+          </span>
+        </div>
+        <Rationale candidate={props.candidate} />
+        <textarea
+          class="docws-note"
+          placeholder="Your note on this candidate…"
+          value={note()}
+          onInput={(e) => setNote(e.currentTarget.value)}
+          onBlur={() => {
+            if (note() !== (props.candidate.note ?? ''))
+              void setDocumentCandidateNote(props.run.id, props.candidate.id, note());
+          }}
+        />
+        <div class="docws-run-actions">
+          <Show when={partial() && declined().size > 0}>
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm"
+              aria-pressed={previewing()}
+              onClick={() => setShowPreview((value) => !value)}
+            >
+              {previewing() ? 'Back to changes' : 'Preview result'}
+            </button>
+          </Show>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            disabled={!canAccept()}
+            title={
+              props.run.status === 'stale'
+                ? 'The document moved since this run and the proposal no longer applies. Re-run it.'
+                : declined().size === 0
+                  ? 'Accept this candidate as one commit on the canonical branch'
+                  : 'Accept the changes you kept as one commit on the canonical branch'
+            }
+            onClick={() => void accept()}
+          >
+            {accepting()
+              ? 'Accepting…'
+              : declined().size === 0
+                ? 'Accept this candidate'
+                : `Accept ${keptCount()} of ${hunks().length} changes`}
+          </button>
+        </div>
+        <Show when={declined().size > 0 && !composed.loading && composed() === null}>
+          <div class="docws-error" role="alert">
+            These changes cannot be combined cleanly. Adjust your choices or refine the candidate.
+          </div>
+        </Show>
+        <CandidateRefinement run={props.run} candidate={props.candidate} />
+      </div>
+      <div class="docws-column-body" ref={bodyRef}>
+        <Show
+          when={previewing()}
+          fallback={
+            <Show
+              when={props.candidate.commitSha}
+              fallback={<div class="docws-empty">No change proposed.</div>}
+            >
+              <Show
+                when={!props.showSource}
+                fallback={
+                  <Show
+                    when={!diff.loading}
+                    fallback={<div class="docws-empty">Loading diff…</div>}
+                  >
+                    <SourceDiff raw={diff() ?? ''} />
+                  </Show>
+                }
+              >
+                <Show
+                  when={!rendered.rendering() || rendered.blocks().length > 0}
+                  fallback={<div class="docws-empty">Rendering…</div>}
+                >
+                  <DocumentViewer
+                    blocks={rendered.blocks()}
+                    changes={changes()}
+                    hunkLeads={hunkLeads}
+                    onToggleHunk={toggleHunk}
+                    declined={(i) => declinedBlocks().has(i)}
+                    renderKey={`cand-${props.candidate.id}`}
+                    page={rendered.page()}
+                  />
+                </Show>
+              </Show>
+            </Show>
+          }
+        >
+          <section aria-label="Result preview" aria-busy={composed.loading || preview.loading}>
+            <div class="docws-rationale">
+              Result with {keptCount()} of {hunks().length} changes. Unselected passages keep their
+              base text. Acceptance requires the document to be unchanged since this run.
+            </div>
+            <Show
+              when={!composed.loading && !preview.loading}
+              fallback={<div class="docws-empty">Preparing preview…</div>}
+            >
+              <Show
+                when={typeof composed() === 'string' ? preview() : null}
+                fallback={
+                  <div class="docws-empty">
+                    Preview unavailable. Return to changes to adjust your choices.
+                  </div>
+                }
+              >
+                {(result) => (
+                  <DocumentViewer
+                    blocks={result().blocks}
+                    page={result().page}
+                    renderKey={`result-${props.candidate.id}`}
+                  />
+                )}
+              </Show>
+            </Show>
+          </section>
+        </Show>
+      </div>
+    </section>
+  );
+}
+
+/** Base on the left, candidates to the right, each opening with its rationale. */
+export function CompareView(props: { run: DocumentRunRecord }) {
+  let baseBodyRef: HTMLDivElement | undefined;
+  const [revealAgents, setRevealAgents] = createSignal(false);
+  const [showSource, setShowSource] = createSignal(false);
+  const [baseContent] = createResource(
+    () => ({ sha: props.run.baseSha, path: props.run.documentPath }),
+    ({ sha, path }) => fetchDocumentAt(sha, path),
+  );
+  const base = createRenderedBlocks(() => baseContent() ?? null);
+  const scope = createMemo(() => scopeRange(base.blocks(), props.run));
+  const candidates = createMemo(() => props.run.candidates.filter((c) => c.commitSha));
+  // Base blocks touched by any candidate, so a deleted paragraph is visible somewhere.
+  const [baseChanges, setBaseChanges] = createSignal<Record<string, BlockChange[]>>({});
+  // The width under the pointer while a seam is dragged. It is kept out of the
+  // store on purpose: panel sizes are part of the persisted snapshot, so
+  // writing one per mouse event would serialise the whole app state per frame.
+  const [drag, setDrag] = createSignal<{ column: string; width: number } | null>(null);
+
+  /** A column the reader sized keeps that width over the layout's. */
+  function columnStyle(column: string): JSX.CSSProperties | undefined {
+    const live = drag();
+    const width = live?.column === column ? live.width : getPanelUserSize(columnKey(column));
+    if (!width) return undefined;
+    return { flex: `0 0 ${width}px`, 'min-width': `${width}px`, 'max-width': `${width}px` };
+  }
+
+  /** The seam that sizes `column`, drawn on that column's right edge. */
+  const seam = (column: string) => (
+    <ColumnSeam
+      dragging={drag()?.column === column}
+      onDrag={(width) => setDrag({ column, width })}
+      onRelease={() => {
+        const live = drag();
+        if (live) setPanelUserSize(columnKey(live.column), live.width);
+        setDrag(null);
+      }}
+      onReset={() => deletePanelUserSize([columnKey(column)])}
+    />
+  );
+  const baseMarks = createMemo<BlockChange[]>(() => {
+    const perCandidate = Object.values(baseChanges());
+    return base.blocks().map((_, i) => {
+      const marks = perCandidate.map((m) => m[i]).filter((m): m is BlockChange => !!m);
+      if (marks.includes('removed')) return 'removed';
+      if (marks.includes('changed')) return 'changed';
+      return 'same';
+    });
+  });
+  // The base opens on the passage the run was scoped to, level with the candidates.
+  createEffect(
+    on([scope, () => base.blocks().length], () => {
+      requestAnimationFrame(() =>
+        revealFirst(baseBodyRef, '.doc-block.is-scope, .doc-block:not([data-change="same"])'),
+      );
+    }),
+  );
+  const scopeText = () => {
+    const s = props.run.scope;
+    if (s.wholeDocument) return 'whole document';
+    return `L${s.startLine}–${s.endLine}${s.heading ? ` · ${s.heading}` : ''}`;
+  };
+
+  return (
+    <div class="docws-compare">
+      <div class="docws-compare-bar">
+        <span class="docws-instruction" title={props.run.instruction}>
+          “{props.run.instruction}”
+        </span>
+        <span>{scopeText()}</span>
+        <span>base {props.run.baseSha.slice(0, 7)}</span>
+        <Show when={props.run.status === 'stale'}>
+          <span class="docws-warning">stale: the document moved since this run</span>
+        </Show>
+        <span style={{ 'margin-left': 'auto' }} />
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={revealAgents()}
+            onChange={(e) => setRevealAgents(e.currentTarget.checked)}
+          />
+          Show agents
+        </label>
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={showSource()}
+            onChange={(e) => setShowSource(e.currentTarget.checked)}
+          />
+          Source diff
+        </label>
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm docws-btn-danger"
+          onClick={() => void rejectDocumentRun(props.run.id)}
+        >
+          Reject all
+        </button>
+      </div>
+      <div class="docws-columns">
+        <section
+          class="docws-column docws-column-base"
+          style={columnStyle('base')}
+          aria-label="Base version"
+        >
+          <div class="docws-column-head">
+            <div class="docws-column-title">Base · {props.run.baseSha.slice(0, 7)}</div>
+            <div class="docws-rationale">
+              <div>
+                The document as every candidate saw it. The scoped passage is outlined; blocks a
+                candidate rewrote or removed are marked.
+              </div>
+            </div>
+          </div>
+          <div class="docws-column-body" ref={baseBodyRef}>
+            <DocumentViewer
+              blocks={base.blocks()}
+              scope={scope()}
+              changes={baseMarks()}
+              renderKey="base"
+              page={base.page()}
+            />
+          </div>
+        </section>
+        {seam('base')}
+        <Index each={candidates()}>
+          {(candidate, i) => (
+            <>
+              <CandidateColumn
+                run={props.run}
+                candidate={candidate()}
+                baseBlocks={base.blocks()}
+                baseSource={baseContent() ?? ''}
+                partialCapable={!base.page()}
+                revealAgents={revealAgents()}
+                showSource={showSource()}
+                onBaseChanges={(id, marks) => setBaseChanges((prev) => ({ ...prev, [id]: marks }))}
+                style={columnStyle(`candidate-${i}`)}
+              />
+              {seam(`candidate-${i}`)}
+            </>
+          )}
+        </Index>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/DocumentIcon.tsx b/src/documents/DocumentIcon.tsx
new file mode 100644
index 000000000..1c4c2afb4
--- /dev/null
+++ b/src/documents/DocumentIcon.tsx
@@ -0,0 +1,19 @@
+/** The document-project glyph: shared by the sidebar row and the workspace header. */
+export function DocumentIcon(props: { size?: number }) {
+  return (
+    <svg
+      width={props.size ?? 18}
+      height={props.size ?? 18}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 1.5h5l3 3v10H4z" />
+      <path d="M9 1.5v3h3M6 8h4M6 10.5h4" />
+    </svg>
+  );
+}
diff --git a/src/documents/DocumentViewer.client.test.tsx b/src/documents/DocumentViewer.client.test.tsx
new file mode 100644
index 000000000..10eacc542
--- /dev/null
+++ b/src/documents/DocumentViewer.client.test.tsx
@@ -0,0 +1,313 @@
+import { createSignal } from 'solid-js';
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { DocumentViewer, releasesSelection } from './DocumentViewer';
+import type { DocumentBlock } from './markdown-blocks';
+
+const { invoke } = vi.hoisted(() => ({ invoke: vi.fn(() => Promise.resolve()) }));
+vi.mock('../lib/ipc', () => ({ invoke }));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  vi.clearAllMocks();
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'paragraph',
+    raw: 'See [the guide](../guide/setup.md#install), [web](https://example.com) and [below](#end).\n',
+    html: '<p>See <a href="../guide/setup.md#install">the guide</a>, <a href="https://example.com">web</a> and <a href="#end">below</a>.</p>',
+    startLine: 1,
+    endLine: 1,
+  },
+  {
+    index: 1,
+    type: 'heading',
+    raw: '## End\n',
+    html: '<h2>End</h2>',
+    startLine: 3,
+    endLine: 3,
+    headingLevel: 2,
+    headingText: 'End',
+  },
+];
+
+function mount(onNavigate: (path: string, anchor?: string) => void) {
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(
+      () => (
+        <DocumentViewer
+          blocks={blocks}
+          renderKey="t"
+          documentPath="docs/notes/readme.md"
+          onNavigate={onNavigate}
+        />
+      ),
+      host,
+    ),
+  );
+  return host;
+}
+
+function click(link: Element | null): boolean {
+  const event = new MouseEvent('click', { bubbles: true, cancelable: true });
+  link?.dispatchEvent(event);
+  return event.defaultPrevented;
+}
+
+describe('DocumentViewer links', () => {
+  it('opens another file of the project inside the workspace', () => {
+    const onNavigate = vi.fn();
+    const host = mount(onNavigate);
+
+    const prevented = click(host.querySelector('a[href="../guide/setup.md#install"]'));
+
+    expect(prevented).toBe(true);
+    expect(onNavigate).toHaveBeenCalledWith('docs/guide/setup.md', 'install');
+  });
+
+  it('hands web links to the browser instead of the app window', () => {
+    const host = mount(vi.fn());
+
+    const prevented = click(host.querySelector('a[href="https://example.com"]'));
+
+    expect(prevented).toBe(true);
+    expect(invoke).toHaveBeenCalledWith('__shell_open_external', { url: 'https://example.com' });
+  });
+
+  it('scrolls to a heading for an in-page anchor', () => {
+    const onNavigate = vi.fn();
+    const host = mount(onNavigate);
+    const heading = host.querySelector<HTMLElement>('h2');
+    if (heading) heading.scrollIntoView = vi.fn();
+
+    click(host.querySelector('a[href="#end"]'));
+
+    expect(heading?.scrollIntoView).toHaveBeenCalled();
+    expect(onNavigate).not.toHaveBeenCalled();
+    expect(invoke).not.toHaveBeenCalled();
+  });
+});
+
+describe('picking a passage', () => {
+  function mountSelectable(
+    onSelect: (s: unknown) => void,
+    selection?: { start: number; end: number },
+  ) {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => (
+          <DocumentViewer
+            blocks={blocks}
+            renderKey="t"
+            selectable
+            selection={selection}
+            onSelect={onSelect}
+          />
+        ),
+        host,
+      ),
+    );
+    return host;
+  }
+
+  function mouseUp(el: Element) {
+    el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+  }
+
+  it('keeps the passage picked when the block already picked is clicked again', () => {
+    const onSelect = vi.fn();
+    // The pane owns the selection, so a block already picked comes in as a prop.
+    const host = mountSelectable(onSelect, { start: 1, end: 1 });
+
+    mouseUp(host.querySelector('[data-block-index="1"]') as HTMLElement);
+
+    expect(onSelect).toHaveBeenCalledTimes(1);
+    expect(onSelect).toHaveBeenCalledWith(expect.objectContaining({ startBlock: 1, endBlock: 1 }));
+  });
+
+  it('moves the passage to another block', () => {
+    const onSelect = vi.fn();
+    const host = mountSelectable(onSelect);
+
+    mouseUp(host.querySelector('[data-block-index="1"]') as HTMLElement);
+    mouseUp(host.querySelector('[data-block-index="0"]') as HTMLElement);
+
+    expect(onSelect).toHaveBeenLastCalledWith(expect.objectContaining({ startBlock: 0 }));
+  });
+});
+
+describe('releasesSelection', () => {
+  it('lets the passage go for a click on the backdrop', () => {
+    const backdrop = document.createElement('div');
+    document.body.append(backdrop);
+
+    expect(releasesSelection(backdrop)).toBe(true);
+  });
+
+  it('holds on for a click on a block or on one of its controls', () => {
+    const host = document.createElement('div');
+    host.innerHTML =
+      '<div data-block-index="0"><p>Prose</p><button type="button">Task</button></div>';
+    document.body.append(host);
+
+    expect(releasesSelection(host.querySelector('p'))).toBe(false);
+    expect(releasesSelection(host.querySelector('button'))).toBe(false);
+    expect(releasesSelection(host.querySelector('[data-block-index]'))).toBe(false);
+  });
+
+  it('holds on when a drag merely ended out in the margin', () => {
+    const backdrop = document.createElement('div');
+    backdrop.textContent = 'margin';
+    document.body.append(backdrop);
+    const range = document.createRange();
+    range.selectNodeContents(backdrop);
+    const native = window.getSelection();
+    native?.removeAllRanges();
+    native?.addRange(range);
+
+    expect(releasesSelection(backdrop)).toBe(false);
+
+    native?.removeAllRanges();
+  });
+
+  it('holds on when there is no element under the pointer', () => {
+    expect(releasesSelection(null)).toBe(false);
+  });
+});
+
+describe('choosing which changes land', () => {
+  function mountWithHunks(args: {
+    onToggleHunk?: (id: number) => void;
+    declined?: (index: number) => boolean;
+    accepted?: () => boolean;
+    stacked?: boolean;
+    onSelect?: (s: unknown) => void;
+  }) {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => (
+          <DocumentViewer
+            blocks={blocks}
+            renderKey="t"
+            selectable
+            onSelect={args.onSelect}
+            changes={['changed', 'same']}
+            hunkLeads={(i) =>
+              i === 0
+                ? [
+                    {
+                      id: 7,
+                      accepted: args.accepted ? args.accepted() : true,
+                      label: 'Include this rewrite',
+                    },
+                    ...(args.stacked
+                      ? [{ id: 8, accepted: true, label: 'Include this removal: “Gone.”' }]
+                      : []),
+                  ]
+                : []
+            }
+            onToggleHunk={args.onToggleHunk}
+            declined={args.declined}
+          />
+        ),
+        host,
+      ),
+    );
+    return host;
+  }
+
+  it('offers one toggle on the block that leads the change', () => {
+    const host = mountWithHunks({});
+
+    const toggles = host.querySelectorAll<HTMLInputElement>('.docws-hunk-toggle input');
+    expect(toggles).toHaveLength(1);
+    expect(toggles[0].checked).toBe(true);
+    expect(toggles[0].getAttribute('aria-label')).toBe('Include this rewrite');
+    expect(toggles[0].closest('[data-block-index]')?.getAttribute('data-block-index')).toBe('0');
+  });
+
+  // The gutter costs the prose 28px; a column showing no toggles keeps it.
+  it('opens the toggle gutter only for a column that has toggles', () => {
+    expect(mountWithHunks({}).querySelector('.docws-hunk-gutter')).not.toBeNull();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentViewer blocks={blocks} renderKey="t" />, host));
+    expect(host.querySelector('.docws-hunk-gutter')).toBeNull();
+  });
+
+  // Two removals can meet on one block; each still needs its own toggle.
+  it('stacks every change that lands on the same block', () => {
+    const host = mountWithHunks({ stacked: true });
+
+    const labels = [...host.querySelectorAll('.docws-hunk-toggle input')].map((el) =>
+      el.getAttribute('aria-label'),
+    );
+    expect(labels).toEqual(['Include this rewrite', 'Include this removal: “Gone.”']);
+  });
+
+  it('reports the change the reader declined', () => {
+    const onToggleHunk = vi.fn();
+    const host = mountWithHunks({ onToggleHunk });
+
+    const toggle = host.querySelector<HTMLInputElement>('.docws-hunk-toggle input');
+    if (!toggle) throw new Error('no toggle rendered');
+    toggle.checked = false;
+    toggle.dispatchEvent(new Event('change', { bubbles: true }));
+
+    expect(onToggleHunk).toHaveBeenCalledWith(7);
+  });
+
+  it('marks a declined block as not landing, and leaves the others alone', () => {
+    const host = mountWithHunks({ accepted: () => false, declined: (i) => i === 0 });
+
+    expect(host.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.checked).toBe(false);
+    expect(host.querySelector('[data-block-index="0"]')?.classList.contains('is-declined')).toBe(
+      true,
+    );
+    expect(host.querySelector('[data-block-index="1"]')?.classList.contains('is-declined')).toBe(
+      false,
+    );
+  });
+
+  // The compare view drives these from a signal; nothing else pins that the
+  // checkbox and the dimming follow it rather than freezing at first render.
+  it("follows the reader's choice without re-creating the checkbox", () => {
+    const [kept, setKept] = createSignal(true);
+    const host = mountWithHunks({ accepted: kept, declined: () => !kept() });
+    const before = host.querySelector('.docws-hunk-toggle input');
+
+    setKept(false);
+
+    expect(host.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.checked).toBe(false);
+    expect(host.querySelector('[data-block-index="0"]')?.classList.contains('is-declined')).toBe(
+      true,
+    );
+    // Same element: a recreated checkbox would drop keyboard focus on toggle.
+    expect(host.querySelector('.docws-hunk-toggle input')).toBe(before);
+
+    setKept(true);
+    expect(host.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.checked).toBe(true);
+  });
+
+  it('does not pick the passage when the toggle is clicked', () => {
+    const onSelect = vi.fn();
+    const host = mountWithHunks({ onSelect });
+
+    host
+      .querySelector('.docws-hunk-toggle input')
+      ?.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
new file mode 100644
index 000000000..18457d76c
--- /dev/null
+++ b/src/documents/DocumentViewer.tsx
@@ -0,0 +1,298 @@
+import { For, Index, Show, createEffect, createMemo, on, type JSX } from 'solid-js';
+import { scopePageCss } from './html-blocks';
+import type { BlockChange, DocumentBlock } from './markdown-blocks';
+import { blockRangeText, nearestHeading, sectionRange } from './markdown-blocks';
+import { PageBlocks, type PageRender } from './PageBlocks';
+import type { DocumentSelection } from './store';
+import { renderMermaidIn } from '../lib/mermaid';
+import { findAnchorTarget, resolveDocumentLink } from './links';
+import { BlockActions, type BlockActionKind } from './BlockActions';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+
+export interface BlockRange {
+  start: number;
+  end: number;
+}
+
+interface DocumentViewerProps {
+  blocks: DocumentBlock[];
+  /** Renders selection affordances and reports selections. */
+  selectable?: boolean;
+  selection?: BlockRange | null;
+  onSelect?: (selection: DocumentSelection | null) => void;
+  /** Per-block change marks for the compare view. */
+  changes?: BlockChange[];
+  /** Blocks inside the run's scope (compare view context). */
+  scope?: BlockRange | null;
+  /**
+   * Compare view: the changes this block leads, each shown as an include
+   * toggle in its margin. Declining one keeps the base's version of that
+   * passage. A block carries more than one only when two removals meet on it.
+   */
+  hunkLeads?: (index: number) => readonly { id: number; accepted: boolean; label: string }[];
+  onToggleHunk?: (id: number) => void;
+  /** True for blocks of a declined change: shown, but not what will land. */
+  declined?: (index: number) => boolean;
+  /** Unique key for mermaid ids. */
+  renderKey: string;
+  /** Rendered inside the block with this index: its annotation marker. */
+  blockMarker?: (index: number) => JSX.Element;
+  /** Which blocks have a marker; a page anchors one inside those alone. */
+  hasMarker?: (index: number) => boolean;
+  /**
+   * A whole HTML page's markup and stylesheet. When set, the page renders as
+   * itself on a light canvas, with the blocks marked inside it, instead of as
+   * the app's markdown theme.
+   */
+  page?: PageRender | null;
+  /** Repo-relative path of the rendered document; relative links resolve against it. */
+  documentPath?: string;
+  /** A link to another file of the project was clicked. */
+  onNavigate?: (path: string, anchor?: string) => void;
+  /** A block's hover toolbar was used: pick the block and open the composer on `action`. */
+  onAction?: (action: BlockActionKind, index: number) => void;
+}
+
+export function selectionFromRange(
+  blocks: readonly DocumentBlock[],
+  range: BlockRange,
+): DocumentSelection {
+  const start = Math.max(0, Math.min(range.start, range.end));
+  const end = Math.min(blocks.length - 1, Math.max(range.start, range.end));
+  return {
+    startBlock: start,
+    endBlock: end,
+    startLine: blocks[start].startLine,
+    endLine: blocks[end].endLine,
+    quote: blockRangeText(blocks, start, end),
+    heading: nearestHeading(blocks, start),
+    wholeDocument: false,
+  };
+}
+
+/** The document's own controls: a click on one is never a click on the prose. */
+const CONTROLS = 'a, button, input, textarea, .docws-marker';
+
+/**
+ * True for a mouse-up on the backdrop: the margins and the space below the
+ * prose, where there is no block and no control. Clicking there lets the
+ * picked passage go, the way clicking beside a dialog dismisses it. A drag
+ * that merely ended out there keeps its range.
+ */
+export function releasesSelection(target: EventTarget | null): boolean {
+  const el = target instanceof Element ? target : null;
+  if (!el || el.closest(`[data-block-index], ${CONTROLS}`)) return false;
+  const native = window.getSelection();
+  return !native || native.isCollapsed;
+}
+
+function blockIndexOf(node: Node | null, container: HTMLElement): number | null {
+  let el: HTMLElement | null = node instanceof HTMLElement ? node : (node?.parentElement ?? null);
+  while (el && el !== container) {
+    const raw = el.dataset.blockIndex;
+    if (raw !== undefined) return Number(raw);
+    el = el.parentElement;
+  }
+  return null;
+}
+
+export function DocumentViewer(props: DocumentViewerProps) {
+  let containerRef: HTMLDivElement | undefined;
+
+  const selected = createMemo(() => {
+    const s = props.selection;
+    if (!s) return null;
+    return { start: Math.min(s.start, s.end), end: Math.max(s.start, s.end) };
+  });
+
+  const isPage = () => !!props.page;
+  const pageKey = () => props.renderKey.replace(/["\\]/g, '');
+  // Every viewer scopes the page's CSS to itself, so two versions of a page
+  // side by side (base and candidate) cannot style each other.
+  // The toggle gutter costs the prose 28px of indent, so it is opened only for
+  // a column that is actually showing toggles — a base column, or a proposal
+  // taken whole, keeps its full width.
+  const hasHunkToggles = createMemo(() => {
+    const leads = props.hunkLeads;
+    if (!leads) return false;
+    return props.blocks.some((_, i) => leads(i).length > 0);
+  });
+
+  const pageCss = createMemo(() =>
+    props.page ? scopePageCss(props.page.stylesheet, `[data-page="${pageKey()}"]`) : '',
+  );
+
+  createEffect(
+    on(
+      () => props.blocks,
+      () => {
+        const key = props.renderKey;
+        queueMicrotask(() => renderMermaidIn(containerRef, key));
+      },
+    ),
+  );
+
+  function emitRange(range: BlockRange | null) {
+    if (!props.onSelect) return;
+    if (!range || props.blocks.length === 0) {
+      props.onSelect(null);
+      return;
+    }
+    props.onSelect(selectionFromRange(props.blocks, range));
+  }
+
+  function handleMouseUp(e: MouseEvent) {
+    if (!props.selectable || !containerRef) return;
+    const target = e.target as HTMLElement | null;
+    if (target?.closest(CONTROLS)) return;
+    const native = window.getSelection();
+    if (native && !native.isCollapsed && native.rangeCount > 0) {
+      const range = native.getRangeAt(0);
+      const start = blockIndexOf(range.startContainer, containerRef);
+      const end = blockIndexOf(range.endContainer, containerRef);
+      if (start === null && end === null) return;
+      // A drag across several blocks scopes them; a selection inside one block
+      // stays a plain text selection so copying keeps working. Click the block
+      // to scope it. The native range is left alone for the same reason.
+      const from = start ?? end ?? 0;
+      const to = end ?? start ?? 0;
+      if (from !== to) emitRange({ start: from, end: to });
+      return;
+    }
+    const index = blockIndexOf(target, containerRef);
+    // Clicking the picked block again keeps it: a second click is how one
+    // reaches for the passage already being worked on, not a way to drop it.
+    // The backdrop, Esc and the composer's own × let it go.
+    if (index !== null) emitRange({ start: index, end: index });
+  }
+
+  function selectSection(index: number, e: MouseEvent) {
+    e.stopPropagation();
+    const [start, end] = sectionRange(props.blocks, index);
+    emitRange({ start, end });
+  }
+
+  // Links never navigate the app window: web links go to the browser, anchors
+  // scroll, and other files of the project open in the workspace.
+  function handleClick(e: MouseEvent) {
+    const anchorEl = (e.target as HTMLElement | null)?.closest<HTMLAnchorElement>('a[href]');
+    if (!anchorEl || !containerRef?.contains(anchorEl)) return;
+    e.preventDefault();
+    const link = resolveDocumentLink(anchorEl.getAttribute('href') ?? '', props.documentPath ?? '');
+    if (!link) return;
+    if (link.kind === 'external') {
+      void invoke(IPC.ShellOpenExternal, { url: link.url });
+    } else if (link.kind === 'anchor') {
+      findAnchorTarget(containerRef, link.id)?.scrollIntoView({ block: 'start' });
+    } else {
+      props.onNavigate?.(link.path, link.anchor);
+    }
+  }
+
+  return (
+    <div
+      ref={(el) => {
+        containerRef = el;
+      }}
+      class="docws-content"
+      classList={{
+        'plan-markdown': !isPage(),
+        'plan-markdown-dialog': !isPage(),
+        'docws-page': isPage(),
+        'docws-selectable': props.selectable === true,
+        'docws-hunk-gutter': hasHunkToggles(),
+      }}
+      onMouseUp={handleMouseUp}
+      onClick={handleClick}
+    >
+      <Show when={props.page}>
+        {(page) => (
+          <>
+            <style>{pageCss()}</style>
+            <PageBlocks
+              html={page().html}
+              blocks={props.blocks}
+              pageKey={pageKey()}
+              selectable={props.selectable}
+              selected={selected()}
+              changes={props.changes}
+              scope={props.scope}
+              blockMarker={props.blockMarker}
+              hasMarker={props.hasMarker}
+              onSelectSection={selectSection}
+              onAction={props.onAction}
+            />
+          </>
+        )}
+      </Show>
+      <For each={isPage() ? [] : props.blocks}>
+        {(block, i) => {
+          const change = () => props.changes?.[i()] ?? 'same';
+          const isSelected = () => {
+            const s = selected();
+            return !!s && i() >= s.start && i() <= s.end;
+          };
+          const inScope = () => {
+            const s = props.scope;
+            return !!s && i() >= s.start && i() <= s.end;
+          };
+          return (
+            <>
+              <div
+                class="doc-block"
+                data-block-index={i()}
+                data-change={change()}
+                classList={{
+                  'is-declined': props.declined?.(i()) === true,
+                  'is-selected': isSelected(),
+                  'is-changed': change() === 'changed',
+                  'is-added': change() === 'added',
+                  'is-removed': change() === 'removed',
+                  'is-scope': inScope() && change() === 'same',
+                }}
+              >
+                <Show when={props.selectable && block.headingLevel !== undefined}>
+                  <button
+                    type="button"
+                    class="docws-section-btn"
+                    title="Select this section"
+                    aria-label={`Select section ${block.headingText ?? ''}`}
+                    onClick={(e) => selectSection(i(), e)}
+                  >
+                    §
+                  </button>
+                </Show>
+                <Show when={props.hunkLeads?.(i())?.length}>
+                  <span class="docws-hunk-toggles">
+                    <Index each={props.hunkLeads?.(i())}>
+                      {(hunk) => (
+                        <label class="docws-hunk-toggle" title={hunk().label}>
+                          <input
+                            type="checkbox"
+                            checked={hunk().accepted}
+                            aria-label={hunk().label}
+                            onChange={() => props.onToggleHunk?.(hunk().id)}
+                          />
+                        </label>
+                      )}
+                    </Index>
+                  </span>
+                </Show>
+                {/* The marker sits in the block's margin, out of the prose:
+                  it is not part of the passage, so clicking it must not toggle
+                  the selection and the highlight stops at the text. */}
+                {props.blockMarker?.(i())}
+                <Show when={props.selectable && props.onAction}>
+                  <BlockActions onAction={(kind) => props.onAction?.(kind, i())} />
+                </Show>
+                {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
+                <div innerHTML={block.html} />
+              </div>
+            </>
+          );
+        }}
+      </For>
+    </div>
+  );
+}
diff --git a/src/documents/DocumentWorkspaceOverlay.client.test.tsx b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
new file mode 100644
index 000000000..eefe52b58
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
@@ -0,0 +1,184 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+
+const { openInEditor, platform } = vi.hoisted(() => ({
+  openInEditor: vi.fn(() => Promise.resolve()),
+  platform: { isMac: false },
+}));
+
+vi.mock('../lib/shell', () => ({ openInEditor }));
+vi.mock('../lib/platform', () => ({
+  get isMac() {
+    return platform.isMac;
+  },
+  isLinux: false,
+  windowChromeTopInset: 0,
+  mod: 'Ctrl',
+  alt: 'Alt',
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ projects: [], activeDocumentProjectId: null, editorCommand: '' });
+  vi.clearAllMocks();
+});
+
+describe('DocumentWorkspaceOverlay', () => {
+  it('uses the entire title-bar background as the window drag region', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const header = host.querySelector<HTMLElement>('.docws-header');
+
+    expect(header?.hasAttribute('data-tauri-drag-region')).toBe(true);
+  });
+
+  it('moves the title clear of the mac window controls', () => {
+    platform.isMac = true;
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    expect(host.querySelector('.docws-overlay')?.classList.contains('is-mac')).toBe(true);
+    platform.isMac = false;
+  });
+
+  it('keeps the project files on a tab of the resizable right panel', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    expect(host.querySelector('.docws-body .resize-handle-h')).not.toBeNull();
+    const rail = host.querySelector<HTMLElement>('.docws-rail');
+    const tabs = Array.from(rail?.querySelectorAll<HTMLButtonElement>('[role="tab"]') ?? []);
+    expect(tabs.map((t) => t.textContent?.trim())).toEqual(['Agent', 'Runs', 'Files']);
+    expect(rail?.querySelector('[aria-label="Project files"]')).toBeNull();
+
+    tabs[2]?.click();
+
+    expect(rail?.querySelector('[aria-label="Project files"]')).not.toBeNull();
+  });
+
+  it('keeps Document and History as tabs and leaves comparing to a modal', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const tabs = Array.from(host.querySelectorAll<HTMLButtonElement>('.docws-header [role="tab"]'));
+    expect(tabs.map((t) => t.textContent?.trim())).toEqual(['Document', 'History']);
+    expect(document.querySelector('.docws-compare-dialog')).toBeNull();
+  });
+
+  it('opens the document in the configured editor from the title', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'docs/notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+      editorCommand: 'code',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Open docs/notes.md in code"]',
+    );
+    expect(button).not.toBeNull();
+
+    button?.click();
+
+    expect(openInEditor).toHaveBeenCalledWith('code', '/projects/release/docs/notes.md');
+  });
+
+  it('keeps the editor button visible but disabled until an editor is configured', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+      editorCommand: '',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Configure an editor command in Settings to open notes.md"]',
+    );
+
+    expect(button?.disabled).toBe(true);
+  });
+});
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
new file mode 100644
index 000000000..fa154703e
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -0,0 +1,591 @@
+import './documents.css';
+import {
+  For,
+  Show,
+  batch,
+  createEffect,
+  createMemo,
+  createSignal,
+  on,
+  onCleanup,
+  onMount,
+} from 'solid-js';
+import { store } from '../store/core';
+import { getProject } from '../store/projects';
+import {
+  activeDocumentPath,
+  closeDocumentWorkspace,
+  dismissUndo,
+  documentStore,
+  openDocumentFile,
+  refreshDocumentSnapshot,
+  reviewableRuns,
+  setDocumentComposerDraft,
+  setDocumentSelection,
+  setDocumentView,
+  setShowResolvedAnnotations,
+  openDocumentCompare,
+  undoDeleteDocumentAnnotation,
+  type DocumentView,
+} from './store';
+import { resetWorkspaceUi } from './workspace-ui';
+import { findAnchorTarget } from './links';
+import { isMac } from '../lib/platform';
+import { relocateAnchor } from './annotation-anchor';
+import { isHtmlDocument } from './html-document';
+import type { DocumentAnnotation } from './types';
+import type { DocumentBlock } from './markdown-blocks';
+import { AnnotationBubble } from './AnnotationBubble';
+import { AnnotationMarker } from './AnnotationMarker';
+import { EditProjectDialog } from '../components/EditProjectDialog';
+import type { Project } from '../store/types';
+import { CompareDialog } from './CompareDialog';
+import { DocumentViewer, releasesSelection, selectionFromRange } from './DocumentViewer';
+import { HistoryView } from './HistoryView';
+import { RunComposer } from './RunComposer';
+import { RightPanel } from './RightPanel';
+import { CandidateOutputDialog } from './CandidateOutputDialog';
+import { BlockEditor, type BlockEditTarget } from './BlockEditor';
+import { ResizablePanel, type PanelChild } from '../components/ResizablePanel';
+import { createRenderedBlocks } from './use-blocks';
+import { DocumentIcon } from './DocumentIcon';
+import { openInEditor } from '../lib/shell';
+import { errMessage } from '../lib/log';
+import { showNotification } from '../store/notification';
+
+/** Space between the picked passage and the composer, and from the column's edges. */
+const COMPOSER_GAP = 8;
+
+function DocumentPane(props: { project: Project }) {
+  let docRef: HTMLDivElement | undefined;
+  let mainRef: HTMLDivElement | undefined;
+  let scrollRef: HTMLDivElement | undefined;
+  let layerRef: HTMLDivElement | undefined;
+  // Where the composer sits when a passage is picked; null puts it at the foot.
+  const [anchorTop, setAnchorTop] = createSignal<number | null>(null);
+  const blocks = createRenderedBlocks(() => documentStore.snapshot?.content ?? null);
+  const documentPath = () => activeDocumentPath() ?? props.project.documentPath ?? '';
+  const selection = () => documentStore.selection;
+  const [blockEdit, setBlockEdit] = createSignal<BlockEditTarget | null>(null);
+  const editableBlock = () => {
+    const s = selection();
+    if (!s || s.wholeDocument || s.startBlock !== s.endBlock || blocks.rendering()) return null;
+    const block = blocks.blocks()[s.startBlock];
+    return block?.startOffset !== undefined && block.endOffset !== undefined ? block : null;
+  };
+  const range = createMemo(() => {
+    const s = selection();
+    return s && !s.wholeDocument ? { start: s.startBlock, end: s.endBlock } : null;
+  });
+
+  /** Open the source editor on a block; only blocks that map back to the source qualify. */
+  function editBlock(block: DocumentBlock | null) {
+    const source = documentStore.snapshot?.content;
+    // Mid-render the blocks belong to an older read of the file than the source.
+    if (!block || source === undefined || blocks.rendering()) return;
+    if (block.startOffset === undefined || block.endOffset === undefined) return;
+    setBlockEdit({ projectRoot: props.project.path, documentPath: documentPath(), source, block });
+  }
+
+  // Relocate every bubble on the current version; the ones that cannot be
+  // placed are shown as detached rather than attached to the wrong passage.
+  const placed = createMemo(() => {
+    const all = blocks.blocks();
+    const byBlock = new Map<number, DocumentAnnotation[]>();
+    const detached: DocumentAnnotation[] = [];
+    const located = new Map<string, { startBlock: number; endBlock: number }>();
+    for (const a of documentStore.annotations) {
+      // Bubbles belong to one document each; the others' stay out of this one.
+      if (a.anchor.path !== documentPath()) continue;
+      if (a.resolved && !documentStore.showResolved) continue;
+      const loc = relocateAnchor(a.anchor, all);
+      if (!loc) {
+        detached.push(a);
+        continue;
+      }
+      located.set(a.id, loc);
+      const list = byBlock.get(loc.endBlock) ?? [];
+      list.push(a);
+      byBlock.set(loc.endBlock, list);
+    }
+    return { byBlock, detached, located };
+  });
+  const resolvedCount = () =>
+    documentStore.annotations.filter((a) => a.resolved && a.anchor.path === documentPath()).length;
+
+  /** A link to another file of the project: open it, then land on its anchor. */
+  async function navigate(path: string, anchor?: string) {
+    await openDocumentFile(path);
+    if (!anchor) return;
+    // The blocks render after the snapshot arrives; give them a frame.
+    requestAnimationFrame(() => {
+      if (docRef) findAnchorTarget(docRef, anchor)?.scrollIntoView({ block: 'start' });
+    });
+  }
+
+  /** A bubble becomes a task: select its passage and open the composer with its text. */
+  function makeTask(annotation: DocumentAnnotation) {
+    const all = blocks.blocks();
+    const loc = placed().located.get(annotation.id) ?? relocateAnchor(annotation.anchor, all);
+    if (!loc) return;
+    const text = annotation.answer
+      ? `${annotation.text}\n\nEarlier answer from ${annotation.answer.agentName}:\n${annotation.answer.text}`
+      : annotation.text;
+    setDocumentComposerDraft({ text, annotationId: annotation.id });
+    setDocumentSelection({
+      startBlock: loc.startBlock,
+      endBlock: loc.endBlock,
+      startLine: all[loc.startBlock].startLine,
+      endLine: all[loc.endBlock].endLine,
+      quote: all
+        .slice(loc.startBlock, loc.endBlock + 1)
+        .map((b) => b.raw.replace(/\n+$/, ''))
+        .join('\n\n'),
+      heading: annotation.anchor.heading,
+      wholeDocument: false,
+    });
+  }
+
+  // The undo offer expires on its own.
+  createEffect(
+    on(
+      () => documentStore.lastDeleted,
+      (deleted) => {
+        if (!deleted) return;
+        const timer = setTimeout(() => dismissUndo(), 10_000);
+        onCleanup(() => clearTimeout(timer));
+      },
+    ),
+  );
+
+  function blockElement(index: number): HTMLElement | null {
+    return docRef?.querySelector<HTMLElement>(`[data-block-index="${index}"]`) ?? null;
+  }
+
+  /**
+   * Puts the composer right under the picked passage, above it when the foot
+   * of the column is too close, and keeps it inside the column while the
+   * prose scrolls under it. With nothing picked it rests at the foot.
+   */
+  function placeComposer() {
+    const s = selection();
+    const last = s && !s.wholeDocument ? blockElement(s.endBlock) : null;
+    const first = s && !s.wholeDocument ? blockElement(s.startBlock) : null;
+    if (!last || !first || !mainRef || !layerRef) {
+      setAnchorTop(null);
+      return;
+    }
+    const column = mainRef.getBoundingClientRect();
+    const height = layerRef.offsetHeight;
+    const minTop = (scrollRef?.getBoundingClientRect().top ?? column.top) - column.top;
+    const maxTop = column.height - height - COMPOSER_GAP;
+    const below = last.getBoundingClientRect().bottom - column.top + COMPOSER_GAP;
+    const above = first.getBoundingClientRect().top - column.top - height - COMPOSER_GAP;
+    const top = below <= maxTop ? below : above >= minTop ? above : maxTop;
+    setAnchorTop(Math.max(minTop + COMPOSER_GAP, Math.min(top, maxTop)));
+  }
+
+  // Bring the picked passage into view and hang the composer off it. The store
+  // merges a new selection into the old object, so track the range itself.
+  const selectedRange = () => {
+    const s = selection();
+    return s ? `${s.startBlock}-${s.endBlock}-${s.wholeDocument ? 'all' : ''}` : null;
+  };
+  createEffect(
+    on([selectedRange, blocks.blocks], () => {
+      const s = selection();
+      requestAnimationFrame(() => {
+        if (s && !s.wholeDocument)
+          blockElement(s.endBlock)?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+        placeComposer();
+      });
+    }),
+  );
+
+  // The composer follows the passage as the prose scrolls and as its own
+  // height changes with the mode and the agents picked. The layer is created
+  // with the first snapshot, well after this mounts, so it is observed from
+  // its own ref rather than here.
+  const layerResize = new ResizeObserver(() => placeComposer());
+  onCleanup(() => layerResize.disconnect());
+  onMount(() => {
+    scrollRef?.addEventListener('scroll', placeComposer, { passive: true });
+    window.addEventListener('resize', placeComposer);
+    onCleanup(() => {
+      scrollRef?.removeEventListener('scroll', placeComposer);
+      window.removeEventListener('resize', placeComposer);
+    });
+  });
+
+  // A whole HTML page renders inline as element blocks in its own style, so it
+  // is worked on like any document. The sandboxed page render stays one click
+  // away for pages that lean on scripts or external stylesheets.
+  const isHtml = createMemo(() => isHtmlDocument(documentStore.snapshot?.content));
+  const [htmlView, setHtmlView] = createSignal<'inline' | 'page'>('inline');
+  const showsPreview = () => isHtml() && htmlView() === 'page';
+
+  const toolbarLabel = () => {
+    if (showsPreview()) return 'Sandboxed render of the page — switch to Inline to scope a task';
+    const s = selection();
+    if (!s || s.wholeDocument)
+      return 'Tasks act on the whole document; click a block, drag across blocks, or use § on a heading to narrow them';
+    return s.startLine === s.endLine
+      ? `Selected line ${s.startLine}`
+      : `Selected lines ${s.startLine}–${s.endLine}`;
+  };
+
+  return (
+    <div class="docws-main docws-doc-main" ref={mainRef}>
+      <div class="docws-toolbar">
+        <Show when={isHtml()}>
+          <span class="docws-tabs">
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={htmlView() === 'inline'}
+              title="The page as blocks you can select and scope tasks to"
+              onClick={() => setHtmlView('inline')}
+            >
+              Inline
+            </button>
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={htmlView() === 'page'}
+              title="The page in a sandboxed frame, exactly as a browser shows it"
+              onClick={() => setHtmlView('page')}
+            >
+              Page
+            </button>
+          </span>
+        </Show>
+        <span>{toolbarLabel()}</span>
+        <Show when={editableBlock() && !showsPreview()}>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            onClick={() => editBlock(editableBlock())}
+          >
+            Edit block
+          </button>
+        </Show>
+        <Show when={documentStore.lastDeleted}>
+          <span class="docws-undo">
+            Deleted a {documentStore.lastDeleted?.kind}.
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm"
+              onClick={() => void undoDeleteDocumentAnnotation()}
+            >
+              Undo
+            </button>
+          </span>
+        </Show>
+        <span style={{ 'margin-left': 'auto' }} />
+        <Show when={resolvedCount() > 0}>
+          <label class="docws-toggle" title="Resolved bubbles collapse to one line">
+            <input
+              type="checkbox"
+              checked={documentStore.showResolved}
+              onChange={(e) => setShowResolvedAnnotations(e.currentTarget.checked)}
+            />
+            {resolvedCount()} resolved
+          </label>
+        </Show>
+      </div>
+      <Show when={documentStore.snapshot?.missing}>
+        <div class="docws-older-banner">The document file is missing from the checkout.</div>
+      </Show>
+      <Show when={showsPreview()}>
+        {/* Fully sandboxed: the page renders with its own CSS but gets no
+              scripts, no forms and no same-origin access to the app. */}
+        <iframe
+          class="docws-html-preview"
+          sandbox=""
+          srcdoc={documentStore.snapshot?.content ?? ''}
+          title="HTML document preview"
+        />
+      </Show>
+      {/* Kept mounted while previewing so blocks, annotations and scroll
+            position survive the toggle. */}
+      <div
+        class="docws-scroll"
+        ref={scrollRef}
+        classList={{ 'is-hidden': showsPreview() }}
+        onMouseUp={(e) => {
+          if (releasesSelection(e.target)) setDocumentSelection(null);
+        }}
+      >
+        <div class="docws-doc" ref={docRef} classList={{ 'is-page': isHtml() }}>
+          <Show when={placed().detached.length > 0}>
+            <div class="docws-detached-section">
+              <div class="docws-rail-title">Detached notes</div>
+              <div class="docws-empty" style={{ padding: '2px 0 6px' }}>
+                Their passages are no longer in the document. Resolve or delete them, or turn them
+                into a task on a new selection.
+              </div>
+              <For each={placed().detached}>
+                {(a) => <AnnotationBubble annotation={a} detached onMakeTask={makeTask} />}
+              </For>
+            </div>
+          </Show>
+          <DocumentViewer
+            blocks={blocks.blocks()}
+            selectable
+            selection={range()}
+            onSelect={setDocumentSelection}
+            renderKey="main"
+            page={blocks.page()}
+            documentPath={documentPath()}
+            onNavigate={(path, anchor) => void navigate(path, anchor)}
+            onAction={(action, index) => {
+              if (action === 'edit') {
+                editBlock(blocks.blocks()[index] ?? null);
+                return;
+              }
+              batch(() => {
+                setDocumentSelection(
+                  selectionFromRange(blocks.blocks(), { start: index, end: index }),
+                );
+                setDocumentComposerDraft({ text: '', mode: action });
+              });
+            }}
+            hasMarker={(index) => (placed().byBlock.get(index)?.length ?? 0) > 0}
+            blockMarker={(index) => {
+              const annotations = placed().byBlock.get(index);
+              return (
+                <Show when={annotations?.length}>
+                  <AnnotationMarker annotations={annotations ?? []} onMakeTask={makeTask} />
+                </Show>
+              );
+            }}
+          />
+          <Show
+            when={
+              blocks.blocks().length === 0 &&
+              !blocks.rendering() &&
+              documentStore.snapshot &&
+              !documentStore.snapshot.missing
+            }
+          >
+            <div class="docws-empty">The document is empty.</div>
+          </Show>
+        </div>
+      </div>
+      {/* The composer floats over the prose instead of opening inside it, so
+          the passage it is about stays where it was picked: right above the
+          popover. It is always there; with nothing picked it rests at the foot
+          of the column and takes the whole document. */}
+      <Show when={documentStore.snapshot && !documentStore.snapshot.missing}>
+        <div
+          class="docws-composer-layer"
+          ref={(el) => {
+            layerRef = el;
+            layerResize.observe(el);
+          }}
+          classList={{ 'is-hidden': showsPreview(), 'is-anchored': anchorTop() !== null }}
+          style={anchorTop() !== null ? { top: `${anchorTop()}px`, bottom: 'auto' } : undefined}
+        >
+          <RunComposer
+            selection={selection()}
+            blocks={blocks.blocks()}
+            onClose={() => {
+              setDocumentSelection(null);
+              setDocumentComposerDraft(null);
+            }}
+          />
+        </div>
+      </Show>
+      <Show keyed when={blockEdit()}>
+        {(target) => (
+          <BlockEditor
+            target={target}
+            onClose={() => setBlockEdit(null)}
+            onSaved={() => {
+              setDocumentSelection(null);
+              void refreshDocumentSnapshot();
+            }}
+          />
+        )}
+      </Show>
+    </div>
+  );
+}
+
+/** Full-window surface for a document project: document, compare, history. */
+export function DocumentWorkspaceOverlay() {
+  const project = createMemo<Project | undefined>(() =>
+    store.activeDocumentProjectId ? getProject(store.activeDocumentProjectId) : undefined,
+  );
+  const [editing, setEditing] = createSignal<Project | null>(null);
+  const snapshot = () => documentStore.snapshot;
+  const reviewable = createMemo(() => reviewableRuns());
+  const editorCommand = () => store.editorCommand.trim();
+  const openPath = () => activeDocumentPath() ?? project()?.documentPath;
+  const editorButtonLabel = () => {
+    const documentPath = openPath() ?? 'document';
+    return editorCommand()
+      ? `Open ${documentPath} in ${editorCommand()}`
+      : `Configure an editor command in Settings to open ${documentPath}`;
+  };
+
+  // Close when the project disappears (removed while open).
+  createEffect(() => {
+    if (store.activeDocumentProjectId && !project()) closeDocumentWorkspace();
+  });
+
+  // Panel state is per workspace: a new project starts from the defaults.
+  createEffect(
+    on(
+      () => project()?.id,
+      () => resetWorkspaceUi(),
+    ),
+  );
+
+  onCleanup(() => {
+    if (documentStore.projectId) closeDocumentWorkspace();
+  });
+
+  function openDocumentInEditor() {
+    const currentProject = project();
+    const command = editorCommand();
+    const path = openPath();
+    if (!currentProject || !path || !command) return;
+    const documentPath = `${currentProject.path.replace(/\/$/, '')}/${path}`;
+    openInEditor(command, documentPath).catch((err) =>
+      showNotification(`Editor failed: ${errMessage(err)}`),
+    );
+  }
+
+  function tab(view: DocumentView, label: string) {
+    return (
+      <button
+        type="button"
+        class="docws-tab"
+        role="tab"
+        aria-selected={documentStore.view === view}
+        onClick={() => setDocumentView(view)}
+      >
+        {label}
+      </button>
+    );
+  }
+
+  // The document column absorbs the window; the right panel keeps the width
+  // the user dragged it to, remembered across restarts. The panel sits
+  // outside the view switch so the agent's terminal stays attached while
+  // comparing or reading history.
+  const panes: PanelChild[] = [
+    {
+      id: 'main',
+      minSize: 360,
+      content: () => (
+        <>
+          <Show when={documentStore.view === 'document' && project()}>
+            {(p) => <DocumentPane project={p()} />}
+          </Show>
+          <Show when={documentStore.view === 'history'}>
+            <div class="docws-main" style={{ overflow: 'hidden' }}>
+              <HistoryView />
+            </div>
+          </Show>
+        </>
+      ),
+    },
+    {
+      id: 'rail',
+      minSize: 300,
+      defaultSize: 420,
+      content: () => <Show when={project()}>{(p) => <RightPanel project={p()} />}</Show>,
+    },
+  ];
+
+  return (
+    <div
+      class="docws-overlay"
+      classList={{ 'is-mac': isMac }}
+      role="dialog"
+      aria-label="Document workspace"
+    >
+      <div class="docws-header" data-tauri-drag-region>
+        <div class="docws-title">
+          <DocumentIcon />
+          <span>{project()?.name}</span>
+          <button
+            type="button"
+            class="docws-btn docws-open-editor"
+            aria-label={editorButtonLabel()}
+            title={editorButtonLabel()}
+            disabled={!editorCommand() || !openPath()}
+            onClick={() => void openDocumentInEditor()}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+              <path d="M3.5 2a1.5 1.5 0 0 0-1.5 1.5v9A1.5 1.5 0 0 0 3.5 14h9a1.5 1.5 0 0 0 1.5-1.5v-3a.75.75 0 0 1 1.5 0v3A3 3 0 0 1 12.5 16h-9A3 3 0 0 1 0 12.5v-9A3 3 0 0 1 3.5 0h3a.75.75 0 0 1 0 1.5h-3ZM10 .75a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0V2.56L8.53 8.53a.75.75 0 0 1-1.06-1.06L13.44 1.5H10.75A.75.75 0 0 1 10 .75Z" />
+            </svg>
+          </button>
+        </div>
+        <span class="docws-subtitle" title={openPath()}>
+          {openPath()}
+        </span>
+        <span class="docws-head-chip" title="Checked-out branch and head commit">
+          <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
+          </svg>
+          {snapshot()?.branch ?? 'detached'} · {snapshot()?.headSha?.slice(0, 7) ?? 'no commits'}
+        </span>
+        <Show when={snapshot()?.dirty}>
+          <span
+            class="docws-head-chip is-warning"
+            title="Committed as “Manual edits” before the next run"
+          >
+            uncommitted edits
+          </span>
+        </Show>
+        <Show when={documentStore.loading}>
+          <span class="docws-head-chip">loading…</span>
+        </Show>
+        <Show when={reviewable().length > 0}>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            title="Open the compare view"
+            onClick={() => openDocumentCompare(reviewable()[0].id)}
+          >
+            {reviewable().length} to review
+          </button>
+        </Show>
+        <div class="docws-tabs" role="tablist">
+          {tab('document', 'Document')}
+          {tab('history', 'History')}
+        </div>
+        <button type="button" class="docws-btn" onClick={() => setEditing(project() ?? null)}>
+          Project
+        </button>
+        <button
+          type="button"
+          class="docws-btn"
+          title="Close (Esc)"
+          onClick={() => closeDocumentWorkspace()}
+        >
+          Close
+        </button>
+      </div>
+      <Show when={documentStore.error}>
+        <div class="docws-banner docws-banner-error" role="alert">
+          {documentStore.error}
+        </div>
+      </Show>
+      <div class="docws-body">
+        <ResizablePanel
+          direction="horizontal"
+          persistKey="docws"
+          absorberIds={['main']}
+          children={panes}
+        />
+      </div>
+      <EditProjectDialog project={editing()} onClose={() => setEditing(null)} />
+      <CandidateOutputDialog />
+      <CompareDialog />
+    </div>
+  );
+}
diff --git a/src/documents/FileTreePanel.tsx b/src/documents/FileTreePanel.tsx
new file mode 100644
index 000000000..675be9064
--- /dev/null
+++ b/src/documents/FileTreePanel.tsx
@@ -0,0 +1,121 @@
+import { For, Show, createEffect, createMemo, createSignal, on } from 'solid-js';
+import { activeDocumentPath, documentStore, openDocumentFile } from './store';
+import { loadDocumentFiles, workspaceUi } from './workspace-ui';
+import { buildPathTree, type PathTreeNode } from './path-tree';
+import { DocumentIcon } from './DocumentIcon';
+
+const DOCUMENT_RE = /\.(md|markdown|html?)$/i;
+
+interface FileTreePanelProps {
+  projectRoot: string;
+}
+
+function Chevron(props: { open: boolean }) {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+      style={{ transform: props.open ? 'rotate(90deg)' : undefined }}
+    >
+      <path d="M6.22 3.22a.75.75 0 0 1 1.06 0l4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.75.75 0 0 1-1.06-1.06L9.94 8 6.22 4.28a.75.75 0 0 1 0-1.06Z" />
+    </svg>
+  );
+}
+
+/**
+ * Every file of the project as a tree, on the Files tab of the right panel.
+ * Any file opens in the viewer, so a project's sources and notes are one
+ * click apart.
+ */
+export function FileTreePanel(props: FileTreePanelProps) {
+  const [collapsed, setCollapsed] = createSignal<Set<string>>(new Set());
+  const tree = createMemo(() => buildPathTree(workspaceUi.files));
+
+  // Commits and external edits add files; re-list on every new head and on open.
+  createEffect(
+    on(
+      () => [props.projectRoot, documentStore.snapshot?.headSha] as const,
+      ([root]) => void loadDocumentFiles(root),
+    ),
+  );
+
+  function toggle(path: string) {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
+  }
+
+  function Node(nodeProps: { node: PathTreeNode; depth: number }) {
+    const isFolder = () => nodeProps.node.children.length > 0;
+    const open = () => !collapsed().has(nodeProps.node.path);
+    const isActive = () => activeDocumentPath() === nodeProps.node.path;
+    const indent = () => ({ 'padding-left': `${8 + nodeProps.depth * 14}px` });
+    return (
+      <>
+        <Show
+          when={isFolder()}
+          fallback={
+            <button
+              type="button"
+              class="docws-tree-row"
+              classList={{ 'is-document': DOCUMENT_RE.test(nodeProps.node.name) }}
+              style={indent()}
+              aria-current={isActive() ? 'true' : undefined}
+              title={nodeProps.node.path}
+              onClick={() => void openDocumentFile(nodeProps.node.path)}
+            >
+              <span class="docws-tree-icon">
+                <Show when={DOCUMENT_RE.test(nodeProps.node.name)} fallback={<span>·</span>}>
+                  <DocumentIcon />
+                </Show>
+              </span>
+              <span class="docws-tree-name">{nodeProps.node.name}</span>
+            </button>
+          }
+        >
+          <button
+            type="button"
+            class="docws-tree-row is-folder"
+            style={indent()}
+            aria-expanded={open()}
+            onClick={() => toggle(nodeProps.node.path)}
+          >
+            <span class="docws-tree-icon">
+              <Chevron open={open()} />
+            </span>
+            <span class="docws-tree-name">{nodeProps.node.name}</span>
+          </button>
+          <Show when={open()}>
+            <For each={nodeProps.node.children}>
+              {(child) => <Node node={child} depth={nodeProps.depth + 1} />}
+            </For>
+          </Show>
+        </Show>
+      </>
+    );
+  }
+
+  return (
+    <div class="docws-files" role="region" aria-label="Project files">
+      <Show when={workspaceUi.filesError}>
+        <div class="docws-error" style={{ padding: '0 10px' }}>
+          {workspaceUi.filesError}
+        </div>
+      </Show>
+      <div class="docws-tree" role="tree">
+        <For each={tree()}>{(node) => <Node node={node} depth={0} />}</For>
+        <Show when={tree().length === 0 && !workspaceUi.filesError}>
+          <div class="docws-empty" style={{ padding: '8px 10px' }}>
+            No files yet.
+          </div>
+        </Show>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
new file mode 100644
index 000000000..c025ca828
--- /dev/null
+++ b/src/documents/HistoryView.tsx
@@ -0,0 +1,219 @@
+import { For, Show, createResource, createSignal, onCleanup } from 'solid-js';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { confirm } from '../lib/dialog';
+import { formatRelativeAge } from '../lib/relativeAge';
+import { activeDocumentPath, documentStore, revertDocumentCommit } from './store';
+import { getProject } from '../store/projects';
+import type { DocumentHistoryEntry } from './types';
+import { DocumentViewer } from './DocumentViewer';
+import { SourceDiff } from './SourceDiff';
+import { createRenderedBlocks } from './use-blocks';
+
+function project() {
+  return documentStore.projectId ? getProject(documentStore.projectId) : undefined;
+}
+
+function EntryDetail(props: {
+  entry: DocumentHistoryEntry;
+  documentPath: string;
+  onReverted: () => void;
+}) {
+  const [mode, setMode] = createSignal<'diff' | 'version'>('diff');
+  const root = () => project()?.path ?? '';
+  const [diff] = createResource(
+    () => ({
+      projectRoot: root(),
+      from: `${props.entry.sha}^`,
+      to: props.entry.sha,
+      documentPath: props.documentPath,
+    }),
+    (args) => invoke<string>(IPC.GetDocumentDiff, args),
+  );
+  const [content] = createResource(
+    () =>
+      mode() === 'version'
+        ? { projectRoot: root(), sha: props.entry.sha, documentPath: props.documentPath }
+        : null,
+    (args) => invoke<string | null>(IPC.GetDocumentAtCommit, args),
+  );
+  const rendered = createRenderedBlocks(() => content() ?? null);
+  const trailerEntries = () => Object.entries(props.entry.trailers);
+
+  async function revert() {
+    const ok = await confirm(
+      `Revert "${props.entry.subject}"? This adds a new commit that undoes it.`,
+      {
+        okLabel: 'Revert',
+        kind: 'warning',
+      },
+    );
+    if (!ok) return;
+    if (await revertDocumentCommit(props.entry.sha)) props.onReverted();
+  }
+
+  return (
+    <div class="docws-history-detail">
+      <div class="docws-history-detail-head">
+        <div class="docws-column-title">
+          <span>{props.entry.subject}</span>
+          <span style={{ 'margin-left': 'auto' }} class="docws-tabs">
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'diff'}
+              onClick={() => setMode('diff')}
+            >
+              Diff
+            </button>
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'version'}
+              onClick={() => setMode('version')}
+            >
+              Version
+            </button>
+          </span>
+        </div>
+        <div class="docws-history-meta">
+          <span>{props.entry.shortSha}</span>
+          <span>{props.entry.author}</span>
+          <span>{new Date(props.entry.timestamp * 1000).toLocaleString()}</span>
+          <span class="docws-badge">
+            {props.entry.manual ? 'manual' : props.entry.trailers.Agent}
+          </span>
+        </div>
+        <Show when={props.entry.body}>
+          <div class="docws-history-body">{props.entry.body}</div>
+        </Show>
+        <Show when={trailerEntries().length > 0}>
+          <dl class="docws-trailers">
+            <For each={trailerEntries()}>
+              {([key, value]) => (
+                <>
+                  <dt>{key}</dt>
+                  <dd>{value}</dd>
+                </>
+              )}
+            </For>
+          </dl>
+        </Show>
+        <div class="docws-run-actions">
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-danger"
+            onClick={() => void revert()}
+          >
+            Revert this commit
+          </button>
+        </div>
+      </div>
+      <Show when={mode() === 'version'}>
+        <div class="docws-older-banner">
+          Older version at {props.entry.shortSha}. The current document is on the Document tab.
+        </div>
+      </Show>
+      <div class="docws-column-body">
+        <Show
+          when={mode() === 'diff'}
+          fallback={
+            <DocumentViewer
+              blocks={rendered.blocks()}
+              renderKey={`hist-${props.entry.shortSha}`}
+              page={rendered.page()}
+            />
+          }
+        >
+          <Show when={!diff.loading} fallback={<div class="docws-empty">Loading diff…</div>}>
+            <SourceDiff raw={diff() ?? ''} />
+          </Show>
+        </Show>
+      </div>
+    </div>
+  );
+}
+
+/** `git log` for the document with the Parallel trailers parsed into prose. */
+export function HistoryView() {
+  const [wholeProject, setWholeProject] = createSignal(false);
+  const [selectedSha, setSelectedSha] = createSignal<string | null>(null);
+  const [version, setVersion] = createSignal(0);
+  const documentPath = () => activeDocumentPath() ?? project()?.documentPath ?? '';
+  const [entries] = createResource(
+    () => ({
+      root: project()?.path,
+      documentPath: documentPath(),
+      whole: wholeProject(),
+      head: documentStore.snapshot?.headSha,
+      version: version(),
+    }),
+    async ({ root, documentPath: docPath, whole }) => {
+      if (!root || !docPath) return [] as DocumentHistoryEntry[];
+      return invoke<DocumentHistoryEntry[]>(IPC.GetDocumentHistory, {
+        projectRoot: root,
+        documentPath: docPath,
+        wholeProject: whole,
+      });
+    },
+  );
+  const selected = () => entries()?.find((e) => e.sha === selectedSha()) ?? entries()?.[0] ?? null;
+  const [nowMs, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
+
+  return (
+    <div class="docws-history">
+      <div class="docws-history-list" role="listbox" aria-label="History">
+        <div class="docws-compare-bar">
+          <label class="docws-toggle">
+            <input
+              type="checkbox"
+              checked={wholeProject()}
+              onChange={(e) => setWholeProject(e.currentTarget.checked)}
+            />
+            Whole project
+          </label>
+          <span style={{ 'margin-left': 'auto' }}>{entries()?.length ?? 0} commits</span>
+        </div>
+        <Show when={entries()?.length === 0}>
+          <div class="docws-empty" style={{ padding: '12px 14px' }}>
+            No commits touch this document yet.
+          </div>
+        </Show>
+        <For each={entries() ?? []}>
+          {(entry) => (
+            <button
+              type="button"
+              role="option"
+              class="docws-history-entry"
+              aria-selected={selected()?.sha === entry.sha}
+              onClick={() => setSelectedSha(entry.sha)}
+            >
+              <span class="docws-history-subject">{entry.subject}</span>
+              <span class="docws-history-meta">
+                <span>{entry.shortSha}</span>
+                <span>{formatRelativeAge(entry.timestamp * 1000, nowMs())}</span>
+                <span class="docws-badge">{entry.manual ? 'manual' : entry.trailers.Agent}</span>
+                <Show when={entry.trailers.Candidate}>
+                  <span>candidate {entry.trailers.Candidate}</span>
+                </Show>
+              </span>
+            </button>
+          )}
+        </For>
+      </div>
+      <Show when={selected()} keyed>
+        {(entry) => (
+          <EntryDetail
+            entry={entry}
+            documentPath={documentPath()}
+            // The version is one of the resource's own inputs, so bumping it
+            // is the refetch; asking for one as well runs `git log` twice.
+            onReverted={() => setVersion((v) => v + 1)}
+          />
+        )}
+      </Show>
+    </div>
+  );
+}
diff --git a/src/documents/ModelRows.tsx b/src/documents/ModelRows.tsx
new file mode 100644
index 000000000..8f7796967
--- /dev/null
+++ b/src/documents/ModelRows.tsx
@@ -0,0 +1,77 @@
+import { For, Show } from 'solid-js';
+import { documentAgentSupport } from '../../electron/documents/shared';
+import type { DocumentCandidateSpec } from '../../electron/documents/types';
+import type { DocumentModelChoice } from '../store/types';
+
+/** One candidate's slot in the remembered choices: an agent and its n-th candidate. */
+export interface ChoiceSlot {
+  agentId: string;
+  index: number;
+}
+
+export interface ModelSlot extends ChoiceSlot {
+  spec: DocumentCandidateSpec;
+}
+
+interface ModelRowsProps {
+  slots: ModelSlot[];
+  choice: (slot: ChoiceSlot) => DocumentModelChoice;
+  /** `persist` is true once the user is done with the field, false while typing. */
+  onChoice: (slot: ChoiceSlot, patch: DocumentModelChoice, persist: boolean) => void;
+}
+
+/** Model and reasoning level per candidate, one row each. */
+export function ModelRows(props: ModelRowsProps) {
+  return (
+    <div class="docws-model-rows" role="group" aria-label="Model per candidate">
+      <For each={props.slots}>
+        {(slot) => {
+          const support = documentAgentSupport(slot.agentId);
+          const listId = `docws-models-${slot.spec.id}`;
+          const who = `candidate ${slot.spec.label} (${slot.spec.agentName})`;
+          return (
+            <div class="docws-model-row">
+              <span class="docws-model-agent">
+                <span class="docws-candidate-label">{slot.spec.label}</span>
+                {slot.spec.agentName}
+                <Show when={slot.spec.isMain}>
+                  <span class="docws-main-badge">main</span>
+                </Show>
+              </span>
+              <label>
+                Model{' '}
+                <input
+                  class="docws-model-input"
+                  list={listId}
+                  placeholder="default"
+                  aria-label={`Model for ${who}`}
+                  title="Any model name the CLI accepts; empty for its default"
+                  value={props.choice(slot).model ?? ''}
+                  onInput={(e) => props.onChoice(slot, { model: e.currentTarget.value }, false)}
+                  onChange={(e) => props.onChoice(slot, { model: e.currentTarget.value }, true)}
+                />
+                <datalist id={listId}>
+                  <For each={support.models}>{(m) => <option value={m} />}</For>
+                </datalist>
+              </label>
+              <Show when={support.efforts.length > 0}>
+                <label>
+                  Reasoning{' '}
+                  <select
+                    class="docws-select"
+                    aria-label={`Reasoning level for ${who}`}
+                    value={props.choice(slot).effort ?? ''}
+                    onChange={(e) => props.onChoice(slot, { effort: e.currentTarget.value }, true)}
+                  >
+                    <option value="">default</option>
+                    <For each={support.efforts}>{(e) => <option value={e}>{e}</option>}</For>
+                  </select>
+                </label>
+              </Show>
+            </div>
+          );
+        }}
+      </For>
+    </div>
+  );
+}
diff --git a/src/documents/NewDocumentProjectDialog.client.test.tsx b/src/documents/NewDocumentProjectDialog.client.test.tsx
new file mode 100644
index 000000000..d4a5052c5
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.client.test.tsx
@@ -0,0 +1,65 @@
+import { render } from 'solid-js/web';
+import { afterEach, expect, it, vi } from 'vitest';
+import { NewDocumentProjectDialog } from './NewDocumentProjectDialog';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+
+vi.mock('../lib/ipc', () => ({ invoke: vi.fn() }));
+vi.mock('../store/projects', () => ({ addDocumentProject: vi.fn(() => 'project') }));
+vi.mock('./store', () => ({ openDocumentWorkspace: vi.fn() }));
+
+let dispose: (() => void) | undefined;
+afterEach(() => {
+  dispose?.();
+  document.body.replaceChildren();
+  vi.resetAllMocks();
+});
+
+async function open(files: Array<{ path: string; committed: boolean }>) {
+  vi.mocked(invoke).mockImplementation(async (channel) =>
+    channel === IPC.InspectDocumentFolder
+      ? { exists: true, isRepo: true, files }
+      : { documentPath: files[0]?.path ?? 'design-notes.md', actions: [] },
+  );
+  dispose = render(() => <NewDocumentProjectDialog open onClose={() => {}} />, document.body);
+  const input = document.querySelector<HTMLInputElement>('[aria-label="Project folder"]');
+  if (!input) throw new Error('Project folder input did not render');
+  input.value = '/tmp/design-notes';
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  await vi.waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith(IPC.InspectDocumentFolder, {
+      projectRoot: '/tmp/design-notes',
+    }),
+  );
+}
+
+function submit() {
+  Array.from(document.querySelectorAll('button'))
+    .find((b) => b.textContent === 'Open workspace')
+    ?.click();
+}
+
+it('creates Markdown without asking first-time users to choose a format', async () => {
+  await open([]);
+  expect(document.querySelector('[aria-label="Document format"]')).toBeNull();
+  submit();
+  await vi.waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith(IPC.PrepareDocumentProject, {
+      projectRoot: '/tmp/design-notes',
+      documentPath: 'design-notes.md',
+      title: 'design-notes',
+    }),
+  );
+});
+
+it('still opens an existing HTML document', async () => {
+  await open([{ path: 'page.html', committed: true }]);
+  submit();
+  await vi.waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith(IPC.PrepareDocumentProject, {
+      projectRoot: '/tmp/design-notes',
+      documentPath: 'page.html',
+      title: 'design-notes',
+    }),
+  );
+});
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
new file mode 100644
index 000000000..094930f9c
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -0,0 +1,324 @@
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  onCleanup,
+} from 'solid-js';
+import { Dialog } from '../components/Dialog';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { openDialog } from '../lib/dialog';
+import { errMessage } from '../lib/log';
+import { theme, sectionLabelStyle } from '../lib/theme';
+import { addDocumentProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import type { DocumentFileInfo, DocumentFolderInfo, DocumentProjectSetup } from './types';
+import { openDocumentWorkspace } from './store';
+
+interface NewDocumentProjectDialogProps {
+  open: boolean;
+  onClose: () => void;
+}
+
+/** Which file the workspace opens on: one from the folder's list, or a new one named after the project. */
+type DocumentChoice = 'default' | 'new' | { existing: string };
+
+/** The file name when the project name has nothing usable in it. */
+const FALLBACK_NAME = 'notes';
+/** Typing a path should not spawn a `git` process per keystroke. */
+const INSPECT_DEBOUNCE_MS = 250;
+
+/** The document a folder most likely wants opened: a committed file, else any file. */
+function preferredDocument(files: DocumentFileInfo[]): string | undefined {
+  return files.find((f) => f.committed)?.path ?? files[0]?.path;
+}
+
+function folderName(folder: string): string {
+  return folder.replace(/\/+$/, '').split('/').pop() ?? folder;
+}
+
+/** `Onboarding flow` → `onboarding-flow`, the file a new project is named after. */
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** "a, b and c" */
+function joinSteps(steps: string[]): string {
+  if (steps.length < 2) return steps.join('');
+  return `${steps.slice(0, -1).join(', ')} and ${steps[steps.length - 1]}`;
+}
+
+/**
+ * Picks a folder and names the project; the document is a Markdown file
+ * named after the project, or one the folder already holds. Nothing has to exist
+ * yet: the folder path is editable, so a new project is a name typed onto a
+ * parent directory, and the backend creates the folder, initialises the
+ * repository, writes the document and makes the first commit.
+ */
+export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
+  const [folder, setFolder] = createSignal('');
+  const [name, setName] = createSignal('');
+  const [nameEdited, setNameEdited] = createSignal(false);
+  const [filter, setFilter] = createSignal('');
+  const [choice, setChoice] = createSignal<DocumentChoice>('default');
+  const [error, setError] = createSignal('');
+  const [busy, setBusy] = createSignal(false);
+
+  // Re-inspected as the path is edited; a folder that does not exist yet comes
+  // back empty rather than as an error.
+  const [settledFolder, setSettledFolder] = createSignal('');
+  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+  createEffect(() => {
+    const value = folder().trim();
+    clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => setSettledFolder(value), INSPECT_DEBOUNCE_MS);
+  });
+  onCleanup(() => clearTimeout(settleTimer));
+
+  const [info] = createResource(
+    () => settledFolder() || null,
+    // A path that is still half-typed, or one the app may not read, is simply
+    // "nothing known about it yet"; creating the project reports the real error.
+    (projectRoot) =>
+      invoke<DocumentFolderInfo>(IPC.InspectDocumentFolder, { projectRoot }).catch(() => null),
+  );
+
+  const files = () => info()?.files ?? [];
+  const visibleFiles = createMemo(() => {
+    const q = filter().trim().toLowerCase();
+    return q ? files().filter((f) => f.path.toLowerCase().includes(q)) : files();
+  });
+  const projectName = () => (nameEdited() ? name() : folderName(folder().trim()));
+  const newDocumentPath = () => `${slugify(projectName()) || FALLBACK_NAME}.md`;
+  const documentPath = () => {
+    const current = choice();
+    if (typeof current === 'object') return current.existing;
+    if (current === 'new') return newDocumentPath();
+    return preferredDocument(files()) ?? newDocumentPath();
+  };
+  /** What creating the project will do, so nothing about it is a surprise. */
+  const plan = createMemo(() => {
+    const current = info();
+    const file = documentPath();
+    if (!current) return [];
+    const steps: string[] = [];
+    if (!current.exists) steps.push('create the folder');
+    if (!current.isRepo) steps.push('initialise a Git repository');
+    const match = files().find((f) => f.path === file);
+    if (!match) steps.push(`create and commit ${file}`);
+    else if (!match.committed) steps.push(`commit ${file}`);
+    return steps;
+  });
+
+  function reset() {
+    setFolder('');
+    setName('');
+    setNameEdited(false);
+    setFilter('');
+    setChoice('default');
+    setError('');
+  }
+
+  function close() {
+    reset();
+    props.onClose();
+  }
+
+  async function chooseFolder() {
+    const selected = await openDialog({ directory: true, multiple: false });
+    if (selected) setFolder(selected as string);
+  }
+
+  const enclosingRepo = () => info()?.enclosingRepo ?? null;
+  const canCreate = () =>
+    folder().trim().startsWith('/') &&
+    documentPath().trim() &&
+    projectName().trim() &&
+    !busy() &&
+    !enclosingRepo();
+
+  async function create() {
+    if (!canCreate()) return;
+    setBusy(true);
+    setError('');
+    try {
+      const setup = await invoke<DocumentProjectSetup>(IPC.PrepareDocumentProject, {
+        projectRoot: folder().trim(),
+        documentPath: documentPath().trim(),
+        title: projectName().trim(),
+      });
+      const id = addDocumentProject(projectName().trim(), folder().trim(), setup.documentPath);
+      if (setup.actions.length > 0) showNotification(setup.actions.join(' · '));
+      close();
+      await openDocumentWorkspace(id);
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const inputStyle = {
+    background: theme.bgInput,
+    border: `1px solid ${theme.border}`,
+    'border-radius': 'var(--radius-md)',
+    padding: '7px 10px',
+    color: theme.fg,
+    'font-size': '13px',
+    outline: 'none',
+    width: '100%',
+    'box-sizing': 'border-box' as const,
+  };
+
+  return (
+    <Dialog open={props.open} onClose={close} width="520px">
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '14px' }}>
+        <h2 style={{ margin: 0, 'font-size': '16px' }}>New document project</h2>
+        <p style={{ margin: 0, 'font-size': '13px', color: theme.fgMuted }}>
+          Write a spec, architecture decision, or design note in Markdown. Select a passage, choose
+          Proposals, and compare alternatives before accepting changes.
+        </p>
+        <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+          <span style={sectionLabelStyle}>Folder</span>
+          <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
+            <input
+              style={{ ...inputStyle, 'font-family': 'var(--font-mono)', 'font-size': '12px' }}
+              aria-label="Project folder"
+              placeholder="/path/to/folder"
+              value={folder()}
+              onInput={(e) => setFolder(e.currentTarget.value)}
+            />
+            <button
+              type="button"
+              class="docws-btn"
+              onClick={() => void chooseFolder()}
+              disabled={busy()}
+            >
+              Browse…
+            </button>
+          </div>
+          <Show
+            when={!folder().trim() || folder().trim().startsWith('/')}
+            fallback={<span class="docws-error">The folder path has to be absolute.</span>}
+          >
+            <span style={{ 'font-size': '12px', color: theme.fgMuted }}>
+              Add a name to the end of the path to start a new project folder there.
+            </span>
+          </Show>
+        </div>
+        <Show when={folder().trim()}>
+          <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+            <span style={sectionLabelStyle}>Name</span>
+            <input
+              style={inputStyle}
+              aria-label="Project name"
+              value={projectName()}
+              onInput={(e) => {
+                setNameEdited(true);
+                setName(e.currentTarget.value);
+              }}
+            />
+          </div>
+          <Show when={files().length > 0}>
+            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+              <span style={sectionLabelStyle}>Document</span>
+              <Show when={files().length > 8}>
+                <input
+                  style={inputStyle}
+                  placeholder="Filter files…"
+                  value={filter()}
+                  onInput={(e) => setFilter(e.currentTarget.value)}
+                />
+              </Show>
+              <div class="docws-picker-list" role="listbox" aria-label="Documents in the folder">
+                <Show when={!files().some((f) => f.path === newDocumentPath())}>
+                  <button
+                    type="button"
+                    role="option"
+                    class="docws-picker-item"
+                    aria-selected={documentPath() === newDocumentPath()}
+                    onClick={() => setChoice('new')}
+                  >
+                    {newDocumentPath()}
+                    <span class="docws-badge">new</span>
+                  </button>
+                </Show>
+                <For each={visibleFiles()}>
+                  {(file) => (
+                    <button
+                      type="button"
+                      role="option"
+                      class="docws-picker-item"
+                      aria-selected={documentPath() === file.path}
+                      onClick={() => setChoice({ existing: file.path })}
+                    >
+                      {file.path}
+                      <Show when={!file.committed}>
+                        <span class="docws-badge">not committed</span>
+                      </Show>
+                    </button>
+                  )}
+                </For>
+              </div>
+            </div>
+          </Show>
+          <Show when={plan().length > 0}>
+            <span style={{ 'font-size': '12px', color: theme.fgMuted }}>
+              Parallel will {joinSteps(plan())}.
+            </span>
+          </Show>
+        </Show>
+        <Show when={enclosingRepo()}>
+          {(repo) => (
+            <div
+              class="docws-error"
+              style={{
+                'font-size': '13px',
+                display: 'flex',
+                'align-items': 'center',
+                gap: '10px',
+                'flex-wrap': 'wrap',
+              }}
+            >
+              <span style={{ flex: '1', 'min-width': '0' }}>
+                That folder is inside the Git repository at {repo()}. Proposals and history belong
+                to the repository, so the project has to be the repository itself.
+              </span>
+              <button
+                type="button"
+                class="docws-btn docws-btn-sm"
+                onClick={() => setFolder(repo())}
+              >
+                Use the repository
+              </button>
+            </div>
+          )}
+        </Show>
+        <Show when={error()}>
+          <div class="docws-error" style={{ 'font-size': '13px' }}>
+            {error()}
+          </div>
+        </Show>
+        <div style={{ display: 'flex', 'justify-content': 'flex-end', gap: '8px' }}>
+          <button type="button" class="docws-btn" onClick={close}>
+            Cancel
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-primary"
+            disabled={!canCreate()}
+            onClick={() => void create()}
+          >
+            {busy() ? 'Setting up…' : 'Open workspace'}
+          </button>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/src/documents/PageBlocks.tsx b/src/documents/PageBlocks.tsx
new file mode 100644
index 000000000..74ab3875e
--- /dev/null
+++ b/src/documents/PageBlocks.tsx
@@ -0,0 +1,128 @@
+import { For, createEffect, createSignal, on, onCleanup, type JSX } from 'solid-js';
+import { createBlockActionsElement, type BlockActionKind } from './BlockActions';
+import { Portal } from 'solid-js/web';
+import type { BlockRange } from './DocumentViewer';
+import type { BlockChange, DocumentBlock } from './markdown-blocks';
+
+/** A whole HTML page ready to show: its body markup with blocks marked, and its CSS. */
+export interface PageRender {
+  stylesheet: string;
+  html: string;
+}
+
+interface PageBlocksProps {
+  html: string;
+  blocks: DocumentBlock[];
+  /** Scope root of the page's CSS; the viewer's stylesheet targets it. */
+  pageKey: string;
+  selectable?: boolean;
+  selected: BlockRange | null;
+  changes?: BlockChange[];
+  scope?: BlockRange | null;
+  blockMarker?: (index: number) => JSX.Element;
+  /** Which blocks have a marker; only those get an anchor. */
+  hasMarker?: (index: number) => boolean;
+  onSelectSection: (index: number, e: MouseEvent) => void;
+  onAction?: (action: BlockActionKind, index: number) => void;
+}
+
+/** Where a block's marker is rendered: a hook appended inside the block. */
+interface MarkerAnchor {
+  index: number;
+  el: HTMLDivElement;
+}
+
+function inRange(range: BlockRange | null | undefined, index: number): boolean {
+  return !!range && index >= range.start && index <= range.end;
+}
+
+/**
+ * Renders a page's markup as one piece so its own layout and stylesheet hold,
+ * and works on the blocks marked inside it by hand: marks are classes on the
+ * page's elements, § buttons are appended to headings, and annotation markers
+ * go into anchors appended inside their block. Every one of those is out of
+ * the page's flow, so nothing the app adds moves the page's own elements.
+ */
+export function PageBlocks(props: PageBlocksProps) {
+  const [body, setBody] = createSignal<HTMLDivElement>();
+  const [anchors, setAnchors] = createSignal<MarkerAnchor[]>([]);
+
+  const blockElement = (index: number) =>
+    body()?.querySelector<HTMLElement>(`[data-block-index="${index}"]`) ?? null;
+
+  // Every effect depends on `props.html` so it runs again once new markup is in place.
+  createEffect(
+    on([() => props.html, () => props.selected, () => props.changes, () => props.scope], () => {
+      const root = body();
+      if (!root) return;
+      for (const el of root.querySelectorAll<HTMLElement>('[data-block-index]')) {
+        const index = Number(el.dataset.blockIndex);
+        const change = props.changes?.[index] ?? 'same';
+        el.dataset.change = change;
+        el.classList.toggle('is-selected', inRange(props.selected, index));
+        el.classList.toggle('is-changed', change === 'changed');
+        el.classList.toggle('is-added', change === 'added');
+        el.classList.toggle('is-removed', change === 'removed');
+        el.classList.toggle('is-scope', inRange(props.scope, index) && change === 'same');
+      }
+    }),
+  );
+
+  // Every block gets the hover toolbar, appended like the § button.
+  createEffect(() => {
+    const onAction = props.onAction;
+    if (!props.html || !props.selectable || !onAction) return;
+    for (const block of props.blocks) {
+      const el = blockElement(block.index);
+      if (!el || el.querySelector(':scope > .docws-block-actions')) continue;
+      el.append(createBlockActionsElement((kind) => onAction(kind, block.index)));
+    }
+  });
+
+  createEffect(() => {
+    if (!props.html || !props.selectable) return;
+    for (const block of props.blocks) {
+      if (block.headingLevel === undefined) continue;
+      const el = blockElement(block.index);
+      if (!el || el.querySelector(':scope > .docws-section-btn')) continue;
+      const button = document.createElement('button');
+      button.type = 'button';
+      button.className = 'docws-section-btn';
+      button.title = 'Select this section';
+      button.setAttribute('aria-label', `Select section ${block.headingText ?? ''}`);
+      button.textContent = '§';
+      button.onclick = (e) => props.onSelectSection(block.index, e);
+      el.append(button);
+    }
+  });
+
+  createEffect(() => {
+    const wants = props.hasMarker;
+    if (!props.html || !body() || !wants) {
+      setAnchors([]);
+      return;
+    }
+    const created: MarkerAnchor[] = [];
+    for (const block of props.blocks) {
+      if (!wants(block.index)) continue;
+      const el = blockElement(block.index);
+      if (!el) continue;
+      const anchor = document.createElement('div');
+      anchor.className = 'docws-marker-anchor';
+      el.append(anchor);
+      created.push({ index: block.index, el: anchor });
+    }
+    setAnchors(created);
+    onCleanup(() => created.forEach((a) => a.el.remove()));
+  });
+
+  return (
+    <>
+      {/* eslint-disable-next-line solid/no-innerhtml -- page markup is DOMPurify-sanitized HTML from a local file */}
+      <div class="docws-page-body" data-page={props.pageKey} ref={setBody} innerHTML={props.html} />
+      <For each={anchors()}>
+        {(anchor) => <Portal mount={anchor.el}>{props.blockMarker?.(anchor.index)}</Portal>}
+      </For>
+    </>
+  );
+}
diff --git a/src/documents/RightPanel.tsx b/src/documents/RightPanel.tsx
new file mode 100644
index 000000000..a9a552f7f
--- /dev/null
+++ b/src/documents/RightPanel.tsx
@@ -0,0 +1,119 @@
+import { For, Show, createMemo } from 'solid-js';
+import type { Project } from '../store/types';
+import { getAgentHookStatus } from '../store/agentHookStatus';
+import { documentStore, openDocumentCompare, rejectDocumentRun, reviewableRuns } from './store';
+import { setRailTab, workspaceUi } from './workspace-ui';
+import { documentAgentPtyId } from './agent-terminal';
+import { AgentTerminal } from './AgentTerminal';
+import { RunsRail } from './RunsRail';
+import { FileTreePanel } from './FileTreePanel';
+
+interface RightPanelProps {
+  project: Project;
+}
+
+/** Finished runs with proposals nobody has accepted or rejected yet. */
+function DecisionStrip() {
+  const pending = createMemo(() => reviewableRuns());
+  return (
+    <Show when={pending().length > 0}>
+      <div class="docws-decisions" role="region" aria-label="Runs awaiting a decision">
+        <For each={pending()}>
+          {(run) => {
+            const proposals = () => run.candidates.filter((c) => c.commitSha).length;
+            return (
+              <div class="docws-decision">
+                <span class="docws-decision-text" title={run.instruction}>
+                  {run.instruction}
+                </span>
+                <button
+                  type="button"
+                  class="docws-btn docws-btn-sm docws-btn-primary"
+                  onClick={() => openDocumentCompare(run.id)}
+                >
+                  {proposals() > 1 ? `Compare ${proposals()}` : 'Review'}
+                </button>
+                <button
+                  type="button"
+                  class="docws-btn docws-btn-sm docws-btn-danger"
+                  onClick={() => void rejectDocumentRun(run.id)}
+                >
+                  Reject
+                </button>
+              </div>
+            );
+          }}
+        </For>
+      </div>
+    </Show>
+  );
+}
+
+/**
+ * The right-hand column: the interactive agent, the one-shot runs and the
+ * project's files, one tab each. Runs that wait for a decision are shown over
+ * the agent too, so nothing sits unnoticed behind a tab that is not up.
+ */
+export function RightPanel(props: RightPanelProps) {
+  const decisions = () => reviewableRuns().length;
+  const running = () =>
+    documentStore.runOrder.filter((id) => documentStore.runs[id]?.status === 'running').length;
+  const agentWaiting = () =>
+    getAgentHookStatus(documentAgentPtyId(props.project.id))?.state === 'waiting';
+
+  return (
+    <aside class="docws-rail" aria-label="Agent and runs">
+      <div class="docws-rail-tabs docws-tabs" role="tablist">
+        <button
+          type="button"
+          class="docws-tab"
+          role="tab"
+          aria-selected={workspaceUi.railTab === 'agent'}
+          onClick={() => setRailTab('agent')}
+        >
+          Agent
+          <Show when={agentWaiting()}>
+            <span class="docws-count is-attention" title="The agent is waiting for you">
+              !
+            </span>
+          </Show>
+        </button>
+        <button
+          type="button"
+          class="docws-tab"
+          role="tab"
+          aria-selected={workspaceUi.railTab === 'runs'}
+          onClick={() => setRailTab('runs')}
+        >
+          Runs
+          <Show when={decisions() + running() > 0}>
+            <span class="docws-count" classList={{ 'is-attention': decisions() > 0 }}>
+              {decisions() > 0 ? decisions() : running()}
+            </span>
+          </Show>
+        </button>
+        <button
+          type="button"
+          class="docws-tab"
+          role="tab"
+          aria-selected={workspaceUi.railTab === 'files'}
+          onClick={() => setRailTab('files')}
+        >
+          Files
+        </button>
+      </div>
+      <Show when={workspaceUi.railTab === 'agent'}>
+        <DecisionStrip />
+        <AgentTerminal project={props.project} />
+      </Show>
+      <Show when={workspaceUi.railTab === 'runs'}>
+        <div class="docws-rail-list">
+          <RunsRail />
+        </div>
+      </Show>
+      <Show when={workspaceUi.railTab === 'files'}>
+        <FileTreePanel projectRoot={props.project.path} />
+      </Show>
+    </aside>
+  );
+}
diff --git a/src/documents/RunComposer.annotate.client.test.tsx b/src/documents/RunComposer.annotate.client.test.tsx
new file mode 100644
index 000000000..13200433b
--- /dev/null
+++ b/src/documents/RunComposer.annotate.client.test.tsx
@@ -0,0 +1,125 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { RunComposer } from './RunComposer';
+import type { DocumentBlock } from './markdown-blocks';
+import type { DocumentSelection } from './store';
+
+const { addDocumentAnnotation } = vi.hoisted(() => ({
+  addDocumentAnnotation: vi.fn(async () => ({ id: 'saved-1' })),
+}));
+
+vi.mock('./agent-terminal', () => ({
+  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+  sendToDocumentAgent: vi.fn(() => Promise.resolve()),
+}));
+
+vi.mock('./store', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./store')>()),
+  addDocumentAnnotation,
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ projects: [], availableAgents: [] });
+  vi.clearAllMocks();
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'paragraph',
+    raw: 'Body text.\n',
+    html: '<p>Body text.</p>',
+    startLine: 1,
+    endLine: 1,
+  },
+];
+
+const passage: DocumentSelection = {
+  startBlock: 0,
+  endBlock: 0,
+  startLine: 1,
+  endLine: 1,
+  quote: 'Body text.',
+  heading: undefined,
+  wholeDocument: false,
+};
+
+function tab(host: HTMLElement, label: string): HTMLButtonElement | undefined {
+  return Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]')).find(
+    (t) => t.textContent?.trim() === label,
+  );
+}
+
+function type(host: HTMLElement, text: string): HTMLTextAreaElement {
+  const textarea = host.querySelector('textarea') as HTMLTextAreaElement;
+  textarea.value = text;
+  textarea.dispatchEvent(new Event('input', { bubbles: true }));
+  return textarea;
+}
+
+function pressEnter(textarea: HTMLTextAreaElement): void {
+  textarea.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+}
+
+describe('RunComposer after a note or question is saved', () => {
+  it('empties the instruction so the next passage opens on a blank composer', async () => {
+    const onClose = vi.fn();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={onClose} />, host),
+    );
+
+    tab(host, 'Ask')?.click();
+    const textarea = type(host, 'Why is this here?');
+    pressEnter(textarea);
+    await vi.waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    expect(addDocumentAnnotation).toHaveBeenCalledWith(
+      'question',
+      'Why is this here?',
+      expect.anything(),
+      undefined,
+    );
+    expect(textarea.value).toBe('');
+  });
+
+  it('empties the instruction for a saved note too', async () => {
+    const onClose = vi.fn();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={onClose} />, host),
+    );
+
+    tab(host, 'Note')?.click();
+    const textarea = type(host, 'Revisit this paragraph.');
+    pressEnter(textarea);
+    await vi.waitFor(() => expect(onClose).toHaveBeenCalled());
+
+    expect(textarea.value).toBe('');
+  });
+
+  it('keeps the text when saving failed, so nothing typed is lost', async () => {
+    addDocumentAnnotation.mockResolvedValueOnce(null as never);
+    const onClose = vi.fn();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={onClose} />, host),
+    );
+
+    tab(host, 'Ask')?.click();
+    const textarea = type(host, 'Why is this here?');
+    pressEnter(textarea);
+    await vi.waitFor(() => expect(addDocumentAnnotation).toHaveBeenCalled());
+
+    expect(onClose).not.toHaveBeenCalled();
+    expect(textarea.value).toBe('Why is this here?');
+  });
+});
diff --git a/src/documents/RunComposer.client.test.tsx b/src/documents/RunComposer.client.test.tsx
new file mode 100644
index 000000000..f3d70bf06
--- /dev/null
+++ b/src/documents/RunComposer.client.test.tsx
@@ -0,0 +1,130 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { RunComposer } from './RunComposer';
+import type { DocumentBlock } from './markdown-blocks';
+import type { DocumentSelection } from './store';
+
+vi.mock('./agent-terminal', () => ({
+  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+  sendToDocumentAgent: vi.fn(() => Promise.resolve()),
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ projects: [], availableAgents: [] });
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'paragraph',
+    raw: '# Title\n',
+    html: '<h1>Title</h1>',
+    startLine: 1,
+    endLine: 1,
+    headingLevel: 1,
+    headingText: 'Title',
+  },
+  {
+    index: 1,
+    type: 'paragraph',
+    raw: 'Body text.\n',
+    html: '<p>Body text.</p>',
+    startLine: 3,
+    endLine: 3,
+  },
+];
+
+const passage: DocumentSelection = {
+  startBlock: 1,
+  endBlock: 1,
+  startLine: 3,
+  endLine: 3,
+  quote: 'Body text.',
+  heading: 'Title',
+  wholeDocument: false,
+};
+
+function mount(selection: DocumentSelection | null) {
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(() => <RunComposer selection={selection} blocks={blocks} onClose={() => {}} />, host),
+  );
+  return host;
+}
+
+function tab(host: HTMLElement, label: string): HTMLButtonElement | null {
+  return (
+    Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]')).find(
+      (b) => b.textContent?.trim() === label,
+    ) ?? null
+  );
+}
+
+describe('RunComposer', () => {
+  it('runs a task in the session and puts proposals on their own tab', () => {
+    const host = mount(passage);
+
+    const task = tab(host, 'Task');
+    const proposals = tab(host, 'Proposals');
+    expect(task?.getAttribute('aria-selected')).toBe('true');
+    expect(proposals?.getAttribute('aria-selected')).toBe('false');
+    expect(host.textContent).toContain('The agent edits your document directly.');
+    expect(host.querySelector<HTMLElement>('[aria-label="Agents"]')?.style.display).toBe('none');
+
+    proposals?.click();
+
+    expect(task?.getAttribute('aria-selected')).toBe('false');
+    expect(proposals?.getAttribute('aria-selected')).toBe('true');
+    expect(host.querySelector<HTMLElement>('[aria-label="Agents"]')?.style.display).toBe('');
+    const options = host.querySelector('details');
+    expect(options).not.toBeNull();
+    expect(options?.open).toBe(false);
+    expect(options?.contains(host.querySelector('[aria-label="Agents"]'))).toBe(true);
+    expect(host.textContent).toContain('Your document changes only when you accept a proposal.');
+    // No second toggle: the run target is one of the modes now.
+    expect(host.querySelectorAll('[role="radio"]')).toHaveLength(0);
+  });
+
+  it('keeps proposals reachable with nothing picked, unlike notes and questions', () => {
+    const host = mount(null);
+
+    expect(tab(host, 'Proposals')?.disabled).toBe(false);
+    expect(tab(host, 'Note')?.disabled).toBe(true);
+  });
+
+  it('acts on the whole document when nothing is picked and keeps notes to passages', () => {
+    const host = mount(null);
+
+    expect(host.textContent).toContain('Whole document');
+    const tabs = Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]'));
+    expect(tabs.find((t) => t.textContent === 'Note')?.disabled).toBe(true);
+    expect(tabs.find((t) => t.textContent === 'Ask')?.disabled).toBe(true);
+    expect(host.querySelector('.docws-composer-quote')).toBeNull();
+  });
+
+  it('opens at full strength on a passage and steps back once focus leaves', () => {
+    const host = mount(passage);
+    const composer = host.querySelector<HTMLElement>('.docws-composer');
+    expect(composer?.classList.contains('is-fresh')).toBe(true);
+
+    const outside = document.createElement('button');
+    document.body.append(outside);
+    composer?.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: outside }));
+
+    expect(composer?.classList.contains('is-fresh')).toBe(false);
+  });
+
+  it('quotes the picked passage and lets notes attach to it', () => {
+    const host = mount(passage);
+
+    expect(host.querySelector('.docws-composer-quote')?.textContent).toBe('Body text.');
+    const tabs = Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]'));
+    expect(tabs.find((t) => t.textContent === 'Note')?.disabled).toBe(false);
+  });
+});
diff --git a/src/documents/RunComposer.draft.client.test.tsx b/src/documents/RunComposer.draft.client.test.tsx
new file mode 100644
index 000000000..d76b5e2db
--- /dev/null
+++ b/src/documents/RunComposer.draft.client.test.tsx
@@ -0,0 +1,88 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { BLOCK_ACTIONS } from './BlockActions';
+import { RunComposer } from './RunComposer';
+import { setDocumentComposerDraft, type DocumentSelection } from './store';
+import type { DocumentBlock } from './markdown-blocks';
+
+vi.mock('./agent-terminal', () => ({
+  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+  sendToDocumentAgent: vi.fn(() => Promise.resolve()),
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setDocumentComposerDraft(null);
+  setStore({ projects: [], availableAgents: [] });
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'paragraph',
+    raw: 'Body text.\n',
+    html: '<p>Body text.</p>',
+    startLine: 1,
+    endLine: 1,
+  },
+];
+
+const passage: DocumentSelection = {
+  startBlock: 0,
+  endBlock: 0,
+  startLine: 1,
+  endLine: 1,
+  quote: 'Body text.',
+  heading: undefined,
+  wholeDocument: false,
+};
+
+describe('RunComposer draft mode', () => {
+  it('opens on the mode a hover action asked for', () => {
+    setDocumentComposerDraft({ text: '', mode: 'question' });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={() => {}} />, host),
+    );
+
+    const selected = Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]')).find(
+      (t) => t.getAttribute('aria-selected') === 'true',
+    );
+    expect(selected?.textContent).toBe('Ask');
+  });
+
+  it('carries the hover icons on its tabs and lets go of the passage from its corner', () => {
+    const onClose = vi.fn();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={onClose} />, host),
+    );
+
+    const tabs = Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]'));
+    // Same glyphs in the same order as the block toolbar, minus its pencil.
+    expect(tabs.map((t) => t.querySelector('path')?.getAttribute('d'))).toEqual(
+      BLOCK_ACTIONS.filter((a) => a.kind !== 'edit').map((a) => a.path),
+    );
+
+    host.querySelector<HTMLButtonElement>('[aria-label="Clear the passage"]')?.click();
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it('has no passage to let go of when it acts on the whole document', () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={null} blocks={blocks} onClose={() => {}} />, host),
+    );
+
+    expect(host.querySelector('[aria-label="Clear the passage"]')).toBeNull();
+    expect(host.textContent).toContain('Whole document');
+  });
+});
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
new file mode 100644
index 000000000..8307c47bd
--- /dev/null
+++ b/src/documents/RunComposer.tsx
@@ -0,0 +1,529 @@
+import { For, Show, createEffect, createMemo, createSignal, on, untrack } from 'solid-js';
+import { store } from '../store/core';
+import {
+  activeDocumentPath,
+  addDocumentAnnotation,
+  buildCandidateSpecs,
+  dispatchDocumentRun,
+  documentMainAgentId,
+  documentModelChoices,
+  documentStore,
+  setDocumentMainAgent,
+  setDocumentModelChoice,
+  withModelChoice,
+  type ComposerMode,
+  type DispatchSelection,
+  type DocumentSelection,
+} from './store';
+import { createAnchor } from './annotation-anchor';
+import type { DocumentBlock } from './markdown-blocks';
+import { getProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import { errMessage } from '../lib/log';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from '../../electron/documents/shared';
+import type { AgentDef } from '../ipc/types';
+import type { DocumentModelChoice } from '../store/types';
+import { ModelRows, type ChoiceSlot, type ModelSlot } from './ModelRows';
+import { buildInteractivePrompt } from './interactive-prompt';
+import { documentAgentPtyId, sendToDocumentAgent } from './agent-terminal';
+import { ActionIcon } from './BlockActions';
+
+interface RunComposerProps {
+  /** The picked passage; null means the whole document. */
+  selection: DocumentSelection | null;
+  /** Current blocks, for anchoring an annotation to the selection. */
+  blocks: DocumentBlock[];
+  onClose: () => void;
+}
+
+const MAX_PER_AGENT = 3;
+
+function wholeDocumentSelection(blocks: DocumentBlock[]): DocumentSelection {
+  const last = blocks[blocks.length - 1];
+  return {
+    startBlock: 0,
+    endBlock: Math.max(0, blocks.length - 1),
+    startLine: blocks[0]?.startLine ?? 1,
+    endLine: last?.endLine ?? 1,
+    quote: '',
+    heading: undefined,
+    wholeDocument: true,
+  };
+}
+
+/**
+ * The popover that turns a passage into work: a task for the interactive
+ * session or for one-shot candidates, a note, or a question. It is always
+ * there over the foot of the document column and fades when it is not in use;
+ * with nothing picked it acts on the whole document. The main session is
+ * preselected with one candidate so the fast path is select, type, Enter.
+ */
+export function RunComposer(props: RunComposerProps) {
+  let textareaRef: HTMLTextAreaElement | undefined;
+  const draft = untrack(() => documentStore.composerDraft);
+  const [instruction, setInstruction] = createSignal(draft?.text ?? '');
+  const [mode, setMode] = createSignal<ComposerMode>('task');
+  // Task and proposals are one instruction with two destinations: the agent's
+  // session, or headless candidates. They share the textarea and the placeholder.
+  const isTask = () => mode() === 'task' || mode() === 'proposals';
+  const oneshot = () => mode() === 'proposals';
+  const [saving, setSaving] = createSignal(false);
+  // Just opened on a passage: shown at full strength until focus leaves it.
+  const [fresh, setFresh] = createSignal(false);
+  let rootRef: HTMLDivElement | undefined;
+  const selection = (): DocumentSelection =>
+    props.selection ?? wholeDocumentSelection(props.blocks);
+  const hasPassage = () => !!props.selection && !props.selection.wholeDocument;
+  const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
+  const mainAgentId = () => documentMainAgentId(project());
+  // Preselecting an agent that is not installed would only fail on dispatch.
+  const [counts, setCounts] = createSignal<Record<string, number>>(
+    untrack(() => {
+      const id = mainAgentId();
+      const main = store.availableAgents.find((a) => a.id === id);
+      return main && main.available !== false ? { [id]: 1 } : {};
+    }),
+  );
+  const [askAgentId, setAskAgentId] = createSignal(mainAgentId());
+  // Starts from the project's last choices per agent and candidate slot, and
+  // is remembered as it changes.
+  const [choices, setChoices] = createSignal<Record<string, DocumentModelChoice[]>>(
+    untrack(() => {
+      const p = project();
+      const ids = Object.keys(p?.documentModels ?? {});
+      return Object.fromEntries(ids.map((id) => [id, documentModelChoices(p, id)]));
+    }),
+  );
+  const choice = (slot: ChoiceSlot): DocumentModelChoice =>
+    choices()[slot.agentId]?.[slot.index] ?? {};
+
+  const agents = createMemo(() => store.availableAgents);
+  const resumable = createMemo(() =>
+    agents().filter((a) => a.available !== false && documentAgentSupport(a.id).resume),
+  );
+
+  // Agents and counts alone: the model rows key off this, so typing a model
+  // name does not rebuild them.
+  const layout = createMemo(() =>
+    agents()
+      .filter((a) => (counts()[a.id] ?? 0) > 0)
+      .map((agent) => ({ agent, count: counts()[agent.id] })),
+  );
+  const picks = (): DispatchSelection[] =>
+    layout().map((pick) => ({ ...pick, choices: choices()[pick.agent.id] ?? [] }));
+  // The same specs dispatch will build, so labels and the main badge match the rail.
+  const slots = createMemo<ModelSlot[]>(() => {
+    const p = project();
+    if (!p) return [];
+    const seen = new Map<string, number>();
+    return buildCandidateSpecs(p, layout(), {}).map((spec) => {
+      const index = seen.get(spec.agentId) ?? 0;
+      seen.set(spec.agentId, index + 1);
+      return { spec, agentId: spec.agentId, index };
+    });
+  });
+  const total = createMemo(() => picks().reduce((n, p) => n + p.count, 0));
+  const canRun = () =>
+    instruction().trim().length > 0 &&
+    total() > 0 &&
+    total() <= MAX_DOCUMENT_CANDIDATES &&
+    !documentStore.dispatching;
+  const canAnnotate = () => instruction().trim().length > 0 && hasPassage() && !saving();
+  const canSend = () => instruction().trim().length > 0 && !!project();
+  const askAgent = () => agents().find((a) => a.id === askAgentId()) ?? resumable()[0];
+
+  /** Notes and questions never touch the document: they are saved beside it. */
+  async function annotate() {
+    if (!canAnnotate()) return;
+    setSaving(true);
+    try {
+      const s = selection();
+      const anchor = createAnchor(
+        props.blocks,
+        s.startBlock,
+        s.endBlock,
+        activeDocumentPath() ?? project()?.documentPath ?? '',
+        documentStore.snapshot?.headSha ?? null,
+      );
+      const saved = await addDocumentAnnotation(
+        mode() === 'question' ? 'question' : 'note',
+        instruction().trim(),
+        anchor,
+        mode() === 'question' ? askAgent() : undefined,
+      );
+      if (saved) finish();
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  function submit() {
+    if (!isTask()) void annotate();
+    else if (oneshot()) void run();
+    else void send();
+  }
+
+  // Picking a passage or turning a bubble into a task brings the cursor here.
+  // The pane scrolls the passage into view; a focus scroll would fight it.
+  // The store merges a new selection into the old object, so track the range.
+  const pickedRange = () =>
+    props.selection ? `${props.selection.startBlock}-${props.selection.endBlock}` : null;
+  createEffect(
+    on(
+      () => [pickedRange(), documentStore.composerDraft] as const,
+      ([range, d]) => {
+        if (!range && !d) {
+          setFresh(false);
+          return;
+        }
+        if (d?.text) setInstruction(d.text);
+        if (d?.mode) setMode(d.mode);
+        setFresh(true);
+        requestAnimationFrame(() => textareaRef?.focus({ preventScroll: true }));
+      },
+    ),
+  );
+
+  function handleFocusOut(e: FocusEvent) {
+    if (!rootRef?.contains(e.relatedTarget as Node | null)) setFresh(false);
+  }
+
+  function without(counts: Record<string, number>, id: string): Record<string, number> {
+    return Object.fromEntries(Object.entries(counts).filter(([key]) => key !== id));
+  }
+
+  function toggleAgent(agent: AgentDef) {
+    setCounts((prev) => (prev[agent.id] ? without(prev, agent.id) : { ...prev, [agent.id]: 1 }));
+  }
+
+  function setChoice(slot: ChoiceSlot, patch: DocumentModelChoice, persist: boolean) {
+    const merged = { ...choice(slot), ...patch };
+    const next: DocumentModelChoice = {};
+    if (merged.model?.trim()) next.model = merged.model.trim();
+    if (merged.effort) next.effort = merged.effort;
+    setChoices((prev) => ({
+      ...prev,
+      [slot.agentId]: withModelChoice(prev[slot.agentId] ?? [], slot.index, next),
+    }));
+    if (persist) setDocumentModelChoice(slot.agentId, slot.index, next);
+  }
+
+  function bump(agent: AgentDef, e: MouseEvent) {
+    e.stopPropagation();
+    setCounts((prev) => ({ ...prev, [agent.id]: ((prev[agent.id] ?? 1) % MAX_PER_AGENT) + 1 }));
+  }
+
+  async function run() {
+    if (!canRun()) return;
+    try {
+      await dispatchDocumentRun(instruction().trim(), picks(), selection());
+      finish();
+    } catch (err) {
+      showNotification(errMessage(err));
+    }
+  }
+
+  /** Types the scoped instruction into the interactive session on the right. */
+  async function send() {
+    const p = project();
+    if (!canSend() || !p) return;
+    const text = buildInteractivePrompt(
+      activeDocumentPath() ?? p.documentPath ?? '',
+      selection(),
+      instruction(),
+    );
+    try {
+      await sendToDocumentAgent(documentAgentPtyId(p.id), text);
+      finish();
+    } catch (err) {
+      showNotification(errMessage(err));
+    }
+  }
+
+  /** Work was handed off: clear the draft and the passage, keep the popover. */
+  function finish() {
+    setInstruction('');
+    props.onClose();
+  }
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      props.onClose();
+      textareaRef?.blur();
+      return;
+    }
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      submit();
+    }
+  }
+
+  const verb = () => {
+    if (mode() === 'note') return 'save';
+    if (mode() === 'question') return 'ask';
+    return oneshot() ? 'run' : 'send';
+  };
+  const keys = () => `Enter to ${verb()} · Esc to clear`;
+
+  /** What the chosen mode does with the passage, said once beside the button. */
+  const hint = () => {
+    if (!isTask()) return 'Saved beside the document, never into it';
+    if (!oneshot()) return 'The agent edits your document directly.';
+    const cap = total() > MAX_DOCUMENT_CANDIDATES ? ` · max ${MAX_DOCUMENT_CANDIDATES}` : '';
+    return `Your document changes only when you accept a proposal.${cap}`;
+  };
+
+  const scopeLabel = () => {
+    const s = selection();
+    if (s.wholeDocument) return 'Whole document';
+    const lines =
+      s.startLine === s.endLine ? `line ${s.startLine}` : `lines ${s.startLine}–${s.endLine}`;
+    return s.heading ? `${lines} · ${s.heading}` : lines;
+  };
+
+  return (
+    <div
+      ref={rootRef}
+      class="docws-composer"
+      role="dialog"
+      aria-label="Run a task on the selected passage"
+      classList={{ 'is-scoped': hasPassage(), 'is-fresh': fresh() }}
+      onFocusOut={handleFocusOut}
+    >
+      <div class="docws-composer-head">
+        <span class="docws-mode-tabs" role="tablist" aria-label="What to do with the passage">
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'task'}
+            title="The agent edits your document directly"
+            onClick={() => setMode('task')}
+          >
+            <ActionIcon kind="task" />
+            Task
+          </button>
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'proposals'}
+            title="Agents draft candidates; review them before accepting"
+            onClick={() => setMode('proposals')}
+          >
+            <ActionIcon kind="proposals" />
+            Proposals
+          </button>
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'note'}
+            disabled={!hasPassage()}
+            title={
+              !hasPassage()
+                ? 'Notes attach to a passage: pick one first'
+                : 'Write a note beside this passage'
+            }
+            onClick={() => setMode('note')}
+          >
+            <ActionIcon kind="note" />
+            Note
+          </button>
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'question'}
+            disabled={!hasPassage()}
+            title={
+              !hasPassage()
+                ? 'Questions attach to a passage: pick one first'
+                : 'Ask an agent about this passage; the answer goes into a bubble'
+            }
+            onClick={() => setMode('question')}
+          >
+            <ActionIcon kind="question" />
+            Ask
+          </button>
+        </span>
+        <span class="docws-composer-scope" title={scopeLabel()}>
+          {scopeLabel()}
+        </span>
+        <Show when={hasPassage()}>
+          <button
+            type="button"
+            class="docws-composer-close"
+            aria-label="Clear the passage"
+            title="Back to the whole document · Esc"
+            onClick={() => props.onClose()}
+          >
+            <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+              <path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z" />
+            </svg>
+          </button>
+        </Show>
+      </div>
+      <Show when={hasPassage()}>
+        <div class="docws-composer-quote">{selection().quote.slice(0, 400)}</div>
+      </Show>
+      <textarea
+        ref={textareaRef}
+        aria-label="Instruction"
+        onKeyDown={handleKeyDown}
+        placeholder={
+          isTask()
+            ? hasPassage()
+              ? 'What should change here? e.g. find a simpler architecture, challenge these assumptions…'
+              : 'What should change in this document? Pick a passage to narrow it down.'
+            : mode() === 'note'
+              ? 'A note to yourself about this passage. It never changes the document.'
+              : 'A question about this passage. The answer lands in a bubble, not in the document.'
+        }
+        value={instruction()}
+        onInput={(e) => setInstruction(e.currentTarget.value)}
+      />
+      <Show when={mode() === 'question'}>
+        <div class="docws-agent-row" role="radiogroup" aria-label="Agent to ask">
+          <For each={agents().filter((a) => documentAgentSupport(a.id).headless)}>
+            {(agent) => (
+              <button
+                type="button"
+                class="docws-agent-chip"
+                role="radio"
+                aria-checked={askAgent()?.id === agent.id}
+                aria-pressed={askAgent()?.id === agent.id}
+                disabled={agent.available === false}
+                title={
+                  agent.available === false ? 'Not installed' : 'Reads the document, cannot edit it'
+                }
+                onClick={() => setAskAgentId(agent.id)}
+              >
+                {agent.name}
+              </button>
+            )}
+          </For>
+        </div>
+      </Show>
+      <details class="docws-proposal-options" style={{ display: oneshot() ? undefined : 'none' }}>
+        <summary>
+          Agents and models · {total()} candidate{total() === 1 ? '' : 's'}
+        </summary>
+        <label>
+          Main session{' '}
+          <select
+            class="docws-select"
+            value={mainAgentId()}
+            onChange={(e) => {
+              const next = e.currentTarget.value;
+              const prevMain = mainAgentId();
+              setDocumentMainAgent(next);
+              setCounts((prev) =>
+                prev[prevMain] && !prev[next]
+                  ? { ...without(prev, prevMain), [next]: prev[prevMain] }
+                  : prev,
+              );
+            }}
+          >
+            <For each={resumable()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
+          </select>
+        </label>
+        <div
+          class="docws-agent-row"
+          role="group"
+          aria-label="Agents"
+          style={{ display: oneshot() ? undefined : 'none' }}
+        >
+          <For each={agents()}>
+            {(agent) => {
+              const support = documentAgentSupport(agent.id);
+              const enabled = () => support.headless && agent.available !== false;
+              const count = () => counts()[agent.id] ?? 0;
+              const title = () =>
+                !support.headless
+                  ? 'No headless mode known for this agent'
+                  : agent.available === false
+                    ? 'Not installed'
+                    : agent.id === mainAgentId()
+                      ? 'Main session (resumes previous context)'
+                      : 'One-shot alternate';
+              return (
+                <div class="docws-agent-pick">
+                  <button
+                    type="button"
+                    class="docws-agent-chip"
+                    aria-pressed={count() > 0}
+                    disabled={!enabled()}
+                    title={title()}
+                    onClick={() => toggleAgent(agent)}
+                  >
+                    {agent.name}
+                    <Show when={agent.id === mainAgentId() && support.resume}>
+                      <span class="docws-main-badge">main</span>
+                    </Show>
+                  </button>
+                  <Show when={count() > 0}>
+                    <button
+                      type="button"
+                      class="docws-count-btn"
+                      aria-label={`Candidates from ${agent.name}: ${count()}`}
+                      title="Candidates from this agent (click to change)"
+                      onClick={(e) => bump(agent, e)}
+                    >
+                      ×{count()}
+                    </button>
+                  </Show>
+                </div>
+              );
+            }}
+          </For>
+        </div>
+        <Show when={oneshot() && slots().length > 0}>
+          <ModelRows slots={slots()} choice={choice} onChoice={setChoice} />
+        </Show>
+      </details>
+      <div class="docws-composer-footer">
+        <span class="docws-composer-hint">{hint()}</span>
+        <span>{keys()}</span>
+        <Show
+          when={isTask()}
+          fallback={
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm docws-btn-primary"
+              disabled={!canAnnotate()}
+              onClick={() => void annotate()}
+            >
+              {saving() ? 'Saving…' : mode() === 'note' ? 'Save note' : 'Ask'}
+            </button>
+          }
+        >
+          <Show
+            when={oneshot()}
+            fallback={
+              <button
+                type="button"
+                class="docws-btn docws-btn-sm docws-btn-primary"
+                disabled={!canSend()}
+                onClick={() => void send()}
+              >
+                Send to agent
+              </button>
+            }
+          >
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm docws-btn-primary"
+              disabled={!canRun()}
+              onClick={() => void run()}
+            >
+              {documentStore.dispatching ? 'Starting…' : 'Generate proposals'}
+            </button>
+          </Show>
+        </Show>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
new file mode 100644
index 000000000..3a296715e
--- /dev/null
+++ b/src/documents/RunsRail.tsx
@@ -0,0 +1,173 @@
+import { For, Show, createMemo, createSignal, onCleanup } from 'solid-js';
+import {
+  activeDocumentPath,
+  cancelDocumentRun,
+  candidateLogKey,
+  documentStore,
+  modelLabel,
+  openDocumentCompare,
+  rejectDocumentRun,
+} from './store';
+import { openCandidateOutput } from './workspace-ui';
+import { formatRelativeAge } from '../lib/relativeAge';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
+
+function scopeLabel(run: DocumentRunRecord): string {
+  const s = run.scope;
+  if (s.wholeDocument) return 'whole document';
+  const lines = s.startLine === s.endLine ? `L${s.startLine}` : `L${s.startLine}–${s.endLine}`;
+  return s.heading ? `${lines} · ${s.heading}` : lines;
+}
+
+/** What the run's outcome means for one candidate. */
+type CandidateVerdict = 'accepted' | 'passed-over' | 'rejected' | null;
+
+function candidateVerdict(run: DocumentRunRecord, c: DocumentCandidateRecord): CandidateVerdict {
+  if (run.acceptedCandidateId === c.id) return 'accepted';
+  if (!c.commitSha) return null;
+  if (run.status === 'accepted') return 'passed-over';
+  if (run.status === 'rejected') return 'rejected';
+  return null;
+}
+
+function candidateState(c: DocumentCandidateRecord, verdict: CandidateVerdict): string {
+  if (verdict === 'accepted') return 'accepted';
+  if (verdict === 'passed-over') return 'not chosen';
+  if (verdict === 'rejected') return 'rejected';
+  if (c.status === 'running') return 'working…';
+  if (c.status === 'done') return c.commitSha ? 'proposal ready' : 'no changes';
+  if (c.status === 'failed') return 'failed';
+  if (c.status === 'cancelled') return 'cancelled';
+  return 'interrupted';
+}
+
+function CandidateRow(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+  showLog: boolean;
+}) {
+  const lines = () => documentStore.logs[candidateLogKey(props.run.id, props.candidate.id)] ?? [];
+  const tail = () => lines().slice(-6);
+  const verdict = () => candidateVerdict(props.run, props.candidate);
+  return (
+    <div
+      class="docws-candidate"
+      classList={{ 'is-passed-over': verdict() === 'passed-over' || verdict() === 'rejected' }}
+      role="button"
+      tabIndex={0}
+      title="Show what this candidate printed"
+      onClick={() => openCandidateOutput({ runId: props.run.id, candidateId: props.candidate.id })}
+      onKeyDown={(e) => {
+        if (e.key !== 'Enter' && e.key !== ' ') return;
+        e.preventDefault();
+        openCandidateOutput({ runId: props.run.id, candidateId: props.candidate.id });
+      }}
+    >
+      <div class="docws-candidate-head">
+        <span class={`docws-dot docws-dot-${props.candidate.status}`} />
+        <span class="docws-candidate-label">{props.candidate.label}</span>
+        <span>{props.candidate.agentName}</span>
+        <Show when={props.candidate.model || props.candidate.effort}>
+          <span class="docws-candidate-model">{modelLabel(props.candidate)}</span>
+        </Show>
+        <Show when={props.candidate.isMain}>
+          <span class="docws-badge">main</span>
+        </Show>
+        <span class="docws-candidate-state" classList={{ 'is-accepted': verdict() === 'accepted' }}>
+          {candidateState(props.candidate, verdict())}
+        </span>
+      </div>
+      <Show when={props.candidate.error && props.candidate.status !== 'running'}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+      <Show when={props.showLog && tail().length > 0}>
+        <div class="docws-log">{tail().join('\n')}</div>
+      </Show>
+    </div>
+  );
+}
+
+/** The runs against the project's documents, newest first; each candidate opens its output. */
+export function RunsRail() {
+  const runs = createMemo(() =>
+    documentStore.runOrder.map((id) => documentStore.runs[id]).filter(Boolean),
+  );
+  const [nowMs, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
+
+  return (
+    <>
+      <Show when={runs().length === 0}>
+        <div class="docws-empty">
+          Select a passage in the document, describe what should change, and pick one or more
+          agents. Proposals show up here.
+        </div>
+      </Show>
+      <For each={runs()}>
+        {(run) => {
+          const proposals = () => run.candidates.filter((c) => c.commitSha).length;
+          const canCompare = () =>
+            (run.status === 'finished' || run.status === 'stale') && proposals() > 0;
+          return (
+            <div class="docws-run" data-run-id={run.id}>
+              <div class="docws-run-head">
+                <span class={`docws-badge docws-badge-${run.status}`}>{run.status}</span>
+                <span class="docws-run-meta" title={new Date(run.createdAt).toLocaleString()}>
+                  {formatRelativeAge(new Date(run.createdAt).getTime(), nowMs())}
+                </span>
+              </div>
+              <div class="docws-run-instruction" title={run.instruction}>
+                {run.instruction}
+              </div>
+              <div class="docws-run-meta" title={scopeLabel(run)}>
+                <Show when={run.documentPath !== activeDocumentPath()}>
+                  <span class="docws-run-doc">{run.documentPath} · </span>
+                </Show>
+                {scopeLabel(run)} · base {run.baseSha.slice(0, 7)}
+              </div>
+              <For each={run.candidates}>
+                {(candidate) => (
+                  <CandidateRow
+                    run={run}
+                    candidate={candidate}
+                    showLog={run.status === 'running'}
+                  />
+                )}
+              </For>
+              <div class="docws-run-actions">
+                <Show when={run.status === 'running'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm"
+                    onClick={() => void cancelDocumentRun(run.id)}
+                  >
+                    Cancel
+                  </button>
+                </Show>
+                <Show when={canCompare()}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-primary"
+                    onClick={() => openDocumentCompare(run.id)}
+                  >
+                    {proposals() > 1 ? `Compare ${proposals()}` : 'Review'}
+                  </button>
+                </Show>
+                <Show when={run.status === 'finished' || run.status === 'stale'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-danger"
+                    onClick={() => void rejectDocumentRun(run.id)}
+                  >
+                    {proposals() > 0 ? 'Reject all' : 'Dismiss'}
+                  </button>
+                </Show>
+              </div>
+            </div>
+          );
+        }}
+      </For>
+    </>
+  );
+}
diff --git a/src/documents/SourceDiff.tsx b/src/documents/SourceDiff.tsx
new file mode 100644
index 000000000..3288b8fac
--- /dev/null
+++ b/src/documents/SourceDiff.tsx
@@ -0,0 +1,43 @@
+import { For, Show } from 'solid-js';
+import { parseUnifiedDiff } from '../lib/unified-diff-parser';
+
+/** Compact unified-diff renderer for the source toggle in compare and history. */
+export function SourceDiff(props: { raw: string }) {
+  const files = () => parseUnifiedDiff(props.raw);
+  return (
+    <div class="docws-diff">
+      <Show when={files().length === 0}>
+        <div class="docws-empty">No source changes.</div>
+      </Show>
+      <For each={files()}>
+        {(file) => (
+          <div>
+            <For each={file.hunks}>
+              {(hunk) => (
+                <div>
+                  <div class="docws-diff-line docws-diff-hunk">
+                    @@ -{hunk.oldStart},{hunk.oldCount} +{hunk.newStart},{hunk.newCount} @@
+                  </div>
+                  <For each={hunk.lines}>
+                    {(line) => (
+                      <div
+                        class="docws-diff-line"
+                        classList={{
+                          'docws-diff-add': line.type === 'add',
+                          'docws-diff-remove': line.type === 'remove',
+                        }}
+                      >
+                        {line.type === 'add' ? '+' : line.type === 'remove' ? '-' : ' '}
+                        {line.content}
+                      </div>
+                    )}
+                  </For>
+                </div>
+              )}
+            </For>
+          </div>
+        )}
+      </For>
+    </div>
+  );
+}
diff --git a/src/documents/agent-terminal.ts b/src/documents/agent-terminal.ts
new file mode 100644
index 000000000..528ba442d
--- /dev/null
+++ b/src/documents/agent-terminal.ts
@@ -0,0 +1,59 @@
+/**
+ * Writes to the workspace's interactive agent the way the task prompt box
+ * does: focus-in, the text as one bracketed paste, then Enter after the TUI
+ * had time to take the paste.
+ */
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { pasteDelayMs } from '../store/tasks';
+import { setRailTab, workspaceUi } from './workspace-ui';
+
+const BRACKETED_PASTE_START = '\x1b[200~';
+const BRACKETED_PASTE_END = '\x1b[201~';
+const FOCUS_IN = '\x1b[I';
+/** How long to wait for the terminal to come up when it was not mounted yet. */
+const SPAWN_WAIT_MS = 15_000;
+const POLL_MS = 100;
+/** A CLI that just started needs a moment before it takes input. */
+const FRESH_START_DELAY_MS = 2_500;
+
+/** The pty id of a project's interactive agent; stable so the session can be
+ *  re-attached after the workspace was closed and reopened. */
+export function documentAgentPtyId(projectId: string): string {
+  return `doc-agent-${projectId}`;
+}
+
+/** The task id the pty is filed under; no task owns it. */
+export function documentAgentTaskId(projectId: string): string {
+  return `doc-agent-${projectId}`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Resolves once the terminal reports a live process, or throws after a wait. */
+async function waitForAgent(): Promise<void> {
+  const wasRunning = workspaceUi.agentRunning;
+  const deadline = Date.now() + SPAWN_WAIT_MS;
+  while (!workspaceUi.agentRunning) {
+    if (Date.now() > deadline) throw new Error('The agent terminal did not start.');
+    await sleep(POLL_MS);
+  }
+  // shortcut: a fixed settle delay for a fresh CLI — the task flow watches
+  // for a stable prompt instead; adopt that if prompts get swallowed.
+  if (!wasRunning) await sleep(FRESH_START_DELAY_MS);
+}
+
+/** Types `text` into the interactive agent, bringing its tab up first. */
+export async function sendToDocumentAgent(ptyId: string, text: string): Promise<void> {
+  setRailTab('agent');
+  await waitForAgent();
+  await invoke(IPC.WriteToAgent, { agentId: ptyId, data: FOCUS_IN });
+  await invoke(IPC.WriteToAgent, {
+    agentId: ptyId,
+    data: `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}`,
+  });
+  await sleep(pasteDelayMs(text));
+  await invoke(IPC.WriteToAgent, { agentId: ptyId, data: '\r' });
+}
diff --git a/src/documents/annotation-anchor.test.ts b/src/documents/annotation-anchor.test.ts
new file mode 100644
index 000000000..683f9ad22
--- /dev/null
+++ b/src/documents/annotation-anchor.test.ts
@@ -0,0 +1,236 @@
+import { describe, expect, it } from 'vitest';
+import { createAnchor, relocateAnchor } from './annotation-anchor';
+import type { DocumentBlock } from './markdown-blocks';
+
+function blocks(raws: string[], headings: Record<number, string> = {}): DocumentBlock[] {
+  let line = 1;
+  return raws.map((raw, index) => {
+    const startLine = line;
+    const endLine = line + raw.split('\n').length - 1;
+    line = endLine + 2;
+    return {
+      index,
+      type: headings[index] ? 'heading' : 'paragraph',
+      startLine,
+      endLine,
+      raw: raw + '\n\n',
+      html: '',
+      headingLevel: headings[index] ? 2 : undefined,
+      headingText: headings[index],
+    };
+  });
+}
+
+const doc = blocks(
+  ['# Title', 'Intro.', '## A', 'Same text.', 'Tail A.', '## B', 'Same text.', 'Tail B.'],
+  {
+    0: 'Title',
+    2: 'A',
+    5: 'B',
+  },
+);
+
+describe('createAnchor', () => {
+  it('captures quote, context and heading', () => {
+    const a = createAnchor(doc, 3, 4, 'd.md', 'abc1234');
+    expect(a.quote).toBe('Same text.\n\nTail A.');
+    expect(a.prefix).toBe('## A');
+    expect(a.suffix).toBe('## B');
+    expect(a.heading).toBe('A');
+    expect(a.startLine).toBe(doc[3].startLine);
+    expect(a.endLine).toBe(doc[4].endLine);
+  });
+});
+
+describe('relocateAnchor', () => {
+  it('finds a unique passage at its recorded lines', () => {
+    const a = createAnchor(doc, 1, 1, 'd.md', null);
+    expect(relocateAnchor(a, doc)).toEqual({ startBlock: 1, endBlock: 1, exact: true });
+  });
+
+  it('relocates when text above it changed', () => {
+    const a = createAnchor(doc, 4, 4, 'd.md', null);
+    const shifted = blocks(
+      ['# Title', 'Intro.', 'New paragraph.', '## A', 'Same text.', 'Tail A.', '## B'],
+      {
+        0: 'Title',
+        3: 'A',
+        6: 'B',
+      },
+    );
+    expect(relocateAnchor(a, shifted)).toEqual({ startBlock: 5, endBlock: 5, exact: false });
+  });
+
+  it('uses surroundings to pick between duplicate passages', () => {
+    const a = createAnchor(doc, 6, 6, 'd.md', null); // "Same text." under B
+    expect(relocateAnchor(a, doc)).toEqual({ startBlock: 6, endBlock: 6, exact: true });
+    // Even when the lines moved, the heading and neighbours still disambiguate.
+    const moved = blocks(
+      ['## A', 'Same text.', 'Tail A.', 'Extra.', '## B', 'Same text.', 'Tail B.'],
+      {
+        0: 'A',
+        4: 'B',
+      },
+    );
+    expect(relocateAnchor(a, moved)).toEqual({ startBlock: 5, endBlock: 5, exact: false });
+  });
+
+  it('detaches when the passage is gone or ambiguous', () => {
+    const a = createAnchor(doc, 4, 4, 'd.md', null);
+    expect(relocateAnchor(a, blocks(['Other.', 'Text.']))).toBeNull();
+    const ambiguous = blocks(['Same.', 'Same.']);
+    const b = createAnchor(ambiguous, 0, 0, 'd.md', null);
+    // Both copies have identical surroundings after an edit that removed their neighbours.
+    expect(
+      relocateAnchor({ ...b, prefix: 'x', suffix: 'y', startLine: 99, endLine: 99 }, ambiguous),
+    ).toBeNull();
+  });
+
+  it('ignores whitespace differences', () => {
+    const a = createAnchor(doc, 1, 1, 'd.md', null);
+    const reflowed = blocks(['# Title', 'Intro.  ']);
+    expect(relocateAnchor(a, reflowed)?.startBlock).toBe(1);
+  });
+});
+
+describe('relocateAnchor with blank lines inside a block', () => {
+  // A loose list keeps its blank line in `raw`, so the quote has more
+  // paragraphs than the passage has blocks.
+  const loose = blocks(['Intro.', '- one\n\n- two', 'Tail.']);
+
+  it('finds a passage whose own text contains a blank line', () => {
+    const anchor = createAnchor(loose, 1, 1, 'notes.md', null);
+    expect(relocateAnchor(anchor, loose)).toEqual({ startBlock: 1, endBlock: 1, exact: true });
+  });
+
+  it('still finds it after the lines above it moved', () => {
+    const anchor = createAnchor(loose, 1, 1, 'notes.md', null);
+    const moved = blocks(['Intro.', 'A new paragraph.', '- one\n\n- two', 'Tail.']);
+    expect(relocateAnchor(anchor, moved)).toEqual({ startBlock: 2, endBlock: 2, exact: false });
+  });
+});
+
+describe('relocateAnchor after the passage was reworded', () => {
+  // An accepted proposal rewrites the passage a note hangs on. Exact matching
+  // orphans the note; this is the case the product produces by design.
+  const before = blocks(['# Title', 'Intro.', '## A', 'The old goals text is vague and long.']);
+
+  it('follows a passage an agent sharpened', () => {
+    const a = createAnchor(before, 3, 3, 'd.md', null);
+    const after = blocks(['# Title', 'Intro.', '## A', 'The old goals text is vague and terse.']);
+    expect(relocateAnchor(a, after)).toEqual({ startBlock: 3, endBlock: 3, exact: true });
+  });
+
+  it('follows it when the lines moved too', () => {
+    const a = createAnchor(before, 3, 3, 'd.md', null);
+    const after = blocks([
+      '# Title',
+      'Intro.',
+      'A new paragraph.',
+      '## A',
+      'The old goals text is vague and terse.',
+    ]);
+    expect(relocateAnchor(a, after)).toEqual({ startBlock: 4, endBlock: 4, exact: false });
+  });
+
+  it('stays detached when the passage was replaced outright', () => {
+    const a = createAnchor(before, 3, 3, 'd.md', null);
+    const after = blocks(['# Title', 'Intro.', '## A', 'Ship the thing by Friday.']);
+    expect(relocateAnchor(a, after)).toBeNull();
+  });
+
+  it('stays detached when two passages are equally close', () => {
+    const source = blocks(['One two three four five.', 'One two three four six.']);
+    const a = createAnchor(source, 0, 0, 'd.md', null);
+    const after = blocks(['One two three four seven.', 'One two three four eight.']);
+    expect(relocateAnchor(a, after)).toBeNull();
+  });
+
+  it('prefers an exact match over a similar neighbour', () => {
+    const source = blocks(['Intro.', 'The goals are vague and long.', 'The goals are vague too.']);
+    const a = createAnchor(source, 2, 2, 'd.md', null);
+    expect(relocateAnchor(a, source)).toEqual({ startBlock: 2, endBlock: 2, exact: true });
+  });
+});
+
+describe('relocateAnchor and parallel passages', () => {
+  // The worst failure: the annotated passage is deleted and a sibling worded
+  // almost the same survives. Similarity alone hands the note to the sibling.
+  const api = blocks([
+    '# API',
+    'The API returns a list of users.',
+    'The API returns a list of groups.',
+  ]);
+
+  it('stays detached when the passage is deleted and its sibling survives', () => {
+    const a = createAnchor(api, 1, 1, 'api.md', null);
+    const after = blocks(['# API', 'The API returns a list of groups.']);
+    expect(relocateAnchor(a, after)).toBeNull();
+  });
+
+  it('still follows a rewording when the neighbour it recorded is still there', () => {
+    const a = createAnchor(api, 1, 1, 'api.md', null);
+    const after = blocks([
+      '# API',
+      'The API returns a list of active users.',
+      'The API returns a list of groups.',
+    ]);
+    // Its recorded lines still hold, so this counts as found where it was.
+    expect(relocateAnchor(a, after)).toEqual({ startBlock: 1, endBlock: 1, exact: true });
+  });
+});
+
+describe('relocateAnchor across section boundaries', () => {
+  // The residual gap the parallel-passage rule left open: the note's whole
+  // section is dropped, and the sibling section that survives is worded almost
+  // identically. Nothing in the surviving text says it is not the passage.
+  const sections = blocks(
+    [
+      '# API',
+      '## Users',
+      'The API returns a paginated list of items for the current account.',
+      '## Groups',
+      'The API returns a paginated list of items for the current team.',
+    ],
+    { 1: 'Users', 3: 'Groups' },
+  );
+  const onUsers = createAnchor(sections, 2, 2, 'api.md', null);
+
+  it('stays detached when a section is dropped and its twin survives', () => {
+    const after = blocks(
+      ['# API', '## Groups', 'The API returns a paginated list of items for the current team.'],
+      { 1: 'Groups' },
+    );
+    expect(relocateAnchor(onUsers, after)).toBeNull();
+  });
+
+  it('still follows the passage when its own section is only reworded', () => {
+    const after = blocks(
+      [
+        '# API',
+        '## Users',
+        'The API returns a paginated list of items for the signed-in account.',
+        '## Groups',
+        'The API returns a paginated list of items for the current team.',
+      ],
+      { 1: 'Users', 3: 'Groups' },
+    );
+    expect(relocateAnchor(onUsers, after)).toEqual({ startBlock: 2, endBlock: 2, exact: true });
+  });
+
+  it('follows the passage when its section moved below its twin', () => {
+    // The boundary is about which side of the recorded neighbours a run sits
+    // on, not about position in the file: reordered sections still resolve.
+    const after = blocks(
+      [
+        '# API',
+        '## Groups',
+        'The API returns a paginated list of items for the current team.',
+        '## Users',
+        'The API returns a paginated list of items for the signed-in account.',
+      ],
+      { 1: 'Groups', 3: 'Users' },
+    );
+    expect(relocateAnchor(onUsers, after)).toEqual({ startBlock: 4, endBlock: 4, exact: false });
+  });
+});
diff --git a/src/documents/annotation-anchor.ts b/src/documents/annotation-anchor.ts
new file mode 100644
index 000000000..2fed54472
--- /dev/null
+++ b/src/documents/annotation-anchor.ts
@@ -0,0 +1,268 @@
+import type { DocumentAnchor } from './types';
+import { blockRangeText, nearestHeading, type DocumentBlock } from './markdown-blocks';
+
+/** Characters of neighbouring text kept on either side of an anchor. */
+const CONTEXT_CHARS = 160;
+
+function normalize(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/** Anchors a block range in the current document version. */
+export function createAnchor(
+  blocks: readonly DocumentBlock[],
+  startBlock: number,
+  endBlock: number,
+  path: string,
+  baseSha: string | null,
+): DocumentAnchor {
+  const start = Math.max(0, Math.min(startBlock, endBlock));
+  const end = Math.min(blocks.length - 1, Math.max(startBlock, endBlock));
+  const before = blocks[start - 1]?.raw ?? '';
+  const after = blocks[end + 1]?.raw ?? '';
+  return {
+    path,
+    baseSha,
+    startLine: blocks[start].startLine,
+    endLine: blocks[end].endLine,
+    quote: blockRangeText(blocks, start, end),
+    prefix: normalize(before).slice(-CONTEXT_CHARS),
+    suffix: normalize(after).slice(0, CONTEXT_CHARS),
+    heading: nearestHeading(blocks, start),
+  };
+}
+
+export interface AnchorLocation {
+  startBlock: number;
+  endBlock: number;
+  /** True when the anchor was found at its recorded lines; false when relocated. */
+  exact: boolean;
+}
+
+/** Word bigrams, or the words themselves when the text is too short for one. */
+function grams(text: string): string[] {
+  const words = text.split(' ').filter(Boolean);
+  if (words.length < 2) return words;
+  const out: string[] = [];
+  for (let i = 0; i < words.length - 1; i++) out.push(`${words[i]} ${words[i + 1]}`);
+  return out;
+}
+
+function gramCounts(grams: readonly string[]): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const g of grams) counts.set(g, (counts.get(g) ?? 0) + 1);
+  return counts;
+}
+
+/** The quoted passage, measured once for the whole search. */
+interface Quote {
+  counts: ReadonlyMap<string, number>;
+  size: number;
+  length: number;
+}
+
+function readQuote(text: string): Quote | null {
+  const own = grams(text);
+  if (own.length === 0) return null;
+  return { counts: gramCounts(own), size: own.length, length: text.length };
+}
+
+/**
+ * Sørensen–Dice over word bigrams: cheap, and stable under the rewording that
+ * is this product's normal case rather than its edge case. An agent that
+ * sharpens a sentence must not orphan the note attached to it.
+ *
+ * The quote's own gram counts are built once and reused across every candidate
+ * run, because the search scores O(blocks x MAX_RUN) of them and rebuilding
+ * the map each time dominated the cost on long documents.
+ */
+function similarity(quote: Quote, candidate: readonly string[]): number {
+  if (quote.size === 0 || candidate.length === 0) return 0;
+  const used = new Map<string, number>();
+  let shared = 0;
+  for (const g of candidate) {
+    const already = used.get(g) ?? 0;
+    if (already < (quote.counts.get(g) ?? 0)) {
+      shared++;
+      used.set(g, already + 1);
+    }
+  }
+  return (2 * shared) / (quote.size + candidate.length);
+}
+
+/**
+ * A neighbour shorter than this is a separator or a bare marker, which two
+ * unrelated passages can carry by accident.
+ */
+const BOUNDARY_MIN = 6;
+
+/** Below this the passage is a different passage, not a reworded one. */
+const FUZZY_FLOOR = 0.5;
+/** How far ahead of the next unrelated passage the winner must be. */
+const FUZZY_MARGIN = 0.1;
+/** Blocks a passage may have grown to; bounds the search on long documents. */
+const MAX_RUN = 6;
+/** Lines within which a passage is taken to be the one that was annotated. */
+const NEAR_LINES = 20;
+
+interface Scored extends AnchorLocation {
+  score: number;
+}
+
+/** A candidate span of blocks, with its text run together. */
+interface Run {
+  start: number;
+  end: number;
+  text: string;
+}
+
+interface Search {
+  anchor: DocumentAnchor;
+  blocks: readonly DocumentBlock[];
+  keys: readonly string[];
+  quote: Quote;
+}
+
+/**
+ * True when a run lies on the far side of one of the anchor's own boundaries.
+ * An anchor records the block before its passage and the block after it, so
+ * those two blocks bracket where the passage can be: a run reaching the
+ * recorded suffix has passed the end, and one reaching back to the recorded
+ * prefix has not yet arrived at the start. Each is scanned over the run plus
+ * the block on the side the neighbour does *not* belong on, so finding the
+ * suffix at the run's own start — or the prefix just after its end — is what
+ * it is: the passage next door, worded like the one the note was written
+ * against. Without this a deleted passage hands its note to a surviving
+ * sibling, which is the worst thing anchoring can do.
+ */
+function crossesBoundary(anchor: DocumentAnchor, keys: readonly string[], run: Run): boolean {
+  const { prefix, suffix } = anchor;
+  if (suffix && suffix.length >= BOUNDARY_MIN) {
+    for (let i = Math.max(run.start - 1, 0); i <= run.end; i++) {
+      if (keys[i].startsWith(suffix)) return true;
+    }
+  }
+  if (!prefix || prefix.length < BOUNDARY_MIN) return false;
+  for (let i = run.start; i <= Math.min(run.end + 1, keys.length - 1); i++) {
+    if (keys[i].endsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/** A run's score, or null when it is no plausible home for the anchor. */
+function scoreRun(search: Search, run: Run): number | null {
+  const { anchor, blocks, keys } = search;
+  if (crossesBoundary(anchor, keys, run)) return null;
+  const base = similarity(search.quote, grams(run.text));
+  if (base < FUZZY_FLOOR) return null;
+  let score = base;
+  if (anchor.prefix && (keys[run.start - 1] ?? '').endsWith(anchor.prefix)) score += 0.05;
+  if (anchor.suffix && (keys[run.end + 1] ?? '').startsWith(anchor.suffix)) score += 0.05;
+  if (anchor.heading && nearestHeading(blocks, run.start) === anchor.heading) score += 0.03;
+  if (Math.abs(blocks[run.start].startLine - anchor.startLine) <= NEAR_LINES) score += 0.02;
+  return score;
+}
+
+/** The best run beginning at a block, grown until it outgrows the quote. */
+function bestRunFrom(search: Search, start: number): Scored | null {
+  const { anchor, blocks, keys } = search;
+  let text = '';
+  let top: Scored | null = null;
+  for (let end = start; end < blocks.length && end - start < MAX_RUN; end++) {
+    const key = keys[end];
+    if (key) text = text ? `${text} ${key}` : key;
+    if (!text) continue;
+    // A run twice the quote's length is no longer the same passage.
+    if (text.length > search.quote.length * 2 && end > start) break;
+    const score = scoreRun(search, { start, end, text });
+    if (score === null || (top && score <= top.score)) continue;
+    const exact =
+      blocks[start].startLine === anchor.startLine && blocks[end].endLine === anchor.endLine;
+    top = { startBlock: start, endBlock: end, exact, score };
+  }
+  return top;
+}
+
+/**
+ * The best relocation by text similarity when nothing matches verbatim.
+ * Neighbours, heading and the recorded lines break ties, the way they do for
+ * an exact match; anything below the floor, or too close to an unrelated
+ * passage, stays detached.
+ */
+function relocateFuzzy(
+  anchor: DocumentAnchor,
+  blocks: readonly DocumentBlock[],
+  keys: readonly string[],
+): AnchorLocation | null {
+  const quote = readQuote(normalize(anchor.quote));
+  if (!quote) return null;
+  const search: Search = { anchor, blocks, keys, quote };
+
+  const best: Scored[] = [];
+  for (let i = 0; i < blocks.length; i++) {
+    const top = bestRunFrom(search, i);
+    if (top) best.push(top);
+  }
+  if (best.length === 0) return null;
+  best.sort((a, b) => b.score - a.score);
+  const winner = best[0];
+  // Runs that overlap the winner are the same passage measured differently;
+  // only a separate passage scoring nearly as well makes this ambiguous.
+  const rival = best.find((c) => c.startBlock > winner.endBlock || c.endBlock < winner.startBlock);
+  if (rival && winner.score - rival.score < FUZZY_MARGIN) return null;
+  return { startBlock: winner.startBlock, endBlock: winner.endBlock, exact: winner.exact };
+}
+
+/**
+ * Finds an anchor in the current blocks. Matches the quoted blocks by text,
+ * then — because agents reword the passages people annotate — by similarity;
+ * when the same passage appears more than once, the surrounding text and the
+ * heading decide. Returns null rather than guessing: a detached bubble is
+ * honest, a misplaced one is not.
+ */
+export function relocateAnchor(
+  anchor: DocumentAnchor,
+  blocks: readonly DocumentBlock[],
+): AnchorLocation | null {
+  if (blocks.length === 0) return null;
+  // The quote is the blocks' own text run together, and a single block can
+  // hold a blank line of its own (a loose list, a fenced snippet, an HTML
+  // element). Splitting the quote on blank lines would therefore count more
+  // pieces than there are blocks and match nothing, so grow a run of blocks
+  // until it reproduces the quote instead.
+  const wanted = normalize(anchor.quote);
+  if (!wanted) return null;
+  const keys = blocks.map((b) => normalize(b.raw));
+
+  const candidates: AnchorLocation[] = [];
+  for (let i = 0; i < blocks.length; i++) {
+    let text = '';
+    for (let end = i; end < blocks.length; end++) {
+      const key = keys[end];
+      if (key) text = text ? `${text} ${key}` : key;
+      if (text.length > wanted.length) break;
+      if (text !== wanted) continue;
+      const exact =
+        blocks[i].startLine === anchor.startLine && blocks[end].endLine === anchor.endLine;
+      candidates.push({ startBlock: i, endBlock: end, exact });
+      break;
+    }
+  }
+  if (candidates.length === 0) return relocateFuzzy(anchor, blocks, keys);
+  if (candidates.length === 1) return candidates[0];
+
+  const score = (c: AnchorLocation): number => {
+    let s = 0;
+    if (c.exact) s += 4;
+    const before = keys[c.startBlock - 1] ?? '';
+    const after = keys[c.endBlock + 1] ?? '';
+    if (anchor.prefix && before.endsWith(anchor.prefix)) s += 2;
+    if (anchor.suffix && after.startsWith(anchor.suffix)) s += 2;
+    if (anchor.heading && nearestHeading(blocks, c.startBlock) === anchor.heading) s += 1;
+    return s;
+  };
+  const ranked = candidates.map((c) => ({ c, s: score(c) })).sort((a, b) => b.s - a.s);
+  // Two equally good matches: refuse to pick one.
+  if (ranked[0].s === ranked[1].s) return null;
+  return ranked[0].c;
+}
diff --git a/src/documents/block-edit.test.ts b/src/documents/block-edit.test.ts
new file mode 100644
index 000000000..351ecb36f
--- /dev/null
+++ b/src/documents/block-edit.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it, vi } from 'vitest';
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+import { renderDocument } from './render-document';
+import { blockEditRange } from './block-edit';
+
+describe('blockEditRange', () => {
+  it('preserves CRLF separators and selects the correct repeated paragraph', async () => {
+    const source = '# Plan\r\n\r\nSame.\r\n\r\nSame.\r\n';
+    const { blocks } = await renderDocument(source);
+    const range = blockEditRange(source, blocks[2]);
+    expect(source.slice(range.startOffset, range.endOffset)).toBe('Same.');
+    expect(source.slice(0, range.startOffset) + 'Changed.' + source.slice(range.endOffset)).toBe(
+      '# Plan\r\n\r\nSame.\r\n\r\nChanged.\r\n',
+    );
+  });
+
+  it('selects one HTML block without touching siblings on the same line', async () => {
+    const source = '<!doctype html><html><body><p>Same.</p><p>Same.</p></body></html>';
+    const { blocks } = await renderDocument(source);
+    const range = blockEditRange(source, blocks[1]);
+    expect(
+      source.slice(0, range.startOffset) + '<p>Changed.</p>' + source.slice(range.endOffset),
+    ).toBe('<!doctype html><html><body><p>Same.</p><p>Changed.</p></body></html>');
+  });
+
+  it('refuses blocks from a different render', async () => {
+    const { blocks } = await renderDocument('# Before');
+    expect(() => blockEditRange('# After', blocks[0])).toThrow(/changed/);
+  });
+});
diff --git a/src/documents/block-edit.ts b/src/documents/block-edit.ts
new file mode 100644
index 000000000..f5183d0bd
--- /dev/null
+++ b/src/documents/block-edit.ts
@@ -0,0 +1,27 @@
+import { normalizeSource, type DocumentBlock } from './markdown-blocks';
+
+/** Map renderer offsets back to the original file without changing its line endings. */
+export function blockEditRange(
+  source: string,
+  block: DocumentBlock,
+): {
+  startOffset: number;
+  endOffset: number;
+} {
+  const { startOffset, endOffset } = block;
+  if (
+    startOffset === undefined ||
+    endOffset === undefined ||
+    normalizeSource(source).slice(startOffset, endOffset) !== block.raw.replace(/\n+$/, '')
+  ) {
+    throw new Error('The passage changed. Select it again to edit.');
+  }
+  const originalOffset = (offset: number): number => {
+    let original = 0;
+    for (let normalized = 0; normalized < offset; normalized++, original++) {
+      if (source[original] === '\r' && source[original + 1] === '\n') original++;
+    }
+    return original;
+  };
+  return { startOffset: originalOffset(startOffset), endOffset: originalOffset(endOffset) };
+}
diff --git a/src/documents/block-merge.test.ts b/src/documents/block-merge.test.ts
new file mode 100644
index 000000000..bc80f2bd6
--- /dev/null
+++ b/src/documents/block-merge.test.ts
@@ -0,0 +1,263 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../lib/shiki-highlighter', () => ({
+  highlightLines: async (code: string) => code.split('\n').map((l) => `<span>${l}</span>`),
+}));
+// DOMPurify needs a DOM; sanitization is markdown-blocks' concern, not this module's.
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+
+import { diffBlocks, renderDocumentBlocks, type DocumentBlock } from './markdown-blocks';
+import {
+  blockHunks,
+  composeAcceptedDocument,
+  composeVerifiedDocument,
+  expectedBlockKeys,
+  hunkKind,
+  hunkLabel,
+  hunkLeadBlocks,
+  type BlockHunk,
+} from './block-merge';
+
+async function pair(baseSource: string, candidateSource: string) {
+  const baseBlocks = await renderDocumentBlocks(baseSource);
+  const candidateBlocks = await renderDocumentBlocks(candidateSource);
+  const hunks = blockHunks(diffBlocks(baseBlocks, candidateBlocks));
+  return { baseSource, baseBlocks, candidateSource, candidateBlocks, hunks };
+}
+
+function compose(
+  parts: Awaited<ReturnType<typeof pair>>,
+  accepted: readonly number[],
+): string | null {
+  return composeAcceptedDocument({ ...parts, accepted: new Set(accepted) });
+}
+
+const BASE = ['# Title', '', 'One.', '', 'Two.', '', 'Three.', ''].join('\n');
+
+describe('blockHunks', () => {
+  it('pairs each rewritten run of base blocks with the candidate run replacing it', async () => {
+    const { hunks } = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three!', ''].join('\n'),
+    );
+    expect(hunks).toEqual<BlockHunk[]>([
+      { id: 0, baseStart: 1, baseEnd: 2, candStart: 1, candEnd: 2 },
+      { id: 1, baseStart: 3, baseEnd: 4, candStart: 3, candEnd: 4 },
+    ]);
+    expect(hunks.map(hunkKind)).toEqual(['rewrite', 'rewrite']);
+  });
+
+  it('reports an insertion as an empty base run and a deletion as an empty candidate run', async () => {
+    const inserted = await pair(
+      BASE,
+      ['# Title', '', 'One.', '', 'New.', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+    expect(inserted.hunks.map(hunkKind)).toEqual(['insertion']);
+    const deleted = await pair(BASE, ['# Title', '', 'One.', '', 'Three.', ''].join('\n'));
+    expect(deleted.hunks.map(hunkKind)).toEqual(['deletion']);
+  });
+});
+
+describe('composeAcceptedDocument', () => {
+  it('returns the base unchanged when every hunk is declined', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two!', '', 'Three!', ''].join('\n'),
+    );
+    expect(compose(parts, [])).toBe(BASE);
+  });
+
+  it('returns the candidate when every hunk is kept', async () => {
+    const candidate = ['# Title', '', 'One!', '', 'Two!', '', 'Three!', ''].join('\n');
+    const parts = await pair(BASE, candidate);
+    expect(compose(parts, [0, 1, 2])).toBe(candidate);
+  });
+
+  it('takes only the hunks that were kept', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three!', ''].join('\n'),
+    );
+    expect(parts.hunks).toHaveLength(2);
+    expect(compose(parts, [1])).toBe(
+      ['# Title', '', 'One.', '', 'Two.', '', 'Three!', ''].join('\n'),
+    );
+    expect(compose(parts, [0])).toBe(
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+  });
+
+  it('drops a deleted paragraph without leaving a hole, and restores it when declined', async () => {
+    const parts = await pair(BASE, ['# Title', '', 'One.', '', 'Three.', ''].join('\n'));
+    expect(compose(parts, [0])).toBe(['# Title', '', 'One.', '', 'Three.', ''].join('\n'));
+    expect(compose(parts, [])).toBe(BASE);
+  });
+
+  it('drops a deleted last paragraph without leaving a hole', async () => {
+    const parts = await pair(BASE, ['# Title', '', 'One.', '', 'Two.', ''].join('\n'));
+    expect(parts.hunks.map(hunkKind)).toEqual(['deletion']);
+    expect(compose(parts, [0])).toBe(['# Title', '', 'One.', '', 'Two.', ''].join('\n'));
+  });
+
+  it('separates an inserted paragraph from its neighbours', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One.', '', 'New.', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+    expect(compose(parts, [0])).toBe(
+      ['# Title', '', 'One.', '', 'New.', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+  });
+
+  it('appends a paragraph added at the end', async () => {
+    const parts = await pair(BASE, [...BASE.split('\n').slice(0, -1), '', 'Four.', ''].join('\n'));
+    expect(parts.hunks.map(hunkKind)).toEqual(['insertion']);
+    expect(compose(parts, [0])).toContain('Three.\n\nFour.');
+  });
+
+  it('keeps the base line endings', async () => {
+    const crlfBase = BASE.replace(/\n/g, '\r\n');
+    const parts = await pair(
+      crlfBase,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+    expect(compose(parts, [0])).toBe(
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three.', ''].join('\r\n'),
+    );
+  });
+
+  it('refuses an insertion whose anchor block drifted, instead of appending it', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One.', '', 'Inserted.', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+    expect(parts.hunks.map(hunkKind)).toEqual(['insertion']);
+    const drifted = parts.baseBlocks.map((b, i) =>
+      i === 2 ? { ...b, startOffset: (b.startOffset ?? 0) + 1 } : b,
+    );
+    expect(
+      composeAcceptedDocument({ ...parts, baseBlocks: drifted, accepted: new Set([0]) }),
+    ).toBeNull();
+  });
+
+  it('refuses to compose when a block no longer matches its recorded offsets', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three.', ''].join('\n'),
+    );
+    const drifted: DocumentBlock[] = parts.baseBlocks.map((b, i) =>
+      i === 1 ? { ...b, startOffset: (b.startOffset ?? 0) + 3 } : b,
+    );
+    expect(
+      composeAcceptedDocument({ ...parts, baseBlocks: drifted, accepted: new Set([0]) }),
+    ).toBeNull();
+  });
+});
+
+describe('hunkLeadBlocks', () => {
+  it('gives each hunk the block its toggle sits on', async () => {
+    const { hunks, candidateBlocks } = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three!', ''].join('\n'),
+    );
+    const leads = hunkLeadBlocks(hunks, candidateBlocks.length);
+    expect([...(leads?.keys() ?? [])]).toEqual([1, 3]);
+  });
+
+  it('hangs a deletion on the block that follows it', async () => {
+    const { hunks, candidateBlocks } = await pair(
+      BASE,
+      ['# Title', '', 'One.', '', 'Three.', ''].join('\n'),
+    );
+    const leads = hunkLeadBlocks(hunks, candidateBlocks.length);
+    expect([...(leads?.keys() ?? [])]).toEqual([2]);
+  });
+
+  // Two deletions, the second ending the document, both want the last block.
+  // Dropping one would leave a change with no way to decline it.
+  it('stacks two deletions that land on the same block', async () => {
+    const parts = await pair(BASE, ['# Title', '', 'Two.', ''].join('\n'));
+    expect(parts.hunks.map(hunkKind)).toEqual(['deletion', 'deletion']);
+    const leads = hunkLeadBlocks(parts.hunks, parts.candidateBlocks.length);
+    expect([...(leads?.values() ?? [])].flat().map((h) => h.id)).toEqual([0, 1]);
+    // Both remain declinable, and declining both restores the base.
+    expect(compose(parts, [])).toBe(BASE);
+    expect(compose(parts, [0, 1])).toBe(['# Title', '', 'Two.', ''].join('\n'));
+  });
+
+  it('refuses when a hunk has nowhere to hang its toggle', () => {
+    expect(
+      hunkLeadBlocks([{ id: 0, baseStart: 0, baseEnd: 1, candStart: 0, candEnd: 0 }], 0),
+    ).toBeNull();
+  });
+});
+
+describe('splicing into a single-newline seam', () => {
+  // A heading and its paragraph sit on consecutive lines. Replacing the
+  // heading with a list used to fuse the paragraph into the last bullet.
+  const seamBase = ['# Doc', '', '## Open questions', 'Should we ship on Friday?', ''].join('\n');
+  const seamCandidate = [
+    '# Doc',
+    '',
+    '- Ship date?',
+    '- Owner?',
+    '',
+    'Should we ship on Friday?',
+    '',
+  ].join('\n');
+
+  it('keeps the neighbouring paragraph a block of its own', async () => {
+    const parts = await pair(seamBase, seamCandidate);
+    expect(parts.hunks).toHaveLength(1);
+    const merged = compose(parts, [0]);
+    expect(merged).toBe(seamCandidate);
+    expect((await renderDocumentBlocks(merged ?? '')).map((b) => b.raw.trim())).toEqual([
+      '# Doc',
+      '- Ship date?\n- Owner?',
+      'Should we ship on Friday?',
+    ]);
+  });
+
+  it('verifies the result re-reads as the blocks the reader picked', async () => {
+    const parts = await pair(seamBase, seamCandidate);
+    await expect(composeVerifiedDocument({ ...parts, accepted: new Set([0]) })).resolves.toBe(
+      seamCandidate,
+    );
+    await expect(composeVerifiedDocument({ ...parts, accepted: new Set<number>() })).resolves.toBe(
+      seamBase,
+    );
+  });
+
+  it('refuses rather than writing a document it cannot verify', async () => {
+    const parts = await pair(seamBase, seamCandidate);
+    const drifted = parts.baseBlocks.map((b, i) =>
+      i === 1 ? { ...b, endOffset: (b.endOffset ?? 0) - 2 } : b,
+    );
+    await expect(
+      composeVerifiedDocument({ ...parts, baseBlocks: drifted, accepted: new Set([0]) }),
+    ).resolves.toBeNull();
+  });
+});
+
+describe('expectedBlockKeys', () => {
+  it('lists base blocks for declined hunks and candidate blocks for kept ones', async () => {
+    const parts = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two.', '', 'Three!', ''].join('\n'),
+    );
+    expect(expectedBlockKeys({ ...parts, accepted: new Set([0]) })).toEqual([
+      '# Title',
+      'One!',
+      'Two.',
+      'Three.',
+    ]);
+  });
+});
+
+describe('hunkLabel', () => {
+  it('names the passage a removal drops, since its toggle sits elsewhere', async () => {
+    const parts = await pair(BASE, ['# Title', '', 'One.', '', 'Three.', ''].join('\n'));
+    expect(hunkLabel(parts.hunks[0], parts.baseBlocks)).toBe('Include this removal: “Two.”');
+    expect(hunkLabel(parts.hunks[0])).toBe('Include this removal');
+  });
+});
diff --git a/src/documents/block-merge.ts b/src/documents/block-merge.ts
new file mode 100644
index 000000000..da461ceae
--- /dev/null
+++ b/src/documents/block-merge.ts
@@ -0,0 +1,257 @@
+import {
+  normalizeSource,
+  renderDocumentBlocks,
+  type BlockChange,
+  type DocumentBlock,
+} from './markdown-blocks';
+
+/**
+ * One reviewable change: a run of base blocks a candidate replaced by a run of
+ * its own. Either run may be empty — an empty base run is an insertion, an
+ * empty candidate run a deletion. Hunks are the unit of partial acceptance,
+ * because a paragraph is the smallest thing a reader decides about.
+ */
+export interface BlockHunk {
+  id: number;
+  /** Half-open ranges of block indices. */
+  baseStart: number;
+  baseEnd: number;
+  candStart: number;
+  candEnd: number;
+}
+
+/** The text a block is compared by, matching `diffBlocks`. */
+function key(block: DocumentBlock): string {
+  return block.raw.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Groups a block diff into hunks. `diffBlocks` marks matched blocks `same` in
+ * both arrays and in the same order, so walking the two together pairs the
+ * unmatched runs between matches.
+ */
+export function blockHunks(diff: { base: BlockChange[]; candidate: BlockChange[] }): BlockHunk[] {
+  const hunks: BlockHunk[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < diff.base.length || j < diff.candidate.length) {
+    if (diff.base[i] === 'same' && diff.candidate[j] === 'same') {
+      i++;
+      j++;
+      continue;
+    }
+    const baseStart = i;
+    const candStart = j;
+    while (i < diff.base.length && diff.base[i] !== 'same') i++;
+    while (j < diff.candidate.length && diff.candidate[j] !== 'same') j++;
+    if (i === baseStart && j === candStart) {
+      // Neither side advanced: the arrays disagree about their matches, which
+      // diffBlocks cannot produce. Step over it rather than spin forever.
+      i++;
+      j++;
+      continue;
+    }
+    hunks.push({ id: hunks.length, baseStart, baseEnd: i, candStart, candEnd: j });
+  }
+  return hunks;
+}
+
+export type HunkKind = 'rewrite' | 'insertion' | 'deletion';
+
+export function hunkKind(hunk: BlockHunk): HunkKind {
+  if (hunk.baseStart === hunk.baseEnd) return 'insertion';
+  if (hunk.candStart === hunk.candEnd) return 'deletion';
+  return 'rewrite';
+}
+
+/** Enough of a passage to recognise it, on one line. */
+function snippet(text: string): string {
+  return text.length > 48 ? `${text.slice(0, 47)}…` : text;
+}
+
+/**
+ * What a toggle does, for its tooltip and screen readers. A deletion names the
+ * passage it drops: its checkbox sits on a block that follows it, so without
+ * the quote there is nothing on screen tying the two together.
+ */
+export function hunkLabel(hunk: BlockHunk, baseBlocks?: readonly DocumentBlock[]): string {
+  const kind = hunkKind(hunk);
+  if (kind === 'insertion') return 'Include this new passage';
+  if (kind === 'rewrite') return 'Include this rewrite';
+  const removed = baseBlocks?.[hunk.baseStart] ? key(baseBlocks[hunk.baseStart]) : '';
+  return removed ? `Include this removal: “${snippet(removed)}”` : 'Include this removal';
+}
+
+/**
+ * The block that carries a hunk's toggle in the candidate column. A rewrite or
+ * an insertion owns its own blocks; a deletion has none, so it hangs on the
+ * block that follows it — the base column is where the dropped passage is
+ * shown. Returns null only when the candidate has no blocks at all.
+ */
+export function hunkLeadBlock(hunk: BlockHunk, candidateBlockCount: number): number | null {
+  if (hunk.candStart < hunk.candEnd) return hunk.candStart;
+  if (hunk.candStart < candidateBlockCount) return hunk.candStart;
+  return candidateBlockCount > 0 ? candidateBlockCount - 1 : null;
+}
+
+/**
+ * Maps each block to the hunks whose toggles sit on it. Two deletions can land
+ * on one block — the last block of the document takes every deletion that ends
+ * it — so a block carries a list rather than a single hunk; dropping the
+ * second would leave a change the reader cannot decline.
+ */
+export function hunkLeadBlocks(
+  hunks: readonly BlockHunk[],
+  candidateBlockCount: number,
+): Map<number, BlockHunk[]> | null {
+  const leads = new Map<number, BlockHunk[]>();
+  for (const hunk of hunks) {
+    const index = hunkLeadBlock(hunk, candidateBlockCount);
+    if (index === null) return null;
+    const at = leads.get(index);
+    if (at) at.push(hunk);
+    else leads.set(index, [hunk]);
+  }
+  return leads;
+}
+
+/** A block's exact span in the normalized source, verified against its text. */
+function spanOf(source: string, block: DocumentBlock | undefined): [number, number] | null {
+  if (!block || block.startOffset === undefined || block.endOffset === undefined) return null;
+  if (source.slice(block.startOffset, block.endOffset) !== block.raw.replace(/\n+$/, ''))
+    return null;
+  return [block.startOffset, block.endOffset];
+}
+
+/** The candidate text a hunk contributes; empty for a deletion. */
+function candidateText(
+  source: string,
+  blocks: readonly DocumentBlock[],
+  hunk: BlockHunk,
+): string | null {
+  if (hunk.candStart === hunk.candEnd) return '';
+  const first = spanOf(source, blocks[hunk.candStart]);
+  const last = spanOf(source, blocks[hunk.candEnd - 1]);
+  if (!first || !last) return null;
+  return source.slice(first[0], last[1]);
+}
+
+/**
+ * The base span a hunk replaces. A deletion also swallows one separator, so
+ * dropping a paragraph does not leave a hole of blank lines behind.
+ */
+function baseSpan(
+  source: string,
+  blocks: readonly DocumentBlock[],
+  hunk: BlockHunk,
+): [number, number] | null {
+  if (hunk.baseStart === hunk.baseEnd) {
+    // Insertion: a zero-width span before the block it precedes.
+    const at = spanOf(source, blocks[hunk.baseStart]);
+    if (at) return [at[0], at[0]];
+    // Only an insertion past the last block may fall back to the end. A block
+    // that failed verification must refuse, not silently append elsewhere.
+    if (hunk.baseStart < blocks.length) return null;
+    const last = spanOf(source, blocks[blocks.length - 1]);
+    return last ? [last[1], last[1]] : null;
+  }
+  const first = spanOf(source, blocks[hunk.baseStart]);
+  const last = spanOf(source, blocks[hunk.baseEnd - 1]);
+  if (!first || !last) return null;
+  if (hunk.candStart !== hunk.candEnd) return [first[0], last[1]];
+  const after = spanOf(source, blocks[hunk.baseEnd]);
+  if (after) return [first[0], after[0]];
+  const before = spanOf(source, blocks[hunk.baseStart - 1]);
+  return before ? [before[1], last[1]] : [first[0], last[1]];
+}
+
+/**
+ * Markdown separates blocks by a blank line, but not always by two newlines: a
+ * heading and its paragraph, or a paragraph and the list under it, sit on
+ * consecutive lines. Splicing a different kind of block into such a seam would
+ * fuse it with its neighbour — a list swallowing the paragraph after it — so
+ * each seam of a spliced passage is opened to a blank line.
+ */
+function endBlank(accumulated: string): string {
+  if (accumulated.trim() === '') return accumulated;
+  return `${accumulated.replace(/\n*$/, '')}\n\n`;
+}
+
+function startBlank(rest: string): string {
+  if (rest.trim() === '') return rest;
+  return `\n\n${rest.replace(/^\n*/, '')}`;
+}
+
+export interface ComposeArgs {
+  baseSource: string;
+  baseBlocks: readonly DocumentBlock[];
+  candidateSource: string;
+  candidateBlocks: readonly DocumentBlock[];
+  hunks: readonly BlockHunk[];
+  /** Hunk ids the reader kept; the rest fall back to the base text. */
+  accepted: ReadonlySet<number>;
+}
+
+/** The blocks the reader chose, in order: the yardstick the result must meet. */
+export function expectedBlockKeys(args: ComposeArgs): string[] {
+  const out: string[] = [];
+  let i = 0;
+  for (const hunk of args.hunks) {
+    for (; i < hunk.baseStart; i++) out.push(key(args.baseBlocks[i]));
+    if (args.accepted.has(hunk.id)) {
+      for (let c = hunk.candStart; c < hunk.candEnd; c++) out.push(key(args.candidateBlocks[c]));
+    } else {
+      for (let b = hunk.baseStart; b < hunk.baseEnd; b++) out.push(key(args.baseBlocks[b]));
+    }
+    i = hunk.baseEnd;
+  }
+  for (; i < args.baseBlocks.length; i++) out.push(key(args.baseBlocks[i]));
+  return out;
+}
+
+/**
+ * Builds the document the reader chose: the base with every accepted hunk
+ * replaced by the candidate's version of it. Returns null when a block's
+ * recorded offsets no longer describe its text, so the caller can fall back to
+ * accepting the candidate whole rather than write something it cannot verify.
+ */
+export function composeAcceptedDocument(args: ComposeArgs): string | null {
+  const base = normalizeSource(args.baseSource);
+  const candidate = normalizeSource(args.candidateSource);
+  let merged = '';
+  let cursor = 0;
+  let openSeam = false;
+  for (const hunk of args.hunks) {
+    if (!args.accepted.has(hunk.id)) continue;
+    const span = baseSpan(base, args.baseBlocks, hunk);
+    const text = candidateText(candidate, args.candidateBlocks, hunk);
+    if (!span || text === null) return null;
+    // Hunks are disjoint and ordered; anything else means the diff and the
+    // offsets disagree, and guessing would corrupt the document.
+    if (span[0] < cursor) return null;
+    const lead = base.slice(cursor, span[0]);
+    merged += openSeam ? startBlank(lead) : lead;
+    // A deletion opens no seam: it already swallowed the separator it left.
+    openSeam = text !== '';
+    if (text !== '') merged = `${endBlank(merged)}${text}`;
+    cursor = span[1];
+  }
+  const tail = base.slice(cursor);
+  merged += openSeam ? startBlank(tail) : tail;
+  return args.baseSource.includes('\r\n') ? merged.replace(/\n/g, '\r\n') : merged;
+}
+
+/**
+ * The composed document, but only if it re-reads as the blocks the reader
+ * picked. Splicing text is not the same as splicing structure — markdown can
+ * fuse two blocks that were separate in both sources — so the result is parsed
+ * back and compared before anyone is allowed to commit it.
+ */
+export async function composeVerifiedDocument(args: ComposeArgs): Promise<string | null> {
+  const merged = composeAcceptedDocument(args);
+  if (merged === null) return null;
+  const got = (await renderDocumentBlocks(merged)).map(key);
+  const want = expectedBlockKeys(args);
+  if (got.length !== want.length || got.some((k, i) => k !== want[i])) return null;
+  return merged;
+}
diff --git a/src/documents/documents-styles.test.ts b/src/documents/documents-styles.test.ts
new file mode 100644
index 000000000..debdc45a9
--- /dev/null
+++ b/src/documents/documents-styles.test.ts
@@ -0,0 +1,42 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { describe, expect, it } from 'vitest';
+
+const css = readFileSync(resolve(__dirname, './documents.css'), 'utf8');
+
+/** The declarations of one top-level rule, by its exact selector. */
+function rule(selector: string): string {
+  const start = css.indexOf(`\n${selector} {`);
+  expect(start, `no rule for ${selector}`).toBeGreaterThanOrEqual(0);
+  return css.slice(start, css.indexOf('}', start));
+}
+
+/* The annotation popover opens on hover, so the path from the marker to the
+   panel is part of its behaviour: these guard the two rules that make the
+   panel reachable with a mouse at all. */
+describe('annotation popover styles', () => {
+  it('hangs the popover straight off the marker, with nothing to cross', () => {
+    const pop = rule('.docws-marker-pop');
+
+    expect(pop).toMatch(/top:\s*100%/);
+    expect(pop).not.toMatch(/margin-top:/);
+  });
+
+  it('holds the popover open briefly after the pointer leaves, but not long', () => {
+    const pop = rule('.docws-marker-pop');
+
+    // The grace lets a pointer that cuts the corner get back in; while it runs
+    // the panel is still a hit target over the prose, so it stays short.
+    const grace = pop.match(/visibility 0s linear (\d*\.?\d+)s/);
+    expect(grace, 'popover has no delayed visibility').not.toBeNull();
+    expect(Number(grace?.[1])).toBeGreaterThan(0);
+    expect(Number(grace?.[1])).toBeLessThanOrEqual(0.25);
+  });
+
+  it('lets the timestamp give way so the buttons beside it keep their row', () => {
+    const time = rule('.docws-bubble-time');
+
+    expect(time).toMatch(/min-width:\s*0/);
+    expect(time).toMatch(/text-overflow:\s*ellipsis/);
+  });
+});
diff --git a/src/documents/documents.css b/src/documents/documents.css
new file mode 100644
index 000000000..abfd2f3e0
--- /dev/null
+++ b/src/documents/documents.css
@@ -0,0 +1,2017 @@
+/* Document workspace overlay — uses the app's design tokens. */
+
+.docws-overlay {
+  position: fixed;
+  inset: 0;
+  /* Below every Dialog (1000+) so the project editor, settings and confirms
+     opened from inside the workspace render on top of it. */
+  z-index: 950;
+  background: var(--bg);
+  display: flex;
+  flex-direction: column;
+  font-family: var(--font-ui);
+  color: var(--fg);
+}
+
+.docws-header {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 10px 18px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-elevated);
+  flex-shrink: 0;
+  min-width: 0;
+  user-select: none;
+}
+
+/* The header itself is the window drag region. Carve out every possible
+   control so the entire remaining background behaves consistently. These
+   declarations also protect controls that overlap the native title strip. */
+.docws-header button,
+.docws-header input,
+.docws-header select,
+.docws-header textarea,
+.docws-header a {
+  -webkit-app-region: no-drag;
+}
+
+/* The mac traffic lights are drawn over the top-left corner of the window;
+   the title moves right so they never sit on it. */
+.docws-overlay.is-mac .docws-header {
+  padding-left: 86px;
+}
+
+.docws-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 15px;
+  min-width: 0;
+}
+
+.docws-title svg {
+  color: var(--accent);
+  flex-shrink: 0;
+}
+
+.docws-open-editor {
+  padding: 4px;
+  flex-shrink: 0;
+}
+
+.docws-subtitle {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--fg-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+}
+
+/* Branch, head and working-tree state ride in the header instead of taking a
+   strip of their own. */
+.docws-head-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-subtle);
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--border-subtle);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.docws-head-chip svg {
+  flex-shrink: 0;
+}
+
+.docws-head-chip.is-warning {
+  color: var(--warning);
+  border-color: color-mix(in srgb, var(--warning) 45%, transparent);
+}
+
+.docws-banner {
+  padding: 6px 18px;
+  font-size: 12px;
+  border-bottom: 1px solid var(--border-subtle);
+  flex-shrink: 0;
+}
+
+.docws-banner-error {
+  background: color-mix(in srgb, var(--error) 12%, transparent);
+  color: var(--error);
+  border-color: color-mix(in srgb, var(--error) 40%, transparent);
+}
+
+.docws-tabs {
+  display: flex;
+  gap: 2px;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 2px;
+  margin-left: auto;
+}
+
+.docws-tab {
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 5px 12px;
+  color: var(--fg-muted);
+  font-family: var(--font-ui);
+  font-size: 13px;
+  cursor: pointer;
+}
+
+/* Tabs select, the composer's target toggle checks; both read the same way. */
+.docws-tab[aria-selected='true'],
+.docws-tab[aria-checked='true'] {
+  background: var(--bg-selected);
+  color: var(--fg);
+}
+
+/* Note and Ask are off until a passage is picked: say so instead of
+   swallowing the click. The button's title explains what to do. */
+.docws-tab:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.docws-tab .docws-count {
+  margin-left: 6px;
+  font-size: 11px;
+  padding: 1px 6px;
+  border-radius: 999px;
+  background: var(--accent);
+  color: var(--accent-text);
+}
+
+.docws-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 6px 12px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 13px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.docws-btn:hover:not(:disabled) {
+  background: var(--bg-hover);
+}
+
+.docws-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.docws-btn-primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--accent-text);
+  font-weight: 600;
+}
+
+.docws-btn-primary:hover:not(:disabled) {
+  background: var(--accent-hover);
+}
+
+.docws-btn-danger {
+  color: var(--error);
+}
+
+.docws-btn-sm {
+  padding: 3px 8px;
+  font-size: 12px;
+}
+
+.docws-body {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+}
+
+.docws-main {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  position: relative;
+}
+
+/* Both columns fill the cells of the resizable split. */
+.docws-body .docws-main,
+.docws-body .docws-rail {
+  height: 100%;
+}
+
+.docws-rail {
+  border-left: 1px solid var(--border);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  background: var(--bg-elevated);
+}
+
+.docws-rail-tabs {
+  margin: 10px 12px 0;
+  align-self: flex-start;
+}
+
+.docws-rail-list {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.docws-count.is-attention {
+  background: var(--warning);
+  color: var(--bg);
+}
+
+/* ── Interactive agent ── */
+
+.docws-agent-pane {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-agent-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+.docws-agent-status {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+.docws-agent-status.is-waiting {
+  color: var(--warning);
+  font-weight: 600;
+}
+
+.docws-agent-term {
+  flex: 1;
+  min-height: 0;
+  position: relative;
+  background: var(--bg);
+}
+
+.docws-decisions {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border);
+  background: color-mix(in srgb, var(--review) 8%, transparent);
+}
+
+.docws-decision {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+}
+
+.docws-decision-text {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ── File tree ── */
+
+.docws-files {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.docws-tree {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  padding: 8px 0;
+}
+
+.docws-tree-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  border: none;
+  background: transparent;
+  color: var(--fg-muted);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  line-height: 1.4;
+  padding: 3px 8px;
+  cursor: pointer;
+  text-align: left;
+  white-space: nowrap;
+}
+
+.docws-tree-row:hover {
+  background: var(--bg-hover);
+}
+
+.docws-tree-row.is-document {
+  color: var(--fg);
+}
+
+.docws-tree-row[aria-current='true'] {
+  background: var(--bg-selected);
+  color: var(--fg);
+}
+
+.docws-tree-icon {
+  width: 14px;
+  display: inline-flex;
+  justify-content: center;
+  flex-shrink: 0;
+  color: var(--fg-subtle);
+}
+
+.docws-tree-icon svg {
+  width: 12px;
+  height: 12px;
+}
+
+.docws-tree-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.docws-rail-title {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--fg-subtle);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.docws-empty {
+  color: var(--fg-subtle);
+  font-size: 13px;
+  padding: 8px 0;
+}
+
+/* ── Rendered document ── */
+
+/* The document column does not scroll itself: the prose scrolls inside it, so
+   the composer can float over the column instead of pushing the prose down. */
+.docws-doc-main {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.docws-scroll {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  /* The composer covers the foot of the column, so a passage scrolled into
+     view has to clear it. The prose reserves as much at its end. */
+  scroll-padding-bottom: 260px;
+}
+
+.docws-doc {
+  position: relative;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 28px 44px 280px;
+}
+
+/* A page gets the whole column, top to bottom, the way a browser gives it the viewport. */
+.docws-doc.is-page {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  min-height: 100%;
+  max-width: none;
+  padding: 0;
+}
+
+.docws-doc.is-page .docws-page {
+  flex: 1;
+  padding-bottom: 280px;
+}
+
+/* Kept mounted while previewing so blocks, annotations and scroll position
+   survive the toggle; re-rendering them on every switch is wasted work. */
+.docws-scroll.is-hidden {
+  display: none;
+}
+
+/* White canvas is what a browser gives a page by default; a page that sets its
+   own background paints over it. */
+.docws-html-preview {
+  flex: 1;
+  width: 100%;
+  min-height: 0;
+  border: 0;
+  background: #fff;
+}
+
+.docws-content:not(.docws-page) .doc-block {
+  position: relative;
+  border-radius: var(--radius-sm);
+  margin: 0 -10px;
+  padding: 2px 10px;
+  transition: background 0.1s ease;
+}
+
+.docws-content.docws-selectable:not(.docws-page) .doc-block:hover:not(.is-selected) {
+  background: color-mix(in srgb, var(--accent) 6%, transparent);
+}
+
+/* The picked passage is ringed on all four sides, not just barred on the left:
+   a tint alone is easy to lose next to a changed or scoped block. The blocks of
+   one passage sit edge to edge, so each shared edge drops out and the range
+   reads as a single outline instead of a stack of boxes. */
+.docws-content:not(.docws-page) .doc-block.is-selected {
+  --sel-edge-top: inset 0 2px 0 var(--accent);
+  --sel-edge-bottom: inset 0 -2px 0 var(--accent);
+  background: color-mix(in srgb, var(--accent) 16%, transparent);
+  box-shadow:
+    inset 3px 0 0 var(--accent),
+    inset -2px 0 0 var(--accent),
+    var(--sel-edge-top),
+    var(--sel-edge-bottom);
+}
+
+.docws-content:not(.docws-page) .doc-block.is-selected + .doc-block.is-selected {
+  --sel-edge-top: 0 0 transparent;
+}
+
+.docws-content:not(.docws-page) .doc-block.is-selected:has(+ .doc-block.is-selected) {
+  --sel-edge-bottom: 0 0 transparent;
+}
+
+.docws-content:not(.docws-page) .doc-block.is-changed {
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  box-shadow: inset 3px 0 0 var(--warning);
+}
+
+.docws-content:not(.docws-page) .doc-block.is-added {
+  background: var(--diff-add-bg);
+  box-shadow: inset 3px 0 0 var(--success);
+}
+
+.docws-content:not(.docws-page) .doc-block.is-removed {
+  background: var(--diff-remove-bg);
+  box-shadow: inset 3px 0 0 var(--error);
+  text-decoration: line-through;
+  text-decoration-color: color-mix(in srgb, var(--error) 60%, transparent);
+}
+
+.docws-content:not(.docws-page) .doc-block.is-scope {
+  box-shadow: inset 3px 0 0 var(--border-focus);
+}
+
+.docws-content:not(.docws-page) .doc-block > :first-child {
+  margin-top: 0.2em;
+}
+
+.docws-content:not(.docws-page) .doc-block > :last-child {
+  margin-bottom: 0.2em;
+}
+
+/* A whole HTML page keeps its own look: browser defaults plus its stylesheet
+   on the light canvas a browser would give it, not the app's markdown theme. */
+/* `medium` rather than 16px: the browser's own default size, which it resolves
+   again for monospace text, so code and pre come out at the size a page gets
+   in a browser instead of a size too big. */
+.docws-page {
+  background: #fff;
+  color: #000;
+  color-scheme: light;
+  font:
+    medium 'Times New Roman',
+    Times,
+    serif;
+  line-height: normal;
+}
+
+/* The body margin a browser starts from; the page's own body rules replace it. */
+.docws-page-body {
+  margin: 8px;
+}
+
+/* The page's own elements are the blocks, so nothing here may move them:
+   outlines mark hover, selection and changes without touching the layout. */
+.docws-page .doc-block {
+  outline-offset: 4px;
+}
+
+/* Anchoring and corners the page can still overrule: a layer loses to every
+   unlayered rule whatever its specificity, so a sticky header stays sticky and
+   a rounded code block keeps its own radius. Blocks the page says nothing
+   about get the anchor the app's absolutely placed markers need. */
+@layer page-block {
+  .docws-page .doc-block {
+    position: relative;
+    border-radius: 2px;
+  }
+}
+
+.docws-page.docws-selectable .doc-block:hover:not(.is-selected) {
+  outline: 1px dashed color-mix(in srgb, var(--accent) 60%, transparent);
+}
+
+/* Thicker than the marks for change, plus a soft halo: a page's own elements
+   often carry a border of their own, and the picked one has to win against it.
+   The halo is a shadow, so it still costs the page no layout. */
+.docws-page .doc-block.is-selected {
+  outline: 3px solid var(--accent);
+  box-shadow: 0 0 0 9px color-mix(in srgb, var(--accent) 18%, transparent);
+}
+
+.docws-page .doc-block.is-changed {
+  outline: 2px solid var(--warning);
+}
+
+.docws-page .doc-block.is-added {
+  outline: 2px solid var(--success);
+}
+
+.docws-page .doc-block.is-removed {
+  outline: 2px solid var(--error);
+  text-decoration: line-through;
+  text-decoration-color: color-mix(in srgb, var(--error) 60%, transparent);
+}
+
+.docws-page .doc-block.is-scope {
+  outline: 2px dashed var(--border-focus);
+}
+
+/* Inside a heading on a white page rather than in the app's gutter. */
+.docws-page .docws-section-btn {
+  left: auto;
+  right: 2px;
+  top: 50%;
+  transform: translateY(-50%);
+  font: 13px var(--font-ui);
+  color: #8a8a8a;
+}
+
+.docws-page .docws-section-btn:hover {
+  color: #222;
+  border-color: #ccc;
+  background: #f0f0f0;
+}
+
+.docws-section-btn {
+  position: absolute;
+  left: -30px;
+  top: 0.55em;
+  width: 22px;
+  height: 22px;
+  border-radius: var(--radius-xs);
+  border: 1px solid transparent;
+  background: transparent;
+  color: var(--fg-subtle);
+  font-size: 13px;
+  cursor: pointer;
+  opacity: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.doc-block:hover .docws-section-btn,
+.docws-section-btn:focus-visible {
+  opacity: 1;
+}
+
+.docws-section-btn:hover {
+  color: var(--fg);
+  border-color: var(--border);
+  background: var(--bg-elevated);
+}
+
+/* ── Block hover toolbar ── */
+
+/* Clear of the block, not on its top edge: the bar used to cover the first
+   line, so a click meant for the passage hit an icon instead. It rests in the
+   gap above, which the column's top padding leaves room for on the first
+   block too. */
+.docws-block-actions {
+  position: absolute;
+  bottom: 100%;
+  right: 6px;
+  z-index: 5;
+  display: inline-flex;
+  gap: 2px;
+  padding: 2px;
+  border-radius: var(--radius-sm);
+  border: 1px solid var(--border);
+  background: var(--bg-elevated);
+  box-shadow: var(--shadow-pop);
+  opacity: 0;
+  transition: opacity 0.1s ease;
+  /* Invisible, so it must also be intangible: it hangs over the block above,
+     where a transparent icon would otherwise swallow that block's clicks. */
+  pointer-events: none;
+}
+
+/* A beat after the pointer arrives, so sweeping down the prose does not flash
+   a toolbar on every block; gone at once when it leaves. The bar sits directly
+   on the block's top edge, so the pointer reaches it without crossing a gap. */
+.doc-block:hover .docws-block-actions,
+.docws-block-actions:focus-within {
+  opacity: 1;
+  pointer-events: auto;
+  transition-delay: 0.12s;
+}
+
+/* The picked blocks have the composer up on them; their toolbars would only
+   repeat what it offers. The other blocks keep theirs, so one click moves
+   the composer to a different block. */
+.doc-block.is-selected .docws-block-actions {
+  display: none;
+}
+
+/* A page's § button and markers sit on the right; the toolbar takes the left. */
+.docws-page .docws-block-actions {
+  right: auto;
+  left: 0;
+  font-family: var(--font-ui);
+}
+
+.docws-block-action {
+  position: relative;
+  width: 22px;
+  height: 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: none;
+  border-radius: var(--radius-xs);
+  background: transparent;
+  color: var(--fg-muted);
+  cursor: pointer;
+  padding: 0;
+}
+
+.docws-block-action:hover,
+.docws-block-action:focus-visible {
+  color: var(--fg);
+  background: var(--bg-selected);
+}
+
+.docws-block-action:active {
+  transform: translateY(1px);
+}
+
+/* Editing the source is a different kind of act from briefing an agent. */
+.docws-block-action[data-kind='edit'] {
+  margin-left: 5px;
+}
+
+.docws-block-action[data-kind='edit']::before {
+  content: '';
+  position: absolute;
+  left: -4px;
+  top: 4px;
+  bottom: 4px;
+  width: 1px;
+  background: var(--border);
+}
+
+/* The label as an instant tooltip: the native one takes a second, and the
+   glyphs alone do not tell task from note. Right-aligned so the long labels
+   grow into the column, never past its edge. */
+.docws-block-action::after {
+  content: attr(aria-label);
+  position: absolute;
+  right: 0;
+  top: calc(100% + 6px);
+  padding: 3px 7px;
+  border-radius: var(--radius-xs);
+  border: 1px solid var(--border);
+  background: var(--bg-elevated);
+  color: var(--fg);
+  font: 11px/1.3 var(--font-ui);
+  white-space: nowrap;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.1s ease;
+}
+
+.docws-block-action:hover::after,
+.docws-block-action:focus-visible::after {
+  opacity: 1;
+  transition-delay: 0.3s;
+}
+
+.docws-page .docws-block-action::after {
+  right: auto;
+  left: 0;
+}
+
+.docws-content:not(.docws-page) table {
+  border-collapse: collapse;
+  margin: 0.6em 0;
+  font-size: 0.92em;
+}
+
+.docws-content:not(.docws-page) th,
+.docws-content:not(.docws-page) td {
+  border: 1px solid var(--border);
+  padding: 4px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+
+.docws-content:not(.docws-page) th {
+  background: color-mix(in srgb, var(--fg) 5%, transparent);
+}
+
+.docws-content:not(.docws-page) blockquote {
+  margin: 0.6em 0;
+  padding: 0.2em 0 0.2em 1em;
+  border-left: 3px solid var(--border);
+  color: var(--fg-muted);
+}
+
+.docws-content:not(.docws-page) img {
+  max-width: 100%;
+}
+
+.docws-content .mermaid-block {
+  padding: 8px;
+  background: var(--bg-input);
+  border-radius: var(--radius-sm);
+  overflow-x: auto;
+  white-space: pre;
+  font-family: var(--font-mono);
+  font-size: 12px;
+}
+
+.docws-content .mermaid-block.mermaid-rendered {
+  white-space: normal;
+  font-family: inherit;
+  font-size: inherit;
+}
+
+.docws-toolbar {
+  position: sticky;
+  top: 0;
+  z-index: 3;
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  padding: 8px 18px;
+  /* `--bg` is a gradient in the default theme, which color-mix cannot take. */
+  background: color-mix(in srgb, var(--bg-elevated) 85%, transparent);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid var(--border-subtle);
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+/* ── Composer ── */
+
+/* The composer floats over the foot of the column. Only the panel itself takes
+   the pointer, so the prose around it stays selectable. */
+.docws-composer-layer {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  justify-content: center;
+  padding: 0 24px 18px;
+  pointer-events: none;
+  z-index: 8;
+}
+
+/* Kept mounted while previewing, so a half-typed instruction survives the
+   toggle; the sandboxed render has no passage to act on. */
+.docws-composer-layer.is-hidden {
+  display: none;
+}
+
+/* Hung off the picked passage; the pane sets `top`. */
+.docws-composer-layer.is-anchored {
+  padding-bottom: 0;
+}
+
+.docws-composer {
+  pointer-events: auto;
+  width: min(760px, 100%);
+  max-height: min(60vh, 560px);
+  overflow-y: auto;
+  background: var(--island-bg);
+  border: 1px solid color-mix(in srgb, var(--accent) 40%, var(--border));
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-pop);
+  padding: 12px 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  transition:
+    opacity 160ms ease,
+    border-color 160ms ease;
+}
+
+/* Always present, so it steps back while the reader is in the prose and
+   comes forward as soon as the pointer or the cursor reaches it. */
+.docws-composer:not(:focus-within):not(:hover):not(.is-fresh) {
+  opacity: 0.55;
+  border-color: var(--border);
+}
+
+/* What to do, and where: the tabs, the passage, and a way out. Never wraps;
+   a long heading in the scope gives way instead. */
+.docws-composer-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--fg-subtle);
+}
+
+/* What the instruction will act on. A shade louder than the rest of the
+   header: it is the one thing here that changes as you pick. */
+.docws-composer-scope {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  color: var(--fg-muted);
+  font-weight: 500;
+}
+
+.docws-composer-close {
+  flex: none;
+  width: 24px;
+  height: 24px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--fg-muted);
+  cursor: pointer;
+}
+
+.docws-composer-close:hover,
+.docws-composer-close:focus-visible {
+  color: var(--fg);
+  background: var(--bg-hover);
+}
+
+/* The passage sits right above the popover, so one line is a reminder of
+   what was picked, not a copy of it. */
+.docws-composer-quote {
+  font-size: 12px;
+  color: var(--fg-muted);
+  border-left: 3px solid var(--accent);
+  padding-left: 8px;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-family: var(--font-mono);
+}
+
+.docws-composer textarea {
+  width: 100%;
+  min-height: 64px;
+  resize: vertical;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 8px 10px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 14px;
+  line-height: 1.5;
+  outline: none;
+  box-sizing: border-box;
+}
+
+.docws-composer textarea:focus {
+  border-color: var(--border-focus);
+}
+
+.docws-proposal-options {
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+.docws-proposal-options summary {
+  cursor: pointer;
+  padding: 4px 0;
+}
+
+.docws-proposal-options[open] > :not(summary) {
+  margin-top: 10px;
+}
+
+.docws-proposal-options > label {
+  display: block;
+}
+
+.docws-refinement {
+  margin-top: 8px;
+}
+
+.docws-refinement p {
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+.docws-refinement textarea {
+  min-height: 72px;
+  margin-bottom: 8px;
+}
+
+.docws-block-editor {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+  color: var(--fg);
+}
+
+.docws-block-editor h2,
+.docws-block-editor p {
+  margin: 0;
+}
+
+.docws-block-editor h2 {
+  font-size: 18px;
+}
+
+.docws-block-editor p {
+  font-size: 13px;
+}
+
+.docws-block-editor textarea {
+  min-height: 180px;
+  max-height: 55vh;
+  resize: vertical;
+  padding: 12px;
+  background: var(--bg-input);
+  color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  font-family: var(--font-mono);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.docws-agent-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  align-items: center;
+}
+
+.docws-agent-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 4px 6px 4px 10px;
+  color: var(--fg-muted);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.docws-agent-pick {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.docws-agent-chip[aria-pressed='true'] {
+  border-color: var(--accent);
+  color: var(--fg);
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+
+.docws-agent-chip:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.docws-agent-chip .docws-main-badge {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.docws-count-btn {
+  min-width: 22px;
+  height: 20px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  background: var(--bg-elevated);
+  color: var(--fg);
+  font-size: 11px;
+  font-family: var(--font-mono);
+  cursor: pointer;
+  padding: 0 5px;
+}
+
+.docws-composer-footer {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--fg-subtle);
+}
+
+.docws-model-rows {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.docws-model-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--fg-subtle);
+}
+
+.docws-model-agent {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 130px;
+  color: var(--fg-muted);
+}
+
+.docws-model-input {
+  width: 12ch;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 3px 6px;
+}
+
+.docws-model-input:focus {
+  outline: none;
+  border-color: var(--border-focus);
+}
+
+/* Pushes what follows to the far end of its row. Every use is inside a flex
+   row, so this holds wherever the class is put. */
+.docws-spacer {
+  flex: 1;
+}
+
+/* What the chosen mode does. It takes the slack and gives way first, so a
+   long sentence never pushes the send button onto a line of its own. */
+.docws-composer-hint {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.docws-composer-footer > :not(.docws-composer-hint) {
+  flex: none;
+}
+
+.docws-select {
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 3px 6px;
+}
+
+/* ── Runs rail ── */
+
+.docws-run {
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--task-panel-bg);
+  padding: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  font-size: 12px;
+}
+
+.docws-run-head {
+  display: flex;
+  justify-content: space-between;
+  gap: 8px;
+  align-items: baseline;
+}
+
+.docws-run-instruction {
+  font-size: 13px;
+  color: var(--fg);
+  line-height: 1.4;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.docws-run-meta {
+  color: var(--fg-subtle);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.docws-badge {
+  display: inline-block;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 1px 6px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  color: var(--fg-muted);
+  white-space: nowrap;
+}
+
+.docws-badge-running {
+  color: var(--info);
+  border-color: color-mix(in srgb, var(--info) 50%, transparent);
+}
+.docws-badge-finished {
+  color: var(--review);
+  border-color: color-mix(in srgb, var(--review) 50%, transparent);
+}
+.docws-badge-accepted {
+  color: var(--success);
+  border-color: color-mix(in srgb, var(--success) 50%, transparent);
+}
+.docws-badge-rejected,
+.docws-badge-failed,
+.docws-badge-stale {
+  color: var(--error);
+  border-color: color-mix(in srgb, var(--error) 50%, transparent);
+}
+
+.docws-candidate {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 6px 8px;
+  border-radius: var(--radius-sm);
+  background: var(--bg-input);
+}
+
+.docws-candidate[role='button'] {
+  cursor: pointer;
+}
+
+.docws-candidate[role='button']:hover,
+.docws-candidate[role='button']:focus-visible {
+  outline: 1px solid var(--border-focus);
+  outline-offset: -1px;
+}
+
+.docws-run-doc {
+  color: var(--fg-muted);
+}
+
+/* ── Candidate output ── */
+
+.docws-output {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.docws-output-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+.docws-output-body {
+  margin: 0;
+  min-height: 200px;
+  max-height: 60vh;
+  overflow: auto;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--fg);
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 10px;
+}
+
+.docws-candidate-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.docws-candidate-label {
+  font-family: var(--font-mono);
+  font-weight: 600;
+}
+
+.docws-candidate-model {
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+.docws-candidate-state {
+  margin-left: auto;
+  color: var(--fg-subtle);
+}
+
+.docws-candidate-state.is-accepted {
+  color: var(--success);
+  font-weight: 600;
+}
+
+.docws-candidate.is-passed-over {
+  opacity: 0.55;
+}
+
+.docws-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--fg-subtle);
+  flex-shrink: 0;
+}
+.docws-dot-running {
+  background: var(--info);
+  animation: docws-pulse 1.2s ease-in-out infinite;
+}
+.docws-dot-done {
+  background: var(--success);
+}
+.docws-dot-failed,
+.docws-dot-interrupted,
+.docws-dot-cancelled {
+  background: var(--error);
+}
+
+@keyframes docws-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+
+.docws-log {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-muted);
+  max-height: 120px;
+  overflow-y: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+  line-height: 1.4;
+}
+
+.docws-run-actions {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+/* ── Compare ── */
+
+.docws-compare {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+/* The compare modal: a head with the run picker and the size toggle, and the
+   compare view filling the rest. */
+.docws-compare-dialog {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-compare-dialog-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--border);
+}
+
+.docws-compare-dialog-body {
+  flex: 1;
+  min-height: 0;
+}
+
+.docws-compare-bar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 18px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--fg-muted);
+  flex-wrap: wrap;
+}
+
+.docws-compare-bar .docws-instruction {
+  color: var(--fg);
+  font-size: 13px;
+  max-width: 520px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.docws-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.docws-columns {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  overflow-x: auto;
+  gap: 0;
+}
+
+.docws-column {
+  flex: 1 0 460px;
+  min-width: 380px;
+  max-width: 760px;
+  border-right: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.docws-column-base {
+  flex-basis: 420px;
+  background: color-mix(in srgb, var(--bg-elevated) 60%, transparent);
+}
+
+.docws-column-head {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.docws-column-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 13px;
+}
+
+/* Capped so a talkative agent cannot push its own document out of view. */
+.docws-rationale {
+  font-size: 12px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-height: 30vh;
+  overflow-y: auto;
+}
+
+.docws-rationale-summary {
+  font-size: 13px;
+  color: var(--fg);
+}
+
+.docws-rationale ul {
+  margin: 0;
+  padding-left: 18px;
+  color: var(--fg-muted);
+}
+
+.docws-rationale .docws-rationale-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--fg-subtle);
+  margin-top: 4px;
+}
+
+.docws-warning {
+  color: var(--warning);
+}
+
+.docws-error {
+  color: var(--error);
+}
+
+.docws-note {
+  width: 100%;
+  box-sizing: border-box;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 5px 8px;
+  resize: vertical;
+  min-height: 30px;
+}
+
+.docws-column-body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 14px 18px 120px;
+}
+
+.docws-column-body .docws-content {
+  font-size: 15px;
+  line-height: 1.6;
+}
+
+.docws-nav {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+/* ── Source diff ── */
+
+.docws-diff {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docws-diff-line {
+  padding: 0 6px;
+}
+
+.docws-diff-add {
+  background: var(--diff-add-bg);
+}
+
+.docws-diff-remove {
+  background: var(--diff-remove-bg);
+}
+
+.docws-diff-hunk {
+  color: var(--info);
+  margin-top: 8px;
+}
+
+/* ── History ── */
+
+.docws-history {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+}
+
+.docws-history-list {
+  width: 360px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-entry {
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 10px 14px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.docws-history-entry:hover {
+  background: var(--bg-hover);
+}
+
+.docws-history-entry[aria-selected='true'] {
+  background: var(--bg-selected-subtle);
+  box-shadow: inset 3px 0 0 var(--accent);
+}
+
+.docws-history-subject {
+  font-size: 13px;
+  line-height: 1.35;
+}
+
+.docws-history-meta {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 11px;
+  color: var(--fg-subtle);
+  font-family: var(--font-mono);
+}
+
+.docws-history-detail {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-detail-head {
+  padding: 12px 18px;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.docws-history-body {
+  white-space: pre-wrap;
+  font-size: 13px;
+  color: var(--fg-muted);
+  line-height: 1.5;
+}
+
+.docws-trailers {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 2px 12px;
+  font-size: 12px;
+  font-family: var(--font-mono);
+}
+
+.docws-trailers dt {
+  color: var(--fg-subtle);
+}
+
+.docws-trailers dd {
+  margin: 0;
+  color: var(--fg);
+  word-break: break-all;
+}
+
+.docws-older-banner {
+  padding: 6px 18px;
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  color: var(--warning);
+  font-size: 12px;
+  border-bottom: 1px solid color-mix(in srgb, var(--warning) 40%, transparent);
+}
+
+.docws-picker-list {
+  max-height: 260px;
+  overflow-y: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--bg-input);
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-picker-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 7px 10px;
+  color: var(--fg);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.docws-picker-item .docws-badge {
+  margin-left: auto;
+}
+
+.docws-picker-item:hover {
+  background: var(--bg-hover);
+}
+
+.docws-picker-item[aria-selected='true'] {
+  background: var(--bg-selected);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docws-dot-running {
+    animation: none;
+  }
+}
+
+/* ── Annotations ── */
+
+.docws-bubble {
+  margin: 6px 0 10px 12px;
+  padding: 10px 12px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border);
+  background: var(--task-panel-bg);
+  font-size: 13px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  position: relative;
+  outline: none;
+}
+
+.docws-bubble::before {
+  content: '';
+  position: absolute;
+  left: -12px;
+  top: 12px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--review);
+}
+
+.docws-bubble.is-question::before {
+  background: var(--info);
+}
+
+.docws-bubble.is-detached {
+  border-style: dashed;
+}
+
+.docws-bubble:focus-visible {
+  border-color: var(--border-focus);
+}
+
+.docws-bubble.is-resolved {
+  padding: 0;
+  border-color: var(--border-subtle);
+  background: transparent;
+}
+
+.docws-bubble.is-resolved::before {
+  opacity: 0.4;
+}
+
+.docws-bubble-collapsed {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  background: transparent;
+  border: none;
+  color: var(--fg-subtle);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 4px 8px;
+  cursor: pointer;
+  text-align: left;
+}
+
+.docws-bubble-collapsed-text {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-decoration: line-through;
+}
+
+.docws-bubble-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+/* In a popover the head has to hold a badge, a time and three buttons on one
+   row: the time is the one part that can lose characters, so it gives way
+   first and keeps the full stamp in its title. */
+.docws-bubble-time {
+  font-family: var(--font-mono);
+  flex: 0 1 auto;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.docws-bubble-text {
+  white-space: pre-wrap;
+  color: var(--fg);
+  cursor: text;
+}
+
+.docws-bubble-quote {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-subtle);
+  border-left: 2px solid var(--border);
+  padding-left: 8px;
+  white-space: pre-wrap;
+  max-height: 80px;
+  overflow: hidden;
+}
+
+.docws-bubble-answer {
+  border-top: 1px solid var(--border-subtle);
+  padding-top: 6px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.docws-bubble-answer-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+.docws-bubble-answer-body {
+  font-size: 13px;
+  color: var(--fg);
+}
+
+.docws-bubble-pending {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--fg-muted);
+  font-size: 12px;
+}
+
+/* ── Annotation markers ── */
+
+/* A note is a symbol in the passage's margin: it opens over the document on
+   hover, on keyboard focus, or pinned by a click, and never moves the prose. */
+.docws-marker {
+  position: absolute;
+  z-index: 4;
+  font-family: var(--font-ui);
+  color: var(--fg);
+  line-height: 1.5;
+  text-align: left;
+}
+
+.docws-content:not(.docws-page) .docws-marker {
+  top: 0.2em;
+  right: -28px;
+}
+
+/* On a page the marker sits inside the block, like the § button: the page's
+   own elements reach the edge of the column and have no margin to sit in. */
+.docws-page .docws-marker {
+  top: 2px;
+  right: 2px;
+}
+
+.docws-page .doc-block:has(.docws-section-btn) .docws-marker {
+  right: 26px;
+}
+
+/* The anchor a page's marker is portalled into is out of the page's flow, so
+   attaching one cannot move the page's own elements. */
+.docws-marker-anchor {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+.docws-marker-anchor .docws-marker {
+  pointer-events: auto;
+}
+
+.docws-marker-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: 2px 4px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-xs);
+  background: var(--bg-elevated);
+  color: var(--review);
+  line-height: 1;
+  cursor: pointer;
+}
+
+/* An open marker paints over its neighbours, so the bubble is never covered by
+   the symbol of a passage further down. */
+.docws-marker:hover,
+.docws-marker:focus-within,
+.docws-marker.is-pinned {
+  z-index: 20;
+}
+
+.docws-marker.is-question .docws-marker-btn {
+  color: var(--info);
+}
+
+.docws-marker-btn:hover,
+.docws-marker.is-pinned .docws-marker-btn {
+  border-color: var(--border-focus);
+}
+
+.docws-marker-count {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--fg-muted);
+}
+
+/* Flush under the symbol, and held for a beat once the pointer leaves: a gap
+   below the symbol drops the hover on the way down, and an instant close does
+   the same to a pointer that cuts the corner on its way in. */
+.docws-marker-pop {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  width: min(440px, calc(100vw - 64px));
+  max-height: 60vh;
+  overflow-y: auto;
+  padding: 8px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--island-bg);
+  box-shadow: var(--shadow-pop);
+  visibility: hidden;
+  opacity: 0;
+  transition:
+    opacity 0.1s ease 0.05s,
+    visibility 0s linear 0.15s;
+}
+
+.docws-marker:hover > .docws-marker-pop,
+.docws-marker:focus-within > .docws-marker-pop,
+.docws-marker.is-pinned > .docws-marker-pop {
+  visibility: visible;
+  opacity: 1;
+  transition:
+    opacity 0.1s ease,
+    visibility 0s;
+}
+
+.docws-marker-pop .docws-bubble {
+  margin: 0;
+}
+
+.docws-marker-pop .docws-bubble + .docws-bubble {
+  margin-top: 8px;
+}
+
+/* The dot points at the passage from the margin; in the popover it has nothing
+   to point at. */
+.docws-marker-pop .docws-bubble::before {
+  display: none;
+}
+
+.docws-undo {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 2px 8px;
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  color: var(--fg);
+}
+
+.docws-detached-section {
+  margin: 0 0 18px;
+  padding: 10px 12px;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius-md);
+}
+
+.docws-mode-tabs {
+  display: inline-flex;
+  gap: 2px;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 2px;
+}
+
+.docws-mode-tabs .docws-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 3px 10px;
+  font-size: 12px;
+}
+
+/* --- Partial acceptance --------------------------------------------------
+   The include toggles sit in the left margin of the block that leads a
+   change, opposite the annotation markers, so the two gutters never collide
+   and a click meant for the prose cannot land on one. The compare columns
+   scroll, and a scroll container cannot reach content at negative x, so the
+   prose is inset far enough for the margin to be inside the column. */
+.docws-column-body .docws-content.docws-hunk-gutter {
+  padding-left: 28px;
+}
+
+.docws-hunk-toggles {
+  position: absolute;
+  top: 0.25em;
+  left: -26px;
+  z-index: 4;
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.docws-hunk-toggle {
+  display: inline-flex;
+  align-items: center;
+  cursor: pointer;
+}
+
+.docws-hunk-toggle input {
+  margin: 0;
+  cursor: pointer;
+  accent-color: var(--accent);
+}
+
+/* A declined change stays readable — you are choosing against it — but loses
+   its change mark and recedes, so what will land is what stands out. */
+.docws-content:not(.docws-page) .doc-block.is-declined {
+  background: transparent;
+  box-shadow: inset 3px 0 0 var(--border);
+  opacity: 0.5;
+}
+
+.docws-page .doc-block.is-declined {
+  outline-color: var(--border);
+  opacity: 0.5;
+}
diff --git a/src/documents/html-blocks.test.ts b/src/documents/html-blocks.test.ts
new file mode 100644
index 000000000..7e5eef1ae
--- /dev/null
+++ b/src/documents/html-blocks.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// DOMPurify needs a DOM; sanitization itself is its job, not this module's.
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+
+import { renderHtmlBlocks, scopePageCss } from './html-blocks';
+import { sectionRange } from './markdown-blocks';
+
+const page = [
+  '<!doctype html>',
+  '<html lang="en">',
+  '<head>',
+  '  <title>Spec</title>',
+  '  <style>body { color: #222 }</style>',
+  '</head>',
+  '<body>',
+  '  <h1>Spec</h1>',
+  '  <p>First paragraph',
+  '  continues here.</p>',
+  '  <!-- a comment -->',
+  '  <h2 id="goals">Goals</h2>',
+  '  <ul>',
+  '    <li>one</li>',
+  '    <li>two</li>',
+  '  </ul>',
+  '  Stray text',
+  '  <script>alert(1)</script>',
+  '  <style>h2 { color: red }</style>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+describe('renderHtmlBlocks', () => {
+  it('makes one block per block-level element with its source lines', () => {
+    const { blocks } = renderHtmlBlocks(page);
+    expect(blocks.map((b) => [b.type, b.startLine, b.endLine])).toEqual([
+      ['h1', 8, 8],
+      ['p', 9, 10],
+      ['h2', 12, 12],
+      ['ul', 13, 16],
+      ['text', 17, 17],
+    ]);
+    expect(blocks[1].raw).toBe('<p>First paragraph\n  continues here.</p>');
+    expect(blocks[4].html).toBe('Stray text');
+    expect(blocks.map((b) => b.index)).toEqual([0, 1, 2, 3, 4]);
+  });
+
+  it('keeps headings selectable as sections', () => {
+    const { blocks } = renderHtmlBlocks(page);
+    expect(blocks[0]).toMatchObject({ headingLevel: 1, headingText: 'Spec' });
+    expect(blocks[2]).toMatchObject({ headingLevel: 2, headingText: 'Goals' });
+    expect(sectionRange(blocks, 2)).toEqual([2, 4]);
+  });
+
+  it('collects every stylesheet in document order and never renders scripts', () => {
+    const { stylesheet, blocks, html } = renderHtmlBlocks(page);
+    expect(stylesheet).toBe('body { color: #222 }\nh2 { color: red }');
+    expect(blocks.some((b) => b.type === 'script' || b.type === 'style')).toBe(false);
+    expect(html).not.toContain('<script');
+    expect(html).not.toContain('<style');
+  });
+
+  it('marks every block in the page markup, wrapping bare text', () => {
+    const { html } = renderHtmlBlocks(page);
+    expect(html).toContain('<h1 data-block-index="0" class="doc-block">Spec</h1>');
+    expect(html).toContain('<h2 id="goals" data-block-index="2" class="doc-block">Goals</h2>');
+    expect(html).toContain(
+      '<span data-block-index="4" class="doc-block">\n  Stray text\n  </span>',
+    );
+  });
+
+  it('looks through wrappers to the innermost blocks and keeps the wrappers', () => {
+    const { blocks, html } = renderHtmlBlocks(
+      [
+        '<!doctype html>',
+        '<body>',
+        '<main>',
+        '  <h1>T</h1>',
+        '  <section class="s"><h2>A</h2><p>x</p></section>',
+        '  <div class="row"><span>inline only</span></div>',
+        '  <blockquote><p>quoted</p></blockquote>',
+        '</main>',
+        '</body>',
+      ].join('\n'),
+    );
+    expect(blocks.map((b) => [b.type, b.startLine])).toEqual([
+      ['h1', 4],
+      ['h2', 5],
+      ['p', 5],
+      ['div', 6],
+      ['p', 7],
+    ]);
+    expect(html).toContain('<main>');
+    expect(html).toContain('<section class="s"><h2 data-block-index="1" class="doc-block">');
+    expect(html).toContain('<div class="row doc-block" data-block-index="3">');
+    expect(html).toContain('<blockquote><p data-block-index="4" class="doc-block">');
+  });
+
+  it('ends an unclosed paragraph where the next block starts', () => {
+    const { blocks } = renderHtmlBlocks('<!doctype html>\n<p>open\n<div>next</div>\n');
+    expect(blocks.map((b) => [b.type, b.startLine, b.endLine, b.raw])).toEqual([
+      ['p', 2, 2, '<p>open'],
+      ['div', 3, 3, '<div>next</div>'],
+    ]);
+  });
+
+  it('renders a page without a body as no blocks', () => {
+    expect(renderHtmlBlocks('<!doctype html><html><head></head></html>').blocks).toEqual([]);
+  });
+});
+
+describe('scopePageCss', () => {
+  it('wraps the rules in @scope for the given root', () => {
+    const css = scopePageCss('h1 { color: red }', '[data-page="main"]');
+    expect(css).toContain(
+      '@scope ([data-page="main"]) to (.docws-marker-anchor, .docws-section-btn, .docws-block-actions) {',
+    );
+    expect(css.indexOf(':where(:scope, :scope *) { margin: revert;')).toBeLessThan(
+      css.indexOf('h1 {'),
+    );
+    expect(css).toContain('h1 { color: red }');
+  });
+
+  it('points html, :root and body rules at the scope root and leaves look-alikes alone', () => {
+    const css = scopePageCss(
+      'html, body { margin: 0 }\n:root { --brand: red }\nbody.dark > p { x: y }\n.body { a: b }\ntbody { c: d }\n@media print { body { e: f } }',
+      '.r',
+    );
+    expect(css).toContain(':scope, :scope { margin: 0 }');
+    expect(css).toContain(':scope { --brand: red }');
+    expect(css).toContain(':scope.dark > p { x: y }');
+    expect(css).toContain('.body { a: b }');
+    expect(css).toContain('tbody { c: d }');
+    expect(css).toContain('@media print { :scope { e: f } }');
+  });
+
+  it('gives universal selectors a :scope twin so a page reset reaches its body', () => {
+    const css = scopePageCss('*, *::before { margin: 0 }\n* p { a: b }\n.c * { d: e }', '.r');
+    expect(css).toContain('*, *::before, :scope, :scope::before { margin: 0 }');
+    // Only a selector that is nothing but `*` can mean the root element.
+    expect(css).toContain('* p { a: b }');
+    expect(css).toContain('.c * { d: e }');
+  });
+
+  it('resolves rem against the root size the page set, and leaves other pages alone', () => {
+    const moved = scopePageCss(
+      ':root { font-size: 62.5% }\nh1 { font-size: 3.2rem; margin: 1rem }',
+      '.r',
+    );
+    expect(moved).toContain('h1 { font-size: 32px; margin: 10px }');
+    const untouched = scopePageCss('h1 { font-size: 3.2rem }', '.r');
+    expect(untouched).toContain('h1 { font-size: 3.2rem }');
+    // A page whose root sits at the browser default needs no rewriting either.
+    const default16 = scopePageCss('html { font-size: 16px }\nh1 { font-size: 2rem }', '.r');
+    expect(default16).toContain('h1 { font-size: 2rem }');
+  });
+
+  it('keeps a stray closing brace from ending the scope and going global', () => {
+    const css = scopePageCss('p { a: b }\n} .docws-marker-anchor { display: none }', '.r');
+    // One `{` for the wrapper, one for the browser defaults, one per page rule:
+    // as many closers as openers means nothing escaped to the app.
+    expect((css.match(/{/g) ?? []).length).toBe((css.match(/}/g) ?? []).length);
+    expect(css.trimEnd().endsWith('}')).toBe(true);
+    expect(css).not.toContain('}\n} .docws-marker-anchor');
+  });
+
+  it('closes what the page left open instead of letting it swallow the wrapper', () => {
+    const css = scopePageCss('p { a: b', '.r');
+    expect((css.match(/{/g) ?? []).length).toBe((css.match(/}/g) ?? []).length);
+  });
+
+  it('hoists font faces and keyframes out of the scope and drops imports', () => {
+    const css = scopePageCss(
+      '@import url(remote.css);\n@font-face { font-family: F; src: url(f.woff) }\np { a: b }\n@keyframes spin { to { transform: rotate(1turn) } }',
+      '.r',
+    );
+    const scopeAt = css.indexOf('@scope');
+    expect(css.indexOf('@font-face')).toBeLessThan(scopeAt);
+    expect(css.indexOf('@keyframes spin')).toBeLessThan(scopeAt);
+    expect(css.indexOf('p { a: b }')).toBeGreaterThan(scopeAt);
+    expect(css).not.toContain('@import');
+  });
+});
diff --git a/src/documents/html-blocks.ts b/src/documents/html-blocks.ts
new file mode 100644
index 000000000..1302d96db
--- /dev/null
+++ b/src/documents/html-blocks.ts
@@ -0,0 +1,391 @@
+/**
+ * A whole HTML page as element blocks. The innermost block-level elements of
+ * <body> (a paragraph, a heading, a list, a table; not the <main> or <div>
+ * around them) are the unit of selection and change marking, the way
+ * markdown's top-level tokens are, and each carries its source line range so
+ * scope, quotes and anchors work unchanged. The page's markup is kept whole,
+ * with the blocks marked in place, so its own layout and stylesheet still
+ * apply when it is shown inline.
+ */
+import DOMPurify from 'dompurify';
+import { SANITIZE_UNTRUSTED } from '../lib/sanitize';
+import {
+  defaultTreeAdapter,
+  html as htmlSpec,
+  parse,
+  serialize,
+  serializeOuter,
+  type DefaultTreeAdapterMap,
+} from 'parse5';
+import type { DocumentBlock } from './markdown-blocks';
+
+type Node = DefaultTreeAdapterMap['node'];
+type ParentNode = DefaultTreeAdapterMap['parentNode'];
+type Element = DefaultTreeAdapterMap['element'];
+type TextNode = DefaultTreeAdapterMap['textNode'];
+
+export interface HtmlDocumentRender {
+  blocks: DocumentBlock[];
+  /** The page's <style> contents in document order; the viewer scopes them. */
+  stylesheet: string;
+  /**
+   * The body's sanitized markup with every block carrying `data-block-index`
+   * and the `doc-block` class, for rendering the page as one piece.
+   */
+  html: string;
+}
+
+const HEADING_RE = /^h([1-6])$/;
+/** Page machinery rather than content: never a block of its own. */
+const SKIPPED_TAGS = new Set(['script', 'style', 'template', 'noscript', 'link', 'meta', 'title']);
+/** Elements that group blocks; one of these holding block children is structure, not a block. */
+const WRAPPER_TAGS = new Set([
+  'address',
+  'article',
+  'aside',
+  'blockquote',
+  'center',
+  'details',
+  'dialog',
+  'div',
+  'fieldset',
+  'footer',
+  'form',
+  'header',
+  'hgroup',
+  'main',
+  'nav',
+  'section',
+]);
+/** Elements that make their parent a wrapper rather than a block of inline content. */
+const BLOCK_TAGS = new Set([
+  ...WRAPPER_TAGS,
+  'canvas',
+  'dl',
+  'figure',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'hr',
+  'img',
+  'ol',
+  'p',
+  'picture',
+  'pre',
+  'svg',
+  'table',
+  'ul',
+  'video',
+]);
+
+function isElement(node: Node): node is Element {
+  return 'tagName' in node;
+}
+
+function isText(node: Node): node is TextNode {
+  return node.nodeName === '#text';
+}
+
+function childNodes(node: Node): Node[] {
+  return 'childNodes' in node ? (node as ParentNode).childNodes : [];
+}
+
+function findChild(node: Node, tagName: string): Element | undefined {
+  return childNodes(node).find((c): c is Element => isElement(c) && c.tagName === tagName);
+}
+
+function textOf(node: Node): string {
+  if (isText(node)) return node.value;
+  return childNodes(node).map(textOf).join('');
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function countNewlines(text: string): number {
+  let n = 0;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+/** Source lines of a node, trimmed of the surrounding whitespace parse5 keeps. */
+function sourceLines(
+  node: Node,
+  source: string,
+  fallbackLine: number,
+): Pick<DocumentBlock, 'startLine' | 'endLine' | 'raw' | 'startOffset' | 'endOffset'> {
+  const loc = node.sourceCodeLocation;
+  if (!loc) return { startLine: fallbackLine, endLine: fallbackLine, raw: '' };
+  const full = source.slice(loc.startOffset, loc.endOffset);
+  const raw = full.trim();
+  const startLine =
+    loc.startLine + countNewlines(full.slice(0, full.length - full.trimStart().length));
+  const startOffset = loc.startOffset + full.length - full.trimStart().length;
+  return {
+    startLine,
+    endLine: startLine + countNewlines(raw),
+    raw,
+    startOffset,
+    endOffset: startOffset + raw.length,
+  };
+}
+
+function blockFor(
+  node: Node,
+  source: string,
+  index: number,
+  fallbackLine: number,
+): DocumentBlock | null {
+  if (isElement(node)) {
+    if (SKIPPED_TAGS.has(node.tagName)) return null;
+    const block: DocumentBlock = {
+      index,
+      type: node.tagName,
+      ...sourceLines(node, source, fallbackLine),
+      html: DOMPurify.sanitize(serializeOuter(node), SANITIZE_UNTRUSTED),
+    };
+    const heading = HEADING_RE.exec(node.tagName);
+    if (heading) {
+      block.headingLevel = Number(heading[1]);
+      block.headingText = textOf(node).trim();
+    }
+    return block;
+  }
+  if (isText(node) && node.value.trim()) {
+    return {
+      index,
+      type: 'text',
+      ...sourceLines(node, source, fallbackLine),
+      html: escapeHtml(node.value.trim()),
+    };
+  }
+  return null;
+}
+
+/** A wrapper is structure to look through; anything else is a block. */
+function isWrapper(node: Element): boolean {
+  return (
+    WRAPPER_TAGS.has(node.tagName) &&
+    node.childNodes.some((c) => isElement(c) && BLOCK_TAGS.has(c.tagName))
+  );
+}
+
+/**
+ * The innermost block-level nodes under `parent`, in document order. Page
+ * machinery met on the way is detached so it never reaches the rendered
+ * markup; its styles were collected before.
+ */
+function collectLeaves(parent: Node, out: Node[]): void {
+  for (const child of [...childNodes(parent)]) {
+    if (isElement(child) && SKIPPED_TAGS.has(child.tagName)) defaultTreeAdapter.detachNode(child);
+    else if (isElement(child) && isWrapper(child)) collectLeaves(child, out);
+    else out.push(child);
+  }
+}
+
+/** Marks a block in the tree so the rendered page carries its index. */
+function markBlock(node: Node, index: number): void {
+  const attrs = [
+    { name: 'data-block-index', value: String(index) },
+    { name: 'class', value: 'doc-block' },
+  ];
+  if (isElement(node)) {
+    const cls = node.attrs.find((a) => a.name === 'class');
+    if (cls) cls.value = `${cls.value} doc-block`;
+    node.attrs.push(...attrs.filter((a) => a.name !== 'class' || !cls));
+    return;
+  }
+  // Bare text has nowhere to hang an attribute; a span changes nothing inline.
+  if (!isText(node) || !node.parentNode) return;
+  const span = defaultTreeAdapter.createElement('span', htmlSpec.NS.HTML, attrs);
+  defaultTreeAdapter.insertBefore(node.parentNode, span, node);
+  defaultTreeAdapter.detachNode(node);
+  defaultTreeAdapter.appendChild(span, node);
+}
+
+function collectStyles(node: Node, out: string[]): void {
+  if (isElement(node) && node.tagName === 'template') return;
+  if (isElement(node) && node.tagName === 'style') {
+    out.push(textOf(node).trim());
+    return;
+  }
+  for (const child of childNodes(node)) collectStyles(child, out);
+}
+
+/**
+ * Splits a page into blocks, one per innermost block-level element (or run of
+ * bare text), each sanitized like a markdown block, and returns the body's
+ * markup with the blocks marked in place. Scripts never reach the DOM; <link>
+ * stylesheets are not followed.
+ */
+export function renderHtmlBlocks(source: string): HtmlDocumentRender {
+  const document = parse(source, { sourceCodeLocationInfo: true });
+  const styles: string[] = [];
+  collectStyles(document, styles);
+  const html = findChild(document, 'html');
+  const body = html && findChild(html, 'body');
+  const leaves: Node[] = [];
+  if (body) collectLeaves(body, leaves);
+  const blocks: DocumentBlock[] = [];
+  let line = 1;
+  for (const node of leaves) {
+    const block = blockFor(node, source, blocks.length, line);
+    if (!block) continue;
+    line = block.endLine;
+    blocks.push(block);
+    markBlock(node, block.index);
+  }
+  return {
+    blocks,
+    stylesheet: styles.filter(Boolean).join('\n'),
+    // A <style> nested inside a block would escape the scoped stylesheet.
+    html: body ? DOMPurify.sanitize(serialize(body), SANITIZE_UNTRUSTED) : '',
+  };
+}
+
+/** At-rules that are global by name and so cannot sit inside @scope. */
+const GLOBAL_AT_RULES = ['@font-face', '@keyframes', '@-webkit-keyframes'];
+/**
+ * `html`, `:root` and `body` where a selector can start or continue. `:root`
+ * belongs here with the rest: a page keeps its custom properties there, and
+ * dropped they take every colour and size defined with them along.
+ */
+const ROOT_SELECTOR_RE = /(^|[\s,>+~{};])(?::root|html|body)(?=[\s,>+~{.#[:]|$)/g;
+
+/** Index just past the `}` closing the block that starts at `from`. */
+function blockEnd(css: string, from: number): number {
+  let depth = 0;
+  for (let i = from; i < css.length; i++) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}' && --depth === 0) return i + 1;
+  }
+  return css.length;
+}
+
+/**
+ * Lifts the at-rules that cannot sit inside `@scope` out of the sheet, and
+ * balances what is left. Balancing is the point: a page's `}` with nothing
+ * open would close the `@scope` wrapper this is about to go inside, and every
+ * rule after it would apply to the whole app. Unmatched closers are dropped
+ * and unclosed blocks are closed here instead.
+ */
+function splitGlobalAtRules(css: string): { hoisted: string; rest: string } {
+  const hoisted: string[] = [];
+  const kept: string[] = [];
+  let depth = 0;
+  let from = 0;
+  for (let i = 0; i < css.length; ) {
+    const rule = depth === 0 ? GLOBAL_AT_RULES.find((r) => css.startsWith(r, i)) : undefined;
+    if (rule) {
+      const end = blockEnd(css, i);
+      kept.push(css.slice(from, i));
+      hoisted.push(css.slice(i, end));
+      i = end;
+      from = end;
+      continue;
+    }
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}') {
+      if (depth === 0) {
+        kept.push(css.slice(from, i));
+        from = i + 1;
+      } else depth--;
+    }
+    i++;
+  }
+  kept.push(css.slice(from));
+  return { hoisted: hoisted.join('\n'), rest: kept.join('') + '}'.repeat(depth) };
+}
+
+/**
+ * The app's own elements inside a page (markers, bubbles, § buttons, the block
+ * toolbar) stay out of its CSS.
+ */
+export const PAGE_SCOPE_LIMIT = '.docws-marker-anchor, .docws-section-btn, .docws-block-actions';
+/**
+ * The app resets every element's margin, padding, box model and scrollbars; a
+ * page starts from the browser's defaults instead. The scope root stands in
+ * for the page's <body>, so it is reverted with the rest. Zero specificity
+ * keeps this below any rule the page has, and it comes first so even the
+ * page's own `*` rules win. The scrollbars take `initial` rather than
+ * `revert`: their colour is inherited, so reverting it would only pick the
+ * app's own up again from the ancestor.
+ */
+const BROWSER_DEFAULTS =
+  ':where(:scope, :scope *) { margin: revert; padding: revert; box-sizing: revert; scrollbar-width: initial; scrollbar-color: initial; }';
+
+/** A selector that is nothing but `*`, optionally with pseudos: `*`, `*::before`, `*:not(pre)`. */
+const UNIVERSAL_SELECTOR_RE = /^\s*\*(?:::?[\w-]+(?:\([^()]*\))?)*\s*$/;
+/** A rule's selector list: what stands between the end of the last block and its `{`. */
+const SELECTOR_LIST_RE = /(^|[{};])([^{};@]*)(?=\{)/g;
+
+/**
+ * `*` matches everything in the scope but never the scope root itself, so a
+ * page's own reset (`* { margin: 0 }`) would skip the element standing in for
+ * its <body> and leave the browser's body margin on it. Every universal
+ * selector gets a `:scope` twin, which does match the root.
+ */
+function widenUniversalSelectors(css: string): string {
+  return css.replace(SELECTOR_LIST_RE, (match, lead: string, selectors: string) => {
+    const twins = selectors
+      .split(',')
+      .filter((s) => UNIVERSAL_SELECTOR_RE.test(s))
+      .map((s) => s.trim().replace('*', ':scope'));
+    return twins.length > 0 ? `${lead}${selectors.trimEnd()}, ${twins.join(', ')} ` : match;
+  });
+}
+
+/** The root font size every `rem` in the sheet is measured against. */
+const DEFAULT_ROOT_PX = 16;
+/** A root rule's declarations: only `html`/`:root` move what `rem` means. */
+const ROOT_RULE_RE = /(?:^|[};])\s*(?::root|html)\s*\{([^{}]*)\}/g;
+const ROOT_FONT_SIZE_RE = /(?:^|;)\s*font-size\s*:\s*(\d*\.?\d+)(px|%)/gi;
+const REM_LENGTH_RE = /(-?\d*\.?\d+)rem\b/g;
+
+/** The page's root font size in px, from its last `html`/`:root` declaration. */
+function rootFontSizePx(css: string): number {
+  let px = DEFAULT_ROOT_PX;
+  for (const [, declarations] of css.matchAll(ROOT_RULE_RE))
+    for (const [, size, unit] of declarations.matchAll(ROOT_FONT_SIZE_RE))
+      px = unit === '%' ? (Number(size) / 100) * DEFAULT_ROOT_PX : Number(size);
+  return px;
+}
+
+/**
+ * A page's `rem` is measured against the app's root element, not the page's,
+ * so a page that moves its root size (`:root { font-size: 62.5% }`, to make
+ * `1.6rem` mean 16px) renders every rem-sized thing at the app's scale
+ * instead. Those lengths are resolved here, against the size the page set.
+ *
+ * shortcut: pages that leave the root size alone are untouched, since the
+ * app's root is the browser default the page would have had. Root sizes in
+ * `em` are left alone too, rather than resolved by hand.
+ */
+function resolveRemLengths(css: string): string {
+  const rootPx = rootFontSizePx(css);
+  if (rootPx === DEFAULT_ROOT_PX) return css;
+  return css.replace(REM_LENGTH_RE, (_m, length: string) => `${Number(length) * rootPx}px`);
+}
+
+/**
+ * Confines a page's stylesheet to one viewer. `@scope` keeps every selector
+ * inside the scope root and out of the app's elements placed within it;
+ * `html`, `:root` and `body` rules are pointed at the root so page-level
+ * fonts, colours, custom properties and widths still apply. `@import` is
+ * dropped so a document cannot pull a whole sheet in; a hoisted `@font-face`
+ * can still fetch its `src`, which wants a Content-Security-Policy rather
+ * than more parsing here.
+ *
+ * shortcut: the rewrites are regexes, not a CSS parser, so the words inside
+ * strings or attribute values would be rewritten too.
+ */
+export function scopePageCss(css: string, scope: string): string {
+  const cleaned = css.replace(/\/\*[\s\S]*?\*\//g, '').replace(/@import\b[^;]*;/g, '');
+  const { hoisted, rest } = splitGlobalAtRules(resolveRemLengths(cleaned));
+  const scoped = widenUniversalSelectors(rest).replace(ROOT_SELECTOR_RE, '$1:scope');
+  return `${hoisted}\n@scope (${scope}) to (${PAGE_SCOPE_LIMIT}) {\n${BROWSER_DEFAULTS}\n${scoped}\n}`;
+}
diff --git a/src/documents/html-document.test.ts b/src/documents/html-document.test.ts
new file mode 100644
index 000000000..22fe8ab8d
--- /dev/null
+++ b/src/documents/html-document.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { isHtmlDocument } from './html-document';
+
+describe('isHtmlDocument', () => {
+  it('recognises a page by its doctype', () => {
+    expect(isHtmlDocument('<!DOCTYPE html>\n<html lang="en">\n<head></head>\n')).toBe(true);
+  });
+
+  it('recognises a page that opens with <html>', () => {
+    expect(isHtmlDocument('<html>\n<body>hi</body>\n</html>')).toBe(true);
+    expect(isHtmlDocument('<html lang="en">')).toBe(true);
+  });
+
+  it('looks past leading comments and whitespace', () => {
+    expect(isHtmlDocument('\n<!-- generated -->\n<!DOCTYPE html>\n<html>')).toBe(true);
+  });
+
+  it('leaves markdown with embedded HTML on the block view', () => {
+    expect(isHtmlDocument('# Title\n\n<div class="callout">note</div>\n')).toBe(false);
+    expect(isHtmlDocument('<div>just a fragment</div>')).toBe(false);
+    expect(isHtmlDocument('Prose about <html> tags.')).toBe(false);
+  });
+
+  it('handles empty and missing content', () => {
+    expect(isHtmlDocument('')).toBe(false);
+    expect(isHtmlDocument(null)).toBe(false);
+    expect(isHtmlDocument(undefined)).toBe(false);
+  });
+});
diff --git a/src/documents/html-document.ts b/src/documents/html-document.ts
new file mode 100644
index 000000000..ec1c1e0e6
--- /dev/null
+++ b/src/documents/html-document.ts
@@ -0,0 +1,11 @@
+/**
+ * A document that is a whole HTML page rather than prose. Markdown legitimately
+ * contains HTML fragments, so only a real document preamble counts: a leading
+ * doctype or <html> element, past any comments. Fragments keep the block view,
+ * which is what the selection and agent-scoping model is built on.
+ */
+const HTML_DOCUMENT_RE = /^\s*(?:<!--[\s\S]*?-->\s*)*(?:<!doctype\s+html\b|<html[\s>])/i;
+
+export function isHtmlDocument(content: string | null | undefined): boolean {
+  return !!content && HTML_DOCUMENT_RE.test(content);
+}
diff --git a/src/documents/interactive-prompt.test.ts b/src/documents/interactive-prompt.test.ts
new file mode 100644
index 000000000..599f5b869
--- /dev/null
+++ b/src/documents/interactive-prompt.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { buildInteractivePrompt } from './interactive-prompt';
+
+describe('buildInteractivePrompt', () => {
+  it('names the document, the lines and the passage before the instruction', () => {
+    const prompt = buildInteractivePrompt(
+      'notes.md',
+      {
+        startBlock: 1,
+        endBlock: 1,
+        startLine: 4,
+        endLine: 6,
+        quote: 'One.\nTwo.',
+        heading: 'Plan',
+        wholeDocument: false,
+      },
+      '  Tighten this.  ',
+    );
+    expect(prompt).toBe(
+      'Document: notes.md\n\nScope: lines 4-6 (under "Plan").\n\n' +
+        'The passage, verbatim:\n> One.\n> Two.\n\nTighten this.',
+    );
+  });
+
+  it('leaves out the quote for the whole document', () => {
+    const prompt = buildInteractivePrompt(
+      'notes.md',
+      {
+        startBlock: 0,
+        endBlock: 3,
+        startLine: 1,
+        endLine: 40,
+        quote: '',
+        wholeDocument: true,
+      },
+      'Rewrite the intro.',
+    );
+    expect(prompt).toBe('Document: notes.md\n\nScope: the whole document.\n\nRewrite the intro.');
+  });
+
+  it('drops the control characters a pasted passage would turn into keystrokes', () => {
+    const prompt = buildInteractivePrompt(
+      'notes.md',
+      {
+        startBlock: 0,
+        endBlock: 0,
+        startLine: 1,
+        endLine: 1,
+        quote: 'Harmless\u001b[201~ then \r/yes',
+        heading: undefined,
+        wholeDocument: false,
+      },
+      'Rewrite it.',
+    );
+    expect(prompt).toContain('> Harmless[201~ then /yes');
+    expect(prompt).not.toContain('\u001b');
+    expect(prompt).not.toContain('\r');
+  });
+});
diff --git a/src/documents/interactive-prompt.ts b/src/documents/interactive-prompt.ts
new file mode 100644
index 000000000..c0fce0d37
--- /dev/null
+++ b/src/documents/interactive-prompt.ts
@@ -0,0 +1,39 @@
+import type { DocumentSelection } from './store';
+
+/**
+ * The message typed into the interactive session for a scoped instruction.
+ * That session runs in the checkout with the user watching, so it is asked to
+ * edit directly and told where; the rest is the user's own words.
+ */
+export function buildInteractivePrompt(
+  documentPath: string,
+  selection: DocumentSelection,
+  instruction: string,
+): string {
+  const where = selection.wholeDocument
+    ? 'the whole document'
+    : selection.heading
+      ? `lines ${selection.startLine}-${selection.endLine} (under "${selection.heading}")`
+      : `lines ${selection.startLine}-${selection.endLine}`;
+  const parts = [`Document: ${documentPath}`, `Scope: ${where}.`];
+  if (!selection.wholeDocument && selection.quote.trim()) {
+    const quote = selection.quote
+      .split('\n')
+      .map((line) => `> ${line}`)
+      .join('\n');
+    parts.push(`The passage, verbatim:\n${quote}`);
+  }
+  parts.push(instruction.trim());
+  return plainText(parts.join('\n\n'));
+}
+
+/**
+ * The passage comes from a file the app did not write and is pasted into a
+ * live terminal. An ESC or a stray `\r` in it would arrive as keystrokes —
+ * enough to end the paste and answer the agent's next prompt — so every C0
+ * control but tab and newline is dropped.
+ */
+function plainText(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, '');
+}
diff --git a/src/documents/links.test.ts b/src/documents/links.test.ts
new file mode 100644
index 000000000..9caa959f0
--- /dev/null
+++ b/src/documents/links.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { headingSlug, resolveDocumentLink } from './links';
+
+describe('resolveDocumentLink', () => {
+  it('keeps web links external', () => {
+    expect(resolveDocumentLink('https://example.com/x', 'docs/a.md')).toEqual({
+      kind: 'external',
+      url: 'https://example.com/x',
+    });
+    expect(resolveDocumentLink('mailto:me@example.com', 'a.md')).toEqual({
+      kind: 'external',
+      url: 'mailto:me@example.com',
+    });
+  });
+
+  it('resolves relative paths against the document folder', () => {
+    expect(resolveDocumentLink('./b.md', 'docs/a.md')).toEqual({ kind: 'file', path: 'docs/b.md' });
+    expect(resolveDocumentLink('../readme.md#plan', 'docs/a.md')).toEqual({
+      kind: 'file',
+      path: 'readme.md',
+      anchor: 'plan',
+    });
+    expect(resolveDocumentLink('/adr/0001.md', 'docs/deep/a.md')).toEqual({
+      kind: 'file',
+      path: 'adr/0001.md',
+    });
+    expect(resolveDocumentLink('my%20notes.md', 'a.md')).toEqual({
+      kind: 'file',
+      path: 'my notes.md',
+    });
+  });
+
+  it('treats a bare hash as an anchor in the same document', () => {
+    expect(resolveDocumentLink('#the-plan', 'a.md')).toEqual({ kind: 'anchor', id: 'the-plan' });
+  });
+
+  it('refuses what it cannot follow', () => {
+    expect(resolveDocumentLink('../../etc/passwd', 'docs/a.md')).toBeNull();
+    expect(resolveDocumentLink('file:///etc/passwd', 'a.md')).toBeNull();
+    expect(resolveDocumentLink('javascript:alert(1)', 'a.md')).toBeNull();
+    expect(resolveDocumentLink('', 'a.md')).toBeNull();
+  });
+});
+
+describe('headingSlug', () => {
+  it('matches the slugs Markdown anchors use', () => {
+    expect(headingSlug('The Plan: Part 2!')).toBe('the-plan-part-2');
+    expect(headingSlug('  Über uns ')).toBe('über-uns');
+  });
+});
diff --git a/src/documents/links.ts b/src/documents/links.ts
new file mode 100644
index 000000000..5d8120251
--- /dev/null
+++ b/src/documents/links.ts
@@ -0,0 +1,73 @@
+/**
+ * What a link in a rendered document points at. Links are the seam between
+ * documents in one project, so a relative target opens inside the workspace
+ * instead of navigating the app window, and web links open in the browser.
+ */
+export type DocumentLink =
+  | { kind: 'external'; url: string }
+  | { kind: 'anchor'; id: string }
+  | { kind: 'file'; path: string; anchor?: string };
+
+const EXTERNAL_RE = /^(?:https?:|mailto:|tel:)/i;
+
+/** Repo-relative path of `target` resolved from the document at `fromPath`. */
+function resolveRelative(fromPath: string, target: string): string | null {
+  const base = fromPath.split('/').slice(0, -1);
+  const parts = target.startsWith('/') ? [] : base;
+  for (const segment of target.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (parts.length === 0) return null;
+      parts.pop();
+      continue;
+    }
+    parts.push(segment);
+  }
+  return parts.length > 0 ? parts.join('/') : null;
+}
+
+/**
+ * Classifies an `href` found in the document at `fromPath`. Returns null for
+ * links the workspace cannot follow (other schemes, paths that climb out of
+ * the project), which the viewer then ignores.
+ */
+export function resolveDocumentLink(href: string, fromPath: string): DocumentLink | null {
+  const trimmed = href.trim();
+  if (!trimmed) return null;
+  if (EXTERNAL_RE.test(trimmed)) return { kind: 'external', url: trimmed };
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null;
+  if (trimmed.startsWith('#')) {
+    const id = decodeURIComponent(trimmed.slice(1));
+    return id ? { kind: 'anchor', id } : null;
+  }
+  const hashAt = trimmed.indexOf('#');
+  const pathPart = hashAt >= 0 ? trimmed.slice(0, hashAt) : trimmed;
+  const anchor = hashAt >= 0 ? decodeURIComponent(trimmed.slice(hashAt + 1)) : undefined;
+  const path = resolveRelative(fromPath, decodeURIComponent(pathPart.split('?')[0]));
+  if (!path) return null;
+  return anchor ? { kind: 'file', path, anchor } : { kind: 'file', path };
+}
+
+/** GitHub-style slug of a heading, what `#anchors` in Markdown point at. */
+export function headingSlug(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/<[^>]+>/g, '')
+    .replace(/[^\p{L}\p{N}\s-]/gu, '')
+    .replace(/\s+/g, '-');
+}
+
+/**
+ * The element `anchor` names inside a rendered document: an element with
+ * that id, or a heading whose slug matches.
+ */
+export function findAnchorTarget(container: ParentNode, anchor: string): HTMLElement | null {
+  const byId = container.querySelector<HTMLElement>(`[id="${CSS.escape(anchor)}"]`);
+  if (byId) return byId;
+  const wanted = anchor.toLowerCase();
+  for (const heading of container.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6')) {
+    if (headingSlug(heading.textContent ?? '') === wanted) return heading;
+  }
+  return null;
+}
diff --git a/src/documents/markdown-blocks.test.ts b/src/documents/markdown-blocks.test.ts
new file mode 100644
index 000000000..bc69f6823
--- /dev/null
+++ b/src/documents/markdown-blocks.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('./shiki-highlighter', () => ({
+  highlightLines: async (code: string) => code.split('\n').map((l) => `<span>${l}</span>`),
+}));
+// DOMPurify needs a DOM; sanitization itself is its job, not this module's.
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+
+import {
+  blockRangeText,
+  diffBlocks,
+  nearestHeading,
+  renderDocumentBlocks,
+  sectionRange,
+  type DocumentBlock,
+} from './markdown-blocks';
+
+const doc = [
+  '# Title',
+  '',
+  'First paragraph',
+  'continues here.',
+  '',
+  '',
+  '## Section A',
+  '',
+  '- one',
+  '- two',
+  '',
+  '```ts',
+  'const x = 1;',
+  '```',
+  '',
+  '### Sub',
+  '',
+  'Deep text.',
+  '',
+  '## Section B',
+  '',
+  'Last.',
+].join('\n');
+
+describe('renderDocumentBlocks', () => {
+  it('maps every block to its source lines', async () => {
+    const blocks = await renderDocumentBlocks(doc);
+    const summary = blocks.map((b) => [b.type, b.startLine, b.endLine]);
+    expect(summary).toEqual([
+      ['heading', 1, 1],
+      ['paragraph', 3, 4],
+      ['heading', 7, 7],
+      ['list', 9, 10],
+      ['code', 12, 14],
+      ['heading', 16, 16],
+      ['paragraph', 18, 18],
+      ['heading', 20, 20],
+      ['paragraph', 22, 22],
+    ]);
+    expect(blocks[0].headingLevel).toBe(1);
+    expect(blocks[0].headingText).toBe('Title');
+    expect(blocks[1].html).toContain('<p>');
+    expect(blocks[4].html).toContain('shiki-block');
+    expect(blocks[4].html).toContain('data-lang="ts"');
+  });
+
+  it('handles CRLF sources', async () => {
+    const blocks = await renderDocumentBlocks('# A\r\n\r\nmiddle\r\n\r\nB');
+    expect(blocks.map((b) => b.startLine)).toEqual([1, 3, 5]);
+  });
+
+  it('renders mermaid fences as placeholders', async () => {
+    const blocks = await renderDocumentBlocks('```mermaid\ngraph TD; A-->B\n```');
+    expect(blocks[0].html).toContain('mermaid-block');
+    expect(blocks[0].html).toContain('data-mermaid');
+  });
+});
+
+describe('sectionRange and nearestHeading', () => {
+  it('spans a heading through its subsections', async () => {
+    const blocks = await renderDocumentBlocks(doc);
+    expect(sectionRange(blocks, 2)).toEqual([2, 6]); // Section A up to Section B
+    expect(sectionRange(blocks, 5)).toEqual([5, 6]); // Sub
+    expect(sectionRange(blocks, 7)).toEqual([7, 8]);
+    expect(sectionRange(blocks, 1)).toEqual([1, 1]); // not a heading
+    expect(nearestHeading(blocks, 4)).toBe('Section A');
+    expect(nearestHeading(blocks, 0)).toBe('Title');
+  });
+});
+
+function fake(raws: string[]): DocumentBlock[] {
+  return raws.map((raw, index) => ({
+    index,
+    type: 'paragraph',
+    startLine: index + 1,
+    endLine: index + 1,
+    raw,
+    html: '',
+  }));
+}
+
+describe('diffBlocks', () => {
+  it('marks identical documents as unchanged', () => {
+    const r = diffBlocks(fake(['a', 'b']), fake(['a', 'b']));
+    expect(r.base).toEqual(['same', 'same']);
+    expect(r.candidate).toEqual(['same', 'same']);
+  });
+
+  it('pairs a rewritten block as changed and a new one as added', () => {
+    const r = diffBlocks(fake(['a', 'b', 'c']), fake(['a', 'B!', 'c', 'd']));
+    expect(r.base).toEqual(['same', 'changed', 'same']);
+    expect(r.candidate).toEqual(['same', 'changed', 'same', 'added']);
+  });
+
+  it('marks a deleted block as removed', () => {
+    const r = diffBlocks(fake(['a', 'b', 'c']), fake(['a', 'c']));
+    expect(r.base).toEqual(['same', 'removed', 'same']);
+    expect(r.candidate).toEqual(['same', 'same']);
+  });
+
+  it('ignores whitespace-only differences', () => {
+    const r = diffBlocks(fake(['a  b\n']), fake(['a b']));
+    expect(r.candidate).toEqual(['same']);
+  });
+});
+
+describe('blockRangeText', () => {
+  it('joins raw blocks without trailing newlines', () => {
+    expect(blockRangeText(fake(['x\n\n', 'y\n']), 0, 1)).toBe('x\n\ny');
+  });
+});
diff --git a/src/documents/markdown-blocks.ts b/src/documents/markdown-blocks.ts
new file mode 100644
index 000000000..439cfa3fd
--- /dev/null
+++ b/src/documents/markdown-blocks.ts
@@ -0,0 +1,230 @@
+import DOMPurify from 'dompurify';
+import { Marked, type Token, type Tokens } from 'marked';
+import { highlightLines } from '../lib/shiki-highlighter';
+import { SANITIZE_UNTRUSTED } from '../lib/sanitize';
+
+/**
+ * A top-level markdown block with its source line range. Blocks are the unit
+ * of selection, scope and change marking in document workspaces: prose is
+ * rewritten paragraph by paragraph, so line-level diffs would be noise.
+ */
+export interface DocumentBlock {
+  index: number;
+  type: string;
+  /** 1-based, inclusive source lines. */
+  startLine: number;
+  endLine: number;
+  /** Exact editable range in newline-normalized source, excluding separators. */
+  startOffset?: number;
+  endOffset?: number;
+  raw: string;
+  html: string;
+  headingLevel?: number;
+  headingText?: string;
+}
+
+export type BlockChange = 'same' | 'added' | 'changed' | 'removed';
+
+interface TokenLike {
+  type: string;
+  lang?: string;
+  text?: string;
+  tokens?: TokenLike[];
+  items?: { tokens?: TokenLike[] }[];
+}
+
+function collectCodeTokens(tokens: readonly TokenLike[], out: { lang: string; text: string }[]) {
+  for (const token of tokens) {
+    if (token.type === 'code' && token.lang !== 'mermaid') {
+      out.push({ lang: token.lang ?? '', text: token.text ?? '' });
+    }
+    if (Array.isArray(token.tokens)) collectCodeTokens(token.tokens, out);
+    if (Array.isArray(token.items)) {
+      for (const item of token.items) {
+        if (Array.isArray(item.tokens)) collectCodeTokens(item.tokens, out);
+      }
+    }
+  }
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function countNewlines(text: string): number {
+  let n = 0;
+  for (let i = 0; i < text.length; i++) if (text.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+/** Normalizes line endings the same way marked does, so offsets line up. */
+export function normalizeSource(source: string): string {
+  return source.replace(/\r\n|\r/g, '\n');
+}
+
+/**
+ * Splits a document into top-level blocks, each rendered to sanitized HTML
+ * with Shiki-highlighted code. Blank-line tokens are dropped; their lines are
+ * absorbed into the gap between blocks.
+ */
+export async function renderDocumentBlocks(rawSource: string): Promise<DocumentBlock[]> {
+  const source = normalizeSource(rawSource);
+  const marked = new Marked();
+  const tokens = marked.lexer(source);
+
+  const codeBlocks: { lang: string; text: string }[] = [];
+  collectCodeTokens(tokens as unknown as TokenLike[], codeBlocks);
+  const highlighted = await Promise.all(
+    codeBlocks.map(({ text, lang }) =>
+      highlightLines(text, lang || 'plaintext').catch(() => null as string[] | null),
+    ),
+  );
+
+  let codeIndex = 0;
+  marked.use({
+    renderer: {
+      code(token: Tokens.Code): string {
+        if (token.lang === 'mermaid') {
+          return `<div class="mermaid-block" data-mermaid="${escapeAttr(token.text ?? '')}">${escapeHtml(token.text ?? '')}</div>`;
+        }
+        const lines = codeIndex < highlighted.length ? highlighted[codeIndex] : null;
+        codeIndex++;
+        const langAttr = token.lang ? ` data-lang="${escapeAttr(token.lang)}"` : '';
+        const body = lines ? lines.join('\n') : escapeHtml(token.text ?? '');
+        return `<pre class="shiki-block"${langAttr}><code>${body}</code></pre>`;
+      },
+    },
+  });
+
+  const blocks: DocumentBlock[] = [];
+  let offset = 0;
+  // Tokens are contiguous, so the line runs forward with them; counting the
+  // newlines before each one instead is quadratic in the document's length.
+  let line = 1;
+  for (const token of tokens as Token[]) {
+    const raw = token.raw ?? '';
+    const startLine = line;
+    line += countNewlines(raw);
+    offset += raw.length;
+    if (token.type === 'space' || !raw.trim()) continue;
+    const endLine = startLine + countNewlines(raw.trimEnd());
+    const html = DOMPurify.sanitize(marked.parser([token]), SANITIZE_UNTRUSTED);
+    const block: DocumentBlock = {
+      index: blocks.length,
+      type: token.type,
+      startLine,
+      endLine,
+      startOffset: offset - raw.length,
+      endOffset: offset - (raw.match(/\n+$/)?.[0].length ?? 0),
+      raw,
+      html,
+    };
+    if (token.type === 'heading') {
+      const heading = token as Tokens.Heading;
+      block.headingLevel = heading.depth;
+      block.headingText = heading.text.trim();
+    }
+    blocks.push(block);
+  }
+  return blocks;
+}
+
+/** Blocks from a heading through the end of its section (next heading of the same or a higher level). */
+export function sectionRange(
+  blocks: readonly DocumentBlock[],
+  headingIndex: number,
+): [number, number] {
+  const heading = blocks[headingIndex];
+  if (!heading || heading.headingLevel === undefined) return [headingIndex, headingIndex];
+  let end = headingIndex;
+  for (let i = headingIndex + 1; i < blocks.length; i++) {
+    const level = blocks[i].headingLevel;
+    if (level !== undefined && level <= heading.headingLevel) break;
+    end = i;
+  }
+  return [headingIndex, end];
+}
+
+/** Nearest heading at or above a block, for labelling a selection. */
+export function nearestHeading(
+  blocks: readonly DocumentBlock[],
+  index: number,
+): string | undefined {
+  for (let i = Math.min(index, blocks.length - 1); i >= 0; i--) {
+    if (blocks[i].headingText) return blocks[i].headingText;
+  }
+  return undefined;
+}
+
+function blockKey(block: DocumentBlock): string {
+  return block.raw.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Marks which blocks changed between a base and a candidate using a longest
+ * common subsequence over block text. Unmatched base blocks that sit next
+ * to unmatched candidate blocks count as `changed` rather than removed+added.
+ */
+export function diffBlocks(
+  base: readonly DocumentBlock[],
+  candidate: readonly DocumentBlock[],
+): { base: BlockChange[]; candidate: BlockChange[] } {
+  const a = base.map(blockKey);
+  const b = candidate.map(blockKey);
+  const n = a.length;
+  const m = b.length;
+  const lcs: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const baseStatus: BlockChange[] = new Array(n).fill('removed');
+  const candStatus: BlockChange[] = new Array(m).fill('added');
+  let i = 0;
+  let j = 0;
+  // Walk the LCS; between matches, pair up the unmatched runs as "changed".
+  const pairRuns = (bi: number, bj: number, ei: number, ej: number) => {
+    const baseRun = ei - bi;
+    const candRun = ej - bj;
+    if (baseRun > 0 && candRun > 0) {
+      for (let k = bj; k < ej; k++) candStatus[k] = 'changed';
+      for (let k = bi; k < ei; k++) baseStatus[k] = 'changed';
+    }
+  };
+  let runStartI = 0;
+  let runStartJ = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      pairRuns(runStartI, runStartJ, i, j);
+      baseStatus[i] = 'same';
+      candStatus[j] = 'same';
+      i++;
+      j++;
+      runStartI = i;
+      runStartJ = j;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  pairRuns(runStartI, runStartJ, n, m);
+  return { base: baseStatus, candidate: candStatus };
+}
+
+/** Plain text of a block range, suitable for quoting in a prompt. */
+export function blockRangeText(blocks: readonly DocumentBlock[], from: number, to: number): string {
+  return blocks
+    .slice(from, to + 1)
+    .map((b) => b.raw.replace(/\n+$/, ''))
+    .join('\n\n');
+}
diff --git a/src/documents/path-tree.test.ts b/src/documents/path-tree.test.ts
new file mode 100644
index 000000000..12f7c23c2
--- /dev/null
+++ b/src/documents/path-tree.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { buildPathTree } from './path-tree';
+
+describe('buildPathTree', () => {
+  it('nests folders before files, both sorted by name', () => {
+    const tree = buildPathTree(['readme.md', 'src/b.md', 'src/a.md', 'assets/logo.png', 'a.md']);
+    expect(tree.map((n) => n.path)).toEqual(['assets', 'src', 'a.md', 'readme.md']);
+    expect(tree[1].children.map((n) => n.path)).toEqual(['src/a.md', 'src/b.md']);
+    expect(tree[1].children[0].children).toEqual([]);
+  });
+
+  it('is empty for no paths', () => {
+    expect(buildPathTree([])).toEqual([]);
+  });
+});
diff --git a/src/documents/path-tree.ts b/src/documents/path-tree.ts
new file mode 100644
index 000000000..19cad3729
--- /dev/null
+++ b/src/documents/path-tree.ts
@@ -0,0 +1,41 @@
+/** A folder or file in the project's file tree. */
+export interface PathTreeNode {
+  name: string;
+  /** Repo-relative path. */
+  path: string;
+  /** Empty for a file. */
+  children: PathTreeNode[];
+}
+
+/** Repo-relative paths as a tree: folders first, then files, both alphabetical. */
+export function buildPathTree(paths: readonly string[]): PathTreeNode[] {
+  interface Raw {
+    children: Map<string, Raw>;
+    isFile: boolean;
+  }
+  const root: Raw = { children: new Map(), isFile: false };
+  for (const full of paths) {
+    const parts = full.split('/').filter(Boolean);
+    let node = root;
+    parts.forEach((part, i) => {
+      let next = node.children.get(part);
+      if (!next) {
+        next = { children: new Map(), isFile: false };
+        node.children.set(part, next);
+      }
+      if (i === parts.length - 1) next.isFile = true;
+      node = next;
+    });
+  }
+  const convert = (node: Raw, parentPath: string): PathTreeNode[] =>
+    [...node.children.entries()]
+      .sort(([aName, a], [bName, b]) => {
+        if (a.isFile !== b.isFile) return a.isFile ? 1 : -1;
+        return aName.localeCompare(bName);
+      })
+      .map(([name, child]) => {
+        const path = parentPath ? `${parentPath}/${name}` : name;
+        return { name, path, children: child.isFile ? [] : convert(child, path) };
+      });
+  return convert(root, '');
+}
diff --git a/src/documents/render-document.test.ts b/src/documents/render-document.test.ts
new file mode 100644
index 000000000..2c8377ffa
--- /dev/null
+++ b/src/documents/render-document.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('../lib/shiki-highlighter', () => ({
+  highlightLines: async (code: string) => code.split('\n').map((l) => `<span>${l}</span>`),
+}));
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+
+import { renderDocument } from './render-document';
+
+describe('renderDocument', () => {
+  it('renders markdown with no stylesheet', async () => {
+    const result = await renderDocument('# Title\n\nText <b>with</b> html.\n');
+    expect(result.page).toBeNull();
+    expect(result.blocks.map((b) => b.type)).toEqual(['heading', 'paragraph']);
+  });
+
+  it('renders a whole page as element blocks with its stylesheet', async () => {
+    const result = await renderDocument(
+      '<!doctype html>\r\n<html><head><style>p { x: y }</style></head>\r\n<body>\r\n<p>Hi</p>\r\n</body></html>',
+    );
+    expect(result.page?.stylesheet).toBe('p { x: y }');
+    expect(result.blocks.map((b) => [b.type, b.startLine])).toEqual([['p', 4]]);
+  });
+});
diff --git a/src/documents/render-document.ts b/src/documents/render-document.ts
new file mode 100644
index 000000000..eed410a5a
--- /dev/null
+++ b/src/documents/render-document.ts
@@ -0,0 +1,19 @@
+import { renderHtmlBlocks } from './html-blocks';
+import { isHtmlDocument } from './html-document';
+import { normalizeSource, renderDocumentBlocks, type DocumentBlock } from './markdown-blocks';
+import type { PageRender } from './PageBlocks';
+
+export interface RenderedDocument {
+  blocks: DocumentBlock[];
+  /** Present for a whole HTML page: its marked-up body and its own stylesheet. */
+  page: PageRender | null;
+}
+
+/** Markdown renders through marked; a whole HTML page becomes its element blocks. */
+export async function renderDocument(source: string): Promise<RenderedDocument> {
+  if (isHtmlDocument(source)) {
+    const { blocks, stylesheet, html } = renderHtmlBlocks(normalizeSource(source));
+    return { blocks, page: { stylesheet, html } };
+  }
+  return { blocks: await renderDocumentBlocks(source), page: null };
+}
diff --git a/src/documents/store.ts b/src/documents/store.ts
new file mode 100644
index 000000000..2fe7a5105
--- /dev/null
+++ b/src/documents/store.ts
@@ -0,0 +1,837 @@
+/**
+ * Document workspace state: the rendered canonical document, the runs made
+ * against it, and the comparison/history views. Kept apart from the task
+ * store because none of it is a task: proposals live in Git, not in panels.
+ */
+import { untrack } from 'solid-js';
+import { createStore, produce } from 'solid-js/store';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { errMessage } from '../lib/log';
+import type { AgentDef } from '../ipc/types';
+import type {
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationKind,
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from './types';
+import {
+  DEFAULT_DOCUMENT_MAIN_AGENT,
+  MAX_DOCUMENT_CANDIDATES,
+  documentAgentSupport,
+} from '../../electron/documents/shared';
+import { store, setStore } from '../store/core';
+import { getProject, updateProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import type { DocumentModelChoice, Project } from '../store/types';
+
+export type DocumentView = 'document' | 'history';
+
+/** A block-aligned selection in the rendered document. */
+export interface DocumentSelection {
+  startBlock: number;
+  endBlock: number;
+  startLine: number;
+  endLine: number;
+  quote: string;
+  heading?: string;
+  wholeDocument: boolean;
+}
+
+/** What the composer does with the passage. */
+export type ComposerMode = 'task' | 'proposals' | 'note' | 'question';
+
+/** What the composer opens with: a bubble turned into a task, or a block's hover action. */
+export interface ComposerDraft {
+  text: string;
+  annotationId?: string;
+  /** Opens the composer on this mode. */
+  mode?: ComposerMode;
+}
+
+interface DocumentWorkspaceState {
+  projectId: string | null;
+  /** Repo-relative path of the document on screen; the project's document
+   *  until a link or the file tree opens another. */
+  documentPath: string | null;
+  annotations: DocumentAnnotation[];
+  /** Last deleted bubble, kept for a single-step undo. */
+  lastDeleted: DocumentAnnotation | null;
+  showResolved: boolean;
+  composerDraft: ComposerDraft | null;
+  snapshot: DocumentSnapshot | null;
+  loading: boolean;
+  error: string | null;
+  runs: Record<string, DocumentRunRecord>;
+  runOrder: string[];
+  /** Streamed log lines per candidate id, bounded. */
+  logs: Record<string, string[]>;
+  view: DocumentView;
+  compareRunId: string | null;
+  selection: DocumentSelection | null;
+  dispatching: boolean;
+}
+
+const MAX_LOG_LINES = 400;
+
+const [docStore, setDocStore] = createStore<DocumentWorkspaceState>({
+  projectId: null,
+  documentPath: null,
+  annotations: [],
+  lastDeleted: null,
+  showResolved: false,
+  composerDraft: null,
+  snapshot: null,
+  loading: false,
+  error: null,
+  runs: {},
+  runOrder: [],
+  logs: {},
+  view: 'document',
+  compareRunId: null,
+  selection: null,
+  dispatching: false,
+});
+
+export { docStore as documentStore };
+
+function activeProject(): Project | undefined {
+  return docStore.projectId ? getProject(docStore.projectId) : undefined;
+}
+
+/** The document on screen, or null when no workspace is open. */
+export function activeDocumentPath(): string | null {
+  return docStore.documentPath;
+}
+
+function requireProject(): { project: Project; documentPath: string } {
+  const project = activeProject();
+  const documentPath = docStore.documentPath;
+  if (!project || !documentPath) throw new Error('No document project is open.');
+  return { project, documentPath };
+}
+
+/** One watcher per document on screen; a stale event from the last document
+ *  carries the old key and is dropped. */
+function watcherKey(projectId: string, documentPath: string): string {
+  return `doc:${projectId}:${documentPath}`;
+}
+
+function currentWatcherKey(): string | null {
+  return docStore.projectId && docStore.documentPath
+    ? watcherKey(docStore.projectId, docStore.documentPath)
+    : null;
+}
+
+/** True while the workspace still shows the project a request was made for. */
+function stillOpen(projectId: string): boolean {
+  return docStore.projectId === projectId;
+}
+
+export async function refreshDocumentSnapshot(): Promise<void> {
+  const project = activeProject();
+  const documentPath = docStore.documentPath;
+  if (!project || !documentPath) return;
+  try {
+    const snapshot = await invoke<DocumentSnapshot>(IPC.ReadDocument, {
+      projectRoot: project.path,
+      documentPath,
+    });
+    if (stillOpen(project.id) && docStore.documentPath === documentPath)
+      setDocStore({ snapshot, error: null });
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+function sortRunIds(runs: Record<string, DocumentRunRecord>): string[] {
+  return Object.values(runs)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+    .map((r) => r.id);
+}
+
+export async function loadDocumentRuns(): Promise<void> {
+  const project = activeProject();
+  if (!project) return;
+  try {
+    const runs = await invoke<DocumentRunRecord[]>(IPC.ListDocumentRuns, {
+      projectRoot: project.path,
+    });
+    const byId: Record<string, DocumentRunRecord> = {};
+    for (const run of runs) byId[run.id] = run;
+    if (!stillOpen(project.id)) return;
+    setDocStore(
+      produce((s) => {
+        s.runs = byId;
+        s.runOrder = sortRunIds(byId);
+      }),
+    );
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+function stopCurrentWatcher(): void {
+  const key = currentWatcherKey();
+  if (key) void invoke(IPC.StopDocumentWatcher, { key }).catch(() => undefined);
+}
+
+/** Watches the document on screen; replaces whatever was watched before. */
+function startWatcher(projectId: string, projectRoot: string, documentPath: string): void {
+  void invoke(IPC.StartDocumentWatcher, {
+    key: watcherKey(projectId, documentPath),
+    projectRoot,
+    documentPath,
+  }).catch((err) => {
+    untrack(() => {
+      if (stillOpen(projectId)) setDocStore('error', errMessage(err));
+    });
+  });
+}
+
+export async function openDocumentWorkspace(projectId: string): Promise<void> {
+  const project = getProject(projectId);
+  if (!project?.documentPath || !store.documentWorkspacesEnabled) return;
+  if (docStore.projectId && docStore.projectId !== projectId) stopCurrentWatcher();
+  setDocStore({
+    projectId,
+    documentPath: project.documentPath,
+    snapshot: null,
+    loading: true,
+    error: null,
+    runs: {},
+    runOrder: [],
+    logs: {},
+    view: 'document',
+    compareRunId: null,
+    selection: null,
+    annotations: [],
+    lastDeleted: null,
+    composerDraft: null,
+  });
+  setStore('activeDocumentProjectId', projectId);
+  // Start watching before the first await so a quick close can stop it.
+  startWatcher(projectId, project.path, project.documentPath);
+  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns(), loadDocumentAnnotations()]);
+  if (stillOpen(projectId)) setDocStore('loading', false);
+}
+
+/**
+ * Shows another file of the open project: the target of an internal link or a
+ * pick in the file tree. The selection belongs to the old document and goes;
+ * runs and annotations are per project and stay.
+ */
+export async function openDocumentFile(documentPath: string): Promise<void> {
+  const project = activeProject();
+  if (!project || docStore.documentPath === documentPath) return;
+  stopCurrentWatcher();
+  setDocStore({ documentPath, selection: null, composerDraft: null, snapshot: null, error: null });
+  startWatcher(project.id, project.path, documentPath);
+  await refreshDocumentSnapshot();
+}
+
+export function closeDocumentWorkspace(): void {
+  stopCurrentWatcher();
+  setDocStore({
+    projectId: null,
+    documentPath: null,
+    selection: null,
+    view: 'document',
+    compareRunId: null,
+    composerDraft: null,
+  });
+  setStore('activeDocumentProjectId', null);
+}
+
+export function setDocumentComposerDraft(draft: ComposerDraft | null): void {
+  setDocStore('composerDraft', draft);
+}
+
+export function setDocumentView(view: DocumentView): void {
+  setDocStore('view', view);
+}
+
+export function setDocumentSelection(selection: DocumentSelection | null): void {
+  setDocStore('selection', selection);
+}
+
+/** Opens the compare view, a modal over whatever tab is up. */
+export function openDocumentCompare(runId: string): void {
+  setDocStore('compareRunId', runId);
+}
+
+export function closeDocumentCompare(): void {
+  setDocStore('compareRunId', null);
+}
+
+/** Runs with at least one proposal to look at. */
+export function reviewableRuns(): DocumentRunRecord[] {
+  return docStore.runOrder
+    .map((id) => docStore.runs[id])
+    .filter(
+      (r) =>
+        (r.status === 'finished' || r.status === 'stale') && r.candidates.some((c) => c.commitSha),
+    );
+}
+
+export function candidateLogKey(runId: string, candidateId: string): string {
+  return `${runId}/${candidateId}`;
+}
+
+/** Agent that owns the main session; falls back to the first resumable one installed. */
+export function documentMainAgentId(project: Project | undefined): string {
+  if (project?.documentMainAgentId) return project.documentMainAgentId;
+  const installed = store.availableAgents.filter((a) => a.available !== false);
+  const preferred = installed.find((a) => a.id === DEFAULT_DOCUMENT_MAIN_AGENT);
+  if (preferred) return preferred.id;
+  return (
+    installed.find((a) => documentAgentSupport(a.id).resume)?.id ?? DEFAULT_DOCUMENT_MAIN_AGENT
+  );
+}
+
+export function setDocumentMainAgent(agentId: string): void {
+  const project = activeProject();
+  if (project) updateProject(project.id, { documentMainAgentId: agentId });
+}
+
+export interface DispatchSelection {
+  agent: AgentDef;
+  count: number;
+  /** Model and reasoning level per candidate of this agent, in order; the
+   *  CLI's defaults where a slot is missing or empty. */
+  choices?: readonly DocumentModelChoice[];
+}
+
+/** "opus · high": how a candidate's model and reasoning level read in the UI. */
+export function modelLabel(choice: DocumentModelChoice): string {
+  return [choice.model, choice.effort].filter(Boolean).join(' · ');
+}
+
+/** The remembered choices for an agent's candidates, first slot first. */
+export function documentModelChoices(
+  project: Project | undefined,
+  agentId: string,
+): DocumentModelChoice[] {
+  const stored: unknown = project?.documentModels?.[agentId];
+  // State saved while the choice was per agent holds one object here.
+  return Array.isArray(stored) ? stored : [];
+}
+
+/** `list` with slot `index` set to `choice`: dense, and without trailing empty slots. */
+export function withModelChoice(
+  list: readonly DocumentModelChoice[],
+  index: number,
+  choice: DocumentModelChoice,
+): DocumentModelChoice[] {
+  const next = Array.from({ length: Math.max(list.length, index + 1) }, (_, i) => list[i] ?? {});
+  next[index] = choice;
+  while (next.length > 0 && !next[next.length - 1].model && !next[next.length - 1].effort) {
+    next.pop();
+  }
+  return next;
+}
+
+/** Remember the composer's choice for one candidate slot, so the next run starts from it. */
+export function setDocumentModelChoice(
+  agentId: string,
+  index: number,
+  choice: DocumentModelChoice,
+): void {
+  const project = activeProject();
+  if (!project) return;
+  const list = withModelChoice(documentModelChoices(project, agentId), index, choice);
+  const rest = Object.fromEntries(
+    Object.entries(project.documentModels ?? {}).filter(([id]) => id !== agentId),
+  );
+  updateProject(project.id, {
+    documentModels: list.length > 0 ? { ...rest, [agentId]: list } : rest,
+  });
+}
+
+function buildScope(selection: DocumentSelection, documentPath: string): DocumentScope {
+  return {
+    path: documentPath,
+    wholeDocument: selection.wholeDocument,
+    startLine: selection.startLine,
+    endLine: selection.endLine,
+    quote: selection.quote,
+    heading: selection.heading,
+  };
+}
+
+function candidateLabel(index: number): string {
+  return String.fromCharCode('A'.charCodeAt(0) + index);
+}
+
+/** Turns the composer's choices into candidate specs: one main, the rest alternates. */
+export function buildCandidateSpecs(
+  project: Project,
+  picks: readonly DispatchSelection[],
+  envFiles: Record<string, string>,
+): DocumentCandidateSpec[] {
+  const mainAgentId = documentMainAgentId(project);
+  const specs: DocumentCandidateSpec[] = [];
+  let index = 0;
+  for (const pick of picks) {
+    const support = documentAgentSupport(pick.agent.id);
+    if (!support.headless) continue;
+    for (let i = 0; i < pick.count; i++) {
+      if (specs.length >= MAX_DOCUMENT_CANDIDATES) break;
+      const isMain = pick.agent.id === mainAgentId && i === 0 && support.resume;
+      const session = isMain ? project.documentSessions?.[pick.agent.id] : undefined;
+      const choice = pick.choices?.[i];
+      specs.push({
+        id: `c${index + 1}`,
+        label: candidateLabel(index),
+        agentId: pick.agent.id,
+        agentName: pick.agent.name,
+        command: pick.agent.command,
+        isMain,
+        model: choice?.model,
+        effort: choice?.effort,
+        sessionId: session?.sessionId,
+        sessionLastSha: session?.lastSha,
+        envFile: envFiles[pick.agent.id],
+      });
+      index++;
+    }
+  }
+  return specs;
+}
+
+export async function dispatchDocumentRun(
+  instruction: string,
+  picks: readonly DispatchSelection[],
+  selection: DocumentSelection,
+): Promise<DocumentRunRecord | null> {
+  const { project, documentPath } = requireProject();
+  const candidates = buildCandidateSpecs(project, picks, store.agentEnvFiles);
+  if (candidates.length === 0) throw new Error('Pick at least one agent with a headless mode.');
+  setDocStore('dispatching', true);
+  try {
+    const run = await invoke<DocumentRunRecord>(IPC.DispatchDocumentRun, {
+      projectRoot: project.path,
+      documentPath,
+      instruction,
+      scope: buildScope(selection, documentPath),
+      candidates,
+    });
+    upsertRun(run);
+    const draft = docStore.composerDraft;
+    setDocStore({ selection: null, composerDraft: null });
+    if (draft?.annotationId) void linkAnnotationToRun(draft.annotationId, run.id);
+    void refreshDocumentSnapshot();
+    return run;
+  } finally {
+    setDocStore('dispatching', false);
+  }
+}
+
+function upsertRun(run: DocumentRunRecord): void {
+  setDocStore(
+    produce((s) => {
+      s.runs[run.id] = run;
+      s.runOrder = sortRunIds(s.runs);
+    }),
+  );
+}
+
+/** Remember the main session so the next dispatch resumes it. The event names
+ *  the project root because the run may finish after its workspace was closed
+ *  or another project was opened. */
+function recordMainSession(
+  projectRoot: string,
+  run: DocumentRunRecord,
+  candidate: DocumentCandidateRecord,
+): void {
+  if (!candidate.isMain || !candidate.sessionId) return;
+  const project = store.projects.find((p) => p.path === projectRoot && p.kind === 'document');
+  if (!project) return;
+  updateProject(project.id, {
+    documentSessions: {
+      ...(project.documentSessions ?? {}),
+      [candidate.agentId]: { sessionId: candidate.sessionId, lastSha: run.baseSha },
+    },
+  });
+}
+
+export function applyDocumentRunEvent(event: DocumentRunEvent): void {
+  const forOpenProject = activeProject()?.path === event.projectRoot;
+  switch (event.type) {
+    case 'log':
+      if (!forOpenProject) return;
+      setDocStore(
+        produce((s) => {
+          const key = candidateLogKey(event.runId, event.candidateId);
+          const lines = s.logs[key] ?? [];
+          lines.push(event.text);
+          if (lines.length > MAX_LOG_LINES) lines.splice(0, lines.length - MAX_LOG_LINES);
+          s.logs[key] = lines;
+        }),
+      );
+      return;
+    case 'candidate': {
+      const run = docStore.runs[event.runId];
+      if (run) recordMainSession(event.projectRoot, run, event.candidate);
+      if (!forOpenProject || !run) return;
+      setDocStore(
+        produce((s) => {
+          const target = s.runs[event.runId];
+          const idx = target.candidates.findIndex((c) => c.id === event.candidate.id);
+          if (idx >= 0) target.candidates[idx] = event.candidate;
+          else target.candidates.push(event.candidate);
+        }),
+      );
+      return;
+    }
+    case 'run': {
+      if (event.run.status === 'finished') {
+        for (const c of event.run.candidates) recordMainSession(event.projectRoot, event.run, c);
+      }
+      if (!forOpenProject) return;
+      upsertRun(event.run);
+      if (event.run.status === 'finished') {
+        setDocStore(
+          produce((s) => {
+            s.logs = Object.fromEntries(
+              Object.entries(s.logs).filter(([key]) => !key.startsWith(`${event.run.id}/`)),
+            );
+          }),
+        );
+        const proposals = event.run.candidates.filter((c) => c.commitSha).length;
+        showNotification(
+          proposals > 0
+            ? `${proposals} proposal${proposals === 1 ? '' : 's'} ready to compare`
+            : 'Run finished without changes',
+        );
+      }
+      return;
+    }
+  }
+}
+
+/** `partial` carries the composed document when the reader declined some changes. */
+export async function acceptDocumentCandidate(
+  runId: string,
+  candidateId: string,
+  partial?: { content: string; accepted: number; total: number },
+): Promise<void> {
+  const { project } = requireProject();
+  try {
+    await invoke<{ sha: string }>(IPC.AcceptDocumentCandidate, {
+      projectRoot: project.path,
+      runId,
+      candidateId,
+      partial,
+    });
+    showNotification(
+      partial ? `Accepted ${partial.accepted} of ${partial.total} changes` : 'Proposal accepted',
+    );
+    setDocStore('compareRunId', null);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+  await Promise.all([loadDocumentRuns(), refreshDocumentSnapshot()]);
+}
+
+export async function refineDocumentCandidate(
+  run: DocumentRunRecord,
+  candidate: DocumentCandidateRecord,
+  instruction: string,
+): Promise<void> {
+  const { project } = requireProject();
+  const agent = store.availableAgents.find(
+    (a) => a.id === candidate.agentId && a.available !== false,
+  );
+  if (!agent) throw new Error('Install or enable this candidate’s agent to refine it.');
+  const candidates = buildCandidateSpecs(
+    project,
+    [
+      {
+        agent,
+        count: 1,
+        choices: [{ model: candidate.model, effort: candidate.effort }],
+      },
+    ],
+    store.agentEnvFiles,
+  ).map((spec) => ({
+    ...spec,
+    isMain: false,
+    sessionId: undefined,
+    sessionLastSha: undefined,
+  }));
+  const revision = await invoke<DocumentRunRecord>(IPC.DispatchDocumentRun, {
+    projectRoot: project.path,
+    documentPath: run.documentPath,
+    instruction,
+    scope: { wholeDocument: true },
+    candidates,
+    refinement: { runId: run.id, candidateId: candidate.id },
+  });
+  if (stillOpen(project.id)) upsertRun(revision);
+  showNotification('Refinement started. The new proposal will appear in Runs.');
+}
+
+export async function rejectDocumentRun(runId: string): Promise<void> {
+  const { project } = requireProject();
+  try {
+    const run = await invoke<DocumentRunRecord>(IPC.RejectDocumentRun, {
+      projectRoot: project.path,
+      runId,
+    });
+    upsertRun(run);
+    if (docStore.compareRunId === runId) setDocStore('compareRunId', null);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+  void refreshDocumentSnapshot();
+}
+
+export async function cancelDocumentRun(runId: string): Promise<void> {
+  await invoke(IPC.CancelDocumentRun, { runId }).catch((err) => showNotification(errMessage(err)));
+}
+
+export async function setDocumentCandidateNote(
+  runId: string,
+  candidateId: string,
+  note: string,
+): Promise<void> {
+  const { project } = requireProject();
+  try {
+    const run = await invoke<DocumentRunRecord>(IPC.SetDocumentCandidateNote, {
+      projectRoot: project.path,
+      runId,
+      candidateId,
+      note,
+    });
+    upsertRun(run);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+export async function revertDocumentCommit(sha: string): Promise<boolean> {
+  const { project } = requireProject();
+  try {
+    await invoke(IPC.RevertDocumentCommit, { projectRoot: project.path, sha });
+    showNotification('Reverted');
+    void refreshDocumentSnapshot();
+    return true;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return false;
+  }
+}
+
+// --- Annotations ----------------------------------------------------------
+
+export async function loadDocumentAnnotations(): Promise<void> {
+  const project = activeProject();
+  if (!project) return;
+  try {
+    const annotations = await invoke<DocumentAnnotation[]>(IPC.ListDocumentAnnotations, {
+      projectRoot: project.path,
+    });
+    if (stillOpen(project.id)) setDocStore('annotations', annotations);
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+function putAnnotation(annotation: DocumentAnnotation): void {
+  setDocStore(
+    produce((s) => {
+      const idx = s.annotations.findIndex((a) => a.id === annotation.id);
+      if (idx >= 0) s.annotations[idx] = annotation;
+      else s.annotations.push(annotation);
+    }),
+  );
+}
+
+async function persistAnnotation(annotation: DocumentAnnotation): Promise<DocumentAnnotation> {
+  const { project } = requireProject();
+  const saved = await invoke<DocumentAnnotation>(IPC.SaveDocumentAnnotation, {
+    projectRoot: project.path,
+    annotation,
+  });
+  putAnnotation(saved);
+  return saved;
+}
+
+/** Creates a note or a question on the anchored passage. Questions are asked right away. */
+export async function addDocumentAnnotation(
+  kind: DocumentAnnotationKind,
+  text: string,
+  anchor: DocumentAnchor,
+  askWith?: AgentDef,
+): Promise<DocumentAnnotation | null> {
+  const now = new Date().toISOString();
+  try {
+    const saved = await persistAnnotation({
+      id: crypto.randomUUID(),
+      kind,
+      anchor,
+      text,
+      createdAt: now,
+      updatedAt: now,
+      resolved: false,
+    });
+    if (kind === 'question' && askWith) await askDocumentAnnotation(saved.id, askWith);
+    return saved;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return null;
+  }
+}
+
+export async function askDocumentAnnotation(annotationId: string, agent: AgentDef): Promise<void> {
+  const { project } = requireProject();
+  const current = docStore.annotations.find((a) => a.id === annotationId);
+  try {
+    const pending = await invoke<DocumentAnnotation>(IPC.AskDocumentAnnotation, {
+      projectRoot: project.path,
+      // The question is about the passage's own document, whichever is on screen now.
+      documentPath: current?.anchor.path ?? docStore.documentPath,
+      annotationId,
+      agentId: agent.id,
+      agentName: agent.name,
+      command: agent.command,
+      envFile: store.agentEnvFiles[agent.id],
+    });
+    putAnnotation(pending);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+export async function setDocumentAnnotationResolved(id: string, resolved: boolean): Promise<void> {
+  const current = docStore.annotations.find((a) => a.id === id);
+  if (!current) return;
+  try {
+    await persistAnnotation({ ...current, resolved });
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+export async function updateDocumentAnnotationText(id: string, text: string): Promise<void> {
+  const current = docStore.annotations.find((a) => a.id === id);
+  if (!current || current.text === text) return;
+  try {
+    await persistAnnotation({ ...current, text });
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+/** One click removes a bubble; the last one removed can be brought back. */
+export async function deleteDocumentAnnotation(id: string): Promise<void> {
+  const { project } = requireProject();
+  const current = docStore.annotations.find((a) => a.id === id);
+  if (!current) return;
+  setDocStore(
+    produce((s) => {
+      s.annotations = s.annotations.filter((a) => a.id !== id);
+      s.lastDeleted = current;
+    }),
+  );
+  try {
+    await invoke(IPC.DeleteDocumentAnnotation, { projectRoot: project.path, id });
+  } catch (err) {
+    showNotification(errMessage(err));
+    putAnnotation(current);
+    setDocStore('lastDeleted', null);
+  }
+}
+
+export async function undoDeleteDocumentAnnotation(): Promise<void> {
+  const last = docStore.lastDeleted;
+  if (!last) return;
+  setDocStore('lastDeleted', null);
+  try {
+    await persistAnnotation(last);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+export function dismissUndo(): void {
+  setDocStore('lastDeleted', null);
+}
+
+export function setShowResolvedAnnotations(show: boolean): void {
+  setDocStore('showResolved', show);
+}
+
+/** Marks a bubble as turned into a run; the bubble collapses but stays. */
+export async function linkAnnotationToRun(annotationId: string, runId: string): Promise<void> {
+  const current = docStore.annotations.find((a) => a.id === annotationId);
+  if (!current) return;
+  try {
+    await persistAnnotation({ ...current, runId, resolved: true });
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+function isAnnotationEvent(v: unknown): v is DocumentAnnotationEvent {
+  if (!v || typeof v !== 'object') return false;
+  const e = v as { projectRoot?: unknown; annotation?: unknown };
+  return typeof e.projectRoot === 'string' && !!e.annotation && typeof e.annotation === 'object';
+}
+
+interface DocumentChangedPayload {
+  key: string;
+  snapshot: DocumentSnapshot;
+}
+
+function isRunEvent(v: unknown): v is DocumentRunEvent {
+  if (!v || typeof v !== 'object') return false;
+  const e = v as { type?: unknown; projectRoot?: unknown };
+  return typeof e.type === 'string' && typeof e.projectRoot === 'string';
+}
+
+/** Subscribes to main-process pushes; call once at startup. Returns a disposer. */
+export function initDocumentListeners(): () => void {
+  const offRun = window.electron.ipcRenderer.on(IPC.DocumentRunEvent, (payload: unknown) => {
+    if (isRunEvent(payload)) untrack(() => applyDocumentRunEvent(payload));
+  });
+  const offAnnotation = window.electron.ipcRenderer.on(
+    IPC.DocumentAnnotationEvent,
+    (payload: unknown) => {
+      if (!isAnnotationEvent(payload)) return;
+      untrack(() => {
+        if (activeProject()?.path === payload.projectRoot) putAnnotation(payload.annotation);
+      });
+    },
+  );
+  const offChanged = window.electron.ipcRenderer.on(IPC.DocumentChanged, (payload: unknown) => {
+    const p = payload as DocumentChangedPayload | undefined;
+    if (!p) return;
+    untrack(() => {
+      if (p.key !== currentWatcherKey()) return;
+      // Read what is being replaced first: `setStore` merges into the node the
+      // old snapshot is a proxy over, so afterwards it reads the new values.
+      const previous = docStore.snapshot;
+      const hadSnapshot = !!previous;
+      const previousContent = previous?.content;
+      const previousHeadSha = previous?.headSha;
+      setDocStore('snapshot', p.snapshot);
+      // The passage under a selection may be gone after an external edit, and a
+      // commit or pull may have brought annotations along.
+      if (hadSnapshot && previousContent !== p.snapshot.content) setDocStore('selection', null);
+      if (hadSnapshot && previousHeadSha !== p.snapshot.headSha) void loadDocumentAnnotations();
+    });
+  });
+  return () => {
+    offRun();
+    offAnnotation();
+    offChanged();
+  };
+}
diff --git a/src/documents/types.ts b/src/documents/types.ts
new file mode 100644
index 000000000..74096439a
--- /dev/null
+++ b/src/documents/types.ts
@@ -0,0 +1,2 @@
+/** The document workspace's IPC shapes, mirrored for the renderer. */
+export type * from '../../electron/documents/types';
diff --git a/src/documents/use-blocks.ts b/src/documents/use-blocks.ts
new file mode 100644
index 000000000..fa8a4e118
--- /dev/null
+++ b/src/documents/use-blocks.ts
@@ -0,0 +1,48 @@
+import { createEffect, createSignal, onCleanup } from 'solid-js';
+import type { DocumentBlock } from './markdown-blocks';
+import type { PageRender } from './PageBlocks';
+import { renderDocument } from './render-document';
+
+/**
+ * Reactively renders a document source into blocks. Stale renders are dropped
+ * when the source changes again before they finish.
+ */
+export function createRenderedBlocks(source: () => string | null | undefined): {
+  blocks: () => DocumentBlock[];
+  /** The page's markup and stylesheet when the source is a whole HTML page. */
+  page: () => PageRender | null;
+  rendering: () => boolean;
+} {
+  const [blocks, setBlocks] = createSignal<DocumentBlock[]>([]);
+  const [page, setPage] = createSignal<PageRender | null>(null);
+  const [rendering, setRendering] = createSignal(false);
+  let generation = 0;
+
+  createEffect(() => {
+    const content = source();
+    const gen = ++generation;
+    if (content === null || content === undefined) {
+      setBlocks([]);
+      setPage(null);
+      setRendering(false);
+      return;
+    }
+    setRendering(true);
+    renderDocument(content)
+      .then((result) => {
+        if (gen !== generation) return;
+        setBlocks(result.blocks);
+        setPage(result.page);
+      })
+      .catch((err) => console.warn('[documents] render failed:', err))
+      .finally(() => {
+        if (gen === generation) setRendering(false);
+      });
+  });
+
+  onCleanup(() => {
+    generation++;
+  });
+
+  return { blocks, page, rendering };
+}
diff --git a/src/documents/workspace-ui.ts b/src/documents/workspace-ui.ts
new file mode 100644
index 000000000..f8197f0d3
--- /dev/null
+++ b/src/documents/workspace-ui.ts
@@ -0,0 +1,63 @@
+/**
+ * Panel state of the open workspace: the project's files, which rail tab is
+ * up, the one-shot output being read, and whether the interactive agent is
+ * live. Kept apart from the document store because none of it is about the
+ * document.
+ */
+import { createStore } from 'solid-js/store';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { errMessage } from '../lib/log';
+
+export type RailTab = 'agent' | 'runs' | 'files';
+
+/** A one-shot candidate whose output is open for reading. */
+export interface OutputTarget {
+  runId: string;
+  candidateId: string;
+}
+
+interface WorkspaceUiState {
+  files: string[];
+  filesError: string | null;
+  railTab: RailTab;
+  output: OutputTarget | null;
+  /** Set once the interactive agent's terminal has a live process behind it. */
+  agentRunning: boolean;
+}
+
+const [ui, setUi] = createStore<WorkspaceUiState>({
+  files: [],
+  filesError: null,
+  railTab: 'agent',
+  output: null,
+  agentRunning: false,
+});
+
+export { ui as workspaceUi };
+
+export async function loadDocumentFiles(projectRoot: string): Promise<void> {
+  try {
+    const files = await invoke<string[]>(IPC.ListDocumentFiles, { projectRoot });
+    setUi({ files, filesError: null });
+  } catch (err) {
+    setUi({ files: [], filesError: errMessage(err) });
+  }
+}
+
+export function setRailTab(tab: RailTab): void {
+  setUi('railTab', tab);
+}
+
+export function openCandidateOutput(target: OutputTarget | null): void {
+  setUi('output', target);
+}
+
+export function setAgentRunning(running: boolean): void {
+  setUi('agentRunning', running);
+}
+
+/** Back to the defaults when a workspace opens; files are per project. */
+export function resetWorkspaceUi(): void {
+  setUi({ files: [], filesError: null, railTab: 'agent', output: null, agentRunning: false });
+}
diff --git a/src/lib/marked-shiki.ts b/src/lib/marked-shiki.ts
index ccce3f662..00b25ec00 100644
--- a/src/lib/marked-shiki.ts
+++ b/src/lib/marked-shiki.ts
@@ -1,4 +1,5 @@
 import DOMPurify from 'dompurify';
+import { SANITIZE_UNTRUSTED } from './sanitize';
 import { Marked, type Tokens } from 'marked';
 import { createSignal, createEffect } from 'solid-js';
 import { highlightLines } from './shiki-highlighter';
@@ -44,7 +45,7 @@ export async function renderMarkdownWithHighlighting(markdown: string): Promise<
 
   marked.use({ renderer });
   const raw = marked.parser(tokens);
-  return DOMPurify.sanitize(raw, { ADD_ATTR: ['data-lang'] });
+  return DOMPurify.sanitize(raw, SANITIZE_UNTRUSTED);
 }
 
 interface TokenLike {
@@ -113,9 +114,10 @@ export function createHighlightedMarkdown(source: () => string | undefined): ()
       .catch(() => {
         if (thisGen === generation) {
           setHtml(
-            DOMPurify.sanitize(new Marked().parse(content, { async: false }) as string, {
-              ADD_ATTR: ['data-lang'],
-            }),
+            DOMPurify.sanitize(
+              new Marked().parse(content, { async: false }) as string,
+              SANITIZE_UNTRUSTED,
+            ),
           );
         }
       });
diff --git a/src/lib/mermaid.client.test.tsx b/src/lib/mermaid.client.test.tsx
new file mode 100644
index 000000000..2e3a1a681
--- /dev/null
+++ b/src/lib/mermaid.client.test.tsx
@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+import { renderMermaidIn } from './mermaid';
+
+const rendered: string[] = [];
+
+vi.mock('mermaid', () => ({
+  default: {
+    initialize: vi.fn(),
+    render: async (id: string, source: string) => {
+      rendered.push(source);
+      return { svg: `<svg id="${id}"></svg>` };
+    },
+  },
+}));
+
+async function waitFor<T>(probe: () => T | null | undefined): Promise<T> {
+  for (let attempt = 0; attempt < 200; attempt++) {
+    const value = probe();
+    if (value) return value;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  throw new Error('Condition never became true');
+}
+
+function host(html: string): HTMLElement {
+  const el = document.createElement('div');
+  el.innerHTML = html;
+  document.body.append(el);
+  return el;
+}
+
+describe('renderMermaidIn', () => {
+  it('renders a diagram whose data attribute the sanitizer stripped', async () => {
+    rendered.length = 0;
+    // What DOMPurify leaves of the placeholder: an arrow in the source means
+    // the whole data-mermaid attribute is dropped, the text stays.
+    const container = host('<div class="mermaid-block">graph TD;\n  A--&gt;B</div>');
+
+    renderMermaidIn(container, 'k');
+
+    await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    expect(rendered).toEqual(['graph TD;\n  A-->B']);
+    expect(container.querySelector('.mermaid-block')?.innerHTML).toContain('<svg');
+  });
+
+  it('still prefers the data attribute when it survived', async () => {
+    rendered.length = 0;
+    const container = host(
+      '<div class="mermaid-block" data-mermaid="graph TD; A---B">placeholder text</div>',
+    );
+
+    renderMermaidIn(container, 'k');
+
+    await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    expect(rendered).toEqual(['graph TD; A---B']);
+  });
+
+  it('leaves an empty placeholder alone', async () => {
+    rendered.length = 0;
+    const container = host('<div class="mermaid-block">   </div>');
+
+    renderMermaidIn(container, 'k');
+
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(rendered).toEqual([]);
+    expect(container.querySelector('.mermaid-rendered')).toBeNull();
+  });
+});
diff --git a/src/lib/mermaid.ts b/src/lib/mermaid.ts
new file mode 100644
index 000000000..9371f560a
--- /dev/null
+++ b/src/lib/mermaid.ts
@@ -0,0 +1,33 @@
+/**
+ * Renders the `.mermaid-block` placeholders that the markdown renderers emit
+ * for ```mermaid fences into SVG diagrams.
+ *
+ * @param container element holding the freshly inserted markdown HTML
+ * @param key unique per rendering surface, so ids stay distinct when the same
+ *   document is on screen twice (inline plan tab and plan dialog, for example)
+ */
+export function renderMermaidIn(container: HTMLElement | undefined, key: string): void {
+  if (!container) return;
+  const nodes = container.querySelectorAll<HTMLElement>('.mermaid-block:not(.mermaid-rendered)');
+  if (nodes.length === 0) return;
+  import('mermaid')
+    .then(({ default: mermaid }) => {
+      mermaid.initialize({ startOnLoad: false, theme: 'dark' });
+      nodes.forEach((el, i) => {
+        // The sanitizer strips any attribute whose value contains `-->`, which
+        // is most flowchart arrows, so `data-mermaid` is gone for exactly the
+        // diagrams people write most. The placeholder's own text is the same
+        // source and survives sanitizing, so fall back to it.
+        const source = el.getAttribute('data-mermaid') || el.textContent || '';
+        if (!source.trim()) return;
+        mermaid
+          .render(`mermaid-${key}-${Date.now()}-${i}`, source)
+          .then(({ svg }) => {
+            el.innerHTML = svg; // nosemgrep: semgrep.no-inner-html-without-sanitize -- mermaid renders its own sanitized SVG from local markdown
+            el.classList.add('mermaid-rendered');
+          })
+          .catch((err) => console.warn('[mermaid] render failed:', err));
+      });
+    })
+    .catch((err) => console.warn('[mermaid] load failed:', err));
+}
diff --git a/src/lib/sanitize.ts b/src/lib/sanitize.ts
new file mode 100644
index 000000000..cdab9495d
--- /dev/null
+++ b/src/lib/sanitize.ts
@@ -0,0 +1,11 @@
+/**
+ * One sanitize policy for markup the app did not write: document files, the
+ * pages they render, and everything an agent prints. `style` is not confined
+ * to the element it sits in, and the form controls can navigate the window the
+ * app itself runs in, so neither survives. `data-lang` is the code renderer's
+ * own attribute, which DOMPurify would otherwise drop.
+ */
+export const SANITIZE_UNTRUSTED = {
+  ADD_ATTR: ['data-lang'],
+  FORBID_TAGS: ['style', 'title', 'form', 'input', 'button', 'textarea', 'select'],
+};
diff --git a/src/store/autosave.ts b/src/store/autosave.ts
index 9cb53fe6f..33ce9f186 100644
--- a/src/store/autosave.ts
+++ b/src/store/autosave.ts
@@ -41,6 +41,7 @@ export function persistedSnapshot(): string {
     focusMode: store.focusMode,
     coordinatorNotificationDelayMs: store.coordinatorNotificationDelayMs,
     coordinatorModeEnabled: store.coordinatorModeEnabled,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed,
     autoStartRemoteAccess: store.autoStartRemoteAccess,
     shareDockerAgentAuth: store.shareDockerAgentAuth,
diff --git a/src/store/core.ts b/src/store/core.ts
index 75301e4a7..c9b97edc0 100644
--- a/src/store/core.ts
+++ b/src/store/core.ts
@@ -90,6 +90,8 @@ export const [store, setStore] = createStore<AppStore>({
   taskSplitMode: {},
   verboseLogging: false,
   coordinatorModeEnabled: false,
+  documentWorkspacesEnabled: false,
+  activeDocumentProjectId: null,
   coordinatorNotificationDelayMs: 60_000,
   coordinatorControlHintDismissed: false,
   defaultStepsEnabled: false,
diff --git a/src/store/persistence.ts b/src/store/persistence.ts
index 16b127333..14ff1de52 100644
--- a/src/store/persistence.ts
+++ b/src/store/persistence.ts
@@ -244,6 +244,7 @@ export async function saveState(): Promise<void> {
     darkThemePreset: store.darkThemePreset !== 'islands-dark' ? store.darkThemePreset : undefined,
     darkThemeCustomId: store.darkThemeCustomId ?? undefined,
     coordinatorModeEnabled: store.coordinatorModeEnabled || undefined,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled || undefined,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed || undefined,
     defaultStepsEnabled: store.defaultStepsEnabled || undefined,
     defaultSkipPermissions: store.defaultSkipPermissions || undefined,
@@ -415,6 +416,7 @@ interface LegacyPersistedState {
   darkThemePreset?: unknown;
   darkThemeCustomId?: unknown;
   coordinatorModeEnabled?: unknown;
+  documentWorkspacesEnabled?: unknown;
   coordinatorControlHintDismissed?: unknown;
   defaultStepsEnabled?: unknown;
   defaultSkipPermissions?: unknown;
@@ -613,6 +615,7 @@ export async function loadState(): Promise<void> {
       }
 
       s.coordinatorModeEnabled = raw.coordinatorModeEnabled === true;
+      s.documentWorkspacesEnabled = raw.documentWorkspacesEnabled === true;
 
       s.coordinatorControlHintDismissed = raw.coordinatorControlHintDismissed === true;
 
diff --git a/src/store/projects.ts b/src/store/projects.ts
index 5ced78edc..73139a2c2 100644
--- a/src/store/projects.ts
+++ b/src/store/projects.ts
@@ -30,6 +30,36 @@ export function addProject(name: string, path: string, isGitRepo?: boolean): str
   return id;
 }
 
+/** A document project: a git repo plus one document inside it. */
+export function addDocumentProject(name: string, path: string, documentPath: string): string {
+  const id = crypto.randomUUID();
+  const project: Project = {
+    id,
+    name,
+    path,
+    color: randomPastelColor(),
+    isGitRepo: true,
+    kind: 'document',
+    documentPath,
+  };
+  // Not the default for new tasks: a document project has no task flow.
+  setStore(
+    produce((s) => {
+      s.projects.push(project);
+    }),
+  );
+  return id;
+}
+
+export function isDocumentProject(project: Project | undefined): boolean {
+  return project?.kind === 'document' && typeof project.documentPath === 'string';
+}
+
+/** Projects that take tasks. Document projects have no task flow, so nothing offers them. */
+export function codeProjects(): Project[] {
+  return store.projects.filter((project) => !isDocumentProject(project));
+}
+
 export function removeProject(projectId: string): void {
   // Guard: skip removal if any tasks still reference this project
   const allTaskIds = [...store.taskOrder, ...store.collapsedTaskOrder];
@@ -67,6 +97,10 @@ export function updateProject(
       | 'verifyCommand'
       | 'terminalBookmarks'
       | 'isGitRepo'
+      | 'documentMainAgentId'
+      | 'documentSessions'
+      | 'documentModels'
+      | 'documentTerminalAgentId'
     >
   >,
 ): void {
@@ -92,6 +126,14 @@ export function updateProject(
       if (updates.terminalBookmarks !== undefined)
         s.projects[idx].terminalBookmarks = updates.terminalBookmarks;
       if (updates.isGitRepo !== undefined) s.projects[idx].isGitRepo = updates.isGitRepo;
+      if (updates.documentMainAgentId !== undefined)
+        s.projects[idx].documentMainAgentId = updates.documentMainAgentId;
+      if (updates.documentSessions !== undefined)
+        s.projects[idx].documentSessions = updates.documentSessions;
+      if (updates.documentModels !== undefined)
+        s.projects[idx].documentModels = updates.documentModels;
+      if (updates.documentTerminalAgentId !== undefined)
+        s.projects[idx].documentTerminalAgentId = updates.documentTerminalAgentId;
     }),
   );
   if (
diff --git a/src/store/remoteTaskHandler.ts b/src/store/remoteTaskHandler.ts
index 48e63a7ec..4d4d735cb 100644
--- a/src/store/remoteTaskHandler.ts
+++ b/src/store/remoteTaskHandler.ts
@@ -5,6 +5,7 @@
 // main-side bridge.
 
 import { store } from './core';
+import { codeProjects } from './projects';
 import { createTask, updateTaskNotes } from './tasks';
 import { invoke } from '../lib/ipc';
 import { IPC } from '../../electron/ipc/channels';
@@ -38,7 +39,7 @@ function handleGetProjects(req: RendererRequest): void {
   reply(
     req.reqId,
     true,
-    store.projects.map((p) => ({ id: p.id, name: p.name })),
+    codeProjects().map((p) => ({ id: p.id, name: p.name })),
   );
 }
 
diff --git a/src/store/store.ts b/src/store/store.ts
index b41c4cf4f..5341a5b4c 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -8,6 +8,9 @@ export {
   getProjectPath,
   getProjectBranchPrefix,
   pickAndAddProject,
+  addDocumentProject,
+  codeProjects,
+  isDocumentProject,
   validateProjectPaths,
   relinkProject,
   isProjectMissing,
@@ -116,6 +119,7 @@ export {
   setTaskViewportVisibility,
   toggleSidebar,
   toggleArena,
+  setDocumentWorkspacesEnabled,
   toggleFocusMode,
   toggleTaskFocusMode,
   setTaskSplitMode,
diff --git a/src/store/tasks.ts b/src/store/tasks.ts
index 5f1f3e31a..0582eed04 100644
--- a/src/store/tasks.ts
+++ b/src/store/tasks.ts
@@ -1550,6 +1550,9 @@ export function setStepsContent(taskId: string, steps: unknown[] | null): void {
 }
 
 export function setTaskLastInputAt(taskId: string): void {
+  // Terminals outside the task flow (the document workspace's agent) pass an
+  // id no task owns; writing through it would create a half-made task.
+  if (!store.tasks[taskId]) return;
   setStore('tasks', taskId, 'lastInputAt', new Date().toISOString());
 }
 
diff --git a/src/store/types.ts b/src/store/types.ts
index 5fee4decb..86219cd70 100644
--- a/src/store/types.ts
+++ b/src/store/types.ts
@@ -87,6 +87,32 @@ export interface Project {
   terminalBookmarks?: TerminalBookmark[];
   isGitRepo?: boolean; // undefined treated as true for backward compat
   tasksCollapsed?: boolean; // sidebar task group, defaults to expanded
+  /** Document workspaces (experimental): a project whose surface is one
+   *  rendered document rather than task terminals. Undefined means 'code'. */
+  kind?: ProjectKind;
+  /** Repo-relative path of the document a document project opens. */
+  documentPath?: string;
+  /** Agent that owns the project's warm main session. */
+  documentMainAgentId?: string;
+  /** Resumable main sessions per agent id, with the base sha each last saw. */
+  documentSessions?: Record<string, DocumentSessionRef>;
+  /** Model and reasoning level last chosen in the run composer, per agent id
+   *  and candidate slot: the agent's first candidate, its second, and so on. */
+  documentModels?: Record<string, DocumentModelChoice[]>;
+  /** Agent running in the workspace's interactive terminal. */
+  documentTerminalAgentId?: string;
+}
+
+export interface DocumentModelChoice {
+  model?: string;
+  effort?: string;
+}
+
+export type ProjectKind = 'code' | 'document';
+
+export interface DocumentSessionRef {
+  sessionId: string;
+  lastSha: string;
 }
 
 export interface Agent {
@@ -308,6 +334,7 @@ export interface PersistedState {
   darkThemePreset?: LookPreset;
   darkThemeCustomId?: string | null;
   coordinatorModeEnabled?: boolean;
+  documentWorkspacesEnabled?: boolean;
   coordinatorNotificationDelayMs?: number;
   coordinatorControlHintDismissed?: boolean;
   defaultStepsEnabled?: boolean;
@@ -435,6 +462,9 @@ export interface AppStore {
   darkThemePreset: LookPreset;
   darkThemeCustomId: string | null;
   coordinatorModeEnabled: boolean;
+  documentWorkspacesEnabled: boolean;
+  /** Project whose document workspace overlay is open. */
+  activeDocumentProjectId: string | null;
   coordinatorNotificationDelayMs: number;
   coordinatorControlHintDismissed: boolean;
   defaultStepsEnabled: boolean;
diff --git a/src/store/ui.ts b/src/store/ui.ts
index 23869d966..67eaa92a8 100644
--- a/src/store/ui.ts
+++ b/src/store/ui.ts
@@ -270,6 +270,11 @@ export function setShareDockerAgentAuth(enabled: boolean): void {
   setStore('shareDockerAgentAuth', enabled);
 }
 
+export function setDocumentWorkspacesEnabled(enabled: boolean): void {
+  setStore('documentWorkspacesEnabled', enabled);
+  if (!enabled) setStore('activeDocumentProjectId', null);
+}
+
 export function toggleArena(show?: boolean): void {
   setStore('showArena', show ?? !store.showArena);
 }
diff --git a/vitest.client.config.ts b/vitest.client.config.ts
index aba8afc58..879e11e60 100644
--- a/vitest.client.config.ts
+++ b/vitest.client.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
   plugins: [solidPlugin({ ssr: false })],
   test: {
     environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.ts'],
     include: ['src/**/*.client.test.tsx'],
   },
 });
diff --git a/vitest.config.ts b/vitest.config.ts
index 76649cd9a..d7962d0dc 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
   plugins: [solidPlugin({ ssr: true })],
   test: {
     environment: 'node',
+    setupFiles: ['./vitest.setup.ts'],
     include: ['src/**/*.test.ts', 'electron/**/*.test.ts', 'scripts/**/*.test.mjs'],
     coverage: {
       provider: 'v8',
diff --git a/vitest.setup.ts b/vitest.setup.ts
new file mode 100644
index 000000000..c6489feb8
--- /dev/null
+++ b/vitest.setup.ts
@@ -0,0 +1,22 @@
+/**
+ * Git exports `GIT_DIR`, `GIT_INDEX_FILE` and friends into the environment of
+ * every hook it runs. `npm test` from `.husky/pre-push` therefore hands those
+ * to each vitest worker, and any `git` a test spawns inherits them — so tests
+ * that build a repository in a temp folder silently operate on the developer's
+ * real checkout instead, committing fixtures onto their branch and clobbering
+ * their index. Scrubbing them here keeps the suite hermetic whatever invoked it.
+ */
+const REPO_POINTING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+  'GIT_QUARANTINE_PATH',
+  'GIT_CEILING_DIRECTORIES',
+] as const;
+
+for (const name of REPO_POINTING_VARS) Reflect.deleteProperty(process.env, name);

From 137339364ea823d0510f67bf7272472cfaa151f9 Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Tue, 8 Sep 2026 21:11:38 +0200
Subject: [PATCH 2/5] feat(documents): agent-driven document workspaces

Squashes today's work on the document workspace:

- run the workspace agent in the task terminal, keep its tab mounted and
  the session alive across tab switches and exits
- review proposals one at a time in the compare view, with agent merge
  and follow-up questions
- float notes and the block toolbar over the window
- enlarge mermaid diagrams in a full-window lightbox
- fix the Solid crash on close and the dialog prose width cap
- address UI review findings

Claude-Session: https://claude.ai/code/session_011wx6DbuYrV9qsunua6BUu3
---
 docs/document-workspaces.md                   | 118 +++--
 electron/documents/annotations.test.ts        |  84 ++++
 electron/documents/annotations.ts             |  75 ++-
 electron/documents/discard.test.ts            |  46 ++
 electron/documents/files.test.ts              |   1 +
 electron/documents/files.ts                   |   5 +-
 electron/documents/merge.integration.test.ts  | 113 +++++
 electron/documents/prompt.test.ts             |  63 +++
 electron/documents/prompt.ts                  |  69 +++
 electron/documents/register.ts                |   6 +
 electron/documents/runs.test.ts               |  12 +
 electron/documents/runs.ts                    |  89 +++-
 electron/documents/types.ts                   |   4 +
 electron/ipc/channel-manifest.json            |   1 +
 electron/preload.cjs                          |   1 +
 src/App.tsx                                   |  27 +-
 src/components/AddProjectMenu.tsx             |  21 +-
 src/components/Dialog.tsx                     |   3 +
 src/components/RemoveProjectConfirm.tsx       |   3 +
 src/components/TaskAITerminal.tsx             |  21 +-
 src/documents/AgentTerminal.client.test.tsx   | 149 ++++++
 src/documents/AgentTerminal.tsx               | 164 ++++---
 .../AnnotationBubble.client.test.tsx          | 131 ++++++
 src/documents/AnnotationBubble.tsx            | 100 +++-
 .../AnnotationMarker.client.test.tsx          | 108 ++++-
 src/documents/AnnotationMarker.tsx            | 129 +++++-
 src/documents/BlockActions.client.test.tsx    | 140 +++---
 src/documents/BlockActions.tsx                | 117 ++---
 src/documents/BlockEditor.client.test.tsx     |  25 +
 src/documents/BlockEditor.tsx                 |  22 +-
 src/documents/CandidateOutputDialog.tsx       |  31 +-
 .../CandidateRefinement.client.test.tsx       |  15 +
 src/documents/CandidateRefinement.tsx         |  26 +-
 src/documents/CompareDialog.tsx               |  74 +--
 src/documents/CompareView.client.test.tsx     | 250 +++++++++-
 src/documents/CompareView.tsx                 | 407 ++++++++++++----
 .../DocumentViewer.toolbar.client.test.tsx    |  51 ++
 src/documents/DocumentViewer.tsx              |  51 +-
 .../DocumentWorkspaceOverlay.client.test.tsx  |  89 +++-
 ...mentWorkspaceOverlay.close.client.test.tsx | 116 +++++
 src/documents/DocumentWorkspaceOverlay.tsx    | 172 ++++++-
 src/documents/FileTreePanel.tsx               |  13 +-
 src/documents/HistoryView.tsx                 |  44 +-
 src/documents/MergeWithAgent.tsx              | 159 +++++++
 src/documents/ModelRows.tsx                   |   7 +
 .../NewDocumentProjectDialog.client.test.tsx  |  65 ++-
 src/documents/NewDocumentProjectDialog.tsx    |  43 +-
 src/documents/PageBlocks.tsx                  |  43 +-
 src/documents/RejectRunConfirm.tsx            |  63 +++
 src/documents/RightPanel.client.test.tsx      |  95 ++++
 src/documents/RightPanel.tsx                  |  46 +-
 .../RunComposer.annotate.client.test.tsx      |  26 +-
 src/documents/RunComposer.client.test.tsx     |  78 +++-
 .../RunComposer.draft.client.test.tsx         |   3 +-
 src/documents/RunComposer.tsx                 | 214 +++++----
 src/documents/RunsRail.client.test.tsx        | 126 +++++
 src/documents/RunsRail.tsx                    |  87 ++--
 src/documents/agent-task.client.test.tsx      | 264 +++++++++++
 src/documents/agent-task.ts                   | 152 ++++++
 src/documents/agent-terminal.ts               |  59 ---
 src/documents/block-merge.test.ts             |  21 +
 src/documents/block-merge.ts                  |  27 +-
 src/documents/documents-styles.test.ts        |  30 +-
 src/documents/documents.css                   | 438 ++++++++++++++----
 src/documents/interactive-prompt.test.ts      |   8 +-
 src/documents/interactive-prompt.ts           |   7 +-
 src/documents/store.trail.client.test.tsx     | 108 +++++
 src/documents/store.ts                        | 158 +++++--
 src/documents/workspace-ui.ts                 |  59 ++-
 src/lib/floating.test.ts                      |  44 ++
 src/lib/floating.ts                           | 107 +++++
 src/lib/mermaid-lightbox.ts                   |  83 ++++
 src/lib/mermaid.client.test.tsx               |  25 +
 src/lib/mermaid.ts                            |   5 +
 src/lib/platform.ts                           |   5 +-
 src/store/core.ts                             |   1 +
 src/store/persistence.test.ts                 |  53 +++
 src/store/persistence.ts                      |  24 +-
 src/store/tasks.ts                            |  13 +
 src/store/types.ts                            |   3 +
 src/store/ui.ts                               |   4 +
 src/styles.css                                |  73 +++
 82 files changed, 5135 insertions(+), 877 deletions(-)
 create mode 100644 electron/documents/discard.test.ts
 create mode 100644 electron/documents/merge.integration.test.ts
 create mode 100644 src/documents/AgentTerminal.client.test.tsx
 create mode 100644 src/documents/AnnotationBubble.client.test.tsx
 create mode 100644 src/documents/DocumentViewer.toolbar.client.test.tsx
 create mode 100644 src/documents/DocumentWorkspaceOverlay.close.client.test.tsx
 create mode 100644 src/documents/MergeWithAgent.tsx
 create mode 100644 src/documents/RejectRunConfirm.tsx
 create mode 100644 src/documents/RightPanel.client.test.tsx
 create mode 100644 src/documents/RunsRail.client.test.tsx
 create mode 100644 src/documents/agent-task.client.test.tsx
 create mode 100644 src/documents/agent-task.ts
 delete mode 100644 src/documents/agent-terminal.ts
 create mode 100644 src/documents/store.trail.client.test.tsx
 create mode 100644 src/lib/floating.test.ts
 create mode 100644 src/lib/floating.ts
 create mode 100644 src/lib/mermaid-lightbox.ts

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 9b0203edf..180d2bc41 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -38,42 +38,62 @@ the document.
    it, and click a relative link inside a document to follow it to the file (and heading)
    it points at. Web links open in the browser. The history, the composer and the runs
    follow the open document.
-4. The composer is a popover over the prose, never inside it, and is always there: with
-   nothing picked it rests at the foot of the column, acts on the whole document, and fades
-   back while you read. Select text, click a block, or press **§** next to a heading to
-   narrow it to a passage: it moves right under the passage (above it when the foot is
-   close), at full strength and with the cursor in it, and follows the passage as you
-   scroll. It steps back once you leave it. Type an instruction and press Enter. Hovering a
+4. The composer is a popover over the prose, never inside it, and stays out of the way
+   until there is something to compose: select text, click a block, or press **§** next
+   to a heading to open it on a passage, or choose **Revise document** in the toolbar to
+   open it on the whole document. On a passage it sits right under it (above it when the
+   foot is close), at full strength and with the cursor in it, and follows the passage as
+   you scroll. It steps back once you leave it. Type an instruction and press Enter. Hovering a
    block shows five icons in the gap just above it, clear of the prose so a click meant
    for the passage cannot land on one, each named as you point at it: task, proposals,
    note and ask pick the block and open the composer on that mode (its tabs carry the same
    icons), and the pencil, set apart, opens the block's source for editing. The picked
    block's icons step aside while the composer is up on it; the other blocks keep theirs,
    so one click moves the composer to another block. The **×** in the composer's corner,
-   or Esc, lets go of the passage and returns it to the foot.
-   The composer's four tabs are the four things one does with a passage; **Task** and
+   or Esc, lets go of the passage and closes the composer.
+   The composer's four tabs are the four things one does with a passage; **Edit with agent** and
    **Proposals** are the same instruction sent two ways:
-   - **Task** types it into the long-running agent session on the right, which
+   - **Edit with agent** types it into the long-running agent session on the right, which
      works in the checkout as you watch. Its edits show up in the viewer as they land and
      are committed as `Manual edits` before the next one-shot run.
-   - **Proposals** runs headless candidates in their own worktrees. Expand
-     **Agents and models** to choose agents and candidate counts. Each candidate gets a
-     **Model** field and, where the CLI has one, a **Reasoning** level, so one agent can run
-     its main session on one model and an
-     alternate on another; both are the CLI's defaults until you choose, and the choice is
-     remembered per project, agent and candidate.
+   - **Proposals**, the default for a new composer, runs headless candidates in their own worktrees. The agents sit in
+     plain view: click one to add or drop it, and its count to have it draft more than
+     once; a counter says how many of the allowed candidates are in play. **Models and
+     main session** folds away the tuning: each candidate gets a **Model** field and, where
+     the CLI has one, a **Reasoning** level, so one agent can run its main session on one
+     model and an alternate on another; both are the CLI's defaults until you choose, and
+     the choice is remembered per project, agent and candidate.
+     The toolbar's **Full width** lets the document use the whole pane instead of a reading
+     column; the choice is remembered. Mermaid diagrams, here and in every other Markdown
+     surface of the app, carry an enlarge button that opens them at the size of the window.
 5. The right-hand panel has three tabs and a draggable seam (double-click it to reset the
-   width; the width is remembered). **Agent** is the interactive session in the app's
-   terminal, with a status chip that says _needs you_ while it waits for an answer; its
-   process survives closing the workspace, and **Restart**, or picking another agent,
-   starts it afresh. **Runs** lists the one-shot runs as they finish; click any candidate to
-   read everything it printed.
+   width; the width is remembered). **Agent** is the terminal a task has: the bar above it
+   shows the last prompt sent, the chips switch between agents, **+** adds another one
+   (as tabs by default, or side by side), and the prompt box below sends to the first
+   agent. A session that exits offers **Restart**, **Resume** and a switch to another
+   agent; one that has exited starts afresh the next time the tab is shown. The processes
+   survive closing the workspace, and the agent last used comes back after the app
+   restarts. A Markdown path the agent prints opens in the viewer when it lies inside the
+   project. The tab stays mounted behind the other two, so switching tabs keeps the
+   scrollback and scroll position. The tab flags _!_ while an agent waits for an answer. **Runs** lists the one-shot runs as they finish,
+   each revision or merge saying which proposals it came from. Click a ready candidate in a
+   finished run to review that proposal; **View output** opens its log. Running, failed and
+   already-decided candidates still open their output.
    Runs that wait for a decision also appear as a strip over the agent, so nothing sits
    unnoticed behind another tab. **Review** (one candidate) or **Compare** (several), or the
-   _n to review_ button in the header, opens the compare view as a large modal over the
-   workspace, with **Fullscreen** to fill the window: base on the left, candidates to the
-   right, each starting with its rationale. Accept one, reject all, or choose **Refine this candidate** and describe
-   what should change. A candidate with more than one change carries a checkbox beside each
+   _n to review_ button in the header, opens the compare view over the whole window: the original
+   on the left and one proposal on the right. Proposal tabs support arrow keys, Home and End,
+   and preserve notes, selected changes and reading position when switching. **Show all proposals**
+   restores the resizable multi-column layout. Each proposal starts with a one-line summary;
+   **Reasoning and notes** expands the full rationale and your review note. Warnings remain
+   visible. The original and proposal start at the same height, even with details expanded.
+   **Apply proposal** (or **Apply n of m changes**) stays below the scrolling document. Apply one,
+   reject all, or choose **Refine this candidate** and describe what should change. With
+   two or more proposals, **Merge with agent** hands the comparing to an agent: pick the
+   proposals and the agent, adjust the guidance, and it drafts one merged proposal from
+   the diffs and your notes on each candidate, saying which parts came from where. The
+   merged version lands in Runs like any other proposal and still needs acceptance.
+   A candidate with more than one change carries a checkbox beside each
    of them: every change is kept until you clear its box, the passages you dropped recede
    in place so you can still read what you turned down, and the button then says
    **Accept n of m changes** and takes only those. **Preview result** shows the complete
@@ -85,11 +105,14 @@ the document.
 6. **History** is `git log` for the document with the `Parallel-*` trailers parsed:
    what changed, which agent, which instruction, which base. Show the diff or render the
    older version. Revert any entry.
-7. **Annotations.** The same composer offers **Note** and **Ask** beside **Task**. A note
+7. **Annotations.** The same composer offers **Note** and **Ask** beside **Edit with agent**. A note
    attaches to the passage as a symbol in its margin; hover it, tab to it, or click it to
    pin it open, and the bubble opens over the document. A question is a bubble an agent
    answers into, running read-only in the checkout; question and answer stay visible
-   together. Resolve (`r`) collapses a bubble to one line, Delete removes it with an Undo
+   together. **Ask follow-up** under an answer continues the conversation with the agent
+   that answered: the follow-up is a new question on the same passage, and the agent is
+   handed the earlier exchange along with it. Resolve (`r`) collapses a bubble to one
+   line, Delete removes it with an Undo
    in the toolbar, and **Make task** reopens the composer on the passage with the bubble's
    text (and answer) as the instruction; the bubble then collapses as `task`.
 
@@ -97,19 +120,28 @@ the document.
    **Edit block** in the toolbar. Edit its
    Markdown or HTML source, then **Save block** to update the document directly. Surrounding
    content and line endings are preserved. If the file changed meanwhile, saving refuses
-   to overwrite it and keeps your text available to copy.
+   to overwrite it and keeps your text available to copy. Edits made this way, or in an
+   outside editor, show as an _uncommitted edits_ chip in the header; click it to discard
+   them and return to the committed version. Next to the editor button, a folder button
+   opens the project in the file manager.
 
 ### How it works
 
 - **Editing happens in the block editor, your editor, or the interactive session.** The app
-  watches the open file and re-renders; an external change drops any active selection. The session
-  on the Agent tab is an ordinary terminal (`TerminalView`) running the chosen agent's
-  CLI in the checkout, one per project, keyed `doc-agent-<project>`; a scoped instruction
-  is pasted into it as _Document, Scope, the passage verbatim, your words_. Because it
-  edits the checkout directly, its work is committed as `Manual edits` by the next
-  one-shot dispatch rather than as a proposal to compare. A restart, or a switch to another
-  agent, spawns fresh instead of attaching: the spawn replaces the live session in one
-  step, so the new terminal never inherits the exit of the one it replaced.
+  watches the open file and re-renders; an external change drops any active selection. The Agent
+  tab is a task's AI terminal and prompt box (`TaskAITerminal`, `PromptInput`) over a hidden
+  task per project, id `doc-agent-<project>`, kept out of the task order so it is neither
+  listed nor persisted; its first agent's pty carries the same id, so reopening the workspace
+  re-attaches, and the agent it ran is remembered on the project. Each time the tab is
+  shown, the agents are re-armed to attach (a restart clears that for its one spawn) and
+  one that exited is reset, since the terminal spawns it afresh. Removing the project
+  kills the sessions. A scoped instruction, _your words, then Document, Scope and the
+  passage verbatim_, goes to the selected agent as a prompt: typed straight in when the agent looks
+  idle (quiet output, no open question, and for Claude no hook turn in flight), else
+  queued as the task's initial prompt, which the prompt box sends once the agent is
+  ready; a second instruction is refused while one waits. Because the agent edits the
+  checkout directly, its work is committed as `Manual edits` by the next one-shot
+  dispatch rather than as a proposal to compare.
 - **Every file of the project is one click away.** The file tree is `git ls-files`
   (tracked and untracked, ignores respected) minus `.parallel/`, `.worktrees/` and `.git/`,
   capped at 5,000 entries, refreshed on every new head. Opening a file swaps the watcher
@@ -158,6 +190,16 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   accepting it uses the existing three-way integration. The run records its source run
   and candidate in `refinement`. Refinement covers the whole proposal because passage
   line numbers may have changed. Dispatch does not commit pending canonical edits.
+- **Merging is a run like any other.** One fresh candidate starts at the source run's
+  base, the same content every proposal saw, and its prompt carries each chosen proposal
+  as a diff against that base, with the candidate's own summary and the reviewer's note.
+  The run records `merge` (source run and candidate ids), covers the whole document, and
+  never resumes the main session, so a warm session is not moved onto unaccepted content.
+  Refining and merging are mutually exclusive on one run.
+- **Follow-up questions form a thread.** A follow-up is a new annotation with
+  `followUpOf` pointing at the answered question. Asking it walks that chain (bounded,
+  and safe against a loop in a hand-edited file) and puts the earlier questions and
+  answers into the read-only prompt ahead of the new one.
 - **Acceptance is one squashed integration commit** on the checked-out branch, containing
   the document and the run record `.parallel/runs/<id>.json`. A proposal whose base is
   behind HEAD is merged three-way on acceptance and marked stale if it no longer applies.
@@ -217,7 +259,11 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   list, a table; not the `<main>` or `<div>` around them) are marked as the blocks. The
   page's stylesheet comes along, scoped to the viewer with `@scope`, `html`/`body` rules
   pointed at the page root, the app's annotation markers kept out of it, scripts and
-  `@import` dropped. Every block carries its source lines, so selection, the composer,
+  `@import` dropped. The block toolbar and an open note are not inside the page at all:
+  they float over the window, placed from the block's on-screen position and moved with
+  it on scroll, so a page element that clips its overflow cannot trap them and nothing
+  in the workspace, the composer included, paints over them. The markdown viewer uses
+  the same two overlays. Every block carries its source lines, so selection, the composer,
   annotations, compare marking and history work on the rendered page exactly as on
   Markdown; marks are outlines and markers hang out of the page's flow, so nothing the
   app adds moves the page's own elements. A **Page** toggle
diff --git a/electron/documents/annotations.test.ts b/electron/documents/annotations.test.ts
index 569db8f0d..27b9374b9 100644
--- a/electron/documents/annotations.test.ts
+++ b/electron/documents/annotations.test.ts
@@ -4,6 +4,7 @@ import os from 'os';
 import path from 'path';
 import type { BrowserWindow } from 'electron';
 import {
+  annotationThread,
   askAnnotation,
   buildAnnotationPrompt,
   deleteAnnotation,
@@ -61,6 +62,56 @@ describe('validateAnnotationInput', () => {
     expect(a.answerStatus).toBeUndefined();
     expect(a.runId).toBeUndefined();
   });
+
+  it('keeps a follow-up link but never one to itself', () => {
+    expect(validateAnnotationInput({ ...note('q-2'), followUpOf: 'q-1' }).followUpOf).toBe('q-1');
+    expect(
+      validateAnnotationInput({ ...note('q-2'), followUpOf: 'q-2' }).followUpOf,
+    ).toBeUndefined();
+    expect(
+      validateAnnotationInput({ ...note('q-2'), followUpOf: 'no way' }).followUpOf,
+    ).toBeUndefined();
+  });
+});
+
+function answered(
+  id: string,
+  text: string,
+  answer: string,
+  followUpOf?: string,
+): DocumentAnnotation {
+  return validateAnnotationInput({
+    ...note(id),
+    kind: 'question',
+    text,
+    followUpOf,
+    answerStatus: 'answered',
+    answer: { text: answer, agentId: 'claude-code', agentName: 'Claude', answeredAt: 'x' },
+  });
+}
+
+describe('annotationThread', () => {
+  it('walks the follow-up chain oldest first and survives a loop', () => {
+    const first = answered('q-1', 'Why?', 'Because.');
+    const second = answered('q-2', 'Why that?', 'Tradition.', 'q-1');
+    const third = answered('q-3', 'Since when?', '', 'q-2');
+    expect(annotationThread([third, first, second], third).map((a) => a.id)).toEqual([
+      'q-1',
+      'q-2',
+    ]);
+    const loopA = answered('l-a', 'a', 'a', 'l-b');
+    const loopB = answered('l-b', 'b', 'b', 'l-a');
+    expect(annotationThread([loopA, loopB], loopA).map((a) => a.id)).toEqual(['l-b']);
+    expect(annotationThread([first], answered('q-9', 'x', 'y', 'gone'))).toEqual([]);
+  });
+
+  it('stops after eight exchanges, keeping the nearest ones', () => {
+    const chain = Array.from({ length: 10 }, (_, i) =>
+      answered(`q-${i}`, `q${i}`, `a${i}`, i > 0 ? `q-${i - 1}` : undefined),
+    );
+    const thread = annotationThread(chain, chain[9]);
+    expect(thread.map((a) => a.id)).toEqual(chain.slice(1, 9).map((a) => a.id));
+  });
 });
 
 describe('buildAnnotationPrompt', () => {
@@ -73,6 +124,39 @@ describe('buildAnnotationPrompt', () => {
     expect(prompt).toContain('> Old goals text.');
     expect(prompt).toContain('Question:\nWhy?');
     expect(prompt).toContain('Do not edit');
+    expect(prompt).not.toContain('follow-up');
+  });
+
+  it('carries the earlier exchange into a follow-up', () => {
+    const first = answered('q-1', 'Why is this here?', 'It anchors the section.');
+    const followUp = answered('q-2', 'Could it move up?', '', 'q-1');
+    const prompt = buildAnnotationPrompt(followUp, annotationThread([first, followUp], followUp));
+    expect(prompt).toContain('This is a follow-up');
+    expect(prompt).toContain('Question:\nWhy is this here?');
+    expect(prompt).toContain('Answer (Claude):\nIt anchors the section.');
+    expect(prompt).toContain('Follow-up question:\nCould it move up?');
+    expect(prompt.indexOf('Why is this here?')).toBeLessThan(prompt.indexOf('Could it move up?'));
+  });
+
+  it('says so when an earlier question got no answer', () => {
+    const unanswered = validateAnnotationInput({ ...note('q-1'), kind: 'question', text: 'Why?' });
+    const followUp = answered('q-2', 'Still, why?', '', 'q-1');
+    expect(buildAnnotationPrompt(followUp, [unanswered])).toContain(
+      'Question:\nWhy?\n\nAnswer: none was given.',
+    );
+  });
+
+  it('keeps a long thread under the Linux argument limit, cutting old answers not the question', () => {
+    const chain = Array.from({ length: 9 }, (_, i) =>
+      answered(`q-${i}`, 'q'.repeat(20_000), 'a'.repeat(50_000), i > 0 ? `q-${i - 1}` : undefined),
+    );
+    const earlier = annotationThread(chain, chain[8]);
+    const prompt = buildAnnotationPrompt(chain[8], earlier);
+    expect(earlier).toHaveLength(8);
+    expect(Buffer.byteLength(prompt)).toBeLessThan(128 * 1024);
+    // Eight answers share 40 000 bytes: 5 000 each, then the marker.
+    expect(prompt.match(/a{5000}\n… \(truncated\)/g)).toHaveLength(8);
+    expect(prompt).toContain('Follow-up question:\n' + 'q'.repeat(20_000));
   });
 });
 
diff --git a/electron/documents/annotations.ts b/electron/documents/annotations.ts
index d9d0ab8a6..716e4eebe 100644
--- a/electron/documents/annotations.ts
+++ b/electron/documents/annotations.ts
@@ -13,6 +13,7 @@ import { errMessage } from '../log.js';
 import { atomicWriteFileSync } from '../mcp/atomic.js';
 import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
 import { loadEnvFile } from '../ipc/env-file.js';
+import { truncateBytes } from './prompt.js';
 import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
 import { documentAgentSupport } from './shared.js';
 import { validateDocumentPath, validateSha } from './runs.js';
@@ -29,6 +30,16 @@ const MAX_ANSWER_CHARS = 50_000;
 const MAX_ANNOTATIONS = 2_000;
 const ANSWER_TIMEOUT_MS = 10 * 60_000;
 const KILL_GRACE_MS = 5_000;
+/** Earlier exchanges a follow-up carries into its prompt, at most. */
+const MAX_THREAD_LENGTH = 8;
+/*
+ * The prompt is one argv element, capped at 128 KiB on Linux, so the thread
+ * is budgeted in bytes: earlier answers share one budget and earlier
+ * questions are cut short. The follow-up itself keeps its full text.
+ */
+const THREAD_ANSWER_BUDGET_BYTES = 40_000;
+const MAX_THREAD_ANSWER_BYTES = 8_000;
+const MAX_THREAD_QUESTION_BYTES = 2_000;
 
 function annotationsPath(projectRoot: string): string {
   return path.join(projectRoot, ANNOTATIONS_REL_PATH);
@@ -102,6 +113,12 @@ export function validateAnnotationInput(value: unknown): DocumentAnnotation {
   const status = v.answerStatus;
   const runId =
     typeof v.runId === 'string' && /^[a-z0-9-]{1,64}$/i.test(v.runId) ? v.runId : undefined;
+  const followUpOf =
+    typeof v.followUpOf === 'string' &&
+    /^[a-z0-9-]{1,64}$/i.test(v.followUpOf) &&
+    v.followUpOf !== id
+      ? v.followUpOf
+      : undefined;
   return {
     id,
     kind,
@@ -115,9 +132,31 @@ export function validateAnnotationInput(value: unknown): DocumentAnnotation {
       status === 'pending' || status === 'answered' || status === 'failed' ? status : undefined,
     answerError: typeof v.answerError === 'string' ? v.answerError.slice(0, 2_000) : undefined,
     runId,
+    followUpOf,
   };
 }
 
+/**
+ * The questions `annotation` follows up on, oldest first. Bounded, and a
+ * loop in a hand-edited file ends the walk rather than the process.
+ */
+export function annotationThread(
+  all: readonly DocumentAnnotation[],
+  annotation: DocumentAnnotation,
+): DocumentAnnotation[] {
+  const chain: DocumentAnnotation[] = [];
+  const seen = new Set<string>([annotation.id]);
+  let parentId = annotation.followUpOf;
+  while (parentId && !seen.has(parentId) && chain.length < MAX_THREAD_LENGTH) {
+    const parent = all.find((a) => a.id === parentId);
+    if (!parent) break;
+    seen.add(parent.id);
+    chain.unshift(parent);
+    parentId = parent.followUpOf;
+  }
+  return chain;
+}
+
 // --- File -----------------------------------------------------------------
 
 export function readAnnotations(projectRoot: string): DocumentAnnotation[] {
@@ -238,8 +277,27 @@ interface ActiveAsk {
 
 const activeAsks = new Map<string, ActiveAsk>();
 
-/** Builds the read-only question prompt. Exported for tests. */
-export function buildAnnotationPrompt(annotation: DocumentAnnotation): string {
+/** One earlier question and its answer, as the agent reads them. */
+function describeExchange(a: DocumentAnnotation, answerBytes: number): string {
+  const answer = a.answer
+    ? `Answer (${a.answer.agentName}):\n${truncateBytes(a.answer.text.trim(), answerBytes)}`
+    : 'Answer: none was given.';
+  return `Question:\n${truncateBytes(a.text.trim(), MAX_THREAD_QUESTION_BYTES)}\n\n${answer}`;
+}
+
+/** Each earlier answer's share of the thread budget. */
+function answerBytesFor(exchanges: number): number {
+  return Math.min(MAX_THREAD_ANSWER_BYTES, Math.floor(THREAD_ANSWER_BUDGET_BYTES / exchanges));
+}
+
+/**
+ * Builds the read-only question prompt. `earlier` holds the exchanges a
+ * follow-up continues, oldest first. Exported for tests.
+ */
+export function buildAnnotationPrompt(
+  annotation: DocumentAnnotation,
+  earlier: readonly DocumentAnnotation[] = [],
+): string {
   const a = annotation.anchor;
   const where = a.heading
     ? `lines ${a.startLine}-${a.endLine} (under "${a.heading}")`
@@ -253,7 +311,15 @@ export function buildAnnotationPrompt(annotation: DocumentAnnotation): string {
       'Read the document (and anything else in the project you need) but do not modify any file.',
     `Document: ${a.path}`,
     `Passage: ${where}\n${quote}`,
-    `Question:\n${annotation.text.trim()}`,
+    ...(earlier.length > 0
+      ? [
+          'This is a follow-up. The earlier exchange on this passage, oldest first:\n\n' +
+            earlier
+              .map((a) => describeExchange(a, answerBytesFor(earlier.length)))
+              .join('\n\n---\n\n'),
+        ]
+      : []),
+    `${earlier.length > 0 ? 'Follow-up question' : 'Question'}:\n${annotation.text.trim()}`,
     [
       'Rules:',
       '- Answer the question about this passage directly and concisely, in Markdown.',
@@ -319,10 +385,11 @@ export async function askAnnotation(
   });
   if (!annotation) throw new Error('Annotation not found');
 
+  const earlier = annotationThread(readAnnotations(projectRoot), annotation);
   const launch = buildHeadlessLaunch({
     agentId,
     command,
-    prompt: buildAnnotationPrompt(annotation),
+    prompt: buildAnnotationPrompt(annotation, earlier),
     newSessionId: randomUUID(),
     readOnly: true,
   });
diff --git a/electron/documents/discard.test.ts b/electron/documents/discard.test.ts
new file mode 100644
index 000000000..ad578f223
--- /dev/null
+++ b/electron/documents/discard.test.ts
@@ -0,0 +1,46 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { discardDocumentEdits, readDocumentSnapshot } from './runs.js';
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+function git(root: string, ...args: string[]) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+describe('discardDocumentEdits', () => {
+  it('restores committed content, staged or not, and leaves .parallel alone', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-discard-'));
+    roots.push(root);
+    git(root, 'init', '-q', '-b', 'main');
+    git(root, 'config', 'user.name', 'Test');
+    git(root, 'config', 'user.email', 'test@example.com');
+    fs.writeFileSync(path.join(root, 'plan.md'), '# Plan\n');
+    fs.writeFileSync(path.join(root, 'notes.md'), '# Notes\n');
+    fs.mkdirSync(path.join(root, '.parallel'));
+    fs.writeFileSync(path.join(root, '.parallel', 'annotations.json'), '{"version":1}');
+    git(root, 'add', '.');
+    git(root, 'commit', '-qm', 'Initial');
+
+    fs.writeFileSync(path.join(root, 'plan.md'), '# Plan\n\nEdited.\n');
+    fs.writeFileSync(path.join(root, 'notes.md'), '# Notes\n\nStaged.\n');
+    git(root, 'add', 'notes.md');
+    fs.writeFileSync(path.join(root, '.parallel', 'annotations.json'), '{"version":1,"x":1}');
+    expect((await readDocumentSnapshot(root, 'plan.md')).dirty).toBe(true);
+
+    await discardDocumentEdits(root);
+
+    expect(fs.readFileSync(path.join(root, 'plan.md'), 'utf8')).toBe('# Plan\n');
+    expect(fs.readFileSync(path.join(root, 'notes.md'), 'utf8')).toBe('# Notes\n');
+    expect(fs.readFileSync(path.join(root, '.parallel', 'annotations.json'), 'utf8')).toBe(
+      '{"version":1,"x":1}',
+    );
+    expect((await readDocumentSnapshot(root, 'plan.md')).dirty).toBe(false);
+  });
+});
diff --git a/electron/documents/files.test.ts b/electron/documents/files.test.ts
index 92738bad1..212d5de7c 100644
--- a/electron/documents/files.test.ts
+++ b/electron/documents/files.test.ts
@@ -31,6 +31,7 @@ describe('listProjectFiles', () => {
     write(dir, 'build/out.txt');
     write(dir, '.gitignore', 'build/\n');
     write(dir, '.parallel/runs/r.json', '{}');
+    write(dir, '.claude/settings.json', '{}');
     write(dir, '.worktrees/x/notes.md');
     execFileSync('git', ['add', 'notes.md'], { cwd: dir });
 
diff --git a/electron/documents/files.ts b/electron/documents/files.ts
index 4391df111..a31e34b67 100644
--- a/electron/documents/files.ts
+++ b/electron/documents/files.ts
@@ -7,8 +7,9 @@ import { git } from './git.js';
 
 /** A tree beyond this is a code project, not a document project. */
 const MAX_FILES = 5_000;
-/** Folders the workspace owns or must never offer to open. */
-const HIDDEN_PREFIXES = ['.parallel/', '.worktrees/', '.git/'];
+/** Folders the workspace owns or must never offer to open; `.claude/` holds
+ *  the settings the app writes for the project's agent session. */
+const HIDDEN_PREFIXES = ['.parallel/', '.worktrees/', '.git/', '.claude/'];
 
 export async function listProjectFiles(projectRoot: string): Promise<string[]> {
   const out = await git(projectRoot, [
diff --git a/electron/documents/merge.integration.test.ts b/electron/documents/merge.integration.test.ts
new file mode 100644
index 000000000..6980f92ad
--- /dev/null
+++ b/electron/documents/merge.integration.test.ts
@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import { dispatchDocumentRun, listDocumentRuns } from './runs.js';
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+function git(root: string, ...args: string[]) {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
+}
+
+async function statusOf(root: string, runId: string) {
+  return (await listDocumentRuns(root)).find((r) => r.id === runId)?.status;
+}
+
+describe('merging proposals with an agent', () => {
+  it('hands the agent every chosen proposal as a diff and records the lineage', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-merge-'));
+    roots.push(root);
+    git(root, 'init', '-q', '-b', 'main');
+    git(root, 'config', 'user.name', 'Test');
+    git(root, 'config', 'user.email', 'test@example.com');
+    fs.writeFileSync(path.join(root, 'plan.md'), '# Plan\n\nOriginal.\n');
+    git(root, 'add', '.');
+    git(root, 'commit', '-qm', 'Initial');
+    const baseSha = git(root, 'rev-parse', 'HEAD');
+    const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-merge-agent-'));
+    roots.push(bin);
+    // Each candidate signs its worktree's name so the two proposals differ.
+    const propose = path.join(bin, 'propose.sh');
+    fs.writeFileSync(
+      propose,
+      '#!/bin/sh\nprintf "\\nFrom %s.\\n" "$(basename "$PWD")" >> plan.md\n',
+      { mode: 0o755 },
+    );
+    // The merging agent keeps its prompt (the claude-code layout: `-p <prompt>`) for the test to read.
+    const promptFile = path.join(bin, 'prompt.txt');
+    const merge = path.join(bin, 'merge.sh');
+    fs.writeFileSync(
+      merge,
+      `#!/bin/sh\nprintf '%s' "$2" > ${JSON.stringify(promptFile)}\nprintf "\\nMerged.\\n" >> plan.md\n`,
+      { mode: 0o755 },
+    );
+    const win = { isDestroyed: () => true } as unknown as BrowserWindow;
+    const spec = (id: string, label: string, command: string) => ({
+      id,
+      label,
+      agentId: 'claude-code',
+      agentName: 'Test',
+      command,
+      isMain: false,
+    });
+    const args = {
+      projectRoot: root,
+      documentPath: 'plan.md',
+      instruction: 'Improve the plan',
+      scope: { wholeDocument: true },
+      candidates: [spec('c1', 'A', propose), spec('c2', 'B', propose)],
+    };
+    const first = await dispatchDocumentRun(win, args);
+    await expect.poll(() => statusOf(root, first.id)).toBe('finished');
+
+    const lineage = { runId: first.id, candidateIds: ['c1', 'c2'] };
+    const merged = await dispatchDocumentRun(win, {
+      ...args,
+      instruction: 'Keep both additions',
+      candidates: [{ ...spec('c1', 'A', merge), isMain: true, sessionId: 'warm' }],
+      merge: lineage,
+    });
+    await expect.poll(() => statusOf(root, merged.id)).toBe('finished');
+    const record = (await listDocumentRuns(root)).find((r) => r.id === merged.id);
+    if (!record) throw new Error('Merge run not found');
+    expect(record.merge).toEqual(lineage);
+    expect(record.baseSha).toBe(baseSha);
+    expect(record.scope.wholeDocument).toBe(true);
+    // Never the warm main session: the merge starts fresh.
+    expect(record.candidates[0].isMain).toBe(false);
+    expect(git(root, 'show', `${record.candidates[0].commitSha}:plan.md`)).toBe(
+      '# Plan\n\nOriginal.\n\nMerged.',
+    );
+    const prompt = fs.readFileSync(promptFile, 'utf8');
+    expect(prompt).toContain('2 candidates proposed changes');
+    expect(prompt).toContain('> Improve the plan');
+    expect(prompt).toContain('### Candidate A (Test)');
+    expect(prompt).toContain('### Candidate B (Test)');
+    expect(prompt).toMatch(/\+From .*-a\./);
+    expect(prompt).toMatch(/\+From .*-b\./);
+    expect(prompt).toContain('Instruction:\nKeep both additions');
+
+    await expect(
+      dispatchDocumentRun(win, { ...args, merge: { runId: first.id, candidateIds: ['c1'] } }),
+    ).rejects.toThrow(/two proposals/);
+    await expect(
+      dispatchDocumentRun(win, {
+        ...args,
+        merge: lineage,
+        refinement: { runId: first.id, candidateId: 'c1' },
+      }),
+    ).rejects.toThrow(/not both/);
+    await expect(
+      dispatchDocumentRun(win, { ...args, merge: { runId: first.id, candidateIds: ['c1', 'c9'] } }),
+    ).rejects.toThrow(/c9/);
+    await expect(
+      dispatchDocumentRun(win, { ...args, documentPath: 'other.md', merge: lineage }),
+    ).rejects.toThrow(/document/);
+  });
+});
diff --git a/electron/documents/prompt.test.ts b/electron/documents/prompt.test.ts
index 92bdfc1d8..0793ebd3f 100644
--- a/electron/documents/prompt.test.ts
+++ b/electron/documents/prompt.test.ts
@@ -48,6 +48,69 @@ describe('buildDocumentPrompt', () => {
     expect(prompt).toContain('Instruction:\nClarify the assumptions.');
   });
 
+  it('shows a merging agent each proposal as a diff with the reviewer notes', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'Prefer the clearer wording.',
+      mergeInstruction: 'Tighten the overview.',
+      mergeCandidates: [
+        { label: 'A', agentName: 'Claude', diff: '-old\n+new A', summary: 'Shortened it.' },
+        { label: 'B', agentName: 'Codex', diff: '-old\n+new B', note: 'Keep the second bullet.' },
+      ],
+    });
+    expect(prompt).toContain('2 candidates proposed changes');
+    expect(prompt).toContain('> Tighten the overview.');
+    expect(prompt).toContain(
+      '### Candidate A (Claude)\nIts own summary: Shortened it.\n```diff\n-old\n+new A\n```',
+    );
+    expect(prompt).toContain("The reviewer's note on it: Keep the second bullet.");
+    expect(prompt).toContain('which parts came from which candidate');
+    expect(prompt).toContain('Instruction:\nPrefer the clearer wording.');
+    expect(prompt).not.toContain('unaccepted candidate');
+  });
+
+  it('keeps a worst-case merge prompt under the Linux argument limit', () => {
+    const candidates = Array.from({ length: 6 }, (_, i) => ({
+      label: 'ABCDEF'[i],
+      agentName: 'Agent',
+      diff: `-old\n+${'x'.repeat(40_000)}`,
+      summary: 's'.repeat(5_000),
+      note: 'n'.repeat(5_000),
+    }));
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'i'.repeat(20_000),
+      mergeInstruction: 'm'.repeat(20_000),
+      mergeCandidates: candidates,
+    });
+    expect(Buffer.byteLength(prompt)).toBeLessThan(128 * 1024);
+    // The diff budget is shared: six candidates get 10 000 bytes each, of
+    // which the diff header takes six.
+    const runs = (prompt.match(/x{100,}/g) ?? []).map((run) => run.length);
+    expect(runs).toEqual(Array<number>(6).fill(10_000 - '-old\n+'.length));
+    expect(prompt.match(/… \(diff truncated\)/g)).toHaveLength(6);
+    expect(prompt).toContain('Instruction:\n' + 'i'.repeat(20_000));
+  });
+
+  it('gives two candidates the full single-diff cap and cuts on a character boundary', () => {
+    const diff = `-old\n+${'é'.repeat(20_000)}`; // 2 bytes per character
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'Merge.',
+      mergeCandidates: [
+        { label: 'A', agentName: 'Agent', diff },
+        { label: 'B', agentName: 'Agent', diff: '-old\n+short' },
+      ],
+    });
+    // 30 000 bytes of "é" is 15 000 characters: whole ones, no replacement glyph.
+    expect(prompt).toMatch(/\+é{14990,}\n… \(diff truncated\)/);
+    expect(prompt).not.toContain('\uFFFD');
+    expect(prompt).toContain('+short\n```');
+  });
+
   it('hands a resumed session the diff since it last saw the document', () => {
     const prompt = buildDocumentPrompt({
       documentPath: 'docs/spec.md',
diff --git a/electron/documents/prompt.ts b/electron/documents/prompt.ts
index 0dffe87f7..fb6281d07 100644
--- a/electron/documents/prompt.ts
+++ b/electron/documents/prompt.ts
@@ -2,6 +2,31 @@ import type { DocumentRationale, DocumentScope } from './types.js';
 
 /** Largest diff (in characters) handed to a resumed main session. */
 const MAX_CATCH_UP_DIFF_CHARS = 20_000;
+/*
+ * The prompt travels as one argv element, which Linux caps at 128 KiB, so
+ * the parts that grow with the proposals are budgeted in bytes: the diffs
+ * share one budget across candidates, and everything else is capped so the
+ * whole prompt stays under the limit even with six candidates.
+ */
+/** Bytes of proposal diffs a merging agent sees in total. */
+const MERGE_DIFF_BUDGET_BYTES = 60_000;
+/** Largest single diff, when few candidates leave room for it. */
+const MAX_MERGE_DIFF_BYTES = 30_000;
+const MAX_MERGE_NOTE_BYTES = 2_000;
+const MAX_MERGE_SUMMARY_BYTES = 500;
+const MAX_MERGE_INSTRUCTION_BYTES = 8_000;
+
+/** One proposal a merging agent is asked to fold into its version. */
+export interface MergeCandidateInput {
+  label: string;
+  agentName: string;
+  /** The proposal as a diff against the base the agent finds on disk. */
+  diff: string;
+  /** What the candidate said it did, when it said. */
+  summary?: string;
+  /** What the reviewer wrote on this candidate in the compare view. */
+  note?: string;
+}
 
 export interface DocumentPromptInput {
   documentPath: string;
@@ -11,6 +36,10 @@ export interface DocumentPromptInput {
   catchUpDiff?: string;
   /** Original task for the proposal already seeded into the worktree. */
   refinementInstruction?: string;
+  /** Proposals to combine; the file on disk is their common base. */
+  mergeCandidates?: MergeCandidateInput[];
+  /** The task those proposals answered. */
+  mergeInstruction?: string;
 }
 
 function quoteBlock(text: string): string {
@@ -20,6 +49,26 @@ function quoteBlock(text: string): string {
     .join('\n');
 }
 
+/** Cuts `text` to at most `maxBytes` of UTF-8 on a character boundary, marking the cut. */
+export function truncateBytes(text: string, maxBytes: number, marker = '… (truncated)'): string {
+  const bytes = new TextEncoder().encode(text);
+  if (bytes.length <= maxBytes) return text;
+  // A cut inside a multi-byte character decodes to U+FFFD at the end; drop it.
+  const head = new TextDecoder().decode(bytes.subarray(0, maxBytes)).replace(/\uFFFD+$/, '');
+  return `${head}\n${marker}`;
+}
+
+/** One proposal, as the merging agent reads it; `diffBytes` is its share of the budget. */
+function describeMergeCandidate(c: MergeCandidateInput, diffBytes: number): string {
+  const lines = [`### Candidate ${c.label} (${c.agentName})`];
+  if (c.summary?.trim())
+    lines.push(`Its own summary: ${truncateBytes(c.summary.trim(), MAX_MERGE_SUMMARY_BYTES)}`);
+  if (c.note?.trim())
+    lines.push(`The reviewer's note on it: ${truncateBytes(c.note.trim(), MAX_MERGE_NOTE_BYTES)}`);
+  lines.push('```diff', truncateBytes(c.diff, diffBytes, '… (diff truncated)'), '```');
+  return lines.join('\n');
+}
+
 /** Builds the instruction a headless agent receives for one proposal. */
 export function buildDocumentPrompt(input: DocumentPromptInput): string {
   const { documentPath, scope, instruction } = input;
@@ -52,6 +101,26 @@ export function buildDocumentPrompt(input: DocumentPromptInput): string {
     );
   }
 
+  if (input.mergeCandidates && input.mergeCandidates.length > 0) {
+    const n = input.mergeCandidates.length;
+    const diffBytes = Math.min(MAX_MERGE_DIFF_BYTES, Math.floor(MERGE_DIFF_BUDGET_BYTES / n));
+    parts.push(
+      [
+        `The file on disk is the base version. ${n} candidates proposed changes to it` +
+          (input.mergeInstruction !== undefined
+            ? `, answering this task:\n${quoteBlock(truncateBytes(input.mergeInstruction, MAX_MERGE_INSTRUCTION_BYTES))}`
+            : '.'),
+        '',
+        'Each candidate is shown below as a diff against that base. Produce one merged version: ' +
+          'keep every improvement worth keeping, resolve conflicts by choosing the stronger wording, ' +
+          'and drop what none of them would miss. Where the reviewer left a note on a candidate, follow it. ' +
+          'Say in the rationale which parts came from which candidate and what you left out.',
+        '',
+        ...input.mergeCandidates.map((c) => describeMergeCandidate(c, diffBytes)),
+      ].join('\n'),
+    );
+  }
+
   if (scope.wholeDocument) {
     parts.push('Scope: the whole document.');
   } else {
diff --git a/electron/documents/register.ts b/electron/documents/register.ts
index d1298c5be..d827e4a29 100644
--- a/electron/documents/register.ts
+++ b/electron/documents/register.ts
@@ -14,6 +14,7 @@ import {
 import {
   acceptDocumentCandidate,
   cancelDocumentRun,
+  discardDocumentEdits,
   dispatchDocumentRun,
   getDocumentAtCommit,
   getDocumentDiff,
@@ -100,6 +101,7 @@ export function registerDocumentHandlers(win: BrowserWindow): void {
       scope: args.scope,
       candidates: args.candidates,
       refinement: args.refinement,
+      merge: args.merge,
     });
   });
 
@@ -157,6 +159,10 @@ export function registerDocumentHandlers(win: BrowserWindow): void {
     return revertDocumentCommit(projectRootArg(args), validateSha(args.sha));
   });
 
+  ipcMain.handle(IPC.DiscardDocumentEdits, (_e, args) => {
+    return discardDocumentEdits(projectRootArg(args));
+  });
+
   // --- Annotations ---
   ipcMain.handle(IPC.ListDocumentAnnotations, (_e, args) => {
     return readAnnotations(projectRootArg(args));
diff --git a/electron/documents/runs.test.ts b/electron/documents/runs.test.ts
index a1085d922..46198ffd8 100644
--- a/electron/documents/runs.test.ts
+++ b/electron/documents/runs.test.ts
@@ -123,6 +123,18 @@ describe('sanitizeRunRecord', () => {
     };
     expect(sanitizeRunRecord(root, sneaky)).toBeNull();
   });
+  it('keeps a well-formed merge lineage and rejects a malformed one', () => {
+    const merge = { runId: 'run-0', candidateIds: ['c1', 'c2'] };
+    expect(sanitizeRunRecord(root, { ...good, merge })?.merge).toEqual(merge);
+    expect(
+      sanitizeRunRecord(root, { ...good, merge: { ...merge, candidateIds: ['c1'] } }),
+    ).toBeNull();
+    expect(
+      sanitizeRunRecord(root, { ...good, merge: { ...merge, candidateIds: ['c1', 'c1'] } }),
+    ).toBeNull();
+    expect(sanitizeRunRecord(root, { ...good, merge: { ...merge, runId: '../x' } })).toBeNull();
+  });
+
   it('rejects foreign branch names and bad shas', () => {
     expect(
       sanitizeRunRecord(root, { ...good, candidates: [{ ...good.candidates[0], branch: 'main' }] }),
diff --git a/electron/documents/runs.ts b/electron/documents/runs.ts
index 1bd721b52..6c0c7f322 100644
--- a/electron/documents/runs.ts
+++ b/electron/documents/runs.ts
@@ -18,7 +18,7 @@ import { loadEnvFile } from '../ipc/env-file.js';
 import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from '../ipc/git.js';
 import { git, gitOk } from './git.js';
 import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
-import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+import { buildDocumentPrompt, parseDocumentRationale, type MergeCandidateInput } from './prompt.js';
 import { appendCandidateLog, ensureDocumentLogsExclude } from './logs.js';
 import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from './shared.js';
 import type {
@@ -394,6 +394,7 @@ export function sanitizeRunRecord(projectRoot: string, raw: unknown): DocumentRu
       validateRunId(run.refinement.runId);
       validateCandidateId(run.refinement.candidateId);
     }
+    if (run.merge) validateMerge(run.merge);
   } catch {
     return null;
   }
@@ -699,6 +700,48 @@ export interface DispatchDocumentRunArgs {
   scope: unknown;
   candidates: unknown;
   refinement?: unknown;
+  merge?: unknown;
+}
+
+/** `{ runId, candidateIds }` as sent by the renderer: two or more proposals of one run. */
+function validateMerge(value: unknown): NonNullable<DocumentRunRecord['merge']> {
+  if (!value || typeof value !== 'object') throw new Error('merge must name the proposals');
+  const source = value as Record<string, unknown>;
+  const ids = source.candidateIds;
+  if (!Array.isArray(ids) || ids.length < 2) throw new Error('merge needs at least two proposals');
+  if (ids.length > MAX_DOCUMENT_CANDIDATES) throw new Error('merge names too many proposals');
+  const candidateIds = ids.map(validateCandidateId);
+  if (new Set(candidateIds).size !== candidateIds.length)
+    throw new Error('merge names a proposal twice');
+  return { runId: validateRunId(source.runId), candidateIds };
+}
+
+/** The proposals of `sourceRun` a merge folds together, each as a diff against the base. */
+async function mergeInputs(
+  projectRoot: string,
+  sourceRun: DocumentRunRecord,
+  candidateIds: readonly string[],
+): Promise<MergeCandidateInput[]> {
+  const inputs: MergeCandidateInput[] = [];
+  for (const id of candidateIds) {
+    const candidate = sourceRun.candidates.find((c) => c.id === id);
+    if (candidate?.status !== 'done' || !candidate.commitSha)
+      throw new Error(`Candidate ${id} has no completed proposal to merge.`);
+    const diff = await git(projectRoot, [
+      'diff',
+      `${sourceRun.baseSha}..${candidate.commitSha}`,
+      '--',
+      sourceRun.documentPath,
+    ]);
+    inputs.push({
+      label: candidate.label,
+      agentName: candidate.agentName,
+      diff,
+      summary: candidate.rationale?.summary,
+      note: candidate.note,
+    });
+  }
+  return inputs;
 }
 
 function parseChangedPaths(porcelainZ: string): string[] {
@@ -999,8 +1042,17 @@ export async function dispatchDocumentRun(
     // A rewritten candidate has different lines. Review the entire revision.
     scope = validateScope({ wholeDocument: true }, documentPath);
   }
+  let merge: DocumentRunRecord['merge'];
+  if (args.merge !== undefined) {
+    if (refinement) throw new Error('A run refines a proposal or merges proposals, not both.');
+    merge = validateMerge(args.merge);
+    // The merged version is judged as a whole, not against the original passage.
+    scope = validateScope({ wholeDocument: true }, documentPath);
+  }
   const specs = validateCandidateSpecs(args.candidates);
-  if (refinement) {
+  if (refinement || merge) {
+    // A revision or a merge is a fresh one-shot: the warm main session is
+    // neither resumed nor moved on to an unaccepted proposal.
     for (const spec of specs) {
       spec.isMain = false;
       spec.sessionId = undefined;
@@ -1013,14 +1065,20 @@ export async function dispatchDocumentRun(
   return withProjectLock(projectRoot, async () => {
     let sourceRun: DocumentRunRecord | undefined;
     let sourceContent: string | undefined;
-    if (refinement) {
-      sourceRun = requireRunRecord(projectRoot, refinement.runId);
+    let mergeCandidates: MergeCandidateInput[] | undefined;
+    const sourceRunId = refinement?.runId ?? merge?.runId;
+    if (sourceRunId) {
+      sourceRun = requireRunRecord(projectRoot, sourceRunId);
       if (typeof sourceRun.instruction !== 'string')
         throw new Error('The original proposal has an invalid instruction.');
       if (sourceRun.documentPath !== documentPath)
         throw new Error('The candidate belongs to another document.');
       if (sourceRun.status !== 'finished' && sourceRun.status !== 'stale')
-        throw new Error('Only proposals awaiting review can be refined.');
+        throw new Error(
+          `Only proposals awaiting review can be ${refinement ? 'refined' : 'merged'}.`,
+        );
+    }
+    if (refinement && sourceRun) {
       const source = sourceRun.candidates.find((c) => c.id === refinement.candidateId);
       if (source?.status !== 'done' || !source.commitSha)
         throw new Error('The candidate has no completed proposal to refine.');
@@ -1028,6 +1086,9 @@ export async function dispatchDocumentRun(
       if (content === null) throw new Error('The proposal document no longer exists.');
       sourceContent = content;
     }
+    if (merge && sourceRun) {
+      mergeCandidates = await mergeInputs(projectRoot, sourceRun, merge.candidateIds);
+    }
     if (!fs.existsSync(path.join(projectRoot, documentPath)))
       throw new Error(`Document not found: ${documentPath}`);
     if (specs.some((s) => s.isMain) && mainSessionBusy(projectRoot)) {
@@ -1057,6 +1118,7 @@ export async function dispatchDocumentRun(
       status: 'running',
       candidates: [],
       refinement,
+      merge,
     };
 
     const prepared: { spec: DocumentCandidateSpec; candidate: DocumentCandidateRecord }[] = [];
@@ -1114,7 +1176,9 @@ export async function dispatchDocumentRun(
           scope,
           instruction,
           catchUpDiff,
-          refinementInstruction: sourceRun?.instruction,
+          refinementInstruction: refinement ? sourceRun?.instruction : undefined,
+          mergeCandidates,
+          mergeInstruction: merge ? sourceRun?.instruction : undefined,
         });
         try {
           spawnCandidate(win, projectRoot, run, spec, candidate, prompt);
@@ -1544,6 +1608,19 @@ export async function revertDocumentCommit(projectRoot: string, sha: string): Pr
   });
 }
 
+/**
+ * Throws away the uncommitted edits to tracked content files: what the
+ * "uncommitted edits" chip counts, and what the next run would otherwise
+ * commit as `Manual edits`. Untracked files and everything under `.parallel/`
+ * (run records, annotations) stay.
+ */
+export async function discardDocumentEdits(projectRoot: string): Promise<void> {
+  await withProjectLock(projectRoot, async () => {
+    await git(projectRoot, ['reset', '-q', ...CONTENT_PATHSPEC]);
+    await git(projectRoot, ['checkout', '-q', ...CONTENT_PATHSPEC]);
+  });
+}
+
 /** Kill every running proposal process; used on app quit. */
 export function stopAllDocumentRuns(): void {
   for (const runId of [...activeRuns.keys()]) void killRun(runId);
diff --git a/electron/documents/types.ts b/electron/documents/types.ts
index 6c640c79e..7c86e7eee 100644
--- a/electron/documents/types.ts
+++ b/electron/documents/types.ts
@@ -114,6 +114,8 @@ export interface DocumentRunRecord {
   candidates: DocumentCandidateRecord[];
   /** Proposal used as the starting content of this revision; never accepted implicitly. */
   refinement?: { runId: string; candidateId: string };
+  /** Proposals of an earlier run this one was asked to combine into a single version. */
+  merge?: { runId: string; candidateIds: string[] };
   acceptedCandidateId?: string;
   /** Set when the reader kept only some of the accepted candidate's changes. */
   partialAcceptance?: { accepted: number; total: number };
@@ -205,6 +207,8 @@ export interface DocumentAnnotation {
   answerError?: string;
   /** Run this annotation was turned into, if any. */
   runId?: string;
+  /** The answered question this one follows up on; the agent sees that exchange too. */
+  followUpOf?: string;
 }
 
 /** Persisted as `.parallel/annotations.json` inside the document project. */
diff --git a/electron/ipc/channel-manifest.json b/electron/ipc/channel-manifest.json
index 3159120ab..548df3178 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -162,6 +162,7 @@
   "GetDocumentAtCommit": "get_document_at_commit",
   "GetDocumentDiff": "get_document_diff",
   "RevertDocumentCommit": "revert_document_commit",
+  "DiscardDocumentEdits": "discard_document_edits",
   "InspectDocumentFolder": "inspect_document_folder",
   "PrepareDocumentProject": "prepare_document_project",
   "DocumentChanged": "document_changed",
diff --git a/electron/preload.cjs b/electron/preload.cjs
index 9cd93e97d..948e39c24 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -166,6 +166,7 @@ const ALLOWED_CHANNELS = new Set([
   'get_document_at_commit',
   'get_document_diff',
   'revert_document_commit',
+  'discard_document_edits',
   'inspect_document_folder',
   'prepare_document_project',
   'document_changed',
diff --git a/src/App.tsx b/src/App.tsx
index 382a181b7..bf12a8a0b 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -88,12 +88,15 @@ import { createCtrlWheelZoomHandler } from './lib/wheelZoom';
 import { redrawAllTerminals } from './lib/terminalFitManager';
 import { ArenaOverlay } from './arena/ArenaOverlay';
 import { DocumentWorkspaceOverlay } from './documents/DocumentWorkspaceOverlay';
+import { isDocumentAgentTaskId } from './documents/agent-task';
 import {
   closeDocumentWorkspace,
   documentStore,
   initDocumentListeners,
+  setDocumentComposerDraft,
   setDocumentSelection,
 } from './documents/store';
+import { dismissPinnedBubbles } from './documents/workspace-ui';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
@@ -649,6 +652,10 @@ function App() {
     });
     setCloseHandlerReady(true);
 
+    // A document workspace's hidden agent task can be the active one; it has
+    // no worktree to close, merge or push and no panel a shell could show in.
+    const listedTask = (id: string) => store.tasks[id] !== undefined && !isDocumentAgentTaskId(id);
+
     const actionHandlers: Record<string, (e: KeyboardEvent) => void> = {
       'navigateRow:up': () => navigateRow('up'),
       'navigateRow:down': () => navigateRow('down'),
@@ -677,19 +684,19 @@ function App() {
           closeTerminal(id);
           return;
         }
-        if (store.tasks[id]) setPendingAction({ type: 'close', taskId: id });
+        if (listedTask(id)) setPendingAction({ type: 'close', taskId: id });
       },
       mergeTask: () => {
         const id = store.activeTaskId;
-        if (id && store.tasks[id]) setPendingAction({ type: 'merge', taskId: id });
+        if (id && listedTask(id)) setPendingAction({ type: 'merge', taskId: id });
       },
       pushTask: () => {
         const id = store.activeTaskId;
-        if (id && store.tasks[id]) setPendingAction({ type: 'push', taskId: id });
+        if (id && listedTask(id)) setPendingAction({ type: 'push', taskId: id });
       },
       spawnShell: () => {
         const id = store.activeTaskId;
-        if (id && store.tasks[id]) spawnShellForTask(id);
+        if (id && listedTask(id)) spawnShellForTask(id);
       },
       sendPrompt: () => sendActivePrompt(),
       createTerminal: (e) => {
@@ -706,8 +713,16 @@ function App() {
           return;
         }
         if (store.activeDocumentProjectId) {
-          if (documentStore.selection) setDocumentSelection(null);
-          else closeDocumentWorkspace();
+          // A pinned note covers the prose and goes first. Then the composer,
+          // up with a passage or with a draft opened from the toolbar or a
+          // note; either way Escape closes it before the workspace.
+          if (dismissPinnedBubbles()) return;
+          if (documentStore.selection || documentStore.composerDraft) {
+            setDocumentSelection(null);
+            setDocumentComposerDraft(null);
+          } else {
+            closeDocumentWorkspace();
+          }
           return;
         }
         if (store.showHelpDialog) {
diff --git a/src/components/AddProjectMenu.tsx b/src/components/AddProjectMenu.tsx
index 4a8170b71..65bb66473 100644
--- a/src/components/AddProjectMenu.tsx
+++ b/src/components/AddProjectMenu.tsx
@@ -22,20 +22,38 @@ const MENU_WIDTH = 232;
  * backing out of the question.
  */
 export function AddProjectMenu(props: AddProjectMenuProps) {
+  let menu: HTMLDivElement | undefined;
+  const items = () =>
+    Array.from(menu?.querySelectorAll<HTMLButtonElement>('[role="menuitem"]') ?? []);
+
   onMount(() => {
+    // Whatever opened the menu (the "+" button) gets the focus back when it goes.
+    const opener = document.activeElement;
+    requestAnimationFrame(() => items()[0]?.focus());
     const onKey = (e: KeyboardEvent) => {
       if (e.key === 'Escape') {
         e.stopPropagation();
         props.onClose();
+        return;
       }
+      if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp') return;
+      e.preventDefault();
+      const list = items();
+      const at = list.indexOf(document.activeElement as HTMLButtonElement);
+      const step = e.key === 'ArrowDown' ? 1 : -1;
+      list[(at + step + list.length) % list.length]?.focus();
     };
     window.addEventListener('keydown', onKey, true);
-    onCleanup(() => window.removeEventListener('keydown', onKey, true));
+    onCleanup(() => {
+      window.removeEventListener('keydown', onKey, true);
+      if (opener instanceof HTMLElement && opener.isConnected) opener.focus();
+    });
   });
 
   const row = (kind: ProjectKindChoice, icon: () => unknown, label: string, hint: string) => (
     <button
       type="button"
+      role="menuitem"
       onClick={() => props.onPick(kind)}
       style={{
         display: 'flex',
@@ -71,6 +89,7 @@ export function AddProjectMenu(props: AddProjectMenuProps) {
         style={{ position: 'fixed', inset: '0', 'z-index': '1200' }}
       >
         <div
+          ref={menu}
           role="menu"
           aria-label="Add project"
           onClick={(e) => e.stopPropagation()}
diff --git a/src/components/Dialog.tsx b/src/components/Dialog.tsx
index 51ea20de3..7f84ecabc 100644
--- a/src/components/Dialog.tsx
+++ b/src/components/Dialog.tsx
@@ -11,6 +11,8 @@ interface DialogProps {
   width?: string;
   zIndex?: number;
   panelStyle?: JSX.CSSProperties;
+  /** Overrides on the backdrop, e.g. a top inset that keeps the window chrome reachable. */
+  overlayStyle?: JSX.CSSProperties;
   /** Element id whose text labels this dialog (sets aria-labelledby). */
   labelledBy?: string;
   /** Element id (or space-separated list) describing this dialog (aria-describedby). */
@@ -93,6 +95,7 @@ export function Dialog(props: DialogProps) {
             'justify-content': 'center',
             background: 'rgba(0,0,0,0.55)',
             'z-index': String(props.zIndex ?? 1000),
+            ...props.overlayStyle,
           }}
           onClick={(e) => {
             if (e.target === e.currentTarget) props.onClose();
diff --git a/src/components/RemoveProjectConfirm.tsx b/src/components/RemoveProjectConfirm.tsx
index 7488fccce..a900d1e89 100644
--- a/src/components/RemoveProjectConfirm.tsx
+++ b/src/components/RemoveProjectConfirm.tsx
@@ -1,6 +1,7 @@
 import { ConfirmDialog } from './ConfirmDialog';
 import { store, removeProject, removeProjectWithTasks } from '../store/store';
 import { getProjectTaskCount } from './project-remove-confirmation';
+import { disposeDocumentAgentTask } from '../documents/agent-task';
 
 interface RemoveProjectConfirmProps {
   /** Project to remove; null keeps the dialog closed. */
@@ -32,6 +33,8 @@ export function RemoveProjectConfirm(props: RemoveProjectConfirmProps) {
       onConfirm={() => {
         const id = props.projectId;
         if (id) {
+          // A document project's agent sessions live outside the task lists.
+          void disposeDocumentAgentTask(id);
           if (taskCount() > 0) {
             removeProjectWithTasks(id);
           } else {
diff --git a/src/components/TaskAITerminal.tsx b/src/components/TaskAITerminal.tsx
index 9d2be526b..89b2b6f3e 100644
--- a/src/components/TaskAITerminal.tsx
+++ b/src/components/TaskAITerminal.tsx
@@ -20,6 +20,7 @@ import {
   toggleAITerminalLayout,
 } from '../store/store';
 import { markDirty, redrawTerminal } from '../lib/terminalFitManager';
+import { isAgentAskingQuestion } from '../store/taskStatus';
 import { isMac } from '../lib/platform';
 import { warn as logWarn } from '../lib/log';
 import { InfoBar } from './InfoBar';
@@ -53,7 +54,9 @@ interface TaskAITerminalProps {
     jump: ((stepIndex: number) => boolean) | undefined,
     firstJumpableIndex: number,
   ) => void;
-  onFileLink?: (filePath: string) => void;
+  /** First look at a Markdown path the agent printed; returns true when it
+   *  took the link. Otherwise the file opens in the Markdown viewer. */
+  onFileLink?: (filePath: string) => boolean;
 }
 
 export function TaskAITerminal(props: TaskAITerminalProps) {
@@ -140,6 +143,15 @@ export function TaskAITerminal(props: TaskAITerminalProps) {
       };
     }
 
+    // Common on a fresh session: a trust or permission prompt comes up before
+    // the first instruction can go in, and "waiting" would look stuck.
+    if (props.task.initialPrompt && isAgentAskingQuestion(props.task.agentIds[0] ?? '')) {
+      return {
+        title: 'Answer the agent to send the queued prompt',
+        text: 'Answer the agent to send the queued prompt',
+      };
+    }
+
     if (props.task.dockerMode && props.task.initialPrompt) {
       return {
         title: 'Starting Docker container…',
@@ -276,6 +288,7 @@ export function TaskAITerminal(props: TaskAITerminalProps) {
                       <button
                         type="button"
                         title={agent()?.def.description ?? agent()?.def.name}
+                        aria-pressed={selected()}
                         onClick={(e) => {
                           e.stopPropagation();
                           selectAgent(agentId);
@@ -419,7 +432,9 @@ export function TaskAITerminal(props: TaskAITerminalProps) {
                 tabsMode={tabsMode()}
                 visible={!tabsMode() || visibleAgentId() === agentId}
                 onSelect={() => selectAgent(agentId)}
-                onFileLink={handleFileLink}
+                onFileLink={(filePath) => {
+                  if (!props.onFileLink?.(filePath)) handleFileLink(filePath);
+                }}
                 onReady={registerAgentFocus}
                 onUnmount={unregisterAgentFocus}
                 onStepNavReady={(api) => handleStepNavReady(agentId, api)}
@@ -873,6 +888,8 @@ function AgentRestartMenu(props: { agentId: string; agentDefId: string }) {
         Restart
       </button>
       <button
+        aria-label="More ways to restart"
+        aria-expanded={showAgentMenu()}
         onClick={(e) => {
           e.stopPropagation();
           setShowAgentMenu(!showAgentMenu());
diff --git a/src/documents/AgentTerminal.client.test.tsx b/src/documents/AgentTerminal.client.test.tsx
new file mode 100644
index 000000000..6f3659677
--- /dev/null
+++ b/src/documents/AgentTerminal.client.test.tsx
@@ -0,0 +1,149 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore, store } from '../store/core';
+import { restartAgent } from '../store/agents';
+import { setInitialPrompt } from '../store/tasks';
+import { clearAgentActivity, markAgentOutput } from '../store/taskStatus';
+import { AgentTerminal } from './AgentTerminal';
+import { documentAgentTaskId, ensureDocumentAgentTask } from './agent-task';
+import type { AgentDef } from '../ipc/types';
+import type { Project } from '../store/types';
+
+const { openDocumentFile } = vi.hoisted(() => ({ openDocumentFile: vi.fn() }));
+
+vi.mock('../components/TerminalView', () => ({
+  TerminalView: (props: { onFileLink?: (filePath: string) => void }) => (
+    <div class="terminal-stub">
+      <button class="link-inside" onClick={() => props.onFileLink?.('/projects/docs/guide.md')} />
+      <button class="link-outside" onClick={() => props.onFileLink?.('/elsewhere/guide.md')} />
+    </div>
+  ),
+}));
+vi.mock('./store', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./store')>()),
+  openDocumentFile,
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  for (const id of Object.keys(store.agents)) clearAgentActivity(id);
+  setStore({
+    projects: [],
+    availableAgents: [],
+    tasks: {},
+    agents: {},
+    activeTaskId: null,
+    activeAgentId: null,
+  });
+  vi.clearAllMocks();
+});
+
+const agent = (id: string, name: string): AgentDef => ({
+  id,
+  name,
+  command: id,
+  args: [],
+  resume_args: [],
+  skip_permissions_args: [],
+  description: '',
+});
+
+function mount(agents: AgentDef[], terminalAgentId?: string, path = '/projects/docs'): HTMLElement {
+  setStore({
+    availableAgents: agents,
+    projects: [
+      {
+        id: 'docs',
+        name: 'Docs',
+        path,
+        color: '',
+        kind: 'document',
+        documentPath: 'notes.md',
+        documentTerminalAgentId: terminalAgentId,
+      },
+    ],
+  });
+  ensureDocumentAgentTask(store.projects[0] as Project);
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(render(() => <AgentTerminal project={store.projects[0] as Project} />, host));
+  return host;
+}
+
+describe('AgentTerminal', () => {
+  it('shows the task terminal with its prompt bar, agent chip and prompt box', () => {
+    const host = mount([agent('claude-code', 'Claude Code'), agent('codex', 'Codex')], 'codex');
+
+    expect(host.querySelector('.terminal-stub')).not.toBeNull();
+    expect(host.textContent).toContain('No prompts sent');
+    expect(host.textContent).toContain('Codex');
+    expect(host.querySelector('textarea.prompt-textarea')).not.toBeNull();
+  });
+
+  it('remembers the agent it runs on the project', () => {
+    mount([agent('codex', 'Codex')]);
+    expect(store.projects[0].documentTerminalAgentId).toBe('codex');
+  });
+
+  it('attaches to the session again when shown after a restart', () => {
+    mount([agent('codex', 'Codex')]);
+    const id = documentAgentTaskId('docs');
+    restartAgent(id, false);
+    expect(store.agents[id]?.attachExisting).toBe(false);
+    disposers.pop()?.();
+
+    mount([agent('codex', 'Codex')]);
+
+    expect(store.agents[id]?.attachExisting).toBe(true);
+  });
+
+  it('spawns an agent that exited afresh when shown again', () => {
+    mount([agent('codex', 'Codex')]);
+    const id = documentAgentTaskId('docs');
+    setStore('agents', id, { status: 'exited', exitCode: 1 });
+    disposers.pop()?.();
+
+    const host = mount([agent('codex', 'Codex')]);
+
+    expect(store.agents[id]?.status).toBe('running');
+    expect(store.agents[id]?.exitCode).toBeNull();
+    expect(host.textContent).not.toContain('exited');
+  });
+
+  it('opens a Markdown path inside the project in the viewer, others elsewhere', () => {
+    const host = mount([agent('codex', 'Codex')]);
+
+    host.querySelector<HTMLButtonElement>('.link-inside')?.click();
+    expect(openDocumentFile).toHaveBeenCalledWith('guide.md');
+
+    host.querySelector<HTMLButtonElement>('.link-outside')?.click();
+    expect(openDocumentFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('opens a path inside a project that was added with a trailing slash', () => {
+    const host = mount([agent('codex', 'Codex')], undefined, '/projects/docs/');
+
+    host.querySelector<HTMLButtonElement>('.link-inside')?.click();
+    expect(openDocumentFile).toHaveBeenCalledWith('guide.md');
+  });
+
+  it('says to answer the agent while the first instruction waits behind a question', () => {
+    const host = mount([agent('codex', 'Codex')]);
+    const id = documentAgentTaskId('docs');
+    setInitialPrompt(id, 'Tighten this.');
+    expect(host.textContent).toContain('Waiting to send prompt');
+
+    markAgentOutput(id, new TextEncoder().encode('Continue? [Y/n]'), id);
+
+    expect(host.textContent).toContain('Answer the agent to send the queued prompt');
+  });
+
+  it('says so when no agent is installed', () => {
+    const host = mount([]);
+    expect(host.textContent).toContain('No agent is installed.');
+    expect(host.querySelector('.terminal-stub')).toBeNull();
+  });
+});
diff --git a/src/documents/AgentTerminal.tsx b/src/documents/AgentTerminal.tsx
index e56b80bf4..2e434eba2 100644
--- a/src/documents/AgentTerminal.tsx
+++ b/src/documents/AgentTerminal.tsx
@@ -1,103 +1,97 @@
-import { For, Show, createMemo, createSignal } from 'solid-js';
-import { TerminalView } from '../components/TerminalView';
+import { Show, createEffect } from 'solid-js';
+import { TaskAITerminal } from '../components/TaskAITerminal';
+import { PromptInput } from '../components/PromptInput';
 import { store } from '../store/core';
-import { getAgentHookStatus } from '../store/agentHookStatus';
+import { effectiveAgentId } from '../store/agent-select';
+import { setActiveAgent } from '../store/navigation';
+import { setTaskFocusedPanel } from '../store/focused-panel';
+import { clearInitialPrompt, clearPrefillPrompt } from '../store/tasks';
 import { updateProject } from '../store/projects';
-import type { Project } from '../store/types';
-import { documentMainAgentId } from './store';
-import { documentAgentPtyId, documentAgentTaskId } from './agent-terminal';
-import { setAgentRunning, workspaceUi } from './workspace-ui';
+import type { Project, Task } from '../store/types';
+import { documentAgentTaskId, rearmDocumentAgents } from './agent-task';
+import { openDocumentFile } from './store';
 
 interface AgentTerminalProps {
   project: Project;
 }
 
 /**
- * The project's long-running interactive agent, in the app's own terminal.
- * It works in the checkout with the user watching, so its edits show up in the
- * viewer as they land and are committed as manual edits before the next run.
- * The session outlives the workspace: closing and reopening re-attaches.
+ * The project's long-running interactive agents, in the terminal, prompt box
+ * and agent chips a task has. They work in the checkout with the user
+ * watching, so their edits show up in the viewer as they land and are
+ * committed as manual edits before the next run. The sessions outlive the
+ * workspace: closing and reopening re-attaches.
  */
 export function AgentTerminal(props: AgentTerminalProps) {
-  const [generation, setGeneration] = createSignal(0);
-  const [exited, setExited] = createSignal<number | null | undefined>(undefined);
-  const ptyId = () => documentAgentPtyId(props.project.id);
-  const agents = createMemo(() => store.availableAgents.filter((a) => a.available !== false));
-  const agentId = () => props.project.documentTerminalAgentId ?? documentMainAgentId(props.project);
-  const agent = () => agents().find((a) => a.id === agentId()) ?? agents()[0];
-  const hook = () => getAgentHookStatus(ptyId());
-  const statusLabel = () => {
-    if (exited() !== undefined) return `exited (${exited() ?? '?'})`;
-    const h = hook();
-    if (h?.state === 'waiting') return 'needs you';
-    if (h?.state === 'working') return 'working';
-    return workspaceUi.agentRunning ? 'idle' : 'starting…';
-  };
+  const task = () => store.tasks[documentAgentTaskId(props.project.id)];
+  const firstAgentId = () => task()?.agentIds[0] ?? '';
 
-  // A restart remounts the terminal without attaching: the spawn replaces the
-  // live session in one step. Killing first and then attaching would latch
-  // the new terminal onto the dying process and show its exit.
-  function restart(nextAgentId?: string) {
-    setAgentRunning(false);
-    setExited(undefined);
-    setGeneration((g) => g + 1);
-    if (nextAgentId) updateProject(props.project.id, { documentTerminalAgentId: nextAgentId });
-  }
+  // The task itself is not persisted; remember its first agent's CLI on the
+  // project so the same one comes back after the app restarts.
+  createEffect(() => {
+    const defId = store.agents[firstAgentId()]?.def.id;
+    if (defId && defId !== props.project.documentTerminalAgentId) {
+      updateProject(props.project.id, { documentTerminalAgentId: defId });
+    }
+  });
 
+  // Keyed so children get the task record itself. A non-keyed accessor
+  // re-reads the project through the rail's <Show> on every access, and
+  // TaskAITerminal reads the task id from its cleanups: on close that read
+  // hits a memo already marked pending, which re-enters the disposal and
+  // crashes inside Solid.
   return (
     <div class="docws-agent-pane">
-      <div class="docws-agent-head">
-        <select
-          class="docws-select"
-          aria-label="Interactive agent"
-          value={agent()?.id}
-          onChange={(e) => restart(e.currentTarget.value)}
-        >
-          <For each={agents()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
-        </select>
-        <span
-          class="docws-agent-status"
-          classList={{ 'is-waiting': hook()?.state === 'waiting' && exited() === undefined }}
-        >
-          {statusLabel()}
-        </span>
-        <span class="docws-spacer" />
-        <button
-          type="button"
-          class="docws-btn docws-btn-sm"
-          title="Stop the session and start a fresh one"
-          onClick={() => restart()}
-        >
-          Restart
-        </button>
-      </div>
-      <Show when={agent()} keyed fallback={<div class="docws-empty">No agent is installed.</div>}>
-        {(def) => (
-          <div class="docws-agent-term">
-            <Show when={`${def.id}:${generation()}`} keyed>
-              <TerminalView
-                taskId={documentAgentTaskId(props.project.id)}
-                agentId={ptyId()}
-                command={def.command}
-                args={def.args}
-                cwd={props.project.path}
-                envFile={store.agentEnvFiles[def.id]}
-                bookmarksEnabled={false}
-                attachExisting={generation() === 0}
-                preserveSessionOnCleanup
-                fontSize={12}
-                onData={() => {
-                  if (!workspaceUi.agentRunning) setAgentRunning(true);
-                }}
-                onExit={(info) => {
-                  setAgentRunning(false);
-                  setExited(info.exit_code);
-                }}
-              />
-            </Show>
-          </div>
-        )}
+      <Show when={task()} keyed fallback={<div class="docws-empty">No agent is installed.</div>}>
+        {(t) => {
+          // Before the terminals mount: they read the attach flag once, on mount.
+          rearmDocumentAgents(t);
+          return <AgentTask task={t} />;
+        }}
       </Show>
     </div>
   );
 }
+
+/** A path the agent printed inside the project opens in the viewer, where the
+ *  work is; anything else keeps the terminal's own Markdown viewer. */
+function openInWorkspace(projectPath: string, filePath: string): boolean {
+  // A project added with a trailing slash would otherwise look for `…//`.
+  const root = `${projectPath.replace(/\/+$/, '')}/`;
+  if (!filePath.startsWith(root)) return false;
+  void openDocumentFile(filePath.slice(root.length));
+  return true;
+}
+
+function AgentTask(props: { task: Task }) {
+  return (
+    <>
+      <div class="docws-agent-term">
+        <TaskAITerminal
+          task={props.task}
+          isActive
+          selectedAgentId={effectiveAgentId(props.task) ?? ''}
+          onSelectAgent={setActiveAgent}
+          onFileLink={(filePath) => openInWorkspace(props.task.worktreePath, filePath)}
+          promptHandle={undefined}
+        />
+      </div>
+      <div class="docws-agent-prompt" onClick={() => setTaskFocusedPanel(props.task.id, 'prompt')}>
+        <PromptInput
+          taskId={props.task.id}
+          taskName={props.task.name}
+          agentId={props.task.agentIds[0] ?? ''}
+          initialPrompt={props.task.initialPrompt}
+          prefillPrompt={props.task.prefillPrompt}
+          onSend={(text) => {
+            // A prompt typed while an instruction waits leaves the wait in place.
+            if (props.task.initialPrompt?.trim() === text.trim()) {
+              clearInitialPrompt(props.task.id);
+            }
+          }}
+          onPrefillConsumed={() => clearPrefillPrompt(props.task.id)}
+        />
+      </div>
+    </>
+  );
+}
diff --git a/src/documents/AnnotationBubble.client.test.tsx b/src/documents/AnnotationBubble.client.test.tsx
new file mode 100644
index 000000000..2aabb6d15
--- /dev/null
+++ b/src/documents/AnnotationBubble.client.test.tsx
@@ -0,0 +1,131 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import type { AgentDef } from '../ipc/types';
+import { AnnotationBubble } from './AnnotationBubble';
+import type { DocumentAnnotation } from './types';
+
+const { askFollowUpQuestion, askDocumentAnnotation } = vi.hoisted(() => ({
+  askFollowUpQuestion: vi.fn(async () => ({ id: 'q-2' })),
+  askDocumentAnnotation: vi.fn(async () => {}),
+}));
+
+vi.mock('./store', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./store')>()),
+  askFollowUpQuestion,
+  askDocumentAnnotation,
+}));
+
+const disposers: Array<() => void> = [];
+
+const agentDef = (id: string, name: string): AgentDef => ({
+  id,
+  name,
+  command: id,
+  args: [],
+  resume_args: [],
+  skip_permissions_args: [],
+  description: '',
+});
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ availableAgents: [] });
+  vi.clearAllMocks();
+});
+
+function question(extra: Partial<DocumentAnnotation> = {}): DocumentAnnotation {
+  return {
+    id: 'q-1',
+    kind: 'question',
+    text: 'Why is this here?',
+    anchor: {
+      path: 'notes.md',
+      baseSha: null,
+      startLine: 1,
+      endLine: 2,
+      quote: 'The passage',
+      prefix: '',
+      suffix: '',
+    },
+    createdAt: '2026-01-01T00:00:00.000Z',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    resolved: false,
+    ...extra,
+  };
+}
+
+const answered = () =>
+  question({
+    answerStatus: 'answered',
+    answer: {
+      text: 'It anchors the section.',
+      agentId: 'codex',
+      agentName: 'Codex',
+      answeredAt: '2026-01-01T00:01:00.000Z',
+    },
+  });
+
+function mount(annotation: DocumentAnnotation): HTMLElement {
+  setStore({
+    availableAgents: [agentDef('claude-code', 'Claude Code'), agentDef('codex', 'Codex')],
+  });
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(() => <AnnotationBubble annotation={annotation} onMakeTask={() => {}} />, host),
+  );
+  return host;
+}
+
+function button(host: HTMLElement, label: string): HTMLButtonElement | null {
+  return (
+    Array.from(host.querySelectorAll('button')).find((b) => b.textContent?.trim() === label) ?? null
+  );
+}
+
+describe('AnnotationBubble follow-ups', () => {
+  it('offers a follow-up to the agent that answered instead of asking again', async () => {
+    const host = mount(answered());
+    expect(button(host, 'Ask again · Codex')).toBeNull();
+    expect(button(host, 'Ask again · Claude Code')).toBeNull();
+
+    button(host, 'Ask follow-up')?.click();
+
+    const box = host.querySelector<HTMLTextAreaElement>(
+      'textarea[aria-label="Follow-up question"]',
+    );
+    if (!box) throw new Error('No follow-up box');
+    box.value = 'Could it move up?';
+    box.dispatchEvent(new Event('input', { bubbles: true }));
+    box.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    await vi.waitFor(() =>
+      expect(askFollowUpQuestion).toHaveBeenCalledWith(
+        expect.objectContaining({ id: 'q-1' }),
+        'Could it move up?',
+        expect.objectContaining({ id: 'codex' }),
+      ),
+    );
+    await vi.waitFor(() =>
+      expect(host.querySelector('textarea[aria-label="Follow-up question"]')).toBeNull(),
+    );
+  });
+
+  it('keeps Ask again for a question whose answer failed', () => {
+    const host = mount(question({ answerStatus: 'failed', answerError: 'Timed out' }));
+    expect(button(host, 'Ask follow-up')).toBeNull();
+    expect(host.textContent).toContain('Timed out');
+    button(host, 'Ask · Codex')?.click();
+    expect(askDocumentAnnotation).toHaveBeenCalledWith(
+      'q-1',
+      expect.objectContaining({ id: 'codex' }),
+    );
+  });
+
+  it('marks a follow-up as continuing an earlier question', () => {
+    const host = mount(question({ id: 'q-2', followUpOf: 'q-1' }));
+    expect(host.querySelector('.docws-bubble-head')?.textContent).toContain('follow-up');
+  });
+});
diff --git a/src/documents/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
index 1418aed80..ed3b03610 100644
--- a/src/documents/AnnotationBubble.tsx
+++ b/src/documents/AnnotationBubble.tsx
@@ -4,6 +4,7 @@ import { store } from '../store/core';
 import { getProject } from '../store/projects';
 import {
   askDocumentAnnotation,
+  askFollowUpQuestion,
   deleteDocumentAnnotation,
   documentMainAgentId,
   documentStore,
@@ -11,8 +12,91 @@ import {
   updateDocumentAnnotationText,
 } from './store';
 import { documentAgentSupport } from '../../electron/documents/shared';
+import type { AgentDef } from '../ipc/types';
 import type { DocumentAnnotation } from './types';
 
+/**
+ * A follow-up continues an answered question as a new question on the same
+ * passage, asked of the agent that answered so it can pick up its own thread.
+ */
+function FollowUp(props: { annotation: DocumentAnnotation; agent: AgentDef }) {
+  const [open, setOpen] = createSignal(false);
+  const [text, setText] = createSignal('');
+  const [asking, setAsking] = createSignal(false);
+
+  async function ask() {
+    if (!text().trim() || asking()) return;
+    setAsking(true);
+    try {
+      const saved = await askFollowUpQuestion(props.annotation, text().trim(), props.agent);
+      if (saved) {
+        setOpen(false);
+        setText('');
+      }
+    } finally {
+      setAsking(false);
+    }
+  }
+
+  return (
+    <Show
+      when={open()}
+      fallback={
+        <div class="docws-run-actions">
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title={`Ask ${props.agent.name} a follow-up question; it sees this exchange`}
+            onClick={() => setOpen(true)}
+          >
+            Ask follow-up
+          </button>
+        </div>
+      }
+    >
+      <div class="docws-bubble-followup">
+        <textarea
+          class="docws-note"
+          aria-label="Follow-up question"
+          placeholder={`Follow-up for ${props.agent.name}…`}
+          value={text()}
+          disabled={asking()}
+          ref={(el) => requestAnimationFrame(() => el.focus())}
+          onInput={(e) => setText(e.currentTarget.value)}
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              e.stopPropagation();
+              setOpen(false);
+            }
+            if (e.key === 'Enter' && !e.shiftKey) {
+              e.preventDefault();
+              void ask();
+            }
+          }}
+        />
+        <div class="docws-run-actions">
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            disabled={!text().trim() || asking()}
+            onClick={() => void ask()}
+          >
+            {asking() ? 'Asking…' : `Ask ${props.agent.name}`}
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            disabled={asking()}
+            onClick={() => setOpen(false)}
+          >
+            Cancel
+          </button>
+        </div>
+      </div>
+    </Show>
+  );
+}
+
 interface AnnotationBubbleProps {
   annotation: DocumentAnnotation;
   /** The passage could not be found in the current version. */
@@ -44,6 +128,12 @@ export function AnnotationBubble(props: AnnotationBubbleProps) {
     askAgents().find((a) => a.id === documentMainAgentId(project())) ?? askAgents()[0];
   const isQuestion = () => props.annotation.kind === 'question';
   const status = () => props.annotation.answerStatus;
+  // A follow-up goes to whoever answered; the default agent stands in when that one is gone.
+  const followUpAgent = () =>
+    askAgents().find((a) => a.id === props.annotation.answer?.agentId) ?? defaultAgent();
+  // "Ask again" is for a question that has no usable answer; an answered one gets a follow-up.
+  const needsAnswer = () =>
+    status() !== 'pending' && (status() === 'failed' || !props.annotation.answer);
 
   function handleKeyDown(e: KeyboardEvent) {
     if (editing()) return;
@@ -98,6 +188,11 @@ export function AnnotationBubble(props: AnnotationBubbleProps) {
       >
         <div class="docws-bubble-head">
           <span class="docws-badge">{kindLabel()}</span>
+          <Show when={props.annotation.followUpOf}>
+            <span class="docws-badge" title="Continues an earlier question on this passage">
+              follow-up
+            </span>
+          </Show>
           <Show when={props.detached}>
             <span
               class="docws-badge docws-badge-stale"
@@ -197,7 +292,10 @@ export function AnnotationBubble(props: AnnotationBubbleProps) {
                 </>
               )}
             </Show>
-            <Show when={status() !== 'pending' && askAgents().length > 0}>
+            <Show when={status() === 'answered' && props.annotation.answer && followUpAgent()}>
+              {(agent) => <FollowUp annotation={props.annotation} agent={agent()} />}
+            </Show>
+            <Show when={needsAnswer() && askAgents().length > 0}>
               <div class="docws-run-actions">
                 <For each={askAgents()}>
                   {(agent) => (
diff --git a/src/documents/AnnotationMarker.client.test.tsx b/src/documents/AnnotationMarker.client.test.tsx
index a6f44ca63..8f9d30a60 100644
--- a/src/documents/AnnotationMarker.client.test.tsx
+++ b/src/documents/AnnotationMarker.client.test.tsx
@@ -1,7 +1,8 @@
 import { render } from 'solid-js/web';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { AnnotationMarker } from './AnnotationMarker';
 import type { DocumentAnnotation, DocumentAnnotationKind } from './types';
+import { dismissPinnedBubbles } from './workspace-ui';
 
 const disposers: Array<() => void> = [];
 
@@ -76,17 +77,41 @@ describe('AnnotationMarker', () => {
     }
   });
 
-  it('keeps the notes out of the prose and in the marker instead', () => {
+  it('keeps the notes out of the prose, floating over the window', () => {
     const host = mount([annotation('a', 'A thought', 'note')]);
 
-    expect(host.querySelector('.docws-marker-pop')?.textContent).toContain('A thought');
-    // Nothing but the marker: the block itself is left as it was written.
+    const pop = document.querySelector<HTMLElement>('.docws-marker-pop');
+    expect(pop?.textContent).toContain('A thought');
+    // Nothing but the symbol in the block: the popover cannot be clipped by a
+    // page element or covered by the composer, so it is not inside either.
     expect(host.firstElementChild?.className).toContain('docws-marker');
+    expect(host.contains(pop)).toBe(false);
+    expect(document.body.contains(pop)).toBe(true);
   });
 
-  it('shortens the time in the popover but keeps the exact stamp reachable', () => {
+  it('opens on hover and holds while the pointer crosses onto the popover', async () => {
     const host = mount([annotation('a', 'A thought', 'note')]);
-    const time = host.querySelector<HTMLElement>('.docws-marker-pop .docws-bubble-time');
+    const marker = host.querySelector<HTMLElement>('.docws-marker');
+    const pop = document.querySelector<HTMLElement>('.docws-marker-pop');
+    expect(pop?.classList.contains('is-open')).toBe(false);
+
+    marker?.dispatchEvent(new MouseEvent('mouseenter'));
+    expect(pop?.classList.contains('is-open')).toBe(true);
+    expect(pop?.style.top).toMatch(/px$/);
+
+    marker?.dispatchEvent(new MouseEvent('mouseleave'));
+    pop?.dispatchEvent(new MouseEvent('mouseenter'));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(pop?.classList.contains('is-open')).toBe(true);
+
+    pop?.dispatchEvent(new MouseEvent('mouseleave'));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(pop?.classList.contains('is-open')).toBe(false);
+  });
+
+  it('shortens the time in the popover but keeps the exact stamp reachable', () => {
+    mount([annotation('a', 'A thought', 'note')]);
+    const time = document.querySelector<HTMLElement>('.docws-marker-pop .docws-bubble-time');
     const exact = new Date('2026-01-01T00:00:00.000Z').toLocaleString();
 
     // The head shares its row with three buttons, so the stamp travels in the
@@ -99,6 +124,27 @@ describe('AnnotationMarker', () => {
     expect(time?.textContent?.length ?? 0).toBeLessThan(exact.length);
   });
 
+  it('lets go of its click-outside listener when unpinned and when unmounted', () => {
+    const added = vi.spyOn(document, 'addEventListener');
+    const removed = vi.spyOn(document, 'removeEventListener');
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+    const mousedowns = (spy: typeof added) =>
+      spy.mock.calls.filter(([type]) => type === 'mousedown').length;
+
+    button?.click();
+    button?.click();
+    button?.click();
+    expect(mousedowns(added)).toBe(2);
+    expect(mousedowns(removed)).toBe(1);
+
+    disposers.pop()?.();
+
+    expect(mousedowns(removed)).toBe(2);
+    added.mockRestore();
+    removed.mockRestore();
+  });
+
   it('pins the notes open on a click and lets Escape close them again', () => {
     const host = mount([annotation('a', 'A thought', 'note')]);
     const marker = host.querySelector<HTMLElement>('.docws-marker');
@@ -107,10 +153,60 @@ describe('AnnotationMarker', () => {
     button?.click();
     expect(button?.getAttribute('aria-expanded')).toBe('true');
     expect(marker?.className).toContain('is-pinned');
+    expect(document.querySelector('.docws-marker-pop')?.classList.contains('is-open')).toBe(true);
 
     marker?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
 
     expect(button?.getAttribute('aria-expanded')).toBe('false');
     expect(marker?.className).not.toContain('is-pinned');
+    expect(document.querySelector('.docws-marker-pop')?.classList.contains('is-open')).toBe(false);
+  });
+
+  it('takes Escape from inside the popover for itself and hands the focus back', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+    const pop = document.querySelector<HTMLElement>('.docws-marker-pop');
+    const resolve = pop?.querySelector<HTMLButtonElement>('button');
+    const escaped = vi.fn();
+    window.addEventListener('keydown', escaped);
+
+    button?.click();
+    resolve?.focus();
+    resolve?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+
+    // The window's shortcuts would read the same key as "close the workspace".
+    expect(escaped).not.toHaveBeenCalled();
+    expect(pop?.classList.contains('is-open')).toBe(false);
+    expect(document.activeElement).toBe(button);
+    window.removeEventListener('keydown', escaped);
+  });
+
+  it('closes a bubble that focus alone holds open, and stays closed on the symbol', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const marker = host.querySelector<HTMLElement>('.docws-marker');
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+    const pop = document.querySelector<HTMLElement>('.docws-marker-pop');
+
+    button?.focus();
+    expect(pop?.classList.contains('is-open')).toBe(true);
+
+    marker?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+
+    expect(pop?.classList.contains('is-open')).toBe(false);
+    expect(document.activeElement).toBe(button);
+  });
+
+  it('lets the workspace dismiss a pinned bubble from wherever the focus is', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+    const pop = document.querySelector<HTMLElement>('.docws-marker-pop');
+
+    expect(dismissPinnedBubbles()).toBe(false);
+    button?.click();
+    expect(pop?.classList.contains('is-open')).toBe(true);
+
+    expect(dismissPinnedBubbles()).toBe(true);
+    expect(pop?.classList.contains('is-open')).toBe(false);
+    expect(dismissPinnedBubbles()).toBe(false);
   });
 });
diff --git a/src/documents/AnnotationMarker.tsx b/src/documents/AnnotationMarker.tsx
index d73678066..1be895e0d 100644
--- a/src/documents/AnnotationMarker.tsx
+++ b/src/documents/AnnotationMarker.tsx
@@ -1,12 +1,35 @@
 import { For, Show, createEffect, createSignal, onCleanup } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import {
+  createAnchorEffect,
+  createHeldSignal,
+  placeBelow,
+  type BelowAnchor,
+} from '../lib/floating';
 import { AnnotationBubble } from './AnnotationBubble';
 import type { DocumentAnnotation } from './types';
+import { registerPinnedBubble } from './workspace-ui';
 
 interface AnnotationMarkerProps {
   annotations: DocumentAnnotation[];
   onMakeTask: (annotation: DocumentAnnotation) => void;
 }
 
+/** Widest the popover gets; narrower windows leave a margin either side. */
+const POP_WIDTH = 440;
+const EDGE = 12;
+/** How long the popover stays once the pointer leaves it or the symbol. */
+const HOVER_HOLD_MS = 150;
+
+/**
+ * Flush under the symbol, right-aligned with it, and kept inside the window;
+ * above the symbol when the popover would not fit below and has more room up.
+ */
+function placePopover(anchor: DOMRect, height?: number): BelowAnchor {
+  const viewport = { width: window.innerWidth, height: window.innerHeight };
+  return placeBelow(anchor, Math.min(POP_WIDTH, viewport.width - 64), viewport, EDGE, height);
+}
+
 function describe(annotations: readonly DocumentAnnotation[]): string {
   const questions = annotations.filter((a) => a.kind === 'question').length;
   const notes = annotations.length - questions;
@@ -24,25 +47,74 @@ function isAwaitingAnswer(annotation: DocumentAnnotation): boolean {
 /**
  * The notes on a passage as a symbol in its margin. They open over the
  * document on hover, on keyboard focus, or pinned by a click, so the prose
- * reads exactly as it does without them.
+ * reads exactly as it does without them. The popover floats over the window
+ * rather than sitting in the block: a page's own CSS can clip what is inside
+ * its elements, and nothing in the workspace may paint over an open note.
  */
 export function AnnotationMarker(props: AnnotationMarkerProps) {
   let root: HTMLDivElement | undefined;
+  let button: HTMLButtonElement | undefined;
+  let pop: HTMLDivElement | undefined;
   const [pinned, setPinned] = createSignal(false);
+  const [focused, setFocused] = createSignal(false);
+  const hover = createHeldSignal<true>(HOVER_HOLD_MS);
+  const open = () => pinned() || focused() || hover.value() === true;
+  const [pos, setPos] = createSignal<BelowAnchor | null>(null);
   const awaiting = () => props.annotations.some(isAwaitingAnswer);
   const label = () =>
     `${describe(props.annotations)}${awaiting() ? ', waiting for an answer' : ''}`;
 
+  createAnchorEffect(open, () => {
+    // The popover is hidden with visibility, not display, so its height is
+    // measurable before it opens.
+    if (button) setPos(placePopover(button.getBoundingClientRect(), pop?.offsetHeight));
+  });
+
+  /** The symbol and its popover count as one thing for focus and clicks. */
+  const inside = (node: EventTarget | null) =>
+    node instanceof Node && (!!root?.contains(node) || !!pop?.contains(node));
+
   // A pinned bubble covers the prose, so anything else the reader does closes it.
   createEffect(() => {
     if (!pinned()) return;
     const close = (e: MouseEvent) => {
-      if (!root?.contains(e.target as Node)) setPinned(false);
+      if (!inside(e.target)) setPinned(false);
     };
     document.addEventListener('mousedown', close);
     onCleanup(() => document.removeEventListener('mousedown', close));
   });
 
+  /**
+   * Shuts the bubble however it was opened. Focus goes back to the symbol
+   * first when it sat inside the popover, so it is not dropped as that hides.
+   */
+  function close() {
+    if (pop?.contains(document.activeElement)) button?.focus();
+    setPinned(false);
+    setFocused(false);
+    hover.clear();
+  }
+
+  // Escape anywhere in the workspace closes a pinned bubble before anything
+  // else does; with the focus elsewhere, the handler below never sees the key.
+  createEffect(() => {
+    if (!pinned()) return;
+    onCleanup(registerPinnedBubble(close));
+  });
+
+  // Bound natively, not delegated: the key has to stop at the bubble, before
+  // the window's shortcuts or a dialog under the popover take it for their own
+  // Escape and close the whole workspace along with the note.
+  function onKeyDown(e: KeyboardEvent) {
+    if (e.key !== 'Escape' || !open()) return;
+    e.stopPropagation();
+    close();
+  }
+
+  function onFocusOut(e: FocusEvent) {
+    if (!inside(e.relatedTarget)) setFocused(false);
+  }
+
   return (
     <div
       ref={root}
@@ -51,23 +123,24 @@ export function AnnotationMarker(props: AnnotationMarkerProps) {
         'is-pinned': pinned(),
         'is-question': props.annotations.some((a) => a.kind === 'question'),
       }}
-      onKeyDown={(e) => {
-        if (e.key !== 'Escape' || !pinned()) return;
-        e.stopPropagation();
-        setPinned(false);
-      }}
+      on:keydown={onKeyDown}
+      onMouseEnter={() => hover.set(true)}
+      onMouseLeave={() => hover.clear()}
+      onFocusIn={() => setFocused(true)}
+      onFocusOut={onFocusOut}
     >
       <button
+        ref={button}
         type="button"
         class="docws-marker-btn"
         aria-label={label()}
         aria-expanded={pinned()}
         onClick={(e) => {
-          const open = !pinned();
-          setPinned(open);
+          const next = !pinned();
+          setPinned(next);
           // Focus alone holds the bubble open, so a click that closes it has to
           // give the focus back. A keyboard activation (detail 0) keeps it.
-          if (!open && e.detail > 0) e.currentTarget.blur();
+          if (!next && e.detail > 0) e.currentTarget.blur();
         }}
       >
         {/* A question waiting on its agent spins in the margin, so the wait is
@@ -76,8 +149,8 @@ export function AnnotationMarker(props: AnnotationMarkerProps) {
           when={awaiting()}
           fallback={
             <svg
-              width="12"
-              height="12"
+              width="16"
+              height="16"
               viewBox="0 0 16 16"
               fill="none"
               stroke="currentColor"
@@ -96,13 +169,31 @@ export function AnnotationMarker(props: AnnotationMarkerProps) {
           <span class="docws-marker-count">{props.annotations.length}</span>
         </Show>
       </button>
-      <div class="docws-marker-pop" role="group" aria-label={label()}>
-        <For each={props.annotations}>
-          {(annotation) => (
-            <AnnotationBubble annotation={annotation} onMakeTask={props.onMakeTask} />
-          )}
-        </For>
-      </div>
+      <Portal>
+        <div
+          ref={pop}
+          class="docws-marker-pop"
+          classList={{ 'is-open': open() && pos() !== null }}
+          role="group"
+          aria-label={label()}
+          style={{
+            top: `${pos()?.top ?? 0}px`,
+            right: `${pos()?.right ?? 0}px`,
+            'max-height': `min(60vh, ${pos()?.maxHeight ?? 0}px)`,
+          }}
+          on:keydown={onKeyDown}
+          onMouseEnter={() => hover.set(true)}
+          onMouseLeave={() => hover.clear()}
+          onFocusIn={() => setFocused(true)}
+          onFocusOut={onFocusOut}
+        >
+          <For each={props.annotations}>
+            {(annotation) => (
+              <AnnotationBubble annotation={annotation} onMakeTask={props.onMakeTask} />
+            )}
+          </For>
+        </div>
+      </Portal>
     </div>
   );
 }
diff --git a/src/documents/BlockActions.client.test.tsx b/src/documents/BlockActions.client.test.tsx
index db5815f4a..e5f301c22 100644
--- a/src/documents/BlockActions.client.test.tsx
+++ b/src/documents/BlockActions.client.test.tsx
@@ -31,44 +31,65 @@ const blocks: DocumentBlock[] = [
   },
 ];
 
-describe('block hover actions', () => {
-  it('offers every composer mode and edit on each block, and reports the block picked', () => {
-    const onAction = vi.fn();
-    const onSelect = vi.fn();
-    const host = document.createElement('div');
-    document.body.append(host);
-    disposers.push(
-      render(
-        () => (
-          <DocumentViewer
-            blocks={blocks}
-            renderKey="t"
-            selectable
-            onSelect={onSelect}
-            onAction={onAction}
-          />
-        ),
-        host,
+function mount(extra: { selectable?: boolean; selection?: { start: number; end: number } } = {}) {
+  const onAction = vi.fn();
+  const onSelect = vi.fn();
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(
+      () => (
+        <DocumentViewer
+          blocks={blocks}
+          renderKey="t"
+          selectable={extra.selectable ?? true}
+          selection={extra.selection}
+          onSelect={onSelect}
+          onAction={onAction}
+        />
       ),
-    );
+      host,
+    ),
+  );
+  return { host, onAction, onSelect };
+}
+
+/** The pointer arrives on the prose of block `index`. */
+function hover(host: HTMLElement, index: number) {
+  host
+    .querySelector(`[data-block-index="${index}"] > div > *`)
+    ?.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+}
 
-    const toolbars = host.querySelectorAll('[data-block-index] .docws-block-actions');
-    expect(toolbars).toHaveLength(2);
-    const second = host.querySelector<HTMLElement>('[data-block-index="1"]');
-    const labels = Array.from(second?.querySelectorAll('button') ?? []).map((b) =>
+const toolbar = () => document.querySelector<HTMLElement>('.docws-block-actions');
+const isOpen = () => toolbar()?.classList.contains('is-open') === true;
+
+describe('block hover actions', () => {
+  it('floats one toolbar over the hovered block and reports the block picked', () => {
+    const { host, onAction, onSelect } = mount();
+    // Not in the block: a page element clipping its overflow could hide it there.
+    expect(host.querySelector('.docws-block-actions')).toBeNull();
+    expect(document.body.contains(toolbar())).toBe(true);
+    expect(isOpen()).toBe(false);
+
+    hover(host, 1);
+
+    expect(isOpen()).toBe(true);
+    expect(toolbar()?.style.top).toMatch(/px$/);
+    const labels = Array.from(toolbar()?.querySelectorAll('button') ?? []).map((b) =>
       b.getAttribute('aria-label'),
     );
     expect(labels).toEqual([
-      'Task on this block',
+      'Edit this block with agent',
       'Proposals for this block',
       'Note beside this block',
       'Ask an agent about this block',
       'Edit this block',
     ]);
 
-    second?.querySelector<HTMLButtonElement>('[aria-label="Note beside this block"]')?.click();
-    second?.querySelector<HTMLButtonElement>('[aria-label="Proposals for this block"]')?.click();
-    second?.querySelector<HTMLButtonElement>('[aria-label="Edit this block"]')?.click();
+    toolbar()?.querySelector<HTMLButtonElement>('[aria-label="Note beside this block"]')?.click();
+    toolbar()?.querySelector<HTMLButtonElement>('[aria-label="Proposals for this block"]')?.click();
+    toolbar()?.querySelector<HTMLButtonElement>('[aria-label="Edit this block"]')?.click();
 
     expect(onAction).toHaveBeenNthCalledWith(1, 'note', 1);
     expect(onAction).toHaveBeenNthCalledWith(2, 'proposals', 1);
@@ -76,53 +97,42 @@ describe('block hover actions', () => {
     expect(onSelect).not.toHaveBeenCalled();
   });
 
-  it('gives the task and edit actions different icons', () => {
-    const host = document.createElement('div');
-    document.body.append(host);
-    disposers.push(
-      render(
-        () => <DocumentViewer blocks={blocks} renderKey="t" selectable onAction={() => {}} />,
-        host,
-      ),
-    );
+  it('stays while the pointer climbs onto it, and goes once it leaves', async () => {
+    const { host } = mount();
+    hover(host, 0);
+    host.querySelector('.docws-content')?.dispatchEvent(new MouseEvent('mouseleave'));
+    toolbar()?.dispatchEvent(new MouseEvent('mouseenter'));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(isOpen()).toBe(true);
 
-    const icon = (label: string) =>
-      host.querySelector(`[aria-label="${label}"] path`)?.getAttribute('d');
-    expect(icon('Task on this block')).not.toEqual(icon('Edit this block'));
+    toolbar()?.dispatchEvent(new MouseEvent('mouseleave'));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(isOpen()).toBe(false);
   });
 
-  it('keeps the toolbars on the other blocks while a passage is picked', () => {
-    const host = document.createElement('div');
-    document.body.append(host);
-    disposers.push(
-      render(
-        () => (
-          <DocumentViewer
-            blocks={blocks}
-            renderKey="t"
-            selectable
-            selection={{ start: 1, end: 1 }}
-            onAction={() => {}}
-          />
-        ),
-        host,
-      ),
-    );
+  it('gives the task and edit actions different icons', () => {
+    mount();
+    const icon = (label: string) =>
+      toolbar()?.querySelector(`[aria-label="${label}"] path`)?.getAttribute('d');
+    expect(icon('Edit this block with agent')).not.toEqual(icon('Edit this block'));
+  });
 
-    // The picked block's toolbar is hidden by style; the rest stay in reach.
+  it('keeps the toolbar for the other blocks while a passage is picked', () => {
+    const { host } = mount({ selection: { start: 1, end: 1 } });
     expect(host.querySelector('[data-block-index="1"]')?.classList.contains('is-selected')).toBe(
       true,
     );
-    expect(host.querySelectorAll('[data-block-index="0"] .docws-block-actions')).toHaveLength(1);
+
+    // The picked block has the composer up on it; the bar would only repeat it.
+    hover(host, 1);
+    expect(isOpen()).toBe(false);
+
+    hover(host, 0);
+    expect(isOpen()).toBe(true);
   });
 
   it('shows no toolbar when the viewer is not selectable', () => {
-    const host = document.createElement('div');
-    document.body.append(host);
-    disposers.push(
-      render(() => <DocumentViewer blocks={blocks} renderKey="t" onAction={() => {}} />, host),
-    );
-
-    expect(host.querySelector('.docws-block-actions')).toBeNull();
+    mount({ selectable: false });
+    expect(toolbar()).toBeNull();
   });
 });
diff --git a/src/documents/BlockActions.tsx b/src/documents/BlockActions.tsx
index c9b214e54..f192322a8 100644
--- a/src/documents/BlockActions.tsx
+++ b/src/documents/BlockActions.tsx
@@ -1,4 +1,6 @@
-import { For } from 'solid-js';
+import { For, createSignal, type Accessor, type JSX } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { createAnchorEffect } from '../lib/floating';
 import type { ComposerMode } from './store';
 
 /** A composer mode, or editing the block's source in place. */
@@ -15,7 +17,7 @@ interface BlockAction {
 export const BLOCK_ACTIONS: readonly BlockAction[] = [
   {
     kind: 'task',
-    title: 'Task on this block',
+    title: 'Edit this block with agent',
     path: 'M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004L9.503.429Zm1.047 1.074L3.286 8.571A.25.25 0 0 0 3.462 9H6.75a.75.75 0 0 1 .694 1.034l-1.713 4.188 6.982-6.793A.25.25 0 0 0 12.538 7H9.25a.75.75 0 0 1-.683-1.06l2.008-4.418.003-.006a.036.036 0 0 0-.004-.009l-.006-.006-.008-.001c-.003 0-.006.002-.009.004Z',
   },
   {
@@ -44,10 +46,6 @@ function iconPath(kind: BlockActionKind): string {
   return BLOCK_ACTIONS.find((a) => a.kind === kind)?.path ?? '';
 }
 
-function iconSvg(path: string): string {
-  return `<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="${path}"/></svg>`;
-}
-
 /** One action's glyph, the same in the block toolbar and on the composer's tabs. */
 export function ActionIcon(props: { kind: BlockActionKind }) {
   return (
@@ -57,55 +55,68 @@ export function ActionIcon(props: { kind: BlockActionKind }) {
   );
 }
 
+/** Just inside the block's right edge, level with the markdown column's own inset. */
+const RIGHT_INSET = 6;
+
+interface BlockActionsProps {
+  /** The block the toolbar belongs to, on screen; null keeps the bar away. */
+  anchor: Accessor<HTMLElement | null>;
+  /** A page's § button and markers sit on the right; its toolbar takes the left. */
+  alignLeft?: boolean;
+  onAction: (kind: BlockActionKind) => void;
+  /** The pointer moved onto (true) or off (false) the bar itself. */
+  onPointer: (inside: boolean) => void;
+}
+
 /**
- * A block's hover toolbar: task, note, ask, edit. One click picks the block
- * and opens the composer on that mode (or the source editor), instead of pick
- * first and choose after.
+ * The hover toolbar of whichever block the pointer is on: task, proposals,
+ * note, ask, edit. One click picks the block and opens the composer on that
+ * mode (or the source editor), instead of pick first and choose after. One
+ * bar serves every block, floating over the window with its bottom edge on
+ * the block's top edge: in the gap above the prose, where a click meant for
+ * the passage cannot land on an icon, and out of reach of a page whose own
+ * CSS clips what its elements contain.
  */
-export function BlockActions(props: { onAction: (kind: BlockActionKind) => void }) {
+export function BlockActions(props: BlockActionsProps) {
+  const [style, setStyle] = createSignal<JSX.CSSProperties | null>(null);
+  const open = () => props.anchor() !== null;
+  createAnchorEffect(open, () => {
+    const rect = props.anchor()?.getBoundingClientRect();
+    if (!rect) return setStyle(null);
+    setStyle(
+      props.alignLeft
+        ? { top: `${rect.top}px`, left: `${rect.left}px` }
+        : { top: `${rect.top}px`, right: `${window.innerWidth - rect.right + RIGHT_INSET}px` },
+    );
+  });
   return (
-    <span class="docws-block-actions" role="toolbar" aria-label="Block actions">
-      <For each={BLOCK_ACTIONS}>
-        {(action) => (
-          <button
-            type="button"
-            class="docws-block-action"
-            data-kind={action.kind}
-            aria-label={action.title}
-            onClick={(e) => {
-              e.stopPropagation();
-              props.onAction(action.kind);
-            }}
-          >
-            <ActionIcon kind={action.kind} />
-          </button>
-        )}
-      </For>
-    </span>
+    <Portal>
+      <span
+        class="docws-block-actions"
+        classList={{ 'is-open': open() && style() !== null }}
+        role="toolbar"
+        aria-label="Block actions"
+        style={style() ?? undefined}
+        onMouseEnter={() => props.onPointer(true)}
+        onMouseLeave={() => props.onPointer(false)}
+      >
+        <For each={BLOCK_ACTIONS}>
+          {(action) => (
+            <button
+              type="button"
+              class="docws-block-action"
+              data-kind={action.kind}
+              aria-label={action.title}
+              onClick={(e) => {
+                e.stopPropagation();
+                props.onAction(action.kind);
+              }}
+            >
+              <ActionIcon kind={action.kind} />
+            </button>
+          )}
+        </For>
+      </span>
+    </Portal>
   );
 }
-
-/** The same toolbar as plain DOM, for pages whose markup is rendered whole. */
-export function createBlockActionsElement(
-  onAction: (kind: BlockActionKind, e: MouseEvent) => void,
-): HTMLSpanElement {
-  const bar = document.createElement('span');
-  bar.className = 'docws-block-actions';
-  bar.setAttribute('role', 'toolbar');
-  bar.setAttribute('aria-label', 'Block actions');
-  for (const action of BLOCK_ACTIONS) {
-    const button = document.createElement('button');
-    button.type = 'button';
-    button.className = 'docws-block-action';
-    button.dataset.kind = action.kind;
-    button.setAttribute('aria-label', action.title);
-    // A constant icon of our own, not page content.
-    button.innerHTML = iconSvg(action.path);
-    button.onclick = (e) => {
-      e.stopPropagation();
-      onAction(action.kind, e);
-    };
-    bar.append(button);
-  }
-  return bar;
-}
diff --git a/src/documents/BlockEditor.client.test.tsx b/src/documents/BlockEditor.client.test.tsx
index b79d872b4..01b7f4de8 100644
--- a/src/documents/BlockEditor.client.test.tsx
+++ b/src/documents/BlockEditor.client.test.tsx
@@ -75,6 +75,31 @@ describe('BlockEditor', () => {
     });
   });
 
+  it('asks before an edit in progress is thrown away', async () => {
+    const { onClose } = mount();
+    const cancel = document.querySelector('.docws-run-actions .docws-btn') as HTMLButtonElement;
+    const find = (label: string) =>
+      Array.from(document.querySelectorAll('button')).find((b) => b.textContent?.trim() === label);
+    cancel.click();
+    expect(onClose).toHaveBeenCalledOnce();
+
+    const input = document.querySelector('textarea') as HTMLTextAreaElement;
+    input.value = 'Half done';
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+    cancel.click();
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(document.body.textContent).toContain('Discard edits?');
+
+    find('Keep editing')?.click();
+    await vi.waitFor(() => expect(document.body.textContent).not.toContain('Discard edits?'));
+    expect(onClose).toHaveBeenCalledOnce();
+    expect(input.value).toBe('Half done');
+
+    cancel.click();
+    find('Discard')?.click();
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+
   it('preserves the edit and stays open when the file has changed', async () => {
     vi.mocked(invoke).mockRejectedValue(new Error('The document changed.'));
     const { onClose, onSaved } = mount();
diff --git a/src/documents/BlockEditor.tsx b/src/documents/BlockEditor.tsx
index 6ed63b6f2..f6178932e 100644
--- a/src/documents/BlockEditor.tsx
+++ b/src/documents/BlockEditor.tsx
@@ -1,5 +1,6 @@
 import { Show, createSignal, createUniqueId, untrack } from 'solid-js';
 import { Dialog } from '../components/Dialog';
+import { ConfirmDialog } from '../components/ConfirmDialog';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
 import { errMessage } from '../lib/log';
@@ -38,9 +39,15 @@ export function BlockEditor(props: {
   const [text, setText] = createSignal(initial);
   const [saving, setSaving] = createSignal(false);
   const [error, setError] = createSignal('');
+  const [confirmDiscard, setConfirmDiscard] = createSignal(false);
   const titleId = createUniqueId();
+  const dirty = () => text() !== initial;
+  // Cancel, Escape and a click beside the dialog all land here; an edit in
+  // progress is asked about first rather than lost.
   const close = () => {
-    if (!saving()) props.onClose();
+    if (saving()) return;
+    if (dirty()) setConfirmDiscard(true);
+    else props.onClose();
   };
 
   async function save() {
@@ -107,6 +114,19 @@ export function BlockEditor(props: {
           </Show>
         </div>
       </div>
+      <ConfirmDialog
+        open={confirmDiscard()}
+        title="Discard edits?"
+        message="The changes to this block have not been saved."
+        confirmLabel="Discard"
+        cancelLabel="Keep editing"
+        danger
+        onConfirm={() => {
+          setConfirmDiscard(false);
+          props.onClose();
+        }}
+        onCancel={() => setConfirmDiscard(false)}
+      />
     </Dialog>
   );
 }
diff --git a/src/documents/CandidateOutputDialog.tsx b/src/documents/CandidateOutputDialog.tsx
index 7fd52ad14..d212fface 100644
--- a/src/documents/CandidateOutputDialog.tsx
+++ b/src/documents/CandidateOutputDialog.tsx
@@ -1,4 +1,12 @@
-import { Show, createEffect, createMemo, createSignal, on, onCleanup } from 'solid-js';
+import {
+  Show,
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+  on,
+  onCleanup,
+} from 'solid-js';
 import { Dialog } from '../components/Dialog';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
@@ -19,6 +27,8 @@ export function CandidateOutputDialog() {
   const [text, setText] = createSignal('');
   const [error, setError] = createSignal<string | null>(null);
   let bodyRef: HTMLPreElement | undefined;
+  let closeRef: HTMLButtonElement | undefined;
+  const id = createUniqueId();
   const target = () => workspaceUi.output;
   const run = () => {
     const t = target();
@@ -51,6 +61,8 @@ export function CandidateOutputDialog() {
       setError(null);
       if (!t) return;
       void load();
+      // Focus moves into the dialog as it opens, as in the app's other dialogs.
+      requestAnimationFrame(() => closeRef?.focus());
     }),
   );
 
@@ -61,19 +73,28 @@ export function CandidateOutputDialog() {
   });
 
   return (
-    <Dialog open={!!target()} onClose={() => openCandidateOutput(null)} width="min(900px, 92vw)">
+    <Dialog
+      open={!!target()}
+      onClose={() => openCandidateOutput(null)}
+      width="min(900px, 92vw)"
+      labelledBy={`${id}-label ${id}-agent`}
+      describedBy={`${id}-instruction`}
+    >
       <Show when={candidate()}>
         {(c) => (
           <div class="docws-output">
             <div class="docws-output-head">
-              <span class="docws-candidate-label">{c().label}</span>
-              <span>{c().agentName}</span>
+              <span class="docws-candidate-label" id={`${id}-label`}>
+                {c().label}
+              </span>
+              <span id={`${id}-agent`}>{c().agentName}</span>
               <Show when={c().model || c().effort}>
                 <span class="docws-candidate-model">{modelLabel(c())}</span>
               </Show>
               <span class={`docws-badge docws-badge-${c().status}`}>{c().status}</span>
               <span class="docws-spacer" />
               <button
+                ref={closeRef}
                 type="button"
                 class="docws-btn docws-btn-sm"
                 onClick={() => openCandidateOutput(null)}
@@ -81,7 +102,7 @@ export function CandidateOutputDialog() {
                 Close
               </button>
             </div>
-            <div class="docws-run-instruction" title={run()?.instruction}>
+            <div class="docws-run-instruction" id={`${id}-instruction`} title={run()?.instruction}>
               {run()?.instruction}
             </div>
             <Show when={c().error}>
diff --git a/src/documents/CandidateRefinement.client.test.tsx b/src/documents/CandidateRefinement.client.test.tsx
index edd9f2fee..a88ddb1f5 100644
--- a/src/documents/CandidateRefinement.client.test.tsx
+++ b/src/documents/CandidateRefinement.client.test.tsx
@@ -64,6 +64,21 @@ describe('CandidateRefinement', () => {
     );
   });
 
+  it('closes on Escape without letting the key out, and puts focus back on its button', () => {
+    const host = mount();
+    const escaped = vi.fn();
+    document.addEventListener('keydown', escaped);
+    host
+      .querySelector('textarea')
+      ?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+
+    // The compare dialog listens on the document and would close over the form.
+    expect(escaped).not.toHaveBeenCalled();
+    expect(host.querySelector('textarea')).toBeNull();
+    expect(document.activeElement).toBe(host.querySelector('button'));
+    document.removeEventListener('keydown', escaped);
+  });
+
   it('keeps feedback available when dispatch fails', async () => {
     vi.mocked(refineDocumentCandidate).mockRejectedValue(new Error('Agent is unavailable'));
     const host = mount();
diff --git a/src/documents/CandidateRefinement.tsx b/src/documents/CandidateRefinement.tsx
index c20938d38..66b262894 100644
--- a/src/documents/CandidateRefinement.tsx
+++ b/src/documents/CandidateRefinement.tsx
@@ -1,12 +1,14 @@
-import { Show, createSignal } from 'solid-js';
+import { Show, createEffect, createSignal, onCleanup } from 'solid-js';
 import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
 import { refineDocumentCandidate } from './store';
 import { errMessage } from '../lib/log';
+import { registerCompareForm } from './workspace-ui';
 
 export function CandidateRefinement(props: {
   run: DocumentRunRecord;
   candidate: DocumentCandidateRecord;
 }) {
+  let toggle: HTMLButtonElement | undefined;
   const [open, setOpen] = createSignal(false);
   const [feedback, setFeedback] = createSignal('');
   const [starting, setStarting] = createSignal(false);
@@ -31,9 +33,29 @@ export function CandidateRefinement(props: {
     }
   }
 
+  function close() {
+    setOpen(false);
+    toggle?.focus();
+  }
+
+  // Registered while open, so Escape reaches the form from anywhere in the dialog.
+  createEffect(() => {
+    if (!open()) return;
+    onCleanup(registerCompareForm(close));
+  });
+
+  // Bound natively so the key stops here: the compare dialog listens on the
+  // document and would take the same Escape as its own and close over the form.
+  function onKeyDown(e: KeyboardEvent) {
+    if (e.key !== 'Escape') return;
+    e.stopPropagation();
+    close();
+  }
+
   return (
     <Show when={available()}>
       <button
+        ref={toggle}
         type="button"
         class="docws-btn docws-btn-sm"
         aria-expanded={open()}
@@ -43,7 +65,7 @@ export function CandidateRefinement(props: {
         Refine this candidate
       </button>
       <Show when={open()}>
-        <div class="docws-refinement">
+        <div class="docws-refinement" on:keydown={onKeyDown}>
           <p>
             Revise this whole proposal with the same agent and model. Your document stays unchanged.
           </p>
diff --git a/src/documents/CompareDialog.tsx b/src/documents/CompareDialog.tsx
index 34e4340a7..6d1f63ac5 100644
--- a/src/documents/CompareDialog.tsx
+++ b/src/documents/CompareDialog.tsx
@@ -1,50 +1,64 @@
-import { For, Show, createMemo, createSignal, type JSX } from 'solid-js';
+import { For, Show, createEffect, createMemo, createUniqueId, type JSX } from 'solid-js';
 import { Dialog } from '../components/Dialog';
+import { isMac, windowChromeTopInset } from '../lib/platform';
 import { closeDocumentCompare, documentStore, openDocumentCompare, reviewableRuns } from './store';
+import { closeTopCompareForm } from './workspace-ui';
 import { CompareView } from './CompareView';
 
-const WINDOWED: JSX.CSSProperties = {
+const PANEL: JSX.CSSProperties = {
   padding: '0',
   gap: '0',
   overflow: 'hidden',
-  height: 'min(920px, 88vh)',
-  'max-height': '88vh',
-};
-
-const FULLSCREEN: JSX.CSSProperties = {
-  padding: '0',
-  gap: '0',
-  overflow: 'hidden',
-  height: '100vh',
-  'max-height': '100vh',
+  height: '100%',
+  'max-height': 'none',
   'border-radius': '0',
   border: 'none',
 };
 
 /**
- * The compare view as a modal over the workspace: it wants the whole width
- * for base and candidates side by side, and it is a decision to make and
- * leave, not a place to stay. Grows to the full window on request.
+ * The compare view fills the window: base and candidates side by side want
+ * every pixel of width, and it is a decision to make and leave, not a place
+ * to stay. The window chrome stays reachable: on macOS the traffic lights are
+ * drawn over the head, which moves its content clear of them; elsewhere the
+ * app's own title bar keeps its strip above the backdrop.
  */
 export function CompareDialog() {
-  const [fullscreen, setFullscreen] = createSignal(false);
   const reviewable = createMemo(() => reviewableRuns());
   const runId = () => documentStore.compareRunId;
   const run = () => {
     const id = runId();
     return id ? documentStore.runs[id] : undefined;
   };
+  const titleId = createUniqueId();
+  let root: HTMLDivElement | undefined;
+
+  // Focus moves into the dialog as it opens, the way the app's other dialogs
+  // do, so the next Tab starts on the review and not wherever the click came from.
+  createEffect(() => {
+    if (!run()) return;
+    requestAnimationFrame(() => root?.focus());
+  });
+
+  // Escape and a click beside the dialog close an open refine or merge form
+  // first; the Close button always closes the dialog.
+  function dismiss() {
+    if (!closeTopCompareForm()) closeDocumentCompare();
+  }
 
   return (
     <Dialog
       open={!!run()}
-      onClose={closeDocumentCompare}
-      width={fullscreen() ? '100vw' : 'min(1500px, 94vw)'}
-      panelStyle={fullscreen() ? FULLSCREEN : WINDOWED}
+      onClose={dismiss}
+      width="100%"
+      panelStyle={PANEL}
+      overlayStyle={isMac ? undefined : { top: `${windowChromeTopInset}px` }}
+      labelledBy={titleId}
     >
-      <div class="docws-compare-dialog">
-        <div class="docws-compare-dialog-head">
-          <span class="docws-rail-title">Compare</span>
+      <div ref={root} class="docws-compare-dialog" classList={{ 'is-mac': isMac }} tabIndex={-1}>
+        <div class="docws-compare-dialog-head" data-tauri-drag-region>
+          <span class="docws-rail-title" id={titleId}>
+            Compare
+          </span>
           <Show when={reviewable().length > 1}>
             <select
               class="docws-select"
@@ -58,15 +72,6 @@ export function CompareDialog() {
             </select>
           </Show>
           <span class="docws-spacer" />
-          <button
-            type="button"
-            class="docws-btn docws-btn-sm"
-            aria-pressed={fullscreen()}
-            title={fullscreen() ? 'Back to a window' : 'Fill the window'}
-            onClick={() => setFullscreen((f) => !f)}
-          >
-            {fullscreen() ? 'Shrink' : 'Fullscreen'}
-          </button>
           <button
             type="button"
             class="docws-btn docws-btn-sm"
@@ -78,7 +83,12 @@ export function CompareDialog() {
         </div>
         <div class="docws-compare-dialog-body">
           <Show when={run() ? runId() : null} keyed>
-            {(id) => <CompareView run={documentStore.runs[id]} />}
+            {(id) => (
+              <CompareView
+                run={documentStore.runs[id]}
+                candidateId={documentStore.compareCandidateId ?? undefined}
+              />
+            )}
           </Show>
         </div>
       </div>
diff --git a/src/documents/CompareView.client.test.tsx b/src/documents/CompareView.client.test.tsx
index 63c2dec8b..2192eedd0 100644
--- a/src/documents/CompareView.client.test.tsx
+++ b/src/documents/CompareView.client.test.tsx
@@ -16,7 +16,11 @@ vi.mock('../lib/ipc', () => ({ invoke }));
 vi.mock('./store', async (importOriginal) => ({
   ...(await importOriginal<typeof import('./store')>()),
   acceptDocumentCandidate: vi.fn(async () => {}),
+  mergeDocumentCandidates: vi.fn(async () => {}),
 }));
+import { mergeDocumentCandidates } from './store';
+import { setStore } from '../store/core';
+import { closeTopCompareForm } from './workspace-ui';
 
 const disposers: Array<() => void> = [];
 const KEYS = ['docws-compare:base', 'docws-compare:candidate-0', 'docws-compare:candidate-1'];
@@ -24,6 +28,7 @@ const KEYS = ['docws-compare:base', 'docws-compare:candidate-0', 'docws-compare:
 afterEach(() => {
   while (disposers.length > 0) disposers.pop()?.();
   document.body.replaceChildren();
+  setStore({ availableAgents: [] });
   deletePanelUserSize(KEYS);
   vi.clearAllMocks();
   vi.restoreAllMocks();
@@ -64,7 +69,7 @@ it('previews retained prose, accepted deletions and insertions, then accepts tha
     expect(result?.textContent).not.toContain('Better intro.');
     expect(result?.textContent).not.toContain('Remove me.');
   });
-  button(column, 'Accept 2 of 3 changes').click();
+  button(column, 'Apply 2 of 3 changes').click();
   await vi.waitFor(() =>
     expect(acceptDocumentCandidate).toHaveBeenCalledWith('run-1', 'c1', {
       content: '# Doc\n\nOriginal intro.\n\n## Keep\n\n## End\n\nTail.\n\nNew ending.\n',
@@ -93,7 +98,7 @@ it('preserves choices when returning to changes and refreshes the preview after
       'Remove me.',
     ),
   );
-  expect(button(column, 'Accept 1 of 3 changes').disabled).toBe(false);
+  expect(button(column, 'Apply 1 of 3 changes').disabled).toBe(false);
 });
 
 it('shows the base when every change is declined and prevents accepting nothing', async () => {
@@ -108,7 +113,7 @@ it('shows the base when every change is declined and prevents accepting nothing'
     expect(result?.textContent).toContain('Remove me.');
     expect(result?.textContent).not.toContain('New ending.');
   });
-  expect(button(column, 'Accept 0 of 3 changes').disabled).toBe(true);
+  expect(button(column, 'Apply 0 of 3 changes').disabled).toBe(true);
 });
 
 it('disables acceptance while composing and reports a failed composition', async () => {
@@ -122,7 +127,7 @@ it('disables acceptance while composing and reports a failed composition', async
   );
   column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.click();
   button(column, 'Preview result').click();
-  expect(button(column, 'Accept 2 of 3 changes').disabled).toBe(true);
+  expect(button(column, 'Apply 2 of 3 changes').disabled).toBe(true);
   expect(column.textContent).toContain('Preparing preview');
   finish(null);
   await vi.waitFor(() =>
@@ -130,14 +135,113 @@ it('disables acceptance while composing and reports a failed composition', async
       'cannot be combined cleanly',
     ),
   );
-  expect(button(column, 'Accept 2 of 3 changes').disabled).toBe(true);
+  expect(button(column, 'Apply 2 of 3 changes').disabled).toBe(true);
   expect(column.textContent).toContain('Preview unavailable');
   expect(acceptDocumentCandidate).not.toHaveBeenCalled();
 });
 
+it('lets an agent merge the proposals the reviewer picks', async () => {
+  setStore({
+    availableAgents: [
+      {
+        id: 'claude-code',
+        name: 'Claude Code',
+        command: 'claude',
+        args: [],
+        resume_args: [],
+        skip_permissions_args: [],
+        description: '',
+      },
+    ],
+  });
+  const host = mount();
+  button(host, 'Merge with agent').click();
+
+  const panel = host.querySelector('[aria-label="Merge with agent"]');
+  if (!panel) throw new Error('Merge panel did not open');
+  const picks = panel.querySelectorAll<HTMLInputElement>('input[type="checkbox"]');
+  expect(picks).toHaveLength(2);
+  expect(panel.querySelector('[aria-pressed="true"]')?.textContent).toBe('Claude Code');
+  const generate = button(panel, 'Generate merged version');
+  expect(generate.disabled).toBe(false);
+
+  picks[1].click();
+  expect(generate.disabled).toBe(true);
+  picks[1].click();
+  generate.click();
+
+  await vi.waitFor(() => expect(mergeDocumentCandidates).toHaveBeenCalled());
+  const request = vi.mocked(mergeDocumentCandidates).mock.calls[0][0];
+  expect(request.run.id).toBe('run-1');
+  expect(request.candidateIds).toEqual(['c1', 'c2']);
+  expect(request.agent.id).toBe('claude-code');
+  expect(request.instruction).toContain('Combine the strongest parts');
+  await vi.waitFor(() => expect(host.querySelector('[aria-label="Merge with agent"]')).toBeNull());
+});
+
+it('keeps the merge form model-blind and lets Escape close the form alone', () => {
+  setStore({
+    availableAgents: [
+      {
+        id: 'claude-code',
+        name: 'Claude Code',
+        command: 'claude',
+        args: [],
+        resume_args: [],
+        skip_permissions_args: [],
+        description: '',
+      },
+    ],
+  });
+  const host = mount();
+  const escaped = vi.fn();
+  document.addEventListener('keydown', escaped);
+  const toggle = button(host, 'Merge with agent');
+  toggle.click();
+
+  const panel = host.querySelector('[aria-label="Merge with agent"]');
+  expect(panel?.textContent).toContain('Candidate A');
+  expect(panel?.textContent).not.toContain('Candidate A · Claude Code');
+  host.querySelector<HTMLInputElement>('.docws-compare-bar input[type="checkbox"]')?.click();
+  expect(panel?.textContent).toContain('Candidate A · Claude Code');
+
+  // The compare dialog listens on the document; the key must not reach it.
+  panel
+    ?.querySelector('textarea')
+    ?.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+  expect(escaped).not.toHaveBeenCalled();
+  expect(host.querySelector('[aria-label="Merge with agent"]')).toBeNull();
+  expect(document.activeElement).toBe(toggle);
+  document.removeEventListener('keydown', escaped);
+});
+
+it('closes an open merge form from the compare dialog before the dialog itself', () => {
+  setStore({
+    availableAgents: [
+      {
+        id: 'claude-code',
+        name: 'Claude Code',
+        command: 'claude',
+        args: [],
+        resume_args: [],
+        skip_permissions_args: [],
+        description: '',
+      },
+    ],
+  });
+  const host = mount();
+  button(host, 'Merge with agent').click();
+  expect(host.querySelector('[aria-label="Merge with agent"]')).not.toBeNull();
+
+  // With the focus outside the form, the dialog's Escape ends up here.
+  expect(closeTopCompareForm()).toBe(true);
+  expect(host.querySelector('[aria-label="Merge with agent"]')).toBeNull();
+  expect(closeTopCompareForm()).toBe(false);
+});
+
 it('keeps whole-candidate acceptance when every change is selected', async () => {
   const column = await comparison();
-  button(column, 'Accept this candidate').click();
+  button(column, 'Apply proposal').click();
   await vi.waitFor(() => expect(acceptDocumentCandidate).toHaveBeenCalledWith('run-1', 'c1'));
 });
 
@@ -153,6 +257,13 @@ function candidate(id: string, label: string): DocumentCandidateRecord {
     status: 'done',
     commitSha: `sha-${id}`,
     startedAt: new Date(0).toISOString(),
+    rationale: {
+      summary: 'Clarify the introduction.',
+      changes: ['Explain the delivery guarantees.'],
+      assumptions: [],
+      questions: [],
+      warnings: ['Verify delivery guarantees before publishing.'],
+    },
   };
 }
 
@@ -168,10 +279,10 @@ const run: DocumentRunRecord = {
   candidates: [candidate('c1', 'A'), candidate('c2', 'B')],
 };
 
-function mount(): HTMLElement {
+function mount(candidateId?: string): HTMLElement {
   const host = document.createElement('div');
   document.body.append(host);
-  disposers.push(render(() => <CompareView run={run} />, host));
+  disposers.push(render(() => <CompareView run={run} candidateId={candidateId} />, host));
   return host;
 }
 
@@ -189,6 +300,7 @@ describe('CompareView columns', () => {
 
   function columns(): { host: HTMLElement; seam: Element; base: HTMLElement } {
     const host = mount();
+    button(host, 'Show all proposals').click();
     const seam = host.querySelector('.docws-columns > .resize-handle');
     const base = host.querySelector<HTMLElement>('.docws-column-base');
     if (!seam || !base) throw new Error('compare columns did not render');
@@ -197,6 +309,7 @@ describe('CompareView columns', () => {
 
   it('offers a seam on every column', () => {
     const host = mount();
+    button(host, 'Show all proposals').click();
     expect(host.querySelectorAll('.docws-columns > .resize-handle')).toHaveLength(3);
   });
 
@@ -279,6 +392,7 @@ describe('CompareView columns', () => {
 
   it('sizes a candidate column from its own seam', () => {
     const host = mount();
+    button(host, 'Show all proposals').click();
     const seams = host.querySelectorAll('.docws-columns > .resize-handle');
 
     drag(seams[1], 100, 500);
@@ -287,3 +401,123 @@ describe('CompareView columns', () => {
     expect(getPanelUserSize('docws-compare:base')).toBeUndefined();
   });
 });
+
+describe('proposal tabs', () => {
+  it('shows the original and one proposal, supports keyboard switching and all-column mode', () => {
+    const host = mount();
+    const visible = () => host.querySelectorAll('.docws-column:not([hidden])');
+    expect(visible()).toHaveLength(2);
+    expect(host.querySelector('.docws-column-base')?.textContent).toContain('Original');
+    const tabs = host.querySelectorAll<HTMLButtonElement>('[role="tab"]');
+    expect(tabs).toHaveLength(2);
+    expect(tabs[0].getAttribute('aria-selected')).toBe('true');
+    tabs[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    expect(tabs[1].getAttribute('aria-selected')).toBe('true');
+    expect(document.activeElement).toBe(tabs[1]);
+    expect(host.querySelector<HTMLElement>('[aria-label="Candidate A"]')?.hidden).toBe(true);
+    expect(host.querySelector<HTMLElement>('[aria-label="Candidate B"]')?.hidden).toBe(false);
+    button(host, 'Show all proposals').click();
+    expect(visible()).toHaveLength(3);
+    button(host, 'Show one proposal').click();
+    expect(visible()).toHaveLength(2);
+    expect(host.querySelector<HTMLElement>('[aria-label="Candidate B"]')?.hidden).toBe(false);
+  });
+
+  it('opens the requested proposal and falls back to the first for an unknown id', () => {
+    const host = mount('c2');
+    expect(host.querySelector<HTMLElement>('[aria-label="Candidate B"]')?.hidden).toBe(false);
+    expect(host.querySelector<HTMLElement>('[aria-label="Candidate A"]')?.hidden).toBe(true);
+    const fallback = mount('missing');
+    expect(fallback.querySelector<HTMLElement>('[aria-label="Candidate A"]')?.hidden).toBe(false);
+  });
+
+  it('preserves partial acceptance and draft notes when switching proposals', async () => {
+    const column = await comparison();
+    const host = column.closest('.docws-compare');
+    if (!host) throw new Error('Comparison did not render');
+    column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.click();
+    const note = column.querySelector<HTMLTextAreaElement>('.docws-note');
+    if (!note) throw new Error('Proposal note did not render');
+    note.value = 'Keep this direction';
+    note.dispatchEvent(new Event('input', { bubbles: true }));
+    button(host, 'Proposal B').click();
+    button(host, 'Proposal A').click();
+    expect(column.querySelector<HTMLInputElement>('.docws-hunk-toggle input')?.checked).toBe(false);
+    expect(column.querySelector<HTMLTextAreaElement>('.docws-note')?.value).toBe(
+      'Keep this direction',
+    );
+    await vi.waitFor(() => expect(button(column, 'Apply 2 of 3 changes').disabled).toBe(false));
+  });
+});
+
+it('reveals a hidden proposal’s first change on first opening and preserves subsequent scroll', async () => {
+  const column = await comparison();
+  const host = column.closest('.docws-compare');
+  const body = host?.querySelector<HTMLElement>('[aria-label="Candidate B"] .docws-column-body');
+  if (!host || !body) throw new Error('Comparison did not render');
+  await vi.waitFor(() =>
+    expect(body.querySelector('.doc-block[data-change="changed"]')).not.toBeNull(),
+  );
+  const changed = body.querySelector<HTMLElement>('.doc-block[data-change="changed"]');
+  if (!changed) throw new Error('Change did not render');
+  changed.getBoundingClientRect = () => ({ top: 1000 }) as DOMRect;
+  button(host, 'Proposal B').click();
+  await vi.waitFor(() => expect(body.scrollTop).toBe(1000));
+  body.scrollTop = 123;
+  button(host, 'Proposal A').click();
+  button(host, 'Proposal B').click();
+  await new Promise((resolve) => requestAnimationFrame(resolve));
+  expect(body.scrollTop).toBe(123);
+});
+
+it('collapses reasoning and notes while keeping warnings and apply controls outside the disclosure', async () => {
+  const host = mount();
+  const column = host.querySelector('[aria-label="Candidate A"]');
+  const details = column?.querySelector<HTMLDetailsElement>('details');
+  expect(details).not.toBeNull();
+  expect(details?.open).toBe(false);
+  expect(details?.querySelector('.docws-note')).not.toBeNull();
+  const warning = column?.querySelector('.docws-warning');
+  expect(warning?.textContent).toContain('Verify delivery guarantees');
+  expect(details?.contains(warning ?? null)).toBe(false);
+  const apply = button(host, 'Apply proposal');
+  expect(details?.contains(apply)).toBe(false);
+  expect(apply.closest('.docws-column-actions')).not.toBeNull();
+  expect(column?.querySelector('.docws-column-head')?.contains(apply)).toBe(false);
+});
+
+it('navigates the original and proposal together, including deletions', async () => {
+  const column = await comparison();
+  const host = column.closest('.docws-compare');
+  if (!host) throw new Error('Comparison missing');
+  const scroll = vi.spyOn(Element.prototype, 'scrollIntoView');
+  scroll.mockClear();
+  column.querySelector<HTMLButtonElement>('[title="Next change"]')?.click();
+  expect(scroll).toHaveBeenCalledTimes(2);
+  expect(scroll.mock.instances.map((el) => (el as HTMLElement).dataset.blockIndex)).toEqual([
+    '1',
+    '1',
+  ]);
+  scroll.mockClear();
+  column.querySelector<HTMLButtonElement>('[title="Next change"]')?.click();
+  expect(scroll.mock.instances.map((el) => (el as HTMLElement).dataset.blockIndex)).toEqual([
+    '3',
+    '3',
+  ]);
+  expect(column.textContent).toContain('2 of 3 changes');
+});
+
+it('hides unchanged markdown while retaining the anchors for deletions', async () => {
+  const column = await comparison();
+  const host = column.closest('.docws-compare');
+  if (!host) throw new Error('Comparison missing');
+  host.querySelector<HTMLInputElement>('[aria-label="Changes only"]')?.click();
+  const title = column.querySelector<HTMLElement>('[data-block-index="0"]');
+  expect(title?.hidden).toBe(true);
+  expect(column.querySelector<HTMLElement>('[data-block-index="3"]')?.hidden).toBe(false);
+  expect(host.querySelector<HTMLElement>('.docws-column-base [data-block-index="3"]')?.hidden).toBe(
+    false,
+  );
+  host.querySelector<HTMLInputElement>('[aria-label="Changes only"]')?.click();
+  expect(title?.hidden).toBe(false);
+});
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
index 4e2684ebb..a7c385aff 100644
--- a/src/documents/CompareView.tsx
+++ b/src/documents/CompareView.tsx
@@ -6,23 +6,31 @@ import {
   createMemo,
   createResource,
   createSignal,
+  createUniqueId,
   on,
   onCleanup,
   untrack,
   type JSX,
 } from 'solid-js';
 import { CandidateRefinement } from './CandidateRefinement';
+import { MergeWithAgent } from './MergeWithAgent';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
 import { diffBlocks, type BlockChange, type DocumentBlock } from './markdown-blocks';
-import { blockHunks, composeVerifiedDocument, hunkLabel, hunkLeadBlocks } from './block-merge';
+import {
+  type BlockHunk,
+  blockHunks,
+  composeVerifiedDocument,
+  hunkLabel,
+  hunkLeadBlocks,
+} from './block-merge';
 import {
   acceptDocumentCandidate,
   documentStore,
   modelLabel,
-  rejectDocumentRun,
   setDocumentCandidateNote,
 } from './store';
+import { RejectRunButton } from './RejectRunConfirm';
 import { getProject } from '../store/projects';
 import { deletePanelUserSize, getPanelUserSize, setPanelUserSize } from '../store/store';
 import { showNotification } from '../store/notification';
@@ -59,43 +67,84 @@ function scopeRange(blocks: readonly DocumentBlock[], run: DocumentRunRecord): B
   return start === -1 ? null : { start, end };
 }
 
-/** Scroll a column so its first block matching `selector` sits in the upper third. */
-function revealFirst(body: HTMLElement | undefined, selector: string): void {
+/**
+ * Scroll a column so its first block matching `selector` sits in the upper
+ * third. False when there is no such block yet.
+ */
+function revealFirst(body: HTMLElement | undefined, selector: string): boolean {
   const target = body?.querySelector<HTMLElement>(selector);
-  if (!body || !target) return;
+  if (!body || !target) return false;
   const offset = target.getBoundingClientRect().top - body.getBoundingClientRect().top;
   body.scrollTop += offset - body.clientHeight / 3;
+  return true;
+}
+
+function plural(n: number, noun: string): string {
+  return `${n} ${noun}${n === 1 ? '' : 's'}`;
+}
+
+function reviewBlocks(
+  hunks: readonly BlockHunk[],
+  side: 'base' | 'cand',
+  count: number,
+): Set<number> {
+  const visible = new Set<number>();
+  for (const hunk of hunks) {
+    const start = hunk[side === 'base' ? 'baseStart' : 'candStart'];
+    const end = hunk[side === 'base' ? 'baseEnd' : 'candEnd'];
+    for (let i = start; i < end; i++) visible.add(i);
+    if (start === end && count > 0) visible.add(Math.min(start, count - 1));
+  }
+  return visible;
 }
 
-function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: number }) {
+function ChangeNav(props: {
+  body: () => HTMLDivElement | undefined;
+  baseBody: () => HTMLDivElement | undefined;
+  hunks: BlockHunk[];
+  baseCount: number;
+  candidateCount: number;
+}) {
   const [cursor, setCursor] = createSignal(-1);
   function go(delta: number) {
-    const body = props.body();
-    if (!body) return;
-    const targets = body.querySelectorAll<HTMLElement>('.doc-block:not([data-change="same"])');
-    if (targets.length === 0) return;
-    const next = (cursor() + delta + targets.length) % targets.length;
+    const count = props.hunks.length;
+    if (!count) return;
+    const next = cursor() < 0 ? (delta > 0 ? 0 : count - 1) : (cursor() + delta + count) % count;
     setCursor(next);
-    targets[next].scrollIntoView({ block: 'center', behavior: 'smooth' });
+    const hunk = props.hunks[next];
+    const reveal = (body: HTMLElement | undefined, index: number) =>
+      body?.querySelector<HTMLElement>(`[data-block-index="${index}"]`)?.scrollIntoView({
+        block: 'center',
+        behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches
+          ? 'instant'
+          : 'smooth',
+      });
+    reveal(props.baseBody(), Math.min(hunk.baseStart, props.baseCount - 1));
+    reveal(props.body(), Math.min(hunk.candStart, props.candidateCount - 1));
   }
   return (
     <span class="docws-nav">
       <button
         type="button"
         class="docws-btn docws-btn-sm"
+        disabled={!props.hunks.length}
         onClick={() => go(-1)}
         title="Previous change"
+        aria-label="Previous change"
       >
         ‹
       </button>
       <span>
-        {props.count} changed block{props.count === 1 ? '' : 's'}
+        {cursor() < 0 ? '' : `${cursor() + 1} of `}
+        {plural(props.hunks.length, 'change')}
       </span>
       <button
         type="button"
         class="docws-btn docws-btn-sm"
+        disabled={!props.hunks.length}
         onClick={() => go(1)}
         title="Next change"
+        aria-label="Next change"
       >
         ›
       </button>
@@ -103,7 +152,7 @@ function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: numbe
   );
 }
 
-function Rationale(props: { candidate: DocumentCandidateRecord }) {
+function Rationale(props: { candidate: DocumentCandidateRecord; children: JSX.Element }) {
   const r = () => props.candidate.rationale;
   const list = (label: string, items: string[] | undefined, cls?: string) => (
     <Show when={items && items.length > 0}>
@@ -115,10 +164,19 @@ function Rationale(props: { candidate: DocumentCandidateRecord }) {
   );
   return (
     <div class="docws-rationale">
-      <div class="docws-rationale-summary">{r()?.summary ?? 'No rationale returned.'}</div>
-      {list('Changes', r()?.changes)}
-      {list('Assumptions', r()?.assumptions)}
-      {list('Open questions', r()?.questions)}
+      <div class="docws-rationale-summary" title={r()?.summary}>
+        {r()?.summary ?? 'No rationale returned.'}
+      </div>
+      <details class="docws-review-details">
+        <summary>Reasoning and notes</summary>
+        <div class="docws-review-details-body">
+          <p>{r()?.summary ?? 'No rationale returned.'}</p>
+          {list('Changes', r()?.changes)}
+          {list('Assumptions', r()?.assumptions)}
+          {list('Open questions', r()?.questions)}
+          {props.children}
+        </div>
+      </details>
       {list('Warnings', r()?.warnings, 'docws-warning')}
       <Show when={props.candidate.outOfScopeFiles?.length}>
         <div class="docws-warning">
@@ -214,8 +272,13 @@ function CandidateColumn(props: {
   partialCapable: boolean;
   revealAgents: boolean;
   showSource: boolean;
+  changesOnly: boolean;
+  baseBody: () => HTMLDivElement | undefined;
+  hidden: boolean;
+  panelId: string;
+  tabId?: string;
   /** Reports which base blocks this candidate changed or removed. */
-  onBaseChanges: (candidateId: string, changes: BlockChange[]) => void;
+  onBaseChanges: (candidateId: string, changes: BlockChange[], hunks: BlockHunk[]) => void;
   /** Width the reader dragged this column to, if any. */
   style?: JSX.CSSProperties;
 }) {
@@ -232,13 +295,20 @@ function CandidateColumn(props: {
   const changes = () => blockDiff().candidate;
   const changedCount = () => changes().filter((c) => c !== 'same').length;
   createEffect(() => {
-    if (rendered.blocks().length > 0) props.onBaseChanges(props.candidate.id, blockDiff().base);
+    if (rendered.blocks().length > 0)
+      props.onBaseChanges(props.candidate.id, blockDiff().base, blockHunks(blockDiff()));
   });
-  // Open on the first changed block: the decision is there, not at the title.
+  // Hidden tabs have no layout. Reveal the first change once the proposal is
+  // visible, then preserve the reader's position when switching tabs.
+  let revealed = false;
   createEffect(
-    on(changedCount, (count) => {
-      if (count === 0) return;
-      requestAnimationFrame(() => revealFirst(bodyRef, '.doc-block:not([data-change="same"])'));
+    on([changedCount, () => props.hidden], ([count, hidden]) => {
+      if (count === 0 || hidden || revealed) return;
+      const frame = requestAnimationFrame(() => {
+        revealFirst(bodyRef, '.doc-block:not([data-change="same"])');
+        revealed = true;
+      });
+      onCleanup(() => cancelAnimationFrame(frame));
     }),
   );
   const [diff] = createResource(
@@ -256,6 +326,7 @@ function CandidateColumn(props: {
   // Partial acceptance: every change is kept until the reader declines it, so
   // the default is exactly the whole-candidate acceptance it replaces.
   const hunks = createMemo(() => blockHunks(blockDiff()));
+  const visible = createMemo(() => reviewBlocks(hunks(), 'cand', rendered.blocks().length));
   const leads = createMemo(() => hunkLeadBlocks(hunks(), rendered.blocks().length));
   const partial = createMemo(
     () => props.partialCapable && !rendered.page() && hunks().length > 1 && !!leads(),
@@ -292,7 +363,9 @@ function CandidateColumn(props: {
     return out;
   });
   const hunkLeads = (index: number) => {
-    if (!partial()) return [];
+    // Gone while the acceptance runs: a toggle that no longer acts would still
+    // flip on screen, and come back out of step with what was sent.
+    if (!partial() || accepting()) return [];
     return (leads()?.get(index) ?? []).map((hunk) => ({
       id: hunk.id,
       accepted: !declined().has(hunk.id),
@@ -377,64 +450,44 @@ function CandidateColumn(props: {
   }
 
   return (
-    <section class="docws-column" style={props.style} aria-label={title()}>
+    <section
+      class="docws-column"
+      style={props.style}
+      aria-label={title()}
+      hidden={props.hidden}
+      id={props.panelId}
+      role={props.tabId ? 'tabpanel' : undefined}
+      aria-labelledby={props.tabId}
+      tabIndex={props.tabId ? 0 : undefined}
+    >
       <div class="docws-column-head">
         <div class="docws-column-title">
           <span class="docws-candidate-label">{props.candidate.label}</span>
           <span>{title()}</span>
           <span style={{ 'margin-left': 'auto' }}>
-            <Show when={!previewing()}>
-              <ChangeNav body={() => bodyRef} count={changedCount()} />
+            <Show when={!previewing() && !props.showSource}>
+              <ChangeNav
+                body={() => bodyRef}
+                baseBody={props.baseBody}
+                hunks={hunks()}
+                baseCount={props.baseBlocks.length}
+                candidateCount={rendered.blocks().length}
+              />
             </Show>
           </span>
         </div>
-        <Rationale candidate={props.candidate} />
-        <textarea
-          class="docws-note"
-          placeholder="Your note on this candidate…"
-          value={note()}
-          onInput={(e) => setNote(e.currentTarget.value)}
-          onBlur={() => {
-            if (note() !== (props.candidate.note ?? ''))
-              void setDocumentCandidateNote(props.run.id, props.candidate.id, note());
-          }}
-        />
-        <div class="docws-run-actions">
-          <Show when={partial() && declined().size > 0}>
-            <button
-              type="button"
-              class="docws-btn docws-btn-sm"
-              aria-pressed={previewing()}
-              onClick={() => setShowPreview((value) => !value)}
-            >
-              {previewing() ? 'Back to changes' : 'Preview result'}
-            </button>
-          </Show>
-          <button
-            type="button"
-            class="docws-btn docws-btn-sm docws-btn-primary"
-            disabled={!canAccept()}
-            title={
-              props.run.status === 'stale'
-                ? 'The document moved since this run and the proposal no longer applies. Re-run it.'
-                : declined().size === 0
-                  ? 'Accept this candidate as one commit on the canonical branch'
-                  : 'Accept the changes you kept as one commit on the canonical branch'
-            }
-            onClick={() => void accept()}
-          >
-            {accepting()
-              ? 'Accepting…'
-              : declined().size === 0
-                ? 'Accept this candidate'
-                : `Accept ${keptCount()} of ${hunks().length} changes`}
-          </button>
-        </div>
-        <Show when={declined().size > 0 && !composed.loading && composed() === null}>
-          <div class="docws-error" role="alert">
-            These changes cannot be combined cleanly. Adjust your choices or refine the candidate.
-          </div>
-        </Show>
+        <Rationale candidate={props.candidate}>
+          <textarea
+            class="docws-note"
+            placeholder="Your note on this candidate…"
+            value={note()}
+            onInput={(e) => setNote(e.currentTarget.value)}
+            onBlur={() => {
+              if (note() !== (props.candidate.note ?? ''))
+                void setDocumentCandidateNote(props.run.id, props.candidate.id, note());
+            }}
+          />
+        </Rationale>
         <CandidateRefinement run={props.run} candidate={props.candidate} />
       </div>
       <div class="docws-column-body" ref={bodyRef}>
@@ -463,6 +516,9 @@ function CandidateColumn(props: {
                   <DocumentViewer
                     blocks={rendered.blocks()}
                     changes={changes()}
+                    visibleBlock={
+                      props.changesOnly && !rendered.page() ? (i) => visible().has(i) : undefined
+                    }
                     hunkLeads={hunkLeads}
                     onToggleHunk={toggleHunk}
                     declined={(i) => declinedBlocks().has(i)}
@@ -503,15 +559,65 @@ function CandidateColumn(props: {
           </section>
         </Show>
       </div>
+      <div class="docws-column-actions">
+        <div class="docws-run-actions">
+          <Show when={partial() && declined().size > 0}>
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm"
+              aria-pressed={previewing()}
+              onClick={() => setShowPreview((value) => !value)}
+            >
+              {previewing() ? 'Back to changes' : 'Preview result'}
+            </button>
+          </Show>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            disabled={!canAccept()}
+            title={
+              props.run.status === 'stale'
+                ? 'The document moved since this run and the proposal no longer applies. Re-run it.'
+                : declined().size === 0
+                  ? 'Apply this proposal to your document'
+                  : 'Apply the selected changes to your document'
+            }
+            onClick={() => void accept()}
+          >
+            {accepting()
+              ? 'Applying…'
+              : declined().size === 0
+                ? 'Apply proposal'
+                : `Apply ${keptCount()} of ${hunks().length} changes`}
+          </button>
+        </div>
+        <Show when={declined().size > 0 && !composed.loading && composed() === null}>
+          <div class="docws-error" role="alert">
+            These changes cannot be combined cleanly. Adjust your choices or refine the candidate.
+          </div>
+        </Show>
+      </div>
     </section>
   );
 }
 
 /** Base on the left, candidates to the right, each opening with its rationale. */
-export function CompareView(props: { run: DocumentRunRecord }) {
+export function CompareView(props: { run: DocumentRunRecord; candidateId?: string }) {
+  const id = createUniqueId();
+  const [showAll, setShowAll] = createSignal(false);
+  const [selectedId, setSelectedId] = createSignal<string>();
+  createEffect(
+    on(
+      () => props.candidateId,
+      (value) => setSelectedId(value),
+    ),
+  );
   let baseBodyRef: HTMLDivElement | undefined;
+  let mergeButton: HTMLButtonElement | undefined;
   const [revealAgents, setRevealAgents] = createSignal(false);
   const [showSource, setShowSource] = createSignal(false);
+  const [changesOnly, setChangesOnly] = createSignal(false);
+  const [merging, setMerging] = createSignal(false);
   const [baseContent] = createResource(
     () => ({ sha: props.run.baseSha, path: props.run.documentPath }),
     ({ sha, path }) => fetchDocumentAt(sha, path),
@@ -519,8 +625,34 @@ export function CompareView(props: { run: DocumentRunRecord }) {
   const base = createRenderedBlocks(() => baseContent() ?? null);
   const scope = createMemo(() => scopeRange(base.blocks(), props.run));
   const candidates = createMemo(() => props.run.candidates.filter((c) => c.commitSha));
+  const selected = createMemo(
+    () => candidates().find((c) => c.id === selectedId()) ?? candidates()[0],
+  );
+  function navigateProposal(e: KeyboardEvent, index: number) {
+    let next: number;
+    if (e.key === 'ArrowRight') next = (index + 1) % candidates().length;
+    else if (e.key === 'ArrowLeft') next = (index - 1 + candidates().length) % candidates().length;
+    else if (e.key === 'Home') next = 0;
+    else if (e.key === 'End') next = candidates().length - 1;
+    else return;
+    e.preventDefault();
+    setSelectedId(candidates()[next].id);
+    document.getElementById(`${id}-tab-${next}`)?.focus();
+  }
+  const canMerge = () =>
+    (props.run.status === 'finished' || props.run.status === 'stale') &&
+    candidates().filter((c) => c.status === 'done').length >= 2;
   // Base blocks touched by any candidate, so a deleted paragraph is visible somewhere.
   const [baseChanges, setBaseChanges] = createSignal<Record<string, BlockChange[]>>({});
+  const [baseHunks, setBaseHunks] = createSignal<Record<string, BlockHunk[]>>({});
+  const baseVisible = createMemo(() =>
+    reviewBlocks(
+      showAll() ? Object.values(baseHunks()).flat() : (baseHunks()[selected()?.id ?? ''] ?? []),
+      'base',
+      base.blocks().length,
+    ),
+  );
+  const filtering = () => changesOnly() && !base.page() && !showSource();
   // The width under the pointer while a seam is dragged. It is kept out of the
   // store on purpose: panel sizes are part of the persisted snapshot, so
   // writing one per mouse event would serialise the whole app state per frame.
@@ -528,6 +660,7 @@ export function CompareView(props: { run: DocumentRunRecord }) {
 
   /** A column the reader sized keeps that width over the layout's. */
   function columnStyle(column: string): JSX.CSSProperties | undefined {
+    if (!showAll()) return undefined;
     const live = drag();
     const width = live?.column === column ? live.width : getPanelUserSize(columnKey(column));
     if (!width) return undefined;
@@ -548,7 +681,9 @@ export function CompareView(props: { run: DocumentRunRecord }) {
     />
   );
   const baseMarks = createMemo<BlockChange[]>(() => {
-    const perCandidate = Object.values(baseChanges());
+    const perCandidate = showAll()
+      ? Object.values(baseChanges())
+      : [baseChanges()[selected()?.id ?? ''] ?? []];
     return base.blocks().map((_, i) => {
       const marks = perCandidate.map((m) => m[i]).filter((m): m is BlockChange => !!m);
       if (marks.includes('removed')) return 'removed';
@@ -556,12 +691,21 @@ export function CompareView(props: { run: DocumentRunRecord }) {
       return 'same';
     });
   });
-  // The base opens on the passage the run was scoped to, level with the candidates.
+  // The base opens on the passage the run was scoped to, level with the
+  // candidates. A whole-document run has no scope, so its base waits for the
+  // first candidate to report the blocks it touched — and then holds still,
+  // rather than jumping each time the reader switches proposals.
+  let baseRevealed = false;
   createEffect(
-    on([scope, () => base.blocks().length], () => {
-      requestAnimationFrame(() =>
-        revealFirst(baseBodyRef, '.doc-block.is-scope, .doc-block:not([data-change="same"])'),
-      );
+    on([scope, () => base.blocks().length, baseMarks], () => {
+      if (baseRevealed) return;
+      const frame = requestAnimationFrame(() => {
+        baseRevealed = revealFirst(
+          baseBodyRef,
+          '.doc-block.is-scope, .doc-block:not([data-change="same"])',
+        );
+      });
+      onCleanup(() => cancelAnimationFrame(frame));
     }),
   );
   const scopeText = () => {
@@ -598,26 +742,92 @@ export function CompareView(props: { run: DocumentRunRecord }) {
           />
           Source diff
         </label>
-        <button
-          type="button"
-          class="docws-btn docws-btn-sm docws-btn-danger"
-          onClick={() => void rejectDocumentRun(props.run.id)}
+        <label
+          class="docws-toggle"
+          title={
+            base.page() || showSource()
+              ? 'Available for rendered Markdown'
+              : 'Hide unchanged passages'
+          }
         >
-          Reject all
-        </button>
+          <input
+            type="checkbox"
+            aria-label="Changes only"
+            checked={filtering()}
+            disabled={!!base.page() || showSource()}
+            onChange={(e) => setChangesOnly(e.currentTarget.checked)}
+          />
+          Changes only
+        </label>
+        <Show when={canMerge()}>
+          <button
+            ref={mergeButton}
+            type="button"
+            class="docws-btn docws-btn-sm"
+            aria-expanded={merging()}
+            title="Let an agent read the proposals and draft one merged version"
+            onClick={() => setMerging((value) => !value)}
+          >
+            Merge with agent
+          </button>
+        </Show>
+        <RejectRunButton run={props.run} label="Reject all" />
       </div>
-      <div class="docws-columns">
+      <Show when={merging() && canMerge()}>
+        <MergeWithAgent
+          run={props.run}
+          revealAgents={revealAgents()}
+          onClose={() => {
+            setMerging(false);
+            mergeButton?.focus();
+          }}
+        />
+      </Show>
+      <Show when={candidates().length > 1}>
+        <div class="docws-proposal-switcher">
+          <Show when={!showAll()}>
+            <div class="docws-tabs" role="tablist" aria-label="Proposals">
+              <Index each={candidates()}>
+                {(candidate, i) => (
+                  <button
+                    type="button"
+                    class="docws-tab"
+                    role="tab"
+                    id={`${id}-tab-${i}`}
+                    aria-controls={`${id}-panel-${i}`}
+                    aria-selected={selected()?.id === candidate().id}
+                    tabIndex={selected()?.id === candidate().id ? 0 : -1}
+                    onClick={() => setSelectedId(candidate().id)}
+                    onKeyDown={(e) => navigateProposal(e, i)}
+                  >
+                    Proposal {candidate().label}
+                  </button>
+                )}
+              </Index>
+            </div>
+          </Show>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            aria-pressed={showAll()}
+            onClick={() => setShowAll((value) => !value)}
+          >
+            {showAll() ? 'Show one proposal' : 'Show all proposals'}
+          </button>
+        </div>
+      </Show>
+      <div class="docws-columns" classList={{ 'is-focused': !showAll() }}>
         <section
           class="docws-column docws-column-base"
           style={columnStyle('base')}
           aria-label="Base version"
         >
           <div class="docws-column-head">
-            <div class="docws-column-title">Base · {props.run.baseSha.slice(0, 7)}</div>
+            <div class="docws-column-title">Original</div>
             <div class="docws-rationale">
               <div>
                 The document as every candidate saw it. The scoped passage is outlined; blocks a
-                candidate rewrote or removed are marked.
+                proposal rewrote or removed are marked.
               </div>
             </div>
           </div>
@@ -626,27 +836,36 @@ export function CompareView(props: { run: DocumentRunRecord }) {
               blocks={base.blocks()}
               scope={scope()}
               changes={baseMarks()}
+              visibleBlock={filtering() ? (i) => baseVisible().has(i) : undefined}
               renderKey="base"
               page={base.page()}
             />
           </div>
         </section>
-        {seam('base')}
+        <Show when={showAll()}>{seam('base')}</Show>
         <Index each={candidates()}>
           {(candidate, i) => (
             <>
               <CandidateColumn
                 run={props.run}
                 candidate={candidate()}
+                hidden={!showAll() && selected()?.id !== candidate().id}
+                panelId={`${id}-panel-${i}`}
+                tabId={!showAll() && candidates().length > 1 ? `${id}-tab-${i}` : undefined}
                 baseBlocks={base.blocks()}
                 baseSource={baseContent() ?? ''}
                 partialCapable={!base.page()}
                 revealAgents={revealAgents()}
                 showSource={showSource()}
-                onBaseChanges={(id, marks) => setBaseChanges((prev) => ({ ...prev, [id]: marks }))}
+                changesOnly={filtering()}
+                baseBody={() => baseBodyRef}
+                onBaseChanges={(id, marks, hunks) => {
+                  setBaseChanges((prev) => ({ ...prev, [id]: marks }));
+                  setBaseHunks((prev) => ({ ...prev, [id]: hunks }));
+                }}
                 style={columnStyle(`candidate-${i}`)}
               />
-              {seam(`candidate-${i}`)}
+              <Show when={showAll()}>{seam(`candidate-${i}`)}</Show>
             </>
           )}
         </Index>
diff --git a/src/documents/DocumentViewer.toolbar.client.test.tsx b/src/documents/DocumentViewer.toolbar.client.test.tsx
new file mode 100644
index 000000000..4588b5d7e
--- /dev/null
+++ b/src/documents/DocumentViewer.toolbar.client.test.tsx
@@ -0,0 +1,51 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DocumentViewer } from './DocumentViewer';
+import type { DocumentBlock } from './markdown-blocks';
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+});
+
+const blocks: DocumentBlock[] = [
+  {
+    index: 0,
+    type: 'paragraph',
+    raw: 'Body text.\n',
+    html: '<p>Body text.</p>',
+    startLine: 1,
+    endLine: 1,
+  },
+];
+
+describe('the floating block toolbar and the viewer\u2019s hover tracking', () => {
+  it('stays open while the pointer moves between its own buttons', async () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(
+        () => <DocumentViewer blocks={blocks} renderKey="t" selectable onAction={() => {}} />,
+        host,
+      ),
+    );
+    host
+      .querySelector('[data-block-index="0"] p')
+      ?.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+    const toolbar = document.querySelector<HTMLElement>('.docws-block-actions');
+    expect(toolbar?.classList.contains('is-open')).toBe(true);
+
+    // Solid routes the portalled toolbar's delegated events back through the
+    // viewer; a move onto one of its buttons must not read as leaving the block.
+    host.querySelector('.docws-content')?.dispatchEvent(new MouseEvent('mouseleave'));
+    toolbar?.dispatchEvent(new MouseEvent('mouseenter'));
+    toolbar
+      ?.querySelectorAll('.docws-block-action')[1]
+      ?.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+
+    expect(toolbar?.classList.contains('is-open')).toBe(true);
+  });
+});
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
index 18457d76c..931248b7a 100644
--- a/src/documents/DocumentViewer.tsx
+++ b/src/documents/DocumentViewer.tsx
@@ -9,6 +9,10 @@ import { findAnchorTarget, resolveDocumentLink } from './links';
 import { BlockActions, type BlockActionKind } from './BlockActions';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
+import { createHeldSignal } from '../lib/floating';
+
+/** How long the hover toolbar waits for the pointer to reach it from the block. */
+const TOOLBAR_HOLD_MS = 100;
 
 export interface BlockRange {
   start: number;
@@ -23,6 +27,8 @@ interface DocumentViewerProps {
   onSelect?: (selection: DocumentSelection | null) => void;
   /** Per-block change marks for the compare view. */
   changes?: BlockChange[];
+  /** Review-only filter; indices stay tied to the complete document. */
+  visibleBlock?: (index: number) => boolean;
   /** Blocks inside the run's scope (compare view context). */
   scope?: BlockRange | null;
   /**
@@ -71,8 +77,12 @@ export function selectionFromRange(
   };
 }
 
-/** The document's own controls: a click on one is never a click on the prose. */
-const CONTROLS = 'a, button, input, textarea, .docws-marker';
+/**
+ * The document's own controls: a click on one is never a click on the prose.
+ * An open note is one of them even though it floats over the window: reading
+ * or editing it must not let go of the passage being worked on.
+ */
+const CONTROLS = 'a, button, input, textarea, .docws-marker, .docws-marker-pop, .docws-bubble';
 
 /**
  * True for a mouse-up on the backdrop: the margins and the space below the
@@ -106,6 +116,25 @@ export function DocumentViewer(props: DocumentViewerProps) {
     return { start: Math.min(s.start, s.end), end: Math.max(s.start, s.end) };
   });
 
+  // The block under the pointer, held for a beat so the pointer can climb
+  // onto the toolbar above it. Picked blocks have the composer up on them;
+  // their toolbar would only repeat what it offers.
+  const hovered = createHeldSignal<number>(TOOLBAR_HOLD_MS);
+  const toolbarBlock = (): HTMLElement | null => {
+    const index = hovered.value();
+    const s = selected();
+    if (index === null || (s && index >= s.start && index <= s.end)) return null;
+    return containerRef?.querySelector<HTMLElement>(`[data-block-index="${index}"]`) ?? null;
+  };
+  function trackHover(e: MouseEvent) {
+    // Solid delivers delegated events from the portalled toolbar and popover
+    // here too; they are in the body, not the document, and not a block.
+    if (!containerRef?.contains(e.target as Node)) return;
+    const index = blockIndexOf(e.target as Node, containerRef);
+    if (index === null) hovered.clear();
+    else hovered.set(index);
+  }
+
   const isPage = () => !!props.page;
   const pageKey = () => props.renderKey.replace(/["\\]/g, '');
   // Every viewer scopes the page's CSS to itself, so two versions of a page
@@ -205,7 +234,20 @@ export function DocumentViewer(props: DocumentViewerProps) {
       }}
       onMouseUp={handleMouseUp}
       onClick={handleClick}
+      onMouseOver={trackHover}
+      onMouseLeave={() => hovered.clear()}
     >
+      <Show when={props.selectable && props.onAction}>
+        <BlockActions
+          anchor={toolbarBlock}
+          alignLeft={isPage()}
+          onAction={(kind) => {
+            const index = hovered.value();
+            if (index !== null) props.onAction?.(kind, index);
+          }}
+          onPointer={(inside) => (inside ? hovered.hold() : hovered.clear())}
+        />
+      </Show>
       <Show when={props.page}>
         {(page) => (
           <>
@@ -221,7 +263,6 @@ export function DocumentViewer(props: DocumentViewerProps) {
               blockMarker={props.blockMarker}
               hasMarker={props.hasMarker}
               onSelectSection={selectSection}
-              onAction={props.onAction}
             />
           </>
         )}
@@ -242,6 +283,7 @@ export function DocumentViewer(props: DocumentViewerProps) {
               <div
                 class="doc-block"
                 data-block-index={i()}
+                hidden={props.visibleBlock?.(i()) === false}
                 data-change={change()}
                 classList={{
                   'is-declined': props.declined?.(i()) === true,
@@ -283,9 +325,6 @@ export function DocumentViewer(props: DocumentViewerProps) {
                   it is not part of the passage, so clicking it must not toggle
                   the selection and the highlight stops at the text. */}
                 {props.blockMarker?.(i())}
-                <Show when={props.selectable && props.onAction}>
-                  <BlockActions onAction={(kind) => props.onAction?.(kind, i())} />
-                </Show>
                 {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
                 <div innerHTML={block.html} />
               </div>
diff --git a/src/documents/DocumentWorkspaceOverlay.client.test.tsx b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
index eefe52b58..ee4bd9d2f 100644
--- a/src/documents/DocumentWorkspaceOverlay.client.test.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
@@ -1,20 +1,21 @@
 import { render } from 'solid-js/web';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { setStore } from '../store/core';
+import { setStore, store } from '../store/core';
 import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+import { documentStore, setDocumentComposerDraft } from './store';
 
-const { openInEditor, platform } = vi.hoisted(() => ({
+const { openInEditor, revealItemInDir, platform } = vi.hoisted(() => ({
   openInEditor: vi.fn(() => Promise.resolve()),
+  revealItemInDir: vi.fn(() => Promise.resolve()),
   platform: { isMac: false },
 }));
 
-vi.mock('../lib/shell', () => ({ openInEditor }));
+vi.mock('../lib/shell', () => ({ openInEditor, revealItemInDir }));
 vi.mock('../lib/platform', () => ({
   get isMac() {
     return platform.isMac;
   },
-  isLinux: false,
-  windowChromeTopInset: 0,
+  windowChromeTopInset: 34,
   mod: 'Ctrl',
   alt: 'Alt',
 }));
@@ -24,10 +25,42 @@ const disposers: Array<() => void> = [];
 afterEach(() => {
   while (disposers.length > 0) disposers.pop()?.();
   document.body.replaceChildren();
-  setStore({ projects: [], activeDocumentProjectId: null, editorCommand: '' });
+  setStore({
+    projects: [],
+    activeDocumentProjectId: null,
+    editorCommand: '',
+    documentFullWidth: false,
+  });
+  setDocumentComposerDraft(null);
   vi.clearAllMocks();
 });
 
+function openWorkspace(): HTMLElement {
+  setStore({
+    projects: [
+      {
+        id: 'docs',
+        name: 'Release notes',
+        path: '/projects/release',
+        color: '',
+        kind: 'document',
+        documentPath: 'notes.md',
+      },
+    ],
+    activeDocumentProjectId: 'docs',
+  });
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+  return host;
+}
+
+function button(host: HTMLElement, label: string): HTMLButtonElement | null {
+  return (
+    Array.from(host.querySelectorAll('button')).find((b) => b.textContent?.trim() === label) ?? null
+  );
+}
+
 describe('DocumentWorkspaceOverlay', () => {
   it('uses the entire title-bar background as the window drag region', () => {
     setStore({
@@ -75,6 +108,50 @@ describe('DocumentWorkspaceOverlay', () => {
     platform.isMac = false;
   });
 
+  it('starts below the custom title bar so its window controls stay clickable', () => {
+    const host = openWorkspace();
+    expect(host.querySelector<HTMLElement>('.docws-overlay')?.style.top).toBe('34px');
+  });
+
+  it('lays the overlay over the whole window on mac, where the title bar is the content', () => {
+    platform.isMac = true;
+    const host = openWorkspace();
+    expect(host.querySelector<HTMLElement>('.docws-overlay')?.style.top).toBe('');
+    platform.isMac = false;
+  });
+
+  it('opens the project folder in the file manager from the title', () => {
+    const host = openWorkspace();
+    const open = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Open the folder /projects/release in the file manager"]',
+    );
+    open?.click();
+    expect(revealItemInDir).toHaveBeenCalledWith('/projects/release');
+  });
+
+  it('keeps the composer away until there is something to compose', () => {
+    const host = openWorkspace();
+    expect(host.querySelector('.docws-composer')).toBeNull();
+
+    button(host, 'Revise document')?.click();
+
+    expect(documentStore.composerDraft).toEqual({ text: '', mode: 'proposals' });
+    expect(button(host, 'Revise document')).toBeNull();
+  });
+
+  it('lets the document take the full width of the pane', () => {
+    const host = openWorkspace();
+    const toggle = button(host, 'Full width');
+    expect(toggle?.getAttribute('aria-pressed')).toBe('false');
+    expect(host.querySelector('.docws-doc')?.classList.contains('is-full-width')).toBe(false);
+
+    toggle?.click();
+
+    expect(store.documentFullWidth).toBe(true);
+    expect(toggle?.getAttribute('aria-pressed')).toBe('true');
+    expect(host.querySelector('.docws-doc')?.classList.contains('is-full-width')).toBe(true);
+  });
+
   it('keeps the project files on a tab of the resizable right panel', () => {
     setStore({
       projects: [
diff --git a/src/documents/DocumentWorkspaceOverlay.close.client.test.tsx b/src/documents/DocumentWorkspaceOverlay.close.client.test.tsx
new file mode 100644
index 000000000..d912cbadf
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.close.client.test.tsx
@@ -0,0 +1,116 @@
+import { render } from 'solid-js/web';
+import { Show, onCleanup, onMount } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore, store } from '../store/core';
+import { addAgentToTask } from '../store/agents';
+import { clearAgentActivity } from '../store/taskStatus';
+import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+import { closeDocumentWorkspace, documentStore } from './store';
+import { documentAgentTaskId, ensureDocumentAgentTask } from './agent-task';
+import type { AgentDef } from '../ipc/types';
+import type { Project } from '../store/types';
+
+// The real terminal registers callbacks and hands them back from its cleanup,
+// the way the terminal pane reads the task while the tree comes down.
+vi.mock('../components/TerminalView', () => ({
+  TerminalView: (props: {
+    onStepNavReady?: (api: unknown) => void;
+    onReady?: (fn: () => void) => void;
+  }) => {
+    onMount(() => {
+      props.onReady?.(() => {});
+      props.onStepNavReady?.({ mark: () => {}, jump: () => false });
+    });
+    onCleanup(() => props.onStepNavReady?.(undefined));
+    return <div class="terminal-stub" />;
+  },
+}));
+vi.mock('../lib/ipc', () => ({
+  invoke: vi.fn(() => Promise.resolve([])),
+  Channel: class {
+    dispose() {}
+  },
+}));
+vi.mock('../lib/shell', () => ({ openInEditor: vi.fn(), revealItemInDir: vi.fn() }));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  for (const id of Object.keys(store.agents)) clearAgentActivity(id);
+  setStore({
+    projects: [],
+    availableAgents: [],
+    tasks: {},
+    agents: {},
+    taskOrder: [],
+    activeTaskId: null,
+    activeAgentId: null,
+    activeDocumentProjectId: null,
+  });
+});
+
+const codex: AgentDef = {
+  id: 'codex',
+  name: 'Codex',
+  command: 'codex',
+  args: [],
+  resume_args: [],
+  skip_permissions_args: [],
+  description: '',
+};
+
+const project: Project = {
+  id: 'docs',
+  name: 'Docs',
+  path: '/projects/docs',
+  color: '',
+  kind: 'document',
+  documentPath: 'notes.md',
+  documentTerminalAgentId: 'codex',
+};
+
+/** Mounted the way the app does it: the overlay lives inside a Show on the store. */
+async function open(): Promise<HTMLElement> {
+  setStore({ availableAgents: [codex], projects: [project], activeDocumentProjectId: 'docs' });
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(
+    render(
+      () => (
+        <Show when={store.activeDocumentProjectId}>
+          <DocumentWorkspaceOverlay />
+        </Show>
+      ),
+      host,
+    ),
+  );
+  await Promise.resolve();
+  expect(host.querySelector('.terminal-stub')).not.toBeNull();
+  expect(store.activeTaskId).toBe(documentAgentTaskId('docs'));
+  return host;
+}
+
+describe('closing the workspace with the agent tab up', () => {
+  it('takes the terminal down cleanly', async () => {
+    const host = await open();
+
+    expect(() => closeDocumentWorkspace()).not.toThrow();
+
+    expect(host.querySelector('.terminal-stub')).toBeNull();
+    expect(documentStore.projectId).toBeNull();
+    expect(store.activeTaskId).toBeNull();
+  });
+
+  it('takes two terminals down cleanly', async () => {
+    const host = await open();
+    const task = ensureDocumentAgentTask(project);
+    await addAgentToTask(task?.id ?? '', codex);
+    expect(host.querySelectorAll('.terminal-stub').length).toBe(2);
+
+    expect(() => closeDocumentWorkspace()).not.toThrow();
+
+    expect(host.querySelector('.terminal-stub')).toBeNull();
+  });
+});
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index fa154703e..77c4d89bc 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -15,9 +15,12 @@ import { getProject } from '../store/projects';
 import {
   activeDocumentPath,
   closeDocumentWorkspace,
+  discardDocumentEdits,
   dismissUndo,
   documentStore,
+  goBackDocument,
   openDocumentFile,
+  previousDocumentPath,
   refreshDocumentSnapshot,
   reviewableRuns,
   setDocumentComposerDraft,
@@ -29,8 +32,9 @@ import {
   type DocumentView,
 } from './store';
 import { resetWorkspaceUi } from './workspace-ui';
+import { activateDocumentAgentTask, releaseDocumentAgentTask } from './agent-task';
 import { findAnchorTarget } from './links';
-import { isMac } from '../lib/platform';
+import { isMac, windowChromeTopInset } from '../lib/platform';
 import { relocateAnchor } from './annotation-anchor';
 import { isHtmlDocument } from './html-document';
 import type { DocumentAnnotation } from './types';
@@ -49,7 +53,10 @@ import { BlockEditor, type BlockEditTarget } from './BlockEditor';
 import { ResizablePanel, type PanelChild } from '../components/ResizablePanel';
 import { createRenderedBlocks } from './use-blocks';
 import { DocumentIcon } from './DocumentIcon';
-import { openInEditor } from '../lib/shell';
+import { ActionIcon } from './BlockActions';
+import { ConfirmDialog } from '../components/ConfirmDialog';
+import { openInEditor, revealItemInDir } from '../lib/shell';
+import { setDocumentFullWidth } from '../store/ui';
 import { errMessage } from '../lib/log';
 import { showNotification } from '../store/notification';
 
@@ -61,6 +68,7 @@ function DocumentPane(props: { project: Project }) {
   let mainRef: HTMLDivElement | undefined;
   let scrollRef: HTMLDivElement | undefined;
   let layerRef: HTMLDivElement | undefined;
+  let reviseRef: HTMLButtonElement | undefined;
   // Where the composer sits when a passage is picked; null puts it at the foot.
   const [anchorTop, setAnchorTop] = createSignal<number | null>(null);
   const blocks = createRenderedBlocks(() => documentStore.snapshot?.content ?? null);
@@ -77,6 +85,9 @@ function DocumentPane(props: { project: Project }) {
     const s = selection();
     return s && !s.wholeDocument ? { start: s.startBlock, end: s.endBlock } : null;
   });
+  // The composer is up while there is something for it to do: a picked
+  // passage, or a task asked for on the whole document.
+  const composerOpen = () => !!selection() || !!documentStore.composerDraft;
 
   /** Open the source editor on a block; only blocks that map back to the source qualify. */
   function editBlock(block: DocumentBlock | null) {
@@ -202,12 +213,13 @@ function DocumentPane(props: { project: Project }) {
     }),
   );
 
-  // The composer follows the passage as the prose scrolls and as its own
-  // height changes with the mode and the agents picked. The layer is created
-  // with the first snapshot, well after this mounts, so it is observed from
-  // its own ref rather than here.
-  const layerResize = new ResizeObserver(() => placeComposer());
-  onCleanup(() => layerResize.disconnect());
+  // The composer follows the passage as the prose scrolls, as its own height
+  // changes with the mode and the agents picked, and as the prose reflows
+  // under it (a theme or width change moves the passage without a scroll).
+  // The layer is created with the first snapshot, well after this mounts, so
+  // both are observed from their own refs rather than here.
+  const reflow = new ResizeObserver(() => placeComposer());
+  onCleanup(() => reflow.disconnect());
   onMount(() => {
     scrollRef?.addEventListener('scroll', placeComposer, { passive: true });
     window.addEventListener('resize', placeComposer);
@@ -228,7 +240,7 @@ function DocumentPane(props: { project: Project }) {
     if (showsPreview()) return 'Sandboxed render of the page — switch to Inline to scope a task';
     const s = selection();
     if (!s || s.wholeDocument)
-      return 'Tasks act on the whole document; click a block, drag across blocks, or use § on a heading to narrow them';
+      return 'Click a block, drag across blocks, or use § on a heading to work on a passage';
     return s.startLine === s.endLine
       ? `Selected line ${s.startLine}`
       : `Selected lines ${s.startLine}–${s.endLine}`;
@@ -259,7 +271,19 @@ function DocumentPane(props: { project: Project }) {
             </button>
           </span>
         </Show>
-        <span>{toolbarLabel()}</span>
+        <Show when={!showsPreview() && !composerOpen()}>
+          <button
+            type="button"
+            ref={reviseRef}
+            class="docws-btn docws-btn-sm docws-toolbar-task"
+            title="Open the composer on the whole document"
+            onClick={() => setDocumentComposerDraft({ text: '', mode: 'proposals' })}
+          >
+            <ActionIcon kind="proposals" />
+            Revise document
+          </button>
+        </Show>
+        <span class="docws-toolbar-label">{toolbarLabel()}</span>
         <Show when={editableBlock() && !showsPreview()}>
           <button
             type="button"
@@ -282,6 +306,21 @@ function DocumentPane(props: { project: Project }) {
           </span>
         </Show>
         <span style={{ 'margin-left': 'auto' }} />
+        <Show when={!showsPreview()}>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            aria-pressed={store.documentFullWidth}
+            title={
+              store.documentFullWidth
+                ? 'Back to a reading width'
+                : 'Let the document take the whole column'
+            }
+            onClick={() => setDocumentFullWidth(!store.documentFullWidth)}
+          >
+            Full width
+          </button>
+        </Show>
         <Show when={resolvedCount() > 0}>
           <label class="docws-toggle" title="Resolved bubbles collapse to one line">
             <input
@@ -316,7 +355,14 @@ function DocumentPane(props: { project: Project }) {
           if (releasesSelection(e.target)) setDocumentSelection(null);
         }}
       >
-        <div class="docws-doc" ref={docRef} classList={{ 'is-page': isHtml() }}>
+        <div
+          class="docws-doc"
+          ref={(el) => {
+            docRef = el;
+            reflow.observe(el);
+          }}
+          classList={{ 'is-page': isHtml(), 'is-full-width': store.documentFullWidth }}
+        >
           <Show when={placed().detached.length > 0}>
             <div class="docws-detached-section">
               <div class="docws-rail-title">Detached notes</div>
@@ -374,14 +420,18 @@ function DocumentPane(props: { project: Project }) {
       </div>
       {/* The composer floats over the prose instead of opening inside it, so
           the passage it is about stays where it was picked: right above the
-          popover. It is always there; with nothing picked it rests at the foot
-          of the column and takes the whole document. */}
-      <Show when={documentStore.snapshot && !documentStore.snapshot.missing}>
+          popover. It is only up while it has work to do: a task on the whole
+          document rests at the foot of the column. */}
+      <Show when={documentStore.snapshot && !documentStore.snapshot.missing && composerOpen()}>
         <div
           class="docws-composer-layer"
           ref={(el) => {
             layerRef = el;
-            layerResize.observe(el);
+            reflow.observe(el);
+            onCleanup(() => {
+              reflow.unobserve(el);
+              if (layerRef === el) layerRef = undefined;
+            });
           }}
           classList={{ 'is-hidden': showsPreview(), 'is-anchored': anchorTop() !== null }}
           style={anchorTop() !== null ? { top: `${anchorTop()}px`, bottom: 'auto' } : undefined}
@@ -392,6 +442,9 @@ function DocumentPane(props: { project: Project }) {
             onClose={() => {
               setDocumentSelection(null);
               setDocumentComposerDraft(null);
+              // The composer takes the focused textarea with it; the toolbar
+              // button that reopens it is the nearest place for focus to land.
+              requestAnimationFrame(() => reviseRef?.focus({ preventScroll: true }));
             }}
           />
         </div>
@@ -418,6 +471,8 @@ export function DocumentWorkspaceOverlay() {
     store.activeDocumentProjectId ? getProject(store.activeDocumentProjectId) : undefined,
   );
   const [editing, setEditing] = createSignal<Project | null>(null);
+  const [confirmDiscard, setConfirmDiscard] = createSignal(false);
+  const [discarding, setDiscarding] = createSignal(false);
   const snapshot = () => documentStore.snapshot;
   const reviewable = createMemo(() => reviewableRuns());
   const editorCommand = () => store.editorCommand.trim();
@@ -442,8 +497,23 @@ export function DocumentWorkspaceOverlay() {
     ),
   );
 
+  // The agent runs in a task of its own. It is the active task while the
+  // workspace is up, so its terminal and prompt box take focus; the task that
+  // was active before gets focus back on close. Created once the installed
+  // agents are known, which may be after the workspace opened.
+  const previousActiveTask = store.activeTaskId;
+  createEffect(
+    on(
+      () => [project(), store.availableAgents] as const,
+      ([p]) => {
+        if (p) activateDocumentAgentTask(p);
+      },
+    ),
+  );
+
   onCleanup(() => {
     if (documentStore.projectId) closeDocumentWorkspace();
+    releaseDocumentAgentTask(previousActiveTask);
   });
 
   function openDocumentInEditor() {
@@ -457,6 +527,15 @@ export function DocumentWorkspaceOverlay() {
     );
   }
 
+  /** The project folder in the system file manager. */
+  function openProjectFolder() {
+    const currentProject = project();
+    if (!currentProject) return;
+    revealItemInDir(currentProject.path).catch((err) =>
+      showNotification(`Could not open folder: ${errMessage(err)}`),
+    );
+  }
+
   function tab(view: DocumentView, label: string) {
     return (
       <button
@@ -496,7 +575,13 @@ export function DocumentWorkspaceOverlay() {
       id: 'rail',
       minSize: 300,
       defaultSize: 420,
-      content: () => <Show when={project()}>{(p) => <RightPanel project={p()} />}</Show>,
+      // Keyed: the panel's children read the project from cleanups, which
+      // must not go through an accessor while the workspace is closing.
+      content: () => (
+        <Show when={project()} keyed>
+          {(p) => <RightPanel project={p} />}
+        </Show>
+      ),
     },
   ];
 
@@ -504,7 +589,11 @@ export function DocumentWorkspaceOverlay() {
     <div
       class="docws-overlay"
       classList={{ 'is-mac': isMac }}
+      // The app's own title bar carries the window controls on every
+      // platform but macOS; the workspace starts below it instead of over it.
+      style={isMac ? undefined : { top: `${windowChromeTopInset}px` }}
       role="dialog"
+      aria-modal="true"
       aria-label="Document workspace"
     >
       <div class="docws-header" data-tauri-drag-region>
@@ -523,7 +612,31 @@ export function DocumentWorkspaceOverlay() {
               <path d="M3.5 2a1.5 1.5 0 0 0-1.5 1.5v9A1.5 1.5 0 0 0 3.5 14h9a1.5 1.5 0 0 0 1.5-1.5v-3a.75.75 0 0 1 1.5 0v3A3 3 0 0 1 12.5 16h-9A3 3 0 0 1 0 12.5v-9A3 3 0 0 1 3.5 0h3a.75.75 0 0 1 0 1.5h-3ZM10 .75a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0V2.56L8.53 8.53a.75.75 0 0 1-1.06-1.06L13.44 1.5H10.75A.75.75 0 0 1 10 .75Z" />
             </svg>
           </button>
+          <button
+            type="button"
+            class="docws-btn docws-open-editor"
+            aria-label={`Open the folder ${project()?.path ?? ''} in the file manager`}
+            title={`Open the folder ${project()?.path ?? ''} in the file manager`}
+            disabled={!project()}
+            onClick={() => openProjectFolder()}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+              <path d="M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75Zm0 1.5H5c.08 0 .15.04.2.1l.9 1.2c.33.44.85.7 1.4.7h6.75a.25.25 0 0 1 .25.25v8.5a.25.25 0 0 1-.25.25H1.75a.25.25 0 0 1-.25-.25V2.75a.25.25 0 0 1 .25-.25Z" />
+            </svg>
+          </button>
         </div>
+        <Show when={previousDocumentPath()}>
+          {(previous) => (
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm"
+              title={`Back to ${previous()}`}
+              onClick={() => void goBackDocument()}
+            >
+              ← Back
+            </button>
+          )}
+        </Show>
         <span class="docws-subtitle" title={openPath()}>
           {openPath()}
         </span>
@@ -534,12 +647,14 @@ export function DocumentWorkspaceOverlay() {
           {snapshot()?.branch ?? 'detached'} · {snapshot()?.headSha?.slice(0, 7) ?? 'no commits'}
         </span>
         <Show when={snapshot()?.dirty}>
-          <span
-            class="docws-head-chip is-warning"
-            title="Committed as “Manual edits” before the next run"
+          <button
+            type="button"
+            class="docws-head-chip is-warning is-action"
+            title="Committed as “Manual edits” before the next run · click to discard them"
+            onClick={() => setConfirmDiscard(true)}
           >
             uncommitted edits
-          </span>
+          </button>
         </Show>
         <Show when={documentStore.loading}>
           <span class="docws-head-chip">loading…</span>
@@ -584,6 +699,23 @@ export function DocumentWorkspaceOverlay() {
         />
       </div>
       <EditProjectDialog project={editing()} onClose={() => setEditing(null)} />
+      <ConfirmDialog
+        open={confirmDiscard()}
+        title="Discard uncommitted edits?"
+        message="Every uncommitted change to tracked files in this project goes back to the last commit. This cannot be undone."
+        confirmLabel="Discard edits"
+        confirmLoading={discarding()}
+        confirmDisabled={discarding()}
+        danger
+        onConfirm={() => {
+          setDiscarding(true);
+          void discardDocumentEdits().finally(() => {
+            setDiscarding(false);
+            setConfirmDiscard(false);
+          });
+        }}
+        onCancel={() => setConfirmDiscard(false)}
+      />
       <CandidateOutputDialog />
       <CompareDialog />
     </div>
diff --git a/src/documents/FileTreePanel.tsx b/src/documents/FileTreePanel.tsx
index 675be9064..de35ef1ef 100644
--- a/src/documents/FileTreePanel.tsx
+++ b/src/documents/FileTreePanel.tsx
@@ -5,6 +5,8 @@ import { buildPathTree, type PathTreeNode } from './path-tree';
 import { DocumentIcon } from './DocumentIcon';
 
 const DOCUMENT_RE = /\.(md|markdown|html?)$/i;
+/** Mirrors MAX_FILES in electron/documents/files.ts: a list this long was cut. */
+const FILE_CAP = 5_000;
 
 interface FileTreePanelProps {
   projectRoot: string;
@@ -32,13 +34,15 @@ function Chevron(props: { open: boolean }) {
  */
 export function FileTreePanel(props: FileTreePanelProps) {
   const [collapsed, setCollapsed] = createSignal<Set<string>>(new Set());
+  // Until the first list arrives an empty tree means nothing yet, not "no files".
+  const [listed, setListed] = createSignal(false);
   const tree = createMemo(() => buildPathTree(workspaceUi.files));
 
   // Commits and external edits add files; re-list on every new head and on open.
   createEffect(
     on(
       () => [props.projectRoot, documentStore.snapshot?.headSha] as const,
-      ([root]) => void loadDocumentFiles(root),
+      ([root]) => void loadDocumentFiles(root).then(() => setListed(true)),
     ),
   );
 
@@ -110,11 +114,16 @@ export function FileTreePanel(props: FileTreePanelProps) {
       </Show>
       <div class="docws-tree" role="tree">
         <For each={tree()}>{(node) => <Node node={node} depth={0} />}</For>
-        <Show when={tree().length === 0 && !workspaceUi.filesError}>
+        <Show when={listed() && tree().length === 0 && !workspaceUi.filesError}>
           <div class="docws-empty" style={{ padding: '8px 10px' }}>
             No files yet.
           </div>
         </Show>
+        <Show when={workspaceUi.files.length >= FILE_CAP}>
+          <div class="docws-empty" style={{ padding: '8px 10px' }}>
+            Showing the first {FILE_CAP.toLocaleString()} files.
+          </div>
+        </Show>
       </div>
     </div>
   );
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
index c025ca828..5a99a669c 100644
--- a/src/documents/HistoryView.tsx
+++ b/src/documents/HistoryView.tsx
@@ -2,6 +2,7 @@ import { For, Show, createResource, createSignal, onCleanup } from 'solid-js';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
 import { confirm } from '../lib/dialog';
+import { errMessage } from '../lib/log';
 import { formatRelativeAge } from '../lib/relativeAge';
 import { activeDocumentPath, documentStore, revertDocumentCommit } from './store';
 import { getProject } from '../store/projects';
@@ -37,7 +38,8 @@ function EntryDetail(props: {
         : null,
     (args) => invoke<string | null>(IPC.GetDocumentAtCommit, args),
   );
-  const rendered = createRenderedBlocks(() => content() ?? null);
+  // Reading a resource that failed throws; the error line below reports it.
+  const rendered = createRenderedBlocks(() => (content.error ? null : (content() ?? null)));
   const trailerEntries = () => Object.entries(props.entry.trailers);
 
   async function revert() {
@@ -118,15 +120,25 @@ function EntryDetail(props: {
         <Show
           when={mode() === 'diff'}
           fallback={
-            <DocumentViewer
-              blocks={rendered.blocks()}
-              renderKey={`hist-${props.entry.shortSha}`}
-              page={rendered.page()}
-            />
+            <>
+              <Show when={content.error}>
+                <div class="docws-error">{errMessage(content.error)}</div>
+              </Show>
+              <DocumentViewer
+                blocks={rendered.blocks()}
+                renderKey={`hist-${props.entry.shortSha}`}
+                page={rendered.page()}
+              />
+            </>
           }
         >
           <Show when={!diff.loading} fallback={<div class="docws-empty">Loading diff…</div>}>
-            <SourceDiff raw={diff() ?? ''} />
+            <Show
+              when={!diff.error}
+              fallback={<div class="docws-error">{errMessage(diff.error)}</div>}
+            >
+              <SourceDiff raw={diff() ?? ''} />
+            </Show>
           </Show>
         </Show>
       </div>
@@ -157,7 +169,10 @@ export function HistoryView() {
       });
     },
   );
-  const selected = () => entries()?.find((e) => e.sha === selectedSha()) ?? entries()?.[0] ?? null;
+  // Reading a resource that failed throws; the error line in the list reports it.
+  const list = () => (entries.error ? [] : (entries() ?? []));
+  const selected = () => list().find((e) => e.sha === selectedSha()) ?? list()[0] ?? null;
+  const count = () => list().length;
   const [nowMs, setNowMs] = createSignal(Date.now());
   const clock = setInterval(() => setNowMs(Date.now()), 30_000);
   onCleanup(() => clearInterval(clock));
@@ -174,14 +189,21 @@ export function HistoryView() {
             />
             Whole project
           </label>
-          <span style={{ 'margin-left': 'auto' }}>{entries()?.length ?? 0} commits</span>
+          <span style={{ 'margin-left': 'auto' }}>
+            {count()} {count() === 1 ? 'commit' : 'commits'}
+          </span>
         </div>
-        <Show when={entries()?.length === 0}>
+        <Show when={entries.error}>
+          <div class="docws-error" style={{ padding: '12px 14px', 'font-size': '12px' }}>
+            {errMessage(entries.error)}
+          </div>
+        </Show>
+        <Show when={!entries.error && entries()?.length === 0}>
           <div class="docws-empty" style={{ padding: '12px 14px' }}>
             No commits touch this document yet.
           </div>
         </Show>
-        <For each={entries() ?? []}>
+        <For each={list()}>
           {(entry) => (
             <button
               type="button"
diff --git a/src/documents/MergeWithAgent.tsx b/src/documents/MergeWithAgent.tsx
new file mode 100644
index 000000000..6fe95a0ce
--- /dev/null
+++ b/src/documents/MergeWithAgent.tsx
@@ -0,0 +1,159 @@
+import { For, Show, createMemo, createSignal, onCleanup } from 'solid-js';
+import { documentAgentSupport } from '../../electron/documents/shared';
+import { errMessage } from '../lib/log';
+import { store } from '../store/core';
+import { getProject } from '../store/projects';
+import {
+  documentMainAgentId,
+  documentModelChoices,
+  documentStore,
+  mergeDocumentCandidates,
+  modelLabel,
+} from './store';
+import type { DocumentRunRecord } from './types';
+import { registerCompareForm } from './workspace-ui';
+
+const DEFAULT_GUIDANCE =
+  'Combine the strongest parts of each candidate into one version. Keep the document’s voice, ' +
+  'and where candidates conflict prefer the clearer wording over the more complete one.';
+
+/**
+ * Hands the reviewing to an agent: it reads the chosen proposals as diffs
+ * against the base and drafts one merged proposal, which lands in Runs like
+ * any other and is never accepted on its own.
+ */
+export function MergeWithAgent(props: {
+  run: DocumentRunRecord;
+  /** Names the agent behind each proposal; off, the review stays model-blind. */
+  revealAgents: boolean;
+  onClose: () => void;
+}) {
+  const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
+  const agents = createMemo(() =>
+    store.availableAgents.filter(
+      (a) => a.available !== false && documentAgentSupport(a.id).headless,
+    ),
+  );
+  const [agentId, setAgentId] = createSignal<string | null>(null);
+  const agent = () =>
+    agents().find((a) => a.id === (agentId() ?? documentMainAgentId(project()))) ?? agents()[0];
+  const mergeable = createMemo(() =>
+    props.run.candidates.filter((c) => c.status === 'done' && c.commitSha),
+  );
+  // Excluded rather than included: every proposal is in until the reviewer drops it.
+  const [excluded, setExcluded] = createSignal<ReadonlySet<string>>(new Set<string>());
+  const chosen = () => mergeable().filter((c) => !excluded().has(c.id));
+  const [guidance, setGuidance] = createSignal(DEFAULT_GUIDANCE);
+  const [starting, setStarting] = createSignal(false);
+  const [error, setError] = createSignal('');
+  const ready = () => !!agent() && chosen().length >= 2 && !!guidance().trim() && !starting();
+
+  function toggleCandidate(id: string) {
+    setExcluded((prev) => {
+      const next = new Set(prev);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+  }
+
+  async function merge() {
+    const picked = agent();
+    if (!picked || !ready()) return;
+    setStarting(true);
+    setError('');
+    try {
+      await mergeDocumentCandidates({
+        run: props.run,
+        candidateIds: chosen().map((c) => c.id),
+        instruction: guidance().trim(),
+        agent: picked,
+        choice: documentModelChoices(project(), picked.id)[0] ?? {},
+      });
+      props.onClose();
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setStarting(false);
+    }
+  }
+
+  // Mounted only while open, so the form is registered for its whole life.
+  // eslint-disable-next-line solid/reactivity -- the registry calls back later, outside any reactive context; it wants the current onClose
+  onCleanup(registerCompareForm(() => props.onClose()));
+
+  // Bound natively so the key stops here: the compare dialog listens on the
+  // document and would take the same Escape as its own and close over the form.
+  function onKeyDown(e: KeyboardEvent) {
+    if (e.key !== 'Escape') return;
+    e.stopPropagation();
+    props.onClose();
+  }
+
+  return (
+    <section class="docws-merge-panel" aria-label="Merge with agent" on:keydown={onKeyDown}>
+      <p>
+        One agent reads the proposals you pick, as diffs against the base, and drafts a single
+        merged proposal. It shows up in Runs for you to review; nothing is accepted for you.
+      </p>
+      <div class="docws-merge-row" role="group" aria-label="Proposals to merge">
+        <For each={mergeable()}>
+          {(candidate) => (
+            <label class="docws-toggle">
+              <input
+                type="checkbox"
+                checked={!excluded().has(candidate.id)}
+                onChange={() => toggleCandidate(candidate.id)}
+                disabled={starting()}
+              />
+              Candidate {candidate.label}
+              {props.revealAgents ? ` · ${candidate.agentName}` : ''}
+            </label>
+          )}
+        </For>
+      </div>
+      <div class="docws-agent-row" role="group" aria-label="Merging agent">
+        <For each={agents()}>
+          {(a) => (
+            <button
+              type="button"
+              class="docws-agent-chip"
+              aria-pressed={agent()?.id === a.id}
+              title={modelLabel(documentModelChoices(project(), a.id)[0] ?? {}) || 'CLI defaults'}
+              onClick={() => setAgentId(a.id)}
+              disabled={starting()}
+            >
+              {a.name}
+            </button>
+          )}
+        </For>
+      </div>
+      <textarea
+        class="docws-note"
+        aria-label="Merge guidance"
+        ref={(el) => queueMicrotask(() => el.focus())}
+        value={guidance()}
+        onInput={(e) => setGuidance(e.currentTarget.value)}
+        disabled={starting()}
+      />
+      <Show when={error()}>
+        <p class="docws-error" role="alert">
+          {error()}
+        </p>
+      </Show>
+      <div class="docws-run-actions">
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm docws-btn-primary"
+          disabled={!ready()}
+          title={chosen().length < 2 ? 'Pick at least two proposals' : undefined}
+          onClick={() => void merge()}
+        >
+          {starting() ? 'Starting…' : 'Generate merged version'}
+        </button>
+        <button type="button" class="docws-btn docws-btn-sm" onClick={() => props.onClose()}>
+          Cancel
+        </button>
+      </div>
+    </section>
+  );
+}
diff --git a/src/documents/ModelRows.tsx b/src/documents/ModelRows.tsx
index 8f7796967..0856ff59d 100644
--- a/src/documents/ModelRows.tsx
+++ b/src/documents/ModelRows.tsx
@@ -49,6 +49,13 @@ export function ModelRows(props: ModelRowsProps) {
                   value={props.choice(slot).model ?? ''}
                   onInput={(e) => props.onChoice(slot, { model: e.currentTarget.value }, false)}
                   onChange={(e) => props.onChoice(slot, { model: e.currentTarget.value }, true)}
+                  onKeyDown={(e) => {
+                    // Escape leaves the field; let through, it would close the
+                    // composer and drop the instruction with it.
+                    if (e.key !== 'Escape') return;
+                    e.stopPropagation();
+                    e.currentTarget.blur();
+                  }}
                 />
                 <datalist id={listId}>
                   <For each={support.models}>{(m) => <option value={m} />}</For>
diff --git a/src/documents/NewDocumentProjectDialog.client.test.tsx b/src/documents/NewDocumentProjectDialog.client.test.tsx
index d4a5052c5..db4aaab82 100644
--- a/src/documents/NewDocumentProjectDialog.client.test.tsx
+++ b/src/documents/NewDocumentProjectDialog.client.test.tsx
@@ -15,24 +15,36 @@ afterEach(() => {
   vi.resetAllMocks();
 });
 
-async function open(files: Array<{ path: string; committed: boolean }>) {
-  vi.mocked(invoke).mockImplementation(async (channel) =>
-    channel === IPC.InspectDocumentFolder
-      ? { exists: true, isRepo: true, files }
-      : { documentPath: files[0]?.path ?? 'design-notes.md', actions: [] },
-  );
-  dispose = render(() => <NewDocumentProjectDialog open onClose={() => {}} />, document.body);
+function folderInput(): HTMLInputElement {
   const input = document.querySelector<HTMLInputElement>('[aria-label="Project folder"]');
   if (!input) throw new Error('Project folder input did not render');
-  input.value = '/tmp/design-notes';
+  return input;
+}
+
+async function typeFolder(path: string) {
+  const input = folderInput();
+  input.value = path;
   input.dispatchEvent(new Event('input', { bubbles: true }));
   await vi.waitFor(() =>
-    expect(invoke).toHaveBeenCalledWith(IPC.InspectDocumentFolder, {
-      projectRoot: '/tmp/design-notes',
-    }),
+    expect(invoke).toHaveBeenCalledWith(IPC.InspectDocumentFolder, { projectRoot: path }),
   );
 }
 
+async function open(files: Array<{ path: string; committed: boolean }>) {
+  vi.mocked(invoke).mockImplementation(async (channel, args) =>
+    channel === IPC.InspectDocumentFolder
+      ? // Only the first folder holds the files; any other path is empty.
+        {
+          exists: true,
+          isRepo: true,
+          files: (args as { projectRoot: string }).projectRoot === '/tmp/design-notes' ? files : [],
+        }
+      : { documentPath: files[0]?.path ?? 'design-notes.md', actions: [] },
+  );
+  dispose = render(() => <NewDocumentProjectDialog open onClose={() => {}} />, document.body);
+  await typeFolder('/tmp/design-notes');
+}
+
 function submit() {
   Array.from(document.querySelectorAll('button'))
     .find((b) => b.textContent === 'Open workspace')
@@ -52,6 +64,37 @@ it('creates Markdown without asking first-time users to choose a format', async
   );
 });
 
+it('focuses the folder path on open and opens the workspace on Enter', async () => {
+  await open([]);
+  await vi.waitFor(() => expect(document.activeElement).toBe(folderInput()));
+  folderInput().dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+  await vi.waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith(IPC.PrepareDocumentProject, {
+      projectRoot: '/tmp/design-notes',
+      documentPath: 'design-notes.md',
+      title: 'design-notes',
+    }),
+  );
+});
+
+it('lets a picked document go when the folder changes', async () => {
+  await open([{ path: 'page.html', committed: true }]);
+  await vi.waitFor(() => expect(document.querySelector('[role="option"]')).not.toBeNull());
+  Array.from(document.querySelectorAll<HTMLButtonElement>('[role="option"]'))
+    .find((b) => b.textContent?.includes('page.html'))
+    ?.click();
+  await typeFolder('/tmp/other');
+  await vi.waitFor(() => expect(document.body.textContent).not.toContain('page.html'));
+  submit();
+  await vi.waitFor(() =>
+    expect(invoke).toHaveBeenCalledWith(IPC.PrepareDocumentProject, {
+      projectRoot: '/tmp/other',
+      documentPath: 'other.md',
+      title: 'other',
+    }),
+  );
+});
+
 it('still opens an existing HTML document', async () => {
   await open([{ path: 'page.html', committed: true }]);
   submit();
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index 094930f9c..1dfdf6a92 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -5,6 +5,7 @@ import {
   createMemo,
   createResource,
   createSignal,
+  on,
   onCleanup,
 } from 'solid-js';
 import { Dialog } from '../components/Dialog';
@@ -69,25 +70,36 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
   const [choice, setChoice] = createSignal<DocumentChoice>('default');
   const [error, setError] = createSignal('');
   const [busy, setBusy] = createSignal(false);
+  let folderInput: HTMLInputElement | undefined;
 
-  // Re-inspected as the path is edited; a folder that does not exist yet comes
-  // back empty rather than as an error.
-  const [settledFolder, setSettledFolder] = createSignal('');
-  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+  // The path is what the dialog is about; typing starts there.
   createEffect(() => {
-    const value = folder().trim();
-    clearTimeout(settleTimer);
-    settleTimer = setTimeout(() => setSettledFolder(value), INSPECT_DEBOUNCE_MS);
+    if (!props.open) return;
+    requestAnimationFrame(() => folderInput?.focus());
   });
-  onCleanup(() => clearTimeout(settleTimer));
 
-  const [info] = createResource(
+  // Re-inspected as the path is edited; a folder that does not exist yet comes
+  // back empty rather than as an error.
+  const [settledFolder, setSettledFolder] = createSignal('');
+  const [info, { mutate: setInfo }] = createResource(
     () => settledFolder() || null,
     // A path that is still half-typed, or one the app may not read, is simply
     // "nothing known about it yet"; creating the project reports the real error.
     (projectRoot) =>
       invoke<DocumentFolderInfo>(IPC.InspectDocumentFolder, { projectRoot }).catch(() => null),
   );
+  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+  createEffect(
+    on(folder, (value) => {
+      // What was known about the last folder, and a file picked from its
+      // list, must not carry over to the next one.
+      setChoice('default');
+      setInfo(undefined);
+      clearTimeout(settleTimer);
+      settleTimer = setTimeout(() => setSettledFolder(value.trim()), INSPECT_DEBOUNCE_MS);
+    }),
+  );
+  onCleanup(() => clearTimeout(settleTimer));
 
   const files = () => info()?.files ?? [];
   const visibleFiles = createMemo(() => {
@@ -123,6 +135,11 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     setFilter('');
     setChoice('default');
     setError('');
+    // The resource keeps its last value while its source is empty, so the
+    // next open would show the old folder's files and plan until it settles.
+    clearTimeout(settleTimer);
+    setSettledFolder('');
+    setInfo(undefined);
   }
 
   function close() {
@@ -164,6 +181,11 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     }
   }
 
+  /** Enter in a field is the primary button, when it is enabled. */
+  function submitOnEnter(e: KeyboardEvent) {
+    if (e.key === 'Enter' && !e.isComposing) void create();
+  }
+
   const inputStyle = {
     background: theme.bgInput,
     border: `1px solid ${theme.border}`,
@@ -189,10 +211,12 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
           <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
             <input
               style={{ ...inputStyle, 'font-family': 'var(--font-mono)', 'font-size': '12px' }}
+              ref={folderInput}
               aria-label="Project folder"
               placeholder="/path/to/folder"
               value={folder()}
               onInput={(e) => setFolder(e.currentTarget.value)}
+              onKeyDown={submitOnEnter}
             />
             <button
               type="button"
@@ -223,6 +247,7 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
                 setNameEdited(true);
                 setName(e.currentTarget.value);
               }}
+              onKeyDown={submitOnEnter}
             />
           </div>
           <Show when={files().length > 0}>
diff --git a/src/documents/PageBlocks.tsx b/src/documents/PageBlocks.tsx
index 74ab3875e..3214c0e79 100644
--- a/src/documents/PageBlocks.tsx
+++ b/src/documents/PageBlocks.tsx
@@ -1,5 +1,4 @@
-import { For, createEffect, createSignal, on, onCleanup, type JSX } from 'solid-js';
-import { createBlockActionsElement, type BlockActionKind } from './BlockActions';
+import { For, createEffect, createMemo, createSignal, on, onCleanup, type JSX } from 'solid-js';
 import { Portal } from 'solid-js/web';
 import type { BlockRange } from './DocumentViewer';
 import type { BlockChange, DocumentBlock } from './markdown-blocks';
@@ -23,7 +22,6 @@ interface PageBlocksProps {
   /** Which blocks have a marker; only those get an anchor. */
   hasMarker?: (index: number) => boolean;
   onSelectSection: (index: number, e: MouseEvent) => void;
-  onAction?: (action: BlockActionKind, index: number) => void;
 }
 
 /** Where a block's marker is rendered: a hook appended inside the block. */
@@ -41,7 +39,9 @@ function inRange(range: BlockRange | null | undefined, index: number): boolean {
  * and works on the blocks marked inside it by hand: marks are classes on the
  * page's elements, § buttons are appended to headings, and annotation markers
  * go into anchors appended inside their block. Every one of those is out of
- * the page's flow, so nothing the app adds moves the page's own elements.
+ * the page's flow, so nothing the app adds moves the page's own elements. The
+ * hover toolbar is the viewer's, floating over the window, since a page's
+ * elements may clip their overflow.
  */
 export function PageBlocks(props: PageBlocksProps) {
   const [body, setBody] = createSignal<HTMLDivElement>();
@@ -68,17 +68,6 @@ export function PageBlocks(props: PageBlocksProps) {
     }),
   );
 
-  // Every block gets the hover toolbar, appended like the § button.
-  createEffect(() => {
-    const onAction = props.onAction;
-    if (!props.html || !props.selectable || !onAction) return;
-    for (const block of props.blocks) {
-      const el = blockElement(block.index);
-      if (!el || el.querySelector(':scope > .docws-block-actions')) continue;
-      el.append(createBlockActionsElement((kind) => onAction(kind, block.index)));
-    }
-  });
-
   createEffect(() => {
     if (!props.html || !props.selectable) return;
     for (const block of props.blocks) {
@@ -96,21 +85,33 @@ export function PageBlocks(props: PageBlocksProps) {
     }
   });
 
+  // Which blocks carry a marker. The notes themselves change far more often
+  // than this set, and rebuilding the anchors on every edit would tear down
+  // the popover being edited; the markers inside the anchors update on their own.
+  const marked = createMemo(
+    () => {
+      const wants = props.hasMarker;
+      if (!wants) return [];
+      return props.blocks.filter((block) => wants(block.index)).map((block) => block.index);
+    },
+    [] as number[],
+    { equals: (a, b) => a.length === b.length && a.every((index, i) => index === b[i]) },
+  );
+
   createEffect(() => {
-    const wants = props.hasMarker;
-    if (!props.html || !body() || !wants) {
+    const indices = marked();
+    if (!props.html || !body() || indices.length === 0) {
       setAnchors([]);
       return;
     }
     const created: MarkerAnchor[] = [];
-    for (const block of props.blocks) {
-      if (!wants(block.index)) continue;
-      const el = blockElement(block.index);
+    for (const index of indices) {
+      const el = blockElement(index);
       if (!el) continue;
       const anchor = document.createElement('div');
       anchor.className = 'docws-marker-anchor';
       el.append(anchor);
-      created.push({ index: block.index, el: anchor });
+      created.push({ index, el: anchor });
     }
     setAnchors(created);
     onCleanup(() => created.forEach((a) => a.el.remove()));
diff --git a/src/documents/RejectRunConfirm.tsx b/src/documents/RejectRunConfirm.tsx
new file mode 100644
index 000000000..731c1e37d
--- /dev/null
+++ b/src/documents/RejectRunConfirm.tsx
@@ -0,0 +1,63 @@
+import { createSignal } from 'solid-js';
+import { ConfirmDialog } from '../components/ConfirmDialog';
+import { rejectDocumentRun } from './store';
+import type { DocumentRunRecord } from './types';
+
+/** Runs whose rejection is under way, so a second click cannot start it twice. */
+const [rejecting, setRejecting] = createSignal<ReadonlySet<string>>(new Set<string>());
+
+async function reject(runId: string): Promise<void> {
+  setRejecting((prev) => new Set(prev).add(runId));
+  try {
+    await rejectDocumentRun(runId);
+  } finally {
+    setRejecting((prev) => {
+      const next = new Set(prev);
+      next.delete(runId);
+      return next;
+    });
+  }
+}
+
+/**
+ * The button that throws a run's proposals away, with the confirmation that
+ * deserves: rejecting deletes the candidates' branches and worktrees, and
+ * nothing brings them back. A run that produced no proposal is only
+ * dismissed, which needs no second thought.
+ */
+export function RejectRunButton(props: { run: DocumentRunRecord; label: string }) {
+  const [confirming, setConfirming] = createSignal(false);
+  const proposals = () => props.run.candidates.filter((c) => c.commitSha).length;
+  const busy = () => rejecting().has(props.run.id);
+
+  function confirm() {
+    setConfirming(false);
+    void reject(props.run.id);
+  }
+
+  return (
+    <>
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm docws-btn-danger"
+        disabled={busy()}
+        onClick={() => (proposals() > 0 ? setConfirming(true) : void reject(props.run.id))}
+      >
+        {props.label}
+      </button>
+      <ConfirmDialog
+        open={confirming()}
+        title={proposals() > 1 ? 'Reject all proposals?' : 'Reject this proposal?'}
+        message={
+          proposals() > 1
+            ? `The ${proposals()} proposals and their branches are deleted. Your document stays as it is.`
+            : 'The proposal and its branch are deleted. Your document stays as it is.'
+        }
+        confirmLabel="Reject"
+        danger
+        onConfirm={confirm}
+        onCancel={() => setConfirming(false)}
+      />
+    </>
+  );
+}
diff --git a/src/documents/RightPanel.client.test.tsx b/src/documents/RightPanel.client.test.tsx
new file mode 100644
index 000000000..f69a9bc34
--- /dev/null
+++ b/src/documents/RightPanel.client.test.tsx
@@ -0,0 +1,95 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore, store } from '../store/core';
+import { clearAgentActivity } from '../store/taskStatus';
+import { RightPanel } from './RightPanel';
+import { ensureDocumentAgentTask } from './agent-task';
+import { resetWorkspaceUi, setRailTab } from './workspace-ui';
+import type { AgentDef } from '../ipc/types';
+import type { Project } from '../store/types';
+
+vi.mock('../components/TerminalView', () => ({
+  TerminalView: () => <div class="terminal-stub" />,
+}));
+vi.mock('../lib/ipc', () => ({
+  invoke: vi.fn(() => Promise.resolve([])),
+  Channel: class {
+    dispose() {}
+  },
+}));
+vi.mock('../lib/shell', () => ({ openInEditor: vi.fn(), revealItemInDir: vi.fn() }));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  for (const id of Object.keys(store.agents)) clearAgentActivity(id);
+  resetWorkspaceUi();
+  setStore({
+    projects: [],
+    availableAgents: [],
+    tasks: {},
+    agents: {},
+    activeTaskId: null,
+    activeAgentId: null,
+  });
+});
+
+const codex: AgentDef = {
+  id: 'codex',
+  name: 'Codex',
+  command: 'codex',
+  args: [],
+  resume_args: [],
+  skip_permissions_args: [],
+  description: '',
+};
+
+const project: Project = {
+  id: 'docs',
+  name: 'Docs',
+  path: '/projects/docs',
+  color: '',
+  kind: 'document',
+  documentPath: 'notes.md',
+  documentTerminalAgentId: 'codex',
+};
+
+function mount(): HTMLElement {
+  setStore({ availableAgents: [codex], projects: [project] });
+  ensureDocumentAgentTask(project);
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(render(() => <RightPanel project={project} />, host));
+  return host;
+}
+
+function tab(host: HTMLElement, label: string): HTMLButtonElement | null {
+  return (
+    Array.from(host.querySelectorAll<HTMLButtonElement>('[role="tab"]')).find(
+      (b) => b.textContent?.trim() === label,
+    ) ?? null
+  );
+}
+
+describe('RightPanel', () => {
+  it('keeps the terminal mounted behind the other tabs', () => {
+    const host = mount();
+    const agentTab = host.querySelector('.docws-agent-tab');
+    expect(host.querySelector('.terminal-stub')).not.toBeNull();
+    expect(agentTab?.classList.contains('is-hidden')).toBe(false);
+
+    tab(host, 'Runs')?.click();
+
+    expect(tab(host, 'Runs')?.getAttribute('aria-selected')).toBe('true');
+    expect(host.querySelector('.terminal-stub')).not.toBeNull();
+    expect(agentTab?.classList.contains('is-hidden')).toBe(true);
+    expect(host.textContent).toContain('Proposals show up here.');
+
+    setRailTab('agent');
+
+    expect(agentTab?.classList.contains('is-hidden')).toBe(false);
+    expect(host.querySelector('.terminal-stub')).not.toBeNull();
+  });
+});
diff --git a/src/documents/RightPanel.tsx b/src/documents/RightPanel.tsx
index a9a552f7f..1e30e134c 100644
--- a/src/documents/RightPanel.tsx
+++ b/src/documents/RightPanel.tsx
@@ -1,12 +1,15 @@
 import { For, Show, createMemo } from 'solid-js';
+import { store } from '../store/core';
 import type { Project } from '../store/types';
 import { getAgentHookStatus } from '../store/agentHookStatus';
-import { documentStore, openDocumentCompare, rejectDocumentRun, reviewableRuns } from './store';
+import { isAgentAskingQuestion } from '../store/taskStatus';
+import { documentStore, openDocumentCompare, reviewableRuns } from './store';
 import { setRailTab, workspaceUi } from './workspace-ui';
-import { documentAgentPtyId } from './agent-terminal';
+import { documentAgentTaskId } from './agent-task';
 import { AgentTerminal } from './AgentTerminal';
 import { RunsRail } from './RunsRail';
 import { FileTreePanel } from './FileTreePanel';
+import { RejectRunButton } from './RejectRunConfirm';
 
 interface RightPanelProps {
   project: Project;
@@ -33,13 +36,7 @@ function DecisionStrip() {
                 >
                   {proposals() > 1 ? `Compare ${proposals()}` : 'Review'}
                 </button>
-                <button
-                  type="button"
-                  class="docws-btn docws-btn-sm docws-btn-danger"
-                  onClick={() => void rejectDocumentRun(run.id)}
-                >
-                  Reject
-                </button>
+                <RejectRunButton run={run} label="Reject" />
               </div>
             );
           }}
@@ -58,22 +55,36 @@ export function RightPanel(props: RightPanelProps) {
   const decisions = () => reviewableRuns().length;
   const running = () =>
     documentStore.runOrder.filter((id) => documentStore.runs[id]?.status === 'running').length;
+  const agentIds = () => store.tasks[documentAgentTaskId(props.project.id)]?.agentIds ?? [];
+  // Claude says so through its hooks; for the rest the terminal output has to tell.
   const agentWaiting = () =>
-    getAgentHookStatus(documentAgentPtyId(props.project.id))?.state === 'waiting';
+    agentIds().some(
+      (id) => getAgentHookStatus(id)?.state === 'waiting' || isAgentAskingQuestion(id),
+    );
+  const runsLabel = () => {
+    if (decisions() > 0) return `Runs, ${decisions()} awaiting a decision`;
+    if (running() > 0) return `Runs, ${running()} running`;
+    return 'Runs';
+  };
 
   return (
-    <aside class="docws-rail" aria-label="Agent and runs">
+    <aside class="docws-rail" aria-label="Agent, runs and files">
       <div class="docws-rail-tabs docws-tabs" role="tablist">
         <button
           type="button"
           class="docws-tab"
           role="tab"
           aria-selected={workspaceUi.railTab === 'agent'}
+          aria-label={agentWaiting() ? 'Agent, waiting for you' : 'Agent'}
           onClick={() => setRailTab('agent')}
         >
           Agent
           <Show when={agentWaiting()}>
-            <span class="docws-count is-attention" title="The agent is waiting for you">
+            <span
+              class="docws-count is-attention"
+              title="The agent is waiting for you"
+              aria-hidden="true"
+            >
               !
             </span>
           </Show>
@@ -83,11 +94,16 @@ export function RightPanel(props: RightPanelProps) {
           class="docws-tab"
           role="tab"
           aria-selected={workspaceUi.railTab === 'runs'}
+          aria-label={runsLabel()}
           onClick={() => setRailTab('runs')}
         >
           Runs
           <Show when={decisions() + running() > 0}>
-            <span class="docws-count" classList={{ 'is-attention': decisions() > 0 }}>
+            <span
+              class="docws-count"
+              classList={{ 'is-attention': decisions() > 0 }}
+              aria-hidden="true"
+            >
               {decisions() > 0 ? decisions() : running()}
             </span>
           </Show>
@@ -102,10 +118,10 @@ export function RightPanel(props: RightPanelProps) {
           Files
         </button>
       </div>
-      <Show when={workspaceUi.railTab === 'agent'}>
+      <div class="docws-agent-tab" classList={{ 'is-hidden': workspaceUi.railTab !== 'agent' }}>
         <DecisionStrip />
         <AgentTerminal project={props.project} />
-      </Show>
+      </div>
       <Show when={workspaceUi.railTab === 'runs'}>
         <div class="docws-rail-list">
           <RunsRail />
diff --git a/src/documents/RunComposer.annotate.client.test.tsx b/src/documents/RunComposer.annotate.client.test.tsx
index 13200433b..40008f5dd 100644
--- a/src/documents/RunComposer.annotate.client.test.tsx
+++ b/src/documents/RunComposer.annotate.client.test.tsx
@@ -9,8 +9,7 @@ const { addDocumentAnnotation } = vi.hoisted(() => ({
   addDocumentAnnotation: vi.fn(async () => ({ id: 'saved-1' })),
 }));
 
-vi.mock('./agent-terminal', () => ({
-  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+vi.mock('./agent-task', () => ({
   sendToDocumentAgent: vi.fn(() => Promise.resolve()),
 }));
 
@@ -66,6 +65,27 @@ function pressEnter(textarea: HTMLTextAreaElement): void {
   textarea.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
 }
 
+describe('RunComposer while an input method is composing', () => {
+  it('leaves Enter to the IME instead of saving a half-typed note', async () => {
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(
+      render(() => <RunComposer selection={passage} blocks={blocks} onClose={() => {}} />, host),
+    );
+    tab(host, 'Note')?.click();
+    const textarea = type(host, '注意');
+
+    textarea.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, isComposing: true }),
+    );
+    await Promise.resolve();
+    expect(addDocumentAnnotation).not.toHaveBeenCalled();
+
+    pressEnter(textarea);
+    await vi.waitFor(() => expect(addDocumentAnnotation).toHaveBeenCalledOnce());
+  });
+});
+
 describe('RunComposer after a note or question is saved', () => {
   it('empties the instruction so the next passage opens on a blank composer', async () => {
     const onClose = vi.fn();
@@ -84,7 +104,7 @@ describe('RunComposer after a note or question is saved', () => {
       'question',
       'Why is this here?',
       expect.anything(),
-      undefined,
+      { askWith: undefined },
     );
     expect(textarea.value).toBe('');
   });
diff --git a/src/documents/RunComposer.client.test.tsx b/src/documents/RunComposer.client.test.tsx
index f3d70bf06..c6115eb7f 100644
--- a/src/documents/RunComposer.client.test.tsx
+++ b/src/documents/RunComposer.client.test.tsx
@@ -5,8 +5,7 @@ import { RunComposer } from './RunComposer';
 import type { DocumentBlock } from './markdown-blocks';
 import type { DocumentSelection } from './store';
 
-vi.mock('./agent-terminal', () => ({
-  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+vi.mock('./agent-task', () => ({
   sendToDocumentAgent: vi.fn(() => Promise.resolve()),
 }));
 
@@ -67,28 +66,79 @@ function tab(host: HTMLElement, label: string): HTMLButtonElement | null {
 }
 
 describe('RunComposer', () => {
-  it('runs a task in the session and puts proposals on their own tab', () => {
+  it('keeps "Send to agent" off while no agent is installed', () => {
     const host = mount(passage);
+    tab(host, 'Edit with agent')?.click();
+    const box = host.querySelector('textarea');
+    if (box) {
+      box.value = 'Tighten this.';
+      box.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    const send = Array.from(host.querySelectorAll('button')).find(
+      (b) => b.textContent?.trim() === 'Send to agent',
+    );
+
+    expect(send?.disabled).toBe(true);
+    expect(send?.title).toBe('No agent is installed.');
+
+    // No workspace is open here, so the button stays off; the reason goes away.
+    setStore('availableAgents', [
+      {
+        id: 'codex',
+        name: 'Codex',
+        command: 'codex',
+        args: [],
+        resume_args: [],
+        skip_permissions_args: [],
+        description: '',
+      },
+    ]);
+    expect(send?.title).toBe('');
+  });
 
-    const task = tab(host, 'Task');
-    const proposals = tab(host, 'Proposals');
-    expect(task?.getAttribute('aria-selected')).toBe('true');
-    expect(proposals?.getAttribute('aria-selected')).toBe('false');
-    expect(host.textContent).toContain('The agent edits your document directly.');
-    expect(host.querySelector<HTMLElement>('[aria-label="Agents"]')?.style.display).toBe('none');
-
-    proposals?.click();
+  it('defaults to proposals and makes direct editing an explicit choice', () => {
+    const host = mount(passage);
 
-    expect(task?.getAttribute('aria-selected')).toBe('false');
+    const task = tab(host, 'Edit with agent');
+    const proposals = tab(host, 'Proposals');
     expect(proposals?.getAttribute('aria-selected')).toBe('true');
-    expect(host.querySelector<HTMLElement>('[aria-label="Agents"]')?.style.display).toBe('');
+    expect(task?.getAttribute('aria-selected')).toBe('false');
+    // Who drafts is the decision, so the agents sit in plain view; tuning is folded away.
+    const agents = host.querySelector('[aria-label="Agents"]');
+    expect(agents).not.toBeNull();
     const options = host.querySelector('details');
     expect(options).not.toBeNull();
     expect(options?.open).toBe(false);
-    expect(options?.contains(host.querySelector('[aria-label="Agents"]'))).toBe(true);
+    expect(options?.contains(agents)).toBe(false);
+    expect(options?.textContent).toContain('Models and main session');
+    expect(host.querySelector('.docws-proposal-count')?.textContent).toMatch(
+      /^\d+ of \d+ candidates?$/,
+    );
     expect(host.textContent).toContain('Your document changes only when you accept a proposal.');
     // No second toggle: the run target is one of the modes now.
     expect(host.querySelectorAll('[role="radio"]')).toHaveLength(0);
+
+    task?.click();
+    expect(task?.getAttribute('aria-selected')).toBe('true');
+    expect(proposals?.getAttribute('aria-selected')).toBe('false');
+    expect(host.textContent).toContain('The agent edits your document directly.');
+    expect(host.querySelector('[aria-label="Agents"]')).toBeNull();
+  });
+
+  it('counts candidates against the maximum in the plural', () => {
+    setStore('availableAgents', [
+      {
+        id: 'claude-code',
+        name: 'Claude Code',
+        command: 'claude',
+        args: [],
+        resume_args: [],
+        skip_permissions_args: [],
+        description: '',
+      },
+    ]);
+    const host = mount(passage);
+    expect(host.querySelector('.docws-proposal-count')?.textContent).toBe('1 of 6 candidates');
   });
 
   it('keeps proposals reachable with nothing picked, unlike notes and questions', () => {
diff --git a/src/documents/RunComposer.draft.client.test.tsx b/src/documents/RunComposer.draft.client.test.tsx
index d76b5e2db..f64e521f0 100644
--- a/src/documents/RunComposer.draft.client.test.tsx
+++ b/src/documents/RunComposer.draft.client.test.tsx
@@ -6,8 +6,7 @@ import { RunComposer } from './RunComposer';
 import { setDocumentComposerDraft, type DocumentSelection } from './store';
 import type { DocumentBlock } from './markdown-blocks';
 
-vi.mock('./agent-terminal', () => ({
-  documentAgentPtyId: (id: string) => `doc-agent-${id}`,
+vi.mock('./agent-task', () => ({
   sendToDocumentAgent: vi.fn(() => Promise.resolve()),
 }));
 
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
index 8307c47bd..54ccc2242 100644
--- a/src/documents/RunComposer.tsx
+++ b/src/documents/RunComposer.tsx
@@ -25,7 +25,7 @@ import type { AgentDef } from '../ipc/types';
 import type { DocumentModelChoice } from '../store/types';
 import { ModelRows, type ChoiceSlot, type ModelSlot } from './ModelRows';
 import { buildInteractivePrompt } from './interactive-prompt';
-import { documentAgentPtyId, sendToDocumentAgent } from './agent-terminal';
+import { sendToDocumentAgent } from './agent-task';
 import { ActionIcon } from './BlockActions';
 
 interface RunComposerProps {
@@ -53,21 +53,23 @@ function wholeDocumentSelection(blocks: DocumentBlock[]): DocumentSelection {
 
 /**
  * The popover that turns a passage into work: a task for the interactive
- * session or for one-shot candidates, a note, or a question. It is always
- * there over the foot of the document column and fades when it is not in use;
- * with nothing picked it acts on the whole document. The main session is
- * preselected with one candidate so the fast path is select, type, Enter.
+ * session or for one-shot candidates, a note, or a question. It opens over
+ * the prose when a passage is picked or a task on the whole document is asked
+ * for, and goes away once the work is handed off or dismissed. The main
+ * session is preselected with one candidate so the fast path is select, type,
+ * Enter.
  */
 export function RunComposer(props: RunComposerProps) {
   let textareaRef: HTMLTextAreaElement | undefined;
   const draft = untrack(() => documentStore.composerDraft);
   const [instruction, setInstruction] = createSignal(draft?.text ?? '');
-  const [mode, setMode] = createSignal<ComposerMode>('task');
+  const [mode, setMode] = createSignal<ComposerMode>('proposals');
   // Task and proposals are one instruction with two destinations: the agent's
   // session, or headless candidates. They share the textarea and the placeholder.
   const isTask = () => mode() === 'task' || mode() === 'proposals';
   const oneshot = () => mode() === 'proposals';
   const [saving, setSaving] = createSignal(false);
+  const [sending, setSending] = createSignal(false);
   // Just opened on a passage: shown at full strength until focus leaves it.
   const [fresh, setFresh] = createSignal(false);
   let rootRef: HTMLDivElement | undefined;
@@ -129,7 +131,9 @@ export function RunComposer(props: RunComposerProps) {
     total() <= MAX_DOCUMENT_CANDIDATES &&
     !documentStore.dispatching;
   const canAnnotate = () => instruction().trim().length > 0 && hasPassage() && !saving();
-  const canSend = () => instruction().trim().length > 0 && !!project();
+  const installed = createMemo(() => agents().filter((a) => a.available !== false));
+  const canSend = () =>
+    instruction().trim().length > 0 && !!project() && installed().length > 0 && !sending();
   const askAgent = () => agents().find((a) => a.id === askAgentId()) ?? resumable()[0];
 
   /** Notes and questions never touch the document: they are saved beside it. */
@@ -149,7 +153,7 @@ export function RunComposer(props: RunComposerProps) {
         mode() === 'question' ? 'question' : 'note',
         instruction().trim(),
         anchor,
-        mode() === 'question' ? askAgent() : undefined,
+        mode() === 'question' ? { askWith: askAgent() } : {},
       );
       if (saved) finish();
     } finally {
@@ -232,11 +236,16 @@ export function RunComposer(props: RunComposerProps) {
       selection(),
       instruction(),
     );
+    // A second Enter while the first is still typing into the terminal would
+    // send the instruction twice.
+    setSending(true);
     try {
-      await sendToDocumentAgent(documentAgentPtyId(p.id), text);
+      await sendToDocumentAgent(p, text);
       finish();
     } catch (err) {
       showNotification(errMessage(err));
+    } finally {
+      setSending(false);
     }
   }
 
@@ -247,6 +256,8 @@ export function RunComposer(props: RunComposerProps) {
   }
 
   function handleKeyDown(e: KeyboardEvent) {
+    // Enter and Escape mid-composition belong to the IME (229 is the legacy signal).
+    if (e.isComposing || e.keyCode === 229) return;
     if (e.key === 'Escape') {
       e.preventDefault();
       e.stopPropagation();
@@ -256,6 +267,8 @@ export function RunComposer(props: RunComposerProps) {
     }
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
+      // The task terminal underneath treats Enter as its send shortcut.
+      e.stopPropagation();
       submit();
     }
   }
@@ -288,7 +301,7 @@ export function RunComposer(props: RunComposerProps) {
       ref={rootRef}
       class="docws-composer"
       role="dialog"
-      aria-label="Run a task on the selected passage"
+      aria-label="Work on the selected passage"
       classList={{ 'is-scoped': hasPassage(), 'is-fresh': fresh() }}
       onFocusOut={handleFocusOut}
     >
@@ -303,7 +316,7 @@ export function RunComposer(props: RunComposerProps) {
             onClick={() => setMode('task')}
           >
             <ActionIcon kind="task" />
-            Task
+            Edit with agent
           </button>
           <button
             type="button"
@@ -352,19 +365,17 @@ export function RunComposer(props: RunComposerProps) {
         <span class="docws-composer-scope" title={scopeLabel()}>
           {scopeLabel()}
         </span>
-        <Show when={hasPassage()}>
-          <button
-            type="button"
-            class="docws-composer-close"
-            aria-label="Clear the passage"
-            title="Back to the whole document · Esc"
-            onClick={() => props.onClose()}
-          >
-            <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-              <path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z" />
-            </svg>
-          </button>
-        </Show>
+        <button
+          type="button"
+          class="docws-composer-close"
+          aria-label={hasPassage() ? 'Clear the passage' : 'Close'}
+          title={hasPassage() ? 'Let go of the passage and close · Esc' : 'Close · Esc'}
+          onClick={() => props.onClose()}
+        >
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z" />
+          </svg>
+        </button>
       </div>
       <Show when={hasPassage()}>
         <div class="docws-composer-quote">{selection().quote.slice(0, 400)}</div>
@@ -407,83 +418,93 @@ export function RunComposer(props: RunComposerProps) {
           </For>
         </div>
       </Show>
-      <details class="docws-proposal-options" style={{ display: oneshot() ? undefined : 'none' }}>
-        <summary>
-          Agents and models · {total()} candidate{total() === 1 ? '' : 's'}
-        </summary>
-        <label>
-          Main session{' '}
-          <select
-            class="docws-select"
-            value={mainAgentId()}
-            onChange={(e) => {
-              const next = e.currentTarget.value;
-              const prevMain = mainAgentId();
-              setDocumentMainAgent(next);
-              setCounts((prev) =>
-                prev[prevMain] && !prev[next]
-                  ? { ...without(prev, prevMain), [next]: prev[prevMain] }
-                  : prev,
-              );
-            }}
-          >
-            <For each={resumable()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
-          </select>
-        </label>
-        <div
-          class="docws-agent-row"
-          role="group"
-          aria-label="Agents"
-          style={{ display: oneshot() ? undefined : 'none' }}
-        >
-          <For each={agents()}>
-            {(agent) => {
-              const support = documentAgentSupport(agent.id);
-              const enabled = () => support.headless && agent.available !== false;
-              const count = () => counts()[agent.id] ?? 0;
-              const title = () =>
-                !support.headless
-                  ? 'No headless mode known for this agent'
-                  : agent.available === false
-                    ? 'Not installed'
-                    : agent.id === mainAgentId()
-                      ? 'Main session (resumes previous context)'
-                      : 'One-shot alternate';
-              return (
-                <div class="docws-agent-pick">
-                  <button
-                    type="button"
-                    class="docws-agent-chip"
-                    aria-pressed={count() > 0}
-                    disabled={!enabled()}
-                    title={title()}
-                    onClick={() => toggleAgent(agent)}
-                  >
-                    {agent.name}
-                    <Show when={agent.id === mainAgentId() && support.resume}>
-                      <span class="docws-main-badge">main</span>
-                    </Show>
-                  </button>
-                  <Show when={count() > 0}>
+      {/* Proposals: who drafts them is the decision, so the agents are in
+          plain view; model and main-session tuning sits one click away. */}
+      <Show when={oneshot()}>
+        <div class="docws-proposal-panel">
+          <div class="docws-proposal-head">
+            <span
+              class="docws-proposal-count"
+              classList={{ 'is-over': total() > MAX_DOCUMENT_CANDIDATES }}
+            >
+              {total()} of {MAX_DOCUMENT_CANDIDATES} candidates
+            </span>
+            <span class="docws-composer-hint">
+              Click an agent to add or drop it, its count to draft more than once.
+            </span>
+          </div>
+          <div class="docws-agent-row" role="group" aria-label="Agents">
+            <For each={agents()}>
+              {(agent) => {
+                const support = documentAgentSupport(agent.id);
+                const enabled = () => support.headless && agent.available !== false;
+                const count = () => counts()[agent.id] ?? 0;
+                const title = () =>
+                  !support.headless
+                    ? 'No headless mode known for this agent'
+                    : agent.available === false
+                      ? 'Not installed'
+                      : agent.id === mainAgentId()
+                        ? 'Main session (resumes previous context)'
+                        : 'One-shot alternate';
+                return (
+                  <div class="docws-agent-pick" classList={{ 'is-on': count() > 0 }}>
                     <button
                       type="button"
-                      class="docws-count-btn"
-                      aria-label={`Candidates from ${agent.name}: ${count()}`}
-                      title="Candidates from this agent (click to change)"
-                      onClick={(e) => bump(agent, e)}
+                      class="docws-agent-chip"
+                      aria-pressed={count() > 0}
+                      disabled={!enabled()}
+                      title={title()}
+                      onClick={() => toggleAgent(agent)}
                     >
-                      ×{count()}
+                      {agent.name}
+                      <Show when={agent.id === mainAgentId() && support.resume}>
+                        <span class="docws-main-badge">main</span>
+                      </Show>
                     </button>
-                  </Show>
-                </div>
-              );
-            }}
-          </For>
+                    <Show when={count() > 0}>
+                      <button
+                        type="button"
+                        class="docws-count-btn"
+                        aria-label={`Candidates from ${agent.name}: ${count()}`}
+                        title={`${count()} candidate${count() === 1 ? '' : 's'} from this agent · click for ${(count() % MAX_PER_AGENT) + 1}`}
+                        onClick={(e) => bump(agent, e)}
+                      >
+                        ×{count()}
+                      </button>
+                    </Show>
+                  </div>
+                );
+              }}
+            </For>
+          </div>
+          <details class="docws-proposal-options">
+            <summary>Models and main session</summary>
+            <label>
+              Main session{' '}
+              <select
+                class="docws-select"
+                value={mainAgentId()}
+                onChange={(e) => {
+                  const next = e.currentTarget.value;
+                  const prevMain = mainAgentId();
+                  setDocumentMainAgent(next);
+                  setCounts((prev) =>
+                    prev[prevMain] && !prev[next]
+                      ? { ...without(prev, prevMain), [next]: prev[prevMain] }
+                      : prev,
+                  );
+                }}
+              >
+                <For each={resumable()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
+              </select>
+            </label>
+            <Show when={slots().length > 0}>
+              <ModelRows slots={slots()} choice={choice} onChoice={setChoice} />
+            </Show>
+          </details>
         </div>
-        <Show when={oneshot() && slots().length > 0}>
-          <ModelRows slots={slots()} choice={choice} onChoice={setChoice} />
-        </Show>
-      </details>
+      </Show>
       <div class="docws-composer-footer">
         <span class="docws-composer-hint">{hint()}</span>
         <span>{keys()}</span>
@@ -507,6 +528,7 @@ export function RunComposer(props: RunComposerProps) {
                 type="button"
                 class="docws-btn docws-btn-sm docws-btn-primary"
                 disabled={!canSend()}
+                title={installed().length === 0 ? 'No agent is installed.' : undefined}
                 onClick={() => void send()}
               >
                 Send to agent
diff --git a/src/documents/RunsRail.client.test.tsx b/src/documents/RunsRail.client.test.tsx
new file mode 100644
index 000000000..8b11af9c2
--- /dev/null
+++ b/src/documents/RunsRail.client.test.tsx
@@ -0,0 +1,126 @@
+import { render } from 'solid-js/web';
+import { afterEach, expect, it, vi } from 'vitest';
+import type { DocumentRunRecord } from './types';
+import { RunsRail } from './RunsRail';
+import { closeDocumentCompare, openDocumentCompare, rejectDocumentRun } from './store';
+import { openCandidateOutput } from './workspace-ui';
+
+const { state } = vi.hoisted(() => ({
+  state: { runs: {} as Record<string, DocumentRunRecord>, runOrder: ['run-1'], logs: {} },
+}));
+vi.mock('./store', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./store')>()),
+  documentStore: state,
+  openDocumentCompare: vi.fn(),
+  rejectDocumentRun: vi.fn(async () => {}),
+}));
+vi.mock('./workspace-ui', () => ({ openCandidateOutput: vi.fn() }));
+
+let dispose: (() => void) | undefined;
+afterEach(() => {
+  dispose?.();
+  document.body.replaceChildren();
+  vi.clearAllMocks();
+});
+
+function mount(status: DocumentRunRecord['status'] = 'finished', hasProposal = true) {
+  state.runs = {
+    'run-1': {
+      version: 1,
+      id: 'run-1',
+      documentPath: 'doc.md',
+      createdAt: new Date(0).toISOString(),
+      instruction: 'Improve the introduction',
+      baseSha: 'abc123',
+      scope: { path: 'doc.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      status,
+      candidates: [
+        {
+          id: 'c2',
+          label: 'B',
+          agentId: 'codex',
+          agentName: 'Codex',
+          isMain: false,
+          status: hasProposal ? 'done' : 'failed',
+          commitSha: hasProposal ? 'proposal-sha' : null,
+          branch: 'proposal',
+          worktreePath: '/tmp/proposal',
+          startedAt: new Date(0).toISOString(),
+        },
+      ],
+    },
+  };
+  const host = document.createElement('div');
+  document.body.append(host);
+  dispose = render(() => <RunsRail />, host);
+  return host;
+}
+
+it('opens the clicked completed proposal and keeps output as a separate action', () => {
+  const host = mount();
+  host.querySelector<HTMLButtonElement>('[aria-label="Review proposal B"]')?.click();
+  expect(openDocumentCompare).toHaveBeenCalledWith('run-1', 'c2');
+  expect(openCandidateOutput).not.toHaveBeenCalled();
+  host.querySelector<HTMLButtonElement>('[aria-label="View output for proposal B"]')?.click();
+  expect(openCandidateOutput).toHaveBeenCalledWith({ runId: 'run-1', candidateId: 'c2' });
+  expect(openDocumentCompare).toHaveBeenCalledTimes(1);
+});
+
+it.each(['running', 'accepted', 'rejected'] as const)('opens output for a %s run', (status) => {
+  const host = mount(status);
+  host.querySelector<HTMLButtonElement>('.docws-candidate-main')?.click();
+  expect(openCandidateOutput).toHaveBeenCalledWith({ runId: 'run-1', candidateId: 'c2' });
+  expect(openDocumentCompare).not.toHaveBeenCalled();
+});
+
+it('opens output when a candidate has no proposal', () => {
+  const host = mount('finished', false);
+  host.querySelector<HTMLButtonElement>('.docws-candidate-main')?.click();
+  expect(openCandidateOutput).toHaveBeenCalledWith({ runId: 'run-1', candidateId: 'c2' });
+  expect(openDocumentCompare).not.toHaveBeenCalled();
+});
+
+function textButton(root: ParentNode, label: string): HTMLButtonElement {
+  const found = Array.from(root.querySelectorAll('button')).find((b) => b.textContent === label);
+  if (!found) throw new Error(`Missing button: ${label}`);
+  return found;
+}
+
+function dialog(): Element {
+  const found = document.querySelector('[role="dialog"]');
+  if (!found) throw new Error('No dialog is open');
+  return found;
+}
+
+it('asks before throwing a proposal away, and rejects only once confirmed', async () => {
+  const host = mount();
+  textButton(host, 'Reject all').click();
+
+  expect(dialog().textContent).toContain('Reject this proposal?');
+  textButton(dialog(), 'Cancel').click();
+  await vi.waitFor(() => expect(document.querySelector('[role="dialog"]')).toBeNull());
+  expect(rejectDocumentRun).not.toHaveBeenCalled();
+
+  textButton(host, 'Reject all').click();
+  textButton(dialog(), 'Reject').click();
+  await vi.waitFor(() => expect(rejectDocumentRun).toHaveBeenCalledWith('run-1'));
+  expect(document.querySelector('[role="dialog"]')).toBeNull();
+});
+
+it('dismisses a run that produced no proposal without asking', () => {
+  const host = mount('finished', false);
+  textButton(host, 'Dismiss').click();
+  expect(document.querySelector('[role="dialog"]')).toBeNull();
+  expect(rejectDocumentRun).toHaveBeenCalledWith('run-1');
+});
+
+it('clears a selected candidate when opening a different run or closing comparison', async () => {
+  const actual = await vi.importActual<typeof import('./store')>('./store');
+  actual.openDocumentCompare('run-1', 'c2');
+  expect(actual.documentStore.compareCandidateId).toBe('c2');
+  actual.openDocumentCompare('run-2');
+  expect(actual.documentStore.compareCandidateId).toBeNull();
+  actual.openDocumentCompare('run-1', 'c2');
+  closeDocumentCompare();
+  expect(actual.documentStore.compareCandidateId).toBeNull();
+});
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
index 3a296715e..f5b9ea9e6 100644
--- a/src/documents/RunsRail.tsx
+++ b/src/documents/RunsRail.tsx
@@ -6,12 +6,22 @@ import {
   documentStore,
   modelLabel,
   openDocumentCompare,
-  rejectDocumentRun,
 } from './store';
 import { openCandidateOutput } from './workspace-ui';
+import { RejectRunButton } from './RejectRunConfirm';
 import { formatRelativeAge } from '../lib/relativeAge';
 import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
 
+/** Where a run's starting content came from, when not the canonical document. */
+function lineageLabel(run: DocumentRunRecord): string | null {
+  const source = run.refinement ?? run.merge;
+  if (!source) return null;
+  const labels = documentStore.runs[source.runId]?.candidates ?? [];
+  const label = (id: string) => labels.find((c) => c.id === id)?.label ?? id;
+  if (run.merge) return `merges ${run.merge.candidateIds.map(label).join(' + ')}`;
+  return run.refinement ? `refines candidate ${label(run.refinement.candidateId)}` : null;
+}
+
 function scopeLabel(run: DocumentRunRecord): string {
   const s = run.scope;
   if (s.wholeDocument) return 'whole document';
@@ -49,34 +59,54 @@ function CandidateRow(props: {
   const lines = () => documentStore.logs[candidateLogKey(props.run.id, props.candidate.id)] ?? [];
   const tail = () => lines().slice(-6);
   const verdict = () => candidateVerdict(props.run, props.candidate);
+  const canReview = () =>
+    (props.run.status === 'finished' || props.run.status === 'stale') &&
+    props.candidate.status === 'done' &&
+    !!props.candidate.commitSha;
+  const output = () =>
+    openCandidateOutput({ runId: props.run.id, candidateId: props.candidate.id });
+
   return (
     <div
       class="docws-candidate"
       classList={{ 'is-passed-over': verdict() === 'passed-over' || verdict() === 'rejected' }}
-      role="button"
-      tabIndex={0}
-      title="Show what this candidate printed"
-      onClick={() => openCandidateOutput({ runId: props.run.id, candidateId: props.candidate.id })}
-      onKeyDown={(e) => {
-        if (e.key !== 'Enter' && e.key !== ' ') return;
-        e.preventDefault();
-        openCandidateOutput({ runId: props.run.id, candidateId: props.candidate.id });
-      }}
     >
-      <div class="docws-candidate-head">
-        <span class={`docws-dot docws-dot-${props.candidate.status}`} />
-        <span class="docws-candidate-label">{props.candidate.label}</span>
-        <span>{props.candidate.agentName}</span>
-        <Show when={props.candidate.model || props.candidate.effort}>
-          <span class="docws-candidate-model">{modelLabel(props.candidate)}</span>
-        </Show>
-        <Show when={props.candidate.isMain}>
-          <span class="docws-badge">main</span>
-        </Show>
-        <span class="docws-candidate-state" classList={{ 'is-accepted': verdict() === 'accepted' }}>
-          {candidateState(props.candidate, verdict())}
+      <button
+        type="button"
+        class="docws-candidate-main"
+        aria-label={`${canReview() ? 'Review' : 'View output for'} proposal ${props.candidate.label}`}
+        onClick={() =>
+          canReview() ? openDocumentCompare(props.run.id, props.candidate.id) : output()
+        }
+      >
+        <span class="docws-candidate-head">
+          <span class={`docws-dot docws-dot-${props.candidate.status}`} />
+          <span class="docws-candidate-label">{props.candidate.label}</span>
+          <span>{props.candidate.agentName}</span>
+          <Show when={props.candidate.model || props.candidate.effort}>
+            <span class="docws-candidate-model">{modelLabel(props.candidate)}</span>
+          </Show>
+          <Show when={props.candidate.isMain}>
+            <span class="docws-badge">main</span>
+          </Show>
+          <span
+            class="docws-candidate-state"
+            classList={{ 'is-accepted': verdict() === 'accepted' }}
+          >
+            {candidateState(props.candidate, verdict())}
+          </span>
         </span>
-      </div>
+      </button>
+      <Show when={canReview()}>
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm"
+          aria-label={`View output for proposal ${props.candidate.label}`}
+          onClick={output}
+        >
+          View output
+        </button>
+      </Show>
       <Show when={props.candidate.error && props.candidate.status !== 'running'}>
         <div class="docws-error">{props.candidate.error}</div>
       </Show>
@@ -120,6 +150,9 @@ export function RunsRail() {
               <div class="docws-run-instruction" title={run.instruction}>
                 {run.instruction}
               </div>
+              <Show when={lineageLabel(run)}>
+                {(lineage) => <div class="docws-run-meta docws-run-lineage">{lineage()}</div>}
+              </Show>
               <div class="docws-run-meta" title={scopeLabel(run)}>
                 <Show when={run.documentPath !== activeDocumentPath()}>
                   <span class="docws-run-doc">{run.documentPath} · </span>
@@ -155,13 +188,7 @@ export function RunsRail() {
                   </button>
                 </Show>
                 <Show when={run.status === 'finished' || run.status === 'stale'}>
-                  <button
-                    type="button"
-                    class="docws-btn docws-btn-sm docws-btn-danger"
-                    onClick={() => void rejectDocumentRun(run.id)}
-                  >
-                    {proposals() > 0 ? 'Reject all' : 'Dismiss'}
-                  </button>
+                  <RejectRunButton run={run} label={proposals() > 0 ? 'Reject all' : 'Dismiss'} />
                 </Show>
               </div>
             </div>
diff --git a/src/documents/agent-task.client.test.tsx b/src/documents/agent-task.client.test.tsx
new file mode 100644
index 000000000..6eb8b0d77
--- /dev/null
+++ b/src/documents/agent-task.client.test.tsx
@@ -0,0 +1,264 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { IPC } from '../../electron/ipc/channels';
+import { setStore, store } from '../store/core';
+import { applyAgentHookEvent, clearAgentHookStatus } from '../store/agentHookStatus';
+import { clearAgentActivity } from '../store/taskStatus';
+import type { AgentDef } from '../ipc/types';
+import type { Project, Task } from '../store/types';
+import {
+  activateDocumentAgentTask,
+  disposeDocumentAgentTask,
+  documentAgentTaskId,
+  ensureDocumentAgentTask,
+  rearmDocumentAgents,
+  releaseDocumentAgentTask,
+  sendToDocumentAgent,
+} from './agent-task';
+import { resetWorkspaceUi, setRailTab, workspaceUi } from './workspace-ui';
+
+const { sendPrompt, invoke } = vi.hoisted(() => ({
+  sendPrompt: vi.fn(() => Promise.resolve()),
+  invoke: vi.fn(() => Promise.resolve()),
+}));
+
+vi.mock('../store/tasks', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../store/tasks')>()),
+  sendPrompt,
+}));
+vi.mock('../lib/ipc', () => ({
+  invoke,
+  Channel: class {
+    dispose() {}
+  },
+}));
+
+afterEach(() => {
+  clearAgentActivity(documentAgentTaskId('docs'));
+  clearAgentHookStatus(documentAgentTaskId('docs'));
+  setStore({
+    projects: [],
+    availableAgents: [],
+    tasks: {},
+    agents: {},
+    taskOrder: [],
+    activeTaskId: null,
+    activeAgentId: null,
+  });
+  resetWorkspaceUi();
+  vi.clearAllMocks();
+});
+
+const agent = (id: string): AgentDef => ({
+  id,
+  name: id,
+  command: id,
+  args: [],
+  resume_args: [],
+  skip_permissions_args: [],
+  description: '',
+});
+
+const project: Project = {
+  id: 'docs',
+  name: 'Docs',
+  path: '/projects/docs',
+  color: '',
+  kind: 'document',
+  documentPath: 'notes.md',
+  documentTerminalAgentId: 'codex',
+};
+
+const codingTask: Task = {
+  id: 't1',
+  name: 'Task 1',
+  projectId: 'code',
+  branchName: 'task/t1',
+  worktreePath: '/projects/code',
+  agentIds: ['a1'],
+  shellAgentIds: [],
+  notes: '',
+  lastPrompt: '',
+  gitIsolation: 'worktree',
+};
+
+function install(...ids: string[]): void {
+  setStore({ availableAgents: ids.map(agent), projects: [project] });
+}
+
+describe('ensureDocumentAgentTask', () => {
+  it('creates a hidden task in the checkout whose first agent shares its id', () => {
+    install('claude-code', 'codex');
+
+    const task = ensureDocumentAgentTask(project);
+
+    expect(task?.id).toBe(documentAgentTaskId('docs'));
+    expect(store.taskOrder).not.toContain(task?.id);
+    expect(task?.gitIsolation).toBe('none');
+    expect(task?.worktreePath).toBe('/projects/docs');
+    expect(task?.agentIds).toEqual([task?.id]);
+    expect(task?.aiTerminalLayout).toBe('tabs');
+    expect(store.agents[task?.id ?? '']?.def.id).toBe('codex');
+    expect(store.agents[task?.id ?? '']?.attachExisting).toBe(true);
+  });
+
+  it('returns the existing task as it is', () => {
+    install('codex');
+    const task = ensureDocumentAgentTask(project);
+    const id = task?.id ?? '';
+    setStore('agents', id, 'attachExisting', false);
+
+    expect(ensureDocumentAgentTask(project)?.id).toBe(id);
+    expect(store.agents[id]?.attachExisting).toBe(false);
+  });
+
+  it('falls back to an installed agent, and to none when nothing is installed', () => {
+    install('claude-code');
+    expect(store.agents[ensureDocumentAgentTask(project)?.id ?? '']?.def.id).toBe('claude-code');
+
+    setStore({ tasks: {}, agents: {}, availableAgents: [] });
+    expect(ensureDocumentAgentTask(project)).toBeNull();
+  });
+});
+
+describe('rearmDocumentAgents', () => {
+  it('attaches to a live session again after a restart cleared the flag', () => {
+    install('codex');
+    const task = ensureDocumentAgentTask(project);
+    const id = task?.id ?? '';
+    setStore('agents', id, 'attachExisting', false);
+
+    rearmDocumentAgents(store.tasks[id] as Task);
+
+    expect(store.agents[id]?.attachExisting).toBe(true);
+    expect(store.agents[id]?.status).toBe('running');
+  });
+
+  it('resets an agent that exited, since the mount spawns it afresh', () => {
+    install('codex');
+    const task = ensureDocumentAgentTask(project);
+    const id = task?.id ?? '';
+    setStore('agents', id, { status: 'exited', exitCode: 1, lastOutput: ['bye'] });
+
+    rearmDocumentAgents(store.tasks[id] as Task);
+
+    expect(store.agents[id]?.status).toBe('running');
+    expect(store.agents[id]?.exitCode).toBeNull();
+    expect(store.agents[id]?.lastOutput).toEqual([]);
+  });
+});
+
+describe('sendToDocumentAgent', () => {
+  it('queues the prompt for a first agent that is still starting, on the agent tab', async () => {
+    install('codex');
+    setRailTab('runs');
+
+    await sendToDocumentAgent(project, 'Tighten the intro.');
+
+    expect(workspaceUi.railTab).toBe('agent');
+    expect(store.tasks[documentAgentTaskId('docs')]?.initialPrompt).toBe('Tighten the intro.');
+    expect(sendPrompt).not.toHaveBeenCalled();
+  });
+
+  it('types the prompt in when the agent sits at its prompt', async () => {
+    install('codex');
+    const id = ensureDocumentAgentTask(project)?.id ?? '';
+    clearAgentActivity(id);
+
+    await sendToDocumentAgent(project, 'Tighten the intro.');
+
+    expect(sendPrompt).toHaveBeenCalledWith(id, id, 'Tighten the intro.');
+  });
+
+  it('holds the instruction while the hooks say a turn is in flight', async () => {
+    install('codex');
+    const id = ensureDocumentAgentTask(project)?.id ?? '';
+    clearAgentActivity(id);
+    applyAgentHookEvent({
+      agentId: id,
+      taskId: id,
+      at: Date.now(),
+      state: 'working',
+      event: 'PreToolUse',
+    });
+
+    await sendToDocumentAgent(project, 'Tighten the intro.');
+
+    expect(sendPrompt).not.toHaveBeenCalled();
+    expect(store.tasks[id]?.initialPrompt).toBe('Tighten the intro.');
+  });
+
+  it('refuses a second instruction while the first still waits', async () => {
+    install('codex');
+    await sendToDocumentAgent(project, 'Tighten the intro.');
+
+    await expect(sendToDocumentAgent(project, 'Cut the outro.')).rejects.toThrow(
+      'The agent has not taken the previous instruction yet.',
+    );
+    expect(store.tasks[documentAgentTaskId('docs')]?.initialPrompt).toBe('Tighten the intro.');
+  });
+
+  it('refuses when no agent is installed', async () => {
+    setStore({ projects: [project] });
+    await expect(sendToDocumentAgent(project, 'x')).rejects.toThrow('No agent is installed.');
+  });
+});
+
+describe('active task hand-over', () => {
+  it('activates the agent task while the workspace is up and hands back after', () => {
+    install('codex');
+    setStore({ tasks: { t1: codingTask }, taskOrder: ['t1'], activeTaskId: 't1' });
+
+    activateDocumentAgentTask(project);
+    expect(store.activeTaskId).toBe(documentAgentTaskId('docs'));
+
+    releaseDocumentAgentTask('t1');
+    expect(store.activeTaskId).toBe('t1');
+  });
+
+  it('falls back to the first task, or none, when the previous one is gone', () => {
+    install('codex');
+    setStore({ tasks: { t1: codingTask }, taskOrder: ['t1'] });
+    activateDocumentAgentTask(project);
+
+    releaseDocumentAgentTask('gone');
+    expect(store.activeTaskId).toBe('t1');
+
+    activateDocumentAgentTask(project);
+    setStore({
+      tasks: { [documentAgentTaskId('docs')]: store.tasks[documentAgentTaskId('docs')] },
+    });
+    setStore({ taskOrder: [] });
+    releaseDocumentAgentTask('t1');
+    expect(store.activeTaskId).toBeNull();
+  });
+
+  it('leaves a task the user picked meanwhile alone', () => {
+    install('codex');
+    setStore({ tasks: { t1: codingTask }, taskOrder: ['t1'], activeTaskId: 't1' });
+    activateDocumentAgentTask(project);
+    setStore('activeTaskId', 't1');
+
+    releaseDocumentAgentTask(null);
+    expect(store.activeTaskId).toBe('t1');
+  });
+});
+
+describe('disposeDocumentAgentTask', () => {
+  it('kills the sessions, forgets the task and gives up the active slot', async () => {
+    install('codex');
+    activateDocumentAgentTask(project);
+    const id = documentAgentTaskId('docs');
+
+    await disposeDocumentAgentTask('docs');
+
+    expect(invoke).toHaveBeenCalledWith(IPC.KillAgent, { agentId: id });
+    expect(store.tasks[id]).toBeUndefined();
+    expect(store.agents[id]).toBeUndefined();
+    expect(store.activeTaskId).toBeNull();
+  });
+
+  it('does nothing for a project that never had one', async () => {
+    await disposeDocumentAgentTask('docs');
+    expect(invoke).not.toHaveBeenCalledWith(IPC.KillAgent, expect.anything());
+  });
+});
diff --git a/src/documents/agent-task.ts b/src/documents/agent-task.ts
new file mode 100644
index 000000000..530c4f6f8
--- /dev/null
+++ b/src/documents/agent-task.ts
@@ -0,0 +1,152 @@
+/**
+ * The workspace's interactive agent is an ordinary task agent. Each document
+ * project gets a hidden task, kept out of the task order so it never shows in
+ * the sidebar or in the persisted state, and the task terminal, its prompt
+ * box, the last-prompt bar and the agent chips are reused as they are.
+ */
+import { produce } from 'solid-js/store';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { setStore, store } from '../store/core';
+import { effectiveAgentId } from '../store/agent-select';
+import { restartAgent } from '../store/agents';
+import { getAgentHookStatus } from '../store/agentHookStatus';
+import { setActiveTask } from '../store/navigation';
+import { createAgentRecord, forgetTask, sendPrompt, setInitialPrompt } from '../store/tasks';
+import { isAgentAskingQuestion, isAgentIdle, markAgentSpawned } from '../store/taskStatus';
+import type { AgentDef } from '../ipc/types';
+import type { Project, Task } from '../store/types';
+import { documentMainAgentId } from './store';
+import { setRailTab } from './workspace-ui';
+
+const TASK_ID_PREFIX = 'doc-agent-';
+
+/** The hidden task's id, which is also the pty id of its first agent; stable
+ *  so the session is re-attached after the workspace was closed and reopened. */
+export function documentAgentTaskId(projectId: string): string {
+  return `${TASK_ID_PREFIX}${projectId}`;
+}
+
+/** True for a workspace's hidden task: it has no worktree to merge, push or close. */
+export function isDocumentAgentTaskId(id: string | null): boolean {
+  return id?.startsWith(TASK_ID_PREFIX) === true;
+}
+
+function terminalAgentDef(project: Project): AgentDef | undefined {
+  const installed = store.availableAgents.filter((a) => a.available !== false);
+  const wanted = project.documentTerminalAgentId ?? documentMainAgentId(project);
+  return installed.find((a) => a.id === wanted) ?? installed[0];
+}
+
+/** The project's agent task, created on first use. Null while no agent is installed. */
+export function ensureDocumentAgentTask(project: Project): Task | null {
+  const id = documentAgentTaskId(project.id);
+  const existing = store.tasks[id];
+  if (existing) return existing;
+  const def = terminalAgentDef(project);
+  if (!def) return null;
+  const agent = createAgentRecord({ id, taskId: id, def, attachExisting: true });
+  const task: Task = {
+    id,
+    name: project.name,
+    projectId: project.id,
+    gitIsolation: 'none',
+    branchName: '',
+    worktreePath: project.path,
+    agentIds: [id],
+    selectedAgentId: id,
+    // The rail is narrow: two terminals side by side would each get half of it.
+    aiTerminalLayout: 'tabs',
+    shellAgentIds: [],
+    notes: '',
+    lastPrompt: '',
+  };
+  setStore(
+    produce((s) => {
+      s.agents[id] = agent;
+      s.tasks[id] = task;
+    }),
+  );
+  markAgentSpawned(id);
+  return store.tasks[id] ?? null;
+}
+
+/**
+ * Readies the task's agents for a terminal about to mount. A live session is
+ * attached to again: restart and switch clear the flag for the one spawn that
+ * replaces a session, and the next mount must not spawn a second time. A
+ * session that exited is spawned afresh by the mount, so its record is reset
+ * the way a restart resets it, or the exit badge would sit over a live agent.
+ */
+export function rearmDocumentAgents(task: Task): void {
+  for (const id of task.agentIds) {
+    const agent = store.agents[id];
+    if (!agent) continue;
+    if (agent.status === 'exited') restartAgent(id, false);
+    else setStore('agents', id, 'attachExisting', true);
+  }
+}
+
+/**
+ * Hands `text` to the workspace's selected agent, bringing its tab up first.
+ * A first agent that is still booting, busy or asking something gets it
+ * queued: the prompt box sends it once the agent looks idle, as it does for a
+ * new task's initial prompt. Only one instruction can wait. Any other agent
+ * is written to right away, like a typed prompt.
+ */
+export async function sendToDocumentAgent(project: Project, text: string): Promise<void> {
+  const task = ensureDocumentAgentTask(project);
+  const agentId = task ? effectiveAgentId(task) : null;
+  if (!task || !agentId) throw new Error('No agent is installed.');
+  setRailTab('agent');
+  if (looksIdle(agentId) || agentId !== task.agentIds[0]) {
+    await sendPrompt(task.id, agentId, text);
+    return;
+  }
+  if (task.initialPrompt) {
+    throw new Error('The agent has not taken the previous instruction yet.');
+  }
+  setInitialPrompt(task.id, text);
+}
+
+/** Quiet output is the only sign for most agents; Claude's hooks say outright
+ *  whether a turn is in flight or the agent waits on the user. */
+function looksIdle(agentId: string): boolean {
+  const hook = getAgentHookStatus(agentId)?.state;
+  if (hook === 'working' || hook === 'waiting') return false;
+  return isAgentIdle(agentId) && !isAgentAskingQuestion(agentId);
+}
+
+/** Makes the workspace's task the active one so its terminal and prompt box
+ *  take focus and the send-prompt shortcut reaches them. */
+export function activateDocumentAgentTask(project: Project): void {
+  const task = ensureDocumentAgentTask(project);
+  if (task && store.activeTaskId !== task.id) setActiveTask(task.id);
+}
+
+function isOpenPanel(id: string | null): id is string {
+  if (!id || isDocumentAgentTaskId(id)) return false;
+  return store.tasks[id] !== undefined || store.terminals[id] !== undefined;
+}
+
+/** Hands the active task back to `previousId` when the workspace closes, or
+ *  to the first task when that one is gone meanwhile. */
+export function releaseDocumentAgentTask(previousId: string | null): void {
+  if (!isDocumentAgentTaskId(store.activeTaskId)) return;
+  const next = isOpenPanel(previousId) ? previousId : store.taskOrder.find(isOpenPanel);
+  if (next) setActiveTask(next);
+  else setStore({ activeTaskId: null, activeAgentId: null });
+}
+
+/** Ends the project's sessions and forgets the task; for when the project is
+ *  removed, since nothing else would ever kill these ptys. */
+export async function disposeDocumentAgentTask(projectId: string): Promise<void> {
+  const task = store.tasks[documentAgentTaskId(projectId)];
+  if (!task) return;
+  const agentIds = [...task.agentIds];
+  if (store.activeTaskId === task.id) releaseDocumentAgentTask(null);
+  await Promise.allSettled(
+    agentIds.map((id) => invoke(IPC.KillAgent, { agentId: id }).catch(console.error)),
+  );
+  forgetTask(task.id, agentIds);
+}
diff --git a/src/documents/agent-terminal.ts b/src/documents/agent-terminal.ts
deleted file mode 100644
index 528ba442d..000000000
--- a/src/documents/agent-terminal.ts
+++ /dev/null
@@ -1,59 +0,0 @@
-/**
- * Writes to the workspace's interactive agent the way the task prompt box
- * does: focus-in, the text as one bracketed paste, then Enter after the TUI
- * had time to take the paste.
- */
-import { IPC } from '../../electron/ipc/channels';
-import { invoke } from '../lib/ipc';
-import { pasteDelayMs } from '../store/tasks';
-import { setRailTab, workspaceUi } from './workspace-ui';
-
-const BRACKETED_PASTE_START = '\x1b[200~';
-const BRACKETED_PASTE_END = '\x1b[201~';
-const FOCUS_IN = '\x1b[I';
-/** How long to wait for the terminal to come up when it was not mounted yet. */
-const SPAWN_WAIT_MS = 15_000;
-const POLL_MS = 100;
-/** A CLI that just started needs a moment before it takes input. */
-const FRESH_START_DELAY_MS = 2_500;
-
-/** The pty id of a project's interactive agent; stable so the session can be
- *  re-attached after the workspace was closed and reopened. */
-export function documentAgentPtyId(projectId: string): string {
-  return `doc-agent-${projectId}`;
-}
-
-/** The task id the pty is filed under; no task owns it. */
-export function documentAgentTaskId(projectId: string): string {
-  return `doc-agent-${projectId}`;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/** Resolves once the terminal reports a live process, or throws after a wait. */
-async function waitForAgent(): Promise<void> {
-  const wasRunning = workspaceUi.agentRunning;
-  const deadline = Date.now() + SPAWN_WAIT_MS;
-  while (!workspaceUi.agentRunning) {
-    if (Date.now() > deadline) throw new Error('The agent terminal did not start.');
-    await sleep(POLL_MS);
-  }
-  // shortcut: a fixed settle delay for a fresh CLI — the task flow watches
-  // for a stable prompt instead; adopt that if prompts get swallowed.
-  if (!wasRunning) await sleep(FRESH_START_DELAY_MS);
-}
-
-/** Types `text` into the interactive agent, bringing its tab up first. */
-export async function sendToDocumentAgent(ptyId: string, text: string): Promise<void> {
-  setRailTab('agent');
-  await waitForAgent();
-  await invoke(IPC.WriteToAgent, { agentId: ptyId, data: FOCUS_IN });
-  await invoke(IPC.WriteToAgent, {
-    agentId: ptyId,
-    data: `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}`,
-  });
-  await sleep(pasteDelayMs(text));
-  await invoke(IPC.WriteToAgent, { agentId: ptyId, data: '\r' });
-}
diff --git a/src/documents/block-merge.test.ts b/src/documents/block-merge.test.ts
index bc80f2bd6..0f1a94a07 100644
--- a/src/documents/block-merge.test.ts
+++ b/src/documents/block-merge.test.ts
@@ -260,4 +260,25 @@ describe('hunkLabel', () => {
     expect(hunkLabel(parts.hunks[0], parts.baseBlocks)).toBe('Include this removal: “Two.”');
     expect(hunkLabel(parts.hunks[0])).toBe('Include this removal');
   });
+
+  it('tells rewrites and insertions apart by the base lines they land on', async () => {
+    const rewrite = await pair(
+      BASE,
+      ['# Title', '', 'One!', '', 'Two!', '', 'Three.', ''].join('\n'),
+    );
+    expect(hunkLabel(rewrite.hunks[0], rewrite.baseBlocks)).toBe(
+      'Include this rewrite of lines 3–5',
+    );
+    expect(hunkLabel(rewrite.hunks[0])).toBe('Include this rewrite');
+
+    const inserted = await pair(
+      BASE,
+      ['# Title', '', 'Zero.', '', 'One.', '', 'Two.', '', 'Three.', '', 'Four.', ''].join('\n'),
+    );
+    expect(inserted.hunks.map((h) => hunkLabel(h, inserted.baseBlocks))).toEqual([
+      'Include this new passage before line 3',
+      'Include this new passage at the end',
+    ]);
+    expect(hunkLabel(inserted.hunks[0])).toBe('Include this new passage');
+  });
 });
diff --git a/src/documents/block-merge.ts b/src/documents/block-merge.ts
index da461ceae..d77ec1d80 100644
--- a/src/documents/block-merge.ts
+++ b/src/documents/block-merge.ts
@@ -69,16 +69,31 @@ function snippet(text: string): string {
   return text.length > 48 ? `${text.slice(0, 47)}…` : text;
 }
 
+/** "line 4" or "lines 4–9". */
+function lineSpan(from: number, to: number): string {
+  return from === to ? `line ${from}` : `lines ${from}–${to}`;
+}
+
 /**
- * What a toggle does, for its tooltip and screen readers. A deletion names the
- * passage it drops: its checkbox sits on a block that follows it, so without
- * the quote there is nothing on screen tying the two together.
+ * What a toggle does, for its tooltip and screen readers. Each names where it
+ * lands in the base: several toggles share a screen and would otherwise read
+ * alike. A deletion quotes the passage it drops instead, since its checkbox
+ * sits on a block that follows it and nothing on screen ties the two together.
  */
 export function hunkLabel(hunk: BlockHunk, baseBlocks?: readonly DocumentBlock[]): string {
   const kind = hunkKind(hunk);
-  if (kind === 'insertion') return 'Include this new passage';
-  if (kind === 'rewrite') return 'Include this rewrite';
-  const removed = baseBlocks?.[hunk.baseStart] ? key(baseBlocks[hunk.baseStart]) : '';
+  const first = baseBlocks?.[hunk.baseStart];
+  if (kind === 'insertion') {
+    if (first) return `Include this new passage before line ${first.startLine}`;
+    return baseBlocks?.length ? 'Include this new passage at the end' : 'Include this new passage';
+  }
+  if (kind === 'rewrite') {
+    const last = baseBlocks?.[hunk.baseEnd - 1];
+    return first && last
+      ? `Include this rewrite of ${lineSpan(first.startLine, last.endLine)}`
+      : 'Include this rewrite';
+  }
+  const removed = first ? key(first) : '';
   return removed ? `Include this removal: “${snippet(removed)}”` : 'Include this removal';
 }
 
diff --git a/src/documents/documents-styles.test.ts b/src/documents/documents-styles.test.ts
index debdc45a9..47cc3d890 100644
--- a/src/documents/documents-styles.test.ts
+++ b/src/documents/documents-styles.test.ts
@@ -15,10 +15,14 @@ function rule(selector: string): string {
    panel is part of its behaviour: these guard the two rules that make the
    panel reachable with a mouse at all. */
 describe('annotation popover styles', () => {
-  it('hangs the popover straight off the marker, with nothing to cross', () => {
+  it('floats the popover over the window, placed by the marker with nothing to cross', () => {
     const pop = rule('.docws-marker-pop');
 
-    expect(pop).toMatch(/top:\s*100%/);
+    // Fixed, so a page element clipping its overflow cannot trap it; the
+    // marker sets top and right from the symbol's on-screen position.
+    expect(pop).toMatch(/position:\s*fixed/);
+    expect(pop).toMatch(/z-index:\s*var\(--docws-floating-z\)/);
+    expect(pop).not.toMatch(/top:/);
     expect(pop).not.toMatch(/margin-top:/);
   });
 
@@ -40,3 +44,25 @@ describe('annotation popover styles', () => {
     expect(time).toMatch(/text-overflow:\s*ellipsis/);
   });
 });
+
+/* The viewer carries the app's dialog prose classes, and that style has a
+   width cap of its own. Full width is the column's choice, so the cap must
+   not come back through the prose. */
+describe('document width', () => {
+  it('lets the prose fill the column, which alone sets the reading measure', () => {
+    expect(rule('.docws-doc')).toMatch(/max-width:\s*800px/);
+    expect(rule('.docws-doc.is-full-width')).toMatch(/max-width:\s*none/);
+    expect(rule('.docws-doc .docws-content')).toMatch(/max-width:\s*none/);
+  });
+});
+
+describe('rail and toolbar layout', () => {
+  it('keeps the view tabs at the left of the toolbar', () => {
+    expect(rule('.docws-tabs')).toMatch(/margin-left:\s*auto/);
+    expect(rule('.docws-toolbar .docws-tabs')).toMatch(/margin-left:\s*0/);
+  });
+
+  it('hides the agent tab instead of unmounting it', () => {
+    expect(rule('.docws-agent-tab.is-hidden')).toMatch(/display:\s*none/);
+  });
+});
diff --git a/src/documents/documents.css b/src/documents/documents.css
index abfd2f3e0..1bffe4b84 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -1,5 +1,12 @@
 /* Document workspace overlay — uses the app's design tokens. */
 
+:root {
+  /* Overlays that float over the window from an anchor in the document (the
+     block toolbar, an open note): above the workspace (950) and the compare
+     dialog (1000), below the app's menus (1200) and the lightbox (3000). */
+  --docws-floating-z: 1100;
+}
+
 .docws-overlay {
   position: fixed;
   inset: 0;
@@ -37,7 +44,9 @@
 }
 
 /* The mac traffic lights are drawn over the top-left corner of the window;
-   the title moves right so they never sit on it. */
+   the title moves right so they never sit on it. Elsewhere the app draws its
+   own title bar with the window controls, and the overlay starts below it
+   (the pane sets `top`). */
 .docws-overlay.is-mac .docws-header {
   padding-left: 86px;
 }
@@ -48,7 +57,15 @@
   gap: 8px;
   font-weight: 600;
   font-size: 15px;
+}
+
+/* The name gives way first, on one line; the buttons after it keep their
+   place instead of being painted over by the path that follows. */
+.docws-title > span {
   min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .docws-title svg {
@@ -56,6 +73,16 @@
   flex-shrink: 0;
 }
 
+/* In a narrow window the header would push Close out of view: the path and
+   the branch chip go first, since the file tree and the History tab carry
+   the same facts. The overlay spans the window, so its width is the window's. */
+@media (max-width: 960px) {
+  .docws-header .docws-subtitle,
+  .docws-header .docws-head-chip:not(.is-action) {
+    display: none;
+  }
+}
+
 .docws-open-editor {
   padding: 4px;
   flex-shrink: 0;
@@ -96,6 +123,16 @@
   border-color: color-mix(in srgb, var(--warning) 45%, transparent);
 }
 
+/* A chip that does something on a click keeps the chip's look and adds the hand. */
+.docws-head-chip.is-action {
+  background: transparent;
+  cursor: pointer;
+}
+
+.docws-head-chip.is-action:hover {
+  background: color-mix(in srgb, var(--warning) 12%, transparent);
+}
+
 .docws-banner {
   padding: 6px 18px;
   font-size: 12px;
@@ -128,6 +165,7 @@
   font-family: var(--font-ui);
   font-size: 13px;
   cursor: pointer;
+  white-space: nowrap;
 }
 
 /* Tabs select, the composer's target toggle checks; both read the same way. */
@@ -188,6 +226,13 @@
   background: var(--accent-hover);
 }
 
+/* Dimming the accent alone still reads as a live button; take the colour away. */
+.docws-btn-primary:disabled {
+  background: var(--bg-hover);
+  border-color: var(--border);
+  color: var(--fg-muted);
+}
+
 .docws-btn-danger {
   color: var(--error);
 }
@@ -242,37 +287,31 @@
 
 .docws-count.is-attention {
   background: var(--warning);
-  color: var(--bg);
+  /* Not `--bg`: it is a gradient in the default look, so the colour would
+     be dropped and the mark inherit the muted grey around it. */
+  color: var(--bg-elevated);
 }
 
 /* ── Interactive agent ── */
 
-.docws-agent-pane {
+/* Kept mounted behind the other tabs: a remount replays the whole scrollback
+   from the pty and loses the scroll position. */
+.docws-agent-tab {
   flex: 1;
   min-height: 0;
   display: flex;
   flex-direction: column;
 }
 
-.docws-agent-head {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 12px;
-  border-bottom: 1px solid var(--border);
-  font-size: 12px;
-  color: var(--fg-muted);
-}
-
-.docws-agent-status {
-  font-family: var(--font-mono);
-  font-size: 11px;
-  color: var(--fg-subtle);
+.docws-agent-tab.is-hidden {
+  display: none;
 }
 
-.docws-agent-status.is-waiting {
-  color: var(--warning);
-  font-weight: 600;
+.docws-agent-pane {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
 }
 
 .docws-agent-term {
@@ -282,6 +321,13 @@
   background: var(--bg);
 }
 
+.docws-agent-prompt {
+  flex: none;
+  height: 96px;
+  padding: 6px 8px 8px;
+  border-top: 1px solid var(--border);
+}
+
 .docws-decisions {
   display: flex;
   flex-direction: column;
@@ -410,6 +456,19 @@
   padding: 28px 44px 280px;
 }
 
+/* Full width is a choice, remembered across workspaces: wide tables and
+   diagrams get the whole column instead of a reading measure. */
+.docws-doc.is-full-width {
+  max-width: none;
+}
+
+/* The shared dialog prose style caps itself at 720px, which is hidden inside
+   the reading measure but would hold the prose there under full width. The
+   column above sets the width; the prose fills it. */
+.docws-doc .docws-content {
+  max-width: none;
+}
+
 /* A page gets the whole column, top to bottom, the way a browser gives it the viewport. */
 .docws-doc.is-page {
   display: flex;
@@ -620,15 +679,16 @@
 
 /* ── Block hover toolbar ── */
 
-/* Clear of the block, not on its top edge: the bar used to cover the first
-   line, so a click meant for the passage hit an icon instead. It rests in the
-   gap above, which the column's top padding leaves room for on the first
-   block too. */
+/* One bar for the whole viewer, floating over the window: the viewer places
+   it so its bottom edge meets the hovered block's top edge, clear of the
+   prose (a bar on the first line made clicks meant for the passage hit an
+   icon) and outside any page element that clips its overflow. Hidden, it is
+   also unfocusable and intangible, so it never swallows a click meant for
+   whatever is under it. */
 .docws-block-actions {
-  position: absolute;
-  bottom: 100%;
-  right: 6px;
-  z-index: 5;
+  position: fixed;
+  z-index: var(--docws-floating-z);
+  transform: translateY(-100%);
   display: inline-flex;
   gap: 2px;
   padding: 2px;
@@ -636,35 +696,22 @@
   border: 1px solid var(--border);
   background: var(--bg-elevated);
   box-shadow: var(--shadow-pop);
+  font-family: var(--font-ui);
+  visibility: hidden;
   opacity: 0;
-  transition: opacity 0.1s ease;
-  /* Invisible, so it must also be intangible: it hangs over the block above,
-     where a transparent icon would otherwise swallow that block's clicks. */
-  pointer-events: none;
+  transition:
+    opacity 0.1s ease,
+    visibility 0s linear 0.1s;
 }
 
 /* A beat after the pointer arrives, so sweeping down the prose does not flash
-   a toolbar on every block; gone at once when it leaves. The bar sits directly
-   on the block's top edge, so the pointer reaches it without crossing a gap. */
-.doc-block:hover .docws-block-actions,
-.docws-block-actions:focus-within {
+   the bar on every block; gone at once when it leaves. */
+.docws-block-actions.is-open {
+  visibility: visible;
   opacity: 1;
-  pointer-events: auto;
-  transition-delay: 0.12s;
-}
-
-/* The picked blocks have the composer up on them; their toolbars would only
-   repeat what it offers. The other blocks keep theirs, so one click moves
-   the composer to a different block. */
-.doc-block.is-selected .docws-block-actions {
-  display: none;
-}
-
-/* A page's § button and markers sit on the right; the toolbar takes the left. */
-.docws-page .docws-block-actions {
-  right: auto;
-  left: 0;
-  font-family: var(--font-ui);
+  transition:
+    opacity 0.1s ease 0.12s,
+    visibility 0s;
 }
 
 .docws-block-action {
@@ -799,6 +846,21 @@
   color: var(--fg-muted);
 }
 
+/* The view tabs lead the toolbar and must not drift with what shows on the
+   right; Full width goes away in the page view. */
+.docws-toolbar .docws-tabs {
+  margin-left: 0;
+}
+
+/* The hint is the one thing in the toolbar that can give way: on one line,
+   cut short, so the buttons keep their row in a narrow column. */
+.docws-toolbar-label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 /* ── Composer ── */
 
 /* The composer floats over the foot of the column. Only the panel itself takes
@@ -847,7 +909,7 @@
 /* Always present, so it steps back while the reader is in the prose and
    comes forward as soon as the pointer or the cursor reaches it. */
 .docws-composer:not(:focus-within):not(:hover):not(.is-fresh) {
-  opacity: 0.55;
+  opacity: 0.8;
   border-color: var(--border);
 }
 
@@ -927,6 +989,49 @@
   border-color: var(--border-focus);
 }
 
+.docws-composer textarea:focus-visible {
+  box-shadow: 0 0 0 2.5px color-mix(in srgb, var(--border-focus) 38%, transparent);
+}
+
+/* The proposals panel: the agents up front, tuning folded away below. */
+.docws-proposal-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 12px;
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius-md);
+  background: color-mix(in srgb, var(--bg-input) 60%, transparent);
+}
+
+.docws-proposal-head {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--fg-subtle);
+}
+
+.docws-proposal-count {
+  flex: none;
+  font-weight: 600;
+  color: var(--fg);
+}
+
+.docws-proposal-count.is-over {
+  color: var(--warning);
+}
+
+.docws-agent-pick.is-on .docws-count-btn {
+  border-color: color-mix(in srgb, var(--accent) 50%, var(--border));
+}
+
+.docws-toolbar-task {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+}
+
 .docws-proposal-options {
   font-size: 12px;
   color: var(--fg-muted);
@@ -1054,8 +1159,9 @@
 
 .docws-composer-footer {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
-  gap: 10px;
+  gap: 6px 10px;
   font-size: 12px;
   color: var(--fg-subtle);
 }
@@ -1099,6 +1205,10 @@
   border-color: var(--border-focus);
 }
 
+.docws-model-input:focus-visible {
+  box-shadow: 0 0 0 2.5px color-mix(in srgb, var(--border-focus) 38%, transparent);
+}
+
 /* Pushes what follows to the far end of its row. Every use is inside a flex
    row, so this holds wherever the class is put. */
 .docws-spacer {
@@ -1341,8 +1451,8 @@
   min-height: 0;
 }
 
-/* The compare modal: a head with the run picker and the size toggle, and the
-   compare view filling the rest. */
+/* The compare modal: a head with the run picker, and the compare view
+   filling the rest of the window. */
 .docws-compare-dialog {
   flex: 1;
   min-height: 0;
@@ -1356,6 +1466,14 @@
   gap: 10px;
   padding: 10px 14px;
   border-bottom: 1px solid var(--border);
+  user-select: none;
+}
+
+/* The head is the window drag region while the view fills the window; on
+   macOS the traffic lights sit in its top-left corner, so it starts to their
+   right, as the workspace header does. */
+.docws-compare-dialog.is-mac .docws-compare-dialog-head {
+  padding-left: 86px;
 }
 
 .docws-compare-dialog-body {
@@ -1483,6 +1601,12 @@
   min-height: 30px;
 }
 
+.docws-note:focus-visible {
+  outline: none;
+  border-color: var(--border-focus);
+  box-shadow: 0 0 0 2.5px color-mix(in srgb, var(--border-focus) 38%, transparent);
+}
+
 .docws-column-body {
   flex: 1;
   min-height: 0;
@@ -1539,8 +1663,8 @@
 }
 
 .docws-history-list {
-  width: 360px;
-  flex-shrink: 0;
+  flex: 0 1 360px;
+  min-width: 220px;
   border-right: 1px solid var(--border);
   overflow-y: auto;
   display: flex;
@@ -1714,6 +1838,8 @@
 
 .docws-bubble:focus-visible {
   border-color: var(--border-focus);
+  outline: 2px solid var(--border-focus);
+  outline-offset: 2px;
 }
 
 .docws-bubble.is-resolved {
@@ -1828,8 +1954,8 @@
 }
 
 .docws-content:not(.docws-page) .docws-marker {
-  top: 0.2em;
-  right: -28px;
+  top: 0.1em;
+  right: -34px;
 }
 
 /* On a page the marker sits inside the block, like the § button: the page's
@@ -1859,7 +1985,7 @@
   display: inline-flex;
   align-items: center;
   gap: 3px;
-  padding: 2px 4px;
+  padding: 3px 5px;
   border: 1px solid var(--border);
   border-radius: var(--radius-xs);
   background: var(--bg-elevated);
@@ -1868,18 +1994,17 @@
   cursor: pointer;
 }
 
-/* An open marker paints over its neighbours, so the bubble is never covered by
-   the symbol of a passage further down. */
-.docws-marker:hover,
-.docws-marker:focus-within,
-.docws-marker.is-pinned {
-  z-index: 20;
-}
-
 .docws-marker.is-question .docws-marker-btn {
   color: var(--info);
 }
 
+/* The wait for an answer is read from the margin, so the spinner is the
+   glyph's size rather than the inline default. */
+.docws-marker-btn .inline-spinner {
+  width: 16px;
+  height: 16px;
+}
+
 .docws-marker-btn:hover,
 .docws-marker.is-pinned .docws-marker-btn {
   border-color: var(--border-focus);
@@ -1891,13 +2016,14 @@
   color: var(--fg-muted);
 }
 
-/* Flush under the symbol, and held for a beat once the pointer leaves: a gap
-   below the symbol drops the hover on the way down, and an instant close does
-   the same to a pointer that cuts the corner on its way in. */
+/* The marker places it flush under the symbol and keeps it inside the window;
+   it floats over everything in the workspace, out of the block, so a page's
+   own CSS cannot clip it and the composer cannot cover it. Held for a beat
+   once the pointer leaves, so a pointer that cuts the corner on its way in
+   does not lose it. It lives in the body, so it carries its own type. */
 .docws-marker-pop {
-  position: absolute;
-  top: 100%;
-  right: 0;
+  position: fixed;
+  z-index: var(--docws-floating-z);
   width: min(440px, calc(100vw - 64px));
   max-height: 60vh;
   overflow-y: auto;
@@ -1906,6 +2032,10 @@
   border-radius: var(--radius-md);
   background: var(--island-bg);
   box-shadow: var(--shadow-pop);
+  font-family: var(--font-ui);
+  color: var(--fg);
+  line-height: 1.5;
+  text-align: left;
   visibility: hidden;
   opacity: 0;
   transition:
@@ -1913,9 +2043,7 @@
     visibility 0s linear 0.15s;
 }
 
-.docws-marker:hover > .docws-marker-pop,
-.docws-marker:focus-within > .docws-marker-pop,
-.docws-marker.is-pinned > .docws-marker-pop {
+.docws-marker-pop.is-open {
   visibility: visible;
   opacity: 1;
   transition:
@@ -1961,10 +2089,16 @@
   border: 1px solid var(--border);
   border-radius: var(--radius-sm);
   padding: 2px;
+  /* A narrow column scrolls the strip rather than wrapping a label onto
+     three lines; the scope text beside it has already given way. */
+  min-width: 0;
+  overflow-x: auto;
+  scrollbar-width: none;
 }
 
 .docws-mode-tabs .docws-tab {
   display: inline-flex;
+  flex: none;
   align-items: center;
   gap: 5px;
   padding: 3px 10px;
@@ -2015,3 +2149,151 @@
   outline-color: var(--border);
   opacity: 0.5;
 }
+
+.docws-run-lineage {
+  font-style: italic;
+}
+
+.docws-merge-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 18px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+}
+
+.docws-merge-panel p {
+  margin: 0;
+  color: var(--fg-muted);
+  line-height: 1.5;
+}
+
+.docws-merge-panel textarea {
+  min-height: 64px;
+}
+
+.docws-merge-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px 14px;
+  align-items: center;
+}
+
+.docws-bubble-followup {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  margin-top: 6px;
+}
+
+.docws-bubble-followup textarea {
+  min-height: 56px;
+}
+
+/* Keep the original and the selected proposal readable without horizontal
+   scrolling. Explicit widths belong to the optional all-proposals layout. */
+.docws-columns.is-focused {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  grid-template-rows: auto minmax(0, 1fr) auto;
+}
+
+.docws-columns.is-focused > .docws-column {
+  display: grid;
+  grid-row: 1 / -1;
+  grid-template-rows: subgrid;
+  min-width: 0;
+  max-width: none;
+}
+
+.docws-columns > .docws-column[hidden] {
+  display: none;
+}
+
+.docws-proposal-switcher {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 8px 14px;
+  border-bottom: 1px solid var(--border);
+}
+
+.docws-proposal-switcher .docws-tabs {
+  min-width: 0;
+  overflow-x: auto;
+}
+
+.docws-proposal-switcher button {
+  flex-shrink: 0;
+}
+
+.docws-column-head {
+  min-height: 0;
+  max-height: 35vh;
+  overflow-y: auto;
+}
+
+.docws-column-actions {
+  flex-shrink: 0;
+  padding: 10px 14px;
+  border-top: 1px solid var(--border);
+  background: var(--bg);
+}
+
+.docws-column-actions .docws-run-actions {
+  justify-content: flex-end;
+}
+
+.docws-column-head .docws-rationale {
+  flex-shrink: 0;
+  max-height: none;
+  overflow: visible;
+}
+
+.docws-column-head .docws-rationale-summary {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.docws-review-details > summary {
+  cursor: pointer;
+  color: var(--fg-muted);
+}
+
+.docws-review-details-body {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-top: 8px;
+}
+
+.docws-review-details-body p {
+  margin: 0;
+}
+
+.docws-candidate-main {
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.docws-candidate-main:hover {
+  color: var(--accent);
+}
+
+.docws-candidate > .docws-btn {
+  margin-top: 6px;
+}
+
+.doc-block[hidden] {
+  display: none;
+}
diff --git a/src/documents/interactive-prompt.test.ts b/src/documents/interactive-prompt.test.ts
index 599f5b869..65c8c4285 100644
--- a/src/documents/interactive-prompt.test.ts
+++ b/src/documents/interactive-prompt.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { buildInteractivePrompt } from './interactive-prompt';
 
 describe('buildInteractivePrompt', () => {
-  it('names the document, the lines and the passage before the instruction', () => {
+  it('puts the instruction first, then the document, the lines and the passage', () => {
     const prompt = buildInteractivePrompt(
       'notes.md',
       {
@@ -17,8 +17,8 @@ describe('buildInteractivePrompt', () => {
       '  Tighten this.  ',
     );
     expect(prompt).toBe(
-      'Document: notes.md\n\nScope: lines 4-6 (under "Plan").\n\n' +
-        'The passage, verbatim:\n> One.\n> Two.\n\nTighten this.',
+      'Tighten this.\n\nDocument: notes.md\n\nScope: lines 4-6 (under "Plan").\n\n' +
+        'The passage, verbatim:\n> One.\n> Two.',
     );
   });
 
@@ -35,7 +35,7 @@ describe('buildInteractivePrompt', () => {
       },
       'Rewrite the intro.',
     );
-    expect(prompt).toBe('Document: notes.md\n\nScope: the whole document.\n\nRewrite the intro.');
+    expect(prompt).toBe('Rewrite the intro.\n\nDocument: notes.md\n\nScope: the whole document.');
   });
 
   it('drops the control characters a pasted passage would turn into keystrokes', () => {
diff --git a/src/documents/interactive-prompt.ts b/src/documents/interactive-prompt.ts
index c0fce0d37..842ae5e16 100644
--- a/src/documents/interactive-prompt.ts
+++ b/src/documents/interactive-prompt.ts
@@ -3,7 +3,9 @@ import type { DocumentSelection } from './store';
 /**
  * The message typed into the interactive session for a scoped instruction.
  * That session runs in the checkout with the user watching, so it is asked to
- * edit directly and told where; the rest is the user's own words.
+ * edit directly and told where. The user's own words come first: the bar over
+ * the terminal shows the start of the last prompt, and it should read them,
+ * not the scaffolding.
  */
 export function buildInteractivePrompt(
   documentPath: string,
@@ -15,7 +17,7 @@ export function buildInteractivePrompt(
     : selection.heading
       ? `lines ${selection.startLine}-${selection.endLine} (under "${selection.heading}")`
       : `lines ${selection.startLine}-${selection.endLine}`;
-  const parts = [`Document: ${documentPath}`, `Scope: ${where}.`];
+  const parts = [instruction.trim(), `Document: ${documentPath}`, `Scope: ${where}.`];
   if (!selection.wholeDocument && selection.quote.trim()) {
     const quote = selection.quote
       .split('\n')
@@ -23,7 +25,6 @@ export function buildInteractivePrompt(
       .join('\n');
     parts.push(`The passage, verbatim:\n${quote}`);
   }
-  parts.push(instruction.trim());
   return plainText(parts.join('\n\n'));
 }
 
diff --git a/src/documents/store.trail.client.test.tsx b/src/documents/store.trail.client.test.tsx
new file mode 100644
index 000000000..d8ecca52c
--- /dev/null
+++ b/src/documents/store.trail.client.test.tsx
@@ -0,0 +1,108 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { IPC } from '../../electron/ipc/channels';
+import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+import {
+  closeDocumentWorkspace,
+  documentStore,
+  goBackDocument,
+  openDocumentFile,
+  openDocumentWorkspace,
+  previousDocumentPath,
+} from './store';
+
+const { invoke } = vi.hoisted(() => ({ invoke: vi.fn() }));
+vi.mock('../lib/ipc', () => ({
+  invoke,
+  Channel: class {
+    dispose() {}
+  },
+}));
+vi.mock('../lib/shell', () => ({ openInEditor: vi.fn(), revealItemInDir: vi.fn() }));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  closeDocumentWorkspace();
+  setStore({ projects: [], activeDocumentProjectId: null, documentWorkspacesEnabled: false });
+  vi.clearAllMocks();
+});
+
+async function openWorkspace(): Promise<void> {
+  invoke.mockImplementation(async (channel: string) =>
+    channel === IPC.ReadDocument
+      ? { content: '# Doc\n', headSha: 'abc1234', branch: 'main', dirty: false, missing: false }
+      : [],
+  );
+  setStore({
+    documentWorkspacesEnabled: true,
+    projects: [
+      {
+        id: 'docs',
+        name: 'Release notes',
+        path: '/projects/release',
+        color: '',
+        kind: 'document',
+        documentPath: 'notes.md',
+      },
+    ],
+  });
+  await openDocumentWorkspace('docs');
+}
+
+function backButton(host: HTMLElement): HTMLButtonElement | null {
+  return (
+    Array.from(host.querySelectorAll('button')).find((b) => b.textContent?.trim() === '← Back') ??
+    null
+  );
+}
+
+describe('document trail', () => {
+  it('remembers the document a link left and returns to it', async () => {
+    await openWorkspace();
+    expect(previousDocumentPath()).toBeNull();
+
+    await openDocumentFile('notes/invoice.md');
+    expect(documentStore.documentPath).toBe('notes/invoice.md');
+    expect(previousDocumentPath()).toBe('notes.md');
+
+    await openDocumentFile('notes/invoice.md');
+    expect(previousDocumentPath()).toBe('notes.md');
+
+    await goBackDocument();
+    expect(documentStore.documentPath).toBe('notes.md');
+    expect(previousDocumentPath()).toBeNull();
+
+    await goBackDocument();
+    expect(documentStore.documentPath).toBe('notes.md');
+  });
+
+  it('starts every workspace with an empty trail', async () => {
+    await openWorkspace();
+    await openDocumentFile('notes/invoice.md');
+    closeDocumentWorkspace();
+    expect(previousDocumentPath()).toBeNull();
+
+    await openWorkspace();
+    expect(previousDocumentPath()).toBeNull();
+  });
+
+  it('offers a Back button in the header once a link has been followed', async () => {
+    await openWorkspace();
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+    expect(backButton(host)).toBeNull();
+
+    await openDocumentFile('notes/invoice.md');
+    const back = backButton(host);
+    expect(back?.title).toBe('Back to notes.md');
+
+    back?.click();
+    await vi.waitFor(() => expect(documentStore.documentPath).toBe('notes.md'));
+    expect(backButton(host)).toBeNull();
+  });
+});
diff --git a/src/documents/store.ts b/src/documents/store.ts
index 2fe7a5105..59db0c1e5 100644
--- a/src/documents/store.ts
+++ b/src/documents/store.ts
@@ -60,6 +60,8 @@ interface DocumentWorkspaceState {
   /** Repo-relative path of the document on screen; the project's document
    *  until a link or the file tree opens another. */
   documentPath: string | null;
+  /** Documents left behind by links and file picks, oldest first; Back walks it. */
+  documentTrail: string[];
   annotations: DocumentAnnotation[];
   /** Last deleted bubble, kept for a single-step undo. */
   lastDeleted: DocumentAnnotation | null;
@@ -74,15 +76,19 @@ interface DocumentWorkspaceState {
   logs: Record<string, string[]>;
   view: DocumentView;
   compareRunId: string | null;
+  compareCandidateId: string | null;
   selection: DocumentSelection | null;
   dispatching: boolean;
 }
 
 const MAX_LOG_LINES = 400;
+/** Deeper than anyone follows links; keeps a long session from growing the trail forever. */
+const MAX_TRAIL = 20;
 
 const [docStore, setDocStore] = createStore<DocumentWorkspaceState>({
   projectId: null,
   documentPath: null,
+  documentTrail: [],
   annotations: [],
   lastDeleted: null,
   showResolved: false,
@@ -95,6 +101,7 @@ const [docStore, setDocStore] = createStore<DocumentWorkspaceState>({
   logs: {},
   view: 'document',
   compareRunId: null,
+  compareCandidateId: null,
   selection: null,
   dispatching: false,
 });
@@ -202,6 +209,7 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
   setDocStore({
     projectId,
     documentPath: project.documentPath,
+    documentTrail: [],
     snapshot: null,
     loading: true,
     error: null,
@@ -210,6 +218,7 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
     logs: {},
     view: 'document',
     compareRunId: null,
+    compareCandidateId: null,
     selection: null,
     annotations: [],
     lastDeleted: null,
@@ -224,14 +233,43 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
 
 /**
  * Shows another file of the open project: the target of an internal link or a
- * pick in the file tree. The selection belongs to the old document and goes;
- * runs and annotations are per project and stay.
+ * pick in the file tree. The document left goes on the trail for Back.
  */
 export async function openDocumentFile(documentPath: string): Promise<void> {
+  const from = docStore.documentPath;
+  if (!from || from === documentPath) return;
+  await showDocument(documentPath, [...docStore.documentTrail, from].slice(-MAX_TRAIL));
+}
+
+/** The document Back returns to, or null at the start of the trail. */
+export function previousDocumentPath(): string | null {
+  const trail = docStore.documentTrail;
+  return trail.length > 0 ? trail[trail.length - 1] : null;
+}
+
+/** Returns to the document left last; nothing happens at the start of the trail. */
+export async function goBackDocument(): Promise<void> {
+  const previous = previousDocumentPath();
+  if (previous === null) return;
+  await showDocument(previous, docStore.documentTrail.slice(0, -1));
+}
+
+/**
+ * Switches the workspace to a file of the open project. The selection belongs
+ * to the old document and goes; runs and annotations are per project and stay.
+ */
+async function showDocument(documentPath: string, documentTrail: string[]): Promise<void> {
   const project = activeProject();
-  if (!project || docStore.documentPath === documentPath) return;
+  if (!project) return;
   stopCurrentWatcher();
-  setDocStore({ documentPath, selection: null, composerDraft: null, snapshot: null, error: null });
+  setDocStore({
+    documentPath,
+    documentTrail,
+    selection: null,
+    composerDraft: null,
+    snapshot: null,
+    error: null,
+  });
   startWatcher(project.id, project.path, documentPath);
   await refreshDocumentSnapshot();
 }
@@ -241,9 +279,11 @@ export function closeDocumentWorkspace(): void {
   setDocStore({
     projectId: null,
     documentPath: null,
+    documentTrail: [],
     selection: null,
     view: 'document',
     compareRunId: null,
+    compareCandidateId: null,
     composerDraft: null,
   });
   setStore('activeDocumentProjectId', null);
@@ -262,12 +302,12 @@ export function setDocumentSelection(selection: DocumentSelection | null): void
 }
 
 /** Opens the compare view, a modal over whatever tab is up. */
-export function openDocumentCompare(runId: string): void {
-  setDocStore('compareRunId', runId);
+export function openDocumentCompare(runId: string, candidateId?: string): void {
+  setDocStore({ compareRunId: runId, compareCandidateId: candidateId ?? null });
 }
 
 export function closeDocumentCompare(): void {
-  setDocStore('compareRunId', null);
+  setDocStore({ compareRunId: null, compareCandidateId: null });
 }
 
 /** Runs with at least one proposal to look at. */
@@ -533,13 +573,30 @@ export async function acceptDocumentCandidate(
     showNotification(
       partial ? `Accepted ${partial.accepted} of ${partial.total} changes` : 'Proposal accepted',
     );
-    setDocStore('compareRunId', null);
+    setDocStore({ compareRunId: null, compareCandidateId: null });
   } catch (err) {
     showNotification(errMessage(err));
   }
   await Promise.all([loadDocumentRuns(), refreshDocumentSnapshot()]);
 }
 
+/**
+ * One throwaway candidate for a run that starts from proposals rather than
+ * the canonical document: the warm main session must not be moved onto
+ * unaccepted content, so it is never resumed here.
+ */
+function oneShotSpecs(
+  project: Project,
+  agent: AgentDef,
+  choice: DocumentModelChoice,
+): DocumentCandidateSpec[] {
+  return buildCandidateSpecs(
+    project,
+    [{ agent, count: 1, choices: [choice] }],
+    store.agentEnvFiles,
+  ).map((spec) => ({ ...spec, isMain: false, sessionId: undefined, sessionLastSha: undefined }));
+}
+
 export async function refineDocumentCandidate(
   run: DocumentRunRecord,
   candidate: DocumentCandidateRecord,
@@ -550,34 +607,43 @@ export async function refineDocumentCandidate(
     (a) => a.id === candidate.agentId && a.available !== false,
   );
   if (!agent) throw new Error('Install or enable this candidate’s agent to refine it.');
-  const candidates = buildCandidateSpecs(
-    project,
-    [
-      {
-        agent,
-        count: 1,
-        choices: [{ model: candidate.model, effort: candidate.effort }],
-      },
-    ],
-    store.agentEnvFiles,
-  ).map((spec) => ({
-    ...spec,
-    isMain: false,
-    sessionId: undefined,
-    sessionLastSha: undefined,
-  }));
   const revision = await invoke<DocumentRunRecord>(IPC.DispatchDocumentRun, {
     projectRoot: project.path,
     documentPath: run.documentPath,
     instruction,
     scope: { wholeDocument: true },
-    candidates,
+    candidates: oneShotSpecs(project, agent, { model: candidate.model, effort: candidate.effort }),
     refinement: { runId: run.id, candidateId: candidate.id },
   });
   if (stillOpen(project.id)) upsertRun(revision);
   showNotification('Refinement started. The new proposal will appear in Runs.');
 }
 
+export interface MergeRequest {
+  run: DocumentRunRecord;
+  candidateIds: readonly string[];
+  /** Guidance for the merging agent, on top of the built-in merge instructions. */
+  instruction: string;
+  agent: AgentDef;
+  choice: DocumentModelChoice;
+}
+
+/** Asks one agent to fold several proposals of `run` into a single new proposal. */
+export async function mergeDocumentCandidates(request: MergeRequest): Promise<void> {
+  const { project } = requireProject();
+  const { run, candidateIds, instruction, agent, choice } = request;
+  const merged = await invoke<DocumentRunRecord>(IPC.DispatchDocumentRun, {
+    projectRoot: project.path,
+    documentPath: run.documentPath,
+    instruction,
+    scope: { wholeDocument: true },
+    candidates: oneShotSpecs(project, agent, choice),
+    merge: { runId: run.id, candidateIds: [...candidateIds] },
+  });
+  if (stillOpen(project.id)) upsertRun(merged);
+  showNotification('Merge started. The merged proposal will appear in Runs.');
+}
+
 export async function rejectDocumentRun(runId: string): Promise<void> {
   const { project } = requireProject();
   try {
@@ -586,7 +652,8 @@ export async function rejectDocumentRun(runId: string): Promise<void> {
       runId,
     });
     upsertRun(run);
-    if (docStore.compareRunId === runId) setDocStore('compareRunId', null);
+    if (docStore.compareRunId === runId)
+      setDocStore({ compareRunId: null, compareCandidateId: null });
   } catch (err) {
     showNotification(errMessage(err));
   }
@@ -629,6 +696,20 @@ export async function revertDocumentCommit(sha: string): Promise<boolean> {
   }
 }
 
+/** Drops the uncommitted edits to tracked files; the document goes back to HEAD. */
+export async function discardDocumentEdits(): Promise<boolean> {
+  const { project } = requireProject();
+  try {
+    await invoke(IPC.DiscardDocumentEdits, { projectRoot: project.path });
+    showNotification('Uncommitted edits discarded');
+    void refreshDocumentSnapshot();
+    return true;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return false;
+  }
+}
+
 // --- Annotations ----------------------------------------------------------
 
 export async function loadDocumentAnnotations(): Promise<void> {
@@ -664,12 +745,19 @@ async function persistAnnotation(annotation: DocumentAnnotation): Promise<Docume
   return saved;
 }
 
+export interface AddAnnotationOptions {
+  /** Agent that answers a question right away; a question without one waits. */
+  askWith?: AgentDef;
+  /** Answered question this one continues; its exchange goes into the prompt. */
+  followUpOf?: string;
+}
+
 /** Creates a note or a question on the anchored passage. Questions are asked right away. */
 export async function addDocumentAnnotation(
   kind: DocumentAnnotationKind,
   text: string,
   anchor: DocumentAnchor,
-  askWith?: AgentDef,
+  options: AddAnnotationOptions = {},
 ): Promise<DocumentAnnotation | null> {
   const now = new Date().toISOString();
   try {
@@ -681,8 +769,10 @@ export async function addDocumentAnnotation(
       createdAt: now,
       updatedAt: now,
       resolved: false,
+      followUpOf: options.followUpOf,
     });
-    if (kind === 'question' && askWith) await askDocumentAnnotation(saved.id, askWith);
+    if (kind === 'question' && options.askWith)
+      await askDocumentAnnotation(saved.id, options.askWith);
     return saved;
   } catch (err) {
     showNotification(errMessage(err));
@@ -690,6 +780,18 @@ export async function addDocumentAnnotation(
   }
 }
 
+/** Continues an answered question on the same passage; the agent sees the earlier exchange. */
+export async function askFollowUpQuestion(
+  parent: DocumentAnnotation,
+  text: string,
+  agent: AgentDef,
+): Promise<DocumentAnnotation | null> {
+  return addDocumentAnnotation('question', text, parent.anchor, {
+    askWith: agent,
+    followUpOf: parent.id,
+  });
+}
+
 export async function askDocumentAnnotation(annotationId: string, agent: AgentDef): Promise<void> {
   const { project } = requireProject();
   const current = docStore.annotations.find((a) => a.id === annotationId);
diff --git a/src/documents/workspace-ui.ts b/src/documents/workspace-ui.ts
index f8197f0d3..473f91749 100644
--- a/src/documents/workspace-ui.ts
+++ b/src/documents/workspace-ui.ts
@@ -1,8 +1,7 @@
 /**
  * Panel state of the open workspace: the project's files, which rail tab is
- * up, the one-shot output being read, and whether the interactive agent is
- * live. Kept apart from the document store because none of it is about the
- * document.
+ * up and the one-shot output being read. Kept apart from the document store
+ * because none of it is about the document.
  */
 import { createStore } from 'solid-js/store';
 import { IPC } from '../../electron/ipc/channels';
@@ -22,8 +21,6 @@ interface WorkspaceUiState {
   filesError: string | null;
   railTab: RailTab;
   output: OutputTarget | null;
-  /** Set once the interactive agent's terminal has a live process behind it. */
-  agentRunning: boolean;
 }
 
 const [ui, setUi] = createStore<WorkspaceUiState>({
@@ -31,7 +28,6 @@ const [ui, setUi] = createStore<WorkspaceUiState>({
   filesError: null,
   railTab: 'agent',
   output: null,
-  agentRunning: false,
 });
 
 export { ui as workspaceUi };
@@ -53,11 +49,52 @@ export function openCandidateOutput(target: OutputTarget | null): void {
   setUi('output', target);
 }
 
-export function setAgentRunning(running: boolean): void {
-  setUi('agentRunning', running);
-}
-
 /** Back to the defaults when a workspace opens; files are per project. */
 export function resetWorkspaceUi(): void {
-  setUi({ files: [], filesError: null, railTab: 'agent', output: null, agentRunning: false });
+  setUi({ files: [], filesError: null, railTab: 'agent', output: null });
+}
+
+/**
+ * The note bubbles pinned open right now, by what closes them. A pinned
+ * bubble covers the prose, so Escape shuts it before anything else in the
+ * workspace — even with the focus nowhere near it, where the bubble's own
+ * key handler cannot see the key.
+ */
+const pinnedBubbles = new Set<() => void>();
+
+export function registerPinnedBubble(dismiss: () => void): () => void {
+  pinnedBubbles.add(dismiss);
+  return () => {
+    pinnedBubbles.delete(dismiss);
+  };
+}
+
+/** Closes every pinned bubble; false when there was none to close. */
+export function dismissPinnedBubbles(): boolean {
+  if (pinnedBubbles.size === 0) return false;
+  for (const dismiss of [...pinnedBubbles]) dismiss();
+  return true;
+}
+
+/**
+ * The forms open over the compare view (refine, merge), by what closes them.
+ * Escape shuts the one opened last before the dialog itself, even with the
+ * focus outside the form, where its own key handler cannot see the key.
+ */
+const compareForms: (() => void)[] = [];
+
+export function registerCompareForm(close: () => void): () => void {
+  compareForms.push(close);
+  return () => {
+    const at = compareForms.indexOf(close);
+    if (at >= 0) compareForms.splice(at, 1);
+  };
+}
+
+/** Closes the form opened last; false when none is open. */
+export function closeTopCompareForm(): boolean {
+  const close = compareForms.pop();
+  if (!close) return false;
+  close();
+  return true;
 }
diff --git a/src/lib/floating.test.ts b/src/lib/floating.test.ts
new file mode 100644
index 000000000..02b2e7289
--- /dev/null
+++ b/src/lib/floating.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { placeBelow } from './floating';
+
+const viewport = { width: 1000, height: 800 };
+
+describe('placeBelow', () => {
+  it('hangs the overlay flush under the anchor, right-aligned with it', () => {
+    const place = placeBelow({ right: 700, bottom: 300 }, 400, viewport);
+    expect(place.top).toBe(302);
+    expect(place.right).toBe(300);
+    expect(place.maxHeight).toBe(800 - 302 - 12);
+  });
+
+  it('keeps an anchor at the window edge from pushing the overlay off it', () => {
+    // A marker in the margin can sit past the right edge of the window.
+    expect(placeBelow({ right: 1010, bottom: 10 }, 400, viewport).right).toBe(12);
+    // Near the left edge, right-alignment would run the overlay off the left.
+    expect(placeBelow({ right: 100, bottom: 10 }, 400, viewport).right).toBe(1000 - 400 - 12);
+  });
+
+  it('leaves the overlay at least a little room when the anchor is near the bottom', () => {
+    expect(placeBelow({ right: 500, bottom: 790 }, 400, viewport).maxHeight).toBe(120);
+  });
+
+  it('goes above an anchor near the bottom once it knows it would not fit below', () => {
+    const anchor = { top: 700, right: 500, bottom: 720 };
+    // Without a height there is nothing to compare, so the overlay stays below.
+    expect(placeBelow(anchor, 400, viewport).top).toBe(722);
+    const above = placeBelow(anchor, 400, viewport, 12, 300);
+    expect(above.top).toBe(700 - 2 - 300);
+    expect(above.maxHeight).toBe(700 - 2 - 12);
+  });
+
+  it('stays below while the overlay fits there, and when there is even less room above', () => {
+    expect(placeBelow({ top: 100, right: 500, bottom: 120 }, 400, viewport, 12, 300).top).toBe(122);
+    expect(placeBelow({ top: 40, right: 500, bottom: 760 }, 400, viewport, 12, 300).top).toBe(762);
+  });
+
+  it('pins a taller-than-the-room overlay to the top edge when flipped', () => {
+    const place = placeBelow({ top: 500, right: 500, bottom: 780 }, 400, viewport, 12, 900);
+    expect(place.top).toBe(12);
+    expect(place.maxHeight).toBe(500 - 2 - 12);
+  });
+});
diff --git a/src/lib/floating.ts b/src/lib/floating.ts
new file mode 100644
index 000000000..495d74a00
--- /dev/null
+++ b/src/lib/floating.ts
@@ -0,0 +1,107 @@
+/**
+ * What an overlay that floats over the window needs: to be placed from its
+ * anchor's on-screen position and to survive the pointer's trip from the
+ * anchor to the overlay itself. Anchors sit in scroll containers and, on
+ * HTML pages, inside elements whose own CSS clips overflow, so the overlay
+ * lives in `document.body` with `position: fixed` and is placed by hand.
+ */
+import { createEffect, createSignal, onCleanup, type Accessor } from 'solid-js';
+
+/**
+ * Runs `place` when `active` turns on, whenever the signals it reads change,
+ * and again on every scroll anywhere and on resize, until `active` turns off.
+ */
+export function createAnchorEffect(active: Accessor<boolean>, place: () => void): void {
+  createEffect(() => {
+    if (!active()) return;
+    place();
+    window.addEventListener('scroll', place, true);
+    window.addEventListener('resize', place);
+    onCleanup(() => {
+      window.removeEventListener('scroll', place, true);
+      window.removeEventListener('resize', place);
+    });
+  });
+}
+
+export interface Viewport {
+  width: number;
+  height: number;
+}
+
+export interface BelowAnchor {
+  top: number;
+  right: number;
+  /** Room left between the overlay's top and the viewport's bottom edge. */
+  maxHeight: number;
+}
+
+/** Breathing room between the anchor and the overlay. */
+const GAP = 2;
+
+/**
+ * Flush under `anchor` and right-aligned with it, kept `edge` px inside the
+ * viewport: an anchor at the window's edge does not push the overlay off it.
+ * Given the overlay's `height`, an anchor too close to the bottom for it gets
+ * the overlay above instead, when there is more room there.
+ */
+export function placeBelow(
+  anchor: { top?: number; right: number; bottom: number },
+  width: number,
+  viewport: Viewport,
+  edge = 12,
+  height?: number,
+): BelowAnchor {
+  const right = Math.min(
+    Math.max(viewport.width - anchor.right, edge),
+    viewport.width - width - edge,
+  );
+  const below = viewport.height - anchor.bottom - GAP - edge;
+  const above = anchor.top === undefined ? 0 : anchor.top - GAP - edge;
+  if (height !== undefined && height > below && above > below) {
+    const top = Math.max(edge, (anchor.top ?? 0) - GAP - height);
+    return { top, right, maxHeight: Math.max(120, above) };
+  }
+  const top = anchor.bottom + GAP;
+  return { top, right, maxHeight: Math.max(120, below) };
+}
+
+export interface HeldSignal<T> {
+  value: Accessor<T | null>;
+  /** Takes effect at once and cancels a pending clear. */
+  set: (value: T) => void;
+  /** Cancels a pending clear without changing the value. */
+  hold: () => void;
+  /** Empties the value after `delayMs`, unless `set` or `hold` comes first. */
+  clear: () => void;
+}
+
+/**
+ * A value that changes at once but empties only after a delay: the beat that
+ * lets a pointer cross from an anchor to the overlay it opened without the
+ * overlay closing under it.
+ */
+export function createHeldSignal<T>(delayMs: number): HeldSignal<T> {
+  const [value, setValue] = createSignal<T | null>(null);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const hold = () => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+  onCleanup(hold);
+  return {
+    value,
+    hold,
+    set: (next) => {
+      hold();
+      setValue(() => next);
+    },
+    clear: () => {
+      hold();
+      timer = setTimeout(() => {
+        timer = undefined;
+        setValue(null);
+      }, delayMs);
+    },
+  };
+}
diff --git a/src/lib/mermaid-lightbox.ts b/src/lib/mermaid-lightbox.ts
new file mode 100644
index 000000000..415ba48cc
--- /dev/null
+++ b/src/lib/mermaid-lightbox.ts
@@ -0,0 +1,83 @@
+/**
+ * A rendered mermaid diagram at the size of the window. Plain DOM rather
+ * than a component so every markdown surface (task notes, the plan dialog,
+ * document workspaces) gets it from `renderMermaidIn` alone.
+ */
+import { isTopmost, popDialog, pushDialog } from './dialog-stack';
+
+const LIGHTBOX_ID = 'mermaid-lightbox';
+
+const CLOSE_GLYPH =
+  '<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"/></svg>';
+
+const ENLARGE_GLYPH =
+  '<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M1.75 10a.75.75 0 0 1 .75.75v2.69l3.22-3.22a.75.75 0 1 1 1.06 1.06L3.56 14.5h2.69a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1-.75-.75v-4.5a.75.75 0 0 1 .75-.75Zm12.5-4a.75.75 0 0 1-.75-.75V2.56l-3.22 3.22a.75.75 0 1 1-1.06-1.06L12.44 1.5H9.75a.75.75 0 0 1 0-1.5h4.5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-.75.75Z"/></svg>';
+
+/** Shows `svg` over the whole window until Esc, the close button or the backdrop. */
+export function openMermaidLightbox(svg: SVGSVGElement, returnFocusTo?: HTMLElement): void {
+  if (document.getElementById(LIGHTBOX_ID)) return;
+  const overlay = document.createElement('div');
+  overlay.id = LIGHTBOX_ID;
+  overlay.className = 'mermaid-lightbox';
+  overlay.setAttribute('role', 'dialog');
+  overlay.setAttribute('aria-modal', 'true');
+  overlay.setAttribute('aria-label', 'Diagram');
+
+  const close = document.createElement('button');
+  close.type = 'button';
+  close.className = 'mermaid-lightbox-close';
+  close.setAttribute('aria-label', 'Close (Esc)');
+  close.title = 'Close (Esc)';
+  close.innerHTML = CLOSE_GLYPH; // nosemgrep: semgrep.no-inner-html-without-sanitize -- constant icon markup
+
+  const body = document.createElement('div');
+  body.className = 'mermaid-lightbox-body';
+  // Mermaid pins its SVG to the width it was laid out at; the copy scales to
+  // the box instead, keeping the diagram's own aspect through its viewBox.
+  const copy = svg.cloneNode(true) as SVGSVGElement;
+  copy.removeAttribute('width');
+  copy.removeAttribute('height');
+  copy.style.maxWidth = 'none';
+  copy.style.width = '100%';
+  copy.style.height = '100%';
+  body.append(copy);
+  overlay.append(close, body);
+
+  function dismiss() {
+    overlay.remove();
+    window.removeEventListener('keydown', onKey, true);
+    popDialog(LIGHTBOX_ID);
+    returnFocusTo?.focus();
+  }
+  // Capture phase, so the dialog underneath does not take the same Escape.
+  function onKey(e: KeyboardEvent) {
+    if (e.key !== 'Escape' || !isTopmost(LIGHTBOX_ID)) return;
+    e.stopPropagation();
+    e.preventDefault();
+    dismiss();
+  }
+  close.addEventListener('click', dismiss);
+  overlay.addEventListener('click', (e) => {
+    if (e.target === overlay || e.target === body) dismiss();
+  });
+  window.addEventListener('keydown', onKey, true);
+  pushDialog(LIGHTBOX_ID);
+  document.body.append(overlay);
+  close.focus();
+}
+
+/** The corner button a rendered diagram gets: opens it in the lightbox. */
+export function createEnlargeButton(block: HTMLElement): HTMLButtonElement {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = 'mermaid-enlarge';
+  button.setAttribute('aria-label', 'Enlarge diagram');
+  button.title = 'Enlarge diagram';
+  button.innerHTML = ENLARGE_GLYPH; // nosemgrep: semgrep.no-inner-html-without-sanitize -- constant icon markup
+  button.addEventListener('click', (e) => {
+    e.stopPropagation();
+    const svg = block.querySelector('svg');
+    if (svg) openMermaidLightbox(svg, button);
+  });
+  return button;
+}
diff --git a/src/lib/mermaid.client.test.tsx b/src/lib/mermaid.client.test.tsx
index 2e3a1a681..55ee427d9 100644
--- a/src/lib/mermaid.client.test.tsx
+++ b/src/lib/mermaid.client.test.tsx
@@ -55,6 +55,31 @@ describe('renderMermaidIn', () => {
     expect(rendered).toEqual(['graph TD; A---B']);
   });
 
+  it('offers to enlarge a rendered diagram into a lightbox that Escape closes', async () => {
+    rendered.length = 0;
+    const container = host('<div class="mermaid-block" data-mermaid="graph TD; A---B">x</div>');
+
+    renderMermaidIn(container, 'k');
+
+    const block = await waitFor(() => container.querySelector('.mermaid-block.mermaid-rendered'));
+    const enlarge = block.querySelector<HTMLButtonElement>('button.mermaid-enlarge');
+    expect(enlarge?.getAttribute('aria-label')).toBe('Enlarge diagram');
+
+    enlarge?.click();
+
+    const lightbox = document.getElementById('mermaid-lightbox');
+    expect(lightbox?.getAttribute('role')).toBe('dialog');
+    expect(lightbox?.querySelector('.mermaid-lightbox-body svg')).not.toBeNull();
+    expect(lightbox?.querySelector<SVGElement>('.mermaid-lightbox-body svg')?.style.width).toBe(
+      '100%',
+    );
+
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', cancelable: true }));
+
+    expect(document.getElementById('mermaid-lightbox')).toBeNull();
+    expect(document.activeElement).toBe(enlarge);
+  });
+
   it('leaves an empty placeholder alone', async () => {
     rendered.length = 0;
     const container = host('<div class="mermaid-block">   </div>');
diff --git a/src/lib/mermaid.ts b/src/lib/mermaid.ts
index 9371f560a..74a7a865d 100644
--- a/src/lib/mermaid.ts
+++ b/src/lib/mermaid.ts
@@ -6,6 +6,8 @@
  * @param key unique per rendering surface, so ids stay distinct when the same
  *   document is on screen twice (inline plan tab and plan dialog, for example)
  */
+import { createEnlargeButton } from './mermaid-lightbox';
+
 export function renderMermaidIn(container: HTMLElement | undefined, key: string): void {
   if (!container) return;
   const nodes = container.querySelectorAll<HTMLElement>('.mermaid-block:not(.mermaid-rendered)');
@@ -25,6 +27,9 @@ export function renderMermaidIn(container: HTMLElement | undefined, key: string)
           .then(({ svg }) => {
             el.innerHTML = svg; // nosemgrep: semgrep.no-inner-html-without-sanitize -- mermaid renders its own sanitized SVG from local markdown
             el.classList.add('mermaid-rendered');
+            // Diagrams outgrow a prose column; the corner button shows them at
+            // the size of the window.
+            el.append(createEnlargeButton(el));
           })
           .catch((err) => console.warn('[mermaid] render failed:', err));
       });
diff --git a/src/lib/platform.ts b/src/lib/platform.ts
index a53e84786..fea7bec7a 100644
--- a/src/lib/platform.ts
+++ b/src/lib/platform.ts
@@ -1,7 +1,8 @@
 export const isMac = navigator.userAgent.includes('Mac');
-export const isLinux = navigator.userAgent.includes('Linux');
 
-export const windowChromeTopInset = isMac ? 32 : isLinux ? 34 : 0;
+/** Height of the window chrome drawn over the top of the page: the native
+ *  traffic-light strip on macOS, the app's own title bar everywhere else. */
+export const windowChromeTopInset = isMac ? 32 : 34;
 
 /** Display name for the primary modifier key: "Cmd" on macOS, "Ctrl" elsewhere. */
 export const mod = isMac ? 'Cmd' : 'Ctrl';
diff --git a/src/store/core.ts b/src/store/core.ts
index c9b97edc0..3f9c01443 100644
--- a/src/store/core.ts
+++ b/src/store/core.ts
@@ -91,6 +91,7 @@ export const [store, setStore] = createStore<AppStore>({
   verboseLogging: false,
   coordinatorModeEnabled: false,
   documentWorkspacesEnabled: false,
+  documentFullWidth: false,
   activeDocumentProjectId: null,
   coordinatorNotificationDelayMs: 60_000,
   coordinatorControlHintDismissed: false,
diff --git a/src/store/persistence.test.ts b/src/store/persistence.test.ts
index b9714cd90..2cf439cb2 100644
--- a/src/store/persistence.test.ts
+++ b/src/store/persistence.test.ts
@@ -1044,3 +1044,56 @@ describe('showSteps → defaultStepsEnabled migration', () => {
     expect(saved.defaultStepsEnabled).toBe(true);
   });
 });
+
+describe('document full width persistence', () => {
+  function stateJson(extra: Record<string, unknown>): string {
+    return JSON.stringify({
+      projects: [],
+      lastProjectId: null,
+      lastAgentId: null,
+      taskOrder: [],
+      collapsedTaskOrder: [],
+      tasks: {},
+      activeTaskId: null,
+      sidebarVisible: true,
+      ...extra,
+    });
+  }
+
+  async function lastSaved(): Promise<Record<string, unknown>> {
+    mockInvoke.mockResolvedValueOnce(undefined);
+    await saveState();
+    const lastCall = mockInvoke.mock.calls[mockInvoke.mock.calls.length - 1];
+    return JSON.parse(lastCall[1].json) as Record<string, unknown>;
+  }
+
+  it('round-trips the preference and leaves the default out of the file', async () => {
+    mockInvoke.mockResolvedValueOnce(stateJson({ documentFullWidth: true }));
+    await loadState();
+    expect(store.documentFullWidth).toBe(true);
+    expect((await lastSaved()).documentFullWidth).toBe(true);
+
+    mockInvoke.mockResolvedValueOnce(stateJson({ documentFullWidth: 'yes' }));
+    await loadState();
+    expect(store.documentFullWidth).toBe(false);
+    expect((await lastSaved()).documentFullWidth).toBeUndefined();
+  });
+});
+
+describe('active task repair', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    setStore('tasks', {});
+    setStore('taskOrder', []);
+    setStore('activeTaskId', 'stale');
+    setStore('focusMode', false);
+  });
+
+  it('drops an active id that names nothing, such as a workspace agent task', async () => {
+    mockInvoke.mockResolvedValueOnce(basePayload({ activeTaskId: 'doc-agent-docs' }));
+
+    await loadState();
+
+    expect(store.activeTaskId).toBeNull();
+  });
+});
diff --git a/src/store/persistence.ts b/src/store/persistence.ts
index 14ff1de52..d8a2af8d4 100644
--- a/src/store/persistence.ts
+++ b/src/store/persistence.ts
@@ -245,6 +245,7 @@ export async function saveState(): Promise<void> {
     darkThemeCustomId: store.darkThemeCustomId ?? undefined,
     coordinatorModeEnabled: store.coordinatorModeEnabled || undefined,
     documentWorkspacesEnabled: store.documentWorkspacesEnabled || undefined,
+    documentFullWidth: store.documentFullWidth || undefined,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed || undefined,
     defaultStepsEnabled: store.defaultStepsEnabled || undefined,
     defaultSkipPermissions: store.defaultSkipPermissions || undefined,
@@ -417,6 +418,7 @@ interface LegacyPersistedState {
   darkThemeCustomId?: unknown;
   coordinatorModeEnabled?: unknown;
   documentWorkspacesEnabled?: unknown;
+  documentFullWidth?: unknown;
   coordinatorControlHintDismissed?: unknown;
   defaultStepsEnabled?: unknown;
   defaultSkipPermissions?: unknown;
@@ -616,6 +618,7 @@ export async function loadState(): Promise<void> {
 
       s.coordinatorModeEnabled = raw.coordinatorModeEnabled === true;
       s.documentWorkspacesEnabled = raw.documentWorkspacesEnabled === true;
+      s.documentFullWidth = raw.documentFullWidth === true;
 
       s.coordinatorControlHintDismissed = raw.coordinatorControlHintDismissed === true;
 
@@ -866,16 +869,17 @@ export async function loadState(): Promise<void> {
       const activeSet = new Set(s.taskOrder);
       s.collapsedTaskOrder = s.collapsedTaskOrder.filter((id) => !activeSet.has(id));
 
-      // Focus mode requires a valid active panel; without one, every panel is
-      // hidden and the strip reads blank. Repair or drop focus mode.
-      if (s.focusMode) {
-        const activeValid =
-          s.activeTaskId !== null &&
-          (s.tasks[s.activeTaskId] !== undefined || s.terminals[s.activeTaskId] !== undefined);
-        if (!activeValid) {
-          s.activeTaskId = s.taskOrder[0] ?? null;
-          if (s.activeTaskId === null) s.focusMode = false;
-        }
+      // The active id can name nothing: a document workspace's hidden agent
+      // task is never saved, so an app that quit with one open points at it.
+      // Focus mode needs a valid active panel on top of that; without one,
+      // every panel is hidden and the strip reads blank. Repair or drop it.
+      const activeValid =
+        s.activeTaskId !== null &&
+        (s.tasks[s.activeTaskId] !== undefined || s.terminals[s.activeTaskId] !== undefined);
+      if (!activeValid) s.activeTaskId = null;
+      if (s.focusMode && s.activeTaskId === null) {
+        s.activeTaskId = s.taskOrder[0] ?? null;
+        if (s.activeTaskId === null) s.focusMode = false;
       }
 
       // Set activeAgentId from the active task
diff --git a/src/store/tasks.ts b/src/store/tasks.ts
index 0582eed04..a0d618ca5 100644
--- a/src/store/tasks.ts
+++ b/src/store/tasks.ts
@@ -617,6 +617,19 @@ function removeTaskFromStore(taskId: string, agentIds: string[]): void {
   }, REMOVE_ANIMATION_MS);
 }
 
+/** Drops a task and its agents from the store at once, with no closing
+ *  animation: for a task that was never listed, such as a document
+ *  workspace's agent task. The caller has killed the agents already. */
+export function forgetTask(taskId: string, agentIds: readonly string[]): void {
+  for (const agentId of agentIds) clearAgentActivity(agentId);
+  clearTaskGitStatusTracking(taskId);
+  setStore(
+    produce((s) => {
+      removeTaskDraftEntries(s, taskId, agentIds, effectiveAgentId);
+    }),
+  );
+}
+
 export async function mergeTask(
   taskId: string,
   options?: { squash?: boolean; message?: string; cleanup?: boolean },
diff --git a/src/store/types.ts b/src/store/types.ts
index 86219cd70..6d42c7210 100644
--- a/src/store/types.ts
+++ b/src/store/types.ts
@@ -335,6 +335,7 @@ export interface PersistedState {
   darkThemeCustomId?: string | null;
   coordinatorModeEnabled?: boolean;
   documentWorkspacesEnabled?: boolean;
+  documentFullWidth?: boolean;
   coordinatorNotificationDelayMs?: number;
   coordinatorControlHintDismissed?: boolean;
   defaultStepsEnabled?: boolean;
@@ -463,6 +464,8 @@ export interface AppStore {
   darkThemeCustomId: string | null;
   coordinatorModeEnabled: boolean;
   documentWorkspacesEnabled: boolean;
+  /** Let the rendered document take the whole column instead of a reading width. */
+  documentFullWidth: boolean;
   /** Project whose document workspace overlay is open. */
   activeDocumentProjectId: string | null;
   coordinatorNotificationDelayMs: number;
diff --git a/src/store/ui.ts b/src/store/ui.ts
index 67eaa92a8..f529288cb 100644
--- a/src/store/ui.ts
+++ b/src/store/ui.ts
@@ -275,6 +275,10 @@ export function setDocumentWorkspacesEnabled(enabled: boolean): void {
   if (!enabled) setStore('activeDocumentProjectId', null);
 }
 
+export function setDocumentFullWidth(fullWidth: boolean): void {
+  setStore('documentFullWidth', fullWidth);
+}
+
 export function toggleArena(show?: boolean): void {
   setStore('showArena', show ?? !store.showArena);
 }
diff --git a/src/styles.css b/src/styles.css
index 536103201..5c18972e4 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -2540,11 +2540,84 @@ body.dragging-task * {
   color: var(--fg-muted);
 }
 .mermaid-block.mermaid-rendered {
+  position: relative;
   white-space: normal;
   text-align: center;
   background: color-mix(in srgb, var(--fg) 3%, transparent);
 }
 
+/* The enlarge button waits in the diagram's corner until the pointer is on it. */
+.mermaid-enlarge {
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-elevated);
+  color: var(--fg-muted);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s ease;
+}
+
+.mermaid-block:hover .mermaid-enlarge,
+.mermaid-enlarge:focus-visible {
+  opacity: 1;
+}
+
+.mermaid-enlarge:hover {
+  color: var(--fg);
+  border-color: var(--border-focus);
+}
+
+/* The diagram at the size of the window, over everything else. */
+.mermaid-lightbox {
+  position: fixed;
+  inset: 0;
+  z-index: 3000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 40px;
+  background: rgba(0, 0, 0, 0.82);
+  cursor: zoom-out;
+}
+
+.mermaid-lightbox-body {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.mermaid-lightbox-body svg {
+  cursor: default;
+}
+
+.mermaid-lightbox-close {
+  position: absolute;
+  top: 14px;
+  right: 14px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 34px;
+  height: 34px;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--bg-elevated);
+  color: var(--fg);
+  cursor: pointer;
+}
+
 /* AskCodeCard loading animation */
 @keyframes askcode-pulse {
   0%,

From c40d2b961b25dcbb08fe2b403f143da4a99e2d3a Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Tue, 8 Sep 2026 21:20:31 +0200
Subject: [PATCH 3/5] fix(ci): give the runner a Git identity

Document setup lets the app create the repository itself, so the commit it
makes has no local identity to fall back on and fails on a bare runner.

Claude-Session: https://claude.ai/code/session_011wx6DbuYrV9qsunua6BUu3
---
 .github/workflows/ci.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 335e21593..ced7a843b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,6 +12,13 @@ jobs:
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
+      # Runners have no global Git identity, and tests that let the app create a
+      # repository of its own commit into it without a local one to fall back on.
+      - name: Give Git an identity
+        run: |
+          git config --global user.email "ci@example.com"
+          git config --global user.name "CI"
+
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '22'

From 44ec17d16ae1355d58b1dee7c7d530087afefab3 Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Tue, 8 Sep 2026 21:20:52 +0200
Subject: [PATCH 4/5] feat(documents): move project settings into the workspace
 header

Claude-Session: https://claude.ai/code/session_011wx6DbuYrV9qsunua6BUu3
---
 src/documents/DocumentWorkspaceOverlay.tsx | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 77c4d89bc..a94086d51 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -624,6 +624,20 @@ export function DocumentWorkspaceOverlay() {
               <path d="M1.75 1A1.75 1.75 0 0 0 0 2.75v10.5C0 14.216.784 15 1.75 15h12.5A1.75 1.75 0 0 0 16 13.25v-8.5A1.75 1.75 0 0 0 14.25 3H7.5a.25.25 0 0 1-.2-.1l-.9-1.2C6.07 1.26 5.55 1 5 1H1.75Zm0 1.5H5c.08 0 .15.04.2.1l.9 1.2c.33.44.85.7 1.4.7h6.75a.25.25 0 0 1 .25.25v8.5a.25.25 0 0 1-.25.25H1.75a.25.25 0 0 1-.25-.25V2.75a.25.25 0 0 1 .25-.25Z" />
             </svg>
           </button>
+          {/* The sidebar opens a document project as this workspace, so its
+              settings are reachable only from here. */}
+          <button
+            type="button"
+            class="docws-btn docws-open-editor"
+            aria-label="Project settings: name, folder and agents"
+            title="Project settings: name, folder and agents"
+            disabled={!project()}
+            onClick={() => setEditing(project() ?? null)}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+              <path d="M8 2.25a.75.75 0 0 1 .73.56l.2.72a4.48 4.48 0 0 1 1.04.43l.66-.37a.75.75 0 0 1 .9.13l.75.75a.75.75 0 0 1 .13.9l-.37.66c.17.33.31.68.43 1.04l.72.2a.75.75 0 0 1 .56.73v1.06a.75.75 0 0 1-.56.73l-.72.2a4.48 4.48 0 0 1-.43 1.04l.37.66a.75.75 0 0 1-.13.9l-.75.75a.75.75 0 0 1-.9.13l-.66-.37a4.48 4.48 0 0 1-1.04.43l-.2.72a.75.75 0 0 1-.73.56H6.94a.75.75 0 0 1-.73-.56l-.2-.72a4.48 4.48 0 0 1-1.04-.43l-.66.37a.75.75 0 0 1-.9-.13l-.75-.75a.75.75 0 0 1-.13-.9l.37-.66a4.48 4.48 0 0 1-.43-1.04l-.72-.2a.75.75 0 0 1-.56-.73V7.47a.75.75 0 0 1 .56-.73l.72-.2c.11-.36.26-.71.43-1.04l-.37-.66a.75.75 0 0 1 .13-.9l.75-.75a.75.75 0 0 1 .9-.13l.66.37c.33-.17.68-.31 1.04-.43l.2-.72a.75.75 0 0 1 .73-.56H8Zm-.53 3.22a2.5 2.5 0 1 0 1.06 4.88 2.5 2.5 0 0 0-1.06-4.88Z" />
+            </svg>
+          </button>
         </div>
         <Show when={previousDocumentPath()}>
           {(previous) => (
@@ -673,9 +687,6 @@ export function DocumentWorkspaceOverlay() {
           {tab('document', 'Document')}
           {tab('history', 'History')}
         </div>
-        <button type="button" class="docws-btn" onClick={() => setEditing(project() ?? null)}>
-          Project
-        </button>
         <button
           type="button"
           class="docws-btn"

From 48ad84730fe341d6bbf3b8a286824626bcbe2060 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 8 Sep 2026 19:33:18 +0000
Subject: [PATCH 5/5] fix(documents): remove stale terminal imports after merge

---
 src/components/TaskAITerminal.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/components/TaskAITerminal.tsx b/src/components/TaskAITerminal.tsx
index 9c0b12940..70273f45d 100644
--- a/src/components/TaskAITerminal.tsx
+++ b/src/components/TaskAITerminal.tsx
@@ -19,9 +19,8 @@ import {
   showNotification,
   toggleAITerminalLayout,
 } from '../store/store';
-import { markDirty, redrawTerminal } from '../lib/terminalFitManager';
+import { markDirty } from '../lib/terminalFitManager';
 import { isAgentAskingQuestion } from '../store/taskStatus';
-import { isMac } from '../lib/platform';
 import { warn as logWarn } from '../lib/log';
 import { InfoBar } from './InfoBar';
 import { TerminalView } from './TerminalView';