# Keyboard and dialog layout

Every key the questionnaire dialog reacts to, the rows it appends for you, and how it
adapts to the size of your terminal.

## Keys

| Key                 | What it does                                                                                                                                                                                                                          | Where it applies                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `↑` / `↓`           | Move between rows. Wraps at both ends.                                                                                                                                                                                                | Option list, Submit picker                                   |
| `Enter`             | Confirm the focused option, commit typed text, close notes, or activate the focused Submit-picker row.                                                                                                                                | Everywhere                                                   |
| `Shift+Enter`       | Insert a newline.                                                                                                                                                                                                                     | `Type something.` input, notes editor                        |
| `Esc`               | Cancel the whole questionnaire.                                                                                                                                                                                                       | Everywhere except the notes editor, where it closes notes    |
| `Tab` / `Shift+Tab` | Next / previous tab, wrapping. `→` / `←` do the same.                                                                                                                                                                                 | Multi-question dialogs only                                  |
| `1`–`9`             | Act on the row with that number: answer with it on a single-select question, toggle it on a multi-select one, or move to `Type something.` (no digit reaches `Next`). Inside `Type something.` and the notes editor, digits are text. | Option list                                                  |
| `Space`             | Toggle the focused authored option. In `Type something.`, Space inserts text.                                                                                                                                                         | Multi-select questions                                       |
| `n`                 | Open the notes editor for the focused question — or, on the Submit tab, the global note for the whole questionnaire. Configurable via `notesKey`.                                                                                     | Every question tab; the Submit tab in multi-question dialogs |
| `Ctrl+G`            | Open Pi's configured external editor with the current custom-answer draft.                                                                                                                                                            | `Type something.` input                                      |
| `Ctrl+U`            | Clear the current custom-answer draft.                                                                                                                                                                                                | `Type something.` input                                      |
| `Ctrl+]`            | Collapse or expand the dialog. Configurable via `collapseKey`.                                                                                                                                                                        | Everywhere, including while collapsed                        |

The table names the default keys; the dialog actually follows your Pi keybindings.
Confirm listens to both `tui.select.confirm` and `tui.input.submit`, and a key bound to
`tui.input.newLine` always inserts a newline even if it also matches confirm. So a
Slack-style configuration — `enter` folded into `tui.input.newLine`, submit moved to
`ctrl+enter` — keeps working: `enter` breaks lines, and your submit key confirms
everywhere `Enter` does.

In a multi-select question, `Enter` on a regular row toggles its checkbox exactly like
`Space`. It does not submit. Focus `Next` and press `Enter` to commit the question. That
is deliberate: it makes `Enter` a zero-cost way to flip boxes without leaving the home row.
`Space` does nothing on `Next` (it is a command, not a choice).

`Type something.` is an inline input, so Space inserts a space. Its checkbox changes to
`[✔]` when the input contains text. Press `Enter` in the input or use `Next` to submit
both the checked options and the custom text.

## The rows the dialog adds

| Row           | Label             | Appended to                                                               |
| ------------- | ----------------- | ------------------------------------------------------------------------- |
| Custom answer | `Type something.` | Every question — single-select and multi-select, with or without previews |
| Commit        | `Next`            | Multi-select questions only                                               |

Focusing `Type something.` switches the row into an inline multiline editor. In preview
mode it expands to the full pane width while you type, so a long custom answer is not
squeezed into the narrow options column. `Shift+Enter` inserts a line break. Vertical
arrows move between lines and return to row navigation at the draft's top and bottom.
The draft replaces the static row label while you browse other options and is isolated
per question. `Ctrl+G` sends it through Pi's configured external editor. `Ctrl+U` clears
it, while `Esc` cancels the questionnaire. In a single-select question, `Enter` on an empty
or blank draft does nothing: a blank custom answer is never recorded. To leave a question
unanswered, move on and submit; the model is told which questions were left blank.

On a single-select question, confirming the input produces `kind: "custom"`. On a
multi-select question, the result uses `kind: "multi"`: `selected` contains checked
labels, and `answer` contains the custom text.

Both labels are reserved — the model cannot author an option that collides with them.
Both localize with the rest of the UI chrome; the reserved-label check always compares
against the canonical English strings.

## Notes

`n` opens a notes editor on any question tab, whether the question is single- or
multi-select and whether or not its options carry previews. Notes are stored in a
side-band keyed by tab index, not inside the answer, so writing a note does not mark a
question as answered — the Submit tab still lists it as outstanding. The note merges into
the answer when you confirm it, and reaches the model as `user notes: <text>`. Once the
editor closes, the question shows the saved note as `Note for this answer: …` (its first
line), and a preview pane's hint changes to "Note saved: press n to edit"; the Submit tab's
review uses the same label.

On the Submit tab, `n` opens the global note editor instead — one note covering the whole
questionnaire. It lives outside every answer, so it survives tab switches and never marks
a question as answered; it reaches the model as `global note: <text>`, and submitting with
nothing but a global note still returns an answered result rather than a decline.

Inside the editor, `Shift+Enter` inserts a newline, while `Esc` and `Enter` close it; other
keystrokes edit the buffer, so `n` types an `n`. Pasted line breaks are preserved.

## Where the dialog appears

The questionnaire opens in Pi's editor area, below the transcript — where Pi's own select
and input prompts appear. The transcript keeps scrolling with `PageUp`/`PageDown` and the
wheel while the dialog keeps its own keys. The dialog takes at most 70% of the terminal
height (at least 12 rows); a taller questionnaire scrolls its options inside that space,
keeping the header, the question, the focused option and the key hints visible.

Wheel and trackpad scrolling reach the transcript only when the terminal reports them as
mouse events. A terminal with mouse reporting turned off (Warp, for one) converts them
into ↑/↓ key presses instead, which move between the dialog's options. tmux does the same
unless mouse mode is on (`set -g mouse on` in `~/.tmux.conf`). `PageUp`/`PageDown`
(`Fn+↑`/`Fn+↓` on a Mac keyboard) scroll the transcript either way.

Two cases open the questionnaire as an overlay instead:

- **A second question while one is open.** Only one questionnaire fits in the editor area,
  so the second covers the bottom of the transcript as an overlay.
- **A question arriving while another overlay, such as `/btw`, is open.** The question
  stacks on top, so the question you see is the one your keys reach. `Ctrl+]` shrinks it to
  its one-line row so `/btw` is readable behind it; the question keeps the keys, so `Esc`
  cancels the question, and `/btw` closes after the question is answered or cancelled.
  Overlays that never take the keys, such as an extension's status panel, don't count: the
  question still opens in the editor area.

While the questionnaire is an overlay, Pi gives it `PageUp`/`PageDown` (and, before Pi 1.2,
the wheel), so the transcript doesn't scroll until the question is answered or cancelled.

## Collapse mode

`Ctrl+]` gets the dialog out of the way. In the editor area it shrinks the questionnaire
to a single dim hint row for more room. The row keeps focus, so the same key brings the
questionnaire back with your answers intact.

When the questionnaire opened as an overlay for a second question, collapse marks the
overlay hidden in Pi's overlay stack, so the transcript it was covering
becomes readable and chat scrolling resumes. The first time you collapse, Pi notifies you
with the key to press — that message names your configured key. Because Pi routes no
input to a hidden overlay, the collapse key is additionally captured at the raw terminal
level. It only acts when the questionnaire is hidden or focused, so a different overlay
on top of it (for example `/btw`) keeps its keystrokes. A question that opened on top of
an overlay that was already showing (for example `/btw`) is never hidden this way: collapse
shrinks it to the one-line row and it keeps focus, because Pi closes overlays from the top
of the stack and would otherwise remove the hidden question when `/btw` closes.

While collapsed, every keystroke other than cancel or expand is ignored, so you cannot
mutate answers you cannot see.

The default `ctrl+]` is free in Terminal.app, iTerm2, Warp, tmux, zellij and screen. On
keyboard layouts where `]` sits on the shifted layer — Latin American `es-AR` / `es-MX`,
among others — set a different `collapseKey`, or `"off"` to disable the shortcut.

## Layout

Options render in a vertical list. When any option in a single-select question carries a
`preview`, the dialog splits into a side-by-side layout with the option list on the left
and a bordered monospace preview box on the right — but only when both the terminal and
the dialog pane are at least 100 columns wide. Below that, the preview stacks underneath
the options instead.

When the dialog is taller than the terminal, the body scrolls between a sticky heading and
a sticky footer, and an overflow indicator shows which direction is clipped: `↑` for
content above, `↓` for content below, `↕` for both.

The footer hint line adapts to context — it drops the notes hint and appends the
`Shift+Enter` newline hint whenever a text editor has the keyboard, with `Ctrl+U` still at
the far right for custom answers. It adds the tab hint only in multi-question dialogs. The
Submit tab follows the same idiom: its bottom hint row sits below the picker and carries
an `n to add a note` part that gives way to the `Shift+Enter` newline hint while the
global-note editor is open; a committed note shows as a `Note` entry in the review list.
`Ctrl+G` remains Pi's global external-editor shortcut and is not repeated there. On narrow
terminals the right edge clips with `…` so the core hints survive.
