pi-ask-popup 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 # pi-ask-popup
 
-Let the model ask you instead of guessing. This Pi extension registers one tool,
-`ask_user_question`, that opens a terminal dialog of up to four questions with
-written-out options, and hands your choices back as structured data.
+Let the model ask you instead of guessing. This Pi extension registers one tool, `ask_user_question`, that opens a terminal dialog of up to four questions with written-out options, and hands your choices back as structured data.
+
+![Single question with a preview, options on the left and a bordered markdown box on the right](./preview/popup-with-tab.webp)
 
 ## Install
 
@@ -10,45 +10,108 @@ written-out options, and hands your choices back as structured data.
 pi install npm:pi-ask-popup
 ```
 
+Restart your Pi session.
+
+```sh
+pi --version  # needs 0.80 or newer
+node --version  # needs 22 or newer
+```
+
+No runtime dependencies, no build step, no API keys. The extension makes no model calls of its own.
+
+## Quick start
+
+Give the model a task with a real decision in it:
+
+> Add caching to the API client.
+
+Rather than picking for you, the model calls `ask_user_question` and a dialog takes over the bottom of your terminal. Move with `Up` and `Down`, pick with `Enter`, or land on `Type something.` to answer in your own words. While typing, `Shift+Enter` adds a line, `Ctrl+G` opens Pi's external editor, `Ctrl+U` clears the draft, and `Esc` cancels the whole questionnaire. Pressing `n` adds a note to the current question. The questionnaire stays in one place until you submit.
+
+When the model asks several things at once, `Tab` moves between questions and a Submit tab reviews everything before it goes back:
+
+![Four questions in tabs with a Submit review tab](./preview/popup-submit.webp)
+
+A note written on a question you never answer still reaches the model, and a global note from the Submit tab covers the whole questionnaire:
+
+![Notes shown dimmed on their tabs and marked in the tab bar](./preview/popup-with-notes.webp)
+
 ## What it does
 
-- **Typed options, not a wall of prose.** Each question carries 2-4 authored
-  choices, and every choice explains what it means or what it costs you.
-- **You can always answer in your own words.** A `Type something.` row is
-  appended to every question and widens to the full pane while you type.
-- **Compare artifacts, not labels.** An option can carry a markdown `preview`
-  that renders in a bordered box beside the option list.
-- **One interruption, not five.** Up to four questions arrive in a single tabbed
-  dialog, and a Submit tab names anything still blank before you commit.
-- **Notes on any answer, or on all of them.** `n` opens a note editor on any
-  question tab, and on the Submit tab it writes one note covering everything.
-  A written note stays on its tab, dimmed, and the tab bar marks which tabs
-  carry one. A note on a question you never answer still reaches the model.
-- **Read the transcript behind it.** `Ctrl+]` collapses the dialog and brings it
-  back with your answers intact.
-- **A timeout that is not a decline.** Auto-dismiss returns a distinct
-  `timed_out` result, so the model never mistakes a clock for a refusal.
-- **Works outside the terminal.** RPC and ACP hosts such as Zed or the VS Code
-  pendant walk the host's native dialogs instead.
+- **Typed options, not a wall of prose.** Each question carries 2 to 4 authored choices, and every choice explains what it means or what it costs you.
+- **You can always answer in your own words.** A `Type something.` row is added to every question and widens to the full pane while you type. On a multi-select question it ticks itself the moment you type into it, and what you wrote is submitted alongside whatever boxes you ticked. Clear the text and the tick goes with it.
+- **Compare artifacts, not labels.** An option can carry a markdown `preview` that renders in a bordered box beside the option list.
+- **One interruption, not five.** Up to four questions arrive in a single tabbed dialog, and a Submit tab names anything still blank before you commit.
+- **Notes on any answer, or on all of them.** `n` opens a note editor on any question tab, and on the Submit tab it writes one note covering everything. A written note stays on its tab, dimmed, and the tab bar marks which tabs carry one. A note on a question you never answer still reaches the model as `unansweredNotes`.
+- **Read the transcript behind it.** `Ctrl+]` collapses the dialog and brings it back with your answers intact.
+- **A timeout that is not a decline.** Pass `timeout` in milliseconds and the dialog shows a live countdown. If it expires, the tool returns `cancelled: true` with `error: "timed_out"`, not a refusal. The model can retry or fall back to asking as plain text.
+- **Works outside the terminal.** RPC and ACP hosts such as Zed or the VS Code pendant walk the host's native dialogs instead.
+
+## Configuration
+
+Optional. Settings live in `pi-ask-popup.json`. Two layers, project overrides global:
+
+| Layer | Path | When it is read |
+| --- | --- | --- |
+| Global | `~/.pi/agent/pi-ask-popup.json` | Always |
+| Project | `<project>/.pi/pi-ask-popup.json` | Only when the workspace is trusted |
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| `collapseKey` | Key that collapses and expands the dialog. Accepts Pi keybinding ids such as `alt+o`. Use `"off"` to disable. | `"ctrl+]"` |
+| `guidance.description` | Full replacement for the tool description the model sees. | built-in description |
+| `guidance.promptSnippet` | One-line summary of the tool in the system prompt. | built-in snippet |
+| `guidance.promptGuidelines` | Usage guidelines given to the model, as a list of strings. | 5 built-in guidelines |
+
+Guidance is read from the global layer only. A checked-in file should not be able to change what the agent is told. `collapseKey` can be set per project.
+
+```json
+{
+  "collapseKey": "alt+o"
+}
+```
+
+A bad field is dropped back to its default without a warning. A whole file with bad JSON is ignored with a warning shown on the next tool call. See [Configuration](./docs/configuration.md) for the full grammar for `collapseKey`, file lookup, and how warnings are shown.
+
+## Reference
+
+- [Tool schema](./docs/tool-schema.md): params, limits, reserved labels, `timeout`, validation errors, the result shape, and the `pi-ask-popup:*` events.
+- [Keyboard and layout](./docs/keyboard.md): every key, the rows the dialog adds, notes, collapse mode, countdown, and how previews and overflow adapt to terminal size.
+- [Configuration](./docs/configuration.md): file lookup, the `collapseKey` grammar, the `guidance.*` prompt overrides, and how bad values are handled.
+- [Hosts and runtime behavior](./docs/hosts.md): terminal vs RPC vs non-interactive, what changes in each, and the `session_load_failed` and `stale_module_cache` cases.
 
 ## Requirements
 
 - Node.js 22 or newer
-- Pi Agent 0.80 or newer, with an interactive terminal or an RPC/ACP host
-- A terminal at least 100 columns wide for side-by-side previews
+- Pi Agent 0.80 or newer, with an interactive terminal or an RPC or ACP host. Non-interactive runs never see the tool.
+- A terminal at least 100 columns wide for side by side previews. Narrower terminals stack the preview under the options.
+
+## Troubleshooting
+
+**The model says the questionnaire UI failed to load and asks its questions as chat text.**
+
+The dialog modules were replaced on disk while Pi was running, usually by a package manager install that touched the store. Repair the install if it is broken, then restart Pi. See [Hosts](./docs/hosts.md) for `session_load_failed` and `stale_module_cache`.
+
+**`Ctrl+]` does nothing.**
+
+On layouts where `]` is on the shifted layer, like Latin American Spanish `es-AR` and `es-MX`, the default is unreachable. Set `collapseKey` to something you can type:
+
+```json
+{
+  "collapseKey": "alt+o"
+}
+```
+
+Or use `"off"` to disable the shortcut. The footer hint inside the dialog and the collapsed one-line hint both name whatever key you set.
+
+**Side by side preview never appears.**
 
-No runtime dependencies, no build step, no API keys. The extension makes no
-model calls of its own.
+Both the terminal and the dialog pane must be at least 100 columns wide. Below that the preview stacks under the options. The preview pane only appears for single-select questions.
 
-## Credits
+## How this relates to other packages
 
-Derived from [`@juicesharp/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question)
-by juicesharp, MIT licensed. This fork strips the `rpiv-config` and `rpiv-i18n`
-dependencies, targets Pi 0.80+, and adds a timeout.
+This is a fork of [`@juicesharp/rpiv-ask-user-question`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question) by juicesharp, MIT licensed. The fork removes the `rpiv-config` and `rpiv-i18n` dependencies, so there is no localization and no XDG config path. Config lives in `~/.pi/agent/pi-ask-popup.json` with a per-project override in `<project>/.pi/pi-ask-popup.json`, and only when the workspace is trusted. It targets Pi 0.80 and later, and it adds a `timeout` with a distinct `timed_out` result.
 
-If you want something smaller, [`pi-ask-user`](https://www.npmjs.com/package/pi-ask-user)
-by Enzo Lucchesi does a comparable job in a fraction of the code, with a
-searchable split-pane selector instead of tabs and previews. Pick whichever fits.
+If you want something smaller, [`pi-ask-user`](https://www.npmjs.com/package/pi-ask-user) by Enzo Lucchesi does a comparable job in far less code, with a searchable split-pane selector instead of tabs and previews. Pick whichever fits your setup. The README notes both so you can choose with full information.
 
 ## License
 

package/docs/configuration.md

@@ -0,0 +1,93 @@
+# Configuration
+
+Every setting this package reads, where the file lives, and what happens when a value is wrong.
+
+## The config file
+
+```text
+pi-ask-popup.json
+```
+
+The file is optional. With no config at all, every setting takes its default. This package only reads the file. It never creates, writes, or changes 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
+
+Two layers. The project layer overrides the global layer. Guidance merges per field, so a workspace can pin one line without restating the rest.
+
+| Layer | Path | When it is read |
+| --- | --- | --- |
+| Global | `~/.pi/agent/pi-ask-popup.json` | Always |
+| Project | `<project>/.pi/pi-ask-popup.json` | Only when the workspace is trusted |
+
+The global path follows `getAgentDir()` from Pi. If you set `PI_CODING_AGENT_DIR`, that directory is used instead of `~/.pi/agent`. `CONFIG_DIR_NAME` is `.pi`, so the project path is always `<project>/.pi/pi-ask-popup.json`.
+
+Project trust matters. Pi asks you to trust a checkout before it runs code from it. The project config is only read when `ctx.isProjectTrusted()` is true. An untrusted checkout cannot change your keyboard shortcut or rewrite the instructions the model sees. Guidance is stricter: it is read from the global layer only, even in a trusted project. Guidance is text that goes into the model prompt, and a checked-in file should not be able to change what the agent is told.
+
+If neither file exists, you get the defaults. That is the normal case, not an error.
+
+## When the file is invalid
+
+The loader never throws. It returns defaults and reports problems as warnings. The caller decides where warnings go. On RPC and JSON hosts the process is speaking a protocol on stdout, so a stray `console.warn` would break the stream. Warnings are shown with `ctx.ui.notify` on the first tool call instead.
+
+| Problem | What happens |
+| --- | --- |
+| File does not exist | No warning. No overrides. |
+| Cannot read the file (permission, is a directory) | Warning with the path and the system message. No overrides from that layer. |
+| Invalid JSON | Warning with the path and the parser message. No overrides from that layer. |
+| Valid JSON that is not an object (string, number, null, array) | Warning that the file is not an object. No overrides from that layer. |
+| A single field has the wrong type | That field is dropped and the built-in default stays. No warning. One bad field should not block the rest. |
+
+## 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. | built-in description |
+| `guidance.promptSnippet` | One-line summary of the tool in the system prompt. | built-in snippet |
+| `guidance.promptGuidelines` | List of usage guidelines given to the model. | 5 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
+
+```text
+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` through `f12`.
+
+Examples that work: `"ctrl+]"`, `"alt+o"`, `"ctrl+shift+h"`, `"f9"`, `"ctrl+}"`.
+
+Set `"off"` to disable the collapse shortcut. 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 `+` part as the key and discards unknown parts, so a typo like `"ctr+]"` would otherwise silently capture every bare `]` you type.
+
+The footer hint inside the dialog names whatever key you configure (`Alt+O to collapse` for `"alt+o"`), as does the collapsed one-line footer and the one-shot notification shown when the dialog is first hidden. With `"off"` the hint is removed.
+
+### `guidance.description`, `guidance.promptSnippet`, and `guidance.promptGuidelines`
+
+`guidance.description` replaces the entire built-in description Pi registers for the `ask_user_question` tool. There is no merging. It is used only when it is a non-empty string. Anything else falls back to the built-in default.
+
+`guidance.promptSnippet` and `guidance.promptGuidelines` replace the text Pi puts in the system prompt about when to use `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.
+
+Guidance is read once, when the extension registers the tool, so changes take effect on the next Pi restart. This is the same for `collapseKey`, but that key is resolved on each tool call so it can pick up the project override.

package/docs/hosts.md

@@ -0,0 +1,71 @@
+# Hosts and runtime behavior
+
+Where the questionnaire renders, what it falls back 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 or 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 sends one standard terminal BEL (`\x07`) just before the interactive wait begins. The signal goes to `stdout` only when `process.stdout.isTTY` is true, so redirected output and non-TTY RPC streams stay untouched. A TTY-backed RPC dialog walk receives the same signal as the TUI path.
+
+The BEL is best effort. If the synchronous write fails, the questionnaire continues and the existing prompt and blocked lifecycle and result shape are unchanged. Your terminal decides whether the BEL is audible, visual, or ignored. No BEL is sent for missing UI, invalid questionnaires, or a failed TUI session load.
+
+### Non-interactive runs
+
+A `before_agent_start` hook checks `ctx.hasUI` before every turn. When there is no UI, `ask_user_question` is removed from the tool list so the model never sees a tool it cannot use. When UI comes back, the tool is restored. The check is idempotent and leaves sibling tools alone.
+
+A second guard lives inside the tool handler. 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 protocol works there, but custom terminal UI does not render. The package catches this two ways: hosts that advertise `ctx.mode === "rpc"` go straight to the dialog walk and skip the TUI import, and older RPC builds are caught by a fallback when custom UI resolves without rendering. Either path needs the host to expose both `select` and `input`.
+
+The walk asks one question per dialog and returns the same result shape the TUI produces. Trade-offs that come with native dialogs:
+
+- 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 types, per-question `n` on a question tab and global `n` on the Submit tab, are terminal-only. The host's native `select` and `input` have 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 checked.
+- Closing any dialog cancels the whole questionnaire, the same as `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 to ask them as plain chat text instead. This is not a decline.
+
+### Timeout on any host
+
+`timeout` is part of the tool params and is passed through to the RPC walk as `dialogOpts.timeout`. The host is expected to dismiss the dialogs after that time. The TUI path runs its own countdown and shows the remaining seconds in the footer. In both cases expiry returns `cancelled: true` with `error: "timed_out"`, not a decline. See [Tool schema](./tool-schema.md).
+
+## Surfaces that depend on conditions
+
+Some parts of the dialog only appear when the conditions are right:
+
+| 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 at least 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 |
+| Countdown | `timeout` was passed and no keystroke has cancelled it |
+
+## Loading and startup cost
+
+The dialog's render graph costs about 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 keeps a process alive, and a failed pre-warm is ignored. The first real call tries again and reports correctly.
+
+The pre-warm exists for a specific failure. Pi's module loader registers a module in its graph cache before it runs, and does not remove it if running throws. If your package manager replaces the store while Pi is running, one failed import can poison the cache for the rest of the process. Running the graph early, while the paths Pi saw at boot still exist, keeps it in memory and avoids that.
+
+When it does happen, you get a structured result 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 cannot be fixed inside 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,65 @@
+# Keyboard and dialog layout
+
+Every key the questionnaire dialog reacts to, the rows it adds for you, and how it adapts to the size of your terminal.
+
+## Keys
+
+| Key | What it does | Where it applies |
+| --- | --- | --- |
+| `Up` / `Down` | 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 and previous tab, wrapping. `Right` / `Left` do the same. | Multi-question dialogs only |
+| `Space` | Toggle the focused checkbox. | Multi-select questions |
+| `n` | Open the notes editor for the focused question, or on the Submit tab the global note for the whole questionnaire. | Every question tab, and 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 with `collapseKey`. | Everywhere, including while collapsed |
+
+The table names the default keys. The dialog 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 setup where `Enter` is mapped to `tui.input.newLine` and submit moved to `Ctrl+Enter` still works: `Enter` breaks lines, and your submit key confirms everywhere `Enter` does.
+
+In a multi-select question, `Enter` on a regular row toggles its checkbox just like `Space`. It does not submit. Committing the question means focusing the `Next` row and pressing `Enter`. That is intentional: it makes `Enter` a cheap way to flip boxes without leaving the home row.
+
+`Space` is blocked on two rows: `Next` is a command, not a choice, and `Type something.` is a text input where the space character belongs to your answer.
+
+Timeout: if the call included a `timeout`, a live countdown shows in the footer and in the collapsed hint row, like `12s left`. The first keystroke you make cancels the timer. It does not reset, it stops.
+
+## The rows the dialog adds
+
+| Row | Label | Added 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.` turns 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 top and bottom of the draft. The draft replaces the static row label while you browse other options and is kept per question. `Ctrl+G` sends it through Pi's configured external editor and brings the result back. `Ctrl+U` clears it. `Esc` is the way to cancel the questionnaire. Confirming the row produces an answer of `kind: "custom"`.
+
+Both labels are reserved. The model cannot use them as option labels. The check always compares against the English strings.
+
+## Notes
+
+`n` opens a notes editor on any question tab, whether the question is single or multi-select and whether its options carry previews. Notes live 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 missing. The note joins 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 covers 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 kept.
+
+A note on a question you never answer is not lost. It is returned as `unansweredNotes` alongside `answers` and appears in the envelope as `note on "<question>": <text>.`
+
+## 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 shows the key to press. That message names your configured key.
+
+Because Pi sends no input to a hidden overlay, the collapse key is also 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 except cancel is ignored. You cannot change answers you cannot see.
+
+The default `Ctrl+]` is free in Terminal.app, iTerm2, Warp, tmux, zellij, and screen. On layouts where `]` sits on the shifted layer, like Latin American `es-AR` or `es-MX`, set a different `collapseKey` or `"off"` to disable it. See [Configuration](./configuration.md) and [Troubleshooting in the README](../README.md).
+
+## 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. This only happens when both the terminal and the dialog pane are at least 100 columns wide. Below that, the preview stacks under 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: `Up` for content above, `Down` for content below, `Both` for both. The exact markers are `↑`, `↓`, and `↕`.
+
+The footer hint line adapts to context. It drops the notes hint and adds the `Shift+Enter` newline hint whenever a text editor has focus, 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 idea: its bottom hint row sits below the picker and carries an `n to add a note` part that gives way to the `Shift+Enter` hint while the global note editor is open. A committed note shows as a `Note` entry in the review list. `Ctrl+G` is Pi's global external editor shortcut and is not repeated there. On narrow terminals the right edge clips with `…` so the main hints stay visible.

package/docs/tool-schema.md

@@ -0,0 +1,124 @@
+# Tool schema
+
+The full program surface of `ask_user_question`: what the model sends, what validation rejects, what comes back, and the event other extensions can listen to.
+
+## Parameters
+
+```ts
+ask_user_question({
+  questions: [
+    {
+      question: string,            // full question text, ends with "?"
+      header: string,              // chip label, max 16 chars
+      options: [
+        {
+          label: string,           // 1 to 5 words, max 60 chars
+          description: string,     // what the choice means or its trade-off
+          preview?: string,        // markdown rendered next to the options
+        },
+        // 2 to 4 options total
+      ],
+      multiSelect?: boolean,       // default false
+    },
+    // 1 to 4 questions total
+  ],
+  timeout?: number,                // ms, min 1000, auto-dismiss with countdown
+})
+```
+
+### Limits
+
+| Field | Constraint | Enforced by |
+| --- | --- | --- |
+| `questions` | 1 to 4 entries | TypeBox schema and `validateQuestionnaire` |
+| `questions[].header` | max 16 characters | TypeBox schema only |
+| `questions[].options` | 2 to 4 entries | TypeBox schema (both bounds) and `validateQuestionnaire` (minimum only) |
+| `options[].label` | max 60 characters | TypeBox schema only |
+| `options[].preview` | single-select questions only | tool description (multi-select tabs render checkbox rows) |
+| `timeout` | integer at least 1000 | TypeBox schema only |
+
+The two `maxLength` limits are checked by the param schema before `execute` runs. The runtime validator does not re-check them.
+
+### Timeout
+
+`timeout` is optional. When set, the dialog starts a live countdown shown in the footer and in the collapsed hint row. The first keystroke cancels the timer. If the countdown reaches zero, the questionnaire dismisses itself and returns `cancelled: true` with `error: "timed_out"`. This is not a decline. The model should retry or ask the same questions as plain chat text. A timed out result keeps the same `answers`, `globalNote`, and `unansweredNotes` the user had managed to leave behind, if any. No timeout means the dialog waits until the user acts.
+
+### Reserved option labels
+
+Using any of `"Other"`, `"Type something."`, or `"Next"` as an option label is rejected with `reserved_label`. The last two are the rows the dialog adds itself. `"Other"` is reserved because models are often primed to reach for it. Reservation is unconditional. A single-select question rejects `"Next"` even though that row is never added there.
+
+## Validation errors
+
+Every rejection returns `cancelled: true`, an empty `answers` array, and an `error` code. The `content[0].text` string is written for the model, not for a log.
+
+| `error` | Cause |
+| --- | --- |
+| `no_questions` | `questions` was empty |
+| `too_many_questions` | more than 4 questions in one call |
+| `duplicate_question` | two questions with identical text |
+| `empty_options` | a question carried fewer than 2 options |
+| `reserved_label` | an option used a reserved label |
+| `duplicate_option_label` | two options in one question share a label |
+| `no_ui` | the run has no UI (`ctx.hasUI === false`) |
+| `no_custom_ui` | the host cannot render custom UI and exposes no `select` or `input` dialogs |
+| `session_load_failed` | the dialog module failed to import (store changed on disk mid session) |
+| `stale_module_cache` | the loader cached a broken module after an earlier failed import. Needs a Pi restart |
+| `timed_out` | the `timeout` countdown expired before the user acted |
+
+`reserved_label` is checked before `duplicate_option_label`.
+
+## Result
+
+```ts
+{
+  content: [{ type: "text", text: string }], // envelope prose, or the decline message
+  details: {
+    answers: Array<{
+      questionIndex: number,
+      question: string,
+      kind: "option" | "custom" | "multi",
+      answer: string | null,       // option label, typed text, or null for multi
+      selected?: string[],         // chosen labels, multi-select only
+      notes?: string,              // free-text note, when you wrote one
+      preview?: string,            // echoed when the chosen option carried a preview
+    }>,
+    cancelled: boolean,
+    globalNote?: string,           // Submit-tab note. Present even when cancelled is true
+    unansweredNotes?: Array<{      // notes on questions that were never answered
+      questionIndex: number,
+      question: string,
+      note: string,
+    }>,
+    error?: QuestionnaireError,    // one of the codes above
+  }
+}
+```
+
+`globalNote` and `unansweredNotes` use a conditional spread. The key only appears when the value is non-empty. A result with no notes has no such key at all, so `!("globalNote" in result)` holds.
+
+### Envelope text
+
+On success the text reads `User has answered your questions: "<question>"="<answer>". … You can now continue with the user's answers in mind.` A chosen option's `preview` is added as `selected preview: <markdown>`, a per-question note as `user notes: <text>`, a note on an unanswered question as `note on "<question>": <text>.`, and the Submit tab's global note as a trailing `global note: <text>.` segment. A global note alone, or a single `unansweredNotes` entry alone, still yields the answered envelope. It counts as an answer even when every question is blank.
+
+Cancelling, and any result with no answer segments, no unanswered note segments, and no global note, both collapse to the single string `User declined to answer questions` so the model sees one clear signal. Partial submission is allowed: unanswered questions simply add no segment. A cancelled result always reads as the decline in text. Its notes, if any, survive only in `details.globalNote` and `details.unansweredNotes`.
+
+When `error` is `timed_out`, the text is `Questionnaire timed out, the user did not respond within the configured timeout. The user never saw a decline; do NOT treat this as a rejection. Ask the questions as plain chat text instead or retry.` The details keep `cancelled: true` and `error: "timed_out"` alongside any notes or answers the user left.
+
+## Events
+
+The package emits one event on Pi's event bus, after validation passes and before the dialog shows. Import it from the `./events` subpath:
+
+```ts
+import {
+  ASK_POPUP_PROMPT_EVENT,
+  ASK_POPUP_BLOCKED_EVENT,
+  type AskPopupPromptEventPayload,
+  type AskPopupBlockedEventPayload,
+} from "pi-ask-popup/events";
+```
+
+`ASK_POPUP_PROMPT_EVENT` channel is `pi-ask-popup:prompt`. Payload is `questions[].{ question, header, multiSelect, options[] }` where each option is `{ label, description, hasPreview }`. Preview content is not shipped, only `hasPreview: boolean`, so listeners that forward the event stay small.
+
+`ASK_POPUP_BLOCKED_EVENT` channel is `pi-ask-popup:blocked`. Payload is `{ blocked: boolean }`. It brackets the wait, true when the questionnaire starts and false when it resolves, so status or footer extensions can show that the agent is waiting.
+
+Both payloads are JSON-safe. Channel names are stable. Changes are append-only and optional, and any breaking change ships as a new channel rather than a version field.

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "pi-ask-popup",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension. A tabbed terminal questionnaire the model can put to you when it would otherwise guess, with typed options, markdown previews and notes instead of free-form replies.",
   "type": "module",
   "license": "MIT",
-  "author": "derangga <derangga1011@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/derangga/pi-extensions.git",
+    "directory": "packages/pi-ask-popup"
+  },
+  "homepage": "https://github.com/derangga/pi-extensions/tree/master/packages/pi-ask-popup#readme",
+  "bugs": {
+    "url": "https://github.com/derangga/pi-extensions/issues"
+  },
+  "author": "derangga <contact@rangga.site>",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -31,6 +40,7 @@
   "files": [
     "src/",
     "docs/",
+    "preview/",
     "README.md",
     "LICENSE"
   ],