docs: add a dashboard keybinding reference

README.md

@@ -48,7 +48,8 @@ The `turn` column is color-coded live — green when the agent is working, yello
 move, red (`⚠`) when a task is blocked waiting on you — so you can tell at a glance which agents
 need you. The `container` column tracks each agent's sandbox as it spawns (`queued → … → live`,
 or `down` when one needs a respawn), and governed sub-tasks nest under their governor (`└─`).
-Press `t` to drop into any task's session, `?` for the full key list.
+Press `t` to drop into any task's session, `?` for the full key list — or see
+[the keybinding reference](docs/dashboard.md).
 
 ## Requirements
 

docs/dashboard.md

@@ -0,0 +1,92 @@
+# Dashboard keybindings
+
+Every key the terminal dashboard responds to, grouped by context. The footer legend shows only
+the essential few; press `?` in the dashboard for the full list on demand. This page is that list,
+kept in sync with the `HOTKEYS` keymap and the modal `BINDINGS` in
+[`src/panopticon/terminal/dashboard.py`](../src/panopticon/terminal/dashboard.py).
+
+## Task list (the main view)
+
+| Key | Action |
+| --- | --- |
+| `t` | Attach to the task's container tmux session |
+| `n` | New task (pick repo, then workflow, then describe the work) |
+| `x` | Drop the highlighted task |
+| `d` | Show/hide the detail pane |
+| `o` | Toggle sort order: created ↔ updated |
+| `r` | Refresh from the task service now |
+| `R` | Respawn a down task (releases its claim so the runner re-spawns it) |
+| `p` | Open the task's URL in the browser |
+| `a` | List the task's artifacts |
+| `g` | Open the repo config screen |
+| `s` | Switch to the task-service session |
+| `u` | Switch to the session-service (runner) session |
+| `y` | Copy the task's slug to the clipboard |
+| `Y` | Copy the task's id to the clipboard |
+| `?` | Help — a modal listing every key |
+| `q` | Quit |
+
+`x` (drop) is the only state transition the dashboard drives; every other transition starts a new
+agentic turn and is triggered from inside the container.
+
+## Navigation
+
+| Key | Action |
+| --- | --- |
+| `↑` `↓` / `k` `j` | Move the cursor up / down |
+| `h` `l` | Vim-style navigation, alongside the arrow keys |
+
+Vim keys work in the task table, the repo table, and the option-list pickers (the `n` repo/workflow
+choice, the `a` artifact list).
+
+## Search
+
+| Key | Action |
+| --- | --- |
+| `/` | Search tasks as you type (matches slug, state, workflow, memo) |
+| `Enter` | Lock the filter — hide the box, keep the filter, restore navigation |
+| `Esc` | Clear the filter (from the search box or a locked filter) |
+
+## Ensembles
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Collapse/expand the governed tasks under a governing task |
+
+`Enter` on a governing task (one with governed children) toggles its sub-tasks between a single dim
+placeholder row and the full list. This is display-only — it does not touch the task service.
+
+## Artifacts modal (`a`)
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Open the selected artifact with the host's default handler |
+| `e` | Open the on-disk file in place (when the dashboard shares the artifact store) |
+| `Esc` | Cancel |
+
+## New-task memo (`n`)
+
+| Key | Action |
+| --- | --- |
+| `Enter` | Submit the memo as the agent's initial prompt |
+| `Ctrl-s` | Set the memo without submitting it (an unsent paste) |
+| `Ctrl-g` | Edit the memo in `$EDITOR` |
+| `Esc` | Cancel |
+
+## Repos modal (`g`)
+
+| Key | Action |
+| --- | --- |
+| `n` | New repo |
+| `e` | Edit the highlighted repo |
+| `s` | Setup repo |
+| `Esc` | Close |
+
+## Supervisor (attached to a task)
+
+| Key | Action |
+| --- | --- |
+| `Ctrl-b d` | Detach and return to the dashboard |
+
+After `t` attaches you to a task's session, the terminal session supervisor brings you back to the
+dashboard when you detach with `Ctrl-b d` (or your own `tmux` prefix + `d`).

docs/overview.md

@@ -133,6 +133,7 @@ This page is the map; these guides are the detail:
 - **[Workflow catalog](workflows/README.md)** — the built-in workflows and how to choose (and
   how to add your own).
 - **[Tasks](tasks.md)** — the task object in full: its properties, states, and lifecycle.
+- **[Dashboard keys](dashboard.md)** — every dashboard keybinding, grouped by context.
 - **[Containers](container.md)** — the container lifecycle, every dashboard status, and recovery.
 - **[Repos](repos.md)** — configuring a repo: secrets, image layers, and capabilities.
 - **[Container auth](auth.md)** — giving each repo's agents their Claude token (and a GitHub token for PRs).