@fadhelhaidar/pi-ask-user 0.0.0-stage → 1.0.2

package/dist/locales/es.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Escribe algo.",
+  "sentinel.next": "Siguiente",
+
+  "submit.label": "Enviar respuestas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para seleccionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.newline": "Mayús+Enter para nueva línea",
+  "hint.clear": "Ctrl+U para borrar",
+  "hint.toggle": "Espacio para alternar",
+  "hint.notes": "n para añadir notas",
+  "hint.tab": "Tab para cambiar de pregunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Revisa tus respuestas",
+  "review.ready": "¿Listo para enviar tus respuestas?",
+  "review.incomplete": "⚠ Responde las preguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Vista previa no disponible",
+  "preview.notes_affordance": "Notas: pulsa n para añadir notas",
+  "notes.header": "Notas:",
+
+  "editor.failed": "Error del editor externo",
+
+  "rpc.multi_instructions": "Introduce los números de todas las opciones que apliquen, separados por comas (p. ej. \"1,3\"), o escribe una respuesta propia como texto.",
+  "rpc.custom_answer_title": "Escribe tu respuesta:"
+}

package/dist/locales/fr.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Écrivez quelque chose.",
+  "sentinel.next": "Suivant",
+
+  "submit.label": "Envoyer les réponses",
+  "submit.cancel": "Annuler",
+
+  "hint.enter": "Entrée pour sélectionner",
+  "hint.navigate": "↑/↓ pour naviguer",
+  "hint.newline": "Maj+Entrée pour une nouvelle ligne",
+  "hint.clear": "Ctrl+U pour effacer",
+  "hint.toggle": "Espace pour basculer",
+  "hint.notes": "n pour ajouter des notes",
+  "hint.tab": "Tab pour changer de question",
+  "hint.cancel": "Échap pour annuler",
+
+  "review.heading": "Vérifiez vos réponses",
+  "review.ready": "Prêt à envoyer vos réponses ?",
+  "review.incomplete": "⚠ Répondez aux questions restantes avant d'envoyer :",
+
+  "preview.no_preview": "Aucun aperçu disponible",
+  "preview.notes_affordance": "Notes : appuyez sur n pour ajouter des notes",
+  "notes.header": "Notes :",
+
+  "editor.failed": "Échec de l’éditeur externe",
+
+  "rpc.multi_instructions": "Saisissez les numéros de toutes les options applicables, séparés par des virgules (p. ex. « 1,3 »), ou tapez une réponse libre en texte.",
+  "rpc.custom_answer_title": "Tapez votre réponse :"
+}

package/dist/locales/pt-BR.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Digite algo.",
+  "sentinel.next": "Próximo",
+
+  "submit.label": "Enviar respostas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para selecionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.newline": "Shift+Enter para nova linha",
+  "hint.clear": "Ctrl+U para limpar",
+  "hint.toggle": "Espaço para alternar",
+  "hint.notes": "n para adicionar notas",
+  "hint.tab": "Tab para trocar de pergunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Revise suas respostas",
+  "review.ready": "Pronto para enviar suas respostas?",
+  "review.incomplete": "⚠ Responda as perguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Pré-visualização indisponível",
+  "preview.notes_affordance": "Notas: pressione n para adicionar notas",
+  "notes.header": "Notas:",
+
+  "editor.failed": "Falha no editor externo",
+
+  "rpc.multi_instructions": "Digite os números de todas as opções aplicáveis, separados por vírgula (ex.: \"1,3\") ou digite uma resposta própria em texto.",
+  "rpc.custom_answer_title": "Digite sua resposta:"
+}

package/dist/locales/pt.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "European Portuguese (Portugal). Auto-translated draft. Native-speaker review welcome via PR. Distinct from pt-BR (Brasil): differs in lexicon (utilizador / você), conjugation, and some terms. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Escreva algo.",
+  "sentinel.next": "Seguinte",
+
+  "submit.label": "Enviar respostas",
+  "submit.cancel": "Cancelar",
+
+  "hint.enter": "Enter para selecionar",
+  "hint.navigate": "↑/↓ para navegar",
+  "hint.newline": "Shift+Enter para nova linha",
+  "hint.clear": "Ctrl+U para limpar",
+  "hint.toggle": "Espaço para alternar",
+  "hint.notes": "n para adicionar notas",
+  "hint.tab": "Tab para mudar de pergunta",
+  "hint.cancel": "Esc para cancelar",
+
+  "review.heading": "Reveja as suas respostas",
+  "review.ready": "Pronto para enviar as suas respostas?",
+  "review.incomplete": "⚠ Responda às perguntas restantes antes de enviar:",
+
+  "preview.no_preview": "Pré-visualização indisponível",
+  "preview.notes_affordance": "Notas: prima n para adicionar notas",
+  "notes.header": "Notas:",
+
+  "editor.failed": "Falha no editor externo",
+
+  "rpc.multi_instructions": "Introduza os números de todas as opções aplicáveis, separados por vírgulas (ex.: \"1,3\") ou escreva uma resposta própria em texto.",
+  "rpc.custom_answer_title": "Escreva a sua resposta:"
+}

package/dist/locales/ru.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Введите что-нибудь.",
+  "sentinel.next": "Далее",
+
+  "submit.label": "Отправить ответы",
+  "submit.cancel": "Отмена",
+
+  "hint.enter": "Enter — выбрать",
+  "hint.navigate": "↑/↓ — навигация",
+  "hint.newline": "Shift+Enter — новая строка",
+  "hint.clear": "Ctrl+U — очистить",
+  "hint.toggle": "Space — переключить",
+  "hint.notes": "n — добавить заметки",
+  "hint.tab": "Tab — следующий вопрос",
+  "hint.cancel": "Esc — отменить",
+
+  "review.heading": "Проверьте свои ответы",
+  "review.ready": "Готовы отправить ответы?",
+  "review.incomplete": "⚠ Ответьте на оставшиеся вопросы перед отправкой:",
+
+  "preview.no_preview": "Предпросмотр недоступен",
+  "preview.notes_affordance": "Заметки: нажмите n, чтобы добавить заметки",
+  "notes.header": "Заметки:",
+
+  "editor.failed": "Ошибка внешнего редактора",
+
+  "rpc.multi_instructions": "Введите номера всех подходящих вариантов через запятую (например, \"1,3\") или введите свой ответ текстом.",
+  "rpc.custom_answer_title": "Введите свой ответ:"
+}

package/dist/locales/uk.json

@@ -0,0 +1,31 @@
+{
+  "_meta.notes": "Auto-translated draft. Native-speaker review welcome via PR. TUI symbols (↑/↓, ⚠) and key names (Enter, Esc, Tab, Space, n, Ctrl+G, Ctrl+U) are universal CLI conventions and stay untranslated.",
+
+  "sentinel.other": "Введіть щось.",
+  "sentinel.next": "Далі",
+
+  "submit.label": "Надіслати відповіді",
+  "submit.cancel": "Скасувати",
+
+  "hint.enter": "Enter — обрати",
+  "hint.navigate": "↑/↓ — навігація",
+  "hint.newline": "Shift+Enter — новий рядок",
+  "hint.clear": "Ctrl+U — очистити",
+  "hint.toggle": "Space — перемкнути",
+  "hint.notes": "n — додати нотатки",
+  "hint.tab": "Tab — наступне питання",
+  "hint.cancel": "Esc — скасувати",
+
+  "review.heading": "Перегляньте свої відповіді",
+  "review.ready": "Готові надіслати відповіді?",
+  "review.incomplete": "⚠ Дайте відповіді на решту питань перед надсиланням:",
+
+  "preview.no_preview": "Попередній перегляд недоступний",
+  "preview.notes_affordance": "Нотатки: натисніть n, щоб додати нотатки",
+  "notes.header": "Нотатки:",
+
+  "editor.failed": "Помилка зовнішнього редактора",
+
+  "rpc.multi_instructions": "Введіть номери всіх відповідних варіантів через кому (наприклад, \"1,3\") або введіть власну відповідь текстом.",
+  "rpc.custom_answer_title": "Введіть свою відповідь:"
+}

package/dist/locales/zh.json

@@ -0,0 +1,33 @@
+{
+  "_meta.notes": "中文翻译。欢迎中文母语者通过 PR 审校。TUI 符号（↑/↓、⚠）为通用 CLI 约定，保持原文不译。Enter、Space 采用中文惯用说法（回车、空格）；Esc、Tab、Ctrl、n 等保留原文。",
+
+  "sentinel.other": "输入内容",
+  "sentinel.next": "下一个",
+
+  "submit.label": "提交答案",
+  "submit.cancel": "取消",
+
+  "hint.enter": "回车选择",
+  "hint.navigate": "↑/↓ 导航",
+  "hint.newline": "Shift+Enter 换行",
+  "hint.clear": "Ctrl+U 清空",
+  "hint.toggle": "空格切换",
+  "hint.notes": "按 n 添加备注",
+  "hint.tab": "Tab 切换问题",
+  "hint.collapse": "{key} 折叠",
+  "hint.expand_line": "{key} 展开 · Esc 取消",
+  "hint.cancel": "Esc 取消",
+
+  "review.heading": "检查你的答案",
+  "review.ready": "准备提交答案了吗？",
+  "review.incomplete": "⚠ 提交前请先回答以下问题：",
+
+  "preview.no_preview": "暂无预览",
+  "preview.notes_affordance": "备注：按 n 添加",
+  "notes.header": "备注：",
+
+  "editor.failed": "外部编辑器启动失败",
+
+  "rpc.multi_instructions": "输入所有适用选项的编号，用逗号分隔（例如 \"1,3\"），或直接输入自定义回答。",
+  "rpc.custom_answer_title": "输入你的回答："
+}

package/docs/configuration.md

@@ -0,0 +1,121 @@
+# Configuration
+
+Every setting the package reads, where the file lives, and what happens when a value is
+wrong.
+
+## The config file
+
+```
+~/.config/rpiv-ask-user-question/config.json
+```
+
+The file is optional — with no config at all, every setting takes its default. This
+package only ever *reads* the file; it never creates, writes or chmods it, so its
+permissions are whatever you give it.
+
+A complete example:
+
+```json
+{
+  "collapseKey": "alt+o",
+  "guidance": {
+    "description": "Ask the user structured questions whenever requirements are ambiguous.",
+    "promptSnippet": "Ask me before guessing on anything ambiguous",
+    "promptGuidelines": [
+      "Batch every clarifying question into one ask_user_question call.",
+      "Put your recommended option first and suffix it with (Recommended)."
+    ]
+  }
+}
+```
+
+### Where the file is looked up
+
+1. `$XDG_CONFIG_HOME/rpiv-ask-user-question/config.json`, if `XDG_CONFIG_HOME` is set,
+   non-empty and absolute. A leading `~` is expanded first; a relative value is ignored.
+   Unset or ignored, the directory falls back to `~/.config`.
+2. If that file does not exist, the legacy path `~/.config/rpiv-ask-user-question/config.json`
+   is read. This path deliberately ignores `XDG_CONFIG_HOME`, so an existing config keeps
+   working after you set the variable.
+3. Neither present: all defaults.
+
+If the XDG-path file exists, its result wins even when it is malformed — there is no
+second chance at the legacy path.
+
+### When the file is invalid
+
+Malformed JSON is not fatal. The loader warns on stderr and continues with defaults:
+
+```
+rpiv-config: invalid JSON at <path>, using default ({}) — <parser message>
+```
+
+Valid JSON that is not an object (a string, number, `null`, or an array) is rejected too,
+falling back to defaults — but silently, with no warning. Individual keys with the wrong
+type are likewise dropped back to their default without a warning.
+
+## Settings
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog overlay. | `"ctrl+]"` |
+| `guidance.description` | Full text of the tool description the model sees. Replaces the built-in default entirely — no merging. | built-in description |
+| `guidance.promptSnippet` | One-line snippet describing the tool in the system prompt. | built-in snippet |
+| `guidance.promptGuidelines` | List of usage guidelines given to the model. | 4 built-in guidelines |
+
+### `collapseKey`
+
+The value uses Pi's keybinding id format: zero or more distinct modifiers from `ctrl`,
+`shift`, `alt`, `super`, joined by `+`, followed by a base key. Values are trimmed and
+lowercased before matching.
+
+The base key is either a single printable character from
+`a-z 0-9 _ - ! @ # $ % ^ & * ( ) | ~ \` ' " : ; , . / < > ? [ ] { } = \`, or one of the
+named keys `escape`, `esc`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`,
+`insert`, `clear`, `home`, `end`, `pageup`, `pagedown`, `up`, `down`, `left`, `right`,
+`f1`–`f12`.
+
+Examples that work: `"ctrl+]"`, `"alt+o"`, `"ctrl+shift+h"`, `"f9"`, `"ctrl+}"`.
+
+Set `"off"` (any casing) to disable the collapse shortcut entirely — no raw terminal
+listener is registered in that case.
+
+A spec that does not match the grammar is rejected and the default is used. This is
+strict on purpose: Pi's parser takes the last `+`-separated part as the key and ignores
+unknown parts, so a typo like `"ctr+]"` would otherwise silently capture every bare `]`
+keypress at the terminal level.
+
+The footer hint inside the dialog names whatever key you configure (`Alt+O to collapse`
+for `"alt+o"`), as do the collapsed one-line footer and the one-shot notification shown
+when the dialog is first hidden. With `"off"` the collapse hint is dropped from the
+footer entirely, since no shortcut can fire.
+
+### `guidance.description`, `guidance.promptSnippet` and `guidance.promptGuidelines`
+
+`guidance.description` replaces the entire built-in description Pi registers for the
+`ask_user_question` tool — the text the model reads when deciding how to use it. There is
+no merging: a valid value wins wholesale. It is used only when it is a non-empty string;
+anything else falls back to the built-in default. Like the other guidance fields it is read
+once, when the extension registers the tool, so changes take effect on the next Pi restart.
+
+These replace the text Pi puts in the system prompt about when to reach for
+`ask_user_question`. Use them to make the model ask more or less often, or to enforce a
+house style for options.
+
+`promptSnippet` is used only when it is a non-empty string. `promptGuidelines` is used
+only when it is a non-empty array whose entries are all non-empty strings. Anything else
+falls back to the built-in defaults. Both are read once, when the extension registers the
+tool, so changes take effect on the next Pi restart.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `XDG_CONFIG_HOME` | Relocates the config directory, as described above. Must be absolute. |
+
+`LANG` and `LC_ALL` influence the dialog language, but they are read by
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) rather than
+by this package — see [localization.md](./localization.md).
+
+No other environment variables are read. The package makes no model calls, so it needs no
+API keys or model settings of its own.

package/docs/hosts.md

@@ -0,0 +1,97 @@
+# Hosts and runtime behavior
+
+Where the questionnaire renders, what it degrades to, and what happens when it cannot
+render at all.
+
+## Three environments
+
+| Environment | What the model sees | What you see |
+| --- | --- | --- |
+| Interactive terminal | `ask_user_question` in its tool list | The full tabbed TUI overlay |
+| RPC / ACP host (VS Code pendant, Zed, Paseo) | `ask_user_question` in its tool list | A sequence of the host's own native select and input dialogs |
+| Non-interactive run (no UI) | Nothing — the tool is removed | Nothing |
+
+### Terminal attention
+
+After UI availability and questionnaire validation succeed, the package emits exactly one standard terminal BEL (`\x07`) immediately before the interactive wait begins. The signal is sent to `stdout` only when `process.stdout.isTTY` is true, so redirected output and non-TTY RPC streams stay untouched. A TTY-backed RPC dialog walker receives the same signal as the TUI path.
+
+The BEL is best effort: if the synchronous terminal write fails, the questionnaire continues and its existing prompt/blocked lifecycle and result envelope are unchanged. The terminal configuration decides whether the BEL is audible, visual, or ignored. No BEL is emitted for missing UI, invalid questionnaires, or a failed TUI session load.
+
+### Non-interactive runs
+
+A `before_agent_start` hook reconciles the active tool set against `ctx.hasUI` before every
+turn. When there is no UI, `ask_user_question` is stripped from the list so the model never
+sees a tool it cannot use — better than offering it and auto-declining every call. When UI
+comes back, the tool is restored. The reconciler is idempotent and leaves sibling tools
+untouched.
+
+A second guard lives inside the tool handler as a one-turn backstop: if a call somehow
+arrives without UI, it returns `error: "no_ui"` and the text
+`Error: UI not available (running in non-interactive mode)`.
+
+### RPC and ACP hosts
+
+RPC hosts report `hasUI: true` because Pi's dialog sub-protocol works there, but custom
+terminal UI does not render. The package detects this two ways: hosts that advertise
+`ctx.mode === "rpc"` route straight to the dialog walker, skipping the TUI import
+entirely, and older RPC builds are caught by a backstop when custom UI resolves without
+rendering anything. Either path requires the host to expose both `select` and `input`.
+
+The walker asks one question per dialog and returns exactly the same result envelope the
+TUI produces. Trade-offs inherent to the native primitives:
+
+- No side-by-side preview pane. Previews are folded into the dialog title instead,
+  truncated at 600 characters each.
+- No tab bar and no Submit review tab — one dialog per question, in order.
+- No notes. Both note kinds — per-question `n` on a question tab and global `n` on the
+  Submit tab — are terminal-only; the host's native `select` and `input` primitives carry
+  no note field.
+- Multi-select is a free-text input: type the option numbers, comma-separated
+  (`1,3`). Any token that is not a valid option index is treated as a typed custom answer,
+  which is how the `Type something.` escape survives. An empty input commits an empty
+  selection, matching `Next` with nothing toggled.
+- Dismissing any dialog cancels the whole questionnaire, mirroring `Esc` in the TUI.
+
+If the host can render neither custom UI nor dialogs, the call returns
+`error: "no_custom_ui"` with text telling the model the user never saw the questions and
+that it should ask them as plain chat text instead — explicitly not a decline.
+
+## Conditional surfaces
+
+Some parts of the dialog exist only under the right conditions:
+
+| Surface | Appears when |
+| --- | --- |
+| Tab bar and Submit tab | The call carries more than one question |
+| `Next` row | The question is multi-select |
+| `Type something.` row | Always |
+| Side-by-side preview | An option carries a `preview`, and terminal and pane are both ≥ 100 columns |
+| Preview pane at all | Single-select questions only |
+| Collapse shortcut | `collapseKey` is not `"off"` |
+| Full overlay hide on collapse | The host also exposes raw terminal input (the only path that can reopen a hidden overlay); without it, collapsing shrinks the dialog to a visible one-line row instead |
+| Localized chrome | `@juicesharp/rpiv-i18n` is installed |
+
+## Loading and startup cost
+
+The dialog's render graph costs roughly 560 ms to import, so it is loaded lazily — on the
+first tool call, not when the extension registers. To keep that first call fast and safe,
+the graph is also pre-warmed in the background two seconds after startup. The pre-warm
+timer is unref'd, so it never holds a process open, and a failed pre-warm is swallowed:
+the first real call re-imports and reports properly.
+
+The pre-warm exists for a specific failure. Pi's module loader registers a module in its
+graph cache *before* evaluating it and does not evict it if evaluation throws. If your
+package manager replaces the dependency store while Pi is running, one failed import can
+poison the cache for the rest of the process. Evaluating the graph early, while the paths
+Pi resolved at boot still exist, keeps it in memory for the process lifetime and makes
+that unreachable.
+
+When it does happen, you get a structured envelope rather than a raw `TypeError`:
+
+| `error` | Meaning | Fix |
+| --- | --- | --- |
+| `session_load_failed` | The dialog module could not be imported. | Repair the install if needed, then restart Pi. |
+| `stale_module_cache` | The module cache went stale after an earlier failed import. | Restart Pi — this is unrecoverable in the running process. |
+
+Both messages tell the model the questions were never shown and to ask them as plain chat
+text instead of treating the failure as a decline.

package/docs/keyboard.md

@@ -0,0 +1,115 @@
+# 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. | 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` 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. 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>`.
+
+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: the overlay is marked hidden in Pi's overlay
+stack and shrinks to a single dim hint row, so the transcript it was covering 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.
+
+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.
+
+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
+
+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.

package/docs/localization.md

@@ -0,0 +1,87 @@
+# Localization
+
+How the dialog picks its language, which languages ship, and how to add one.
+
+## Enabling it
+
+The extension works standalone: install only this package and you get the full dialog in
+English. Localization needs one more install:
+
+```sh
+pi install npm:@juicesharp/rpiv-i18n
+```
+
+Restart your Pi session. If you installed through
+[`@juicesharp/rpiv-pi`](https://www.npmjs.com/package/@juicesharp/rpiv-pi) and ran
+`/rpiv-setup`, you already have it.
+
+The dependency is a genuinely optional peer. This package loads the SDK inside a
+`try`/`catch` at startup; when it is absent, every string falls back to its inline English
+literal at the call site. There is no warning and no crash — the dialog simply renders in
+English.
+
+## Picking a language
+
+With the SDK installed, the locale resolves in this order, first hit wins:
+
+1. `pi --locale <code>` on the command line
+2. `~/.config/rpiv-i18n/locale.json`
+3. `LANG` / `LC_ALL` from the environment
+4. English
+
+`/languages` opens an interactive picker and flips the strings live — the dialog reads its
+strings at render time, so an open questionnaire follows the change. Both `/languages` and
+`--locale` are registered by `@juicesharp/rpiv-i18n`, not by this package.
+
+## Shipped languages
+
+Nine locale files ship in `locales/`:
+
+| Code | Language |
+| --- | --- |
+| `de` | Deutsch |
+| `en` | English |
+| `es` | Español |
+| `fr` | Français |
+| `pt` | Português |
+| `pt-BR` | Português (Brasil) |
+| `ru` | Русский |
+| `uk` | Українська |
+| `zh` | 中文 |
+
+## What is translated, and what is not
+
+Translation covers the chrome you read: the `Type something.` and `Next` sentinel rows,
+the footer hint segments (including the collapsed-state line and the Submit tab's
+`n to add a note` hint), the Submit picker labels, the review-tab heading with its
+submit-readiness prompt, incomplete-answers warning, and committed-note `Note` label, the
+preview pane's empty and notes-affordance lines, the notes header and the global-note
+header on the Submit tab, the
+external-editor failure notification, and the two RPC dialog prompts. Twenty-six keys in total,
+all under the namespace `@juicesharp/rpiv-ask-user-question`.
+
+Everything the *model* reads stays English by design: the tool description, the parameter
+schema descriptions, error messages, and the reserved-label list. Those are prompt inputs,
+not UI, and translating them would change model behavior rather than your reading
+experience. It also means reserved-label validation compares against fixed English
+strings, so `Type something.` is rejected as an authored option label in every locale.
+
+## Adding a language
+
+No code change is required.
+
+1. Copy `locales/en.json` to `locales/<code>.json`, where `<code>` is a locale the SDK
+   supports.
+2. Translate the values. Keep every key, and keep the placeholders and leading symbols
+   (`↑/↓`, `⚠`) intact. `hint.collapse` and `hint.expand_line` contain a literal `{key}`
+   placeholder that is replaced at render time with the user's configured `collapseKey` —
+   keep it verbatim, positioned wherever your language's word order wants the key name.
+3. Restart Pi and select the language with `/languages`.
+
+The loader iterates the SDK's supported-locale list over this directory at startup, so a
+new file is picked up automatically. See the
+[`@juicesharp/rpiv-i18n`](https://www.npmjs.com/package/@juicesharp/rpiv-i18n) README,
+section "Contributing translations", for the full convention.
+
+Keys are looked up individually with an English fallback, so a partially translated file
+is safe — untranslated keys render in English rather than blank.