@arcforgelabs/dictate 2026.6.20 → 2026.7.4-unstable.3.1

package/README.md

@@ -6,18 +6,19 @@ Desktop dictation that types into the focused app.
 speak, and it transcribes into whatever app you are already using.
 
 Current status: early desktop app. Linux installs, Windows 11 source installs,
-tray controls, startup integration, recent history, model selection, API key
-storage, update, and uninstall paths are implemented. Windows Store/signed
-installer packaging is being prepared; see `docs/goal.md`.
+tray controls, startup integration, local dictation history, update, and
+uninstall paths are implemented. Microsoft Store packaging and submission
+automation are maintained separately from GitHub releases; see
+`docs/msstore-automation.md`. The current transcription/model deployment plan is
+`docs/TRANSCRIPTION_PLAN.md`.
 
 ## Install
 
 Windows 11 normal install:
 
-The target public channel is Microsoft Store distribution. Until that listing is
-ready, use the GitHub release installer artifacts for internal validation only.
-The PowerShell bootstrap installer below is a developer/source path, not the
-normal public install route.
+The target public channel is Microsoft Store distribution. GitHub release
+artifacts and the PowerShell bootstrap installer below are developer/source or
+internal validation paths, not the normal public Windows install route.
 
 Windows developer/source install from the hosted bootstrap:
 
@@ -25,15 +26,21 @@ Windows developer/source install from the hosted bootstrap:
 powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@arcforgelabs/dictate@latest/install.ps1 | iex"
 ```
 
+Unstable developer/source bootstrap for pre-stable feature testing:
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@arcforgelabs/dictate@unstable/install.ps1 | iex"
+```
+
 Open **Dictate** from the Start Menu after install.
 
-Ubuntu/Debian source install:
+Linux default install (per-user, no sudo for app updates):
 
 ```bash
 ./install-ubuntu.sh
 ```
 
-Generic Linux source install:
+Generic Linux user install:
 
 ```bash
 ./install.sh
@@ -41,6 +48,14 @@ Generic Linux source install:
 
 Open **Dictate** from the app launcher after install.
 
+Linux system package install is also supported when you explicitly want a
+machine-wide `.deb` install:
+
+```bash
+DICTATE_BUNDLES=deb scripts/build-linux-desktop.sh
+./install.sh --system
+```
+
 Windows developer/source install, from the repo/source directory:
 
 ```powershell
@@ -60,15 +75,13 @@ npx @arcforgelabs/dictate install
 
 ```text
 Open Dictate
-Select Model
-Set API key if using a hosted model
-Set push-to-talk shortcut if desired
+Use the mic button or configured push-to-talk shortcut
 Hold shortcut, speak, release
-Review Recent History when needed
+Review Dictations when needed
 ```
 
 By default, Dictate installs a normal app launcher entry and starts on sign-in.
-Startup can be changed from Settings.
+Advanced configuration is available through the `dictate config` CLI.
 
 ## Update And Uninstall
 
@@ -79,6 +92,20 @@ powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/
 powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@arcforgelabs/dictate@latest/uninstall.ps1 | iex"
 ```
 
+To test updates before they are promoted to stable:
+
+```powershell
+powershell -ExecutionPolicy Bypass -Command "iwr -useb https://cdn.jsdelivr.net/npm/@arcforgelabs/dictate@unstable/update.ps1 | iex"
+```
+
+Users on the app's npm-backed update path can opt into or out of unstable
+updates from the CLI:
+
+```bash
+dictate config set-update-channel unstable
+dictate config set-update-channel stable
+```
+
 Windows from source:
 
 ```powershell
@@ -86,13 +113,19 @@ powershell -ExecutionPolicy Bypass -File .\update-windows.ps1
 powershell -ExecutionPolicy Bypass -File .\uninstall-windows.ps1
 ```
 
-Linux:
+Linux user install:
 
 ```bash
 ./update.sh
 ./uninstall.sh
 ```
 
+Linux system package update:
+
+```bash
+./update.sh --system
+```
+
 Use `-RemoveUserData` on Windows or `--remove-user-data` on Linux only when you
 also want to remove config, logs, history, and downloaded model data.
 
@@ -102,23 +135,37 @@ also want to remove config, logs, history, and downloaded model data.
 - 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
+- Presents a simple capture-first desktop UI
 - Supports launch on startup
-- Stores hosted-provider API keys in the OS secret store
-- Keeps a small Recent History for copy/paste recovery
+- Stores CLI-configured hosted-provider API keys in the OS secret store
+- Keeps a small local dictations history for copy/paste recovery
 - Provides installer, updater, uninstaller, and doctor paths
 
 ## Models
 
-Supported provider defaults:
-
-- `faster-whisper/turbo` for local transcription
-- `openai/gpt-4o-mini-transcribe`
-- `xai/grok-speech-to-text`
-- `gemini/gemini-3-flash-preview`
-
-Local transcription can use CPU or GPU where supported. Hosted providers require
-an API key before they can be selected.
+The default local English path is Parakeet where the runtime is available. The
+desktop UI keeps engine names out of the primary workflow; advanced users and
+tests can still configure explicit local or hosted providers through CLI options
+and `dictate config`.
+
+GPU lanes are explicit:
+
+- NVIDIA CUDA: install with the `gpu` extra and verify with
+  `dictate doctor --stt-backend parakeet --device cuda --quick`.
+- Windows AMD GPU: install with the `amd` extra for ONNX Runtime DirectML and
+  verify with `dictate doctor --stt-backend parakeet --device amd --quick`.
+- Linux AMD GPU: install a ROCm/MIGraphX-capable ONNX Runtime build, then verify
+  with `dictate doctor --stt-backend parakeet --device amd --quick`.
+- Meeting uses a dedicated speaker-attribution lane. Inspect it with
+  `dictate config show`; set it with
+  `dictate config set-meeting-model parakeet-pyannote/parakeet-tdt-0.6b-v2`.
+  Source installs can add pyannote support with `./install.sh --meeting` or
+  `.\install-windows.ps1 -Meeting`, then verify with
+  `dictate doctor --stt-backend parakeet-pyannote --device cuda --quick`.
+  Experimental preflight targets also exist for
+  `parakeet-diarizen/parakeet-tdt-0.6b-v2` and
+  `parakeet-sortformer/parakeet-tdt-0.6b-v2`; these still require their
+  runtime-specific DiariZen or NeMo setup before selection.
 
 ## Commands
 
@@ -132,11 +179,13 @@ dictate doctor --quick --fix
 dictate doctor --check-model-load
 ```
 
-Hotword and model options are available from Settings. CLI flags still exist for
-automation and testing:
+Advanced configuration remains available for automation and testing:
 
 ```bash
 dictate --stt-backend faster-whisper --model turbo
+dictate config show
+dictate config set-provider online
+dictate config set-key xai xai-YOUR_KEY_HERE
 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
@@ -164,33 +213,45 @@ and should not be packaged into the public repo default config.
 ## Safety
 
 - Dictate does not intentionally write raw API keys to `config.yaml`.
-- API keys configured in the app use the OS secret store.
+- API keys configured through the CLI 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.
 
 ## Desktop UI — the Quiet Console (preview)
 
-A design-system desktop Settings window is being built alongside the tray:
+A quiet desktop window sits alongside the tray — a capture home (the mic is the
+record button), the notes list, and the ⌘K palette; no settings menu (config via
+the `dictate config` CLI).
 
-- [`ui/`](ui/README.md) — React/Vite front-end (the Quiet Console: seven views,
-  ⌘K palette, listening HUD, light/dark, GNOME/KDE chrome).
+- [`ui/`](ui/README.md) — React/Vite front-end. For UI work, **`cd ui && npm run
+  dev`** opens the whole app at `http://localhost:5173` against a built-in mock
+  (no engine, no Tauri, no STT) — the fast UI loop in a browser. Details, and
+  when to use the Tauri shell instead, are in that README's *Develop* section.
 - [`ui-shell/`](ui-shell/README.md) — Tauri 2 shell that hosts it on Linux.
 - `src/dictate/ui_server.py` — the loopback control server the UI talks to; the
-  tray's **Open Settings…** launches the shell (falling back to native dialogs).
+  tray can launch the shell for the desktop capture surface.
 - See [`design/PLAN.md`](design/PLAN.md) for the cross-platform plan.
 
-**Install it like a normal app:** tagged releases attach a **self-contained**
-Linux **`.deb`** and **`.AppImage`** — they bundle the frozen Python engine
-inside (PyInstaller sidecar), so there's no separate Python/pip step. Download,
-install, launch; speech models download on first use.
+**Install it like a normal app:** the default Linux channel is a per-user install
+under `~/.local/share/dictate` with launchers in `~/.local/bin` and
+`~/.local/share/applications`. App updates do not need sudo.
+
+```bash
+./install.sh
+./update.sh
+```
+
+Tagged releases can also attach a **self-contained** Linux **`.deb`** for users
+who explicitly want a system package. It bundles the frozen Python engine inside
+(PyInstaller sidecar), so there's no separate Python/pip step:
 
 ```bash
-sudo apt install ./dictate_*_amd64.deb      # or: chmod +x Dictate_*.AppImage && ./Dictate_*.AppImage
+sudo apt install ./Dictate_*_amd64.deb
 ```
 
-The app lives in the tray (Open Settings / Quit) and does push-to-talk straight
-away. Build the package yourself in one step with
+The app lives in the tray and desktop shell and does push-to-talk straight away.
+Build the package yourself in one step with
 [`scripts/build-linux-desktop.sh`](scripts/build-linux-desktop.sh) — see
 [`ui-shell/README.md`](ui-shell/README.md). The `pip`/`install.sh` route remains
 for source/dev installs.
@@ -198,13 +259,14 @@ for source/dev installs.
 ## Docs
 
 - [Windows 11 support](docs/windows-11.md)
-- [Recent History spec](docs/recent-dictation-history-spec.md)
+- [Transcription deployment plan](docs/TRANSCRIPTION_PLAN.md)
 - [Release/versioning](docs/release-versioning.md)
 - [Desktop packaging & CI runbook](docs/desktop-packaging.md)
 - [Microsoft Store automation](docs/msstore-automation.md)
 - [Microsoft Store listing draft](docs/msstore-listing.md)
-- [Windows release goal](docs/goal.md)
+- [Deployment security](docs/deployment-security.md)
 - [Development streams](docs/development-streams.md)
+- [Archived docs index](docs/archive/README.md)
 - [Security policy](SECURITY.md)
 
 ## License

package/config/default-config.yaml

@@ -1,10 +1,20 @@
 hotwords: []
 push_to_talk_combo: ctrl_r
-stt_backend: faster-whisper
 stt_compute_type: int8
 stt_device: auto
-# Local Whisper uses the single supported local model:
+# Leave stt_backend/stt_model unset for the hardware-aware local default:
+# English Parakeet v2 on CPU, CUDA, and AMD when the Parakeet runtime is
+# available. Accelerator readiness is checked by doctor/preflight.
+# Set stt_backend/stt_model explicitly to override:
+# stt_backend: parakeet
+# stt_model: parakeet-tdt-0.6b-v2
+# Meeting mode uses a separate speaker-attribution lane. Leave these unset for
+# the default local Parakeet+pyannote Meeting backend, or set them explicitly.
+# meeting_stt_backend: parakeet-pyannote
+# meeting_stt_model: parakeet-tdt-0.6b-v2
+# stt_backend: faster-whisper
 # stt_model: turbo
+# stt_model: large-v3
 # To avoid local compute, set one hosted backend:
 # stt_backend: openai
 # stt_model: gpt-4o-mini-transcribe

package/install-windows.ps1

@@ -3,6 +3,7 @@ param(
     [switch]$NoPrepareTurbo,
     [switch]$NoShortcut,
     [switch]$NoStartup,
+    [switch]$Meeting,
     [switch]$RecreateVenv
 )
 
@@ -257,7 +258,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.6.20" -PropertyType String | Out-Null
+    New-ItemProperty -Force -Path $keyPath -Name "DisplayVersion" -Value "2026.7.4" -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) {
@@ -383,7 +384,12 @@ if (-not (Test-Path $venvPython)) {
 }
 
 Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "pip", "install", "--upgrade", "pip") -Description "Upgrading pip"
-Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "pip", "install", "-e", "${PSScriptRoot}[windows]") -Description "Installing Dictate Windows package"
+$installExtras = @("windows")
+if ($Meeting) {
+    $installExtras += "meeting"
+}
+$installTarget = "${PSScriptRoot}[$($installExtras -join ',')]"
+Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "pip", "install", "-e", $installTarget) -Description "Installing Dictate Windows package"
 
 Seed-Config
 Write-LauncherScripts -ScriptsDir $scriptsDir
@@ -395,7 +401,10 @@ Install-StartupShortcut -TargetPath $wscript -Arguments $trayArgs -WorkingDirect
 Register-InstalledApp -InstallLocation $PSScriptRoot -DisplayIcon (Join-Path $PSScriptRoot "assets\dictate.ico")
 
 if (-not $NoPrepareTurbo) {
-    Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "dictate", "prepare-model", "--stt-backend", "faster-whisper", "--model", "turbo", "--device", "auto", "--compute-type", "int8") -Description "Preparing faster-whisper turbo model"
+    # Keep the legacy switch name for installer compatibility, but prepare the
+    # fresh local default: Parakeet v2. Explicit faster-whisper users can still
+    # prepare that backend manually.
+    Invoke-Checked -Exe $venvPython -ArgumentList @("-m", "dictate", "prepare-model", "--stt-backend", "parakeet", "--device", "auto", "--compute-type", "int8") -Description "Preparing Parakeet model"
 }
 
 if (-not $NoVerify) {

package/install.ps1

@@ -10,10 +10,10 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$DictateVersion = "2026.6.20"
+$DictateVersion = "2026.7.4-unstable.3.1"
 
 if (-not $ArchiveUrl) {
-    $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/refs/tags/v$DictateVersion.zip"
+    $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/3f6f050451d0d0e140193534f102c6b5f2b58b19.zip"
 }
 
 if (-not $InstallRoot) {
@@ -76,6 +76,10 @@ try {
     if ($LASTEXITCODE -ne 0) {
         throw "Dictate Windows installer failed with exit code $LASTEXITCODE."
     }
+    $dictateExe = Join-Path $installRootPath ".venv\Scripts\dictate.exe"
+    if (Test-Path $dictateExe) {
+        & $dictateExe set-installed-package-version $DictateVersion | Out-Null
+    }
 } finally {
     if (Test-Path $stagingRoot) {
         Remove-Item -Recurse -Force $stagingRoot

package/install.sh

@@ -5,13 +5,15 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PACKAGE_VERSION="$(sed -n 's/^  "version": "\([^"]*\)",/\1/p' "$SCRIPT_DIR/package.json" | head -n 1 || true)"
 INSTALL_DIR="$HOME/.local/share/dictate"
 BIN_DIR="$HOME/.local/bin"
 DESKTOP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
 AUTOSTART_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
 ICON_DIR="$INSTALL_DIR/share/icons"
 ICON_PATH="$ICON_DIR/dictate-simple.png"
-DESKTOP_PATH="$DESKTOP_DIR/Dictate.desktop"
+APP_ICON_SOURCE="$SCRIPT_DIR/ui-shell/src-tauri/icons/icon.png"
+DESKTOP_PATH="$DESKTOP_DIR/dictate.desktop"
 CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/dictate"
 CONFIG_PATH="$CONFIG_DIR/config.yaml"
 DEFAULT_CONFIG_SOURCE="$SCRIPT_DIR/config/default-config.yaml"
@@ -20,6 +22,9 @@ PREPARE_TURBO=1
 SEED_DEFAULT_CONFIG=1
 STARTUP=1
 INSTALL_UI=1
+INSTALL_GPU="${DICTATE_INSTALL_GPU:-0}"
+INSTALL_MEETING="${DICTATE_INSTALL_MEETING:-0}"
+INSTALL_SCOPE="user"
 PYTHON_BIN="${PYTHON_BIN:-python3}"
 
 # Prefer the distro Python so --system-site-packages can see modules such as
@@ -30,17 +35,58 @@ fi
 
 usage() {
   cat <<EOF
-Usage: $0 [--no-verify] [--no-prepare-turbo] [--no-seed-default-config] [--no-startup] [--no-ui] [--session-backend auto|x11|wayland]
+Usage: $0 [--user|--system] [--gpu] [--meeting] [--no-verify] [--no-prepare-turbo] [--no-seed-default-config] [--no-startup] [--no-ui] [--session-backend auto|x11|wayland]
 
-Installs dictate into ~/.local/share/dictate, links ~/.local/bin/dictate and
+Default: --user.
+
+--user installs dictate into ~/.local/share/dictate, links ~/.local/bin/dictate and
 ~/.local/bin/dictate-ui-server, seeds the default config on first install,
-creates app launcher/autostart entries, prepares the faster-whisper turbo model,
+creates app launcher/autostart entries, prepares the Parakeet local model,
 and installs the desktop "Quiet Console" UI shell when a build toolchain is
 present (unless disabled). All steps degrade gracefully when prerequisites are
 missing.
+
+--system installs a Linux desktop package into system paths using apt/pkexec or
+sudo. It is intentionally explicit because it requires administrator approval.
+
+--gpu installs Dictate's GPU optional dependencies for local CUDA/ONNX Runtime
+testing on capable machines.
+
+--meeting installs Dictate's pyannote/torch optional dependencies for the
+parakeet-pyannote Meeting lane. DiariZen and Sortformer still require their
+runtime-specific setup before selecting those experimental lanes.
 EOF
 }
 
+install_system_package() {
+  if [ "$(uname -s)" != "Linux" ]; then
+    echo "--system is only supported by this installer on Linux."
+    exit 2
+  fi
+
+  local deb_path="${DICTATE_DEB:-}"
+  if [ -z "$deb_path" ]; then
+    deb_path="$(find "$SCRIPT_DIR/ui-shell/src-tauri/target/release/bundle/deb" -maxdepth 1 -name 'Dictate_*_amd64.deb' 2>/dev/null | sort | tail -n 1 || true)"
+  fi
+  if [ -z "$deb_path" ] || [ ! -f "$deb_path" ]; then
+    echo "No local .deb found. Build one first:"
+    echo "  DICTATE_BUNDLES=deb scripts/build-linux-desktop.sh"
+    echo "Or pass one explicitly:"
+    echo "  DICTATE_DEB=/path/to/Dictate_..._amd64.deb $0 --system"
+    exit 1
+  fi
+
+  echo "Installing system package: $deb_path"
+  if command -v pkexec >/dev/null 2>&1; then
+    pkexec apt-get install -y "$deb_path"
+  elif command -v sudo >/dev/null 2>&1; then
+    sudo apt-get install -y "$deb_path"
+  else
+    echo "Need pkexec or sudo to install a system package."
+    exit 1
+  fi
+}
+
 detect_session_backend() {
   if [ -n "${WAYLAND_DISPLAY:-}" ] || [ "${XDG_SESSION_TYPE:-}" = "wayland" ]; then
     printf 'wayland\n'
@@ -80,6 +126,24 @@ while [ "$#" -gt 0 ]; do
     --no-ui)
       INSTALL_UI=0
       ;;
+    --gpu)
+      INSTALL_GPU=1
+      ;;
+    --no-gpu)
+      INSTALL_GPU=0
+      ;;
+    --meeting)
+      INSTALL_MEETING=1
+      ;;
+    --no-meeting)
+      INSTALL_MEETING=0
+      ;;
+    --user)
+      INSTALL_SCOPE="user"
+      ;;
+    --system)
+      INSTALL_SCOPE="system"
+      ;;
     --session-backend)
       shift
       SESSION_BACKEND="${1:-}"
@@ -99,17 +163,33 @@ while [ "$#" -gt 0 ]; do
   shift
 done
 
+if [ "$INSTALL_SCOPE" = "system" ]; then
+  install_system_package
+  exit 0
+fi
+
 if [ "$SESSION_BACKEND" = "auto" ]; then
   SESSION_BACKEND="$(detect_session_backend)"
 fi
 
-PIP_TARGET="$SCRIPT_DIR"
+EXTRAS=()
 if [ "$SESSION_BACKEND" = "x11" ]; then
-  PIP_TARGET="${SCRIPT_DIR}[x11]"
+  EXTRAS+=("x11")
 elif [ "$SESSION_BACKEND" = "wayland" ]; then
-  PIP_TARGET="${SCRIPT_DIR}[wayland]"
+  EXTRAS+=("wayland")
 elif [ "$SESSION_BACKEND" = "unknown" ]; then
-  PIP_TARGET="${SCRIPT_DIR}[x11,wayland]"
+  EXTRAS+=("x11" "wayland")
+fi
+if [ "$INSTALL_GPU" -eq 1 ]; then
+  EXTRAS+=("gpu")
+fi
+if [ "$INSTALL_MEETING" -eq 1 ]; then
+  EXTRAS+=("meeting")
+fi
+PIP_TARGET="$SCRIPT_DIR"
+if [ "${#EXTRAS[@]}" -gt 0 ]; then
+  extras_csv="$(IFS=,; printf '%s' "${EXTRAS[*]}")"
+  PIP_TARGET="${SCRIPT_DIR}[${extras_csv}]"
 fi
 
 echo "Detected install session backend: $SESSION_BACKEND"
@@ -125,6 +205,34 @@ elif command -v rpm >/dev/null 2>&1 && rpm -q dictate >/dev/null 2>&1; then
   echo "  Use one install method. To remove the package first: sudo dnf remove dictate"
 fi
 
+# Stop any running Dictate engine before we overwrite it, so the new install can
+# claim the single-instance lock cleanly instead of colliding with a stale daemon.
+stop_running_dictate() {
+  # Prefer the installed CLI's own clean stop; it knows the lock location.
+  if command -v dictate >/dev/null 2>&1 && dictate stop --quiet 2>/dev/null; then
+    return 0
+  fi
+  # Fallback (older builds without `dictate stop`): kill via the lock PID file.
+  local lockdir
+  if [ -n "${XDG_RUNTIME_DIR:-}" ]; then
+    lockdir="$XDG_RUNTIME_DIR/dictate-daemon.lockdir"
+  else
+    lockdir="/tmp/dictate-daemon-$(id -u).lockdir"
+  fi
+  local pidfile="$lockdir/pid"
+  [ -f "$pidfile" ] || return 0
+  local pid
+  pid="$(cat "$pidfile" 2>/dev/null || true)"
+  [ -n "$pid" ] || return 0
+  if kill -0 "$pid" 2>/dev/null; then
+    kill "$pid" 2>/dev/null || true
+    for _ in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$pid" 2>/dev/null || break; sleep 0.3; done
+    kill -9 "$pid" 2>/dev/null || true
+  fi
+}
+echo "Stopping any running Dictate engine ..."
+stop_running_dictate
+
 echo "Creating venv at $INSTALL_DIR ..."
 uv venv "$INSTALL_DIR/venv" --python "$PYTHON_BIN" --system-site-packages --quiet
 
@@ -140,11 +248,15 @@ ln -sf "$INSTALL_DIR/venv/bin/dictate-ui-server" "$BIN_DIR/dictate-ui-server"
 echo "Installing icon ..."
 mkdir -p "$ICON_DIR"
 rm -f "$ICON_DIR/dictate-controls.png" "$ICON_DIR/dictate.png"
-install -m 644 "$SCRIPT_DIR/assets/dictate.png" "$ICON_PATH"
+if [ -f "$APP_ICON_SOURCE" ]; then
+  install -m 644 "$APP_ICON_SOURCE" "$ICON_PATH"
+else
+  install -m 644 "$SCRIPT_DIR/assets/dictate.png" "$ICON_PATH"
+fi
 
 echo "Installing desktop entry ..."
 mkdir -p "$DESKTOP_DIR"
-rm -f "$DESKTOP_DIR/dictate-settings.desktop" "$DESKTOP_DIR/dictate.desktop"
+rm -f "$DESKTOP_DIR/dictate-settings.desktop" "$DESKTOP_DIR/Dictate.desktop" "$DESKTOP_DIR/dictate.desktop"
 cat > "$DESKTOP_PATH" <<EOF
 [Desktop Entry]
 Name=Dictate
@@ -155,6 +267,10 @@ Type=Application
 Categories=AudioVideo;Audio;
 Keywords=voice;speech;transcription;dictation;asr;whisper;canary;
 Terminal=false
+# The Tauri shell window reports app_id "dictate-ui-shell" (GTK prgname). Without
+# this, GNOME can't match the running window to this launcher and shows a second,
+# icon-less "dictate-ui-shell" entry with a generic fallback icon.
+StartupWMClass=dictate-ui-shell
 EOF
 
 update-desktop-database "$DESKTOP_DIR" 2>/dev/null || true
@@ -172,6 +288,7 @@ Type=Application
 Categories=AudioVideo;Audio;
 Keywords=voice;speech;transcription;dictation;asr;whisper;canary;
 Terminal=false
+StartupWMClass=dictate-ui-shell
 X-GNOME-Autostart-enabled=true
 EOF
 fi
@@ -206,22 +323,58 @@ install_desktop_ui() {
   npm --prefix "$SCRIPT_DIR/ui" ci >/dev/null 2>&1 \
     || npm --prefix "$SCRIPT_DIR/ui" install >/dev/null 2>&1 \
     || { echo "UI front-end install failed; skipping the optional shell."; print_ui_hint; return 0; }
-  if ! npm --prefix "$SCRIPT_DIR/ui" run build >/dev/null 2>&1; then
-    echo "UI front-end build failed; skipping the optional shell."; print_ui_hint; return 0
-  fi
-  if ! ( cd "$shell_src" && cargo build --release --manifest-path src-tauri/Cargo.toml ); then
+  npm --prefix "$shell_src" ci >/dev/null 2>&1 \
+    || npm --prefix "$shell_src" install >/dev/null 2>&1 \
+    || { echo "UI shell tooling install failed; skipping the optional shell."; print_ui_hint; return 0; }
+  # Tauri validates configured bundle resources even for --no-bundle builds.
+  # Stage a per-user engine wrapper before the build so the resource glob exists,
+  # then install the same wrapper next to the shell binary below.
+  local bundled_engine_dir="$shell_src/src-tauri/engine"
+  mkdir -p "$bundled_engine_dir"
+  cat > "$bundled_engine_dir/dictate-engine" <<WRAP
+#!/bin/sh
+exec "$INSTALL_DIR/venv/bin/dictate" "\$@"
+WRAP
+  chmod 755 "$bundled_engine_dir/dictate-engine"
+  # Build through the Tauri CLI, NOT a raw `cargo build`. The CLI enables the
+  # `custom-protocol` feature that embeds the frontend and serves it over the
+  # app protocol. A plain cargo build omits that feature, so the shell falls
+  # back to loading the dev server (localhost:5173) and shows "Could not connect
+  # to localhost: Connection refused" at runtime. --no-bundle: we only need the
+  # binary here, not a .deb/AppImage. (beforeBuildCommand rebuilds ui/dist.)
+  if ! ( cd "$shell_src" && npm run tauri -- build --no-bundle ); then
     echo "Desktop UI shell build failed; the engine + tray remain fully functional."
     print_ui_hint
     return 0
   fi
   install -m 755 "$shell_src/src-tauri/target/release/dictate-ui-shell" "$target"
   echo "Installed desktop UI shell: $target"
+
+  # Give the shell an absolute-path engine right next to it. The shell's
+  # bundled-engine lookup checks <exe_dir>/engine first — before any system
+  # path (e.g. a leftover /usr/lib/Dictate from an old .deb) and independent of
+  # the minimal PATH a desktop launcher provides. Pointing it at the per-user
+  # venv means one process both dictates and serves, and keeps sys.executable
+  # inside ~/.local so the install reads as "linux-user" and the in-app updater
+  # never needs sudo/pkexec.
+  local engine_dir="$BIN_DIR/engine"
+  mkdir -p "$engine_dir"
+  install -m 755 "$bundled_engine_dir/dictate-engine" "$engine_dir/dictate-engine"
+  echo "Installed per-user engine launcher: $engine_dir/dictate-engine"
 }
 
 if [ "$INSTALL_UI" -eq 1 ]; then
   install_desktop_ui
 fi
 
+if [ -x "$BIN_DIR/dictate-ui-shell" ]; then
+  echo "Pointing launcher entries at the desktop UI shell ..."
+  sed -i "s|^Exec=.*|Exec=$BIN_DIR/dictate-ui-shell|" "$DESKTOP_PATH"
+  if [ "$STARTUP" -eq 1 ] && [ -f "$AUTOSTART_DIR/dictate.desktop" ]; then
+    sed -i "s|^Exec=.*|Exec=$BIN_DIR/dictate-ui-shell|" "$AUTOSTART_DIR/dictate.desktop"
+  fi
+fi
+
 if [ "$SEED_DEFAULT_CONFIG" -eq 1 ]; then
   if [ ! -f "$CONFIG_PATH" ]; then
     if [ ! -f "$DEFAULT_CONFIG_SOURCE" ]; then
@@ -240,6 +393,9 @@ if [ "$SEED_DEFAULT_CONFIG" -eq 1 ]; then
 fi
 
 DICTATE_BIN="$INSTALL_DIR/venv/bin/dictate"
+if [ -n "$PACKAGE_VERSION" ]; then
+  "$DICTATE_BIN" set-installed-package-version "$PACKAGE_VERSION" >/dev/null 2>&1 || true
+fi
 
 run_logged_check() {
   local label="$1"
@@ -266,14 +422,15 @@ run_logged_check() {
 
 if [ "$PREPARE_TURBO" -eq 1 ]; then
   PREPARE_LOG="/tmp/dictate-install-prepare.log"
+  # Keep the legacy flag name for installer compatibility, but prepare the
+  # fresh local default: Parakeet v2.
   run_logged_check \
-    "dictate prepare-model --stt-backend faster-whisper --model turbo --device auto --compute-type int8" \
+    "dictate prepare-model --stt-backend parakeet --device auto --compute-type int8" \
     "$PREPARE_LOG" \
     1800 \
     "$DICTATE_BIN" \
     prepare-model \
-    --stt-backend faster-whisper \
-    --model turbo \
+    --stt-backend parakeet \
     --device auto \
     --compute-type int8
 fi
@@ -283,14 +440,12 @@ if [ "$VERIFY" -eq 1 ]; then
   run_logged_check "dictate --help" "$VERIFY_LOG" 20 "$DICTATE_BIN" --help
   run_logged_check "dictate benchmark --help" "$VERIFY_LOG" 20 "$DICTATE_BIN" benchmark --help
   run_logged_check \
-    "dictate doctor --quick --stt-backend faster-whisper --model turbo" \
+    "dictate doctor --quick" \
     "$VERIFY_LOG" \
     20 \
     "$DICTATE_BIN" \
     doctor \
-    --quick \
-    --stt-backend faster-whisper \
-    --model turbo
+    --quick
 fi
 
 if [ "$STARTUP" -eq 1 ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcforgelabs/dictate",
-  "version": "2026.6.20",
+  "version": "2026.7.4-unstable.3.1",
   "description": "Installer shim for Dictate desktop dictation.",
   "license": "MIT",
   "type": "module",

package/uninstall.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 
 INSTALL_DIR="$HOME/.local/share/dictate"
 BIN_PATH="$HOME/.local/bin/dictate"
+UI_SHELL_BIN_PATH="$HOME/.local/bin/dictate-ui-shell"
 UI_SERVER_BIN_PATH="$HOME/.local/bin/dictate-ui-server"
 DESKTOP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
 AUTOSTART_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
@@ -95,10 +96,12 @@ remove_managed_symlink() {
 stop_source_processes
 
 remove_file "$DESKTOP_DIR/dictate.desktop"
+remove_file "$DESKTOP_DIR/Dictate.desktop"
 remove_file "$DESKTOP_DIR/dictate-settings.desktop"
 remove_file "$AUTOSTART_DIR/dictate.desktop"
 
 remove_managed_symlink "$BIN_PATH" "$INSTALL_DIR/venv/bin/dictate"
+remove_file "$UI_SHELL_BIN_PATH"
 remove_managed_symlink "$UI_SERVER_BIN_PATH" "$INSTALL_DIR/venv/bin/dictate-ui-server"
 
 rm -rf "$INSTALL_DIR/venv" "$INSTALL_DIR/share/icons" "$INSTALL_DIR/logs"

package/update.ps1

@@ -10,10 +10,10 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$DictateVersion = "2026.6.20"
+$DictateVersion = "2026.7.4-unstable.3.1"
 
 if (-not $ArchiveUrl) {
-    $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/refs/tags/v$DictateVersion.zip"
+    $ArchiveUrl = "https://github.com/arcforgelabs/dictate/archive/3f6f050451d0d0e140193534f102c6b5f2b58b19.zip"
 }
 
 if (-not $InstallRoot) {
@@ -105,6 +105,10 @@ try {
     if ($LASTEXITCODE -ne 0) {
         throw "Dictate Windows updater failed with exit code $LASTEXITCODE."
     }
+    $dictateExe = Join-Path $installRootPath ".venv\Scripts\dictate.exe"
+    if (Test-Path $dictateExe) {
+        & $dictateExe set-installed-package-version $DictateVersion | Out-Null
+    }
 } finally {
     if (Test-Path $stagingRoot) {
         Remove-Item -Recurse -Force $stagingRoot

package/update.sh

@@ -8,19 +8,55 @@ DESKTOP_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/applications"
 AUTOSTART_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
 ICON_DIR="$INSTALL_DIR/share/icons"
 AUTOSTART_PATH="$AUTOSTART_DIR/dictate.desktop"
+UPDATE_SCOPE="user"
+
+usage() {
+  cat <<EOF
+Usage: $0 [--user|--system] [install.sh options]
+
+Default: --user.
+
+--user updates the per-user install in ~/.local/share/dictate without sudo.
+--system updates a Linux desktop package in system paths using apt/pkexec or sudo.
+EOF
+}
 
 cleanup_legacy_entries() {
   rm -f "$DESKTOP_DIR/dictate-settings.desktop"
   rm -f "$ICON_DIR/dictate-controls.png" "$ICON_DIR/dictate.png"
 }
 
+args=()
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --user)
+      UPDATE_SCOPE="user"
+      ;;
+    --system)
+      UPDATE_SCOPE="system"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      args+=("$1")
+      ;;
+  esac
+  shift
+done
+
+if [ "$UPDATE_SCOPE" = "system" ]; then
+  "$SCRIPT_DIR/install.sh" --system "${args[@]}"
+  exit 0
+fi
+
 if [ -d "$SCRIPT_DIR/.git" ]; then
   git -C "$SCRIPT_DIR" pull --ff-only
 fi
 
 cleanup_legacy_entries
 
-args=("$@")
 startup_option_seen=0
 for arg in "${args[@]}"; do
   if [ "$arg" = "--no-startup" ]; then