Hex Feature Map¶

Hex                                      // macOS release
├── Get ready                            // install, permissions, local model
├── Dictate                              // hold OR double-tap lock
├── Use the result                       // paste, paste-last, History
├── Adjust behavior                      // shortcut, microphone, recording preferences
├── Process text                         // Output tab + context-selected Modes
├── Opt in                               // Meetings: off by default
├── Recover                              // prove the next attempt works
└── Maintain the app                     // menu bar, login, updates, quit

Download Hex                              // setup.download-recovery
├── anoma.ly/hex names the visitor's platform  // setup.download-button
│   ├── Mac -> DMG | Intel Mac -> disabled, "needs Apple silicon"
│   ├── Windows x64 / ARM64 (UA-CH) -> hex-setup-<version>-windows-<arch>.exe + SmartScreen note
│   ├── Linux -> copyable `curl … install-linux.sh | sh` + Arch/glibc requirement
│   ├── Phone -> Send yourself the link
│   └── Other platforms -> every build, Homebrew, the GitHub release
├── Website, README, installers, apps, feeds, appcast -> anoma.ly/hex/files -> R2 bytes (Worker hex-production-site)
├── Releases up to 2.3.1 -> downloads.hex.kitlangton.dev (Kit's frozen bucket) -> the same bytes
├── GitHub v<version> (app-v through 2.3.1) -> identical DMG, Setup.exe, and Linux bytes
└── Older app cannot reach its update feed -> manually install the DMG

Install on Windows                        // setup.windows-installer
├── Setup.exe, per user, no admin -> managed versions\<version>\hex.exe
│   ├── x64 without a Vulkan 1.2 driver -> installs; speech on the CPU + Settings note (#1240)
│   ├── another version installed (e.g. self-updated) -> install this one over it
│   └── finish -> Open Hex -> the first run downloads a model
└── Settings › Apps -> uninstall every version, shortcut, Launch at login; keep data

Install on Linux                          // setup.linux-installer
└── curl … | sh -> signed feed -> verified artifact -> launcher + hex.service
    └── cannot start -> name the glibc floor or the missing Arch packages

Prepare local models                      // separate network dependency
└── Dictation -> huggingface.co and its download CDN
    └── Transfer fails -> host-specific guidance -> restore access -> Retry

Launch Hex, setup incomplete              // setup.tour; every build and OS, full window
├── One onboarding: the first-run story (rune_ui/onboarding_kit/live.rs) over
│   the tour state machine (desktop::onboarding::Flow); no flag, no other tour
├── Skip (quiet, top-right, only on the demo and the practice)    // setup.skip
│   ├── Passes over that part to the next step setup still needs: permissions,
│   │   then Almost ready while the model downloads, else Hex is ready
│   ├── Never closes onboarding or records it done
│   └── No Skip on permissions, the model step or download, or the paste
│       permission. Check: `onboarding_skip` (scripts/check-onboarding.sh)
├── GNOME/KDE Wayland (pastes through the RemoteDesktop portal, no wtype)
│   and no saved grant -> before Your turn, "Let Hex paste for you"     // setup.paste-access
│   ├── Says why: Hex only sends the paste keystroke, never sees the screen;
│   │   the desktop asks once and may call it remote desktop (#932)
│   ├── Allow -> opens the desktop's dialog; the grant's restore token is saved,
│   │   so the first paste needs no dialog
│   ├── Refused -> Try again, or Continue (the desktop asks at the first paste)
│   ├── X11, wlroots with wtype, macOS, Windows -> no page
│   └── Skipped or refused -> Settings › General shows it under "Permissions
│       needed" until allowed. Check: golden `onboarding-paste`; the real
│       portal dialog is not exercised
├── 2.3.1 or Swift Hex -> Sparkle offers the new Hex -> Install Update   // setup.legacy-update; macOS
│   ├── Replaces the old app in place (its file name kept) and opens the new one
│   ├── Accepted only because app/Info.plist keeps the old SUPublicEDKey;
│   │   scripts/validate-app.sh requires it. Feed items: docs/plans/swift-app-handoff.md
│   └── No automated check; a clean-Mac install from each old app is the proof
├── 2.3.1 Linux or Windows updates into this build     // setup.legacy-adopt
│   ├── It lands in <data>/voice-control/versions/<version>; its first app or
│   │   `service` launch from there moves it into the managed layout, then
│   │   relaunches from it (Linux: exec, so the old unit keeps its process)
│   ├── Linux -> 2.3.1's marked unit, ~/.local/bin/hex link, and hex.desktop
│   │   entries move aside -> the built-in .github/release/install-linux.sh
│   │   installs this executable -> session.env copied; failure puts them back
│   ├── Windows -> %APPDATA%\hex\versions, receipt, Hex.lnk recreated,
│   │   Launch at login repointed, 2.3.1's Apps & Features entry removed
│   ├── Failure -> logged, runs in place; the next launch tries again
│   ├── Settings, history, and models in voice-control are not carried over
│   └── Check: `a_legacy_linux_install_moves_into_the_installers_layout`,
│       `a_failed_move_puts_the_legacy_files_back`; Windows and a real 2.3.1
│       feed update are unverified
├── Upgrading from 2.3.1 or earlier (same `hex` folder)     // setup.upgrade; macOS
│   ├── `anomaly.hex` is a new identity: macOS kept none of the old grants
│   ├── Settings without `anomaly-hex-identity` in `migrations` -> checked once at launch
│   │   ├── Permissions or the selected model not ready -> the old completion
│   │   │   no longer counts -> onboarding opens from the start
│   │   └── Everything ready -> no onboarding; nothing but the ID changes
│   ├── Saved settings are kept; the ID is recorded either way
│   └── Setup ready, listener starting -> a running 2.3.1 or Swift Hex   // setup.quit-legacy
│       (retired bundle IDs) is asked to quit, so both never answer Option;
│       it stays installed. No check; `macos_rune::quit_legacy_hex`
├── Setting up Hex -> speech model download starts at once  // setup.background-download
│   ├── Model -> the selection recommended for the system's first preferred
│   │            language (English -> Parakeet Unified English; e.g. French ->
│   │            Parakeet v3, Japanese -> Qwen3-ASR); the language capsule
│   │            switches between English and that language
│   ├── The download is held while the Hugging Face scan runs (headers only)
│   ├── Models found here -> the model step instead      // setup.found-choice
│   │   ├── "Choose a speech model": one list, ours first and selected, then the
│   │   │   found files; a pick starts at once (ours downloads, a found one is
│   │   │   checked and used in place); Continue starts the selected row
│   │   ├── A found pick moves on with no download page or pill
│   │   └── Back on the pages after it returns to the list to change the pick
│   ├── Nothing found -> this page as always, the recommended model downloading
│   ├── Progress moves to the top pill once the story moves on; failure ->
│   │   why, in one line (a proxy or certificate, #894), + Use a model
│   │   file… + Try again
│   ├── Failed, or stalled 30 s without bytes, with every permission ready
│   │   -> Continue without a model (quiet), saying dictation won't work
│   │   until a model is added with Add model file…      // setup.without-model
│   │   └── Records completion and closes onboarding; Settings › General's
│   │       Speech model row says no model is installed (with the download's
│   │       error), + Download + Add model file…. Check: golden
│   │       `onboarding-no-model`, `onboarding_continue_without_model`
│   └── Change or delete the model later in Settings      // setup.delete-model
├── The demo: Without Hex (typed, with typos) -> With Hex (spoken) -> Continue
├── Quit part-way -> next launch resumes at the saved step  // setup.resume
│   └── Permissions are read again at launch: a setup they now finish (macOS's
│       Quit & Reopen after a grant) is passed; past setup, it waits until they do
├── Permissions                           // setup.checklist; skipped when granted
│   ├── macOS: "Let Hex hear you and type for you", Microphone and Accessibility
│   │   ├── No Input Monitoring row: Accessibility also lets the shortcut taps listen
│   │   ├── Microphone -> macOS prompt; refused -> "Open System Settings" + guide
│   │   ├── Accessibility -> Privacy pane + drag guide
│   │   │   ├── Retired Hex bundle IDs (`com.kitlangton.hex2`, `com.kitlangton.Hex`,
│   │   │   │   `com.kitlangton.Hex.debug`) cleared once in the background (`tccutil reset`,
│   │   │   │   ignoring `OSStatus -10814` when no bundle is on disk)
│   │   │   ├── Returned from System Settings still untrusted (2 s, or 6 s side-by-side) ->
│   │   │   │   "An older Hex entry can keep this off" + "Still grey? Fix it"
│   │   │   │   -> resets the running bundle ID + retired IDs, prompts, and reopens the guide
│   │   │   └── macOS 27 names the list "Device Control and Data Access"; the row follows
│   │   ├── On in System Settings, unusable until relaunch -> "Needs a restart"
│   │   │   └── Every permission on -> "Restart Hex" -> relaunch at setup  // setup.restart
│   │   └── Last grant -> 0.7 s beat -> the story moves on
│   ├── Windows: only while the microphone privacy switch is off: "Let Hex hear
│   │   you", one Microphone row -> Open Settings (ms-settings:privacy-microphone)
│   └── Linux: no page
├── Almost ready: the model still downloads -> waits, then Your turn
├── Your turn: the practice game          // setup.practice; every OS
│   ├── "Clear your messages": hold the saved shortcut and answer the lit card;
│   │   Hex's own dictation (macOS listener, Linux and Windows event log) holds
│   │   the keys, flies the live words, and lightning burns the answered card
│   ├── A short, silent, or failed try -> a hint under the field
│   └── Done at any time -> Hex is ready  // practice is never required
├── Listener cannot start after setup     // setup.relaunch; event tap refused
│   ├── First time -> Hex records a marker, reopens itself, resumes at the practice
│   └── Within 2 min of that relaunch -> "Hex's shortcut didn't start." + Reopen Hex
└── Hex is ready -> where Hex lives (menu bar, system tray, or app launcher)
    ├── Try again -> back to the practice game
    └── Start using Hex -> records completion once setup is ready; closes onboarding
Run setup again (Labs) or `hex onboarding reset` -> the same story from the start,
on every build; settings, models, and permissions stay, so their pages pass

Observed on macOS 26.6.2 and macOS 27.0 VMs (2026-10-31, SIP enabled): unprivileged
`/usr/bin/tccutil reset` from inside `anomaly.hex` clears `Accessibility`,
`ScreenCapture`, and `AudioCapture` entries for retired Hex bundles on disk with
no password prompt (`rc=64` / `OSStatus -10814` when absent from disk), and
resetting `anomaly.hex` followed by `AXIsProcessTrustedWithOptions` /
`CGRequestScreenCaptureAccess` replaces a stale `CDHash` entry that stayed grey
or untrusted in System Settings. Checks:
`tccutil_exit_codes_distinguish_cleared_absent_and_failed_bundles`,
`stale_tracker_waits_for_return_from_system_settings_and_ignores_touch_id_focus`,
`stale_accessibility_row_resets_permission_and_returns_to_waiting` in
[desktop/onboarding.rs](https://atomgit.com/GitHub_Trending/hex19/hex/blob/dev/src/desktop/onboarding.rs), and
`stale_permissions_offer_fix_it_and_reset_entries_across_panes` in
[rune_ui/tests/panes.rs](https://atomgit.com/GitHub_Trending/hex19/hex/blob/dev/src/rune_ui/tests/panes.rs). Scenes:
`mac-onboarding-stale`, `mac-settings-permissions-stale`.

Apple silicon, macOS 15+. Choices come from the compiled model/language catalog;
Apple Speech is currently excluded from the desktop picker.

```ts
General > Dictation > Speech model, then Language below it   // setup.language-select; every desktop root
├── Speech model -> Picker: Compare, then every model; never changes the language
│   ├── Compare -> "Speech model for Japanese": three columns from the saved
│   │   language's models, recommendations first; "{n} more models" -> every model
│   ├── Every model -> the saved language's models, Your model files, then a fold
│   │   "{n} more that don't speak Japanese"
│   ├── Model without the saved language -> Row: "Choosing it switches the
│   │   language to English"
│   └── Choose it -> ChooseModel(model, model's default: English, else its first)
│       └── Saved -> Language row: "<Model> doesn't support Japanese, so the
│           language changed to English" until the next choice
├── Language -> Select of the saved model's languages (catalog order, Auto first
│   when it detects); one language -> the field shows it, disabled
│   └── Choose -> ChooseModel(same model, language): the same preparation as a
│       model choice, so per-language assets (Apple Speech locales) install
└── The saved TranscriptionSelection is always a pair the model supports

Choose a supported language              // setup.language-conditioning; macOS + Linux picker
├── Parakeet v3 -> Detect language from audio; selected language does not constrain output
├── Granite Speech 5.0 -> No language input; transcribes whichever of en, fr,
│   de, es, pt, it, ja it hears (#1252)
├── Whisper -> Use selected language to guide decoding; accuracy is not guaranteed
├── Whisper (ivrit.ai's and NB-Whisper too), Qwen3-ASR 0.6B, QwenCleo-ASR 1.7B -> Vocabulary ->
│   context prompt (vocabulary.md); output that only repeats it is dropped
├── Hebrew -> ivrit.ai Whisper large-v3-turbo, always with the `he` hint (it
│   lost Whisper's language detection); stock Whisper turbo also offers it
├── Russian -> GigaAM v3 (Russian only, no language input); Parakeet v3 and
│   Whisper turbo also offer it
├── Norwegian -> NB-Whisper Medium, always with the `no` hint (Bokmål is all
│   Hex measured); stock Whisper turbo also offers it (#1150)
└── Bangla -> Whisper only, with the `bn` hint; Auto lets Whisper guess per clip

Settings picker > Compare                 // setup.model-card; shared by every desktop root
├── Column head -> Role (Recommended, Fewest wrong words, Fastest, Most languages,
│   Reads your vocabulary; from the catalog for the saved language), name, one-line blurb
├── Rows -> Wait when you stop (30 s ÷ realtime; "None" when it streams), Wrong
│   words or characters "1 in N" (benchmark in the saved language, else "Not
│   measured"; row hidden when none is measured), Languages, Reads your vocabulary,
│   Download size; one strictly best value is medium weight, ties get none
├── Action cell -> exactly one: In use dot, progress with Cancel, Use, or
│   Download <size>; Primary only on the recommended column when it can be chosen
├── The model in use or preparing replaces the last column when it would be left out
└── "{n} more models" -> Every model

Settings picker > Every model row          // fixed height; scrolls
├── Name, role, blurb, then "No wait · 1 in 50 words wrong · 25 languages · 2.5 GB"
├── Saved language unsupported -> Warning line naming the language it switches to
├── Trailing edge -> In use dot; progress with Cancel; else Use/Download; Delete when downloaded
├── Labs > Benchmark details (off) -> raw error rate "7.57% CER", a wrapping line:
│   language · dataset/split · source · conditions or "unknown" ·
│   speed qualified; "Most accurate" only between comparable records (labs.md)
├── Labs > Parakeet Ultra (off) -> its row with a Labs tag and Details: languages,  // setup.parakeet-ultra
│   measured memory, the CC BY 4.0 credit, notice, Source/License links, folded
│   published benchmarks "not measured in Hex" (labs.md)
├── "Add model file…" in the header -> imported cards after the catalog:  // setup.custom-models
│   Imported · family · languages · Not benchmarked · file · licence · SHA-256
│   prefix; Rename, Remove (not the active
│   model); missing or changed -> warning line and no Use (own-models.md)
└── Found on this computer -> a scan of the Hugging Face cache when the picker  // setup.found-models
    opens: other compatible files at the top (Not tested by Hex, Use); a catalog
    model already downloaded there says so and offers Use; a found file's
    Delete is Forget (own-models.md)

Menu bar > Speech Model                   // setup.quick-model-switch; macOS
├── Downloaded models -> Last selected language shown beside each model
├── Choose -> Verify installed artifact -> Prewarm -> Save selection
│   ├── Success -> Checkmark moves; Settings reflects the saved selection
│   └── Failure -> Previous selection remains; open Settings for the error
├── Preparing -> Cancel Model Switch      // never cancels dictation/output jobs
└── Manage Models… -> Settings picker      // downloads; languages in the Language row

Labs > Switch model with keyboard language      // setup.input-source-model; macOS, Windows, Linux X11; off by default; General shows the mappings while on
├── Each enabled keyboard input source -> Don't switch, or a downloaded model and language
│   ├── New mapping -> The source's own language when the model has it
│   ├── One-language model -> Its language shown fixed
│   └── New/unmapped source -> Don't switch; keep the current model
├── Source changes (shortcut, Input menu, automatic app/document switch)
│   └── 300 ms after the last change -> Existing installed-only picker preparation
│       ├── Same model and language already selected -> Nothing loads
│       ├── Success -> Save the selection, keeping the model's remembered hints
│       └── Failure -> Existing picker error; no download or guessed fallback
├── Manual model choice -> Supersede pending automatic work; do not reapply at recording start
├── Enable -> Apply the current source's mapping once it is observed
├── Edit the active mapping -> Apply now
├── Disable -> Cancel automatic work; stop observing; leave the selected model alone
└── Relaunch -> Observe current source without applying it; preserve the manual choice

Settings picker > Every model > Downloaded row   // setup.delete-model; macOS
├── Delete -> "Delete <size>?" -> Delete again
│   ├── Success -> Model file, receipt, and partial download removed; row offers Download
│   └── Download in progress -> Nothing removed; "Model could not be deleted." with reason
├── Selected dictation model (any language) -> No Delete
├── Preparing or Apple Speech model -> No Delete
├── Model choice or closing the picker -> Confirmation cleared
└── Labs > Downloaded models only (off) -> "Downloaded models take <size>" (Hex's own   // labs.picker-downloaded
    files) + "Only downloaded models", which leaves just the downloaded rows, each
    with its Delete; reset when the picker opens (labs.md, #1018)

Saved shortcut                           // dictation; Option by default; Windows and X11 accept mouse buttons, macOS with Labs > Mouse shortcuts
├── Hold -> Speak -> Release
├── Tap, tap -> Speak hands-free -> Press again   // Shortcut mode: Hold or double-tap
├── Tap mode (Toggle) -> Cancel shortcut, Escape by default, while recording
│   -> Discarded: nothing pasted or saved; transcribing jobs finish (#1022)
├── Hold modes -> no cancel: Escape reaches the app, every dictation pastes (#786)
└── macOS recorder: a key alone needs a modifier, except F1–F20 and Home, End,
    Page Up, Page Down, Help (#1138; keys_without_modifiers_need_one_except_function_keys)

General > Shortcut mode -> Hold or double-tap (default), Hold, Tap, Double-tap
  -> Modal: each choice with its keys and a looping key/recording timeline
  -> Double-tap needs a key binding; with a lone modifier it says so

Labs > Second dictation shortcut (macOS, off)   // labs.md; issue 627
  -> General shows "Second dictation shortcut" under Shortcut (unbound, clearable)
  -> it dictates like the shortcut: Hold/Toggle, double-tap lock, release
  -> the shortcut that starts a capture finishes it; the other stands down meanwhile

Labs > Unload model when idle (off; 5/15/30/60 min, default 15)   // labs.md; transcription/engine
  -> nothing used the model that long and nothing records -> the model unloads
  -> next press, meeting chunk, or API request -> reloads first; audio waits, nothing lost

Completed output                         // output
├── Paste -> Current focus, in submission order
│   ├── Previous clipboard restored 500 ms later, unless something newer replaced it
│   ├── Windows -> the transcript is marked out of clipboard history (Win+V) and cloud sync (#851)
│   ├── Labs > Keep dictation on clipboard (macOS, off) -> the dictation stays on the clipboard (labs.md)
│   └── Labs > Copy dictation only (macOS, off) -> clipboard only: no paste, typing, or restore (labs.md)
├── Paste Last Dictation                  // menu or Option-Shift-V / saved binding
│   ├── Last completed dictation
│   └── macOS menu item shows the saved binding (⌥⇧V by default); unbound,
│       modifier-only, or a mouse button -> no shortcut shown
└── History
    ├── Inspect / search / copy (row hover or the card) / delete
    ├── Retention ("Kept 7 days ▾" menu) -> Seven days by default, always hard-capped
    ├── Off ("History off") -> Stop new entries; preserve existing entries
    ├── Same menu > Clear all history… -> asks in the header; only the red confirm clears
    └── Labs > Keep recordings (off) -> new entries keep their 16 kHz audio   // labs.keep-recordings
        -> also "Keep audio too" in the retention menu while the lab is offered
        -> the card's "Transcribe again" menu runs it through any installed model
        -> the new text with Copy and Replace; Clear all and retention delete the audio (labs.md, #1032)
        -> Replace keeps the old text as one of 5 earlier versions: Copy, Use this version (#1177)
Every entry since #1177 -> "Speech model" fact: the model that made its text (+ language when chosen)

Sidebar                                  // settings.nav
├── General, Output, History, then each feature that is on: Meetings and
│   Voice Filter (Labs toggles), Annotate, Playground (Labs, an item)
└── Labs -> a store of unfinished features, each off by default: search, categories, cards with their own settings inline; hex://labs/<feature> opens its group (labs.md)
    // Command-1…9 follow the panes' order (labs::order)

General                                  // settings
├── Basics card -> Shortcut, Speech model, Language, Microphone, Launch at login
│   ├── Each row leads with an icon; choices are inline dropdowns, not segments
│   ├── Language -> fixed text for a one-language model, else a dropdown
│   └── A row that hides or shows (Advanced, a microphone error)
│       -> Folds under a clip as the rows below slide over it; no fade in place
├── Microphone -> Value names the input in use, with live level bars // settings.microphone
│   ├── "System default · Kit Pods", or a saved device
│   ├── Level bars -> peak of the audio Hex receives, ~30 fps while General shows them above rest // input_level
│   │   ├── Read from one atomic the audio owner stores per chunk; never opens or blocks the mic
│   │   ├── Quiet room (bars at rest) -> no 30 fps frames; the window's 250 ms tick notices a rise.
│   │   │   An open General window with a warm mic woke 34.5 times a second in a quiet room before
│   │   │   (dev-364, headless sway on apollo, Oct 31) and 4.1 after; macOS was reasoned about only
│   │   ├── No audio for 250 ms (released while idle, failed, not allowed) -> flat, dimmed
│   │   └── Scenes: mac-settings-mic-level (a recorded WAV, `--video`), mac-settings-mic-released
│   │       // check: the_microphone_level_follows_the_voice (Linux)
│   ├── Re-listed on a device or default change while General shows (Windows: also every 3 s)
│   ├── System default -> The OS default input, followed live
│   │   ├── Default changes -> Switch once capture is idle; new stream opens before the old drops
│   │   ├── Default is Hex Microphone -> Built-in mic, else first real input; row says so
│   │   ├── Stand-ins never include virtual or aggregate inputs (macOS: e.g. Microsoft Teams Audio)
│   │   │   ├── Nothing real left -> "lid is closed" / "no microphone" error, not silence
│   │   │   └── A virtual default, saved device, or `--device` is still used as named
│   │   └── Default is Bluetooth (Advanced switch on) -> Built-in mic, else first wired/USB input
│   │       ├── Row says "KIT PODS is Bluetooth, so Hex listens to MacBook Pro Microphone"
│   │       ├── Windows: WASAPI `BTHENUM`, or a headset/handset endpoint of unknown bus (`BTHHFENUM`)
│   │       ├── Linux: a `bluez5` default source; Hex opens ALSA's default, then moves its own
│   │       │   stream to the PCI input, else the first other hardware source (pactl, PipeWire);
│   │       │   the stream is marked so WirePlumber never remembers the move. A Bluetooth
│   │       │   default chosen while Hex's stream is open is followed until the next open
│   │       ├── No other usable input (or lid closed, Bluetooth only) -> the Bluetooth default
│   │       ├── A saved Bluetooth mic or `--device` is always used as named
│   │       └── Dictation only: meeting recording keeps the Bluetooth default, which
│   │           a call app on the headset is using (#1086;
│   │           a_meeting_keeps_the_bluetooth_default_a_call_uses)
│   ├── Saved device missing -> System default stands in, value names it
│   │   ├── Row says "SHURE MV7 isn't connected; using your Mac's input"
│   │   ├── Menu keeps "SHURE MV7" checked with a faint "not connected"
│   │   └── Device returns -> Switch back once idle; the setting never changes
│   ├── Menu lists real inputs only                                // never Hex Microphone
│   └── Open menu covers the controls beneath it; click elsewhere dismisses
├── Advanced ▸ -> one fold per pane, closed by default, even while a setting in it is in use
│   ├── Collapse -> drops a pending release confirmation
│   ├── Dictation -> Shortcut side, keyboard-language mappings (while its Labs toggle is on),
│   │   Use the Mac's microphone instead of Bluetooth (Linux, Windows: "Use another
│   │   microphone instead of Bluetooth")
│   ├── Output -> Paste last shortcut, While dictating, Dictation HUD, Terminal paste (Linux)
│   │   (Dictate without processing sits in the Output pane; see dictation.md)
│   └── Application -> Enable on launch, Show Dock icon, Sound volume, Sounds,
│       Interface language, Update channel (self-updating installs)
│       // Interface language System: macOS's first preferred language (zh-Hans -> 简体中文,
│       // zh-Hant, zh-TW, zh-HK, zh-MO -> 繁體中文), Linux LC_ALL/LC_MESSAGES/LANG
│       // (zh_TW.UTF-8 -> 繁體中文), Windows the user locale; unknown -> English
│       // Text language (rune::text::set_language): 日本語 -> ja, 简体中文 -> zh-Hans,
│       // 繁體中文 -> zh-Hant (zh-HK in Hong Kong/Macau); another interface on a
│       // ja/ko/zh system locale -> that locale. Han text falls back to its fonts
│       // (Hiragino Sans, Yu Gothic, Noto Sans CJK JP for ja) and shapes with its
│       // locl forms (#1382)
├── Use the Mac's / another microphone instead of Bluetooth (Advanced, on)
│   └── Off -> System default follows a Bluetooth default too; re-resolves once idle
├── Labs > Share dictation shortcut with other apps (Windows, off)
│   └── On -> the hook passes the shortcut's key-down/up on instead of consuming it
├── Terminal paste (Advanced on Linux, Labs on Windows; off)
│   └── On -> paste sends Ctrl+Shift+V instead of Ctrl+V; applies to the next paste
├── Turn off the mic when not dictating (General, under Microphone; off)   // release_microphone_while_idle
│   ├── One switch, no confirmation; its line says what the state means (issue 61), on every OS
│   ├── Off (default) -> "The mic stays ready so dictation starts instantly; your system shows it in use"
│   │   Open while idle; pre-roll available
│   └── On -> "The mic opens only while you dictate; the first moment can be clipped"
│       Open on press; no pre-roll; startup delay
├── While dictating -> Mute / Pause media / Lower audio / Do nothing
│   ├── Lower audio -> Lower to slider, 0–100% of the previous volume (default 20%)
│   ├── Intentional capture only, not ordinary shortcut chords
│   ├── Pause/resume only players already reported running by macOS
│   ├── Linux restore -> Waits 300 ms; a new capture keeps it suppressed // double-tap lock
│   └── Labs > Also pause the browser (macOS, Pause media only; off by default); its permission row shows here while on
│       ├── Turning it on without System Audio Recording -> ask now, never while dictating
│       ├── On -> Screen & System Audio Recording row: Allow / waiting / Allowed
│       └── Dictation -> browser_media sequence below
├── Sound volume -> immediate feedback; zero suppresses tones
│   └── Default output changes or disappears (macOS) -> next tone reopens on the current default
├── Sounds -> Sheet: hear each set on Hex's real HUD, pick one
└── Linux / Windows -> listener card and desktop commands below the basics

Pause media + Also pause the browser     // browser_media
├── A browser uses the microphone (a call) -> leave it alone
├── No browser process has its audio output open -> leave it alone (no tap)
├── Listen to those processes' own output (private process tap), 3 windows of 100 ms
│   └── Any window at or below -60 dBFS, or no level -> leave it alone
├── Send the system pause command (MediaRemote 1; never the toggle)
├── Poll 5 windows of 100 ms
│   ├── 2 windows in a row below -90 dBFS -> Hex paused it
│   └── Otherwise (another tab, a sound that ended later, or the pause went elsewhere) -> no play later
└── Dictation ends and Hex paused it -> first, before the players: listen 300 ms to every browser process
    ├── Above -60 dBFS (you started it again) -> no play
    ├── No level, a browser runs and every one has closed its output -> still paused: play
    │   (a pause longer than about 10 s closes the output; a tap on it delivers nothing)
    ├── No level otherwise (browser quit, tap failed) -> no play
    └── Otherwise -> send the system play command (MediaRemote 0), then poll 20 windows of 100 ms
        ├── A window above -60 dBFS -> resumed
        ├── No level before the first level (the output is opening again) -> keep polling
        ├── No level after a level -> stop listening
        ├── No browser output open after 10 windows (tab closed: the play reached another app) -> send pause once
        ├── Never a level and a browser opened its output -> stop listening
        └── Silent throughout (tab closed or reloaded: the play reached another app) -> send pause once

Intentional recording                    // recording.environment, idle_sleep
├── Prevent idle sleep
│   ├── macOS -> IOKit no-idle-sleep assertion
│   ├── Linux -> logind `idle:sleep` inhibitor; `idle` only where polkit refuses a
│   │   process outside the seat session (Hex's user service) to block sleep
│   ├── Windows -> system-required power request (from the press, as its While dictating does)
│   └── Failure -> Warn and continue recording
└── Finish/cancel -> Release it
    // no caffeinate child process or executable-policy dialog

A pane, detail card or dropdown longer than its space    // ui.scroll-bar (#1209)
├── Scroll bar -> a thin thumb on the right edge, only while the content overflows
│   ├── Drag the thumb -> the content follows it
│   └── Press above or below it -> jumps there
├── Page Up / Page Down, Home / End -> page the pane around focus or the pointer
├── Open menu or dropdown -> ↑ ↓ move the highlight, Page Up / Down by the rows it
│   shows, Home / End to the ends; the highlight stays in view
├── Model search picker -> the same; Home / End only while the search is empty
└── Wheel and trackpad -> unchanged

Output (main sidebar, replaces the Modes editor) // rune_ui/output.rs; scenes output*
├── Trust prompt -> Allow a config that uses fetch or programs (only when one asks)
├── Edit with agent -> Copy a prompt naming the steps' keys (the AI rewrite too), `hex settings`,
│   `hex vocabulary` for names, and the transforms docs
├── Open file -> settings.json in the default editor
├── Every dictation -> Global's steps, numbered, read-only
├── Try -> Global's corrections and built-ins on a typed sentence
│   ├── Scripts and rewriting run only when dictating
│   └── Labs > Fix results in Output (off, #989) -> Vocabulary (the shared sheet) and,
│       with a sentence typed, Fix this: copies Edit with agent's prompt ending
│       `When I say "<sentence>", Hex pastes "<result>". It should paste: ` (labs.md)
└── In some apps -> Each mode's apps and its steps (Only: …), opens to list them
    // the old Modes editor stays in the code for its scenes, unreachable

Foreground context -> Select processing
├── Matching website                     // macOS: scriptable browsers, then AXWebArea; Windows: UIA; Linux: AT-SPI
├── Otherwise matching application
├── Hex itself in front                  // application only: Hex never reads its own AX tree (#1402)
└── Otherwise Global

Selected mode                            // replaces Global's rewrite and transformations
  -> Its vocabulary, then the shared one   // features/vocabulary.md (vocabulary.modes)
  -> Global's corrections, then the mode's  // every OS
  -> OpenCode transformation             // optional provider-backed rewrite
  -> Transformations                     // ordered text chain
  -> Paste or Send

Stage fails -> Preserve its input        // failed chain discards partial results

Transform host APIs                      // personal_commands/{io,fetch,process,trust}.rs
├── fetch(url, { method, headers, body, signal }) -> Response (ureq, platform TLS)
├── node:child_process execFile / exec (+ node:util promisify, input option)
├── setTimeout, AbortController, AbortSignal.timeout
└── First use -> Output pane trust prompt (hosts, programs, or capability)
    ├── Allow -> hash of every loaded file pinned in transform-trust.json
    ├── Any edit -> asks again
    └── Not allowed -> call throws -> chain fails -> text pasted unchanged
Timeout or settle -> requests abandoned, process group / job object killed