diff --git a/README.md b/README.md
index 322645a..6a3a677 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,12 @@ Press `Enter` to take control of a task, then `Ctrl-\` to return to the dashboar
 
 ![`fleetcom` attach](docs/img/attach.png)
 
+### Custom groups
+
+Organize related tasks into named groups, even when they run in different directories.
+
+![`fleetcom` custom-group view](docs/img/groups.png)
+
 ### Resume agent sessions
 
 Start `claude`, `codex`, or `grok` normally. When you rerun the task or reload a saved session, `fleetcom` resumes the same conversation automatically.
@@ -53,48 +59,35 @@ For normal use, install the published crate from [crates.io](https://crates.io/c
 cargo install fleetcom
 ```
 
-### From source
-
-From the project root:
-
-- `cargo install --path .` to install `fleetcom` on `PATH`, or
-- `cargo build --release` and run `target/release/fleetcom`.
+[Source installation](docs/README.md#installation-from-source) covers builds from a repository clone.
 
 ## Usage
 
-| Invocation | Behavior |
-| -- | -- |
-| `fleetcom` | Connect to the daemon, autostarting it when necessary, and open the dashboard |
-| `fleetcom <session>` | Load a saved session, then open the dashboard |
-| `fleetcom --foreground` | Run in-process without a daemon; tasks stop when the client quits |
-| `fleetcom --scrollback <lines>` | Set per-task scrollback (default 2,000); read at supervisor start, so a running daemon keeps its value until `--kill` |
-| `fleetcom --kill` | Stop the daemon and every task it owns |
-| `fleetcom --help` / `--version` | Print usage or version information and exit |
+Connect to the daemon, autostarting it when necessary, and open the dashboard by invoking:
 
-The first ordinary invocation starts the daemon when necessary. `--daemon` is an internal mode.
+```sh
+fleetcom
+```
+
+The [invocation reference](docs/commands.md#invocation) covers sessions, foreground mode, scrollback, and daemon shutdown.
 
 ## Key Commands
 
 ### Dashboard
 
-| Key | Command |
-| -- | -- |
-| ↑ ↓ / `k` `j` | move the selection |
-| `Enter` | attach to the selected task |
-| `Space` | peek at the selected task |
-| `n` | new command in the invocation directory |
-| `@` | new command in a directory you pick (with completion) |
-| `q` | disconnect; leave the daemon and tasks running |
-| `Q` | quit; kill the tasks and stop the daemon |
+The dashboard shows two short key hints; `?` opens an expanded key reference:
+
+```text
+  ❯ n run · @ dir · / find · s sort
+  ↑↓ select · enter attach · space peek · ? controls
+```
 
 ### Attached
 
-| Key | Command |
-| -- | -- |
-| `Ctrl-\` | background the task and return to the dashboard |
-| anything else | forwarded to the task's PTY |
+- `Ctrl-\` backgrounds the task and returns to the dashboard.
+- Other supported input is forwarded to the task's PTY.
 
-[`docs/commands.md`](docs/commands.md) covers every key and launch flag, including the routing mechanics.
+[`docs/commands.md`](docs/commands.md#dashboard) covers every key and launch flag, including the routing mechanics.
 
 ## How it works
 
diff --git a/docs/README.md b/docs/README.md
index eace472..8f3abe1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -62,11 +62,11 @@ Run `fleetcom`. The first invocation starts the daemon and opens an empty dashbo
 ```text
   fleetcom   0 running · 0 idle · 0 done      by state · dir · custom
 
-  ❯ n run · @ dir · / find · s sort · w save · o load
-  ↑↓ select · enter attach · space peek · m tag · g group · R rename · r rerun · X kill · q detach · Q quit
+  ❯ n run · @ dir · / find · s sort
+  ↑↓ select · enter attach · space peek · ? controls
 ```
 
-Press `n`, enter a command, and press `Enter`. The command runs in its own PTY and appears under Running. Repeat the process for a second command:
+The hint rows cover common dashboard actions; `?` opens an expanded key reference. Press `n`, enter a command, and press `Enter`. The command runs in its own PTY and appears under Running. Repeat the process for a second command:
 
 ```text
   fleetcom   2 running · 0 idle · 0 done      by state · dir · custom
@@ -75,8 +75,8 @@ Press `n`, enter a command, and press `Enter`. The command runs in its own PTY a
   ✻  cargo watch -x test      test result: ok. 42 passed         9s
   ✻  npm run dev              VITE v5.0  ready in 312 ms         4s
 
-  ❯ n run · @ dir · / find · s sort · w save · o load
-  ↑↓ select · enter attach · space peek · m tag · g group · R rename · r rerun · X kill · q detach · Q quit
+  ❯ n run · @ dir · / find · s sort
+  ↑↓ select · enter attach · space peek · ? controls
 ```
 
 Each row is `glyph · tag · command · latest output · age`. The age counts from the task's last meaningful edge: launch while running, last output once idle, exit once completed. `Space` peeks: a read-only box of the selected task's live screen, without leaving the dashboard:
diff --git a/docs/commands.md b/docs/commands.md
index 29df21e..cb101f7 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -29,15 +29,19 @@
 | `/` | Jump the selection to a task by name, command, or group (opens the [find palette](#the--find-palette)) |
 | `s` | Cycle grouping: by state / by directory / by custom group |
 | `m` | Tag the selected task "in use" (toggles) |
+| `M` | Select the next tagged task in dashboard order, wrapping at the end |
 | `g` | Assign the selected task to a group (opens the group picker) |
 | `R` | Rename the selected task: a display name shown in place of the command |
 | `r` | Rerun a finished task; supported agent tasks use the captured resume command |
 | `X` | Kill a running task (`TERM`, then `KILL` after 2 s), or remove a finished one |
 | `w` | Save the current tasks as a session |
 | `o` | Load a saved session or a recovery snapshot (opens the [session picker](#the-o-session-picker)) |
-| `q` (or `Ctrl-C`) | Disconnect; leave the daemon and tasks running |
+| `?` | Open the [controls overlay](#the--controls-overlay) |
+| `q` (or `Ctrl-C`) | Disconnect from the daemon; under `--foreground`, quit and stop the tasks |
 | `Q` | Quit; kill the tasks and stop the daemon |
 
+![`fleetcom` controls overlay](img/controls.png)
+
 ### Status glyphs
 
 | Glyph | Meaning |
@@ -128,6 +132,8 @@ Groups belong to task state: an assignment survives client detach and rerun (`r`
 
 `m` toggles the "in use" tag and marks the task with `◆`. In state mode, tagged tasks form the In use section at the top. In custom mode, a tag moves the task to the top of its existing group rather than creating a global section. Within a dir or custom section, tasks sort as tagged, live, then completed; each class then sorts by directory and spawn order. Idle state does not affect row order in these modes, so a quiet task keeps its position and shows `∙`. State mode instead moves quiet tasks from Running to Idle.
 
+`M` cycles the selection through tagged tasks in dashboard order. It wraps after the last tagged task. With no tagged tasks, the selection does not move; with one, the selection moves to that task and stays there.
+
 In custom mode only, a new command inherits the selected task's group, through both `n` and the `@` picker. The spawn prompt shows the destination as `❯ dir ▸ group ▸ command`, each segment present only when it applies: the dir segment for a non-default directory, the group segment when a group will be inherited. State- and dir-mode spawns start unassigned.
 
 #### Renaming
@@ -142,11 +148,15 @@ The daemon removes control characters, trims surrounding whitespace, and limits
 
 `@` opens a bottom panel containing a path field and its matching directories. `Enter` depends on the selected row type:
 
-- Current directory: run the command in that directory (`Enter`).
-- Recent directories: ones you've launched in before; `Enter` runs there, `Tab`/`→` browses into them.
-- Subdirectories of the current path: `Enter` or `Tab`/`→` descends into one.
+- Resolved path: run the command in that directory (`Enter`). Row 0 is always this row, so the list is never empty.
+- Current task directories: `Enter` runs there; `Tab`/`→` browses into them. These rows precede subdirectories.
+- Subdirectories of the resolved path: `Enter` or `Tab`/`→` descends into one.
+
+Typing filters both lists under different rules. A subdirectory matches the fragment as a case-insensitive prefix. A current task directory matches a case-insensitive substring of its final path component: `log` finds `~/Documents/Code/Rust/Logria`, while `crab` finds both `crabapple` and `crabstep`. Parent components do not participate, so `doc` does not match every directory under `~/Documents/`.
 
-Typing filters the rows; `Backspace` deletes one character and the matches re-filter; `↑`/`↓` move the highlight; `Esc` cancels. Completion updates on each input, permitting navigation and launch without leaving the dashboard. `←`/`→` move the caret within the typed path (`→` descends only when the caret is at the end), and `Ctrl-A`/`Ctrl-E` (or `Home`/`End`) jump to either end; the same caret keys work in every `fleetcom` text field.
+Once the field contains `/`, current task directory rows are omitted; the picker shows the resolved path and its matching subdirectories. Without `/`, a current task directory that is also a matching subdirectory appears once, with the current task row behavior.
+
+`Backspace` deletes one character and the matches re-filter; `↑`/`↓` move the highlight; `Esc` cancels. Completion updates on each input, permitting navigation and launch without leaving the dashboard. `←`/`→` move the caret within the typed path (`→` descends only when the caret is at the end), and `Ctrl-A`/`Ctrl-E` (or `Home`/`End`) jump to either end; the same caret keys work in every `fleetcom` text field.
 
 ## The `/` find palette
 
@@ -178,6 +188,16 @@ The daemon normalizes every group name received from the picker or a [session](s
 
 A recovery row reads `<age> ago · <tasks> task(s) · <label>`: the file's age, its command count, and its stored label (normally `autosaved <timestamp>`). `Enter` loads the highlighted snapshot; the status line confirms the load and suggests saving it. Press `w` to save the recovered fleet as a named session.
 
+## The `?` controls overlay
+
+The dashboard's two hint rows cover common actions: `↑↓ select · enter attach · space peek · ? controls` and `❯ n run · @ dir · / find · s sort`. `?` opens an expanded reference for dashboard actions and the attached-mode background chord.
+
+The overlay groups bindings by purpose in a centered box. It does not scroll. `?`, `Esc`, or `q` returns to the dashboard. Other keys do nothing in the overlay; `Ctrl-C` still disconnects.
+
+`?` is Shift-`/`. `fleetcom` accepts both event forms for this binding: `?`, or `/` with Shift. An unmodified `/` still opens the [find palette](#the--find-palette).
+
+The box uses a two-column layout. When height is limited, group headers drop first; if the entries still do not fit, the overlay clips the tail and reports `+N more` on the bottom border. Narrow terminals clip each row to the box width.
+
 ## Peek
 
 A centered box over the dashboard showing the selected task's live screen (the last screenful). `↑`/`↓` (or `k`/`j`) switch which task you're peeking at; `Enter` attaches to it; `r` reruns it if it has finished; `Space`, `Esc`, or `q` closes.
@@ -186,7 +206,7 @@ The footer's `preview:` segment names the source of the row's dashboard preview:
 
 ## Attached
 
-The task owns the terminal, and its status bar reads `[attached] <command>    Ctrl-\ background`, or `[attached] <name> · <command>` for a named task. `Ctrl-\` returns to the dashboard; every other key (control chords included) goes to the child.
+The task owns the terminal, and its status bar reads `[attached] <command>    Ctrl-\ background`, or `[attached] <name> · <command>` for a named task. `Ctrl-\` returns to the dashboard. Other supported input normally goes to the child; [scrollback](#scrollback) reserves its navigation keys.
 
 ## Connection loss
 
diff --git a/docs/img/README.md b/docs/img/README.md
new file mode 100644
index 0000000..3d911a3
--- /dev/null
+++ b/docs/img/README.md
@@ -0,0 +1,47 @@
+# README screenshots
+
+Each `.ansi` file is one dashboard frame written by the real renderer over a
+fabricated fleet, so a terminal `cat`-ing it paints exactly what a live run
+paints.
+
+| Frame | Shows |
+| -- | -- |
+| `home.ansi` | grouped by directory, the list outgrowing its region |
+| `quickpeek.ansi` | grouped by state, peek open over a finished run |
+| `groups.ansi` | grouped by custom group: one section spans five directories, and one directory feeds two sections |
+| `controls.ansi` | the `?` overlay over the dir-grouped dashboard |
+
+All four render the same 21 tasks. `attach.png` is captured from a live session,
+because it needs a live attach.
+
+The fixture is `write_readme_screenshot_fixtures` in `src/app_tests.rs`. Edit the
+fleet there (task names, previews, ages, tags, selection), then regenerate:
+
+```sh
+cargo test -- --ignored write_readme_screenshot_fixtures
+```
+
+Every duration in the fixture is constant. With the same `$HOME`, two runs write
+identical bytes; section labels abbreviate that path to `~`.
+
+## Capturing
+
+```sh
+clear; cat docs/img/home.ansi;      read -rsk 1; printf '\033[?25h'
+clear; cat docs/img/quickpeek.ansi; read -rsk 1; printf '\033[?25h'
+clear; cat docs/img/groups.ansi;    read -rsk 1; printf '\033[?25h'
+clear; cat docs/img/controls.ansi;  read -rsk 1; printf '\033[?25h'
+```
+
+`read` blocks until a keypress, so the screenshot is taken with nothing emitted
+after the frame; the trailing `printf` restores the cursor, which the frame
+hides. The flags are zsh's; bash spells the same thing `read -rs -n1`, and
+`read -r` waits for Enter in both.
+
+Each frame parks the cursor on the terminal's last row, outside centered
+overlays. This matters for `render_peek`, which otherwise leaves the cursor
+inside the peek box while `read` waits.
+
+The terminal must be at least 107×30, the size the frames are painted at. `clear`
+first: a frame only paints its own rows, so a taller window would show stale
+scrollback beneath it.
diff --git a/docs/img/attach.png b/docs/img/attach.png
index 80c2d00..c535084 100644
Binary files a/docs/img/attach.png and b/docs/img/attach.png differ
diff --git a/docs/img/controls.ansi b/docs/img/controls.ansi
new file mode 100644
index 0000000..8bb42bb
--- /dev/null
+++ b/docs/img/controls.ansi
@@ -0,0 +1 @@
+]0;fleetcom[?2026h[?25l  fleetcom   12 running · 2 idle · 7 done      by state · dir · custom · 4/21                                                                                                                                           ~/Documents/Code/Rust/fleetcom                                                                             ✻ ◆Dashboard Refine           ✻ Scope small fixes for dashboard and CLI                                2m  ✻ ◆Summary Refine             Inferring… · thinking with high effort                                   5m  ✻  Grok Language              Grok 4.5 (xhigh) · Responding…                                          12m  ✻  Codex Language             gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 387K used · 9.… 18m  ✻  Codex Review               gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 221K used · 4.… 24m  ✓  cargo test                 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered… 12s  ✗  cargo clippy               error: could not compile `fleetcom` (lib test) due to 1 previous error   3m  ~                                                                                                          ✻  claude agents              2 awaiting input · claude agents                                         1h  ✻  Zellij                     Desktop ¦ Utility                                                        2h  ∙  python                     >>>                                                                     41m  ✓  brew update && brew upgra… Already up-to-date.                                                     13m  ~/Documents/Code/Apple/turret                                                                              ✻  Game Infra Review          Turret Game Codebase Organization and Ex… - grok                         8m  ✻  Missile Nerf               gpt-5.6-sol high · turret · main · 129K used · 1.31M in · 10.1K out     33m  ✻  EMP Nerf                   gpt-5.6-sol high · turret · main · 161K used · 1.64M in · 10.4K out     35m  ~/Documents/Code/Rust/crabapple                                                                            ✓  cargo test                 all doctests ran in 0.39s; merged doctests compilation took 0.38s       17m  ~/Documents/Code/Rust/crabstep                                                                             ✓  cargo test                 all doctests ran in 0.83s; merged doctests compilation took 0.81s       21m  ~/Documents/Code/Rust/imessage-exporter                                                                    ✻  claude                     ✻ Review GitHub issue 780                                                6m  ✓  cargo test                 all doctests ran in 1.99s; merged doctests compilation took 1.95s       19m  ~/Documents/Code/Rust/Logria                                                                               ✻  cargo watch -x test        [Running 'cargo test'] test result: ok. 223 passed; 0 failed            45s  ❯ n run · @ dir · / find · s sort                                                                          ↑↓ select · enter attach · space peek · ? controls                                                       [?25l┌─ controls ────────────────────────────────────────────┐│  Navigate                                             ││    ↑↓ / kj   move selection  /         find a task    ││    Tab ⇧Tab  jump section    M         next tagged    ││  Act                                                  ││    enter     attach          r         rerun finished ││    space     peek            X         kill or remove ││  Organize                                             ││    m         tag in use      R         rename         ││    g         assign group    s         cycle grouping ││  Create                                               ││    n         run here        @         run in a dir   ││  Session                                              ││    w         save session    o         load session   ││  Leave                                                ││    q         detach          Q         quit and kill  ││  Attached                                             ││    Ctrl-\    background                               │└───────────────────────────────────────────────────────┘ ? esc close [?2026l
\ No newline at end of file
diff --git a/docs/img/controls.png b/docs/img/controls.png
new file mode 100644
index 0000000..2fb35af
Binary files /dev/null and b/docs/img/controls.png differ
diff --git a/docs/img/groups.ansi b/docs/img/groups.ansi
new file mode 100644
index 0000000..916a928
--- /dev/null
+++ b/docs/img/groups.ansi
@@ -0,0 +1 @@
+]0;fleetcom[?2026h[?25l  fleetcom   12 running · 2 idle · 7 done      by state · dir · custom                                                                                                                                                  dashboard                                                                                                  ✻ ◆Dashboard Refine           ✻ Scope small fixes for dashboard and CLI                                2m  ✻ ◆Summary Refine             Inferring… · thinking with high effort                                   5m  ✻  Grok Language              Grok 4.5 (xhigh) · Responding…                                          12m  ✻  Codex Language             gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 387K used · 9.… 18m  ✻  Codex Review               gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 221K used · 4.… 24m  desktop                                                                                                    ✻  claude agents              2 awaiting input · claude agents                                         1h  ✻  Zellij                     Desktop ¦ Utility                                                        2h  ✓  brew update && brew upgra… Already up-to-date.                                                     13m  tests                                                                                                      ✻  cargo watch -x test        [Running 'cargo test'] test result: ok. 223 passed; 0 failed            45s  ∙  cargo doc --open           Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.41s     26m  ✓  cargo test                 all doctests ran in 0.39s; merged doctests compilation took 0.38s       17m  ✓  cargo test                 all doctests ran in 0.83s; merged doctests compilation took 0.81s       21m  ✓  cargo test                 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered… 12s  ✗  cargo clippy               error: could not compile `fleetcom` (lib test) due to 1 previous error   3m  ✓  cargo test                 all doctests ran in 1.99s; merged doctests compilation took 1.95s       19m  ✓  cargo test                 test result: ok. 223 passed; 0 failed; 0 ignored; 0 measured; 0 filter… 31m  turret                                                                                                     ✻  Game Infra Review          Turret Game Codebase Organization and Ex… - grok                         8m  ✻  Missile Nerf               gpt-5.6-sol high · turret · main · 129K used · 1.31M in · 10.1K out     33m  ✻  EMP Nerf                   gpt-5.6-sol high · turret · main · 161K used · 1.64M in · 10.4K out     35m  Unassigned                                                                                                 ∙  python                     >>>                                                                     41m  ✻  claude                     ✻ Review GitHub issue 780                                                6m  ❯ n run · @ dir · / find · s sort                                                                          ↑↓ select · enter attach · space peek · ? controls                                                       [?25l[?2026l
\ No newline at end of file
diff --git a/docs/img/groups.png b/docs/img/groups.png
new file mode 100644
index 0000000..df335bd
Binary files /dev/null and b/docs/img/groups.png differ
diff --git a/docs/img/home.ansi b/docs/img/home.ansi
new file mode 100644
index 0000000..747bed7
--- /dev/null
+++ b/docs/img/home.ansi
@@ -0,0 +1 @@
+]0;fleetcom[?2026h[?25l  fleetcom   12 running · 2 idle · 7 done      by state · dir · custom · 4/21                                                                                                                                           ~/Documents/Code/Rust/fleetcom                                                                             ✻ ◆Dashboard Refine           ✻ Scope small fixes for dashboard and CLI                                2m  ✻ ◆Summary Refine             Inferring… · thinking with high effort                                   5m  ✻  Grok Language              Grok 4.5 (xhigh) · Responding…                                          12m  ✻  Codex Language             gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 387K used · 9.… 18m  ✻  Codex Review               gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 221K used · 4.… 24m  ✓  cargo test                 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered… 12s  ✗  cargo clippy               error: could not compile `fleetcom` (lib test) due to 1 previous error   3m  ~                                                                                                          ✻  claude agents              2 awaiting input · claude agents                                         1h  ✻  Zellij                     Desktop ¦ Utility                                                        2h  ∙  python                     >>>                                                                     41m  ✓  brew update && brew upgra… Already up-to-date.                                                     13m  ~/Documents/Code/Apple/turret                                                                              ✻  Game Infra Review          Turret Game Codebase Organization and Ex… - grok                         8m  ✻  Missile Nerf               gpt-5.6-sol high · turret · main · 129K used · 1.31M in · 10.1K out     33m  ✻  EMP Nerf                   gpt-5.6-sol high · turret · main · 161K used · 1.64M in · 10.4K out     35m  ~/Documents/Code/Rust/crabapple                                                                            ✓  cargo test                 all doctests ran in 0.39s; merged doctests compilation took 0.38s       17m  ~/Documents/Code/Rust/crabstep                                                                             ✓  cargo test                 all doctests ran in 0.83s; merged doctests compilation took 0.81s       21m  ~/Documents/Code/Rust/imessage-exporter                                                                    ✻  claude                     ✻ Review GitHub issue 780                                                6m  ✓  cargo test                 all doctests ran in 1.99s; merged doctests compilation took 1.95s       19m  ~/Documents/Code/Rust/Logria                                                                               ✻  cargo watch -x test        [Running 'cargo test'] test result: ok. 223 passed; 0 failed            45s  ❯ n run · @ dir · / find · s sort                                                                          ↑↓ select · enter attach · space peek · ? controls                                                       [?25l[?2026l
\ No newline at end of file
diff --git a/docs/img/home.png b/docs/img/home.png
index d0963ea..3bc1166 100644
Binary files a/docs/img/home.png and b/docs/img/home.png differ
diff --git a/docs/img/quickpeek.ansi b/docs/img/quickpeek.ansi
new file mode 100644
index 0000000..1b0f137
--- /dev/null
+++ b/docs/img/quickpeek.ansi
@@ -0,0 +1 @@
+]0;fleetcom[?2026h[?25l  fleetcom   1 running · 13 idle · 7 done      by state · dir · custom                                                                                                                                                  In use                                                                                                     ∙ ◆Dashboard Refine           ✻ Scope small fixes for dashboard and CLI                               32s  ∙ ◆Summary Refine             ✻ Review fleetcom preview design document                               13s  Running                                                                                                    ✻  Zellij                     Desktop ¦ Utility                                                       20m  Idle                                                                                                       ∙  claude agents              2 awaiting input · claude agents                                         1m  ∙  python                     >>>                                                                     20m  ∙  Game Infra Review          Turret Game Codebase Organization and Ex… - grok                         1m  ∙  Missile Nerf               gpt-5.6-sol high · turret · main · 129K used · 1.31M in · 10.1K out      1m  ∙  EMP Nerf                   gpt-5.6-sol high · turret · main · 161K used · 1.64M in · 10.4K out      1m  ∙  Grok Language              Grok 4.5 (xhigh) · Responding…                                           1m  ∙  Codex Language             gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 387K used · 9.5… 1m  ∙  Codex Review               gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 221K used · 4.4… 1m  ∙  claude                     ✻ Review GitHub issue 780                                                1m  ∙  cargo watch -x test        [Running 'cargo test'] test result: ok. 223 passed; 0 failed             2m  ∙  cargo doc --open           Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.41s     28m  Completed                                                                                                  ✓  brew update && brew upgra… Already up-to-date.                                                     15m  ✓  cargo test                 all doctests ran in 0.39s; merged doctests compilation took 0.38s       19m  ✓  cargo test                 all doctests ran in 0.83s; merged doctests compilation took 0.81s       20m  ✓  cargo test                 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered… 20m  ✗  cargo clippy               error: could not compile `fleetcom` (lib test) due to 1 previous error  21m  ✓  cargo test                 all doctests ran in 1.99s; merged doctests compilation took 1.95s       20m  ✓  cargo test                 test result: ok. 223 passed; 0 failed; 0 ignored; 0 measured; 0 filter… 20m                                                                                                             ❯ n run · @ dir · / find · s sort                                                                          ↑↓ select · enter attach · space peek · ? controls                                                       [?25l┌─ cargo test ─────────────────────────────────────────────────────────────────┐│test util::sanitizers::tests::test_length_clean ... ok                        ││test util::sanitizers::tests::test_row_length_clean ... ok                    ││test util::sanitizers::tests::test_length_dirty ... ok                        ││test util::sanitizers::tests::test_length_wide_chars ... ok                   ││test util::sanitizers::tests::test_sanitize_filename_clean ... ok             ││test util::sanitizers::tests::test_row_length_dirty ... ok                    ││test util::sanitizers::tests::test_row_length_wide_chars ... ok               ││test util::sanitizers::tests::test_sanitize_filename_control_chars ... ok     ││test util::sanitizers::tests::test_sanitize_filename_trim ... ok              ││test util::sanitizers::tests::test_sanitize_filename_invalid_chars ... ok     ││test util::sanitizers::tests::test_sanitize_filename_long ... ok              ││                                                                              ││test result: ok. 223 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out;…││                                                                              │└──────────────────────────────────────────────────────────────────────────────┘ space/esc close · enter attach · preview: floor (frozen) [?2026l
\ No newline at end of file
diff --git a/docs/img/quickpeek.png b/docs/img/quickpeek.png
index 35e2d83..2b5917c 100644
Binary files a/docs/img/quickpeek.png and b/docs/img/quickpeek.png differ
diff --git a/src/app.rs b/src/app.rs
index 2599b6e..5ccba03 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -96,6 +96,8 @@ pub enum Mode {
     LoadSession,
     /// Overlay preview of the selected task.
     Peek,
+    /// Read-only key-reference overlay.
+    Controls,
     /// Full-screen, keystrokes forwarded to the focused task's PTY.
     Attached,
     /// The daemon connection dropped; a banner offers reconnect or quit.
@@ -139,9 +141,9 @@ pub enum SessionPage {
 /// What Enter does with a picker row.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DirKind {
-    /// The current directory (row 0): Enter runs the command here.
+    /// The resolved path (row 0): Enter runs the command there.
     Use,
-    /// A recently-used dir: Enter runs the command there (one-press reuse).
+    /// A current task's directory: Enter runs there; Tab descends into it.
     Jump,
     /// A subdirectory: Enter and Tab descend into it.
     Into,
@@ -664,6 +666,25 @@ impl App {
         self.select_section_wrap(false);
     }
 
+    /// Select the next tagged task in display order, wrapping as needed.
+    /// Start at the first tag when nothing is selected; preserve the selection
+    /// when no task is tagged.
+    fn select_next_tagged(&mut self) {
+        let order = self.display_order();
+        if order.is_empty() {
+            return;
+        }
+        // Start one past the selection so a tagged selection advances; without
+        // a selection, start at the top of the list.
+        let start = self.selected_pos(&order).map_or(0, |pos| pos + 1);
+        let next = (0..order.len())
+            .map(|off| order[(start + off) % order.len()])
+            .find(|&i| self.views[i].tagged);
+        if let Some(i) = next {
+            self.selected_id = Some(self.views[i].id);
+        }
+    }
+
     /// Send the desired watch state when its target or attachment mode changes.
     fn set_watch(&mut self, want: Option<(u64, bool)>) {
         if want != self.watched {
@@ -886,9 +907,9 @@ impl App {
 
     // --- `@` directory picker -------------------------------------------------
 
-    /// Recompute picker rows: the current directory first (row 0, "run here"),
-    /// then, before you've typed anything, the in-use dirs for one-press
-    /// reuse, then the subdirectories of the current dir matching the fragment.
+    /// Rebuild directory-picker rows with the resolved path first. When the
+    /// input has no slash, matching current-task directories follow. Matching
+    /// subdirectories of the resolved path come last.
     fn refresh_dir_candidates(&mut self) {
         let (base_str, partial) = split_input(&self.dir_input);
         let base = self.resolve(base_str);
@@ -899,20 +920,35 @@ impl App {
             kind: DirKind::Use,
         }];
 
-        if self.dir_input.is_empty() {
+        // Include current-task directories only when the input contains no `/`.
+        // `split_input` leaves `base_str` empty exactly in that case.
+        if base_str.is_empty() {
+            let needle = partial.to_lowercase();
             for p in self.in_use_dirs() {
-                if p != base {
-                    cands.push(DirCand {
-                        label: path::abbreviate(&p),
-                        path: p,
-                        kind: DirKind::Jump,
-                    });
+                let label = path::abbreviate(&p);
+                // Match the final component so shared parent components do not
+                // match every sibling directory.
+                if p == base || !label_leaf(&label).to_lowercase().contains(&needle) {
+                    continue;
                 }
+                cands.push(DirCand {
+                    label,
+                    path: p,
+                    kind: DirKind::Jump,
+                });
             }
         }
 
         for name in list_dirs(&base, partial) {
             let path = base.join(&name);
+            // A current-task directory that is also a subdirectory already has
+            // a row: Enter runs there, and Tab descends.
+            if cands
+                .iter()
+                .any(|c| c.kind == DirKind::Jump && c.path == path)
+            {
+                continue;
+            }
             cands.push(DirCand {
                 label: name,
                 path,
@@ -920,8 +956,8 @@ impl App {
             });
         }
 
-        // Nothing typed → keep the current dir selected (row 0). Filtering →
-        // jump to the first match so Tab/Enter drills straight in.
+        // An empty trailing fragment selects the resolved path. Otherwise,
+        // select the first matching row when one exists.
         self.dir_sel = if partial.is_empty() || cands.len() < 2 {
             0
         } else {
@@ -930,8 +966,7 @@ impl App {
         self.dir_candidates = cands;
     }
 
-    /// Distinct working directories of current tasks, most-recently-spawned
-    /// first: the "recent" quick-pick list.
+    /// Distinct task working directories, ordered by the newest task in each.
     fn in_use_dirs(&self) -> Vec<PathBuf> {
         let mut order: Vec<usize> = (0..self.views.len()).collect();
         order.sort_by_key(|&i| std::cmp::Reverse(self.views[i].id));
@@ -1122,6 +1157,7 @@ impl App {
             Mode::Rename => self.on_key_rename(k),
             Mode::LoadSession => self.on_key_loadsession(k),
             Mode::Peek => self.on_key_peek(k),
+            Mode::Controls => self.on_key_controls(k),
             Mode::Attached => self.on_key_attached(out, k)?,
             Mode::Disconnected => self.on_key_disconnected(k),
         }
@@ -1139,6 +1175,10 @@ impl App {
     }
 
     fn on_key_dashboard(&mut self, k: KeyEvent) {
+        if is_controls_key(k) {
+            self.mode = Mode::Controls;
+            return;
+        }
         match k.code {
             // `q` detaches (daemon + tasks live on); `Q` kills all and stops it.
             KeyCode::Char('q') => {
@@ -1159,12 +1199,14 @@ impl App {
                 }
             }
             KeyCode::Enter => self.attach(),
+            // `m` toggles a tag; `M` cycles through tagged tasks.
             KeyCode::Char('m') => {
                 if let Some(i) = self.selected_task() {
                     let (id, tagged) = (self.views[i].id, self.views[i].tagged);
                     self.transport.send(Command::Tag { id, on: !tagged });
                 }
             }
+            KeyCode::Char('M') => self.select_next_tagged(),
             KeyCode::Char('g') => self.open_group_picker(),
             KeyCode::Char('/') => self.open_find_palette(),
             // Uppercase R renames; lowercase r reruns.
@@ -1290,7 +1332,8 @@ impl App {
     fn on_key_pickdir(&mut self, k: KeyEvent) {
         // Tab descends; Right descends at the end and moves the caret elsewhere.
         if k.code == KeyCode::Tab || (k.code == KeyCode::Right && self.dir_input.at_end()) {
-            // Descend into the highlighted dir; a no-op on the current-dir row.
+            // Descend into the highlighted directory; the resolved-path row is
+            // a no-op.
             if let Some(c) = self.dir_candidates.get(self.dir_sel)
                 && c.kind != DirKind::Use
             {
@@ -1311,9 +1354,9 @@ impl App {
                 if let Some(c) = self.dir_candidates.get(self.dir_sel) {
                     let path = c.path.clone();
                     match c.kind {
-                        // Current dir or a recent dir: run the command there.
+                        // Resolved path or current-task directory: run there.
                         DirKind::Use | DirKind::Jump => self.confirm_dir(path),
-                        // Subdirectory: descend and select it (one keypress).
+                        // Subdirectory: descend and select its resolved-path row.
                         DirKind::Into => self.enter_dir(path),
                     }
                 }
@@ -1400,6 +1443,13 @@ impl App {
         }
     }
 
+    /// Close the controls overlay on `?`, Esc, or `q`.
+    fn on_key_controls(&mut self, k: KeyEvent) {
+        if is_controls_key(k) || matches!(k.code, KeyCode::Esc | KeyCode::Char('q')) {
+            self.mode = Mode::Dashboard;
+        }
+    }
+
     fn on_key_attached(&mut self, out: &mut Stdout, k: KeyEvent) -> io::Result<()> {
         // Ctrl-\ backgrounds the task; crossterm may report it as Ctrl-4.
         let detach = k.modifiers.contains(KeyModifiers::CONTROL)
@@ -1771,6 +1821,16 @@ fn key_event_to_key(ev: KeyEvent) -> Option<(Key, Mods)> {
     Some((code, mods))
 }
 
+/// Recognize either Shift-`/` event: `?`, or `/` with the Shift modifier.
+/// An unmodified `/` remains available to the find palette.
+fn is_controls_key(k: KeyEvent) -> bool {
+    match k.code {
+        KeyCode::Char('?') => true,
+        KeyCode::Char('/') => k.modifiers.contains(KeyModifiers::SHIFT),
+        _ => false,
+    }
+}
+
 /// Apply prompt editing keys. Returns `Some(true)` for text changes,
 /// `Some(false)` for caret motion or ignored Ctrl chords, and `None` for
 /// unsupported keys. Ctrl-A and Ctrl-E move to the start and end.
@@ -1836,8 +1896,8 @@ fn paste_into(buf: &mut EditBuffer, s: &str) {
     }
 }
 
-/// Split a typed path into (directory-so-far, trailing fragment). The fragment
-/// is prefix-matched against candidates; the directory is what we list.
+/// Split a typed path into its directory prefix and trailing search fragment.
+/// Candidate types apply their own matching rules to the fragment.
 fn split_input(input: &str) -> (&str, &str) {
     match input.rfind('/') {
         Some(pos) => (&input[..=pos], &input[pos + 1..]),
@@ -1845,6 +1905,16 @@ fn split_input(input: &str) -> (&str, &str) {
     }
 }
 
+/// Return the final path component of an abbreviated display label.
+/// Trailing slashes are ignored. Labels without a final component, such as
+/// `/`, are returned unchanged.
+fn label_leaf(label: &str) -> &str {
+    Path::new(label)
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or(label)
+}
+
 /// Subdirectories of `base` whose names start with `partial`, ignoring case.
 /// Results use the same case-insensitive collation. Hidden entries appear only
 /// when `partial` starts with `.`.
diff --git a/src/app_tests.rs b/src/app_tests.rs
index 1fa8058..bc084ce 100644
--- a/src/app_tests.rs
+++ b/src/app_tests.rs
@@ -1,5 +1,6 @@
 use super::*;
 use crate::{
+    protocol::{Preview, PreviewSource},
     supervisor::Supervisor,
     testutil::{temp, wait_until},
     transport::LocalTransport,
@@ -1019,6 +1020,204 @@ fn list_dirs_collates_case_insensitively() {
     let _ = std::fs::remove_dir_all(&base);
 }
 
+/// Build an `@`-picker fixture with `fleetcom` as the invocation directory,
+/// three sibling task directories, and a `fleetcom/docs` subdirectory.
+fn recents_fixture(tag: &str) -> (App, PathBuf) {
+    let root = temp(tag);
+    let rust = root.join("Documents/Code/Rust");
+    for name in ["fleetcom", "Logria", "crabapple", "crabstep"] {
+        std::fs::create_dir_all(rust.join(name)).unwrap();
+    }
+    std::fs::create_dir_all(rust.join("fleetcom/docs")).unwrap();
+
+    let mut app = App::new_local(30, 100);
+    app.invocation_dir = rust.join("fleetcom");
+    // Spawn oldest first so `in_use_dirs` returns Logria, crabapple, crabstep.
+    for name in ["crabstep", "crabapple", "Logria"] {
+        app.spawn_in("sleep 5", rust.join(name));
+    }
+    app.pump();
+    (app, root)
+}
+
+/// Open the `@` picker and type `fragment` one key at a time.
+fn type_pickdir(app: &mut App, fragment: &str) {
+    app.on_key_dashboard(key(KeyCode::Char('@')));
+    for c in fragment.chars() {
+        app.on_key_pickdir(key(KeyCode::Char(c)));
+    }
+}
+
+/// Current-task directory paths in picker order.
+fn jump_paths(app: &App) -> Vec<PathBuf> {
+    app.dir_candidates
+        .iter()
+        .filter(|c| c.kind == DirKind::Jump)
+        .map(|c| c.path.clone())
+        .collect()
+}
+
+/// Final-component matching includes task directories outside the invocation
+/// directory.
+#[test]
+fn pickdir_fragment_surfaces_a_sibling_recent() {
+    let (mut app, root) = recents_fixture("pickdir_recent_sibling");
+    let rust = root.join("Documents/Code/Rust");
+
+    type_pickdir(&mut app, "log");
+
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(app.dir_candidates[0].path, app.invocation_dir);
+    assert_eq!(
+        jump_paths(&app),
+        vec![rust.join("Logria")],
+        "`log` matches the Logria leaf"
+    );
+    assert!(
+        !rust.join("Logria").starts_with(&app.invocation_dir),
+        "the match must be a sibling, not a subdirectory"
+    );
+    assert_eq!(app.dir_sel, 1, "the recent is preselected for Enter");
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// Current-task directories use case-insensitive substring matching.
+#[test]
+fn pickdir_recent_match_folds_case() {
+    let (mut app, root) = recents_fixture("pickdir_recent_case");
+    let rust = root.join("Documents/Code/Rust");
+
+    type_pickdir(&mut app, "LOG");
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(
+        jump_paths(&app),
+        vec![rust.join("Logria")],
+        "an uppercase fragment matches a capitalized name"
+    );
+
+    // Mid-component: `ria` sits at the end of `Logria`, past any prefix.
+    app.on_key_pickdir(key(KeyCode::Esc));
+    type_pickdir(&mut app, "ria");
+    assert_eq!(jump_paths(&app), vec![rust.join("Logria")]);
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// A fragment includes every matching current-task directory.
+#[test]
+fn pickdir_fragment_surfaces_every_matching_recent() {
+    let (mut app, root) = recents_fixture("pickdir_recent_many");
+    let rust = root.join("Documents/Code/Rust");
+
+    type_pickdir(&mut app, "crab");
+
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(
+        jump_paths(&app),
+        vec![rust.join("crabapple"), rust.join("crabstep")],
+        "recents keep their newest-first order"
+    );
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// Parent components do not match current-task directories.
+#[test]
+fn pickdir_middle_component_matches_no_recent() {
+    let (mut app, root) = recents_fixture("pickdir_recent_middle");
+
+    type_pickdir(&mut app, "doc");
+
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert!(
+        jump_paths(&app).is_empty(),
+        "a shared parent must not flood the panel"
+    );
+    assert_eq!(app.dir_candidates.len(), 2);
+    assert_eq!(app.dir_candidates[1].kind, DirKind::Into);
+    assert_eq!(app.dir_candidates[1].label, "docs");
+    assert_eq!(app.dir_sel, 1, "the subdirectory keeps row 1");
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// A `/` omits current-task directories from the picker.
+#[test]
+fn pickdir_slash_suppresses_recents() {
+    let (mut app, root) = recents_fixture("pickdir_recent_slash");
+    let rust = root.join("Documents/Code/Rust");
+
+    // `..` resolves to the parent containing every fixture task directory.
+    type_pickdir(&mut app, "../");
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(app.dir_candidates[0].path, rust);
+    assert!(jump_paths(&app).is_empty(), "a `/` drops the recents");
+    assert!(
+        app.dir_candidates[1..]
+            .iter()
+            .all(|c| c.kind == DirKind::Into)
+    );
+    assert_eq!(
+        app.dir_candidates
+            .iter()
+            .filter(|c| c.path == rust.join("Logria"))
+            .count(),
+        1,
+        "Logria is listed once, as a subdirectory"
+    );
+
+    // Filtering the resolved path still omits current-task directory rows.
+    for c in "log".chars() {
+        app.on_key_pickdir(key(KeyCode::Char(c)));
+    }
+    assert!(jump_paths(&app).is_empty());
+    assert_eq!(app.dir_candidates[1].path, rust.join("Logria"));
+    assert_eq!(app.dir_candidates[1].kind, DirKind::Into);
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// An empty field lists every current-task directory.
+#[test]
+fn pickdir_empty_input_lists_every_recent() {
+    let (mut app, root) = recents_fixture("pickdir_recent_empty");
+    let rust = root.join("Documents/Code/Rust");
+
+    type_pickdir(&mut app, "");
+
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(app.dir_candidates[0].path, app.invocation_dir);
+    assert_eq!(
+        jump_paths(&app),
+        vec![
+            rust.join("Logria"),
+            rust.join("crabapple"),
+            rust.join("crabstep"),
+        ]
+    );
+    assert_eq!(app.dir_sel, 0, "an empty field keeps the current dir");
+    let _ = std::fs::remove_dir_all(&root);
+}
+
+/// A current-task directory that is also a subdirectory appears once, using
+/// current-task row behavior.
+#[test]
+fn pickdir_dedupes_a_recent_that_is_also_a_subdirectory() {
+    let (mut app, root) = recents_fixture("pickdir_recent_dedupe");
+    let docs = root.join("Documents/Code/Rust/fleetcom/docs");
+    app.spawn_in("sleep 5", docs.clone());
+    app.pump();
+
+    type_pickdir(&mut app, "doc");
+
+    assert_eq!(app.dir_candidates[0].kind, DirKind::Use);
+    assert_eq!(
+        app.dir_candidates.iter().filter(|c| c.path == docs).count(),
+        1,
+        "one row per directory"
+    );
+    assert_eq!(app.dir_candidates.len(), 2);
+    assert_eq!(app.dir_candidates[1].kind, DirKind::Jump);
+    assert_eq!(app.dir_candidates[1].path, docs);
+    let _ = std::fs::remove_dir_all(&root);
+}
+
 /// Focus is by id, so it points at the same task even after the list shifts
 /// (a lower-id task is removed) and reports gone once it's removed.
 #[test]
@@ -1262,6 +1461,188 @@ fn section_nav_defaults_without_selection() {
     assert_eq!(empty.selected_id, None);
 }
 
+// --- `M` cycle tagged tasks -------------------------------------------
+
+/// Build four state-grouped tasks with ids 2 and 4 tagged.
+fn app_with_tagged_pair() -> App {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    for _ in 0..4 {
+        app.spawn_in("sleep 5", inv.clone());
+    }
+    app.pump();
+    app.transport.send(Command::Tag { id: 2, on: true });
+    app.transport.send(Command::Tag { id: 4, on: true });
+    app.pump();
+    assert_eq!(
+        app.section_ids(),
+        vec![
+            ("In use".to_string(), vec![2, 4]),
+            ("Running".to_string(), vec![1, 3]),
+        ],
+        "tagging reorders: the cycle runs 2 -> 4, then wraps"
+    );
+    app
+}
+
+/// Build two custom groups with the first task in each group tagged.
+fn app_with_tags_split_across_groups() -> App {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 1
+    app.spawn_grouped("sleep 5", inv.clone(), "alpha"); // id 2
+    app.spawn_grouped("sleep 5", inv.clone(), "beta"); // id 3
+    app.spawn_grouped("sleep 5", inv, "beta"); // id 4
+    app.pump();
+    app.group_mode = GroupMode::Custom;
+    app.transport.send(Command::Tag { id: 1, on: true });
+    app.transport.send(Command::Tag { id: 3, on: true });
+    app.pump();
+    assert_eq!(
+        app.section_ids(),
+        vec![
+            ("alpha".to_string(), vec![1, 2]),
+            ("beta".to_string(), vec![3, 4]),
+        ],
+        "tags head their own groups: display order is 1, 2, 3, 4"
+    );
+    app
+}
+
+/// `M` advances through the tagged tasks in display order and wraps.
+#[test]
+fn cycle_tagged_advances_and_wraps() {
+    let mut app = app_with_tagged_pair();
+    app.resolve_selection();
+    assert_eq!(app.selected_id, Some(2), "first row is the first tag");
+
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(4), "forward to the second tag");
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(
+        app.selected_id,
+        Some(2),
+        "past the last tag wraps to the first"
+    );
+}
+
+/// `M` skips untagged rows between tagged tasks.
+#[test]
+fn cycle_tagged_skips_untagged_tasks() {
+    let mut app = app_with_tags_split_across_groups();
+    app.selected_id = Some(1);
+
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(3), "untagged id 2 is skipped");
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(
+        app.selected_id,
+        Some(1),
+        "untagged id 4 is skipped on the wrap"
+    );
+}
+
+/// `M` leaves the dashboard unchanged when no task is tagged.
+#[test]
+fn cycle_tagged_is_noop_without_tags() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("sleep 5", inv); // id 2
+    app.pump();
+    app.resolve_selection();
+    assert_eq!(app.selected_id, Some(1));
+
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(1), "no tags: the selection stands");
+    assert!(app.mode == Mode::Dashboard, "no tags: the mode stands");
+    assert!(app.notice().is_none() && app.status.is_none());
+}
+
+/// From an untagged row, `M` selects the next tagged task.
+#[test]
+fn cycle_tagged_from_untagged_selection_jumps_forward() {
+    let mut app = app_with_tags_split_across_groups();
+
+    app.selected_id = Some(2);
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(3), "next tag after the untagged row");
+
+    // A selection after the last tagged task wraps to the first.
+    app.selected_id = Some(4);
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(1), "no tag below: wrap to the first");
+}
+
+/// With one tagged task selected, `M` leaves it selected.
+#[test]
+fn cycle_tagged_with_one_tag_holds_the_selection() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv.clone()); // id 1
+    app.spawn_in("sleep 5", inv.clone()); // id 2
+    app.spawn_in("sleep 5", inv); // id 3
+    app.pump();
+    app.transport.send(Command::Tag { id: 2, on: true });
+    app.pump();
+    app.resolve_selection();
+    assert_eq!(app.selected_id, Some(2), "the only tag heads the list");
+
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(2), "selection is held, not cleared");
+}
+
+/// Without a selection, `M` selects the first tagged task.
+#[test]
+fn cycle_tagged_without_selection_takes_the_first_tag() {
+    let mut app = app_with_tagged_pair();
+    app.selected_id = None;
+    app.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(app.selected_id, Some(2), "no selection: first tag in order");
+
+    let mut empty = App::new_local(30, 100);
+    empty.on_key_dashboard(key(KeyCode::Char('M')));
+    assert_eq!(empty.selected_id, None, "empty fleet: nothing to select");
+}
+
+/// `M` changes only the dashboard selection.
+#[test]
+fn cycle_tagged_mutates_no_task_state() {
+    let mut app = app_with_tags_split_across_groups();
+    app.resolve_selection();
+    let before: Vec<_> = app
+        .views
+        .iter()
+        .map(|v| (v.id, v.tagged, v.group.clone(), v.lifecycle))
+        .collect();
+
+    for _ in 0..5 {
+        app.on_key_dashboard(key(KeyCode::Char('M')));
+    }
+    // Apply queued transport commands before comparing task state.
+    app.pump();
+
+    let after: Vec<_> = app
+        .views
+        .iter()
+        .map(|v| (v.id, v.tagged, v.group.clone(), v.lifecycle))
+        .collect();
+    assert_eq!(before, after, "tags, groups, and lifecycles are untouched");
+    assert_eq!(
+        app.section_ids(),
+        vec![
+            ("alpha".to_string(), vec![1, 2]),
+            ("beta".to_string(), vec![3, 4]),
+        ],
+        "order is unchanged, so nothing reordered the list"
+    );
+    assert!(app.notice().is_none() && app.status.is_none());
+    assert!(app.mode == Mode::Dashboard);
+    // Five presses over two tags: an odd count lands on the second.
+    assert_eq!(app.selected_id, Some(3));
+}
+
 /// Supported crossterm keys and modifiers map to their wire representation.
 #[test]
 fn key_event_maps_to_semantic_key() {
@@ -1588,6 +1969,10 @@ fn ctrl(code: KeyCode) -> KeyEvent {
     KeyEvent::new(code, KeyModifiers::CONTROL)
 }
 
+fn shift(code: KeyCode) -> KeyEvent {
+    KeyEvent::new(code, KeyModifiers::SHIFT)
+}
+
 /// `g` opens the picker only when a task is selected, pinning the target
 /// to that task's id.
 #[test]
@@ -2055,6 +2440,145 @@ fn find_paste_filters_the_candidates() {
     assert_eq!(find_ids(&app), vec![2]);
 }
 
+// --- `?` controls overlay -----------------------------------------------
+
+/// Paint one frame of the current mode and return it as text.
+fn painted(app: &mut App) -> String {
+    app.last_frame.clear(); // identical frames are skipped
+    let mut out = Vec::new();
+    crate::ui::render(&mut out, app).unwrap();
+    String::from_utf8_lossy(&out).into_owned()
+}
+
+/// `?` opens the overlay; `?`, `Esc`, and `q` each close it.
+#[test]
+fn controls_overlay_opens_on_question_and_closes_on_peeks_key_set() {
+    let mut app = App::new_local(30, 100);
+    for close in [KeyCode::Char('?'), KeyCode::Esc, KeyCode::Char('q')] {
+        app.on_key_dashboard(key(KeyCode::Char('?')));
+        assert!(app.mode == Mode::Controls, "? must open the overlay");
+        app.on_key_controls(key(close));
+        assert!(app.mode == Mode::Dashboard, "{close:?} must close it");
+    }
+}
+
+/// Both accepted Shift-`/` event forms, `?` and `/` with Shift, open and close
+/// the overlay.
+#[test]
+fn controls_overlay_accepts_both_spellings_of_the_chord() {
+    let mut app = App::new_local(30, 100);
+    for chord in [key(KeyCode::Char('?')), shift(KeyCode::Char('/'))] {
+        app.on_key_dashboard(chord);
+        assert!(
+            app.mode == Mode::Controls,
+            "{chord:?} must open the overlay"
+        );
+        app.on_key_controls(chord);
+        assert!(app.mode == Mode::Dashboard, "{chord:?} must close it");
+    }
+}
+
+/// Shift distinguishes the overlay from find: unmodified `/` still opens the
+/// find palette.
+#[test]
+fn plain_slash_still_opens_the_find_palette() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv);
+    app.pump();
+    app.on_key_dashboard(key(KeyCode::Char('/')));
+    assert!(app.mode == Mode::Find);
+}
+
+/// Dashboard bindings are inert while the controls overlay is open.
+#[test]
+fn controls_overlay_ignores_dashboard_keys() {
+    let mut app = App::new_local(30, 100);
+    let inv = app.invocation_dir.clone();
+    app.spawn_in("sleep 5", inv);
+    app.pump();
+    app.resolve_selection();
+
+    app.on_key_dashboard(key(KeyCode::Char('?')));
+    app.on_key_controls(key(KeyCode::Char('m')));
+    app.on_key_controls(key(KeyCode::Char('n')));
+    app.pump();
+    assert!(app.mode == Mode::Controls, "neither key closes the overlay");
+    assert!(!app.views[0].tagged, "m must not reach the task");
+    assert!(app.input.as_str().is_empty(), "n must not open the prompt");
+
+    app.on_key_controls(key(KeyCode::Esc));
+    app.on_key_dashboard(key(KeyCode::Char('m')));
+    app.pump();
+    assert!(app.views[0].tagged);
+}
+
+/// A 30-row terminal shows the group headings.
+#[test]
+fn controls_overlay_groups_its_entries_when_the_terminal_is_tall() {
+    let mut app = App::new_local(30, 100);
+    app.on_key_dashboard(key(KeyCode::Char('?')));
+    let f = painted(&mut app);
+    assert!(f.contains("┌─ controls "), "{f:?}");
+    assert!(f.contains("Navigate"), "{f:?}");
+    assert!(f.contains("w         save session"), "{f:?}");
+    assert!(f.contains("? esc close"), "{f:?}");
+}
+
+/// At 20 rows, the flat layout preserves every entry by dropping headings.
+#[test]
+fn controls_overlay_drops_the_group_headers_before_any_entry() {
+    let mut app = App::new_local(20, 100);
+    app.on_key_dashboard(key(KeyCode::Char('?')));
+    let f = painted(&mut app);
+    assert!(!f.contains("Navigate"), "the headers go first: {f:?}");
+    assert!(
+        f.contains("w         save session"),
+        "no entry is hidden: {f:?}"
+    );
+}
+
+/// At 12 rows, the overlay clips seven entries and reports the count.
+#[test]
+fn controls_overlay_reports_clipped_entries_on_its_border() {
+    let mut app = App::new_local(12, 100);
+    app.on_key_dashboard(key(KeyCode::Char('?')));
+    let f = painted(&mut app);
+    assert!(f.contains("? esc close · +7 more"), "{f:?}");
+    assert!(!f.contains("save session"), "the tail is clipped: {f:?}");
+}
+
+/// Foreground has no daemon to leave running, so `q` is labeled quit.
+#[test]
+fn controls_overlay_names_the_foreground_exit_a_quit() {
+    let mut app = App::new_local(30, 100);
+    app.on_key_dashboard(key(KeyCode::Char('?')));
+    let f = painted(&mut app);
+    assert!(!app.daemon_backed);
+    assert!(f.contains("q         quit "), "{f:?}");
+    assert!(!f.contains("detach"), "{f:?}");
+
+    app.daemon_backed = true;
+    let f = painted(&mut app);
+    assert!(f.contains("q         detach"), "{f:?}");
+}
+
+/// Dashboard hint rows show common actions and link to the controls overlay.
+#[test]
+fn dashboard_hints_defer_the_long_tail_to_the_overlay() {
+    let mut app = App::new_local(30, 100);
+    let f = painted(&mut app);
+    assert!(f.contains("  ❯ n run · @ dir · / find · s sort"), "{f:?}");
+    assert!(
+        f.contains("  ↑↓ select · enter attach · space peek · ? controls"),
+        "{f:?}"
+    );
+    assert!(
+        !f.contains("w save"),
+        "the tail moved to the overlay: {f:?}"
+    );
+}
+
 // --- `R` rename prompt --------------------------------------------------
 
 /// The rename prompt captures the selected task ID and current name.
@@ -3330,3 +3854,652 @@ fn input_and_attached_echo_bypass_the_repaint_floor() {
     // Before the floor elapses, wait for its remaining duration.
     assert_eq!(wait_for_paint(false, Duration::ZERO), PAINT_MIN);
 }
+
+// --- README frame fixtures --------------------------------------------------
+//
+// The real renderer writes each fabricated fleet to `docs/img/*.ansi`. Printing
+// one of these files reproduces the corresponding dashboard frame.
+
+/// Fixture terminal size. The 30 rows fit every section plus one spare list
+/// row; 107 columns produce a 71-column preview cell and an 80-column peek box.
+const FIXTURE_ROWS: u16 = 30;
+const FIXTURE_COLS: u16 = 107;
+
+/// A client with no core behind it. The fixture assigns `views` and
+/// `focused_screen` directly, so no command is sent and no event arrives.
+struct NoTransport;
+
+impl Transport for NoTransport {
+    fn send(&mut self, _cmd: Command) {}
+
+    fn poll(&mut self) -> Vec<Event> {
+        Vec::new()
+    }
+
+    fn connected(&self) -> bool {
+        true
+    }
+
+    fn shutdown(&mut self, _intent: ExitIntent) {}
+}
+
+/// Fabricated seconds. Every fixture duration is a constant: a clock reading
+/// would change the bytes between runs. `const` so the `QUIET` table can hold
+/// them directly.
+const fn secs(n: u64) -> Duration {
+    Duration::from_secs(n)
+}
+
+/// Fabricated minutes.
+const fn mins(n: u64) -> Duration {
+    Duration::from_secs(n * 60)
+}
+
+/// Live summary-adapter preview, carrying the matcher id the peek footer names.
+fn anchor(text: &str, rule: &'static str) -> Preview {
+    Preview {
+        text: text.to_string(),
+        source: PreviewSource::Anchor,
+        rule: Some(rule),
+        frozen: false,
+    }
+}
+
+/// Live window-title preview.
+fn title(text: &str) -> Preview {
+    Preview {
+        text: text.to_string(),
+        source: PreviewSource::Title,
+        rule: None,
+        frozen: false,
+    }
+}
+
+/// Live last-row preview.
+fn floor(text: &str) -> Preview {
+    Preview {
+        text: text.to_string(),
+        source: PreviewSource::Floor,
+        rule: None,
+        frozen: false,
+    }
+}
+
+/// The last-row preview a finished task froze on.
+fn frozen(text: &str) -> Preview {
+    Preview {
+        text: text.to_string(),
+        source: PreviewSource::Floor,
+        rule: None,
+        frozen: true,
+    }
+}
+
+/// The fleet's working directories, keyed as they appear in the section labels.
+/// `dir_label` abbreviates `$HOME` to `~`, so these must be built from it.
+struct Dirs {
+    home: PathBuf,
+    fleetcom: PathBuf,
+    turret: PathBuf,
+    crabapple: PathBuf,
+    crabstep: PathBuf,
+    imessage: PathBuf,
+    logria: PathBuf,
+}
+
+impl Dirs {
+    fn new(home: &Path) -> Dirs {
+        let code = home.join("Documents/Code");
+        Dirs {
+            home: home.to_path_buf(),
+            fleetcom: code.join("Rust/fleetcom"),
+            turret: code.join("Apple/turret"),
+            crabapple: code.join("Rust/crabapple"),
+            crabstep: code.join("Rust/crabstep"),
+            imessage: code.join("Rust/imessage-exporter"),
+            logria: code.join("Rust/Logria"),
+        }
+    }
+}
+
+/// A dashboard client over `views`, with `~/Documents/Code/Rust/fleetcom` as
+/// the invocation directory so directory mode ranks that section first.
+/// Daemon-backed mode omits the foreground marker from generated frames.
+fn fixture_app(dirs: &Dirs, group_mode: GroupMode, views: Vec<TaskView>) -> App {
+    let mut app = App::assemble(FIXTURE_ROWS, FIXTURE_COLS, |_, _, _| Box::new(NoTransport));
+    app.daemon_backed = true;
+    app.invocation_label = app.dir_label(&dirs.fleetcom);
+    app.invocation_dir = dirs.fleetcom.clone();
+    app.spawn_cwd = dirs.fleetcom.clone();
+    app.group_mode = group_mode;
+    app.views = views;
+    app
+}
+
+/// The active frame's 21 tasks: 12 active, two idle, and seven finished.
+/// Task IDs encode launch order; `row_rank` moves tagged tasks ahead of their
+/// peers and finished tasks behind them within a section.
+fn live_fleet(dirs: &Dirs) -> Vec<TaskView> {
+    vec![
+        TaskView {
+            id: 1,
+            command: "claude".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: true,
+            group: Some("dashboard".to_string()),
+            name: Some("Dashboard Refine".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor(
+                "✻ Scope small fixes for dashboard and CLI",
+                "claude:action-row",
+            ),
+            started_ago: mins(2),
+            quiet_ago: Some(secs(3)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 2,
+            command: "claude".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: true,
+            group: Some("dashboard".to_string()),
+            name: Some("Summary Refine".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor("Inferring… · thinking with high effort", "claude:spinner"),
+            started_ago: mins(5),
+            quiet_ago: Some(secs(8)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 3,
+            command: "grok".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: false,
+            group: Some("dashboard".to_string()),
+            name: Some("Grok Language".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor("Grok 4.5 (xhigh) · Responding…", "grok:spinner"),
+            started_ago: mins(12),
+            quiet_ago: Some(secs(4)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 4,
+            command: "codex".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: false,
+            group: Some("dashboard".to_string()),
+            name: Some("Codex Language".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor(CODEX_LANGUAGE, "codex:working"),
+            started_ago: mins(18),
+            quiet_ago: Some(secs(2)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 5,
+            command: "codex".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: false,
+            group: Some("dashboard".to_string()),
+            name: Some("Codex Review".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor(CODEX_REVIEW, "codex:working"),
+            started_ago: mins(24),
+            quiet_ago: Some(secs(6)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 6,
+            command: "cargo test".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen(FLEETCOM_TESTS),
+            started_ago: mins(2),
+            quiet_ago: None,
+            finished_ago: Some(secs(12)),
+        },
+        TaskView {
+            id: 19,
+            command: "cargo clippy".to_string(),
+            cwd: dirs.fleetcom.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Failed,
+            parked: false,
+            preview: frozen(FLEETCOM_CLIPPY),
+            started_ago: mins(5),
+            quiet_ago: None,
+            finished_ago: Some(mins(3)),
+        },
+        TaskView {
+            id: 7,
+            command: "claude".to_string(),
+            cwd: dirs.home.clone(),
+            tagged: false,
+            group: Some("desktop".to_string()),
+            name: Some("claude agents".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: title("2 awaiting input · claude agents"),
+            started_ago: mins(63),
+            quiet_ago: Some(secs(9)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 8,
+            command: "zellij".to_string(),
+            cwd: dirs.home.clone(),
+            tagged: false,
+            group: Some("desktop".to_string()),
+            name: Some("Zellij".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: title("Desktop ¦ Utility"),
+            started_ago: mins(126),
+            quiet_ago: Some(secs(4)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 9,
+            command: "python".to_string(),
+            cwd: dirs.home.clone(),
+            tagged: false,
+            group: None,
+            name: None,
+            lifecycle: Lifecycle::Idle,
+            parked: true,
+            preview: floor(">>>"),
+            started_ago: mins(48),
+            quiet_ago: Some(mins(41)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 10,
+            command: "brew update && brew upgrade".to_string(),
+            cwd: dirs.home.clone(),
+            tagged: false,
+            group: Some("desktop".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen("Already up-to-date."),
+            started_ago: mins(14),
+            quiet_ago: None,
+            finished_ago: Some(mins(13)),
+        },
+        TaskView {
+            id: 11,
+            command: "grok".to_string(),
+            cwd: dirs.turret.clone(),
+            tagged: false,
+            group: Some("turret".to_string()),
+            name: Some("Game Infra Review".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: title("Turret Game Codebase Organization and Ex… - grok"),
+            started_ago: mins(8),
+            quiet_ago: Some(secs(5)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 12,
+            command: "codex".to_string(),
+            cwd: dirs.turret.clone(),
+            tagged: false,
+            group: Some("turret".to_string()),
+            name: Some("Missile Nerf".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor(MISSILE_NERF, "codex:working"),
+            started_ago: mins(33),
+            quiet_ago: Some(secs(7)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 13,
+            command: "codex".to_string(),
+            cwd: dirs.turret.clone(),
+            tagged: false,
+            group: Some("turret".to_string()),
+            name: Some("EMP Nerf".to_string()),
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor(EMP_NERF, "codex:working"),
+            started_ago: mins(35),
+            quiet_ago: Some(secs(3)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 14,
+            command: "cargo test".to_string(),
+            cwd: dirs.crabapple.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen(CRABAPPLE_TESTS),
+            started_ago: mins(18),
+            quiet_ago: None,
+            finished_ago: Some(mins(17)),
+        },
+        TaskView {
+            id: 15,
+            command: "cargo test".to_string(),
+            cwd: dirs.crabstep.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen(CRABSTEP_TESTS),
+            started_ago: mins(22),
+            quiet_ago: None,
+            finished_ago: Some(mins(21)),
+        },
+        TaskView {
+            id: 16,
+            command: "claude".to_string(),
+            cwd: dirs.imessage.clone(),
+            tagged: false,
+            group: None,
+            name: None,
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: anchor("✻ Review GitHub issue 780", "claude:action-row"),
+            started_ago: mins(6),
+            quiet_ago: Some(secs(2)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 17,
+            command: "cargo test".to_string(),
+            cwd: dirs.imessage.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen(IMESSAGE_TESTS),
+            started_ago: mins(20),
+            quiet_ago: None,
+            finished_ago: Some(mins(19)),
+        },
+        TaskView {
+            id: 18,
+            command: "cargo test".to_string(),
+            cwd: dirs.logria.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            preview: frozen(LOGRIA_TESTS),
+            started_ago: mins(32),
+            quiet_ago: None,
+            finished_ago: Some(mins(31)),
+        },
+        TaskView {
+            id: 20,
+            command: "cargo watch -x test".to_string(),
+            cwd: dirs.logria.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            preview: floor(LOGRIA_WATCH),
+            started_ago: secs(45),
+            quiet_ago: Some(secs(2)),
+            finished_ago: None,
+        },
+        TaskView {
+            id: 21,
+            command: "cargo doc --open".to_string(),
+            cwd: dirs.logria.clone(),
+            tagged: false,
+            group: Some("tests".to_string()),
+            name: None,
+            lifecycle: Lifecycle::Idle,
+            parked: true,
+            preview: floor(LOGRIA_DOC),
+            started_ago: mins(28),
+            quiet_ago: Some(mins(26)),
+            finished_ago: None,
+        },
+    ]
+}
+
+/// Per-task state for the quiet frame. Task identity remains in `live_fleet`;
+/// this table replaces lifecycle, age, and one preview.
+struct Quiet {
+    id: u64,
+    lifecycle: Lifecycle,
+    parked: bool,
+    started_ago: Duration,
+    quiet_ago: Option<Duration>,
+    finished_ago: Option<Duration>,
+    /// Replacement anchor preview as `(text, matcher id)`; `None` keeps the
+    /// live fleet's.
+    preview: Option<(&'static str, &'static str)>,
+}
+
+impl Quiet {
+    /// A live task quiet past `IDLE_AFTER`, timed from its last output.
+    const fn idle(id: u64, started: Duration, quiet: Duration) -> Quiet {
+        Quiet {
+            id,
+            lifecycle: Lifecycle::Idle,
+            parked: true,
+            started_ago: started,
+            quiet_ago: Some(quiet),
+            finished_ago: None,
+            preview: None,
+        }
+    }
+
+    /// A live task still inside `IDLE_AFTER`, timed from launch.
+    const fn active(id: u64, started: Duration, quiet: Duration) -> Quiet {
+        Quiet {
+            lifecycle: Lifecycle::Active,
+            parked: false,
+            ..Quiet::idle(id, started, quiet)
+        }
+    }
+
+    /// A task that exited cleanly, timed from the exit.
+    const fn done(id: u64, started: Duration, finished: Duration) -> Quiet {
+        Quiet {
+            lifecycle: Lifecycle::Ok,
+            parked: false,
+            quiet_ago: None,
+            finished_ago: Some(finished),
+            ..Quiet::idle(id, started, finished)
+        }
+    }
+
+    /// A task that exited non-zero, timed from the exit.
+    const fn failed(id: u64, started: Duration, finished: Duration) -> Quiet {
+        Quiet {
+            lifecycle: Lifecycle::Failed,
+            ..Quiet::done(id, started, finished)
+        }
+    }
+
+    /// Swap in a different status line.
+    const fn saying(mut self, text: &'static str, rule: &'static str) -> Quiet {
+        self.preview = Some((text, rule));
+        self
+    }
+}
+
+/// Quiet-frame overrides, one per task. The rendered ages include `32s` and
+/// `13s` for the tagged pair, `1m` for most idle agents, and `15m`–`21m` for
+/// finished tasks.
+const QUIET: [Quiet; 21] = [
+    Quiet::idle(1, mins(22), secs(32)),
+    Quiet::idle(2, mins(21), secs(13)).saying(SUMMARY_QUIET, "claude:action-row"),
+    Quiet::idle(3, mins(21), mins(1)),
+    Quiet::idle(4, mins(21), mins(1)),
+    Quiet::idle(5, mins(21), mins(1)),
+    Quiet::done(6, mins(21), mins(20)),
+    Quiet::idle(7, mins(21), mins(1)),
+    // Keep Zellij active so the Running section remains non-empty.
+    Quiet::active(8, mins(20), secs(4)),
+    Quiet::idle(9, mins(22), mins(20)),
+    Quiet::done(10, mins(16), mins(15)),
+    Quiet::idle(11, mins(21), mins(1)),
+    Quiet::idle(12, mins(21), mins(1)),
+    Quiet::idle(13, mins(21), mins(1)),
+    Quiet::done(14, mins(20), mins(19)),
+    Quiet::done(15, mins(21), mins(20)),
+    Quiet::idle(16, mins(21), mins(1)),
+    Quiet::done(17, mins(21), mins(20)),
+    Quiet::done(18, mins(21), mins(20)),
+    Quiet::failed(19, mins(24), mins(21)),
+    Quiet::idle(20, mins(4), mins(2)),
+    Quiet::idle(21, mins(30), mins(28)),
+];
+
+/// The quiet frame's 21 tasks: one active, 13 idle, and seven finished.
+/// `parked` follows `lifecycle` because the core derives both from the same
+/// `IDLE_AFTER` window.
+fn quiet_fleet(dirs: &Dirs) -> Vec<TaskView> {
+    let mut views = live_fleet(dirs);
+    assert_eq!(
+        views.len(),
+        QUIET.len(),
+        "every task needs a peek-frame override"
+    );
+    for v in &mut views {
+        let Some(q) = QUIET.iter().find(|q| q.id == v.id) else {
+            panic!("no peek-frame override for task {}", v.id);
+        };
+        v.lifecycle = q.lifecycle;
+        v.parked = q.parked;
+        v.started_ago = q.started_ago;
+        v.quiet_ago = q.quiet_ago;
+        v.finished_ago = q.finished_ago;
+        if let Some((text, rule)) = q.preview {
+            v.preview = anchor(text, rule);
+        }
+    }
+    views
+}
+
+// Preview texts long enough that the row cell truncates them. They are stored
+// whole: the `…` in the painted frame is the renderer's, not the fixture's.
+const CODEX_LANGUAGE: &str =
+    "gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 387K used · 9.53M in · 61.2K out";
+const CODEX_REVIEW: &str =
+    "gpt-5.6-sol high · fleetcom · feat/cs/interface-fixes · 221K used · 4.41M in · 38.7K out";
+const MISSILE_NERF: &str = "gpt-5.6-sol high · turret · main · 129K used · 1.31M in · 10.1K out";
+const EMP_NERF: &str = "gpt-5.6-sol high · turret · main · 161K used · 1.64M in · 10.4K out";
+const FLEETCOM_TESTS: &str =
+    "test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.03s";
+const LOGRIA_TESTS: &str = "test result: ok. 223 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.38s";
+const CRABAPPLE_TESTS: &str = "all doctests ran in 0.39s; merged doctests compilation took 0.38s";
+const CRABSTEP_TESTS: &str = "all doctests ran in 0.83s; merged doctests compilation took 0.81s";
+const IMESSAGE_TESTS: &str = "all doctests ran in 1.99s; merged doctests compilation took 1.95s";
+const FLEETCOM_CLIPPY: &str =
+    "error: could not compile `fleetcom` (lib test) due to 1 previous error";
+const LOGRIA_WATCH: &str = "[Running 'cargo test'] test result: ok. 223 passed; 0 failed";
+const LOGRIA_DOC: &str = "Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.41s";
+/// Preview used only by the quiet frame.
+const SUMMARY_QUIET: &str = "✻ Review fleetcom preview design document";
+
+/// The peeked task's screen: the tail of a `cargo test` run. `render_peek`
+/// shows the last `inner_h` lines, so these are already the visible ones.
+fn cargo_test_screen(id: u64) -> ScreenView {
+    let lines = [
+        "test util::sanitizers::tests::test_length_clean ... ok",
+        "test util::sanitizers::tests::test_row_length_clean ... ok",
+        "test util::sanitizers::tests::test_length_dirty ... ok",
+        "test util::sanitizers::tests::test_length_wide_chars ... ok",
+        "test util::sanitizers::tests::test_sanitize_filename_clean ... ok",
+        "test util::sanitizers::tests::test_row_length_dirty ... ok",
+        "test util::sanitizers::tests::test_row_length_wide_chars ... ok",
+        "test util::sanitizers::tests::test_sanitize_filename_control_chars ... ok",
+        "test util::sanitizers::tests::test_sanitize_filename_trim ... ok",
+        "test util::sanitizers::tests::test_sanitize_filename_invalid_chars ... ok",
+        "test util::sanitizers::tests::test_sanitize_filename_long ... ok",
+        "",
+        LOGRIA_TESTS,
+        "",
+    ];
+    ScreenView {
+        id,
+        lines: lines.iter().map(|s| s.to_string()).collect(),
+        // Peek reads `lines` only; the attached path never runs here.
+        formatted: Vec::new(),
+        cursor: (0, 0),
+        hide_cursor: true,
+        wants_mouse: false,
+        alt_screen: false,
+        alt_scroll: false,
+        scrollback: 0,
+    }
+}
+
+/// Paint `app` once and return the frame bytes.
+fn frame(app: &mut App) -> Vec<u8> {
+    // OSC 0 keeps the captured window title independent of the printing shell.
+    let mut out = b"\x1b]0;fleetcom\x07".to_vec();
+    let painted = out.len();
+    crate::ui::render(&mut out, app).expect("a fixture frame always paints");
+    assert!(out.len() > painted, "a fresh App must emit its first frame");
+    // Park the cursor on the terminal's final row, outside centered overlays.
+    out.extend_from_slice(format!("\x1b[{};1H", app.rows).as_bytes());
+    out
+}
+
+/// Rewrite the four `docs/img/*.ansi` dashboard frames. This test is ignored
+/// because it writes repository fixtures.
+///
+/// Fixed durations and ordered inputs make the output deterministic for a
+/// given `$HOME`; `dir_label` abbreviates that path to `~` in section labels.
+#[test]
+#[ignore = "writes docs/img/*.ansi; run by hand to refresh the README screenshots"]
+fn write_readme_screenshot_fixtures() {
+    let home = std::env::var("HOME").expect("HOME must be set to abbreviate the section labels");
+    assert!(!home.is_empty(), "HOME must not be empty");
+    let dirs = Dirs::new(Path::new(&home));
+    let out_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("docs/img");
+
+    // Grouped by directory, selection on a live codex task.
+    let mut app = fixture_app(&dirs, GroupMode::Dir, live_fleet(&dirs));
+    app.selected_id = Some(4);
+    std::fs::write(out_dir.join("home.ansi"), frame(&mut app)).unwrap();
+
+    // State grouping with peek open over the first finished test. Directory
+    // ordering places id 14 first in Completed and beside the peek box.
+    let mut app = fixture_app(&dirs, GroupMode::State, quiet_fleet(&dirs));
+    app.mode = Mode::Peek;
+    app.selected_id = Some(14);
+    // Seed the watched screen directly because NoTransport emits no frames.
+    app.focused_screen = Some(cargo_test_screen(14));
+    std::fs::write(out_dir.join("quickpeek.ansi"), frame(&mut app)).unwrap();
+
+    // Custom grouping puts five directories in `tests` and splits fleetcom's
+    // directory between two sections.
+    let mut app = fixture_app(&dirs, GroupMode::Custom, live_fleet(&dirs));
+    app.selected_id = Some(4);
+    std::fs::write(out_dir.join("groups.ansi"), frame(&mut app)).unwrap();
+
+    // The `?` overlay over the same dir-grouped dashboard.
+    let mut app = fixture_app(&dirs, GroupMode::Dir, live_fleet(&dirs));
+    app.selected_id = Some(4);
+    app.mode = Mode::Controls;
+    std::fs::write(out_dir.join("controls.ansi"), frame(&mut app)).unwrap();
+}
diff --git a/src/ui.rs b/src/ui.rs
index 9424fb0..68c5fc7 100644
--- a/src/ui.rs
+++ b/src/ui.rs
@@ -47,6 +47,10 @@ pub fn render(out: &mut impl Write, app: &mut App) -> io::Result<bool> {
             render_dashboard(&mut buf, app)?;
             render_find(&mut buf, app)?;
         }
+        Mode::Controls => {
+            render_dashboard(&mut buf, app)?;
+            render_controls(&mut buf, app)?;
+        }
         Mode::LoadSession => {
             render_dashboard(&mut buf, app)?;
             render_session_picker(&mut buf, app)?;
@@ -202,30 +206,15 @@ fn render_dashboard(out: &mut impl Write, app: &App) -> io::Result<()> {
         Some((line, _)) => put(out, cmd_y, line, cols)?,
         None => match transient_line(app.notice(), app.status.as_deref()) {
             Some(line) => put(out, cmd_y, &line, cols)?,
-            None => dim(
-                out,
-                cmd_y,
-                "  ❯ n run · @ dir · / find · s sort · w save · o load",
-                cols,
-            )?,
+            None => dim(out, cmd_y, "  ❯ n run · @ dir · / find · s sort", cols)?,
         },
     }
 
-    // Footer hints. In foreground there is no daemon to detach from: both
-    // intents stop the in-process core (`ThreadTransport::shutdown` ignores
-    // the intent), so advertising `q detach` there would promise survival the
-    // tasks don't have.
-    let exit_hint = if app.daemon_backed {
-        "q detach · Q quit"
-    } else {
-        "q quit"
-    };
+    // Keep common actions visible and route the remaining bindings through `?`.
     dim(
         out,
         rows.saturating_sub(1),
-        &format!(
-            "  ↑↓ select · enter attach · space peek · m tag · g group · R rename · r rerun · X kill · {exit_hint}"
-        ),
+        "  ↑↓ select · enter attach · space peek · ? controls",
         cols,
     )?;
 
@@ -476,6 +465,172 @@ fn preview_provenance(p: &Preview) -> String {
     s
 }
 
+/// One controls-overlay entry. Adjacent entries with the same `group` share a
+/// heading in the grouped layout.
+struct Control {
+    key: &'static str,
+    desc: &'static str,
+    group: &'static str,
+}
+
+impl Control {
+    const fn new(key: &'static str, desc: &'static str, group: &'static str) -> Self {
+        Self { key, desc, group }
+    }
+}
+
+/// Controls-overlay entries. Each group's first half fills the left column;
+/// the second half fills the right.
+const CONTROLS: [Control; 19] = [
+    Control::new("↑↓ / kj", "move selection", "Navigate"),
+    Control::new("Tab ⇧Tab", "jump section", "Navigate"),
+    Control::new("/", "find a task", "Navigate"),
+    Control::new("M", "next tagged", "Navigate"),
+    Control::new("enter", "attach", "Act"),
+    Control::new("space", "peek", "Act"),
+    Control::new("r", "rerun finished", "Act"),
+    Control::new("X", "kill or remove", "Act"),
+    Control::new("m", "tag in use", "Organize"),
+    Control::new("g", "assign group", "Organize"),
+    Control::new("R", "rename", "Organize"),
+    Control::new("s", "cycle grouping", "Organize"),
+    Control::new("n", "run here", "Create"),
+    Control::new("@", "run in a dir", "Create"),
+    Control::new("w", "save session", "Session"),
+    Control::new("o", "load session", "Session"),
+    Control::new("q", "detach", "Leave"),
+    Control::new("Q", "quit and kill", "Leave"),
+    Control::new("Ctrl-\\", "background", "Attached"),
+];
+
+/// Label `q` as quit in foreground mode because it stops in-process tasks.
+fn control_desc(c: &Control, daemon_backed: bool) -> &'static str {
+    match c.key {
+        "q" if !daemon_backed => "quit",
+        _ => c.desc,
+    }
+}
+
+/// Split `CONTROLS` into its contiguous group runs.
+fn control_groups() -> Vec<&'static [Control]> {
+    let mut groups = Vec::new();
+    let mut start = 0;
+    for i in 1..=CONTROLS.len() {
+        if i == CONTROLS.len() || CONTROLS[i].group != CONTROLS[start].group {
+            groups.push(&CONTROLS[start..i]);
+            start = i;
+        }
+    }
+    groups
+}
+
+/// Rows required for group headings and their entries.
+fn grouped_rows() -> usize {
+    control_groups()
+        .iter()
+        .map(|g| 1 + g.len().div_ceil(2))
+        .sum()
+}
+
+/// Rows required for the complete two-column table without headings.
+fn flat_rows() -> usize {
+    CONTROLS.len().div_ceil(2)
+}
+
+/// Render the centered key reference, dropping headings before entries when
+/// height is constrained.
+fn render_controls(out: &mut impl Write, app: &App) -> io::Result<()> {
+    let cols = app.cols as usize;
+    let rows = app.rows as usize;
+
+    // Use stored descriptions so foreground's shorter `q` label does not resize
+    // the box.
+    let key_w = CONTROLS.iter().map(|c| c.key.width()).max().unwrap_or(0);
+    let desc_w = CONTROLS.iter().map(|c| c.desc.width()).max().unwrap_or(0);
+    let cell_w = key_w + 2 + desc_w;
+    let cell = |c: &Control| {
+        format!(
+            "{}  {}",
+            pad(c.key, key_w),
+            control_desc(c, app.daemon_backed)
+        )
+    };
+    // Use a fixed left-cell width to align the right column across groups.
+    let two_col = |run: &[Control]| -> Vec<String> {
+        let h = run.len().div_ceil(2);
+        (0..h)
+            .map(|i| match run.get(h + i) {
+                Some(r) => format!("  {}  {}", pad(&cell(&run[i]), cell_w), cell(r)),
+                None => format!("  {}", cell(&run[i])),
+            })
+            .collect()
+    };
+
+    // Reserve four rows for dashboard context when space permits. A three-row
+    // minimum preserves both borders and one entry row.
+    let avail = rows.saturating_sub(4).max(3);
+    let body_h = avail - 2;
+    let mut hidden = 0;
+    let body: Vec<String> = if grouped_rows() <= body_h {
+        control_groups()
+            .into_iter()
+            .flat_map(|g| {
+                let header = std::iter::once(format!("  {}", g[0].group));
+                header.chain(two_col(g).into_iter().map(|r| format!("  {r}")))
+            })
+            .collect()
+    } else if flat_rows() <= body_h {
+        two_col(&CONTROLS)
+    } else {
+        let shown = (body_h * 2).min(CONTROLS.len());
+        hidden = CONTROLS.len() - shown;
+        two_col(&CONTROLS[..shown])
+    };
+
+    // Add two borders and one trailing padding column. The four-column minimum
+    // keeps the border valid; narrow terminals clip rows instead of reflowing.
+    let content_w = body.iter().map(|s| s.width()).max().unwrap_or(0);
+    let bw = (content_w + 3).min(cols.max(4));
+    let bh = body.len() + 2;
+    let inner_w = bw - 2;
+    let x0 = cols.saturating_sub(bw) / 2;
+    let y0 = rows.saturating_sub(bh) / 2;
+
+    queue!(
+        out,
+        MoveTo(x0 as u16, y0 as u16),
+        Print(format!("┌{}┐", peek_top_border("controls", inner_w)))
+    )?;
+    for (k, line) in body.iter().enumerate() {
+        queue!(
+            out,
+            MoveTo(x0 as u16, (y0 + 1 + k) as u16),
+            Print(format!("│{}│", pad(line, inner_w)))
+        )?;
+    }
+
+    let by = (y0 + 1 + body.len()) as u16;
+    queue!(
+        out,
+        MoveTo(x0 as u16, by),
+        Print(format!("└{}┘", "─".repeat(inner_w)))
+    )?;
+    // Report omitted entries on the bottom border.
+    let more = if hidden > 0 {
+        format!(" · +{hidden} more")
+    } else {
+        String::new()
+    };
+    queue!(
+        out,
+        MoveTo((x0 + 2) as u16, by),
+        SetAttribute(Attribute::Dim),
+        Print(truncate(&format!(" ? esc close{more} "), inner_w)),
+        SetAttribute(Attribute::Reset)
+    )?;
+    Ok(())
+}
+
 /// The varying content of a bottom-panel picker; `render_panel` owns the
 /// shared skeleton.
 struct Panel<'a> {
@@ -1052,6 +1207,34 @@ mod tests {
         assert_eq!(wl.width() + wp.width() + wt.width(), cols);
     }
 
+    /// Every entry is non-empty, no key is duplicated, and each group label is
+    /// one contiguous run (the renderer prints a header per run).
+    #[test]
+    fn control_table_is_unique_and_partitioned_by_group() {
+        let mut keys: Vec<&str> = Vec::new();
+        for c in &CONTROLS {
+            assert!(!c.key.is_empty(), "empty key beside {:?}", c.desc);
+            assert!(!c.desc.is_empty(), "empty description beside {}", c.key);
+            assert!(!keys.contains(&c.key), "duplicate key {}", c.key);
+            keys.push(c.key);
+        }
+        let groups = control_groups();
+        let mut labels: Vec<&str> = groups.iter().map(|g| g[0].group).collect();
+        let total: usize = groups.iter().map(|g| g.len()).sum();
+        assert_eq!(total, CONTROLS.len(), "the runs must cover the table");
+        labels.sort_unstable();
+        let distinct = labels.len();
+        labels.dedup();
+        assert_eq!(labels.len(), distinct, "a group must be one contiguous run");
+    }
+
+    /// The grouped form adds one heading row per group to the flat entry rows.
+    #[test]
+    fn control_forms_shrink_before_they_clip() {
+        assert_eq!(flat_rows(), CONTROLS.len().div_ceil(2));
+        assert_eq!(grouped_rows(), flat_rows() + control_groups().len());
+    }
+
     /// Peek borders remain column-exact for wide and overlong labels.
     #[test]
     fn peek_top_border_fills_to_inner_width() {