@arcforgelabs/dictate 2026.6.3

package/install.sh

@@ -0,0 +1,303 @@
+#!/usr/bin/env bash
+# Install/update dictate into a standalone venv at ~/.local/share/dictate.
+# Uses --system-site-packages so GTK/gi bindings are available.
+# Re-run this script after pulling changes to update the installation.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+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"
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/dictate"
+CONFIG_PATH="$CONFIG_DIR/config.yaml"
+DEFAULT_CONFIG_SOURCE="$SCRIPT_DIR/config/default-config.yaml"
+VERIFY=1
+PREPARE_TURBO=1
+SEED_DEFAULT_CONFIG=1
+STARTUP=1
+INSTALL_UI=1
+PYTHON_BIN="${PYTHON_BIN:-python3}"
+
+# Prefer the distro Python so --system-site-packages can see modules such as
+# python3-gi from /usr/lib/python3/dist-packages.
+if [ -x /usr/bin/python3 ]; then
+  PYTHON_BIN="/usr/bin/python3"
+fi
+
+usage() {
+  cat <<EOF
+Usage: $0 [--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
+~/.local/bin/dictate-ui-server, seeds the default config on first install,
+creates app launcher/autostart entries, prepares the faster-whisper turbo 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.
+EOF
+}
+
+detect_session_backend() {
+  if [ -n "${WAYLAND_DISPLAY:-}" ] || [ "${XDG_SESSION_TYPE:-}" = "wayland" ]; then
+    printf 'wayland\n'
+    return
+  fi
+  if [ -n "${DISPLAY:-}" ] || [ "${XDG_SESSION_TYPE:-}" = "x11" ]; then
+    printf 'x11\n'
+    return
+  fi
+  if [ -n "${XDG_SESSION_ID:-}" ] && command -v loginctl >/dev/null 2>&1; then
+    local detected
+    detected="$(loginctl show-session "$XDG_SESSION_ID" -p Type --value 2>/dev/null || true)"
+    if [ "$detected" = "wayland" ] || [ "$detected" = "x11" ]; then
+      printf '%s\n' "$detected"
+      return
+    fi
+  fi
+  printf 'unknown\n'
+}
+
+SESSION_BACKEND="auto"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --no-verify)
+      VERIFY=0
+      ;;
+    --no-prepare-turbo)
+      PREPARE_TURBO=0
+      ;;
+    --no-seed-default-config)
+      SEED_DEFAULT_CONFIG=0
+      ;;
+    --no-startup)
+      STARTUP=0
+      ;;
+    --no-ui)
+      INSTALL_UI=0
+      ;;
+    --session-backend)
+      shift
+      SESSION_BACKEND="${1:-}"
+      ;;
+    --session-backend=*)
+      SESSION_BACKEND="${1#*=}"
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+if [ "$SESSION_BACKEND" = "auto" ]; then
+  SESSION_BACKEND="$(detect_session_backend)"
+fi
+
+PIP_TARGET="$SCRIPT_DIR"
+if [ "$SESSION_BACKEND" = "x11" ]; then
+  PIP_TARGET="${SCRIPT_DIR}[x11]"
+elif [ "$SESSION_BACKEND" = "wayland" ]; then
+  PIP_TARGET="${SCRIPT_DIR}[wayland]"
+elif [ "$SESSION_BACKEND" = "unknown" ]; then
+  PIP_TARGET="${SCRIPT_DIR}[x11,wayland]"
+fi
+
+echo "Detected install session backend: $SESSION_BACKEND"
+
+# The packaged build (.deb/.rpm) and this source install both ship a tray/daemon
+# and would fight over the push-to-talk key. Warn rather than silently double up.
+if command -v dpkg-query >/dev/null 2>&1 \
+   && dpkg-query -W -f='${Status}' dictate 2>/dev/null | grep -q "install ok installed"; then
+  echo "WARNING: a packaged Dictate (.deb) is already installed and would conflict."
+  echo "  Use one install method. To remove the package first: sudo apt remove dictate"
+elif command -v rpm >/dev/null 2>&1 && rpm -q dictate >/dev/null 2>&1; then
+  echo "WARNING: a packaged Dictate (.rpm) is already installed and would conflict."
+  echo "  Use one install method. To remove the package first: sudo dnf remove dictate"
+fi
+
+echo "Creating venv at $INSTALL_DIR ..."
+uv venv "$INSTALL_DIR/venv" --python "$PYTHON_BIN" --system-site-packages --quiet
+
+echo "Installing dictate from $PIP_TARGET ..."
+uv pip install "$PIP_TARGET" --python "$INSTALL_DIR/venv/bin/python" --quiet
+
+echo "Linking binaries ..."
+mkdir -p "$BIN_DIR"
+ln -sf "$INSTALL_DIR/venv/bin/dictate" "$BIN_DIR/dictate"
+# Expose the control server so the desktop shell can launch it on PATH.
+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"
+
+echo "Installing desktop entry ..."
+mkdir -p "$DESKTOP_DIR"
+rm -f "$DESKTOP_DIR/dictate-settings.desktop"
+cat > "$DESKTOP_DIR/dictate.desktop" <<EOF
+[Desktop Entry]
+Name=Dictate
+Comment=Dictate into the focused app
+Exec=$HOME/.local/bin/dictate
+Icon=$ICON_PATH
+Type=Application
+Categories=AudioVideo;Audio;
+Keywords=voice;speech;transcription;dictation;asr;whisper;canary;
+Terminal=false
+EOF
+
+update-desktop-database "$DESKTOP_DIR" 2>/dev/null || true
+
+if [ "$STARTUP" -eq 1 ]; then
+  echo "Installing autostart entry ..."
+  mkdir -p "$AUTOSTART_DIR"
+  cat > "$AUTOSTART_DIR/dictate.desktop" <<EOF
+[Desktop Entry]
+Name=Dictate
+Comment=Dictate into the focused app
+Exec=$HOME/.local/bin/dictate
+Icon=$ICON_PATH
+Type=Application
+Categories=AudioVideo;Audio;
+Keywords=voice;speech;transcription;dictation;asr;whisper;canary;
+Terminal=false
+X-GNOME-Autostart-enabled=true
+EOF
+fi
+
+print_ui_hint() {
+  cat <<EOF
+  The Quiet Console desktop UI is optional — the tray app works without it
+  (native dialogs as fallback). To add it later:
+    - download a .deb / AppImage from the GitHub release, or
+    - build it from this checkout: scripts/build-linux-desktop.sh
+  See ui-shell/README.md for details.
+EOF
+}
+
+install_desktop_ui() {
+  local shell_src="$SCRIPT_DIR/ui-shell"
+  local target="$BIN_DIR/dictate-ui-shell"
+
+  if command -v dictate-ui-shell >/dev/null 2>&1; then
+    echo "Desktop UI shell already installed: $(command -v dictate-ui-shell)"
+    return 0
+  fi
+  if [ ! -d "$shell_src" ]; then
+    echo "Desktop UI shell sources not present; skipping the optional UI."
+    print_ui_hint
+    return 0
+  fi
+  if ! command -v cargo >/dev/null 2>&1 || ! command -v npm >/dev/null 2>&1 \
+     || ! pkg-config --exists webkit2gtk-4.1 2>/dev/null; then
+    echo "Desktop UI build toolchain not found (needs cargo, npm, webkit2gtk-4.1-dev)."
+    print_ui_hint
+    return 0
+  fi
+
+  echo "Building the desktop UI shell (this can take a few minutes) ..."
+  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
+    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"
+}
+
+if [ "$INSTALL_UI" -eq 1 ]; then
+  install_desktop_ui
+fi
+
+if [ "$SEED_DEFAULT_CONFIG" -eq 1 ]; then
+  if [ ! -f "$CONFIG_PATH" ]; then
+    if [ ! -f "$DEFAULT_CONFIG_SOURCE" ]; then
+      echo "Default config template not found: $DEFAULT_CONFIG_SOURCE"
+      exit 1
+    fi
+    echo "Seeding default config at $CONFIG_PATH ..."
+    mkdir -p "$CONFIG_DIR"
+    install -m 600 "$DEFAULT_CONFIG_SOURCE" "$CONFIG_PATH"
+    if [ "$SESSION_BACKEND" = "wayland" ]; then
+      sed -i 's/^push_to_talk_combo: .*/push_to_talk_combo: ctrl+space/' "$CONFIG_PATH"
+    fi
+  else
+    echo "Existing config found at $CONFIG_PATH; leaving it unchanged."
+  fi
+fi
+
+DICTATE_BIN="$INSTALL_DIR/venv/bin/dictate"
+
+run_logged_check() {
+  local label="$1"
+  local log_path="$2"
+  local timeout_seconds="$3"
+  shift 3
+  echo "Running: $label ..."
+  if command -v timeout >/dev/null 2>&1; then
+    if ! timeout "${timeout_seconds}s" "$@" >"$log_path" 2>&1; then
+      echo "Command failed: $label"
+      echo "See: $log_path"
+      tail -n 120 "$log_path" || true
+      exit 1
+    fi
+  else
+    if ! "$@" >"$log_path" 2>&1; then
+      echo "Command failed: $label"
+      echo "See: $log_path"
+      tail -n 120 "$log_path" || true
+      exit 1
+    fi
+  fi
+}
+
+if [ "$PREPARE_TURBO" -eq 1 ]; then
+  PREPARE_LOG="/tmp/dictate-install-prepare.log"
+  run_logged_check \
+    "dictate prepare-model --stt-backend faster-whisper --model turbo --device auto --compute-type int8" \
+    "$PREPARE_LOG" \
+    1800 \
+    "$DICTATE_BIN" \
+    prepare-model \
+    --stt-backend faster-whisper \
+    --model turbo \
+    --device auto \
+    --compute-type int8
+fi
+
+if [ "$VERIFY" -eq 1 ]; then
+  VERIFY_LOG="/tmp/dictate-install-verify.log"
+  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" \
+    "$VERIFY_LOG" \
+    20 \
+    "$DICTATE_BIN" \
+    doctor \
+    --quick \
+    --stt-backend faster-whisper \
+    --model turbo
+fi
+
+if [ "$STARTUP" -eq 1 ]; then
+  echo "Done. 'dictate' is now available on your PATH, in the app launcher, and starts when you sign in."
+else
+  echo "Done. 'dictate' is now available on your PATH and in the app launcher."
+fi

package/npm/dictate-lifecycle.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(scriptDir);
+const invokedAs = basename(process.argv[1] || "dictate-install");
+const firstArg = process.argv[2] || "";
+
+let command = "install";
+let passthrough = process.argv.slice(2);
+if (invokedAs.includes("update")) {
+  command = "update";
+} else if (invokedAs.includes("uninstall")) {
+  command = "uninstall";
+} else if (["install", "update", "uninstall", "wizard"].includes(firstArg)) {
+  command = firstArg;
+  passthrough = process.argv.slice(3);
+}
+
+const isWindows = process.platform === "win32";
+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")]],
+      wizard: ["powershell.exe", ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", join(packageRoot, "install.ps1"), "-Wizard"]],
+    }
+  : {
+      install: ["bash", [join(packageRoot, "install.sh")]],
+      update: ["bash", [join(packageRoot, "update.sh")]],
+      uninstall: ["bash", [join(packageRoot, "uninstall.sh")]],
+      wizard: null,
+    };
+
+const selected = scripts[command];
+if (!selected) {
+  console.error(`dictate ${command} is not supported on ${process.platform}`);
+  process.exit(2);
+}
+
+const [exe, args] = selected;
+const result = spawnSync(exe, [...args, ...passthrough], { stdio: "inherit" });
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@arcforgelabs/dictate",
+  "version": "2026.6.3",
+  "description": "Installer shim for Dictate desktop dictation.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/arcforgelabs/dictate#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arcforgelabs/dictate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/arcforgelabs/dictate/issues"
+  },
+  "bin": {
+    "dictate-install": "npm/dictate-lifecycle.mjs",
+    "dictate-update": "npm/dictate-lifecycle.mjs",
+    "dictate-uninstall": "npm/dictate-lifecycle.mjs"
+  },
+  "files": [
+    "install.ps1",
+    "update.ps1",
+    "install-windows.ps1",
+    "install-windows-wizard.ps1",
+    "update-windows.ps1",
+    "uninstall.ps1",
+    "uninstall-windows.ps1",
+    "install.sh",
+    "update.sh",
+    "uninstall.sh",
+    "config/default-config.yaml",
+    "assets/dictate.ico",
+    "assets/dictate.png",
+    "assets/dictate-listening.ico",
+    "assets/dictate-listening.png",
+    "npm/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/uninstall-windows.ps1

@@ -0,0 +1,83 @@
+param(
+    [switch]$Quiet,
+    [switch]$RemoveUserData
+)
+
+$ErrorActionPreference = "Stop"
+
+function Remove-IfExists {
+    param([string]$Path)
+    if (Test-Path $Path) {
+        Remove-Item -Force -Path $Path
+    }
+}
+
+function Stop-DictateProcesses {
+    $currentPid = $PID
+    $matches = Get-CimInstance Win32_Process |
+        Where-Object {
+            $_.ProcessId -ne $currentPid -and (
+                $_.Name -in @("dictate.exe", "dictate-controls.exe") -or
+                $_.CommandLine -like '*dictate.exe* --type-backend pynput*' -or
+                $_.CommandLine -like '*pythonw.exe* -m dictate --type-backend pynput*' -or
+                $_.CommandLine -like '*dictate-daemon.cmd*' -or
+                $_.CommandLine -like '*dictate-controls*'
+            )
+        }
+    foreach ($match in $matches) {
+        Stop-Process -Id $match.ProcessId -Force -ErrorAction SilentlyContinue
+    }
+    Start-Sleep -Milliseconds 500
+}
+
+$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"
+}
+$startupDir = Join-Path $programsDir "Startup"
+
+Remove-IfExists -Path (Join-Path $programsDir "Dictate.lnk")
+Remove-IfExists -Path (Join-Path $programsDir "Dictate Controls.lnk")
+Remove-IfExists -Path (Join-Path $startupDir "Dictate.lnk")
+
+$uninstallKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\Dictate"
+if (Test-Path $uninstallKey) {
+    Remove-Item -Recurse -Force -Path $uninstallKey
+}
+
+Stop-DictateProcesses
+
+$venvDir = Join-Path $PSScriptRoot ".venv"
+if (Test-Path $venvDir) {
+    Remove-Item -Recurse -Force -Path $venvDir
+}
+
+$localAppData = $env:LOCALAPPDATA
+if (-not $localAppData) {
+    $localAppData = Join-Path $HOME "AppData\Local"
+}
+$appData = $env:APPDATA
+if (-not $appData) {
+    $appData = Join-Path $HOME "AppData\Roaming"
+}
+$dataDir = Join-Path $localAppData "dictate"
+$configDir = Join-Path $appData "dictate"
+
+if ($RemoveUserData) {
+    if (Test-Path $dataDir) {
+        Remove-Item -Recurse -Force -Path $dataDir
+    }
+    if (Test-Path $configDir) {
+        Remove-Item -Recurse -Force -Path $configDir
+    }
+}
+
+if (-not $Quiet) {
+    Write-Host "Dictate shortcuts, startup entry, app registration, and runtime venv removed."
+    if ($RemoveUserData) {
+        Write-Host "User config/data removed."
+    } else {
+        Write-Host "User config/data preserved. Re-run with -RemoveUserData to remove it."
+    }
+    Write-Host "Install source files were left in place: $PSScriptRoot"
+}

package/uninstall.ps1

@@ -0,0 +1,51 @@
+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"
+}

package/uninstall.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Remove Dictate launchers/autostart and installed runtime files.
+set -euo pipefail
+
+INSTALL_DIR="$HOME/.local/share/dictate"
+BIN_PATH="$HOME/.local/bin/dictate"
+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"
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/dictate"
+REMOVE_USER_DATA=0
+QUIET=0
+
+usage() {
+  cat <<EOF
+Usage: $0 [--remove-user-data] [--quiet]
+
+Removes Dictate launcher/autostart entries, ~/.local/bin/dictate, and the
+installed runtime venv/icons. User config, logs, history, and downloaded models
+are preserved unless --remove-user-data is passed.
+EOF
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --remove-user-data)
+      REMOVE_USER_DATA=1
+      ;;
+    --quiet)
+      QUIET=1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+say() {
+  if [ "$QUIET" -eq 0 ]; then
+    printf '%s\n' "$1"
+  fi
+}
+
+remove_file() {
+  local path="$1"
+  if [ -e "$path" ] || [ -L "$path" ]; then
+    rm -f "$path"
+    say "Removed $path"
+  fi
+}
+
+remove_dir_if_empty() {
+  local path="$1"
+  if [ -d "$path" ]; then
+    rmdir "$path" 2>/dev/null || true
+  fi
+}
+
+# Stop a running source-install daemon/server before pulling its venv out from
+# under it (only our venv path is matched, never a packaged /usr install).
+stop_source_processes() {
+  local pattern="$INSTALL_DIR/venv"
+  if command -v pkill >/dev/null 2>&1 && pgrep -f "$pattern" >/dev/null 2>&1; then
+    say "Stopping running source-install Dictate processes ..."
+    pkill -TERM -f "$pattern" 2>/dev/null || true
+    for _ in 1 2 3 4 5; do
+      pgrep -f "$pattern" >/dev/null 2>&1 || break
+      sleep 0.3
+    done
+    pkill -KILL -f "$pattern" 2>/dev/null || true
+  fi
+}
+
+remove_managed_symlink() {
+  local link="$1" want="$2"
+  if [ -L "$link" ]; then
+    local target
+    target="$(readlink "$link" || true)"
+    if [ "$target" = "$want" ]; then
+      remove_file "$link"
+    else
+      say "Leaving $link because it points to $target"
+    fi
+  elif [ -e "$link" ]; then
+    say "Leaving $link because it is not a Dictate-managed symlink"
+  fi
+}
+
+stop_source_processes
+
+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_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"
+remove_dir_if_empty "$INSTALL_DIR/share"
+say "Removed installed runtime files from $INSTALL_DIR"
+
+if [ "$REMOVE_USER_DATA" -eq 1 ]; then
+  rm -rf "$CONFIG_DIR" "$INSTALL_DIR"
+  say "Removed user config/data: $CONFIG_DIR and $INSTALL_DIR"
+else
+  say "Preserved user config/data: $CONFIG_DIR and $INSTALL_DIR"
+fi
+
+update-desktop-database "$DESKTOP_DIR" 2>/dev/null || true
+
+say "Dictate uninstall complete."