F4: document propose/accept — manual smoke, README, playground loop (#12)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -12,7 +12,8 @@ catalog (a pure, key-free SDK call) in a notification and the
 "Cowriting (Cline SDK)" output channel.
 
 Features shipped so far: F2 region-anchored threads (Feature #4), F3 live
-human/Claude attribution (Feature #6).
+human/Claude attribution (Feature #6), F4 propose/accept diff flow
+(Feature #12).
 
 ## Architecture
 
@@ -67,13 +68,36 @@ Attribution" output channel) rather than silently moved or discarded.
 - **`Cowriting: Ask Claude to Edit Selection`** — select text → enter an
   instruction → a live `@cline/sdk` turn runs on the built-in `claude-code`
   provider (rides your local Claude Code Pro/Max login; the extension stores no
-  credentials). The replacement lands in the buffer as a Claude-attributed span.
+  credentials). As of F4 the turn ends in a **proposal** (see below); accepted
+  text lands as a Claude-attributed span.
 - **`Cowriting: Toggle Attribution`** — show/hide attribution decorations.
 - `cowriting.applyAgentEdit` _(palette-hidden)_ — the single machine-edit
   ingress seam. Tests drive this directly so CI requires no LLM.
 
 Design: `vscode-cowriting-plugin-content/specs/coauthoring-attribution.md`.
 
+## F4 — Propose/accept diff flow (Feature #12)
+
+Claude's edits arrive as **pending proposals** — propose-by-default, the
+document never changes without your say-so. A proposal renders two ways at
+once: an **amber tint** on the target range, and a "Claude proposes" comment
+thread showing a fenced `diff` of current → proposed text with two actions:
+
+- **✓ Accept Proposal** — applies the replacement through the `applyAgentEdit`
+  seam, so it lands Claude-attributed (F3) — and the proposal disappears.
+- **✗ Reject Proposal** — the document is untouched; the proposal disappears.
+
+Pending proposals persist git-natively in the same sidecar (`proposals[]`,
+sharing the F2/F3 `anchors` fingerprints), survive reload, and re-anchor as
+surrounding text changes. If the **target text itself** changes, the proposal
+goes **stale** (status-bar count, accept disabled — never applied by guess);
+undo the change and it becomes decidable again. `cowriting.proposeAgentEdit`
+_(palette-hidden)_ is the programmatic propose ingress E2E drives — no LLM in
+CI.
+
+Design: `vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md`.
+Live smoke: [`docs/MANUAL-SMOKE-F4.md`](docs/MANUAL-SMOKE-F4.md).
+
 ## Develop
 
 - `npm run watch` — rebuild on change.