docs(ui): record the shared diff plumbing and the modal chrome rules

DiffEditorSetup is the place for AvaloniaEdit host boilerplate now, so note why
the diff viewer and the merge editor share it but stay separate controls, and
that ModalShell owns the titlebar drag and the OffScreenMargin inset for every
modal.

src/ClaudeDo.Ui/CLAUDE.md

@@ -31,8 +31,8 @@ ViewModels/
   Conflicts/  — ConflictResolverViewModel + ConflictModels
 Views/          — mirrors the VM layout; Islands/Detail/ holds TaskHeaderBar,
                   DescriptionStepsCard, WorkConsole; plus SessionTerminalView
-Views/Controls/ — MarkdownView, ModalShell, ThemedDatePicker, DiffTextView, InheritedBadge,
-                  AgentConfigEditor, UsagePill, UsageGaugeBar
+Views/Controls/ — MarkdownView, ModalShell, ThemedDatePicker, DiffTextView, DiffEditorSetup,
+                  InheritedBadge, AgentConfigEditor, UsagePill, UsageGaugeBar
 Design/         — Tokens.axaml (design tokens; merged before styles)
                   + IslandStyles.axaml (component styles + the filled icon geometry library)
 ```
@@ -76,6 +76,12 @@ split/wrap toggles persist to `ui.config.json` via `AppSettings`.
 single-task and planning unit-merge conflicts. Full detail →
 [review-merge](../../docs/explore-notes/review-merge.md).
 
+The two surfaces are **not** variants of one control (read-only 2-way renderer over aligned rows
+vs. 3-way editor over a writable document), but they share their AvaloniaEdit host plumbing via
+`Views/Controls/DiffEditorSetup.cs`: the process-wide TextMate `Registry`, `InstallHighlighting`,
+`ApplyGrammar`, the `Brush` resource fallback, the `Seg` segment, and `VerticalScrollSync`. Put
+new editor boilerplate there rather than copying it a third time.
+
 ## Services
 
 - **WorkerClient / IWorkerClient** — SignalR client on `http://127.0.0.1:47821/hub`, auto-reconnect with exponential backoff. The surface **tracks `WorkerHub`** — treat `src/ClaudeDo.Worker/Hub/WorkerHub.cs` as the canonical method list rather than duplicating it here. Events mirror `HubBroadcaster`. Lifecycle (`StartAsync`/`StopAsync`) and a few admin methods live only on the concrete `WorkerClient`.
@@ -96,6 +102,11 @@ uppercase.
 Modals use `TaskCompletionSource` results behind the reusable `ModalShell` control — the dialog
 sets the result on save/cancel, the caller awaits the TCS.
 
+`ModalShell` also owns the window chrome for every modal: the titlebar drag goes through
+`Window.BeginMoveDrag` (so Windows snap works — drag to the top edge to maximise; the OS only
+snaps `CanResize="True"` windows, which is the opt-in), and it insets itself by the window's
+`OffScreenMargin` so a maximised extended-client-area window isn't clipped at the edges.
+
 ## Gotchas
 
 - **`PathIcon` *fills* its geometry.** Line-art/stroke icons must be authored as filled geometry or rendered with a stroked `Path` (e.g. `Icon.PlanDay` via the `Path.plan-icon` style). A pure stroke path in a `PathIcon` is **invisible**.