DynamicDevices · ajlennon · Aug 5, 2026 · Aug 5, 2026
@@ -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

@@ -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).
 

@@ -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", … }`.

@@ -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`) |

@@ -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