# 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` | Toggle a multi-select checkbox (including custom text), confirm a single-select answer, close notes, or activate Next/Submit. | 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 |
| `Space` | Insert a normal space while typing; never toggle a checkbox. | Text inputs only |
| `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 |
| `1`–`9` | Act on the row with that number: answer a single-select question, toggle a multi-select row, or move to `Type something.` so you can type. A digit you bound yourself, or set as `notesKey`, keeps that meaning. | Option list |
| `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` is the only checkbox toggle key. It does not
submit or move focus. Committing the question means focusing `Next`/`Submit` and
pressing `Enter`. Space does nothing outside text inputs.

Focusing the multi-select `Type something.` row allows immediate typing. Enter
selects or deselects its checkbox while retaining the draft and editor focus.
Space inserts an ordinary space. Typing or leaving the row does not automatically
select it; press Enter to include it. Unchecking keeps the text available to edit
or reselect later, but excludes it from the submitted answer.

## 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
both single-select and multi-select questions. 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` round-trips it through Pi's configured external editor; `Ctrl+U`
clears it, while `Esc` remains the explicit way to cancel the questionnaire. Confirming
it produces an answer of `kind: "custom"` in single-select mode. In multi-select
mode, checked custom text is included in the `answer` field of a `kind: "multi"`
answer alongside predefined `selected` labels; unchecked text remains only a draft
and is not submitted.

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. On non-Latin layouts set
`notesKey` (see [Configuration](configuration.md)) to the character your keyboard types,
or to a key spec such as `"ctrl+n"`. 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>`.

A saved note stays visible after its editor closes, as one dimmed
`Note for this answer: …` row that `n` reopens; the preview hint switches to
`Note saved: press n to edit`, and the Submit-tab 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.

## Collapse mode

`Ctrl+]` gets the dialog out of the way: it shrinks to a single dim hint row, so the
transcript becomes readable and chat scrolling resumes. Press the same key to bring the
questionnaire back with your answers intact. The first time you collapse, Pi notifies you
with the key to press — that message names your configured key.

How it collapses depends on where the dialog opened. Inline (Pi's editor area) it simply
keeps the editor slot and the one-line row. An overlay is marked hidden in Pi's overlay
stack instead, and 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 `/btw` keeps its one-line row rather than
hiding, since Pi closes overlays from the top of the stack and would otherwise pop `/btw`
instead of the hidden question.

While collapsed, every keystroke other than cancel 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

The dialog opens inline in Pi's editor area below the transcript, where Pi's own prompts
appear, and takes at most 70% of the terminal height (never fewer than 12 rows); it
scrolls within that space, so the transcript above it stays scrollable while a question is
open. A second questionnaire opened while an inline one is showing, or a question arriving
while another overlay such as `/btw` is open, opens as an overlay on top instead, so the
question on screen is the one receiving keys.

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 space it has, the header and question stay pinned while
the body scrolls between them and a sticky footer, and an overflow indicator shows which
direction is clipped: `↑` for content above, `↓` for content below, `↕` for both. The
markers never replace the focused row, padding is trimmed before content, and only the
padding — never the body — is dropped to make the dialog fit.

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.