@iamsamuelrodda/dictate 2026.5.18-1 → 2026.5.18

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Samuel Rodda
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,3 @@
+Dictate
+
+This product includes software from the Dictate project.

package/README.md

@@ -1,175 +1,367 @@
-# 🎙️ Dictate
-
-Desktop dictation that types into the focused app.
-
-`dictate` runs as a small tray app. Press your configured push-to-talk shortcut,
-speak, and it transcribes into whatever app you are already using.
-
-Current status: early desktop app. Linux and Windows 11 installs, tray controls,
-startup integration, recent history, model selection, API key storage, update,
-and uninstall paths are implemented. Signed Windows installer packaging is still
-future work.
+# dictate
+
+Local voice-to-text for desktop dictation: hold `Right Ctrl`, speak, release to transcribe and type into the focused window.
+
+Linux is the primary tray desktop. Windows 11 is supported as a separate headless compatibility stream.
+
+## Features
+
+- Speech-to-text backends kept intentionally small:
+  - `faster-whisper` with `turbo` (default local Whisper path)
+  - `openai` with `gpt-4o-mini-transcribe`
+  - `xai` with `grok-speech-to-text`
+  - `gemini` with `gemini-3-flash-preview`
+- Capability-aware backend contract (`hotwords`, prompt bias, language hint handling) so unsupported options fail soft with clear warnings.
+- Backend-agnostic lexical adaptation modes: `native`, `prompt`, `post`, `hybrid`.
+- Push-to-talk daemon: `Right Ctrl` hold/release to record/transcribe/type.
+- Configurable push-to-talk key (`ctrl_r` default, `ctrl_l` supported for Wayland/laptop compatibility).
+- System tray toggle (pause/resume dictation).
+- Tray backend switcher (change local/API transcription route without restart).
+- Recent history with copy/paste actions and pagination for up to 20 dictations.
+- One-shot mode for terminal workflows (print to stdout or copy to clipboard).
+- Typing backend auto-selection (`xdotool` on X11, `wtype`/`ydotool` on Wayland, `pynput` on Windows).
+- Explicit backend resource release on switch.
+
+## Requirements
+
+- Linux (X11 recommended; Wayland supported depending on typing backend and hotkey support).
+- Windows 11 for headless push-to-talk and one-shot modes.
+- Python 3.11 or 3.12.
+- Microphone/audio: `sounddevice` + a working PortAudio setup.
+- Typing backend (for daemon modes):
+  - X11: `xdotool` (recommended)
+  - Wayland: `wtype` or `ydotool`
+  - Windows 11: `pynput`
+- Clipboard (for `--once --copy`): `xclip` on Linux or `pyperclip` on Windows.
+- Tray icon dependencies (for default tray mode):
+  - GTK + GI bindings (`python3-gi`)
+  - Ayatana indicator bindings (`gir1.2-ayatanaappindicator3-0.1` or equivalent for your distro)
 
 ## Install
 
-Windows 11 normal install:
-
-```powershell
-powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@iamsamuelrodda/dictate@latest/install.ps1 | iex"
-```
-
-Open **Dictate** from the Start Menu after install.
-
-Ubuntu/Debian source install:
+Ubuntu/Debian install with system packages, seeded default hotwords config, and prepared `faster-whisper/turbo`:
 
 ```bash
 ./install-ubuntu.sh
 ```
 
-Generic Linux source install:
+Generic repo install (assumes OS packages and `uv` are already present):
 
 ```bash
 ./install.sh
 ```
 
-Open **Dictate** from the app launcher after install.
+`install.sh` seeds the Linux config file from [`config/default-config.yaml`](config/default-config.yaml) on first install and prepares the `faster-whisper/turbo` model by default. Existing user config is left untouched.
 
-Windows source install, from the repo/source directory:
+Installer verification/model preparation can be skipped if needed:
 
-```powershell
-powershell -ExecutionPolicy Bypass -File .\install-windows-wizard.ps1
+```bash
+./install.sh --no-verify --no-prepare-turbo
 ```
 
-The local `.ps1` installer scripts must be run from a checkout or extracted
-source directory. They will not work from `C:\Windows\System32`.
-
-Node/npm users can also run:
+Windows 11 install from PowerShell:
 
 ```powershell
-npx @iamsamuelrodda/dictate install
+powershell -ExecutionPolicy Bypass -File .\install-windows.ps1
 ```
 
-## Workflow
+Windows setup wizard:
 
-```text
-Open Dictate
-Select Model
-Set API key if using a hosted model
-Set push-to-talk shortcut if desired
-Hold shortcut, speak, release
-Review Recent History when needed
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install-windows-wizard.ps1
 ```
 
-By default, Dictate installs a normal app launcher entry and starts on sign-in.
-Startup can be changed from Settings.
-
-## Update And Uninstall
-
-Windows installed from the hosted installer:
+Hosted Windows one-liner:
 
 ```powershell
-powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@iamsamuelrodda/dictate@latest/update.ps1 | iex"
-powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@iamsamuelrodda/dictate@latest/uninstall.ps1 | iex"
+powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@iamsamuelrodda/dictate@latest/install.ps1 | iex"
 ```
 
-Windows from source:
+Node/npm users can also run:
 
 ```powershell
-powershell -ExecutionPolicy Bypass -File .\update-windows.ps1
-powershell -ExecutionPolicy Bypass -File .\uninstall-windows.ps1
+npx @iamsamuelrodda/dictate install
 ```
 
-Linux:
+This creates `.venv`, installs the Windows dependencies, seeds config, writes launcher scripts, prepares the default model, runs diagnostics, and installs a Start Menu shortcut named `Dictate`. The `Dictate` shortcut starts the Windows tray app. See [Windows 11 support](docs/windows-11.md) for details.
+The Windows installer also verifies the Microsoft Visual C++ runtime needed by the native transcription wheels and installs it when it is missing.
+
+Update or uninstall from a source checkout:
 
 ```bash
 ./update.sh
 ./uninstall.sh
 ```
 
-Use `-RemoveUserData` on Windows or `--remove-user-data` on Linux only when you
-also want to remove config, logs, history, and downloaded model data.
-
-## What It Does Today
+```powershell
+powershell -ExecutionPolicy Bypass -File .\update-windows.ps1
+powershell -ExecutionPolicy Bypass -File .\uninstall-windows.ps1
+```
 
-- Starts from the Windows Start Menu or Linux app launcher
-- Runs as a tray app
-- Types dictated text into the focused app
-- Supports configurable push-to-talk
-- Shows selected model/status in the app UI
-- Supports launch on startup
-- Stores hosted-provider API keys in the OS secret store
-- Keeps a small Recent History for copy/paste recovery
-- Provides installer, updater, uninstaller, and doctor paths
+Use `--remove-user-data` on Linux or `-RemoveUserData` on Windows only when you also want to remove config, logs, history, and downloaded model data.
 
-## Models
+Dictate is built to be useful, but it has real-world risks. Support and maintenance are best-effort, and important output should be checked before you rely on it. Report issues so they can be fixed; if Dictate saves you time and you have the means, paid support helps keep the work moving. Arc Forge terms are at <https://arcforge.au/terms>.
 
-Supported provider defaults:
+## Usage
 
-- `faster-whisper/turbo` for local transcription
-- `openai/gpt-4o-mini-transcribe`
-- `xai/grok-speech-to-text`
-- `gemini/gemini-3-flash-preview`
+Tray mode (default):
 
-Local transcription can use CPU or GPU where supported. Hosted providers require
-an API key before they can be selected.
+```bash
+dictate
+```
 
-## Commands
+Headless daemon (no tray icon):
 
 ```bash
-dictate
 dictate --no-tray
+```
+
+One-shot (record until Enter, print to stdout):
+
+```bash
 dictate --once
+```
+
+One-shot (record until Enter, copy to clipboard):
+
+```bash
 dictate --once --copy
+```
+
+Run diagnostics:
+
+```bash
 dictate doctor --quick
 dictate doctor --quick --fix
+dictate doctor --quick --update-paths
 dictate doctor --check-model-load
 ```
 
-Hotword and model options are available from Settings. CLI flags still exist for
-automation and testing:
+Select model/device/compute-type/language:
 
 ```bash
 dictate --stt-backend faster-whisper --model turbo
 dictate --stt-backend openai --model gpt-4o-mini-transcribe
 dictate --stt-backend xai --model grok-speech-to-text
 dictate --stt-backend gemini --model gemini-3-flash-preview
-dictate --add-hotword AcmeWidget
+dictate --device cpu
+dictate --compute-type float16
+dictate --language en
+dictate --lexicon-mode hybrid
+```
+
+`--compute-type` affects `faster-whisper` only. Hosted API backends ignore local device and compute settings.
+For hosted backends, use the tray **API Key** provider menu or Windows controls to store keys in the OS secret store
+(Secret Service/libsecret on Linux, Windows Credential Manager on Windows). Dictate never writes raw API keys
+to `config.yaml`. Environment variables such as `DICTATE_OPENAI_API_KEY`, `DICTATE_XAI_API_KEY`, and
+`DICTATE_GEMINI_API_KEY` still take priority, and advanced users can keep using `*_api_key_command` config
+entries that call their own secret manager.
+
+Manage lexical post-corrections:
+
+```bash
+dictate --add-lexicon-replacement kinneri=canary
+dictate --remove-lexicon-replacement kinneri
+dictate --list-lexicon-replacements
+```
+
+## STT Backends
+
+Supported defaults for low-latency dictation:
+
+- Local default: `faster-whisper` with `turbo`
+- Hosted OpenAI route: `openai` with `gpt-4o-mini-transcribe`
+- Hosted xAI route: `xai` with `grok-speech-to-text`
+- Hosted Gemini route: `gemini` with `gemini-3-flash-preview`
+
+Examples:
+
+```bash
+# Local Whisper Turbo
+dictate --stt-backend faster-whisper --model turbo --language en
+
+# Hosted transcription path, useful when local GPU should be reserved for other work
+OPENAI_API_KEY=... dictate --stt-backend openai --model gpt-4o-mini-transcribe --language en
+
+# Hosted xAI path with keyterm biasing from configured hotwords
+XAI_API_KEY=... dictate --stt-backend xai --model grok-speech-to-text --language en
+
+# Hosted Gemini path using Gemini audio understanding
+GEMINI_API_KEY=... dictate --stt-backend gemini --model gemini-3-flash-preview --language en
+
+# Desktop autostart can use keys stored from the tray API Key provider menu.
+# Advanced external secret-manager helpers are still supported:
+# stt_backend: openai
+# stt_model: gpt-4o-mini-transcribe
+# openai_api_key_command: /home/samuelrodda/.local/bin/dictate-openai-key
+# stt_backend: xai
+# stt_model: grok-speech-to-text
+# xai_api_key_command: /home/samuelrodda/.local/bin/dictate-xai-key
+# stt_backend: gemini
+# stt_model: gemini-3-flash-preview
+# gemini_api_key_command: /home/samuelrodda/.local/bin/dictate-gemini-key
+```
+
+The app UI exposes one local Whisper option: `faster-whisper/turbo`.
+
+Force typing backend (daemon modes):
+
+```bash
+dictate --type-backend xdotool
+dictate --type-backend wtype
+dictate --type-backend ydotool
+dictate --type-backend pynput
+```
+
+## Hotwords
+
+Hotwords improve recognition of custom vocabulary (project names, technical terms, etc.).
+
+Manage saved hotwords:
+
+```bash
+dictate --add-hotword Kubernetes
+dictate --add-hotword OpenBao,Vikunja
+dictate --remove-hotword Vikunja
 dictate --list-hotwords
 ```
 
-## State
+Hotwords are saved to the platform config file. On Linux this is usually `~/.config/dictate/config.yaml`; on Windows this is `%APPDATA%\dictate\config.yaml`. Fresh installs created through the repo installer seed this file from [`config/default-config.yaml`](config/default-config.yaml).
+
+You can also pass one-off hotwords without saving them:
+
+```bash
+dictate --hotwords "Kubernetes,OpenBao"
+```
+
+CLI `--hotwords` and saved hotwords are merged at startup.
+
+Lexical adaptation modes (backend-agnostic):
+
+- `native` (default): use backend-native hotword biasing (effective on `faster-whisper`)
+- `prompt`: use prompt/context biasing (effective on prompt-capable API backends)
+- `post`: run lightweight post-correction against hotwords/replacements
+- `hybrid`: apply all supported strategies
+
+Mode behavior by backend:
+
+- `faster-whisper`: `native`/`hybrid` applies decode-time hotword bias.
+- `openai` and `gemini`: use `prompt` or `hybrid` for prompt/context biasing, and/or `post`/`hybrid` for post-correction.
+- `xai`: `native`/`hybrid` passes keyterms to the hosted STT API.
+- In `native` mode on backends without native hotwords, hotwords are ignored with a warning.
+
+Examples:
+
+```bash
+# Use prompt biasing with your hotwords list on a prompt-capable API backend
+dictate --stt-backend gemini --lexicon-mode prompt
+
+# Hybrid mode combines native/prompt/post where available
+dictate --lexicon-mode hybrid
+
+# Add explicit post-correction replacements
+dictate --add-lexicon-replacement kinneri=canary
+dictate --remove-lexicon-replacement kinneri
+dictate --list-lexicon-replacements
+```
+
+## How It Works
+
+**Hold Right Ctrl** to record, **release** to transcribe and type into the focused window.
+
+If your desktop or keyboard reports `Right Ctrl` unreliably, set this in your platform config file:
+
+```yaml
+push_to_talk_combo: ctrl_l
+```
+
+In tray mode, a microphone icon appears in the system tray with a right-click menu:
+
+- **Active** — checkbox to pause/resume listening for the hotkey. The icon switches to a muted microphone when paused.
+- **Select Model** — switch between Local, OpenAI, xAI, and Gemini live.
+- **Hotwords** — manage saved vocabulary when the selected backend can use it.
+- **API Key** — store or clear OpenAI, xAI, and Gemini keys in the OS secret store.
+- **Hotkeys** — configure the recording shortcut.
+- **Recent History** — copy or paste a previous dictation. History keeps up to 20 entries and paginates the list.
+- If switching fails, Dictate keeps the previous backend active and shows an error dialog.
+- **Quit** — stops the daemon.
+
+You can also quit from the terminal with `Ctrl+C`.
+
+## Notes And Troubleshooting
+
+- First local run will likely download Whisper model files. Network is required once per model.
+- Tray backend selections are persisted in the platform config file and used on startup unless CLI flags override them.
+- Persisted STT selection keys:
+  - `stt_backend`
+  - `stt_model`
+  - `stt_device`
+  - `stt_compute_type`
+- Additional recognized config keys:
+  - `push_to_talk_combo` (examples: `ctrl_r`, `ctrl_l`, `ctrl+space`, `ctrl+shift`)
+  - `lexicon_mode` (optional startup default; set manually in config)
+  - `lexicon_replacements` (managed by CLI replacement commands)
+  - `openai_api_key_command`, `xai_api_key_command`, `gemini_api_key_command`
+- Preflight now checks STT backend readiness (dependency imports + CUDA visibility) before model load.
+- Startup stderr is mirrored to logs:
+  - Linux latest run: `~/.local/share/dictate/logs/latest.log`
+  - Linux last non-zero exit: `~/.local/share/dictate/logs/last_failure.log`
+  - Windows logs: `%LOCALAPPDATA%\dictate\logs\`
+  - fallback when home path is not writable: system temp directory `dictate-logs`
+- On Wayland:
+  - `xdotool` generally will not work for native Wayland apps.
+  - Prefer `wtype` (simple) or `ydotool` (may require extra setup/permissions).
+  - Global hotkeys can be restricted on some Wayland compositors; if your combo does not fire, try `push_to_talk_combo: ctrl_l` or `push_to_talk_combo: ctrl+space`, use `--once`, or run an X11 session.
+- On Windows 11, the Start Menu shortcut named `Dictate` starts the native tray app. Use `dictate --no-tray --type-backend pynput` only when you explicitly want a headless daemon.
+- If preflight reports missing tools, install them via your distro package manager (e.g. `xdotool`, `xclip`, `wtype`) or install the Windows extra with `pip install -e ".[windows]"`.
+- Dictation uses the system default microphone input device. If your default input is misconfigured, fix it in your OS audio settings.
+- If the app does not launch from GUI, run `dictate doctor --quick` and inspect the reported active log directory.
+
+## Benchmarking
+
+Use the local benchmark harness to compare backends/models on your own accent and vocabulary:
 
-User state is local:
+```bash
+dictate benchmark \
+  --manifest benchmarks/example_manifest.csv \
+  --audio-root benchmarks \
+  --stt-backend faster-whisper \
+  --model turbo \
+  --device auto \
+  --language en
+```
 
-```text
-Linux:
-  ~/.config/dictate/config.yaml
-  ~/.local/share/dictate/
+Legacy wrapper still works:
 
-Windows:
-  %APPDATA%\dictate\config.yaml
-  %LOCALAPPDATA%\dictate\
+```bash
+uv run python scripts/benchmark_stt.py --help
 ```
 
-Repo defaults intentionally ship with `hotwords: []`. Hotwords are user-specific
-and should not be packaged into the public repo default config.
+Create your own manifest with Australian-accent phrases and proper nouns. Format docs: `benchmarks/README.md`.
 
-## Safety
+## Testing
 
-- Dictate does not intentionally write raw API keys to `config.yaml`.
-- API keys configured in the app use the OS secret store.
-- Dictation text can be sensitive; check logs and issue reports before sharing.
-- Important transcriptions should be verified before relying on them.
-- Support and maintenance are best-effort.
+Run regression tests:
+
+```bash
+uv run python -m unittest discover -s tests
+```
 
-## Docs
+## Development
 
-- [Windows 11 support](docs/windows-11.md)
-- [Recent History spec](docs/recent-dictation-history-spec.md)
-- [Release/versioning](docs/release-versioning.md)
-- [Development streams](docs/development-streams.md)
-- [Security policy](SECURITY.md)
+- Entry point: `dictate` is `dictate.__main__:main_with_logging` (see `src/dictate/__main__.py`).
+- Core pipeline modules:
+  - audio capture: `src/dictate/audio.py`
+  - transcription engine: `src/dictate/engine.py`
+  - typing/clipboard outputs: `src/dictate/outputs.py`
+  - environment checks: `src/dictate/preflight.py`
+  - STT backends + registry: `src/dictate/stt/`
+- Platform docs:
+  - Windows 11 stream: `docs/windows-11.md`
+  - Development streams: `docs/development-streams.md`
+  - CalVer releases: `docs/release-versioning.md`
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+Apache-2.0 (see `LICENSE`). Preserve `NOTICE` when redistributing the project.
+Contributions are accepted under the terms in `CONTRIBUTING.md`.

package/config/default-config.yaml

@@ -1,4 +1,32 @@
-hotwords: []
+hotwords:
+  - Todoist
+  - Joplin
+  - Kubernetes
+  - Arc
+  - Bitwarden
+  - OpenBao
+  - Claude Code
+  - Prometheus
+  - Grafana
+  - Pi
+  - Arc Forge
+  - ASIC
+  - GIMP
+  - Ghostty
+  - Inkscape
+  - See
+  - see
+  - Seazona
+  - OpenClaw
+  - Aegis
+  - Cato
+  - Rodda
+  - Sure
+  - Moasure
+  - Schemantics
+  - root
+  - Xero
+  - Pixel Forge
 push_to_talk_combo: ctrl_r
 stt_backend: faster-whisper
 stt_compute_type: int8

package/install-windows.ps1

@@ -179,7 +179,6 @@ function New-DictateShortcut {
     param(
         [string]$ShortcutPath,
         [string]$TargetPath,
-        [string]$Arguments = "",
         [string]$WorkingDirectory,
         [string]$Description
     )
@@ -188,7 +187,6 @@ function New-DictateShortcut {
     $shell = New-Object -ComObject WScript.Shell
     $shortcut = $shell.CreateShortcut($ShortcutPath)
     $shortcut.TargetPath = $TargetPath
-    $shortcut.Arguments = $Arguments
     $shortcut.WorkingDirectory = $WorkingDirectory
     $shortcut.Description = $Description
     if (Test-Path $iconPath) {
@@ -200,7 +198,6 @@ function New-DictateShortcut {
 function Install-StartMenuShortcut {
     param(
         [string]$TargetPath,
-        [string]$Arguments = "",
         [string]$WorkingDirectory
     )
 
@@ -217,7 +214,7 @@ function Install-StartMenuShortcut {
     }
 
     Remove-Item -Force -ErrorAction SilentlyContinue -Path $legacyShortcutPath
-    New-DictateShortcut -ShortcutPath $shortcutPath -TargetPath $TargetPath -Arguments $Arguments -WorkingDirectory $WorkingDirectory -Description "Start Dictate push-to-talk tray"
+    New-DictateShortcut -ShortcutPath $shortcutPath -TargetPath $TargetPath -WorkingDirectory $WorkingDirectory -Description "Start Dictate push-to-talk tray"
 
     Write-Host "==> Installed Start Menu shortcut: $shortcutPath"
 }
@@ -225,7 +222,6 @@ function Install-StartMenuShortcut {
 function Install-StartupShortcut {
     param(
         [string]$TargetPath,
-        [string]$Arguments = "",
         [string]$WorkingDirectory
     )
 
@@ -243,7 +239,7 @@ function Install-StartupShortcut {
     New-Item -ItemType Directory -Force -Path $startupDir | Out-Null
 
     $shortcutPath = Join-Path $startupDir "Dictate.lnk"
-    New-DictateShortcut -ShortcutPath $shortcutPath -TargetPath $TargetPath -Arguments $Arguments -WorkingDirectory $WorkingDirectory -Description "Start Dictate automatically at sign-in"
+    New-DictateShortcut -ShortcutPath $shortcutPath -TargetPath $TargetPath -WorkingDirectory $WorkingDirectory -Description "Start Dictate automatically at sign-in"
 
     Write-Host "==> Installed startup shortcut: $shortcutPath"
 }
@@ -257,7 +253,7 @@ function Register-InstalledApp {
     $keyPath = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\Dictate"
     New-Item -Force -Path $keyPath | Out-Null
     New-ItemProperty -Force -Path $keyPath -Name "DisplayName" -Value "Dictate" -PropertyType String | Out-Null
-    New-ItemProperty -Force -Path $keyPath -Name "DisplayVersion" -Value "2026.5.18-1" -PropertyType String | Out-Null
+    New-ItemProperty -Force -Path $keyPath -Name "DisplayVersion" -Value "2026.5.18" -PropertyType String | Out-Null
     New-ItemProperty -Force -Path $keyPath -Name "Publisher" -Value "Arc Forge Labs" -PropertyType String | Out-Null
     New-ItemProperty -Force -Path $keyPath -Name "InstallLocation" -Value $InstallLocation -PropertyType String | Out-Null
     if (Test-Path $DisplayIcon) {
@@ -295,11 +291,8 @@ Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "pip", "install", "-e", "$
 
 Seed-Config
 Write-LauncherScripts -ScriptsDir $scriptsDir
-$trayVbs = Join-Path $scriptsDir "dictate-tray.vbs"
-$wscript = Join-Path $env:WINDIR "System32\wscript.exe"
-$trayArgs = "`"$trayVbs`""
-Install-StartMenuShortcut -TargetPath $wscript -Arguments $trayArgs -WorkingDirectory $PSScriptRoot
-Install-StartupShortcut -TargetPath $wscript -Arguments $trayArgs -WorkingDirectory $PSScriptRoot
+Install-StartMenuShortcut -TargetPath (Join-Path $scriptsDir "dictate-tray.vbs") -WorkingDirectory $PSScriptRoot
+Install-StartupShortcut -TargetPath (Join-Path $scriptsDir "dictate-tray.vbs") -WorkingDirectory $PSScriptRoot
 Register-InstalledApp -InstallLocation $PSScriptRoot -DisplayIcon (Join-Path $PSScriptRoot "assets\dictate.ico")
 
 if (-not $NoPrepareTurbo) {

package/install.ps1

@@ -10,7 +10,7 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$DictateVersion = "2026.5.18-1"
+$DictateVersion = "2026.5.18"
 
 if (-not $ArchiveUrl) {
     $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/refs/tags/v$DictateVersion.zip"

package/install.sh

@@ -127,7 +127,7 @@ rm -f "$DESKTOP_DIR/dictate-settings.desktop"
 cat > "$DESKTOP_DIR/dictate.desktop" <<EOF
 [Desktop Entry]
 Name=Dictate
-Comment=Dictate into the focused app
+Comment=Local voice-to-text with push-to-talk
 Exec=$HOME/.local/bin/dictate
 Icon=$ICON_PATH
 Type=Application
@@ -144,7 +144,7 @@ if [ "$STARTUP" -eq 1 ]; then
   cat > "$AUTOSTART_DIR/dictate.desktop" <<EOF
 [Desktop Entry]
 Name=Dictate
-Comment=Dictate into the focused app
+Comment=Local voice-to-text with push-to-talk
 Exec=$HOME/.local/bin/dictate
 Icon=$ICON_PATH
 Type=Application

package/npm/dictate-lifecycle.mjs

@@ -24,7 +24,7 @@ const scripts = isWindows
   ? {
       install: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "install.ps1")]],
       update: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "update.ps1")]],
-      uninstall: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "uninstall.ps1")]],
+      uninstall: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "uninstall-windows.ps1")]],
       wizard: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "install.ps1"), "-Wizard"]],
     }
   : {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@iamsamuelrodda/dictate",
-  "version": "2026.5.18-1",
-  "description": "Installer shim for Dictate desktop dictation.",
-  "license": "MIT",
+  "version": "2026.5.18",
+  "description": "Installer shim for Dictate desktop voice-to-text.",
+  "license": "Apache-2.0",
   "type": "module",
   "homepage": "https://github.com/arcforgelabs/dictate#readme",
   "repository": {
@@ -23,7 +23,6 @@
     "install-windows.ps1",
     "install-windows-wizard.ps1",
     "update-windows.ps1",
-    "uninstall.ps1",
     "uninstall-windows.ps1",
     "install.sh",
     "update.sh",
@@ -35,7 +34,8 @@
     "assets/dictate-listening.png",
     "npm/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "publishConfig": {
     "access": "public",

package/update.ps1

@@ -10,7 +10,7 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$DictateVersion = "2026.5.18-1"
+$DictateVersion = "2026.5.18"
 
 if (-not $ArchiveUrl) {
     $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/refs/tags/v$DictateVersion.zip"

package/uninstall.ps1

@@ -1,51 +0,0 @@
-param(
-    [string]$InstallRoot,
-    [switch]$Quiet,
-    [switch]$RemoveUserData
-)
-
-$ErrorActionPreference = "Stop"
-
-if (-not $InstallRoot) {
-    $base = $env:LOCALAPPDATA
-    if (-not $base) {
-        $base = Join-Path $HOME "AppData\Local"
-    }
-    $InstallRoot = Join-Path $base "Dictate"
-}
-
-$installRootPath = [System.IO.Path]::GetFullPath($InstallRoot)
-$sourceDir = Join-Path $installRootPath "source"
-$uninstaller = Join-Path $sourceDir "uninstall-windows.ps1"
-
-if (Test-Path $uninstaller) {
-    $args = @("-NoProfile", "-ExecutionPolicy", "Bypass", "-File", $uninstaller)
-    if ($Quiet) { $args += "-Quiet" }
-    if ($RemoveUserData) { $args += "-RemoveUserData" }
-    & powershell @args
-    if ($LASTEXITCODE -ne 0) {
-        throw "Dictate Windows uninstaller failed with exit code $LASTEXITCODE."
-    }
-} else {
-    if (-not $Quiet) {
-        Write-Host "Dictate source uninstaller not found: $uninstaller"
-        Write-Host "Removing known Start Menu, startup, and Installed Apps entries."
-    }
-    $programsDir = Join-Path $env:APPDATA "Microsoft\Windows\Start Menu\Programs"
-    if (-not $env:APPDATA) {
-        $programsDir = Join-Path $HOME "AppData\Roaming\Microsoft\Windows\Start Menu\Programs"
-    }
-    Remove-Item -Force -ErrorAction SilentlyContinue -Path `
-        (Join-Path $programsDir "Dictate.lnk"), `
-        (Join-Path $programsDir "Dictate Controls.lnk"), `
-        (Join-Path $programsDir "Startup\Dictate.lnk")
-    Remove-Item -Recurse -Force -ErrorAction SilentlyContinue -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\Dictate"
-}
-
-if (Test-Path $installRootPath) {
-    Remove-Item -Recurse -Force -Path $installRootPath
-}
-
-if (-not $Quiet) {
-    Write-Host "Dictate removed from: $installRootPath"
-}