diff --git a/.dependency-cruiser.cjs b/.dependency-cruiser.cjs
index 35f5dd564..88fb383e6 100644
--- a/.dependency-cruiser.cjs
+++ b/.dependency-cruiser.cjs
@@ -16,12 +16,14 @@ module.exports = {
         //   - electron/mcp/validation.ts — string-only branch/UUID validators; the renderer
         //     shares them so it never offers a branch the IPC layer would reject
         //   - electron/shared/ — renderer-safe constants/pure helpers (no Node/Electron imports)
+        //   - electron/documents/shared.ts — agent ids/labels the document workspace shows
         pathNot: [
           '^electron/ipc/channels\\.ts',
           '^electron/mcp/prompt-detect\\.ts',
           '^electron/mcp/validation\\.ts',
           '^electron/agent-hooks/status\\.ts',
           '^electron/shared/',
+          '^electron/documents/shared\\.ts',
         ],
       },
     },
diff --git a/.gitignore b/.gitignore
index 7d5ed2181..ff871a58d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,7 @@ update-test/
 # Keep generated docs content ignored, but track the authored architecture overview.
 docs/*
 !docs/architecture-overview.html
+!docs/document-workspaces.md
 
 # Sandbox bind-mount artifacts from user home (not project files).
 # Root-anchored so legitimate nested files with these names are still tracked.
diff --git a/docs/document-workspaces.md b/docs/document-workspaces.md
new file mode 100644
index 000000000..41629961b
--- /dev/null
+++ b/docs/document-workspaces.md
@@ -0,0 +1,187 @@
+# Document Workspaces
+
+**A project type in Parallel Code for exploring problems in prose**
+
+Status: experimental, behind the _Document workspaces_ switch in Settings → Experimental.
+Slices 1 to 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
+writing and thinking: architecture notes, specs, ADRs, research. Several agents get the
+same passage and the same base version. You read the alternatives and decide what enters
+the document.
+
+```
+                    ┌──────────────  Claude Code  ──────────────●  accepted
+                    │                                            \
+   ────────●  base ─┤                                             ●──────
+                    │                                            /
+                    └──────────────  Codex  ───────────────○  discarded
+```
+
+## What is built
+
+### Using it
+
+1. Enable _Document workspaces_ under Settings → Experimental.
+2. Click **+** next to Projects and choose **Document project…**. Type or browse to a
+   folder and name the 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
+   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.
+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
+
+- **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. Only tracked files count as pending edits: untracked scratch files
+  and everything under `.parallel/` stay out of that commit.
+- **Headless agents.** Each candidate runs the official CLI in print mode inside its own
+  worktree under `.worktrees/parallel-doc/`: `claude -p --output-format stream-json`
+  with tools limited to Read/Edit/Write/Glob/Grep, `codex exec --json --sandbox
+workspace-write` (the sandbox blocks writes outside the worktree),
+  `gemini -p --output-format json --approval-mode auto_edit` (`plan`, Gemini's read-only
+  mode, for annotation questions). Process exit means the
+  proposal is ready. Cancelling kills the CLI's whole process group. OpenCode and Copilot
+  expose an unrestricted shell in print mode and are not offered until they can be
+  restricted.
+- **The main session stays warm.** One agent owns the project's main session (choose it in
+  the composer). Its worktree is persistent (`.worktrees/parallel-doc-main`) so the working
+  directory, and with it the provider's prompt cache, never changes; each run resumes the
+  session by id (`claude --resume`, `codex exec resume`). After the canonical document
+  moves, the next prompt to that session carries the diff since it last saw the file.
+  Other agents, and extra candidates from the main agent, are one-shot alternates. While
+  the main session is working, a new run can only use alternates.
+- **Scope is enforced, not trusted.** Files the agent touched or staged outside the
+  document are reverted before the proposal commit and listed on the candidate; the
+  proposal commit is verified to contain the document alone. Hunks inside the document
+  but outside the selected passage are counted and flagged.
+- **Structured rationale.** Every prompt asks the agent to end with a JSON block:
+  summary, changes, assumptions, questions, warnings. It opens each candidate in the
+  compare view and becomes the commit message.
+- **One proposal commit per candidate** on a `parallel-doc/<run>-<label>` branch, carrying
+  `Parallel-Run`, `Parallel-Agent`, `Parallel-Candidate`, `Parallel-Scope` and
+  `Parallel-Base` trailers.
+- **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. Reverting from the history view undoes a commit's content and keeps the
+  run records, with a `Parallel-Revert` trailer.
+- **Run records are checked on load.** They travel with the repository, so a clone can
+  carry records written elsewhere. Worktree paths, branch names and commit hashes are
+  validated against what this app would have produced before they reach git or the
+  filesystem; a record that fails is ignored.
+- **Compare view** renders base and candidates with the same renderer, marks changed,
+  added and removed blocks at block granularity, navigates by changed block, and hides
+  agent identity until you toggle _Show agents_. _Source diff_ swaps the rendering for the
+  unified diff. Each candidate has a free-text note stored in the run record.
+- **Anchors stay out of the prose.** An annotation records path, base commit, lines, the
+  exact quote, the neighbouring text and the nearest heading in
+  `.parallel/annotations.json` (`version: 1`). On every version the app relocates it by
+  quote, 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.
+- **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
+  `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
+
+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.
+
+---
+
+## 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/documents/agents.test.ts b/electron/documents/agents.test.ts
new file mode 100644
index 000000000..febae1806
--- /dev/null
+++ b/electron/documents/agents.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+import { buildHeadlessLaunch, createHeadlessParser, CLAUDE_DOCUMENT_TOOLS } from './agents.js';
+
+describe('buildHeadlessLaunch', () => {
+  it('starts a fresh claude session with a fixed id and no shell tools', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'claude-code',
+      command: 'claude',
+      prompt: 'Do it',
+      newSessionId: 'sid-1',
+    });
+    expect(launch.command).toBe('claude');
+    expect(launch.args).toContain('--session-id');
+    expect(launch.args).toContain('sid-1');
+    expect(launch.args).not.toContain('--resume');
+    const toolsIdx = launch.args.indexOf('--tools');
+    expect(launch.args[toolsIdx + 1]).toBe(CLAUDE_DOCUMENT_TOOLS);
+    expect(launch.args).not.toContain('--dangerously-skip-permissions');
+  });
+
+  it('resumes claude by session id', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'claude-code',
+      command: 'claude',
+      prompt: 'Again',
+      sessionId: 'old',
+      newSessionId: 'new',
+    });
+    expect(launch.args).toContain('--resume');
+    expect(launch.args).toContain('old');
+    expect(launch.args).not.toContain('--session-id');
+  });
+
+  it('puts codex flags before the resume subcommand', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'codex',
+      command: 'codex',
+      prompt: 'P',
+      sessionId: 'thread-1',
+      newSessionId: 'x',
+    });
+    expect(launch.args.slice(0, 2)).toEqual(['exec', '--json']);
+    expect(launch.args.indexOf('resume')).toBeGreaterThan(launch.args.indexOf('--sandbox'));
+    expect(launch.args.slice(-2)).toEqual(['thread-1', 'P']);
+  });
+
+  it('ignores a session id for agents that cannot resume', () => {
+    const launch = buildHeadlessLaunch({
+      agentId: 'gemini',
+      command: 'gemini',
+      prompt: 'P',
+      sessionId: 'ignored',
+      newSessionId: 'x',
+    });
+    expect(launch.args).not.toContain('ignored');
+  });
+
+  it('rejects agents without a headless mode', () => {
+    expect(() =>
+      buildHeadlessLaunch({
+        agentId: 'antigravity',
+        command: 'agy',
+        prompt: 'P',
+        newSessionId: 'x',
+      }),
+    ).toThrow(/no headless mode/);
+  });
+});
+
+describe('claude stream-json parser', () => {
+  it('collects session id, tool log lines and the final result across chunks', () => {
+    const parser = createHeadlessParser('claude-code');
+    const lines = [
+      JSON.stringify({ type: 'system', subtype: 'init', session_id: 's1' }),
+      JSON.stringify({
+        type: 'assistant',
+        message: {
+          content: [
+            { type: 'text', text: 'Looking' },
+            { type: 'tool_use', name: 'Edit', input: { file_path: 'docs/a.md' } },
+          ],
+        },
+      }),
+      JSON.stringify({
+        type: 'result',
+        subtype: 'success',
+        result: 'Final ```json\n{}\n```',
+        session_id: 's1',
+      }),
+    ];
+    const joined = lines.join('\n') + '\n';
+    const log = [...parser.feed(joined.slice(0, 40)), ...parser.feed(joined.slice(40))];
+    expect(log).toEqual(['session started', 'Looking', '→ Edit docs/a.md']);
+    const outcome = parser.finish();
+    expect(outcome.sessionId).toBe('s1');
+    expect(outcome.resultText).toContain('Final');
+    expect(outcome.error).toBeUndefined();
+  });
+
+  it('surfaces an error result', () => {
+    const parser = createHeadlessParser('claude-code');
+    parser.feed(
+      JSON.stringify({ type: 'result', subtype: 'error', is_error: true, result: 'boom' }) + '\n',
+    );
+    expect(parser.finish().error).toBe('boom');
+  });
+
+  it('names the failure from errors or the subtype when the result is empty', () => {
+    const detailed = createHeadlessParser('claude-code');
+    detailed.feed(
+      JSON.stringify({
+        type: 'result',
+        subtype: 'error_during_execution',
+        is_error: true,
+        errors: ['rate limited'],
+      }) + '\n',
+    );
+    expect(detailed.finish().error).toBe('rate limited');
+
+    const bare = createHeadlessParser('claude-code');
+    bare.feed(
+      JSON.stringify({ type: 'result', subtype: 'error_max_turns', is_error: true }) + '\n',
+    );
+    expect(bare.finish().error).toBe('max turns');
+
+    const blank = createHeadlessParser('claude-code');
+    blank.feed(JSON.stringify({ type: 'result', subtype: 'error', is_error: true }) + '\n');
+    expect(blank.finish().error).toBe('agent reported an error');
+  });
+
+  it('passes non-json lines through and falls back to assistant text', () => {
+    const parser = createHeadlessParser('claude-code');
+    const log = parser.feed('warning: something\n');
+    expect(log).toEqual(['warning: something']);
+    parser.feed(
+      JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'T' }] } }),
+    );
+    expect(parser.finish().resultText).toBe('T');
+  });
+});
+
+describe('codex jsonl parser', () => {
+  it('reads the thread id, file changes and last agent message', () => {
+    const parser = createHeadlessParser('codex');
+    const events = [
+      { type: 'thread.started', thread_id: 't1' },
+      { type: 'item.completed', item: { type: 'agent_message', text: 'first' } },
+      {
+        type: 'item.completed',
+        item: { type: 'file_change', changes: [{ path: 'a.md', kind: 'update' }] },
+      },
+      { type: 'item.completed', item: { type: 'agent_message', text: 'last' } },
+      { type: 'turn.completed', usage: {} },
+    ];
+    const log = parser.feed(events.map((e) => JSON.stringify(e)).join('\n'));
+    expect(log).toEqual(['session started', 'first', '→ update a.md', 'last']);
+    const outcome = parser.finish();
+    expect(outcome.sessionId).toBe('t1');
+    expect(outcome.resultText).toBe('last');
+  });
+
+  it('records stream errors', () => {
+    const parser = createHeadlessParser('codex');
+    parser.feed(JSON.stringify({ type: 'error', message: 'quota' }) + '\n');
+    expect(parser.finish().error).toBe('quota');
+  });
+});
+
+describe('gemini and plain parsers', () => {
+  it('extracts the gemini response', () => {
+    const parser = createHeadlessParser('gemini');
+    parser.feed('{"response": "hello", ');
+    parser.feed('"session_id": "g1"}');
+    expect(parser.finish()).toEqual({ resultText: 'hello', sessionId: 'g1', error: undefined });
+  });
+
+  it('treats unparseable gemini output as text', () => {
+    const parser = createHeadlessParser('gemini');
+    parser.feed('plain');
+    expect(parser.finish().resultText).toBe('plain');
+  });
+
+  it('keeps everything for plain-text agents', () => {
+    const parser = createHeadlessParser('custom-agent');
+    const log = parser.feed('one\ntwo\n');
+    expect(log).toEqual(['one', 'two']);
+    expect(parser.finish().resultText).toBe('one\ntwo\n');
+  });
+});
diff --git a/electron/documents/agents.ts b/electron/documents/agents.ts
new file mode 100644
index 000000000..d217616be
--- /dev/null
+++ b/electron/documents/agents.ts
@@ -0,0 +1,322 @@
+/**
+ * Headless launches for document proposals: how each supported CLI is
+ * started in print mode, and how its output is turned into a readable log,
+ * a final message and a session id.
+ */
+import { documentAgentSupport } from './shared.js';
+
+export interface HeadlessLaunch {
+  command: string;
+  args: string[];
+}
+
+export interface HeadlessLaunchOptions {
+  agentId: string;
+  command: string;
+  prompt: string;
+  /** Session to resume; ignored when the agent cannot resume. */
+  sessionId?: string;
+  /** Session id to assign to a fresh Claude run so it can be resumed later. */
+  newSessionId: string;
+  /** Answering a question: the agent may read but never write. */
+  readOnly?: boolean;
+}
+
+export interface HeadlessOutcome {
+  resultText: string;
+  sessionId?: string;
+  /** Provider-reported error, when the stream carried one. */
+  error?: string;
+}
+
+/** Incremental parser over a CLI's stdout. */
+export interface HeadlessOutputParser {
+  /** Feed raw stdout; returns human-readable log lines to forward. */
+  feed(chunk: string): string[];
+  /** Flush and return the final outcome once the process exited. */
+  finish(): HeadlessOutcome;
+}
+
+/** Tools a document proposal may use: read and edit files, nothing that runs code. */
+export const CLAUDE_DOCUMENT_TOOLS = 'Read,Edit,Write,Glob,Grep';
+/** Tools for answering a question about a document: reading only. */
+export const CLAUDE_READ_ONLY_TOOLS = 'Read,Glob,Grep';
+
+export function buildHeadlessLaunch(opts: HeadlessLaunchOptions): HeadlessLaunch {
+  const support = documentAgentSupport(opts.agentId);
+  if (!support.headless) {
+    throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
+  }
+  const resume = support.resume && opts.sessionId ? opts.sessionId : undefined;
+
+  switch (opts.agentId) {
+    case 'claude-code': {
+      const args = [
+        '-p',
+        opts.prompt,
+        '--output-format',
+        'stream-json',
+        '--verbose',
+        '--permission-mode',
+        opts.readOnly ? 'default' : 'acceptEdits',
+        '--tools',
+        opts.readOnly ? CLAUDE_READ_ONLY_TOOLS : CLAUDE_DOCUMENT_TOOLS,
+      ];
+      if (resume) args.push('--resume', resume);
+      else args.push('--session-id', opts.newSessionId);
+      return { command: opts.command, args };
+    }
+    case 'codex': {
+      const args = [
+        'exec',
+        '--json',
+        '--sandbox',
+        opts.readOnly ? 'read-only' : 'workspace-write',
+        '--skip-git-repo-check',
+      ];
+      if (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',
+          // `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:
+      throw new Error(`Agent "${opts.agentId}" has no headless mode for document runs.`);
+  }
+}
+
+function tryParseJson(line: string): Record<string, unknown> | null {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('{')) return null;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+function describeToolInput(name: string, input: unknown): string {
+  if (!input || typeof input !== 'object') return name;
+  const obj = input as Record<string, unknown>;
+  const target =
+    asString(obj.file_path) ?? asString(obj.path) ?? asString(obj.pattern) ?? asString(obj.command);
+  return target ? `${name} ${target}` : name;
+}
+
+/** Splits a stream into complete lines, keeping a partial tail between feeds. */
+class LineBuffer {
+  private tail = '';
+  push(chunk: string): string[] {
+    const data = this.tail + chunk;
+    const lines = data.split('\n');
+    this.tail = lines.pop() ?? '';
+    return lines;
+  }
+  flush(): string[] {
+    const rest = this.tail;
+    this.tail = '';
+    return rest.trim() ? [rest] : [];
+  }
+}
+
+/** Parser for `claude -p --output-format stream-json --verbose`. */
+class ClaudeStreamParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private sessionId?: string;
+  private result?: string;
+  private error?: string;
+  private lastAssistantText = '';
+
+  feed(chunk: string): string[] {
+    return this.lines.push(chunk).flatMap((line) => this.handle(line));
+  }
+
+  private handle(line: string): string[] {
+    const event = tryParseJson(line);
+    if (!event) return line.trim() ? [line] : [];
+    const sid = asString(event.session_id);
+    if (sid) this.sessionId = sid;
+
+    switch (event.type) {
+      case 'system':
+        return event.subtype === 'init' ? ['session started'] : [];
+      case 'assistant': {
+        const message = event.message as { content?: unknown } | undefined;
+        const content = Array.isArray(message?.content) ? message.content : [];
+        const out: string[] = [];
+        for (const block of content as Record<string, unknown>[]) {
+          if (block.type === 'text' && typeof block.text === 'string') {
+            this.lastAssistantText = block.text;
+            out.push(block.text);
+          } else if (block.type === 'tool_use') {
+            out.push(`→ ${describeToolInput(asString(block.name) ?? 'tool', block.input)}`);
+          }
+        }
+        return out;
+      }
+      case 'result': {
+        const text = asString(event.result);
+        if (text) this.result = text;
+        if (event.is_error === true) {
+          // Newer CLIs put the detail in `errors` and only name the failure
+          // class in `subtype` (error_max_turns, error_during_execution).
+          const errors = Array.isArray(event.errors) ? event.errors.map(asString) : [];
+          const subtype =
+            asString(event.subtype)
+              ?.replace(/^error_?/, '')
+              .replace(/_/g, ' ') || undefined;
+          this.error =
+            text ??
+            asString(event.error) ??
+            errors.find(Boolean) ??
+            subtype ??
+            'agent reported an error';
+        }
+        return [];
+      }
+      default:
+        return [];
+    }
+  }
+
+  finish(): HeadlessOutcome {
+    const rest = this.lines.flush().flatMap((line) => this.handle(line));
+    void rest;
+    return {
+      resultText: this.result ?? this.lastAssistantText,
+      sessionId: this.sessionId,
+      error: this.error,
+    };
+  }
+}
+
+/** Parser for `codex exec --json` (JSONL thread events). */
+class CodexJsonlParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private threadId?: string;
+  private lastMessage = '';
+  private error?: string;
+
+  feed(chunk: string): string[] {
+    return this.lines.push(chunk).flatMap((line) => this.handle(line));
+  }
+
+  private handle(line: string): string[] {
+    const event = tryParseJson(line);
+    if (!event) return line.trim() ? [line] : [];
+
+    switch (event.type) {
+      case 'thread.started': {
+        const id = asString(event.thread_id);
+        if (id) this.threadId = id;
+        return ['session started'];
+      }
+      case 'item.completed': {
+        const item = (event.item ?? {}) as Record<string, unknown>;
+        switch (item.type) {
+          case 'agent_message': {
+            const text = asString(item.text) ?? '';
+            if (text) this.lastMessage = text;
+            return text ? [text] : [];
+          }
+          case 'file_change': {
+            const changes = Array.isArray(item.changes) ? item.changes : [];
+            return changes.map((c) => {
+              const change = c as Record<string, unknown>;
+              return `→ ${asString(change.kind) ?? 'edit'} ${asString(change.path) ?? ''}`.trim();
+            });
+          }
+          case 'command_execution':
+            return [`→ ran ${asString(item.command) ?? 'command'}`];
+          case 'error':
+            this.error = asString(item.message) ?? 'agent reported an error';
+            return [`error: ${this.error}`];
+          default:
+            return [];
+        }
+      }
+      case 'error': {
+        this.error = asString(event.message) ?? 'agent reported an error';
+        return [`error: ${this.error}`];
+      }
+      default:
+        return [];
+    }
+  }
+
+  finish(): HeadlessOutcome {
+    for (const line of this.lines.flush()) this.handle(line);
+    return { resultText: this.lastMessage, sessionId: this.threadId, error: this.error };
+  }
+}
+
+/** Parser for `gemini -p --output-format json`: a single JSON document with `response`. */
+class GeminiJsonParser implements HeadlessOutputParser {
+  private raw = '';
+
+  feed(chunk: string): string[] {
+    this.raw += chunk;
+    return [];
+  }
+
+  finish(): HeadlessOutcome {
+    const parsed = tryParseJson(this.raw);
+    if (parsed) {
+      const response = asString(parsed.response);
+      const error = parsed.error as Record<string, unknown> | undefined;
+      return {
+        resultText: response ?? '',
+        sessionId: asString(parsed.session_id),
+        error: error ? (asString(error.message) ?? 'agent reported an error') : undefined,
+      };
+    }
+    return { resultText: this.raw };
+  }
+}
+
+/** Plain-text fallback: everything is the final message. */
+class PlainTextParser implements HeadlessOutputParser {
+  private readonly lines = new LineBuffer();
+  private raw = '';
+
+  feed(chunk: string): string[] {
+    this.raw += chunk;
+    return this.lines.push(chunk).filter((l) => l.trim().length > 0);
+  }
+
+  finish(): HeadlessOutcome {
+    return { resultText: this.raw };
+  }
+}
+
+export function createHeadlessParser(agentId: string): HeadlessOutputParser {
+  switch (agentId) {
+    case 'claude-code':
+      return new ClaudeStreamParser();
+    case 'codex':
+      return new CodexJsonlParser();
+    case 'gemini':
+      return new GeminiJsonParser();
+    default:
+      return new PlainTextParser();
+  }
+}
diff --git a/electron/documents/annotations.test.ts b/electron/documents/annotations.test.ts
new file mode 100644
index 000000000..569db8f0d
--- /dev/null
+++ b/electron/documents/annotations.test.ts
@@ -0,0 +1,183 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import {
+  askAnnotation,
+  buildAnnotationPrompt,
+  deleteAnnotation,
+  readAnnotations,
+  saveAnnotation,
+  validateAnnotationInput,
+} from './annotations.js';
+import type { DocumentAnnotation, DocumentAnnotationEvent } from './types.js';
+
+const anchor = {
+  path: 'docs/spec.md',
+  baseSha: 'abcdef1234567',
+  startLine: 5,
+  endLine: 7,
+  quote: '## Goals\n\nOld goals text.',
+  prefix: 'Intro paragraph.',
+  suffix: '## Later',
+  heading: 'Goals',
+};
+
+function note(id: string, extra: Partial<DocumentAnnotation> = {}): Record<string, unknown> {
+  return {
+    id,
+    kind: 'note',
+    anchor,
+    text: `note ${id}`,
+    createdAt: '2026-01-01T00:00:00Z',
+    ...extra,
+  };
+}
+
+describe('validateAnnotationInput', () => {
+  it('normalizes a note', () => {
+    const a = validateAnnotationInput(note('n-1', { resolved: true }));
+    expect(a.kind).toBe('note');
+    expect(a.resolved).toBe(true);
+    expect(a.anchor.heading).toBe('Goals');
+    expect(a.answer).toBeUndefined();
+  });
+  it('rejects bad ids, kinds, anchors and shas', () => {
+    expect(() => validateAnnotationInput(note('bad id!'))).toThrow(/id/);
+    expect(() => validateAnnotationInput({ ...note('n-1'), kind: 'task' })).toThrow(/kind/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, startLine: 9, endLine: 2 } }),
+    ).toThrow(/lines/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, baseSha: 'HEAD' } }),
+    ).toThrow(/baseSha/);
+    expect(() =>
+      validateAnnotationInput({ ...note('n-1'), anchor: { ...anchor, path: '../x.md' } }),
+    ).toThrow();
+  });
+  it('drops unknown statuses and run ids', () => {
+    const a = validateAnnotationInput({ ...note('n-1'), answerStatus: 'weird', runId: 'bad id' });
+    expect(a.answerStatus).toBeUndefined();
+    expect(a.runId).toBeUndefined();
+  });
+});
+
+describe('buildAnnotationPrompt', () => {
+  it('quotes the passage and forbids edits', () => {
+    const prompt = buildAnnotationPrompt(
+      validateAnnotationInput({ ...note('q-1'), kind: 'question', text: 'Why?' }),
+    );
+    expect(prompt).toContain('Document: docs/spec.md');
+    expect(prompt).toContain('lines 5-7 (under "Goals")');
+    expect(prompt).toContain('> Old goals text.');
+    expect(prompt).toContain('Question:\nWhy?');
+    expect(prompt).toContain('Do not edit');
+  });
+});
+
+describe('annotations file and asking', () => {
+  let root: string;
+  let fakeAgent: string;
+  const events: DocumentAnnotationEvent[] = [];
+  const win = {
+    isDestroyed: () => false,
+    webContents: { send: (_ch: string, payload: DocumentAnnotationEvent) => events.push(payload) },
+  } as unknown as BrowserWindow;
+
+  beforeAll(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-'));
+    const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-ann-bin-'));
+    fakeAgent = path.join(binDir, 'fake-claude.sh');
+    fs.writeFileSync(
+      fakeAgent,
+      [
+        '#!/bin/sh',
+        // Prove read-only tools were requested and answer.
+        'case "$*" in *"Read,Glob,Grep"*) ;; *) echo "wrong tools" >&2; exit 2;; esac',
+        'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"s","result":"The passage assumes **nothing**."}\'',
+      ].join('\n') + '\n',
+      { mode: 0o755 },
+    );
+  });
+
+  afterAll(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('round-trips annotations and keeps a pending answer across edits', async () => {
+    expect(readAnnotations(root)).toEqual([]);
+    await saveAnnotation(root, note('a-1'));
+    await saveAnnotation(root, note('a-2', { kind: 'question', text: 'Why?' }));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-1', 'a-2']);
+    expect(fs.existsSync(path.join(root, '.parallel', 'annotations.json'))).toBe(true);
+
+    const edited = await saveAnnotation(root, { ...note('a-1'), text: 'edited', resolved: true });
+    expect(edited.text).toBe('edited');
+    expect(readAnnotations(root)[0].createdAt).toBe('2026-01-01T00:00:00Z');
+
+    await deleteAnnotation(root, 'a-1');
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('skips malformed entries instead of losing the file', async () => {
+    const file = path.join(root, '.parallel', 'annotations.json');
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as { annotations: unknown[] };
+    raw.annotations.push({ id: 'bad', kind: 'note' });
+    fs.writeFileSync(file, JSON.stringify(raw));
+    expect(readAnnotations(root).map((a) => a.id)).toEqual(['a-2']);
+  });
+
+  it('asks a read-only agent and stores the answer in the bubble', async () => {
+    const pending = await askAnnotation(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      annotationId: 'a-2',
+      agentId: 'claude-code',
+      agentName: 'Fake Claude',
+      command: fakeAgent,
+    });
+    expect(pending.answerStatus).toBe('pending');
+    const answered = await new Promise<DocumentAnnotation>((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = events.find(
+          (e) => e.annotation.id === 'a-2' && e.annotation.answerStatus !== 'pending',
+        );
+        if (done) return resolve(done.annotation);
+        if (Date.now() - started > 10_000) return reject(new Error('no answer'));
+        setTimeout(tick, 50);
+      };
+      tick();
+    });
+    expect(answered.answerStatus).toBe('answered');
+    expect(answered.answer?.text).toContain('assumes **nothing**');
+    expect(answered.answer?.agentName).toBe('Fake Claude');
+    expect(readAnnotations(root)[0].answer?.text).toContain('nothing');
+    // Question and answer both survive: the question text is untouched.
+    expect(readAnnotations(root)[0].text).toBe('Why?');
+  });
+
+  it('refuses agents without a headless mode and unknown annotations', async () => {
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'a-2',
+        agentId: 'opencode',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/no headless mode/);
+    await expect(
+      askAnnotation(win, {
+        projectRoot: root,
+        documentPath: 'docs/spec.md',
+        annotationId: 'missing-1',
+        agentId: 'claude-code',
+        agentName: 'x',
+        command: fakeAgent,
+      }),
+    ).rejects.toThrow(/not found/);
+  });
+});
diff --git a/electron/documents/annotations.ts b/electron/documents/annotations.ts
new file mode 100644
index 000000000..d9d0ab8a6
--- /dev/null
+++ b/electron/documents/annotations.ts
@@ -0,0 +1,400 @@
+/**
+ * Annotations for document workspaces: notes and agent-answered questions
+ * anchored to a passage. They sit beside the document and never modify it,
+ * which makes them the safe way to interrogate a draft.
+ */
+import { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import { errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { documentAgentSupport } from './shared.js';
+import { validateDocumentPath, validateSha } from './runs.js';
+import type {
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationsFile,
+} from './types.js';
+
+export const ANNOTATIONS_REL_PATH = path.posix.join('.parallel', 'annotations.json');
+const MAX_TEXT_CHARS = 20_000;
+const MAX_ANSWER_CHARS = 50_000;
+const MAX_ANNOTATIONS = 2_000;
+const ANSWER_TIMEOUT_MS = 10 * 60_000;
+const KILL_GRACE_MS = 5_000;
+
+function annotationsPath(projectRoot: string): string {
+  return path.join(projectRoot, ANNOTATIONS_REL_PATH);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+// --- Validation -----------------------------------------------------------
+
+function validateAnnotationId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{1,64}$/i.test(value))
+    throw new Error('annotation id is invalid');
+  return value;
+}
+
+function text(value: unknown, label: string, max = MAX_TEXT_CHARS): string {
+  if (typeof value !== 'string') throw new Error(`${label} must be a string`);
+  return value.slice(0, max);
+}
+
+function validateAnchor(value: unknown): DocumentAnchor {
+  if (!value || typeof value !== 'object') throw new Error('anchor must be an object');
+  const a = value as Record<string, unknown>;
+  const startLine = Number(a.startLine);
+  const endLine = Number(a.endLine);
+  if (
+    !Number.isInteger(startLine) ||
+    !Number.isInteger(endLine) ||
+    startLine < 1 ||
+    endLine < startLine
+  )
+    throw new Error('anchor lines are invalid');
+  const baseSha =
+    a.baseSha === null || a.baseSha === undefined ? null : validateSha(a.baseSha, 'anchor.baseSha');
+  const heading =
+    typeof a.heading === 'string' && a.heading.trim() ? a.heading.slice(0, 300) : undefined;
+  return {
+    path: validateDocumentPath(a.path),
+    baseSha,
+    startLine,
+    endLine,
+    quote: text(a.quote, 'anchor.quote'),
+    prefix: text(a.prefix, 'anchor.prefix', 500),
+    suffix: text(a.suffix, 'anchor.suffix', 500),
+    heading,
+  };
+}
+
+/** Accepts what the renderer sends for a new or edited annotation. */
+export function validateAnnotationInput(value: unknown): DocumentAnnotation {
+  if (!value || typeof value !== 'object') throw new Error('annotation must be an object');
+  const v = value as Record<string, unknown>;
+  const kind = v.kind === 'question' ? 'question' : v.kind === 'note' ? 'note' : null;
+  if (!kind) throw new Error('annotation kind is invalid');
+  const id = validateAnnotationId(v.id);
+  const answer =
+    v.answer && typeof v.answer === 'object'
+      ? {
+          text: text((v.answer as Record<string, unknown>).text, 'answer.text', MAX_ANSWER_CHARS),
+          agentId: text((v.answer as Record<string, unknown>).agentId, 'answer.agentId', 64),
+          agentName: text((v.answer as Record<string, unknown>).agentName, 'answer.agentName', 64),
+          answeredAt: text(
+            (v.answer as Record<string, unknown>).answeredAt,
+            'answer.answeredAt',
+            64,
+          ),
+        }
+      : undefined;
+  const status = v.answerStatus;
+  const runId =
+    typeof v.runId === 'string' && /^[a-z0-9-]{1,64}$/i.test(v.runId) ? v.runId : undefined;
+  return {
+    id,
+    kind,
+    anchor: validateAnchor(v.anchor),
+    text: text(v.text, 'text'),
+    createdAt: typeof v.createdAt === 'string' ? v.createdAt.slice(0, 64) : nowIso(),
+    updatedAt: nowIso(),
+    resolved: v.resolved === true,
+    answer,
+    answerStatus:
+      status === 'pending' || status === 'answered' || status === 'failed' ? status : undefined,
+    answerError: typeof v.answerError === 'string' ? v.answerError.slice(0, 2_000) : undefined,
+    runId,
+  };
+}
+
+// --- File -----------------------------------------------------------------
+
+export function readAnnotations(projectRoot: string): DocumentAnnotation[] {
+  try {
+    const raw = JSON.parse(fs.readFileSync(annotationsPath(projectRoot), 'utf-8')) as unknown;
+    if (!raw || typeof raw !== 'object') return [];
+    const file = raw as Partial<DocumentAnnotationsFile>;
+    if (file.version !== 1 || !Array.isArray(file.annotations)) return [];
+    const out: DocumentAnnotation[] = [];
+    for (const entry of file.annotations) {
+      try {
+        const valid = validateAnnotationInput(entry);
+        // Keep the stored timestamp; validation stamps "now" for edits only.
+        valid.updatedAt =
+          typeof (entry as DocumentAnnotation).updatedAt === 'string'
+            ? (entry as DocumentAnnotation).updatedAt
+            : valid.updatedAt;
+        out.push(valid);
+      } catch {
+        // A malformed entry (hand-edited or from another tool) is skipped, not fatal.
+      }
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+function writeAnnotations(projectRoot: string, annotations: DocumentAnnotation[]): void {
+  const file: DocumentAnnotationsFile = { version: 1, annotations };
+  fs.mkdirSync(path.dirname(annotationsPath(projectRoot)), { recursive: true });
+  atomicWriteFileSync(annotationsPath(projectRoot), JSON.stringify(file, null, 2) + '\n');
+}
+
+const fileLocks = new Map<string, Promise<void>>();
+
+function withFileLock<T>(projectRoot: string, fn: () => T | Promise<T>): Promise<T> {
+  const key = path.resolve(projectRoot);
+  const prev = fileLocks.get(key) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  fileLocks.set(
+    key,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+export function saveAnnotation(projectRoot: string, input: unknown): Promise<DocumentAnnotation> {
+  const annotation = validateAnnotationInput(input);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const idx = all.findIndex((a) => a.id === annotation.id);
+    if (idx >= 0) {
+      // A pending answer belongs to the running ask, not to the edit.
+      const stored = all[idx];
+      if (stored.answerStatus === 'pending' && annotation.answerStatus !== 'pending') {
+        annotation.answer = stored.answer;
+        annotation.answerStatus = stored.answerStatus;
+      }
+      annotation.createdAt = stored.createdAt;
+      all[idx] = annotation;
+    } else {
+      if (all.length >= MAX_ANNOTATIONS) throw new Error('Too many annotations in this project.');
+      all.push(annotation);
+    }
+    writeAnnotations(projectRoot, all);
+    return annotation;
+  });
+}
+
+export function deleteAnnotation(projectRoot: string, idRaw: unknown): Promise<void> {
+  const id = validateAnnotationId(idRaw);
+  cancelAsk(id);
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    writeAnnotations(
+      projectRoot,
+      all.filter((a) => a.id !== id),
+    );
+  });
+}
+
+function updateAnnotation(
+  projectRoot: string,
+  id: string,
+  mutate: (a: DocumentAnnotation) => void,
+): Promise<DocumentAnnotation | null> {
+  return withFileLock(projectRoot, () => {
+    const all = readAnnotations(projectRoot);
+    const target = all.find((a) => a.id === id);
+    if (!target) return null;
+    mutate(target);
+    target.updatedAt = nowIso();
+    writeAnnotations(projectRoot, all);
+    return target;
+  });
+}
+
+// --- Asking an agent ------------------------------------------------------
+
+export interface AskAnnotationArgs {
+  projectRoot: string;
+  documentPath: unknown;
+  annotationId: unknown;
+  agentId: unknown;
+  agentName: unknown;
+  command: unknown;
+  envFile?: unknown;
+}
+
+interface ActiveAsk {
+  proc: ChildProcess;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const activeAsks = new Map<string, ActiveAsk>();
+
+/** Builds the read-only question prompt. Exported for tests. */
+export function buildAnnotationPrompt(annotation: DocumentAnnotation): string {
+  const a = annotation.anchor;
+  const where = a.heading
+    ? `lines ${a.startLine}-${a.endLine} (under "${a.heading}")`
+    : `lines ${a.startLine}-${a.endLine}`;
+  const quote = a.quote
+    .split('\n')
+    .map((l) => `> ${l}`)
+    .join('\n');
+  return [
+    'You are answering a question about a document in a Parallel Code document workspace. ' +
+      'Read the document (and anything else in the project you need) but do not modify any file.',
+    `Document: ${a.path}`,
+    `Passage: ${where}\n${quote}`,
+    `Question:\n${annotation.text.trim()}`,
+    [
+      'Rules:',
+      '- Answer the question about this passage directly and concisely, in Markdown.',
+      '- Quote the document where it supports your answer; say plainly when it does not.',
+      '- Do not rewrite the passage unless the question asks for a rewrite, and then show it as a suggestion.',
+      '- Do not edit, create or delete files, and do not run commands.',
+    ].join('\n'),
+  ].join('\n\n');
+}
+
+function killAsk(entry: ActiveAsk): void {
+  const pid = entry.proc.pid;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      if (pid) process.kill(-pid, sig);
+      else entry.proc.kill(sig);
+    } catch {
+      // Already gone.
+    }
+  };
+  signal('SIGTERM');
+  setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS).unref?.();
+}
+
+export function cancelAsk(annotationId: string): void {
+  const entry = activeAsks.get(annotationId);
+  if (!entry) return;
+  clearTimeout(entry.timer);
+  activeAsks.delete(annotationId);
+  killAsk(entry);
+}
+
+export function stopAllAsks(): void {
+  for (const id of [...activeAsks.keys()]) cancelAsk(id);
+}
+
+/**
+ * Runs a headless, read-only agent in the project checkout and writes its
+ * final message into the annotation. Progress is pushed as
+ * `IPC.DocumentAnnotationEvent`.
+ */
+export async function askAnnotation(
+  win: BrowserWindow,
+  args: AskAnnotationArgs,
+): Promise<DocumentAnnotation> {
+  const { projectRoot } = args;
+  validateDocumentPath(args.documentPath);
+  const annotationId = validateAnnotationId(args.annotationId);
+  const agentId = text(args.agentId, 'agentId', 64);
+  if (!documentAgentSupport(agentId).headless)
+    throw new Error(`Agent "${agentId}" has no headless mode for document questions.`);
+  const agentName = text(args.agentName, 'agentName', 64);
+  const command = text(args.command, 'command', 200);
+  if (!command.trim() || /[\s;&|<>$`'"\\]/.test(command)) throw new Error('command is invalid');
+  const envFile = args.envFile === undefined ? undefined : text(args.envFile, 'envFile', 1_000);
+  validateCommand(command);
+
+  cancelAsk(annotationId);
+  const annotation = await updateAnnotation(projectRoot, annotationId, (a) => {
+    a.kind = 'question';
+    a.answerStatus = 'pending';
+    a.answerError = undefined;
+  });
+  if (!annotation) throw new Error('Annotation not found');
+
+  const launch = buildHeadlessLaunch({
+    agentId,
+    command,
+    prompt: buildAnnotationPrompt(annotation),
+    newSessionId: randomUUID(),
+    readOnly: true,
+  });
+  const env = buildPtySpawnEnv({}, envFile?.trim() ? loadEnvFile(envFile) : {});
+  const parser = createHeadlessParser(agentId);
+  const proc = spawn(launch.command, launch.args, {
+    cwd: projectRoot,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  proc.stdout?.setEncoding('utf8');
+  proc.stderr?.setEncoding('utf8');
+  let stderrTail = '';
+  proc.stdout?.on('data', (chunk: string) => void parser.feed(chunk));
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-4_000);
+  });
+
+  const entry: ActiveAsk = {
+    proc,
+    timer: setTimeout(() => {
+      stderrTail = 'Timed out.';
+      killAsk(entry);
+    }, ANSWER_TIMEOUT_MS),
+  };
+  activeAsks.set(annotationId, entry);
+
+  const emit = (a: DocumentAnnotation) => {
+    if (!win.isDestroyed()) {
+      const event: DocumentAnnotationEvent = { projectRoot, annotation: a };
+      win.webContents.send(IPC.DocumentAnnotationEvent, event);
+    }
+  };
+  emit(annotation);
+
+  let settled = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(entry.timer);
+    const wasActive = activeAsks.get(annotationId) === entry;
+    if (wasActive) activeAsks.delete(annotationId);
+    const outcome = parser.finish();
+    const failure =
+      spawnError?.message ??
+      outcome.error ??
+      (!outcome.resultText.trim()
+        ? stderrTail.trim() || `The agent exited with code ${exitCode ?? 'unknown'} and no answer.`
+        : undefined);
+    const updated = await updateAnnotation(projectRoot, annotationId, (a) => {
+      if (!wasActive) return; // cancelled or superseded: leave whatever the newer ask wrote
+      if (failure && !outcome.resultText.trim()) {
+        a.answerStatus = 'failed';
+        a.answerError = failure.slice(0, 2_000);
+      } else {
+        a.answerStatus = 'answered';
+        a.answerError = failure?.slice(0, 2_000);
+        a.answer = {
+          text: outcome.resultText.slice(0, MAX_ANSWER_CHARS),
+          agentId,
+          agentName,
+          answeredAt: nowIso(),
+        };
+      }
+    }).catch((err) => {
+      console.warn('[annotations] failed to store answer:', errMessage(err));
+      return null;
+    });
+    if (updated && wasActive) emit(updated);
+  };
+  proc.on('close', (code) => void settle(code));
+  proc.on('error', (err) => void settle(1, err));
+  return annotation;
+}
diff --git a/electron/documents/git.ts b/electron/documents/git.ts
new file mode 100644
index 000000000..7ed8485bd
--- /dev/null
+++ b/electron/documents/git.ts
@@ -0,0 +1,24 @@
+/** The `git` invocation every document-workspace module shares. */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { debug as logDebug } from '../log.js';
+
+const execFileAsync = promisify(execFile);
+/** A document's history can be large; `git log -p` on it must not be truncated. */
+const MAX_BUFFER = 20 * 1024 * 1024;
+
+export async function git(cwd: string, args: string[]): Promise<string> {
+  logDebug('git', args.join(' '));
+  const { stdout } = await execFileAsync('git', args, { cwd, maxBuffer: MAX_BUFFER });
+  return stdout;
+}
+
+/** `git` for commands whose failure is an answer rather than an error. */
+export async function gitOk(cwd: string, args: string[]): Promise<boolean> {
+  try {
+    await git(cwd, args);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/electron/documents/prompt.test.ts b/electron/documents/prompt.test.ts
new file mode 100644
index 000000000..7a686f913
--- /dev/null
+++ b/electron/documents/prompt.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+
+const scope = {
+  path: 'docs/spec.md',
+  wholeDocument: false,
+  startLine: 10,
+  endLine: 12,
+  quote: 'First line\nSecond line',
+  heading: 'Overview',
+};
+
+describe('buildDocumentPrompt', () => {
+  it('quotes the scoped passage and names the file', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Tighten this.',
+    });
+    expect(prompt).toContain('Document: docs/spec.md');
+    expect(prompt).toContain('lines 10-12 (under "Overview")');
+    expect(prompt).toContain('> First line\n> Second line');
+    expect(prompt).toContain('Instruction:\nTighten this.');
+    expect(prompt).toContain('```json');
+    expect(prompt).not.toContain('Since your previous turn');
+  });
+
+  it('describes a whole-document scope', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope: { ...scope, wholeDocument: true },
+      instruction: 'Review.',
+    });
+    expect(prompt).toContain('Scope: the whole document.');
+    expect(prompt).not.toContain('verbatim');
+  });
+
+  it('hands a resumed session the diff since it last saw the document', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Go on.',
+      catchUpDiff: '--- a\n+++ b\n@@ -1 +1 @@\n-old\n+new',
+    });
+    expect(prompt).toContain('Since your previous turn');
+    expect(prompt).toContain('+new');
+  });
+
+  it('truncates an oversized catch-up diff', () => {
+    const prompt = buildDocumentPrompt({
+      documentPath: 'docs/spec.md',
+      scope,
+      instruction: 'Go on.',
+      catchUpDiff: 'x'.repeat(30_000),
+    });
+    expect(prompt).toContain('(diff truncated)');
+    expect(prompt.length).toBeLessThan(25_000);
+  });
+});
+
+describe('parseDocumentRationale', () => {
+  it('takes the last fenced json block', () => {
+    const text =
+      'Some prose.\n```json\n{"summary": "early"}\n```\nMore.\n```json\n{"summary": "final", "changes": ["a", "b"], "questions": ["q"]}\n```';
+    const r = parseDocumentRationale(text);
+    expect(r.summary).toBe('final');
+    expect(r.changes).toEqual(['a', 'b']);
+    expect(r.questions).toEqual(['q']);
+    expect(r.assumptions).toEqual([]);
+  });
+
+  it('accepts an unlabeled fence and drops non-string entries', () => {
+    const r = parseDocumentRationale('```\n{"summary":"s","changes":["ok", 3, ""]}\n```');
+    expect(r.summary).toBe('s');
+    expect(r.changes).toEqual(['ok']);
+  });
+
+  it('parses bare json', () => {
+    expect(parseDocumentRationale('{"summary":"bare"}').summary).toBe('bare');
+  });
+
+  it('falls back to the first line of prose', () => {
+    const r = parseDocumentRationale('\n\nI rewrote the intro.\nDetails follow.');
+    expect(r.summary).toBe('I rewrote the intro.');
+    expect(r.warnings).toEqual([]);
+  });
+
+  it('flags an empty result', () => {
+    const r = parseDocumentRationale('   ');
+    expect(r.summary).toBe('No rationale returned.');
+    expect(r.warnings).toHaveLength(1);
+  });
+
+  it('ignores a fence that is valid json but not a rationale', () => {
+    const r = parseDocumentRationale('```json\n[1,2]\n```\nSummary line');
+    expect(r.summary).toBe('Summary line');
+  });
+});
diff --git a/electron/documents/prompt.ts b/electron/documents/prompt.ts
new file mode 100644
index 000000000..ff191b926
--- /dev/null
+++ b/electron/documents/prompt.ts
@@ -0,0 +1,136 @@
+import type { DocumentRationale, DocumentScope } from './types.js';
+
+/** Largest diff (in characters) handed to a resumed main session. */
+const MAX_CATCH_UP_DIFF_CHARS = 20_000;
+
+export interface DocumentPromptInput {
+  documentPath: string;
+  scope: DocumentScope;
+  instruction: string;
+  /** Diff of the canonical document since the resumed session last saw it. */
+  catchUpDiff?: string;
+}
+
+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');
+}
+
+/** Rationale entries end up in commit bodies: one line each, no stray newlines. */
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((v): v is string => typeof v === 'string' && v.trim().length > 0)
+    .map(oneLine);
+}
+
+function rationaleFromObject(value: unknown): DocumentRationale | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const obj = value as Record<string, unknown>;
+  const summary = typeof obj.summary === 'string' ? oneLine(obj.summary) : '';
+  const changes = stringList(obj.changes);
+  if (!summary && changes.length === 0) return null;
+  return {
+    summary: summary || changes[0],
+    changes,
+    assumptions: stringList(obj.assumptions),
+    questions: stringList(obj.questions),
+    warnings: stringList(obj.warnings),
+  };
+}
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extracts the structured rationale from an agent's final message. Takes the
+ * last fenced JSON block; falls back to the whole text as JSON, then to a
+ * summary made from the first non-empty line.
+ */
+export function parseDocumentRationale(text: string): DocumentRationale {
+  const fences = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)\n\s*```/g)];
+  for (let i = fences.length - 1; i >= 0; i--) {
+    const parsed = rationaleFromObject(tryParse(fences[i][1].trim()));
+    if (parsed) return parsed;
+  }
+  const whole = rationaleFromObject(tryParse(text.trim()));
+  if (whole) return whole;
+
+  const prose = text.replace(/```[\s\S]*?```/g, '');
+  const firstLine = prose
+    .split('\n')
+    .map((l) => l.trim())
+    .find((l) => l.length > 0);
+  return {
+    summary: firstLine ? firstLine.slice(0, 200) : 'No rationale returned.',
+    changes: [],
+    assumptions: [],
+    questions: [],
+    warnings: firstLine ? [] : ['The agent returned no rationale.'],
+  };
+}
diff --git a/electron/documents/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
new file mode 100644
index 000000000..d147fba7d
--- /dev/null
+++ b/electron/documents/runs.integration.test.ts
@@ -0,0 +1,450 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import {
+  acceptDocumentCandidate,
+  commitPendingEdits,
+  dispatchDocumentRun,
+  revertDocumentCommit,
+  getDocumentAtCommit,
+  getDocumentDiff,
+  getDocumentHistory,
+  listDocumentRuns,
+  readDocumentSnapshot,
+  rejectDocumentRun,
+} from './runs.js';
+import { inspectDocumentFolder } from './setup.js';
+import type { DocumentRunEvent, DocumentRunRecord } from './types.js';
+
+/**
+ * Exercises the whole proposal lifecycle against a real temporary repository
+ * with a fake "claude" script standing in for the CLI: it rewrites the scoped
+ * passage, touches a file outside scope, and prints a stream-json result.
+ */
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+const DOC = [
+  '# Spec',
+  '',
+  'Intro paragraph.',
+  '',
+  '## Goals',
+  '',
+  'Old goals text.',
+  '',
+  '## Later',
+  '',
+  'Untouched.',
+  '',
+].join('\n');
+
+let root: string;
+let fakeAgent: string;
+const events: DocumentRunEvent[] = [];
+const win = {
+  isDestroyed: () => false,
+  webContents: { send: (_ch: string, payload: DocumentRunEvent) => events.push(payload) },
+} as unknown as BrowserWindow;
+
+function waitForRunFinish(runId: string): Promise<DocumentRunRecord> {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const tick = () => {
+      const done = events.find(
+        (e): e is Extract<DocumentRunEvent, { type: 'run' }> =>
+          e.type === 'run' && e.run.id === runId && e.run.status !== 'running',
+      );
+      if (done) return resolve(done.run);
+      if (Date.now() - started > 20_000) return reject(new Error('run did not finish'));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}
+
+beforeAll(() => {
+  process.env.GIT_AUTHOR_NAME = 'Test';
+  process.env.GIT_AUTHOR_EMAIL = 'test@example.com';
+  process.env.GIT_COMMITTER_NAME = 'Test';
+  process.env.GIT_COMMITTER_EMAIL = 'test@example.com';
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-'));
+  git(root, 'init', '-q', '-b', 'main');
+  fs.mkdirSync(path.join(root, 'docs'));
+  fs.writeFileSync(path.join(root, 'docs', 'spec.md'), DOC);
+  fs.writeFileSync(path.join(root, 'README.md'), '# Readme\n');
+  git(root, 'add', '.');
+  git(root, 'commit', '-q', '-m', 'initial');
+
+  // The fake CLI lives outside the repo so it never shows up as a change.
+  const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-bin-'));
+  fakeAgent = path.join(binDir, 'fake-claude.sh');
+  fs.writeFileSync(
+    fakeAgent,
+    [
+      '#!/bin/sh',
+      'sed -i.bak "s/Old goals text./New goals text, sharper./" docs/spec.md && rm -f docs/spec.md.bak',
+      'echo "stray" > STRAY.txt && git add STRAY.txt',
+      'echo "scratch" > notes.tmp',
+      'printf \'%s\\n\' \'{"type":"system","subtype":"init","session_id":"sess-1"}\'',
+      'printf \'%s\\n\' \'{"type":"assistant","message":{"content":[{"type":"tool_use","name":"Edit","input":{"file_path":"docs/spec.md"}}]}}\'',
+      'printf \'%s\\n\' \'{"type":"result","subtype":"success","session_id":"sess-1","result":"Done.\\n```json\\n{\\"summary\\":\\"Sharpened the goals\\",\\"changes\\":[\\"rewrote goals\\"],\\"questions\\":[\\"ok?\\"]}\\n```"}\'',
+    ].join('\n') + '\n',
+    { mode: 0o755 },
+  );
+});
+
+afterAll(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('document workspace lifecycle', () => {
+  it('lists the markdown a ready repository offers', async () => {
+    expect(await inspectDocumentFolder(root)).toMatchObject({
+      isRepo: true,
+      hasCommits: true,
+      files: [
+        { path: 'README.md', committed: true },
+        { path: 'docs/spec.md', committed: true },
+      ],
+    });
+  });
+
+  it('diffs the root commit against the empty tree', async () => {
+    const rootSha = git(root, 'rev-list', '--max-parents=0', 'HEAD').trim();
+    const diff = await getDocumentDiff(root, `${rootSha}^`, rootSha, 'docs/spec.md');
+    expect(diff).toContain('+# Spec');
+  });
+
+  it('reads a snapshot', async () => {
+    const snap = await readDocumentSnapshot(root, 'docs/spec.md');
+    expect(snap.content).toBe(DOC);
+    expect(snap.branch).toBe('main');
+    expect(snap.dirty).toBe(false);
+    expect(snap.headSha).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('commits pending edits, runs a candidate in a worktree, strips out-of-scope files and commits a proposal', async () => {
+    // A pending manual edit must become the base; an untracked scratch file must not.
+    fs.appendFileSync(path.join(root, 'README.md'), 'manual\n');
+    fs.writeFileSync(path.join(root, 'scratch.txt'), 'not for history\n');
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Sharpen the goals.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Goals\n\nOld goals text.',
+        heading: 'Goals',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: true,
+        },
+      ],
+    });
+    expect(run.status).toBe('running');
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Manual edits');
+    expect(git(root, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('README.md');
+    expect(git(root, 'status', '--porcelain', 'scratch.txt').trim()).toMatch(/^\?\? scratch.txt/);
+    fs.rmSync(path.join(root, 'scratch.txt'));
+    expect(run.baseSha).toBe(git(root, 'rev-parse', 'HEAD').trim());
+
+    const finished = await waitForRunFinish(run.id);
+    const c = finished.candidates[0];
+    const proposalSha = String(c.commitSha);
+    expect(c.status).toBe('done');
+    expect(c.sessionId).toBe('sess-1');
+    expect(c.rationale?.summary).toBe('Sharpened the goals');
+    expect(c.rationale?.questions).toEqual(['ok?']);
+    expect(c.outOfScopeFiles?.sort()).toEqual(['STRAY.txt', 'notes.tmp']);
+    expect(c.outOfScopeHunks).toBeUndefined();
+    expect(c.commitSha).toMatch(/^[0-9a-f]{40}$/);
+    expect(c.worktreePath).toBe(path.join(root, '.worktrees', 'parallel-doc-main'));
+    expect(events.some((e) => e.type === 'log' && e.text.includes('Edit docs/spec.md'))).toBe(true);
+
+    // The proposal commit carries only the document and readable trailers.
+    const files = git(root, 'show', '--format=', '--name-only', proposalSha).trim();
+    expect(files).toBe('docs/spec.md');
+    const message = git(root, 'show', '-s', '--format=%B', proposalSha);
+    expect(message).toContain('Sharpened the goals');
+    expect(message).toContain('Parallel-Agent: Fake Claude');
+    expect(message).toContain('Parallel-Scope: docs/spec.md#L5-L7');
+    expect(message).toContain(`Parallel-Base: ${run.baseSha}`);
+
+    // The canonical document is untouched until acceptance.
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toBe(DOC);
+    expect(await getDocumentAtCommit(root, proposalSha, 'docs/spec.md')).toContain(
+      'New goals text',
+    );
+    expect(await getDocumentDiff(root, run.baseSha, proposalSha, 'docs/spec.md')).toContain(
+      '+New goals text',
+    );
+
+    // Records are persisted and reloadable.
+    const listed = listDocumentRuns(root);
+    expect(listed.map((r) => r.id)).toEqual([run.id]);
+    expect(listed[0].status).toBe('finished');
+
+    // Accept: one squashed integration commit with the run record.
+    const { sha } = await acceptDocumentCandidate(root, run.id, 'c1');
+    expect(sha).toBe(git(root, 'rev-parse', 'HEAD').trim());
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toContain('New goals text');
+    const accepted = git(root, 'show', '--format=%B', '--name-only', sha);
+    expect(accepted).toContain('Parallel-Run: ' + run.id);
+    expect(accepted).toContain('Parallel-Candidate: A');
+    expect(accepted).toContain('docs/spec.md');
+    expect(accepted).toContain(`.parallel/runs/${run.id}.json`);
+    expect(git(root, 'rev-list', '--count', 'HEAD').trim()).toBe('3');
+    expect(listDocumentRuns(root)[0].status).toBe('accepted');
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/already accepted/);
+
+    // History for the document parses trailers and marks manual commits.
+    const history = await getDocumentHistory(root, 'docs/spec.md', false);
+    expect(history.map((h) => h.manual)).toEqual([false, true]);
+    expect(history[0].trailers.Agent).toBe('Fake Claude');
+    expect(history[0].body).not.toContain('Parallel-');
+    const whole = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(whole).toHaveLength(3);
+
+    // Reverting the acceptance restores the document but keeps the run record.
+    const reverted = await revertDocumentCommit(root, sha);
+    expect(reverted).toBe(git(root, 'rev-parse', 'HEAD').trim());
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toBe(DOC);
+    expect(fs.existsSync(path.join(root, '.parallel', 'runs', `${run.id}.json`))).toBe(true);
+    expect(git(root, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('docs/spec.md');
+    expect(git(root, 'show', '-s', '--format=%B', 'HEAD')).toContain(`Parallel-Revert: ${sha}`);
+    expect(listDocumentRuns(root).map((r) => r.id)).toEqual([run.id]);
+  });
+
+  it('refuses to reuse the main worktree while its candidate is still running', async () => {
+    const binDir = path.dirname(fakeAgent);
+    const slow = path.join(binDir, 'slow.sh');
+    fs.writeFileSync(slow, '#!/bin/sh\nsleep 3\n', { mode: 0o755 });
+    const base = {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Slow.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    };
+    const running = await dispatchDocumentRun(win, {
+      ...base,
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Slow',
+          command: slow,
+          isMain: true,
+        },
+      ],
+    });
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [
+          {
+            id: 'c1',
+            label: 'A',
+            agentId: 'claude-code',
+            agentName: 'Slow',
+            command: slow,
+            isMain: true,
+          },
+        ],
+      }),
+    ).rejects.toThrow(/main session is still working/);
+    // An alternate-only run is fine meanwhile.
+    const alt = await dispatchDocumentRun(win, {
+      ...base,
+      candidates: [
+        {
+          id: 'c1',
+          label: 'B',
+          agentId: 'claude-code',
+          agentName: 'Slow',
+          command: slow,
+          isMain: false,
+        },
+      ],
+    });
+    // Rejecting a running run kills it and waits for it to settle before cleanup.
+    const rejected = await rejectDocumentRun(root, running.id);
+    expect(rejected.status).toBe('rejected');
+    expect(rejected.candidates[0].status).toBe('cancelled');
+    expect(listDocumentRuns(root).find((r) => r.id === running.id)?.status).toBe('rejected');
+    await waitForRunFinish(alt.id);
+    await rejectDocumentRun(root, alt.id);
+  });
+
+  // Its own repository: the tests above share one and depend on its state.
+  it('leaves what the user staged by hand out of its own commits', async () => {
+    const solo = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-staged-'));
+    git(solo, 'init', '-q', '-b', 'main');
+    fs.mkdirSync(path.join(solo, 'docs'));
+    fs.writeFileSync(path.join(solo, 'docs', 'spec.md'), DOC);
+    fs.writeFileSync(path.join(solo, 'README.md'), '# Readme\n');
+    git(solo, 'add', '.');
+    git(solo, 'commit', '-q', '-m', 'initial');
+
+    // The user stages a new file of their own and edits a tracked one.
+    fs.writeFileSync(path.join(solo, 'staged-by-user.md'), '# Not ours\n');
+    git(solo, 'add', 'staged-by-user.md');
+    fs.appendFileSync(path.join(solo, 'README.md'), 'manual edit\n');
+
+    const base = await commitPendingEdits(solo);
+    expect(git(solo, 'show', '--format=', '--name-only', base).trim()).toBe('README.md');
+    const stillStaged = () => git(solo, 'status', '--porcelain', '--', 'staged-by-user.md').trim();
+    expect(stillStaged()).toBe('A  staged-by-user.md');
+
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: solo,
+      documentPath: 'docs/spec.md',
+      instruction: 'Sharpen the goals.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    await waitForRunFinish(run.id);
+    const { sha } = await acceptDocumentCandidate(solo, run.id, 'c1');
+    expect(git(solo, 'show', '--format=', '--name-only', sha).trim().split('\n').sort()).toEqual([
+      `.parallel/runs/${run.id}.json`,
+      'docs/spec.md',
+    ]);
+    expect(stillStaged()).toBe('A  staged-by-user.md');
+    fs.rmSync(solo, { recursive: true, force: true });
+  });
+
+  it('rejects candidate specs that would smuggle flags into git or the CLI', async () => {
+    const base = {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'x',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    };
+    const spec = {
+      id: 'c1',
+      label: 'A',
+      agentId: 'claude-code',
+      agentName: 'F',
+      command: fakeAgent,
+      isMain: true,
+    };
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [{ ...spec, sessionLastSha: '--output=/tmp/x' }],
+      }),
+    ).rejects.toThrow(/sessionLastSha/);
+    await expect(
+      dispatchDocumentRun(win, {
+        ...base,
+        candidates: [{ ...spec, sessionId: '--dangerously-skip-permissions' }],
+      }),
+    ).rejects.toThrow(/sessionId/);
+    await expect(
+      dispatchDocumentRun(win, { ...base, candidates: [{ ...spec, agentId: 'opencode' }] }),
+    ).rejects.toThrow(/no headless mode/);
+    await expect(commitPendingEdits(root)).resolves.toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('marks a proposal stale when the base moved and it conflicts, and rejects cleanly', async () => {
+    // The revert above restored the original text, so the fake edit applies again.
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Again.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    const finished = await waitForRunFinish(run.id);
+    const c = finished.candidates[0];
+    expect(c.commitSha).toBeTruthy();
+    // Alternates get seeded sandbox files; those must not count as strays.
+    expect(c.outOfScopeFiles?.some((f) => f.startsWith('.claude/'))).toBe(false);
+
+    // Meanwhile the user rewrites the same line by hand and commits it.
+    fs.writeFileSync(
+      path.join(root, 'docs', 'spec.md'),
+      DOC.replace('Old goals text.', 'Hand-written goals.'),
+    );
+    git(root, 'commit', '-q', '-am', 'hand edit');
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/no longer applies/);
+    expect(listDocumentRuns(root).find((r) => r.id === run.id)?.status).toBe('stale');
+    expect(git(root, 'status', '--porcelain', '--', 'docs').trim()).toBe('');
+    expect(fs.readFileSync(path.join(root, 'docs', 'spec.md'), 'utf8')).toContain('Hand-written');
+
+    const rejected = await rejectDocumentRun(root, run.id);
+    expect(rejected.status).toBe('rejected');
+    expect(fs.existsSync(c.worktreePath)).toBe(false);
+    expect(git(root, 'branch', '--list', c.branch).trim()).toBe('');
+    // The rejection is a metadata-only commit, invisible in the document history.
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Reject proposals');
+    const history = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(history.map((h) => h.subject)).not.toContain('Reject proposals');
+  });
+
+  // Runs after the test above, which already replaced the text the fake agent
+  // looks for, so this candidate finds nothing to change.
+  it('records a candidate that changed nothing, and rejects it cleanly', async () => {
+    const run = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'docs/spec.md',
+      instruction: 'Again.',
+      scope: { wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Fake Claude',
+          command: fakeAgent,
+          isMain: false,
+        },
+      ],
+    });
+    const finished = await waitForRunFinish(run.id);
+    // The fake edit no longer matches (text already replaced) so nothing changes.
+    expect(finished.candidates[0].noChanges).toBe(true);
+    expect(finished.candidates[0].commitSha).toBeNull();
+    await expect(acceptDocumentCandidate(root, run.id, 'c1')).rejects.toThrow(/no change/);
+    const rejected = await rejectDocumentRun(root, run.id);
+    expect(rejected.status).toBe('rejected');
+    expect(fs.existsSync(finished.candidates[0].worktreePath)).toBe(false);
+    expect(git(root, 'branch', '--list', finished.candidates[0].branch).trim()).toBe('');
+    // The rejection is a metadata-only commit, invisible in the document history.
+    expect(git(root, 'log', '--format=%s', '-n', '1').trim()).toBe('Reject proposals');
+    const history = await getDocumentHistory(root, 'docs/spec.md', true);
+    expect(history.map((h) => h.subject)).not.toContain('Reject proposals');
+  });
+});
diff --git a/electron/documents/runs.real-claude.integration.test.ts b/electron/documents/runs.real-claude.integration.test.ts
new file mode 100644
index 000000000..202fd91d6
--- /dev/null
+++ b/electron/documents/runs.real-claude.integration.test.ts
@@ -0,0 +1,211 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { BrowserWindow } from 'electron';
+import { acceptDocumentCandidate, dispatchDocumentRun } from './runs.js';
+import { askAnnotation, readAnnotations, saveAnnotation } from './annotations.js';
+import type {
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentRunEvent,
+  DocumentRunRecord,
+} from './types.js';
+
+/**
+ * Drives the real `claude` CLI through one proposal and one resumed follow-up.
+ * Costs a few API calls, so it only runs when explicitly asked for:
+ *   RUN_REAL_CLAUDE_DOC_TEST=1 npx vitest run electron/documents/runs.real-claude.integration.test.ts
+ */
+const RUN = process.env.RUN_REAL_CLAUDE_DOC_TEST === '1';
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+const DOC = [
+  '# Notes',
+  '',
+  'Intro stays as it is.',
+  '',
+  '## Weather',
+  '',
+  'The weather is nice.',
+  '',
+  '## Closing',
+  '',
+  'Bye.',
+  '',
+].join('\n');
+
+describe.skipIf(!RUN)('document workspace with the real claude CLI', () => {
+  let root: string;
+  const events: DocumentRunEvent[] = [];
+  const annotationEvents: DocumentAnnotationEvent[] = [];
+  const win = {
+    isDestroyed: () => false,
+    webContents: {
+      send: (ch: string, payload: DocumentRunEvent | DocumentAnnotationEvent) => {
+        if (ch === 'document_annotation_event')
+          annotationEvents.push(payload as DocumentAnnotationEvent);
+        else events.push(payload as DocumentRunEvent);
+      },
+    },
+  } as unknown as BrowserWindow;
+
+  function waitForRun(runId: string): Promise<DocumentRunRecord> {
+    return new Promise((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = events.find(
+          (e): e is Extract<DocumentRunEvent, { type: 'run' }> =>
+            e.type === 'run' && e.run.id === runId && e.run.status !== 'running',
+        );
+        if (done) return resolve(done.run);
+        if (Date.now() - started > 240_000) return reject(new Error('run did not finish'));
+        setTimeout(tick, 250);
+      };
+      tick();
+    });
+  }
+
+  beforeAll(() => {
+    process.env.GIT_AUTHOR_NAME ??= 'Test';
+    process.env.GIT_AUTHOR_EMAIL ??= 'test@example.com';
+    process.env.GIT_COMMITTER_NAME ??= 'Test';
+    process.env.GIT_COMMITTER_EMAIL ??= 'test@example.com';
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-docws-real-'));
+    git(root, 'init', '-q', '-b', 'main');
+    fs.writeFileSync(path.join(root, 'notes.md'), DOC);
+    git(root, 'add', '.');
+    git(root, 'commit', '-q', '-m', 'initial');
+  });
+
+  afterAll(() => {
+    if (root) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('proposes, accepts, then resumes the main session with the catch-up diff', async () => {
+    const first = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      instruction:
+        'Replace the sentence in this section with exactly: "The weather is stormy today." Keep the heading.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is nice.',
+        heading: 'Weather',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Claude Code',
+          command: 'claude',
+          isMain: true,
+        },
+      ],
+    });
+    const done = await waitForRun(first.id);
+    const c = done.candidates[0];
+    expect(c.status, c.error).toBe('done');
+    expect(c.sessionId).toBeTruthy();
+    expect(c.commitSha).toBeTruthy();
+    expect(c.outOfScopeFiles ?? []).toEqual([]);
+    expect(c.rationale?.summary).toBeTruthy();
+    const proposed = git(root, 'show', `${c.commitSha}:notes.md`);
+    expect(proposed).toContain('stormy');
+    expect(proposed).toContain('Intro stays as it is.');
+
+    await acceptDocumentCandidate(root, first.id, 'c1');
+    expect(fs.readFileSync(path.join(root, 'notes.md'), 'utf8')).toContain('stormy');
+
+    // Second turn resumes the same session; it must answer from memory of the
+    // instruction it was given while seeing the accepted document.
+    const second = await dispatchDocumentRun(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      instruction:
+        'In this section, add one more sentence after the existing one that repeats, in quotes, the exact sentence you were asked to insert in your previous turn.',
+      scope: {
+        wholeDocument: false,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is stormy today.',
+        heading: 'Weather',
+      },
+      candidates: [
+        {
+          id: 'c1',
+          label: 'A',
+          agentId: 'claude-code',
+          agentName: 'Claude Code',
+          command: 'claude',
+          isMain: true,
+          sessionId: c.sessionId,
+          sessionLastSha: first.baseSha,
+        },
+      ],
+    });
+    const done2 = await waitForRun(second.id);
+    const c2 = done2.candidates[0];
+    expect(c2.status, c2.error).toBe('done');
+    expect(c2.sessionId).toBe(c.sessionId);
+    expect(c2.commitSha).toBeTruthy();
+    const proposed2 = git(root, 'show', `${c2.commitSha}:notes.md`);
+    expect(proposed2).toContain('The weather is stormy today.');
+    expect(proposed2.match(/stormy/g)?.length).toBeGreaterThanOrEqual(2);
+  }, 300_000);
+
+  it('answers a question about a passage without touching the document', async () => {
+    const before = fs.readFileSync(path.join(root, 'notes.md'), 'utf8');
+    const head = git(root, 'rev-parse', 'HEAD').trim();
+    await saveAnnotation(root, {
+      id: 'q-real-1',
+      kind: 'question',
+      text: 'In one short sentence: what is the weather in this passage? Do not edit anything.',
+      anchor: {
+        path: 'notes.md',
+        baseSha: head,
+        startLine: 5,
+        endLine: 7,
+        quote: '## Weather\n\nThe weather is stormy today.',
+        prefix: 'Intro stays as it is.',
+        suffix: '## Closing',
+        heading: 'Weather',
+      },
+      createdAt: new Date().toISOString(),
+    });
+    await askAnnotation(win, {
+      projectRoot: root,
+      documentPath: 'notes.md',
+      annotationId: 'q-real-1',
+      agentId: 'claude-code',
+      agentName: 'Claude Code',
+      command: 'claude',
+    });
+    const answered = await new Promise<DocumentAnnotation>((resolve, reject) => {
+      const started = Date.now();
+      const tick = () => {
+        const done = annotationEvents.find(
+          (e) => e.annotation.id === 'q-real-1' && e.annotation.answerStatus !== 'pending',
+        );
+        if (done) return resolve(done.annotation);
+        if (Date.now() - started > 240_000) return reject(new Error('no answer'));
+        setTimeout(tick, 250);
+      };
+      tick();
+    });
+    expect(answered.answerStatus, answered.answerError).toBe('answered');
+    expect(answered.answer?.text.toLowerCase()).toContain('storm');
+    expect(readAnnotations(root).find((a) => a.id === 'q-real-1')?.answer?.text).toBeTruthy();
+    // Read-only: no file changed, no commit made.
+    expect(fs.readFileSync(path.join(root, 'notes.md'), 'utf8')).toBe(before);
+    expect(git(root, 'rev-parse', 'HEAD').trim()).toBe(head);
+    expect(git(root, 'status', '--porcelain', '--', 'notes.md').trim()).toBe('');
+  }, 300_000);
+});
diff --git a/electron/documents/runs.test.ts b/electron/documents/runs.test.ts
new file mode 100644
index 000000000..a1085d922
--- /dev/null
+++ b/electron/documents/runs.test.ts
@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import {
+  countOutOfScopeHunks,
+  parseCommitBody,
+  sanitizeRunRecord,
+  validateDocumentPath,
+  validateSha,
+} from './runs.js';
+
+describe('validateDocumentPath', () => {
+  it('accepts a relative markdown path and normalizes ./', () => {
+    expect(validateDocumentPath('./docs/spec.md')).toBe('docs/spec.md');
+  });
+  it('rejects traversal, absolute paths and metadata directories', () => {
+    expect(() => validateDocumentPath('../x.md')).toThrow();
+    expect(() => validateDocumentPath('docs/../x.md')).toThrow();
+    expect(() => validateDocumentPath('/abs/x.md')).toThrow();
+    expect(() => validateDocumentPath('.parallel/runs/a.json')).toThrow();
+    expect(() => validateDocumentPath('.worktrees/x/a.md')).toThrow();
+    expect(() => validateDocumentPath('.git/config')).toThrow();
+    expect(validateDocumentPath('.github/README.md')).toBe('.github/README.md');
+    expect(() => validateDocumentPath('')).toThrow();
+    expect(() => validateDocumentPath(3)).toThrow();
+  });
+});
+
+describe('validateSha', () => {
+  it('accepts hex hashes only', () => {
+    expect(validateSha('abcdef1')).toBe('abcdef1');
+    expect(() => validateSha('HEAD~1')).toThrow();
+    expect(() => validateSha('abc')).toThrow();
+  });
+});
+
+describe('countOutOfScopeHunks', () => {
+  const scope = {
+    path: 'a.md',
+    wholeDocument: false,
+    startLine: 10,
+    endLine: 20,
+    quote: '',
+  };
+  it('counts nothing for a whole-document scope', () => {
+    expect(countOutOfScopeHunks('@@ -1,3 +1,4 @@\n', { ...scope, wholeDocument: true })).toBe(0);
+  });
+  it('accepts hunks inside or adjacent to the scope', () => {
+    const diff = ['@@ -10,3 +10,4 @@', '@@ -19,2 +20,2 @@', '@@ -9 +9 @@', '@@ -21 +22 @@'].join(
+      '\n',
+    );
+    expect(countOutOfScopeHunks(diff, scope)).toBe(0);
+  });
+  it('flags hunks clearly outside the scope, including pure insertions', () => {
+    const diff = ['@@ -2,3 +2,4 @@', '@@ -30,0 +32,2 @@', '@@ -15 +16 @@'].join('\n');
+    expect(countOutOfScopeHunks(diff, scope)).toBe(2);
+  });
+  it('treats an insertion right after the scope as in scope', () => {
+    expect(countOutOfScopeHunks('@@ -20,0 +21,3 @@', scope)).toBe(0);
+    expect(countOutOfScopeHunks('@@ -22,0 +23,3 @@', scope)).toBe(1);
+  });
+});
+
+describe('parseCommitBody', () => {
+  it('separates prose from Parallel trailers', () => {
+    const body =
+      'Rewrote the intro.\n\n- shorter\n\nParallel-Run: r1\nParallel-Agent: Claude Code\nParallel-Scope: a.md#L1-L3\n';
+    const { text, trailers } = parseCommitBody(body);
+    expect(text).toBe('Rewrote the intro.\n\n- shorter');
+    expect(trailers).toEqual({ Run: 'r1', Agent: 'Claude Code', Scope: 'a.md#L1-L3' });
+  });
+  it('returns empty trailers for a manual commit', () => {
+    expect(parseCommitBody('just a note').trailers).toEqual({});
+  });
+  it('ignores trailer-shaped lines outside the final paragraph', () => {
+    const body =
+      'Prose.\nParallel-Agent: Human\n\n- more\n\nParallel-Run: r1\nParallel-Agent: Codex';
+    const { text, trailers } = parseCommitBody(body);
+    expect(trailers.Agent).toBe('Codex');
+    expect(text).toContain('Parallel-Agent: Human');
+  });
+  it('treats a mixed last paragraph as prose', () => {
+    expect(parseCommitBody('Parallel-Agent: X\nnot a trailer').trailers).toEqual({});
+  });
+});
+
+describe('sanitizeRunRecord', () => {
+  const root = '/repo';
+  const good = {
+    version: 1,
+    id: 'run-1',
+    documentPath: 'docs/a.md',
+    baseSha: 'abcdef1234567',
+    status: 'finished',
+    createdAt: 'x',
+    instruction: 'i',
+    scope: { path: 'docs/a.md', wholeDocument: true, startLine: 1, endLine: 1, quote: '' },
+    candidates: [
+      {
+        id: 'c1',
+        label: 'A',
+        agentId: 'claude-code',
+        agentName: 'Claude',
+        isMain: false,
+        branch: 'parallel-doc/abc-a',
+        worktreePath: '/repo/.worktrees/parallel-doc/abc-a',
+        status: 'done',
+        commitSha: 'abcdef1234567',
+        startedAt: 'x',
+      },
+    ],
+  };
+  it('accepts a record this app would have written', () => {
+    expect(sanitizeRunRecord(root, good)).not.toBeNull();
+  });
+  it('rejects a worktree path outside .worktrees', () => {
+    const bad = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/home/me/Documents' }],
+    };
+    expect(sanitizeRunRecord(root, bad)).toBeNull();
+    const sneaky = {
+      ...good,
+      candidates: [{ ...good.candidates[0], worktreePath: '/repo/.worktrees/../../etc' }],
+    };
+    expect(sanitizeRunRecord(root, sneaky)).toBeNull();
+  });
+  it('rejects foreign branch names and bad shas', () => {
+    expect(
+      sanitizeRunRecord(root, { ...good, candidates: [{ ...good.candidates[0], branch: 'main' }] }),
+    ).toBeNull();
+    expect(
+      sanitizeRunRecord(root, {
+        ...good,
+        candidates: [{ ...good.candidates[0], commitSha: '--output=x' }],
+      }),
+    ).toBeNull();
+    expect(sanitizeRunRecord(root, { ...good, baseSha: 'HEAD' })).toBeNull();
+  });
+});
diff --git a/electron/documents/runs.ts b/electron/documents/runs.ts
new file mode 100644
index 000000000..48433c9b6
--- /dev/null
+++ b/electron/documents/runs.ts
@@ -0,0 +1,1314 @@
+/**
+ * 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 { spawn, type ChildProcess } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { randomUUID } from 'crypto';
+import type { BrowserWindow } from 'electron';
+import { IPC } from '../ipc/channels.js';
+import { errMessage } from '../log.js';
+import { atomicWriteFileSync } from '../mcp/atomic.js';
+import { buildPtySpawnEnv, validateCommand } from '../ipc/pty.js';
+import { loadEnvFile } from '../ipc/env-file.js';
+import { createWorktree, ensureWorktreeContainerExclude, removeWorktree } from '../ipc/git.js';
+import { git, gitOk } from './git.js';
+import { buildHeadlessLaunch, createHeadlessParser } from './agents.js';
+import { buildDocumentPrompt, parseDocumentRationale } from './prompt.js';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from './shared.js';
+import type {
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentHistoryEntry,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from './types.js';
+
+/** A proposal that runs longer than this is killed and marked failed. */
+const CANDIDATE_TIMEOUT_MS = 30 * 60_000;
+/** Longest instruction accepted from the renderer. */
+const MAX_INSTRUCTION_CHARS = 20_000;
+const RUNS_DIR = path.join('.parallel', 'runs');
+/** Annotations ride along with content commits; kept in sync with document-annotations.ts. */
+const ANNOTATIONS_FILE = path.posix.join('.parallel', 'annotations.json');
+const MAIN_WORKTREE_DIR = path.join('.worktrees', 'parallel-doc-main');
+const BRANCH_PREFIX = 'parallel-doc';
+const WATCH_DEBOUNCE_MS = 200;
+const WATCH_POLL_MS = 3_000;
+const STDERR_TAIL_CHARS = 4_000;
+const MAX_LOG_LINE_CHARS = 4_000;
+/** Grace period between SIGTERM and SIGKILL when cancelling a candidate. */
+const KILL_GRACE_MS = 5_000;
+/** How long rejection waits for killed processes to settle before cleaning up. */
+const SETTLE_WAIT_MS = 8_000;
+/** Files the app seeds into a worktree; never the agent's doing. */
+const SEEDED_PREFIXES = ['.claude/'];
+
+// --- Validation -----------------------------------------------------------
+
+/** A document path is repo-relative and stays inside the project's content. */
+export function validateDocumentPath(value: unknown): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error('documentPath must be a string');
+  const normalized = value.replace(/\\/g, '/').replace(/^\.\//, '');
+  if (path.isAbsolute(normalized)) throw new Error('documentPath must be relative');
+  if (normalized.split('/').some((seg) => seg === '..' || seg === ''))
+    throw new Error('documentPath must not contain ".." or empty segments');
+  if (/^\.(parallel|worktrees|git)(\/|$)/.test(normalized))
+    throw new Error('documentPath must not point into .parallel, .worktrees or .git');
+  return normalized;
+}
+
+function validateRunId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{4,64}$/i.test(value))
+    throw new Error('runId is invalid');
+  return value;
+}
+
+function validateCandidateId(value: unknown): string {
+  if (typeof value !== 'string' || !/^[a-z0-9-]{1,64}$/i.test(value))
+    throw new Error('candidateId is invalid');
+  return value;
+}
+
+export function validateSha(value: unknown, label = 'sha'): string {
+  if (typeof value !== 'string' || !/^[0-9a-f]{7,64}$/i.test(value))
+    throw new Error(`${label} must be a commit hash`);
+  return value;
+}
+
+const BRANCH_RE = /^parallel-doc\/[a-z0-9][a-z0-9-]{0,80}$/;
+
+function validateScope(value: unknown, documentPath: string): DocumentScope {
+  if (!value || typeof value !== 'object') throw new Error('scope must be an object');
+  const s = value as Record<string, unknown>;
+  const wholeDocument = s.wholeDocument === true;
+  const startLine = Number(s.startLine);
+  const endLine = Number(s.endLine);
+  if (!wholeDocument) {
+    if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1)
+      throw new Error('scope lines must be positive integers');
+    if (endLine < startLine) throw new Error('scope endLine must not precede startLine');
+  }
+  const quote = typeof s.quote === 'string' ? s.quote : '';
+  const heading = typeof s.heading === 'string' && s.heading.trim() ? s.heading.trim() : undefined;
+  return {
+    path: documentPath,
+    wholeDocument,
+    startLine: wholeDocument ? 1 : startLine,
+    endLine: wholeDocument ? 1 : endLine,
+    quote: quote.slice(0, 20_000),
+    heading,
+  };
+}
+
+function validateCandidateSpecs(value: unknown): DocumentCandidateSpec[] {
+  if (!Array.isArray(value) || value.length === 0) throw new Error('candidates must be a list');
+  if (value.length > MAX_DOCUMENT_CANDIDATES)
+    throw new Error(`At most ${MAX_DOCUMENT_CANDIDATES} candidates per run`);
+  const seen = new Set<string>();
+  return value.map((raw): DocumentCandidateSpec => {
+    if (!raw || typeof raw !== 'object') throw new Error('candidate must be an object');
+    const c = raw as Record<string, unknown>;
+    const id = validateCandidateId(c.id);
+    if (seen.has(id)) throw new Error('duplicate candidate id');
+    seen.add(id);
+    const str = (key: string): string => {
+      const v = c[key];
+      if (typeof v !== 'string' || !v.trim()) throw new Error(`candidate.${key} must be a string`);
+      return v;
+    };
+    const optStr = (key: string): string | undefined => {
+      const v = c[key];
+      if (v === undefined || v === null || v === '') return undefined;
+      if (typeof v !== 'string') throw new Error(`candidate.${key} must be a string`);
+      return v;
+    };
+    const label = str('label');
+    if (!/^[A-Za-z0-9 _-]{1,24}$/.test(label)) throw new Error('candidate.label is invalid');
+    const agentId = str('agentId');
+    if (!documentAgentSupport(agentId).headless)
+      throw new Error(`Agent "${agentId}" has no headless mode for document runs.`);
+    const command = str('command');
+    if (/[\s;&|<>$`'"\\]/.test(command)) throw new Error('candidate.command is invalid');
+    // Session ids and shas are handed to CLIs and git as positional values;
+    // a leading dash would turn them into flags.
+    const sessionId = optStr('sessionId');
+    if (sessionId && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(sessionId))
+      throw new Error('candidate.sessionId is invalid');
+    const sessionLastShaRaw = optStr('sessionLastSha');
+    const sessionLastSha =
+      sessionLastShaRaw === undefined
+        ? undefined
+        : validateSha(sessionLastShaRaw, 'candidate.sessionLastSha');
+    return {
+      id,
+      label,
+      agentId,
+      agentName: str('agentName').slice(0, 64),
+      command,
+      isMain: c.isMain === true,
+      sessionId,
+      sessionLastSha,
+      envFile: optStr('envFile'),
+    };
+  });
+}
+
+/** True when `candidate` (typically a persisted path) resolves under `dir`. */
+function isInside(dir: string, candidate: string): boolean {
+  const rel = path.relative(path.resolve(dir), path.resolve(candidate));
+  return rel.length > 0 && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// --- Snapshots and watcher ------------------------------------------------
+
+async function headSha(projectRoot: string): Promise<string | null> {
+  try {
+    return (await git(projectRoot, ['rev-parse', '--verify', 'HEAD'])).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function currentBranch(projectRoot: string): Promise<string | null> {
+  try {
+    const out = (await git(projectRoot, ['symbolic-ref', '--short', '-q', 'HEAD'])).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Pathspec for "pending edits": tracked content only, never run records. */
+const CONTENT_PATHSPEC = ['--', '.', ':(exclude).parallel'];
+
+/**
+ * Uncommitted changes to tracked files. Untracked files are deliberately not
+ * "pending edits": sweeping them into a commit would put scratch files into
+ * the canonical history.
+ */
+async function isDirty(projectRoot: string): Promise<boolean> {
+  const out = await git(projectRoot, [
+    'status',
+    '--porcelain',
+    '--untracked-files=no',
+    ...CONTENT_PATHSPEC,
+  ]);
+  return out.trim().length > 0;
+}
+
+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');
+}
+
+/**
+ * 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');
+    return sanitizeRunRecord(projectRoot, JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function requireRunRecord(projectRoot: string, runId: string): DocumentRunRecord {
+  const run = readRunRecord(projectRoot, runId);
+  if (!run) throw new Error(`Run ${runId} not found`);
+  return run;
+}
+
+// --- Active runs ----------------------------------------------------------
+
+interface ActiveCandidate {
+  proc: ChildProcess;
+  timer: ReturnType<typeof setTimeout>;
+  killTimer: ReturnType<typeof setTimeout> | null;
+  cancelled: boolean;
+  /** Resolves once the process has exited and its record was written. */
+  settled: Promise<void>;
+  resolveSettled: () => void;
+  /** Record of the candidate this process works for. */
+  candidate: DocumentCandidateRecord;
+}
+
+interface ActiveRun {
+  projectRoot: string;
+  candidates: Map<string, ActiveCandidate>;
+}
+
+const activeRuns = new Map<string, ActiveRun>();
+const projectLocks = new Map<string, Promise<void>>();
+
+function withProjectLock<T>(projectRoot: string, fn: () => Promise<T>): Promise<T> {
+  const key = path.resolve(projectRoot);
+  const prev = projectLocks.get(key) ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  projectLocks.set(
+    key,
+    next.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return next;
+}
+
+function sendEvent(win: BrowserWindow, event: DocumentRunEvent): void {
+  if (!win.isDestroyed()) win.webContents.send(IPC.DocumentRunEvent, event);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+/** Whether an active run in this project still has its main candidate working. */
+function mainSessionBusy(projectRoot: string): boolean {
+  const root = path.resolve(projectRoot);
+  for (const run of activeRuns.values()) {
+    if (path.resolve(run.projectRoot) !== root) continue;
+    for (const entry of run.candidates.values()) {
+      if (entry.candidate.isMain) return true;
+    }
+  }
+  return false;
+}
+
+/** Kills a candidate's whole process group, escalating to SIGKILL after a grace period. */
+function killCandidate(entry: ActiveCandidate): void {
+  const pid = entry.proc.pid;
+  if (!pid || entry.proc.exitCode !== null || entry.proc.signalCode !== null) return;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      // Negative pid: the process group created by `detached: true`.
+      process.kill(-pid, sig);
+    } catch {
+      try {
+        entry.proc.kill(sig);
+      } catch {
+        // Already gone.
+      }
+    }
+  };
+  signal('SIGTERM');
+  if (!entry.killTimer) {
+    entry.killTimer = setTimeout(() => signal('SIGKILL'), KILL_GRACE_MS);
+    entry.killTimer.unref?.();
+  }
+}
+
+/** Runs the app persisted as running but that no process backs any more. */
+function reconcileInterrupted(projectRoot: string, run: DocumentRunRecord): DocumentRunRecord {
+  if (run.status !== 'running' || activeRuns.has(run.id)) return run;
+  for (const c of run.candidates) {
+    if (c.status === 'running') {
+      c.status = 'interrupted';
+      c.finishedAt = nowIso();
+      c.error = 'The app was closed while this proposal was running.';
+    }
+  }
+  run.status = 'finished';
+  run.finishedAt = run.finishedAt ?? nowIso();
+  writeRunRecord(projectRoot, run);
+  return run;
+}
+
+export function listDocumentRuns(projectRoot: string): DocumentRunRecord[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(runsDir(projectRoot)).filter((n) => n.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  const runs: DocumentRunRecord[] = [];
+  for (const name of names) {
+    const run = readRunRecord(projectRoot, name.slice(0, -'.json'.length));
+    if (run) runs.push(reconcileInterrupted(projectRoot, run));
+  }
+  runs.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  return runs;
+}
+
+/** The run whose candidate owns `branch`, if any record says so. */
+function runOwningBranch(projectRoot: string, branch: string): DocumentRunRecord | undefined {
+  return listDocumentRuns(projectRoot).find((r) => r.candidates.some((c) => c.branch === branch));
+}
+
+// --- Pending manual edits -------------------------------------------------
+
+/**
+ * Tracked content that differs from HEAD: what the user has been editing.
+ * `--diff-filter=MDT` leaves out additions, so a new file the user staged by
+ * hand is not swept into a commit this app writes.
+ */
+async function pendingContentPaths(projectRoot: string): Promise<string[]> {
+  const out = await git(projectRoot, [
+    'diff',
+    '--name-only',
+    '-z',
+    '--diff-filter=MDT',
+    'HEAD',
+    ...CONTENT_PATHSPEC,
+  ]).catch(() => '');
+  return out.split('\0').filter(Boolean);
+}
+
+/**
+ * Commits the user's edits to tracked files as a plain commit, so the run
+ * has a real base. Returns HEAD afterwards. Throws in an empty repository.
+ */
+export async function commitPendingEdits(projectRoot: string): Promise<string> {
+  ensureWorktreeContainerExclude(projectRoot);
+  const paths = await pendingContentPaths(projectRoot);
+  await git(projectRoot, ['add', '-u', ...CONTENT_PATHSPEC]);
+  if (await stageAnnotations(projectRoot)) paths.push(ANNOTATIONS_FILE);
+  if (paths.length > 0) await commitPaths(projectRoot, 'Manual edits', paths);
+  const sha = await headSha(projectRoot);
+  if (!sha) throw new Error('The project repository has no commits yet.');
+  return sha;
+}
+
+/**
+ * Commits exactly `paths`. `--only` takes them from the working tree and
+ * leaves the rest of the index alone, so whatever the user had staged stays
+ * staged instead of riding along in a commit this app attributes to itself.
+ */
+async function commitPaths(projectRoot: string, message: string, paths: string[]): Promise<void> {
+  await git(projectRoot, ['commit', '-q', '--only', '-m', message, '--', ...paths]);
+}
+
+/**
+ * Annotations are committed alongside content and metadata, never on their
+ * own. Returns true when the file exists and differs from HEAD.
+ */
+async function stageAnnotations(projectRoot: string): Promise<boolean> {
+  if (!fs.existsSync(path.join(projectRoot, ANNOTATIONS_FILE))) return false;
+  if (!(await gitOk(projectRoot, ['add', '-f', '--', ANNOTATIONS_FILE]))) return false;
+  return !(await gitOk(projectRoot, ['diff', '--cached', '--quiet', '--', ANNOTATIONS_FILE]));
+}
+
+// --- Worktrees ------------------------------------------------------------
+
+function shortRunId(runId: string): string {
+  return runId.replace(/-/g, '').slice(0, 8);
+}
+
+function candidateBranch(runId: string, label: string): string {
+  return `${BRANCH_PREFIX}/${shortRunId(runId)}-${label.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+}
+
+/** The main session keeps one worktree so its working directory never changes. */
+async function prepareMainWorktree(
+  projectRoot: string,
+  branch: string,
+  baseSha: string,
+): Promise<string> {
+  const worktreePath = path.join(projectRoot, MAIN_WORKTREE_DIR);
+  ensureWorktreeContainerExclude(projectRoot);
+  await gitOk(projectRoot, ['worktree', 'prune']);
+  if (!fs.existsSync(path.join(worktreePath, '.git'))) {
+    fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+    await git(projectRoot, ['worktree', 'add', '-b', branch, worktreePath, baseSha]);
+    return worktreePath;
+  }
+  const previous = await currentBranch(worktreePath);
+  await git(worktreePath, ['reset', '--hard', '-q']);
+  await git(worktreePath, ['clean', '-fdq']);
+  await git(worktreePath, ['checkout', '-q', '-B', branch, baseSha]);
+  // The branch the worktree just left belongs to an earlier run. Drop it
+  // once that run is settled; a proposal still under review keeps its branch.
+  if (previous && previous !== branch && BRANCH_RE.test(previous)) {
+    const owner = runOwningBranch(projectRoot, previous);
+    if (!owner || owner.status === 'accepted' || owner.status === 'rejected') {
+      await gitOk(projectRoot, ['branch', '-D', previous]);
+    }
+  }
+  return worktreePath;
+}
+
+async function prepareAlternateWorktree(
+  projectRoot: string,
+  branch: string,
+  baseSha: string,
+): Promise<string> {
+  const { path: worktreePath } = await createWorktree(projectRoot, branch, [], baseSha, true);
+  return worktreePath;
+}
+
+async function cleanupCandidate(
+  projectRoot: string,
+  candidate: DocumentCandidateRecord,
+): Promise<void> {
+  // Records are sanitized on load, but this is the destructive step: check again.
+  if (!BRANCH_RE.test(candidate.branch)) return;
+  if (!isInside(path.join(projectRoot, '.worktrees'), candidate.worktreePath)) return;
+  if (candidate.isMain) {
+    // The persistent worktree stays; only drop the branch when it is no
+    // longer checked out there (the next dispatch moves it and deletes it).
+    const mainPath = path.join(projectRoot, MAIN_WORKTREE_DIR);
+    const checkedOut = await currentBranch(mainPath).catch(() => null);
+    if (checkedOut !== candidate.branch)
+      await gitOk(projectRoot, ['branch', '-D', candidate.branch]);
+    return;
+  }
+  await removeWorktree(projectRoot, candidate.branch, true, candidate.worktreePath).catch((err) =>
+    console.warn(`[documents] cleanup of ${candidate.branch} failed:`, err),
+  );
+}
+
+// --- Scope enforcement ----------------------------------------------------
+
+/** Counts hunks of a `-U0` diff whose old-file range lies outside the scope. */
+export function countOutOfScopeHunks(diffU0: string, scope: DocumentScope): number {
+  if (scope.wholeDocument) return 0;
+  let count = 0;
+  const re = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/gm;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(diffU0)) !== null) {
+    const start = Number(m[1]);
+    const len = m[2] === undefined ? 1 : Number(m[2]);
+    // A pure insertion reports the line *before* it with length 0; treat it
+    // as touching that line and the next.
+    const from = start;
+    const to = len === 0 ? start + 1 : start + len - 1;
+    // One line of slack on either side: agents routinely re-wrap the
+    // neighbouring blank line or paragraph boundary.
+    const inScope = to >= scope.startLine - 1 && from <= scope.endLine + 1;
+    if (!inScope) count++;
+  }
+  return count;
+}
+
+// --- Dispatch -------------------------------------------------------------
+
+export interface DispatchDocumentRunArgs {
+  projectRoot: string;
+  documentPath: unknown;
+  instruction: unknown;
+  scope: unknown;
+  candidates: unknown;
+}
+
+function parseChangedPaths(porcelainZ: string): string[] {
+  const out: string[] = [];
+  for (const entry of porcelainZ.split('\0')) {
+    if (!entry.trim()) continue;
+    // "XY path". Renames would add a second, status-less NUL entry that this
+    // would mangle — callers reset the index first, so status never reports
+    // one here.
+    const p = entry.slice(3);
+    if (p) out.push(p);
+  }
+  return out;
+}
+
+function trailerBlock(entries: [string, string][]): string {
+  return entries
+    .filter(([, v]) => v.trim().length > 0)
+    .map(([k, v]) => `Parallel-${k}: ${v.replace(/\s+/g, ' ').trim()}`)
+    .join('\n');
+}
+
+function scopeTrailer(scope: DocumentScope): string {
+  if (scope.wholeDocument) return scope.path;
+  return `${scope.path}#L${scope.startLine}-L${scope.endLine}`;
+}
+
+function commitTitle(summary: string, fallback: string): string {
+  const line = (summary || fallback).split('\n')[0].trim();
+  return line.length > 72 ? line.slice(0, 69).trimEnd() + '…' : line;
+}
+
+/** Agent-written text that lands in a commit body: one line, no trailer look-alikes. */
+function bodyLine(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .replace(/^Parallel-/i, 'Parallel ')
+    .trim();
+}
+
+/**
+ * Turns whatever the agent left in its worktree into a proposal commit that
+ * contains only the document, and records what was stripped.
+ */
+async function finalizeCandidate(
+  run: DocumentRunRecord,
+  candidate: DocumentCandidateRecord,
+  outcome: { resultText: string; sessionId?: string; error?: string },
+  exitCode: number | null,
+  stderrTail: string,
+  cancelled: boolean,
+): Promise<void> {
+  const { worktreePath } = candidate;
+  candidate.exitCode = exitCode;
+  candidate.finishedAt = nowIso();
+  if (outcome.sessionId) candidate.sessionId = outcome.sessionId;
+  candidate.resultText = outcome.resultText.slice(0, 50_000);
+
+  if (cancelled) {
+    candidate.status = 'cancelled';
+    candidate.error = 'Cancelled.';
+    return;
+  }
+
+  try {
+    // The worktree must still be on this candidate's branch; otherwise the
+    // commit would land on someone else's proposal.
+    const onBranch = await currentBranch(worktreePath);
+    if (onBranch !== candidate.branch) {
+      throw new Error(
+        `The worktree moved to '${onBranch ?? 'a detached HEAD'}' while the agent was working.`,
+      );
+    }
+
+    // An agent with a shell may have staged files; scope is judged against
+    // HEAD, not the index, so unstage everything first.
+    await git(worktreePath, ['reset', '-q']);
+    const docPath = run.documentPath;
+    const changed = parseChangedPaths(
+      await git(worktreePath, ['status', '--porcelain', '-z', '--untracked-files=all']),
+    );
+    const outOfScope = changed.filter(
+      (p) => p !== docPath && !SEEDED_PREFIXES.some((prefix) => p.startsWith(prefix)),
+    );
+    if (changed.some((p) => p !== docPath)) {
+      // Keep the document edit, drop everything else.
+      const docAbs = path.join(worktreePath, docPath);
+      const keep = fs.existsSync(docAbs) ? fs.readFileSync(docAbs, 'utf-8') : null;
+      await git(worktreePath, ['checkout', '-q', '--', '.']);
+      await git(worktreePath, ['clean', '-fdq']);
+      if (keep !== null) fs.writeFileSync(docAbs, keep);
+    }
+    if (outOfScope.length > 0) candidate.outOfScopeFiles = outOfScope.slice(0, 50);
+
+    const docChanged = !(await gitOk(worktreePath, ['diff', '--quiet', 'HEAD', '--', docPath]));
+    const rationale = parseDocumentRationale(outcome.resultText);
+    candidate.rationale = rationale;
+
+    if (!docChanged) {
+      candidate.noChanges = true;
+      candidate.commitSha = null;
+      candidate.status = outcome.error || (exitCode !== 0 && exitCode !== null) ? 'failed' : 'done';
+      candidate.error = outcome.error ?? (candidate.status === 'failed' ? stderrTail : undefined);
+      return;
+    }
+
+    const diffU0 = await git(worktreePath, ['diff', '-U0', 'HEAD', '--', docPath]);
+    const strayHunks = countOutOfScopeHunks(diffU0, run.scope);
+    if (strayHunks > 0) candidate.outOfScopeHunks = strayHunks;
+
+    const body = [
+      commitTitle(bodyLine(rationale.summary), `Proposal from ${candidate.agentName}`),
+      '',
+      ...rationale.changes.map((c) => `- ${bodyLine(c)}`),
+      '',
+      trailerBlock([
+        ['Run', run.id],
+        ['Agent', candidate.agentName],
+        ['Candidate', candidate.label],
+        ['Scope', scopeTrailer(run.scope)],
+        ['Base', run.baseSha],
+      ]),
+    ].join('\n');
+    await git(worktreePath, ['add', '--', docPath]);
+    await git(worktreePath, ['commit', '-q', '--only', '-m', body, '--', docPath]);
+    const committed = (await git(worktreePath, ['show', '--format=', '--name-only', 'HEAD']))
+      .split('\n')
+      .filter((l) => l.trim());
+    if (committed.length !== 1 || committed[0] !== docPath) {
+      throw new Error(`Proposal commit touched ${committed.join(', ')} instead of ${docPath}.`);
+    }
+    candidate.commitSha = (await git(worktreePath, ['rev-parse', 'HEAD'])).trim();
+    candidate.status = 'done';
+    if (outcome.error) candidate.error = outcome.error;
+  } catch (err) {
+    candidate.status = 'failed';
+    candidate.error = errMessage(err);
+    candidate.commitSha = null;
+  }
+}
+
+/**
+ * Persists a finished candidate under the project lock, re-reading the
+ * record so a note or a rejection written meanwhile survives. Returns the
+ * record as stored.
+ */
+async function storeCandidateResult(
+  projectRoot: string,
+  runId: string,
+  candidate: DocumentCandidateRecord,
+  allSettled: boolean,
+): Promise<DocumentRunRecord | null> {
+  return withProjectLock(projectRoot, async () => {
+    const fresh = readRunRecord(projectRoot, runId);
+    if (!fresh) return null;
+    const idx = fresh.candidates.findIndex((c) => c.id === candidate.id);
+    const stored = idx >= 0 ? fresh.candidates[idx] : undefined;
+    const merged: DocumentCandidateRecord = { ...candidate, note: stored?.note ?? candidate.note };
+    // A rejection that landed first wins over the process's own verdict.
+    if (stored?.status === 'cancelled' && fresh.status === 'rejected') merged.status = 'cancelled';
+    if (idx >= 0) fresh.candidates[idx] = merged;
+    else fresh.candidates.push(merged);
+    if (allSettled && fresh.status === 'running') {
+      fresh.status = 'finished';
+      fresh.finishedAt = nowIso();
+    }
+    writeRunRecord(projectRoot, fresh);
+    return fresh;
+  });
+}
+
+function spawnCandidate(
+  win: BrowserWindow,
+  projectRoot: string,
+  run: DocumentRunRecord,
+  spec: DocumentCandidateSpec,
+  candidate: DocumentCandidateRecord,
+  prompt: string,
+): void {
+  const active = activeRuns.get(run.id);
+  if (!active) return;
+
+  const launch = buildHeadlessLaunch({
+    agentId: spec.agentId,
+    command: spec.command,
+    prompt,
+    sessionId: spec.sessionId,
+    newSessionId: randomUUID(),
+  });
+  const fileEnv = spec.envFile?.trim() ? loadEnvFile(spec.envFile) : {};
+  const env = buildPtySpawnEnv({}, fileEnv);
+  const parser = createHeadlessParser(spec.agentId);
+
+  const proc = spawn(launch.command, launch.args, {
+    cwd: candidate.worktreePath,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // Own process group, so cancelling reaches the CLI's children too.
+    detached: true,
+  });
+  proc.stdout?.setEncoding('utf8');
+  proc.stderr?.setEncoding('utf8');
+
+  let resolveSettled: () => void = () => undefined;
+  const settled = new Promise<void>((resolve) => {
+    resolveSettled = resolve;
+  });
+  const entry: ActiveCandidate = {
+    proc,
+    cancelled: false,
+    killTimer: null,
+    settled,
+    resolveSettled,
+    candidate,
+    timer: setTimeout(() => {
+      candidate.error = 'Timed out.';
+      killCandidate(entry);
+    }, CANDIDATE_TIMEOUT_MS),
+  };
+  active.candidates.set(candidate.id, entry);
+
+  let stderrTail = '';
+  const log = (text: string) => {
+    const clipped =
+      text.length > MAX_LOG_LINE_CHARS ? text.slice(0, MAX_LOG_LINE_CHARS) + '…' : text;
+    sendEvent(win, {
+      type: 'log',
+      projectRoot,
+      runId: run.id,
+      candidateId: candidate.id,
+      text: clipped,
+    });
+  };
+
+  proc.stdout?.on('data', (chunk: string) => {
+    for (const line of parser.feed(chunk)) log(line);
+  });
+  proc.stderr?.on('data', (chunk: string) => {
+    stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+    if (chunk.trim()) log(chunk.trimEnd());
+  });
+
+  let settledOnce = false;
+  const settle = async (exitCode: number | null, spawnError?: Error) => {
+    if (settledOnce) return;
+    settledOnce = true;
+    clearTimeout(entry.timer);
+    if (entry.killTimer) clearTimeout(entry.killTimer);
+    const outcome = parser.finish();
+    if (spawnError) outcome.error = spawnError.message;
+    else if (candidate.error === 'Timed out.') outcome.error = 'Timed out.';
+    await finalizeCandidate(run, candidate, outcome, exitCode, stderrTail, entry.cancelled);
+    active.candidates.delete(candidate.id);
+    const allSettled = active.candidates.size === 0;
+    if (allSettled) activeRuns.delete(run.id);
+    let stored: DocumentRunRecord | null = null;
+    try {
+      stored = await storeCandidateResult(projectRoot, run.id, candidate, allSettled);
+    } catch (err) {
+      console.warn('[documents] failed to write run record:', err);
+    }
+    sendEvent(win, { type: 'candidate', projectRoot, runId: run.id, candidate });
+    if (stored && stored.status !== 'running') {
+      sendEvent(win, { type: 'run', projectRoot, run: stored });
+    }
+    entry.resolveSettled();
+  };
+
+  proc.on('close', (code) => void settle(code));
+  proc.on('error', (err) => void settle(1, err));
+}
+
+export async function dispatchDocumentRun(
+  win: BrowserWindow,
+  args: DispatchDocumentRunArgs,
+): Promise<DocumentRunRecord> {
+  const { projectRoot } = args;
+  const documentPath = validateDocumentPath(args.documentPath);
+  if (typeof args.instruction !== 'string' || !args.instruction.trim())
+    throw new Error('instruction must be a non-empty string');
+  if (args.instruction.length > MAX_INSTRUCTION_CHARS) throw new Error('instruction is too long');
+  const instruction = args.instruction;
+  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}`);
+    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 = {
+      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();
+      }
+    }
+
+    // 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;
+    }
+    if (stored.status === 'running' && !activeRuns.has(runId)) {
+      stored.status = 'finished';
+      stored.finishedAt = stored.finishedAt ?? nowIso();
+    }
+    writeRunRecord(projectRoot, stored);
+    sendEvent(win, { type: 'run', projectRoot, run: stored });
+    return stored;
+  });
+}
+
+/** Signals every candidate of a run; returns a promise that settles when they have exited. */
+function killRun(runId: string): Promise<void> {
+  const active = activeRuns.get(runId);
+  if (!active) return Promise.resolve();
+  const pending: Promise<void>[] = [];
+  for (const entry of active.candidates.values()) {
+    entry.cancelled = true;
+    killCandidate(entry);
+    pending.push(entry.settled);
+  }
+  return Promise.all(pending).then(() => undefined);
+}
+
+export function cancelDocumentRun(runId: unknown): void {
+  void killRun(validateRunId(runId));
+}
+
+// --- Accept / reject ------------------------------------------------------
+
+function integrationMessage(run: DocumentRunRecord, candidate: DocumentCandidateRecord): string {
+  const rationale = candidate.rationale;
+  const lines = [
+    commitTitle(bodyLine(rationale?.summary ?? ''), `Accept proposal from ${candidate.agentName}`),
+    '',
+  ];
+  const section = (label: string, items: string[] | undefined) => {
+    if (!items?.length) return;
+    lines.push(label, ...items.map((c) => `- ${bodyLine(c)}`), '');
+  };
+  section('Changes:', rationale?.changes);
+  section('Assumptions:', rationale?.assumptions);
+  section('Open questions:', rationale?.questions);
+  lines.push(
+    trailerBlock([
+      ['Run', run.id],
+      ['Agent', candidate.agentName],
+      ['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)]);
+      // 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';
+      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);
+  // Let killed processes settle before their worktrees go away; a CLI that
+  // ignores signals is not allowed to hold the rejection hostage.
+  await Promise.race([
+    killRun(runId),
+    new Promise<void>((resolve) => setTimeout(resolve, SETTLE_WAIT_MS).unref?.()),
+  ]);
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    if (run.status === 'accepted') throw new Error('An accepted run cannot be rejected.');
+    activeRuns.delete(runId);
+    for (const c of run.candidates) await cleanupCandidate(projectRoot, c);
+    run.status = 'rejected';
+    run.finishedAt = run.finishedAt ?? nowIso();
+    for (const c of run.candidates) {
+      if (c.status === 'running') c.status = 'cancelled';
+    }
+    writeRunRecord(projectRoot, run);
+    // Keep the record in history (it documents what was tried) without
+    // touching content: a metadata-only commit the history view filters out.
+    try {
+      await git(projectRoot, ['add', '-f', '--', runRecordRelPath(runId)]);
+      const paths = [runRecordRelPath(runId)];
+      if (await stageAnnotations(projectRoot)) paths.push(ANNOTATIONS_FILE);
+      await commitPaths(
+        projectRoot,
+        `Reject proposals\n\nParallel-Run: ${runId}\nParallel-Metadata: true`,
+        paths,
+      );
+    } catch (err) {
+      console.warn('[documents] could not commit rejected run record:', err);
+    }
+    return run;
+  });
+}
+
+export function setDocumentCandidateNote(
+  projectRoot: string,
+  runIdRaw: unknown,
+  candidateIdRaw: unknown,
+  note: unknown,
+): Promise<DocumentRunRecord> {
+  const runId = validateRunId(runIdRaw);
+  const candidateId = validateCandidateId(candidateIdRaw);
+  if (typeof note !== 'string') throw new Error('note must be a string');
+  return withProjectLock(projectRoot, async () => {
+    const run = requireRunRecord(projectRoot, runId);
+    const candidate = run.candidates.find((c) => c.id === candidateId);
+    if (!candidate) throw new Error('Candidate not found');
+    candidate.note = note.slice(0, 5_000) || undefined;
+    writeRunRecord(projectRoot, run);
+    return run;
+  });
+}
+
+// --- History --------------------------------------------------------------
+
+const TRAILER_RE = /^Parallel-([A-Za-z]+):\s*(.*)$/;
+
+/**
+ * Splits a commit body into prose and `Parallel-*` trailers. Only the last
+ * paragraph counts as trailers, like git itself, so agent prose that happens
+ * to contain a trailer-shaped line cannot re-attribute a commit. Exported
+ * for tests.
+ */
+export function parseCommitBody(body: string): { text: string; trailers: Record<string, string> } {
+  const trimmed = body.replace(/\s+$/, '');
+  const paragraphs = trimmed.split(/\n\s*\n/);
+  const last = paragraphs[paragraphs.length - 1] ?? '';
+  const lastLines = last.split('\n').map((l) => l.trim());
+  const isTrailerBlock = lastLines.length > 0 && lastLines.every((l) => TRAILER_RE.test(l));
+  const trailers: Record<string, string> = {};
+  if (isTrailerBlock) {
+    for (const line of lastLines) {
+      const m = TRAILER_RE.exec(line);
+      if (m) trailers[m[1]] = m[2].trim();
+    }
+    paragraphs.pop();
+  }
+  return { text: paragraphs.join('\n\n').trim(), trailers };
+}
+
+export async function getDocumentHistory(
+  projectRoot: string,
+  documentPath: string,
+  wholeProject: boolean,
+  limit = 200,
+): Promise<DocumentHistoryEntry[]> {
+  const pathArgs = wholeProject ? ['--', '.', ':(exclude).parallel'] : ['--', documentPath];
+  let out = '';
+  try {
+    out = await git(projectRoot, [
+      'log',
+      `--max-count=${limit}`,
+      '--format=%H%x1f%h%x1f%an%x1f%at%x1f%s%x1f%b%x1e',
+      ...pathArgs,
+    ]);
+  } catch {
+    return [];
+  }
+  const entries: DocumentHistoryEntry[] = [];
+  for (const record of out.split('\x1e')) {
+    if (!record.trim()) continue;
+    const [sha, shortSha, author, at, subject, body = ''] = record.replace(/^\n/, '').split('\x1f');
+    if (!sha) continue;
+    const { text, trailers } = parseCommitBody(body);
+    entries.push({
+      sha,
+      shortSha,
+      subject,
+      body: text,
+      author,
+      timestamp: Number(at) || 0,
+      trailers,
+      manual: !trailers.Agent,
+    });
+  }
+  return entries;
+}
+
+export async function getDocumentAtCommit(
+  projectRoot: string,
+  sha: string,
+  documentPath: string,
+): Promise<string | null> {
+  try {
+    return await git(projectRoot, ['show', `${sha}:${documentPath}`]);
+  } catch {
+    return null;
+  }
+}
+
+/** Git's well-known empty tree, what a root commit is diffed against. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+/** Unified diff of one document between two commits (`from` may be `<sha>^`). */
+export async function getDocumentDiff(
+  projectRoot: string,
+  from: string,
+  to: string,
+  documentPath: string,
+): Promise<string> {
+  try {
+    return await git(projectRoot, ['diff', '-U3', `${from}..${to}`, '--', documentPath]);
+  } catch {
+    // `<sha>^` does not exist for a root commit; the whole file is its change.
+    if (!from.endsWith('^')) return '';
+    return git(projectRoot, ['diff', '-U3', `${EMPTY_TREE}..${to}`, '--', documentPath]).catch(
+      () => '',
+    );
+  }
+}
+
+/**
+ * Reverts a commit's content changes with a new commit. Run records under
+ * `.parallel/` are kept as they are: they document what happened, and the
+ * revert itself becomes part of that history.
+ */
+export async function revertDocumentCommit(projectRoot: string, sha: string): Promise<string> {
+  return withProjectLock(projectRoot, async () => {
+    await commitPendingEdits(projectRoot);
+    const subject = (await git(projectRoot, ['log', '-1', '--format=%s', sha])).trim();
+    // The paths the commit touched are the ones the revert may undo; run
+    // records are not among them.
+    const paths = (await git(projectRoot, ['show', '--format=', '--name-only', '-z', sha]))
+      .split('\0')
+      .filter((p) => p && !p.startsWith('.parallel/'));
+    try {
+      await git(projectRoot, ['revert', '--no-commit', sha]);
+      // Restore run records the reverted commit may have added or changed.
+      await gitOk(projectRoot, ['checkout', '-q', 'HEAD', '--', '.parallel']);
+      await gitOk(projectRoot, ['reset', '-q', '--', '.parallel']);
+      if (paths.length === 0) throw new Error('Nothing to revert outside run metadata.');
+      await commitPaths(projectRoot, `Revert "${subject}"\n\nParallel-Revert: ${sha}`, paths);
+    } catch (err) {
+      await gitOk(projectRoot, ['reset', '--hard', '-q', 'HEAD']);
+      await gitOk(projectRoot, ['clean', '-fdq', '--', '.parallel']);
+      throw new Error(`Revert failed: ${errMessage(err)}`);
+    }
+    return (await git(projectRoot, ['rev-parse', 'HEAD'])).trim();
+  });
+}
+
+/** Kill every running proposal process; used on app quit. */
+export function stopAllDocumentRuns(): void {
+  for (const runId of [...activeRuns.keys()]) void killRun(runId);
+}
diff --git a/electron/documents/setup.test.ts b/electron/documents/setup.test.ts
new file mode 100644
index 000000000..e7a96875f
--- /dev/null
+++ b/electron/documents/setup.test.ts
@@ -0,0 +1,174 @@
+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({
+      exists: true,
+      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({
+      exists: true,
+      isRepo: true,
+      enclosingRepo: null,
+      hasCommits: true,
+      files: [
+        { path: 'committed.md', committed: true },
+        { path: 'loose.md', committed: false },
+      ],
+    });
+  });
+
+  it('reports a folder that does not exist yet as empty rather than failing', async () => {
+    const missing = path.join(tmpFolder(), 'not', 'made', 'yet');
+
+    expect(await inspectDocumentFolder(missing)).toEqual({
+      exists: false,
+      isRepo: false,
+      enclosingRepo: null,
+      hasCommits: false,
+      files: [],
+    });
+  });
+
+  it('names the enclosing repository instead of claiming a subfolder is one', async () => {
+    const dir = tmpFolder();
+    initRepo(dir);
+    fs.mkdirSync(path.join(dir, 'sub'));
+
+    const info = await inspectDocumentFolder(path.join(dir, 'sub'));
+    expect(info.isRepo).toBe(false);
+    expect(info.enclosingRepo).toBe(fs.realpathSync(dir));
+  });
+});
+
+describe('prepareDocumentProject', () => {
+  it('turns a plain folder into a repository with the document committed', async () => {
+    const dir = tmpFolder();
+    fs.writeFileSync(path.join(dir, 'plan.md'), '# Plan\n');
+
+    const result = await prepareDocumentProject(dir, 'plan.md');
+
+    expect(result.documentPath).toBe('plan.md');
+    expect(result.actions).toEqual(['Initialised a Git repository', 'Committed plan.md']);
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('plan.md');
+  });
+
+  it('creates the folder itself when the path does not exist yet', async () => {
+    const dir = path.join(tmpFolder(), 'design-notes');
+
+    const result = await prepareDocumentProject(dir, 'notes');
+
+    expect(result.actions).toEqual([
+      'Created the folder',
+      'Initialised a Git repository',
+      'Created notes.md',
+      'Committed notes.md',
+    ]);
+    expect(git(dir, 'show', '--format=', '--name-only', 'HEAD').trim()).toBe('notes.md');
+  });
+
+  it('refuses a path that is a file', async () => {
+    const file = path.join(tmpFolder(), 'a-file.txt');
+    fs.writeFileSync(file, 'x');
+
+    await expect(prepareDocumentProject(file, 'notes.md')).rejects.toThrow(/not a folder/);
+  });
+
+  it('creates a starter document when the name is new, adding the extension', async () => {
+    const dir = tmpFolder();
+
+    const result = await prepareDocumentProject(dir, 'release-notes');
+
+    expect(result.documentPath).toBe('release-notes.md');
+    expect(result.actions).toEqual([
+      'Initialised a Git repository',
+      'Created release-notes.md',
+      'Committed release-notes.md',
+    ]);
+    expect(fs.readFileSync(path.join(dir, 'release-notes.md'), 'utf8')).toBe('# Release notes\n\n');
+  });
+
+  it('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..9c2f8ac7f
--- /dev/null
+++ b/electron/documents/setup.ts
@@ -0,0 +1,151 @@
+/**
+ * Onboarding for document projects: what a folder already offers, and the
+ * smallest set of steps that turns it into something the workspace can run
+ * against — a Git repository whose chosen document is committed.
+ */
+import fs from 'fs';
+import path from 'path';
+import { ensureWorktreeContainerExclude } from '../ipc/git.js';
+import { git, gitOk } from './git.js';
+import { validateDocumentPath } from './runs.js';
+import type { DocumentFileInfo, DocumentFolderInfo, DocumentProjectSetup } from './types.js';
+
+const MAX_FILES = 1000;
+/** How far the pre-repository scan walks before it stops looking. */
+const SCAN_DEPTH = 4;
+const 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> {
+  // 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 { 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, []));
+  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 { exists: true, 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 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(`${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(
+      `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/documents/shared.ts b/electron/documents/shared.ts
new file mode 100644
index 000000000..63e823157
--- /dev/null
+++ b/electron/documents/shared.ts
@@ -0,0 +1,35 @@
+/**
+ * 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;
+}
+
+/**
+ * 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 },
+};
+
+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/electron/documents/types.ts b/electron/documents/types.ts
new file mode 100644
index 000000000..c6e18fc2a
--- /dev/null
+++ b/electron/documents/types.ts
@@ -0,0 +1,209 @@
+/**
+ * The shapes the document workspace sends across IPC. Renderer-safe: types
+ * only, no runtime imports.
+ */
+
+/** A Markdown file a folder offers as the document to work on. */
+export interface DocumentFileInfo {
+  path: string;
+  /** False for files setup still has to commit before runs can branch from them. */
+  committed: boolean;
+}
+
+/** What a candidate folder already has, so the picker can offer to fill the gaps. */
+export interface DocumentFolderInfo {
+  /** False for a folder the user named but has not created; setup makes it. */
+  exists: boolean;
+  isRepo: boolean;
+  /** Set when the folder is inside someone else's repository, which setup refuses to nest in. */
+  enclosingRepo: string | null;
+  hasCommits: boolean;
+  files: DocumentFileInfo[];
+}
+
+/** What `prepareDocumentProject` did, in order, so the app can say so. */
+export interface DocumentProjectSetup {
+  documentPath: string;
+  actions: string[];
+}
+
+/** Current state of the canonical document in the project checkout. */
+export interface DocumentSnapshot {
+  content: string;
+  /** HEAD sha of the canonical branch; null in an empty repository. */
+  headSha: string | null;
+  /** Checked-out branch name; null when HEAD is detached. */
+  branch: string | null;
+  /** True when the working tree has uncommitted changes (outside `.worktrees/`). */
+  dirty: boolean;
+  /** True when the document file is missing from the checkout. */
+  missing: boolean;
+}
+
+/** What part of the document a run is allowed to change. Lines are 1-based and
+ *  inclusive at the base commit; a whole-document scope has `wholeDocument`. */
+export interface DocumentScope {
+  path: string;
+  wholeDocument: boolean;
+  startLine: number;
+  endLine: number;
+  /** Exact quoted text of the selected passage (block-aligned). */
+  quote: string;
+  /** Nearest heading above the selection, when any. */
+  heading?: string;
+}
+
+export interface DocumentRationale {
+  summary: string;
+  changes: string[];
+  assumptions: string[];
+  questions: string[];
+  warnings: string[];
+}
+
+export type DocumentCandidateStatus = 'running' | 'done' | 'failed' | 'cancelled' | 'interrupted';
+
+export interface DocumentCandidateRecord {
+  id: string;
+  /** Neutral label used when the comparison hides agent identity ("A", "B", …). */
+  label: string;
+  agentId: string;
+  agentName: string;
+  /** The project's warm main session rather than a throwaway alternate. */
+  isMain: boolean;
+  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/channel-manifest.json b/electron/ipc/channel-manifest.json
index 3eeba5c8d..1e4f3d469 100644
--- a/electron/ipc/channel-manifest.json
+++ b/electron/ipc/channel-manifest.json
@@ -147,5 +147,27 @@
   "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",
+  "InspectDocumentFolder": "inspect_document_folder",
+  "PrepareDocumentProject": "prepare_document_project",
+  "DocumentChanged": "document_changed",
+  "DocumentRunEvent": "document_run_event",
+  "ListDocumentAnnotations": "list_document_annotations",
+  "SaveDocumentAnnotation": "save_document_annotation",
+  "DeleteDocumentAnnotation": "delete_document_annotation",
+  "AskDocumentAnnotation": "ask_document_annotation",
+  "DocumentAnnotationEvent": "document_annotation_event"
 }
diff --git a/electron/ipc/register.ts b/electron/ipc/register.ts
index aadab018a..187317626 100644
--- a/electron/ipc/register.ts
+++ b/electron/ipc/register.ts
@@ -106,7 +106,9 @@ import {
   assertStringArray,
   assertOptionalString,
   assertOptionalBoolean,
+  validatePath,
 } from './validate.js';
+import { registerDocumentHandlers } from '../documents/register.js';
 import { validateBranchName as sharedValidateBranchName, validateUUID } from '../mcp/validation.js';
 import { debug as logDebug, warn as logWarn, errMessage } from '../log.js';
 import { getMCPRemoteServerUrl, detectStaleDockerMCPUrl } from '../mcp/config.js';
@@ -179,13 +181,6 @@ async function startRemoteServerOnFreePort(
   throw new Error(`No free port found in range ${start}–${end}`);
 }
 
-/** Reject paths that are non-absolute or attempt directory traversal. */
-function validatePath(p: unknown, label: string): void {
-  if (typeof p !== 'string') throw new Error(`${label} must be a string`);
-  if (!path.isAbsolute(p)) throw new Error(`${label} must be absolute`);
-  if (p.includes('..')) throw new Error(`${label} must not contain ".."`);
-}
-
 function isMissingCommandError(err: unknown, command: string): boolean {
   const e = err as { path?: unknown; syscall?: unknown };
   return (
@@ -962,6 +957,8 @@ export function registerAllHandlers(win: BrowserWindow): void {
     cancelAskAboutCode(args.requestId);
   });
 
+  registerDocumentHandlers(win);
+
   // --- File links ---
   ipcMain.handle(IPC.OpenPath, (_e, args) => {
     validatePath(args.filePath, 'filePath');
diff --git a/electron/ipc/validate.ts b/electron/ipc/validate.ts
index a4baf4822..9ad3c9ea3 100644
--- a/electron/ipc/validate.ts
+++ b/electron/ipc/validate.ts
@@ -1,4 +1,12 @@
 /** Runtime type assertion helpers for IPC handler args. */
+import path from 'path';
+
+/** Reject paths that are non-absolute or attempt directory traversal. */
+export function validatePath(p: unknown, label: string): void {
+  if (typeof p !== 'string') throw new Error(`${label} must be a string`);
+  if (!path.isAbsolute(p)) throw new Error(`${label} must be absolute`);
+  if (p.includes('..')) throw new Error(`${label} must not contain ".."`);
+}
 
 export function assertString(val: unknown, label: string): asserts val is string {
   if (typeof val !== 'string') throw new Error(`${label} must be a string`);
diff --git a/electron/main.ts b/electron/main.ts
index cbeeba525..50cbf2fae 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 { stopAllDocumentWork } from './documents/register.js';
 import { stopAllStepsWatchers } from './ipc/steps.js';
 import { verificationRunner } from './ipc/verify.js';
 import { IPC } from './ipc/channels.js';
@@ -288,6 +289,7 @@ app.on('will-quit', () => {
   verificationRunner.cancelAll();
   stopAgentHookRuntime();
   stopAllPlanWatchers();
+  stopAllDocumentWork();
   stopAllStepsWatchers();
 });
 
diff --git a/electron/preload.cjs b/electron/preload.cjs
index f301b25e6..3bfdff5f1 100644
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -152,6 +152,28 @@ 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',
+  'inspect_document_folder',
+  'prepare_document_project',
+  'document_changed',
+  'document_run_event',
+  'list_document_annotations',
+  'save_document_annotation',
+  'delete_document_annotation',
+  'ask_document_annotation',
+  'document_annotation_event',
 ]);
 
 function isAllowedChannel(channel) {
diff --git a/electron/test-env.test.ts b/electron/test-env.test.ts
new file mode 100644
index 000000000..02097396d
--- /dev/null
+++ b/electron/test-env.test.ts
@@ -0,0 +1,38 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+/**
+ * Guards the invariant every git-touching test depends on: a `git` spawned by a
+ * test acts on its own temp repository, never on the checkout the suite runs in.
+ * Run from a git hook without `vitest.setup.ts` scrubbing the inherited
+ * `GIT_DIR`/`GIT_INDEX_FILE`, both of these fail.
+ */
+describe('test environment', () => {
+  const made: string[] = [];
+  afterEach(() => {
+    for (const dir of made.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('hands tests no pointer to a surrounding repository', () => {
+    for (const name of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR'])
+      expect({ [name]: process.env[name] }).toEqual({ [name]: undefined });
+  });
+
+  it('creates a temp repository in the temp folder, not in the ambient one', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pc-test-env-'));
+    made.push(dir);
+    execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+
+    // `--show-toplevel` would pass either way: an inherited GIT_DIR leaves the
+    // work tree at cwd. Only the git dir itself reveals the hijack.
+    const gitDir = execFileSync('git', ['rev-parse', '--absolute-git-dir'], {
+      cwd: dir,
+      encoding: 'utf8',
+    }).trim();
+
+    expect(fs.realpathSync(gitDir)).toBe(path.join(fs.realpathSync(dir), '.git'));
+  });
+});
diff --git a/src/App.tsx b/src/App.tsx
index 033f91efb..382a181b7 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -87,6 +87,13 @@ import { isMac, mod } from './lib/platform';
 import { createCtrlWheelZoomHandler } from './lib/wheelZoom';
 import { redrawAllTerminals } from './lib/terminalFitManager';
 import { ArenaOverlay } from './arena/ArenaOverlay';
+import { DocumentWorkspaceOverlay } from './documents/DocumentWorkspaceOverlay';
+import {
+  closeDocumentWorkspace,
+  documentStore,
+  initDocumentListeners,
+  setDocumentSelection,
+} from './documents/store';
 import { resetForNewMatch } from './arena/store';
 import { startDesktopNotificationWatcher } from './store/desktopNotifications';
 import { startPrChecksSubscription } from './store/pr-checks';
@@ -336,6 +343,7 @@ function App() {
     // Before the first await: restored agents start firing hooks as soon as
     // loadState spawns them, and IPC does not replay what nobody listened to.
     const stopAgentHookStatusListener = startAgentHookStatusListener();
+    const stopDocumentListeners = initDocumentListeners();
     void syncWindowFocused();
     void syncWindowMaximized();
 
@@ -697,6 +705,11 @@ function App() {
           closeArena();
           return;
         }
+        if (store.activeDocumentProjectId) {
+          if (documentStore.selection) setDocumentSelection(null);
+          else closeDocumentWorkspace();
+          return;
+        }
         if (store.showHelpDialog) {
           toggleHelpDialog(false);
           return;
@@ -742,6 +755,7 @@ function App() {
       stopRemoteTaskHandlers();
       stopRemoteStatusSync();
       stopAgentHookStatusListener();
+      stopDocumentListeners();
       offPlanContent();
       offStepsContent();
       unlistenFocusChanged?.();
@@ -919,6 +933,9 @@ function App() {
         <Show when={store.showArena}>
           <ArenaOverlay onClose={closeArena} />
         </Show>
+        <Show when={store.activeDocumentProjectId}>
+          <DocumentWorkspaceOverlay />
+        </Show>
         <Show when={showDropOverlay()}>
           <DropOverlay />
         </Show>
diff --git a/src/components/AddProjectMenu.tsx b/src/components/AddProjectMenu.tsx
new file mode 100644
index 000000000..4a8170b71
--- /dev/null
+++ b/src/components/AddProjectMenu.tsx
@@ -0,0 +1,114 @@
+import { onCleanup, onMount } from 'solid-js';
+import { Portal } from 'solid-js/web';
+import { theme } from '../lib/theme';
+import { sf } from '../lib/fontScale';
+import { DocumentIcon } from '../documents/DocumentIcon';
+
+export type ProjectKindChoice = 'code' | 'document';
+
+interface AddProjectMenuProps {
+  /** Viewport coordinates of the "+" button this hangs from. */
+  anchor: { left: number; top: number };
+  onPick: (kind: ProjectKindChoice) => void;
+  onClose: () => void;
+}
+
+const MENU_WIDTH = 232;
+
+/**
+ * The two project kinds, offered rather than asked. This replaces a native
+ * message box: that blocked the window to pose a question in a dialog system
+ * the app does not control, and its Escape cancelled the whole add instead of
+ * backing out of the question.
+ */
+export function AddProjectMenu(props: AddProjectMenuProps) {
+  onMount(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.stopPropagation();
+        props.onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey, true);
+    onCleanup(() => window.removeEventListener('keydown', onKey, true));
+  });
+
+  const row = (kind: ProjectKindChoice, icon: () => unknown, label: string, hint: string) => (
+    <button
+      type="button"
+      onClick={() => props.onPick(kind)}
+      style={{
+        display: 'flex',
+        'align-items': 'flex-start',
+        gap: '9px',
+        padding: '8px 10px',
+        background: 'transparent',
+        border: 'none',
+        'border-radius': 'var(--radius-sm)',
+        color: theme.fg,
+        cursor: 'pointer',
+        'text-align': 'left',
+        font: 'inherit',
+      }}
+      onMouseEnter={(e) => (e.currentTarget.style.background = theme.bgHover)}
+      onMouseLeave={(e) => (e.currentTarget.style.background = 'transparent')}
+    >
+      <span style={{ color: theme.fgMuted, 'margin-top': '1px', 'flex-shrink': '0' }}>
+        {icon() as never}
+      </span>
+      <span style={{ display: 'flex', 'flex-direction': 'column', gap: '1px', 'min-width': '0' }}>
+        <span style={{ 'font-size': sf(12), 'font-weight': '500' }}>{label}</span>
+        <span style={{ 'font-size': sf(11), color: theme.fgMuted }}>{hint}</span>
+      </span>
+    </button>
+  );
+
+  return (
+    <Portal>
+      <div
+        onClick={() => props.onClose()}
+        onContextMenu={() => props.onClose()}
+        style={{ position: 'fixed', inset: '0', 'z-index': '1200' }}
+      >
+        <div
+          role="menu"
+          aria-label="Add project"
+          onClick={(e) => e.stopPropagation()}
+          style={{
+            position: 'fixed',
+            left: `${props.anchor.left}px`,
+            top: `${props.anchor.top}px`,
+            width: `${MENU_WIDTH}px`,
+            background: theme.bgElevated,
+            border: `1px solid ${theme.border}`,
+            'border-radius': 'var(--radius-md)',
+            'box-shadow': '0 6px 20px rgba(0, 0, 0, 0.35)',
+            padding: '4px',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '1px',
+          }}
+        >
+          {row(
+            'code',
+            () => (
+              <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
+                <path d="M1.5 3.25A1.75 1.75 0 0 1 3.25 1.5h2.9c.46 0 .9.18 1.23.51l.86.86h4.51c.97 0 1.75.78 1.75 1.75v7.63c0 .97-.78 1.75-1.75 1.75H3.25a1.75 1.75 0 0 1-1.75-1.75z" />
+              </svg>
+            ),
+            'Code project…',
+            'A git repo that holds tasks',
+          )}
+          {row(
+            'document',
+            () => (
+              <DocumentIcon size={14} />
+            ),
+            'Document project…',
+            'A folder with one Markdown document',
+          )}
+        </div>
+      </div>
+    </Portal>
+  );
+}
diff --git a/src/components/EditProjectDialog.tsx b/src/components/EditProjectDialog.tsx
index b6b664b66..97e2caae9 100644
--- a/src/components/EditProjectDialog.tsx
+++ b/src/components/EditProjectDialog.tsx
@@ -8,6 +8,7 @@ import { SegmentedButtons } from './SegmentedButtons';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
 import { CloseIcon } from './icons';
 import { RemoveProjectConfirm } from './RemoveProjectConfirm';
+import { isDocumentProject } from '../store/projects';
 
 interface EditProjectDialogProps {
   project: Project | null;
@@ -32,6 +33,9 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
   const [newCommand, setNewCommand] = createSignal('');
   const [showImportDialog, setShowImportDialog] = createSignal(false);
   const [confirmRemove, setConfirmRemove] = createSignal(false);
+  /** Branch and worktree settings only mean something where tasks run. */
+  const isDocument = () => isDocumentProject(props.project ?? undefined);
+  const showsTaskSettings = () => props.project?.isGitRepo !== false && !isDocument();
   let nameRef!: HTMLInputElement;
 
   // Sync signals when project prop changes
@@ -130,22 +134,24 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
               >
                 {project().path}
               </div>
-              <button
-                type="button"
-                onClick={() => setShowImportDialog(true)}
-                style={{
-                  padding: '3px 10px',
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': 'var(--radius-sm)',
-                  color: theme.fgMuted,
-                  cursor: 'pointer',
-                  'font-size': '11px',
-                  'flex-shrink': '0',
-                }}
-              >
-                Import Worktrees
-              </button>
+              <Show when={!isDocument()}>
+                <button
+                  type="button"
+                  onClick={() => setShowImportDialog(true)}
+                  style={{
+                    padding: '3px 10px',
+                    background: theme.bgInput,
+                    border: `1px solid ${theme.border}`,
+                    'border-radius': 'var(--radius-sm)',
+                    color: theme.fgMuted,
+                    cursor: 'pointer',
+                    'font-size': '11px',
+                    'flex-shrink': '0',
+                  }}
+                >
+                  Import Worktrees
+                </button>
+              </Show>
               <button
                 type="button"
                 onClick={() => relinkProject(project().id)}
@@ -242,7 +248,7 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
             </div>
 
             {/* Branch prefix — git projects only */}
-            <Show when={props.project?.isGitRepo !== false}>
+            <Show when={showsTaskSettings()}>
               <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
                 <label style={sectionLabelStyle}>Branch prefix</label>
                 <input
@@ -325,7 +331,7 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
             </div>
 
             {/* Git-specific settings — hidden for non-git projects */}
-            <Show when={props.project?.isGitRepo !== false}>
+            <Show when={showsTaskSettings()}>
               {/* Close cleanup preference */}
               <label
                 style={{
@@ -386,177 +392,181 @@ export function EditProjectDialog(props: EditProjectDialogProps) {
               </div>
             </Show>
 
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>
-                Verify command{' '}
-                <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
-                  (runs in the task worktree)
-                </span>
-              </label>
-              <input
-                class="input-field"
-                type="text"
-                value={verifyCommand()}
-                onInput={(e) => setVerifyCommand(e.currentTarget.value)}
-                placeholder="npm run typecheck && npm test"
-                style={{
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': '8px',
-                  padding: '10px 14px',
-                  color: theme.fg,
-                  'font-size': '14px',
-                  'font-family': "'JetBrains Mono', monospace",
-                  outline: 'none',
-                }}
-              />
-              <div
-                style={{
-                  'font-size': '12px',
-                  color: theme.fgSubtle,
-                  padding: '2px 2px 0',
-                }}
-              >
-                Runs from the merge dialog, when an agent calls <code>land_self</code>, and before
-                the coordinator merges. A failure is advisory in the merge dialog, but{' '}
-                <code>land_self</code> and <code>merge_task</code> refuse to merge until it passes.{' '}
-                <code>PARALLEL_CODE_TASK_ID</code> and <code>PARALLEL_CODE_BRANCH</code> are set for
-                namespacing shared resources.
-              </div>
-            </div>
-
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>
-                Coverage report path{' '}
-                <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
-                  (relative to repo root)
-                </span>
-              </label>
-              <input
-                class="input-field"
-                type="text"
-                value={coverageReportPath()}
-                onInput={(e) => setCoverageReportPath(e.currentTarget.value)}
-                placeholder="coverage/coverage-summary.json or coverage/lcov.info"
-                style={{
-                  background: theme.bgInput,
-                  border: `1px solid ${theme.border}`,
-                  'border-radius': 'var(--radius-md)',
-                  padding: '10px 14px',
-                  color: theme.fg,
-                  'font-size': '14px',
-                  'font-family': "'JetBrains Mono', monospace",
-                  outline: 'none',
-                }}
-              />
-              <div
-                style={{
-                  'font-size': '12px',
-                  color: theme.fgSubtle,
-                  padding: '2px 2px 0',
-                }}
-              >
-                Leave blank to try <code>coverage/coverage-summary.json</code>, then{' '}
-                <code>coverage/lcov.info</code>.
-              </div>
-            </div>
-
-            {/* Command Bookmarks */}
-            <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
-              <label style={sectionLabelStyle}>Command Bookmarks</label>
-              <Show when={bookmarks().length > 0}>
-                <div style={{ display: 'flex', 'flex-direction': 'column', gap: '4px' }}>
-                  <For each={bookmarks()}>
-                    {(bookmark) => (
-                      <div
-                        style={{
-                          display: 'flex',
-                          'align-items': 'center',
-                          gap: '8px',
-                          padding: '4px 8px',
-                          background: theme.bgInput,
-                          'border-radius': 'var(--radius-sm)',
-                          border: `1px solid ${theme.border}`,
-                        }}
-                      >
-                        <span
-                          style={{
-                            flex: '1',
-                            'font-size': '12px',
-                            'font-family': "'JetBrains Mono', monospace",
-                            color: theme.fgSubtle,
-                            overflow: 'hidden',
-                            'text-overflow': 'ellipsis',
-                            'white-space': 'nowrap',
-                          }}
-                        >
-                          {bookmark.command}
-                        </span>
-                        <button
-                          type="button"
-                          onClick={() => removeBookmark(bookmark.id)}
-                          style={{
-                            background: 'transparent',
-                            border: 'none',
-                            color: theme.fgSubtle,
-                            cursor: 'pointer',
-                            padding: '2px',
-                            'line-height': '1',
-                            'flex-shrink': '0',
-                          }}
-                          title="Remove bookmark"
-                        >
-                          <CloseIcon size={12} />
-                        </button>
-                      </div>
-                    )}
-                  </For>
-                </div>
-              </Show>
-              <div style={{ display: 'flex', gap: '6px' }}>
+            {/* Worktrees, verification, coverage and terminal bookmarks belong to
+                code tasks; a document project runs none of them. */}
+            <Show when={!isDocument()}>
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>
+                  Verify command{' '}
+                  <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
+                    (runs in the task worktree)
+                  </span>
+                </label>
                 <input
                   class="input-field"
                   type="text"
-                  value={newCommand()}
-                  onInput={(e) => setNewCommand(e.currentTarget.value)}
-                  onKeyDown={(e) => {
-                    if (e.key === 'Enter') {
-                      e.preventDefault();
-                      addBookmark();
-                    }
-                  }}
-                  placeholder="e.g. npm run dev"
+                  value={verifyCommand()}
+                  onInput={(e) => setVerifyCommand(e.currentTarget.value)}
+                  placeholder="npm run typecheck && npm test"
                   style={{
-                    flex: '1',
                     background: theme.bgInput,
                     border: `1px solid ${theme.border}`,
-                    'border-radius': 'var(--radius-md)',
-                    padding: '8px 12px',
+                    'border-radius': '8px',
+                    padding: '10px 14px',
                     color: theme.fg,
-                    'font-size': '13px',
+                    'font-size': '14px',
                     'font-family': "'JetBrains Mono', monospace",
                     outline: 'none',
                   }}
                 />
-                <button
-                  type="button"
-                  onClick={addBookmark}
-                  disabled={!newCommand().trim()}
+                <div
+                  style={{
+                    'font-size': '12px',
+                    color: theme.fgSubtle,
+                    padding: '2px 2px 0',
+                  }}
+                >
+                  Runs from the merge dialog, when an agent calls <code>land_self</code>, and before
+                  the coordinator merges. A failure is advisory in the merge dialog, but{' '}
+                  <code>land_self</code> and <code>merge_task</code> refuse to merge until it
+                  passes. <code>PARALLEL_CODE_TASK_ID</code> and <code>PARALLEL_CODE_BRANCH</code>{' '}
+                  are set for namespacing shared resources.
+                </div>
+              </div>
+
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>
+                  Coverage report path{' '}
+                  <span style={{ opacity: '0.5', 'text-transform': 'none' }}>
+                    (relative to repo root)
+                  </span>
+                </label>
+                <input
+                  class="input-field"
+                  type="text"
+                  value={coverageReportPath()}
+                  onInput={(e) => setCoverageReportPath(e.currentTarget.value)}
+                  placeholder="coverage/coverage-summary.json or coverage/lcov.info"
                   style={{
-                    padding: '8px 14px',
                     background: theme.bgInput,
                     border: `1px solid ${theme.border}`,
                     'border-radius': 'var(--radius-md)',
-                    color: newCommand().trim() ? theme.fg : theme.fgSubtle,
-                    cursor: newCommand().trim() ? 'pointer' : 'not-allowed',
-                    'font-size': '13px',
-                    'flex-shrink': '0',
+                    padding: '10px 14px',
+                    color: theme.fg,
+                    'font-size': '14px',
+                    'font-family': "'JetBrains Mono', monospace",
+                    outline: 'none',
+                  }}
+                />
+                <div
+                  style={{
+                    'font-size': '12px',
+                    color: theme.fgSubtle,
+                    padding: '2px 2px 0',
                   }}
                 >
-                  Add
-                </button>
+                  Leave blank to try <code>coverage/coverage-summary.json</code>, then{' '}
+                  <code>coverage/lcov.info</code>.
+                </div>
               </div>
-            </div>
+
+              {/* Command Bookmarks */}
+              <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+                <label style={sectionLabelStyle}>Command Bookmarks</label>
+                <Show when={bookmarks().length > 0}>
+                  <div style={{ display: 'flex', 'flex-direction': 'column', gap: '4px' }}>
+                    <For each={bookmarks()}>
+                      {(bookmark) => (
+                        <div
+                          style={{
+                            display: 'flex',
+                            'align-items': 'center',
+                            gap: '8px',
+                            padding: '4px 8px',
+                            background: theme.bgInput,
+                            'border-radius': 'var(--radius-sm)',
+                            border: `1px solid ${theme.border}`,
+                          }}
+                        >
+                          <span
+                            style={{
+                              flex: '1',
+                              'font-size': '12px',
+                              'font-family': "'JetBrains Mono', monospace",
+                              color: theme.fgSubtle,
+                              overflow: 'hidden',
+                              'text-overflow': 'ellipsis',
+                              'white-space': 'nowrap',
+                            }}
+                          >
+                            {bookmark.command}
+                          </span>
+                          <button
+                            type="button"
+                            onClick={() => removeBookmark(bookmark.id)}
+                            style={{
+                              background: 'transparent',
+                              border: 'none',
+                              color: theme.fgSubtle,
+                              cursor: 'pointer',
+                              padding: '2px',
+                              'line-height': '1',
+                              'flex-shrink': '0',
+                            }}
+                            title="Remove bookmark"
+                          >
+                            <CloseIcon size={12} />
+                          </button>
+                        </div>
+                      )}
+                    </For>
+                  </div>
+                </Show>
+                <div style={{ display: 'flex', gap: '6px' }}>
+                  <input
+                    class="input-field"
+                    type="text"
+                    value={newCommand()}
+                    onInput={(e) => setNewCommand(e.currentTarget.value)}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter') {
+                        e.preventDefault();
+                        addBookmark();
+                      }
+                    }}
+                    placeholder="e.g. npm run dev"
+                    style={{
+                      flex: '1',
+                      background: theme.bgInput,
+                      border: `1px solid ${theme.border}`,
+                      'border-radius': 'var(--radius-md)',
+                      padding: '8px 12px',
+                      color: theme.fg,
+                      'font-size': '13px',
+                      'font-family': "'JetBrains Mono', monospace",
+                      outline: 'none',
+                    }}
+                  />
+                  <button
+                    type="button"
+                    onClick={addBookmark}
+                    disabled={!newCommand().trim()}
+                    style={{
+                      padding: '8px 14px',
+                      background: theme.bgInput,
+                      border: `1px solid ${theme.border}`,
+                      'border-radius': 'var(--radius-md)',
+                      color: newCommand().trim() ? theme.fg : theme.fgSubtle,
+                      cursor: newCommand().trim() ? 'pointer' : 'not-allowed',
+                      'font-size': '13px',
+                      'flex-shrink': '0',
+                    }}
+                  >
+                    Add
+                  </button>
+                </div>
+              </div>
+            </Show>
 
             {/* Buttons */}
             <div
diff --git a/src/components/IconButton.tsx b/src/components/IconButton.tsx
index b46181d47..c5fce9d42 100644
--- a/src/components/IconButton.tsx
+++ b/src/components/IconButton.tsx
@@ -3,7 +3,7 @@ import { theme } from '../lib/theme';
 
 interface IconButtonProps {
   icon: string | JSX.Element;
-  onClick: (e: MouseEvent) => void;
+  onClick: JSX.EventHandler<HTMLButtonElement, MouseEvent>;
   title?: string;
   size?: 'sm' | 'md';
 }
diff --git a/src/components/NewTaskDialog.tsx b/src/components/NewTaskDialog.tsx
index f50f0c1b2..b4b4429b3 100644
--- a/src/components/NewTaskDialog.tsx
+++ b/src/components/NewTaskDialog.tsx
@@ -30,6 +30,7 @@ import {
   setPrefillPrompt,
   setDockerAvailable,
   setDockerImage,
+  codeProjects,
 } from '../store/store';
 import type { GitIsolationMode } from '../store/types';
 import {
@@ -551,7 +552,9 @@ export function NewTaskDialog(props: NewTaskDialogProps) {
 
             // Pre-fill from drop data if present
             const dropUrl = store.newTaskDropUrl;
-            const fallbackProjectId = store.lastProjectId ?? store.projects[0]?.id ?? null;
+            const targets = codeProjects();
+            const fallbackProjectId =
+              targets.find((p) => p.id === store.lastProjectId)?.id ?? targets[0]?.id ?? null;
             const defaults = dropUrl ? getGitHubDropDefaults(dropUrl) : null;
 
             if (dropUrl) setPrompt(`review ${dropUrl}`);
diff --git a/src/components/ProjectSelect.tsx b/src/components/ProjectSelect.tsx
index 26ec7fb11..806727749 100644
--- a/src/components/ProjectSelect.tsx
+++ b/src/components/ProjectSelect.tsx
@@ -1,5 +1,5 @@
 import { For, Show } from 'solid-js';
-import { store } from '../store/store';
+import { codeProjects } from '../store/projects';
 
 interface ProjectSelectProps {
   value: string | null;
@@ -20,7 +20,7 @@ export function ProjectSelect(props: ProjectSelectProps) {
           {props.placeholder}
         </option>
       </Show>
-      <For each={[...store.projects].sort((a, b) => a.name.localeCompare(b.name))}>
+      <For each={codeProjects().sort((a, b) => a.name.localeCompare(b.name))}>
         {(project) => (
           <option value={project.id}>
             {project.name} — {project.path}
diff --git a/src/components/SettingsDialog.tsx b/src/components/SettingsDialog.tsx
index c17d14e96..13e9372af 100644
--- a/src/components/SettingsDialog.tsx
+++ b/src/components/SettingsDialog.tsx
@@ -35,6 +35,7 @@ import {
   setLightTheme,
   setDarkTheme,
   setCoordinatorModeEnabled,
+  setDocumentWorkspacesEnabled,
   setCoordinatorNotificationDelayMs,
   setDefaultStepsEnabled,
   setDefaultSkipPermissions,
@@ -1075,6 +1076,14 @@ export function SettingsDialog(props: SettingsDialogProps) {
           aria-labelledby="settings-tabbutton-experimental"
           style={{ display: 'flex', 'flex-direction': 'column', gap: '18px' }}
         >
+          <SettingsSection title="Document workspaces">
+            <SettingsCheckboxRow
+              label="Document workspaces"
+              checked={store.documentWorkspacesEnabled}
+              onChange={setDocumentWorkspacesEnabled}
+              description="Add document projects: a folder with one Markdown document, set up for you if it is not a Git repository yet. Select a passage, send the same instruction to one or more agents running headlessly in isolated worktrees, compare the proposals side by side, and accept one as a single readable commit. Adds Document project to the + button next to Projects."
+            />
+          </SettingsSection>
           <SettingsSection title="Coordinator">
             <SettingsCheckboxRow
               label="Coordinator mode"
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index b0fcaf095..853721ce1 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -40,6 +40,11 @@ import { computeNeedsInputTasks, jumpToWaitingTask } from '../store/sidebar-atte
 import { ConnectPhoneModal } from './ConnectPhoneModal';
 import { RemoveProjectConfirm } from './RemoveProjectConfirm';
 import { EditProjectDialog } from './EditProjectDialog';
+import { NewDocumentProjectDialog } from '../documents/NewDocumentProjectDialog';
+import { openDocumentWorkspace } from '../documents/store';
+import { codeProjects, isDocumentProject } from '../store/projects';
+import { DocumentIcon } from '../documents/DocumentIcon';
+import { AddProjectMenu } from './AddProjectMenu';
 import { ImportWorktreesDialog } from './ImportWorktreesDialog';
 import { SidebarFooter } from './SidebarFooter';
 import { IconButton } from './IconButton';
@@ -595,7 +600,27 @@ export function Sidebar() {
     });
   });
 
-  async function handleAddProject() {
+  const [showNewDocumentProject, setShowNewDocumentProject] = createSignal(false);
+  const [addMenuAt, setAddMenuAt] = createSignal<{ left: number; top: number } | null>(null);
+
+  /** With one project kind there is nothing to choose, so "+" stays direct. */
+  function handleAddProject(anchor: HTMLElement) {
+    if (!store.documentWorkspacesEnabled) {
+      void addCodeProject();
+      return;
+    }
+    const rect = anchor.getBoundingClientRect();
+    setAddMenuAt({ left: rect.left, top: rect.bottom + 4 });
+  }
+
+  /** A document project navigates; a code project opens its settings. */
+  function openProjectRow(project: Project): void {
+    if (isDocumentProject(project) && !isProjectMissing(project.id))
+      void openDocumentWorkspace(project.id);
+    else setEditingProject(project);
+  }
+
+  async function addCodeProject() {
     const projectId = await pickAndAddProject();
     if (!projectId) return;
 
@@ -830,7 +855,7 @@ export function Sidebar() {
                   <path d="M7.75 2a.75.75 0 0 1 .75.75V7h4.25a.75.75 0 0 1 0 1.5H8.5v4.25a.75.75 0 0 1-1.5 0V8.5H2.75a.75.75 0 0 1 0-1.5H7V2.75A.75.75 0 0 1 7.75 2Z" />
                 </svg>
               }
-              onClick={() => handleAddProject()}
+              onClick={(e) => handleAddProject(e.currentTarget)}
               title="Add project"
               size="sm"
             />
@@ -862,14 +887,17 @@ export function Sidebar() {
                       tabIndex={0}
                       class="project-row"
                       data-project-id={project.id}
-                      onClick={() => setEditingProject(project)}
+                      onClick={() => openProjectRow(project)}
                       onKeyDown={(e) => {
-                        if (e.key === 'Enter') setEditingProject(project);
+                        if (e.key !== 'Enter') return;
+                        openProjectRow(project);
                       }}
                       title={
                         isProjectMissing(project.id)
                           ? `Folder not found: ${abbreviateHomePath(project.path)}`
-                          : abbreviateHomePath(project.path)
+                          : isDocumentProject(project)
+                            ? `Document workspace: ${project.documentPath} (${abbreviateHomePath(project.path)})`
+                            : abbreviateHomePath(project.path)
                       }
                       style={{
                         display: 'flex',
@@ -886,15 +914,24 @@ export function Sidebar() {
                         'flex-shrink': '0',
                       }}
                     >
-                      <div
-                        style={{
-                          width: '8px',
-                          height: '8px',
-                          'border-radius': '50%',
-                          background: project.color,
-                          'flex-shrink': '0',
-                        }}
-                      />
+                      <Show
+                        when={isDocumentProject(project)}
+                        fallback={
+                          <div
+                            style={{
+                              width: '8px',
+                              height: '8px',
+                              'border-radius': '50%',
+                              background: project.color,
+                              'flex-shrink': '0',
+                            }}
+                          />
+                        }
+                      >
+                        <span style={{ color: project.color, display: 'flex', 'flex-shrink': '0' }}>
+                          <DocumentIcon size={12} />
+                        </span>
+                      </Show>
                       <span
                         style={{
                           flex: '1',
@@ -957,11 +994,11 @@ export function Sidebar() {
 
         {/* New task / Link project button */}
         <Show
-          when={store.projects.length > 0}
+          when={codeProjects().length > 0}
           fallback={
             <button
               class="icon-btn"
-              onClick={() => handleAddProject()}
+              onClick={(e) => handleAddProject(e.currentTarget)}
               style={{
                 background: 'transparent',
                 border: `1px solid ${theme.border}`,
@@ -1031,7 +1068,7 @@ export function Sidebar() {
               const focusedProjectId = store.sidebarFocusedProjectId;
               if (focusedProjectId) {
                 const project = store.projects.find((p) => p.id === focusedProjectId);
-                if (project) setEditingProject(project);
+                if (project) openProjectRow(project);
                 return;
               }
               const taskId = store.sidebarFocusedTaskId;
@@ -1148,6 +1185,23 @@ export function Sidebar() {
         <ConnectPhoneModal open={showConnectPhone()} onClose={() => setShowConnectPhone(false)} />
 
         <EditProjectDialog project={editingProject()} onClose={() => setEditingProject(null)} />
+        <Show when={addMenuAt()}>
+          {(at) => (
+            <AddProjectMenu
+              anchor={at()}
+              onClose={() => setAddMenuAt(null)}
+              onPick={(kind) => {
+                setAddMenuAt(null);
+                if (kind === 'document') setShowNewDocumentProject(true);
+                else void addCodeProject();
+              }}
+            />
+          )}
+        </Show>
+        <NewDocumentProjectDialog
+          open={showNewDocumentProject()}
+          onClose={() => setShowNewDocumentProject(false)}
+        />
         <ImportWorktreesDialog
           open={importProject() !== null}
           project={importProject()}
diff --git a/src/components/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/AnnotationBubble.tsx b/src/documents/AnnotationBubble.tsx
new file mode 100644
index 000000000..a4d30bb87
--- /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';
+import { documentAgentSupport } from '../../electron/documents/shared';
+import type { DocumentAnnotation } from './types';
+
+interface AnnotationBubbleProps {
+  annotation: DocumentAnnotation;
+  /** The passage could not be found in the current version. */
+  detached?: boolean;
+  onMakeTask: (annotation: DocumentAnnotation) => void;
+}
+
+/**
+ * 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/CompareView.tsx b/src/documents/CompareView.tsx
new file mode 100644
index 000000000..9f255e042
--- /dev/null
+++ b/src/documents/CompareView.tsx
@@ -0,0 +1,369 @@
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  on,
+  untrack,
+} from 'solid-js';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { diffBlocks, type BlockChange, type DocumentBlock } from './markdown-blocks';
+import {
+  acceptDocumentCandidate,
+  documentStore,
+  rejectDocumentRun,
+  setDocumentCandidateNote,
+} from './store';
+import { getProject } from '../store/projects';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './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 };
+}
+
+/** Scroll a column so its first block matching `selector` sits in the upper third. */
+function revealFirst(body: HTMLElement | undefined, selector: string): void {
+  const target = body?.querySelector<HTMLElement>(selector);
+  if (!body || !target) return;
+  const offset = target.getBoundingClientRect().top - body.getBoundingClientRect().top;
+  body.scrollTop += offset - body.clientHeight / 3;
+}
+
+function ChangeNav(props: { body: () => HTMLDivElement | undefined; count: number }) {
+  const [cursor, setCursor] = createSignal(-1);
+  function go(delta: number) {
+    const body = props.body();
+    if (!body) return;
+    const targets = body.querySelectorAll<HTMLElement>('.doc-block:not([data-change="same"])');
+    if (targets.length === 0) return;
+    const next = (cursor() + delta + targets.length) % targets.length;
+    setCursor(next);
+    targets[next].scrollIntoView({ block: 'center', behavior: 'smooth' });
+  }
+  return (
+    <span class="docws-nav">
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(-1)}
+        title="Previous change"
+      >
+        ‹
+      </button>
+      <span>
+        {props.count} changed block{props.count === 1 ? '' : 's'}
+      </span>
+      <button
+        type="button"
+        class="docws-btn docws-btn-sm"
+        onClick={() => go(1)}
+        title="Next change"
+      >
+        ›
+      </button>
+    </span>
+  );
+}
+
+function Rationale(props: { candidate: DocumentCandidateRecord }) {
+  const r = () => props.candidate.rationale;
+  const list = (label: string, items: string[] | undefined, cls?: string) => (
+    <Show when={items && items.length > 0}>
+      <div class="docws-rationale-label">{label}</div>
+      <ul class={cls}>
+        <For each={items}>{(item) => <li>{item}</li>}</For>
+      </ul>
+    </Show>
+  );
+  return (
+    <div class="docws-rationale">
+      <div class="docws-rationale-summary">{r()?.summary ?? 'No rationale returned.'}</div>
+      {list('Changes', r()?.changes)}
+      {list('Assumptions', r()?.assumptions)}
+      {list('Open questions', r()?.questions)}
+      {list('Warnings', r()?.warnings, 'docws-warning')}
+      <Show when={props.candidate.outOfScopeFiles?.length}>
+        <div class="docws-warning">
+          Touched files outside the document (reverted):{' '}
+          {props.candidate.outOfScopeFiles?.join(', ')}
+        </div>
+      </Show>
+      <Show when={props.candidate.outOfScopeHunks}>
+        <div class="docws-warning">
+          {props.candidate.outOfScopeHunks} change{props.candidate.outOfScopeHunks === 1 ? '' : 's'}{' '}
+          outside the selected passage.
+        </div>
+      </Show>
+      <Show when={props.candidate.error}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+    </div>
+  );
+}
+
+function CandidateColumn(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+  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(
+    () =>
+      props.candidate.commitSha
+        ? { sha: props.candidate.commitSha, path: props.run.documentPath }
+        : null,
+    ({ sha, path }) => fetchDocumentAt(sha, path),
+  );
+  const rendered = createRenderedBlocks(() => content() ?? null);
+  const blockDiff = createMemo(() => diffBlocks(props.baseBlocks, rendered.blocks()));
+  const changes = () => blockDiff().candidate;
+  const changedCount = () => changes().filter((c) => c !== 'same').length;
+  createEffect(() => {
+    if (rendered.blocks().length > 0) props.onBaseChanges(props.candidate.id, blockDiff().base);
+  });
+  // Open on the first changed block: the decision is there, not at the title.
+  createEffect(
+    on(changedCount, (count) => {
+      if (count === 0) return;
+      requestAnimationFrame(() => revealFirst(bodyRef, '.doc-block:not([data-change="same"])'));
+    }),
+  );
+  const [diff] = createResource(
+    () =>
+      props.showSource && props.candidate.commitSha
+        ? {
+            projectRoot: projectRoot(),
+            from: props.run.baseSha,
+            to: props.candidate.commitSha,
+            documentPath: props.run.documentPath,
+          }
+        : null,
+    (args) => invoke<string>(IPC.GetDocumentDiff, args),
+  );
+  const [note, setNote] = createSignal(untrack(() => props.candidate.note ?? ''));
+  const [accepting, setAccepting] = createSignal(false);
+  const canAccept = () =>
+    !!props.candidate.commitSha && props.run.status === 'finished' && !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 and the proposal no longer applies. Re-run it.'
+                : '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={
+              <Show when={!diff.loading} fallback={<div class="docws-empty">Loading diff…</div>}>
+                <SourceDiff raw={diff() ?? ''} />
+              </Show>
+            }
+          >
+            <Show
+              when={!rendered.rendering() || rendered.blocks().length > 0}
+              fallback={<div class="docws-empty">Rendering…</div>}
+            >
+              <DocumentViewer
+                blocks={rendered.blocks()}
+                changes={changes()}
+                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 }) {
+  let baseBodyRef: HTMLDivElement | undefined;
+  const [revealAgents, setRevealAgents] = createSignal(false);
+  const [showSource, setShowSource] = createSignal(false);
+  const [baseContent] = createResource(
+    () => ({ sha: props.run.baseSha, path: props.run.documentPath }),
+    ({ sha, path }) => fetchDocumentAt(sha, path),
+  );
+  const base = createRenderedBlocks(() => baseContent() ?? null);
+  const scope = createMemo(() => scopeRange(base.blocks(), props.run));
+  const candidates = createMemo(() => props.run.candidates.filter((c) => c.commitSha));
+  // Base blocks touched by any candidate, so a deleted paragraph is visible somewhere.
+  const [baseChanges, setBaseChanges] = createSignal<Record<string, BlockChange[]>>({});
+  const baseMarks = createMemo<BlockChange[]>(() => {
+    const perCandidate = Object.values(baseChanges());
+    return base.blocks().map((_, i) => {
+      const marks = perCandidate.map((m) => m[i]).filter((m): m is BlockChange => !!m);
+      if (marks.includes('removed')) return 'removed';
+      if (marks.includes('changed')) return 'changed';
+      return 'same';
+    });
+  });
+  // The base opens on the passage the run was scoped to, level with the candidates.
+  createEffect(
+    on([scope, () => base.blocks().length], () => {
+      requestAnimationFrame(() =>
+        revealFirst(baseBodyRef, '.doc-block.is-scope, .doc-block:not([data-change="same"])'),
+      );
+    }),
+  );
+  const scopeText = () => {
+    const s = props.run.scope;
+    if (s.wholeDocument) return 'whole document';
+    return `L${s.startLine}–${s.endLine}${s.heading ? ` · ${s.heading}` : ''}`;
+  };
+
+  return (
+    <div class="docws-compare">
+      <div class="docws-compare-bar">
+        <span class="docws-instruction" title={props.run.instruction}>
+          “{props.run.instruction}”
+        </span>
+        <span>{scopeText()}</span>
+        <span>base {props.run.baseSha.slice(0, 7)}</span>
+        <Show when={props.run.status === 'stale'}>
+          <span class="docws-warning">stale: the document moved since this run</span>
+        </Show>
+        <span style={{ 'margin-left': 'auto' }} />
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={revealAgents()}
+            onChange={(e) => setRevealAgents(e.currentTarget.checked)}
+          />
+          Show agents
+        </label>
+        <label class="docws-toggle">
+          <input
+            type="checkbox"
+            checked={showSource()}
+            onChange={(e) => setShowSource(e.currentTarget.checked)}
+          />
+          Source diff
+        </label>
+        <button
+          type="button"
+          class="docws-btn docws-btn-sm docws-btn-danger"
+          onClick={() => void rejectDocumentRun(props.run.id)}
+        >
+          Reject all
+        </button>
+      </div>
+      <div class="docws-columns">
+        <section class="docws-column docws-column-base" aria-label="Base version">
+          <div class="docws-column-head">
+            <div class="docws-column-title">Base · {props.run.baseSha.slice(0, 7)}</div>
+            <div class="docws-rationale">
+              <div>
+                The document as every candidate saw it. The scoped passage is outlined; blocks a
+                candidate rewrote or removed are marked.
+              </div>
+            </div>
+          </div>
+          <div class="docws-column-body" ref={baseBodyRef}>
+            <DocumentViewer
+              blocks={base.blocks()}
+              scope={scope()}
+              changes={baseMarks()}
+              renderKey="base"
+            />
+          </div>
+        </section>
+        <For each={candidates()}>
+          {(candidate) => (
+            <CandidateColumn
+              run={props.run}
+              candidate={candidate}
+              baseBlocks={base.blocks()}
+              revealAgents={revealAgents()}
+              showSource={showSource()}
+              onBaseChanges={(id, marks) => setBaseChanges((prev) => ({ ...prev, [id]: marks }))}
+            />
+          )}
+        </For>
+      </div>
+    </div>
+  );
+}
diff --git a/src/documents/DocumentIcon.tsx b/src/documents/DocumentIcon.tsx
new file mode 100644
index 000000000..1c4c2afb4
--- /dev/null
+++ b/src/documents/DocumentIcon.tsx
@@ -0,0 +1,19 @@
+/** The document-project glyph: shared by the sidebar row and the workspace header. */
+export function DocumentIcon(props: { size?: number }) {
+  return (
+    <svg
+      width={props.size ?? 18}
+      height={props.size ?? 18}
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="1.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M4 1.5h5l3 3v10H4z" />
+      <path d="M9 1.5v3h3M6 8h4M6 10.5h4" />
+    </svg>
+  );
+}
diff --git a/src/documents/DocumentViewer.tsx b/src/documents/DocumentViewer.tsx
new file mode 100644
index 000000000..16e9ff4e8
--- /dev/null
+++ b/src/documents/DocumentViewer.tsx
@@ -0,0 +1,174 @@
+import { For, Show, createEffect, createMemo, on, type JSX } from 'solid-js';
+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 {
+  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;
+  /** Rendered after the block with this index (annotation bubbles, the composer). */
+  afterBlock?: (index: number) => 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;
+      // 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);
+    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>
+              {/* 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())}
+            </>
+          );
+        }}
+      </For>
+    </div>
+  );
+}
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
new file mode 100644
index 000000000..9778d75cd
--- /dev/null
+++ b/src/documents/DocumentWorkspaceOverlay.tsx
@@ -0,0 +1,477 @@
+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,
+  dismissUndo,
+  documentStore,
+  reviewableRuns,
+  setDocumentComposerDraft,
+  setDocumentSelection,
+  setDocumentView,
+  setShowResolvedAnnotations,
+  openDocumentCompare,
+  undoDeleteDocumentAnnotation,
+  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';
+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';
+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;
+  const blocks = createRenderedBlocks(() => documentStore.snapshot?.content ?? null);
+  const selection = () => documentStore.selection;
+  const range = createMemo(() => {
+    const s = selection();
+    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 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));
+      },
+    ),
+  );
+
+  // 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([selectedRange, blocks.blocks], () => {
+      if (!selection()) return;
+      requestAnimationFrame(() => {
+        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 });
+      });
+    }),
+  );
+
+  // 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';
+    if (s.wholeDocument) return 'Whole document selected';
+    return s.startLine === s.endLine
+      ? `Selected line ${s.startLine}`
+      : `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">
+          <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">
+              Deleted a {documentStore.lastDeleted?.kind}.
+              <button
+                type="button"
+                class="docws-btn docws-btn-sm"
+                onClick={() => void undoDeleteDocumentAnnotation()}
+              >
+                Undo
+              </button>
+            </span>
+          </Show>
+          <span style={{ 'margin-left': 'auto' }} />
+          <Show when={resolvedCount() > 0}>
+            <label class="docws-toggle" title="Resolved bubbles collapse to one line">
+              <input
+                type="checkbox"
+                checked={documentStore.showResolved}
+                onChange={(e) => setShowResolvedAnnotations(e.currentTarget.checked)}
+              />
+              {resolvedCount()} resolved
+            </label>
+          </Show>
+          <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"
+              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>
+        <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>
+              <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>
+          <Show when={selection()?.wholeDocument}>
+            <div class="docws-composer-slot" ref={claimComposer} />
+          </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={composerAfterBlock() === index}>
+                  <div class="docws-composer-slot" ref={claimComposer} />
+                </Show>
+              </>
+            )}
+          />
+          <Show
+            when={
+              blocks.blocks().length === 0 &&
+              !blocks.rendering() &&
+              documentStore.snapshot &&
+              !documentStore.snapshot.missing
+            }
+          >
+            <div class="docws-empty">The document is empty.</div>
+          </Show>
+        </div>
+      </div>
+      <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());
+  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(() => {
+    if (store.activeDocumentProjectId && !project()) closeDocumentWorkspace();
+  });
+
+  onCleanup(() => {
+    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
+        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" 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}
+        </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)}
+          {tab('history', 'History')}
+        </div>
+        <button type="button" class="docws-btn" onClick={() => setEditing(project() ?? null)}>
+          Project
+        </button>
+        <button
+          type="button"
+          class="docws-btn"
+          title="Close (Esc)"
+          onClick={() => closeDocumentWorkspace()}
+        >
+          Close
+        </button>
+      </div>
+      <Show when={documentStore.error}>
+        <div class="docws-banner docws-banner-error" role="alert">
+          {documentStore.error}
+        </div>
+      </Show>
+      <div class="docws-body">
+        <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={documentStore.compareRunId && compareRun() ? documentStore.compareRunId : null}
+              keyed
+              fallback={
+                <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>
+              }
+            >
+              {(runId) => <CompareView run={documentStore.runs[runId]} />}
+            </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..769e55dc8
--- /dev/null
+++ b/src/documents/HistoryView.tsx
@@ -0,0 +1,216 @@
+import { For, Show, createResource, createSignal, onCleanup } from 'solid-js';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { confirm } from '../lib/dialog';
+import { formatRelativeAge } from '../lib/relativeAge';
+import { documentStore, revertDocumentCommit } from './store';
+import { getProject } from '../store/projects';
+import type { DocumentHistoryEntry } from './types';
+import { DocumentViewer } from './DocumentViewer';
+import { SourceDiff } from './SourceDiff';
+import { createRenderedBlocks } from './use-blocks';
+
+function project() {
+  return documentStore.projectId ? getProject(documentStore.projectId) : undefined;
+}
+
+function EntryDetail(props: {
+  entry: DocumentHistoryEntry;
+  documentPath: string;
+  onReverted: () => void;
+}) {
+  const [mode, setMode] = createSignal<'diff' | 'version'>('diff');
+  const root = () => project()?.path ?? '';
+  const [diff] = createResource(
+    () => ({
+      projectRoot: root(),
+      from: `${props.entry.sha}^`,
+      to: props.entry.sha,
+      documentPath: props.documentPath,
+    }),
+    (args) => invoke<string>(IPC.GetDocumentDiff, args),
+  );
+  const [content] = createResource(
+    () =>
+      mode() === 'version'
+        ? { projectRoot: root(), sha: props.entry.sha, documentPath: props.documentPath }
+        : null,
+    (args) => invoke<string | null>(IPC.GetDocumentAtCommit, args),
+  );
+  const rendered = createRenderedBlocks(() => content() ?? null);
+  const trailerEntries = () => Object.entries(props.entry.trailers);
+
+  async function revert() {
+    const ok = await confirm(
+      `Revert "${props.entry.subject}"? This adds a new commit that undoes it.`,
+      {
+        okLabel: 'Revert',
+        kind: 'warning',
+      },
+    );
+    if (!ok) return;
+    if (await revertDocumentCommit(props.entry.sha)) props.onReverted();
+  }
+
+  return (
+    <div class="docws-history-detail">
+      <div class="docws-history-detail-head">
+        <div class="docws-column-title">
+          <span>{props.entry.subject}</span>
+          <span style={{ 'margin-left': 'auto' }} class="docws-tabs">
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'diff'}
+              onClick={() => setMode('diff')}
+            >
+              Diff
+            </button>
+            <button
+              type="button"
+              class="docws-tab"
+              aria-selected={mode() === 'version'}
+              onClick={() => setMode('version')}
+            >
+              Version
+            </button>
+          </span>
+        </div>
+        <div class="docws-history-meta">
+          <span>{props.entry.shortSha}</span>
+          <span>{props.entry.author}</span>
+          <span>{new Date(props.entry.timestamp * 1000).toLocaleString()}</span>
+          <span class="docws-badge">
+            {props.entry.manual ? 'manual' : props.entry.trailers.Agent}
+          </span>
+        </div>
+        <Show when={props.entry.body}>
+          <div class="docws-history-body">{props.entry.body}</div>
+        </Show>
+        <Show when={trailerEntries().length > 0}>
+          <dl class="docws-trailers">
+            <For each={trailerEntries()}>
+              {([key, value]) => (
+                <>
+                  <dt>{key}</dt>
+                  <dd>{value}</dd>
+                </>
+              )}
+            </For>
+          </dl>
+        </Show>
+        <div class="docws-run-actions">
+          <button
+            type="button"
+            class="docws-btn docws-btn-sm docws-btn-danger"
+            onClick={() => void revert()}
+          >
+            Revert this commit
+          </button>
+        </div>
+      </div>
+      <Show when={mode() === 'version'}>
+        <div class="docws-older-banner">
+          Older version at {props.entry.shortSha}. The current document is on the Document tab.
+        </div>
+      </Show>
+      <div class="docws-column-body">
+        <Show
+          when={mode() === 'diff'}
+          fallback={
+            <DocumentViewer blocks={rendered.blocks()} renderKey={`hist-${props.entry.shortSha}`} />
+          }
+        >
+          <Show when={!diff.loading} fallback={<div class="docws-empty">Loading diff…</div>}>
+            <SourceDiff raw={diff() ?? ''} />
+          </Show>
+        </Show>
+      </div>
+    </div>
+  );
+}
+
+/** `git log` for the document with the Parallel trailers parsed into prose. */
+export function HistoryView() {
+  const [wholeProject, setWholeProject] = createSignal(false);
+  const [selectedSha, setSelectedSha] = createSignal<string | null>(null);
+  const [version, setVersion] = createSignal(0);
+  const documentPath = () => 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, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
+
+  return (
+    <div class="docws-history">
+      <div class="docws-history-list" role="listbox" aria-label="History">
+        <div class="docws-compare-bar">
+          <label class="docws-toggle">
+            <input
+              type="checkbox"
+              checked={wholeProject()}
+              onChange={(e) => setWholeProject(e.currentTarget.checked)}
+            />
+            Whole project
+          </label>
+          <span style={{ 'margin-left': 'auto' }}>{entries()?.length ?? 0} commits</span>
+        </div>
+        <Show when={entries()?.length === 0}>
+          <div class="docws-empty" style={{ padding: '12px 14px' }}>
+            No commits touch this document yet.
+          </div>
+        </Show>
+        <For each={entries() ?? []}>
+          {(entry) => (
+            <button
+              type="button"
+              role="option"
+              class="docws-history-entry"
+              aria-selected={selected()?.sha === entry.sha}
+              onClick={() => setSelectedSha(entry.sha)}
+            >
+              <span class="docws-history-subject">{entry.subject}</span>
+              <span class="docws-history-meta">
+                <span>{entry.shortSha}</span>
+                <span>{formatRelativeAge(entry.timestamp * 1000, nowMs())}</span>
+                <span class="docws-badge">{entry.manual ? 'manual' : entry.trailers.Agent}</span>
+                <Show when={entry.trailers.Candidate}>
+                  <span>candidate {entry.trailers.Candidate}</span>
+                </Show>
+              </span>
+            </button>
+          )}
+        </For>
+      </div>
+      <Show when={selected()} keyed>
+        {(entry) => (
+          <EntryDetail
+            entry={entry}
+            documentPath={documentPath()}
+            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..6c0c1cfa1
--- /dev/null
+++ b/src/documents/NewDocumentProjectDialog.tsx
@@ -0,0 +1,317 @@
+import {
+  For,
+  Show,
+  createEffect,
+  createMemo,
+  createResource,
+  createSignal,
+  onCleanup,
+} from 'solid-js';
+import { Dialog } from '../components/Dialog';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { openDialog } from '../lib/dialog';
+import { errMessage } from '../lib/log';
+import { theme, sectionLabelStyle } from '../lib/theme';
+import { addDocumentProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import type { DocumentFolderInfo, DocumentProjectSetup } from './types';
+import { openDocumentWorkspace } from './store';
+
+interface NewDocumentProjectDialogProps {
+  open: boolean;
+  onClose: () => void;
+}
+
+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 {
+  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;
+}
+
+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
+ * parent directory, and the backend creates the folder, initialises the
+ * repository, writes the document and makes the first commit.
+ */
+export function NewDocumentProjectDialog(props: NewDocumentProjectDialogProps) {
+  const [folder, setFolder] = createSignal('');
+  const [name, setName] = createSignal('');
+  const [nameEdited, setNameEdited] = createSignal(false);
+  const [filter, setFilter] = createSignal('');
+  const [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, so nothing about it is a surprise. */
+  const plan = createMemo(() => {
+    const current = info();
+    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('initialise a Git repository');
+    const match = files().find((f) => f.path === file);
+    if (!match) steps.push(`create and commit ${file}`);
+    else if (!match.committed) steps.push(`commit ${file}`);
+    return steps;
+  });
+
+  function reset() {
+    setFolder('');
+    setName('');
+    setNameEdited(false);
+    setFilter('');
+    setDocumentInput('');
+    setDocumentEdited(false);
+    setError('');
+  }
+
+  function close() {
+    reset();
+    props.onClose();
+  }
+
+  async function chooseFolder() {
+    const selected = await openDialog({ directory: true, multiple: false });
+    if (selected) setFolder(selected as string);
+  }
+
+  const enclosingRepo = () => info()?.enclosingRepo ?? null;
+  const canCreate = () =>
+    folder().trim().startsWith('/') &&
+    documentPath().trim() &&
+    projectName().trim() &&
+    !busy() &&
+    !enclosingRepo();
+
+  async function create() {
+    if (!canCreate()) return;
+    setBusy(true);
+    setError('');
+    try {
+      const setup = await invoke<DocumentProjectSetup>(IPC.PrepareDocumentProject, {
+        projectRoot: folder().trim(),
+        documentPath: documentPath().trim(),
+      });
+      const id = addDocumentProject(projectName().trim(), folder().trim(), setup.documentPath);
+      if (setup.actions.length > 0) showNotification(setup.actions.join(' · '));
+      close();
+      await openDocumentWorkspace(id);
+    } catch (err) {
+      setError(errMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const inputStyle = {
+    background: theme.bgInput,
+    border: `1px solid ${theme.border}`,
+    'border-radius': 'var(--radius-md)',
+    padding: '7px 10px',
+    color: theme.fg,
+    'font-size': '13px',
+    outline: 'none',
+    width: '100%',
+    'box-sizing': 'border-box' as const,
+  };
+
+  return (
+    <Dialog open={props.open} onClose={close} width="520px">
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '14px' }}>
+        <h2 style={{ margin: 0, 'font-size': '16px' }}>New document project</h2>
+        <p style={{ margin: 0, 'font-size': '13px', color: theme.fgMuted }}>
+          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}>Folder</span>
+          <div style={{ display: 'flex', gap: '8px', 'align-items': 'center' }}>
+            <input
+              style={{ ...inputStyle, 'font-family': 'var(--font-mono)', 'font-size': '12px' }}
+              aria-label="Project folder"
+              placeholder="/path/to/folder"
+              value={folder()}
+              onInput={(e) => setFolder(e.currentTarget.value)}
+            />
+            <button
+              type="button"
+              class="docws-btn"
+              onClick={() => void chooseFolder()}
+              disabled={busy()}
+            >
+              Browse…
+            </button>
+          </div>
+          <Show
+            when={!folder().trim() || folder().trim().startsWith('/')}
+            fallback={<span class="docws-error">The folder path has to be absolute.</span>}
+          >
+            <span style={{ 'font-size': '12px', color: theme.fgMuted }}>
+              Add a name to the end of the path to start a new project folder there.
+            </span>
+          </Show>
+        </div>
+        <Show when={folder().trim()}>
+          <div style={{ display: 'flex', 'flex-direction': 'column', gap: '6px' }}>
+            <span style={sectionLabelStyle}>Name</span>
+            <input
+              style={inputStyle}
+              value={projectName()}
+              onInput={(e) => {
+                setNameEdited(true);
+                setName(e.currentTarget.value);
+              }}
+            />
+          </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) => {
+                setDocumentEdited(true);
+                setDocumentInput(e.currentTarget.value);
+              }}
+            />
+            <Show when={files().length > 8}>
+              <input
+                style={inputStyle}
+                placeholder="Filter files…"
+                value={filter()}
+                onInput={(e) => setFilter(e.currentTarget.value)}
+              />
+            </Show>
+            <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={() => {
+                        setDocumentEdited(true);
+                        setDocumentInput(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 {joinSteps(plan())}.
+              </span>
+            </Show>
+          </div>
+        </Show>
+        <Show when={enclosingRepo()}>
+          {(repo) => (
+            <div
+              class="docws-error"
+              style={{
+                'font-size': '13px',
+                display: 'flex',
+                'align-items': 'center',
+                gap: '10px',
+                'flex-wrap': 'wrap',
+              }}
+            >
+              <span style={{ flex: '1', 'min-width': '0' }}>
+                That folder is inside the Git repository at {repo()}. Proposals and history belong
+                to the repository, so the project has to be the repository itself.
+              </span>
+              <button
+                type="button"
+                class="docws-btn docws-btn-sm"
+                onClick={() => setFolder(repo())}
+              >
+                Use the repository
+              </button>
+            </div>
+          )}
+        </Show>
+        <Show when={error()}>
+          <div class="docws-error" style={{ 'font-size': '13px' }}>
+            {error()}
+          </div>
+        </Show>
+        <div style={{ display: 'flex', 'justify-content': 'flex-end', gap: '8px' }}>
+          <button type="button" class="docws-btn" onClick={close}>
+            Cancel
+          </button>
+          <button
+            type="button"
+            class="docws-btn docws-btn-primary"
+            disabled={!canCreate()}
+            onClick={() => void create()}
+          >
+            {busy() ? 'Setting up…' : 'Open workspace'}
+          </button>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
diff --git a/src/documents/RunComposer.tsx b/src/documents/RunComposer.tsx
new file mode 100644
index 000000000..2cc11095b
--- /dev/null
+++ b/src/documents/RunComposer.tsx
@@ -0,0 +1,352 @@
+import { For, Show, createMemo, createSignal, onMount, untrack } from 'solid-js';
+import { store } from '../store/core';
+import {
+  addDocumentAnnotation,
+  dispatchDocumentRun,
+  documentMainAgentId,
+  documentStore,
+  setDocumentMainAgent,
+  type DispatchSelection,
+  type DocumentSelection,
+} from './store';
+import { createAnchor } from './annotation-anchor';
+import type { DocumentBlock } from './markdown-blocks';
+import { getProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import { errMessage } from '../lib/log';
+import { MAX_DOCUMENT_CANDIDATES, documentAgentSupport } from '../../electron/documents/shared';
+import type { AgentDef } from '../ipc/types';
+
+interface RunComposerProps {
+  selection: DocumentSelection;
+  /** Current blocks, for anchoring an annotation to the selection. */
+  blocks: DocumentBlock[];
+  onClose: () => void;
+}
+
+type ComposerMode = 'task' | 'note' | 'question';
+
+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 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());
+  // 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);
+  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;
+  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(() => {
+    // 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> {
+    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();
+      submit();
+    }
+  }
+
+  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"
+      onKeyDown={handleKeyDown}
+      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 style={{ display: mode() === 'task' ? undefined : 'none' }}>
+          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={
+          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)}
+      />
+      <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);
+            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">
+        <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>
+          Enter to {mode() === 'task' ? 'run' : mode() === 'note' ? 'save' : 'ask'} · Esc to close
+        </span>
+        <button type="button" class="docws-btn docws-btn-sm" onClick={() => props.onClose()}>
+          Cancel
+        </button>
+        <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>
+          }
+        >
+          <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/RunsRail.tsx b/src/documents/RunsRail.tsx
new file mode 100644
index 000000000..f05ad5866
--- /dev/null
+++ b/src/documents/RunsRail.tsx
@@ -0,0 +1,156 @@
+import { For, Show, createMemo, createSignal, onCleanup } from 'solid-js';
+import {
+  cancelDocumentRun,
+  candidateLogKey,
+  documentStore,
+  openDocumentCompare,
+  rejectDocumentRun,
+} from './store';
+import { formatRelativeAge } from '../lib/relativeAge';
+import type { DocumentCandidateRecord, DocumentRunRecord } from './types';
+
+function scopeLabel(run: DocumentRunRecord): string {
+  const s = run.scope;
+  if (s.wholeDocument) return 'whole document';
+  const lines = s.startLine === s.endLine ? `L${s.startLine}` : `L${s.startLine}–${s.endLine}`;
+  return s.heading ? `${lines} · ${s.heading}` : lines;
+}
+
+/** What the run's outcome means for one candidate. */
+type CandidateVerdict = 'accepted' | 'passed-over' | 'rejected' | null;
+
+function candidateVerdict(run: DocumentRunRecord, c: DocumentCandidateRecord): CandidateVerdict {
+  if (run.acceptedCandidateId === c.id) return 'accepted';
+  if (!c.commitSha) return null;
+  if (run.status === 'accepted') return 'passed-over';
+  if (run.status === 'rejected') return 'rejected';
+  return null;
+}
+
+function candidateState(c: DocumentCandidateRecord, verdict: CandidateVerdict): string {
+  if (verdict === 'accepted') return 'accepted';
+  if (verdict === 'passed-over') return 'not chosen';
+  if (verdict === 'rejected') return 'rejected';
+  if (c.status === 'running') return 'working…';
+  if (c.status === 'done') return c.commitSha ? 'proposal ready' : 'no changes';
+  if (c.status === 'failed') return 'failed';
+  if (c.status === 'cancelled') return 'cancelled';
+  return 'interrupted';
+}
+
+function CandidateRow(props: {
+  run: DocumentRunRecord;
+  candidate: DocumentCandidateRecord;
+  showLog: boolean;
+}) {
+  const lines = () => documentStore.logs[candidateLogKey(props.run.id, props.candidate.id)] ?? [];
+  const tail = () => lines().slice(-6);
+  const verdict = () => candidateVerdict(props.run, props.candidate);
+  return (
+    <div
+      class="docws-candidate"
+      classList={{ 'is-passed-over': verdict() === 'passed-over' || verdict() === 'rejected' }}
+    >
+      <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 class="docws-candidate-state" classList={{ 'is-accepted': verdict() === 'accepted' }}>
+          {candidateState(props.candidate, verdict())}
+        </span>
+      </div>
+      <Show when={props.candidate.error && props.candidate.status !== 'running'}>
+        <div class="docws-error">{props.candidate.error}</div>
+      </Show>
+      <Show when={props.showLog && tail().length > 0}>
+        <div class="docws-log">{tail().join('\n')}</div>
+      </Show>
+    </div>
+  );
+}
+
+/** 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, setNowMs] = createSignal(Date.now());
+  const clock = setInterval(() => setNowMs(Date.now()), 30_000);
+  onCleanup(() => clearInterval(clock));
+
+  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
+                    run={run}
+                    candidate={candidate}
+                    showLog={run.status === 'running'}
+                  />
+                )}
+              </For>
+              <div class="docws-run-actions">
+                <Show when={run.status === 'running'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm"
+                    onClick={() => void cancelDocumentRun(run.id)}
+                  >
+                    Cancel
+                  </button>
+                </Show>
+                <Show when={canCompare()}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-primary"
+                    onClick={() => openDocumentCompare(run.id)}
+                  >
+                    {proposals() > 1 ? `Compare ${proposals()}` : 'Review'}
+                  </button>
+                </Show>
+                <Show when={run.status === 'finished' || run.status === 'stale'}>
+                  <button
+                    type="button"
+                    class="docws-btn docws-btn-sm docws-btn-danger"
+                    onClick={() => void rejectDocumentRun(run.id)}
+                  >
+                    {proposals() > 0 ? 'Reject all' : 'Dismiss'}
+                  </button>
+                </Show>
+              </div>
+            </div>
+          );
+        }}
+      </For>
+    </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/annotation-anchor.test.ts b/src/documents/annotation-anchor.test.ts
new file mode 100644
index 000000000..1c9f3a04d
--- /dev/null
+++ b/src/documents/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/documents/annotation-anchor.ts b/src/documents/annotation-anchor.ts
new file mode 100644
index 000000000..d8f2020ec
--- /dev/null
+++ b/src/documents/annotation-anchor.ts
@@ -0,0 +1,92 @@
+import type { DocumentAnchor } from './types';
+import { blockRangeText, nearestHeading, type DocumentBlock } from './markdown-blocks';
+
+/** Characters of neighbouring text kept on either side of an anchor. */
+const CONTEXT_CHARS = 160;
+
+function normalize(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+/** Anchors a block range in the current document version. */
+export function createAnchor(
+  blocks: readonly DocumentBlock[],
+  startBlock: number,
+  endBlock: number,
+  path: string,
+  baseSha: string | null,
+): DocumentAnchor {
+  const start = Math.max(0, Math.min(startBlock, endBlock));
+  const end = Math.min(blocks.length - 1, Math.max(startBlock, endBlock));
+  const before = blocks[start - 1]?.raw ?? '';
+  const after = blocks[end + 1]?.raw ?? '';
+  return {
+    path,
+    baseSha,
+    startLine: blocks[start].startLine,
+    endLine: blocks[end].endLine,
+    quote: blockRangeText(blocks, start, end),
+    prefix: normalize(before).slice(-CONTEXT_CHARS),
+    suffix: normalize(after).slice(0, CONTEXT_CHARS),
+    heading: nearestHeading(blocks, start),
+  };
+}
+
+export interface AnchorLocation {
+  startBlock: number;
+  endBlock: number;
+  /** True when the anchor was found at its recorded lines; false when relocated. */
+  exact: boolean;
+}
+
+/**
+ * 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/documents/documents.css b/src/documents/documents.css
new file mode 100644
index 000000000..4f6d6a584
--- /dev/null
+++ b/src/documents/documents.css
@@ -0,0 +1,1162 @@
+/* Document workspace overlay — uses the app's design tokens. */
+
+.docws-overlay {
+  position: fixed;
+  inset: 0;
+  /* Below every Dialog (1000+) so the project editor, settings and confirms
+     opened from inside the workspace render on top of it. */
+  z-index: 950;
+  background: var(--bg);
+  display: flex;
+  flex-direction: column;
+  font-family: var(--font-ui);
+  color: var(--fg);
+}
+
+.docws-header {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  padding: 10px 18px;
+  border-bottom: 1px solid var(--border);
+  background: var(--bg-elevated);
+  flex-shrink: 0;
+  min-width: 0;
+  user-select: none;
+}
+
+/* The header itself is the window drag region. Carve out every possible
+   control so the entire remaining background behaves consistently. These
+   declarations also protect controls that overlap the native title strip. */
+.docws-header button,
+.docws-header input,
+.docws-header select,
+.docws-header textarea,
+.docws-header a {
+  -webkit-app-region: no-drag;
+}
+
+.docws-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 15px;
+  min-width: 0;
+}
+
+.docws-title svg {
+  color: var(--accent);
+  flex-shrink: 0;
+}
+
+.docws-open-editor {
+  padding: 4px;
+  flex-shrink: 0;
+}
+
+.docws-subtitle {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--fg-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  min-width: 0;
+}
+
+/* Branch, head and working-tree state ride in the header instead of taking a
+   strip of their own. */
+.docws-head-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-subtle);
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--border-subtle);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.docws-head-chip svg {
+  flex-shrink: 0;
+}
+
+.docws-head-chip.is-warning {
+  color: var(--warning);
+  border-color: color-mix(in srgb, var(--warning) 45%, transparent);
+}
+
+.docws-banner {
+  padding: 6px 18px;
+  font-size: 12px;
+  border-bottom: 1px solid var(--border-subtle);
+  flex-shrink: 0;
+}
+
+.docws-banner-error {
+  background: color-mix(in srgb, var(--error) 12%, transparent);
+  color: var(--error);
+  border-color: color-mix(in srgb, var(--error) 40%, transparent);
+}
+
+.docws-tabs {
+  display: flex;
+  gap: 2px;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 2px;
+  margin-left: auto;
+}
+
+.docws-tab {
+  background: transparent;
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 5px 12px;
+  color: var(--fg-muted);
+  font-family: var(--font-ui);
+  font-size: 13px;
+  cursor: pointer;
+}
+
+.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-empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  padding: 72px 24px;
+  text-align: center;
+  color: var(--fg-muted);
+  font-size: 13px;
+  max-width: 420px;
+  margin: 0 auto;
+}
+
+.docws-empty-state-title {
+  font-size: 15px;
+  font-weight: 600;
+  color: var(--fg);
+}
+
+.docws-empty-state .docws-btn {
+  margin-top: 8px;
+}
+
+/* ── Rendered document ── */
+
+.docws-doc {
+  position: relative;
+  max-width: 800px;
+  margin: 0 auto;
+  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);
+  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 ── */
+
+/* Sits in the flow under the selected passage; the prose after it moves down
+   instead of disappearing behind it. */
+.docws-composer {
+  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);
+  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-candidate-state {
+  margin-left: auto;
+  color: var(--fg-subtle);
+}
+
+.docws-candidate-state.is-accepted {
+  color: var(--success);
+  font-weight: 600;
+}
+
+.docws-candidate.is-passed-over {
+  opacity: 0.55;
+}
+
+.docws-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--fg-subtle);
+  flex-shrink: 0;
+}
+.docws-dot-running {
+  background: var(--info);
+  animation: docws-pulse 1.2s ease-in-out infinite;
+}
+.docws-dot-done {
+  background: var(--success);
+}
+.docws-dot-failed,
+.docws-dot-interrupted,
+.docws-dot-cancelled {
+  background: var(--error);
+}
+
+@keyframes docws-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+
+.docws-log {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--fg-muted);
+  max-height: 120px;
+  overflow-y: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+  line-height: 1.4;
+}
+
+.docws-run-actions {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+/* ── Compare ── */
+
+.docws-compare {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.docws-compare-bar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 8px 18px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--fg-muted);
+  flex-wrap: wrap;
+}
+
+.docws-compare-bar .docws-instruction {
+  color: var(--fg);
+  font-size: 13px;
+  max-width: 520px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.docws-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.docws-columns {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  overflow-x: auto;
+  gap: 0;
+}
+
+.docws-column {
+  flex: 1 0 460px;
+  min-width: 380px;
+  max-width: 760px;
+  border-right: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.docws-column-base {
+  flex-basis: 420px;
+  background: color-mix(in srgb, var(--bg-elevated) 60%, transparent);
+}
+
+.docws-column-head {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px 14px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.docws-column-title {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+  font-size: 13px;
+}
+
+/* Capped so a talkative agent cannot push its own document out of view. */
+.docws-rationale {
+  font-size: 12px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  max-height: 30vh;
+  overflow-y: auto;
+}
+
+.docws-rationale-summary {
+  font-size: 13px;
+  color: var(--fg);
+}
+
+.docws-rationale ul {
+  margin: 0;
+  padding-left: 18px;
+  color: var(--fg-muted);
+}
+
+.docws-rationale .docws-rationale-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--fg-subtle);
+  margin-top: 4px;
+}
+
+.docws-warning {
+  color: var(--warning);
+}
+
+.docws-error {
+  color: var(--error);
+}
+
+.docws-note {
+  width: 100%;
+  box-sizing: border-box;
+  background: var(--bg-input);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  color: var(--fg);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 5px 8px;
+  resize: vertical;
+  min-height: 30px;
+}
+
+.docws-column-body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 14px 18px 120px;
+}
+
+.docws-column-body .docws-content {
+  font-size: 15px;
+  line-height: 1.6;
+}
+
+.docws-nav {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 12px;
+  color: var(--fg-muted);
+}
+
+/* ── Source diff ── */
+
+.docws-diff {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.docws-diff-line {
+  padding: 0 6px;
+}
+
+.docws-diff-add {
+  background: var(--diff-add-bg);
+}
+
+.docws-diff-remove {
+  background: var(--diff-remove-bg);
+}
+
+.docws-diff-hunk {
+  color: var(--info);
+  margin-top: 8px;
+}
+
+/* ── History ── */
+
+.docws-history {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+}
+
+.docws-history-list {
+  width: 360px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-entry {
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 10px 14px;
+  color: var(--fg);
+  font-family: var(--font-ui);
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.docws-history-entry:hover {
+  background: var(--bg-hover);
+}
+
+.docws-history-entry[aria-selected='true'] {
+  background: var(--bg-selected-subtle);
+  box-shadow: inset 3px 0 0 var(--accent);
+}
+
+.docws-history-subject {
+  font-size: 13px;
+  line-height: 1.35;
+}
+
+.docws-history-meta {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 11px;
+  color: var(--fg-subtle);
+  font-family: var(--font-mono);
+}
+
+.docws-history-detail {
+  flex: 1;
+  min-width: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-history-detail-head {
+  padding: 12px 18px;
+  border-bottom: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.docws-history-body {
+  white-space: pre-wrap;
+  font-size: 13px;
+  color: var(--fg-muted);
+  line-height: 1.5;
+}
+
+.docws-trailers {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 2px 12px;
+  font-size: 12px;
+  font-family: var(--font-mono);
+}
+
+.docws-trailers dt {
+  color: var(--fg-subtle);
+}
+
+.docws-trailers dd {
+  margin: 0;
+  color: var(--fg);
+  word-break: break-all;
+}
+
+.docws-older-banner {
+  padding: 6px 18px;
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  color: var(--warning);
+  font-size: 12px;
+  border-bottom: 1px solid color-mix(in srgb, var(--warning) 40%, transparent);
+}
+
+.docws-picker-list {
+  max-height: 260px;
+  overflow-y: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  background: var(--bg-input);
+  display: flex;
+  flex-direction: column;
+}
+
+.docws-picker-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  text-align: left;
+  background: transparent;
+  border: none;
+  border-bottom: 1px solid var(--border-subtle);
+  padding: 7px 10px;
+  color: var(--fg);
+  font-family: var(--font-mono);
+  font-size: 12px;
+  cursor: pointer;
+}
+
+.docws-picker-item .docws-badge {
+  margin-left: auto;
+}
+
+.docws-picker-item:hover {
+  background: var(--bg-hover);
+}
+
+.docws-picker-item[aria-selected='true'] {
+  background: var(--bg-selected);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .docws-dot-running {
+    animation: none;
+  }
+}
+
+/* ── Annotations ── */
+
+.docws-bubble {
+  margin: 6px 0 10px 12px;
+  padding: 10px 12px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border);
+  background: var(--task-panel-bg);
+  font-size: 13px;
+  line-height: 1.5;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  position: relative;
+  outline: none;
+}
+
+.docws-bubble::before {
+  content: '';
+  position: absolute;
+  left: -12px;
+  top: 12px;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--review);
+}
+
+.docws-bubble.is-question::before {
+  background: var(--info);
+}
+
+.docws-bubble.is-detached {
+  border-style: dashed;
+}
+
+.docws-bubble:focus-visible {
+  border-color: var(--border-focus);
+}
+
+.docws-bubble.is-resolved {
+  padding: 0;
+  border-color: var(--border-subtle);
+  background: transparent;
+}
+
+.docws-bubble.is-resolved::before {
+  opacity: 0.4;
+}
+
+.docws-bubble-collapsed {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  background: transparent;
+  border: none;
+  color: var(--fg-subtle);
+  font-family: var(--font-ui);
+  font-size: 12px;
+  padding: 4px 8px;
+  cursor: pointer;
+  text-align: left;
+}
+
+.docws-bubble-collapsed-text {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  text-decoration: line-through;
+}
+
+.docws-bubble-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--fg-subtle);
+}
+
+.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/documents/html-document.test.ts b/src/documents/html-document.test.ts
new file mode 100644
index 000000000..22fe8ab8d
--- /dev/null
+++ b/src/documents/html-document.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { isHtmlDocument } from './html-document';
+
+describe('isHtmlDocument', () => {
+  it('recognises a page by its doctype', () => {
+    expect(isHtmlDocument('<!DOCTYPE html>\n<html lang="en">\n<head></head>\n')).toBe(true);
+  });
+
+  it('recognises a page that opens with <html>', () => {
+    expect(isHtmlDocument('<html>\n<body>hi</body>\n</html>')).toBe(true);
+    expect(isHtmlDocument('<html lang="en">')).toBe(true);
+  });
+
+  it('looks past leading comments and whitespace', () => {
+    expect(isHtmlDocument('\n<!-- generated -->\n<!DOCTYPE html>\n<html>')).toBe(true);
+  });
+
+  it('leaves markdown with embedded HTML on the block view', () => {
+    expect(isHtmlDocument('# Title\n\n<div class="callout">note</div>\n')).toBe(false);
+    expect(isHtmlDocument('<div>just a fragment</div>')).toBe(false);
+    expect(isHtmlDocument('Prose about <html> tags.')).toBe(false);
+  });
+
+  it('handles empty and missing content', () => {
+    expect(isHtmlDocument('')).toBe(false);
+    expect(isHtmlDocument(null)).toBe(false);
+    expect(isHtmlDocument(undefined)).toBe(false);
+  });
+});
diff --git a/src/documents/html-document.ts b/src/documents/html-document.ts
new file mode 100644
index 000000000..ec1c1e0e6
--- /dev/null
+++ b/src/documents/html-document.ts
@@ -0,0 +1,11 @@
+/**
+ * A document that is a whole HTML page rather than prose. Markdown legitimately
+ * contains HTML fragments, so only a real document preamble counts: a leading
+ * doctype or <html> element, past any comments. Fragments keep the block view,
+ * which is what the selection and agent-scoping model is built on.
+ */
+const HTML_DOCUMENT_RE = /^\s*(?:<!--[\s\S]*?-->\s*)*(?:<!doctype\s+html\b|<html[\s>])/i;
+
+export function isHtmlDocument(content: string | null | undefined): boolean {
+  return !!content && HTML_DOCUMENT_RE.test(content);
+}
diff --git a/src/documents/markdown-blocks.test.ts b/src/documents/markdown-blocks.test.ts
new file mode 100644
index 000000000..bc69f6823
--- /dev/null
+++ b/src/documents/markdown-blocks.test.ts
@@ -0,0 +1,129 @@
+import { describe, expect, it, vi } from 'vitest';
+
+vi.mock('./shiki-highlighter', () => ({
+  highlightLines: async (code: string) => code.split('\n').map((l) => `<span>${l}</span>`),
+}));
+// DOMPurify needs a DOM; sanitization itself is its job, not this module's.
+vi.mock('dompurify', () => ({ default: { sanitize: (html: string) => html } }));
+
+import {
+  blockRangeText,
+  diffBlocks,
+  nearestHeading,
+  renderDocumentBlocks,
+  sectionRange,
+  type DocumentBlock,
+} from './markdown-blocks';
+
+const doc = [
+  '# Title',
+  '',
+  'First paragraph',
+  'continues here.',
+  '',
+  '',
+  '## Section A',
+  '',
+  '- one',
+  '- two',
+  '',
+  '```ts',
+  'const x = 1;',
+  '```',
+  '',
+  '### Sub',
+  '',
+  'Deep text.',
+  '',
+  '## Section B',
+  '',
+  'Last.',
+].join('\n');
+
+describe('renderDocumentBlocks', () => {
+  it('maps every block to its source lines', async () => {
+    const blocks = await renderDocumentBlocks(doc);
+    const summary = blocks.map((b) => [b.type, b.startLine, b.endLine]);
+    expect(summary).toEqual([
+      ['heading', 1, 1],
+      ['paragraph', 3, 4],
+      ['heading', 7, 7],
+      ['list', 9, 10],
+      ['code', 12, 14],
+      ['heading', 16, 16],
+      ['paragraph', 18, 18],
+      ['heading', 20, 20],
+      ['paragraph', 22, 22],
+    ]);
+    expect(blocks[0].headingLevel).toBe(1);
+    expect(blocks[0].headingText).toBe('Title');
+    expect(blocks[1].html).toContain('<p>');
+    expect(blocks[4].html).toContain('shiki-block');
+    expect(blocks[4].html).toContain('data-lang="ts"');
+  });
+
+  it('handles CRLF sources', async () => {
+    const blocks = await renderDocumentBlocks('# A\r\n\r\nmiddle\r\n\r\nB');
+    expect(blocks.map((b) => b.startLine)).toEqual([1, 3, 5]);
+  });
+
+  it('renders mermaid fences as placeholders', async () => {
+    const blocks = await renderDocumentBlocks('```mermaid\ngraph TD; A-->B\n```');
+    expect(blocks[0].html).toContain('mermaid-block');
+    expect(blocks[0].html).toContain('data-mermaid');
+  });
+});
+
+describe('sectionRange and nearestHeading', () => {
+  it('spans a heading through its subsections', async () => {
+    const blocks = await renderDocumentBlocks(doc);
+    expect(sectionRange(blocks, 2)).toEqual([2, 6]); // Section A up to Section B
+    expect(sectionRange(blocks, 5)).toEqual([5, 6]); // Sub
+    expect(sectionRange(blocks, 7)).toEqual([7, 8]);
+    expect(sectionRange(blocks, 1)).toEqual([1, 1]); // not a heading
+    expect(nearestHeading(blocks, 4)).toBe('Section A');
+    expect(nearestHeading(blocks, 0)).toBe('Title');
+  });
+});
+
+function fake(raws: string[]): DocumentBlock[] {
+  return raws.map((raw, index) => ({
+    index,
+    type: 'paragraph',
+    startLine: index + 1,
+    endLine: index + 1,
+    raw,
+    html: '',
+  }));
+}
+
+describe('diffBlocks', () => {
+  it('marks identical documents as unchanged', () => {
+    const r = diffBlocks(fake(['a', 'b']), fake(['a', 'b']));
+    expect(r.base).toEqual(['same', 'same']);
+    expect(r.candidate).toEqual(['same', 'same']);
+  });
+
+  it('pairs a rewritten block as changed and a new one as added', () => {
+    const r = diffBlocks(fake(['a', 'b', 'c']), fake(['a', 'B!', 'c', 'd']));
+    expect(r.base).toEqual(['same', 'changed', 'same']);
+    expect(r.candidate).toEqual(['same', 'changed', 'same', 'added']);
+  });
+
+  it('marks a deleted block as removed', () => {
+    const r = diffBlocks(fake(['a', 'b', 'c']), fake(['a', 'c']));
+    expect(r.base).toEqual(['same', 'removed', 'same']);
+    expect(r.candidate).toEqual(['same', 'same']);
+  });
+
+  it('ignores whitespace-only differences', () => {
+    const r = diffBlocks(fake(['a  b\n']), fake(['a b']));
+    expect(r.candidate).toEqual(['same']);
+  });
+});
+
+describe('blockRangeText', () => {
+  it('joins raw blocks without trailing newlines', () => {
+    expect(blockRangeText(fake(['x\n\n', 'y\n']), 0, 1)).toBe('x\n\ny');
+  });
+});
diff --git a/src/documents/markdown-blocks.ts b/src/documents/markdown-blocks.ts
new file mode 100644
index 000000000..ee46523ef
--- /dev/null
+++ b/src/documents/markdown-blocks.ts
@@ -0,0 +1,220 @@
+import DOMPurify from 'dompurify';
+import { Marked, type Token, type Tokens } from 'marked';
+import { highlightLines } from '../lib/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/documents/store.ts b/src/documents/store.ts
new file mode 100644
index 000000000..425250a1e
--- /dev/null
+++ b/src/documents/store.ts
@@ -0,0 +1,683 @@
+/**
+ * Document workspace state: the rendered canonical document, the runs made
+ * against it, and the comparison/history views. Kept apart from the task
+ * store because none of it is a task: proposals live in Git, not in panels.
+ */
+import { untrack } from 'solid-js';
+import { createStore, produce } from 'solid-js/store';
+import { IPC } from '../../electron/ipc/channels';
+import { invoke } from '../lib/ipc';
+import { errMessage } from '../lib/log';
+import type { AgentDef } from '../ipc/types';
+import type {
+  DocumentAnchor,
+  DocumentAnnotation,
+  DocumentAnnotationEvent,
+  DocumentAnnotationKind,
+  DocumentCandidateRecord,
+  DocumentCandidateSpec,
+  DocumentRunEvent,
+  DocumentRunRecord,
+  DocumentScope,
+  DocumentSnapshot,
+} from './types';
+import {
+  DEFAULT_DOCUMENT_MAIN_AGENT,
+  MAX_DOCUMENT_CANDIDATES,
+  documentAgentSupport,
+} from '../../electron/documents/shared';
+import { store, setStore } from '../store/core';
+import { getProject, updateProject } from '../store/projects';
+import { showNotification } from '../store/notification';
+import type { Project } from '../store/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;
+}
+
+/** 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;
+  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,
+  annotations: [],
+  lastDeleted: null,
+  showResolved: false,
+  composerDraft: null,
+  snapshot: null,
+  loading: false,
+  error: null,
+  runs: {},
+  runOrder: [],
+  logs: {},
+  view: 'document',
+  compareRunId: null,
+  selection: null,
+  dispatching: false,
+});
+
+export { docStore as documentStore };
+
+function activeProject(): Project | undefined {
+  return docStore.projectId ? getProject(docStore.projectId) : undefined;
+}
+
+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}`;
+}
+
+/** 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;
+  try {
+    const snapshot = await invoke<DocumentSnapshot>(IPC.ReadDocument, {
+      projectRoot: project.path,
+      documentPath: project.documentPath,
+    });
+    if (stillOpen(project.id)) setDocStore({ snapshot, error: null });
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+function sortRunIds(runs: Record<string, DocumentRunRecord>): string[] {
+  return Object.values(runs)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+    .map((r) => r.id);
+}
+
+export async function loadDocumentRuns(): Promise<void> {
+  const project = activeProject();
+  if (!project) return;
+  try {
+    const runs = await invoke<DocumentRunRecord[]>(IPC.ListDocumentRuns, {
+      projectRoot: project.path,
+    });
+    const byId: Record<string, DocumentRunRecord> = {};
+    for (const run of runs) byId[run.id] = run;
+    if (!stillOpen(project.id)) return;
+    setDocStore(
+      produce((s) => {
+        s.runs = byId;
+        s.runOrder = sortRunIds(byId);
+      }),
+    );
+  } catch (err) {
+    if (stillOpen(project.id)) setDocStore('error', errMessage(err));
+  }
+}
+
+export async function openDocumentWorkspace(projectId: string): Promise<void> {
+  const project = getProject(projectId);
+  if (!project?.documentPath || !store.documentWorkspacesEnabled) 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,
+    annotations: [],
+    lastDeleted: null,
+    composerDraft: null,
+  });
+  setStore('activeDocumentProjectId', projectId);
+  // 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) => {
+    untrack(() => {
+      if (stillOpen(projectId)) setDocStore('error', errMessage(err));
+    });
+  });
+  await Promise.all([refreshDocumentSnapshot(), loadDocumentRuns(), loadDocumentAnnotations()]);
+  if (stillOpen(projectId)) setDocStore('loading', false);
+}
+
+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,
+    composerDraft: null,
+  });
+  setStore('activeDocumentProjectId', null);
+}
+
+export function setDocumentComposerDraft(draft: ComposerDraft | null): void {
+  setDocStore('composerDraft', draft);
+}
+
+export function setDocumentView(view: DocumentView): void {
+  setDocStore('view', view);
+}
+
+export function setDocumentSelection(selection: DocumentSelection | null): void {
+  setDocStore('selection', selection);
+}
+
+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') && r.candidates.some((c) => c.commitSha),
+    );
+}
+
+export function candidateLogKey(runId: string, candidateId: string): string {
+  return `${runId}/${candidateId}`;
+}
+
+/** Agent that owns the main session; falls back to the first resumable one installed. */
+export function documentMainAgentId(project: Project | undefined): string {
+  if (project?.documentMainAgentId) return project.documentMainAgentId;
+  const installed = store.availableAgents.filter((a) => a.available !== false);
+  const preferred = installed.find((a) => a.id === DEFAULT_DOCUMENT_MAIN_AGENT);
+  if (preferred) return preferred.id;
+  return (
+    installed.find((a) => documentAgentSupport(a.id).resume)?.id ?? DEFAULT_DOCUMENT_MAIN_AGENT
+  );
+}
+
+export function setDocumentMainAgent(agentId: string): void {
+  const project = activeProject();
+  if (project) updateProject(project.id, { documentMainAgentId: agentId });
+}
+
+export interface DispatchSelection {
+  agent: AgentDef;
+  count: number;
+}
+
+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);
+    const draft = docStore.composerDraft;
+    setDocStore({ selection: null, composerDraft: null });
+    if (draft?.annotationId) void linkAnnotationToRun(draft.annotationId, run.id);
+    void refreshDocumentSnapshot();
+    return run;
+  } finally {
+    setDocStore('dispatching', false);
+  }
+}
+
+function upsertRun(run: DocumentRunRecord): void {
+  setDocStore(
+    produce((s) => {
+      s.runs[run.id] = run;
+      s.runOrder = sortRunIds(s.runs);
+    }),
+  );
+}
+
+/** Remember the main session so the next dispatch resumes it. The event names
+ *  the project root because the run may finish after its workspace was closed
+ *  or another project was opened. */
+function recordMainSession(
+  projectRoot: string,
+  run: DocumentRunRecord,
+  candidate: DocumentCandidateRecord,
+): void {
+  if (!candidate.isMain || !candidate.sessionId) return;
+  const project = store.projects.find((p) => p.path === projectRoot && p.kind === 'document');
+  if (!project) return;
+  updateProject(project.id, {
+    documentSessions: {
+      ...(project.documentSessions ?? {}),
+      [candidate.agentId]: { sessionId: candidate.sessionId, lastSha: run.baseSha },
+    },
+  });
+}
+
+export function applyDocumentRunEvent(event: DocumentRunEvent): void {
+  const forOpenProject = activeProject()?.path === event.projectRoot;
+  switch (event.type) {
+    case 'log':
+      if (!forOpenProject) return;
+      setDocStore(
+        produce((s) => {
+          const key = candidateLogKey(event.runId, event.candidateId);
+          const lines = s.logs[key] ?? [];
+          lines.push(event.text);
+          if (lines.length > MAX_LOG_LINES) lines.splice(0, lines.length - MAX_LOG_LINES);
+          s.logs[key] = lines;
+        }),
+      );
+      return;
+    case 'candidate': {
+      const run = docStore.runs[event.runId];
+      if (run) recordMainSession(event.projectRoot, run, event.candidate);
+      if (!forOpenProject || !run) return;
+      setDocStore(
+        produce((s) => {
+          const target = s.runs[event.runId];
+          const idx = target.candidates.findIndex((c) => c.id === event.candidate.id);
+          if (idx >= 0) target.candidates[idx] = event.candidate;
+          else target.candidates.push(event.candidate);
+        }),
+      );
+      return;
+    }
+    case 'run': {
+      if (event.run.status === 'finished') {
+        for (const c of event.run.candidates) recordMainSession(event.projectRoot, event.run, c);
+      }
+      if (!forOpenProject) return;
+      upsertRun(event.run);
+      if (event.run.status === 'finished') {
+        setDocStore(
+          produce((s) => {
+            s.logs = Object.fromEntries(
+              Object.entries(s.logs).filter(([key]) => !key.startsWith(`${event.run.id}/`)),
+            );
+          }),
+        );
+        const proposals = event.run.candidates.filter((c) => c.commitSha).length;
+        showNotification(
+          proposals > 0
+            ? `${proposals} proposal${proposals === 1 ? '' : 's'} ready to compare`
+            : 'Run finished without changes',
+        );
+      }
+      return;
+    }
+  }
+}
+
+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;
+  }
+}
+
+// --- 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;
+}
+
+function isRunEvent(v: unknown): v is DocumentRunEvent {
+  if (!v || typeof v !== 'object') return false;
+  const e = v as { type?: unknown; projectRoot?: unknown };
+  return typeof e.type === 'string' && typeof e.projectRoot === 'string';
+}
+
+/** Subscribes to main-process pushes; call once at startup. Returns a disposer. */
+export function initDocumentListeners(): () => void {
+  const offRun = window.electron.ipcRenderer.on(IPC.DocumentRunEvent, (payload: unknown) => {
+    if (isRunEvent(payload)) untrack(() => applyDocumentRunEvent(payload));
+  });
+  const offAnnotation = window.electron.ipcRenderer.on(
+    IPC.DocumentAnnotationEvent,
+    (payload: unknown) => {
+      if (!isAnnotationEvent(payload)) return;
+      untrack(() => {
+        if (activeProject()?.path === payload.projectRoot) putAnnotation(payload.annotation);
+      });
+    },
+  );
+  const offChanged = window.electron.ipcRenderer.on(IPC.DocumentChanged, (payload: unknown) => {
+    const p = payload as DocumentChangedPayload | undefined;
+    if (!p) return;
+    untrack(() => {
+      if (!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, 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();
+  };
+}
diff --git a/src/documents/types.ts b/src/documents/types.ts
new file mode 100644
index 000000000..74096439a
--- /dev/null
+++ b/src/documents/types.ts
@@ -0,0 +1,2 @@
+/** The document workspace's IPC shapes, mirrored for the renderer. */
+export type * from '../../electron/documents/types';
diff --git a/src/documents/use-blocks.ts b/src/documents/use-blocks.ts
new file mode 100644
index 000000000..7a053c27c
--- /dev/null
+++ b/src/documents/use-blocks.ts
@@ -0,0 +1,61 @@
+import { createEffect, createSignal, onCleanup } from 'solid-js';
+import { renderDocumentBlocks, type DocumentBlock } from './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/store/autosave.ts b/src/store/autosave.ts
index 9cb53fe6f..33ce9f186 100644
--- a/src/store/autosave.ts
+++ b/src/store/autosave.ts
@@ -41,6 +41,7 @@ export function persistedSnapshot(): string {
     focusMode: store.focusMode,
     coordinatorNotificationDelayMs: store.coordinatorNotificationDelayMs,
     coordinatorModeEnabled: store.coordinatorModeEnabled,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed,
     autoStartRemoteAccess: store.autoStartRemoteAccess,
     shareDockerAgentAuth: store.shareDockerAgentAuth,
diff --git a/src/store/core.ts b/src/store/core.ts
index 75301e4a7..c9b97edc0 100644
--- a/src/store/core.ts
+++ b/src/store/core.ts
@@ -90,6 +90,8 @@ export const [store, setStore] = createStore<AppStore>({
   taskSplitMode: {},
   verboseLogging: false,
   coordinatorModeEnabled: false,
+  documentWorkspacesEnabled: false,
+  activeDocumentProjectId: null,
   coordinatorNotificationDelayMs: 60_000,
   coordinatorControlHintDismissed: false,
   defaultStepsEnabled: false,
diff --git a/src/store/persistence.ts b/src/store/persistence.ts
index 16b127333..14ff1de52 100644
--- a/src/store/persistence.ts
+++ b/src/store/persistence.ts
@@ -244,6 +244,7 @@ export async function saveState(): Promise<void> {
     darkThemePreset: store.darkThemePreset !== 'islands-dark' ? store.darkThemePreset : undefined,
     darkThemeCustomId: store.darkThemeCustomId ?? undefined,
     coordinatorModeEnabled: store.coordinatorModeEnabled || undefined,
+    documentWorkspacesEnabled: store.documentWorkspacesEnabled || undefined,
     coordinatorControlHintDismissed: store.coordinatorControlHintDismissed || undefined,
     defaultStepsEnabled: store.defaultStepsEnabled || undefined,
     defaultSkipPermissions: store.defaultSkipPermissions || undefined,
@@ -415,6 +416,7 @@ interface LegacyPersistedState {
   darkThemePreset?: unknown;
   darkThemeCustomId?: unknown;
   coordinatorModeEnabled?: unknown;
+  documentWorkspacesEnabled?: unknown;
   coordinatorControlHintDismissed?: unknown;
   defaultStepsEnabled?: unknown;
   defaultSkipPermissions?: unknown;
@@ -613,6 +615,7 @@ export async function loadState(): Promise<void> {
       }
 
       s.coordinatorModeEnabled = raw.coordinatorModeEnabled === true;
+      s.documentWorkspacesEnabled = raw.documentWorkspacesEnabled === true;
 
       s.coordinatorControlHintDismissed = raw.coordinatorControlHintDismissed === true;
 
diff --git a/src/store/projects.ts b/src/store/projects.ts
index 5ced78edc..8c3966e08 100644
--- a/src/store/projects.ts
+++ b/src/store/projects.ts
@@ -30,6 +30,36 @@ export function addProject(name: string, path: string, isGitRepo?: boolean): str
   return id;
 }
 
+/** A document project: a git repo plus one document inside it. */
+export function addDocumentProject(name: string, path: string, documentPath: string): string {
+  const id = crypto.randomUUID();
+  const project: Project = {
+    id,
+    name,
+    path,
+    color: randomPastelColor(),
+    isGitRepo: true,
+    kind: 'document',
+    documentPath,
+  };
+  // Not the default for new tasks: a document project has no task flow.
+  setStore(
+    produce((s) => {
+      s.projects.push(project);
+    }),
+  );
+  return id;
+}
+
+export function isDocumentProject(project: Project | undefined): boolean {
+  return project?.kind === 'document' && typeof project.documentPath === 'string';
+}
+
+/** Projects that take tasks. Document projects have no task flow, so nothing offers them. */
+export function codeProjects(): Project[] {
+  return store.projects.filter((project) => !isDocumentProject(project));
+}
+
 export function removeProject(projectId: string): void {
   // Guard: skip removal if any tasks still reference this project
   const allTaskIds = [...store.taskOrder, ...store.collapsedTaskOrder];
@@ -67,6 +97,8 @@ export function updateProject(
       | 'verifyCommand'
       | 'terminalBookmarks'
       | 'isGitRepo'
+      | 'documentMainAgentId'
+      | 'documentSessions'
     >
   >,
 ): void {
@@ -92,6 +124,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/remoteTaskHandler.ts b/src/store/remoteTaskHandler.ts
index 48e63a7ec..4d4d735cb 100644
--- a/src/store/remoteTaskHandler.ts
+++ b/src/store/remoteTaskHandler.ts
@@ -5,6 +5,7 @@
 // main-side bridge.
 
 import { store } from './core';
+import { codeProjects } from './projects';
 import { createTask, updateTaskNotes } from './tasks';
 import { invoke } from '../lib/ipc';
 import { IPC } from '../../electron/ipc/channels';
@@ -38,7 +39,7 @@ function handleGetProjects(req: RendererRequest): void {
   reply(
     req.reqId,
     true,
-    store.projects.map((p) => ({ id: p.id, name: p.name })),
+    codeProjects().map((p) => ({ id: p.id, name: p.name })),
   );
 }
 
diff --git a/src/store/store.ts b/src/store/store.ts
index b41c4cf4f..5341a5b4c 100644
--- a/src/store/store.ts
+++ b/src/store/store.ts
@@ -8,6 +8,9 @@ export {
   getProjectPath,
   getProjectBranchPrefix,
   pickAndAddProject,
+  addDocumentProject,
+  codeProjects,
+  isDocumentProject,
   validateProjectPaths,
   relinkProject,
   isProjectMissing,
@@ -116,6 +119,7 @@ export {
   setTaskViewportVisibility,
   toggleSidebar,
   toggleArena,
+  setDocumentWorkspacesEnabled,
   toggleFocusMode,
   toggleTaskFocusMode,
   setTaskSplitMode,
diff --git a/src/store/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);
 }
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);