diff --git a/docs/components/active-agents.md b/docs/components/active-agents.md
index ba75ecf8..279dbe6f 100644
--- a/docs/components/active-agents.md
+++ b/docs/components/active-agents.md
@@ -36,22 +36,21 @@ Command Palette → "Toggle Active Agents Panel".
 | **Done** | finished, not yet seen | blue |
 | **Idle** | nothing running / seen | grey |
 
-The list is sorted by urgency: **Blocked → Working → Done → Idle**, then by most
-recently changed. (See [agent-detection](agent-detection.md) for how these states
-are determined.)
+Rows appear in the order agents are first detected. (See
+[agent-detection](agent-detection.md) for how these states are determined.)
 
 ## Interactions
 
 - **Click a row** → focuses that worktree + tab + pane and brings Prowl forward. A
   **Done** row downgrades to **Idle** once focused.
-- **Keyboard navigation:** `⌃⌥↓` next agent, `⌃⌥↑` previous agent (wraps).
+- **Keyboard navigation:** `⌥⌃↓` next agent, `⌥⌃↑` previous agent (wraps).
 - **Resize** the panel by dragging its top edge (height is remembered).
 - **Auto-show:** if `autoShowActiveAgentsPanel` is on and the panel is hidden, a
   newly detected agent opens it automatically.
 
 ## Empty state
 
-When nothing is running: "New agents will appear here."
+When nothing is running: "New agents will appear here".
 
 ## Settings
 
@@ -62,10 +61,11 @@ When nothing is running: "New agents will appear here."
 ## Relationship to other features
 
 - **Agent detection** ([agent-detection](agent-detection.md)) feeds this panel.
-- **Notifications** ([notifications](notifications.md)) fire on the same
-  transitions (e.g. an agent finishing → Done).
+- **Notifications** ([notifications](notifications.md)) are driven by a separate
+  signal — terminal bell / OSC desktop notifications and command-finished
+  events — which usually coincides with, but is not the same as, a detected finish.
 - **Canvas** ([canvas](canvas.md)) is the spatial counterpart — cards light up on
-  the same completion signal.
+  that same notification/unread signal, not on the detected status itself.
 
 ## Gotchas for agents
 
diff --git a/docs/components/agent-detection.md b/docs/components/agent-detection.md
index 0bb7d95a..15e9af3a 100644
--- a/docs/components/agent-detection.md
+++ b/docs/components/agent-detection.md
@@ -56,8 +56,8 @@ A **Done** pane becomes **Idle** the moment you focus it.
 - ~**300 ms** when an agent is present or you're typing (active).
 - ~**2 s** when idle.
 
-The heavier process probe is throttled (≈ every few seconds unless something
-changes) so many panes don't add up to high CPU. Status indicators redraw on a
+The heavier process probe is throttled (cached ≈ 0.75 s per process group unless
+something changes) so many panes don't add up to high CPU. Status indicators redraw on a
 coarse tick rather than every frame for the same reason.
 
 ## The indicator
diff --git a/docs/components/canvas.md b/docs/components/canvas.md
index 37014b29..1b8140c7 100644
--- a/docs/components/canvas.md
+++ b/docs/components/canvas.md
@@ -32,9 +32,11 @@ Canvas lets you **type a command once and send it to many agents at once**:
 
 Selection controls:
 - `⌘`-click a card body → toggle it in/out of the selection.
-- `⌘`-click an already-selected card → make it the **primary** (the one you type
-  into) without deselecting the rest.
-- Click empty canvas, or press **Esc** → clear the selection.
+- **Click (without `⌘`)** an already-selected card → make it the **primary** (the
+  one you type into) without deselecting the rest. (`⌘`-clicking a selected card
+  instead *removes* it from the selection.)
+- Click empty canvas → clear the selection. **Esc** also clears it while
+  broadcasting (two or more cards selected).
 
 ## Working with cards
 
@@ -74,7 +76,8 @@ explaining pan/zoom/expand.
 - Default card size adapts to screen width (roughly 800×550 on a 14", larger on a
   27"). Cards have generous min/max bounds and snap-animate on resize.
 - On first entry, cards auto-arrange into a balanced grid. Positions, sizes, and
-  z-order are remembered for the session and restored when you return to Canvas.
+  z-order are persisted across launches (in `UserDefaults`) and restored when you
+  return to Canvas.
 - Closing a card's last tab prunes it; focus advances to a neighbor.
 
 ## Many agents at once
diff --git a/docs/components/cli.md b/docs/components/cli.md
index 36427bdd..fed71120 100644
--- a/docs/components/cli.md
+++ b/docs/components/cli.md
@@ -123,8 +123,9 @@ the command's output to a file and `cat` it.
 Send a keystroke.
 
 - `--repeat <1–100>` — repeat the key.
-- Tokens: named keys (`enter`/`return`, `esc`, `tab`, `backspace`, `delete`,
-  `space`, arrows `up`/`down`/`left`/`right`, `pageup`/`pagedown`, `home`/`end`,
+- Tokens: named keys (`enter`/`return`, `esc`, `tab`, `backspace` — `delete` is an
+  alias for backspace; use `delete-forward` for a forward delete — `space`, arrows
+  `up`/`down`/`left`/`right`, `pageup`/`pagedown`, `home`/`end`,
   `f1`–`f12`, punctuation), single characters (`a`–`z`, `0`–`9`, etc.), and
   modifier combos joined with `-`: `cmd`/`command`, `shift`, `opt`/`option`/`alt`,
   `ctrl`/`control` — e.g. `ctrl-c`, `cmd-k`, `shift-tab`, `cmd-shift-p`.
diff --git a/docs/components/notifications.md b/docs/components/notifications.md
index 3747daee..bee00625 100644
--- a/docs/components/notifications.md
+++ b/docs/components/notifications.md
@@ -12,8 +12,9 @@
 Prowl watches your panes and surfaces three kinds of alerts so you can leave the
 screen and come back exactly when you're needed:
 
-1. **Agent reminders** — when an agent in an unfocused worktree produces output or
-   finishes, Prowl flags that worktree (bell/unread) and can notify.
+1. **Agent reminders** — when an agent in an unfocused worktree rings the bell or
+   emits a desktop notification (e.g. on finishing), Prowl flags that worktree
+   (bell/unread) and can notify.
 2. **Command-finished notifications** — when a long-running command completes.
 3. **Terminal bell / desktop notifications** — bell (BEL) and explicit terminal
    notifications increment unread indicators.
@@ -30,8 +31,10 @@ screen and come back exactly when you're needed:
 Custom commands also post a success toast when they exit 0.
 
 Whether these become **macOS system banners** depends on
-`systemNotificationsEnabled`; in-app alerts depend on `inAppNotificationsEnabled`;
-sound depends on `notificationSoundEnabled`.
+`systemNotificationsEnabled`; in-app alerts depend on `inAppNotificationsEnabled`.
+A standalone sound (`notificationSoundEnabled`) plays only when system
+notifications are **disabled** — when banners are on, the banner carries its own
+sound.
 
 ## Where unread shows up
 
@@ -52,7 +55,7 @@ top of its section. **Jump to Latest Unread** (`⌘⌥U`) takes you straight to
 - **Badge:** `showNotificationDotOnDock` shows an unread count on the Dock icon.
   Requires macOS notification permission + "Badge app icon" enabled; Prowl
   disables the toggle if the system doesn't allow it.
-- **Bounce:** `dockBounceMode` — `off`, `once` (single bounce), or `continuously`
+- **Bounce:** `dockBounceMode` — `off`, `once` (single bounce), or `continuous`
   (bounces until you bring Prowl forward).
 
 ## Settings (Settings → Notifications)
diff --git a/docs/components/repositories-and-worktrees.md b/docs/components/repositories-and-worktrees.md
index 34f4f7a8..3831453c 100644
--- a/docs/components/repositories-and-worktrees.md
+++ b/docs/components/repositories-and-worktrees.md
@@ -107,8 +107,9 @@ The **main worktree cannot be archived.**
 Deleting removes the worktree directory (and optionally its branch).
 
 - **Right-click** the row → "Delete Worktree", or **`⌘⇧⌫`**.
-- A confirmation dialog offers **"Delete the local branch (`git branch -d`)"**.
-  Default behavior comes from `deleteBranchOnDeleteWorktree`.
+- A confirmation dialog offers an **"Also delete local branch"** toggle (its
+  tooltip notes `git branch -d`). Default behavior comes from
+  `deleteBranchOnDeleteWorktree`.
 - Prowl removes the worktree (relocating + `git worktree prune` if needed). If
   branch deletion is rejected because the branch isn't merged, it offers a
   **force delete** (`git branch -D`).
@@ -123,15 +124,19 @@ it from Prowl (closing its open terminals); it does **not** delete files on disk
 
 ## Opening a worktree in another app
 
-`⌘O` opens the worktree (Finder by default). Right-click → submenu, or per-repo
-default (`openActionID`) / global default (`defaultEditorID`), pick from any
-installed app Prowl detects: Finder, Terminal, `$EDITOR`, VS Code (+ Insiders),
-Cursor, Zed, Windsurf, Xcode, JetBrains IDEs, GitHub Desktop / Fork / GitKraken /
-Sourcetree / Sublime Merge / SmartGit / GitUp, and terminals (Alacritty, Ghostty,
-Kitty, Warp, WezTerm). If the chosen app isn't installed, Prowl shows an alert.
-
-Other per-row context-menu items: **Copy Path**, **Reveal in Finder**,
-**Repo Settings**.
+`⌘O` opens the worktree with the auto-detected default app — your first installed
+editor (Cursor → Zed → VS Code → Windsurf → …), falling through to Xcode and then
+**Finder only when no preferred app is found**. Use the **Open** dropdown in the
+worktree's detail toolbar to pick a different app, or set a per-repo default
+(`openActionID`) / global default (`defaultEditorID`). Prowl detects: Finder,
+Terminal, `$EDITOR`, VS Code (+ Insiders), VSCodium, Cursor, Zed, Windsurf,
+Antigravity, Xcode, Android Studio, JetBrains IDEs, GitHub Desktop / Fork /
+GitKraken / Sourcetree / Sublime Merge / SmartGit / GitUp, and terminals
+(Alacritty, Ghostty, Kitty, Warp, WezTerm). If the chosen app isn't installed,
+Prowl shows an alert.
+
+Other per-row context-menu items: **Copy Path**, **Reveal in Finder**. (Repo
+Settings lives on the repository **header** menu, not the worktree row.)
 
 ## Repository appearance (icon & color)
 
diff --git a/docs/components/settings.md b/docs/components/settings.md
index cb307dbb..abeb6d17 100644
--- a/docs/components/settings.md
+++ b/docs/components/settings.md
@@ -16,12 +16,12 @@ window is a sidebar of tabs plus a detail pane.
 
 | Tab | Controls |
 |-----|----------|
-| **General** | Appearance (system/light/dark), default app for opening worktrees, confirm-before-quit, default view mode, window chrome tint, toolbar buttons (Run / Open-in-editor), dim unfocused splits, restore layout on launch. |
+| **General** | Appearance (system/light/dark), default app for opening worktrees, confirm-before-quit, default view mode, window chrome tint, toolbar buttons (Run / Open-in-editor), dim unfocused splits, Active Agents panel auto-show & tab titles. |
 | **Notifications** | In-app alerts, sound, macOS system notifications, move-notified-to-top, command-finished notification + threshold, Dock badge & bounce. → [notifications](notifications.md) |
 | **Shortcuts** | Remap app keyboard shortcuts; view defaults; resolve conflicts. → [keyboard-shortcuts](../reference/keyboard-shortcuts.md) |
 | **Worktree** | Worktree creation/deletion defaults: prompt on create, fetch before create, base directory, copy ignored/untracked files, delete-branch-on-delete, merged-worktree action, archived auto-delete period. |
 | **Updates** | Update channel (Stable/Tip), auto-check toggle, "Check for Updates Now". → [updates](updates.md) |
-| **Advanced** | Analytics, crash reports, and the **Install Command Line Tool** (`prowl` CLI) action. |
+| **Advanced** | Analytics, crash reports, restore terminal layout on launch (experimental) + clear saved layout, and the **Install Command Line Tool** (`prowl` CLI) action. |
 | **GitHub** | Enable GitHub integration (uses the `gh` CLI). → [github-pull-requests](github-pull-requests.md) |
 | **Repositories / Repo Settings** | Per-repository: setup/archive/run scripts, **Custom Commands**, default base ref & directory, copy-files overrides, open-with app, custom title, icon & color, PR merge strategy, line-diff & PR-state fetching. Reached from the sidebar context menu → "Repo Settings". → [custom-actions](custom-actions.md), [repositories-and-worktrees](repositories-and-worktrees.md) |
 
diff --git a/docs/components/shelf.md b/docs/components/shelf.md
index 5dc320e9..fec1d92a 100644
--- a/docs/components/shelf.md
+++ b/docs/components/shelf.md
@@ -24,7 +24,7 @@ otherwise it's a no-op.
 |--------|-----|
 | Flip to **next book** (worktree) | `⌘⌃→` |
 | Flip to **previous book** | `⌘⌃←` |
-| Jump to **book 1–9** | `⌃⌥1` … `⌃⌥9` |
+| Jump to **book 1–9** | `⌥⌃1` … `⌥⌃9` |
 | Cycle the open book's **tabs** | `⌘⌃↓` (next) / `⌘⌃↑` (previous) |
 | Select the open book's **tab 1–9** | `⌘1` … `⌘9` |
 
diff --git a/docs/components/terminal.md b/docs/components/terminal.md
index bb0accaa..8c920355 100644
--- a/docs/components/terminal.md
+++ b/docs/components/terminal.md
@@ -63,8 +63,8 @@ A tab's displayed title is, in order of precedence:
 2. the **live shell title** the running program emits (OSC 2), else
 3. an auto-generated default like `project 1`, `project 2`.
 
-Tabs created for a Run Script show the command and are **title-locked** until it
-finishes. Prowl also "learns" your shell's idle prompt so it doesn't mistake it
+The Run Script tab is labeled **RUN SCRIPT** and is **title-locked** for its
+lifetime. Prowl also "learns" your shell's idle prompt so it doesn't mistake it
 for a meaningful title.
 
 > **Titles are free-form and can lie or lag.** Any program can set any title.
diff --git a/docs/components/updates.md b/docs/components/updates.md
index 4af5fc01..6743c1f7 100644
--- a/docs/components/updates.md
+++ b/docs/components/updates.md
@@ -20,14 +20,17 @@ Prowl uses the **Sparkle** framework for auto-updates. Releases are notarized.
 
 ## Channels
 
-`updateChannel` selects the release track: **Stable** (default) or **Tip**. Choose
-in Settings → Updates. (Day-to-day, Stable is the published track.)
+`updateChannel` offers **Stable** (default) and **Tip** in Settings → Updates.
+Tip is **no longer published separately** and currently resolves to the same feed
+as Stable, so the two behave identically today.
 
 ## Settings
 
-- `updateChannel` — `stable` or `tip`.
+- `updateChannel` — `stable` or `tip` (Tip currently resolves to Stable).
 - `updatesAutomaticallyCheckForUpdates` — background checks (default on).
-- `updatesAutomaticallyDownloadUpdates` — auto-download in the background.
+- `updatesAutomaticallyDownloadUpdates` — present in settings but **not currently
+  wired** to Sparkle or exposed in the UI; the background-download preference is
+  chosen via Sparkle's own permission dialog.
 
 ## Install via Homebrew
 
diff --git a/docs/components/view-modes.md b/docs/components/view-modes.md
index f943a53d..e8b73816 100644
--- a/docs/components/view-modes.md
+++ b/docs/components/view-modes.md
@@ -18,9 +18,9 @@
 ## How to switch
 
 - **Canvas:** `⌘⌥↩` (`toggle_canvas`), the sidebar Canvas button, or Command
-  Palette → "Canvas".
+  Palette → "Toggle Canvas".
 - **Shelf:** `⌘⇧↩` (`toggle_shelf`), the sidebar Shelf button, or Command Palette →
-  "Shelf".
+  "Toggle Shelf".
 - **Back to Normal:** toggle the active mode off, or select a worktree in the
   sidebar.
 
@@ -29,7 +29,7 @@ Toggling Canvas or Shelf with **no open worktrees** does nothing.
 ## What's preserved across switches
 
 - Your running terminals, tabs, and panes are untouched.
-- Canvas remembers card positions/sizes/z-order for the session.
+- Canvas persists card positions/sizes/z-order across launches.
 - Entering Shelf keeps your current worktree open (or jumps to the first available
   one if you were on Canvas / archived / nothing).
 - Exiting Canvas returns you to the focused card's worktree, the worktree you had
diff --git a/docs/reference/keyboard-shortcuts.md b/docs/reference/keyboard-shortcuts.md
index fe3a433b..94afac63 100644
--- a/docs/reference/keyboard-shortcuts.md
+++ b/docs/reference/keyboard-shortcuts.md
@@ -41,8 +41,8 @@ Symbols: **⌘** Command · **⇧** Shift · **⌥** Option · **⌃** Control 
 |--------|---------|------------|------------|
 | Toggle Left Sidebar | ⌘⌃S | `toggle_left_sidebar` | yes |
 | Toggle Active Agents Panel | ⌘⌥P | `toggle_active_agents_panel` | yes |
-| Select Next Agent (in panel) | ⌃⌥↓ | `select_next_active_agent` | yes |
-| Select Previous Agent (in panel) | ⌃⌥↑ | `select_previous_active_agent` | yes |
+| Select Next Agent (in panel) | ⌥⌃↓ | `select_next_active_agent` | yes |
+| Select Previous Agent (in panel) | ⌥⌃↑ | `select_previous_active_agent` | yes |
 | Jump to Latest Unread | ⌘⌥U | `jump_to_latest_unread` | yes |
 | Show Diff | ⌘⇧Y | `show_diff` | yes |
 | Toggle Canvas | ⌘⌥↩ | `toggle_canvas` | yes |
@@ -54,7 +54,7 @@ Symbols: **⌘** Command · **⇧** Shift · **⌥** Option · **⌃** Control 
 |--------|---------|------------|------------|
 | Select Next Book | ⌘⌃→ | `select_next_shelf_book` | yes |
 | Select Previous Book | ⌘⌃← | `select_previous_shelf_book` | yes |
-| Select Book 1–9 | ⌃⌥1 … ⌃⌥9 | `select_shelf_book_1` … `_9` | yes |
+| Select Book 1–9 | ⌥⌃1 … ⌥⌃9 | `select_shelf_book_1` … `_9` | yes |
 
 > In Shelf view, **⌘⌃←/→ flips between books (worktrees)** and **⌘⌃↑/↓ cycles the
 > tabs of the open book** (those are the `select_previous/next_worktree` actions).
@@ -98,7 +98,7 @@ your Ghostty config (`~/.config/ghostty/config`). Typical defaults in parenthese
 | New Terminal (tab) | `new_tab` | ⌘T |
 | Close Terminal (pane/surface) | `close_surface` | ⌘W |
 | Close Terminal Tab | `close_tab` | ⌘⇧W |
-| New Split (vertical / horizontal) | `new_split:right` / `new_split:down` | (Ghostty default) |
+| New Split (vertical / horizontal) | `new_split:right` / `new_split:down` | (Ghostty default; config-only, not in the Terminal menu) |
 | Reset Font Size | `reset_font_size` | ⌘0 |
 | Increase Font Size | `increase_font_size:1` | ⌘+ |
 | Decrease Font Size | `decrease_font_size:1` | ⌘- |
@@ -128,7 +128,7 @@ hotkey — see [`components/custom-actions.md`](../components/custom-actions.md)
   `~/.prowl/settings.json` under `keybindingUserOverrides`.
 - **`quit_application`** is fixed (`systemFixedAppAction`) — it can't be remapped.
 - **Canvas/local actions** (`localInteraction`, e.g. Arrange/Organize/Expand,
-  Rename Branch) are remappable but only checked against each other for conflicts.
+  Rename Branch) are remappable and conflict-checked against all remappable actions.
 - **Custom Command** hotkeys are repo-scoped and take precedence over app
   shortcuts within the focused repository; conflicts are surfaced when recording.
 - **Terminal engine keys** are owned by Ghostty. Prowl automatically *unbinds*
@@ -140,7 +140,7 @@ hotkey — see [`components/custom-actions.md`](../components/custom-actions.md)
 
 - These are **defaults**. If a human says "my `⌘P` does X", trust them — they may
   have remapped it. The CLI is binding-independent; prefer it for automation.
-- When two rows look like they share keys (e.g. `⌃⌥↑/↓` for agent navigation vs
+- When two rows look like they share keys (e.g. `⌥⌃↑/↓` for agent navigation vs
   `⌘⌥↑/↓` for pane navigation), check the **modifiers carefully** — Control vs
   Command distinguishes them.
 - `select_previous/next_worktree` (⌘⌃↑/↓) is overloaded by design: in Shelf view
diff --git a/docs/reference/settings-fields.md b/docs/reference/settings-fields.md
index beae60b5..2186e9f3 100644
--- a/docs/reference/settings-fields.md
+++ b/docs/reference/settings-fields.md
@@ -58,7 +58,7 @@ JSON is pretty-printed with sorted keys. Legacy `~/.supacode` is migrated to
 | `windowTintCustomColor` | color | default | The custom tint color (when `windowTintMode = custom`). |
 | `showRunButtonInToolbar` | Bool | `true` | Show the Run Script button in the toolbar. |
 | `showDefaultEditorInToolbar` | Bool | `true` | Show the open-in-editor button in the toolbar. |
-| `dockBounceMode` | enum (`off`/`once`/`continuously`) | `off` | Dock bounce on notification. |
+| `dockBounceMode` | enum (`off`/`once`/`continuous`) | `off` | Dock bounce on notification. |
 | `showNotificationDotOnDock` | Bool | `false` | Numeric unread badge on the Dock icon. |
 | `shelfSpineTintFallback` | enum (`neutral`/`systemTint`) | `neutral` | Shelf spine color when a repo has no color. |
 | `shelfSpineTintFollowsRepositoryColor` | Bool | `true` | Tint shelf spines by repo color. |