diff --git a/README.md b/README.md index ceab523..f3f5b2b 100644 --- a/README.md +++ b/README.md @@ -87,10 +87,16 @@ Full env / prefs: [SETUP.md](SETUP.md). Never commit tokens. - Radiolist / checklist; recommended option first; options capped at **8** - Keyboard: **1–8** select · **Enter** OK · **Esc** cancel (footer hint; see [docs/AGENTS.md — Dialog UX](docs/AGENTS.md#dialog-ux-humans)) +- **Readable Confirm bodies:** first line (the ask) always fully visible; + Command / To+body / notes scroll underneath — so tall gates do not hide the + payload or push Cancel/OK off-screen +- Optional **image / images** preview in the dialog (Linux Gtk; click to + enlarge, **F** / header to maximize; primary monitor only) - Remembers last dialog size (`prefs.window`; position on Windows; size-only on typical Wayland) -- Windows: scrollable option list +- Windows: scrollable option list + same lead/detail Confirm layout - Danger chrome; OK/Enter briefly armed (~1s) +- Footer **Audio** checkbox (persistent) plus env mutes - Something else is always available (type, or Speak→STT when configured) - Works text-only without TTS/STT; lean JSON results by default - Optional TTS / mic answers / acks (auto-listen and acks **off** until opted in) @@ -100,6 +106,19 @@ Full env / prefs: [SETUP.md](SETUP.md). Never commit tokens. Packages & audio matrix: [DEPENDENCIES.md](DEPENDENCIES.md). +### Using the dialog (humans) + +You do not need the agent to explain the chrome — the footer shows hotkeys. + +1. Read the **first line** of the question (the ask). On dangerous prompts it + sits in a pink **Confirm** card. +2. If there is a **Command:** / **To:** / path block under it, that is the + payload — scroll inside the card if needed; Cancel/OK stay pinned. +3. Pick **1–8** (or click), then **Enter** once OK is armed (~1s). **Esc** + cancels. Uncheck **Audio** to mute TTS/STT for later dialogs. + +Full table: [Dialog UX (humans)](docs/AGENTS.md#dialog-ux-humans). + --- ## Tested platforms diff --git a/SETUP.md b/SETUP.md index 370100f..0a36c08 100644 --- a/SETUP.md +++ b/SETUP.md @@ -2,7 +2,9 @@ Deep dive for **MCP registration**, prefs, and **optional** TTS/STT. Dialogs work with no audio configured. For install + quick start, see -[README.md](README.md). Agent call contract: [docs/AGENTS.md](docs/AGENTS.md). +[README.md](README.md). How humans read the dialog (lead/detail, hotkeys, +Audio): [docs/AGENTS.md — Dialog UX](docs/AGENTS.md#dialog-ux-humans). Agent +call contract: same [docs/AGENTS.md](docs/AGENTS.md). **Voice backend detail (Qwen3-TTS + faster-whisper):** [docs/VOICE-BACKENDS.md](docs/VOICE-BACKENDS.md). diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 18baafc..913a842 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -46,9 +46,11 @@ skill via `ask-question-install --skill` (`~/.cursor/skills/ask-multiple-choice` - **`question`:** short colleague sentence by default. **Only when confirming content** (send message, ship doc, approve a draft) include the **referent** in `question` (To + body/excerpt, or path + what changes) — the dialog often - appears before chat. Do **not** paste process templates / PATTERN walls into - routine forks. No meta about dialogs or voice. Tall referents scroll inside - the body height cap. + appears before chat. **Readable-first:** put the decision ask on the **first + line**; put Command / To+body / path **before** meta notes. The dialog keeps + that lead fully visible; detail lines scroll under a height cap. Do **not** + paste process templates / PATTERN walls into routine forks. No meta about + dialogs or voice. - Mark recommended **only** in the option label (`Foo (recommended)`) **and** pass **`recommended_id`** / `recommended_ids`. Never put “Recommended: …” inside `question`. @@ -163,23 +165,37 @@ disable. Cancel / Escape always work immediately. ## Dialog UX (humans) Agents do not need to document these in `question` text — the dialog shows a -footer hint. Useful when coaching a human or writing host docs: +footer hint. Useful when coaching a human or writing host docs. + +### Keyboard / controls | Input | Behaviour | |-------|-----------| | **1–8** (top row or keypad) | Select that option (1-based). Labels show `1 · …`. Multi-select **toggles**. Ignored while the Something else entry is focused. | | **Enter** | Confirm OK after the arm delay (same as clicking OK). | | **Esc** / window close | Cancel. | +| **Audio** (footer checkbox) | Persistent mute for TTS/STT (`prefs.audio_enabled`). Env `ASK_QUESTION_AUDIO=0` also mutes. | | **R** / **L** | Replay question / Listen (Linux voice only, when configured). | | **Click preview** (image MCQs) | Toggle large vs compact (~320px) image scale. | | **F** / header maximize (image MCQs) | Maximize / restore the window so the still can use most of the screen. | -Long `question` text is shown in a calm Confirm **card** when `dangerous` -(soft pink, title + body). The **first line** (decision ask) stays fully -visible; remaining lines (command / To+body / meta) height-cap with an inner -scrollbar so tall self-contained referents cannot push Cancel/OK off-screen. -Dense ` · `-separated fields become separate lines. Option rows stay in the -middle scroll. +### Reading the question (lead + detail) + +Multi-line `question` text (and dense ` · `-separated fields, which become +separate lines) uses a **lead / detail** layout on Linux and Windows: + +1. **Lead** — the first non-empty line (the decision ask) stays **fully + visible** — never clipped under the pink border or options. +2. **Detail** — remaining lines (Command / To+body / path / notes) sit under a + height cap with an inner scrollbar when tall, so Cancel/OK stay on-screen. + +When `dangerous=true`, the lead+detail sit in a calm pink **Confirm** card +(title **Confirm** + body). Normal MCQs use the same lead/detail split without +the pink chrome. Option rows stay in the middle scroll. + +**Authors:** put the ask first; put the referent (command, To+body, path) +before meta notes such as “not a policy decision” — otherwise the human sees +chrome and has to scroll for the payload. Size (and on Windows, position) is remembered in `~/.config/ask-question-mcp/prefs.json` under `"window": { "w", "h", … }`. diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md index f5e43fb..c1db673 100644 --- a/docs/WINDOWS.md +++ b/docs/WINDOWS.md @@ -25,7 +25,8 @@ Canonical install steps: this file (and a one-line pointer from the should submit as Something else (digits while typing go to the entry, not options). 9. Smoke **dangerous** — ask for an irreversible choice (`dangerous=true`). Expect: - Window title / options prefixed with **⛔** (no-entry) - - Pink **Confirm** banner with the question + - Pink **Confirm** banner; **first line** (ask) fully visible; extra lines + (e.g. `Command: …`) under it, scrollable if tall - Red **OK** that stays disabled ~1s (`OK (Ns)`) before confirm 10. Resize the dialog, OK, reopen — size (and position) should roughly match. 11. When nudged for platform feedback: choose **works** (or open a GitHub issue) so @@ -42,9 +43,11 @@ Shared path (`zenity_ask` → `win_list_ask.py`): | --- | --- | | Something else always offered | Yes (same as Linux; `allow_other` ignored) | | Danger mark **⛔** + confirm arm | Yes (`danger_arm.py`) | -| Danger banner wording | **⛔ Confirm** + question (pink banner) | +| Danger banner wording | **⛔ Confirm** + lead ask (pink banner) | +| Lead / detail (ask visible; tall referent scrolls) | Yes (`split_lead_detail`) | | Red OK on danger | Yes | | Voice / duck / STT | No (text-only) | +| Image / images preview | No (ignored; text-only) | | Gtk footer / scroll layout fixes | N/A (tkinter layout) | | 1–8 hotkeys + Enter / Esc | Yes | | Remember size/position | Yes (`prefs.window`) | diff --git a/skills/ask-multiple-choice/SKILL.md b/skills/ask-multiple-choice/SKILL.md index efeab47..f5df775 100644 --- a/skills/ask-multiple-choice/SKILL.md +++ b/skills/ask-multiple-choice/SKILL.md @@ -23,6 +23,8 @@ choose among options the human must decide. 3. **`question`:** short colleague sentence by default. **Only when confirming content** (send/ship/approve a draft) put the **referent** in `question` (To + body, or path + what changes) — dialog often appears before chat. + **Readable-first** (`mcq-question-readable-first`): lead line = the ask + (always fully visible); put Command/To+body/path **before** meta notes. Do **not** dump process templates, PATTERN blocks, or long meta into routine forks. No meta about dialogs/voice. 4. **Permission / action asks (Alex 2026-07-30):** state **what** Briar will do