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/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c59bebcaf..bb68fe4f0 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'
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..180d2bc41
--- /dev/null
+++ b/docs/document-workspaces.md
@@ -0,0 +1,360 @@
+# 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 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 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:
+   - **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**, 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 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 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
+   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 **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. **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`.
+
+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. 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 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
+  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.
+- **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.
+- **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. 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
+  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..27b9374b9
--- /dev/null
+++ b/electron/documents/annotations.test.ts
@@ -0,0 +1,267 @@
+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 {
+  annotationThread,
+  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();
+  });
+
+  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', () => {
+  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');
+    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));
+  });
+});
+
+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..716e4eebe
--- /dev/null
+++ b/electron/documents/annotations.ts
@@ -0,0 +1,467 @@
+/**
+ * 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 { truncateBytes } from './prompt.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;
+/** 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);
+}
+
+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;
+  const followUpOf =
+    typeof v.followUpOf === 'string' &&
+    /^[a-z0-9-]{1,64}$/i.test(v.followUpOf) &&
+    v.followUpOf !== id
+      ? v.followUpOf
+      : 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,
+    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[] {
+  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>();
+
+/** 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}")`
+    : `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}`,
+    ...(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.',
+      '- 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 earlier = annotationThread(readAnnotations(projectRoot), annotation);
+  const launch = buildHeadlessLaunch({
+    agentId,
+    command,
+    prompt: buildAnnotationPrompt(annotation, earlier),
+    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/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/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..212d5de7c
--- /dev/null
+++ b/electron/documents/files.test.ts
@@ -0,0 +1,40 @@
+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, '.claude/settings.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..a31e34b67
--- /dev/null
+++ b/electron/documents/files.ts
@@ -0,0 +1,28 @@
+/**
+ * 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; `.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, [
+    '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/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
new file mode 100644
index 000000000..0793ebd3f
--- /dev/null
+++ b/electron/documents/prompt.test.ts
@@ -0,0 +1,174 @@
+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('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',
+      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..fb6281d07
--- /dev/null
+++ b/electron/documents/prompt.ts
@@ -0,0 +1,214 @@
+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;
+  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;
+  /** 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 {
+  return text
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .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;
+  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 (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 {
+    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..d827e4a29
--- /dev/null
+++ b/electron/documents/register.ts
@@ -0,0 +1,199 @@
+/**
+ * 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,
+  discardDocumentEdits,
+  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,
+      merge: args.merge,
+    });
+  });
+
+  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));
+  });
+
+  ipcMain.handle(IPC.DiscardDocumentEdits, (_e, args) => {
+    return discardDocumentEdits(projectRootArg(args));
+  });
+
+  // --- 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..46198ffd8
--- /dev/null
+++ b/electron/documents/runs.test.ts
@@ -0,0 +1,150 @@
+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('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' }] }),
+    ).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..6c0c7f322
--- /dev/null
+++ b/electron/documents/runs.ts
@@ -0,0 +1,1627 @@
+/**
+ * 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, type MergeCandidateInput } 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);
+    }
+    if (run.merge) validateMerge(run.merge);
+  } 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;
+  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[] {
+  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);
+  }
+  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 || 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;
+      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;
+    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 ${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.');
+      const content = await getDocumentAtCommit(projectRoot, source.commitSha, documentPath);
+      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)) {
+      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,
+      merge,
+    };
+
+    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: refinement ? sourceRun?.instruction : undefined,
+          mergeCandidates,
+          mergeInstruction: merge ? sourceRun?.instruction : undefined,
+        });
+        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();
+  });
+}
+
+/**
+ * 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/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..7c86e7eee
--- /dev/null
+++ b/electron/documents/types.ts
@@ -0,0 +1,223 @@
+/**
+ * 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 };
+  /** 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 };
+  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;
+  /** 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. */
+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..548df3178 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -147,5 +147,31 @@
   "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",
+  "DiscardDocumentEdits": "discard_document_edits",
+  "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..948e39c24 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -152,6 +152,32 @@ 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',
+  'discard_document_edits',
+  '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 f533b8056..ed3a8849c 100644
--- a/package.json
+++ b/package.json
@@ -58,6 +58,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..bf12a8a0b 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -87,6 +87,16 @@ 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 { 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';
@@ -336,6 +346,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();
 
@@ -641,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'),
@@ -669,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) => {
@@ -697,6 +712,19 @@ function App() {
           closeArena();
           return;
         }
+        if (store.activeDocumentProjectId) {
+          // 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) {
           toggleHelpDialog(false);
           return;
@@ -742,6 +770,7 @@ function App() {
       stopRemoteTaskHandlers();
       stopRemoteStatusSync();
       stopAgentHookStatusListener();
+      stopDocumentListeners();
       offPlanContent();
       offStepsContent();
       unlistenFocusChanged?.();
@@ -919,6 +948,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..65bb66473
--- /dev/null
+++ b/src/components/AddProjectMenu.tsx
@@ -0,0 +1,133 @@
+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) {
+  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);
+      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',
+        '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
+          ref={menu}
+          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/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/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/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/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 8d6a13093..f661193a1 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/TaskAITerminal.tsx b/src/components/TaskAITerminal.tsx
index 29d457b6a..70273f45d 100644
--- a/src/components/TaskAITerminal.tsx
+++ b/src/components/TaskAITerminal.tsx
@@ -20,6 +20,7 @@ import {
   toggleAITerminalLayout,
 } from '../store/store';
 import { markDirty } from '../lib/terminalFitManager';
+import { isAgentAskingQuestion } from '../store/taskStatus';
 import { warn as logWarn } from '../lib/log';
 import { InfoBar } from './InfoBar';
 import { TerminalView } from './TerminalView';
@@ -52,7 +53,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) {
@@ -136,6 +139,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…',
@@ -272,6 +284,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);
@@ -415,7 +428,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)}
@@ -870,6 +885,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/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.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
new file mode 100644
index 000000000..2e434eba2
--- /dev/null
+++ b/src/documents/AgentTerminal.tsx
@@ -0,0 +1,97 @@
+import { Show, createEffect } from 'solid-js';
+import { TaskAITerminal } from '../components/TaskAITerminal';
+import { PromptInput } from '../components/PromptInput';
+import { store } from '../store/core';
+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, Task } from '../store/types';
+import { documentAgentTaskId, rearmDocumentAgents } from './agent-task';
+import { openDocumentFile } from './store';
+
+interface AgentTerminalProps {
+  project: Project;
+}
+
+/**
+ * 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 task = () => store.tasks[documentAgentTaskId(props.project.id)];
+  const firstAgentId = () => task()?.agentIds[0] ?? '';
+
+  // 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">
+      <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
new file mode 100644
index 000000000..ed3b03610
--- /dev/null
+++ b/src/documents/AnnotationBubble.tsx
@@ -0,0 +1,322 @@
+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,
+  askFollowUpQuestion,
+  deleteDocumentAnnotation,
+  documentMainAgentId,
+  documentStore,
+  setDocumentAnnotationResolved,
+  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. */
+  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;
+  // 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;
+    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.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"
+              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() === '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) => (
+                    <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..8f9d30a60
--- /dev/null
+++ b/src/documents/AnnotationMarker.client.test.tsx
@@ -0,0 +1,212 @@
+import { render } from 'solid-js/web';
+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> = [];
+
+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, floating over the window', () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+
+    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('opens on hover and holds while the pointer crosses onto the popover', async () => {
+    const host = mount([annotation('a', 'A thought', 'note')]);
+    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
+    // 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('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');
+    const button = host.querySelector<HTMLButtonElement>('.docws-marker-btn');
+
+    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
new file mode 100644
index 000000000..1be895e0d
--- /dev/null
+++ b/src/documents/AnnotationMarker.tsx
@@ -0,0 +1,199 @@
+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;
+  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. 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 (!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}
+      class="docws-marker"
+      classList={{
+        'is-pinned': pinned(),
+        'is-question': props.annotations.some((a) => a.kind === 'question'),
+      }}
+      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 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 (!next && 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="16"
+              height="16"
+              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>
+      <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
new file mode 100644
index 000000000..e5f301c22
--- /dev/null
+++ b/src/documents/BlockActions.client.test.tsx
@@ -0,0 +1,138 @@
+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,
+  },
+];
+
+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 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([
+      'Edit this block with agent',
+      'Proposals for this block',
+      'Note beside this block',
+      'Ask an agent about this block',
+      'Edit this block',
+    ]);
+
+    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);
+    expect(onAction).toHaveBeenNthCalledWith(3, 'edit', 1);
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+
+  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);
+
+    toolbar()?.dispatchEvent(new MouseEvent('mouseleave'));
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(isOpen()).toBe(false);
+  });
+
+  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'));
+  });
+
+  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,
+    );
+
+    // 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', () => {
+    mount({ selectable: false });
+    expect(toolbar()).toBeNull();
+  });
+});
diff --git a/src/documents/BlockActions.tsx b/src/documents/BlockActions.tsx
new file mode 100644
index 000000000..f192322a8
--- /dev/null
+++ b/src/documents/BlockActions.tsx
@@ -0,0 +1,122 @@
+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. */
+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: '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',
+  },
+  {
+    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 ?? '';
+}
+
+/** 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>
+  );
+}
+
+/** 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;
+}
+
+/**
+ * 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: 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 (
+    <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>
+  );
+}
diff --git a/src/documents/BlockEditor.client.test.tsx b/src/documents/BlockEditor.client.test.tsx
new file mode 100644
index 000000000..01b7f4de8
--- /dev/null
+++ b/src/documents/BlockEditor.client.test.tsx
@@ -0,0 +1,117 @@
+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('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();
+    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..f6178932e
--- /dev/null
+++ b/src/documents/BlockEditor.tsx
@@ -0,0 +1,132 @@
+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';
+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 [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()) return;
+    if (dirty()) setConfirmDiscard(true);
+    else 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>
+      <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
new file mode 100644
index 000000000..d212fface
--- /dev/null
+++ b/src/documents/CandidateOutputDialog.tsx
@@ -0,0 +1,122 @@
+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';
+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;
+  let closeRef: HTMLButtonElement | undefined;
+  const id = createUniqueId();
+  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();
+      // Focus moves into the dialog as it opens, as in the app's other dialogs.
+      requestAnimationFrame(() => closeRef?.focus());
+    }),
+  );
+
+  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)"
+      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" 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)}
+              >
+                Close
+              </button>
+            </div>
+            <div class="docws-run-instruction" id={`${id}-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..a88ddb1f5
--- /dev/null
+++ b/src/documents/CandidateRefinement.client.test.tsx
@@ -0,0 +1,95 @@
+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('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();
+    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..66b262894
--- /dev/null
+++ b/src/documents/CandidateRefinement.tsx
@@ -0,0 +1,98 @@
+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);
+  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);
+    }
+  }
+
+  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()}
+        onClick={() => setOpen(!open())}
+        disabled={starting()}
+      >
+        Refine this candidate
+      </button>
+      <Show when={open()}>
+        <div class="docws-refinement" on:keydown={onKeyDown}>
+          <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..6d1f63ac5
--- /dev/null
+++ b/src/documents/CompareDialog.tsx
@@ -0,0 +1,97 @@
+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 PANEL: JSX.CSSProperties = {
+  padding: '0',
+  gap: '0',
+  overflow: 'hidden',
+  height: '100%',
+  'max-height': 'none',
+  'border-radius': '0',
+  border: 'none',
+};
+
+/**
+ * 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 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={dismiss}
+      width="100%"
+      panelStyle={PANEL}
+      overlayStyle={isMac ? undefined : { top: `${windowChromeTopInset}px` }}
+      labelledBy={titleId}
+    >
+      <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"
+              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"
+            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]}
+                candidateId={documentStore.compareCandidateId ?? undefined}
+              />
+            )}
+          </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..2192eedd0
--- /dev/null
+++ b/src/documents/CompareView.client.test.tsx
@@ -0,0 +1,523 @@
+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 () => {}),
+  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'];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ availableAgents: [] });
+  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, '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',
+      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, 'Apply 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, 'Apply 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, 'Apply 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, '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, 'Apply proposal').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(),
+    rationale: {
+      summary: 'Clarify the introduction.',
+      changes: ['Explain the delivery guarantees.'],
+      assumptions: [],
+      questions: [],
+      warnings: ['Verify delivery guarantees before publishing.'],
+    },
+  };
+}
+
+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(candidateId?: string): HTMLElement {
+  const host = document.createElement('div');
+  document.body.append(host);
+  disposers.push(render(() => <CompareView run={run} candidateId={candidateId} />, 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();
+    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');
+    return { host, seam, base };
+  }
+
+  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);
+  });
+
+  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();
+    button(host, 'Show all proposals').click();
+    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();
+  });
+});
+
+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
new file mode 100644
index 000000000..a7c385aff
--- /dev/null
+++ b/src/documents/CompareView.tsx
@@ -0,0 +1,875 @@
+import {
+  For,
+  Index,
+  Show,
+  createEffect,
+  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 {
+  type BlockHunk,
+  blockHunks,
+  composeVerifiedDocument,
+  hunkLabel,
+  hunkLeadBlocks,
+} from './block-merge';
+import {
+  acceptDocumentCandidate,
+  documentStore,
+  modelLabel,
+  setDocumentCandidateNote,
+} from './store';
+import { RejectRunButton } from './RejectRunConfirm';
+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. 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 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;
+  baseBody: () => HTMLDivElement | undefined;
+  hunks: BlockHunk[];
+  baseCount: number;
+  candidateCount: number;
+}) {
+  const [cursor, setCursor] = createSignal(-1);
+  function go(delta: number) {
+    const count = props.hunks.length;
+    if (!count) return;
+    const next = cursor() < 0 ? (delta > 0 ? 0 : count - 1) : (cursor() + delta + count) % count;
+    setCursor(next);
+    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>
+        {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>
+    </span>
+  );
+}
+
+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}>
+      <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" 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">
+          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;
+  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[], hunks: BlockHunk[]) => 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, blockHunks(blockDiff()));
+  });
+  // 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, () => 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(
+    () =>
+      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 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(),
+  );
+  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) => {
+    // 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),
+      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()}
+      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() && !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());
+            }}
+          />
+        </Rationale>
+        <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()}
+                    visibleBlock={
+                      props.changesOnly && !rendered.page() ? (i) => visible().has(i) : undefined
+                    }
+                    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>
+      <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; 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),
+  );
+  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.
+  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 {
+    if (!showAll()) return 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 = 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';
+      if (marks.includes('changed')) return 'changed';
+      return 'same';
+    });
+  });
+  // 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, 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 = () => {
+    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>
+        <label
+          class="docws-toggle"
+          title={
+            base.page() || showSource()
+              ? 'Available for rendered Markdown'
+              : 'Hide unchanged passages'
+          }
+        >
+          <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>
+      <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">Original</div>
+            <div class="docws-rationale">
+              <div>
+                The document as every candidate saw it. The scoped passage is outlined; blocks a
+                proposal rewrote or removed are marked.
+              </div>
+            </div>
+          </div>
+          <div class="docws-column-body" ref={baseBodyRef}>
+            <DocumentViewer
+              blocks={base.blocks()}
+              scope={scope()}
+              changes={baseMarks()}
+              visibleBlock={filtering() ? (i) => baseVisible().has(i) : undefined}
+              renderKey="base"
+              page={base.page()}
+            />
+          </div>
+        </section>
+        <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()}
+                changesOnly={filtering()}
+                baseBody={() => baseBodyRef}
+                onBaseChanges={(id, marks, hunks) => {
+                  setBaseChanges((prev) => ({ ...prev, [id]: marks }));
+                  setBaseHunks((prev) => ({ ...prev, [id]: hunks }));
+                }}
+                style={columnStyle(`candidate-${i}`)}
+              />
+              <Show when={showAll()}>{seam(`candidate-${i}`)}</Show>
+            </>
+          )}
+        </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.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
new file mode 100644
index 000000000..931248b7a
--- /dev/null
+++ b/src/documents/DocumentViewer.tsx
@@ -0,0 +1,337 @@
+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';
+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;
+  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[];
+  /** 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;
+  /**
+   * 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.
+ * 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
+ * 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) };
+  });
+
+  // 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
+  // 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}
+      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) => (
+          <>
+            <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}
+            />
+          </>
+        )}
+      </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()}
+                hidden={props.visibleBlock?.(i()) === false}
+                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())}
+                {/* 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..ee4bd9d2f
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
@@ -0,0 +1,261 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore, store } from '../store/core';
+import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+import { documentStore, setDocumentComposerDraft } from './store';
+
+const { openInEditor, revealItemInDir, platform } = vi.hoisted(() => ({
+  openInEditor: vi.fn(() => Promise.resolve()),
+  revealItemInDir: vi.fn(() => Promise.resolve()),
+  platform: { isMac: false },
+}));
+
+vi.mock('../lib/shell', () => ({ openInEditor, revealItemInDir }));
+vi.mock('../lib/platform', () => ({
+  get isMac() {
+    return platform.isMac;
+  },
+  windowChromeTopInset: 34,
+  mod: 'Ctrl',
+  alt: 'Alt',
+}));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  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({
+      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('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: [
+        {
+          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.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
new file mode 100644
index 000000000..a94086d51
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -0,0 +1,734 @@
+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,
+  discardDocumentEdits,
+  dismissUndo,
+  documentStore,
+  goBackDocument,
+  openDocumentFile,
+  previousDocumentPath,
+  refreshDocumentSnapshot,
+  reviewableRuns,
+  setDocumentComposerDraft,
+  setDocumentSelection,
+  setDocumentView,
+  setShowResolvedAnnotations,
+  openDocumentCompare,
+  undoDeleteDocumentAnnotation,
+  type DocumentView,
+} from './store';
+import { resetWorkspaceUi } from './workspace-ui';
+import { activateDocumentAgentTask, releaseDocumentAgentTask } from './agent-task';
+import { findAnchorTarget } from './links';
+import { isMac, windowChromeTopInset } 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 { 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';
+
+/** 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;
+  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);
+  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;
+  });
+  // 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) {
+    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, 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);
+    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 '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}`;
+  };
+
+  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>
+        <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"
+            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={!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
+              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={(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>
+              <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 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;
+            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}
+        >
+          <RunComposer
+            selection={selection()}
+            blocks={blocks.blocks()}
+            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>
+      </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 [confirmDiscard, setConfirmDiscard] = createSignal(false);
+  const [discarding, setDiscarding] = createSignal(false);
+  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(),
+    ),
+  );
+
+  // 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() {
+    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)}`),
+    );
+  }
+
+  /** 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
+        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,
+      // 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>
+      ),
+    },
+  ];
+
+  return (
+    <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>
+        <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>
+          <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>
+          {/* 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) => (
+            <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>
+        <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}>
+          <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
+          </button>
+        </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"
+          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)} />
+      <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
new file mode 100644
index 000000000..de35ef1ef
--- /dev/null
+++ b/src/documents/FileTreePanel.tsx
@@ -0,0 +1,130 @@
+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;
+/** Mirrors MAX_FILES in electron/documents/files.ts: a list this long was cut. */
+const FILE_CAP = 5_000;
+
+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());
+  // 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).then(() => setListed(true)),
+    ),
+  );
+
+  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={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
new file mode 100644
index 000000000..5a99a669c
--- /dev/null
+++ b/src/documents/HistoryView.tsx
@@ -0,0 +1,241 @@
+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';
+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),
+  );
+  // 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() {
+    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={
+            <>
+              <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>}>
+            <Show
+              when={!diff.error}
+              fallback={<div class="docws-error">{errMessage(diff.error)}</div>}
+            >
+              <SourceDiff raw={diff() ?? ''} />
+            </Show>
+          </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,
+      });
+    },
+  );
+  // 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));
+
+  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' }}>
+            {count()} {count() === 1 ? 'commit' : 'commits'}
+          </span>
+        </div>
+        <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={list()}>
+          {(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/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
new file mode 100644
index 000000000..0856ff59d
--- /dev/null
+++ b/src/documents/ModelRows.tsx
@@ -0,0 +1,84 @@
+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)}
+                  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>
+                </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..db4aaab82
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.client.test.tsx
@@ -0,0 +1,108 @@
+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();
+});
+
+function folderInput(): HTMLInputElement {
+  const input = document.querySelector<HTMLInputElement>('[aria-label="Project folder"]');
+  if (!input) throw new Error('Project folder input did not render');
+  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: 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')
+    ?.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('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();
+  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..1dfdf6a92
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -0,0 +1,349 @@
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  on,
+  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);
+  let folderInput: HTMLInputElement | undefined;
+
+  // The path is what the dialog is about; typing starts there.
+  createEffect(() => {
+    if (!props.open) return;
+    requestAnimationFrame(() => folderInput?.focus());
+  });
+
+  // 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(() => {
+    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('');
+    // 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() {
+    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);
+    }
+  }
+
+  /** 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}`,
+    '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' }}
+              ref={folderInput}
+              aria-label="Project folder"
+              placeholder="/path/to/folder"
+              value={folder()}
+              onInput={(e) => setFolder(e.currentTarget.value)}
+              onKeyDown={submitOnEnter}
+            />
+            <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);
+              }}
+              onKeyDown={submitOnEnter}
+            />
+          </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..3214c0e79
--- /dev/null
+++ b/src/documents/PageBlocks.tsx
@@ -0,0 +1,129 @@
+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';
+
+/** 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;
+}
+
+/** 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. 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>();
+  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');
+      }
+    }),
+  );
+
+  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);
+    }
+  });
+
+  // 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 indices = marked();
+    if (!props.html || !body() || indices.length === 0) {
+      setAnchors([]);
+      return;
+    }
+    const created: MarkerAnchor[] = [];
+    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, 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/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
new file mode 100644
index 000000000..1e30e134c
--- /dev/null
+++ b/src/documents/RightPanel.tsx
@@ -0,0 +1,135 @@
+import { For, Show, createMemo } from 'solid-js';
+import { store } from '../store/core';
+import type { Project } from '../store/types';
+import { getAgentHookStatus } from '../store/agentHookStatus';
+import { isAgentAskingQuestion } from '../store/taskStatus';
+import { documentStore, openDocumentCompare, reviewableRuns } from './store';
+import { setRailTab, workspaceUi } from './workspace-ui';
+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;
+}
+
+/** 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>
+                <RejectRunButton run={run} label="Reject" />
+              </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 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 = () =>
+    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, 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"
+              aria-hidden="true"
+            >
+              !
+            </span>
+          </Show>
+        </button>
+        <button
+          type="button"
+          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 }}
+              aria-hidden="true"
+            >
+              {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>
+      <div class="docws-agent-tab" classList={{ 'is-hidden': workspaceUi.railTab !== 'agent' }}>
+        <DecisionStrip />
+        <AgentTerminal project={props.project} />
+      </div>
+      <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..40008f5dd
--- /dev/null
+++ b/src/documents/RunComposer.annotate.client.test.tsx
@@ -0,0 +1,145 @@
+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-task', () => ({
+  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 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();
+    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(),
+      { askWith: 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..c6115eb7f
--- /dev/null
+++ b/src/documents/RunComposer.client.test.tsx
@@ -0,0 +1,180 @@
+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-task', () => ({
+  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('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('');
+  });
+
+  it('defaults to proposals and makes direct editing an explicit choice', () => {
+    const host = mount(passage);
+
+    const task = tab(host, 'Edit with agent');
+    const proposals = tab(host, 'Proposals');
+    expect(proposals?.getAttribute('aria-selected')).toBe('true');
+    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(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', () => {
+    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..f64e521f0
--- /dev/null
+++ b/src/documents/RunComposer.draft.client.test.tsx
@@ -0,0 +1,87 @@
+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-task', () => ({
+  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..54ccc2242
--- /dev/null
+++ b/src/documents/RunComposer.tsx
@@ -0,0 +1,551 @@
+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 { sendToDocumentAgent } from './agent-task';
+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 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>('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;
+  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 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. */
+  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' ? { askWith: askAgent() } : {},
+      );
+      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(),
+    );
+    // A second Enter while the first is still typing into the terminal would
+    // send the instruction twice.
+    setSending(true);
+    try {
+      await sendToDocumentAgent(p, text);
+      finish();
+    } catch (err) {
+      showNotification(errMessage(err));
+    } finally {
+      setSending(false);
+    }
+  }
+
+  /** Work was handed off: clear the draft and the passage, keep the popover. */
+  function finish() {
+    setInstruction('');
+    props.onClose();
+  }
+
+  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();
+      props.onClose();
+      textareaRef?.blur();
+      return;
+    }
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      // The task terminal underneath treats Enter as its send shortcut.
+      e.stopPropagation();
+      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="Work 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" />
+            Edit with agent
+          </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>
+        <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>
+      </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>
+      {/* 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-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={`${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>
+      <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()}
+                title={installed().length === 0 ? 'No agent is installed.' : undefined}
+                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.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
new file mode 100644
index 000000000..f5b9ea9e6
--- /dev/null
+++ b/src/documents/RunsRail.tsx
@@ -0,0 +1,200 @@
+import { For, Show, createMemo, createSignal, onCleanup } from 'solid-js';
+import {
+  activeDocumentPath,
+  cancelDocumentRun,
+  candidateLogKey,
+  documentStore,
+  modelLabel,
+  openDocumentCompare,
+} 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';
+  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);
+  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' }}
+    >
+      <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>
+      </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>
+      <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>
+              <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>
+                </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'}>
+                  <RejectRunButton run={run} label={proposals() > 0 ? 'Reject all' : 'Dismiss'} />
+                </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-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/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..0f1a94a07
--- /dev/null
+++ b/src/documents/block-merge.test.ts
@@ -0,0 +1,284 @@
+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');
+  });
+
+  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
new file mode 100644
index 000000000..d77ec1d80
--- /dev/null
+++ b/src/documents/block-merge.ts
@@ -0,0 +1,272 @@
+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;
+}
+
+/** "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. 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);
+  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';
+}
+
+/**
+ * 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..47cc3d890
--- /dev/null
+++ b/src/documents/documents-styles.test.ts
@@ -0,0 +1,68 @@
+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('floats the popover over the window, placed by the marker with nothing to cross', () => {
+    const pop = rule('.docws-marker-pop');
+
+    // 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:/);
+  });
+
+  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/);
+  });
+});
+
+/* 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
new file mode 100644
index 000000000..1bffe4b84
--- /dev/null
+++ b/src/documents/documents.css
@@ -0,0 +1,2299 @@
+/* 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;
+  /* 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. 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;
+}
+
+.docws-title {
+  display: flex;
+  align-items: center;
+  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 {
+  color: var(--accent);
+  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;
+}
+
+.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);
+}
+
+/* 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;
+  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;
+  white-space: nowrap;
+}
+
+/* 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);
+}
+
+/* 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);
+}
+
+.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);
+  /* 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 ── */
+
+/* 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-tab.is-hidden {
+  display: none;
+}
+
+.docws-agent-pane {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-agent-term {
+  flex: 1;
+  min-height: 0;
+  position: relative;
+  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;
+  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;
+}
+
+/* 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;
+  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 ── */
+
+/* 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: fixed;
+  z-index: var(--docws-floating-z);
+  transform: translateY(-100%);
+  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);
+  font-family: var(--font-ui);
+  visibility: hidden;
+  opacity: 0;
+  transition:
+    opacity 0.1s ease,
+    visibility 0s linear 0.1s;
+}
+
+/* A beat after the pointer arrives, so sweeping down the prose does not flash
+   the bar on every block; gone at once when it leaves. */
+.docws-block-actions.is-open {
+  visibility: visible;
+  opacity: 1;
+  transition:
+    opacity 0.1s ease 0.12s,
+    visibility 0s;
+}
+
+.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);
+}
+
+/* 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
+   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.8;
+  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-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);
+}
+
+.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;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px 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);
+}
+
+.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 {
+  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 compare view
+   filling the rest of the window. */
+.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);
+  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 {
+  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-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;
+  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 {
+  flex: 0 1 360px;
+  min-width: 220px;
+  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);
+  outline: 2px solid var(--border-focus);
+  outline-offset: 2px;
+}
+
+.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.1em;
+  right: -34px;
+}
+
+/* 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: 3px 5px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-xs);
+  background: var(--bg-elevated);
+  color: var(--review);
+  line-height: 1;
+  cursor: pointer;
+}
+
+.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);
+}
+
+.docws-marker-count {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--fg-muted);
+}
+
+/* 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: fixed;
+  z-index: var(--docws-floating-z);
+  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);
+  font-family: var(--font-ui);
+  color: var(--fg);
+  line-height: 1.5;
+  text-align: left;
+  visibility: hidden;
+  opacity: 0;
+  transition:
+    opacity 0.1s ease 0.05s,
+    visibility 0s linear 0.15s;
+}
+
+.docws-marker-pop.is-open {
+  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;
+  /* 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;
+  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;
+}
+
+.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/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..65c8c4285
--- /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('puts the instruction first, then the document, the lines and the passage', () => {
+    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(
+      'Tighten this.\n\nDocument: notes.md\n\nScope: lines 4-6 (under "Plan").\n\n' +
+        'The passage, verbatim:\n> One.\n> Two.',
+    );
+  });
+
+  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('Rewrite the intro.\n\nDocument: notes.md\n\nScope: the whole document.');
+  });
+
+  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..842ae5e16
--- /dev/null
+++ b/src/documents/interactive-prompt.ts
@@ -0,0 +1,40 @@
+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 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,
+  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 = [instruction.trim(), `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}`);
+  }
+  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.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
new file mode 100644
index 000000000..59db0c1e5
--- /dev/null
+++ b/src/documents/store.ts
@@ -0,0 +1,939 @@
+/**
+ * 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;
+  /** 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;
+  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;
+  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,
+  composerDraft: null,
+  snapshot: null,
+  loading: false,
+  error: null,
+  runs: {},
+  runOrder: [],
+  logs: {},
+  view: 'document',
+  compareRunId: null,
+  compareCandidateId: 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,
+    documentTrail: [],
+    snapshot: null,
+    loading: true,
+    error: null,
+    runs: {},
+    runOrder: [],
+    logs: {},
+    view: 'document',
+    compareRunId: null,
+    compareCandidateId: 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 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) return;
+  stopCurrentWatcher();
+  setDocStore({
+    documentPath,
+    documentTrail,
+    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,
+    documentTrail: [],
+    selection: null,
+    view: 'document',
+    compareRunId: null,
+    compareCandidateId: 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, candidateId?: string): void {
+  setDocStore({ compareRunId: runId, compareCandidateId: candidateId ?? null });
+}
+
+export function closeDocumentCompare(): void {
+  setDocStore({ compareRunId: null, compareCandidateId: 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, 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,
+  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 revision = await invoke<DocumentRunRecord>(IPC.DispatchDocumentRun, {
+    projectRoot: project.path,
+    documentPath: run.documentPath,
+    instruction,
+    scope: { wholeDocument: true },
+    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 {
+    const run = await invoke<DocumentRunRecord>(IPC.RejectDocumentRun, {
+      projectRoot: project.path,
+      runId,
+    });
+    upsertRun(run);
+    if (docStore.compareRunId === runId)
+      setDocStore({ compareRunId: null, compareCandidateId: 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;
+  }
+}
+
+/** 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> {
+  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;
+}
+
+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,
+  options: AddAnnotationOptions = {},
+): 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,
+      followUpOf: options.followUpOf,
+    });
+    if (kind === 'question' && options.askWith)
+      await askDocumentAnnotation(saved.id, options.askWith);
+    return saved;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return null;
+  }
+}
+
+/** 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);
+  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..473f91749
--- /dev/null
+++ b/src/documents/workspace-ui.ts
@@ -0,0 +1,100 @@
+/**
+ * Panel state of the open workspace: the project's files, which rail tab is
+ * 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';
+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;
+}
+
+const [ui, setUi] = createStore<WorkspaceUiState>({
+  files: [],
+  filesError: null,
+  railTab: 'agent',
+  output: null,
+});
+
+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);
+}
+
+/** Back to the defaults when a workspace opens; files are per project. */
+export function resetWorkspaceUi(): void {
+  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/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-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
new file mode 100644
index 000000000..55ee427d9
--- /dev/null
+++ b/src/lib/mermaid.client.test.tsx
@@ -0,0 +1,93 @@
+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('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>');
+
+    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..74a7a865d
--- /dev/null
+++ b/src/lib/mermaid.ts
@@ -0,0 +1,38 @@
+/**
+ * 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)
+ */
+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)');
+  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');
+            // 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));
+      });
+    })
+    .catch((err) => console.warn('[mermaid] load 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/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 57b7a0405..d94933e16 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..3f9c01443 100644
--- a/src/store/core.ts
+++ b/src/store/core.ts
@@ -90,6 +90,9 @@ export const [store, setStore] = createStore<AppStore>({
   taskSplitMode: {},
   verboseLogging: false,
   coordinatorModeEnabled: false,
+  documentWorkspacesEnabled: false,
+  documentFullWidth: false,
+  activeDocumentProjectId: null,
   coordinatorNotificationDelayMs: 60_000,
   coordinatorControlHintDismissed: false,
   defaultStepsEnabled: false,
diff --git a/src/store/persistence.test.ts b/src/store/persistence.test.ts
index 3667f356f..c875299f3 100644
--- a/src/store/persistence.test.ts
+++ b/src/store/persistence.test.ts
@@ -1045,6 +1045,59 @@ describe('showSteps → defaultStepsEnabled migration', () => {
   });
 });
 
+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();
+  });
+});
+
 describe('saveState failure reporting', () => {
   it('tells the user when the state file could not be written', async () => {
     vi.useFakeTimers();
diff --git a/src/store/persistence.ts b/src/store/persistence.ts
index 4ccf0c7fb..38d87e0f9 100644
--- a/src/store/persistence.ts
+++ b/src/store/persistence.ts
@@ -246,6 +246,8 @@ 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,
+    documentFullWidth: store.documentFullWidth || undefined,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed || undefined,
     defaultStepsEnabled: store.defaultStepsEnabled || undefined,
     defaultSkipPermissions: store.defaultSkipPermissions || undefined,
@@ -433,6 +435,8 @@ interface LegacyPersistedState {
   darkThemePreset?: unknown;
   darkThemeCustomId?: unknown;
   coordinatorModeEnabled?: unknown;
+  documentWorkspacesEnabled?: unknown;
+  documentFullWidth?: unknown;
   coordinatorControlHintDismissed?: unknown;
   defaultStepsEnabled?: unknown;
   defaultSkipPermissions?: unknown;
@@ -631,6 +635,8 @@ 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;
 
@@ -881,16 +887,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/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 9a8aef115..30baebe2b 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 },
@@ -1556,6 +1569,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..6d42c7210 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,8 @@ export interface PersistedState {
   darkThemePreset?: LookPreset;
   darkThemeCustomId?: string | null;
   coordinatorModeEnabled?: boolean;
+  documentWorkspacesEnabled?: boolean;
+  documentFullWidth?: boolean;
   coordinatorNotificationDelayMs?: number;
   coordinatorControlHintDismissed?: boolean;
   defaultStepsEnabled?: boolean;
@@ -435,6 +463,11 @@ export interface AppStore {
   darkThemePreset: LookPreset;
   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;
   coordinatorControlHintDismissed: boolean;
   defaultStepsEnabled: boolean;
diff --git a/src/store/ui.ts b/src/store/ui.ts
index 23869d966..f529288cb 100644
--- a/src/store/ui.ts
+++ b/src/store/ui.ts
@@ -270,6 +270,15 @@ 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 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 52c5e1276..8269fb7a6 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -2586,11 +2586,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%,
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 d214c76a7..bf02ab4fa 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);