From ea36a008c3c5905485c24946ae254a6104577d53 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 3 Sep 2026 23:08:57 +0000
Subject: [PATCH 01/12] feat(documents): add document workspaces behind an
 experimental flag

A new project kind for exploring problems in prose: a Git repository
plus one Markdown document. Select a passage, send the same instruction
to one or more agents, compare the proposals side by side, accept one as
a single readable commit.

Backend (electron/ipc/documents.ts):
- Dispatch commits pending manual edits, snapshots the base, gives every
  candidate its own worktree and runs the official CLI headlessly
  (claude -p stream-json with read/edit tools only, codex exec --json,
  gemini -p json). Process exit means the proposal is ready.
- The main session keeps a persistent worktree so its cwd (and the
  provider's prompt cache) never changes, resumes by session id, and is
  handed the diff of the canonical document since it last saw it.
- Out-of-scope files are reverted and listed; hunks outside the selected
  passage are counted. The structured rationale the prompt asks for
  becomes the proposal commit message with Parallel-* trailers.
- Acceptance is one squashed integration commit carrying the run record;
  a base that moved is merged three-way or marked stale. Rejection
  commits the record alone so history stays readable.
- Document watcher, history with parsed trailers, version and diff at a
  commit, revert.

Renderer (src/documents, src/store/documents.ts):
- Full-window workspace with Document, Compare and History tabs.
- Block-level rendering with source line mapping (src/lib/markdown-blocks),
  selection by text, block or heading section, and an in-place composer
  with agent chips and candidate counts.
- Compare view: rationale first, rendered base and candidates, changed
  blocks marked and navigable, model-blind by default, source diff
  toggle, per-candidate notes, accept or reject.
- Document project creation from the sidebar, flag in Settings.

Tests cover the prompt and rationale parsing, CLI launch and output
parsers, scope checks, block mapping and diffing, and the full lifecycle
against a real temporary repository with a fake agent. An env-gated test
drives the real claude CLI through a proposal, acceptance and a resumed
follow-up.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UP9JjPPAYEBBNe1VbGnSzU
---
 .gitignore                                    |    1 +
 docs/document-workspaces.md                   |  150 +++
 electron/ipc/channel-manifest.json            |   18 +-
 electron/ipc/document-agents.test.ts          |  170 +++
 electron/ipc/document-agents.ts               |  295 +++++
 electron/ipc/document-prompt.test.ts          |   98 ++
 electron/ipc/document-prompt.ts               |  129 ++
 electron/ipc/documents.integration.test.ts    |  234 ++++
 .../documents.real-claude.integration.test.ts |  150 +++
 electron/ipc/documents.test.ts                |   70 ++
 electron/ipc/documents.ts                     | 1040 +++++++++++++++++
 electron/ipc/register.ts                      |  110 ++
 electron/ipc/shared-types.ts                  |  123 ++
 electron/main.ts                              |    3 +
 electron/preload.cjs                          |   16 +
 electron/shared/document-agents.ts            |   29 +
 src/App.tsx                                   |   11 +
 src/components/SettingsDialog.tsx             |    9 +
 src/components/Sidebar.tsx                    |   37 +-
 src/documents/CompareView.tsx                 |  305 +++++
 src/documents/DocumentViewer.tsx              |  164 +++
 src/documents/DocumentWorkspaceOverlay.tsx    |  268 +++++
 src/documents/HistoryView.tsx                 |  212 ++++
 src/documents/NewDocumentProjectDialog.tsx    |  181 +++
 src/documents/RunComposer.tsx                 |  211 ++++
 src/documents/RunsRail.tsx                    |  127 ++
 src/documents/SourceDiff.tsx                  |   43 +
 src/documents/documents.css                   |  895 ++++++++++++++
 src/documents/use-blocks.ts                   |   61 +
 src/ipc/types.ts                              |   10 +
 src/lib/markdown-blocks.test.ts               |  129 ++
 src/lib/markdown-blocks.ts                    |  220 ++++
 src/store/autosave.ts                         |    1 +
 src/store/core.ts                             |    2 +
 src/store/documents.ts                        |  441 +++++++
 src/store/persistence.ts                      |    3 +
 src/store/projects.ts                         |   31 +
 src/store/store.ts                            |    3 +
 src/store/types.ts                            |   20 +
 src/store/ui.ts                               |    5 +
 40 files changed, 6021 insertions(+), 4 deletions(-)
 create mode 100644 docs/document-workspaces.md
 create mode 100644 electron/ipc/document-agents.test.ts
 create mode 100644 electron/ipc/document-agents.ts
 create mode 100644 electron/ipc/document-prompt.test.ts
 create mode 100644 electron/ipc/document-prompt.ts
 create mode 100644 electron/ipc/documents.integration.test.ts
 create mode 100644 electron/ipc/documents.real-claude.integration.test.ts
 create mode 100644 electron/ipc/documents.test.ts
 create mode 100644 electron/ipc/documents.ts
 create mode 100644 electron/shared/document-agents.ts
 create mode 100644 src/documents/CompareView.tsx
 create mode 100644 src/documents/DocumentViewer.tsx
 create mode 100644 src/documents/DocumentWorkspaceOverlay.tsx
 create mode 100644 src/documents/HistoryView.tsx
 create mode 100644 src/documents/NewDocumentProjectDialog.tsx
 create mode 100644 src/documents/RunComposer.tsx
 create mode 100644 src/documents/RunsRail.tsx
 create mode 100644 src/documents/SourceDiff.tsx
 create mode 100644 src/documents/documents.css
 create mode 100644 src/documents/use-blocks.ts
 create mode 100644 src/lib/markdown-blocks.test.ts
 create mode 100644 src/lib/markdown-blocks.ts
 create mode 100644 src/store/documents.ts

diff --git a/.gitignore b/.gitignore
index 7d5ed2181..ff871a58d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ update-test/
 # Keep generated docs content ignored, but track the authored architecture overview.
 docs/*
 !docs/architecture-overview.html
+!docs/document-workspaces.md
 
 # Sandbox bind-mount artifacts from user home (not project files).
 # Root-anchored so legitimate nested files with these names are still tracked.
diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
new file mode 100644
index 000000000..71dc0279f
--- /dev/null
+++ b/docs/document-workspaces.md
@@ -0,0 +1,150 @@
+# 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 and 2 of the plan below are built; annotations and HTML are not.
+
+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**. Pick a Git repository and
+   one tracked Markdown file in it.
+3. The workspace opens full-window with three tabs: **Document**, **Compare**, **History**.
+4. In the document, select text, click a block, or press **§** next to a heading to select
+   the section. A composer opens under the selection: type an instruction, pick agents and
+   candidate counts, press Enter.
+5. Proposals appear in the right-hand rail as they finish. **Review** (one candidate) or
+   **Compare** (several) opens the compare view: base on the left, candidates to the right,
+   each starting with its rationale. Accept one, or reject all.
+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.
+
+### How it works
+
+- **Editing happens in your editor.** The app watches the file and re-renders; an external
+  change drops any active selection.
+- **Dispatch commits pending edits first** as a plain `Manual edits` commit so every run
+  has a real base. Files under `.parallel/` are left 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`, `gemini -p --output-format json --approval-mode auto_edit`.
+  Process exit means the proposal is ready.
+- **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.
+- **Scope is enforced, not trusted.** Files the agent touched outside the document are
+  reverted before the proposal commit and listed on the candidate. 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.
+- **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.
+  Rejection commits the run record alone, so the history view (which excludes `.parallel/`)
+  never shows it.
+- **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.
+- **Run records are versioned** (`version: 1`) so a format change is a migration.
+
+### Not in this slice
+
+Annotations, HTML documents, partial acceptance, evaluator agents, refinement rounds,
+durable anchors across versions, in-app editing. Custom agents without a known headless
+mode cannot be picked. Agents other than Claude Code and Codex run one-shot only.
+
+---
+
+## 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
+
+1. Annotations: bubbles on anchors, agent-answered questions, single-keypress dismissal.
+2. HTML: static sandboxed preview with DOM-to-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/ipc/channel-manifest.json b/electron/ipc/channel-manifest.json
index 3eeba5c8d..0a1b9afae 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -147,5 +147,21 @@
   "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",
+  "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",
+  "ListDocumentFiles": "list_document_files",
+  "DocumentChanged": "document_changed",
+  "DocumentRunEvent": "document_run_event"
 }
diff --git a/electron/ipc/document-agents.test.ts b/electron/ipc/document-agents.test.ts
new file mode 100644
index 000000000..54c69b58e
--- /dev/null
+++ b/electron/ipc/document-agents.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildHeadlessLaunch,
+  createHeadlessParser,
+  CLAUDE_DOCUMENT_TOOLS,
+} from './document-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('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('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('opencode');
+    const log = parser.feed('one\ntwo\n');
+    expect(log).toEqual(['one', 'two']);
+    expect(parser.finish().resultText).toBe('one\ntwo\n');
+  });
+});
diff --git a/electron/ipc/document-agents.ts b/electron/ipc/document-agents.ts
new file mode 100644
index 000000000..144f15117
--- /dev/null
+++ b/electron/ipc/document-agents.ts
@@ -0,0 +1,295 @@
+/**
+ * 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/document-agents.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;
+}
+
+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';
+
+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',
+        'acceptEdits',
+        '--tools',
+        CLAUDE_DOCUMENT_TOOLS,
+      ];
+      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', 'workspace-write', '--skip-git-repo-check'];
+      if (resume) args.push('resume', resume, opts.prompt);
+      else args.push(opts.prompt);
+      return { command: opts.command, args };
+    }
+    case 'gemini':
+      return {
+        command: opts.command,
+        args: ['-p', opts.prompt, '--output-format', 'json', '--approval-mode', 'auto_edit'],
+      };
+    case 'opencode':
+      return { command: opts.command, args: ['run', opts.prompt] };
+    case 'copilot':
+      return { command: opts.command, args: ['-p', opts.prompt, '--allow-all-tools'] };
+    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) {
+          this.error = text ?? asString(event.error) ?? '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/ipc/document-prompt.test.ts b/electron/ipc/document-prompt.test.ts
new file mode 100644
index 000000000..f192f81d0
--- /dev/null
+++ b/electron/ipc/document-prompt.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import { buildDocumentPrompt, parseDocumentRationale } from './document-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('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/ipc/document-prompt.ts b/electron/ipc/document-prompt.ts
new file mode 100644
index 000000000..42537c5d5
--- /dev/null
+++ b/electron/ipc/document-prompt.ts
@@ -0,0 +1,129 @@
+import type { DocumentRationale, DocumentScope } from './shared-types.js';
+
+/** Largest diff (in characters) handed to a resumed main session. */
+const MAX_CATCH_UP_DIFF_CHARS = 20_000;
+
+export interface DocumentPromptInput {
+  documentPath: string;
+  scope: DocumentScope;
+  instruction: string;
+  /** Diff of the canonical document since the resumed session last saw it. */
+  catchUpDiff?: string;
+}
+
+function quoteBlock(text: string): string {
+  return text
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n');
+}
+
+/** Builds the instruction a headless agent receives for one proposal. */
+export function buildDocumentPrompt(input: DocumentPromptInput): string {
+  const { documentPath, scope, instruction } = input;
+  const parts: string[] = [];
+
+  parts.push(
+    'You are revising a document in a Parallel Code document workspace. ' +
+      'Your working directory is an isolated copy of the project; the file on disk is the current version.',
+  );
+
+  if (input.catchUpDiff?.trim()) {
+    const diff =
+      input.catchUpDiff.length > MAX_CATCH_UP_DIFF_CHARS
+        ? input.catchUpDiff.slice(0, MAX_CATCH_UP_DIFF_CHARS) + '\n… (diff truncated)'
+        : input.catchUpDiff;
+    parts.push(
+      'Since your previous turn the canonical document changed. Do not rely on the version you remember; ' +
+        're-read the file. The changes were:\n```diff\n' +
+        diff +
+        '\n```',
+    );
+  }
+
+  parts.push(`Document: ${documentPath}`);
+
+  if (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');
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((v): v is string => typeof v === 'string' && v.trim().length > 0);
+}
+
+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' ? obj.summary.trim() : '';
+  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/ipc/documents.integration.test.ts b/electron/ipc/documents.integration.test.ts
new file mode 100644
index 000000000..f0994039b
--- /dev/null
+++ b/electron/ipc/documents.integration.test.ts
@@ -0,0 +1,234 @@
+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,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentFiles,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+} from './documents.js';
+import type { DocumentRunEvent, DocumentRunRecord } from './shared-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',
+      '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 tracked markdown files', async () => {
+    expect(await listDocumentFiles(root)).toEqual(['README.md', 'docs/spec.md']);
+  });
+
+  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.
+    fs.appendFileSync(path.join(root, 'README.md'), 'manual\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(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).toEqual(['STRAY.txt']);
+    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);
+  });
+
+  it('marks a proposal stale when the base moved and it conflicts, and rejects cleanly otherwise', 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/ipc/documents.real-claude.integration.test.ts b/electron/ipc/documents.real-claude.integration.test.ts
new file mode 100644
index 000000000..ce63fab14
--- /dev/null
+++ b/electron/ipc/documents.real-claude.integration.test.ts
@@ -0,0 +1,150 @@
+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 './documents.js';
+import type { DocumentRunEvent, DocumentRunRecord } from './shared-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/ipc/documents.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 win = {
+    isDestroyed: () => false,
+    webContents: { send: (_ch: string, payload: DocumentRunEvent) => events.push(payload) },
+  } 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);
+});
diff --git a/electron/ipc/documents.test.ts b/electron/ipc/documents.test.ts
new file mode 100644
index 000000000..401a8fd8d
--- /dev/null
+++ b/electron/ipc/documents.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import {
+  countOutOfScopeHunks,
+  parseCommitBody,
+  validateDocumentPath,
+  validateSha,
+} from './documents.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('')).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({});
+  });
+});
diff --git a/electron/ipc/documents.ts b/electron/ipc/documents.ts
new file mode 100644
index 000000000..53b84f76e
--- /dev/null
+++ b/electron/ipc/documents.ts
@@ -0,0 +1,1040 @@
+/**
+ * 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. Nothing in
+ * here changes the canonical document except `acceptDocumentCandidate`.
+ */
+import { execFile, spawn, type ChildProcess } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from './channels.js';
+import { debug as logDebug, errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from './pty.js';
+import { loadEnvFile } from './env-file.js';
+import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from './git.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './document-agents.js';
+import { buildDocumentPrompt, parseDocumentRationale } from './document-prompt.js';
+import { MAX_DOCUMENT_CANDIDATES } from '../shared/document-agents.js';
+import type {
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentHistoryEntry,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from './shared-types.js';
+
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 20 * 1024 * 1024;
+/** 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');
+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;
+
+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;
+}
+
+async function gitOk(cwd: string, args: string[]): Promise<boolean> {
+  try {
+    await git(cwd, args);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- Validation -----------------------------------------------------------
+
+/** A document path is repo-relative and stays inside the project. */
+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 (normalized.startsWith('.parallel/') || normalized.startsWith('.worktrees/'))
+    throw new Error('documentPath must not point into .parallel or .worktrees');
+  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;
+}
+
+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 command = str('command');
+    if (/[\s;&|<>$`'"\\]/.test(command)) throw new Error('candidate.command is invalid');
+    const sessionId = optStr('sessionId');
+    if (sessionId && !/^[A-Za-z0-9_.-]{1,128}$/.test(sessionId))
+      throw new Error('candidate.sessionId is invalid');
+    return {
+      id,
+      label,
+      agentId: str('agentId'),
+      agentName: str('agentName').slice(0, 64),
+      command,
+      isMain: c.isMain === true,
+      sessionId,
+      sessionLastSha: optStr('sessionLastSha'),
+      envFile: optStr('envFile'),
+    };
+  });
+}
+
+// --- 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 that leaves run records out of "pending edits": they are committed
+ *  explicitly by acceptance and rejection so they never bury content commits. */
+const CONTENT_PATHSPEC = ['--', '.', ':(exclude).parallel'];
+
+async function isDirty(projectRoot: string): Promise<boolean> {
+  const out = await git(projectRoot, [
+    'status',
+    '--porcelain',
+    '--untracked-files=all',
+    ...CONTENT_PATHSPEC,
+  ]);
+  return out.trim().length > 0;
+}
+
+export async function readDocumentSnapshot(
+  projectRoot: string,
+  documentPath: string,
+): Promise<DocumentSnapshot> {
+  const abs = path.join(projectRoot, documentPath);
+  let content = '';
+  let missing = false;
+  try {
+    content = await fs.promises.readFile(abs, '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 };
+}
+
+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');
+}
+
+function readRunRecord(projectRoot: string, runId: string): DocumentRunRecord | null {
+  try {
+    const raw = fs.readFileSync(runRecordPath(projectRoot, runId), 'utf-8');
+    const parsed = JSON.parse(raw) as DocumentRunRecord;
+    if (parsed.version !== 1 || !Array.isArray(parsed.candidates)) return null;
+    return parsed;
+  } 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>;
+  cancelled: boolean;
+}
+
+interface ActiveRun {
+  projectRoot: string;
+  candidates: Map<string, ActiveCandidate>;
+}
+
+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();
+}
+
+/** 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;
+}
+
+// --- Pending manual edits -------------------------------------------------
+
+/**
+ * Commits whatever the user changed in the checkout 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);
+  if (await isDirty(projectRoot)) {
+    await git(projectRoot, ['add', '-A', ...CONTENT_PATHSPEC]);
+    await git(projectRoot, ['commit', '-q', '-m', 'Manual edits']);
+  }
+  const sha = await headSha(projectRoot);
+  if (!sha) throw new Error('The project repository has no commits yet.');
+  return sha;
+}
+
+// --- 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;
+  }
+  await git(worktreePath, ['reset', '--hard', '-q']);
+  await git(worktreePath, ['clean', '-fdq']);
+  await git(worktreePath, ['checkout', '-q', '-B', branch, baseSha]);
+  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> {
+  if (candidate.isMain) {
+    // The persistent worktree stays; only drop the branch when it is no
+    // longer checked out there (the next dispatch moves it anyway).
+    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;
+}
+
+function parseChangedPaths(porcelainZ: string): string[] {
+  const out: string[] = [];
+  for (const entry of porcelainZ.split('\0')) {
+    if (!entry.trim()) continue;
+    // "XY path" or "XY orig -> path" (renames use a second NUL entry; the
+    // first path after the status is what we act on).
+    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;
+}
+
+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 {
+    const changed = parseChangedPaths(
+      await git(worktreePath, ['status', '--porcelain', '-z', '--untracked-files=all']),
+    );
+    const docPath = run.documentPath;
+    const outOfScope = changed.filter((p) => p !== docPath);
+    if (outOfScope.length > 0) {
+      // 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);
+      candidate.outOfScopeFiles = outOfScope.slice(0, 50);
+    }
+
+    const docChanged = !(await gitOk(worktreePath, ['diff', '--quiet', '--', 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', '--', docPath]);
+    const strayHunks = countOutOfScopeHunks(diffU0, run.scope);
+    if (strayHunks > 0) candidate.outOfScopeHunks = strayHunks;
+
+    const body = [
+      commitTitle(rationale.summary, `Proposal from ${candidate.agentName}`),
+      '',
+      ...rationale.changes.map((c) => `- ${c}`),
+      '',
+      trailerBlock([
+        ['Run', run.id],
+        ['Agent', candidate.agentName],
+        ['Candidate', candidate.label],
+        ['Scope', scopeTrailer(run.scope)],
+        ['Base', run.baseSha],
+      ]),
+    ].join('\n');
+    await git(worktreePath, ['add', '--', docPath]);
+    await git(worktreePath, ['commit', '-q', '-m', body]);
+    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;
+  }
+}
+
+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(),
+  });
+  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'],
+  });
+
+  const entry: ActiveCandidate = {
+    proc,
+    cancelled: false,
+    timer: setTimeout(() => {
+      candidate.error = 'Timed out.';
+      proc.kill('SIGTERM');
+    }, 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;
+    sendEvent(win, { type: 'log', runId: run.id, candidateId: candidate.id, text: clipped });
+  };
+
+  proc.stdout?.on('data', (chunk: Buffer) => {
+    for (const line of parser.feed(chunk.toString('utf8'))) log(line);
+  });
+  proc.stderr?.on('data', (chunk: Buffer) => {
+    const text = chunk.toString('utf8');
+    stderrTail = (stderrTail + text).slice(-STDERR_TAIL_CHARS);
+    if (text.trim()) log(text.trimEnd());
+  });
+
+  let settled = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(entry.timer);
+    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);
+    sendEvent(win, { type: 'candidate', runId: run.id, candidate });
+    if (active.candidates.size === 0) {
+      activeRuns.delete(run.id);
+      run.status = 'finished';
+      run.finishedAt = nowIso();
+    }
+    try {
+      writeRunRecord(projectRoot, run);
+    } catch (err) {
+      console.warn('[documents] failed to write run record:', err);
+    }
+    if (run.status === 'finished') sendEvent(win, { type: 'run', run });
+  };
+
+  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;
+  const scope = validateScope(args.scope, documentPath);
+  const specs = validateCandidateSpecs(args.candidates);
+  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 () => {
+    if (!fs.existsSync(path.join(projectRoot, documentPath)))
+      throw new Error(`Document not found: ${documentPath}`);
+    const baseSha = await commitPendingEdits(projectRoot);
+    const runId = randomUUID();
+    const run: DocumentRunRecord = {
+      version: 1,
+      id: runId,
+      documentPath,
+      createdAt: nowIso(),
+      instruction,
+      scope,
+      baseSha,
+      status: 'running',
+      candidates: [],
+    };
+
+    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,
+          branch,
+          worktreePath,
+          status: 'running',
+          commitSha: null,
+          startedAt: nowIso(),
+        };
+        run.candidates.push(candidate);
+        prepared.push({ spec, candidate });
+      }
+    } catch (err) {
+      for (const { candidate } of prepared) await cleanupCandidate(projectRoot, candidate);
+      throw err;
+    }
+
+    writeRunRecord(projectRoot, run);
+    activeRuns.set(runId, { projectRoot, candidates: new Map() });
+
+    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 });
+      try {
+        spawnCandidate(win, projectRoot, run, spec, candidate, prompt);
+      } catch (err) {
+        candidate.status = 'failed';
+        candidate.error = errMessage(err);
+        candidate.finishedAt = nowIso();
+      }
+    }
+
+    const active = activeRuns.get(runId);
+    if (active && active.candidates.size === 0) {
+      activeRuns.delete(runId);
+      run.status = 'finished';
+      run.finishedAt = nowIso();
+    }
+    writeRunRecord(projectRoot, run);
+    sendEvent(win, { type: 'run', run });
+    return run;
+  });
+}
+
+export function cancelDocumentRun(runId: unknown): void {
+  const id = validateRunId(runId);
+  const active = activeRuns.get(id);
+  if (!active) return;
+  for (const entry of active.candidates.values()) {
+    entry.cancelled = true;
+    entry.proc.kill('SIGTERM');
+  }
+}
+
+// --- Accept / reject ------------------------------------------------------
+
+function integrationMessage(run: DocumentRunRecord, candidate: DocumentCandidateRecord): string {
+  const rationale = candidate.rationale;
+  const lines = [
+    commitTitle(rationale?.summary ?? '', `Accept proposal from ${candidate.agentName}`),
+    '',
+  ];
+  if (rationale?.changes.length) lines.push(...rationale.changes.map((c) => `- ${c}`), '');
+  if (rationale?.assumptions.length)
+    lines.push('Assumptions:', ...rationale.assumptions.map((c) => `- ${c}`), '');
+  if (rationale?.questions.length)
+    lines.push('Open questions:', ...rationale.questions.map((c) => `- ${c}`), '');
+  lines.push(
+    trailerBlock([
+      ['Run', run.id],
+      ['Agent', candidate.agentName],
+      ['Candidate', candidate.label],
+      ['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,
+): Promise<{ sha: string }> {
+  const runId = validateRunId(runIdRaw);
+  const candidateId = validateCandidateId(candidateIdRaw);
+  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 (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.finishedAt = run.finishedAt ?? nowIso();
+    writeRunRecord(projectRoot, run);
+    try {
+      await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      await git(projectRoot, ['commit', '-q', '-m', integrationMessage(run, candidate)]);
+    } catch (err) {
+      await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
+      run.status = 'finished';
+      run.acceptedCandidateId = 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);
+  cancelDocumentRun(runId);
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    if (run.status === 'accepted') throw new Error('An accepted run cannot be rejected.');
+    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)]);
+      await git(projectRoot, [
+        'commit',
+        '-q',
+        '-m',
+        `Reject proposals\n\nParallel-Run: ${runId}\nParallel-Metadata: true`,
+        '--',
+        runRecordRelPath(runId),
+      ]);
+    } 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,
+): DocumentRunRecord {
+  const runId = validateRunId(runIdRaw);
+  const candidateId = validateCandidateId(candidateIdRaw);
+  if (typeof note !== 'string') throw new Error('note must be a string');
+  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. Exported for tests. */
+export function parseCommitBody(body: string): { text: string; trailers: Record<string, string> } {
+  const trailers: Record<string, string> = {};
+  const text: string[] = [];
+  for (const line of body.split('\n')) {
+    const m = TRAILER_RE.exec(line.trim());
+    if (m) trailers[m[1]] = m[2].trim();
+    else text.push(line);
+  }
+  return { text: text.join('\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;
+  }
+}
+
+/** 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 {
+    // Root commit: nothing to diff against.
+    return '';
+  }
+}
+
+export async function revertDocumentCommit(projectRoot: string, sha: string): Promise<string> {
+  return withProjectLock(projectRoot, async () => {
+    await commitPendingEdits(projectRoot);
+    try {
+      await git(projectRoot, ['revert', '--no-edit', sha]);
+    } catch (err) {
+      await gitOk(projectRoot, ['revert', '--abort']);
+      throw new Error(`Revert failed: ${errMessage(err)}`);
+    }
+    return (await git(projectRoot, ['rev-parse', 'HEAD'])).trim();
+  });
+}
+
+/** Markdown files tracked in the repository, for the document picker. */
+export async function listDocumentFiles(projectRoot: string): Promise<string[]> {
+  try {
+    const out = await git(projectRoot, ['ls-files', '-z', '--', '*.md', '*.markdown']);
+    return out
+      .split('\0')
+      .filter((p) => p && !p.startsWith('.parallel/') && !p.startsWith('.worktrees/'))
+      .slice(0, 1000);
+  } catch {
+    return [];
+  }
+}
+
+/** Kill every running proposal process; used on app quit. */
+export function stopAllDocumentRuns(): void {
+  for (const [runId] of activeRuns) cancelDocumentRun(runId);
+}
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index aadab018a..748a94581 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -94,6 +94,24 @@ import {
 } from './updater.js';
 import { spawn } from 'child_process';
 import { askAboutCode, cancelAskAboutCode } from './ask-code.js';
+import {
+  acceptDocumentCandidate,
+  cancelDocumentRun,
+  dispatchDocumentRun,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentFiles,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+  revertDocumentCommit,
+  setDocumentCandidateNote,
+  startDocumentWatcher,
+  stopDocumentWatcher,
+  validateDocumentPath,
+  validateSha,
+} from './documents.js';
 import { setMinimaxApiKey } from './ask-code-minimax.js';
 import { getSystemMonospaceFonts } from './system-fonts.js';
 import { fetchClaudeUsage } from './claude-usage.js';
@@ -962,6 +980,98 @@ export function registerAllHandlers(win: BrowserWindow): void {
     cancelAskAboutCode(args.requestId);
   });
 
+  // --- Document workspaces ---
+  // Every handler takes the project root from the renderer and validates it;
+  // the document path is repo-relative and checked against traversal.
+  ipcMain.handle(IPC.ReadDocument, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    return readDocumentSnapshot(projectRoot, validateDocumentPath(args.documentPath));
+  });
+
+  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.ListDocumentFiles, (_e, args) => {
+    return listDocumentFiles(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.ListDocumentRuns, (_e, args) => {
+    return listDocumentRuns(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.DispatchDocumentRun, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    return dispatchDocumentRun(win, {
+      projectRoot,
+      documentPath: args.documentPath,
+      instruction: args.instruction,
+      scope: args.scope,
+      candidates: args.candidates,
+    });
+  });
+
+  ipcMain.handle(IPC.CancelDocumentRun, (_e, args) => {
+    cancelDocumentRun(args.runId);
+  });
+
+  ipcMain.handle(IPC.AcceptDocumentCandidate, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    return acceptDocumentCandidate(projectRoot, args.runId, args.candidateId);
+  });
+
+  ipcMain.handle(IPC.RejectDocumentRun, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    return rejectDocumentRun(projectRoot, args.runId);
+  });
+
+  ipcMain.handle(IPC.SetDocumentCandidateNote, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    return setDocumentCandidateNote(projectRoot, 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) => {
+    const projectRoot = projectRootArg(args);
+    return getDocumentAtCommit(
+      projectRoot,
+      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) => {
+    const projectRoot = projectRootArg(args);
+    return revertDocumentCommit(projectRoot, validateSha(args.sha));
+  });
+
   // --- File links ---
   ipcMain.handle(IPC.OpenPath, (_e, args) => {
     validatePath(args.filePath, 'filePath');
diff --git a/electron/ipc/shared-types.ts b/electron/ipc/shared-types.ts
index b0ae28be5..9eb653376 100644
--- a/electron/ipc/shared-types.ts
+++ b/electron/ipc/shared-types.ts
@@ -221,3 +221,126 @@ export type UsageResult =
   | { status: 'unavailable'; reason: string }
   /** Transient failure — the renderer keeps its last good snapshot. */
   | { status: 'error'; message: string };
+
+// --- Document workspaces ---
+
+/** 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;
+  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[];
+  acceptedCandidateId?: string;
+  finishedAt?: string;
+}
+
+/** Streamed from the main process while a run is in flight. */
+export type DocumentRunEvent =
+  | { type: 'log'; runId: string; candidateId: string; text: string }
+  | { type: 'candidate'; runId: string; candidate: DocumentCandidateRecord }
+  | { type: 'run'; run: DocumentRunRecord };
+
+export interface DocumentCandidateSpec {
+  id: string;
+  label: string;
+  agentId: string;
+  agentName: string;
+  command: string;
+  isMain: boolean;
+  /** 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;
+}
diff --git a/electron/main.ts b/electron/main.ts
index cbeeba525..30bdc8b97 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -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 { stopAllDocumentRuns, stopAllDocumentWatchers } from './ipc/documents.js';
 import { stopAllStepsWatchers } from './ipc/steps.js';
 import { verificationRunner } from './ipc/verify.js';
 import { IPC } from './ipc/channels.js';
@@ -288,6 +289,8 @@ app.on('will-quit', () => {
   verificationRunner.cancelAll();
   stopAgentHookRuntime();
   stopAllPlanWatchers();
+  stopAllDocumentWatchers();
+  stopAllDocumentRuns();
   stopAllStepsWatchers();
 });
 
diff --git a/electron/preload.cjs b/electron/preload.cjs
index f301b25e6..e4527b048 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -152,6 +152,22 @@ const ALLOWED_CHANNELS = new Set([
   'mcp_stale_url_warning',
   'mcp_coordinated_task_closed',
   'mcp_task_cleanup_failed',
+  'read_document',
+  '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',
+  'list_document_files',
+  'document_changed',
+  'document_run_event',
 ]);
 
 function isAllowedChannel(channel) {
diff --git a/electron/shared/document-agents.ts b/electron/shared/document-agents.ts
new file mode 100644
index 000000000..d64cd47c0
--- /dev/null
+++ b/electron/shared/document-agents.ts
@@ -0,0 +1,29 @@
+/**
+ * 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;
+}
+
+export const DOCUMENT_AGENT_SUPPORT: Record<string, DocumentAgentSupport> = {
+  'claude-code': { headless: true, resume: true },
+  codex: { headless: true, resume: true },
+  gemini: { headless: true, resume: false },
+  opencode: { headless: true, resume: false },
+  copilot: { headless: true, resume: false },
+};
+
+export function documentAgentSupport(agentId: string): DocumentAgentSupport {
+  return DOCUMENT_AGENT_SUPPORT[agentId] ?? { headless: false, resume: false };
+}
+
+/** 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/src/App.tsx b/src/App.tsx
index 033f91efb..998f4bf60 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -87,6 +87,8 @@ import { isMac, mod } from './lib/platform';
 import { createCtrlWheelZoomHandler } from './lib/wheelZoom';
 import { redrawAllTerminals } from './lib/terminalFitManager';
 import { ArenaOverlay } from './arena/ArenaOverlay';
+import { DocumentWorkspaceOverlay } from './documents/DocumentWorkspaceOverlay';
+import { closeDocumentWorkspace, initDocumentListeners } from './store/documents';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
@@ -336,6 +338,7 @@ function App() {
     // Before the first await: restored agents start firing hooks as soon as
     // loadState spawns them, and IPC does not replay what nobody listened to.
     const stopAgentHookStatusListener = startAgentHookStatusListener();
+    const stopDocumentListeners = initDocumentListeners();
     void syncWindowFocused();
     void syncWindowMaximized();
 
@@ -697,6 +700,10 @@ function App() {
           closeArena();
           return;
         }
+        if (store.activeDocumentProjectId) {
+          closeDocumentWorkspace();
+          return;
+        }
         if (store.showHelpDialog) {
           toggleHelpDialog(false);
           return;
@@ -742,6 +749,7 @@ function App() {
       stopRemoteTaskHandlers();
       stopRemoteStatusSync();
       stopAgentHookStatusListener();
+      stopDocumentListeners();
       offPlanContent();
       offStepsContent();
       unlistenFocusChanged?.();
@@ -919,6 +927,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/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index c17d14e96..6f38a6716 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 Git repository plus one Markdown document. 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."
+            />
+          </SettingsSection>
           <SettingsSection title="Coordinator">
             <SettingsCheckboxRow
               label="Coordinator mode"
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index b0fcaf095..ebfaa4164 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -40,6 +40,10 @@ 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 '../store/documents';
+import { isDocumentProject } from '../store/projects';
+import { choice } from '../lib/dialog';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
 import { SidebarFooter } from './SidebarFooter';
 import { IconButton } from './IconButton';
@@ -595,7 +599,21 @@ export function Sidebar() {
     });
   });
 
+  const [showNewDocumentProject, setShowNewDocumentProject] = createSignal(false);
+
   async function handleAddProject() {
+    if (store.documentWorkspacesEnabled) {
+      const picked = await choice('What kind of project?', {
+        buttons: ['Code project', 'Document project', 'Cancel'],
+        defaultId: 0,
+        cancelId: 2,
+      });
+      if (picked === 2) return;
+      if (picked === 1) {
+        setShowNewDocumentProject(true);
+        return;
+      }
+    }
     const projectId = await pickAndAddProject();
     if (!projectId) return;
 
@@ -862,14 +880,23 @@ export function Sidebar() {
                       tabIndex={0}
                       class="project-row"
                       data-project-id={project.id}
-                      onClick={() => setEditingProject(project)}
+                      onClick={() => {
+                        if (isDocumentProject(project) && !isProjectMissing(project.id))
+                          void openDocumentWorkspace(project.id);
+                        else setEditingProject(project);
+                      }}
                       onKeyDown={(e) => {
-                        if (e.key === 'Enter') setEditingProject(project);
+                        if (e.key !== 'Enter') return;
+                        if (isDocumentProject(project) && !isProjectMissing(project.id))
+                          void openDocumentWorkspace(project.id);
+                        else setEditingProject(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',
@@ -1148,6 +1175,10 @@ export function Sidebar() {
         <ConnectPhoneModal open={showConnectPhone()} onClose={() => setShowConnectPhone(false)} />
 
         <EditProjectDialog project={editingProject()} onClose={() => setEditingProject(null)} />
+        <NewDocumentProjectDialog
+          open={showNewDocumentProject()}
+          onClose={() => setShowNewDocumentProject(false)}
+        />
         <ImportWorktreesDialog
           open={importProject() !== null}
           project={importProject()}
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
new file mode 100644
index 000000000..6c327d202
--- /dev/null
+++ b/src/documents/CompareView.tsx
@@ -0,0 +1,305 @@
+import { For, Show, createMemo, createResource, createSignal, untrack } from 'solid-js';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { diffBlocks, type DocumentBlock } from '../lib/markdown-blocks';
+import {
+  acceptDocumentCandidate,
+  documentStore,
+  rejectDocumentRun,
+  setDocumentCandidateNote,
+} from '../store/documents';
+import { getProject } from '../store/projects';
+import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
+import { DocumentViewer, type BlockRange } from './DocumentViewer';
+import { SourceDiff } from './SourceDiff';
+import { createRenderedBlocks } from './use-blocks';
+
+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 };
+}
+
+function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: number }) {
+  const [cursor, setCursor] = createSignal(-1);
+  function go(delta: number) {
+    const body = props.body();
+    if (!body) return;
+    const targets = body.querySelectorAll<HTMLElement>('.doc-block:not([data-change="same"])');
+    if (targets.length === 0) return;
+    const next = (cursor() + delta + targets.length) % targets.length;
+    setCursor(next);
+    targets[next].scrollIntoView({ block: 'center', behavior: 'smooth' });
+  }
+  return (
+    <span class="docws-nav">
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(-1)}
+        title="Previous change"
+      >
+        ‹
+      </button>
+      <span>
+        {props.count} changed block{props.count === 1 ? '' : 's'}
+      </span>
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(1)}
+        title="Next change"
+      >
+        ›
+      </button>
+    </span>
+  );
+}
+
+function Rationale(props: { candidate: DocumentCandidateRecord }) {
+  const r = () => props.candidate.rationale;
+  const list = (label: string, items: string[] | undefined, cls?: string) => (
+    <Show when={items && items.length > 0}>
+      <div class="docws-rationale-label">{label}</div>
+      <ul class={cls}>
+        <For each={items}>{(item) => <li>{item}</li>}</For>
+      </ul>
+    </Show>
+  );
+  return (
+    <div class="docws-rationale">
+      <div class="docws-rationale-summary">{r()?.summary ?? 'No rationale returned.'}</div>
+      {list('Changes', r()?.changes)}
+      {list('Assumptions', r()?.assumptions)}
+      {list('Open questions', r()?.questions)}
+      {list('Warnings', r()?.warnings, 'docws-warning')}
+      <Show when={props.candidate.outOfScopeFiles?.length}>
+        <div class="docws-warning">
+          Touched files outside the document (reverted):{' '}
+          {props.candidate.outOfScopeFiles?.join(', ')}
+        </div>
+      </Show>
+      <Show when={props.candidate.outOfScopeHunks}>
+        <div class="docws-warning">
+          {props.candidate.outOfScopeHunks} change{props.candidate.outOfScopeHunks === 1 ? '' : 's'}{' '}
+          outside the selected passage.
+        </div>
+      </Show>
+      <Show when={props.candidate.error}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+    </div>
+  );
+}
+
+function CandidateColumn(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+  baseBlocks: DocumentBlock[];
+  revealAgents: boolean;
+  showSource: boolean;
+}) {
+  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 changes = createMemo(() => diffBlocks(props.baseBlocks, rendered.blocks()).candidate);
+  const changedCount = () => changes().filter((c) => c !== 'same').length;
+  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),
+  );
+  const [note, setNote] = createSignal(untrack(() => props.candidate.note ?? ''));
+  const [accepting, setAccepting] = createSignal(false);
+  const canAccept = () =>
+    !!props.candidate.commitSha &&
+    (props.run.status === 'finished' || props.run.status === 'stale') &&
+    !accepting();
+  const title = () =>
+    props.revealAgents
+      ? `${props.candidate.agentName}${props.candidate.isMain ? ' · main session' : ''}`
+      : `Candidate ${props.candidate.label}`;
+
+  async function accept() {
+    setAccepting(true);
+    try {
+      await acceptDocumentCandidate(props.run.id, props.candidate.id);
+    } finally {
+      setAccepting(false);
+    }
+  }
+
+  return (
+    <section class="docws-column" aria-label={title()}>
+      <div class="docws-column-head">
+        <div class="docws-column-title">
+          <span class="docws-candidate-label">{props.candidate.label}</span>
+          <span>{title()}</span>
+          <span style={{ 'margin-left': 'auto' }}>
+            <ChangeNav body={() => bodyRef} count={changedCount()} />
+          </span>
+        </div>
+        <Rationale candidate={props.candidate} />
+        <textarea
+          class="docws-note"
+          placeholder="Your note on this candidate…"
+          value={note()}
+          onInput={(e) => setNote(e.currentTarget.value)}
+          onBlur={() => {
+            if (note() !== (props.candidate.note ?? ''))
+              void setDocumentCandidateNote(props.run.id, props.candidate.id, note());
+          }}
+        />
+        <div class="docws-run-actions">
+          <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; accepting rebases the proposal'
+                : 'Accept this candidate as one commit on the canonical branch'
+            }
+            onClick={() => void accept()}
+          >
+            {accepting() ? 'Accepting…' : 'Accept this candidate'}
+          </button>
+        </div>
+      </div>
+      <div class="docws-column-body" ref={bodyRef}>
+        <Show
+          when={props.candidate.commitSha}
+          fallback={<div class="docws-empty">No change proposed.</div>}
+        >
+          <Show when={!props.showSource} fallback={<SourceDiff raw={diff() ?? ''} />}>
+            <Show
+              when={!rendered.rendering() || rendered.blocks().length > 0}
+              fallback={<div class="docws-empty">Rendering…</div>}
+            >
+              <DocumentViewer
+                blocks={rendered.blocks()}
+                changes={changes()}
+                renderKey={`cand-${props.candidate.id}`}
+              />
+            </Show>
+          </Show>
+        </Show>
+      </div>
+    </section>
+  );
+}
+
+/** Base on the left, candidates to the right, each opening with its rationale. */
+export function CompareView(props: { run: DocumentRunRecord }) {
+  const [revealAgents, setRevealAgents] = createSignal(false);
+  const [showSource, setShowSource] = createSignal(false);
+  const [baseContent] = createResource(
+    () => ({ sha: props.run.baseSha, path: props.run.documentPath }),
+    ({ sha, path }) => fetchDocumentAt(sha, path),
+  );
+  const base = createRenderedBlocks(() => baseContent() ?? null);
+  const scope = createMemo(() => scopeRange(base.blocks(), props.run));
+  const candidates = createMemo(() => props.run.candidates.filter((c) => c.commitSha));
+  const scopeText = () => {
+    const s = props.run.scope;
+    if (s.wholeDocument) return 'whole document';
+    return `L${s.startLine}–${s.endLine}${s.heading ? ` · ${s.heading}` : ''}`;
+  };
+
+  return (
+    <div class="docws-compare">
+      <div class="docws-compare-bar">
+        <span class="docws-instruction" title={props.run.instruction}>
+          “{props.run.instruction}”
+        </span>
+        <span>{scopeText()}</span>
+        <span>base {props.run.baseSha.slice(0, 7)}</span>
+        <Show when={props.run.status === 'stale'}>
+          <span class="docws-warning">stale: the document moved since this run</span>
+        </Show>
+        <span style={{ 'margin-left': 'auto' }} />
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={revealAgents()}
+            onChange={(e) => setRevealAgents(e.currentTarget.checked)}
+          />
+          Show agents
+        </label>
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={showSource()}
+            onChange={(e) => setShowSource(e.currentTarget.checked)}
+          />
+          Source diff
+        </label>
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm docws-btn-danger"
+          onClick={() => void rejectDocumentRun(props.run.id)}
+        >
+          Reject all
+        </button>
+      </div>
+      <div class="docws-columns">
+        <section class="docws-column docws-column-base" aria-label="Base version">
+          <div class="docws-column-head">
+            <div class="docws-column-title">Base · {props.run.baseSha.slice(0, 7)}</div>
+            <div class="docws-rationale">
+              <div>The document as every candidate saw it. The scoped passage is marked.</div>
+            </div>
+          </div>
+          <div class="docws-column-body">
+            <DocumentViewer blocks={base.blocks()} scope={scope()} renderKey="base" />
+          </div>
+        </section>
+        <For each={candidates()}>
+          {(candidate) => (
+            <CandidateColumn
+              run={props.run}
+              candidate={candidate}
+              baseBlocks={base.blocks()}
+              revealAgents={revealAgents()}
+              showSource={showSource()}
+            />
+          )}
+        </For>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
new file mode 100644
index 000000000..70e125449
--- /dev/null
+++ b/src/documents/DocumentViewer.tsx
@@ -0,0 +1,164 @@
+import { For, Show, createEffect, createMemo, on, type JSX } from 'solid-js';
+import type { BlockChange, DocumentBlock } from '../lib/markdown-blocks';
+import { blockRangeText, nearestHeading, sectionRange } from '../lib/markdown-blocks';
+import type { DocumentSelection } from '../store/documents';
+import { renderMermaidIn } from './use-blocks';
+
+export interface BlockRange {
+  start: number;
+  end: number;
+}
+
+interface DocumentViewerProps {
+  blocks: DocumentBlock[];
+  /** Renders selection affordances and reports selections. */
+  selectable?: boolean;
+  selection?: BlockRange | null;
+  onSelect?: (selection: DocumentSelection | null) => void;
+  /** Per-block change marks for the compare view. */
+  changes?: BlockChange[];
+  /** Blocks inside the run's scope (compare view context). */
+  scope?: BlockRange | null;
+  /** Unique key for mermaid ids. */
+  renderKey: string;
+  onContainer?: (el: HTMLDivElement) => void;
+  children?: JSX.Element;
+}
+
+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,
+  };
+}
+
+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) };
+  });
+
+  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('a, button, input, textarea, .docws-composer')) 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;
+      native.removeAllRanges();
+      emitRange({ start: start ?? end ?? 0, end: end ?? start ?? 0 });
+      return;
+    }
+    const index = blockIndexOf(target, containerRef);
+    if (index === null) return;
+    const current = selected();
+    if (current && current.start === index && current.end === index) emitRange(null);
+    else emitRange({ start: index, end: index });
+  }
+
+  function selectSection(index: number, e: MouseEvent) {
+    e.stopPropagation();
+    const [start, end] = sectionRange(props.blocks, index);
+    emitRange({ start, end });
+  }
+
+  return (
+    <div
+      ref={(el) => {
+        containerRef = el;
+        props.onContainer?.(el);
+      }}
+      class="plan-markdown plan-markdown-dialog docws-content"
+      classList={{ 'docws-selectable': props.selectable === true }}
+      onMouseUp={handleMouseUp}
+    >
+      <For each={props.blocks}>
+        {(block, i) => {
+          const change = () => props.changes?.[i()] ?? 'same';
+          const isSelected = () => {
+            const s = selected();
+            return !!s && i() >= s.start && i() <= s.end;
+          };
+          const inScope = () => {
+            const s = props.scope;
+            return !!s && i() >= s.start && i() <= s.end;
+          };
+          return (
+            <div
+              class="doc-block"
+              data-block-index={i()}
+              data-change={change()}
+              classList={{
+                'is-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>
+              {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
+              <div innerHTML={block.html} />
+            </div>
+          );
+        }}
+      </For>
+      {props.children}
+    </div>
+  );
+}
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
new file mode 100644
index 000000000..2bb845e85
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -0,0 +1,268 @@
+import './documents.css';
+import { For, Show, createEffect, createMemo, createSignal, on, onCleanup } from 'solid-js';
+import { store } from '../store/core';
+import { getProject } from '../store/projects';
+import {
+  closeDocumentWorkspace,
+  documentStore,
+  reviewableRuns,
+  setDocumentSelection,
+  setDocumentView,
+  openDocumentCompare,
+  type DocumentView,
+} from '../store/documents';
+import { EditProjectDialog } from '../components/EditProjectDialog';
+import type { Project } from '../store/types';
+import { CompareView } from './CompareView';
+import { DocumentViewer } from './DocumentViewer';
+import { HistoryView } from './HistoryView';
+import { RunComposer } from './RunComposer';
+import { RunsRail } from './RunsRail';
+import { createRenderedBlocks } from './use-blocks';
+
+function DocumentIcon() {
+  return (
+    <svg
+      width="18"
+      height="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>
+  );
+}
+
+function DocumentPane() {
+  let docRef: HTMLDivElement | undefined;
+  const blocks = createRenderedBlocks(() => documentStore.snapshot?.content ?? null);
+  const [anchorTop, setAnchorTop] = createSignal(0);
+  const selection = () => documentStore.selection;
+  const range = createMemo(() => {
+    const s = selection();
+    return s && !s.wholeDocument ? { start: s.startBlock, end: s.endBlock } : null;
+  });
+
+  // Park the composer right under the last selected block.
+  createEffect(
+    on([selection, blocks.blocks], () => {
+      const s = selection();
+      if (!s || !docRef) return;
+      requestAnimationFrame(() => {
+        if (!docRef) return;
+        const index = s.wholeDocument ? 0 : s.endBlock;
+        const el = docRef.querySelector<HTMLElement>(`.doc-block[data-block-index="${index}"]`);
+        const top = s.wholeDocument ? 0 : el ? el.offsetTop + el.offsetHeight + 8 : 0;
+        setAnchorTop(top);
+        if (!s.wholeDocument && el) {
+          const composer = docRef.querySelector<HTMLElement>('.docws-composer');
+          composer?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+        }
+      });
+    }),
+  );
+
+  const toolbarLabel = () => {
+    const s = selection();
+    if (!s) return 'Select text, click a block, or use § on a heading to scope a task';
+    return s.wholeDocument
+      ? 'Whole document selected'
+      : `Selected lines ${s.startLine}–${s.endLine}`;
+  };
+
+  function selectWholeDocument() {
+    const all = blocks.blocks();
+    if (all.length === 0) return;
+    setDocumentSelection({
+      startBlock: 0,
+      endBlock: all.length - 1,
+      startLine: all[0].startLine,
+      endLine: all[all.length - 1].endLine,
+      quote: '',
+      heading: undefined,
+      wholeDocument: true,
+    });
+  }
+
+  return (
+    <>
+      <div class="docws-main">
+        <div class="docws-toolbar">
+          <span>{toolbarLabel()}</span>
+          <span style={{ 'margin-left': 'auto' }} />
+          <button type="button" class="docws-btn docws-btn-sm" onClick={selectWholeDocument}>
+            Whole document
+          </button>
+          <Show when={selection()}>
+            <button
+              type="button"
+              class="docws-btn docws-btn-sm"
+              onClick={() => setDocumentSelection(null)}
+            >
+              Clear
+            </button>
+          </Show>
+        </div>
+        <Show when={documentStore.snapshot?.missing}>
+          <div class="docws-older-banner">The document file is missing from the checkout.</div>
+        </Show>
+        <div class="docws-doc" ref={docRef}>
+          <DocumentViewer
+            blocks={blocks.blocks()}
+            selectable
+            selection={range()}
+            onSelect={setDocumentSelection}
+            renderKey="main"
+          >
+            <Show when={selection()} keyed>
+              {(s) => (
+                <RunComposer
+                  selection={s}
+                  anchorTop={anchorTop()}
+                  onClose={() => setDocumentSelection(null)}
+                />
+              )}
+            </Show>
+          </DocumentViewer>
+          <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>
+      <RunsRail />
+    </>
+  );
+}
+
+/** Full-window surface for a document project: document, compare, history. */
+export function DocumentWorkspaceOverlay() {
+  const project = createMemo<Project | undefined>(() =>
+    store.activeDocumentProjectId ? getProject(store.activeDocumentProjectId) : undefined,
+  );
+  const [editing, setEditing] = createSignal<Project | null>(null);
+  const snapshot = () => documentStore.snapshot;
+  const compareRun = () =>
+    documentStore.compareRunId ? documentStore.runs[documentStore.compareRunId] : undefined;
+  const reviewable = createMemo(() => reviewableRuns());
+
+  // Close when the project disappears (removed while open).
+  createEffect(() => {
+    if (store.activeDocumentProjectId && !project()) closeDocumentWorkspace();
+  });
+
+  onCleanup(() => {
+    if (documentStore.projectId) closeDocumentWorkspace();
+  });
+
+  function tab(view: DocumentView, label: string, count?: number) {
+    return (
+      <button
+        type="button"
+        class="docws-tab"
+        role="tab"
+        aria-selected={documentStore.view === view}
+        onClick={() => {
+          if (view === 'compare' && !compareRun() && reviewable()[0])
+            openDocumentCompare(reviewable()[0].id);
+          else setDocumentView(view);
+        }}
+      >
+        {label}
+        <Show when={count}>
+          <span class="docws-count">{count}</span>
+        </Show>
+      </button>
+    );
+  }
+
+  return (
+    <div class="docws-overlay" role="dialog" aria-label="Document workspace">
+      <div class="docws-header">
+        <div class="docws-title">
+          <DocumentIcon />
+          <span>{project()?.name}</span>
+        </div>
+        <span class="docws-subtitle" title={project()?.documentPath}>
+          {project()?.documentPath}
+        </span>
+        <div class="docws-tabs" role="tablist">
+          {tab('document', 'Document')}
+          {tab('compare', 'Compare', reviewable().length)}
+          {tab('history', 'History')}
+        </div>
+        <button type="button" class="docws-btn" onClick={() => setEditing(project() ?? null)}>
+          Project
+        </button>
+        <button type="button" class="docws-btn" onClick={() => closeDocumentWorkspace()}>
+          Close
+        </button>
+      </div>
+      <div class="docws-status-line">
+        <span>{snapshot()?.branch ?? 'detached'}</span>
+        <span>@ {snapshot()?.headSha?.slice(0, 7) ?? 'no commits'}</span>
+        <Show when={snapshot()?.dirty}>
+          <span class="docws-dirty">uncommitted edits (committed on the next run)</span>
+        </Show>
+        <Show when={documentStore.error}>
+          <span class="docws-error">{documentStore.error}</span>
+        </Show>
+        <Show when={documentStore.loading}>
+          <span>loading…</span>
+        </Show>
+      </div>
+      <div class="docws-body">
+        <Show when={documentStore.view === 'document'}>
+          <DocumentPane />
+        </Show>
+        <Show when={documentStore.view === 'compare'}>
+          <div class="docws-main" style={{ overflow: 'hidden' }}>
+            <Show when={reviewable().length > 1 && compareRun()}>
+              <div class="docws-compare-bar">
+                <span>Run</span>
+                <select
+                  class="docws-select"
+                  value={compareRun()?.id}
+                  onChange={(e) => openDocumentCompare(e.currentTarget.value)}
+                >
+                  <For each={reviewable()}>
+                    {(r) => <option value={r.id}>{r.instruction.slice(0, 80)}</option>}
+                  </For>
+                </select>
+              </div>
+            </Show>
+            <Show
+              when={compareRun()}
+              keyed
+              fallback={
+                <div class="docws-empty" style={{ padding: '24px' }}>
+                  Nothing to compare yet. Finished runs with proposals appear here.
+                </div>
+              }
+            >
+              {(run) => <CompareView run={run} />}
+            </Show>
+          </div>
+        </Show>
+        <Show when={documentStore.view === 'history'}>
+          <div class="docws-main" style={{ overflow: 'hidden' }}>
+            <HistoryView />
+          </div>
+        </Show>
+      </div>
+      <EditProjectDialog project={editing()} onClose={() => setEditing(null)} />
+    </div>
+  );
+}
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
new file mode 100644
index 000000000..abe91742f
--- /dev/null
+++ b/src/documents/HistoryView.tsx
@@ -0,0 +1,212 @@
+import { For, Show, createResource, createSignal } from 'solid-js';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { confirm } from '../lib/dialog';
+import { formatRelativeAge } from '../lib/relativeAge';
+import { documentStore, revertDocumentCommit } from '../store/documents';
+import { getProject } from '../store/projects';
+import type { DocumentHistoryEntry } from '../ipc/types';
+import { DocumentViewer } from './DocumentViewer';
+import { SourceDiff } from './SourceDiff';
+import { createRenderedBlocks } from './use-blocks';
+
+function project() {
+  return documentStore.projectId ? getProject(documentStore.projectId) : undefined;
+}
+
+function EntryDetail(props: {
+  entry: DocumentHistoryEntry;
+  documentPath: string;
+  onReverted: () => void;
+}) {
+  const [mode, setMode] = createSignal<'diff' | 'version'>('diff');
+  const root = () => project()?.path ?? '';
+  const [diff] = createResource(
+    () => ({
+      projectRoot: root(),
+      from: `${props.entry.sha}^`,
+      to: props.entry.sha,
+      documentPath: props.documentPath,
+    }),
+    (args) => invoke<string>(IPC.GetDocumentDiff, args),
+  );
+  const [content] = createResource(
+    () =>
+      mode() === 'version'
+        ? { projectRoot: root(), sha: props.entry.sha, documentPath: props.documentPath }
+        : null,
+    (args) => invoke<string | null>(IPC.GetDocumentAtCommit, args),
+  );
+  const rendered = createRenderedBlocks(() => content() ?? null);
+  const trailerEntries = () => Object.entries(props.entry.trailers);
+
+  async function revert() {
+    const ok = await confirm(
+      `Revert "${props.entry.subject}"? This adds a new commit that undoes it.`,
+      {
+        okLabel: 'Revert',
+        kind: 'warning',
+      },
+    );
+    if (!ok) return;
+    if (await revertDocumentCommit(props.entry.sha)) props.onReverted();
+  }
+
+  return (
+    <div class="docws-history-detail">
+      <div class="docws-history-detail-head">
+        <div class="docws-column-title">
+          <span>{props.entry.subject}</span>
+          <span style={{ 'margin-left': 'auto' }} class="docws-tabs">
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'diff'}
+              onClick={() => setMode('diff')}
+            >
+              Diff
+            </button>
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'version'}
+              onClick={() => setMode('version')}
+            >
+              Version
+            </button>
+          </span>
+        </div>
+        <div class="docws-history-meta">
+          <span>{props.entry.shortSha}</span>
+          <span>{props.entry.author}</span>
+          <span>{new Date(props.entry.timestamp * 1000).toLocaleString()}</span>
+          <span class="docws-badge">
+            {props.entry.manual ? 'manual' : props.entry.trailers.Agent}
+          </span>
+        </div>
+        <Show when={props.entry.body}>
+          <div class="docws-history-body">{props.entry.body}</div>
+        </Show>
+        <Show when={trailerEntries().length > 0}>
+          <dl class="docws-trailers">
+            <For each={trailerEntries()}>
+              {([key, value]) => (
+                <>
+                  <dt>{key}</dt>
+                  <dd>{value}</dd>
+                </>
+              )}
+            </For>
+          </dl>
+        </Show>
+        <div class="docws-run-actions">
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-danger"
+            onClick={() => void revert()}
+          >
+            Revert this commit
+          </button>
+        </div>
+      </div>
+      <Show when={mode() === 'version'}>
+        <div class="docws-older-banner">
+          Older version at {props.entry.shortSha}. The current document is on the Document tab.
+        </div>
+      </Show>
+      <div class="docws-column-body">
+        <Show
+          when={mode() === 'diff'}
+          fallback={
+            <DocumentViewer blocks={rendered.blocks()} renderKey={`hist-${props.entry.shortSha}`} />
+          }
+        >
+          <SourceDiff raw={diff() ?? ''} />
+        </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 = () => project()?.documentPath ?? '';
+  const [entries, { refetch }] = createResource(
+    () => ({
+      root: project()?.path,
+      documentPath: documentPath(),
+      whole: wholeProject(),
+      head: documentStore.snapshot?.headSha,
+      version: version(),
+    }),
+    async ({ root, documentPath: docPath, whole }) => {
+      if (!root || !docPath) return [] as DocumentHistoryEntry[];
+      return invoke<DocumentHistoryEntry[]>(IPC.GetDocumentHistory, {
+        projectRoot: root,
+        documentPath: docPath,
+        wholeProject: whole,
+      });
+    },
+  );
+  const selected = () => entries()?.find((e) => e.sha === selectedSha()) ?? entries()?.[0] ?? null;
+  const nowMs = () => Date.now();
+
+  return (
+    <div class="docws-history">
+      <div class="docws-history-list" role="listbox" aria-label="History">
+        <div class="docws-compare-bar">
+          <label class="docws-toggle">
+            <input
+              type="checkbox"
+              checked={wholeProject()}
+              onChange={(e) => setWholeProject(e.currentTarget.checked)}
+            />
+            Whole project
+          </label>
+          <span style={{ 'margin-left': 'auto' }}>{entries()?.length ?? 0} commits</span>
+        </div>
+        <Show when={entries()?.length === 0}>
+          <div class="docws-empty" style={{ padding: '12px 14px' }}>
+            No commits touch this document yet.
+          </div>
+        </Show>
+        <For each={entries() ?? []}>
+          {(entry) => (
+            <button
+              type="button"
+              role="option"
+              class="docws-history-entry"
+              aria-selected={selected()?.sha === entry.sha}
+              onClick={() => setSelectedSha(entry.sha)}
+            >
+              <span class="docws-history-subject">{entry.subject}</span>
+              <span class="docws-history-meta">
+                <span>{entry.shortSha}</span>
+                <span>{formatRelativeAge(entry.timestamp * 1000, nowMs())}</span>
+                <span class="docws-badge">{entry.manual ? 'manual' : entry.trailers.Agent}</span>
+                <Show when={entry.trailers.Candidate}>
+                  <span>candidate {entry.trailers.Candidate}</span>
+                </Show>
+              </span>
+            </button>
+          )}
+        </For>
+      </div>
+      <Show when={selected()} keyed>
+        {(entry) => (
+          <EntryDetail
+            entry={entry}
+            documentPath={documentPath()}
+            onReverted={() => {
+              setVersion((v) => v + 1);
+              void refetch();
+            }}
+          />
+        )}
+      </Show>
+    </div>
+  );
+}
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
new file mode 100644
index 000000000..88e8e8576
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -0,0 +1,181 @@
+import { For, Show, createMemo, createSignal } 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 { openDocumentWorkspace } from '../store/documents';
+
+interface NewDocumentProjectDialogProps {
+  open: boolean;
+  onClose: () => void;
+}
+
+/** Picks a Git repository and one Markdown document inside it. */
+export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
+  const [folder, setFolder] = createSignal('');
+  const [name, setName] = createSignal('');
+  const [files, setFiles] = createSignal<string[]>([]);
+  const [filter, setFilter] = createSignal('');
+  const [documentPath, setDocumentPath] = createSignal('');
+  const [error, setError] = createSignal('');
+  const [busy, setBusy] = createSignal(false);
+
+  const visibleFiles = createMemo(() => {
+    const q = filter().trim().toLowerCase();
+    return q ? files().filter((f) => f.toLowerCase().includes(q)) : files();
+  });
+
+  function reset() {
+    setFolder('');
+    setName('');
+    setFiles([]);
+    setFilter('');
+    setDocumentPath('');
+    setError('');
+  }
+
+  function close() {
+    reset();
+    props.onClose();
+  }
+
+  async function chooseFolder() {
+    const selected = await openDialog({ directory: true, multiple: false });
+    if (!selected) return;
+    const path = selected as string;
+    setBusy(true);
+    setError('');
+    try {
+      const isGit = await invoke<boolean>(IPC.CheckIsGitRepo, { path });
+      if (!isGit) {
+        setError('Document projects need a Git repository. Run `git init` in the folder first.');
+        return;
+      }
+      const list = await invoke<string[]>(IPC.ListDocumentFiles, { projectRoot: path });
+      setFolder(path);
+      setName(path.split('/').pop() || path);
+      setFiles(list);
+      setDocumentPath(list.length === 1 ? list[0] : '');
+      if (list.length === 0) setError('No tracked Markdown files found. Commit a .md file first.');
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const canCreate = () => folder() && documentPath() && name().trim() && !busy();
+
+  async function create() {
+    if (!canCreate()) return;
+    const id = addDocumentProject(name().trim(), folder(), documentPath());
+    close();
+    await openDocumentWorkspace(id);
+  }
+
+  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 }}>
+          A Git repository with a Markdown document. Agents propose changes in isolated worktrees;
+          you decide what enters the document.
+        </p>
+        <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+          <span style={sectionLabelStyle}>Repository</span>
+          <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
+            <button
+              type="button"
+              class="docws-btn"
+              onClick={() => void chooseFolder()}
+              disabled={busy()}
+            >
+              {folder() ? 'Change folder…' : 'Choose folder…'}
+            </button>
+            <span
+              style={{
+                'font-family': 'var(--font-mono)',
+                'font-size': '12px',
+                color: theme.fgMuted,
+                overflow: 'hidden',
+                'text-overflow': 'ellipsis',
+                'white-space': 'nowrap',
+              }}
+            >
+              {folder()}
+            </span>
+          </div>
+        </div>
+        <Show when={folder()}>
+          <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+            <span style={sectionLabelStyle}>Name</span>
+            <input
+              style={inputStyle}
+              value={name()}
+              onInput={(e) => setName(e.currentTarget.value)}
+            />
+          </div>
+          <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="Markdown files">
+              <For each={visibleFiles()}>
+                {(file) => (
+                  <button
+                    type="button"
+                    role="option"
+                    class="docws-picker-item"
+                    aria-selected={documentPath() === file}
+                    onClick={() => setDocumentPath(file)}
+                  >
+                    {file}
+                  </button>
+                )}
+              </For>
+            </div>
+          </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()}
+          >
+            Open workspace
+          </button>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
new file mode 100644
index 000000000..9a49c6da6
--- /dev/null
+++ b/src/documents/RunComposer.tsx
@@ -0,0 +1,211 @@
+import { For, Show, createMemo, createSignal, onMount } from 'solid-js';
+import { store } from '../store/core';
+import {
+  dispatchDocumentRun,
+  documentMainAgentId,
+  documentStore,
+  setDocumentMainAgent,
+  type DispatchSelection,
+  type DocumentSelection,
+} from '../store/documents';
+import { getProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import { errMessage } from '../lib/log';
+import {
+  MAX_DOCUMENT_CANDIDATES,
+  documentAgentSupport,
+} from '../../electron/shared/document-agents';
+import type { AgentDef } from '../ipc/types';
+
+interface RunComposerProps {
+  selection: DocumentSelection;
+  /** Offset inside the document container where the composer sits. */
+  anchorTop: number;
+  onClose: () => void;
+}
+
+const MAX_PER_AGENT = 3;
+
+/**
+ * The overlay that turns a selection into a run: instruction, agents and
+ * candidate counts. 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 [instruction, setInstruction] = createSignal('');
+  const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
+  const mainAgentId = () => documentMainAgentId(project());
+  const [counts, setCounts] = createSignal<Record<string, number>>({ [mainAgentId()]: 1 });
+
+  const agents = createMemo(() => store.availableAgents);
+  const resumable = createMemo(() =>
+    agents().filter((a) => a.available !== false && documentAgentSupport(a.id).resume),
+  );
+
+  const picks = createMemo<DispatchSelection[]>(() =>
+    agents()
+      .filter((a) => (counts()[a.id] ?? 0) > 0)
+      .map((agent) => ({ agent, count: counts()[agent.id] })),
+  );
+  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;
+
+  onMount(() => {
+    requestAnimationFrame(() => textareaRef?.focus());
+  });
+
+  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 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());
+      props.onClose();
+    } catch (err) {
+      showNotification(errMessage(err));
+    }
+  }
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      props.onClose();
+      return;
+    }
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      void run();
+    }
+  }
+
+  const scopeLabel = () => {
+    const s = props.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
+      class="docws-composer"
+      role="dialog"
+      aria-label="Run a task on the selected passage"
+      style={{ top: `${props.anchorTop}px` }}
+      onKeyDown={handleKeyDown}
+      onMouseUp={(e) => e.stopPropagation()}
+    >
+      <div class="docws-composer-footer">
+        <span>{scopeLabel()}</span>
+        <span class="docws-spacer" />
+        <label>
+          Main session{' '}
+          <select
+            class="docws-select"
+            value={mainAgentId()}
+            onChange={(e) => {
+              const next = e.currentTarget.value;
+              const prevMain = mainAgentId();
+              setDocumentMainAgent(next);
+              setCounts((prev) =>
+                prev[prevMain] && !prev[next]
+                  ? { ...without(prev, prevMain), [next]: prev[prevMain] }
+                  : prev,
+              );
+            }}
+          >
+            <For each={resumable()}>{(a) => <option value={a.id}>{a.name}</option>}</For>
+          </select>
+        </label>
+      </div>
+      <Show when={!props.selection.wholeDocument}>
+        <div class="docws-composer-quote">{props.selection.quote.slice(0, 400)}</div>
+      </Show>
+      <textarea
+        ref={textareaRef}
+        placeholder="What should change here? e.g. find a simpler architecture, challenge these assumptions…"
+        value={instruction()}
+        onInput={(e) => setInstruction(e.currentTarget.value)}
+      />
+      <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 (
+              <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>
+                <Show when={count() > 0}>
+                  <span
+                    class="docws-count-btn"
+                    role="button"
+                    title="Candidates from this agent (click to change)"
+                    onClick={(e) => bump(agent, e)}
+                  >
+                    ×{count()}
+                  </span>
+                </Show>
+              </button>
+            );
+          }}
+        </For>
+      </div>
+      <div class="docws-composer-footer">
+        <span>
+          {total()} candidate{total() === 1 ? '' : 's'}
+          {total() > 1 ? ' · opens the compare view' : ''}
+          {total() > MAX_DOCUMENT_CANDIDATES ? ` · max ${MAX_DOCUMENT_CANDIDATES}` : ''}
+        </span>
+        <span class="docws-spacer" />
+        <span>Enter to run · Esc to close</span>
+        <button type="button" class="docws-btn docws-btn-sm" onClick={() => props.onClose()}>
+          Cancel
+        </button>
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm docws-btn-primary"
+          disabled={!canRun()}
+          onClick={() => void run()}
+        >
+          {documentStore.dispatching ? 'Starting…' : 'Run'}
+        </button>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
new file mode 100644
index 000000000..a05f80b11
--- /dev/null
+++ b/src/documents/RunsRail.tsx
@@ -0,0 +1,127 @@
+import { For, Show, createMemo } from 'solid-js';
+import {
+  cancelDocumentRun,
+  documentStore,
+  openDocumentCompare,
+  rejectDocumentRun,
+} from '../store/documents';
+import { formatRelativeAge } from '../lib/relativeAge';
+import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
+
+function scopeLabel(run: DocumentRunRecord): string {
+  const s = run.scope;
+  if (s.wholeDocument) return 'whole document';
+  const lines = s.startLine === s.endLine ? `L${s.startLine}` : `L${s.startLine}–${s.endLine}`;
+  return s.heading ? `${lines} · ${s.heading}` : lines;
+}
+
+function candidateState(c: DocumentCandidateRecord): string {
+  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: { candidate: DocumentCandidateRecord; showLog: boolean }) {
+  const lines = () => documentStore.logs[props.candidate.id] ?? [];
+  const tail = () => lines().slice(-6);
+  return (
+    <div class="docws-candidate">
+      <div class="docws-candidate-head">
+        <span class={`docws-dot docws-dot-${props.candidate.status}`} />
+        <span class="docws-candidate-label">{props.candidate.label}</span>
+        <span>{props.candidate.agentName}</span>
+        <Show when={props.candidate.isMain}>
+          <span class="docws-badge">main</span>
+        </Show>
+        <span style={{ 'margin-left': 'auto', color: 'var(--fg-subtle)' }}>
+          {candidateState(props.candidate)}
+        </span>
+      </div>
+      <Show when={props.candidate.error && props.candidate.status !== 'running'}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+      <Show when={props.showLog && tail().length > 0}>
+        <div class="docws-log">{tail().join('\n')}</div>
+      </Show>
+    </div>
+  );
+}
+
+/** Right-hand list of runs against the open document, newest first. */
+export function RunsRail() {
+  const runs = createMemo(() =>
+    documentStore.runOrder.map((id) => documentStore.runs[id]).filter(Boolean),
+  );
+  const nowMs = () => Date.now();
+
+  return (
+    <aside class="docws-rail" aria-label="Runs">
+      <div class="docws-rail-title">Runs</div>
+      <Show when={runs().length === 0}>
+        <div class="docws-empty">
+          Select a passage in the document, describe what should change, and pick one or more
+          agents. Proposals show up here.
+        </div>
+      </Show>
+      <For each={runs()}>
+        {(run) => {
+          const proposals = () => run.candidates.filter((c) => c.commitSha).length;
+          const canCompare = () =>
+            (run.status === 'finished' || run.status === 'stale') && proposals() > 0;
+          return (
+            <div class="docws-run" data-run-id={run.id}>
+              <div class="docws-run-head">
+                <span class={`docws-badge docws-badge-${run.status}`}>{run.status}</span>
+                <span class="docws-run-meta" title={new Date(run.createdAt).toLocaleString()}>
+                  {formatRelativeAge(new Date(run.createdAt).getTime(), nowMs())}
+                </span>
+              </div>
+              <div class="docws-run-instruction" title={run.instruction}>
+                {run.instruction}
+              </div>
+              <div class="docws-run-meta" title={scopeLabel(run)}>
+                {scopeLabel(run)} · base {run.baseSha.slice(0, 7)}
+              </div>
+              <For each={run.candidates}>
+                {(candidate) => (
+                  <CandidateRow candidate={candidate} showLog={run.status === 'running'} />
+                )}
+              </For>
+              <div class="docws-run-actions">
+                <Show when={run.status === 'running'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm"
+                    onClick={() => void cancelDocumentRun(run.id)}
+                  >
+                    Cancel
+                  </button>
+                </Show>
+                <Show when={canCompare()}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-primary"
+                    onClick={() => openDocumentCompare(run.id)}
+                  >
+                    {proposals() > 1 ? `Compare ${proposals()}` : 'Review'}
+                  </button>
+                </Show>
+                <Show when={run.status === 'finished' || run.status === 'stale'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-danger"
+                    onClick={() => void rejectDocumentRun(run.id)}
+                  >
+                    {proposals() > 0 ? 'Reject all' : 'Dismiss'}
+                  </button>
+                </Show>
+              </div>
+            </div>
+          );
+        }}
+      </For>
+    </aside>
+  );
+}
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/documents.css b/src/documents/documents.css
new file mode 100644
index 000000000..cf59535ac
--- /dev/null
+++ b/src/documents/documents.css
@@ -0,0 +1,895 @@
+/* Document workspace overlay — uses the app's design tokens. */
+
+.docws-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1900;
+  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);
+  flex-shrink: 0;
+  min-width: 0;
+}
+
+.docws-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 15px;
+  min-width: 0;
+}
+
+.docws-title svg {
+  color: var(--accent);
+  flex-shrink: 0;
+}
+
+.docws-subtitle {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--fg-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+}
+
+.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;
+}
+
+.docws-tab[aria-selected='true'] {
+  background: var(--bg-selected);
+  color: var(--fg);
+}
+
+.docws-tab .docws-count {
+  margin-left: 6px;
+  font-size: 11px;
+  padding: 1px 6px;
+  border-radius: 999px;
+  background: var(--accent);
+  color: var(--accent-text);
+}
+
+.docws-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 6px 12px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 13px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.docws-btn:hover:not(:disabled) {
+  background: var(--bg-hover);
+}
+
+.docws-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.docws-btn-primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--accent-text);
+  font-weight: 600;
+}
+
+.docws-btn-primary:hover:not(:disabled) {
+  background: var(--accent-hover);
+}
+
+.docws-btn-danger {
+  color: var(--error);
+}
+
+.docws-btn-sm {
+  padding: 3px 8px;
+  font-size: 12px;
+}
+
+.docws-body {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+}
+
+.docws-main {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  position: relative;
+}
+
+.docws-rail {
+  width: 320px;
+  flex-shrink: 0;
+  border-left: 1px solid var(--border);
+  overflow-y: auto;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  background: var(--bg-elevated);
+}
+
+.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;
+}
+
+.docws-status-line {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 18px;
+  font-size: 12px;
+  color: var(--fg-muted);
+  border-bottom: 1px solid var(--border-subtle);
+  font-family: var(--font-mono);
+}
+
+.docws-status-line .docws-dirty {
+  color: var(--warning);
+}
+
+/* ── Rendered document ── */
+
+.docws-doc {
+  position: relative;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 28px 44px 200px;
+}
+
+.docws-content .doc-block {
+  position: relative;
+  border-radius: var(--radius-sm);
+  margin: 0 -10px;
+  padding: 2px 10px;
+  transition: background 0.1s ease;
+}
+
+.docws-content.docws-selectable .doc-block:hover {
+  background: color-mix(in srgb, var(--accent) 6%, transparent);
+}
+
+.docws-content .doc-block.is-selected {
+  background: color-mix(in srgb, var(--accent) 16%, transparent);
+  box-shadow: inset 3px 0 0 var(--accent);
+}
+
+.docws-content .doc-block.is-changed {
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  box-shadow: inset 3px 0 0 var(--warning);
+}
+
+.docws-content .doc-block.is-added {
+  background: var(--diff-add-bg);
+  box-shadow: inset 3px 0 0 var(--success);
+}
+
+.docws-content .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 .doc-block.is-scope {
+  box-shadow: inset 3px 0 0 var(--border-focus);
+}
+
+.docws-content .doc-block > :first-child {
+  margin-top: 0.2em;
+}
+
+.docws-content .doc-block > :last-child {
+  margin-bottom: 0.2em;
+}
+
+.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);
+}
+
+.docws-content table {
+  border-collapse: collapse;
+  margin: 0.6em 0;
+  font-size: 0.92em;
+}
+
+.docws-content th,
+.docws-content td {
+  border: 1px solid var(--border);
+  padding: 4px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+
+.docws-content th {
+  background: color-mix(in srgb, var(--fg) 5%, transparent);
+}
+
+.docws-content blockquote {
+  margin: 0.6em 0;
+  padding: 0.2em 0 0.2em 1em;
+  border-left: 3px solid var(--border);
+  color: var(--fg-muted);
+}
+
+.docws-content 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;
+  background: color-mix(in srgb, var(--bg) 88%, transparent);
+  backdrop-filter: blur(8px);
+  border-bottom: 1px solid var(--border-subtle);
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+/* ── Composer ── */
+
+.docws-composer {
+  position: absolute;
+  left: 0;
+  right: 0;
+  z-index: 5;
+  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;
+}
+
+.docws-composer-quote {
+  font-size: 12px;
+  color: var(--fg-muted);
+  border-left: 3px solid var(--accent);
+  padding-left: 8px;
+  max-height: 64px;
+  overflow: hidden;
+  white-space: pre-wrap;
+  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-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-chip[aria-pressed='true'] {
+  border-color: var(--accent);
+  color: var(--fg);
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+
+.docws-agent-chip:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.docws-agent-chip .docws-main-badge {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--accent);
+  font-weight: 600;
+}
+
+.docws-count-btn {
+  min-width: 22px;
+  height: 20px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  background: var(--bg-elevated);
+  color: var(--fg);
+  font-size: 11px;
+  font-family: var(--font-mono);
+  cursor: pointer;
+  padding: 0 5px;
+}
+
+.docws-composer-footer {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 12px;
+  color: var(--fg-subtle);
+}
+
+.docws-composer-footer .docws-spacer {
+  flex: 1;
+}
+
+.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-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.docws-candidate-label {
+  font-family: var(--font-mono);
+  font-weight: 600;
+}
+
+.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;
+}
+
+.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;
+}
+
+.docws-rationale {
+  font-size: 12px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.docws-rationale-summary {
+  font-size: 13px;
+  color: var(--fg);
+}
+
+.docws-rationale ul {
+  margin: 0;
+  padding-left: 18px;
+  color: var(--fg-muted);
+}
+
+.docws-rationale .docws-rationale-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--fg-subtle);
+  margin-top: 4px;
+}
+
+.docws-warning {
+  color: var(--warning);
+}
+
+.docws-error {
+  color: var(--error);
+}
+
+.docws-note {
+  width: 100%;
+  box-sizing: border-box;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 5px 8px;
+  resize: vertical;
+  min-height: 30px;
+}
+
+.docws-column-body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 14px 18px 120px;
+}
+
+.docws-column-body .docws-content {
+  font-size: 15px;
+  line-height: 1.6;
+}
+
+.docws-nav {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+/* ── Source diff ── */
+
+.docws-diff {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docws-diff-line {
+  padding: 0 6px;
+}
+
+.docws-diff-add {
+  background: var(--diff-add-bg);
+}
+
+.docws-diff-remove {
+  background: var(--diff-remove-bg);
+}
+
+.docws-diff-hunk {
+  color: var(--info);
+  margin-top: 8px;
+}
+
+/* ── History ── */
+
+.docws-history {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+}
+
+.docws-history-list {
+  width: 360px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-entry {
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 10px 14px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.docws-history-entry:hover {
+  background: var(--bg-hover);
+}
+
+.docws-history-entry[aria-selected='true'] {
+  background: var(--bg-selected-subtle);
+  box-shadow: inset 3px 0 0 var(--accent);
+}
+
+.docws-history-subject {
+  font-size: 13px;
+  line-height: 1.35;
+}
+
+.docws-history-meta {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 11px;
+  color: var(--fg-subtle);
+  font-family: var(--font-mono);
+}
+
+.docws-history-detail {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-detail-head {
+  padding: 12px 18px;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.docws-history-body {
+  white-space: pre-wrap;
+  font-size: 13px;
+  color: var(--fg-muted);
+  line-height: 1.5;
+}
+
+.docws-trailers {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 2px 12px;
+  font-size: 12px;
+  font-family: var(--font-mono);
+}
+
+.docws-trailers dt {
+  color: var(--fg-subtle);
+}
+
+.docws-trailers dd {
+  margin: 0;
+  color: var(--fg);
+  word-break: break-all;
+}
+
+.docws-older-banner {
+  padding: 6px 18px;
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  color: var(--warning);
+  font-size: 12px;
+  border-bottom: 1px solid color-mix(in srgb, var(--warning) 40%, transparent);
+}
+
+.docws-picker-list {
+  max-height: 260px;
+  overflow-y: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--bg-input);
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-picker-item {
+  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: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;
+  }
+}
diff --git a/src/documents/use-blocks.ts b/src/documents/use-blocks.ts
new file mode 100644
index 000000000..09a0fb78e
--- /dev/null
+++ b/src/documents/use-blocks.ts
@@ -0,0 +1,61 @@
+import { createEffect, createSignal, onCleanup } from 'solid-js';
+import { renderDocumentBlocks, type DocumentBlock } from '../lib/markdown-blocks';
+
+/**
+ * Reactively renders a markdown source into blocks. Stale renders are dropped
+ * when the source changes again before they finish.
+ */
+export function createRenderedBlocks(source: () => string | null | undefined): {
+  blocks: () => DocumentBlock[];
+  rendering: () => boolean;
+} {
+  const [blocks, setBlocks] = createSignal<DocumentBlock[]>([]);
+  const [rendering, setRendering] = createSignal(false);
+  let generation = 0;
+
+  createEffect(() => {
+    const content = source();
+    const gen = ++generation;
+    if (content === null || content === undefined) {
+      setBlocks([]);
+      setRendering(false);
+      return;
+    }
+    setRendering(true);
+    renderDocumentBlocks(content)
+      .then((result) => {
+        if (gen === generation) setBlocks(result);
+      })
+      .catch((err) => console.warn('[documents] render failed:', err))
+      .finally(() => {
+        if (gen === generation) setRendering(false);
+      });
+  });
+
+  onCleanup(() => {
+    generation++;
+  });
+
+  return { blocks, rendering };
+}
+
+/** Renders mermaid placeholders inside a container after its HTML is set. */
+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) => {
+      const source = el.getAttribute('data-mermaid');
+      if (!source) return;
+      mermaid
+        .render(`mermaid-doc-${key}-${Date.now()}-${i}`, source)
+        .then(({ svg }) => {
+          el.innerHTML = svg; // nosemgrep: semgrep.no-inner-html-without-sanitize -- mermaid renders its own sanitized SVG from document text
+          el.classList.add('mermaid-rendered');
+        })
+        .catch(() => undefined);
+    });
+  });
+}
diff --git a/src/ipc/types.ts b/src/ipc/types.ts
index 4b46282de..6e281df90 100644
--- a/src/ipc/types.ts
+++ b/src/ipc/types.ts
@@ -7,6 +7,16 @@ export type {
   CoverageMetricSummary,
   CoverageSummary,
   CreateTaskResult,
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentCandidateStatus,
+  DocumentHistoryEntry,
+  DocumentRationale,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentRunStatus,
+  DocumentScope,
+  DocumentSnapshot,
   EslintQualityFinding,
   EslintQualityResult,
   FileDiffResult,
diff --git a/src/lib/markdown-blocks.test.ts b/src/lib/markdown-blocks.test.ts
new file mode 100644
index 000000000..bc69f6823
--- /dev/null
+++ b/src/lib/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/lib/markdown-blocks.ts b/src/lib/markdown-blocks.ts
new file mode 100644
index 000000000..8c977ef1c
--- /dev/null
+++ b/src/lib/markdown-blocks.ts
@@ -0,0 +1,220 @@
+import DOMPurify from 'dompurify';
+import { Marked, type Token, type Tokens } from 'marked';
+import { highlightLines } from './shiki-highlighter';
+
+/**
+ * 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;
+  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;
+  for (const token of tokens as Token[]) {
+    const raw = token.raw ?? '';
+    const startLine = countNewlines(source.slice(0, offset)) + 1;
+    offset += raw.length;
+    if (token.type === 'space' || !raw.trim()) continue;
+    const endLine = startLine + countNewlines(raw.trimEnd());
+    const html = DOMPurify.sanitize(marked.parser([token]), { ADD_ATTR: ['data-lang'] });
+    const block: DocumentBlock = {
+      index: blocks.length,
+      type: token.type,
+      startLine,
+      endLine,
+      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/store/autosave.ts b/src/store/autosave.ts
index 9cb53fe6f..33ce9f186 100644
--- a/src/store/autosave.ts
+++ b/src/store/autosave.ts
@@ -41,6 +41,7 @@ export function persistedSnapshot(): string {
     focusMode: store.focusMode,
     coordinatorNotificationDelayMs: store.coordinatorNotificationDelayMs,
     coordinatorModeEnabled: store.coordinatorModeEnabled,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed,
     autoStartRemoteAccess: store.autoStartRemoteAccess,
     shareDockerAgentAuth: store.shareDockerAgentAuth,
diff --git a/src/store/core.ts b/src/store/core.ts
index 75301e4a7..c9b97edc0 100644
--- a/src/store/core.ts
+++ b/src/store/core.ts
@@ -90,6 +90,8 @@ export const [store, setStore] = createStore<AppStore>({
   taskSplitMode: {},
   verboseLogging: false,
   coordinatorModeEnabled: false,
+  documentWorkspacesEnabled: false,
+  activeDocumentProjectId: null,
   coordinatorNotificationDelayMs: 60_000,
   coordinatorControlHintDismissed: false,
   defaultStepsEnabled: false,
diff --git a/src/store/documents.ts b/src/store/documents.ts
new file mode 100644
index 000000000..8b1931285
--- /dev/null
+++ b/src/store/documents.ts
@@ -0,0 +1,441 @@
+/**
+ * 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,
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from '../ipc/types';
+import {
+  DEFAULT_DOCUMENT_MAIN_AGENT,
+  MAX_DOCUMENT_CANDIDATES,
+  documentAgentSupport,
+} from '../../electron/shared/document-agents';
+import { store, setStore } from './core';
+import { getProject, updateProject } from './projects';
+import { showNotification } from './notification';
+import type { Project } from './types';
+
+export type DocumentView = 'document' | 'compare' | '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;
+}
+
+interface DocumentWorkspaceState {
+  projectId: string | null;
+  snapshot: DocumentSnapshot | null;
+  loading: boolean;
+  error: string | null;
+  runs: Record<string, DocumentRunRecord>;
+  runOrder: string[];
+  /** Streamed log lines per candidate id, bounded. */
+  logs: Record<string, string[]>;
+  view: DocumentView;
+  compareRunId: string | null;
+  selection: DocumentSelection | null;
+  dispatching: boolean;
+}
+
+const MAX_LOG_LINES = 400;
+
+const [docStore, setDocStore] = createStore<DocumentWorkspaceState>({
+  projectId: null,
+  snapshot: null,
+  loading: false,
+  error: null,
+  runs: {},
+  runOrder: [],
+  logs: {},
+  view: 'document',
+  compareRunId: null,
+  selection: null,
+  dispatching: false,
+});
+
+export { docStore as documentStore };
+
+function activeProject(): Project | undefined {
+  return docStore.projectId ? getProject(docStore.projectId) : undefined;
+}
+
+function requireProject(): Project & { documentPath: string } {
+  const project = activeProject();
+  if (!project || !project.documentPath) throw new Error('No document project is open.');
+  return project as Project & { documentPath: string };
+}
+
+function watcherKey(projectId: string): string {
+  return `doc:${projectId}`;
+}
+
+export async function refreshDocumentSnapshot(): Promise<void> {
+  const project = activeProject();
+  if (!project?.documentPath) return;
+  try {
+    const snapshot = await invoke<DocumentSnapshot>(IPC.ReadDocument, {
+      projectRoot: project.path,
+      documentPath: project.documentPath,
+    });
+    setDocStore({ snapshot, error: null });
+  } catch (err) {
+    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;
+    setDocStore(
+      produce((s) => {
+        s.runs = byId;
+        s.runOrder = sortRunIds(byId);
+      }),
+    );
+  } catch (err) {
+    setDocStore('error', errMessage(err));
+  }
+}
+
+export async function openDocumentWorkspace(projectId: string): Promise<void> {
+  const project = getProject(projectId);
+  if (!project?.documentPath) return;
+  const previous = docStore.projectId;
+  if (previous && previous !== projectId) {
+    void invoke(IPC.StopDocumentWatcher, { key: watcherKey(previous) }).catch(() => undefined);
+  }
+  setDocStore({
+    projectId,
+    snapshot: null,
+    loading: true,
+    error: null,
+    runs: {},
+    runOrder: [],
+    logs: {},
+    view: 'document',
+    compareRunId: null,
+    selection: null,
+  });
+  setStore('activeDocumentProjectId', projectId);
+  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns()]);
+  setDocStore('loading', false);
+  void invoke(IPC.StartDocumentWatcher, {
+    key: watcherKey(projectId),
+    projectRoot: project.path,
+    documentPath: project.documentPath,
+  }).catch((err) => setDocStore('error', errMessage(err)));
+}
+
+export function closeDocumentWorkspace(): void {
+  const projectId = docStore.projectId;
+  if (projectId) {
+    void invoke(IPC.StopDocumentWatcher, { key: watcherKey(projectId) }).catch(() => undefined);
+  }
+  setDocStore({ projectId: null, selection: null, view: 'document', compareRunId: null });
+  setStore('activeDocumentProjectId', null);
+}
+
+export function setDocumentView(view: DocumentView): void {
+  setDocStore('view', view);
+}
+
+export function setDocumentSelection(selection: DocumentSelection | null): void {
+  setDocStore('selection', selection);
+}
+
+export function openDocumentCompare(runId: string): void {
+  setDocStore({ compareRunId: runId, view: 'compare' });
+}
+
+export function reviewableRuns(): DocumentRunRecord[] {
+  return docStore.runOrder
+    .map((id) => docStore.runs[id])
+    .filter((r) => r.status === 'finished' || r.status === 'stale');
+}
+
+/** 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;
+}
+
+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;
+      specs.push({
+        id: `c${index + 1}`,
+        label: candidateLabel(index),
+        agentId: pick.agent.id,
+        agentName: pick.agent.name,
+        command: pick.agent.command,
+        isMain,
+        sessionId: session?.sessionId,
+        sessionLastSha: session?.lastSha,
+        envFile: envFiles[pick.agent.id],
+      });
+      index++;
+    }
+  }
+  return specs;
+}
+
+export async function dispatchDocumentRun(
+  instruction: string,
+  picks: readonly DispatchSelection[],
+): Promise<DocumentRunRecord | null> {
+  const project = requireProject();
+  const selection = docStore.selection;
+  if (!selection) throw new Error('Select a passage first.');
+  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: project.documentPath,
+      instruction,
+      scope: buildScope(selection, project.documentPath),
+      candidates,
+    });
+    upsertRun(run);
+    setDocStore('selection', null);
+    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. */
+function recordMainSession(run: DocumentRunRecord, candidate: DocumentCandidateRecord): void {
+  if (!candidate.isMain || !candidate.sessionId) return;
+  const project = activeProject();
+  if (!project) return;
+  updateProject(project.id, {
+    documentSessions: {
+      ...(project.documentSessions ?? {}),
+      [candidate.agentId]: { sessionId: candidate.sessionId, lastSha: run.baseSha },
+    },
+  });
+}
+
+export function applyDocumentRunEvent(event: DocumentRunEvent): void {
+  switch (event.type) {
+    case 'log':
+      setDocStore(
+        produce((s) => {
+          const lines = s.logs[event.candidateId] ?? [];
+          lines.push(event.text);
+          if (lines.length > MAX_LOG_LINES) lines.splice(0, lines.length - MAX_LOG_LINES);
+          s.logs[event.candidateId] = lines;
+        }),
+      );
+      return;
+    case 'candidate': {
+      const run = docStore.runs[event.runId];
+      if (!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);
+        }),
+      );
+      recordMainSession(run, event.candidate);
+      return;
+    }
+    case 'run':
+      upsertRun(event.run);
+      if (event.run.status === 'finished') {
+        for (const c of event.run.candidates) recordMainSession(event.run, c);
+        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;
+  }
+}
+
+export async function acceptDocumentCandidate(runId: string, candidateId: string): Promise<void> {
+  const project = requireProject();
+  try {
+    await invoke<{ sha: string }>(IPC.AcceptDocumentCandidate, {
+      projectRoot: project.path,
+      runId,
+      candidateId,
+    });
+    showNotification('Proposal accepted');
+    setDocStore({ view: 'document', compareRunId: null });
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+  await Promise.all([loadDocumentRuns(), refreshDocumentSnapshot()]);
+}
+
+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({ view: 'document', compareRunId: null });
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+  void refreshDocumentSnapshot();
+}
+
+export async function cancelDocumentRun(runId: string): Promise<void> {
+  await invoke(IPC.CancelDocumentRun, { runId }).catch((err) => showNotification(errMessage(err)));
+}
+
+export async function setDocumentCandidateNote(
+  runId: string,
+  candidateId: string,
+  note: string,
+): Promise<void> {
+  const project = requireProject();
+  try {
+    const run = await invoke<DocumentRunRecord>(IPC.SetDocumentCandidateNote, {
+      projectRoot: project.path,
+      runId,
+      candidateId,
+      note,
+    });
+    upsertRun(run);
+  } catch (err) {
+    showNotification(errMessage(err));
+  }
+}
+
+export async function revertDocumentCommit(sha: string): Promise<boolean> {
+  const project = requireProject();
+  try {
+    await invoke(IPC.RevertDocumentCommit, { projectRoot: project.path, sha });
+    showNotification('Reverted');
+    void refreshDocumentSnapshot();
+    return true;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return false;
+  }
+}
+
+interface DocumentChangedPayload {
+  key: string;
+  snapshot: DocumentSnapshot;
+}
+
+function isRunEvent(v: unknown): v is DocumentRunEvent {
+  return !!v && typeof v === 'object' && typeof (v as { type?: unknown }).type === '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 offChanged = window.electron.ipcRenderer.on(IPC.DocumentChanged, (payload: unknown) => {
+    const p = payload as DocumentChangedPayload | undefined;
+    if (!p) return;
+    untrack(() => {
+      if (!docStore.projectId || p.key !== watcherKey(docStore.projectId)) return;
+      const previous = docStore.snapshot;
+      setDocStore('snapshot', p.snapshot);
+      // The passage under a selection may be gone after an external edit.
+      if (previous && previous.content !== p.snapshot.content) setDocStore('selection', null);
+    });
+  });
+  return () => {
+    offRun();
+    offChanged();
+  };
+}
diff --git a/src/store/persistence.ts b/src/store/persistence.ts
index 16b127333..14ff1de52 100644
--- a/src/store/persistence.ts
+++ b/src/store/persistence.ts
@@ -244,6 +244,7 @@ export async function saveState(): Promise<void> {
     darkThemePreset: store.darkThemePreset !== 'islands-dark' ? store.darkThemePreset : undefined,
     darkThemeCustomId: store.darkThemeCustomId ?? undefined,
     coordinatorModeEnabled: store.coordinatorModeEnabled || undefined,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled || undefined,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed || undefined,
     defaultStepsEnabled: store.defaultStepsEnabled || undefined,
     defaultSkipPermissions: store.defaultSkipPermissions || undefined,
@@ -415,6 +416,7 @@ interface LegacyPersistedState {
   darkThemePreset?: unknown;
   darkThemeCustomId?: unknown;
   coordinatorModeEnabled?: unknown;
+  documentWorkspacesEnabled?: unknown;
   coordinatorControlHintDismissed?: unknown;
   defaultStepsEnabled?: unknown;
   defaultSkipPermissions?: unknown;
@@ -613,6 +615,7 @@ export async function loadState(): Promise<void> {
       }
 
       s.coordinatorModeEnabled = raw.coordinatorModeEnabled === true;
+      s.documentWorkspacesEnabled = raw.documentWorkspacesEnabled === true;
 
       s.coordinatorControlHintDismissed = raw.coordinatorControlHintDismissed === true;
 
diff --git a/src/store/projects.ts b/src/store/projects.ts
index 5ced78edc..ca8d3f2bc 100644
--- a/src/store/projects.ts
+++ b/src/store/projects.ts
@@ -30,6 +30,31 @@ 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,
+  };
+  setStore(
+    produce((s) => {
+      s.projects.push(project);
+      s.lastProjectId = id;
+    }),
+  );
+  return id;
+}
+
+export function isDocumentProject(project: Project | undefined): boolean {
+  return project?.kind === 'document' && typeof project.documentPath === 'string';
+}
+
 export function removeProject(projectId: string): void {
   // Guard: skip removal if any tasks still reference this project
   const allTaskIds = [...store.taskOrder, ...store.collapsedTaskOrder];
@@ -67,6 +92,8 @@ export function updateProject(
       | 'verifyCommand'
       | 'terminalBookmarks'
       | 'isGitRepo'
+      | 'documentMainAgentId'
+      | 'documentSessions'
     >
   >,
 ): void {
@@ -92,6 +119,10 @@ 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 (
diff --git a/src/store/store.ts b/src/store/store.ts
index b41c4cf4f..8add82b01 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -8,6 +8,8 @@ export {
   getProjectPath,
   getProjectBranchPrefix,
   pickAndAddProject,
+  addDocumentProject,
+  isDocumentProject,
   validateProjectPaths,
   relinkProject,
   isProjectMissing,
@@ -116,6 +118,7 @@ export {
   setTaskViewportVisibility,
   toggleSidebar,
   toggleArena,
+  setDocumentWorkspacesEnabled,
   toggleFocusMode,
   toggleTaskFocusMode,
   setTaskSplitMode,
diff --git a/src/store/types.ts b/src/store/types.ts
index 5fee4decb..bc5f1af79 100644
--- a/src/store/types.ts
+++ b/src/store/types.ts
@@ -87,6 +87,22 @@ 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>;
+}
+
+export type ProjectKind = 'code' | 'document';
+
+export interface DocumentSessionRef {
+  sessionId: string;
+  lastSha: string;
 }
 
 export interface Agent {
@@ -308,6 +324,7 @@ export interface PersistedState {
   darkThemePreset?: LookPreset;
   darkThemeCustomId?: string | null;
   coordinatorModeEnabled?: boolean;
+  documentWorkspacesEnabled?: boolean;
   coordinatorNotificationDelayMs?: number;
   coordinatorControlHintDismissed?: boolean;
   defaultStepsEnabled?: boolean;
@@ -435,6 +452,9 @@ export interface AppStore {
   darkThemePreset: LookPreset;
   darkThemeCustomId: string | null;
   coordinatorModeEnabled: boolean;
+  documentWorkspacesEnabled: boolean;
+  /** Project whose document workspace overlay is open. */
+  activeDocumentProjectId: string | null;
   coordinatorNotificationDelayMs: number;
   coordinatorControlHintDismissed: boolean;
   defaultStepsEnabled: boolean;
diff --git a/src/store/ui.ts b/src/store/ui.ts
index 23869d966..67eaa92a8 100644
--- a/src/store/ui.ts
+++ b/src/store/ui.ts
@@ -270,6 +270,11 @@ export function setShareDockerAgentAuth(enabled: boolean): void {
   setStore('shareDockerAgentAuth', enabled);
 }
 
+export function setDocumentWorkspacesEnabled(enabled: boolean): void {
+  setStore('documentWorkspacesEnabled', enabled);
+  if (!enabled) setStore('activeDocumentProjectId', null);
+}
+
 export function toggleArena(show?: boolean): void {
   setStore('showArena', show ?? !store.showArena);
 }

From 98ba6821c3d406f083782ea5d6105143ec83722e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 3 Sep 2026 23:37:20 +0000
Subject: [PATCH 02/12] fix(documents): harden run lifecycle and scope events
 after review

Backend:
- Refuse a new main-session run while the main worktree is still in use,
  and fail a candidate whose worktree left its branch before commit.
- Validate run records on load: worktree paths must sit under .worktrees,
  branches must be parallel-doc/*, hashes must be hex. A cloned record
  can no longer name an arbitrary directory for cleanup.
- Judge scope against HEAD: unstage before reverting strays, commit with
  --only, and verify the proposal commit touches the document alone.
- Validate sessionLastSha as a hash and forbid a leading dash in session
  ids so neither can reach git or the CLI as a flag.
- Write candidate results under the project lock by re-reading the record,
  so a note or rejection that landed meanwhile is not overwritten; reject
  waits for killed processes to settle before removing worktrees.
- Ignore app-seeded .claude files when listing out-of-scope files.
- Drop OpenCode and Copilot from headless support until their shell can
  be restricted.
- Commit only tracked changes as "Manual edits"; untracked files stay out.
- Spawn candidates detached and kill the process group, escalating to
  SIGKILL; decode stdout as a stream so multi-byte characters survive.
- Delete the main worktree's previous branch once its run is settled.
- Revert keeps run records and adds a Parallel-Revert trailer.
- Parse trailers only from the final paragraph and flatten rationale
  entries so agent text cannot re-attribute a commit.
- Reject .git/ as a document path and unsupported agents before any
  worktree is created.

Renderer:
- Run events carry the project root; runs and main sessions are recorded
  for the project they belong to even after its workspace was closed.
- The workspace overlay sits below dialogs so the project editor and
  settings render on top of it.
- Compare view is keyed by run id so notes and rejections no longer
  remount it; the composer keeps its draft when the selection changes.
- Text inside one block stays a native selection so copying works;
  multi-block drags, block clicks and section buttons scope a run.
- Candidate logs are keyed per run, relative ages tick, the base column
  marks blocks a candidate rewrote or removed, stale runs cannot be
  accepted, diffs show a loading state, Escape clears the composer
  before closing the workspace.
- Document projects stay out of the new-task project picker.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UP9JjPPAYEBBNe1VbGnSzU
---
 docs/document-workspaces.md                |  31 +-
 electron/ipc/document-agents.test.ts       |   2 +-
 electron/ipc/document-agents.ts            |   4 -
 electron/ipc/document-prompt.ts            |  11 +-
 electron/ipc/documents.integration.test.ts | 255 ++++++++++++-
 electron/ipc/documents.test.ts             |  68 ++++
 electron/ipc/documents.ts                  | 402 +++++++++++++++++----
 electron/ipc/shared-types.ts               |   6 +-
 electron/shared/document-agents.ts         |  10 +-
 src/App.tsx                                |  10 +-
 src/components/NewTaskDialog.tsx           |   6 +-
 src/components/ProjectSelect.tsx           |   6 +-
 src/documents/CompareView.tsx              |  59 ++-
 src/documents/DocumentViewer.tsx           |   8 +-
 src/documents/DocumentWorkspaceOverlay.tsx |   8 +-
 src/documents/HistoryView.tsx              |  10 +-
 src/documents/RunsRail.tsx                 |  21 +-
 src/documents/documents.css                |   4 +-
 src/store/documents.ts                     |  75 +++-
 src/store/projects.ts                      |   2 +-
 20 files changed, 849 insertions(+), 149 deletions(-)

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 71dc0279f..7dba86207 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -42,21 +42,27 @@ the document.
 - **Editing happens in your editor.** The app watches the file and re-renders; an external
   change drops any active selection.
 - **Dispatch commits pending edits first** as a plain `Manual edits` commit so every run
-  has a real base. Files under `.parallel/` are left out of that commit.
+  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`, `gemini -p --output-format json --approval-mode auto_edit`.
-  Process exit means the proposal is ready.
+workspace-write` (the sandbox blocks writes outside the worktree),
+  `gemini -p --output-format json --approval-mode auto_edit`. 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.
 - **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.
-- **Scope is enforced, not trusted.** Files the agent touched outside the document are
-  reverted before the proposal commit and listed on the candidate. Hunks inside the
-  document but outside the selected passage are counted and flagged.
+  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.
@@ -67,7 +73,12 @@ workspace-write`, `gemini -p --output-format json --approval-mode auto_edit`.
   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.
   Rejection commits the run record alone, so the history view (which excludes `.parallel/`)
-  never shows it.
+  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
@@ -77,8 +88,8 @@ workspace-write`, `gemini -p --output-format json --approval-mode auto_edit`.
 ### Not in this slice
 
 Annotations, HTML documents, partial acceptance, evaluator agents, refinement rounds,
-durable anchors across versions, in-app editing. Custom agents without a known headless
-mode cannot be picked. Agents other than Claude Code and Codex run one-shot only.
+durable anchors across versions, in-app editing. Custom agents, OpenCode and Copilot
+cannot be picked. Gemini runs one-shot only.
 
 ---
 
diff --git a/electron/ipc/document-agents.test.ts b/electron/ipc/document-agents.test.ts
index 54c69b58e..7eccd72dd 100644
--- a/electron/ipc/document-agents.test.ts
+++ b/electron/ipc/document-agents.test.ts
@@ -162,7 +162,7 @@ describe('gemini and plain parsers', () => {
   });
 
   it('keeps everything for plain-text agents', () => {
-    const parser = createHeadlessParser('opencode');
+    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/ipc/document-agents.ts b/electron/ipc/document-agents.ts
index 144f15117..e7a99feca 100644
--- a/electron/ipc/document-agents.ts
+++ b/electron/ipc/document-agents.ts
@@ -73,10 +73,6 @@ export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch
         command: opts.command,
         args: ['-p', opts.prompt, '--output-format', 'json', '--approval-mode', 'auto_edit'],
       };
-    case 'opencode':
-      return { command: opts.command, args: ['run', opts.prompt] };
-    case 'copilot':
-      return { command: opts.command, args: ['-p', opts.prompt, '--allow-all-tools'] };
     default:
       throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
   }
diff --git a/electron/ipc/document-prompt.ts b/electron/ipc/document-prompt.ts
index 42537c5d5..bd0d997db 100644
--- a/electron/ipc/document-prompt.ts
+++ b/electron/ipc/document-prompt.ts
@@ -72,15 +72,22 @@ export function buildDocumentPrompt(input: DocumentPromptInput): string {
   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);
+  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' ? obj.summary.trim() : '';
+  const summary = typeof obj.summary === 'string' ? oneLine(obj.summary) : '';
   const changes = stringList(obj.changes);
   if (!summary && changes.length === 0) return null;
   return {
diff --git a/electron/ipc/documents.integration.test.ts b/electron/ipc/documents.integration.test.ts
index f0994039b..2a8de4a12 100644
--- a/electron/ipc/documents.integration.test.ts
+++ b/electron/ipc/documents.integration.test.ts
@@ -6,7 +6,9 @@ import path from 'path';
 import type { BrowserWindow } from 'electron';
 import {
   acceptDocumentCandidate,
+  commitPendingEdits,
   dispatchDocumentRun,
+  revertDocumentCommit,
   getDocumentAtCommit,
   getDocumentDiff,
   getDocumentHistory,
@@ -87,7 +89,8 @@ beforeAll(() => {
     [
       '#!/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',
+      '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```"}\'',
@@ -114,8 +117,9 @@ describe('document workspace lifecycle', () => {
   });
 
   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.
+    // 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',
@@ -140,6 +144,9 @@ describe('document workspace lifecycle', () => {
     });
     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);
@@ -149,7 +156,7 @@ describe('document workspace lifecycle', () => {
     expect(c.sessionId).toBe('sess-1');
     expect(c.rationale?.summary).toBe('Sharpened the goals');
     expect(c.rationale?.questions).toEqual(['ok?']);
-    expect(c.outOfScopeFiles).toEqual(['STRAY.txt']);
+    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'));
@@ -198,6 +205,248 @@ describe('document workspace lifecycle', () => {
     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);
+  });
+
+  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');
+  });
+
+  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);
+  });
+
+  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 otherwise', async () => {
diff --git a/electron/ipc/documents.test.ts b/electron/ipc/documents.test.ts
index 401a8fd8d..3d489977e 100644
--- a/electron/ipc/documents.test.ts
+++ b/electron/ipc/documents.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   countOutOfScopeHunks,
   parseCommitBody,
+  sanitizeRunRecord,
   validateDocumentPath,
   validateSha,
 } from './documents.js';
@@ -16,6 +17,8 @@ describe('validateDocumentPath', () => {
     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();
   });
@@ -67,4 +70,69 @@ describe('parseCommitBody', () => {
   it('returns empty trailers for a manual commit', () => {
     expect(parseCommitBody('just a note').trailers).toEqual({});
   });
+  it('ignores trailer-shaped lines outside the final paragraph', () => {
+    const body =
+      'Prose.\nParallel-Agent: Human\n\n- more\n\nParallel-Run: r1\nParallel-Agent: Codex';
+    const { text, trailers } = parseCommitBody(body);
+    expect(trailers.Agent).toBe('Codex');
+    expect(text).toContain('Parallel-Agent: Human');
+  });
+  it('treats a mixed last paragraph as prose', () => {
+    expect(parseCommitBody('Parallel-Agent: X\nnot a trailer').trailers).toEqual({});
+  });
+});
+
+describe('sanitizeRunRecord', () => {
+  const root = '/repo';
+  const good = {
+    version: 1,
+    id: 'run-1',
+    documentPath: 'docs/a.md',
+    baseSha: 'abcdef1234567',
+    status: 'finished',
+    createdAt: 'x',
+    instruction: 'i',
+    scope: { path: 'docs/a.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    candidates: [
+      {
+        id: 'c1',
+        label: 'A',
+        agentId: 'claude-code',
+        agentName: 'Claude',
+        isMain: false,
+        branch: 'parallel-doc/abc-a',
+        worktreePath: '/repo/.worktrees/parallel-doc/abc-a',
+        status: 'done',
+        commitSha: 'abcdef1234567',
+        startedAt: 'x',
+      },
+    ],
+  };
+  it('accepts a record this app would have written', () => {
+    expect(sanitizeRunRecord(root, good)).not.toBeNull();
+  });
+  it('rejects a worktree path outside .worktrees', () => {
+    const bad = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/home/me/Documents' }],
+    };
+    expect(sanitizeRunRecord(root, bad)).toBeNull();
+    const sneaky = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/repo/.worktrees/../../etc' }],
+    };
+    expect(sanitizeRunRecord(root, sneaky)).toBeNull();
+  });
+  it('rejects foreign branch names and bad shas', () => {
+    expect(
+      sanitizeRunRecord(root, { ...good, candidates: [{ ...good.candidates[0], branch: 'main' }] }),
+    ).toBeNull();
+    expect(
+      sanitizeRunRecord(root, {
+        ...good,
+        candidates: [{ ...good.candidates[0], commitSha: '--output=x' }],
+      }),
+    ).toBeNull();
+    expect(sanitizeRunRecord(root, { ...good, baseSha: 'HEAD' })).toBeNull();
+  });
 });
diff --git a/electron/ipc/documents.ts b/electron/ipc/documents.ts
index 53b84f76e..599d850f7 100644
--- a/electron/ipc/documents.ts
+++ b/electron/ipc/documents.ts
@@ -19,7 +19,7 @@ import { loadEnvFile } from './env-file.js';
 import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from './git.js';
 import { buildHeadlessLaunch, createHeadlessParser } from './document-agents.js';
 import { buildDocumentPrompt, parseDocumentRationale } from './document-prompt.js';
-import { MAX_DOCUMENT_CANDIDATES } from '../shared/document-agents.js';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from '../shared/document-agents.js';
 import type {
   DocumentCandidateRecord,
   DocumentCandidateSpec,
@@ -43,6 +43,12 @@ 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/'];
 
 async function git(cwd: string, args: string[]): Promise<string> {
   logDebug('git', args.join(' '));
@@ -61,15 +67,15 @@ async function gitOk(cwd: string, args: string[]): Promise<boolean> {
 
 // --- Validation -----------------------------------------------------------
 
-/** A document path is repo-relative and stays inside the project. */
+/** 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 (normalized.startsWith('.parallel/') || normalized.startsWith('.worktrees/'))
-    throw new Error('documentPath must not point into .parallel or .worktrees');
+  if (/^\.(parallel|worktrees|git)(\/|$)/.test(normalized))
+    throw new Error('documentPath must not point into .parallel, .worktrees or .git');
   return normalized;
 }
 
@@ -91,6 +97,8 @@ export function validateSha(value: unknown, label = 'sha'): string {
   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>;
@@ -138,25 +146,41 @@ function validateCandidateSpecs(value: unknown): DocumentCandidateSpec[] {
     };
     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_.-]{1,128}$/.test(sessionId))
+    if (sessionId && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(sessionId))
       throw new Error('candidate.sessionId is invalid');
+    const sessionLastShaRaw = optStr('sessionLastSha');
+    const sessionLastSha =
+      sessionLastShaRaw === undefined
+        ? undefined
+        : validateSha(sessionLastShaRaw, 'candidate.sessionLastSha');
     return {
       id,
       label,
-      agentId: str('agentId'),
+      agentId,
       agentName: str('agentName').slice(0, 64),
       command,
       isMain: c.isMain === true,
       sessionId,
-      sessionLastSha: optStr('sessionLastSha'),
+      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> {
@@ -176,15 +200,19 @@ async function currentBranch(projectRoot: string): Promise<string | null> {
   }
 }
 
-/** Pathspec that leaves run records out of "pending edits": they are committed
- *  explicitly by acceptance and rejection so they never bury content commits. */
+/** 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=all',
+    '--untracked-files=no',
     ...CONTENT_PATHSPEC,
   ]);
   return out.trim().length > 0;
@@ -307,12 +335,42 @@ function writeRunRecord(projectRoot: string, run: DocumentRunRecord): void {
   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');
+  } 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');
-    const parsed = JSON.parse(raw) as DocumentRunRecord;
-    if (parsed.version !== 1 || !Array.isArray(parsed.candidates)) return null;
-    return parsed;
+    return sanitizeRunRecord(projectRoot, JSON.parse(raw));
   } catch {
     return null;
   }
@@ -329,7 +387,13 @@ function requireRunRecord(projectRoot: string, runId: string): DocumentRunRecord
 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 {
@@ -362,6 +426,41 @@ 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;
@@ -394,16 +493,21 @@ export function listDocumentRuns(projectRoot: string): DocumentRunRecord[] {
   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 -------------------------------------------------
 
 /**
- * Commits whatever the user changed in the checkout as a plain commit, so the
- * run has a real base. Returns HEAD afterwards. Throws in an empty repository.
+ * 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);
   if (await isDirty(projectRoot)) {
-    await git(projectRoot, ['add', '-A', ...CONTENT_PATHSPEC]);
+    await git(projectRoot, ['add', '-u', ...CONTENT_PATHSPEC]);
     await git(projectRoot, ['commit', '-q', '-m', 'Manual edits']);
   }
   const sha = await headSha(projectRoot);
@@ -435,9 +539,18 @@ async function prepareMainWorktree(
     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;
 }
 
@@ -454,9 +567,12 @@ 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 anyway).
+    // 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)
@@ -505,8 +621,8 @@ function parseChangedPaths(porcelainZ: string): string[] {
   const out: string[] = [];
   for (const entry of porcelainZ.split('\0')) {
     if (!entry.trim()) continue;
-    // "XY path" or "XY orig -> path" (renames use a second NUL entry; the
-    // first path after the status is what we act on).
+    // "XY path" (renames use a second NUL entry; the first path after the
+    // status is what we act on).
     const p = entry.slice(3);
     if (p) out.push(p);
   }
@@ -530,6 +646,18 @@ function commitTitle(summary: string, fallback: string): string {
   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,
@@ -551,22 +679,36 @@ async function finalizeCandidate(
   }
 
   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 docPath = run.documentPath;
-    const outOfScope = changed.filter((p) => p !== docPath);
-    if (outOfScope.length > 0) {
+    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);
-      candidate.outOfScopeFiles = outOfScope.slice(0, 50);
     }
+    if (outOfScope.length > 0) candidate.outOfScopeFiles = outOfScope.slice(0, 50);
 
-    const docChanged = !(await gitOk(worktreePath, ['diff', '--quiet', '--', docPath]));
+    const docChanged = !(await gitOk(worktreePath, ['diff', '--quiet', 'HEAD', '--', docPath]));
     const rationale = parseDocumentRationale(outcome.resultText);
     candidate.rationale = rationale;
 
@@ -578,14 +720,14 @@ async function finalizeCandidate(
       return;
     }
 
-    const diffU0 = await git(worktreePath, ['diff', '-U0', '--', docPath]);
+    const diffU0 = await git(worktreePath, ['diff', '-U0', 'HEAD', '--', docPath]);
     const strayHunks = countOutOfScopeHunks(diffU0, run.scope);
     if (strayHunks > 0) candidate.outOfScopeHunks = strayHunks;
 
     const body = [
-      commitTitle(rationale.summary, `Proposal from ${candidate.agentName}`),
+      commitTitle(bodyLine(rationale.summary), `Proposal from ${candidate.agentName}`),
       '',
-      ...rationale.changes.map((c) => `- ${c}`),
+      ...rationale.changes.map((c) => `- ${bodyLine(c)}`),
       '',
       trailerBlock([
         ['Run', run.id],
@@ -596,7 +738,13 @@ async function finalizeCandidate(
       ]),
     ].join('\n');
     await git(worktreePath, ['add', '--', docPath]);
-    await git(worktreePath, ['commit', '-q', '-m', body]);
+    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;
@@ -607,6 +755,36 @@ async function finalizeCandidate(
   }
 }
 
+/**
+ * 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,
@@ -633,14 +811,26 @@ function spawnCandidate(
     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.';
-      proc.kill('SIGTERM');
+      killCandidate(entry);
     }, CANDIDATE_TIMEOUT_MS),
   };
   active.candidates.set(candidate.id, entry);
@@ -649,40 +839,47 @@ function spawnCandidate(
   const log = (text: string) => {
     const clipped =
       text.length > MAX_LOG_LINE_CHARS ? text.slice(0, MAX_LOG_LINE_CHARS) + '…' : text;
-    sendEvent(win, { type: 'log', runId: run.id, candidateId: candidate.id, text: clipped });
+    sendEvent(win, {
+      type: 'log',
+      projectRoot,
+      runId: run.id,
+      candidateId: candidate.id,
+      text: clipped,
+    });
   };
 
-  proc.stdout?.on('data', (chunk: Buffer) => {
-    for (const line of parser.feed(chunk.toString('utf8'))) log(line);
+  proc.stdout?.on('data', (chunk: string) => {
+    for (const line of parser.feed(chunk)) log(line);
   });
-  proc.stderr?.on('data', (chunk: Buffer) => {
-    const text = chunk.toString('utf8');
-    stderrTail = (stderrTail + text).slice(-STDERR_TAIL_CHARS);
-    if (text.trim()) log(text.trimEnd());
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+    if (chunk.trim()) log(chunk.trimEnd());
   });
 
-  let settled = false;
+  let settledOnce = false;
   const settle = async (exitCode: number | null, spawnError?: Error) => {
-    if (settled) return;
-    settled = true;
+    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);
-    sendEvent(win, { type: 'candidate', runId: run.id, candidate });
-    if (active.candidates.size === 0) {
-      activeRuns.delete(run.id);
-      run.status = 'finished';
-      run.finishedAt = nowIso();
-    }
+    const allSettled = active.candidates.size === 0;
+    if (allSettled) activeRuns.delete(run.id);
+    let stored: DocumentRunRecord | null = null;
     try {
-      writeRunRecord(projectRoot, run);
+      stored = await storeCandidateResult(projectRoot, run.id, candidate, allSettled);
     } catch (err) {
       console.warn('[documents] failed to write run record:', err);
     }
-    if (run.status === 'finished') sendEvent(win, { type: 'run', run });
+    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));
@@ -707,6 +904,11 @@ export async function dispatchDocumentRun(
   return withProjectLock(projectRoot, async () => {
     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.',
+      );
+    }
     const baseSha = await commitPendingEdits(projectRoot);
     const runId = randomUUID();
     const run: DocumentRunRecord = {
@@ -778,19 +980,26 @@ export async function dispatchDocumentRun(
       run.finishedAt = nowIso();
     }
     writeRunRecord(projectRoot, run);
-    sendEvent(win, { type: 'run', run });
+    sendEvent(win, { type: 'run', projectRoot, run });
     return run;
   });
 }
 
-export function cancelDocumentRun(runId: unknown): void {
-  const id = validateRunId(runId);
-  const active = activeRuns.get(id);
-  if (!active) return;
+/** 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;
-    entry.proc.kill('SIGTERM');
+    killCandidate(entry);
+    pending.push(entry.settled);
   }
+  return Promise.all(pending).then(() => undefined);
+}
+
+export function cancelDocumentRun(runId: unknown): void {
+  void killRun(validateRunId(runId));
 }
 
 // --- Accept / reject ------------------------------------------------------
@@ -798,14 +1007,16 @@ export function cancelDocumentRun(runId: unknown): void {
 function integrationMessage(run: DocumentRunRecord, candidate: DocumentCandidateRecord): string {
   const rationale = candidate.rationale;
   const lines = [
-    commitTitle(rationale?.summary ?? '', `Accept proposal from ${candidate.agentName}`),
+    commitTitle(bodyLine(rationale?.summary ?? ''), `Accept proposal from ${candidate.agentName}`),
     '',
   ];
-  if (rationale?.changes.length) lines.push(...rationale.changes.map((c) => `- ${c}`), '');
-  if (rationale?.assumptions.length)
-    lines.push('Assumptions:', ...rationale.assumptions.map((c) => `- ${c}`), '');
-  if (rationale?.questions.length)
-    lines.push('Open questions:', ...rationale.questions.map((c) => `- ${c}`), '');
+  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],
@@ -880,10 +1091,16 @@ export async function rejectDocumentRun(
   runIdRaw: unknown,
 ): Promise<DocumentRunRecord> {
   const runId = validateRunId(runIdRaw);
-  cancelDocumentRun(runId);
+  // 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();
@@ -915,32 +1132,45 @@ export function setDocumentCandidateNote(
   runIdRaw: unknown,
   candidateIdRaw: unknown,
   note: unknown,
-): DocumentRunRecord {
+): Promise<DocumentRunRecord> {
   const runId = validateRunId(runIdRaw);
   const candidateId = validateCandidateId(candidateIdRaw);
   if (typeof note !== 'string') throw new Error('note must be a string');
-  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;
+  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. Exported for tests. */
+/**
+ * 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> = {};
-  const text: string[] = [];
-  for (const line of body.split('\n')) {
-    const m = TRAILER_RE.exec(line.trim());
-    if (m) trailers[m[1]] = m[2].trim();
-    else text.push(line);
+  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: text.join('\n').trim(), trailers };
+  return { text: paragraphs.join('\n\n').trim(), trailers };
 }
 
 export async function getDocumentHistory(
@@ -1008,13 +1238,31 @@ export async function getDocumentDiff(
   }
 }
 
+/**
+ * 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();
     try {
-      await git(projectRoot, ['revert', '--no-edit', sha]);
+      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']);
+      const staged = !(await gitOk(projectRoot, ['diff', '--cached', '--quiet']));
+      if (!staged) throw new Error('Nothing to revert outside run metadata.');
+      await git(projectRoot, [
+        'commit',
+        '-q',
+        '-m',
+        `Revert "${subject}"\n\nParallel-Revert: ${sha}`,
+      ]);
     } catch (err) {
-      await gitOk(projectRoot, ['revert', '--abort']);
+      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();
@@ -1036,5 +1284,5 @@ export async function listDocumentFiles(projectRoot: string): Promise<string[]>
 
 /** Kill every running proposal process; used on app quit. */
 export function stopAllDocumentRuns(): void {
-  for (const [runId] of activeRuns) cancelDocumentRun(runId);
+  for (const runId of [...activeRuns.keys()]) void killRun(runId);
 }
diff --git a/electron/ipc/shared-types.ts b/electron/ipc/shared-types.ts
index 9eb653376..f9ad99222 100644
--- a/electron/ipc/shared-types.ts
+++ b/electron/ipc/shared-types.ts
@@ -312,9 +312,9 @@ export interface DocumentRunRecord {
 
 /** Streamed from the main process while a run is in flight. */
 export type DocumentRunEvent =
-  | { type: 'log'; runId: string; candidateId: string; text: string }
-  | { type: 'candidate'; runId: string; candidate: DocumentCandidateRecord }
-  | { type: 'run'; run: DocumentRunRecord };
+  | { 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;
diff --git a/electron/shared/document-agents.ts b/electron/shared/document-agents.ts
index d64cd47c0..63e823157 100644
--- a/electron/shared/document-agents.ts
+++ b/electron/shared/document-agents.ts
@@ -10,12 +10,18 @@ export interface DocumentAgentSupport {
   resume: boolean;
 }
 
+/**
+ * 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 },
   codex: { headless: true, resume: true },
   gemini: { headless: true, resume: false },
-  opencode: { headless: true, resume: false },
-  copilot: { headless: true, resume: false },
 };
 
 export function documentAgentSupport(agentId: string): DocumentAgentSupport {
diff --git a/src/App.tsx b/src/App.tsx
index 998f4bf60..be275d185 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -88,7 +88,12 @@ import { createCtrlWheelZoomHandler } from './lib/wheelZoom';
 import { redrawAllTerminals } from './lib/terminalFitManager';
 import { ArenaOverlay } from './arena/ArenaOverlay';
 import { DocumentWorkspaceOverlay } from './documents/DocumentWorkspaceOverlay';
-import { closeDocumentWorkspace, initDocumentListeners } from './store/documents';
+import {
+  closeDocumentWorkspace,
+  documentStore,
+  initDocumentListeners,
+  setDocumentSelection,
+} from './store/documents';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
@@ -701,7 +706,8 @@ function App() {
           return;
         }
         if (store.activeDocumentProjectId) {
-          closeDocumentWorkspace();
+          if (documentStore.selection) setDocumentSelection(null);
+          else closeDocumentWorkspace();
           return;
         }
         if (store.showHelpDialog) {
diff --git a/src/components/NewTaskDialog.tsx b/src/components/NewTaskDialog.tsx
index f50f0c1b2..2eb416680 100644
--- a/src/components/NewTaskDialog.tsx
+++ b/src/components/NewTaskDialog.tsx
@@ -551,7 +551,11 @@ 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 codeProjects = store.projects.filter((p) => p.kind !== 'document');
+            const fallbackProjectId =
+              codeProjects.find((p) => p.id === store.lastProjectId)?.id ??
+              codeProjects[0]?.id ??
+              null;
             const defaults = dropUrl ? getGitHubDropDefaults(dropUrl) : null;
 
             if (dropUrl) setPrompt(`review ${dropUrl}`);
diff --git a/src/components/ProjectSelect.tsx b/src/components/ProjectSelect.tsx
index 26ec7fb11..316eed2cb 100644
--- a/src/components/ProjectSelect.tsx
+++ b/src/components/ProjectSelect.tsx
@@ -20,7 +20,11 @@ export function ProjectSelect(props: ProjectSelectProps) {
           {props.placeholder}
         </option>
       </Show>
-      <For each={[...store.projects].sort((a, b) => a.name.localeCompare(b.name))}>
+      <For
+        each={store.projects
+          .filter((p) => p.kind !== 'document')
+          .sort((a, b) => a.name.localeCompare(b.name))}
+      >
         {(project) => (
           <option value={project.id}>
             {project.name} — {project.path}
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
index 6c327d202..82684b3b6 100644
--- a/src/documents/CompareView.tsx
+++ b/src/documents/CompareView.tsx
@@ -1,7 +1,15 @@
-import { For, Show, createMemo, createResource, createSignal, untrack } from 'solid-js';
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  untrack,
+} from 'solid-js';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
-import { diffBlocks, type DocumentBlock } from '../lib/markdown-blocks';
+import { diffBlocks, type BlockChange, type DocumentBlock } from '../lib/markdown-blocks';
 import {
   acceptDocumentCandidate,
   documentStore,
@@ -119,6 +127,8 @@ function CandidateColumn(props: {
   baseBlocks: DocumentBlock[];
   revealAgents: boolean;
   showSource: boolean;
+  /** Reports which base blocks this candidate changed or removed. */
+  onBaseChanges: (candidateId: string, changes: BlockChange[]) => void;
 }) {
   let bodyRef: HTMLDivElement | undefined;
   const [content] = createResource(
@@ -129,8 +139,12 @@ function CandidateColumn(props: {
     ({ sha, path }) => fetchDocumentAt(sha, path),
   );
   const rendered = createRenderedBlocks(() => content() ?? null);
-  const changes = createMemo(() => diffBlocks(props.baseBlocks, rendered.blocks()).candidate);
+  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);
+  });
   const [diff] = createResource(
     () =>
       props.showSource && props.candidate.commitSha
@@ -146,9 +160,7 @@ function CandidateColumn(props: {
   const [note, setNote] = createSignal(untrack(() => props.candidate.note ?? ''));
   const [accepting, setAccepting] = createSignal(false);
   const canAccept = () =>
-    !!props.candidate.commitSha &&
-    (props.run.status === 'finished' || props.run.status === 'stale') &&
-    !accepting();
+    !!props.candidate.commitSha && props.run.status === 'finished' && !accepting();
   const title = () =>
     props.revealAgents
       ? `${props.candidate.agentName}${props.candidate.isMain ? ' · main session' : ''}`
@@ -191,7 +203,7 @@ function CandidateColumn(props: {
             disabled={!canAccept()}
             title={
               props.run.status === 'stale'
-                ? 'The document moved since this run; accepting rebases the proposal'
+                ? 'The document moved since this run and the proposal no longer applies. Re-run it.'
                 : 'Accept this candidate as one commit on the canonical branch'
             }
             onClick={() => void accept()}
@@ -205,7 +217,14 @@ function CandidateColumn(props: {
           when={props.candidate.commitSha}
           fallback={<div class="docws-empty">No change proposed.</div>}
         >
-          <Show when={!props.showSource} fallback={<SourceDiff raw={diff() ?? ''} />}>
+          <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>}
@@ -234,6 +253,17 @@ export function CompareView(props: { run: DocumentRunRecord }) {
   const base = createRenderedBlocks(() => baseContent() ?? null);
   const scope = createMemo(() => scopeRange(base.blocks(), props.run));
   const candidates = createMemo(() => props.run.candidates.filter((c) => c.commitSha));
+  // Base blocks touched by any candidate, so a deleted paragraph is visible somewhere.
+  const [baseChanges, setBaseChanges] = createSignal<Record<string, BlockChange[]>>({});
+  const baseMarks = createMemo<BlockChange[]>(() => {
+    const perCandidate = Object.values(baseChanges());
+    return base.blocks().map((_, i) => {
+      const marks = perCandidate.map((m) => m[i]).filter((m): m is BlockChange => !!m);
+      if (marks.includes('removed')) return 'removed';
+      if (marks.includes('changed')) return 'changed';
+      return 'same';
+    });
+  });
   const scopeText = () => {
     const s = props.run.scope;
     if (s.wholeDocument) return 'whole document';
@@ -281,11 +311,19 @@ export function CompareView(props: { run: DocumentRunRecord }) {
           <div class="docws-column-head">
             <div class="docws-column-title">Base · {props.run.baseSha.slice(0, 7)}</div>
             <div class="docws-rationale">
-              <div>The document as every candidate saw it. The scoped passage is marked.</div>
+              <div>
+                The document as every candidate saw it. The scoped passage is outlined; blocks a
+                candidate rewrote or removed are marked.
+              </div>
             </div>
           </div>
           <div class="docws-column-body">
-            <DocumentViewer blocks={base.blocks()} scope={scope()} renderKey="base" />
+            <DocumentViewer
+              blocks={base.blocks()}
+              scope={scope()}
+              changes={baseMarks()}
+              renderKey="base"
+            />
           </div>
         </section>
         <For each={candidates()}>
@@ -296,6 +334,7 @@ export function CompareView(props: { run: DocumentRunRecord }) {
               baseBlocks={base.blocks()}
               revealAgents={revealAgents()}
               showSource={showSource()}
+              onBaseChanges={(id, marks) => setBaseChanges((prev) => ({ ...prev, [id]: marks }))}
             />
           )}
         </For>
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
index 70e125449..23c6e85ae 100644
--- a/src/documents/DocumentViewer.tsx
+++ b/src/documents/DocumentViewer.tsx
@@ -90,8 +90,12 @@ export function DocumentViewer(props: DocumentViewerProps) {
       const start = blockIndexOf(range.startContainer, containerRef);
       const end = blockIndexOf(range.endContainer, containerRef);
       if (start === null && end === null) return;
-      native.removeAllRanges();
-      emitRange({ start: start ?? end ?? 0, end: end ?? start ?? 0 });
+      // 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);
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 2bb845e85..be0f68c14 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -120,10 +120,10 @@ function DocumentPane() {
             onSelect={setDocumentSelection}
             renderKey="main"
           >
-            <Show when={selection()} keyed>
+            <Show when={selection()}>
               {(s) => (
                 <RunComposer
-                  selection={s}
+                  selection={s()}
                   anchorTop={anchorTop()}
                   onClose={() => setDocumentSelection(null)}
                 />
@@ -244,7 +244,7 @@ export function DocumentWorkspaceOverlay() {
               </div>
             </Show>
             <Show
-              when={compareRun()}
+              when={documentStore.compareRunId && compareRun() ? documentStore.compareRunId : null}
               keyed
               fallback={
                 <div class="docws-empty" style={{ padding: '24px' }}>
@@ -252,7 +252,7 @@ export function DocumentWorkspaceOverlay() {
                 </div>
               }
             >
-              {(run) => <CompareView run={run} />}
+              {(runId) => <CompareView run={documentStore.runs[runId]} />}
             </Show>
           </div>
         </Show>
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
index abe91742f..b84a879e9 100644
--- a/src/documents/HistoryView.tsx
+++ b/src/documents/HistoryView.tsx
@@ -1,4 +1,4 @@
-import { For, Show, createResource, createSignal } from 'solid-js';
+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';
@@ -121,7 +121,9 @@ function EntryDetail(props: {
             <DocumentViewer blocks={rendered.blocks()} renderKey={`hist-${props.entry.shortSha}`} />
           }
         >
-          <SourceDiff raw={diff() ?? ''} />
+          <Show when={!diff.loading} fallback={<div class="docws-empty">Loading diff…</div>}>
+            <SourceDiff raw={diff() ?? ''} />
+          </Show>
         </Show>
       </div>
     </div>
@@ -152,7 +154,9 @@ export function HistoryView() {
     },
   );
   const selected = () => entries()?.find((e) => e.sha === selectedSha()) ?? entries()?.[0] ?? null;
-  const nowMs = () => Date.now();
+  const [nowMs, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
 
   return (
     <div class="docws-history">
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
index a05f80b11..d1b7f4660 100644
--- a/src/documents/RunsRail.tsx
+++ b/src/documents/RunsRail.tsx
@@ -1,6 +1,7 @@
-import { For, Show, createMemo } from 'solid-js';
+import { For, Show, createMemo, createSignal, onCleanup } from 'solid-js';
 import {
   cancelDocumentRun,
+  candidateLogKey,
   documentStore,
   openDocumentCompare,
   rejectDocumentRun,
@@ -23,8 +24,12 @@ function candidateState(c: DocumentCandidateRecord): string {
   return 'interrupted';
 }
 
-function CandidateRow(props: { candidate: DocumentCandidateRecord; showLog: boolean }) {
-  const lines = () => documentStore.logs[props.candidate.id] ?? [];
+function CandidateRow(props: {
+  runId: string;
+  candidate: DocumentCandidateRecord;
+  showLog: boolean;
+}) {
+  const lines = () => documentStore.logs[candidateLogKey(props.runId, props.candidate.id)] ?? [];
   const tail = () => lines().slice(-6);
   return (
     <div class="docws-candidate">
@@ -54,7 +59,9 @@ export function RunsRail() {
   const runs = createMemo(() =>
     documentStore.runOrder.map((id) => documentStore.runs[id]).filter(Boolean),
   );
-  const nowMs = () => Date.now();
+  const [nowMs, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
 
   return (
     <aside class="docws-rail" aria-label="Runs">
@@ -86,7 +93,11 @@ export function RunsRail() {
               </div>
               <For each={run.candidates}>
                 {(candidate) => (
-                  <CandidateRow candidate={candidate} showLog={run.status === 'running'} />
+                  <CandidateRow
+                    runId={run.id}
+                    candidate={candidate}
+                    showLog={run.status === 'running'}
+                  />
                 )}
               </For>
               <div class="docws-run-actions">
diff --git a/src/documents/documents.css b/src/documents/documents.css
index cf59535ac..9836ccd5e 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -3,7 +3,9 @@
 .docws-overlay {
   position: fixed;
   inset: 0;
-  z-index: 1900;
+  /* 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;
diff --git a/src/store/documents.ts b/src/store/documents.ts
index 8b1931285..d532c0c32 100644
--- a/src/store/documents.ts
+++ b/src/store/documents.ts
@@ -87,6 +87,11 @@ function watcherKey(projectId: string): string {
   return `doc:${projectId}`;
 }
 
+/** 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();
   if (!project?.documentPath) return;
@@ -95,9 +100,9 @@ export async function refreshDocumentSnapshot(): Promise<void> {
       projectRoot: project.path,
       documentPath: project.documentPath,
     });
-    setDocStore({ snapshot, error: null });
+    if (stillOpen(project.id)) setDocStore({ snapshot, error: null });
   } catch (err) {
-    setDocStore('error', errMessage(err));
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
   }
 }
 
@@ -116,6 +121,7 @@ export async function loadDocumentRuns(): Promise<void> {
     });
     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;
@@ -123,7 +129,7 @@ export async function loadDocumentRuns(): Promise<void> {
       }),
     );
   } catch (err) {
-    setDocStore('error', errMessage(err));
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
   }
 }
 
@@ -147,13 +153,18 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
     selection: null,
   });
   setStore('activeDocumentProjectId', projectId);
-  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns()]);
-  setDocStore('loading', false);
+  // Start watching before the first await so a quick close can stop it.
   void invoke(IPC.StartDocumentWatcher, {
     key: watcherKey(projectId),
     projectRoot: project.path,
     documentPath: project.documentPath,
-  }).catch((err) => setDocStore('error', errMessage(err)));
+  }).catch((err) => {
+    untrack(() => {
+      if (stillOpen(projectId)) setDocStore('error', errMessage(err));
+    });
+  });
+  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns()]);
+  if (stillOpen(projectId)) setDocStore('loading', false);
 }
 
 export function closeDocumentWorkspace(): void {
@@ -177,10 +188,18 @@ export function openDocumentCompare(runId: string): void {
   setDocStore({ compareRunId: runId, view: 'compare' });
 }
 
+/** 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');
+    .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. */
@@ -288,10 +307,16 @@ function upsertRun(run: DocumentRunRecord): void {
   );
 }
 
-/** Remember the main session so the next dispatch resumes it. */
-function recordMainSession(run: DocumentRunRecord, candidate: DocumentCandidateRecord): void {
+/** 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 = activeProject();
+  const project = store.projects.find((p) => p.path === projectRoot && p.kind === 'document');
   if (!project) return;
   updateProject(project.id, {
     documentSessions: {
@@ -302,20 +327,24 @@ function recordMainSession(run: DocumentRunRecord, candidate: DocumentCandidateR
 }
 
 export function applyDocumentRunEvent(event: DocumentRunEvent): void {
+  const forOpenProject = activeProject()?.path === event.projectRoot;
   switch (event.type) {
     case 'log':
+      if (!forOpenProject) return;
       setDocStore(
         produce((s) => {
-          const lines = s.logs[event.candidateId] ?? [];
+          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[event.candidateId] = lines;
+          s.logs[key] = lines;
         }),
       );
       return;
     case 'candidate': {
       const run = docStore.runs[event.runId];
-      if (!run) return;
+      if (run) recordMainSession(event.projectRoot, run, event.candidate);
+      if (!forOpenProject || !run) return;
       setDocStore(
         produce((s) => {
           const target = s.runs[event.runId];
@@ -324,13 +353,22 @@ export function applyDocumentRunEvent(event: DocumentRunEvent): void {
           else target.candidates.push(event.candidate);
         }),
       );
-      recordMainSession(run, event.candidate);
       return;
     }
-    case 'run':
+    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') {
-        for (const c of event.run.candidates) recordMainSession(event.run, c);
+        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
@@ -339,6 +377,7 @@ export function applyDocumentRunEvent(event: DocumentRunEvent): void {
         );
       }
       return;
+    }
   }
 }
 
@@ -415,7 +454,9 @@ interface DocumentChangedPayload {
 }
 
 function isRunEvent(v: unknown): v is DocumentRunEvent {
-  return !!v && typeof v === 'object' && typeof (v as { type?: unknown }).type === 'string';
+  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. */
diff --git a/src/store/projects.ts b/src/store/projects.ts
index ca8d3f2bc..8fd968103 100644
--- a/src/store/projects.ts
+++ b/src/store/projects.ts
@@ -42,10 +42,10 @@ export function addDocumentProject(name: string, path: string, documentPath: str
     kind: 'document',
     documentPath,
   };
+  // Not the default for new tasks: a document project has no task flow.
   setStore(
     produce((s) => {
       s.projects.push(project);
-      s.lastProjectId = id;
     }),
   );
   return id;

From cbac5a06a55eb7b23dd665e4d0a66115f84c5a4d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 4 Sep 2026 06:54:03 +0000
Subject: [PATCH 03/12] feat(documents): add annotations with agent-answered
 questions

Bubbles beside the document that never modify it. The composer gains
Note and Ask modes next to Task; a note is saved under the passage, a
question is answered by a headless read-only agent run in the checkout
(claude with Read/Glob/Grep only, codex --sandbox read-only, gemini
default approval). Question and answer stay visible together.

- Anchors record path, base commit, lines, exact quote, neighbouring
  text and nearest heading in .parallel/annotations.json (version 1).
  The renderer relocates each bubble by quote on the current version,
  disambiguates duplicates by neighbours and heading, and shows the rest
  as detached rather than attaching them to the wrong passage.
- Resolve (r) collapses a bubble to one line; Delete/Backspace removes
  it with an Undo in the toolbar instead of a confirmation. Make task
  reopens the composer on the passage with the bubble's text and answer
  as the instruction and links the bubble to the run.
- Annotations are committed alongside content and metadata commits,
  never on their own, so they stay out of the document history view.
- Backend validates every stored entry, keeps pending answers across
  edits, kills answer processes as a group, and reloads annotations in
  the renderer when HEAD moves.

Tests cover validation, the file round trip, malformed entries, a fake
read-only agent, and anchor relocation; the env-gated real-CLI test now
also asks a question and checks that nothing in the checkout changed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UP9JjPPAYEBBNe1VbGnSzU
---
 docs/document-workspaces.md                   |  18 +-
 electron/ipc/channel-manifest.json            |   7 +-
 electron/ipc/document-agents.ts               |  25 +-
 electron/ipc/document-annotations.test.ts     | 183 ++++++++
 electron/ipc/document-annotations.ts          | 400 ++++++++++++++++++
 .../documents.real-claude.integration.test.ts |  65 ++-
 electron/ipc/documents.ts                     |  17 +-
 electron/ipc/register.ts                      |  33 ++
 electron/ipc/shared-types.ts                  |  60 +++
 electron/main.ts                              |   2 +
 electron/preload.cjs                          |   5 +
 src/documents/AnnotationBubble.tsx            | 215 ++++++++++
 src/documents/DocumentViewer.tsx              |   3 +
 src/documents/DocumentWorkspaceOverlay.tsx    | 111 ++++-
 src/documents/RunComposer.tsx                 | 174 +++++++-
 src/documents/documents.css                   | 161 +++++++
 src/ipc/types.ts                              |   4 +
 src/lib/annotation-anchor.test.ts             |  94 ++++
 src/lib/annotation-anchor.ts                  |  92 ++++
 src/store/documents.ts                        | 209 ++++++++-
 20 files changed, 1841 insertions(+), 37 deletions(-)
 create mode 100644 electron/ipc/document-annotations.test.ts
 create mode 100644 electron/ipc/document-annotations.ts
 create mode 100644 src/documents/AnnotationBubble.tsx
 create mode 100644 src/lib/annotation-anchor.test.ts
 create mode 100644 src/lib/annotation-anchor.ts

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 7dba86207..5c7800770 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -3,7 +3,7 @@
 **A project type in Parallel Code for exploring problems in prose**
 
 Status: experimental, behind the _Document workspaces_ switch in Settings → Experimental.
-Slices 1 and 2 of the plan below are built; annotations and HTML are not.
+Slices 1 to 3 of the plan below are built (the loop, comparison, annotations); HTML is not.
 
 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
@@ -36,6 +36,12 @@ the document.
 6. **History** is `git log` for the document with the `Parallel-*` trailers parsed:
    what changed, which agent, which instruction, which base. Show the diff or render the
    older version. Revert any entry.
+7. **Annotations.** The same composer offers **Note** and **Ask** beside **Task**. A note
+   is a bubble under the passage. A question is a bubble an agent answers into, running
+   read-only in the checkout; question and answer stay visible together. Resolve (`r`)
+   collapses a bubble to one line, Delete removes it with an Undo in the toolbar, and
+   **Make task** reopens the composer on the passage with the bubble's text (and answer)
+   as the instruction; the bubble then collapses as `task`.
 
 ### How it works
 
@@ -83,12 +89,18 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   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, using neighbours and heading when the same passage appears twice, and shows it
+  as **detached** rather than attaching it 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.
 
 ### Not in this slice
 
-Annotations, HTML documents, partial acceptance, evaluator agents, refinement rounds,
-durable anchors across versions, in-app editing. Custom agents, OpenCode and Copilot
+HTML documents, partial acceptance, evaluator agents, refinement rounds, threaded
+annotations, in-app editing. Custom agents, OpenCode and Copilot
 cannot be picked. Gemini runs one-shot only.
 
 ---
diff --git a/electron/ipc/channel-manifest.json b/electron/ipc/channel-manifest.json
index 0a1b9afae..70beef0ae 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -163,5 +163,10 @@
   "RevertDocumentCommit": "revert_document_commit",
   "ListDocumentFiles": "list_document_files",
   "DocumentChanged": "document_changed",
-  "DocumentRunEvent": "document_run_event"
+  "DocumentRunEvent": "document_run_event",
+  "ListDocumentAnnotations": "list_document_annotations",
+  "SaveDocumentAnnotation": "save_document_annotation",
+  "DeleteDocumentAnnotation": "delete_document_annotation",
+  "AskDocumentAnnotation": "ask_document_annotation",
+  "DocumentAnnotationEvent": "document_annotation_event"
 }
diff --git a/electron/ipc/document-agents.ts b/electron/ipc/document-agents.ts
index e7a99feca..b9fab2fde 100644
--- a/electron/ipc/document-agents.ts
+++ b/electron/ipc/document-agents.ts
@@ -18,6 +18,8 @@ export interface HeadlessLaunchOptions {
   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;
 }
 
 export interface HeadlessOutcome {
@@ -37,6 +39,8 @@ export interface HeadlessOutputParser {
 
 /** 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);
@@ -54,16 +58,22 @@ export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch
         'stream-json',
         '--verbose',
         '--permission-mode',
-        'acceptEdits',
+        opts.readOnly ? 'default' : 'acceptEdits',
         '--tools',
-        CLAUDE_DOCUMENT_TOOLS,
+        opts.readOnly ? CLAUDE_READ_ONLY_TOOLS : CLAUDE_DOCUMENT_TOOLS,
       ];
       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', 'workspace-write', '--skip-git-repo-check'];
+      const args = [
+        'exec',
+        '--json',
+        '--sandbox',
+        opts.readOnly ? 'read-only' : 'workspace-write',
+        '--skip-git-repo-check',
+      ];
       if (resume) args.push('resume', resume, opts.prompt);
       else args.push(opts.prompt);
       return { command: opts.command, args };
@@ -71,7 +81,14 @@ export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch
     case 'gemini':
       return {
         command: opts.command,
-        args: ['-p', opts.prompt, '--output-format', 'json', '--approval-mode', 'auto_edit'],
+        args: [
+          '-p',
+          opts.prompt,
+          '--output-format',
+          'json',
+          '--approval-mode',
+          opts.readOnly ? 'default' : 'auto_edit',
+        ],
       };
     default:
       throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
diff --git a/electron/ipc/document-annotations.test.ts b/electron/ipc/document-annotations.test.ts
new file mode 100644
index 000000000..278f0c68e
--- /dev/null
+++ b/electron/ipc/document-annotations.test.ts
@@ -0,0 +1,183 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import {
+  askAnnotation,
+  buildAnnotationPrompt,
+  deleteAnnotation,
+  readAnnotations,
+  saveAnnotation,
+  validateAnnotationInput,
+} from './document-annotations.js';
+import type { DocumentAnnotation, DocumentAnnotationEvent } from './shared-types.js';
+
+const anchor = {
+  path: 'docs/spec.md',
+  baseSha: 'abcdef1234567',
+  startLine: 5,
+  endLine: 7,
+  quote: '## Goals\n\nOld goals text.',
+  prefix: 'Intro paragraph.',
+  suffix: '## Later',
+  heading: 'Goals',
+};
+
+function note(id: string, extra: Partial<DocumentAnnotation> = {}): Record<string, unknown> {
+  return {
+    id,
+    kind: 'note',
+    anchor,
+    text: `note ${id}`,
+    createdAt: '2026-01-01T00:00:00Z',
+    ...extra,
+  };
+}
+
+describe('validateAnnotationInput', () => {
+  it('normalizes a note', () => {
+    const a = validateAnnotationInput(note('n-1', { resolved: true }));
+    expect(a.kind).toBe('note');
+    expect(a.resolved).toBe(true);
+    expect(a.anchor.heading).toBe('Goals');
+    expect(a.answer).toBeUndefined();
+  });
+  it('rejects bad ids, kinds, anchors and shas', () => {
+    expect(() => validateAnnotationInput(note('bad id!'))).toThrow(/id/);
+    expect(() => validateAnnotationInput({ ...note('n-1'), kind: 'task' })).toThrow(/kind/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, startLine: 9, endLine: 2 } }),
+    ).toThrow(/lines/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, baseSha: 'HEAD' } }),
+    ).toThrow(/baseSha/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, path: '../x.md' } }),
+    ).toThrow();
+  });
+  it('drops unknown statuses and run ids', () => {
+    const a = validateAnnotationInput({ ...note('n-1'), answerStatus: 'weird', runId: 'bad id' });
+    expect(a.answerStatus).toBeUndefined();
+    expect(a.runId).toBeUndefined();
+  });
+});
+
+describe('buildAnnotationPrompt', () => {
+  it('quotes the passage and forbids edits', () => {
+    const prompt = buildAnnotationPrompt(
+      validateAnnotationInput({ ...note('q-1'), kind: 'question', text: 'Why?' }),
+    );
+    expect(prompt).toContain('Document: docs/spec.md');
+    expect(prompt).toContain('lines 5-7 (under "Goals")');
+    expect(prompt).toContain('> Old goals text.');
+    expect(prompt).toContain('Question:\nWhy?');
+    expect(prompt).toContain('Do not edit');
+  });
+});
+
+describe('annotations file and asking', () => {
+  let root: string;
+  let fakeAgent: string;
+  const events: DocumentAnnotationEvent[] = [];
+  const win = {
+    isDestroyed: () => false,
+    webContents: { send: (_ch: string, payload: DocumentAnnotationEvent) => events.push(payload) },
+  } as unknown as BrowserWindow;
+
+  beforeAll(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-'));
+    const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-bin-'));
+    fakeAgent = path.join(binDir, 'fake-claude.sh');
+    fs.writeFileSync(
+      fakeAgent,
+      [
+        '#!/bin/sh',
+        // Prove read-only tools were requested and answer.
+        'case "$*" in *"Read,Glob,Grep"*) ;; *) echo "wrong tools" >&2; exit 2;; esac',
+        'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"s","result":"The passage assumes **nothing**."}\'',
+      ].join('\n') + '\n',
+      { mode: 0o755 },
+    );
+  });
+
+  afterAll(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('round-trips annotations and keeps a pending answer across edits', async () => {
+    expect(readAnnotations(root)).toEqual([]);
+    await saveAnnotation(root, note('a-1'));
+    await saveAnnotation(root, note('a-2', { kind: 'question', text: 'Why?' }));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-1', 'a-2']);
+    expect(fs.existsSync(path.join(root, '.parallel', 'annotations.json'))).toBe(true);
+
+    const edited = await saveAnnotation(root, { ...note('a-1'), text: 'edited', resolved: true });
+    expect(edited.text).toBe('edited');
+    expect(readAnnotations(root)[0].createdAt).toBe('2026-01-01T00:00:00Z');
+
+    await deleteAnnotation(root, 'a-1');
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('skips malformed entries instead of losing the file', async () => {
+    const file = path.join(root, '.parallel', 'annotations.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as { annotations: unknown[] };
+    raw.annotations.push({ id: 'bad', kind: 'note' });
+    fs.writeFileSync(file, JSON.stringify(raw));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('asks a read-only agent and stores the answer in the bubble', async () => {
+    const pending = await askAnnotation(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      annotationId: 'a-2',
+      agentId: 'claude-code',
+      agentName: 'Fake Claude',
+      command: fakeAgent,
+    });
+    expect(pending.answerStatus).toBe('pending');
+    const answered = await new Promise<DocumentAnnotation>((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = events.find(
+          (e) => e.annotation.id === 'a-2' && e.annotation.answerStatus !== 'pending',
+        );
+        if (done) return resolve(done.annotation);
+        if (Date.now() - started > 10_000) return reject(new Error('no answer'));
+        setTimeout(tick, 50);
+      };
+      tick();
+    });
+    expect(answered.answerStatus).toBe('answered');
+    expect(answered.answer?.text).toContain('assumes **nothing**');
+    expect(answered.answer?.agentName).toBe('Fake Claude');
+    expect(readAnnotations(root)[0].answer?.text).toContain('nothing');
+    // Question and answer both survive: the question text is untouched.
+    expect(readAnnotations(root)[0].text).toBe('Why?');
+  });
+
+  it('refuses agents without a headless mode and unknown annotations', async () => {
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'a-2',
+        agentId: 'opencode',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/no headless mode/);
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'missing-1',
+        agentId: 'claude-code',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/not found/);
+  });
+});
diff --git a/electron/ipc/document-annotations.ts b/electron/ipc/document-annotations.ts
new file mode 100644
index 000000000..92efefbc1
--- /dev/null
+++ b/electron/ipc/document-annotations.ts
@@ -0,0 +1,400 @@
+/**
+ * Annotations for document workspaces: notes and agent-answered questions
+ * anchored to a passage. They sit beside the document and never modify it,
+ * which makes them the safe way to interrogate a draft.
+ */
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from './channels.js';
+import { errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from './pty.js';
+import { loadEnvFile } from './env-file.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './document-agents.js';
+import { documentAgentSupport } from '../shared/document-agents.js';
+import { validateDocumentPath, validateSha } from './documents.js';
+import type {
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationsFile,
+} from './shared-types.js';
+
+export const ANNOTATIONS_REL_PATH = path.posix.join('.parallel', 'annotations.json');
+const MAX_TEXT_CHARS = 20_000;
+const MAX_ANSWER_CHARS = 50_000;
+const MAX_ANNOTATIONS = 2_000;
+const ANSWER_TIMEOUT_MS = 10 * 60_000;
+const KILL_GRACE_MS = 5_000;
+
+function annotationsPath(projectRoot: string): string {
+  return path.join(projectRoot, ANNOTATIONS_REL_PATH);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+// --- Validation -----------------------------------------------------------
+
+function validateAnnotationId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{1,64}$/i.test(value))
+    throw new Error('annotation id is invalid');
+  return value;
+}
+
+function text(value: unknown, label: string, max = MAX_TEXT_CHARS): string {
+  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
+  return value.slice(0, max);
+}
+
+function validateAnchor(value: unknown): DocumentAnchor {
+  if (!value || typeof value !== 'object') throw new Error('anchor must be an object');
+  const a = value as Record<string, unknown>;
+  const startLine = Number(a.startLine);
+  const endLine = Number(a.endLine);
+  if (
+    !Number.isInteger(startLine) ||
+    !Number.isInteger(endLine) ||
+    startLine < 1 ||
+    endLine < startLine
+  )
+    throw new Error('anchor lines are invalid');
+  const baseSha =
+    a.baseSha === null || a.baseSha === undefined ? null : validateSha(a.baseSha, 'anchor.baseSha');
+  const heading =
+    typeof a.heading === 'string' && a.heading.trim() ? a.heading.slice(0, 300) : undefined;
+  return {
+    path: validateDocumentPath(a.path),
+    baseSha,
+    startLine,
+    endLine,
+    quote: text(a.quote, 'anchor.quote'),
+    prefix: text(a.prefix, 'anchor.prefix', 500),
+    suffix: text(a.suffix, 'anchor.suffix', 500),
+    heading,
+  };
+}
+
+/** Accepts what the renderer sends for a new or edited annotation. */
+export function validateAnnotationInput(value: unknown): DocumentAnnotation {
+  if (!value || typeof value !== 'object') throw new Error('annotation must be an object');
+  const v = value as Record<string, unknown>;
+  const kind = v.kind === 'question' ? 'question' : v.kind === 'note' ? 'note' : null;
+  if (!kind) throw new Error('annotation kind is invalid');
+  const id = validateAnnotationId(v.id);
+  const answer =
+    v.answer && typeof v.answer === 'object'
+      ? {
+          text: text((v.answer as Record<string, unknown>).text, 'answer.text', MAX_ANSWER_CHARS),
+          agentId: text((v.answer as Record<string, unknown>).agentId, 'answer.agentId', 64),
+          agentName: text((v.answer as Record<string, unknown>).agentName, 'answer.agentName', 64),
+          answeredAt: text(
+            (v.answer as Record<string, unknown>).answeredAt,
+            'answer.answeredAt',
+            64,
+          ),
+        }
+      : undefined;
+  const status = v.answerStatus;
+  const runId =
+    typeof v.runId === 'string' && /^[a-z0-9-]{1,64}$/i.test(v.runId) ? v.runId : undefined;
+  return {
+    id,
+    kind,
+    anchor: validateAnchor(v.anchor),
+    text: text(v.text, 'text'),
+    createdAt: typeof v.createdAt === 'string' ? v.createdAt.slice(0, 64) : nowIso(),
+    updatedAt: nowIso(),
+    resolved: v.resolved === true,
+    answer,
+    answerStatus:
+      status === 'pending' || status === 'answered' || status === 'failed' ? status : undefined,
+    answerError: typeof v.answerError === 'string' ? v.answerError.slice(0, 2_000) : undefined,
+    runId,
+  };
+}
+
+// --- File -----------------------------------------------------------------
+
+export function readAnnotations(projectRoot: string): DocumentAnnotation[] {
+  try {
+    const raw = JSON.parse(fs.readFileSync(annotationsPath(projectRoot), 'utf-8')) as unknown;
+    if (!raw || typeof raw !== 'object') return [];
+    const file = raw as Partial<DocumentAnnotationsFile>;
+    if (file.version !== 1 || !Array.isArray(file.annotations)) return [];
+    const out: DocumentAnnotation[] = [];
+    for (const entry of file.annotations) {
+      try {
+        const valid = validateAnnotationInput(entry);
+        // Keep the stored timestamp; validation stamps "now" for edits only.
+        valid.updatedAt =
+          typeof (entry as DocumentAnnotation).updatedAt === 'string'
+            ? (entry as DocumentAnnotation).updatedAt
+            : valid.updatedAt;
+        out.push(valid);
+      } catch {
+        // A malformed entry (hand-edited or from another tool) is skipped, not fatal.
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function writeAnnotations(projectRoot: string, annotations: DocumentAnnotation[]): void {
+  const file: DocumentAnnotationsFile = { version: 1, annotations };
+  fs.mkdirSync(path.dirname(annotationsPath(projectRoot)), { recursive: true });
+  atomicWriteFileSync(annotationsPath(projectRoot), JSON.stringify(file, null, 2) + '\n');
+}
+
+const fileLocks = new Map<string, Promise<void>>();
+
+function withFileLock<T>(projectRoot: string, fn: () => T | Promise<T>): Promise<T> {
+  const key = path.resolve(projectRoot);
+  const prev = fileLocks.get(key) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  fileLocks.set(
+    key,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+export function saveAnnotation(projectRoot: string, input: unknown): Promise<DocumentAnnotation> {
+  const annotation = validateAnnotationInput(input);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const idx = all.findIndex((a) => a.id === annotation.id);
+    if (idx >= 0) {
+      // A pending answer belongs to the running ask, not to the edit.
+      const stored = all[idx];
+      if (stored.answerStatus === 'pending' && annotation.answerStatus !== 'pending') {
+        annotation.answer = stored.answer;
+        annotation.answerStatus = stored.answerStatus;
+      }
+      annotation.createdAt = stored.createdAt;
+      all[idx] = annotation;
+    } else {
+      if (all.length >= MAX_ANNOTATIONS) throw new Error('Too many annotations in this project.');
+      all.push(annotation);
+    }
+    writeAnnotations(projectRoot, all);
+    return annotation;
+  });
+}
+
+export function deleteAnnotation(projectRoot: string, idRaw: unknown): Promise<void> {
+  const id = validateAnnotationId(idRaw);
+  cancelAsk(id);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    writeAnnotations(
+      projectRoot,
+      all.filter((a) => a.id !== id),
+    );
+  });
+}
+
+function updateAnnotation(
+  projectRoot: string,
+  id: string,
+  mutate: (a: DocumentAnnotation) => void,
+): Promise<DocumentAnnotation | null> {
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const target = all.find((a) => a.id === id);
+    if (!target) return null;
+    mutate(target);
+    target.updatedAt = nowIso();
+    writeAnnotations(projectRoot, all);
+    return target;
+  });
+}
+
+// --- Asking an agent ------------------------------------------------------
+
+export interface AskAnnotationArgs {
+  projectRoot: string;
+  documentPath: unknown;
+  annotationId: unknown;
+  agentId: unknown;
+  agentName: unknown;
+  command: unknown;
+  envFile?: unknown;
+}
+
+interface ActiveAsk {
+  proc: ChildProcess;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const activeAsks = new Map<string, ActiveAsk>();
+
+/** Builds the read-only question prompt. Exported for tests. */
+export function buildAnnotationPrompt(annotation: DocumentAnnotation): string {
+  const a = annotation.anchor;
+  const where = a.heading
+    ? `lines ${a.startLine}-${a.endLine} (under "${a.heading}")`
+    : `lines ${a.startLine}-${a.endLine}`;
+  const quote = a.quote
+    .split('\n')
+    .map((l) => `> ${l}`)
+    .join('\n');
+  return [
+    'You are answering a question about a document in a Parallel Code document workspace. ' +
+      'Read the document (and anything else in the project you need) but do not modify any file.',
+    `Document: ${a.path}`,
+    `Passage: ${where}\n${quote}`,
+    `Question:\n${annotation.text.trim()}`,
+    [
+      'Rules:',
+      '- Answer the question about this passage directly and concisely, in Markdown.',
+      '- Quote the document where it supports your answer; say plainly when it does not.',
+      '- Do not rewrite the passage unless the question asks for a rewrite, and then show it as a suggestion.',
+      '- Do not edit, create or delete files, and do not run commands.',
+    ].join('\n'),
+  ].join('\n\n');
+}
+
+function killAsk(entry: ActiveAsk): void {
+  const pid = entry.proc.pid;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      if (pid) process.kill(-pid, sig);
+      else entry.proc.kill(sig);
+    } catch {
+      // Already gone.
+    }
+  };
+  signal('SIGTERM');
+  setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS).unref?.();
+}
+
+export function cancelAsk(annotationId: string): void {
+  const entry = activeAsks.get(annotationId);
+  if (!entry) return;
+  clearTimeout(entry.timer);
+  activeAsks.delete(annotationId);
+  killAsk(entry);
+}
+
+export function stopAllAsks(): void {
+  for (const id of [...activeAsks.keys()]) cancelAsk(id);
+}
+
+/**
+ * Runs a headless, read-only agent in the project checkout and writes its
+ * final message into the annotation. Progress is pushed as
+ * `IPC.DocumentAnnotationEvent`.
+ */
+export async function askAnnotation(
+  win: BrowserWindow,
+  args: AskAnnotationArgs,
+): Promise<DocumentAnnotation> {
+  const { projectRoot } = args;
+  validateDocumentPath(args.documentPath);
+  const annotationId = validateAnnotationId(args.annotationId);
+  const agentId = text(args.agentId, 'agentId', 64);
+  if (!documentAgentSupport(agentId).headless)
+    throw new Error(`Agent "${agentId}" has no headless mode for document questions.`);
+  const agentName = text(args.agentName, 'agentName', 64);
+  const command = text(args.command, 'command', 200);
+  if (!command.trim() || /[\s;&|<>$`'"\\]/.test(command)) throw new Error('command is invalid');
+  const envFile = args.envFile === undefined ? undefined : text(args.envFile, 'envFile', 1_000);
+  validateCommand(command);
+
+  cancelAsk(annotationId);
+  const annotation = await updateAnnotation(projectRoot, annotationId, (a) => {
+    a.kind = 'question';
+    a.answerStatus = 'pending';
+    a.answerError = undefined;
+  });
+  if (!annotation) throw new Error('Annotation not found');
+
+  const launch = buildHeadlessLaunch({
+    agentId,
+    command,
+    prompt: buildAnnotationPrompt(annotation),
+    newSessionId: randomUUID(),
+    readOnly: true,
+  });
+  const env = buildPtySpawnEnv({}, envFile?.trim() ? loadEnvFile(envFile) : {});
+  const parser = createHeadlessParser(agentId);
+  const proc = spawn(launch.command, launch.args, {
+    cwd: projectRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  proc.stdout?.setEncoding('utf8');
+  proc.stderr?.setEncoding('utf8');
+  let stderrTail = '';
+  proc.stdout?.on('data', (chunk: string) => void parser.feed(chunk));
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-4_000);
+  });
+
+  const entry: ActiveAsk = {
+    proc,
+    timer: setTimeout(() => {
+      stderrTail = 'Timed out.';
+      killAsk(entry);
+    }, ANSWER_TIMEOUT_MS),
+  };
+  activeAsks.set(annotationId, entry);
+
+  const emit = (a: DocumentAnnotation) => {
+    if (!win.isDestroyed()) {
+      const event: DocumentAnnotationEvent = { projectRoot, annotation: a };
+      win.webContents.send(IPC.DocumentAnnotationEvent, event);
+    }
+  };
+  emit(annotation);
+
+  let settled = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(entry.timer);
+    const wasActive = activeAsks.get(annotationId) === entry;
+    if (wasActive) activeAsks.delete(annotationId);
+    const outcome = parser.finish();
+    const failure =
+      spawnError?.message ??
+      outcome.error ??
+      (!outcome.resultText.trim()
+        ? stderrTail.trim() || `The agent exited with code ${exitCode ?? 'unknown'} and no answer.`
+        : undefined);
+    const updated = await updateAnnotation(projectRoot, annotationId, (a) => {
+      if (!wasActive) return; // cancelled or superseded: leave whatever the newer ask wrote
+      if (failure && !outcome.resultText.trim()) {
+        a.answerStatus = 'failed';
+        a.answerError = failure.slice(0, 2_000);
+      } else {
+        a.answerStatus = 'answered';
+        a.answerError = failure?.slice(0, 2_000);
+        a.answer = {
+          text: outcome.resultText.slice(0, MAX_ANSWER_CHARS),
+          agentId,
+          agentName,
+          answeredAt: nowIso(),
+        };
+      }
+    }).catch((err) => {
+      console.warn('[annotations] failed to store answer:', errMessage(err));
+      return null;
+    });
+    if (updated && wasActive) emit(updated);
+  };
+  proc.on('close', (code) => void settle(code));
+  proc.on('error', (err) => void settle(1, err));
+  return annotation;
+}
diff --git a/electron/ipc/documents.real-claude.integration.test.ts b/electron/ipc/documents.real-claude.integration.test.ts
index ce63fab14..de9df2230 100644
--- a/electron/ipc/documents.real-claude.integration.test.ts
+++ b/electron/ipc/documents.real-claude.integration.test.ts
@@ -5,7 +5,13 @@ import os from 'os';
 import path from 'path';
 import type { BrowserWindow } from 'electron';
 import { acceptDocumentCandidate, dispatchDocumentRun } from './documents.js';
-import type { DocumentRunEvent, DocumentRunRecord } from './shared-types.js';
+import { askAnnotation, readAnnotations, saveAnnotation } from './document-annotations.js';
+import type {
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentRunEvent,
+  DocumentRunRecord,
+} from './shared-types.js';
 
 /**
  * Drives the real `claude` CLI through one proposal and one resumed follow-up.
@@ -36,9 +42,16 @@ const DOC = [
 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) => events.push(payload) },
+    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> {
@@ -147,4 +160,52 @@ describe.skipIf(!RUN)('document workspace with the real claude CLI', () => {
     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/ipc/documents.ts b/electron/ipc/documents.ts
index 599d850f7..628996455 100644
--- a/electron/ipc/documents.ts
+++ b/electron/ipc/documents.ts
@@ -37,6 +37,8 @@ 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;
@@ -506,8 +508,9 @@ function runOwningBranch(projectRoot: string, branch: string): DocumentRunRecord
  */
 export async function commitPendingEdits(projectRoot: string): Promise<string> {
   ensureWorktreeContainerExclude(projectRoot);
-  if (await isDirty(projectRoot)) {
-    await git(projectRoot, ['add', '-u', ...CONTENT_PATHSPEC]);
+  await git(projectRoot, ['add', '-u', ...CONTENT_PATHSPEC]);
+  await stageAnnotations(projectRoot);
+  if (!(await gitOk(projectRoot, ['diff', '--cached', '--quiet']))) {
     await git(projectRoot, ['commit', '-q', '-m', 'Manual edits']);
   }
   const sha = await headSha(projectRoot);
@@ -515,6 +518,12 @@ export async function commitPendingEdits(projectRoot: string): Promise<string> {
   return sha;
 }
 
+/** Annotations are committed alongside content and metadata, never on their own. */
+async function stageAnnotations(projectRoot: string): Promise<void> {
+  if (!fs.existsSync(path.join(projectRoot, ANNOTATIONS_FILE))) return;
+  await gitOk(projectRoot, ['add', '-f', '--', ANNOTATIONS_FILE]);
+}
+
 // --- Worktrees ------------------------------------------------------------
 
 function shortRunId(runId: string): string {
@@ -1072,6 +1081,7 @@ export async function acceptDocumentCandidate(
     writeRunRecord(projectRoot, run);
     try {
       await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      await stageAnnotations(projectRoot);
       await git(projectRoot, ['commit', '-q', '-m', integrationMessage(run, candidate)]);
     } catch (err) {
       await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
@@ -1112,13 +1122,12 @@ export async function rejectDocumentRun(
     // touching content: a metadata-only commit the history view filters out.
     try {
       await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      await stageAnnotations(projectRoot);
       await git(projectRoot, [
         'commit',
         '-q',
         '-m',
         `Reject proposals\n\nParallel-Run: ${runId}\nParallel-Metadata: true`,
-        '--',
-        runRecordRelPath(runId),
       ]);
     } catch (err) {
       console.warn('[documents] could not commit rejected run record:', err);
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index 748a94581..b9959128c 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -112,6 +112,12 @@ import {
   validateDocumentPath,
   validateSha,
 } from './documents.js';
+import {
+  askAnnotation,
+  deleteAnnotation,
+  readAnnotations,
+  saveAnnotation,
+} from './document-annotations.js';
 import { setMinimaxApiKey } from './ask-code-minimax.js';
 import { getSystemMonospaceFonts } from './system-fonts.js';
 import { fetchClaudeUsage } from './claude-usage.js';
@@ -1072,6 +1078,33 @@ export function registerAllHandlers(win: BrowserWindow): void {
     return revertDocumentCommit(projectRoot, validateSha(args.sha));
   });
 
+  // --- Document 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,
+    });
+  });
+
   // --- File links ---
   ipcMain.handle(IPC.OpenPath, (_e, args) => {
     validatePath(args.filePath, 'filePath');
diff --git a/electron/ipc/shared-types.ts b/electron/ipc/shared-types.ts
index f9ad99222..71f218425 100644
--- a/electron/ipc/shared-types.ts
+++ b/electron/ipc/shared-types.ts
@@ -344,3 +344,63 @@ export interface DocumentHistoryEntry {
   /** True when no agent trailer is present: a manual commit. */
   manual: boolean;
 }
+
+// --- Document annotations ---
+
+/**
+ * Where an annotation sits. Offsets alone go stale as soon as anything above
+ * them changes, so the anchor also carries the exact quote, its neighbours
+ * and the nearest heading; the renderer relocates it on the current version
+ * and shows it detached when it cannot.
+ */
+export interface DocumentAnchor {
+  path: string;
+  /** Commit the offsets were taken against. */
+  baseSha: string | null;
+  startLine: number;
+  endLine: number;
+  /** Exact source text of the anchored blocks. */
+  quote: string;
+  /** Tail of the preceding block and head of the following one. */
+  prefix: string;
+  suffix: string;
+  heading?: string;
+}
+
+export type DocumentAnnotationKind = 'note' | 'question';
+
+export interface DocumentAnnotationAnswer {
+  text: string;
+  agentId: string;
+  agentName: string;
+  answeredAt: string;
+}
+
+export type DocumentAnswerStatus = 'pending' | 'answered' | 'failed';
+
+/** A bubble beside the document: a note, or a question an agent answers into it. */
+export interface DocumentAnnotation {
+  id: string;
+  kind: DocumentAnnotationKind;
+  anchor: DocumentAnchor;
+  text: string;
+  createdAt: string;
+  updatedAt: string;
+  resolved: boolean;
+  answer?: DocumentAnnotationAnswer;
+  answerStatus?: DocumentAnswerStatus;
+  answerError?: string;
+  /** Run this annotation was turned into, if any. */
+  runId?: string;
+}
+
+/** Persisted as `.parallel/annotations.json` inside the document project. */
+export interface DocumentAnnotationsFile {
+  version: 1;
+  annotations: DocumentAnnotation[];
+}
+
+export interface DocumentAnnotationEvent {
+  projectRoot: string;
+  annotation: DocumentAnnotation;
+}
diff --git a/electron/main.ts b/electron/main.ts
index 30bdc8b97..5b3a25c6c 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -11,6 +11,7 @@ import { startAgentHookRuntime, stopAgentHookRuntime } from './agent-hooks/runti
 import { killAllAgents } from './ipc/pty.js';
 import { stopAllPlanWatchers } from './ipc/plans.js';
 import { stopAllDocumentRuns, stopAllDocumentWatchers } from './ipc/documents.js';
+import { stopAllAsks } from './ipc/document-annotations.js';
 import { stopAllStepsWatchers } from './ipc/steps.js';
 import { verificationRunner } from './ipc/verify.js';
 import { IPC } from './ipc/channels.js';
@@ -291,6 +292,7 @@ app.on('will-quit', () => {
   stopAllPlanWatchers();
   stopAllDocumentWatchers();
   stopAllDocumentRuns();
+  stopAllAsks();
   stopAllStepsWatchers();
 });
 
diff --git a/electron/preload.cjs b/electron/preload.cjs
index e4527b048..67a121166 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -168,6 +168,11 @@ const ALLOWED_CHANNELS = new Set([
   'list_document_files',
   'document_changed',
   'document_run_event',
+  'list_document_annotations',
+  'save_document_annotation',
+  'delete_document_annotation',
+  'ask_document_annotation',
+  'document_annotation_event',
 ]);
 
 function isAllowedChannel(channel) {
diff --git a/src/documents/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
new file mode 100644
index 000000000..3d0aebfde
--- /dev/null
+++ b/src/documents/AnnotationBubble.tsx
@@ -0,0 +1,215 @@
+import { For, Show, createMemo, createSignal } from 'solid-js';
+import { createHighlightedMarkdown } from '../lib/marked-shiki';
+import { store } from '../store/core';
+import { getProject } from '../store/projects';
+import {
+  askDocumentAnnotation,
+  deleteDocumentAnnotation,
+  documentMainAgentId,
+  documentStore,
+  setDocumentAnnotationResolved,
+  updateDocumentAnnotationText,
+} from '../store/documents';
+import { documentAgentSupport } from '../../electron/shared/document-agents';
+import type { DocumentAnnotation } from '../ipc/types';
+
+interface AnnotationBubbleProps {
+  annotation: DocumentAnnotation;
+  /** The passage could not be found in the current version. */
+  detached?: boolean;
+  onMakeTask: (annotation: DocumentAnnotation) => void;
+}
+
+/**
+ * A note or a question beside the document. Resolved bubbles collapse to one
+ * line; Delete or Backspace on a focused bubble removes it, with undo in the
+ * toolbar instead of a confirmation.
+ */
+export function AnnotationBubble(props: AnnotationBubbleProps) {
+  const [editing, setEditing] = createSignal(false);
+  const [draft, setDraft] = createSignal('');
+  const answerHtml = createHighlightedMarkdown(() => props.annotation.answer?.text);
+  const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
+  const askAgents = createMemo(() =>
+    store.availableAgents.filter(
+      (a) => a.available !== false && documentAgentSupport(a.id).headless,
+    ),
+  );
+  const defaultAgent = () =>
+    askAgents().find((a) => a.id === documentMainAgentId(project())) ?? askAgents()[0];
+  const isQuestion = () => props.annotation.kind === 'question';
+  const status = () => props.annotation.answerStatus;
+
+  function handleKeyDown(e: KeyboardEvent) {
+    if (editing()) return;
+    if (e.target instanceof HTMLTextAreaElement || e.target instanceof HTMLInputElement) return;
+    if (e.key === 'Delete' || e.key === 'Backspace') {
+      e.preventDefault();
+      void deleteDocumentAnnotation(props.annotation.id);
+    } else if (e.key === 'r' && !e.metaKey && !e.ctrlKey) {
+      e.preventDefault();
+      void setDocumentAnnotationResolved(props.annotation.id, !props.annotation.resolved);
+    }
+  }
+
+  function startEdit() {
+    setDraft(props.annotation.text);
+    setEditing(true);
+  }
+
+  function commitEdit() {
+    setEditing(false);
+    void updateDocumentAnnotationText(props.annotation.id, draft().trim() || props.annotation.text);
+  }
+
+  const kindLabel = () => (isQuestion() ? 'Question' : 'Note');
+
+  return (
+    <div
+      class="docws-bubble"
+      classList={{
+        'is-resolved': props.annotation.resolved,
+        'is-detached': props.detached === true,
+        'is-question': isQuestion(),
+      }}
+      tabIndex={0}
+      role="group"
+      aria-label={`${kindLabel()}: ${props.annotation.text.slice(0, 80)}`}
+      onKeyDown={handleKeyDown}
+    >
+      <Show
+        when={!props.annotation.resolved}
+        fallback={
+          <button
+            type="button"
+            class="docws-bubble-collapsed"
+            title="Resolved. Click to reopen."
+            onClick={() => void setDocumentAnnotationResolved(props.annotation.id, false)}
+          >
+            <span class="docws-badge">{props.annotation.runId ? 'task' : 'resolved'}</span>
+            <span class="docws-bubble-collapsed-text">{props.annotation.text}</span>
+          </button>
+        }
+      >
+        <div class="docws-bubble-head">
+          <span class="docws-badge">{kindLabel()}</span>
+          <Show when={props.detached}>
+            <span
+              class="docws-badge docws-badge-stale"
+              title="The passage this was attached to is no longer in the document"
+            >
+              detached
+            </span>
+          </Show>
+          <span class="docws-bubble-time">
+            {new Date(props.annotation.createdAt).toLocaleString()}
+          </span>
+          <span class="docws-spacer" />
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title="Resolve (r)"
+            onClick={() => void setDocumentAnnotationResolved(props.annotation.id, true)}
+          >
+            Resolve
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm"
+            title="Send this to an agent as a task on the passage"
+            onClick={() => props.onMakeTask(props.annotation)}
+          >
+            Make task
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-danger"
+            title="Delete (Del). Undo from the toolbar."
+            onClick={() => void deleteDocumentAnnotation(props.annotation.id)}
+          >
+            ×
+          </button>
+        </div>
+        <Show when={props.detached}>
+          <div class="docws-bubble-quote" title="Passage as it was when the note was written">
+            {props.annotation.anchor.quote.slice(0, 300)}
+          </div>
+        </Show>
+        <Show
+          when={!editing()}
+          fallback={
+            <textarea
+              class="docws-note"
+              value={draft()}
+              onInput={(e) => setDraft(e.currentTarget.value)}
+              onBlur={commitEdit}
+              onKeyDown={(e) => {
+                if (e.key === 'Escape') {
+                  e.stopPropagation();
+                  setEditing(false);
+                }
+                if (e.key === 'Enter' && !e.shiftKey) {
+                  e.preventDefault();
+                  commitEdit();
+                }
+              }}
+              ref={(el) => requestAnimationFrame(() => el.focus())}
+            />
+          }
+        >
+          <div class="docws-bubble-text" onDblClick={startEdit} title="Double-click to edit">
+            {props.annotation.text}
+          </div>
+        </Show>
+        <Show when={isQuestion()}>
+          <div class="docws-bubble-answer">
+            <Show when={status() === 'pending'}>
+              <div class="docws-bubble-pending">
+                <span class="docws-dot docws-dot-running" /> Answering…
+              </div>
+            </Show>
+            <Show when={status() === 'failed'}>
+              <div class="docws-error">
+                {props.annotation.answerError ?? 'The agent gave no answer.'}
+              </div>
+            </Show>
+            <Show when={props.annotation.answer}>
+              {(answer) => (
+                <>
+                  <div class="docws-bubble-answer-head">
+                    <span class="docws-badge">answer</span>
+                    <span>{answer().agentName}</span>
+                    <Show when={status() === 'answered' && props.annotation.answerError}>
+                      <span class="docws-warning">{props.annotation.answerError}</span>
+                    </Show>
+                  </div>
+                  {/* eslint-disable-next-line solid/no-innerhtml -- DOMPurify-sanitized markdown from the agent's answer */}
+                  <div class="plan-markdown docws-bubble-answer-body" innerHTML={answerHtml()} />
+                </>
+              )}
+            </Show>
+            <Show when={status() !== 'pending' && askAgents().length > 0}>
+              <div class="docws-run-actions">
+                <For each={askAgents()}>
+                  {(agent) => (
+                    <button
+                      type="button"
+                      class="docws-btn docws-btn-sm"
+                      title={`${props.annotation.answer ? 'Ask again' : 'Ask'} ${agent.name}`}
+                      onClick={() => void askDocumentAnnotation(props.annotation.id, agent)}
+                    >
+                      {props.annotation.answer ? 'Ask again' : 'Ask'}
+                      {askAgents().length > 1 || agent.id !== defaultAgent()?.id
+                        ? ` · ${agent.name}`
+                        : ''}
+                    </button>
+                  )}
+                </For>
+              </div>
+            </Show>
+          </div>
+        </Show>
+      </Show>
+    </div>
+  );
+}
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
index 23c6e85ae..4109c49a2 100644
--- a/src/documents/DocumentViewer.tsx
+++ b/src/documents/DocumentViewer.tsx
@@ -22,6 +22,8 @@ interface DocumentViewerProps {
   /** Unique key for mermaid ids. */
   renderKey: string;
   onContainer?: (el: HTMLDivElement) => void;
+  /** Rendered after the block with this index (annotation bubbles). */
+  afterBlock?: (index: number) => JSX.Element;
   children?: JSX.Element;
 }
 
@@ -158,6 +160,7 @@ export function DocumentViewer(props: DocumentViewerProps) {
               </Show>
               {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
               <div innerHTML={block.html} />
+              {props.afterBlock?.(i())}
             </div>
           );
         }}
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index be0f68c14..899378c7e 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -4,13 +4,20 @@ import { store } from '../store/core';
 import { getProject } from '../store/projects';
 import {
   closeDocumentWorkspace,
+  dismissUndo,
   documentStore,
   reviewableRuns,
+  setDocumentComposerDraft,
   setDocumentSelection,
   setDocumentView,
+  setShowResolvedAnnotations,
   openDocumentCompare,
+  undoDeleteDocumentAnnotation,
   type DocumentView,
 } from '../store/documents';
+import { relocateAnchor } from '../lib/annotation-anchor';
+import type { DocumentAnnotation } from '../ipc/types';
+import { AnnotationBubble } from './AnnotationBubble';
 import { EditProjectDialog } from '../components/EditProjectDialog';
 import type { Project } from '../store/types';
 import { CompareView } from './CompareView';
@@ -49,6 +56,65 @@ function DocumentPane() {
     return s && !s.wholeDocument ? { start: s.startBlock, end: s.endBlock } : null;
   });
 
+  // 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) {
+      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 openCount = () => documentStore.annotations.filter((a) => !a.resolved).length;
+  const resolvedCount = () => documentStore.annotations.filter((a) => a.resolved).length;
+
+  /** 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));
+      },
+    ),
+  );
+
   // Park the composer right under the last selected block.
   createEffect(
     on([selection, blocks.blocks], () => {
@@ -95,7 +161,29 @@ function DocumentPane() {
       <div class="docws-main">
         <div class="docws-toolbar">
           <span>{toolbarLabel()}</span>
+          <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={openCount() + 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>
           <button type="button" class="docws-btn docws-btn-sm" onClick={selectWholeDocument}>
             Whole document
           </button>
@@ -113,19 +201,40 @@ function DocumentPane() {
           <div class="docws-older-banner">The document file is missing from the checkout.</div>
         </Show>
         <div class="docws-doc" ref={docRef}>
+          <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"
+            afterBlock={(index) => (
+              <For each={placed().byBlock.get(index) ?? []}>
+                {(a) => <AnnotationBubble annotation={a} onMakeTask={makeTask} />}
+              </For>
+            )}
           >
             <Show when={selection()}>
               {(s) => (
                 <RunComposer
                   selection={s()}
+                  blocks={blocks.blocks()}
                   anchorTop={anchorTop()}
-                  onClose={() => setDocumentSelection(null)}
+                  onClose={() => {
+                    setDocumentSelection(null);
+                    setDocumentComposerDraft(null);
+                  }}
                 />
               )}
             </Show>
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
index 9a49c6da6..d31a4cb49 100644
--- a/src/documents/RunComposer.tsx
+++ b/src/documents/RunComposer.tsx
@@ -1,6 +1,7 @@
-import { For, Show, createMemo, createSignal, onMount } from 'solid-js';
+import { For, Show, createMemo, createSignal, onMount, untrack } from 'solid-js';
 import { store } from '../store/core';
 import {
+  addDocumentAnnotation,
   dispatchDocumentRun,
   documentMainAgentId,
   documentStore,
@@ -8,6 +9,8 @@ import {
   type DispatchSelection,
   type DocumentSelection,
 } from '../store/documents';
+import { createAnchor } from '../lib/annotation-anchor';
+import type { DocumentBlock } from '../lib/markdown-blocks';
 import { getProject } from '../store/projects';
 import { showNotification } from '../store/notification';
 import { errMessage } from '../lib/log';
@@ -19,11 +22,15 @@ import type { AgentDef } from '../ipc/types';
 
 interface RunComposerProps {
   selection: DocumentSelection;
+  /** Current blocks, for anchoring an annotation to the selection. */
+  blocks: DocumentBlock[];
   /** Offset inside the document container where the composer sits. */
   anchorTop: number;
   onClose: () => void;
 }
 
+type ComposerMode = 'task' | 'note' | 'question';
+
 const MAX_PER_AGENT = 3;
 
 /**
@@ -33,10 +40,14 @@ const MAX_PER_AGENT = 3;
  */
 export function RunComposer(props: RunComposerProps) {
   let textareaRef: HTMLTextAreaElement | undefined;
-  const [instruction, setInstruction] = createSignal('');
+  const draft = untrack(() => documentStore.composerDraft);
+  const [instruction, setInstruction] = createSignal(draft?.text ?? '');
+  const [mode, setMode] = createSignal<ComposerMode>('task');
+  const [saving, setSaving] = createSignal(false);
   const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
   const mainAgentId = () => documentMainAgentId(project());
   const [counts, setCounts] = createSignal<Record<string, number>>({ [mainAgentId()]: 1 });
+  const [askAgentId, setAskAgentId] = createSignal(mainAgentId());
 
   const agents = createMemo(() => store.availableAgents);
   const resumable = createMemo(() =>
@@ -54,6 +65,38 @@ export function RunComposer(props: RunComposerProps) {
     total() > 0 &&
     total() <= MAX_DOCUMENT_CANDIDATES &&
     !documentStore.dispatching;
+  const canAnnotate = () =>
+    instruction().trim().length > 0 && !props.selection.wholeDocument && !saving();
+  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 anchor = createAnchor(
+        props.blocks,
+        props.selection.startBlock,
+        props.selection.endBlock,
+        project()?.documentPath ?? '',
+        documentStore.snapshot?.headSha ?? null,
+      );
+      const saved = await addDocumentAnnotation(
+        mode() === 'question' ? 'question' : 'note',
+        instruction().trim(),
+        anchor,
+        mode() === 'question' ? askAgent() : undefined,
+      );
+      if (saved) props.onClose();
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  function submit() {
+    if (mode() === 'task') void run();
+    else void annotate();
+  }
 
   onMount(() => {
     requestAnimationFrame(() => textareaRef?.focus());
@@ -91,7 +134,7 @@ export function RunComposer(props: RunComposerProps) {
     }
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
-      void run();
+      submit();
     }
   }
 
@@ -113,9 +156,50 @@ export function RunComposer(props: RunComposerProps) {
       onMouseUp={(e) => e.stopPropagation()}
     >
       <div class="docws-composer-footer">
+        <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'}
+            onClick={() => setMode('task')}
+          >
+            Task
+          </button>
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'note'}
+            disabled={props.selection.wholeDocument}
+            title={
+              props.selection.wholeDocument
+                ? 'Notes attach to a passage, not the whole document'
+                : 'Write a note beside this passage'
+            }
+            onClick={() => setMode('note')}
+          >
+            Note
+          </button>
+          <button
+            type="button"
+            class="docws-tab"
+            role="tab"
+            aria-selected={mode() === 'question'}
+            disabled={props.selection.wholeDocument}
+            title={
+              props.selection.wholeDocument
+                ? 'Questions attach to a passage, not the whole document'
+                : 'Ask an agent about this passage; the answer goes into a bubble'
+            }
+            onClick={() => setMode('question')}
+          >
+            Ask
+          </button>
+        </span>
         <span>{scopeLabel()}</span>
         <span class="docws-spacer" />
-        <label>
+        <label style={{ display: mode() === 'task' ? undefined : 'none' }}>
           Main session{' '}
           <select
             class="docws-select"
@@ -140,11 +224,44 @@ export function RunComposer(props: RunComposerProps) {
       </Show>
       <textarea
         ref={textareaRef}
-        placeholder="What should change here? e.g. find a simpler architecture, challenge these assumptions…"
+        placeholder={
+          mode() === 'task'
+            ? 'What should change here? e.g. find a simpler architecture, challenge these assumptions…'
+            : 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)}
       />
-      <div class="docws-agent-row" role="group" aria-label="Agents">
+      <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>
+      <div
+        class="docws-agent-row"
+        role="group"
+        aria-label="Agents"
+        style={{ display: mode() === 'task' ? undefined : 'none' }}
+      >
         <For each={agents()}>
           {(agent) => {
             const support = documentAgentSupport(agent.id);
@@ -187,24 +304,45 @@ export function RunComposer(props: RunComposerProps) {
         </For>
       </div>
       <div class="docws-composer-footer">
+        <Show
+          when={mode() === 'task'}
+          fallback={<span>Saved beside the document, never into it</span>}
+        >
+          <span>
+            {total()} candidate{total() === 1 ? '' : 's'}
+            {total() > 1 ? ' · opens the compare view' : ''}
+            {total() > MAX_DOCUMENT_CANDIDATES ? ` · max ${MAX_DOCUMENT_CANDIDATES}` : ''}
+          </span>
+        </Show>
+        <span class="docws-spacer" />
         <span>
-          {total()} candidate{total() === 1 ? '' : 's'}
-          {total() > 1 ? ' · opens the compare view' : ''}
-          {total() > MAX_DOCUMENT_CANDIDATES ? ` · max ${MAX_DOCUMENT_CANDIDATES}` : ''}
+          Enter to {mode() === 'task' ? 'run' : mode() === 'note' ? 'save' : 'ask'} · Esc to close
         </span>
-        <span class="docws-spacer" />
-        <span>Enter to run · Esc to close</span>
         <button type="button" class="docws-btn docws-btn-sm" onClick={() => props.onClose()}>
           Cancel
         </button>
-        <button
-          type="button"
-          class="docws-btn docws-btn-sm docws-btn-primary"
-          disabled={!canRun()}
-          onClick={() => void run()}
+        <Show
+          when={mode() === 'task'}
+          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>
+          }
         >
-          {documentStore.dispatching ? 'Starting…' : 'Run'}
-        </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-primary"
+            disabled={!canRun()}
+            onClick={() => void run()}
+          >
+            {documentStore.dispatching ? 'Starting…' : 'Run'}
+          </button>
+        </Show>
       </div>
     </div>
   );
diff --git a/src/documents/documents.css b/src/documents/documents.css
index 9836ccd5e..86272c910 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -895,3 +895,164 @@
     animation: none;
   }
 }
+
+/* ── Annotations ── */
+
+.docws-bubble {
+  margin: 6px 0 10px 12px;
+  padding: 10px 12px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border);
+  background: var(--task-panel-bg);
+  font-size: 13px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  position: relative;
+  outline: none;
+}
+
+.docws-bubble::before {
+  content: '';
+  position: absolute;
+  left: -12px;
+  top: 12px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--review);
+}
+
+.docws-bubble.is-question::before {
+  background: var(--info);
+}
+
+.docws-bubble.is-detached {
+  border-style: dashed;
+}
+
+.docws-bubble:focus-visible {
+  border-color: var(--border-focus);
+}
+
+.docws-bubble.is-resolved {
+  padding: 0;
+  border-color: var(--border-subtle);
+  background: transparent;
+}
+
+.docws-bubble.is-resolved::before {
+  opacity: 0.4;
+}
+
+.docws-bubble-collapsed {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  background: transparent;
+  border: none;
+  color: var(--fg-subtle);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 4px 8px;
+  cursor: pointer;
+  text-align: left;
+}
+
+.docws-bubble-collapsed-text {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-decoration: line-through;
+}
+
+.docws-bubble-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+.docws-bubble-time {
+  font-family: var(--font-mono);
+}
+
+.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;
+}
+
+.docws-undo {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 2px 8px;
+  border-radius: var(--radius-sm);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  color: var(--fg);
+}
+
+.docws-detached-section {
+  margin: 0 0 18px;
+  padding: 10px 12px;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius-md);
+}
+
+.docws-mode-tabs {
+  display: inline-flex;
+  gap: 2px;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 2px;
+}
+
+.docws-mode-tabs .docws-tab {
+  padding: 3px 10px;
+  font-size: 12px;
+}
diff --git a/src/ipc/types.ts b/src/ipc/types.ts
index 6e281df90..43c60a626 100644
--- a/src/ipc/types.ts
+++ b/src/ipc/types.ts
@@ -7,6 +7,10 @@ export type {
   CoverageMetricSummary,
   CoverageSummary,
   CreateTaskResult,
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationKind,
   DocumentCandidateRecord,
   DocumentCandidateSpec,
   DocumentCandidateStatus,
diff --git a/src/lib/annotation-anchor.test.ts b/src/lib/annotation-anchor.test.ts
new file mode 100644
index 000000000..1c9f3a04d
--- /dev/null
+++ b/src/lib/annotation-anchor.test.ts
@@ -0,0 +1,94 @@
+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);
+  });
+});
diff --git a/src/lib/annotation-anchor.ts b/src/lib/annotation-anchor.ts
new file mode 100644
index 000000000..f243d39a5
--- /dev/null
+++ b/src/lib/annotation-anchor.ts
@@ -0,0 +1,92 @@
+import type { DocumentAnchor } from '../ipc/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;
+}
+
+/**
+ * Finds an anchor in the current blocks. Matches the quoted blocks by text;
+ * 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;
+  const wanted = anchor.quote
+    .split(/\n\s*\n/)
+    .map(normalize)
+    .filter((t) => t.length > 0);
+  if (wanted.length === 0) return null;
+  const keys = blocks.map((b) => normalize(b.raw));
+
+  const candidates: AnchorLocation[] = [];
+  for (let i = 0; i + wanted.length <= blocks.length; i++) {
+    let ok = true;
+    for (let k = 0; k < wanted.length; k++) {
+      if (keys[i + k] !== wanted[k]) {
+        ok = false;
+        break;
+      }
+    }
+    if (!ok) continue;
+    const end = i + wanted.length - 1;
+    const exact =
+      blocks[i].startLine === anchor.startLine && blocks[end].endLine === anchor.endLine;
+    candidates.push({ startBlock: i, endBlock: end, exact });
+  }
+  if (candidates.length === 0) return null;
+  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/store/documents.ts b/src/store/documents.ts
index d532c0c32..40e0cd5f9 100644
--- a/src/store/documents.ts
+++ b/src/store/documents.ts
@@ -10,6 +10,10 @@ import { invoke } from '../lib/ipc';
 import { errMessage } from '../lib/log';
 import type {
   AgentDef,
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationKind,
   DocumentCandidateRecord,
   DocumentCandidateSpec,
   DocumentRunEvent,
@@ -40,8 +44,19 @@ export interface DocumentSelection {
   wholeDocument: boolean;
 }
 
+/** What the composer opens with when a bubble is turned into a task. */
+export interface ComposerDraft {
+  text: string;
+  annotationId?: string;
+}
+
 interface DocumentWorkspaceState {
   projectId: string | null;
+  annotations: DocumentAnnotation[];
+  /** Last deleted bubble, kept for a single-step undo. */
+  lastDeleted: DocumentAnnotation | null;
+  showResolved: boolean;
+  composerDraft: ComposerDraft | null;
   snapshot: DocumentSnapshot | null;
   loading: boolean;
   error: string | null;
@@ -59,6 +74,10 @@ const MAX_LOG_LINES = 400;
 
 const [docStore, setDocStore] = createStore<DocumentWorkspaceState>({
   projectId: null,
+  annotations: [],
+  lastDeleted: null,
+  showResolved: false,
+  composerDraft: null,
   snapshot: null,
   loading: false,
   error: null,
@@ -151,6 +170,9 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
     view: 'document',
     compareRunId: null,
     selection: null,
+    annotations: [],
+    lastDeleted: null,
+    composerDraft: null,
   });
   setStore('activeDocumentProjectId', projectId);
   // Start watching before the first await so a quick close can stop it.
@@ -163,7 +185,7 @@ export async function openDocumentWorkspace(projectId: string): Promise<void> {
       if (stillOpen(projectId)) setDocStore('error', errMessage(err));
     });
   });
-  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns()]);
+  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns(), loadDocumentAnnotations()]);
   if (stillOpen(projectId)) setDocStore('loading', false);
 }
 
@@ -172,10 +194,20 @@ export function closeDocumentWorkspace(): void {
   if (projectId) {
     void invoke(IPC.StopDocumentWatcher, { key: watcherKey(projectId) }).catch(() => undefined);
   }
-  setDocStore({ projectId: null, selection: null, view: 'document', compareRunId: null });
+  setDocStore({
+    projectId: null,
+    selection: null,
+    view: 'document',
+    compareRunId: null,
+    composerDraft: null,
+  });
   setStore('activeDocumentProjectId', null);
 }
 
+export function setDocumentComposerDraft(draft: ComposerDraft | null): void {
+  setDocStore('composerDraft', draft);
+}
+
 export function setDocumentView(view: DocumentView): void {
   setDocStore('view', view);
 }
@@ -290,7 +322,9 @@ export async function dispatchDocumentRun(
       candidates,
     });
     upsertRun(run);
-    setDocStore('selection', null);
+    const draft = docStore.composerDraft;
+    setDocStore({ selection: null, composerDraft: null });
+    if (draft?.annotationId) void linkAnnotationToRun(draft.annotationId, run.id);
     void refreshDocumentSnapshot();
     return run;
   } finally {
@@ -448,6 +482,161 @@ export async function revertDocumentCommit(sha: string): Promise<boolean> {
   }
 }
 
+// --- Annotations ----------------------------------------------------------
+
+export async function loadDocumentAnnotations(): Promise<void> {
+  const project = activeProject();
+  if (!project) return;
+  try {
+    const annotations = await invoke<DocumentAnnotation[]>(IPC.ListDocumentAnnotations, {
+      projectRoot: project.path,
+    });
+    if (stillOpen(project.id)) setDocStore('annotations', annotations);
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+function putAnnotation(annotation: DocumentAnnotation): void {
+  setDocStore(
+    produce((s) => {
+      const idx = s.annotations.findIndex((a) => a.id === annotation.id);
+      if (idx >= 0) s.annotations[idx] = annotation;
+      else s.annotations.push(annotation);
+    }),
+  );
+}
+
+async function persistAnnotation(annotation: DocumentAnnotation): Promise<DocumentAnnotation> {
+  const project = requireProject();
+  const saved = await invoke<DocumentAnnotation>(IPC.SaveDocumentAnnotation, {
+    projectRoot: project.path,
+    annotation,
+  });
+  putAnnotation(saved);
+  return saved;
+}
+
+/** Creates a note or a question on the anchored passage. Questions are asked right away. */
+export async function addDocumentAnnotation(
+  kind: DocumentAnnotationKind,
+  text: string,
+  anchor: DocumentAnchor,
+  askWith?: AgentDef,
+): Promise<DocumentAnnotation | null> {
+  const now = new Date().toISOString();
+  try {
+    const saved = await persistAnnotation({
+      id: crypto.randomUUID(),
+      kind,
+      anchor,
+      text,
+      createdAt: now,
+      updatedAt: now,
+      resolved: false,
+    });
+    if (kind === 'question' && askWith) await askDocumentAnnotation(saved.id, askWith);
+    return saved;
+  } catch (err) {
+    showNotification(errMessage(err));
+    return null;
+  }
+}
+
+export async function askDocumentAnnotation(annotationId: string, agent: AgentDef): Promise<void> {
+  const project = requireProject();
+  try {
+    const pending = await invoke<DocumentAnnotation>(IPC.AskDocumentAnnotation, {
+      projectRoot: project.path,
+      documentPath: project.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;
@@ -464,6 +653,15 @@ 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;
@@ -471,12 +669,15 @@ export function initDocumentListeners(): () => void {
       if (!docStore.projectId || p.key !== watcherKey(docStore.projectId)) return;
       const previous = docStore.snapshot;
       setDocStore('snapshot', p.snapshot);
-      // The passage under a selection may be gone after an external edit.
+      // The passage under a selection may be gone after an external edit, and a
+      // commit or pull may have brought annotations along.
       if (previous && previous.content !== p.snapshot.content) setDocStore('selection', null);
+      if (previous && previous.headSha !== p.snapshot.headSha) void loadDocumentAnnotations();
     });
   });
   return () => {
     offRun();
+    offAnnotation();
     offChanged();
   };
 }

From e94fd2a84799d1e5f23209bc6a4b73590f68f86e Mon Sep 17 00:00:00 2001
From: Johannes Millan <johannes.millan@gmail.com>
Date: Fri, 4 Sep 2026 09:42:26 +0200
Subject: [PATCH 04/12] refactor(documents): give document workspaces their own
 folders and setup

Move the feature out of electron/ipc, electron/shared, src/lib and src/store
into electron/documents and src/documents, and let it prepare its own project:
creating one now runs whatever is missing (git init, the starter document, the
first commit) instead of asking the user to do it first.

Also from review: app-written commits take an explicit path list via
`commit --only`, so nothing the user staged rides along; a candidate that
settles while dispatch is still spawning is no longer resurrected as running;
Gemini answers annotation questions in `plan`, its read-only mode.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 .dependency-cruiser.cjs                       |   2 +
 docs/document-workspaces.md                   |  15 +-
 .../agents.test.ts}                           |   6 +-
 .../agents.ts}                                |   6 +-
 .../annotations.test.ts}                      |   4 +-
 .../annotations.ts}                           |  14 +-
 electron/documents/git.ts                     |  24 +++
 .../prompt.test.ts}                           |   2 +-
 .../prompt.ts}                                |   2 +-
 .../runs.integration.test.ts}                 | 161 +++++++-----------
 .../runs.real-claude.integration.test.ts}     |   8 +-
 .../runs.test.ts}                             |   2 +-
 .../{ipc/documents.ts => documents/runs.ts}   | 161 ++++++++++--------
 electron/documents/setup.test.ts              | 139 +++++++++++++++
 electron/documents/setup.ts                   | 145 ++++++++++++++++
 .../shared.ts}                                |   0
 electron/ipc/channel-manifest.json            |   3 +-
 electron/ipc/register.ts                      |  14 +-
 electron/ipc/shared-types.ts                  |  22 +++
 electron/main.ts                              |   4 +-
 electron/preload.cjs                          |   3 +-
 src/App.tsx                                   |   2 +-
 src/components/Sidebar.tsx                    |   2 +-
 src/documents/AnnotationBubble.tsx            |   4 +-
 src/documents/CompareView.tsx                 |   4 +-
 src/documents/DocumentViewer.tsx              |   6 +-
 src/documents/DocumentWorkspaceOverlay.tsx    |   4 +-
 src/documents/HistoryView.tsx                 |   2 +-
 src/documents/NewDocumentProjectDialog.tsx    | 135 +++++++++++----
 src/documents/RunComposer.tsx                 |  20 ++-
 src/documents/RunsRail.tsx                    |   2 +-
 .../annotation-anchor.test.ts                 |   0
 src/{lib => documents}/annotation-anchor.ts   |   0
 src/documents/documents.css                   |   7 +
 .../markdown-blocks.test.ts                   |   0
 src/{lib => documents}/markdown-blocks.ts     |   2 +-
 .../documents.ts => documents/store.ts}       |  10 +-
 src/documents/use-blocks.ts                   |   2 +-
 src/ipc/types.ts                              |   3 +
 src/store/remoteTaskHandler.ts                |   3 +-
 40 files changed, 671 insertions(+), 274 deletions(-)
 rename electron/{ipc/document-agents.test.ts => documents/agents.test.ts} (98%)
 rename electron/{ipc/document-agents.ts => documents/agents.ts} (97%)
 rename electron/{ipc/document-annotations.test.ts => documents/annotations.test.ts} (99%)
 rename electron/{ipc/document-annotations.ts => documents/annotations.ts} (97%)
 create mode 100644 electron/documents/git.ts
 rename electron/{ipc/document-prompt.test.ts => documents/prompt.test.ts} (97%)
 rename electron/{ipc/document-prompt.ts => documents/prompt.ts} (98%)
 rename electron/{ipc/documents.integration.test.ts => documents/runs.integration.test.ts} (83%)
 rename electron/{ipc/documents.real-claude.integration.test.ts => documents/runs.real-claude.integration.test.ts} (97%)
 rename electron/{ipc/documents.test.ts => documents/runs.test.ts} (99%)
 rename electron/{ipc/documents.ts => documents/runs.ts} (91%)
 create mode 100644 electron/documents/setup.test.ts
 create mode 100644 electron/documents/setup.ts
 rename electron/{shared/document-agents.ts => documents/shared.ts} (100%)
 rename src/{lib => documents}/annotation-anchor.test.ts (100%)
 rename src/{lib => documents}/annotation-anchor.ts (100%)
 rename src/{lib => documents}/markdown-blocks.test.ts (100%)
 rename src/{lib => documents}/markdown-blocks.ts (99%)
 rename src/{store/documents.ts => documents/store.ts} (98%)

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/docs/document-workspaces.md b/docs/document-workspaces.md
index 5c7800770..9aea091ac 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -24,8 +24,9 @@ the document.
 ### Using it
 
 1. Enable _Document workspaces_ under Settings → Experimental.
-2. Click **+** next to Projects and choose **Document project**. Pick a Git repository and
-   one tracked Markdown file in it.
+2. Click **+** next to Projects and choose **Document project**. Pick any folder and name
+   the document. Neither has to exist yet: the dialog says what it will do — `git init`,
+   create the file, make the first commit — and does it when you confirm.
 3. The workspace opens full-window with three tabs: **Document**, **Compare**, **History**.
 4. In the document, select text, click a block, or press **§** next to a heading to select
    the section. A composer opens under the selection: type an instruction, pick agents and
@@ -54,7 +55,8 @@ the document.
   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`. Process exit means the
+  `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.
@@ -96,6 +98,13 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   as **detached** rather than attaching it 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 —
+  `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.
+- **It lives in two folders.** `electron/documents/` (runs, agents, prompts, annotations,
+  setup) and `src/documents/` (the workspace UI with its store and markdown helpers). The
+  one file the renderer imports across that boundary is `electron/documents/shared.ts`.
 
 ### Not in this slice
 
diff --git a/electron/ipc/document-agents.test.ts b/electron/documents/agents.test.ts
similarity index 98%
rename from electron/ipc/document-agents.test.ts
rename to electron/documents/agents.test.ts
index 7eccd72dd..500f7e96d 100644
--- a/electron/ipc/document-agents.test.ts
+++ b/electron/documents/agents.test.ts
@@ -1,9 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import {
-  buildHeadlessLaunch,
-  createHeadlessParser,
-  CLAUDE_DOCUMENT_TOOLS,
-} from './document-agents.js';
+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', () => {
diff --git a/electron/ipc/document-agents.ts b/electron/documents/agents.ts
similarity index 97%
rename from electron/ipc/document-agents.ts
rename to electron/documents/agents.ts
index b9fab2fde..11bed2510 100644
--- a/electron/ipc/document-agents.ts
+++ b/electron/documents/agents.ts
@@ -3,7 +3,7 @@
  * 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/document-agents.js';
+import { documentAgentSupport } from './shared.js';
 
 export interface HeadlessLaunch {
   command: string;
@@ -87,7 +87,9 @@ export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch
           '--output-format',
           'json',
           '--approval-mode',
-          opts.readOnly ? 'default' : 'auto_edit',
+          // `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',
         ],
       };
     default:
diff --git a/electron/ipc/document-annotations.test.ts b/electron/documents/annotations.test.ts
similarity index 99%
rename from electron/ipc/document-annotations.test.ts
rename to electron/documents/annotations.test.ts
index 278f0c68e..19076c212 100644
--- a/electron/ipc/document-annotations.test.ts
+++ b/electron/documents/annotations.test.ts
@@ -10,8 +10,8 @@ import {
   readAnnotations,
   saveAnnotation,
   validateAnnotationInput,
-} from './document-annotations.js';
-import type { DocumentAnnotation, DocumentAnnotationEvent } from './shared-types.js';
+} from './annotations.js';
+import type { DocumentAnnotation, DocumentAnnotationEvent } from '../ipc/shared-types.js';
 
 const anchor = {
   path: 'docs/spec.md',
diff --git a/electron/ipc/document-annotations.ts b/electron/documents/annotations.ts
similarity index 97%
rename from electron/ipc/document-annotations.ts
rename to electron/documents/annotations.ts
index 92efefbc1..5d0357d13 100644
--- a/electron/ipc/document-annotations.ts
+++ b/electron/documents/annotations.ts
@@ -8,20 +8,20 @@ import fs from 'fs';
 import path from 'path';
 import { randomUUID } from 'crypto';
 import type { BrowserWindow } from 'electron';
-import { IPC } from './channels.js';
+import { IPC } from '../ipc/channels.js';
 import { errMessage } from '../log.js';
 import { atomicWriteFileSync } from '../mcp/atomic.js';
-import { buildPtySpawnEnv, validateCommand } from './pty.js';
-import { loadEnvFile } from './env-file.js';
-import { buildHeadlessLaunch, createHeadlessParser } from './document-agents.js';
-import { documentAgentSupport } from '../shared/document-agents.js';
-import { validateDocumentPath, validateSha } from './documents.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { documentAgentSupport } from './shared.js';
+import { validateDocumentPath, validateSha } from './runs.js';
 import type {
   DocumentAnchor,
   DocumentAnnotation,
   DocumentAnnotationEvent,
   DocumentAnnotationsFile,
-} from './shared-types.js';
+} from '../ipc/shared-types.js';
 
 export const ANNOTATIONS_REL_PATH = path.posix.join('.parallel', 'annotations.json');
 const MAX_TEXT_CHARS = 20_000;
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/ipc/document-prompt.test.ts b/electron/documents/prompt.test.ts
similarity index 97%
rename from electron/ipc/document-prompt.test.ts
rename to electron/documents/prompt.test.ts
index f192f81d0..7a686f913 100644
--- a/electron/ipc/document-prompt.test.ts
+++ b/electron/documents/prompt.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { buildDocumentPrompt, parseDocumentRationale } from './document-prompt.js';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
 
 const scope = {
   path: 'docs/spec.md',
diff --git a/electron/ipc/document-prompt.ts b/electron/documents/prompt.ts
similarity index 98%
rename from electron/ipc/document-prompt.ts
rename to electron/documents/prompt.ts
index bd0d997db..932ee5d6c 100644
--- a/electron/ipc/document-prompt.ts
+++ b/electron/documents/prompt.ts
@@ -1,4 +1,4 @@
-import type { DocumentRationale, DocumentScope } from './shared-types.js';
+import type { DocumentRationale, DocumentScope } from '../ipc/shared-types.js';
 
 /** Largest diff (in characters) handed to a resumed main session. */
 const MAX_CATCH_UP_DIFF_CHARS = 20_000;
diff --git a/electron/ipc/documents.integration.test.ts b/electron/documents/runs.integration.test.ts
similarity index 83%
rename from electron/ipc/documents.integration.test.ts
rename to electron/documents/runs.integration.test.ts
index 2a8de4a12..bace1516f 100644
--- a/electron/ipc/documents.integration.test.ts
+++ b/electron/documents/runs.integration.test.ts
@@ -12,12 +12,12 @@ import {
   getDocumentAtCommit,
   getDocumentDiff,
   getDocumentHistory,
-  listDocumentFiles,
   listDocumentRuns,
   readDocumentSnapshot,
   rejectDocumentRun,
-} from './documents.js';
-import type { DocumentRunEvent, DocumentRunRecord } from './shared-types.js';
+} from './runs.js';
+import { inspectDocumentFolder } from './setup.js';
+import type { DocumentRunEvent, DocumentRunRecord } from '../ipc/shared-types.js';
 
 /**
  * Exercises the whole proposal lifecycle against a real temporary repository
@@ -104,8 +104,15 @@ afterAll(() => {
 });
 
 describe('document workspace lifecycle', () => {
-  it('lists tracked markdown files', async () => {
-    expect(await listDocumentFiles(root)).toEqual(['README.md', 'docs/spec.md']);
+  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('reads a snapshot', async () => {
@@ -277,6 +284,52 @@ describe('document workspace lifecycle', () => {
     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 });
+  });
+
   it('rejects candidate specs that would smuggle flags into git or the CLI', async () => {
     const base = {
       projectRoot: root,
@@ -355,101 +408,9 @@ describe('document workspace lifecycle', () => {
     expect(history.map((h) => h.subject)).not.toContain('Reject proposals');
   });
 
-  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);
-  });
-
-  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 otherwise', async () => {
+  // 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',
diff --git a/electron/ipc/documents.real-claude.integration.test.ts b/electron/documents/runs.real-claude.integration.test.ts
similarity index 97%
rename from electron/ipc/documents.real-claude.integration.test.ts
rename to electron/documents/runs.real-claude.integration.test.ts
index de9df2230..1727ff454 100644
--- a/electron/ipc/documents.real-claude.integration.test.ts
+++ b/electron/documents/runs.real-claude.integration.test.ts
@@ -4,19 +4,19 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import type { BrowserWindow } from 'electron';
-import { acceptDocumentCandidate, dispatchDocumentRun } from './documents.js';
-import { askAnnotation, readAnnotations, saveAnnotation } from './document-annotations.js';
+import { acceptDocumentCandidate, dispatchDocumentRun } from './runs.js';
+import { askAnnotation, readAnnotations, saveAnnotation } from './annotations.js';
 import type {
   DocumentAnnotation,
   DocumentAnnotationEvent,
   DocumentRunEvent,
   DocumentRunRecord,
-} from './shared-types.js';
+} from '../ipc/shared-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/ipc/documents.real-claude.integration.test.ts
+ *   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';
 
diff --git a/electron/ipc/documents.test.ts b/electron/documents/runs.test.ts
similarity index 99%
rename from electron/ipc/documents.test.ts
rename to electron/documents/runs.test.ts
index 3d489977e..a1085d922 100644
--- a/electron/ipc/documents.test.ts
+++ b/electron/documents/runs.test.ts
@@ -5,7 +5,7 @@ import {
   sanitizeRunRecord,
   validateDocumentPath,
   validateSha,
-} from './documents.js';
+} from './runs.js';
 
 describe('validateDocumentPath', () => {
   it('accepts a relative markdown path and normalizes ./', () => {
diff --git a/electron/ipc/documents.ts b/electron/documents/runs.ts
similarity index 91%
rename from electron/ipc/documents.ts
rename to electron/documents/runs.ts
index 628996455..fc1ee00af 100644
--- a/electron/ipc/documents.ts
+++ b/electron/documents/runs.ts
@@ -5,21 +5,21 @@
  * Git holds the content; `.parallel/runs/` holds the run records. Nothing in
  * here changes the canonical document except `acceptDocumentCandidate`.
  */
-import { execFile, spawn, type ChildProcess } from 'child_process';
-import { promisify } from 'util';
+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 './channels.js';
-import { debug as logDebug, errMessage } from '../log.js';
+import { IPC } from '../ipc/channels.js';
+import { errMessage } from '../log.js';
 import { atomicWriteFileSync } from '../mcp/atomic.js';
-import { buildPtySpawnEnv, validateCommand } from './pty.js';
-import { loadEnvFile } from './env-file.js';
-import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from './git.js';
-import { buildHeadlessLaunch, createHeadlessParser } from './document-agents.js';
-import { buildDocumentPrompt, parseDocumentRationale } from './document-prompt.js';
-import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from '../shared/document-agents.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from '../ipc/git.js';
+import { git, gitOk } from './git.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from './shared.js';
 import type {
   DocumentCandidateRecord,
   DocumentCandidateSpec,
@@ -28,10 +28,8 @@ import type {
   DocumentRunRecord,
   DocumentScope,
   DocumentSnapshot,
-} from './shared-types.js';
+} from '../ipc/shared-types.js';
 
-const execFileAsync = promisify(execFile);
-const MAX_BUFFER = 20 * 1024 * 1024;
 /** 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. */
@@ -52,21 +50,6 @@ const SETTLE_WAIT_MS = 8_000;
 /** Files the app seeds into a worktree; never the agent's doing. */
 const SEEDED_PREFIXES = ['.claude/'];
 
-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;
-}
-
-async function gitOk(cwd: string, args: string[]): Promise<boolean> {
-  try {
-    await git(cwd, args);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 // --- Validation -----------------------------------------------------------
 
 /** A document path is repo-relative and stays inside the project's content. */
@@ -502,26 +485,55 @@ function runOwningBranch(projectRoot: string, branch: string): DocumentRunRecord
 
 // --- 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]);
-  await stageAnnotations(projectRoot);
-  if (!(await gitOk(projectRoot, ['diff', '--cached', '--quiet']))) {
-    await git(projectRoot, ['commit', '-q', '-m', 'Manual edits']);
-  }
+  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;
 }
 
-/** Annotations are committed alongside content and metadata, never on their own. */
-async function stageAnnotations(projectRoot: string): Promise<void> {
-  if (!fs.existsSync(path.join(projectRoot, ANNOTATIONS_FILE))) return;
-  await gitOk(projectRoot, ['add', '-f', '--', ANNOTATIONS_FILE]);
+/**
+ * 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 ------------------------------------------------------------
@@ -630,8 +642,9 @@ function parseChangedPaths(porcelainZ: string): string[] {
   const out: string[] = [];
   for (const entry of porcelainZ.split('\0')) {
     if (!entry.trim()) continue;
-    // "XY path" (renames use a second NUL entry; the first path after the
-    // status is what we act on).
+    // "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);
   }
@@ -982,15 +995,24 @@ export async function dispatchDocumentRun(
       }
     }
 
-    const active = activeRuns.get(runId);
-    if (active && active.candidates.size === 0) {
-      activeRuns.delete(runId);
-      run.status = 'finished';
-      run.finishedAt = nowIso();
+    // A candidate can settle while this loop awaits a catch-up diff, and its
+    // settle path writes the authoritative record. Merge the candidates only
+    // this function knows about — the ones whose spawn threw — instead of
+    // writing the in-memory copy over it, which would resurrect `running`.
+    if (activeRuns.get(runId)?.candidates.size === 0) activeRuns.delete(runId);
+    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;
     }
-    writeRunRecord(projectRoot, run);
-    sendEvent(win, { type: 'run', projectRoot, run });
-    return run;
+    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;
   });
 }
 
@@ -1081,8 +1103,11 @@ export async function acceptDocumentCandidate(
     writeRunRecord(projectRoot, run);
     try {
       await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
-      await stageAnnotations(projectRoot);
-      await git(projectRoot, ['commit', '-q', '-m', integrationMessage(run, candidate)]);
+      // The proposal commit was verified to hold the document alone, so the
+      // squash brought in exactly that path.
+      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';
@@ -1122,13 +1147,13 @@ export async function rejectDocumentRun(
     // touching content: a metadata-only commit the history view filters out.
     try {
       await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
-      await stageAnnotations(projectRoot);
-      await git(projectRoot, [
-        'commit',
-        '-q',
-        '-m',
+      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);
     }
@@ -1256,19 +1281,18 @@ export async function revertDocumentCommit(projectRoot: string, sha: string): Pr
   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']);
-      const staged = !(await gitOk(projectRoot, ['diff', '--cached', '--quiet']));
-      if (!staged) throw new Error('Nothing to revert outside run metadata.');
-      await git(projectRoot, [
-        'commit',
-        '-q',
-        '-m',
-        `Revert "${subject}"\n\nParallel-Revert: ${sha}`,
-      ]);
+      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']);
@@ -1278,19 +1302,6 @@ export async function revertDocumentCommit(projectRoot: string, sha: string): Pr
   });
 }
 
-/** Markdown files tracked in the repository, for the document picker. */
-export async function listDocumentFiles(projectRoot: string): Promise<string[]> {
-  try {
-    const out = await git(projectRoot, ['ls-files', '-z', '--', '*.md', '*.markdown']);
-    return out
-      .split('\0')
-      .filter((p) => p && !p.startsWith('.parallel/') && !p.startsWith('.worktrees/'))
-      .slice(0, 1000);
-  } catch {
-    return [];
-  }
-}
-
 /** 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..1e81fe705
--- /dev/null
+++ b/electron/documents/setup.test.ts
@@ -0,0 +1,139 @@
+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 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, 'ignore.txt'), 'x');
+
+    expect(await inspectDocumentFolder(dir)).toEqual({
+      isRepo: false,
+      enclosingRepo: null,
+      hasCommits: false,
+      files: [{ path: 'notes/plan.md', 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({
+      isRepo: true,
+      enclosingRepo: null,
+      hasCommits: true,
+      files: [
+        { path: 'committed.md', committed: true },
+        { path: 'loose.md', committed: false },
+      ],
+    });
+  });
+
+  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 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('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..6a429d7be
--- /dev/null
+++ b/electron/documents/setup.ts
@@ -0,0 +1,145 @@
+/**
+ * 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 '../ipc/shared-types.js';
+
+const MAX_FILES = 1000;
+/** How far the pre-repository scan walks before it stops looking. */
+const SCAN_DEPTH = 4;
+const MARKDOWN_RE = /\.(md|markdown)$/i;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.parallel', '.worktrees']);
+
+function isMarkdown(file: string): boolean {
+  return MARKDOWN_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;
+  }
+}
+
+/** Markdown in a folder that is not a repository yet, so the picker still has something to show. */
+function scanMarkdown(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() && isMarkdown(entry.name)) found.push(child);
+    }
+  };
+  walk(folder, '', 0);
+  return found.sort();
+}
+
+const MARKDOWN_PATHSPEC = ['--', '*.md', '*.markdown'];
+
+async function listMarkdown(folder: string, lsFilesArgs: string[]): Promise<string[]> {
+  const out = await git(folder, ['ls-files', '-z', ...lsFilesArgs, ...MARKDOWN_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 Markdown is listed too: `prepareDocumentProject`
+ * commits whatever the user picks, so there is no reason to hide it.
+ */
+export async function inspectDocumentFolder(folder: string): Promise<DocumentFolderInfo> {
+  const toplevel = await repoToplevel(folder);
+  const isRepo = toplevel !== null && toplevel === fs.realpathSync(folder);
+  if (!isRepo) {
+    const files = scanMarkdown(folder).map(
+      (p): DocumentFileInfo => ({ path: p, committed: false }),
+    );
+    return { isRepo: false, enclosingRepo: toplevel, hasCommits: false, files };
+  }
+  const hasCommits = await gitOk(folder, ['rev-parse', '--verify', 'HEAD']);
+  const tracked = new Set(await listMarkdown(folder, []));
+  const untracked = await listMarkdown(folder, ['--others', '--exclude-standard']);
+  const files = [...tracked, ...untracked]
+    .sort()
+    .slice(0, MAX_FILES)
+    .map((p): DocumentFileInfo => ({ path: p, committed: hasCommits && tracked.has(p) }));
+  return { isRepo: true, enclosingRepo: null, hasCommits, files };
+}
+
+/** `notes.md` → `Notes`; the heading a brand-new document opens with. */
+function starterContent(documentPath: string): string {
+  const title = path.basename(documentPath).replace(MARKDOWN_RE, '').replace(/[-_]+/g, ' ').trim();
+  return `# ${title.charAt(0).toUpperCase()}${title.slice(1)}\n\n`;
+}
+
+function withMarkdownExtension(documentPath: string): string {
+  return isMarkdown(documentPath) ? documentPath : `${documentPath}.md`;
+}
+
+/**
+ * Brings `folder` up to what the workspace assumes: a repository of its own,
+ * with `requestedPath` committed. Every step is skipped when it is already
+ * true, so re-running this on a ready project does nothing.
+ */
+export async function prepareDocumentProject(
+  folder: string,
+  requestedPath: string,
+): Promise<DocumentProjectSetup> {
+  if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory())
+    throw new Error('Pick a folder that exists.');
+  const documentPath = withMarkdownExtension(validateDocumentPath(requestedPath));
+  const actions: string[] = [];
+
+  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));
+    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/shared/document-agents.ts b/electron/documents/shared.ts
similarity index 100%
rename from electron/shared/document-agents.ts
rename to electron/documents/shared.ts
diff --git a/electron/ipc/channel-manifest.json b/electron/ipc/channel-manifest.json
index 70beef0ae..1e4f3d469 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -161,7 +161,8 @@
   "GetDocumentAtCommit": "get_document_at_commit",
   "GetDocumentDiff": "get_document_diff",
   "RevertDocumentCommit": "revert_document_commit",
-  "ListDocumentFiles": "list_document_files",
+  "InspectDocumentFolder": "inspect_document_folder",
+  "PrepareDocumentProject": "prepare_document_project",
   "DocumentChanged": "document_changed",
   "DocumentRunEvent": "document_run_event",
   "ListDocumentAnnotations": "list_document_annotations",
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index b9959128c..5b4152d7a 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -101,7 +101,6 @@ import {
   getDocumentAtCommit,
   getDocumentDiff,
   getDocumentHistory,
-  listDocumentFiles,
   listDocumentRuns,
   readDocumentSnapshot,
   rejectDocumentRun,
@@ -111,13 +110,14 @@ import {
   stopDocumentWatcher,
   validateDocumentPath,
   validateSha,
-} from './documents.js';
+} from '../documents/runs.js';
+import { inspectDocumentFolder, prepareDocumentProject } from '../documents/setup.js';
 import {
   askAnnotation,
   deleteAnnotation,
   readAnnotations,
   saveAnnotation,
-} from './document-annotations.js';
+} from '../documents/annotations.js';
 import { setMinimaxApiKey } from './ask-code-minimax.js';
 import { getSystemMonospaceFonts } from './system-fonts.js';
 import { fetchClaudeUsage } from './claude-usage.js';
@@ -1005,8 +1005,12 @@ export function registerAllHandlers(win: BrowserWindow): void {
     stopDocumentWatcher(args.key);
   });
 
-  ipcMain.handle(IPC.ListDocumentFiles, (_e, args) => {
-    return listDocumentFiles(projectRootArg(args));
+  ipcMain.handle(IPC.InspectDocumentFolder, (_e, args) => {
+    return inspectDocumentFolder(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.PrepareDocumentProject, (_e, args) => {
+    return prepareDocumentProject(projectRootArg(args), args.documentPath);
   });
 
   ipcMain.handle(IPC.ListDocumentRuns, (_e, args) => {
diff --git a/electron/ipc/shared-types.ts b/electron/ipc/shared-types.ts
index 71f218425..5cd2913ea 100644
--- a/electron/ipc/shared-types.ts
+++ b/electron/ipc/shared-types.ts
@@ -224,6 +224,28 @@ export type UsageResult =
 
 // --- Document workspaces ---
 
+/** 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 {
+  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;
diff --git a/electron/main.ts b/electron/main.ts
index 5b3a25c6c..d8dcd74ec 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -10,8 +10,8 @@ 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 { stopAllDocumentRuns, stopAllDocumentWatchers } from './ipc/documents.js';
-import { stopAllAsks } from './ipc/document-annotations.js';
+import { stopAllDocumentRuns, stopAllDocumentWatchers } from './documents/runs.js';
+import { stopAllAsks } from './documents/annotations.js';
 import { stopAllStepsWatchers } from './ipc/steps.js';
 import { verificationRunner } from './ipc/verify.js';
 import { IPC } from './ipc/channels.js';
diff --git a/electron/preload.cjs b/electron/preload.cjs
index 67a121166..3bfdff5f1 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -165,7 +165,8 @@ const ALLOWED_CHANNELS = new Set([
   'get_document_at_commit',
   'get_document_diff',
   'revert_document_commit',
-  'list_document_files',
+  'inspect_document_folder',
+  'prepare_document_project',
   'document_changed',
   'document_run_event',
   'list_document_annotations',
diff --git a/src/App.tsx b/src/App.tsx
index be275d185..382a181b7 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -93,7 +93,7 @@ import {
   documentStore,
   initDocumentListeners,
   setDocumentSelection,
-} from './store/documents';
+} from './documents/store';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index ebfaa4164..48d031755 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -41,7 +41,7 @@ import { ConnectPhoneModal } from './ConnectPhoneModal';
 import { RemoveProjectConfirm } from './RemoveProjectConfirm';
 import { EditProjectDialog } from './EditProjectDialog';
 import { NewDocumentProjectDialog } from '../documents/NewDocumentProjectDialog';
-import { openDocumentWorkspace } from '../store/documents';
+import { openDocumentWorkspace } from '../documents/store';
 import { isDocumentProject } from '../store/projects';
 import { choice } from '../lib/dialog';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
diff --git a/src/documents/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
index 3d0aebfde..7da723283 100644
--- a/src/documents/AnnotationBubble.tsx
+++ b/src/documents/AnnotationBubble.tsx
@@ -9,8 +9,8 @@ import {
   documentStore,
   setDocumentAnnotationResolved,
   updateDocumentAnnotationText,
-} from '../store/documents';
-import { documentAgentSupport } from '../../electron/shared/document-agents';
+} from './store';
+import { documentAgentSupport } from '../../electron/documents/shared';
 import type { DocumentAnnotation } from '../ipc/types';
 
 interface AnnotationBubbleProps {
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
index 82684b3b6..71677edce 100644
--- a/src/documents/CompareView.tsx
+++ b/src/documents/CompareView.tsx
@@ -9,13 +9,13 @@ import {
 } from 'solid-js';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
-import { diffBlocks, type BlockChange, type DocumentBlock } from '../lib/markdown-blocks';
+import { diffBlocks, type BlockChange, type DocumentBlock } from './markdown-blocks';
 import {
   acceptDocumentCandidate,
   documentStore,
   rejectDocumentRun,
   setDocumentCandidateNote,
-} from '../store/documents';
+} from './store';
 import { getProject } from '../store/projects';
 import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
 import { DocumentViewer, type BlockRange } from './DocumentViewer';
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
index 4109c49a2..f71fbe113 100644
--- a/src/documents/DocumentViewer.tsx
+++ b/src/documents/DocumentViewer.tsx
@@ -1,7 +1,7 @@
 import { For, Show, createEffect, createMemo, on, type JSX } from 'solid-js';
-import type { BlockChange, DocumentBlock } from '../lib/markdown-blocks';
-import { blockRangeText, nearestHeading, sectionRange } from '../lib/markdown-blocks';
-import type { DocumentSelection } from '../store/documents';
+import type { BlockChange, DocumentBlock } from './markdown-blocks';
+import { blockRangeText, nearestHeading, sectionRange } from './markdown-blocks';
+import type { DocumentSelection } from './store';
 import { renderMermaidIn } from './use-blocks';
 
 export interface BlockRange {
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 899378c7e..4c82a522b 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -14,8 +14,8 @@ import {
   openDocumentCompare,
   undoDeleteDocumentAnnotation,
   type DocumentView,
-} from '../store/documents';
-import { relocateAnchor } from '../lib/annotation-anchor';
+} from './store';
+import { relocateAnchor } from './annotation-anchor';
 import type { DocumentAnnotation } from '../ipc/types';
 import { AnnotationBubble } from './AnnotationBubble';
 import { EditProjectDialog } from '../components/EditProjectDialog';
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
index b84a879e9..afd1b025b 100644
--- a/src/documents/HistoryView.tsx
+++ b/src/documents/HistoryView.tsx
@@ -3,7 +3,7 @@ import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
 import { confirm } from '../lib/dialog';
 import { formatRelativeAge } from '../lib/relativeAge';
-import { documentStore, revertDocumentCommit } from '../store/documents';
+import { documentStore, revertDocumentCommit } from './store';
 import { getProject } from '../store/projects';
 import type { DocumentHistoryEntry } from '../ipc/types';
 import { DocumentViewer } from './DocumentViewer';
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index 88e8e8576..e65bd4201 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -6,32 +6,64 @@ import { openDialog } from '../lib/dialog';
 import { errMessage } from '../lib/log';
 import { theme, sectionLabelStyle } from '../lib/theme';
 import { addDocumentProject } from '../store/projects';
-import { openDocumentWorkspace } from '../store/documents';
+import { showNotification } from '../store/notification';
+import type { DocumentFolderInfo, DocumentProjectSetup } from '../ipc/types';
+import { openDocumentWorkspace } from './store';
 
 interface NewDocumentProjectDialogProps {
   open: boolean;
   onClose: () => void;
 }
 
-/** Picks a Git repository and one Markdown document inside it. */
+const DEFAULT_DOCUMENT = 'notes.md';
+
+/** Mirrors the extension the backend appends, so the plan below names the real file. */
+function withMarkdownExtension(value: string): string {
+  return /\.(md|markdown)$/i.test(value) ? value : `${value}.md`;
+}
+
+/** The document a folder most likely wants opened: a committed file, else any file. */
+function preferredDocument(info: DocumentFolderInfo): string {
+  return info.files.find((f) => f.committed)?.path ?? info.files[0]?.path ?? DEFAULT_DOCUMENT;
+}
+
+/**
+ * Picks a folder and one Markdown document inside it. Neither has to exist
+ * yet: the backend initialises the repository, creates the document and makes
+ * the first commit, so the only thing asked of the user is where and what.
+ */
 export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
   const [folder, setFolder] = createSignal('');
+  const [info, setInfo] = createSignal<DocumentFolderInfo | null>(null);
   const [name, setName] = createSignal('');
-  const [files, setFiles] = createSignal<string[]>([]);
   const [filter, setFilter] = createSignal('');
   const [documentPath, setDocumentPath] = createSignal('');
   const [error, setError] = createSignal('');
   const [busy, setBusy] = createSignal(false);
 
+  const files = () => info()?.files ?? [];
   const visibleFiles = createMemo(() => {
     const q = filter().trim().toLowerCase();
-    return q ? files().filter((f) => f.toLowerCase().includes(q)) : files();
+    return q ? files().filter((f) => f.path.toLowerCase().includes(q)) : files();
+  });
+
+  /** What creating the project will do to the folder, so nothing is a surprise. */
+  const plan = createMemo(() => {
+    const current = info();
+    const wanted = withMarkdownExtension(documentPath().trim());
+    if (!current || !documentPath().trim()) return [];
+    const steps: string[] = [];
+    if (!current.isRepo) steps.push('run `git init`');
+    const match = files().find((f) => f.path === wanted);
+    if (!match) steps.push(`create ${wanted}`);
+    if (!match?.committed) steps.push('make a commit');
+    return steps;
   });
 
   function reset() {
     setFolder('');
+    setInfo(null);
     setName('');
-    setFiles([]);
     setFilter('');
     setDocumentPath('');
     setError('');
@@ -49,17 +81,20 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     setBusy(true);
     setError('');
     try {
-      const isGit = await invoke<boolean>(IPC.CheckIsGitRepo, { path });
-      if (!isGit) {
-        setError('Document projects need a Git repository. Run `git init` in the folder first.');
+      const found = await invoke<DocumentFolderInfo>(IPC.InspectDocumentFolder, {
+        projectRoot: path,
+      });
+      if (found.enclosingRepo) {
+        setError(
+          `That folder is inside the Git repository at ${found.enclosingRepo}. ` +
+            'Pick that repository instead, so proposals and history stay in one place.',
+        );
         return;
       }
-      const list = await invoke<string[]>(IPC.ListDocumentFiles, { projectRoot: path });
       setFolder(path);
+      setInfo(found);
       setName(path.split('/').pop() || path);
-      setFiles(list);
-      setDocumentPath(list.length === 1 ? list[0] : '');
-      if (list.length === 0) setError('No tracked Markdown files found. Commit a .md file first.');
+      setDocumentPath(preferredDocument(found));
     } catch (err) {
       setError(errMessage(err));
     } finally {
@@ -67,13 +102,26 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     }
   }
 
-  const canCreate = () => folder() && documentPath() && name().trim() && !busy();
+  const canCreate = () => folder() && documentPath().trim() && name().trim() && !busy();
 
   async function create() {
     if (!canCreate()) return;
-    const id = addDocumentProject(name().trim(), folder(), documentPath());
-    close();
-    await openDocumentWorkspace(id);
+    setBusy(true);
+    setError('');
+    try {
+      const setup = await invoke<DocumentProjectSetup>(IPC.PrepareDocumentProject, {
+        projectRoot: folder(),
+        documentPath: documentPath().trim(),
+      });
+      const id = addDocumentProject(name().trim(), folder(), setup.documentPath);
+      if (setup.actions.length > 0) showNotification(setup.actions.join(' · '));
+      close();
+      await openDocumentWorkspace(id);
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setBusy(false);
+    }
   }
 
   const inputStyle = {
@@ -93,11 +141,11 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
       <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 }}>
-          A Git repository with a Markdown document. Agents propose changes in isolated worktrees;
-          you decide what enters the document.
+          A folder with a Markdown document. Agents propose changes in isolated worktrees; you
+          decide what enters the document.
         </p>
         <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
-          <span style={sectionLabelStyle}>Repository</span>
+          <span style={sectionLabelStyle}>Folder</span>
           <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
             <button
               type="button"
@@ -132,6 +180,13 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
           </div>
           <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
             <span style={sectionLabelStyle}>Document</span>
+            <input
+              style={inputStyle}
+              aria-label="Document path"
+              placeholder={DEFAULT_DOCUMENT}
+              value={documentPath()}
+              onInput={(e) => setDocumentPath(e.currentTarget.value)}
+            />
             <Show when={files().length > 8}>
               <input
                 style={inputStyle}
@@ -140,21 +195,31 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
                 onInput={(e) => setFilter(e.currentTarget.value)}
               />
             </Show>
-            <div class="docws-picker-list" role="listbox" aria-label="Markdown files">
-              <For each={visibleFiles()}>
-                {(file) => (
-                  <button
-                    type="button"
-                    role="option"
-                    class="docws-picker-item"
-                    aria-selected={documentPath() === file}
-                    onClick={() => setDocumentPath(file)}
-                  >
-                    {file}
-                  </button>
-                )}
-              </For>
-            </div>
+            <Show when={files().length > 0}>
+              <div class="docws-picker-list" role="listbox" aria-label="Markdown files">
+                <For each={visibleFiles()}>
+                  {(file) => (
+                    <button
+                      type="button"
+                      role="option"
+                      class="docws-picker-item"
+                      aria-selected={documentPath() === file.path}
+                      onClick={() => setDocumentPath(file.path)}
+                    >
+                      {file.path}
+                      <Show when={!file.committed}>
+                        <span class="docws-badge">not committed</span>
+                      </Show>
+                    </button>
+                  )}
+                </For>
+              </div>
+            </Show>
+            <Show when={plan().length > 0}>
+              <span style={{ 'font-size': '12px', color: theme.fgMuted }}>
+                Parallel will {plan().join(', ')}.
+              </span>
+            </Show>
           </div>
         </Show>
         <Show when={error()}>
@@ -172,7 +237,7 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
             disabled={!canCreate()}
             onClick={() => void create()}
           >
-            Open workspace
+            {busy() ? 'Setting up…' : 'Open workspace'}
           </button>
         </div>
       </div>
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
index d31a4cb49..58097b4c0 100644
--- a/src/documents/RunComposer.tsx
+++ b/src/documents/RunComposer.tsx
@@ -8,16 +8,13 @@ import {
   setDocumentMainAgent,
   type DispatchSelection,
   type DocumentSelection,
-} from '../store/documents';
-import { createAnchor } from '../lib/annotation-anchor';
-import type { DocumentBlock } from '../lib/markdown-blocks';
+} 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/shared/document-agents';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from '../../electron/documents/shared';
 import type { AgentDef } from '../ipc/types';
 
 interface RunComposerProps {
@@ -46,7 +43,14 @@ export function RunComposer(props: RunComposerProps) {
   const [saving, setSaving] = createSignal(false);
   const project = () => (documentStore.projectId ? getProject(documentStore.projectId) : undefined);
   const mainAgentId = () => documentMainAgentId(project());
-  const [counts, setCounts] = createSignal<Record<string, number>>({ [mainAgentId()]: 1 });
+  // 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());
 
   const agents = createMemo(() => store.availableAgents);
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
index d1b7f4660..ca0ede00e 100644
--- a/src/documents/RunsRail.tsx
+++ b/src/documents/RunsRail.tsx
@@ -5,7 +5,7 @@ import {
   documentStore,
   openDocumentCompare,
   rejectDocumentRun,
-} from '../store/documents';
+} from './store';
 import { formatRelativeAge } from '../lib/relativeAge';
 import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
 
diff --git a/src/lib/annotation-anchor.test.ts b/src/documents/annotation-anchor.test.ts
similarity index 100%
rename from src/lib/annotation-anchor.test.ts
rename to src/documents/annotation-anchor.test.ts
diff --git a/src/lib/annotation-anchor.ts b/src/documents/annotation-anchor.ts
similarity index 100%
rename from src/lib/annotation-anchor.ts
rename to src/documents/annotation-anchor.ts
diff --git a/src/documents/documents.css b/src/documents/documents.css
index 86272c910..3e78f3246 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -871,6 +871,9 @@
 }
 
 .docws-picker-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
   text-align: left;
   background: transparent;
   border: none;
@@ -882,6 +885,10 @@
   cursor: pointer;
 }
 
+.docws-picker-item .docws-badge {
+  margin-left: auto;
+}
+
 .docws-picker-item:hover {
   background: var(--bg-hover);
 }
diff --git a/src/lib/markdown-blocks.test.ts b/src/documents/markdown-blocks.test.ts
similarity index 100%
rename from src/lib/markdown-blocks.test.ts
rename to src/documents/markdown-blocks.test.ts
diff --git a/src/lib/markdown-blocks.ts b/src/documents/markdown-blocks.ts
similarity index 99%
rename from src/lib/markdown-blocks.ts
rename to src/documents/markdown-blocks.ts
index 8c977ef1c..ee46523ef 100644
--- a/src/lib/markdown-blocks.ts
+++ b/src/documents/markdown-blocks.ts
@@ -1,6 +1,6 @@
 import DOMPurify from 'dompurify';
 import { Marked, type Token, type Tokens } from 'marked';
-import { highlightLines } from './shiki-highlighter';
+import { highlightLines } from '../lib/shiki-highlighter';
 
 /**
  * A top-level markdown block with its source line range. Blocks are the unit
diff --git a/src/store/documents.ts b/src/documents/store.ts
similarity index 98%
rename from src/store/documents.ts
rename to src/documents/store.ts
index 40e0cd5f9..dbb95ae57 100644
--- a/src/store/documents.ts
+++ b/src/documents/store.ts
@@ -25,11 +25,11 @@ import {
   DEFAULT_DOCUMENT_MAIN_AGENT,
   MAX_DOCUMENT_CANDIDATES,
   documentAgentSupport,
-} from '../../electron/shared/document-agents';
-import { store, setStore } from './core';
-import { getProject, updateProject } from './projects';
-import { showNotification } from './notification';
-import type { Project } from './types';
+} from '../../electron/documents/shared';
+import { store, setStore } from '../store/core';
+import { getProject, updateProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import type { Project } from '../store/types';
 
 export type DocumentView = 'document' | 'compare' | 'history';
 
diff --git a/src/documents/use-blocks.ts b/src/documents/use-blocks.ts
index 09a0fb78e..7a053c27c 100644
--- a/src/documents/use-blocks.ts
+++ b/src/documents/use-blocks.ts
@@ -1,5 +1,5 @@
 import { createEffect, createSignal, onCleanup } from 'solid-js';
-import { renderDocumentBlocks, type DocumentBlock } from '../lib/markdown-blocks';
+import { renderDocumentBlocks, type DocumentBlock } from './markdown-blocks';
 
 /**
  * Reactively renders a markdown source into blocks. Stale renders are dropped
diff --git a/src/ipc/types.ts b/src/ipc/types.ts
index 43c60a626..b478c18ce 100644
--- a/src/ipc/types.ts
+++ b/src/ipc/types.ts
@@ -14,7 +14,10 @@ export type {
   DocumentCandidateRecord,
   DocumentCandidateSpec,
   DocumentCandidateStatus,
+  DocumentFileInfo,
+  DocumentFolderInfo,
   DocumentHistoryEntry,
+  DocumentProjectSetup,
   DocumentRationale,
   DocumentRunEvent,
   DocumentRunRecord,
diff --git a/src/store/remoteTaskHandler.ts b/src/store/remoteTaskHandler.ts
index 48e63a7ec..d57f6ad04 100644
--- a/src/store/remoteTaskHandler.ts
+++ b/src/store/remoteTaskHandler.ts
@@ -38,7 +38,8 @@ function handleGetProjects(req: RendererRequest): void {
   reply(
     req.reqId,
     true,
-    store.projects.map((p) => ({ id: p.id, name: p.name })),
+    // Document projects have no task flow, so they are not offered as targets.
+    store.projects.filter((p) => p.kind !== 'document').map((p) => ({ id: p.id, name: p.name })),
   );
 }
 

From 279c5fee15f693f5ea2b62205eb721167ebe57cf Mon Sep 17 00:00:00 2001
From: Johannes Millan <johannes.millan@gmail.com>
Date: Fri, 4 Sep 2026 09:49:00 +0200
Subject: [PATCH 05/12] refactor(documents): move the feature's IPC layer and
 types into its folder

The workspace's 19 handlers were inline in the app-wide registrar and its 20
IPC shapes sat in two shared type barrels, so the feature still reached into
four files it did not own. They now live in electron/documents/register.ts and
electron/documents/types.ts, with src/documents/types.ts mirroring the shapes
for the renderer. register.ts sheds 150 lines, shared-types.ts 204, and
main.ts calls one stopAllDocumentWork() instead of three shutdown functions.

validatePath joins the other argument validators in ipc/validate.ts so both
registrars share it, and the `kind !== 'document'` filter that had been copied
into three call sites becomes codeProjects().

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 docs/document-workspaces.md                   |   9 +-
 electron/documents/annotations.test.ts        |   2 +-
 electron/documents/annotations.ts             |   2 +-
 electron/documents/prompt.ts                  |   2 +-
 electron/documents/register.ts                | 169 ++++++++++++++
 electron/documents/runs.integration.test.ts   |   2 +-
 .../runs.real-claude.integration.test.ts      |   2 +-
 electron/documents/runs.ts                    |   2 +-
 electron/documents/setup.ts                   |   6 +-
 electron/documents/types.ts                   | 207 ++++++++++++++++++
 electron/ipc/register.ts                      | 156 +------------
 electron/ipc/shared-types.ts                  | 205 -----------------
 electron/ipc/validate.ts                      |   8 +
 electron/main.ts                              |   7 +-
 src/components/NewTaskDialog.tsx              |   7 +-
 src/components/ProjectSelect.tsx              |   8 +-
 src/documents/AnnotationBubble.tsx            |   2 +-
 src/documents/CompareView.tsx                 |   2 +-
 src/documents/DocumentWorkspaceOverlay.tsx    |   2 +-
 src/documents/HistoryView.tsx                 |   2 +-
 src/documents/NewDocumentProjectDialog.tsx    |   2 +-
 src/documents/RunsRail.tsx                    |   2 +-
 src/documents/annotation-anchor.ts            |   2 +-
 src/documents/store.ts                        |   4 +-
 src/documents/types.ts                        |   2 +
 src/ipc/types.ts                              |  17 --
 src/store/projects.ts                         |   5 +
 src/store/remoteTaskHandler.ts                |   4 +-
 src/store/store.ts                            |   1 +
 29 files changed, 426 insertions(+), 415 deletions(-)
 create mode 100644 electron/documents/register.ts
 create mode 100644 electron/documents/types.ts
 create mode 100644 src/documents/types.ts

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 9aea091ac..2849f3849 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -102,9 +102,12 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   `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.
-- **It lives in two folders.** `electron/documents/` (runs, agents, prompts, annotations,
-  setup) and `src/documents/` (the workspace UI with its store and markdown helpers). The
-  one file the renderer imports across that boundary is `electron/documents/shared.ts`.
+- **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
+  three lines: `registerDocumentHandlers(win)` and `stopAllDocumentWork()` in main,
+  `<DocumentWorkspaceOverlay />` in `App.tsx`. The one runtime module the renderer imports
+  across the process boundary is `electron/documents/shared.ts`.
 
 ### Not in this slice
 
diff --git a/electron/documents/annotations.test.ts b/electron/documents/annotations.test.ts
index 19076c212..569db8f0d 100644
--- a/electron/documents/annotations.test.ts
+++ b/electron/documents/annotations.test.ts
@@ -11,7 +11,7 @@ import {
   saveAnnotation,
   validateAnnotationInput,
 } from './annotations.js';
-import type { DocumentAnnotation, DocumentAnnotationEvent } from '../ipc/shared-types.js';
+import type { DocumentAnnotation, DocumentAnnotationEvent } from './types.js';
 
 const anchor = {
   path: 'docs/spec.md',
diff --git a/electron/documents/annotations.ts b/electron/documents/annotations.ts
index 5d0357d13..d9d0ab8a6 100644
--- a/electron/documents/annotations.ts
+++ b/electron/documents/annotations.ts
@@ -21,7 +21,7 @@ import type {
   DocumentAnnotation,
   DocumentAnnotationEvent,
   DocumentAnnotationsFile,
-} from '../ipc/shared-types.js';
+} from './types.js';
 
 export const ANNOTATIONS_REL_PATH = path.posix.join('.parallel', 'annotations.json');
 const MAX_TEXT_CHARS = 20_000;
diff --git a/electron/documents/prompt.ts b/electron/documents/prompt.ts
index 932ee5d6c..ff191b926 100644
--- a/electron/documents/prompt.ts
+++ b/electron/documents/prompt.ts
@@ -1,4 +1,4 @@
-import type { DocumentRationale, DocumentScope } from '../ipc/shared-types.js';
+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;
diff --git a/electron/documents/register.ts b/electron/documents/register.ts
new file mode 100644
index 000000000..078a72228
--- /dev/null
+++ b/electron/documents/register.ts
@@ -0,0 +1,169 @@
+/**
+ * Every IPC handler the document workspace owns, in one place. Handlers take
+ * the project root from the renderer and validate it; document paths are
+ * repo-relative and checked against traversal.
+ */
+import { ipcMain, type BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import {
+  assertOptionalBoolean,
+  assertOptionalString,
+  assertString,
+  validatePath,
+} from '../ipc/validate.js';
+import {
+  acceptDocumentCandidate,
+  cancelDocumentRun,
+  dispatchDocumentRun,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+  revertDocumentCommit,
+  setDocumentCandidateNote,
+  startDocumentWatcher,
+  stopAllDocumentRuns,
+  stopAllDocumentWatchers,
+  stopDocumentWatcher,
+  validateDocumentPath,
+  validateSha,
+} from './runs.js';
+import { inspectDocumentFolder, prepareDocumentProject } from './setup.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.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);
+  });
+
+  ipcMain.handle(IPC.ListDocumentRuns, (_e, args) => {
+    return listDocumentRuns(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.DispatchDocumentRun, (_e, args) => {
+    return dispatchDocumentRun(win, {
+      projectRoot: projectRootArg(args),
+      documentPath: args.documentPath,
+      instruction: args.instruction,
+      scope: args.scope,
+      candidates: args.candidates,
+    });
+  });
+
+  ipcMain.handle(IPC.CancelDocumentRun, (_e, args) => {
+    cancelDocumentRun(args.runId);
+  });
+
+  ipcMain.handle(IPC.AcceptDocumentCandidate, (_e, args) => {
+    return acceptDocumentCandidate(projectRootArg(args), args.runId, args.candidateId);
+  });
+
+  ipcMain.handle(IPC.RejectDocumentRun, (_e, args) => {
+    return rejectDocumentRun(projectRootArg(args), args.runId);
+  });
+
+  ipcMain.handle(IPC.SetDocumentCandidateNote, (_e, args) => {
+    return setDocumentCandidateNote(projectRootArg(args), args.runId, args.candidateId, args.note);
+  });
+
+  ipcMain.handle(IPC.GetDocumentHistory, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    assertOptionalBoolean(args.wholeProject, 'wholeProject');
+    return getDocumentHistory(
+      projectRoot,
+      validateDocumentPath(args.documentPath),
+      args.wholeProject === true,
+    );
+  });
+
+  ipcMain.handle(IPC.GetDocumentAtCommit, (_e, args) => {
+    return getDocumentAtCommit(
+      projectRootArg(args),
+      validateSha(args.sha),
+      validateDocumentPath(args.documentPath),
+    );
+  });
+
+  ipcMain.handle(IPC.GetDocumentDiff, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    const to = validateSha(args.to, 'to');
+    // `from` is a commit hash, or that hash's parent for history entries.
+    assertString(args.from, 'from');
+    const from = args.from.endsWith('^')
+      ? `${validateSha(args.from.slice(0, -1), 'from')}^`
+      : validateSha(args.from, 'from');
+    return getDocumentDiff(projectRoot, from, to, validateDocumentPath(args.documentPath));
+  });
+
+  ipcMain.handle(IPC.RevertDocumentCommit, (_e, args) => {
+    return revertDocumentCommit(projectRootArg(args), validateSha(args.sha));
+  });
+
+  // --- Annotations ---
+  ipcMain.handle(IPC.ListDocumentAnnotations, (_e, args) => {
+    return readAnnotations(projectRootArg(args));
+  });
+
+  ipcMain.handle(IPC.SaveDocumentAnnotation, (_e, args) => {
+    return saveAnnotation(projectRootArg(args), args.annotation);
+  });
+
+  ipcMain.handle(IPC.DeleteDocumentAnnotation, (_e, args) => {
+    return deleteAnnotation(projectRootArg(args), args.id);
+  });
+
+  ipcMain.handle(IPC.AskDocumentAnnotation, (_e, args) => {
+    const projectRoot = projectRootArg(args);
+    assertOptionalString(args.envFile, 'envFile');
+    return askAnnotation(win, {
+      projectRoot,
+      documentPath: args.documentPath,
+      annotationId: args.annotationId,
+      agentId: args.agentId,
+      agentName: args.agentName,
+      command: args.command,
+      envFile: args.envFile,
+    });
+  });
+}
+
+/** Everything the feature keeps alive; called on app quit. */
+export function stopAllDocumentWork(): void {
+  stopAllDocumentWatchers();
+  stopAllDocumentRuns();
+  stopAllAsks();
+}
diff --git a/electron/documents/runs.integration.test.ts b/electron/documents/runs.integration.test.ts
index bace1516f..3e3b56a06 100644
--- a/electron/documents/runs.integration.test.ts
+++ b/electron/documents/runs.integration.test.ts
@@ -17,7 +17,7 @@ import {
   rejectDocumentRun,
 } from './runs.js';
 import { inspectDocumentFolder } from './setup.js';
-import type { DocumentRunEvent, DocumentRunRecord } from '../ipc/shared-types.js';
+import type { DocumentRunEvent, DocumentRunRecord } from './types.js';
 
 /**
  * Exercises the whole proposal lifecycle against a real temporary repository
diff --git a/electron/documents/runs.real-claude.integration.test.ts b/electron/documents/runs.real-claude.integration.test.ts
index 1727ff454..202fd91d6 100644
--- a/electron/documents/runs.real-claude.integration.test.ts
+++ b/electron/documents/runs.real-claude.integration.test.ts
@@ -11,7 +11,7 @@ import type {
   DocumentAnnotationEvent,
   DocumentRunEvent,
   DocumentRunRecord,
-} from '../ipc/shared-types.js';
+} from './types.js';
 
 /**
  * Drives the real `claude` CLI through one proposal and one resumed follow-up.
diff --git a/electron/documents/runs.ts b/electron/documents/runs.ts
index fc1ee00af..60f3f3047 100644
--- a/electron/documents/runs.ts
+++ b/electron/documents/runs.ts
@@ -28,7 +28,7 @@ import type {
   DocumentRunRecord,
   DocumentScope,
   DocumentSnapshot,
-} from '../ipc/shared-types.js';
+} from './types.js';
 
 /** A proposal that runs longer than this is killed and marked failed. */
 const CANDIDATE_TIMEOUT_MS = 30 * 60_000;
diff --git a/electron/documents/setup.ts b/electron/documents/setup.ts
index 6a429d7be..9f21f4ee7 100644
--- a/electron/documents/setup.ts
+++ b/electron/documents/setup.ts
@@ -8,11 +8,7 @@ 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 '../ipc/shared-types.js';
+import type { DocumentFileInfo, DocumentFolderInfo, DocumentProjectSetup } from './types.js';
 
 const MAX_FILES = 1000;
 /** How far the pre-repository scan walks before it stops looking. */
diff --git a/electron/documents/types.ts b/electron/documents/types.ts
new file mode 100644
index 000000000..82e40d11c
--- /dev/null
+++ b/electron/documents/types.ts
@@ -0,0 +1,207 @@
+/**
+ * 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 {
+  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;
+  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[];
+  acceptedCandidateId?: string;
+  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;
+  /** Provider session to resume for the main candidate. */
+  sessionId?: string;
+  /** Sha the resumed session last saw; the prompt carries the diff since then. */
+  sessionLastSha?: string;
+  /** Per-agent env file, when configured. */
+  envFile?: string;
+}
+
+export interface DocumentHistoryEntry {
+  sha: string;
+  shortSha: string;
+  subject: string;
+  body: string;
+  author: string;
+  /** Unix seconds. */
+  timestamp: number;
+  /** `Parallel-*` trailers, keys without the prefix (e.g. `Agent`, `Run`). */
+  trailers: Record<string, string>;
+  /** True when no agent trailer is present: a manual commit. */
+  manual: boolean;
+}
+
+// --- Document annotations ---
+
+/**
+ * Where an annotation sits. Offsets alone go stale as soon as anything above
+ * them changes, so the anchor also carries the exact quote, its neighbours
+ * and the nearest heading; the renderer relocates it on the current version
+ * and shows it detached when it cannot.
+ */
+export interface DocumentAnchor {
+  path: string;
+  /** Commit the offsets were taken against. */
+  baseSha: string | null;
+  startLine: number;
+  endLine: number;
+  /** Exact source text of the anchored blocks. */
+  quote: string;
+  /** Tail of the preceding block and head of the following one. */
+  prefix: string;
+  suffix: string;
+  heading?: string;
+}
+
+export type DocumentAnnotationKind = 'note' | 'question';
+
+export interface DocumentAnnotationAnswer {
+  text: string;
+  agentId: string;
+  agentName: string;
+  answeredAt: string;
+}
+
+export type DocumentAnswerStatus = 'pending' | 'answered' | 'failed';
+
+/** A bubble beside the document: a note, or a question an agent answers into it. */
+export interface DocumentAnnotation {
+  id: string;
+  kind: DocumentAnnotationKind;
+  anchor: DocumentAnchor;
+  text: string;
+  createdAt: string;
+  updatedAt: string;
+  resolved: boolean;
+  answer?: DocumentAnnotationAnswer;
+  answerStatus?: DocumentAnswerStatus;
+  answerError?: string;
+  /** Run this annotation was turned into, if any. */
+  runId?: string;
+}
+
+/** Persisted as `.parallel/annotations.json` inside the document project. */
+export interface DocumentAnnotationsFile {
+  version: 1;
+  annotations: DocumentAnnotation[];
+}
+
+export interface DocumentAnnotationEvent {
+  projectRoot: string;
+  annotation: DocumentAnnotation;
+}
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index 5b4152d7a..187317626 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -94,30 +94,6 @@ import {
 } from './updater.js';
 import { spawn } from 'child_process';
 import { askAboutCode, cancelAskAboutCode } from './ask-code.js';
-import {
-  acceptDocumentCandidate,
-  cancelDocumentRun,
-  dispatchDocumentRun,
-  getDocumentAtCommit,
-  getDocumentDiff,
-  getDocumentHistory,
-  listDocumentRuns,
-  readDocumentSnapshot,
-  rejectDocumentRun,
-  revertDocumentCommit,
-  setDocumentCandidateNote,
-  startDocumentWatcher,
-  stopDocumentWatcher,
-  validateDocumentPath,
-  validateSha,
-} from '../documents/runs.js';
-import { inspectDocumentFolder, prepareDocumentProject } from '../documents/setup.js';
-import {
-  askAnnotation,
-  deleteAnnotation,
-  readAnnotations,
-  saveAnnotation,
-} from '../documents/annotations.js';
 import { setMinimaxApiKey } from './ask-code-minimax.js';
 import { getSystemMonospaceFonts } from './system-fonts.js';
 import { fetchClaudeUsage } from './claude-usage.js';
@@ -130,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';
@@ -203,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 (
@@ -986,128 +957,7 @@ export function registerAllHandlers(win: BrowserWindow): void {
     cancelAskAboutCode(args.requestId);
   });
 
-  // --- Document workspaces ---
-  // Every handler takes the project root from the renderer and validates it;
-  // the document path is repo-relative and checked against traversal.
-  ipcMain.handle(IPC.ReadDocument, (_e, args) => {
-    const projectRoot = projectRootArg(args);
-    return readDocumentSnapshot(projectRoot, validateDocumentPath(args.documentPath));
-  });
-
-  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);
-  });
-
-  ipcMain.handle(IPC.ListDocumentRuns, (_e, args) => {
-    return listDocumentRuns(projectRootArg(args));
-  });
-
-  ipcMain.handle(IPC.DispatchDocumentRun, (_e, args) => {
-    const projectRoot = projectRootArg(args);
-    return dispatchDocumentRun(win, {
-      projectRoot,
-      documentPath: args.documentPath,
-      instruction: args.instruction,
-      scope: args.scope,
-      candidates: args.candidates,
-    });
-  });
-
-  ipcMain.handle(IPC.CancelDocumentRun, (_e, args) => {
-    cancelDocumentRun(args.runId);
-  });
-
-  ipcMain.handle(IPC.AcceptDocumentCandidate, (_e, args) => {
-    const projectRoot = projectRootArg(args);
-    return acceptDocumentCandidate(projectRoot, args.runId, args.candidateId);
-  });
-
-  ipcMain.handle(IPC.RejectDocumentRun, (_e, args) => {
-    const projectRoot = projectRootArg(args);
-    return rejectDocumentRun(projectRoot, args.runId);
-  });
-
-  ipcMain.handle(IPC.SetDocumentCandidateNote, (_e, args) => {
-    const projectRoot = projectRootArg(args);
-    return setDocumentCandidateNote(projectRoot, 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) => {
-    const projectRoot = projectRootArg(args);
-    return getDocumentAtCommit(
-      projectRoot,
-      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) => {
-    const projectRoot = projectRootArg(args);
-    return revertDocumentCommit(projectRoot, validateSha(args.sha));
-  });
-
-  // --- Document 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,
-    });
-  });
+  registerDocumentHandlers(win);
 
   // --- File links ---
   ipcMain.handle(IPC.OpenPath, (_e, args) => {
diff --git a/electron/ipc/shared-types.ts b/electron/ipc/shared-types.ts
index 5cd2913ea..b0ae28be5 100644
--- a/electron/ipc/shared-types.ts
+++ b/electron/ipc/shared-types.ts
@@ -221,208 +221,3 @@ export type UsageResult =
   | { status: 'unavailable'; reason: string }
   /** Transient failure — the renderer keeps its last good snapshot. */
   | { status: 'error'; message: string };
-
-// --- Document workspaces ---
-
-/** 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 {
-  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;
-  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[];
-  acceptedCandidateId?: string;
-  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;
-  /** Provider session to resume for the main candidate. */
-  sessionId?: string;
-  /** Sha the resumed session last saw; the prompt carries the diff since then. */
-  sessionLastSha?: string;
-  /** Per-agent env file, when configured. */
-  envFile?: string;
-}
-
-export interface DocumentHistoryEntry {
-  sha: string;
-  shortSha: string;
-  subject: string;
-  body: string;
-  author: string;
-  /** Unix seconds. */
-  timestamp: number;
-  /** `Parallel-*` trailers, keys without the prefix (e.g. `Agent`, `Run`). */
-  trailers: Record<string, string>;
-  /** True when no agent trailer is present: a manual commit. */
-  manual: boolean;
-}
-
-// --- Document annotations ---
-
-/**
- * Where an annotation sits. Offsets alone go stale as soon as anything above
- * them changes, so the anchor also carries the exact quote, its neighbours
- * and the nearest heading; the renderer relocates it on the current version
- * and shows it detached when it cannot.
- */
-export interface DocumentAnchor {
-  path: string;
-  /** Commit the offsets were taken against. */
-  baseSha: string | null;
-  startLine: number;
-  endLine: number;
-  /** Exact source text of the anchored blocks. */
-  quote: string;
-  /** Tail of the preceding block and head of the following one. */
-  prefix: string;
-  suffix: string;
-  heading?: string;
-}
-
-export type DocumentAnnotationKind = 'note' | 'question';
-
-export interface DocumentAnnotationAnswer {
-  text: string;
-  agentId: string;
-  agentName: string;
-  answeredAt: string;
-}
-
-export type DocumentAnswerStatus = 'pending' | 'answered' | 'failed';
-
-/** A bubble beside the document: a note, or a question an agent answers into it. */
-export interface DocumentAnnotation {
-  id: string;
-  kind: DocumentAnnotationKind;
-  anchor: DocumentAnchor;
-  text: string;
-  createdAt: string;
-  updatedAt: string;
-  resolved: boolean;
-  answer?: DocumentAnnotationAnswer;
-  answerStatus?: DocumentAnswerStatus;
-  answerError?: string;
-  /** Run this annotation was turned into, if any. */
-  runId?: string;
-}
-
-/** Persisted as `.parallel/annotations.json` inside the document project. */
-export interface DocumentAnnotationsFile {
-  version: 1;
-  annotations: DocumentAnnotation[];
-}
-
-export interface DocumentAnnotationEvent {
-  projectRoot: string;
-  annotation: DocumentAnnotation;
-}
diff --git a/electron/ipc/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 d8dcd74ec..50cbf2fae 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -10,8 +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 { stopAllDocumentRuns, stopAllDocumentWatchers } from './documents/runs.js';
-import { stopAllAsks } from './documents/annotations.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';
@@ -290,9 +289,7 @@ app.on('will-quit', () => {
   verificationRunner.cancelAll();
   stopAgentHookRuntime();
   stopAllPlanWatchers();
-  stopAllDocumentWatchers();
-  stopAllDocumentRuns();
-  stopAllAsks();
+  stopAllDocumentWork();
   stopAllStepsWatchers();
 });
 
diff --git a/src/components/NewTaskDialog.tsx b/src/components/NewTaskDialog.tsx
index 2eb416680..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,11 +552,9 @@ export function NewTaskDialog(props: NewTaskDialogProps) {
 
             // Pre-fill from drop data if present
             const dropUrl = store.newTaskDropUrl;
-            const codeProjects = store.projects.filter((p) => p.kind !== 'document');
+            const targets = codeProjects();
             const fallbackProjectId =
-              codeProjects.find((p) => p.id === store.lastProjectId)?.id ??
-              codeProjects[0]?.id ??
-              null;
+              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/ProjectSelect.tsx b/src/components/ProjectSelect.tsx
index 316eed2cb..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,11 +20,7 @@ export function ProjectSelect(props: ProjectSelectProps) {
           {props.placeholder}
         </option>
       </Show>
-      <For
-        each={store.projects
-          .filter((p) => p.kind !== 'document')
-          .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/documents/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
index 7da723283..a4d30bb87 100644
--- a/src/documents/AnnotationBubble.tsx
+++ b/src/documents/AnnotationBubble.tsx
@@ -11,7 +11,7 @@ import {
   updateDocumentAnnotationText,
 } from './store';
 import { documentAgentSupport } from '../../electron/documents/shared';
-import type { DocumentAnnotation } from '../ipc/types';
+import type { DocumentAnnotation } from './types';
 
 interface AnnotationBubbleProps {
   annotation: DocumentAnnotation;
diff --git a/src/documents/CompareView.tsx b/src/documents/CompareView.tsx
index 71677edce..0ce589e20 100644
--- a/src/documents/CompareView.tsx
+++ b/src/documents/CompareView.tsx
@@ -17,7 +17,7 @@ import {
   setDocumentCandidateNote,
 } from './store';
 import { getProject } from '../store/projects';
-import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
 import { DocumentViewer, type BlockRange } from './DocumentViewer';
 import { SourceDiff } from './SourceDiff';
 import { createRenderedBlocks } from './use-blocks';
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 4c82a522b..191728d69 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -16,7 +16,7 @@ import {
   type DocumentView,
 } from './store';
 import { relocateAnchor } from './annotation-anchor';
-import type { DocumentAnnotation } from '../ipc/types';
+import type { DocumentAnnotation } from './types';
 import { AnnotationBubble } from './AnnotationBubble';
 import { EditProjectDialog } from '../components/EditProjectDialog';
 import type { Project } from '../store/types';
diff --git a/src/documents/HistoryView.tsx b/src/documents/HistoryView.tsx
index afd1b025b..769e55dc8 100644
--- a/src/documents/HistoryView.tsx
+++ b/src/documents/HistoryView.tsx
@@ -5,7 +5,7 @@ import { confirm } from '../lib/dialog';
 import { formatRelativeAge } from '../lib/relativeAge';
 import { documentStore, revertDocumentCommit } from './store';
 import { getProject } from '../store/projects';
-import type { DocumentHistoryEntry } from '../ipc/types';
+import type { DocumentHistoryEntry } from './types';
 import { DocumentViewer } from './DocumentViewer';
 import { SourceDiff } from './SourceDiff';
 import { createRenderedBlocks } from './use-blocks';
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index e65bd4201..d759dcc8e 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -7,7 +7,7 @@ import { errMessage } from '../lib/log';
 import { theme, sectionLabelStyle } from '../lib/theme';
 import { addDocumentProject } from '../store/projects';
 import { showNotification } from '../store/notification';
-import type { DocumentFolderInfo, DocumentProjectSetup } from '../ipc/types';
+import type { DocumentFolderInfo, DocumentProjectSetup } from './types';
 import { openDocumentWorkspace } from './store';
 
 interface NewDocumentProjectDialogProps {
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
index ca0ede00e..82457d297 100644
--- a/src/documents/RunsRail.tsx
+++ b/src/documents/RunsRail.tsx
@@ -7,7 +7,7 @@ import {
   rejectDocumentRun,
 } from './store';
 import { formatRelativeAge } from '../lib/relativeAge';
-import type { DocumentCandidateRecord, DocumentRunRecord } from '../ipc/types';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
 
 function scopeLabel(run: DocumentRunRecord): string {
   const s = run.scope;
diff --git a/src/documents/annotation-anchor.ts b/src/documents/annotation-anchor.ts
index f243d39a5..d8f2020ec 100644
--- a/src/documents/annotation-anchor.ts
+++ b/src/documents/annotation-anchor.ts
@@ -1,4 +1,4 @@
-import type { DocumentAnchor } from '../ipc/types';
+import type { DocumentAnchor } from './types';
 import { blockRangeText, nearestHeading, type DocumentBlock } from './markdown-blocks';
 
 /** Characters of neighbouring text kept on either side of an anchor. */
diff --git a/src/documents/store.ts b/src/documents/store.ts
index dbb95ae57..a902b81f2 100644
--- a/src/documents/store.ts
+++ b/src/documents/store.ts
@@ -8,8 +8,8 @@ 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 {
-  AgentDef,
   DocumentAnchor,
   DocumentAnnotation,
   DocumentAnnotationEvent,
@@ -20,7 +20,7 @@ import type {
   DocumentRunRecord,
   DocumentScope,
   DocumentSnapshot,
-} from '../ipc/types';
+} from './types';
 import {
   DEFAULT_DOCUMENT_MAIN_AGENT,
   MAX_DOCUMENT_CANDIDATES,
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/ipc/types.ts b/src/ipc/types.ts
index b478c18ce..4b46282de 100644
--- a/src/ipc/types.ts
+++ b/src/ipc/types.ts
@@ -7,23 +7,6 @@ export type {
   CoverageMetricSummary,
   CoverageSummary,
   CreateTaskResult,
-  DocumentAnchor,
-  DocumentAnnotation,
-  DocumentAnnotationEvent,
-  DocumentAnnotationKind,
-  DocumentCandidateRecord,
-  DocumentCandidateSpec,
-  DocumentCandidateStatus,
-  DocumentFileInfo,
-  DocumentFolderInfo,
-  DocumentHistoryEntry,
-  DocumentProjectSetup,
-  DocumentRationale,
-  DocumentRunEvent,
-  DocumentRunRecord,
-  DocumentRunStatus,
-  DocumentScope,
-  DocumentSnapshot,
   EslintQualityFinding,
   EslintQualityResult,
   FileDiffResult,
diff --git a/src/store/projects.ts b/src/store/projects.ts
index 8fd968103..8c3966e08 100644
--- a/src/store/projects.ts
+++ b/src/store/projects.ts
@@ -55,6 +55,11 @@ 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];
diff --git a/src/store/remoteTaskHandler.ts b/src/store/remoteTaskHandler.ts
index d57f6ad04..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,8 +39,7 @@ function handleGetProjects(req: RendererRequest): void {
   reply(
     req.reqId,
     true,
-    // Document projects have no task flow, so they are not offered as targets.
-    store.projects.filter((p) => p.kind !== 'document').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 8add82b01..5341a5b4c 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -9,6 +9,7 @@ export {
   getProjectBranchPrefix,
   pickAndAddProject,
   addDocumentProject,
+  codeProjects,
   isDocumentProject,
   validateProjectPaths,
   relinkProject,

From 989552419ca4a729fe525b9e904512bd581a7f14 Mon Sep 17 00:00:00 2001
From: Johannes Millan <johannes.millan@gmail.com>
Date: Fri, 4 Sep 2026 10:01:24 +0200
Subject: [PATCH 06/12] feat(documents): create the project folder too, instead
 of asking for one

Picking a document project still meant creating its folder outside the app
first. The Folder field is now an editable path: browse to a parent, type a
name onto the end, and that folder is the project. Setup creates it, and
inspection treats a path that does not exist yet as empty rather than an
error, so the dialog keeps describing what it will do while you type.

The path is inspected 250ms after typing stops rather than per keystroke, an
enclosing repository is reported inline instead of only on confirm, and the
Settings description no longer claims a Git repository is a prerequisite.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 docs/document-workspaces.md                |  15 +-
 electron/documents/setup.test.ts           |  35 +++++
 electron/documents/setup.ts                |  24 +++-
 electron/documents/types.ts                |   2 +
 src/components/SettingsDialog.tsx          |   2 +-
 src/documents/NewDocumentProjectDialog.tsx | 158 +++++++++++++--------
 6 files changed, 164 insertions(+), 72 deletions(-)

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 2849f3849..19de31266 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -24,9 +24,10 @@ the document.
 ### Using it
 
 1. Enable _Document workspaces_ under Settings → Experimental.
-2. Click **+** next to Projects and choose **Document project**. Pick any folder and name
-   the document. Neither has to exist yet: the dialog says what it will do — `git init`,
-   create the file, make the first commit — and does it when you confirm.
+2. Click **+** next to Projects and choose **Document project**. Type or browse to a
+   folder and name the document. Neither has to exist: type a new name onto the end of the
+   path and that folder is the project. 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 three tabs: **Document**, **Compare**, **History**.
 4. In the document, select text, click a block, or press **§** next to a heading to select
    the section. A composer opens under the selection: type an instruction, pick agents and
@@ -98,10 +99,10 @@ workspace-write` (the sandbox blocks writes outside the worktree),
   as **detached** rather than attaching it 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 —
-  `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.
+- **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.
 - **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
diff --git a/electron/documents/setup.test.ts b/electron/documents/setup.test.ts
index 1e81fe705..e7a96875f 100644
--- a/electron/documents/setup.test.ts
+++ b/electron/documents/setup.test.ts
@@ -35,6 +35,7 @@ describe('inspectDocumentFolder', () => {
     fs.writeFileSync(path.join(dir, 'ignore.txt'), 'x');
 
     expect(await inspectDocumentFolder(dir)).toEqual({
+      exists: true,
       isRepo: false,
       enclosingRepo: null,
       hasCommits: false,
@@ -51,6 +52,7 @@ describe('inspectDocumentFolder', () => {
     fs.writeFileSync(path.join(dir, 'loose.md'), '# Two\n');
 
     expect(await inspectDocumentFolder(dir)).toEqual({
+      exists: true,
       isRepo: true,
       enclosingRepo: null,
       hasCommits: true,
@@ -61,6 +63,18 @@ describe('inspectDocumentFolder', () => {
     });
   });
 
+  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);
@@ -84,6 +98,27 @@ describe('prepareDocumentProject', () => {
     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();
 
diff --git a/electron/documents/setup.ts b/electron/documents/setup.ts
index 9f21f4ee7..9c2f8ac7f 100644
--- a/electron/documents/setup.ts
+++ b/electron/documents/setup.ts
@@ -67,13 +67,17 @@ async function listMarkdown(folder: string, lsFilesArgs: string[]): Promise<stri
  * 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 = scanMarkdown(folder).map(
       (p): DocumentFileInfo => ({ path: p, committed: false }),
     );
-    return { isRepo: false, enclosingRepo: toplevel, hasCommits: false, files };
+    return { exists: true, isRepo: false, enclosingRepo: toplevel, hasCommits: false, files };
   }
   const hasCommits = await gitOk(folder, ['rev-parse', '--verify', 'HEAD']);
   const tracked = new Set(await listMarkdown(folder, []));
@@ -82,7 +86,7 @@ export async function inspectDocumentFolder(folder: string): Promise<DocumentFol
     .sort()
     .slice(0, MAX_FILES)
     .map((p): DocumentFileInfo => ({ path: p, committed: hasCommits && tracked.has(p) }));
-  return { isRepo: true, enclosingRepo: null, hasCommits, files };
+  return { exists: true, isRepo: true, enclosingRepo: null, hasCommits, files };
 }
 
 /** `notes.md` → `Notes`; the heading a brand-new document opens with. */
@@ -96,19 +100,25 @@ function withMarkdownExtension(documentPath: string): string {
 }
 
 /**
- * Brings `folder` up to what the workspace assumes: a repository of its own,
- * with `requestedPath` committed. Every step is skipped when it is already
- * true, so re-running this on a ready project does nothing.
+ * 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.
  */
 export async function prepareDocumentProject(
   folder: string,
   requestedPath: string,
 ): Promise<DocumentProjectSetup> {
-  if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory())
-    throw new Error('Pick a folder that exists.');
+  if (fs.existsSync(folder) && !fs.statSync(folder).isDirectory())
+    throw new Error(`${folder} is a file, not a folder.`);
   const documentPath = withMarkdownExtension(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(
diff --git a/electron/documents/types.ts b/electron/documents/types.ts
index 82e40d11c..c6e18fc2a 100644
--- a/electron/documents/types.ts
+++ b/electron/documents/types.ts
@@ -12,6 +12,8 @@ export interface DocumentFileInfo {
 
 /** 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;
diff --git a/src/components/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index 6f38a6716..083a91221 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -1081,7 +1081,7 @@ export function SettingsDialog(props: SettingsDialogProps) {
               label="Document workspaces"
               checked={store.documentWorkspacesEnabled}
               onChange={setDocumentWorkspacesEnabled}
-              description="Add document projects: a Git repository plus one Markdown document. 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."
+              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."
             />
           </SettingsSection>
           <SettingsSection title="Coordinator">
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index d759dcc8e..e4f288c9d 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -1,4 +1,12 @@
-import { For, Show, createMemo, createSignal } from 'solid-js';
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  onCleanup,
+} from 'solid-js';
 import { Dialog } from '../components/Dialog';
 import { IPC } from '../../electron/ipc/channels';
 import { invoke } from '../lib/ipc';
@@ -16,6 +24,8 @@ interface NewDocumentProjectDialogProps {
 }
 
 const DEFAULT_DOCUMENT = 'notes.md';
+/** Typing a path should not spawn a `git` process per keystroke. */
+const INSPECT_DEBOUNCE_MS = 250;
 
 /** Mirrors the extension the backend appends, so the plan below names the real file. */
 function withMarkdownExtension(value: string): string {
@@ -27,45 +37,78 @@ function preferredDocument(info: DocumentFolderInfo): string {
   return info.files.find((f) => f.committed)?.path ?? info.files[0]?.path ?? DEFAULT_DOCUMENT;
 }
 
+function folderName(folder: string): string {
+  return folder.replace(/\/+$/, '').split('/').pop() ?? folder;
+}
+
 /**
  * Picks a folder and one Markdown document inside it. Neither has to exist
- * yet: the backend initialises the repository, creates the document and makes
- * the first commit, so the only thing asked of the user is where and what.
+ * 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 [info, setInfo] = createSignal<DocumentFolderInfo | null>(null);
   const [name, setName] = createSignal('');
+  const [nameEdited, setNameEdited] = createSignal(false);
   const [filter, setFilter] = createSignal('');
-  const [documentPath, setDocumentPath] = createSignal('');
+  const [documentInput, setDocumentInput] = createSignal('');
+  const [documentEdited, setDocumentEdited] = createSignal(false);
   const [error, setError] = createSignal('');
   const [busy, setBusy] = createSignal(false);
 
+  // Re-inspected as the path is edited; a folder that does not exist yet comes
+  // back empty rather than as an error.
+  const [settledFolder, setSettledFolder] = createSignal('');
+  let settleTimer: ReturnType<typeof setTimeout> | undefined;
+  createEffect(() => {
+    const value = folder().trim();
+    clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => setSettledFolder(value), INSPECT_DEBOUNCE_MS);
+  });
+  onCleanup(() => clearTimeout(settleTimer));
+
+  const [info] = createResource(
+    () => settledFolder() || null,
+    // A path that is still half-typed, or one the app may not read, is simply
+    // "nothing known about it yet"; creating the project reports the real error.
+    (projectRoot) =>
+      invoke<DocumentFolderInfo>(IPC.InspectDocumentFolder, { projectRoot }).catch(() => null),
+  );
+
   const files = () => info()?.files ?? [];
   const visibleFiles = createMemo(() => {
     const q = filter().trim().toLowerCase();
     return q ? files().filter((f) => f.path.toLowerCase().includes(q)) : files();
   });
+  const documentPath = () => {
+    if (documentEdited()) return documentInput();
+    const found = info();
+    return found ? preferredDocument(found) : '';
+  };
+  const projectName = () => (nameEdited() ? name() : folderName(folder().trim()));
 
-  /** What creating the project will do to the folder, so nothing is a surprise. */
+  /** What creating the project will do, so nothing about it is a surprise. */
   const plan = createMemo(() => {
     const current = info();
-    const wanted = withMarkdownExtension(documentPath().trim());
-    if (!current || !documentPath().trim()) return [];
+    const wanted = documentPath().trim();
+    if (!current || !wanted) return [];
     const steps: string[] = [];
+    if (!current.exists) steps.push('create the folder');
     if (!current.isRepo) steps.push('run `git init`');
-    const match = files().find((f) => f.path === wanted);
-    if (!match) steps.push(`create ${wanted}`);
+    const match = files().find((f) => f.path === withMarkdownExtension(wanted));
+    if (!match) steps.push(`create ${withMarkdownExtension(wanted)}`);
     if (!match?.committed) steps.push('make a commit');
     return steps;
   });
 
   function reset() {
     setFolder('');
-    setInfo(null);
     setName('');
+    setNameEdited(false);
     setFilter('');
-    setDocumentPath('');
+    setDocumentInput('');
+    setDocumentEdited(false);
     setError('');
   }
 
@@ -76,33 +119,16 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
 
   async function chooseFolder() {
     const selected = await openDialog({ directory: true, multiple: false });
-    if (!selected) return;
-    const path = selected as string;
-    setBusy(true);
-    setError('');
-    try {
-      const found = await invoke<DocumentFolderInfo>(IPC.InspectDocumentFolder, {
-        projectRoot: path,
-      });
-      if (found.enclosingRepo) {
-        setError(
-          `That folder is inside the Git repository at ${found.enclosingRepo}. ` +
-            'Pick that repository instead, so proposals and history stay in one place.',
-        );
-        return;
-      }
-      setFolder(path);
-      setInfo(found);
-      setName(path.split('/').pop() || path);
-      setDocumentPath(preferredDocument(found));
-    } catch (err) {
-      setError(errMessage(err));
-    } finally {
-      setBusy(false);
-    }
+    if (selected) setFolder(selected as string);
   }
 
-  const canCreate = () => folder() && documentPath().trim() && name().trim() && !busy();
+  const enclosingRepo = () => info()?.enclosingRepo ?? null;
+  const canCreate = () =>
+    folder().trim().startsWith('/') &&
+    documentPath().trim() &&
+    projectName().trim() &&
+    !busy() &&
+    !enclosingRepo();
 
   async function create() {
     if (!canCreate()) return;
@@ -110,10 +136,10 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     setError('');
     try {
       const setup = await invoke<DocumentProjectSetup>(IPC.PrepareDocumentProject, {
-        projectRoot: folder(),
+        projectRoot: folder().trim(),
         documentPath: documentPath().trim(),
       });
-      const id = addDocumentProject(name().trim(), folder(), setup.documentPath);
+      const id = addDocumentProject(projectName().trim(), folder().trim(), setup.documentPath);
       if (setup.actions.length > 0) showNotification(setup.actions.join(' · '));
       close();
       await openDocumentWorkspace(id);
@@ -147,35 +173,41 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
         <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
           <span style={sectionLabelStyle}>Folder</span>
           <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
+            <input
+              style={{ ...inputStyle, 'font-family': 'var(--font-mono)', 'font-size': '12px' }}
+              aria-label="Project folder"
+              placeholder="/path/to/folder"
+              value={folder()}
+              onInput={(e) => setFolder(e.currentTarget.value)}
+            />
             <button
               type="button"
               class="docws-btn"
               onClick={() => void chooseFolder()}
               disabled={busy()}
             >
-              {folder() ? 'Change folder…' : 'Choose folder…'}
+              Browse…
             </button>
-            <span
-              style={{
-                'font-family': 'var(--font-mono)',
-                'font-size': '12px',
-                color: theme.fgMuted,
-                overflow: 'hidden',
-                'text-overflow': 'ellipsis',
-                'white-space': 'nowrap',
-              }}
-            >
-              {folder()}
-            </span>
           </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()}>
+        <Show when={folder().trim()}>
           <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
             <span style={sectionLabelStyle}>Name</span>
             <input
               style={inputStyle}
-              value={name()}
-              onInput={(e) => setName(e.currentTarget.value)}
+              value={projectName()}
+              onInput={(e) => {
+                setNameEdited(true);
+                setName(e.currentTarget.value);
+              }}
             />
           </div>
           <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
@@ -185,7 +217,10 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
               aria-label="Document path"
               placeholder={DEFAULT_DOCUMENT}
               value={documentPath()}
-              onInput={(e) => setDocumentPath(e.currentTarget.value)}
+              onInput={(e) => {
+                setDocumentEdited(true);
+                setDocumentInput(e.currentTarget.value);
+              }}
             />
             <Show when={files().length > 8}>
               <input
@@ -204,7 +239,10 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
                       role="option"
                       class="docws-picker-item"
                       aria-selected={documentPath() === file.path}
-                      onClick={() => setDocumentPath(file.path)}
+                      onClick={() => {
+                        setDocumentEdited(true);
+                        setDocumentInput(file.path);
+                      }}
                     >
                       {file.path}
                       <Show when={!file.committed}>
@@ -222,6 +260,12 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
             </Show>
           </div>
         </Show>
+        <Show when={enclosingRepo()}>
+          <div class="docws-error" style={{ 'font-size': '13px' }}>
+            That folder is inside the Git repository at {enclosingRepo()}. Pick that repository
+            instead, so proposals and history stay in one place.
+          </div>
+        </Show>
         <Show when={error()}>
           <div class="docws-error" style={{ 'font-size': '13px' }}>
             {error()}

From 83668164a83b34b9dd4c8ecdc2c0ed381c176a4e Mon Sep 17 00:00:00 2001
From: Johannes Millan <johannes.millan@gmail.com>
Date: Fri, 4 Sep 2026 10:39:39 +0200
Subject: [PATCH 07/12] feat(documents): offer the project kinds instead of
 asking in a native modal

Enabling document workspaces put a native message box in front of every
project add, code ones included. It was titled "Confirm", used a dialog system
the app does not control, and its Escape cancelled the whole add rather than
the question. The + button now opens an in-app menu with the two kinds; with
the flag off it goes straight to the folder picker as it always did.

Document rows carry the document glyph instead of the colour dot, so a row
that opens a full-window workspace no longer looks exactly like one that opens
project settings.

Fixes found while reviewing the entry points:

- Enter on a focused project row always opened Edit Project, so keyboard users
  got branch prefixes and verify commands for a document project. Both the
  click and key paths now go through one openProjectRow.
- The New Task button and the empty-state layout counted every project, so a
  user whose only project was a document project was offered a task flow with
  no project to run it in.
- openDocumentWorkspace ignored documentWorkspacesEnabled, so turning the
  experiment off left the rows live.
- EditProjectDialog gated branch and worktree settings on isGitRepo, which a
  document project sets true; it now gates on whether tasks run there.
- The dialog's "that folder is inside the repository at X" dead end is a
  button that switches to X, instead of prose telling the user to start over.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 docs/document-workspaces.md                |   9 +-
 src/components/AddProjectMenu.tsx          | 114 +++++++++++++++++++++
 src/components/EditProjectDialog.tsx       |   8 +-
 src/components/IconButton.tsx              |   2 +-
 src/components/SettingsDialog.tsx          |   2 +-
 src/components/Sidebar.tsx                 |  93 ++++++++++-------
 src/components/TilingLayout.tsx            |   3 +-
 src/documents/DocumentIcon.tsx             |  19 ++++
 src/documents/DocumentWorkspaceOverlay.tsx |  20 +---
 src/documents/NewDocumentProjectDialog.tsx |  28 ++++-
 src/documents/store.ts                     |   2 +-
 11 files changed, 232 insertions(+), 68 deletions(-)
 create mode 100644 src/components/AddProjectMenu.tsx
 create mode 100644 src/documents/DocumentIcon.tsx

diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
index 19de31266..41629961b 100644
--- a/docs/document-workspaces.md
+++ b/docs/document-workspaces.md
@@ -24,7 +24,7 @@ the document.
 ### Using it
 
 1. Enable _Document workspaces_ under Settings → Experimental.
-2. Click **+** next to Projects and choose **Document project**. Type or browse to a
+2. Click **+** next to Projects and choose **Document project…**. Type or browse to a
    folder and name the document. Neither has to exist: type a new name onto the end of the
    path and that folder is the project. The dialog says what it will do — create the
    folder, `git init`, create the file, make the first commit — and does it on confirm.
@@ -106,9 +106,10 @@ workspace-write` (the sandbox blocks writes outside the worktree),
 - **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
-  three lines: `registerDocumentHandlers(win)` and `stopAllDocumentWork()` in main,
-  `<DocumentWorkspaceOverlay />` in `App.tsx`. The one runtime module the renderer imports
-  across the process boundary is `electron/documents/shared.ts`.
+  `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
 
diff --git a/src/components/AddProjectMenu.tsx b/src/components/AddProjectMenu.tsx
new file mode 100644
index 000000000..4a8170b71
--- /dev/null
+++ b/src/components/AddProjectMenu.tsx
@@ -0,0 +1,114 @@
+import { onCleanup, onMount } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { theme } from '../lib/theme';
+import { sf } from '../lib/fontScale';
+import { DocumentIcon } from '../documents/DocumentIcon';
+
+export type ProjectKindChoice = 'code' | 'document';
+
+interface AddProjectMenuProps {
+  /** Viewport coordinates of the "+" button this hangs from. */
+  anchor: { left: number; top: number };
+  onPick: (kind: ProjectKindChoice) => void;
+  onClose: () => void;
+}
+
+const MENU_WIDTH = 232;
+
+/**
+ * The two project kinds, offered rather than asked. This replaces a native
+ * message box: that blocked the window to pose a question in a dialog system
+ * the app does not control, and its Escape cancelled the whole add instead of
+ * backing out of the question.
+ */
+export function AddProjectMenu(props: AddProjectMenuProps) {
+  onMount(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        props.onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey, true);
+    onCleanup(() => window.removeEventListener('keydown', onKey, true));
+  });
+
+  const row = (kind: ProjectKindChoice, icon: () => unknown, label: string, hint: string) => (
+    <button
+      type="button"
+      onClick={() => props.onPick(kind)}
+      style={{
+        display: 'flex',
+        'align-items': 'flex-start',
+        gap: '9px',
+        padding: '8px 10px',
+        background: 'transparent',
+        border: 'none',
+        'border-radius': 'var(--radius-sm)',
+        color: theme.fg,
+        cursor: 'pointer',
+        'text-align': 'left',
+        font: 'inherit',
+      }}
+      onMouseEnter={(e) => (e.currentTarget.style.background = theme.bgHover)}
+      onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+    >
+      <span style={{ color: theme.fgMuted, 'margin-top': '1px', 'flex-shrink': '0' }}>
+        {icon() as never}
+      </span>
+      <span style={{ display: 'flex', 'flex-direction': 'column', gap: '1px', 'min-width': '0' }}>
+        <span style={{ 'font-size': sf(12), 'font-weight': '500' }}>{label}</span>
+        <span style={{ 'font-size': sf(11), color: theme.fgMuted }}>{hint}</span>
+      </span>
+    </button>
+  );
+
+  return (
+    <Portal>
+      <div
+        onClick={() => props.onClose()}
+        onContextMenu={() => props.onClose()}
+        style={{ position: 'fixed', inset: '0', 'z-index': '1200' }}
+      >
+        <div
+          role="menu"
+          aria-label="Add project"
+          onClick={(e) => e.stopPropagation()}
+          style={{
+            position: 'fixed',
+            left: `${props.anchor.left}px`,
+            top: `${props.anchor.top}px`,
+            width: `${MENU_WIDTH}px`,
+            background: theme.bgElevated,
+            border: `1px solid ${theme.border}`,
+            'border-radius': 'var(--radius-md)',
+            'box-shadow': '0 6px 20px rgba(0, 0, 0, 0.35)',
+            padding: '4px',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '1px',
+          }}
+        >
+          {row(
+            'code',
+            () => (
+              <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M1.5 3.25A1.75 1.75 0 0 1 3.25 1.5h2.9c.46 0 .9.18 1.23.51l.86.86h4.51c.97 0 1.75.78 1.75 1.75v7.63c0 .97-.78 1.75-1.75 1.75H3.25a1.75 1.75 0 0 1-1.75-1.75z" />
+              </svg>
+            ),
+            'Code project…',
+            'A git repo that holds tasks',
+          )}
+          {row(
+            'document',
+            () => (
+              <DocumentIcon size={14} />
+            ),
+            'Document project…',
+            'A folder with one Markdown document',
+          )}
+        </div>
+      </div>
+    </Portal>
+  );
+}
diff --git a/src/components/EditProjectDialog.tsx b/src/components/EditProjectDialog.tsx
index b6b664b66..d6bb731b0 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 showsTaskSettings = () =>
+    props.project?.isGitRepo !== false && !isDocumentProject(props.project ?? undefined);
   let nameRef!: HTMLInputElement;
 
   // Sync signals when project prop changes
@@ -242,7 +246,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 +329,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={{
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/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index 083a91221..13e9372af 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -1081,7 +1081,7 @@ export function SettingsDialog(props: SettingsDialogProps) {
               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."
+              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">
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index 48d031755..853721ce1 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -42,8 +42,9 @@ import { RemoveProjectConfirm } from './RemoveProjectConfirm';
 import { EditProjectDialog } from './EditProjectDialog';
 import { NewDocumentProjectDialog } from '../documents/NewDocumentProjectDialog';
 import { openDocumentWorkspace } from '../documents/store';
-import { isDocumentProject } from '../store/projects';
-import { choice } from '../lib/dialog';
+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';
@@ -600,20 +601,26 @@ export function Sidebar() {
   });
 
   const [showNewDocumentProject, setShowNewDocumentProject] = createSignal(false);
+  const [addMenuAt, setAddMenuAt] = createSignal<{ left: number; top: number } | null>(null);
 
-  async function handleAddProject() {
-    if (store.documentWorkspacesEnabled) {
-      const picked = await choice('What kind of project?', {
-        buttons: ['Code project', 'Document project', 'Cancel'],
-        defaultId: 0,
-        cancelId: 2,
-      });
-      if (picked === 2) return;
-      if (picked === 1) {
-        setShowNewDocumentProject(true);
-        return;
-      }
+  /** 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;
 
@@ -848,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"
             />
@@ -880,16 +887,10 @@ export function Sidebar() {
                       tabIndex={0}
                       class="project-row"
                       data-project-id={project.id}
-                      onClick={() => {
-                        if (isDocumentProject(project) && !isProjectMissing(project.id))
-                          void openDocumentWorkspace(project.id);
-                        else setEditingProject(project);
-                      }}
+                      onClick={() => openProjectRow(project)}
                       onKeyDown={(e) => {
                         if (e.key !== 'Enter') return;
-                        if (isDocumentProject(project) && !isProjectMissing(project.id))
-                          void openDocumentWorkspace(project.id);
-                        else setEditingProject(project);
+                        openProjectRow(project);
                       }}
                       title={
                         isProjectMissing(project.id)
@@ -913,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',
@@ -984,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}`,
@@ -1058,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;
@@ -1175,6 +1185,19 @@ 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)}
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/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/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 191728d69..f78e95e0e 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -26,25 +26,7 @@ import { HistoryView } from './HistoryView';
 import { RunComposer } from './RunComposer';
 import { RunsRail } from './RunsRail';
 import { createRenderedBlocks } from './use-blocks';
-
-function DocumentIcon() {
-  return (
-    <svg
-      width="18"
-      height="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>
-  );
-}
+import { DocumentIcon } from './DocumentIcon';
 
 function DocumentPane() {
   let docRef: HTMLDivElement | undefined;
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index e4f288c9d..647169170 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -261,10 +261,30 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
           </div>
         </Show>
         <Show when={enclosingRepo()}>
-          <div class="docws-error" style={{ 'font-size': '13px' }}>
-            That folder is inside the Git repository at {enclosingRepo()}. Pick that repository
-            instead, so proposals and history stay in one place.
-          </div>
+          {(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' }}>
diff --git a/src/documents/store.ts b/src/documents/store.ts
index a902b81f2..425250a1e 100644
--- a/src/documents/store.ts
+++ b/src/documents/store.ts
@@ -154,7 +154,7 @@ export async function loadDocumentRuns(): Promise<void> {
 
 export async function openDocumentWorkspace(projectId: string): Promise<void> {
   const project = getProject(projectId);
-  if (!project?.documentPath) return;
+  if (!project?.documentPath || !store.documentWorkspacesEnabled) return;
   const previous = docStore.projectId;
   if (previous && previous !== projectId) {
     void invoke(IPC.StopDocumentWatcher, { key: watcherKey(previous) }).catch(() => undefined);

From 8e5bf902dea8c0f672a90a1242edf92e171372f0 Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Fri, 4 Sep 2026 11:01:59 +0200
Subject: [PATCH 08/12] fix(test): keep git hook env from redirecting tests at
 the real repo
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Git exports GIT_DIR and GIT_INDEX_FILE into every hook environment. `npm
test` from .husky/pre-push handed them to each vitest worker, so a `git`
a test spawned inherited them and acted on the developer's checkout rather
than its own temp folder: `git init` re-initialised the real repository,
fixture commits landed on the branch being pushed, and the index was
clobbered — leaving the working tree reading as entirely untracked.

vitest.setup.ts scrubs the repo-pointing GIT_* vars for both suites, so the
suite is hermetic under any git-invoked context, not just this one hook.
electron/test-env.test.ts guards the invariant; both assertions fail without
the scrub. It checks --absolute-git-dir rather than --show-toplevel, since
an inherited GIT_DIR still leaves the work tree at cwd.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 electron/test-env.test.ts | 38 ++++++++++++++++++++++++++++++++++++++
 vitest.client.config.ts   |  1 +
 vitest.config.ts          |  1 +
 vitest.setup.ts           | 22 ++++++++++++++++++++++
 4 files changed, 62 insertions(+)
 create mode 100644 electron/test-env.test.ts
 create mode 100644 vitest.setup.ts

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/vitest.client.config.ts b/vitest.client.config.ts
index aba8afc58..879e11e60 100644
--- a/vitest.client.config.ts
+++ b/vitest.client.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
   plugins: [solidPlugin({ ssr: false })],
   test: {
     environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.ts'],
     include: ['src/**/*.client.test.tsx'],
   },
 });
diff --git a/vitest.config.ts b/vitest.config.ts
index 76649cd9a..d7962d0dc 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,6 +5,7 @@ export default defineConfig({
   plugins: [solidPlugin({ ssr: true })],
   test: {
     environment: 'node',
+    setupFiles: ['./vitest.setup.ts'],
     include: ['src/**/*.test.ts', 'electron/**/*.test.ts', 'scripts/**/*.test.mjs'],
     coverage: {
       provider: 'v8',
diff --git a/vitest.setup.ts b/vitest.setup.ts
new file mode 100644
index 000000000..c6489feb8
--- /dev/null
+++ b/vitest.setup.ts
@@ -0,0 +1,22 @@
+/**
+ * Git exports `GIT_DIR`, `GIT_INDEX_FILE` and friends into the environment of
+ * every hook it runs. `npm test` from `.husky/pre-push` therefore hands those
+ * to each vitest worker, and any `git` a test spawns inherits them — so tests
+ * that build a repository in a temp folder silently operate on the developer's
+ * real checkout instead, committing fixtures onto their branch and clobbering
+ * their index. Scrubbing them here keeps the suite hermetic whatever invoked it.
+ */
+const REPO_POINTING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_PREFIX',
+  'GIT_QUARANTINE_PATH',
+  'GIT_CEILING_DIRECTORIES',
+] as const;
+
+for (const name of REPO_POINTING_VARS) Reflect.deleteProperty(process.env, name);

From 12e7668b2153350c03ad6905e72d766749abb01a Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Fri, 4 Sep 2026 11:09:17 +0200
Subject: [PATCH 09/12] fix(documents): carve header controls out of the window
 drag region
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

.docws-overlay is fixed at inset:0, so the workspace paints over the window
titlebar. main.ts injects `[data-tauri-drag-region] button { no-drag }`, but
that only reaches descendants of the drag region, and the overlay is a
sibling of the titlebar rather than a child. Chromium unions drag rects and
subtracts no-drag rects irrespective of DOM nesting, so the top band stayed
draggable and swallowed clicks landing in it — the tabs and the Project and
Close buttons sit at roughly y=10-38, straight through the 34px band on
Linux and the 32px one on macOS.

Only the controls are carved out, not the whole header: while the workspace
is open it covers the real titlebar, so the header is the only handle left
for moving the window.

Matches the existing precedent for the focus-mode pills at styles.css:2096.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 src/documents/documents.css | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/documents/documents.css b/src/documents/documents.css
index 3e78f3246..5f0c16f6e 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -23,6 +23,18 @@
   min-width: 0;
 }
 
+/* The overlay is fixed at inset:0, so it sits on top of the window titlebar and
+   its [data-tauri-drag-region] — a sibling, not an ancestor, so main.ts's
+   injected `[data-tauri-drag-region] button { no-drag }` rule cannot reach
+   these. Without the carve-out the OS drag region swallows every click in the
+   top ~34px, which is exactly where the header's tabs and buttons sit. The rest
+   of the header stays draggable on purpose: while the workspace is open it is
+   the only handle left for moving the window. */
+.docws-header .docws-tab,
+.docws-header .docws-btn {
+  -webkit-app-region: no-drag;
+}
+
 .docws-title {
   display: flex;
   align-items: center;

From e7a44160fd14c856428115d8084825c6e1fa755e Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Fri, 4 Sep 2026 11:26:55 +0200
Subject: [PATCH 10/12] feat(documents): improve workspace header controls

Add a document editor shortcut and make the full header background a predictable window drag surface while keeping controls interactive.
---
 .../DocumentWorkspaceOverlay.client.test.tsx  | 99 +++++++++++++++++++
 src/documents/DocumentWorkspaceOverlay.tsx    | 34 ++++++-
 src/documents/documents.css                   | 24 +++--
 3 files changed, 147 insertions(+), 10 deletions(-)
 create mode 100644 src/documents/DocumentWorkspaceOverlay.client.test.tsx

diff --git a/src/documents/DocumentWorkspaceOverlay.client.test.tsx b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
new file mode 100644
index 000000000..c1140346a
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.client.test.tsx
@@ -0,0 +1,99 @@
+import { render } from 'solid-js/web';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { setStore } from '../store/core';
+import { DocumentWorkspaceOverlay } from './DocumentWorkspaceOverlay';
+
+const { openInEditor } = vi.hoisted(() => ({
+  openInEditor: vi.fn(() => Promise.resolve()),
+}));
+
+vi.mock('../lib/shell', () => ({ openInEditor }));
+
+const disposers: Array<() => void> = [];
+
+afterEach(() => {
+  while (disposers.length > 0) disposers.pop()?.();
+  document.body.replaceChildren();
+  setStore({ projects: [], activeDocumentProjectId: null, editorCommand: '' });
+  vi.clearAllMocks();
+});
+
+describe('DocumentWorkspaceOverlay', () => {
+  it('uses the entire title-bar background as the window drag region', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const header = host.querySelector<HTMLElement>('.docws-header');
+
+    expect(header?.hasAttribute('data-tauri-drag-region')).toBe(true);
+  });
+
+  it('opens the document in the configured editor from the title', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'docs/notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+      editorCommand: 'code',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Open docs/notes.md in code"]',
+    );
+    expect(button).not.toBeNull();
+
+    button?.click();
+
+    expect(openInEditor).toHaveBeenCalledWith('code', '/projects/release/docs/notes.md');
+  });
+
+  it('keeps the editor button visible but disabled until an editor is configured', () => {
+    setStore({
+      projects: [
+        {
+          id: 'docs',
+          name: 'Release notes',
+          path: '/projects/release',
+          color: '',
+          kind: 'document',
+          documentPath: 'notes.md',
+        },
+      ],
+      activeDocumentProjectId: 'docs',
+      editorCommand: '',
+    });
+    const host = document.createElement('div');
+    document.body.append(host);
+    disposers.push(render(() => <DocumentWorkspaceOverlay />, host));
+
+    const button = host.querySelector<HTMLButtonElement>(
+      'button[aria-label="Configure an editor command in Settings to open notes.md"]',
+    );
+
+    expect(button?.disabled).toBe(true);
+  });
+});
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index f78e95e0e..0c469562e 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -27,6 +27,9 @@ import { RunComposer } from './RunComposer';
 import { RunsRail } from './RunsRail';
 import { createRenderedBlocks } from './use-blocks';
 import { DocumentIcon } from './DocumentIcon';
+import { openInEditor } from '../lib/shell';
+import { errMessage } from '../lib/log';
+import { showNotification } from '../store/notification';
 
 function DocumentPane() {
   let docRef: HTMLDivElement | undefined;
@@ -248,6 +251,13 @@ export function DocumentWorkspaceOverlay() {
   const compareRun = () =>
     documentStore.compareRunId ? documentStore.runs[documentStore.compareRunId] : undefined;
   const reviewable = createMemo(() => reviewableRuns());
+  const editorCommand = () => store.editorCommand.trim();
+  const editorButtonLabel = () => {
+    const documentPath = project()?.documentPath ?? '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(() => {
@@ -258,6 +268,16 @@ export function DocumentWorkspaceOverlay() {
     if (documentStore.projectId) closeDocumentWorkspace();
   });
 
+  function openDocumentInEditor() {
+    const currentProject = project();
+    const command = editorCommand();
+    if (!currentProject?.documentPath || !command) return;
+    const documentPath = `${currentProject.path.replace(/\/$/, '')}/${currentProject.documentPath}`;
+    openInEditor(command, documentPath).catch((err) =>
+      showNotification(`Editor failed: ${errMessage(err)}`),
+    );
+  }
+
   function tab(view: DocumentView, label: string, count?: number) {
     return (
       <button
@@ -281,10 +301,22 @@ export function DocumentWorkspaceOverlay() {
 
   return (
     <div class="docws-overlay" role="dialog" aria-label="Document workspace">
-      <div class="docws-header">
+      <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() || !project()?.documentPath}
+            onClick={() => void openDocumentInEditor()}
+          >
+            <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+              <path d="M3.5 2a1.5 1.5 0 0 0-1.5 1.5v9A1.5 1.5 0 0 0 3.5 14h9a1.5 1.5 0 0 0 1.5-1.5v-3a.75.75 0 0 1 1.5 0v3A3 3 0 0 1 12.5 16h-9A3 3 0 0 1 0 12.5v-9A3 3 0 0 1 3.5 0h3a.75.75 0 0 1 0 1.5h-3ZM10 .75a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 .75.75v4.5a.75.75 0 0 1-1.5 0V2.56L8.53 8.53a.75.75 0 0 1-1.06-1.06L13.44 1.5H10.75A.75.75 0 0 1 10 .75Z" />
+            </svg>
+          </button>
         </div>
         <span class="docws-subtitle" title={project()?.documentPath}>
           {project()?.documentPath}
diff --git a/src/documents/documents.css b/src/documents/documents.css
index 5f0c16f6e..57cf8e840 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -19,19 +19,20 @@
   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 overlay is fixed at inset:0, so it sits on top of the window titlebar and
-   its [data-tauri-drag-region] — a sibling, not an ancestor, so main.ts's
-   injected `[data-tauri-drag-region] button { no-drag }` rule cannot reach
-   these. Without the carve-out the OS drag region swallows every click in the
-   top ~34px, which is exactly where the header's tabs and buttons sit. The rest
-   of the header stays draggable on purpose: while the workspace is open it is
-   the only handle left for moving the window. */
-.docws-header .docws-tab,
-.docws-header .docws-btn {
+/* 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;
 }
 
@@ -49,6 +50,11 @@
   flex-shrink: 0;
 }
 
+.docws-open-editor {
+  padding: 4px;
+  flex-shrink: 0;
+}
+
 .docws-subtitle {
   font-family: var(--font-mono);
   font-size: 12px;

From d5e4876ec83e424325a46d35e7f4455cf28e20a9 Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Fri, 4 Sep 2026 11:45:25 +0200
Subject: [PATCH 11/12] feat(documents): preview HTML documents instead of
 mangling them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A document that is a whole HTML page cannot survive the markdown path.
marked splits HTML blocks at blank lines per CommonMark, so a page is
chopped into fragments; indented markup trips the four-space code rule; and
DOMPurify strips <style>, <head> and the doctype by design, which leaves the
first block empty and spills the page's CSS out as a paragraph. The result
read as "HTML rendering is broken" when the renderer was in fact working
exactly as specified on input that was never markdown.

Detect a real document preamble — a doctype or <html>, past any comments —
and render those in a fully sandboxed iframe, so the page appears with its
own stylesheet. sandbox="" allows CSS but no scripts, forms or same-origin
access to the app. A Preview/Blocks toggle keeps the block list one click
away, since selection and agent scoping are built on it; the block view stays
mounted behind the preview so blocks, annotations and scroll position survive
the switch.

Markdown containing HTML fragments is untouched and keeps the block view.

Claude-Session: https://claude.ai/code/session_01HG5Ape4rpESujEixxzhwgL
---
 src/documents/DocumentWorkspaceOverlay.tsx | 51 +++++++++++++++++++---
 src/documents/documents.css                | 16 +++++++
 src/documents/html-document.test.ts        | 29 ++++++++++++
 src/documents/html-document.ts             | 11 +++++
 4 files changed, 102 insertions(+), 5 deletions(-)
 create mode 100644 src/documents/html-document.test.ts
 create mode 100644 src/documents/html-document.ts

diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index 0c469562e..f1d9f5938 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -16,6 +16,7 @@ import {
   type DocumentView,
 } from './store';
 import { relocateAnchor } from './annotation-anchor';
+import { isHtmlDocument } from './html-document';
 import type { DocumentAnnotation } from './types';
 import { AnnotationBubble } from './AnnotationBubble';
 import { EditProjectDialog } from '../components/EditProjectDialog';
@@ -119,7 +120,15 @@ function DocumentPane() {
     }),
   );
 
+  // A whole HTML page cannot survive the markdown path: marked splits it at
+  // blank lines and the sanitizer drops <style>, so it renders as debris. Show
+  // it as the page it is, and keep the block view one click away for scoping.
+  const isHtml = createMemo(() => isHtmlDocument(documentStore.snapshot?.content));
+  const [htmlView, setHtmlView] = createSignal<'preview' | 'blocks'>('preview');
+  const showsPreview = () => isHtml() && htmlView() === 'preview';
+
   const toolbarLabel = () => {
+    if (showsPreview()) return 'Preview of the HTML document — switch to Blocks to scope a task';
     const s = selection();
     if (!s) return 'Select text, click a block, or use § on a heading to scope a task';
     return s.wholeDocument
@@ -145,6 +154,26 @@ function DocumentPane() {
     <>
       <div class="docws-main">
         <div class="docws-toolbar">
+          <Show when={isHtml()}>
+            <span class="docws-tabs">
+              <button
+                type="button"
+                class="docws-tab"
+                aria-selected={htmlView() === 'preview'}
+                onClick={() => setHtmlView('preview')}
+              >
+                Preview
+              </button>
+              <button
+                type="button"
+                class="docws-tab"
+                aria-selected={htmlView() === 'blocks'}
+                onClick={() => setHtmlView('blocks')}
+              >
+                Blocks
+              </button>
+            </span>
+          </Show>
           <span>{toolbarLabel()}</span>
           <Show when={documentStore.lastDeleted}>
             <span class="docws-undo">
@@ -169,10 +198,12 @@ function DocumentPane() {
               {resolvedCount()} resolved
             </label>
           </Show>
-          <button type="button" class="docws-btn docws-btn-sm" onClick={selectWholeDocument}>
-            Whole document
-          </button>
-          <Show when={selection()}>
+          <Show when={!showsPreview()}>
+            <button type="button" class="docws-btn docws-btn-sm" onClick={selectWholeDocument}>
+              Whole document
+            </button>
+          </Show>
+          <Show when={selection() && !showsPreview()}>
             <button
               type="button"
               class="docws-btn docws-btn-sm"
@@ -185,7 +216,17 @@ function DocumentPane() {
         <Show when={documentStore.snapshot?.missing}>
           <div class="docws-older-banner">The document file is missing from the checkout.</div>
         </Show>
-        <div class="docws-doc" ref={docRef}>
+        <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>
+        <div class="docws-doc" ref={docRef} classList={{ 'is-hidden': showsPreview() }}>
           <Show when={placed().detached.length > 0}>
             <div class="docws-detached-section">
               <div class="docws-rail-title">Detached notes</div>
diff --git a/src/documents/documents.css b/src/documents/documents.css
index 57cf8e840..22e0da0ad 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -207,6 +207,22 @@
   padding: 28px 44px 200px;
 }
 
+/* Kept mounted while previewing so blocks, annotations and scroll position
+   survive the toggle; re-rendering them on every switch is wasted work. */
+.docws-doc.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 .doc-block {
   position: relative;
   border-radius: var(--radius-sm);
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);
+}

From ff6c1cbd07f874ecd54713c87de564664a41083d Mon Sep 17 00:00:00 2001
From: Test <test@example.com>
Date: Fri, 4 Sep 2026 12:21:26 +0200
Subject: [PATCH 12/12] feat(documents): improve workspace UI

- Fold the branch/head status strip into header chips; errors become a
  banner under the header
- Render the run composer in the document flow under the selected block
  (or above the document for a whole-document task) as one instance that
  moves between passages, so the instruction and agent picks survive a
  change of selection and the prose after it is never covered
- Render annotation bubbles after their block rather than inside it, so
  clicking a bubble no longer toggles the block selection
- Toolbar: singular "Selected line N"; the resolved toggle appears only
  once something is resolved
- Rail: mark the accepted candidate and dim the ones not chosen or
  rejected
- Compare: open every column on its first change or the scoped passage,
  cap the rationale height, and give the empty state a title, a hint and
  a way back to the document
- Project dialog: hide worktree, verify, coverage and bookmark settings
  for document projects; new-project plan reads as a sentence
- History: diff the root commit against the empty tree instead of
  showing "No source changes"
- Headless parser: report the CLI's `errors`/`subtype` detail instead of
  a generic "agent reported an error"

Claude-Session: https://claude.ai/code/session_01HtLDFZmcK6ASGvVy2YX5rr
---
 electron/documents/agents.test.ts           |  23 ++
 electron/documents/agents.ts                |  14 +-
 electron/documents/runs.integration.test.ts |   6 +
 electron/documents/runs.ts                  |  10 +-
 src/components/EditProjectDialog.tsx        | 348 ++++++++++----------
 src/documents/CompareView.tsx               |  27 +-
 src/documents/DocumentViewer.tsx            |  61 ++--
 src/documents/DocumentWorkspaceOverlay.tsx  | 149 ++++++---
 src/documents/NewDocumentProjectDialog.tsx  |  17 +-
 src/documents/RunComposer.tsx               |   7 +-
 src/documents/RunsRail.tsx                  |  32 +-
 src/documents/documents.css                 |  85 ++++-
 12 files changed, 496 insertions(+), 283 deletions(-)

diff --git a/electron/documents/agents.test.ts b/electron/documents/agents.test.ts
index 500f7e96d..febae1806 100644
--- a/electron/documents/agents.test.ts
+++ b/electron/documents/agents.test.ts
@@ -105,6 +105,29 @@ describe('claude stream-json parser', () => {
     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');
diff --git a/electron/documents/agents.ts b/electron/documents/agents.ts
index 11bed2510..d217616be 100644
--- a/electron/documents/agents.ts
+++ b/electron/documents/agents.ts
@@ -177,7 +177,19 @@ class ClaudeStreamParser implements HeadlessOutputParser {
         const text = asString(event.result);
         if (text) this.result = text;
         if (event.is_error === true) {
-          this.error = text ?? asString(event.error) ?? 'agent reported an error';
+          // 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 [];
       }
diff --git a/electron/documents/runs.integration.test.ts b/electron/documents/runs.integration.test.ts
index 3e3b56a06..d147fba7d 100644
--- a/electron/documents/runs.integration.test.ts
+++ b/electron/documents/runs.integration.test.ts
@@ -115,6 +115,12 @@ describe('document workspace lifecycle', () => {
     });
   });
 
+  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);
diff --git a/electron/documents/runs.ts b/electron/documents/runs.ts
index 60f3f3047..48433c9b6 100644
--- a/electron/documents/runs.ts
+++ b/electron/documents/runs.ts
@@ -1257,6 +1257,9 @@ export async function getDocumentAtCommit(
   }
 }
 
+/** 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,
@@ -1267,8 +1270,11 @@ export async function getDocumentDiff(
   try {
     return await git(projectRoot, ['diff', '-U3', `${from}..${to}`, '--', documentPath]);
   } catch {
-    // Root commit: nothing to diff against.
-    return '';
+    // `<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(
+      () => '',
+    );
   }
 }
 
diff --git a/src/components/EditProjectDialog.tsx b/src/components/EditProjectDialog.tsx
index d6bb731b0..97e2caae9 100644
--- a/src/components/EditProjectDialog.tsx
+++ b/src/components/EditProjectDialog.tsx
@@ -34,8 +34,8 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
   const [showImportDialog, setShowImportDialog] = createSignal(false);
   const [confirmRemove, setConfirmRemove] = createSignal(false);
   /** Branch and worktree settings only mean something where tasks run. */
-  const showsTaskSettings = () =>
-    props.project?.isGitRepo !== false && !isDocumentProject(props.project ?? undefined);
+  const isDocument = () => isDocumentProject(props.project ?? undefined);
+  const showsTaskSettings = () => props.project?.isGitRepo !== false && !isDocument();
   let nameRef!: HTMLInputElement;
 
   // Sync signals when project prop changes
@@ -134,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)}
@@ -390,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/documents/CompareView.tsx b/src/documents/CompareView.tsx
index 0ce589e20..9f255e042 100644
--- a/src/documents/CompareView.tsx
+++ b/src/documents/CompareView.tsx
@@ -5,6 +5,7 @@ import {
   createMemo,
   createResource,
   createSignal,
+  on,
   untrack,
 } from 'solid-js';
 import { IPC } from '../../electron/ipc/channels';
@@ -49,6 +50,14 @@ function scopeRange(blocks: readonly DocumentBlock[], run: DocumentRunRecord): B
   return start === -1 ? null : { start, end };
 }
 
+/** Scroll a column so its first block matching `selector` sits in the upper third. */
+function revealFirst(body: HTMLElement | undefined, selector: string): void {
+  const target = body?.querySelector<HTMLElement>(selector);
+  if (!body || !target) return;
+  const offset = target.getBoundingClientRect().top - body.getBoundingClientRect().top;
+  body.scrollTop += offset - body.clientHeight / 3;
+}
+
 function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: number }) {
   const [cursor, setCursor] = createSignal(-1);
   function go(delta: number) {
@@ -145,6 +154,13 @@ function CandidateColumn(props: {
   createEffect(() => {
     if (rendered.blocks().length > 0) props.onBaseChanges(props.candidate.id, blockDiff().base);
   });
+  // Open on the first changed block: the decision is there, not at the title.
+  createEffect(
+    on(changedCount, (count) => {
+      if (count === 0) return;
+      requestAnimationFrame(() => revealFirst(bodyRef, '.doc-block:not([data-change="same"])'));
+    }),
+  );
   const [diff] = createResource(
     () =>
       props.showSource && props.candidate.commitSha
@@ -244,6 +260,7 @@ function CandidateColumn(props: {
 
 /** Base on the left, candidates to the right, each opening with its rationale. */
 export function CompareView(props: { run: DocumentRunRecord }) {
+  let baseBodyRef: HTMLDivElement | undefined;
   const [revealAgents, setRevealAgents] = createSignal(false);
   const [showSource, setShowSource] = createSignal(false);
   const [baseContent] = createResource(
@@ -264,6 +281,14 @@ export function CompareView(props: { run: DocumentRunRecord }) {
       return 'same';
     });
   });
+  // The base opens on the passage the run was scoped to, level with the candidates.
+  createEffect(
+    on([scope, () => base.blocks().length], () => {
+      requestAnimationFrame(() =>
+        revealFirst(baseBodyRef, '.doc-block.is-scope, .doc-block:not([data-change="same"])'),
+      );
+    }),
+  );
   const scopeText = () => {
     const s = props.run.scope;
     if (s.wholeDocument) return 'whole document';
@@ -317,7 +342,7 @@ export function CompareView(props: { run: DocumentRunRecord }) {
               </div>
             </div>
           </div>
-          <div class="docws-column-body">
+          <div class="docws-column-body" ref={baseBodyRef}>
             <DocumentViewer
               blocks={base.blocks()}
               scope={scope()}
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
index f71fbe113..16e9ff4e8 100644
--- a/src/documents/DocumentViewer.tsx
+++ b/src/documents/DocumentViewer.tsx
@@ -22,9 +22,8 @@ interface DocumentViewerProps {
   /** Unique key for mermaid ids. */
   renderKey: string;
   onContainer?: (el: HTMLDivElement) => void;
-  /** Rendered after the block with this index (annotation bubbles). */
+  /** Rendered after the block with this index (annotation bubbles, the composer). */
   afterBlock?: (index: number) => JSX.Element;
-  children?: JSX.Element;
 }
 
 export function selectionFromRange(
@@ -135,37 +134,41 @@ export function DocumentViewer(props: DocumentViewerProps) {
             return !!s && i() >= s.start && i() <= s.end;
           };
           return (
-            <div
-              class="doc-block"
-              data-block-index={i()}
-              data-change={change()}
-              classList={{
-                '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>
-              {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
-              <div innerHTML={block.html} />
+            <>
+              <div
+                class="doc-block"
+                data-block-index={i()}
+                data-change={change()}
+                classList={{
+                  '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>
+                {/* eslint-disable-next-line solid/no-innerhtml -- block HTML is DOMPurify-sanitized markdown from a local file */}
+                <div innerHTML={block.html} />
+              </div>
+              {/* Bubbles and the composer follow the block instead of sitting inside
+                it: they are not part of the passage, so clicking them must not
+                toggle its selection and the highlight stops at the prose. */}
               {props.afterBlock?.(i())}
-            </div>
+            </>
           );
         }}
       </For>
-      {props.children}
     </div>
   );
 }
diff --git a/src/documents/DocumentWorkspaceOverlay.tsx b/src/documents/DocumentWorkspaceOverlay.tsx
index f1d9f5938..9778d75cd 100644
--- a/src/documents/DocumentWorkspaceOverlay.tsx
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -35,7 +35,6 @@ import { showNotification } from '../store/notification';
 function DocumentPane() {
   let docRef: HTMLDivElement | undefined;
   const blocks = createRenderedBlocks(() => documentStore.snapshot?.content ?? null);
-  const [anchorTop, setAnchorTop] = createSignal(0);
   const selection = () => documentStore.selection;
   const range = createMemo(() => {
     const s = selection();
@@ -63,7 +62,6 @@ function DocumentPane() {
     }
     return { byBlock, detached, located };
   });
-  const openCount = () => documentStore.annotations.filter((a) => !a.resolved).length;
   const resolvedCount = () => documentStore.annotations.filter((a) => a.resolved).length;
 
   /** A bubble becomes a task: select its passage and open the composer with its text. */
@@ -101,21 +99,48 @@ function DocumentPane() {
     ),
   );
 
-  // Park the composer right under the last selected block.
+  // One composer instance, moved under whichever block ends the selection (or
+  // above the document for a whole-document task), so the typed instruction
+  // and agent picks survive a change of passage. It sits in the flow: the
+  // prose after it moves down instead of disappearing behind it.
+  const composerHost = (
+    <div class="docws-composer-host">
+      <Show when={selection()}>
+        {(s) => (
+          <RunComposer
+            selection={s()}
+            blocks={blocks.blocks()}
+            onClose={() => {
+              setDocumentSelection(null);
+              setDocumentComposerDraft(null);
+            }}
+          />
+        )}
+      </Show>
+    </div>
+  ) as HTMLDivElement;
+  const composerAfterBlock = () => {
+    const s = selection();
+    return s && !s.wholeDocument ? s.endBlock : -1;
+  };
+  const claimComposer = (slot: HTMLDivElement) => slot.appendChild(composerHost);
+
+  // Bring the composer into view when it opens under a new passage. 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([selection, blocks.blocks], () => {
-      const s = selection();
-      if (!s || !docRef) return;
+    on([selectedRange, blocks.blocks], () => {
+      if (!selection()) return;
       requestAnimationFrame(() => {
-        if (!docRef) return;
-        const index = s.wholeDocument ? 0 : s.endBlock;
-        const el = docRef.querySelector<HTMLElement>(`.doc-block[data-block-index="${index}"]`);
-        const top = s.wholeDocument ? 0 : el ? el.offsetTop + el.offsetHeight + 8 : 0;
-        setAnchorTop(top);
-        if (!s.wholeDocument && el) {
-          const composer = docRef.querySelector<HTMLElement>('.docws-composer');
-          composer?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
-        }
+        docRef
+          ?.querySelector<HTMLElement>('.docws-composer')
+          ?.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+        // Moving the composer between slots blurred it, and the passage was
+        // picked to write about.
+        composerHost.querySelector('textarea')?.focus({ preventScroll: true });
       });
     }),
   );
@@ -131,8 +156,9 @@ function DocumentPane() {
     if (showsPreview()) return 'Preview of the HTML document — switch to Blocks to scope a task';
     const s = selection();
     if (!s) return 'Select text, click a block, or use § on a heading to scope a task';
-    return s.wholeDocument
-      ? 'Whole document selected'
+    if (s.wholeDocument) return 'Whole document selected';
+    return s.startLine === s.endLine
+      ? `Selected line ${s.startLine}`
       : `Selected lines ${s.startLine}–${s.endLine}`;
   };
 
@@ -188,7 +214,7 @@ function DocumentPane() {
             </span>
           </Show>
           <span style={{ 'margin-left': 'auto' }} />
-          <Show when={openCount() + resolvedCount() > 0}>
+          <Show when={resolvedCount() > 0}>
             <label class="docws-toggle" title="Resolved bubbles collapse to one line">
               <input
                 type="checkbox"
@@ -239,6 +265,9 @@ function DocumentPane() {
               </For>
             </div>
           </Show>
+          <Show when={selection()?.wholeDocument}>
+            <div class="docws-composer-slot" ref={claimComposer} />
+          </Show>
           <DocumentViewer
             blocks={blocks.blocks()}
             selectable
@@ -246,25 +275,16 @@ function DocumentPane() {
             onSelect={setDocumentSelection}
             renderKey="main"
             afterBlock={(index) => (
-              <For each={placed().byBlock.get(index) ?? []}>
-                {(a) => <AnnotationBubble annotation={a} onMakeTask={makeTask} />}
-              </For>
+              <>
+                <For each={placed().byBlock.get(index) ?? []}>
+                  {(a) => <AnnotationBubble annotation={a} onMakeTask={makeTask} />}
+                </For>
+                <Show when={composerAfterBlock() === index}>
+                  <div class="docws-composer-slot" ref={claimComposer} />
+                </Show>
+              </>
             )}
-          >
-            <Show when={selection()}>
-              {(s) => (
-                <RunComposer
-                  selection={s()}
-                  blocks={blocks.blocks()}
-                  anchorTop={anchorTop()}
-                  onClose={() => {
-                    setDocumentSelection(null);
-                    setDocumentComposerDraft(null);
-                  }}
-                />
-              )}
-            </Show>
-          </DocumentViewer>
+          />
           <Show
             when={
               blocks.blocks().length === 0 &&
@@ -362,6 +382,23 @@ export function DocumentWorkspaceOverlay() {
         <span class="docws-subtitle" title={project()?.documentPath}>
           {project()?.documentPath}
         </span>
+        <span class="docws-head-chip" title="Checked-out branch and head commit">
+          <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+            <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
+          </svg>
+          {snapshot()?.branch ?? 'detached'} · {snapshot()?.headSha?.slice(0, 7) ?? 'no commits'}
+        </span>
+        <Show when={snapshot()?.dirty}>
+          <span
+            class="docws-head-chip is-warning"
+            title="Committed as “Manual edits” before the next run"
+          >
+            uncommitted edits
+          </span>
+        </Show>
+        <Show when={documentStore.loading}>
+          <span class="docws-head-chip">loading…</span>
+        </Show>
         <div class="docws-tabs" role="tablist">
           {tab('document', 'Document')}
           {tab('compare', 'Compare', reviewable().length)}
@@ -370,23 +407,20 @@ export function DocumentWorkspaceOverlay() {
         <button type="button" class="docws-btn" onClick={() => setEditing(project() ?? null)}>
           Project
         </button>
-        <button type="button" class="docws-btn" onClick={() => closeDocumentWorkspace()}>
+        <button
+          type="button"
+          class="docws-btn"
+          title="Close (Esc)"
+          onClick={() => closeDocumentWorkspace()}
+        >
           Close
         </button>
       </div>
-      <div class="docws-status-line">
-        <span>{snapshot()?.branch ?? 'detached'}</span>
-        <span>@ {snapshot()?.headSha?.slice(0, 7) ?? 'no commits'}</span>
-        <Show when={snapshot()?.dirty}>
-          <span class="docws-dirty">uncommitted edits (committed on the next run)</span>
-        </Show>
-        <Show when={documentStore.error}>
-          <span class="docws-error">{documentStore.error}</span>
-        </Show>
-        <Show when={documentStore.loading}>
-          <span>loading…</span>
-        </Show>
-      </div>
+      <Show when={documentStore.error}>
+        <div class="docws-banner docws-banner-error" role="alert">
+          {documentStore.error}
+        </div>
+      </Show>
       <div class="docws-body">
         <Show when={documentStore.view === 'document'}>
           <DocumentPane />
@@ -411,8 +445,19 @@ export function DocumentWorkspaceOverlay() {
               when={documentStore.compareRunId && compareRun() ? documentStore.compareRunId : null}
               keyed
               fallback={
-                <div class="docws-empty" style={{ padding: '24px' }}>
-                  Nothing to compare yet. Finished runs with proposals appear here.
+                <div class="docws-empty-state">
+                  <div class="docws-empty-state-title">Nothing to compare yet</div>
+                  <div>
+                    Select a passage on the Document tab and run a task. Finished runs with
+                    proposals appear here.
+                  </div>
+                  <button
+                    type="button"
+                    class="docws-btn"
+                    onClick={() => setDocumentView('document')}
+                  >
+                    Go to the document
+                  </button>
                 </div>
               }
             >
diff --git a/src/documents/NewDocumentProjectDialog.tsx b/src/documents/NewDocumentProjectDialog.tsx
index 647169170..6c0c1cfa1 100644
--- a/src/documents/NewDocumentProjectDialog.tsx
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -41,6 +41,12 @@ function folderName(folder: string): string {
   return folder.replace(/\/+$/, '').split('/').pop() ?? folder;
 }
 
+/** "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 one Markdown document inside it. Neither has to exist
  * yet: the folder path is editable, so a new project is a name typed onto a
@@ -94,11 +100,12 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
     const wanted = documentPath().trim();
     if (!current || !wanted) return [];
     const steps: string[] = [];
+    const file = withMarkdownExtension(wanted);
     if (!current.exists) steps.push('create the folder');
-    if (!current.isRepo) steps.push('run `git init`');
-    const match = files().find((f) => f.path === withMarkdownExtension(wanted));
-    if (!match) steps.push(`create ${withMarkdownExtension(wanted)}`);
-    if (!match?.committed) steps.push('make a commit');
+    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;
   });
 
@@ -255,7 +262,7 @@ export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
             </Show>
             <Show when={plan().length > 0}>
               <span style={{ 'font-size': '12px', color: theme.fgMuted }}>
-                Parallel will {plan().join(', ')}.
+                Parallel will {joinSteps(plan())}.
               </span>
             </Show>
           </div>
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
index 58097b4c0..2cc11095b 100644
--- a/src/documents/RunComposer.tsx
+++ b/src/documents/RunComposer.tsx
@@ -21,8 +21,6 @@ interface RunComposerProps {
   selection: DocumentSelection;
   /** Current blocks, for anchoring an annotation to the selection. */
   blocks: DocumentBlock[];
-  /** Offset inside the document container where the composer sits. */
-  anchorTop: number;
   onClose: () => void;
 }
 
@@ -103,7 +101,9 @@ export function RunComposer(props: RunComposerProps) {
   }
 
   onMount(() => {
-    requestAnimationFrame(() => textareaRef?.focus());
+    // The pane scrolls the composer into view itself; a focus scroll would cut
+    // that short and leave the composer half hidden.
+    requestAnimationFrame(() => textareaRef?.focus({ preventScroll: true }));
   });
 
   function without(counts: Record<string, number>, id: string): Record<string, number> {
@@ -155,7 +155,6 @@ export function RunComposer(props: RunComposerProps) {
       class="docws-composer"
       role="dialog"
       aria-label="Run a task on the selected passage"
-      style={{ top: `${props.anchorTop}px` }}
       onKeyDown={handleKeyDown}
       onMouseUp={(e) => e.stopPropagation()}
     >
diff --git a/src/documents/RunsRail.tsx b/src/documents/RunsRail.tsx
index 82457d297..f05ad5866 100644
--- a/src/documents/RunsRail.tsx
+++ b/src/documents/RunsRail.tsx
@@ -16,7 +16,21 @@ function scopeLabel(run: DocumentRunRecord): string {
   return s.heading ? `${lines} · ${s.heading}` : lines;
 }
 
-function candidateState(c: DocumentCandidateRecord): string {
+/** 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';
@@ -25,14 +39,18 @@ function candidateState(c: DocumentCandidateRecord): string {
 }
 
 function CandidateRow(props: {
-  runId: string;
+  run: DocumentRunRecord;
   candidate: DocumentCandidateRecord;
   showLog: boolean;
 }) {
-  const lines = () => documentStore.logs[candidateLogKey(props.runId, props.candidate.id)] ?? [];
+  const lines = () => documentStore.logs[candidateLogKey(props.run.id, props.candidate.id)] ?? [];
   const tail = () => lines().slice(-6);
+  const verdict = () => candidateVerdict(props.run, props.candidate);
   return (
-    <div class="docws-candidate">
+    <div
+      class="docws-candidate"
+      classList={{ 'is-passed-over': verdict() === 'passed-over' || verdict() === 'rejected' }}
+    >
       <div class="docws-candidate-head">
         <span class={`docws-dot docws-dot-${props.candidate.status}`} />
         <span class="docws-candidate-label">{props.candidate.label}</span>
@@ -40,8 +58,8 @@ function CandidateRow(props: {
         <Show when={props.candidate.isMain}>
           <span class="docws-badge">main</span>
         </Show>
-        <span style={{ 'margin-left': 'auto', color: 'var(--fg-subtle)' }}>
-          {candidateState(props.candidate)}
+        <span class="docws-candidate-state" classList={{ 'is-accepted': verdict() === 'accepted' }}>
+          {candidateState(props.candidate, verdict())}
         </span>
       </div>
       <Show when={props.candidate.error && props.candidate.status !== 'running'}>
@@ -94,7 +112,7 @@ export function RunsRail() {
               <For each={run.candidates}>
                 {(candidate) => (
                   <CandidateRow
-                    runId={run.id}
+                    run={run}
                     candidate={candidate}
                     showLog={run.status === 'running'}
                   />
diff --git a/src/documents/documents.css b/src/documents/documents.css
index 22e0da0ad..4f6d6a584 100644
--- a/src/documents/documents.css
+++ b/src/documents/documents.css
@@ -65,6 +65,44 @@
   min-width: 0;
 }
 
+/* Branch, head and working-tree state ride in the header instead of taking a
+   strip of their own. */
+.docws-head-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-subtle);
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--border-subtle);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.docws-head-chip svg {
+  flex-shrink: 0;
+}
+
+.docws-head-chip.is-warning {
+  color: var(--warning);
+  border-color: color-mix(in srgb, var(--warning) 45%, transparent);
+}
+
+.docws-banner {
+  padding: 6px 18px;
+  font-size: 12px;
+  border-bottom: 1px solid var(--border-subtle);
+  flex-shrink: 0;
+}
+
+.docws-banner-error {
+  background: color-mix(in srgb, var(--error) 12%, transparent);
+  color: var(--error);
+  border-color: color-mix(in srgb, var(--error) 40%, transparent);
+}
+
 .docws-tabs {
   display: flex;
   gap: 2px;
@@ -183,19 +221,28 @@
   padding: 8px 0;
 }
 
-.docws-status-line {
+.docws-empty-state {
   display: flex;
+  flex-direction: column;
   align-items: center;
+  justify-content: center;
   gap: 8px;
-  padding: 6px 18px;
-  font-size: 12px;
+  padding: 72px 24px;
+  text-align: center;
   color: var(--fg-muted);
-  border-bottom: 1px solid var(--border-subtle);
-  font-family: var(--font-mono);
+  font-size: 13px;
+  max-width: 420px;
+  margin: 0 auto;
 }
 
-.docws-status-line .docws-dirty {
-  color: var(--warning);
+.docws-empty-state-title {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--fg);
+}
+
+.docws-empty-state .docws-btn {
+  margin-top: 8px;
 }
 
 /* ── Rendered document ── */
@@ -360,11 +407,10 @@
 
 /* ── Composer ── */
 
+/* Sits in the flow under the selected passage; the prose after it moves down
+   instead of disappearing behind it. */
 .docws-composer {
-  position: absolute;
-  left: 0;
-  right: 0;
-  z-index: 5;
+  margin: 10px 0 18px;
   background: var(--island-bg);
   border: 1px solid color-mix(in srgb, var(--accent) 40%, var(--border));
   border-radius: var(--radius-lg);
@@ -571,6 +617,20 @@
   font-weight: 600;
 }
 
+.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;
@@ -695,12 +755,15 @@
   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 {